1guestfs(3) Virtualization Support guestfs(3)
2
6 guestfs - Library for accessing and modifying virtual machine images
7
9 #include <guestfs.h>
10 guestfs_h *g = guestfs_create ();
12 guestfs_add_drive (g, "guest.img");
13 guestfs_launch (g);
14 guestfs_mount (g, "/dev/sda1", "/");
15 guestfs_touch (g, "/hello");
16 guestfs_umount (g, "/");
17 guestfs_shutdown (g);
18 guestfs_close (g);
19 cc prog.c -o prog -lguestfs
21 or:
22 cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
23
25 Libguestfs is a library for accessing and modifying disk images and
26 virtual machines.
27 This manual page documents the C API.
29 If you are looking for an introduction to libguestfs, see the web site:
31 http://libguestfs.org/
32 Each virt tool has its own man page (for a full list, go to "SEE ALSO"
34 at the end of this file).
35 Other libguestfs manual pages:
37 guestfs-faq(1)
39 Frequently Asked Questions (FAQ).
40 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 guestfs-recipes(1)
46 Tips and recipes.
47 guestfs-performance(1)
49 Performance tips and solutions.
50 libguestfs-test-tool(1)
52 guestfs-testing(1)
53 Help testing libguestfs.
54 guestfs-building(1)
56 How to build libguestfs from source.
57 guestfs-hacking(1)
59 Contribute code to libguestfs.
60 guestfs-internals(1)
62 How libguestfs works.
63 guestfs-security(1)
65 Security information, including CVEs affecting libguestfs.
66
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 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 The general structure of all libguestfs-using programs looks like this:
82 guestfs_h *g = guestfs_create ();
84 /* Call guestfs_add_drive additional times if there are
86 * multiple disk images.
87 */
88 guestfs_add_drive (g, "guest.img");
89 /* 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 /* Either: examine what partitions, LVs etc are available: */
97 char **partitions = guestfs_list_partitions (g);
98 char **logvols = guestfs_lvs (g);
99 /* Or: ask libguestfs to find filesystems for you: */
101 char **filesystems = guestfs_list_filesystems (g);
102 /* Or: use inspection (see INSPECTION section below). */
104 /* To access a filesystem in the image, you must mount it. */
106 guestfs_mount (g, "/dev/sda1", "/");
107 /* Now you can perform filesystem actions on the guest
109 * disk image.
110 */
111 guestfs_touch (g, "/hello");
112 /* Synchronize the disk. This is the opposite of guestfs_launch. */
114 guestfs_shutdown (g);
115 /* Close and free the handle 'g'. */
117 guestfs_close (g);
118 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 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 See guestfs-examples(3) for fully worked examples.
132 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 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 guestfs_add_drive_opts (g, filename,
145 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
146 -1);
147 You can add a disk read-only using:
149 guestfs_add_drive_opts (g, filename,
151 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
152 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
153 -1);
154 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 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 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 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 There are slightly different rules when hotplugging disks (in
175 libguestfs ≥ 1.20). See "HOTPLUGGING" below.
176 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 guestfs_mount (g, "/dev/sda1", "/");
185 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 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 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 To mount a filesystem read-only, use "guestfs_mount_ro". There are
204 several other variations of the "guestfs_mount_*" call.
205 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 Specify filenames as full paths, starting with "/" and including the
214 mount point.
215 For example, if you mounted a filesystem at "/" and you want to read
217 the file called "etc/passwd" then you could do:
218 char *data = guestfs_cat (g, "/etc/passwd");
220 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 As another example, to create a top-level directory on that filesystem
226 called "var" you would do:
227 guestfs_mkdir (g, "/var");
229 To create a symlink you could do:
231 guestfs_ln_s (g, "/etc/init.d/portmap",
233 "/etc/rc3.d/S30portmap");
234 Libguestfs will reject attempts to use relative paths and there is no
236 concept of a current working directory.
237 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 File writes are affected by the per-handle umask, set by calling
245 "guestfs_umask" and defaulting to 022. See "UMASK".
246 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 PARTITIONING
252 Libguestfs contains API calls to read, create and modify partition
253 tables on disk images.
254 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 const char *parttype = "mbr";
259 if (disk_is_larger_than_2TB)
260 parttype = "gpt";
261 guestfs_part_disk (g, "/dev/sda", parttype);
262 Obviously this effectively wipes anything that was on that disk image
264 before.
265 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 This author strongly recommends reading the LVM HOWTO, online at
273 http://tldp.org/HOWTO/LVM-HOWTO/.
274 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 "guestfs_read_file" can be used to read files which contain arbitrary 8
281 bit data, since it returns a (pointer, size) pair.
282 "guestfs_download" can be used to download any file, with no limits on
284 content or size.
285 To download multiple files, see "guestfs_tar_out" and
287 "guestfs_tgz_out".
288 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 To upload a single file, use "guestfs_upload". This call has no limits
297 on file content or size.
298 To upload multiple files, see "guestfs_tar_in" and "guestfs_tgz_in".
300 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 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 file to file
317 Use "guestfs_cp" to copy a single file, or "guestfs_cp_a" to copy
318 directories recursively.
319 To copy part of a file (offset and size) use
321 "guestfs_copy_file_to_file".
322 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 Example: duplicate the contents of an LV:
330 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 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 guestfs_copy_device_to_device (g,
341 "/dev/VG/Original", "/dev/VG/Copy",
342 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
343 -1);
344 file on the host to file or device
346 Use "guestfs_upload". See "UPLOADING" above.
347 file or device to file on the host
349 Use "guestfs_download". See "DOWNLOADING" above.
350 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 For example, virt-cat(1) writes its output to stdout by doing:
360 guestfs_download (g, filename, "/dev/stdout");
362 and you can write tar output to a file descriptor "fd" by doing:
364 char devfd[64];
366 snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
367 guestfs_tar_out (g, "/", devfd);
368 LISTING FILES
370 "guestfs_ll" is just designed for humans to read (mainly when using the
371 guestfish(1)-equivalent command "ll").
372 "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 "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 "guestfs_find" and "guestfs_find0" can be used to recursively list
381 files.
382 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 There are many limitations to this:
389 · The kernel version that the command runs under will be different
391 from what it expects.
392 · If the command needs to communicate with daemons, then most likely
394 they won't be running.
395 · The command will be running in limited memory.
397 · The network may not be available unless you enable it (see
399 "guestfs_set_network").
400 · Only supports Linux guests (not Windows, BSD, etc).
402 · Architecture limitations (eg. won’t work for a PPC guest on an X86
404 host).
405 · For SELinux guests, you may need to relabel the guest after
407 creating new files. See "SELINUX" below.
408 · 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 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 The two main API calls to run commands are "guestfs_command" and
425 "guestfs_sh" (there are also variations).
426 The difference is that "guestfs_sh" runs commands using the shell, so
428 any shell globs, redirections, etc will work.
429 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 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 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 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 Consult the journal documentation here: sd-journal(3),
449 sd_journal_open(3).
450 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 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 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 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 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 The default umask is 022, so files are created with modes such as 0644
478 and directories with 0755.
479 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 For more information about umask, see umask(2).
485 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 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 You can locate a filesystem by its label or UUID using
496 "guestfs_findfs_label" or "guestfs_findfs_uuid".
497 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 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 ENCRYPTED DISKS
509 Libguestfs allows you to access Linux guests which have been encrypted
510 using whole disk encryption that conforms to the Linux Unified Key
511 Setup (LUKS) standard. This includes nearly all whole disk encryption
512 systems used by modern Linux guests. Windows BitLocker is also
513 supported.
514 Use "guestfs_vfs_type" to identify encrypted block devices. For LUKS
516 it returns the string "crypto_LUKS". For Windows BitLocker it returns
517 "BitLocker".
518 Then open these devices by calling "guestfs_cryptsetup_open".
520 Obviously you will require the passphrase!
521 Opening an encrypted device creates a new device mapper device called
523 /dev/mapper/mapname (where "mapname" is the string you supply to
524 "guestfs_cryptsetup_open"). Reads and writes to this mapper device are
525 decrypted from and encrypted to the underlying block device
526 respectively.
527 LVM volume groups on the device can be made visible by calling
529 "guestfs_vgscan" followed by "guestfs_vg_activate_all". The logical
530 volume(s) can now be mounted in the usual way.
531 Use the reverse process to close an encrypted device. Unmount any
533 logical volumes on it, deactivate the volume groups by calling
534 "guestfs_vg_activate (g, 0, ["/dev/VG"])". Then close the mapper
535 device by calling "guestfs_cryptsetup_close" on the /dev/mapper/mapname
536 device (not the underlying encrypted block device).
537 MOUNT LOCAL
539 In libguestfs ≥ 1.18, it is possible to mount the libguestfs filesystem
540 on a local directory and access it using ordinary POSIX calls and
541 programs.
542 Availability of this is subject to a number of restrictions: it
544 requires FUSE (the Filesystem in USErspace), and libfuse must also have
545 been available when libguestfs was compiled. FUSE may require that a
546 kernel module is loaded, and it may be necessary to add the current
547 user to a special "fuse" group. See the documentation for your
548 distribution and http://fuse.sf.net for further information.
549 The call to mount the libguestfs filesystem on a local directory is
551 "guestfs_mount_local" (q.v.) followed by "guestfs_mount_local_run".
552 The latter does not return until you unmount the filesystem. The
553 reason is that the call enters the FUSE main loop and processes kernel
554 requests, turning them into libguestfs calls. An alternative design
555 would have been to create a background thread to do this, but
556 libguestfs doesn't require pthreads. This way is also more flexible:
557 for example the user can create another thread for
558 "guestfs_mount_local_run".
559 "guestfs_mount_local" needs a certain amount of time to set up the
561 mountpoint. The mountpoint is not ready to use until the call returns.
562 At this point, accesses to the filesystem will block until the main
563 loop is entered (ie. "guestfs_mount_local_run"). So if you need to
564 start another process to access the filesystem, put the fork between
565 "guestfs_mount_local" and "guestfs_mount_local_run".
566 MOUNT LOCAL COMPATIBILITY
568 Since local mounting was only added in libguestfs 1.18, and may not be
570 available even in these builds, you should consider writing code so
571 that it doesn't depend on this feature, and can fall back to using
572 libguestfs file system calls.
573 If libguestfs was compiled without support for "guestfs_mount_local"
575 then calling it will return an error with errno set to "ENOTSUP" (see
576 "guestfs_last_errno").
577 MOUNT LOCAL PERFORMANCE
579 Libguestfs on top of FUSE performs quite poorly. For best performance
581 do not use it. Use ordinary libguestfs filesystem calls, upload,
582 download etc. instead.
583 HOTPLUGGING
585 In libguestfs ≥ 1.20, you may add drives and remove after calling
586 "guestfs_launch". There are some restrictions, see below. This is
587 called hotplugging.
588 Only a subset of the backends support hotplugging (currently only the
590 libvirt backend has support). It also requires that you use libvirt ≥
591 0.10.3 and qemu ≥ 1.2.
592 To hot-add a disk, simply call "guestfs_add_drive_opts" after
594 "guestfs_launch". It is mandatory to specify the "label" parameter so
595 that the newly added disk has a predictable name. For example:
596 if (guestfs_launch (g) == -1)
598 error ("launch failed");
599 if (guestfs_add_drive_opts (g, filename,
601 GUESTFS_ADD_DRIVE_OPTS_LABEL, "newdisk",
602 -1) == -1)
603 error ("hot-add of disk failed");
604 if (guestfs_part_disk ("/dev/disk/guestfs/newdisk", "mbr") == -1)
606 error ("partitioning of hot-added disk failed");
607 To hot-remove a disk, call "guestfs_remove_drive". You can call this
609 before or after "guestfs_launch". You can only remove disks that were
610 previously added with a label.
611 Backends that support hotplugging do not require that you add ≥ 1 disk
613 before calling launch. When hotplugging is supported you don't need to
614 add any disks.
615 REMOTE STORAGE
617 CEPH
618 Libguestfs can access Ceph (librbd/RBD) disks.
620 To do this, set the optional "protocol" and "server" parameters of
622 "guestfs_add_drive_opts" like this:
623 char **servers = { "ceph1.example.org:3000", /* ... */, NULL };
625 guestfs_add_drive_opts (g, "pool/image",
626 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
627 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "rbd",
628 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
629 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "rbduser",
630 GUESTFS_ADD_DRIVE_OPTS_SECRET, "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
631 -1);
632 "servers" (the "server" parameter) is a list of one or more Ceph
634 servers. The server string is documented in "guestfs_add_drive_opts".
635 The "username" and "secret" parameters are also optional, and if not
636 given, then no authentication will be used.
637 FTP, HTTP AND TFTP
639 Libguestfs can access remote disks over FTP, FTPS, HTTP, HTTPS or TFTP
641 protocols.
642 To do this, set the optional "protocol" and "server" parameters of
644 "guestfs_add_drive_opts" like this:
645 char **servers = { "www.example.org", NULL };
647 guestfs_add_drive_opts (g, "/disk.img",
648 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
649 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "http",
650 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
651 -1);
652 The "protocol" can be one of "ftp", "ftps", "http", "https" or "tftp".
654 "servers" (the "server" parameter) is a list which must have a single
656 element. The single element is a string defining the web, FTP or TFTP
657 server. The format of this string is documented in
658 "guestfs_add_drive_opts".
659 GLUSTER
661 Libguestfs can access Gluster disks.
663 To do this, set the optional "protocol" and "server" parameters of
665 "guestfs_add_drive_opts" like this:
666 char **servers = { "gluster.example.org:24007", NULL };
668 guestfs_add_drive_opts (g, "volname/image",
669 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
670 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "gluster",
671 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
672 -1);
673 "servers" (the "server" parameter) is a list which must have a single
675 element. The single element is a string defining the Gluster server.
676 The format of this string is documented in "guestfs_add_drive_opts".
677 Note that gluster usually requires the client process (ie. libguestfs)
679 to run as root and will give unfathomable errors if it is not (eg. "No
680 data available").
681 ISCSI
683 Libguestfs can access iSCSI disks remotely.
685 To do this, set the optional "protocol" and "server" parameters like
687 this:
688 char **server = { "iscsi.example.org:3000", NULL };
690 guestfs_add_drive_opts (g, "target-iqn-name/lun",
691 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
692 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "iscsi",
693 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
694 -1);
695 The "server" parameter is a list which must have a single element. The
697 single element is a string defining the iSCSI server. The format of
698 this string is documented in "guestfs_add_drive_opts".
699 NETWORK BLOCK DEVICE
701 Libguestfs can access Network Block Device (NBD) disks remotely.
703 To do this, set the optional "protocol" and "server" parameters of
705 "guestfs_add_drive_opts" like this:
706 char **server = { "nbd.example.org:3000", NULL };
708 guestfs_add_drive_opts (g, "" /* export name - see below */,
709 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
710 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
711 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
712 -1);
713 Notes:
715 · "server" is in fact a list of servers. For NBD you must always
717 supply a list with a single element. (Other remote protocols
718 require zero or more than one server, hence the requirement for
719 this parameter to be a list).
720 · The "server" string is documented in "guestfs_add_drive_opts". To
722 connect to a local qemu-nbd instance over a Unix domain socket, use
723 "unix:/path/to/socket".
724 · The "filename" parameter is the NBD export name. Use an empty
726 string to mean the default export. Many NBD servers, including
727 qemu-nbd, do not support export names.
728 · If using qemu-nbd as your server, you should always specify the
730 "-t" option. The reason is that libguestfs may open several
731 connections to the server.
732 · The libvirt backend requires that you set the "format" parameter of
734 "guestfs_add_drive_opts" accurately when you use writable NBD
735 disks.
736 · The libvirt backend has a bug that stops Unix domain socket
738 connections from working:
739 https://bugzilla.redhat.com/show_bug.cgi?id=922888
740 · The direct backend does not support readonly connections because of
742 a bug in qemu: https://bugs.launchpad.net/qemu/+bug/1155677
743 SHEEPDOG
745 Libguestfs can access Sheepdog disks.
747 To do this, set the optional "protocol" and "server" parameters of
749 "guestfs_add_drive_opts" like this:
750 char **servers = { /* optional servers ... */ NULL };
752 guestfs_add_drive_opts (g, "volume",
753 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
754 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "sheepdog",
755 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
756 -1);
757 The optional list of "servers" may be zero or more server addresses
759 ("hostname:port"). The format of the server strings is documented in
760 "guestfs_add_drive_opts".
761 SSH
763 Libguestfs can access disks over a Secure Shell (SSH) connection.
765 To do this, set the "protocol" and "server" and (optionally) "username"
767 parameters of "guestfs_add_drive_opts" like this:
768 char **server = { "remote.example.com", NULL };
770 guestfs_add_drive_opts (g, "/path/to/disk.img",
771 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
772 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "ssh",
773 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
774 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "remoteuser",
775 -1);
776 The format of the server string is documented in
778 "guestfs_add_drive_opts".
779 INSPECTION
781 Libguestfs has APIs for inspecting an unknown disk image to find out if
782 it contains operating systems, an install CD or a live CD.
783 Add all disks belonging to the unknown virtual machine and call
785 "guestfs_launch" in the usual way.
786 Then call "guestfs_inspect_os". This function uses other libguestfs
788 calls and certain heuristics, and returns a list of operating systems
789 that were found. An empty list means none were found. A single
790 element is the root filesystem of the operating system. For dual- or
791 multi-boot guests, multiple roots can be returned, each one
792 corresponding to a separate operating system. (Multi-boot virtual
793 machines are extremely rare in the world of virtualization, but since
794 this scenario can happen, we have built libguestfs to deal with it.)
795 For each root, you can then call various "guestfs_inspect_get_*"
797 functions to get additional details about that operating system. For
798 example, call "guestfs_inspect_get_type" to return the string "windows"
799 or "linux" for Windows and Linux-based operating systems respectively.
800 Un*x-like and Linux-based operating systems usually consist of several
802 filesystems which are mounted at boot time (for example, a separate
803 boot partition mounted on /boot). The inspection rules are able to
804 detect how filesystems correspond to mount points. Call
805 "guestfs_inspect_get_mountpoints" to get this mapping. It might return
806 a hash table like this example:
807 /boot => /dev/sda1
809 / => /dev/vg_guest/lv_root
810 /usr => /dev/vg_guest/lv_usr
811 The caller can then make calls to "guestfs_mount" to mount the
813 filesystems as suggested.
814 Be careful to mount filesystems in the right order (eg. / before /usr).
816 Sorting the keys of the hash by length, shortest first, should work.
817 Inspection currently only works for some common operating systems.
819 Contributors are welcome to send patches for other operating systems
820 that we currently cannot detect.
821 Encrypted disks must be opened before inspection. See "ENCRYPTED
823 DISKS" for more details. The "guestfs_inspect_os" function just
824 ignores any encrypted devices.
825 A note on the implementation: The call "guestfs_inspect_os" performs
827 inspection and caches the results in the guest handle. Subsequent
828 calls to "guestfs_inspect_get_*" return this cached information, but do
829 not re-read the disks. If you change the content of the guest disks,
830 you can redo inspection by calling "guestfs_inspect_os" again.
831 ("guestfs_inspect_list_applications2" works a little differently from
832 the other calls and does read the disks. See documentation for that
833 function for details).
834 INSPECTING INSTALL DISKS
836 Libguestfs (since 1.9.4) can detect some install disks, install CDs,
838 live CDs and more.
839 Further information is available about the operating system that can be
841 installed using the regular inspection APIs like
842 "guestfs_inspect_get_product_name", "guestfs_inspect_get_major_version"
843 etc.
844 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
846 Libguestfs can mount NTFS partitions. It does this using the
847 http://www.ntfs-3g.org/ driver.
848 DRIVE LETTERS AND PATHS
850 DOS and Windows still use drive letters, and the filesystems are always
852 treated as case insensitive by Windows itself, and therefore you might
853 find a Windows configuration file referring to a path like
854 "c:\windows\system32". When the filesystem is mounted in libguestfs,
855 that directory might be referred to as /WINDOWS/System32.
856 Drive letter mappings can be found using inspection (see "INSPECTION"
858 and "guestfs_inspect_get_drive_mappings")
859 Dealing with separator characters (backslash vs forward slash) is
861 outside the scope of libguestfs, but usually a simple character
862 replacement will work.
863 To resolve the case insensitivity of paths, call
865 "guestfs_case_sensitive_path".
866 LONG FILENAMES ON NTFS
868 NTFS supports filenames up to 255 characters long. "Character" means a
870 2 byte UTF-16 codepoint which can encode the most common Unicode
871 codepoints.
872 Most Linux filesystems support filenames up to 255 bytes. This means
874 you may get an error:
875 File name too long
877 when you copy a file from NTFS to a Linux filesystem if the name, when
879 reencoded as UTF-8, would exceed 255 bytes in length.
880 This will most often happen when using non-ASCII names that are longer
882 than ~127 characters (eg. Greek, Cyrillic) or longer than ~85
883 characters (Asian languages).
884 A workaround is not to try to store such long filenames on Linux native
886 filesystems. Since the tar(1) format can store unlimited length
887 filenames, keep the files in a tarball.
888 ACCESSING THE WINDOWS REGISTRY
890 Libguestfs also provides some help for decoding Windows Registry "hive"
892 files, through a separate C library called hivex(3).
893 Before libguestfs 1.19.35 you had to download the hive file, operate on
895 it locally using hivex, and upload it again. Since this version, we
896 have included the major hivex APIs directly in the libguestfs API (see
897 "guestfs_hivex_open"). This means that if you have opened a Windows
898 guest, you can read and write the registry directly.
899 See also virt-win-reg(1).
901 SYMLINKS ON NTFS-3G FILESYSTEMS
903 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
905 provide something which looks like a Linux symlink. The way it tries
906 to do the rewriting is described here:
907 http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
909 The essential problem is that ntfs-3g simply does not have enough
911 information to do a correct job. NTFS links can contain drive letters
912 and references to external device GUIDs that ntfs-3g has no way of
913 resolving. It is almost certainly the case that libguestfs callers
914 should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
915 NTFS volumes).
916 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
918 "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
919 attribute, and read the raw reparse data from that (you can find the
920 format documented in various places around the web).
921 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
923 There are other useful extended attributes that can be read from
925 ntfs-3g filesystems (using "guestfs_getxattr"). See:
926 http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
928 WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP
930 Windows guests which have been hibernated (instead of fully shut down)
932 cannot be mounted. This is a limitation of ntfs-3g. You will see an
933 error like this:
934 The disk contains an unclean file system (0, 0).
936 Metadata kept in Windows cache, refused to mount.
937 Failed to mount '/dev/sda2': Operation not permitted
938 The NTFS partition is in an unsafe state. Please resume
939 and shutdown Windows fully (no hibernation or fast
940 restarting), or mount the volume read-only with the
941 'ro' mount option.
942 In Windows 8, the shutdown button does not shut down the guest at all.
944 Instead it usually hibernates the guest. This is known as "fast
945 startup".
946 Some suggested workarounds are:
948 · Mount read-only (eg. "guestfs_mount_ro").
950 · On Windows 8, turn off fast startup. It is in the Control Panel →
952 Power Options → Choose what the power buttons do → Change settings
953 that are currently unavailable → Turn on fast startup.
954 · On Windows 7 and earlier, shut the guest off properly instead of
956 hibernating it.
957 RESIZE2FS ERRORS
959 The "guestfs_resize2fs", "guestfs_resize2fs_size" and
960 "guestfs_resize2fs_M" calls are used to resize ext2/3/4 filesystems.
961 The underlying program (resize2fs(8)) requires that the filesystem is
963 clean and recently fsck'd before you can resize it. Also, if the
964 resize operation fails for some reason, then you had to call fsck the
965 filesystem again to fix it.
966 In libguestfs "lt" 1.17.14, you usually had to call "guestfs_e2fsck_f"
968 before the resize. However, in "ge" 1.17.14, e2fsck(8) is called
969 automatically before the resize, so you no longer need to do this.
970 The resize2fs(8) program can still fail, in which case it prints an
972 error message similar to:
973 Please run 'e2fsck -fy <device>' to fix the filesystem
975 after the aborted resize operation.
976 You can do this by calling "guestfs_e2fsck" with the "forceall" option.
978 However in the context of disk images, it is usually better to avoid
979 this situation, eg. by rolling back to an earlier snapshot, or by
980 copying and resizing and on failure going back to the original.
981 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
983 Although we don’t want to discourage you from using the C API, we will
984 mention here that the same API is also available in other languages.
985 The API is broadly identical in all supported languages. This means
987 that the C call "guestfs_add_drive_ro(g,file)" is
988 "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
989 and "g#add_drive_ro file" in OCaml. In other words, a straightforward,
990 predictable isomorphism between each language.
991 Error messages are automatically transformed into exceptions if the
993 language supports it.
994 We don’t try to "object orientify" parts of the API in OO languages,
996 although contributors are welcome to write higher level APIs above what
997 we provide in their favourite languages if they wish.
998 C++ You can use the guestfs.h header file from C++ programs. The C++
1000 API is identical to the C API. C++ classes and exceptions are not
1001 used.
1002 C# The C# bindings are highly experimental. Please read the warnings
1004 at the top of csharp/Libguestfs.cs.
1005 Erlang
1007 See guestfs-erlang(3).
1008 GObject
1010 Experimental GObject bindings (with GObject Introspection support)
1011 are available.
1012 See guestfs-gobject(3).
1014 Go See guestfs-golang(3).
1016 Haskell
1018 This language binding is working but incomplete:
1019 · Functions with optional arguments are not bound. Implementing
1021 optional arguments in Haskell seems to be very complex.
1022 · Events are not bound.
1024 · Functions with the following return types are not bound:
1026 · Any function returning a struct.
1028 · Any function returning a list of structs.
1030 · A few functions that return fixed length buffers
1032 (specifically ones declared "RBufferOut" in the generator).
1033 · A tiny number of obscure functions that return constant
1035 strings (specifically ones declared "RConstOptString" in
1036 the generator).
1037 Java
1039 Full documentation is contained in the Javadoc which is distributed
1040 with libguestfs. For examples, see guestfs-java(3).
1041 Lua See guestfs-lua(3).
1043 OCaml
1045 See guestfs-ocaml(3).
1046 Perl
1048 See guestfs-perl(3) and Sys::Guestfs(3).
1049 PHP For documentation see "README-PHP" supplied with libguestfs sources
1051 or in the php-libguestfs package for your distribution.
1052 The PHP binding only works correctly on 64 bit machines.
1054 Python
1056 See guestfs-python(3).
1057 Ruby
1059 See guestfs-ruby(3).
1060 For JRuby, use the Java bindings.
1062 shell scripts
1064 See guestfish(1).
1065 LIBGUESTFS GOTCHAS
1067 http://en.wikipedia.org/wiki/Gotcha_(programming): "A feature of a
1068 system [...] that works in the way it is documented but is
1069 counterintuitive and almost invites mistakes."
1070 Since we developed libguestfs and the associated tools, there are
1072 several things we would have designed differently, but are now stuck
1073 with for backwards compatibility or other reasons. If there is ever a
1074 libguestfs 2.0 release, you can expect these to change. Beware of
1075 them.
1076 Read-only should be the default.
1078 In guestfish(3), --ro should be the default, and you should have to
1079 specify --rw if you want to make changes to the image.
1080 This would reduce the potential to corrupt live VM images.
1082 Note that many filesystems change the disk when you just mount and
1084 unmount, even if you didn't perform any writes. You need to use
1085 "guestfs_add_drive_ro" to guarantee that the disk is not changed.
1086 guestfish command line is hard to use.
1088 guestfish disk.img doesn't do what people expect (open disk.img for
1089 examination). It tries to run a guestfish command disk.img which
1090 doesn't exist, so it fails. In earlier versions of guestfish the
1091 error message was also unintuitive, but we have corrected this
1092 since. Like the Bourne shell, we should have used "guestfish -c
1093 command" to run commands.
1094 guestfish megabyte modifiers don’t work right on all commands
1096 In recent guestfish you can use "1M" to mean 1 megabyte (and
1097 similarly for other modifiers). What guestfish actually does is to
1098 multiply the number part by the modifier part and pass the result
1099 to the C API. However this doesn't work for a few APIs which
1100 aren't expecting bytes, but are already expecting some other unit
1101 (eg. megabytes).
1102 The most common is "guestfs_lvcreate". The guestfish command:
1104 lvcreate LV VG 100M
1106 does not do what you might expect. Instead because
1108 "guestfs_lvcreate" is already expecting megabytes, this tries to
1109 create a 100 terabyte (100 megabytes * megabytes) logical volume.
1110 The error message you get from this is also a little obscure.
1111 This could be fixed in the generator by specially marking
1113 parameters and return values which take bytes or other units.
1114 Ambiguity between devices and paths
1116 There is a subtle ambiguity in the API between a device name (eg.
1117 /dev/sdb2) and a similar pathname. A file might just happen to be
1118 called "sdb2" in the directory /dev (consider some non-Unix VM
1119 image).
1120 In the current API we usually resolve this ambiguity by having two
1122 separate calls, for example "guestfs_checksum" and
1123 "guestfs_checksum_device". Some API calls are ambiguous and
1124 (incorrectly) resolve the problem by detecting if the path supplied
1125 begins with /dev/.
1126 To avoid both the ambiguity and the need to duplicate some calls,
1128 we could make paths/devices into structured names. One way to do
1129 this would be to use a notation like grub ("hd(0,0)"), although
1130 nobody really likes this aspect of grub. Another way would be to
1131 use a structured type, equivalent to this OCaml type:
1132 type path = Path of string | Device of int | Partition of int * int
1134 which would allow you to pass arguments like:
1136 Path "/foo/bar"
1138 Device 1 (* /dev/sdb, or perhaps /dev/sda *)
1139 Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
1140 Path "/dev/sdb2" (* not a device *)
1141 As you can see there are still problems to resolve even with this
1143 representation. Also consider how it might work in guestfish.
1144 KEYS AND PASSPHRASES
1146 Certain libguestfs calls take a parameter that contains sensitive key
1147 material, passed in as a C string.
1148 In the future we would hope to change the libguestfs implementation so
1150 that keys are mlock(2)-ed into physical RAM, and thus can never end up
1151 in swap. However this is not done at the moment, because of the
1152 complexity of such an implementation.
1153 Therefore you should be aware that any key parameter you pass to
1155 libguestfs might end up being written out to the swap partition. If
1156 this is a concern, scrub the swap partition or don't use libguestfs on
1157 encrypted devices.
1158 MULTIPLE HANDLES AND MULTIPLE THREADS
1160 All high-level libguestfs actions are synchronous. If you want to use
1161 libguestfs asynchronously then you must create a thread.
1162 Threads in libguestfs ≥ 1.38
1164 In libguestfs ≥ 1.38, each handle ("guestfs_h") contains a lock which
1166 is acquired automatically when you call a libguestfs function. The
1167 practical effect of this is you can call libguestfs functions with the
1168 same handle from multiple threads without needing to do any locking.
1169 Also in libguestfs ≥ 1.38, the last error on the handle
1171 ("guestfs_last_error", "guestfs_last_errno") is stored in thread-local
1172 storage, so it is safe to write code like:
1173 if (guestfs_add_drive_ro (g, drive) == -1)
1175 fprintf (stderr, "error was: %s\n", guestfs_last_error (g));
1176 even when other threads may be concurrently using the same handle "g".
1178 Threads in libguestfs < 1.38
1180 In libguestfs < 1.38, you must use the handle only from a single
1182 thread. Either use the handle exclusively from one thread, or provide
1183 your own mutex so that two threads cannot issue calls on the same
1184 handle at the same time. Even apparently innocent functions like
1185 "guestfs_get_trace" are not safe to be called from multiple threads
1186 without a mutex in libguestfs < 1.38.
1187 Use "guestfs_set_identifier" to make it simpler to identify threads in
1189 trace output.
1190 PATH
1192 Libguestfs needs a supermin appliance, which it finds by looking along
1193 an internal path.
1194 By default it looks for these in the directory "$libdir/guestfs" (eg.
1196 /usr/local/lib/guestfs or /usr/lib64/guestfs).
1197 Use "guestfs_set_path" or set the environment variable
1199 "LIBGUESTFS_PATH" to change the directories that libguestfs will search
1200 in. The value is a colon-separated list of paths. The current
1201 directory is not searched unless the path contains an empty element or
1202 ".". For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
1203 current directory and then /usr/lib/guestfs.
1204 QEMU WRAPPERS
1206 If you want to compile your own qemu, run qemu from a non-standard
1207 location, or pass extra arguments to qemu, then you can write a shell-
1208 script wrapper around qemu.
1209 There is one important rule to remember: you must "exec qemu" as the
1211 last command in the shell script (so that qemu replaces the shell and
1212 becomes the direct child of the libguestfs-using program). If you
1213 don't do this, then the qemu process won't be cleaned up correctly.
1214 Here is an example of a wrapper, where I have built my own copy of qemu
1216 from source:
1217 #!/bin/sh -
1219 qemudir=/home/rjones/d/qemu
1220 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1221 Save this script as /tmp/qemu.wrapper (or wherever), "chmod +x", and
1223 then use it by setting the LIBGUESTFS_HV environment variable. For
1224 example:
1225 LIBGUESTFS_HV=/tmp/qemu.wrapper guestfish
1227 Note that libguestfs also calls qemu with the -help and -version
1229 options in order to determine features.
1230 Wrappers can also be used to edit the options passed to qemu. In the
1232 following example, the "-machine ..." option ("-machine" and the
1233 following argument) are removed from the command line and replaced with
1234 "-machine pc,accel=tcg". The while loop iterates over the options
1235 until it finds the right one to remove, putting the remaining options
1236 into the "args" array.
1237 #!/bin/bash -
1239 i=0
1241 while [ $# -gt 0 ]; do
1242 case "$1" in
1243 -machine)
1244 shift 2;;
1245 *)
1246 args[i]="$1"
1247 (( i++ ))
1248 shift ;;
1249 esac
1250 done
1251 exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
1253 BACKEND
1255 The backend (previously known as the "attach method") controls how
1256 libguestfs creates and/or connects to the backend daemon, eg. by
1257 starting qemu directly, or using libvirt to manage an appliance,
1258 running User-Mode Linux, or connecting to an already running daemon.
1259 You can set the backend by calling "guestfs_set_backend", or by setting
1261 the environment variable "LIBGUESTFS_BACKEND".
1262 Possible backends are described below:
1264 "direct"
1266 "appliance"
1267 Run qemu directly to launch an appliance.
1268 "direct" and "appliance" are synonyms.
1270 This is the ordinary method and normally the default, but see the
1272 note below.
1273 "libvirt"
1275 "libvirt:null"
1276 "libvirt:URI"
1277 Use libvirt to launch and manage the appliance.
1278 "libvirt" causes libguestfs to choose a suitable URI for creating
1280 session guests. If using the libvirt backend, you almost always
1281 should use this.
1282 "libvirt:null" causes libguestfs to use the "NULL" connection URI,
1284 which causes libvirt to try to guess what the user meant. You
1285 probably don't want to use this.
1286 "libvirt:URI" uses URI as the libvirt connection URI (see
1288 http://libvirt.org/uri.html). The typical libvirt backend with a
1289 URI would be "libvirt:qemu:///session"
1290 The libvirt backend supports more features, including hotplugging
1292 (see "HOTPLUGGING") and sVirt.
1293 "uml"
1295 Run the User-Mode Linux kernel. The location of the kernel is set
1296 using $LIBGUESTFS_HV or using the "guestfs_set_qemu" API (note that
1297 qemu is not involved, we just reuse the same variable in the handle
1298 for convenience).
1299 User-Mode Linux can be much faster, simpler and more lightweight
1301 than using a full-blown virtual machine, but it also has some
1302 shortcomings. See "USER-MODE LINUX BACKEND" below.
1303 "unix:path"
1305 Connect to the Unix domain socket path.
1306 This method lets you connect to an existing daemon or (using
1308 virtio-serial) to a live guest. For more information, see
1309 "ATTACHING TO RUNNING DAEMONS".
1310 "direct" is usually the default backend. However since libguestfs ≥
1312 1.19.24, libguestfs can be built with a different default by doing:
1313 ./configure --with-default-backend=...
1315 To find out if libguestfs was compiled with a different default
1317 backend, do:
1318 unset LIBGUESTFS_BACKEND
1320 guestfish get-backend
1321 BACKEND SETTINGS
1323 Each backend can be configured by passing a list of strings. You can
1324 either call "guestfs_set_backend_settings" with a list of strings, or
1325 set the "LIBGUESTFS_BACKEND_SETTINGS" environment variable to a colon-
1326 separated list of strings (before creating the handle).
1327 force_tcg
1329 Using:
1331 export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
1333 will force the direct and libvirt backends to use TCG (software
1335 emulation) instead of KVM (hardware accelerated virtualization).
1336 gdb
1338 The direct backend supports:
1340 export LIBGUESTFS_BACKEND_SETTINGS=gdb
1342 When this is set, qemu will not start running the appliance
1344 immediately. It will wait for you to connect to it using gdb:
1345 $ gdb
1347 (gdb) symbol-file /path/to/vmlinux
1348 (gdb) target remote tcp::1234
1349 (gdb) cont
1350 You can then debug the appliance kernel, which is useful to debug boot
1352 failures (especially ones where there are no debug messages printed -
1353 tip: look in the kernel "log_buf").
1354 On Fedora, install "kernel-debuginfo" for the "vmlinux" file
1356 (containing symbols). Make sure the symbols precisely match the kernel
1357 being used.
1358 ATTACHING TO RUNNING DAEMONS
1360 Note [4m(1): This is highly experimental and has a tendency to eat babies.
1361 Use with caution.
1362 Note [4m(2): This section explains how to attach to a running daemon from
1364 a low level perspective. For most users, simply using virt tools such
1365 as guestfish(1) with the --live option will "just work".
1366 Using guestfs_set_backend
1368 By calling "guestfs_set_backend" you can change how the library
1370 connects to the "guestfsd" daemon in "guestfs_launch" (read
1371 "ARCHITECTURE" in guestfs-internals(1) for some background).
1372 The normal backend is "direct", where a small appliance is created
1374 containing the daemon, and then the library connects to this.
1375 "libvirt" or "libvirt:URI" are alternatives that use libvirt to start
1376 the appliance.
1377 Setting the backend to "unix:path" (where path is the path of a Unix
1379 domain socket) causes "guestfs_launch" to connect to an existing daemon
1380 over the Unix domain socket.
1381 The normal use for this is to connect to a running virtual machine that
1383 contains a "guestfsd" daemon, and send commands so you can read and
1384 write files inside the live virtual machine.
1385 Using guestfs_add_domain with live flag
1387 "guestfs_add_domain" provides some help for getting the correct
1389 backend. If you pass the "live" option to this function, then (if the
1390 virtual machine is running) it will examine the libvirt XML looking for
1391 a virtio-serial channel to connect to:
1392 <domain>
1394 ...
1395 <devices>
1396 ...
1397 <channel type='unix'>
1398 <source mode='bind' path='/path/to/socket'/>
1399 <target type='virtio' name='org.libguestfs.channel.0'/>
1400 </channel>
1401 ...
1402 </devices>
1403 </domain>
1404 "guestfs_add_domain" extracts /path/to/socket and sets the backend to
1406 "unix:/path/to/socket".
1407 Some of the libguestfs tools (including guestfish) support a --live
1409 option which is passed through to "guestfs_add_domain" thus allowing
1410 you to attach to and modify live virtual machines.
1411 The virtual machine needs to have been set up beforehand so that it has
1413 the virtio-serial channel and so that guestfsd is running inside it.
1414 USER-MODE LINUX BACKEND
1416 Setting the following environment variables (or the equivalent in the
1417 API) selects the User-Mode Linux backend:
1418 export LIBGUESTFS_BACKEND=uml
1420 export LIBGUESTFS_HV=/path/to/vmlinux
1421 "vmlinux" (or it may be called "linux") is the Linux binary, compiled
1423 to run as a userspace process. Note that we reuse the qemu variable in
1424 the handle for convenience; qemu is not involved.
1425 User-Mode Linux can be faster and more lightweight than running a full-
1427 blown virtual machine as the backend (especially if you are already
1428 running libguestfs in a virtual machine or cloud instance), but it also
1429 has some shortcomings compared to the usual qemu/KVM-based backend.
1430 BUILDING USER-MODE LINUX FROM SOURCE
1432 Your Linux distro may provide UML in which case you can ignore this
1434 section.
1435 These instructions are adapted from:
1437 http://user-mode-linux.sourceforge.net/source.html
1438 1. Check out Linux sources
1440 Clone the Linux git repository or download the Linux source
1441 tarball.
1442 2. Configure the kernel
1444 Note: All ‘make’ commands must have "ARCH=um" added.
1445 make menuconfig ARCH=um
1447 Make sure any filesystem drivers that you need are compiled into
1449 the kernel.
1450 Currently, it needs a large amount of extra work to get modules
1452 working. It’s recommended that you disable module support in the
1453 kernel configuration, which will cause everything to be compiled
1454 into the image.
1455 3. Build the kernel
1457 make ARCH=um
1458 This will leave a file called "linux" or "vmlinux" in the top-level
1460 directory. This is the UML kernel. You should set "LIBGUESTFS_HV"
1461 to point to this file.
1462 USER-MODE LINUX DIFFERENCES FROM KVM
1464 UML only supports raw-format images
1466 Only plain raw-format images will work. No qcow2, no backing
1467 files.
1468 UML does not support any remote drives
1470 No NBD, etc.
1471 UML only works on ix86 and x86-64
1473 UML is experimental
1474 In particular, support for UML in libguestfs depends on support for
1475 UML in the upstream kernel. If UML was ever removed from the
1476 upstream Linux kernel, then we might remove it from libguestfs too.
1477 ABI GUARANTEE
1479 We guarantee the libguestfs ABI (binary interface), for public, high-
1480 level actions as outlined in this section. Although we will deprecate
1481 some actions, for example if they get replaced by newer calls, we will
1482 keep the old actions forever. This allows you the developer to program
1483 in confidence against the libguestfs API.
1484 BLOCK DEVICE NAMING
1486 Libguestfs defines /dev/sd* as the standard naming scheme for devices
1487 passed to API calls. So /dev/sda means "the first device added by
1488 "guestfs_add_drive_opts"", and /dev/sdb3 means "the third partition on
1489 the second device".
1490 Internally device names are sometimes translated, but this should not
1492 be visible at the API level.
1493 DISK LABELS
1495 In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1497 using the optional "label" parameter to "guestfs_add_drive_opts".
1498 (Note that disk labels are different from and not related to filesystem
1499 labels).
1500 Not all versions of libguestfs support setting a disk label, and when
1502 it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1503 When you add a disk with a label, it can either be addressed using
1505 /dev/sd*, or using /dev/disk/guestfs/label. Partitions on the disk can
1506 be addressed using /dev/disk/guestfs/labelpartnum.
1507 Listing devices ("guestfs_list_devices") and partitions
1509 ("guestfs_list_partitions") returns the block device names. However
1510 you can use "guestfs_list_disk_labels" to map disk labels to block
1511 device and partition names.
1512 NULL DISKS
1514 When adding a disk using, eg., "guestfs_add_drive", you can set the
1515 filename to "/dev/null". This string is treated specially by
1516 libguestfs, causing it to add a "null disk".
1517 A null disk has the following properties:
1519 · A null disk will appear as a normal device, eg. in calls to
1521 "guestfs_list_devices".
1522 · You may add "/dev/null" multiple times.
1524 · You should not try to access a null disk in any way. For example,
1526 you shouldn't try to read it or mount it.
1527 Null disks are used for three main purposes:
1529 1. Performance testing of libguestfs (see guestfs-performance(1)).
1531 2. The internal test suite.
1533 3. If you want to use libguestfs APIs that don’t refer to disks, since
1535 libguestfs requires that at least one disk is added, you should add
1536 a null disk.
1537 For example, to test if a feature is available, use code like this:
1539 guestfs_h *g;
1541 char **groups = [ "btrfs", NULL ];
1542 g = guestfs_create ();
1544 guestfs_add_drive (g, "/dev/null");
1545 guestfs_launch (g);
1546 if (guestfs_available (g, groups) == 0) {
1547 // group(s) are available
1548 } else {
1549 // group(s) are not available
1550 }
1551 guestfs_close (g);
1552 DISK IMAGE FORMATS
1554 Virtual disks come in a variety of formats. Some common formats are
1555 listed below.
1556 Note that libguestfs itself is not responsible for handling the disk
1558 format: this is done using qemu(1). If support for a particular format
1559 is missing or broken, this has to be fixed in qemu.
1560 COMMON VIRTUAL DISK IMAGE FORMATS
1562 raw Raw format is simply a dump of the sequential bytes of the virtual
1564 hard disk. There is no header, container, compression or
1565 processing of any sort.
1566 Since raw format requires no translation to read or write, it is
1568 both fast and very well supported by qemu and all other
1569 hypervisors. You can consider it to be a universal format that any
1570 hypervisor can access.
1571 Raw format files are not compressed and so take up the full space
1573 of the original disk image even when they are empty. A variation
1574 (on Linux/Unix at least) is to not store ranges of all-zero bytes
1575 by storing the file as a sparse file. This "variant format" is
1576 sometimes called raw sparse. Many utilities, including
1577 virt-sparsify(1), can make raw disk images sparse.
1578 qcow2
1580 Qcow2 is the native disk image format used by qemu. Internally it
1581 uses a two-level directory structure so that only blocks containing
1582 data are stored in the file. It also has many other features such
1583 as compression, snapshots and backing files.
1584 There are at least two distinct variants of this format, although
1586 qemu (and hence libguestfs) handles both transparently to the user.
1587 vmdk
1589 VMDK is VMware’s native disk image format. There are many
1590 variations. Modern qemu (hence libguestfs) supports most
1591 variations, but you should be aware that older versions of qemu had
1592 some very bad data-corrupting bugs in this area.
1593 Note that VMware ESX exposes files with the name guest-flat.vmdk.
1595 These are not VMDK. They are raw format files which happen to have
1596 a ".vmdk" extension.
1597 vdi VDI is VirtualBox’s native disk image format. Qemu (hence
1599 libguestfs) has generally good support for this.
1600 vpc
1602 vhd VPC (old) and VHD (modern) are the native disk image format of
1603 Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1604 Obsolete formats
1606 The following formats are obsolete and should not be used: qcow
1607 (aka qcow1), cow, bochs.
1608 DETECTING THE FORMAT OF A DISK IMAGE
1610 Firstly note there is a security issue with auto-detecting the format
1612 of a disk image. It may or may not apply in your use case. Read
1613 "CVE-2010-3851" below.
1614 Libguestfs offers an API to get the format of a disk image
1616 ("guestfs_disk_format"), and it is safest to use this.
1617 Don’t be tempted to try parsing the text / human-readable output of
1619 "qemu-img" since it cannot be parsed reliably and securely. Also do
1620 not use the "file" command since the output of that changes over time.
1621
1623 guestfs_h *
1624 "guestfs_h" is the opaque type representing a connection handle.
1625 Create a handle by calling "guestfs_create" or "guestfs_create_flags".
1626 Call "guestfs_close" to free the handle and release all resources used.
1627 For information on using multiple handles and threads, see the section
1629 "MULTIPLE HANDLES AND MULTIPLE THREADS" above.
1630 guestfs_create
1632 guestfs_h *guestfs_create (void);
1633 Create a connection handle.
1635 On success this returns a non-NULL pointer to a handle. On error it
1637 returns NULL.
1638 You have to "configure" the handle after creating it. This includes
1640 calling "guestfs_add_drive_opts" (or one of the equivalent calls) on
1641 the handle at least once.
1642 After configuring the handle, you have to call "guestfs_launch".
1644 You may also want to configure error handling for the handle. See the
1646 "ERROR HANDLING" section below.
1647 guestfs_create_flags
1649 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
1650 Create a connection handle, supplying extra flags and extra arguments
1652 to control how the handle is created.
1653 On success this returns a non-NULL pointer to a handle. On error it
1655 returns NULL.
1656 "guestfs_create" is equivalent to calling guestfs_create_flags(0).
1658 The following flags may be logically ORed together. (Currently no
1660 extra arguments are used).
1661 "GUESTFS_CREATE_NO_ENVIRONMENT"
1663 Don’t parse any environment variables (such as "LIBGUESTFS_DEBUG"
1664 etc).
1665 You can call "guestfs_parse_environment" or
1667 "guestfs_parse_environment_list" afterwards to parse environment
1668 variables. Alternately, don't call these functions if you want the
1669 handle to be unaffected by environment variables. See the example
1670 below.
1671 The default (if this flag is not given) is to implicitly call
1673 "guestfs_parse_environment".
1674 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT"
1676 Don’t try to close the handle in an atexit(3) handler if the
1677 program exits without explicitly closing the handle.
1678 The default (if this flag is not given) is to install such an
1680 atexit handler.
1681 USING "GUESTFS_CREATE_NO_ENVIRONMENT"
1683 You might use "GUESTFS_CREATE_NO_ENVIRONMENT" and an explicit call to
1685 "guestfs_parse_environment" like this:
1686 guestfs_h *g;
1688 int r;
1689 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
1691 if (!g) {
1692 perror ("guestfs_create_flags");
1693 exit (EXIT_FAILURE);
1694 }
1695 r = guestfs_parse_environment (g);
1696 if (r == -1)
1697 exit (EXIT_FAILURE);
1698 Or to create a handle which is unaffected by environment variables,
1700 omit the call to "guestfs_parse_environment" from the above code.
1701 The above code has another advantage which is that any errors from
1703 parsing the environment are passed through the error handler, whereas
1704 "guestfs_create" prints errors on stderr and ignores them.
1705 guestfs_close
1707 void guestfs_close (guestfs_h *g);
1708 This closes the connection handle and frees up all resources used. If
1710 a close callback was set on the handle, then it is called.
1711 The correct way to close the handle is:
1713 if (guestfs_shutdown (g) == -1) {
1715 /* handle write errors here */
1716 }
1717 guestfs_close (g);
1718 "guestfs_shutdown" is only needed if all of the following are true:
1720 1. one or more disks were added in read-write mode, and
1722 2. guestfs_launch was called, and
1724 3. you made some changes, and
1726 4. you have a way to handle write errors (eg. by exiting with an error
1728 code or reporting something to the user).
1729
1731 API functions can return errors. For example, almost all functions
1732 that return "int" will return "-1" to indicate an error.
1733 Additional information is available for errors: an error message string
1735 and optionally an error number (errno) if the thing that failed was a
1736 system call.
1737 You can get at the additional information about the last error on the
1739 handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1740 setting up an error handler with "guestfs_set_error_handler".
1741 When the handle is created, a default error handler is installed which
1743 prints the error message string to "stderr". For small short-running
1744 command line programs it is sufficient to do:
1745 if (guestfs_launch (g) == -1)
1747 exit (EXIT_FAILURE);
1748 since the default error handler will ensure that an error message has
1750 been printed to "stderr" before the program exits.
1751 For other programs the caller will almost certainly want to install an
1753 alternate error handler or do error handling in-line as in the example
1754 below. The non-C language bindings all install NULL error handlers and
1755 turn errors into exceptions using code similar to this:
1756 const char *msg;
1758 int errnum;
1759 /* This disables the default behaviour of printing errors
1761 on stderr. */
1762 guestfs_set_error_handler (g, NULL, NULL);
1763 if (guestfs_launch (g) == -1) {
1765 /* Examine the error message and print it, throw it,
1766 etc. */
1767 msg = guestfs_last_error (g);
1768 errnum = guestfs_last_errno (g);
1769 fprintf (stderr, "%s", msg);
1771 if (errnum != 0)
1772 fprintf (stderr, ": %s", strerror (errnum));
1773 fprintf (stderr, "\n");
1774 /* ... */
1776 }
1777 "guestfs_create" returns "NULL" if the handle cannot be created, and
1779 because there is no handle if this happens there is no way to get
1780 additional error information. Since libguestfs ≥ 1.20, you can use
1781 "guestfs_create_flags" to properly deal with errors during handle
1782 creation, although the vast majority of programs can continue to use
1783 "guestfs_create" and not worry about this situation.
1784 Out of memory errors are handled differently. The default action is to
1786 call abort(3). If this is undesirable, then you can set a handler
1787 using "guestfs_set_out_of_memory_handler".
1788 guestfs_last_error
1790 const char *guestfs_last_error (guestfs_h *g);
1791 This returns the last error message that happened on "g". If there has
1793 not been an error since the handle was created, then this returns
1794 "NULL".
1795 Note the returned string does not have a newline character at the end.
1797 Most error messages are single lines. Some are split over multiple
1798 lines and contain "\n" characters within the string but not at the end.
1799 The lifetime of the returned string is until the next error occurs on
1801 the same handle, or "guestfs_close" is called. If you need to keep it
1802 longer, copy it.
1803 guestfs_last_errno
1805 int guestfs_last_errno (guestfs_h *g);
1806 This returns the last error number (errno) that happened on "g".
1808 If successful, an errno integer not equal to zero is returned.
1810 In many cases the special errno "ENOTSUP" is returned if you tried to
1812 call a function or use a feature which is not supported.
1813 If no error number is available, this returns 0. This call can return
1815 0 in three situations:
1816 1. There has not been any error on the handle.
1818 2. There has been an error but the errno was meaningless. This
1820 corresponds to the case where the error did not come from a failed
1821 system call, but for some other reason.
1822 3. There was an error from a failed system call, but for some reason
1824 the errno was not captured and returned. This usually indicates a
1825 bug in libguestfs.
1826 Libguestfs tries to convert the errno from inside the appliance into a
1828 corresponding errno for the caller (not entirely trivial: the appliance
1829 might be running a completely different operating system from the
1830 library and error numbers are not standardized across Un*xen). If this
1831 could not be done, then the error is translated to "EINVAL". In
1832 practice this should only happen in very rare circumstances.
1833 guestfs_set_error_handler
1835 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1836 void *opaque,
1837 const char *msg);
1838 void guestfs_set_error_handler (guestfs_h *g,
1839 guestfs_error_handler_cb cb,
1840 void *opaque);
1841 The callback "cb" will be called if there is an error. The parameters
1843 passed to the callback are an opaque data pointer and the error message
1844 string.
1845 "errno" is not passed to the callback. To get that the callback must
1847 call "guestfs_last_errno".
1848 Note that the message string "msg" is freed as soon as the callback
1850 function returns, so if you want to stash it somewhere you must make
1851 your own copy.
1852 The default handler prints messages on "stderr".
1854 If you set "cb" to "NULL" then no handler is called.
1856 guestfs_get_error_handler
1858 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1859 void **opaque_rtn);
1860 Returns the current error handler callback.
1862 guestfs_push_error_handler
1864 void guestfs_push_error_handler (guestfs_h *g,
1865 guestfs_error_handler_cb cb,
1866 void *opaque);
1867 This is the same as "guestfs_set_error_handler", except that the old
1869 error handler is stashed away in a stack inside the handle. You can
1870 restore the previous error handler by calling
1871 "guestfs_pop_error_handler".
1872 Use the following code to temporarily disable errors around a function:
1874 guestfs_push_error_handler (g, NULL, NULL);
1876 guestfs_mkdir (g, "/foo"); /* We don't care if this fails. */
1877 guestfs_pop_error_handler (g);
1878 guestfs_pop_error_handler
1880 void guestfs_pop_error_handler (guestfs_h *g);
1881 Restore the previous error handler (see "guestfs_push_error_handler").
1883 If you pop the stack too many times, then the default error handler is
1885 restored.
1886 guestfs_set_out_of_memory_handler
1888 typedef void (*guestfs_abort_cb) (void);
1889 void guestfs_set_out_of_memory_handler (guestfs_h *g,
1890 guestfs_abort_cb);
1891 The callback "cb" will be called if there is an out of memory
1893 situation. Note this callback must not return.
1894 The default is to call abort(3).
1896 You cannot set "cb" to "NULL". You can’t ignore out of memory
1898 situations.
1899 guestfs_get_out_of_memory_handler
1901 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1902 This returns the current out of memory handler.
1904
1906 guestfs_acl_delete_def_file
1907 int
1908 guestfs_acl_delete_def_file (guestfs_h *g,
1909 const char *dir);
1910 This function deletes the default POSIX Access Control List (ACL)
1912 attached to directory "dir".
1913 This function returns 0 on success or -1 on error.
1915 This function depends on the feature "acl". See also
1917 "guestfs_feature_available".
1918 (Added in 1.19.63)
1920 guestfs_acl_get_file
1922 char *
1923 guestfs_acl_get_file (guestfs_h *g,
1924 const char *path,
1925 const char *acltype);
1926 This function returns the POSIX Access Control List (ACL) attached to
1928 "path". The ACL is returned in "long text form" (see acl(5)).
1929 The "acltype" parameter may be:
1931 "access"
1933 Return the ordinary (access) ACL for any file, directory or other
1934 filesystem object.
1935 "default"
1937 Return the default ACL. Normally this only makes sense if "path"
1938 is a directory.
1939 This function returns a string, or NULL on error. The caller must free
1941 the returned string after use.
1942 This function depends on the feature "acl". See also
1944 "guestfs_feature_available".
1945 (Added in 1.19.63)
1947 guestfs_acl_set_file
1949 int
1950 guestfs_acl_set_file (guestfs_h *g,
1951 const char *path,
1952 const char *acltype,
1953 const char *acl);
1954 This function sets the POSIX Access Control List (ACL) attached to
1956 "path".
1957 The "acltype" parameter may be:
1959 "access"
1961 Set the ordinary (access) ACL for any file, directory or other
1962 filesystem object.
1963 "default"
1965 Set the default ACL. Normally this only makes sense if "path" is a
1966 directory.
1967 The "acl" parameter is the new ACL in either "long text form" or "short
1969 text form" (see acl(5)). The new ACL completely replaces any previous
1970 ACL on the file. The ACL must contain the full Unix permissions (eg.
1971 "u::rwx,g::rx,o::rx").
1972 If you are specifying individual users or groups, then the mask field
1974 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1975 "g:ID:..." field(s). A full ACL string might therefore look like this:
1976 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1978 \ Unix permissions / \mask/ \ ACL /
1979 You should use numeric UIDs and GIDs. To map usernames and groupnames
1981 to the correct numeric ID in the context of the guest, use the Augeas
1982 functions (see "guestfs_aug_init").
1983 This function returns 0 on success or -1 on error.
1985 This function depends on the feature "acl". See also
1987 "guestfs_feature_available".
1988 (Added in 1.19.63)
1990 guestfs_add_cdrom
1992 int
1993 guestfs_add_cdrom (guestfs_h *g,
1994 const char *filename);
1995 This function is deprecated. In new code, use the
1997 "guestfs_add_drive_ro" call instead.
1998 Deprecated functions will not be removed from the API, but the fact
2000 that they are deprecated indicates that there are problems with correct
2001 use of these functions.
2002 This function adds a virtual CD-ROM disk image to the guest.
2004 The image is added as read-only drive, so this function is equivalent
2006 of "guestfs_add_drive_ro".
2007 This function returns 0 on success or -1 on error.
2009 (Added in 0.3)
2011 guestfs_add_domain
2013 int
2014 guestfs_add_domain (guestfs_h *g,
2015 const char *dom,
2016 ...);
2017 You may supply a list of optional arguments to this call. Use zero or
2019 more of the following pairs of parameters, and terminate the list with
2020 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2021 GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
2023 GUESTFS_ADD_DOMAIN_READONLY, int readonly,
2024 GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
2025 GUESTFS_ADD_DOMAIN_LIVE, int live,
2026 GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
2027 GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
2028 GUESTFS_ADD_DOMAIN_CACHEMODE, const char *cachemode,
2029 GUESTFS_ADD_DOMAIN_DISCARD, const char *discard,
2030 GUESTFS_ADD_DOMAIN_COPYONREAD, int copyonread,
2031 This function adds the disk(s) attached to the named libvirt domain
2033 "dom". It works by connecting to libvirt, requesting the domain and
2034 domain XML from libvirt, parsing it for disks, and calling
2035 "guestfs_add_drive_opts" on each one.
2036 The number of disks added is returned. This operation is atomic: if an
2038 error is returned, then no disks are added.
2039 This function does some minimal checks to make sure the libvirt domain
2041 is not running (unless "readonly" is true). In a future version we
2042 will try to acquire the libvirt lock on each disk.
2043 Disks must be accessible locally. This often means that adding disks
2045 from a remote libvirt connection (see https://libvirt.org/remote.html)
2046 will fail unless those disks are accessible via the same device path
2047 locally too.
2048 The optional "libvirturi" parameter sets the libvirt URI (see
2050 https://libvirt.org/uri.html). If this is not set then we connect to
2051 the default libvirt URI (or one set through an environment variable,
2052 see the libvirt documentation for full details).
2053 The optional "live" flag controls whether this call will try to connect
2055 to a running virtual machine "guestfsd" process if it sees a suitable
2056 <channel> element in the libvirt XML definition. The default (if the
2057 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
2058 for more information.
2059 If the "allowuuid" flag is true (default is false) then a UUID may be
2061 passed instead of the domain name. The "dom" string is treated as a
2062 UUID first and looked up, and if that lookup fails then we treat "dom"
2063 as a name as usual.
2064 The optional "readonlydisk" parameter controls what we do for disks
2066 which are marked <readonly/> in the libvirt XML. Possible values are:
2067 readonlydisk = "error"
2069 If "readonly" is false:
2070 The whole call is aborted with an error if any disk with the
2072 <readonly/> flag is found.
2073 If "readonly" is true:
2075 Disks with the <readonly/> flag are added read-only.
2077 readonlydisk = "read"
2079 If "readonly" is false:
2080 Disks with the <readonly/> flag are added read-only. Other disks
2082 are added read/write.
2083 If "readonly" is true:
2085 Disks with the <readonly/> flag are added read-only.
2087 readonlydisk = "write" (default)
2089 If "readonly" is false:
2090 Disks with the <readonly/> flag are added read/write.
2092 If "readonly" is true:
2094 Disks with the <readonly/> flag are added read-only.
2096 readonlydisk = "ignore"
2098 If "readonly" is true or false:
2099 Disks with the <readonly/> flag are skipped.
2101 If present, the value of "logical_block_size" attribute of <blockio/>
2103 tag in libvirt XML will be passed as "blocksize" parameter to
2104 "guestfs_add_drive_opts".
2105 The other optional parameters are passed directly through to
2107 "guestfs_add_drive_opts".
2108 On error this function returns -1.
2110 (Added in 1.7.4)
2112 guestfs_add_domain_va
2114 int
2115 guestfs_add_domain_va (guestfs_h *g,
2116 const char *dom,
2117 va_list args);
2118 This is the "va_list variant" of "guestfs_add_domain".
2120 See "CALLS WITH OPTIONAL ARGUMENTS".
2122 guestfs_add_domain_argv
2124 int
2125 guestfs_add_domain_argv (guestfs_h *g,
2126 const char *dom,
2127 const struct guestfs_add_domain_argv *optargs);
2128 This is the "argv variant" of "guestfs_add_domain".
2130 See "CALLS WITH OPTIONAL ARGUMENTS".
2132 guestfs_add_drive
2134 int
2135 guestfs_add_drive (guestfs_h *g,
2136 const char *filename);
2137 This function is provided for backwards compatibility with earlier
2139 versions of libguestfs. It simply calls "guestfs_add_drive_opts" with
2140 no optional arguments.
2141 (Added in 0.3)
2143 guestfs_add_drive_opts
2145 int
2146 guestfs_add_drive_opts (guestfs_h *g,
2147 const char *filename,
2148 ...);
2149 You may supply a list of optional arguments to this call. Use zero or
2151 more of the following pairs of parameters, and terminate the list with
2152 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2153 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2155 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2156 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2157 GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2158 GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2159 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2160 GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2161 GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2162 GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2163 GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2164 GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2165 GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2166 GUESTFS_ADD_DRIVE_OPTS_BLOCKSIZE, int blocksize,
2167 This function adds a disk image called filename to the handle.
2169 filename may be a regular host file or a host device.
2170 When this function is called before "guestfs_launch" (the usual case)
2172 then the first time you call this function, the disk appears in the API
2173 as /dev/sda, the second time as /dev/sdb, and so on.
2174 In libguestfs ≥ 1.20 you can also call this function after launch (with
2176 some restrictions). This is called "hotplugging". When hotplugging,
2177 you must specify a "label" so that the new disk gets a predictable
2178 name. For more information see "HOTPLUGGING".
2179 You don't necessarily need to be root when using libguestfs. However
2181 you obviously do need sufficient permissions to access the filename for
2182 whatever operations you want to perform (ie. read access if you just
2183 want to read the image or write access if you want to modify the
2184 image).
2185 This call checks that filename exists.
2187 filename may be the special string "/dev/null". See "NULL DISKS".
2189 The optional arguments are:
2191 "readonly"
2193 If true then the image is treated as read-only. Writes are still
2194 allowed, but they are stored in a temporary snapshot overlay which
2195 is discarded at the end. The disk that you add is not modified.
2196 "format"
2198 This forces the image format. If you omit this (or use
2199 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2200 automatically detected. Possible formats include "raw" and
2201 "qcow2".
2202 Automatic detection of the format opens you up to a potential
2204 security hole when dealing with untrusted raw-format images. See
2205 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
2206 security hole.
2207 "iface"
2209 This rarely-used option lets you emulate the behaviour of the
2210 deprecated "guestfs_add_drive_with_if" call (q.v.)
2211 "name"
2213 The name the drive had in the original guest, e.g. /dev/sdb. This
2214 is used as a hint to the guest inspection process if it is
2215 available.
2216 "label"
2218 Give the disk a label. The label should be a unique, short string
2219 using only ASCII characters "[a-zA-Z]". As well as its usual name
2220 in the API (such as /dev/sda), the drive will also be named
2221 /dev/disk/guestfs/label.
2222 See "DISK LABELS".
2224 "protocol"
2226 The optional protocol argument can be used to select an alternate
2227 source protocol.
2228 See also: "REMOTE STORAGE".
2230 "protocol = "file""
2232 filename is interpreted as a local file or device. This is the
2233 default if the optional protocol parameter is omitted.
2234 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
2236 Connect to a remote FTP, HTTP or TFTP server. The "server"
2237 parameter must also be supplied - see below.
2238 See also: "FTP, HTTP AND TFTP"
2240 "protocol = "gluster""
2242 Connect to the GlusterFS server. The "server" parameter must
2243 also be supplied - see below.
2244 See also: "GLUSTER"
2246 "protocol = "iscsi""
2248 Connect to the iSCSI server. The "server" parameter must also
2249 be supplied - see below. The "username" parameter may be
2250 supplied. See below. The "secret" parameter may be supplied.
2251 See below.
2252 See also: "ISCSI".
2254 "protocol = "nbd""
2256 Connect to the Network Block Device server. The "server"
2257 parameter must also be supplied - see below.
2258 See also: "NETWORK BLOCK DEVICE".
2260 "protocol = "rbd""
2262 Connect to the Ceph (librbd/RBD) server. The "server"
2263 parameter must also be supplied - see below. The "username"
2264 parameter may be supplied. See below. The "secret" parameter
2265 may be supplied. See below.
2266 See also: "CEPH".
2268 "protocol = "sheepdog""
2270 Connect to the Sheepdog server. The "server" parameter may
2271 also be supplied - see below.
2272 See also: "SHEEPDOG".
2274 "protocol = "ssh""
2276 Connect to the Secure Shell (ssh) server.
2277 The "server" parameter must be supplied. The "username"
2279 parameter may be supplied. See below.
2280 See also: "SSH".
2282 "server"
2284 For protocols which require access to a remote server, this is a
2285 list of server(s).
2286 Protocol Number of servers required
2288 -------- --------------------------
2289 file List must be empty or param not used at all
2290 ftp|ftps|http|https|tftp Exactly one
2291 gluster Exactly one
2292 iscsi Exactly one
2293 nbd Exactly one
2294 rbd Zero or more
2295 sheepdog Zero or more
2296 ssh Exactly one
2297 Each list element is a string specifying a server. The string must
2299 be in one of the following formats:
2300 hostname
2302 hostname:port
2303 tcp:hostname
2304 tcp:hostname:port
2305 unix:/path/to/socket
2306 If the port number is omitted, then the standard port number for
2308 the protocol is used (see /etc/services).
2309 "username"
2311 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
2312 "tftp" protocols, this specifies the remote username.
2313 If not given, then the local username is used for "ssh", and no
2315 authentication is attempted for ceph. But note this sometimes may
2316 give unexpected results, for example if using the libvirt backend
2317 and if the libvirt backend is configured to start the qemu
2318 appliance as a special user such as "qemu.qemu". If in doubt,
2319 specify the remote username you want.
2320 "secret"
2322 For the "rbd" protocol only, this specifies the ‘secret’ to use
2323 when connecting to the remote device. It must be base64 encoded.
2324 If not given, then a secret matching the given username will be
2326 looked up in the default keychain locations, or if no username is
2327 given, then no authentication will be used.
2328 "cachemode"
2330 Choose whether or not libguestfs will obey sync operations (safe
2331 but slow) or not (unsafe but fast). The possible values for this
2332 string are:
2333 "cachemode = "writeback""
2335 This is the default.
2336 Write operations in the API do not return until a write(2) call
2338 has completed in the host [but note this does not imply that
2339 anything gets written to disk].
2340 Sync operations in the API, including implicit syncs caused by
2342 filesystem journalling, will not return until an fdatasync(2)
2343 call has completed in the host, indicating that data has been
2344 committed to disk.
2345 "cachemode = "unsafe""
2347 In this mode, there are no guarantees. Libguestfs may cache
2348 anything and ignore sync requests. This is suitable only for
2349 scratch or temporary disks.
2350 "discard"
2352 Enable or disable discard (a.k.a. trim or unmap) support on this
2353 drive. If enabled, operations such as "guestfs_fstrim" will be
2354 able to discard / make thin / punch holes in the underlying host
2355 file or device.
2356 Possible discard settings are:
2358 "discard = "disable""
2360 Disable discard support. This is the default.
2361 "discard = "enable""
2363 Enable discard support. Fail if discard is not possible.
2364 "discard = "besteffort""
2366 Enable discard support if possible, but don't fail if it is not
2367 supported.
2368 Since not all backends and not all underlying systems support
2370 discard, this is a good choice if you want to use discard if
2371 possible, but don't mind if it doesn't work.
2372 "copyonread"
2374 The boolean parameter "copyonread" enables copy-on-read support.
2375 This only affects disk formats which have backing files, and causes
2376 reads to be stored in the overlay layer, speeding up multiple reads
2377 of the same area of disk.
2378 The default is false.
2380 "blocksize"
2382 This parameter sets the sector size of the disk. Possible values
2383 are 512 (the default if the parameter is omitted) or 4096. Use
2384 4096 when handling an "Advanced Format" disk that uses 4K sector
2385 size (https://en.wikipedia.org/wiki/Advanced_Format).
2386 Only a subset of the backends support this parameter (currently
2388 only the libvirt and direct backends do).
2389 This function returns 0 on success or -1 on error.
2391 (Added in 0.3)
2393 guestfs_add_drive_opts_va
2395 int
2396 guestfs_add_drive_opts_va (guestfs_h *g,
2397 const char *filename,
2398 va_list args);
2399 This is the "va_list variant" of "guestfs_add_drive_opts".
2401 See "CALLS WITH OPTIONAL ARGUMENTS".
2403 guestfs_add_drive_opts_argv
2405 int
2406 guestfs_add_drive_opts_argv (guestfs_h *g,
2407 const char *filename,
2408 const struct guestfs_add_drive_opts_argv *optargs);
2409 This is the "argv variant" of "guestfs_add_drive_opts".
2411 See "CALLS WITH OPTIONAL ARGUMENTS".
2413 guestfs_add_drive_ro
2415 int
2416 guestfs_add_drive_ro (guestfs_h *g,
2417 const char *filename);
2418 This function is the equivalent of calling "guestfs_add_drive_opts"
2420 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2421 so the disk is added read-only, with the format being detected
2422 automatically.
2423 This function returns 0 on success or -1 on error.
2425 (Added in 1.0.38)
2427 guestfs_add_drive_ro_with_if
2429 int
2430 guestfs_add_drive_ro_with_if (guestfs_h *g,
2431 const char *filename,
2432 const char *iface);
2433 This function is deprecated. In new code, use the "guestfs_add_drive"
2435 call instead.
2436 Deprecated functions will not be removed from the API, but the fact
2438 that they are deprecated indicates that there are problems with correct
2439 use of these functions.
2440 This is the same as "guestfs_add_drive_ro" but it allows you to specify
2442 the QEMU interface emulation to use at run time.
2443 This function returns 0 on success or -1 on error.
2445 (Added in 1.0.84)
2447 guestfs_add_drive_scratch
2449 int
2450 guestfs_add_drive_scratch (guestfs_h *g,
2451 int64_t size,
2452 ...);
2453 You may supply a list of optional arguments to this call. Use zero or
2455 more of the following pairs of parameters, and terminate the list with
2456 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2457 GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2459 GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2460 GUESTFS_ADD_DRIVE_SCRATCH_BLOCKSIZE, int blocksize,
2461 This command adds a temporary scratch drive to the handle. The "size"
2463 parameter is the virtual size (in bytes). The scratch drive is blank
2464 initially (all reads return zeroes until you start writing to it). The
2465 drive is deleted when the handle is closed.
2466 The optional arguments "name", "label" and "blocksize" are passed
2468 through to "guestfs_add_drive_opts".
2469 This function returns 0 on success or -1 on error.
2471 (Added in 1.23.10)
2473 guestfs_add_drive_scratch_va
2475 int
2476 guestfs_add_drive_scratch_va (guestfs_h *g,
2477 int64_t size,
2478 va_list args);
2479 This is the "va_list variant" of "guestfs_add_drive_scratch".
2481 See "CALLS WITH OPTIONAL ARGUMENTS".
2483 guestfs_add_drive_scratch_argv
2485 int
2486 guestfs_add_drive_scratch_argv (guestfs_h *g,
2487 int64_t size,
2488 const struct guestfs_add_drive_scratch_argv *optargs);
2489 This is the "argv variant" of "guestfs_add_drive_scratch".
2491 See "CALLS WITH OPTIONAL ARGUMENTS".
2493 guestfs_add_drive_with_if
2495 int
2496 guestfs_add_drive_with_if (guestfs_h *g,
2497 const char *filename,
2498 const char *iface);
2499 This function is deprecated. In new code, use the "guestfs_add_drive"
2501 call instead.
2502 Deprecated functions will not be removed from the API, but the fact
2504 that they are deprecated indicates that there are problems with correct
2505 use of these functions.
2506 This is the same as "guestfs_add_drive" but it allows you to specify
2508 the QEMU interface emulation to use at run time.
2509 This function returns 0 on success or -1 on error.
2511 (Added in 1.0.84)
2513 guestfs_add_libvirt_dom
2515 int
2516 guestfs_add_libvirt_dom (guestfs_h *g,
2517 void * /* really virDomainPtr */ dom,
2518 ...);
2519 You may supply a list of optional arguments to this call. Use zero or
2521 more of the following pairs of parameters, and terminate the list with
2522 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2523 GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2525 GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2526 GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2527 GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2528 GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2529 GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2530 GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2531 This function adds the disk(s) attached to the libvirt domain "dom".
2533 It works by requesting the domain XML from libvirt, parsing it for
2534 disks, and calling "guestfs_add_drive_opts" on each one.
2535 In the C API we declare "void *dom", but really it has type
2537 "virDomainPtr dom". This is so we don't need <libvirt.h>.
2538 The number of disks added is returned. This operation is atomic: if an
2540 error is returned, then no disks are added.
2541 This function does some minimal checks to make sure the libvirt domain
2543 is not running (unless "readonly" is true). In a future version we
2544 will try to acquire the libvirt lock on each disk.
2545 Disks must be accessible locally. This often means that adding disks
2547 from a remote libvirt connection (see https://libvirt.org/remote.html)
2548 will fail unless those disks are accessible via the same device path
2549 locally too.
2550 The optional "live" flag controls whether this call will try to connect
2552 to a running virtual machine "guestfsd" process if it sees a suitable
2553 <channel> element in the libvirt XML definition. The default (if the
2554 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
2555 for more information.
2556 The optional "readonlydisk" parameter controls what we do for disks
2558 which are marked <readonly/> in the libvirt XML. See
2559 "guestfs_add_domain" for possible values.
2560 If present, the value of "logical_block_size" attribute of <blockio/>
2562 tag in libvirt XML will be passed as "blocksize" parameter to
2563 "guestfs_add_drive_opts".
2564 The other optional parameters are passed directly through to
2566 "guestfs_add_drive_opts".
2567 On error this function returns -1.
2569 (Added in 1.29.14)
2571 guestfs_add_libvirt_dom_va
2573 int
2574 guestfs_add_libvirt_dom_va (guestfs_h *g,
2575 void * /* really virDomainPtr */ dom,
2576 va_list args);
2577 This is the "va_list variant" of "guestfs_add_libvirt_dom".
2579 See "CALLS WITH OPTIONAL ARGUMENTS".
2581 guestfs_add_libvirt_dom_argv
2583 int
2584 guestfs_add_libvirt_dom_argv (guestfs_h *g,
2585 void * /* really virDomainPtr */ dom,
2586 const struct guestfs_add_libvirt_dom_argv *optargs);
2587 This is the "argv variant" of "guestfs_add_libvirt_dom".
2589 See "CALLS WITH OPTIONAL ARGUMENTS".
2591 guestfs_aug_clear
2593 int
2594 guestfs_aug_clear (guestfs_h *g,
2595 const char *augpath);
2596 Set the value associated with "path" to "NULL". This is the same as
2598 the augtool(1) "clear" command.
2599 This function returns 0 on success or -1 on error.
2601 (Added in 1.3.4)
2603 guestfs_aug_close
2605 int
2606 guestfs_aug_close (guestfs_h *g);
2607 Close the current Augeas handle and free up any resources used by it.
2609 After calling this, you have to call "guestfs_aug_init" again before
2610 you can use any other Augeas functions.
2611 This function returns 0 on success or -1 on error.
2613 (Added in 0.7)
2615 guestfs_aug_defnode
2617 struct guestfs_int_bool *
2618 guestfs_aug_defnode (guestfs_h *g,
2619 const char *name,
2620 const char *expr,
2621 const char *val);
2622 Defines a variable "name" whose value is the result of evaluating
2624 "expr".
2625 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2627 to calling "guestfs_aug_set" "expr", "val". "name" will be the nodeset
2628 containing that single node.
2629 On success this returns a pair containing the number of nodes in the
2631 nodeset, and a boolean flag if a node was created.
2632 This function returns a "struct guestfs_int_bool *", or NULL if there
2634 was an error. The caller must call "guestfs_free_int_bool" after use.
2635 (Added in 0.7)
2637 guestfs_aug_defvar
2639 int
2640 guestfs_aug_defvar (guestfs_h *g,
2641 const char *name,
2642 const char *expr);
2643 Defines an Augeas variable "name" whose value is the result of
2645 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2646 On success this returns the number of nodes in "expr", or 0 if "expr"
2648 evaluates to something which is not a nodeset.
2649 On error this function returns -1.
2651 (Added in 0.7)
2653 guestfs_aug_get
2655 char *
2656 guestfs_aug_get (guestfs_h *g,
2657 const char *augpath);
2658 Look up the value associated with "path". If "path" matches exactly
2660 one node, the "value" is returned.
2661 This function returns a string, or NULL on error. The caller must free
2663 the returned string after use.
2664 (Added in 0.7)
2666 guestfs_aug_init
2668 int
2669 guestfs_aug_init (guestfs_h *g,
2670 const char *root,
2671 int flags);
2672 Create a new Augeas handle for editing configuration files. If there
2674 was any previous Augeas handle associated with this guestfs session,
2675 then it is closed.
2676 You must call this before using any other "guestfs_aug_*" commands.
2678 "root" is the filesystem root. "root" must not be NULL, use / instead.
2680 The flags are the same as the flags defined in <augeas.h>, the logical
2682 or of the following integers:
2683 "AUG_SAVE_BACKUP" = 1
2685 Keep the original file with a ".augsave" extension.
2686 "AUG_SAVE_NEWFILE" = 2
2688 Save changes into a file with extension ".augnew", and do not
2689 overwrite original. Overrides "AUG_SAVE_BACKUP".
2690 "AUG_TYPE_CHECK" = 4
2692 Typecheck lenses.
2693 This option is only useful when debugging Augeas lenses. Use of
2695 this option may require additional memory for the libguestfs
2696 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2697 environment variable or call "guestfs_set_memsize".
2698 "AUG_NO_STDINC" = 8
2700 Do not use standard load path for modules.
2701 "AUG_SAVE_NOOP" = 16
2703 Make save a no-op, just record what would have been changed.
2704 "AUG_NO_LOAD" = 32
2706 Do not load the tree in "guestfs_aug_init".
2707 To close the handle, you can call "guestfs_aug_close".
2709 To find out more about Augeas, see http://augeas.net/.
2711 This function returns 0 on success or -1 on error.
2713 (Added in 0.7)
2715 guestfs_aug_insert
2717 int
2718 guestfs_aug_insert (guestfs_h *g,
2719 const char *augpath,
2720 const char *label,
2721 int before);
2722 Create a new sibling "label" for "path", inserting it into the tree
2724 before or after "path" (depending on the boolean flag "before").
2725 "path" must match exactly one existing node in the tree, and "label"
2727 must be a label, ie. not contain /, "*" or end with a bracketed index
2728 "[N]".
2729 This function returns 0 on success or -1 on error.
2731 (Added in 0.7)
2733 guestfs_aug_label
2735 char *
2736 guestfs_aug_label (guestfs_h *g,
2737 const char *augpath);
2738 The label (name of the last element) of the Augeas path expression
2740 "augpath" is returned. "augpath" must match exactly one node, else
2741 this function returns an error.
2742 This function returns a string, or NULL on error. The caller must free
2744 the returned string after use.
2745 (Added in 1.23.14)
2747 guestfs_aug_load
2749 int
2750 guestfs_aug_load (guestfs_h *g);
2751 Load files into the tree.
2753 See "aug_load" in the Augeas documentation for the full gory details.
2755 This function returns 0 on success or -1 on error.
2757 (Added in 0.7)
2759 guestfs_aug_ls
2761 char **
2762 guestfs_aug_ls (guestfs_h *g,
2763 const char *augpath);
2764 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2766 sorting the resulting nodes into alphabetical order.
2767 This function returns a NULL-terminated array of strings (like
2769 environ(3)), or NULL if there was an error. The caller must free the
2770 strings and the array after use.
2771 (Added in 0.8)
2773 guestfs_aug_match
2775 char **
2776 guestfs_aug_match (guestfs_h *g,
2777 const char *augpath);
2778 Returns a list of paths which match the path expression "path". The
2780 returned paths are sufficiently qualified so that they match exactly
2781 one node in the current tree.
2782 This function returns a NULL-terminated array of strings (like
2784 environ(3)), or NULL if there was an error. The caller must free the
2785 strings and the array after use.
2786 (Added in 0.7)
2788 guestfs_aug_mv
2790 int
2791 guestfs_aug_mv (guestfs_h *g,
2792 const char *src,
2793 const char *dest);
2794 Move the node "src" to "dest". "src" must match exactly one node.
2796 "dest" is overwritten if it exists.
2797 This function returns 0 on success or -1 on error.
2799 (Added in 0.7)
2801 guestfs_aug_rm
2803 int
2804 guestfs_aug_rm (guestfs_h *g,
2805 const char *augpath);
2806 Remove "path" and all of its children.
2808 On success this returns the number of entries which were removed.
2810 On error this function returns -1.
2812 (Added in 0.7)
2814 guestfs_aug_save
2816 int
2817 guestfs_aug_save (guestfs_h *g);
2818 This writes all pending changes to disk.
2820 The flags which were passed to "guestfs_aug_init" affect exactly how
2822 files are saved.
2823 This function returns 0 on success or -1 on error.
2825 (Added in 0.7)
2827 guestfs_aug_set
2829 int
2830 guestfs_aug_set (guestfs_h *g,
2831 const char *augpath,
2832 const char *val);
2833 Set the value associated with "augpath" to "val".
2835 In the Augeas API, it is possible to clear a node by setting the value
2837 to NULL. Due to an oversight in the libguestfs API you cannot do that
2838 with this call. Instead you must use the "guestfs_aug_clear" call.
2839 This function returns 0 on success or -1 on error.
2841 (Added in 0.7)
2843 guestfs_aug_setm
2845 int
2846 guestfs_aug_setm (guestfs_h *g,
2847 const char *base,
2848 const char *sub,
2849 const char *val);
2850 Change multiple Augeas nodes in a single operation. "base" is an
2852 expression matching multiple nodes. "sub" is a path expression
2853 relative to "base". All nodes matching "base" are found, and then for
2854 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2855 which case the "base" nodes are modified.
2856 This returns the number of nodes modified.
2858 On error this function returns -1.
2860 (Added in 1.23.14)
2862 guestfs_aug_transform
2864 int
2865 guestfs_aug_transform (guestfs_h *g,
2866 const char *lens,
2867 const char *file,
2868 ...);
2869 You may supply a list of optional arguments to this call. Use zero or
2871 more of the following pairs of parameters, and terminate the list with
2872 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2873 GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2875 Add an Augeas transformation for the specified "lens" so it can handle
2877 "file".
2878 If "remove" is true ("false" by default), then the transformation is
2880 removed.
2881 This function returns 0 on success or -1 on error.
2883 (Added in 1.35.2)
2885 guestfs_aug_transform_va
2887 int
2888 guestfs_aug_transform_va (guestfs_h *g,
2889 const char *lens,
2890 const char *file,
2891 va_list args);
2892 This is the "va_list variant" of "guestfs_aug_transform".
2894 See "CALLS WITH OPTIONAL ARGUMENTS".
2896 guestfs_aug_transform_argv
2898 int
2899 guestfs_aug_transform_argv (guestfs_h *g,
2900 const char *lens,
2901 const char *file,
2902 const struct guestfs_aug_transform_argv *optargs);
2903 This is the "argv variant" of "guestfs_aug_transform".
2905 See "CALLS WITH OPTIONAL ARGUMENTS".
2907 guestfs_available
2909 int
2910 guestfs_available (guestfs_h *g,
2911 char *const *groups);
2912 This command is used to check the availability of some groups of
2914 functionality in the appliance, which not all builds of the libguestfs
2915 appliance will be able to provide.
2916 The libguestfs groups, and the functions that those groups correspond
2918 to, are listed in "AVAILABILITY". You can also fetch this list at
2919 runtime by calling "guestfs_available_all_groups".
2920 The argument "groups" is a list of group names, eg: "["inotify",
2922 "augeas"]" would check for the availability of the Linux inotify
2923 functions and Augeas (configuration file editing) functions.
2924 The command returns no error if all requested groups are available.
2926 It fails with an error if one or more of the requested groups is
2928 unavailable in the appliance.
2929 If an unknown group name is included in the list of groups then an
2931 error is always returned.
2932 Notes:
2934 · "guestfs_feature_available" is the same as this call, but with a
2936 slightly simpler to use API: that call returns a boolean true/false
2937 instead of throwing an error.
2938 · You must call "guestfs_launch" before calling this function.
2940 The reason is because we don't know what groups are supported by
2942 the appliance/daemon until it is running and can be queried.
2943 · If a group of functions is available, this does not necessarily
2945 mean that they will work. You still have to check for errors when
2946 calling individual API functions even if they are available.
2947 · It is usually the job of distro packagers to build complete
2949 functionality into the libguestfs appliance. Upstream libguestfs,
2950 if built from source with all requirements satisfied, will support
2951 everything.
2952 · This call was added in version 1.0.80. In previous versions of
2954 libguestfs all you could do would be to speculatively execute a
2955 command to find out if the daemon implemented it. See also
2956 "guestfs_version".
2957 See also "guestfs_filesystem_available".
2959 This function returns 0 on success or -1 on error.
2961 (Added in 1.0.80)
2963 guestfs_available_all_groups
2965 char **
2966 guestfs_available_all_groups (guestfs_h *g);
2967 This command returns a list of all optional groups that this daemon
2969 knows about. Note this returns both supported and unsupported groups.
2970 To find out which ones the daemon can actually support you have to call
2971 "guestfs_available" / "guestfs_feature_available" on each member of the
2972 returned list.
2973 See also "guestfs_available", "guestfs_feature_available" and
2975 "AVAILABILITY".
2976 This function returns a NULL-terminated array of strings (like
2978 environ(3)), or NULL if there was an error. The caller must free the
2979 strings and the array after use.
2980 (Added in 1.3.15)
2982 guestfs_base64_in
2984 int
2985 guestfs_base64_in (guestfs_h *g,
2986 const char *base64file,
2987 const char *filename);
2988 This command uploads base64-encoded data from "base64file" to filename.
2990 This function returns 0 on success or -1 on error.
2992 (Added in 1.3.5)
2994 guestfs_base64_out
2996 int
2997 guestfs_base64_out (guestfs_h *g,
2998 const char *filename,
2999 const char *base64file);
3000 This command downloads the contents of filename, writing it out to
3002 local file "base64file" encoded as base64.
3003 This function returns 0 on success or -1 on error.
3005 (Added in 1.3.5)
3007 guestfs_blkdiscard
3009 int
3010 guestfs_blkdiscard (guestfs_h *g,
3011 const char *device);
3012 This discards all blocks on the block device "device", giving the free
3014 space back to the host.
3015 This operation requires support in libguestfs, the host filesystem,
3017 qemu and the host kernel. If this support isn't present it may give an
3018 error or even appear to run but do nothing. You must also set the
3019 "discard" attribute on the underlying drive (see
3020 "guestfs_add_drive_opts").
3021 This function returns 0 on success or -1 on error.
3023 This function depends on the feature "blkdiscard". See also
3025 "guestfs_feature_available".
3026 (Added in 1.25.44)
3028 guestfs_blkdiscardzeroes
3030 int
3031 guestfs_blkdiscardzeroes (guestfs_h *g,
3032 const char *device);
3033 This call returns true if blocks on "device" that have been discarded
3035 by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
3036 when read the next time.
3037 If it returns false, then it may be that discarded blocks are read as
3039 stale or random data.
3040 This function returns a C truth value on success or -1 on error.
3042 This function depends on the feature "blkdiscardzeroes". See also
3044 "guestfs_feature_available".
3045 (Added in 1.25.44)
3047 guestfs_blkid
3049 char **
3050 guestfs_blkid (guestfs_h *g,
3051 const char *device);
3052 This command returns block device attributes for "device". The
3054 following fields are usually present in the returned hash. Other fields
3055 may also be present.
3056 "UUID"
3058 The uuid of this device.
3059 "LABEL"
3061 The label of this device.
3062 "VERSION"
3064 The version of blkid command.
3065 "TYPE"
3067 The filesystem type or RAID of this device.
3068 "USAGE"
3070 The usage of this device, for example "filesystem" or "raid".
3071 This function returns a NULL-terminated array of strings, or NULL if
3073 there was an error. The array of strings will always have length
3074 "2n+1", where "n" keys and values alternate, followed by the trailing
3075 NULL entry. The caller must free the strings and the array after use.
3076 (Added in 1.15.9)
3078 guestfs_blockdev_flushbufs
3080 int
3081 guestfs_blockdev_flushbufs (guestfs_h *g,
3082 const char *device);
3083 This tells the kernel to flush internal buffers associated with
3085 "device".
3086 This uses the blockdev(8) command.
3088 This function returns 0 on success or -1 on error.
3090 (Added in 1.9.3)
3092 guestfs_blockdev_getbsz
3094 int
3095 guestfs_blockdev_getbsz (guestfs_h *g,
3096 const char *device);
3097 This returns the block size of a device.
3099 Note: this is different from both size in blocks and filesystem block
3101 size. Also this setting is not really used by anything. You should
3102 probably not use it for anything. Filesystems have their own idea
3103 about what block size to choose.
3104 This uses the blockdev(8) command.
3106 On error this function returns -1.
3108 (Added in 1.9.3)
3110 guestfs_blockdev_getro
3112 int
3113 guestfs_blockdev_getro (guestfs_h *g,
3114 const char *device);
3115 Returns a boolean indicating if the block device is read-only (true if
3117 read-only, false if not).
3118 This uses the blockdev(8) command.
3120 This function returns a C truth value on success or -1 on error.
3122 (Added in 1.9.3)
3124 guestfs_blockdev_getsize64
3126 int64_t
3127 guestfs_blockdev_getsize64 (guestfs_h *g,
3128 const char *device);
3129 This returns the size of the device in bytes.
3131 See also "guestfs_blockdev_getsz".
3133 This uses the blockdev(8) command.
3135 On error this function returns -1.
3137 (Added in 1.9.3)
3139 guestfs_blockdev_getss
3141 int
3142 guestfs_blockdev_getss (guestfs_h *g,
3143 const char *device);
3144 This returns the size of sectors on a block device. Usually 512, but
3146 can be larger for modern devices.
3147 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
3149 for that).
3150 This uses the blockdev(8) command.
3152 On error this function returns -1.
3154 (Added in 1.9.3)
3156 guestfs_blockdev_getsz
3158 int64_t
3159 guestfs_blockdev_getsz (guestfs_h *g,
3160 const char *device);
3161 This returns the size of the device in units of 512-byte sectors (even
3163 if the sectorsize isn't 512 bytes ... weird).
3164 See also "guestfs_blockdev_getss" for the real sector size of the
3166 device, and "guestfs_blockdev_getsize64" for the more useful size in
3167 bytes.
3168 This uses the blockdev(8) command.
3170 On error this function returns -1.
3172 (Added in 1.9.3)
3174 guestfs_blockdev_rereadpt
3176 int
3177 guestfs_blockdev_rereadpt (guestfs_h *g,
3178 const char *device);
3179 Reread the partition table on "device".
3181 This uses the blockdev(8) command.
3183 This function returns 0 on success or -1 on error.
3185 (Added in 1.9.3)
3187 guestfs_blockdev_setbsz
3189 int
3190 guestfs_blockdev_setbsz (guestfs_h *g,
3191 const char *device,
3192 int blocksize);
3193 This function is deprecated. There is no replacement. Consult the API
3195 documentation in guestfs(3) for further information.
3196 Deprecated functions will not be removed from the API, but the fact
3198 that they are deprecated indicates that there are problems with correct
3199 use of these functions.
3200 This call does nothing and has never done anything because of a bug in
3202 blockdev. Do not use it.
3203 If you need to set the filesystem block size, use the "blocksize"
3205 option of "guestfs_mkfs".
3206 This function returns 0 on success or -1 on error.
3208 (Added in 1.9.3)
3210 guestfs_blockdev_setra
3212 int
3213 guestfs_blockdev_setra (guestfs_h *g,
3214 const char *device,
3215 int sectors);
3216 Set readahead (in 512-byte sectors) for the device.
3218 This uses the blockdev(8) command.
3220 This function returns 0 on success or -1 on error.
3222 (Added in 1.29.10)
3224 guestfs_blockdev_setro
3226 int
3227 guestfs_blockdev_setro (guestfs_h *g,
3228 const char *device);
3229 Sets the block device named "device" to read-only.
3231 This uses the blockdev(8) command.
3233 This function returns 0 on success or -1 on error.
3235 (Added in 1.9.3)
3237 guestfs_blockdev_setrw
3239 int
3240 guestfs_blockdev_setrw (guestfs_h *g,
3241 const char *device);
3242 Sets the block device named "device" to read-write.
3244 This uses the blockdev(8) command.
3246 This function returns 0 on success or -1 on error.
3248 (Added in 1.9.3)
3250 guestfs_btrfs_balance_cancel
3252 int
3253 guestfs_btrfs_balance_cancel (guestfs_h *g,
3254 const char *path);
3255 Cancel a running balance on a btrfs filesystem.
3257 This function returns 0 on success or -1 on error.
3259 This function depends on the feature "btrfs". See also
3261 "guestfs_feature_available".
3262 (Added in 1.29.22)
3264 guestfs_btrfs_balance_pause
3266 int
3267 guestfs_btrfs_balance_pause (guestfs_h *g,
3268 const char *path);
3269 Pause a running balance on a btrfs filesystem.
3271 This function returns 0 on success or -1 on error.
3273 This function depends on the feature "btrfs". See also
3275 "guestfs_feature_available".
3276 (Added in 1.29.22)
3278 guestfs_btrfs_balance_resume
3280 int
3281 guestfs_btrfs_balance_resume (guestfs_h *g,
3282 const char *path);
3283 Resume a paused balance on a btrfs filesystem.
3285 This function returns 0 on success or -1 on error.
3287 This function depends on the feature "btrfs". See also
3289 "guestfs_feature_available".
3290 (Added in 1.29.22)
3292 guestfs_btrfs_balance_status
3294 struct guestfs_btrfsbalance *
3295 guestfs_btrfs_balance_status (guestfs_h *g,
3296 const char *path);
3297 Show the status of a running or paused balance on a btrfs filesystem.
3299 This function returns a "struct guestfs_btrfsbalance *", or NULL if
3301 there was an error. The caller must call "guestfs_free_btrfsbalance"
3302 after use.
3303 This function depends on the feature "btrfs". See also
3305 "guestfs_feature_available".
3306 (Added in 1.29.26)
3308 guestfs_btrfs_device_add
3310 int
3311 guestfs_btrfs_device_add (guestfs_h *g,
3312 char *const *devices,
3313 const char *fs);
3314 Add the list of device(s) in "devices" to the btrfs filesystem mounted
3316 at "fs". If "devices" is an empty list, this does nothing.
3317 This function returns 0 on success or -1 on error.
3319 This function depends on the feature "btrfs". See also
3321 "guestfs_feature_available".
3322 (Added in 1.17.35)
3324 guestfs_btrfs_device_delete
3326 int
3327 guestfs_btrfs_device_delete (guestfs_h *g,
3328 char *const *devices,
3329 const char *fs);
3330 Remove the "devices" from the btrfs filesystem mounted at "fs". If
3332 "devices" is an empty list, this does nothing.
3333 This function returns 0 on success or -1 on error.
3335 This function depends on the feature "btrfs". See also
3337 "guestfs_feature_available".
3338 (Added in 1.17.35)
3340 guestfs_btrfs_filesystem_balance
3342 int
3343 guestfs_btrfs_filesystem_balance (guestfs_h *g,
3344 const char *fs);
3345 Balance the chunks in the btrfs filesystem mounted at "fs" across the
3347 underlying devices.
3348 This function returns 0 on success or -1 on error.
3350 This function depends on the feature "btrfs". See also
3352 "guestfs_feature_available".
3353 (Added in 1.17.35)
3355 guestfs_btrfs_filesystem_defragment
3357 int
3358 guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3359 const char *path,
3360 ...);
3361 You may supply a list of optional arguments to this call. Use zero or
3363 more of the following pairs of parameters, and terminate the list with
3364 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3365 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3367 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3368 Defragment a file or directory on a btrfs filesystem. compress is one
3370 of zlib or lzo.
3371 This function returns 0 on success or -1 on error.
3373 This function depends on the feature "btrfs". See also
3375 "guestfs_feature_available".
3376 (Added in 1.29.22)
3378 guestfs_btrfs_filesystem_defragment_va
3380 int
3381 guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3382 const char *path,
3383 va_list args);
3384 This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3386 See "CALLS WITH OPTIONAL ARGUMENTS".
3388 guestfs_btrfs_filesystem_defragment_argv
3390 int
3391 guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3392 const char *path,
3393 const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3394 This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3396 See "CALLS WITH OPTIONAL ARGUMENTS".
3398 guestfs_btrfs_filesystem_resize
3400 int
3401 guestfs_btrfs_filesystem_resize (guestfs_h *g,
3402 const char *mountpoint,
3403 ...);
3404 You may supply a list of optional arguments to this call. Use zero or
3406 more of the following pairs of parameters, and terminate the list with
3407 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3408 GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3410 This command resizes a btrfs filesystem.
3412 Note that unlike other resize calls, the filesystem has to be mounted
3414 and the parameter is the mountpoint not the device (this is a
3415 requirement of btrfs itself).
3416 The optional parameters are:
3418 "size"
3420 The new size (in bytes) of the filesystem. If omitted, the
3421 filesystem is resized to the maximum size.
3422 See also btrfs(8).
3424 This function returns 0 on success or -1 on error.
3426 This function depends on the feature "btrfs". See also
3428 "guestfs_feature_available".
3429 (Added in 1.11.17)
3431 guestfs_btrfs_filesystem_resize_va
3433 int
3434 guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3435 const char *mountpoint,
3436 va_list args);
3437 This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3439 See "CALLS WITH OPTIONAL ARGUMENTS".
3441 guestfs_btrfs_filesystem_resize_argv
3443 int
3444 guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3445 const char *mountpoint,
3446 const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3447 This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3449 See "CALLS WITH OPTIONAL ARGUMENTS".
3451 guestfs_btrfs_filesystem_show
3453 char **
3454 guestfs_btrfs_filesystem_show (guestfs_h *g,
3455 const char *device);
3456 Show all the devices where the filesystems in "device" is spanned over.
3458 If not all the devices for the filesystems are present, then this
3460 function fails and the "errno" is set to "ENODEV".
3461 This function returns a NULL-terminated array of strings (like
3463 environ(3)), or NULL if there was an error. The caller must free the
3464 strings and the array after use.
3465 This function depends on the feature "btrfs". See also
3467 "guestfs_feature_available".
3468 (Added in 1.33.29)
3470 guestfs_btrfs_filesystem_sync
3472 int
3473 guestfs_btrfs_filesystem_sync (guestfs_h *g,
3474 const char *fs);
3475 Force sync on the btrfs filesystem mounted at "fs".
3477 This function returns 0 on success or -1 on error.
3479 This function depends on the feature "btrfs". See also
3481 "guestfs_feature_available".
3482 (Added in 1.17.35)
3484 guestfs_btrfs_fsck
3486 int
3487 guestfs_btrfs_fsck (guestfs_h *g,
3488 const char *device,
3489 ...);
3490 You may supply a list of optional arguments to this call. Use zero or
3492 more of the following pairs of parameters, and terminate the list with
3493 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3494 GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3496 GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3497 Used to check a btrfs filesystem, "device" is the device file where the
3499 filesystem is stored.
3500 This function returns 0 on success or -1 on error.
3502 This function depends on the feature "btrfs". See also
3504 "guestfs_feature_available".
3505 (Added in 1.17.43)
3507 guestfs_btrfs_fsck_va
3509 int
3510 guestfs_btrfs_fsck_va (guestfs_h *g,
3511 const char *device,
3512 va_list args);
3513 This is the "va_list variant" of "guestfs_btrfs_fsck".
3515 See "CALLS WITH OPTIONAL ARGUMENTS".
3517 guestfs_btrfs_fsck_argv
3519 int
3520 guestfs_btrfs_fsck_argv (guestfs_h *g,
3521 const char *device,
3522 const struct guestfs_btrfs_fsck_argv *optargs);
3523 This is the "argv variant" of "guestfs_btrfs_fsck".
3525 See "CALLS WITH OPTIONAL ARGUMENTS".
3527 guestfs_btrfs_image
3529 int
3530 guestfs_btrfs_image (guestfs_h *g,
3531 char *const *source,
3532 const char *image,
3533 ...);
3534 You may supply a list of optional arguments to this call. Use zero or
3536 more of the following pairs of parameters, and terminate the list with
3537 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3538 GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3540 This is used to create an image of a btrfs filesystem. All data will
3542 be zeroed, but metadata and the like is preserved.
3543 This function returns 0 on success or -1 on error.
3545 This function depends on the feature "btrfs". See also
3547 "guestfs_feature_available".
3548 (Added in 1.29.32)
3550 guestfs_btrfs_image_va
3552 int
3553 guestfs_btrfs_image_va (guestfs_h *g,
3554 char *const *source,
3555 const char *image,
3556 va_list args);
3557 This is the "va_list variant" of "guestfs_btrfs_image".
3559 See "CALLS WITH OPTIONAL ARGUMENTS".
3561 guestfs_btrfs_image_argv
3563 int
3564 guestfs_btrfs_image_argv (guestfs_h *g,
3565 char *const *source,
3566 const char *image,
3567 const struct guestfs_btrfs_image_argv *optargs);
3568 This is the "argv variant" of "guestfs_btrfs_image".
3570 See "CALLS WITH OPTIONAL ARGUMENTS".
3572 guestfs_btrfs_qgroup_assign
3574 int
3575 guestfs_btrfs_qgroup_assign (guestfs_h *g,
3576 const char *src,
3577 const char *dst,
3578 const char *path);
3579 Add qgroup "src" to parent qgroup "dst". This command can group several
3581 qgroups into a parent qgroup to share common limit.
3582 This function returns 0 on success or -1 on error.
3584 This function depends on the feature "btrfs". See also
3586 "guestfs_feature_available".
3587 (Added in 1.29.17)
3589 guestfs_btrfs_qgroup_create
3591 int
3592 guestfs_btrfs_qgroup_create (guestfs_h *g,
3593 const char *qgroupid,
3594 const char *subvolume);
3595 Create a quota group (qgroup) for subvolume at "subvolume".
3597 This function returns 0 on success or -1 on error.
3599 This function depends on the feature "btrfs". See also
3601 "guestfs_feature_available".
3602 (Added in 1.29.17)
3604 guestfs_btrfs_qgroup_destroy
3606 int
3607 guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3608 const char *qgroupid,
3609 const char *subvolume);
3610 Destroy a quota group.
3612 This function returns 0 on success or -1 on error.
3614 This function depends on the feature "btrfs". See also
3616 "guestfs_feature_available".
3617 (Added in 1.29.17)
3619 guestfs_btrfs_qgroup_limit
3621 int
3622 guestfs_btrfs_qgroup_limit (guestfs_h *g,
3623 const char *subvolume,
3624 int64_t size);
3625 Limit the size of the subvolume with path "subvolume".
3627 This function returns 0 on success or -1 on error.
3629 This function depends on the feature "btrfs". See also
3631 "guestfs_feature_available".
3632 (Added in 1.29.17)
3634 guestfs_btrfs_qgroup_remove
3636 int
3637 guestfs_btrfs_qgroup_remove (guestfs_h *g,
3638 const char *src,
3639 const char *dst,
3640 const char *path);
3641 Remove qgroup "src" from the parent qgroup "dst".
3643 This function returns 0 on success or -1 on error.
3645 This function depends on the feature "btrfs". See also
3647 "guestfs_feature_available".
3648 (Added in 1.29.17)
3650 guestfs_btrfs_qgroup_show
3652 struct guestfs_btrfsqgroup_list *
3653 guestfs_btrfs_qgroup_show (guestfs_h *g,
3654 const char *path);
3655 Show all subvolume quota groups in a btrfs filesystem, including their
3657 usages.
3658 This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3660 there was an error. The caller must call
3661 "guestfs_free_btrfsqgroup_list" after use.
3662 This function depends on the feature "btrfs". See also
3664 "guestfs_feature_available".
3665 (Added in 1.29.17)
3667 guestfs_btrfs_quota_enable
3669 int
3670 guestfs_btrfs_quota_enable (guestfs_h *g,
3671 const char *fs,
3672 int enable);
3673 Enable or disable subvolume quota support for filesystem which contains
3675 "path".
3676 This function returns 0 on success or -1 on error.
3678 This function depends on the feature "btrfs". See also
3680 "guestfs_feature_available".
3681 (Added in 1.29.17)
3683 guestfs_btrfs_quota_rescan
3685 int
3686 guestfs_btrfs_quota_rescan (guestfs_h *g,
3687 const char *fs);
3688 Trash all qgroup numbers and scan the metadata again with the current
3690 config.
3691 This function returns 0 on success or -1 on error.
3693 This function depends on the feature "btrfs". See also
3695 "guestfs_feature_available".
3696 (Added in 1.29.17)
3698 guestfs_btrfs_replace
3700 int
3701 guestfs_btrfs_replace (guestfs_h *g,
3702 const char *srcdev,
3703 const char *targetdev,
3704 const char *mntpoint);
3705 Replace device of a btrfs filesystem. On a live filesystem, duplicate
3707 the data to the target device which is currently stored on the source
3708 device. After completion of the operation, the source device is wiped
3709 out and removed from the filesystem.
3710 The "targetdev" needs to be same size or larger than the "srcdev".
3712 Devices which are currently mounted are never allowed to be used as the
3713 "targetdev".
3714 This function returns 0 on success or -1 on error.
3716 This function depends on the feature "btrfs". See also
3718 "guestfs_feature_available".
3719 (Added in 1.29.48)
3721 guestfs_btrfs_rescue_chunk_recover
3723 int
3724 guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3725 const char *device);
3726 Recover the chunk tree of btrfs filesystem by scanning the devices one
3728 by one.
3729 This function returns 0 on success or -1 on error.
3731 This function depends on the feature "btrfs". See also
3733 "guestfs_feature_available".
3734 (Added in 1.29.22)
3736 guestfs_btrfs_rescue_super_recover
3738 int
3739 guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3740 const char *device);
3741 Recover bad superblocks from good copies.
3743 This function returns 0 on success or -1 on error.
3745 This function depends on the feature "btrfs". See also
3747 "guestfs_feature_available".
3748 (Added in 1.29.22)
3750 guestfs_btrfs_scrub_cancel
3752 int
3753 guestfs_btrfs_scrub_cancel (guestfs_h *g,
3754 const char *path);
3755 Cancel a running scrub on a btrfs filesystem.
3757 This function returns 0 on success or -1 on error.
3759 This function depends on the feature "btrfs". See also
3761 "guestfs_feature_available".
3762 (Added in 1.29.22)
3764 guestfs_btrfs_scrub_resume
3766 int
3767 guestfs_btrfs_scrub_resume (guestfs_h *g,
3768 const char *path);
3769 Resume a previously canceled or interrupted scrub on a btrfs
3771 filesystem.
3772 This function returns 0 on success or -1 on error.
3774 This function depends on the feature "btrfs". See also
3776 "guestfs_feature_available".
3777 (Added in 1.29.22)
3779 guestfs_btrfs_scrub_start
3781 int
3782 guestfs_btrfs_scrub_start (guestfs_h *g,
3783 const char *path);
3784 Reads all the data and metadata on the filesystem, and uses checksums
3786 and the duplicate copies from RAID storage to identify and repair any
3787 corrupt data.
3788 This function returns 0 on success or -1 on error.
3790 This function depends on the feature "btrfs". See also
3792 "guestfs_feature_available".
3793 (Added in 1.29.22)
3795 guestfs_btrfs_scrub_status
3797 struct guestfs_btrfsscrub *
3798 guestfs_btrfs_scrub_status (guestfs_h *g,
3799 const char *path);
3800 Show status of running or finished scrub on a btrfs filesystem.
3802 This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3804 was an error. The caller must call "guestfs_free_btrfsscrub" after
3805 use.
3806 This function depends on the feature "btrfs". See also
3808 "guestfs_feature_available".
3809 (Added in 1.29.26)
3811 guestfs_btrfs_set_seeding
3813 int
3814 guestfs_btrfs_set_seeding (guestfs_h *g,
3815 const char *device,
3816 int seeding);
3817 Enable or disable the seeding feature of a device that contains a btrfs
3819 filesystem.
3820 This function returns 0 on success or -1 on error.
3822 This function depends on the feature "btrfs". See also
3824 "guestfs_feature_available".
3825 (Added in 1.17.43)
3827 guestfs_btrfs_subvolume_create
3829 int
3830 guestfs_btrfs_subvolume_create (guestfs_h *g,
3831 const char *dest);
3832 This function is provided for backwards compatibility with earlier
3834 versions of libguestfs. It simply calls
3835 "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3836 (Added in 1.17.35)
3838 guestfs_btrfs_subvolume_create_opts
3840 int
3841 guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3842 const char *dest,
3843 ...);
3844 You may supply a list of optional arguments to this call. Use zero or
3846 more of the following pairs of parameters, and terminate the list with
3847 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3848 GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3850 Create a btrfs subvolume. The "dest" argument is the destination
3852 directory and the name of the subvolume, in the form
3853 /path/to/dest/name. The optional parameter "qgroupid" represents the
3854 qgroup which the newly created subvolume will be added to.
3855 This function returns 0 on success or -1 on error.
3857 This function depends on the feature "btrfs". See also
3859 "guestfs_feature_available".
3860 (Added in 1.17.35)
3862 guestfs_btrfs_subvolume_create_opts_va
3864 int
3865 guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3866 const char *dest,
3867 va_list args);
3868 This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3870 See "CALLS WITH OPTIONAL ARGUMENTS".
3872 guestfs_btrfs_subvolume_create_opts_argv
3874 int
3875 guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3876 const char *dest,
3877 const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3878 This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3880 See "CALLS WITH OPTIONAL ARGUMENTS".
3882 guestfs_btrfs_subvolume_delete
3884 int
3885 guestfs_btrfs_subvolume_delete (guestfs_h *g,
3886 const char *subvolume);
3887 Delete the named btrfs subvolume or snapshot.
3889 This function returns 0 on success or -1 on error.
3891 This function depends on the feature "btrfs". See also
3893 "guestfs_feature_available".
3894 (Added in 1.17.35)
3896 guestfs_btrfs_subvolume_get_default
3898 int64_t
3899 guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3900 const char *fs);
3901 Get the default subvolume or snapshot of a filesystem mounted at
3903 "mountpoint".
3904 On error this function returns -1.
3906 This function depends on the feature "btrfs". See also
3908 "guestfs_feature_available".
3909 (Added in 1.29.17)
3911 guestfs_btrfs_subvolume_list
3913 struct guestfs_btrfssubvolume_list *
3914 guestfs_btrfs_subvolume_list (guestfs_h *g,
3915 const char *fs);
3916 List the btrfs snapshots and subvolumes of the btrfs filesystem which
3918 is mounted at "fs".
3919 This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3921 if there was an error. The caller must call
3922 "guestfs_free_btrfssubvolume_list" after use.
3923 This function depends on the feature "btrfs". See also
3925 "guestfs_feature_available".
3926 (Added in 1.17.35)
3928 guestfs_btrfs_subvolume_set_default
3930 int
3931 guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3932 int64_t id,
3933 const char *fs);
3934 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3936 default. See "guestfs_btrfs_subvolume_list" to get a list of
3937 subvolumes.
3938 This function returns 0 on success or -1 on error.
3940 This function depends on the feature "btrfs". See also
3942 "guestfs_feature_available".
3943 (Added in 1.17.35)
3945 guestfs_btrfs_subvolume_show
3947 char **
3948 guestfs_btrfs_subvolume_show (guestfs_h *g,
3949 const char *subvolume);
3950 Return detailed information of the subvolume.
3952 This function returns a NULL-terminated array of strings, or NULL if
3954 there was an error. The array of strings will always have length
3955 "2n+1", where "n" keys and values alternate, followed by the trailing
3956 NULL entry. The caller must free the strings and the array after use.
3957 This function depends on the feature "btrfs". See also
3959 "guestfs_feature_available".
3960 (Added in 1.29.17)
3962 guestfs_btrfs_subvolume_snapshot
3964 int
3965 guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3966 const char *source,
3967 const char *dest);
3968 This function is provided for backwards compatibility with earlier
3970 versions of libguestfs. It simply calls
3971 "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3972 (Added in 1.17.35)
3974 guestfs_btrfs_subvolume_snapshot_opts
3976 int
3977 guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3978 const char *source,
3979 const char *dest,
3980 ...);
3981 You may supply a list of optional arguments to this call. Use zero or
3983 more of the following pairs of parameters, and terminate the list with
3984 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3985 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3987 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3988 Create a snapshot of the btrfs subvolume "source". The "dest" argument
3990 is the destination directory and the name of the snapshot, in the form
3991 /path/to/dest/name. By default the newly created snapshot is writable,
3992 if the value of optional parameter "ro" is true, then a readonly
3993 snapshot is created. The optional parameter "qgroupid" represents the
3994 qgroup which the newly created snapshot will be added to.
3995 This function returns 0 on success or -1 on error.
3997 This function depends on the feature "btrfs". See also
3999 "guestfs_feature_available".
4000 (Added in 1.17.35)
4002 guestfs_btrfs_subvolume_snapshot_opts_va
4004 int
4005 guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
4006 const char *source,
4007 const char *dest,
4008 va_list args);
4009 This is the "va_list variant" of
4011 "guestfs_btrfs_subvolume_snapshot_opts".
4012 See "CALLS WITH OPTIONAL ARGUMENTS".
4014 guestfs_btrfs_subvolume_snapshot_opts_argv
4016 int
4017 guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
4018 const char *source,
4019 const char *dest,
4020 const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
4021 This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
4023 See "CALLS WITH OPTIONAL ARGUMENTS".
4025 guestfs_btrfstune_enable_extended_inode_refs
4027 int
4028 guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
4029 const char *device);
4030 This will Enable extended inode refs.
4032 This function returns 0 on success or -1 on error.
4034 This function depends on the feature "btrfs". See also
4036 "guestfs_feature_available".
4037 (Added in 1.29.29)
4039 guestfs_btrfstune_enable_skinny_metadata_extent_refs
4041 int
4042 guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
4043 const char *device);
4044 This enable skinny metadata extent refs.
4046 This function returns 0 on success or -1 on error.
4048 This function depends on the feature "btrfs". See also
4050 "guestfs_feature_available".
4051 (Added in 1.29.29)
4053 guestfs_btrfstune_seeding
4055 int
4056 guestfs_btrfstune_seeding (guestfs_h *g,
4057 const char *device,
4058 int seeding);
4059 Enable seeding of a btrfs device, this will force a fs readonly so that
4061 you can use it to build other filesystems.
4062 This function returns 0 on success or -1 on error.
4064 This function depends on the feature "btrfs". See also
4066 "guestfs_feature_available".
4067 (Added in 1.29.29)
4069 guestfs_c_pointer
4071 int64_t
4072 guestfs_c_pointer (guestfs_h *g);
4073 In non-C language bindings, this allows you to retrieve the underlying
4075 C pointer to the handle (ie. "guestfs_h *"). The purpose of this is to
4076 allow other libraries to interwork with libguestfs.
4077 On error this function returns -1.
4079 (Added in 1.29.17)
4081 guestfs_canonical_device_name
4083 char *
4084 guestfs_canonical_device_name (guestfs_h *g,
4085 const char *device);
4086 This utility function is useful when displaying device names to the
4088 user. It takes a number of irregular device names and returns them in
4089 a consistent format:
4090 /dev/hdX
4092 /dev/vdX
4093 These are returned as /dev/sdX. Note this works for device names
4094 and partition names. This is approximately the reverse of the
4095 algorithm described in "BLOCK DEVICE NAMING".
4096 /dev/mapper/VG-LV
4098 /dev/dm-N
4099 Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
4100 Other strings are returned unmodified.
4102 This function returns a string, or NULL on error. The caller must free
4104 the returned string after use.
4105 (Added in 1.19.7)
4107 guestfs_cap_get_file
4109 char *
4110 guestfs_cap_get_file (guestfs_h *g,
4111 const char *path);
4112 This function returns the Linux capabilities attached to "path". The
4114 capabilities set is returned in text form (see cap_to_text(3)).
4115 If no capabilities are attached to a file, an empty string is returned.
4117 This function returns a string, or NULL on error. The caller must free
4119 the returned string after use.
4120 This function depends on the feature "linuxcaps". See also
4122 "guestfs_feature_available".
4123 (Added in 1.19.63)
4125 guestfs_cap_set_file
4127 int
4128 guestfs_cap_set_file (guestfs_h *g,
4129 const char *path,
4130 const char *cap);
4131 This function sets the Linux capabilities attached to "path". The
4133 capabilities set "cap" should be passed in text form (see
4134 cap_from_text(3)).
4135 This function returns 0 on success or -1 on error.
4137 This function depends on the feature "linuxcaps". See also
4139 "guestfs_feature_available".
4140 (Added in 1.19.63)
4142 guestfs_case_sensitive_path
4144 char *
4145 guestfs_case_sensitive_path (guestfs_h *g,
4146 const char *path);
4147 This can be used to resolve case insensitive paths on a filesystem
4149 which is case sensitive. The use case is to resolve paths which you
4150 have read from Windows configuration files or the Windows Registry, to
4151 the true path.
4152 The command handles a peculiarity of the Linux ntfs-3g filesystem
4154 driver (and probably others), which is that although the underlying
4155 filesystem is case-insensitive, the driver exports the filesystem to
4156 Linux as case-sensitive.
4157 One consequence of this is that special directories such as C:\windows
4159 may appear as /WINDOWS or /windows (or other things) depending on the
4160 precise details of how they were created. In Windows itself this would
4161 not be a problem.
4162 Bug or feature? You decide:
4164 https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4165 "guestfs_case_sensitive_path" attempts to resolve the true case of each
4167 element in the path. It will return a resolved path if either the full
4168 path or its parent directory exists. If the parent directory exists but
4169 the full path does not, the case of the parent directory will be
4170 correctly resolved, and the remainder appended unmodified. For example,
4171 if the file "/Windows/System32/netkvm.sys" exists:
4172 "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4174 "Windows/System32/netkvm.sys"
4175 "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4177 "Windows/System32/NoSuchFile"
4178 "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4180 ERROR
4181 Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4183 cannot be used to check for the existence of a file.
4184 Note: This function does not handle drive names, backslashes etc.
4186 See also "guestfs_realpath".
4188 This function returns a string, or NULL on error. The caller must free
4190 the returned string after use.
4191 (Added in 1.0.75)
4193 guestfs_cat
4195 char *
4196 guestfs_cat (guestfs_h *g,
4197 const char *path);
4198 Return the contents of the file named "path".
4200 Because, in C, this function returns a "char *", there is no way to
4202 differentiate between a "\0" character in a file and end of string. To
4203 handle binary files, use the "guestfs_read_file" or "guestfs_download"
4204 functions.
4205 This function returns a string, or NULL on error. The caller must free
4207 the returned string after use.
4208 (Added in 0.4)
4210 guestfs_checksum
4212 char *
4213 guestfs_checksum (guestfs_h *g,
4214 const char *csumtype,
4215 const char *path);
4216 This call computes the MD5, SHAx or CRC checksum of the file named
4218 "path".
4219 The type of checksum to compute is given by the "csumtype" parameter
4221 which must have one of the following values:
4222 "crc"
4224 Compute the cyclic redundancy check (CRC) specified by POSIX for
4225 the "cksum" command.
4226 "md5"
4228 Compute the MD5 hash (using the md5sum(1) program).
4229 "sha1"
4231 Compute the SHA1 hash (using the sha1sum(1) program).
4232 "sha224"
4234 Compute the SHA224 hash (using the sha224sum(1) program).
4235 "sha256"
4237 Compute the SHA256 hash (using the sha256sum(1) program).
4238 "sha384"
4240 Compute the SHA384 hash (using the sha384sum(1) program).
4241 "sha512"
4243 Compute the SHA512 hash (using the sha512sum(1) program).
4244 The checksum is returned as a printable string.
4246 To get the checksum for a device, use "guestfs_checksum_device".
4248 To get the checksums for many files, use "guestfs_checksums_out".
4250 This function returns a string, or NULL on error. The caller must free
4252 the returned string after use.
4253 (Added in 1.0.2)
4255 guestfs_checksum_device
4257 char *
4258 guestfs_checksum_device (guestfs_h *g,
4259 const char *csumtype,
4260 const char *device);
4261 This call computes the MD5, SHAx or CRC checksum of the contents of the
4263 device named "device". For the types of checksums supported see the
4264 "guestfs_checksum" command.
4265 This function returns a string, or NULL on error. The caller must free
4267 the returned string after use.
4268 (Added in 1.3.2)
4270 guestfs_checksums_out
4272 int
4273 guestfs_checksums_out (guestfs_h *g,
4274 const char *csumtype,
4275 const char *directory,
4276 const char *sumsfile);
4277 This command computes the checksums of all regular files in directory
4279 and then emits a list of those checksums to the local output file
4280 "sumsfile".
4281 This can be used for verifying the integrity of a virtual machine.
4283 However to be properly secure you should pay attention to the output of
4284 the checksum command (it uses the ones from GNU coreutils). In
4285 particular when the filename is not printable, coreutils uses a special
4286 backslash syntax. For more information, see the GNU coreutils info
4287 file.
4288 This function returns 0 on success or -1 on error.
4290 (Added in 1.3.7)
4292 guestfs_chmod
4294 int
4295 guestfs_chmod (guestfs_h *g,
4296 int mode,
4297 const char *path);
4298 Change the mode (permissions) of "path" to "mode". Only numeric modes
4300 are supported.
4301 Note: When using this command from guestfish, "mode" by default would
4303 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4304 700.
4305 The mode actually set is affected by the umask.
4307 This function returns 0 on success or -1 on error.
4309 (Added in 0.8)
4311 guestfs_chown
4313 int
4314 guestfs_chown (guestfs_h *g,
4315 int owner,
4316 int group,
4317 const char *path);
4318 Change the file owner to "owner" and group to "group".
4320 Only numeric uid and gid are supported. If you want to use names, you
4322 will need to locate and parse the password file yourself (Augeas
4323 support makes this relatively easy).
4324 This function returns 0 on success or -1 on error.
4326 (Added in 0.8)
4328 guestfs_clear_backend_setting
4330 int
4331 guestfs_clear_backend_setting (guestfs_h *g,
4332 const char *name);
4333 If there is a backend setting string matching "name" or beginning with
4335 "name=", then that string is removed from the backend settings.
4336 This call returns the number of strings which were removed (which may
4338 be 0, 1 or greater than 1).
4339 See "BACKEND", "BACKEND SETTINGS".
4341 On error this function returns -1.
4343 (Added in 1.27.2)
4345 guestfs_command
4347 char *
4348 guestfs_command (guestfs_h *g,
4349 char *const *arguments);
4350 This call runs a command from the guest filesystem. The filesystem
4352 must be mounted, and must contain a compatible operating system (ie.
4353 something Linux, with the same or compatible processor architecture).
4354 The single parameter is an argv-style list of arguments. The first
4356 element is the name of the program to run. Subsequent elements are
4357 parameters. The list must be non-empty (ie. must contain a program
4358 name). Note that the command runs directly, and is not invoked via the
4359 shell (see "guestfs_sh").
4360 The return value is anything printed to stdout by the command.
4362 If the command returns a non-zero exit status, then this function
4364 returns an error message. The error message string is the content of
4365 stderr from the command.
4366 The $PATH environment variable will contain at least /usr/bin and /bin.
4368 If you require a program from another location, you should provide the
4369 full path in the first parameter.
4370 Shared libraries and data files required by the program must be
4372 available on filesystems which are mounted in the correct places. It
4373 is the caller’s responsibility to ensure all filesystems that are
4374 needed are mounted at the right locations.
4375 This function returns a string, or NULL on error. The caller must free
4377 the returned string after use.
4378 Because of the message protocol, there is a transfer limit of somewhere
4380 between 2MB and 4MB. See "PROTOCOL LIMITS".
4381 (Added in 1.9.1)
4383 guestfs_command_lines
4385 char **
4386 guestfs_command_lines (guestfs_h *g,
4387 char *const *arguments);
4388 This is the same as "guestfs_command", but splits the result into a
4390 list of lines.
4391 See also: "guestfs_sh_lines"
4393 This function returns a NULL-terminated array of strings (like
4395 environ(3)), or NULL if there was an error. The caller must free the
4396 strings and the array after use.
4397 Because of the message protocol, there is a transfer limit of somewhere
4399 between 2MB and 4MB. See "PROTOCOL LIMITS".
4400 (Added in 1.9.1)
4402 guestfs_compress_device_out
4404 int
4405 guestfs_compress_device_out (guestfs_h *g,
4406 const char *ctype,
4407 const char *device,
4408 const char *zdevice,
4409 ...);
4410 You may supply a list of optional arguments to this call. Use zero or
4412 more of the following pairs of parameters, and terminate the list with
4413 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4414 GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4416 This command compresses "device" and writes it out to the local file
4418 "zdevice".
4419 The "ctype" and optional "level" parameters have the same meaning as in
4421 "guestfs_compress_out".
4422 This function returns 0 on success or -1 on error.
4424 (Added in 1.13.15)
4426 guestfs_compress_device_out_va
4428 int
4429 guestfs_compress_device_out_va (guestfs_h *g,
4430 const char *ctype,
4431 const char *device,
4432 const char *zdevice,
4433 va_list args);
4434 This is the "va_list variant" of "guestfs_compress_device_out".
4436 See "CALLS WITH OPTIONAL ARGUMENTS".
4438 guestfs_compress_device_out_argv
4440 int
4441 guestfs_compress_device_out_argv (guestfs_h *g,
4442 const char *ctype,
4443 const char *device,
4444 const char *zdevice,
4445 const struct guestfs_compress_device_out_argv *optargs);
4446 This is the "argv variant" of "guestfs_compress_device_out".
4448 See "CALLS WITH OPTIONAL ARGUMENTS".
4450 guestfs_compress_out
4452 int
4453 guestfs_compress_out (guestfs_h *g,
4454 const char *ctype,
4455 const char *file,
4456 const char *zfile,
4457 ...);
4458 You may supply a list of optional arguments to this call. Use zero or
4460 more of the following pairs of parameters, and terminate the list with
4461 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4462 GUESTFS_COMPRESS_OUT_LEVEL, int level,
4464 This command compresses file and writes it out to the local file zfile.
4466 The compression program used is controlled by the "ctype" parameter.
4468 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4469 Some compression types may not be supported by particular builds of
4470 libguestfs, in which case you will get an error containing the
4471 substring "not supported".
4472 The optional "level" parameter controls compression level. The meaning
4474 and default for this parameter depends on the compression program being
4475 used.
4476 This function returns 0 on success or -1 on error.
4478 (Added in 1.13.15)
4480 guestfs_compress_out_va
4482 int
4483 guestfs_compress_out_va (guestfs_h *g,
4484 const char *ctype,
4485 const char *file,
4486 const char *zfile,
4487 va_list args);
4488 This is the "va_list variant" of "guestfs_compress_out".
4490 See "CALLS WITH OPTIONAL ARGUMENTS".
4492 guestfs_compress_out_argv
4494 int
4495 guestfs_compress_out_argv (guestfs_h *g,
4496 const char *ctype,
4497 const char *file,
4498 const char *zfile,
4499 const struct guestfs_compress_out_argv *optargs);
4500 This is the "argv variant" of "guestfs_compress_out".
4502 See "CALLS WITH OPTIONAL ARGUMENTS".
4504 guestfs_config
4506 int
4507 guestfs_config (guestfs_h *g,
4508 const char *hvparam,
4509 const char *hvvalue);
4510 This can be used to add arbitrary hypervisor parameters of the form
4512 -param value. Actually it’s not quite arbitrary - we prevent you from
4513 setting some parameters which would interfere with parameters that we
4514 use.
4515 The first character of "hvparam" string must be a "-" (dash).
4517 "hvvalue" can be NULL.
4519 This function returns 0 on success or -1 on error.
4521 (Added in 0.3)
4523 guestfs_copy_attributes
4525 int
4526 guestfs_copy_attributes (guestfs_h *g,
4527 const char *src,
4528 const char *dest,
4529 ...);
4530 You may supply a list of optional arguments to this call. Use zero or
4532 more of the following pairs of parameters, and terminate the list with
4533 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4534 GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4536 GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4537 GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4538 GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4539 Copy the attributes of a path (which can be a file or a directory) to
4541 another path.
4542 By default no attribute is copied, so make sure to specify any (or
4544 "all" to copy everything).
4545 The optional arguments specify which attributes can be copied:
4547 "mode"
4549 Copy part of the file mode from "source" to "destination". Only the
4550 UNIX permissions and the sticky/setuid/setgid bits can be copied.
4551 "xattributes"
4553 Copy the Linux extended attributes (xattrs) from "source" to
4554 "destination". This flag does nothing if the linuxxattrs feature
4555 is not available (see "guestfs_feature_available").
4556 "ownership"
4558 Copy the owner uid and the group gid of "source" to "destination".
4559 "all"
4561 Copy all the attributes from "source" to "destination". Enabling it
4562 enables all the other flags, if they are not specified already.
4563 This function returns 0 on success or -1 on error.
4565 (Added in 1.25.21)
4567 guestfs_copy_attributes_va
4569 int
4570 guestfs_copy_attributes_va (guestfs_h *g,
4571 const char *src,
4572 const char *dest,
4573 va_list args);
4574 This is the "va_list variant" of "guestfs_copy_attributes".
4576 See "CALLS WITH OPTIONAL ARGUMENTS".
4578 guestfs_copy_attributes_argv
4580 int
4581 guestfs_copy_attributes_argv (guestfs_h *g,
4582 const char *src,
4583 const char *dest,
4584 const struct guestfs_copy_attributes_argv *optargs);
4585 This is the "argv variant" of "guestfs_copy_attributes".
4587 See "CALLS WITH OPTIONAL ARGUMENTS".
4589 guestfs_copy_device_to_device
4591 int
4592 guestfs_copy_device_to_device (guestfs_h *g,
4593 const char *src,
4594 const char *dest,
4595 ...);
4596 You may supply a list of optional arguments to this call. Use zero or
4598 more of the following pairs of parameters, and terminate the list with
4599 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4600 GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4602 GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4603 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4604 GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4605 GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4606 The four calls "guestfs_copy_device_to_device",
4608 "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4609 "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4610 a destination (device|file).
4611 Partial copies can be made since you can specify optionally the source
4613 offset, destination offset and size to copy. These values are all
4614 specified in bytes. If not given, the offsets both default to zero,
4615 and the size defaults to copying as much as possible until we hit the
4616 end of the source.
4617 The source and destination may be the same object. However overlapping
4619 regions may not be copied correctly.
4620 If the destination is a file, it is created if required. If the
4622 destination file is not large enough, it is extended.
4623 If the destination is a file and the "append" flag is not set, then the
4625 destination file is truncated. If the "append" flag is set, then the
4626 copy appends to the destination file. The "append" flag currently
4627 cannot be set for devices.
4628 If the "sparse" flag is true then the call avoids writing blocks that
4630 contain only zeroes, which can help in some situations where the
4631 backing disk is thin-provisioned. Note that unless the target is
4632 already zeroed, using this option will result in incorrect copying.
4633 This function returns 0 on success or -1 on error.
4635 This long-running command can generate progress notification messages
4637 so that the caller can display a progress bar or indicator. To receive
4638 these messages, the caller must register a progress event callback.
4639 See "GUESTFS_EVENT_PROGRESS".
4640 (Added in 1.13.25)
4642 guestfs_copy_device_to_device_va
4644 int
4645 guestfs_copy_device_to_device_va (guestfs_h *g,
4646 const char *src,
4647 const char *dest,
4648 va_list args);
4649 This is the "va_list variant" of "guestfs_copy_device_to_device".
4651 See "CALLS WITH OPTIONAL ARGUMENTS".
4653 guestfs_copy_device_to_device_argv
4655 int
4656 guestfs_copy_device_to_device_argv (guestfs_h *g,
4657 const char *src,
4658 const char *dest,
4659 const struct guestfs_copy_device_to_device_argv *optargs);
4660 This is the "argv variant" of "guestfs_copy_device_to_device".
4662 See "CALLS WITH OPTIONAL ARGUMENTS".
4664 guestfs_copy_device_to_file
4666 int
4667 guestfs_copy_device_to_file (guestfs_h *g,
4668 const char *src,
4669 const char *dest,
4670 ...);
4671 You may supply a list of optional arguments to this call. Use zero or
4673 more of the following pairs of parameters, and terminate the list with
4674 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4675 GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4677 GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4678 GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4679 GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4680 GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4681 See "guestfs_copy_device_to_device" for a general overview of this
4683 call.
4684 This function returns 0 on success or -1 on error.
4686 This long-running command can generate progress notification messages
4688 so that the caller can display a progress bar or indicator. To receive
4689 these messages, the caller must register a progress event callback.
4690 See "GUESTFS_EVENT_PROGRESS".
4691 (Added in 1.13.25)
4693 guestfs_copy_device_to_file_va
4695 int
4696 guestfs_copy_device_to_file_va (guestfs_h *g,
4697 const char *src,
4698 const char *dest,
4699 va_list args);
4700 This is the "va_list variant" of "guestfs_copy_device_to_file".
4702 See "CALLS WITH OPTIONAL ARGUMENTS".
4704 guestfs_copy_device_to_file_argv
4706 int
4707 guestfs_copy_device_to_file_argv (guestfs_h *g,
4708 const char *src,
4709 const char *dest,
4710 const struct guestfs_copy_device_to_file_argv *optargs);
4711 This is the "argv variant" of "guestfs_copy_device_to_file".
4713 See "CALLS WITH OPTIONAL ARGUMENTS".
4715 guestfs_copy_file_to_device
4717 int
4718 guestfs_copy_file_to_device (guestfs_h *g,
4719 const char *src,
4720 const char *dest,
4721 ...);
4722 You may supply a list of optional arguments to this call. Use zero or
4724 more of the following pairs of parameters, and terminate the list with
4725 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4726 GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4728 GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4729 GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4730 GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4731 GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4732 See "guestfs_copy_device_to_device" for a general overview of this
4734 call.
4735 This function returns 0 on success or -1 on error.
4737 This long-running command can generate progress notification messages
4739 so that the caller can display a progress bar or indicator. To receive
4740 these messages, the caller must register a progress event callback.
4741 See "GUESTFS_EVENT_PROGRESS".
4742 (Added in 1.13.25)
4744 guestfs_copy_file_to_device_va
4746 int
4747 guestfs_copy_file_to_device_va (guestfs_h *g,
4748 const char *src,
4749 const char *dest,
4750 va_list args);
4751 This is the "va_list variant" of "guestfs_copy_file_to_device".
4753 See "CALLS WITH OPTIONAL ARGUMENTS".
4755 guestfs_copy_file_to_device_argv
4757 int
4758 guestfs_copy_file_to_device_argv (guestfs_h *g,
4759 const char *src,
4760 const char *dest,
4761 const struct guestfs_copy_file_to_device_argv *optargs);
4762 This is the "argv variant" of "guestfs_copy_file_to_device".
4764 See "CALLS WITH OPTIONAL ARGUMENTS".
4766 guestfs_copy_file_to_file
4768 int
4769 guestfs_copy_file_to_file (guestfs_h *g,
4770 const char *src,
4771 const char *dest,
4772 ...);
4773 You may supply a list of optional arguments to this call. Use zero or
4775 more of the following pairs of parameters, and terminate the list with
4776 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4777 GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4779 GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4780 GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4781 GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4782 GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4783 See "guestfs_copy_device_to_device" for a general overview of this
4785 call.
4786 This is not the function you want for copying files. This is for
4788 copying blocks within existing files. See "guestfs_cp", "guestfs_cp_a"
4789 and "guestfs_mv" for general file copying and moving functions.
4790 This function returns 0 on success or -1 on error.
4792 This long-running command can generate progress notification messages
4794 so that the caller can display a progress bar or indicator. To receive
4795 these messages, the caller must register a progress event callback.
4796 See "GUESTFS_EVENT_PROGRESS".
4797 (Added in 1.13.25)
4799 guestfs_copy_file_to_file_va
4801 int
4802 guestfs_copy_file_to_file_va (guestfs_h *g,
4803 const char *src,
4804 const char *dest,
4805 va_list args);
4806 This is the "va_list variant" of "guestfs_copy_file_to_file".
4808 See "CALLS WITH OPTIONAL ARGUMENTS".
4810 guestfs_copy_file_to_file_argv
4812 int
4813 guestfs_copy_file_to_file_argv (guestfs_h *g,
4814 const char *src,
4815 const char *dest,
4816 const struct guestfs_copy_file_to_file_argv *optargs);
4817 This is the "argv variant" of "guestfs_copy_file_to_file".
4819 See "CALLS WITH OPTIONAL ARGUMENTS".
4821 guestfs_copy_in
4823 int
4824 guestfs_copy_in (guestfs_h *g,
4825 const char *localpath,
4826 const char *remotedir);
4827 "guestfs_copy_in" copies local files or directories recursively into
4829 the disk image, placing them in the directory called "remotedir" (which
4830 must exist).
4831 Wildcards cannot be used.
4833 This function returns 0 on success or -1 on error.
4835 (Added in 1.29.24)
4837 guestfs_copy_out
4839 int
4840 guestfs_copy_out (guestfs_h *g,
4841 const char *remotepath,
4842 const char *localdir);
4843 "guestfs_copy_out" copies remote files or directories recursively out
4845 of the disk image, placing them on the host disk in a local directory
4846 called "localdir" (which must exist).
4847 To download to the current directory, use "." as in:
4849 C<guestfs_copy_out> /home .
4851 Wildcards cannot be used.
4853 This function returns 0 on success or -1 on error.
4855 (Added in 1.29.24)
4857 guestfs_copy_size
4859 int
4860 guestfs_copy_size (guestfs_h *g,
4861 const char *src,
4862 const char *dest,
4863 int64_t size);
4864 This function is deprecated. In new code, use the
4866 "guestfs_copy_device_to_device" call instead.
4867 Deprecated functions will not be removed from the API, but the fact
4869 that they are deprecated indicates that there are problems with correct
4870 use of these functions.
4871 This command copies exactly "size" bytes from one source device or file
4873 "src" to another destination device or file "dest".
4874 Note this will fail if the source is too short or if the destination is
4876 not large enough.
4877 This function returns 0 on success or -1 on error.
4879 This long-running command can generate progress notification messages
4881 so that the caller can display a progress bar or indicator. To receive
4882 these messages, the caller must register a progress event callback.
4883 See "GUESTFS_EVENT_PROGRESS".
4884 (Added in 1.0.87)
4886 guestfs_cp
4888 int
4889 guestfs_cp (guestfs_h *g,
4890 const char *src,
4891 const char *dest);
4892 This copies a file from "src" to "dest" where "dest" is either a
4894 destination filename or destination directory.
4895 This function returns 0 on success or -1 on error.
4897 (Added in 1.0.18)
4899 guestfs_cp_a
4901 int
4902 guestfs_cp_a (guestfs_h *g,
4903 const char *src,
4904 const char *dest);
4905 This copies a file or directory from "src" to "dest" recursively using
4907 the "cp -a" command.
4908 This function returns 0 on success or -1 on error.
4910 (Added in 1.0.18)
4912 guestfs_cp_r
4914 int
4915 guestfs_cp_r (guestfs_h *g,
4916 const char *src,
4917 const char *dest);
4918 This copies a file or directory from "src" to "dest" recursively using
4920 the "cp -rP" command.
4921 Most users should use "guestfs_cp_a" instead. This command is useful
4923 when you don't want to preserve permissions, because the target
4924 filesystem does not support it (primarily when writing to DOS FAT
4925 filesystems).
4926 This function returns 0 on success or -1 on error.
4928 (Added in 1.21.38)
4930 guestfs_cpio_out
4932 int
4933 guestfs_cpio_out (guestfs_h *g,
4934 const char *directory,
4935 const char *cpiofile,
4936 ...);
4937 You may supply a list of optional arguments to this call. Use zero or
4939 more of the following pairs of parameters, and terminate the list with
4940 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4941 GUESTFS_CPIO_OUT_FORMAT, const char *format,
4943 This command packs the contents of directory and downloads it to local
4945 file "cpiofile".
4946 The optional "format" parameter can be used to select the format. Only
4948 the following formats are currently permitted:
4949 "newc"
4951 New (SVR4) portable format. This format happens to be compatible
4952 with the cpio-like format used by the Linux kernel for initramfs.
4953 This is the default format.
4955 "crc"
4957 New (SVR4) portable format with a checksum.
4958 This function returns 0 on success or -1 on error.
4960 (Added in 1.27.9)
4962 guestfs_cpio_out_va
4964 int
4965 guestfs_cpio_out_va (guestfs_h *g,
4966 const char *directory,
4967 const char *cpiofile,
4968 va_list args);
4969 This is the "va_list variant" of "guestfs_cpio_out".
4971 See "CALLS WITH OPTIONAL ARGUMENTS".
4973 guestfs_cpio_out_argv
4975 int
4976 guestfs_cpio_out_argv (guestfs_h *g,
4977 const char *directory,
4978 const char *cpiofile,
4979 const struct guestfs_cpio_out_argv *optargs);
4980 This is the "argv variant" of "guestfs_cpio_out".
4982 See "CALLS WITH OPTIONAL ARGUMENTS".
4984 guestfs_cryptsetup_close
4986 int
4987 guestfs_cryptsetup_close (guestfs_h *g,
4988 const char *device);
4989 This closes an encrypted device that was created earlier by
4991 "guestfs_cryptsetup_open". The "device" parameter must be the name of
4992 the mapping device (ie. /dev/mapper/mapname) and not the name of the
4993 underlying block device.
4994 This function returns 0 on success or -1 on error.
4996 This function depends on the feature "luks". See also
4998 "guestfs_feature_available".
4999 (Added in 1.43.2)
5001 guestfs_cryptsetup_open
5003 int
5004 guestfs_cryptsetup_open (guestfs_h *g,
5005 const char *device,
5006 const char *key,
5007 const char *mapname,
5008 ...);
5009 You may supply a list of optional arguments to this call. Use zero or
5011 more of the following pairs of parameters, and terminate the list with
5012 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5013 GUESTFS_CRYPTSETUP_OPEN_READONLY, int readonly,
5015 GUESTFS_CRYPTSETUP_OPEN_CRYPTTYPE, const char *crypttype,
5016 This command opens a block device which has been encrypted according to
5018 the Linux Unified Key Setup (LUKS) standard, Windows BitLocker, or some
5019 other types.
5020 "device" is the encrypted block device or partition.
5022 The caller must supply one of the keys associated with the encrypted
5024 block device, in the "key" parameter.
5025 This creates a new block device called /dev/mapper/mapname. Reads and
5027 writes to this block device are decrypted from and encrypted to the
5028 underlying "device" respectively.
5029 "mapname" cannot be "control" because that name is reserved by device-
5031 mapper.
5032 If the optional "crypttype" parameter is not present then libguestfs
5034 tries to guess the correct type (for example LUKS or BitLocker).
5035 However you can override this by specifying one of the following types:
5036 "luks"
5038 A Linux LUKS device.
5039 "bitlk"
5041 A Windows BitLocker device.
5042 The optional "readonly" flag, if set to true, creates a read-only
5044 mapping.
5045 If this block device contains LVM volume groups, then calling
5047 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
5048 visible.
5049 Use "guestfs_list_dm_devices" to list all device mapper devices.
5051 This function returns 0 on success or -1 on error.
5053 This function takes a key or passphrase parameter which could contain
5055 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
5056 information.
5057 This function depends on the feature "luks". See also
5059 "guestfs_feature_available".
5060 (Added in 1.43.2)
5062 guestfs_cryptsetup_open_va
5064 int
5065 guestfs_cryptsetup_open_va (guestfs_h *g,
5066 const char *device,
5067 const char *key,
5068 const char *mapname,
5069 va_list args);
5070 This is the "va_list variant" of "guestfs_cryptsetup_open".
5072 See "CALLS WITH OPTIONAL ARGUMENTS".
5074 guestfs_cryptsetup_open_argv
5076 int
5077 guestfs_cryptsetup_open_argv (guestfs_h *g,
5078 const char *device,
5079 const char *key,
5080 const char *mapname,
5081 const struct guestfs_cryptsetup_open_argv *optargs);
5082 This is the "argv variant" of "guestfs_cryptsetup_open".
5084 See "CALLS WITH OPTIONAL ARGUMENTS".
5086 guestfs_dd
5088 int
5089 guestfs_dd (guestfs_h *g,
5090 const char *src,
5091 const char *dest);
5092 This function is deprecated. In new code, use the
5094 "guestfs_copy_device_to_device" call instead.
5095 Deprecated functions will not be removed from the API, but the fact
5097 that they are deprecated indicates that there are problems with correct
5098 use of these functions.
5099 This command copies from one source device or file "src" to another
5101 destination device or file "dest". Normally you would use this to copy
5102 to or from a device or partition, for example to duplicate a
5103 filesystem.
5104 If the destination is a device, it must be as large or larger than the
5106 source file or device, otherwise the copy will fail. This command
5107 cannot do partial copies (see "guestfs_copy_device_to_device").
5108 This function returns 0 on success or -1 on error.
5110 (Added in 1.0.80)
5112 guestfs_device_index
5114 int
5115 guestfs_device_index (guestfs_h *g,
5116 const char *device);
5117 This function takes a device name (eg. "/dev/sdb") and returns the
5119 index of the device in the list of devices.
5120 Index numbers start from 0. The named device must exist, for example
5122 as a string returned from "guestfs_list_devices".
5123 See also "guestfs_list_devices", "guestfs_part_to_dev".
5125 On error this function returns -1.
5127 (Added in 1.19.7)
5129 guestfs_df
5131 char *
5132 guestfs_df (guestfs_h *g);
5133 This command runs the df(1) command to report disk space used.
5135 This command is mostly useful for interactive sessions. It is not
5137 intended that you try to parse the output string. Use
5138 "guestfs_statvfs" from programs.
5139 This function returns a string, or NULL on error. The caller must free
5141 the returned string after use.
5142 (Added in 1.0.54)
5144 guestfs_df_h
5146 char *
5147 guestfs_df_h (guestfs_h *g);
5148 This command runs the "df -h" command to report disk space used in
5150 human-readable format.
5151 This command is mostly useful for interactive sessions. It is not
5153 intended that you try to parse the output string. Use
5154 "guestfs_statvfs" from programs.
5155 This function returns a string, or NULL on error. The caller must free
5157 the returned string after use.
5158 (Added in 1.0.54)
5160 guestfs_disk_create
5162 int
5163 guestfs_disk_create (guestfs_h *g,
5164 const char *filename,
5165 const char *format,
5166 int64_t size,
5167 ...);
5168 You may supply a list of optional arguments to this call. Use zero or
5170 more of the following pairs of parameters, and terminate the list with
5171 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5172 GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
5174 GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
5175 GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
5176 GUESTFS_DISK_CREATE_COMPAT, const char *compat,
5177 GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
5178 Create a blank disk image called filename (a host file) with format
5180 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
5181 If used with the optional "backingfile" parameter, then a snapshot is
5183 created on top of the backing file. In this case, "size" must be
5184 passed as "-1". The size of the snapshot is the same as the size of
5185 the backing file, which is discovered automatically. You are
5186 encouraged to also pass "backingformat" to describe the format of
5187 "backingfile".
5188 If filename refers to a block device, then the device is formatted.
5190 The "size" is ignored since block devices have an intrinsic size.
5191 The other optional parameters are:
5193 "preallocation"
5195 If format is "raw", then this can be either "off" (or "sparse") or
5196 "full" to create a sparse or fully allocated file respectively.
5197 The default is "off".
5198 If format is "qcow2", then this can be "off" (or "sparse"),
5200 "metadata" or "full". Preallocating metadata can be faster when
5201 doing lots of writes, but uses more space. The default is "off".
5202 "compat"
5204 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5205 supported by qemu ≥ 1.1.
5206 "clustersize"
5208 "qcow2" only: Change the qcow2 cluster size. The default is 65536
5209 (bytes) and this setting may be any power of two between 512 and
5210 2097152.
5211 Note that this call does not add the new disk to the handle. You may
5213 need to call "guestfs_add_drive_opts" separately.
5214 This function returns 0 on success or -1 on error.
5216 (Added in 1.25.31)
5218 guestfs_disk_create_va
5220 int
5221 guestfs_disk_create_va (guestfs_h *g,
5222 const char *filename,
5223 const char *format,
5224 int64_t size,
5225 va_list args);
5226 This is the "va_list variant" of "guestfs_disk_create".
5228 See "CALLS WITH OPTIONAL ARGUMENTS".
5230 guestfs_disk_create_argv
5232 int
5233 guestfs_disk_create_argv (guestfs_h *g,
5234 const char *filename,
5235 const char *format,
5236 int64_t size,
5237 const struct guestfs_disk_create_argv *optargs);
5238 This is the "argv variant" of "guestfs_disk_create".
5240 See "CALLS WITH OPTIONAL ARGUMENTS".
5242 guestfs_disk_format
5244 char *
5245 guestfs_disk_format (guestfs_h *g,
5246 const char *filename);
5247 Detect and return the format of the disk image called filename.
5249 filename can also be a host device, etc. If the format of the image
5250 could not be detected, then "unknown" is returned.
5251 Note that detecting the disk format can be insecure under some
5253 circumstances. See "CVE-2010-3851".
5254 See also: "DISK IMAGE FORMATS"
5256 This function returns a string, or NULL on error. The caller must free
5258 the returned string after use.
5259 (Added in 1.19.38)
5261 guestfs_disk_has_backing_file
5263 int
5264 guestfs_disk_has_backing_file (guestfs_h *g,
5265 const char *filename);
5266 Detect and return whether the disk image filename has a backing file.
5268 Note that detecting disk features can be insecure under some
5270 circumstances. See "CVE-2010-3851".
5271 This function returns a C truth value on success or -1 on error.
5273 (Added in 1.19.39)
5275 guestfs_disk_virtual_size
5277 int64_t
5278 guestfs_disk_virtual_size (guestfs_h *g,
5279 const char *filename);
5280 Detect and return the virtual size in bytes of the disk image called
5282 filename.
5283 Note that detecting disk features can be insecure under some
5285 circumstances. See "CVE-2010-3851".
5286 On error this function returns -1.
5288 (Added in 1.19.39)
5290 guestfs_dmesg
5292 char *
5293 guestfs_dmesg (guestfs_h *g);
5294 This returns the kernel messages (dmesg(1) output) from the guest
5296 kernel. This is sometimes useful for extended debugging of problems.
5297 Another way to get the same information is to enable verbose messages
5299 with "guestfs_set_verbose" or by setting the environment variable
5300 "LIBGUESTFS_DEBUG=1" before running the program.
5301 This function returns a string, or NULL on error. The caller must free
5303 the returned string after use.
5304 (Added in 1.0.18)
5306 guestfs_download
5308 int
5309 guestfs_download (guestfs_h *g,
5310 const char *remotefilename,
5311 const char *filename);
5312 Download file remotefilename and save it as filename on the local
5314 machine.
5315 filename can also be a named pipe.
5317 See also "guestfs_upload", "guestfs_cat".
5319 This function returns 0 on success or -1 on error.
5321 This long-running command can generate progress notification messages
5323 so that the caller can display a progress bar or indicator. To receive
5324 these messages, the caller must register a progress event callback.
5325 See "GUESTFS_EVENT_PROGRESS".
5326 (Added in 1.0.2)
5328 guestfs_download_blocks
5330 int
5331 guestfs_download_blocks (guestfs_h *g,
5332 const char *device,
5333 int64_t start,
5334 int64_t stop,
5335 const char *filename,
5336 ...);
5337 You may supply a list of optional arguments to this call. Use zero or
5339 more of the following pairs of parameters, and terminate the list with
5340 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5341 GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5343 Download the data units from start address to stop from the disk
5345 partition (eg. /dev/sda1) and save them as filename on the local
5346 machine.
5347 The use of this API on sparse disk image formats such as QCOW, may
5349 result in large zero-filled files downloaded on the host.
5350 The size of a data unit varies across filesystem implementations. On
5352 NTFS filesystems data units are referred as clusters while on ExtX ones
5353 they are referred as fragments.
5354 If the optional "unallocated" flag is true (default is false), only the
5356 unallocated blocks will be extracted. This is useful to detect hidden
5357 data or to retrieve deleted files which data units have not been
5358 overwritten yet.
5359 This function returns 0 on success or -1 on error.
5361 This long-running command can generate progress notification messages
5363 so that the caller can display a progress bar or indicator. To receive
5364 these messages, the caller must register a progress event callback.
5365 See "GUESTFS_EVENT_PROGRESS".
5366 This function depends on the feature "sleuthkit". See also
5368 "guestfs_feature_available".
5369 (Added in 1.33.45)
5371 guestfs_download_blocks_va
5373 int
5374 guestfs_download_blocks_va (guestfs_h *g,
5375 const char *device,
5376 int64_t start,
5377 int64_t stop,
5378 const char *filename,
5379 va_list args);
5380 This is the "va_list variant" of "guestfs_download_blocks".
5382 See "CALLS WITH OPTIONAL ARGUMENTS".
5384 guestfs_download_blocks_argv
5386 int
5387 guestfs_download_blocks_argv (guestfs_h *g,
5388 const char *device,
5389 int64_t start,
5390 int64_t stop,
5391 const char *filename,
5392 const struct guestfs_download_blocks_argv *optargs);
5393 This is the "argv variant" of "guestfs_download_blocks".
5395 See "CALLS WITH OPTIONAL ARGUMENTS".
5397 guestfs_download_inode
5399 int
5400 guestfs_download_inode (guestfs_h *g,
5401 const char *device,
5402 int64_t inode,
5403 const char *filename);
5404 Download a file given its inode from the disk partition (eg. /dev/sda1)
5406 and save it as filename on the local machine.
5407 It is not required to mount the disk to run this command.
5409 The command is capable of downloading deleted or inaccessible files.
5411 This function returns 0 on success or -1 on error.
5413 This long-running command can generate progress notification messages
5415 so that the caller can display a progress bar or indicator. To receive
5416 these messages, the caller must register a progress event callback.
5417 See "GUESTFS_EVENT_PROGRESS".
5418 This function depends on the feature "sleuthkit". See also
5420 "guestfs_feature_available".
5421 (Added in 1.33.14)
5423 guestfs_download_offset
5425 int
5426 guestfs_download_offset (guestfs_h *g,
5427 const char *remotefilename,
5428 const char *filename,
5429 int64_t offset,
5430 int64_t size);
5431 Download file remotefilename and save it as filename on the local
5433 machine.
5434 remotefilename is read for "size" bytes starting at "offset" (this
5436 region must be within the file or device).
5437 Note that there is no limit on the amount of data that can be
5439 downloaded with this call, unlike with "guestfs_pread", and this call
5440 always reads the full amount unless an error occurs.
5441 See also "guestfs_download", "guestfs_pread".
5443 This function returns 0 on success or -1 on error.
5445 This long-running command can generate progress notification messages
5447 so that the caller can display a progress bar or indicator. To receive
5448 these messages, the caller must register a progress event callback.
5449 See "GUESTFS_EVENT_PROGRESS".
5450 (Added in 1.5.17)
5452 guestfs_drop_caches
5454 int
5455 guestfs_drop_caches (guestfs_h *g,
5456 int whattodrop);
5457 This instructs the guest kernel to drop its page cache, and/or dentries
5459 and inode caches. The parameter "whattodrop" tells the kernel what
5460 precisely to drop, see https://linux-mm.org/Drop_Caches
5461 Setting "whattodrop" to 3 should drop everything.
5463 This automatically calls sync(2) before the operation, so that the
5465 maximum guest memory is freed.
5466 This function returns 0 on success or -1 on error.
5468 (Added in 1.0.18)
5470 guestfs_du
5472 int64_t
5473 guestfs_du (guestfs_h *g,
5474 const char *path);
5475 This command runs the "du -s" command to estimate file space usage for
5477 "path".
5478 "path" can be a file or a directory. If "path" is a directory then the
5480 estimate includes the contents of the directory and all subdirectories
5481 (recursively).
5482 The result is the estimated size in kilobytes (ie. units of 1024
5484 bytes).
5485 On error this function returns -1.
5487 This long-running command can generate progress notification messages
5489 so that the caller can display a progress bar or indicator. To receive
5490 these messages, the caller must register a progress event callback.
5491 See "GUESTFS_EVENT_PROGRESS".
5492 (Added in 1.0.54)
5494 guestfs_e2fsck
5496 int
5497 guestfs_e2fsck (guestfs_h *g,
5498 const char *device,
5499 ...);
5500 You may supply a list of optional arguments to this call. Use zero or
5502 more of the following pairs of parameters, and terminate the list with
5503 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5504 GUESTFS_E2FSCK_CORRECT, int correct,
5506 GUESTFS_E2FSCK_FORCEALL, int forceall,
5507 This runs the ext2/ext3 filesystem checker on "device". It can take
5509 the following optional arguments:
5510 "correct"
5512 Automatically repair the file system. This option will cause e2fsck
5513 to automatically fix any filesystem problems that can be safely
5514 fixed without human intervention.
5515 This option may not be specified at the same time as the "forceall"
5517 option.
5518 "forceall"
5520 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5521 used non-interactively.
5522 This option may not be specified at the same time as the "correct"
5524 option.
5525 This function returns 0 on success or -1 on error.
5527 (Added in 1.15.17)
5529 guestfs_e2fsck_va
5531 int
5532 guestfs_e2fsck_va (guestfs_h *g,
5533 const char *device,
5534 va_list args);
5535 This is the "va_list variant" of "guestfs_e2fsck".
5537 See "CALLS WITH OPTIONAL ARGUMENTS".
5539 guestfs_e2fsck_argv
5541 int
5542 guestfs_e2fsck_argv (guestfs_h *g,
5543 const char *device,
5544 const struct guestfs_e2fsck_argv *optargs);
5545 This is the "argv variant" of "guestfs_e2fsck".
5547 See "CALLS WITH OPTIONAL ARGUMENTS".
5549 guestfs_e2fsck_f
5551 int
5552 guestfs_e2fsck_f (guestfs_h *g,
5553 const char *device);
5554 This function is deprecated. In new code, use the "guestfs_e2fsck"
5556 call instead.
5557 Deprecated functions will not be removed from the API, but the fact
5559 that they are deprecated indicates that there are problems with correct
5560 use of these functions.
5561 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5563 checker on "device", noninteractively (-p), even if the filesystem
5564 appears to be clean (-f).
5565 This function returns 0 on success or -1 on error.
5567 (Added in 1.0.29)
5569 guestfs_echo_daemon
5571 char *
5572 guestfs_echo_daemon (guestfs_h *g,
5573 char *const *words);
5574 This command concatenates the list of "words" passed with single spaces
5576 between them and returns the resulting string.
5577 You can use this command to test the connection through to the daemon.
5579 See also "guestfs_ping_daemon".
5581 This function returns a string, or NULL on error. The caller must free
5583 the returned string after use.
5584 (Added in 1.0.69)
5586 guestfs_egrep
5588 char **
5589 guestfs_egrep (guestfs_h *g,
5590 const char *regex,
5591 const char *path);
5592 This function is deprecated. In new code, use the "guestfs_grep" call
5594 instead.
5595 Deprecated functions will not be removed from the API, but the fact
5597 that they are deprecated indicates that there are problems with correct
5598 use of these functions.
5599 This calls the external egrep(1) program and returns the matching
5601 lines.
5602 This function returns a NULL-terminated array of strings (like
5604 environ(3)), or NULL if there was an error. The caller must free the
5605 strings and the array after use.
5606 Because of the message protocol, there is a transfer limit of somewhere
5608 between 2MB and 4MB. See "PROTOCOL LIMITS".
5609 (Added in 1.0.66)
5611 guestfs_egrepi
5613 char **
5614 guestfs_egrepi (guestfs_h *g,
5615 const char *regex,
5616 const char *path);
5617 This function is deprecated. In new code, use the "guestfs_grep" call
5619 instead.
5620 Deprecated functions will not be removed from the API, but the fact
5622 that they are deprecated indicates that there are problems with correct
5623 use of these functions.
5624 This calls the external "egrep -i" program and returns the matching
5626 lines.
5627 This function returns a NULL-terminated array of strings (like
5629 environ(3)), or NULL if there was an error. The caller must free the
5630 strings and the array after use.
5631 Because of the message protocol, there is a transfer limit of somewhere
5633 between 2MB and 4MB. See "PROTOCOL LIMITS".
5634 (Added in 1.0.66)
5636 guestfs_equal
5638 int
5639 guestfs_equal (guestfs_h *g,
5640 const char *file1,
5641 const char *file2);
5642 This compares the two files file1 and file2 and returns true if their
5644 content is exactly equal, or false otherwise.
5645 The external cmp(1) program is used for the comparison.
5647 This function returns a C truth value on success or -1 on error.
5649 (Added in 1.0.18)
5651 guestfs_exists
5653 int
5654 guestfs_exists (guestfs_h *g,
5655 const char *path);
5656 This returns "true" if and only if there is a file, directory (or
5658 anything) with the given "path" name.
5659 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5661 This function returns a C truth value on success or -1 on error.
5663 (Added in 0.8)
5665 guestfs_extlinux
5667 int
5668 guestfs_extlinux (guestfs_h *g,
5669 const char *directory);
5670 Install the SYSLINUX bootloader on the device mounted at directory.
5672 Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5673 used on an ext2/3/4 or btrfs filesystem.
5674 The directory parameter can be either a mountpoint, or a directory
5676 within the mountpoint.
5677 You also have to mark the partition as "active"
5679 ("guestfs_part_set_bootable") and a Master Boot Record must be
5680 installed (eg. using "guestfs_pwrite_device") on the first sector of
5681 the whole disk. The SYSLINUX package comes with some suitable Master
5682 Boot Records. See the extlinux(1) man page for further information.
5683 Additional configuration can be supplied to SYSLINUX by placing a file
5685 called extlinux.conf on the filesystem under directory. For further
5686 information about the contents of this file, see extlinux(1).
5687 See also "guestfs_syslinux".
5689 This function returns 0 on success or -1 on error.
5691 This function depends on the feature "extlinux". See also
5693 "guestfs_feature_available".
5694 (Added in 1.21.27)
5696 guestfs_f2fs_expand
5698 int
5699 guestfs_f2fs_expand (guestfs_h *g,
5700 const char *device);
5701 This expands a f2fs filesystem to match the size of the underlying
5703 device.
5704 This function returns 0 on success or -1 on error.
5706 This function depends on the feature "f2fs". See also
5708 "guestfs_feature_available".
5709 (Added in 1.39.3)
5711 guestfs_fallocate
5713 int
5714 guestfs_fallocate (guestfs_h *g,
5715 const char *path,
5716 int len);
5717 This function is deprecated. In new code, use the
5719 "guestfs_fallocate64" call instead.
5720 Deprecated functions will not be removed from the API, but the fact
5722 that they are deprecated indicates that there are problems with correct
5723 use of these functions.
5724 This command preallocates a file (containing zero bytes) named "path"
5726 of size "len" bytes. If the file exists already, it is overwritten.
5727 Do not confuse this with the guestfish-specific "alloc" command which
5729 allocates a file in the host and attaches it as a device.
5730 This function returns 0 on success or -1 on error.
5732 (Added in 1.0.66)
5734 guestfs_fallocate64
5736 int
5737 guestfs_fallocate64 (guestfs_h *g,
5738 const char *path,
5739 int64_t len);
5740 This command preallocates a file (containing zero bytes) named "path"
5742 of size "len" bytes. If the file exists already, it is overwritten.
5743 Note that this call allocates disk blocks for the file. To create a
5745 sparse file use "guestfs_truncate_size" instead.
5746 The deprecated call "guestfs_fallocate" does the same, but owing to an
5748 oversight it only allowed 30 bit lengths to be specified, effectively
5749 limiting the maximum size of files created through that call to 1GB.
5750 Do not confuse this with the guestfish-specific "alloc" and "sparse"
5752 commands which create a file in the host and attach it as a device.
5753 This function returns 0 on success or -1 on error.
5755 (Added in 1.3.17)
5757 guestfs_feature_available
5759 int
5760 guestfs_feature_available (guestfs_h *g,
5761 char *const *groups);
5762 This is the same as "guestfs_available", but unlike that call it
5764 returns a simple true/false boolean result, instead of throwing an
5765 exception if a feature is not found. For other documentation see
5766 "guestfs_available".
5767 This function returns a C truth value on success or -1 on error.
5769 (Added in 1.21.26)
5771 guestfs_fgrep
5773 char **
5774 guestfs_fgrep (guestfs_h *g,
5775 const char *pattern,
5776 const char *path);
5777 This function is deprecated. In new code, use the "guestfs_grep" call
5779 instead.
5780 Deprecated functions will not be removed from the API, but the fact
5782 that they are deprecated indicates that there are problems with correct
5783 use of these functions.
5784 This calls the external fgrep(1) program and returns the matching
5786 lines.
5787 This function returns a NULL-terminated array of strings (like
5789 environ(3)), or NULL if there was an error. The caller must free the
5790 strings and the array after use.
5791 Because of the message protocol, there is a transfer limit of somewhere
5793 between 2MB and 4MB. See "PROTOCOL LIMITS".
5794 (Added in 1.0.66)
5796 guestfs_fgrepi
5798 char **
5799 guestfs_fgrepi (guestfs_h *g,
5800 const char *pattern,
5801 const char *path);
5802 This function is deprecated. In new code, use the "guestfs_grep" call
5804 instead.
5805 Deprecated functions will not be removed from the API, but the fact
5807 that they are deprecated indicates that there are problems with correct
5808 use of these functions.
5809 This calls the external "fgrep -i" program and returns the matching
5811 lines.
5812 This function returns a NULL-terminated array of strings (like
5814 environ(3)), or NULL if there was an error. The caller must free the
5815 strings and the array after use.
5816 Because of the message protocol, there is a transfer limit of somewhere
5818 between 2MB and 4MB. See "PROTOCOL LIMITS".
5819 (Added in 1.0.66)
5821 guestfs_file
5823 char *
5824 guestfs_file (guestfs_h *g,
5825 const char *path);
5826 This call uses the standard file(1) command to determine the type or
5828 contents of the file.
5829 This call will also transparently look inside various types of
5831 compressed file.
5832 The exact command which runs is "file -zb path". Note in particular
5834 that the filename is not prepended to the output (the -b option).
5835 The output depends on the output of the underlying file(1) command and
5837 it can change in future in ways beyond our control. In other words,
5838 the output is not guaranteed by the ABI.
5839 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5841 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5842 This function returns a string, or NULL on error. The caller must free
5844 the returned string after use.
5845 (Added in 1.9.1)
5847 guestfs_file_architecture
5849 char *
5850 guestfs_file_architecture (guestfs_h *g,
5851 const char *filename);
5852 This detects the architecture of the binary filename, and returns it if
5854 known.
5855 Currently defined architectures are:
5857 "aarch64"
5859 64 bit ARM.
5860 "arm"
5862 32 bit ARM.
5863 "i386"
5865 This string is returned for all 32 bit i386, i486, i586, i686
5866 binaries irrespective of the precise processor requirements of the
5867 binary.
5868 "ia64"
5870 Intel Itanium.
5871 "ppc"
5873 32 bit Power PC.
5874 "ppc64"
5876 64 bit Power PC (big endian).
5877 "ppc64le"
5879 64 bit Power PC (little endian).
5880 "riscv32"
5882 "riscv64"
5883 "riscv128"
5884 RISC-V 32-, 64- or 128-bit variants.
5885 "s390"
5887 31 bit IBM S/390.
5888 "s390x"
5890 64 bit IBM S/390.
5891 "sparc"
5893 32 bit SPARC.
5894 "sparc64"
5896 64 bit SPARC V9 and above.
5897 "x86_64"
5899 64 bit x86-64.
5900 Libguestfs may return other architecture strings in future.
5902 The function works on at least the following types of files:
5904 · many types of Un*x and Linux binary
5906 · many types of Un*x and Linux shared library
5908 · Windows Win32 and Win64 binaries
5910 · Windows Win32 and Win64 DLLs
5912 Win32 binaries and DLLs return "i386".
5914 Win64 binaries and DLLs return "x86_64".
5916 · Linux kernel modules
5918 · Linux new-style initrd images
5920 · some non-x86 Linux vmlinuz kernels
5922 What it can't do currently:
5924 · static libraries (libfoo.a)
5926 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5928 · x86 Linux vmlinuz kernels
5930 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5932 and compressed code, and are horribly hard to unpack. If you want
5933 to find the architecture of a kernel, use the architecture of the
5934 associated initrd or kernel module(s) instead.
5935 This function returns a string, or NULL on error. The caller must free
5937 the returned string after use.
5938 (Added in 1.5.3)
5940 guestfs_filesize
5942 int64_t
5943 guestfs_filesize (guestfs_h *g,
5944 const char *file);
5945 This command returns the size of file in bytes.
5947 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5949 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
5950 devices, use "guestfs_blockdev_getsize64".
5951 On error this function returns -1.
5953 (Added in 1.0.82)
5955 guestfs_filesystem_available
5957 int
5958 guestfs_filesystem_available (guestfs_h *g,
5959 const char *filesystem);
5960 Check whether libguestfs supports the named filesystem. The argument
5962 "filesystem" is a filesystem name, such as "ext3".
5963 You must call "guestfs_launch" before using this command.
5965 This is mainly useful as a negative test. If this returns true, it
5967 doesn't mean that a particular filesystem can be created or mounted,
5968 since filesystems can fail for other reasons such as it being a later
5969 version of the filesystem, or having incompatible features, or lacking
5970 the right mkfs.<fs> tool.
5971 See also "guestfs_available", "guestfs_feature_available",
5973 "AVAILABILITY".
5974 This function returns a C truth value on success or -1 on error.
5976 (Added in 1.19.5)
5978 guestfs_filesystem_walk
5980 struct guestfs_tsk_dirent_list *
5981 guestfs_filesystem_walk (guestfs_h *g,
5982 const char *device);
5983 Walk through the internal structures of a disk partition (eg.
5985 /dev/sda1) in order to return a list of all the files and directories
5986 stored within.
5987 It is not necessary to mount the disk partition to run this command.
5989 All entries in the filesystem are returned. This function can list
5991 deleted or unaccessible files. The entries are not sorted.
5992 The "tsk_dirent" structure contains the following fields.
5994 "tsk_inode"
5996 Filesystem reference number of the node. It might be 0 if the node
5997 has been deleted.
5998 "tsk_type"
6000 Basic file type information. See below for a detailed list of
6001 values.
6002 "tsk_size"
6004 File size in bytes. It might be "-1" if the node has been deleted.
6005 "tsk_name"
6007 The file path relative to its directory.
6008 "tsk_flags"
6010 Bitfield containing extra information regarding the entry. It
6011 contains the logical OR of the following values:
6012 0x0001
6014 If set to 1, the file is allocated and visible within the
6015 filesystem. Otherwise, the file has been deleted. Under
6016 certain circumstances, the function "download_inode" can be
6017 used to recover deleted files.
6018 0x0002
6020 Filesystem such as NTFS and Ext2 or greater, separate the file
6021 name from the metadata structure. The bit is set to 1 when the
6022 file name is in an unallocated state and the metadata structure
6023 is in an allocated one. This generally implies the metadata
6024 has been reallocated to a new file. Therefore, information
6025 such as file type, file size, timestamps, number of links and
6026 symlink target might not correspond with the ones of the
6027 original deleted entry.
6028 0x0004
6030 The bit is set to 1 when the file is compressed using
6031 filesystem native compression support (NTFS). The API is not
6032 able to detect application level compression.
6033 "tsk_atime_sec"
6035 "tsk_atime_nsec"
6036 "tsk_mtime_sec"
6037 "tsk_mtime_nsec"
6038 "tsk_ctime_sec"
6039 "tsk_ctime_nsec"
6040 "tsk_crtime_sec"
6041 "tsk_crtime_nsec"
6042 Respectively, access, modification, last status change and creation
6043 time in Unix format in seconds and nanoseconds.
6044 "tsk_nlink"
6046 Number of file names pointing to this entry.
6047 "tsk_link"
6049 If the entry is a symbolic link, this field will contain the path
6050 to the target file.
6051 The "tsk_type" field will contain one of the following characters:
6053 'b' Block special
6055 'c' Char special
6057 'd' Directory
6059 'f' FIFO (named pipe)
6061 'l' Symbolic link
6063 'r' Regular file
6065 's' Socket
6067 'h' Shadow inode (Solaris)
6069 'w' Whiteout inode (BSD)
6071 'u' Unknown file type
6073 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6075 there was an error. The caller must call
6076 "guestfs_free_tsk_dirent_list" after use.
6077 This long-running command can generate progress notification messages
6079 so that the caller can display a progress bar or indicator. To receive
6080 these messages, the caller must register a progress event callback.
6081 See "GUESTFS_EVENT_PROGRESS".
6082 This function depends on the feature "libtsk". See also
6084 "guestfs_feature_available".
6085 (Added in 1.33.39)
6087 guestfs_fill
6089 int
6090 guestfs_fill (guestfs_h *g,
6091 int c,
6092 int len,
6093 const char *path);
6094 This command creates a new file called "path". The initial content of
6096 the file is "len" octets of "c", where "c" must be a number in the
6097 range "[0..255]".
6098 To fill a file with zero bytes (sparsely), it is much more efficient to
6100 use "guestfs_truncate_size". To create a file with a pattern of
6101 repeating bytes use "guestfs_fill_pattern".
6102 This function returns 0 on success or -1 on error.
6104 This long-running command can generate progress notification messages
6106 so that the caller can display a progress bar or indicator. To receive
6107 these messages, the caller must register a progress event callback.
6108 See "GUESTFS_EVENT_PROGRESS".
6109 (Added in 1.0.79)
6111 guestfs_fill_dir
6113 int
6114 guestfs_fill_dir (guestfs_h *g,
6115 const char *dir,
6116 int nr);
6117 This function, useful for testing filesystems, creates "nr" empty files
6119 in the directory "dir" with names 00000000 through "nr-1" (ie. each
6120 file name is 8 digits long padded with zeroes).
6121 This function returns 0 on success or -1 on error.
6123 (Added in 1.19.32)
6125 guestfs_fill_pattern
6127 int
6128 guestfs_fill_pattern (guestfs_h *g,
6129 const char *pattern,
6130 int len,
6131 const char *path);
6132 This function is like "guestfs_fill" except that it creates a new file
6134 of length "len" containing the repeating pattern of bytes in "pattern".
6135 The pattern is truncated if necessary to ensure the length of the file
6136 is exactly "len" bytes.
6137 This function returns 0 on success or -1 on error.
6139 This long-running command can generate progress notification messages
6141 so that the caller can display a progress bar or indicator. To receive
6142 these messages, the caller must register a progress event callback.
6143 See "GUESTFS_EVENT_PROGRESS".
6144 (Added in 1.3.12)
6146 guestfs_find
6148 char **
6149 guestfs_find (guestfs_h *g,
6150 const char *directory);
6151 This command lists out all files and directories, recursively, starting
6153 at directory. It is essentially equivalent to running the shell
6154 command "find directory -print" but some post-processing happens on the
6155 output, described below.
6156 This returns a list of strings without any prefix. Thus if the
6158 directory structure was:
6159 /tmp/a
6161 /tmp/b
6162 /tmp/c/d
6163 then the returned list from "guestfs_find" /tmp would be 4 elements:
6165 a
6167 b
6168 c
6169 c/d
6170 If directory is not a directory, then this command returns an error.
6172 The returned list is sorted.
6174 This function returns a NULL-terminated array of strings (like
6176 environ(3)), or NULL if there was an error. The caller must free the
6177 strings and the array after use.
6178 (Added in 1.0.27)
6180 guestfs_find0
6182 int
6183 guestfs_find0 (guestfs_h *g,
6184 const char *directory,
6185 const char *files);
6186 This command lists out all files and directories, recursively, starting
6188 at directory, placing the resulting list in the external file called
6189 files.
6190 This command works the same way as "guestfs_find" with the following
6192 exceptions:
6193 · The resulting list is written to an external file.
6195 · Items (filenames) in the result are separated by "\0" characters.
6197 See find(1) option -print0.
6198 · The result list is not sorted.
6200 This function returns 0 on success or -1 on error.
6202 (Added in 1.0.74)
6204 guestfs_find_inode
6206 struct guestfs_tsk_dirent_list *
6207 guestfs_find_inode (guestfs_h *g,
6208 const char *device,
6209 int64_t inode);
6210 Searches all the entries associated with the given inode.
6212 For each entry, a "tsk_dirent" structure is returned. See
6214 "filesystem_walk" for more information about "tsk_dirent" structures.
6215 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6217 there was an error. The caller must call
6218 "guestfs_free_tsk_dirent_list" after use.
6219 This long-running command can generate progress notification messages
6221 so that the caller can display a progress bar or indicator. To receive
6222 these messages, the caller must register a progress event callback.
6223 See "GUESTFS_EVENT_PROGRESS".
6224 This function depends on the feature "libtsk". See also
6226 "guestfs_feature_available".
6227 (Added in 1.35.6)
6229 guestfs_findfs_label
6231 char *
6232 guestfs_findfs_label (guestfs_h *g,
6233 const char *label);
6234 This command searches the filesystems and returns the one which has the
6236 given label. An error is returned if no such filesystem can be found.
6237 To find the label of a filesystem, use "guestfs_vfs_label".
6239 This function returns a string, or NULL on error. The caller must free
6241 the returned string after use.
6242 (Added in 1.5.3)
6244 guestfs_findfs_uuid
6246 char *
6247 guestfs_findfs_uuid (guestfs_h *g,
6248 const char *uuid);
6249 This command searches the filesystems and returns the one which has the
6251 given UUID. An error is returned if no such filesystem can be found.
6252 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6254 This function returns a string, or NULL on error. The caller must free
6256 the returned string after use.
6257 (Added in 1.5.3)
6259 guestfs_fsck
6261 int
6262 guestfs_fsck (guestfs_h *g,
6263 const char *fstype,
6264 const char *device);
6265 This runs the filesystem checker (fsck) on "device" which should have
6267 filesystem type "fstype".
6268 The returned integer is the status. See fsck(8) for the list of status
6270 codes from "fsck".
6271 Notes:
6273 · Multiple status codes can be summed together.
6275 · A non-zero return code can mean "success", for example if errors
6277 have been corrected on the filesystem.
6278 · Checking or repairing NTFS volumes is not supported (by linux-
6280 ntfs).
6281 This command is entirely equivalent to running "fsck -a -t fstype
6283 device".
6284 On error this function returns -1.
6286 (Added in 1.0.16)
6288 guestfs_fstrim
6290 int
6291 guestfs_fstrim (guestfs_h *g,
6292 const char *mountpoint,
6293 ...);
6294 You may supply a list of optional arguments to this call. Use zero or
6296 more of the following pairs of parameters, and terminate the list with
6297 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6298 GUESTFS_FSTRIM_OFFSET, int64_t offset,
6300 GUESTFS_FSTRIM_LENGTH, int64_t length,
6301 GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6302 Trim the free space in the filesystem mounted on "mountpoint". The
6304 filesystem must be mounted read-write.
6305 The filesystem contents are not affected, but any free space in the
6307 filesystem is "trimmed", that is, given back to the host device, thus
6308 making disk images more sparse, allowing unused space in qcow2 files to
6309 be reused, etc.
6310 This operation requires support in libguestfs, the mounted filesystem,
6312 the host filesystem, qemu and the host kernel. If this support isn't
6313 present it may give an error or even appear to run but do nothing.
6314 In the case where the kernel vfs driver does not support trimming, this
6316 call will fail with errno set to "ENOTSUP". Currently this happens
6317 when trying to trim FAT filesystems.
6318 See also "guestfs_zero_free_space". That is a slightly different
6320 operation that turns free space in the filesystem into zeroes. It is
6321 valid to call "guestfs_fstrim" either instead of, or after calling
6322 "guestfs_zero_free_space".
6323 This function returns 0 on success or -1 on error.
6325 This function depends on the feature "fstrim". See also
6327 "guestfs_feature_available".
6328 (Added in 1.19.6)
6330 guestfs_fstrim_va
6332 int
6333 guestfs_fstrim_va (guestfs_h *g,
6334 const char *mountpoint,
6335 va_list args);
6336 This is the "va_list variant" of "guestfs_fstrim".
6338 See "CALLS WITH OPTIONAL ARGUMENTS".
6340 guestfs_fstrim_argv
6342 int
6343 guestfs_fstrim_argv (guestfs_h *g,
6344 const char *mountpoint,
6345 const struct guestfs_fstrim_argv *optargs);
6346 This is the "argv variant" of "guestfs_fstrim".
6348 See "CALLS WITH OPTIONAL ARGUMENTS".
6350 guestfs_get_append
6352 const char *
6353 guestfs_get_append (guestfs_h *g);
6354 Return the additional kernel options which are added to the libguestfs
6356 appliance kernel command line.
6357 If "NULL" then no options are added.
6359 This function returns a string which may be NULL. There is no way to
6361 return an error from this function. The string is owned by the guest
6362 handle and must not be freed.
6363 (Added in 1.0.26)
6365 guestfs_get_attach_method
6367 char *
6368 guestfs_get_attach_method (guestfs_h *g);
6369 This function is deprecated. In new code, use the
6371 "guestfs_get_backend" call instead.
6372 Deprecated functions will not be removed from the API, but the fact
6374 that they are deprecated indicates that there are problems with correct
6375 use of these functions.
6376 Return the current backend.
6378 See "guestfs_set_backend" and "BACKEND".
6380 This function returns a string, or NULL on error. The caller must free
6382 the returned string after use.
6383 (Added in 1.9.8)
6385 guestfs_get_autosync
6387 int
6388 guestfs_get_autosync (guestfs_h *g);
6389 Get the autosync flag.
6391 This function returns a C truth value on success or -1 on error.
6393 (Added in 0.3)
6395 guestfs_get_backend
6397 char *
6398 guestfs_get_backend (guestfs_h *g);
6399 Return the current backend.
6401 This handle property was previously called the "attach method".
6403 See "guestfs_set_backend" and "BACKEND".
6405 This function returns a string, or NULL on error. The caller must free
6407 the returned string after use.
6408 (Added in 1.21.26)
6410 guestfs_get_backend_setting
6412 char *
6413 guestfs_get_backend_setting (guestfs_h *g,
6414 const char *name);
6415 Find a backend setting string which is either "name" or begins with
6417 "name=". If "name", this returns the string "1". If "name=", this
6418 returns the part after the equals sign (which may be an empty string).
6419 If no such setting is found, this function throws an error. The errno
6421 (see "guestfs_last_errno") will be "ESRCH" in this case.
6422 See "BACKEND", "BACKEND SETTINGS".
6424 This function returns a string, or NULL on error. The caller must free
6426 the returned string after use.
6427 (Added in 1.27.2)
6429 guestfs_get_backend_settings
6431 char **
6432 guestfs_get_backend_settings (guestfs_h *g);
6433 Return the current backend settings.
6435 This call returns all backend settings strings. If you want to find a
6437 single backend setting, see "guestfs_get_backend_setting".
6438 See "BACKEND", "BACKEND SETTINGS".
6440 This function returns a NULL-terminated array of strings (like
6442 environ(3)), or NULL if there was an error. The caller must free the
6443 strings and the array after use.
6444 (Added in 1.25.24)
6446 guestfs_get_cachedir
6448 char *
6449 guestfs_get_cachedir (guestfs_h *g);
6450 Get the directory used by the handle to store the appliance cache.
6452 This function returns a string, or NULL on error. The caller must free
6454 the returned string after use.
6455 (Added in 1.19.58)
6457 guestfs_get_direct
6459 int
6460 guestfs_get_direct (guestfs_h *g);
6461 This function is deprecated. In new code, use the
6463 "guestfs_internal_get_console_socket" call instead.
6464 Deprecated functions will not be removed from the API, but the fact
6466 that they are deprecated indicates that there are problems with correct
6467 use of these functions.
6468 Return the direct appliance mode flag.
6470 This function returns a C truth value on success or -1 on error.
6472 (Added in 1.0.72)
6474 guestfs_get_e2attrs
6476 char *
6477 guestfs_get_e2attrs (guestfs_h *g,
6478 const char *file);
6479 This returns the file attributes associated with file.
6481 The attributes are a set of bits associated with each inode which
6483 affect the behaviour of the file. The attributes are returned as a
6484 string of letters (described below). The string may be empty,
6485 indicating that no file attributes are set for this file.
6486 These attributes are only present when the file is located on an
6488 ext2/3/4 filesystem. Using this call on other filesystem types will
6489 result in an error.
6490 The characters (file attributes) in the returned string are currently:
6492 'A' When the file is accessed, its atime is not modified.
6494 'a' The file is append-only.
6496 'c' The file is compressed on-disk.
6498 'D' (Directories only.) Changes to this directory are written
6500 synchronously to disk.
6501 'd' The file is not a candidate for backup (see dump(8)).
6503 'E' The file has compression errors.
6505 'e' The file is using extents.
6507 'h' The file is storing its blocks in units of the filesystem blocksize
6509 instead of sectors.
6510 'I' (Directories only.) The directory is using hashed trees.
6512 'i' The file is immutable. It cannot be modified, deleted or renamed.
6514 No link can be created to this file.
6515 'j' The file is data-journaled.
6517 's' When the file is deleted, all its blocks will be zeroed.
6519 'S' Changes to this file are written synchronously to disk.
6521 'T' (Directories only.) This is a hint to the block allocator that
6523 subdirectories contained in this directory should be spread across
6524 blocks. If not present, the block allocator will try to group
6525 subdirectories together.
6526 't' For a file, this disables tail-merging. (Not used by upstream
6528 implementations of ext2.)
6529 'u' When the file is deleted, its blocks will be saved, allowing the
6531 file to be undeleted.
6532 'X' The raw contents of the compressed file may be accessed.
6534 'Z' The compressed file is dirty.
6536 More file attributes may be added to this list later. Not all file
6538 attributes may be set for all kinds of files. For detailed
6539 information, consult the chattr(1) man page.
6540 See also "guestfs_set_e2attrs".
6542 Don't confuse these attributes with extended attributes (see
6544 "guestfs_getxattr").
6545 This function returns a string, or NULL on error. The caller must free
6547 the returned string after use.
6548 (Added in 1.17.31)
6550 guestfs_get_e2generation
6552 int64_t
6553 guestfs_get_e2generation (guestfs_h *g,
6554 const char *file);
6555 This returns the ext2 file generation of a file. The generation (which
6557 used to be called the "version") is a number associated with an inode.
6558 This is most commonly used by NFS servers.
6559 The generation is only present when the file is located on an ext2/3/4
6561 filesystem. Using this call on other filesystem types will result in
6562 an error.
6563 See "guestfs_set_e2generation".
6565 On error this function returns -1.
6567 (Added in 1.17.31)
6569 guestfs_get_e2label
6571 char *
6572 guestfs_get_e2label (guestfs_h *g,
6573 const char *device);
6574 This function is deprecated. In new code, use the "guestfs_vfs_label"
6576 call instead.
6577 Deprecated functions will not be removed from the API, but the fact
6579 that they are deprecated indicates that there are problems with correct
6580 use of these functions.
6581 This returns the ext2/3/4 filesystem label of the filesystem on
6583 "device".
6584 This function returns a string, or NULL on error. The caller must free
6586 the returned string after use.
6587 (Added in 1.0.15)
6589 guestfs_get_e2uuid
6591 char *
6592 guestfs_get_e2uuid (guestfs_h *g,
6593 const char *device);
6594 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
6596 call instead.
6597 Deprecated functions will not be removed from the API, but the fact
6599 that they are deprecated indicates that there are problems with correct
6600 use of these functions.
6601 This returns the ext2/3/4 filesystem UUID of the filesystem on
6603 "device".
6604 This function returns a string, or NULL on error. The caller must free
6606 the returned string after use.
6607 (Added in 1.0.15)
6609 guestfs_get_hv
6611 char *
6612 guestfs_get_hv (guestfs_h *g);
6613 Return the current hypervisor binary.
6615 This is always non-NULL. If it wasn't set already, then this will
6617 return the default qemu binary name.
6618 This function returns a string, or NULL on error. The caller must free
6620 the returned string after use.
6621 (Added in 1.23.17)
6623 guestfs_get_identifier
6625 const char *
6626 guestfs_get_identifier (guestfs_h *g);
6627 Get the handle identifier. See "guestfs_set_identifier".
6629 This function returns a string, or NULL on error. The string is owned
6631 by the guest handle and must not be freed.
6632 (Added in 1.31.14)
6634 guestfs_get_libvirt_requested_credential_challenge
6636 char *
6637 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6638 int index);
6639 Get the challenge (provided by libvirt) for the "index"'th requested
6641 credential. If libvirt did not provide a challenge, this returns the
6642 empty string "".
6643 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6645 This function returns a string, or NULL on error. The caller must free
6647 the returned string after use.
6648 (Added in 1.19.52)
6650 guestfs_get_libvirt_requested_credential_defresult
6652 char *
6653 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6654 int index);
6655 Get the default result (provided by libvirt) for the "index"'th
6657 requested credential. If libvirt did not provide a default result,
6658 this returns the empty string "".
6659 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6661 This function returns a string, or NULL on error. The caller must free
6663 the returned string after use.
6664 (Added in 1.19.52)
6666 guestfs_get_libvirt_requested_credential_prompt
6668 char *
6669 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6670 int index);
6671 Get the prompt (provided by libvirt) for the "index"'th requested
6673 credential. If libvirt did not provide a prompt, this returns the
6674 empty string "".
6675 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6677 This function returns a string, or NULL on error. The caller must free
6679 the returned string after use.
6680 (Added in 1.19.52)
6682 guestfs_get_libvirt_requested_credentials
6684 char **
6685 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6686 This should only be called during the event callback for events of type
6688 "GUESTFS_EVENT_LIBVIRT_AUTH".
6689 Return the list of credentials requested by libvirt. Possible values
6691 are a subset of the strings provided when you called
6692 "guestfs_set_libvirt_supported_credentials".
6693 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6695 This function returns a NULL-terminated array of strings (like
6697 environ(3)), or NULL if there was an error. The caller must free the
6698 strings and the array after use.
6699 (Added in 1.19.52)
6701 guestfs_get_memsize
6703 int
6704 guestfs_get_memsize (guestfs_h *g);
6705 This gets the memory size in megabytes allocated to the hypervisor.
6707 If "guestfs_set_memsize" was not called on this handle, and if
6709 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6710 default value for memsize.
6711 For more information on the architecture of libguestfs, see guestfs(3).
6713 On error this function returns -1.
6715 (Added in 1.0.55)
6717 guestfs_get_network
6719 int
6720 guestfs_get_network (guestfs_h *g);
6721 This returns the enable network flag.
6723 This function returns a C truth value on success or -1 on error.
6725 (Added in 1.5.4)
6727 guestfs_get_path
6729 const char *
6730 guestfs_get_path (guestfs_h *g);
6731 Return the current search path.
6733 This is always non-NULL. If it wasn't set already, then this will
6735 return the default path.
6736 This function returns a string, or NULL on error. The string is owned
6738 by the guest handle and must not be freed.
6739 (Added in 0.3)
6741 guestfs_get_pgroup
6743 int
6744 guestfs_get_pgroup (guestfs_h *g);
6745 This returns the process group flag.
6747 This function returns a C truth value on success or -1 on error.
6749 (Added in 1.11.18)
6751 guestfs_get_pid
6753 int
6754 guestfs_get_pid (guestfs_h *g);
6755 Return the process ID of the hypervisor. If there is no hypervisor
6757 running, then this will return an error.
6758 This is an internal call used for debugging and testing.
6760 On error this function returns -1.
6762 (Added in 1.0.56)
6764 guestfs_get_program
6766 const char *
6767 guestfs_get_program (guestfs_h *g);
6768 Get the program name. See "guestfs_set_program".
6770 This function returns a string, or NULL on error. The string is owned
6772 by the guest handle and must not be freed.
6773 (Added in 1.21.29)
6775 guestfs_get_qemu
6777 const char *
6778 guestfs_get_qemu (guestfs_h *g);
6779 This function is deprecated. In new code, use the "guestfs_get_hv"
6781 call instead.
6782 Deprecated functions will not be removed from the API, but the fact
6784 that they are deprecated indicates that there are problems with correct
6785 use of these functions.
6786 Return the current hypervisor binary (usually qemu).
6788 This is always non-NULL. If it wasn't set already, then this will
6790 return the default qemu binary name.
6791 This function returns a string, or NULL on error. The string is owned
6793 by the guest handle and must not be freed.
6794 (Added in 1.0.6)
6796 guestfs_get_recovery_proc
6798 int
6799 guestfs_get_recovery_proc (guestfs_h *g);
6800 Return the recovery process enabled flag.
6802 This function returns a C truth value on success or -1 on error.
6804 (Added in 1.0.77)
6806 guestfs_get_selinux
6808 int
6809 guestfs_get_selinux (guestfs_h *g);
6810 This function is deprecated. In new code, use the
6812 "guestfs_selinux_relabel" call instead.
6813 Deprecated functions will not be removed from the API, but the fact
6815 that they are deprecated indicates that there are problems with correct
6816 use of these functions.
6817 This returns the current setting of the selinux flag which is passed to
6819 the appliance at boot time. See "guestfs_set_selinux".
6820 For more information on the architecture of libguestfs, see guestfs(3).
6822 This function returns a C truth value on success or -1 on error.
6824 (Added in 1.0.67)
6826 guestfs_get_smp
6828 int
6829 guestfs_get_smp (guestfs_h *g);
6830 This returns the number of virtual CPUs assigned to the appliance.
6832 On error this function returns -1.
6834 (Added in 1.13.15)
6836 guestfs_get_sockdir
6838 char *
6839 guestfs_get_sockdir (guestfs_h *g);
6840 Get the directory used by the handle to store temporary socket files.
6842 This is different from "guestfs_get_tmpdir", as we need shorter paths
6844 for sockets (due to the limited buffers of filenames for UNIX sockets),
6845 and "guestfs_get_tmpdir" may be too long for them.
6846 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6848 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6849 the default.
6850 This function returns a string, or NULL on error. The caller must free
6852 the returned string after use.
6853 (Added in 1.33.8)
6855 guestfs_get_state
6857 int
6858 guestfs_get_state (guestfs_h *g);
6859 This returns the current state as an opaque integer. This is only
6861 useful for printing debug and internal error messages.
6862 For more information on states, see guestfs(3).
6864 On error this function returns -1.
6866 (Added in 1.0.2)
6868 guestfs_get_tmpdir
6870 char *
6871 guestfs_get_tmpdir (guestfs_h *g);
6872 Get the directory used by the handle to store temporary files.
6874 This function returns a string, or NULL on error. The caller must free
6876 the returned string after use.
6877 (Added in 1.19.58)
6879 guestfs_get_trace
6881 int
6882 guestfs_get_trace (guestfs_h *g);
6883 Return the command trace flag.
6885 This function returns a C truth value on success or -1 on error.
6887 (Added in 1.0.69)
6889 guestfs_get_umask
6891 int
6892 guestfs_get_umask (guestfs_h *g);
6893 Return the current umask. By default the umask is 022 unless it has
6895 been set by calling "guestfs_umask".
6896 On error this function returns -1.
6898 (Added in 1.3.4)
6900 guestfs_get_verbose
6902 int
6903 guestfs_get_verbose (guestfs_h *g);
6904 This returns the verbose messages flag.
6906 This function returns a C truth value on success or -1 on error.
6908 (Added in 0.3)
6910 guestfs_getcon
6912 char *
6913 guestfs_getcon (guestfs_h *g);
6914 This function is deprecated. In new code, use the
6916 "guestfs_selinux_relabel" call instead.
6917 Deprecated functions will not be removed from the API, but the fact
6919 that they are deprecated indicates that there are problems with correct
6920 use of these functions.
6921 This gets the SELinux security context of the daemon.
6923 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6925 This function returns a string, or NULL on error. The caller must free
6927 the returned string after use.
6928 This function depends on the feature "selinux". See also
6930 "guestfs_feature_available".
6931 (Added in 1.0.67)
6933 guestfs_getxattr
6935 char *
6936 guestfs_getxattr (guestfs_h *g,
6937 const char *path,
6938 const char *name,
6939 size_t *size_r);
6940 Get a single extended attribute from file "path" named "name". This
6942 call follows symlinks. If you want to lookup an extended attribute for
6943 the symlink itself, use "guestfs_lgetxattr".
6944 Normally it is better to get all extended attributes from a file in one
6946 go by calling "guestfs_getxattrs". However some Linux filesystem
6947 implementations are buggy and do not provide a way to list out
6948 attributes. For these filesystems (notably ntfs-3g) you have to know
6949 the names of the extended attributes you want in advance and call this
6950 function.
6951 Extended attribute values are blobs of binary data. If there is no
6953 extended attribute named "name", this returns an error.
6954 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6956 This function returns a buffer, or NULL on error. The size of the
6958 returned buffer is written to *size_r. The caller must free the
6959 returned buffer after use.
6960 This function depends on the feature "linuxxattrs". See also
6962 "guestfs_feature_available".
6963 (Added in 1.7.24)
6965 guestfs_getxattrs
6967 struct guestfs_xattr_list *
6968 guestfs_getxattrs (guestfs_h *g,
6969 const char *path);
6970 This call lists the extended attributes of the file or directory
6972 "path".
6973 At the system call level, this is a combination of the listxattr(2) and
6975 getxattr(2) calls.
6976 See also: "guestfs_lgetxattrs", attr(5).
6978 This function returns a "struct guestfs_xattr_list *", or NULL if there
6980 was an error. The caller must call "guestfs_free_xattr_list" after
6981 use.
6982 This function depends on the feature "linuxxattrs". See also
6984 "guestfs_feature_available".
6985 (Added in 1.0.59)
6987 guestfs_glob_expand
6989 char **
6990 guestfs_glob_expand (guestfs_h *g,
6991 const char *pattern);
6992 This function is provided for backwards compatibility with earlier
6994 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
6995 with no optional arguments.
6996 (Added in 1.0.50)
6998 guestfs_glob_expand_opts
7000 char **
7001 guestfs_glob_expand_opts (guestfs_h *g,
7002 const char *pattern,
7003 ...);
7004 You may supply a list of optional arguments to this call. Use zero or
7006 more of the following pairs of parameters, and terminate the list with
7007 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7008 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
7010 This command searches for all the pathnames matching "pattern"
7012 according to the wildcard expansion rules used by the shell.
7013 If no paths match, then this returns an empty list (note: not an
7015 error).
7016 It is just a wrapper around the C glob(3) function with flags
7018 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
7019 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
7021 and it defaults to true. It can be explicitly set as off to return no
7022 trailing slashes in filenames of directories.
7023 Notice that there is no equivalent command for expanding a device name
7025 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
7026 etc functions instead.
7027 This function returns a NULL-terminated array of strings (like
7029 environ(3)), or NULL if there was an error. The caller must free the
7030 strings and the array after use.
7031 (Added in 1.0.50)
7033 guestfs_glob_expand_opts_va
7035 char **
7036 guestfs_glob_expand_opts_va (guestfs_h *g,
7037 const char *pattern,
7038 va_list args);
7039 This is the "va_list variant" of "guestfs_glob_expand_opts".
7041 See "CALLS WITH OPTIONAL ARGUMENTS".
7043 guestfs_glob_expand_opts_argv
7045 char **
7046 guestfs_glob_expand_opts_argv (guestfs_h *g,
7047 const char *pattern,
7048 const struct guestfs_glob_expand_opts_argv *optargs);
7049 This is the "argv variant" of "guestfs_glob_expand_opts".
7051 See "CALLS WITH OPTIONAL ARGUMENTS".
7053 guestfs_grep
7055 char **
7056 guestfs_grep (guestfs_h *g,
7057 const char *regex,
7058 const char *path);
7059 This function is provided for backwards compatibility with earlier
7061 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
7062 optional arguments.
7063 (Added in 1.0.66)
7065 guestfs_grep_opts
7067 char **
7068 guestfs_grep_opts (guestfs_h *g,
7069 const char *regex,
7070 const char *path,
7071 ...);
7072 You may supply a list of optional arguments to this call. Use zero or
7074 more of the following pairs of parameters, and terminate the list with
7075 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7076 GUESTFS_GREP_OPTS_EXTENDED, int extended,
7078 GUESTFS_GREP_OPTS_FIXED, int fixed,
7079 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
7080 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
7081 This calls the external grep(1) program and returns the matching lines.
7083 The optional flags are:
7085 "extended"
7087 Use extended regular expressions. This is the same as using the -E
7088 flag.
7089 "fixed"
7091 Match fixed (don't use regular expressions). This is the same as
7092 using the -F flag.
7093 "insensitive"
7095 Match case-insensitive. This is the same as using the -i flag.
7096 "compressed"
7098 Use zgrep(1) instead of grep(1). This allows the input to be
7099 compress- or gzip-compressed.
7100 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 Because of the message protocol, there is a transfer limit of somewhere
7106 between 2MB and 4MB. See "PROTOCOL LIMITS".
7107 (Added in 1.0.66)
7109 guestfs_grep_opts_va
7111 char **
7112 guestfs_grep_opts_va (guestfs_h *g,
7113 const char *regex,
7114 const char *path,
7115 va_list args);
7116 This is the "va_list variant" of "guestfs_grep_opts".
7118 See "CALLS WITH OPTIONAL ARGUMENTS".
7120 guestfs_grep_opts_argv
7122 char **
7123 guestfs_grep_opts_argv (guestfs_h *g,
7124 const char *regex,
7125 const char *path,
7126 const struct guestfs_grep_opts_argv *optargs);
7127 This is the "argv variant" of "guestfs_grep_opts".
7129 See "CALLS WITH OPTIONAL ARGUMENTS".
7131 guestfs_grepi
7133 char **
7134 guestfs_grepi (guestfs_h *g,
7135 const char *regex,
7136 const char *path);
7137 This function is deprecated. In new code, use the "guestfs_grep" call
7139 instead.
7140 Deprecated functions will not be removed from the API, but the fact
7142 that they are deprecated indicates that there are problems with correct
7143 use of these functions.
7144 This calls the external "grep -i" program and returns the matching
7146 lines.
7147 This function returns a NULL-terminated array of strings (like
7149 environ(3)), or NULL if there was an error. The caller must free the
7150 strings and the array after use.
7151 Because of the message protocol, there is a transfer limit of somewhere
7153 between 2MB and 4MB. See "PROTOCOL LIMITS".
7154 (Added in 1.0.66)
7156 guestfs_grub_install
7158 int
7159 guestfs_grub_install (guestfs_h *g,
7160 const char *root,
7161 const char *device);
7162 This command installs GRUB 1 (the Grand Unified Bootloader) on
7164 "device", with the root directory being "root".
7165 Notes:
7167 · There is currently no way in the API to install grub2, which is
7169 used by most modern Linux guests. It is possible to run the grub2
7170 command from the guest, although see the caveats in "RUNNING
7171 COMMANDS".
7172 · This uses grub-install(8) from the host. Unfortunately grub is not
7174 always compatible with itself, so this only works in rather narrow
7175 circumstances. Careful testing with each guest version is
7176 advisable.
7177 · If grub-install reports the error "No suitable drive was found in
7179 the generated device map." it may be that you need to create a
7180 /boot/grub/device.map file first that contains the mapping between
7181 grub device names and Linux device names. It is usually sufficient
7182 to create a file containing:
7183 (hd0) /dev/vda
7185 replacing /dev/vda with the name of the installation device.
7187 This function returns 0 on success or -1 on error.
7189 This function depends on the feature "grub". See also
7191 "guestfs_feature_available".
7192 (Added in 1.0.17)
7194 guestfs_head
7196 char **
7197 guestfs_head (guestfs_h *g,
7198 const char *path);
7199 This command returns up to the first 10 lines of a file as a list of
7201 strings.
7202 This function returns a NULL-terminated array of strings (like
7204 environ(3)), or NULL if there was an error. The caller must free the
7205 strings and the array after use.
7206 Because of the message protocol, there is a transfer limit of somewhere
7208 between 2MB and 4MB. See "PROTOCOL LIMITS".
7209 (Added in 1.0.54)
7211 guestfs_head_n
7213 char **
7214 guestfs_head_n (guestfs_h *g,
7215 int nrlines,
7216 const char *path);
7217 If the parameter "nrlines" is a positive number, this returns the first
7219 "nrlines" lines of the file "path".
7220 If the parameter "nrlines" is a negative number, this returns lines
7222 from the file "path", excluding the last "nrlines" lines.
7223 If the parameter "nrlines" is zero, this returns an empty list.
7225 This function returns a NULL-terminated array of strings (like
7227 environ(3)), or NULL if there was an error. The caller must free the
7228 strings and the array after use.
7229 Because of the message protocol, there is a transfer limit of somewhere
7231 between 2MB and 4MB. See "PROTOCOL LIMITS".
7232 (Added in 1.0.54)
7234 guestfs_hexdump
7236 char *
7237 guestfs_hexdump (guestfs_h *g,
7238 const char *path);
7239 This runs "hexdump -C" on the given "path". The result is the human-
7241 readable, canonical hex dump of the file.
7242 This function returns a string, or NULL on error. The caller must free
7244 the returned string after use.
7245 Because of the message protocol, there is a transfer limit of somewhere
7247 between 2MB and 4MB. See "PROTOCOL LIMITS".
7248 (Added in 1.0.22)
7250 guestfs_hivex_close
7252 int
7253 guestfs_hivex_close (guestfs_h *g);
7254 Close the current hivex handle.
7256 This is a wrapper around the hivex(3) call of the same name.
7258 This function returns 0 on success or -1 on error.
7260 This function depends on the feature "hivex". See also
7262 "guestfs_feature_available".
7263 (Added in 1.19.35)
7265 guestfs_hivex_commit
7267 int
7268 guestfs_hivex_commit (guestfs_h *g,
7269 const char *filename);
7270 Commit (write) changes to the hive.
7272 If the optional filename parameter is null, then the changes are
7274 written back to the same hive that was opened. If this is not null
7275 then they are written to the alternate filename given and the original
7276 hive is left untouched.
7277 This is a wrapper around the hivex(3) call of the same name.
7279 This function returns 0 on success or -1 on error.
7281 This function depends on the feature "hivex". See also
7283 "guestfs_feature_available".
7284 (Added in 1.19.35)
7286 guestfs_hivex_node_add_child
7288 int64_t
7289 guestfs_hivex_node_add_child (guestfs_h *g,
7290 int64_t parent,
7291 const char *name);
7292 Add a child node to "parent" named "name".
7294 This is a wrapper around the hivex(3) call of the same name.
7296 On error this function returns -1.
7298 This function depends on the feature "hivex". See also
7300 "guestfs_feature_available".
7301 (Added in 1.19.35)
7303 guestfs_hivex_node_children
7305 struct guestfs_hivex_node_list *
7306 guestfs_hivex_node_children (guestfs_h *g,
7307 int64_t nodeh);
7308 Return the list of nodes which are subkeys of "nodeh".
7310 This is a wrapper around the hivex(3) call of the same name.
7312 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7314 there was an error. The caller must call
7315 "guestfs_free_hivex_node_list" after use.
7316 This function depends on the feature "hivex". See also
7318 "guestfs_feature_available".
7319 (Added in 1.19.35)
7321 guestfs_hivex_node_delete_child
7323 int
7324 guestfs_hivex_node_delete_child (guestfs_h *g,
7325 int64_t nodeh);
7326 Delete "nodeh", recursively if necessary.
7328 This is a wrapper around the hivex(3) call of the same name.
7330 This function returns 0 on success or -1 on error.
7332 This function depends on the feature "hivex". See also
7334 "guestfs_feature_available".
7335 (Added in 1.19.35)
7337 guestfs_hivex_node_get_child
7339 int64_t
7340 guestfs_hivex_node_get_child (guestfs_h *g,
7341 int64_t nodeh,
7342 const char *name);
7343 Return the child of "nodeh" with the name "name", if it exists. This
7345 can return 0 meaning the name was not found.
7346 This is a wrapper around the hivex(3) call of the same name.
7348 On error this function returns -1.
7350 This function depends on the feature "hivex". See also
7352 "guestfs_feature_available".
7353 (Added in 1.19.35)
7355 guestfs_hivex_node_get_value
7357 int64_t
7358 guestfs_hivex_node_get_value (guestfs_h *g,
7359 int64_t nodeh,
7360 const char *key);
7361 Return the value attached to "nodeh" which has the name "key", if it
7363 exists. This can return 0 meaning the key was not found.
7364 This is a wrapper around the hivex(3) call of the same name.
7366 On error this function returns -1.
7368 This function depends on the feature "hivex". See also
7370 "guestfs_feature_available".
7371 (Added in 1.19.35)
7373 guestfs_hivex_node_name
7375 char *
7376 guestfs_hivex_node_name (guestfs_h *g,
7377 int64_t nodeh);
7378 Return the name of "nodeh".
7380 This is a wrapper around the hivex(3) call of the same name.
7382 This function returns a string, or NULL on error. The caller must free
7384 the returned string after use.
7385 This function depends on the feature "hivex". See also
7387 "guestfs_feature_available".
7388 (Added in 1.19.35)
7390 guestfs_hivex_node_parent
7392 int64_t
7393 guestfs_hivex_node_parent (guestfs_h *g,
7394 int64_t nodeh);
7395 Return the parent node of "nodeh".
7397 This is a wrapper around the hivex(3) call of the same name.
7399 On error this function returns -1.
7401 This function depends on the feature "hivex". See also
7403 "guestfs_feature_available".
7404 (Added in 1.19.35)
7406 guestfs_hivex_node_set_value
7408 int
7409 guestfs_hivex_node_set_value (guestfs_h *g,
7410 int64_t nodeh,
7411 const char *key,
7412 int64_t t,
7413 const char *val,
7414 size_t val_size);
7415 Set or replace a single value under the node "nodeh". The "key" is the
7417 name, "t" is the type, and "val" is the data.
7418 This is a wrapper around the hivex(3) call of the same name.
7420 This function returns 0 on success or -1 on error.
7422 This function depends on the feature "hivex". See also
7424 "guestfs_feature_available".
7425 (Added in 1.19.35)
7427 guestfs_hivex_node_values
7429 struct guestfs_hivex_value_list *
7430 guestfs_hivex_node_values (guestfs_h *g,
7431 int64_t nodeh);
7432 Return the array of (key, datatype, data) tuples attached to "nodeh".
7434 This is a wrapper around the hivex(3) call of the same name.
7436 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7438 there was an error. The caller must call
7439 "guestfs_free_hivex_value_list" after use.
7440 This function depends on the feature "hivex". See also
7442 "guestfs_feature_available".
7443 (Added in 1.19.35)
7445 guestfs_hivex_open
7447 int
7448 guestfs_hivex_open (guestfs_h *g,
7449 const char *filename,
7450 ...);
7451 You may supply a list of optional arguments to this call. Use zero or
7453 more of the following pairs of parameters, and terminate the list with
7454 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7455 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7457 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7458 GUESTFS_HIVEX_OPEN_WRITE, int write,
7459 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7460 Open the Windows Registry hive file named filename. If there was any
7462 previous hivex handle associated with this guestfs session, then it is
7463 closed.
7464 This is a wrapper around the hivex(3) call of the same name.
7466 This function returns 0 on success or -1 on error.
7468 This function depends on the feature "hivex". See also
7470 "guestfs_feature_available".
7471 (Added in 1.19.35)
7473 guestfs_hivex_open_va
7475 int
7476 guestfs_hivex_open_va (guestfs_h *g,
7477 const char *filename,
7478 va_list args);
7479 This is the "va_list variant" of "guestfs_hivex_open".
7481 See "CALLS WITH OPTIONAL ARGUMENTS".
7483 guestfs_hivex_open_argv
7485 int
7486 guestfs_hivex_open_argv (guestfs_h *g,
7487 const char *filename,
7488 const struct guestfs_hivex_open_argv *optargs);
7489 This is the "argv variant" of "guestfs_hivex_open".
7491 See "CALLS WITH OPTIONAL ARGUMENTS".
7493 guestfs_hivex_root
7495 int64_t
7496 guestfs_hivex_root (guestfs_h *g);
7497 Return the root node of the hive.
7499 This is a wrapper around the hivex(3) call of the same name.
7501 On error this function returns -1.
7503 This function depends on the feature "hivex". See also
7505 "guestfs_feature_available".
7506 (Added in 1.19.35)
7508 guestfs_hivex_value_key
7510 char *
7511 guestfs_hivex_value_key (guestfs_h *g,
7512 int64_t valueh);
7513 Return the key (name) field of a (key, datatype, data) tuple.
7515 This is a wrapper around the hivex(3) call of the same name.
7517 This function returns a string, or NULL on error. The caller must free
7519 the returned string after use.
7520 This function depends on the feature "hivex". See also
7522 "guestfs_feature_available".
7523 (Added in 1.19.35)
7525 guestfs_hivex_value_string
7527 char *
7528 guestfs_hivex_value_string (guestfs_h *g,
7529 int64_t valueh);
7530 This calls "guestfs_hivex_value_value" (which returns the data field
7532 from a hivex value tuple). It then assumes that the field is a
7533 UTF-16LE string and converts the result to UTF-8 (or if this is not
7534 possible, it returns an error).
7535 This is useful for reading strings out of the Windows registry.
7537 However it is not foolproof because the registry is not strongly-typed
7538 and fields can contain arbitrary or unexpected data.
7539 This function returns a string, or NULL on error. The caller must free
7541 the returned string after use.
7542 This function depends on the feature "hivex". See also
7544 "guestfs_feature_available".
7545 (Added in 1.37.22)
7547 guestfs_hivex_value_type
7549 int64_t
7550 guestfs_hivex_value_type (guestfs_h *g,
7551 int64_t valueh);
7552 Return the data type field from a (key, datatype, data) tuple.
7554 This is a wrapper around the hivex(3) call of the same name.
7556 On error this function returns -1.
7558 This function depends on the feature "hivex". See also
7560 "guestfs_feature_available".
7561 (Added in 1.19.35)
7563 guestfs_hivex_value_utf8
7565 char *
7566 guestfs_hivex_value_utf8 (guestfs_h *g,
7567 int64_t valueh);
7568 This function is deprecated. In new code, use the
7570 "guestfs_hivex_value_string" call instead.
7571 Deprecated functions will not be removed from the API, but the fact
7573 that they are deprecated indicates that there are problems with correct
7574 use of these functions.
7575 This calls "guestfs_hivex_value_value" (which returns the data field
7577 from a hivex value tuple). It then assumes that the field is a
7578 UTF-16LE string and converts the result to UTF-8 (or if this is not
7579 possible, it returns an error).
7580 This is useful for reading strings out of the Windows registry.
7582 However it is not foolproof because the registry is not strongly-typed
7583 and fields can contain arbitrary or unexpected data.
7584 This function returns a string, or NULL on error. The caller must free
7586 the returned string after use.
7587 This function depends on the feature "hivex". See also
7589 "guestfs_feature_available".
7590 (Added in 1.19.35)
7592 guestfs_hivex_value_value
7594 char *
7595 guestfs_hivex_value_value (guestfs_h *g,
7596 int64_t valueh,
7597 size_t *size_r);
7598 Return the data field of a (key, datatype, data) tuple.
7600 This is a wrapper around the hivex(3) call of the same name.
7602 See also: "guestfs_hivex_value_utf8".
7604 This function returns a buffer, or NULL on error. The size of the
7606 returned buffer is written to *size_r. The caller must free the
7607 returned buffer after use.
7608 This function depends on the feature "hivex". See also
7610 "guestfs_feature_available".
7611 (Added in 1.19.35)
7613 guestfs_initrd_cat
7615 char *
7616 guestfs_initrd_cat (guestfs_h *g,
7617 const char *initrdpath,
7618 const char *filename,
7619 size_t *size_r);
7620 This command unpacks the file filename from the initrd file called
7622 initrdpath. The filename must be given without the initial /
7623 character.
7624 For example, in guestfish you could use the following command to
7626 examine the boot script (usually called /init) contained in a Linux
7627 initrd or initramfs image:
7628 initrd-cat /boot/initrd-<version>.img init
7630 See also "guestfs_initrd_list".
7632 This function returns a buffer, or NULL on error. The size of the
7634 returned buffer is written to *size_r. The caller must free the
7635 returned buffer after use.
7636 Because of the message protocol, there is a transfer limit of somewhere
7638 between 2MB and 4MB. See "PROTOCOL LIMITS".
7639 (Added in 1.0.84)
7641 guestfs_initrd_list
7643 char **
7644 guestfs_initrd_list (guestfs_h *g,
7645 const char *path);
7646 This command lists out files contained in an initrd.
7648 The files are listed without any initial / character. The files are
7650 listed in the order they appear (not necessarily alphabetical).
7651 Directory names are listed as separate items.
7652 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7654 as initrd. We only support the newer initramfs format (compressed cpio
7655 files).
7656 This function returns a NULL-terminated array of strings (like
7658 environ(3)), or NULL if there was an error. The caller must free the
7659 strings and the array after use.
7660 (Added in 1.0.54)
7662 guestfs_inotify_add_watch
7664 int64_t
7665 guestfs_inotify_add_watch (guestfs_h *g,
7666 const char *path,
7667 int mask);
7668 Watch "path" for the events listed in "mask".
7670 Note that if "path" is a directory then events within that directory
7672 are watched, but this does not happen recursively (in subdirectories).
7673 Note for non-C or non-Linux callers: the inotify events are defined by
7675 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7676 On error this function returns -1.
7678 This function depends on the feature "inotify". See also
7680 "guestfs_feature_available".
7681 (Added in 1.0.66)
7683 guestfs_inotify_close
7685 int
7686 guestfs_inotify_close (guestfs_h *g);
7687 This closes the inotify handle which was previously opened by
7689 inotify_init. It removes all watches, throws away any pending events,
7690 and deallocates all resources.
7691 This function returns 0 on success or -1 on error.
7693 This function depends on the feature "inotify". See also
7695 "guestfs_feature_available".
7696 (Added in 1.0.66)
7698 guestfs_inotify_files
7700 char **
7701 guestfs_inotify_files (guestfs_h *g);
7702 This function is a helpful wrapper around "guestfs_inotify_read" which
7704 just returns a list of pathnames of objects that were touched. The
7705 returned pathnames are sorted and deduplicated.
7706 This function returns a NULL-terminated array of strings (like
7708 environ(3)), or NULL if there was an error. The caller must free the
7709 strings and the array after use.
7710 This function depends on the feature "inotify". See also
7712 "guestfs_feature_available".
7713 (Added in 1.0.66)
7715 guestfs_inotify_init
7717 int
7718 guestfs_inotify_init (guestfs_h *g,
7719 int maxevents);
7720 This command creates a new inotify handle. The inotify subsystem can
7722 be used to notify events which happen to objects in the guest
7723 filesystem.
7724 "maxevents" is the maximum number of events which will be queued up
7726 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7727 this is passed as 0, then the kernel (or previously set) default is
7728 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7729 limit, the kernel throws away events, but records the fact that it
7730 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7731 structure list (see "guestfs_inotify_read").
7732 Before any events are generated, you have to add some watches to the
7734 internal watch list. See: "guestfs_inotify_add_watch" and
7735 "guestfs_inotify_rm_watch".
7736 Queued up events should be read periodically by calling
7738 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7739 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7740 events out often enough then you risk the internal queue overflowing.
7741 The handle should be closed after use by calling
7743 "guestfs_inotify_close". This also removes any watches automatically.
7744 See also inotify(7) for an overview of the inotify interface as exposed
7746 by the Linux kernel, which is roughly what we expose via libguestfs.
7747 Note that there is one global inotify handle per libguestfs instance.
7748 This function returns 0 on success or -1 on error.
7750 This function depends on the feature "inotify". See also
7752 "guestfs_feature_available".
7753 (Added in 1.0.66)
7755 guestfs_inotify_read
7757 struct guestfs_inotify_event_list *
7758 guestfs_inotify_read (guestfs_h *g);
7759 Return the complete queue of events that have happened since the
7761 previous read call.
7762 If no events have happened, this returns an empty list.
7764 Note: In order to make sure that all events have been read, you must
7766 call this function repeatedly until it returns an empty list. The
7767 reason is that the call will read events up to the maximum appliance-
7768 to-host message size and leave remaining events in the queue.
7769 This function returns a "struct guestfs_inotify_event_list *", or NULL
7771 if there was an error. The caller must call
7772 "guestfs_free_inotify_event_list" after use.
7773 This function depends on the feature "inotify". See also
7775 "guestfs_feature_available".
7776 (Added in 1.0.66)
7778 guestfs_inotify_rm_watch
7780 int
7781 guestfs_inotify_rm_watch (guestfs_h *g,
7782 int wd);
7783 Remove a previously defined inotify watch. See
7785 "guestfs_inotify_add_watch".
7786 This function returns 0 on success or -1 on error.
7788 This function depends on the feature "inotify". See also
7790 "guestfs_feature_available".
7791 (Added in 1.0.66)
7793 guestfs_inspect_get_arch
7795 char *
7796 guestfs_inspect_get_arch (guestfs_h *g,
7797 const char *root);
7798 This returns the architecture of the inspected operating system. The
7800 possible return values are listed under "guestfs_file_architecture".
7801 If the architecture could not be determined, then the string "unknown"
7803 is returned.
7804 Please read "INSPECTION" for more details.
7806 This function returns a string, or NULL on error. The caller must free
7808 the returned string after use.
7809 (Added in 1.5.3)
7811 guestfs_inspect_get_distro
7813 char *
7814 guestfs_inspect_get_distro (guestfs_h *g,
7815 const char *root);
7816 This returns the distro (distribution) of the inspected operating
7818 system.
7819 Currently defined distros are:
7821 "alpinelinux"
7823 Alpine Linux.
7824 "altlinux"
7826 ALT Linux.
7827 "archlinux"
7829 Arch Linux.
7830 "buildroot"
7832 Buildroot-derived distro, but not one we specifically recognize.
7833 "centos"
7835 CentOS.
7836 "cirros"
7838 Cirros.
7839 "coreos"
7841 CoreOS.
7842 "debian"
7844 Debian.
7845 "fedora"
7847 Fedora.
7848 "freebsd"
7850 FreeBSD.
7851 "freedos"
7853 FreeDOS.
7854 "frugalware"
7856 Frugalware.
7857 "gentoo"
7859 Gentoo.
7860 "kalilinux"
7862 Kali Linux.
7863 "linuxmint"
7865 Linux Mint.
7866 "mageia"
7868 Mageia.
7869 "mandriva"
7871 Mandriva.
7872 "meego"
7874 MeeGo.
7875 "msdos"
7877 Microsoft DOS.
7878 "neokylin"
7880 NeoKylin.
7881 "netbsd"
7883 NetBSD.
7884 "openbsd"
7886 OpenBSD.
7887 "openmandriva"
7889 OpenMandriva Lx.
7890 "opensuse"
7892 OpenSUSE.
7893 "oraclelinux"
7895 Oracle Linux.
7896 "pardus"
7898 Pardus.
7899 "pldlinux"
7901 PLD Linux.
7902 "redhat-based"
7904 Some Red Hat-derived distro.
7905 "rhel"
7907 Red Hat Enterprise Linux.
7908 "scientificlinux"
7910 Scientific Linux.
7911 "slackware"
7913 Slackware.
7914 "sles"
7916 SuSE Linux Enterprise Server or Desktop.
7917 "suse-based"
7919 Some openSuSE-derived distro.
7920 "ttylinux"
7922 ttylinux.
7923 "ubuntu"
7925 Ubuntu.
7926 "unknown"
7928 The distro could not be determined.
7929 "voidlinux"
7931 Void Linux.
7932 "windows"
7934 Windows does not have distributions. This string is returned if
7935 the OS type is Windows.
7936 Future versions of libguestfs may return other strings here. The
7938 caller should be prepared to handle any string.
7939 Please read "INSPECTION" for more details.
7941 This function returns a string, or NULL on error. The caller must free
7943 the returned string after use.
7944 (Added in 1.5.3)
7946 guestfs_inspect_get_drive_mappings
7948 char **
7949 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7950 const char *root);
7951 This call is useful for Windows which uses a primitive system of
7953 assigning drive letters (like C:\) to partitions. This inspection API
7954 examines the Windows Registry to find out how disks/partitions are
7955 mapped to drive letters, and returns a hash table as in the example
7956 below:
7957 C => /dev/vda2
7959 E => /dev/vdb1
7960 F => /dev/vdc1
7961 Note that keys are drive letters. For Windows, the key is case
7963 insensitive and just contains the drive letter, without the customary
7964 colon separator character.
7965 In future we may support other operating systems that also used drive
7967 letters, but the keys for those might not be case insensitive and might
7968 be longer than 1 character. For example in OS-9, hard drives were
7969 named "h0", "h1" etc.
7970 For Windows guests, currently only hard drive mappings are returned.
7972 Removable disks (eg. DVD-ROMs) are ignored.
7973 For guests that do not use drive mappings, or if the drive mappings
7975 could not be determined, this returns an empty hash table.
7976 Please read "INSPECTION" for more details. See also
7978 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7979 This function returns a NULL-terminated array of strings, or NULL if
7981 there was an error. The array of strings will always have length
7982 "2n+1", where "n" keys and values alternate, followed by the trailing
7983 NULL entry. The caller must free the strings and the array after use.
7984 (Added in 1.9.17)
7986 guestfs_inspect_get_filesystems
7988 char **
7989 guestfs_inspect_get_filesystems (guestfs_h *g,
7990 const char *root);
7991 This returns a list of all the filesystems that we think are associated
7993 with this operating system. This includes the root filesystem, other
7994 ordinary filesystems, and non-mounted devices like swap partitions.
7995 In the case of a multi-boot virtual machine, it is possible for a
7997 filesystem to be shared between operating systems.
7998 Please read "INSPECTION" for more details. See also
8000 "guestfs_inspect_get_mountpoints".
8001 This function returns a NULL-terminated array of strings (like
8003 environ(3)), or NULL if there was an error. The caller must free the
8004 strings and the array after use.
8005 (Added in 1.5.3)
8007 guestfs_inspect_get_format
8009 char *
8010 guestfs_inspect_get_format (guestfs_h *g,
8011 const char *root);
8012 This function is deprecated. There is no replacement. Consult the API
8014 documentation in guestfs(3) for further information.
8015 Deprecated functions will not be removed from the API, but the fact
8017 that they are deprecated indicates that there are problems with correct
8018 use of these functions.
8019 Before libguestfs 1.38, there was some unreliable support for detecting
8021 installer CDs. This API would return:
8022 "installed"
8024 This is an installed operating system.
8025 "installer"
8027 The disk image being inspected is not an installed operating
8028 system, but a bootable install disk, live CD, or similar.
8029 "unknown"
8031 The format of this disk image is not known.
8032 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
8034 directly to detect installer CDs.
8035 Please read "INSPECTION" for more details.
8037 This function returns a string, or NULL on error. The caller must free
8039 the returned string after use.
8040 (Added in 1.9.4)
8042 guestfs_inspect_get_hostname
8044 char *
8045 guestfs_inspect_get_hostname (guestfs_h *g,
8046 const char *root);
8047 This function returns the hostname of the operating system as found by
8049 inspection of the guest’s configuration files.
8050 If the hostname could not be determined, then the string "unknown" is
8052 returned.
8053 Please read "INSPECTION" for more details.
8055 This function returns a string, or NULL on error. The caller must free
8057 the returned string after use.
8058 (Added in 1.7.9)
8060 guestfs_inspect_get_icon
8062 char *
8063 guestfs_inspect_get_icon (guestfs_h *g,
8064 const char *root,
8065 size_t *size_r,
8066 ...);
8067 You may supply a list of optional arguments to this call. Use zero or
8069 more of the following pairs of parameters, and terminate the list with
8070 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8071 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
8073 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
8074 This function returns an icon corresponding to the inspected operating
8076 system. The icon is returned as a buffer containing a PNG image (re-
8077 encoded to PNG if necessary).
8078 If it was not possible to get an icon this function returns a zero-
8080 length (non-NULL) buffer. Callers must check for this case.
8081 Libguestfs will start by looking for a file called /etc/favicon.png or
8083 C:\etc\favicon.png and if it has the correct format, the contents of
8084 this file will be returned. You can disable favicons by passing the
8085 optional "favicon" boolean as false (default is true).
8086 If finding the favicon fails, then we look in other places in the guest
8088 for a suitable icon.
8089 If the optional "highquality" boolean is true then only high quality
8091 icons are returned, which means only icons of high resolution with an
8092 alpha channel. The default (false) is to return any icon we can, even
8093 if it is of substandard quality.
8094 Notes:
8096 · Unlike most other inspection API calls, the guest’s disks must be
8098 mounted up before you call this, since it needs to read information
8099 from the guest filesystem during the call.
8100 · Security: The icon data comes from the untrusted guest, and should
8102 be treated with caution. PNG files have been known to contain
8103 exploits. Ensure that libpng (or other relevant libraries) are
8104 fully up to date before trying to process or display the icon.
8105 · The PNG image returned can be any size. It might not be square.
8107 Libguestfs tries to return the largest, highest quality icon
8108 available. The application must scale the icon to the required
8109 size.
8110 · Extracting icons from Windows guests requires the external
8112 wrestool(1) program from the "icoutils" package, and several
8113 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
8114 package. These must be installed separately.
8115 · Operating system icons are usually trademarks. Seek legal advice
8117 before using trademarks in applications.
8118 This function returns a buffer, or NULL on error. The size of the
8120 returned buffer is written to *size_r. The caller must free the
8121 returned buffer after use.
8122 (Added in 1.11.12)
8124 guestfs_inspect_get_icon_va
8126 char *
8127 guestfs_inspect_get_icon_va (guestfs_h *g,
8128 const char *root,
8129 size_t *size_r,
8130 va_list args);
8131 This is the "va_list variant" of "guestfs_inspect_get_icon".
8133 See "CALLS WITH OPTIONAL ARGUMENTS".
8135 guestfs_inspect_get_icon_argv
8137 char *
8138 guestfs_inspect_get_icon_argv (guestfs_h *g,
8139 const char *root,
8140 size_t *size_r,
8141 const struct guestfs_inspect_get_icon_argv *optargs);
8142 This is the "argv variant" of "guestfs_inspect_get_icon".
8144 See "CALLS WITH OPTIONAL ARGUMENTS".
8146 guestfs_inspect_get_major_version
8148 int
8149 guestfs_inspect_get_major_version (guestfs_h *g,
8150 const char *root);
8151 This returns the major version number of the inspected operating
8153 system.
8154 Windows uses a consistent versioning scheme which is not reflected in
8156 the popular public names used by the operating system. Notably the
8157 operating system known as "Windows 7" is really version 6.1 (ie. major
8158 = 6, minor = 1). You can find out the real versions corresponding to
8159 releases of Windows by consulting Wikipedia or MSDN.
8160 If the version could not be determined, then 0 is returned.
8162 Please read "INSPECTION" for more details.
8164 On error this function returns -1.
8166 (Added in 1.5.3)
8168 guestfs_inspect_get_minor_version
8170 int
8171 guestfs_inspect_get_minor_version (guestfs_h *g,
8172 const char *root);
8173 This returns the minor version number of the inspected operating
8175 system.
8176 If the version could not be determined, then 0 is returned.
8178 Please read "INSPECTION" for more details. See also
8180 "guestfs_inspect_get_major_version".
8181 On error this function returns -1.
8183 (Added in 1.5.3)
8185 guestfs_inspect_get_mountpoints
8187 char **
8188 guestfs_inspect_get_mountpoints (guestfs_h *g,
8189 const char *root);
8190 This returns a hash of where we think the filesystems associated with
8192 this operating system should be mounted. Callers should note that this
8193 is at best an educated guess made by reading configuration files such
8194 as /etc/fstab. In particular note that this may return filesystems
8195 which are non-existent or not mountable and callers should be prepared
8196 to handle or ignore failures if they try to mount them.
8197 Each element in the returned hashtable has a key which is the path of
8199 the mountpoint (eg. /boot) and a value which is the filesystem that
8200 would be mounted there (eg. /dev/sda1).
8201 Non-mounted devices such as swap devices are not returned in this list.
8203 For operating systems like Windows which still use drive letters, this
8205 call will only return an entry for the first drive "mounted on" /. For
8206 information about the mapping of drive letters to partitions, see
8207 "guestfs_inspect_get_drive_mappings".
8208 Please read "INSPECTION" for more details. See also
8210 "guestfs_inspect_get_filesystems".
8211 This function returns a NULL-terminated array of strings, or NULL if
8213 there was an error. The array of strings will always have length
8214 "2n+1", where "n" keys and values alternate, followed by the trailing
8215 NULL entry. The caller must free the strings and the array after use.
8216 (Added in 1.5.3)
8218 guestfs_inspect_get_osinfo
8220 char *
8221 guestfs_inspect_get_osinfo (guestfs_h *g,
8222 const char *root);
8223 This function returns a possible short ID for libosinfo corresponding
8225 to the guest.
8226 Note: The returned ID is only a guess by libguestfs, and nothing
8228 ensures that it actually exists in osinfo-db.
8229 If no ID could not be determined, then the string "unknown" is
8231 returned.
8232 This function returns a string, or NULL on error. The caller must free
8234 the returned string after use.
8235 (Added in 1.39.1)
8237 guestfs_inspect_get_package_format
8239 char *
8240 guestfs_inspect_get_package_format (guestfs_h *g,
8241 const char *root);
8242 This function and "guestfs_inspect_get_package_management" return the
8244 package format and package management tool used by the inspected
8245 operating system. For example for Fedora these functions would return
8246 "rpm" (package format), and "yum" or "dnf" (package management).
8247 This returns the string "unknown" if we could not determine the package
8249 format or if the operating system does not have a real packaging system
8250 (eg. Windows).
8251 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8253 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
8254 other strings.
8255 Please read "INSPECTION" for more details.
8257 This function returns a string, or NULL on error. The caller must free
8259 the returned string after use.
8260 (Added in 1.7.5)
8262 guestfs_inspect_get_package_management
8264 char *
8265 guestfs_inspect_get_package_management (guestfs_h *g,
8266 const char *root);
8267 "guestfs_inspect_get_package_format" and this function return the
8269 package format and package management tool used by the inspected
8270 operating system. For example for Fedora these functions would return
8271 "rpm" (package format), and "yum" or "dnf" (package management).
8272 This returns the string "unknown" if we could not determine the package
8274 management tool or if the operating system does not have a real
8275 packaging system (eg. Windows).
8276 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8278 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8279 "apk", "xbps". Future versions of libguestfs may return other strings.
8280 Please read "INSPECTION" for more details.
8282 This function returns a string, or NULL on error. The caller must free
8284 the returned string after use.
8285 (Added in 1.7.5)
8287 guestfs_inspect_get_product_name
8289 char *
8290 guestfs_inspect_get_product_name (guestfs_h *g,
8291 const char *root);
8292 This returns the product name of the inspected operating system. The
8294 product name is generally some freeform string which can be displayed
8295 to the user, but should not be parsed by programs.
8296 If the product name could not be determined, then the string "unknown"
8298 is returned.
8299 Please read "INSPECTION" for more details.
8301 This function returns a string, or NULL on error. The caller must free
8303 the returned string after use.
8304 (Added in 1.5.3)
8306 guestfs_inspect_get_product_variant
8308 char *
8309 guestfs_inspect_get_product_variant (guestfs_h *g,
8310 const char *root);
8311 This returns the product variant of the inspected operating system.
8313 For Windows guests, this returns the contents of the Registry key
8315 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8316 which is usually a string such as "Client" or "Server" (other values
8317 are possible). This can be used to distinguish consumer and enterprise
8318 versions of Windows that have the same version number (for example,
8319 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8320 is "Client" and the latter is "Server").
8321 For enterprise Linux guests, in future we intend this to return the
8323 product variant such as "Desktop", "Server" and so on. But this is not
8324 implemented at present.
8325 If the product variant could not be determined, then the string
8327 "unknown" is returned.
8328 Please read "INSPECTION" for more details. See also
8330 "guestfs_inspect_get_product_name",
8331 "guestfs_inspect_get_major_version".
8332 This function returns a string, or NULL on error. The caller must free
8334 the returned string after use.
8335 (Added in 1.9.13)
8337 guestfs_inspect_get_roots
8339 char **
8340 guestfs_inspect_get_roots (guestfs_h *g);
8341 This function is a convenient way to get the list of root devices, as
8343 returned from a previous call to "guestfs_inspect_os", but without
8344 redoing the whole inspection process.
8345 This returns an empty list if either no root devices were found or the
8347 caller has not called "guestfs_inspect_os".
8348 Please read "INSPECTION" for more details.
8350 This function returns a NULL-terminated array of strings (like
8352 environ(3)), or NULL if there was an error. The caller must free the
8353 strings and the array after use.
8354 (Added in 1.7.3)
8356 guestfs_inspect_get_type
8358 char *
8359 guestfs_inspect_get_type (guestfs_h *g,
8360 const char *root);
8361 This returns the type of the inspected operating system. Currently
8363 defined types are:
8364 "linux"
8366 Any Linux-based operating system.
8367 "windows"
8369 Any Microsoft Windows operating system.
8370 "freebsd"
8372 FreeBSD.
8373 "netbsd"
8375 NetBSD.
8376 "openbsd"
8378 OpenBSD.
8379 "hurd"
8381 GNU/Hurd.
8382 "dos"
8384 MS-DOS, FreeDOS and others.
8385 "minix"
8387 MINIX.
8388 "unknown"
8390 The operating system type could not be determined.
8391 Future versions of libguestfs may return other strings here. The
8393 caller should be prepared to handle any string.
8394 Please read "INSPECTION" for more details.
8396 This function returns a string, or NULL on error. The caller must free
8398 the returned string after use.
8399 (Added in 1.5.3)
8401 guestfs_inspect_get_windows_current_control_set
8403 char *
8404 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8405 const char *root);
8406 This returns the Windows CurrentControlSet of the inspected guest. The
8408 CurrentControlSet is a registry key name such as "ControlSet001".
8409 This call assumes that the guest is Windows and that the Registry could
8411 be examined by inspection. If this is not the case then an error is
8412 returned.
8413 Please read "INSPECTION" for more details.
8415 This function returns a string, or NULL on error. The caller must free
8417 the returned string after use.
8418 (Added in 1.9.17)
8420 guestfs_inspect_get_windows_software_hive
8422 char *
8423 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8424 const char *root);
8425 This returns the path to the hive (binary Windows Registry file)
8427 corresponding to HKLM\SOFTWARE.
8428 This call assumes that the guest is Windows and that the guest has a
8430 software hive file with the right name. If this is not the case then
8431 an error is returned. This call does not check that the hive is a
8432 valid Windows Registry hive.
8433 You can use "guestfs_hivex_open" to read or write to the hive.
8435 Please read "INSPECTION" for more details.
8437 This function returns a string, or NULL on error. The caller must free
8439 the returned string after use.
8440 (Added in 1.35.26)
8442 guestfs_inspect_get_windows_system_hive
8444 char *
8445 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8446 const char *root);
8447 This returns the path to the hive (binary Windows Registry file)
8449 corresponding to HKLM\SYSTEM.
8450 This call assumes that the guest is Windows and that the guest has a
8452 system hive file with the right name. If this is not the case then an
8453 error is returned. This call does not check that the hive is a valid
8454 Windows Registry hive.
8455 You can use "guestfs_hivex_open" to read or write to the hive.
8457 Please read "INSPECTION" for more details.
8459 This function returns a string, or NULL on error. The caller must free
8461 the returned string after use.
8462 (Added in 1.35.26)
8464 guestfs_inspect_get_windows_systemroot
8466 char *
8467 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8468 const char *root);
8469 This returns the Windows systemroot of the inspected guest. The
8471 systemroot is a directory path such as /WINDOWS.
8472 This call assumes that the guest is Windows and that the systemroot
8474 could be determined by inspection. If this is not the case then an
8475 error is returned.
8476 Please read "INSPECTION" for more details.
8478 This function returns a string, or NULL on error. The caller must free
8480 the returned string after use.
8481 (Added in 1.5.25)
8483 guestfs_inspect_is_live
8485 int
8486 guestfs_inspect_is_live (guestfs_h *g,
8487 const char *root);
8488 This function is deprecated. There is no replacement. Consult the API
8490 documentation in guestfs(3) for further information.
8491 Deprecated functions will not be removed from the API, but the fact
8493 that they are deprecated indicates that there are problems with correct
8494 use of these functions.
8495 This is deprecated and always returns "false".
8497 Please read "INSPECTION" for more details.
8499 This function returns a C truth value on success or -1 on error.
8501 (Added in 1.9.4)
8503 guestfs_inspect_is_multipart
8505 int
8506 guestfs_inspect_is_multipart (guestfs_h *g,
8507 const char *root);
8508 This function is deprecated. There is no replacement. Consult the API
8510 documentation in guestfs(3) for further information.
8511 Deprecated functions will not be removed from the API, but the fact
8513 that they are deprecated indicates that there are problems with correct
8514 use of these functions.
8515 This is deprecated and always returns "false".
8517 Please read "INSPECTION" for more details.
8519 This function returns a C truth value on success or -1 on error.
8521 (Added in 1.9.4)
8523 guestfs_inspect_is_netinst
8525 int
8526 guestfs_inspect_is_netinst (guestfs_h *g,
8527 const char *root);
8528 This function is deprecated. There is no replacement. Consult the API
8530 documentation in guestfs(3) for further information.
8531 Deprecated functions will not be removed from the API, but the fact
8533 that they are deprecated indicates that there are problems with correct
8534 use of these functions.
8535 This is deprecated and always returns "false".
8537 Please read "INSPECTION" for more details.
8539 This function returns a C truth value on success or -1 on error.
8541 (Added in 1.9.4)
8543 guestfs_inspect_list_applications
8545 struct guestfs_application_list *
8546 guestfs_inspect_list_applications (guestfs_h *g,
8547 const char *root);
8548 This function is deprecated. In new code, use the
8550 "guestfs_inspect_list_applications2" call instead.
8551 Deprecated functions will not be removed from the API, but the fact
8553 that they are deprecated indicates that there are problems with correct
8554 use of these functions.
8555 Return the list of applications installed in the operating system.
8557 Note: This call works differently from other parts of the inspection
8559 API. You have to call "guestfs_inspect_os", then
8560 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8561 calling this. Listing applications is a significantly more difficult
8562 operation which requires access to the full filesystem. Also note that
8563 unlike the other "guestfs_inspect_get_*" calls which are just returning
8564 data cached in the libguestfs handle, this call actually reads parts of
8565 the mounted filesystems during the call.
8566 This returns an empty list if the inspection code was not able to
8568 determine the list of applications.
8569 The application structure contains the following fields:
8571 "app_name"
8573 The name of the application. For Linux guests, this is the package
8574 name.
8575 "app_display_name"
8577 The display name of the application, sometimes localized to the
8578 install language of the guest operating system.
8579 If unavailable this is returned as an empty string "". Callers
8581 needing to display something can use "app_name" instead.
8582 "app_epoch"
8584 For package managers which use epochs, this contains the epoch of
8585 the package (an integer). If unavailable, this is returned as 0.
8586 "app_version"
8588 The version string of the application or package. If unavailable
8589 this is returned as an empty string "".
8590 "app_release"
8592 The release string of the application or package, for package
8593 managers that use this. If unavailable this is returned as an
8594 empty string "".
8595 "app_install_path"
8597 The installation path of the application (on operating systems such
8598 as Windows which use installation paths). This path is in the
8599 format used by the guest operating system, it is not a libguestfs
8600 path.
8601 If unavailable this is returned as an empty string "".
8603 "app_trans_path"
8605 The install path translated into a libguestfs path. If unavailable
8606 this is returned as an empty string "".
8607 "app_publisher"
8609 The name of the publisher of the application, for package managers
8610 that use this. If unavailable this is returned as an empty string
8611 "".
8612 "app_url"
8614 The URL (eg. upstream URL) of the application. If unavailable this
8615 is returned as an empty string "".
8616 "app_source_package"
8618 For packaging systems which support this, the name of the source
8619 package. If unavailable this is returned as an empty string "".
8620 "app_summary"
8622 A short (usually one line) description of the application or
8623 package. If unavailable this is returned as an empty string "".
8624 "app_description"
8626 A longer description of the application or package. If unavailable
8627 this is returned as an empty string "".
8628 Please read "INSPECTION" for more details.
8630 This function returns a "struct guestfs_application_list *", or NULL if
8632 there was an error. The caller must call
8633 "guestfs_free_application_list" after use.
8634 (Added in 1.7.8)
8636 guestfs_inspect_list_applications2
8638 struct guestfs_application2_list *
8639 guestfs_inspect_list_applications2 (guestfs_h *g,
8640 const char *root);
8641 Return the list of applications installed in the operating system.
8643 Note: This call works differently from other parts of the inspection
8645 API. You have to call "guestfs_inspect_os", then
8646 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8647 calling this. Listing applications is a significantly more difficult
8648 operation which requires access to the full filesystem. Also note that
8649 unlike the other "guestfs_inspect_get_*" calls which are just returning
8650 data cached in the libguestfs handle, this call actually reads parts of
8651 the mounted filesystems during the call.
8652 This returns an empty list if the inspection code was not able to
8654 determine the list of applications.
8655 The application structure contains the following fields:
8657 "app2_name"
8659 The name of the application. For Linux guests, this is the package
8660 name.
8661 "app2_display_name"
8663 The display name of the application, sometimes localized to the
8664 install language of the guest operating system.
8665 If unavailable this is returned as an empty string "". Callers
8667 needing to display something can use "app2_name" instead.
8668 "app2_epoch"
8670 For package managers which use epochs, this contains the epoch of
8671 the package (an integer). If unavailable, this is returned as 0.
8672 "app2_version"
8674 The version string of the application or package. If unavailable
8675 this is returned as an empty string "".
8676 "app2_release"
8678 The release string of the application or package, for package
8679 managers that use this. If unavailable this is returned as an
8680 empty string "".
8681 "app2_arch"
8683 The architecture string of the application or package, for package
8684 managers that use this. If unavailable this is returned as an
8685 empty string "".
8686 "app2_install_path"
8688 The installation path of the application (on operating systems such
8689 as Windows which use installation paths). This path is in the
8690 format used by the guest operating system, it is not a libguestfs
8691 path.
8692 If unavailable this is returned as an empty string "".
8694 "app2_trans_path"
8696 The install path translated into a libguestfs path. If unavailable
8697 this is returned as an empty string "".
8698 "app2_publisher"
8700 The name of the publisher of the application, for package managers
8701 that use this. If unavailable this is returned as an empty string
8702 "".
8703 "app2_url"
8705 The URL (eg. upstream URL) of the application. If unavailable this
8706 is returned as an empty string "".
8707 "app2_source_package"
8709 For packaging systems which support this, the name of the source
8710 package. If unavailable this is returned as an empty string "".
8711 "app2_summary"
8713 A short (usually one line) description of the application or
8714 package. If unavailable this is returned as an empty string "".
8715 "app2_description"
8717 A longer description of the application or package. If unavailable
8718 this is returned as an empty string "".
8719 Please read "INSPECTION" for more details.
8721 This function returns a "struct guestfs_application2_list *", or NULL
8723 if there was an error. The caller must call
8724 "guestfs_free_application2_list" after use.
8725 (Added in 1.19.56)
8727 guestfs_inspect_os
8729 char **
8730 guestfs_inspect_os (guestfs_h *g);
8731 This function uses other libguestfs functions and certain heuristics to
8733 inspect the disk(s) (usually disks belonging to a virtual machine),
8734 looking for operating systems.
8735 The list returned is empty if no operating systems were found.
8737 If one operating system was found, then this returns a list with a
8739 single element, which is the name of the root filesystem of this
8740 operating system. It is also possible for this function to return a
8741 list containing more than one element, indicating a dual-boot or multi-
8742 boot virtual machine, with each element being the root filesystem of
8743 one of the operating systems.
8744 You can pass the root string(s) returned to other
8746 "guestfs_inspect_get_*" functions in order to query further information
8747 about each operating system, such as the name and version.
8748 This function uses other libguestfs features such as "guestfs_mount_ro"
8750 and "guestfs_umount_all" in order to mount and unmount filesystems and
8751 look at the contents. This should be called with no disks currently
8752 mounted. The function may also use Augeas, so any existing Augeas
8753 handle will be closed.
8754 This function cannot decrypt encrypted disks. The caller must do that
8756 first (supplying the necessary keys) if the disk is encrypted.
8757 Please read "INSPECTION" for more details.
8759 See also "guestfs_list_filesystems".
8761 This function returns a NULL-terminated array of strings (like
8763 environ(3)), or NULL if there was an error. The caller must free the
8764 strings and the array after use.
8765 (Added in 1.5.3)
8767 guestfs_is_blockdev
8769 int
8770 guestfs_is_blockdev (guestfs_h *g,
8771 const char *path);
8772 This function is provided for backwards compatibility with earlier
8774 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8775 with no optional arguments.
8776 (Added in 1.5.10)
8778 guestfs_is_blockdev_opts
8780 int
8781 guestfs_is_blockdev_opts (guestfs_h *g,
8782 const char *path,
8783 ...);
8784 You may supply a list of optional arguments to this call. Use zero or
8786 more of the following pairs of parameters, and terminate the list with
8787 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8788 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8790 This returns "true" if and only if there is a block device with the
8792 given "path" name.
8793 If the optional flag "followsymlinks" is true, then a symlink (or chain
8795 of symlinks) that ends with a block device also causes the function to
8796 return true.
8797 This call only looks at files within the guest filesystem. Libguestfs
8799 partitions and block devices (eg. /dev/sda) cannot be used as the
8800 "path" parameter of this call.
8801 See also "guestfs_stat".
8803 This function returns a C truth value on success or -1 on error.
8805 (Added in 1.5.10)
8807 guestfs_is_blockdev_opts_va
8809 int
8810 guestfs_is_blockdev_opts_va (guestfs_h *g,
8811 const char *path,
8812 va_list args);
8813 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8815 See "CALLS WITH OPTIONAL ARGUMENTS".
8817 guestfs_is_blockdev_opts_argv
8819 int
8820 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8821 const char *path,
8822 const struct guestfs_is_blockdev_opts_argv *optargs);
8823 This is the "argv variant" of "guestfs_is_blockdev_opts".
8825 See "CALLS WITH OPTIONAL ARGUMENTS".
8827 guestfs_is_busy
8829 int
8830 guestfs_is_busy (guestfs_h *g);
8831 This always returns false. This function is deprecated with no
8833 replacement. Do not use this function.
8834 For more information on states, see guestfs(3).
8836 This function returns a C truth value on success or -1 on error.
8838 (Added in 1.0.2)
8840 guestfs_is_chardev
8842 int
8843 guestfs_is_chardev (guestfs_h *g,
8844 const char *path);
8845 This function is provided for backwards compatibility with earlier
8847 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8848 no optional arguments.
8849 (Added in 1.5.10)
8851 guestfs_is_chardev_opts
8853 int
8854 guestfs_is_chardev_opts (guestfs_h *g,
8855 const char *path,
8856 ...);
8857 You may supply a list of optional arguments to this call. Use zero or
8859 more of the following pairs of parameters, and terminate the list with
8860 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8861 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8863 This returns "true" if and only if there is a character device with the
8865 given "path" name.
8866 If the optional flag "followsymlinks" is true, then a symlink (or chain
8868 of symlinks) that ends with a chardev also causes the function to
8869 return true.
8870 See also "guestfs_stat".
8872 This function returns a C truth value on success or -1 on error.
8874 (Added in 1.5.10)
8876 guestfs_is_chardev_opts_va
8878 int
8879 guestfs_is_chardev_opts_va (guestfs_h *g,
8880 const char *path,
8881 va_list args);
8882 This is the "va_list variant" of "guestfs_is_chardev_opts".
8884 See "CALLS WITH OPTIONAL ARGUMENTS".
8886 guestfs_is_chardev_opts_argv
8888 int
8889 guestfs_is_chardev_opts_argv (guestfs_h *g,
8890 const char *path,
8891 const struct guestfs_is_chardev_opts_argv *optargs);
8892 This is the "argv variant" of "guestfs_is_chardev_opts".
8894 See "CALLS WITH OPTIONAL ARGUMENTS".
8896 guestfs_is_config
8898 int
8899 guestfs_is_config (guestfs_h *g);
8900 This returns true iff this handle is being configured (in the "CONFIG"
8902 state).
8903 For more information on states, see guestfs(3).
8905 This function returns a C truth value on success or -1 on error.
8907 (Added in 1.0.2)
8909 guestfs_is_dir
8911 int
8912 guestfs_is_dir (guestfs_h *g,
8913 const char *path);
8914 This function is provided for backwards compatibility with earlier
8916 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8917 optional arguments.
8918 (Added in 0.8)
8920 guestfs_is_dir_opts
8922 int
8923 guestfs_is_dir_opts (guestfs_h *g,
8924 const char *path,
8925 ...);
8926 You may supply a list of optional arguments to this call. Use zero or
8928 more of the following pairs of parameters, and terminate the list with
8929 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8930 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8932 This returns "true" if and only if there is a directory with the given
8934 "path" name. Note that it returns false for other objects like files.
8935 If the optional flag "followsymlinks" is true, then a symlink (or chain
8937 of symlinks) that ends with a directory also causes the function to
8938 return true.
8939 See also "guestfs_stat".
8941 This function returns a C truth value on success or -1 on error.
8943 (Added in 0.8)
8945 guestfs_is_dir_opts_va
8947 int
8948 guestfs_is_dir_opts_va (guestfs_h *g,
8949 const char *path,
8950 va_list args);
8951 This is the "va_list variant" of "guestfs_is_dir_opts".
8953 See "CALLS WITH OPTIONAL ARGUMENTS".
8955 guestfs_is_dir_opts_argv
8957 int
8958 guestfs_is_dir_opts_argv (guestfs_h *g,
8959 const char *path,
8960 const struct guestfs_is_dir_opts_argv *optargs);
8961 This is the "argv variant" of "guestfs_is_dir_opts".
8963 See "CALLS WITH OPTIONAL ARGUMENTS".
8965 guestfs_is_fifo
8967 int
8968 guestfs_is_fifo (guestfs_h *g,
8969 const char *path);
8970 This function is provided for backwards compatibility with earlier
8972 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8973 optional arguments.
8974 (Added in 1.5.10)
8976 guestfs_is_fifo_opts
8978 int
8979 guestfs_is_fifo_opts (guestfs_h *g,
8980 const char *path,
8981 ...);
8982 You may supply a list of optional arguments to this call. Use zero or
8984 more of the following pairs of parameters, and terminate the list with
8985 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8986 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8988 This returns "true" if and only if there is a FIFO (named pipe) with
8990 the given "path" name.
8991 If the optional flag "followsymlinks" is true, then a symlink (or chain
8993 of symlinks) that ends with a FIFO also causes the function to return
8994 true.
8995 See also "guestfs_stat".
8997 This function returns a C truth value on success or -1 on error.
8999 (Added in 1.5.10)
9001 guestfs_is_fifo_opts_va
9003 int
9004 guestfs_is_fifo_opts_va (guestfs_h *g,
9005 const char *path,
9006 va_list args);
9007 This is the "va_list variant" of "guestfs_is_fifo_opts".
9009 See "CALLS WITH OPTIONAL ARGUMENTS".
9011 guestfs_is_fifo_opts_argv
9013 int
9014 guestfs_is_fifo_opts_argv (guestfs_h *g,
9015 const char *path,
9016 const struct guestfs_is_fifo_opts_argv *optargs);
9017 This is the "argv variant" of "guestfs_is_fifo_opts".
9019 See "CALLS WITH OPTIONAL ARGUMENTS".
9021 guestfs_is_file
9023 int
9024 guestfs_is_file (guestfs_h *g,
9025 const char *path);
9026 This function is provided for backwards compatibility with earlier
9028 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
9029 optional arguments.
9030 (Added in 0.8)
9032 guestfs_is_file_opts
9034 int
9035 guestfs_is_file_opts (guestfs_h *g,
9036 const char *path,
9037 ...);
9038 You may supply a list of optional arguments to this call. Use zero or
9040 more of the following pairs of parameters, and terminate the list with
9041 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9042 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9044 This returns "true" if and only if there is a regular file with the
9046 given "path" name. Note that it returns false for other objects like
9047 directories.
9048 If the optional flag "followsymlinks" is true, then a symlink (or chain
9050 of symlinks) that ends with a file also causes the function to return
9051 true.
9052 See also "guestfs_stat".
9054 This function returns a C truth value on success or -1 on error.
9056 (Added in 0.8)
9058 guestfs_is_file_opts_va
9060 int
9061 guestfs_is_file_opts_va (guestfs_h *g,
9062 const char *path,
9063 va_list args);
9064 This is the "va_list variant" of "guestfs_is_file_opts".
9066 See "CALLS WITH OPTIONAL ARGUMENTS".
9068 guestfs_is_file_opts_argv
9070 int
9071 guestfs_is_file_opts_argv (guestfs_h *g,
9072 const char *path,
9073 const struct guestfs_is_file_opts_argv *optargs);
9074 This is the "argv variant" of "guestfs_is_file_opts".
9076 See "CALLS WITH OPTIONAL ARGUMENTS".
9078 guestfs_is_launching
9080 int
9081 guestfs_is_launching (guestfs_h *g);
9082 This returns true iff this handle is launching the subprocess (in the
9084 "LAUNCHING" state).
9085 For more information on states, see guestfs(3).
9087 This function returns a C truth value on success or -1 on error.
9089 (Added in 1.0.2)
9091 guestfs_is_lv
9093 int
9094 guestfs_is_lv (guestfs_h *g,
9095 const char *mountable);
9096 This command tests whether "mountable" is a logical volume, and returns
9098 true iff this is the case.
9099 This function returns a C truth value on success or -1 on error.
9101 (Added in 1.5.3)
9103 guestfs_is_ready
9105 int
9106 guestfs_is_ready (guestfs_h *g);
9107 This returns true iff this handle is ready to accept commands (in the
9109 "READY" state).
9110 For more information on states, see guestfs(3).
9112 This function returns a C truth value on success or -1 on error.
9114 (Added in 1.0.2)
9116 guestfs_is_socket
9118 int
9119 guestfs_is_socket (guestfs_h *g,
9120 const char *path);
9121 This function is provided for backwards compatibility with earlier
9123 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
9124 no optional arguments.
9125 (Added in 1.5.10)
9127 guestfs_is_socket_opts
9129 int
9130 guestfs_is_socket_opts (guestfs_h *g,
9131 const char *path,
9132 ...);
9133 You may supply a list of optional arguments to this call. Use zero or
9135 more of the following pairs of parameters, and terminate the list with
9136 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9137 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9139 This returns "true" if and only if there is a Unix domain socket with
9141 the given "path" name.
9142 If the optional flag "followsymlinks" is true, then a symlink (or chain
9144 of symlinks) that ends with a socket also causes the function to return
9145 true.
9146 See also "guestfs_stat".
9148 This function returns a C truth value on success or -1 on error.
9150 (Added in 1.5.10)
9152 guestfs_is_socket_opts_va
9154 int
9155 guestfs_is_socket_opts_va (guestfs_h *g,
9156 const char *path,
9157 va_list args);
9158 This is the "va_list variant" of "guestfs_is_socket_opts".
9160 See "CALLS WITH OPTIONAL ARGUMENTS".
9162 guestfs_is_socket_opts_argv
9164 int
9165 guestfs_is_socket_opts_argv (guestfs_h *g,
9166 const char *path,
9167 const struct guestfs_is_socket_opts_argv *optargs);
9168 This is the "argv variant" of "guestfs_is_socket_opts".
9170 See "CALLS WITH OPTIONAL ARGUMENTS".
9172 guestfs_is_symlink
9174 int
9175 guestfs_is_symlink (guestfs_h *g,
9176 const char *path);
9177 This returns "true" if and only if there is a symbolic link with the
9179 given "path" name.
9180 See also "guestfs_stat".
9182 This function returns a C truth value on success or -1 on error.
9184 (Added in 1.5.10)
9186 guestfs_is_whole_device
9188 int
9189 guestfs_is_whole_device (guestfs_h *g,
9190 const char *device);
9191 This returns "true" if and only if "device" refers to a whole block
9193 device. That is, not a partition or a logical device.
9194 This function returns a C truth value on success or -1 on error.
9196 (Added in 1.21.9)
9198 guestfs_is_zero
9200 int
9201 guestfs_is_zero (guestfs_h *g,
9202 const char *path);
9203 This returns true iff the file exists and the file is empty or it
9205 contains all zero bytes.
9206 This function returns a C truth value on success or -1 on error.
9208 (Added in 1.11.8)
9210 guestfs_is_zero_device
9212 int
9213 guestfs_is_zero_device (guestfs_h *g,
9214 const char *device);
9215 This returns true iff the device exists and contains all zero bytes.
9217 Note that for large devices this can take a long time to run.
9219 This function returns a C truth value on success or -1 on error.
9221 (Added in 1.11.8)
9223 guestfs_isoinfo
9225 struct guestfs_isoinfo *
9226 guestfs_isoinfo (guestfs_h *g,
9227 const char *isofile);
9228 This is the same as "guestfs_isoinfo_device" except that it works for
9230 an ISO file located inside some other mounted filesystem. Note that in
9231 the common case where you have added an ISO file as a libguestfs
9232 device, you would not call this. Instead you would call
9233 "guestfs_isoinfo_device".
9234 This function returns a "struct guestfs_isoinfo *", or NULL if there
9236 was an error. The caller must call "guestfs_free_isoinfo" after use.
9237 (Added in 1.17.19)
9239 guestfs_isoinfo_device
9241 struct guestfs_isoinfo *
9242 guestfs_isoinfo_device (guestfs_h *g,
9243 const char *device);
9244 "device" is an ISO device. This returns a struct of information read
9246 from the primary volume descriptor (the ISO equivalent of the
9247 superblock) of the device.
9248 Usually it is more efficient to use the isoinfo(1) command with the -d
9250 option on the host to analyze ISO files, instead of going through
9251 libguestfs.
9252 For information on the primary volume descriptor fields, see
9254 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9255 This function returns a "struct guestfs_isoinfo *", or NULL if there
9257 was an error. The caller must call "guestfs_free_isoinfo" after use.
9258 (Added in 1.17.19)
9260 guestfs_journal_close
9262 int
9263 guestfs_journal_close (guestfs_h *g);
9264 Close the journal handle.
9266 This function returns 0 on success or -1 on error.
9268 This function depends on the feature "journal". See also
9270 "guestfs_feature_available".
9271 (Added in 1.23.11)
9273 guestfs_journal_get
9275 struct guestfs_xattr_list *
9276 guestfs_journal_get (guestfs_h *g);
9277 Read the current journal entry. This returns all the fields in the
9279 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
9280 field name (a string).
9281 The "attrval" is the field value (a binary blob, often but not always a
9283 string). Please note that "attrval" is a byte array, not a
9284 \0-terminated C string.
9285 The length of data may be truncated to the data threshold (see:
9287 "guestfs_journal_set_data_threshold",
9288 "guestfs_journal_get_data_threshold").
9289 If you set the data threshold to unlimited (0) then this call can read
9291 a journal entry of any size, ie. it is not limited by the libguestfs
9292 protocol.
9293 This function returns a "struct guestfs_xattr_list *", or NULL if there
9295 was an error. The caller must call "guestfs_free_xattr_list" after
9296 use.
9297 This function depends on the feature "journal". See also
9299 "guestfs_feature_available".
9300 (Added in 1.23.11)
9302 guestfs_journal_get_data_threshold
9304 int64_t
9305 guestfs_journal_get_data_threshold (guestfs_h *g);
9306 Get the current data threshold for reading journal entries. This is a
9308 hint to the journal that it may truncate data fields to this size when
9309 reading them (note also that it may not truncate them). If this
9310 returns 0, then the threshold is unlimited.
9311 See also "guestfs_journal_set_data_threshold".
9313 On error this function returns -1.
9315 This function depends on the feature "journal". See also
9317 "guestfs_feature_available".
9318 (Added in 1.23.11)
9320 guestfs_journal_get_realtime_usec
9322 int64_t
9323 guestfs_journal_get_realtime_usec (guestfs_h *g);
9324 Get the realtime (wallclock) timestamp of the current journal entry.
9326 On error this function returns -1.
9328 This function depends on the feature "journal". See also
9330 "guestfs_feature_available".
9331 (Added in 1.27.18)
9333 guestfs_journal_next
9335 int
9336 guestfs_journal_next (guestfs_h *g);
9337 Move to the next journal entry. You have to call this at least once
9339 after opening the handle before you are able to read data.
9340 The returned boolean tells you if there are any more journal records to
9342 read. "true" means you can read the next record (eg. using
9343 "guestfs_journal_get"), and "false" means you have reached the end of
9344 the journal.
9345 This function returns a C truth value on success or -1 on error.
9347 This function depends on the feature "journal". See also
9349 "guestfs_feature_available".
9350 (Added in 1.23.11)
9352 guestfs_journal_open
9354 int
9355 guestfs_journal_open (guestfs_h *g,
9356 const char *directory);
9357 Open the systemd journal located in directory. Any previously opened
9359 journal handle is closed.
9360 The contents of the journal can be read using "guestfs_journal_next"
9362 and "guestfs_journal_get".
9363 After you have finished using the journal, you should close the handle
9365 by calling "guestfs_journal_close".
9366 This function returns 0 on success or -1 on error.
9368 This function depends on the feature "journal". See also
9370 "guestfs_feature_available".
9371 (Added in 1.23.11)
9373 guestfs_journal_set_data_threshold
9375 int
9376 guestfs_journal_set_data_threshold (guestfs_h *g,
9377 int64_t threshold);
9378 Set the data threshold for reading journal entries. This is a hint to
9380 the journal that it may truncate data fields to this size when reading
9381 them (note also that it may not truncate them). If you set this to 0,
9382 then the threshold is unlimited.
9383 See also "guestfs_journal_get_data_threshold".
9385 This function returns 0 on success or -1 on error.
9387 This function depends on the feature "journal". See also
9389 "guestfs_feature_available".
9390 (Added in 1.23.11)
9392 guestfs_journal_skip
9394 int64_t
9395 guestfs_journal_skip (guestfs_h *g,
9396 int64_t skip);
9397 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9399 The number of entries actually skipped is returned (note "rskip ≥ 0").
9401 If this is not the same as the absolute value of the skip parameter
9402 ("|skip|") you passed in then it means you have reached the end or the
9403 start of the journal.
9404 On error this function returns -1.
9406 This function depends on the feature "journal". See also
9408 "guestfs_feature_available".
9409 (Added in 1.23.11)
9411 guestfs_kill_subprocess
9413 int
9414 guestfs_kill_subprocess (guestfs_h *g);
9415 This function is deprecated. In new code, use the "guestfs_shutdown"
9417 call instead.
9418 Deprecated functions will not be removed from the API, but the fact
9420 that they are deprecated indicates that there are problems with correct
9421 use of these functions.
9422 This kills the hypervisor.
9424 Do not call this. See: "guestfs_shutdown" instead.
9426 This function returns 0 on success or -1 on error.
9428 (Added in 0.3)
9430 guestfs_launch
9432 int
9433 guestfs_launch (guestfs_h *g);
9434 You should call this after configuring the handle (eg. adding drives)
9436 but before performing any actions.
9437 Do not call "guestfs_launch" twice on the same handle. Although it
9439 will not give an error (for historical reasons), the precise behaviour
9440 when you do this is not well defined. Handles are very cheap to
9441 create, so create a new one for each launch.
9442 This function returns 0 on success or -1 on error.
9444 This long-running command can generate progress notification messages
9446 so that the caller can display a progress bar or indicator. To receive
9447 these messages, the caller must register a progress event callback.
9448 See "GUESTFS_EVENT_PROGRESS".
9449 (Added in 0.3)
9451 guestfs_lchown
9453 int
9454 guestfs_lchown (guestfs_h *g,
9455 int owner,
9456 int group,
9457 const char *path);
9458 Change the file owner to "owner" and group to "group". This is like
9460 "guestfs_chown" but if "path" is a symlink then the link itself is
9461 changed, not the target.
9462 Only numeric uid and gid are supported. If you want to use names, you
9464 will need to locate and parse the password file yourself (Augeas
9465 support makes this relatively easy).
9466 This function returns 0 on success or -1 on error.
9468 (Added in 1.0.77)
9470 guestfs_ldmtool_create_all
9472 int
9473 guestfs_ldmtool_create_all (guestfs_h *g);
9474 This function scans all block devices looking for Windows dynamic disk
9476 volumes and partitions, and creates devices for any that were found.
9477 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9479 return all devices.
9480 Note that you don't normally need to call this explicitly, since it is
9482 done automatically at "guestfs_launch" time. However you might want to
9483 call this function if you have hotplugged disks or have just created a
9484 Windows dynamic disk.
9485 This function returns 0 on success or -1 on error.
9487 This function depends on the feature "ldm". See also
9489 "guestfs_feature_available".
9490 (Added in 1.20.0)
9492 guestfs_ldmtool_diskgroup_disks
9494 char **
9495 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9496 const char *diskgroup);
9497 Return the disks in a Windows dynamic disk group. The "diskgroup"
9499 parameter should be the GUID of a disk group, one element from the list
9500 returned by "guestfs_ldmtool_scan".
9501 This function returns a NULL-terminated array of strings (like
9503 environ(3)), or NULL if there was an error. The caller must free the
9504 strings and the array after use.
9505 This function depends on the feature "ldm". See also
9507 "guestfs_feature_available".
9508 (Added in 1.20.0)
9510 guestfs_ldmtool_diskgroup_name
9512 char *
9513 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9514 const char *diskgroup);
9515 Return the name of a Windows dynamic disk group. The "diskgroup"
9517 parameter should be the GUID of a disk group, one element from the list
9518 returned by "guestfs_ldmtool_scan".
9519 This function returns a string, or NULL on error. The caller must free
9521 the returned string after use.
9522 This function depends on the feature "ldm". See also
9524 "guestfs_feature_available".
9525 (Added in 1.20.0)
9527 guestfs_ldmtool_diskgroup_volumes
9529 char **
9530 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9531 const char *diskgroup);
9532 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9534 parameter should be the GUID of a disk group, one element from the list
9535 returned by "guestfs_ldmtool_scan".
9536 This function returns a NULL-terminated array of strings (like
9538 environ(3)), or NULL if there was an error. The caller must free the
9539 strings and the array after use.
9540 This function depends on the feature "ldm". See also
9542 "guestfs_feature_available".
9543 (Added in 1.20.0)
9545 guestfs_ldmtool_remove_all
9547 int
9548 guestfs_ldmtool_remove_all (guestfs_h *g);
9549 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9551 removes the device mapper mappings for all Windows dynamic disk volumes
9552 This function returns 0 on success or -1 on error.
9554 This function depends on the feature "ldm". See also
9556 "guestfs_feature_available".
9557 (Added in 1.20.0)
9559 guestfs_ldmtool_scan
9561 char **
9562 guestfs_ldmtool_scan (guestfs_h *g);
9563 This function scans for Windows dynamic disks. It returns a list of
9565 identifiers (GUIDs) for all disk groups that were found. These
9566 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9567 This function scans all block devices. To scan a subset of block
9569 devices, call "guestfs_ldmtool_scan_devices" instead.
9570 This function returns a NULL-terminated array of strings (like
9572 environ(3)), or NULL if there was an error. The caller must free the
9573 strings and the array after use.
9574 This function depends on the feature "ldm". See also
9576 "guestfs_feature_available".
9577 (Added in 1.20.0)
9579 guestfs_ldmtool_scan_devices
9581 char **
9582 guestfs_ldmtool_scan_devices (guestfs_h *g,
9583 char *const *devices);
9584 This function scans for Windows dynamic disks. It returns a list of
9586 identifiers (GUIDs) for all disk groups that were found. These
9587 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9588 The parameter "devices" is a list of block devices which are scanned.
9590 If this list is empty, all block devices are scanned.
9591 This function returns a NULL-terminated array of strings (like
9593 environ(3)), or NULL if there was an error. The caller must free the
9594 strings and the array after use.
9595 This function depends on the feature "ldm". See also
9597 "guestfs_feature_available".
9598 (Added in 1.20.0)
9600 guestfs_ldmtool_volume_hint
9602 char *
9603 guestfs_ldmtool_volume_hint (guestfs_h *g,
9604 const char *diskgroup,
9605 const char *volume);
9606 Return the hint field of the volume named "volume" in the disk group
9608 with GUID "diskgroup". This may not be defined, in which case the
9609 empty string is returned. The hint field is often, though not always,
9610 the name of a Windows drive, eg. "E:".
9611 This function returns a string, or NULL on error. The caller must free
9613 the returned string after use.
9614 This function depends on the feature "ldm". See also
9616 "guestfs_feature_available".
9617 (Added in 1.20.0)
9619 guestfs_ldmtool_volume_partitions
9621 char **
9622 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9623 const char *diskgroup,
9624 const char *volume);
9625 Return the list of partitions in the volume named "volume" in the disk
9627 group with GUID "diskgroup".
9628 This function returns a NULL-terminated array of strings (like
9630 environ(3)), or NULL if there was an error. The caller must free the
9631 strings and the array after use.
9632 This function depends on the feature "ldm". See also
9634 "guestfs_feature_available".
9635 (Added in 1.20.0)
9637 guestfs_ldmtool_volume_type
9639 char *
9640 guestfs_ldmtool_volume_type (guestfs_h *g,
9641 const char *diskgroup,
9642 const char *volume);
9643 Return the type of the volume named "volume" in the disk group with
9645 GUID "diskgroup".
9646 Possible volume types that can be returned here include: "simple",
9648 "spanned", "striped", "mirrored", "raid5". Other types may also be
9649 returned.
9650 This function returns a string, or NULL on error. The caller must free
9652 the returned string after use.
9653 This function depends on the feature "ldm". See also
9655 "guestfs_feature_available".
9656 (Added in 1.20.0)
9658 guestfs_lgetxattr
9660 char *
9661 guestfs_lgetxattr (guestfs_h *g,
9662 const char *path,
9663 const char *name,
9664 size_t *size_r);
9665 Get a single extended attribute from file "path" named "name". If
9667 "path" is a symlink, then this call returns an extended attribute from
9668 the symlink.
9669 Normally it is better to get all extended attributes from a file in one
9671 go by calling "guestfs_getxattrs". However some Linux filesystem
9672 implementations are buggy and do not provide a way to list out
9673 attributes. For these filesystems (notably ntfs-3g) you have to know
9674 the names of the extended attributes you want in advance and call this
9675 function.
9676 Extended attribute values are blobs of binary data. If there is no
9678 extended attribute named "name", this returns an error.
9679 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9681 This function returns a buffer, or NULL on error. The size of the
9683 returned buffer is written to *size_r. The caller must free the
9684 returned buffer after use.
9685 This function depends on the feature "linuxxattrs". See also
9687 "guestfs_feature_available".
9688 (Added in 1.7.24)
9690 guestfs_lgetxattrs
9692 struct guestfs_xattr_list *
9693 guestfs_lgetxattrs (guestfs_h *g,
9694 const char *path);
9695 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9697 link, then it returns the extended attributes of the link itself.
9698 This function returns a "struct guestfs_xattr_list *", or NULL if there
9700 was an error. The caller must call "guestfs_free_xattr_list" after
9701 use.
9702 This function depends on the feature "linuxxattrs". See also
9704 "guestfs_feature_available".
9705 (Added in 1.0.59)
9707 guestfs_list_9p
9709 char **
9710 guestfs_list_9p (guestfs_h *g);
9711 List all 9p filesystems attached to the guest. A list of mount tags is
9713 returned.
9714 This function returns a NULL-terminated array of strings (like
9716 environ(3)), or NULL if there was an error. The caller must free the
9717 strings and the array after use.
9718 (Added in 1.11.12)
9720 guestfs_list_devices
9722 char **
9723 guestfs_list_devices (guestfs_h *g);
9724 List all the block devices.
9726 The full block device names are returned, eg. /dev/sda.
9728 See also "guestfs_list_filesystems".
9730 This function returns a NULL-terminated array of strings (like
9732 environ(3)), or NULL if there was an error. The caller must free the
9733 strings and the array after use.
9734 (Added in 0.4)
9736 guestfs_list_disk_labels
9738 char **
9739 guestfs_list_disk_labels (guestfs_h *g);
9740 If you add drives using the optional "label" parameter of
9742 "guestfs_add_drive_opts", you can use this call to map between disk
9743 labels, and raw block device and partition names (like /dev/sda and
9744 /dev/sda1).
9745 This returns a hashtable, where keys are the disk labels (without the
9747 /dev/disk/guestfs prefix), and the values are the full raw block device
9748 and partition names (eg. /dev/sda and /dev/sda1).
9749 This function returns a NULL-terminated array of strings, or NULL if
9751 there was an error. The array of strings will always have length
9752 "2n+1", where "n" keys and values alternate, followed by the trailing
9753 NULL entry. The caller must free the strings and the array after use.
9754 (Added in 1.19.49)
9756 guestfs_list_dm_devices
9758 char **
9759 guestfs_list_dm_devices (guestfs_h *g);
9760 List all device mapper devices.
9762 The returned list contains /dev/mapper/* devices, eg. ones created by a
9764 previous call to "guestfs_luks_open".
9765 Device mapper devices which correspond to logical volumes are not
9767 returned in this list. Call "guestfs_lvs" if you want to list logical
9768 volumes.
9769 This function returns a NULL-terminated array of strings (like
9771 environ(3)), or NULL if there was an error. The caller must free the
9772 strings and the array after use.
9773 (Added in 1.11.15)
9775 guestfs_list_filesystems
9777 char **
9778 guestfs_list_filesystems (guestfs_h *g);
9779 This inspection command looks for filesystems on partitions, block
9781 devices and logical volumes, returning a list of "mountables"
9782 containing filesystems and their type.
9783 The return value is a hash, where the keys are the devices containing
9785 filesystems, and the values are the filesystem types. For example:
9786 "/dev/sda1" => "ntfs"
9788 "/dev/sda2" => "ext2"
9789 "/dev/vg_guest/lv_root" => "ext4"
9790 "/dev/vg_guest/lv_swap" => "swap"
9791 The key is not necessarily a block device. It may also be an opaque
9793 ‘mountable’ string which can be passed to "guestfs_mount".
9794 The value can have the special value "unknown", meaning the content of
9796 the device is undetermined or empty. "swap" means a Linux swap
9797 partition.
9798 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9800 might have included "guestfs_mount" and "guestfs_umount", and therefore
9801 you had to use this soon after launch and only when nothing else was
9802 mounted. This restriction is removed in libguestfs ≥ 1.38.
9803 Not all of the filesystems returned will be mountable. In particular,
9805 swap partitions are returned in the list. Also this command does not
9806 check that each filesystem found is valid and mountable, and some
9807 filesystems might be mountable but require special options.
9808 Filesystems may not all belong to a single logical operating system
9809 (use "guestfs_inspect_os" to look for OSes).
9810 This function returns a NULL-terminated array of strings, or NULL if
9812 there was an error. The array of strings will always have length
9813 "2n+1", where "n" keys and values alternate, followed by the trailing
9814 NULL entry. The caller must free the strings and the array after use.
9815 (Added in 1.5.15)
9817 guestfs_list_ldm_partitions
9819 char **
9820 guestfs_list_ldm_partitions (guestfs_h *g);
9821 This function returns all Windows dynamic disk partitions that were
9823 found at launch time. It returns a list of device names.
9824 This function returns a NULL-terminated array of strings (like
9826 environ(3)), or NULL if there was an error. The caller must free the
9827 strings and the array after use.
9828 This function depends on the feature "ldm". See also
9830 "guestfs_feature_available".
9831 (Added in 1.20.0)
9833 guestfs_list_ldm_volumes
9835 char **
9836 guestfs_list_ldm_volumes (guestfs_h *g);
9837 This function returns all Windows dynamic disk volumes that were found
9839 at launch time. It returns a list of device names.
9840 This function returns a NULL-terminated array of strings (like
9842 environ(3)), or NULL if there was an error. The caller must free the
9843 strings and the array after use.
9844 This function depends on the feature "ldm". See also
9846 "guestfs_feature_available".
9847 (Added in 1.20.0)
9849 guestfs_list_md_devices
9851 char **
9852 guestfs_list_md_devices (guestfs_h *g);
9853 List all Linux md devices.
9855 This function returns a NULL-terminated array of strings (like
9857 environ(3)), or NULL if there was an error. The caller must free the
9858 strings and the array after use.
9859 (Added in 1.15.4)
9861 guestfs_list_partitions
9863 char **
9864 guestfs_list_partitions (guestfs_h *g);
9865 List all the partitions detected on all block devices.
9867 The full partition device names are returned, eg. /dev/sda1
9869 This does not return logical volumes. For that you will need to call
9871 "guestfs_lvs".
9872 See also "guestfs_list_filesystems".
9874 This function returns a NULL-terminated array of strings (like
9876 environ(3)), or NULL if there was an error. The caller must free the
9877 strings and the array after use.
9878 (Added in 0.4)
9880 guestfs_ll
9882 char *
9883 guestfs_ll (guestfs_h *g,
9884 const char *directory);
9885 List the files in directory (relative to the root directory, there is
9887 no cwd) in the format of "ls -la".
9888 This command is mostly useful for interactive sessions. It is not
9890 intended that you try to parse the output string.
9891 This function returns a string, or NULL on error. The caller must free
9893 the returned string after use.
9894 (Added in 0.4)
9896 guestfs_llz
9898 char *
9899 guestfs_llz (guestfs_h *g,
9900 const char *directory);
9901 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9903 call instead.
9904 Deprecated functions will not be removed from the API, but the fact
9906 that they are deprecated indicates that there are problems with correct
9907 use of these functions.
9908 List the files in directory in the format of "ls -laZ".
9910 This command is mostly useful for interactive sessions. It is not
9912 intended that you try to parse the output string.
9913 This function returns a string, or NULL on error. The caller must free
9915 the returned string after use.
9916 (Added in 1.17.6)
9918 guestfs_ln
9920 int
9921 guestfs_ln (guestfs_h *g,
9922 const char *target,
9923 const char *linkname);
9924 This command creates a hard link.
9926 This function returns 0 on success or -1 on error.
9928 (Added in 1.0.66)
9930 guestfs_ln_f
9932 int
9933 guestfs_ln_f (guestfs_h *g,
9934 const char *target,
9935 const char *linkname);
9936 This command creates a hard link, removing the link "linkname" if it
9938 exists already.
9939 This function returns 0 on success or -1 on error.
9941 (Added in 1.0.66)
9943 guestfs_ln_s
9945 int
9946 guestfs_ln_s (guestfs_h *g,
9947 const char *target,
9948 const char *linkname);
9949 This command creates a symbolic link using the "ln -s" command.
9951 This function returns 0 on success or -1 on error.
9953 (Added in 1.0.66)
9955 guestfs_ln_sf
9957 int
9958 guestfs_ln_sf (guestfs_h *g,
9959 const char *target,
9960 const char *linkname);
9961 This command creates a symbolic link using the "ln -sf" command, The -f
9963 option removes the link ("linkname") if it exists already.
9964 This function returns 0 on success or -1 on error.
9966 (Added in 1.0.66)
9968 guestfs_lremovexattr
9970 int
9971 guestfs_lremovexattr (guestfs_h *g,
9972 const char *xattr,
9973 const char *path);
9974 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9976 link, then it removes an extended attribute of the link itself.
9977 This function returns 0 on success or -1 on error.
9979 This function depends on the feature "linuxxattrs". See also
9981 "guestfs_feature_available".
9982 (Added in 1.0.59)
9984 guestfs_ls
9986 char **
9987 guestfs_ls (guestfs_h *g,
9988 const char *directory);
9989 List the files in directory (relative to the root directory, there is
9991 no cwd). The "." and ".." entries are not returned, but hidden files
9992 are shown.
9993 This function returns a NULL-terminated array of strings (like
9995 environ(3)), or NULL if there was an error. The caller must free the
9996 strings and the array after use.
9997 (Added in 0.4)
9999 guestfs_ls0
10001 int
10002 guestfs_ls0 (guestfs_h *g,
10003 const char *dir,
10004 const char *filenames);
10005 This specialized command is used to get a listing of the filenames in
10007 the directory "dir". The list of filenames is written to the local
10008 file filenames (on the host).
10009 In the output file, the filenames are separated by "\0" characters.
10011 "." and ".." are not returned. The filenames are not sorted.
10013 This function returns 0 on success or -1 on error.
10015 (Added in 1.19.32)
10017 guestfs_lsetxattr
10019 int
10020 guestfs_lsetxattr (guestfs_h *g,
10021 const char *xattr,
10022 const char *val,
10023 int vallen,
10024 const char *path);
10025 This is the same as "guestfs_setxattr", but if "path" is a symbolic
10027 link, then it sets an extended attribute of the link itself.
10028 This function returns 0 on success or -1 on error.
10030 This function depends on the feature "linuxxattrs". See also
10032 "guestfs_feature_available".
10033 (Added in 1.0.59)
10035 guestfs_lstat
10037 struct guestfs_stat *
10038 guestfs_lstat (guestfs_h *g,
10039 const char *path);
10040 This function is deprecated. In new code, use the "guestfs_lstatns"
10042 call instead.
10043 Deprecated functions will not be removed from the API, but the fact
10045 that they are deprecated indicates that there are problems with correct
10046 use of these functions.
10047 Returns file information for the given "path".
10049 This is the same as "guestfs_stat" except that if "path" is a symbolic
10051 link, then the link is stat-ed, not the file it refers to.
10052 This is the same as the lstat(2) system call.
10054 This function returns a "struct guestfs_stat *", or NULL if there was
10056 an error. The caller must call "guestfs_free_stat" after use.
10057 (Added in 1.9.2)
10059 guestfs_lstatlist
10061 struct guestfs_stat_list *
10062 guestfs_lstatlist (guestfs_h *g,
10063 const char *path,
10064 char *const *names);
10065 This function is deprecated. In new code, use the
10067 "guestfs_lstatnslist" call instead.
10068 Deprecated functions will not be removed from the API, but the fact
10070 that they are deprecated indicates that there are problems with correct
10071 use of these functions.
10072 This call allows you to perform the "guestfs_lstat" operation on
10074 multiple files, where all files are in the directory "path". "names"
10075 is the list of files from this directory.
10076 On return you get a list of stat structs, with a one-to-one
10078 correspondence to the "names" list. If any name did not exist or could
10079 not be lstat'd, then the "st_ino" field of that structure is set to
10080 "-1".
10081 This call is intended for programs that want to efficiently list a
10083 directory contents without making many round-trips. See also
10084 "guestfs_lxattrlist" for a similarly efficient call for getting
10085 extended attributes.
10086 This function returns a "struct guestfs_stat_list *", or NULL if there
10088 was an error. The caller must call "guestfs_free_stat_list" after use.
10089 (Added in 1.0.77)
10091 guestfs_lstatns
10093 struct guestfs_statns *
10094 guestfs_lstatns (guestfs_h *g,
10095 const char *path);
10096 Returns file information for the given "path".
10098 This is the same as "guestfs_statns" except that if "path" is a
10100 symbolic link, then the link is stat-ed, not the file it refers to.
10101 This is the same as the lstat(2) system call.
10103 This function returns a "struct guestfs_statns *", or NULL if there was
10105 an error. The caller must call "guestfs_free_statns" after use.
10106 (Added in 1.27.53)
10108 guestfs_lstatnslist
10110 struct guestfs_statns_list *
10111 guestfs_lstatnslist (guestfs_h *g,
10112 const char *path,
10113 char *const *names);
10114 This call allows you to perform the "guestfs_lstatns" operation on
10116 multiple files, where all files are in the directory "path". "names"
10117 is the list of files from this directory.
10118 On return you get a list of stat structs, with a one-to-one
10120 correspondence to the "names" list. If any name did not exist or could
10121 not be lstat'd, then the "st_ino" field of that structure is set to
10122 "-1".
10123 This call is intended for programs that want to efficiently list a
10125 directory contents without making many round-trips. See also
10126 "guestfs_lxattrlist" for a similarly efficient call for getting
10127 extended attributes.
10128 This function returns a "struct guestfs_statns_list *", or NULL if
10130 there was an error. The caller must call "guestfs_free_statns_list"
10131 after use.
10132 (Added in 1.27.53)
10134 guestfs_luks_add_key
10136 int
10137 guestfs_luks_add_key (guestfs_h *g,
10138 const char *device,
10139 const char *key,
10140 const char *newkey,
10141 int keyslot);
10142 This command adds a new key on LUKS device "device". "key" is any
10144 existing key, and is used to access the device. "newkey" is the new
10145 key to add. "keyslot" is the key slot that will be replaced.
10146 Note that if "keyslot" already contains a key, then this command will
10148 fail. You have to use "guestfs_luks_kill_slot" first to remove that
10149 key.
10150 This function returns 0 on success or -1 on error.
10152 This function takes a key or passphrase parameter which could contain
10154 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10155 information.
10156 This function depends on the feature "luks". See also
10158 "guestfs_feature_available".
10159 (Added in 1.5.2)
10161 guestfs_luks_close
10163 int
10164 guestfs_luks_close (guestfs_h *g,
10165 const char *device);
10166 This function is deprecated. In new code, use the
10168 "guestfs_cryptsetup_close" call instead.
10169 Deprecated functions will not be removed from the API, but the fact
10171 that they are deprecated indicates that there are problems with correct
10172 use of these functions.
10173 This closes a LUKS device that was created earlier by
10175 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
10176 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10177 and not the name of the underlying block device.
10178 This function returns 0 on success or -1 on error.
10180 This function depends on the feature "luks". See also
10182 "guestfs_feature_available".
10183 (Added in 1.5.1)
10185 guestfs_luks_format
10187 int
10188 guestfs_luks_format (guestfs_h *g,
10189 const char *device,
10190 const char *key,
10191 int keyslot);
10192 This command erases existing data on "device" and formats the device as
10194 a LUKS encrypted device. "key" is the initial key, which is added to
10195 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
10196 This function returns 0 on success or -1 on error.
10198 This function takes a key or passphrase parameter which could contain
10200 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10201 information.
10202 This function depends on the feature "luks". See also
10204 "guestfs_feature_available".
10205 (Added in 1.5.2)
10207 guestfs_luks_format_cipher
10209 int
10210 guestfs_luks_format_cipher (guestfs_h *g,
10211 const char *device,
10212 const char *key,
10213 int keyslot,
10214 const char *cipher);
10215 This command is the same as "guestfs_luks_format" but it also allows
10217 you to set the "cipher" used.
10218 This function returns 0 on success or -1 on error.
10220 This function takes a key or passphrase parameter which could contain
10222 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10223 information.
10224 This function depends on the feature "luks". See also
10226 "guestfs_feature_available".
10227 (Added in 1.5.2)
10229 guestfs_luks_kill_slot
10231 int
10232 guestfs_luks_kill_slot (guestfs_h *g,
10233 const char *device,
10234 const char *key,
10235 int keyslot);
10236 This command deletes the key in key slot "keyslot" from the encrypted
10238 LUKS device "device". "key" must be one of the other keys.
10239 This function returns 0 on success or -1 on error.
10241 This function takes a key or passphrase parameter which could contain
10243 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10244 information.
10245 This function depends on the feature "luks". See also
10247 "guestfs_feature_available".
10248 (Added in 1.5.2)
10250 guestfs_luks_open
10252 int
10253 guestfs_luks_open (guestfs_h *g,
10254 const char *device,
10255 const char *key,
10256 const char *mapname);
10257 This function is deprecated. In new code, use the
10259 "guestfs_cryptsetup_open" call instead.
10260 Deprecated functions will not be removed from the API, but the fact
10262 that they are deprecated indicates that there are problems with correct
10263 use of these functions.
10264 This command opens a block device which has been encrypted according to
10266 the Linux Unified Key Setup (LUKS) standard.
10267 "device" is the encrypted block device or partition.
10269 The caller must supply one of the keys associated with the LUKS block
10271 device, in the "key" parameter.
10272 This creates a new block device called /dev/mapper/mapname. Reads and
10274 writes to this block device are decrypted from and encrypted to the
10275 underlying "device" respectively.
10276 If this block device contains LVM volume groups, then calling
10278 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10279 visible.
10280 Use "guestfs_list_dm_devices" to list all device mapper devices.
10282 This function returns 0 on success or -1 on error.
10284 This function takes a key or passphrase parameter which could contain
10286 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10287 information.
10288 This function depends on the feature "luks". See also
10290 "guestfs_feature_available".
10291 (Added in 1.5.1)
10293 guestfs_luks_open_ro
10295 int
10296 guestfs_luks_open_ro (guestfs_h *g,
10297 const char *device,
10298 const char *key,
10299 const char *mapname);
10300 This function is deprecated. In new code, use the
10302 "guestfs_cryptsetup_open" call instead.
10303 Deprecated functions will not be removed from the API, but the fact
10305 that they are deprecated indicates that there are problems with correct
10306 use of these functions.
10307 This is the same as "guestfs_luks_open" except that a read-only mapping
10309 is created.
10310 This function returns 0 on success or -1 on error.
10312 This function takes a key or passphrase parameter which could contain
10314 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10315 information.
10316 This function depends on the feature "luks". See also
10318 "guestfs_feature_available".
10319 (Added in 1.5.1)
10321 guestfs_luks_uuid
10323 char *
10324 guestfs_luks_uuid (guestfs_h *g,
10325 const char *device);
10326 This returns the UUID of the LUKS device "device".
10328 This function returns a string, or NULL on error. The caller must free
10330 the returned string after use.
10331 This function depends on the feature "luks". See also
10333 "guestfs_feature_available".
10334 (Added in 1.41.9)
10336 guestfs_lvcreate
10338 int
10339 guestfs_lvcreate (guestfs_h *g,
10340 const char *logvol,
10341 const char *volgroup,
10342 int mbytes);
10343 This creates an LVM logical volume called "logvol" on the volume group
10345 "volgroup", with "size" megabytes.
10346 This function returns 0 on success or -1 on error.
10348 This function depends on the feature "lvm2". See also
10350 "guestfs_feature_available".
10351 (Added in 0.8)
10353 guestfs_lvcreate_free
10355 int
10356 guestfs_lvcreate_free (guestfs_h *g,
10357 const char *logvol,
10358 const char *volgroup,
10359 int percent);
10360 Create an LVM logical volume called /dev/volgroup/logvol, using
10362 approximately "percent" % of the free space remaining in the volume
10363 group. Most usefully, when "percent" is 100 this will create the
10364 largest possible LV.
10365 This function returns 0 on success or -1 on error.
10367 This function depends on the feature "lvm2". See also
10369 "guestfs_feature_available".
10370 (Added in 1.17.18)
10372 guestfs_lvm_canonical_lv_name
10374 char *
10375 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10376 const char *lvname);
10377 This converts alternative naming schemes for LVs that you might find to
10379 the canonical name. For example, /dev/mapper/VG-LV is converted to
10380 /dev/VG/LV.
10381 This command returns an error if the "lvname" parameter does not refer
10383 to a logical volume. In this case errno will be set to "EINVAL".
10384 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10386 This function returns a string, or NULL on error. The caller must free
10388 the returned string after use.
10389 (Added in 1.5.24)
10391 guestfs_lvm_clear_filter
10393 int
10394 guestfs_lvm_clear_filter (guestfs_h *g);
10395 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10397 to see every block device.
10398 This command also clears the LVM cache and performs a volume group
10400 scan.
10401 This function returns 0 on success or -1 on error.
10403 (Added in 1.5.1)
10405 guestfs_lvm_remove_all
10407 int
10408 guestfs_lvm_remove_all (guestfs_h *g);
10409 This command removes all LVM logical volumes, volume groups and
10411 physical volumes.
10412 This function returns 0 on success or -1 on error.
10414 This function depends on the feature "lvm2". See also
10416 "guestfs_feature_available".
10417 (Added in 0.8)
10419 guestfs_lvm_scan
10421 int
10422 guestfs_lvm_scan (guestfs_h *g,
10423 int activate);
10424 This scans all block devices and rebuilds the list of LVM physical
10426 volumes, volume groups and logical volumes.
10427 If the "activate" parameter is "true" then newly found volume groups
10429 and logical volumes are activated, meaning the LV /dev/VG/LV devices
10430 become visible.
10431 When a libguestfs handle is launched it scans for existing devices, so
10433 you do not normally need to use this API. However it is useful when
10434 you have added a new device or deleted an existing device (such as when
10435 the "guestfs_luks_open" API is used).
10436 This function returns 0 on success or -1 on error.
10438 (Added in 1.39.8)
10440 guestfs_lvm_set_filter
10442 int
10443 guestfs_lvm_set_filter (guestfs_h *g,
10444 char *const *devices);
10445 This sets the LVM device filter so that LVM will only be able to "see"
10447 the block devices in the list "devices", and will ignore all other
10448 attached block devices.
10449 Where disk image(s) contain duplicate PVs or VGs, this command is
10451 useful to get LVM to ignore the duplicates, otherwise LVM can get
10452 confused. Note also there are two types of duplication possible:
10453 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10454 cloned but just happen to have the same name. In normal operation you
10455 cannot create this situation, but you can do it outside LVM, eg. by
10456 cloning disk images or by bit twiddling inside the LVM metadata.
10457 This command also clears the LVM cache and performs a volume group
10459 scan.
10460 You can filter whole block devices or individual partitions.
10462 You cannot use this if any VG is currently in use (eg. contains a
10464 mounted filesystem), even if you are not filtering out that VG.
10465 This function returns 0 on success or -1 on error.
10467 This function depends on the feature "lvm2". See also
10469 "guestfs_feature_available".
10470 (Added in 1.5.1)
10472 guestfs_lvremove
10474 int
10475 guestfs_lvremove (guestfs_h *g,
10476 const char *device);
10477 Remove an LVM logical volume "device", where "device" is the path to
10479 the LV, such as /dev/VG/LV.
10480 You can also remove all LVs in a volume group by specifying the VG
10482 name, /dev/VG.
10483 This function returns 0 on success or -1 on error.
10485 This function depends on the feature "lvm2". See also
10487 "guestfs_feature_available".
10488 (Added in 1.0.13)
10490 guestfs_lvrename
10492 int
10493 guestfs_lvrename (guestfs_h *g,
10494 const char *logvol,
10495 const char *newlogvol);
10496 Rename a logical volume "logvol" with the new name "newlogvol".
10498 This function returns 0 on success or -1 on error.
10500 (Added in 1.0.83)
10502 guestfs_lvresize
10504 int
10505 guestfs_lvresize (guestfs_h *g,
10506 const char *device,
10507 int mbytes);
10508 This resizes (expands or shrinks) an existing LVM logical volume to
10510 "mbytes". When reducing, data in the reduced part is lost.
10511 This function returns 0 on success or -1 on error.
10513 This function depends on the feature "lvm2". See also
10515 "guestfs_feature_available".
10516 (Added in 1.0.27)
10518 guestfs_lvresize_free
10520 int
10521 guestfs_lvresize_free (guestfs_h *g,
10522 const char *lv,
10523 int percent);
10524 This expands an existing logical volume "lv" so that it fills "pc" % of
10526 the remaining free space in the volume group. Commonly you would call
10527 this with pc = 100 which expands the logical volume as much as
10528 possible, using all remaining free space in the volume group.
10529 This function returns 0 on success or -1 on error.
10531 This function depends on the feature "lvm2". See also
10533 "guestfs_feature_available".
10534 (Added in 1.3.3)
10536 guestfs_lvs
10538 char **
10539 guestfs_lvs (guestfs_h *g);
10540 List all the logical volumes detected. This is the equivalent of the
10542 lvs(8) command.
10543 This returns a list of the logical volume device names (eg.
10545 /dev/VolGroup00/LogVol00).
10546 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10548 This function returns a NULL-terminated array of strings (like
10550 environ(3)), or NULL if there was an error. The caller must free the
10551 strings and the array after use.
10552 This function depends on the feature "lvm2". See also
10554 "guestfs_feature_available".
10555 (Added in 0.4)
10557 guestfs_lvs_full
10559 struct guestfs_lvm_lv_list *
10560 guestfs_lvs_full (guestfs_h *g);
10561 List all the logical volumes detected. This is the equivalent of the
10563 lvs(8) command. The "full" version includes all fields.
10564 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10566 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10567 after use.
10568 This function depends on the feature "lvm2". See also
10570 "guestfs_feature_available".
10571 (Added in 0.4)
10573 guestfs_lvuuid
10575 char *
10576 guestfs_lvuuid (guestfs_h *g,
10577 const char *device);
10578 This command returns the UUID of the LVM LV "device".
10580 This function returns a string, or NULL on error. The caller must free
10582 the returned string after use.
10583 (Added in 1.0.87)
10585 guestfs_lxattrlist
10587 struct guestfs_xattr_list *
10588 guestfs_lxattrlist (guestfs_h *g,
10589 const char *path,
10590 char *const *names);
10591 This call allows you to get the extended attributes of multiple files,
10593 where all files are in the directory "path". "names" is the list of
10594 files from this directory.
10595 On return you get a flat list of xattr structs which must be
10597 interpreted sequentially. The first xattr struct always has a zero-
10598 length "attrname". "attrval" in this struct is zero-length to indicate
10599 there was an error doing "guestfs_lgetxattr" for this file, or is a C
10600 string which is a decimal number (the number of following attributes
10601 for this file, which could be "0"). Then after the first xattr struct
10602 are the zero or more attributes for the first named file. This repeats
10603 for the second and subsequent files.
10604 This call is intended for programs that want to efficiently list a
10606 directory contents without making many round-trips. See also
10607 "guestfs_lstatlist" for a similarly efficient call for getting standard
10608 stats.
10609 This function returns a "struct guestfs_xattr_list *", or NULL if there
10611 was an error. The caller must call "guestfs_free_xattr_list" after
10612 use.
10613 This function depends on the feature "linuxxattrs". See also
10615 "guestfs_feature_available".
10616 (Added in 1.0.77)
10618 guestfs_max_disks
10620 int
10621 guestfs_max_disks (guestfs_h *g);
10622 Return the maximum number of disks that may be added to a handle (eg.
10624 by "guestfs_add_drive_opts" and similar calls).
10625 This function was added in libguestfs 1.19.7. In previous versions of
10627 libguestfs the limit was 25.
10628 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10630 On error this function returns -1.
10632 (Added in 1.19.7)
10634 guestfs_md_create
10636 int
10637 guestfs_md_create (guestfs_h *g,
10638 const char *name,
10639 char *const *devices,
10640 ...);
10641 You may supply a list of optional arguments to this call. Use zero or
10643 more of the following pairs of parameters, and terminate the list with
10644 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10645 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10647 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10648 GUESTFS_MD_CREATE_SPARE, int spare,
10649 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10650 GUESTFS_MD_CREATE_LEVEL, const char *level,
10651 Create a Linux md (RAID) device named "name" on the devices in the list
10653 "devices".
10654 The optional parameters are:
10656 "missingbitmap"
10658 A bitmap of missing devices. If a bit is set it means that a
10659 missing device is added to the array. The least significant bit
10660 corresponds to the first device in the array.
10661 As examples:
10663 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10665 resulting array would be "[<missing>, "/dev/sda"]".
10666 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10668 resulting array would be "["/dev/sda", <missing>]".
10669 This defaults to 0 (no missing devices).
10671 The length of "devices" + the number of bits set in "missingbitmap"
10673 must equal "nrdevices" + "spare".
10674 "nrdevices"
10676 The number of active RAID devices.
10677 If not set, this defaults to the length of "devices" plus the
10679 number of bits set in "missingbitmap".
10680 "spare"
10682 The number of spare devices.
10683 If not set, this defaults to 0.
10685 "chunk"
10687 The chunk size in bytes.
10688 "level"
10690 The RAID level, which can be one of: "linear", "raid0", 0,
10691 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
10692 "raid10", 10. Some of these are synonymous, and more levels may be
10693 added in future.
10694 If not set, this defaults to "raid1".
10696 This function returns 0 on success or -1 on error.
10698 This function depends on the feature "mdadm". See also
10700 "guestfs_feature_available".
10701 (Added in 1.15.6)
10703 guestfs_md_create_va
10705 int
10706 guestfs_md_create_va (guestfs_h *g,
10707 const char *name,
10708 char *const *devices,
10709 va_list args);
10710 This is the "va_list variant" of "guestfs_md_create".
10712 See "CALLS WITH OPTIONAL ARGUMENTS".
10714 guestfs_md_create_argv
10716 int
10717 guestfs_md_create_argv (guestfs_h *g,
10718 const char *name,
10719 char *const *devices,
10720 const struct guestfs_md_create_argv *optargs);
10721 This is the "argv variant" of "guestfs_md_create".
10723 See "CALLS WITH OPTIONAL ARGUMENTS".
10725 guestfs_md_detail
10727 char **
10728 guestfs_md_detail (guestfs_h *g,
10729 const char *md);
10730 This command exposes the output of "mdadm -DY <md>". The following
10732 fields are usually present in the returned hash. Other fields may also
10733 be present.
10734 "level"
10736 The raid level of the MD device.
10737 "devices"
10739 The number of underlying devices in the MD device.
10740 "metadata"
10742 The metadata version used.
10743 "uuid"
10745 The UUID of the MD device.
10746 "name"
10748 The name of the MD device.
10749 This function returns a NULL-terminated array of strings, or NULL if
10751 there was an error. The array of strings will always have length
10752 "2n+1", where "n" keys and values alternate, followed by the trailing
10753 NULL entry. The caller must free the strings and the array after use.
10754 This function depends on the feature "mdadm". See also
10756 "guestfs_feature_available".
10757 (Added in 1.15.6)
10759 guestfs_md_stat
10761 struct guestfs_mdstat_list *
10762 guestfs_md_stat (guestfs_h *g,
10763 const char *md);
10764 This call returns a list of the underlying devices which make up the
10766 single software RAID array device "md".
10767 To get a list of software RAID devices, call "guestfs_list_md_devices".
10769 Each structure returned corresponds to one device along with additional
10771 status information:
10772 "mdstat_device"
10774 The name of the underlying device.
10775 "mdstat_index"
10777 The index of this device within the array.
10778 "mdstat_flags"
10780 Flags associated with this device. This is a string containing (in
10781 no specific order) zero or more of the following flags:
10782 "W" write-mostly
10784 "F" device is faulty
10786 "S" device is a RAID spare
10788 "R" replacement
10790 This function returns a "struct guestfs_mdstat_list *", or NULL if
10792 there was an error. The caller must call "guestfs_free_mdstat_list"
10793 after use.
10794 This function depends on the feature "mdadm". See also
10796 "guestfs_feature_available".
10797 (Added in 1.17.21)
10799 guestfs_md_stop
10801 int
10802 guestfs_md_stop (guestfs_h *g,
10803 const char *md);
10804 This command deactivates the MD array named "md". The device is
10806 stopped, but it is not destroyed or zeroed.
10807 This function returns 0 on success or -1 on error.
10809 This function depends on the feature "mdadm". See also
10811 "guestfs_feature_available".
10812 (Added in 1.15.6)
10814 guestfs_mkdir
10816 int
10817 guestfs_mkdir (guestfs_h *g,
10818 const char *path);
10819 Create a directory named "path".
10821 This function returns 0 on success or -1 on error.
10823 (Added in 0.8)
10825 guestfs_mkdir_mode
10827 int
10828 guestfs_mkdir_mode (guestfs_h *g,
10829 const char *path,
10830 int mode);
10831 This command creates a directory, setting the initial permissions of
10833 the directory to "mode".
10834 For common Linux filesystems, the actual mode which is set will be
10836 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10837 the mode in other ways.
10838 See also "guestfs_mkdir", "guestfs_umask"
10840 This function returns 0 on success or -1 on error.
10842 (Added in 1.0.77)
10844 guestfs_mkdir_p
10846 int
10847 guestfs_mkdir_p (guestfs_h *g,
10848 const char *path);
10849 Create a directory named "path", creating any parent directories as
10851 necessary. This is like the "mkdir -p" shell command.
10852 This function returns 0 on success or -1 on error.
10854 (Added in 0.8)
10856 guestfs_mkdtemp
10858 char *
10859 guestfs_mkdtemp (guestfs_h *g,
10860 const char *tmpl);
10861 This command creates a temporary directory. The "tmpl" parameter
10863 should be a full pathname for the temporary directory name with the
10864 final six characters being "XXXXXX".
10865 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10867 one being suitable for Windows filesystems.
10868 The name of the temporary directory that was created is returned.
10870 The temporary directory is created with mode 0700 and is owned by root.
10872 The caller is responsible for deleting the temporary directory and its
10874 contents after use.
10875 See also: mkdtemp(3)
10877 This function returns a string, or NULL on error. The caller must free
10879 the returned string after use.
10880 (Added in 1.0.54)
10882 guestfs_mke2fs
10884 int
10885 guestfs_mke2fs (guestfs_h *g,
10886 const char *device,
10887 ...);
10888 You may supply a list of optional arguments to this call. Use zero or
10890 more of the following pairs of parameters, and terminate the list with
10891 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10892 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10894 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10895 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10896 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10897 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10898 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10899 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10900 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10901 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10902 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10903 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10904 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10905 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10906 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10907 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10908 GUESTFS_MKE2FS_LABEL, const char *label,
10909 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10910 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10911 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10912 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10913 GUESTFS_MKE2FS_UUID, const char *uuid,
10914 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10915 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10916 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10917 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10918 GUESTFS_MKE2FS_TESTFS, int testfs,
10919 GUESTFS_MKE2FS_DISCARD, int discard,
10920 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10921 GUESTFS_MKE2FS_EXTENT, int extent,
10922 GUESTFS_MKE2FS_FILETYPE, int filetype,
10923 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10924 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10925 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10926 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10927 GUESTFS_MKE2FS_QUOTA, int quota,
10928 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10929 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10930 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10931 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10933 "device".
10934 The optional "blockscount" is the size of the filesystem in blocks. If
10936 omitted it defaults to the size of "device". Note if the filesystem is
10937 too small to contain a journal, "mke2fs" will silently create an ext2
10938 filesystem instead.
10939 This function returns 0 on success or -1 on error.
10941 (Added in 1.19.44)
10943 guestfs_mke2fs_va
10945 int
10946 guestfs_mke2fs_va (guestfs_h *g,
10947 const char *device,
10948 va_list args);
10949 This is the "va_list variant" of "guestfs_mke2fs".
10951 See "CALLS WITH OPTIONAL ARGUMENTS".
10953 guestfs_mke2fs_argv
10955 int
10956 guestfs_mke2fs_argv (guestfs_h *g,
10957 const char *device,
10958 const struct guestfs_mke2fs_argv *optargs);
10959 This is the "argv variant" of "guestfs_mke2fs".
10961 See "CALLS WITH OPTIONAL ARGUMENTS".
10963 guestfs_mke2fs_J
10965 int
10966 guestfs_mke2fs_J (guestfs_h *g,
10967 const char *fstype,
10968 int blocksize,
10969 const char *device,
10970 const char *journal);
10971 This function is deprecated. In new code, use the "guestfs_mke2fs"
10973 call instead.
10974 Deprecated functions will not be removed from the API, but the fact
10976 that they are deprecated indicates that there are problems with correct
10977 use of these functions.
10978 This creates an ext2/3/4 filesystem on "device" with an external
10980 journal on "journal". It is equivalent to the command:
10981 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10983 See also "guestfs_mke2journal".
10985 This function returns 0 on success or -1 on error.
10987 (Added in 1.0.68)
10989 guestfs_mke2fs_JL
10991 int
10992 guestfs_mke2fs_JL (guestfs_h *g,
10993 const char *fstype,
10994 int blocksize,
10995 const char *device,
10996 const char *label);
10997 This function is deprecated. In new code, use the "guestfs_mke2fs"
10999 call instead.
11000 Deprecated functions will not be removed from the API, but the fact
11002 that they are deprecated indicates that there are problems with correct
11003 use of these functions.
11004 This creates an ext2/3/4 filesystem on "device" with an external
11006 journal on the journal labeled "label".
11007 See also "guestfs_mke2journal_L".
11009 This function returns 0 on success or -1 on error.
11011 (Added in 1.0.68)
11013 guestfs_mke2fs_JU
11015 int
11016 guestfs_mke2fs_JU (guestfs_h *g,
11017 const char *fstype,
11018 int blocksize,
11019 const char *device,
11020 const char *uuid);
11021 This function is deprecated. In new code, use the "guestfs_mke2fs"
11023 call instead.
11024 Deprecated functions will not be removed from the API, but the fact
11026 that they are deprecated indicates that there are problems with correct
11027 use of these functions.
11028 This creates an ext2/3/4 filesystem on "device" with an external
11030 journal on the journal with UUID "uuid".
11031 See also "guestfs_mke2journal_U".
11033 This function returns 0 on success or -1 on error.
11035 This function depends on the feature "linuxfsuuid". See also
11037 "guestfs_feature_available".
11038 (Added in 1.0.68)
11040 guestfs_mke2journal
11042 int
11043 guestfs_mke2journal (guestfs_h *g,
11044 int blocksize,
11045 const char *device);
11046 This function is deprecated. In new code, use the "guestfs_mke2fs"
11048 call instead.
11049 Deprecated functions will not be removed from the API, but the fact
11051 that they are deprecated indicates that there are problems with correct
11052 use of these functions.
11053 This creates an ext2 external journal on "device". It is equivalent to
11055 the command:
11056 mke2fs -O journal_dev -b blocksize device
11058 This function returns 0 on success or -1 on error.
11060 (Added in 1.0.68)
11062 guestfs_mke2journal_L
11064 int
11065 guestfs_mke2journal_L (guestfs_h *g,
11066 int blocksize,
11067 const char *label,
11068 const char *device);
11069 This function is deprecated. In new code, use the "guestfs_mke2fs"
11071 call instead.
11072 Deprecated functions will not be removed from the API, but the fact
11074 that they are deprecated indicates that there are problems with correct
11075 use of these functions.
11076 This creates an ext2 external journal on "device" with label "label".
11078 This function returns 0 on success or -1 on error.
11080 (Added in 1.0.68)
11082 guestfs_mke2journal_U
11084 int
11085 guestfs_mke2journal_U (guestfs_h *g,
11086 int blocksize,
11087 const char *uuid,
11088 const char *device);
11089 This function is deprecated. In new code, use the "guestfs_mke2fs"
11091 call instead.
11092 Deprecated functions will not be removed from the API, but the fact
11094 that they are deprecated indicates that there are problems with correct
11095 use of these functions.
11096 This creates an ext2 external journal on "device" with UUID "uuid".
11098 This function returns 0 on success or -1 on error.
11100 This function depends on the feature "linuxfsuuid". See also
11102 "guestfs_feature_available".
11103 (Added in 1.0.68)
11105 guestfs_mkfifo
11107 int
11108 guestfs_mkfifo (guestfs_h *g,
11109 int mode,
11110 const char *path);
11111 This call creates a FIFO (named pipe) called "path" with mode "mode".
11113 It is just a convenient wrapper around "guestfs_mknod".
11114 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11116 The mode actually set is affected by the umask.
11118 This function returns 0 on success or -1 on error.
11120 This function depends on the feature "mknod". See also
11122 "guestfs_feature_available".
11123 (Added in 1.0.55)
11125 guestfs_mkfs
11127 int
11128 guestfs_mkfs (guestfs_h *g,
11129 const char *fstype,
11130 const char *device);
11131 This function is provided for backwards compatibility with earlier
11133 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
11134 optional arguments.
11135 (Added in 0.8)
11137 guestfs_mkfs_opts
11139 int
11140 guestfs_mkfs_opts (guestfs_h *g,
11141 const char *fstype,
11142 const char *device,
11143 ...);
11144 You may supply a list of optional arguments to this call. Use zero or
11146 more of the following pairs of parameters, and terminate the list with
11147 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11148 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
11150 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
11151 GUESTFS_MKFS_OPTS_INODE, int inode,
11152 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
11153 GUESTFS_MKFS_OPTS_LABEL, const char *label,
11154 This function creates a filesystem on "device". The filesystem type is
11156 "fstype", for example "ext3".
11157 The optional arguments are:
11159 "blocksize"
11161 The filesystem block size. Supported block sizes depend on the
11162 filesystem type, but typically they are 1024, 2048 or 4096 for
11163 Linux ext2/3 filesystems.
11164 For VFAT and NTFS the "blocksize" parameter is treated as the
11166 requested cluster size.
11167 For UFS block sizes, please see mkfs.ufs(8).
11169 "features"
11171 This passes the -O parameter to the external mkfs program.
11172 For certain filesystem types, this allows extra filesystem features
11174 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
11175 You cannot use this optional parameter with the "gfs" or "gfs2"
11177 filesystem type.
11178 "inode"
11180 This passes the -I parameter to the external mke2fs(8) program
11181 which sets the inode size (only for ext2/3/4 filesystems at
11182 present).
11183 "sectorsize"
11185 This passes the -S parameter to external mkfs.ufs(8) program, which
11186 sets sector size for ufs filesystem.
11187 This function returns 0 on success or -1 on error.
11189 (Added in 0.8)
11191 guestfs_mkfs_opts_va
11193 int
11194 guestfs_mkfs_opts_va (guestfs_h *g,
11195 const char *fstype,
11196 const char *device,
11197 va_list args);
11198 This is the "va_list variant" of "guestfs_mkfs_opts".
11200 See "CALLS WITH OPTIONAL ARGUMENTS".
11202 guestfs_mkfs_opts_argv
11204 int
11205 guestfs_mkfs_opts_argv (guestfs_h *g,
11206 const char *fstype,
11207 const char *device,
11208 const struct guestfs_mkfs_opts_argv *optargs);
11209 This is the "argv variant" of "guestfs_mkfs_opts".
11211 See "CALLS WITH OPTIONAL ARGUMENTS".
11213 guestfs_mkfs_b
11215 int
11216 guestfs_mkfs_b (guestfs_h *g,
11217 const char *fstype,
11218 int blocksize,
11219 const char *device);
11220 This function is deprecated. In new code, use the "guestfs_mkfs" call
11222 instead.
11223 Deprecated functions will not be removed from the API, but the fact
11225 that they are deprecated indicates that there are problems with correct
11226 use of these functions.
11227 This call is similar to "guestfs_mkfs", but it allows you to control
11229 the block size of the resulting filesystem. Supported block sizes
11230 depend on the filesystem type, but typically they are 1024, 2048 or
11231 4096 only.
11232 For VFAT and NTFS the "blocksize" parameter is treated as the requested
11234 cluster size.
11235 This function returns 0 on success or -1 on error.
11237 (Added in 1.0.68)
11239 guestfs_mkfs_btrfs
11241 int
11242 guestfs_mkfs_btrfs (guestfs_h *g,
11243 char *const *devices,
11244 ...);
11245 You may supply a list of optional arguments to this call. Use zero or
11247 more of the following pairs of parameters, and terminate the list with
11248 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11249 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11251 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11252 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11253 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11254 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11255 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11256 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11257 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11258 Create a btrfs filesystem, allowing all configurables to be set. For
11260 more information on the optional arguments, see mkfs.btrfs(8).
11261 Since btrfs filesystems can span multiple devices, this takes a non-
11263 empty list of devices.
11264 To create general filesystems, use "guestfs_mkfs".
11266 This function returns 0 on success or -1 on error.
11268 This function depends on the feature "btrfs". See also
11270 "guestfs_feature_available".
11271 (Added in 1.17.25)
11273 guestfs_mkfs_btrfs_va
11275 int
11276 guestfs_mkfs_btrfs_va (guestfs_h *g,
11277 char *const *devices,
11278 va_list args);
11279 This is the "va_list variant" of "guestfs_mkfs_btrfs".
11281 See "CALLS WITH OPTIONAL ARGUMENTS".
11283 guestfs_mkfs_btrfs_argv
11285 int
11286 guestfs_mkfs_btrfs_argv (guestfs_h *g,
11287 char *const *devices,
11288 const struct guestfs_mkfs_btrfs_argv *optargs);
11289 This is the "argv variant" of "guestfs_mkfs_btrfs".
11291 See "CALLS WITH OPTIONAL ARGUMENTS".
11293 guestfs_mklost_and_found
11295 int
11296 guestfs_mklost_and_found (guestfs_h *g,
11297 const char *mountpoint);
11298 Make the "lost+found" directory, normally in the root directory of an
11300 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
11301 to create the "lost+found" directory.
11302 This function returns 0 on success or -1 on error.
11304 (Added in 1.19.56)
11306 guestfs_mkmountpoint
11308 int
11309 guestfs_mkmountpoint (guestfs_h *g,
11310 const char *exemptpath);
11311 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11313 that can be used to create extra mountpoints before mounting the first
11314 filesystem.
11315 These calls are only necessary in some very limited circumstances,
11317 mainly the case where you want to mount a mix of unrelated and/or read-
11318 only filesystems together.
11319 For example, live CDs often contain a "Russian doll" nest of
11321 filesystems, an ISO outer layer, with a squashfs image inside, with an
11322 ext2/3 image inside that. You can unpack this as follows in guestfish:
11323 add-ro Fedora-11-i686-Live.iso
11325 run
11326 mkmountpoint /cd
11327 mkmountpoint /sqsh
11328 mkmountpoint /ext3fs
11329 mount /dev/sda /cd
11330 mount-loop /cd/LiveOS/squashfs.img /sqsh
11331 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11332 The inner filesystem is now unpacked under the /ext3fs mountpoint.
11334 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11336 You may get unexpected errors if you try to mix these calls. It is
11337 safest to manually unmount filesystems and remove mountpoints after
11338 use.
11339 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11341 first, so for this to work for manual mountpoints, you must ensure that
11342 the innermost mountpoints have the longest pathnames, as in the example
11343 code above.
11344 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11346 Autosync [see "guestfs_set_autosync", this is set by default on
11348 handles] can cause "guestfs_umount_all" to be called when the handle is
11349 closed which can also trigger these issues.
11350 This function returns 0 on success or -1 on error.
11352 (Added in 1.0.62)
11354 guestfs_mknod
11356 int
11357 guestfs_mknod (guestfs_h *g,
11358 int mode,
11359 int devmajor,
11360 int devminor,
11361 const char *path);
11362 This call creates block or character special devices, or named pipes
11364 (FIFOs).
11365 The "mode" parameter should be the mode, using the standard constants.
11367 "devmajor" and "devminor" are the device major and minor numbers, only
11368 used when creating block and character special devices.
11369 Note that, just like mknod(2), the mode must be bitwise OR'd with
11371 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11372 a regular file). These constants are available in the standard Linux
11373 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11374 "guestfs_mkfifo" which are wrappers around this command which bitwise
11375 OR in the appropriate constant for you.
11376 The mode actually set is affected by the umask.
11378 This function returns 0 on success or -1 on error.
11380 This function depends on the feature "mknod". See also
11382 "guestfs_feature_available".
11383 (Added in 1.0.55)
11385 guestfs_mknod_b
11387 int
11388 guestfs_mknod_b (guestfs_h *g,
11389 int mode,
11390 int devmajor,
11391 int devminor,
11392 const char *path);
11393 This call creates a block device node called "path" with mode "mode"
11395 and device major/minor "devmajor" and "devminor". It is just a
11396 convenient wrapper around "guestfs_mknod".
11397 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11399 The mode actually set is affected by the umask.
11401 This function returns 0 on success or -1 on error.
11403 This function depends on the feature "mknod". See also
11405 "guestfs_feature_available".
11406 (Added in 1.0.55)
11408 guestfs_mknod_c
11410 int
11411 guestfs_mknod_c (guestfs_h *g,
11412 int mode,
11413 int devmajor,
11414 int devminor,
11415 const char *path);
11416 This call creates a char device node called "path" with mode "mode" and
11418 device major/minor "devmajor" and "devminor". It is just a convenient
11419 wrapper around "guestfs_mknod".
11420 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11422 The mode actually set is affected by the umask.
11424 This function returns 0 on success or -1 on error.
11426 This function depends on the feature "mknod". See also
11428 "guestfs_feature_available".
11429 (Added in 1.0.55)
11431 guestfs_mksquashfs
11433 int
11434 guestfs_mksquashfs (guestfs_h *g,
11435 const char *path,
11436 const char *filename,
11437 ...);
11438 You may supply a list of optional arguments to this call. Use zero or
11440 more of the following pairs of parameters, and terminate the list with
11441 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11442 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11444 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11445 Create a squashfs filesystem for the specified "path".
11447 The optional "compress" flag controls compression. If not given, then
11449 the output compressed using "gzip". Otherwise one of the following
11450 strings may be given to select the compression type of the squashfs:
11451 "gzip", "lzma", "lzo", "lz4", "xz".
11452 The other optional arguments are:
11454 "excludes"
11456 A list of wildcards. Files are excluded if they match any of the
11457 wildcards.
11458 Please note that this API may fail when used to compress directories
11460 with large files, such as the resulting squashfs will be over 3GB big.
11461 This function returns 0 on success or -1 on error.
11463 This function depends on the feature "squashfs". See also
11465 "guestfs_feature_available".
11466 (Added in 1.35.25)
11468 guestfs_mksquashfs_va
11470 int
11471 guestfs_mksquashfs_va (guestfs_h *g,
11472 const char *path,
11473 const char *filename,
11474 va_list args);
11475 This is the "va_list variant" of "guestfs_mksquashfs".
11477 See "CALLS WITH OPTIONAL ARGUMENTS".
11479 guestfs_mksquashfs_argv
11481 int
11482 guestfs_mksquashfs_argv (guestfs_h *g,
11483 const char *path,
11484 const char *filename,
11485 const struct guestfs_mksquashfs_argv *optargs);
11486 This is the "argv variant" of "guestfs_mksquashfs".
11488 See "CALLS WITH OPTIONAL ARGUMENTS".
11490 guestfs_mkswap
11492 int
11493 guestfs_mkswap (guestfs_h *g,
11494 const char *device);
11495 This function is provided for backwards compatibility with earlier
11497 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11498 optional arguments.
11499 (Added in 1.0.55)
11501 guestfs_mkswap_opts
11503 int
11504 guestfs_mkswap_opts (guestfs_h *g,
11505 const char *device,
11506 ...);
11507 You may supply a list of optional arguments to this call. Use zero or
11509 more of the following pairs of parameters, and terminate the list with
11510 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11511 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11513 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11514 Create a Linux swap partition on "device".
11516 The option arguments "label" and "uuid" allow you to set the label
11518 and/or UUID of the new swap partition.
11519 This function returns 0 on success or -1 on error.
11521 (Added in 1.0.55)
11523 guestfs_mkswap_opts_va
11525 int
11526 guestfs_mkswap_opts_va (guestfs_h *g,
11527 const char *device,
11528 va_list args);
11529 This is the "va_list variant" of "guestfs_mkswap_opts".
11531 See "CALLS WITH OPTIONAL ARGUMENTS".
11533 guestfs_mkswap_opts_argv
11535 int
11536 guestfs_mkswap_opts_argv (guestfs_h *g,
11537 const char *device,
11538 const struct guestfs_mkswap_opts_argv *optargs);
11539 This is the "argv variant" of "guestfs_mkswap_opts".
11541 See "CALLS WITH OPTIONAL ARGUMENTS".
11543 guestfs_mkswap_L
11545 int
11546 guestfs_mkswap_L (guestfs_h *g,
11547 const char *label,
11548 const char *device);
11549 This function is deprecated. In new code, use the "guestfs_mkswap"
11551 call instead.
11552 Deprecated functions will not be removed from the API, but the fact
11554 that they are deprecated indicates that there are problems with correct
11555 use of these functions.
11556 Create a swap partition on "device" with label "label".
11558 Note that you cannot attach a swap label to a block device (eg.
11560 /dev/sda), just to a partition. This appears to be a limitation of the
11561 kernel or swap tools.
11562 This function returns 0 on success or -1 on error.
11564 (Added in 1.0.55)
11566 guestfs_mkswap_U
11568 int
11569 guestfs_mkswap_U (guestfs_h *g,
11570 const char *uuid,
11571 const char *device);
11572 This function is deprecated. In new code, use the "guestfs_mkswap"
11574 call instead.
11575 Deprecated functions will not be removed from the API, but the fact
11577 that they are deprecated indicates that there are problems with correct
11578 use of these functions.
11579 Create a swap partition on "device" with UUID "uuid".
11581 This function returns 0 on success or -1 on error.
11583 This function depends on the feature "linuxfsuuid". See also
11585 "guestfs_feature_available".
11586 (Added in 1.0.55)
11588 guestfs_mkswap_file
11590 int
11591 guestfs_mkswap_file (guestfs_h *g,
11592 const char *path);
11593 Create a swap file.
11595 This command just writes a swap file signature to an existing file. To
11597 create the file itself, use something like "guestfs_fallocate".
11598 This function returns 0 on success or -1 on error.
11600 (Added in 1.0.66)
11602 guestfs_mktemp
11604 char *
11605 guestfs_mktemp (guestfs_h *g,
11606 const char *tmpl,
11607 ...);
11608 You may supply a list of optional arguments to this call. Use zero or
11610 more of the following pairs of parameters, and terminate the list with
11611 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11612 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11614 This command creates a temporary file. The "tmpl" parameter should be
11616 a full pathname for the temporary directory name with the final six
11617 characters being "XXXXXX".
11618 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11620 one being suitable for Windows filesystems.
11621 The name of the temporary file that was created is returned.
11623 The temporary file is created with mode 0600 and is owned by root.
11625 The caller is responsible for deleting the temporary file after use.
11627 If the optional "suffix" parameter is given, then the suffix (eg.
11629 ".txt") is appended to the temporary name.
11630 See also: "guestfs_mkdtemp".
11632 This function returns a string, or NULL on error. The caller must free
11634 the returned string after use.
11635 (Added in 1.19.53)
11637 guestfs_mktemp_va
11639 char *
11640 guestfs_mktemp_va (guestfs_h *g,
11641 const char *tmpl,
11642 va_list args);
11643 This is the "va_list variant" of "guestfs_mktemp".
11645 See "CALLS WITH OPTIONAL ARGUMENTS".
11647 guestfs_mktemp_argv
11649 char *
11650 guestfs_mktemp_argv (guestfs_h *g,
11651 const char *tmpl,
11652 const struct guestfs_mktemp_argv *optargs);
11653 This is the "argv variant" of "guestfs_mktemp".
11655 See "CALLS WITH OPTIONAL ARGUMENTS".
11657 guestfs_modprobe
11659 int
11660 guestfs_modprobe (guestfs_h *g,
11661 const char *modulename);
11662 This loads a kernel module in the appliance.
11664 This function returns 0 on success or -1 on error.
11666 This function depends on the feature "linuxmodules". See also
11668 "guestfs_feature_available".
11669 (Added in 1.0.68)
11671 guestfs_mount
11673 int
11674 guestfs_mount (guestfs_h *g,
11675 const char *mountable,
11676 const char *mountpoint);
11677 Mount a guest disk at a position in the filesystem. Block devices are
11679 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11680 If those block devices contain partitions, they will have the usual
11681 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11682 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11683 "guestfs_inspect_get_mountpoints".
11684 The rules are the same as for mount(2): A filesystem must first be
11686 mounted on / before others can be mounted. Other filesystems can only
11687 be mounted on directories which already exist.
11688 The mounted filesystem is writable, if we have sufficient permissions
11690 on the underlying device.
11691 Before libguestfs 1.13.16, this call implicitly added the options
11693 "sync" and "noatime". The "sync" option greatly slowed writes and
11694 caused many problems for users. If your program might need to work
11695 with older versions of libguestfs, use "guestfs_mount_options" instead
11696 (using an empty string for the first parameter if you don't want any
11697 options).
11698 This function returns 0 on success or -1 on error.
11700 (Added in 0.3)
11702 guestfs_mount_9p
11704 int
11705 guestfs_mount_9p (guestfs_h *g,
11706 const char *mounttag,
11707 const char *mountpoint,
11708 ...);
11709 You may supply a list of optional arguments to this call. Use zero or
11711 more of the following pairs of parameters, and terminate the list with
11712 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11713 GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11715 Mount the virtio-9p filesystem with the tag "mounttag" on the directory
11717 "mountpoint".
11718 If required, "trans=virtio" will be automatically added to the options.
11720 Any other options required can be passed in the optional "options"
11721 parameter.
11722 This function returns 0 on success or -1 on error.
11724 (Added in 1.11.12)
11726 guestfs_mount_9p_va
11728 int
11729 guestfs_mount_9p_va (guestfs_h *g,
11730 const char *mounttag,
11731 const char *mountpoint,
11732 va_list args);
11733 This is the "va_list variant" of "guestfs_mount_9p".
11735 See "CALLS WITH OPTIONAL ARGUMENTS".
11737 guestfs_mount_9p_argv
11739 int
11740 guestfs_mount_9p_argv (guestfs_h *g,
11741 const char *mounttag,
11742 const char *mountpoint,
11743 const struct guestfs_mount_9p_argv *optargs);
11744 This is the "argv variant" of "guestfs_mount_9p".
11746 See "CALLS WITH OPTIONAL ARGUMENTS".
11748 guestfs_mount_local
11750 int
11751 guestfs_mount_local (guestfs_h *g,
11752 const char *localmountpoint,
11753 ...);
11754 You may supply a list of optional arguments to this call. Use zero or
11756 more of the following pairs of parameters, and terminate the list with
11757 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11758 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11760 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11761 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11762 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11763 This call exports the libguestfs-accessible filesystem to a local
11765 mountpoint (directory) called "localmountpoint". Ordinary reads and
11766 writes to files and directories under "localmountpoint" are redirected
11767 through libguestfs.
11768 If the optional "readonly" flag is set to true, then writes to the
11770 filesystem return error "EROFS".
11771 "options" is a comma-separated list of mount options. See
11773 guestmount(1) for some useful options.
11774 "cachetimeout" sets the timeout (in seconds) for cached directory
11776 entries. The default is 60 seconds. See guestmount(1) for further
11777 information.
11778 If "debugcalls" is set to true, then additional debugging information
11780 is generated for every FUSE call.
11781 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11783 processing requests (access to it will block). You have to call
11784 "guestfs_mount_local_run" to run the main loop.
11785 See "MOUNT LOCAL" for full documentation.
11787 This function returns 0 on success or -1 on error.
11789 (Added in 1.17.22)
11791 guestfs_mount_local_va
11793 int
11794 guestfs_mount_local_va (guestfs_h *g,
11795 const char *localmountpoint,
11796 va_list args);
11797 This is the "va_list variant" of "guestfs_mount_local".
11799 See "CALLS WITH OPTIONAL ARGUMENTS".
11801 guestfs_mount_local_argv
11803 int
11804 guestfs_mount_local_argv (guestfs_h *g,
11805 const char *localmountpoint,
11806 const struct guestfs_mount_local_argv *optargs);
11807 This is the "argv variant" of "guestfs_mount_local".
11809 See "CALLS WITH OPTIONAL ARGUMENTS".
11811 guestfs_mount_local_run
11813 int
11814 guestfs_mount_local_run (guestfs_h *g);
11815 Run the main loop which translates kernel calls to libguestfs calls.
11817 This should only be called after "guestfs_mount_local" returns
11819 successfully. The call will not return until the filesystem is
11820 unmounted.
11821 Note you must not make concurrent libguestfs calls on the same handle
11823 from another thread.
11824 You may call this from a different thread than the one which called
11826 "guestfs_mount_local", subject to the usual rules for threads and
11827 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11828 See "MOUNT LOCAL" for full documentation.
11830 This function returns 0 on success or -1 on error.
11832 (Added in 1.17.22)
11834 guestfs_mount_loop
11836 int
11837 guestfs_mount_loop (guestfs_h *g,
11838 const char *file,
11839 const char *mountpoint);
11840 This command lets you mount file (a filesystem image in a file) on a
11842 mount point. It is entirely equivalent to the command "mount -o loop
11843 file mountpoint".
11844 This function returns 0 on success or -1 on error.
11846 (Added in 1.0.54)
11848 guestfs_mount_options
11850 int
11851 guestfs_mount_options (guestfs_h *g,
11852 const char *options,
11853 const char *mountable,
11854 const char *mountpoint);
11855 This is the same as the "guestfs_mount" command, but it allows you to
11857 set the mount options as for the mount(8) -o flag.
11858 If the "options" parameter is an empty string, then no options are
11860 passed (all options default to whatever the filesystem uses).
11861 This function returns 0 on success or -1 on error.
11863 (Added in 1.0.10)
11865 guestfs_mount_ro
11867 int
11868 guestfs_mount_ro (guestfs_h *g,
11869 const char *mountable,
11870 const char *mountpoint);
11871 This is the same as the "guestfs_mount" command, but it mounts the
11873 filesystem with the read-only (-o ro) flag.
11874 This function returns 0 on success or -1 on error.
11876 (Added in 1.0.10)
11878 guestfs_mount_vfs
11880 int
11881 guestfs_mount_vfs (guestfs_h *g,
11882 const char *options,
11883 const char *vfstype,
11884 const char *mountable,
11885 const char *mountpoint);
11886 This is the same as the "guestfs_mount" command, but it allows you to
11888 set both the mount options and the vfstype as for the mount(8) -o and
11889 -t flags.
11890 This function returns 0 on success or -1 on error.
11892 (Added in 1.0.10)
11894 guestfs_mountable_device
11896 char *
11897 guestfs_mountable_device (guestfs_h *g,
11898 const char *mountable);
11899 Returns the device name of a mountable. In quite a lot of cases, the
11901 mountable is the device name.
11902 However this doesn't apply for btrfs subvolumes, where the mountable is
11904 a combination of both the device name and the subvolume path (see also
11905 "guestfs_mountable_subvolume" to extract the subvolume path of the
11906 mountable if any).
11907 This function returns a string, or NULL on error. The caller must free
11909 the returned string after use.
11910 (Added in 1.33.15)
11912 guestfs_mountable_subvolume
11914 char *
11915 guestfs_mountable_subvolume (guestfs_h *g,
11916 const char *mountable);
11917 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11919 are a combination of both the device name and the subvolume path (see
11920 also "guestfs_mountable_device" to extract the device of the
11921 mountable).
11922 If the mountable does not represent a btrfs subvolume, then this
11924 function fails and the "errno" is set to "EINVAL".
11925 This function returns a string, or NULL on error. The caller must free
11927 the returned string after use.
11928 (Added in 1.33.15)
11930 guestfs_mountpoints
11932 char **
11933 guestfs_mountpoints (guestfs_h *g);
11934 This call is similar to "guestfs_mounts". That call returns a list of
11936 devices. This one returns a hash table (map) of device name to
11937 directory where the device is mounted.
11938 This function returns a NULL-terminated array of strings, or NULL if
11940 there was an error. The array of strings will always have length
11941 "2n+1", where "n" keys and values alternate, followed by the trailing
11942 NULL entry. The caller must free the strings and the array after use.
11943 (Added in 1.0.62)
11945 guestfs_mounts
11947 char **
11948 guestfs_mounts (guestfs_h *g);
11949 This returns the list of currently mounted filesystems. It returns the
11951 list of devices (eg. /dev/sda1, /dev/VG/LV).
11952 Some internal mounts are not shown.
11954 See also: "guestfs_mountpoints"
11956 This function returns a NULL-terminated array of strings (like
11958 environ(3)), or NULL if there was an error. The caller must free the
11959 strings and the array after use.
11960 (Added in 0.8)
11962 guestfs_mv
11964 int
11965 guestfs_mv (guestfs_h *g,
11966 const char *src,
11967 const char *dest);
11968 This moves a file from "src" to "dest" where "dest" is either a
11970 destination filename or destination directory.
11971 See also: "guestfs_rename".
11973 This function returns 0 on success or -1 on error.
11975 (Added in 1.0.18)
11977 guestfs_nr_devices
11979 int
11980 guestfs_nr_devices (guestfs_h *g);
11981 This returns the number of whole block devices that were added. This
11983 is the same as the number of devices that would be returned if you
11984 called "guestfs_list_devices".
11985 To find out the maximum number of devices that could be added, call
11987 "guestfs_max_disks".
11988 On error this function returns -1.
11990 (Added in 1.19.15)
11992 guestfs_ntfs_3g_probe
11994 int
11995 guestfs_ntfs_3g_probe (guestfs_h *g,
11996 int rw,
11997 const char *device);
11998 This command runs the ntfs-3g.probe(8) command which probes an NTFS
12000 "device" for mountability. (Not all NTFS volumes can be mounted read-
12001 write, and some cannot be mounted at all).
12002 "rw" is a boolean flag. Set it to true if you want to test if the
12004 volume can be mounted read-write. Set it to false if you want to test
12005 if the volume can be mounted read-only.
12006 The return value is an integer which 0 if the operation would succeed,
12008 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
12009 On error this function returns -1.
12011 This function depends on the feature "ntfs3g". See also
12013 "guestfs_feature_available".
12014 (Added in 1.0.43)
12016 guestfs_ntfscat_i
12018 int
12019 guestfs_ntfscat_i (guestfs_h *g,
12020 const char *device,
12021 int64_t inode,
12022 const char *filename);
12023 Download a file given its inode from a NTFS filesystem and save it as
12025 filename on the local machine.
12026 This allows to download some otherwise inaccessible files such as the
12028 ones within the $Extend folder.
12029 The filesystem from which to extract the file must be unmounted,
12031 otherwise the call will fail.
12032 This function returns 0 on success or -1 on error.
12034 This long-running command can generate progress notification messages
12036 so that the caller can display a progress bar or indicator. To receive
12037 these messages, the caller must register a progress event callback.
12038 See "GUESTFS_EVENT_PROGRESS".
12039 (Added in 1.33.14)
12041 guestfs_ntfsclone_in
12043 int
12044 guestfs_ntfsclone_in (guestfs_h *g,
12045 const char *backupfile,
12046 const char *device);
12047 Restore the "backupfile" (from a previous call to
12049 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
12050 of this device.
12051 This function returns 0 on success or -1 on error.
12053 This function depends on the feature "ntfs3g". See also
12055 "guestfs_feature_available".
12056 (Added in 1.17.9)
12058 guestfs_ntfsclone_out
12060 int
12061 guestfs_ntfsclone_out (guestfs_h *g,
12062 const char *device,
12063 const char *backupfile,
12064 ...);
12065 You may supply a list of optional arguments to this call. Use zero or
12067 more of the following pairs of parameters, and terminate the list with
12068 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12069 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
12071 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
12072 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
12073 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
12074 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
12075 Stream the NTFS filesystem "device" to the local file "backupfile".
12077 The format used for the backup file is a special format used by the
12078 ntfsclone(8) tool.
12079 If the optional "metadataonly" flag is true, then only the metadata is
12081 saved, losing all the user data (this is useful for diagnosing some
12082 filesystem problems).
12083 The optional "rescue", "ignorefscheck", "preservetimestamps" and
12085 "force" flags have precise meanings detailed in the ntfsclone(8) man
12086 page.
12087 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
12089 device.
12090 This function returns 0 on success or -1 on error.
12092 This function depends on the feature "ntfs3g". See also
12094 "guestfs_feature_available".
12095 (Added in 1.17.9)
12097 guestfs_ntfsclone_out_va
12099 int
12100 guestfs_ntfsclone_out_va (guestfs_h *g,
12101 const char *device,
12102 const char *backupfile,
12103 va_list args);
12104 This is the "va_list variant" of "guestfs_ntfsclone_out".
12106 See "CALLS WITH OPTIONAL ARGUMENTS".
12108 guestfs_ntfsclone_out_argv
12110 int
12111 guestfs_ntfsclone_out_argv (guestfs_h *g,
12112 const char *device,
12113 const char *backupfile,
12114 const struct guestfs_ntfsclone_out_argv *optargs);
12115 This is the "argv variant" of "guestfs_ntfsclone_out".
12117 See "CALLS WITH OPTIONAL ARGUMENTS".
12119 guestfs_ntfsfix
12121 int
12122 guestfs_ntfsfix (guestfs_h *g,
12123 const char *device,
12124 ...);
12125 You may supply a list of optional arguments to this call. Use zero or
12127 more of the following pairs of parameters, and terminate the list with
12128 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12129 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
12131 This command repairs some fundamental NTFS inconsistencies, resets the
12133 NTFS journal file, and schedules an NTFS consistency check for the
12134 first boot into Windows.
12135 This is not an equivalent of Windows "chkdsk". It does not scan the
12137 filesystem for inconsistencies.
12138 The optional "clearbadsectors" flag clears the list of bad sectors.
12140 This is useful after cloning a disk with bad sectors to a new disk.
12141 This function returns 0 on success or -1 on error.
12143 This function depends on the feature "ntfs3g". See also
12145 "guestfs_feature_available".
12146 (Added in 1.17.9)
12148 guestfs_ntfsfix_va
12150 int
12151 guestfs_ntfsfix_va (guestfs_h *g,
12152 const char *device,
12153 va_list args);
12154 This is the "va_list variant" of "guestfs_ntfsfix".
12156 See "CALLS WITH OPTIONAL ARGUMENTS".
12158 guestfs_ntfsfix_argv
12160 int
12161 guestfs_ntfsfix_argv (guestfs_h *g,
12162 const char *device,
12163 const struct guestfs_ntfsfix_argv *optargs);
12164 This is the "argv variant" of "guestfs_ntfsfix".
12166 See "CALLS WITH OPTIONAL ARGUMENTS".
12168 guestfs_ntfsresize
12170 int
12171 guestfs_ntfsresize (guestfs_h *g,
12172 const char *device);
12173 This function is provided for backwards compatibility with earlier
12175 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
12176 no optional arguments.
12177 (Added in 1.3.2)
12179 guestfs_ntfsresize_opts
12181 int
12182 guestfs_ntfsresize_opts (guestfs_h *g,
12183 const char *device,
12184 ...);
12185 You may supply a list of optional arguments to this call. Use zero or
12187 more of the following pairs of parameters, and terminate the list with
12188 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12189 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12191 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12192 This command resizes an NTFS filesystem, expanding or shrinking it to
12194 the size of the underlying device.
12195 The optional parameters are:
12197 "size"
12199 The new size (in bytes) of the filesystem. If omitted, the
12200 filesystem is resized to fit the container (eg. partition).
12201 "force"
12203 If this option is true, then force the resize of the filesystem
12204 even if the filesystem is marked as requiring a consistency check.
12205 After the resize operation, the filesystem is always marked as
12207 requiring a consistency check (for safety). You have to boot into
12208 Windows to perform this check and clear this condition. If you
12209 don't set the "force" option then it is not possible to call
12210 "guestfs_ntfsresize" multiple times on a single filesystem without
12211 booting into Windows between each resize.
12212 See also ntfsresize(8).
12214 This function returns 0 on success or -1 on error.
12216 This function depends on the feature "ntfsprogs". See also
12218 "guestfs_feature_available".
12219 (Added in 1.3.2)
12221 guestfs_ntfsresize_opts_va
12223 int
12224 guestfs_ntfsresize_opts_va (guestfs_h *g,
12225 const char *device,
12226 va_list args);
12227 This is the "va_list variant" of "guestfs_ntfsresize_opts".
12229 See "CALLS WITH OPTIONAL ARGUMENTS".
12231 guestfs_ntfsresize_opts_argv
12233 int
12234 guestfs_ntfsresize_opts_argv (guestfs_h *g,
12235 const char *device,
12236 const struct guestfs_ntfsresize_opts_argv *optargs);
12237 This is the "argv variant" of "guestfs_ntfsresize_opts".
12239 See "CALLS WITH OPTIONAL ARGUMENTS".
12241 guestfs_ntfsresize_size
12243 int
12244 guestfs_ntfsresize_size (guestfs_h *g,
12245 const char *device,
12246 int64_t size);
12247 This function is deprecated. In new code, use the "guestfs_ntfsresize"
12249 call instead.
12250 Deprecated functions will not be removed from the API, but the fact
12252 that they are deprecated indicates that there are problems with correct
12253 use of these functions.
12254 This command is the same as "guestfs_ntfsresize" except that it allows
12256 you to specify the new size (in bytes) explicitly.
12257 This function returns 0 on success or -1 on error.
12259 This function depends on the feature "ntfsprogs". See also
12261 "guestfs_feature_available".
12262 (Added in 1.3.14)
12264 guestfs_parse_environment
12266 int
12267 guestfs_parse_environment (guestfs_h *g);
12268 Parse the program’s environment and set flags in the handle
12270 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12271 flag is set in the handle.
12272 Most programs do not need to call this. It is done implicitly when you
12274 call "guestfs_create".
12275 See "ENVIRONMENT VARIABLES" for a list of environment variables that
12277 can affect libguestfs handles. See also "guestfs_create_flags", and
12278 "guestfs_parse_environment_list".
12279 This function returns 0 on success or -1 on error.
12281 (Added in 1.19.53)
12283 guestfs_parse_environment_list
12285 int
12286 guestfs_parse_environment_list (guestfs_h *g,
12287 char *const *environment);
12288 Parse the list of strings in the argument "environment" and set flags
12290 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
12291 string in the list, then the ‘verbose’ flag is set in the handle.
12292 This is the same as "guestfs_parse_environment" except that it parses
12294 an explicit list of strings instead of the program's environment.
12295 This function returns 0 on success or -1 on error.
12297 (Added in 1.19.53)
12299 guestfs_part_add
12301 int
12302 guestfs_part_add (guestfs_h *g,
12303 const char *device,
12304 const char *prlogex,
12305 int64_t startsect,
12306 int64_t endsect);
12307 This command adds a partition to "device". If there is no partition
12309 table on the device, call "guestfs_part_init" first.
12310 The "prlogex" parameter is the type of partition. Normally you should
12312 pass "p" or "primary" here, but MBR partition tables also support "l"
12313 (or "logical") and "e" (or "extended") partition types.
12314 "startsect" and "endsect" are the start and end of the partition in
12316 sectors. "endsect" may be negative, which means it counts backwards
12317 from the end of the disk ("-1" is the last sector).
12318 Creating a partition which covers the whole disk is not so easy. Use
12320 "guestfs_part_disk" to do that.
12321 This function returns 0 on success or -1 on error.
12323 (Added in 1.0.78)
12325 guestfs_part_del
12327 int
12328 guestfs_part_del (guestfs_h *g,
12329 const char *device,
12330 int partnum);
12331 This command deletes the partition numbered "partnum" on "device".
12333 Note that in the case of MBR partitioning, deleting an extended
12335 partition also deletes any logical partitions it contains.
12336 This function returns 0 on success or -1 on error.
12338 (Added in 1.3.2)
12340 guestfs_part_disk
12342 int
12343 guestfs_part_disk (guestfs_h *g,
12344 const char *device,
12345 const char *parttype);
12346 This command is simply a combination of "guestfs_part_init" followed by
12348 "guestfs_part_add" to create a single primary partition covering the
12349 whole disk.
12350 "parttype" is the partition table type, usually "mbr" or "gpt", but
12352 other possible values are described in "guestfs_part_init".
12353 This function returns 0 on success or -1 on error.
12355 (Added in 1.0.78)
12357 guestfs_part_expand_gpt
12359 int
12360 guestfs_part_expand_gpt (guestfs_h *g,
12361 const char *device);
12362 Move backup GPT data structures to the end of the disk. This is useful
12364 in case of in-place image expand since disk space after backup GPT
12365 header is not usable. This is equivalent to "sgdisk -e".
12366 See also sgdisk(8).
12368 This function returns 0 on success or -1 on error.
12370 This function depends on the feature "gdisk". See also
12372 "guestfs_feature_available".
12373 (Added in 1.33.2)
12375 guestfs_part_get_bootable
12377 int
12378 guestfs_part_get_bootable (guestfs_h *g,
12379 const char *device,
12380 int partnum);
12381 This command returns true if the partition "partnum" on "device" has
12383 the bootable flag set.
12384 See also "guestfs_part_set_bootable".
12386 This function returns a C truth value on success or -1 on error.
12388 (Added in 1.3.2)
12390 guestfs_part_get_disk_guid
12392 char *
12393 guestfs_part_get_disk_guid (guestfs_h *g,
12394 const char *device);
12395 Return the disk identifier (GUID) of a GPT-partitioned "device".
12397 Behaviour is undefined for other partition types.
12398 This function returns a string, or NULL on error. The caller must free
12400 the returned string after use.
12401 This function depends on the feature "gdisk". See also
12403 "guestfs_feature_available".
12404 (Added in 1.33.2)
12406 guestfs_part_get_gpt_attributes
12408 int64_t
12409 guestfs_part_get_gpt_attributes (guestfs_h *g,
12410 const char *device,
12411 int partnum);
12412 Return the attribute flags of numbered GPT partition "partnum". An
12414 error is returned for MBR partitions.
12415 On error this function returns -1.
12417 This function depends on the feature "gdisk". See also
12419 "guestfs_feature_available".
12420 (Added in 1.21.1)
12422 guestfs_part_get_gpt_guid
12424 char *
12425 guestfs_part_get_gpt_guid (guestfs_h *g,
12426 const char *device,
12427 int partnum);
12428 Return the GUID of numbered GPT partition "partnum".
12430 This function returns a string, or NULL on error. The caller must free
12432 the returned string after use.
12433 This function depends on the feature "gdisk". See also
12435 "guestfs_feature_available".
12436 (Added in 1.29.25)
12438 guestfs_part_get_gpt_type
12440 char *
12441 guestfs_part_get_gpt_type (guestfs_h *g,
12442 const char *device,
12443 int partnum);
12444 Return the type GUID of numbered GPT partition "partnum". For MBR
12446 partitions, return an appropriate GUID corresponding to the MBR type.
12447 Behaviour is undefined for other partition types.
12448 This function returns a string, or NULL on error. The caller must free
12450 the returned string after use.
12451 This function depends on the feature "gdisk". See also
12453 "guestfs_feature_available".
12454 (Added in 1.21.1)
12456 guestfs_part_get_mbr_id
12458 int
12459 guestfs_part_get_mbr_id (guestfs_h *g,
12460 const char *device,
12461 int partnum);
12462 Returns the MBR type byte (also known as the ID byte) from the numbered
12464 partition "partnum".
12465 Note that only MBR (old DOS-style) partitions have type bytes. You
12467 will get undefined results for other partition table types (see
12468 "guestfs_part_get_parttype").
12469 On error this function returns -1.
12471 (Added in 1.3.2)
12473 guestfs_part_get_mbr_part_type
12475 char *
12476 guestfs_part_get_mbr_part_type (guestfs_h *g,
12477 const char *device,
12478 int partnum);
12479 This returns the partition type of an MBR partition numbered "partnum"
12481 on device "device".
12482 It returns "primary", "logical", or "extended".
12484 This function returns a string, or NULL on error. The caller must free
12486 the returned string after use.
12487 (Added in 1.29.32)
12489 guestfs_part_get_name
12491 char *
12492 guestfs_part_get_name (guestfs_h *g,
12493 const char *device,
12494 int partnum);
12495 This gets the partition name on partition numbered "partnum" on device
12497 "device". Note that partitions are numbered from 1.
12498 The partition name can only be read on certain types of partition
12500 table. This works on "gpt" but not on "mbr" partitions.
12501 This function returns a string, or NULL on error. The caller must free
12503 the returned string after use.
12504 (Added in 1.25.33)
12506 guestfs_part_get_parttype
12508 char *
12509 guestfs_part_get_parttype (guestfs_h *g,
12510 const char *device);
12511 This command examines the partition table on "device" and returns the
12513 partition table type (format) being used.
12514 Common return values include: "msdos" (a DOS/Windows style MBR
12516 partition table), "gpt" (a GPT/EFI-style partition table). Other
12517 values are possible, although unusual. See "guestfs_part_init" for a
12518 full list.
12519 This function returns a string, or NULL on error. The caller must free
12521 the returned string after use.
12522 (Added in 1.0.78)
12524 guestfs_part_init
12526 int
12527 guestfs_part_init (guestfs_h *g,
12528 const char *device,
12529 const char *parttype);
12530 This creates an empty partition table on "device" of one of the
12532 partition types listed below. Usually "parttype" should be either
12533 "msdos" or "gpt" (for large disks).
12534 Initially there are no partitions. Following this, you should call
12536 "guestfs_part_add" for each partition required.
12537 Possible values for "parttype" are:
12539 "efi"
12541 "gpt"
12542 Intel EFI / GPT partition table.
12543 This is recommended for >= 2 TB partitions that will be accessed
12545 from Linux and Intel-based Mac OS X. It also has limited backwards
12546 compatibility with the "mbr" format.
12547 "mbr"
12549 "msdos"
12550 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12551 and Windows. This partition type will only work for device sizes
12552 up to 2 TB. For large disks we recommend using "gpt".
12553 Other partition table types that may work but are not supported
12555 include:
12556 "aix"
12558 AIX disk labels.
12559 "amiga"
12561 "rdb"
12562 Amiga "Rigid Disk Block" format.
12563 "bsd"
12565 BSD disk labels.
12566 "dasd"
12568 DASD, used on IBM mainframes.
12569 "dvh"
12571 MIPS/SGI volumes.
12572 "mac"
12574 Old Mac partition format. Modern Macs use "gpt".
12575 "pc98"
12577 NEC PC-98 format, common in Japan apparently.
12578 "sun"
12580 Sun disk labels.
12581 This function returns 0 on success or -1 on error.
12583 (Added in 1.0.78)
12585 guestfs_part_list
12587 struct guestfs_partition_list *
12588 guestfs_part_list (guestfs_h *g,
12589 const char *device);
12590 This command parses the partition table on "device" and returns the
12592 list of partitions found.
12593 The fields in the returned structure are:
12595 "part_num"
12597 Partition number, counting from 1.
12598 "part_start"
12600 Start of the partition in bytes. To get sectors you have to divide
12601 by the device’s sector size, see "guestfs_blockdev_getss".
12602 "part_end"
12604 End of the partition in bytes.
12605 "part_size"
12607 Size of the partition in bytes.
12608 This function returns a "struct guestfs_partition_list *", or NULL if
12610 there was an error. The caller must call "guestfs_free_partition_list"
12611 after use.
12612 (Added in 1.0.78)
12614 guestfs_part_resize
12616 int
12617 guestfs_part_resize (guestfs_h *g,
12618 const char *device,
12619 int partnum,
12620 int64_t endsect);
12621 This command resizes the partition numbered "partnum" on "device" by
12623 moving the end position.
12624 Note that this does not modify any filesystem present in the partition.
12626 If you wish to do this, you will need to use filesystem resizing
12627 commands like "guestfs_resize2fs".
12628 When growing a partition you will want to grow the filesystem
12630 afterwards, but when shrinking, you need to shrink the filesystem
12631 before the partition.
12632 This function returns 0 on success or -1 on error.
12634 (Added in 1.37.20)
12636 guestfs_part_set_bootable
12638 int
12639 guestfs_part_set_bootable (guestfs_h *g,
12640 const char *device,
12641 int partnum,
12642 int bootable);
12643 This sets the bootable flag on partition numbered "partnum" on device
12645 "device". Note that partitions are numbered from 1.
12646 The bootable flag is used by some operating systems (notably Windows)
12648 to determine which partition to boot from. It is by no means
12649 universally recognized.
12650 This function returns 0 on success or -1 on error.
12652 (Added in 1.0.78)
12654 guestfs_part_set_disk_guid
12656 int
12657 guestfs_part_set_disk_guid (guestfs_h *g,
12658 const char *device,
12659 const char *guid);
12660 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12662 Return an error if the partition table of "device" isn't GPT, or if
12663 "guid" is not a valid GUID.
12664 This function returns 0 on success or -1 on error.
12666 This function depends on the feature "gdisk". See also
12668 "guestfs_feature_available".
12669 (Added in 1.33.2)
12671 guestfs_part_set_disk_guid_random
12673 int
12674 guestfs_part_set_disk_guid_random (guestfs_h *g,
12675 const char *device);
12676 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12678 randomly generated value. Return an error if the partition table of
12679 "device" isn't GPT.
12680 This function returns 0 on success or -1 on error.
12682 This function depends on the feature "gdisk". See also
12684 "guestfs_feature_available".
12685 (Added in 1.33.2)
12687 guestfs_part_set_gpt_attributes
12689 int
12690 guestfs_part_set_gpt_attributes (guestfs_h *g,
12691 const char *device,
12692 int partnum,
12693 int64_t attributes);
12694 Set the attribute flags of numbered GPT partition "partnum" to
12696 "attributes". Return an error if the partition table of "device" isn't
12697 GPT.
12698 See
12700 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12701 for a useful list of partition attributes.
12702 This function returns 0 on success or -1 on error.
12704 This function depends on the feature "gdisk". See also
12706 "guestfs_feature_available".
12707 (Added in 1.21.1)
12709 guestfs_part_set_gpt_guid
12711 int
12712 guestfs_part_set_gpt_guid (guestfs_h *g,
12713 const char *device,
12714 int partnum,
12715 const char *guid);
12716 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12718 error if the partition table of "device" isn't GPT, or if "guid" is not
12719 a valid GUID.
12720 This function returns 0 on success or -1 on error.
12722 This function depends on the feature "gdisk". See also
12724 "guestfs_feature_available".
12725 (Added in 1.29.25)
12727 guestfs_part_set_gpt_type
12729 int
12730 guestfs_part_set_gpt_type (guestfs_h *g,
12731 const char *device,
12732 int partnum,
12733 const char *guid);
12734 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12736 an error if the partition table of "device" isn't GPT, or if "guid" is
12737 not a valid GUID.
12738 See
12740 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12741 for a useful list of type GUIDs.
12742 This function returns 0 on success or -1 on error.
12744 This function depends on the feature "gdisk". See also
12746 "guestfs_feature_available".
12747 (Added in 1.21.1)
12749 guestfs_part_set_mbr_id
12751 int
12752 guestfs_part_set_mbr_id (guestfs_h *g,
12753 const char *device,
12754 int partnum,
12755 int idbyte);
12756 Sets the MBR type byte (also known as the ID byte) of the numbered
12758 partition "partnum" to "idbyte". Note that the type bytes quoted in
12759 most documentation are in fact hexadecimal numbers, but usually
12760 documented without any leading "0x" which might be confusing.
12761 Note that only MBR (old DOS-style) partitions have type bytes. You
12763 will get undefined results for other partition table types (see
12764 "guestfs_part_get_parttype").
12765 This function returns 0 on success or -1 on error.
12767 (Added in 1.3.2)
12769 guestfs_part_set_name
12771 int
12772 guestfs_part_set_name (guestfs_h *g,
12773 const char *device,
12774 int partnum,
12775 const char *name);
12776 This sets the partition name on partition numbered "partnum" on device
12778 "device". Note that partitions are numbered from 1.
12779 The partition name can only be set on certain types of partition table.
12781 This works on "gpt" but not on "mbr" partitions.
12782 This function returns 0 on success or -1 on error.
12784 (Added in 1.0.78)
12786 guestfs_part_to_dev
12788 char *
12789 guestfs_part_to_dev (guestfs_h *g,
12790 const char *partition);
12791 This function takes a partition name (eg. "/dev/sdb1") and removes the
12793 partition number, returning the device name (eg. "/dev/sdb").
12794 The named partition must exist, for example as a string returned from
12796 "guestfs_list_partitions".
12797 See also "guestfs_part_to_partnum", "guestfs_device_index".
12799 This function returns a string, or NULL on error. The caller must free
12801 the returned string after use.
12802 (Added in 1.5.15)
12804 guestfs_part_to_partnum
12806 int
12807 guestfs_part_to_partnum (guestfs_h *g,
12808 const char *partition);
12809 This function takes a partition name (eg. "/dev/sdb1") and returns the
12811 partition number (eg. 1).
12812 The named partition must exist, for example as a string returned from
12814 "guestfs_list_partitions".
12815 See also "guestfs_part_to_dev".
12817 On error this function returns -1.
12819 (Added in 1.13.25)
12821 guestfs_ping_daemon
12823 int
12824 guestfs_ping_daemon (guestfs_h *g);
12825 This is a test probe into the guestfs daemon running inside the
12827 libguestfs appliance. Calling this function checks that the daemon
12828 responds to the ping message, without affecting the daemon or attached
12829 block device(s) in any other way.
12830 This function returns 0 on success or -1 on error.
12832 (Added in 1.0.18)
12834 guestfs_pread
12836 char *
12837 guestfs_pread (guestfs_h *g,
12838 const char *path,
12839 int count,
12840 int64_t offset,
12841 size_t *size_r);
12842 This command lets you read part of a file. It reads "count" bytes of
12844 the file, starting at "offset", from file "path".
12845 This may read fewer bytes than requested. For further details see the
12847 pread(2) system call.
12848 See also "guestfs_pwrite", "guestfs_pread_device".
12850 This function returns a buffer, or NULL on error. The size of the
12852 returned buffer is written to *size_r. The caller must free the
12853 returned buffer after use.
12854 Because of the message protocol, there is a transfer limit of somewhere
12856 between 2MB and 4MB. See "PROTOCOL LIMITS".
12857 (Added in 1.0.77)
12859 guestfs_pread_device
12861 char *
12862 guestfs_pread_device (guestfs_h *g,
12863 const char *device,
12864 int count,
12865 int64_t offset,
12866 size_t *size_r);
12867 This command lets you read part of a block device. It reads "count"
12869 bytes of "device", starting at "offset".
12870 This may read fewer bytes than requested. For further details see the
12872 pread(2) system call.
12873 See also "guestfs_pread".
12875 This function returns a buffer, or NULL on error. The size of the
12877 returned buffer is written to *size_r. The caller must free the
12878 returned buffer after use.
12879 Because of the message protocol, there is a transfer limit of somewhere
12881 between 2MB and 4MB. See "PROTOCOL LIMITS".
12882 (Added in 1.5.21)
12884 guestfs_pvchange_uuid
12886 int
12887 guestfs_pvchange_uuid (guestfs_h *g,
12888 const char *device);
12889 Generate a new random UUID for the physical volume "device".
12891 This function returns 0 on success or -1 on error.
12893 This function depends on the feature "lvm2". See also
12895 "guestfs_feature_available".
12896 (Added in 1.19.26)
12898 guestfs_pvchange_uuid_all
12900 int
12901 guestfs_pvchange_uuid_all (guestfs_h *g);
12902 Generate new random UUIDs for all physical volumes.
12904 This function returns 0 on success or -1 on error.
12906 This function depends on the feature "lvm2". See also
12908 "guestfs_feature_available".
12909 (Added in 1.19.26)
12911 guestfs_pvcreate
12913 int
12914 guestfs_pvcreate (guestfs_h *g,
12915 const char *device);
12916 This creates an LVM physical volume on the named "device", where
12918 "device" should usually be a partition name such as /dev/sda1.
12919 This function returns 0 on success or -1 on error.
12921 This function depends on the feature "lvm2". See also
12923 "guestfs_feature_available".
12924 (Added in 0.8)
12926 guestfs_pvremove
12928 int
12929 guestfs_pvremove (guestfs_h *g,
12930 const char *device);
12931 This wipes a physical volume "device" so that LVM will no longer
12933 recognise it.
12934 The implementation uses the pvremove(8) command which refuses to wipe
12936 physical volumes that contain any volume groups, so you have to remove
12937 those first.
12938 This function returns 0 on success or -1 on error.
12940 This function depends on the feature "lvm2". See also
12942 "guestfs_feature_available".
12943 (Added in 1.0.13)
12945 guestfs_pvresize
12947 int
12948 guestfs_pvresize (guestfs_h *g,
12949 const char *device);
12950 This resizes (expands or shrinks) an existing LVM physical volume to
12952 match the new size of the underlying device.
12953 This function returns 0 on success or -1 on error.
12955 This function depends on the feature "lvm2". See also
12957 "guestfs_feature_available".
12958 (Added in 1.0.26)
12960 guestfs_pvresize_size
12962 int
12963 guestfs_pvresize_size (guestfs_h *g,
12964 const char *device,
12965 int64_t size);
12966 This command is the same as "guestfs_pvresize" except that it allows
12968 you to specify the new size (in bytes) explicitly.
12969 This function returns 0 on success or -1 on error.
12971 This function depends on the feature "lvm2". See also
12973 "guestfs_feature_available".
12974 (Added in 1.3.14)
12976 guestfs_pvs
12978 char **
12979 guestfs_pvs (guestfs_h *g);
12980 List all the physical volumes detected. This is the equivalent of the
12982 pvs(8) command.
12983 This returns a list of just the device names that contain PVs (eg.
12985 /dev/sda2).
12986 See also "guestfs_pvs_full".
12988 This function returns a NULL-terminated array of strings (like
12990 environ(3)), or NULL if there was an error. The caller must free the
12991 strings and the array after use.
12992 This function depends on the feature "lvm2". See also
12994 "guestfs_feature_available".
12995 (Added in 0.4)
12997 guestfs_pvs_full
12999 struct guestfs_lvm_pv_list *
13000 guestfs_pvs_full (guestfs_h *g);
13001 List all the physical volumes detected. This is the equivalent of the
13003 pvs(8) command. The "full" version includes all fields.
13004 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
13006 there was an error. The caller must call "guestfs_free_lvm_pv_list"
13007 after use.
13008 This function depends on the feature "lvm2". See also
13010 "guestfs_feature_available".
13011 (Added in 0.4)
13013 guestfs_pvuuid
13015 char *
13016 guestfs_pvuuid (guestfs_h *g,
13017 const char *device);
13018 This command returns the UUID of the LVM PV "device".
13020 This function returns a string, or NULL on error. The caller must free
13022 the returned string after use.
13023 (Added in 1.0.87)
13025 guestfs_pwrite
13027 int
13028 guestfs_pwrite (guestfs_h *g,
13029 const char *path,
13030 const char *content,
13031 size_t content_size,
13032 int64_t offset);
13033 This command writes to part of a file. It writes the data buffer
13035 "content" to the file "path" starting at offset "offset".
13036 This command implements the pwrite(2) system call, and like that system
13038 call it may not write the full data requested. The return value is the
13039 number of bytes that were actually written to the file. This could
13040 even be 0, although short writes are unlikely for regular files in
13041 ordinary circumstances.
13042 See also "guestfs_pread", "guestfs_pwrite_device".
13044 On error this function returns -1.
13046 Because of the message protocol, there is a transfer limit of somewhere
13048 between 2MB and 4MB. See "PROTOCOL LIMITS".
13049 (Added in 1.3.14)
13051 guestfs_pwrite_device
13053 int
13054 guestfs_pwrite_device (guestfs_h *g,
13055 const char *device,
13056 const char *content,
13057 size_t content_size,
13058 int64_t offset);
13059 This command writes to part of a device. It writes the data buffer
13061 "content" to "device" starting at offset "offset".
13062 This command implements the pwrite(2) system call, and like that system
13064 call it may not write the full data requested (although short writes to
13065 disk devices and partitions are probably impossible with standard Linux
13066 kernels).
13067 See also "guestfs_pwrite".
13069 On error this function returns -1.
13071 Because of the message protocol, there is a transfer limit of somewhere
13073 between 2MB and 4MB. See "PROTOCOL LIMITS".
13074 (Added in 1.5.20)
13076 guestfs_read_file
13078 char *
13079 guestfs_read_file (guestfs_h *g,
13080 const char *path,
13081 size_t *size_r);
13082 This calls returns the contents of the file "path" as a buffer.
13084 Unlike "guestfs_cat", this function can correctly handle files that
13086 contain embedded ASCII NUL characters.
13087 This function returns a buffer, or NULL on error. The size of the
13089 returned buffer is written to *size_r. The caller must free the
13090 returned buffer after use.
13091 (Added in 1.0.63)
13093 guestfs_read_lines
13095 char **
13096 guestfs_read_lines (guestfs_h *g,
13097 const char *path);
13098 Return the contents of the file named "path".
13100 The file contents are returned as a list of lines. Trailing "LF" and
13102 "CRLF" character sequences are not returned.
13103 Note that this function cannot correctly handle binary files
13105 (specifically, files containing "\0" character which is treated as end
13106 of string). For those you need to use the "guestfs_read_file" function
13107 and split the buffer into lines yourself.
13108 This function returns a NULL-terminated array of strings (like
13110 environ(3)), or NULL if there was an error. The caller must free the
13111 strings and the array after use.
13112 (Added in 0.7)
13114 guestfs_readdir
13116 struct guestfs_dirent_list *
13117 guestfs_readdir (guestfs_h *g,
13118 const char *dir);
13119 This returns the list of directory entries in directory "dir".
13121 All entries in the directory are returned, including "." and "..". The
13123 entries are not sorted, but returned in the same order as the
13124 underlying filesystem.
13125 Also this call returns basic file type information about each file.
13127 The "ftyp" field will contain one of the following characters:
13128 'b' Block special
13130 'c' Char special
13132 'd' Directory
13134 'f' FIFO (named pipe)
13136 'l' Symbolic link
13138 'r' Regular file
13140 's' Socket
13142 'u' Unknown file type
13144 '?' The readdir(3) call returned a "d_type" field with an unexpected
13146 value
13147 This function is primarily intended for use by programs. To get a
13149 simple list of names, use "guestfs_ls". To get a printable directory
13150 for human consumption, use "guestfs_ll".
13151 This function returns a "struct guestfs_dirent_list *", or NULL if
13153 there was an error. The caller must call "guestfs_free_dirent_list"
13154 after use.
13155 Because of the message protocol, there is a transfer limit of somewhere
13157 between 2MB and 4MB. See "PROTOCOL LIMITS".
13158 (Added in 1.0.55)
13160 guestfs_readlink
13162 char *
13163 guestfs_readlink (guestfs_h *g,
13164 const char *path);
13165 This command reads the target of a symbolic link.
13167 This function returns a string, or NULL on error. The caller must free
13169 the returned string after use.
13170 (Added in 1.0.66)
13172 guestfs_readlinklist
13174 char **
13175 guestfs_readlinklist (guestfs_h *g,
13176 const char *path,
13177 char *const *names);
13178 This call allows you to do a "readlink" operation on multiple files,
13180 where all files are in the directory "path". "names" is the list of
13181 files from this directory.
13182 On return you get a list of strings, with a one-to-one correspondence
13184 to the "names" list. Each string is the value of the symbolic link.
13185 If the readlink(2) operation fails on any name, then the corresponding
13187 result string is the empty string "". However the whole operation is
13188 completed even if there were readlink(2) errors, and so you can call
13189 this function with names where you don't know if they are symbolic
13190 links already (albeit slightly less efficient).
13191 This call is intended for programs that want to efficiently list a
13193 directory contents without making many round-trips.
13194 This function returns a NULL-terminated array of strings (like
13196 environ(3)), or NULL if there was an error. The caller must free the
13197 strings and the array after use.
13198 (Added in 1.0.77)
13200 guestfs_realpath
13202 char *
13203 guestfs_realpath (guestfs_h *g,
13204 const char *path);
13205 Return the canonicalized absolute pathname of "path". The returned
13207 path has no ".", ".." or symbolic link path elements.
13208 This function returns a string, or NULL on error. The caller must free
13210 the returned string after use.
13211 (Added in 1.0.66)
13213 guestfs_remount
13215 int
13216 guestfs_remount (guestfs_h *g,
13217 const char *mountpoint,
13218 ...);
13219 You may supply a list of optional arguments to this call. Use zero or
13221 more of the following pairs of parameters, and terminate the list with
13222 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13223 GUESTFS_REMOUNT_RW, int rw,
13225 This call allows you to change the "rw" (readonly/read-write) flag on
13227 an already mounted filesystem at "mountpoint", converting a readonly
13228 filesystem to be read-write, or vice-versa.
13229 Note that at the moment you must supply the "optional" "rw" parameter.
13231 In future we may allow other flags to be adjusted.
13232 This function returns 0 on success or -1 on error.
13234 (Added in 1.23.2)
13236 guestfs_remount_va
13238 int
13239 guestfs_remount_va (guestfs_h *g,
13240 const char *mountpoint,
13241 va_list args);
13242 This is the "va_list variant" of "guestfs_remount".
13244 See "CALLS WITH OPTIONAL ARGUMENTS".
13246 guestfs_remount_argv
13248 int
13249 guestfs_remount_argv (guestfs_h *g,
13250 const char *mountpoint,
13251 const struct guestfs_remount_argv *optargs);
13252 This is the "argv variant" of "guestfs_remount".
13254 See "CALLS WITH OPTIONAL ARGUMENTS".
13256 guestfs_remove_drive
13258 int
13259 guestfs_remove_drive (guestfs_h *g,
13260 const char *label);
13261 This function is conceptually the opposite of "guestfs_add_drive_opts".
13263 It removes the drive that was previously added with label "label".
13264 Note that in order to remove drives, you have to add them with labels
13266 (see the optional "label" argument to "guestfs_add_drive_opts"). If
13267 you didn't use a label, then they cannot be removed.
13268 You can call this function before or after launching the handle. If
13270 called after launch, if the backend supports it, we try to hot unplug
13271 the drive: see "HOTPLUGGING". The disk must not be in use (eg.
13272 mounted) when you do this. We try to detect if the disk is in use and
13273 stop you from doing this.
13274 This function returns 0 on success or -1 on error.
13276 (Added in 1.19.49)
13278 guestfs_removexattr
13280 int
13281 guestfs_removexattr (guestfs_h *g,
13282 const char *xattr,
13283 const char *path);
13284 This call removes the extended attribute named "xattr" of the file
13286 "path".
13287 See also: "guestfs_lremovexattr", attr(5).
13289 This function returns 0 on success or -1 on error.
13291 This function depends on the feature "linuxxattrs". See also
13293 "guestfs_feature_available".
13294 (Added in 1.0.59)
13296 guestfs_rename
13298 int
13299 guestfs_rename (guestfs_h *g,
13300 const char *oldpath,
13301 const char *newpath);
13302 Rename a file to a new place on the same filesystem. This is the same
13304 as the Linux rename(2) system call. In most cases you are better to
13305 use "guestfs_mv" instead.
13306 This function returns 0 on success or -1 on error.
13308 (Added in 1.21.5)
13310 guestfs_resize2fs
13312 int
13313 guestfs_resize2fs (guestfs_h *g,
13314 const char *device);
13315 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13317 underlying device.
13318 See also "RESIZE2FS ERRORS".
13320 This function returns 0 on success or -1 on error.
13322 (Added in 1.0.27)
13324 guestfs_resize2fs_M
13326 int
13327 guestfs_resize2fs_M (guestfs_h *g,
13328 const char *device);
13329 This command is the same as "guestfs_resize2fs", but the filesystem is
13331 resized to its minimum size. This works like the -M option to the
13332 resize2fs(8) command.
13333 To get the resulting size of the filesystem you should call
13335 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13336 These two numbers, multiplied together, give the resulting size of the
13337 minimal filesystem in bytes.
13338 See also "RESIZE2FS ERRORS".
13340 This function returns 0 on success or -1 on error.
13342 (Added in 1.9.4)
13344 guestfs_resize2fs_size
13346 int
13347 guestfs_resize2fs_size (guestfs_h *g,
13348 const char *device,
13349 int64_t size);
13350 This command is the same as "guestfs_resize2fs" except that it allows
13352 you to specify the new size (in bytes) explicitly.
13353 See also "RESIZE2FS ERRORS".
13355 This function returns 0 on success or -1 on error.
13357 (Added in 1.3.14)
13359 guestfs_rm
13361 int
13362 guestfs_rm (guestfs_h *g,
13363 const char *path);
13364 Remove the single file "path".
13366 This function returns 0 on success or -1 on error.
13368 (Added in 0.8)
13370 guestfs_rm_f
13372 int
13373 guestfs_rm_f (guestfs_h *g,
13374 const char *path);
13375 Remove the file "path".
13377 If the file doesn't exist, that error is ignored. (Other errors, eg.
13379 I/O errors or bad paths, are not ignored)
13380 This call cannot remove directories. Use "guestfs_rmdir" to remove an
13382 empty directory, or "guestfs_rm_rf" to remove directories recursively.
13383 This function returns 0 on success or -1 on error.
13385 (Added in 1.19.42)
13387 guestfs_rm_rf
13389 int
13390 guestfs_rm_rf (guestfs_h *g,
13391 const char *path);
13392 Remove the file or directory "path", recursively removing the contents
13394 if its a directory. This is like the "rm -rf" shell command.
13395 This function returns 0 on success or -1 on error.
13397 (Added in 0.8)
13399 guestfs_rmdir
13401 int
13402 guestfs_rmdir (guestfs_h *g,
13403 const char *path);
13404 Remove the single directory "path".
13406 This function returns 0 on success or -1 on error.
13408 (Added in 0.8)
13410 guestfs_rmmountpoint
13412 int
13413 guestfs_rmmountpoint (guestfs_h *g,
13414 const char *exemptpath);
13415 This call removes a mountpoint that was previously created with
13417 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13418 This function returns 0 on success or -1 on error.
13420 (Added in 1.0.62)
13422 guestfs_rsync
13424 int
13425 guestfs_rsync (guestfs_h *g,
13426 const char *src,
13427 const char *dest,
13428 ...);
13429 You may supply a list of optional arguments to this call. Use zero or
13431 more of the following pairs of parameters, and terminate the list with
13432 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13433 GUESTFS_RSYNC_ARCHIVE, int archive,
13435 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13436 This call may be used to copy or synchronize two directories under the
13438 same libguestfs handle. This uses the rsync(1) program which uses a
13439 fast algorithm that avoids copying files unnecessarily.
13440 "src" and "dest" are the source and destination directories. Files are
13442 copied from "src" to "dest".
13443 The optional arguments are:
13445 "archive"
13447 Turns on archive mode. This is the same as passing the --archive
13448 flag to "rsync".
13449 "deletedest"
13451 Delete files at the destination that do not exist at the source.
13452 This function returns 0 on success or -1 on error.
13454 This function depends on the feature "rsync". See also
13456 "guestfs_feature_available".
13457 (Added in 1.19.29)
13459 guestfs_rsync_va
13461 int
13462 guestfs_rsync_va (guestfs_h *g,
13463 const char *src,
13464 const char *dest,
13465 va_list args);
13466 This is the "va_list variant" of "guestfs_rsync".
13468 See "CALLS WITH OPTIONAL ARGUMENTS".
13470 guestfs_rsync_argv
13472 int
13473 guestfs_rsync_argv (guestfs_h *g,
13474 const char *src,
13475 const char *dest,
13476 const struct guestfs_rsync_argv *optargs);
13477 This is the "argv variant" of "guestfs_rsync".
13479 See "CALLS WITH OPTIONAL ARGUMENTS".
13481 guestfs_rsync_in
13483 int
13484 guestfs_rsync_in (guestfs_h *g,
13485 const char *remote,
13486 const char *dest,
13487 ...);
13488 You may supply a list of optional arguments to this call. Use zero or
13490 more of the following pairs of parameters, and terminate the list with
13491 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13492 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13494 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13495 This call may be used to copy or synchronize the filesystem on the host
13497 or on a remote computer with the filesystem within libguestfs. This
13498 uses the rsync(1) program which uses a fast algorithm that avoids
13499 copying files unnecessarily.
13500 This call only works if the network is enabled. See
13502 "guestfs_set_network" or the --network option to various tools like
13503 guestfish(1).
13504 Files are copied from the remote server and directory specified by
13506 "remote" to the destination directory "dest".
13507 The format of the remote server string is defined by rsync(1). Note
13509 that there is no way to supply a password or passphrase so the target
13510 must be set up not to require one.
13511 The optional arguments are the same as those of "guestfs_rsync".
13513 This function returns 0 on success or -1 on error.
13515 This function depends on the feature "rsync". See also
13517 "guestfs_feature_available".
13518 (Added in 1.19.29)
13520 guestfs_rsync_in_va
13522 int
13523 guestfs_rsync_in_va (guestfs_h *g,
13524 const char *remote,
13525 const char *dest,
13526 va_list args);
13527 This is the "va_list variant" of "guestfs_rsync_in".
13529 See "CALLS WITH OPTIONAL ARGUMENTS".
13531 guestfs_rsync_in_argv
13533 int
13534 guestfs_rsync_in_argv (guestfs_h *g,
13535 const char *remote,
13536 const char *dest,
13537 const struct guestfs_rsync_in_argv *optargs);
13538 This is the "argv variant" of "guestfs_rsync_in".
13540 See "CALLS WITH OPTIONAL ARGUMENTS".
13542 guestfs_rsync_out
13544 int
13545 guestfs_rsync_out (guestfs_h *g,
13546 const char *src,
13547 const char *remote,
13548 ...);
13549 You may supply a list of optional arguments to this call. Use zero or
13551 more of the following pairs of parameters, and terminate the list with
13552 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13553 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13555 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13556 This call may be used to copy or synchronize the filesystem within
13558 libguestfs with a filesystem on the host or on a remote computer. This
13559 uses the rsync(1) program which uses a fast algorithm that avoids
13560 copying files unnecessarily.
13561 This call only works if the network is enabled. See
13563 "guestfs_set_network" or the --network option to various tools like
13564 guestfish(1).
13565 Files are copied from the source directory "src" to the remote server
13567 and directory specified by "remote".
13568 The format of the remote server string is defined by rsync(1). Note
13570 that there is no way to supply a password or passphrase so the target
13571 must be set up not to require one.
13572 The optional arguments are the same as those of "guestfs_rsync".
13574 Globbing does not happen on the "src" parameter. In programs which use
13576 the API directly you have to expand wildcards yourself (see
13577 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13578 (see "glob" in guestfish(1)), for example:
13579 ><fs> glob rsync-out /* rsync://remote/
13581 This function returns 0 on success or -1 on error.
13583 This function depends on the feature "rsync". See also
13585 "guestfs_feature_available".
13586 (Added in 1.19.29)
13588 guestfs_rsync_out_va
13590 int
13591 guestfs_rsync_out_va (guestfs_h *g,
13592 const char *src,
13593 const char *remote,
13594 va_list args);
13595 This is the "va_list variant" of "guestfs_rsync_out".
13597 See "CALLS WITH OPTIONAL ARGUMENTS".
13599 guestfs_rsync_out_argv
13601 int
13602 guestfs_rsync_out_argv (guestfs_h *g,
13603 const char *src,
13604 const char *remote,
13605 const struct guestfs_rsync_out_argv *optargs);
13606 This is the "argv variant" of "guestfs_rsync_out".
13608 See "CALLS WITH OPTIONAL ARGUMENTS".
13610 guestfs_scrub_device
13612 int
13613 guestfs_scrub_device (guestfs_h *g,
13614 const char *device);
13615 This command writes patterns over "device" to make data retrieval more
13617 difficult.
13618 It is an interface to the scrub(1) program. See that manual page for
13620 more details.
13621 This function returns 0 on success or -1 on error.
13623 This function depends on the feature "scrub". See also
13625 "guestfs_feature_available".
13626 (Added in 1.0.52)
13628 guestfs_scrub_file
13630 int
13631 guestfs_scrub_file (guestfs_h *g,
13632 const char *file);
13633 This command writes patterns over a file to make data retrieval more
13635 difficult.
13636 The file is removed after scrubbing.
13638 It is an interface to the scrub(1) program. See that manual page for
13640 more details.
13641 This function returns 0 on success or -1 on error.
13643 This function depends on the feature "scrub". See also
13645 "guestfs_feature_available".
13646 (Added in 1.0.52)
13648 guestfs_scrub_freespace
13650 int
13651 guestfs_scrub_freespace (guestfs_h *g,
13652 const char *dir);
13653 This command creates the directory "dir" and then fills it with files
13655 until the filesystem is full, and scrubs the files as for
13656 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13657 free space on the partition containing "dir".
13658 It is an interface to the scrub(1) program. See that manual page for
13660 more details.
13661 This function returns 0 on success or -1 on error.
13663 This function depends on the feature "scrub". See also
13665 "guestfs_feature_available".
13666 (Added in 1.0.52)
13668 guestfs_selinux_relabel
13670 int
13671 guestfs_selinux_relabel (guestfs_h *g,
13672 const char *specfile,
13673 const char *path,
13674 ...);
13675 You may supply a list of optional arguments to this call. Use zero or
13677 more of the following pairs of parameters, and terminate the list with
13678 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13679 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13681 SELinux relabel parts of the filesystem.
13683 The "specfile" parameter controls the policy spec file used. You have
13685 to parse "/etc/selinux/config" to find the correct SELinux policy and
13686 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13687 "/contexts/files/file_contexts".
13688 The required "path" parameter is the top level directory where
13690 relabelling starts. Normally you should pass "path" as "/" to relabel
13691 the whole guest filesystem.
13692 The optional "force" boolean controls whether the context is reset for
13694 customizable files, and also whether the user, role and range parts of
13695 the file context is changed.
13696 This function returns 0 on success or -1 on error.
13698 This function depends on the feature "selinuxrelabel". See also
13700 "guestfs_feature_available".
13701 (Added in 1.33.43)
13703 guestfs_selinux_relabel_va
13705 int
13706 guestfs_selinux_relabel_va (guestfs_h *g,
13707 const char *specfile,
13708 const char *path,
13709 va_list args);
13710 This is the "va_list variant" of "guestfs_selinux_relabel".
13712 See "CALLS WITH OPTIONAL ARGUMENTS".
13714 guestfs_selinux_relabel_argv
13716 int
13717 guestfs_selinux_relabel_argv (guestfs_h *g,
13718 const char *specfile,
13719 const char *path,
13720 const struct guestfs_selinux_relabel_argv *optargs);
13721 This is the "argv variant" of "guestfs_selinux_relabel".
13723 See "CALLS WITH OPTIONAL ARGUMENTS".
13725 guestfs_set_append
13727 int
13728 guestfs_set_append (guestfs_h *g,
13729 const char *append);
13730 This function is used to add additional options to the libguestfs
13732 appliance kernel command line.
13733 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13735 environment variable.
13736 Setting "append" to "NULL" means no additional options are passed
13738 (libguestfs always adds a few of its own).
13739 This function returns 0 on success or -1 on error.
13741 (Added in 1.0.26)
13743 guestfs_set_attach_method
13745 int
13746 guestfs_set_attach_method (guestfs_h *g,
13747 const char *backend);
13748 This function is deprecated. In new code, use the
13750 "guestfs_set_backend" call instead.
13751 Deprecated functions will not be removed from the API, but the fact
13753 that they are deprecated indicates that there are problems with correct
13754 use of these functions.
13755 Set the method that libguestfs uses to connect to the backend guestfsd
13757 daemon.
13758 See "BACKEND".
13760 This function returns 0 on success or -1 on error.
13762 (Added in 1.9.8)
13764 guestfs_set_autosync
13766 int
13767 guestfs_set_autosync (guestfs_h *g,
13768 int autosync);
13769 If "autosync" is true, this enables autosync. Libguestfs will make a
13771 best effort attempt to make filesystems consistent and synchronized
13772 when the handle is closed (also if the program exits without closing
13773 handles).
13774 This is enabled by default (since libguestfs 1.5.24, previously it was
13776 disabled by default).
13777 This function returns 0 on success or -1 on error.
13779 (Added in 0.3)
13781 guestfs_set_backend
13783 int
13784 guestfs_set_backend (guestfs_h *g,
13785 const char *backend);
13786 Set the method that libguestfs uses to connect to the backend guestfsd
13788 daemon.
13789 This handle property was previously called the "attach method".
13791 See "BACKEND".
13793 This function returns 0 on success or -1 on error.
13795 (Added in 1.21.26)
13797 guestfs_set_backend_setting
13799 int
13800 guestfs_set_backend_setting (guestfs_h *g,
13801 const char *name,
13802 const char *val);
13803 Append "name=value" to the backend settings string list. However if a
13805 string already exists matching "name" or beginning with "name=", then
13806 that setting is replaced.
13807 See "BACKEND", "BACKEND SETTINGS".
13809 This function returns 0 on success or -1 on error.
13811 (Added in 1.27.2)
13813 guestfs_set_backend_settings
13815 int
13816 guestfs_set_backend_settings (guestfs_h *g,
13817 char *const *settings);
13818 Set a list of zero or more settings which are passed through to the
13820 current backend. Each setting is a string which is interpreted in a
13821 backend-specific way, or ignored if not understood by the backend.
13822 The default value is an empty list, unless the environment variable
13824 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13825 This environment variable contains a colon-separated list of settings.
13826 This call replaces all backend settings. If you want to replace a
13828 single backend setting, see "guestfs_set_backend_setting". If you want
13829 to clear a single backend setting, see "guestfs_clear_backend_setting".
13830 See "BACKEND", "BACKEND SETTINGS".
13832 This function returns 0 on success or -1 on error.
13834 (Added in 1.25.24)
13836 guestfs_set_cachedir
13838 int
13839 guestfs_set_cachedir (guestfs_h *g,
13840 const char *cachedir);
13841 Set the directory used by the handle to store the appliance cache, when
13843 using a supermin appliance. The appliance is cached and shared between
13844 all handles which have the same effective user ID.
13845 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13847 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13848 default. Else if "TMPDIR" is set, then that is the default. Else
13849 /var/tmp is the default.
13850 This function returns 0 on success or -1 on error.
13852 (Added in 1.19.58)
13854 guestfs_set_direct
13856 int
13857 guestfs_set_direct (guestfs_h *g,
13858 int direct);
13859 This function is deprecated. In new code, use the
13861 "guestfs_internal_get_console_socket" call instead.
13862 Deprecated functions will not be removed from the API, but the fact
13864 that they are deprecated indicates that there are problems with correct
13865 use of these functions.
13866 If the direct appliance mode flag is enabled, then stdin and stdout are
13868 passed directly through to the appliance once it is launched.
13869 One consequence of this is that log messages aren't caught by the
13871 library and handled by "guestfs_set_log_message_callback", but go
13872 straight to stdout.
13873 You probably don't want to use this unless you know what you are doing.
13875 The default is disabled.
13877 This function returns 0 on success or -1 on error.
13879 (Added in 1.0.72)
13881 guestfs_set_e2attrs
13883 int
13884 guestfs_set_e2attrs (guestfs_h *g,
13885 const char *file,
13886 const char *attrs,
13887 ...);
13888 You may supply a list of optional arguments to this call. Use zero or
13890 more of the following pairs of parameters, and terminate the list with
13891 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13892 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13894 This sets or clears the file attributes "attrs" associated with the
13896 inode file.
13897 "attrs" is a string of characters representing file attributes. See
13899 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13900 attributes can be changed.
13901 If optional boolean "clear" is not present or false, then the "attrs"
13903 listed are set in the inode.
13904 If "clear" is true, then the "attrs" listed are cleared in the inode.
13906 In both cases, other attributes not present in the "attrs" string are
13908 left unchanged.
13909 These attributes are only present when the file is located on an
13911 ext2/3/4 filesystem. Using this call on other filesystem types will
13912 result in an error.
13913 This function returns 0 on success or -1 on error.
13915 (Added in 1.17.31)
13917 guestfs_set_e2attrs_va
13919 int
13920 guestfs_set_e2attrs_va (guestfs_h *g,
13921 const char *file,
13922 const char *attrs,
13923 va_list args);
13924 This is the "va_list variant" of "guestfs_set_e2attrs".
13926 See "CALLS WITH OPTIONAL ARGUMENTS".
13928 guestfs_set_e2attrs_argv
13930 int
13931 guestfs_set_e2attrs_argv (guestfs_h *g,
13932 const char *file,
13933 const char *attrs,
13934 const struct guestfs_set_e2attrs_argv *optargs);
13935 This is the "argv variant" of "guestfs_set_e2attrs".
13937 See "CALLS WITH OPTIONAL ARGUMENTS".
13939 guestfs_set_e2generation
13941 int
13942 guestfs_set_e2generation (guestfs_h *g,
13943 const char *file,
13944 int64_t generation);
13945 This sets the ext2 file generation of a file.
13947 See "guestfs_get_e2generation".
13949 This function returns 0 on success or -1 on error.
13951 (Added in 1.17.31)
13953 guestfs_set_e2label
13955 int
13956 guestfs_set_e2label (guestfs_h *g,
13957 const char *device,
13958 const char *label);
13959 This function is deprecated. In new code, use the "guestfs_set_label"
13961 call instead.
13962 Deprecated functions will not be removed from the API, but the fact
13964 that they are deprecated indicates that there are problems with correct
13965 use of these functions.
13966 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13968 to "label". Filesystem labels are limited to 16 characters.
13969 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13971 return the existing label on a filesystem.
13972 This function returns 0 on success or -1 on error.
13974 (Added in 1.0.15)
13976 guestfs_set_e2uuid
13978 int
13979 guestfs_set_e2uuid (guestfs_h *g,
13980 const char *device,
13981 const char *uuid);
13982 This function is deprecated. In new code, use the "guestfs_set_uuid"
13984 call instead.
13985 Deprecated functions will not be removed from the API, but the fact
13987 that they are deprecated indicates that there are problems with correct
13988 use of these functions.
13989 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
13991 "uuid". The format of the UUID and alternatives such as "clear",
13992 "random" and "time" are described in the tune2fs(8) manpage.
13993 You can use "guestfs_vfs_uuid" to return the existing UUID of a
13995 filesystem.
13996 This function returns 0 on success or -1 on error.
13998 (Added in 1.0.15)
14000 guestfs_set_hv
14002 int
14003 guestfs_set_hv (guestfs_h *g,
14004 const char *hv);
14005 Set the hypervisor binary that we will use. The hypervisor depends on
14007 the backend, but is usually the location of the qemu/KVM hypervisor.
14008 For the uml backend, it is the location of the "linux" or "vmlinux"
14009 binary.
14010 The default is chosen when the library was compiled by the configure
14012 script.
14013 You can also override this by setting the "LIBGUESTFS_HV" environment
14015 variable.
14016 Note that you should call this function as early as possible after
14018 creating the handle. This is because some pre-launch operations depend
14019 on testing qemu features (by running "qemu -help"). If the qemu binary
14020 changes, we don't retest features, and so you might see inconsistent
14021 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14022 all since that picks the qemu binary at the same time as the handle is
14023 created.
14024 This function returns 0 on success or -1 on error.
14026 (Added in 1.23.17)
14028 guestfs_set_identifier
14030 int
14031 guestfs_set_identifier (guestfs_h *g,
14032 const char *identifier);
14033 This is an informative string which the caller may optionally set in
14035 the handle. It is printed in various places, allowing the current
14036 handle to be identified in debugging output.
14037 One important place is when tracing is enabled. If the identifier
14039 string is not an empty string, then trace messages change from this:
14040 libguestfs: trace: get_tmpdir
14042 libguestfs: trace: get_tmpdir = "/tmp"
14043 to this:
14045 libguestfs: trace: ID: get_tmpdir
14047 libguestfs: trace: ID: get_tmpdir = "/tmp"
14048 where "ID" is the identifier string set by this call.
14050 The identifier must only contain alphanumeric ASCII characters,
14052 underscore and minus sign. The default is the empty string.
14053 See also "guestfs_set_program", "guestfs_set_trace",
14055 "guestfs_get_identifier".
14056 This function returns 0 on success or -1 on error.
14058 (Added in 1.31.14)
14060 guestfs_set_label
14062 int
14063 guestfs_set_label (guestfs_h *g,
14064 const char *mountable,
14065 const char *label);
14066 Set the filesystem label on "mountable" to "label".
14068 Only some filesystem types support labels, and libguestfs supports
14070 setting labels on only a subset of these.
14071 ext2, ext3, ext4
14073 Labels are limited to 16 bytes.
14074 NTFS
14076 Labels are limited to 128 unicode characters.
14077 XFS The label is limited to 12 bytes. The filesystem must not be
14079 mounted when trying to set the label.
14080 btrfs
14082 The label is limited to 255 bytes and some characters are not
14083 allowed. Setting the label on a btrfs subvolume will set the label
14084 on its parent filesystem. The filesystem must not be mounted when
14085 trying to set the label.
14086 fat The label is limited to 11 bytes.
14088 swap
14090 The label is limited to 16 bytes.
14091 If there is no support for changing the label for the type of the
14093 specified filesystem, set_label will fail and set errno as ENOTSUP.
14094 To read the label on a filesystem, call "guestfs_vfs_label".
14096 This function returns 0 on success or -1 on error.
14098 (Added in 1.17.9)
14100 guestfs_set_libvirt_requested_credential
14102 int
14103 guestfs_set_libvirt_requested_credential (guestfs_h *g,
14104 int index,
14105 const char *cred,
14106 size_t cred_size);
14107 After requesting the "index"'th credential from the user, call this
14109 function to pass the answer back to libvirt.
14110 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14112 This function returns 0 on success or -1 on error.
14114 (Added in 1.19.52)
14116 guestfs_set_libvirt_supported_credentials
14118 int
14119 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
14120 char *const *creds);
14121 Call this function before setting an event handler for
14123 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
14124 that the program knows how to process.
14125 The "creds" list must be a non-empty list of strings. Possible strings
14127 are:
14128 "username"
14130 "authname"
14131 "language"
14132 "cnonce"
14133 "passphrase"
14134 "echoprompt"
14135 "noechoprompt"
14136 "realm"
14137 "external"
14138 See libvirt documentation for the meaning of these credential types.
14140 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14142 This function returns 0 on success or -1 on error.
14144 (Added in 1.19.52)
14146 guestfs_set_memsize
14148 int
14149 guestfs_set_memsize (guestfs_h *g,
14150 int memsize);
14151 This sets the memory size in megabytes allocated to the hypervisor.
14153 This only has any effect if called before "guestfs_launch".
14154 You can also change this by setting the environment variable
14156 "LIBGUESTFS_MEMSIZE" before the handle is created.
14157 For more information on the architecture of libguestfs, see guestfs(3).
14159 This function returns 0 on success or -1 on error.
14161 (Added in 1.0.55)
14163 guestfs_set_network
14165 int
14166 guestfs_set_network (guestfs_h *g,
14167 int network);
14168 If "network" is true, then the network is enabled in the libguestfs
14170 appliance. The default is false.
14171 This affects whether commands are able to access the network (see
14173 "RUNNING COMMANDS").
14174 You must call this before calling "guestfs_launch", otherwise it has no
14176 effect.
14177 This function returns 0 on success or -1 on error.
14179 (Added in 1.5.4)
14181 guestfs_set_path
14183 int
14184 guestfs_set_path (guestfs_h *g,
14185 const char *searchpath);
14186 Set the path that libguestfs searches for kernel and initrd.img.
14188 The default is "$libdir/guestfs" unless overridden by setting
14190 "LIBGUESTFS_PATH" environment variable.
14191 Setting "path" to "NULL" restores the default path.
14193 This function returns 0 on success or -1 on error.
14195 (Added in 0.3)
14197 guestfs_set_pgroup
14199 int
14200 guestfs_set_pgroup (guestfs_h *g,
14201 int pgroup);
14202 If "pgroup" is true, child processes are placed into their own process
14204 group.
14205 The practical upshot of this is that signals like "SIGINT" (from users
14207 pressing "^C") won't be received by the child process.
14208 The default for this flag is false, because usually you want "^C" to
14210 kill the subprocess. Guestfish sets this flag to true when used
14211 interactively, so that "^C" can cancel long-running commands gracefully
14212 (see "guestfs_user_cancel").
14213 This function returns 0 on success or -1 on error.
14215 (Added in 1.11.18)
14217 guestfs_set_program
14219 int
14220 guestfs_set_program (guestfs_h *g,
14221 const char *program);
14222 Set the program name. This is an informative string which the main
14224 program may optionally set in the handle.
14225 When the handle is created, the program name in the handle is set to
14227 the basename from "argv[0]". The program name can never be "NULL".
14228 This function returns 0 on success or -1 on error.
14230 (Added in 1.21.29)
14232 guestfs_set_qemu
14234 int
14235 guestfs_set_qemu (guestfs_h *g,
14236 const char *hv);
14237 This function is deprecated. In new code, use the "guestfs_set_hv"
14239 call instead.
14240 Deprecated functions will not be removed from the API, but the fact
14242 that they are deprecated indicates that there are problems with correct
14243 use of these functions.
14244 Set the hypervisor binary (usually qemu) that we will use.
14246 The default is chosen when the library was compiled by the configure
14248 script.
14249 You can also override this by setting the "LIBGUESTFS_HV" environment
14251 variable.
14252 Setting "hv" to "NULL" restores the default qemu binary.
14254 Note that you should call this function as early as possible after
14256 creating the handle. This is because some pre-launch operations depend
14257 on testing qemu features (by running "qemu -help"). If the qemu binary
14258 changes, we don't retest features, and so you might see inconsistent
14259 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14260 all since that picks the qemu binary at the same time as the handle is
14261 created.
14262 This function returns 0 on success or -1 on error.
14264 (Added in 1.0.6)
14266 guestfs_set_recovery_proc
14268 int
14269 guestfs_set_recovery_proc (guestfs_h *g,
14270 int recoveryproc);
14271 If this is called with the parameter "false" then "guestfs_launch" does
14273 not create a recovery process. The purpose of the recovery process is
14274 to stop runaway hypervisor processes in the case where the main program
14275 aborts abruptly.
14276 This only has any effect if called before "guestfs_launch", and the
14278 default is true.
14279 About the only time when you would want to disable this is if the main
14281 process will fork itself into the background ("daemonize" itself). In
14282 this case the recovery process thinks that the main program has
14283 disappeared and so kills the hypervisor, which is not very helpful.
14284 This function returns 0 on success or -1 on error.
14286 (Added in 1.0.77)
14288 guestfs_set_selinux
14290 int
14291 guestfs_set_selinux (guestfs_h *g,
14292 int selinux);
14293 This function is deprecated. In new code, use the
14295 "guestfs_selinux_relabel" call instead.
14296 Deprecated functions will not be removed from the API, but the fact
14298 that they are deprecated indicates that there are problems with correct
14299 use of these functions.
14300 This sets the selinux flag that is passed to the appliance at boot
14302 time. The default is "selinux=0" (disabled).
14303 Note that if SELinux is enabled, it is always in Permissive mode
14305 ("enforcing=0").
14306 For more information on the architecture of libguestfs, see guestfs(3).
14308 This function returns 0 on success or -1 on error.
14310 (Added in 1.0.67)
14312 guestfs_set_smp
14314 int
14315 guestfs_set_smp (guestfs_h *g,
14316 int smp);
14317 Change the number of virtual CPUs assigned to the appliance. The
14319 default is 1. Increasing this may improve performance, though often it
14320 has no effect.
14321 This function must be called before "guestfs_launch".
14323 This function returns 0 on success or -1 on error.
14325 (Added in 1.13.15)
14327 guestfs_set_tmpdir
14329 int
14330 guestfs_set_tmpdir (guestfs_h *g,
14331 const char *tmpdir);
14332 Set the directory used by the handle to store temporary files.
14334 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14336 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14337 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
14338 default.
14339 This function returns 0 on success or -1 on error.
14341 (Added in 1.19.58)
14343 guestfs_set_trace
14345 int
14346 guestfs_set_trace (guestfs_h *g,
14347 int trace);
14348 If the command trace flag is set to 1, then libguestfs calls,
14350 parameters and return values are traced.
14351 If you want to trace C API calls into libguestfs (and other libraries)
14353 then possibly a better way is to use the external ltrace(1) command.
14354 Command traces are disabled unless the environment variable
14356 "LIBGUESTFS_TRACE" is defined and set to 1.
14357 Trace messages are normally sent to "stderr", unless you register a
14359 callback to send them somewhere else (see
14360 "guestfs_set_event_callback").
14361 This function returns 0 on success or -1 on error.
14363 (Added in 1.0.69)
14365 guestfs_set_uuid
14367 int
14368 guestfs_set_uuid (guestfs_h *g,
14369 const char *device,
14370 const char *uuid);
14371 Set the filesystem UUID on "device" to "uuid". If this fails and the
14373 errno is ENOTSUP, means that there is no support for changing the UUID
14374 for the type of the specified filesystem.
14375 Only some filesystem types support setting UUIDs.
14377 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14379 This function returns 0 on success or -1 on error.
14381 (Added in 1.23.10)
14383 guestfs_set_uuid_random
14385 int
14386 guestfs_set_uuid_random (guestfs_h *g,
14387 const char *device);
14388 Set the filesystem UUID on "device" to a random UUID. If this fails
14390 and the errno is ENOTSUP, means that there is no support for changing
14391 the UUID for the type of the specified filesystem.
14392 Only some filesystem types support setting UUIDs.
14394 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14396 This function returns 0 on success or -1 on error.
14398 (Added in 1.29.50)
14400 guestfs_set_verbose
14402 int
14403 guestfs_set_verbose (guestfs_h *g,
14404 int verbose);
14405 If "verbose" is true, this turns on verbose messages.
14407 Verbose messages are disabled unless the environment variable
14409 "LIBGUESTFS_DEBUG" is defined and set to 1.
14410 Verbose messages are normally sent to "stderr", unless you register a
14412 callback to send them somewhere else (see
14413 "guestfs_set_event_callback").
14414 This function returns 0 on success or -1 on error.
14416 (Added in 0.3)
14418 guestfs_setcon
14420 int
14421 guestfs_setcon (guestfs_h *g,
14422 const char *context);
14423 This function is deprecated. In new code, use the
14425 "guestfs_selinux_relabel" call instead.
14426 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 This sets the SELinux security context of the daemon to the string
14432 "context".
14433 See the documentation about SELINUX in guestfs(3).
14435 This function returns 0 on success or -1 on error.
14437 This function depends on the feature "selinux". See also
14439 "guestfs_feature_available".
14440 (Added in 1.0.67)
14442 guestfs_setxattr
14444 int
14445 guestfs_setxattr (guestfs_h *g,
14446 const char *xattr,
14447 const char *val,
14448 int vallen,
14449 const char *path);
14450 This call sets the extended attribute named "xattr" of the file "path"
14452 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14453 data.
14454 See also: "guestfs_lsetxattr", attr(5).
14456 This function returns 0 on success or -1 on error.
14458 This function depends on the feature "linuxxattrs". See also
14460 "guestfs_feature_available".
14461 (Added in 1.0.59)
14463 guestfs_sfdisk
14465 int
14466 guestfs_sfdisk (guestfs_h *g,
14467 const char *device,
14468 int cyls,
14469 int heads,
14470 int sectors,
14471 char *const *lines);
14472 This function is deprecated. In new code, use the "guestfs_part_add"
14474 call instead.
14475 Deprecated functions will not be removed from the API, but the fact
14477 that they are deprecated indicates that there are problems with correct
14478 use of these functions.
14479 This is a direct interface to the sfdisk(8) program for creating
14481 partitions on block devices.
14482 "device" should be a block device, for example /dev/sda.
14484 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14486 sectors on the device, which are passed directly to sfdisk(8) as the
14487 -C, -H and -S parameters. If you pass 0 for any of these, then the
14488 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14489 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
14490 (or rather, the kernel) cannot work out the right geometry and you will
14491 need to tell it.
14492 "lines" is a list of lines that we feed to sfdisk(8). For more
14494 information refer to the sfdisk(8) manpage.
14495 To create a single partition occupying the whole disk, you would pass
14497 "lines" as a single element list, when the single element being the
14498 string "," (comma).
14499 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14501 This function returns 0 on success or -1 on error.
14503 (Added in 0.8)
14505 guestfs_sfdiskM
14507 int
14508 guestfs_sfdiskM (guestfs_h *g,
14509 const char *device,
14510 char *const *lines);
14511 This function is deprecated. In new code, use the "guestfs_part_add"
14513 call instead.
14514 Deprecated functions will not be removed from the API, but the fact
14516 that they are deprecated indicates that there are problems with correct
14517 use of these functions.
14518 This is a simplified interface to the "guestfs_sfdisk" command, where
14520 partition sizes are specified in megabytes only (rounded to the nearest
14521 cylinder) and you don't need to specify the cyls, heads and sectors
14522 parameters which were rarely if ever used anyway.
14523 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14525 "guestfs_part_disk"
14526 This function returns 0 on success or -1 on error.
14528 (Added in 1.0.55)
14530 guestfs_sfdisk_N
14532 int
14533 guestfs_sfdisk_N (guestfs_h *g,
14534 const char *device,
14535 int partnum,
14536 int cyls,
14537 int heads,
14538 int sectors,
14539 const char *line);
14540 This function is deprecated. In new code, use the "guestfs_part_add"
14542 call instead.
14543 Deprecated functions will not be removed from the API, but the fact
14545 that they are deprecated indicates that there are problems with correct
14546 use of these functions.
14547 This runs sfdisk(8) option to modify just the single partition "n"
14549 (note: "n" counts from 1).
14550 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14552 for the cyls/heads/sectors parameters.
14553 See also: "guestfs_part_add"
14555 This function returns 0 on success or -1 on error.
14557 (Added in 1.0.26)
14559 guestfs_sfdisk_disk_geometry
14561 char *
14562 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14563 const char *device);
14564 This displays the disk geometry of "device" read from the partition
14566 table. Especially in the case where the underlying block device has
14567 been resized, this can be different from the kernel’s idea of the
14568 geometry (see "guestfs_sfdisk_kernel_geometry").
14569 The result is in human-readable format, and not designed to be parsed.
14571 This function returns a string, or NULL on error. The caller must free
14573 the returned string after use.
14574 (Added in 1.0.26)
14576 guestfs_sfdisk_kernel_geometry
14578 char *
14579 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14580 const char *device);
14581 This displays the kernel’s idea of the geometry of "device".
14583 The result is in human-readable format, and not designed to be parsed.
14585 This function returns a string, or NULL on error. The caller must free
14587 the returned string after use.
14588 (Added in 1.0.26)
14590 guestfs_sfdisk_l
14592 char *
14593 guestfs_sfdisk_l (guestfs_h *g,
14594 const char *device);
14595 This function is deprecated. In new code, use the "guestfs_part_list"
14597 call instead.
14598 Deprecated functions will not be removed from the API, but the fact
14600 that they are deprecated indicates that there are problems with correct
14601 use of these functions.
14602 This displays the partition table on "device", in the human-readable
14604 output of the sfdisk(8) command. It is not intended to be parsed.
14605 See also: "guestfs_part_list"
14607 This function returns a string, or NULL on error. The caller must free
14609 the returned string after use.
14610 (Added in 1.0.26)
14612 guestfs_sh
14614 char *
14615 guestfs_sh (guestfs_h *g,
14616 const char *command);
14617 This call runs a command from the guest filesystem via the guest’s
14619 /bin/sh.
14620 This is like "guestfs_command", but passes the command to:
14622 /bin/sh -c "command"
14624 Depending on the guest’s shell, this usually results in wildcards being
14626 expanded, shell expressions being interpolated and so on.
14627 All the provisos about "guestfs_command" apply to this call.
14629 This function returns a string, or NULL on error. The caller must free
14631 the returned string after use.
14632 (Added in 1.0.50)
14634 guestfs_sh_lines
14636 char **
14637 guestfs_sh_lines (guestfs_h *g,
14638 const char *command);
14639 This is the same as "guestfs_sh", but splits the result into a list of
14641 lines.
14642 See also: "guestfs_command_lines"
14644 This function returns a NULL-terminated array of strings (like
14646 environ(3)), or NULL if there was an error. The caller must free the
14647 strings and the array after use.
14648 (Added in 1.0.50)
14650 guestfs_shutdown
14652 int
14653 guestfs_shutdown (guestfs_h *g);
14654 This is the opposite of "guestfs_launch". It performs an orderly
14656 shutdown of the backend process(es). If the autosync flag is set
14657 (which is the default) then the disk image is synchronized.
14658 If the subprocess exits with an error then this function will return an
14660 error, which should not be ignored (it may indicate that the disk image
14661 could not be written out properly).
14662 It is safe to call this multiple times. Extra calls are ignored.
14664 This call does not close or free up the handle. You still need to call
14666 "guestfs_close" afterwards.
14667 "guestfs_close" will call this if you don't do it explicitly, but note
14669 that any errors are ignored in that case.
14670 This function returns 0 on success or -1 on error.
14672 (Added in 1.19.16)
14674 guestfs_sleep
14676 int
14677 guestfs_sleep (guestfs_h *g,
14678 int secs);
14679 Sleep for "secs" seconds.
14681 This function returns 0 on success or -1 on error.
14683 (Added in 1.0.41)
14685 guestfs_stat
14687 struct guestfs_stat *
14688 guestfs_stat (guestfs_h *g,
14689 const char *path);
14690 This function is deprecated. In new code, use the "guestfs_statns"
14692 call instead.
14693 Deprecated functions will not be removed from the API, but the fact
14695 that they are deprecated indicates that there are problems with correct
14696 use of these functions.
14697 Returns file information for the given "path".
14699 This is the same as the stat(2) system call.
14701 This function returns a "struct guestfs_stat *", or NULL if there was
14703 an error. The caller must call "guestfs_free_stat" after use.
14704 (Added in 1.9.2)
14706 guestfs_statns
14708 struct guestfs_statns *
14709 guestfs_statns (guestfs_h *g,
14710 const char *path);
14711 Returns file information for the given "path".
14713 This is the same as the stat(2) system call.
14715 This function returns a "struct guestfs_statns *", or NULL if there was
14717 an error. The caller must call "guestfs_free_statns" after use.
14718 (Added in 1.27.53)
14720 guestfs_statvfs
14722 struct guestfs_statvfs *
14723 guestfs_statvfs (guestfs_h *g,
14724 const char *path);
14725 Returns file system statistics for any mounted file system. "path"
14727 should be a file or directory in the mounted file system (typically it
14728 is the mount point itself, but it doesn't need to be).
14729 This is the same as the statvfs(2) system call.
14731 This function returns a "struct guestfs_statvfs *", or NULL if there
14733 was an error. The caller must call "guestfs_free_statvfs" after use.
14734 (Added in 1.9.2)
14736 guestfs_strings
14738 char **
14739 guestfs_strings (guestfs_h *g,
14740 const char *path);
14741 This runs the strings(1) command on a file and returns the list of
14743 printable strings found.
14744 The "strings" command has, in the past, had problems with parsing
14746 untrusted files. These are mitigated in the current version of
14747 libguestfs, but see "CVE-2014-8484".
14748 This function returns a NULL-terminated array of strings (like
14750 environ(3)), or NULL if there was an error. The caller must free the
14751 strings and the array after use.
14752 Because of the message protocol, there is a transfer limit of somewhere
14754 between 2MB and 4MB. See "PROTOCOL LIMITS".
14755 (Added in 1.0.22)
14757 guestfs_strings_e
14759 char **
14760 guestfs_strings_e (guestfs_h *g,
14761 const char *encoding,
14762 const char *path);
14763 This is like the "guestfs_strings" command, but allows you to specify
14765 the encoding of strings that are looked for in the source file "path".
14766 Allowed encodings are:
14768 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14770 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14771 S Single 8-bit-byte characters.
14773 b 16-bit big endian strings such as those encoded in UTF-16BE or
14775 UCS-2BE.
14776 l (lower case letter L)
14778 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14779 for examining binaries in Windows guests.
14780 B 32-bit big endian such as UCS-4BE.
14782 L 32-bit little endian such as UCS-4LE.
14784 The returned strings are transcoded to UTF-8.
14786 The "strings" command has, in the past, had problems with parsing
14788 untrusted files. These are mitigated in the current version of
14789 libguestfs, but see "CVE-2014-8484".
14790 This function returns a NULL-terminated array of strings (like
14792 environ(3)), or NULL if there was an error. The caller must free the
14793 strings and the array after use.
14794 Because of the message protocol, there is a transfer limit of somewhere
14796 between 2MB and 4MB. See "PROTOCOL LIMITS".
14797 (Added in 1.0.22)
14799 guestfs_swapoff_device
14801 int
14802 guestfs_swapoff_device (guestfs_h *g,
14803 const char *device);
14804 This command disables the libguestfs appliance swap device or partition
14806 named "device". See "guestfs_swapon_device".
14807 This function returns 0 on success or -1 on error.
14809 (Added in 1.0.66)
14811 guestfs_swapoff_file
14813 int
14814 guestfs_swapoff_file (guestfs_h *g,
14815 const char *file);
14816 This command disables the libguestfs appliance swap on file.
14818 This function returns 0 on success or -1 on error.
14820 (Added in 1.0.66)
14822 guestfs_swapoff_label
14824 int
14825 guestfs_swapoff_label (guestfs_h *g,
14826 const char *label);
14827 This command disables the libguestfs appliance swap on labeled swap
14829 partition.
14830 This function returns 0 on success or -1 on error.
14832 (Added in 1.0.66)
14834 guestfs_swapoff_uuid
14836 int
14837 guestfs_swapoff_uuid (guestfs_h *g,
14838 const char *uuid);
14839 This command disables the libguestfs appliance swap partition with the
14841 given UUID.
14842 This function returns 0 on success or -1 on error.
14844 This function depends on the feature "linuxfsuuid". See also
14846 "guestfs_feature_available".
14847 (Added in 1.0.66)
14849 guestfs_swapon_device
14851 int
14852 guestfs_swapon_device (guestfs_h *g,
14853 const char *device);
14854 This command enables the libguestfs appliance to use the swap device or
14856 partition named "device". The increased memory is made available for
14857 all commands, for example those run using "guestfs_command" or
14858 "guestfs_sh".
14859 Note that you should not swap to existing guest swap partitions unless
14861 you know what you are doing. They may contain hibernation information,
14862 or other information that the guest doesn't want you to trash. You
14863 also risk leaking information about the host to the guest this way.
14864 Instead, attach a new host device to the guest and swap on that.
14865 This function returns 0 on success or -1 on error.
14867 (Added in 1.0.66)
14869 guestfs_swapon_file
14871 int
14872 guestfs_swapon_file (guestfs_h *g,
14873 const char *file);
14874 This command enables swap to a file. See "guestfs_swapon_device" for
14876 other notes.
14877 This function returns 0 on success or -1 on error.
14879 (Added in 1.0.66)
14881 guestfs_swapon_label
14883 int
14884 guestfs_swapon_label (guestfs_h *g,
14885 const char *label);
14886 This command enables swap to a labeled swap partition. See
14888 "guestfs_swapon_device" for other notes.
14889 This function returns 0 on success or -1 on error.
14891 (Added in 1.0.66)
14893 guestfs_swapon_uuid
14895 int
14896 guestfs_swapon_uuid (guestfs_h *g,
14897 const char *uuid);
14898 This command enables swap to a swap partition with the given UUID. See
14900 "guestfs_swapon_device" for other notes.
14901 This function returns 0 on success or -1 on error.
14903 This function depends on the feature "linuxfsuuid". See also
14905 "guestfs_feature_available".
14906 (Added in 1.0.66)
14908 guestfs_sync
14910 int
14911 guestfs_sync (guestfs_h *g);
14912 This syncs the disk, so that any writes are flushed through to the
14914 underlying disk image.
14915 You should always call this if you have modified a disk image, before
14917 closing the handle.
14918 This function returns 0 on success or -1 on error.
14920 (Added in 0.3)
14922 guestfs_syslinux
14924 int
14925 guestfs_syslinux (guestfs_h *g,
14926 const char *device,
14927 ...);
14928 You may supply a list of optional arguments to this call. Use zero or
14930 more of the following pairs of parameters, and terminate the list with
14931 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14932 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14934 Install the SYSLINUX bootloader on "device".
14936 The device parameter must be either a whole disk formatted as a FAT
14938 filesystem, or a partition formatted as a FAT filesystem. In the
14939 latter case, the partition should be marked as "active"
14940 ("guestfs_part_set_bootable") and a Master Boot Record must be
14941 installed (eg. using "guestfs_pwrite_device") on the first sector of
14942 the whole disk. The SYSLINUX package comes with some suitable Master
14943 Boot Records. See the syslinux(1) man page for further information.
14944 The optional arguments are:
14946 directory
14948 Install SYSLINUX in the named subdirectory, instead of in the root
14949 directory of the FAT filesystem.
14950 Additional configuration can be supplied to SYSLINUX by placing a file
14952 called syslinux.cfg on the FAT filesystem, either in the root
14953 directory, or under directory if that optional argument is being used.
14954 For further information about the contents of this file, see
14955 syslinux(1).
14956 See also "guestfs_extlinux".
14958 This function returns 0 on success or -1 on error.
14960 This function depends on the feature "syslinux". See also
14962 "guestfs_feature_available".
14963 (Added in 1.21.27)
14965 guestfs_syslinux_va
14967 int
14968 guestfs_syslinux_va (guestfs_h *g,
14969 const char *device,
14970 va_list args);
14971 This is the "va_list variant" of "guestfs_syslinux".
14973 See "CALLS WITH OPTIONAL ARGUMENTS".
14975 guestfs_syslinux_argv
14977 int
14978 guestfs_syslinux_argv (guestfs_h *g,
14979 const char *device,
14980 const struct guestfs_syslinux_argv *optargs);
14981 This is the "argv variant" of "guestfs_syslinux".
14983 See "CALLS WITH OPTIONAL ARGUMENTS".
14985 guestfs_tail
14987 char **
14988 guestfs_tail (guestfs_h *g,
14989 const char *path);
14990 This command returns up to the last 10 lines of a file as a list of
14992 strings.
14993 This function returns a NULL-terminated array of strings (like
14995 environ(3)), or NULL if there was an error. The caller must free the
14996 strings and the array after use.
14997 Because of the message protocol, there is a transfer limit of somewhere
14999 between 2MB and 4MB. See "PROTOCOL LIMITS".
15000 (Added in 1.0.54)
15002 guestfs_tail_n
15004 char **
15005 guestfs_tail_n (guestfs_h *g,
15006 int nrlines,
15007 const char *path);
15008 If the parameter "nrlines" is a positive number, this returns the last
15010 "nrlines" lines of the file "path".
15011 If the parameter "nrlines" is a negative number, this returns lines
15013 from the file "path", starting with the "-nrlines"'th line.
15014 If the parameter "nrlines" is zero, this returns an empty list.
15016 This function returns a NULL-terminated array of strings (like
15018 environ(3)), or NULL if there was an error. The caller must free the
15019 strings and the array after use.
15020 Because of the message protocol, there is a transfer limit of somewhere
15022 between 2MB and 4MB. See "PROTOCOL LIMITS".
15023 (Added in 1.0.54)
15025 guestfs_tar_in
15027 int
15028 guestfs_tar_in (guestfs_h *g,
15029 const char *tarfile,
15030 const char *directory);
15031 This function is provided for backwards compatibility with earlier
15033 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
15034 optional arguments.
15035 (Added in 1.0.3)
15037 guestfs_tar_in_opts
15039 int
15040 guestfs_tar_in_opts (guestfs_h *g,
15041 const char *tarfile,
15042 const char *directory,
15043 ...);
15044 You may supply a list of optional arguments to this call. Use zero or
15046 more of the following pairs of parameters, and terminate the list with
15047 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15048 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
15050 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
15051 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
15052 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
15053 This command uploads and unpacks local file "tarfile" into directory.
15055 The optional "compress" flag controls compression. If not given, then
15057 the input should be an uncompressed tar file. Otherwise one of the
15058 following strings may be given to select the compression type of the
15059 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15060 all builds of libguestfs will support all of these compression types).
15061 The other optional arguments are:
15063 "xattrs"
15065 If set to true, extended attributes are restored from the tar file.
15066 "selinux"
15068 If set to true, SELinux contexts are restored from the tar file.
15069 "acls"
15071 If set to true, POSIX ACLs are restored from the tar file.
15072 This function returns 0 on success or -1 on error.
15074 (Added in 1.0.3)
15076 guestfs_tar_in_opts_va
15078 int
15079 guestfs_tar_in_opts_va (guestfs_h *g,
15080 const char *tarfile,
15081 const char *directory,
15082 va_list args);
15083 This is the "va_list variant" of "guestfs_tar_in_opts".
15085 See "CALLS WITH OPTIONAL ARGUMENTS".
15087 guestfs_tar_in_opts_argv
15089 int
15090 guestfs_tar_in_opts_argv (guestfs_h *g,
15091 const char *tarfile,
15092 const char *directory,
15093 const struct guestfs_tar_in_opts_argv *optargs);
15094 This is the "argv variant" of "guestfs_tar_in_opts".
15096 See "CALLS WITH OPTIONAL ARGUMENTS".
15098 guestfs_tar_out
15100 int
15101 guestfs_tar_out (guestfs_h *g,
15102 const char *directory,
15103 const char *tarfile);
15104 This function is provided for backwards compatibility with earlier
15106 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
15107 optional arguments.
15108 (Added in 1.0.3)
15110 guestfs_tar_out_opts
15112 int
15113 guestfs_tar_out_opts (guestfs_h *g,
15114 const char *directory,
15115 const char *tarfile,
15116 ...);
15117 You may supply a list of optional arguments to this call. Use zero or
15119 more of the following pairs of parameters, and terminate the list with
15120 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15121 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
15123 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
15124 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
15125 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
15126 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
15127 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
15128 This command packs the contents of directory and downloads it to local
15130 file "tarfile".
15131 The optional "compress" flag controls compression. If not given, then
15133 the output will be an uncompressed tar file. Otherwise one of the
15134 following strings may be given to select the compression type of the
15135 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15136 all builds of libguestfs will support all of these compression types).
15137 The other optional arguments are:
15139 "excludes"
15141 A list of wildcards. Files are excluded if they match any of the
15142 wildcards.
15143 "numericowner"
15145 If set to true, the output tar file will contain UID/GID numbers
15146 instead of user/group names.
15147 "xattrs"
15149 If set to true, extended attributes are saved in the output tar.
15150 "selinux"
15152 If set to true, SELinux contexts are saved in the output tar.
15153 "acls"
15155 If set to true, POSIX ACLs are saved in the output tar.
15156 This function returns 0 on success or -1 on error.
15158 (Added in 1.0.3)
15160 guestfs_tar_out_opts_va
15162 int
15163 guestfs_tar_out_opts_va (guestfs_h *g,
15164 const char *directory,
15165 const char *tarfile,
15166 va_list args);
15167 This is the "va_list variant" of "guestfs_tar_out_opts".
15169 See "CALLS WITH OPTIONAL ARGUMENTS".
15171 guestfs_tar_out_opts_argv
15173 int
15174 guestfs_tar_out_opts_argv (guestfs_h *g,
15175 const char *directory,
15176 const char *tarfile,
15177 const struct guestfs_tar_out_opts_argv *optargs);
15178 This is the "argv variant" of "guestfs_tar_out_opts".
15180 See "CALLS WITH OPTIONAL ARGUMENTS".
15182 guestfs_tgz_in
15184 int
15185 guestfs_tgz_in (guestfs_h *g,
15186 const char *tarball,
15187 const char *directory);
15188 This function is deprecated. In new code, use the "guestfs_tar_in"
15190 call instead.
15191 Deprecated functions will not be removed from the API, but the fact
15193 that they are deprecated indicates that there are problems with correct
15194 use of these functions.
15195 This command uploads and unpacks local file "tarball" (a gzip
15197 compressed tar file) into directory.
15198 This function returns 0 on success or -1 on error.
15200 (Added in 1.0.3)
15202 guestfs_tgz_out
15204 int
15205 guestfs_tgz_out (guestfs_h *g,
15206 const char *directory,
15207 const char *tarball);
15208 This function is deprecated. In new code, use the "guestfs_tar_out"
15210 call instead.
15211 Deprecated functions will not be removed from the API, but the fact
15213 that they are deprecated indicates that there are problems with correct
15214 use of these functions.
15215 This command packs the contents of directory and downloads it to local
15217 file "tarball".
15218 This function returns 0 on success or -1 on error.
15220 (Added in 1.0.3)
15222 guestfs_touch
15224 int
15225 guestfs_touch (guestfs_h *g,
15226 const char *path);
15227 Touch acts like the touch(1) command. It can be used to update the
15229 timestamps on a file, or, if the file does not exist, to create a new
15230 zero-length file.
15231 This command only works on regular files, and will fail on other file
15233 types such as directories, symbolic links, block special etc.
15234 This function returns 0 on success or -1 on error.
15236 (Added in 0.3)
15238 guestfs_truncate
15240 int
15241 guestfs_truncate (guestfs_h *g,
15242 const char *path);
15243 This command truncates "path" to a zero-length file. The file must
15245 exist already.
15246 This function returns 0 on success or -1 on error.
15248 (Added in 1.0.77)
15250 guestfs_truncate_size
15252 int
15253 guestfs_truncate_size (guestfs_h *g,
15254 const char *path,
15255 int64_t size);
15256 This command truncates "path" to size "size" bytes. The file must
15258 exist already.
15259 If the current file size is less than "size" then the file is extended
15261 to the required size with zero bytes. This creates a sparse file (ie.
15262 disk blocks are not allocated for the file until you write to it). To
15263 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15264 This function returns 0 on success or -1 on error.
15266 (Added in 1.0.77)
15268 guestfs_tune2fs
15270 int
15271 guestfs_tune2fs (guestfs_h *g,
15272 const char *device,
15273 ...);
15274 You may supply a list of optional arguments to this call. Use zero or
15276 more of the following pairs of parameters, and terminate the list with
15277 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15278 GUESTFS_TUNE2FS_FORCE, int force,
15280 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15281 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15282 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15283 GUESTFS_TUNE2FS_GROUP, int64_t group,
15284 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15285 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15286 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15287 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15288 GUESTFS_TUNE2FS_USER, int64_t user,
15289 This call allows you to adjust various filesystem parameters of an
15291 ext2/ext3/ext4 filesystem called "device".
15292 The optional parameters are:
15294 "force"
15296 Force tune2fs to complete the operation even in the face of errors.
15297 This is the same as the tune2fs(8) "-f" option.
15298 "maxmountcount"
15300 Set the number of mounts after which the filesystem is checked by
15301 e2fsck(8). If this is 0 then the number of mounts is disregarded.
15302 This is the same as the tune2fs(8) "-c" option.
15303 "mountcount"
15305 Set the number of times the filesystem has been mounted. This is
15306 the same as the tune2fs(8) "-C" option.
15307 "errorbehavior"
15309 Change the behavior of the kernel code when errors are detected.
15310 Possible values currently are: "continue", "remount-ro", "panic".
15311 In practice these options don't really make any difference,
15312 particularly for write errors.
15313 This is the same as the tune2fs(8) "-e" option.
15315 "group"
15317 Set the group which can use reserved filesystem blocks. This is
15318 the same as the tune2fs(8) "-g" option except that it can only be
15319 specified as a number.
15320 "intervalbetweenchecks"
15322 Adjust the maximal time between two filesystem checks (in seconds).
15323 If the option is passed as 0 then time-dependent checking is
15324 disabled.
15325 This is the same as the tune2fs(8) "-i" option.
15327 "reservedblockspercentage"
15329 Set the percentage of the filesystem which may only be allocated by
15330 privileged processes. This is the same as the tune2fs(8) "-m"
15331 option.
15332 "lastmounteddirectory"
15334 Set the last mounted directory. This is the same as the tune2fs(8)
15335 "-M" option.
15336 "reservedblockscount" Set the number of reserved filesystem blocks.
15338 This is the same as the tune2fs(8) "-r" option.
15339 "user"
15340 Set the user who can use the reserved filesystem blocks. This is
15341 the same as the tune2fs(8) "-u" option except that it can only be
15342 specified as a number.
15343 To get the current values of filesystem parameters, see
15345 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
15346 tune2fs(8) man page.
15347 This function returns 0 on success or -1 on error.
15349 (Added in 1.15.4)
15351 guestfs_tune2fs_va
15353 int
15354 guestfs_tune2fs_va (guestfs_h *g,
15355 const char *device,
15356 va_list args);
15357 This is the "va_list variant" of "guestfs_tune2fs".
15359 See "CALLS WITH OPTIONAL ARGUMENTS".
15361 guestfs_tune2fs_argv
15363 int
15364 guestfs_tune2fs_argv (guestfs_h *g,
15365 const char *device,
15366 const struct guestfs_tune2fs_argv *optargs);
15367 This is the "argv variant" of "guestfs_tune2fs".
15369 See "CALLS WITH OPTIONAL ARGUMENTS".
15371 guestfs_tune2fs_l
15373 char **
15374 guestfs_tune2fs_l (guestfs_h *g,
15375 const char *device);
15376 This returns the contents of the ext2, ext3 or ext4 filesystem
15378 superblock on "device".
15379 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
15381 for more details. The list of fields returned isn't clearly defined,
15382 and depends on both the version of "tune2fs" that libguestfs was built
15383 against, and the filesystem itself.
15384 This function returns a NULL-terminated array of strings, or NULL if
15386 there was an error. The array of strings will always have length
15387 "2n+1", where "n" keys and values alternate, followed by the trailing
15388 NULL entry. The caller must free the strings and the array after use.
15389 (Added in 1.9.2)
15391 guestfs_txz_in
15393 int
15394 guestfs_txz_in (guestfs_h *g,
15395 const char *tarball,
15396 const char *directory);
15397 This function is deprecated. In new code, use the "guestfs_tar_in"
15399 call instead.
15400 Deprecated functions will not be removed from the API, but the fact
15402 that they are deprecated indicates that there are problems with correct
15403 use of these functions.
15404 This command uploads and unpacks local file "tarball" (an xz compressed
15406 tar file) into directory.
15407 This function returns 0 on success or -1 on error.
15409 This function depends on the feature "xz". See also
15411 "guestfs_feature_available".
15412 (Added in 1.3.2)
15414 guestfs_txz_out
15416 int
15417 guestfs_txz_out (guestfs_h *g,
15418 const char *directory,
15419 const char *tarball);
15420 This function is deprecated. In new code, use the "guestfs_tar_out"
15422 call instead.
15423 Deprecated functions will not be removed from the API, but the fact
15425 that they are deprecated indicates that there are problems with correct
15426 use of these functions.
15427 This command packs the contents of directory and downloads it to local
15429 file "tarball" (as an xz compressed tar archive).
15430 This function returns 0 on success or -1 on error.
15432 This function depends on the feature "xz". See also
15434 "guestfs_feature_available".
15435 (Added in 1.3.2)
15437 guestfs_umask
15439 int
15440 guestfs_umask (guestfs_h *g,
15441 int mask);
15442 This function sets the mask used for creating new files and device
15444 nodes to "mask & 0777".
15445 Typical umask values would be 022 which creates new files with
15447 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15448 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15449 The default umask is 022. This is important because it means that
15451 directories and device nodes will be created with 0644 or 0755 mode
15452 even if you specify 0777.
15453 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15455 "guestfs_mkdir".
15456 This call returns the previous umask.
15458 On error this function returns -1.
15460 (Added in 1.0.55)
15462 guestfs_umount
15464 int
15465 guestfs_umount (guestfs_h *g,
15466 const char *pathordevice);
15467 This function is provided for backwards compatibility with earlier
15469 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15470 optional arguments.
15471 (Added in 0.8)
15473 guestfs_umount_opts
15475 int
15476 guestfs_umount_opts (guestfs_h *g,
15477 const char *pathordevice,
15478 ...);
15479 You may supply a list of optional arguments to this call. Use zero or
15481 more of the following pairs of parameters, and terminate the list with
15482 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15483 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15485 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15486 This unmounts the given filesystem. The filesystem may be specified
15488 either by its mountpoint (path) or the device which contains the
15489 filesystem.
15490 This function returns 0 on success or -1 on error.
15492 (Added in 0.8)
15494 guestfs_umount_opts_va
15496 int
15497 guestfs_umount_opts_va (guestfs_h *g,
15498 const char *pathordevice,
15499 va_list args);
15500 This is the "va_list variant" of "guestfs_umount_opts".
15502 See "CALLS WITH OPTIONAL ARGUMENTS".
15504 guestfs_umount_opts_argv
15506 int
15507 guestfs_umount_opts_argv (guestfs_h *g,
15508 const char *pathordevice,
15509 const struct guestfs_umount_opts_argv *optargs);
15510 This is the "argv variant" of "guestfs_umount_opts".
15512 See "CALLS WITH OPTIONAL ARGUMENTS".
15514 guestfs_umount_all
15516 int
15517 guestfs_umount_all (guestfs_h *g);
15518 This unmounts all mounted filesystems.
15520 Some internal mounts are not unmounted by this call.
15522 This function returns 0 on success or -1 on error.
15524 (Added in 0.8)
15526 guestfs_umount_local
15528 int
15529 guestfs_umount_local (guestfs_h *g,
15530 ...);
15531 You may supply a list of optional arguments to this call. Use zero or
15533 more of the following pairs of parameters, and terminate the list with
15534 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15535 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15537 If libguestfs is exporting the filesystem on a local mountpoint, then
15539 this unmounts it.
15540 See "MOUNT LOCAL" for full documentation.
15542 This function returns 0 on success or -1 on error.
15544 (Added in 1.17.22)
15546 guestfs_umount_local_va
15548 int
15549 guestfs_umount_local_va (guestfs_h *g,
15550 va_list args);
15551 This is the "va_list variant" of "guestfs_umount_local".
15553 See "CALLS WITH OPTIONAL ARGUMENTS".
15555 guestfs_umount_local_argv
15557 int
15558 guestfs_umount_local_argv (guestfs_h *g,
15559 const struct guestfs_umount_local_argv *optargs);
15560 This is the "argv variant" of "guestfs_umount_local".
15562 See "CALLS WITH OPTIONAL ARGUMENTS".
15564 guestfs_upload
15566 int
15567 guestfs_upload (guestfs_h *g,
15568 const char *filename,
15569 const char *remotefilename);
15570 Upload local file filename to remotefilename on the filesystem.
15572 filename can also be a named pipe.
15574 See also "guestfs_download".
15576 This function returns 0 on success or -1 on error.
15578 This long-running command can generate progress notification messages
15580 so that the caller can display a progress bar or indicator. To receive
15581 these messages, the caller must register a progress event callback.
15582 See "GUESTFS_EVENT_PROGRESS".
15583 (Added in 1.0.2)
15585 guestfs_upload_offset
15587 int
15588 guestfs_upload_offset (guestfs_h *g,
15589 const char *filename,
15590 const char *remotefilename,
15591 int64_t offset);
15592 Upload local file filename to remotefilename on the filesystem.
15594 remotefilename is overwritten starting at the byte "offset" specified.
15596 The intention is to overwrite parts of existing files or devices,
15597 although if a non-existent file is specified then it is created with a
15598 "hole" before "offset". The size of the data written is implicit in
15599 the size of the source filename.
15600 Note that there is no limit on the amount of data that can be uploaded
15602 with this call, unlike with "guestfs_pwrite", and this call always
15603 writes the full amount unless an error occurs.
15604 See also "guestfs_upload", "guestfs_pwrite".
15606 This function returns 0 on success or -1 on error.
15608 This long-running command can generate progress notification messages
15610 so that the caller can display a progress bar or indicator. To receive
15611 these messages, the caller must register a progress event callback.
15612 See "GUESTFS_EVENT_PROGRESS".
15613 (Added in 1.5.17)
15615 guestfs_user_cancel
15617 int
15618 guestfs_user_cancel (guestfs_h *g);
15619 This function cancels the current upload or download operation.
15621 Unlike most other libguestfs calls, this function is signal safe and
15623 thread safe. You can call it from a signal handler or from another
15624 thread, without needing to do any locking.
15625 The transfer that was in progress (if there is one) will stop shortly
15627 afterwards, and will return an error. The errno (see
15628 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15629 find out if the operation was cancelled or failed because of another
15630 error.
15631 No cleanup is performed: for example, if a file was being uploaded then
15633 after cancellation there may be a partially uploaded file. It is the
15634 caller’s responsibility to clean up if necessary.
15635 There are two common places that you might call "guestfs_user_cancel":
15637 In an interactive text-based program, you might call it from a "SIGINT"
15639 signal handler so that pressing "^C" cancels the current operation.
15640 (You also need to call "guestfs_set_pgroup" so that child processes
15641 don't receive the "^C" signal).
15642 In a graphical program, when the main thread is displaying a progress
15644 bar with a cancel button, wire up the cancel button to call this
15645 function.
15646 This function returns 0 on success or -1 on error.
15648 (Added in 1.11.18)
15650 guestfs_utimens
15652 int
15653 guestfs_utimens (guestfs_h *g,
15654 const char *path,
15655 int64_t atsecs,
15656 int64_t atnsecs,
15657 int64_t mtsecs,
15658 int64_t mtnsecs);
15659 This command sets the timestamps of a file with nanosecond precision.
15661 "atsecs", "atnsecs" are the last access time (atime) in secs and
15663 nanoseconds from the epoch.
15664 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
15666 nanoseconds from the epoch.
15667 If the *nsecs field contains the special value "-1" then the
15669 corresponding timestamp is set to the current time. (The *secs field
15670 is ignored in this case).
15671 If the *nsecs field contains the special value "-2" then the
15673 corresponding timestamp is left unchanged. (The *secs field is ignored
15674 in this case).
15675 This function returns 0 on success or -1 on error.
15677 (Added in 1.0.77)
15679 guestfs_utsname
15681 struct guestfs_utsname *
15682 guestfs_utsname (guestfs_h *g);
15683 This returns the kernel version of the appliance, where this is
15685 available. This information is only useful for debugging. Nothing in
15686 the returned structure is defined by the API.
15687 This function returns a "struct guestfs_utsname *", or NULL if there
15689 was an error. The caller must call "guestfs_free_utsname" after use.
15690 (Added in 1.19.27)
15692 guestfs_version
15694 struct guestfs_version *
15695 guestfs_version (guestfs_h *g);
15696 Return the libguestfs version number that the program is linked
15698 against.
15699 Note that because of dynamic linking this is not necessarily the
15701 version of libguestfs that you compiled against. You can compile the
15702 program, and then at runtime dynamically link against a completely
15703 different libguestfs.so library.
15704 This call was added in version 1.0.58. In previous versions of
15706 libguestfs there was no way to get the version number. From C code you
15707 can use dynamic linker functions to find out if this symbol exists (if
15708 it doesn't, then it’s an earlier version).
15709 The call returns a structure with four elements. The first three
15711 ("major", "minor" and "release") are numbers and correspond to the
15712 usual version triplet. The fourth element ("extra") is a string and is
15713 normally empty, but may be used for distro-specific information.
15714 To construct the original version string:
15716 "$major.$minor.$release$extra"
15717 See also: "LIBGUESTFS VERSION NUMBERS".
15719 Note: Don't use this call to test for availability of features. In
15721 enterprise distributions we backport features from later versions into
15722 earlier versions, making this an unreliable way to test for features.
15723 Use "guestfs_available" or "guestfs_feature_available" instead.
15724 This function returns a "struct guestfs_version *", or NULL if there
15726 was an error. The caller must call "guestfs_free_version" after use.
15727 (Added in 1.0.58)
15729 guestfs_vfs_label
15731 char *
15732 guestfs_vfs_label (guestfs_h *g,
15733 const char *mountable);
15734 This returns the label of the filesystem on "mountable".
15736 If the filesystem is unlabeled, this returns the empty string.
15738 To find a filesystem from the label, use "guestfs_findfs_label".
15740 This function returns a string, or NULL on error. The caller must free
15742 the returned string after use.
15743 (Added in 1.3.18)
15745 guestfs_vfs_minimum_size
15747 int64_t
15748 guestfs_vfs_minimum_size (guestfs_h *g,
15749 const char *mountable);
15750 Get the minimum size of filesystem in bytes. This is the minimum
15752 possible size for filesystem shrinking.
15753 If getting minimum size of specified filesystem is not supported, this
15755 will fail and set errno as ENOTSUP.
15756 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15758 On error this function returns -1.
15760 (Added in 1.31.18)
15762 guestfs_vfs_type
15764 char *
15765 guestfs_vfs_type (guestfs_h *g,
15766 const char *mountable);
15767 This command gets the filesystem type corresponding to the filesystem
15769 on "mountable".
15770 For most filesystems, the result is the name of the Linux VFS module
15772 which would be used to mount this filesystem if you mounted it without
15773 specifying the filesystem type. For example a string such as "ext3" or
15774 "ntfs".
15775 This function returns a string, or NULL on error. The caller must free
15777 the returned string after use.
15778 (Added in 1.0.75)
15780 guestfs_vfs_uuid
15782 char *
15783 guestfs_vfs_uuid (guestfs_h *g,
15784 const char *mountable);
15785 This returns the filesystem UUID of the filesystem on "mountable".
15787 If the filesystem does not have a UUID, this returns the empty string.
15789 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15791 This function returns a string, or NULL on error. The caller must free
15793 the returned string after use.
15794 (Added in 1.3.18)
15796 guestfs_vg_activate
15798 int
15799 guestfs_vg_activate (guestfs_h *g,
15800 int activate,
15801 char *const *volgroups);
15802 This command activates or (if "activate" is false) deactivates all
15804 logical volumes in the listed volume groups "volgroups".
15805 This command is the same as running "vgchange -a y|n volgroups..."
15807 Note that if "volgroups" is an empty list then all volume groups are
15809 activated or deactivated.
15810 This function returns 0 on success or -1 on error.
15812 This function depends on the feature "lvm2". See also
15814 "guestfs_feature_available".
15815 (Added in 1.0.26)
15817 guestfs_vg_activate_all
15819 int
15820 guestfs_vg_activate_all (guestfs_h *g,
15821 int activate);
15822 This command activates or (if "activate" is false) deactivates all
15824 logical volumes in all volume groups.
15825 This command is the same as running "vgchange -a y|n"
15827 This function returns 0 on success or -1 on error.
15829 This function depends on the feature "lvm2". See also
15831 "guestfs_feature_available".
15832 (Added in 1.0.26)
15834 guestfs_vgchange_uuid
15836 int
15837 guestfs_vgchange_uuid (guestfs_h *g,
15838 const char *vg);
15839 Generate a new random UUID for the volume group "vg".
15841 This function returns 0 on success or -1 on error.
15843 This function depends on the feature "lvm2". See also
15845 "guestfs_feature_available".
15846 (Added in 1.19.26)
15848 guestfs_vgchange_uuid_all
15850 int
15851 guestfs_vgchange_uuid_all (guestfs_h *g);
15852 Generate new random UUIDs for all volume groups.
15854 This function returns 0 on success or -1 on error.
15856 This function depends on the feature "lvm2". See also
15858 "guestfs_feature_available".
15859 (Added in 1.19.26)
15861 guestfs_vgcreate
15863 int
15864 guestfs_vgcreate (guestfs_h *g,
15865 const char *volgroup,
15866 char *const *physvols);
15867 This creates an LVM volume group called "volgroup" from the non-empty
15869 list of physical volumes "physvols".
15870 This function returns 0 on success or -1 on error.
15872 This function depends on the feature "lvm2". See also
15874 "guestfs_feature_available".
15875 (Added in 0.8)
15877 guestfs_vglvuuids
15879 char **
15880 guestfs_vglvuuids (guestfs_h *g,
15881 const char *vgname);
15882 Given a VG called "vgname", this returns the UUIDs of all the logical
15884 volumes created in this volume group.
15885 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15887 associate logical volumes and volume groups.
15888 See also "guestfs_vgpvuuids".
15890 This function returns a NULL-terminated array of strings (like
15892 environ(3)), or NULL if there was an error. The caller must free the
15893 strings and the array after use.
15894 (Added in 1.0.87)
15896 guestfs_vgmeta
15898 char *
15899 guestfs_vgmeta (guestfs_h *g,
15900 const char *vgname,
15901 size_t *size_r);
15902 "vgname" is an LVM volume group. This command examines the volume
15904 group and returns its metadata.
15905 Note that the metadata is an internal structure used by LVM, subject to
15907 change at any time, and is provided for information only.
15908 This function returns a buffer, or NULL on error. The size of the
15910 returned buffer is written to *size_r. The caller must free the
15911 returned buffer after use.
15912 This function depends on the feature "lvm2". See also
15914 "guestfs_feature_available".
15915 (Added in 1.17.20)
15917 guestfs_vgpvuuids
15919 char **
15920 guestfs_vgpvuuids (guestfs_h *g,
15921 const char *vgname);
15922 Given a VG called "vgname", this returns the UUIDs of all the physical
15924 volumes that this volume group resides on.
15925 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15927 associate physical volumes and volume groups.
15928 See also "guestfs_vglvuuids".
15930 This function returns a NULL-terminated array of strings (like
15932 environ(3)), or NULL if there was an error. The caller must free the
15933 strings and the array after use.
15934 (Added in 1.0.87)
15936 guestfs_vgremove
15938 int
15939 guestfs_vgremove (guestfs_h *g,
15940 const char *vgname);
15941 Remove an LVM volume group "vgname", (for example "VG").
15943 This also forcibly removes all logical volumes in the volume group (if
15945 any).
15946 This function returns 0 on success or -1 on error.
15948 This function depends on the feature "lvm2". See also
15950 "guestfs_feature_available".
15951 (Added in 1.0.13)
15953 guestfs_vgrename
15955 int
15956 guestfs_vgrename (guestfs_h *g,
15957 const char *volgroup,
15958 const char *newvolgroup);
15959 Rename a volume group "volgroup" with the new name "newvolgroup".
15961 This function returns 0 on success or -1 on error.
15963 (Added in 1.0.83)
15965 guestfs_vgs
15967 char **
15968 guestfs_vgs (guestfs_h *g);
15969 List all the volumes groups detected. This is the equivalent of the
15971 vgs(8) command.
15972 This returns a list of just the volume group names that were detected
15974 (eg. "VolGroup00").
15975 See also "guestfs_vgs_full".
15977 This function returns a NULL-terminated array of strings (like
15979 environ(3)), or NULL if there was an error. The caller must free the
15980 strings and the array after use.
15981 This function depends on the feature "lvm2". See also
15983 "guestfs_feature_available".
15984 (Added in 0.4)
15986 guestfs_vgs_full
15988 struct guestfs_lvm_vg_list *
15989 guestfs_vgs_full (guestfs_h *g);
15990 List all the volumes groups detected. This is the equivalent of the
15992 vgs(8) command. The "full" version includes all fields.
15993 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
15995 there was an error. The caller must call "guestfs_free_lvm_vg_list"
15996 after use.
15997 This function depends on the feature "lvm2". See also
15999 "guestfs_feature_available".
16000 (Added in 0.4)
16002 guestfs_vgscan
16004 int
16005 guestfs_vgscan (guestfs_h *g);
16006 This function is deprecated. In new code, use the "guestfs_lvm_scan"
16008 call instead.
16009 Deprecated functions will not be removed from the API, but the fact
16011 that they are deprecated indicates that there are problems with correct
16012 use of these functions.
16013 This rescans all block devices and rebuilds the list of LVM physical
16015 volumes, volume groups and logical volumes.
16016 This function returns 0 on success or -1 on error.
16018 (Added in 1.3.2)
16020 guestfs_vguuid
16022 char *
16023 guestfs_vguuid (guestfs_h *g,
16024 const char *vgname);
16025 This command returns the UUID of the LVM VG named "vgname".
16027 This function returns a string, or NULL on error. The caller must free
16029 the returned string after use.
16030 (Added in 1.0.87)
16032 guestfs_wait_ready
16034 int
16035 guestfs_wait_ready (guestfs_h *g);
16036 This function is deprecated. There is no replacement. Consult the API
16038 documentation in guestfs(3) for further information.
16039 Deprecated functions will not be removed from the API, but the fact
16041 that they are deprecated indicates that there are problems with correct
16042 use of these functions.
16043 This function is a no op.
16045 In versions of the API < 1.0.71 you had to call this function just
16047 after calling "guestfs_launch" to wait for the launch to complete.
16048 However this is no longer necessary because "guestfs_launch" now does
16049 the waiting.
16050 If you see any calls to this function in code then you can just remove
16052 them, unless you want to retain compatibility with older versions of
16053 the API.
16054 This function returns 0 on success or -1 on error.
16056 (Added in 0.3)
16058 guestfs_wc_c
16060 int
16061 guestfs_wc_c (guestfs_h *g,
16062 const char *path);
16063 This command counts the characters in a file, using the "wc -c"
16065 external command.
16066 On error this function returns -1.
16068 (Added in 1.0.54)
16070 guestfs_wc_l
16072 int
16073 guestfs_wc_l (guestfs_h *g,
16074 const char *path);
16075 This command counts the lines in a file, using the "wc -l" external
16077 command.
16078 On error this function returns -1.
16080 (Added in 1.0.54)
16082 guestfs_wc_w
16084 int
16085 guestfs_wc_w (guestfs_h *g,
16086 const char *path);
16087 This command counts the words in a file, using the "wc -w" external
16089 command.
16090 On error this function returns -1.
16092 (Added in 1.0.54)
16094 guestfs_wipefs
16096 int
16097 guestfs_wipefs (guestfs_h *g,
16098 const char *device);
16099 This command erases filesystem or RAID signatures from the specified
16101 "device" to make the filesystem invisible to libblkid.
16102 This does not erase the filesystem itself nor any other data from the
16104 "device".
16105 Compare with "guestfs_zero" which zeroes the first few blocks of a
16107 device.
16108 This function returns 0 on success or -1 on error.
16110 This function depends on the feature "wipefs". See also
16112 "guestfs_feature_available".
16113 (Added in 1.17.6)
16115 guestfs_write
16117 int
16118 guestfs_write (guestfs_h *g,
16119 const char *path,
16120 const char *content,
16121 size_t content_size);
16122 This call creates a file called "path". The content of the file is the
16124 string "content" (which can contain any 8 bit data).
16125 See also "guestfs_write_append".
16127 This function returns 0 on success or -1 on error.
16129 (Added in 1.3.14)
16131 guestfs_write_append
16133 int
16134 guestfs_write_append (guestfs_h *g,
16135 const char *path,
16136 const char *content,
16137 size_t content_size);
16138 This call appends "content" to the end of file "path". If "path" does
16140 not exist, then a new file is created.
16141 See also "guestfs_write".
16143 This function returns 0 on success or -1 on error.
16145 (Added in 1.11.18)
16147 guestfs_write_file
16149 int
16150 guestfs_write_file (guestfs_h *g,
16151 const char *path,
16152 const char *content,
16153 int size);
16154 This function is deprecated. In new code, use the "guestfs_write" call
16156 instead.
16157 Deprecated functions will not be removed from the API, but the fact
16159 that they are deprecated indicates that there are problems with correct
16160 use of these functions.
16161 This call creates a file called "path". The contents of the file is
16163 the string "content" (which can contain any 8 bit data), with length
16164 "size".
16165 As a special case, if "size" is 0 then the length is calculated using
16167 "strlen" (so in this case the content cannot contain embedded ASCII
16168 NULs).
16169 NB. Owing to a bug, writing content containing ASCII NUL characters
16171 does not work, even if the length is specified.
16172 This function returns 0 on success or -1 on error.
16174 Because of the message protocol, there is a transfer limit of somewhere
16176 between 2MB and 4MB. See "PROTOCOL LIMITS".
16177 (Added in 0.8)
16179 guestfs_xfs_admin
16181 int
16182 guestfs_xfs_admin (guestfs_h *g,
16183 const char *device,
16184 ...);
16185 You may supply a list of optional arguments to this call. Use zero or
16187 more of the following pairs of parameters, and terminate the list with
16188 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16189 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16191 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16192 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16193 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16194 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16195 GUESTFS_XFS_ADMIN_LABEL, const char *label,
16196 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16197 Change the parameters of the XFS filesystem on "device".
16199 Devices that are mounted cannot be modified. Administrators must
16201 unmount filesystems before this call can modify parameters.
16202 Some of the parameters of a mounted filesystem can be examined and
16204 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16205 This function returns 0 on success or -1 on error.
16207 This function depends on the feature "xfs". See also
16209 "guestfs_feature_available".
16210 (Added in 1.19.33)
16212 guestfs_xfs_admin_va
16214 int
16215 guestfs_xfs_admin_va (guestfs_h *g,
16216 const char *device,
16217 va_list args);
16218 This is the "va_list variant" of "guestfs_xfs_admin".
16220 See "CALLS WITH OPTIONAL ARGUMENTS".
16222 guestfs_xfs_admin_argv
16224 int
16225 guestfs_xfs_admin_argv (guestfs_h *g,
16226 const char *device,
16227 const struct guestfs_xfs_admin_argv *optargs);
16228 This is the "argv variant" of "guestfs_xfs_admin".
16230 See "CALLS WITH OPTIONAL ARGUMENTS".
16232 guestfs_xfs_growfs
16234 int
16235 guestfs_xfs_growfs (guestfs_h *g,
16236 const char *path,
16237 ...);
16238 You may supply a list of optional arguments to this call. Use zero or
16240 more of the following pairs of parameters, and terminate the list with
16241 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16242 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16244 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16245 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16246 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16247 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16248 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16249 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16250 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16251 Grow the XFS filesystem mounted at "path".
16253 The returned struct contains geometry information. Missing fields are
16255 returned as "-1" (for numeric fields) or empty string.
16256 This function returns 0 on success or -1 on error.
16258 This function depends on the feature "xfs". See also
16260 "guestfs_feature_available".
16261 (Added in 1.19.28)
16263 guestfs_xfs_growfs_va
16265 int
16266 guestfs_xfs_growfs_va (guestfs_h *g,
16267 const char *path,
16268 va_list args);
16269 This is the "va_list variant" of "guestfs_xfs_growfs".
16271 See "CALLS WITH OPTIONAL ARGUMENTS".
16273 guestfs_xfs_growfs_argv
16275 int
16276 guestfs_xfs_growfs_argv (guestfs_h *g,
16277 const char *path,
16278 const struct guestfs_xfs_growfs_argv *optargs);
16279 This is the "argv variant" of "guestfs_xfs_growfs".
16281 See "CALLS WITH OPTIONAL ARGUMENTS".
16283 guestfs_xfs_info
16285 struct guestfs_xfsinfo *
16286 guestfs_xfs_info (guestfs_h *g,
16287 const char *pathordevice);
16288 "pathordevice" is a mounted XFS filesystem or a device containing an
16290 XFS filesystem. This command returns the geometry of the filesystem.
16291 The returned struct contains geometry information. Missing fields are
16293 returned as "-1" (for numeric fields) or empty string.
16294 This function returns a "struct guestfs_xfsinfo *", or NULL if there
16296 was an error. The caller must call "guestfs_free_xfsinfo" after use.
16297 This function depends on the feature "xfs". See also
16299 "guestfs_feature_available".
16300 (Added in 1.19.21)
16302 guestfs_xfs_repair
16304 int
16305 guestfs_xfs_repair (guestfs_h *g,
16306 const char *device,
16307 ...);
16308 You may supply a list of optional arguments to this call. Use zero or
16310 more of the following pairs of parameters, and terminate the list with
16311 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16312 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16314 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16315 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16316 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16317 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16318 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16319 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16320 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16321 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16322 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16323 Repair corrupt or damaged XFS filesystem on "device".
16325 The filesystem is specified using the "device" argument which should be
16327 the device name of the disk partition or volume containing the
16328 filesystem. If given the name of a block device, "xfs_repair" will
16329 attempt to find the raw device associated with the specified block
16330 device and will use the raw device instead.
16331 Regardless, the filesystem to be repaired must be unmounted, otherwise,
16333 the resulting filesystem may be inconsistent or corrupt.
16334 The returned status indicates whether filesystem corruption was
16336 detected (returns 1) or was not detected (returns 0).
16337 On error this function returns -1.
16339 This function depends on the feature "xfs". See also
16341 "guestfs_feature_available".
16342 (Added in 1.19.36)
16344 guestfs_xfs_repair_va
16346 int
16347 guestfs_xfs_repair_va (guestfs_h *g,
16348 const char *device,
16349 va_list args);
16350 This is the "va_list variant" of "guestfs_xfs_repair".
16352 See "CALLS WITH OPTIONAL ARGUMENTS".
16354 guestfs_xfs_repair_argv
16356 int
16357 guestfs_xfs_repair_argv (guestfs_h *g,
16358 const char *device,
16359 const struct guestfs_xfs_repair_argv *optargs);
16360 This is the "argv variant" of "guestfs_xfs_repair".
16362 See "CALLS WITH OPTIONAL ARGUMENTS".
16364 guestfs_yara_destroy
16366 int
16367 guestfs_yara_destroy (guestfs_h *g);
16368 Destroy previously loaded Yara rules in order to free libguestfs
16370 resources.
16371 This function returns 0 on success or -1 on error.
16373 This function depends on the feature "libyara". See also
16375 "guestfs_feature_available".
16376 (Added in 1.37.13)
16378 guestfs_yara_load
16380 int
16381 guestfs_yara_load (guestfs_h *g,
16382 const char *filename);
16383 Upload a set of Yara rules from local file filename.
16385 Yara rules allow to categorize files based on textual or binary
16387 patterns within their content. See "guestfs_yara_scan" to see how to
16388 scan files with the loaded rules.
16389 Rules can be in binary format, as when compiled with yarac command, or
16391 in source code format. In the latter case, the rules will be first
16392 compiled and then loaded.
16393 Rules in source code format cannot include external files. In such
16395 cases, it is recommended to compile them first.
16396 Previously loaded rules will be destroyed.
16398 This function returns 0 on success or -1 on error.
16400 This long-running command can generate progress notification messages
16402 so that the caller can display a progress bar or indicator. To receive
16403 these messages, the caller must register a progress event callback.
16404 See "GUESTFS_EVENT_PROGRESS".
16405 This function depends on the feature "libyara". See also
16407 "guestfs_feature_available".
16408 (Added in 1.37.13)
16410 guestfs_yara_scan
16412 struct guestfs_yara_detection_list *
16413 guestfs_yara_scan (guestfs_h *g,
16414 const char *path);
16415 Scan a file with the previously loaded Yara rules.
16417 For each matching rule, a "yara_detection" structure is returned.
16419 The "yara_detection" structure contains the following fields.
16421 "yara_name"
16423 Path of the file matching a Yara rule.
16424 "yara_rule"
16426 Identifier of the Yara rule which matched against the given file.
16427 This function returns a "struct guestfs_yara_detection_list *", or NULL
16429 if there was an error. The caller must call
16430 "guestfs_free_yara_detection_list" after use.
16431 This long-running command can generate progress notification messages
16433 so that the caller can display a progress bar or indicator. To receive
16434 these messages, the caller must register a progress event callback.
16435 See "GUESTFS_EVENT_PROGRESS".
16436 This function depends on the feature "libyara". See also
16438 "guestfs_feature_available".
16439 (Added in 1.37.13)
16441 guestfs_zegrep
16443 char **
16444 guestfs_zegrep (guestfs_h *g,
16445 const char *regex,
16446 const char *path);
16447 This function is deprecated. In new code, use the "guestfs_grep" call
16449 instead.
16450 Deprecated functions will not be removed from the API, but the fact
16452 that they are deprecated indicates that there are problems with correct
16453 use of these functions.
16454 This calls the external "zegrep" program and returns the matching
16456 lines.
16457 This function returns a NULL-terminated array of strings (like
16459 environ(3)), or NULL if there was an error. The caller must free the
16460 strings and the array after use.
16461 Because of the message protocol, there is a transfer limit of somewhere
16463 between 2MB and 4MB. See "PROTOCOL LIMITS".
16464 (Added in 1.0.66)
16466 guestfs_zegrepi
16468 char **
16469 guestfs_zegrepi (guestfs_h *g,
16470 const char *regex,
16471 const char *path);
16472 This function is deprecated. In new code, use the "guestfs_grep" call
16474 instead.
16475 Deprecated functions will not be removed from the API, but the fact
16477 that they are deprecated indicates that there are problems with correct
16478 use of these functions.
16479 This calls the external "zegrep -i" program and returns the matching
16481 lines.
16482 This function returns a NULL-terminated array of strings (like
16484 environ(3)), or NULL if there was an error. The caller must free the
16485 strings and the array after use.
16486 Because of the message protocol, there is a transfer limit of somewhere
16488 between 2MB and 4MB. See "PROTOCOL LIMITS".
16489 (Added in 1.0.66)
16491 guestfs_zero
16493 int
16494 guestfs_zero (guestfs_h *g,
16495 const char *device);
16496 This command writes zeroes over the first few blocks of "device".
16498 How many blocks are zeroed isn't specified (but it’s not enough to
16500 securely wipe the device). It should be sufficient to remove any
16501 partition tables, filesystem superblocks and so on.
16502 If blocks are already zero, then this command avoids writing zeroes.
16504 This prevents the underlying device from becoming non-sparse or growing
16505 unnecessarily.
16506 See also: "guestfs_zero_device", "guestfs_scrub_device",
16508 "guestfs_is_zero_device"
16509 This function returns 0 on success or -1 on error.
16511 This long-running command can generate progress notification messages
16513 so that the caller can display a progress bar or indicator. To receive
16514 these messages, the caller must register a progress event callback.
16515 See "GUESTFS_EVENT_PROGRESS".
16516 (Added in 1.0.16)
16518 guestfs_zero_device
16520 int
16521 guestfs_zero_device (guestfs_h *g,
16522 const char *device);
16523 This command writes zeroes over the entire "device". Compare with
16525 "guestfs_zero" which just zeroes the first few blocks of a device.
16526 If blocks are already zero, then this command avoids writing zeroes.
16528 This prevents the underlying device from becoming non-sparse or growing
16529 unnecessarily.
16530 This function returns 0 on success or -1 on error.
16532 This long-running command can generate progress notification messages
16534 so that the caller can display a progress bar or indicator. To receive
16535 these messages, the caller must register a progress event callback.
16536 See "GUESTFS_EVENT_PROGRESS".
16537 (Added in 1.3.1)
16539 guestfs_zero_free_space
16541 int
16542 guestfs_zero_free_space (guestfs_h *g,
16543 const char *directory);
16544 Zero the free space in the filesystem mounted on directory. The
16546 filesystem must be mounted read-write.
16547 The filesystem contents are not affected, but any free space in the
16549 filesystem is freed.
16550 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16552 either as an alternative to this, or after calling this, depending on
16553 your requirements.
16554 This function returns 0 on success or -1 on error.
16556 This long-running command can generate progress notification messages
16558 so that the caller can display a progress bar or indicator. To receive
16559 these messages, the caller must register a progress event callback.
16560 See "GUESTFS_EVENT_PROGRESS".
16561 (Added in 1.17.18)
16563 guestfs_zerofree
16565 int
16566 guestfs_zerofree (guestfs_h *g,
16567 const char *device);
16568 This runs the zerofree program on "device". This program claims to
16570 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16571 it possible to compress the filesystem more effectively.
16572 You should not run this program if the filesystem is mounted.
16574 It is possible that using this program can damage the filesystem or
16576 data on the filesystem.
16577 This function returns 0 on success or -1 on error.
16579 This function depends on the feature "zerofree". See also
16581 "guestfs_feature_available".
16582 (Added in 1.0.26)
16584 guestfs_zfgrep
16586 char **
16587 guestfs_zfgrep (guestfs_h *g,
16588 const char *pattern,
16589 const char *path);
16590 This function is deprecated. In new code, use the "guestfs_grep" call
16592 instead.
16593 Deprecated functions will not be removed from the API, but the fact
16595 that they are deprecated indicates that there are problems with correct
16596 use of these functions.
16597 This calls the external "zfgrep" program and returns the matching
16599 lines.
16600 This function returns a NULL-terminated array of strings (like
16602 environ(3)), or NULL if there was an error. The caller must free the
16603 strings and the array after use.
16604 Because of the message protocol, there is a transfer limit of somewhere
16606 between 2MB and 4MB. See "PROTOCOL LIMITS".
16607 (Added in 1.0.66)
16609 guestfs_zfgrepi
16611 char **
16612 guestfs_zfgrepi (guestfs_h *g,
16613 const char *pattern,
16614 const char *path);
16615 This function is deprecated. In new code, use the "guestfs_grep" call
16617 instead.
16618 Deprecated functions will not be removed from the API, but the fact
16620 that they are deprecated indicates that there are problems with correct
16621 use of these functions.
16622 This calls the external "zfgrep -i" program and returns the matching
16624 lines.
16625 This function returns a NULL-terminated array of strings (like
16627 environ(3)), or NULL if there was an error. The caller must free the
16628 strings and the array after use.
16629 Because of the message protocol, there is a transfer limit of somewhere
16631 between 2MB and 4MB. See "PROTOCOL LIMITS".
16632 (Added in 1.0.66)
16634 guestfs_zfile
16636 char *
16637 guestfs_zfile (guestfs_h *g,
16638 const char *meth,
16639 const char *path);
16640 This function is deprecated. In new code, use the "guestfs_file" call
16642 instead.
16643 Deprecated functions will not be removed from the API, but the fact
16645 that they are deprecated indicates that there are problems with correct
16646 use of these functions.
16647 This command runs file(1) after first decompressing "path" using
16649 "meth".
16650 "meth" must be one of "gzip", "compress" or "bzip2".
16652 Since 1.0.63, use "guestfs_file" instead which can now process
16654 compressed files.
16655 This function returns a string, or NULL on error. The caller must free
16657 the returned string after use.
16658 (Added in 1.0.59)
16660 guestfs_zgrep
16662 char **
16663 guestfs_zgrep (guestfs_h *g,
16664 const char *regex,
16665 const char *path);
16666 This function is deprecated. In new code, use the "guestfs_grep" call
16668 instead.
16669 Deprecated functions will not be removed from the API, but the fact
16671 that they are deprecated indicates that there are problems with correct
16672 use of these functions.
16673 This calls the external zgrep(1) program and returns the matching
16675 lines.
16676 This function returns a NULL-terminated array of strings (like
16678 environ(3)), or NULL if there was an error. The caller must free the
16679 strings and the array after use.
16680 Because of the message protocol, there is a transfer limit of somewhere
16682 between 2MB and 4MB. See "PROTOCOL LIMITS".
16683 (Added in 1.0.66)
16685 guestfs_zgrepi
16687 char **
16688 guestfs_zgrepi (guestfs_h *g,
16689 const char *regex,
16690 const char *path);
16691 This function is deprecated. In new code, use the "guestfs_grep" call
16693 instead.
16694 Deprecated functions will not be removed from the API, but the fact
16696 that they are deprecated indicates that there are problems with correct
16697 use of these functions.
16698 This calls the external "zgrep -i" program and returns the matching
16700 lines.
16701 This function returns a NULL-terminated array of strings (like
16703 environ(3)), or NULL if there was an error. The caller must free the
16704 strings and the array after use.
16705 Because of the message protocol, there is a transfer limit of somewhere
16707 between 2MB and 4MB. See "PROTOCOL LIMITS".
16708 (Added in 1.0.66)
16710
16712 guestfs_int_bool
16713 struct guestfs_int_bool {
16714 int32_t i;
16715 int32_t b;
16716 };
16717 struct guestfs_int_bool_list {
16719 uint32_t len; /* Number of elements in list. */
16720 struct guestfs_int_bool *val; /* Elements. */
16721 };
16722 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16724 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16725 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16727 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16728 void guestfs_free_int_bool (struct guestfs_int_bool *);
16730 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16731 guestfs_lvm_pv
16733 struct guestfs_lvm_pv {
16734 char *pv_name;
16735 /* The next field is NOT nul-terminated, be careful when printing it: */
16736 char pv_uuid[32];
16737 char *pv_fmt;
16738 uint64_t pv_size;
16739 uint64_t dev_size;
16740 uint64_t pv_free;
16741 uint64_t pv_used;
16742 char *pv_attr;
16743 int64_t pv_pe_count;
16744 int64_t pv_pe_alloc_count;
16745 char *pv_tags;
16746 uint64_t pe_start;
16747 int64_t pv_mda_count;
16748 uint64_t pv_mda_free;
16749 };
16750 struct guestfs_lvm_pv_list {
16752 uint32_t len; /* Number of elements in list. */
16753 struct guestfs_lvm_pv *val; /* Elements. */
16754 };
16755 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16757 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16758 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16760 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16761 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16763 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16764 guestfs_lvm_vg
16766 struct guestfs_lvm_vg {
16767 char *vg_name;
16768 /* The next field is NOT nul-terminated, be careful when printing it: */
16769 char vg_uuid[32];
16770 char *vg_fmt;
16771 char *vg_attr;
16772 uint64_t vg_size;
16773 uint64_t vg_free;
16774 char *vg_sysid;
16775 uint64_t vg_extent_size;
16776 int64_t vg_extent_count;
16777 int64_t vg_free_count;
16778 int64_t max_lv;
16779 int64_t max_pv;
16780 int64_t pv_count;
16781 int64_t lv_count;
16782 int64_t snap_count;
16783 int64_t vg_seqno;
16784 char *vg_tags;
16785 int64_t vg_mda_count;
16786 uint64_t vg_mda_free;
16787 };
16788 struct guestfs_lvm_vg_list {
16790 uint32_t len; /* Number of elements in list. */
16791 struct guestfs_lvm_vg *val; /* Elements. */
16792 };
16793 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16795 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16796 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16798 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16799 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16801 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16802 guestfs_lvm_lv
16804 struct guestfs_lvm_lv {
16805 char *lv_name;
16806 /* The next field is NOT nul-terminated, be careful when printing it: */
16807 char lv_uuid[32];
16808 char *lv_attr;
16809 int64_t lv_major;
16810 int64_t lv_minor;
16811 int64_t lv_kernel_major;
16812 int64_t lv_kernel_minor;
16813 uint64_t lv_size;
16814 int64_t seg_count;
16815 char *origin;
16816 /* The next field is [0..100] or -1 meaning 'not present': */
16817 float snap_percent;
16818 /* The next field is [0..100] or -1 meaning 'not present': */
16819 float copy_percent;
16820 char *move_pv;
16821 char *lv_tags;
16822 char *mirror_log;
16823 char *modules;
16824 };
16825 struct guestfs_lvm_lv_list {
16827 uint32_t len; /* Number of elements in list. */
16828 struct guestfs_lvm_lv *val; /* Elements. */
16829 };
16830 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16832 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16833 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16835 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16836 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16838 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16839 guestfs_stat
16841 struct guestfs_stat {
16842 int64_t dev;
16843 int64_t ino;
16844 int64_t mode;
16845 int64_t nlink;
16846 int64_t uid;
16847 int64_t gid;
16848 int64_t rdev;
16849 int64_t size;
16850 int64_t blksize;
16851 int64_t blocks;
16852 int64_t atime;
16853 int64_t mtime;
16854 int64_t ctime;
16855 };
16856 struct guestfs_stat_list {
16858 uint32_t len; /* Number of elements in list. */
16859 struct guestfs_stat *val; /* Elements. */
16860 };
16861 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16863 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16864 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16866 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16867 void guestfs_free_stat (struct guestfs_stat *);
16869 void guestfs_free_stat_list (struct guestfs_stat_list *);
16870 guestfs_statns
16872 struct guestfs_statns {
16873 int64_t st_dev;
16874 int64_t st_ino;
16875 int64_t st_mode;
16876 int64_t st_nlink;
16877 int64_t st_uid;
16878 int64_t st_gid;
16879 int64_t st_rdev;
16880 int64_t st_size;
16881 int64_t st_blksize;
16882 int64_t st_blocks;
16883 int64_t st_atime_sec;
16884 int64_t st_atime_nsec;
16885 int64_t st_mtime_sec;
16886 int64_t st_mtime_nsec;
16887 int64_t st_ctime_sec;
16888 int64_t st_ctime_nsec;
16889 int64_t st_spare1;
16890 int64_t st_spare2;
16891 int64_t st_spare3;
16892 int64_t st_spare4;
16893 int64_t st_spare5;
16894 int64_t st_spare6;
16895 };
16896 struct guestfs_statns_list {
16898 uint32_t len; /* Number of elements in list. */
16899 struct guestfs_statns *val; /* Elements. */
16900 };
16901 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16903 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16904 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16906 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16907 void guestfs_free_statns (struct guestfs_statns *);
16909 void guestfs_free_statns_list (struct guestfs_statns_list *);
16910 guestfs_statvfs
16912 struct guestfs_statvfs {
16913 int64_t bsize;
16914 int64_t frsize;
16915 int64_t blocks;
16916 int64_t bfree;
16917 int64_t bavail;
16918 int64_t files;
16919 int64_t ffree;
16920 int64_t favail;
16921 int64_t fsid;
16922 int64_t flag;
16923 int64_t namemax;
16924 };
16925 struct guestfs_statvfs_list {
16927 uint32_t len; /* Number of elements in list. */
16928 struct guestfs_statvfs *val; /* Elements. */
16929 };
16930 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16932 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16933 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16935 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16936 void guestfs_free_statvfs (struct guestfs_statvfs *);
16938 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16939 guestfs_dirent
16941 struct guestfs_dirent {
16942 int64_t ino;
16943 char ftyp;
16944 char *name;
16945 };
16946 struct guestfs_dirent_list {
16948 uint32_t len; /* Number of elements in list. */
16949 struct guestfs_dirent *val; /* Elements. */
16950 };
16951 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16953 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16954 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16956 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16957 void guestfs_free_dirent (struct guestfs_dirent *);
16959 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16960 guestfs_version
16962 struct guestfs_version {
16963 int64_t major;
16964 int64_t minor;
16965 int64_t release;
16966 char *extra;
16967 };
16968 struct guestfs_version_list {
16970 uint32_t len; /* Number of elements in list. */
16971 struct guestfs_version *val; /* Elements. */
16972 };
16973 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16975 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16976 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16978 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16979 void guestfs_free_version (struct guestfs_version *);
16981 void guestfs_free_version_list (struct guestfs_version_list *);
16982 guestfs_xattr
16984 struct guestfs_xattr {
16985 char *attrname;
16986 /* The next two fields describe a byte array. */
16987 uint32_t attrval_len;
16988 char *attrval;
16989 };
16990 struct guestfs_xattr_list {
16992 uint32_t len; /* Number of elements in list. */
16993 struct guestfs_xattr *val; /* Elements. */
16994 };
16995 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16997 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16998 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
17000 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
17001 void guestfs_free_xattr (struct guestfs_xattr *);
17003 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
17004 guestfs_inotify_event
17006 struct guestfs_inotify_event {
17007 int64_t in_wd;
17008 uint32_t in_mask;
17009 uint32_t in_cookie;
17010 char *in_name;
17011 };
17012 struct guestfs_inotify_event_list {
17014 uint32_t len; /* Number of elements in list. */
17015 struct guestfs_inotify_event *val; /* Elements. */
17016 };
17017 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
17019 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
17020 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
17022 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
17023 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
17025 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
17026 guestfs_partition
17028 struct guestfs_partition {
17029 int32_t part_num;
17030 uint64_t part_start;
17031 uint64_t part_end;
17032 uint64_t part_size;
17033 };
17034 struct guestfs_partition_list {
17036 uint32_t len; /* Number of elements in list. */
17037 struct guestfs_partition *val; /* Elements. */
17038 };
17039 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
17041 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
17042 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
17044 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
17045 void guestfs_free_partition (struct guestfs_partition *);
17047 void guestfs_free_partition_list (struct guestfs_partition_list *);
17048 guestfs_application
17050 struct guestfs_application {
17051 char *app_name;
17052 char *app_display_name;
17053 int32_t app_epoch;
17054 char *app_version;
17055 char *app_release;
17056 char *app_install_path;
17057 char *app_trans_path;
17058 char *app_publisher;
17059 char *app_url;
17060 char *app_source_package;
17061 char *app_summary;
17062 char *app_description;
17063 };
17064 struct guestfs_application_list {
17066 uint32_t len; /* Number of elements in list. */
17067 struct guestfs_application *val; /* Elements. */
17068 };
17069 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
17071 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
17072 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
17074 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
17075 void guestfs_free_application (struct guestfs_application *);
17077 void guestfs_free_application_list (struct guestfs_application_list *);
17078 guestfs_application2
17080 struct guestfs_application2 {
17081 char *app2_name;
17082 char *app2_display_name;
17083 int32_t app2_epoch;
17084 char *app2_version;
17085 char *app2_release;
17086 char *app2_arch;
17087 char *app2_install_path;
17088 char *app2_trans_path;
17089 char *app2_publisher;
17090 char *app2_url;
17091 char *app2_source_package;
17092 char *app2_summary;
17093 char *app2_description;
17094 char *app2_spare1;
17095 char *app2_spare2;
17096 char *app2_spare3;
17097 char *app2_spare4;
17098 };
17099 struct guestfs_application2_list {
17101 uint32_t len; /* Number of elements in list. */
17102 struct guestfs_application2 *val; /* Elements. */
17103 };
17104 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
17106 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
17107 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
17109 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
17110 void guestfs_free_application2 (struct guestfs_application2 *);
17112 void guestfs_free_application2_list (struct guestfs_application2_list *);
17113 guestfs_isoinfo
17115 struct guestfs_isoinfo {
17116 char *iso_system_id;
17117 char *iso_volume_id;
17118 uint32_t iso_volume_space_size;
17119 uint32_t iso_volume_set_size;
17120 uint32_t iso_volume_sequence_number;
17121 uint32_t iso_logical_block_size;
17122 char *iso_volume_set_id;
17123 char *iso_publisher_id;
17124 char *iso_data_preparer_id;
17125 char *iso_application_id;
17126 char *iso_copyright_file_id;
17127 char *iso_abstract_file_id;
17128 char *iso_bibliographic_file_id;
17129 int64_t iso_volume_creation_t;
17130 int64_t iso_volume_modification_t;
17131 int64_t iso_volume_expiration_t;
17132 int64_t iso_volume_effective_t;
17133 };
17134 struct guestfs_isoinfo_list {
17136 uint32_t len; /* Number of elements in list. */
17137 struct guestfs_isoinfo *val; /* Elements. */
17138 };
17139 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
17141 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
17142 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
17144 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
17145 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
17147 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
17148 guestfs_mdstat
17150 struct guestfs_mdstat {
17151 char *mdstat_device;
17152 int32_t mdstat_index;
17153 char *mdstat_flags;
17154 };
17155 struct guestfs_mdstat_list {
17157 uint32_t len; /* Number of elements in list. */
17158 struct guestfs_mdstat *val; /* Elements. */
17159 };
17160 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
17162 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
17163 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
17165 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
17166 void guestfs_free_mdstat (struct guestfs_mdstat *);
17168 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
17169 guestfs_btrfssubvolume
17171 struct guestfs_btrfssubvolume {
17172 uint64_t btrfssubvolume_id;
17173 uint64_t btrfssubvolume_top_level_id;
17174 char *btrfssubvolume_path;
17175 };
17176 struct guestfs_btrfssubvolume_list {
17178 uint32_t len; /* Number of elements in list. */
17179 struct guestfs_btrfssubvolume *val; /* Elements. */
17180 };
17181 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17183 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17184 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17186 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17187 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17189 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17190 guestfs_btrfsqgroup
17192 struct guestfs_btrfsqgroup {
17193 char *btrfsqgroup_id;
17194 uint64_t btrfsqgroup_rfer;
17195 uint64_t btrfsqgroup_excl;
17196 };
17197 struct guestfs_btrfsqgroup_list {
17199 uint32_t len; /* Number of elements in list. */
17200 struct guestfs_btrfsqgroup *val; /* Elements. */
17201 };
17202 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17204 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17205 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17207 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17208 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17210 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17211 guestfs_btrfsbalance
17213 struct guestfs_btrfsbalance {
17214 char *btrfsbalance_status;
17215 uint64_t btrfsbalance_total;
17216 uint64_t btrfsbalance_balanced;
17217 uint64_t btrfsbalance_considered;
17218 uint64_t btrfsbalance_left;
17219 };
17220 struct guestfs_btrfsbalance_list {
17222 uint32_t len; /* Number of elements in list. */
17223 struct guestfs_btrfsbalance *val; /* Elements. */
17224 };
17225 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17227 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17228 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17230 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17231 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17233 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17234 guestfs_btrfsscrub
17236 struct guestfs_btrfsscrub {
17237 uint64_t btrfsscrub_data_extents_scrubbed;
17238 uint64_t btrfsscrub_tree_extents_scrubbed;
17239 uint64_t btrfsscrub_data_bytes_scrubbed;
17240 uint64_t btrfsscrub_tree_bytes_scrubbed;
17241 uint64_t btrfsscrub_read_errors;
17242 uint64_t btrfsscrub_csum_errors;
17243 uint64_t btrfsscrub_verify_errors;
17244 uint64_t btrfsscrub_no_csum;
17245 uint64_t btrfsscrub_csum_discards;
17246 uint64_t btrfsscrub_super_errors;
17247 uint64_t btrfsscrub_malloc_errors;
17248 uint64_t btrfsscrub_uncorrectable_errors;
17249 uint64_t btrfsscrub_unverified_errors;
17250 uint64_t btrfsscrub_corrected_errors;
17251 uint64_t btrfsscrub_last_physical;
17252 };
17253 struct guestfs_btrfsscrub_list {
17255 uint32_t len; /* Number of elements in list. */
17256 struct guestfs_btrfsscrub *val; /* Elements. */
17257 };
17258 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17260 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17261 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17263 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17264 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17266 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17267 guestfs_xfsinfo
17269 struct guestfs_xfsinfo {
17270 char *xfs_mntpoint;
17271 uint32_t xfs_inodesize;
17272 uint32_t xfs_agcount;
17273 uint32_t xfs_agsize;
17274 uint32_t xfs_sectsize;
17275 uint32_t xfs_attr;
17276 uint32_t xfs_blocksize;
17277 uint64_t xfs_datablocks;
17278 uint32_t xfs_imaxpct;
17279 uint32_t xfs_sunit;
17280 uint32_t xfs_swidth;
17281 uint32_t xfs_dirversion;
17282 uint32_t xfs_dirblocksize;
17283 uint32_t xfs_cimode;
17284 char *xfs_logname;
17285 uint32_t xfs_logblocksize;
17286 uint32_t xfs_logblocks;
17287 uint32_t xfs_logversion;
17288 uint32_t xfs_logsectsize;
17289 uint32_t xfs_logsunit;
17290 uint32_t xfs_lazycount;
17291 char *xfs_rtname;
17292 uint32_t xfs_rtextsize;
17293 uint64_t xfs_rtblocks;
17294 uint64_t xfs_rtextents;
17295 };
17296 struct guestfs_xfsinfo_list {
17298 uint32_t len; /* Number of elements in list. */
17299 struct guestfs_xfsinfo *val; /* Elements. */
17300 };
17301 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17303 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17304 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17306 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17307 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17309 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17310 guestfs_utsname
17312 struct guestfs_utsname {
17313 char *uts_sysname;
17314 char *uts_release;
17315 char *uts_version;
17316 char *uts_machine;
17317 };
17318 struct guestfs_utsname_list {
17320 uint32_t len; /* Number of elements in list. */
17321 struct guestfs_utsname *val; /* Elements. */
17322 };
17323 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17325 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17326 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17328 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17329 void guestfs_free_utsname (struct guestfs_utsname *);
17331 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17332 guestfs_hivex_node
17334 struct guestfs_hivex_node {
17335 int64_t hivex_node_h;
17336 };
17337 struct guestfs_hivex_node_list {
17339 uint32_t len; /* Number of elements in list. */
17340 struct guestfs_hivex_node *val; /* Elements. */
17341 };
17342 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17344 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17345 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17347 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17348 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17350 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17351 guestfs_hivex_value
17353 struct guestfs_hivex_value {
17354 int64_t hivex_value_h;
17355 };
17356 struct guestfs_hivex_value_list {
17358 uint32_t len; /* Number of elements in list. */
17359 struct guestfs_hivex_value *val; /* Elements. */
17360 };
17361 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17363 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17364 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17366 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17367 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17369 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17370 guestfs_internal_mountable
17372 struct guestfs_internal_mountable {
17373 int32_t im_type;
17374 char *im_device;
17375 char *im_volume;
17376 };
17377 struct guestfs_internal_mountable_list {
17379 uint32_t len; /* Number of elements in list. */
17380 struct guestfs_internal_mountable *val; /* Elements. */
17381 };
17382 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17384 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17385 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17387 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17388 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17390 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17391 guestfs_tsk_dirent
17393 struct guestfs_tsk_dirent {
17394 uint64_t tsk_inode;
17395 char tsk_type;
17396 int64_t tsk_size;
17397 char *tsk_name;
17398 uint32_t tsk_flags;
17399 int64_t tsk_atime_sec;
17400 int64_t tsk_atime_nsec;
17401 int64_t tsk_mtime_sec;
17402 int64_t tsk_mtime_nsec;
17403 int64_t tsk_ctime_sec;
17404 int64_t tsk_ctime_nsec;
17405 int64_t tsk_crtime_sec;
17406 int64_t tsk_crtime_nsec;
17407 int64_t tsk_nlink;
17408 char *tsk_link;
17409 int64_t tsk_spare1;
17410 };
17411 struct guestfs_tsk_dirent_list {
17413 uint32_t len; /* Number of elements in list. */
17414 struct guestfs_tsk_dirent *val; /* Elements. */
17415 };
17416 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17418 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17419 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17421 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17422 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17424 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17425 guestfs_yara_detection
17427 struct guestfs_yara_detection {
17428 char *yara_name;
17429 char *yara_rule;
17430 };
17431 struct guestfs_yara_detection_list {
17433 uint32_t len; /* Number of elements in list. */
17434 struct guestfs_yara_detection *val; /* Elements. */
17435 };
17436 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17438 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17439 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17441 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17442 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17444 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17445
17447 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17448 Using "guestfs_available" you can test availability of the following
17449 groups of functions. This test queries the appliance to see if the
17450 appliance you are currently using supports the functionality.
17451 acl The following functions: "guestfs_acl_delete_def_file"
17453 "guestfs_acl_get_file" "guestfs_acl_set_file"
17454 blkdiscard
17456 The following functions: "guestfs_blkdiscard"
17457 blkdiscardzeroes
17459 The following functions: "guestfs_blkdiscardzeroes"
17460 btrfs
17462 The following functions: "guestfs_btrfs_balance_cancel"
17463 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17464 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17465 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17466 "guestfs_btrfs_filesystem_defragment"
17467 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17468 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17469 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17470 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17471 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17472 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17473 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17474 "guestfs_btrfs_rescue_chunk_recover"
17475 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17476 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17477 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17478 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17479 "guestfs_btrfs_subvolume_get_default"
17480 "guestfs_btrfs_subvolume_list"
17481 "guestfs_btrfs_subvolume_set_default"
17482 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17483 "guestfs_btrfstune_enable_extended_inode_refs"
17484 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17485 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17486 extlinux
17488 The following functions: "guestfs_extlinux"
17489 f2fs
17491 The following functions: "guestfs_f2fs_expand"
17492 fstrim
17494 The following functions: "guestfs_fstrim"
17495 gdisk
17497 The following functions: "guestfs_part_expand_gpt"
17498 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17499 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17500 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17501 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17502 "guestfs_part_set_gpt_type"
17503 grub
17505 The following functions: "guestfs_grub_install"
17506 hivex
17508 The following functions: "guestfs_hivex_close"
17509 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17510 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17511 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17512 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17513 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17514 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17515 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17516 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17517 inotify
17519 The following functions: "guestfs_inotify_add_watch"
17520 "guestfs_inotify_close" "guestfs_inotify_files"
17521 "guestfs_inotify_init" "guestfs_inotify_read"
17522 "guestfs_inotify_rm_watch"
17523 journal
17525 The following functions: "guestfs_internal_journal_get"
17526 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17527 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17528 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17529 "guestfs_journal_skip"
17530 ldm The following functions: "guestfs_ldmtool_create_all"
17532 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17533 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17534 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17535 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17536 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17537 "guestfs_list_ldm_volumes"
17538 libtsk
17540 The following functions: "guestfs_internal_filesystem_walk"
17541 "guestfs_internal_find_inode"
17542 libyara
17544 The following functions: "guestfs_internal_yara_scan"
17545 "guestfs_yara_destroy" "guestfs_yara_load"
17546 linuxcaps
17548 The following functions: "guestfs_cap_get_file"
17549 "guestfs_cap_set_file"
17550 linuxfsuuid
17552 The following functions: "guestfs_mke2fs_JU"
17553 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17554 "guestfs_swapon_uuid"
17555 linuxmodules
17557 The following functions: "guestfs_modprobe"
17558 linuxxattrs
17560 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17561 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17562 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17563 "guestfs_removexattr" "guestfs_setxattr"
17564 luks
17566 The following functions: "guestfs_cryptsetup_close"
17567 "guestfs_cryptsetup_open" "guestfs_luks_add_key"
17568 "guestfs_luks_close" "guestfs_luks_format"
17569 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17570 "guestfs_luks_open" "guestfs_luks_open_ro" "guestfs_luks_uuid"
17571 lvm2
17573 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17574 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17575 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17576 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17577 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17578 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17579 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17580 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17581 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17582 "guestfs_vgs" "guestfs_vgs_full"
17583 mdadm
17585 The following functions: "guestfs_md_create" "guestfs_md_detail"
17586 "guestfs_md_stat" "guestfs_md_stop"
17587 mknod
17589 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17590 "guestfs_mknod_b" "guestfs_mknod_c"
17591 ntfs3g
17593 The following functions: "guestfs_ntfs_3g_probe"
17594 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17595 ntfsprogs
17597 The following functions: "guestfs_ntfsresize"
17598 "guestfs_ntfsresize_size"
17599 rsync
17601 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17602 "guestfs_rsync_out"
17603 scrub
17605 The following functions: "guestfs_scrub_device"
17606 "guestfs_scrub_file" "guestfs_scrub_freespace"
17607 selinux
17609 The following functions: "guestfs_getcon" "guestfs_setcon"
17610 selinuxrelabel
17612 The following functions: "guestfs_selinux_relabel"
17613 sleuthkit
17615 The following functions: "guestfs_download_blocks"
17616 "guestfs_download_inode"
17617 squashfs
17619 The following functions: "guestfs_mksquashfs"
17620 syslinux
17622 The following functions: "guestfs_syslinux"
17623 wipefs
17625 The following functions: "guestfs_wipefs"
17626 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17628 "guestfs_xfs_info" "guestfs_xfs_repair"
17629 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17631 zerofree
17633 The following functions: "guestfs_zerofree"
17634 FILESYSTEM AVAILABLE
17636 The "guestfs_filesystem_available" call tests whether a filesystem type
17637 is supported by the appliance kernel.
17638 This is mainly useful as a negative test. If this returns true, it
17640 doesn't mean that a particular filesystem can be mounted, since
17641 filesystems can fail for other reasons such as it being a later version
17642 of the filesystem, or having incompatible features.
17643 GUESTFISH supported COMMAND
17645 In guestfish(3) there is a handy interactive command "supported" which
17646 prints out the available groups and whether they are supported by this
17647 build of libguestfs. Note however that you have to do "run" first.
17648 SINGLE CALLS AT COMPILE TIME
17650 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17651 function, such as:
17652 #define GUESTFS_HAVE_DD 1
17654 if "guestfs_dd" is available.
17656 Before version 1.5.8, if you needed to test whether a single libguestfs
17658 function is available at compile time, we recommended using build tools
17659 such as autoconf or cmake. For example in autotools you could use:
17660 AC_CHECK_LIB([guestfs],[guestfs_create])
17662 AC_CHECK_FUNCS([guestfs_dd])
17663 which would result in "HAVE_GUESTFS_DD" being either defined or not
17665 defined in your program.
17666 SINGLE CALLS AT RUN TIME
17668 Testing at compile time doesn't guarantee that a function really exists
17669 in the library. The reason is that you might be dynamically linked
17670 against a previous libguestfs.so (dynamic library) which doesn't have
17671 the call. This situation unfortunately results in a segmentation
17672 fault, which is a shortcoming of the C dynamic linking system itself.
17673 You can use dlopen(3) to test if a function is available at run time,
17675 as in this example program (note that you still need the compile time
17676 check as well):
17677 #include <stdio.h>
17679 #include <stdlib.h>
17680 #include <unistd.h>
17681 #include <dlfcn.h>
17682 #include <guestfs.h>
17683 main ()
17685 {
17686 #ifdef GUESTFS_HAVE_DD
17687 void *dl;
17688 int has_function;
17689 /* Test if the function guestfs_dd is really available. */
17691 dl = dlopen (NULL, RTLD_LAZY);
17692 if (!dl) {
17693 fprintf (stderr, "dlopen: %s\n", dlerror ());
17694 exit (EXIT_FAILURE);
17695 }
17696 has_function = dlsym (dl, "guestfs_dd") != NULL;
17697 dlclose (dl);
17698 if (!has_function)
17700 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17701 else {
17702 printf ("this libguestfs.so has guestfs_dd function\n");
17703 /* Now it's safe to call
17704 guestfs_dd (g, "foo", "bar");
17705 */
17706 }
17707 #else
17708 printf ("guestfs_dd function was not found at compile time\n");
17709 #endif
17710 }
17711 You may think the above is an awful lot of hassle, and it is. There
17713 are other ways outside of the C linking system to ensure that this kind
17714 of incompatibility never arises, such as using package versioning:
17715 Requires: libguestfs >= 1.0.80
17717
17719 A recent feature of the API is the introduction of calls which take
17720 optional arguments. In C these are declared 3 ways. The main way is
17721 as a call which takes variable arguments (ie. "..."), as in this
17722 example:
17723 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17725 Call this with a list of optional arguments, terminated by "-1". So to
17727 call with no optional arguments specified:
17728 guestfs_add_drive_opts (g, filename, -1);
17730 With a single optional argument:
17732 guestfs_add_drive_opts (g, filename,
17734 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17735 -1);
17736 With two:
17738 guestfs_add_drive_opts (g, filename,
17740 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17741 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17742 -1);
17743 and so forth. Don’t forget the terminating "-1" otherwise Bad Things
17745 will happen!
17746 USING va_list FOR OPTIONAL ARGUMENTS
17748 The second variant has the same name with the suffix "_va", which works
17749 the same way but takes a "va_list". See the C manual for details. For
17750 the example function, this is declared:
17751 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17753 va_list args);
17754 CONSTRUCTING OPTIONAL ARGUMENTS
17756 The third variant is useful where you need to construct these calls.
17757 You pass in a structure where you fill in the optional fields. The
17758 structure has a bitmask as the first element which you must set to
17759 indicate which fields you have filled in. For our example function the
17760 structure and call are declared:
17761 struct guestfs_add_drive_opts_argv {
17763 uint64_t bitmask;
17764 int readonly;
17765 const char *format;
17766 /* ... */
17767 };
17768 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17769 const struct guestfs_add_drive_opts_argv *optargs);
17770 You could call it like this:
17772 struct guestfs_add_drive_opts_argv optargs = {
17774 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17775 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17776 .readonly = 1,
17777 .format = "qcow2"
17778 };
17779 guestfs_add_drive_opts_argv (g, filename, &optargs);
17781 Notes:
17783 · The "_BITMASK" suffix on each option name when specifying the
17785 bitmask.
17786 · You do not need to fill in all fields of the structure.
17788 · There must be a one-to-one correspondence between fields of the
17790 structure that are filled in, and bits set in the bitmask.
17791 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17793 In other languages, optional arguments are expressed in the way that is
17794 natural for that language. We refer you to the language-specific
17795 documentation for more details on that.
17796 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17798
17800 SETTING CALLBACKS TO HANDLE EVENTS
17801 Note: This section documents the generic event mechanism introduced in
17802 libguestfs 1.10, which you should use in new code if possible. The old
17803 functions "guestfs_set_log_message_callback",
17804 "guestfs_set_subprocess_quit_callback",
17805 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17806 "guestfs_set_progress_callback" are no longer documented in this manual
17807 page. Because of the ABI guarantee, the old functions continue to
17808 work.
17809 Handles generate events when certain things happen, such as log
17811 messages being generated, progress messages during long-running
17812 operations, or the handle being closed. The API calls described below
17813 let you register a callback to be called when events happen. You can
17814 register multiple callbacks (for the same, different or overlapping
17815 sets of events), and individually remove callbacks. If callbacks are
17816 not removed, then they remain in force until the handle is closed.
17817 In the current implementation, events are only generated synchronously:
17819 that means that events (and hence callbacks) can only happen while you
17820 are in the middle of making another libguestfs call. The callback is
17821 called in the same thread.
17822 Events may contain a payload, usually nothing (void), an array of 64
17824 bit unsigned integers, or a message buffer. Payloads are discussed
17825 later on.
17826 CLASSES OF EVENTS
17828 GUESTFS_EVENT_CLOSE (payload type: void)
17829 The callback function will be called while the handle is being
17830 closed (synchronously from "guestfs_close").
17831 Note that libguestfs installs an atexit(3) handler to try to clean
17833 up handles that are open when the program exits. This means that
17834 this callback might be called indirectly from exit(3), which can
17835 cause unexpected problems in higher-level languages (eg. if your
17836 HLL interpreter has already been cleaned up by the time this is
17837 called, and if your callback then jumps into some HLL function).
17838 If no callback is registered: the handle is closed without any
17840 callback being invoked.
17841 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17843 The callback function will be called when the child process quits,
17844 either asynchronously or if killed by "guestfs_kill_subprocess".
17845 (This corresponds to a transition from any state to the CONFIG
17846 state).
17847 If no callback is registered: the event is ignored.
17849 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17851 The callback function will be called when the child process becomes
17852 ready first time after it has been launched. (This corresponds to
17853 a transition from LAUNCHING to the READY state).
17854 If no callback is registered: the event is ignored.
17856 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17858 Some long-running operations can generate progress messages. If
17859 this callback is registered, then it will be called each time a
17860 progress message is generated (usually two seconds after the
17861 operation started, and three times per second thereafter until it
17862 completes, although the frequency may change in future versions).
17863 The callback receives in the payload four unsigned 64 bit numbers
17865 which are (in order): "proc_nr", "serial", "position", "total".
17866 The units of "total" are not defined, although for some operations
17868 "total" may relate in some way to the amount of data to be
17869 transferred (eg. in bytes or megabytes), and "position" may be the
17870 portion which has been transferred.
17871 The only defined and stable parts of the API are:
17873 · The callback can display to the user some type of progress bar
17875 or indicator which shows the ratio of "position":"total".
17876 · 0 <= "position" <= "total"
17878 · If any progress notification is sent during a call, then a
17880 final progress notification is always sent when "position" =
17881 "total" (unless the call fails with an error).
17882 This is to simplify caller code, so callers can easily set the
17884 progress indicator to "100%" at the end of the operation,
17885 without requiring special code to detect this case.
17886 · For some calls we are unable to estimate the progress of the
17888 call, but we can still generate progress messages to indicate
17889 activity. This is known as "pulse mode", and is directly
17890 supported by certain progress bar implementations (eg.
17891 GtkProgressBar).
17892 For these calls, zero or more progress messages are generated
17894 with "position = 0" and "total = 1", followed by a final
17895 message with "position = total = 1".
17896 As noted above, if the call fails with an error then the final
17898 message may not be generated.
17899 The callback also receives the procedure number ("proc_nr") and
17901 serial number ("serial") of the call. These are only useful for
17902 debugging protocol issues, and the callback can normally ignore
17903 them. The callback may want to print these numbers in error
17904 messages or debugging messages.
17905 If no callback is registered: progress messages are discarded.
17907 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17909 The callback function is called whenever a log message is generated
17910 by qemu, the appliance kernel, guestfsd (daemon), or utility
17911 programs.
17912 If the verbose flag ("guestfs_set_verbose") is set before launch
17914 ("guestfs_launch") then additional debug messages are generated.
17915 If no callback is registered: the messages are discarded unless the
17917 verbose flag is set in which case they are sent to stderr. You can
17918 override the printing of verbose messages to stderr by setting up a
17919 callback.
17920 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17922 The callback function is called whenever a log message is generated
17923 by the library part of libguestfs.
17924 If the verbose flag ("guestfs_set_verbose") is set then additional
17926 debug messages are generated.
17927 If no callback is registered: the messages are discarded unless the
17929 verbose flag is set in which case they are sent to stderr. You can
17930 override the printing of verbose messages to stderr by setting up a
17931 callback.
17932 GUESTFS_EVENT_WARNING (payload type: message buffer)
17934 The callback function is called whenever a warning message is
17935 generated by the library part of libguestfs.
17936 If no callback is registered: the messages are printed to stderr.
17938 You can override the printing of warning messages to stderr by
17939 setting up a callback.
17940 GUESTFS_EVENT_TRACE (payload type: message buffer)
17942 The callback function is called whenever a trace message is
17943 generated. This only applies if the trace flag
17944 ("guestfs_set_trace") is set.
17945 If no callback is registered: the messages are sent to stderr. You
17947 can override the printing of trace messages to stderr by setting up
17948 a callback.
17949 GUESTFS_EVENT_ENTER (payload type: function name)
17951 The callback function is called whenever a libguestfs function is
17952 entered.
17953 The payload is a string which contains the name of the function
17955 that we are entering (not including "guestfs_" prefix).
17956 Note that libguestfs functions can call themselves, so you may see
17958 many events from a single call. A few libguestfs functions do not
17959 generate this event.
17960 If no callback is registered: the event is ignored.
17962 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17964 For any API function that opens a libvirt connection, this event
17965 may be generated to indicate that libvirt demands authentication
17966 information. See "LIBVIRT AUTHENTICATION" below.
17967 If no callback is registered: "virConnectAuthPtrDefault" is used
17969 (suitable for command-line programs only).
17970 EVENT API
17972 guestfs_set_event_callback
17973 int guestfs_set_event_callback (guestfs_h *g,
17975 guestfs_event_callback cb,
17976 uint64_t event_bitmask,
17977 int flags,
17978 void *opaque);
17979 This function registers a callback ("cb") for all event classes in the
17981 "event_bitmask".
17982 For example, to register for all log message events, you could call
17984 this function with the bitmask
17985 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17986 To register a single callback for all possible classes of events, use
17987 "GUESTFS_EVENT_ALL".
17988 "flags" should always be passed as 0.
17990 "opaque" is an opaque pointer which is passed to the callback. You can
17992 use it for any purpose.
17993 The return value is the event handle (an integer) which you can use to
17995 delete the callback (see below).
17996 If there is an error, this function returns "-1", and sets the error in
17998 the handle in the usual way (see "guestfs_last_error" etc.)
17999 Callbacks remain in effect until they are deleted, or until the handle
18001 is closed.
18002 In the case where multiple callbacks are registered for a particular
18004 event class, all of the callbacks are called. The order in which
18005 multiple callbacks are called is not defined.
18006 guestfs_delete_event_callback
18008 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
18010 Delete a callback that was previously registered. "event_handle"
18012 should be the integer that was returned by a previous call to
18013 "guestfs_set_event_callback" on the same handle.
18014 guestfs_event_to_string
18016 char *guestfs_event_to_string (uint64_t event);
18018 "event" is either a single event or a bitmask of events. This returns
18020 a string representation (useful for debugging or printing events).
18021 A single event is returned as the name in lower case, eg. "close".
18023 A bitmask of several events is returned as a comma-separated list, eg.
18025 "close,progress".
18026 If zero is passed, then the empty string "" is returned.
18028 On success this returns a string. On error it returns NULL and sets
18030 "errno".
18031 The returned string must be freed by the caller.
18033 guestfs_event_callback
18035 typedef void (*guestfs_event_callback) (
18037 guestfs_h *g,
18038 void *opaque,
18039 uint64_t event,
18040 int event_handle,
18041 int flags,
18042 const char *buf, size_t buf_len,
18043 const uint64_t *array, size_t array_len);
18044 This is the type of the event callback function that you have to
18046 provide.
18047 The basic parameters are: the handle ("g"), the opaque user pointer
18049 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
18050 handle, and "flags" which in the current API you should ignore.
18051 The remaining parameters contain the event payload (if any). Each
18053 event may contain a payload, which usually relates to the event class,
18054 but for future proofing your code should be written to handle any
18055 payload for any event class.
18056 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
18058 there is no message buffer). Note that this message buffer can contain
18059 arbitrary 8 bit data, including NUL bytes.
18060 "array" and "array_len" is an array of 64 bit unsigned integers. At
18062 the moment this is only used for progress messages.
18063 EXAMPLE: CAPTURING LOG MESSAGES
18065 A working program demonstrating this can be found in
18066 examples/debug-logging.c in the source of libguestfs.
18067 One motivation for the generic event API was to allow GUI programs to
18069 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
18070 unconditionally to "stderr".
18071 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
18073 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
18074 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
18075 must capture error messages separately).
18076 Programs have to set up a callback to capture the classes of events of
18078 interest:
18079 int eh =
18081 guestfs_set_event_callback
18082 (g, message_callback,
18083 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
18084 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
18085 0, NULL) == -1)
18086 if (eh == -1) {
18087 // handle error in the usual way
18088 }
18089 The callback can then direct messages to the appropriate place. In
18091 this example, messages are directed to syslog:
18092 static void
18094 message_callback (
18095 guestfs_h *g,
18096 void *opaque,
18097 uint64_t event,
18098 int event_handle,
18099 int flags,
18100 const char *buf, size_t buf_len,
18101 const uint64_t *array, size_t array_len)
18102 {
18103 const int priority = LOG_USER|LOG_INFO;
18104 if (buf_len > 0)
18105 syslog (priority, "event 0x%lx: %s", event, buf);
18106 }
18107 LIBVIRT AUTHENTICATION
18109 Some libguestfs API calls can open libvirt connections. Currently the
18110 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
18111 backend has been selected. Libvirt connections may require
18112 authentication, for example if they need to access a remote server or
18113 to access root services from non-root. Libvirt authentication happens
18114 via a callback mechanism, see
18115 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
18116 You may provide libvirt authentication data by registering a callback
18118 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
18119 If no such event is registered, then libguestfs uses a libvirt function
18121 that provides command-line prompts ("virConnectAuthPtrDefault"). This
18122 is only suitable for command-line libguestfs programs.
18123 To provide authentication, first call
18125 "guestfs_set_libvirt_supported_credentials" with the list of
18126 credentials your program knows how to provide. Second, register a
18127 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
18128 will be called when libvirt is requesting authentication information.
18129 In the event handler, call "guestfs_get_libvirt_requested_credentials"
18131 to get a list of the credentials that libvirt is asking for. You then
18132 need to ask (eg. the user) for each credential, and call
18133 "guestfs_set_libvirt_requested_credential" with the answer. Note that
18134 for each credential, additional information may be available via the
18135 calls "guestfs_get_libvirt_requested_credential_prompt",
18136 "guestfs_get_libvirt_requested_credential_challenge" or
18137 "guestfs_get_libvirt_requested_credential_defresult".
18138 The example program below should make this clearer.
18140 There is also a more substantial working example program supplied with
18142 the libguestfs sources, called libvirt-auth.c.
18143 main ()
18145 {
18146 guestfs_h *g;
18147 char *creds[] = { "authname", "passphrase", NULL };
18148 int r, eh;
18149 g = guestfs_create ();
18151 if (!g) exit (EXIT_FAILURE);
18152 /* Tell libvirt what credentials the program supports. */
18154 r = guestfs_set_libvirt_supported_credentials (g, creds);
18155 if (r == -1)
18156 exit (EXIT_FAILURE);
18157 /* Set up the event handler. */
18159 eh = guestfs_set_event_callback (
18160 g, do_auth,
18161 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
18162 if (eh == -1)
18163 exit (EXIT_FAILURE);
18164 /* An example of a call that may ask for credentials. */
18166 r = guestfs_add_domain (
18167 g, "dom",
18168 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
18169 -1);
18170 if (r == -1)
18171 exit (EXIT_FAILURE);
18172 exit (EXIT_SUCCESS);
18174 }
18175 static void
18177 do_auth (guestfs_h *g,
18178 void *opaque,
18179 uint64_t event,
18180 int event_handle,
18181 int flags,
18182 const char *buf, size_t buf_len,
18183 const uint64_t *array, size_t array_len)
18184 {
18185 char **creds;
18186 size_t i;
18187 char *prompt;
18188 char *reply;
18189 size_t replylen;
18190 int r;
18191 // buf will be the libvirt URI. buf_len may be ignored.
18193 printf ("Authentication required for libvirt conn '%s'\n",
18194 buf);
18195 // Ask libguestfs what credentials libvirt is demanding.
18197 creds = guestfs_get_libvirt_requested_credentials (g);
18198 if (creds == NULL)
18199 exit (EXIT_FAILURE);
18200 // Now ask the user for answers.
18202 for (i = 0; creds[i] != NULL; ++i)
18203 {
18204 if (strcmp (creds[i], "authname") == 0 ||
18205 strcmp (creds[i], "passphrase") == 0)
18206 {
18207 prompt =
18208 guestfs_get_libvirt_requested_credential_prompt (g, i);
18209 if (prompt && strcmp (prompt, "") != 0)
18210 printf ("%s: ", prompt);
18211 free (prompt);
18212 // Some code here to ask for the credential.
18214 // ...
18215 // Put the reply in 'reply', length 'replylen' (bytes).
18216 r = guestfs_set_libvirt_requested_credential (g, i,
18218 reply, replylen);
18219 if (r == -1)
18220 exit (EXIT_FAILURE);
18221 }
18222 free (creds[i]);
18224 }
18225 free (creds);
18227 }
18228
18230 Some operations can be cancelled by the caller while they are in
18231 progress. Currently only operations that involve uploading or
18232 downloading data can be cancelled (technically: operations that have
18233 "FileIn" or "FileOut" parameters in the generator).
18234 To cancel the transfer, call "guestfs_user_cancel". For more
18236 information, read the description of "guestfs_user_cancel".
18237
18239 You can attach named pieces of private data to the libguestfs handle,
18240 fetch them by name, and walk over them, for the lifetime of the handle.
18241 This is called the private data area and is only available from the C
18242 API.
18243 To attach a named piece of data, use the following call:
18245 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18247 "key" is the name to associate with this data, and "data" is an
18249 arbitrary pointer (which can be "NULL"). Any previous item with the
18250 same key is overwritten.
18251 You can use any "key" string you want, but avoid keys beginning with an
18253 underscore character (libguestfs uses those for its own internal
18254 purposes, such as implementing language bindings). It is recommended
18255 that you prefix the key with some unique string to avoid collisions
18256 with other users.
18257 To retrieve the pointer, use:
18259 void *guestfs_get_private (guestfs_h *g, const char *key);
18261 This function returns "NULL" if either no data is found associated with
18263 "key", or if the user previously set the "key"’s "data" pointer to
18264 "NULL".
18265 Libguestfs does not try to look at or interpret the "data" pointer in
18267 any way. As far as libguestfs is concerned, it need not be a valid
18268 pointer at all. In particular, libguestfs does not try to free the
18269 data when the handle is closed. If the data must be freed, then the
18270 caller must either free it before calling "guestfs_close" or must set
18271 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18272 To walk over all entries, use these two functions:
18274 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18276 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18278 "guestfs_first_private" returns the first key, pointer pair ("first"
18280 does not have any particular meaning -- keys are not returned in any
18281 defined order). A pointer to the key is returned in *key_rtn and the
18282 corresponding data pointer is returned from the function. "NULL" is
18283 returned if there are no keys stored in the handle.
18284 "guestfs_next_private" returns the next key, pointer pair. The return
18286 value of this function is "NULL" if there are no further entries to
18287 return.
18288 Notes about walking over entries:
18290 · You must not call "guestfs_set_private" while walking over the
18292 entries.
18293 · The handle maintains an internal iterator which is reset when you
18295 call "guestfs_first_private". This internal iterator is
18296 invalidated when you call "guestfs_set_private".
18297 · If you have set the data pointer associated with a key to "NULL",
18299 ie:
18300 guestfs_set_private (g, key, NULL);
18302 then that "key" is not returned when walking.
18304 · *key_rtn is only valid until the next call to
18306 "guestfs_first_private", "guestfs_next_private" or
18307 "guestfs_set_private".
18308 The following example code shows how to print all keys and data
18310 pointers that are associated with the handle "g":
18311 const char *key;
18313 void *data = guestfs_first_private (g, &key);
18314 while (data != NULL)
18315 {
18316 printf ("key = %s, data = %p\n", key, data);
18317 data = guestfs_next_private (g, &key);
18318 }
18319 More commonly you are only interested in keys that begin with an
18321 application-specific prefix "foo_". Modify the loop like so:
18322 const char *key;
18324 void *data = guestfs_first_private (g, &key);
18325 while (data != NULL)
18326 {
18327 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18328 printf ("key = %s, data = %p\n", key, data);
18329 data = guestfs_next_private (g, &key);
18330 }
18331 If you need to modify keys while walking, then you have to jump back to
18333 the beginning of the loop. For example, to delete all keys prefixed
18334 with "foo_":
18335 const char *key;
18337 void *data;
18338 again:
18339 data = guestfs_first_private (g, &key);
18340 while (data != NULL)
18341 {
18342 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18343 {
18344 guestfs_set_private (g, key, NULL);
18345 /* note that 'key' pointer is now invalid, and so is
18346 the internal iterator */
18347 goto again;
18348 }
18349 data = guestfs_next_private (g, &key);
18350 }
18351 Note that the above loop is guaranteed to terminate because the keys
18353 are being deleted, but other manipulations of keys within the loop
18354 might not terminate unless you also maintain an indication of which
18355 keys have been visited.
18356
18358 The libguestfs C library can be probed using systemtap or DTrace. This
18359 is true of any library, not just libguestfs. However libguestfs also
18360 contains static markers to help in probing internal operations.
18361 You can list all the static markers by doing:
18363 stap -l 'process("/usr/lib*/libguestfs.so.0")
18365 .provider("guestfs").mark("*")'
18366 Note: These static markers are not part of the stable API and may
18368 change in future versions.
18369 SYSTEMTAP SCRIPT EXAMPLE
18371 This script contains examples of displaying both the static markers and
18372 some ordinary C entry points:
18373 global last;
18375 function display_time () {
18377 now = gettimeofday_us ();
18378 delta = 0;
18379 if (last > 0)
18380 delta = now - last;
18381 last = now;
18382 printf ("%d (+%d):", now, delta);
18384 }
18385 probe begin {
18387 last = 0;
18388 printf ("ready\n");
18389 }
18390 /* Display all calls to static markers. */
18392 probe process("/usr/lib*/libguestfs.so.0")
18393 .provider("guestfs").mark("*") ? {
18394 display_time();
18395 printf ("\t%s %s\n", $$name, $$parms);
18396 }
18397 /* Display all calls to guestfs_mkfs* functions. */
18399 probe process("/usr/lib*/libguestfs.so.0")
18400 .function("guestfs_mkfs*") ? {
18401 display_time();
18402 printf ("\t%s %s\n", probefunc(), $$parms);
18403 }
18404 The script above can be saved to test.stap and run using the stap(1)
18406 program. Note that you either have to be root, or you have to add
18407 yourself to several special stap groups. Consult the systemtap
18408 documentation for more information.
18409 # stap /tmp/test.stap
18411 ready
18412 In another terminal, run a guestfish command such as this:
18414 guestfish -N fs
18416 In the first terminal, stap trace output similar to this is shown:
18418 1318248056692655 (+0): launch_start
18420 1318248056692850 (+195): launch_build_appliance_start
18421 1318248056818285 (+125435): launch_build_appliance_end
18422 1318248056838059 (+19774): launch_run_qemu
18423 1318248061071167 (+4233108): launch_end
18424 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
18425
18427 Since April 2010, libguestfs has started to make separate development
18428 and stable releases, along with corresponding branches in our git
18429 repository. These separate releases can be identified by version
18430 number:
18431 even numbers for stable: 1.2.x, 1.4.x, ...
18433 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18434 |
18435 v
18436 1 . 3 . 5
18437 ^ ^
18438 | |
18439 | `-------- sub-version
18440 |
18441 `------ always '1' because we don't change the ABI
18442 Thus "1.3.5" is the 5th update to the development branch "1.3".
18444 As time passes we cherry pick fixes from the development branch and
18446 backport those into the stable branch, the effect being that the stable
18447 branch should get more stable and less buggy over time. So the stable
18448 releases are ideal for people who don't need new features but would
18449 just like the software to work.
18450 Our criteria for backporting changes are:
18452 · Documentation changes which don’t affect any code are backported
18454 unless the documentation refers to a future feature which is not in
18455 stable.
18456 · Bug fixes which are not controversial, fix obvious problems, and
18458 have been well tested are backported.
18459 · Simple rearrangements of code which shouldn't affect how it works
18461 get backported. This is so that the code in the two branches
18462 doesn't get too far out of step, allowing us to backport future
18463 fixes more easily.
18464 · We don’t backport new features, new APIs, new tools etc, except in
18466 one exceptional case: the new feature is required in order to
18467 implement an important bug fix.
18468 A new stable branch starts when we think the new features in
18470 development are substantial and compelling enough over the current
18471 stable branch to warrant it. When that happens we create new stable
18472 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18473 oh release won't necessarily be so stable at this point, but by
18474 backporting fixes from development, that branch will stabilize over
18475 time.
18476
18478 PROTOCOL LIMITS
18479 Internally libguestfs uses a message-based protocol to pass API calls
18480 and their responses to and from a small "appliance" (see
18481 guestfs-internals(1) for plenty more detail about this). The maximum
18482 message size used by the protocol is slightly less than 4 MB. For some
18483 API calls you may need to be aware of this limit. The API calls which
18484 may be affected are individually documented, with a link back to this
18485 section of the documentation.
18486 In libguestfs < 1.19.32, several calls had to encode either their
18488 entire argument list or their entire return value (or sometimes both)
18489 in a single protocol message, and this gave them an arbitrary
18490 limitation on how much data they could handle. For example,
18491 "guestfs_cat" could only download a file if it was less than around 4
18492 MB in size. In later versions of libguestfs, some of these limits have
18493 been removed. The APIs which were previously limited but are now
18494 unlimited (except perhaps by available memory) are listed below. To
18495 find out if a specific API is subject to protocol limits, check for the
18496 warning in the API documentation which links to this section, and
18497 remember to check the version of the documentation that matches the
18498 version of libguestfs you are using.
18499 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18501 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18502 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18503 "guestfs_ls".
18504 See also "UPLOADING" and "DOWNLOADING" for further information about
18506 copying large amounts of data into or out of a filesystem.
18507 MAXIMUM NUMBER OF DISKS
18509 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18510 may be added by calling "guestfs_max_disks". In earlier versions of
18511 libguestfs (ie. where this call is not available) you should assume the
18512 maximum is 25.
18513 The rest of this section covers implementation details, which could
18515 change in future.
18516 When using virtio-scsi disks (the default if available in qemu) the
18518 current limit is 255 disks. When using virtio-blk (the old default)
18519 the limit is around 27 disks, but may vary according to implementation
18520 details and whether the network is enabled.
18521 Virtio-scsi as used by libguestfs is configured to use one target per
18523 disk, and 256 targets are available.
18524 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18526 31 slots, but some of these are used for other purposes.
18527 One virtual disk is used by libguestfs internally.
18529 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18531 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18532 the limit was 25. This has been fixed in more recent versions.
18533 In libguestfs ≥ 1.20 it is possible to hot plug disks. See
18535 "HOTPLUGGING".
18536 MAXIMUM NUMBER OF PARTITIONS PER DISK
18538 Virtio limits the maximum number of partitions per disk to 15.
18539 This is because it reserves 4 bits for the minor device number (thus
18541 /dev/vda, and /dev/vda1 through /dev/vda15).
18542 If you attach a disk with more than 15 partitions, the extra partitions
18544 are ignored by libguestfs.
18545 MAXIMUM SIZE OF A DISK
18547 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18548 We have tested block devices up to 1 exabyte (2**60 or
18550 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18551 host filesystem.
18552 Although libguestfs probably does not impose any limit, the underlying
18554 host storage will. If you store disk images on a host ext4 filesystem,
18555 then the maximum size will be limited by the maximum ext4 file size
18556 (currently 16 TB). If you store disk images as host logical volumes
18557 then you are limited by the maximum size of an LV.
18558 For the hugest disk image files, we recommend using XFS on the host for
18560 storage.
18561 MAXIMUM SIZE OF A PARTITION
18563 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18564 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18565 address a partition located beyond 2 TB on the disk.
18566 It is recommended that you use GPT partitions on disks which are larger
18568 than this size. GPT uses 64 bit sector numbers and so can address
18569 partitions which are theoretically larger than the largest disk we
18570 could support.
18571 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18573 This depends on the filesystem type. libguestfs itself does not impose
18574 any known limit. Consult Wikipedia or the filesystem documentation to
18575 find out what these limits are.
18576 MAXIMUM UPLOAD AND DOWNLOAD
18578 The API functions "guestfs_upload", "guestfs_download",
18579 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18580 uploads and downloads.
18581 INSPECTION LIMITS
18583 The inspection code has several arbitrary limits on things like the
18584 size of Windows Registry hive it will read, and the length of product
18585 name. These are intended to stop a malicious guest from consuming
18586 arbitrary amounts of memory and disk space on the host, and should not
18587 be reached in practice. See the source code for more information.
18588
18590 Some of the tools support a --machine-readable option, which is
18591 generally used to make the output more machine friendly, for easier
18592 parsing for example. By default, this output goes to stdout.
18593 When using the --machine-readable option, the progress, information,
18595 warning, and error messages are also printed in JSON format for easier
18596 log tracking. Thus, it is highly recommended to redirect the machine-
18597 readable output to a different stream. The format of these JSON
18598 messages is like the following (actually printed within a single line,
18599 below it is indented for readability):
18600 {
18602 "message": "Finishing off",
18603 "timestamp": "2019-03-22T14:46:49.067294446+01:00",
18604 "type": "message"
18605 }
18606 "type" can be: "message" for progress messages, "info" for information
18608 messages, "warning" for warning messages, and "error" for error
18609 message. "timestamp" is the RFC 3339 timestamp of the message.
18610 In addition to that, a subset of these tools support an extra string
18612 passed to the --machine-readable option: this string specifies where
18613 the machine-readable output will go.
18614 The possible values are:
18616 fd:fd
18618 The output goes to the specified fd, which is a file descriptor
18619 already opened for writing.
18620 file:filename
18622 The output goes to the specified filename.
18623 stream:stdout
18625 The output goes to stdout. This is basically the same as the
18626 default behaviour of --machine-readable with no parameter, although
18627 stdout as output is specified explicitly.
18628 stream:stderr
18630 The output goes to stderr.
18631
18633 LIBGUESTFS_APPEND
18634 Pass additional options to the guest kernel.
18635 LIBGUESTFS_ATTACH_METHOD
18637 This is the old way to set "LIBGUESTFS_BACKEND".
18638 LIBGUESTFS_BACKEND
18640 Choose the default way to create the appliance. See
18641 "guestfs_set_backend" and "BACKEND".
18642 LIBGUESTFS_BACKEND_SETTINGS
18644 A colon-separated list of backend-specific settings. See
18645 "BACKEND", "BACKEND SETTINGS".
18646 LIBGUESTFS_CACHEDIR
18648 The location where libguestfs will cache its appliance, when using
18649 a supermin appliance. The appliance is cached and shared between
18650 all handles which have the same effective user ID.
18651 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18653 "TMPDIR" is not set, then /var/tmp is used.
18654 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18656 LIBGUESTFS_DEBUG
18658 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18659 same effect as calling "guestfs_set_verbose (g, 1)".
18660 LIBGUESTFS_HV
18662 Set the default hypervisor (usually qemu) binary that libguestfs
18663 uses. If not set, then the qemu which was found at compile time by
18664 the configure script is used.
18665 See also "QEMU WRAPPERS" above.
18667 LIBGUESTFS_MEMSIZE
18669 Set the memory allocated to the qemu process, in megabytes. For
18670 example:
18671 LIBGUESTFS_MEMSIZE=700
18673 LIBGUESTFS_PATH
18675 Set the path that libguestfs uses to search for a supermin
18676 appliance. See the discussion of paths in section "PATH" above.
18677 LIBGUESTFS_QEMU
18679 This is the old way to set "LIBGUESTFS_HV".
18680 LIBGUESTFS_TMPDIR
18682 The location where libguestfs will store temporary files used by
18683 each handle.
18684 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18686 "TMPDIR" is not set, then /tmp is used.
18687 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18689 LIBGUESTFS_TRACE
18691 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18692 same effect as calling "guestfs_set_trace (g, 1)".
18693 PATH
18695 Libguestfs may run some external programs, and relies on $PATH
18696 being set to a reasonable value. If using the libvirt backend,
18697 libvirt will not work at all unless $PATH contains the path of
18698 qemu/KVM. Note that PHP by default removes $PATH from the
18699 environment which tends to break everything.
18700 SUPERMIN_KERNEL
18702 SUPERMIN_KERNEL_VERSION
18703 SUPERMIN_MODULES
18704 These three environment variables allow the kernel that libguestfs
18705 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18706 set, then the most recent host kernel is chosen. For more
18707 information about kernel selection, see supermin(1).
18708 TMPDIR
18710 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18711 XDG_RUNTIME_DIR
18713 This directory represents a user-specific directory for storing
18714 non-essential runtime files.
18715 If it is set, then is used to store temporary sockets. Otherwise,
18717 /tmp is used.
18718 See also "get-sockdir",
18720 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18721
18723 Examples written in C: guestfs-examples(3).
18724 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18726 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18727 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18728 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18730 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18731 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18732 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18733 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18734 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18735 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18736 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18737 virt-win-reg(1).
18738 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18740 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18741 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18742 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18743 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18745 sd-journal(3).
18746 Website: http://libguestfs.org/
18748 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18750 disktype(1).
18751
18753 Richard W.M. Jones ("rjones at redhat dot com")
18754
18756 Copyright (C) 2009-2020 Red Hat Inc.
18757
18759 This library is free software; you can redistribute it and/or modify it
18760 under the terms of the GNU Lesser General Public License as published
18761 by the Free Software Foundation; either version 2 of the License, or
18762 (at your option) any later version.
18763 This library is distributed in the hope that it will be useful, but
18765 WITHOUT ANY WARRANTY; without even the implied warranty of
18766 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18767 Lesser General Public License for more details.
18768 You should have received a copy of the GNU Lesser General Public
18770 License along with this library; if not, write to the Free Software
18771 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18772 02110-1301 USA
18773
18775 To get a list of bugs against libguestfs, use this link:
18776 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18777 To report a new bug against libguestfs, use this link:
18779 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18780 When reporting a bug, please supply:
18782 · The version of libguestfs.
18784 · Where you got libguestfs (eg. which Linux distro, compiled from
18786 source, etc)
18787 · Describe the bug accurately and give a way to reproduce it.
18789 · Run libguestfs-test-tool(1) and paste the complete, unedited output
18791 into the bug report.
18792libguestfs-1.44.0 2021-01-05 guestfs(3)