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 force_kvm
1338 Using:
1340 export LIBGUESTFS_BACKEND_SETTINGS=force_kvm
1342 will force the direct and libvirt backends to use KVM (hardware
1344 accelerated virtualization) instead of TCG (software emulation).
1345 gdb
1347 The direct backend supports:
1349 export LIBGUESTFS_BACKEND_SETTINGS=gdb
1351 When this is set, qemu will not start running the appliance
1353 immediately. It will wait for you to connect to it using gdb:
1354 $ gdb
1356 (gdb) symbol-file /path/to/vmlinux
1357 (gdb) target remote tcp::1234
1358 (gdb) cont
1359 You can then debug the appliance kernel, which is useful to debug boot
1361 failures (especially ones where there are no debug messages printed -
1362 tip: look in the kernel "log_buf").
1363 On Fedora, install "kernel-debuginfo" for the "vmlinux" file
1365 (containing symbols). Make sure the symbols precisely match the kernel
1366 being used.
1367 ATTACHING TO RUNNING DAEMONS
1369 Note [4m(1): This is highly experimental and has a tendency to eat babies.
1370 Use with caution.
1371 Note [4m(2): This section explains how to attach to a running daemon from
1373 a low level perspective. For most users, simply using virt tools such
1374 as guestfish(1) with the --live option will "just work".
1375 Using guestfs_set_backend
1377 By calling "guestfs_set_backend" you can change how the library
1379 connects to the "guestfsd" daemon in "guestfs_launch" (read
1380 "ARCHITECTURE" in guestfs-internals(1) for some background).
1381 The normal backend is "direct", where a small appliance is created
1383 containing the daemon, and then the library connects to this.
1384 "libvirt" or "libvirt:URI" are alternatives that use libvirt to start
1385 the appliance.
1386 Setting the backend to "unix:path" (where path is the path of a Unix
1388 domain socket) causes "guestfs_launch" to connect to an existing daemon
1389 over the Unix domain socket.
1390 The normal use for this is to connect to a running virtual machine that
1392 contains a "guestfsd" daemon, and send commands so you can read and
1393 write files inside the live virtual machine.
1394 Using guestfs_add_domain with live flag
1396 "guestfs_add_domain" provides some help for getting the correct
1398 backend. If you pass the "live" option to this function, then (if the
1399 virtual machine is running) it will examine the libvirt XML looking for
1400 a virtio-serial channel to connect to:
1401 <domain>
1403 ...
1404 <devices>
1405 ...
1406 <channel type='unix'>
1407 <source mode='bind' path='/path/to/socket'/>
1408 <target type='virtio' name='org.libguestfs.channel.0'/>
1409 </channel>
1410 ...
1411 </devices>
1412 </domain>
1413 "guestfs_add_domain" extracts /path/to/socket and sets the backend to
1415 "unix:/path/to/socket".
1416 Some of the libguestfs tools (including guestfish) support a --live
1418 option which is passed through to "guestfs_add_domain" thus allowing
1419 you to attach to and modify live virtual machines.
1420 The virtual machine needs to have been set up beforehand so that it has
1422 the virtio-serial channel and so that guestfsd is running inside it.
1423 USER-MODE LINUX BACKEND
1425 Setting the following environment variables (or the equivalent in the
1426 API) selects the User-Mode Linux backend:
1427 export LIBGUESTFS_BACKEND=uml
1429 export LIBGUESTFS_HV=/path/to/vmlinux
1430 "vmlinux" (or it may be called "linux") is the Linux binary, compiled
1432 to run as a userspace process. Note that we reuse the qemu variable in
1433 the handle for convenience; qemu is not involved.
1434 User-Mode Linux can be faster and more lightweight than running a full-
1436 blown virtual machine as the backend (especially if you are already
1437 running libguestfs in a virtual machine or cloud instance), but it also
1438 has some shortcomings compared to the usual qemu/KVM-based backend.
1439 BUILDING USER-MODE LINUX FROM SOURCE
1441 Your Linux distro may provide UML in which case you can ignore this
1443 section.
1444 These instructions are adapted from:
1446 http://user-mode-linux.sourceforge.net/source.html
1447 1. Check out Linux sources
1449 Clone the Linux git repository or download the Linux source
1450 tarball.
1451 2. Configure the kernel
1453 Note: All ‘make’ commands must have "ARCH=um" added.
1454 make menuconfig ARCH=um
1456 Make sure any filesystem drivers that you need are compiled into
1458 the kernel.
1459 Currently, it needs a large amount of extra work to get modules
1461 working. It’s recommended that you disable module support in the
1462 kernel configuration, which will cause everything to be compiled
1463 into the image.
1464 3. Build the kernel
1466 make ARCH=um
1467 This will leave a file called "linux" or "vmlinux" in the top-level
1469 directory. This is the UML kernel. You should set "LIBGUESTFS_HV"
1470 to point to this file.
1471 USER-MODE LINUX DIFFERENCES FROM KVM
1473 UML only supports raw-format images
1475 Only plain raw-format images will work. No qcow2, no backing
1476 files.
1477 UML does not support any remote drives
1479 No NBD, etc.
1480 UML only works on ix86 and x86-64
1482 UML is experimental
1483 In particular, support for UML in libguestfs depends on support for
1484 UML in the upstream kernel. If UML was ever removed from the
1485 upstream Linux kernel, then we might remove it from libguestfs too.
1486 ABI GUARANTEE
1488 We guarantee the libguestfs ABI (binary interface), for public, high-
1489 level actions as outlined in this section. Although we will deprecate
1490 some actions, for example if they get replaced by newer calls, we will
1491 keep the old actions forever. This allows you the developer to program
1492 in confidence against the libguestfs API.
1493 BLOCK DEVICE NAMING
1495 Libguestfs defines /dev/sd* as the standard naming scheme for devices
1496 passed to API calls. So /dev/sda means "the first device added by
1497 "guestfs_add_drive_opts"", and /dev/sdb3 means "the third partition on
1498 the second device".
1499 Internally device names are sometimes translated, but this should not
1501 be visible at the API level.
1502 DISK LABELS
1504 In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1506 using the optional "label" parameter to "guestfs_add_drive_opts".
1507 (Note that disk labels are different from and not related to filesystem
1508 labels).
1509 Not all versions of libguestfs support setting a disk label, and when
1511 it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1512 When you add a disk with a label, it can either be addressed using
1514 /dev/sd*, or using /dev/disk/guestfs/label. Partitions on the disk can
1515 be addressed using /dev/disk/guestfs/labelpartnum.
1516 Listing devices ("guestfs_list_devices") and partitions
1518 ("guestfs_list_partitions") returns the block device names. However
1519 you can use "guestfs_list_disk_labels" to map disk labels to block
1520 device and partition names.
1521 NULL DISKS
1523 When adding a disk using, eg., "guestfs_add_drive", you can set the
1524 filename to "/dev/null". This string is treated specially by
1525 libguestfs, causing it to add a "null disk".
1526 A null disk has the following properties:
1528 • A null disk will appear as a normal device, eg. in calls to
1530 "guestfs_list_devices".
1531 • You may add "/dev/null" multiple times.
1533 • You should not try to access a null disk in any way. For example,
1535 you shouldn't try to read it or mount it.
1536 Null disks are used for three main purposes:
1538 1. Performance testing of libguestfs (see guestfs-performance(1)).
1540 2. The internal test suite.
1542 3. If you want to use libguestfs APIs that don’t refer to disks, since
1544 libguestfs requires that at least one disk is added, you should add
1545 a null disk.
1546 For example, to test if a feature is available, use code like this:
1548 guestfs_h *g;
1550 char **groups = [ "btrfs", NULL ];
1551 g = guestfs_create ();
1553 guestfs_add_drive (g, "/dev/null");
1554 guestfs_launch (g);
1555 if (guestfs_available (g, groups) == 0) {
1556 // group(s) are available
1557 } else {
1558 // group(s) are not available
1559 }
1560 guestfs_close (g);
1561 DISK IMAGE FORMATS
1563 Virtual disks come in a variety of formats. Some common formats are
1564 listed below.
1565 Note that libguestfs itself is not responsible for handling the disk
1567 format: this is done using qemu(1). If support for a particular format
1568 is missing or broken, this has to be fixed in qemu.
1569 COMMON VIRTUAL DISK IMAGE FORMATS
1571 raw Raw format is simply a dump of the sequential bytes of the virtual
1573 hard disk. There is no header, container, compression or
1574 processing of any sort.
1575 Since raw format requires no translation to read or write, it is
1577 both fast and very well supported by qemu and all other
1578 hypervisors. You can consider it to be a universal format that any
1579 hypervisor can access.
1580 Raw format files are not compressed and so take up the full space
1582 of the original disk image even when they are empty. A variation
1583 (on Linux/Unix at least) is to not store ranges of all-zero bytes
1584 by storing the file as a sparse file. This "variant format" is
1585 sometimes called raw sparse. Many utilities, including
1586 virt-sparsify(1), can make raw disk images sparse.
1587 qcow2
1589 Qcow2 is the native disk image format used by qemu. Internally it
1590 uses a two-level directory structure so that only blocks containing
1591 data are stored in the file. It also has many other features such
1592 as compression, snapshots and backing files.
1593 There are at least two distinct variants of this format, although
1595 qemu (and hence libguestfs) handles both transparently to the user.
1596 vmdk
1598 VMDK is VMware’s native disk image format. There are many
1599 variations. Modern qemu (hence libguestfs) supports most
1600 variations, but you should be aware that older versions of qemu had
1601 some very bad data-corrupting bugs in this area.
1602 Note that VMware ESX exposes files with the name guest-flat.vmdk.
1604 These are not VMDK. They are raw format files which happen to have
1605 a ".vmdk" extension.
1606 vdi VDI is VirtualBox’s native disk image format. Qemu (hence
1608 libguestfs) has generally good support for this.
1609 vpc
1611 vhd VPC (old) and VHD (modern) are the native disk image format of
1612 Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1613 Obsolete formats
1615 The following formats are obsolete and should not be used: qcow
1616 (aka qcow1), cow, bochs.
1617 DETECTING THE FORMAT OF A DISK IMAGE
1619 Firstly note there is a security issue with auto-detecting the format
1621 of a disk image. It may or may not apply in your use case. Read
1622 "CVE-2010-3851" below.
1623 Libguestfs offers an API to get the format of a disk image
1625 ("guestfs_disk_format"), and it is safest to use this.
1626 Don’t be tempted to try parsing the text / human-readable output of
1628 "qemu-img" since it cannot be parsed reliably and securely. Also do
1629 not use the "file" command since the output of that changes over time.
1630
1632 guestfs_h *
1633 "guestfs_h" is the opaque type representing a connection handle.
1634 Create a handle by calling "guestfs_create" or "guestfs_create_flags".
1635 Call "guestfs_close" to free the handle and release all resources used.
1636 For information on using multiple handles and threads, see the section
1638 "MULTIPLE HANDLES AND MULTIPLE THREADS" above.
1639 guestfs_create
1641 guestfs_h *guestfs_create (void);
1642 Create a connection handle.
1644 On success this returns a non-NULL pointer to a handle. On error it
1646 returns NULL.
1647 You have to "configure" the handle after creating it. This includes
1649 calling "guestfs_add_drive_opts" (or one of the equivalent calls) on
1650 the handle at least once.
1651 After configuring the handle, you have to call "guestfs_launch".
1653 You may also want to configure error handling for the handle. See the
1655 "ERROR HANDLING" section below.
1656 guestfs_create_flags
1658 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
1659 Create a connection handle, supplying extra flags and extra arguments
1661 to control how the handle is created.
1662 On success this returns a non-NULL pointer to a handle. On error it
1664 returns NULL.
1665 "guestfs_create" is equivalent to calling guestfs_create_flags(0).
1667 The following flags may be logically ORed together. (Currently no
1669 extra arguments are used).
1670 "GUESTFS_CREATE_NO_ENVIRONMENT"
1672 Don’t parse any environment variables (such as "LIBGUESTFS_DEBUG"
1673 etc).
1674 You can call "guestfs_parse_environment" or
1676 "guestfs_parse_environment_list" afterwards to parse environment
1677 variables. Alternately, don't call these functions if you want the
1678 handle to be unaffected by environment variables. See the example
1679 below.
1680 The default (if this flag is not given) is to implicitly call
1682 "guestfs_parse_environment".
1683 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT"
1685 Don’t try to close the handle in an atexit(3) handler if the
1686 program exits without explicitly closing the handle.
1687 The default (if this flag is not given) is to install such an
1689 atexit handler.
1690 USING "GUESTFS_CREATE_NO_ENVIRONMENT"
1692 You might use "GUESTFS_CREATE_NO_ENVIRONMENT" and an explicit call to
1694 "guestfs_parse_environment" like this:
1695 guestfs_h *g;
1697 int r;
1698 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
1700 if (!g) {
1701 perror ("guestfs_create_flags");
1702 exit (EXIT_FAILURE);
1703 }
1704 r = guestfs_parse_environment (g);
1705 if (r == -1)
1706 exit (EXIT_FAILURE);
1707 Or to create a handle which is unaffected by environment variables,
1709 omit the call to "guestfs_parse_environment" from the above code.
1710 The above code has another advantage which is that any errors from
1712 parsing the environment are passed through the error handler, whereas
1713 "guestfs_create" prints errors on stderr and ignores them.
1714 guestfs_close
1716 void guestfs_close (guestfs_h *g);
1717 This closes the connection handle and frees up all resources used. If
1719 a close callback was set on the handle, then it is called.
1720 The correct way to close the handle is:
1722 if (guestfs_shutdown (g) == -1) {
1724 /* handle write errors here */
1725 }
1726 guestfs_close (g);
1727 "guestfs_shutdown" is only needed if all of the following are true:
1729 1. one or more disks were added in read-write mode, and
1731 2. guestfs_launch was called, and
1733 3. you made some changes, and
1735 4. you have a way to handle write errors (eg. by exiting with an error
1737 code or reporting something to the user).
1738
1740 API functions can return errors. For example, almost all functions
1741 that return "int" will return "-1" to indicate an error.
1742 Additional information is available for errors: an error message string
1744 and optionally an error number (errno) if the thing that failed was a
1745 system call.
1746 You can get at the additional information about the last error on the
1748 handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1749 setting up an error handler with "guestfs_set_error_handler".
1750 When the handle is created, a default error handler is installed which
1752 prints the error message string to "stderr". For small short-running
1753 command line programs it is sufficient to do:
1754 if (guestfs_launch (g) == -1)
1756 exit (EXIT_FAILURE);
1757 since the default error handler will ensure that an error message has
1759 been printed to "stderr" before the program exits.
1760 For other programs the caller will almost certainly want to install an
1762 alternate error handler or do error handling in-line as in the example
1763 below. The non-C language bindings all install NULL error handlers and
1764 turn errors into exceptions using code similar to this:
1765 const char *msg;
1767 int errnum;
1768 /* This disables the default behaviour of printing errors
1770 on stderr. */
1771 guestfs_set_error_handler (g, NULL, NULL);
1772 if (guestfs_launch (g) == -1) {
1774 /* Examine the error message and print it, throw it,
1775 etc. */
1776 msg = guestfs_last_error (g);
1777 errnum = guestfs_last_errno (g);
1778 fprintf (stderr, "%s", msg);
1780 if (errnum != 0)
1781 fprintf (stderr, ": %s", strerror (errnum));
1782 fprintf (stderr, "\n");
1783 /* ... */
1785 }
1786 "guestfs_create" returns "NULL" if the handle cannot be created, and
1788 because there is no handle if this happens there is no way to get
1789 additional error information. Since libguestfs ≥ 1.20, you can use
1790 "guestfs_create_flags" to properly deal with errors during handle
1791 creation, although the vast majority of programs can continue to use
1792 "guestfs_create" and not worry about this situation.
1793 Out of memory errors are handled differently. The default action is to
1795 call abort(3). If this is undesirable, then you can set a handler
1796 using "guestfs_set_out_of_memory_handler".
1797 guestfs_last_error
1799 const char *guestfs_last_error (guestfs_h *g);
1800 This returns the last error message that happened on "g". If there has
1802 not been an error since the handle was created, then this returns
1803 "NULL".
1804 Note the returned string does not have a newline character at the end.
1806 Most error messages are single lines. Some are split over multiple
1807 lines and contain "\n" characters within the string but not at the end.
1808 The lifetime of the returned string is until the next error occurs on
1810 the same handle, or "guestfs_close" is called. If you need to keep it
1811 longer, copy it.
1812 guestfs_last_errno
1814 int guestfs_last_errno (guestfs_h *g);
1815 This returns the last error number (errno) that happened on "g".
1817 If successful, an errno integer not equal to zero is returned.
1819 In many cases the special errno "ENOTSUP" is returned if you tried to
1821 call a function or use a feature which is not supported.
1822 If no error number is available, this returns 0. This call can return
1824 0 in three situations:
1825 1. There has not been any error on the handle.
1827 2. There has been an error but the errno was meaningless. This
1829 corresponds to the case where the error did not come from a failed
1830 system call, but for some other reason.
1831 3. There was an error from a failed system call, but for some reason
1833 the errno was not captured and returned. This usually indicates a
1834 bug in libguestfs.
1835 Libguestfs tries to convert the errno from inside the appliance into a
1837 corresponding errno for the caller (not entirely trivial: the appliance
1838 might be running a completely different operating system from the
1839 library and error numbers are not standardized across Un*xen). If this
1840 could not be done, then the error is translated to "EINVAL". In
1841 practice this should only happen in very rare circumstances.
1842 guestfs_set_error_handler
1844 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1845 void *opaque,
1846 const char *msg);
1847 void guestfs_set_error_handler (guestfs_h *g,
1848 guestfs_error_handler_cb cb,
1849 void *opaque);
1850 The callback "cb" will be called if there is an error. The parameters
1852 passed to the callback are an opaque data pointer and the error message
1853 string.
1854 "errno" is not passed to the callback. To get that the callback must
1856 call "guestfs_last_errno".
1857 Note that the message string "msg" is freed as soon as the callback
1859 function returns, so if you want to stash it somewhere you must make
1860 your own copy.
1861 The default handler prints messages on "stderr".
1863 If you set "cb" to "NULL" then no handler is called.
1865 guestfs_get_error_handler
1867 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1868 void **opaque_rtn);
1869 Returns the current error handler callback.
1871 guestfs_push_error_handler
1873 void guestfs_push_error_handler (guestfs_h *g,
1874 guestfs_error_handler_cb cb,
1875 void *opaque);
1876 This is the same as "guestfs_set_error_handler", except that the old
1878 error handler is stashed away in a stack inside the handle. You can
1879 restore the previous error handler by calling
1880 "guestfs_pop_error_handler".
1881 Use the following code to temporarily disable errors around a function:
1883 guestfs_push_error_handler (g, NULL, NULL);
1885 guestfs_mkdir (g, "/foo"); /* We don't care if this fails. */
1886 guestfs_pop_error_handler (g);
1887 guestfs_pop_error_handler
1889 void guestfs_pop_error_handler (guestfs_h *g);
1890 Restore the previous error handler (see "guestfs_push_error_handler").
1892 If you pop the stack too many times, then the default error handler is
1894 restored.
1895 guestfs_set_out_of_memory_handler
1897 typedef void (*guestfs_abort_cb) (void);
1898 void guestfs_set_out_of_memory_handler (guestfs_h *g,
1899 guestfs_abort_cb);
1900 The callback "cb" will be called if there is an out of memory
1902 situation. Note this callback must not return.
1903 The default is to call abort(3).
1905 You cannot set "cb" to "NULL". You can’t ignore out of memory
1907 situations.
1908 guestfs_get_out_of_memory_handler
1910 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1911 This returns the current out of memory handler.
1913
1915 guestfs_acl_delete_def_file
1916 int
1917 guestfs_acl_delete_def_file (guestfs_h *g,
1918 const char *dir);
1919 This function deletes the default POSIX Access Control List (ACL)
1921 attached to directory "dir".
1922 This function returns 0 on success or -1 on error.
1924 This function depends on the feature "acl". See also
1926 "guestfs_feature_available".
1927 (Added in 1.19.63)
1929 guestfs_acl_get_file
1931 char *
1932 guestfs_acl_get_file (guestfs_h *g,
1933 const char *path,
1934 const char *acltype);
1935 This function returns the POSIX Access Control List (ACL) attached to
1937 "path". The ACL is returned in "long text form" (see acl(5)).
1938 The "acltype" parameter may be:
1940 "access"
1942 Return the ordinary (access) ACL for any file, directory or other
1943 filesystem object.
1944 "default"
1946 Return the default ACL. Normally this only makes sense if "path"
1947 is a directory.
1948 This function returns a string, or NULL on error. The caller must free
1950 the returned string after use.
1951 This function depends on the feature "acl". See also
1953 "guestfs_feature_available".
1954 (Added in 1.19.63)
1956 guestfs_acl_set_file
1958 int
1959 guestfs_acl_set_file (guestfs_h *g,
1960 const char *path,
1961 const char *acltype,
1962 const char *acl);
1963 This function sets the POSIX Access Control List (ACL) attached to
1965 "path".
1966 The "acltype" parameter may be:
1968 "access"
1970 Set the ordinary (access) ACL for any file, directory or other
1971 filesystem object.
1972 "default"
1974 Set the default ACL. Normally this only makes sense if "path" is a
1975 directory.
1976 The "acl" parameter is the new ACL in either "long text form" or "short
1978 text form" (see acl(5)). The new ACL completely replaces any previous
1979 ACL on the file. The ACL must contain the full Unix permissions (eg.
1980 "u::rwx,g::rx,o::rx").
1981 If you are specifying individual users or groups, then the mask field
1983 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1984 "g:ID:..." field(s). A full ACL string might therefore look like this:
1985 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1987 \ Unix permissions / \mask/ \ ACL /
1988 You should use numeric UIDs and GIDs. To map usernames and groupnames
1990 to the correct numeric ID in the context of the guest, use the Augeas
1991 functions (see "guestfs_aug_init").
1992 This function returns 0 on success or -1 on error.
1994 This function depends on the feature "acl". See also
1996 "guestfs_feature_available".
1997 (Added in 1.19.63)
1999 guestfs_add_cdrom
2001 int
2002 guestfs_add_cdrom (guestfs_h *g,
2003 const char *filename);
2004 This function is deprecated. In new code, use the
2006 "guestfs_add_drive_ro" call instead.
2007 Deprecated functions will not be removed from the API, but the fact
2009 that they are deprecated indicates that there are problems with correct
2010 use of these functions.
2011 This function adds a virtual CD-ROM disk image to the guest.
2013 The image is added as read-only drive, so this function is equivalent
2015 of "guestfs_add_drive_ro".
2016 This function returns 0 on success or -1 on error.
2018 (Added in 0.3)
2020 guestfs_add_domain
2022 int
2023 guestfs_add_domain (guestfs_h *g,
2024 const char *dom,
2025 ...);
2026 You may supply a list of optional arguments to this call. Use zero or
2028 more of the following pairs of parameters, and terminate the list with
2029 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2030 GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
2032 GUESTFS_ADD_DOMAIN_READONLY, int readonly,
2033 GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
2034 GUESTFS_ADD_DOMAIN_LIVE, int live,
2035 GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
2036 GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
2037 GUESTFS_ADD_DOMAIN_CACHEMODE, const char *cachemode,
2038 GUESTFS_ADD_DOMAIN_DISCARD, const char *discard,
2039 GUESTFS_ADD_DOMAIN_COPYONREAD, int copyonread,
2040 This function adds the disk(s) attached to the named libvirt domain
2042 "dom". It works by connecting to libvirt, requesting the domain and
2043 domain XML from libvirt, parsing it for disks, and calling
2044 "guestfs_add_drive_opts" on each one.
2045 The number of disks added is returned. This operation is atomic: if an
2047 error is returned, then no disks are added.
2048 This function does some minimal checks to make sure the libvirt domain
2050 is not running (unless "readonly" is true). In a future version we
2051 will try to acquire the libvirt lock on each disk.
2052 Disks must be accessible locally. This often means that adding disks
2054 from a remote libvirt connection (see https://libvirt.org/remote.html)
2055 will fail unless those disks are accessible via the same device path
2056 locally too.
2057 The optional "libvirturi" parameter sets the libvirt URI (see
2059 https://libvirt.org/uri.html). If this is not set then we connect to
2060 the default libvirt URI (or one set through an environment variable,
2061 see the libvirt documentation for full details).
2062 The optional "live" flag controls whether this call will try to connect
2064 to a running virtual machine "guestfsd" process if it sees a suitable
2065 <channel> element in the libvirt XML definition. The default (if the
2066 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
2067 for more information.
2068 If the "allowuuid" flag is true (default is false) then a UUID may be
2070 passed instead of the domain name. The "dom" string is treated as a
2071 UUID first and looked up, and if that lookup fails then we treat "dom"
2072 as a name as usual.
2073 The optional "readonlydisk" parameter controls what we do for disks
2075 which are marked <readonly/> in the libvirt XML. Possible values are:
2076 readonlydisk = "error"
2078 If "readonly" is false:
2079 The whole call is aborted with an error if any disk with the
2081 <readonly/> flag is found.
2082 If "readonly" is true:
2084 Disks with the <readonly/> flag are added read-only.
2086 readonlydisk = "read"
2088 If "readonly" is false:
2089 Disks with the <readonly/> flag are added read-only. Other disks
2091 are added read/write.
2092 If "readonly" is true:
2094 Disks with the <readonly/> flag are added read-only.
2096 readonlydisk = "write" (default)
2098 If "readonly" is false:
2099 Disks with the <readonly/> flag are added read/write.
2101 If "readonly" is true:
2103 Disks with the <readonly/> flag are added read-only.
2105 readonlydisk = "ignore"
2107 If "readonly" is true or false:
2108 Disks with the <readonly/> flag are skipped.
2110 If present, the value of "logical_block_size" attribute of <blockio/>
2112 tag in libvirt XML will be passed as "blocksize" parameter to
2113 "guestfs_add_drive_opts".
2114 The other optional parameters are passed directly through to
2116 "guestfs_add_drive_opts".
2117 On error this function returns -1.
2119 (Added in 1.7.4)
2121 guestfs_add_domain_va
2123 int
2124 guestfs_add_domain_va (guestfs_h *g,
2125 const char *dom,
2126 va_list args);
2127 This is the "va_list variant" of "guestfs_add_domain".
2129 See "CALLS WITH OPTIONAL ARGUMENTS".
2131 guestfs_add_domain_argv
2133 int
2134 guestfs_add_domain_argv (guestfs_h *g,
2135 const char *dom,
2136 const struct guestfs_add_domain_argv *optargs);
2137 This is the "argv variant" of "guestfs_add_domain".
2139 See "CALLS WITH OPTIONAL ARGUMENTS".
2141 guestfs_add_drive
2143 int
2144 guestfs_add_drive (guestfs_h *g,
2145 const char *filename);
2146 This function is provided for backwards compatibility with earlier
2148 versions of libguestfs. It simply calls "guestfs_add_drive_opts" with
2149 no optional arguments.
2150 (Added in 0.3)
2152 guestfs_add_drive_opts
2154 int
2155 guestfs_add_drive_opts (guestfs_h *g,
2156 const char *filename,
2157 ...);
2158 You may supply a list of optional arguments to this call. Use zero or
2160 more of the following pairs of parameters, and terminate the list with
2161 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2162 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2164 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2165 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2166 GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2167 GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2168 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2169 GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2170 GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2171 GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2172 GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2173 GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2174 GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2175 GUESTFS_ADD_DRIVE_OPTS_BLOCKSIZE, int blocksize,
2176 This function adds a disk image called filename to the handle.
2178 filename may be a regular host file or a host device.
2179 When this function is called before "guestfs_launch" (the usual case)
2181 then the first time you call this function, the disk appears in the API
2182 as /dev/sda, the second time as /dev/sdb, and so on.
2183 In libguestfs ≥ 1.20 you can also call this function after launch (with
2185 some restrictions). This is called "hotplugging". When hotplugging,
2186 you must specify a "label" so that the new disk gets a predictable
2187 name. For more information see "HOTPLUGGING".
2188 You don't necessarily need to be root when using libguestfs. However
2190 you obviously do need sufficient permissions to access the filename for
2191 whatever operations you want to perform (ie. read access if you just
2192 want to read the image or write access if you want to modify the
2193 image).
2194 This call checks that filename exists.
2196 filename may be the special string "/dev/null". See "NULL DISKS".
2198 The optional arguments are:
2200 "readonly"
2202 If true then the image is treated as read-only. Writes are still
2203 allowed, but they are stored in a temporary snapshot overlay which
2204 is discarded at the end. The disk that you add is not modified.
2205 "format"
2207 This forces the image format. If you omit this (or use
2208 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2209 automatically detected. Possible formats include "raw" and
2210 "qcow2".
2211 Automatic detection of the format opens you up to a potential
2213 security hole when dealing with untrusted raw-format images. See
2214 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
2215 security hole.
2216 "iface"
2218 This rarely-used option lets you emulate the behaviour of the
2219 deprecated "guestfs_add_drive_with_if" call (q.v.)
2220 "name"
2222 The name the drive had in the original guest, e.g. /dev/sdb. This
2223 is used as a hint to the guest inspection process if it is
2224 available.
2225 "label"
2227 Give the disk a label. The label should be a unique, short string
2228 using only ASCII characters "[a-zA-Z]". As well as its usual name
2229 in the API (such as /dev/sda), the drive will also be named
2230 /dev/disk/guestfs/label.
2231 See "DISK LABELS".
2233 "protocol"
2235 The optional protocol argument can be used to select an alternate
2236 source protocol.
2237 See also: "REMOTE STORAGE".
2239 "protocol = "file""
2241 filename is interpreted as a local file or device. This is the
2242 default if the optional protocol parameter is omitted.
2243 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
2245 Connect to a remote FTP, HTTP or TFTP server. The "server"
2246 parameter must also be supplied - see below.
2247 See also: "FTP, HTTP AND TFTP"
2249 "protocol = "gluster""
2251 Connect to the GlusterFS server. The "server" parameter must
2252 also be supplied - see below.
2253 See also: "GLUSTER"
2255 "protocol = "iscsi""
2257 Connect to the iSCSI server. The "server" parameter must also
2258 be supplied - see below. The "username" parameter may be
2259 supplied. See below. The "secret" parameter may be supplied.
2260 See below.
2261 See also: "ISCSI".
2263 "protocol = "nbd""
2265 Connect to the Network Block Device server. The "server"
2266 parameter must also be supplied - see below.
2267 See also: "NETWORK BLOCK DEVICE".
2269 "protocol = "rbd""
2271 Connect to the Ceph (librbd/RBD) server. The "server"
2272 parameter must also be supplied - see below. The "username"
2273 parameter may be supplied. See below. The "secret" parameter
2274 may be supplied. See below.
2275 See also: "CEPH".
2277 "protocol = "sheepdog""
2279 Connect to the Sheepdog server. The "server" parameter may
2280 also be supplied - see below.
2281 See also: "SHEEPDOG".
2283 "protocol = "ssh""
2285 Connect to the Secure Shell (ssh) server.
2286 The "server" parameter must be supplied. The "username"
2288 parameter may be supplied. See below.
2289 See also: "SSH".
2291 "server"
2293 For protocols which require access to a remote server, this is a
2294 list of server(s).
2295 Protocol Number of servers required
2297 -------- --------------------------
2298 file List must be empty or param not used at all
2299 ftp|ftps|http|https|tftp Exactly one
2300 gluster Exactly one
2301 iscsi Exactly one
2302 nbd Exactly one
2303 rbd Zero or more
2304 sheepdog Zero or more
2305 ssh Exactly one
2306 Each list element is a string specifying a server. The string must
2308 be in one of the following formats:
2309 hostname
2311 hostname:port
2312 tcp:hostname
2313 tcp:hostname:port
2314 unix:/path/to/socket
2315 If the port number is omitted, then the standard port number for
2317 the protocol is used (see /etc/services).
2318 "username"
2320 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
2321 "tftp" protocols, this specifies the remote username.
2322 If not given, then the local username is used for "ssh", and no
2324 authentication is attempted for ceph. But note this sometimes may
2325 give unexpected results, for example if using the libvirt backend
2326 and if the libvirt backend is configured to start the qemu
2327 appliance as a special user such as "qemu.qemu". If in doubt,
2328 specify the remote username you want.
2329 "secret"
2331 For the "rbd" protocol only, this specifies the ‘secret’ to use
2332 when connecting to the remote device. It must be base64 encoded.
2333 If not given, then a secret matching the given username will be
2335 looked up in the default keychain locations, or if no username is
2336 given, then no authentication will be used.
2337 "cachemode"
2339 Choose whether or not libguestfs will obey sync operations (safe
2340 but slow) or not (unsafe but fast). The possible values for this
2341 string are:
2342 "cachemode = "writeback""
2344 This is the default.
2345 Write operations in the API do not return until a write(2) call
2347 has completed in the host [but note this does not imply that
2348 anything gets written to disk].
2349 Sync operations in the API, including implicit syncs caused by
2351 filesystem journalling, will not return until an fdatasync(2)
2352 call has completed in the host, indicating that data has been
2353 committed to disk.
2354 "cachemode = "unsafe""
2356 In this mode, there are no guarantees. Libguestfs may cache
2357 anything and ignore sync requests. This is suitable only for
2358 scratch or temporary disks.
2359 "discard"
2361 Enable or disable discard (a.k.a. trim or unmap) support on this
2362 drive. If enabled, operations such as "guestfs_fstrim" will be
2363 able to discard / make thin / punch holes in the underlying host
2364 file or device.
2365 Possible discard settings are:
2367 "discard = "disable""
2369 Disable discard support. This is the default.
2370 "discard = "enable""
2372 Enable discard support. Fail if discard is not possible.
2373 "discard = "besteffort""
2375 Enable discard support if possible, but don't fail if it is not
2376 supported.
2377 Since not all backends and not all underlying systems support
2379 discard, this is a good choice if you want to use discard if
2380 possible, but don't mind if it doesn't work.
2381 "copyonread"
2383 The boolean parameter "copyonread" enables copy-on-read support.
2384 This only affects disk formats which have backing files, and causes
2385 reads to be stored in the overlay layer, speeding up multiple reads
2386 of the same area of disk.
2387 The default is false.
2389 "blocksize"
2391 This parameter sets the sector size of the disk. Possible values
2392 are 512 (the default if the parameter is omitted) or 4096. Use
2393 4096 when handling an "Advanced Format" disk that uses 4K sector
2394 size (https://en.wikipedia.org/wiki/Advanced_Format).
2395 Only a subset of the backends support this parameter (currently
2397 only the libvirt and direct backends do).
2398 This function returns 0 on success or -1 on error.
2400 (Added in 0.3)
2402 guestfs_add_drive_opts_va
2404 int
2405 guestfs_add_drive_opts_va (guestfs_h *g,
2406 const char *filename,
2407 va_list args);
2408 This is the "va_list variant" of "guestfs_add_drive_opts".
2410 See "CALLS WITH OPTIONAL ARGUMENTS".
2412 guestfs_add_drive_opts_argv
2414 int
2415 guestfs_add_drive_opts_argv (guestfs_h *g,
2416 const char *filename,
2417 const struct guestfs_add_drive_opts_argv *optargs);
2418 This is the "argv variant" of "guestfs_add_drive_opts".
2420 See "CALLS WITH OPTIONAL ARGUMENTS".
2422 guestfs_add_drive_ro
2424 int
2425 guestfs_add_drive_ro (guestfs_h *g,
2426 const char *filename);
2427 This function is the equivalent of calling "guestfs_add_drive_opts"
2429 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2430 so the disk is added read-only, with the format being detected
2431 automatically.
2432 This function returns 0 on success or -1 on error.
2434 (Added in 1.0.38)
2436 guestfs_add_drive_ro_with_if
2438 int
2439 guestfs_add_drive_ro_with_if (guestfs_h *g,
2440 const char *filename,
2441 const char *iface);
2442 This function is deprecated. In new code, use the "guestfs_add_drive"
2444 call instead.
2445 Deprecated functions will not be removed from the API, but the fact
2447 that they are deprecated indicates that there are problems with correct
2448 use of these functions.
2449 This is the same as "guestfs_add_drive_ro" but it allows you to specify
2451 the QEMU interface emulation to use at run time.
2452 This function returns 0 on success or -1 on error.
2454 (Added in 1.0.84)
2456 guestfs_add_drive_scratch
2458 int
2459 guestfs_add_drive_scratch (guestfs_h *g,
2460 int64_t size,
2461 ...);
2462 You may supply a list of optional arguments to this call. Use zero or
2464 more of the following pairs of parameters, and terminate the list with
2465 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2466 GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2468 GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2469 GUESTFS_ADD_DRIVE_SCRATCH_BLOCKSIZE, int blocksize,
2470 This command adds a temporary scratch drive to the handle. The "size"
2472 parameter is the virtual size (in bytes). The scratch drive is blank
2473 initially (all reads return zeroes until you start writing to it). The
2474 drive is deleted when the handle is closed.
2475 The optional arguments "name", "label" and "blocksize" are passed
2477 through to "guestfs_add_drive_opts".
2478 This function returns 0 on success or -1 on error.
2480 (Added in 1.23.10)
2482 guestfs_add_drive_scratch_va
2484 int
2485 guestfs_add_drive_scratch_va (guestfs_h *g,
2486 int64_t size,
2487 va_list args);
2488 This is the "va_list variant" of "guestfs_add_drive_scratch".
2490 See "CALLS WITH OPTIONAL ARGUMENTS".
2492 guestfs_add_drive_scratch_argv
2494 int
2495 guestfs_add_drive_scratch_argv (guestfs_h *g,
2496 int64_t size,
2497 const struct guestfs_add_drive_scratch_argv *optargs);
2498 This is the "argv variant" of "guestfs_add_drive_scratch".
2500 See "CALLS WITH OPTIONAL ARGUMENTS".
2502 guestfs_add_drive_with_if
2504 int
2505 guestfs_add_drive_with_if (guestfs_h *g,
2506 const char *filename,
2507 const char *iface);
2508 This function is deprecated. In new code, use the "guestfs_add_drive"
2510 call instead.
2511 Deprecated functions will not be removed from the API, but the fact
2513 that they are deprecated indicates that there are problems with correct
2514 use of these functions.
2515 This is the same as "guestfs_add_drive" but it allows you to specify
2517 the QEMU interface emulation to use at run time.
2518 This function returns 0 on success or -1 on error.
2520 (Added in 1.0.84)
2522 guestfs_add_libvirt_dom
2524 int
2525 guestfs_add_libvirt_dom (guestfs_h *g,
2526 void * /* really virDomainPtr */ dom,
2527 ...);
2528 You may supply a list of optional arguments to this call. Use zero or
2530 more of the following pairs of parameters, and terminate the list with
2531 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2532 GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2534 GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2535 GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2536 GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2537 GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2538 GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2539 GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2540 This function adds the disk(s) attached to the libvirt domain "dom".
2542 It works by requesting the domain XML from libvirt, parsing it for
2543 disks, and calling "guestfs_add_drive_opts" on each one.
2544 In the C API we declare "void *dom", but really it has type
2546 "virDomainPtr dom". This is so we don't need <libvirt.h>.
2547 The number of disks added is returned. This operation is atomic: if an
2549 error is returned, then no disks are added.
2550 This function does some minimal checks to make sure the libvirt domain
2552 is not running (unless "readonly" is true). In a future version we
2553 will try to acquire the libvirt lock on each disk.
2554 Disks must be accessible locally. This often means that adding disks
2556 from a remote libvirt connection (see https://libvirt.org/remote.html)
2557 will fail unless those disks are accessible via the same device path
2558 locally too.
2559 The optional "live" flag controls whether this call will try to connect
2561 to a running virtual machine "guestfsd" process if it sees a suitable
2562 <channel> element in the libvirt XML definition. The default (if the
2563 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
2564 for more information.
2565 The optional "readonlydisk" parameter controls what we do for disks
2567 which are marked <readonly/> in the libvirt XML. See
2568 "guestfs_add_domain" for possible values.
2569 If present, the value of "logical_block_size" attribute of <blockio/>
2571 tag in libvirt XML will be passed as "blocksize" parameter to
2572 "guestfs_add_drive_opts".
2573 The other optional parameters are passed directly through to
2575 "guestfs_add_drive_opts".
2576 On error this function returns -1.
2578 (Added in 1.29.14)
2580 guestfs_add_libvirt_dom_va
2582 int
2583 guestfs_add_libvirt_dom_va (guestfs_h *g,
2584 void * /* really virDomainPtr */ dom,
2585 va_list args);
2586 This is the "va_list variant" of "guestfs_add_libvirt_dom".
2588 See "CALLS WITH OPTIONAL ARGUMENTS".
2590 guestfs_add_libvirt_dom_argv
2592 int
2593 guestfs_add_libvirt_dom_argv (guestfs_h *g,
2594 void * /* really virDomainPtr */ dom,
2595 const struct guestfs_add_libvirt_dom_argv *optargs);
2596 This is the "argv variant" of "guestfs_add_libvirt_dom".
2598 See "CALLS WITH OPTIONAL ARGUMENTS".
2600 guestfs_aug_clear
2602 int
2603 guestfs_aug_clear (guestfs_h *g,
2604 const char *augpath);
2605 Set the value associated with "path" to "NULL". This is the same as
2607 the augtool(1) "clear" command.
2608 This function returns 0 on success or -1 on error.
2610 (Added in 1.3.4)
2612 guestfs_aug_close
2614 int
2615 guestfs_aug_close (guestfs_h *g);
2616 Close the current Augeas handle and free up any resources used by it.
2618 After calling this, you have to call "guestfs_aug_init" again before
2619 you can use any other Augeas functions.
2620 This function returns 0 on success or -1 on error.
2622 (Added in 0.7)
2624 guestfs_aug_defnode
2626 struct guestfs_int_bool *
2627 guestfs_aug_defnode (guestfs_h *g,
2628 const char *name,
2629 const char *expr,
2630 const char *val);
2631 Defines a variable "name" whose value is the result of evaluating
2633 "expr".
2634 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2636 to calling "guestfs_aug_set" "expr", "val". "name" will be the nodeset
2637 containing that single node.
2638 On success this returns a pair containing the number of nodes in the
2640 nodeset, and a boolean flag if a node was created.
2641 This function returns a "struct guestfs_int_bool *", or NULL if there
2643 was an error. The caller must call "guestfs_free_int_bool" after use.
2644 (Added in 0.7)
2646 guestfs_aug_defvar
2648 int
2649 guestfs_aug_defvar (guestfs_h *g,
2650 const char *name,
2651 const char *expr);
2652 Defines an Augeas variable "name" whose value is the result of
2654 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2655 On success this returns the number of nodes in "expr", or 0 if "expr"
2657 evaluates to something which is not a nodeset.
2658 On error this function returns -1.
2660 (Added in 0.7)
2662 guestfs_aug_get
2664 char *
2665 guestfs_aug_get (guestfs_h *g,
2666 const char *augpath);
2667 Look up the value associated with "path". If "path" matches exactly
2669 one node, the "value" is returned.
2670 This function returns a string, or NULL on error. The caller must free
2672 the returned string after use.
2673 (Added in 0.7)
2675 guestfs_aug_init
2677 int
2678 guestfs_aug_init (guestfs_h *g,
2679 const char *root,
2680 int flags);
2681 Create a new Augeas handle for editing configuration files. If there
2683 was any previous Augeas handle associated with this guestfs session,
2684 then it is closed.
2685 You must call this before using any other "guestfs_aug_*" commands.
2687 "root" is the filesystem root. "root" must not be NULL, use / instead.
2689 The flags are the same as the flags defined in <augeas.h>, the logical
2691 or of the following integers:
2692 "AUG_SAVE_BACKUP" = 1
2694 Keep the original file with a ".augsave" extension.
2695 "AUG_SAVE_NEWFILE" = 2
2697 Save changes into a file with extension ".augnew", and do not
2698 overwrite original. Overrides "AUG_SAVE_BACKUP".
2699 "AUG_TYPE_CHECK" = 4
2701 Typecheck lenses.
2702 This option is only useful when debugging Augeas lenses. Use of
2704 this option may require additional memory for the libguestfs
2705 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2706 environment variable or call "guestfs_set_memsize".
2707 "AUG_NO_STDINC" = 8
2709 Do not use standard load path for modules.
2710 "AUG_SAVE_NOOP" = 16
2712 Make save a no-op, just record what would have been changed.
2713 "AUG_NO_LOAD" = 32
2715 Do not load the tree in "guestfs_aug_init".
2716 To close the handle, you can call "guestfs_aug_close".
2718 To find out more about Augeas, see http://augeas.net/.
2720 This function returns 0 on success or -1 on error.
2722 (Added in 0.7)
2724 guestfs_aug_insert
2726 int
2727 guestfs_aug_insert (guestfs_h *g,
2728 const char *augpath,
2729 const char *label,
2730 int before);
2731 Create a new sibling "label" for "path", inserting it into the tree
2733 before or after "path" (depending on the boolean flag "before").
2734 "path" must match exactly one existing node in the tree, and "label"
2736 must be a label, ie. not contain /, "*" or end with a bracketed index
2737 "[N]".
2738 This function returns 0 on success or -1 on error.
2740 (Added in 0.7)
2742 guestfs_aug_label
2744 char *
2745 guestfs_aug_label (guestfs_h *g,
2746 const char *augpath);
2747 The label (name of the last element) of the Augeas path expression
2749 "augpath" is returned. "augpath" must match exactly one node, else
2750 this function returns an error.
2751 This function returns a string, or NULL on error. The caller must free
2753 the returned string after use.
2754 (Added in 1.23.14)
2756 guestfs_aug_load
2758 int
2759 guestfs_aug_load (guestfs_h *g);
2760 Load files into the tree.
2762 See "aug_load" in the Augeas documentation for the full gory details.
2764 This function returns 0 on success or -1 on error.
2766 (Added in 0.7)
2768 guestfs_aug_ls
2770 char **
2771 guestfs_aug_ls (guestfs_h *g,
2772 const char *augpath);
2773 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2775 sorting the resulting nodes into alphabetical order.
2776 This function returns a NULL-terminated array of strings (like
2778 environ(3)), or NULL if there was an error. The caller must free the
2779 strings and the array after use.
2780 (Added in 0.8)
2782 guestfs_aug_match
2784 char **
2785 guestfs_aug_match (guestfs_h *g,
2786 const char *augpath);
2787 Returns a list of paths which match the path expression "path". The
2789 returned paths are sufficiently qualified so that they match exactly
2790 one node in the current tree.
2791 This function returns a NULL-terminated array of strings (like
2793 environ(3)), or NULL if there was an error. The caller must free the
2794 strings and the array after use.
2795 (Added in 0.7)
2797 guestfs_aug_mv
2799 int
2800 guestfs_aug_mv (guestfs_h *g,
2801 const char *src,
2802 const char *dest);
2803 Move the node "src" to "dest". "src" must match exactly one node.
2805 "dest" is overwritten if it exists.
2806 This function returns 0 on success or -1 on error.
2808 (Added in 0.7)
2810 guestfs_aug_rm
2812 int
2813 guestfs_aug_rm (guestfs_h *g,
2814 const char *augpath);
2815 Remove "path" and all of its children.
2817 On success this returns the number of entries which were removed.
2819 On error this function returns -1.
2821 (Added in 0.7)
2823 guestfs_aug_save
2825 int
2826 guestfs_aug_save (guestfs_h *g);
2827 This writes all pending changes to disk.
2829 The flags which were passed to "guestfs_aug_init" affect exactly how
2831 files are saved.
2832 This function returns 0 on success or -1 on error.
2834 (Added in 0.7)
2836 guestfs_aug_set
2838 int
2839 guestfs_aug_set (guestfs_h *g,
2840 const char *augpath,
2841 const char *val);
2842 Set the value associated with "augpath" to "val".
2844 In the Augeas API, it is possible to clear a node by setting the value
2846 to NULL. Due to an oversight in the libguestfs API you cannot do that
2847 with this call. Instead you must use the "guestfs_aug_clear" call.
2848 This function returns 0 on success or -1 on error.
2850 (Added in 0.7)
2852 guestfs_aug_setm
2854 int
2855 guestfs_aug_setm (guestfs_h *g,
2856 const char *base,
2857 const char *sub,
2858 const char *val);
2859 Change multiple Augeas nodes in a single operation. "base" is an
2861 expression matching multiple nodes. "sub" is a path expression
2862 relative to "base". All nodes matching "base" are found, and then for
2863 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2864 which case the "base" nodes are modified.
2865 This returns the number of nodes modified.
2867 On error this function returns -1.
2869 (Added in 1.23.14)
2871 guestfs_aug_transform
2873 int
2874 guestfs_aug_transform (guestfs_h *g,
2875 const char *lens,
2876 const char *file,
2877 ...);
2878 You may supply a list of optional arguments to this call. Use zero or
2880 more of the following pairs of parameters, and terminate the list with
2881 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2882 GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2884 Add an Augeas transformation for the specified "lens" so it can handle
2886 "file".
2887 If "remove" is true ("false" by default), then the transformation is
2889 removed.
2890 This function returns 0 on success or -1 on error.
2892 (Added in 1.35.2)
2894 guestfs_aug_transform_va
2896 int
2897 guestfs_aug_transform_va (guestfs_h *g,
2898 const char *lens,
2899 const char *file,
2900 va_list args);
2901 This is the "va_list variant" of "guestfs_aug_transform".
2903 See "CALLS WITH OPTIONAL ARGUMENTS".
2905 guestfs_aug_transform_argv
2907 int
2908 guestfs_aug_transform_argv (guestfs_h *g,
2909 const char *lens,
2910 const char *file,
2911 const struct guestfs_aug_transform_argv *optargs);
2912 This is the "argv variant" of "guestfs_aug_transform".
2914 See "CALLS WITH OPTIONAL ARGUMENTS".
2916 guestfs_available
2918 int
2919 guestfs_available (guestfs_h *g,
2920 char *const *groups);
2921 This command is used to check the availability of some groups of
2923 functionality in the appliance, which not all builds of the libguestfs
2924 appliance will be able to provide.
2925 The libguestfs groups, and the functions that those groups correspond
2927 to, are listed in "AVAILABILITY". You can also fetch this list at
2928 runtime by calling "guestfs_available_all_groups".
2929 The argument "groups" is a list of group names, eg: "["inotify",
2931 "augeas"]" would check for the availability of the Linux inotify
2932 functions and Augeas (configuration file editing) functions.
2933 The command returns no error if all requested groups are available.
2935 It fails with an error if one or more of the requested groups is
2937 unavailable in the appliance.
2938 If an unknown group name is included in the list of groups then an
2940 error is always returned.
2941 Notes:
2943 • "guestfs_feature_available" is the same as this call, but with a
2945 slightly simpler to use API: that call returns a boolean true/false
2946 instead of throwing an error.
2947 • You must call "guestfs_launch" before calling this function.
2949 The reason is because we don't know what groups are supported by
2951 the appliance/daemon until it is running and can be queried.
2952 • If a group of functions is available, this does not necessarily
2954 mean that they will work. You still have to check for errors when
2955 calling individual API functions even if they are available.
2956 • It is usually the job of distro packagers to build complete
2958 functionality into the libguestfs appliance. Upstream libguestfs,
2959 if built from source with all requirements satisfied, will support
2960 everything.
2961 • This call was added in version 1.0.80. In previous versions of
2963 libguestfs all you could do would be to speculatively execute a
2964 command to find out if the daemon implemented it. See also
2965 "guestfs_version".
2966 See also "guestfs_filesystem_available".
2968 This function returns 0 on success or -1 on error.
2970 (Added in 1.0.80)
2972 guestfs_available_all_groups
2974 char **
2975 guestfs_available_all_groups (guestfs_h *g);
2976 This command returns a list of all optional groups that this daemon
2978 knows about. Note this returns both supported and unsupported groups.
2979 To find out which ones the daemon can actually support you have to call
2980 "guestfs_available" / "guestfs_feature_available" on each member of the
2981 returned list.
2982 See also "guestfs_available", "guestfs_feature_available" and
2984 "AVAILABILITY".
2985 This function returns a NULL-terminated array of strings (like
2987 environ(3)), or NULL if there was an error. The caller must free the
2988 strings and the array after use.
2989 (Added in 1.3.15)
2991 guestfs_base64_in
2993 int
2994 guestfs_base64_in (guestfs_h *g,
2995 const char *base64file,
2996 const char *filename);
2997 This command uploads base64-encoded data from "base64file" to filename.
2999 This function returns 0 on success or -1 on error.
3001 (Added in 1.3.5)
3003 guestfs_base64_out
3005 int
3006 guestfs_base64_out (guestfs_h *g,
3007 const char *filename,
3008 const char *base64file);
3009 This command downloads the contents of filename, writing it out to
3011 local file "base64file" encoded as base64.
3012 This function returns 0 on success or -1 on error.
3014 (Added in 1.3.5)
3016 guestfs_blkdiscard
3018 int
3019 guestfs_blkdiscard (guestfs_h *g,
3020 const char *device);
3021 This discards all blocks on the block device "device", giving the free
3023 space back to the host.
3024 This operation requires support in libguestfs, the host filesystem,
3026 qemu and the host kernel. If this support isn't present it may give an
3027 error or even appear to run but do nothing. You must also set the
3028 "discard" attribute on the underlying drive (see
3029 "guestfs_add_drive_opts").
3030 This function returns 0 on success or -1 on error.
3032 This function depends on the feature "blkdiscard". See also
3034 "guestfs_feature_available".
3035 (Added in 1.25.44)
3037 guestfs_blkdiscardzeroes
3039 int
3040 guestfs_blkdiscardzeroes (guestfs_h *g,
3041 const char *device);
3042 This call returns true if blocks on "device" that have been discarded
3044 by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
3045 when read the next time.
3046 If it returns false, then it may be that discarded blocks are read as
3048 stale or random data.
3049 This function returns a C truth value on success or -1 on error.
3051 This function depends on the feature "blkdiscardzeroes". See also
3053 "guestfs_feature_available".
3054 (Added in 1.25.44)
3056 guestfs_blkid
3058 char **
3059 guestfs_blkid (guestfs_h *g,
3060 const char *device);
3061 This command returns block device attributes for "device". The
3063 following fields are usually present in the returned hash. Other fields
3064 may also be present.
3065 "UUID"
3067 The uuid of this device.
3068 "LABEL"
3070 The label of this device.
3071 "VERSION"
3073 The version of blkid command.
3074 "TYPE"
3076 The filesystem type or RAID of this device.
3077 "USAGE"
3079 The usage of this device, for example "filesystem" or "raid".
3080 This function returns a NULL-terminated array of strings, or NULL if
3082 there was an error. The array of strings will always have length
3083 "2n+1", where "n" keys and values alternate, followed by the trailing
3084 NULL entry. The caller must free the strings and the array after use.
3085 (Added in 1.15.9)
3087 guestfs_blockdev_flushbufs
3089 int
3090 guestfs_blockdev_flushbufs (guestfs_h *g,
3091 const char *device);
3092 This tells the kernel to flush internal buffers associated with
3094 "device".
3095 This uses the blockdev(8) command.
3097 This function returns 0 on success or -1 on error.
3099 (Added in 1.9.3)
3101 guestfs_blockdev_getbsz
3103 int
3104 guestfs_blockdev_getbsz (guestfs_h *g,
3105 const char *device);
3106 This returns the block size of a device.
3108 Note: this is different from both size in blocks and filesystem block
3110 size. Also this setting is not really used by anything. You should
3111 probably not use it for anything. Filesystems have their own idea
3112 about what block size to choose.
3113 This uses the blockdev(8) command.
3115 On error this function returns -1.
3117 (Added in 1.9.3)
3119 guestfs_blockdev_getro
3121 int
3122 guestfs_blockdev_getro (guestfs_h *g,
3123 const char *device);
3124 Returns a boolean indicating if the block device is read-only (true if
3126 read-only, false if not).
3127 This uses the blockdev(8) command.
3129 This function returns a C truth value on success or -1 on error.
3131 (Added in 1.9.3)
3133 guestfs_blockdev_getsize64
3135 int64_t
3136 guestfs_blockdev_getsize64 (guestfs_h *g,
3137 const char *device);
3138 This returns the size of the device in bytes.
3140 See also "guestfs_blockdev_getsz".
3142 This uses the blockdev(8) command.
3144 On error this function returns -1.
3146 (Added in 1.9.3)
3148 guestfs_blockdev_getss
3150 int
3151 guestfs_blockdev_getss (guestfs_h *g,
3152 const char *device);
3153 This returns the size of sectors on a block device. Usually 512, but
3155 can be larger for modern devices.
3156 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
3158 for that).
3159 This uses the blockdev(8) command.
3161 On error this function returns -1.
3163 (Added in 1.9.3)
3165 guestfs_blockdev_getsz
3167 int64_t
3168 guestfs_blockdev_getsz (guestfs_h *g,
3169 const char *device);
3170 This returns the size of the device in units of 512-byte sectors (even
3172 if the sectorsize isn't 512 bytes ... weird).
3173 See also "guestfs_blockdev_getss" for the real sector size of the
3175 device, and "guestfs_blockdev_getsize64" for the more useful size in
3176 bytes.
3177 This uses the blockdev(8) command.
3179 On error this function returns -1.
3181 (Added in 1.9.3)
3183 guestfs_blockdev_rereadpt
3185 int
3186 guestfs_blockdev_rereadpt (guestfs_h *g,
3187 const char *device);
3188 Reread the partition table on "device".
3190 This uses the blockdev(8) command.
3192 This function returns 0 on success or -1 on error.
3194 (Added in 1.9.3)
3196 guestfs_blockdev_setbsz
3198 int
3199 guestfs_blockdev_setbsz (guestfs_h *g,
3200 const char *device,
3201 int blocksize);
3202 This function is deprecated. There is no replacement. Consult the API
3204 documentation in guestfs(3) for further information.
3205 Deprecated functions will not be removed from the API, but the fact
3207 that they are deprecated indicates that there are problems with correct
3208 use of these functions.
3209 This call does nothing and has never done anything because of a bug in
3211 blockdev. Do not use it.
3212 If you need to set the filesystem block size, use the "blocksize"
3214 option of "guestfs_mkfs".
3215 This function returns 0 on success or -1 on error.
3217 (Added in 1.9.3)
3219 guestfs_blockdev_setra
3221 int
3222 guestfs_blockdev_setra (guestfs_h *g,
3223 const char *device,
3224 int sectors);
3225 Set readahead (in 512-byte sectors) for the device.
3227 This uses the blockdev(8) command.
3229 This function returns 0 on success or -1 on error.
3231 (Added in 1.29.10)
3233 guestfs_blockdev_setro
3235 int
3236 guestfs_blockdev_setro (guestfs_h *g,
3237 const char *device);
3238 Sets the block device named "device" to read-only.
3240 This uses the blockdev(8) command.
3242 This function returns 0 on success or -1 on error.
3244 (Added in 1.9.3)
3246 guestfs_blockdev_setrw
3248 int
3249 guestfs_blockdev_setrw (guestfs_h *g,
3250 const char *device);
3251 Sets the block device named "device" to read-write.
3253 This uses the blockdev(8) command.
3255 This function returns 0 on success or -1 on error.
3257 (Added in 1.9.3)
3259 guestfs_btrfs_balance_cancel
3261 int
3262 guestfs_btrfs_balance_cancel (guestfs_h *g,
3263 const char *path);
3264 Cancel a running balance on a btrfs filesystem.
3266 This function returns 0 on success or -1 on error.
3268 This function depends on the feature "btrfs". See also
3270 "guestfs_feature_available".
3271 (Added in 1.29.22)
3273 guestfs_btrfs_balance_pause
3275 int
3276 guestfs_btrfs_balance_pause (guestfs_h *g,
3277 const char *path);
3278 Pause a running balance on a btrfs filesystem.
3280 This function returns 0 on success or -1 on error.
3282 This function depends on the feature "btrfs". See also
3284 "guestfs_feature_available".
3285 (Added in 1.29.22)
3287 guestfs_btrfs_balance_resume
3289 int
3290 guestfs_btrfs_balance_resume (guestfs_h *g,
3291 const char *path);
3292 Resume a paused balance on a btrfs filesystem.
3294 This function returns 0 on success or -1 on error.
3296 This function depends on the feature "btrfs". See also
3298 "guestfs_feature_available".
3299 (Added in 1.29.22)
3301 guestfs_btrfs_balance_status
3303 struct guestfs_btrfsbalance *
3304 guestfs_btrfs_balance_status (guestfs_h *g,
3305 const char *path);
3306 Show the status of a running or paused balance on a btrfs filesystem.
3308 This function returns a "struct guestfs_btrfsbalance *", or NULL if
3310 there was an error. The caller must call "guestfs_free_btrfsbalance"
3311 after use.
3312 This function depends on the feature "btrfs". See also
3314 "guestfs_feature_available".
3315 (Added in 1.29.26)
3317 guestfs_btrfs_device_add
3319 int
3320 guestfs_btrfs_device_add (guestfs_h *g,
3321 char *const *devices,
3322 const char *fs);
3323 Add the list of device(s) in "devices" to the btrfs filesystem mounted
3325 at "fs". If "devices" is an empty list, this does nothing.
3326 This function returns 0 on success or -1 on error.
3328 This function depends on the feature "btrfs". See also
3330 "guestfs_feature_available".
3331 (Added in 1.17.35)
3333 guestfs_btrfs_device_delete
3335 int
3336 guestfs_btrfs_device_delete (guestfs_h *g,
3337 char *const *devices,
3338 const char *fs);
3339 Remove the "devices" from the btrfs filesystem mounted at "fs". If
3341 "devices" is an empty list, this does nothing.
3342 This function returns 0 on success or -1 on error.
3344 This function depends on the feature "btrfs". See also
3346 "guestfs_feature_available".
3347 (Added in 1.17.35)
3349 guestfs_btrfs_filesystem_balance
3351 int
3352 guestfs_btrfs_filesystem_balance (guestfs_h *g,
3353 const char *fs);
3354 Balance the chunks in the btrfs filesystem mounted at "fs" across the
3356 underlying devices.
3357 This function returns 0 on success or -1 on error.
3359 This function depends on the feature "btrfs". See also
3361 "guestfs_feature_available".
3362 (Added in 1.17.35)
3364 guestfs_btrfs_filesystem_defragment
3366 int
3367 guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3368 const char *path,
3369 ...);
3370 You may supply a list of optional arguments to this call. Use zero or
3372 more of the following pairs of parameters, and terminate the list with
3373 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3374 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3376 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3377 Defragment a file or directory on a btrfs filesystem. compress is one
3379 of zlib or lzo.
3380 This function returns 0 on success or -1 on error.
3382 This function depends on the feature "btrfs". See also
3384 "guestfs_feature_available".
3385 (Added in 1.29.22)
3387 guestfs_btrfs_filesystem_defragment_va
3389 int
3390 guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3391 const char *path,
3392 va_list args);
3393 This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3395 See "CALLS WITH OPTIONAL ARGUMENTS".
3397 guestfs_btrfs_filesystem_defragment_argv
3399 int
3400 guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3401 const char *path,
3402 const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3403 This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3405 See "CALLS WITH OPTIONAL ARGUMENTS".
3407 guestfs_btrfs_filesystem_resize
3409 int
3410 guestfs_btrfs_filesystem_resize (guestfs_h *g,
3411 const char *mountpoint,
3412 ...);
3413 You may supply a list of optional arguments to this call. Use zero or
3415 more of the following pairs of parameters, and terminate the list with
3416 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3417 GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3419 This command resizes a btrfs filesystem.
3421 Note that unlike other resize calls, the filesystem has to be mounted
3423 and the parameter is the mountpoint not the device (this is a
3424 requirement of btrfs itself).
3425 The optional parameters are:
3427 "size"
3429 The new size (in bytes) of the filesystem. If omitted, the
3430 filesystem is resized to the maximum size.
3431 See also btrfs(8).
3433 This function returns 0 on success or -1 on error.
3435 This function depends on the feature "btrfs". See also
3437 "guestfs_feature_available".
3438 (Added in 1.11.17)
3440 guestfs_btrfs_filesystem_resize_va
3442 int
3443 guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3444 const char *mountpoint,
3445 va_list args);
3446 This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3448 See "CALLS WITH OPTIONAL ARGUMENTS".
3450 guestfs_btrfs_filesystem_resize_argv
3452 int
3453 guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3454 const char *mountpoint,
3455 const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3456 This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3458 See "CALLS WITH OPTIONAL ARGUMENTS".
3460 guestfs_btrfs_filesystem_show
3462 char **
3463 guestfs_btrfs_filesystem_show (guestfs_h *g,
3464 const char *device);
3465 Show all the devices where the filesystems in "device" is spanned over.
3467 If not all the devices for the filesystems are present, then this
3469 function fails and the "errno" is set to "ENODEV".
3470 This function returns a NULL-terminated array of strings (like
3472 environ(3)), or NULL if there was an error. The caller must free the
3473 strings and the array after use.
3474 This function depends on the feature "btrfs". See also
3476 "guestfs_feature_available".
3477 (Added in 1.33.29)
3479 guestfs_btrfs_filesystem_sync
3481 int
3482 guestfs_btrfs_filesystem_sync (guestfs_h *g,
3483 const char *fs);
3484 Force sync on the btrfs filesystem mounted at "fs".
3486 This function returns 0 on success or -1 on error.
3488 This function depends on the feature "btrfs". See also
3490 "guestfs_feature_available".
3491 (Added in 1.17.35)
3493 guestfs_btrfs_fsck
3495 int
3496 guestfs_btrfs_fsck (guestfs_h *g,
3497 const char *device,
3498 ...);
3499 You may supply a list of optional arguments to this call. Use zero or
3501 more of the following pairs of parameters, and terminate the list with
3502 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3503 GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3505 GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3506 Used to check a btrfs filesystem, "device" is the device file where the
3508 filesystem is stored.
3509 This function returns 0 on success or -1 on error.
3511 This function depends on the feature "btrfs". See also
3513 "guestfs_feature_available".
3514 (Added in 1.17.43)
3516 guestfs_btrfs_fsck_va
3518 int
3519 guestfs_btrfs_fsck_va (guestfs_h *g,
3520 const char *device,
3521 va_list args);
3522 This is the "va_list variant" of "guestfs_btrfs_fsck".
3524 See "CALLS WITH OPTIONAL ARGUMENTS".
3526 guestfs_btrfs_fsck_argv
3528 int
3529 guestfs_btrfs_fsck_argv (guestfs_h *g,
3530 const char *device,
3531 const struct guestfs_btrfs_fsck_argv *optargs);
3532 This is the "argv variant" of "guestfs_btrfs_fsck".
3534 See "CALLS WITH OPTIONAL ARGUMENTS".
3536 guestfs_btrfs_image
3538 int
3539 guestfs_btrfs_image (guestfs_h *g,
3540 char *const *source,
3541 const char *image,
3542 ...);
3543 You may supply a list of optional arguments to this call. Use zero or
3545 more of the following pairs of parameters, and terminate the list with
3546 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3547 GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3549 This is used to create an image of a btrfs filesystem. All data will
3551 be zeroed, but metadata and the like is preserved.
3552 This function returns 0 on success or -1 on error.
3554 This function depends on the feature "btrfs". See also
3556 "guestfs_feature_available".
3557 (Added in 1.29.32)
3559 guestfs_btrfs_image_va
3561 int
3562 guestfs_btrfs_image_va (guestfs_h *g,
3563 char *const *source,
3564 const char *image,
3565 va_list args);
3566 This is the "va_list variant" of "guestfs_btrfs_image".
3568 See "CALLS WITH OPTIONAL ARGUMENTS".
3570 guestfs_btrfs_image_argv
3572 int
3573 guestfs_btrfs_image_argv (guestfs_h *g,
3574 char *const *source,
3575 const char *image,
3576 const struct guestfs_btrfs_image_argv *optargs);
3577 This is the "argv variant" of "guestfs_btrfs_image".
3579 See "CALLS WITH OPTIONAL ARGUMENTS".
3581 guestfs_btrfs_qgroup_assign
3583 int
3584 guestfs_btrfs_qgroup_assign (guestfs_h *g,
3585 const char *src,
3586 const char *dst,
3587 const char *path);
3588 Add qgroup "src" to parent qgroup "dst". This command can group several
3590 qgroups into a parent qgroup to share common limit.
3591 This function returns 0 on success or -1 on error.
3593 This function depends on the feature "btrfs". See also
3595 "guestfs_feature_available".
3596 (Added in 1.29.17)
3598 guestfs_btrfs_qgroup_create
3600 int
3601 guestfs_btrfs_qgroup_create (guestfs_h *g,
3602 const char *qgroupid,
3603 const char *subvolume);
3604 Create a quota group (qgroup) for subvolume at "subvolume".
3606 This function returns 0 on success or -1 on error.
3608 This function depends on the feature "btrfs". See also
3610 "guestfs_feature_available".
3611 (Added in 1.29.17)
3613 guestfs_btrfs_qgroup_destroy
3615 int
3616 guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3617 const char *qgroupid,
3618 const char *subvolume);
3619 Destroy a quota group.
3621 This function returns 0 on success or -1 on error.
3623 This function depends on the feature "btrfs". See also
3625 "guestfs_feature_available".
3626 (Added in 1.29.17)
3628 guestfs_btrfs_qgroup_limit
3630 int
3631 guestfs_btrfs_qgroup_limit (guestfs_h *g,
3632 const char *subvolume,
3633 int64_t size);
3634 Limit the size of the subvolume with path "subvolume".
3636 This function returns 0 on success or -1 on error.
3638 This function depends on the feature "btrfs". See also
3640 "guestfs_feature_available".
3641 (Added in 1.29.17)
3643 guestfs_btrfs_qgroup_remove
3645 int
3646 guestfs_btrfs_qgroup_remove (guestfs_h *g,
3647 const char *src,
3648 const char *dst,
3649 const char *path);
3650 Remove qgroup "src" from the parent qgroup "dst".
3652 This function returns 0 on success or -1 on error.
3654 This function depends on the feature "btrfs". See also
3656 "guestfs_feature_available".
3657 (Added in 1.29.17)
3659 guestfs_btrfs_qgroup_show
3661 struct guestfs_btrfsqgroup_list *
3662 guestfs_btrfs_qgroup_show (guestfs_h *g,
3663 const char *path);
3664 Show all subvolume quota groups in a btrfs filesystem, including their
3666 usages.
3667 This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3669 there was an error. The caller must call
3670 "guestfs_free_btrfsqgroup_list" after use.
3671 This function depends on the feature "btrfs". See also
3673 "guestfs_feature_available".
3674 (Added in 1.29.17)
3676 guestfs_btrfs_quota_enable
3678 int
3679 guestfs_btrfs_quota_enable (guestfs_h *g,
3680 const char *fs,
3681 int enable);
3682 Enable or disable subvolume quota support for filesystem which contains
3684 "path".
3685 This function returns 0 on success or -1 on error.
3687 This function depends on the feature "btrfs". See also
3689 "guestfs_feature_available".
3690 (Added in 1.29.17)
3692 guestfs_btrfs_quota_rescan
3694 int
3695 guestfs_btrfs_quota_rescan (guestfs_h *g,
3696 const char *fs);
3697 Trash all qgroup numbers and scan the metadata again with the current
3699 config.
3700 This function returns 0 on success or -1 on error.
3702 This function depends on the feature "btrfs". See also
3704 "guestfs_feature_available".
3705 (Added in 1.29.17)
3707 guestfs_btrfs_replace
3709 int
3710 guestfs_btrfs_replace (guestfs_h *g,
3711 const char *srcdev,
3712 const char *targetdev,
3713 const char *mntpoint);
3714 Replace device of a btrfs filesystem. On a live filesystem, duplicate
3716 the data to the target device which is currently stored on the source
3717 device. After completion of the operation, the source device is wiped
3718 out and removed from the filesystem.
3719 The "targetdev" needs to be same size or larger than the "srcdev".
3721 Devices which are currently mounted are never allowed to be used as the
3722 "targetdev".
3723 This function returns 0 on success or -1 on error.
3725 This function depends on the feature "btrfs". See also
3727 "guestfs_feature_available".
3728 (Added in 1.29.48)
3730 guestfs_btrfs_rescue_chunk_recover
3732 int
3733 guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3734 const char *device);
3735 Recover the chunk tree of btrfs filesystem by scanning the devices one
3737 by one.
3738 This function returns 0 on success or -1 on error.
3740 This function depends on the feature "btrfs". See also
3742 "guestfs_feature_available".
3743 (Added in 1.29.22)
3745 guestfs_btrfs_rescue_super_recover
3747 int
3748 guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3749 const char *device);
3750 Recover bad superblocks from good copies.
3752 This function returns 0 on success or -1 on error.
3754 This function depends on the feature "btrfs". See also
3756 "guestfs_feature_available".
3757 (Added in 1.29.22)
3759 guestfs_btrfs_scrub_cancel
3761 int
3762 guestfs_btrfs_scrub_cancel (guestfs_h *g,
3763 const char *path);
3764 Cancel a running scrub on a btrfs filesystem.
3766 This function returns 0 on success or -1 on error.
3768 This function depends on the feature "btrfs". See also
3770 "guestfs_feature_available".
3771 (Added in 1.29.22)
3773 guestfs_btrfs_scrub_resume
3775 int
3776 guestfs_btrfs_scrub_resume (guestfs_h *g,
3777 const char *path);
3778 Resume a previously canceled or interrupted scrub on a btrfs
3780 filesystem.
3781 This function returns 0 on success or -1 on error.
3783 This function depends on the feature "btrfs". See also
3785 "guestfs_feature_available".
3786 (Added in 1.29.22)
3788 guestfs_btrfs_scrub_start
3790 int
3791 guestfs_btrfs_scrub_start (guestfs_h *g,
3792 const char *path);
3793 Reads all the data and metadata on the filesystem, and uses checksums
3795 and the duplicate copies from RAID storage to identify and repair any
3796 corrupt data.
3797 This function returns 0 on success or -1 on error.
3799 This function depends on the feature "btrfs". See also
3801 "guestfs_feature_available".
3802 (Added in 1.29.22)
3804 guestfs_btrfs_scrub_status
3806 struct guestfs_btrfsscrub *
3807 guestfs_btrfs_scrub_status (guestfs_h *g,
3808 const char *path);
3809 Show status of running or finished scrub on a btrfs filesystem.
3811 This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3813 was an error. The caller must call "guestfs_free_btrfsscrub" after
3814 use.
3815 This function depends on the feature "btrfs". See also
3817 "guestfs_feature_available".
3818 (Added in 1.29.26)
3820 guestfs_btrfs_set_seeding
3822 int
3823 guestfs_btrfs_set_seeding (guestfs_h *g,
3824 const char *device,
3825 int seeding);
3826 Enable or disable the seeding feature of a device that contains a btrfs
3828 filesystem.
3829 This function returns 0 on success or -1 on error.
3831 This function depends on the feature "btrfs". See also
3833 "guestfs_feature_available".
3834 (Added in 1.17.43)
3836 guestfs_btrfs_subvolume_create
3838 int
3839 guestfs_btrfs_subvolume_create (guestfs_h *g,
3840 const char *dest);
3841 This function is provided for backwards compatibility with earlier
3843 versions of libguestfs. It simply calls
3844 "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3845 (Added in 1.17.35)
3847 guestfs_btrfs_subvolume_create_opts
3849 int
3850 guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3851 const char *dest,
3852 ...);
3853 You may supply a list of optional arguments to this call. Use zero or
3855 more of the following pairs of parameters, and terminate the list with
3856 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3857 GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3859 Create a btrfs subvolume. The "dest" argument is the destination
3861 directory and the name of the subvolume, in the form
3862 /path/to/dest/name. The optional parameter "qgroupid" represents the
3863 qgroup which the newly created subvolume will be added to.
3864 This function returns 0 on success or -1 on error.
3866 This function depends on the feature "btrfs". See also
3868 "guestfs_feature_available".
3869 (Added in 1.17.35)
3871 guestfs_btrfs_subvolume_create_opts_va
3873 int
3874 guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3875 const char *dest,
3876 va_list args);
3877 This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3879 See "CALLS WITH OPTIONAL ARGUMENTS".
3881 guestfs_btrfs_subvolume_create_opts_argv
3883 int
3884 guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3885 const char *dest,
3886 const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3887 This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3889 See "CALLS WITH OPTIONAL ARGUMENTS".
3891 guestfs_btrfs_subvolume_delete
3893 int
3894 guestfs_btrfs_subvolume_delete (guestfs_h *g,
3895 const char *subvolume);
3896 Delete the named btrfs subvolume or snapshot.
3898 This function returns 0 on success or -1 on error.
3900 This function depends on the feature "btrfs". See also
3902 "guestfs_feature_available".
3903 (Added in 1.17.35)
3905 guestfs_btrfs_subvolume_get_default
3907 int64_t
3908 guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3909 const char *fs);
3910 Get the default subvolume or snapshot of a filesystem mounted at
3912 "mountpoint".
3913 On error this function returns -1.
3915 This function depends on the feature "btrfs". See also
3917 "guestfs_feature_available".
3918 (Added in 1.29.17)
3920 guestfs_btrfs_subvolume_list
3922 struct guestfs_btrfssubvolume_list *
3923 guestfs_btrfs_subvolume_list (guestfs_h *g,
3924 const char *fs);
3925 List the btrfs snapshots and subvolumes of the btrfs filesystem which
3927 is mounted at "fs".
3928 This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3930 if there was an error. The caller must call
3931 "guestfs_free_btrfssubvolume_list" after use.
3932 This function depends on the feature "btrfs". See also
3934 "guestfs_feature_available".
3935 (Added in 1.17.35)
3937 guestfs_btrfs_subvolume_set_default
3939 int
3940 guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3941 int64_t id,
3942 const char *fs);
3943 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3945 default. See "guestfs_btrfs_subvolume_list" to get a list of
3946 subvolumes.
3947 This function returns 0 on success or -1 on error.
3949 This function depends on the feature "btrfs". See also
3951 "guestfs_feature_available".
3952 (Added in 1.17.35)
3954 guestfs_btrfs_subvolume_show
3956 char **
3957 guestfs_btrfs_subvolume_show (guestfs_h *g,
3958 const char *subvolume);
3959 Return detailed information of the subvolume.
3961 This function returns a NULL-terminated array of strings, or NULL if
3963 there was an error. The array of strings will always have length
3964 "2n+1", where "n" keys and values alternate, followed by the trailing
3965 NULL entry. The caller must free the strings and the array after use.
3966 This function depends on the feature "btrfs". See also
3968 "guestfs_feature_available".
3969 (Added in 1.29.17)
3971 guestfs_btrfs_subvolume_snapshot
3973 int
3974 guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3975 const char *source,
3976 const char *dest);
3977 This function is provided for backwards compatibility with earlier
3979 versions of libguestfs. It simply calls
3980 "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3981 (Added in 1.17.35)
3983 guestfs_btrfs_subvolume_snapshot_opts
3985 int
3986 guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3987 const char *source,
3988 const char *dest,
3989 ...);
3990 You may supply a list of optional arguments to this call. Use zero or
3992 more of the following pairs of parameters, and terminate the list with
3993 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3994 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3996 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3997 Create a snapshot of the btrfs subvolume "source". The "dest" argument
3999 is the destination directory and the name of the snapshot, in the form
4000 /path/to/dest/name. By default the newly created snapshot is writable,
4001 if the value of optional parameter "ro" is true, then a readonly
4002 snapshot is created. The optional parameter "qgroupid" represents the
4003 qgroup which the newly created snapshot will be added to.
4004 This function returns 0 on success or -1 on error.
4006 This function depends on the feature "btrfs". See also
4008 "guestfs_feature_available".
4009 (Added in 1.17.35)
4011 guestfs_btrfs_subvolume_snapshot_opts_va
4013 int
4014 guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
4015 const char *source,
4016 const char *dest,
4017 va_list args);
4018 This is the "va_list variant" of
4020 "guestfs_btrfs_subvolume_snapshot_opts".
4021 See "CALLS WITH OPTIONAL ARGUMENTS".
4023 guestfs_btrfs_subvolume_snapshot_opts_argv
4025 int
4026 guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
4027 const char *source,
4028 const char *dest,
4029 const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
4030 This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
4032 See "CALLS WITH OPTIONAL ARGUMENTS".
4034 guestfs_btrfstune_enable_extended_inode_refs
4036 int
4037 guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
4038 const char *device);
4039 This will Enable extended inode refs.
4041 This function returns 0 on success or -1 on error.
4043 This function depends on the feature "btrfs". See also
4045 "guestfs_feature_available".
4046 (Added in 1.29.29)
4048 guestfs_btrfstune_enable_skinny_metadata_extent_refs
4050 int
4051 guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
4052 const char *device);
4053 This enable skinny metadata extent refs.
4055 This function returns 0 on success or -1 on error.
4057 This function depends on the feature "btrfs". See also
4059 "guestfs_feature_available".
4060 (Added in 1.29.29)
4062 guestfs_btrfstune_seeding
4064 int
4065 guestfs_btrfstune_seeding (guestfs_h *g,
4066 const char *device,
4067 int seeding);
4068 Enable seeding of a btrfs device, this will force a fs readonly so that
4070 you can use it to build other filesystems.
4071 This function returns 0 on success or -1 on error.
4073 This function depends on the feature "btrfs". See also
4075 "guestfs_feature_available".
4076 (Added in 1.29.29)
4078 guestfs_c_pointer
4080 int64_t
4081 guestfs_c_pointer (guestfs_h *g);
4082 In non-C language bindings, this allows you to retrieve the underlying
4084 C pointer to the handle (ie. "guestfs_h *"). The purpose of this is to
4085 allow other libraries to interwork with libguestfs.
4086 On error this function returns -1.
4088 (Added in 1.29.17)
4090 guestfs_canonical_device_name
4092 char *
4093 guestfs_canonical_device_name (guestfs_h *g,
4094 const char *device);
4095 This utility function is useful when displaying device names to the
4097 user. It takes a number of irregular device names and returns them in
4098 a consistent format:
4099 /dev/hdX
4101 /dev/vdX
4102 These are returned as /dev/sdX. Note this works for device names
4103 and partition names. This is approximately the reverse of the
4104 algorithm described in "BLOCK DEVICE NAMING".
4105 /dev/mapper/VG-LV
4107 /dev/dm-N
4108 Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
4109 Other strings are returned unmodified.
4111 This function returns a string, or NULL on error. The caller must free
4113 the returned string after use.
4114 (Added in 1.19.7)
4116 guestfs_cap_get_file
4118 char *
4119 guestfs_cap_get_file (guestfs_h *g,
4120 const char *path);
4121 This function returns the Linux capabilities attached to "path". The
4123 capabilities set is returned in text form (see cap_to_text(3)).
4124 If no capabilities are attached to a file, an empty string is returned.
4126 This function returns a string, or NULL on error. The caller must free
4128 the returned string after use.
4129 This function depends on the feature "linuxcaps". See also
4131 "guestfs_feature_available".
4132 (Added in 1.19.63)
4134 guestfs_cap_set_file
4136 int
4137 guestfs_cap_set_file (guestfs_h *g,
4138 const char *path,
4139 const char *cap);
4140 This function sets the Linux capabilities attached to "path". The
4142 capabilities set "cap" should be passed in text form (see
4143 cap_from_text(3)).
4144 This function returns 0 on success or -1 on error.
4146 This function depends on the feature "linuxcaps". See also
4148 "guestfs_feature_available".
4149 (Added in 1.19.63)
4151 guestfs_case_sensitive_path
4153 char *
4154 guestfs_case_sensitive_path (guestfs_h *g,
4155 const char *path);
4156 This can be used to resolve case insensitive paths on a filesystem
4158 which is case sensitive. The use case is to resolve paths which you
4159 have read from Windows configuration files or the Windows Registry, to
4160 the true path.
4161 The command handles a peculiarity of the Linux ntfs-3g filesystem
4163 driver (and probably others), which is that although the underlying
4164 filesystem is case-insensitive, the driver exports the filesystem to
4165 Linux as case-sensitive.
4166 One consequence of this is that special directories such as C:\windows
4168 may appear as /WINDOWS or /windows (or other things) depending on the
4169 precise details of how they were created. In Windows itself this would
4170 not be a problem.
4171 Bug or feature? You decide:
4173 https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4174 "guestfs_case_sensitive_path" attempts to resolve the true case of each
4176 element in the path. It will return a resolved path if either the full
4177 path or its parent directory exists. If the parent directory exists but
4178 the full path does not, the case of the parent directory will be
4179 correctly resolved, and the remainder appended unmodified. For example,
4180 if the file "/Windows/System32/netkvm.sys" exists:
4181 "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4183 "Windows/System32/netkvm.sys"
4184 "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4186 "Windows/System32/NoSuchFile"
4187 "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4189 ERROR
4190 Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4192 cannot be used to check for the existence of a file.
4193 Note: This function does not handle drive names, backslashes etc.
4195 See also "guestfs_realpath".
4197 This function returns a string, or NULL on error. The caller must free
4199 the returned string after use.
4200 (Added in 1.0.75)
4202 guestfs_cat
4204 char *
4205 guestfs_cat (guestfs_h *g,
4206 const char *path);
4207 Return the contents of the file named "path".
4209 Because, in C, this function returns a "char *", there is no way to
4211 differentiate between a "\0" character in a file and end of string. To
4212 handle binary files, use the "guestfs_read_file" or "guestfs_download"
4213 functions.
4214 This function returns a string, or NULL on error. The caller must free
4216 the returned string after use.
4217 (Added in 0.4)
4219 guestfs_checksum
4221 char *
4222 guestfs_checksum (guestfs_h *g,
4223 const char *csumtype,
4224 const char *path);
4225 This call computes the MD5, SHAx or CRC checksum of the file named
4227 "path".
4228 The type of checksum to compute is given by the "csumtype" parameter
4230 which must have one of the following values:
4231 "crc"
4233 Compute the cyclic redundancy check (CRC) specified by POSIX for
4234 the "cksum" command.
4235 "md5"
4237 Compute the MD5 hash (using the md5sum(1) program).
4238 "sha1"
4240 Compute the SHA1 hash (using the sha1sum(1) program).
4241 "sha224"
4243 Compute the SHA224 hash (using the sha224sum(1) program).
4244 "sha256"
4246 Compute the SHA256 hash (using the sha256sum(1) program).
4247 "sha384"
4249 Compute the SHA384 hash (using the sha384sum(1) program).
4250 "sha512"
4252 Compute the SHA512 hash (using the sha512sum(1) program).
4253 The checksum is returned as a printable string.
4255 To get the checksum for a device, use "guestfs_checksum_device".
4257 To get the checksums for many files, use "guestfs_checksums_out".
4259 This function returns a string, or NULL on error. The caller must free
4261 the returned string after use.
4262 (Added in 1.0.2)
4264 guestfs_checksum_device
4266 char *
4267 guestfs_checksum_device (guestfs_h *g,
4268 const char *csumtype,
4269 const char *device);
4270 This call computes the MD5, SHAx or CRC checksum of the contents of the
4272 device named "device". For the types of checksums supported see the
4273 "guestfs_checksum" command.
4274 This function returns a string, or NULL on error. The caller must free
4276 the returned string after use.
4277 (Added in 1.3.2)
4279 guestfs_checksums_out
4281 int
4282 guestfs_checksums_out (guestfs_h *g,
4283 const char *csumtype,
4284 const char *directory,
4285 const char *sumsfile);
4286 This command computes the checksums of all regular files in directory
4288 and then emits a list of those checksums to the local output file
4289 "sumsfile".
4290 This can be used for verifying the integrity of a virtual machine.
4292 However to be properly secure you should pay attention to the output of
4293 the checksum command (it uses the ones from GNU coreutils). In
4294 particular when the filename is not printable, coreutils uses a special
4295 backslash syntax. For more information, see the GNU coreutils info
4296 file.
4297 This function returns 0 on success or -1 on error.
4299 (Added in 1.3.7)
4301 guestfs_chmod
4303 int
4304 guestfs_chmod (guestfs_h *g,
4305 int mode,
4306 const char *path);
4307 Change the mode (permissions) of "path" to "mode". Only numeric modes
4309 are supported.
4310 Note: When using this command from guestfish, "mode" by default would
4312 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4313 700.
4314 The mode actually set is affected by the umask.
4316 This function returns 0 on success or -1 on error.
4318 (Added in 0.8)
4320 guestfs_chown
4322 int
4323 guestfs_chown (guestfs_h *g,
4324 int owner,
4325 int group,
4326 const char *path);
4327 Change the file owner to "owner" and group to "group".
4329 Only numeric uid and gid are supported. If you want to use names, you
4331 will need to locate and parse the password file yourself (Augeas
4332 support makes this relatively easy).
4333 This function returns 0 on success or -1 on error.
4335 (Added in 0.8)
4337 guestfs_clear_backend_setting
4339 int
4340 guestfs_clear_backend_setting (guestfs_h *g,
4341 const char *name);
4342 If there is a backend setting string matching "name" or beginning with
4344 "name=", then that string is removed from the backend settings.
4345 This call returns the number of strings which were removed (which may
4347 be 0, 1 or greater than 1).
4348 See "BACKEND", "BACKEND SETTINGS".
4350 On error this function returns -1.
4352 (Added in 1.27.2)
4354 guestfs_command
4356 char *
4357 guestfs_command (guestfs_h *g,
4358 char *const *arguments);
4359 This call runs a command from the guest filesystem. The filesystem
4361 must be mounted, and must contain a compatible operating system (ie.
4362 something Linux, with the same or compatible processor architecture).
4363 The single parameter is an argv-style list of arguments. The first
4365 element is the name of the program to run. Subsequent elements are
4366 parameters. The list must be non-empty (ie. must contain a program
4367 name). Note that the command runs directly, and is not invoked via the
4368 shell (see "guestfs_sh").
4369 The return value is anything printed to stdout by the command.
4371 If the command returns a non-zero exit status, then this function
4373 returns an error message. The error message string is the content of
4374 stderr from the command.
4375 The $PATH environment variable will contain at least /usr/bin and /bin.
4377 If you require a program from another location, you should provide the
4378 full path in the first parameter.
4379 Shared libraries and data files required by the program must be
4381 available on filesystems which are mounted in the correct places. It
4382 is the caller’s responsibility to ensure all filesystems that are
4383 needed are mounted at the right locations.
4384 This function returns a string, or NULL on error. The caller must free
4386 the returned string after use.
4387 Because of the message protocol, there is a transfer limit of somewhere
4389 between 2MB and 4MB. See "PROTOCOL LIMITS".
4390 (Added in 1.9.1)
4392 guestfs_command_lines
4394 char **
4395 guestfs_command_lines (guestfs_h *g,
4396 char *const *arguments);
4397 This is the same as "guestfs_command", but splits the result into a
4399 list of lines.
4400 See also: "guestfs_sh_lines"
4402 This function returns a NULL-terminated array of strings (like
4404 environ(3)), or NULL if there was an error. The caller must free the
4405 strings and the array after use.
4406 Because of the message protocol, there is a transfer limit of somewhere
4408 between 2MB and 4MB. See "PROTOCOL LIMITS".
4409 (Added in 1.9.1)
4411 guestfs_compress_device_out
4413 int
4414 guestfs_compress_device_out (guestfs_h *g,
4415 const char *ctype,
4416 const char *device,
4417 const char *zdevice,
4418 ...);
4419 You may supply a list of optional arguments to this call. Use zero or
4421 more of the following pairs of parameters, and terminate the list with
4422 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4423 GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4425 This command compresses "device" and writes it out to the local file
4427 "zdevice".
4428 The "ctype" and optional "level" parameters have the same meaning as in
4430 "guestfs_compress_out".
4431 This function returns 0 on success or -1 on error.
4433 (Added in 1.13.15)
4435 guestfs_compress_device_out_va
4437 int
4438 guestfs_compress_device_out_va (guestfs_h *g,
4439 const char *ctype,
4440 const char *device,
4441 const char *zdevice,
4442 va_list args);
4443 This is the "va_list variant" of "guestfs_compress_device_out".
4445 See "CALLS WITH OPTIONAL ARGUMENTS".
4447 guestfs_compress_device_out_argv
4449 int
4450 guestfs_compress_device_out_argv (guestfs_h *g,
4451 const char *ctype,
4452 const char *device,
4453 const char *zdevice,
4454 const struct guestfs_compress_device_out_argv *optargs);
4455 This is the "argv variant" of "guestfs_compress_device_out".
4457 See "CALLS WITH OPTIONAL ARGUMENTS".
4459 guestfs_compress_out
4461 int
4462 guestfs_compress_out (guestfs_h *g,
4463 const char *ctype,
4464 const char *file,
4465 const char *zfile,
4466 ...);
4467 You may supply a list of optional arguments to this call. Use zero or
4469 more of the following pairs of parameters, and terminate the list with
4470 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4471 GUESTFS_COMPRESS_OUT_LEVEL, int level,
4473 This command compresses file and writes it out to the local file zfile.
4475 The compression program used is controlled by the "ctype" parameter.
4477 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4478 Some compression types may not be supported by particular builds of
4479 libguestfs, in which case you will get an error containing the
4480 substring "not supported".
4481 The optional "level" parameter controls compression level. The meaning
4483 and default for this parameter depends on the compression program being
4484 used.
4485 This function returns 0 on success or -1 on error.
4487 (Added in 1.13.15)
4489 guestfs_compress_out_va
4491 int
4492 guestfs_compress_out_va (guestfs_h *g,
4493 const char *ctype,
4494 const char *file,
4495 const char *zfile,
4496 va_list args);
4497 This is the "va_list variant" of "guestfs_compress_out".
4499 See "CALLS WITH OPTIONAL ARGUMENTS".
4501 guestfs_compress_out_argv
4503 int
4504 guestfs_compress_out_argv (guestfs_h *g,
4505 const char *ctype,
4506 const char *file,
4507 const char *zfile,
4508 const struct guestfs_compress_out_argv *optargs);
4509 This is the "argv variant" of "guestfs_compress_out".
4511 See "CALLS WITH OPTIONAL ARGUMENTS".
4513 guestfs_config
4515 int
4516 guestfs_config (guestfs_h *g,
4517 const char *hvparam,
4518 const char *hvvalue);
4519 This can be used to add arbitrary hypervisor parameters of the form
4521 -param value. Actually it’s not quite arbitrary - we prevent you from
4522 setting some parameters which would interfere with parameters that we
4523 use.
4524 The first character of "hvparam" string must be a "-" (dash).
4526 "hvvalue" can be NULL.
4528 This function returns 0 on success or -1 on error.
4530 (Added in 0.3)
4532 guestfs_copy_attributes
4534 int
4535 guestfs_copy_attributes (guestfs_h *g,
4536 const char *src,
4537 const char *dest,
4538 ...);
4539 You may supply a list of optional arguments to this call. Use zero or
4541 more of the following pairs of parameters, and terminate the list with
4542 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4543 GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4545 GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4546 GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4547 GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4548 Copy the attributes of a path (which can be a file or a directory) to
4550 another path.
4551 By default no attribute is copied, so make sure to specify any (or
4553 "all" to copy everything).
4554 The optional arguments specify which attributes can be copied:
4556 "mode"
4558 Copy part of the file mode from "source" to "destination". Only the
4559 UNIX permissions and the sticky/setuid/setgid bits can be copied.
4560 "xattributes"
4562 Copy the Linux extended attributes (xattrs) from "source" to
4563 "destination". This flag does nothing if the linuxxattrs feature
4564 is not available (see "guestfs_feature_available").
4565 "ownership"
4567 Copy the owner uid and the group gid of "source" to "destination".
4568 "all"
4570 Copy all the attributes from "source" to "destination". Enabling it
4571 enables all the other flags, if they are not specified already.
4572 This function returns 0 on success or -1 on error.
4574 (Added in 1.25.21)
4576 guestfs_copy_attributes_va
4578 int
4579 guestfs_copy_attributes_va (guestfs_h *g,
4580 const char *src,
4581 const char *dest,
4582 va_list args);
4583 This is the "va_list variant" of "guestfs_copy_attributes".
4585 See "CALLS WITH OPTIONAL ARGUMENTS".
4587 guestfs_copy_attributes_argv
4589 int
4590 guestfs_copy_attributes_argv (guestfs_h *g,
4591 const char *src,
4592 const char *dest,
4593 const struct guestfs_copy_attributes_argv *optargs);
4594 This is the "argv variant" of "guestfs_copy_attributes".
4596 See "CALLS WITH OPTIONAL ARGUMENTS".
4598 guestfs_copy_device_to_device
4600 int
4601 guestfs_copy_device_to_device (guestfs_h *g,
4602 const char *src,
4603 const char *dest,
4604 ...);
4605 You may supply a list of optional arguments to this call. Use zero or
4607 more of the following pairs of parameters, and terminate the list with
4608 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4609 GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4611 GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4612 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4613 GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4614 GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4615 The four calls "guestfs_copy_device_to_device",
4617 "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4618 "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4619 a destination (device|file).
4620 Partial copies can be made since you can specify optionally the source
4622 offset, destination offset and size to copy. These values are all
4623 specified in bytes. If not given, the offsets both default to zero,
4624 and the size defaults to copying as much as possible until we hit the
4625 end of the source.
4626 The source and destination may be the same object. However overlapping
4628 regions may not be copied correctly.
4629 If the destination is a file, it is created if required. If the
4631 destination file is not large enough, it is extended.
4632 If the destination is a file and the "append" flag is not set, then the
4634 destination file is truncated. If the "append" flag is set, then the
4635 copy appends to the destination file. The "append" flag currently
4636 cannot be set for devices.
4637 If the "sparse" flag is true then the call avoids writing blocks that
4639 contain only zeroes, which can help in some situations where the
4640 backing disk is thin-provisioned. Note that unless the target is
4641 already zeroed, using this option will result in incorrect copying.
4642 This function returns 0 on success or -1 on error.
4644 This long-running command can generate progress notification messages
4646 so that the caller can display a progress bar or indicator. To receive
4647 these messages, the caller must register a progress event callback.
4648 See "GUESTFS_EVENT_PROGRESS".
4649 (Added in 1.13.25)
4651 guestfs_copy_device_to_device_va
4653 int
4654 guestfs_copy_device_to_device_va (guestfs_h *g,
4655 const char *src,
4656 const char *dest,
4657 va_list args);
4658 This is the "va_list variant" of "guestfs_copy_device_to_device".
4660 See "CALLS WITH OPTIONAL ARGUMENTS".
4662 guestfs_copy_device_to_device_argv
4664 int
4665 guestfs_copy_device_to_device_argv (guestfs_h *g,
4666 const char *src,
4667 const char *dest,
4668 const struct guestfs_copy_device_to_device_argv *optargs);
4669 This is the "argv variant" of "guestfs_copy_device_to_device".
4671 See "CALLS WITH OPTIONAL ARGUMENTS".
4673 guestfs_copy_device_to_file
4675 int
4676 guestfs_copy_device_to_file (guestfs_h *g,
4677 const char *src,
4678 const char *dest,
4679 ...);
4680 You may supply a list of optional arguments to this call. Use zero or
4682 more of the following pairs of parameters, and terminate the list with
4683 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4684 GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4686 GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4687 GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4688 GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4689 GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4690 See "guestfs_copy_device_to_device" for a general overview of this
4692 call.
4693 This function returns 0 on success or -1 on error.
4695 This long-running command can generate progress notification messages
4697 so that the caller can display a progress bar or indicator. To receive
4698 these messages, the caller must register a progress event callback.
4699 See "GUESTFS_EVENT_PROGRESS".
4700 (Added in 1.13.25)
4702 guestfs_copy_device_to_file_va
4704 int
4705 guestfs_copy_device_to_file_va (guestfs_h *g,
4706 const char *src,
4707 const char *dest,
4708 va_list args);
4709 This is the "va_list variant" of "guestfs_copy_device_to_file".
4711 See "CALLS WITH OPTIONAL ARGUMENTS".
4713 guestfs_copy_device_to_file_argv
4715 int
4716 guestfs_copy_device_to_file_argv (guestfs_h *g,
4717 const char *src,
4718 const char *dest,
4719 const struct guestfs_copy_device_to_file_argv *optargs);
4720 This is the "argv variant" of "guestfs_copy_device_to_file".
4722 See "CALLS WITH OPTIONAL ARGUMENTS".
4724 guestfs_copy_file_to_device
4726 int
4727 guestfs_copy_file_to_device (guestfs_h *g,
4728 const char *src,
4729 const char *dest,
4730 ...);
4731 You may supply a list of optional arguments to this call. Use zero or
4733 more of the following pairs of parameters, and terminate the list with
4734 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4735 GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4737 GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4738 GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4739 GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4740 GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4741 See "guestfs_copy_device_to_device" for a general overview of this
4743 call.
4744 This function returns 0 on success or -1 on error.
4746 This long-running command can generate progress notification messages
4748 so that the caller can display a progress bar or indicator. To receive
4749 these messages, the caller must register a progress event callback.
4750 See "GUESTFS_EVENT_PROGRESS".
4751 (Added in 1.13.25)
4753 guestfs_copy_file_to_device_va
4755 int
4756 guestfs_copy_file_to_device_va (guestfs_h *g,
4757 const char *src,
4758 const char *dest,
4759 va_list args);
4760 This is the "va_list variant" of "guestfs_copy_file_to_device".
4762 See "CALLS WITH OPTIONAL ARGUMENTS".
4764 guestfs_copy_file_to_device_argv
4766 int
4767 guestfs_copy_file_to_device_argv (guestfs_h *g,
4768 const char *src,
4769 const char *dest,
4770 const struct guestfs_copy_file_to_device_argv *optargs);
4771 This is the "argv variant" of "guestfs_copy_file_to_device".
4773 See "CALLS WITH OPTIONAL ARGUMENTS".
4775 guestfs_copy_file_to_file
4777 int
4778 guestfs_copy_file_to_file (guestfs_h *g,
4779 const char *src,
4780 const char *dest,
4781 ...);
4782 You may supply a list of optional arguments to this call. Use zero or
4784 more of the following pairs of parameters, and terminate the list with
4785 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4786 GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4788 GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4789 GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4790 GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4791 GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4792 See "guestfs_copy_device_to_device" for a general overview of this
4794 call.
4795 This is not the function you want for copying files. This is for
4797 copying blocks within existing files. See "guestfs_cp", "guestfs_cp_a"
4798 and "guestfs_mv" for general file copying and moving functions.
4799 This function returns 0 on success or -1 on error.
4801 This long-running command can generate progress notification messages
4803 so that the caller can display a progress bar or indicator. To receive
4804 these messages, the caller must register a progress event callback.
4805 See "GUESTFS_EVENT_PROGRESS".
4806 (Added in 1.13.25)
4808 guestfs_copy_file_to_file_va
4810 int
4811 guestfs_copy_file_to_file_va (guestfs_h *g,
4812 const char *src,
4813 const char *dest,
4814 va_list args);
4815 This is the "va_list variant" of "guestfs_copy_file_to_file".
4817 See "CALLS WITH OPTIONAL ARGUMENTS".
4819 guestfs_copy_file_to_file_argv
4821 int
4822 guestfs_copy_file_to_file_argv (guestfs_h *g,
4823 const char *src,
4824 const char *dest,
4825 const struct guestfs_copy_file_to_file_argv *optargs);
4826 This is the "argv variant" of "guestfs_copy_file_to_file".
4828 See "CALLS WITH OPTIONAL ARGUMENTS".
4830 guestfs_copy_in
4832 int
4833 guestfs_copy_in (guestfs_h *g,
4834 const char *localpath,
4835 const char *remotedir);
4836 "guestfs_copy_in" copies local files or directories recursively into
4838 the disk image, placing them in the directory called "remotedir" (which
4839 must exist).
4840 Wildcards cannot be used.
4842 This function returns 0 on success or -1 on error.
4844 (Added in 1.29.24)
4846 guestfs_copy_out
4848 int
4849 guestfs_copy_out (guestfs_h *g,
4850 const char *remotepath,
4851 const char *localdir);
4852 "guestfs_copy_out" copies remote files or directories recursively out
4854 of the disk image, placing them on the host disk in a local directory
4855 called "localdir" (which must exist).
4856 To download to the current directory, use "." as in:
4858 C<guestfs_copy_out> /home .
4860 Wildcards cannot be used.
4862 This function returns 0 on success or -1 on error.
4864 (Added in 1.29.24)
4866 guestfs_copy_size
4868 int
4869 guestfs_copy_size (guestfs_h *g,
4870 const char *src,
4871 const char *dest,
4872 int64_t size);
4873 This function is deprecated. In new code, use the
4875 "guestfs_copy_device_to_device" call instead.
4876 Deprecated functions will not be removed from the API, but the fact
4878 that they are deprecated indicates that there are problems with correct
4879 use of these functions.
4880 This command copies exactly "size" bytes from one source device or file
4882 "src" to another destination device or file "dest".
4883 Note this will fail if the source is too short or if the destination is
4885 not large enough.
4886 This function returns 0 on success or -1 on error.
4888 This long-running command can generate progress notification messages
4890 so that the caller can display a progress bar or indicator. To receive
4891 these messages, the caller must register a progress event callback.
4892 See "GUESTFS_EVENT_PROGRESS".
4893 (Added in 1.0.87)
4895 guestfs_cp
4897 int
4898 guestfs_cp (guestfs_h *g,
4899 const char *src,
4900 const char *dest);
4901 This copies a file from "src" to "dest" where "dest" is either a
4903 destination filename or destination directory.
4904 This function returns 0 on success or -1 on error.
4906 (Added in 1.0.18)
4908 guestfs_cp_a
4910 int
4911 guestfs_cp_a (guestfs_h *g,
4912 const char *src,
4913 const char *dest);
4914 This copies a file or directory from "src" to "dest" recursively using
4916 the "cp -a" command.
4917 This function returns 0 on success or -1 on error.
4919 (Added in 1.0.18)
4921 guestfs_cp_r
4923 int
4924 guestfs_cp_r (guestfs_h *g,
4925 const char *src,
4926 const char *dest);
4927 This copies a file or directory from "src" to "dest" recursively using
4929 the "cp -rP" command.
4930 Most users should use "guestfs_cp_a" instead. This command is useful
4932 when you don't want to preserve permissions, because the target
4933 filesystem does not support it (primarily when writing to DOS FAT
4934 filesystems).
4935 This function returns 0 on success or -1 on error.
4937 (Added in 1.21.38)
4939 guestfs_cpio_out
4941 int
4942 guestfs_cpio_out (guestfs_h *g,
4943 const char *directory,
4944 const char *cpiofile,
4945 ...);
4946 You may supply a list of optional arguments to this call. Use zero or
4948 more of the following pairs of parameters, and terminate the list with
4949 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4950 GUESTFS_CPIO_OUT_FORMAT, const char *format,
4952 This command packs the contents of directory and downloads it to local
4954 file "cpiofile".
4955 The optional "format" parameter can be used to select the format. Only
4957 the following formats are currently permitted:
4958 "newc"
4960 New (SVR4) portable format. This format happens to be compatible
4961 with the cpio-like format used by the Linux kernel for initramfs.
4962 This is the default format.
4964 "crc"
4966 New (SVR4) portable format with a checksum.
4967 This function returns 0 on success or -1 on error.
4969 (Added in 1.27.9)
4971 guestfs_cpio_out_va
4973 int
4974 guestfs_cpio_out_va (guestfs_h *g,
4975 const char *directory,
4976 const char *cpiofile,
4977 va_list args);
4978 This is the "va_list variant" of "guestfs_cpio_out".
4980 See "CALLS WITH OPTIONAL ARGUMENTS".
4982 guestfs_cpio_out_argv
4984 int
4985 guestfs_cpio_out_argv (guestfs_h *g,
4986 const char *directory,
4987 const char *cpiofile,
4988 const struct guestfs_cpio_out_argv *optargs);
4989 This is the "argv variant" of "guestfs_cpio_out".
4991 See "CALLS WITH OPTIONAL ARGUMENTS".
4993 guestfs_cryptsetup_close
4995 int
4996 guestfs_cryptsetup_close (guestfs_h *g,
4997 const char *device);
4998 This closes an encrypted device that was created earlier by
5000 "guestfs_cryptsetup_open". The "device" parameter must be the name of
5001 the mapping device (ie. /dev/mapper/mapname) and not the name of the
5002 underlying block device.
5003 This function returns 0 on success or -1 on error.
5005 This function depends on the feature "luks". See also
5007 "guestfs_feature_available".
5008 (Added in 1.43.2)
5010 guestfs_cryptsetup_open
5012 int
5013 guestfs_cryptsetup_open (guestfs_h *g,
5014 const char *device,
5015 const char *key,
5016 const char *mapname,
5017 ...);
5018 You may supply a list of optional arguments to this call. Use zero or
5020 more of the following pairs of parameters, and terminate the list with
5021 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5022 GUESTFS_CRYPTSETUP_OPEN_READONLY, int readonly,
5024 GUESTFS_CRYPTSETUP_OPEN_CRYPTTYPE, const char *crypttype,
5025 This command opens a block device which has been encrypted according to
5027 the Linux Unified Key Setup (LUKS) standard, Windows BitLocker, or some
5028 other types.
5029 "device" is the encrypted block device or partition.
5031 The caller must supply one of the keys associated with the encrypted
5033 block device, in the "key" parameter.
5034 This creates a new block device called /dev/mapper/mapname. Reads and
5036 writes to this block device are decrypted from and encrypted to the
5037 underlying "device" respectively.
5038 "mapname" cannot be "control" because that name is reserved by device-
5040 mapper.
5041 If the optional "crypttype" parameter is not present then libguestfs
5043 tries to guess the correct type (for example LUKS or BitLocker).
5044 However you can override this by specifying one of the following types:
5045 "luks"
5047 A Linux LUKS device.
5048 "bitlk"
5050 A Windows BitLocker device.
5051 The optional "readonly" flag, if set to true, creates a read-only
5053 mapping.
5054 If this block device contains LVM volume groups, then calling
5056 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
5057 visible.
5058 Use "guestfs_list_dm_devices" to list all device mapper devices.
5060 This function returns 0 on success or -1 on error.
5062 This function takes a key or passphrase parameter which could contain
5064 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
5065 information.
5066 This function depends on the feature "luks". See also
5068 "guestfs_feature_available".
5069 (Added in 1.43.2)
5071 guestfs_cryptsetup_open_va
5073 int
5074 guestfs_cryptsetup_open_va (guestfs_h *g,
5075 const char *device,
5076 const char *key,
5077 const char *mapname,
5078 va_list args);
5079 This is the "va_list variant" of "guestfs_cryptsetup_open".
5081 See "CALLS WITH OPTIONAL ARGUMENTS".
5083 guestfs_cryptsetup_open_argv
5085 int
5086 guestfs_cryptsetup_open_argv (guestfs_h *g,
5087 const char *device,
5088 const char *key,
5089 const char *mapname,
5090 const struct guestfs_cryptsetup_open_argv *optargs);
5091 This is the "argv variant" of "guestfs_cryptsetup_open".
5093 See "CALLS WITH OPTIONAL ARGUMENTS".
5095 guestfs_dd
5097 int
5098 guestfs_dd (guestfs_h *g,
5099 const char *src,
5100 const char *dest);
5101 This function is deprecated. In new code, use the
5103 "guestfs_copy_device_to_device" call instead.
5104 Deprecated functions will not be removed from the API, but the fact
5106 that they are deprecated indicates that there are problems with correct
5107 use of these functions.
5108 This command copies from one source device or file "src" to another
5110 destination device or file "dest". Normally you would use this to copy
5111 to or from a device or partition, for example to duplicate a
5112 filesystem.
5113 If the destination is a device, it must be as large or larger than the
5115 source file or device, otherwise the copy will fail. This command
5116 cannot do partial copies (see "guestfs_copy_device_to_device").
5117 This function returns 0 on success or -1 on error.
5119 (Added in 1.0.80)
5121 guestfs_device_index
5123 int
5124 guestfs_device_index (guestfs_h *g,
5125 const char *device);
5126 This function takes a device name (eg. "/dev/sdb") and returns the
5128 index of the device in the list of devices.
5129 Index numbers start from 0. The named device must exist, for example
5131 as a string returned from "guestfs_list_devices".
5132 See also "guestfs_list_devices", "guestfs_part_to_dev".
5134 On error this function returns -1.
5136 (Added in 1.19.7)
5138 guestfs_df
5140 char *
5141 guestfs_df (guestfs_h *g);
5142 This command runs the df(1) command to report disk space used.
5144 This command is mostly useful for interactive sessions. It is not
5146 intended that you try to parse the output string. Use
5147 "guestfs_statvfs" from programs.
5148 This function returns a string, or NULL on error. The caller must free
5150 the returned string after use.
5151 (Added in 1.0.54)
5153 guestfs_df_h
5155 char *
5156 guestfs_df_h (guestfs_h *g);
5157 This command runs the "df -h" command to report disk space used in
5159 human-readable format.
5160 This command is mostly useful for interactive sessions. It is not
5162 intended that you try to parse the output string. Use
5163 "guestfs_statvfs" from programs.
5164 This function returns a string, or NULL on error. The caller must free
5166 the returned string after use.
5167 (Added in 1.0.54)
5169 guestfs_disk_create
5171 int
5172 guestfs_disk_create (guestfs_h *g,
5173 const char *filename,
5174 const char *format,
5175 int64_t size,
5176 ...);
5177 You may supply a list of optional arguments to this call. Use zero or
5179 more of the following pairs of parameters, and terminate the list with
5180 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5181 GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
5183 GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
5184 GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
5185 GUESTFS_DISK_CREATE_COMPAT, const char *compat,
5186 GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
5187 Create a blank disk image called filename (a host file) with format
5189 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
5190 If used with the optional "backingfile" parameter, then a snapshot is
5192 created on top of the backing file. In this case, "size" must be
5193 passed as "-1". The size of the snapshot is the same as the size of
5194 the backing file, which is discovered automatically. You are
5195 encouraged to also pass "backingformat" to describe the format of
5196 "backingfile".
5197 If filename refers to a block device, then the device is formatted.
5199 The "size" is ignored since block devices have an intrinsic size.
5200 The other optional parameters are:
5202 "preallocation"
5204 If format is "raw", then this can be either "off" (or "sparse") or
5205 "full" to create a sparse or fully allocated file respectively.
5206 The default is "off".
5207 If format is "qcow2", then this can be "off" (or "sparse"),
5209 "metadata" or "full". Preallocating metadata can be faster when
5210 doing lots of writes, but uses more space. The default is "off".
5211 "compat"
5213 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5214 supported by qemu ≥ 1.1.
5215 "clustersize"
5217 "qcow2" only: Change the qcow2 cluster size. The default is 65536
5218 (bytes) and this setting may be any power of two between 512 and
5219 2097152.
5220 Note that this call does not add the new disk to the handle. You may
5222 need to call "guestfs_add_drive_opts" separately.
5223 This function returns 0 on success or -1 on error.
5225 (Added in 1.25.31)
5227 guestfs_disk_create_va
5229 int
5230 guestfs_disk_create_va (guestfs_h *g,
5231 const char *filename,
5232 const char *format,
5233 int64_t size,
5234 va_list args);
5235 This is the "va_list variant" of "guestfs_disk_create".
5237 See "CALLS WITH OPTIONAL ARGUMENTS".
5239 guestfs_disk_create_argv
5241 int
5242 guestfs_disk_create_argv (guestfs_h *g,
5243 const char *filename,
5244 const char *format,
5245 int64_t size,
5246 const struct guestfs_disk_create_argv *optargs);
5247 This is the "argv variant" of "guestfs_disk_create".
5249 See "CALLS WITH OPTIONAL ARGUMENTS".
5251 guestfs_disk_format
5253 char *
5254 guestfs_disk_format (guestfs_h *g,
5255 const char *filename);
5256 Detect and return the format of the disk image called filename.
5258 filename can also be a host device, etc. If the format of the image
5259 could not be detected, then "unknown" is returned.
5260 Note that detecting the disk format can be insecure under some
5262 circumstances. See "CVE-2010-3851".
5263 See also: "DISK IMAGE FORMATS"
5265 This function returns a string, or NULL on error. The caller must free
5267 the returned string after use.
5268 (Added in 1.19.38)
5270 guestfs_disk_has_backing_file
5272 int
5273 guestfs_disk_has_backing_file (guestfs_h *g,
5274 const char *filename);
5275 Detect and return whether the disk image filename has a backing file.
5277 Note that detecting disk features can be insecure under some
5279 circumstances. See "CVE-2010-3851".
5280 This function returns a C truth value on success or -1 on error.
5282 (Added in 1.19.39)
5284 guestfs_disk_virtual_size
5286 int64_t
5287 guestfs_disk_virtual_size (guestfs_h *g,
5288 const char *filename);
5289 Detect and return the virtual size in bytes of the disk image called
5291 filename.
5292 Note that detecting disk features can be insecure under some
5294 circumstances. See "CVE-2010-3851".
5295 On error this function returns -1.
5297 (Added in 1.19.39)
5299 guestfs_dmesg
5301 char *
5302 guestfs_dmesg (guestfs_h *g);
5303 This returns the kernel messages (dmesg(1) output) from the guest
5305 kernel. This is sometimes useful for extended debugging of problems.
5306 Another way to get the same information is to enable verbose messages
5308 with "guestfs_set_verbose" or by setting the environment variable
5309 "LIBGUESTFS_DEBUG=1" before running the program.
5310 This function returns a string, or NULL on error. The caller must free
5312 the returned string after use.
5313 (Added in 1.0.18)
5315 guestfs_download
5317 int
5318 guestfs_download (guestfs_h *g,
5319 const char *remotefilename,
5320 const char *filename);
5321 Download file remotefilename and save it as filename on the local
5323 machine.
5324 filename can also be a named pipe.
5326 See also "guestfs_upload", "guestfs_cat".
5328 This function returns 0 on success or -1 on error.
5330 This long-running command can generate progress notification messages
5332 so that the caller can display a progress bar or indicator. To receive
5333 these messages, the caller must register a progress event callback.
5334 See "GUESTFS_EVENT_PROGRESS".
5335 (Added in 1.0.2)
5337 guestfs_download_blocks
5339 int
5340 guestfs_download_blocks (guestfs_h *g,
5341 const char *device,
5342 int64_t start,
5343 int64_t stop,
5344 const char *filename,
5345 ...);
5346 You may supply a list of optional arguments to this call. Use zero or
5348 more of the following pairs of parameters, and terminate the list with
5349 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5350 GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5352 Download the data units from start address to stop from the disk
5354 partition (eg. /dev/sda1) and save them as filename on the local
5355 machine.
5356 The use of this API on sparse disk image formats such as QCOW, may
5358 result in large zero-filled files downloaded on the host.
5359 The size of a data unit varies across filesystem implementations. On
5361 NTFS filesystems data units are referred as clusters while on ExtX ones
5362 they are referred as fragments.
5363 If the optional "unallocated" flag is true (default is false), only the
5365 unallocated blocks will be extracted. This is useful to detect hidden
5366 data or to retrieve deleted files which data units have not been
5367 overwritten yet.
5368 This function returns 0 on success or -1 on error.
5370 This long-running command can generate progress notification messages
5372 so that the caller can display a progress bar or indicator. To receive
5373 these messages, the caller must register a progress event callback.
5374 See "GUESTFS_EVENT_PROGRESS".
5375 This function depends on the feature "sleuthkit". See also
5377 "guestfs_feature_available".
5378 (Added in 1.33.45)
5380 guestfs_download_blocks_va
5382 int
5383 guestfs_download_blocks_va (guestfs_h *g,
5384 const char *device,
5385 int64_t start,
5386 int64_t stop,
5387 const char *filename,
5388 va_list args);
5389 This is the "va_list variant" of "guestfs_download_blocks".
5391 See "CALLS WITH OPTIONAL ARGUMENTS".
5393 guestfs_download_blocks_argv
5395 int
5396 guestfs_download_blocks_argv (guestfs_h *g,
5397 const char *device,
5398 int64_t start,
5399 int64_t stop,
5400 const char *filename,
5401 const struct guestfs_download_blocks_argv *optargs);
5402 This is the "argv variant" of "guestfs_download_blocks".
5404 See "CALLS WITH OPTIONAL ARGUMENTS".
5406 guestfs_download_inode
5408 int
5409 guestfs_download_inode (guestfs_h *g,
5410 const char *device,
5411 int64_t inode,
5412 const char *filename);
5413 Download a file given its inode from the disk partition (eg. /dev/sda1)
5415 and save it as filename on the local machine.
5416 It is not required to mount the disk to run this command.
5418 The command is capable of downloading deleted or inaccessible files.
5420 This function returns 0 on success or -1 on error.
5422 This long-running command can generate progress notification messages
5424 so that the caller can display a progress bar or indicator. To receive
5425 these messages, the caller must register a progress event callback.
5426 See "GUESTFS_EVENT_PROGRESS".
5427 This function depends on the feature "sleuthkit". See also
5429 "guestfs_feature_available".
5430 (Added in 1.33.14)
5432 guestfs_download_offset
5434 int
5435 guestfs_download_offset (guestfs_h *g,
5436 const char *remotefilename,
5437 const char *filename,
5438 int64_t offset,
5439 int64_t size);
5440 Download file remotefilename and save it as filename on the local
5442 machine.
5443 remotefilename is read for "size" bytes starting at "offset" (this
5445 region must be within the file or device).
5446 Note that there is no limit on the amount of data that can be
5448 downloaded with this call, unlike with "guestfs_pread", and this call
5449 always reads the full amount unless an error occurs.
5450 See also "guestfs_download", "guestfs_pread".
5452 This function returns 0 on success or -1 on error.
5454 This long-running command can generate progress notification messages
5456 so that the caller can display a progress bar or indicator. To receive
5457 these messages, the caller must register a progress event callback.
5458 See "GUESTFS_EVENT_PROGRESS".
5459 (Added in 1.5.17)
5461 guestfs_drop_caches
5463 int
5464 guestfs_drop_caches (guestfs_h *g,
5465 int whattodrop);
5466 This instructs the guest kernel to drop its page cache, and/or dentries
5468 and inode caches. The parameter "whattodrop" tells the kernel what
5469 precisely to drop, see https://linux-mm.org/Drop_Caches
5470 Setting "whattodrop" to 3 should drop everything.
5472 This automatically calls sync(2) before the operation, so that the
5474 maximum guest memory is freed.
5475 This function returns 0 on success or -1 on error.
5477 (Added in 1.0.18)
5479 guestfs_du
5481 int64_t
5482 guestfs_du (guestfs_h *g,
5483 const char *path);
5484 This command runs the "du -s" command to estimate file space usage for
5486 "path".
5487 "path" can be a file or a directory. If "path" is a directory then the
5489 estimate includes the contents of the directory and all subdirectories
5490 (recursively).
5491 The result is the estimated size in kilobytes (ie. units of 1024
5493 bytes).
5494 On error this function returns -1.
5496 This long-running command can generate progress notification messages
5498 so that the caller can display a progress bar or indicator. To receive
5499 these messages, the caller must register a progress event callback.
5500 See "GUESTFS_EVENT_PROGRESS".
5501 (Added in 1.0.54)
5503 guestfs_e2fsck
5505 int
5506 guestfs_e2fsck (guestfs_h *g,
5507 const char *device,
5508 ...);
5509 You may supply a list of optional arguments to this call. Use zero or
5511 more of the following pairs of parameters, and terminate the list with
5512 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5513 GUESTFS_E2FSCK_CORRECT, int correct,
5515 GUESTFS_E2FSCK_FORCEALL, int forceall,
5516 This runs the ext2/ext3 filesystem checker on "device". It can take
5518 the following optional arguments:
5519 "correct"
5521 Automatically repair the file system. This option will cause e2fsck
5522 to automatically fix any filesystem problems that can be safely
5523 fixed without human intervention.
5524 This option may not be specified at the same time as the "forceall"
5526 option.
5527 "forceall"
5529 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5530 used non-interactively.
5531 This option may not be specified at the same time as the "correct"
5533 option.
5534 This function returns 0 on success or -1 on error.
5536 (Added in 1.15.17)
5538 guestfs_e2fsck_va
5540 int
5541 guestfs_e2fsck_va (guestfs_h *g,
5542 const char *device,
5543 va_list args);
5544 This is the "va_list variant" of "guestfs_e2fsck".
5546 See "CALLS WITH OPTIONAL ARGUMENTS".
5548 guestfs_e2fsck_argv
5550 int
5551 guestfs_e2fsck_argv (guestfs_h *g,
5552 const char *device,
5553 const struct guestfs_e2fsck_argv *optargs);
5554 This is the "argv variant" of "guestfs_e2fsck".
5556 See "CALLS WITH OPTIONAL ARGUMENTS".
5558 guestfs_e2fsck_f
5560 int
5561 guestfs_e2fsck_f (guestfs_h *g,
5562 const char *device);
5563 This function is deprecated. In new code, use the "guestfs_e2fsck"
5565 call instead.
5566 Deprecated functions will not be removed from the API, but the fact
5568 that they are deprecated indicates that there are problems with correct
5569 use of these functions.
5570 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5572 checker on "device", noninteractively (-p), even if the filesystem
5573 appears to be clean (-f).
5574 This function returns 0 on success or -1 on error.
5576 (Added in 1.0.29)
5578 guestfs_echo_daemon
5580 char *
5581 guestfs_echo_daemon (guestfs_h *g,
5582 char *const *words);
5583 This command concatenates the list of "words" passed with single spaces
5585 between them and returns the resulting string.
5586 You can use this command to test the connection through to the daemon.
5588 See also "guestfs_ping_daemon".
5590 This function returns a string, or NULL on error. The caller must free
5592 the returned string after use.
5593 (Added in 1.0.69)
5595 guestfs_egrep
5597 char **
5598 guestfs_egrep (guestfs_h *g,
5599 const char *regex,
5600 const char *path);
5601 This function is deprecated. In new code, use the "guestfs_grep" call
5603 instead.
5604 Deprecated functions will not be removed from the API, but the fact
5606 that they are deprecated indicates that there are problems with correct
5607 use of these functions.
5608 This calls the external egrep(1) program and returns the matching
5610 lines.
5611 This function returns a NULL-terminated array of strings (like
5613 environ(3)), or NULL if there was an error. The caller must free the
5614 strings and the array after use.
5615 Because of the message protocol, there is a transfer limit of somewhere
5617 between 2MB and 4MB. See "PROTOCOL LIMITS".
5618 (Added in 1.0.66)
5620 guestfs_egrepi
5622 char **
5623 guestfs_egrepi (guestfs_h *g,
5624 const char *regex,
5625 const char *path);
5626 This function is deprecated. In new code, use the "guestfs_grep" call
5628 instead.
5629 Deprecated functions will not be removed from the API, but the fact
5631 that they are deprecated indicates that there are problems with correct
5632 use of these functions.
5633 This calls the external "egrep -i" program and returns the matching
5635 lines.
5636 This function returns a NULL-terminated array of strings (like
5638 environ(3)), or NULL if there was an error. The caller must free the
5639 strings and the array after use.
5640 Because of the message protocol, there is a transfer limit of somewhere
5642 between 2MB and 4MB. See "PROTOCOL LIMITS".
5643 (Added in 1.0.66)
5645 guestfs_equal
5647 int
5648 guestfs_equal (guestfs_h *g,
5649 const char *file1,
5650 const char *file2);
5651 This compares the two files file1 and file2 and returns true if their
5653 content is exactly equal, or false otherwise.
5654 The external cmp(1) program is used for the comparison.
5656 This function returns a C truth value on success or -1 on error.
5658 (Added in 1.0.18)
5660 guestfs_exists
5662 int
5663 guestfs_exists (guestfs_h *g,
5664 const char *path);
5665 This returns "true" if and only if there is a file, directory (or
5667 anything) with the given "path" name.
5668 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5670 This function returns a C truth value on success or -1 on error.
5672 (Added in 0.8)
5674 guestfs_extlinux
5676 int
5677 guestfs_extlinux (guestfs_h *g,
5678 const char *directory);
5679 Install the SYSLINUX bootloader on the device mounted at directory.
5681 Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5682 used on an ext2/3/4 or btrfs filesystem.
5683 The directory parameter can be either a mountpoint, or a directory
5685 within the mountpoint.
5686 You also have to mark the partition as "active"
5688 ("guestfs_part_set_bootable") and a Master Boot Record must be
5689 installed (eg. using "guestfs_pwrite_device") on the first sector of
5690 the whole disk. The SYSLINUX package comes with some suitable Master
5691 Boot Records. See the extlinux(1) man page for further information.
5692 Additional configuration can be supplied to SYSLINUX by placing a file
5694 called extlinux.conf on the filesystem under directory. For further
5695 information about the contents of this file, see extlinux(1).
5696 See also "guestfs_syslinux".
5698 This function returns 0 on success or -1 on error.
5700 This function depends on the feature "extlinux". See also
5702 "guestfs_feature_available".
5703 (Added in 1.21.27)
5705 guestfs_f2fs_expand
5707 int
5708 guestfs_f2fs_expand (guestfs_h *g,
5709 const char *device);
5710 This expands a f2fs filesystem to match the size of the underlying
5712 device.
5713 This function returns 0 on success or -1 on error.
5715 This function depends on the feature "f2fs". See also
5717 "guestfs_feature_available".
5718 (Added in 1.39.3)
5720 guestfs_fallocate
5722 int
5723 guestfs_fallocate (guestfs_h *g,
5724 const char *path,
5725 int len);
5726 This function is deprecated. In new code, use the
5728 "guestfs_fallocate64" call instead.
5729 Deprecated functions will not be removed from the API, but the fact
5731 that they are deprecated indicates that there are problems with correct
5732 use of these functions.
5733 This command preallocates a file (containing zero bytes) named "path"
5735 of size "len" bytes. If the file exists already, it is overwritten.
5736 Do not confuse this with the guestfish-specific "alloc" command which
5738 allocates a file in the host and attaches it as a device.
5739 This function returns 0 on success or -1 on error.
5741 (Added in 1.0.66)
5743 guestfs_fallocate64
5745 int
5746 guestfs_fallocate64 (guestfs_h *g,
5747 const char *path,
5748 int64_t len);
5749 This command preallocates a file (containing zero bytes) named "path"
5751 of size "len" bytes. If the file exists already, it is overwritten.
5752 Note that this call allocates disk blocks for the file. To create a
5754 sparse file use "guestfs_truncate_size" instead.
5755 The deprecated call "guestfs_fallocate" does the same, but owing to an
5757 oversight it only allowed 30 bit lengths to be specified, effectively
5758 limiting the maximum size of files created through that call to 1GB.
5759 Do not confuse this with the guestfish-specific "alloc" and "sparse"
5761 commands which create a file in the host and attach it as a device.
5762 This function returns 0 on success or -1 on error.
5764 (Added in 1.3.17)
5766 guestfs_feature_available
5768 int
5769 guestfs_feature_available (guestfs_h *g,
5770 char *const *groups);
5771 This is the same as "guestfs_available", but unlike that call it
5773 returns a simple true/false boolean result, instead of throwing an
5774 exception if a feature is not found. For other documentation see
5775 "guestfs_available".
5776 This function returns a C truth value on success or -1 on error.
5778 (Added in 1.21.26)
5780 guestfs_fgrep
5782 char **
5783 guestfs_fgrep (guestfs_h *g,
5784 const char *pattern,
5785 const char *path);
5786 This function is deprecated. In new code, use the "guestfs_grep" call
5788 instead.
5789 Deprecated functions will not be removed from the API, but the fact
5791 that they are deprecated indicates that there are problems with correct
5792 use of these functions.
5793 This calls the external fgrep(1) program and returns the matching
5795 lines.
5796 This function returns a NULL-terminated array of strings (like
5798 environ(3)), or NULL if there was an error. The caller must free the
5799 strings and the array after use.
5800 Because of the message protocol, there is a transfer limit of somewhere
5802 between 2MB and 4MB. See "PROTOCOL LIMITS".
5803 (Added in 1.0.66)
5805 guestfs_fgrepi
5807 char **
5808 guestfs_fgrepi (guestfs_h *g,
5809 const char *pattern,
5810 const char *path);
5811 This function is deprecated. In new code, use the "guestfs_grep" call
5813 instead.
5814 Deprecated functions will not be removed from the API, but the fact
5816 that they are deprecated indicates that there are problems with correct
5817 use of these functions.
5818 This calls the external "fgrep -i" program and returns the matching
5820 lines.
5821 This function returns a NULL-terminated array of strings (like
5823 environ(3)), or NULL if there was an error. The caller must free the
5824 strings and the array after use.
5825 Because of the message protocol, there is a transfer limit of somewhere
5827 between 2MB and 4MB. See "PROTOCOL LIMITS".
5828 (Added in 1.0.66)
5830 guestfs_file
5832 char *
5833 guestfs_file (guestfs_h *g,
5834 const char *path);
5835 This call uses the standard file(1) command to determine the type or
5837 contents of the file.
5838 This call will also transparently look inside various types of
5840 compressed file.
5841 The exact command which runs is "file -zb path". Note in particular
5843 that the filename is not prepended to the output (the -b option).
5844 The output depends on the output of the underlying file(1) command and
5846 it can change in future in ways beyond our control. In other words,
5847 the output is not guaranteed by the ABI.
5848 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5850 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5851 This function returns a string, or NULL on error. The caller must free
5853 the returned string after use.
5854 (Added in 1.9.1)
5856 guestfs_file_architecture
5858 char *
5859 guestfs_file_architecture (guestfs_h *g,
5860 const char *filename);
5861 This detects the architecture of the binary filename, and returns it if
5863 known.
5864 Currently defined architectures are:
5866 "aarch64"
5868 64 bit ARM.
5869 "arm"
5871 32 bit ARM.
5872 "i386"
5874 This string is returned for all 32 bit i386, i486, i586, i686
5875 binaries irrespective of the precise processor requirements of the
5876 binary.
5877 "ia64"
5879 Intel Itanium.
5880 "ppc"
5882 32 bit Power PC.
5883 "ppc64"
5885 64 bit Power PC (big endian).
5886 "ppc64le"
5888 64 bit Power PC (little endian).
5889 "riscv32"
5891 "riscv64"
5892 "riscv128"
5893 RISC-V 32-, 64- or 128-bit variants.
5894 "s390"
5896 31 bit IBM S/390.
5897 "s390x"
5899 64 bit IBM S/390.
5900 "sparc"
5902 32 bit SPARC.
5903 "sparc64"
5905 64 bit SPARC V9 and above.
5906 "x86_64"
5908 64 bit x86-64.
5909 Libguestfs may return other architecture strings in future.
5911 The function works on at least the following types of files:
5913 • many types of Un*x and Linux binary
5915 • many types of Un*x and Linux shared library
5917 • Windows Win32 and Win64 binaries
5919 • Windows Win32 and Win64 DLLs
5921 Win32 binaries and DLLs return "i386".
5923 Win64 binaries and DLLs return "x86_64".
5925 • Linux kernel modules
5927 • Linux new-style initrd images
5929 • some non-x86 Linux vmlinuz kernels
5931 What it can't do currently:
5933 • static libraries (libfoo.a)
5935 • Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5937 • x86 Linux vmlinuz kernels
5939 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5941 and compressed code, and are horribly hard to unpack. If you want
5942 to find the architecture of a kernel, use the architecture of the
5943 associated initrd or kernel module(s) instead.
5944 This function returns a string, or NULL on error. The caller must free
5946 the returned string after use.
5947 (Added in 1.5.3)
5949 guestfs_filesize
5951 int64_t
5952 guestfs_filesize (guestfs_h *g,
5953 const char *file);
5954 This command returns the size of file in bytes.
5956 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5958 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
5959 devices, use "guestfs_blockdev_getsize64".
5960 On error this function returns -1.
5962 (Added in 1.0.82)
5964 guestfs_filesystem_available
5966 int
5967 guestfs_filesystem_available (guestfs_h *g,
5968 const char *filesystem);
5969 Check whether libguestfs supports the named filesystem. The argument
5971 "filesystem" is a filesystem name, such as "ext3".
5972 You must call "guestfs_launch" before using this command.
5974 This is mainly useful as a negative test. If this returns true, it
5976 doesn't mean that a particular filesystem can be created or mounted,
5977 since filesystems can fail for other reasons such as it being a later
5978 version of the filesystem, or having incompatible features, or lacking
5979 the right mkfs.<fs> tool.
5980 See also "guestfs_available", "guestfs_feature_available",
5982 "AVAILABILITY".
5983 This function returns a C truth value on success or -1 on error.
5985 (Added in 1.19.5)
5987 guestfs_filesystem_walk
5989 struct guestfs_tsk_dirent_list *
5990 guestfs_filesystem_walk (guestfs_h *g,
5991 const char *device);
5992 Walk through the internal structures of a disk partition (eg.
5994 /dev/sda1) in order to return a list of all the files and directories
5995 stored within.
5996 It is not necessary to mount the disk partition to run this command.
5998 All entries in the filesystem are returned. This function can list
6000 deleted or unaccessible files. The entries are not sorted.
6001 The "tsk_dirent" structure contains the following fields.
6003 "tsk_inode"
6005 Filesystem reference number of the node. It might be 0 if the node
6006 has been deleted.
6007 "tsk_type"
6009 Basic file type information. See below for a detailed list of
6010 values.
6011 "tsk_size"
6013 File size in bytes. It might be "-1" if the node has been deleted.
6014 "tsk_name"
6016 The file path relative to its directory.
6017 "tsk_flags"
6019 Bitfield containing extra information regarding the entry. It
6020 contains the logical OR of the following values:
6021 0x0001
6023 If set to 1, the file is allocated and visible within the
6024 filesystem. Otherwise, the file has been deleted. Under
6025 certain circumstances, the function "download_inode" can be
6026 used to recover deleted files.
6027 0x0002
6029 Filesystem such as NTFS and Ext2 or greater, separate the file
6030 name from the metadata structure. The bit is set to 1 when the
6031 file name is in an unallocated state and the metadata structure
6032 is in an allocated one. This generally implies the metadata
6033 has been reallocated to a new file. Therefore, information
6034 such as file type, file size, timestamps, number of links and
6035 symlink target might not correspond with the ones of the
6036 original deleted entry.
6037 0x0004
6039 The bit is set to 1 when the file is compressed using
6040 filesystem native compression support (NTFS). The API is not
6041 able to detect application level compression.
6042 "tsk_atime_sec"
6044 "tsk_atime_nsec"
6045 "tsk_mtime_sec"
6046 "tsk_mtime_nsec"
6047 "tsk_ctime_sec"
6048 "tsk_ctime_nsec"
6049 "tsk_crtime_sec"
6050 "tsk_crtime_nsec"
6051 Respectively, access, modification, last status change and creation
6052 time in Unix format in seconds and nanoseconds.
6053 "tsk_nlink"
6055 Number of file names pointing to this entry.
6056 "tsk_link"
6058 If the entry is a symbolic link, this field will contain the path
6059 to the target file.
6060 The "tsk_type" field will contain one of the following characters:
6062 'b' Block special
6064 'c' Char special
6066 'd' Directory
6068 'f' FIFO (named pipe)
6070 'l' Symbolic link
6072 'r' Regular file
6074 's' Socket
6076 'h' Shadow inode (Solaris)
6078 'w' Whiteout inode (BSD)
6080 'u' Unknown file type
6082 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6084 there was an error. The caller must call
6085 "guestfs_free_tsk_dirent_list" after use.
6086 This long-running command can generate progress notification messages
6088 so that the caller can display a progress bar or indicator. To receive
6089 these messages, the caller must register a progress event callback.
6090 See "GUESTFS_EVENT_PROGRESS".
6091 This function depends on the feature "libtsk". See also
6093 "guestfs_feature_available".
6094 (Added in 1.33.39)
6096 guestfs_fill
6098 int
6099 guestfs_fill (guestfs_h *g,
6100 int c,
6101 int len,
6102 const char *path);
6103 This command creates a new file called "path". The initial content of
6105 the file is "len" octets of "c", where "c" must be a number in the
6106 range "[0..255]".
6107 To fill a file with zero bytes (sparsely), it is much more efficient to
6109 use "guestfs_truncate_size". To create a file with a pattern of
6110 repeating bytes use "guestfs_fill_pattern".
6111 This function returns 0 on success or -1 on error.
6113 This long-running command can generate progress notification messages
6115 so that the caller can display a progress bar or indicator. To receive
6116 these messages, the caller must register a progress event callback.
6117 See "GUESTFS_EVENT_PROGRESS".
6118 (Added in 1.0.79)
6120 guestfs_fill_dir
6122 int
6123 guestfs_fill_dir (guestfs_h *g,
6124 const char *dir,
6125 int nr);
6126 This function, useful for testing filesystems, creates "nr" empty files
6128 in the directory "dir" with names 00000000 through "nr-1" (ie. each
6129 file name is 8 digits long padded with zeroes).
6130 This function returns 0 on success or -1 on error.
6132 (Added in 1.19.32)
6134 guestfs_fill_pattern
6136 int
6137 guestfs_fill_pattern (guestfs_h *g,
6138 const char *pattern,
6139 int len,
6140 const char *path);
6141 This function is like "guestfs_fill" except that it creates a new file
6143 of length "len" containing the repeating pattern of bytes in "pattern".
6144 The pattern is truncated if necessary to ensure the length of the file
6145 is exactly "len" bytes.
6146 This function returns 0 on success or -1 on error.
6148 This long-running command can generate progress notification messages
6150 so that the caller can display a progress bar or indicator. To receive
6151 these messages, the caller must register a progress event callback.
6152 See "GUESTFS_EVENT_PROGRESS".
6153 (Added in 1.3.12)
6155 guestfs_find
6157 char **
6158 guestfs_find (guestfs_h *g,
6159 const char *directory);
6160 This command lists out all files and directories, recursively, starting
6162 at directory. It is essentially equivalent to running the shell
6163 command "find directory -print" but some post-processing happens on the
6164 output, described below.
6165 This returns a list of strings without any prefix. Thus if the
6167 directory structure was:
6168 /tmp/a
6170 /tmp/b
6171 /tmp/c/d
6172 then the returned list from "guestfs_find" /tmp would be 4 elements:
6174 a
6176 b
6177 c
6178 c/d
6179 If directory is not a directory, then this command returns an error.
6181 The returned list is sorted.
6183 This function returns a NULL-terminated array of strings (like
6185 environ(3)), or NULL if there was an error. The caller must free the
6186 strings and the array after use.
6187 (Added in 1.0.27)
6189 guestfs_find0
6191 int
6192 guestfs_find0 (guestfs_h *g,
6193 const char *directory,
6194 const char *files);
6195 This command lists out all files and directories, recursively, starting
6197 at directory, placing the resulting list in the external file called
6198 files.
6199 This command works the same way as "guestfs_find" with the following
6201 exceptions:
6202 • The resulting list is written to an external file.
6204 • Items (filenames) in the result are separated by "\0" characters.
6206 See find(1) option -print0.
6207 • The result list is not sorted.
6209 This function returns 0 on success or -1 on error.
6211 (Added in 1.0.74)
6213 guestfs_find_inode
6215 struct guestfs_tsk_dirent_list *
6216 guestfs_find_inode (guestfs_h *g,
6217 const char *device,
6218 int64_t inode);
6219 Searches all the entries associated with the given inode.
6221 For each entry, a "tsk_dirent" structure is returned. See
6223 "filesystem_walk" for more information about "tsk_dirent" structures.
6224 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6226 there was an error. The caller must call
6227 "guestfs_free_tsk_dirent_list" after use.
6228 This long-running command can generate progress notification messages
6230 so that the caller can display a progress bar or indicator. To receive
6231 these messages, the caller must register a progress event callback.
6232 See "GUESTFS_EVENT_PROGRESS".
6233 This function depends on the feature "libtsk". See also
6235 "guestfs_feature_available".
6236 (Added in 1.35.6)
6238 guestfs_findfs_label
6240 char *
6241 guestfs_findfs_label (guestfs_h *g,
6242 const char *label);
6243 This command searches the filesystems and returns the one which has the
6245 given label. An error is returned if no such filesystem can be found.
6246 To find the label of a filesystem, use "guestfs_vfs_label".
6248 This function returns a string, or NULL on error. The caller must free
6250 the returned string after use.
6251 (Added in 1.5.3)
6253 guestfs_findfs_uuid
6255 char *
6256 guestfs_findfs_uuid (guestfs_h *g,
6257 const char *uuid);
6258 This command searches the filesystems and returns the one which has the
6260 given UUID. An error is returned if no such filesystem can be found.
6261 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6263 This function returns a string, or NULL on error. The caller must free
6265 the returned string after use.
6266 (Added in 1.5.3)
6268 guestfs_fsck
6270 int
6271 guestfs_fsck (guestfs_h *g,
6272 const char *fstype,
6273 const char *device);
6274 This runs the filesystem checker (fsck) on "device" which should have
6276 filesystem type "fstype".
6277 The returned integer is the status. See fsck(8) for the list of status
6279 codes from "fsck".
6280 Notes:
6282 • Multiple status codes can be summed together.
6284 • A non-zero return code can mean "success", for example if errors
6286 have been corrected on the filesystem.
6287 • Checking or repairing NTFS volumes is not supported (by linux-
6289 ntfs).
6290 This command is entirely equivalent to running "fsck -a -t fstype
6292 device".
6293 On error this function returns -1.
6295 (Added in 1.0.16)
6297 guestfs_fstrim
6299 int
6300 guestfs_fstrim (guestfs_h *g,
6301 const char *mountpoint,
6302 ...);
6303 You may supply a list of optional arguments to this call. Use zero or
6305 more of the following pairs of parameters, and terminate the list with
6306 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6307 GUESTFS_FSTRIM_OFFSET, int64_t offset,
6309 GUESTFS_FSTRIM_LENGTH, int64_t length,
6310 GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6311 Trim the free space in the filesystem mounted on "mountpoint". The
6313 filesystem must be mounted read-write.
6314 The filesystem contents are not affected, but any free space in the
6316 filesystem is "trimmed", that is, given back to the host device, thus
6317 making disk images more sparse, allowing unused space in qcow2 files to
6318 be reused, etc.
6319 This operation requires support in libguestfs, the mounted filesystem,
6321 the host filesystem, qemu and the host kernel. If this support isn't
6322 present it may give an error or even appear to run but do nothing.
6323 In the case where the kernel vfs driver does not support trimming, this
6325 call will fail with errno set to "ENOTSUP". Currently this happens
6326 when trying to trim FAT filesystems.
6327 See also "guestfs_zero_free_space". That is a slightly different
6329 operation that turns free space in the filesystem into zeroes. It is
6330 valid to call "guestfs_fstrim" either instead of, or after calling
6331 "guestfs_zero_free_space".
6332 This function returns 0 on success or -1 on error.
6334 This function depends on the feature "fstrim". See also
6336 "guestfs_feature_available".
6337 (Added in 1.19.6)
6339 guestfs_fstrim_va
6341 int
6342 guestfs_fstrim_va (guestfs_h *g,
6343 const char *mountpoint,
6344 va_list args);
6345 This is the "va_list variant" of "guestfs_fstrim".
6347 See "CALLS WITH OPTIONAL ARGUMENTS".
6349 guestfs_fstrim_argv
6351 int
6352 guestfs_fstrim_argv (guestfs_h *g,
6353 const char *mountpoint,
6354 const struct guestfs_fstrim_argv *optargs);
6355 This is the "argv variant" of "guestfs_fstrim".
6357 See "CALLS WITH OPTIONAL ARGUMENTS".
6359 guestfs_get_append
6361 const char *
6362 guestfs_get_append (guestfs_h *g);
6363 Return the additional kernel options which are added to the libguestfs
6365 appliance kernel command line.
6366 If "NULL" then no options are added.
6368 This function returns a string which may be NULL. There is no way to
6370 return an error from this function. The string is owned by the guest
6371 handle and must not be freed.
6372 (Added in 1.0.26)
6374 guestfs_get_attach_method
6376 char *
6377 guestfs_get_attach_method (guestfs_h *g);
6378 This function is deprecated. In new code, use the
6380 "guestfs_get_backend" call instead.
6381 Deprecated functions will not be removed from the API, but the fact
6383 that they are deprecated indicates that there are problems with correct
6384 use of these functions.
6385 Return the current backend.
6387 See "guestfs_set_backend" and "BACKEND".
6389 This function returns a string, or NULL on error. The caller must free
6391 the returned string after use.
6392 (Added in 1.9.8)
6394 guestfs_get_autosync
6396 int
6397 guestfs_get_autosync (guestfs_h *g);
6398 Get the autosync flag.
6400 This function returns a C truth value on success or -1 on error.
6402 (Added in 0.3)
6404 guestfs_get_backend
6406 char *
6407 guestfs_get_backend (guestfs_h *g);
6408 Return the current backend.
6410 This handle property was previously called the "attach method".
6412 See "guestfs_set_backend" and "BACKEND".
6414 This function returns a string, or NULL on error. The caller must free
6416 the returned string after use.
6417 (Added in 1.21.26)
6419 guestfs_get_backend_setting
6421 char *
6422 guestfs_get_backend_setting (guestfs_h *g,
6423 const char *name);
6424 Find a backend setting string which is either "name" or begins with
6426 "name=". If "name", this returns the string "1". If "name=", this
6427 returns the part after the equals sign (which may be an empty string).
6428 If no such setting is found, this function throws an error. The errno
6430 (see "guestfs_last_errno") will be "ESRCH" in this case.
6431 See "BACKEND", "BACKEND SETTINGS".
6433 This function returns a string, or NULL on error. The caller must free
6435 the returned string after use.
6436 (Added in 1.27.2)
6438 guestfs_get_backend_settings
6440 char **
6441 guestfs_get_backend_settings (guestfs_h *g);
6442 Return the current backend settings.
6444 This call returns all backend settings strings. If you want to find a
6446 single backend setting, see "guestfs_get_backend_setting".
6447 See "BACKEND", "BACKEND SETTINGS".
6449 This function returns a NULL-terminated array of strings (like
6451 environ(3)), or NULL if there was an error. The caller must free the
6452 strings and the array after use.
6453 (Added in 1.25.24)
6455 guestfs_get_cachedir
6457 char *
6458 guestfs_get_cachedir (guestfs_h *g);
6459 Get the directory used by the handle to store the appliance cache.
6461 This function returns a string, or NULL on error. The caller must free
6463 the returned string after use.
6464 (Added in 1.19.58)
6466 guestfs_get_direct
6468 int
6469 guestfs_get_direct (guestfs_h *g);
6470 This function is deprecated. In new code, use the
6472 "guestfs_internal_get_console_socket" call instead.
6473 Deprecated functions will not be removed from the API, but the fact
6475 that they are deprecated indicates that there are problems with correct
6476 use of these functions.
6477 Return the direct appliance mode flag.
6479 This function returns a C truth value on success or -1 on error.
6481 (Added in 1.0.72)
6483 guestfs_get_e2attrs
6485 char *
6486 guestfs_get_e2attrs (guestfs_h *g,
6487 const char *file);
6488 This returns the file attributes associated with file.
6490 The attributes are a set of bits associated with each inode which
6492 affect the behaviour of the file. The attributes are returned as a
6493 string of letters (described below). The string may be empty,
6494 indicating that no file attributes are set for this file.
6495 These attributes are only present when the file is located on an
6497 ext2/3/4 filesystem. Using this call on other filesystem types will
6498 result in an error.
6499 The characters (file attributes) in the returned string are currently:
6501 'A' When the file is accessed, its atime is not modified.
6503 'a' The file is append-only.
6505 'c' The file is compressed on-disk.
6507 'D' (Directories only.) Changes to this directory are written
6509 synchronously to disk.
6510 'd' The file is not a candidate for backup (see dump(8)).
6512 'E' The file has compression errors.
6514 'e' The file is using extents.
6516 'h' The file is storing its blocks in units of the filesystem blocksize
6518 instead of sectors.
6519 'I' (Directories only.) The directory is using hashed trees.
6521 'i' The file is immutable. It cannot be modified, deleted or renamed.
6523 No link can be created to this file.
6524 'j' The file is data-journaled.
6526 's' When the file is deleted, all its blocks will be zeroed.
6528 'S' Changes to this file are written synchronously to disk.
6530 'T' (Directories only.) This is a hint to the block allocator that
6532 subdirectories contained in this directory should be spread across
6533 blocks. If not present, the block allocator will try to group
6534 subdirectories together.
6535 't' For a file, this disables tail-merging. (Not used by upstream
6537 implementations of ext2.)
6538 'u' When the file is deleted, its blocks will be saved, allowing the
6540 file to be undeleted.
6541 'X' The raw contents of the compressed file may be accessed.
6543 'Z' The compressed file is dirty.
6545 More file attributes may be added to this list later. Not all file
6547 attributes may be set for all kinds of files. For detailed
6548 information, consult the chattr(1) man page.
6549 See also "guestfs_set_e2attrs".
6551 Don't confuse these attributes with extended attributes (see
6553 "guestfs_getxattr").
6554 This function returns a string, or NULL on error. The caller must free
6556 the returned string after use.
6557 (Added in 1.17.31)
6559 guestfs_get_e2generation
6561 int64_t
6562 guestfs_get_e2generation (guestfs_h *g,
6563 const char *file);
6564 This returns the ext2 file generation of a file. The generation (which
6566 used to be called the "version") is a number associated with an inode.
6567 This is most commonly used by NFS servers.
6568 The generation is only present when the file is located on an ext2/3/4
6570 filesystem. Using this call on other filesystem types will result in
6571 an error.
6572 See "guestfs_set_e2generation".
6574 On error this function returns -1.
6576 (Added in 1.17.31)
6578 guestfs_get_e2label
6580 char *
6581 guestfs_get_e2label (guestfs_h *g,
6582 const char *device);
6583 This function is deprecated. In new code, use the "guestfs_vfs_label"
6585 call instead.
6586 Deprecated functions will not be removed from the API, but the fact
6588 that they are deprecated indicates that there are problems with correct
6589 use of these functions.
6590 This returns the ext2/3/4 filesystem label of the filesystem on
6592 "device".
6593 This function returns a string, or NULL on error. The caller must free
6595 the returned string after use.
6596 (Added in 1.0.15)
6598 guestfs_get_e2uuid
6600 char *
6601 guestfs_get_e2uuid (guestfs_h *g,
6602 const char *device);
6603 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
6605 call instead.
6606 Deprecated functions will not be removed from the API, but the fact
6608 that they are deprecated indicates that there are problems with correct
6609 use of these functions.
6610 This returns the ext2/3/4 filesystem UUID of the filesystem on
6612 "device".
6613 This function returns a string, or NULL on error. The caller must free
6615 the returned string after use.
6616 (Added in 1.0.15)
6618 guestfs_get_hv
6620 char *
6621 guestfs_get_hv (guestfs_h *g);
6622 Return the current hypervisor binary.
6624 This is always non-NULL. If it wasn't set already, then this will
6626 return the default qemu binary name.
6627 This function returns a string, or NULL on error. The caller must free
6629 the returned string after use.
6630 (Added in 1.23.17)
6632 guestfs_get_identifier
6634 const char *
6635 guestfs_get_identifier (guestfs_h *g);
6636 Get the handle identifier. See "guestfs_set_identifier".
6638 This function returns a string, or NULL on error. The string is owned
6640 by the guest handle and must not be freed.
6641 (Added in 1.31.14)
6643 guestfs_get_libvirt_requested_credential_challenge
6645 char *
6646 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6647 int index);
6648 Get the challenge (provided by libvirt) for the "index"'th requested
6650 credential. If libvirt did not provide a challenge, this returns the
6651 empty string "".
6652 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6654 This function returns a string, or NULL on error. The caller must free
6656 the returned string after use.
6657 (Added in 1.19.52)
6659 guestfs_get_libvirt_requested_credential_defresult
6661 char *
6662 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6663 int index);
6664 Get the default result (provided by libvirt) for the "index"'th
6666 requested credential. If libvirt did not provide a default result,
6667 this returns the empty string "".
6668 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6670 This function returns a string, or NULL on error. The caller must free
6672 the returned string after use.
6673 (Added in 1.19.52)
6675 guestfs_get_libvirt_requested_credential_prompt
6677 char *
6678 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6679 int index);
6680 Get the prompt (provided by libvirt) for the "index"'th requested
6682 credential. If libvirt did not provide a prompt, this returns the
6683 empty string "".
6684 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6686 This function returns a string, or NULL on error. The caller must free
6688 the returned string after use.
6689 (Added in 1.19.52)
6691 guestfs_get_libvirt_requested_credentials
6693 char **
6694 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6695 This should only be called during the event callback for events of type
6697 "GUESTFS_EVENT_LIBVIRT_AUTH".
6698 Return the list of credentials requested by libvirt. Possible values
6700 are a subset of the strings provided when you called
6701 "guestfs_set_libvirt_supported_credentials".
6702 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6704 This function returns a NULL-terminated array of strings (like
6706 environ(3)), or NULL if there was an error. The caller must free the
6707 strings and the array after use.
6708 (Added in 1.19.52)
6710 guestfs_get_memsize
6712 int
6713 guestfs_get_memsize (guestfs_h *g);
6714 This gets the memory size in megabytes allocated to the hypervisor.
6716 If "guestfs_set_memsize" was not called on this handle, and if
6718 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6719 default value for memsize.
6720 For more information on the architecture of libguestfs, see guestfs(3).
6722 On error this function returns -1.
6724 (Added in 1.0.55)
6726 guestfs_get_network
6728 int
6729 guestfs_get_network (guestfs_h *g);
6730 This returns the enable network flag.
6732 This function returns a C truth value on success or -1 on error.
6734 (Added in 1.5.4)
6736 guestfs_get_path
6738 const char *
6739 guestfs_get_path (guestfs_h *g);
6740 Return the current search path.
6742 This is always non-NULL. If it wasn't set already, then this will
6744 return the default path.
6745 This function returns a string, or NULL on error. The string is owned
6747 by the guest handle and must not be freed.
6748 (Added in 0.3)
6750 guestfs_get_pgroup
6752 int
6753 guestfs_get_pgroup (guestfs_h *g);
6754 This returns the process group flag.
6756 This function returns a C truth value on success or -1 on error.
6758 (Added in 1.11.18)
6760 guestfs_get_pid
6762 int
6763 guestfs_get_pid (guestfs_h *g);
6764 Return the process ID of the hypervisor. If there is no hypervisor
6766 running, then this will return an error.
6767 This is an internal call used for debugging and testing.
6769 On error this function returns -1.
6771 (Added in 1.0.56)
6773 guestfs_get_program
6775 const char *
6776 guestfs_get_program (guestfs_h *g);
6777 Get the program name. See "guestfs_set_program".
6779 This function returns a string, or NULL on error. The string is owned
6781 by the guest handle and must not be freed.
6782 (Added in 1.21.29)
6784 guestfs_get_qemu
6786 const char *
6787 guestfs_get_qemu (guestfs_h *g);
6788 This function is deprecated. In new code, use the "guestfs_get_hv"
6790 call instead.
6791 Deprecated functions will not be removed from the API, but the fact
6793 that they are deprecated indicates that there are problems with correct
6794 use of these functions.
6795 Return the current hypervisor binary (usually qemu).
6797 This is always non-NULL. If it wasn't set already, then this will
6799 return the default qemu binary name.
6800 This function returns a string, or NULL on error. The string is owned
6802 by the guest handle and must not be freed.
6803 (Added in 1.0.6)
6805 guestfs_get_recovery_proc
6807 int
6808 guestfs_get_recovery_proc (guestfs_h *g);
6809 Return the recovery process enabled flag.
6811 This function returns a C truth value on success or -1 on error.
6813 (Added in 1.0.77)
6815 guestfs_get_selinux
6817 int
6818 guestfs_get_selinux (guestfs_h *g);
6819 This function is deprecated. In new code, use the
6821 "guestfs_selinux_relabel" call instead.
6822 Deprecated functions will not be removed from the API, but the fact
6824 that they are deprecated indicates that there are problems with correct
6825 use of these functions.
6826 This returns the current setting of the selinux flag which is passed to
6828 the appliance at boot time. See "guestfs_set_selinux".
6829 For more information on the architecture of libguestfs, see guestfs(3).
6831 This function returns a C truth value on success or -1 on error.
6833 (Added in 1.0.67)
6835 guestfs_get_smp
6837 int
6838 guestfs_get_smp (guestfs_h *g);
6839 This returns the number of virtual CPUs assigned to the appliance.
6841 On error this function returns -1.
6843 (Added in 1.13.15)
6845 guestfs_get_sockdir
6847 char *
6848 guestfs_get_sockdir (guestfs_h *g);
6849 Get the directory used by the handle to store temporary socket files.
6851 This is different from "guestfs_get_tmpdir", as we need shorter paths
6853 for sockets (due to the limited buffers of filenames for UNIX sockets),
6854 and "guestfs_get_tmpdir" may be too long for them.
6855 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6857 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6858 the default.
6859 This function returns a string, or NULL on error. The caller must free
6861 the returned string after use.
6862 (Added in 1.33.8)
6864 guestfs_get_state
6866 int
6867 guestfs_get_state (guestfs_h *g);
6868 This returns the current state as an opaque integer. This is only
6870 useful for printing debug and internal error messages.
6871 For more information on states, see guestfs(3).
6873 On error this function returns -1.
6875 (Added in 1.0.2)
6877 guestfs_get_tmpdir
6879 char *
6880 guestfs_get_tmpdir (guestfs_h *g);
6881 Get the directory used by the handle to store temporary files.
6883 This function returns a string, or NULL on error. The caller must free
6885 the returned string after use.
6886 (Added in 1.19.58)
6888 guestfs_get_trace
6890 int
6891 guestfs_get_trace (guestfs_h *g);
6892 Return the command trace flag.
6894 This function returns a C truth value on success or -1 on error.
6896 (Added in 1.0.69)
6898 guestfs_get_umask
6900 int
6901 guestfs_get_umask (guestfs_h *g);
6902 Return the current umask. By default the umask is 022 unless it has
6904 been set by calling "guestfs_umask".
6905 On error this function returns -1.
6907 (Added in 1.3.4)
6909 guestfs_get_verbose
6911 int
6912 guestfs_get_verbose (guestfs_h *g);
6913 This returns the verbose messages flag.
6915 This function returns a C truth value on success or -1 on error.
6917 (Added in 0.3)
6919 guestfs_getcon
6921 char *
6922 guestfs_getcon (guestfs_h *g);
6923 This function is deprecated. In new code, use the
6925 "guestfs_selinux_relabel" call instead.
6926 Deprecated functions will not be removed from the API, but the fact
6928 that they are deprecated indicates that there are problems with correct
6929 use of these functions.
6930 This gets the SELinux security context of the daemon.
6932 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6934 This function returns a string, or NULL on error. The caller must free
6936 the returned string after use.
6937 This function depends on the feature "selinux". See also
6939 "guestfs_feature_available".
6940 (Added in 1.0.67)
6942 guestfs_getxattr
6944 char *
6945 guestfs_getxattr (guestfs_h *g,
6946 const char *path,
6947 const char *name,
6948 size_t *size_r);
6949 Get a single extended attribute from file "path" named "name". This
6951 call follows symlinks. If you want to lookup an extended attribute for
6952 the symlink itself, use "guestfs_lgetxattr".
6953 Normally it is better to get all extended attributes from a file in one
6955 go by calling "guestfs_getxattrs". However some Linux filesystem
6956 implementations are buggy and do not provide a way to list out
6957 attributes. For these filesystems (notably ntfs-3g) you have to know
6958 the names of the extended attributes you want in advance and call this
6959 function.
6960 Extended attribute values are blobs of binary data. If there is no
6962 extended attribute named "name", this returns an error.
6963 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6965 This function returns a buffer, or NULL on error. The size of the
6967 returned buffer is written to *size_r. The caller must free the
6968 returned buffer after use.
6969 This function depends on the feature "linuxxattrs". See also
6971 "guestfs_feature_available".
6972 (Added in 1.7.24)
6974 guestfs_getxattrs
6976 struct guestfs_xattr_list *
6977 guestfs_getxattrs (guestfs_h *g,
6978 const char *path);
6979 This call lists the extended attributes of the file or directory
6981 "path".
6982 At the system call level, this is a combination of the listxattr(2) and
6984 getxattr(2) calls.
6985 See also: "guestfs_lgetxattrs", attr(5).
6987 This function returns a "struct guestfs_xattr_list *", or NULL if there
6989 was an error. The caller must call "guestfs_free_xattr_list" after
6990 use.
6991 This function depends on the feature "linuxxattrs". See also
6993 "guestfs_feature_available".
6994 (Added in 1.0.59)
6996 guestfs_glob_expand
6998 char **
6999 guestfs_glob_expand (guestfs_h *g,
7000 const char *pattern);
7001 This function is provided for backwards compatibility with earlier
7003 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
7004 with no optional arguments.
7005 (Added in 1.0.50)
7007 guestfs_glob_expand_opts
7009 char **
7010 guestfs_glob_expand_opts (guestfs_h *g,
7011 const char *pattern,
7012 ...);
7013 You may supply a list of optional arguments to this call. Use zero or
7015 more of the following pairs of parameters, and terminate the list with
7016 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7017 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
7019 This command searches for all the pathnames matching "pattern"
7021 according to the wildcard expansion rules used by the shell.
7022 If no paths match, then this returns an empty list (note: not an
7024 error).
7025 It is just a wrapper around the C glob(3) function with flags
7027 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
7028 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
7030 and it defaults to true. It can be explicitly set as off to return no
7031 trailing slashes in filenames of directories.
7032 Notice that there is no equivalent command for expanding a device name
7034 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
7035 etc functions instead.
7036 This function returns a NULL-terminated array of strings (like
7038 environ(3)), or NULL if there was an error. The caller must free the
7039 strings and the array after use.
7040 (Added in 1.0.50)
7042 guestfs_glob_expand_opts_va
7044 char **
7045 guestfs_glob_expand_opts_va (guestfs_h *g,
7046 const char *pattern,
7047 va_list args);
7048 This is the "va_list variant" of "guestfs_glob_expand_opts".
7050 See "CALLS WITH OPTIONAL ARGUMENTS".
7052 guestfs_glob_expand_opts_argv
7054 char **
7055 guestfs_glob_expand_opts_argv (guestfs_h *g,
7056 const char *pattern,
7057 const struct guestfs_glob_expand_opts_argv *optargs);
7058 This is the "argv variant" of "guestfs_glob_expand_opts".
7060 See "CALLS WITH OPTIONAL ARGUMENTS".
7062 guestfs_grep
7064 char **
7065 guestfs_grep (guestfs_h *g,
7066 const char *regex,
7067 const char *path);
7068 This function is provided for backwards compatibility with earlier
7070 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
7071 optional arguments.
7072 (Added in 1.0.66)
7074 guestfs_grep_opts
7076 char **
7077 guestfs_grep_opts (guestfs_h *g,
7078 const char *regex,
7079 const char *path,
7080 ...);
7081 You may supply a list of optional arguments to this call. Use zero or
7083 more of the following pairs of parameters, and terminate the list with
7084 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7085 GUESTFS_GREP_OPTS_EXTENDED, int extended,
7087 GUESTFS_GREP_OPTS_FIXED, int fixed,
7088 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
7089 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
7090 This calls the external grep(1) program and returns the matching lines.
7092 The optional flags are:
7094 "extended"
7096 Use extended regular expressions. This is the same as using the -E
7097 flag.
7098 "fixed"
7100 Match fixed (don't use regular expressions). This is the same as
7101 using the -F flag.
7102 "insensitive"
7104 Match case-insensitive. This is the same as using the -i flag.
7105 "compressed"
7107 Use zgrep(1) instead of grep(1). This allows the input to be
7108 compress- or gzip-compressed.
7109 This function returns a NULL-terminated array of strings (like
7111 environ(3)), or NULL if there was an error. The caller must free the
7112 strings and the array after use.
7113 Because of the message protocol, there is a transfer limit of somewhere
7115 between 2MB and 4MB. See "PROTOCOL LIMITS".
7116 (Added in 1.0.66)
7118 guestfs_grep_opts_va
7120 char **
7121 guestfs_grep_opts_va (guestfs_h *g,
7122 const char *regex,
7123 const char *path,
7124 va_list args);
7125 This is the "va_list variant" of "guestfs_grep_opts".
7127 See "CALLS WITH OPTIONAL ARGUMENTS".
7129 guestfs_grep_opts_argv
7131 char **
7132 guestfs_grep_opts_argv (guestfs_h *g,
7133 const char *regex,
7134 const char *path,
7135 const struct guestfs_grep_opts_argv *optargs);
7136 This is the "argv variant" of "guestfs_grep_opts".
7138 See "CALLS WITH OPTIONAL ARGUMENTS".
7140 guestfs_grepi
7142 char **
7143 guestfs_grepi (guestfs_h *g,
7144 const char *regex,
7145 const char *path);
7146 This function is deprecated. In new code, use the "guestfs_grep" call
7148 instead.
7149 Deprecated functions will not be removed from the API, but the fact
7151 that they are deprecated indicates that there are problems with correct
7152 use of these functions.
7153 This calls the external "grep -i" program and returns the matching
7155 lines.
7156 This function returns a NULL-terminated array of strings (like
7158 environ(3)), or NULL if there was an error. The caller must free the
7159 strings and the array after use.
7160 Because of the message protocol, there is a transfer limit of somewhere
7162 between 2MB and 4MB. See "PROTOCOL LIMITS".
7163 (Added in 1.0.66)
7165 guestfs_grub_install
7167 int
7168 guestfs_grub_install (guestfs_h *g,
7169 const char *root,
7170 const char *device);
7171 This command installs GRUB 1 (the Grand Unified Bootloader) on
7173 "device", with the root directory being "root".
7174 Notes:
7176 • There is currently no way in the API to install grub2, which is
7178 used by most modern Linux guests. It is possible to run the grub2
7179 command from the guest, although see the caveats in "RUNNING
7180 COMMANDS".
7181 • This uses grub-install(8) from the host. Unfortunately grub is not
7183 always compatible with itself, so this only works in rather narrow
7184 circumstances. Careful testing with each guest version is
7185 advisable.
7186 • If grub-install reports the error "No suitable drive was found in
7188 the generated device map." it may be that you need to create a
7189 /boot/grub/device.map file first that contains the mapping between
7190 grub device names and Linux device names. It is usually sufficient
7191 to create a file containing:
7192 (hd0) /dev/vda
7194 replacing /dev/vda with the name of the installation device.
7196 This function returns 0 on success or -1 on error.
7198 This function depends on the feature "grub". See also
7200 "guestfs_feature_available".
7201 (Added in 1.0.17)
7203 guestfs_head
7205 char **
7206 guestfs_head (guestfs_h *g,
7207 const char *path);
7208 This command returns up to the first 10 lines of a file as a list of
7210 strings.
7211 This function returns a NULL-terminated array of strings (like
7213 environ(3)), or NULL if there was an error. The caller must free the
7214 strings and the array after use.
7215 Because of the message protocol, there is a transfer limit of somewhere
7217 between 2MB and 4MB. See "PROTOCOL LIMITS".
7218 (Added in 1.0.54)
7220 guestfs_head_n
7222 char **
7223 guestfs_head_n (guestfs_h *g,
7224 int nrlines,
7225 const char *path);
7226 If the parameter "nrlines" is a positive number, this returns the first
7228 "nrlines" lines of the file "path".
7229 If the parameter "nrlines" is a negative number, this returns lines
7231 from the file "path", excluding the last "nrlines" lines.
7232 If the parameter "nrlines" is zero, this returns an empty list.
7234 This function returns a NULL-terminated array of strings (like
7236 environ(3)), or NULL if there was an error. The caller must free the
7237 strings and the array after use.
7238 Because of the message protocol, there is a transfer limit of somewhere
7240 between 2MB and 4MB. See "PROTOCOL LIMITS".
7241 (Added in 1.0.54)
7243 guestfs_hexdump
7245 char *
7246 guestfs_hexdump (guestfs_h *g,
7247 const char *path);
7248 This runs "hexdump -C" on the given "path". The result is the human-
7250 readable, canonical hex dump of the file.
7251 This function returns a string, or NULL on error. The caller must free
7253 the returned string after use.
7254 Because of the message protocol, there is a transfer limit of somewhere
7256 between 2MB and 4MB. See "PROTOCOL LIMITS".
7257 (Added in 1.0.22)
7259 guestfs_hivex_close
7261 int
7262 guestfs_hivex_close (guestfs_h *g);
7263 Close the current hivex handle.
7265 This is a wrapper around the hivex(3) call of the same name.
7267 This function returns 0 on success or -1 on error.
7269 This function depends on the feature "hivex". See also
7271 "guestfs_feature_available".
7272 (Added in 1.19.35)
7274 guestfs_hivex_commit
7276 int
7277 guestfs_hivex_commit (guestfs_h *g,
7278 const char *filename);
7279 Commit (write) changes to the hive.
7281 If the optional filename parameter is null, then the changes are
7283 written back to the same hive that was opened. If this is not null
7284 then they are written to the alternate filename given and the original
7285 hive is left untouched.
7286 This is a wrapper around the hivex(3) call of the same name.
7288 This function returns 0 on success or -1 on error.
7290 This function depends on the feature "hivex". See also
7292 "guestfs_feature_available".
7293 (Added in 1.19.35)
7295 guestfs_hivex_node_add_child
7297 int64_t
7298 guestfs_hivex_node_add_child (guestfs_h *g,
7299 int64_t parent,
7300 const char *name);
7301 Add a child node to "parent" named "name".
7303 This is a wrapper around the hivex(3) call of the same name.
7305 On error this function returns -1.
7307 This function depends on the feature "hivex". See also
7309 "guestfs_feature_available".
7310 (Added in 1.19.35)
7312 guestfs_hivex_node_children
7314 struct guestfs_hivex_node_list *
7315 guestfs_hivex_node_children (guestfs_h *g,
7316 int64_t nodeh);
7317 Return the list of nodes which are subkeys of "nodeh".
7319 This is a wrapper around the hivex(3) call of the same name.
7321 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7323 there was an error. The caller must call
7324 "guestfs_free_hivex_node_list" after use.
7325 This function depends on the feature "hivex". See also
7327 "guestfs_feature_available".
7328 (Added in 1.19.35)
7330 guestfs_hivex_node_delete_child
7332 int
7333 guestfs_hivex_node_delete_child (guestfs_h *g,
7334 int64_t nodeh);
7335 Delete "nodeh", recursively if necessary.
7337 This is a wrapper around the hivex(3) call of the same name.
7339 This function returns 0 on success or -1 on error.
7341 This function depends on the feature "hivex". See also
7343 "guestfs_feature_available".
7344 (Added in 1.19.35)
7346 guestfs_hivex_node_get_child
7348 int64_t
7349 guestfs_hivex_node_get_child (guestfs_h *g,
7350 int64_t nodeh,
7351 const char *name);
7352 Return the child of "nodeh" with the name "name", if it exists. This
7354 can return 0 meaning the name was not found.
7355 This is a wrapper around the hivex(3) call of the same name.
7357 On error this function returns -1.
7359 This function depends on the feature "hivex". See also
7361 "guestfs_feature_available".
7362 (Added in 1.19.35)
7364 guestfs_hivex_node_get_value
7366 int64_t
7367 guestfs_hivex_node_get_value (guestfs_h *g,
7368 int64_t nodeh,
7369 const char *key);
7370 Return the value attached to "nodeh" which has the name "key", if it
7372 exists. This can return 0 meaning the key was not found.
7373 This is a wrapper around the hivex(3) call of the same name.
7375 On error this function returns -1.
7377 This function depends on the feature "hivex". See also
7379 "guestfs_feature_available".
7380 (Added in 1.19.35)
7382 guestfs_hivex_node_name
7384 char *
7385 guestfs_hivex_node_name (guestfs_h *g,
7386 int64_t nodeh);
7387 Return the name of "nodeh".
7389 This is a wrapper around the hivex(3) call of the same name.
7391 This function returns a string, or NULL on error. The caller must free
7393 the returned string after use.
7394 This function depends on the feature "hivex". See also
7396 "guestfs_feature_available".
7397 (Added in 1.19.35)
7399 guestfs_hivex_node_parent
7401 int64_t
7402 guestfs_hivex_node_parent (guestfs_h *g,
7403 int64_t nodeh);
7404 Return the parent node of "nodeh".
7406 This is a wrapper around the hivex(3) call of the same name.
7408 On error this function returns -1.
7410 This function depends on the feature "hivex". See also
7412 "guestfs_feature_available".
7413 (Added in 1.19.35)
7415 guestfs_hivex_node_set_value
7417 int
7418 guestfs_hivex_node_set_value (guestfs_h *g,
7419 int64_t nodeh,
7420 const char *key,
7421 int64_t t,
7422 const char *val,
7423 size_t val_size);
7424 Set or replace a single value under the node "nodeh". The "key" is the
7426 name, "t" is the type, and "val" is the data.
7427 This is a wrapper around the hivex(3) call of the same name.
7429 This function returns 0 on success or -1 on error.
7431 This function depends on the feature "hivex". See also
7433 "guestfs_feature_available".
7434 (Added in 1.19.35)
7436 guestfs_hivex_node_values
7438 struct guestfs_hivex_value_list *
7439 guestfs_hivex_node_values (guestfs_h *g,
7440 int64_t nodeh);
7441 Return the array of (key, datatype, data) tuples attached to "nodeh".
7443 This is a wrapper around the hivex(3) call of the same name.
7445 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7447 there was an error. The caller must call
7448 "guestfs_free_hivex_value_list" after use.
7449 This function depends on the feature "hivex". See also
7451 "guestfs_feature_available".
7452 (Added in 1.19.35)
7454 guestfs_hivex_open
7456 int
7457 guestfs_hivex_open (guestfs_h *g,
7458 const char *filename,
7459 ...);
7460 You may supply a list of optional arguments to this call. Use zero or
7462 more of the following pairs of parameters, and terminate the list with
7463 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7464 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7466 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7467 GUESTFS_HIVEX_OPEN_WRITE, int write,
7468 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7469 Open the Windows Registry hive file named filename. If there was any
7471 previous hivex handle associated with this guestfs session, then it is
7472 closed.
7473 This is a wrapper around the hivex(3) call of the same name.
7475 This function returns 0 on success or -1 on error.
7477 This function depends on the feature "hivex". See also
7479 "guestfs_feature_available".
7480 (Added in 1.19.35)
7482 guestfs_hivex_open_va
7484 int
7485 guestfs_hivex_open_va (guestfs_h *g,
7486 const char *filename,
7487 va_list args);
7488 This is the "va_list variant" of "guestfs_hivex_open".
7490 See "CALLS WITH OPTIONAL ARGUMENTS".
7492 guestfs_hivex_open_argv
7494 int
7495 guestfs_hivex_open_argv (guestfs_h *g,
7496 const char *filename,
7497 const struct guestfs_hivex_open_argv *optargs);
7498 This is the "argv variant" of "guestfs_hivex_open".
7500 See "CALLS WITH OPTIONAL ARGUMENTS".
7502 guestfs_hivex_root
7504 int64_t
7505 guestfs_hivex_root (guestfs_h *g);
7506 Return the root node of the hive.
7508 This is a wrapper around the hivex(3) call of the same name.
7510 On error this function returns -1.
7512 This function depends on the feature "hivex". See also
7514 "guestfs_feature_available".
7515 (Added in 1.19.35)
7517 guestfs_hivex_value_key
7519 char *
7520 guestfs_hivex_value_key (guestfs_h *g,
7521 int64_t valueh);
7522 Return the key (name) field of a (key, datatype, data) tuple.
7524 This is a wrapper around the hivex(3) call of the same name.
7526 This function returns a string, or NULL on error. The caller must free
7528 the returned string after use.
7529 This function depends on the feature "hivex". See also
7531 "guestfs_feature_available".
7532 (Added in 1.19.35)
7534 guestfs_hivex_value_string
7536 char *
7537 guestfs_hivex_value_string (guestfs_h *g,
7538 int64_t valueh);
7539 This calls "guestfs_hivex_value_value" (which returns the data field
7541 from a hivex value tuple). It then assumes that the field is a
7542 UTF-16LE string and converts the result to UTF-8 (or if this is not
7543 possible, it returns an error).
7544 This is useful for reading strings out of the Windows registry.
7546 However it is not foolproof because the registry is not strongly-typed
7547 and fields can contain arbitrary or unexpected data.
7548 This function returns a string, or NULL on error. The caller must free
7550 the returned string after use.
7551 This function depends on the feature "hivex". See also
7553 "guestfs_feature_available".
7554 (Added in 1.37.22)
7556 guestfs_hivex_value_type
7558 int64_t
7559 guestfs_hivex_value_type (guestfs_h *g,
7560 int64_t valueh);
7561 Return the data type field from a (key, datatype, data) tuple.
7563 This is a wrapper around the hivex(3) call of the same name.
7565 On error this function returns -1.
7567 This function depends on the feature "hivex". See also
7569 "guestfs_feature_available".
7570 (Added in 1.19.35)
7572 guestfs_hivex_value_utf8
7574 char *
7575 guestfs_hivex_value_utf8 (guestfs_h *g,
7576 int64_t valueh);
7577 This function is deprecated. In new code, use the
7579 "guestfs_hivex_value_string" call instead.
7580 Deprecated functions will not be removed from the API, but the fact
7582 that they are deprecated indicates that there are problems with correct
7583 use of these functions.
7584 This calls "guestfs_hivex_value_value" (which returns the data field
7586 from a hivex value tuple). It then assumes that the field is a
7587 UTF-16LE string and converts the result to UTF-8 (or if this is not
7588 possible, it returns an error).
7589 This is useful for reading strings out of the Windows registry.
7591 However it is not foolproof because the registry is not strongly-typed
7592 and fields can contain arbitrary or unexpected data.
7593 This function returns a string, or NULL on error. The caller must free
7595 the returned string after use.
7596 This function depends on the feature "hivex". See also
7598 "guestfs_feature_available".
7599 (Added in 1.19.35)
7601 guestfs_hivex_value_value
7603 char *
7604 guestfs_hivex_value_value (guestfs_h *g,
7605 int64_t valueh,
7606 size_t *size_r);
7607 Return the data field of a (key, datatype, data) tuple.
7609 This is a wrapper around the hivex(3) call of the same name.
7611 See also: "guestfs_hivex_value_utf8".
7613 This function returns a buffer, or NULL on error. The size of the
7615 returned buffer is written to *size_r. The caller must free the
7616 returned buffer after use.
7617 This function depends on the feature "hivex". See also
7619 "guestfs_feature_available".
7620 (Added in 1.19.35)
7622 guestfs_initrd_cat
7624 char *
7625 guestfs_initrd_cat (guestfs_h *g,
7626 const char *initrdpath,
7627 const char *filename,
7628 size_t *size_r);
7629 This command unpacks the file filename from the initrd file called
7631 initrdpath. The filename must be given without the initial /
7632 character.
7633 For example, in guestfish you could use the following command to
7635 examine the boot script (usually called /init) contained in a Linux
7636 initrd or initramfs image:
7637 initrd-cat /boot/initrd-<version>.img init
7639 See also "guestfs_initrd_list".
7641 This function returns a buffer, or NULL on error. The size of the
7643 returned buffer is written to *size_r. The caller must free the
7644 returned buffer after use.
7645 Because of the message protocol, there is a transfer limit of somewhere
7647 between 2MB and 4MB. See "PROTOCOL LIMITS".
7648 (Added in 1.0.84)
7650 guestfs_initrd_list
7652 char **
7653 guestfs_initrd_list (guestfs_h *g,
7654 const char *path);
7655 This command lists out files contained in an initrd.
7657 The files are listed without any initial / character. The files are
7659 listed in the order they appear (not necessarily alphabetical).
7660 Directory names are listed as separate items.
7661 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7663 as initrd. We only support the newer initramfs format (compressed cpio
7664 files).
7665 This function returns a NULL-terminated array of strings (like
7667 environ(3)), or NULL if there was an error. The caller must free the
7668 strings and the array after use.
7669 (Added in 1.0.54)
7671 guestfs_inotify_add_watch
7673 int64_t
7674 guestfs_inotify_add_watch (guestfs_h *g,
7675 const char *path,
7676 int mask);
7677 Watch "path" for the events listed in "mask".
7679 Note that if "path" is a directory then events within that directory
7681 are watched, but this does not happen recursively (in subdirectories).
7682 Note for non-C or non-Linux callers: the inotify events are defined by
7684 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7685 On error this function returns -1.
7687 This function depends on the feature "inotify". See also
7689 "guestfs_feature_available".
7690 (Added in 1.0.66)
7692 guestfs_inotify_close
7694 int
7695 guestfs_inotify_close (guestfs_h *g);
7696 This closes the inotify handle which was previously opened by
7698 inotify_init. It removes all watches, throws away any pending events,
7699 and deallocates all resources.
7700 This function returns 0 on success or -1 on error.
7702 This function depends on the feature "inotify". See also
7704 "guestfs_feature_available".
7705 (Added in 1.0.66)
7707 guestfs_inotify_files
7709 char **
7710 guestfs_inotify_files (guestfs_h *g);
7711 This function is a helpful wrapper around "guestfs_inotify_read" which
7713 just returns a list of pathnames of objects that were touched. The
7714 returned pathnames are sorted and deduplicated.
7715 This function returns a NULL-terminated array of strings (like
7717 environ(3)), or NULL if there was an error. The caller must free the
7718 strings and the array after use.
7719 This function depends on the feature "inotify". See also
7721 "guestfs_feature_available".
7722 (Added in 1.0.66)
7724 guestfs_inotify_init
7726 int
7727 guestfs_inotify_init (guestfs_h *g,
7728 int maxevents);
7729 This command creates a new inotify handle. The inotify subsystem can
7731 be used to notify events which happen to objects in the guest
7732 filesystem.
7733 "maxevents" is the maximum number of events which will be queued up
7735 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7736 this is passed as 0, then the kernel (or previously set) default is
7737 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7738 limit, the kernel throws away events, but records the fact that it
7739 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7740 structure list (see "guestfs_inotify_read").
7741 Before any events are generated, you have to add some watches to the
7743 internal watch list. See: "guestfs_inotify_add_watch" and
7744 "guestfs_inotify_rm_watch".
7745 Queued up events should be read periodically by calling
7747 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7748 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7749 events out often enough then you risk the internal queue overflowing.
7750 The handle should be closed after use by calling
7752 "guestfs_inotify_close". This also removes any watches automatically.
7753 See also inotify(7) for an overview of the inotify interface as exposed
7755 by the Linux kernel, which is roughly what we expose via libguestfs.
7756 Note that there is one global inotify handle per libguestfs instance.
7757 This function returns 0 on success or -1 on error.
7759 This function depends on the feature "inotify". See also
7761 "guestfs_feature_available".
7762 (Added in 1.0.66)
7764 guestfs_inotify_read
7766 struct guestfs_inotify_event_list *
7767 guestfs_inotify_read (guestfs_h *g);
7768 Return the complete queue of events that have happened since the
7770 previous read call.
7771 If no events have happened, this returns an empty list.
7773 Note: In order to make sure that all events have been read, you must
7775 call this function repeatedly until it returns an empty list. The
7776 reason is that the call will read events up to the maximum appliance-
7777 to-host message size and leave remaining events in the queue.
7778 This function returns a "struct guestfs_inotify_event_list *", or NULL
7780 if there was an error. The caller must call
7781 "guestfs_free_inotify_event_list" after use.
7782 This function depends on the feature "inotify". See also
7784 "guestfs_feature_available".
7785 (Added in 1.0.66)
7787 guestfs_inotify_rm_watch
7789 int
7790 guestfs_inotify_rm_watch (guestfs_h *g,
7791 int wd);
7792 Remove a previously defined inotify watch. See
7794 "guestfs_inotify_add_watch".
7795 This function returns 0 on success or -1 on error.
7797 This function depends on the feature "inotify". See also
7799 "guestfs_feature_available".
7800 (Added in 1.0.66)
7802 guestfs_inspect_get_arch
7804 char *
7805 guestfs_inspect_get_arch (guestfs_h *g,
7806 const char *root);
7807 This returns the architecture of the inspected operating system. The
7809 possible return values are listed under "guestfs_file_architecture".
7810 If the architecture could not be determined, then the string "unknown"
7812 is returned.
7813 Please read "INSPECTION" for more details.
7815 This function returns a string, or NULL on error. The caller must free
7817 the returned string after use.
7818 (Added in 1.5.3)
7820 guestfs_inspect_get_distro
7822 char *
7823 guestfs_inspect_get_distro (guestfs_h *g,
7824 const char *root);
7825 This returns the distro (distribution) of the inspected operating
7827 system.
7828 Currently defined distros are:
7830 "alpinelinux"
7832 Alpine Linux.
7833 "altlinux"
7835 ALT Linux.
7836 "archlinux"
7838 Arch Linux.
7839 "buildroot"
7841 Buildroot-derived distro, but not one we specifically recognize.
7842 "centos"
7844 CentOS.
7845 "cirros"
7847 Cirros.
7848 "coreos"
7850 CoreOS.
7851 "debian"
7853 Debian.
7854 "fedora"
7856 Fedora.
7857 "freebsd"
7859 FreeBSD.
7860 "freedos"
7862 FreeDOS.
7863 "frugalware"
7865 Frugalware.
7866 "gentoo"
7868 Gentoo.
7869 "kalilinux"
7871 Kali Linux.
7872 "linuxmint"
7874 Linux Mint.
7875 "mageia"
7877 Mageia.
7878 "mandriva"
7880 Mandriva.
7881 "meego"
7883 MeeGo.
7884 "msdos"
7886 Microsoft DOS.
7887 "neokylin"
7889 NeoKylin.
7890 "netbsd"
7892 NetBSD.
7893 "openbsd"
7895 OpenBSD.
7896 "openmandriva"
7898 OpenMandriva Lx.
7899 "opensuse"
7901 OpenSUSE.
7902 "oraclelinux"
7904 Oracle Linux.
7905 "pardus"
7907 Pardus.
7908 "pldlinux"
7910 PLD Linux.
7911 "redhat-based"
7913 Some Red Hat-derived distro.
7914 "rhel"
7916 Red Hat Enterprise Linux.
7917 "scientificlinux"
7919 Scientific Linux.
7920 "slackware"
7922 Slackware.
7923 "sles"
7925 SuSE Linux Enterprise Server or Desktop.
7926 "suse-based"
7928 Some openSuSE-derived distro.
7929 "ttylinux"
7931 ttylinux.
7932 "ubuntu"
7934 Ubuntu.
7935 "unknown"
7937 The distro could not be determined.
7938 "voidlinux"
7940 Void Linux.
7941 "windows"
7943 Windows does not have distributions. This string is returned if
7944 the OS type is Windows.
7945 Future versions of libguestfs may return other strings here. The
7947 caller should be prepared to handle any string.
7948 Please read "INSPECTION" for more details.
7950 This function returns a string, or NULL on error. The caller must free
7952 the returned string after use.
7953 (Added in 1.5.3)
7955 guestfs_inspect_get_drive_mappings
7957 char **
7958 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7959 const char *root);
7960 This call is useful for Windows which uses a primitive system of
7962 assigning drive letters (like C:\) to partitions. This inspection API
7963 examines the Windows Registry to find out how disks/partitions are
7964 mapped to drive letters, and returns a hash table as in the example
7965 below:
7966 C => /dev/vda2
7968 E => /dev/vdb1
7969 F => /dev/vdc1
7970 Note that keys are drive letters. For Windows, the key is case
7972 insensitive and just contains the drive letter, without the customary
7973 colon separator character.
7974 In future we may support other operating systems that also used drive
7976 letters, but the keys for those might not be case insensitive and might
7977 be longer than 1 character. For example in OS-9, hard drives were
7978 named "h0", "h1" etc.
7979 For Windows guests, currently only hard drive mappings are returned.
7981 Removable disks (eg. DVD-ROMs) are ignored.
7982 For guests that do not use drive mappings, or if the drive mappings
7984 could not be determined, this returns an empty hash table.
7985 Please read "INSPECTION" for more details. See also
7987 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7988 This function returns a NULL-terminated array of strings, or NULL if
7990 there was an error. The array of strings will always have length
7991 "2n+1", where "n" keys and values alternate, followed by the trailing
7992 NULL entry. The caller must free the strings and the array after use.
7993 (Added in 1.9.17)
7995 guestfs_inspect_get_filesystems
7997 char **
7998 guestfs_inspect_get_filesystems (guestfs_h *g,
7999 const char *root);
8000 This returns a list of all the filesystems that we think are associated
8002 with this operating system. This includes the root filesystem, other
8003 ordinary filesystems, and non-mounted devices like swap partitions.
8004 In the case of a multi-boot virtual machine, it is possible for a
8006 filesystem to be shared between operating systems.
8007 Please read "INSPECTION" for more details. See also
8009 "guestfs_inspect_get_mountpoints".
8010 This function returns a NULL-terminated array of strings (like
8012 environ(3)), or NULL if there was an error. The caller must free the
8013 strings and the array after use.
8014 (Added in 1.5.3)
8016 guestfs_inspect_get_format
8018 char *
8019 guestfs_inspect_get_format (guestfs_h *g,
8020 const char *root);
8021 This function is deprecated. There is no replacement. Consult the API
8023 documentation in guestfs(3) for further information.
8024 Deprecated functions will not be removed from the API, but the fact
8026 that they are deprecated indicates that there are problems with correct
8027 use of these functions.
8028 Before libguestfs 1.38, there was some unreliable support for detecting
8030 installer CDs. This API would return:
8031 "installed"
8033 This is an installed operating system.
8034 "installer"
8036 The disk image being inspected is not an installed operating
8037 system, but a bootable install disk, live CD, or similar.
8038 "unknown"
8040 The format of this disk image is not known.
8041 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
8043 directly to detect installer CDs.
8044 Please read "INSPECTION" for more details.
8046 This function returns a string, or NULL on error. The caller must free
8048 the returned string after use.
8049 (Added in 1.9.4)
8051 guestfs_inspect_get_hostname
8053 char *
8054 guestfs_inspect_get_hostname (guestfs_h *g,
8055 const char *root);
8056 This function returns the hostname of the operating system as found by
8058 inspection of the guest’s configuration files.
8059 If the hostname could not be determined, then the string "unknown" is
8061 returned.
8062 Please read "INSPECTION" for more details.
8064 This function returns a string, or NULL on error. The caller must free
8066 the returned string after use.
8067 (Added in 1.7.9)
8069 guestfs_inspect_get_icon
8071 char *
8072 guestfs_inspect_get_icon (guestfs_h *g,
8073 const char *root,
8074 size_t *size_r,
8075 ...);
8076 You may supply a list of optional arguments to this call. Use zero or
8078 more of the following pairs of parameters, and terminate the list with
8079 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8080 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
8082 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
8083 This function returns an icon corresponding to the inspected operating
8085 system. The icon is returned as a buffer containing a PNG image (re-
8086 encoded to PNG if necessary).
8087 If it was not possible to get an icon this function returns a zero-
8089 length (non-NULL) buffer. Callers must check for this case.
8090 Libguestfs will start by looking for a file called /etc/favicon.png or
8092 C:\etc\favicon.png and if it has the correct format, the contents of
8093 this file will be returned. You can disable favicons by passing the
8094 optional "favicon" boolean as false (default is true).
8095 If finding the favicon fails, then we look in other places in the guest
8097 for a suitable icon.
8098 If the optional "highquality" boolean is true then only high quality
8100 icons are returned, which means only icons of high resolution with an
8101 alpha channel. The default (false) is to return any icon we can, even
8102 if it is of substandard quality.
8103 Notes:
8105 • Unlike most other inspection API calls, the guest’s disks must be
8107 mounted up before you call this, since it needs to read information
8108 from the guest filesystem during the call.
8109 • Security: The icon data comes from the untrusted guest, and should
8111 be treated with caution. PNG files have been known to contain
8112 exploits. Ensure that libpng (or other relevant libraries) are
8113 fully up to date before trying to process or display the icon.
8114 • The PNG image returned can be any size. It might not be square.
8116 Libguestfs tries to return the largest, highest quality icon
8117 available. The application must scale the icon to the required
8118 size.
8119 • Extracting icons from Windows guests requires the external
8121 wrestool(1) program from the "icoutils" package, and several
8122 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
8123 package. These must be installed separately.
8124 • Operating system icons are usually trademarks. Seek legal advice
8126 before using trademarks in applications.
8127 This function returns a buffer, or NULL on error. The size of the
8129 returned buffer is written to *size_r. The caller must free the
8130 returned buffer after use.
8131 (Added in 1.11.12)
8133 guestfs_inspect_get_icon_va
8135 char *
8136 guestfs_inspect_get_icon_va (guestfs_h *g,
8137 const char *root,
8138 size_t *size_r,
8139 va_list args);
8140 This is the "va_list variant" of "guestfs_inspect_get_icon".
8142 See "CALLS WITH OPTIONAL ARGUMENTS".
8144 guestfs_inspect_get_icon_argv
8146 char *
8147 guestfs_inspect_get_icon_argv (guestfs_h *g,
8148 const char *root,
8149 size_t *size_r,
8150 const struct guestfs_inspect_get_icon_argv *optargs);
8151 This is the "argv variant" of "guestfs_inspect_get_icon".
8153 See "CALLS WITH OPTIONAL ARGUMENTS".
8155 guestfs_inspect_get_major_version
8157 int
8158 guestfs_inspect_get_major_version (guestfs_h *g,
8159 const char *root);
8160 This returns the major version number of the inspected operating
8162 system.
8163 Windows uses a consistent versioning scheme which is not reflected in
8165 the popular public names used by the operating system. Notably the
8166 operating system known as "Windows 7" is really version 6.1 (ie. major
8167 = 6, minor = 1). You can find out the real versions corresponding to
8168 releases of Windows by consulting Wikipedia or MSDN.
8169 If the version could not be determined, then 0 is returned.
8171 Please read "INSPECTION" for more details.
8173 On error this function returns -1.
8175 (Added in 1.5.3)
8177 guestfs_inspect_get_minor_version
8179 int
8180 guestfs_inspect_get_minor_version (guestfs_h *g,
8181 const char *root);
8182 This returns the minor version number of the inspected operating
8184 system.
8185 If the version could not be determined, then 0 is returned.
8187 Please read "INSPECTION" for more details. See also
8189 "guestfs_inspect_get_major_version".
8190 On error this function returns -1.
8192 (Added in 1.5.3)
8194 guestfs_inspect_get_mountpoints
8196 char **
8197 guestfs_inspect_get_mountpoints (guestfs_h *g,
8198 const char *root);
8199 This returns a hash of where we think the filesystems associated with
8201 this operating system should be mounted. Callers should note that this
8202 is at best an educated guess made by reading configuration files such
8203 as /etc/fstab. In particular note that this may return filesystems
8204 which are non-existent or not mountable and callers should be prepared
8205 to handle or ignore failures if they try to mount them.
8206 Each element in the returned hashtable has a key which is the path of
8208 the mountpoint (eg. /boot) and a value which is the filesystem that
8209 would be mounted there (eg. /dev/sda1).
8210 Non-mounted devices such as swap devices are not returned in this list.
8212 For operating systems like Windows which still use drive letters, this
8214 call will only return an entry for the first drive "mounted on" /. For
8215 information about the mapping of drive letters to partitions, see
8216 "guestfs_inspect_get_drive_mappings".
8217 Please read "INSPECTION" for more details. See also
8219 "guestfs_inspect_get_filesystems".
8220 This function returns a NULL-terminated array of strings, or NULL if
8222 there was an error. The array of strings will always have length
8223 "2n+1", where "n" keys and values alternate, followed by the trailing
8224 NULL entry. The caller must free the strings and the array after use.
8225 (Added in 1.5.3)
8227 guestfs_inspect_get_osinfo
8229 char *
8230 guestfs_inspect_get_osinfo (guestfs_h *g,
8231 const char *root);
8232 This function returns a possible short ID for libosinfo corresponding
8234 to the guest.
8235 Note: The returned ID is only a guess by libguestfs, and nothing
8237 ensures that it actually exists in osinfo-db.
8238 If no ID could not be determined, then the string "unknown" is
8240 returned.
8241 This function returns a string, or NULL on error. The caller must free
8243 the returned string after use.
8244 (Added in 1.39.1)
8246 guestfs_inspect_get_package_format
8248 char *
8249 guestfs_inspect_get_package_format (guestfs_h *g,
8250 const char *root);
8251 This function and "guestfs_inspect_get_package_management" return the
8253 package format and package management tool used by the inspected
8254 operating system. For example for Fedora these functions would return
8255 "rpm" (package format), and "yum" or "dnf" (package management).
8256 This returns the string "unknown" if we could not determine the package
8258 format or if the operating system does not have a real packaging system
8259 (eg. Windows).
8260 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8262 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
8263 other strings.
8264 Please read "INSPECTION" for more details.
8266 This function returns a string, or NULL on error. The caller must free
8268 the returned string after use.
8269 (Added in 1.7.5)
8271 guestfs_inspect_get_package_management
8273 char *
8274 guestfs_inspect_get_package_management (guestfs_h *g,
8275 const char *root);
8276 "guestfs_inspect_get_package_format" and this function return the
8278 package format and package management tool used by the inspected
8279 operating system. For example for Fedora these functions would return
8280 "rpm" (package format), and "yum" or "dnf" (package management).
8281 This returns the string "unknown" if we could not determine the package
8283 management tool or if the operating system does not have a real
8284 packaging system (eg. Windows).
8285 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8287 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8288 "apk", "xbps". Future versions of libguestfs may return other strings.
8289 Please read "INSPECTION" for more details.
8291 This function returns a string, or NULL on error. The caller must free
8293 the returned string after use.
8294 (Added in 1.7.5)
8296 guestfs_inspect_get_product_name
8298 char *
8299 guestfs_inspect_get_product_name (guestfs_h *g,
8300 const char *root);
8301 This returns the product name of the inspected operating system. The
8303 product name is generally some freeform string which can be displayed
8304 to the user, but should not be parsed by programs.
8305 If the product name could not be determined, then the string "unknown"
8307 is returned.
8308 Please read "INSPECTION" for more details.
8310 This function returns a string, or NULL on error. The caller must free
8312 the returned string after use.
8313 (Added in 1.5.3)
8315 guestfs_inspect_get_product_variant
8317 char *
8318 guestfs_inspect_get_product_variant (guestfs_h *g,
8319 const char *root);
8320 This returns the product variant of the inspected operating system.
8322 For Windows guests, this returns the contents of the Registry key
8324 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8325 which is usually a string such as "Client" or "Server" (other values
8326 are possible). This can be used to distinguish consumer and enterprise
8327 versions of Windows that have the same version number (for example,
8328 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8329 is "Client" and the latter is "Server").
8330 For enterprise Linux guests, in future we intend this to return the
8332 product variant such as "Desktop", "Server" and so on. But this is not
8333 implemented at present.
8334 If the product variant could not be determined, then the string
8336 "unknown" is returned.
8337 Please read "INSPECTION" for more details. See also
8339 "guestfs_inspect_get_product_name",
8340 "guestfs_inspect_get_major_version".
8341 This function returns a string, or NULL on error. The caller must free
8343 the returned string after use.
8344 (Added in 1.9.13)
8346 guestfs_inspect_get_roots
8348 char **
8349 guestfs_inspect_get_roots (guestfs_h *g);
8350 This function is a convenient way to get the list of root devices, as
8352 returned from a previous call to "guestfs_inspect_os", but without
8353 redoing the whole inspection process.
8354 This returns an empty list if either no root devices were found or the
8356 caller has not called "guestfs_inspect_os".
8357 Please read "INSPECTION" for more details.
8359 This function returns a NULL-terminated array of strings (like
8361 environ(3)), or NULL if there was an error. The caller must free the
8362 strings and the array after use.
8363 (Added in 1.7.3)
8365 guestfs_inspect_get_type
8367 char *
8368 guestfs_inspect_get_type (guestfs_h *g,
8369 const char *root);
8370 This returns the type of the inspected operating system. Currently
8372 defined types are:
8373 "linux"
8375 Any Linux-based operating system.
8376 "windows"
8378 Any Microsoft Windows operating system.
8379 "freebsd"
8381 FreeBSD.
8382 "netbsd"
8384 NetBSD.
8385 "openbsd"
8387 OpenBSD.
8388 "hurd"
8390 GNU/Hurd.
8391 "dos"
8393 MS-DOS, FreeDOS and others.
8394 "minix"
8396 MINIX.
8397 "unknown"
8399 The operating system type could not be determined.
8400 Future versions of libguestfs may return other strings here. The
8402 caller should be prepared to handle any string.
8403 Please read "INSPECTION" for more details.
8405 This function returns a string, or NULL on error. The caller must free
8407 the returned string after use.
8408 (Added in 1.5.3)
8410 guestfs_inspect_get_windows_current_control_set
8412 char *
8413 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8414 const char *root);
8415 This returns the Windows CurrentControlSet of the inspected guest. The
8417 CurrentControlSet is a registry key name such as "ControlSet001".
8418 This call assumes that the guest is Windows and that the Registry could
8420 be examined by inspection. If this is not the case then an error is
8421 returned.
8422 Please read "INSPECTION" for more details.
8424 This function returns a string, or NULL on error. The caller must free
8426 the returned string after use.
8427 (Added in 1.9.17)
8429 guestfs_inspect_get_windows_software_hive
8431 char *
8432 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8433 const char *root);
8434 This returns the path to the hive (binary Windows Registry file)
8436 corresponding to HKLM\SOFTWARE.
8437 This call assumes that the guest is Windows and that the guest has a
8439 software hive file with the right name. If this is not the case then
8440 an error is returned. This call does not check that the hive is a
8441 valid Windows Registry hive.
8442 You can use "guestfs_hivex_open" to read or write to the hive.
8444 Please read "INSPECTION" for more details.
8446 This function returns a string, or NULL on error. The caller must free
8448 the returned string after use.
8449 (Added in 1.35.26)
8451 guestfs_inspect_get_windows_system_hive
8453 char *
8454 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8455 const char *root);
8456 This returns the path to the hive (binary Windows Registry file)
8458 corresponding to HKLM\SYSTEM.
8459 This call assumes that the guest is Windows and that the guest has a
8461 system hive file with the right name. If this is not the case then an
8462 error is returned. This call does not check that the hive is a valid
8463 Windows Registry hive.
8464 You can use "guestfs_hivex_open" to read or write to the hive.
8466 Please read "INSPECTION" for more details.
8468 This function returns a string, or NULL on error. The caller must free
8470 the returned string after use.
8471 (Added in 1.35.26)
8473 guestfs_inspect_get_windows_systemroot
8475 char *
8476 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8477 const char *root);
8478 This returns the Windows systemroot of the inspected guest. The
8480 systemroot is a directory path such as /WINDOWS.
8481 This call assumes that the guest is Windows and that the systemroot
8483 could be determined by inspection. If this is not the case then an
8484 error is returned.
8485 Please read "INSPECTION" for more details.
8487 This function returns a string, or NULL on error. The caller must free
8489 the returned string after use.
8490 (Added in 1.5.25)
8492 guestfs_inspect_is_live
8494 int
8495 guestfs_inspect_is_live (guestfs_h *g,
8496 const char *root);
8497 This function is deprecated. There is no replacement. Consult the API
8499 documentation in guestfs(3) for further information.
8500 Deprecated functions will not be removed from the API, but the fact
8502 that they are deprecated indicates that there are problems with correct
8503 use of these functions.
8504 This is deprecated and always returns "false".
8506 Please read "INSPECTION" for more details.
8508 This function returns a C truth value on success or -1 on error.
8510 (Added in 1.9.4)
8512 guestfs_inspect_is_multipart
8514 int
8515 guestfs_inspect_is_multipart (guestfs_h *g,
8516 const char *root);
8517 This function is deprecated. There is no replacement. Consult the API
8519 documentation in guestfs(3) for further information.
8520 Deprecated functions will not be removed from the API, but the fact
8522 that they are deprecated indicates that there are problems with correct
8523 use of these functions.
8524 This is deprecated and always returns "false".
8526 Please read "INSPECTION" for more details.
8528 This function returns a C truth value on success or -1 on error.
8530 (Added in 1.9.4)
8532 guestfs_inspect_is_netinst
8534 int
8535 guestfs_inspect_is_netinst (guestfs_h *g,
8536 const char *root);
8537 This function is deprecated. There is no replacement. Consult the API
8539 documentation in guestfs(3) for further information.
8540 Deprecated functions will not be removed from the API, but the fact
8542 that they are deprecated indicates that there are problems with correct
8543 use of these functions.
8544 This is deprecated and always returns "false".
8546 Please read "INSPECTION" for more details.
8548 This function returns a C truth value on success or -1 on error.
8550 (Added in 1.9.4)
8552 guestfs_inspect_list_applications
8554 struct guestfs_application_list *
8555 guestfs_inspect_list_applications (guestfs_h *g,
8556 const char *root);
8557 This function is deprecated. In new code, use the
8559 "guestfs_inspect_list_applications2" call instead.
8560 Deprecated functions will not be removed from the API, but the fact
8562 that they are deprecated indicates that there are problems with correct
8563 use of these functions.
8564 Return the list of applications installed in the operating system.
8566 Note: This call works differently from other parts of the inspection
8568 API. You have to call "guestfs_inspect_os", then
8569 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8570 calling this. Listing applications is a significantly more difficult
8571 operation which requires access to the full filesystem. Also note that
8572 unlike the other "guestfs_inspect_get_*" calls which are just returning
8573 data cached in the libguestfs handle, this call actually reads parts of
8574 the mounted filesystems during the call.
8575 This returns an empty list if the inspection code was not able to
8577 determine the list of applications.
8578 The application structure contains the following fields:
8580 "app_name"
8582 The name of the application. For Linux guests, this is the package
8583 name.
8584 "app_display_name"
8586 The display name of the application, sometimes localized to the
8587 install language of the guest operating system.
8588 If unavailable this is returned as an empty string "". Callers
8590 needing to display something can use "app_name" instead.
8591 "app_epoch"
8593 For package managers which use epochs, this contains the epoch of
8594 the package (an integer). If unavailable, this is returned as 0.
8595 "app_version"
8597 The version string of the application or package. If unavailable
8598 this is returned as an empty string "".
8599 "app_release"
8601 The release string of the application or package, for package
8602 managers that use this. If unavailable this is returned as an
8603 empty string "".
8604 "app_install_path"
8606 The installation path of the application (on operating systems such
8607 as Windows which use installation paths). This path is in the
8608 format used by the guest operating system, it is not a libguestfs
8609 path.
8610 If unavailable this is returned as an empty string "".
8612 "app_trans_path"
8614 The install path translated into a libguestfs path. If unavailable
8615 this is returned as an empty string "".
8616 "app_publisher"
8618 The name of the publisher of the application, for package managers
8619 that use this. If unavailable this is returned as an empty string
8620 "".
8621 "app_url"
8623 The URL (eg. upstream URL) of the application. If unavailable this
8624 is returned as an empty string "".
8625 "app_source_package"
8627 For packaging systems which support this, the name of the source
8628 package. If unavailable this is returned as an empty string "".
8629 "app_summary"
8631 A short (usually one line) description of the application or
8632 package. If unavailable this is returned as an empty string "".
8633 "app_description"
8635 A longer description of the application or package. If unavailable
8636 this is returned as an empty string "".
8637 Please read "INSPECTION" for more details.
8639 This function returns a "struct guestfs_application_list *", or NULL if
8641 there was an error. The caller must call
8642 "guestfs_free_application_list" after use.
8643 (Added in 1.7.8)
8645 guestfs_inspect_list_applications2
8647 struct guestfs_application2_list *
8648 guestfs_inspect_list_applications2 (guestfs_h *g,
8649 const char *root);
8650 Return the list of applications installed in the operating system.
8652 Note: This call works differently from other parts of the inspection
8654 API. You have to call "guestfs_inspect_os", then
8655 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8656 calling this. Listing applications is a significantly more difficult
8657 operation which requires access to the full filesystem. Also note that
8658 unlike the other "guestfs_inspect_get_*" calls which are just returning
8659 data cached in the libguestfs handle, this call actually reads parts of
8660 the mounted filesystems during the call.
8661 This returns an empty list if the inspection code was not able to
8663 determine the list of applications.
8664 The application structure contains the following fields:
8666 "app2_name"
8668 The name of the application. For Linux guests, this is the package
8669 name.
8670 "app2_display_name"
8672 The display name of the application, sometimes localized to the
8673 install language of the guest operating system.
8674 If unavailable this is returned as an empty string "". Callers
8676 needing to display something can use "app2_name" instead.
8677 "app2_epoch"
8679 For package managers which use epochs, this contains the epoch of
8680 the package (an integer). If unavailable, this is returned as 0.
8681 "app2_version"
8683 The version string of the application or package. If unavailable
8684 this is returned as an empty string "".
8685 "app2_release"
8687 The release string of the application or package, for package
8688 managers that use this. If unavailable this is returned as an
8689 empty string "".
8690 "app2_arch"
8692 The architecture string of the application or package, for package
8693 managers that use this. If unavailable this is returned as an
8694 empty string "".
8695 "app2_install_path"
8697 The installation path of the application (on operating systems such
8698 as Windows which use installation paths). This path is in the
8699 format used by the guest operating system, it is not a libguestfs
8700 path.
8701 If unavailable this is returned as an empty string "".
8703 "app2_trans_path"
8705 The install path translated into a libguestfs path. If unavailable
8706 this is returned as an empty string "".
8707 "app2_publisher"
8709 The name of the publisher of the application, for package managers
8710 that use this. If unavailable this is returned as an empty string
8711 "".
8712 "app2_url"
8714 The URL (eg. upstream URL) of the application. If unavailable this
8715 is returned as an empty string "".
8716 "app2_source_package"
8718 For packaging systems which support this, the name of the source
8719 package. If unavailable this is returned as an empty string "".
8720 "app2_summary"
8722 A short (usually one line) description of the application or
8723 package. If unavailable this is returned as an empty string "".
8724 "app2_description"
8726 A longer description of the application or package. If unavailable
8727 this is returned as an empty string "".
8728 Please read "INSPECTION" for more details.
8730 This function returns a "struct guestfs_application2_list *", or NULL
8732 if there was an error. The caller must call
8733 "guestfs_free_application2_list" after use.
8734 (Added in 1.19.56)
8736 guestfs_inspect_os
8738 char **
8739 guestfs_inspect_os (guestfs_h *g);
8740 This function uses other libguestfs functions and certain heuristics to
8742 inspect the disk(s) (usually disks belonging to a virtual machine),
8743 looking for operating systems.
8744 The list returned is empty if no operating systems were found.
8746 If one operating system was found, then this returns a list with a
8748 single element, which is the name of the root filesystem of this
8749 operating system. It is also possible for this function to return a
8750 list containing more than one element, indicating a dual-boot or multi-
8751 boot virtual machine, with each element being the root filesystem of
8752 one of the operating systems.
8753 You can pass the root string(s) returned to other
8755 "guestfs_inspect_get_*" functions in order to query further information
8756 about each operating system, such as the name and version.
8757 This function uses other libguestfs features such as "guestfs_mount_ro"
8759 and "guestfs_umount_all" in order to mount and unmount filesystems and
8760 look at the contents. This should be called with no disks currently
8761 mounted. The function may also use Augeas, so any existing Augeas
8762 handle will be closed.
8763 This function cannot decrypt encrypted disks. The caller must do that
8765 first (supplying the necessary keys) if the disk is encrypted.
8766 Please read "INSPECTION" for more details.
8768 See also "guestfs_list_filesystems".
8770 This function returns a NULL-terminated array of strings (like
8772 environ(3)), or NULL if there was an error. The caller must free the
8773 strings and the array after use.
8774 (Added in 1.5.3)
8776 guestfs_is_blockdev
8778 int
8779 guestfs_is_blockdev (guestfs_h *g,
8780 const char *path);
8781 This function is provided for backwards compatibility with earlier
8783 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8784 with no optional arguments.
8785 (Added in 1.5.10)
8787 guestfs_is_blockdev_opts
8789 int
8790 guestfs_is_blockdev_opts (guestfs_h *g,
8791 const char *path,
8792 ...);
8793 You may supply a list of optional arguments to this call. Use zero or
8795 more of the following pairs of parameters, and terminate the list with
8796 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8797 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8799 This returns "true" if and only if there is a block device with the
8801 given "path" name.
8802 If the optional flag "followsymlinks" is true, then a symlink (or chain
8804 of symlinks) that ends with a block device also causes the function to
8805 return true.
8806 This call only looks at files within the guest filesystem. Libguestfs
8808 partitions and block devices (eg. /dev/sda) cannot be used as the
8809 "path" parameter of this call.
8810 See also "guestfs_stat".
8812 This function returns a C truth value on success or -1 on error.
8814 (Added in 1.5.10)
8816 guestfs_is_blockdev_opts_va
8818 int
8819 guestfs_is_blockdev_opts_va (guestfs_h *g,
8820 const char *path,
8821 va_list args);
8822 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8824 See "CALLS WITH OPTIONAL ARGUMENTS".
8826 guestfs_is_blockdev_opts_argv
8828 int
8829 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8830 const char *path,
8831 const struct guestfs_is_blockdev_opts_argv *optargs);
8832 This is the "argv variant" of "guestfs_is_blockdev_opts".
8834 See "CALLS WITH OPTIONAL ARGUMENTS".
8836 guestfs_is_busy
8838 int
8839 guestfs_is_busy (guestfs_h *g);
8840 This always returns false. This function is deprecated with no
8842 replacement. Do not use this function.
8843 For more information on states, see guestfs(3).
8845 This function returns a C truth value on success or -1 on error.
8847 (Added in 1.0.2)
8849 guestfs_is_chardev
8851 int
8852 guestfs_is_chardev (guestfs_h *g,
8853 const char *path);
8854 This function is provided for backwards compatibility with earlier
8856 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8857 no optional arguments.
8858 (Added in 1.5.10)
8860 guestfs_is_chardev_opts
8862 int
8863 guestfs_is_chardev_opts (guestfs_h *g,
8864 const char *path,
8865 ...);
8866 You may supply a list of optional arguments to this call. Use zero or
8868 more of the following pairs of parameters, and terminate the list with
8869 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8870 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8872 This returns "true" if and only if there is a character device with the
8874 given "path" name.
8875 If the optional flag "followsymlinks" is true, then a symlink (or chain
8877 of symlinks) that ends with a chardev also causes the function to
8878 return true.
8879 See also "guestfs_stat".
8881 This function returns a C truth value on success or -1 on error.
8883 (Added in 1.5.10)
8885 guestfs_is_chardev_opts_va
8887 int
8888 guestfs_is_chardev_opts_va (guestfs_h *g,
8889 const char *path,
8890 va_list args);
8891 This is the "va_list variant" of "guestfs_is_chardev_opts".
8893 See "CALLS WITH OPTIONAL ARGUMENTS".
8895 guestfs_is_chardev_opts_argv
8897 int
8898 guestfs_is_chardev_opts_argv (guestfs_h *g,
8899 const char *path,
8900 const struct guestfs_is_chardev_opts_argv *optargs);
8901 This is the "argv variant" of "guestfs_is_chardev_opts".
8903 See "CALLS WITH OPTIONAL ARGUMENTS".
8905 guestfs_is_config
8907 int
8908 guestfs_is_config (guestfs_h *g);
8909 This returns true iff this handle is being configured (in the "CONFIG"
8911 state).
8912 For more information on states, see guestfs(3).
8914 This function returns a C truth value on success or -1 on error.
8916 (Added in 1.0.2)
8918 guestfs_is_dir
8920 int
8921 guestfs_is_dir (guestfs_h *g,
8922 const char *path);
8923 This function is provided for backwards compatibility with earlier
8925 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8926 optional arguments.
8927 (Added in 0.8)
8929 guestfs_is_dir_opts
8931 int
8932 guestfs_is_dir_opts (guestfs_h *g,
8933 const char *path,
8934 ...);
8935 You may supply a list of optional arguments to this call. Use zero or
8937 more of the following pairs of parameters, and terminate the list with
8938 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8939 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8941 This returns "true" if and only if there is a directory with the given
8943 "path" name. Note that it returns false for other objects like files.
8944 If the optional flag "followsymlinks" is true, then a symlink (or chain
8946 of symlinks) that ends with a directory also causes the function to
8947 return true.
8948 See also "guestfs_stat".
8950 This function returns a C truth value on success or -1 on error.
8952 (Added in 0.8)
8954 guestfs_is_dir_opts_va
8956 int
8957 guestfs_is_dir_opts_va (guestfs_h *g,
8958 const char *path,
8959 va_list args);
8960 This is the "va_list variant" of "guestfs_is_dir_opts".
8962 See "CALLS WITH OPTIONAL ARGUMENTS".
8964 guestfs_is_dir_opts_argv
8966 int
8967 guestfs_is_dir_opts_argv (guestfs_h *g,
8968 const char *path,
8969 const struct guestfs_is_dir_opts_argv *optargs);
8970 This is the "argv variant" of "guestfs_is_dir_opts".
8972 See "CALLS WITH OPTIONAL ARGUMENTS".
8974 guestfs_is_fifo
8976 int
8977 guestfs_is_fifo (guestfs_h *g,
8978 const char *path);
8979 This function is provided for backwards compatibility with earlier
8981 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8982 optional arguments.
8983 (Added in 1.5.10)
8985 guestfs_is_fifo_opts
8987 int
8988 guestfs_is_fifo_opts (guestfs_h *g,
8989 const char *path,
8990 ...);
8991 You may supply a list of optional arguments to this call. Use zero or
8993 more of the following pairs of parameters, and terminate the list with
8994 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8995 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8997 This returns "true" if and only if there is a FIFO (named pipe) with
8999 the given "path" name.
9000 If the optional flag "followsymlinks" is true, then a symlink (or chain
9002 of symlinks) that ends with a FIFO also causes the function to return
9003 true.
9004 See also "guestfs_stat".
9006 This function returns a C truth value on success or -1 on error.
9008 (Added in 1.5.10)
9010 guestfs_is_fifo_opts_va
9012 int
9013 guestfs_is_fifo_opts_va (guestfs_h *g,
9014 const char *path,
9015 va_list args);
9016 This is the "va_list variant" of "guestfs_is_fifo_opts".
9018 See "CALLS WITH OPTIONAL ARGUMENTS".
9020 guestfs_is_fifo_opts_argv
9022 int
9023 guestfs_is_fifo_opts_argv (guestfs_h *g,
9024 const char *path,
9025 const struct guestfs_is_fifo_opts_argv *optargs);
9026 This is the "argv variant" of "guestfs_is_fifo_opts".
9028 See "CALLS WITH OPTIONAL ARGUMENTS".
9030 guestfs_is_file
9032 int
9033 guestfs_is_file (guestfs_h *g,
9034 const char *path);
9035 This function is provided for backwards compatibility with earlier
9037 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
9038 optional arguments.
9039 (Added in 0.8)
9041 guestfs_is_file_opts
9043 int
9044 guestfs_is_file_opts (guestfs_h *g,
9045 const char *path,
9046 ...);
9047 You may supply a list of optional arguments to this call. Use zero or
9049 more of the following pairs of parameters, and terminate the list with
9050 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9051 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9053 This returns "true" if and only if there is a regular file with the
9055 given "path" name. Note that it returns false for other objects like
9056 directories.
9057 If the optional flag "followsymlinks" is true, then a symlink (or chain
9059 of symlinks) that ends with a file also causes the function to return
9060 true.
9061 See also "guestfs_stat".
9063 This function returns a C truth value on success or -1 on error.
9065 (Added in 0.8)
9067 guestfs_is_file_opts_va
9069 int
9070 guestfs_is_file_opts_va (guestfs_h *g,
9071 const char *path,
9072 va_list args);
9073 This is the "va_list variant" of "guestfs_is_file_opts".
9075 See "CALLS WITH OPTIONAL ARGUMENTS".
9077 guestfs_is_file_opts_argv
9079 int
9080 guestfs_is_file_opts_argv (guestfs_h *g,
9081 const char *path,
9082 const struct guestfs_is_file_opts_argv *optargs);
9083 This is the "argv variant" of "guestfs_is_file_opts".
9085 See "CALLS WITH OPTIONAL ARGUMENTS".
9087 guestfs_is_launching
9089 int
9090 guestfs_is_launching (guestfs_h *g);
9091 This returns true iff this handle is launching the subprocess (in the
9093 "LAUNCHING" state).
9094 For more information on states, see guestfs(3).
9096 This function returns a C truth value on success or -1 on error.
9098 (Added in 1.0.2)
9100 guestfs_is_lv
9102 int
9103 guestfs_is_lv (guestfs_h *g,
9104 const char *mountable);
9105 This command tests whether "mountable" is a logical volume, and returns
9107 true iff this is the case.
9108 This function returns a C truth value on success or -1 on error.
9110 (Added in 1.5.3)
9112 guestfs_is_ready
9114 int
9115 guestfs_is_ready (guestfs_h *g);
9116 This returns true iff this handle is ready to accept commands (in the
9118 "READY" state).
9119 For more information on states, see guestfs(3).
9121 This function returns a C truth value on success or -1 on error.
9123 (Added in 1.0.2)
9125 guestfs_is_socket
9127 int
9128 guestfs_is_socket (guestfs_h *g,
9129 const char *path);
9130 This function is provided for backwards compatibility with earlier
9132 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
9133 no optional arguments.
9134 (Added in 1.5.10)
9136 guestfs_is_socket_opts
9138 int
9139 guestfs_is_socket_opts (guestfs_h *g,
9140 const char *path,
9141 ...);
9142 You may supply a list of optional arguments to this call. Use zero or
9144 more of the following pairs of parameters, and terminate the list with
9145 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9146 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9148 This returns "true" if and only if there is a Unix domain socket with
9150 the given "path" name.
9151 If the optional flag "followsymlinks" is true, then a symlink (or chain
9153 of symlinks) that ends with a socket also causes the function to return
9154 true.
9155 See also "guestfs_stat".
9157 This function returns a C truth value on success or -1 on error.
9159 (Added in 1.5.10)
9161 guestfs_is_socket_opts_va
9163 int
9164 guestfs_is_socket_opts_va (guestfs_h *g,
9165 const char *path,
9166 va_list args);
9167 This is the "va_list variant" of "guestfs_is_socket_opts".
9169 See "CALLS WITH OPTIONAL ARGUMENTS".
9171 guestfs_is_socket_opts_argv
9173 int
9174 guestfs_is_socket_opts_argv (guestfs_h *g,
9175 const char *path,
9176 const struct guestfs_is_socket_opts_argv *optargs);
9177 This is the "argv variant" of "guestfs_is_socket_opts".
9179 See "CALLS WITH OPTIONAL ARGUMENTS".
9181 guestfs_is_symlink
9183 int
9184 guestfs_is_symlink (guestfs_h *g,
9185 const char *path);
9186 This returns "true" if and only if there is a symbolic link with the
9188 given "path" name.
9189 See also "guestfs_stat".
9191 This function returns a C truth value on success or -1 on error.
9193 (Added in 1.5.10)
9195 guestfs_is_whole_device
9197 int
9198 guestfs_is_whole_device (guestfs_h *g,
9199 const char *device);
9200 This returns "true" if and only if "device" refers to a whole block
9202 device. That is, not a partition or a logical device.
9203 This function returns a C truth value on success or -1 on error.
9205 (Added in 1.21.9)
9207 guestfs_is_zero
9209 int
9210 guestfs_is_zero (guestfs_h *g,
9211 const char *path);
9212 This returns true iff the file exists and the file is empty or it
9214 contains all zero bytes.
9215 This function returns a C truth value on success or -1 on error.
9217 (Added in 1.11.8)
9219 guestfs_is_zero_device
9221 int
9222 guestfs_is_zero_device (guestfs_h *g,
9223 const char *device);
9224 This returns true iff the device exists and contains all zero bytes.
9226 Note that for large devices this can take a long time to run.
9228 This function returns a C truth value on success or -1 on error.
9230 (Added in 1.11.8)
9232 guestfs_isoinfo
9234 struct guestfs_isoinfo *
9235 guestfs_isoinfo (guestfs_h *g,
9236 const char *isofile);
9237 This is the same as "guestfs_isoinfo_device" except that it works for
9239 an ISO file located inside some other mounted filesystem. Note that in
9240 the common case where you have added an ISO file as a libguestfs
9241 device, you would not call this. Instead you would call
9242 "guestfs_isoinfo_device".
9243 This function returns a "struct guestfs_isoinfo *", or NULL if there
9245 was an error. The caller must call "guestfs_free_isoinfo" after use.
9246 (Added in 1.17.19)
9248 guestfs_isoinfo_device
9250 struct guestfs_isoinfo *
9251 guestfs_isoinfo_device (guestfs_h *g,
9252 const char *device);
9253 "device" is an ISO device. This returns a struct of information read
9255 from the primary volume descriptor (the ISO equivalent of the
9256 superblock) of the device.
9257 Usually it is more efficient to use the isoinfo(1) command with the -d
9259 option on the host to analyze ISO files, instead of going through
9260 libguestfs.
9261 For information on the primary volume descriptor fields, see
9263 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9264 This function returns a "struct guestfs_isoinfo *", or NULL if there
9266 was an error. The caller must call "guestfs_free_isoinfo" after use.
9267 (Added in 1.17.19)
9269 guestfs_journal_close
9271 int
9272 guestfs_journal_close (guestfs_h *g);
9273 Close the journal handle.
9275 This function returns 0 on success or -1 on error.
9277 This function depends on the feature "journal". See also
9279 "guestfs_feature_available".
9280 (Added in 1.23.11)
9282 guestfs_journal_get
9284 struct guestfs_xattr_list *
9285 guestfs_journal_get (guestfs_h *g);
9286 Read the current journal entry. This returns all the fields in the
9288 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
9289 field name (a string).
9290 The "attrval" is the field value (a binary blob, often but not always a
9292 string). Please note that "attrval" is a byte array, not a
9293 \0-terminated C string.
9294 The length of data may be truncated to the data threshold (see:
9296 "guestfs_journal_set_data_threshold",
9297 "guestfs_journal_get_data_threshold").
9298 If you set the data threshold to unlimited (0) then this call can read
9300 a journal entry of any size, ie. it is not limited by the libguestfs
9301 protocol.
9302 This function returns a "struct guestfs_xattr_list *", or NULL if there
9304 was an error. The caller must call "guestfs_free_xattr_list" after
9305 use.
9306 This function depends on the feature "journal". See also
9308 "guestfs_feature_available".
9309 (Added in 1.23.11)
9311 guestfs_journal_get_data_threshold
9313 int64_t
9314 guestfs_journal_get_data_threshold (guestfs_h *g);
9315 Get the current data threshold for reading journal entries. This is a
9317 hint to the journal that it may truncate data fields to this size when
9318 reading them (note also that it may not truncate them). If this
9319 returns 0, then the threshold is unlimited.
9320 See also "guestfs_journal_set_data_threshold".
9322 On error this function returns -1.
9324 This function depends on the feature "journal". See also
9326 "guestfs_feature_available".
9327 (Added in 1.23.11)
9329 guestfs_journal_get_realtime_usec
9331 int64_t
9332 guestfs_journal_get_realtime_usec (guestfs_h *g);
9333 Get the realtime (wallclock) timestamp of the current journal entry.
9335 On error this function returns -1.
9337 This function depends on the feature "journal". See also
9339 "guestfs_feature_available".
9340 (Added in 1.27.18)
9342 guestfs_journal_next
9344 int
9345 guestfs_journal_next (guestfs_h *g);
9346 Move to the next journal entry. You have to call this at least once
9348 after opening the handle before you are able to read data.
9349 The returned boolean tells you if there are any more journal records to
9351 read. "true" means you can read the next record (eg. using
9352 "guestfs_journal_get"), and "false" means you have reached the end of
9353 the journal.
9354 This function returns a C truth value on success or -1 on error.
9356 This function depends on the feature "journal". See also
9358 "guestfs_feature_available".
9359 (Added in 1.23.11)
9361 guestfs_journal_open
9363 int
9364 guestfs_journal_open (guestfs_h *g,
9365 const char *directory);
9366 Open the systemd journal located in directory. Any previously opened
9368 journal handle is closed.
9369 The contents of the journal can be read using "guestfs_journal_next"
9371 and "guestfs_journal_get".
9372 After you have finished using the journal, you should close the handle
9374 by calling "guestfs_journal_close".
9375 This function returns 0 on success or -1 on error.
9377 This function depends on the feature "journal". See also
9379 "guestfs_feature_available".
9380 (Added in 1.23.11)
9382 guestfs_journal_set_data_threshold
9384 int
9385 guestfs_journal_set_data_threshold (guestfs_h *g,
9386 int64_t threshold);
9387 Set the data threshold for reading journal entries. This is a hint to
9389 the journal that it may truncate data fields to this size when reading
9390 them (note also that it may not truncate them). If you set this to 0,
9391 then the threshold is unlimited.
9392 See also "guestfs_journal_get_data_threshold".
9394 This function returns 0 on success or -1 on error.
9396 This function depends on the feature "journal". See also
9398 "guestfs_feature_available".
9399 (Added in 1.23.11)
9401 guestfs_journal_skip
9403 int64_t
9404 guestfs_journal_skip (guestfs_h *g,
9405 int64_t skip);
9406 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9408 The number of entries actually skipped is returned (note "rskip ≥ 0").
9410 If this is not the same as the absolute value of the skip parameter
9411 ("|skip|") you passed in then it means you have reached the end or the
9412 start of the journal.
9413 On error this function returns -1.
9415 This function depends on the feature "journal". See also
9417 "guestfs_feature_available".
9418 (Added in 1.23.11)
9420 guestfs_kill_subprocess
9422 int
9423 guestfs_kill_subprocess (guestfs_h *g);
9424 This function is deprecated. In new code, use the "guestfs_shutdown"
9426 call instead.
9427 Deprecated functions will not be removed from the API, but the fact
9429 that they are deprecated indicates that there are problems with correct
9430 use of these functions.
9431 This kills the hypervisor.
9433 Do not call this. See: "guestfs_shutdown" instead.
9435 This function returns 0 on success or -1 on error.
9437 (Added in 0.3)
9439 guestfs_launch
9441 int
9442 guestfs_launch (guestfs_h *g);
9443 You should call this after configuring the handle (eg. adding drives)
9445 but before performing any actions.
9446 Do not call "guestfs_launch" twice on the same handle. Although it
9448 will not give an error (for historical reasons), the precise behaviour
9449 when you do this is not well defined. Handles are very cheap to
9450 create, so create a new one for each launch.
9451 This function returns 0 on success or -1 on error.
9453 This long-running command can generate progress notification messages
9455 so that the caller can display a progress bar or indicator. To receive
9456 these messages, the caller must register a progress event callback.
9457 See "GUESTFS_EVENT_PROGRESS".
9458 (Added in 0.3)
9460 guestfs_lchown
9462 int
9463 guestfs_lchown (guestfs_h *g,
9464 int owner,
9465 int group,
9466 const char *path);
9467 Change the file owner to "owner" and group to "group". This is like
9469 "guestfs_chown" but if "path" is a symlink then the link itself is
9470 changed, not the target.
9471 Only numeric uid and gid are supported. If you want to use names, you
9473 will need to locate and parse the password file yourself (Augeas
9474 support makes this relatively easy).
9475 This function returns 0 on success or -1 on error.
9477 (Added in 1.0.77)
9479 guestfs_ldmtool_create_all
9481 int
9482 guestfs_ldmtool_create_all (guestfs_h *g);
9483 This function scans all block devices looking for Windows dynamic disk
9485 volumes and partitions, and creates devices for any that were found.
9486 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9488 return all devices.
9489 Note that you don't normally need to call this explicitly, since it is
9491 done automatically at "guestfs_launch" time. However you might want to
9492 call this function if you have hotplugged disks or have just created a
9493 Windows dynamic disk.
9494 This function returns 0 on success or -1 on error.
9496 This function depends on the feature "ldm". See also
9498 "guestfs_feature_available".
9499 (Added in 1.20.0)
9501 guestfs_ldmtool_diskgroup_disks
9503 char **
9504 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9505 const char *diskgroup);
9506 Return the disks in a Windows dynamic disk group. The "diskgroup"
9508 parameter should be the GUID of a disk group, one element from the list
9509 returned by "guestfs_ldmtool_scan".
9510 This function returns a NULL-terminated array of strings (like
9512 environ(3)), or NULL if there was an error. The caller must free the
9513 strings and the array after use.
9514 This function depends on the feature "ldm". See also
9516 "guestfs_feature_available".
9517 (Added in 1.20.0)
9519 guestfs_ldmtool_diskgroup_name
9521 char *
9522 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9523 const char *diskgroup);
9524 Return the name of a Windows dynamic disk group. The "diskgroup"
9526 parameter should be the GUID of a disk group, one element from the list
9527 returned by "guestfs_ldmtool_scan".
9528 This function returns a string, or NULL on error. The caller must free
9530 the returned string after use.
9531 This function depends on the feature "ldm". See also
9533 "guestfs_feature_available".
9534 (Added in 1.20.0)
9536 guestfs_ldmtool_diskgroup_volumes
9538 char **
9539 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9540 const char *diskgroup);
9541 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9543 parameter should be the GUID of a disk group, one element from the list
9544 returned by "guestfs_ldmtool_scan".
9545 This function returns a NULL-terminated array of strings (like
9547 environ(3)), or NULL if there was an error. The caller must free the
9548 strings and the array after use.
9549 This function depends on the feature "ldm". See also
9551 "guestfs_feature_available".
9552 (Added in 1.20.0)
9554 guestfs_ldmtool_remove_all
9556 int
9557 guestfs_ldmtool_remove_all (guestfs_h *g);
9558 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9560 removes the device mapper mappings for all Windows dynamic disk volumes
9561 This function returns 0 on success or -1 on error.
9563 This function depends on the feature "ldm". See also
9565 "guestfs_feature_available".
9566 (Added in 1.20.0)
9568 guestfs_ldmtool_scan
9570 char **
9571 guestfs_ldmtool_scan (guestfs_h *g);
9572 This function scans for Windows dynamic disks. It returns a list of
9574 identifiers (GUIDs) for all disk groups that were found. These
9575 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9576 This function scans all block devices. To scan a subset of block
9578 devices, call "guestfs_ldmtool_scan_devices" instead.
9579 This function returns a NULL-terminated array of strings (like
9581 environ(3)), or NULL if there was an error. The caller must free the
9582 strings and the array after use.
9583 This function depends on the feature "ldm". See also
9585 "guestfs_feature_available".
9586 (Added in 1.20.0)
9588 guestfs_ldmtool_scan_devices
9590 char **
9591 guestfs_ldmtool_scan_devices (guestfs_h *g,
9592 char *const *devices);
9593 This function scans for Windows dynamic disks. It returns a list of
9595 identifiers (GUIDs) for all disk groups that were found. These
9596 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9597 The parameter "devices" is a list of block devices which are scanned.
9599 If this list is empty, all block devices are scanned.
9600 This function returns a NULL-terminated array of strings (like
9602 environ(3)), or NULL if there was an error. The caller must free the
9603 strings and the array after use.
9604 This function depends on the feature "ldm". See also
9606 "guestfs_feature_available".
9607 (Added in 1.20.0)
9609 guestfs_ldmtool_volume_hint
9611 char *
9612 guestfs_ldmtool_volume_hint (guestfs_h *g,
9613 const char *diskgroup,
9614 const char *volume);
9615 Return the hint field of the volume named "volume" in the disk group
9617 with GUID "diskgroup". This may not be defined, in which case the
9618 empty string is returned. The hint field is often, though not always,
9619 the name of a Windows drive, eg. "E:".
9620 This function returns a string, or NULL on error. The caller must free
9622 the returned string after use.
9623 This function depends on the feature "ldm". See also
9625 "guestfs_feature_available".
9626 (Added in 1.20.0)
9628 guestfs_ldmtool_volume_partitions
9630 char **
9631 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9632 const char *diskgroup,
9633 const char *volume);
9634 Return the list of partitions in the volume named "volume" in the disk
9636 group with GUID "diskgroup".
9637 This function returns a NULL-terminated array of strings (like
9639 environ(3)), or NULL if there was an error. The caller must free the
9640 strings and the array after use.
9641 This function depends on the feature "ldm". See also
9643 "guestfs_feature_available".
9644 (Added in 1.20.0)
9646 guestfs_ldmtool_volume_type
9648 char *
9649 guestfs_ldmtool_volume_type (guestfs_h *g,
9650 const char *diskgroup,
9651 const char *volume);
9652 Return the type of the volume named "volume" in the disk group with
9654 GUID "diskgroup".
9655 Possible volume types that can be returned here include: "simple",
9657 "spanned", "striped", "mirrored", "raid5". Other types may also be
9658 returned.
9659 This function returns a string, or NULL on error. The caller must free
9661 the returned string after use.
9662 This function depends on the feature "ldm". See also
9664 "guestfs_feature_available".
9665 (Added in 1.20.0)
9667 guestfs_lgetxattr
9669 char *
9670 guestfs_lgetxattr (guestfs_h *g,
9671 const char *path,
9672 const char *name,
9673 size_t *size_r);
9674 Get a single extended attribute from file "path" named "name". If
9676 "path" is a symlink, then this call returns an extended attribute from
9677 the symlink.
9678 Normally it is better to get all extended attributes from a file in one
9680 go by calling "guestfs_getxattrs". However some Linux filesystem
9681 implementations are buggy and do not provide a way to list out
9682 attributes. For these filesystems (notably ntfs-3g) you have to know
9683 the names of the extended attributes you want in advance and call this
9684 function.
9685 Extended attribute values are blobs of binary data. If there is no
9687 extended attribute named "name", this returns an error.
9688 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9690 This function returns a buffer, or NULL on error. The size of the
9692 returned buffer is written to *size_r. The caller must free the
9693 returned buffer after use.
9694 This function depends on the feature "linuxxattrs". See also
9696 "guestfs_feature_available".
9697 (Added in 1.7.24)
9699 guestfs_lgetxattrs
9701 struct guestfs_xattr_list *
9702 guestfs_lgetxattrs (guestfs_h *g,
9703 const char *path);
9704 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9706 link, then it returns the extended attributes of the link itself.
9707 This function returns a "struct guestfs_xattr_list *", or NULL if there
9709 was an error. The caller must call "guestfs_free_xattr_list" after
9710 use.
9711 This function depends on the feature "linuxxattrs". See also
9713 "guestfs_feature_available".
9714 (Added in 1.0.59)
9716 guestfs_list_9p
9718 char **
9719 guestfs_list_9p (guestfs_h *g);
9720 List all 9p filesystems attached to the guest. A list of mount tags is
9722 returned.
9723 This function returns a NULL-terminated array of strings (like
9725 environ(3)), or NULL if there was an error. The caller must free the
9726 strings and the array after use.
9727 (Added in 1.11.12)
9729 guestfs_list_devices
9731 char **
9732 guestfs_list_devices (guestfs_h *g);
9733 List all the block devices.
9735 The full block device names are returned, eg. /dev/sda.
9737 See also "guestfs_list_filesystems".
9739 This function returns a NULL-terminated array of strings (like
9741 environ(3)), or NULL if there was an error. The caller must free the
9742 strings and the array after use.
9743 (Added in 0.4)
9745 guestfs_list_disk_labels
9747 char **
9748 guestfs_list_disk_labels (guestfs_h *g);
9749 If you add drives using the optional "label" parameter of
9751 "guestfs_add_drive_opts", you can use this call to map between disk
9752 labels, and raw block device and partition names (like /dev/sda and
9753 /dev/sda1).
9754 This returns a hashtable, where keys are the disk labels (without the
9756 /dev/disk/guestfs prefix), and the values are the full raw block device
9757 and partition names (eg. /dev/sda and /dev/sda1).
9758 This function returns a NULL-terminated array of strings, or NULL if
9760 there was an error. The array of strings will always have length
9761 "2n+1", where "n" keys and values alternate, followed by the trailing
9762 NULL entry. The caller must free the strings and the array after use.
9763 (Added in 1.19.49)
9765 guestfs_list_dm_devices
9767 char **
9768 guestfs_list_dm_devices (guestfs_h *g);
9769 List all device mapper devices.
9771 The returned list contains /dev/mapper/* devices, eg. ones created by a
9773 previous call to "guestfs_luks_open".
9774 Device mapper devices which correspond to logical volumes are not
9776 returned in this list. Call "guestfs_lvs" if you want to list logical
9777 volumes.
9778 This function returns a NULL-terminated array of strings (like
9780 environ(3)), or NULL if there was an error. The caller must free the
9781 strings and the array after use.
9782 (Added in 1.11.15)
9784 guestfs_list_filesystems
9786 char **
9787 guestfs_list_filesystems (guestfs_h *g);
9788 This inspection command looks for filesystems on partitions, block
9790 devices and logical volumes, returning a list of "mountables"
9791 containing filesystems and their type.
9792 The return value is a hash, where the keys are the devices containing
9794 filesystems, and the values are the filesystem types. For example:
9795 "/dev/sda1" => "ntfs"
9797 "/dev/sda2" => "ext2"
9798 "/dev/vg_guest/lv_root" => "ext4"
9799 "/dev/vg_guest/lv_swap" => "swap"
9800 The key is not necessarily a block device. It may also be an opaque
9802 ‘mountable’ string which can be passed to "guestfs_mount".
9803 The value can have the special value "unknown", meaning the content of
9805 the device is undetermined or empty. "swap" means a Linux swap
9806 partition.
9807 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9809 might have included "guestfs_mount" and "guestfs_umount", and therefore
9810 you had to use this soon after launch and only when nothing else was
9811 mounted. This restriction is removed in libguestfs ≥ 1.38.
9812 Not all of the filesystems returned will be mountable. In particular,
9814 swap partitions are returned in the list. Also this command does not
9815 check that each filesystem found is valid and mountable, and some
9816 filesystems might be mountable but require special options.
9817 Filesystems may not all belong to a single logical operating system
9818 (use "guestfs_inspect_os" to look for OSes).
9819 This function returns a NULL-terminated array of strings, or NULL if
9821 there was an error. The array of strings will always have length
9822 "2n+1", where "n" keys and values alternate, followed by the trailing
9823 NULL entry. The caller must free the strings and the array after use.
9824 (Added in 1.5.15)
9826 guestfs_list_ldm_partitions
9828 char **
9829 guestfs_list_ldm_partitions (guestfs_h *g);
9830 This function returns all Windows dynamic disk partitions that were
9832 found at launch time. It returns a list of device names.
9833 This function returns a NULL-terminated array of strings (like
9835 environ(3)), or NULL if there was an error. The caller must free the
9836 strings and the array after use.
9837 This function depends on the feature "ldm". See also
9839 "guestfs_feature_available".
9840 (Added in 1.20.0)
9842 guestfs_list_ldm_volumes
9844 char **
9845 guestfs_list_ldm_volumes (guestfs_h *g);
9846 This function returns all Windows dynamic disk volumes that were found
9848 at launch time. It returns a list of device names.
9849 This function returns a NULL-terminated array of strings (like
9851 environ(3)), or NULL if there was an error. The caller must free the
9852 strings and the array after use.
9853 This function depends on the feature "ldm". See also
9855 "guestfs_feature_available".
9856 (Added in 1.20.0)
9858 guestfs_list_md_devices
9860 char **
9861 guestfs_list_md_devices (guestfs_h *g);
9862 List all Linux md devices.
9864 This function returns a NULL-terminated array of strings (like
9866 environ(3)), or NULL if there was an error. The caller must free the
9867 strings and the array after use.
9868 (Added in 1.15.4)
9870 guestfs_list_partitions
9872 char **
9873 guestfs_list_partitions (guestfs_h *g);
9874 List all the partitions detected on all block devices.
9876 The full partition device names are returned, eg. /dev/sda1
9878 This does not return logical volumes. For that you will need to call
9880 "guestfs_lvs".
9881 See also "guestfs_list_filesystems".
9883 This function returns a NULL-terminated array of strings (like
9885 environ(3)), or NULL if there was an error. The caller must free the
9886 strings and the array after use.
9887 (Added in 0.4)
9889 guestfs_ll
9891 char *
9892 guestfs_ll (guestfs_h *g,
9893 const char *directory);
9894 List the files in directory (relative to the root directory, there is
9896 no cwd) in the format of "ls -la".
9897 This command is mostly useful for interactive sessions. It is not
9899 intended that you try to parse the output string.
9900 This function returns a string, or NULL on error. The caller must free
9902 the returned string after use.
9903 (Added in 0.4)
9905 guestfs_llz
9907 char *
9908 guestfs_llz (guestfs_h *g,
9909 const char *directory);
9910 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9912 call instead.
9913 Deprecated functions will not be removed from the API, but the fact
9915 that they are deprecated indicates that there are problems with correct
9916 use of these functions.
9917 List the files in directory in the format of "ls -laZ".
9919 This command is mostly useful for interactive sessions. It is not
9921 intended that you try to parse the output string.
9922 This function returns a string, or NULL on error. The caller must free
9924 the returned string after use.
9925 (Added in 1.17.6)
9927 guestfs_ln
9929 int
9930 guestfs_ln (guestfs_h *g,
9931 const char *target,
9932 const char *linkname);
9933 This command creates a hard link.
9935 This function returns 0 on success or -1 on error.
9937 (Added in 1.0.66)
9939 guestfs_ln_f
9941 int
9942 guestfs_ln_f (guestfs_h *g,
9943 const char *target,
9944 const char *linkname);
9945 This command creates a hard link, removing the link "linkname" if it
9947 exists already.
9948 This function returns 0 on success or -1 on error.
9950 (Added in 1.0.66)
9952 guestfs_ln_s
9954 int
9955 guestfs_ln_s (guestfs_h *g,
9956 const char *target,
9957 const char *linkname);
9958 This command creates a symbolic link using the "ln -s" command.
9960 This function returns 0 on success or -1 on error.
9962 (Added in 1.0.66)
9964 guestfs_ln_sf
9966 int
9967 guestfs_ln_sf (guestfs_h *g,
9968 const char *target,
9969 const char *linkname);
9970 This command creates a symbolic link using the "ln -sf" command, The -f
9972 option removes the link ("linkname") if it exists already.
9973 This function returns 0 on success or -1 on error.
9975 (Added in 1.0.66)
9977 guestfs_lremovexattr
9979 int
9980 guestfs_lremovexattr (guestfs_h *g,
9981 const char *xattr,
9982 const char *path);
9983 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9985 link, then it removes an extended attribute of the link itself.
9986 This function returns 0 on success or -1 on error.
9988 This function depends on the feature "linuxxattrs". See also
9990 "guestfs_feature_available".
9991 (Added in 1.0.59)
9993 guestfs_ls
9995 char **
9996 guestfs_ls (guestfs_h *g,
9997 const char *directory);
9998 List the files in directory (relative to the root directory, there is
10000 no cwd). The "." and ".." entries are not returned, but hidden files
10001 are shown.
10002 This function returns a NULL-terminated array of strings (like
10004 environ(3)), or NULL if there was an error. The caller must free the
10005 strings and the array after use.
10006 (Added in 0.4)
10008 guestfs_ls0
10010 int
10011 guestfs_ls0 (guestfs_h *g,
10012 const char *dir,
10013 const char *filenames);
10014 This specialized command is used to get a listing of the filenames in
10016 the directory "dir". The list of filenames is written to the local
10017 file filenames (on the host).
10018 In the output file, the filenames are separated by "\0" characters.
10020 "." and ".." are not returned. The filenames are not sorted.
10022 This function returns 0 on success or -1 on error.
10024 (Added in 1.19.32)
10026 guestfs_lsetxattr
10028 int
10029 guestfs_lsetxattr (guestfs_h *g,
10030 const char *xattr,
10031 const char *val,
10032 int vallen,
10033 const char *path);
10034 This is the same as "guestfs_setxattr", but if "path" is a symbolic
10036 link, then it sets an extended attribute of the link itself.
10037 This function returns 0 on success or -1 on error.
10039 This function depends on the feature "linuxxattrs". See also
10041 "guestfs_feature_available".
10042 (Added in 1.0.59)
10044 guestfs_lstat
10046 struct guestfs_stat *
10047 guestfs_lstat (guestfs_h *g,
10048 const char *path);
10049 This function is deprecated. In new code, use the "guestfs_lstatns"
10051 call instead.
10052 Deprecated functions will not be removed from the API, but the fact
10054 that they are deprecated indicates that there are problems with correct
10055 use of these functions.
10056 Returns file information for the given "path".
10058 This is the same as "guestfs_stat" except that if "path" is a symbolic
10060 link, then the link is stat-ed, not the file it refers to.
10061 This is the same as the lstat(2) system call.
10063 This function returns a "struct guestfs_stat *", or NULL if there was
10065 an error. The caller must call "guestfs_free_stat" after use.
10066 (Added in 1.9.2)
10068 guestfs_lstatlist
10070 struct guestfs_stat_list *
10071 guestfs_lstatlist (guestfs_h *g,
10072 const char *path,
10073 char *const *names);
10074 This function is deprecated. In new code, use the
10076 "guestfs_lstatnslist" call instead.
10077 Deprecated functions will not be removed from the API, but the fact
10079 that they are deprecated indicates that there are problems with correct
10080 use of these functions.
10081 This call allows you to perform the "guestfs_lstat" operation on
10083 multiple files, where all files are in the directory "path". "names"
10084 is the list of files from this directory.
10085 On return you get a list of stat structs, with a one-to-one
10087 correspondence to the "names" list. If any name did not exist or could
10088 not be lstat'd, then the "st_ino" field of that structure is set to
10089 "-1".
10090 This call is intended for programs that want to efficiently list a
10092 directory contents without making many round-trips. See also
10093 "guestfs_lxattrlist" for a similarly efficient call for getting
10094 extended attributes.
10095 This function returns a "struct guestfs_stat_list *", or NULL if there
10097 was an error. The caller must call "guestfs_free_stat_list" after use.
10098 (Added in 1.0.77)
10100 guestfs_lstatns
10102 struct guestfs_statns *
10103 guestfs_lstatns (guestfs_h *g,
10104 const char *path);
10105 Returns file information for the given "path".
10107 This is the same as "guestfs_statns" except that if "path" is a
10109 symbolic link, then the link is stat-ed, not the file it refers to.
10110 This is the same as the lstat(2) system call.
10112 This function returns a "struct guestfs_statns *", or NULL if there was
10114 an error. The caller must call "guestfs_free_statns" after use.
10115 (Added in 1.27.53)
10117 guestfs_lstatnslist
10119 struct guestfs_statns_list *
10120 guestfs_lstatnslist (guestfs_h *g,
10121 const char *path,
10122 char *const *names);
10123 This call allows you to perform the "guestfs_lstatns" operation on
10125 multiple files, where all files are in the directory "path". "names"
10126 is the list of files from this directory.
10127 On return you get a list of stat structs, with a one-to-one
10129 correspondence to the "names" list. If any name did not exist or could
10130 not be lstat'd, then the "st_ino" field of that structure is set to
10131 "-1".
10132 This call is intended for programs that want to efficiently list a
10134 directory contents without making many round-trips. See also
10135 "guestfs_lxattrlist" for a similarly efficient call for getting
10136 extended attributes.
10137 This function returns a "struct guestfs_statns_list *", or NULL if
10139 there was an error. The caller must call "guestfs_free_statns_list"
10140 after use.
10141 (Added in 1.27.53)
10143 guestfs_luks_add_key
10145 int
10146 guestfs_luks_add_key (guestfs_h *g,
10147 const char *device,
10148 const char *key,
10149 const char *newkey,
10150 int keyslot);
10151 This command adds a new key on LUKS device "device". "key" is any
10153 existing key, and is used to access the device. "newkey" is the new
10154 key to add. "keyslot" is the key slot that will be replaced.
10155 Note that if "keyslot" already contains a key, then this command will
10157 fail. You have to use "guestfs_luks_kill_slot" first to remove that
10158 key.
10159 This function returns 0 on success or -1 on error.
10161 This function takes a key or passphrase parameter which could contain
10163 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10164 information.
10165 This function depends on the feature "luks". See also
10167 "guestfs_feature_available".
10168 (Added in 1.5.2)
10170 guestfs_luks_close
10172 int
10173 guestfs_luks_close (guestfs_h *g,
10174 const char *device);
10175 This function is deprecated. In new code, use the
10177 "guestfs_cryptsetup_close" call instead.
10178 Deprecated functions will not be removed from the API, but the fact
10180 that they are deprecated indicates that there are problems with correct
10181 use of these functions.
10182 This closes a LUKS device that was created earlier by
10184 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
10185 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10186 and not the name of the underlying block device.
10187 This function returns 0 on success or -1 on error.
10189 This function depends on the feature "luks". See also
10191 "guestfs_feature_available".
10192 (Added in 1.5.1)
10194 guestfs_luks_format
10196 int
10197 guestfs_luks_format (guestfs_h *g,
10198 const char *device,
10199 const char *key,
10200 int keyslot);
10201 This command erases existing data on "device" and formats the device as
10203 a LUKS encrypted device. "key" is the initial key, which is added to
10204 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
10205 This function returns 0 on success or -1 on error.
10207 This function takes a key or passphrase parameter which could contain
10209 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10210 information.
10211 This function depends on the feature "luks". See also
10213 "guestfs_feature_available".
10214 (Added in 1.5.2)
10216 guestfs_luks_format_cipher
10218 int
10219 guestfs_luks_format_cipher (guestfs_h *g,
10220 const char *device,
10221 const char *key,
10222 int keyslot,
10223 const char *cipher);
10224 This command is the same as "guestfs_luks_format" but it also allows
10226 you to set the "cipher" used.
10227 This function returns 0 on success or -1 on error.
10229 This function takes a key or passphrase parameter which could contain
10231 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10232 information.
10233 This function depends on the feature "luks". See also
10235 "guestfs_feature_available".
10236 (Added in 1.5.2)
10238 guestfs_luks_kill_slot
10240 int
10241 guestfs_luks_kill_slot (guestfs_h *g,
10242 const char *device,
10243 const char *key,
10244 int keyslot);
10245 This command deletes the key in key slot "keyslot" from the encrypted
10247 LUKS device "device". "key" must be one of the other keys.
10248 This function returns 0 on success or -1 on error.
10250 This function takes a key or passphrase parameter which could contain
10252 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10253 information.
10254 This function depends on the feature "luks". See also
10256 "guestfs_feature_available".
10257 (Added in 1.5.2)
10259 guestfs_luks_open
10261 int
10262 guestfs_luks_open (guestfs_h *g,
10263 const char *device,
10264 const char *key,
10265 const char *mapname);
10266 This function is deprecated. In new code, use the
10268 "guestfs_cryptsetup_open" call instead.
10269 Deprecated functions will not be removed from the API, but the fact
10271 that they are deprecated indicates that there are problems with correct
10272 use of these functions.
10273 This command opens a block device which has been encrypted according to
10275 the Linux Unified Key Setup (LUKS) standard.
10276 "device" is the encrypted block device or partition.
10278 The caller must supply one of the keys associated with the LUKS block
10280 device, in the "key" parameter.
10281 This creates a new block device called /dev/mapper/mapname. Reads and
10283 writes to this block device are decrypted from and encrypted to the
10284 underlying "device" respectively.
10285 If this block device contains LVM volume groups, then calling
10287 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10288 visible.
10289 Use "guestfs_list_dm_devices" to list all device mapper devices.
10291 This function returns 0 on success or -1 on error.
10293 This function takes a key or passphrase parameter which could contain
10295 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10296 information.
10297 This function depends on the feature "luks". See also
10299 "guestfs_feature_available".
10300 (Added in 1.5.1)
10302 guestfs_luks_open_ro
10304 int
10305 guestfs_luks_open_ro (guestfs_h *g,
10306 const char *device,
10307 const char *key,
10308 const char *mapname);
10309 This function is deprecated. In new code, use the
10311 "guestfs_cryptsetup_open" call instead.
10312 Deprecated functions will not be removed from the API, but the fact
10314 that they are deprecated indicates that there are problems with correct
10315 use of these functions.
10316 This is the same as "guestfs_luks_open" except that a read-only mapping
10318 is created.
10319 This function returns 0 on success or -1 on error.
10321 This function takes a key or passphrase parameter which could contain
10323 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10324 information.
10325 This function depends on the feature "luks". See also
10327 "guestfs_feature_available".
10328 (Added in 1.5.1)
10330 guestfs_luks_uuid
10332 char *
10333 guestfs_luks_uuid (guestfs_h *g,
10334 const char *device);
10335 This returns the UUID of the LUKS device "device".
10337 This function returns a string, or NULL on error. The caller must free
10339 the returned string after use.
10340 This function depends on the feature "luks". See also
10342 "guestfs_feature_available".
10343 (Added in 1.41.9)
10345 guestfs_lvcreate
10347 int
10348 guestfs_lvcreate (guestfs_h *g,
10349 const char *logvol,
10350 const char *volgroup,
10351 int mbytes);
10352 This creates an LVM logical volume called "logvol" on the volume group
10354 "volgroup", with "size" megabytes.
10355 This function returns 0 on success or -1 on error.
10357 This function depends on the feature "lvm2". See also
10359 "guestfs_feature_available".
10360 (Added in 0.8)
10362 guestfs_lvcreate_free
10364 int
10365 guestfs_lvcreate_free (guestfs_h *g,
10366 const char *logvol,
10367 const char *volgroup,
10368 int percent);
10369 Create an LVM logical volume called /dev/volgroup/logvol, using
10371 approximately "percent" % of the free space remaining in the volume
10372 group. Most usefully, when "percent" is 100 this will create the
10373 largest possible LV.
10374 This function returns 0 on success or -1 on error.
10376 This function depends on the feature "lvm2". See also
10378 "guestfs_feature_available".
10379 (Added in 1.17.18)
10381 guestfs_lvm_canonical_lv_name
10383 char *
10384 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10385 const char *lvname);
10386 This converts alternative naming schemes for LVs that you might find to
10388 the canonical name. For example, /dev/mapper/VG-LV is converted to
10389 /dev/VG/LV.
10390 This command returns an error if the "lvname" parameter does not refer
10392 to a logical volume. In this case errno will be set to "EINVAL".
10393 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10395 This function returns a string, or NULL on error. The caller must free
10397 the returned string after use.
10398 (Added in 1.5.24)
10400 guestfs_lvm_clear_filter
10402 int
10403 guestfs_lvm_clear_filter (guestfs_h *g);
10404 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10406 to see every block device.
10407 This command also clears the LVM cache and performs a volume group
10409 scan.
10410 This function returns 0 on success or -1 on error.
10412 (Added in 1.5.1)
10414 guestfs_lvm_remove_all
10416 int
10417 guestfs_lvm_remove_all (guestfs_h *g);
10418 This command removes all LVM logical volumes, volume groups and
10420 physical volumes.
10421 This function returns 0 on success or -1 on error.
10423 This function depends on the feature "lvm2". See also
10425 "guestfs_feature_available".
10426 (Added in 0.8)
10428 guestfs_lvm_scan
10430 int
10431 guestfs_lvm_scan (guestfs_h *g,
10432 int activate);
10433 This scans all block devices and rebuilds the list of LVM physical
10435 volumes, volume groups and logical volumes.
10436 If the "activate" parameter is "true" then newly found volume groups
10438 and logical volumes are activated, meaning the LV /dev/VG/LV devices
10439 become visible.
10440 When a libguestfs handle is launched it scans for existing devices, so
10442 you do not normally need to use this API. However it is useful when
10443 you have added a new device or deleted an existing device (such as when
10444 the "guestfs_luks_open" API is used).
10445 This function returns 0 on success or -1 on error.
10447 (Added in 1.39.8)
10449 guestfs_lvm_set_filter
10451 int
10452 guestfs_lvm_set_filter (guestfs_h *g,
10453 char *const *devices);
10454 This sets the LVM device filter so that LVM will only be able to "see"
10456 the block devices in the list "devices", and will ignore all other
10457 attached block devices.
10458 Where disk image(s) contain duplicate PVs or VGs, this command is
10460 useful to get LVM to ignore the duplicates, otherwise LVM can get
10461 confused. Note also there are two types of duplication possible:
10462 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10463 cloned but just happen to have the same name. In normal operation you
10464 cannot create this situation, but you can do it outside LVM, eg. by
10465 cloning disk images or by bit twiddling inside the LVM metadata.
10466 This command also clears the LVM cache and performs a volume group
10468 scan.
10469 You can filter whole block devices or individual partitions.
10471 You cannot use this if any VG is currently in use (eg. contains a
10473 mounted filesystem), even if you are not filtering out that VG.
10474 This function returns 0 on success or -1 on error.
10476 This function depends on the feature "lvm2". See also
10478 "guestfs_feature_available".
10479 (Added in 1.5.1)
10481 guestfs_lvremove
10483 int
10484 guestfs_lvremove (guestfs_h *g,
10485 const char *device);
10486 Remove an LVM logical volume "device", where "device" is the path to
10488 the LV, such as /dev/VG/LV.
10489 You can also remove all LVs in a volume group by specifying the VG
10491 name, /dev/VG.
10492 This function returns 0 on success or -1 on error.
10494 This function depends on the feature "lvm2". See also
10496 "guestfs_feature_available".
10497 (Added in 1.0.13)
10499 guestfs_lvrename
10501 int
10502 guestfs_lvrename (guestfs_h *g,
10503 const char *logvol,
10504 const char *newlogvol);
10505 Rename a logical volume "logvol" with the new name "newlogvol".
10507 This function returns 0 on success or -1 on error.
10509 (Added in 1.0.83)
10511 guestfs_lvresize
10513 int
10514 guestfs_lvresize (guestfs_h *g,
10515 const char *device,
10516 int mbytes);
10517 This resizes (expands or shrinks) an existing LVM logical volume to
10519 "mbytes". When reducing, data in the reduced part is lost.
10520 This function returns 0 on success or -1 on error.
10522 This function depends on the feature "lvm2". See also
10524 "guestfs_feature_available".
10525 (Added in 1.0.27)
10527 guestfs_lvresize_free
10529 int
10530 guestfs_lvresize_free (guestfs_h *g,
10531 const char *lv,
10532 int percent);
10533 This expands an existing logical volume "lv" so that it fills "pc" % of
10535 the remaining free space in the volume group. Commonly you would call
10536 this with pc = 100 which expands the logical volume as much as
10537 possible, using all remaining free space in the volume group.
10538 This function returns 0 on success or -1 on error.
10540 This function depends on the feature "lvm2". See also
10542 "guestfs_feature_available".
10543 (Added in 1.3.3)
10545 guestfs_lvs
10547 char **
10548 guestfs_lvs (guestfs_h *g);
10549 List all the logical volumes detected. This is the equivalent of the
10551 lvs(8) command.
10552 This returns a list of the logical volume device names (eg.
10554 /dev/VolGroup00/LogVol00).
10555 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10557 This function returns a NULL-terminated array of strings (like
10559 environ(3)), or NULL if there was an error. The caller must free the
10560 strings and the array after use.
10561 This function depends on the feature "lvm2". See also
10563 "guestfs_feature_available".
10564 (Added in 0.4)
10566 guestfs_lvs_full
10568 struct guestfs_lvm_lv_list *
10569 guestfs_lvs_full (guestfs_h *g);
10570 List all the logical volumes detected. This is the equivalent of the
10572 lvs(8) command. The "full" version includes all fields.
10573 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10575 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10576 after use.
10577 This function depends on the feature "lvm2". See also
10579 "guestfs_feature_available".
10580 (Added in 0.4)
10582 guestfs_lvuuid
10584 char *
10585 guestfs_lvuuid (guestfs_h *g,
10586 const char *device);
10587 This command returns the UUID of the LVM LV "device".
10589 This function returns a string, or NULL on error. The caller must free
10591 the returned string after use.
10592 (Added in 1.0.87)
10594 guestfs_lxattrlist
10596 struct guestfs_xattr_list *
10597 guestfs_lxattrlist (guestfs_h *g,
10598 const char *path,
10599 char *const *names);
10600 This call allows you to get the extended attributes of multiple files,
10602 where all files are in the directory "path". "names" is the list of
10603 files from this directory.
10604 On return you get a flat list of xattr structs which must be
10606 interpreted sequentially. The first xattr struct always has a zero-
10607 length "attrname". "attrval" in this struct is zero-length to indicate
10608 there was an error doing "guestfs_lgetxattr" for this file, or is a C
10609 string which is a decimal number (the number of following attributes
10610 for this file, which could be "0"). Then after the first xattr struct
10611 are the zero or more attributes for the first named file. This repeats
10612 for the second and subsequent files.
10613 This call is intended for programs that want to efficiently list a
10615 directory contents without making many round-trips. See also
10616 "guestfs_lstatlist" for a similarly efficient call for getting standard
10617 stats.
10618 This function returns a "struct guestfs_xattr_list *", or NULL if there
10620 was an error. The caller must call "guestfs_free_xattr_list" after
10621 use.
10622 This function depends on the feature "linuxxattrs". See also
10624 "guestfs_feature_available".
10625 (Added in 1.0.77)
10627 guestfs_max_disks
10629 int
10630 guestfs_max_disks (guestfs_h *g);
10631 Return the maximum number of disks that may be added to a handle (eg.
10633 by "guestfs_add_drive_opts" and similar calls).
10634 This function was added in libguestfs 1.19.7. In previous versions of
10636 libguestfs the limit was 25.
10637 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10639 On error this function returns -1.
10641 (Added in 1.19.7)
10643 guestfs_md_create
10645 int
10646 guestfs_md_create (guestfs_h *g,
10647 const char *name,
10648 char *const *devices,
10649 ...);
10650 You may supply a list of optional arguments to this call. Use zero or
10652 more of the following pairs of parameters, and terminate the list with
10653 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10654 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10656 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10657 GUESTFS_MD_CREATE_SPARE, int spare,
10658 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10659 GUESTFS_MD_CREATE_LEVEL, const char *level,
10660 Create a Linux md (RAID) device named "name" on the devices in the list
10662 "devices".
10663 The optional parameters are:
10665 "missingbitmap"
10667 A bitmap of missing devices. If a bit is set it means that a
10668 missing device is added to the array. The least significant bit
10669 corresponds to the first device in the array.
10670 As examples:
10672 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10674 resulting array would be "[<missing>, "/dev/sda"]".
10675 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10677 resulting array would be "["/dev/sda", <missing>]".
10678 This defaults to 0 (no missing devices).
10680 The length of "devices" + the number of bits set in "missingbitmap"
10682 must equal "nrdevices" + "spare".
10683 "nrdevices"
10685 The number of active RAID devices.
10686 If not set, this defaults to the length of "devices" plus the
10688 number of bits set in "missingbitmap".
10689 "spare"
10691 The number of spare devices.
10692 If not set, this defaults to 0.
10694 "chunk"
10696 The chunk size in bytes.
10697 "level"
10699 The RAID level, which can be one of: "linear", "raid0", 0,
10700 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
10701 "raid10", 10. Some of these are synonymous, and more levels may be
10702 added in future.
10703 If not set, this defaults to "raid1".
10705 This function returns 0 on success or -1 on error.
10707 This function depends on the feature "mdadm". See also
10709 "guestfs_feature_available".
10710 (Added in 1.15.6)
10712 guestfs_md_create_va
10714 int
10715 guestfs_md_create_va (guestfs_h *g,
10716 const char *name,
10717 char *const *devices,
10718 va_list args);
10719 This is the "va_list variant" of "guestfs_md_create".
10721 See "CALLS WITH OPTIONAL ARGUMENTS".
10723 guestfs_md_create_argv
10725 int
10726 guestfs_md_create_argv (guestfs_h *g,
10727 const char *name,
10728 char *const *devices,
10729 const struct guestfs_md_create_argv *optargs);
10730 This is the "argv variant" of "guestfs_md_create".
10732 See "CALLS WITH OPTIONAL ARGUMENTS".
10734 guestfs_md_detail
10736 char **
10737 guestfs_md_detail (guestfs_h *g,
10738 const char *md);
10739 This command exposes the output of "mdadm -DY <md>". The following
10741 fields are usually present in the returned hash. Other fields may also
10742 be present.
10743 "level"
10745 The raid level of the MD device.
10746 "devices"
10748 The number of underlying devices in the MD device.
10749 "metadata"
10751 The metadata version used.
10752 "uuid"
10754 The UUID of the MD device.
10755 "name"
10757 The name of the MD device.
10758 This function returns a NULL-terminated array of strings, or NULL if
10760 there was an error. The array of strings will always have length
10761 "2n+1", where "n" keys and values alternate, followed by the trailing
10762 NULL entry. The caller must free the strings and the array after use.
10763 This function depends on the feature "mdadm". See also
10765 "guestfs_feature_available".
10766 (Added in 1.15.6)
10768 guestfs_md_stat
10770 struct guestfs_mdstat_list *
10771 guestfs_md_stat (guestfs_h *g,
10772 const char *md);
10773 This call returns a list of the underlying devices which make up the
10775 single software RAID array device "md".
10776 To get a list of software RAID devices, call "guestfs_list_md_devices".
10778 Each structure returned corresponds to one device along with additional
10780 status information:
10781 "mdstat_device"
10783 The name of the underlying device.
10784 "mdstat_index"
10786 The index of this device within the array.
10787 "mdstat_flags"
10789 Flags associated with this device. This is a string containing (in
10790 no specific order) zero or more of the following flags:
10791 "W" write-mostly
10793 "F" device is faulty
10795 "S" device is a RAID spare
10797 "R" replacement
10799 This function returns a "struct guestfs_mdstat_list *", or NULL if
10801 there was an error. The caller must call "guestfs_free_mdstat_list"
10802 after use.
10803 This function depends on the feature "mdadm". See also
10805 "guestfs_feature_available".
10806 (Added in 1.17.21)
10808 guestfs_md_stop
10810 int
10811 guestfs_md_stop (guestfs_h *g,
10812 const char *md);
10813 This command deactivates the MD array named "md". The device is
10815 stopped, but it is not destroyed or zeroed.
10816 This function returns 0 on success or -1 on error.
10818 This function depends on the feature "mdadm". See also
10820 "guestfs_feature_available".
10821 (Added in 1.15.6)
10823 guestfs_mkdir
10825 int
10826 guestfs_mkdir (guestfs_h *g,
10827 const char *path);
10828 Create a directory named "path".
10830 This function returns 0 on success or -1 on error.
10832 (Added in 0.8)
10834 guestfs_mkdir_mode
10836 int
10837 guestfs_mkdir_mode (guestfs_h *g,
10838 const char *path,
10839 int mode);
10840 This command creates a directory, setting the initial permissions of
10842 the directory to "mode".
10843 For common Linux filesystems, the actual mode which is set will be
10845 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10846 the mode in other ways.
10847 See also "guestfs_mkdir", "guestfs_umask"
10849 This function returns 0 on success or -1 on error.
10851 (Added in 1.0.77)
10853 guestfs_mkdir_p
10855 int
10856 guestfs_mkdir_p (guestfs_h *g,
10857 const char *path);
10858 Create a directory named "path", creating any parent directories as
10860 necessary. This is like the "mkdir -p" shell command.
10861 This function returns 0 on success or -1 on error.
10863 (Added in 0.8)
10865 guestfs_mkdtemp
10867 char *
10868 guestfs_mkdtemp (guestfs_h *g,
10869 const char *tmpl);
10870 This command creates a temporary directory. The "tmpl" parameter
10872 should be a full pathname for the temporary directory name with the
10873 final six characters being "XXXXXX".
10874 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10876 one being suitable for Windows filesystems.
10877 The name of the temporary directory that was created is returned.
10879 The temporary directory is created with mode 0700 and is owned by root.
10881 The caller is responsible for deleting the temporary directory and its
10883 contents after use.
10884 See also: mkdtemp(3)
10886 This function returns a string, or NULL on error. The caller must free
10888 the returned string after use.
10889 (Added in 1.0.54)
10891 guestfs_mke2fs
10893 int
10894 guestfs_mke2fs (guestfs_h *g,
10895 const char *device,
10896 ...);
10897 You may supply a list of optional arguments to this call. Use zero or
10899 more of the following pairs of parameters, and terminate the list with
10900 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10901 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10903 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10904 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10905 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10906 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10907 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10908 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10909 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10910 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10911 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10912 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10913 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10914 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10915 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10916 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10917 GUESTFS_MKE2FS_LABEL, const char *label,
10918 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10919 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10920 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10921 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10922 GUESTFS_MKE2FS_UUID, const char *uuid,
10923 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10924 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10925 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10926 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10927 GUESTFS_MKE2FS_TESTFS, int testfs,
10928 GUESTFS_MKE2FS_DISCARD, int discard,
10929 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10930 GUESTFS_MKE2FS_EXTENT, int extent,
10931 GUESTFS_MKE2FS_FILETYPE, int filetype,
10932 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10933 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10934 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10935 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10936 GUESTFS_MKE2FS_QUOTA, int quota,
10937 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10938 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10939 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10940 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10942 "device".
10943 The optional "blockscount" is the size of the filesystem in blocks. If
10945 omitted it defaults to the size of "device". Note if the filesystem is
10946 too small to contain a journal, "mke2fs" will silently create an ext2
10947 filesystem instead.
10948 This function returns 0 on success or -1 on error.
10950 (Added in 1.19.44)
10952 guestfs_mke2fs_va
10954 int
10955 guestfs_mke2fs_va (guestfs_h *g,
10956 const char *device,
10957 va_list args);
10958 This is the "va_list variant" of "guestfs_mke2fs".
10960 See "CALLS WITH OPTIONAL ARGUMENTS".
10962 guestfs_mke2fs_argv
10964 int
10965 guestfs_mke2fs_argv (guestfs_h *g,
10966 const char *device,
10967 const struct guestfs_mke2fs_argv *optargs);
10968 This is the "argv variant" of "guestfs_mke2fs".
10970 See "CALLS WITH OPTIONAL ARGUMENTS".
10972 guestfs_mke2fs_J
10974 int
10975 guestfs_mke2fs_J (guestfs_h *g,
10976 const char *fstype,
10977 int blocksize,
10978 const char *device,
10979 const char *journal);
10980 This function is deprecated. In new code, use the "guestfs_mke2fs"
10982 call instead.
10983 Deprecated functions will not be removed from the API, but the fact
10985 that they are deprecated indicates that there are problems with correct
10986 use of these functions.
10987 This creates an ext2/3/4 filesystem on "device" with an external
10989 journal on "journal". It is equivalent to the command:
10990 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10992 See also "guestfs_mke2journal".
10994 This function returns 0 on success or -1 on error.
10996 (Added in 1.0.68)
10998 guestfs_mke2fs_JL
11000 int
11001 guestfs_mke2fs_JL (guestfs_h *g,
11002 const char *fstype,
11003 int blocksize,
11004 const char *device,
11005 const char *label);
11006 This function is deprecated. In new code, use the "guestfs_mke2fs"
11008 call instead.
11009 Deprecated functions will not be removed from the API, but the fact
11011 that they are deprecated indicates that there are problems with correct
11012 use of these functions.
11013 This creates an ext2/3/4 filesystem on "device" with an external
11015 journal on the journal labeled "label".
11016 See also "guestfs_mke2journal_L".
11018 This function returns 0 on success or -1 on error.
11020 (Added in 1.0.68)
11022 guestfs_mke2fs_JU
11024 int
11025 guestfs_mke2fs_JU (guestfs_h *g,
11026 const char *fstype,
11027 int blocksize,
11028 const char *device,
11029 const char *uuid);
11030 This function is deprecated. In new code, use the "guestfs_mke2fs"
11032 call instead.
11033 Deprecated functions will not be removed from the API, but the fact
11035 that they are deprecated indicates that there are problems with correct
11036 use of these functions.
11037 This creates an ext2/3/4 filesystem on "device" with an external
11039 journal on the journal with UUID "uuid".
11040 See also "guestfs_mke2journal_U".
11042 This function returns 0 on success or -1 on error.
11044 This function depends on the feature "linuxfsuuid". See also
11046 "guestfs_feature_available".
11047 (Added in 1.0.68)
11049 guestfs_mke2journal
11051 int
11052 guestfs_mke2journal (guestfs_h *g,
11053 int blocksize,
11054 const char *device);
11055 This function is deprecated. In new code, use the "guestfs_mke2fs"
11057 call instead.
11058 Deprecated functions will not be removed from the API, but the fact
11060 that they are deprecated indicates that there are problems with correct
11061 use of these functions.
11062 This creates an ext2 external journal on "device". It is equivalent to
11064 the command:
11065 mke2fs -O journal_dev -b blocksize device
11067 This function returns 0 on success or -1 on error.
11069 (Added in 1.0.68)
11071 guestfs_mke2journal_L
11073 int
11074 guestfs_mke2journal_L (guestfs_h *g,
11075 int blocksize,
11076 const char *label,
11077 const char *device);
11078 This function is deprecated. In new code, use the "guestfs_mke2fs"
11080 call instead.
11081 Deprecated functions will not be removed from the API, but the fact
11083 that they are deprecated indicates that there are problems with correct
11084 use of these functions.
11085 This creates an ext2 external journal on "device" with label "label".
11087 This function returns 0 on success or -1 on error.
11089 (Added in 1.0.68)
11091 guestfs_mke2journal_U
11093 int
11094 guestfs_mke2journal_U (guestfs_h *g,
11095 int blocksize,
11096 const char *uuid,
11097 const char *device);
11098 This function is deprecated. In new code, use the "guestfs_mke2fs"
11100 call instead.
11101 Deprecated functions will not be removed from the API, but the fact
11103 that they are deprecated indicates that there are problems with correct
11104 use of these functions.
11105 This creates an ext2 external journal on "device" with UUID "uuid".
11107 This function returns 0 on success or -1 on error.
11109 This function depends on the feature "linuxfsuuid". See also
11111 "guestfs_feature_available".
11112 (Added in 1.0.68)
11114 guestfs_mkfifo
11116 int
11117 guestfs_mkfifo (guestfs_h *g,
11118 int mode,
11119 const char *path);
11120 This call creates a FIFO (named pipe) called "path" with mode "mode".
11122 It is just a convenient wrapper around "guestfs_mknod".
11123 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11125 The mode actually set is affected by the umask.
11127 This function returns 0 on success or -1 on error.
11129 This function depends on the feature "mknod". See also
11131 "guestfs_feature_available".
11132 (Added in 1.0.55)
11134 guestfs_mkfs
11136 int
11137 guestfs_mkfs (guestfs_h *g,
11138 const char *fstype,
11139 const char *device);
11140 This function is provided for backwards compatibility with earlier
11142 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
11143 optional arguments.
11144 (Added in 0.8)
11146 guestfs_mkfs_opts
11148 int
11149 guestfs_mkfs_opts (guestfs_h *g,
11150 const char *fstype,
11151 const char *device,
11152 ...);
11153 You may supply a list of optional arguments to this call. Use zero or
11155 more of the following pairs of parameters, and terminate the list with
11156 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11157 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
11159 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
11160 GUESTFS_MKFS_OPTS_INODE, int inode,
11161 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
11162 GUESTFS_MKFS_OPTS_LABEL, const char *label,
11163 This function creates a filesystem on "device". The filesystem type is
11165 "fstype", for example "ext3".
11166 The optional arguments are:
11168 "blocksize"
11170 The filesystem block size. Supported block sizes depend on the
11171 filesystem type, but typically they are 1024, 2048 or 4096 for
11172 Linux ext2/3 filesystems.
11173 For VFAT and NTFS the "blocksize" parameter is treated as the
11175 requested cluster size.
11176 For UFS block sizes, please see mkfs.ufs(8).
11178 "features"
11180 This passes the -O parameter to the external mkfs program.
11181 For certain filesystem types, this allows extra filesystem features
11183 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
11184 You cannot use this optional parameter with the "gfs" or "gfs2"
11186 filesystem type.
11187 "inode"
11189 This passes the -I parameter to the external mke2fs(8) program
11190 which sets the inode size (only for ext2/3/4 filesystems at
11191 present).
11192 "sectorsize"
11194 This passes the -S parameter to external mkfs.ufs(8) program, which
11195 sets sector size for ufs filesystem.
11196 This function returns 0 on success or -1 on error.
11198 (Added in 0.8)
11200 guestfs_mkfs_opts_va
11202 int
11203 guestfs_mkfs_opts_va (guestfs_h *g,
11204 const char *fstype,
11205 const char *device,
11206 va_list args);
11207 This is the "va_list variant" of "guestfs_mkfs_opts".
11209 See "CALLS WITH OPTIONAL ARGUMENTS".
11211 guestfs_mkfs_opts_argv
11213 int
11214 guestfs_mkfs_opts_argv (guestfs_h *g,
11215 const char *fstype,
11216 const char *device,
11217 const struct guestfs_mkfs_opts_argv *optargs);
11218 This is the "argv variant" of "guestfs_mkfs_opts".
11220 See "CALLS WITH OPTIONAL ARGUMENTS".
11222 guestfs_mkfs_b
11224 int
11225 guestfs_mkfs_b (guestfs_h *g,
11226 const char *fstype,
11227 int blocksize,
11228 const char *device);
11229 This function is deprecated. In new code, use the "guestfs_mkfs" call
11231 instead.
11232 Deprecated functions will not be removed from the API, but the fact
11234 that they are deprecated indicates that there are problems with correct
11235 use of these functions.
11236 This call is similar to "guestfs_mkfs", but it allows you to control
11238 the block size of the resulting filesystem. Supported block sizes
11239 depend on the filesystem type, but typically they are 1024, 2048 or
11240 4096 only.
11241 For VFAT and NTFS the "blocksize" parameter is treated as the requested
11243 cluster size.
11244 This function returns 0 on success or -1 on error.
11246 (Added in 1.0.68)
11248 guestfs_mkfs_btrfs
11250 int
11251 guestfs_mkfs_btrfs (guestfs_h *g,
11252 char *const *devices,
11253 ...);
11254 You may supply a list of optional arguments to this call. Use zero or
11256 more of the following pairs of parameters, and terminate the list with
11257 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11258 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11260 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11261 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11262 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11263 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11264 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11265 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11266 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11267 Create a btrfs filesystem, allowing all configurables to be set. For
11269 more information on the optional arguments, see mkfs.btrfs(8).
11270 Since btrfs filesystems can span multiple devices, this takes a non-
11272 empty list of devices.
11273 To create general filesystems, use "guestfs_mkfs".
11275 This function returns 0 on success or -1 on error.
11277 This function depends on the feature "btrfs". See also
11279 "guestfs_feature_available".
11280 (Added in 1.17.25)
11282 guestfs_mkfs_btrfs_va
11284 int
11285 guestfs_mkfs_btrfs_va (guestfs_h *g,
11286 char *const *devices,
11287 va_list args);
11288 This is the "va_list variant" of "guestfs_mkfs_btrfs".
11290 See "CALLS WITH OPTIONAL ARGUMENTS".
11292 guestfs_mkfs_btrfs_argv
11294 int
11295 guestfs_mkfs_btrfs_argv (guestfs_h *g,
11296 char *const *devices,
11297 const struct guestfs_mkfs_btrfs_argv *optargs);
11298 This is the "argv variant" of "guestfs_mkfs_btrfs".
11300 See "CALLS WITH OPTIONAL ARGUMENTS".
11302 guestfs_mklost_and_found
11304 int
11305 guestfs_mklost_and_found (guestfs_h *g,
11306 const char *mountpoint);
11307 Make the "lost+found" directory, normally in the root directory of an
11309 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
11310 to create the "lost+found" directory.
11311 This function returns 0 on success or -1 on error.
11313 (Added in 1.19.56)
11315 guestfs_mkmountpoint
11317 int
11318 guestfs_mkmountpoint (guestfs_h *g,
11319 const char *exemptpath);
11320 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11322 that can be used to create extra mountpoints before mounting the first
11323 filesystem.
11324 These calls are only necessary in some very limited circumstances,
11326 mainly the case where you want to mount a mix of unrelated and/or read-
11327 only filesystems together.
11328 For example, live CDs often contain a "Russian doll" nest of
11330 filesystems, an ISO outer layer, with a squashfs image inside, with an
11331 ext2/3 image inside that. You can unpack this as follows in guestfish:
11332 add-ro Fedora-11-i686-Live.iso
11334 run
11335 mkmountpoint /cd
11336 mkmountpoint /sqsh
11337 mkmountpoint /ext3fs
11338 mount /dev/sda /cd
11339 mount-loop /cd/LiveOS/squashfs.img /sqsh
11340 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11341 The inner filesystem is now unpacked under the /ext3fs mountpoint.
11343 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11345 You may get unexpected errors if you try to mix these calls. It is
11346 safest to manually unmount filesystems and remove mountpoints after
11347 use.
11348 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11350 first, so for this to work for manual mountpoints, you must ensure that
11351 the innermost mountpoints have the longest pathnames, as in the example
11352 code above.
11353 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11355 Autosync [see "guestfs_set_autosync", this is set by default on
11357 handles] can cause "guestfs_umount_all" to be called when the handle is
11358 closed which can also trigger these issues.
11359 This function returns 0 on success or -1 on error.
11361 (Added in 1.0.62)
11363 guestfs_mknod
11365 int
11366 guestfs_mknod (guestfs_h *g,
11367 int mode,
11368 int devmajor,
11369 int devminor,
11370 const char *path);
11371 This call creates block or character special devices, or named pipes
11373 (FIFOs).
11374 The "mode" parameter should be the mode, using the standard constants.
11376 "devmajor" and "devminor" are the device major and minor numbers, only
11377 used when creating block and character special devices.
11378 Note that, just like mknod(2), the mode must be bitwise OR'd with
11380 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11381 a regular file). These constants are available in the standard Linux
11382 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11383 "guestfs_mkfifo" which are wrappers around this command which bitwise
11384 OR in the appropriate constant for you.
11385 The mode actually set is affected by the umask.
11387 This function returns 0 on success or -1 on error.
11389 This function depends on the feature "mknod". See also
11391 "guestfs_feature_available".
11392 (Added in 1.0.55)
11394 guestfs_mknod_b
11396 int
11397 guestfs_mknod_b (guestfs_h *g,
11398 int mode,
11399 int devmajor,
11400 int devminor,
11401 const char *path);
11402 This call creates a block device node called "path" with mode "mode"
11404 and device major/minor "devmajor" and "devminor". It is just a
11405 convenient wrapper around "guestfs_mknod".
11406 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11408 The mode actually set is affected by the umask.
11410 This function returns 0 on success or -1 on error.
11412 This function depends on the feature "mknod". See also
11414 "guestfs_feature_available".
11415 (Added in 1.0.55)
11417 guestfs_mknod_c
11419 int
11420 guestfs_mknod_c (guestfs_h *g,
11421 int mode,
11422 int devmajor,
11423 int devminor,
11424 const char *path);
11425 This call creates a char device node called "path" with mode "mode" and
11427 device major/minor "devmajor" and "devminor". It is just a convenient
11428 wrapper around "guestfs_mknod".
11429 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11431 The mode actually set is affected by the umask.
11433 This function returns 0 on success or -1 on error.
11435 This function depends on the feature "mknod". See also
11437 "guestfs_feature_available".
11438 (Added in 1.0.55)
11440 guestfs_mksquashfs
11442 int
11443 guestfs_mksquashfs (guestfs_h *g,
11444 const char *path,
11445 const char *filename,
11446 ...);
11447 You may supply a list of optional arguments to this call. Use zero or
11449 more of the following pairs of parameters, and terminate the list with
11450 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11451 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11453 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11454 Create a squashfs filesystem for the specified "path".
11456 The optional "compress" flag controls compression. If not given, then
11458 the output compressed using "gzip". Otherwise one of the following
11459 strings may be given to select the compression type of the squashfs:
11460 "gzip", "lzma", "lzo", "lz4", "xz".
11461 The other optional arguments are:
11463 "excludes"
11465 A list of wildcards. Files are excluded if they match any of the
11466 wildcards.
11467 Please note that this API may fail when used to compress directories
11469 with large files, such as the resulting squashfs will be over 3GB big.
11470 This function returns 0 on success or -1 on error.
11472 This function depends on the feature "squashfs". See also
11474 "guestfs_feature_available".
11475 (Added in 1.35.25)
11477 guestfs_mksquashfs_va
11479 int
11480 guestfs_mksquashfs_va (guestfs_h *g,
11481 const char *path,
11482 const char *filename,
11483 va_list args);
11484 This is the "va_list variant" of "guestfs_mksquashfs".
11486 See "CALLS WITH OPTIONAL ARGUMENTS".
11488 guestfs_mksquashfs_argv
11490 int
11491 guestfs_mksquashfs_argv (guestfs_h *g,
11492 const char *path,
11493 const char *filename,
11494 const struct guestfs_mksquashfs_argv *optargs);
11495 This is the "argv variant" of "guestfs_mksquashfs".
11497 See "CALLS WITH OPTIONAL ARGUMENTS".
11499 guestfs_mkswap
11501 int
11502 guestfs_mkswap (guestfs_h *g,
11503 const char *device);
11504 This function is provided for backwards compatibility with earlier
11506 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11507 optional arguments.
11508 (Added in 1.0.55)
11510 guestfs_mkswap_opts
11512 int
11513 guestfs_mkswap_opts (guestfs_h *g,
11514 const char *device,
11515 ...);
11516 You may supply a list of optional arguments to this call. Use zero or
11518 more of the following pairs of parameters, and terminate the list with
11519 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11520 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11522 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11523 Create a Linux swap partition on "device".
11525 The option arguments "label" and "uuid" allow you to set the label
11527 and/or UUID of the new swap partition.
11528 This function returns 0 on success or -1 on error.
11530 (Added in 1.0.55)
11532 guestfs_mkswap_opts_va
11534 int
11535 guestfs_mkswap_opts_va (guestfs_h *g,
11536 const char *device,
11537 va_list args);
11538 This is the "va_list variant" of "guestfs_mkswap_opts".
11540 See "CALLS WITH OPTIONAL ARGUMENTS".
11542 guestfs_mkswap_opts_argv
11544 int
11545 guestfs_mkswap_opts_argv (guestfs_h *g,
11546 const char *device,
11547 const struct guestfs_mkswap_opts_argv *optargs);
11548 This is the "argv variant" of "guestfs_mkswap_opts".
11550 See "CALLS WITH OPTIONAL ARGUMENTS".
11552 guestfs_mkswap_L
11554 int
11555 guestfs_mkswap_L (guestfs_h *g,
11556 const char *label,
11557 const char *device);
11558 This function is deprecated. In new code, use the "guestfs_mkswap"
11560 call instead.
11561 Deprecated functions will not be removed from the API, but the fact
11563 that they are deprecated indicates that there are problems with correct
11564 use of these functions.
11565 Create a swap partition on "device" with label "label".
11567 Note that you cannot attach a swap label to a block device (eg.
11569 /dev/sda), just to a partition. This appears to be a limitation of the
11570 kernel or swap tools.
11571 This function returns 0 on success or -1 on error.
11573 (Added in 1.0.55)
11575 guestfs_mkswap_U
11577 int
11578 guestfs_mkswap_U (guestfs_h *g,
11579 const char *uuid,
11580 const char *device);
11581 This function is deprecated. In new code, use the "guestfs_mkswap"
11583 call instead.
11584 Deprecated functions will not be removed from the API, but the fact
11586 that they are deprecated indicates that there are problems with correct
11587 use of these functions.
11588 Create a swap partition on "device" with UUID "uuid".
11590 This function returns 0 on success or -1 on error.
11592 This function depends on the feature "linuxfsuuid". See also
11594 "guestfs_feature_available".
11595 (Added in 1.0.55)
11597 guestfs_mkswap_file
11599 int
11600 guestfs_mkswap_file (guestfs_h *g,
11601 const char *path);
11602 Create a swap file.
11604 This command just writes a swap file signature to an existing file. To
11606 create the file itself, use something like "guestfs_fallocate".
11607 This function returns 0 on success or -1 on error.
11609 (Added in 1.0.66)
11611 guestfs_mktemp
11613 char *
11614 guestfs_mktemp (guestfs_h *g,
11615 const char *tmpl,
11616 ...);
11617 You may supply a list of optional arguments to this call. Use zero or
11619 more of the following pairs of parameters, and terminate the list with
11620 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11621 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11623 This command creates a temporary file. The "tmpl" parameter should be
11625 a full pathname for the temporary directory name with the final six
11626 characters being "XXXXXX".
11627 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11629 one being suitable for Windows filesystems.
11630 The name of the temporary file that was created is returned.
11632 The temporary file is created with mode 0600 and is owned by root.
11634 The caller is responsible for deleting the temporary file after use.
11636 If the optional "suffix" parameter is given, then the suffix (eg.
11638 ".txt") is appended to the temporary name.
11639 See also: "guestfs_mkdtemp".
11641 This function returns a string, or NULL on error. The caller must free
11643 the returned string after use.
11644 (Added in 1.19.53)
11646 guestfs_mktemp_va
11648 char *
11649 guestfs_mktemp_va (guestfs_h *g,
11650 const char *tmpl,
11651 va_list args);
11652 This is the "va_list variant" of "guestfs_mktemp".
11654 See "CALLS WITH OPTIONAL ARGUMENTS".
11656 guestfs_mktemp_argv
11658 char *
11659 guestfs_mktemp_argv (guestfs_h *g,
11660 const char *tmpl,
11661 const struct guestfs_mktemp_argv *optargs);
11662 This is the "argv variant" of "guestfs_mktemp".
11664 See "CALLS WITH OPTIONAL ARGUMENTS".
11666 guestfs_modprobe
11668 int
11669 guestfs_modprobe (guestfs_h *g,
11670 const char *modulename);
11671 This loads a kernel module in the appliance.
11673 This function returns 0 on success or -1 on error.
11675 This function depends on the feature "linuxmodules". See also
11677 "guestfs_feature_available".
11678 (Added in 1.0.68)
11680 guestfs_mount
11682 int
11683 guestfs_mount (guestfs_h *g,
11684 const char *mountable,
11685 const char *mountpoint);
11686 Mount a guest disk at a position in the filesystem. Block devices are
11688 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11689 If those block devices contain partitions, they will have the usual
11690 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11691 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11692 "guestfs_inspect_get_mountpoints".
11693 The rules are the same as for mount(2): A filesystem must first be
11695 mounted on / before others can be mounted. Other filesystems can only
11696 be mounted on directories which already exist.
11697 The mounted filesystem is writable, if we have sufficient permissions
11699 on the underlying device.
11700 Before libguestfs 1.13.16, this call implicitly added the options
11702 "sync" and "noatime". The "sync" option greatly slowed writes and
11703 caused many problems for users. If your program might need to work
11704 with older versions of libguestfs, use "guestfs_mount_options" instead
11705 (using an empty string for the first parameter if you don't want any
11706 options).
11707 This function returns 0 on success or -1 on error.
11709 (Added in 0.3)
11711 guestfs_mount_9p
11713 int
11714 guestfs_mount_9p (guestfs_h *g,
11715 const char *mounttag,
11716 const char *mountpoint,
11717 ...);
11718 You may supply a list of optional arguments to this call. Use zero or
11720 more of the following pairs of parameters, and terminate the list with
11721 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11722 GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11724 Mount the virtio-9p filesystem with the tag "mounttag" on the directory
11726 "mountpoint".
11727 If required, "trans=virtio" will be automatically added to the options.
11729 Any other options required can be passed in the optional "options"
11730 parameter.
11731 This function returns 0 on success or -1 on error.
11733 (Added in 1.11.12)
11735 guestfs_mount_9p_va
11737 int
11738 guestfs_mount_9p_va (guestfs_h *g,
11739 const char *mounttag,
11740 const char *mountpoint,
11741 va_list args);
11742 This is the "va_list variant" of "guestfs_mount_9p".
11744 See "CALLS WITH OPTIONAL ARGUMENTS".
11746 guestfs_mount_9p_argv
11748 int
11749 guestfs_mount_9p_argv (guestfs_h *g,
11750 const char *mounttag,
11751 const char *mountpoint,
11752 const struct guestfs_mount_9p_argv *optargs);
11753 This is the "argv variant" of "guestfs_mount_9p".
11755 See "CALLS WITH OPTIONAL ARGUMENTS".
11757 guestfs_mount_local
11759 int
11760 guestfs_mount_local (guestfs_h *g,
11761 const char *localmountpoint,
11762 ...);
11763 You may supply a list of optional arguments to this call. Use zero or
11765 more of the following pairs of parameters, and terminate the list with
11766 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11767 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11769 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11770 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11771 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11772 This call exports the libguestfs-accessible filesystem to a local
11774 mountpoint (directory) called "localmountpoint". Ordinary reads and
11775 writes to files and directories under "localmountpoint" are redirected
11776 through libguestfs.
11777 If the optional "readonly" flag is set to true, then writes to the
11779 filesystem return error "EROFS".
11780 "options" is a comma-separated list of mount options. See
11782 guestmount(1) for some useful options.
11783 "cachetimeout" sets the timeout (in seconds) for cached directory
11785 entries. The default is 60 seconds. See guestmount(1) for further
11786 information.
11787 If "debugcalls" is set to true, then additional debugging information
11789 is generated for every FUSE call.
11790 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11792 processing requests (access to it will block). You have to call
11793 "guestfs_mount_local_run" to run the main loop.
11794 See "MOUNT LOCAL" for full documentation.
11796 This function returns 0 on success or -1 on error.
11798 (Added in 1.17.22)
11800 guestfs_mount_local_va
11802 int
11803 guestfs_mount_local_va (guestfs_h *g,
11804 const char *localmountpoint,
11805 va_list args);
11806 This is the "va_list variant" of "guestfs_mount_local".
11808 See "CALLS WITH OPTIONAL ARGUMENTS".
11810 guestfs_mount_local_argv
11812 int
11813 guestfs_mount_local_argv (guestfs_h *g,
11814 const char *localmountpoint,
11815 const struct guestfs_mount_local_argv *optargs);
11816 This is the "argv variant" of "guestfs_mount_local".
11818 See "CALLS WITH OPTIONAL ARGUMENTS".
11820 guestfs_mount_local_run
11822 int
11823 guestfs_mount_local_run (guestfs_h *g);
11824 Run the main loop which translates kernel calls to libguestfs calls.
11826 This should only be called after "guestfs_mount_local" returns
11828 successfully. The call will not return until the filesystem is
11829 unmounted.
11830 Note you must not make concurrent libguestfs calls on the same handle
11832 from another thread.
11833 You may call this from a different thread than the one which called
11835 "guestfs_mount_local", subject to the usual rules for threads and
11836 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11837 See "MOUNT LOCAL" for full documentation.
11839 This function returns 0 on success or -1 on error.
11841 (Added in 1.17.22)
11843 guestfs_mount_loop
11845 int
11846 guestfs_mount_loop (guestfs_h *g,
11847 const char *file,
11848 const char *mountpoint);
11849 This command lets you mount file (a filesystem image in a file) on a
11851 mount point. It is entirely equivalent to the command "mount -o loop
11852 file mountpoint".
11853 This function returns 0 on success or -1 on error.
11855 (Added in 1.0.54)
11857 guestfs_mount_options
11859 int
11860 guestfs_mount_options (guestfs_h *g,
11861 const char *options,
11862 const char *mountable,
11863 const char *mountpoint);
11864 This is the same as the "guestfs_mount" command, but it allows you to
11866 set the mount options as for the mount(8) -o flag.
11867 If the "options" parameter is an empty string, then no options are
11869 passed (all options default to whatever the filesystem uses).
11870 This function returns 0 on success or -1 on error.
11872 (Added in 1.0.10)
11874 guestfs_mount_ro
11876 int
11877 guestfs_mount_ro (guestfs_h *g,
11878 const char *mountable,
11879 const char *mountpoint);
11880 This is the same as the "guestfs_mount" command, but it mounts the
11882 filesystem with the read-only (-o ro) flag.
11883 This function returns 0 on success or -1 on error.
11885 (Added in 1.0.10)
11887 guestfs_mount_vfs
11889 int
11890 guestfs_mount_vfs (guestfs_h *g,
11891 const char *options,
11892 const char *vfstype,
11893 const char *mountable,
11894 const char *mountpoint);
11895 This is the same as the "guestfs_mount" command, but it allows you to
11897 set both the mount options and the vfstype as for the mount(8) -o and
11898 -t flags.
11899 This function returns 0 on success or -1 on error.
11901 (Added in 1.0.10)
11903 guestfs_mountable_device
11905 char *
11906 guestfs_mountable_device (guestfs_h *g,
11907 const char *mountable);
11908 Returns the device name of a mountable. In quite a lot of cases, the
11910 mountable is the device name.
11911 However this doesn't apply for btrfs subvolumes, where the mountable is
11913 a combination of both the device name and the subvolume path (see also
11914 "guestfs_mountable_subvolume" to extract the subvolume path of the
11915 mountable if any).
11916 This function returns a string, or NULL on error. The caller must free
11918 the returned string after use.
11919 (Added in 1.33.15)
11921 guestfs_mountable_subvolume
11923 char *
11924 guestfs_mountable_subvolume (guestfs_h *g,
11925 const char *mountable);
11926 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11928 are a combination of both the device name and the subvolume path (see
11929 also "guestfs_mountable_device" to extract the device of the
11930 mountable).
11931 If the mountable does not represent a btrfs subvolume, then this
11933 function fails and the "errno" is set to "EINVAL".
11934 This function returns a string, or NULL on error. The caller must free
11936 the returned string after use.
11937 (Added in 1.33.15)
11939 guestfs_mountpoints
11941 char **
11942 guestfs_mountpoints (guestfs_h *g);
11943 This call is similar to "guestfs_mounts". That call returns a list of
11945 devices. This one returns a hash table (map) of device name to
11946 directory where the device is mounted.
11947 This function returns a NULL-terminated array of strings, or NULL if
11949 there was an error. The array of strings will always have length
11950 "2n+1", where "n" keys and values alternate, followed by the trailing
11951 NULL entry. The caller must free the strings and the array after use.
11952 (Added in 1.0.62)
11954 guestfs_mounts
11956 char **
11957 guestfs_mounts (guestfs_h *g);
11958 This returns the list of currently mounted filesystems. It returns the
11960 list of devices (eg. /dev/sda1, /dev/VG/LV).
11961 Some internal mounts are not shown.
11963 See also: "guestfs_mountpoints"
11965 This function returns a NULL-terminated array of strings (like
11967 environ(3)), or NULL if there was an error. The caller must free the
11968 strings and the array after use.
11969 (Added in 0.8)
11971 guestfs_mv
11973 int
11974 guestfs_mv (guestfs_h *g,
11975 const char *src,
11976 const char *dest);
11977 This moves a file from "src" to "dest" where "dest" is either a
11979 destination filename or destination directory.
11980 See also: "guestfs_rename".
11982 This function returns 0 on success or -1 on error.
11984 (Added in 1.0.18)
11986 guestfs_nr_devices
11988 int
11989 guestfs_nr_devices (guestfs_h *g);
11990 This returns the number of whole block devices that were added. This
11992 is the same as the number of devices that would be returned if you
11993 called "guestfs_list_devices".
11994 To find out the maximum number of devices that could be added, call
11996 "guestfs_max_disks".
11997 On error this function returns -1.
11999 (Added in 1.19.15)
12001 guestfs_ntfs_3g_probe
12003 int
12004 guestfs_ntfs_3g_probe (guestfs_h *g,
12005 int rw,
12006 const char *device);
12007 This command runs the ntfs-3g.probe(8) command which probes an NTFS
12009 "device" for mountability. (Not all NTFS volumes can be mounted read-
12010 write, and some cannot be mounted at all).
12011 "rw" is a boolean flag. Set it to true if you want to test if the
12013 volume can be mounted read-write. Set it to false if you want to test
12014 if the volume can be mounted read-only.
12015 The return value is an integer which 0 if the operation would succeed,
12017 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
12018 On error this function returns -1.
12020 This function depends on the feature "ntfs3g". See also
12022 "guestfs_feature_available".
12023 (Added in 1.0.43)
12025 guestfs_ntfscat_i
12027 int
12028 guestfs_ntfscat_i (guestfs_h *g,
12029 const char *device,
12030 int64_t inode,
12031 const char *filename);
12032 Download a file given its inode from a NTFS filesystem and save it as
12034 filename on the local machine.
12035 This allows to download some otherwise inaccessible files such as the
12037 ones within the $Extend folder.
12038 The filesystem from which to extract the file must be unmounted,
12040 otherwise the call will fail.
12041 This function returns 0 on success or -1 on error.
12043 This long-running command can generate progress notification messages
12045 so that the caller can display a progress bar or indicator. To receive
12046 these messages, the caller must register a progress event callback.
12047 See "GUESTFS_EVENT_PROGRESS".
12048 (Added in 1.33.14)
12050 guestfs_ntfsclone_in
12052 int
12053 guestfs_ntfsclone_in (guestfs_h *g,
12054 const char *backupfile,
12055 const char *device);
12056 Restore the "backupfile" (from a previous call to
12058 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
12059 of this device.
12060 This function returns 0 on success or -1 on error.
12062 This function depends on the feature "ntfs3g". See also
12064 "guestfs_feature_available".
12065 (Added in 1.17.9)
12067 guestfs_ntfsclone_out
12069 int
12070 guestfs_ntfsclone_out (guestfs_h *g,
12071 const char *device,
12072 const char *backupfile,
12073 ...);
12074 You may supply a list of optional arguments to this call. Use zero or
12076 more of the following pairs of parameters, and terminate the list with
12077 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12078 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
12080 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
12081 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
12082 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
12083 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
12084 Stream the NTFS filesystem "device" to the local file "backupfile".
12086 The format used for the backup file is a special format used by the
12087 ntfsclone(8) tool.
12088 If the optional "metadataonly" flag is true, then only the metadata is
12090 saved, losing all the user data (this is useful for diagnosing some
12091 filesystem problems).
12092 The optional "rescue", "ignorefscheck", "preservetimestamps" and
12094 "force" flags have precise meanings detailed in the ntfsclone(8) man
12095 page.
12096 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
12098 device.
12099 This function returns 0 on success or -1 on error.
12101 This function depends on the feature "ntfs3g". See also
12103 "guestfs_feature_available".
12104 (Added in 1.17.9)
12106 guestfs_ntfsclone_out_va
12108 int
12109 guestfs_ntfsclone_out_va (guestfs_h *g,
12110 const char *device,
12111 const char *backupfile,
12112 va_list args);
12113 This is the "va_list variant" of "guestfs_ntfsclone_out".
12115 See "CALLS WITH OPTIONAL ARGUMENTS".
12117 guestfs_ntfsclone_out_argv
12119 int
12120 guestfs_ntfsclone_out_argv (guestfs_h *g,
12121 const char *device,
12122 const char *backupfile,
12123 const struct guestfs_ntfsclone_out_argv *optargs);
12124 This is the "argv variant" of "guestfs_ntfsclone_out".
12126 See "CALLS WITH OPTIONAL ARGUMENTS".
12128 guestfs_ntfsfix
12130 int
12131 guestfs_ntfsfix (guestfs_h *g,
12132 const char *device,
12133 ...);
12134 You may supply a list of optional arguments to this call. Use zero or
12136 more of the following pairs of parameters, and terminate the list with
12137 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12138 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
12140 This command repairs some fundamental NTFS inconsistencies, resets the
12142 NTFS journal file, and schedules an NTFS consistency check for the
12143 first boot into Windows.
12144 This is not an equivalent of Windows "chkdsk". It does not scan the
12146 filesystem for inconsistencies.
12147 The optional "clearbadsectors" flag clears the list of bad sectors.
12149 This is useful after cloning a disk with bad sectors to a new disk.
12150 This function returns 0 on success or -1 on error.
12152 This function depends on the feature "ntfs3g". See also
12154 "guestfs_feature_available".
12155 (Added in 1.17.9)
12157 guestfs_ntfsfix_va
12159 int
12160 guestfs_ntfsfix_va (guestfs_h *g,
12161 const char *device,
12162 va_list args);
12163 This is the "va_list variant" of "guestfs_ntfsfix".
12165 See "CALLS WITH OPTIONAL ARGUMENTS".
12167 guestfs_ntfsfix_argv
12169 int
12170 guestfs_ntfsfix_argv (guestfs_h *g,
12171 const char *device,
12172 const struct guestfs_ntfsfix_argv *optargs);
12173 This is the "argv variant" of "guestfs_ntfsfix".
12175 See "CALLS WITH OPTIONAL ARGUMENTS".
12177 guestfs_ntfsresize
12179 int
12180 guestfs_ntfsresize (guestfs_h *g,
12181 const char *device);
12182 This function is provided for backwards compatibility with earlier
12184 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
12185 no optional arguments.
12186 (Added in 1.3.2)
12188 guestfs_ntfsresize_opts
12190 int
12191 guestfs_ntfsresize_opts (guestfs_h *g,
12192 const char *device,
12193 ...);
12194 You may supply a list of optional arguments to this call. Use zero or
12196 more of the following pairs of parameters, and terminate the list with
12197 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12198 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12200 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12201 This command resizes an NTFS filesystem, expanding or shrinking it to
12203 the size of the underlying device.
12204 The optional parameters are:
12206 "size"
12208 The new size (in bytes) of the filesystem. If omitted, the
12209 filesystem is resized to fit the container (eg. partition).
12210 "force"
12212 If this option is true, then force the resize of the filesystem
12213 even if the filesystem is marked as requiring a consistency check.
12214 After the resize operation, the filesystem is always marked as
12216 requiring a consistency check (for safety). You have to boot into
12217 Windows to perform this check and clear this condition. If you
12218 don't set the "force" option then it is not possible to call
12219 "guestfs_ntfsresize" multiple times on a single filesystem without
12220 booting into Windows between each resize.
12221 See also ntfsresize(8).
12223 This function returns 0 on success or -1 on error.
12225 This function depends on the feature "ntfsprogs". See also
12227 "guestfs_feature_available".
12228 (Added in 1.3.2)
12230 guestfs_ntfsresize_opts_va
12232 int
12233 guestfs_ntfsresize_opts_va (guestfs_h *g,
12234 const char *device,
12235 va_list args);
12236 This is the "va_list variant" of "guestfs_ntfsresize_opts".
12238 See "CALLS WITH OPTIONAL ARGUMENTS".
12240 guestfs_ntfsresize_opts_argv
12242 int
12243 guestfs_ntfsresize_opts_argv (guestfs_h *g,
12244 const char *device,
12245 const struct guestfs_ntfsresize_opts_argv *optargs);
12246 This is the "argv variant" of "guestfs_ntfsresize_opts".
12248 See "CALLS WITH OPTIONAL ARGUMENTS".
12250 guestfs_ntfsresize_size
12252 int
12253 guestfs_ntfsresize_size (guestfs_h *g,
12254 const char *device,
12255 int64_t size);
12256 This function is deprecated. In new code, use the "guestfs_ntfsresize"
12258 call instead.
12259 Deprecated functions will not be removed from the API, but the fact
12261 that they are deprecated indicates that there are problems with correct
12262 use of these functions.
12263 This command is the same as "guestfs_ntfsresize" except that it allows
12265 you to specify the new size (in bytes) explicitly.
12266 This function returns 0 on success or -1 on error.
12268 This function depends on the feature "ntfsprogs". See also
12270 "guestfs_feature_available".
12271 (Added in 1.3.14)
12273 guestfs_parse_environment
12275 int
12276 guestfs_parse_environment (guestfs_h *g);
12277 Parse the program’s environment and set flags in the handle
12279 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12280 flag is set in the handle.
12281 Most programs do not need to call this. It is done implicitly when you
12283 call "guestfs_create".
12284 See "ENVIRONMENT VARIABLES" for a list of environment variables that
12286 can affect libguestfs handles. See also "guestfs_create_flags", and
12287 "guestfs_parse_environment_list".
12288 This function returns 0 on success or -1 on error.
12290 (Added in 1.19.53)
12292 guestfs_parse_environment_list
12294 int
12295 guestfs_parse_environment_list (guestfs_h *g,
12296 char *const *environment);
12297 Parse the list of strings in the argument "environment" and set flags
12299 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
12300 string in the list, then the ‘verbose’ flag is set in the handle.
12301 This is the same as "guestfs_parse_environment" except that it parses
12303 an explicit list of strings instead of the program's environment.
12304 This function returns 0 on success or -1 on error.
12306 (Added in 1.19.53)
12308 guestfs_part_add
12310 int
12311 guestfs_part_add (guestfs_h *g,
12312 const char *device,
12313 const char *prlogex,
12314 int64_t startsect,
12315 int64_t endsect);
12316 This command adds a partition to "device". If there is no partition
12318 table on the device, call "guestfs_part_init" first.
12319 The "prlogex" parameter is the type of partition. Normally you should
12321 pass "p" or "primary" here, but MBR partition tables also support "l"
12322 (or "logical") and "e" (or "extended") partition types.
12323 "startsect" and "endsect" are the start and end of the partition in
12325 sectors. "endsect" may be negative, which means it counts backwards
12326 from the end of the disk ("-1" is the last sector).
12327 Creating a partition which covers the whole disk is not so easy. Use
12329 "guestfs_part_disk" to do that.
12330 This function returns 0 on success or -1 on error.
12332 (Added in 1.0.78)
12334 guestfs_part_del
12336 int
12337 guestfs_part_del (guestfs_h *g,
12338 const char *device,
12339 int partnum);
12340 This command deletes the partition numbered "partnum" on "device".
12342 Note that in the case of MBR partitioning, deleting an extended
12344 partition also deletes any logical partitions it contains.
12345 This function returns 0 on success or -1 on error.
12347 (Added in 1.3.2)
12349 guestfs_part_disk
12351 int
12352 guestfs_part_disk (guestfs_h *g,
12353 const char *device,
12354 const char *parttype);
12355 This command is simply a combination of "guestfs_part_init" followed by
12357 "guestfs_part_add" to create a single primary partition covering the
12358 whole disk.
12359 "parttype" is the partition table type, usually "mbr" or "gpt", but
12361 other possible values are described in "guestfs_part_init".
12362 This function returns 0 on success or -1 on error.
12364 (Added in 1.0.78)
12366 guestfs_part_expand_gpt
12368 int
12369 guestfs_part_expand_gpt (guestfs_h *g,
12370 const char *device);
12371 Move backup GPT data structures to the end of the disk. This is useful
12373 in case of in-place image expand since disk space after backup GPT
12374 header is not usable. This is equivalent to "sgdisk -e".
12375 See also sgdisk(8).
12377 This function returns 0 on success or -1 on error.
12379 This function depends on the feature "gdisk". See also
12381 "guestfs_feature_available".
12382 (Added in 1.33.2)
12384 guestfs_part_get_bootable
12386 int
12387 guestfs_part_get_bootable (guestfs_h *g,
12388 const char *device,
12389 int partnum);
12390 This command returns true if the partition "partnum" on "device" has
12392 the bootable flag set.
12393 See also "guestfs_part_set_bootable".
12395 This function returns a C truth value on success or -1 on error.
12397 (Added in 1.3.2)
12399 guestfs_part_get_disk_guid
12401 char *
12402 guestfs_part_get_disk_guid (guestfs_h *g,
12403 const char *device);
12404 Return the disk identifier (GUID) of a GPT-partitioned "device".
12406 Behaviour is undefined for other partition types.
12407 This function returns a string, or NULL on error. The caller must free
12409 the returned string after use.
12410 This function depends on the feature "gdisk". See also
12412 "guestfs_feature_available".
12413 (Added in 1.33.2)
12415 guestfs_part_get_gpt_attributes
12417 int64_t
12418 guestfs_part_get_gpt_attributes (guestfs_h *g,
12419 const char *device,
12420 int partnum);
12421 Return the attribute flags of numbered GPT partition "partnum". An
12423 error is returned for MBR partitions.
12424 On error this function returns -1.
12426 This function depends on the feature "gdisk". See also
12428 "guestfs_feature_available".
12429 (Added in 1.21.1)
12431 guestfs_part_get_gpt_guid
12433 char *
12434 guestfs_part_get_gpt_guid (guestfs_h *g,
12435 const char *device,
12436 int partnum);
12437 Return the GUID of numbered GPT partition "partnum".
12439 This function returns a string, or NULL on error. The caller must free
12441 the returned string after use.
12442 This function depends on the feature "gdisk". See also
12444 "guestfs_feature_available".
12445 (Added in 1.29.25)
12447 guestfs_part_get_gpt_type
12449 char *
12450 guestfs_part_get_gpt_type (guestfs_h *g,
12451 const char *device,
12452 int partnum);
12453 Return the type GUID of numbered GPT partition "partnum". For MBR
12455 partitions, return an appropriate GUID corresponding to the MBR type.
12456 Behaviour is undefined for other partition types.
12457 This function returns a string, or NULL on error. The caller must free
12459 the returned string after use.
12460 This function depends on the feature "gdisk". See also
12462 "guestfs_feature_available".
12463 (Added in 1.21.1)
12465 guestfs_part_get_mbr_id
12467 int
12468 guestfs_part_get_mbr_id (guestfs_h *g,
12469 const char *device,
12470 int partnum);
12471 Returns the MBR type byte (also known as the ID byte) from the numbered
12473 partition "partnum".
12474 Note that only MBR (old DOS-style) partitions have type bytes. You
12476 will get undefined results for other partition table types (see
12477 "guestfs_part_get_parttype").
12478 On error this function returns -1.
12480 (Added in 1.3.2)
12482 guestfs_part_get_mbr_part_type
12484 char *
12485 guestfs_part_get_mbr_part_type (guestfs_h *g,
12486 const char *device,
12487 int partnum);
12488 This returns the partition type of an MBR partition numbered "partnum"
12490 on device "device".
12491 It returns "primary", "logical", or "extended".
12493 This function returns a string, or NULL on error. The caller must free
12495 the returned string after use.
12496 (Added in 1.29.32)
12498 guestfs_part_get_name
12500 char *
12501 guestfs_part_get_name (guestfs_h *g,
12502 const char *device,
12503 int partnum);
12504 This gets the partition name on partition numbered "partnum" on device
12506 "device". Note that partitions are numbered from 1.
12507 The partition name can only be read on certain types of partition
12509 table. This works on "gpt" but not on "mbr" partitions.
12510 This function returns a string, or NULL on error. The caller must free
12512 the returned string after use.
12513 (Added in 1.25.33)
12515 guestfs_part_get_parttype
12517 char *
12518 guestfs_part_get_parttype (guestfs_h *g,
12519 const char *device);
12520 This command examines the partition table on "device" and returns the
12522 partition table type (format) being used.
12523 Common return values include: "msdos" (a DOS/Windows style MBR
12525 partition table), "gpt" (a GPT/EFI-style partition table). Other
12526 values are possible, although unusual. See "guestfs_part_init" for a
12527 full list.
12528 This function returns a string, or NULL on error. The caller must free
12530 the returned string after use.
12531 (Added in 1.0.78)
12533 guestfs_part_init
12535 int
12536 guestfs_part_init (guestfs_h *g,
12537 const char *device,
12538 const char *parttype);
12539 This creates an empty partition table on "device" of one of the
12541 partition types listed below. Usually "parttype" should be either
12542 "msdos" or "gpt" (for large disks).
12543 Initially there are no partitions. Following this, you should call
12545 "guestfs_part_add" for each partition required.
12546 Possible values for "parttype" are:
12548 "efi"
12550 "gpt"
12551 Intel EFI / GPT partition table.
12552 This is recommended for >= 2 TB partitions that will be accessed
12554 from Linux and Intel-based Mac OS X. It also has limited backwards
12555 compatibility with the "mbr" format.
12556 "mbr"
12558 "msdos"
12559 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12560 and Windows. This partition type will only work for device sizes
12561 up to 2 TB. For large disks we recommend using "gpt".
12562 Other partition table types that may work but are not supported
12564 include:
12565 "aix"
12567 AIX disk labels.
12568 "amiga"
12570 "rdb"
12571 Amiga "Rigid Disk Block" format.
12572 "bsd"
12574 BSD disk labels.
12575 "dasd"
12577 DASD, used on IBM mainframes.
12578 "dvh"
12580 MIPS/SGI volumes.
12581 "mac"
12583 Old Mac partition format. Modern Macs use "gpt".
12584 "pc98"
12586 NEC PC-98 format, common in Japan apparently.
12587 "sun"
12589 Sun disk labels.
12590 This function returns 0 on success or -1 on error.
12592 (Added in 1.0.78)
12594 guestfs_part_list
12596 struct guestfs_partition_list *
12597 guestfs_part_list (guestfs_h *g,
12598 const char *device);
12599 This command parses the partition table on "device" and returns the
12601 list of partitions found.
12602 The fields in the returned structure are:
12604 "part_num"
12606 Partition number, counting from 1.
12607 "part_start"
12609 Start of the partition in bytes. To get sectors you have to divide
12610 by the device’s sector size, see "guestfs_blockdev_getss".
12611 "part_end"
12613 End of the partition in bytes.
12614 "part_size"
12616 Size of the partition in bytes.
12617 This function returns a "struct guestfs_partition_list *", or NULL if
12619 there was an error. The caller must call "guestfs_free_partition_list"
12620 after use.
12621 (Added in 1.0.78)
12623 guestfs_part_resize
12625 int
12626 guestfs_part_resize (guestfs_h *g,
12627 const char *device,
12628 int partnum,
12629 int64_t endsect);
12630 This command resizes the partition numbered "partnum" on "device" by
12632 moving the end position.
12633 Note that this does not modify any filesystem present in the partition.
12635 If you wish to do this, you will need to use filesystem resizing
12636 commands like "guestfs_resize2fs".
12637 When growing a partition you will want to grow the filesystem
12639 afterwards, but when shrinking, you need to shrink the filesystem
12640 before the partition.
12641 This function returns 0 on success or -1 on error.
12643 (Added in 1.37.20)
12645 guestfs_part_set_bootable
12647 int
12648 guestfs_part_set_bootable (guestfs_h *g,
12649 const char *device,
12650 int partnum,
12651 int bootable);
12652 This sets the bootable flag on partition numbered "partnum" on device
12654 "device". Note that partitions are numbered from 1.
12655 The bootable flag is used by some operating systems (notably Windows)
12657 to determine which partition to boot from. It is by no means
12658 universally recognized.
12659 This function returns 0 on success or -1 on error.
12661 (Added in 1.0.78)
12663 guestfs_part_set_disk_guid
12665 int
12666 guestfs_part_set_disk_guid (guestfs_h *g,
12667 const char *device,
12668 const char *guid);
12669 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12671 Return an error if the partition table of "device" isn't GPT, or if
12672 "guid" is not a valid GUID.
12673 This function returns 0 on success or -1 on error.
12675 This function depends on the feature "gdisk". See also
12677 "guestfs_feature_available".
12678 (Added in 1.33.2)
12680 guestfs_part_set_disk_guid_random
12682 int
12683 guestfs_part_set_disk_guid_random (guestfs_h *g,
12684 const char *device);
12685 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12687 randomly generated value. Return an error if the partition table of
12688 "device" isn't GPT.
12689 This function returns 0 on success or -1 on error.
12691 This function depends on the feature "gdisk". See also
12693 "guestfs_feature_available".
12694 (Added in 1.33.2)
12696 guestfs_part_set_gpt_attributes
12698 int
12699 guestfs_part_set_gpt_attributes (guestfs_h *g,
12700 const char *device,
12701 int partnum,
12702 int64_t attributes);
12703 Set the attribute flags of numbered GPT partition "partnum" to
12705 "attributes". Return an error if the partition table of "device" isn't
12706 GPT.
12707 See
12709 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12710 for a useful list of partition attributes.
12711 This function returns 0 on success or -1 on error.
12713 This function depends on the feature "gdisk". See also
12715 "guestfs_feature_available".
12716 (Added in 1.21.1)
12718 guestfs_part_set_gpt_guid
12720 int
12721 guestfs_part_set_gpt_guid (guestfs_h *g,
12722 const char *device,
12723 int partnum,
12724 const char *guid);
12725 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12727 error if the partition table of "device" isn't GPT, or if "guid" is not
12728 a valid GUID.
12729 This function returns 0 on success or -1 on error.
12731 This function depends on the feature "gdisk". See also
12733 "guestfs_feature_available".
12734 (Added in 1.29.25)
12736 guestfs_part_set_gpt_type
12738 int
12739 guestfs_part_set_gpt_type (guestfs_h *g,
12740 const char *device,
12741 int partnum,
12742 const char *guid);
12743 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12745 an error if the partition table of "device" isn't GPT, or if "guid" is
12746 not a valid GUID.
12747 See
12749 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12750 for a useful list of type GUIDs.
12751 This function returns 0 on success or -1 on error.
12753 This function depends on the feature "gdisk". See also
12755 "guestfs_feature_available".
12756 (Added in 1.21.1)
12758 guestfs_part_set_mbr_id
12760 int
12761 guestfs_part_set_mbr_id (guestfs_h *g,
12762 const char *device,
12763 int partnum,
12764 int idbyte);
12765 Sets the MBR type byte (also known as the ID byte) of the numbered
12767 partition "partnum" to "idbyte". Note that the type bytes quoted in
12768 most documentation are in fact hexadecimal numbers, but usually
12769 documented without any leading "0x" which might be confusing.
12770 Note that only MBR (old DOS-style) partitions have type bytes. You
12772 will get undefined results for other partition table types (see
12773 "guestfs_part_get_parttype").
12774 This function returns 0 on success or -1 on error.
12776 (Added in 1.3.2)
12778 guestfs_part_set_name
12780 int
12781 guestfs_part_set_name (guestfs_h *g,
12782 const char *device,
12783 int partnum,
12784 const char *name);
12785 This sets the partition name on partition numbered "partnum" on device
12787 "device". Note that partitions are numbered from 1.
12788 The partition name can only be set on certain types of partition table.
12790 This works on "gpt" but not on "mbr" partitions.
12791 This function returns 0 on success or -1 on error.
12793 (Added in 1.0.78)
12795 guestfs_part_to_dev
12797 char *
12798 guestfs_part_to_dev (guestfs_h *g,
12799 const char *partition);
12800 This function takes a partition name (eg. "/dev/sdb1") and removes the
12802 partition number, returning the device name (eg. "/dev/sdb").
12803 The named partition must exist, for example as a string returned from
12805 "guestfs_list_partitions".
12806 See also "guestfs_part_to_partnum", "guestfs_device_index".
12808 This function returns a string, or NULL on error. The caller must free
12810 the returned string after use.
12811 (Added in 1.5.15)
12813 guestfs_part_to_partnum
12815 int
12816 guestfs_part_to_partnum (guestfs_h *g,
12817 const char *partition);
12818 This function takes a partition name (eg. "/dev/sdb1") and returns the
12820 partition number (eg. 1).
12821 The named partition must exist, for example as a string returned from
12823 "guestfs_list_partitions".
12824 See also "guestfs_part_to_dev".
12826 On error this function returns -1.
12828 (Added in 1.13.25)
12830 guestfs_ping_daemon
12832 int
12833 guestfs_ping_daemon (guestfs_h *g);
12834 This is a test probe into the guestfs daemon running inside the
12836 libguestfs appliance. Calling this function checks that the daemon
12837 responds to the ping message, without affecting the daemon or attached
12838 block device(s) in any other way.
12839 This function returns 0 on success or -1 on error.
12841 (Added in 1.0.18)
12843 guestfs_pread
12845 char *
12846 guestfs_pread (guestfs_h *g,
12847 const char *path,
12848 int count,
12849 int64_t offset,
12850 size_t *size_r);
12851 This command lets you read part of a file. It reads "count" bytes of
12853 the file, starting at "offset", from file "path".
12854 This may read fewer bytes than requested. For further details see the
12856 pread(2) system call.
12857 See also "guestfs_pwrite", "guestfs_pread_device".
12859 This function returns a buffer, or NULL on error. The size of the
12861 returned buffer is written to *size_r. The caller must free the
12862 returned buffer after use.
12863 Because of the message protocol, there is a transfer limit of somewhere
12865 between 2MB and 4MB. See "PROTOCOL LIMITS".
12866 (Added in 1.0.77)
12868 guestfs_pread_device
12870 char *
12871 guestfs_pread_device (guestfs_h *g,
12872 const char *device,
12873 int count,
12874 int64_t offset,
12875 size_t *size_r);
12876 This command lets you read part of a block device. It reads "count"
12878 bytes of "device", starting at "offset".
12879 This may read fewer bytes than requested. For further details see the
12881 pread(2) system call.
12882 See also "guestfs_pread".
12884 This function returns a buffer, or NULL on error. The size of the
12886 returned buffer is written to *size_r. The caller must free the
12887 returned buffer after use.
12888 Because of the message protocol, there is a transfer limit of somewhere
12890 between 2MB and 4MB. See "PROTOCOL LIMITS".
12891 (Added in 1.5.21)
12893 guestfs_pvchange_uuid
12895 int
12896 guestfs_pvchange_uuid (guestfs_h *g,
12897 const char *device);
12898 Generate a new random UUID for the physical volume "device".
12900 This function returns 0 on success or -1 on error.
12902 This function depends on the feature "lvm2". See also
12904 "guestfs_feature_available".
12905 (Added in 1.19.26)
12907 guestfs_pvchange_uuid_all
12909 int
12910 guestfs_pvchange_uuid_all (guestfs_h *g);
12911 Generate new random UUIDs for all physical volumes.
12913 This function returns 0 on success or -1 on error.
12915 This function depends on the feature "lvm2". See also
12917 "guestfs_feature_available".
12918 (Added in 1.19.26)
12920 guestfs_pvcreate
12922 int
12923 guestfs_pvcreate (guestfs_h *g,
12924 const char *device);
12925 This creates an LVM physical volume on the named "device", where
12927 "device" should usually be a partition name such as /dev/sda1.
12928 This function returns 0 on success or -1 on error.
12930 This function depends on the feature "lvm2". See also
12932 "guestfs_feature_available".
12933 (Added in 0.8)
12935 guestfs_pvremove
12937 int
12938 guestfs_pvremove (guestfs_h *g,
12939 const char *device);
12940 This wipes a physical volume "device" so that LVM will no longer
12942 recognise it.
12943 The implementation uses the pvremove(8) command which refuses to wipe
12945 physical volumes that contain any volume groups, so you have to remove
12946 those first.
12947 This function returns 0 on success or -1 on error.
12949 This function depends on the feature "lvm2". See also
12951 "guestfs_feature_available".
12952 (Added in 1.0.13)
12954 guestfs_pvresize
12956 int
12957 guestfs_pvresize (guestfs_h *g,
12958 const char *device);
12959 This resizes (expands or shrinks) an existing LVM physical volume to
12961 match the new size of the underlying device.
12962 This function returns 0 on success or -1 on error.
12964 This function depends on the feature "lvm2". See also
12966 "guestfs_feature_available".
12967 (Added in 1.0.26)
12969 guestfs_pvresize_size
12971 int
12972 guestfs_pvresize_size (guestfs_h *g,
12973 const char *device,
12974 int64_t size);
12975 This command is the same as "guestfs_pvresize" except that it allows
12977 you to specify the new size (in bytes) explicitly.
12978 This function returns 0 on success or -1 on error.
12980 This function depends on the feature "lvm2". See also
12982 "guestfs_feature_available".
12983 (Added in 1.3.14)
12985 guestfs_pvs
12987 char **
12988 guestfs_pvs (guestfs_h *g);
12989 List all the physical volumes detected. This is the equivalent of the
12991 pvs(8) command.
12992 This returns a list of just the device names that contain PVs (eg.
12994 /dev/sda2).
12995 See also "guestfs_pvs_full".
12997 This function returns a NULL-terminated array of strings (like
12999 environ(3)), or NULL if there was an error. The caller must free the
13000 strings and the array after use.
13001 This function depends on the feature "lvm2". See also
13003 "guestfs_feature_available".
13004 (Added in 0.4)
13006 guestfs_pvs_full
13008 struct guestfs_lvm_pv_list *
13009 guestfs_pvs_full (guestfs_h *g);
13010 List all the physical volumes detected. This is the equivalent of the
13012 pvs(8) command. The "full" version includes all fields.
13013 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
13015 there was an error. The caller must call "guestfs_free_lvm_pv_list"
13016 after use.
13017 This function depends on the feature "lvm2". See also
13019 "guestfs_feature_available".
13020 (Added in 0.4)
13022 guestfs_pvuuid
13024 char *
13025 guestfs_pvuuid (guestfs_h *g,
13026 const char *device);
13027 This command returns the UUID of the LVM PV "device".
13029 This function returns a string, or NULL on error. The caller must free
13031 the returned string after use.
13032 (Added in 1.0.87)
13034 guestfs_pwrite
13036 int
13037 guestfs_pwrite (guestfs_h *g,
13038 const char *path,
13039 const char *content,
13040 size_t content_size,
13041 int64_t offset);
13042 This command writes to part of a file. It writes the data buffer
13044 "content" to the file "path" starting at offset "offset".
13045 This command implements the pwrite(2) system call, and like that system
13047 call it may not write the full data requested. The return value is the
13048 number of bytes that were actually written to the file. This could
13049 even be 0, although short writes are unlikely for regular files in
13050 ordinary circumstances.
13051 See also "guestfs_pread", "guestfs_pwrite_device".
13053 On error this function returns -1.
13055 Because of the message protocol, there is a transfer limit of somewhere
13057 between 2MB and 4MB. See "PROTOCOL LIMITS".
13058 (Added in 1.3.14)
13060 guestfs_pwrite_device
13062 int
13063 guestfs_pwrite_device (guestfs_h *g,
13064 const char *device,
13065 const char *content,
13066 size_t content_size,
13067 int64_t offset);
13068 This command writes to part of a device. It writes the data buffer
13070 "content" to "device" starting at offset "offset".
13071 This command implements the pwrite(2) system call, and like that system
13073 call it may not write the full data requested (although short writes to
13074 disk devices and partitions are probably impossible with standard Linux
13075 kernels).
13076 See also "guestfs_pwrite".
13078 On error this function returns -1.
13080 Because of the message protocol, there is a transfer limit of somewhere
13082 between 2MB and 4MB. See "PROTOCOL LIMITS".
13083 (Added in 1.5.20)
13085 guestfs_read_file
13087 char *
13088 guestfs_read_file (guestfs_h *g,
13089 const char *path,
13090 size_t *size_r);
13091 This calls returns the contents of the file "path" as a buffer.
13093 Unlike "guestfs_cat", this function can correctly handle files that
13095 contain embedded ASCII NUL characters.
13096 This function returns a buffer, or NULL on error. The size of the
13098 returned buffer is written to *size_r. The caller must free the
13099 returned buffer after use.
13100 (Added in 1.0.63)
13102 guestfs_read_lines
13104 char **
13105 guestfs_read_lines (guestfs_h *g,
13106 const char *path);
13107 Return the contents of the file named "path".
13109 The file contents are returned as a list of lines. Trailing "LF" and
13111 "CRLF" character sequences are not returned.
13112 Note that this function cannot correctly handle binary files
13114 (specifically, files containing "\0" character which is treated as end
13115 of string). For those you need to use the "guestfs_read_file" function
13116 and split the buffer into lines yourself.
13117 This function returns a NULL-terminated array of strings (like
13119 environ(3)), or NULL if there was an error. The caller must free the
13120 strings and the array after use.
13121 (Added in 0.7)
13123 guestfs_readdir
13125 struct guestfs_dirent_list *
13126 guestfs_readdir (guestfs_h *g,
13127 const char *dir);
13128 This returns the list of directory entries in directory "dir".
13130 All entries in the directory are returned, including "." and "..". The
13132 entries are not sorted, but returned in the same order as the
13133 underlying filesystem.
13134 Also this call returns basic file type information about each file.
13136 The "ftyp" field will contain one of the following characters:
13137 'b' Block special
13139 'c' Char special
13141 'd' Directory
13143 'f' FIFO (named pipe)
13145 'l' Symbolic link
13147 'r' Regular file
13149 's' Socket
13151 'u' Unknown file type
13153 '?' The readdir(3) call returned a "d_type" field with an unexpected
13155 value
13156 This function is primarily intended for use by programs. To get a
13158 simple list of names, use "guestfs_ls". To get a printable directory
13159 for human consumption, use "guestfs_ll".
13160 This function returns a "struct guestfs_dirent_list *", or NULL if
13162 there was an error. The caller must call "guestfs_free_dirent_list"
13163 after use.
13164 Because of the message protocol, there is a transfer limit of somewhere
13166 between 2MB and 4MB. See "PROTOCOL LIMITS".
13167 (Added in 1.0.55)
13169 guestfs_readlink
13171 char *
13172 guestfs_readlink (guestfs_h *g,
13173 const char *path);
13174 This command reads the target of a symbolic link.
13176 This function returns a string, or NULL on error. The caller must free
13178 the returned string after use.
13179 (Added in 1.0.66)
13181 guestfs_readlinklist
13183 char **
13184 guestfs_readlinklist (guestfs_h *g,
13185 const char *path,
13186 char *const *names);
13187 This call allows you to do a "readlink" operation on multiple files,
13189 where all files are in the directory "path". "names" is the list of
13190 files from this directory.
13191 On return you get a list of strings, with a one-to-one correspondence
13193 to the "names" list. Each string is the value of the symbolic link.
13194 If the readlink(2) operation fails on any name, then the corresponding
13196 result string is the empty string "". However the whole operation is
13197 completed even if there were readlink(2) errors, and so you can call
13198 this function with names where you don't know if they are symbolic
13199 links already (albeit slightly less efficient).
13200 This call is intended for programs that want to efficiently list a
13202 directory contents without making many round-trips.
13203 This function returns a NULL-terminated array of strings (like
13205 environ(3)), or NULL if there was an error. The caller must free the
13206 strings and the array after use.
13207 (Added in 1.0.77)
13209 guestfs_realpath
13211 char *
13212 guestfs_realpath (guestfs_h *g,
13213 const char *path);
13214 Return the canonicalized absolute pathname of "path". The returned
13216 path has no ".", ".." or symbolic link path elements.
13217 This function returns a string, or NULL on error. The caller must free
13219 the returned string after use.
13220 (Added in 1.0.66)
13222 guestfs_remount
13224 int
13225 guestfs_remount (guestfs_h *g,
13226 const char *mountpoint,
13227 ...);
13228 You may supply a list of optional arguments to this call. Use zero or
13230 more of the following pairs of parameters, and terminate the list with
13231 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13232 GUESTFS_REMOUNT_RW, int rw,
13234 This call allows you to change the "rw" (readonly/read-write) flag on
13236 an already mounted filesystem at "mountpoint", converting a readonly
13237 filesystem to be read-write, or vice-versa.
13238 Note that at the moment you must supply the "optional" "rw" parameter.
13240 In future we may allow other flags to be adjusted.
13241 This function returns 0 on success or -1 on error.
13243 (Added in 1.23.2)
13245 guestfs_remount_va
13247 int
13248 guestfs_remount_va (guestfs_h *g,
13249 const char *mountpoint,
13250 va_list args);
13251 This is the "va_list variant" of "guestfs_remount".
13253 See "CALLS WITH OPTIONAL ARGUMENTS".
13255 guestfs_remount_argv
13257 int
13258 guestfs_remount_argv (guestfs_h *g,
13259 const char *mountpoint,
13260 const struct guestfs_remount_argv *optargs);
13261 This is the "argv variant" of "guestfs_remount".
13263 See "CALLS WITH OPTIONAL ARGUMENTS".
13265 guestfs_remove_drive
13267 int
13268 guestfs_remove_drive (guestfs_h *g,
13269 const char *label);
13270 This function is conceptually the opposite of "guestfs_add_drive_opts".
13272 It removes the drive that was previously added with label "label".
13273 Note that in order to remove drives, you have to add them with labels
13275 (see the optional "label" argument to "guestfs_add_drive_opts"). If
13276 you didn't use a label, then they cannot be removed.
13277 You can call this function before or after launching the handle. If
13279 called after launch, if the backend supports it, we try to hot unplug
13280 the drive: see "HOTPLUGGING". The disk must not be in use (eg.
13281 mounted) when you do this. We try to detect if the disk is in use and
13282 stop you from doing this.
13283 This function returns 0 on success or -1 on error.
13285 (Added in 1.19.49)
13287 guestfs_removexattr
13289 int
13290 guestfs_removexattr (guestfs_h *g,
13291 const char *xattr,
13292 const char *path);
13293 This call removes the extended attribute named "xattr" of the file
13295 "path".
13296 See also: "guestfs_lremovexattr", attr(5).
13298 This function returns 0 on success or -1 on error.
13300 This function depends on the feature "linuxxattrs". See also
13302 "guestfs_feature_available".
13303 (Added in 1.0.59)
13305 guestfs_rename
13307 int
13308 guestfs_rename (guestfs_h *g,
13309 const char *oldpath,
13310 const char *newpath);
13311 Rename a file to a new place on the same filesystem. This is the same
13313 as the Linux rename(2) system call. In most cases you are better to
13314 use "guestfs_mv" instead.
13315 This function returns 0 on success or -1 on error.
13317 (Added in 1.21.5)
13319 guestfs_resize2fs
13321 int
13322 guestfs_resize2fs (guestfs_h *g,
13323 const char *device);
13324 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13326 underlying device.
13327 See also "RESIZE2FS ERRORS".
13329 This function returns 0 on success or -1 on error.
13331 (Added in 1.0.27)
13333 guestfs_resize2fs_M
13335 int
13336 guestfs_resize2fs_M (guestfs_h *g,
13337 const char *device);
13338 This command is the same as "guestfs_resize2fs", but the filesystem is
13340 resized to its minimum size. This works like the -M option to the
13341 resize2fs(8) command.
13342 To get the resulting size of the filesystem you should call
13344 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13345 These two numbers, multiplied together, give the resulting size of the
13346 minimal filesystem in bytes.
13347 See also "RESIZE2FS ERRORS".
13349 This function returns 0 on success or -1 on error.
13351 (Added in 1.9.4)
13353 guestfs_resize2fs_size
13355 int
13356 guestfs_resize2fs_size (guestfs_h *g,
13357 const char *device,
13358 int64_t size);
13359 This command is the same as "guestfs_resize2fs" except that it allows
13361 you to specify the new size (in bytes) explicitly.
13362 See also "RESIZE2FS ERRORS".
13364 This function returns 0 on success or -1 on error.
13366 (Added in 1.3.14)
13368 guestfs_rm
13370 int
13371 guestfs_rm (guestfs_h *g,
13372 const char *path);
13373 Remove the single file "path".
13375 This function returns 0 on success or -1 on error.
13377 (Added in 0.8)
13379 guestfs_rm_f
13381 int
13382 guestfs_rm_f (guestfs_h *g,
13383 const char *path);
13384 Remove the file "path".
13386 If the file doesn't exist, that error is ignored. (Other errors, eg.
13388 I/O errors or bad paths, are not ignored)
13389 This call cannot remove directories. Use "guestfs_rmdir" to remove an
13391 empty directory, or "guestfs_rm_rf" to remove directories recursively.
13392 This function returns 0 on success or -1 on error.
13394 (Added in 1.19.42)
13396 guestfs_rm_rf
13398 int
13399 guestfs_rm_rf (guestfs_h *g,
13400 const char *path);
13401 Remove the file or directory "path", recursively removing the contents
13403 if its a directory. This is like the "rm -rf" shell command.
13404 This function returns 0 on success or -1 on error.
13406 (Added in 0.8)
13408 guestfs_rmdir
13410 int
13411 guestfs_rmdir (guestfs_h *g,
13412 const char *path);
13413 Remove the single directory "path".
13415 This function returns 0 on success or -1 on error.
13417 (Added in 0.8)
13419 guestfs_rmmountpoint
13421 int
13422 guestfs_rmmountpoint (guestfs_h *g,
13423 const char *exemptpath);
13424 This call removes a mountpoint that was previously created with
13426 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13427 This function returns 0 on success or -1 on error.
13429 (Added in 1.0.62)
13431 guestfs_rsync
13433 int
13434 guestfs_rsync (guestfs_h *g,
13435 const char *src,
13436 const char *dest,
13437 ...);
13438 You may supply a list of optional arguments to this call. Use zero or
13440 more of the following pairs of parameters, and terminate the list with
13441 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13442 GUESTFS_RSYNC_ARCHIVE, int archive,
13444 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13445 This call may be used to copy or synchronize two directories under the
13447 same libguestfs handle. This uses the rsync(1) program which uses a
13448 fast algorithm that avoids copying files unnecessarily.
13449 "src" and "dest" are the source and destination directories. Files are
13451 copied from "src" to "dest".
13452 The optional arguments are:
13454 "archive"
13456 Turns on archive mode. This is the same as passing the --archive
13457 flag to "rsync".
13458 "deletedest"
13460 Delete files at the destination that do not exist at the source.
13461 This function returns 0 on success or -1 on error.
13463 This function depends on the feature "rsync". See also
13465 "guestfs_feature_available".
13466 (Added in 1.19.29)
13468 guestfs_rsync_va
13470 int
13471 guestfs_rsync_va (guestfs_h *g,
13472 const char *src,
13473 const char *dest,
13474 va_list args);
13475 This is the "va_list variant" of "guestfs_rsync".
13477 See "CALLS WITH OPTIONAL ARGUMENTS".
13479 guestfs_rsync_argv
13481 int
13482 guestfs_rsync_argv (guestfs_h *g,
13483 const char *src,
13484 const char *dest,
13485 const struct guestfs_rsync_argv *optargs);
13486 This is the "argv variant" of "guestfs_rsync".
13488 See "CALLS WITH OPTIONAL ARGUMENTS".
13490 guestfs_rsync_in
13492 int
13493 guestfs_rsync_in (guestfs_h *g,
13494 const char *remote,
13495 const char *dest,
13496 ...);
13497 You may supply a list of optional arguments to this call. Use zero or
13499 more of the following pairs of parameters, and terminate the list with
13500 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13501 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13503 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13504 This call may be used to copy or synchronize the filesystem on the host
13506 or on a remote computer with the filesystem within libguestfs. This
13507 uses the rsync(1) program which uses a fast algorithm that avoids
13508 copying files unnecessarily.
13509 This call only works if the network is enabled. See
13511 "guestfs_set_network" or the --network option to various tools like
13512 guestfish(1).
13513 Files are copied from the remote server and directory specified by
13515 "remote" to the destination directory "dest".
13516 The format of the remote server string is defined by rsync(1). Note
13518 that there is no way to supply a password or passphrase so the target
13519 must be set up not to require one.
13520 The optional arguments are the same as those of "guestfs_rsync".
13522 This function returns 0 on success or -1 on error.
13524 This function depends on the feature "rsync". See also
13526 "guestfs_feature_available".
13527 (Added in 1.19.29)
13529 guestfs_rsync_in_va
13531 int
13532 guestfs_rsync_in_va (guestfs_h *g,
13533 const char *remote,
13534 const char *dest,
13535 va_list args);
13536 This is the "va_list variant" of "guestfs_rsync_in".
13538 See "CALLS WITH OPTIONAL ARGUMENTS".
13540 guestfs_rsync_in_argv
13542 int
13543 guestfs_rsync_in_argv (guestfs_h *g,
13544 const char *remote,
13545 const char *dest,
13546 const struct guestfs_rsync_in_argv *optargs);
13547 This is the "argv variant" of "guestfs_rsync_in".
13549 See "CALLS WITH OPTIONAL ARGUMENTS".
13551 guestfs_rsync_out
13553 int
13554 guestfs_rsync_out (guestfs_h *g,
13555 const char *src,
13556 const char *remote,
13557 ...);
13558 You may supply a list of optional arguments to this call. Use zero or
13560 more of the following pairs of parameters, and terminate the list with
13561 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13562 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13564 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13565 This call may be used to copy or synchronize the filesystem within
13567 libguestfs with a filesystem on the host or on a remote computer. This
13568 uses the rsync(1) program which uses a fast algorithm that avoids
13569 copying files unnecessarily.
13570 This call only works if the network is enabled. See
13572 "guestfs_set_network" or the --network option to various tools like
13573 guestfish(1).
13574 Files are copied from the source directory "src" to the remote server
13576 and directory specified by "remote".
13577 The format of the remote server string is defined by rsync(1). Note
13579 that there is no way to supply a password or passphrase so the target
13580 must be set up not to require one.
13581 The optional arguments are the same as those of "guestfs_rsync".
13583 Globbing does not happen on the "src" parameter. In programs which use
13585 the API directly you have to expand wildcards yourself (see
13586 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13587 (see "glob" in guestfish(1)), for example:
13588 ><fs> glob rsync-out /* rsync://remote/
13590 This function returns 0 on success or -1 on error.
13592 This function depends on the feature "rsync". See also
13594 "guestfs_feature_available".
13595 (Added in 1.19.29)
13597 guestfs_rsync_out_va
13599 int
13600 guestfs_rsync_out_va (guestfs_h *g,
13601 const char *src,
13602 const char *remote,
13603 va_list args);
13604 This is the "va_list variant" of "guestfs_rsync_out".
13606 See "CALLS WITH OPTIONAL ARGUMENTS".
13608 guestfs_rsync_out_argv
13610 int
13611 guestfs_rsync_out_argv (guestfs_h *g,
13612 const char *src,
13613 const char *remote,
13614 const struct guestfs_rsync_out_argv *optargs);
13615 This is the "argv variant" of "guestfs_rsync_out".
13617 See "CALLS WITH OPTIONAL ARGUMENTS".
13619 guestfs_scrub_device
13621 int
13622 guestfs_scrub_device (guestfs_h *g,
13623 const char *device);
13624 This command writes patterns over "device" to make data retrieval more
13626 difficult.
13627 It is an interface to the scrub(1) program. See that manual page for
13629 more details.
13630 This function returns 0 on success or -1 on error.
13632 This function depends on the feature "scrub". See also
13634 "guestfs_feature_available".
13635 (Added in 1.0.52)
13637 guestfs_scrub_file
13639 int
13640 guestfs_scrub_file (guestfs_h *g,
13641 const char *file);
13642 This command writes patterns over a file to make data retrieval more
13644 difficult.
13645 The file is removed after scrubbing.
13647 It is an interface to the scrub(1) program. See that manual page for
13649 more details.
13650 This function returns 0 on success or -1 on error.
13652 This function depends on the feature "scrub". See also
13654 "guestfs_feature_available".
13655 (Added in 1.0.52)
13657 guestfs_scrub_freespace
13659 int
13660 guestfs_scrub_freespace (guestfs_h *g,
13661 const char *dir);
13662 This command creates the directory "dir" and then fills it with files
13664 until the filesystem is full, and scrubs the files as for
13665 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13666 free space on the partition containing "dir".
13667 It is an interface to the scrub(1) program. See that manual page for
13669 more details.
13670 This function returns 0 on success or -1 on error.
13672 This function depends on the feature "scrub". See also
13674 "guestfs_feature_available".
13675 (Added in 1.0.52)
13677 guestfs_selinux_relabel
13679 int
13680 guestfs_selinux_relabel (guestfs_h *g,
13681 const char *specfile,
13682 const char *path,
13683 ...);
13684 You may supply a list of optional arguments to this call. Use zero or
13686 more of the following pairs of parameters, and terminate the list with
13687 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13688 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13690 SELinux relabel parts of the filesystem.
13692 The "specfile" parameter controls the policy spec file used. You have
13694 to parse "/etc/selinux/config" to find the correct SELinux policy and
13695 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13696 "/contexts/files/file_contexts".
13697 The required "path" parameter is the top level directory where
13699 relabelling starts. Normally you should pass "path" as "/" to relabel
13700 the whole guest filesystem.
13701 The optional "force" boolean controls whether the context is reset for
13703 customizable files, and also whether the user, role and range parts of
13704 the file context is changed.
13705 This function returns 0 on success or -1 on error.
13707 This function depends on the feature "selinuxrelabel". See also
13709 "guestfs_feature_available".
13710 (Added in 1.33.43)
13712 guestfs_selinux_relabel_va
13714 int
13715 guestfs_selinux_relabel_va (guestfs_h *g,
13716 const char *specfile,
13717 const char *path,
13718 va_list args);
13719 This is the "va_list variant" of "guestfs_selinux_relabel".
13721 See "CALLS WITH OPTIONAL ARGUMENTS".
13723 guestfs_selinux_relabel_argv
13725 int
13726 guestfs_selinux_relabel_argv (guestfs_h *g,
13727 const char *specfile,
13728 const char *path,
13729 const struct guestfs_selinux_relabel_argv *optargs);
13730 This is the "argv variant" of "guestfs_selinux_relabel".
13732 See "CALLS WITH OPTIONAL ARGUMENTS".
13734 guestfs_set_append
13736 int
13737 guestfs_set_append (guestfs_h *g,
13738 const char *append);
13739 This function is used to add additional options to the libguestfs
13741 appliance kernel command line.
13742 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13744 environment variable.
13745 Setting "append" to "NULL" means no additional options are passed
13747 (libguestfs always adds a few of its own).
13748 This function returns 0 on success or -1 on error.
13750 (Added in 1.0.26)
13752 guestfs_set_attach_method
13754 int
13755 guestfs_set_attach_method (guestfs_h *g,
13756 const char *backend);
13757 This function is deprecated. In new code, use the
13759 "guestfs_set_backend" call instead.
13760 Deprecated functions will not be removed from the API, but the fact
13762 that they are deprecated indicates that there are problems with correct
13763 use of these functions.
13764 Set the method that libguestfs uses to connect to the backend guestfsd
13766 daemon.
13767 See "BACKEND".
13769 This function returns 0 on success or -1 on error.
13771 (Added in 1.9.8)
13773 guestfs_set_autosync
13775 int
13776 guestfs_set_autosync (guestfs_h *g,
13777 int autosync);
13778 If "autosync" is true, this enables autosync. Libguestfs will make a
13780 best effort attempt to make filesystems consistent and synchronized
13781 when the handle is closed (also if the program exits without closing
13782 handles).
13783 This is enabled by default (since libguestfs 1.5.24, previously it was
13785 disabled by default).
13786 This function returns 0 on success or -1 on error.
13788 (Added in 0.3)
13790 guestfs_set_backend
13792 int
13793 guestfs_set_backend (guestfs_h *g,
13794 const char *backend);
13795 Set the method that libguestfs uses to connect to the backend guestfsd
13797 daemon.
13798 This handle property was previously called the "attach method".
13800 See "BACKEND".
13802 This function returns 0 on success or -1 on error.
13804 (Added in 1.21.26)
13806 guestfs_set_backend_setting
13808 int
13809 guestfs_set_backend_setting (guestfs_h *g,
13810 const char *name,
13811 const char *val);
13812 Append "name=value" to the backend settings string list. However if a
13814 string already exists matching "name" or beginning with "name=", then
13815 that setting is replaced.
13816 See "BACKEND", "BACKEND SETTINGS".
13818 This function returns 0 on success or -1 on error.
13820 (Added in 1.27.2)
13822 guestfs_set_backend_settings
13824 int
13825 guestfs_set_backend_settings (guestfs_h *g,
13826 char *const *settings);
13827 Set a list of zero or more settings which are passed through to the
13829 current backend. Each setting is a string which is interpreted in a
13830 backend-specific way, or ignored if not understood by the backend.
13831 The default value is an empty list, unless the environment variable
13833 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13834 This environment variable contains a colon-separated list of settings.
13835 This call replaces all backend settings. If you want to replace a
13837 single backend setting, see "guestfs_set_backend_setting". If you want
13838 to clear a single backend setting, see "guestfs_clear_backend_setting".
13839 See "BACKEND", "BACKEND SETTINGS".
13841 This function returns 0 on success or -1 on error.
13843 (Added in 1.25.24)
13845 guestfs_set_cachedir
13847 int
13848 guestfs_set_cachedir (guestfs_h *g,
13849 const char *cachedir);
13850 Set the directory used by the handle to store the appliance cache, when
13852 using a supermin appliance. The appliance is cached and shared between
13853 all handles which have the same effective user ID.
13854 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13856 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13857 default. Else if "TMPDIR" is set, then that is the default. Else
13858 /var/tmp is the default.
13859 This function returns 0 on success or -1 on error.
13861 (Added in 1.19.58)
13863 guestfs_set_direct
13865 int
13866 guestfs_set_direct (guestfs_h *g,
13867 int direct);
13868 This function is deprecated. In new code, use the
13870 "guestfs_internal_get_console_socket" call instead.
13871 Deprecated functions will not be removed from the API, but the fact
13873 that they are deprecated indicates that there are problems with correct
13874 use of these functions.
13875 If the direct appliance mode flag is enabled, then stdin and stdout are
13877 passed directly through to the appliance once it is launched.
13878 One consequence of this is that log messages aren't caught by the
13880 library and handled by "guestfs_set_log_message_callback", but go
13881 straight to stdout.
13882 You probably don't want to use this unless you know what you are doing.
13884 The default is disabled.
13886 This function returns 0 on success or -1 on error.
13888 (Added in 1.0.72)
13890 guestfs_set_e2attrs
13892 int
13893 guestfs_set_e2attrs (guestfs_h *g,
13894 const char *file,
13895 const char *attrs,
13896 ...);
13897 You may supply a list of optional arguments to this call. Use zero or
13899 more of the following pairs of parameters, and terminate the list with
13900 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13901 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13903 This sets or clears the file attributes "attrs" associated with the
13905 inode file.
13906 "attrs" is a string of characters representing file attributes. See
13908 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13909 attributes can be changed.
13910 If optional boolean "clear" is not present or false, then the "attrs"
13912 listed are set in the inode.
13913 If "clear" is true, then the "attrs" listed are cleared in the inode.
13915 In both cases, other attributes not present in the "attrs" string are
13917 left unchanged.
13918 These attributes are only present when the file is located on an
13920 ext2/3/4 filesystem. Using this call on other filesystem types will
13921 result in an error.
13922 This function returns 0 on success or -1 on error.
13924 (Added in 1.17.31)
13926 guestfs_set_e2attrs_va
13928 int
13929 guestfs_set_e2attrs_va (guestfs_h *g,
13930 const char *file,
13931 const char *attrs,
13932 va_list args);
13933 This is the "va_list variant" of "guestfs_set_e2attrs".
13935 See "CALLS WITH OPTIONAL ARGUMENTS".
13937 guestfs_set_e2attrs_argv
13939 int
13940 guestfs_set_e2attrs_argv (guestfs_h *g,
13941 const char *file,
13942 const char *attrs,
13943 const struct guestfs_set_e2attrs_argv *optargs);
13944 This is the "argv variant" of "guestfs_set_e2attrs".
13946 See "CALLS WITH OPTIONAL ARGUMENTS".
13948 guestfs_set_e2generation
13950 int
13951 guestfs_set_e2generation (guestfs_h *g,
13952 const char *file,
13953 int64_t generation);
13954 This sets the ext2 file generation of a file.
13956 See "guestfs_get_e2generation".
13958 This function returns 0 on success or -1 on error.
13960 (Added in 1.17.31)
13962 guestfs_set_e2label
13964 int
13965 guestfs_set_e2label (guestfs_h *g,
13966 const char *device,
13967 const char *label);
13968 This function is deprecated. In new code, use the "guestfs_set_label"
13970 call instead.
13971 Deprecated functions will not be removed from the API, but the fact
13973 that they are deprecated indicates that there are problems with correct
13974 use of these functions.
13975 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13977 to "label". Filesystem labels are limited to 16 characters.
13978 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13980 return the existing label on a filesystem.
13981 This function returns 0 on success or -1 on error.
13983 (Added in 1.0.15)
13985 guestfs_set_e2uuid
13987 int
13988 guestfs_set_e2uuid (guestfs_h *g,
13989 const char *device,
13990 const char *uuid);
13991 This function is deprecated. In new code, use the "guestfs_set_uuid"
13993 call instead.
13994 Deprecated functions will not be removed from the API, but the fact
13996 that they are deprecated indicates that there are problems with correct
13997 use of these functions.
13998 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
14000 "uuid". The format of the UUID and alternatives such as "clear",
14001 "random" and "time" are described in the tune2fs(8) manpage.
14002 You can use "guestfs_vfs_uuid" to return the existing UUID of a
14004 filesystem.
14005 This function returns 0 on success or -1 on error.
14007 (Added in 1.0.15)
14009 guestfs_set_hv
14011 int
14012 guestfs_set_hv (guestfs_h *g,
14013 const char *hv);
14014 Set the hypervisor binary that we will use. The hypervisor depends on
14016 the backend, but is usually the location of the qemu/KVM hypervisor.
14017 For the uml backend, it is the location of the "linux" or "vmlinux"
14018 binary.
14019 The default is chosen when the library was compiled by the configure
14021 script.
14022 You can also override this by setting the "LIBGUESTFS_HV" environment
14024 variable.
14025 Note that you should call this function as early as possible after
14027 creating the handle. This is because some pre-launch operations depend
14028 on testing qemu features (by running "qemu -help"). If the qemu binary
14029 changes, we don't retest features, and so you might see inconsistent
14030 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14031 all since that picks the qemu binary at the same time as the handle is
14032 created.
14033 This function returns 0 on success or -1 on error.
14035 (Added in 1.23.17)
14037 guestfs_set_identifier
14039 int
14040 guestfs_set_identifier (guestfs_h *g,
14041 const char *identifier);
14042 This is an informative string which the caller may optionally set in
14044 the handle. It is printed in various places, allowing the current
14045 handle to be identified in debugging output.
14046 One important place is when tracing is enabled. If the identifier
14048 string is not an empty string, then trace messages change from this:
14049 libguestfs: trace: get_tmpdir
14051 libguestfs: trace: get_tmpdir = "/tmp"
14052 to this:
14054 libguestfs: trace: ID: get_tmpdir
14056 libguestfs: trace: ID: get_tmpdir = "/tmp"
14057 where "ID" is the identifier string set by this call.
14059 The identifier must only contain alphanumeric ASCII characters,
14061 underscore and minus sign. The default is the empty string.
14062 See also "guestfs_set_program", "guestfs_set_trace",
14064 "guestfs_get_identifier".
14065 This function returns 0 on success or -1 on error.
14067 (Added in 1.31.14)
14069 guestfs_set_label
14071 int
14072 guestfs_set_label (guestfs_h *g,
14073 const char *mountable,
14074 const char *label);
14075 Set the filesystem label on "mountable" to "label".
14077 Only some filesystem types support labels, and libguestfs supports
14079 setting labels on only a subset of these.
14080 ext2, ext3, ext4
14082 Labels are limited to 16 bytes.
14083 NTFS
14085 Labels are limited to 128 unicode characters.
14086 XFS The label is limited to 12 bytes. The filesystem must not be
14088 mounted when trying to set the label.
14089 btrfs
14091 The label is limited to 255 bytes and some characters are not
14092 allowed. Setting the label on a btrfs subvolume will set the label
14093 on its parent filesystem. The filesystem must not be mounted when
14094 trying to set the label.
14095 fat The label is limited to 11 bytes.
14097 swap
14099 The label is limited to 16 bytes.
14100 If there is no support for changing the label for the type of the
14102 specified filesystem, set_label will fail and set errno as ENOTSUP.
14103 To read the label on a filesystem, call "guestfs_vfs_label".
14105 This function returns 0 on success or -1 on error.
14107 (Added in 1.17.9)
14109 guestfs_set_libvirt_requested_credential
14111 int
14112 guestfs_set_libvirt_requested_credential (guestfs_h *g,
14113 int index,
14114 const char *cred,
14115 size_t cred_size);
14116 After requesting the "index"'th credential from the user, call this
14118 function to pass the answer back to libvirt.
14119 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14121 This function returns 0 on success or -1 on error.
14123 (Added in 1.19.52)
14125 guestfs_set_libvirt_supported_credentials
14127 int
14128 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
14129 char *const *creds);
14130 Call this function before setting an event handler for
14132 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
14133 that the program knows how to process.
14134 The "creds" list must be a non-empty list of strings. Possible strings
14136 are:
14137 "username"
14139 "authname"
14140 "language"
14141 "cnonce"
14142 "passphrase"
14143 "echoprompt"
14144 "noechoprompt"
14145 "realm"
14146 "external"
14147 See libvirt documentation for the meaning of these credential types.
14149 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14151 This function returns 0 on success or -1 on error.
14153 (Added in 1.19.52)
14155 guestfs_set_memsize
14157 int
14158 guestfs_set_memsize (guestfs_h *g,
14159 int memsize);
14160 This sets the memory size in megabytes allocated to the hypervisor.
14162 This only has any effect if called before "guestfs_launch".
14163 You can also change this by setting the environment variable
14165 "LIBGUESTFS_MEMSIZE" before the handle is created.
14166 For more information on the architecture of libguestfs, see guestfs(3).
14168 This function returns 0 on success or -1 on error.
14170 (Added in 1.0.55)
14172 guestfs_set_network
14174 int
14175 guestfs_set_network (guestfs_h *g,
14176 int network);
14177 If "network" is true, then the network is enabled in the libguestfs
14179 appliance. The default is false.
14180 This affects whether commands are able to access the network (see
14182 "RUNNING COMMANDS").
14183 You must call this before calling "guestfs_launch", otherwise it has no
14185 effect.
14186 This function returns 0 on success or -1 on error.
14188 (Added in 1.5.4)
14190 guestfs_set_path
14192 int
14193 guestfs_set_path (guestfs_h *g,
14194 const char *searchpath);
14195 Set the path that libguestfs searches for kernel and initrd.img.
14197 The default is "$libdir/guestfs" unless overridden by setting
14199 "LIBGUESTFS_PATH" environment variable.
14200 Setting "path" to "NULL" restores the default path.
14202 This function returns 0 on success or -1 on error.
14204 (Added in 0.3)
14206 guestfs_set_pgroup
14208 int
14209 guestfs_set_pgroup (guestfs_h *g,
14210 int pgroup);
14211 If "pgroup" is true, child processes are placed into their own process
14213 group.
14214 The practical upshot of this is that signals like "SIGINT" (from users
14216 pressing "^C") won't be received by the child process.
14217 The default for this flag is false, because usually you want "^C" to
14219 kill the subprocess. Guestfish sets this flag to true when used
14220 interactively, so that "^C" can cancel long-running commands gracefully
14221 (see "guestfs_user_cancel").
14222 This function returns 0 on success or -1 on error.
14224 (Added in 1.11.18)
14226 guestfs_set_program
14228 int
14229 guestfs_set_program (guestfs_h *g,
14230 const char *program);
14231 Set the program name. This is an informative string which the main
14233 program may optionally set in the handle.
14234 When the handle is created, the program name in the handle is set to
14236 the basename from "argv[0]". The program name can never be "NULL".
14237 This function returns 0 on success or -1 on error.
14239 (Added in 1.21.29)
14241 guestfs_set_qemu
14243 int
14244 guestfs_set_qemu (guestfs_h *g,
14245 const char *hv);
14246 This function is deprecated. In new code, use the "guestfs_set_hv"
14248 call instead.
14249 Deprecated functions will not be removed from the API, but the fact
14251 that they are deprecated indicates that there are problems with correct
14252 use of these functions.
14253 Set the hypervisor binary (usually qemu) that we will use.
14255 The default is chosen when the library was compiled by the configure
14257 script.
14258 You can also override this by setting the "LIBGUESTFS_HV" environment
14260 variable.
14261 Setting "hv" to "NULL" restores the default qemu binary.
14263 Note that you should call this function as early as possible after
14265 creating the handle. This is because some pre-launch operations depend
14266 on testing qemu features (by running "qemu -help"). If the qemu binary
14267 changes, we don't retest features, and so you might see inconsistent
14268 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14269 all since that picks the qemu binary at the same time as the handle is
14270 created.
14271 This function returns 0 on success or -1 on error.
14273 (Added in 1.0.6)
14275 guestfs_set_recovery_proc
14277 int
14278 guestfs_set_recovery_proc (guestfs_h *g,
14279 int recoveryproc);
14280 If this is called with the parameter "false" then "guestfs_launch" does
14282 not create a recovery process. The purpose of the recovery process is
14283 to stop runaway hypervisor processes in the case where the main program
14284 aborts abruptly.
14285 This only has any effect if called before "guestfs_launch", and the
14287 default is true.
14288 About the only time when you would want to disable this is if the main
14290 process will fork itself into the background ("daemonize" itself). In
14291 this case the recovery process thinks that the main program has
14292 disappeared and so kills the hypervisor, which is not very helpful.
14293 This function returns 0 on success or -1 on error.
14295 (Added in 1.0.77)
14297 guestfs_set_selinux
14299 int
14300 guestfs_set_selinux (guestfs_h *g,
14301 int selinux);
14302 This function is deprecated. In new code, use the
14304 "guestfs_selinux_relabel" call instead.
14305 Deprecated functions will not be removed from the API, but the fact
14307 that they are deprecated indicates that there are problems with correct
14308 use of these functions.
14309 This sets the selinux flag that is passed to the appliance at boot
14311 time. The default is "selinux=0" (disabled).
14312 Note that if SELinux is enabled, it is always in Permissive mode
14314 ("enforcing=0").
14315 For more information on the architecture of libguestfs, see guestfs(3).
14317 This function returns 0 on success or -1 on error.
14319 (Added in 1.0.67)
14321 guestfs_set_smp
14323 int
14324 guestfs_set_smp (guestfs_h *g,
14325 int smp);
14326 Change the number of virtual CPUs assigned to the appliance. The
14328 default is 1. Increasing this may improve performance, though often it
14329 has no effect.
14330 This function must be called before "guestfs_launch".
14332 This function returns 0 on success or -1 on error.
14334 (Added in 1.13.15)
14336 guestfs_set_tmpdir
14338 int
14339 guestfs_set_tmpdir (guestfs_h *g,
14340 const char *tmpdir);
14341 Set the directory used by the handle to store temporary files.
14343 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14345 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14346 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
14347 default.
14348 This function returns 0 on success or -1 on error.
14350 (Added in 1.19.58)
14352 guestfs_set_trace
14354 int
14355 guestfs_set_trace (guestfs_h *g,
14356 int trace);
14357 If the command trace flag is set to 1, then libguestfs calls,
14359 parameters and return values are traced.
14360 If you want to trace C API calls into libguestfs (and other libraries)
14362 then possibly a better way is to use the external ltrace(1) command.
14363 Command traces are disabled unless the environment variable
14365 "LIBGUESTFS_TRACE" is defined and set to 1.
14366 Trace messages are normally sent to "stderr", unless you register a
14368 callback to send them somewhere else (see
14369 "guestfs_set_event_callback").
14370 This function returns 0 on success or -1 on error.
14372 (Added in 1.0.69)
14374 guestfs_set_uuid
14376 int
14377 guestfs_set_uuid (guestfs_h *g,
14378 const char *device,
14379 const char *uuid);
14380 Set the filesystem UUID on "device" to "uuid". If this fails and the
14382 errno is ENOTSUP, means that there is no support for changing the UUID
14383 for the type of the specified filesystem.
14384 Only some filesystem types support setting UUIDs.
14386 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14388 This function returns 0 on success or -1 on error.
14390 (Added in 1.23.10)
14392 guestfs_set_uuid_random
14394 int
14395 guestfs_set_uuid_random (guestfs_h *g,
14396 const char *device);
14397 Set the filesystem UUID on "device" to a random UUID. If this fails
14399 and the errno is ENOTSUP, means that there is no support for changing
14400 the UUID for the type of the specified filesystem.
14401 Only some filesystem types support setting UUIDs.
14403 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14405 This function returns 0 on success or -1 on error.
14407 (Added in 1.29.50)
14409 guestfs_set_verbose
14411 int
14412 guestfs_set_verbose (guestfs_h *g,
14413 int verbose);
14414 If "verbose" is true, this turns on verbose messages.
14416 Verbose messages are disabled unless the environment variable
14418 "LIBGUESTFS_DEBUG" is defined and set to 1.
14419 Verbose messages are normally sent to "stderr", unless you register a
14421 callback to send them somewhere else (see
14422 "guestfs_set_event_callback").
14423 This function returns 0 on success or -1 on error.
14425 (Added in 0.3)
14427 guestfs_setcon
14429 int
14430 guestfs_setcon (guestfs_h *g,
14431 const char *context);
14432 This function is deprecated. In new code, use the
14434 "guestfs_selinux_relabel" call instead.
14435 Deprecated functions will not be removed from the API, but the fact
14437 that they are deprecated indicates that there are problems with correct
14438 use of these functions.
14439 This sets the SELinux security context of the daemon to the string
14441 "context".
14442 See the documentation about SELINUX in guestfs(3).
14444 This function returns 0 on success or -1 on error.
14446 This function depends on the feature "selinux". See also
14448 "guestfs_feature_available".
14449 (Added in 1.0.67)
14451 guestfs_setxattr
14453 int
14454 guestfs_setxattr (guestfs_h *g,
14455 const char *xattr,
14456 const char *val,
14457 int vallen,
14458 const char *path);
14459 This call sets the extended attribute named "xattr" of the file "path"
14461 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14462 data.
14463 See also: "guestfs_lsetxattr", attr(5).
14465 This function returns 0 on success or -1 on error.
14467 This function depends on the feature "linuxxattrs". See also
14469 "guestfs_feature_available".
14470 (Added in 1.0.59)
14472 guestfs_sfdisk
14474 int
14475 guestfs_sfdisk (guestfs_h *g,
14476 const char *device,
14477 int cyls,
14478 int heads,
14479 int sectors,
14480 char *const *lines);
14481 This function is deprecated. In new code, use the "guestfs_part_add"
14483 call instead.
14484 Deprecated functions will not be removed from the API, but the fact
14486 that they are deprecated indicates that there are problems with correct
14487 use of these functions.
14488 This is a direct interface to the sfdisk(8) program for creating
14490 partitions on block devices.
14491 "device" should be a block device, for example /dev/sda.
14493 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14495 sectors on the device, which are passed directly to sfdisk(8) as the
14496 -C, -H and -S parameters. If you pass 0 for any of these, then the
14497 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14498 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
14499 (or rather, the kernel) cannot work out the right geometry and you will
14500 need to tell it.
14501 "lines" is a list of lines that we feed to sfdisk(8). For more
14503 information refer to the sfdisk(8) manpage.
14504 To create a single partition occupying the whole disk, you would pass
14506 "lines" as a single element list, when the single element being the
14507 string "," (comma).
14508 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14510 This function returns 0 on success or -1 on error.
14512 (Added in 0.8)
14514 guestfs_sfdiskM
14516 int
14517 guestfs_sfdiskM (guestfs_h *g,
14518 const char *device,
14519 char *const *lines);
14520 This function is deprecated. In new code, use the "guestfs_part_add"
14522 call instead.
14523 Deprecated functions will not be removed from the API, but the fact
14525 that they are deprecated indicates that there are problems with correct
14526 use of these functions.
14527 This is a simplified interface to the "guestfs_sfdisk" command, where
14529 partition sizes are specified in megabytes only (rounded to the nearest
14530 cylinder) and you don't need to specify the cyls, heads and sectors
14531 parameters which were rarely if ever used anyway.
14532 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14534 "guestfs_part_disk"
14535 This function returns 0 on success or -1 on error.
14537 (Added in 1.0.55)
14539 guestfs_sfdisk_N
14541 int
14542 guestfs_sfdisk_N (guestfs_h *g,
14543 const char *device,
14544 int partnum,
14545 int cyls,
14546 int heads,
14547 int sectors,
14548 const char *line);
14549 This function is deprecated. In new code, use the "guestfs_part_add"
14551 call instead.
14552 Deprecated functions will not be removed from the API, but the fact
14554 that they are deprecated indicates that there are problems with correct
14555 use of these functions.
14556 This runs sfdisk(8) option to modify just the single partition "n"
14558 (note: "n" counts from 1).
14559 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14561 for the cyls/heads/sectors parameters.
14562 See also: "guestfs_part_add"
14564 This function returns 0 on success or -1 on error.
14566 (Added in 1.0.26)
14568 guestfs_sfdisk_disk_geometry
14570 char *
14571 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14572 const char *device);
14573 This displays the disk geometry of "device" read from the partition
14575 table. Especially in the case where the underlying block device has
14576 been resized, this can be different from the kernel’s idea of the
14577 geometry (see "guestfs_sfdisk_kernel_geometry").
14578 The result is in human-readable format, and not designed to be parsed.
14580 This function returns a string, or NULL on error. The caller must free
14582 the returned string after use.
14583 (Added in 1.0.26)
14585 guestfs_sfdisk_kernel_geometry
14587 char *
14588 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14589 const char *device);
14590 This displays the kernel’s idea of the geometry of "device".
14592 The result is in human-readable format, and not designed to be parsed.
14594 This function returns a string, or NULL on error. The caller must free
14596 the returned string after use.
14597 (Added in 1.0.26)
14599 guestfs_sfdisk_l
14601 char *
14602 guestfs_sfdisk_l (guestfs_h *g,
14603 const char *device);
14604 This function is deprecated. In new code, use the "guestfs_part_list"
14606 call instead.
14607 Deprecated functions will not be removed from the API, but the fact
14609 that they are deprecated indicates that there are problems with correct
14610 use of these functions.
14611 This displays the partition table on "device", in the human-readable
14613 output of the sfdisk(8) command. It is not intended to be parsed.
14614 See also: "guestfs_part_list"
14616 This function returns a string, or NULL on error. The caller must free
14618 the returned string after use.
14619 (Added in 1.0.26)
14621 guestfs_sh
14623 char *
14624 guestfs_sh (guestfs_h *g,
14625 const char *command);
14626 This call runs a command from the guest filesystem via the guest’s
14628 /bin/sh.
14629 This is like "guestfs_command", but passes the command to:
14631 /bin/sh -c "command"
14633 Depending on the guest’s shell, this usually results in wildcards being
14635 expanded, shell expressions being interpolated and so on.
14636 All the provisos about "guestfs_command" apply to this call.
14638 This function returns a string, or NULL on error. The caller must free
14640 the returned string after use.
14641 (Added in 1.0.50)
14643 guestfs_sh_lines
14645 char **
14646 guestfs_sh_lines (guestfs_h *g,
14647 const char *command);
14648 This is the same as "guestfs_sh", but splits the result into a list of
14650 lines.
14651 See also: "guestfs_command_lines"
14653 This function returns a NULL-terminated array of strings (like
14655 environ(3)), or NULL if there was an error. The caller must free the
14656 strings and the array after use.
14657 (Added in 1.0.50)
14659 guestfs_shutdown
14661 int
14662 guestfs_shutdown (guestfs_h *g);
14663 This is the opposite of "guestfs_launch". It performs an orderly
14665 shutdown of the backend process(es). If the autosync flag is set
14666 (which is the default) then the disk image is synchronized.
14667 If the subprocess exits with an error then this function will return an
14669 error, which should not be ignored (it may indicate that the disk image
14670 could not be written out properly).
14671 It is safe to call this multiple times. Extra calls are ignored.
14673 This call does not close or free up the handle. You still need to call
14675 "guestfs_close" afterwards.
14676 "guestfs_close" will call this if you don't do it explicitly, but note
14678 that any errors are ignored in that case.
14679 This function returns 0 on success or -1 on error.
14681 (Added in 1.19.16)
14683 guestfs_sleep
14685 int
14686 guestfs_sleep (guestfs_h *g,
14687 int secs);
14688 Sleep for "secs" seconds.
14690 This function returns 0 on success or -1 on error.
14692 (Added in 1.0.41)
14694 guestfs_stat
14696 struct guestfs_stat *
14697 guestfs_stat (guestfs_h *g,
14698 const char *path);
14699 This function is deprecated. In new code, use the "guestfs_statns"
14701 call instead.
14702 Deprecated functions will not be removed from the API, but the fact
14704 that they are deprecated indicates that there are problems with correct
14705 use of these functions.
14706 Returns file information for the given "path".
14708 This is the same as the stat(2) system call.
14710 This function returns a "struct guestfs_stat *", or NULL if there was
14712 an error. The caller must call "guestfs_free_stat" after use.
14713 (Added in 1.9.2)
14715 guestfs_statns
14717 struct guestfs_statns *
14718 guestfs_statns (guestfs_h *g,
14719 const char *path);
14720 Returns file information for the given "path".
14722 This is the same as the stat(2) system call.
14724 This function returns a "struct guestfs_statns *", or NULL if there was
14726 an error. The caller must call "guestfs_free_statns" after use.
14727 (Added in 1.27.53)
14729 guestfs_statvfs
14731 struct guestfs_statvfs *
14732 guestfs_statvfs (guestfs_h *g,
14733 const char *path);
14734 Returns file system statistics for any mounted file system. "path"
14736 should be a file or directory in the mounted file system (typically it
14737 is the mount point itself, but it doesn't need to be).
14738 This is the same as the statvfs(2) system call.
14740 This function returns a "struct guestfs_statvfs *", or NULL if there
14742 was an error. The caller must call "guestfs_free_statvfs" after use.
14743 (Added in 1.9.2)
14745 guestfs_strings
14747 char **
14748 guestfs_strings (guestfs_h *g,
14749 const char *path);
14750 This runs the strings(1) command on a file and returns the list of
14752 printable strings found.
14753 The "strings" command has, in the past, had problems with parsing
14755 untrusted files. These are mitigated in the current version of
14756 libguestfs, but see "CVE-2014-8484".
14757 This function returns a NULL-terminated array of strings (like
14759 environ(3)), or NULL if there was an error. The caller must free the
14760 strings and the array after use.
14761 Because of the message protocol, there is a transfer limit of somewhere
14763 between 2MB and 4MB. See "PROTOCOL LIMITS".
14764 (Added in 1.0.22)
14766 guestfs_strings_e
14768 char **
14769 guestfs_strings_e (guestfs_h *g,
14770 const char *encoding,
14771 const char *path);
14772 This is like the "guestfs_strings" command, but allows you to specify
14774 the encoding of strings that are looked for in the source file "path".
14775 Allowed encodings are:
14777 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14779 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14780 S Single 8-bit-byte characters.
14782 b 16-bit big endian strings such as those encoded in UTF-16BE or
14784 UCS-2BE.
14785 l (lower case letter L)
14787 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14788 for examining binaries in Windows guests.
14789 B 32-bit big endian such as UCS-4BE.
14791 L 32-bit little endian such as UCS-4LE.
14793 The returned strings are transcoded to UTF-8.
14795 The "strings" command has, in the past, had problems with parsing
14797 untrusted files. These are mitigated in the current version of
14798 libguestfs, but see "CVE-2014-8484".
14799 This function returns a NULL-terminated array of strings (like
14801 environ(3)), or NULL if there was an error. The caller must free the
14802 strings and the array after use.
14803 Because of the message protocol, there is a transfer limit of somewhere
14805 between 2MB and 4MB. See "PROTOCOL LIMITS".
14806 (Added in 1.0.22)
14808 guestfs_swapoff_device
14810 int
14811 guestfs_swapoff_device (guestfs_h *g,
14812 const char *device);
14813 This command disables the libguestfs appliance swap device or partition
14815 named "device". See "guestfs_swapon_device".
14816 This function returns 0 on success or -1 on error.
14818 (Added in 1.0.66)
14820 guestfs_swapoff_file
14822 int
14823 guestfs_swapoff_file (guestfs_h *g,
14824 const char *file);
14825 This command disables the libguestfs appliance swap on file.
14827 This function returns 0 on success or -1 on error.
14829 (Added in 1.0.66)
14831 guestfs_swapoff_label
14833 int
14834 guestfs_swapoff_label (guestfs_h *g,
14835 const char *label);
14836 This command disables the libguestfs appliance swap on labeled swap
14838 partition.
14839 This function returns 0 on success or -1 on error.
14841 (Added in 1.0.66)
14843 guestfs_swapoff_uuid
14845 int
14846 guestfs_swapoff_uuid (guestfs_h *g,
14847 const char *uuid);
14848 This command disables the libguestfs appliance swap partition with the
14850 given UUID.
14851 This function returns 0 on success or -1 on error.
14853 This function depends on the feature "linuxfsuuid". See also
14855 "guestfs_feature_available".
14856 (Added in 1.0.66)
14858 guestfs_swapon_device
14860 int
14861 guestfs_swapon_device (guestfs_h *g,
14862 const char *device);
14863 This command enables the libguestfs appliance to use the swap device or
14865 partition named "device". The increased memory is made available for
14866 all commands, for example those run using "guestfs_command" or
14867 "guestfs_sh".
14868 Note that you should not swap to existing guest swap partitions unless
14870 you know what you are doing. They may contain hibernation information,
14871 or other information that the guest doesn't want you to trash. You
14872 also risk leaking information about the host to the guest this way.
14873 Instead, attach a new host device to the guest and swap on that.
14874 This function returns 0 on success or -1 on error.
14876 (Added in 1.0.66)
14878 guestfs_swapon_file
14880 int
14881 guestfs_swapon_file (guestfs_h *g,
14882 const char *file);
14883 This command enables swap to a file. See "guestfs_swapon_device" for
14885 other notes.
14886 This function returns 0 on success or -1 on error.
14888 (Added in 1.0.66)
14890 guestfs_swapon_label
14892 int
14893 guestfs_swapon_label (guestfs_h *g,
14894 const char *label);
14895 This command enables swap to a labeled swap partition. See
14897 "guestfs_swapon_device" for other notes.
14898 This function returns 0 on success or -1 on error.
14900 (Added in 1.0.66)
14902 guestfs_swapon_uuid
14904 int
14905 guestfs_swapon_uuid (guestfs_h *g,
14906 const char *uuid);
14907 This command enables swap to a swap partition with the given UUID. See
14909 "guestfs_swapon_device" for other notes.
14910 This function returns 0 on success or -1 on error.
14912 This function depends on the feature "linuxfsuuid". See also
14914 "guestfs_feature_available".
14915 (Added in 1.0.66)
14917 guestfs_sync
14919 int
14920 guestfs_sync (guestfs_h *g);
14921 This syncs the disk, so that any writes are flushed through to the
14923 underlying disk image.
14924 You should always call this if you have modified a disk image, before
14926 closing the handle.
14927 This function returns 0 on success or -1 on error.
14929 (Added in 0.3)
14931 guestfs_syslinux
14933 int
14934 guestfs_syslinux (guestfs_h *g,
14935 const char *device,
14936 ...);
14937 You may supply a list of optional arguments to this call. Use zero or
14939 more of the following pairs of parameters, and terminate the list with
14940 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14941 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14943 Install the SYSLINUX bootloader on "device".
14945 The device parameter must be either a whole disk formatted as a FAT
14947 filesystem, or a partition formatted as a FAT filesystem. In the
14948 latter case, the partition should be marked as "active"
14949 ("guestfs_part_set_bootable") and a Master Boot Record must be
14950 installed (eg. using "guestfs_pwrite_device") on the first sector of
14951 the whole disk. The SYSLINUX package comes with some suitable Master
14952 Boot Records. See the syslinux(1) man page for further information.
14953 The optional arguments are:
14955 directory
14957 Install SYSLINUX in the named subdirectory, instead of in the root
14958 directory of the FAT filesystem.
14959 Additional configuration can be supplied to SYSLINUX by placing a file
14961 called syslinux.cfg on the FAT filesystem, either in the root
14962 directory, or under directory if that optional argument is being used.
14963 For further information about the contents of this file, see
14964 syslinux(1).
14965 See also "guestfs_extlinux".
14967 This function returns 0 on success or -1 on error.
14969 This function depends on the feature "syslinux". See also
14971 "guestfs_feature_available".
14972 (Added in 1.21.27)
14974 guestfs_syslinux_va
14976 int
14977 guestfs_syslinux_va (guestfs_h *g,
14978 const char *device,
14979 va_list args);
14980 This is the "va_list variant" of "guestfs_syslinux".
14982 See "CALLS WITH OPTIONAL ARGUMENTS".
14984 guestfs_syslinux_argv
14986 int
14987 guestfs_syslinux_argv (guestfs_h *g,
14988 const char *device,
14989 const struct guestfs_syslinux_argv *optargs);
14990 This is the "argv variant" of "guestfs_syslinux".
14992 See "CALLS WITH OPTIONAL ARGUMENTS".
14994 guestfs_tail
14996 char **
14997 guestfs_tail (guestfs_h *g,
14998 const char *path);
14999 This command returns up to the last 10 lines of a file as a list of
15001 strings.
15002 This function returns a NULL-terminated array of strings (like
15004 environ(3)), or NULL if there was an error. The caller must free the
15005 strings and the array after use.
15006 Because of the message protocol, there is a transfer limit of somewhere
15008 between 2MB and 4MB. See "PROTOCOL LIMITS".
15009 (Added in 1.0.54)
15011 guestfs_tail_n
15013 char **
15014 guestfs_tail_n (guestfs_h *g,
15015 int nrlines,
15016 const char *path);
15017 If the parameter "nrlines" is a positive number, this returns the last
15019 "nrlines" lines of the file "path".
15020 If the parameter "nrlines" is a negative number, this returns lines
15022 from the file "path", starting with the "-nrlines"'th line.
15023 If the parameter "nrlines" is zero, this returns an empty list.
15025 This function returns a NULL-terminated array of strings (like
15027 environ(3)), or NULL if there was an error. The caller must free the
15028 strings and the array after use.
15029 Because of the message protocol, there is a transfer limit of somewhere
15031 between 2MB and 4MB. See "PROTOCOL LIMITS".
15032 (Added in 1.0.54)
15034 guestfs_tar_in
15036 int
15037 guestfs_tar_in (guestfs_h *g,
15038 const char *tarfile,
15039 const char *directory);
15040 This function is provided for backwards compatibility with earlier
15042 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
15043 optional arguments.
15044 (Added in 1.0.3)
15046 guestfs_tar_in_opts
15048 int
15049 guestfs_tar_in_opts (guestfs_h *g,
15050 const char *tarfile,
15051 const char *directory,
15052 ...);
15053 You may supply a list of optional arguments to this call. Use zero or
15055 more of the following pairs of parameters, and terminate the list with
15056 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15057 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
15059 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
15060 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
15061 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
15062 This command uploads and unpacks local file "tarfile" into directory.
15064 The optional "compress" flag controls compression. If not given, then
15066 the input should be an uncompressed tar file. Otherwise one of the
15067 following strings may be given to select the compression type of the
15068 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15069 all builds of libguestfs will support all of these compression types).
15070 The other optional arguments are:
15072 "xattrs"
15074 If set to true, extended attributes are restored from the tar file.
15075 "selinux"
15077 If set to true, SELinux contexts are restored from the tar file.
15078 "acls"
15080 If set to true, POSIX ACLs are restored from the tar file.
15081 This function returns 0 on success or -1 on error.
15083 (Added in 1.0.3)
15085 guestfs_tar_in_opts_va
15087 int
15088 guestfs_tar_in_opts_va (guestfs_h *g,
15089 const char *tarfile,
15090 const char *directory,
15091 va_list args);
15092 This is the "va_list variant" of "guestfs_tar_in_opts".
15094 See "CALLS WITH OPTIONAL ARGUMENTS".
15096 guestfs_tar_in_opts_argv
15098 int
15099 guestfs_tar_in_opts_argv (guestfs_h *g,
15100 const char *tarfile,
15101 const char *directory,
15102 const struct guestfs_tar_in_opts_argv *optargs);
15103 This is the "argv variant" of "guestfs_tar_in_opts".
15105 See "CALLS WITH OPTIONAL ARGUMENTS".
15107 guestfs_tar_out
15109 int
15110 guestfs_tar_out (guestfs_h *g,
15111 const char *directory,
15112 const char *tarfile);
15113 This function is provided for backwards compatibility with earlier
15115 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
15116 optional arguments.
15117 (Added in 1.0.3)
15119 guestfs_tar_out_opts
15121 int
15122 guestfs_tar_out_opts (guestfs_h *g,
15123 const char *directory,
15124 const char *tarfile,
15125 ...);
15126 You may supply a list of optional arguments to this call. Use zero or
15128 more of the following pairs of parameters, and terminate the list with
15129 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15130 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
15132 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
15133 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
15134 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
15135 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
15136 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
15137 This command packs the contents of directory and downloads it to local
15139 file "tarfile".
15140 The optional "compress" flag controls compression. If not given, then
15142 the output will be an uncompressed tar file. Otherwise one of the
15143 following strings may be given to select the compression type of the
15144 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15145 all builds of libguestfs will support all of these compression types).
15146 The other optional arguments are:
15148 "excludes"
15150 A list of wildcards. Files are excluded if they match any of the
15151 wildcards.
15152 "numericowner"
15154 If set to true, the output tar file will contain UID/GID numbers
15155 instead of user/group names.
15156 "xattrs"
15158 If set to true, extended attributes are saved in the output tar.
15159 "selinux"
15161 If set to true, SELinux contexts are saved in the output tar.
15162 "acls"
15164 If set to true, POSIX ACLs are saved in the output tar.
15165 This function returns 0 on success or -1 on error.
15167 (Added in 1.0.3)
15169 guestfs_tar_out_opts_va
15171 int
15172 guestfs_tar_out_opts_va (guestfs_h *g,
15173 const char *directory,
15174 const char *tarfile,
15175 va_list args);
15176 This is the "va_list variant" of "guestfs_tar_out_opts".
15178 See "CALLS WITH OPTIONAL ARGUMENTS".
15180 guestfs_tar_out_opts_argv
15182 int
15183 guestfs_tar_out_opts_argv (guestfs_h *g,
15184 const char *directory,
15185 const char *tarfile,
15186 const struct guestfs_tar_out_opts_argv *optargs);
15187 This is the "argv variant" of "guestfs_tar_out_opts".
15189 See "CALLS WITH OPTIONAL ARGUMENTS".
15191 guestfs_tgz_in
15193 int
15194 guestfs_tgz_in (guestfs_h *g,
15195 const char *tarball,
15196 const char *directory);
15197 This function is deprecated. In new code, use the "guestfs_tar_in"
15199 call instead.
15200 Deprecated functions will not be removed from the API, but the fact
15202 that they are deprecated indicates that there are problems with correct
15203 use of these functions.
15204 This command uploads and unpacks local file "tarball" (a gzip
15206 compressed tar file) into directory.
15207 This function returns 0 on success or -1 on error.
15209 (Added in 1.0.3)
15211 guestfs_tgz_out
15213 int
15214 guestfs_tgz_out (guestfs_h *g,
15215 const char *directory,
15216 const char *tarball);
15217 This function is deprecated. In new code, use the "guestfs_tar_out"
15219 call instead.
15220 Deprecated functions will not be removed from the API, but the fact
15222 that they are deprecated indicates that there are problems with correct
15223 use of these functions.
15224 This command packs the contents of directory and downloads it to local
15226 file "tarball".
15227 This function returns 0 on success or -1 on error.
15229 (Added in 1.0.3)
15231 guestfs_touch
15233 int
15234 guestfs_touch (guestfs_h *g,
15235 const char *path);
15236 Touch acts like the touch(1) command. It can be used to update the
15238 timestamps on a file, or, if the file does not exist, to create a new
15239 zero-length file.
15240 This command only works on regular files, and will fail on other file
15242 types such as directories, symbolic links, block special etc.
15243 This function returns 0 on success or -1 on error.
15245 (Added in 0.3)
15247 guestfs_truncate
15249 int
15250 guestfs_truncate (guestfs_h *g,
15251 const char *path);
15252 This command truncates "path" to a zero-length file. The file must
15254 exist already.
15255 This function returns 0 on success or -1 on error.
15257 (Added in 1.0.77)
15259 guestfs_truncate_size
15261 int
15262 guestfs_truncate_size (guestfs_h *g,
15263 const char *path,
15264 int64_t size);
15265 This command truncates "path" to size "size" bytes. The file must
15267 exist already.
15268 If the current file size is less than "size" then the file is extended
15270 to the required size with zero bytes. This creates a sparse file (ie.
15271 disk blocks are not allocated for the file until you write to it). To
15272 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15273 This function returns 0 on success or -1 on error.
15275 (Added in 1.0.77)
15277 guestfs_tune2fs
15279 int
15280 guestfs_tune2fs (guestfs_h *g,
15281 const char *device,
15282 ...);
15283 You may supply a list of optional arguments to this call. Use zero or
15285 more of the following pairs of parameters, and terminate the list with
15286 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15287 GUESTFS_TUNE2FS_FORCE, int force,
15289 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15290 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15291 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15292 GUESTFS_TUNE2FS_GROUP, int64_t group,
15293 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15294 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15295 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15296 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15297 GUESTFS_TUNE2FS_USER, int64_t user,
15298 This call allows you to adjust various filesystem parameters of an
15300 ext2/ext3/ext4 filesystem called "device".
15301 The optional parameters are:
15303 "force"
15305 Force tune2fs to complete the operation even in the face of errors.
15306 This is the same as the tune2fs(8) "-f" option.
15307 "maxmountcount"
15309 Set the number of mounts after which the filesystem is checked by
15310 e2fsck(8). If this is 0 then the number of mounts is disregarded.
15311 This is the same as the tune2fs(8) "-c" option.
15312 "mountcount"
15314 Set the number of times the filesystem has been mounted. This is
15315 the same as the tune2fs(8) "-C" option.
15316 "errorbehavior"
15318 Change the behavior of the kernel code when errors are detected.
15319 Possible values currently are: "continue", "remount-ro", "panic".
15320 In practice these options don't really make any difference,
15321 particularly for write errors.
15322 This is the same as the tune2fs(8) "-e" option.
15324 "group"
15326 Set the group which can use reserved filesystem blocks. This is
15327 the same as the tune2fs(8) "-g" option except that it can only be
15328 specified as a number.
15329 "intervalbetweenchecks"
15331 Adjust the maximal time between two filesystem checks (in seconds).
15332 If the option is passed as 0 then time-dependent checking is
15333 disabled.
15334 This is the same as the tune2fs(8) "-i" option.
15336 "reservedblockspercentage"
15338 Set the percentage of the filesystem which may only be allocated by
15339 privileged processes. This is the same as the tune2fs(8) "-m"
15340 option.
15341 "lastmounteddirectory"
15343 Set the last mounted directory. This is the same as the tune2fs(8)
15344 "-M" option.
15345 "reservedblockscount" Set the number of reserved filesystem blocks.
15347 This is the same as the tune2fs(8) "-r" option.
15348 "user"
15349 Set the user who can use the reserved filesystem blocks. This is
15350 the same as the tune2fs(8) "-u" option except that it can only be
15351 specified as a number.
15352 To get the current values of filesystem parameters, see
15354 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
15355 tune2fs(8) man page.
15356 This function returns 0 on success or -1 on error.
15358 (Added in 1.15.4)
15360 guestfs_tune2fs_va
15362 int
15363 guestfs_tune2fs_va (guestfs_h *g,
15364 const char *device,
15365 va_list args);
15366 This is the "va_list variant" of "guestfs_tune2fs".
15368 See "CALLS WITH OPTIONAL ARGUMENTS".
15370 guestfs_tune2fs_argv
15372 int
15373 guestfs_tune2fs_argv (guestfs_h *g,
15374 const char *device,
15375 const struct guestfs_tune2fs_argv *optargs);
15376 This is the "argv variant" of "guestfs_tune2fs".
15378 See "CALLS WITH OPTIONAL ARGUMENTS".
15380 guestfs_tune2fs_l
15382 char **
15383 guestfs_tune2fs_l (guestfs_h *g,
15384 const char *device);
15385 This returns the contents of the ext2, ext3 or ext4 filesystem
15387 superblock on "device".
15388 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
15390 for more details. The list of fields returned isn't clearly defined,
15391 and depends on both the version of "tune2fs" that libguestfs was built
15392 against, and the filesystem itself.
15393 This function returns a NULL-terminated array of strings, or NULL if
15395 there was an error. The array of strings will always have length
15396 "2n+1", where "n" keys and values alternate, followed by the trailing
15397 NULL entry. The caller must free the strings and the array after use.
15398 (Added in 1.9.2)
15400 guestfs_txz_in
15402 int
15403 guestfs_txz_in (guestfs_h *g,
15404 const char *tarball,
15405 const char *directory);
15406 This function is deprecated. In new code, use the "guestfs_tar_in"
15408 call instead.
15409 Deprecated functions will not be removed from the API, but the fact
15411 that they are deprecated indicates that there are problems with correct
15412 use of these functions.
15413 This command uploads and unpacks local file "tarball" (an xz compressed
15415 tar file) into directory.
15416 This function returns 0 on success or -1 on error.
15418 This function depends on the feature "xz". See also
15420 "guestfs_feature_available".
15421 (Added in 1.3.2)
15423 guestfs_txz_out
15425 int
15426 guestfs_txz_out (guestfs_h *g,
15427 const char *directory,
15428 const char *tarball);
15429 This function is deprecated. In new code, use the "guestfs_tar_out"
15431 call instead.
15432 Deprecated functions will not be removed from the API, but the fact
15434 that they are deprecated indicates that there are problems with correct
15435 use of these functions.
15436 This command packs the contents of directory and downloads it to local
15438 file "tarball" (as an xz compressed tar archive).
15439 This function returns 0 on success or -1 on error.
15441 This function depends on the feature "xz". See also
15443 "guestfs_feature_available".
15444 (Added in 1.3.2)
15446 guestfs_umask
15448 int
15449 guestfs_umask (guestfs_h *g,
15450 int mask);
15451 This function sets the mask used for creating new files and device
15453 nodes to "mask & 0777".
15454 Typical umask values would be 022 which creates new files with
15456 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15457 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15458 The default umask is 022. This is important because it means that
15460 directories and device nodes will be created with 0644 or 0755 mode
15461 even if you specify 0777.
15462 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15464 "guestfs_mkdir".
15465 This call returns the previous umask.
15467 On error this function returns -1.
15469 (Added in 1.0.55)
15471 guestfs_umount
15473 int
15474 guestfs_umount (guestfs_h *g,
15475 const char *pathordevice);
15476 This function is provided for backwards compatibility with earlier
15478 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15479 optional arguments.
15480 (Added in 0.8)
15482 guestfs_umount_opts
15484 int
15485 guestfs_umount_opts (guestfs_h *g,
15486 const char *pathordevice,
15487 ...);
15488 You may supply a list of optional arguments to this call. Use zero or
15490 more of the following pairs of parameters, and terminate the list with
15491 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15492 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15494 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15495 This unmounts the given filesystem. The filesystem may be specified
15497 either by its mountpoint (path) or the device which contains the
15498 filesystem.
15499 This function returns 0 on success or -1 on error.
15501 (Added in 0.8)
15503 guestfs_umount_opts_va
15505 int
15506 guestfs_umount_opts_va (guestfs_h *g,
15507 const char *pathordevice,
15508 va_list args);
15509 This is the "va_list variant" of "guestfs_umount_opts".
15511 See "CALLS WITH OPTIONAL ARGUMENTS".
15513 guestfs_umount_opts_argv
15515 int
15516 guestfs_umount_opts_argv (guestfs_h *g,
15517 const char *pathordevice,
15518 const struct guestfs_umount_opts_argv *optargs);
15519 This is the "argv variant" of "guestfs_umount_opts".
15521 See "CALLS WITH OPTIONAL ARGUMENTS".
15523 guestfs_umount_all
15525 int
15526 guestfs_umount_all (guestfs_h *g);
15527 This unmounts all mounted filesystems.
15529 Some internal mounts are not unmounted by this call.
15531 This function returns 0 on success or -1 on error.
15533 (Added in 0.8)
15535 guestfs_umount_local
15537 int
15538 guestfs_umount_local (guestfs_h *g,
15539 ...);
15540 You may supply a list of optional arguments to this call. Use zero or
15542 more of the following pairs of parameters, and terminate the list with
15543 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15544 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15546 If libguestfs is exporting the filesystem on a local mountpoint, then
15548 this unmounts it.
15549 See "MOUNT LOCAL" for full documentation.
15551 This function returns 0 on success or -1 on error.
15553 (Added in 1.17.22)
15555 guestfs_umount_local_va
15557 int
15558 guestfs_umount_local_va (guestfs_h *g,
15559 va_list args);
15560 This is the "va_list variant" of "guestfs_umount_local".
15562 See "CALLS WITH OPTIONAL ARGUMENTS".
15564 guestfs_umount_local_argv
15566 int
15567 guestfs_umount_local_argv (guestfs_h *g,
15568 const struct guestfs_umount_local_argv *optargs);
15569 This is the "argv variant" of "guestfs_umount_local".
15571 See "CALLS WITH OPTIONAL ARGUMENTS".
15573 guestfs_upload
15575 int
15576 guestfs_upload (guestfs_h *g,
15577 const char *filename,
15578 const char *remotefilename);
15579 Upload local file filename to remotefilename on the filesystem.
15581 filename can also be a named pipe.
15583 See also "guestfs_download".
15585 This function returns 0 on success or -1 on error.
15587 This long-running command can generate progress notification messages
15589 so that the caller can display a progress bar or indicator. To receive
15590 these messages, the caller must register a progress event callback.
15591 See "GUESTFS_EVENT_PROGRESS".
15592 (Added in 1.0.2)
15594 guestfs_upload_offset
15596 int
15597 guestfs_upload_offset (guestfs_h *g,
15598 const char *filename,
15599 const char *remotefilename,
15600 int64_t offset);
15601 Upload local file filename to remotefilename on the filesystem.
15603 remotefilename is overwritten starting at the byte "offset" specified.
15605 The intention is to overwrite parts of existing files or devices,
15606 although if a non-existent file is specified then it is created with a
15607 "hole" before "offset". The size of the data written is implicit in
15608 the size of the source filename.
15609 Note that there is no limit on the amount of data that can be uploaded
15611 with this call, unlike with "guestfs_pwrite", and this call always
15612 writes the full amount unless an error occurs.
15613 See also "guestfs_upload", "guestfs_pwrite".
15615 This function returns 0 on success or -1 on error.
15617 This long-running command can generate progress notification messages
15619 so that the caller can display a progress bar or indicator. To receive
15620 these messages, the caller must register a progress event callback.
15621 See "GUESTFS_EVENT_PROGRESS".
15622 (Added in 1.5.17)
15624 guestfs_user_cancel
15626 int
15627 guestfs_user_cancel (guestfs_h *g);
15628 This function cancels the current upload or download operation.
15630 Unlike most other libguestfs calls, this function is signal safe and
15632 thread safe. You can call it from a signal handler or from another
15633 thread, without needing to do any locking.
15634 The transfer that was in progress (if there is one) will stop shortly
15636 afterwards, and will return an error. The errno (see
15637 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15638 find out if the operation was cancelled or failed because of another
15639 error.
15640 No cleanup is performed: for example, if a file was being uploaded then
15642 after cancellation there may be a partially uploaded file. It is the
15643 caller’s responsibility to clean up if necessary.
15644 There are two common places that you might call "guestfs_user_cancel":
15646 In an interactive text-based program, you might call it from a "SIGINT"
15648 signal handler so that pressing "^C" cancels the current operation.
15649 (You also need to call "guestfs_set_pgroup" so that child processes
15650 don't receive the "^C" signal).
15651 In a graphical program, when the main thread is displaying a progress
15653 bar with a cancel button, wire up the cancel button to call this
15654 function.
15655 This function returns 0 on success or -1 on error.
15657 (Added in 1.11.18)
15659 guestfs_utimens
15661 int
15662 guestfs_utimens (guestfs_h *g,
15663 const char *path,
15664 int64_t atsecs,
15665 int64_t atnsecs,
15666 int64_t mtsecs,
15667 int64_t mtnsecs);
15668 This command sets the timestamps of a file with nanosecond precision.
15670 "atsecs", "atnsecs" are the last access time (atime) in secs and
15672 nanoseconds from the epoch.
15673 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
15675 nanoseconds from the epoch.
15676 If the *nsecs field contains the special value "-1" then the
15678 corresponding timestamp is set to the current time. (The *secs field
15679 is ignored in this case).
15680 If the *nsecs field contains the special value "-2" then the
15682 corresponding timestamp is left unchanged. (The *secs field is ignored
15683 in this case).
15684 This function returns 0 on success or -1 on error.
15686 (Added in 1.0.77)
15688 guestfs_utsname
15690 struct guestfs_utsname *
15691 guestfs_utsname (guestfs_h *g);
15692 This returns the kernel version of the appliance, where this is
15694 available. This information is only useful for debugging. Nothing in
15695 the returned structure is defined by the API.
15696 This function returns a "struct guestfs_utsname *", or NULL if there
15698 was an error. The caller must call "guestfs_free_utsname" after use.
15699 (Added in 1.19.27)
15701 guestfs_version
15703 struct guestfs_version *
15704 guestfs_version (guestfs_h *g);
15705 Return the libguestfs version number that the program is linked
15707 against.
15708 Note that because of dynamic linking this is not necessarily the
15710 version of libguestfs that you compiled against. You can compile the
15711 program, and then at runtime dynamically link against a completely
15712 different libguestfs.so library.
15713 This call was added in version 1.0.58. In previous versions of
15715 libguestfs there was no way to get the version number. From C code you
15716 can use dynamic linker functions to find out if this symbol exists (if
15717 it doesn't, then it’s an earlier version).
15718 The call returns a structure with four elements. The first three
15720 ("major", "minor" and "release") are numbers and correspond to the
15721 usual version triplet. The fourth element ("extra") is a string and is
15722 normally empty, but may be used for distro-specific information.
15723 To construct the original version string:
15725 "$major.$minor.$release$extra"
15726 See also: "LIBGUESTFS VERSION NUMBERS".
15728 Note: Don't use this call to test for availability of features. In
15730 enterprise distributions we backport features from later versions into
15731 earlier versions, making this an unreliable way to test for features.
15732 Use "guestfs_available" or "guestfs_feature_available" instead.
15733 This function returns a "struct guestfs_version *", or NULL if there
15735 was an error. The caller must call "guestfs_free_version" after use.
15736 (Added in 1.0.58)
15738 guestfs_vfs_label
15740 char *
15741 guestfs_vfs_label (guestfs_h *g,
15742 const char *mountable);
15743 This returns the label of the filesystem on "mountable".
15745 If the filesystem is unlabeled, this returns the empty string.
15747 To find a filesystem from the label, use "guestfs_findfs_label".
15749 This function returns a string, or NULL on error. The caller must free
15751 the returned string after use.
15752 (Added in 1.3.18)
15754 guestfs_vfs_minimum_size
15756 int64_t
15757 guestfs_vfs_minimum_size (guestfs_h *g,
15758 const char *mountable);
15759 Get the minimum size of filesystem in bytes. This is the minimum
15761 possible size for filesystem shrinking.
15762 If getting minimum size of specified filesystem is not supported, this
15764 will fail and set errno as ENOTSUP.
15765 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15767 On error this function returns -1.
15769 (Added in 1.31.18)
15771 guestfs_vfs_type
15773 char *
15774 guestfs_vfs_type (guestfs_h *g,
15775 const char *mountable);
15776 This command gets the filesystem type corresponding to the filesystem
15778 on "mountable".
15779 For most filesystems, the result is the name of the Linux VFS module
15781 which would be used to mount this filesystem if you mounted it without
15782 specifying the filesystem type. For example a string such as "ext3" or
15783 "ntfs".
15784 This function returns a string, or NULL on error. The caller must free
15786 the returned string after use.
15787 (Added in 1.0.75)
15789 guestfs_vfs_uuid
15791 char *
15792 guestfs_vfs_uuid (guestfs_h *g,
15793 const char *mountable);
15794 This returns the filesystem UUID of the filesystem on "mountable".
15796 If the filesystem does not have a UUID, this returns the empty string.
15798 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15800 This function returns a string, or NULL on error. The caller must free
15802 the returned string after use.
15803 (Added in 1.3.18)
15805 guestfs_vg_activate
15807 int
15808 guestfs_vg_activate (guestfs_h *g,
15809 int activate,
15810 char *const *volgroups);
15811 This command activates or (if "activate" is false) deactivates all
15813 logical volumes in the listed volume groups "volgroups".
15814 This command is the same as running "vgchange -a y|n volgroups..."
15816 Note that if "volgroups" is an empty list then all volume groups are
15818 activated or deactivated.
15819 This function returns 0 on success or -1 on error.
15821 This function depends on the feature "lvm2". See also
15823 "guestfs_feature_available".
15824 (Added in 1.0.26)
15826 guestfs_vg_activate_all
15828 int
15829 guestfs_vg_activate_all (guestfs_h *g,
15830 int activate);
15831 This command activates or (if "activate" is false) deactivates all
15833 logical volumes in all volume groups.
15834 This command is the same as running "vgchange -a y|n"
15836 This function returns 0 on success or -1 on error.
15838 This function depends on the feature "lvm2". See also
15840 "guestfs_feature_available".
15841 (Added in 1.0.26)
15843 guestfs_vgchange_uuid
15845 int
15846 guestfs_vgchange_uuid (guestfs_h *g,
15847 const char *vg);
15848 Generate a new random UUID for the volume group "vg".
15850 This function returns 0 on success or -1 on error.
15852 This function depends on the feature "lvm2". See also
15854 "guestfs_feature_available".
15855 (Added in 1.19.26)
15857 guestfs_vgchange_uuid_all
15859 int
15860 guestfs_vgchange_uuid_all (guestfs_h *g);
15861 Generate new random UUIDs for all volume groups.
15863 This function returns 0 on success or -1 on error.
15865 This function depends on the feature "lvm2". See also
15867 "guestfs_feature_available".
15868 (Added in 1.19.26)
15870 guestfs_vgcreate
15872 int
15873 guestfs_vgcreate (guestfs_h *g,
15874 const char *volgroup,
15875 char *const *physvols);
15876 This creates an LVM volume group called "volgroup" from the non-empty
15878 list of physical volumes "physvols".
15879 This function returns 0 on success or -1 on error.
15881 This function depends on the feature "lvm2". See also
15883 "guestfs_feature_available".
15884 (Added in 0.8)
15886 guestfs_vglvuuids
15888 char **
15889 guestfs_vglvuuids (guestfs_h *g,
15890 const char *vgname);
15891 Given a VG called "vgname", this returns the UUIDs of all the logical
15893 volumes created in this volume group.
15894 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15896 associate logical volumes and volume groups.
15897 See also "guestfs_vgpvuuids".
15899 This function returns a NULL-terminated array of strings (like
15901 environ(3)), or NULL if there was an error. The caller must free the
15902 strings and the array after use.
15903 (Added in 1.0.87)
15905 guestfs_vgmeta
15907 char *
15908 guestfs_vgmeta (guestfs_h *g,
15909 const char *vgname,
15910 size_t *size_r);
15911 "vgname" is an LVM volume group. This command examines the volume
15913 group and returns its metadata.
15914 Note that the metadata is an internal structure used by LVM, subject to
15916 change at any time, and is provided for information only.
15917 This function returns a buffer, or NULL on error. The size of the
15919 returned buffer is written to *size_r. The caller must free the
15920 returned buffer after use.
15921 This function depends on the feature "lvm2". See also
15923 "guestfs_feature_available".
15924 (Added in 1.17.20)
15926 guestfs_vgpvuuids
15928 char **
15929 guestfs_vgpvuuids (guestfs_h *g,
15930 const char *vgname);
15931 Given a VG called "vgname", this returns the UUIDs of all the physical
15933 volumes that this volume group resides on.
15934 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15936 associate physical volumes and volume groups.
15937 See also "guestfs_vglvuuids".
15939 This function returns a NULL-terminated array of strings (like
15941 environ(3)), or NULL if there was an error. The caller must free the
15942 strings and the array after use.
15943 (Added in 1.0.87)
15945 guestfs_vgremove
15947 int
15948 guestfs_vgremove (guestfs_h *g,
15949 const char *vgname);
15950 Remove an LVM volume group "vgname", (for example "VG").
15952 This also forcibly removes all logical volumes in the volume group (if
15954 any).
15955 This function returns 0 on success or -1 on error.
15957 This function depends on the feature "lvm2". See also
15959 "guestfs_feature_available".
15960 (Added in 1.0.13)
15962 guestfs_vgrename
15964 int
15965 guestfs_vgrename (guestfs_h *g,
15966 const char *volgroup,
15967 const char *newvolgroup);
15968 Rename a volume group "volgroup" with the new name "newvolgroup".
15970 This function returns 0 on success or -1 on error.
15972 (Added in 1.0.83)
15974 guestfs_vgs
15976 char **
15977 guestfs_vgs (guestfs_h *g);
15978 List all the volumes groups detected. This is the equivalent of the
15980 vgs(8) command.
15981 This returns a list of just the volume group names that were detected
15983 (eg. "VolGroup00").
15984 See also "guestfs_vgs_full".
15986 This function returns a NULL-terminated array of strings (like
15988 environ(3)), or NULL if there was an error. The caller must free the
15989 strings and the array after use.
15990 This function depends on the feature "lvm2". See also
15992 "guestfs_feature_available".
15993 (Added in 0.4)
15995 guestfs_vgs_full
15997 struct guestfs_lvm_vg_list *
15998 guestfs_vgs_full (guestfs_h *g);
15999 List all the volumes groups detected. This is the equivalent of the
16001 vgs(8) command. The "full" version includes all fields.
16002 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
16004 there was an error. The caller must call "guestfs_free_lvm_vg_list"
16005 after use.
16006 This function depends on the feature "lvm2". See also
16008 "guestfs_feature_available".
16009 (Added in 0.4)
16011 guestfs_vgscan
16013 int
16014 guestfs_vgscan (guestfs_h *g);
16015 This function is deprecated. In new code, use the "guestfs_lvm_scan"
16017 call instead.
16018 Deprecated functions will not be removed from the API, but the fact
16020 that they are deprecated indicates that there are problems with correct
16021 use of these functions.
16022 This rescans all block devices and rebuilds the list of LVM physical
16024 volumes, volume groups and logical volumes.
16025 This function returns 0 on success or -1 on error.
16027 (Added in 1.3.2)
16029 guestfs_vguuid
16031 char *
16032 guestfs_vguuid (guestfs_h *g,
16033 const char *vgname);
16034 This command returns the UUID of the LVM VG named "vgname".
16036 This function returns a string, or NULL on error. The caller must free
16038 the returned string after use.
16039 (Added in 1.0.87)
16041 guestfs_wait_ready
16043 int
16044 guestfs_wait_ready (guestfs_h *g);
16045 This function is deprecated. There is no replacement. Consult the API
16047 documentation in guestfs(3) for further information.
16048 Deprecated functions will not be removed from the API, but the fact
16050 that they are deprecated indicates that there are problems with correct
16051 use of these functions.
16052 This function is a no op.
16054 In versions of the API < 1.0.71 you had to call this function just
16056 after calling "guestfs_launch" to wait for the launch to complete.
16057 However this is no longer necessary because "guestfs_launch" now does
16058 the waiting.
16059 If you see any calls to this function in code then you can just remove
16061 them, unless you want to retain compatibility with older versions of
16062 the API.
16063 This function returns 0 on success or -1 on error.
16065 (Added in 0.3)
16067 guestfs_wc_c
16069 int
16070 guestfs_wc_c (guestfs_h *g,
16071 const char *path);
16072 This command counts the characters in a file, using the "wc -c"
16074 external command.
16075 On error this function returns -1.
16077 (Added in 1.0.54)
16079 guestfs_wc_l
16081 int
16082 guestfs_wc_l (guestfs_h *g,
16083 const char *path);
16084 This command counts the lines in a file, using the "wc -l" external
16086 command.
16087 On error this function returns -1.
16089 (Added in 1.0.54)
16091 guestfs_wc_w
16093 int
16094 guestfs_wc_w (guestfs_h *g,
16095 const char *path);
16096 This command counts the words in a file, using the "wc -w" external
16098 command.
16099 On error this function returns -1.
16101 (Added in 1.0.54)
16103 guestfs_wipefs
16105 int
16106 guestfs_wipefs (guestfs_h *g,
16107 const char *device);
16108 This command erases filesystem or RAID signatures from the specified
16110 "device" to make the filesystem invisible to libblkid.
16111 This does not erase the filesystem itself nor any other data from the
16113 "device".
16114 Compare with "guestfs_zero" which zeroes the first few blocks of a
16116 device.
16117 This function returns 0 on success or -1 on error.
16119 This function depends on the feature "wipefs". See also
16121 "guestfs_feature_available".
16122 (Added in 1.17.6)
16124 guestfs_write
16126 int
16127 guestfs_write (guestfs_h *g,
16128 const char *path,
16129 const char *content,
16130 size_t content_size);
16131 This call creates a file called "path". The content of the file is the
16133 string "content" (which can contain any 8 bit data).
16134 See also "guestfs_write_append".
16136 This function returns 0 on success or -1 on error.
16138 (Added in 1.3.14)
16140 guestfs_write_append
16142 int
16143 guestfs_write_append (guestfs_h *g,
16144 const char *path,
16145 const char *content,
16146 size_t content_size);
16147 This call appends "content" to the end of file "path". If "path" does
16149 not exist, then a new file is created.
16150 See also "guestfs_write".
16152 This function returns 0 on success or -1 on error.
16154 (Added in 1.11.18)
16156 guestfs_write_file
16158 int
16159 guestfs_write_file (guestfs_h *g,
16160 const char *path,
16161 const char *content,
16162 int size);
16163 This function is deprecated. In new code, use the "guestfs_write" call
16165 instead.
16166 Deprecated functions will not be removed from the API, but the fact
16168 that they are deprecated indicates that there are problems with correct
16169 use of these functions.
16170 This call creates a file called "path". The contents of the file is
16172 the string "content" (which can contain any 8 bit data), with length
16173 "size".
16174 As a special case, if "size" is 0 then the length is calculated using
16176 "strlen" (so in this case the content cannot contain embedded ASCII
16177 NULs).
16178 NB. Owing to a bug, writing content containing ASCII NUL characters
16180 does not work, even if the length is specified.
16181 This function returns 0 on success or -1 on error.
16183 Because of the message protocol, there is a transfer limit of somewhere
16185 between 2MB and 4MB. See "PROTOCOL LIMITS".
16186 (Added in 0.8)
16188 guestfs_xfs_admin
16190 int
16191 guestfs_xfs_admin (guestfs_h *g,
16192 const char *device,
16193 ...);
16194 You may supply a list of optional arguments to this call. Use zero or
16196 more of the following pairs of parameters, and terminate the list with
16197 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16198 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16200 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16201 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16202 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16203 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16204 GUESTFS_XFS_ADMIN_LABEL, const char *label,
16205 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16206 Change the parameters of the XFS filesystem on "device".
16208 Devices that are mounted cannot be modified. Administrators must
16210 unmount filesystems before this call can modify parameters.
16211 Some of the parameters of a mounted filesystem can be examined and
16213 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16214 This function returns 0 on success or -1 on error.
16216 This function depends on the feature "xfs". See also
16218 "guestfs_feature_available".
16219 (Added in 1.19.33)
16221 guestfs_xfs_admin_va
16223 int
16224 guestfs_xfs_admin_va (guestfs_h *g,
16225 const char *device,
16226 va_list args);
16227 This is the "va_list variant" of "guestfs_xfs_admin".
16229 See "CALLS WITH OPTIONAL ARGUMENTS".
16231 guestfs_xfs_admin_argv
16233 int
16234 guestfs_xfs_admin_argv (guestfs_h *g,
16235 const char *device,
16236 const struct guestfs_xfs_admin_argv *optargs);
16237 This is the "argv variant" of "guestfs_xfs_admin".
16239 See "CALLS WITH OPTIONAL ARGUMENTS".
16241 guestfs_xfs_growfs
16243 int
16244 guestfs_xfs_growfs (guestfs_h *g,
16245 const char *path,
16246 ...);
16247 You may supply a list of optional arguments to this call. Use zero or
16249 more of the following pairs of parameters, and terminate the list with
16250 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16251 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16253 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16254 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16255 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16256 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16257 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16258 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16259 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16260 Grow the XFS filesystem mounted at "path".
16262 The returned struct contains geometry information. Missing fields are
16264 returned as "-1" (for numeric fields) or empty string.
16265 This function returns 0 on success or -1 on error.
16267 This function depends on the feature "xfs". See also
16269 "guestfs_feature_available".
16270 (Added in 1.19.28)
16272 guestfs_xfs_growfs_va
16274 int
16275 guestfs_xfs_growfs_va (guestfs_h *g,
16276 const char *path,
16277 va_list args);
16278 This is the "va_list variant" of "guestfs_xfs_growfs".
16280 See "CALLS WITH OPTIONAL ARGUMENTS".
16282 guestfs_xfs_growfs_argv
16284 int
16285 guestfs_xfs_growfs_argv (guestfs_h *g,
16286 const char *path,
16287 const struct guestfs_xfs_growfs_argv *optargs);
16288 This is the "argv variant" of "guestfs_xfs_growfs".
16290 See "CALLS WITH OPTIONAL ARGUMENTS".
16292 guestfs_xfs_info
16294 struct guestfs_xfsinfo *
16295 guestfs_xfs_info (guestfs_h *g,
16296 const char *pathordevice);
16297 "pathordevice" is a mounted XFS filesystem or a device containing an
16299 XFS filesystem. This command returns the geometry of the filesystem.
16300 The returned struct contains geometry information. Missing fields are
16302 returned as "-1" (for numeric fields) or empty string.
16303 This function returns a "struct guestfs_xfsinfo *", or NULL if there
16305 was an error. The caller must call "guestfs_free_xfsinfo" after use.
16306 This function depends on the feature "xfs". See also
16308 "guestfs_feature_available".
16309 (Added in 1.19.21)
16311 guestfs_xfs_repair
16313 int
16314 guestfs_xfs_repair (guestfs_h *g,
16315 const char *device,
16316 ...);
16317 You may supply a list of optional arguments to this call. Use zero or
16319 more of the following pairs of parameters, and terminate the list with
16320 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16321 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16323 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16324 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16325 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16326 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16327 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16328 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16329 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16330 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16331 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16332 Repair corrupt or damaged XFS filesystem on "device".
16334 The filesystem is specified using the "device" argument which should be
16336 the device name of the disk partition or volume containing the
16337 filesystem. If given the name of a block device, "xfs_repair" will
16338 attempt to find the raw device associated with the specified block
16339 device and will use the raw device instead.
16340 Regardless, the filesystem to be repaired must be unmounted, otherwise,
16342 the resulting filesystem may be inconsistent or corrupt.
16343 The returned status indicates whether filesystem corruption was
16345 detected (returns 1) or was not detected (returns 0).
16346 On error this function returns -1.
16348 This function depends on the feature "xfs". See also
16350 "guestfs_feature_available".
16351 (Added in 1.19.36)
16353 guestfs_xfs_repair_va
16355 int
16356 guestfs_xfs_repair_va (guestfs_h *g,
16357 const char *device,
16358 va_list args);
16359 This is the "va_list variant" of "guestfs_xfs_repair".
16361 See "CALLS WITH OPTIONAL ARGUMENTS".
16363 guestfs_xfs_repair_argv
16365 int
16366 guestfs_xfs_repair_argv (guestfs_h *g,
16367 const char *device,
16368 const struct guestfs_xfs_repair_argv *optargs);
16369 This is the "argv variant" of "guestfs_xfs_repair".
16371 See "CALLS WITH OPTIONAL ARGUMENTS".
16373 guestfs_yara_destroy
16375 int
16376 guestfs_yara_destroy (guestfs_h *g);
16377 Destroy previously loaded Yara rules in order to free libguestfs
16379 resources.
16380 This function returns 0 on success or -1 on error.
16382 This function depends on the feature "libyara". See also
16384 "guestfs_feature_available".
16385 (Added in 1.37.13)
16387 guestfs_yara_load
16389 int
16390 guestfs_yara_load (guestfs_h *g,
16391 const char *filename);
16392 Upload a set of Yara rules from local file filename.
16394 Yara rules allow to categorize files based on textual or binary
16396 patterns within their content. See "guestfs_yara_scan" to see how to
16397 scan files with the loaded rules.
16398 Rules can be in binary format, as when compiled with yarac command, or
16400 in source code format. In the latter case, the rules will be first
16401 compiled and then loaded.
16402 Rules in source code format cannot include external files. In such
16404 cases, it is recommended to compile them first.
16405 Previously loaded rules will be destroyed.
16407 This function returns 0 on success or -1 on error.
16409 This long-running command can generate progress notification messages
16411 so that the caller can display a progress bar or indicator. To receive
16412 these messages, the caller must register a progress event callback.
16413 See "GUESTFS_EVENT_PROGRESS".
16414 This function depends on the feature "libyara". See also
16416 "guestfs_feature_available".
16417 (Added in 1.37.13)
16419 guestfs_yara_scan
16421 struct guestfs_yara_detection_list *
16422 guestfs_yara_scan (guestfs_h *g,
16423 const char *path);
16424 Scan a file with the previously loaded Yara rules.
16426 For each matching rule, a "yara_detection" structure is returned.
16428 The "yara_detection" structure contains the following fields.
16430 "yara_name"
16432 Path of the file matching a Yara rule.
16433 "yara_rule"
16435 Identifier of the Yara rule which matched against the given file.
16436 This function returns a "struct guestfs_yara_detection_list *", or NULL
16438 if there was an error. The caller must call
16439 "guestfs_free_yara_detection_list" after use.
16440 This long-running command can generate progress notification messages
16442 so that the caller can display a progress bar or indicator. To receive
16443 these messages, the caller must register a progress event callback.
16444 See "GUESTFS_EVENT_PROGRESS".
16445 This function depends on the feature "libyara". See also
16447 "guestfs_feature_available".
16448 (Added in 1.37.13)
16450 guestfs_zegrep
16452 char **
16453 guestfs_zegrep (guestfs_h *g,
16454 const char *regex,
16455 const char *path);
16456 This function is deprecated. In new code, use the "guestfs_grep" call
16458 instead.
16459 Deprecated functions will not be removed from the API, but the fact
16461 that they are deprecated indicates that there are problems with correct
16462 use of these functions.
16463 This calls the external "zegrep" program and returns the matching
16465 lines.
16466 This function returns a NULL-terminated array of strings (like
16468 environ(3)), or NULL if there was an error. The caller must free the
16469 strings and the array after use.
16470 Because of the message protocol, there is a transfer limit of somewhere
16472 between 2MB and 4MB. See "PROTOCOL LIMITS".
16473 (Added in 1.0.66)
16475 guestfs_zegrepi
16477 char **
16478 guestfs_zegrepi (guestfs_h *g,
16479 const char *regex,
16480 const char *path);
16481 This function is deprecated. In new code, use the "guestfs_grep" call
16483 instead.
16484 Deprecated functions will not be removed from the API, but the fact
16486 that they are deprecated indicates that there are problems with correct
16487 use of these functions.
16488 This calls the external "zegrep -i" program and returns the matching
16490 lines.
16491 This function returns a NULL-terminated array of strings (like
16493 environ(3)), or NULL if there was an error. The caller must free the
16494 strings and the array after use.
16495 Because of the message protocol, there is a transfer limit of somewhere
16497 between 2MB and 4MB. See "PROTOCOL LIMITS".
16498 (Added in 1.0.66)
16500 guestfs_zero
16502 int
16503 guestfs_zero (guestfs_h *g,
16504 const char *device);
16505 This command writes zeroes over the first few blocks of "device".
16507 How many blocks are zeroed isn't specified (but it’s not enough to
16509 securely wipe the device). It should be sufficient to remove any
16510 partition tables, filesystem superblocks and so on.
16511 If blocks are already zero, then this command avoids writing zeroes.
16513 This prevents the underlying device from becoming non-sparse or growing
16514 unnecessarily.
16515 See also: "guestfs_zero_device", "guestfs_scrub_device",
16517 "guestfs_is_zero_device"
16518 This function returns 0 on success or -1 on error.
16520 This long-running command can generate progress notification messages
16522 so that the caller can display a progress bar or indicator. To receive
16523 these messages, the caller must register a progress event callback.
16524 See "GUESTFS_EVENT_PROGRESS".
16525 (Added in 1.0.16)
16527 guestfs_zero_device
16529 int
16530 guestfs_zero_device (guestfs_h *g,
16531 const char *device);
16532 This command writes zeroes over the entire "device". Compare with
16534 "guestfs_zero" which just zeroes the first few blocks of a device.
16535 If blocks are already zero, then this command avoids writing zeroes.
16537 This prevents the underlying device from becoming non-sparse or growing
16538 unnecessarily.
16539 This function returns 0 on success or -1 on error.
16541 This long-running command can generate progress notification messages
16543 so that the caller can display a progress bar or indicator. To receive
16544 these messages, the caller must register a progress event callback.
16545 See "GUESTFS_EVENT_PROGRESS".
16546 (Added in 1.3.1)
16548 guestfs_zero_free_space
16550 int
16551 guestfs_zero_free_space (guestfs_h *g,
16552 const char *directory);
16553 Zero the free space in the filesystem mounted on directory. The
16555 filesystem must be mounted read-write.
16556 The filesystem contents are not affected, but any free space in the
16558 filesystem is freed.
16559 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16561 either as an alternative to this, or after calling this, depending on
16562 your requirements.
16563 This function returns 0 on success or -1 on error.
16565 This long-running command can generate progress notification messages
16567 so that the caller can display a progress bar or indicator. To receive
16568 these messages, the caller must register a progress event callback.
16569 See "GUESTFS_EVENT_PROGRESS".
16570 (Added in 1.17.18)
16572 guestfs_zerofree
16574 int
16575 guestfs_zerofree (guestfs_h *g,
16576 const char *device);
16577 This runs the zerofree program on "device". This program claims to
16579 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16580 it possible to compress the filesystem more effectively.
16581 You should not run this program if the filesystem is mounted.
16583 It is possible that using this program can damage the filesystem or
16585 data on the filesystem.
16586 This function returns 0 on success or -1 on error.
16588 This function depends on the feature "zerofree". See also
16590 "guestfs_feature_available".
16591 (Added in 1.0.26)
16593 guestfs_zfgrep
16595 char **
16596 guestfs_zfgrep (guestfs_h *g,
16597 const char *pattern,
16598 const char *path);
16599 This function is deprecated. In new code, use the "guestfs_grep" call
16601 instead.
16602 Deprecated functions will not be removed from the API, but the fact
16604 that they are deprecated indicates that there are problems with correct
16605 use of these functions.
16606 This calls the external "zfgrep" program and returns the matching
16608 lines.
16609 This function returns a NULL-terminated array of strings (like
16611 environ(3)), or NULL if there was an error. The caller must free the
16612 strings and the array after use.
16613 Because of the message protocol, there is a transfer limit of somewhere
16615 between 2MB and 4MB. See "PROTOCOL LIMITS".
16616 (Added in 1.0.66)
16618 guestfs_zfgrepi
16620 char **
16621 guestfs_zfgrepi (guestfs_h *g,
16622 const char *pattern,
16623 const char *path);
16624 This function is deprecated. In new code, use the "guestfs_grep" call
16626 instead.
16627 Deprecated functions will not be removed from the API, but the fact
16629 that they are deprecated indicates that there are problems with correct
16630 use of these functions.
16631 This calls the external "zfgrep -i" program and returns the matching
16633 lines.
16634 This function returns a NULL-terminated array of strings (like
16636 environ(3)), or NULL if there was an error. The caller must free the
16637 strings and the array after use.
16638 Because of the message protocol, there is a transfer limit of somewhere
16640 between 2MB and 4MB. See "PROTOCOL LIMITS".
16641 (Added in 1.0.66)
16643 guestfs_zfile
16645 char *
16646 guestfs_zfile (guestfs_h *g,
16647 const char *meth,
16648 const char *path);
16649 This function is deprecated. In new code, use the "guestfs_file" call
16651 instead.
16652 Deprecated functions will not be removed from the API, but the fact
16654 that they are deprecated indicates that there are problems with correct
16655 use of these functions.
16656 This command runs file(1) after first decompressing "path" using
16658 "meth".
16659 "meth" must be one of "gzip", "compress" or "bzip2".
16661 Since 1.0.63, use "guestfs_file" instead which can now process
16663 compressed files.
16664 This function returns a string, or NULL on error. The caller must free
16666 the returned string after use.
16667 (Added in 1.0.59)
16669 guestfs_zgrep
16671 char **
16672 guestfs_zgrep (guestfs_h *g,
16673 const char *regex,
16674 const char *path);
16675 This function is deprecated. In new code, use the "guestfs_grep" call
16677 instead.
16678 Deprecated functions will not be removed from the API, but the fact
16680 that they are deprecated indicates that there are problems with correct
16681 use of these functions.
16682 This calls the external zgrep(1) program and returns the matching
16684 lines.
16685 This function returns a NULL-terminated array of strings (like
16687 environ(3)), or NULL if there was an error. The caller must free the
16688 strings and the array after use.
16689 Because of the message protocol, there is a transfer limit of somewhere
16691 between 2MB and 4MB. See "PROTOCOL LIMITS".
16692 (Added in 1.0.66)
16694 guestfs_zgrepi
16696 char **
16697 guestfs_zgrepi (guestfs_h *g,
16698 const char *regex,
16699 const char *path);
16700 This function is deprecated. In new code, use the "guestfs_grep" call
16702 instead.
16703 Deprecated functions will not be removed from the API, but the fact
16705 that they are deprecated indicates that there are problems with correct
16706 use of these functions.
16707 This calls the external "zgrep -i" program and returns the matching
16709 lines.
16710 This function returns a NULL-terminated array of strings (like
16712 environ(3)), or NULL if there was an error. The caller must free the
16713 strings and the array after use.
16714 Because of the message protocol, there is a transfer limit of somewhere
16716 between 2MB and 4MB. See "PROTOCOL LIMITS".
16717 (Added in 1.0.66)
16719
16721 guestfs_int_bool
16722 struct guestfs_int_bool {
16723 int32_t i;
16724 int32_t b;
16725 };
16726 struct guestfs_int_bool_list {
16728 uint32_t len; /* Number of elements in list. */
16729 struct guestfs_int_bool *val; /* Elements. */
16730 };
16731 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16733 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16734 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16736 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16737 void guestfs_free_int_bool (struct guestfs_int_bool *);
16739 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16740 guestfs_lvm_pv
16742 struct guestfs_lvm_pv {
16743 char *pv_name;
16744 /* The next field is NOT nul-terminated, be careful when printing it: */
16745 char pv_uuid[32];
16746 char *pv_fmt;
16747 uint64_t pv_size;
16748 uint64_t dev_size;
16749 uint64_t pv_free;
16750 uint64_t pv_used;
16751 char *pv_attr;
16752 int64_t pv_pe_count;
16753 int64_t pv_pe_alloc_count;
16754 char *pv_tags;
16755 uint64_t pe_start;
16756 int64_t pv_mda_count;
16757 uint64_t pv_mda_free;
16758 };
16759 struct guestfs_lvm_pv_list {
16761 uint32_t len; /* Number of elements in list. */
16762 struct guestfs_lvm_pv *val; /* Elements. */
16763 };
16764 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16766 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16767 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16769 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16770 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16772 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16773 guestfs_lvm_vg
16775 struct guestfs_lvm_vg {
16776 char *vg_name;
16777 /* The next field is NOT nul-terminated, be careful when printing it: */
16778 char vg_uuid[32];
16779 char *vg_fmt;
16780 char *vg_attr;
16781 uint64_t vg_size;
16782 uint64_t vg_free;
16783 char *vg_sysid;
16784 uint64_t vg_extent_size;
16785 int64_t vg_extent_count;
16786 int64_t vg_free_count;
16787 int64_t max_lv;
16788 int64_t max_pv;
16789 int64_t pv_count;
16790 int64_t lv_count;
16791 int64_t snap_count;
16792 int64_t vg_seqno;
16793 char *vg_tags;
16794 int64_t vg_mda_count;
16795 uint64_t vg_mda_free;
16796 };
16797 struct guestfs_lvm_vg_list {
16799 uint32_t len; /* Number of elements in list. */
16800 struct guestfs_lvm_vg *val; /* Elements. */
16801 };
16802 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16804 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16805 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16807 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16808 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16810 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16811 guestfs_lvm_lv
16813 struct guestfs_lvm_lv {
16814 char *lv_name;
16815 /* The next field is NOT nul-terminated, be careful when printing it: */
16816 char lv_uuid[32];
16817 char *lv_attr;
16818 int64_t lv_major;
16819 int64_t lv_minor;
16820 int64_t lv_kernel_major;
16821 int64_t lv_kernel_minor;
16822 uint64_t lv_size;
16823 int64_t seg_count;
16824 char *origin;
16825 /* The next field is [0..100] or -1 meaning 'not present': */
16826 float snap_percent;
16827 /* The next field is [0..100] or -1 meaning 'not present': */
16828 float copy_percent;
16829 char *move_pv;
16830 char *lv_tags;
16831 char *mirror_log;
16832 char *modules;
16833 };
16834 struct guestfs_lvm_lv_list {
16836 uint32_t len; /* Number of elements in list. */
16837 struct guestfs_lvm_lv *val; /* Elements. */
16838 };
16839 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16841 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16842 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16844 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16845 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16847 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16848 guestfs_stat
16850 struct guestfs_stat {
16851 int64_t dev;
16852 int64_t ino;
16853 int64_t mode;
16854 int64_t nlink;
16855 int64_t uid;
16856 int64_t gid;
16857 int64_t rdev;
16858 int64_t size;
16859 int64_t blksize;
16860 int64_t blocks;
16861 int64_t atime;
16862 int64_t mtime;
16863 int64_t ctime;
16864 };
16865 struct guestfs_stat_list {
16867 uint32_t len; /* Number of elements in list. */
16868 struct guestfs_stat *val; /* Elements. */
16869 };
16870 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16872 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16873 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16875 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16876 void guestfs_free_stat (struct guestfs_stat *);
16878 void guestfs_free_stat_list (struct guestfs_stat_list *);
16879 guestfs_statns
16881 struct guestfs_statns {
16882 int64_t st_dev;
16883 int64_t st_ino;
16884 int64_t st_mode;
16885 int64_t st_nlink;
16886 int64_t st_uid;
16887 int64_t st_gid;
16888 int64_t st_rdev;
16889 int64_t st_size;
16890 int64_t st_blksize;
16891 int64_t st_blocks;
16892 int64_t st_atime_sec;
16893 int64_t st_atime_nsec;
16894 int64_t st_mtime_sec;
16895 int64_t st_mtime_nsec;
16896 int64_t st_ctime_sec;
16897 int64_t st_ctime_nsec;
16898 int64_t st_spare1;
16899 int64_t st_spare2;
16900 int64_t st_spare3;
16901 int64_t st_spare4;
16902 int64_t st_spare5;
16903 int64_t st_spare6;
16904 };
16905 struct guestfs_statns_list {
16907 uint32_t len; /* Number of elements in list. */
16908 struct guestfs_statns *val; /* Elements. */
16909 };
16910 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16912 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16913 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16915 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16916 void guestfs_free_statns (struct guestfs_statns *);
16918 void guestfs_free_statns_list (struct guestfs_statns_list *);
16919 guestfs_statvfs
16921 struct guestfs_statvfs {
16922 int64_t bsize;
16923 int64_t frsize;
16924 int64_t blocks;
16925 int64_t bfree;
16926 int64_t bavail;
16927 int64_t files;
16928 int64_t ffree;
16929 int64_t favail;
16930 int64_t fsid;
16931 int64_t flag;
16932 int64_t namemax;
16933 };
16934 struct guestfs_statvfs_list {
16936 uint32_t len; /* Number of elements in list. */
16937 struct guestfs_statvfs *val; /* Elements. */
16938 };
16939 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16941 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16942 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16944 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16945 void guestfs_free_statvfs (struct guestfs_statvfs *);
16947 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16948 guestfs_dirent
16950 struct guestfs_dirent {
16951 int64_t ino;
16952 char ftyp;
16953 char *name;
16954 };
16955 struct guestfs_dirent_list {
16957 uint32_t len; /* Number of elements in list. */
16958 struct guestfs_dirent *val; /* Elements. */
16959 };
16960 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16962 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16963 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16965 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16966 void guestfs_free_dirent (struct guestfs_dirent *);
16968 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16969 guestfs_version
16971 struct guestfs_version {
16972 int64_t major;
16973 int64_t minor;
16974 int64_t release;
16975 char *extra;
16976 };
16977 struct guestfs_version_list {
16979 uint32_t len; /* Number of elements in list. */
16980 struct guestfs_version *val; /* Elements. */
16981 };
16982 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16984 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16985 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16987 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16988 void guestfs_free_version (struct guestfs_version *);
16990 void guestfs_free_version_list (struct guestfs_version_list *);
16991 guestfs_xattr
16993 struct guestfs_xattr {
16994 char *attrname;
16995 /* The next two fields describe a byte array. */
16996 uint32_t attrval_len;
16997 char *attrval;
16998 };
16999 struct guestfs_xattr_list {
17001 uint32_t len; /* Number of elements in list. */
17002 struct guestfs_xattr *val; /* Elements. */
17003 };
17004 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
17006 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
17007 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
17009 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
17010 void guestfs_free_xattr (struct guestfs_xattr *);
17012 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
17013 guestfs_inotify_event
17015 struct guestfs_inotify_event {
17016 int64_t in_wd;
17017 uint32_t in_mask;
17018 uint32_t in_cookie;
17019 char *in_name;
17020 };
17021 struct guestfs_inotify_event_list {
17023 uint32_t len; /* Number of elements in list. */
17024 struct guestfs_inotify_event *val; /* Elements. */
17025 };
17026 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
17028 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
17029 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
17031 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
17032 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
17034 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
17035 guestfs_partition
17037 struct guestfs_partition {
17038 int32_t part_num;
17039 uint64_t part_start;
17040 uint64_t part_end;
17041 uint64_t part_size;
17042 };
17043 struct guestfs_partition_list {
17045 uint32_t len; /* Number of elements in list. */
17046 struct guestfs_partition *val; /* Elements. */
17047 };
17048 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
17050 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
17051 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
17053 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
17054 void guestfs_free_partition (struct guestfs_partition *);
17056 void guestfs_free_partition_list (struct guestfs_partition_list *);
17057 guestfs_application
17059 struct guestfs_application {
17060 char *app_name;
17061 char *app_display_name;
17062 int32_t app_epoch;
17063 char *app_version;
17064 char *app_release;
17065 char *app_install_path;
17066 char *app_trans_path;
17067 char *app_publisher;
17068 char *app_url;
17069 char *app_source_package;
17070 char *app_summary;
17071 char *app_description;
17072 };
17073 struct guestfs_application_list {
17075 uint32_t len; /* Number of elements in list. */
17076 struct guestfs_application *val; /* Elements. */
17077 };
17078 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
17080 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
17081 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
17083 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
17084 void guestfs_free_application (struct guestfs_application *);
17086 void guestfs_free_application_list (struct guestfs_application_list *);
17087 guestfs_application2
17089 struct guestfs_application2 {
17090 char *app2_name;
17091 char *app2_display_name;
17092 int32_t app2_epoch;
17093 char *app2_version;
17094 char *app2_release;
17095 char *app2_arch;
17096 char *app2_install_path;
17097 char *app2_trans_path;
17098 char *app2_publisher;
17099 char *app2_url;
17100 char *app2_source_package;
17101 char *app2_summary;
17102 char *app2_description;
17103 char *app2_spare1;
17104 char *app2_spare2;
17105 char *app2_spare3;
17106 char *app2_spare4;
17107 };
17108 struct guestfs_application2_list {
17110 uint32_t len; /* Number of elements in list. */
17111 struct guestfs_application2 *val; /* Elements. */
17112 };
17113 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
17115 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
17116 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
17118 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
17119 void guestfs_free_application2 (struct guestfs_application2 *);
17121 void guestfs_free_application2_list (struct guestfs_application2_list *);
17122 guestfs_isoinfo
17124 struct guestfs_isoinfo {
17125 char *iso_system_id;
17126 char *iso_volume_id;
17127 uint32_t iso_volume_space_size;
17128 uint32_t iso_volume_set_size;
17129 uint32_t iso_volume_sequence_number;
17130 uint32_t iso_logical_block_size;
17131 char *iso_volume_set_id;
17132 char *iso_publisher_id;
17133 char *iso_data_preparer_id;
17134 char *iso_application_id;
17135 char *iso_copyright_file_id;
17136 char *iso_abstract_file_id;
17137 char *iso_bibliographic_file_id;
17138 int64_t iso_volume_creation_t;
17139 int64_t iso_volume_modification_t;
17140 int64_t iso_volume_expiration_t;
17141 int64_t iso_volume_effective_t;
17142 };
17143 struct guestfs_isoinfo_list {
17145 uint32_t len; /* Number of elements in list. */
17146 struct guestfs_isoinfo *val; /* Elements. */
17147 };
17148 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
17150 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
17151 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
17153 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
17154 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
17156 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
17157 guestfs_mdstat
17159 struct guestfs_mdstat {
17160 char *mdstat_device;
17161 int32_t mdstat_index;
17162 char *mdstat_flags;
17163 };
17164 struct guestfs_mdstat_list {
17166 uint32_t len; /* Number of elements in list. */
17167 struct guestfs_mdstat *val; /* Elements. */
17168 };
17169 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
17171 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
17172 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
17174 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
17175 void guestfs_free_mdstat (struct guestfs_mdstat *);
17177 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
17178 guestfs_btrfssubvolume
17180 struct guestfs_btrfssubvolume {
17181 uint64_t btrfssubvolume_id;
17182 uint64_t btrfssubvolume_top_level_id;
17183 char *btrfssubvolume_path;
17184 };
17185 struct guestfs_btrfssubvolume_list {
17187 uint32_t len; /* Number of elements in list. */
17188 struct guestfs_btrfssubvolume *val; /* Elements. */
17189 };
17190 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17192 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17193 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17195 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17196 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17198 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17199 guestfs_btrfsqgroup
17201 struct guestfs_btrfsqgroup {
17202 char *btrfsqgroup_id;
17203 uint64_t btrfsqgroup_rfer;
17204 uint64_t btrfsqgroup_excl;
17205 };
17206 struct guestfs_btrfsqgroup_list {
17208 uint32_t len; /* Number of elements in list. */
17209 struct guestfs_btrfsqgroup *val; /* Elements. */
17210 };
17211 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17213 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17214 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17216 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17217 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17219 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17220 guestfs_btrfsbalance
17222 struct guestfs_btrfsbalance {
17223 char *btrfsbalance_status;
17224 uint64_t btrfsbalance_total;
17225 uint64_t btrfsbalance_balanced;
17226 uint64_t btrfsbalance_considered;
17227 uint64_t btrfsbalance_left;
17228 };
17229 struct guestfs_btrfsbalance_list {
17231 uint32_t len; /* Number of elements in list. */
17232 struct guestfs_btrfsbalance *val; /* Elements. */
17233 };
17234 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17236 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17237 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17239 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17240 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17242 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17243 guestfs_btrfsscrub
17245 struct guestfs_btrfsscrub {
17246 uint64_t btrfsscrub_data_extents_scrubbed;
17247 uint64_t btrfsscrub_tree_extents_scrubbed;
17248 uint64_t btrfsscrub_data_bytes_scrubbed;
17249 uint64_t btrfsscrub_tree_bytes_scrubbed;
17250 uint64_t btrfsscrub_read_errors;
17251 uint64_t btrfsscrub_csum_errors;
17252 uint64_t btrfsscrub_verify_errors;
17253 uint64_t btrfsscrub_no_csum;
17254 uint64_t btrfsscrub_csum_discards;
17255 uint64_t btrfsscrub_super_errors;
17256 uint64_t btrfsscrub_malloc_errors;
17257 uint64_t btrfsscrub_uncorrectable_errors;
17258 uint64_t btrfsscrub_unverified_errors;
17259 uint64_t btrfsscrub_corrected_errors;
17260 uint64_t btrfsscrub_last_physical;
17261 };
17262 struct guestfs_btrfsscrub_list {
17264 uint32_t len; /* Number of elements in list. */
17265 struct guestfs_btrfsscrub *val; /* Elements. */
17266 };
17267 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17269 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17270 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17272 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17273 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17275 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17276 guestfs_xfsinfo
17278 struct guestfs_xfsinfo {
17279 char *xfs_mntpoint;
17280 uint32_t xfs_inodesize;
17281 uint32_t xfs_agcount;
17282 uint32_t xfs_agsize;
17283 uint32_t xfs_sectsize;
17284 uint32_t xfs_attr;
17285 uint32_t xfs_blocksize;
17286 uint64_t xfs_datablocks;
17287 uint32_t xfs_imaxpct;
17288 uint32_t xfs_sunit;
17289 uint32_t xfs_swidth;
17290 uint32_t xfs_dirversion;
17291 uint32_t xfs_dirblocksize;
17292 uint32_t xfs_cimode;
17293 char *xfs_logname;
17294 uint32_t xfs_logblocksize;
17295 uint32_t xfs_logblocks;
17296 uint32_t xfs_logversion;
17297 uint32_t xfs_logsectsize;
17298 uint32_t xfs_logsunit;
17299 uint32_t xfs_lazycount;
17300 char *xfs_rtname;
17301 uint32_t xfs_rtextsize;
17302 uint64_t xfs_rtblocks;
17303 uint64_t xfs_rtextents;
17304 };
17305 struct guestfs_xfsinfo_list {
17307 uint32_t len; /* Number of elements in list. */
17308 struct guestfs_xfsinfo *val; /* Elements. */
17309 };
17310 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17312 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17313 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17315 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17316 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17318 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17319 guestfs_utsname
17321 struct guestfs_utsname {
17322 char *uts_sysname;
17323 char *uts_release;
17324 char *uts_version;
17325 char *uts_machine;
17326 };
17327 struct guestfs_utsname_list {
17329 uint32_t len; /* Number of elements in list. */
17330 struct guestfs_utsname *val; /* Elements. */
17331 };
17332 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17334 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17335 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17337 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17338 void guestfs_free_utsname (struct guestfs_utsname *);
17340 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17341 guestfs_hivex_node
17343 struct guestfs_hivex_node {
17344 int64_t hivex_node_h;
17345 };
17346 struct guestfs_hivex_node_list {
17348 uint32_t len; /* Number of elements in list. */
17349 struct guestfs_hivex_node *val; /* Elements. */
17350 };
17351 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17353 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17354 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17356 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17357 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17359 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17360 guestfs_hivex_value
17362 struct guestfs_hivex_value {
17363 int64_t hivex_value_h;
17364 };
17365 struct guestfs_hivex_value_list {
17367 uint32_t len; /* Number of elements in list. */
17368 struct guestfs_hivex_value *val; /* Elements. */
17369 };
17370 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17372 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17373 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17375 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17376 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17378 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17379 guestfs_internal_mountable
17381 struct guestfs_internal_mountable {
17382 int32_t im_type;
17383 char *im_device;
17384 char *im_volume;
17385 };
17386 struct guestfs_internal_mountable_list {
17388 uint32_t len; /* Number of elements in list. */
17389 struct guestfs_internal_mountable *val; /* Elements. */
17390 };
17391 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17393 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17394 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17396 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17397 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17399 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17400 guestfs_tsk_dirent
17402 struct guestfs_tsk_dirent {
17403 uint64_t tsk_inode;
17404 char tsk_type;
17405 int64_t tsk_size;
17406 char *tsk_name;
17407 uint32_t tsk_flags;
17408 int64_t tsk_atime_sec;
17409 int64_t tsk_atime_nsec;
17410 int64_t tsk_mtime_sec;
17411 int64_t tsk_mtime_nsec;
17412 int64_t tsk_ctime_sec;
17413 int64_t tsk_ctime_nsec;
17414 int64_t tsk_crtime_sec;
17415 int64_t tsk_crtime_nsec;
17416 int64_t tsk_nlink;
17417 char *tsk_link;
17418 int64_t tsk_spare1;
17419 };
17420 struct guestfs_tsk_dirent_list {
17422 uint32_t len; /* Number of elements in list. */
17423 struct guestfs_tsk_dirent *val; /* Elements. */
17424 };
17425 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17427 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17428 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17430 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17431 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17433 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17434 guestfs_yara_detection
17436 struct guestfs_yara_detection {
17437 char *yara_name;
17438 char *yara_rule;
17439 };
17440 struct guestfs_yara_detection_list {
17442 uint32_t len; /* Number of elements in list. */
17443 struct guestfs_yara_detection *val; /* Elements. */
17444 };
17445 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17447 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17448 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17450 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17451 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17453 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17454
17456 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17457 Using "guestfs_available" you can test availability of the following
17458 groups of functions. This test queries the appliance to see if the
17459 appliance you are currently using supports the functionality.
17460 acl The following functions: "guestfs_acl_delete_def_file"
17462 "guestfs_acl_get_file" "guestfs_acl_set_file"
17463 blkdiscard
17465 The following functions: "guestfs_blkdiscard"
17466 blkdiscardzeroes
17468 The following functions: "guestfs_blkdiscardzeroes"
17469 btrfs
17471 The following functions: "guestfs_btrfs_balance_cancel"
17472 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17473 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17474 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17475 "guestfs_btrfs_filesystem_defragment"
17476 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17477 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17478 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17479 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17480 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17481 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17482 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17483 "guestfs_btrfs_rescue_chunk_recover"
17484 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17485 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17486 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17487 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17488 "guestfs_btrfs_subvolume_get_default"
17489 "guestfs_btrfs_subvolume_list"
17490 "guestfs_btrfs_subvolume_set_default"
17491 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17492 "guestfs_btrfstune_enable_extended_inode_refs"
17493 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17494 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17495 extlinux
17497 The following functions: "guestfs_extlinux"
17498 f2fs
17500 The following functions: "guestfs_f2fs_expand"
17501 fstrim
17503 The following functions: "guestfs_fstrim"
17504 gdisk
17506 The following functions: "guestfs_part_expand_gpt"
17507 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17508 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17509 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17510 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17511 "guestfs_part_set_gpt_type"
17512 grub
17514 The following functions: "guestfs_grub_install"
17515 hivex
17517 The following functions: "guestfs_hivex_close"
17518 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17519 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17520 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17521 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17522 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17523 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17524 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17525 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17526 inotify
17528 The following functions: "guestfs_inotify_add_watch"
17529 "guestfs_inotify_close" "guestfs_inotify_files"
17530 "guestfs_inotify_init" "guestfs_inotify_read"
17531 "guestfs_inotify_rm_watch"
17532 journal
17534 The following functions: "guestfs_internal_journal_get"
17535 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17536 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17537 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17538 "guestfs_journal_skip"
17539 ldm The following functions: "guestfs_ldmtool_create_all"
17541 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17542 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17543 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17544 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17545 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17546 "guestfs_list_ldm_volumes"
17547 libtsk
17549 The following functions: "guestfs_internal_filesystem_walk"
17550 "guestfs_internal_find_inode"
17551 libyara
17553 The following functions: "guestfs_internal_yara_scan"
17554 "guestfs_yara_destroy" "guestfs_yara_load"
17555 linuxcaps
17557 The following functions: "guestfs_cap_get_file"
17558 "guestfs_cap_set_file"
17559 linuxfsuuid
17561 The following functions: "guestfs_mke2fs_JU"
17562 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17563 "guestfs_swapon_uuid"
17564 linuxmodules
17566 The following functions: "guestfs_modprobe"
17567 linuxxattrs
17569 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17570 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17571 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17572 "guestfs_removexattr" "guestfs_setxattr"
17573 luks
17575 The following functions: "guestfs_cryptsetup_close"
17576 "guestfs_cryptsetup_open" "guestfs_luks_add_key"
17577 "guestfs_luks_close" "guestfs_luks_format"
17578 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17579 "guestfs_luks_open" "guestfs_luks_open_ro" "guestfs_luks_uuid"
17580 lvm2
17582 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17583 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17584 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17585 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17586 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17587 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17588 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17589 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17590 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17591 "guestfs_vgs" "guestfs_vgs_full"
17592 mdadm
17594 The following functions: "guestfs_md_create" "guestfs_md_detail"
17595 "guestfs_md_stat" "guestfs_md_stop"
17596 mknod
17598 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17599 "guestfs_mknod_b" "guestfs_mknod_c"
17600 ntfs3g
17602 The following functions: "guestfs_ntfs_3g_probe"
17603 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17604 ntfsprogs
17606 The following functions: "guestfs_ntfsresize"
17607 "guestfs_ntfsresize_size"
17608 rsync
17610 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17611 "guestfs_rsync_out"
17612 scrub
17614 The following functions: "guestfs_scrub_device"
17615 "guestfs_scrub_file" "guestfs_scrub_freespace"
17616 selinux
17618 The following functions: "guestfs_getcon" "guestfs_setcon"
17619 selinuxrelabel
17621 The following functions: "guestfs_selinux_relabel"
17622 sleuthkit
17624 The following functions: "guestfs_download_blocks"
17625 "guestfs_download_inode"
17626 squashfs
17628 The following functions: "guestfs_mksquashfs"
17629 syslinux
17631 The following functions: "guestfs_syslinux"
17632 wipefs
17634 The following functions: "guestfs_wipefs"
17635 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17637 "guestfs_xfs_info" "guestfs_xfs_repair"
17638 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17640 zerofree
17642 The following functions: "guestfs_zerofree"
17643 FILESYSTEM AVAILABLE
17645 The "guestfs_filesystem_available" call tests whether a filesystem type
17646 is supported by the appliance kernel.
17647 This is mainly useful as a negative test. If this returns true, it
17649 doesn't mean that a particular filesystem can be mounted, since
17650 filesystems can fail for other reasons such as it being a later version
17651 of the filesystem, or having incompatible features.
17652 GUESTFISH supported COMMAND
17654 In guestfish(3) there is a handy interactive command "supported" which
17655 prints out the available groups and whether they are supported by this
17656 build of libguestfs. Note however that you have to do "run" first.
17657 SINGLE CALLS AT COMPILE TIME
17659 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17660 function, such as:
17661 #define GUESTFS_HAVE_DD 1
17663 if "guestfs_dd" is available.
17665 Before version 1.5.8, if you needed to test whether a single libguestfs
17667 function is available at compile time, we recommended using build tools
17668 such as autoconf or cmake. For example in autotools you could use:
17669 AC_CHECK_LIB([guestfs],[guestfs_create])
17671 AC_CHECK_FUNCS([guestfs_dd])
17672 which would result in "HAVE_GUESTFS_DD" being either defined or not
17674 defined in your program.
17675 SINGLE CALLS AT RUN TIME
17677 Testing at compile time doesn't guarantee that a function really exists
17678 in the library. The reason is that you might be dynamically linked
17679 against a previous libguestfs.so (dynamic library) which doesn't have
17680 the call. This situation unfortunately results in a segmentation
17681 fault, which is a shortcoming of the C dynamic linking system itself.
17682 You can use dlopen(3) to test if a function is available at run time,
17684 as in this example program (note that you still need the compile time
17685 check as well):
17686 #include <stdio.h>
17688 #include <stdlib.h>
17689 #include <unistd.h>
17690 #include <dlfcn.h>
17691 #include <guestfs.h>
17692 main ()
17694 {
17695 #ifdef GUESTFS_HAVE_DD
17696 void *dl;
17697 int has_function;
17698 /* Test if the function guestfs_dd is really available. */
17700 dl = dlopen (NULL, RTLD_LAZY);
17701 if (!dl) {
17702 fprintf (stderr, "dlopen: %s\n", dlerror ());
17703 exit (EXIT_FAILURE);
17704 }
17705 has_function = dlsym (dl, "guestfs_dd") != NULL;
17706 dlclose (dl);
17707 if (!has_function)
17709 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17710 else {
17711 printf ("this libguestfs.so has guestfs_dd function\n");
17712 /* Now it's safe to call
17713 guestfs_dd (g, "foo", "bar");
17714 */
17715 }
17716 #else
17717 printf ("guestfs_dd function was not found at compile time\n");
17718 #endif
17719 }
17720 You may think the above is an awful lot of hassle, and it is. There
17722 are other ways outside of the C linking system to ensure that this kind
17723 of incompatibility never arises, such as using package versioning:
17724 Requires: libguestfs >= 1.0.80
17726
17728 A recent feature of the API is the introduction of calls which take
17729 optional arguments. In C these are declared 3 ways. The main way is
17730 as a call which takes variable arguments (ie. "..."), as in this
17731 example:
17732 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17734 Call this with a list of optional arguments, terminated by "-1". So to
17736 call with no optional arguments specified:
17737 guestfs_add_drive_opts (g, filename, -1);
17739 With a single optional argument:
17741 guestfs_add_drive_opts (g, filename,
17743 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17744 -1);
17745 With two:
17747 guestfs_add_drive_opts (g, filename,
17749 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17750 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17751 -1);
17752 and so forth. Don’t forget the terminating "-1" otherwise Bad Things
17754 will happen!
17755 USING va_list FOR OPTIONAL ARGUMENTS
17757 The second variant has the same name with the suffix "_va", which works
17758 the same way but takes a "va_list". See the C manual for details. For
17759 the example function, this is declared:
17760 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17762 va_list args);
17763 CONSTRUCTING OPTIONAL ARGUMENTS
17765 The third variant is useful where you need to construct these calls.
17766 You pass in a structure where you fill in the optional fields. The
17767 structure has a bitmask as the first element which you must set to
17768 indicate which fields you have filled in. For our example function the
17769 structure and call are declared:
17770 struct guestfs_add_drive_opts_argv {
17772 uint64_t bitmask;
17773 int readonly;
17774 const char *format;
17775 /* ... */
17776 };
17777 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17778 const struct guestfs_add_drive_opts_argv *optargs);
17779 You could call it like this:
17781 struct guestfs_add_drive_opts_argv optargs = {
17783 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17784 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17785 .readonly = 1,
17786 .format = "qcow2"
17787 };
17788 guestfs_add_drive_opts_argv (g, filename, &optargs);
17790 Notes:
17792 • The "_BITMASK" suffix on each option name when specifying the
17794 bitmask.
17795 • You do not need to fill in all fields of the structure.
17797 • There must be a one-to-one correspondence between fields of the
17799 structure that are filled in, and bits set in the bitmask.
17800 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17802 In other languages, optional arguments are expressed in the way that is
17803 natural for that language. We refer you to the language-specific
17804 documentation for more details on that.
17805 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17807
17809 SETTING CALLBACKS TO HANDLE EVENTS
17810 Note: This section documents the generic event mechanism introduced in
17811 libguestfs 1.10, which you should use in new code if possible. The old
17812 functions "guestfs_set_log_message_callback",
17813 "guestfs_set_subprocess_quit_callback",
17814 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17815 "guestfs_set_progress_callback" are no longer documented in this manual
17816 page. Because of the ABI guarantee, the old functions continue to
17817 work.
17818 Handles generate events when certain things happen, such as log
17820 messages being generated, progress messages during long-running
17821 operations, or the handle being closed. The API calls described below
17822 let you register a callback to be called when events happen. You can
17823 register multiple callbacks (for the same, different or overlapping
17824 sets of events), and individually remove callbacks. If callbacks are
17825 not removed, then they remain in force until the handle is closed.
17826 In the current implementation, events are only generated synchronously:
17828 that means that events (and hence callbacks) can only happen while you
17829 are in the middle of making another libguestfs call. The callback is
17830 called in the same thread.
17831 Events may contain a payload, usually nothing (void), an array of 64
17833 bit unsigned integers, or a message buffer. Payloads are discussed
17834 later on.
17835 CLASSES OF EVENTS
17837 GUESTFS_EVENT_CLOSE (payload type: void)
17838 The callback function will be called while the handle is being
17839 closed (synchronously from "guestfs_close").
17840 Note that libguestfs installs an atexit(3) handler to try to clean
17842 up handles that are open when the program exits. This means that
17843 this callback might be called indirectly from exit(3), which can
17844 cause unexpected problems in higher-level languages (eg. if your
17845 HLL interpreter has already been cleaned up by the time this is
17846 called, and if your callback then jumps into some HLL function).
17847 If no callback is registered: the handle is closed without any
17849 callback being invoked.
17850 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17852 The callback function will be called when the child process quits,
17853 either asynchronously or if killed by "guestfs_kill_subprocess".
17854 (This corresponds to a transition from any state to the CONFIG
17855 state).
17856 If no callback is registered: the event is ignored.
17858 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17860 The callback function will be called when the child process becomes
17861 ready first time after it has been launched. (This corresponds to
17862 a transition from LAUNCHING to the READY state).
17863 If no callback is registered: the event is ignored.
17865 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17867 Some long-running operations can generate progress messages. If
17868 this callback is registered, then it will be called each time a
17869 progress message is generated (usually two seconds after the
17870 operation started, and three times per second thereafter until it
17871 completes, although the frequency may change in future versions).
17872 The callback receives in the payload four unsigned 64 bit numbers
17874 which are (in order): "proc_nr", "serial", "position", "total".
17875 The units of "total" are not defined, although for some operations
17877 "total" may relate in some way to the amount of data to be
17878 transferred (eg. in bytes or megabytes), and "position" may be the
17879 portion which has been transferred.
17880 The only defined and stable parts of the API are:
17882 • The callback can display to the user some type of progress bar
17884 or indicator which shows the ratio of "position":"total".
17885 • 0 <= "position" <= "total"
17887 • If any progress notification is sent during a call, then a
17889 final progress notification is always sent when "position" =
17890 "total" (unless the call fails with an error).
17891 This is to simplify caller code, so callers can easily set the
17893 progress indicator to "100%" at the end of the operation,
17894 without requiring special code to detect this case.
17895 • For some calls we are unable to estimate the progress of the
17897 call, but we can still generate progress messages to indicate
17898 activity. This is known as "pulse mode", and is directly
17899 supported by certain progress bar implementations (eg.
17900 GtkProgressBar).
17901 For these calls, zero or more progress messages are generated
17903 with "position = 0" and "total = 1", followed by a final
17904 message with "position = total = 1".
17905 As noted above, if the call fails with an error then the final
17907 message may not be generated.
17908 The callback also receives the procedure number ("proc_nr") and
17910 serial number ("serial") of the call. These are only useful for
17911 debugging protocol issues, and the callback can normally ignore
17912 them. The callback may want to print these numbers in error
17913 messages or debugging messages.
17914 If no callback is registered: progress messages are discarded.
17916 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17918 The callback function is called whenever a log message is generated
17919 by qemu, the appliance kernel, guestfsd (daemon), or utility
17920 programs.
17921 If the verbose flag ("guestfs_set_verbose") is set before launch
17923 ("guestfs_launch") then additional debug messages are generated.
17924 If no callback is registered: the messages are discarded unless the
17926 verbose flag is set in which case they are sent to stderr. You can
17927 override the printing of verbose messages to stderr by setting up a
17928 callback.
17929 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17931 The callback function is called whenever a log message is generated
17932 by the library part of libguestfs.
17933 If the verbose flag ("guestfs_set_verbose") is set then additional
17935 debug messages are generated.
17936 If no callback is registered: the messages are discarded unless the
17938 verbose flag is set in which case they are sent to stderr. You can
17939 override the printing of verbose messages to stderr by setting up a
17940 callback.
17941 GUESTFS_EVENT_WARNING (payload type: message buffer)
17943 The callback function is called whenever a warning message is
17944 generated by the library part of libguestfs.
17945 If no callback is registered: the messages are printed to stderr.
17947 You can override the printing of warning messages to stderr by
17948 setting up a callback.
17949 GUESTFS_EVENT_TRACE (payload type: message buffer)
17951 The callback function is called whenever a trace message is
17952 generated. This only applies if the trace flag
17953 ("guestfs_set_trace") is set.
17954 If no callback is registered: the messages are sent to stderr. You
17956 can override the printing of trace messages to stderr by setting up
17957 a callback.
17958 GUESTFS_EVENT_ENTER (payload type: function name)
17960 The callback function is called whenever a libguestfs function is
17961 entered.
17962 The payload is a string which contains the name of the function
17964 that we are entering (not including "guestfs_" prefix).
17965 Note that libguestfs functions can call themselves, so you may see
17967 many events from a single call. A few libguestfs functions do not
17968 generate this event.
17969 If no callback is registered: the event is ignored.
17971 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17973 For any API function that opens a libvirt connection, this event
17974 may be generated to indicate that libvirt demands authentication
17975 information. See "LIBVIRT AUTHENTICATION" below.
17976 If no callback is registered: "virConnectAuthPtrDefault" is used
17978 (suitable for command-line programs only).
17979 EVENT API
17981 guestfs_set_event_callback
17982 int guestfs_set_event_callback (guestfs_h *g,
17984 guestfs_event_callback cb,
17985 uint64_t event_bitmask,
17986 int flags,
17987 void *opaque);
17988 This function registers a callback ("cb") for all event classes in the
17990 "event_bitmask".
17991 For example, to register for all log message events, you could call
17993 this function with the bitmask
17994 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17995 To register a single callback for all possible classes of events, use
17996 "GUESTFS_EVENT_ALL".
17997 "flags" should always be passed as 0.
17999 "opaque" is an opaque pointer which is passed to the callback. You can
18001 use it for any purpose.
18002 The return value is the event handle (an integer) which you can use to
18004 delete the callback (see below).
18005 If there is an error, this function returns "-1", and sets the error in
18007 the handle in the usual way (see "guestfs_last_error" etc.)
18008 Callbacks remain in effect until they are deleted, or until the handle
18010 is closed.
18011 In the case where multiple callbacks are registered for a particular
18013 event class, all of the callbacks are called. The order in which
18014 multiple callbacks are called is not defined.
18015 guestfs_delete_event_callback
18017 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
18019 Delete a callback that was previously registered. "event_handle"
18021 should be the integer that was returned by a previous call to
18022 "guestfs_set_event_callback" on the same handle.
18023 guestfs_event_to_string
18025 char *guestfs_event_to_string (uint64_t event);
18027 "event" is either a single event or a bitmask of events. This returns
18029 a string representation (useful for debugging or printing events).
18030 A single event is returned as the name in lower case, eg. "close".
18032 A bitmask of several events is returned as a comma-separated list, eg.
18034 "close,progress".
18035 If zero is passed, then the empty string "" is returned.
18037 On success this returns a string. On error it returns NULL and sets
18039 "errno".
18040 The returned string must be freed by the caller.
18042 guestfs_event_callback
18044 typedef void (*guestfs_event_callback) (
18046 guestfs_h *g,
18047 void *opaque,
18048 uint64_t event,
18049 int event_handle,
18050 int flags,
18051 const char *buf, size_t buf_len,
18052 const uint64_t *array, size_t array_len);
18053 This is the type of the event callback function that you have to
18055 provide.
18056 The basic parameters are: the handle ("g"), the opaque user pointer
18058 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
18059 handle, and "flags" which in the current API you should ignore.
18060 The remaining parameters contain the event payload (if any). Each
18062 event may contain a payload, which usually relates to the event class,
18063 but for future proofing your code should be written to handle any
18064 payload for any event class.
18065 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
18067 there is no message buffer). Note that this message buffer can contain
18068 arbitrary 8 bit data, including NUL bytes.
18069 "array" and "array_len" is an array of 64 bit unsigned integers. At
18071 the moment this is only used for progress messages.
18072 EXAMPLE: CAPTURING LOG MESSAGES
18074 A working program demonstrating this can be found in
18075 examples/debug-logging.c in the source of libguestfs.
18076 One motivation for the generic event API was to allow GUI programs to
18078 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
18079 unconditionally to "stderr".
18080 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
18082 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
18083 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
18084 must capture error messages separately).
18085 Programs have to set up a callback to capture the classes of events of
18087 interest:
18088 int eh =
18090 guestfs_set_event_callback
18091 (g, message_callback,
18092 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
18093 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
18094 0, NULL) == -1)
18095 if (eh == -1) {
18096 // handle error in the usual way
18097 }
18098 The callback can then direct messages to the appropriate place. In
18100 this example, messages are directed to syslog:
18101 static void
18103 message_callback (
18104 guestfs_h *g,
18105 void *opaque,
18106 uint64_t event,
18107 int event_handle,
18108 int flags,
18109 const char *buf, size_t buf_len,
18110 const uint64_t *array, size_t array_len)
18111 {
18112 const int priority = LOG_USER|LOG_INFO;
18113 if (buf_len > 0)
18114 syslog (priority, "event 0x%lx: %s", event, buf);
18115 }
18116 LIBVIRT AUTHENTICATION
18118 Some libguestfs API calls can open libvirt connections. Currently the
18119 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
18120 backend has been selected. Libvirt connections may require
18121 authentication, for example if they need to access a remote server or
18122 to access root services from non-root. Libvirt authentication happens
18123 via a callback mechanism, see
18124 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
18125 You may provide libvirt authentication data by registering a callback
18127 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
18128 If no such event is registered, then libguestfs uses a libvirt function
18130 that provides command-line prompts ("virConnectAuthPtrDefault"). This
18131 is only suitable for command-line libguestfs programs.
18132 To provide authentication, first call
18134 "guestfs_set_libvirt_supported_credentials" with the list of
18135 credentials your program knows how to provide. Second, register a
18136 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
18137 will be called when libvirt is requesting authentication information.
18138 In the event handler, call "guestfs_get_libvirt_requested_credentials"
18140 to get a list of the credentials that libvirt is asking for. You then
18141 need to ask (eg. the user) for each credential, and call
18142 "guestfs_set_libvirt_requested_credential" with the answer. Note that
18143 for each credential, additional information may be available via the
18144 calls "guestfs_get_libvirt_requested_credential_prompt",
18145 "guestfs_get_libvirt_requested_credential_challenge" or
18146 "guestfs_get_libvirt_requested_credential_defresult".
18147 The example program below should make this clearer.
18149 There is also a more substantial working example program supplied with
18151 the libguestfs sources, called libvirt-auth.c.
18152 main ()
18154 {
18155 guestfs_h *g;
18156 char *creds[] = { "authname", "passphrase", NULL };
18157 int r, eh;
18158 g = guestfs_create ();
18160 if (!g) exit (EXIT_FAILURE);
18161 /* Tell libvirt what credentials the program supports. */
18163 r = guestfs_set_libvirt_supported_credentials (g, creds);
18164 if (r == -1)
18165 exit (EXIT_FAILURE);
18166 /* Set up the event handler. */
18168 eh = guestfs_set_event_callback (
18169 g, do_auth,
18170 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
18171 if (eh == -1)
18172 exit (EXIT_FAILURE);
18173 /* An example of a call that may ask for credentials. */
18175 r = guestfs_add_domain (
18176 g, "dom",
18177 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
18178 -1);
18179 if (r == -1)
18180 exit (EXIT_FAILURE);
18181 exit (EXIT_SUCCESS);
18183 }
18184 static void
18186 do_auth (guestfs_h *g,
18187 void *opaque,
18188 uint64_t event,
18189 int event_handle,
18190 int flags,
18191 const char *buf, size_t buf_len,
18192 const uint64_t *array, size_t array_len)
18193 {
18194 char **creds;
18195 size_t i;
18196 char *prompt;
18197 char *reply;
18198 size_t replylen;
18199 int r;
18200 // buf will be the libvirt URI. buf_len may be ignored.
18202 printf ("Authentication required for libvirt conn '%s'\n",
18203 buf);
18204 // Ask libguestfs what credentials libvirt is demanding.
18206 creds = guestfs_get_libvirt_requested_credentials (g);
18207 if (creds == NULL)
18208 exit (EXIT_FAILURE);
18209 // Now ask the user for answers.
18211 for (i = 0; creds[i] != NULL; ++i)
18212 {
18213 if (strcmp (creds[i], "authname") == 0 ||
18214 strcmp (creds[i], "passphrase") == 0)
18215 {
18216 prompt =
18217 guestfs_get_libvirt_requested_credential_prompt (g, i);
18218 if (prompt && strcmp (prompt, "") != 0)
18219 printf ("%s: ", prompt);
18220 free (prompt);
18221 // Some code here to ask for the credential.
18223 // ...
18224 // Put the reply in 'reply', length 'replylen' (bytes).
18225 r = guestfs_set_libvirt_requested_credential (g, i,
18227 reply, replylen);
18228 if (r == -1)
18229 exit (EXIT_FAILURE);
18230 }
18231 free (creds[i]);
18233 }
18234 free (creds);
18236 }
18237
18239 Some operations can be cancelled by the caller while they are in
18240 progress. Currently only operations that involve uploading or
18241 downloading data can be cancelled (technically: operations that have
18242 "FileIn" or "FileOut" parameters in the generator).
18243 To cancel the transfer, call "guestfs_user_cancel". For more
18245 information, read the description of "guestfs_user_cancel".
18246
18248 You can attach named pieces of private data to the libguestfs handle,
18249 fetch them by name, and walk over them, for the lifetime of the handle.
18250 This is called the private data area and is only available from the C
18251 API.
18252 To attach a named piece of data, use the following call:
18254 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18256 "key" is the name to associate with this data, and "data" is an
18258 arbitrary pointer (which can be "NULL"). Any previous item with the
18259 same key is overwritten.
18260 You can use any "key" string you want, but avoid keys beginning with an
18262 underscore character (libguestfs uses those for its own internal
18263 purposes, such as implementing language bindings). It is recommended
18264 that you prefix the key with some unique string to avoid collisions
18265 with other users.
18266 To retrieve the pointer, use:
18268 void *guestfs_get_private (guestfs_h *g, const char *key);
18270 This function returns "NULL" if either no data is found associated with
18272 "key", or if the user previously set the "key"’s "data" pointer to
18273 "NULL".
18274 Libguestfs does not try to look at or interpret the "data" pointer in
18276 any way. As far as libguestfs is concerned, it need not be a valid
18277 pointer at all. In particular, libguestfs does not try to free the
18278 data when the handle is closed. If the data must be freed, then the
18279 caller must either free it before calling "guestfs_close" or must set
18280 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18281 To walk over all entries, use these two functions:
18283 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18285 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18287 "guestfs_first_private" returns the first key, pointer pair ("first"
18289 does not have any particular meaning -- keys are not returned in any
18290 defined order). A pointer to the key is returned in *key_rtn and the
18291 corresponding data pointer is returned from the function. "NULL" is
18292 returned if there are no keys stored in the handle.
18293 "guestfs_next_private" returns the next key, pointer pair. The return
18295 value of this function is "NULL" if there are no further entries to
18296 return.
18297 Notes about walking over entries:
18299 • You must not call "guestfs_set_private" while walking over the
18301 entries.
18302 • The handle maintains an internal iterator which is reset when you
18304 call "guestfs_first_private". This internal iterator is
18305 invalidated when you call "guestfs_set_private".
18306 • If you have set the data pointer associated with a key to "NULL",
18308 ie:
18309 guestfs_set_private (g, key, NULL);
18311 then that "key" is not returned when walking.
18313 • *key_rtn is only valid until the next call to
18315 "guestfs_first_private", "guestfs_next_private" or
18316 "guestfs_set_private".
18317 The following example code shows how to print all keys and data
18319 pointers that are associated with the handle "g":
18320 const char *key;
18322 void *data = guestfs_first_private (g, &key);
18323 while (data != NULL)
18324 {
18325 printf ("key = %s, data = %p\n", key, data);
18326 data = guestfs_next_private (g, &key);
18327 }
18328 More commonly you are only interested in keys that begin with an
18330 application-specific prefix "foo_". Modify the loop like so:
18331 const char *key;
18333 void *data = guestfs_first_private (g, &key);
18334 while (data != NULL)
18335 {
18336 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18337 printf ("key = %s, data = %p\n", key, data);
18338 data = guestfs_next_private (g, &key);
18339 }
18340 If you need to modify keys while walking, then you have to jump back to
18342 the beginning of the loop. For example, to delete all keys prefixed
18343 with "foo_":
18344 const char *key;
18346 void *data;
18347 again:
18348 data = guestfs_first_private (g, &key);
18349 while (data != NULL)
18350 {
18351 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18352 {
18353 guestfs_set_private (g, key, NULL);
18354 /* note that 'key' pointer is now invalid, and so is
18355 the internal iterator */
18356 goto again;
18357 }
18358 data = guestfs_next_private (g, &key);
18359 }
18360 Note that the above loop is guaranteed to terminate because the keys
18362 are being deleted, but other manipulations of keys within the loop
18363 might not terminate unless you also maintain an indication of which
18364 keys have been visited.
18365
18367 The libguestfs C library can be probed using systemtap or DTrace. This
18368 is true of any library, not just libguestfs. However libguestfs also
18369 contains static markers to help in probing internal operations.
18370 You can list all the static markers by doing:
18372 stap -l 'process("/usr/lib*/libguestfs.so.0")
18374 .provider("guestfs").mark("*")'
18375 Note: These static markers are not part of the stable API and may
18377 change in future versions.
18378 SYSTEMTAP SCRIPT EXAMPLE
18380 This script contains examples of displaying both the static markers and
18381 some ordinary C entry points:
18382 global last;
18384 function display_time () {
18386 now = gettimeofday_us ();
18387 delta = 0;
18388 if (last > 0)
18389 delta = now - last;
18390 last = now;
18391 printf ("%d (+%d):", now, delta);
18393 }
18394 probe begin {
18396 last = 0;
18397 printf ("ready\n");
18398 }
18399 /* Display all calls to static markers. */
18401 probe process("/usr/lib*/libguestfs.so.0")
18402 .provider("guestfs").mark("*") ? {
18403 display_time();
18404 printf ("\t%s %s\n", $$name, $$parms);
18405 }
18406 /* Display all calls to guestfs_mkfs* functions. */
18408 probe process("/usr/lib*/libguestfs.so.0")
18409 .function("guestfs_mkfs*") ? {
18410 display_time();
18411 printf ("\t%s %s\n", probefunc(), $$parms);
18412 }
18413 The script above can be saved to test.stap and run using the stap(1)
18415 program. Note that you either have to be root, or you have to add
18416 yourself to several special stap groups. Consult the systemtap
18417 documentation for more information.
18418 # stap /tmp/test.stap
18420 ready
18421 In another terminal, run a guestfish command such as this:
18423 guestfish -N fs
18425 In the first terminal, stap trace output similar to this is shown:
18427 1318248056692655 (+0): launch_start
18429 1318248056692850 (+195): launch_build_appliance_start
18430 1318248056818285 (+125435): launch_build_appliance_end
18431 1318248056838059 (+19774): launch_run_qemu
18432 1318248061071167 (+4233108): launch_end
18433 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
18434
18436 Since April 2010, libguestfs has started to make separate development
18437 and stable releases, along with corresponding branches in our git
18438 repository. These separate releases can be identified by version
18439 number:
18440 even numbers for stable: 1.2.x, 1.4.x, ...
18442 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18443 |
18444 v
18445 1 . 3 . 5
18446 ^ ^
18447 | |
18448 | `-------- sub-version
18449 |
18450 `------ always '1' because we don't change the ABI
18451 Thus "1.3.5" is the 5th update to the development branch "1.3".
18453 As time passes we cherry pick fixes from the development branch and
18455 backport those into the stable branch, the effect being that the stable
18456 branch should get more stable and less buggy over time. So the stable
18457 releases are ideal for people who don't need new features but would
18458 just like the software to work.
18459 Our criteria for backporting changes are:
18461 • Documentation changes which don’t affect any code are backported
18463 unless the documentation refers to a future feature which is not in
18464 stable.
18465 • Bug fixes which are not controversial, fix obvious problems, and
18467 have been well tested are backported.
18468 • Simple rearrangements of code which shouldn't affect how it works
18470 get backported. This is so that the code in the two branches
18471 doesn't get too far out of step, allowing us to backport future
18472 fixes more easily.
18473 • We don’t backport new features, new APIs, new tools etc, except in
18475 one exceptional case: the new feature is required in order to
18476 implement an important bug fix.
18477 A new stable branch starts when we think the new features in
18479 development are substantial and compelling enough over the current
18480 stable branch to warrant it. When that happens we create new stable
18481 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18482 oh release won't necessarily be so stable at this point, but by
18483 backporting fixes from development, that branch will stabilize over
18484 time.
18485
18487 PROTOCOL LIMITS
18488 Internally libguestfs uses a message-based protocol to pass API calls
18489 and their responses to and from a small "appliance" (see
18490 guestfs-internals(1) for plenty more detail about this). The maximum
18491 message size used by the protocol is slightly less than 4 MB. For some
18492 API calls you may need to be aware of this limit. The API calls which
18493 may be affected are individually documented, with a link back to this
18494 section of the documentation.
18495 In libguestfs < 1.19.32, several calls had to encode either their
18497 entire argument list or their entire return value (or sometimes both)
18498 in a single protocol message, and this gave them an arbitrary
18499 limitation on how much data they could handle. For example,
18500 "guestfs_cat" could only download a file if it was less than around 4
18501 MB in size. In later versions of libguestfs, some of these limits have
18502 been removed. The APIs which were previously limited but are now
18503 unlimited (except perhaps by available memory) are listed below. To
18504 find out if a specific API is subject to protocol limits, check for the
18505 warning in the API documentation which links to this section, and
18506 remember to check the version of the documentation that matches the
18507 version of libguestfs you are using.
18508 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18510 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18511 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18512 "guestfs_ls".
18513 See also "UPLOADING" and "DOWNLOADING" for further information about
18515 copying large amounts of data into or out of a filesystem.
18516 MAXIMUM NUMBER OF DISKS
18518 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18519 may be added by calling "guestfs_max_disks". In earlier versions of
18520 libguestfs (ie. where this call is not available) you should assume the
18521 maximum is 25.
18522 The rest of this section covers implementation details, which could
18524 change in future.
18525 When using virtio-scsi disks (the default if available in qemu) the
18527 current limit is 255 disks. When using virtio-blk (the old default)
18528 the limit is around 27 disks, but may vary according to implementation
18529 details and whether the network is enabled.
18530 Virtio-scsi as used by libguestfs is configured to use one target per
18532 disk, and 256 targets are available.
18533 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18535 31 slots, but some of these are used for other purposes.
18536 One virtual disk is used by libguestfs internally.
18538 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18540 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18541 the limit was 25. This has been fixed in more recent versions.
18542 In libguestfs ≥ 1.20 it is possible to hot plug disks. See
18544 "HOTPLUGGING".
18545 MAXIMUM NUMBER OF PARTITIONS PER DISK
18547 Virtio limits the maximum number of partitions per disk to 15.
18548 This is because it reserves 4 bits for the minor device number (thus
18550 /dev/vda, and /dev/vda1 through /dev/vda15).
18551 If you attach a disk with more than 15 partitions, the extra partitions
18553 are ignored by libguestfs.
18554 MAXIMUM SIZE OF A DISK
18556 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18557 We have tested block devices up to 1 exabyte (2**60 or
18559 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18560 host filesystem.
18561 Although libguestfs probably does not impose any limit, the underlying
18563 host storage will. If you store disk images on a host ext4 filesystem,
18564 then the maximum size will be limited by the maximum ext4 file size
18565 (currently 16 TB). If you store disk images as host logical volumes
18566 then you are limited by the maximum size of an LV.
18567 For the hugest disk image files, we recommend using XFS on the host for
18569 storage.
18570 MAXIMUM SIZE OF A PARTITION
18572 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18573 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18574 address a partition located beyond 2 TB on the disk.
18575 It is recommended that you use GPT partitions on disks which are larger
18577 than this size. GPT uses 64 bit sector numbers and so can address
18578 partitions which are theoretically larger than the largest disk we
18579 could support.
18580 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18582 This depends on the filesystem type. libguestfs itself does not impose
18583 any known limit. Consult Wikipedia or the filesystem documentation to
18584 find out what these limits are.
18585 MAXIMUM UPLOAD AND DOWNLOAD
18587 The API functions "guestfs_upload", "guestfs_download",
18588 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18589 uploads and downloads.
18590 INSPECTION LIMITS
18592 The inspection code has several arbitrary limits on things like the
18593 size of Windows Registry hive it will read, and the length of product
18594 name. These are intended to stop a malicious guest from consuming
18595 arbitrary amounts of memory and disk space on the host, and should not
18596 be reached in practice. See the source code for more information.
18597
18599 Some of the tools support a --machine-readable option, which is
18600 generally used to make the output more machine friendly, for easier
18601 parsing for example. By default, this output goes to stdout.
18602 When using the --machine-readable option, the progress, information,
18604 warning, and error messages are also printed in JSON format for easier
18605 log tracking. Thus, it is highly recommended to redirect the machine-
18606 readable output to a different stream. The format of these JSON
18607 messages is like the following (actually printed within a single line,
18608 below it is indented for readability):
18609 {
18611 "message": "Finishing off",
18612 "timestamp": "2019-03-22T14:46:49.067294446+01:00",
18613 "type": "message"
18614 }
18615 "type" can be: "message" for progress messages, "info" for information
18617 messages, "warning" for warning messages, and "error" for error
18618 message. "timestamp" is the RFC 3339 timestamp of the message.
18619 In addition to that, a subset of these tools support an extra string
18621 passed to the --machine-readable option: this string specifies where
18622 the machine-readable output will go.
18623 The possible values are:
18625 fd:fd
18627 The output goes to the specified fd, which is a file descriptor
18628 already opened for writing.
18629 file:filename
18631 The output goes to the specified filename.
18632 stream:stdout
18634 The output goes to stdout. This is basically the same as the
18635 default behaviour of --machine-readable with no parameter, although
18636 stdout as output is specified explicitly.
18637 stream:stderr
18639 The output goes to stderr.
18640
18642 LIBGUESTFS_APPEND
18643 Pass additional options to the guest kernel.
18644 LIBGUESTFS_ATTACH_METHOD
18646 This is the old way to set "LIBGUESTFS_BACKEND".
18647 LIBGUESTFS_BACKEND
18649 Choose the default way to create the appliance. See
18650 "guestfs_set_backend" and "BACKEND".
18651 LIBGUESTFS_BACKEND_SETTINGS
18653 A colon-separated list of backend-specific settings. See
18654 "BACKEND", "BACKEND SETTINGS".
18655 LIBGUESTFS_CACHEDIR
18657 The location where libguestfs will cache its appliance, when using
18658 a supermin appliance. The appliance is cached and shared between
18659 all handles which have the same effective user ID.
18660 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18662 "TMPDIR" is not set, then /var/tmp is used.
18663 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18665 LIBGUESTFS_DEBUG
18667 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18668 same effect as calling "guestfs_set_verbose (g, 1)".
18669 LIBGUESTFS_HV
18671 Set the default hypervisor (usually qemu) binary that libguestfs
18672 uses. If not set, then the qemu which was found at compile time by
18673 the configure script is used.
18674 See also "QEMU WRAPPERS" above.
18676 LIBGUESTFS_MEMSIZE
18678 Set the memory allocated to the qemu process, in megabytes. For
18679 example:
18680 LIBGUESTFS_MEMSIZE=700
18682 LIBGUESTFS_PATH
18684 Set the path that libguestfs uses to search for a supermin
18685 appliance. See the discussion of paths in section "PATH" above.
18686 LIBGUESTFS_QEMU
18688 This is the old way to set "LIBGUESTFS_HV".
18689 LIBGUESTFS_TMPDIR
18691 The location where libguestfs will store temporary files used by
18692 each handle.
18693 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18695 "TMPDIR" is not set, then /tmp is used.
18696 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18698 LIBGUESTFS_TRACE
18700 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18701 same effect as calling "guestfs_set_trace (g, 1)".
18702 PATH
18704 Libguestfs may run some external programs, and relies on $PATH
18705 being set to a reasonable value. If using the libvirt backend,
18706 libvirt will not work at all unless $PATH contains the path of
18707 qemu/KVM. Note that PHP by default removes $PATH from the
18708 environment which tends to break everything.
18709 SUPERMIN_KERNEL
18711 SUPERMIN_KERNEL_VERSION
18712 SUPERMIN_MODULES
18713 These three environment variables allow the kernel that libguestfs
18714 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18715 set, then the most recent host kernel is chosen. For more
18716 information about kernel selection, see supermin(1).
18717 TMPDIR
18719 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18720 XDG_RUNTIME_DIR
18722 This directory represents a user-specific directory for storing
18723 non-essential runtime files.
18724 If it is set, then is used to store temporary sockets. Otherwise,
18726 /tmp is used.
18727 See also "get-sockdir",
18729 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18730
18732 Examples written in C: guestfs-examples(3).
18733 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18735 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18736 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18737 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18739 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18740 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18741 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18742 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18743 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18744 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18745 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18746 virt-win-reg(1).
18747 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18749 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18750 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18751 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18752 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18754 sd-journal(3).
18755 Website: http://libguestfs.org/
18757 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18759 disktype(1).
18760
18762 Richard W.M. Jones ("rjones at redhat dot com")
18763
18765 Copyright (C) 2009-2020 Red Hat Inc.
18766
18768 This library is free software; you can redistribute it and/or modify it
18769 under the terms of the GNU Lesser General Public License as published
18770 by the Free Software Foundation; either version 2 of the License, or
18771 (at your option) any later version.
18772 This library is distributed in the hope that it will be useful, but
18774 WITHOUT ANY WARRANTY; without even the implied warranty of
18775 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18776 Lesser General Public License for more details.
18777 You should have received a copy of the GNU Lesser General Public
18779 License along with this library; if not, write to the Free Software
18780 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18781 02110-1301 USA
18782
18784 To get a list of bugs against libguestfs, use this link:
18785 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18786 To report a new bug against libguestfs, use this link:
18788 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18789 When reporting a bug, please supply:
18791 • The version of libguestfs.
18793 • Where you got libguestfs (eg. which Linux distro, compiled from
18795 source, etc)
18796 • Describe the bug accurately and give a way to reproduce it.
18798 • Run libguestfs-test-tool(1) and paste the complete, unedited output
18800 into the bug report.
18801libguestfs-1.45.4 2021-04-03 guestfs(3)