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.
513 Use "guestfs_vfs_type" to identify LUKS-encrypted block devices (it
515 returns the string "crypto_LUKS").
516 Then open these devices by calling "guestfs_luks_open". Obviously you
518 will require the passphrase!
519 Opening a LUKS device creates a new device mapper device called
521 /dev/mapper/mapname (where "mapname" is the string you supply to
522 "guestfs_luks_open"). Reads and writes to this mapper device are
523 decrypted from and encrypted to the underlying block device
524 respectively.
525 LVM volume groups on the device can be made visible by calling
527 "guestfs_vgscan" followed by "guestfs_vg_activate_all". The logical
528 volume(s) can now be mounted in the usual way.
529 Use the reverse process to close a LUKS device. Unmount any logical
531 volumes on it, deactivate the volume groups by calling
532 "guestfs_vg_activate (g, 0, ["/dev/VG"])". Then close the mapper
533 device by calling "guestfs_luks_close" on the /dev/mapper/mapname
534 device (not the underlying encrypted block device).
535 MOUNT LOCAL
537 In libguestfs ≥ 1.18, it is possible to mount the libguestfs filesystem
538 on a local directory and access it using ordinary POSIX calls and
539 programs.
540 Availability of this is subject to a number of restrictions: it
542 requires FUSE (the Filesystem in USErspace), and libfuse must also have
543 been available when libguestfs was compiled. FUSE may require that a
544 kernel module is loaded, and it may be necessary to add the current
545 user to a special "fuse" group. See the documentation for your
546 distribution and http://fuse.sf.net for further information.
547 The call to mount the libguestfs filesystem on a local directory is
549 "guestfs_mount_local" (q.v.) followed by "guestfs_mount_local_run".
550 The latter does not return until you unmount the filesystem. The
551 reason is that the call enters the FUSE main loop and processes kernel
552 requests, turning them into libguestfs calls. An alternative design
553 would have been to create a background thread to do this, but
554 libguestfs doesn't require pthreads. This way is also more flexible:
555 for example the user can create another thread for
556 "guestfs_mount_local_run".
557 "guestfs_mount_local" needs a certain amount of time to set up the
559 mountpoint. The mountpoint is not ready to use until the call returns.
560 At this point, accesses to the filesystem will block until the main
561 loop is entered (ie. "guestfs_mount_local_run"). So if you need to
562 start another process to access the filesystem, put the fork between
563 "guestfs_mount_local" and "guestfs_mount_local_run".
564 MOUNT LOCAL COMPATIBILITY
566 Since local mounting was only added in libguestfs 1.18, and may not be
568 available even in these builds, you should consider writing code so
569 that it doesn't depend on this feature, and can fall back to using
570 libguestfs file system calls.
571 If libguestfs was compiled without support for "guestfs_mount_local"
573 then calling it will return an error with errno set to "ENOTSUP" (see
574 "guestfs_last_errno").
575 MOUNT LOCAL PERFORMANCE
577 Libguestfs on top of FUSE performs quite poorly. For best performance
579 do not use it. Use ordinary libguestfs filesystem calls, upload,
580 download etc. instead.
581 HOTPLUGGING
583 In libguestfs ≥ 1.20, you may add drives and remove after calling
584 "guestfs_launch". There are some restrictions, see below. This is
585 called hotplugging.
586 Only a subset of the backends support hotplugging (currently only the
588 libvirt backend has support). It also requires that you use libvirt ≥
589 0.10.3 and qemu ≥ 1.2.
590 To hot-add a disk, simply call "guestfs_add_drive_opts" after
592 "guestfs_launch". It is mandatory to specify the "label" parameter so
593 that the newly added disk has a predictable name. For example:
594 if (guestfs_launch (g) == -1)
596 error ("launch failed");
597 if (guestfs_add_drive_opts (g, filename,
599 GUESTFS_ADD_DRIVE_OPTS_LABEL, "newdisk",
600 -1) == -1)
601 error ("hot-add of disk failed");
602 if (guestfs_part_disk ("/dev/disk/guestfs/newdisk", "mbr") == -1)
604 error ("partitioning of hot-added disk failed");
605 To hot-remove a disk, call "guestfs_remove_drive". You can call this
607 before or after "guestfs_launch". You can only remove disks that were
608 previously added with a label.
609 Backends that support hotplugging do not require that you add ≥ 1 disk
611 before calling launch. When hotplugging is supported you don't need to
612 add any disks.
613 REMOTE STORAGE
615 CEPH
616 Libguestfs can access Ceph (librbd/RBD) disks.
618 To do this, set the optional "protocol" and "server" parameters of
620 "guestfs_add_drive_opts" like this:
621 char **servers = { "ceph1.example.org:3000", /* ... */, NULL };
623 guestfs_add_drive_opts (g, "pool/image",
624 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
625 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "rbd",
626 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
627 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "rbduser",
628 GUESTFS_ADD_DRIVE_OPTS_SECRET, "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
629 -1);
630 "servers" (the "server" parameter) is a list of one or more Ceph
632 servers. The server string is documented in "guestfs_add_drive_opts".
633 The "username" and "secret" parameters are also optional, and if not
634 given, then no authentication will be used.
635 NETWORK BLOCK DEVICE
637 Libguestfs can access Network Block Device (NBD) disks remotely.
639 To do this, set the optional "protocol" and "server" parameters of
641 "guestfs_add_drive_opts" like this:
642 char **server = { "nbd.example.org:3000", NULL };
644 guestfs_add_drive_opts (g, "" /* export name - see below */,
645 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
646 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
647 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
648 -1);
649 Notes:
651 · "server" is in fact a list of servers. For NBD you must always
653 supply a list with a single element. (Other remote protocols
654 require zero or more than one server, hence the requirement for
655 this parameter to be a list).
656 · The "server" string is documented in "guestfs_add_drive_opts". To
658 connect to a local qemu-nbd instance over a Unix domain socket, use
659 "unix:/path/to/socket".
660 · The "filename" parameter is the NBD export name. Use an empty
662 string to mean the default export. Many NBD servers, including
663 qemu-nbd, do not support export names.
664 · If using qemu-nbd as your server, you should always specify the
666 "-t" option. The reason is that libguestfs may open several
667 connections to the server.
668 · The libvirt backend requires that you set the "format" parameter of
670 "guestfs_add_drive_opts" accurately when you use writable NBD
671 disks.
672 · The libvirt backend has a bug that stops Unix domain socket
674 connections from working:
675 https://bugzilla.redhat.com/show_bug.cgi?id=922888
676 · The direct backend does not support readonly connections because of
678 a bug in qemu: https://bugs.launchpad.net/qemu/+bug/1155677
679 INSPECTION
681 Libguestfs has APIs for inspecting an unknown disk image to find out if
682 it contains operating systems, an install CD or a live CD.
683 Add all disks belonging to the unknown virtual machine and call
685 "guestfs_launch" in the usual way.
686 Then call "guestfs_inspect_os". This function uses other libguestfs
688 calls and certain heuristics, and returns a list of operating systems
689 that were found. An empty list means none were found. A single
690 element is the root filesystem of the operating system. For dual- or
691 multi-boot guests, multiple roots can be returned, each one
692 corresponding to a separate operating system. (Multi-boot virtual
693 machines are extremely rare in the world of virtualization, but since
694 this scenario can happen, we have built libguestfs to deal with it.)
695 For each root, you can then call various "guestfs_inspect_get_*"
697 functions to get additional details about that operating system. For
698 example, call "guestfs_inspect_get_type" to return the string "windows"
699 or "linux" for Windows and Linux-based operating systems respectively.
700 Un*x-like and Linux-based operating systems usually consist of several
702 filesystems which are mounted at boot time (for example, a separate
703 boot partition mounted on /boot). The inspection rules are able to
704 detect how filesystems correspond to mount points. Call
705 "guestfs_inspect_get_mountpoints" to get this mapping. It might return
706 a hash table like this example:
707 /boot => /dev/sda1
709 / => /dev/vg_guest/lv_root
710 /usr => /dev/vg_guest/lv_usr
711 The caller can then make calls to "guestfs_mount" to mount the
713 filesystems as suggested.
714 Be careful to mount filesystems in the right order (eg. / before /usr).
716 Sorting the keys of the hash by length, shortest first, should work.
717 Inspection currently only works for some common operating systems.
719 Contributors are welcome to send patches for other operating systems
720 that we currently cannot detect.
721 Encrypted disks must be opened before inspection. See "ENCRYPTED
723 DISKS" for more details. The "guestfs_inspect_os" function just
724 ignores any encrypted devices.
725 A note on the implementation: The call "guestfs_inspect_os" performs
727 inspection and caches the results in the guest handle. Subsequent
728 calls to "guestfs_inspect_get_*" return this cached information, but do
729 not re-read the disks. If you change the content of the guest disks,
730 you can redo inspection by calling "guestfs_inspect_os" again.
731 ("guestfs_inspect_list_applications2" works a little differently from
732 the other calls and does read the disks. See documentation for that
733 function for details).
734 INSPECTING INSTALL DISKS
736 Libguestfs (since 1.9.4) can detect some install disks, install CDs,
738 live CDs and more.
739 Further information is available about the operating system that can be
741 installed using the regular inspection APIs like
742 "guestfs_inspect_get_product_name", "guestfs_inspect_get_major_version"
743 etc.
744 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
746 Libguestfs can mount NTFS partitions. It does this using the
747 http://www.ntfs-3g.org/ driver.
748 DRIVE LETTERS AND PATHS
750 DOS and Windows still use drive letters, and the filesystems are always
752 treated as case insensitive by Windows itself, and therefore you might
753 find a Windows configuration file referring to a path like
754 "c:\windows\system32". When the filesystem is mounted in libguestfs,
755 that directory might be referred to as /WINDOWS/System32.
756 Drive letter mappings can be found using inspection (see "INSPECTION"
758 and "guestfs_inspect_get_drive_mappings")
759 Dealing with separator characters (backslash vs forward slash) is
761 outside the scope of libguestfs, but usually a simple character
762 replacement will work.
763 To resolve the case insensitivity of paths, call
765 "guestfs_case_sensitive_path".
766 LONG FILENAMES ON NTFS
768 NTFS supports filenames up to 255 characters long. "Character" means a
770 2 byte UTF-16 codepoint which can encode the most common Unicode
771 codepoints.
772 Most Linux filesystems support filenames up to 255 bytes. This means
774 you may get an error:
775 File name too long
777 when you copy a file from NTFS to a Linux filesystem if the name, when
779 reencoded as UTF-8, would exceed 255 bytes in length.
780 This will most often happen when using non-ASCII names that are longer
782 than ~127 characters (eg. Greek, Cyrillic) or longer than ~85
783 characters (Asian languages).
784 A workaround is not to try to store such long filenames on Linux native
786 filesystems. Since the tar(1) format can store unlimited length
787 filenames, keep the files in a tarball.
788 ACCESSING THE WINDOWS REGISTRY
790 Libguestfs also provides some help for decoding Windows Registry "hive"
792 files, through a separate C library called hivex(3).
793 Before libguestfs 1.19.35 you had to download the hive file, operate on
795 it locally using hivex, and upload it again. Since this version, we
796 have included the major hivex APIs directly in the libguestfs API (see
797 "guestfs_hivex_open"). This means that if you have opened a Windows
798 guest, you can read and write the registry directly.
799 See also virt-win-reg(1).
801 SYMLINKS ON NTFS-3G FILESYSTEMS
803 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
805 provide something which looks like a Linux symlink. The way it tries
806 to do the rewriting is described here:
807 http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
809 The essential problem is that ntfs-3g simply does not have enough
811 information to do a correct job. NTFS links can contain drive letters
812 and references to external device GUIDs that ntfs-3g has no way of
813 resolving. It is almost certainly the case that libguestfs callers
814 should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
815 NTFS volumes).
816 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
818 "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
819 attribute, and read the raw reparse data from that (you can find the
820 format documented in various places around the web).
821 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
823 There are other useful extended attributes that can be read from
825 ntfs-3g filesystems (using "guestfs_getxattr"). See:
826 http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
828 WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP
830 Windows guests which have been hibernated (instead of fully shut down)
832 cannot be mounted. This is a limitation of ntfs-3g. You will see an
833 error like this:
834 The disk contains an unclean file system (0, 0).
836 Metadata kept in Windows cache, refused to mount.
837 Failed to mount '/dev/sda2': Operation not permitted
838 The NTFS partition is in an unsafe state. Please resume
839 and shutdown Windows fully (no hibernation or fast
840 restarting), or mount the volume read-only with the
841 'ro' mount option.
842 In Windows 8, the shutdown button does not shut down the guest at all.
844 Instead it usually hibernates the guest. This is known as "fast
845 startup".
846 Some suggested workarounds are:
848 · Mount read-only (eg. "guestfs_mount_ro").
850 · On Windows 8, turn off fast startup. It is in the Control Panel →
852 Power Options → Choose what the power buttons do → Change settings
853 that are currently unavailable → Turn on fast startup.
854 · On Windows 7 and earlier, shut the guest off properly instead of
856 hibernating it.
857 RESIZE2FS ERRORS
859 The "guestfs_resize2fs", "guestfs_resize2fs_size" and
860 "guestfs_resize2fs_M" calls are used to resize ext2/3/4 filesystems.
861 The underlying program (resize2fs(8)) requires that the filesystem is
863 clean and recently fsck'd before you can resize it. Also, if the
864 resize operation fails for some reason, then you had to call fsck the
865 filesystem again to fix it.
866 In libguestfs "lt" 1.17.14, you usually had to call "guestfs_e2fsck_f"
868 before the resize. However, in "ge" 1.17.14, e2fsck(8) is called
869 automatically before the resize, so you no longer need to do this.
870 The resize2fs(8) program can still fail, in which case it prints an
872 error message similar to:
873 Please run 'e2fsck -fy <device>' to fix the filesystem
875 after the aborted resize operation.
876 You can do this by calling "guestfs_e2fsck" with the "forceall" option.
878 However in the context of disk images, it is usually better to avoid
879 this situation, eg. by rolling back to an earlier snapshot, or by
880 copying and resizing and on failure going back to the original.
881 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
883 Although we don’t want to discourage you from using the C API, we will
884 mention here that the same API is also available in other languages.
885 The API is broadly identical in all supported languages. This means
887 that the C call "guestfs_add_drive_ro(g,file)" is
888 "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
889 and "g#add_drive_ro file" in OCaml. In other words, a straightforward,
890 predictable isomorphism between each language.
891 Error messages are automatically transformed into exceptions if the
893 language supports it.
894 We don’t try to "object orientify" parts of the API in OO languages,
896 although contributors are welcome to write higher level APIs above what
897 we provide in their favourite languages if they wish.
898 C++ You can use the guestfs.h header file from C++ programs. The C++
900 API is identical to the C API. C++ classes and exceptions are not
901 used.
902 C# The C# bindings are highly experimental. Please read the warnings
904 at the top of csharp/Libguestfs.cs.
905 Erlang
907 See guestfs-erlang(3).
908 GObject
910 Experimental GObject bindings (with GObject Introspection support)
911 are available.
912 See guestfs-gobject(3).
914 Go See guestfs-golang(3).
916 Haskell
918 This language binding is working but incomplete:
919 · Functions with optional arguments are not bound. Implementing
921 optional arguments in Haskell seems to be very complex.
922 · Events are not bound.
924 · Functions with the following return types are not bound:
926 · Any function returning a struct.
928 · Any function returning a list of structs.
930 · A few functions that return fixed length buffers
932 (specifically ones declared "RBufferOut" in the generator).
933 · A tiny number of obscure functions that return constant
935 strings (specifically ones declared "RConstOptString" in
936 the generator).
937 Java
939 Full documentation is contained in the Javadoc which is distributed
940 with libguestfs. For examples, see guestfs-java(3).
941 Lua See guestfs-lua(3).
943 OCaml
945 See guestfs-ocaml(3).
946 Perl
948 See guestfs-perl(3) and Sys::Guestfs(3).
949 PHP For documentation see "README-PHP" supplied with libguestfs sources
951 or in the php-libguestfs package for your distribution.
952 The PHP binding only works correctly on 64 bit machines.
954 Python
956 See guestfs-python(3).
957 Ruby
959 See guestfs-ruby(3).
960 For JRuby, use the Java bindings.
962 shell scripts
964 See guestfish(1).
965 LIBGUESTFS GOTCHAS
967 http://en.wikipedia.org/wiki/Gotcha_(programming): "A feature of a
968 system [...] that works in the way it is documented but is
969 counterintuitive and almost invites mistakes."
970 Since we developed libguestfs and the associated tools, there are
972 several things we would have designed differently, but are now stuck
973 with for backwards compatibility or other reasons. If there is ever a
974 libguestfs 2.0 release, you can expect these to change. Beware of
975 them.
976 Read-only should be the default.
978 In guestfish(3), --ro should be the default, and you should have to
979 specify --rw if you want to make changes to the image.
980 This would reduce the potential to corrupt live VM images.
982 Note that many filesystems change the disk when you just mount and
984 unmount, even if you didn't perform any writes. You need to use
985 "guestfs_add_drive_ro" to guarantee that the disk is not changed.
986 guestfish command line is hard to use.
988 guestfish disk.img doesn't do what people expect (open disk.img for
989 examination). It tries to run a guestfish command disk.img which
990 doesn't exist, so it fails. In earlier versions of guestfish the
991 error message was also unintuitive, but we have corrected this
992 since. Like the Bourne shell, we should have used "guestfish -c
993 command" to run commands.
994 guestfish megabyte modifiers don’t work right on all commands
996 In recent guestfish you can use "1M" to mean 1 megabyte (and
997 similarly for other modifiers). What guestfish actually does is to
998 multiply the number part by the modifier part and pass the result
999 to the C API. However this doesn't work for a few APIs which
1000 aren't expecting bytes, but are already expecting some other unit
1001 (eg. megabytes).
1002 The most common is "guestfs_lvcreate". The guestfish command:
1004 lvcreate LV VG 100M
1006 does not do what you might expect. Instead because
1008 "guestfs_lvcreate" is already expecting megabytes, this tries to
1009 create a 100 terabyte (100 megabytes * megabytes) logical volume.
1010 The error message you get from this is also a little obscure.
1011 This could be fixed in the generator by specially marking
1013 parameters and return values which take bytes or other units.
1014 Ambiguity between devices and paths
1016 There is a subtle ambiguity in the API between a device name (eg.
1017 /dev/sdb2) and a similar pathname. A file might just happen to be
1018 called "sdb2" in the directory /dev (consider some non-Unix VM
1019 image).
1020 In the current API we usually resolve this ambiguity by having two
1022 separate calls, for example "guestfs_checksum" and
1023 "guestfs_checksum_device". Some API calls are ambiguous and
1024 (incorrectly) resolve the problem by detecting if the path supplied
1025 begins with /dev/.
1026 To avoid both the ambiguity and the need to duplicate some calls,
1028 we could make paths/devices into structured names. One way to do
1029 this would be to use a notation like grub ("hd(0,0)"), although
1030 nobody really likes this aspect of grub. Another way would be to
1031 use a structured type, equivalent to this OCaml type:
1032 type path = Path of string | Device of int | Partition of int * int
1034 which would allow you to pass arguments like:
1036 Path "/foo/bar"
1038 Device 1 (* /dev/sdb, or perhaps /dev/sda *)
1039 Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
1040 Path "/dev/sdb2" (* not a device *)
1041 As you can see there are still problems to resolve even with this
1043 representation. Also consider how it might work in guestfish.
1044 KEYS AND PASSPHRASES
1046 Certain libguestfs calls take a parameter that contains sensitive key
1047 material, passed in as a C string.
1048 In the future we would hope to change the libguestfs implementation so
1050 that keys are mlock(2)-ed into physical RAM, and thus can never end up
1051 in swap. However this is not done at the moment, because of the
1052 complexity of such an implementation.
1053 Therefore you should be aware that any key parameter you pass to
1055 libguestfs might end up being written out to the swap partition. If
1056 this is a concern, scrub the swap partition or don't use libguestfs on
1057 encrypted devices.
1058 MULTIPLE HANDLES AND MULTIPLE THREADS
1060 All high-level libguestfs actions are synchronous. If you want to use
1061 libguestfs asynchronously then you must create a thread.
1062 Threads in libguestfs ≥ 1.38
1064 In libguestfs ≥ 1.38, each handle ("guestfs_h") contains a lock which
1066 is acquired automatically when you call a libguestfs function. The
1067 practical effect of this is you can call libguestfs functions with the
1068 same handle from multiple threads without needing to do any locking.
1069 Also in libguestfs ≥ 1.38, the last error on the handle
1071 ("guestfs_last_error", "guestfs_last_errno") is stored in thread-local
1072 storage, so it is safe to write code like:
1073 if (guestfs_add_drive_ro (g, drive) == -1)
1075 fprintf (stderr, "error was: %s\n", guestfs_last_error (g));
1076 even when other threads may be concurrently using the same handle "g".
1078 Threads in libguestfs < 1.38
1080 In libguestfs < 1.38, you must use the handle only from a single
1082 thread. Either use the handle exclusively from one thread, or provide
1083 your own mutex so that two threads cannot issue calls on the same
1084 handle at the same time. Even apparently innocent functions like
1085 "guestfs_get_trace" are not safe to be called from multiple threads
1086 without a mutex in libguestfs < 1.38.
1087 Use "guestfs_set_identifier" to make it simpler to identify threads in
1089 trace output.
1090 PATH
1092 Libguestfs needs a supermin appliance, which it finds by looking along
1093 an internal path.
1094 By default it looks for these in the directory "$libdir/guestfs" (eg.
1096 /usr/local/lib/guestfs or /usr/lib64/guestfs).
1097 Use "guestfs_set_path" or set the environment variable
1099 "LIBGUESTFS_PATH" to change the directories that libguestfs will search
1100 in. The value is a colon-separated list of paths. The current
1101 directory is not searched unless the path contains an empty element or
1102 ".". For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
1103 current directory and then /usr/lib/guestfs.
1104 QEMU WRAPPERS
1106 If you want to compile your own qemu, run qemu from a non-standard
1107 location, or pass extra arguments to qemu, then you can write a shell-
1108 script wrapper around qemu.
1109 There is one important rule to remember: you must "exec qemu" as the
1111 last command in the shell script (so that qemu replaces the shell and
1112 becomes the direct child of the libguestfs-using program). If you
1113 don't do this, then the qemu process won't be cleaned up correctly.
1114 Here is an example of a wrapper, where I have built my own copy of qemu
1116 from source:
1117 #!/bin/sh -
1119 qemudir=/home/rjones/d/qemu
1120 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1121 Save this script as /tmp/qemu.wrapper (or wherever), "chmod +x", and
1123 then use it by setting the LIBGUESTFS_HV environment variable. For
1124 example:
1125 LIBGUESTFS_HV=/tmp/qemu.wrapper guestfish
1127 Note that libguestfs also calls qemu with the -help and -version
1129 options in order to determine features.
1130 Wrappers can also be used to edit the options passed to qemu. In the
1132 following example, the "-machine ..." option ("-machine" and the
1133 following argument) are removed from the command line and replaced with
1134 "-machine pc,accel=tcg". The while loop iterates over the options
1135 until it finds the right one to remove, putting the remaining options
1136 into the "args" array.
1137 #!/bin/bash -
1139 i=0
1141 while [ $# -gt 0 ]; do
1142 case "$1" in
1143 -machine)
1144 shift 2;;
1145 *)
1146 args[i]="$1"
1147 (( i++ ))
1148 shift ;;
1149 esac
1150 done
1151 exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
1153 BACKEND
1155 The backend (previously known as the "attach method") controls how
1156 libguestfs creates and/or connects to the backend daemon, eg. by
1157 starting qemu directly, or using libvirt to manage an appliance,
1158 running User-Mode Linux, or connecting to an already running daemon.
1159 You can set the backend by calling "guestfs_set_backend", or by setting
1161 the environment variable "LIBGUESTFS_BACKEND".
1162 Possible backends are described below:
1164 "direct"
1166 "appliance"
1167 Run qemu directly to launch an appliance.
1168 "direct" and "appliance" are synonyms.
1170 This is the ordinary method and normally the default, but see the
1172 note below.
1173 "libvirt"
1175 "libvirt:null"
1176 "libvirt:URI"
1177 Use libvirt to launch and manage the appliance.
1178 "libvirt" causes libguestfs to choose a suitable URI for creating
1180 session guests. If using the libvirt backend, you almost always
1181 should use this.
1182 "libvirt:null" causes libguestfs to use the "NULL" connection URI,
1184 which causes libvirt to try to guess what the user meant. You
1185 probably don't want to use this.
1186 "libvirt:URI" uses URI as the libvirt connection URI (see
1188 http://libvirt.org/uri.html). The typical libvirt backend with a
1189 URI would be "libvirt:qemu:///session"
1190 The libvirt backend supports more features, including hotplugging
1192 (see "HOTPLUGGING") and sVirt.
1193 "uml"
1195 Run the User-Mode Linux kernel. The location of the kernel is set
1196 using $LIBGUESTFS_HV or using the "guestfs_set_qemu" API (note that
1197 qemu is not involved, we just reuse the same variable in the handle
1198 for convenience).
1199 User-Mode Linux can be much faster, simpler and more lightweight
1201 than using a full-blown virtual machine, but it also has some
1202 shortcomings. See "USER-MODE LINUX BACKEND" below.
1203 "unix:path"
1205 Connect to the Unix domain socket path.
1206 This method lets you connect to an existing daemon or (using
1208 virtio-serial) to a live guest. For more information, see
1209 "ATTACHING TO RUNNING DAEMONS".
1210 "direct" is usually the default backend. However since libguestfs ≥
1212 1.19.24, libguestfs can be built with a different default by doing:
1213 ./configure --with-default-backend=...
1215 To find out if libguestfs was compiled with a different default
1217 backend, do:
1218 unset LIBGUESTFS_BACKEND
1220 guestfish get-backend
1221 BACKEND SETTINGS
1223 Each backend can be configured by passing a list of strings. You can
1224 either call "guestfs_set_backend_settings" with a list of strings, or
1225 set the "LIBGUESTFS_BACKEND_SETTINGS" environment variable to a colon-
1226 separated list of strings (before creating the handle).
1227 force_tcg
1229 Using:
1231 export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
1233 will force the direct and libvirt backends to use TCG (software
1235 emulation) instead of KVM (hardware accelerated virtualization).
1236 gdb
1238 The direct backend supports:
1240 export LIBGUESTFS_BACKEND_SETTINGS=gdb
1242 When this is set, qemu will not start running the appliance
1244 immediately. It will wait for you to connect to it using gdb:
1245 $ gdb
1247 (gdb) symbol-file /path/to/vmlinux
1248 (gdb) target remote tcp::1234
1249 (gdb) cont
1250 You can then debug the appliance kernel, which is useful to debug boot
1252 failures (especially ones where there are no debug messages printed -
1253 tip: look in the kernel "log_buf").
1254 On Fedora, install "kernel-debuginfo" for the "vmlinux" file
1256 (containing symbols). Make sure the symbols precisely match the kernel
1257 being used.
1258 ATTACHING TO RUNNING DAEMONS
1260 Note [4m(1): This is highly experimental and has a tendency to eat babies.
1261 Use with caution.
1262 Note [4m(2): This section explains how to attach to a running daemon from
1264 a low level perspective. For most users, simply using virt tools such
1265 as guestfish(1) with the --live option will "just work".
1266 Using guestfs_set_backend
1268 By calling "guestfs_set_backend" you can change how the library
1270 connects to the "guestfsd" daemon in "guestfs_launch" (read
1271 "ARCHITECTURE" in guestfs-internals(1) for some background).
1272 The normal backend is "direct", where a small appliance is created
1274 containing the daemon, and then the library connects to this.
1275 "libvirt" or "libvirt:URI" are alternatives that use libvirt to start
1276 the appliance.
1277 Setting the backend to "unix:path" (where path is the path of a Unix
1279 domain socket) causes "guestfs_launch" to connect to an existing daemon
1280 over the Unix domain socket.
1281 The normal use for this is to connect to a running virtual machine that
1283 contains a "guestfsd" daemon, and send commands so you can read and
1284 write files inside the live virtual machine.
1285 Using guestfs_add_domain with live flag
1287 "guestfs_add_domain" provides some help for getting the correct
1289 backend. If you pass the "live" option to this function, then (if the
1290 virtual machine is running) it will examine the libvirt XML looking for
1291 a virtio-serial channel to connect to:
1292 <domain>
1294 ...
1295 <devices>
1296 ...
1297 <channel type='unix'>
1298 <source mode='bind' path='/path/to/socket'/>
1299 <target type='virtio' name='org.libguestfs.channel.0'/>
1300 </channel>
1301 ...
1302 </devices>
1303 </domain>
1304 "guestfs_add_domain" extracts /path/to/socket and sets the backend to
1306 "unix:/path/to/socket".
1307 Some of the libguestfs tools (including guestfish) support a --live
1309 option which is passed through to "guestfs_add_domain" thus allowing
1310 you to attach to and modify live virtual machines.
1311 The virtual machine needs to have been set up beforehand so that it has
1313 the virtio-serial channel and so that guestfsd is running inside it.
1314 USER-MODE LINUX BACKEND
1316 Setting the following environment variables (or the equivalent in the
1317 API) selects the User-Mode Linux backend:
1318 export LIBGUESTFS_BACKEND=uml
1320 export LIBGUESTFS_HV=/path/to/vmlinux
1321 "vmlinux" (or it may be called "linux") is the Linux binary, compiled
1323 to run as a userspace process. Note that we reuse the qemu variable in
1324 the handle for convenience; qemu is not involved.
1325 User-Mode Linux can be faster and more lightweight than running a full-
1327 blown virtual machine as the backend (especially if you are already
1328 running libguestfs in a virtual machine or cloud instance), but it also
1329 has some shortcomings compared to the usual qemu/KVM-based backend.
1330 BUILDING USER-MODE LINUX FROM SOURCE
1332 Your Linux distro may provide UML in which case you can ignore this
1334 section.
1335 These instructions are adapted from:
1337 http://user-mode-linux.sourceforge.net/source.html
1338 1. Check out Linux sources
1340 Clone the Linux git repository or download the Linux source
1341 tarball.
1342 2. Configure the kernel
1344 Note: All ‘make’ commands must have "ARCH=um" added.
1345 make menuconfig ARCH=um
1347 Make sure any filesystem drivers that you need are compiled into
1349 the kernel.
1350 Currently, it needs a large amount of extra work to get modules
1352 working. It’s recommended that you disable module support in the
1353 kernel configuration, which will cause everything to be compiled
1354 into the image.
1355 3. Build the kernel
1357 make ARCH=um
1358 This will leave a file called "linux" or "vmlinux" in the top-level
1360 directory. This is the UML kernel. You should set "LIBGUESTFS_HV"
1361 to point to this file.
1362 USER-MODE LINUX DIFFERENCES FROM KVM
1364 UML only supports raw-format images
1366 Only plain raw-format images will work. No qcow2, no backing
1367 files.
1368 UML does not support any remote drives
1370 No NBD, etc.
1371 UML only works on ix86 and x86-64
1373 UML is experimental
1374 In particular, support for UML in libguestfs depends on support for
1375 UML in the upstream kernel. If UML was ever removed from the
1376 upstream Linux kernel, then we might remove it from libguestfs too.
1377 ABI GUARANTEE
1379 We guarantee the libguestfs ABI (binary interface), for public, high-
1380 level actions as outlined in this section. Although we will deprecate
1381 some actions, for example if they get replaced by newer calls, we will
1382 keep the old actions forever. This allows you the developer to program
1383 in confidence against the libguestfs API.
1384 BLOCK DEVICE NAMING
1386 Libguestfs defines /dev/sd* as the standard naming scheme for devices
1387 passed to API calls. So /dev/sda means "the first device added by
1388 "guestfs_add_drive_opts"", and /dev/sdb3 means "the third partition on
1389 the second device".
1390 Internally device names are sometimes translated, but this should not
1392 be visible at the API level.
1393 DISK LABELS
1395 In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1397 using the optional "label" parameter to "guestfs_add_drive_opts".
1398 (Note that disk labels are different from and not related to filesystem
1399 labels).
1400 Not all versions of libguestfs support setting a disk label, and when
1402 it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1403 When you add a disk with a label, it can either be addressed using
1405 /dev/sd*, or using /dev/disk/guestfs/label. Partitions on the disk can
1406 be addressed using /dev/disk/guestfs/labelpartnum.
1407 Listing devices ("guestfs_list_devices") and partitions
1409 ("guestfs_list_partitions") returns the block device names. However
1410 you can use "guestfs_list_disk_labels" to map disk labels to block
1411 device and partition names.
1412 NULL DISKS
1414 When adding a disk using, eg., "guestfs_add_drive", you can set the
1415 filename to "/dev/null". This string is treated specially by
1416 libguestfs, causing it to add a "null disk".
1417 A null disk has the following properties:
1419 · A null disk will appear as a normal device, eg. in calls to
1421 "guestfs_list_devices".
1422 · You may add "/dev/null" multiple times.
1424 · You should not try to access a null disk in any way. For example,
1426 you shouldn't try to read it or mount it.
1427 Null disks are used for three main purposes:
1429 1. Performance testing of libguestfs (see guestfs-performance(1)).
1431 2. The internal test suite.
1433 3. If you want to use libguestfs APIs that don’t refer to disks, since
1435 libguestfs requires that at least one disk is added, you should add
1436 a null disk.
1437 For example, to test if a feature is available, use code like this:
1439 guestfs_h *g;
1441 char **groups = [ "btrfs", NULL ];
1442 g = guestfs_create ();
1444 guestfs_add_drive (g, "/dev/null");
1445 guestfs_launch (g);
1446 if (guestfs_available (g, groups) == 0) {
1447 // group(s) are available
1448 } else {
1449 // group(s) are not available
1450 }
1451 guestfs_close (g);
1452 DISK IMAGE FORMATS
1454 Virtual disks come in a variety of formats. Some common formats are
1455 listed below.
1456 Note that libguestfs itself is not responsible for handling the disk
1458 format: this is done using qemu(1). If support for a particular format
1459 is missing or broken, this has to be fixed in qemu.
1460 COMMON VIRTUAL DISK IMAGE FORMATS
1462 raw Raw format is simply a dump of the sequential bytes of the virtual
1464 hard disk. There is no header, container, compression or
1465 processing of any sort.
1466 Since raw format requires no translation to read or write, it is
1468 both fast and very well supported by qemu and all other
1469 hypervisors. You can consider it to be a universal format that any
1470 hypervisor can access.
1471 Raw format files are not compressed and so take up the full space
1473 of the original disk image even when they are empty. A variation
1474 (on Linux/Unix at least) is to not store ranges of all-zero bytes
1475 by storing the file as a sparse file. This "variant format" is
1476 sometimes called raw sparse. Many utilities, including
1477 virt-sparsify(1), can make raw disk images sparse.
1478 qcow2
1480 Qcow2 is the native disk image format used by qemu. Internally it
1481 uses a two-level directory structure so that only blocks containing
1482 data are stored in the file. It also has many other features such
1483 as compression, snapshots and backing files.
1484 There are at least two distinct variants of this format, although
1486 qemu (and hence libguestfs) handles both transparently to the user.
1487 vmdk
1489 VMDK is VMware’s native disk image format. There are many
1490 variations. Modern qemu (hence libguestfs) supports most
1491 variations, but you should be aware that older versions of qemu had
1492 some very bad data-corrupting bugs in this area.
1493 Note that VMware ESX exposes files with the name guest-flat.vmdk.
1495 These are not VMDK. They are raw format files which happen to have
1496 a ".vmdk" extension.
1497 vdi VDI is VirtualBox’s native disk image format. Qemu (hence
1499 libguestfs) has generally good support for this.
1500 vpc
1502 vhd VPC (old) and VHD (modern) are the native disk image format of
1503 Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1504 Obsolete formats
1506 The following formats are obsolete and should not be used: qcow
1507 (aka qcow1), cow, bochs.
1508 DETECTING THE FORMAT OF A DISK IMAGE
1510 Firstly note there is a security issue with auto-detecting the format
1512 of a disk image. It may or may not apply in your use case. Read
1513 "CVE-2010-3851" below.
1514 Libguestfs offers an API to get the format of a disk image
1516 ("guestfs_disk_format", and it is safest to use this.
1517 Don’t be tempted to try parsing the text / human-readable output of
1519 "qemu-img" since it cannot be parsed reliably and securely. Also do
1520 not use the "file" command since the output of that changes over time.
1521
1523 guestfs_h *
1524 "guestfs_h" is the opaque type representing a connection handle.
1525 Create a handle by calling "guestfs_create" or "guestfs_create_flags".
1526 Call "guestfs_close" to free the handle and release all resources used.
1527 For information on using multiple handles and threads, see the section
1529 "MULTIPLE HANDLES AND MULTIPLE THREADS" above.
1530 guestfs_create
1532 guestfs_h *guestfs_create (void);
1533 Create a connection handle.
1535 On success this returns a non-NULL pointer to a handle. On error it
1537 returns NULL.
1538 You have to "configure" the handle after creating it. This includes
1540 calling "guestfs_add_drive_opts" (or one of the equivalent calls) on
1541 the handle at least once.
1542 After configuring the handle, you have to call "guestfs_launch".
1544 You may also want to configure error handling for the handle. See the
1546 "ERROR HANDLING" section below.
1547 guestfs_create_flags
1549 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
1550 Create a connection handle, supplying extra flags and extra arguments
1552 to control how the handle is created.
1553 On success this returns a non-NULL pointer to a handle. On error it
1555 returns NULL.
1556 "guestfs_create" is equivalent to calling guestfs_create_flags(0).
1558 The following flags may be logically ORed together. (Currently no
1560 extra arguments are used).
1561 "GUESTFS_CREATE_NO_ENVIRONMENT"
1563 Don’t parse any environment variables (such as "LIBGUESTFS_DEBUG"
1564 etc).
1565 You can call "guestfs_parse_environment" or
1567 "guestfs_parse_environment_list" afterwards to parse environment
1568 variables. Alternately, don't call these functions if you want the
1569 handle to be unaffected by environment variables. See the example
1570 below.
1571 The default (if this flag is not given) is to implicitly call
1573 "guestfs_parse_environment".
1574 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT"
1576 Don’t try to close the handle in an atexit(3) handler if the
1577 program exits without explicitly closing the handle.
1578 The default (if this flag is not given) is to install such an
1580 atexit handler.
1581 USING "GUESTFS_CREATE_NO_ENVIRONMENT"
1583 You might use "GUESTFS_CREATE_NO_ENVIRONMENT" and an explicit call to
1585 "guestfs_parse_environment" like this:
1586 guestfs_h *g;
1588 int r;
1589 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
1591 if (!g) {
1592 perror ("guestfs_create_flags");
1593 exit (EXIT_FAILURE);
1594 }
1595 r = guestfs_parse_environment (g);
1596 if (r == -1)
1597 exit (EXIT_FAILURE);
1598 Or to create a handle which is unaffected by environment variables,
1600 omit the call to "guestfs_parse_environment" from the above code.
1601 The above code has another advantage which is that any errors from
1603 parsing the environment are passed through the error handler, whereas
1604 "guestfs_create" prints errors on stderr and ignores them.
1605 guestfs_close
1607 void guestfs_close (guestfs_h *g);
1608 This closes the connection handle and frees up all resources used. If
1610 a close callback was set on the handle, then it is called.
1611 The correct way to close the handle is:
1613 if (guestfs_shutdown (g) == -1) {
1615 /* handle write errors here */
1616 }
1617 guestfs_close (g);
1618 "guestfs_shutdown" is only needed if all of the following are true:
1620 1. one or more disks were added in read-write mode, and
1622 2. guestfs_launch was called, and
1624 3. you made some changes, and
1626 4. you have a way to handle write errors (eg. by exiting with an error
1628 code or reporting something to the user).
1629
1631 API functions can return errors. For example, almost all functions
1632 that return "int" will return "-1" to indicate an error.
1633 Additional information is available for errors: an error message string
1635 and optionally an error number (errno) if the thing that failed was a
1636 system call.
1637 You can get at the additional information about the last error on the
1639 handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1640 setting up an error handler with "guestfs_set_error_handler".
1641 When the handle is created, a default error handler is installed which
1643 prints the error message string to "stderr". For small short-running
1644 command line programs it is sufficient to do:
1645 if (guestfs_launch (g) == -1)
1647 exit (EXIT_FAILURE);
1648 since the default error handler will ensure that an error message has
1650 been printed to "stderr" before the program exits.
1651 For other programs the caller will almost certainly want to install an
1653 alternate error handler or do error handling in-line as in the example
1654 below. The non-C language bindings all install NULL error handlers and
1655 turn errors into exceptions using code similar to this:
1656 const char *msg;
1658 int errnum;
1659 /* This disables the default behaviour of printing errors
1661 on stderr. */
1662 guestfs_set_error_handler (g, NULL, NULL);
1663 if (guestfs_launch (g) == -1) {
1665 /* Examine the error message and print it, throw it,
1666 etc. */
1667 msg = guestfs_last_error (g);
1668 errnum = guestfs_last_errno (g);
1669 fprintf (stderr, "%s", msg);
1671 if (errnum != 0)
1672 fprintf (stderr, ": %s", strerror (errnum));
1673 fprintf (stderr, "\n");
1674 /* ... */
1676 }
1677 "guestfs_create" returns "NULL" if the handle cannot be created, and
1679 because there is no handle if this happens there is no way to get
1680 additional error information. Since libguestfs ≥ 1.20, you can use
1681 "guestfs_create_flags" to properly deal with errors during handle
1682 creation, although the vast majority of programs can continue to use
1683 "guestfs_create" and not worry about this situation.
1684 Out of memory errors are handled differently. The default action is to
1686 call abort(3). If this is undesirable, then you can set a handler
1687 using "guestfs_set_out_of_memory_handler".
1688 guestfs_last_error
1690 const char *guestfs_last_error (guestfs_h *g);
1691 This returns the last error message that happened on "g". If there has
1693 not been an error since the handle was created, then this returns
1694 "NULL".
1695 Note the returned string does not have a newline character at the end.
1697 Most error messages are single lines. Some are split over multiple
1698 lines and contain "\n" characters within the string but not at the end.
1699 The lifetime of the returned string is until the next error occurs on
1701 the same handle, or "guestfs_close" is called. If you need to keep it
1702 longer, copy it.
1703 guestfs_last_errno
1705 int guestfs_last_errno (guestfs_h *g);
1706 This returns the last error number (errno) that happened on "g".
1708 If successful, an errno integer not equal to zero is returned.
1710 In many cases the special errno "ENOTSUP" is returned if you tried to
1712 call a function or use a feature which is not supported.
1713 If no error number is available, this returns 0. This call can return
1715 0 in three situations:
1716 1. There has not been any error on the handle.
1718 2. There has been an error but the errno was meaningless. This
1720 corresponds to the case where the error did not come from a failed
1721 system call, but for some other reason.
1722 3. There was an error from a failed system call, but for some reason
1724 the errno was not captured and returned. This usually indicates a
1725 bug in libguestfs.
1726 Libguestfs tries to convert the errno from inside the appliance into a
1728 corresponding errno for the caller (not entirely trivial: the appliance
1729 might be running a completely different operating system from the
1730 library and error numbers are not standardized across Un*xen). If this
1731 could not be done, then the error is translated to "EINVAL". In
1732 practice this should only happen in very rare circumstances.
1733 guestfs_set_error_handler
1735 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1736 void *opaque,
1737 const char *msg);
1738 void guestfs_set_error_handler (guestfs_h *g,
1739 guestfs_error_handler_cb cb,
1740 void *opaque);
1741 The callback "cb" will be called if there is an error. The parameters
1743 passed to the callback are an opaque data pointer and the error message
1744 string.
1745 "errno" is not passed to the callback. To get that the callback must
1747 call "guestfs_last_errno".
1748 Note that the message string "msg" is freed as soon as the callback
1750 function returns, so if you want to stash it somewhere you must make
1751 your own copy.
1752 The default handler prints messages on "stderr".
1754 If you set "cb" to "NULL" then no handler is called.
1756 guestfs_get_error_handler
1758 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1759 void **opaque_rtn);
1760 Returns the current error handler callback.
1762 guestfs_push_error_handler
1764 void guestfs_push_error_handler (guestfs_h *g,
1765 guestfs_error_handler_cb cb,
1766 void *opaque);
1767 This is the same as "guestfs_set_error_handler", except that the old
1769 error handler is stashed away in a stack inside the handle. You can
1770 restore the previous error handler by calling
1771 "guestfs_pop_error_handler".
1772 Use the following code to temporarily disable errors around a function:
1774 guestfs_push_error_handler (g, NULL, NULL);
1776 guestfs_mkdir (g, "/foo"); /* We don't care if this fails. */
1777 guestfs_pop_error_handler (g);
1778 guestfs_pop_error_handler
1780 void guestfs_pop_error_handler (guestfs_h *g);
1781 Restore the previous error handler (see "guestfs_push_error_handler").
1783 If you pop the stack too many times, then the default error handler is
1785 restored.
1786 guestfs_set_out_of_memory_handler
1788 typedef void (*guestfs_abort_cb) (void);
1789 void guestfs_set_out_of_memory_handler (guestfs_h *g,
1790 guestfs_abort_cb);
1791 The callback "cb" will be called if there is an out of memory
1793 situation. Note this callback must not return.
1794 The default is to call abort(3).
1796 You cannot set "cb" to "NULL". You can’t ignore out of memory
1798 situations.
1799 guestfs_get_out_of_memory_handler
1801 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1802 This returns the current out of memory handler.
1804
1806 guestfs_acl_delete_def_file
1807 int
1808 guestfs_acl_delete_def_file (guestfs_h *g,
1809 const char *dir);
1810 This function deletes the default POSIX Access Control List (ACL)
1812 attached to directory "dir".
1813 This function returns 0 on success or -1 on error.
1815 This function depends on the feature "acl". See also
1817 "guestfs_feature_available".
1818 (Added in 1.19.63)
1820 guestfs_acl_get_file
1822 char *
1823 guestfs_acl_get_file (guestfs_h *g,
1824 const char *path,
1825 const char *acltype);
1826 This function returns the POSIX Access Control List (ACL) attached to
1828 "path". The ACL is returned in "long text form" (see acl(5)).
1829 The "acltype" parameter may be:
1831 "access"
1833 Return the ordinary (access) ACL for any file, directory or other
1834 filesystem object.
1835 "default"
1837 Return the default ACL. Normally this only makes sense if "path"
1838 is a directory.
1839 This function returns a string, or NULL on error. The caller must free
1841 the returned string after use.
1842 This function depends on the feature "acl". See also
1844 "guestfs_feature_available".
1845 (Added in 1.19.63)
1847 guestfs_acl_set_file
1849 int
1850 guestfs_acl_set_file (guestfs_h *g,
1851 const char *path,
1852 const char *acltype,
1853 const char *acl);
1854 This function sets the POSIX Access Control List (ACL) attached to
1856 "path".
1857 The "acltype" parameter may be:
1859 "access"
1861 Set the ordinary (access) ACL for any file, directory or other
1862 filesystem object.
1863 "default"
1865 Set the default ACL. Normally this only makes sense if "path" is a
1866 directory.
1867 The "acl" parameter is the new ACL in either "long text form" or "short
1869 text form" (see acl(5)). The new ACL completely replaces any previous
1870 ACL on the file. The ACL must contain the full Unix permissions (eg.
1871 "u::rwx,g::rx,o::rx").
1872 If you are specifying individual users or groups, then the mask field
1874 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1875 "g:ID:..." field(s). A full ACL string might therefore look like this:
1876 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1878 \ Unix permissions / \mask/ \ ACL /
1879 You should use numeric UIDs and GIDs. To map usernames and groupnames
1881 to the correct numeric ID in the context of the guest, use the Augeas
1882 functions (see "guestfs_aug_init").
1883 This function returns 0 on success or -1 on error.
1885 This function depends on the feature "acl". See also
1887 "guestfs_feature_available".
1888 (Added in 1.19.63)
1890 guestfs_add_cdrom
1892 int
1893 guestfs_add_cdrom (guestfs_h *g,
1894 const char *filename);
1895 This function is deprecated. In new code, use the
1897 "guestfs_add_drive_ro" call instead.
1898 Deprecated functions will not be removed from the API, but the fact
1900 that they are deprecated indicates that there are problems with correct
1901 use of these functions.
1902 This function adds a virtual CD-ROM disk image to the guest.
1904 The image is added as read-only drive, so this function is equivalent
1906 of "guestfs_add_drive_ro".
1907 This function returns 0 on success or -1 on error.
1909 (Added in 0.3)
1911 guestfs_add_domain
1913 int
1914 guestfs_add_domain (guestfs_h *g,
1915 const char *dom,
1916 ...);
1917 You may supply a list of optional arguments to this call. Use zero or
1919 more of the following pairs of parameters, and terminate the list with
1920 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
1921 GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
1923 GUESTFS_ADD_DOMAIN_READONLY, int readonly,
1924 GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
1925 GUESTFS_ADD_DOMAIN_LIVE, int live,
1926 GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
1927 GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
1928 GUESTFS_ADD_DOMAIN_CACHEMODE, const char *cachemode,
1929 GUESTFS_ADD_DOMAIN_DISCARD, const char *discard,
1930 GUESTFS_ADD_DOMAIN_COPYONREAD, int copyonread,
1931 This function adds the disk(s) attached to the named libvirt domain
1933 "dom". It works by connecting to libvirt, requesting the domain and
1934 domain XML from libvirt, parsing it for disks, and calling
1935 "guestfs_add_drive_opts" on each one.
1936 The number of disks added is returned. This operation is atomic: if an
1938 error is returned, then no disks are added.
1939 This function does some minimal checks to make sure the libvirt domain
1941 is not running (unless "readonly" is true). In a future version we
1942 will try to acquire the libvirt lock on each disk.
1943 Disks must be accessible locally. This often means that adding disks
1945 from a remote libvirt connection (see http://libvirt.org/remote.html)
1946 will fail unless those disks are accessible via the same device path
1947 locally too.
1948 The optional "libvirturi" parameter sets the libvirt URI (see
1950 http://libvirt.org/uri.html). If this is not set then we connect to
1951 the default libvirt URI (or one set through an environment variable,
1952 see the libvirt documentation for full details).
1953 The optional "live" flag controls whether this call will try to connect
1955 to a running virtual machine "guestfsd" process if it sees a suitable
1956 <channel> element in the libvirt XML definition. The default (if the
1957 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
1958 for more information.
1959 If the "allowuuid" flag is true (default is false) then a UUID may be
1961 passed instead of the domain name. The "dom" string is treated as a
1962 UUID first and looked up, and if that lookup fails then we treat "dom"
1963 as a name as usual.
1964 The optional "readonlydisk" parameter controls what we do for disks
1966 which are marked <readonly/> in the libvirt XML. Possible values are:
1967 readonlydisk = "error"
1969 If "readonly" is false:
1970 The whole call is aborted with an error if any disk with the
1972 <readonly/> flag is found.
1973 If "readonly" is true:
1975 Disks with the <readonly/> flag are added read-only.
1977 readonlydisk = "read"
1979 If "readonly" is false:
1980 Disks with the <readonly/> flag are added read-only. Other disks
1982 are added read/write.
1983 If "readonly" is true:
1985 Disks with the <readonly/> flag are added read-only.
1987 readonlydisk = "write" (default)
1989 If "readonly" is false:
1990 Disks with the <readonly/> flag are added read/write.
1992 If "readonly" is true:
1994 Disks with the <readonly/> flag are added read-only.
1996 readonlydisk = "ignore"
1998 If "readonly" is true or false:
1999 Disks with the <readonly/> flag are skipped.
2001 The other optional parameters are passed directly through to
2003 "guestfs_add_drive_opts".
2004 On error this function returns -1.
2006 (Added in 1.7.4)
2008 guestfs_add_domain_va
2010 int
2011 guestfs_add_domain_va (guestfs_h *g,
2012 const char *dom,
2013 va_list args);
2014 This is the "va_list variant" of "guestfs_add_domain".
2016 See "CALLS WITH OPTIONAL ARGUMENTS".
2018 guestfs_add_domain_argv
2020 int
2021 guestfs_add_domain_argv (guestfs_h *g,
2022 const char *dom,
2023 const struct guestfs_add_domain_argv *optargs);
2024 This is the "argv variant" of "guestfs_add_domain".
2026 See "CALLS WITH OPTIONAL ARGUMENTS".
2028 guestfs_add_drive
2030 int
2031 guestfs_add_drive (guestfs_h *g,
2032 const char *filename);
2033 This function is provided for backwards compatibility with earlier
2035 versions of libguestfs. It simply calls "guestfs_add_drive_opts" with
2036 no optional arguments.
2037 (Added in 0.3)
2039 guestfs_add_drive_opts
2041 int
2042 guestfs_add_drive_opts (guestfs_h *g,
2043 const char *filename,
2044 ...);
2045 You may supply a list of optional arguments to this call. Use zero or
2047 more of the following pairs of parameters, and terminate the list with
2048 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2049 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2051 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2052 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2053 GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2054 GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2055 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2056 GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2057 GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2058 GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2059 GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2060 GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2061 GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2062 This function adds a disk image called filename to the handle.
2064 filename may be a regular host file or a host device.
2065 When this function is called before "guestfs_launch" (the usual case)
2067 then the first time you call this function, the disk appears in the API
2068 as /dev/sda, the second time as /dev/sdb, and so on.
2069 In libguestfs ≥ 1.20 you can also call this function after launch (with
2071 some restrictions). This is called "hotplugging". When hotplugging,
2072 you must specify a "label" so that the new disk gets a predictable
2073 name. For more information see "HOTPLUGGING".
2074 You don't necessarily need to be root when using libguestfs. However
2076 you obviously do need sufficient permissions to access the filename for
2077 whatever operations you want to perform (ie. read access if you just
2078 want to read the image or write access if you want to modify the
2079 image).
2080 This call checks that filename exists.
2082 filename may be the special string "/dev/null". See "NULL DISKS".
2084 The optional arguments are:
2086 "readonly"
2088 If true then the image is treated as read-only. Writes are still
2089 allowed, but they are stored in a temporary snapshot overlay which
2090 is discarded at the end. The disk that you add is not modified.
2091 "format"
2093 This forces the image format. If you omit this (or use
2094 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2095 automatically detected. Possible formats include "raw" and
2096 "qcow2".
2097 Automatic detection of the format opens you up to a potential
2099 security hole when dealing with untrusted raw-format images. See
2100 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
2101 security hole.
2102 "iface"
2104 This rarely-used option lets you emulate the behaviour of the
2105 deprecated "guestfs_add_drive_with_if" call (q.v.)
2106 "name"
2108 The name the drive had in the original guest, e.g. /dev/sdb. This
2109 is used as a hint to the guest inspection process if it is
2110 available.
2111 "label"
2113 Give the disk a label. The label should be a unique, short string
2114 using only ASCII characters "[a-zA-Z]". As well as its usual name
2115 in the API (such as /dev/sda), the drive will also be named
2116 /dev/disk/guestfs/label.
2117 See "DISK LABELS".
2119 "protocol"
2121 The optional protocol argument can be used to select an alternate
2122 source protocol.
2123 See also: "REMOTE STORAGE".
2125 "protocol = "file""
2127 filename is interpreted as a local file or device. This is the
2128 default if the optional protocol parameter is omitted.
2129 "protocol = "nbd""
2131 Connect to the Network Block Device server. The "server"
2132 parameter must also be supplied - see below.
2133 See also: "NETWORK BLOCK DEVICE".
2135 "protocol = "rbd""
2137 Connect to the Ceph (librbd/RBD) server. The "server"
2138 parameter must also be supplied - see below. The "username"
2139 parameter may be supplied. See below. The "secret" parameter
2140 may be supplied. See below.
2141 See also: "CEPH".
2143 "server"
2145 For protocols which require access to a remote server, this is a
2146 list of server(s).
2147 Protocol Number of servers required
2149 -------- --------------------------
2150 file List must be empty or param not used at all
2151 nbd Exactly one
2152 rbd Zero or more
2153 Each list element is a string specifying a server. The string must
2155 be in one of the following formats:
2156 hostname
2158 hostname:port
2159 tcp:hostname
2160 tcp:hostname:port
2161 unix:/path/to/socket
2162 If the port number is omitted, then the standard port number for
2164 the protocol is used (see /etc/services).
2165 "username"
2167 For the "rbd" protocol, this specifies the remote username.
2168 If not given, then no authentication is attempted for ceph. But
2170 note this sometimes may give unexpected results, for example if
2171 using the libvirt backend and if the libvirt backend is configured
2172 to start the qemu appliance as a special user such as "qemu.qemu".
2173 If in doubt, specify the remote username you want.
2174 "secret"
2176 For the "rbd" protocol only, this specifies the ‘secret’ to use
2177 when connecting to the remote device. It must be base64 encoded.
2178 If not given, then a secret matching the given username will be
2180 looked up in the default keychain locations, or if no username is
2181 given, then no authentication will be used.
2182 "cachemode"
2184 Choose whether or not libguestfs will obey sync operations (safe
2185 but slow) or not (unsafe but fast). The possible values for this
2186 string are:
2187 "cachemode = "writeback""
2189 This is the default.
2190 Write operations in the API do not return until a write(2) call
2192 has completed in the host [but note this does not imply that
2193 anything gets written to disk].
2194 Sync operations in the API, including implicit syncs caused by
2196 filesystem journalling, will not return until an fdatasync(2)
2197 call has completed in the host, indicating that data has been
2198 committed to disk.
2199 "cachemode = "unsafe""
2201 In this mode, there are no guarantees. Libguestfs may cache
2202 anything and ignore sync requests. This is suitable only for
2203 scratch or temporary disks.
2204 "discard"
2206 Enable or disable discard (a.k.a. trim or unmap) support on this
2207 drive. If enabled, operations such as "guestfs_fstrim" will be
2208 able to discard / make thin / punch holes in the underlying host
2209 file or device.
2210 Possible discard settings are:
2212 "discard = "disable""
2214 Disable discard support. This is the default.
2215 "discard = "enable""
2217 Enable discard support. Fail if discard is not possible.
2218 "discard = "besteffort""
2220 Enable discard support if possible, but don't fail if it is not
2221 supported.
2222 Since not all backends and not all underlying systems support
2224 discard, this is a good choice if you want to use discard if
2225 possible, but don't mind if it doesn't work.
2226 "copyonread"
2228 The boolean parameter "copyonread" enables copy-on-read support.
2229 This only affects disk formats which have backing files, and causes
2230 reads to be stored in the overlay layer, speeding up multiple reads
2231 of the same area of disk.
2232 The default is false.
2234 This function returns 0 on success or -1 on error.
2236 (Added in 0.3)
2238 guestfs_add_drive_opts_va
2240 int
2241 guestfs_add_drive_opts_va (guestfs_h *g,
2242 const char *filename,
2243 va_list args);
2244 This is the "va_list variant" of "guestfs_add_drive_opts".
2246 See "CALLS WITH OPTIONAL ARGUMENTS".
2248 guestfs_add_drive_opts_argv
2250 int
2251 guestfs_add_drive_opts_argv (guestfs_h *g,
2252 const char *filename,
2253 const struct guestfs_add_drive_opts_argv *optargs);
2254 This is the "argv variant" of "guestfs_add_drive_opts".
2256 See "CALLS WITH OPTIONAL ARGUMENTS".
2258 guestfs_add_drive_ro
2260 int
2261 guestfs_add_drive_ro (guestfs_h *g,
2262 const char *filename);
2263 This function is the equivalent of calling "guestfs_add_drive_opts"
2265 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2266 so the disk is added read-only, with the format being detected
2267 automatically.
2268 This function returns 0 on success or -1 on error.
2270 (Added in 1.0.38)
2272 guestfs_add_drive_ro_with_if
2274 int
2275 guestfs_add_drive_ro_with_if (guestfs_h *g,
2276 const char *filename,
2277 const char *iface);
2278 This function is deprecated. In new code, use the "guestfs_add_drive"
2280 call instead.
2281 Deprecated functions will not be removed from the API, but the fact
2283 that they are deprecated indicates that there are problems with correct
2284 use of these functions.
2285 This is the same as "guestfs_add_drive_ro" but it allows you to specify
2287 the QEMU interface emulation to use at run time.
2288 This function returns 0 on success or -1 on error.
2290 (Added in 1.0.84)
2292 guestfs_add_drive_scratch
2294 int
2295 guestfs_add_drive_scratch (guestfs_h *g,
2296 int64_t size,
2297 ...);
2298 You may supply a list of optional arguments to this call. Use zero or
2300 more of the following pairs of parameters, and terminate the list with
2301 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2302 GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2304 GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2305 This command adds a temporary scratch drive to the handle. The "size"
2307 parameter is the virtual size (in bytes). The scratch drive is blank
2308 initially (all reads return zeroes until you start writing to it). The
2309 drive is deleted when the handle is closed.
2310 The optional arguments "name" and "label" are passed through to
2312 "guestfs_add_drive".
2313 This function returns 0 on success or -1 on error.
2315 (Added in 1.23.10)
2317 guestfs_add_drive_scratch_va
2319 int
2320 guestfs_add_drive_scratch_va (guestfs_h *g,
2321 int64_t size,
2322 va_list args);
2323 This is the "va_list variant" of "guestfs_add_drive_scratch".
2325 See "CALLS WITH OPTIONAL ARGUMENTS".
2327 guestfs_add_drive_scratch_argv
2329 int
2330 guestfs_add_drive_scratch_argv (guestfs_h *g,
2331 int64_t size,
2332 const struct guestfs_add_drive_scratch_argv *optargs);
2333 This is the "argv variant" of "guestfs_add_drive_scratch".
2335 See "CALLS WITH OPTIONAL ARGUMENTS".
2337 guestfs_add_drive_with_if
2339 int
2340 guestfs_add_drive_with_if (guestfs_h *g,
2341 const char *filename,
2342 const char *iface);
2343 This function is deprecated. In new code, use the "guestfs_add_drive"
2345 call instead.
2346 Deprecated functions will not be removed from the API, but the fact
2348 that they are deprecated indicates that there are problems with correct
2349 use of these functions.
2350 This is the same as "guestfs_add_drive" but it allows you to specify
2352 the QEMU interface emulation to use at run time.
2353 This function returns 0 on success or -1 on error.
2355 (Added in 1.0.84)
2357 guestfs_add_libvirt_dom
2359 int
2360 guestfs_add_libvirt_dom (guestfs_h *g,
2361 void * /* really virDomainPtr */ dom,
2362 ...);
2363 You may supply a list of optional arguments to this call. Use zero or
2365 more of the following pairs of parameters, and terminate the list with
2366 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2367 GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2369 GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2370 GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2371 GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2372 GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2373 GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2374 GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2375 This function adds the disk(s) attached to the libvirt domain "dom".
2377 It works by requesting the domain XML from libvirt, parsing it for
2378 disks, and calling "guestfs_add_drive_opts" on each one.
2379 In the C API we declare "void *dom", but really it has type
2381 "virDomainPtr dom". This is so we don't need <libvirt.h>.
2382 The number of disks added is returned. This operation is atomic: if an
2384 error is returned, then no disks are added.
2385 This function does some minimal checks to make sure the libvirt domain
2387 is not running (unless "readonly" is true). In a future version we
2388 will try to acquire the libvirt lock on each disk.
2389 Disks must be accessible locally. This often means that adding disks
2391 from a remote libvirt connection (see http://libvirt.org/remote.html)
2392 will fail unless those disks are accessible via the same device path
2393 locally too.
2394 The optional "live" flag controls whether this call will try to connect
2396 to a running virtual machine "guestfsd" process if it sees a suitable
2397 <channel> element in the libvirt XML definition. The default (if the
2398 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
2399 for more information.
2400 The optional "readonlydisk" parameter controls what we do for disks
2402 which are marked <readonly/> in the libvirt XML. See
2403 "guestfs_add_domain" for possible values.
2404 The other optional parameters are passed directly through to
2406 "guestfs_add_drive_opts".
2407 On error this function returns -1.
2409 (Added in 1.29.14)
2411 guestfs_add_libvirt_dom_va
2413 int
2414 guestfs_add_libvirt_dom_va (guestfs_h *g,
2415 void * /* really virDomainPtr */ dom,
2416 va_list args);
2417 This is the "va_list variant" of "guestfs_add_libvirt_dom".
2419 See "CALLS WITH OPTIONAL ARGUMENTS".
2421 guestfs_add_libvirt_dom_argv
2423 int
2424 guestfs_add_libvirt_dom_argv (guestfs_h *g,
2425 void * /* really virDomainPtr */ dom,
2426 const struct guestfs_add_libvirt_dom_argv *optargs);
2427 This is the "argv variant" of "guestfs_add_libvirt_dom".
2429 See "CALLS WITH OPTIONAL ARGUMENTS".
2431 guestfs_aug_clear
2433 int
2434 guestfs_aug_clear (guestfs_h *g,
2435 const char *augpath);
2436 Set the value associated with "path" to "NULL". This is the same as
2438 the augtool(1) "clear" command.
2439 This function returns 0 on success or -1 on error.
2441 (Added in 1.3.4)
2443 guestfs_aug_close
2445 int
2446 guestfs_aug_close (guestfs_h *g);
2447 Close the current Augeas handle and free up any resources used by it.
2449 After calling this, you have to call "guestfs_aug_init" again before
2450 you can use any other Augeas functions.
2451 This function returns 0 on success or -1 on error.
2453 (Added in 0.7)
2455 guestfs_aug_defnode
2457 struct guestfs_int_bool *
2458 guestfs_aug_defnode (guestfs_h *g,
2459 const char *name,
2460 const char *expr,
2461 const char *val);
2462 Defines a variable "name" whose value is the result of evaluating
2464 "expr".
2465 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2467 to calling "guestfs_aug_set" "expr", "value". "name" will be the
2468 nodeset containing that single node.
2469 On success this returns a pair containing the number of nodes in the
2471 nodeset, and a boolean flag if a node was created.
2472 This function returns a "struct guestfs_int_bool *", or NULL if there
2474 was an error. The caller must call "guestfs_free_int_bool" after use.
2475 (Added in 0.7)
2477 guestfs_aug_defvar
2479 int
2480 guestfs_aug_defvar (guestfs_h *g,
2481 const char *name,
2482 const char *expr);
2483 Defines an Augeas variable "name" whose value is the result of
2485 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2486 On success this returns the number of nodes in "expr", or 0 if "expr"
2488 evaluates to something which is not a nodeset.
2489 On error this function returns -1.
2491 (Added in 0.7)
2493 guestfs_aug_get
2495 char *
2496 guestfs_aug_get (guestfs_h *g,
2497 const char *augpath);
2498 Look up the value associated with "path". If "path" matches exactly
2500 one node, the "value" is returned.
2501 This function returns a string, or NULL on error. The caller must free
2503 the returned string after use.
2504 (Added in 0.7)
2506 guestfs_aug_init
2508 int
2509 guestfs_aug_init (guestfs_h *g,
2510 const char *root,
2511 int flags);
2512 Create a new Augeas handle for editing configuration files. If there
2514 was any previous Augeas handle associated with this guestfs session,
2515 then it is closed.
2516 You must call this before using any other "guestfs_aug_*" commands.
2518 "root" is the filesystem root. "root" must not be NULL, use / instead.
2520 The flags are the same as the flags defined in <augeas.h>, the logical
2522 or of the following integers:
2523 "AUG_SAVE_BACKUP" = 1
2525 Keep the original file with a ".augsave" extension.
2526 "AUG_SAVE_NEWFILE" = 2
2528 Save changes into a file with extension ".augnew", and do not
2529 overwrite original. Overrides "AUG_SAVE_BACKUP".
2530 "AUG_TYPE_CHECK" = 4
2532 Typecheck lenses.
2533 This option is only useful when debugging Augeas lenses. Use of
2535 this option may require additional memory for the libguestfs
2536 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2537 environment variable or call "guestfs_set_memsize".
2538 "AUG_NO_STDINC" = 8
2540 Do not use standard load path for modules.
2541 "AUG_SAVE_NOOP" = 16
2543 Make save a no-op, just record what would have been changed.
2544 "AUG_NO_LOAD" = 32
2546 Do not load the tree in "guestfs_aug_init".
2547 To close the handle, you can call "guestfs_aug_close".
2549 To find out more about Augeas, see http://augeas.net/.
2551 This function returns 0 on success or -1 on error.
2553 (Added in 0.7)
2555 guestfs_aug_insert
2557 int
2558 guestfs_aug_insert (guestfs_h *g,
2559 const char *augpath,
2560 const char *label,
2561 int before);
2562 Create a new sibling "label" for "path", inserting it into the tree
2564 before or after "path" (depending on the boolean flag "before").
2565 "path" must match exactly one existing node in the tree, and "label"
2567 must be a label, ie. not contain /, "*" or end with a bracketed index
2568 "[N]".
2569 This function returns 0 on success or -1 on error.
2571 (Added in 0.7)
2573 guestfs_aug_label
2575 char *
2576 guestfs_aug_label (guestfs_h *g,
2577 const char *augpath);
2578 The label (name of the last element) of the Augeas path expression
2580 "augpath" is returned. "augpath" must match exactly one node, else
2581 this function returns an error.
2582 This function returns a string, or NULL on error. The caller must free
2584 the returned string after use.
2585 (Added in 1.23.14)
2587 guestfs_aug_load
2589 int
2590 guestfs_aug_load (guestfs_h *g);
2591 Load files into the tree.
2593 See "aug_load" in the Augeas documentation for the full gory details.
2595 This function returns 0 on success or -1 on error.
2597 (Added in 0.7)
2599 guestfs_aug_ls
2601 char **
2602 guestfs_aug_ls (guestfs_h *g,
2603 const char *augpath);
2604 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2606 sorting the resulting nodes into alphabetical order.
2607 This function returns a NULL-terminated array of strings (like
2609 environ(3)), or NULL if there was an error. The caller must free the
2610 strings and the array after use.
2611 (Added in 0.8)
2613 guestfs_aug_match
2615 char **
2616 guestfs_aug_match (guestfs_h *g,
2617 const char *augpath);
2618 Returns a list of paths which match the path expression "path". The
2620 returned paths are sufficiently qualified so that they match exactly
2621 one node in the current tree.
2622 This function returns a NULL-terminated array of strings (like
2624 environ(3)), or NULL if there was an error. The caller must free the
2625 strings and the array after use.
2626 (Added in 0.7)
2628 guestfs_aug_mv
2630 int
2631 guestfs_aug_mv (guestfs_h *g,
2632 const char *src,
2633 const char *dest);
2634 Move the node "src" to "dest". "src" must match exactly one node.
2636 "dest" is overwritten if it exists.
2637 This function returns 0 on success or -1 on error.
2639 (Added in 0.7)
2641 guestfs_aug_rm
2643 int
2644 guestfs_aug_rm (guestfs_h *g,
2645 const char *augpath);
2646 Remove "path" and all of its children.
2648 On success this returns the number of entries which were removed.
2650 On error this function returns -1.
2652 (Added in 0.7)
2654 guestfs_aug_save
2656 int
2657 guestfs_aug_save (guestfs_h *g);
2658 This writes all pending changes to disk.
2660 The flags which were passed to "guestfs_aug_init" affect exactly how
2662 files are saved.
2663 This function returns 0 on success or -1 on error.
2665 (Added in 0.7)
2667 guestfs_aug_set
2669 int
2670 guestfs_aug_set (guestfs_h *g,
2671 const char *augpath,
2672 const char *val);
2673 Set the value associated with "path" to "val".
2675 In the Augeas API, it is possible to clear a node by setting the value
2677 to NULL. Due to an oversight in the libguestfs API you cannot do that
2678 with this call. Instead you must use the "guestfs_aug_clear" call.
2679 This function returns 0 on success or -1 on error.
2681 (Added in 0.7)
2683 guestfs_aug_setm
2685 int
2686 guestfs_aug_setm (guestfs_h *g,
2687 const char *base,
2688 const char *sub,
2689 const char *val);
2690 Change multiple Augeas nodes in a single operation. "base" is an
2692 expression matching multiple nodes. "sub" is a path expression
2693 relative to "base". All nodes matching "base" are found, and then for
2694 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2695 which case the "base" nodes are modified.
2696 This returns the number of nodes modified.
2698 On error this function returns -1.
2700 (Added in 1.23.14)
2702 guestfs_aug_transform
2704 int
2705 guestfs_aug_transform (guestfs_h *g,
2706 const char *lens,
2707 const char *file,
2708 ...);
2709 You may supply a list of optional arguments to this call. Use zero or
2711 more of the following pairs of parameters, and terminate the list with
2712 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2713 GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2715 Add an Augeas transformation for the specified "lens" so it can handle
2717 "file".
2718 If "remove" is true ("false" by default), then the transformation is
2720 removed.
2721 This function returns 0 on success or -1 on error.
2723 (Added in 1.35.2)
2725 guestfs_aug_transform_va
2727 int
2728 guestfs_aug_transform_va (guestfs_h *g,
2729 const char *lens,
2730 const char *file,
2731 va_list args);
2732 This is the "va_list variant" of "guestfs_aug_transform".
2734 See "CALLS WITH OPTIONAL ARGUMENTS".
2736 guestfs_aug_transform_argv
2738 int
2739 guestfs_aug_transform_argv (guestfs_h *g,
2740 const char *lens,
2741 const char *file,
2742 const struct guestfs_aug_transform_argv *optargs);
2743 This is the "argv variant" of "guestfs_aug_transform".
2745 See "CALLS WITH OPTIONAL ARGUMENTS".
2747 guestfs_available
2749 int
2750 guestfs_available (guestfs_h *g,
2751 char *const *groups);
2752 This command is used to check the availability of some groups of
2754 functionality in the appliance, which not all builds of the libguestfs
2755 appliance will be able to provide.
2756 The libguestfs groups, and the functions that those groups correspond
2758 to, are listed in "AVAILABILITY". You can also fetch this list at
2759 runtime by calling "guestfs_available_all_groups".
2760 The argument "groups" is a list of group names, eg: "["inotify",
2762 "augeas"]" would check for the availability of the Linux inotify
2763 functions and Augeas (configuration file editing) functions.
2764 The command returns no error if all requested groups are available.
2766 It fails with an error if one or more of the requested groups is
2768 unavailable in the appliance.
2769 If an unknown group name is included in the list of groups then an
2771 error is always returned.
2772 Notes:
2774 · "guestfs_feature_available" is the same as this call, but with a
2776 slightly simpler to use API: that call returns a boolean true/false
2777 instead of throwing an error.
2778 · You must call "guestfs_launch" before calling this function.
2780 The reason is because we don't know what groups are supported by
2782 the appliance/daemon until it is running and can be queried.
2783 · If a group of functions is available, this does not necessarily
2785 mean that they will work. You still have to check for errors when
2786 calling individual API functions even if they are available.
2787 · It is usually the job of distro packagers to build complete
2789 functionality into the libguestfs appliance. Upstream libguestfs,
2790 if built from source with all requirements satisfied, will support
2791 everything.
2792 · This call was added in version 1.0.80. In previous versions of
2794 libguestfs all you could do would be to speculatively execute a
2795 command to find out if the daemon implemented it. See also
2796 "guestfs_version".
2797 See also "guestfs_filesystem_available".
2799 This function returns 0 on success or -1 on error.
2801 (Added in 1.0.80)
2803 guestfs_available_all_groups
2805 char **
2806 guestfs_available_all_groups (guestfs_h *g);
2807 This command returns a list of all optional groups that this daemon
2809 knows about. Note this returns both supported and unsupported groups.
2810 To find out which ones the daemon can actually support you have to call
2811 "guestfs_available" / "guestfs_feature_available" on each member of the
2812 returned list.
2813 See also "guestfs_available", "guestfs_feature_available" and
2815 "AVAILABILITY".
2816 This function returns a NULL-terminated array of strings (like
2818 environ(3)), or NULL if there was an error. The caller must free the
2819 strings and the array after use.
2820 (Added in 1.3.15)
2822 guestfs_base64_in
2824 int
2825 guestfs_base64_in (guestfs_h *g,
2826 const char *base64file,
2827 const char *filename);
2828 This command uploads base64-encoded data from "base64file" to filename.
2830 This function returns 0 on success or -1 on error.
2832 (Added in 1.3.5)
2834 guestfs_base64_out
2836 int
2837 guestfs_base64_out (guestfs_h *g,
2838 const char *filename,
2839 const char *base64file);
2840 This command downloads the contents of filename, writing it out to
2842 local file "base64file" encoded as base64.
2843 This function returns 0 on success or -1 on error.
2845 (Added in 1.3.5)
2847 guestfs_blkdiscard
2849 int
2850 guestfs_blkdiscard (guestfs_h *g,
2851 const char *device);
2852 This discards all blocks on the block device "device", giving the free
2854 space back to the host.
2855 This operation requires support in libguestfs, the host filesystem,
2857 qemu and the host kernel. If this support isn't present it may give an
2858 error or even appear to run but do nothing. You must also set the
2859 "discard" attribute on the underlying drive (see
2860 "guestfs_add_drive_opts").
2861 This function returns 0 on success or -1 on error.
2863 This function depends on the feature "blkdiscard". See also
2865 "guestfs_feature_available".
2866 (Added in 1.25.44)
2868 guestfs_blkdiscardzeroes
2870 int
2871 guestfs_blkdiscardzeroes (guestfs_h *g,
2872 const char *device);
2873 This call returns true if blocks on "device" that have been discarded
2875 by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
2876 when read the next time.
2877 If it returns false, then it may be that discarded blocks are read as
2879 stale or random data.
2880 This function returns a C truth value on success or -1 on error.
2882 This function depends on the feature "blkdiscardzeroes". See also
2884 "guestfs_feature_available".
2885 (Added in 1.25.44)
2887 guestfs_blkid
2889 char **
2890 guestfs_blkid (guestfs_h *g,
2891 const char *device);
2892 This command returns block device attributes for "device". The
2894 following fields are usually present in the returned hash. Other fields
2895 may also be present.
2896 "UUID"
2898 The uuid of this device.
2899 "LABEL"
2901 The label of this device.
2902 "VERSION"
2904 The version of blkid command.
2905 "TYPE"
2907 The filesystem type or RAID of this device.
2908 "USAGE"
2910 The usage of this device, for example "filesystem" or "raid".
2911 This function returns a NULL-terminated array of strings, or NULL if
2913 there was an error. The array of strings will always have length
2914 "2n+1", where "n" keys and values alternate, followed by the trailing
2915 NULL entry. The caller must free the strings and the array after use.
2916 (Added in 1.15.9)
2918 guestfs_blockdev_flushbufs
2920 int
2921 guestfs_blockdev_flushbufs (guestfs_h *g,
2922 const char *device);
2923 This tells the kernel to flush internal buffers associated with
2925 "device".
2926 This uses the blockdev(8) command.
2928 This function returns 0 on success or -1 on error.
2930 (Added in 1.9.3)
2932 guestfs_blockdev_getbsz
2934 int
2935 guestfs_blockdev_getbsz (guestfs_h *g,
2936 const char *device);
2937 This returns the block size of a device.
2939 Note: this is different from both size in blocks and filesystem block
2941 size. Also this setting is not really used by anything. You should
2942 probably not use it for anything. Filesystems have their own idea
2943 about what block size to choose.
2944 This uses the blockdev(8) command.
2946 On error this function returns -1.
2948 (Added in 1.9.3)
2950 guestfs_blockdev_getro
2952 int
2953 guestfs_blockdev_getro (guestfs_h *g,
2954 const char *device);
2955 Returns a boolean indicating if the block device is read-only (true if
2957 read-only, false if not).
2958 This uses the blockdev(8) command.
2960 This function returns a C truth value on success or -1 on error.
2962 (Added in 1.9.3)
2964 guestfs_blockdev_getsize64
2966 int64_t
2967 guestfs_blockdev_getsize64 (guestfs_h *g,
2968 const char *device);
2969 This returns the size of the device in bytes.
2971 See also "guestfs_blockdev_getsz".
2973 This uses the blockdev(8) command.
2975 On error this function returns -1.
2977 (Added in 1.9.3)
2979 guestfs_blockdev_getss
2981 int
2982 guestfs_blockdev_getss (guestfs_h *g,
2983 const char *device);
2984 This returns the size of sectors on a block device. Usually 512, but
2986 can be larger for modern devices.
2987 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
2989 for that).
2990 This uses the blockdev(8) command.
2992 On error this function returns -1.
2994 (Added in 1.9.3)
2996 guestfs_blockdev_getsz
2998 int64_t
2999 guestfs_blockdev_getsz (guestfs_h *g,
3000 const char *device);
3001 This returns the size of the device in units of 512-byte sectors (even
3003 if the sectorsize isn't 512 bytes ... weird).
3004 See also "guestfs_blockdev_getss" for the real sector size of the
3006 device, and "guestfs_blockdev_getsize64" for the more useful size in
3007 bytes.
3008 This uses the blockdev(8) command.
3010 On error this function returns -1.
3012 (Added in 1.9.3)
3014 guestfs_blockdev_rereadpt
3016 int
3017 guestfs_blockdev_rereadpt (guestfs_h *g,
3018 const char *device);
3019 Reread the partition table on "device".
3021 This uses the blockdev(8) command.
3023 This function returns 0 on success or -1 on error.
3025 (Added in 1.9.3)
3027 guestfs_blockdev_setbsz
3029 int
3030 guestfs_blockdev_setbsz (guestfs_h *g,
3031 const char *device,
3032 int blocksize);
3033 This function is deprecated. There is no replacement. Consult the API
3035 documentation in guestfs(3) for further information.
3036 Deprecated functions will not be removed from the API, but the fact
3038 that they are deprecated indicates that there are problems with correct
3039 use of these functions.
3040 This call does nothing and has never done anything because of a bug in
3042 blockdev. Do not use it.
3043 If you need to set the filesystem block size, use the "blocksize"
3045 option of "guestfs_mkfs".
3046 This function returns 0 on success or -1 on error.
3048 (Added in 1.9.3)
3050 guestfs_blockdev_setra
3052 int
3053 guestfs_blockdev_setra (guestfs_h *g,
3054 const char *device,
3055 int sectors);
3056 Set readahead (in 512-byte sectors) for the device.
3058 This uses the blockdev(8) command.
3060 This function returns 0 on success or -1 on error.
3062 (Added in 1.29.10)
3064 guestfs_blockdev_setro
3066 int
3067 guestfs_blockdev_setro (guestfs_h *g,
3068 const char *device);
3069 Sets the block device named "device" to read-only.
3071 This uses the blockdev(8) command.
3073 This function returns 0 on success or -1 on error.
3075 (Added in 1.9.3)
3077 guestfs_blockdev_setrw
3079 int
3080 guestfs_blockdev_setrw (guestfs_h *g,
3081 const char *device);
3082 Sets the block device named "device" to read-write.
3084 This uses the blockdev(8) command.
3086 This function returns 0 on success or -1 on error.
3088 (Added in 1.9.3)
3090 guestfs_btrfs_balance_cancel
3092 int
3093 guestfs_btrfs_balance_cancel (guestfs_h *g,
3094 const char *path);
3095 Cancel a running balance on a btrfs filesystem.
3097 This function returns 0 on success or -1 on error.
3099 This function depends on the feature "btrfs". See also
3101 "guestfs_feature_available".
3102 (Added in 1.29.22)
3104 guestfs_btrfs_balance_pause
3106 int
3107 guestfs_btrfs_balance_pause (guestfs_h *g,
3108 const char *path);
3109 Pause a running balance on a btrfs filesystem.
3111 This function returns 0 on success or -1 on error.
3113 This function depends on the feature "btrfs". See also
3115 "guestfs_feature_available".
3116 (Added in 1.29.22)
3118 guestfs_btrfs_balance_resume
3120 int
3121 guestfs_btrfs_balance_resume (guestfs_h *g,
3122 const char *path);
3123 Resume a paused balance on a btrfs filesystem.
3125 This function returns 0 on success or -1 on error.
3127 This function depends on the feature "btrfs". See also
3129 "guestfs_feature_available".
3130 (Added in 1.29.22)
3132 guestfs_btrfs_balance_status
3134 struct guestfs_btrfsbalance *
3135 guestfs_btrfs_balance_status (guestfs_h *g,
3136 const char *path);
3137 Show the status of a running or paused balance on a btrfs filesystem.
3139 This function returns a "struct guestfs_btrfsbalance *", or NULL if
3141 there was an error. The caller must call "guestfs_free_btrfsbalance"
3142 after use.
3143 This function depends on the feature "btrfs". See also
3145 "guestfs_feature_available".
3146 (Added in 1.29.26)
3148 guestfs_btrfs_device_add
3150 int
3151 guestfs_btrfs_device_add (guestfs_h *g,
3152 char *const *devices,
3153 const char *fs);
3154 Add the list of device(s) in "devices" to the btrfs filesystem mounted
3156 at "fs". If "devices" is an empty list, this does nothing.
3157 This function returns 0 on success or -1 on error.
3159 This function depends on the feature "btrfs". See also
3161 "guestfs_feature_available".
3162 (Added in 1.17.35)
3164 guestfs_btrfs_device_delete
3166 int
3167 guestfs_btrfs_device_delete (guestfs_h *g,
3168 char *const *devices,
3169 const char *fs);
3170 Remove the "devices" from the btrfs filesystem mounted at "fs". If
3172 "devices" is an empty list, this does nothing.
3173 This function returns 0 on success or -1 on error.
3175 This function depends on the feature "btrfs". See also
3177 "guestfs_feature_available".
3178 (Added in 1.17.35)
3180 guestfs_btrfs_filesystem_balance
3182 int
3183 guestfs_btrfs_filesystem_balance (guestfs_h *g,
3184 const char *fs);
3185 Balance the chunks in the btrfs filesystem mounted at "fs" across the
3187 underlying devices.
3188 This function returns 0 on success or -1 on error.
3190 This function depends on the feature "btrfs". See also
3192 "guestfs_feature_available".
3193 (Added in 1.17.35)
3195 guestfs_btrfs_filesystem_defragment
3197 int
3198 guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3199 const char *path,
3200 ...);
3201 You may supply a list of optional arguments to this call. Use zero or
3203 more of the following pairs of parameters, and terminate the list with
3204 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3205 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3207 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3208 Defragment a file or directory on a btrfs filesystem. compress is one
3210 of zlib or lzo.
3211 This function returns 0 on success or -1 on error.
3213 This function depends on the feature "btrfs". See also
3215 "guestfs_feature_available".
3216 (Added in 1.29.22)
3218 guestfs_btrfs_filesystem_defragment_va
3220 int
3221 guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3222 const char *path,
3223 va_list args);
3224 This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3226 See "CALLS WITH OPTIONAL ARGUMENTS".
3228 guestfs_btrfs_filesystem_defragment_argv
3230 int
3231 guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3232 const char *path,
3233 const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3234 This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3236 See "CALLS WITH OPTIONAL ARGUMENTS".
3238 guestfs_btrfs_filesystem_resize
3240 int
3241 guestfs_btrfs_filesystem_resize (guestfs_h *g,
3242 const char *mountpoint,
3243 ...);
3244 You may supply a list of optional arguments to this call. Use zero or
3246 more of the following pairs of parameters, and terminate the list with
3247 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3248 GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3250 This command resizes a btrfs filesystem.
3252 Note that unlike other resize calls, the filesystem has to be mounted
3254 and the parameter is the mountpoint not the device (this is a
3255 requirement of btrfs itself).
3256 The optional parameters are:
3258 "size"
3260 The new size (in bytes) of the filesystem. If omitted, the
3261 filesystem is resized to the maximum size.
3262 See also btrfs(8).
3264 This function returns 0 on success or -1 on error.
3266 This function depends on the feature "btrfs". See also
3268 "guestfs_feature_available".
3269 (Added in 1.11.17)
3271 guestfs_btrfs_filesystem_resize_va
3273 int
3274 guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3275 const char *mountpoint,
3276 va_list args);
3277 This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3279 See "CALLS WITH OPTIONAL ARGUMENTS".
3281 guestfs_btrfs_filesystem_resize_argv
3283 int
3284 guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3285 const char *mountpoint,
3286 const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3287 This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3289 See "CALLS WITH OPTIONAL ARGUMENTS".
3291 guestfs_btrfs_filesystem_show
3293 char **
3294 guestfs_btrfs_filesystem_show (guestfs_h *g,
3295 const char *device);
3296 Show all the devices where the filesystems in "device" is spanned over.
3298 If not all the devices for the filesystems are present, then this
3300 function fails and the "errno" is set to "ENODEV".
3301 This function returns a NULL-terminated array of strings (like
3303 environ(3)), or NULL if there was an error. The caller must free the
3304 strings and the array after use.
3305 This function depends on the feature "btrfs". See also
3307 "guestfs_feature_available".
3308 (Added in 1.33.29)
3310 guestfs_btrfs_filesystem_sync
3312 int
3313 guestfs_btrfs_filesystem_sync (guestfs_h *g,
3314 const char *fs);
3315 Force sync on the btrfs filesystem mounted at "fs".
3317 This function returns 0 on success or -1 on error.
3319 This function depends on the feature "btrfs". See also
3321 "guestfs_feature_available".
3322 (Added in 1.17.35)
3324 guestfs_btrfs_fsck
3326 int
3327 guestfs_btrfs_fsck (guestfs_h *g,
3328 const char *device,
3329 ...);
3330 You may supply a list of optional arguments to this call. Use zero or
3332 more of the following pairs of parameters, and terminate the list with
3333 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3334 GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3336 GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3337 Used to check a btrfs filesystem, "device" is the device file where the
3339 filesystem is stored.
3340 This function returns 0 on success or -1 on error.
3342 This function depends on the feature "btrfs". See also
3344 "guestfs_feature_available".
3345 (Added in 1.17.43)
3347 guestfs_btrfs_fsck_va
3349 int
3350 guestfs_btrfs_fsck_va (guestfs_h *g,
3351 const char *device,
3352 va_list args);
3353 This is the "va_list variant" of "guestfs_btrfs_fsck".
3355 See "CALLS WITH OPTIONAL ARGUMENTS".
3357 guestfs_btrfs_fsck_argv
3359 int
3360 guestfs_btrfs_fsck_argv (guestfs_h *g,
3361 const char *device,
3362 const struct guestfs_btrfs_fsck_argv *optargs);
3363 This is the "argv variant" of "guestfs_btrfs_fsck".
3365 See "CALLS WITH OPTIONAL ARGUMENTS".
3367 guestfs_btrfs_image
3369 int
3370 guestfs_btrfs_image (guestfs_h *g,
3371 char *const *source,
3372 const char *image,
3373 ...);
3374 You may supply a list of optional arguments to this call. Use zero or
3376 more of the following pairs of parameters, and terminate the list with
3377 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3378 GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3380 This is used to create an image of a btrfs filesystem. All data will
3382 be zeroed, but metadata and the like is preserved.
3383 This function returns 0 on success or -1 on error.
3385 This function depends on the feature "btrfs". See also
3387 "guestfs_feature_available".
3388 (Added in 1.29.32)
3390 guestfs_btrfs_image_va
3392 int
3393 guestfs_btrfs_image_va (guestfs_h *g,
3394 char *const *source,
3395 const char *image,
3396 va_list args);
3397 This is the "va_list variant" of "guestfs_btrfs_image".
3399 See "CALLS WITH OPTIONAL ARGUMENTS".
3401 guestfs_btrfs_image_argv
3403 int
3404 guestfs_btrfs_image_argv (guestfs_h *g,
3405 char *const *source,
3406 const char *image,
3407 const struct guestfs_btrfs_image_argv *optargs);
3408 This is the "argv variant" of "guestfs_btrfs_image".
3410 See "CALLS WITH OPTIONAL ARGUMENTS".
3412 guestfs_btrfs_qgroup_assign
3414 int
3415 guestfs_btrfs_qgroup_assign (guestfs_h *g,
3416 const char *src,
3417 const char *dst,
3418 const char *path);
3419 Add qgroup "src" to parent qgroup "dst". This command can group several
3421 qgroups into a parent qgroup to share common limit.
3422 This function returns 0 on success or -1 on error.
3424 This function depends on the feature "btrfs". See also
3426 "guestfs_feature_available".
3427 (Added in 1.29.17)
3429 guestfs_btrfs_qgroup_create
3431 int
3432 guestfs_btrfs_qgroup_create (guestfs_h *g,
3433 const char *qgroupid,
3434 const char *subvolume);
3435 Create a quota group (qgroup) for subvolume at "subvolume".
3437 This function returns 0 on success or -1 on error.
3439 This function depends on the feature "btrfs". See also
3441 "guestfs_feature_available".
3442 (Added in 1.29.17)
3444 guestfs_btrfs_qgroup_destroy
3446 int
3447 guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3448 const char *qgroupid,
3449 const char *subvolume);
3450 Destroy a quota group.
3452 This function returns 0 on success or -1 on error.
3454 This function depends on the feature "btrfs". See also
3456 "guestfs_feature_available".
3457 (Added in 1.29.17)
3459 guestfs_btrfs_qgroup_limit
3461 int
3462 guestfs_btrfs_qgroup_limit (guestfs_h *g,
3463 const char *subvolume,
3464 int64_t size);
3465 Limit the size of the subvolume with path "subvolume".
3467 This function returns 0 on success or -1 on error.
3469 This function depends on the feature "btrfs". See also
3471 "guestfs_feature_available".
3472 (Added in 1.29.17)
3474 guestfs_btrfs_qgroup_remove
3476 int
3477 guestfs_btrfs_qgroup_remove (guestfs_h *g,
3478 const char *src,
3479 const char *dst,
3480 const char *path);
3481 Remove qgroup "src" from the parent qgroup "dst".
3483 This function returns 0 on success or -1 on error.
3485 This function depends on the feature "btrfs". See also
3487 "guestfs_feature_available".
3488 (Added in 1.29.17)
3490 guestfs_btrfs_qgroup_show
3492 struct guestfs_btrfsqgroup_list *
3493 guestfs_btrfs_qgroup_show (guestfs_h *g,
3494 const char *path);
3495 Show all subvolume quota groups in a btrfs filesystem, including their
3497 usages.
3498 This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3500 there was an error. The caller must call
3501 "guestfs_free_btrfsqgroup_list" after use.
3502 This function depends on the feature "btrfs". See also
3504 "guestfs_feature_available".
3505 (Added in 1.29.17)
3507 guestfs_btrfs_quota_enable
3509 int
3510 guestfs_btrfs_quota_enable (guestfs_h *g,
3511 const char *fs,
3512 int enable);
3513 Enable or disable subvolume quota support for filesystem which contains
3515 "path".
3516 This function returns 0 on success or -1 on error.
3518 This function depends on the feature "btrfs". See also
3520 "guestfs_feature_available".
3521 (Added in 1.29.17)
3523 guestfs_btrfs_quota_rescan
3525 int
3526 guestfs_btrfs_quota_rescan (guestfs_h *g,
3527 const char *fs);
3528 Trash all qgroup numbers and scan the metadata again with the current
3530 config.
3531 This function returns 0 on success or -1 on error.
3533 This function depends on the feature "btrfs". See also
3535 "guestfs_feature_available".
3536 (Added in 1.29.17)
3538 guestfs_btrfs_replace
3540 int
3541 guestfs_btrfs_replace (guestfs_h *g,
3542 const char *srcdev,
3543 const char *targetdev,
3544 const char *mntpoint);
3545 Replace device of a btrfs filesystem. On a live filesystem, duplicate
3547 the data to the target device which is currently stored on the source
3548 device. After completion of the operation, the source device is wiped
3549 out and removed from the filesystem.
3550 The "targetdev" needs to be same size or larger than the "srcdev".
3552 Devices which are currently mounted are never allowed to be used as the
3553 "targetdev".
3554 This function returns 0 on success or -1 on error.
3556 This function depends on the feature "btrfs". See also
3558 "guestfs_feature_available".
3559 (Added in 1.29.48)
3561 guestfs_btrfs_rescue_chunk_recover
3563 int
3564 guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3565 const char *device);
3566 Recover the chunk tree of btrfs filesystem by scanning the devices one
3568 by one.
3569 This function returns 0 on success or -1 on error.
3571 This function depends on the feature "btrfs". See also
3573 "guestfs_feature_available".
3574 (Added in 1.29.22)
3576 guestfs_btrfs_rescue_super_recover
3578 int
3579 guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3580 const char *device);
3581 Recover bad superblocks from good copies.
3583 This function returns 0 on success or -1 on error.
3585 This function depends on the feature "btrfs". See also
3587 "guestfs_feature_available".
3588 (Added in 1.29.22)
3590 guestfs_btrfs_scrub_cancel
3592 int
3593 guestfs_btrfs_scrub_cancel (guestfs_h *g,
3594 const char *path);
3595 Cancel a running scrub on a btrfs filesystem.
3597 This function returns 0 on success or -1 on error.
3599 This function depends on the feature "btrfs". See also
3601 "guestfs_feature_available".
3602 (Added in 1.29.22)
3604 guestfs_btrfs_scrub_resume
3606 int
3607 guestfs_btrfs_scrub_resume (guestfs_h *g,
3608 const char *path);
3609 Resume a previously canceled or interrupted scrub on a btrfs
3611 filesystem.
3612 This function returns 0 on success or -1 on error.
3614 This function depends on the feature "btrfs". See also
3616 "guestfs_feature_available".
3617 (Added in 1.29.22)
3619 guestfs_btrfs_scrub_start
3621 int
3622 guestfs_btrfs_scrub_start (guestfs_h *g,
3623 const char *path);
3624 Reads all the data and metadata on the filesystem, and uses checksums
3626 and the duplicate copies from RAID storage to identify and repair any
3627 corrupt data.
3628 This function returns 0 on success or -1 on error.
3630 This function depends on the feature "btrfs". See also
3632 "guestfs_feature_available".
3633 (Added in 1.29.22)
3635 guestfs_btrfs_scrub_status
3637 struct guestfs_btrfsscrub *
3638 guestfs_btrfs_scrub_status (guestfs_h *g,
3639 const char *path);
3640 Show status of running or finished scrub on a btrfs filesystem.
3642 This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3644 was an error. The caller must call "guestfs_free_btrfsscrub" after
3645 use.
3646 This function depends on the feature "btrfs". See also
3648 "guestfs_feature_available".
3649 (Added in 1.29.26)
3651 guestfs_btrfs_set_seeding
3653 int
3654 guestfs_btrfs_set_seeding (guestfs_h *g,
3655 const char *device,
3656 int seeding);
3657 Enable or disable the seeding feature of a device that contains a btrfs
3659 filesystem.
3660 This function returns 0 on success or -1 on error.
3662 This function depends on the feature "btrfs". See also
3664 "guestfs_feature_available".
3665 (Added in 1.17.43)
3667 guestfs_btrfs_subvolume_create
3669 int
3670 guestfs_btrfs_subvolume_create (guestfs_h *g,
3671 const char *dest);
3672 This function is provided for backwards compatibility with earlier
3674 versions of libguestfs. It simply calls
3675 "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3676 (Added in 1.17.35)
3678 guestfs_btrfs_subvolume_create_opts
3680 int
3681 guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3682 const char *dest,
3683 ...);
3684 You may supply a list of optional arguments to this call. Use zero or
3686 more of the following pairs of parameters, and terminate the list with
3687 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3688 GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3690 Create a btrfs subvolume. The "dest" argument is the destination
3692 directory and the name of the subvolume, in the form
3693 /path/to/dest/name. The optional parameter "qgroupid" represents the
3694 qgroup which the newly created subvolume will be added to.
3695 This function returns 0 on success or -1 on error.
3697 This function depends on the feature "btrfs". See also
3699 "guestfs_feature_available".
3700 (Added in 1.17.35)
3702 guestfs_btrfs_subvolume_create_opts_va
3704 int
3705 guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3706 const char *dest,
3707 va_list args);
3708 This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3710 See "CALLS WITH OPTIONAL ARGUMENTS".
3712 guestfs_btrfs_subvolume_create_opts_argv
3714 int
3715 guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3716 const char *dest,
3717 const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3718 This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3720 See "CALLS WITH OPTIONAL ARGUMENTS".
3722 guestfs_btrfs_subvolume_delete
3724 int
3725 guestfs_btrfs_subvolume_delete (guestfs_h *g,
3726 const char *subvolume);
3727 Delete the named btrfs subvolume or snapshot.
3729 This function returns 0 on success or -1 on error.
3731 This function depends on the feature "btrfs". See also
3733 "guestfs_feature_available".
3734 (Added in 1.17.35)
3736 guestfs_btrfs_subvolume_get_default
3738 int64_t
3739 guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3740 const char *fs);
3741 Get the default subvolume or snapshot of a filesystem mounted at
3743 "mountpoint".
3744 On error this function returns -1.
3746 This function depends on the feature "btrfs". See also
3748 "guestfs_feature_available".
3749 (Added in 1.29.17)
3751 guestfs_btrfs_subvolume_list
3753 struct guestfs_btrfssubvolume_list *
3754 guestfs_btrfs_subvolume_list (guestfs_h *g,
3755 const char *fs);
3756 List the btrfs snapshots and subvolumes of the btrfs filesystem which
3758 is mounted at "fs".
3759 This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3761 if there was an error. The caller must call
3762 "guestfs_free_btrfssubvolume_list" after use.
3763 This function depends on the feature "btrfs". See also
3765 "guestfs_feature_available".
3766 (Added in 1.17.35)
3768 guestfs_btrfs_subvolume_set_default
3770 int
3771 guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3772 int64_t id,
3773 const char *fs);
3774 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3776 default. See "guestfs_btrfs_subvolume_list" to get a list of
3777 subvolumes.
3778 This function returns 0 on success or -1 on error.
3780 This function depends on the feature "btrfs". See also
3782 "guestfs_feature_available".
3783 (Added in 1.17.35)
3785 guestfs_btrfs_subvolume_show
3787 char **
3788 guestfs_btrfs_subvolume_show (guestfs_h *g,
3789 const char *subvolume);
3790 Return detailed information of the subvolume.
3792 This function returns a NULL-terminated array of strings, or NULL if
3794 there was an error. The array of strings will always have length
3795 "2n+1", where "n" keys and values alternate, followed by the trailing
3796 NULL entry. The caller must free the strings and the array after use.
3797 This function depends on the feature "btrfs". See also
3799 "guestfs_feature_available".
3800 (Added in 1.29.17)
3802 guestfs_btrfs_subvolume_snapshot
3804 int
3805 guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3806 const char *source,
3807 const char *dest);
3808 This function is provided for backwards compatibility with earlier
3810 versions of libguestfs. It simply calls
3811 "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3812 (Added in 1.17.35)
3814 guestfs_btrfs_subvolume_snapshot_opts
3816 int
3817 guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3818 const char *source,
3819 const char *dest,
3820 ...);
3821 You may supply a list of optional arguments to this call. Use zero or
3823 more of the following pairs of parameters, and terminate the list with
3824 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3825 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3827 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3828 Create a snapshot of the btrfs subvolume "source". The "dest" argument
3830 is the destination directory and the name of the snapshot, in the form
3831 /path/to/dest/name. By default the newly created snapshot is writable,
3832 if the value of optional parameter "ro" is true, then a readonly
3833 snapshot is created. The optional parameter "qgroupid" represents the
3834 qgroup which the newly created snapshot will be added to.
3835 This function returns 0 on success or -1 on error.
3837 This function depends on the feature "btrfs". See also
3839 "guestfs_feature_available".
3840 (Added in 1.17.35)
3842 guestfs_btrfs_subvolume_snapshot_opts_va
3844 int
3845 guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
3846 const char *source,
3847 const char *dest,
3848 va_list args);
3849 This is the "va_list variant" of
3851 "guestfs_btrfs_subvolume_snapshot_opts".
3852 See "CALLS WITH OPTIONAL ARGUMENTS".
3854 guestfs_btrfs_subvolume_snapshot_opts_argv
3856 int
3857 guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
3858 const char *source,
3859 const char *dest,
3860 const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
3861 This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
3863 See "CALLS WITH OPTIONAL ARGUMENTS".
3865 guestfs_btrfstune_enable_extended_inode_refs
3867 int
3868 guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
3869 const char *device);
3870 This will Enable extended inode refs.
3872 This function returns 0 on success or -1 on error.
3874 This function depends on the feature "btrfs". See also
3876 "guestfs_feature_available".
3877 (Added in 1.29.29)
3879 guestfs_btrfstune_enable_skinny_metadata_extent_refs
3881 int
3882 guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
3883 const char *device);
3884 This enable skinny metadata extent refs.
3886 This function returns 0 on success or -1 on error.
3888 This function depends on the feature "btrfs". See also
3890 "guestfs_feature_available".
3891 (Added in 1.29.29)
3893 guestfs_btrfstune_seeding
3895 int
3896 guestfs_btrfstune_seeding (guestfs_h *g,
3897 const char *device,
3898 int seeding);
3899 Enable seeding of a btrfs device, this will force a fs readonly so that
3901 you can use it to build other filesystems.
3902 This function returns 0 on success or -1 on error.
3904 This function depends on the feature "btrfs". See also
3906 "guestfs_feature_available".
3907 (Added in 1.29.29)
3909 guestfs_c_pointer
3911 int64_t
3912 guestfs_c_pointer (guestfs_h *g);
3913 In non-C language bindings, this allows you to retrieve the underlying
3915 C pointer to the handle (ie. "guestfs_h *"). The purpose of this is to
3916 allow other libraries to interwork with libguestfs.
3917 On error this function returns -1.
3919 (Added in 1.29.17)
3921 guestfs_canonical_device_name
3923 char *
3924 guestfs_canonical_device_name (guestfs_h *g,
3925 const char *device);
3926 This utility function is useful when displaying device names to the
3928 user. It takes a number of irregular device names and returns them in
3929 a consistent format:
3930 /dev/hdX
3932 /dev/vdX
3933 These are returned as /dev/sdX. Note this works for device names
3934 and partition names. This is approximately the reverse of the
3935 algorithm described in "BLOCK DEVICE NAMING".
3936 /dev/mapper/VG-LV
3938 /dev/dm-N
3939 Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
3940 Other strings are returned unmodified.
3942 This function returns a string, or NULL on error. The caller must free
3944 the returned string after use.
3945 (Added in 1.19.7)
3947 guestfs_cap_get_file
3949 char *
3950 guestfs_cap_get_file (guestfs_h *g,
3951 const char *path);
3952 This function returns the Linux capabilities attached to "path". The
3954 capabilities set is returned in text form (see cap_to_text(3)).
3955 If no capabilities are attached to a file, an empty string is returned.
3957 This function returns a string, or NULL on error. The caller must free
3959 the returned string after use.
3960 This function depends on the feature "linuxcaps". See also
3962 "guestfs_feature_available".
3963 (Added in 1.19.63)
3965 guestfs_cap_set_file
3967 int
3968 guestfs_cap_set_file (guestfs_h *g,
3969 const char *path,
3970 const char *cap);
3971 This function sets the Linux capabilities attached to "path". The
3973 capabilities set "cap" should be passed in text form (see
3974 cap_from_text(3)).
3975 This function returns 0 on success or -1 on error.
3977 This function depends on the feature "linuxcaps". See also
3979 "guestfs_feature_available".
3980 (Added in 1.19.63)
3982 guestfs_case_sensitive_path
3984 char *
3985 guestfs_case_sensitive_path (guestfs_h *g,
3986 const char *path);
3987 This can be used to resolve case insensitive paths on a filesystem
3989 which is case sensitive. The use case is to resolve paths which you
3990 have read from Windows configuration files or the Windows Registry, to
3991 the true path.
3992 The command handles a peculiarity of the Linux ntfs-3g filesystem
3994 driver (and probably others), which is that although the underlying
3995 filesystem is case-insensitive, the driver exports the filesystem to
3996 Linux as case-sensitive.
3997 One consequence of this is that special directories such as C:\windows
3999 may appear as /WINDOWS or /windows (or other things) depending on the
4000 precise details of how they were created. In Windows itself this would
4001 not be a problem.
4002 Bug or feature? You decide:
4004 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4005 "guestfs_case_sensitive_path" attempts to resolve the true case of each
4007 element in the path. It will return a resolved path if either the full
4008 path or its parent directory exists. If the parent directory exists but
4009 the full path does not, the case of the parent directory will be
4010 correctly resolved, and the remainder appended unmodified. For example,
4011 if the file "/Windows/System32/netkvm.sys" exists:
4012 "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4014 "Windows/System32/netkvm.sys"
4015 "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4017 "Windows/System32/NoSuchFile"
4018 "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4020 ERROR
4021 Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4023 cannot be used to check for the existence of a file.
4024 Note: This function does not handle drive names, backslashes etc.
4026 See also "guestfs_realpath".
4028 This function returns a string, or NULL on error. The caller must free
4030 the returned string after use.
4031 (Added in 1.0.75)
4033 guestfs_cat
4035 char *
4036 guestfs_cat (guestfs_h *g,
4037 const char *path);
4038 Return the contents of the file named "path".
4040 Because, in C, this function returns a "char *", there is no way to
4042 differentiate between a "\0" character in a file and end of string. To
4043 handle binary files, use the "guestfs_read_file" or "guestfs_download"
4044 functions.
4045 This function returns a string, or NULL on error. The caller must free
4047 the returned string after use.
4048 (Added in 0.4)
4050 guestfs_checksum
4052 char *
4053 guestfs_checksum (guestfs_h *g,
4054 const char *csumtype,
4055 const char *path);
4056 This call computes the MD5, SHAx or CRC checksum of the file named
4058 "path".
4059 The type of checksum to compute is given by the "csumtype" parameter
4061 which must have one of the following values:
4062 "crc"
4064 Compute the cyclic redundancy check (CRC) specified by POSIX for
4065 the "cksum" command.
4066 "md5"
4068 Compute the MD5 hash (using the "md5sum" program).
4069 "sha1"
4071 Compute the SHA1 hash (using the "sha1sum" program).
4072 "sha224"
4074 Compute the SHA224 hash (using the "sha224sum" program).
4075 "sha256"
4077 Compute the SHA256 hash (using the "sha256sum" program).
4078 "sha384"
4080 Compute the SHA384 hash (using the "sha384sum" program).
4081 "sha512"
4083 Compute the SHA512 hash (using the "sha512sum" program).
4084 The checksum is returned as a printable string.
4086 To get the checksum for a device, use "guestfs_checksum_device".
4088 To get the checksums for many files, use "guestfs_checksums_out".
4090 This function returns a string, or NULL on error. The caller must free
4092 the returned string after use.
4093 (Added in 1.0.2)
4095 guestfs_checksum_device
4097 char *
4098 guestfs_checksum_device (guestfs_h *g,
4099 const char *csumtype,
4100 const char *device);
4101 This call computes the MD5, SHAx or CRC checksum of the contents of the
4103 device named "device". For the types of checksums supported see the
4104 "guestfs_checksum" command.
4105 This function returns a string, or NULL on error. The caller must free
4107 the returned string after use.
4108 (Added in 1.3.2)
4110 guestfs_checksums_out
4112 int
4113 guestfs_checksums_out (guestfs_h *g,
4114 const char *csumtype,
4115 const char *directory,
4116 const char *sumsfile);
4117 This command computes the checksums of all regular files in directory
4119 and then emits a list of those checksums to the local output file
4120 "sumsfile".
4121 This can be used for verifying the integrity of a virtual machine.
4123 However to be properly secure you should pay attention to the output of
4124 the checksum command (it uses the ones from GNU coreutils). In
4125 particular when the filename is not printable, coreutils uses a special
4126 backslash syntax. For more information, see the GNU coreutils info
4127 file.
4128 This function returns 0 on success or -1 on error.
4130 (Added in 1.3.7)
4132 guestfs_chmod
4134 int
4135 guestfs_chmod (guestfs_h *g,
4136 int mode,
4137 const char *path);
4138 Change the mode (permissions) of "path" to "mode". Only numeric modes
4140 are supported.
4141 Note: When using this command from guestfish, "mode" by default would
4143 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4144 700.
4145 The mode actually set is affected by the umask.
4147 This function returns 0 on success or -1 on error.
4149 (Added in 0.8)
4151 guestfs_chown
4153 int
4154 guestfs_chown (guestfs_h *g,
4155 int owner,
4156 int group,
4157 const char *path);
4158 Change the file owner to "owner" and group to "group".
4160 Only numeric uid and gid are supported. If you want to use names, you
4162 will need to locate and parse the password file yourself (Augeas
4163 support makes this relatively easy).
4164 This function returns 0 on success or -1 on error.
4166 (Added in 0.8)
4168 guestfs_clear_backend_setting
4170 int
4171 guestfs_clear_backend_setting (guestfs_h *g,
4172 const char *name);
4173 If there is a backend setting string matching "name" or beginning with
4175 "name=", then that string is removed from the backend settings.
4176 This call returns the number of strings which were removed (which may
4178 be 0, 1 or greater than 1).
4179 See "BACKEND", "BACKEND SETTINGS".
4181 On error this function returns -1.
4183 (Added in 1.27.2)
4185 guestfs_command
4187 char *
4188 guestfs_command (guestfs_h *g,
4189 char *const *arguments);
4190 This call runs a command from the guest filesystem. The filesystem
4192 must be mounted, and must contain a compatible operating system (ie.
4193 something Linux, with the same or compatible processor architecture).
4194 The single parameter is an argv-style list of arguments. The first
4196 element is the name of the program to run. Subsequent elements are
4197 parameters. The list must be non-empty (ie. must contain a program
4198 name). Note that the command runs directly, and is not invoked via the
4199 shell (see "guestfs_sh").
4200 The return value is anything printed to stdout by the command.
4202 If the command returns a non-zero exit status, then this function
4204 returns an error message. The error message string is the content of
4205 stderr from the command.
4206 The $PATH environment variable will contain at least /usr/bin and /bin.
4208 If you require a program from another location, you should provide the
4209 full path in the first parameter.
4210 Shared libraries and data files required by the program must be
4212 available on filesystems which are mounted in the correct places. It
4213 is the caller’s responsibility to ensure all filesystems that are
4214 needed are mounted at the right locations.
4215 This function returns a string, or NULL on error. The caller must free
4217 the returned string after use.
4218 Because of the message protocol, there is a transfer limit of somewhere
4220 between 2MB and 4MB. See "PROTOCOL LIMITS".
4221 (Added in 1.9.1)
4223 guestfs_command_lines
4225 char **
4226 guestfs_command_lines (guestfs_h *g,
4227 char *const *arguments);
4228 This is the same as "guestfs_command", but splits the result into a
4230 list of lines.
4231 See also: "guestfs_sh_lines"
4233 This function returns a NULL-terminated array of strings (like
4235 environ(3)), or NULL if there was an error. The caller must free the
4236 strings and the array after use.
4237 Because of the message protocol, there is a transfer limit of somewhere
4239 between 2MB and 4MB. See "PROTOCOL LIMITS".
4240 (Added in 1.9.1)
4242 guestfs_compress_device_out
4244 int
4245 guestfs_compress_device_out (guestfs_h *g,
4246 const char *ctype,
4247 const char *device,
4248 const char *zdevice,
4249 ...);
4250 You may supply a list of optional arguments to this call. Use zero or
4252 more of the following pairs of parameters, and terminate the list with
4253 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4254 GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4256 This command compresses "device" and writes it out to the local file
4258 "zdevice".
4259 The "ctype" and optional "level" parameters have the same meaning as in
4261 "guestfs_compress_out".
4262 This function returns 0 on success or -1 on error.
4264 (Added in 1.13.15)
4266 guestfs_compress_device_out_va
4268 int
4269 guestfs_compress_device_out_va (guestfs_h *g,
4270 const char *ctype,
4271 const char *device,
4272 const char *zdevice,
4273 va_list args);
4274 This is the "va_list variant" of "guestfs_compress_device_out".
4276 See "CALLS WITH OPTIONAL ARGUMENTS".
4278 guestfs_compress_device_out_argv
4280 int
4281 guestfs_compress_device_out_argv (guestfs_h *g,
4282 const char *ctype,
4283 const char *device,
4284 const char *zdevice,
4285 const struct guestfs_compress_device_out_argv *optargs);
4286 This is the "argv variant" of "guestfs_compress_device_out".
4288 See "CALLS WITH OPTIONAL ARGUMENTS".
4290 guestfs_compress_out
4292 int
4293 guestfs_compress_out (guestfs_h *g,
4294 const char *ctype,
4295 const char *file,
4296 const char *zfile,
4297 ...);
4298 You may supply a list of optional arguments to this call. Use zero or
4300 more of the following pairs of parameters, and terminate the list with
4301 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4302 GUESTFS_COMPRESS_OUT_LEVEL, int level,
4304 This command compresses file and writes it out to the local file zfile.
4306 The compression program used is controlled by the "ctype" parameter.
4308 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4309 Some compression types may not be supported by particular builds of
4310 libguestfs, in which case you will get an error containing the
4311 substring "not supported".
4312 The optional "level" parameter controls compression level. The meaning
4314 and default for this parameter depends on the compression program being
4315 used.
4316 This function returns 0 on success or -1 on error.
4318 (Added in 1.13.15)
4320 guestfs_compress_out_va
4322 int
4323 guestfs_compress_out_va (guestfs_h *g,
4324 const char *ctype,
4325 const char *file,
4326 const char *zfile,
4327 va_list args);
4328 This is the "va_list variant" of "guestfs_compress_out".
4330 See "CALLS WITH OPTIONAL ARGUMENTS".
4332 guestfs_compress_out_argv
4334 int
4335 guestfs_compress_out_argv (guestfs_h *g,
4336 const char *ctype,
4337 const char *file,
4338 const char *zfile,
4339 const struct guestfs_compress_out_argv *optargs);
4340 This is the "argv variant" of "guestfs_compress_out".
4342 See "CALLS WITH OPTIONAL ARGUMENTS".
4344 guestfs_config
4346 int
4347 guestfs_config (guestfs_h *g,
4348 const char *hvparam,
4349 const char *hvvalue);
4350 This can be used to add arbitrary hypervisor parameters of the form
4352 -param value. Actually it’s not quite arbitrary - we prevent you from
4353 setting some parameters which would interfere with parameters that we
4354 use.
4355 The first character of "hvparam" string must be a "-" (dash).
4357 "hvvalue" can be NULL.
4359 This function returns 0 on success or -1 on error.
4361 (Added in 0.3)
4363 guestfs_copy_attributes
4365 int
4366 guestfs_copy_attributes (guestfs_h *g,
4367 const char *src,
4368 const char *dest,
4369 ...);
4370 You may supply a list of optional arguments to this call. Use zero or
4372 more of the following pairs of parameters, and terminate the list with
4373 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4374 GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4376 GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4377 GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4378 GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4379 Copy the attributes of a path (which can be a file or a directory) to
4381 another path.
4382 By default "no" attribute is copied, so make sure to specify any (or
4384 "all" to copy everything).
4385 The optional arguments specify which attributes can be copied:
4387 "mode"
4389 Copy part of the file mode from "source" to "destination". Only the
4390 UNIX permissions and the sticky/setuid/setgid bits can be copied.
4391 "xattributes"
4393 Copy the Linux extended attributes (xattrs) from "source" to
4394 "destination". This flag does nothing if the linuxxattrs feature
4395 is not available (see "guestfs_feature_available").
4396 "ownership"
4398 Copy the owner uid and the group gid of "source" to "destination".
4399 "all"
4401 Copy all the attributes from "source" to "destination". Enabling it
4402 enables all the other flags, if they are not specified already.
4403 This function returns 0 on success or -1 on error.
4405 (Added in 1.25.21)
4407 guestfs_copy_attributes_va
4409 int
4410 guestfs_copy_attributes_va (guestfs_h *g,
4411 const char *src,
4412 const char *dest,
4413 va_list args);
4414 This is the "va_list variant" of "guestfs_copy_attributes".
4416 See "CALLS WITH OPTIONAL ARGUMENTS".
4418 guestfs_copy_attributes_argv
4420 int
4421 guestfs_copy_attributes_argv (guestfs_h *g,
4422 const char *src,
4423 const char *dest,
4424 const struct guestfs_copy_attributes_argv *optargs);
4425 This is the "argv variant" of "guestfs_copy_attributes".
4427 See "CALLS WITH OPTIONAL ARGUMENTS".
4429 guestfs_copy_device_to_device
4431 int
4432 guestfs_copy_device_to_device (guestfs_h *g,
4433 const char *src,
4434 const char *dest,
4435 ...);
4436 You may supply a list of optional arguments to this call. Use zero or
4438 more of the following pairs of parameters, and terminate the list with
4439 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4440 GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4442 GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4443 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4444 GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4445 GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4446 The four calls "guestfs_copy_device_to_device",
4448 "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4449 "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4450 a destination (device|file).
4451 Partial copies can be made since you can specify optionally the source
4453 offset, destination offset and size to copy. These values are all
4454 specified in bytes. If not given, the offsets both default to zero,
4455 and the size defaults to copying as much as possible until we hit the
4456 end of the source.
4457 The source and destination may be the same object. However overlapping
4459 regions may not be copied correctly.
4460 If the destination is a file, it is created if required. If the
4462 destination file is not large enough, it is extended.
4463 If the destination is a file and the "append" flag is not set, then the
4465 destination file is truncated. If the "append" flag is set, then the
4466 copy appends to the destination file. The "append" flag currently
4467 cannot be set for devices.
4468 If the "sparse" flag is true then the call avoids writing blocks that
4470 contain only zeroes, which can help in some situations where the
4471 backing disk is thin-provisioned. Note that unless the target is
4472 already zeroed, using this option will result in incorrect copying.
4473 This function returns 0 on success or -1 on error.
4475 This long-running command can generate progress notification messages
4477 so that the caller can display a progress bar or indicator. To receive
4478 these messages, the caller must register a progress event callback.
4479 See "GUESTFS_EVENT_PROGRESS".
4480 (Added in 1.13.25)
4482 guestfs_copy_device_to_device_va
4484 int
4485 guestfs_copy_device_to_device_va (guestfs_h *g,
4486 const char *src,
4487 const char *dest,
4488 va_list args);
4489 This is the "va_list variant" of "guestfs_copy_device_to_device".
4491 See "CALLS WITH OPTIONAL ARGUMENTS".
4493 guestfs_copy_device_to_device_argv
4495 int
4496 guestfs_copy_device_to_device_argv (guestfs_h *g,
4497 const char *src,
4498 const char *dest,
4499 const struct guestfs_copy_device_to_device_argv *optargs);
4500 This is the "argv variant" of "guestfs_copy_device_to_device".
4502 See "CALLS WITH OPTIONAL ARGUMENTS".
4504 guestfs_copy_device_to_file
4506 int
4507 guestfs_copy_device_to_file (guestfs_h *g,
4508 const char *src,
4509 const char *dest,
4510 ...);
4511 You may supply a list of optional arguments to this call. Use zero or
4513 more of the following pairs of parameters, and terminate the list with
4514 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4515 GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4517 GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4518 GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4519 GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4520 GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4521 See "guestfs_copy_device_to_device" for a general overview of this
4523 call.
4524 This function returns 0 on success or -1 on error.
4526 This long-running command can generate progress notification messages
4528 so that the caller can display a progress bar or indicator. To receive
4529 these messages, the caller must register a progress event callback.
4530 See "GUESTFS_EVENT_PROGRESS".
4531 (Added in 1.13.25)
4533 guestfs_copy_device_to_file_va
4535 int
4536 guestfs_copy_device_to_file_va (guestfs_h *g,
4537 const char *src,
4538 const char *dest,
4539 va_list args);
4540 This is the "va_list variant" of "guestfs_copy_device_to_file".
4542 See "CALLS WITH OPTIONAL ARGUMENTS".
4544 guestfs_copy_device_to_file_argv
4546 int
4547 guestfs_copy_device_to_file_argv (guestfs_h *g,
4548 const char *src,
4549 const char *dest,
4550 const struct guestfs_copy_device_to_file_argv *optargs);
4551 This is the "argv variant" of "guestfs_copy_device_to_file".
4553 See "CALLS WITH OPTIONAL ARGUMENTS".
4555 guestfs_copy_file_to_device
4557 int
4558 guestfs_copy_file_to_device (guestfs_h *g,
4559 const char *src,
4560 const char *dest,
4561 ...);
4562 You may supply a list of optional arguments to this call. Use zero or
4564 more of the following pairs of parameters, and terminate the list with
4565 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4566 GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4568 GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4569 GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4570 GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4571 GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4572 See "guestfs_copy_device_to_device" for a general overview of this
4574 call.
4575 This function returns 0 on success or -1 on error.
4577 This long-running command can generate progress notification messages
4579 so that the caller can display a progress bar or indicator. To receive
4580 these messages, the caller must register a progress event callback.
4581 See "GUESTFS_EVENT_PROGRESS".
4582 (Added in 1.13.25)
4584 guestfs_copy_file_to_device_va
4586 int
4587 guestfs_copy_file_to_device_va (guestfs_h *g,
4588 const char *src,
4589 const char *dest,
4590 va_list args);
4591 This is the "va_list variant" of "guestfs_copy_file_to_device".
4593 See "CALLS WITH OPTIONAL ARGUMENTS".
4595 guestfs_copy_file_to_device_argv
4597 int
4598 guestfs_copy_file_to_device_argv (guestfs_h *g,
4599 const char *src,
4600 const char *dest,
4601 const struct guestfs_copy_file_to_device_argv *optargs);
4602 This is the "argv variant" of "guestfs_copy_file_to_device".
4604 See "CALLS WITH OPTIONAL ARGUMENTS".
4606 guestfs_copy_file_to_file
4608 int
4609 guestfs_copy_file_to_file (guestfs_h *g,
4610 const char *src,
4611 const char *dest,
4612 ...);
4613 You may supply a list of optional arguments to this call. Use zero or
4615 more of the following pairs of parameters, and terminate the list with
4616 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4617 GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4619 GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4620 GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4621 GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4622 GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4623 See "guestfs_copy_device_to_device" for a general overview of this
4625 call.
4626 This is not the function you want for copying files. This is for
4628 copying blocks within existing files. See "guestfs_cp", "guestfs_cp_a"
4629 and "guestfs_mv" for general file copying and moving functions.
4630 This function returns 0 on success or -1 on error.
4632 This long-running command can generate progress notification messages
4634 so that the caller can display a progress bar or indicator. To receive
4635 these messages, the caller must register a progress event callback.
4636 See "GUESTFS_EVENT_PROGRESS".
4637 (Added in 1.13.25)
4639 guestfs_copy_file_to_file_va
4641 int
4642 guestfs_copy_file_to_file_va (guestfs_h *g,
4643 const char *src,
4644 const char *dest,
4645 va_list args);
4646 This is the "va_list variant" of "guestfs_copy_file_to_file".
4648 See "CALLS WITH OPTIONAL ARGUMENTS".
4650 guestfs_copy_file_to_file_argv
4652 int
4653 guestfs_copy_file_to_file_argv (guestfs_h *g,
4654 const char *src,
4655 const char *dest,
4656 const struct guestfs_copy_file_to_file_argv *optargs);
4657 This is the "argv variant" of "guestfs_copy_file_to_file".
4659 See "CALLS WITH OPTIONAL ARGUMENTS".
4661 guestfs_copy_in
4663 int
4664 guestfs_copy_in (guestfs_h *g,
4665 const char *localpath,
4666 const char *remotedir);
4667 "guestfs_copy_in" copies local files or directories recursively into
4669 the disk image, placing them in the directory called "remotedir" (which
4670 must exist).
4671 Wildcards cannot be used.
4673 This function returns 0 on success or -1 on error.
4675 (Added in 1.29.24)
4677 guestfs_copy_out
4679 int
4680 guestfs_copy_out (guestfs_h *g,
4681 const char *remotepath,
4682 const char *localdir);
4683 "guestfs_copy_out" copies remote files or directories recursively out
4685 of the disk image, placing them on the host disk in a local directory
4686 called "localdir" (which must exist).
4687 To download to the current directory, use "." as in:
4689 C<guestfs_copy_out> /home .
4691 Wildcards cannot be used.
4693 This function returns 0 on success or -1 on error.
4695 (Added in 1.29.24)
4697 guestfs_copy_size
4699 int
4700 guestfs_copy_size (guestfs_h *g,
4701 const char *src,
4702 const char *dest,
4703 int64_t size);
4704 This function is deprecated. In new code, use the
4706 "guestfs_copy_device_to_device" call instead.
4707 Deprecated functions will not be removed from the API, but the fact
4709 that they are deprecated indicates that there are problems with correct
4710 use of these functions.
4711 This command copies exactly "size" bytes from one source device or file
4713 "src" to another destination device or file "dest".
4714 Note this will fail if the source is too short or if the destination is
4716 not large enough.
4717 This function returns 0 on success or -1 on error.
4719 This long-running command can generate progress notification messages
4721 so that the caller can display a progress bar or indicator. To receive
4722 these messages, the caller must register a progress event callback.
4723 See "GUESTFS_EVENT_PROGRESS".
4724 (Added in 1.0.87)
4726 guestfs_cp
4728 int
4729 guestfs_cp (guestfs_h *g,
4730 const char *src,
4731 const char *dest);
4732 This copies a file from "src" to "dest" where "dest" is either a
4734 destination filename or destination directory.
4735 This function returns 0 on success or -1 on error.
4737 (Added in 1.0.18)
4739 guestfs_cp_a
4741 int
4742 guestfs_cp_a (guestfs_h *g,
4743 const char *src,
4744 const char *dest);
4745 This copies a file or directory from "src" to "dest" recursively using
4747 the "cp -a" command.
4748 This function returns 0 on success or -1 on error.
4750 (Added in 1.0.18)
4752 guestfs_cp_r
4754 int
4755 guestfs_cp_r (guestfs_h *g,
4756 const char *src,
4757 const char *dest);
4758 This copies a file or directory from "src" to "dest" recursively using
4760 the "cp -rP" command.
4761 Most users should use "guestfs_cp_a" instead. This command is useful
4763 when you don't want to preserve permissions, because the target
4764 filesystem does not support it (primarily when writing to DOS FAT
4765 filesystems).
4766 This function returns 0 on success or -1 on error.
4768 (Added in 1.21.38)
4770 guestfs_cpio_out
4772 int
4773 guestfs_cpio_out (guestfs_h *g,
4774 const char *directory,
4775 const char *cpiofile,
4776 ...);
4777 You may supply a list of optional arguments to this call. Use zero or
4779 more of the following pairs of parameters, and terminate the list with
4780 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4781 GUESTFS_CPIO_OUT_FORMAT, const char *format,
4783 This command packs the contents of directory and downloads it to local
4785 file "cpiofile".
4786 The optional "format" parameter can be used to select the format. Only
4788 the following formats are currently permitted:
4789 "newc"
4791 New (SVR4) portable format. This format happens to be compatible
4792 with the cpio-like format used by the Linux kernel for initramfs.
4793 This is the default format.
4795 "crc"
4797 New (SVR4) portable format with a checksum.
4798 This function returns 0 on success or -1 on error.
4800 (Added in 1.27.9)
4802 guestfs_cpio_out_va
4804 int
4805 guestfs_cpio_out_va (guestfs_h *g,
4806 const char *directory,
4807 const char *cpiofile,
4808 va_list args);
4809 This is the "va_list variant" of "guestfs_cpio_out".
4811 See "CALLS WITH OPTIONAL ARGUMENTS".
4813 guestfs_cpio_out_argv
4815 int
4816 guestfs_cpio_out_argv (guestfs_h *g,
4817 const char *directory,
4818 const char *cpiofile,
4819 const struct guestfs_cpio_out_argv *optargs);
4820 This is the "argv variant" of "guestfs_cpio_out".
4822 See "CALLS WITH OPTIONAL ARGUMENTS".
4824 guestfs_dd
4826 int
4827 guestfs_dd (guestfs_h *g,
4828 const char *src,
4829 const char *dest);
4830 This function is deprecated. In new code, use the
4832 "guestfs_copy_device_to_device" call instead.
4833 Deprecated functions will not be removed from the API, but the fact
4835 that they are deprecated indicates that there are problems with correct
4836 use of these functions.
4837 This command copies from one source device or file "src" to another
4839 destination device or file "dest". Normally you would use this to copy
4840 to or from a device or partition, for example to duplicate a
4841 filesystem.
4842 If the destination is a device, it must be as large or larger than the
4844 source file or device, otherwise the copy will fail. This command
4845 cannot do partial copies (see "guestfs_copy_device_to_device").
4846 This function returns 0 on success or -1 on error.
4848 (Added in 1.0.80)
4850 guestfs_device_index
4852 int
4853 guestfs_device_index (guestfs_h *g,
4854 const char *device);
4855 This function takes a device name (eg. "/dev/sdb") and returns the
4857 index of the device in the list of devices.
4858 Index numbers start from 0. The named device must exist, for example
4860 as a string returned from "guestfs_list_devices".
4861 See also "guestfs_list_devices", "guestfs_part_to_dev".
4863 On error this function returns -1.
4865 (Added in 1.19.7)
4867 guestfs_df
4869 char *
4870 guestfs_df (guestfs_h *g);
4871 This command runs the "df" command to report disk space used.
4873 This command is mostly useful for interactive sessions. It is not
4875 intended that you try to parse the output string. Use
4876 "guestfs_statvfs" from programs.
4877 This function returns a string, or NULL on error. The caller must free
4879 the returned string after use.
4880 (Added in 1.0.54)
4882 guestfs_df_h
4884 char *
4885 guestfs_df_h (guestfs_h *g);
4886 This command runs the "df -h" command to report disk space used in
4888 human-readable format.
4889 This command is mostly useful for interactive sessions. It is not
4891 intended that you try to parse the output string. Use
4892 "guestfs_statvfs" from programs.
4893 This function returns a string, or NULL on error. The caller must free
4895 the returned string after use.
4896 (Added in 1.0.54)
4898 guestfs_disk_create
4900 int
4901 guestfs_disk_create (guestfs_h *g,
4902 const char *filename,
4903 const char *format,
4904 int64_t size,
4905 ...);
4906 You may supply a list of optional arguments to this call. Use zero or
4908 more of the following pairs of parameters, and terminate the list with
4909 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4910 GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
4912 GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
4913 GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
4914 GUESTFS_DISK_CREATE_COMPAT, const char *compat,
4915 GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
4916 Create a blank disk image called filename (a host file) with format
4918 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
4919 If used with the optional "backingfile" parameter, then a snapshot is
4921 created on top of the backing file. In this case, "size" must be
4922 passed as "-1". The size of the snapshot is the same as the size of
4923 the backing file, which is discovered automatically. You are
4924 encouraged to also pass "backingformat" to describe the format of
4925 "backingfile".
4926 If filename refers to a block device, then the device is formatted.
4928 The "size" is ignored since block devices have an intrinsic size.
4929 The other optional parameters are:
4931 "preallocation"
4933 If format is "raw", then this can be either "off" (or "sparse") or
4934 "full" to create a sparse or fully allocated file respectively.
4935 The default is "off".
4936 If format is "qcow2", then this can be "off" (or "sparse"),
4938 "metadata" or "full". Preallocating metadata can be faster when
4939 doing lots of writes, but uses more space. The default is "off".
4940 "compat"
4942 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
4943 supported by qemu ≥ 1.1.
4944 "clustersize"
4946 "qcow2" only: Change the qcow2 cluster size. The default is 65536
4947 (bytes) and this setting may be any power of two between 512 and
4948 2097152.
4949 Note that this call does not add the new disk to the handle. You may
4951 need to call "guestfs_add_drive_opts" separately.
4952 This function returns 0 on success or -1 on error.
4954 (Added in 1.25.31)
4956 guestfs_disk_create_va
4958 int
4959 guestfs_disk_create_va (guestfs_h *g,
4960 const char *filename,
4961 const char *format,
4962 int64_t size,
4963 va_list args);
4964 This is the "va_list variant" of "guestfs_disk_create".
4966 See "CALLS WITH OPTIONAL ARGUMENTS".
4968 guestfs_disk_create_argv
4970 int
4971 guestfs_disk_create_argv (guestfs_h *g,
4972 const char *filename,
4973 const char *format,
4974 int64_t size,
4975 const struct guestfs_disk_create_argv *optargs);
4976 This is the "argv variant" of "guestfs_disk_create".
4978 See "CALLS WITH OPTIONAL ARGUMENTS".
4980 guestfs_disk_format
4982 char *
4983 guestfs_disk_format (guestfs_h *g,
4984 const char *filename);
4985 Detect and return the format of the disk image called filename.
4987 filename can also be a host device, etc. If the format of the image
4988 could not be detected, then "unknown" is returned.
4989 Note that detecting the disk format can be insecure under some
4991 circumstances. See "CVE-2010-3851".
4992 See also: "DISK IMAGE FORMATS"
4994 This function returns a string, or NULL on error. The caller must free
4996 the returned string after use.
4997 (Added in 1.19.38)
4999 guestfs_disk_has_backing_file
5001 int
5002 guestfs_disk_has_backing_file (guestfs_h *g,
5003 const char *filename);
5004 Detect and return whether the disk image filename has a backing file.
5006 Note that detecting disk features can be insecure under some
5008 circumstances. See "CVE-2010-3851".
5009 This function returns a C truth value on success or -1 on error.
5011 (Added in 1.19.39)
5013 guestfs_disk_virtual_size
5015 int64_t
5016 guestfs_disk_virtual_size (guestfs_h *g,
5017 const char *filename);
5018 Detect and return the virtual size in bytes of the disk image called
5020 filename.
5021 Note that detecting disk features can be insecure under some
5023 circumstances. See "CVE-2010-3851".
5024 On error this function returns -1.
5026 (Added in 1.19.39)
5028 guestfs_dmesg
5030 char *
5031 guestfs_dmesg (guestfs_h *g);
5032 This returns the kernel messages ("dmesg" output) from the guest
5034 kernel. This is sometimes useful for extended debugging of problems.
5035 Another way to get the same information is to enable verbose messages
5037 with "guestfs_set_verbose" or by setting the environment variable
5038 "LIBGUESTFS_DEBUG=1" before running the program.
5039 This function returns a string, or NULL on error. The caller must free
5041 the returned string after use.
5042 (Added in 1.0.18)
5044 guestfs_download
5046 int
5047 guestfs_download (guestfs_h *g,
5048 const char *remotefilename,
5049 const char *filename);
5050 Download file remotefilename and save it as filename on the local
5052 machine.
5053 filename can also be a named pipe.
5055 See also "guestfs_upload", "guestfs_cat".
5057 This function returns 0 on success or -1 on error.
5059 This long-running command can generate progress notification messages
5061 so that the caller can display a progress bar or indicator. To receive
5062 these messages, the caller must register a progress event callback.
5063 See "GUESTFS_EVENT_PROGRESS".
5064 (Added in 1.0.2)
5066 guestfs_download_blocks
5068 int
5069 guestfs_download_blocks (guestfs_h *g,
5070 const char *device,
5071 int64_t start,
5072 int64_t stop,
5073 const char *filename,
5074 ...);
5075 You may supply a list of optional arguments to this call. Use zero or
5077 more of the following pairs of parameters, and terminate the list with
5078 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5079 GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5081 Download the data units from start address to stop from the disk
5083 partition (eg. /dev/sda1) and save them as filename on the local
5084 machine.
5085 The use of this API on sparse disk image formats such as QCOW, may
5087 result in large zero-filled files downloaded on the host.
5088 The size of a data unit varies across filesystem implementations. On
5090 NTFS filesystems data units are referred as clusters while on ExtX ones
5091 they are referred as fragments.
5092 If the optional "unallocated" flag is true (default is false), only the
5094 unallocated blocks will be extracted. This is useful to detect hidden
5095 data or to retrieve deleted files which data units have not been
5096 overwritten yet.
5097 This function returns 0 on success or -1 on error.
5099 This long-running command can generate progress notification messages
5101 so that the caller can display a progress bar or indicator. To receive
5102 these messages, the caller must register a progress event callback.
5103 See "GUESTFS_EVENT_PROGRESS".
5104 This function depends on the feature "sleuthkit". See also
5106 "guestfs_feature_available".
5107 (Added in 1.33.45)
5109 guestfs_download_blocks_va
5111 int
5112 guestfs_download_blocks_va (guestfs_h *g,
5113 const char *device,
5114 int64_t start,
5115 int64_t stop,
5116 const char *filename,
5117 va_list args);
5118 This is the "va_list variant" of "guestfs_download_blocks".
5120 See "CALLS WITH OPTIONAL ARGUMENTS".
5122 guestfs_download_blocks_argv
5124 int
5125 guestfs_download_blocks_argv (guestfs_h *g,
5126 const char *device,
5127 int64_t start,
5128 int64_t stop,
5129 const char *filename,
5130 const struct guestfs_download_blocks_argv *optargs);
5131 This is the "argv variant" of "guestfs_download_blocks".
5133 See "CALLS WITH OPTIONAL ARGUMENTS".
5135 guestfs_download_inode
5137 int
5138 guestfs_download_inode (guestfs_h *g,
5139 const char *device,
5140 int64_t inode,
5141 const char *filename);
5142 Download a file given its inode from the disk partition (eg. /dev/sda1)
5144 and save it as filename on the local machine.
5145 It is not required to mount the disk to run this command.
5147 The command is capable of downloading deleted or inaccessible files.
5149 This function returns 0 on success or -1 on error.
5151 This long-running command can generate progress notification messages
5153 so that the caller can display a progress bar or indicator. To receive
5154 these messages, the caller must register a progress event callback.
5155 See "GUESTFS_EVENT_PROGRESS".
5156 This function depends on the feature "sleuthkit". See also
5158 "guestfs_feature_available".
5159 (Added in 1.33.14)
5161 guestfs_download_offset
5163 int
5164 guestfs_download_offset (guestfs_h *g,
5165 const char *remotefilename,
5166 const char *filename,
5167 int64_t offset,
5168 int64_t size);
5169 Download file remotefilename and save it as filename on the local
5171 machine.
5172 remotefilename is read for "size" bytes starting at "offset" (this
5174 region must be within the file or device).
5175 Note that there is no limit on the amount of data that can be
5177 downloaded with this call, unlike with "guestfs_pread", and this call
5178 always reads the full amount unless an error occurs.
5179 See also "guestfs_download", "guestfs_pread".
5181 This function returns 0 on success or -1 on error.
5183 This long-running command can generate progress notification messages
5185 so that the caller can display a progress bar or indicator. To receive
5186 these messages, the caller must register a progress event callback.
5187 See "GUESTFS_EVENT_PROGRESS".
5188 (Added in 1.5.17)
5190 guestfs_drop_caches
5192 int
5193 guestfs_drop_caches (guestfs_h *g,
5194 int whattodrop);
5195 This instructs the guest kernel to drop its page cache, and/or dentries
5197 and inode caches. The parameter "whattodrop" tells the kernel what
5198 precisely to drop, see http://linux-mm.org/Drop_Caches
5199 Setting "whattodrop" to 3 should drop everything.
5201 This automatically calls sync(2) before the operation, so that the
5203 maximum guest memory is freed.
5204 This function returns 0 on success or -1 on error.
5206 (Added in 1.0.18)
5208 guestfs_du
5210 int64_t
5211 guestfs_du (guestfs_h *g,
5212 const char *path);
5213 This command runs the "du -s" command to estimate file space usage for
5215 "path".
5216 "path" can be a file or a directory. If "path" is a directory then the
5218 estimate includes the contents of the directory and all subdirectories
5219 (recursively).
5220 The result is the estimated size in kilobytes (ie. units of 1024
5222 bytes).
5223 On error this function returns -1.
5225 This long-running command can generate progress notification messages
5227 so that the caller can display a progress bar or indicator. To receive
5228 these messages, the caller must register a progress event callback.
5229 See "GUESTFS_EVENT_PROGRESS".
5230 (Added in 1.0.54)
5232 guestfs_e2fsck
5234 int
5235 guestfs_e2fsck (guestfs_h *g,
5236 const char *device,
5237 ...);
5238 You may supply a list of optional arguments to this call. Use zero or
5240 more of the following pairs of parameters, and terminate the list with
5241 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5242 GUESTFS_E2FSCK_CORRECT, int correct,
5244 GUESTFS_E2FSCK_FORCEALL, int forceall,
5245 This runs the ext2/ext3 filesystem checker on "device". It can take
5247 the following optional arguments:
5248 "correct"
5250 Automatically repair the file system. This option will cause e2fsck
5251 to automatically fix any filesystem problems that can be safely
5252 fixed without human intervention.
5253 This option may not be specified at the same time as the "forceall"
5255 option.
5256 "forceall"
5258 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5259 used non-interactively.
5260 This option may not be specified at the same time as the "correct"
5262 option.
5263 This function returns 0 on success or -1 on error.
5265 (Added in 1.15.17)
5267 guestfs_e2fsck_va
5269 int
5270 guestfs_e2fsck_va (guestfs_h *g,
5271 const char *device,
5272 va_list args);
5273 This is the "va_list variant" of "guestfs_e2fsck".
5275 See "CALLS WITH OPTIONAL ARGUMENTS".
5277 guestfs_e2fsck_argv
5279 int
5280 guestfs_e2fsck_argv (guestfs_h *g,
5281 const char *device,
5282 const struct guestfs_e2fsck_argv *optargs);
5283 This is the "argv variant" of "guestfs_e2fsck".
5285 See "CALLS WITH OPTIONAL ARGUMENTS".
5287 guestfs_e2fsck_f
5289 int
5290 guestfs_e2fsck_f (guestfs_h *g,
5291 const char *device);
5292 This function is deprecated. In new code, use the "guestfs_e2fsck"
5294 call instead.
5295 Deprecated functions will not be removed from the API, but the fact
5297 that they are deprecated indicates that there are problems with correct
5298 use of these functions.
5299 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5301 checker on "device", noninteractively (-p), even if the filesystem
5302 appears to be clean (-f).
5303 This function returns 0 on success or -1 on error.
5305 (Added in 1.0.29)
5307 guestfs_echo_daemon
5309 char *
5310 guestfs_echo_daemon (guestfs_h *g,
5311 char *const *words);
5312 This command concatenates the list of "words" passed with single spaces
5314 between them and returns the resulting string.
5315 You can use this command to test the connection through to the daemon.
5317 See also "guestfs_ping_daemon".
5319 This function returns a string, or NULL on error. The caller must free
5321 the returned string after use.
5322 (Added in 1.0.69)
5324 guestfs_egrep
5326 char **
5327 guestfs_egrep (guestfs_h *g,
5328 const char *regex,
5329 const char *path);
5330 This function is deprecated. In new code, use the "guestfs_grep" call
5332 instead.
5333 Deprecated functions will not be removed from the API, but the fact
5335 that they are deprecated indicates that there are problems with correct
5336 use of these functions.
5337 This calls the external "egrep" program and returns the matching lines.
5339 This function returns a NULL-terminated array of strings (like
5341 environ(3)), or NULL if there was an error. The caller must free the
5342 strings and the array after use.
5343 Because of the message protocol, there is a transfer limit of somewhere
5345 between 2MB and 4MB. See "PROTOCOL LIMITS".
5346 (Added in 1.0.66)
5348 guestfs_egrepi
5350 char **
5351 guestfs_egrepi (guestfs_h *g,
5352 const char *regex,
5353 const char *path);
5354 This function is deprecated. In new code, use the "guestfs_grep" call
5356 instead.
5357 Deprecated functions will not be removed from the API, but the fact
5359 that they are deprecated indicates that there are problems with correct
5360 use of these functions.
5361 This calls the external "egrep -i" program and returns the matching
5363 lines.
5364 This function returns a NULL-terminated array of strings (like
5366 environ(3)), or NULL if there was an error. The caller must free the
5367 strings and the array after use.
5368 Because of the message protocol, there is a transfer limit of somewhere
5370 between 2MB and 4MB. See "PROTOCOL LIMITS".
5371 (Added in 1.0.66)
5373 guestfs_equal
5375 int
5376 guestfs_equal (guestfs_h *g,
5377 const char *file1,
5378 const char *file2);
5379 This compares the two files file1 and file2 and returns true if their
5381 content is exactly equal, or false otherwise.
5382 The external cmp(1) program is used for the comparison.
5384 This function returns a C truth value on success or -1 on error.
5386 (Added in 1.0.18)
5388 guestfs_exists
5390 int
5391 guestfs_exists (guestfs_h *g,
5392 const char *path);
5393 This returns "true" if and only if there is a file, directory (or
5395 anything) with the given "path" name.
5396 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5398 This function returns a C truth value on success or -1 on error.
5400 (Added in 0.8)
5402 guestfs_extlinux
5404 int
5405 guestfs_extlinux (guestfs_h *g,
5406 const char *directory);
5407 Install the SYSLINUX bootloader on the device mounted at directory.
5409 Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5410 used on an ext2/3/4 or btrfs filesystem.
5411 The directory parameter can be either a mountpoint, or a directory
5413 within the mountpoint.
5414 You also have to mark the partition as "active"
5416 ("guestfs_part_set_bootable") and a Master Boot Record must be
5417 installed (eg. using "guestfs_pwrite_device") on the first sector of
5418 the whole disk. The SYSLINUX package comes with some suitable Master
5419 Boot Records. See the extlinux(1) man page for further information.
5420 Additional configuration can be supplied to SYSLINUX by placing a file
5422 called extlinux.conf on the filesystem under directory. For further
5423 information about the contents of this file, see extlinux(1).
5424 See also "guestfs_syslinux".
5426 This function returns 0 on success or -1 on error.
5428 This function depends on the feature "extlinux". See also
5430 "guestfs_feature_available".
5431 (Added in 1.21.27)
5433 guestfs_fallocate
5435 int
5436 guestfs_fallocate (guestfs_h *g,
5437 const char *path,
5438 int len);
5439 This function is deprecated. In new code, use the
5441 "guestfs_fallocate64" call instead.
5442 Deprecated functions will not be removed from the API, but the fact
5444 that they are deprecated indicates that there are problems with correct
5445 use of these functions.
5446 This command preallocates a file (containing zero bytes) named "path"
5448 of size "len" bytes. If the file exists already, it is overwritten.
5449 Do not confuse this with the guestfish-specific "alloc" command which
5451 allocates a file in the host and attaches it as a device.
5452 This function returns 0 on success or -1 on error.
5454 (Added in 1.0.66)
5456 guestfs_fallocate64
5458 int
5459 guestfs_fallocate64 (guestfs_h *g,
5460 const char *path,
5461 int64_t len);
5462 This command preallocates a file (containing zero bytes) named "path"
5464 of size "len" bytes. If the file exists already, it is overwritten.
5465 Note that this call allocates disk blocks for the file. To create a
5467 sparse file use "guestfs_truncate_size" instead.
5468 The deprecated call "guestfs_fallocate" does the same, but owing to an
5470 oversight it only allowed 30 bit lengths to be specified, effectively
5471 limiting the maximum size of files created through that call to 1GB.
5472 Do not confuse this with the guestfish-specific "alloc" and "sparse"
5474 commands which create a file in the host and attach it as a device.
5475 This function returns 0 on success or -1 on error.
5477 (Added in 1.3.17)
5479 guestfs_feature_available
5481 int
5482 guestfs_feature_available (guestfs_h *g,
5483 char *const *groups);
5484 This is the same as "guestfs_available", but unlike that call it
5486 returns a simple true/false boolean result, instead of throwing an
5487 exception if a feature is not found. For other documentation see
5488 "guestfs_available".
5489 This function returns a C truth value on success or -1 on error.
5491 (Added in 1.21.26)
5493 guestfs_fgrep
5495 char **
5496 guestfs_fgrep (guestfs_h *g,
5497 const char *pattern,
5498 const char *path);
5499 This function is deprecated. In new code, use the "guestfs_grep" call
5501 instead.
5502 Deprecated functions will not be removed from the API, but the fact
5504 that they are deprecated indicates that there are problems with correct
5505 use of these functions.
5506 This calls the external "fgrep" program and returns the matching lines.
5508 This function returns a NULL-terminated array of strings (like
5510 environ(3)), or NULL if there was an error. The caller must free the
5511 strings and the array after use.
5512 Because of the message protocol, there is a transfer limit of somewhere
5514 between 2MB and 4MB. See "PROTOCOL LIMITS".
5515 (Added in 1.0.66)
5517 guestfs_fgrepi
5519 char **
5520 guestfs_fgrepi (guestfs_h *g,
5521 const char *pattern,
5522 const char *path);
5523 This function is deprecated. In new code, use the "guestfs_grep" call
5525 instead.
5526 Deprecated functions will not be removed from the API, but the fact
5528 that they are deprecated indicates that there are problems with correct
5529 use of these functions.
5530 This calls the external "fgrep -i" program and returns the matching
5532 lines.
5533 This function returns a NULL-terminated array of strings (like
5535 environ(3)), or NULL if there was an error. The caller must free the
5536 strings and the array after use.
5537 Because of the message protocol, there is a transfer limit of somewhere
5539 between 2MB and 4MB. See "PROTOCOL LIMITS".
5540 (Added in 1.0.66)
5542 guestfs_file
5544 char *
5545 guestfs_file (guestfs_h *g,
5546 const char *path);
5547 This call uses the standard file(1) command to determine the type or
5549 contents of the file.
5550 This call will also transparently look inside various types of
5552 compressed file.
5553 The exact command which runs is "file -zb path". Note in particular
5555 that the filename is not prepended to the output (the -b option).
5556 The output depends on the output of the underlying file(1) command and
5558 it can change in future in ways beyond our control. In other words,
5559 the output is not guaranteed by the ABI.
5560 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5562 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5563 This function returns a string, or NULL on error. The caller must free
5565 the returned string after use.
5566 (Added in 1.9.1)
5568 guestfs_file_architecture
5570 char *
5571 guestfs_file_architecture (guestfs_h *g,
5572 const char *filename);
5573 This detects the architecture of the binary filename, and returns it if
5575 known.
5576 Currently defined architectures are:
5578 "aarch64"
5580 64 bit ARM.
5581 "arm"
5583 32 bit ARM.
5584 "i386"
5586 This string is returned for all 32 bit i386, i486, i586, i686
5587 binaries irrespective of the precise processor requirements of the
5588 binary.
5589 "ia64"
5591 Intel Itanium.
5592 "ppc"
5594 32 bit Power PC.
5595 "ppc64"
5597 64 bit Power PC (big endian).
5598 "ppc64le"
5600 64 bit Power PC (little endian).
5601 "riscv32"
5603 "riscv64"
5604 "riscv128"
5605 RISC-V 32-, 64- or 128-bit variants.
5606 "s390"
5608 31 bit IBM S/390.
5609 "s390x"
5611 64 bit IBM S/390.
5612 "sparc"
5614 32 bit SPARC.
5615 "sparc64"
5617 64 bit SPARC V9 and above.
5618 "x86_64"
5620 64 bit x86-64.
5621 Libguestfs may return other architecture strings in future.
5623 The function works on at least the following types of files:
5625 · many types of Un*x and Linux binary
5627 · many types of Un*x and Linux shared library
5629 · Windows Win32 and Win64 binaries
5631 · Windows Win32 and Win64 DLLs
5633 Win32 binaries and DLLs return "i386".
5635 Win64 binaries and DLLs return "x86_64".
5637 · Linux kernel modules
5639 · Linux new-style initrd images
5641 · some non-x86 Linux vmlinuz kernels
5643 What it can't do currently:
5645 · static libraries (libfoo.a)
5647 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5649 · x86 Linux vmlinuz kernels
5651 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5653 and compressed code, and are horribly hard to unpack. If you want
5654 to find the architecture of a kernel, use the architecture of the
5655 associated initrd or kernel module(s) instead.
5656 This function returns a string, or NULL on error. The caller must free
5658 the returned string after use.
5659 (Added in 1.5.3)
5661 guestfs_filesize
5663 int64_t
5664 guestfs_filesize (guestfs_h *g,
5665 const char *file);
5666 This command returns the size of file in bytes.
5668 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5670 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
5671 devices, use "guestfs_blockdev_getsize64".
5672 On error this function returns -1.
5674 (Added in 1.0.82)
5676 guestfs_filesystem_available
5678 int
5679 guestfs_filesystem_available (guestfs_h *g,
5680 const char *filesystem);
5681 Check whether libguestfs supports the named filesystem. The argument
5683 "filesystem" is a filesystem name, such as "ext3".
5684 You must call "guestfs_launch" before using this command.
5686 This is mainly useful as a negative test. If this returns true, it
5688 doesn't mean that a particular filesystem can be created or mounted,
5689 since filesystems can fail for other reasons such as it being a later
5690 version of the filesystem, or having incompatible features, or lacking
5691 the right mkfs.<fs> tool.
5692 See also "guestfs_available", "guestfs_feature_available",
5694 "AVAILABILITY".
5695 This function returns a C truth value on success or -1 on error.
5697 (Added in 1.19.5)
5699 guestfs_filesystem_walk
5701 struct guestfs_tsk_dirent_list *
5702 guestfs_filesystem_walk (guestfs_h *g,
5703 const char *device);
5704 Walk through the internal structures of a disk partition (eg.
5706 /dev/sda1) in order to return a list of all the files and directories
5707 stored within.
5708 It is not necessary to mount the disk partition to run this command.
5710 All entries in the filesystem are returned. This function can list
5712 deleted or unaccessible files. The entries are not sorted.
5713 The "tsk_dirent" structure contains the following fields.
5715 "tsk_inode"
5717 Filesystem reference number of the node. It might be 0 if the node
5718 has been deleted.
5719 "tsk_type"
5721 Basic file type information. See below for a detailed list of
5722 values.
5723 "tsk_size"
5725 File size in bytes. It might be "-1" if the node has been deleted.
5726 "tsk_name"
5728 The file path relative to its directory.
5729 "tsk_flags"
5731 Bitfield containing extra information regarding the entry. It
5732 contains the logical OR of the following values:
5733 0x0001
5735 If set to 1, the file is allocated and visible within the
5736 filesystem. Otherwise, the file has been deleted. Under
5737 certain circumstances, the function "download_inode" can be
5738 used to recover deleted files.
5739 0x0002
5741 Filesystem such as NTFS and Ext2 or greater, separate the file
5742 name from the metadata structure. The bit is set to 1 when the
5743 file name is in an unallocated state and the metadata structure
5744 is in an allocated one. This generally implies the metadata
5745 has been reallocated to a new file. Therefore, information
5746 such as file type, file size, timestamps, number of links and
5747 symlink target might not correspond with the ones of the
5748 original deleted entry.
5749 0x0004
5751 The bit is set to 1 when the file is compressed using
5752 filesystem native compression support (NTFS). The API is not
5753 able to detect application level compression.
5754 "tsk_atime_sec"
5756 "tsk_atime_nsec"
5757 "tsk_mtime_sec"
5758 "tsk_mtime_nsec"
5759 "tsk_ctime_sec"
5760 "tsk_ctime_nsec"
5761 "tsk_crtime_sec"
5762 "tsk_crtime_nsec"
5763 Respectively, access, modification, last status change and creation
5764 time in Unix format in seconds and nanoseconds.
5765 "tsk_nlink"
5767 Number of file names pointing to this entry.
5768 "tsk_link"
5770 If the entry is a symbolic link, this field will contain the path
5771 to the target file.
5772 The "tsk_type" field will contain one of the following characters:
5774 'b' Block special
5776 'c' Char special
5778 'd' Directory
5780 'f' FIFO (named pipe)
5782 'l' Symbolic link
5784 'r' Regular file
5786 's' Socket
5788 'h' Shadow inode (Solaris)
5790 'w' Whiteout inode (BSD)
5792 'u' Unknown file type
5794 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
5796 there was an error. The caller must call
5797 "guestfs_free_tsk_dirent_list" after use.
5798 This long-running command can generate progress notification messages
5800 so that the caller can display a progress bar or indicator. To receive
5801 these messages, the caller must register a progress event callback.
5802 See "GUESTFS_EVENT_PROGRESS".
5803 This function depends on the feature "libtsk". See also
5805 "guestfs_feature_available".
5806 (Added in 1.33.39)
5808 guestfs_fill
5810 int
5811 guestfs_fill (guestfs_h *g,
5812 int c,
5813 int len,
5814 const char *path);
5815 This command creates a new file called "path". The initial content of
5817 the file is "len" octets of "c", where "c" must be a number in the
5818 range "[0..255]".
5819 To fill a file with zero bytes (sparsely), it is much more efficient to
5821 use "guestfs_truncate_size". To create a file with a pattern of
5822 repeating bytes use "guestfs_fill_pattern".
5823 This function returns 0 on success or -1 on error.
5825 This long-running command can generate progress notification messages
5827 so that the caller can display a progress bar or indicator. To receive
5828 these messages, the caller must register a progress event callback.
5829 See "GUESTFS_EVENT_PROGRESS".
5830 (Added in 1.0.79)
5832 guestfs_fill_dir
5834 int
5835 guestfs_fill_dir (guestfs_h *g,
5836 const char *dir,
5837 int nr);
5838 This function, useful for testing filesystems, creates "nr" empty files
5840 in the directory "dir" with names 00000000 through "nr-1" (ie. each
5841 file name is 8 digits long padded with zeroes).
5842 This function returns 0 on success or -1 on error.
5844 (Added in 1.19.32)
5846 guestfs_fill_pattern
5848 int
5849 guestfs_fill_pattern (guestfs_h *g,
5850 const char *pattern,
5851 int len,
5852 const char *path);
5853 This function is like "guestfs_fill" except that it creates a new file
5855 of length "len" containing the repeating pattern of bytes in "pattern".
5856 The pattern is truncated if necessary to ensure the length of the file
5857 is exactly "len" bytes.
5858 This function returns 0 on success or -1 on error.
5860 This long-running command can generate progress notification messages
5862 so that the caller can display a progress bar or indicator. To receive
5863 these messages, the caller must register a progress event callback.
5864 See "GUESTFS_EVENT_PROGRESS".
5865 (Added in 1.3.12)
5867 guestfs_find
5869 char **
5870 guestfs_find (guestfs_h *g,
5871 const char *directory);
5872 This command lists out all files and directories, recursively, starting
5874 at directory. It is essentially equivalent to running the shell
5875 command "find directory -print" but some post-processing happens on the
5876 output, described below.
5877 This returns a list of strings without any prefix. Thus if the
5879 directory structure was:
5880 /tmp/a
5882 /tmp/b
5883 /tmp/c/d
5884 then the returned list from "guestfs_find" /tmp would be 4 elements:
5886 a
5888 b
5889 c
5890 c/d
5891 If directory is not a directory, then this command returns an error.
5893 The returned list is sorted.
5895 This function returns a NULL-terminated array of strings (like
5897 environ(3)), or NULL if there was an error. The caller must free the
5898 strings and the array after use.
5899 (Added in 1.0.27)
5901 guestfs_find0
5903 int
5904 guestfs_find0 (guestfs_h *g,
5905 const char *directory,
5906 const char *files);
5907 This command lists out all files and directories, recursively, starting
5909 at directory, placing the resulting list in the external file called
5910 files.
5911 This command works the same way as "guestfs_find" with the following
5913 exceptions:
5914 · The resulting list is written to an external file.
5916 · Items (filenames) in the result are separated by "\0" characters.
5918 See find(1) option -print0.
5919 · The result list is not sorted.
5921 This function returns 0 on success or -1 on error.
5923 (Added in 1.0.74)
5925 guestfs_find_inode
5927 struct guestfs_tsk_dirent_list *
5928 guestfs_find_inode (guestfs_h *g,
5929 const char *device,
5930 int64_t inode);
5931 Searches all the entries associated with the given inode.
5933 For each entry, a "tsk_dirent" structure is returned. See
5935 "filesystem_walk" for more information about "tsk_dirent" structures.
5936 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
5938 there was an error. The caller must call
5939 "guestfs_free_tsk_dirent_list" after use.
5940 This long-running command can generate progress notification messages
5942 so that the caller can display a progress bar or indicator. To receive
5943 these messages, the caller must register a progress event callback.
5944 See "GUESTFS_EVENT_PROGRESS".
5945 This function depends on the feature "libtsk". See also
5947 "guestfs_feature_available".
5948 (Added in 1.35.6)
5950 guestfs_findfs_label
5952 char *
5953 guestfs_findfs_label (guestfs_h *g,
5954 const char *label);
5955 This command searches the filesystems and returns the one which has the
5957 given label. An error is returned if no such filesystem can be found.
5958 To find the label of a filesystem, use "guestfs_vfs_label".
5960 This function returns a string, or NULL on error. The caller must free
5962 the returned string after use.
5963 (Added in 1.5.3)
5965 guestfs_findfs_uuid
5967 char *
5968 guestfs_findfs_uuid (guestfs_h *g,
5969 const char *uuid);
5970 This command searches the filesystems and returns the one which has the
5972 given UUID. An error is returned if no such filesystem can be found.
5973 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
5975 This function returns a string, or NULL on error. The caller must free
5977 the returned string after use.
5978 (Added in 1.5.3)
5980 guestfs_fsck
5982 int
5983 guestfs_fsck (guestfs_h *g,
5984 const char *fstype,
5985 const char *device);
5986 This runs the filesystem checker (fsck) on "device" which should have
5988 filesystem type "fstype".
5989 The returned integer is the status. See fsck(8) for the list of status
5991 codes from "fsck".
5992 Notes:
5994 · Multiple status codes can be summed together.
5996 · A non-zero return code can mean "success", for example if errors
5998 have been corrected on the filesystem.
5999 · Checking or repairing NTFS volumes is not supported (by linux-
6001 ntfs).
6002 This command is entirely equivalent to running "fsck -a -t fstype
6004 device".
6005 On error this function returns -1.
6007 (Added in 1.0.16)
6009 guestfs_fstrim
6011 int
6012 guestfs_fstrim (guestfs_h *g,
6013 const char *mountpoint,
6014 ...);
6015 You may supply a list of optional arguments to this call. Use zero or
6017 more of the following pairs of parameters, and terminate the list with
6018 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6019 GUESTFS_FSTRIM_OFFSET, int64_t offset,
6021 GUESTFS_FSTRIM_LENGTH, int64_t length,
6022 GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6023 Trim the free space in the filesystem mounted on "mountpoint". The
6025 filesystem must be mounted read-write.
6026 The filesystem contents are not affected, but any free space in the
6028 filesystem is "trimmed", that is, given back to the host device, thus
6029 making disk images more sparse, allowing unused space in qcow2 files to
6030 be reused, etc.
6031 This operation requires support in libguestfs, the mounted filesystem,
6033 the host filesystem, qemu and the host kernel. If this support isn't
6034 present it may give an error or even appear to run but do nothing.
6035 In the case where the kernel vfs driver does not support trimming, this
6037 call will fail with errno set to "ENOTSUP". Currently this happens
6038 when trying to trim FAT filesystems.
6039 See also "guestfs_zero_free_space". That is a slightly different
6041 operation that turns free space in the filesystem into zeroes. It is
6042 valid to call "guestfs_fstrim" either instead of, or after calling
6043 "guestfs_zero_free_space".
6044 This function returns 0 on success or -1 on error.
6046 This function depends on the feature "fstrim". See also
6048 "guestfs_feature_available".
6049 (Added in 1.19.6)
6051 guestfs_fstrim_va
6053 int
6054 guestfs_fstrim_va (guestfs_h *g,
6055 const char *mountpoint,
6056 va_list args);
6057 This is the "va_list variant" of "guestfs_fstrim".
6059 See "CALLS WITH OPTIONAL ARGUMENTS".
6061 guestfs_fstrim_argv
6063 int
6064 guestfs_fstrim_argv (guestfs_h *g,
6065 const char *mountpoint,
6066 const struct guestfs_fstrim_argv *optargs);
6067 This is the "argv variant" of "guestfs_fstrim".
6069 See "CALLS WITH OPTIONAL ARGUMENTS".
6071 guestfs_get_append
6073 const char *
6074 guestfs_get_append (guestfs_h *g);
6075 Return the additional kernel options which are added to the libguestfs
6077 appliance kernel command line.
6078 If "NULL" then no options are added.
6080 This function returns a string which may be NULL. There is no way to
6082 return an error from this function. The string is owned by the guest
6083 handle and must not be freed.
6084 (Added in 1.0.26)
6086 guestfs_get_attach_method
6088 char *
6089 guestfs_get_attach_method (guestfs_h *g);
6090 This function is deprecated. In new code, use the
6092 "guestfs_get_backend" call instead.
6093 Deprecated functions will not be removed from the API, but the fact
6095 that they are deprecated indicates that there are problems with correct
6096 use of these functions.
6097 Return the current backend.
6099 See "guestfs_set_backend" and "BACKEND".
6101 This function returns a string, or NULL on error. The caller must free
6103 the returned string after use.
6104 (Added in 1.9.8)
6106 guestfs_get_autosync
6108 int
6109 guestfs_get_autosync (guestfs_h *g);
6110 Get the autosync flag.
6112 This function returns a C truth value on success or -1 on error.
6114 (Added in 0.3)
6116 guestfs_get_backend
6118 char *
6119 guestfs_get_backend (guestfs_h *g);
6120 Return the current backend.
6122 This handle property was previously called the "attach method".
6124 See "guestfs_set_backend" and "BACKEND".
6126 This function returns a string, or NULL on error. The caller must free
6128 the returned string after use.
6129 (Added in 1.21.26)
6131 guestfs_get_backend_setting
6133 char *
6134 guestfs_get_backend_setting (guestfs_h *g,
6135 const char *name);
6136 Find a backend setting string which is either "name" or begins with
6138 "name=". If "name", this returns the string "1". If "name=", this
6139 returns the part after the equals sign (which may be an empty string).
6140 If no such setting is found, this function throws an error. The errno
6142 (see "guestfs_last_errno") will be "ESRCH" in this case.
6143 See "BACKEND", "BACKEND SETTINGS".
6145 This function returns a string, or NULL on error. The caller must free
6147 the returned string after use.
6148 (Added in 1.27.2)
6150 guestfs_get_backend_settings
6152 char **
6153 guestfs_get_backend_settings (guestfs_h *g);
6154 Return the current backend settings.
6156 This call returns all backend settings strings. If you want to find a
6158 single backend setting, see "guestfs_get_backend_setting".
6159 See "BACKEND", "BACKEND SETTINGS".
6161 This function returns a NULL-terminated array of strings (like
6163 environ(3)), or NULL if there was an error. The caller must free the
6164 strings and the array after use.
6165 (Added in 1.25.24)
6167 guestfs_get_cachedir
6169 char *
6170 guestfs_get_cachedir (guestfs_h *g);
6171 Get the directory used by the handle to store the appliance cache.
6173 This function returns a string, or NULL on error. The caller must free
6175 the returned string after use.
6176 (Added in 1.19.58)
6178 guestfs_get_direct
6180 int
6181 guestfs_get_direct (guestfs_h *g);
6182 This function is deprecated. In new code, use the
6184 "guestfs_internal_get_console_socket" call instead.
6185 Deprecated functions will not be removed from the API, but the fact
6187 that they are deprecated indicates that there are problems with correct
6188 use of these functions.
6189 Return the direct appliance mode flag.
6191 This function returns a C truth value on success or -1 on error.
6193 (Added in 1.0.72)
6195 guestfs_get_e2attrs
6197 char *
6198 guestfs_get_e2attrs (guestfs_h *g,
6199 const char *file);
6200 This returns the file attributes associated with file.
6202 The attributes are a set of bits associated with each inode which
6204 affect the behaviour of the file. The attributes are returned as a
6205 string of letters (described below). The string may be empty,
6206 indicating that no file attributes are set for this file.
6207 These attributes are only present when the file is located on an
6209 ext2/3/4 filesystem. Using this call on other filesystem types will
6210 result in an error.
6211 The characters (file attributes) in the returned string are currently:
6213 'A' When the file is accessed, its atime is not modified.
6215 'a' The file is append-only.
6217 'c' The file is compressed on-disk.
6219 'D' (Directories only.) Changes to this directory are written
6221 synchronously to disk.
6222 'd' The file is not a candidate for backup (see dump(8)).
6224 'E' The file has compression errors.
6226 'e' The file is using extents.
6228 'h' The file is storing its blocks in units of the filesystem blocksize
6230 instead of sectors.
6231 'I' (Directories only.) The directory is using hashed trees.
6233 'i' The file is immutable. It cannot be modified, deleted or renamed.
6235 No link can be created to this file.
6236 'j' The file is data-journaled.
6238 's' When the file is deleted, all its blocks will be zeroed.
6240 'S' Changes to this file are written synchronously to disk.
6242 'T' (Directories only.) This is a hint to the block allocator that
6244 subdirectories contained in this directory should be spread across
6245 blocks. If not present, the block allocator will try to group
6246 subdirectories together.
6247 't' For a file, this disables tail-merging. (Not used by upstream
6249 implementations of ext2.)
6250 'u' When the file is deleted, its blocks will be saved, allowing the
6252 file to be undeleted.
6253 'X' The raw contents of the compressed file may be accessed.
6255 'Z' The compressed file is dirty.
6257 More file attributes may be added to this list later. Not all file
6259 attributes may be set for all kinds of files. For detailed
6260 information, consult the chattr(1) man page.
6261 See also "guestfs_set_e2attrs".
6263 Don't confuse these attributes with extended attributes (see
6265 "guestfs_getxattr").
6266 This function returns a string, or NULL on error. The caller must free
6268 the returned string after use.
6269 (Added in 1.17.31)
6271 guestfs_get_e2generation
6273 int64_t
6274 guestfs_get_e2generation (guestfs_h *g,
6275 const char *file);
6276 This returns the ext2 file generation of a file. The generation (which
6278 used to be called the "version") is a number associated with an inode.
6279 This is most commonly used by NFS servers.
6280 The generation is only present when the file is located on an ext2/3/4
6282 filesystem. Using this call on other filesystem types will result in
6283 an error.
6284 See "guestfs_set_e2generation".
6286 On error this function returns -1.
6288 (Added in 1.17.31)
6290 guestfs_get_e2label
6292 char *
6293 guestfs_get_e2label (guestfs_h *g,
6294 const char *device);
6295 This function is deprecated. In new code, use the "guestfs_vfs_label"
6297 call instead.
6298 Deprecated functions will not be removed from the API, but the fact
6300 that they are deprecated indicates that there are problems with correct
6301 use of these functions.
6302 This returns the ext2/3/4 filesystem label of the filesystem on
6304 "device".
6305 This function returns a string, or NULL on error. The caller must free
6307 the returned string after use.
6308 (Added in 1.0.15)
6310 guestfs_get_e2uuid
6312 char *
6313 guestfs_get_e2uuid (guestfs_h *g,
6314 const char *device);
6315 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
6317 call instead.
6318 Deprecated functions will not be removed from the API, but the fact
6320 that they are deprecated indicates that there are problems with correct
6321 use of these functions.
6322 This returns the ext2/3/4 filesystem UUID of the filesystem on
6324 "device".
6325 This function returns a string, or NULL on error. The caller must free
6327 the returned string after use.
6328 (Added in 1.0.15)
6330 guestfs_get_hv
6332 char *
6333 guestfs_get_hv (guestfs_h *g);
6334 Return the current hypervisor binary.
6336 This is always non-NULL. If it wasn't set already, then this will
6338 return the default qemu binary name.
6339 This function returns a string, or NULL on error. The caller must free
6341 the returned string after use.
6342 (Added in 1.23.17)
6344 guestfs_get_identifier
6346 const char *
6347 guestfs_get_identifier (guestfs_h *g);
6348 Get the handle identifier. See "guestfs_set_identifier".
6350 This function returns a string, or NULL on error. The string is owned
6352 by the guest handle and must not be freed.
6353 (Added in 1.31.14)
6355 guestfs_get_libvirt_requested_credential_challenge
6357 char *
6358 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6359 int index);
6360 Get the challenge (provided by libvirt) for the "index"'th requested
6362 credential. If libvirt did not provide a challenge, this returns the
6363 empty string "".
6364 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6366 This function returns a string, or NULL on error. The caller must free
6368 the returned string after use.
6369 (Added in 1.19.52)
6371 guestfs_get_libvirt_requested_credential_defresult
6373 char *
6374 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6375 int index);
6376 Get the default result (provided by libvirt) for the "index"'th
6378 requested credential. If libvirt did not provide a default result,
6379 this returns the empty string "".
6380 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6382 This function returns a string, or NULL on error. The caller must free
6384 the returned string after use.
6385 (Added in 1.19.52)
6387 guestfs_get_libvirt_requested_credential_prompt
6389 char *
6390 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6391 int index);
6392 Get the prompt (provided by libvirt) for the "index"'th requested
6394 credential. If libvirt did not provide a prompt, this returns the
6395 empty string "".
6396 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6398 This function returns a string, or NULL on error. The caller must free
6400 the returned string after use.
6401 (Added in 1.19.52)
6403 guestfs_get_libvirt_requested_credentials
6405 char **
6406 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6407 This should only be called during the event callback for events of type
6409 "GUESTFS_EVENT_LIBVIRT_AUTH".
6410 Return the list of credentials requested by libvirt. Possible values
6412 are a subset of the strings provided when you called
6413 "guestfs_set_libvirt_supported_credentials".
6414 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6416 This function returns a NULL-terminated array of strings (like
6418 environ(3)), or NULL if there was an error. The caller must free the
6419 strings and the array after use.
6420 (Added in 1.19.52)
6422 guestfs_get_memsize
6424 int
6425 guestfs_get_memsize (guestfs_h *g);
6426 This gets the memory size in megabytes allocated to the hypervisor.
6428 If "guestfs_set_memsize" was not called on this handle, and if
6430 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6431 default value for memsize.
6432 For more information on the architecture of libguestfs, see guestfs(3).
6434 On error this function returns -1.
6436 (Added in 1.0.55)
6438 guestfs_get_network
6440 int
6441 guestfs_get_network (guestfs_h *g);
6442 This returns the enable network flag.
6444 This function returns a C truth value on success or -1 on error.
6446 (Added in 1.5.4)
6448 guestfs_get_path
6450 const char *
6451 guestfs_get_path (guestfs_h *g);
6452 Return the current search path.
6454 This is always non-NULL. If it wasn't set already, then this will
6456 return the default path.
6457 This function returns a string, or NULL on error. The string is owned
6459 by the guest handle and must not be freed.
6460 (Added in 0.3)
6462 guestfs_get_pgroup
6464 int
6465 guestfs_get_pgroup (guestfs_h *g);
6466 This returns the process group flag.
6468 This function returns a C truth value on success or -1 on error.
6470 (Added in 1.11.18)
6472 guestfs_get_pid
6474 int
6475 guestfs_get_pid (guestfs_h *g);
6476 Return the process ID of the hypervisor. If there is no hypervisor
6478 running, then this will return an error.
6479 This is an internal call used for debugging and testing.
6481 On error this function returns -1.
6483 (Added in 1.0.56)
6485 guestfs_get_program
6487 const char *
6488 guestfs_get_program (guestfs_h *g);
6489 Get the program name. See "guestfs_set_program".
6491 This function returns a string, or NULL on error. The string is owned
6493 by the guest handle and must not be freed.
6494 (Added in 1.21.29)
6496 guestfs_get_qemu
6498 const char *
6499 guestfs_get_qemu (guestfs_h *g);
6500 This function is deprecated. In new code, use the "guestfs_get_hv"
6502 call instead.
6503 Deprecated functions will not be removed from the API, but the fact
6505 that they are deprecated indicates that there are problems with correct
6506 use of these functions.
6507 Return the current hypervisor binary (usually qemu).
6509 This is always non-NULL. If it wasn't set already, then this will
6511 return the default qemu binary name.
6512 This function returns a string, or NULL on error. The string is owned
6514 by the guest handle and must not be freed.
6515 (Added in 1.0.6)
6517 guestfs_get_recovery_proc
6519 int
6520 guestfs_get_recovery_proc (guestfs_h *g);
6521 Return the recovery process enabled flag.
6523 This function returns a C truth value on success or -1 on error.
6525 (Added in 1.0.77)
6527 guestfs_get_selinux
6529 int
6530 guestfs_get_selinux (guestfs_h *g);
6531 This function is deprecated. In new code, use the
6533 "guestfs_selinux_relabel" call instead.
6534 Deprecated functions will not be removed from the API, but the fact
6536 that they are deprecated indicates that there are problems with correct
6537 use of these functions.
6538 This returns the current setting of the selinux flag which is passed to
6540 the appliance at boot time. See "guestfs_set_selinux".
6541 For more information on the architecture of libguestfs, see guestfs(3).
6543 This function returns a C truth value on success or -1 on error.
6545 (Added in 1.0.67)
6547 guestfs_get_smp
6549 int
6550 guestfs_get_smp (guestfs_h *g);
6551 This returns the number of virtual CPUs assigned to the appliance.
6553 On error this function returns -1.
6555 (Added in 1.13.15)
6557 guestfs_get_sockdir
6559 char *
6560 guestfs_get_sockdir (guestfs_h *g);
6561 Get the directory used by the handle to store temporary socket files.
6563 This is different from "guestfs_tmpdir", as we need shorter paths for
6565 sockets (due to the limited buffers of filenames for UNIX sockets), and
6566 "guestfs_tmpdir" may be too long for them.
6567 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6569 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6570 the default.
6571 This function returns a string, or NULL on error. The caller must free
6573 the returned string after use.
6574 (Added in 1.33.8)
6576 guestfs_get_state
6578 int
6579 guestfs_get_state (guestfs_h *g);
6580 This returns the current state as an opaque integer. This is only
6582 useful for printing debug and internal error messages.
6583 For more information on states, see guestfs(3).
6585 On error this function returns -1.
6587 (Added in 1.0.2)
6589 guestfs_get_tmpdir
6591 char *
6592 guestfs_get_tmpdir (guestfs_h *g);
6593 Get the directory used by the handle to store temporary files.
6595 This function returns a string, or NULL on error. The caller must free
6597 the returned string after use.
6598 (Added in 1.19.58)
6600 guestfs_get_trace
6602 int
6603 guestfs_get_trace (guestfs_h *g);
6604 Return the command trace flag.
6606 This function returns a C truth value on success or -1 on error.
6608 (Added in 1.0.69)
6610 guestfs_get_umask
6612 int
6613 guestfs_get_umask (guestfs_h *g);
6614 Return the current umask. By default the umask is 022 unless it has
6616 been set by calling "guestfs_umask".
6617 On error this function returns -1.
6619 (Added in 1.3.4)
6621 guestfs_get_verbose
6623 int
6624 guestfs_get_verbose (guestfs_h *g);
6625 This returns the verbose messages flag.
6627 This function returns a C truth value on success or -1 on error.
6629 (Added in 0.3)
6631 guestfs_getcon
6633 char *
6634 guestfs_getcon (guestfs_h *g);
6635 This function is deprecated. In new code, use the
6637 "guestfs_selinux_relabel" call instead.
6638 Deprecated functions will not be removed from the API, but the fact
6640 that they are deprecated indicates that there are problems with correct
6641 use of these functions.
6642 This gets the SELinux security context of the daemon.
6644 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6646 This function returns a string, or NULL on error. The caller must free
6648 the returned string after use.
6649 This function depends on the feature "selinux". See also
6651 "guestfs_feature_available".
6652 (Added in 1.0.67)
6654 guestfs_getxattr
6656 char *
6657 guestfs_getxattr (guestfs_h *g,
6658 const char *path,
6659 const char *name,
6660 size_t *size_r);
6661 Get a single extended attribute from file "path" named "name". This
6663 call follows symlinks. If you want to lookup an extended attribute for
6664 the symlink itself, use "guestfs_lgetxattr".
6665 Normally it is better to get all extended attributes from a file in one
6667 go by calling "guestfs_getxattrs". However some Linux filesystem
6668 implementations are buggy and do not provide a way to list out
6669 attributes. For these filesystems (notably ntfs-3g) you have to know
6670 the names of the extended attributes you want in advance and call this
6671 function.
6672 Extended attribute values are blobs of binary data. If there is no
6674 extended attribute named "name", this returns an error.
6675 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6677 This function returns a buffer, or NULL on error. The size of the
6679 returned buffer is written to *size_r. The caller must free the
6680 returned buffer after use.
6681 This function depends on the feature "linuxxattrs". See also
6683 "guestfs_feature_available".
6684 (Added in 1.7.24)
6686 guestfs_getxattrs
6688 struct guestfs_xattr_list *
6689 guestfs_getxattrs (guestfs_h *g,
6690 const char *path);
6691 This call lists the extended attributes of the file or directory
6693 "path".
6694 At the system call level, this is a combination of the listxattr(2) and
6696 getxattr(2) calls.
6697 See also: "guestfs_lgetxattrs", attr(5).
6699 This function returns a "struct guestfs_xattr_list *", or NULL if there
6701 was an error. The caller must call "guestfs_free_xattr_list" after
6702 use.
6703 This function depends on the feature "linuxxattrs". See also
6705 "guestfs_feature_available".
6706 (Added in 1.0.59)
6708 guestfs_glob_expand
6710 char **
6711 guestfs_glob_expand (guestfs_h *g,
6712 const char *pattern);
6713 This function is provided for backwards compatibility with earlier
6715 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
6716 with no optional arguments.
6717 (Added in 1.0.50)
6719 guestfs_glob_expand_opts
6721 char **
6722 guestfs_glob_expand_opts (guestfs_h *g,
6723 const char *pattern,
6724 ...);
6725 You may supply a list of optional arguments to this call. Use zero or
6727 more of the following pairs of parameters, and terminate the list with
6728 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6729 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
6731 This command searches for all the pathnames matching "pattern"
6733 according to the wildcard expansion rules used by the shell.
6734 If no paths match, then this returns an empty list (note: not an
6736 error).
6737 It is just a wrapper around the C glob(3) function with flags
6739 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
6740 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
6742 and it defaults to true. It can be explicitly set as off to return no
6743 trailing slashes in filenames of directories.
6744 Notice that there is no equivalent command for expanding a device name
6746 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
6747 etc functions instead.
6748 This function returns a NULL-terminated array of strings (like
6750 environ(3)), or NULL if there was an error. The caller must free the
6751 strings and the array after use.
6752 (Added in 1.0.50)
6754 guestfs_glob_expand_opts_va
6756 char **
6757 guestfs_glob_expand_opts_va (guestfs_h *g,
6758 const char *pattern,
6759 va_list args);
6760 This is the "va_list variant" of "guestfs_glob_expand_opts".
6762 See "CALLS WITH OPTIONAL ARGUMENTS".
6764 guestfs_glob_expand_opts_argv
6766 char **
6767 guestfs_glob_expand_opts_argv (guestfs_h *g,
6768 const char *pattern,
6769 const struct guestfs_glob_expand_opts_argv *optargs);
6770 This is the "argv variant" of "guestfs_glob_expand_opts".
6772 See "CALLS WITH OPTIONAL ARGUMENTS".
6774 guestfs_grep
6776 char **
6777 guestfs_grep (guestfs_h *g,
6778 const char *regex,
6779 const char *path);
6780 This function is provided for backwards compatibility with earlier
6782 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
6783 optional arguments.
6784 (Added in 1.0.66)
6786 guestfs_grep_opts
6788 char **
6789 guestfs_grep_opts (guestfs_h *g,
6790 const char *regex,
6791 const char *path,
6792 ...);
6793 You may supply a list of optional arguments to this call. Use zero or
6795 more of the following pairs of parameters, and terminate the list with
6796 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6797 GUESTFS_GREP_OPTS_EXTENDED, int extended,
6799 GUESTFS_GREP_OPTS_FIXED, int fixed,
6800 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
6801 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
6802 This calls the external "grep" program and returns the matching lines.
6804 The optional flags are:
6806 "extended"
6808 Use extended regular expressions. This is the same as using the -E
6809 flag.
6810 "fixed"
6812 Match fixed (don't use regular expressions). This is the same as
6813 using the -F flag.
6814 "insensitive"
6816 Match case-insensitive. This is the same as using the -i flag.
6817 "compressed"
6819 Use "zgrep" instead of "grep". This allows the input to be
6820 compress- or gzip-compressed.
6821 This function returns a NULL-terminated array of strings (like
6823 environ(3)), or NULL if there was an error. The caller must free the
6824 strings and the array after use.
6825 Because of the message protocol, there is a transfer limit of somewhere
6827 between 2MB and 4MB. See "PROTOCOL LIMITS".
6828 (Added in 1.0.66)
6830 guestfs_grep_opts_va
6832 char **
6833 guestfs_grep_opts_va (guestfs_h *g,
6834 const char *regex,
6835 const char *path,
6836 va_list args);
6837 This is the "va_list variant" of "guestfs_grep_opts".
6839 See "CALLS WITH OPTIONAL ARGUMENTS".
6841 guestfs_grep_opts_argv
6843 char **
6844 guestfs_grep_opts_argv (guestfs_h *g,
6845 const char *regex,
6846 const char *path,
6847 const struct guestfs_grep_opts_argv *optargs);
6848 This is the "argv variant" of "guestfs_grep_opts".
6850 See "CALLS WITH OPTIONAL ARGUMENTS".
6852 guestfs_grepi
6854 char **
6855 guestfs_grepi (guestfs_h *g,
6856 const char *regex,
6857 const char *path);
6858 This function is deprecated. In new code, use the "guestfs_grep" call
6860 instead.
6861 Deprecated functions will not be removed from the API, but the fact
6863 that they are deprecated indicates that there are problems with correct
6864 use of these functions.
6865 This calls the external "grep -i" program and returns the matching
6867 lines.
6868 This function returns a NULL-terminated array of strings (like
6870 environ(3)), or NULL if there was an error. The caller must free the
6871 strings and the array after use.
6872 Because of the message protocol, there is a transfer limit of somewhere
6874 between 2MB and 4MB. See "PROTOCOL LIMITS".
6875 (Added in 1.0.66)
6877 guestfs_grub_install
6879 int
6880 guestfs_grub_install (guestfs_h *g,
6881 const char *root,
6882 const char *device);
6883 This command installs GRUB 1 (the Grand Unified Bootloader) on
6885 "device", with the root directory being "root".
6886 Notes:
6888 · There is currently no way in the API to install grub2, which is
6890 used by most modern Linux guests. It is possible to run the grub2
6891 command from the guest, although see the caveats in "RUNNING
6892 COMMANDS".
6893 · This uses "grub-install" from the host. Unfortunately grub is not
6895 always compatible with itself, so this only works in rather narrow
6896 circumstances. Careful testing with each guest version is
6897 advisable.
6898 · If grub-install reports the error "No suitable drive was found in
6900 the generated device map." it may be that you need to create a
6901 /boot/grub/device.map file first that contains the mapping between
6902 grub device names and Linux device names. It is usually sufficient
6903 to create a file containing:
6904 (hd0) /dev/vda
6906 replacing /dev/vda with the name of the installation device.
6908 This function returns 0 on success or -1 on error.
6910 This function depends on the feature "grub". See also
6912 "guestfs_feature_available".
6913 (Added in 1.0.17)
6915 guestfs_head
6917 char **
6918 guestfs_head (guestfs_h *g,
6919 const char *path);
6920 This command returns up to the first 10 lines of a file as a list of
6922 strings.
6923 This function returns a NULL-terminated array of strings (like
6925 environ(3)), or NULL if there was an error. The caller must free the
6926 strings and the array after use.
6927 Because of the message protocol, there is a transfer limit of somewhere
6929 between 2MB and 4MB. See "PROTOCOL LIMITS".
6930 (Added in 1.0.54)
6932 guestfs_head_n
6934 char **
6935 guestfs_head_n (guestfs_h *g,
6936 int nrlines,
6937 const char *path);
6938 If the parameter "nrlines" is a positive number, this returns the first
6940 "nrlines" lines of the file "path".
6941 If the parameter "nrlines" is a negative number, this returns lines
6943 from the file "path", excluding the last "nrlines" lines.
6944 If the parameter "nrlines" is zero, this returns an empty list.
6946 This function returns a NULL-terminated array of strings (like
6948 environ(3)), or NULL if there was an error. The caller must free the
6949 strings and the array after use.
6950 Because of the message protocol, there is a transfer limit of somewhere
6952 between 2MB and 4MB. See "PROTOCOL LIMITS".
6953 (Added in 1.0.54)
6955 guestfs_hexdump
6957 char *
6958 guestfs_hexdump (guestfs_h *g,
6959 const char *path);
6960 This runs "hexdump -C" on the given "path". The result is the human-
6962 readable, canonical hex dump of the file.
6963 This function returns a string, or NULL on error. The caller must free
6965 the returned string after use.
6966 Because of the message protocol, there is a transfer limit of somewhere
6968 between 2MB and 4MB. See "PROTOCOL LIMITS".
6969 (Added in 1.0.22)
6971 guestfs_hivex_close
6973 int
6974 guestfs_hivex_close (guestfs_h *g);
6975 Close the current hivex handle.
6977 This is a wrapper around the hivex(3) call of the same name.
6979 This function returns 0 on success or -1 on error.
6981 This function depends on the feature "hivex". See also
6983 "guestfs_feature_available".
6984 (Added in 1.19.35)
6986 guestfs_hivex_commit
6988 int
6989 guestfs_hivex_commit (guestfs_h *g,
6990 const char *filename);
6991 Commit (write) changes to the hive.
6993 If the optional filename parameter is null, then the changes are
6995 written back to the same hive that was opened. If this is not null
6996 then they are written to the alternate filename given and the original
6997 hive is left untouched.
6998 This is a wrapper around the hivex(3) call of the same name.
7000 This function returns 0 on success or -1 on error.
7002 This function depends on the feature "hivex". See also
7004 "guestfs_feature_available".
7005 (Added in 1.19.35)
7007 guestfs_hivex_node_add_child
7009 int64_t
7010 guestfs_hivex_node_add_child (guestfs_h *g,
7011 int64_t parent,
7012 const char *name);
7013 Add a child node to "parent" named "name".
7015 This is a wrapper around the hivex(3) call of the same name.
7017 On error this function returns -1.
7019 This function depends on the feature "hivex". See also
7021 "guestfs_feature_available".
7022 (Added in 1.19.35)
7024 guestfs_hivex_node_children
7026 struct guestfs_hivex_node_list *
7027 guestfs_hivex_node_children (guestfs_h *g,
7028 int64_t nodeh);
7029 Return the list of nodes which are subkeys of "nodeh".
7031 This is a wrapper around the hivex(3) call of the same name.
7033 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7035 there was an error. The caller must call
7036 "guestfs_free_hivex_node_list" after use.
7037 This function depends on the feature "hivex". See also
7039 "guestfs_feature_available".
7040 (Added in 1.19.35)
7042 guestfs_hivex_node_delete_child
7044 int
7045 guestfs_hivex_node_delete_child (guestfs_h *g,
7046 int64_t nodeh);
7047 Delete "nodeh", recursively if necessary.
7049 This is a wrapper around the hivex(3) call of the same name.
7051 This function returns 0 on success or -1 on error.
7053 This function depends on the feature "hivex". See also
7055 "guestfs_feature_available".
7056 (Added in 1.19.35)
7058 guestfs_hivex_node_get_child
7060 int64_t
7061 guestfs_hivex_node_get_child (guestfs_h *g,
7062 int64_t nodeh,
7063 const char *name);
7064 Return the child of "nodeh" with the name "name", if it exists. This
7066 can return 0 meaning the name was not found.
7067 This is a wrapper around the hivex(3) call of the same name.
7069 On error this function returns -1.
7071 This function depends on the feature "hivex". See also
7073 "guestfs_feature_available".
7074 (Added in 1.19.35)
7076 guestfs_hivex_node_get_value
7078 int64_t
7079 guestfs_hivex_node_get_value (guestfs_h *g,
7080 int64_t nodeh,
7081 const char *key);
7082 Return the value attached to "nodeh" which has the name "key", if it
7084 exists. This can return 0 meaning the key was not found.
7085 This is a wrapper around the hivex(3) call of the same name.
7087 On error this function returns -1.
7089 This function depends on the feature "hivex". See also
7091 "guestfs_feature_available".
7092 (Added in 1.19.35)
7094 guestfs_hivex_node_name
7096 char *
7097 guestfs_hivex_node_name (guestfs_h *g,
7098 int64_t nodeh);
7099 Return the name of "nodeh".
7101 This is a wrapper around the hivex(3) call of the same name.
7103 This function returns a string, or NULL on error. The caller must free
7105 the returned string after use.
7106 This function depends on the feature "hivex". See also
7108 "guestfs_feature_available".
7109 (Added in 1.19.35)
7111 guestfs_hivex_node_parent
7113 int64_t
7114 guestfs_hivex_node_parent (guestfs_h *g,
7115 int64_t nodeh);
7116 Return the parent node of "nodeh".
7118 This is a wrapper around the hivex(3) call of the same name.
7120 On error this function returns -1.
7122 This function depends on the feature "hivex". See also
7124 "guestfs_feature_available".
7125 (Added in 1.19.35)
7127 guestfs_hivex_node_set_value
7129 int
7130 guestfs_hivex_node_set_value (guestfs_h *g,
7131 int64_t nodeh,
7132 const char *key,
7133 int64_t t,
7134 const char *val,
7135 size_t val_size);
7136 Set or replace a single value under the node "nodeh". The "key" is the
7138 name, "t" is the type, and "val" is the data.
7139 This is a wrapper around the hivex(3) call of the same name.
7141 This function returns 0 on success or -1 on error.
7143 This function depends on the feature "hivex". See also
7145 "guestfs_feature_available".
7146 (Added in 1.19.35)
7148 guestfs_hivex_node_values
7150 struct guestfs_hivex_value_list *
7151 guestfs_hivex_node_values (guestfs_h *g,
7152 int64_t nodeh);
7153 Return the array of (key, datatype, data) tuples attached to "nodeh".
7155 This is a wrapper around the hivex(3) call of the same name.
7157 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7159 there was an error. The caller must call
7160 "guestfs_free_hivex_value_list" after use.
7161 This function depends on the feature "hivex". See also
7163 "guestfs_feature_available".
7164 (Added in 1.19.35)
7166 guestfs_hivex_open
7168 int
7169 guestfs_hivex_open (guestfs_h *g,
7170 const char *filename,
7171 ...);
7172 You may supply a list of optional arguments to this call. Use zero or
7174 more of the following pairs of parameters, and terminate the list with
7175 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7176 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7178 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7179 GUESTFS_HIVEX_OPEN_WRITE, int write,
7180 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7181 Open the Windows Registry hive file named filename. If there was any
7183 previous hivex handle associated with this guestfs session, then it is
7184 closed.
7185 This is a wrapper around the hivex(3) call of the same name.
7187 This function returns 0 on success or -1 on error.
7189 This function depends on the feature "hivex". See also
7191 "guestfs_feature_available".
7192 (Added in 1.19.35)
7194 guestfs_hivex_open_va
7196 int
7197 guestfs_hivex_open_va (guestfs_h *g,
7198 const char *filename,
7199 va_list args);
7200 This is the "va_list variant" of "guestfs_hivex_open".
7202 See "CALLS WITH OPTIONAL ARGUMENTS".
7204 guestfs_hivex_open_argv
7206 int
7207 guestfs_hivex_open_argv (guestfs_h *g,
7208 const char *filename,
7209 const struct guestfs_hivex_open_argv *optargs);
7210 This is the "argv variant" of "guestfs_hivex_open".
7212 See "CALLS WITH OPTIONAL ARGUMENTS".
7214 guestfs_hivex_root
7216 int64_t
7217 guestfs_hivex_root (guestfs_h *g);
7218 Return the root node of the hive.
7220 This is a wrapper around the hivex(3) call of the same name.
7222 On error this function returns -1.
7224 This function depends on the feature "hivex". See also
7226 "guestfs_feature_available".
7227 (Added in 1.19.35)
7229 guestfs_hivex_value_key
7231 char *
7232 guestfs_hivex_value_key (guestfs_h *g,
7233 int64_t valueh);
7234 Return the key (name) field of a (key, datatype, data) tuple.
7236 This is a wrapper around the hivex(3) call of the same name.
7238 This function returns a string, or NULL on error. The caller must free
7240 the returned string after use.
7241 This function depends on the feature "hivex". See also
7243 "guestfs_feature_available".
7244 (Added in 1.19.35)
7246 guestfs_hivex_value_string
7248 char *
7249 guestfs_hivex_value_string (guestfs_h *g,
7250 int64_t valueh);
7251 This calls "guestfs_hivex_value_value" (which returns the data field
7253 from a hivex value tuple). It then assumes that the field is a
7254 UTF-16LE string and converts the result to UTF-8 (or if this is not
7255 possible, it returns an error).
7256 This is useful for reading strings out of the Windows registry.
7258 However it is not foolproof because the registry is not strongly-typed
7259 and fields can contain arbitrary or unexpected data.
7260 This function returns a string, or NULL on error. The caller must free
7262 the returned string after use.
7263 This function depends on the feature "hivex". See also
7265 "guestfs_feature_available".
7266 (Added in 1.37.22)
7268 guestfs_hivex_value_type
7270 int64_t
7271 guestfs_hivex_value_type (guestfs_h *g,
7272 int64_t valueh);
7273 Return the data type field from a (key, datatype, data) tuple.
7275 This is a wrapper around the hivex(3) call of the same name.
7277 On error this function returns -1.
7279 This function depends on the feature "hivex". See also
7281 "guestfs_feature_available".
7282 (Added in 1.19.35)
7284 guestfs_hivex_value_utf8
7286 char *
7287 guestfs_hivex_value_utf8 (guestfs_h *g,
7288 int64_t valueh);
7289 This function is deprecated. In new code, use the
7291 "guestfs_hivex_value_string" call instead.
7292 Deprecated functions will not be removed from the API, but the fact
7294 that they are deprecated indicates that there are problems with correct
7295 use of these functions.
7296 This calls "guestfs_hivex_value_value" (which returns the data field
7298 from a hivex value tuple). It then assumes that the field is a
7299 UTF-16LE string and converts the result to UTF-8 (or if this is not
7300 possible, it returns an error).
7301 This is useful for reading strings out of the Windows registry.
7303 However it is not foolproof because the registry is not strongly-typed
7304 and fields can contain arbitrary or unexpected data.
7305 This function returns a string, or NULL on error. The caller must free
7307 the returned string after use.
7308 This function depends on the feature "hivex". See also
7310 "guestfs_feature_available".
7311 (Added in 1.19.35)
7313 guestfs_hivex_value_value
7315 char *
7316 guestfs_hivex_value_value (guestfs_h *g,
7317 int64_t valueh,
7318 size_t *size_r);
7319 Return the data field of a (key, datatype, data) tuple.
7321 This is a wrapper around the hivex(3) call of the same name.
7323 See also: "guestfs_hivex_value_utf8".
7325 This function returns a buffer, or NULL on error. The size of the
7327 returned buffer is written to *size_r. The caller must free the
7328 returned buffer after use.
7329 This function depends on the feature "hivex". See also
7331 "guestfs_feature_available".
7332 (Added in 1.19.35)
7334 guestfs_initrd_cat
7336 char *
7337 guestfs_initrd_cat (guestfs_h *g,
7338 const char *initrdpath,
7339 const char *filename,
7340 size_t *size_r);
7341 This command unpacks the file filename from the initrd file called
7343 initrdpath. The filename must be given without the initial /
7344 character.
7345 For example, in guestfish you could use the following command to
7347 examine the boot script (usually called /init) contained in a Linux
7348 initrd or initramfs image:
7349 initrd-cat /boot/initrd-<version>.img init
7351 See also "guestfs_initrd_list".
7353 This function returns a buffer, or NULL on error. The size of the
7355 returned buffer is written to *size_r. The caller must free the
7356 returned buffer after use.
7357 Because of the message protocol, there is a transfer limit of somewhere
7359 between 2MB and 4MB. See "PROTOCOL LIMITS".
7360 (Added in 1.0.84)
7362 guestfs_initrd_list
7364 char **
7365 guestfs_initrd_list (guestfs_h *g,
7366 const char *path);
7367 This command lists out files contained in an initrd.
7369 The files are listed without any initial / character. The files are
7371 listed in the order they appear (not necessarily alphabetical).
7372 Directory names are listed as separate items.
7373 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7375 as initrd. We only support the newer initramfs format (compressed cpio
7376 files).
7377 This function returns a NULL-terminated array of strings (like
7379 environ(3)), or NULL if there was an error. The caller must free the
7380 strings and the array after use.
7381 (Added in 1.0.54)
7383 guestfs_inotify_add_watch
7385 int64_t
7386 guestfs_inotify_add_watch (guestfs_h *g,
7387 const char *path,
7388 int mask);
7389 Watch "path" for the events listed in "mask".
7391 Note that if "path" is a directory then events within that directory
7393 are watched, but this does not happen recursively (in subdirectories).
7394 Note for non-C or non-Linux callers: the inotify events are defined by
7396 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7397 On error this function returns -1.
7399 This function depends on the feature "inotify". See also
7401 "guestfs_feature_available".
7402 (Added in 1.0.66)
7404 guestfs_inotify_close
7406 int
7407 guestfs_inotify_close (guestfs_h *g);
7408 This closes the inotify handle which was previously opened by
7410 inotify_init. It removes all watches, throws away any pending events,
7411 and deallocates all resources.
7412 This function returns 0 on success or -1 on error.
7414 This function depends on the feature "inotify". See also
7416 "guestfs_feature_available".
7417 (Added in 1.0.66)
7419 guestfs_inotify_files
7421 char **
7422 guestfs_inotify_files (guestfs_h *g);
7423 This function is a helpful wrapper around "guestfs_inotify_read" which
7425 just returns a list of pathnames of objects that were touched. The
7426 returned pathnames are sorted and deduplicated.
7427 This function returns a NULL-terminated array of strings (like
7429 environ(3)), or NULL if there was an error. The caller must free the
7430 strings and the array after use.
7431 This function depends on the feature "inotify". See also
7433 "guestfs_feature_available".
7434 (Added in 1.0.66)
7436 guestfs_inotify_init
7438 int
7439 guestfs_inotify_init (guestfs_h *g,
7440 int maxevents);
7441 This command creates a new inotify handle. The inotify subsystem can
7443 be used to notify events which happen to objects in the guest
7444 filesystem.
7445 "maxevents" is the maximum number of events which will be queued up
7447 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7448 this is passed as 0, then the kernel (or previously set) default is
7449 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7450 limit, the kernel throws away events, but records the fact that it
7451 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7452 structure list (see "guestfs_inotify_read").
7453 Before any events are generated, you have to add some watches to the
7455 internal watch list. See: "guestfs_inotify_add_watch" and
7456 "guestfs_inotify_rm_watch".
7457 Queued up events should be read periodically by calling
7459 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7460 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7461 events out often enough then you risk the internal queue overflowing.
7462 The handle should be closed after use by calling
7464 "guestfs_inotify_close". This also removes any watches automatically.
7465 See also inotify(7) for an overview of the inotify interface as exposed
7467 by the Linux kernel, which is roughly what we expose via libguestfs.
7468 Note that there is one global inotify handle per libguestfs instance.
7469 This function returns 0 on success or -1 on error.
7471 This function depends on the feature "inotify". See also
7473 "guestfs_feature_available".
7474 (Added in 1.0.66)
7476 guestfs_inotify_read
7478 struct guestfs_inotify_event_list *
7479 guestfs_inotify_read (guestfs_h *g);
7480 Return the complete queue of events that have happened since the
7482 previous read call.
7483 If no events have happened, this returns an empty list.
7485 Note: In order to make sure that all events have been read, you must
7487 call this function repeatedly until it returns an empty list. The
7488 reason is that the call will read events up to the maximum appliance-
7489 to-host message size and leave remaining events in the queue.
7490 This function returns a "struct guestfs_inotify_event_list *", or NULL
7492 if there was an error. The caller must call
7493 "guestfs_free_inotify_event_list" after use.
7494 This function depends on the feature "inotify". See also
7496 "guestfs_feature_available".
7497 (Added in 1.0.66)
7499 guestfs_inotify_rm_watch
7501 int
7502 guestfs_inotify_rm_watch (guestfs_h *g,
7503 int wd);
7504 Remove a previously defined inotify watch. See
7506 "guestfs_inotify_add_watch".
7507 This function returns 0 on success or -1 on error.
7509 This function depends on the feature "inotify". See also
7511 "guestfs_feature_available".
7512 (Added in 1.0.66)
7514 guestfs_inspect_get_arch
7516 char *
7517 guestfs_inspect_get_arch (guestfs_h *g,
7518 const char *root);
7519 This returns the architecture of the inspected operating system. The
7521 possible return values are listed under "guestfs_file_architecture".
7522 If the architecture could not be determined, then the string "unknown"
7524 is returned.
7525 Please read "INSPECTION" for more details.
7527 This function returns a string, or NULL on error. The caller must free
7529 the returned string after use.
7530 (Added in 1.5.3)
7532 guestfs_inspect_get_distro
7534 char *
7535 guestfs_inspect_get_distro (guestfs_h *g,
7536 const char *root);
7537 This returns the distro (distribution) of the inspected operating
7539 system.
7540 Currently defined distros are:
7542 "alpinelinux"
7544 Alpine Linux.
7545 "altlinux"
7547 ALT Linux.
7548 "archlinux"
7550 Arch Linux.
7551 "buildroot"
7553 Buildroot-derived distro, but not one we specifically recognize.
7554 "centos"
7556 CentOS.
7557 "cirros"
7559 Cirros.
7560 "coreos"
7562 CoreOS.
7563 "debian"
7565 Debian.
7566 "fedora"
7568 Fedora.
7569 "freebsd"
7571 FreeBSD.
7572 "freedos"
7574 FreeDOS.
7575 "frugalware"
7577 Frugalware.
7578 "gentoo"
7580 Gentoo.
7581 "linuxmint"
7583 Linux Mint.
7584 "mageia"
7586 Mageia.
7587 "mandriva"
7589 Mandriva.
7590 "meego"
7592 MeeGo.
7593 "msdos"
7595 Microsoft DOS.
7596 "neokylin"
7598 NeoKylin.
7599 "netbsd"
7601 NetBSD.
7602 "openbsd"
7604 OpenBSD.
7605 "opensuse"
7607 OpenSUSE.
7608 "oraclelinux"
7610 Oracle Linux.
7611 "pardus"
7613 Pardus.
7614 "pldlinux"
7616 PLD Linux.
7617 "redhat-based"
7619 Some Red Hat-derived distro.
7620 "rhel"
7622 Red Hat Enterprise Linux.
7623 "scientificlinux"
7625 Scientific Linux.
7626 "slackware"
7628 Slackware.
7629 "sles"
7631 SuSE Linux Enterprise Server or Desktop.
7632 "suse-based"
7634 Some openSuSE-derived distro.
7635 "ttylinux"
7637 ttylinux.
7638 "ubuntu"
7640 Ubuntu.
7641 "unknown"
7643 The distro could not be determined.
7644 "voidlinux"
7646 Void Linux.
7647 "windows"
7649 Windows does not have distributions. This string is returned if
7650 the OS type is Windows.
7651 Future versions of libguestfs may return other strings here. The
7653 caller should be prepared to handle any string.
7654 Please read "INSPECTION" for more details.
7656 This function returns a string, or NULL on error. The caller must free
7658 the returned string after use.
7659 (Added in 1.5.3)
7661 guestfs_inspect_get_drive_mappings
7663 char **
7664 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7665 const char *root);
7666 This call is useful for Windows which uses a primitive system of
7668 assigning drive letters (like C:\) to partitions. This inspection API
7669 examines the Windows Registry to find out how disks/partitions are
7670 mapped to drive letters, and returns a hash table as in the example
7671 below:
7672 C => /dev/vda2
7674 E => /dev/vdb1
7675 F => /dev/vdc1
7676 Note that keys are drive letters. For Windows, the key is case
7678 insensitive and just contains the drive letter, without the customary
7679 colon separator character.
7680 In future we may support other operating systems that also used drive
7682 letters, but the keys for those might not be case insensitive and might
7683 be longer than 1 character. For example in OS-9, hard drives were
7684 named "h0", "h1" etc.
7685 For Windows guests, currently only hard drive mappings are returned.
7687 Removable disks (eg. DVD-ROMs) are ignored.
7688 For guests that do not use drive mappings, or if the drive mappings
7690 could not be determined, this returns an empty hash table.
7691 Please read "INSPECTION" for more details. See also
7693 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7694 This function returns a NULL-terminated array of strings, or NULL if
7696 there was an error. The array of strings will always have length
7697 "2n+1", where "n" keys and values alternate, followed by the trailing
7698 NULL entry. The caller must free the strings and the array after use.
7699 (Added in 1.9.17)
7701 guestfs_inspect_get_filesystems
7703 char **
7704 guestfs_inspect_get_filesystems (guestfs_h *g,
7705 const char *root);
7706 This returns a list of all the filesystems that we think are associated
7708 with this operating system. This includes the root filesystem, other
7709 ordinary filesystems, and non-mounted devices like swap partitions.
7710 In the case of a multi-boot virtual machine, it is possible for a
7712 filesystem to be shared between operating systems.
7713 Please read "INSPECTION" for more details. See also
7715 "guestfs_inspect_get_mountpoints".
7716 This function returns a NULL-terminated array of strings (like
7718 environ(3)), or NULL if there was an error. The caller must free the
7719 strings and the array after use.
7720 (Added in 1.5.3)
7722 guestfs_inspect_get_format
7724 char *
7725 guestfs_inspect_get_format (guestfs_h *g,
7726 const char *root);
7727 This function is deprecated. There is no replacement. Consult the API
7729 documentation in guestfs(3) for further information.
7730 Deprecated functions will not be removed from the API, but the fact
7732 that they are deprecated indicates that there are problems with correct
7733 use of these functions.
7734 Before libguestfs 1.38, there was some unreliable support for detecting
7736 installer CDs. This API would return:
7737 "installed"
7739 This is an installed operating system.
7740 "installer"
7742 The disk image being inspected is not an installed operating
7743 system, but a bootable install disk, live CD, or similar.
7744 "unknown"
7746 The format of this disk image is not known.
7747 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
7749 directly to detect installer CDs.
7750 Please read "INSPECTION" for more details.
7752 This function returns a string, or NULL on error. The caller must free
7754 the returned string after use.
7755 (Added in 1.9.4)
7757 guestfs_inspect_get_hostname
7759 char *
7760 guestfs_inspect_get_hostname (guestfs_h *g,
7761 const char *root);
7762 This function returns the hostname of the operating system as found by
7764 inspection of the guest’s configuration files.
7765 If the hostname could not be determined, then the string "unknown" is
7767 returned.
7768 Please read "INSPECTION" for more details.
7770 This function returns a string, or NULL on error. The caller must free
7772 the returned string after use.
7773 (Added in 1.7.9)
7775 guestfs_inspect_get_icon
7777 char *
7778 guestfs_inspect_get_icon (guestfs_h *g,
7779 const char *root,
7780 size_t *size_r,
7781 ...);
7782 You may supply a list of optional arguments to this call. Use zero or
7784 more of the following pairs of parameters, and terminate the list with
7785 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7786 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
7788 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
7789 This function returns an icon corresponding to the inspected operating
7791 system. The icon is returned as a buffer containing a PNG image (re-
7792 encoded to PNG if necessary).
7793 If it was not possible to get an icon this function returns a zero-
7795 length (non-NULL) buffer. Callers must check for this case.
7796 Libguestfs will start by looking for a file called /etc/favicon.png or
7798 C:\etc\favicon.png and if it has the correct format, the contents of
7799 this file will be returned. You can disable favicons by passing the
7800 optional "favicon" boolean as false (default is true).
7801 If finding the favicon fails, then we look in other places in the guest
7803 for a suitable icon.
7804 If the optional "highquality" boolean is true then only high quality
7806 icons are returned, which means only icons of high resolution with an
7807 alpha channel. The default (false) is to return any icon we can, even
7808 if it is of substandard quality.
7809 Notes:
7811 · Unlike most other inspection API calls, the guest’s disks must be
7813 mounted up before you call this, since it needs to read information
7814 from the guest filesystem during the call.
7815 · Security: The icon data comes from the untrusted guest, and should
7817 be treated with caution. PNG files have been known to contain
7818 exploits. Ensure that libpng (or other relevant libraries) are
7819 fully up to date before trying to process or display the icon.
7820 · The PNG image returned can be any size. It might not be square.
7822 Libguestfs tries to return the largest, highest quality icon
7823 available. The application must scale the icon to the required
7824 size.
7825 · Extracting icons from Windows guests requires the external
7827 "wrestool" program from the "icoutils" package, and several
7828 programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
7829 package. These must be installed separately.
7830 · Operating system icons are usually trademarks. Seek legal advice
7832 before using trademarks in applications.
7833 This function returns a buffer, or NULL on error. The size of the
7835 returned buffer is written to *size_r. The caller must free the
7836 returned buffer after use.
7837 (Added in 1.11.12)
7839 guestfs_inspect_get_icon_va
7841 char *
7842 guestfs_inspect_get_icon_va (guestfs_h *g,
7843 const char *root,
7844 size_t *size_r,
7845 va_list args);
7846 This is the "va_list variant" of "guestfs_inspect_get_icon".
7848 See "CALLS WITH OPTIONAL ARGUMENTS".
7850 guestfs_inspect_get_icon_argv
7852 char *
7853 guestfs_inspect_get_icon_argv (guestfs_h *g,
7854 const char *root,
7855 size_t *size_r,
7856 const struct guestfs_inspect_get_icon_argv *optargs);
7857 This is the "argv variant" of "guestfs_inspect_get_icon".
7859 See "CALLS WITH OPTIONAL ARGUMENTS".
7861 guestfs_inspect_get_major_version
7863 int
7864 guestfs_inspect_get_major_version (guestfs_h *g,
7865 const char *root);
7866 This returns the major version number of the inspected operating
7868 system.
7869 Windows uses a consistent versioning scheme which is not reflected in
7871 the popular public names used by the operating system. Notably the
7872 operating system known as "Windows 7" is really version 6.1 (ie. major
7873 = 6, minor = 1). You can find out the real versions corresponding to
7874 releases of Windows by consulting Wikipedia or MSDN.
7875 If the version could not be determined, then 0 is returned.
7877 Please read "INSPECTION" for more details.
7879 On error this function returns -1.
7881 (Added in 1.5.3)
7883 guestfs_inspect_get_minor_version
7885 int
7886 guestfs_inspect_get_minor_version (guestfs_h *g,
7887 const char *root);
7888 This returns the minor version number of the inspected operating
7890 system.
7891 If the version could not be determined, then 0 is returned.
7893 Please read "INSPECTION" for more details. See also
7895 "guestfs_inspect_get_major_version".
7896 On error this function returns -1.
7898 (Added in 1.5.3)
7900 guestfs_inspect_get_mountpoints
7902 char **
7903 guestfs_inspect_get_mountpoints (guestfs_h *g,
7904 const char *root);
7905 This returns a hash of where we think the filesystems associated with
7907 this operating system should be mounted. Callers should note that this
7908 is at best an educated guess made by reading configuration files such
7909 as /etc/fstab. In particular note that this may return filesystems
7910 which are non-existent or not mountable and callers should be prepared
7911 to handle or ignore failures if they try to mount them.
7912 Each element in the returned hashtable has a key which is the path of
7914 the mountpoint (eg. /boot) and a value which is the filesystem that
7915 would be mounted there (eg. /dev/sda1).
7916 Non-mounted devices such as swap devices are not returned in this list.
7918 For operating systems like Windows which still use drive letters, this
7920 call will only return an entry for the first drive "mounted on" /. For
7921 information about the mapping of drive letters to partitions, see
7922 "guestfs_inspect_get_drive_mappings".
7923 Please read "INSPECTION" for more details. See also
7925 "guestfs_inspect_get_filesystems".
7926 This function returns a NULL-terminated array of strings, or NULL if
7928 there was an error. The array of strings will always have length
7929 "2n+1", where "n" keys and values alternate, followed by the trailing
7930 NULL entry. The caller must free the strings and the array after use.
7931 (Added in 1.5.3)
7933 guestfs_inspect_get_osinfo
7935 char *
7936 guestfs_inspect_get_osinfo (guestfs_h *g,
7937 const char *root);
7938 This function returns a possible short ID for libosinfo corresponding
7940 to the guest.
7941 Note: The returned ID is only a guess by libguestfs, and nothing
7943 ensures that it actually exists in osinfo-db.
7944 If no ID could not be determined, then the string "unknown" is
7946 returned.
7947 This function returns a string, or NULL on error. The caller must free
7949 the returned string after use.
7950 (Added in 1.39.1)
7952 guestfs_inspect_get_package_format
7954 char *
7955 guestfs_inspect_get_package_format (guestfs_h *g,
7956 const char *root);
7957 This function and "guestfs_inspect_get_package_management" return the
7959 package format and package management tool used by the inspected
7960 operating system. For example for Fedora these functions would return
7961 "rpm" (package format), and "yum" or "dnf" (package management).
7962 This returns the string "unknown" if we could not determine the package
7964 format or if the operating system does not have a real packaging system
7965 (eg. Windows).
7966 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
7968 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
7969 other strings.
7970 Please read "INSPECTION" for more details.
7972 This function returns a string, or NULL on error. The caller must free
7974 the returned string after use.
7975 (Added in 1.7.5)
7977 guestfs_inspect_get_package_management
7979 char *
7980 guestfs_inspect_get_package_management (guestfs_h *g,
7981 const char *root);
7982 "guestfs_inspect_get_package_format" and this function return the
7984 package format and package management tool used by the inspected
7985 operating system. For example for Fedora these functions would return
7986 "rpm" (package format), and "yum" or "dnf" (package management).
7987 This returns the string "unknown" if we could not determine the package
7989 management tool or if the operating system does not have a real
7990 packaging system (eg. Windows).
7991 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
7993 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
7994 "apk", "xbps". Future versions of libguestfs may return other strings.
7995 Please read "INSPECTION" for more details.
7997 This function returns a string, or NULL on error. The caller must free
7999 the returned string after use.
8000 (Added in 1.7.5)
8002 guestfs_inspect_get_product_name
8004 char *
8005 guestfs_inspect_get_product_name (guestfs_h *g,
8006 const char *root);
8007 This returns the product name of the inspected operating system. The
8009 product name is generally some freeform string which can be displayed
8010 to the user, but should not be parsed by programs.
8011 If the product name could not be determined, then the string "unknown"
8013 is returned.
8014 Please read "INSPECTION" for more details.
8016 This function returns a string, or NULL on error. The caller must free
8018 the returned string after use.
8019 (Added in 1.5.3)
8021 guestfs_inspect_get_product_variant
8023 char *
8024 guestfs_inspect_get_product_variant (guestfs_h *g,
8025 const char *root);
8026 This returns the product variant of the inspected operating system.
8028 For Windows guests, this returns the contents of the Registry key
8030 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8031 which is usually a string such as "Client" or "Server" (other values
8032 are possible). This can be used to distinguish consumer and enterprise
8033 versions of Windows that have the same version number (for example,
8034 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8035 is "Client" and the latter is "Server").
8036 For enterprise Linux guests, in future we intend this to return the
8038 product variant such as "Desktop", "Server" and so on. But this is not
8039 implemented at present.
8040 If the product variant could not be determined, then the string
8042 "unknown" is returned.
8043 Please read "INSPECTION" for more details. See also
8045 "guestfs_inspect_get_product_name",
8046 "guestfs_inspect_get_major_version".
8047 This function returns a string, or NULL on error. The caller must free
8049 the returned string after use.
8050 (Added in 1.9.13)
8052 guestfs_inspect_get_roots
8054 char **
8055 guestfs_inspect_get_roots (guestfs_h *g);
8056 This function is a convenient way to get the list of root devices, as
8058 returned from a previous call to "guestfs_inspect_os", but without
8059 redoing the whole inspection process.
8060 This returns an empty list if either no root devices were found or the
8062 caller has not called "guestfs_inspect_os".
8063 Please read "INSPECTION" for more details.
8065 This function returns a NULL-terminated array of strings (like
8067 environ(3)), or NULL if there was an error. The caller must free the
8068 strings and the array after use.
8069 (Added in 1.7.3)
8071 guestfs_inspect_get_type
8073 char *
8074 guestfs_inspect_get_type (guestfs_h *g,
8075 const char *root);
8076 This returns the type of the inspected operating system. Currently
8078 defined types are:
8079 "linux"
8081 Any Linux-based operating system.
8082 "windows"
8084 Any Microsoft Windows operating system.
8085 "freebsd"
8087 FreeBSD.
8088 "netbsd"
8090 NetBSD.
8091 "openbsd"
8093 OpenBSD.
8094 "hurd"
8096 GNU/Hurd.
8097 "dos"
8099 MS-DOS, FreeDOS and others.
8100 "minix"
8102 MINIX.
8103 "unknown"
8105 The operating system type could not be determined.
8106 Future versions of libguestfs may return other strings here. The
8108 caller should be prepared to handle any string.
8109 Please read "INSPECTION" for more details.
8111 This function returns a string, or NULL on error. The caller must free
8113 the returned string after use.
8114 (Added in 1.5.3)
8116 guestfs_inspect_get_windows_current_control_set
8118 char *
8119 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8120 const char *root);
8121 This returns the Windows CurrentControlSet of the inspected guest. The
8123 CurrentControlSet is a registry key name such as "ControlSet001".
8124 This call assumes that the guest is Windows and that the Registry could
8126 be examined by inspection. If this is not the case then an error is
8127 returned.
8128 Please read "INSPECTION" for more details.
8130 This function returns a string, or NULL on error. The caller must free
8132 the returned string after use.
8133 (Added in 1.9.17)
8135 guestfs_inspect_get_windows_software_hive
8137 char *
8138 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8139 const char *root);
8140 This returns the path to the hive (binary Windows Registry file)
8142 corresponding to HKLM\SOFTWARE.
8143 This call assumes that the guest is Windows and that the guest has a
8145 software hive file with the right name. If this is not the case then
8146 an error is returned. This call does not check that the hive is a
8147 valid Windows Registry hive.
8148 You can use "guestfs_hivex_open" to read or write to the hive.
8150 Please read "INSPECTION" for more details.
8152 This function returns a string, or NULL on error. The caller must free
8154 the returned string after use.
8155 (Added in 1.35.26)
8157 guestfs_inspect_get_windows_system_hive
8159 char *
8160 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8161 const char *root);
8162 This returns the path to the hive (binary Windows Registry file)
8164 corresponding to HKLM\SYSTEM.
8165 This call assumes that the guest is Windows and that the guest has a
8167 system hive file with the right name. If this is not the case then an
8168 error is returned. This call does not check that the hive is a valid
8169 Windows Registry hive.
8170 You can use "guestfs_hivex_open" to read or write to the hive.
8172 Please read "INSPECTION" for more details.
8174 This function returns a string, or NULL on error. The caller must free
8176 the returned string after use.
8177 (Added in 1.35.26)
8179 guestfs_inspect_get_windows_systemroot
8181 char *
8182 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8183 const char *root);
8184 This returns the Windows systemroot of the inspected guest. The
8186 systemroot is a directory path such as /WINDOWS.
8187 This call assumes that the guest is Windows and that the systemroot
8189 could be determined by inspection. If this is not the case then an
8190 error is returned.
8191 Please read "INSPECTION" for more details.
8193 This function returns a string, or NULL on error. The caller must free
8195 the returned string after use.
8196 (Added in 1.5.25)
8198 guestfs_inspect_is_live
8200 int
8201 guestfs_inspect_is_live (guestfs_h *g,
8202 const char *root);
8203 This function is deprecated. There is no replacement. Consult the API
8205 documentation in guestfs(3) for further information.
8206 Deprecated functions will not be removed from the API, but the fact
8208 that they are deprecated indicates that there are problems with correct
8209 use of these functions.
8210 This is deprecated and always returns "false".
8212 Please read "INSPECTION" for more details.
8214 This function returns a C truth value on success or -1 on error.
8216 (Added in 1.9.4)
8218 guestfs_inspect_is_multipart
8220 int
8221 guestfs_inspect_is_multipart (guestfs_h *g,
8222 const char *root);
8223 This function is deprecated. There is no replacement. Consult the API
8225 documentation in guestfs(3) for further information.
8226 Deprecated functions will not be removed from the API, but the fact
8228 that they are deprecated indicates that there are problems with correct
8229 use of these functions.
8230 This is deprecated and always returns "false".
8232 Please read "INSPECTION" for more details.
8234 This function returns a C truth value on success or -1 on error.
8236 (Added in 1.9.4)
8238 guestfs_inspect_is_netinst
8240 int
8241 guestfs_inspect_is_netinst (guestfs_h *g,
8242 const char *root);
8243 This function is deprecated. There is no replacement. Consult the API
8245 documentation in guestfs(3) for further information.
8246 Deprecated functions will not be removed from the API, but the fact
8248 that they are deprecated indicates that there are problems with correct
8249 use of these functions.
8250 This is deprecated and always returns "false".
8252 Please read "INSPECTION" for more details.
8254 This function returns a C truth value on success or -1 on error.
8256 (Added in 1.9.4)
8258 guestfs_inspect_list_applications
8260 struct guestfs_application_list *
8261 guestfs_inspect_list_applications (guestfs_h *g,
8262 const char *root);
8263 This function is deprecated. In new code, use the
8265 "guestfs_inspect_list_applications2" call instead.
8266 Deprecated functions will not be removed from the API, but the fact
8268 that they are deprecated indicates that there are problems with correct
8269 use of these functions.
8270 Return the list of applications installed in the operating system.
8272 Note: This call works differently from other parts of the inspection
8274 API. You have to call "guestfs_inspect_os", then
8275 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8276 calling this. Listing applications is a significantly more difficult
8277 operation which requires access to the full filesystem. Also note that
8278 unlike the other "guestfs_inspect_get_*" calls which are just returning
8279 data cached in the libguestfs handle, this call actually reads parts of
8280 the mounted filesystems during the call.
8281 This returns an empty list if the inspection code was not able to
8283 determine the list of applications.
8284 The application structure contains the following fields:
8286 "app_name"
8288 The name of the application. For Red Hat-derived and Debian-
8289 derived Linux guests, this is the package name.
8290 "app_display_name"
8292 The display name of the application, sometimes localized to the
8293 install language of the guest operating system.
8294 If unavailable this is returned as an empty string "". Callers
8296 needing to display something can use "app_name" instead.
8297 "app_epoch"
8299 For package managers which use epochs, this contains the epoch of
8300 the package (an integer). If unavailable, this is returned as 0.
8301 "app_version"
8303 The version string of the application or package. If unavailable
8304 this is returned as an empty string "".
8305 "app_release"
8307 The release string of the application or package, for package
8308 managers that use this. If unavailable this is returned as an
8309 empty string "".
8310 "app_install_path"
8312 The installation path of the application (on operating systems such
8313 as Windows which use installation paths). This path is in the
8314 format used by the guest operating system, it is not a libguestfs
8315 path.
8316 If unavailable this is returned as an empty string "".
8318 "app_trans_path"
8320 The install path translated into a libguestfs path. If unavailable
8321 this is returned as an empty string "".
8322 "app_publisher"
8324 The name of the publisher of the application, for package managers
8325 that use this. If unavailable this is returned as an empty string
8326 "".
8327 "app_url"
8329 The URL (eg. upstream URL) of the application. If unavailable this
8330 is returned as an empty string "".
8331 "app_source_package"
8333 For packaging systems which support this, the name of the source
8334 package. If unavailable this is returned as an empty string "".
8335 "app_summary"
8337 A short (usually one line) description of the application or
8338 package. If unavailable this is returned as an empty string "".
8339 "app_description"
8341 A longer description of the application or package. If unavailable
8342 this is returned as an empty string "".
8343 Please read "INSPECTION" for more details.
8345 This function returns a "struct guestfs_application_list *", or NULL if
8347 there was an error. The caller must call
8348 "guestfs_free_application_list" after use.
8349 (Added in 1.7.8)
8351 guestfs_inspect_list_applications2
8353 struct guestfs_application2_list *
8354 guestfs_inspect_list_applications2 (guestfs_h *g,
8355 const char *root);
8356 Return the list of applications installed in the operating system.
8358 Note: This call works differently from other parts of the inspection
8360 API. You have to call "guestfs_inspect_os", then
8361 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8362 calling this. Listing applications is a significantly more difficult
8363 operation which requires access to the full filesystem. Also note that
8364 unlike the other "guestfs_inspect_get_*" calls which are just returning
8365 data cached in the libguestfs handle, this call actually reads parts of
8366 the mounted filesystems during the call.
8367 This returns an empty list if the inspection code was not able to
8369 determine the list of applications.
8370 The application structure contains the following fields:
8372 "app2_name"
8374 The name of the application. For Red Hat-derived and Debian-
8375 derived Linux guests, this is the package name.
8376 "app2_display_name"
8378 The display name of the application, sometimes localized to the
8379 install language of the guest operating system.
8380 If unavailable this is returned as an empty string "". Callers
8382 needing to display something can use "app2_name" instead.
8383 "app2_epoch"
8385 For package managers which use epochs, this contains the epoch of
8386 the package (an integer). If unavailable, this is returned as 0.
8387 "app2_version"
8389 The version string of the application or package. If unavailable
8390 this is returned as an empty string "".
8391 "app2_release"
8393 The release string of the application or package, for package
8394 managers that use this. If unavailable this is returned as an
8395 empty string "".
8396 "app2_arch"
8398 The architecture string of the application or package, for package
8399 managers that use this. If unavailable this is returned as an
8400 empty string "".
8401 "app2_install_path"
8403 The installation path of the application (on operating systems such
8404 as Windows which use installation paths). This path is in the
8405 format used by the guest operating system, it is not a libguestfs
8406 path.
8407 If unavailable this is returned as an empty string "".
8409 "app2_trans_path"
8411 The install path translated into a libguestfs path. If unavailable
8412 this is returned as an empty string "".
8413 "app2_publisher"
8415 The name of the publisher of the application, for package managers
8416 that use this. If unavailable this is returned as an empty string
8417 "".
8418 "app2_url"
8420 The URL (eg. upstream URL) of the application. If unavailable this
8421 is returned as an empty string "".
8422 "app2_source_package"
8424 For packaging systems which support this, the name of the source
8425 package. If unavailable this is returned as an empty string "".
8426 "app2_summary"
8428 A short (usually one line) description of the application or
8429 package. If unavailable this is returned as an empty string "".
8430 "app2_description"
8432 A longer description of the application or package. If unavailable
8433 this is returned as an empty string "".
8434 Please read "INSPECTION" for more details.
8436 This function returns a "struct guestfs_application2_list *", or NULL
8438 if there was an error. The caller must call
8439 "guestfs_free_application2_list" after use.
8440 (Added in 1.19.56)
8442 guestfs_inspect_os
8444 char **
8445 guestfs_inspect_os (guestfs_h *g);
8446 This function uses other libguestfs functions and certain heuristics to
8448 inspect the disk(s) (usually disks belonging to a virtual machine),
8449 looking for operating systems.
8450 The list returned is empty if no operating systems were found.
8452 If one operating system was found, then this returns a list with a
8454 single element, which is the name of the root filesystem of this
8455 operating system. It is also possible for this function to return a
8456 list containing more than one element, indicating a dual-boot or multi-
8457 boot virtual machine, with each element being the root filesystem of
8458 one of the operating systems.
8459 You can pass the root string(s) returned to other
8461 "guestfs_inspect_get_*" functions in order to query further information
8462 about each operating system, such as the name and version.
8463 This function uses other libguestfs features such as "guestfs_mount_ro"
8465 and "guestfs_umount_all" in order to mount and unmount filesystems and
8466 look at the contents. This should be called with no disks currently
8467 mounted. The function may also use Augeas, so any existing Augeas
8468 handle will be closed.
8469 This function cannot decrypt encrypted disks. The caller must do that
8471 first (supplying the necessary keys) if the disk is encrypted.
8472 Please read "INSPECTION" for more details.
8474 See also "guestfs_list_filesystems".
8476 This function returns a NULL-terminated array of strings (like
8478 environ(3)), or NULL if there was an error. The caller must free the
8479 strings and the array after use.
8480 (Added in 1.5.3)
8482 guestfs_is_blockdev
8484 int
8485 guestfs_is_blockdev (guestfs_h *g,
8486 const char *path);
8487 This function is provided for backwards compatibility with earlier
8489 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8490 with no optional arguments.
8491 (Added in 1.5.10)
8493 guestfs_is_blockdev_opts
8495 int
8496 guestfs_is_blockdev_opts (guestfs_h *g,
8497 const char *path,
8498 ...);
8499 You may supply a list of optional arguments to this call. Use zero or
8501 more of the following pairs of parameters, and terminate the list with
8502 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8503 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8505 This returns "true" if and only if there is a block device with the
8507 given "path" name.
8508 If the optional flag "followsymlinks" is true, then a symlink (or chain
8510 of symlinks) that ends with a block device also causes the function to
8511 return true.
8512 This call only looks at files within the guest filesystem. Libguestfs
8514 partitions and block devices (eg. /dev/sda) cannot be used as the
8515 "path" parameter of this call.
8516 See also "guestfs_stat".
8518 This function returns a C truth value on success or -1 on error.
8520 (Added in 1.5.10)
8522 guestfs_is_blockdev_opts_va
8524 int
8525 guestfs_is_blockdev_opts_va (guestfs_h *g,
8526 const char *path,
8527 va_list args);
8528 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8530 See "CALLS WITH OPTIONAL ARGUMENTS".
8532 guestfs_is_blockdev_opts_argv
8534 int
8535 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8536 const char *path,
8537 const struct guestfs_is_blockdev_opts_argv *optargs);
8538 This is the "argv variant" of "guestfs_is_blockdev_opts".
8540 See "CALLS WITH OPTIONAL ARGUMENTS".
8542 guestfs_is_busy
8544 int
8545 guestfs_is_busy (guestfs_h *g);
8546 This always returns false. This function is deprecated with no
8548 replacement. Do not use this function.
8549 For more information on states, see guestfs(3).
8551 This function returns a C truth value on success or -1 on error.
8553 (Added in 1.0.2)
8555 guestfs_is_chardev
8557 int
8558 guestfs_is_chardev (guestfs_h *g,
8559 const char *path);
8560 This function is provided for backwards compatibility with earlier
8562 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8563 no optional arguments.
8564 (Added in 1.5.10)
8566 guestfs_is_chardev_opts
8568 int
8569 guestfs_is_chardev_opts (guestfs_h *g,
8570 const char *path,
8571 ...);
8572 You may supply a list of optional arguments to this call. Use zero or
8574 more of the following pairs of parameters, and terminate the list with
8575 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8576 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8578 This returns "true" if and only if there is a character device with the
8580 given "path" name.
8581 If the optional flag "followsymlinks" is true, then a symlink (or chain
8583 of symlinks) that ends with a chardev also causes the function to
8584 return true.
8585 See also "guestfs_stat".
8587 This function returns a C truth value on success or -1 on error.
8589 (Added in 1.5.10)
8591 guestfs_is_chardev_opts_va
8593 int
8594 guestfs_is_chardev_opts_va (guestfs_h *g,
8595 const char *path,
8596 va_list args);
8597 This is the "va_list variant" of "guestfs_is_chardev_opts".
8599 See "CALLS WITH OPTIONAL ARGUMENTS".
8601 guestfs_is_chardev_opts_argv
8603 int
8604 guestfs_is_chardev_opts_argv (guestfs_h *g,
8605 const char *path,
8606 const struct guestfs_is_chardev_opts_argv *optargs);
8607 This is the "argv variant" of "guestfs_is_chardev_opts".
8609 See "CALLS WITH OPTIONAL ARGUMENTS".
8611 guestfs_is_config
8613 int
8614 guestfs_is_config (guestfs_h *g);
8615 This returns true iff this handle is being configured (in the "CONFIG"
8617 state).
8618 For more information on states, see guestfs(3).
8620 This function returns a C truth value on success or -1 on error.
8622 (Added in 1.0.2)
8624 guestfs_is_dir
8626 int
8627 guestfs_is_dir (guestfs_h *g,
8628 const char *path);
8629 This function is provided for backwards compatibility with earlier
8631 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8632 optional arguments.
8633 (Added in 0.8)
8635 guestfs_is_dir_opts
8637 int
8638 guestfs_is_dir_opts (guestfs_h *g,
8639 const char *path,
8640 ...);
8641 You may supply a list of optional arguments to this call. Use zero or
8643 more of the following pairs of parameters, and terminate the list with
8644 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8645 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8647 This returns "true" if and only if there is a directory with the given
8649 "path" name. Note that it returns false for other objects like files.
8650 If the optional flag "followsymlinks" is true, then a symlink (or chain
8652 of symlinks) that ends with a directory also causes the function to
8653 return true.
8654 See also "guestfs_stat".
8656 This function returns a C truth value on success or -1 on error.
8658 (Added in 0.8)
8660 guestfs_is_dir_opts_va
8662 int
8663 guestfs_is_dir_opts_va (guestfs_h *g,
8664 const char *path,
8665 va_list args);
8666 This is the "va_list variant" of "guestfs_is_dir_opts".
8668 See "CALLS WITH OPTIONAL ARGUMENTS".
8670 guestfs_is_dir_opts_argv
8672 int
8673 guestfs_is_dir_opts_argv (guestfs_h *g,
8674 const char *path,
8675 const struct guestfs_is_dir_opts_argv *optargs);
8676 This is the "argv variant" of "guestfs_is_dir_opts".
8678 See "CALLS WITH OPTIONAL ARGUMENTS".
8680 guestfs_is_fifo
8682 int
8683 guestfs_is_fifo (guestfs_h *g,
8684 const char *path);
8685 This function is provided for backwards compatibility with earlier
8687 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8688 optional arguments.
8689 (Added in 1.5.10)
8691 guestfs_is_fifo_opts
8693 int
8694 guestfs_is_fifo_opts (guestfs_h *g,
8695 const char *path,
8696 ...);
8697 You may supply a list of optional arguments to this call. Use zero or
8699 more of the following pairs of parameters, and terminate the list with
8700 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8701 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8703 This returns "true" if and only if there is a FIFO (named pipe) with
8705 the given "path" name.
8706 If the optional flag "followsymlinks" is true, then a symlink (or chain
8708 of symlinks) that ends with a FIFO also causes the function to return
8709 true.
8710 See also "guestfs_stat".
8712 This function returns a C truth value on success or -1 on error.
8714 (Added in 1.5.10)
8716 guestfs_is_fifo_opts_va
8718 int
8719 guestfs_is_fifo_opts_va (guestfs_h *g,
8720 const char *path,
8721 va_list args);
8722 This is the "va_list variant" of "guestfs_is_fifo_opts".
8724 See "CALLS WITH OPTIONAL ARGUMENTS".
8726 guestfs_is_fifo_opts_argv
8728 int
8729 guestfs_is_fifo_opts_argv (guestfs_h *g,
8730 const char *path,
8731 const struct guestfs_is_fifo_opts_argv *optargs);
8732 This is the "argv variant" of "guestfs_is_fifo_opts".
8734 See "CALLS WITH OPTIONAL ARGUMENTS".
8736 guestfs_is_file
8738 int
8739 guestfs_is_file (guestfs_h *g,
8740 const char *path);
8741 This function is provided for backwards compatibility with earlier
8743 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
8744 optional arguments.
8745 (Added in 0.8)
8747 guestfs_is_file_opts
8749 int
8750 guestfs_is_file_opts (guestfs_h *g,
8751 const char *path,
8752 ...);
8753 You may supply a list of optional arguments to this call. Use zero or
8755 more of the following pairs of parameters, and terminate the list with
8756 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8757 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8759 This returns "true" if and only if there is a regular file with the
8761 given "path" name. Note that it returns false for other objects like
8762 directories.
8763 If the optional flag "followsymlinks" is true, then a symlink (or chain
8765 of symlinks) that ends with a file also causes the function to return
8766 true.
8767 See also "guestfs_stat".
8769 This function returns a C truth value on success or -1 on error.
8771 (Added in 0.8)
8773 guestfs_is_file_opts_va
8775 int
8776 guestfs_is_file_opts_va (guestfs_h *g,
8777 const char *path,
8778 va_list args);
8779 This is the "va_list variant" of "guestfs_is_file_opts".
8781 See "CALLS WITH OPTIONAL ARGUMENTS".
8783 guestfs_is_file_opts_argv
8785 int
8786 guestfs_is_file_opts_argv (guestfs_h *g,
8787 const char *path,
8788 const struct guestfs_is_file_opts_argv *optargs);
8789 This is the "argv variant" of "guestfs_is_file_opts".
8791 See "CALLS WITH OPTIONAL ARGUMENTS".
8793 guestfs_is_launching
8795 int
8796 guestfs_is_launching (guestfs_h *g);
8797 This returns true iff this handle is launching the subprocess (in the
8799 "LAUNCHING" state).
8800 For more information on states, see guestfs(3).
8802 This function returns a C truth value on success or -1 on error.
8804 (Added in 1.0.2)
8806 guestfs_is_lv
8808 int
8809 guestfs_is_lv (guestfs_h *g,
8810 const char *mountable);
8811 This command tests whether "mountable" is a logical volume, and returns
8813 true iff this is the case.
8814 This function returns a C truth value on success or -1 on error.
8816 (Added in 1.5.3)
8818 guestfs_is_ready
8820 int
8821 guestfs_is_ready (guestfs_h *g);
8822 This returns true iff this handle is ready to accept commands (in the
8824 "READY" state).
8825 For more information on states, see guestfs(3).
8827 This function returns a C truth value on success or -1 on error.
8829 (Added in 1.0.2)
8831 guestfs_is_socket
8833 int
8834 guestfs_is_socket (guestfs_h *g,
8835 const char *path);
8836 This function is provided for backwards compatibility with earlier
8838 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
8839 no optional arguments.
8840 (Added in 1.5.10)
8842 guestfs_is_socket_opts
8844 int
8845 guestfs_is_socket_opts (guestfs_h *g,
8846 const char *path,
8847 ...);
8848 You may supply a list of optional arguments to this call. Use zero or
8850 more of the following pairs of parameters, and terminate the list with
8851 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8852 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8854 This returns "true" if and only if there is a Unix domain socket with
8856 the given "path" name.
8857 If the optional flag "followsymlinks" is true, then a symlink (or chain
8859 of symlinks) that ends with a socket also causes the function to return
8860 true.
8861 See also "guestfs_stat".
8863 This function returns a C truth value on success or -1 on error.
8865 (Added in 1.5.10)
8867 guestfs_is_socket_opts_va
8869 int
8870 guestfs_is_socket_opts_va (guestfs_h *g,
8871 const char *path,
8872 va_list args);
8873 This is the "va_list variant" of "guestfs_is_socket_opts".
8875 See "CALLS WITH OPTIONAL ARGUMENTS".
8877 guestfs_is_socket_opts_argv
8879 int
8880 guestfs_is_socket_opts_argv (guestfs_h *g,
8881 const char *path,
8882 const struct guestfs_is_socket_opts_argv *optargs);
8883 This is the "argv variant" of "guestfs_is_socket_opts".
8885 See "CALLS WITH OPTIONAL ARGUMENTS".
8887 guestfs_is_symlink
8889 int
8890 guestfs_is_symlink (guestfs_h *g,
8891 const char *path);
8892 This returns "true" if and only if there is a symbolic link with the
8894 given "path" name.
8895 See also "guestfs_stat".
8897 This function returns a C truth value on success or -1 on error.
8899 (Added in 1.5.10)
8901 guestfs_is_whole_device
8903 int
8904 guestfs_is_whole_device (guestfs_h *g,
8905 const char *device);
8906 This returns "true" if and only if "device" refers to a whole block
8908 device. That is, not a partition or a logical device.
8909 This function returns a C truth value on success or -1 on error.
8911 (Added in 1.21.9)
8913 guestfs_is_zero
8915 int
8916 guestfs_is_zero (guestfs_h *g,
8917 const char *path);
8918 This returns true iff the file exists and the file is empty or it
8920 contains all zero bytes.
8921 This function returns a C truth value on success or -1 on error.
8923 (Added in 1.11.8)
8925 guestfs_is_zero_device
8927 int
8928 guestfs_is_zero_device (guestfs_h *g,
8929 const char *device);
8930 This returns true iff the device exists and contains all zero bytes.
8932 Note that for large devices this can take a long time to run.
8934 This function returns a C truth value on success or -1 on error.
8936 (Added in 1.11.8)
8938 guestfs_isoinfo
8940 struct guestfs_isoinfo *
8941 guestfs_isoinfo (guestfs_h *g,
8942 const char *isofile);
8943 This is the same as "guestfs_isoinfo_device" except that it works for
8945 an ISO file located inside some other mounted filesystem. Note that in
8946 the common case where you have added an ISO file as a libguestfs
8947 device, you would not call this. Instead you would call
8948 "guestfs_isoinfo_device".
8949 This function returns a "struct guestfs_isoinfo *", or NULL if there
8951 was an error. The caller must call "guestfs_free_isoinfo" after use.
8952 (Added in 1.17.19)
8954 guestfs_isoinfo_device
8956 struct guestfs_isoinfo *
8957 guestfs_isoinfo_device (guestfs_h *g,
8958 const char *device);
8959 "device" is an ISO device. This returns a struct of information read
8961 from the primary volume descriptor (the ISO equivalent of the
8962 superblock) of the device.
8963 Usually it is more efficient to use the isoinfo(1) command with the -d
8965 option on the host to analyze ISO files, instead of going through
8966 libguestfs.
8967 For information on the primary volume descriptor fields, see
8969 http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
8970 This function returns a "struct guestfs_isoinfo *", or NULL if there
8972 was an error. The caller must call "guestfs_free_isoinfo" after use.
8973 (Added in 1.17.19)
8975 guestfs_journal_close
8977 int
8978 guestfs_journal_close (guestfs_h *g);
8979 Close the journal handle.
8981 This function returns 0 on success or -1 on error.
8983 This function depends on the feature "journal". See also
8985 "guestfs_feature_available".
8986 (Added in 1.23.11)
8988 guestfs_journal_get
8990 struct guestfs_xattr_list *
8991 guestfs_journal_get (guestfs_h *g);
8992 Read the current journal entry. This returns all the fields in the
8994 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
8995 field name (a string).
8996 The "attrval" is the field value (a binary blob, often but not always a
8998 string). Please note that "attrval" is a byte array, not a
8999 \0-terminated C string.
9000 The length of data may be truncated to the data threshold (see:
9002 "guestfs_journal_set_data_threshold",
9003 "guestfs_journal_get_data_threshold").
9004 If you set the data threshold to unlimited (0) then this call can read
9006 a journal entry of any size, ie. it is not limited by the libguestfs
9007 protocol.
9008 This function returns a "struct guestfs_xattr_list *", or NULL if there
9010 was an error. The caller must call "guestfs_free_xattr_list" after
9011 use.
9012 This function depends on the feature "journal". See also
9014 "guestfs_feature_available".
9015 (Added in 1.23.11)
9017 guestfs_journal_get_data_threshold
9019 int64_t
9020 guestfs_journal_get_data_threshold (guestfs_h *g);
9021 Get the current data threshold for reading journal entries. This is a
9023 hint to the journal that it may truncate data fields to this size when
9024 reading them (note also that it may not truncate them). If this
9025 returns 0, then the threshold is unlimited.
9026 See also "guestfs_journal_set_data_threshold".
9028 On error this function returns -1.
9030 This function depends on the feature "journal". See also
9032 "guestfs_feature_available".
9033 (Added in 1.23.11)
9035 guestfs_journal_get_realtime_usec
9037 int64_t
9038 guestfs_journal_get_realtime_usec (guestfs_h *g);
9039 Get the realtime (wallclock) timestamp of the current journal entry.
9041 On error this function returns -1.
9043 This function depends on the feature "journal". See also
9045 "guestfs_feature_available".
9046 (Added in 1.27.18)
9048 guestfs_journal_next
9050 int
9051 guestfs_journal_next (guestfs_h *g);
9052 Move to the next journal entry. You have to call this at least once
9054 after opening the handle before you are able to read data.
9055 The returned boolean tells you if there are any more journal records to
9057 read. "true" means you can read the next record (eg. using
9058 "guestfs_journal_get"), and "false" means you have reached the end of
9059 the journal.
9060 This function returns a C truth value on success or -1 on error.
9062 This function depends on the feature "journal". See also
9064 "guestfs_feature_available".
9065 (Added in 1.23.11)
9067 guestfs_journal_open
9069 int
9070 guestfs_journal_open (guestfs_h *g,
9071 const char *directory);
9072 Open the systemd journal located in directory. Any previously opened
9074 journal handle is closed.
9075 The contents of the journal can be read using "guestfs_journal_next"
9077 and "guestfs_journal_get".
9078 After you have finished using the journal, you should close the handle
9080 by calling "guestfs_journal_close".
9081 This function returns 0 on success or -1 on error.
9083 This function depends on the feature "journal". See also
9085 "guestfs_feature_available".
9086 (Added in 1.23.11)
9088 guestfs_journal_set_data_threshold
9090 int
9091 guestfs_journal_set_data_threshold (guestfs_h *g,
9092 int64_t threshold);
9093 Set the data threshold for reading journal entries. This is a hint to
9095 the journal that it may truncate data fields to this size when reading
9096 them (note also that it may not truncate them). If you set this to 0,
9097 then the threshold is unlimited.
9098 See also "guestfs_journal_get_data_threshold".
9100 This function returns 0 on success or -1 on error.
9102 This function depends on the feature "journal". See also
9104 "guestfs_feature_available".
9105 (Added in 1.23.11)
9107 guestfs_journal_skip
9109 int64_t
9110 guestfs_journal_skip (guestfs_h *g,
9111 int64_t skip);
9112 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9114 The number of entries actually skipped is returned (note "rskip ≥ 0").
9116 If this is not the same as the absolute value of the skip parameter
9117 ("|skip|") you passed in then it means you have reached the end or the
9118 start of the journal.
9119 On error this function returns -1.
9121 This function depends on the feature "journal". See also
9123 "guestfs_feature_available".
9124 (Added in 1.23.11)
9126 guestfs_kill_subprocess
9128 int
9129 guestfs_kill_subprocess (guestfs_h *g);
9130 This function is deprecated. In new code, use the "guestfs_shutdown"
9132 call instead.
9133 Deprecated functions will not be removed from the API, but the fact
9135 that they are deprecated indicates that there are problems with correct
9136 use of these functions.
9137 This kills the hypervisor.
9139 Do not call this. See: "guestfs_shutdown" instead.
9141 This function returns 0 on success or -1 on error.
9143 (Added in 0.3)
9145 guestfs_launch
9147 int
9148 guestfs_launch (guestfs_h *g);
9149 You should call this after configuring the handle (eg. adding drives)
9151 but before performing any actions.
9152 Do not call "guestfs_launch" twice on the same handle. Although it
9154 will not give an error (for historical reasons), the precise behaviour
9155 when you do this is not well defined. Handles are very cheap to
9156 create, so create a new one for each launch.
9157 This function returns 0 on success or -1 on error.
9159 This long-running command can generate progress notification messages
9161 so that the caller can display a progress bar or indicator. To receive
9162 these messages, the caller must register a progress event callback.
9163 See "GUESTFS_EVENT_PROGRESS".
9164 (Added in 0.3)
9166 guestfs_lchown
9168 int
9169 guestfs_lchown (guestfs_h *g,
9170 int owner,
9171 int group,
9172 const char *path);
9173 Change the file owner to "owner" and group to "group". This is like
9175 "guestfs_chown" but if "path" is a symlink then the link itself is
9176 changed, not the target.
9177 Only numeric uid and gid are supported. If you want to use names, you
9179 will need to locate and parse the password file yourself (Augeas
9180 support makes this relatively easy).
9181 This function returns 0 on success or -1 on error.
9183 (Added in 1.0.77)
9185 guestfs_ldmtool_create_all
9187 int
9188 guestfs_ldmtool_create_all (guestfs_h *g);
9189 This function scans all block devices looking for Windows dynamic disk
9191 volumes and partitions, and creates devices for any that were found.
9192 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9194 return all devices.
9195 Note that you don't normally need to call this explicitly, since it is
9197 done automatically at "guestfs_launch" time. However you might want to
9198 call this function if you have hotplugged disks or have just created a
9199 Windows dynamic disk.
9200 This function returns 0 on success or -1 on error.
9202 This function depends on the feature "ldm". See also
9204 "guestfs_feature_available".
9205 (Added in 1.20.0)
9207 guestfs_ldmtool_diskgroup_disks
9209 char **
9210 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9211 const char *diskgroup);
9212 Return the disks in a Windows dynamic disk group. The "diskgroup"
9214 parameter should be the GUID of a disk group, one element from the list
9215 returned by "guestfs_ldmtool_scan".
9216 This function returns a NULL-terminated array of strings (like
9218 environ(3)), or NULL if there was an error. The caller must free the
9219 strings and the array after use.
9220 This function depends on the feature "ldm". See also
9222 "guestfs_feature_available".
9223 (Added in 1.20.0)
9225 guestfs_ldmtool_diskgroup_name
9227 char *
9228 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9229 const char *diskgroup);
9230 Return the name of a Windows dynamic disk group. The "diskgroup"
9232 parameter should be the GUID of a disk group, one element from the list
9233 returned by "guestfs_ldmtool_scan".
9234 This function returns a string, or NULL on error. The caller must free
9236 the returned string after use.
9237 This function depends on the feature "ldm". See also
9239 "guestfs_feature_available".
9240 (Added in 1.20.0)
9242 guestfs_ldmtool_diskgroup_volumes
9244 char **
9245 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9246 const char *diskgroup);
9247 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9249 parameter should be the GUID of a disk group, one element from the list
9250 returned by "guestfs_ldmtool_scan".
9251 This function returns a NULL-terminated array of strings (like
9253 environ(3)), or NULL if there was an error. The caller must free the
9254 strings and the array after use.
9255 This function depends on the feature "ldm". See also
9257 "guestfs_feature_available".
9258 (Added in 1.20.0)
9260 guestfs_ldmtool_remove_all
9262 int
9263 guestfs_ldmtool_remove_all (guestfs_h *g);
9264 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9266 removes the device mapper mappings for all Windows dynamic disk volumes
9267 This function returns 0 on success or -1 on error.
9269 This function depends on the feature "ldm". See also
9271 "guestfs_feature_available".
9272 (Added in 1.20.0)
9274 guestfs_ldmtool_scan
9276 char **
9277 guestfs_ldmtool_scan (guestfs_h *g);
9278 This function scans for Windows dynamic disks. It returns a list of
9280 identifiers (GUIDs) for all disk groups that were found. These
9281 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9282 This function scans all block devices. To scan a subset of block
9284 devices, call "guestfs_ldmtool_scan_devices" instead.
9285 This function returns a NULL-terminated array of strings (like
9287 environ(3)), or NULL if there was an error. The caller must free the
9288 strings and the array after use.
9289 This function depends on the feature "ldm". See also
9291 "guestfs_feature_available".
9292 (Added in 1.20.0)
9294 guestfs_ldmtool_scan_devices
9296 char **
9297 guestfs_ldmtool_scan_devices (guestfs_h *g,
9298 char *const *devices);
9299 This function scans for Windows dynamic disks. It returns a list of
9301 identifiers (GUIDs) for all disk groups that were found. These
9302 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9303 The parameter "devices" is a list of block devices which are scanned.
9305 If this list is empty, all block devices are scanned.
9306 This function returns a NULL-terminated array of strings (like
9308 environ(3)), or NULL if there was an error. The caller must free the
9309 strings and the array after use.
9310 This function depends on the feature "ldm". See also
9312 "guestfs_feature_available".
9313 (Added in 1.20.0)
9315 guestfs_ldmtool_volume_hint
9317 char *
9318 guestfs_ldmtool_volume_hint (guestfs_h *g,
9319 const char *diskgroup,
9320 const char *volume);
9321 Return the hint field of the volume named "volume" in the disk group
9323 with GUID "diskgroup". This may not be defined, in which case the
9324 empty string is returned. The hint field is often, though not always,
9325 the name of a Windows drive, eg. "E:".
9326 This function returns a string, or NULL on error. The caller must free
9328 the returned string after use.
9329 This function depends on the feature "ldm". See also
9331 "guestfs_feature_available".
9332 (Added in 1.20.0)
9334 guestfs_ldmtool_volume_partitions
9336 char **
9337 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9338 const char *diskgroup,
9339 const char *volume);
9340 Return the list of partitions in the volume named "volume" in the disk
9342 group with GUID "diskgroup".
9343 This function returns a NULL-terminated array of strings (like
9345 environ(3)), or NULL if there was an error. The caller must free the
9346 strings and the array after use.
9347 This function depends on the feature "ldm". See also
9349 "guestfs_feature_available".
9350 (Added in 1.20.0)
9352 guestfs_ldmtool_volume_type
9354 char *
9355 guestfs_ldmtool_volume_type (guestfs_h *g,
9356 const char *diskgroup,
9357 const char *volume);
9358 Return the type of the volume named "volume" in the disk group with
9360 GUID "diskgroup".
9361 Possible volume types that can be returned here include: "simple",
9363 "spanned", "striped", "mirrored", "raid5". Other types may also be
9364 returned.
9365 This function returns a string, or NULL on error. The caller must free
9367 the returned string after use.
9368 This function depends on the feature "ldm". See also
9370 "guestfs_feature_available".
9371 (Added in 1.20.0)
9373 guestfs_lgetxattr
9375 char *
9376 guestfs_lgetxattr (guestfs_h *g,
9377 const char *path,
9378 const char *name,
9379 size_t *size_r);
9380 Get a single extended attribute from file "path" named "name". If
9382 "path" is a symlink, then this call returns an extended attribute from
9383 the symlink.
9384 Normally it is better to get all extended attributes from a file in one
9386 go by calling "guestfs_getxattrs". However some Linux filesystem
9387 implementations are buggy and do not provide a way to list out
9388 attributes. For these filesystems (notably ntfs-3g) you have to know
9389 the names of the extended attributes you want in advance and call this
9390 function.
9391 Extended attribute values are blobs of binary data. If there is no
9393 extended attribute named "name", this returns an error.
9394 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9396 This function returns a buffer, or NULL on error. The size of the
9398 returned buffer is written to *size_r. The caller must free the
9399 returned buffer after use.
9400 This function depends on the feature "linuxxattrs". See also
9402 "guestfs_feature_available".
9403 (Added in 1.7.24)
9405 guestfs_lgetxattrs
9407 struct guestfs_xattr_list *
9408 guestfs_lgetxattrs (guestfs_h *g,
9409 const char *path);
9410 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9412 link, then it returns the extended attributes of the link itself.
9413 This function returns a "struct guestfs_xattr_list *", or NULL if there
9415 was an error. The caller must call "guestfs_free_xattr_list" after
9416 use.
9417 This function depends on the feature "linuxxattrs". See also
9419 "guestfs_feature_available".
9420 (Added in 1.0.59)
9422 guestfs_list_devices
9424 char **
9425 guestfs_list_devices (guestfs_h *g);
9426 List all the block devices.
9428 The full block device names are returned, eg. /dev/sda.
9430 See also "guestfs_list_filesystems".
9432 This function returns a NULL-terminated array of strings (like
9434 environ(3)), or NULL if there was an error. The caller must free the
9435 strings and the array after use.
9436 (Added in 0.4)
9438 guestfs_list_disk_labels
9440 char **
9441 guestfs_list_disk_labels (guestfs_h *g);
9442 If you add drives using the optional "label" parameter of
9444 "guestfs_add_drive_opts", you can use this call to map between disk
9445 labels, and raw block device and partition names (like /dev/sda and
9446 /dev/sda1).
9447 This returns a hashtable, where keys are the disk labels (without the
9449 /dev/disk/guestfs prefix), and the values are the full raw block device
9450 and partition names (eg. /dev/sda and /dev/sda1).
9451 This function returns a NULL-terminated array of strings, or NULL if
9453 there was an error. The array of strings will always have length
9454 "2n+1", where "n" keys and values alternate, followed by the trailing
9455 NULL entry. The caller must free the strings and the array after use.
9456 (Added in 1.19.49)
9458 guestfs_list_dm_devices
9460 char **
9461 guestfs_list_dm_devices (guestfs_h *g);
9462 List all device mapper devices.
9464 The returned list contains /dev/mapper/* devices, eg. ones created by a
9466 previous call to "guestfs_luks_open".
9467 Device mapper devices which correspond to logical volumes are not
9469 returned in this list. Call "guestfs_lvs" if you want to list logical
9470 volumes.
9471 This function returns a NULL-terminated array of strings (like
9473 environ(3)), or NULL if there was an error. The caller must free the
9474 strings and the array after use.
9475 (Added in 1.11.15)
9477 guestfs_list_filesystems
9479 char **
9480 guestfs_list_filesystems (guestfs_h *g);
9481 This inspection command looks for filesystems on partitions, block
9483 devices and logical volumes, returning a list of "mountables"
9484 containing filesystems and their type.
9485 The return value is a hash, where the keys are the devices containing
9487 filesystems, and the values are the filesystem types. For example:
9488 "/dev/sda1" => "ntfs"
9490 "/dev/sda2" => "ext2"
9491 "/dev/vg_guest/lv_root" => "ext4"
9492 "/dev/vg_guest/lv_swap" => "swap"
9493 The key is not necessarily a block device. It may also be an opaque
9495 ‘mountable’ string which can be passed to "guestfs_mount".
9496 The value can have the special value "unknown", meaning the content of
9498 the device is undetermined or empty. "swap" means a Linux swap
9499 partition.
9500 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9502 might have included "guestfs_mount" and "guestfs_umount", and therefore
9503 you had to use this soon after launch and only when nothing else was
9504 mounted. This restriction is removed in libguestfs ≥ 1.38.
9505 Not all of the filesystems returned will be mountable. In particular,
9507 swap partitions are returned in the list. Also this command does not
9508 check that each filesystem found is valid and mountable, and some
9509 filesystems might be mountable but require special options.
9510 Filesystems may not all belong to a single logical operating system
9511 (use "guestfs_inspect_os" to look for OSes).
9512 This function returns a NULL-terminated array of strings, or NULL if
9514 there was an error. The array of strings will always have length
9515 "2n+1", where "n" keys and values alternate, followed by the trailing
9516 NULL entry. The caller must free the strings and the array after use.
9517 (Added in 1.5.15)
9519 guestfs_list_ldm_partitions
9521 char **
9522 guestfs_list_ldm_partitions (guestfs_h *g);
9523 This function returns all Windows dynamic disk partitions that were
9525 found at launch time. It returns a list of device names.
9526 This function returns a NULL-terminated array of strings (like
9528 environ(3)), or NULL if there was an error. The caller must free the
9529 strings and the array after use.
9530 This function depends on the feature "ldm". See also
9532 "guestfs_feature_available".
9533 (Added in 1.20.0)
9535 guestfs_list_ldm_volumes
9537 char **
9538 guestfs_list_ldm_volumes (guestfs_h *g);
9539 This function returns all Windows dynamic disk volumes that were found
9541 at launch time. It returns a list of device names.
9542 This function returns a NULL-terminated array of strings (like
9544 environ(3)), or NULL if there was an error. The caller must free the
9545 strings and the array after use.
9546 This function depends on the feature "ldm". See also
9548 "guestfs_feature_available".
9549 (Added in 1.20.0)
9551 guestfs_list_md_devices
9553 char **
9554 guestfs_list_md_devices (guestfs_h *g);
9555 List all Linux md devices.
9557 This function returns a NULL-terminated array of strings (like
9559 environ(3)), or NULL if there was an error. The caller must free the
9560 strings and the array after use.
9561 (Added in 1.15.4)
9563 guestfs_list_partitions
9565 char **
9566 guestfs_list_partitions (guestfs_h *g);
9567 List all the partitions detected on all block devices.
9569 The full partition device names are returned, eg. /dev/sda1
9571 This does not return logical volumes. For that you will need to call
9573 "guestfs_lvs".
9574 See also "guestfs_list_filesystems".
9576 This function returns a NULL-terminated array of strings (like
9578 environ(3)), or NULL if there was an error. The caller must free the
9579 strings and the array after use.
9580 (Added in 0.4)
9582 guestfs_ll
9584 char *
9585 guestfs_ll (guestfs_h *g,
9586 const char *directory);
9587 List the files in directory (relative to the root directory, there is
9589 no cwd) in the format of 'ls -la'.
9590 This command is mostly useful for interactive sessions. It is not
9592 intended that you try to parse the output string.
9593 This function returns a string, or NULL on error. The caller must free
9595 the returned string after use.
9596 (Added in 0.4)
9598 guestfs_llz
9600 char *
9601 guestfs_llz (guestfs_h *g,
9602 const char *directory);
9603 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9605 call instead.
9606 Deprecated functions will not be removed from the API, but the fact
9608 that they are deprecated indicates that there are problems with correct
9609 use of these functions.
9610 List the files in directory in the format of 'ls -laZ'.
9612 This command is mostly useful for interactive sessions. It is not
9614 intended that you try to parse the output string.
9615 This function returns a string, or NULL on error. The caller must free
9617 the returned string after use.
9618 (Added in 1.17.6)
9620 guestfs_ln
9622 int
9623 guestfs_ln (guestfs_h *g,
9624 const char *target,
9625 const char *linkname);
9626 This command creates a hard link using the "ln" command.
9628 This function returns 0 on success or -1 on error.
9630 (Added in 1.0.66)
9632 guestfs_ln_f
9634 int
9635 guestfs_ln_f (guestfs_h *g,
9636 const char *target,
9637 const char *linkname);
9638 This command creates a hard link using the "ln -f" command. The -f
9640 option removes the link ("linkname") if it exists already.
9641 This function returns 0 on success or -1 on error.
9643 (Added in 1.0.66)
9645 guestfs_ln_s
9647 int
9648 guestfs_ln_s (guestfs_h *g,
9649 const char *target,
9650 const char *linkname);
9651 This command creates a symbolic link using the "ln -s" command.
9653 This function returns 0 on success or -1 on error.
9655 (Added in 1.0.66)
9657 guestfs_ln_sf
9659 int
9660 guestfs_ln_sf (guestfs_h *g,
9661 const char *target,
9662 const char *linkname);
9663 This command creates a symbolic link using the "ln -sf" command, The -f
9665 option removes the link ("linkname") if it exists already.
9666 This function returns 0 on success or -1 on error.
9668 (Added in 1.0.66)
9670 guestfs_lremovexattr
9672 int
9673 guestfs_lremovexattr (guestfs_h *g,
9674 const char *xattr,
9675 const char *path);
9676 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9678 link, then it removes an extended attribute of the link itself.
9679 This function returns 0 on success or -1 on error.
9681 This function depends on the feature "linuxxattrs". See also
9683 "guestfs_feature_available".
9684 (Added in 1.0.59)
9686 guestfs_ls
9688 char **
9689 guestfs_ls (guestfs_h *g,
9690 const char *directory);
9691 List the files in directory (relative to the root directory, there is
9693 no cwd). The '.' and '..' entries are not returned, but hidden files
9694 are shown.
9695 This function returns a NULL-terminated array of strings (like
9697 environ(3)), or NULL if there was an error. The caller must free the
9698 strings and the array after use.
9699 (Added in 0.4)
9701 guestfs_ls0
9703 int
9704 guestfs_ls0 (guestfs_h *g,
9705 const char *dir,
9706 const char *filenames);
9707 This specialized command is used to get a listing of the filenames in
9709 the directory "dir". The list of filenames is written to the local
9710 file filenames (on the host).
9711 In the output file, the filenames are separated by "\0" characters.
9713 "." and ".." are not returned. The filenames are not sorted.
9715 This function returns 0 on success or -1 on error.
9717 (Added in 1.19.32)
9719 guestfs_lsetxattr
9721 int
9722 guestfs_lsetxattr (guestfs_h *g,
9723 const char *xattr,
9724 const char *val,
9725 int vallen,
9726 const char *path);
9727 This is the same as "guestfs_setxattr", but if "path" is a symbolic
9729 link, then it sets an extended attribute of the link itself.
9730 This function returns 0 on success or -1 on error.
9732 This function depends on the feature "linuxxattrs". See also
9734 "guestfs_feature_available".
9735 (Added in 1.0.59)
9737 guestfs_lstat
9739 struct guestfs_stat *
9740 guestfs_lstat (guestfs_h *g,
9741 const char *path);
9742 This function is deprecated. In new code, use the "guestfs_lstatns"
9744 call instead.
9745 Deprecated functions will not be removed from the API, but the fact
9747 that they are deprecated indicates that there are problems with correct
9748 use of these functions.
9749 Returns file information for the given "path".
9751 This is the same as "guestfs_stat" except that if "path" is a symbolic
9753 link, then the link is stat-ed, not the file it refers to.
9754 This is the same as the lstat(2) system call.
9756 This function returns a "struct guestfs_stat *", or NULL if there was
9758 an error. The caller must call "guestfs_free_stat" after use.
9759 (Added in 1.9.2)
9761 guestfs_lstatlist
9763 struct guestfs_stat_list *
9764 guestfs_lstatlist (guestfs_h *g,
9765 const char *path,
9766 char *const *names);
9767 This function is deprecated. In new code, use the
9769 "guestfs_lstatnslist" call instead.
9770 Deprecated functions will not be removed from the API, but the fact
9772 that they are deprecated indicates that there are problems with correct
9773 use of these functions.
9774 This call allows you to perform the "guestfs_lstat" operation on
9776 multiple files, where all files are in the directory "path". "names"
9777 is the list of files from this directory.
9778 On return you get a list of stat structs, with a one-to-one
9780 correspondence to the "names" list. If any name did not exist or could
9781 not be lstat'd, then the "st_ino" field of that structure is set to
9782 "-1".
9783 This call is intended for programs that want to efficiently list a
9785 directory contents without making many round-trips. See also
9786 "guestfs_lxattrlist" for a similarly efficient call for getting
9787 extended attributes.
9788 This function returns a "struct guestfs_stat_list *", or NULL if there
9790 was an error. The caller must call "guestfs_free_stat_list" after use.
9791 (Added in 1.0.77)
9793 guestfs_lstatns
9795 struct guestfs_statns *
9796 guestfs_lstatns (guestfs_h *g,
9797 const char *path);
9798 Returns file information for the given "path".
9800 This is the same as "guestfs_statns" except that if "path" is a
9802 symbolic link, then the link is stat-ed, not the file it refers to.
9803 This is the same as the lstat(2) system call.
9805 This function returns a "struct guestfs_statns *", or NULL if there was
9807 an error. The caller must call "guestfs_free_statns" after use.
9808 (Added in 1.27.53)
9810 guestfs_lstatnslist
9812 struct guestfs_statns_list *
9813 guestfs_lstatnslist (guestfs_h *g,
9814 const char *path,
9815 char *const *names);
9816 This call allows you to perform the "guestfs_lstatns" operation on
9818 multiple files, where all files are in the directory "path". "names"
9819 is the list of files from this directory.
9820 On return you get a list of stat structs, with a one-to-one
9822 correspondence to the "names" list. If any name did not exist or could
9823 not be lstat'd, then the "st_ino" field of that structure is set to
9824 "-1".
9825 This call is intended for programs that want to efficiently list a
9827 directory contents without making many round-trips. See also
9828 "guestfs_lxattrlist" for a similarly efficient call for getting
9829 extended attributes.
9830 This function returns a "struct guestfs_statns_list *", or NULL if
9832 there was an error. The caller must call "guestfs_free_statns_list"
9833 after use.
9834 (Added in 1.27.53)
9836 guestfs_luks_add_key
9838 int
9839 guestfs_luks_add_key (guestfs_h *g,
9840 const char *device,
9841 const char *key,
9842 const char *newkey,
9843 int keyslot);
9844 This command adds a new key on LUKS device "device". "key" is any
9846 existing key, and is used to access the device. "newkey" is the new
9847 key to add. "keyslot" is the key slot that will be replaced.
9848 Note that if "keyslot" already contains a key, then this command will
9850 fail. You have to use "guestfs_luks_kill_slot" first to remove that
9851 key.
9852 This function returns 0 on success or -1 on error.
9854 This function takes a key or passphrase parameter which could contain
9856 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
9857 information.
9858 This function depends on the feature "luks". See also
9860 "guestfs_feature_available".
9861 (Added in 1.5.2)
9863 guestfs_luks_close
9865 int
9866 guestfs_luks_close (guestfs_h *g,
9867 const char *device);
9868 This closes a LUKS device that was created earlier by
9870 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
9871 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
9872 and not the name of the underlying block device.
9873 This function returns 0 on success or -1 on error.
9875 This function depends on the feature "luks". See also
9877 "guestfs_feature_available".
9878 (Added in 1.5.1)
9880 guestfs_luks_format
9882 int
9883 guestfs_luks_format (guestfs_h *g,
9884 const char *device,
9885 const char *key,
9886 int keyslot);
9887 This command erases existing data on "device" and formats the device as
9889 a LUKS encrypted device. "key" is the initial key, which is added to
9890 key slot "slot". (LUKS supports 8 key slots, numbered 0-7).
9891 This function returns 0 on success or -1 on error.
9893 This function takes a key or passphrase parameter which could contain
9895 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
9896 information.
9897 This function depends on the feature "luks". See also
9899 "guestfs_feature_available".
9900 (Added in 1.5.2)
9902 guestfs_luks_format_cipher
9904 int
9905 guestfs_luks_format_cipher (guestfs_h *g,
9906 const char *device,
9907 const char *key,
9908 int keyslot,
9909 const char *cipher);
9910 This command is the same as "guestfs_luks_format" but it also allows
9912 you to set the "cipher" used.
9913 This function returns 0 on success or -1 on error.
9915 This function takes a key or passphrase parameter which could contain
9917 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
9918 information.
9919 This function depends on the feature "luks". See also
9921 "guestfs_feature_available".
9922 (Added in 1.5.2)
9924 guestfs_luks_kill_slot
9926 int
9927 guestfs_luks_kill_slot (guestfs_h *g,
9928 const char *device,
9929 const char *key,
9930 int keyslot);
9931 This command deletes the key in key slot "keyslot" from the encrypted
9933 LUKS device "device". "key" must be one of the other keys.
9934 This function returns 0 on success or -1 on error.
9936 This function takes a key or passphrase parameter which could contain
9938 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
9939 information.
9940 This function depends on the feature "luks". See also
9942 "guestfs_feature_available".
9943 (Added in 1.5.2)
9945 guestfs_luks_open
9947 int
9948 guestfs_luks_open (guestfs_h *g,
9949 const char *device,
9950 const char *key,
9951 const char *mapname);
9952 This command opens a block device which has been encrypted according to
9954 the Linux Unified Key Setup (LUKS) standard.
9955 "device" is the encrypted block device or partition.
9957 The caller must supply one of the keys associated with the LUKS block
9959 device, in the "key" parameter.
9960 This creates a new block device called /dev/mapper/mapname. Reads and
9962 writes to this block device are decrypted from and encrypted to the
9963 underlying "device" respectively.
9964 If this block device contains LVM volume groups, then calling
9966 "guestfs_vgscan" followed by "guestfs_vg_activate_all" will make them
9967 visible.
9968 Use "guestfs_list_dm_devices" to list all device mapper devices.
9970 This function returns 0 on success or -1 on error.
9972 This function takes a key or passphrase parameter which could contain
9974 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
9975 information.
9976 This function depends on the feature "luks". See also
9978 "guestfs_feature_available".
9979 (Added in 1.5.1)
9981 guestfs_luks_open_ro
9983 int
9984 guestfs_luks_open_ro (guestfs_h *g,
9985 const char *device,
9986 const char *key,
9987 const char *mapname);
9988 This is the same as "guestfs_luks_open" except that a read-only mapping
9990 is created.
9991 This function returns 0 on success or -1 on error.
9993 This function takes a key or passphrase parameter which could contain
9995 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
9996 information.
9997 This function depends on the feature "luks". See also
9999 "guestfs_feature_available".
10000 (Added in 1.5.1)
10002 guestfs_lvcreate
10004 int
10005 guestfs_lvcreate (guestfs_h *g,
10006 const char *logvol,
10007 const char *volgroup,
10008 int mbytes);
10009 This creates an LVM logical volume called "logvol" on the volume group
10011 "volgroup", with "size" megabytes.
10012 This function returns 0 on success or -1 on error.
10014 This function depends on the feature "lvm2". See also
10016 "guestfs_feature_available".
10017 (Added in 0.8)
10019 guestfs_lvcreate_free
10021 int
10022 guestfs_lvcreate_free (guestfs_h *g,
10023 const char *logvol,
10024 const char *volgroup,
10025 int percent);
10026 Create an LVM logical volume called /dev/volgroup/logvol, using
10028 approximately "percent" % of the free space remaining in the volume
10029 group. Most usefully, when "percent" is 100 this will create the
10030 largest possible LV.
10031 This function returns 0 on success or -1 on error.
10033 This function depends on the feature "lvm2". See also
10035 "guestfs_feature_available".
10036 (Added in 1.17.18)
10038 guestfs_lvm_canonical_lv_name
10040 char *
10041 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10042 const char *lvname);
10043 This converts alternative naming schemes for LVs that you might find to
10045 the canonical name. For example, /dev/mapper/VG-LV is converted to
10046 /dev/VG/LV.
10047 This command returns an error if the "lvname" parameter does not refer
10049 to a logical volume.
10050 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10052 This function returns a string, or NULL on error. The caller must free
10054 the returned string after use.
10055 (Added in 1.5.24)
10057 guestfs_lvm_clear_filter
10059 int
10060 guestfs_lvm_clear_filter (guestfs_h *g);
10061 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10063 to see every block device.
10064 This command also clears the LVM cache and performs a volume group
10066 scan.
10067 This function returns 0 on success or -1 on error.
10069 (Added in 1.5.1)
10071 guestfs_lvm_remove_all
10073 int
10074 guestfs_lvm_remove_all (guestfs_h *g);
10075 This command removes all LVM logical volumes, volume groups and
10077 physical volumes.
10078 This function returns 0 on success or -1 on error.
10080 This function depends on the feature "lvm2". See also
10082 "guestfs_feature_available".
10083 (Added in 0.8)
10085 guestfs_lvm_set_filter
10087 int
10088 guestfs_lvm_set_filter (guestfs_h *g,
10089 char *const *devices);
10090 This sets the LVM device filter so that LVM will only be able to "see"
10092 the block devices in the list "devices", and will ignore all other
10093 attached block devices.
10094 Where disk image(s) contain duplicate PVs or VGs, this command is
10096 useful to get LVM to ignore the duplicates, otherwise LVM can get
10097 confused. Note also there are two types of duplication possible:
10098 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10099 cloned but just happen to have the same name. In normal operation you
10100 cannot create this situation, but you can do it outside LVM, eg. by
10101 cloning disk images or by bit twiddling inside the LVM metadata.
10102 This command also clears the LVM cache and performs a volume group
10104 scan.
10105 You can filter whole block devices or individual partitions.
10107 You cannot use this if any VG is currently in use (eg. contains a
10109 mounted filesystem), even if you are not filtering out that VG.
10110 This function returns 0 on success or -1 on error.
10112 This function depends on the feature "lvm2". See also
10114 "guestfs_feature_available".
10115 (Added in 1.5.1)
10117 guestfs_lvremove
10119 int
10120 guestfs_lvremove (guestfs_h *g,
10121 const char *device);
10122 Remove an LVM logical volume "device", where "device" is the path to
10124 the LV, such as /dev/VG/LV.
10125 You can also remove all LVs in a volume group by specifying the VG
10127 name, /dev/VG.
10128 This function returns 0 on success or -1 on error.
10130 This function depends on the feature "lvm2". See also
10132 "guestfs_feature_available".
10133 (Added in 1.0.13)
10135 guestfs_lvrename
10137 int
10138 guestfs_lvrename (guestfs_h *g,
10139 const char *logvol,
10140 const char *newlogvol);
10141 Rename a logical volume "logvol" with the new name "newlogvol".
10143 This function returns 0 on success or -1 on error.
10145 (Added in 1.0.83)
10147 guestfs_lvresize
10149 int
10150 guestfs_lvresize (guestfs_h *g,
10151 const char *device,
10152 int mbytes);
10153 This resizes (expands or shrinks) an existing LVM logical volume to
10155 "mbytes". When reducing, data in the reduced part is lost.
10156 This function returns 0 on success or -1 on error.
10158 This function depends on the feature "lvm2". See also
10160 "guestfs_feature_available".
10161 (Added in 1.0.27)
10163 guestfs_lvresize_free
10165 int
10166 guestfs_lvresize_free (guestfs_h *g,
10167 const char *lv,
10168 int percent);
10169 This expands an existing logical volume "lv" so that it fills "pc"% of
10171 the remaining free space in the volume group. Commonly you would call
10172 this with pc = 100 which expands the logical volume as much as
10173 possible, using all remaining free space in the volume group.
10174 This function returns 0 on success or -1 on error.
10176 This function depends on the feature "lvm2". See also
10178 "guestfs_feature_available".
10179 (Added in 1.3.3)
10181 guestfs_lvs
10183 char **
10184 guestfs_lvs (guestfs_h *g);
10185 List all the logical volumes detected. This is the equivalent of the
10187 lvs(8) command.
10188 This returns a list of the logical volume device names (eg.
10190 /dev/VolGroup00/LogVol00).
10191 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10193 This function returns a NULL-terminated array of strings (like
10195 environ(3)), or NULL if there was an error. The caller must free the
10196 strings and the array after use.
10197 This function depends on the feature "lvm2". See also
10199 "guestfs_feature_available".
10200 (Added in 0.4)
10202 guestfs_lvs_full
10204 struct guestfs_lvm_lv_list *
10205 guestfs_lvs_full (guestfs_h *g);
10206 List all the logical volumes detected. This is the equivalent of the
10208 lvs(8) command. The "full" version includes all fields.
10209 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10211 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10212 after use.
10213 This function depends on the feature "lvm2". See also
10215 "guestfs_feature_available".
10216 (Added in 0.4)
10218 guestfs_lvuuid
10220 char *
10221 guestfs_lvuuid (guestfs_h *g,
10222 const char *device);
10223 This command returns the UUID of the LVM LV "device".
10225 This function returns a string, or NULL on error. The caller must free
10227 the returned string after use.
10228 (Added in 1.0.87)
10230 guestfs_lxattrlist
10232 struct guestfs_xattr_list *
10233 guestfs_lxattrlist (guestfs_h *g,
10234 const char *path,
10235 char *const *names);
10236 This call allows you to get the extended attributes of multiple files,
10238 where all files are in the directory "path". "names" is the list of
10239 files from this directory.
10240 On return you get a flat list of xattr structs which must be
10242 interpreted sequentially. The first xattr struct always has a zero-
10243 length "attrname". "attrval" in this struct is zero-length to indicate
10244 there was an error doing "lgetxattr" for this file, or is a C string
10245 which is a decimal number (the number of following attributes for this
10246 file, which could be "0"). Then after the first xattr struct are the
10247 zero or more attributes for the first named file. This repeats for the
10248 second and subsequent files.
10249 This call is intended for programs that want to efficiently list a
10251 directory contents without making many round-trips. See also
10252 "guestfs_lstatlist" for a similarly efficient call for getting standard
10253 stats.
10254 This function returns a "struct guestfs_xattr_list *", or NULL if there
10256 was an error. The caller must call "guestfs_free_xattr_list" after
10257 use.
10258 This function depends on the feature "linuxxattrs". See also
10260 "guestfs_feature_available".
10261 (Added in 1.0.77)
10263 guestfs_max_disks
10265 int
10266 guestfs_max_disks (guestfs_h *g);
10267 Return the maximum number of disks that may be added to a handle (eg.
10269 by "guestfs_add_drive_opts" and similar calls).
10270 This function was added in libguestfs 1.19.7. In previous versions of
10272 libguestfs the limit was 25.
10273 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10275 On error this function returns -1.
10277 (Added in 1.19.7)
10279 guestfs_md_create
10281 int
10282 guestfs_md_create (guestfs_h *g,
10283 const char *name,
10284 char *const *devices,
10285 ...);
10286 You may supply a list of optional arguments to this call. Use zero or
10288 more of the following pairs of parameters, and terminate the list with
10289 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10290 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10292 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10293 GUESTFS_MD_CREATE_SPARE, int spare,
10294 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10295 GUESTFS_MD_CREATE_LEVEL, const char *level,
10296 Create a Linux md (RAID) device named "name" on the devices in the list
10298 "devices".
10299 The optional parameters are:
10301 "missingbitmap"
10303 A bitmap of missing devices. If a bit is set it means that a
10304 missing device is added to the array. The least significant bit
10305 corresponds to the first device in the array.
10306 As examples:
10308 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10310 resulting array would be "[<missing>, "/dev/sda"]".
10311 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10313 resulting array would be "["/dev/sda", <missing>]".
10314 This defaults to 0 (no missing devices).
10316 The length of "devices" + the number of bits set in "missingbitmap"
10318 must equal "nrdevices" + "spare".
10319 "nrdevices"
10321 The number of active RAID devices.
10322 If not set, this defaults to the length of "devices" plus the
10324 number of bits set in "missingbitmap".
10325 "spare"
10327 The number of spare devices.
10328 If not set, this defaults to 0.
10330 "chunk"
10332 The chunk size in bytes.
10333 "level"
10335 The RAID level, which can be one of: linear, raid0, 0, stripe,
10336 raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10. Some
10337 of these are synonymous, and more levels may be added in future.
10338 If not set, this defaults to "raid1".
10340 This function returns 0 on success or -1 on error.
10342 This function depends on the feature "mdadm". See also
10344 "guestfs_feature_available".
10345 (Added in 1.15.6)
10347 guestfs_md_create_va
10349 int
10350 guestfs_md_create_va (guestfs_h *g,
10351 const char *name,
10352 char *const *devices,
10353 va_list args);
10354 This is the "va_list variant" of "guestfs_md_create".
10356 See "CALLS WITH OPTIONAL ARGUMENTS".
10358 guestfs_md_create_argv
10360 int
10361 guestfs_md_create_argv (guestfs_h *g,
10362 const char *name,
10363 char *const *devices,
10364 const struct guestfs_md_create_argv *optargs);
10365 This is the "argv variant" of "guestfs_md_create".
10367 See "CALLS WITH OPTIONAL ARGUMENTS".
10369 guestfs_md_detail
10371 char **
10372 guestfs_md_detail (guestfs_h *g,
10373 const char *md);
10374 This command exposes the output of 'mdadm -DY <md>'. The following
10376 fields are usually present in the returned hash. Other fields may also
10377 be present.
10378 "level"
10380 The raid level of the MD device.
10381 "devices"
10383 The number of underlying devices in the MD device.
10384 "metadata"
10386 The metadata version used.
10387 "uuid"
10389 The UUID of the MD device.
10390 "name"
10392 The name of the MD device.
10393 This function returns a NULL-terminated array of strings, or NULL if
10395 there was an error. The array of strings will always have length
10396 "2n+1", where "n" keys and values alternate, followed by the trailing
10397 NULL entry. The caller must free the strings and the array after use.
10398 This function depends on the feature "mdadm". See also
10400 "guestfs_feature_available".
10401 (Added in 1.15.6)
10403 guestfs_md_stat
10405 struct guestfs_mdstat_list *
10406 guestfs_md_stat (guestfs_h *g,
10407 const char *md);
10408 This call returns a list of the underlying devices which make up the
10410 single software RAID array device "md".
10411 To get a list of software RAID devices, call "guestfs_list_md_devices".
10413 Each structure returned corresponds to one device along with additional
10415 status information:
10416 "mdstat_device"
10418 The name of the underlying device.
10419 "mdstat_index"
10421 The index of this device within the array.
10422 "mdstat_flags"
10424 Flags associated with this device. This is a string containing (in
10425 no specific order) zero or more of the following flags:
10426 "W" write-mostly
10428 "F" device is faulty
10430 "S" device is a RAID spare
10432 "R" replacement
10434 This function returns a "struct guestfs_mdstat_list *", or NULL if
10436 there was an error. The caller must call "guestfs_free_mdstat_list"
10437 after use.
10438 This function depends on the feature "mdadm". See also
10440 "guestfs_feature_available".
10441 (Added in 1.17.21)
10443 guestfs_md_stop
10445 int
10446 guestfs_md_stop (guestfs_h *g,
10447 const char *md);
10448 This command deactivates the MD array named "md". The device is
10450 stopped, but it is not destroyed or zeroed.
10451 This function returns 0 on success or -1 on error.
10453 This function depends on the feature "mdadm". See also
10455 "guestfs_feature_available".
10456 (Added in 1.15.6)
10458 guestfs_mkdir
10460 int
10461 guestfs_mkdir (guestfs_h *g,
10462 const char *path);
10463 Create a directory named "path".
10465 This function returns 0 on success or -1 on error.
10467 (Added in 0.8)
10469 guestfs_mkdir_mode
10471 int
10472 guestfs_mkdir_mode (guestfs_h *g,
10473 const char *path,
10474 int mode);
10475 This command creates a directory, setting the initial permissions of
10477 the directory to "mode".
10478 For common Linux filesystems, the actual mode which is set will be
10480 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10481 the mode in other ways.
10482 See also "guestfs_mkdir", "guestfs_umask"
10484 This function returns 0 on success or -1 on error.
10486 (Added in 1.0.77)
10488 guestfs_mkdir_p
10490 int
10491 guestfs_mkdir_p (guestfs_h *g,
10492 const char *path);
10493 Create a directory named "path", creating any parent directories as
10495 necessary. This is like the "mkdir -p" shell command.
10496 This function returns 0 on success or -1 on error.
10498 (Added in 0.8)
10500 guestfs_mkdtemp
10502 char *
10503 guestfs_mkdtemp (guestfs_h *g,
10504 const char *tmpl);
10505 This command creates a temporary directory. The "tmpl" parameter
10507 should be a full pathname for the temporary directory name with the
10508 final six characters being "XXXXXX".
10509 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10511 one being suitable for Windows filesystems.
10512 The name of the temporary directory that was created is returned.
10514 The temporary directory is created with mode 0700 and is owned by root.
10516 The caller is responsible for deleting the temporary directory and its
10518 contents after use.
10519 See also: mkdtemp(3)
10521 This function returns a string, or NULL on error. The caller must free
10523 the returned string after use.
10524 (Added in 1.0.54)
10526 guestfs_mke2fs
10528 int
10529 guestfs_mke2fs (guestfs_h *g,
10530 const char *device,
10531 ...);
10532 You may supply a list of optional arguments to this call. Use zero or
10534 more of the following pairs of parameters, and terminate the list with
10535 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10536 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10538 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10539 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10540 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10541 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10542 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10543 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10544 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10545 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10546 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10547 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10548 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10549 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10550 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10551 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10552 GUESTFS_MKE2FS_LABEL, const char *label,
10553 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10554 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10555 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10556 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10557 GUESTFS_MKE2FS_UUID, const char *uuid,
10558 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10559 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10560 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10561 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10562 GUESTFS_MKE2FS_TESTFS, int testfs,
10563 GUESTFS_MKE2FS_DISCARD, int discard,
10564 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10565 GUESTFS_MKE2FS_EXTENT, int extent,
10566 GUESTFS_MKE2FS_FILETYPE, int filetype,
10567 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10568 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10569 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10570 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10571 GUESTFS_MKE2FS_QUOTA, int quota,
10572 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10573 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10574 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10575 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10577 "device".
10578 The optional "blockscount" is the size of the filesystem in blocks. If
10580 omitted it defaults to the size of "device". Note if the filesystem is
10581 too small to contain a journal, "mke2fs" will silently create an ext2
10582 filesystem instead.
10583 This function returns 0 on success or -1 on error.
10585 (Added in 1.19.44)
10587 guestfs_mke2fs_va
10589 int
10590 guestfs_mke2fs_va (guestfs_h *g,
10591 const char *device,
10592 va_list args);
10593 This is the "va_list variant" of "guestfs_mke2fs".
10595 See "CALLS WITH OPTIONAL ARGUMENTS".
10597 guestfs_mke2fs_argv
10599 int
10600 guestfs_mke2fs_argv (guestfs_h *g,
10601 const char *device,
10602 const struct guestfs_mke2fs_argv *optargs);
10603 This is the "argv variant" of "guestfs_mke2fs".
10605 See "CALLS WITH OPTIONAL ARGUMENTS".
10607 guestfs_mke2fs_J
10609 int
10610 guestfs_mke2fs_J (guestfs_h *g,
10611 const char *fstype,
10612 int blocksize,
10613 const char *device,
10614 const char *journal);
10615 This function is deprecated. In new code, use the "guestfs_mke2fs"
10617 call instead.
10618 Deprecated functions will not be removed from the API, but the fact
10620 that they are deprecated indicates that there are problems with correct
10621 use of these functions.
10622 This creates an ext2/3/4 filesystem on "device" with an external
10624 journal on "journal". It is equivalent to the command:
10625 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10627 See also "guestfs_mke2journal".
10629 This function returns 0 on success or -1 on error.
10631 (Added in 1.0.68)
10633 guestfs_mke2fs_JL
10635 int
10636 guestfs_mke2fs_JL (guestfs_h *g,
10637 const char *fstype,
10638 int blocksize,
10639 const char *device,
10640 const char *label);
10641 This function is deprecated. In new code, use the "guestfs_mke2fs"
10643 call instead.
10644 Deprecated functions will not be removed from the API, but the fact
10646 that they are deprecated indicates that there are problems with correct
10647 use of these functions.
10648 This creates an ext2/3/4 filesystem on "device" with an external
10650 journal on the journal labeled "label".
10651 See also "guestfs_mke2journal_L".
10653 This function returns 0 on success or -1 on error.
10655 (Added in 1.0.68)
10657 guestfs_mke2fs_JU
10659 int
10660 guestfs_mke2fs_JU (guestfs_h *g,
10661 const char *fstype,
10662 int blocksize,
10663 const char *device,
10664 const char *uuid);
10665 This function is deprecated. In new code, use the "guestfs_mke2fs"
10667 call instead.
10668 Deprecated functions will not be removed from the API, but the fact
10670 that they are deprecated indicates that there are problems with correct
10671 use of these functions.
10672 This creates an ext2/3/4 filesystem on "device" with an external
10674 journal on the journal with UUID "uuid".
10675 See also "guestfs_mke2journal_U".
10677 This function returns 0 on success or -1 on error.
10679 This function depends on the feature "linuxfsuuid". See also
10681 "guestfs_feature_available".
10682 (Added in 1.0.68)
10684 guestfs_mke2journal
10686 int
10687 guestfs_mke2journal (guestfs_h *g,
10688 int blocksize,
10689 const char *device);
10690 This function is deprecated. In new code, use the "guestfs_mke2fs"
10692 call instead.
10693 Deprecated functions will not be removed from the API, but the fact
10695 that they are deprecated indicates that there are problems with correct
10696 use of these functions.
10697 This creates an ext2 external journal on "device". It is equivalent to
10699 the command:
10700 mke2fs -O journal_dev -b blocksize device
10702 This function returns 0 on success or -1 on error.
10704 (Added in 1.0.68)
10706 guestfs_mke2journal_L
10708 int
10709 guestfs_mke2journal_L (guestfs_h *g,
10710 int blocksize,
10711 const char *label,
10712 const char *device);
10713 This function is deprecated. In new code, use the "guestfs_mke2fs"
10715 call instead.
10716 Deprecated functions will not be removed from the API, but the fact
10718 that they are deprecated indicates that there are problems with correct
10719 use of these functions.
10720 This creates an ext2 external journal on "device" with label "label".
10722 This function returns 0 on success or -1 on error.
10724 (Added in 1.0.68)
10726 guestfs_mke2journal_U
10728 int
10729 guestfs_mke2journal_U (guestfs_h *g,
10730 int blocksize,
10731 const char *uuid,
10732 const char *device);
10733 This function is deprecated. In new code, use the "guestfs_mke2fs"
10735 call instead.
10736 Deprecated functions will not be removed from the API, but the fact
10738 that they are deprecated indicates that there are problems with correct
10739 use of these functions.
10740 This creates an ext2 external journal on "device" with UUID "uuid".
10742 This function returns 0 on success or -1 on error.
10744 This function depends on the feature "linuxfsuuid". See also
10746 "guestfs_feature_available".
10747 (Added in 1.0.68)
10749 guestfs_mkfifo
10751 int
10752 guestfs_mkfifo (guestfs_h *g,
10753 int mode,
10754 const char *path);
10755 This call creates a FIFO (named pipe) called "path" with mode "mode".
10757 It is just a convenient wrapper around "guestfs_mknod".
10758 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
10760 The mode actually set is affected by the umask.
10762 This function returns 0 on success or -1 on error.
10764 This function depends on the feature "mknod". See also
10766 "guestfs_feature_available".
10767 (Added in 1.0.55)
10769 guestfs_mkfs
10771 int
10772 guestfs_mkfs (guestfs_h *g,
10773 const char *fstype,
10774 const char *device);
10775 This function is provided for backwards compatibility with earlier
10777 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
10778 optional arguments.
10779 (Added in 0.8)
10781 guestfs_mkfs_opts
10783 int
10784 guestfs_mkfs_opts (guestfs_h *g,
10785 const char *fstype,
10786 const char *device,
10787 ...);
10788 You may supply a list of optional arguments to this call. Use zero or
10790 more of the following pairs of parameters, and terminate the list with
10791 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10792 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
10794 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
10795 GUESTFS_MKFS_OPTS_INODE, int inode,
10796 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
10797 GUESTFS_MKFS_OPTS_LABEL, const char *label,
10798 This function creates a filesystem on "device". The filesystem type is
10800 "fstype", for example "ext3".
10801 The optional arguments are:
10803 "blocksize"
10805 The filesystem block size. Supported block sizes depend on the
10806 filesystem type, but typically they are 1024, 2048 or 4096 for
10807 Linux ext2/3 filesystems.
10808 For VFAT and NTFS the "blocksize" parameter is treated as the
10810 requested cluster size.
10811 For UFS block sizes, please see mkfs.ufs(8).
10813 "features"
10815 This passes the -O parameter to the external mkfs program.
10816 For certain filesystem types, this allows extra filesystem features
10818 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
10819 You cannot use this optional parameter with the "gfs" or "gfs2"
10821 filesystem type.
10822 "inode"
10824 This passes the -I parameter to the external mke2fs(8) program
10825 which sets the inode size (only for ext2/3/4 filesystems at
10826 present).
10827 "sectorsize"
10829 This passes the -S parameter to external mkfs.ufs(8) program, which
10830 sets sector size for ufs filesystem.
10831 This function returns 0 on success or -1 on error.
10833 (Added in 0.8)
10835 guestfs_mkfs_opts_va
10837 int
10838 guestfs_mkfs_opts_va (guestfs_h *g,
10839 const char *fstype,
10840 const char *device,
10841 va_list args);
10842 This is the "va_list variant" of "guestfs_mkfs_opts".
10844 See "CALLS WITH OPTIONAL ARGUMENTS".
10846 guestfs_mkfs_opts_argv
10848 int
10849 guestfs_mkfs_opts_argv (guestfs_h *g,
10850 const char *fstype,
10851 const char *device,
10852 const struct guestfs_mkfs_opts_argv *optargs);
10853 This is the "argv variant" of "guestfs_mkfs_opts".
10855 See "CALLS WITH OPTIONAL ARGUMENTS".
10857 guestfs_mkfs_b
10859 int
10860 guestfs_mkfs_b (guestfs_h *g,
10861 const char *fstype,
10862 int blocksize,
10863 const char *device);
10864 This function is deprecated. In new code, use the "guestfs_mkfs" call
10866 instead.
10867 Deprecated functions will not be removed from the API, but the fact
10869 that they are deprecated indicates that there are problems with correct
10870 use of these functions.
10871 This call is similar to "guestfs_mkfs", but it allows you to control
10873 the block size of the resulting filesystem. Supported block sizes
10874 depend on the filesystem type, but typically they are 1024, 2048 or
10875 4096 only.
10876 For VFAT and NTFS the "blocksize" parameter is treated as the requested
10878 cluster size.
10879 This function returns 0 on success or -1 on error.
10881 (Added in 1.0.68)
10883 guestfs_mkfs_btrfs
10885 int
10886 guestfs_mkfs_btrfs (guestfs_h *g,
10887 char *const *devices,
10888 ...);
10889 You may supply a list of optional arguments to this call. Use zero or
10891 more of the following pairs of parameters, and terminate the list with
10892 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10893 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
10895 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
10896 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
10897 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
10898 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
10899 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
10900 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
10901 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
10902 Create a btrfs filesystem, allowing all configurables to be set. For
10904 more information on the optional arguments, see mkfs.btrfs(8).
10905 Since btrfs filesystems can span multiple devices, this takes a non-
10907 empty list of devices.
10908 To create general filesystems, use "guestfs_mkfs".
10910 This function returns 0 on success or -1 on error.
10912 This function depends on the feature "btrfs". See also
10914 "guestfs_feature_available".
10915 (Added in 1.17.25)
10917 guestfs_mkfs_btrfs_va
10919 int
10920 guestfs_mkfs_btrfs_va (guestfs_h *g,
10921 char *const *devices,
10922 va_list args);
10923 This is the "va_list variant" of "guestfs_mkfs_btrfs".
10925 See "CALLS WITH OPTIONAL ARGUMENTS".
10927 guestfs_mkfs_btrfs_argv
10929 int
10930 guestfs_mkfs_btrfs_argv (guestfs_h *g,
10931 char *const *devices,
10932 const struct guestfs_mkfs_btrfs_argv *optargs);
10933 This is the "argv variant" of "guestfs_mkfs_btrfs".
10935 See "CALLS WITH OPTIONAL ARGUMENTS".
10937 guestfs_mklost_and_found
10939 int
10940 guestfs_mklost_and_found (guestfs_h *g,
10941 const char *mountpoint);
10942 Make the "lost+found" directory, normally in the root directory of an
10944 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
10945 to create the "lost+found" directory.
10946 This function returns 0 on success or -1 on error.
10948 (Added in 1.19.56)
10950 guestfs_mkmountpoint
10952 int
10953 guestfs_mkmountpoint (guestfs_h *g,
10954 const char *exemptpath);
10955 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
10957 that can be used to create extra mountpoints before mounting the first
10958 filesystem.
10959 These calls are only necessary in some very limited circumstances,
10961 mainly the case where you want to mount a mix of unrelated and/or read-
10962 only filesystems together.
10963 For example, live CDs often contain a "Russian doll" nest of
10965 filesystems, an ISO outer layer, with a squashfs image inside, with an
10966 ext2/3 image inside that. You can unpack this as follows in guestfish:
10967 add-ro Fedora-11-i686-Live.iso
10969 run
10970 mkmountpoint /cd
10971 mkmountpoint /sqsh
10972 mkmountpoint /ext3fs
10973 mount /dev/sda /cd
10974 mount-loop /cd/LiveOS/squashfs.img /sqsh
10975 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
10976 The inner filesystem is now unpacked under the /ext3fs mountpoint.
10978 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
10980 You may get unexpected errors if you try to mix these calls. It is
10981 safest to manually unmount filesystems and remove mountpoints after
10982 use.
10983 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
10985 first, so for this to work for manual mountpoints, you must ensure that
10986 the innermost mountpoints have the longest pathnames, as in the example
10987 code above.
10988 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
10990 Autosync [see "guestfs_set_autosync", this is set by default on
10992 handles] can cause "guestfs_umount_all" to be called when the handle is
10993 closed which can also trigger these issues.
10994 This function returns 0 on success or -1 on error.
10996 (Added in 1.0.62)
10998 guestfs_mknod
11000 int
11001 guestfs_mknod (guestfs_h *g,
11002 int mode,
11003 int devmajor,
11004 int devminor,
11005 const char *path);
11006 This call creates block or character special devices, or named pipes
11008 (FIFOs).
11009 The "mode" parameter should be the mode, using the standard constants.
11011 "devmajor" and "devminor" are the device major and minor numbers, only
11012 used when creating block and character special devices.
11013 Note that, just like mknod(2), the mode must be bitwise OR'd with
11015 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11016 a regular file). These constants are available in the standard Linux
11017 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11018 "guestfs_mkfifo" which are wrappers around this command which bitwise
11019 OR in the appropriate constant for you.
11020 The mode actually set is affected by the umask.
11022 This function returns 0 on success or -1 on error.
11024 This function depends on the feature "mknod". See also
11026 "guestfs_feature_available".
11027 (Added in 1.0.55)
11029 guestfs_mknod_b
11031 int
11032 guestfs_mknod_b (guestfs_h *g,
11033 int mode,
11034 int devmajor,
11035 int devminor,
11036 const char *path);
11037 This call creates a block device node called "path" with mode "mode"
11039 and device major/minor "devmajor" and "devminor". It is just a
11040 convenient wrapper around "guestfs_mknod".
11041 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11043 The mode actually set is affected by the umask.
11045 This function returns 0 on success or -1 on error.
11047 This function depends on the feature "mknod". See also
11049 "guestfs_feature_available".
11050 (Added in 1.0.55)
11052 guestfs_mknod_c
11054 int
11055 guestfs_mknod_c (guestfs_h *g,
11056 int mode,
11057 int devmajor,
11058 int devminor,
11059 const char *path);
11060 This call creates a char device node called "path" with mode "mode" and
11062 device major/minor "devmajor" and "devminor". It is just a convenient
11063 wrapper around "guestfs_mknod".
11064 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11066 The mode actually set is affected by the umask.
11068 This function returns 0 on success or -1 on error.
11070 This function depends on the feature "mknod". See also
11072 "guestfs_feature_available".
11073 (Added in 1.0.55)
11075 guestfs_mksquashfs
11077 int
11078 guestfs_mksquashfs (guestfs_h *g,
11079 const char *path,
11080 const char *filename,
11081 ...);
11082 You may supply a list of optional arguments to this call. Use zero or
11084 more of the following pairs of parameters, and terminate the list with
11085 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11086 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11088 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11089 Create a squashfs filesystem for the specified "path".
11091 The optional "compress" flag controls compression. If not given, then
11093 the output compressed using "gzip". Otherwise one of the following
11094 strings may be given to select the compression type of the squashfs:
11095 "gzip", "lzma", "lzo", "lz4", "xz".
11096 The other optional arguments are:
11098 "excludes"
11100 A list of wildcards. Files are excluded if they match any of the
11101 wildcards.
11102 Please note that this API may fail when used to compress directories
11104 with large files, such as the resulting squashfs will be over 3GB big.
11105 This function returns 0 on success or -1 on error.
11107 This function depends on the feature "squashfs". See also
11109 "guestfs_feature_available".
11110 (Added in 1.35.25)
11112 guestfs_mksquashfs_va
11114 int
11115 guestfs_mksquashfs_va (guestfs_h *g,
11116 const char *path,
11117 const char *filename,
11118 va_list args);
11119 This is the "va_list variant" of "guestfs_mksquashfs".
11121 See "CALLS WITH OPTIONAL ARGUMENTS".
11123 guestfs_mksquashfs_argv
11125 int
11126 guestfs_mksquashfs_argv (guestfs_h *g,
11127 const char *path,
11128 const char *filename,
11129 const struct guestfs_mksquashfs_argv *optargs);
11130 This is the "argv variant" of "guestfs_mksquashfs".
11132 See "CALLS WITH OPTIONAL ARGUMENTS".
11134 guestfs_mkswap
11136 int
11137 guestfs_mkswap (guestfs_h *g,
11138 const char *device);
11139 This function is provided for backwards compatibility with earlier
11141 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11142 optional arguments.
11143 (Added in 1.0.55)
11145 guestfs_mkswap_opts
11147 int
11148 guestfs_mkswap_opts (guestfs_h *g,
11149 const char *device,
11150 ...);
11151 You may supply a list of optional arguments to this call. Use zero or
11153 more of the following pairs of parameters, and terminate the list with
11154 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11155 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11157 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11158 Create a Linux swap partition on "device".
11160 The option arguments "label" and "uuid" allow you to set the label
11162 and/or UUID of the new swap partition.
11163 This function returns 0 on success or -1 on error.
11165 (Added in 1.0.55)
11167 guestfs_mkswap_opts_va
11169 int
11170 guestfs_mkswap_opts_va (guestfs_h *g,
11171 const char *device,
11172 va_list args);
11173 This is the "va_list variant" of "guestfs_mkswap_opts".
11175 See "CALLS WITH OPTIONAL ARGUMENTS".
11177 guestfs_mkswap_opts_argv
11179 int
11180 guestfs_mkswap_opts_argv (guestfs_h *g,
11181 const char *device,
11182 const struct guestfs_mkswap_opts_argv *optargs);
11183 This is the "argv variant" of "guestfs_mkswap_opts".
11185 See "CALLS WITH OPTIONAL ARGUMENTS".
11187 guestfs_mkswap_L
11189 int
11190 guestfs_mkswap_L (guestfs_h *g,
11191 const char *label,
11192 const char *device);
11193 This function is deprecated. In new code, use the "guestfs_mkswap"
11195 call instead.
11196 Deprecated functions will not be removed from the API, but the fact
11198 that they are deprecated indicates that there are problems with correct
11199 use of these functions.
11200 Create a swap partition on "device" with label "label".
11202 Note that you cannot attach a swap label to a block device (eg.
11204 /dev/sda), just to a partition. This appears to be a limitation of the
11205 kernel or swap tools.
11206 This function returns 0 on success or -1 on error.
11208 (Added in 1.0.55)
11210 guestfs_mkswap_U
11212 int
11213 guestfs_mkswap_U (guestfs_h *g,
11214 const char *uuid,
11215 const char *device);
11216 This function is deprecated. In new code, use the "guestfs_mkswap"
11218 call instead.
11219 Deprecated functions will not be removed from the API, but the fact
11221 that they are deprecated indicates that there are problems with correct
11222 use of these functions.
11223 Create a swap partition on "device" with UUID "uuid".
11225 This function returns 0 on success or -1 on error.
11227 This function depends on the feature "linuxfsuuid". See also
11229 "guestfs_feature_available".
11230 (Added in 1.0.55)
11232 guestfs_mkswap_file
11234 int
11235 guestfs_mkswap_file (guestfs_h *g,
11236 const char *path);
11237 Create a swap file.
11239 This command just writes a swap file signature to an existing file. To
11241 create the file itself, use something like "guestfs_fallocate".
11242 This function returns 0 on success or -1 on error.
11244 (Added in 1.0.66)
11246 guestfs_mktemp
11248 char *
11249 guestfs_mktemp (guestfs_h *g,
11250 const char *tmpl,
11251 ...);
11252 You may supply a list of optional arguments to this call. Use zero or
11254 more of the following pairs of parameters, and terminate the list with
11255 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11256 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11258 This command creates a temporary file. The "tmpl" parameter should be
11260 a full pathname for the temporary directory name with the final six
11261 characters being "XXXXXX".
11262 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11264 one being suitable for Windows filesystems.
11265 The name of the temporary file that was created is returned.
11267 The temporary file is created with mode 0600 and is owned by root.
11269 The caller is responsible for deleting the temporary file after use.
11271 If the optional "suffix" parameter is given, then the suffix (eg.
11273 ".txt") is appended to the temporary name.
11274 See also: "guestfs_mkdtemp".
11276 This function returns a string, or NULL on error. The caller must free
11278 the returned string after use.
11279 (Added in 1.19.53)
11281 guestfs_mktemp_va
11283 char *
11284 guestfs_mktemp_va (guestfs_h *g,
11285 const char *tmpl,
11286 va_list args);
11287 This is the "va_list variant" of "guestfs_mktemp".
11289 See "CALLS WITH OPTIONAL ARGUMENTS".
11291 guestfs_mktemp_argv
11293 char *
11294 guestfs_mktemp_argv (guestfs_h *g,
11295 const char *tmpl,
11296 const struct guestfs_mktemp_argv *optargs);
11297 This is the "argv variant" of "guestfs_mktemp".
11299 See "CALLS WITH OPTIONAL ARGUMENTS".
11301 guestfs_modprobe
11303 int
11304 guestfs_modprobe (guestfs_h *g,
11305 const char *modulename);
11306 This loads a kernel module in the appliance.
11308 This function returns 0 on success or -1 on error.
11310 This function depends on the feature "linuxmodules". See also
11312 "guestfs_feature_available".
11313 (Added in 1.0.68)
11315 guestfs_mount
11317 int
11318 guestfs_mount (guestfs_h *g,
11319 const char *mountable,
11320 const char *mountpoint);
11321 Mount a guest disk at a position in the filesystem. Block devices are
11323 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11324 If those block devices contain partitions, they will have the usual
11325 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11326 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11327 "guestfs_inspect_get_mountpoints".
11328 The rules are the same as for mount(2): A filesystem must first be
11330 mounted on / before others can be mounted. Other filesystems can only
11331 be mounted on directories which already exist.
11332 The mounted filesystem is writable, if we have sufficient permissions
11334 on the underlying device.
11335 Before libguestfs 1.13.16, this call implicitly added the options
11337 "sync" and "noatime". The "sync" option greatly slowed writes and
11338 caused many problems for users. If your program might need to work
11339 with older versions of libguestfs, use "guestfs_mount_options" instead
11340 (using an empty string for the first parameter if you don't want any
11341 options).
11342 This function returns 0 on success or -1 on error.
11344 (Added in 0.3)
11346 guestfs_mount_local
11348 int
11349 guestfs_mount_local (guestfs_h *g,
11350 const char *localmountpoint,
11351 ...);
11352 You may supply a list of optional arguments to this call. Use zero or
11354 more of the following pairs of parameters, and terminate the list with
11355 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11356 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11358 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11359 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11360 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11361 This call exports the libguestfs-accessible filesystem to a local
11363 mountpoint (directory) called "localmountpoint". Ordinary reads and
11364 writes to files and directories under "localmountpoint" are redirected
11365 through libguestfs.
11366 If the optional "readonly" flag is set to true, then writes to the
11368 filesystem return error "EROFS".
11369 "options" is a comma-separated list of mount options. See
11371 guestmount(1) for some useful options.
11372 "cachetimeout" sets the timeout (in seconds) for cached directory
11374 entries. The default is 60 seconds. See guestmount(1) for further
11375 information.
11376 If "debugcalls" is set to true, then additional debugging information
11378 is generated for every FUSE call.
11379 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11381 processing requests (access to it will block). You have to call
11382 "guestfs_mount_local_run" to run the main loop.
11383 See "MOUNT LOCAL" for full documentation.
11385 This function returns 0 on success or -1 on error.
11387 (Added in 1.17.22)
11389 guestfs_mount_local_va
11391 int
11392 guestfs_mount_local_va (guestfs_h *g,
11393 const char *localmountpoint,
11394 va_list args);
11395 This is the "va_list variant" of "guestfs_mount_local".
11397 See "CALLS WITH OPTIONAL ARGUMENTS".
11399 guestfs_mount_local_argv
11401 int
11402 guestfs_mount_local_argv (guestfs_h *g,
11403 const char *localmountpoint,
11404 const struct guestfs_mount_local_argv *optargs);
11405 This is the "argv variant" of "guestfs_mount_local".
11407 See "CALLS WITH OPTIONAL ARGUMENTS".
11409 guestfs_mount_local_run
11411 int
11412 guestfs_mount_local_run (guestfs_h *g);
11413 Run the main loop which translates kernel calls to libguestfs calls.
11415 This should only be called after "guestfs_mount_local" returns
11417 successfully. The call will not return until the filesystem is
11418 unmounted.
11419 Note you must not make concurrent libguestfs calls on the same handle
11421 from another thread.
11422 You may call this from a different thread than the one which called
11424 "guestfs_mount_local", subject to the usual rules for threads and
11425 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11426 See "MOUNT LOCAL" for full documentation.
11428 This function returns 0 on success or -1 on error.
11430 (Added in 1.17.22)
11432 guestfs_mount_loop
11434 int
11435 guestfs_mount_loop (guestfs_h *g,
11436 const char *file,
11437 const char *mountpoint);
11438 This command lets you mount file (a filesystem image in a file) on a
11440 mount point. It is entirely equivalent to the command "mount -o loop
11441 file mountpoint".
11442 This function returns 0 on success or -1 on error.
11444 (Added in 1.0.54)
11446 guestfs_mount_options
11448 int
11449 guestfs_mount_options (guestfs_h *g,
11450 const char *options,
11451 const char *mountable,
11452 const char *mountpoint);
11453 This is the same as the "guestfs_mount" command, but it allows you to
11455 set the mount options as for the mount(8) -o flag.
11456 If the "options" parameter is an empty string, then no options are
11458 passed (all options default to whatever the filesystem uses).
11459 This function returns 0 on success or -1 on error.
11461 (Added in 1.0.10)
11463 guestfs_mount_ro
11465 int
11466 guestfs_mount_ro (guestfs_h *g,
11467 const char *mountable,
11468 const char *mountpoint);
11469 This is the same as the "guestfs_mount" command, but it mounts the
11471 filesystem with the read-only (-o ro) flag.
11472 This function returns 0 on success or -1 on error.
11474 (Added in 1.0.10)
11476 guestfs_mount_vfs
11478 int
11479 guestfs_mount_vfs (guestfs_h *g,
11480 const char *options,
11481 const char *vfstype,
11482 const char *mountable,
11483 const char *mountpoint);
11484 This is the same as the "guestfs_mount" command, but it allows you to
11486 set both the mount options and the vfstype as for the mount(8) -o and
11487 -t flags.
11488 This function returns 0 on success or -1 on error.
11490 (Added in 1.0.10)
11492 guestfs_mountable_device
11494 char *
11495 guestfs_mountable_device (guestfs_h *g,
11496 const char *mountable);
11497 Returns the device name of a mountable. In quite a lot of cases, the
11499 mountable is the device name.
11500 However this doesn't apply for btrfs subvolumes, where the mountable is
11502 a combination of both the device name and the subvolume path (see also
11503 "guestfs_mountable_subvolume" to extract the subvolume path of the
11504 mountable if any).
11505 This function returns a string, or NULL on error. The caller must free
11507 the returned string after use.
11508 (Added in 1.33.15)
11510 guestfs_mountable_subvolume
11512 char *
11513 guestfs_mountable_subvolume (guestfs_h *g,
11514 const char *mountable);
11515 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11517 are a combination of both the device name and the subvolume path (see
11518 also "guestfs_mountable_device" to extract the device of the
11519 mountable).
11520 If the mountable does not represent a btrfs subvolume, then this
11522 function fails and the "errno" is set to "EINVAL".
11523 This function returns a string, or NULL on error. The caller must free
11525 the returned string after use.
11526 (Added in 1.33.15)
11528 guestfs_mountpoints
11530 char **
11531 guestfs_mountpoints (guestfs_h *g);
11532 This call is similar to "guestfs_mounts". That call returns a list of
11534 devices. This one returns a hash table (map) of device name to
11535 directory where the device is mounted.
11536 This function returns a NULL-terminated array of strings, or NULL if
11538 there was an error. The array of strings will always have length
11539 "2n+1", where "n" keys and values alternate, followed by the trailing
11540 NULL entry. The caller must free the strings and the array after use.
11541 (Added in 1.0.62)
11543 guestfs_mounts
11545 char **
11546 guestfs_mounts (guestfs_h *g);
11547 This returns the list of currently mounted filesystems. It returns the
11549 list of devices (eg. /dev/sda1, /dev/VG/LV).
11550 Some internal mounts are not shown.
11552 See also: "guestfs_mountpoints"
11554 This function returns a NULL-terminated array of strings (like
11556 environ(3)), or NULL if there was an error. The caller must free the
11557 strings and the array after use.
11558 (Added in 0.8)
11560 guestfs_mv
11562 int
11563 guestfs_mv (guestfs_h *g,
11564 const char *src,
11565 const char *dest);
11566 This moves a file from "src" to "dest" where "dest" is either a
11568 destination filename or destination directory.
11569 See also: "guestfs_rename".
11571 This function returns 0 on success or -1 on error.
11573 (Added in 1.0.18)
11575 guestfs_nr_devices
11577 int
11578 guestfs_nr_devices (guestfs_h *g);
11579 This returns the number of whole block devices that were added. This
11581 is the same as the number of devices that would be returned if you
11582 called "guestfs_list_devices".
11583 To find out the maximum number of devices that could be added, call
11585 "guestfs_max_disks".
11586 On error this function returns -1.
11588 (Added in 1.19.15)
11590 guestfs_ntfs_3g_probe
11592 int
11593 guestfs_ntfs_3g_probe (guestfs_h *g,
11594 int rw,
11595 const char *device);
11596 This command runs the ntfs-3g.probe(8) command which probes an NTFS
11598 "device" for mountability. (Not all NTFS volumes can be mounted read-
11599 write, and some cannot be mounted at all).
11600 "rw" is a boolean flag. Set it to true if you want to test if the
11602 volume can be mounted read-write. Set it to false if you want to test
11603 if the volume can be mounted read-only.
11604 The return value is an integer which 0 if the operation would succeed,
11606 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
11607 On error this function returns -1.
11609 This function depends on the feature "ntfs3g". See also
11611 "guestfs_feature_available".
11612 (Added in 1.0.43)
11614 guestfs_ntfscat_i
11616 int
11617 guestfs_ntfscat_i (guestfs_h *g,
11618 const char *device,
11619 int64_t inode,
11620 const char *filename);
11621 Download a file given its inode from a NTFS filesystem and save it as
11623 filename on the local machine.
11624 This allows to download some otherwise inaccessible files such as the
11626 ones within the $Extend folder.
11627 The filesystem from which to extract the file must be unmounted,
11629 otherwise the call will fail.
11630 This function returns 0 on success or -1 on error.
11632 This long-running command can generate progress notification messages
11634 so that the caller can display a progress bar or indicator. To receive
11635 these messages, the caller must register a progress event callback.
11636 See "GUESTFS_EVENT_PROGRESS".
11637 (Added in 1.33.14)
11639 guestfs_ntfsclone_in
11641 int
11642 guestfs_ntfsclone_in (guestfs_h *g,
11643 const char *backupfile,
11644 const char *device);
11645 Restore the "backupfile" (from a previous call to
11647 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
11648 of this device.
11649 This function returns 0 on success or -1 on error.
11651 This function depends on the feature "ntfs3g". See also
11653 "guestfs_feature_available".
11654 (Added in 1.17.9)
11656 guestfs_ntfsclone_out
11658 int
11659 guestfs_ntfsclone_out (guestfs_h *g,
11660 const char *device,
11661 const char *backupfile,
11662 ...);
11663 You may supply a list of optional arguments to this call. Use zero or
11665 more of the following pairs of parameters, and terminate the list with
11666 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11667 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
11669 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
11670 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
11671 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
11672 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
11673 Stream the NTFS filesystem "device" to the local file "backupfile".
11675 The format used for the backup file is a special format used by the
11676 ntfsclone(8) tool.
11677 If the optional "metadataonly" flag is true, then only the metadata is
11679 saved, losing all the user data (this is useful for diagnosing some
11680 filesystem problems).
11681 The optional "rescue", "ignorefscheck", "preservetimestamps" and
11683 "force" flags have precise meanings detailed in the ntfsclone(8) man
11684 page.
11685 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
11687 device.
11688 This function returns 0 on success or -1 on error.
11690 This function depends on the feature "ntfs3g". See also
11692 "guestfs_feature_available".
11693 (Added in 1.17.9)
11695 guestfs_ntfsclone_out_va
11697 int
11698 guestfs_ntfsclone_out_va (guestfs_h *g,
11699 const char *device,
11700 const char *backupfile,
11701 va_list args);
11702 This is the "va_list variant" of "guestfs_ntfsclone_out".
11704 See "CALLS WITH OPTIONAL ARGUMENTS".
11706 guestfs_ntfsclone_out_argv
11708 int
11709 guestfs_ntfsclone_out_argv (guestfs_h *g,
11710 const char *device,
11711 const char *backupfile,
11712 const struct guestfs_ntfsclone_out_argv *optargs);
11713 This is the "argv variant" of "guestfs_ntfsclone_out".
11715 See "CALLS WITH OPTIONAL ARGUMENTS".
11717 guestfs_ntfsfix
11719 int
11720 guestfs_ntfsfix (guestfs_h *g,
11721 const char *device,
11722 ...);
11723 You may supply a list of optional arguments to this call. Use zero or
11725 more of the following pairs of parameters, and terminate the list with
11726 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11727 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
11729 This command repairs some fundamental NTFS inconsistencies, resets the
11731 NTFS journal file, and schedules an NTFS consistency check for the
11732 first boot into Windows.
11733 This is not an equivalent of Windows "chkdsk". It does not scan the
11735 filesystem for inconsistencies.
11736 The optional "clearbadsectors" flag clears the list of bad sectors.
11738 This is useful after cloning a disk with bad sectors to a new disk.
11739 This function returns 0 on success or -1 on error.
11741 This function depends on the feature "ntfs3g". See also
11743 "guestfs_feature_available".
11744 (Added in 1.17.9)
11746 guestfs_ntfsfix_va
11748 int
11749 guestfs_ntfsfix_va (guestfs_h *g,
11750 const char *device,
11751 va_list args);
11752 This is the "va_list variant" of "guestfs_ntfsfix".
11754 See "CALLS WITH OPTIONAL ARGUMENTS".
11756 guestfs_ntfsfix_argv
11758 int
11759 guestfs_ntfsfix_argv (guestfs_h *g,
11760 const char *device,
11761 const struct guestfs_ntfsfix_argv *optargs);
11762 This is the "argv variant" of "guestfs_ntfsfix".
11764 See "CALLS WITH OPTIONAL ARGUMENTS".
11766 guestfs_ntfsresize
11768 int
11769 guestfs_ntfsresize (guestfs_h *g,
11770 const char *device);
11771 This function is provided for backwards compatibility with earlier
11773 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
11774 no optional arguments.
11775 (Added in 1.3.2)
11777 guestfs_ntfsresize_opts
11779 int
11780 guestfs_ntfsresize_opts (guestfs_h *g,
11781 const char *device,
11782 ...);
11783 You may supply a list of optional arguments to this call. Use zero or
11785 more of the following pairs of parameters, and terminate the list with
11786 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11787 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
11789 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
11790 This command resizes an NTFS filesystem, expanding or shrinking it to
11792 the size of the underlying device.
11793 The optional parameters are:
11795 "size"
11797 The new size (in bytes) of the filesystem. If omitted, the
11798 filesystem is resized to fit the container (eg. partition).
11799 "force"
11801 If this option is true, then force the resize of the filesystem
11802 even if the filesystem is marked as requiring a consistency check.
11803 After the resize operation, the filesystem is always marked as
11805 requiring a consistency check (for safety). You have to boot into
11806 Windows to perform this check and clear this condition. If you
11807 don't set the "force" option then it is not possible to call
11808 "guestfs_ntfsresize" multiple times on a single filesystem without
11809 booting into Windows between each resize.
11810 See also ntfsresize(8).
11812 This function returns 0 on success or -1 on error.
11814 This function depends on the feature "ntfsprogs". See also
11816 "guestfs_feature_available".
11817 (Added in 1.3.2)
11819 guestfs_ntfsresize_opts_va
11821 int
11822 guestfs_ntfsresize_opts_va (guestfs_h *g,
11823 const char *device,
11824 va_list args);
11825 This is the "va_list variant" of "guestfs_ntfsresize_opts".
11827 See "CALLS WITH OPTIONAL ARGUMENTS".
11829 guestfs_ntfsresize_opts_argv
11831 int
11832 guestfs_ntfsresize_opts_argv (guestfs_h *g,
11833 const char *device,
11834 const struct guestfs_ntfsresize_opts_argv *optargs);
11835 This is the "argv variant" of "guestfs_ntfsresize_opts".
11837 See "CALLS WITH OPTIONAL ARGUMENTS".
11839 guestfs_ntfsresize_size
11841 int
11842 guestfs_ntfsresize_size (guestfs_h *g,
11843 const char *device,
11844 int64_t size);
11845 This function is deprecated. In new code, use the "guestfs_ntfsresize"
11847 call instead.
11848 Deprecated functions will not be removed from the API, but the fact
11850 that they are deprecated indicates that there are problems with correct
11851 use of these functions.
11852 This command is the same as "guestfs_ntfsresize" except that it allows
11854 you to specify the new size (in bytes) explicitly.
11855 This function returns 0 on success or -1 on error.
11857 This function depends on the feature "ntfsprogs". See also
11859 "guestfs_feature_available".
11860 (Added in 1.3.14)
11862 guestfs_parse_environment
11864 int
11865 guestfs_parse_environment (guestfs_h *g);
11866 Parse the program’s environment and set flags in the handle
11868 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
11869 flag is set in the handle.
11870 Most programs do not need to call this. It is done implicitly when you
11872 call "guestfs_create".
11873 See "ENVIRONMENT VARIABLES" for a list of environment variables that
11875 can affect libguestfs handles. See also "guestfs_create_flags", and
11876 "guestfs_parse_environment_list".
11877 This function returns 0 on success or -1 on error.
11879 (Added in 1.19.53)
11881 guestfs_parse_environment_list
11883 int
11884 guestfs_parse_environment_list (guestfs_h *g,
11885 char *const *environment);
11886 Parse the list of strings in the argument "environment" and set flags
11888 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
11889 string in the list, then the ‘verbose’ flag is set in the handle.
11890 This is the same as "guestfs_parse_environment" except that it parses
11892 an explicit list of strings instead of the program's environment.
11893 This function returns 0 on success or -1 on error.
11895 (Added in 1.19.53)
11897 guestfs_part_add
11899 int
11900 guestfs_part_add (guestfs_h *g,
11901 const char *device,
11902 const char *prlogex,
11903 int64_t startsect,
11904 int64_t endsect);
11905 This command adds a partition to "device". If there is no partition
11907 table on the device, call "guestfs_part_init" first.
11908 The "prlogex" parameter is the type of partition. Normally you should
11910 pass "p" or "primary" here, but MBR partition tables also support "l"
11911 (or "logical") and "e" (or "extended") partition types.
11912 "startsect" and "endsect" are the start and end of the partition in
11914 sectors. "endsect" may be negative, which means it counts backwards
11915 from the end of the disk ("-1" is the last sector).
11916 Creating a partition which covers the whole disk is not so easy. Use
11918 "guestfs_part_disk" to do that.
11919 This function returns 0 on success or -1 on error.
11921 (Added in 1.0.78)
11923 guestfs_part_del
11925 int
11926 guestfs_part_del (guestfs_h *g,
11927 const char *device,
11928 int partnum);
11929 This command deletes the partition numbered "partnum" on "device".
11931 Note that in the case of MBR partitioning, deleting an extended
11933 partition also deletes any logical partitions it contains.
11934 This function returns 0 on success or -1 on error.
11936 (Added in 1.3.2)
11938 guestfs_part_disk
11940 int
11941 guestfs_part_disk (guestfs_h *g,
11942 const char *device,
11943 const char *parttype);
11944 This command is simply a combination of "guestfs_part_init" followed by
11946 "guestfs_part_add" to create a single primary partition covering the
11947 whole disk.
11948 "parttype" is the partition table type, usually "mbr" or "gpt", but
11950 other possible values are described in "guestfs_part_init".
11951 This function returns 0 on success or -1 on error.
11953 (Added in 1.0.78)
11955 guestfs_part_expand_gpt
11957 int
11958 guestfs_part_expand_gpt (guestfs_h *g,
11959 const char *device);
11960 Move backup GPT data structures to the end of the disk. This is useful
11962 in case of in-place image expand since disk space after backup GPT
11963 header is not usable. This is equivalent to "sgdisk -e".
11964 See also sgdisk(8).
11966 This function returns 0 on success or -1 on error.
11968 This function depends on the feature "gdisk". See also
11970 "guestfs_feature_available".
11971 (Added in 1.33.2)
11973 guestfs_part_get_bootable
11975 int
11976 guestfs_part_get_bootable (guestfs_h *g,
11977 const char *device,
11978 int partnum);
11979 This command returns true if the partition "partnum" on "device" has
11981 the bootable flag set.
11982 See also "guestfs_part_set_bootable".
11984 This function returns a C truth value on success or -1 on error.
11986 (Added in 1.3.2)
11988 guestfs_part_get_disk_guid
11990 char *
11991 guestfs_part_get_disk_guid (guestfs_h *g,
11992 const char *device);
11993 Return the disk identifier (GUID) of a GPT-partitioned "device".
11995 Behaviour is undefined for other partition types.
11996 This function returns a string, or NULL on error. The caller must free
11998 the returned string after use.
11999 This function depends on the feature "gdisk". See also
12001 "guestfs_feature_available".
12002 (Added in 1.33.2)
12004 guestfs_part_get_gpt_attributes
12006 int64_t
12007 guestfs_part_get_gpt_attributes (guestfs_h *g,
12008 const char *device,
12009 int partnum);
12010 Return the attribute flags of numbered GPT partition "partnum". An
12012 error is returned for MBR partitions.
12013 On error this function returns -1.
12015 This function depends on the feature "gdisk". See also
12017 "guestfs_feature_available".
12018 (Added in 1.21.1)
12020 guestfs_part_get_gpt_guid
12022 char *
12023 guestfs_part_get_gpt_guid (guestfs_h *g,
12024 const char *device,
12025 int partnum);
12026 Return the GUID of numbered GPT partition "partnum".
12028 This function returns a string, or NULL on error. The caller must free
12030 the returned string after use.
12031 This function depends on the feature "gdisk". See also
12033 "guestfs_feature_available".
12034 (Added in 1.29.25)
12036 guestfs_part_get_gpt_type
12038 char *
12039 guestfs_part_get_gpt_type (guestfs_h *g,
12040 const char *device,
12041 int partnum);
12042 Return the type GUID of numbered GPT partition "partnum". For MBR
12044 partitions, return an appropriate GUID corresponding to the MBR type.
12045 Behaviour is undefined for other partition types.
12046 This function returns a string, or NULL on error. The caller must free
12048 the returned string after use.
12049 This function depends on the feature "gdisk". See also
12051 "guestfs_feature_available".
12052 (Added in 1.21.1)
12054 guestfs_part_get_mbr_id
12056 int
12057 guestfs_part_get_mbr_id (guestfs_h *g,
12058 const char *device,
12059 int partnum);
12060 Returns the MBR type byte (also known as the ID byte) from the numbered
12062 partition "partnum".
12063 Note that only MBR (old DOS-style) partitions have type bytes. You
12065 will get undefined results for other partition table types (see
12066 "guestfs_part_get_parttype").
12067 On error this function returns -1.
12069 (Added in 1.3.2)
12071 guestfs_part_get_mbr_part_type
12073 char *
12074 guestfs_part_get_mbr_part_type (guestfs_h *g,
12075 const char *device,
12076 int partnum);
12077 This returns the partition type of an MBR partition numbered "partnum"
12079 on device "device".
12080 It returns "primary", "logical", or "extended".
12082 This function returns a string, or NULL on error. The caller must free
12084 the returned string after use.
12085 (Added in 1.29.32)
12087 guestfs_part_get_name
12089 char *
12090 guestfs_part_get_name (guestfs_h *g,
12091 const char *device,
12092 int partnum);
12093 This gets the partition name on partition numbered "partnum" on device
12095 "device". Note that partitions are numbered from 1.
12096 The partition name can only be read on certain types of partition
12098 table. This works on "gpt" but not on "mbr" partitions.
12099 This function returns a string, or NULL on error. The caller must free
12101 the returned string after use.
12102 (Added in 1.25.33)
12104 guestfs_part_get_parttype
12106 char *
12107 guestfs_part_get_parttype (guestfs_h *g,
12108 const char *device);
12109 This command examines the partition table on "device" and returns the
12111 partition table type (format) being used.
12112 Common return values include: "msdos" (a DOS/Windows style MBR
12114 partition table), "gpt" (a GPT/EFI-style partition table). Other
12115 values are possible, although unusual. See "guestfs_part_init" for a
12116 full list.
12117 This function returns a string, or NULL on error. The caller must free
12119 the returned string after use.
12120 (Added in 1.0.78)
12122 guestfs_part_init
12124 int
12125 guestfs_part_init (guestfs_h *g,
12126 const char *device,
12127 const char *parttype);
12128 This creates an empty partition table on "device" of one of the
12130 partition types listed below. Usually "parttype" should be either
12131 "msdos" or "gpt" (for large disks).
12132 Initially there are no partitions. Following this, you should call
12134 "guestfs_part_add" for each partition required.
12135 Possible values for "parttype" are:
12137 efi
12139 gpt Intel EFI / GPT partition table.
12140 This is recommended for >= 2 TB partitions that will be accessed
12142 from Linux and Intel-based Mac OS X. It also has limited backwards
12143 compatibility with the "mbr" format.
12144 mbr
12146 msdos
12147 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12148 and Windows. This partition type will only work for device sizes
12149 up to 2 TB. For large disks we recommend using "gpt".
12150 Other partition table types that may work but are not supported
12152 include:
12153 aix AIX disk labels.
12155 amiga
12157 rdb Amiga "Rigid Disk Block" format.
12158 bsd BSD disk labels.
12160 dasd
12162 DASD, used on IBM mainframes.
12163 dvh MIPS/SGI volumes.
12165 mac Old Mac partition format. Modern Macs use "gpt".
12167 pc98
12169 NEC PC-98 format, common in Japan apparently.
12170 sun Sun disk labels.
12172 This function returns 0 on success or -1 on error.
12174 (Added in 1.0.78)
12176 guestfs_part_list
12178 struct guestfs_partition_list *
12179 guestfs_part_list (guestfs_h *g,
12180 const char *device);
12181 This command parses the partition table on "device" and returns the
12183 list of partitions found.
12184 The fields in the returned structure are:
12186 part_num
12188 Partition number, counting from 1.
12189 part_start
12191 Start of the partition in bytes. To get sectors you have to divide
12192 by the device’s sector size, see "guestfs_blockdev_getss".
12193 part_end
12195 End of the partition in bytes.
12196 part_size
12198 Size of the partition in bytes.
12199 This function returns a "struct guestfs_partition_list *", or NULL if
12201 there was an error. The caller must call "guestfs_free_partition_list"
12202 after use.
12203 (Added in 1.0.78)
12205 guestfs_part_resize
12207 int
12208 guestfs_part_resize (guestfs_h *g,
12209 const char *device,
12210 int partnum,
12211 int64_t endsect);
12212 This command resizes the partition numbered "partnum" on "device" by
12214 moving the end position.
12215 Note that this does not modify any filesystem present in the partition.
12217 If you wish to do this, you will need to use filesystem resizing
12218 commands like "guestfs_resize2fs".
12219 When growing a partition you will want to grow the filesystem
12221 afterwards, but when shrinking, you need to shrink the filesystem
12222 before the partition.
12223 This function returns 0 on success or -1 on error.
12225 (Added in 1.37.20)
12227 guestfs_part_set_bootable
12229 int
12230 guestfs_part_set_bootable (guestfs_h *g,
12231 const char *device,
12232 int partnum,
12233 int bootable);
12234 This sets the bootable flag on partition numbered "partnum" on device
12236 "device". Note that partitions are numbered from 1.
12237 The bootable flag is used by some operating systems (notably Windows)
12239 to determine which partition to boot from. It is by no means
12240 universally recognized.
12241 This function returns 0 on success or -1 on error.
12243 (Added in 1.0.78)
12245 guestfs_part_set_disk_guid
12247 int
12248 guestfs_part_set_disk_guid (guestfs_h *g,
12249 const char *device,
12250 const char *guid);
12251 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12253 Return an error if the partition table of "device" isn't GPT, or if
12254 "guid" is not a valid GUID.
12255 This function returns 0 on success or -1 on error.
12257 This function depends on the feature "gdisk". See also
12259 "guestfs_feature_available".
12260 (Added in 1.33.2)
12262 guestfs_part_set_disk_guid_random
12264 int
12265 guestfs_part_set_disk_guid_random (guestfs_h *g,
12266 const char *device);
12267 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12269 randomly generated value. Return an error if the partition table of
12270 "device" isn't GPT.
12271 This function returns 0 on success or -1 on error.
12273 This function depends on the feature "gdisk". See also
12275 "guestfs_feature_available".
12276 (Added in 1.33.2)
12278 guestfs_part_set_gpt_attributes
12280 int
12281 guestfs_part_set_gpt_attributes (guestfs_h *g,
12282 const char *device,
12283 int partnum,
12284 int64_t attributes);
12285 Set the attribute flags of numbered GPT partition "partnum" to
12287 "attributes". Return an error if the partition table of "device" isn't
12288 GPT.
12289 See
12291 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12292 for a useful list of partition attributes.
12293 This function returns 0 on success or -1 on error.
12295 This function depends on the feature "gdisk". See also
12297 "guestfs_feature_available".
12298 (Added in 1.21.1)
12300 guestfs_part_set_gpt_guid
12302 int
12303 guestfs_part_set_gpt_guid (guestfs_h *g,
12304 const char *device,
12305 int partnum,
12306 const char *guid);
12307 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12309 error if the partition table of "device" isn't GPT, or if "guid" is not
12310 a valid GUID.
12311 This function returns 0 on success or -1 on error.
12313 This function depends on the feature "gdisk". See also
12315 "guestfs_feature_available".
12316 (Added in 1.29.25)
12318 guestfs_part_set_gpt_type
12320 int
12321 guestfs_part_set_gpt_type (guestfs_h *g,
12322 const char *device,
12323 int partnum,
12324 const char *guid);
12325 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12327 an error if the partition table of "device" isn't GPT, or if "guid" is
12328 not a valid GUID.
12329 See
12331 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12332 for a useful list of type GUIDs.
12333 This function returns 0 on success or -1 on error.
12335 This function depends on the feature "gdisk". See also
12337 "guestfs_feature_available".
12338 (Added in 1.21.1)
12340 guestfs_part_set_mbr_id
12342 int
12343 guestfs_part_set_mbr_id (guestfs_h *g,
12344 const char *device,
12345 int partnum,
12346 int idbyte);
12347 Sets the MBR type byte (also known as the ID byte) of the numbered
12349 partition "partnum" to "idbyte". Note that the type bytes quoted in
12350 most documentation are in fact hexadecimal numbers, but usually
12351 documented without any leading "0x" which might be confusing.
12352 Note that only MBR (old DOS-style) partitions have type bytes. You
12354 will get undefined results for other partition table types (see
12355 "guestfs_part_get_parttype").
12356 This function returns 0 on success or -1 on error.
12358 (Added in 1.3.2)
12360 guestfs_part_set_name
12362 int
12363 guestfs_part_set_name (guestfs_h *g,
12364 const char *device,
12365 int partnum,
12366 const char *name);
12367 This sets the partition name on partition numbered "partnum" on device
12369 "device". Note that partitions are numbered from 1.
12370 The partition name can only be set on certain types of partition table.
12372 This works on "gpt" but not on "mbr" partitions.
12373 This function returns 0 on success or -1 on error.
12375 (Added in 1.0.78)
12377 guestfs_part_to_dev
12379 char *
12380 guestfs_part_to_dev (guestfs_h *g,
12381 const char *partition);
12382 This function takes a partition name (eg. "/dev/sdb1") and removes the
12384 partition number, returning the device name (eg. "/dev/sdb").
12385 The named partition must exist, for example as a string returned from
12387 "guestfs_list_partitions".
12388 See also "guestfs_part_to_partnum", "guestfs_device_index".
12390 This function returns a string, or NULL on error. The caller must free
12392 the returned string after use.
12393 (Added in 1.5.15)
12395 guestfs_part_to_partnum
12397 int
12398 guestfs_part_to_partnum (guestfs_h *g,
12399 const char *partition);
12400 This function takes a partition name (eg. "/dev/sdb1") and returns the
12402 partition number (eg. 1).
12403 The named partition must exist, for example as a string returned from
12405 "guestfs_list_partitions".
12406 See also "guestfs_part_to_dev".
12408 On error this function returns -1.
12410 (Added in 1.13.25)
12412 guestfs_ping_daemon
12414 int
12415 guestfs_ping_daemon (guestfs_h *g);
12416 This is a test probe into the guestfs daemon running inside the
12418 libguestfs appliance. Calling this function checks that the daemon
12419 responds to the ping message, without affecting the daemon or attached
12420 block device(s) in any other way.
12421 This function returns 0 on success or -1 on error.
12423 (Added in 1.0.18)
12425 guestfs_pread
12427 char *
12428 guestfs_pread (guestfs_h *g,
12429 const char *path,
12430 int count,
12431 int64_t offset,
12432 size_t *size_r);
12433 This command lets you read part of a file. It reads "count" bytes of
12435 the file, starting at "offset", from file "path".
12436 This may read fewer bytes than requested. For further details see the
12438 pread(2) system call.
12439 See also "guestfs_pwrite", "guestfs_pread_device".
12441 This function returns a buffer, or NULL on error. The size of the
12443 returned buffer is written to *size_r. The caller must free the
12444 returned buffer after use.
12445 Because of the message protocol, there is a transfer limit of somewhere
12447 between 2MB and 4MB. See "PROTOCOL LIMITS".
12448 (Added in 1.0.77)
12450 guestfs_pread_device
12452 char *
12453 guestfs_pread_device (guestfs_h *g,
12454 const char *device,
12455 int count,
12456 int64_t offset,
12457 size_t *size_r);
12458 This command lets you read part of a block device. It reads "count"
12460 bytes of "device", starting at "offset".
12461 This may read fewer bytes than requested. For further details see the
12463 pread(2) system call.
12464 See also "guestfs_pread".
12466 This function returns a buffer, or NULL on error. The size of the
12468 returned buffer is written to *size_r. The caller must free the
12469 returned buffer after use.
12470 Because of the message protocol, there is a transfer limit of somewhere
12472 between 2MB and 4MB. See "PROTOCOL LIMITS".
12473 (Added in 1.5.21)
12475 guestfs_pvchange_uuid
12477 int
12478 guestfs_pvchange_uuid (guestfs_h *g,
12479 const char *device);
12480 Generate a new random UUID for the physical volume "device".
12482 This function returns 0 on success or -1 on error.
12484 This function depends on the feature "lvm2". See also
12486 "guestfs_feature_available".
12487 (Added in 1.19.26)
12489 guestfs_pvchange_uuid_all
12491 int
12492 guestfs_pvchange_uuid_all (guestfs_h *g);
12493 Generate new random UUIDs for all physical volumes.
12495 This function returns 0 on success or -1 on error.
12497 This function depends on the feature "lvm2". See also
12499 "guestfs_feature_available".
12500 (Added in 1.19.26)
12502 guestfs_pvcreate
12504 int
12505 guestfs_pvcreate (guestfs_h *g,
12506 const char *device);
12507 This creates an LVM physical volume on the named "device", where
12509 "device" should usually be a partition name such as /dev/sda1.
12510 This function returns 0 on success or -1 on error.
12512 This function depends on the feature "lvm2". See also
12514 "guestfs_feature_available".
12515 (Added in 0.8)
12517 guestfs_pvremove
12519 int
12520 guestfs_pvremove (guestfs_h *g,
12521 const char *device);
12522 This wipes a physical volume "device" so that LVM will no longer
12524 recognise it.
12525 The implementation uses the "pvremove" command which refuses to wipe
12527 physical volumes that contain any volume groups, so you have to remove
12528 those first.
12529 This function returns 0 on success or -1 on error.
12531 This function depends on the feature "lvm2". See also
12533 "guestfs_feature_available".
12534 (Added in 1.0.13)
12536 guestfs_pvresize
12538 int
12539 guestfs_pvresize (guestfs_h *g,
12540 const char *device);
12541 This resizes (expands or shrinks) an existing LVM physical volume to
12543 match the new size of the underlying device.
12544 This function returns 0 on success or -1 on error.
12546 This function depends on the feature "lvm2". See also
12548 "guestfs_feature_available".
12549 (Added in 1.0.26)
12551 guestfs_pvresize_size
12553 int
12554 guestfs_pvresize_size (guestfs_h *g,
12555 const char *device,
12556 int64_t size);
12557 This command is the same as "guestfs_pvresize" except that it allows
12559 you to specify the new size (in bytes) explicitly.
12560 This function returns 0 on success or -1 on error.
12562 This function depends on the feature "lvm2". See also
12564 "guestfs_feature_available".
12565 (Added in 1.3.14)
12567 guestfs_pvs
12569 char **
12570 guestfs_pvs (guestfs_h *g);
12571 List all the physical volumes detected. This is the equivalent of the
12573 pvs(8) command.
12574 This returns a list of just the device names that contain PVs (eg.
12576 /dev/sda2).
12577 See also "guestfs_pvs_full".
12579 This function returns a NULL-terminated array of strings (like
12581 environ(3)), or NULL if there was an error. The caller must free the
12582 strings and the array after use.
12583 This function depends on the feature "lvm2". See also
12585 "guestfs_feature_available".
12586 (Added in 0.4)
12588 guestfs_pvs_full
12590 struct guestfs_lvm_pv_list *
12591 guestfs_pvs_full (guestfs_h *g);
12592 List all the physical volumes detected. This is the equivalent of the
12594 pvs(8) command. The "full" version includes all fields.
12595 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
12597 there was an error. The caller must call "guestfs_free_lvm_pv_list"
12598 after use.
12599 This function depends on the feature "lvm2". See also
12601 "guestfs_feature_available".
12602 (Added in 0.4)
12604 guestfs_pvuuid
12606 char *
12607 guestfs_pvuuid (guestfs_h *g,
12608 const char *device);
12609 This command returns the UUID of the LVM PV "device".
12611 This function returns a string, or NULL on error. The caller must free
12613 the returned string after use.
12614 (Added in 1.0.87)
12616 guestfs_pwrite
12618 int
12619 guestfs_pwrite (guestfs_h *g,
12620 const char *path,
12621 const char *content,
12622 size_t content_size,
12623 int64_t offset);
12624 This command writes to part of a file. It writes the data buffer
12626 "content" to the file "path" starting at offset "offset".
12627 This command implements the pwrite(2) system call, and like that system
12629 call it may not write the full data requested. The return value is the
12630 number of bytes that were actually written to the file. This could
12631 even be 0, although short writes are unlikely for regular files in
12632 ordinary circumstances.
12633 See also "guestfs_pread", "guestfs_pwrite_device".
12635 On error this function returns -1.
12637 Because of the message protocol, there is a transfer limit of somewhere
12639 between 2MB and 4MB. See "PROTOCOL LIMITS".
12640 (Added in 1.3.14)
12642 guestfs_pwrite_device
12644 int
12645 guestfs_pwrite_device (guestfs_h *g,
12646 const char *device,
12647 const char *content,
12648 size_t content_size,
12649 int64_t offset);
12650 This command writes to part of a device. It writes the data buffer
12652 "content" to "device" starting at offset "offset".
12653 This command implements the pwrite(2) system call, and like that system
12655 call it may not write the full data requested (although short writes to
12656 disk devices and partitions are probably impossible with standard Linux
12657 kernels).
12658 See also "guestfs_pwrite".
12660 On error this function returns -1.
12662 Because of the message protocol, there is a transfer limit of somewhere
12664 between 2MB and 4MB. See "PROTOCOL LIMITS".
12665 (Added in 1.5.20)
12667 guestfs_read_file
12669 char *
12670 guestfs_read_file (guestfs_h *g,
12671 const char *path,
12672 size_t *size_r);
12673 This calls returns the contents of the file "path" as a buffer.
12675 Unlike "guestfs_cat", this function can correctly handle files that
12677 contain embedded ASCII NUL characters.
12678 This function returns a buffer, or NULL on error. The size of the
12680 returned buffer is written to *size_r. The caller must free the
12681 returned buffer after use.
12682 (Added in 1.0.63)
12684 guestfs_read_lines
12686 char **
12687 guestfs_read_lines (guestfs_h *g,
12688 const char *path);
12689 Return the contents of the file named "path".
12691 The file contents are returned as a list of lines. Trailing "LF" and
12693 "CRLF" character sequences are not returned.
12694 Note that this function cannot correctly handle binary files
12696 (specifically, files containing "\0" character which is treated as end
12697 of string). For those you need to use the "guestfs_read_file" function
12698 and split the buffer into lines yourself.
12699 This function returns a NULL-terminated array of strings (like
12701 environ(3)), or NULL if there was an error. The caller must free the
12702 strings and the array after use.
12703 (Added in 0.7)
12705 guestfs_readdir
12707 struct guestfs_dirent_list *
12708 guestfs_readdir (guestfs_h *g,
12709 const char *dir);
12710 This returns the list of directory entries in directory "dir".
12712 All entries in the directory are returned, including "." and "..". The
12714 entries are not sorted, but returned in the same order as the
12715 underlying filesystem.
12716 Also this call returns basic file type information about each file.
12718 The "ftyp" field will contain one of the following characters:
12719 'b' Block special
12721 'c' Char special
12723 'd' Directory
12725 'f' FIFO (named pipe)
12727 'l' Symbolic link
12729 'r' Regular file
12731 's' Socket
12733 'u' Unknown file type
12735 '?' The readdir(3) call returned a "d_type" field with an unexpected
12737 value
12738 This function is primarily intended for use by programs. To get a
12740 simple list of names, use "guestfs_ls". To get a printable directory
12741 for human consumption, use "guestfs_ll".
12742 This function returns a "struct guestfs_dirent_list *", or NULL if
12744 there was an error. The caller must call "guestfs_free_dirent_list"
12745 after use.
12746 Because of the message protocol, there is a transfer limit of somewhere
12748 between 2MB and 4MB. See "PROTOCOL LIMITS".
12749 (Added in 1.0.55)
12751 guestfs_readlink
12753 char *
12754 guestfs_readlink (guestfs_h *g,
12755 const char *path);
12756 This command reads the target of a symbolic link.
12758 This function returns a string, or NULL on error. The caller must free
12760 the returned string after use.
12761 (Added in 1.0.66)
12763 guestfs_readlinklist
12765 char **
12766 guestfs_readlinklist (guestfs_h *g,
12767 const char *path,
12768 char *const *names);
12769 This call allows you to do a "readlink" operation on multiple files,
12771 where all files are in the directory "path". "names" is the list of
12772 files from this directory.
12773 On return you get a list of strings, with a one-to-one correspondence
12775 to the "names" list. Each string is the value of the symbolic link.
12776 If the readlink(2) operation fails on any name, then the corresponding
12778 result string is the empty string "". However the whole operation is
12779 completed even if there were readlink(2) errors, and so you can call
12780 this function with names where you don't know if they are symbolic
12781 links already (albeit slightly less efficient).
12782 This call is intended for programs that want to efficiently list a
12784 directory contents without making many round-trips.
12785 This function returns a NULL-terminated array of strings (like
12787 environ(3)), or NULL if there was an error. The caller must free the
12788 strings and the array after use.
12789 (Added in 1.0.77)
12791 guestfs_realpath
12793 char *
12794 guestfs_realpath (guestfs_h *g,
12795 const char *path);
12796 Return the canonicalized absolute pathname of "path". The returned
12798 path has no ".", ".." or symbolic link path elements.
12799 This function returns a string, or NULL on error. The caller must free
12801 the returned string after use.
12802 (Added in 1.0.66)
12804 guestfs_remount
12806 int
12807 guestfs_remount (guestfs_h *g,
12808 const char *mountpoint,
12809 ...);
12810 You may supply a list of optional arguments to this call. Use zero or
12812 more of the following pairs of parameters, and terminate the list with
12813 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12814 GUESTFS_REMOUNT_RW, int rw,
12816 This call allows you to change the "rw" (readonly/read-write) flag on
12818 an already mounted filesystem at "mountpoint", converting a readonly
12819 filesystem to be read-write, or vice-versa.
12820 Note that at the moment you must supply the "optional" "rw" parameter.
12822 In future we may allow other flags to be adjusted.
12823 This function returns 0 on success or -1 on error.
12825 (Added in 1.23.2)
12827 guestfs_remount_va
12829 int
12830 guestfs_remount_va (guestfs_h *g,
12831 const char *mountpoint,
12832 va_list args);
12833 This is the "va_list variant" of "guestfs_remount".
12835 See "CALLS WITH OPTIONAL ARGUMENTS".
12837 guestfs_remount_argv
12839 int
12840 guestfs_remount_argv (guestfs_h *g,
12841 const char *mountpoint,
12842 const struct guestfs_remount_argv *optargs);
12843 This is the "argv variant" of "guestfs_remount".
12845 See "CALLS WITH OPTIONAL ARGUMENTS".
12847 guestfs_remove_drive
12849 int
12850 guestfs_remove_drive (guestfs_h *g,
12851 const char *label);
12852 This function is conceptually the opposite of "guestfs_add_drive_opts".
12854 It removes the drive that was previously added with label "label".
12855 Note that in order to remove drives, you have to add them with labels
12857 (see the optional "label" argument to "guestfs_add_drive_opts"). If
12858 you didn't use a label, then they cannot be removed.
12859 You can call this function before or after launching the handle. If
12861 called after launch, if the backend supports it, we try to hot unplug
12862 the drive: see "HOTPLUGGING". The disk must not be in use (eg.
12863 mounted) when you do this. We try to detect if the disk is in use and
12864 stop you from doing this.
12865 This function returns 0 on success or -1 on error.
12867 (Added in 1.19.49)
12869 guestfs_removexattr
12871 int
12872 guestfs_removexattr (guestfs_h *g,
12873 const char *xattr,
12874 const char *path);
12875 This call removes the extended attribute named "xattr" of the file
12877 "path".
12878 See also: "guestfs_lremovexattr", attr(5).
12880 This function returns 0 on success or -1 on error.
12882 This function depends on the feature "linuxxattrs". See also
12884 "guestfs_feature_available".
12885 (Added in 1.0.59)
12887 guestfs_rename
12889 int
12890 guestfs_rename (guestfs_h *g,
12891 const char *oldpath,
12892 const char *newpath);
12893 Rename a file to a new place on the same filesystem. This is the same
12895 as the Linux rename(2) system call. In most cases you are better to
12896 use "guestfs_mv" instead.
12897 This function returns 0 on success or -1 on error.
12899 (Added in 1.21.5)
12901 guestfs_resize2fs
12903 int
12904 guestfs_resize2fs (guestfs_h *g,
12905 const char *device);
12906 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
12908 underlying device.
12909 See also "RESIZE2FS ERRORS".
12911 This function returns 0 on success or -1 on error.
12913 (Added in 1.0.27)
12915 guestfs_resize2fs_M
12917 int
12918 guestfs_resize2fs_M (guestfs_h *g,
12919 const char *device);
12920 This command is the same as "guestfs_resize2fs", but the filesystem is
12922 resized to its minimum size. This works like the -M option to the
12923 "resize2fs" command.
12924 To get the resulting size of the filesystem you should call
12926 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
12927 These two numbers, multiplied together, give the resulting size of the
12928 minimal filesystem in bytes.
12929 See also "RESIZE2FS ERRORS".
12931 This function returns 0 on success or -1 on error.
12933 (Added in 1.9.4)
12935 guestfs_resize2fs_size
12937 int
12938 guestfs_resize2fs_size (guestfs_h *g,
12939 const char *device,
12940 int64_t size);
12941 This command is the same as "guestfs_resize2fs" except that it allows
12943 you to specify the new size (in bytes) explicitly.
12944 See also "RESIZE2FS ERRORS".
12946 This function returns 0 on success or -1 on error.
12948 (Added in 1.3.14)
12950 guestfs_rm
12952 int
12953 guestfs_rm (guestfs_h *g,
12954 const char *path);
12955 Remove the single file "path".
12957 This function returns 0 on success or -1 on error.
12959 (Added in 0.8)
12961 guestfs_rm_f
12963 int
12964 guestfs_rm_f (guestfs_h *g,
12965 const char *path);
12966 Remove the file "path".
12968 If the file doesn't exist, that error is ignored. (Other errors, eg.
12970 I/O errors or bad paths, are not ignored)
12971 This call cannot remove directories. Use "guestfs_rmdir" to remove an
12973 empty directory, or "guestfs_rm_rf" to remove directories recursively.
12974 This function returns 0 on success or -1 on error.
12976 (Added in 1.19.42)
12978 guestfs_rm_rf
12980 int
12981 guestfs_rm_rf (guestfs_h *g,
12982 const char *path);
12983 Remove the file or directory "path", recursively removing the contents
12985 if its a directory. This is like the "rm -rf" shell command.
12986 This function returns 0 on success or -1 on error.
12988 (Added in 0.8)
12990 guestfs_rmdir
12992 int
12993 guestfs_rmdir (guestfs_h *g,
12994 const char *path);
12995 Remove the single directory "path".
12997 This function returns 0 on success or -1 on error.
12999 (Added in 0.8)
13001 guestfs_rmmountpoint
13003 int
13004 guestfs_rmmountpoint (guestfs_h *g,
13005 const char *exemptpath);
13006 This call removes a mountpoint that was previously created with
13008 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13009 This function returns 0 on success or -1 on error.
13011 (Added in 1.0.62)
13013 guestfs_rsync
13015 int
13016 guestfs_rsync (guestfs_h *g,
13017 const char *src,
13018 const char *dest,
13019 ...);
13020 You may supply a list of optional arguments to this call. Use zero or
13022 more of the following pairs of parameters, and terminate the list with
13023 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13024 GUESTFS_RSYNC_ARCHIVE, int archive,
13026 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13027 This call may be used to copy or synchronize two directories under the
13029 same libguestfs handle. This uses the rsync(1) program which uses a
13030 fast algorithm that avoids copying files unnecessarily.
13031 "src" and "dest" are the source and destination directories. Files are
13033 copied from "src" to "dest".
13034 The optional arguments are:
13036 "archive"
13038 Turns on archive mode. This is the same as passing the --archive
13039 flag to "rsync".
13040 "deletedest"
13042 Delete files at the destination that do not exist at the source.
13043 This function returns 0 on success or -1 on error.
13045 This function depends on the feature "rsync". See also
13047 "guestfs_feature_available".
13048 (Added in 1.19.29)
13050 guestfs_rsync_va
13052 int
13053 guestfs_rsync_va (guestfs_h *g,
13054 const char *src,
13055 const char *dest,
13056 va_list args);
13057 This is the "va_list variant" of "guestfs_rsync".
13059 See "CALLS WITH OPTIONAL ARGUMENTS".
13061 guestfs_rsync_argv
13063 int
13064 guestfs_rsync_argv (guestfs_h *g,
13065 const char *src,
13066 const char *dest,
13067 const struct guestfs_rsync_argv *optargs);
13068 This is the "argv variant" of "guestfs_rsync".
13070 See "CALLS WITH OPTIONAL ARGUMENTS".
13072 guestfs_rsync_in
13074 int
13075 guestfs_rsync_in (guestfs_h *g,
13076 const char *remote,
13077 const char *dest,
13078 ...);
13079 You may supply a list of optional arguments to this call. Use zero or
13081 more of the following pairs of parameters, and terminate the list with
13082 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13083 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13085 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13086 This call may be used to copy or synchronize the filesystem on the host
13088 or on a remote computer with the filesystem within libguestfs. This
13089 uses the rsync(1) program which uses a fast algorithm that avoids
13090 copying files unnecessarily.
13091 This call only works if the network is enabled. See
13093 "guestfs_set_network" or the --network option to various tools like
13094 guestfish(1).
13095 Files are copied from the remote server and directory specified by
13097 "remote" to the destination directory "dest".
13098 The format of the remote server string is defined by rsync(1). Note
13100 that there is no way to supply a password or passphrase so the target
13101 must be set up not to require one.
13102 The optional arguments are the same as those of "guestfs_rsync".
13104 This function returns 0 on success or -1 on error.
13106 This function depends on the feature "rsync". See also
13108 "guestfs_feature_available".
13109 (Added in 1.19.29)
13111 guestfs_rsync_in_va
13113 int
13114 guestfs_rsync_in_va (guestfs_h *g,
13115 const char *remote,
13116 const char *dest,
13117 va_list args);
13118 This is the "va_list variant" of "guestfs_rsync_in".
13120 See "CALLS WITH OPTIONAL ARGUMENTS".
13122 guestfs_rsync_in_argv
13124 int
13125 guestfs_rsync_in_argv (guestfs_h *g,
13126 const char *remote,
13127 const char *dest,
13128 const struct guestfs_rsync_in_argv *optargs);
13129 This is the "argv variant" of "guestfs_rsync_in".
13131 See "CALLS WITH OPTIONAL ARGUMENTS".
13133 guestfs_rsync_out
13135 int
13136 guestfs_rsync_out (guestfs_h *g,
13137 const char *src,
13138 const char *remote,
13139 ...);
13140 You may supply a list of optional arguments to this call. Use zero or
13142 more of the following pairs of parameters, and terminate the list with
13143 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13144 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13146 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13147 This call may be used to copy or synchronize the filesystem within
13149 libguestfs with a filesystem on the host or on a remote computer. This
13150 uses the rsync(1) program which uses a fast algorithm that avoids
13151 copying files unnecessarily.
13152 This call only works if the network is enabled. See
13154 "guestfs_set_network" or the --network option to various tools like
13155 guestfish(1).
13156 Files are copied from the source directory "src" to the remote server
13158 and directory specified by "remote".
13159 The format of the remote server string is defined by rsync(1). Note
13161 that there is no way to supply a password or passphrase so the target
13162 must be set up not to require one.
13163 The optional arguments are the same as those of "guestfs_rsync".
13165 Globbing does not happen on the "src" parameter. In programs which use
13167 the API directly you have to expand wildcards yourself (see
13168 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13169 (see "glob" in guestfish(1)), for example:
13170 ><fs> glob rsync-out /* rsync://remote/
13172 This function returns 0 on success or -1 on error.
13174 This function depends on the feature "rsync". See also
13176 "guestfs_feature_available".
13177 (Added in 1.19.29)
13179 guestfs_rsync_out_va
13181 int
13182 guestfs_rsync_out_va (guestfs_h *g,
13183 const char *src,
13184 const char *remote,
13185 va_list args);
13186 This is the "va_list variant" of "guestfs_rsync_out".
13188 See "CALLS WITH OPTIONAL ARGUMENTS".
13190 guestfs_rsync_out_argv
13192 int
13193 guestfs_rsync_out_argv (guestfs_h *g,
13194 const char *src,
13195 const char *remote,
13196 const struct guestfs_rsync_out_argv *optargs);
13197 This is the "argv variant" of "guestfs_rsync_out".
13199 See "CALLS WITH OPTIONAL ARGUMENTS".
13201 guestfs_scrub_device
13203 int
13204 guestfs_scrub_device (guestfs_h *g,
13205 const char *device);
13206 This command writes patterns over "device" to make data retrieval more
13208 difficult.
13209 It is an interface to the scrub(1) program. See that manual page for
13211 more details.
13212 This function returns 0 on success or -1 on error.
13214 This function depends on the feature "scrub". See also
13216 "guestfs_feature_available".
13217 (Added in 1.0.52)
13219 guestfs_scrub_file
13221 int
13222 guestfs_scrub_file (guestfs_h *g,
13223 const char *file);
13224 This command writes patterns over a file to make data retrieval more
13226 difficult.
13227 The file is removed after scrubbing.
13229 It is an interface to the scrub(1) program. See that manual page for
13231 more details.
13232 This function returns 0 on success or -1 on error.
13234 This function depends on the feature "scrub". See also
13236 "guestfs_feature_available".
13237 (Added in 1.0.52)
13239 guestfs_scrub_freespace
13241 int
13242 guestfs_scrub_freespace (guestfs_h *g,
13243 const char *dir);
13244 This command creates the directory "dir" and then fills it with files
13246 until the filesystem is full, and scrubs the files as for
13247 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13248 free space on the partition containing "dir".
13249 It is an interface to the scrub(1) program. See that manual page for
13251 more details.
13252 This function returns 0 on success or -1 on error.
13254 This function depends on the feature "scrub". See also
13256 "guestfs_feature_available".
13257 (Added in 1.0.52)
13259 guestfs_selinux_relabel
13261 int
13262 guestfs_selinux_relabel (guestfs_h *g,
13263 const char *specfile,
13264 const char *path,
13265 ...);
13266 You may supply a list of optional arguments to this call. Use zero or
13268 more of the following pairs of parameters, and terminate the list with
13269 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13270 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13272 SELinux relabel parts of the filesystem.
13274 The "specfile" parameter controls the policy spec file used. You have
13276 to parse "/etc/selinux/config" to find the correct SELinux policy and
13277 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13278 "/contexts/files/file_contexts".
13279 The required "path" parameter is the top level directory where
13281 relabelling starts. Normally you should pass "path" as "/" to relabel
13282 the whole guest filesystem.
13283 The optional "force" boolean controls whether the context is reset for
13285 customizable files, and also whether the user, role and range parts of
13286 the file context is changed.
13287 This function returns 0 on success or -1 on error.
13289 This function depends on the feature "selinuxrelabel". See also
13291 "guestfs_feature_available".
13292 (Added in 1.33.43)
13294 guestfs_selinux_relabel_va
13296 int
13297 guestfs_selinux_relabel_va (guestfs_h *g,
13298 const char *specfile,
13299 const char *path,
13300 va_list args);
13301 This is the "va_list variant" of "guestfs_selinux_relabel".
13303 See "CALLS WITH OPTIONAL ARGUMENTS".
13305 guestfs_selinux_relabel_argv
13307 int
13308 guestfs_selinux_relabel_argv (guestfs_h *g,
13309 const char *specfile,
13310 const char *path,
13311 const struct guestfs_selinux_relabel_argv *optargs);
13312 This is the "argv variant" of "guestfs_selinux_relabel".
13314 See "CALLS WITH OPTIONAL ARGUMENTS".
13316 guestfs_set_append
13318 int
13319 guestfs_set_append (guestfs_h *g,
13320 const char *append);
13321 This function is used to add additional options to the libguestfs
13323 appliance kernel command line.
13324 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13326 environment variable.
13327 Setting "append" to "NULL" means no additional options are passed
13329 (libguestfs always adds a few of its own).
13330 This function returns 0 on success or -1 on error.
13332 (Added in 1.0.26)
13334 guestfs_set_attach_method
13336 int
13337 guestfs_set_attach_method (guestfs_h *g,
13338 const char *backend);
13339 This function is deprecated. In new code, use the
13341 "guestfs_set_backend" call instead.
13342 Deprecated functions will not be removed from the API, but the fact
13344 that they are deprecated indicates that there are problems with correct
13345 use of these functions.
13346 Set the method that libguestfs uses to connect to the backend guestfsd
13348 daemon.
13349 See "BACKEND".
13351 This function returns 0 on success or -1 on error.
13353 (Added in 1.9.8)
13355 guestfs_set_autosync
13357 int
13358 guestfs_set_autosync (guestfs_h *g,
13359 int autosync);
13360 If "autosync" is true, this enables autosync. Libguestfs will make a
13362 best effort attempt to make filesystems consistent and synchronized
13363 when the handle is closed (also if the program exits without closing
13364 handles).
13365 This is enabled by default (since libguestfs 1.5.24, previously it was
13367 disabled by default).
13368 This function returns 0 on success or -1 on error.
13370 (Added in 0.3)
13372 guestfs_set_backend
13374 int
13375 guestfs_set_backend (guestfs_h *g,
13376 const char *backend);
13377 Set the method that libguestfs uses to connect to the backend guestfsd
13379 daemon.
13380 This handle property was previously called the "attach method".
13382 See "BACKEND".
13384 This function returns 0 on success or -1 on error.
13386 (Added in 1.21.26)
13388 guestfs_set_backend_setting
13390 int
13391 guestfs_set_backend_setting (guestfs_h *g,
13392 const char *name,
13393 const char *val);
13394 Append "name=value" to the backend settings string list. However if a
13396 string already exists matching "name" or beginning with "name=", then
13397 that setting is replaced.
13398 See "BACKEND", "BACKEND SETTINGS".
13400 This function returns 0 on success or -1 on error.
13402 (Added in 1.27.2)
13404 guestfs_set_backend_settings
13406 int
13407 guestfs_set_backend_settings (guestfs_h *g,
13408 char *const *settings);
13409 Set a list of zero or more settings which are passed through to the
13411 current backend. Each setting is a string which is interpreted in a
13412 backend-specific way, or ignored if not understood by the backend.
13413 The default value is an empty list, unless the environment variable
13415 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13416 This environment variable contains a colon-separated list of settings.
13417 This call replaces all backend settings. If you want to replace a
13419 single backend setting, see "guestfs_set_backend_setting". If you want
13420 to clear a single backend setting, see "guestfs_clear_backend_setting".
13421 See "BACKEND", "BACKEND SETTINGS".
13423 This function returns 0 on success or -1 on error.
13425 (Added in 1.25.24)
13427 guestfs_set_cachedir
13429 int
13430 guestfs_set_cachedir (guestfs_h *g,
13431 const char *cachedir);
13432 Set the directory used by the handle to store the appliance cache, when
13434 using a supermin appliance. The appliance is cached and shared between
13435 all handles which have the same effective user ID.
13436 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13438 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13439 default. Else if "TMPDIR" is set, then that is the default. Else
13440 /var/tmp is the default.
13441 This function returns 0 on success or -1 on error.
13443 (Added in 1.19.58)
13445 guestfs_set_direct
13447 int
13448 guestfs_set_direct (guestfs_h *g,
13449 int direct);
13450 This function is deprecated. In new code, use the
13452 "guestfs_internal_get_console_socket" call instead.
13453 Deprecated functions will not be removed from the API, but the fact
13455 that they are deprecated indicates that there are problems with correct
13456 use of these functions.
13457 If the direct appliance mode flag is enabled, then stdin and stdout are
13459 passed directly through to the appliance once it is launched.
13460 One consequence of this is that log messages aren't caught by the
13462 library and handled by "guestfs_set_log_message_callback", but go
13463 straight to stdout.
13464 You probably don't want to use this unless you know what you are doing.
13466 The default is disabled.
13468 This function returns 0 on success or -1 on error.
13470 (Added in 1.0.72)
13472 guestfs_set_e2attrs
13474 int
13475 guestfs_set_e2attrs (guestfs_h *g,
13476 const char *file,
13477 const char *attrs,
13478 ...);
13479 You may supply a list of optional arguments to this call. Use zero or
13481 more of the following pairs of parameters, and terminate the list with
13482 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13483 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13485 This sets or clears the file attributes "attrs" associated with the
13487 inode file.
13488 "attrs" is a string of characters representing file attributes. See
13490 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13491 attributes can be changed.
13492 If optional boolean "clear" is not present or false, then the "attrs"
13494 listed are set in the inode.
13495 If "clear" is true, then the "attrs" listed are cleared in the inode.
13497 In both cases, other attributes not present in the "attrs" string are
13499 left unchanged.
13500 These attributes are only present when the file is located on an
13502 ext2/3/4 filesystem. Using this call on other filesystem types will
13503 result in an error.
13504 This function returns 0 on success or -1 on error.
13506 (Added in 1.17.31)
13508 guestfs_set_e2attrs_va
13510 int
13511 guestfs_set_e2attrs_va (guestfs_h *g,
13512 const char *file,
13513 const char *attrs,
13514 va_list args);
13515 This is the "va_list variant" of "guestfs_set_e2attrs".
13517 See "CALLS WITH OPTIONAL ARGUMENTS".
13519 guestfs_set_e2attrs_argv
13521 int
13522 guestfs_set_e2attrs_argv (guestfs_h *g,
13523 const char *file,
13524 const char *attrs,
13525 const struct guestfs_set_e2attrs_argv *optargs);
13526 This is the "argv variant" of "guestfs_set_e2attrs".
13528 See "CALLS WITH OPTIONAL ARGUMENTS".
13530 guestfs_set_e2generation
13532 int
13533 guestfs_set_e2generation (guestfs_h *g,
13534 const char *file,
13535 int64_t generation);
13536 This sets the ext2 file generation of a file.
13538 See "guestfs_get_e2generation".
13540 This function returns 0 on success or -1 on error.
13542 (Added in 1.17.31)
13544 guestfs_set_e2label
13546 int
13547 guestfs_set_e2label (guestfs_h *g,
13548 const char *device,
13549 const char *label);
13550 This function is deprecated. In new code, use the "guestfs_set_label"
13552 call instead.
13553 Deprecated functions will not be removed from the API, but the fact
13555 that they are deprecated indicates that there are problems with correct
13556 use of these functions.
13557 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13559 to "label". Filesystem labels are limited to 16 characters.
13560 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13562 return the existing label on a filesystem.
13563 This function returns 0 on success or -1 on error.
13565 (Added in 1.0.15)
13567 guestfs_set_e2uuid
13569 int
13570 guestfs_set_e2uuid (guestfs_h *g,
13571 const char *device,
13572 const char *uuid);
13573 This function is deprecated. In new code, use the "guestfs_set_uuid"
13575 call instead.
13576 Deprecated functions will not be removed from the API, but the fact
13578 that they are deprecated indicates that there are problems with correct
13579 use of these functions.
13580 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
13582 "uuid". The format of the UUID and alternatives such as "clear",
13583 "random" and "time" are described in the tune2fs(8) manpage.
13584 You can use "guestfs_vfs_uuid" to return the existing UUID of a
13586 filesystem.
13587 This function returns 0 on success or -1 on error.
13589 (Added in 1.0.15)
13591 guestfs_set_hv
13593 int
13594 guestfs_set_hv (guestfs_h *g,
13595 const char *hv);
13596 Set the hypervisor binary that we will use. The hypervisor depends on
13598 the backend, but is usually the location of the qemu/KVM hypervisor.
13599 For the uml backend, it is the location of the "linux" or "vmlinux"
13600 binary.
13601 The default is chosen when the library was compiled by the configure
13603 script.
13604 You can also override this by setting the "LIBGUESTFS_HV" environment
13606 variable.
13607 Note that you should call this function as early as possible after
13609 creating the handle. This is because some pre-launch operations depend
13610 on testing qemu features (by running "qemu -help"). If the qemu binary
13611 changes, we don't retest features, and so you might see inconsistent
13612 results. Using the environment variable "LIBGUESTFS_HV" is safest of
13613 all since that picks the qemu binary at the same time as the handle is
13614 created.
13615 This function returns 0 on success or -1 on error.
13617 (Added in 1.23.17)
13619 guestfs_set_identifier
13621 int
13622 guestfs_set_identifier (guestfs_h *g,
13623 const char *identifier);
13624 This is an informative string which the caller may optionally set in
13626 the handle. It is printed in various places, allowing the current
13627 handle to be identified in debugging output.
13628 One important place is when tracing is enabled. If the identifier
13630 string is not an empty string, then trace messages change from this:
13631 libguestfs: trace: get_tmpdir
13633 libguestfs: trace: get_tmpdir = "/tmp"
13634 to this:
13636 libguestfs: trace: ID: get_tmpdir
13638 libguestfs: trace: ID: get_tmpdir = "/tmp"
13639 where "ID" is the identifier string set by this call.
13641 The identifier must only contain alphanumeric ASCII characters,
13643 underscore and minus sign. The default is the empty string.
13644 See also "guestfs_set_program", "guestfs_set_trace",
13646 "guestfs_get_identifier".
13647 This function returns 0 on success or -1 on error.
13649 (Added in 1.31.14)
13651 guestfs_set_label
13653 int
13654 guestfs_set_label (guestfs_h *g,
13655 const char *mountable,
13656 const char *label);
13657 Set the filesystem label on "mountable" to "label".
13659 Only some filesystem types support labels, and libguestfs supports
13661 setting labels on only a subset of these.
13662 ext2, ext3, ext4
13664 Labels are limited to 16 bytes.
13665 NTFS
13667 Labels are limited to 128 unicode characters.
13668 XFS The label is limited to 12 bytes. The filesystem must not be
13670 mounted when trying to set the label.
13671 btrfs
13673 The label is limited to 255 bytes and some characters are not
13674 allowed. Setting the label on a btrfs subvolume will set the label
13675 on its parent filesystem. The filesystem must not be mounted when
13676 trying to set the label.
13677 fat The label is limited to 11 bytes.
13679 swap
13681 The label is limited to 16 bytes.
13682 If there is no support for changing the label for the type of the
13684 specified filesystem, set_label will fail and set errno as ENOTSUP.
13685 To read the label on a filesystem, call "guestfs_vfs_label".
13687 This function returns 0 on success or -1 on error.
13689 (Added in 1.17.9)
13691 guestfs_set_libvirt_requested_credential
13693 int
13694 guestfs_set_libvirt_requested_credential (guestfs_h *g,
13695 int index,
13696 const char *cred,
13697 size_t cred_size);
13698 After requesting the "index"'th credential from the user, call this
13700 function to pass the answer back to libvirt.
13701 See "LIBVIRT AUTHENTICATION" for documentation and example code.
13703 This function returns 0 on success or -1 on error.
13705 (Added in 1.19.52)
13707 guestfs_set_libvirt_supported_credentials
13709 int
13710 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
13711 char *const *creds);
13712 Call this function before setting an event handler for
13714 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
13715 that the program knows how to process.
13716 The "creds" list must be a non-empty list of strings. Possible strings
13718 are:
13719 "username"
13721 "authname"
13722 "language"
13723 "cnonce"
13724 "passphrase"
13725 "echoprompt"
13726 "noechoprompt"
13727 "realm"
13728 "external"
13729 See libvirt documentation for the meaning of these credential types.
13731 See "LIBVIRT AUTHENTICATION" for documentation and example code.
13733 This function returns 0 on success or -1 on error.
13735 (Added in 1.19.52)
13737 guestfs_set_memsize
13739 int
13740 guestfs_set_memsize (guestfs_h *g,
13741 int memsize);
13742 This sets the memory size in megabytes allocated to the hypervisor.
13744 This only has any effect if called before "guestfs_launch".
13745 You can also change this by setting the environment variable
13747 "LIBGUESTFS_MEMSIZE" before the handle is created.
13748 For more information on the architecture of libguestfs, see guestfs(3).
13750 This function returns 0 on success or -1 on error.
13752 (Added in 1.0.55)
13754 guestfs_set_network
13756 int
13757 guestfs_set_network (guestfs_h *g,
13758 int network);
13759 If "network" is true, then the network is enabled in the libguestfs
13761 appliance. The default is false.
13762 This affects whether commands are able to access the network (see
13764 "RUNNING COMMANDS").
13765 You must call this before calling "guestfs_launch", otherwise it has no
13767 effect.
13768 This function returns 0 on success or -1 on error.
13770 (Added in 1.5.4)
13772 guestfs_set_path
13774 int
13775 guestfs_set_path (guestfs_h *g,
13776 const char *searchpath);
13777 Set the path that libguestfs searches for kernel and initrd.img.
13779 The default is "$libdir/guestfs" unless overridden by setting
13781 "LIBGUESTFS_PATH" environment variable.
13782 Setting "path" to "NULL" restores the default path.
13784 This function returns 0 on success or -1 on error.
13786 (Added in 0.3)
13788 guestfs_set_pgroup
13790 int
13791 guestfs_set_pgroup (guestfs_h *g,
13792 int pgroup);
13793 If "pgroup" is true, child processes are placed into their own process
13795 group.
13796 The practical upshot of this is that signals like "SIGINT" (from users
13798 pressing "^C") won't be received by the child process.
13799 The default for this flag is false, because usually you want "^C" to
13801 kill the subprocess. Guestfish sets this flag to true when used
13802 interactively, so that "^C" can cancel long-running commands gracefully
13803 (see "guestfs_user_cancel").
13804 This function returns 0 on success or -1 on error.
13806 (Added in 1.11.18)
13808 guestfs_set_program
13810 int
13811 guestfs_set_program (guestfs_h *g,
13812 const char *program);
13813 Set the program name. This is an informative string which the main
13815 program may optionally set in the handle.
13816 When the handle is created, the program name in the handle is set to
13818 the basename from "argv[0]". The program name can never be "NULL".
13819 This function returns 0 on success or -1 on error.
13821 (Added in 1.21.29)
13823 guestfs_set_qemu
13825 int
13826 guestfs_set_qemu (guestfs_h *g,
13827 const char *hv);
13828 This function is deprecated. In new code, use the "guestfs_set_hv"
13830 call instead.
13831 Deprecated functions will not be removed from the API, but the fact
13833 that they are deprecated indicates that there are problems with correct
13834 use of these functions.
13835 Set the hypervisor binary (usually qemu) that we will use.
13837 The default is chosen when the library was compiled by the configure
13839 script.
13840 You can also override this by setting the "LIBGUESTFS_HV" environment
13842 variable.
13843 Setting "hv" to "NULL" restores the default qemu binary.
13845 Note that you should call this function as early as possible after
13847 creating the handle. This is because some pre-launch operations depend
13848 on testing qemu features (by running "qemu -help"). If the qemu binary
13849 changes, we don't retest features, and so you might see inconsistent
13850 results. Using the environment variable "LIBGUESTFS_HV" is safest of
13851 all since that picks the qemu binary at the same time as the handle is
13852 created.
13853 This function returns 0 on success or -1 on error.
13855 (Added in 1.0.6)
13857 guestfs_set_recovery_proc
13859 int
13860 guestfs_set_recovery_proc (guestfs_h *g,
13861 int recoveryproc);
13862 If this is called with the parameter "false" then "guestfs_launch" does
13864 not create a recovery process. The purpose of the recovery process is
13865 to stop runaway hypervisor processes in the case where the main program
13866 aborts abruptly.
13867 This only has any effect if called before "guestfs_launch", and the
13869 default is true.
13870 About the only time when you would want to disable this is if the main
13872 process will fork itself into the background ("daemonize" itself). In
13873 this case the recovery process thinks that the main program has
13874 disappeared and so kills the hypervisor, which is not very helpful.
13875 This function returns 0 on success or -1 on error.
13877 (Added in 1.0.77)
13879 guestfs_set_selinux
13881 int
13882 guestfs_set_selinux (guestfs_h *g,
13883 int selinux);
13884 This function is deprecated. In new code, use the
13886 "guestfs_selinux_relabel" call instead.
13887 Deprecated functions will not be removed from the API, but the fact
13889 that they are deprecated indicates that there are problems with correct
13890 use of these functions.
13891 This sets the selinux flag that is passed to the appliance at boot
13893 time. The default is "selinux=0" (disabled).
13894 Note that if SELinux is enabled, it is always in Permissive mode
13896 ("enforcing=0").
13897 For more information on the architecture of libguestfs, see guestfs(3).
13899 This function returns 0 on success or -1 on error.
13901 (Added in 1.0.67)
13903 guestfs_set_smp
13905 int
13906 guestfs_set_smp (guestfs_h *g,
13907 int smp);
13908 Change the number of virtual CPUs assigned to the appliance. The
13910 default is 1. Increasing this may improve performance, though often it
13911 has no effect.
13912 This function must be called before "guestfs_launch".
13914 This function returns 0 on success or -1 on error.
13916 (Added in 1.13.15)
13918 guestfs_set_tmpdir
13920 int
13921 guestfs_set_tmpdir (guestfs_h *g,
13922 const char *tmpdir);
13923 Set the directory used by the handle to store temporary files.
13925 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
13927 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
13928 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
13929 default.
13930 This function returns 0 on success or -1 on error.
13932 (Added in 1.19.58)
13934 guestfs_set_trace
13936 int
13937 guestfs_set_trace (guestfs_h *g,
13938 int trace);
13939 If the command trace flag is set to 1, then libguestfs calls,
13941 parameters and return values are traced.
13942 If you want to trace C API calls into libguestfs (and other libraries)
13944 then possibly a better way is to use the external ltrace(1) command.
13945 Command traces are disabled unless the environment variable
13947 "LIBGUESTFS_TRACE" is defined and set to 1.
13948 Trace messages are normally sent to "stderr", unless you register a
13950 callback to send them somewhere else (see
13951 "guestfs_set_event_callback").
13952 This function returns 0 on success or -1 on error.
13954 (Added in 1.0.69)
13956 guestfs_set_uuid
13958 int
13959 guestfs_set_uuid (guestfs_h *g,
13960 const char *device,
13961 const char *uuid);
13962 Set the filesystem UUID on "device" to "uuid". If this fails and the
13964 errno is ENOTSUP, means that there is no support for changing the UUID
13965 for the type of the specified filesystem.
13966 Only some filesystem types support setting UUIDs.
13968 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
13970 This function returns 0 on success or -1 on error.
13972 (Added in 1.23.10)
13974 guestfs_set_uuid_random
13976 int
13977 guestfs_set_uuid_random (guestfs_h *g,
13978 const char *device);
13979 Set the filesystem UUID on "device" to a random UUID. If this fails
13981 and the errno is ENOTSUP, means that there is no support for changing
13982 the UUID for the type of the specified filesystem.
13983 Only some filesystem types support setting UUIDs.
13985 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
13987 This function returns 0 on success or -1 on error.
13989 (Added in 1.29.50)
13991 guestfs_set_verbose
13993 int
13994 guestfs_set_verbose (guestfs_h *g,
13995 int verbose);
13996 If "verbose" is true, this turns on verbose messages.
13998 Verbose messages are disabled unless the environment variable
14000 "LIBGUESTFS_DEBUG" is defined and set to 1.
14001 Verbose messages are normally sent to "stderr", unless you register a
14003 callback to send them somewhere else (see
14004 "guestfs_set_event_callback").
14005 This function returns 0 on success or -1 on error.
14007 (Added in 0.3)
14009 guestfs_setcon
14011 int
14012 guestfs_setcon (guestfs_h *g,
14013 const char *context);
14014 This function is deprecated. In new code, use the
14016 "guestfs_selinux_relabel" call instead.
14017 Deprecated functions will not be removed from the API, but the fact
14019 that they are deprecated indicates that there are problems with correct
14020 use of these functions.
14021 This sets the SELinux security context of the daemon to the string
14023 "context".
14024 See the documentation about SELINUX in guestfs(3).
14026 This function returns 0 on success or -1 on error.
14028 This function depends on the feature "selinux". See also
14030 "guestfs_feature_available".
14031 (Added in 1.0.67)
14033 guestfs_setxattr
14035 int
14036 guestfs_setxattr (guestfs_h *g,
14037 const char *xattr,
14038 const char *val,
14039 int vallen,
14040 const char *path);
14041 This call sets the extended attribute named "xattr" of the file "path"
14043 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14044 data.
14045 See also: "guestfs_lsetxattr", attr(5).
14047 This function returns 0 on success or -1 on error.
14049 This function depends on the feature "linuxxattrs". See also
14051 "guestfs_feature_available".
14052 (Added in 1.0.59)
14054 guestfs_sfdisk
14056 int
14057 guestfs_sfdisk (guestfs_h *g,
14058 const char *device,
14059 int cyls,
14060 int heads,
14061 int sectors,
14062 char *const *lines);
14063 This function is deprecated. In new code, use the "guestfs_part_add"
14065 call instead.
14066 Deprecated functions will not be removed from the API, but the fact
14068 that they are deprecated indicates that there are problems with correct
14069 use of these functions.
14070 This is a direct interface to the sfdisk(8) program for creating
14072 partitions on block devices.
14073 "device" should be a block device, for example /dev/sda.
14075 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14077 sectors on the device, which are passed directly to sfdisk as the -C,
14078 -H and -S parameters. If you pass 0 for any of these, then the
14079 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14080 just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or
14081 rather, the kernel) cannot work out the right geometry and you will
14082 need to tell it.
14083 "lines" is a list of lines that we feed to "sfdisk". For more
14085 information refer to the sfdisk(8) manpage.
14086 To create a single partition occupying the whole disk, you would pass
14088 "lines" as a single element list, when the single element being the
14089 string "," (comma).
14090 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14092 This function returns 0 on success or -1 on error.
14094 (Added in 0.8)
14096 guestfs_sfdiskM
14098 int
14099 guestfs_sfdiskM (guestfs_h *g,
14100 const char *device,
14101 char *const *lines);
14102 This function is deprecated. In new code, use the "guestfs_part_add"
14104 call instead.
14105 Deprecated functions will not be removed from the API, but the fact
14107 that they are deprecated indicates that there are problems with correct
14108 use of these functions.
14109 This is a simplified interface to the "guestfs_sfdisk" command, where
14111 partition sizes are specified in megabytes only (rounded to the nearest
14112 cylinder) and you don't need to specify the cyls, heads and sectors
14113 parameters which were rarely if ever used anyway.
14114 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14116 "guestfs_part_disk"
14117 This function returns 0 on success or -1 on error.
14119 (Added in 1.0.55)
14121 guestfs_sfdisk_N
14123 int
14124 guestfs_sfdisk_N (guestfs_h *g,
14125 const char *device,
14126 int partnum,
14127 int cyls,
14128 int heads,
14129 int sectors,
14130 const char *line);
14131 This function is deprecated. In new code, use the "guestfs_part_add"
14133 call instead.
14134 Deprecated functions will not be removed from the API, but the fact
14136 that they are deprecated indicates that there are problems with correct
14137 use of these functions.
14138 This runs sfdisk(8) option to modify just the single partition "n"
14140 (note: "n" counts from 1).
14141 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14143 for the cyls/heads/sectors parameters.
14144 See also: "guestfs_part_add"
14146 This function returns 0 on success or -1 on error.
14148 (Added in 1.0.26)
14150 guestfs_sfdisk_disk_geometry
14152 char *
14153 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14154 const char *device);
14155 This displays the disk geometry of "device" read from the partition
14157 table. Especially in the case where the underlying block device has
14158 been resized, this can be different from the kernel’s idea of the
14159 geometry (see "guestfs_sfdisk_kernel_geometry").
14160 The result is in human-readable format, and not designed to be parsed.
14162 This function returns a string, or NULL on error. The caller must free
14164 the returned string after use.
14165 (Added in 1.0.26)
14167 guestfs_sfdisk_kernel_geometry
14169 char *
14170 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14171 const char *device);
14172 This displays the kernel’s idea of the geometry of "device".
14174 The result is in human-readable format, and not designed to be parsed.
14176 This function returns a string, or NULL on error. The caller must free
14178 the returned string after use.
14179 (Added in 1.0.26)
14181 guestfs_sfdisk_l
14183 char *
14184 guestfs_sfdisk_l (guestfs_h *g,
14185 const char *device);
14186 This function is deprecated. In new code, use the "guestfs_part_list"
14188 call instead.
14189 Deprecated functions will not be removed from the API, but the fact
14191 that they are deprecated indicates that there are problems with correct
14192 use of these functions.
14193 This displays the partition table on "device", in the human-readable
14195 output of the sfdisk(8) command. It is not intended to be parsed.
14196 See also: "guestfs_part_list"
14198 This function returns a string, or NULL on error. The caller must free
14200 the returned string after use.
14201 (Added in 1.0.26)
14203 guestfs_sh
14205 char *
14206 guestfs_sh (guestfs_h *g,
14207 const char *command);
14208 This call runs a command from the guest filesystem via the guest’s
14210 /bin/sh.
14211 This is like "guestfs_command", but passes the command to:
14213 /bin/sh -c "command"
14215 Depending on the guest’s shell, this usually results in wildcards being
14217 expanded, shell expressions being interpolated and so on.
14218 All the provisos about "guestfs_command" apply to this call.
14220 This function returns a string, or NULL on error. The caller must free
14222 the returned string after use.
14223 (Added in 1.0.50)
14225 guestfs_sh_lines
14227 char **
14228 guestfs_sh_lines (guestfs_h *g,
14229 const char *command);
14230 This is the same as "guestfs_sh", but splits the result into a list of
14232 lines.
14233 See also: "guestfs_command_lines"
14235 This function returns a NULL-terminated array of strings (like
14237 environ(3)), or NULL if there was an error. The caller must free the
14238 strings and the array after use.
14239 (Added in 1.0.50)
14241 guestfs_shutdown
14243 int
14244 guestfs_shutdown (guestfs_h *g);
14245 This is the opposite of "guestfs_launch". It performs an orderly
14247 shutdown of the backend process(es). If the autosync flag is set
14248 (which is the default) then the disk image is synchronized.
14249 If the subprocess exits with an error then this function will return an
14251 error, which should not be ignored (it may indicate that the disk image
14252 could not be written out properly).
14253 It is safe to call this multiple times. Extra calls are ignored.
14255 This call does not close or free up the handle. You still need to call
14257 "guestfs_close" afterwards.
14258 "guestfs_close" will call this if you don't do it explicitly, but note
14260 that any errors are ignored in that case.
14261 This function returns 0 on success or -1 on error.
14263 (Added in 1.19.16)
14265 guestfs_sleep
14267 int
14268 guestfs_sleep (guestfs_h *g,
14269 int secs);
14270 Sleep for "secs" seconds.
14272 This function returns 0 on success or -1 on error.
14274 (Added in 1.0.41)
14276 guestfs_stat
14278 struct guestfs_stat *
14279 guestfs_stat (guestfs_h *g,
14280 const char *path);
14281 This function is deprecated. In new code, use the "guestfs_statns"
14283 call instead.
14284 Deprecated functions will not be removed from the API, but the fact
14286 that they are deprecated indicates that there are problems with correct
14287 use of these functions.
14288 Returns file information for the given "path".
14290 This is the same as the stat(2) system call.
14292 This function returns a "struct guestfs_stat *", or NULL if there was
14294 an error. The caller must call "guestfs_free_stat" after use.
14295 (Added in 1.9.2)
14297 guestfs_statns
14299 struct guestfs_statns *
14300 guestfs_statns (guestfs_h *g,
14301 const char *path);
14302 Returns file information for the given "path".
14304 This is the same as the stat(2) system call.
14306 This function returns a "struct guestfs_statns *", or NULL if there was
14308 an error. The caller must call "guestfs_free_statns" after use.
14309 (Added in 1.27.53)
14311 guestfs_statvfs
14313 struct guestfs_statvfs *
14314 guestfs_statvfs (guestfs_h *g,
14315 const char *path);
14316 Returns file system statistics for any mounted file system. "path"
14318 should be a file or directory in the mounted file system (typically it
14319 is the mount point itself, but it doesn't need to be).
14320 This is the same as the statvfs(2) system call.
14322 This function returns a "struct guestfs_statvfs *", or NULL if there
14324 was an error. The caller must call "guestfs_free_statvfs" after use.
14325 (Added in 1.9.2)
14327 guestfs_strings
14329 char **
14330 guestfs_strings (guestfs_h *g,
14331 const char *path);
14332 This runs the strings(1) command on a file and returns the list of
14334 printable strings found.
14335 The "strings" command has, in the past, had problems with parsing
14337 untrusted files. These are mitigated in the current version of
14338 libguestfs, but see "CVE-2014-8484".
14339 This function returns a NULL-terminated array of strings (like
14341 environ(3)), or NULL if there was an error. The caller must free the
14342 strings and the array after use.
14343 Because of the message protocol, there is a transfer limit of somewhere
14345 between 2MB and 4MB. See "PROTOCOL LIMITS".
14346 (Added in 1.0.22)
14348 guestfs_strings_e
14350 char **
14351 guestfs_strings_e (guestfs_h *g,
14352 const char *encoding,
14353 const char *path);
14354 This is like the "guestfs_strings" command, but allows you to specify
14356 the encoding of strings that are looked for in the source file "path".
14357 Allowed encodings are:
14359 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14361 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14362 S Single 8-bit-byte characters.
14364 b 16-bit big endian strings such as those encoded in UTF-16BE or
14366 UCS-2BE.
14367 l (lower case letter L)
14369 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14370 for examining binaries in Windows guests.
14371 B 32-bit big endian such as UCS-4BE.
14373 L 32-bit little endian such as UCS-4LE.
14375 The returned strings are transcoded to UTF-8.
14377 The "strings" command has, in the past, had problems with parsing
14379 untrusted files. These are mitigated in the current version of
14380 libguestfs, but see "CVE-2014-8484".
14381 This function returns a NULL-terminated array of strings (like
14383 environ(3)), or NULL if there was an error. The caller must free the
14384 strings and the array after use.
14385 Because of the message protocol, there is a transfer limit of somewhere
14387 between 2MB and 4MB. See "PROTOCOL LIMITS".
14388 (Added in 1.0.22)
14390 guestfs_swapoff_device
14392 int
14393 guestfs_swapoff_device (guestfs_h *g,
14394 const char *device);
14395 This command disables the libguestfs appliance swap device or partition
14397 named "device". See "guestfs_swapon_device".
14398 This function returns 0 on success or -1 on error.
14400 (Added in 1.0.66)
14402 guestfs_swapoff_file
14404 int
14405 guestfs_swapoff_file (guestfs_h *g,
14406 const char *file);
14407 This command disables the libguestfs appliance swap on file.
14409 This function returns 0 on success or -1 on error.
14411 (Added in 1.0.66)
14413 guestfs_swapoff_label
14415 int
14416 guestfs_swapoff_label (guestfs_h *g,
14417 const char *label);
14418 This command disables the libguestfs appliance swap on labeled swap
14420 partition.
14421 This function returns 0 on success or -1 on error.
14423 (Added in 1.0.66)
14425 guestfs_swapoff_uuid
14427 int
14428 guestfs_swapoff_uuid (guestfs_h *g,
14429 const char *uuid);
14430 This command disables the libguestfs appliance swap partition with the
14432 given UUID.
14433 This function returns 0 on success or -1 on error.
14435 This function depends on the feature "linuxfsuuid". See also
14437 "guestfs_feature_available".
14438 (Added in 1.0.66)
14440 guestfs_swapon_device
14442 int
14443 guestfs_swapon_device (guestfs_h *g,
14444 const char *device);
14445 This command enables the libguestfs appliance to use the swap device or
14447 partition named "device". The increased memory is made available for
14448 all commands, for example those run using "guestfs_command" or
14449 "guestfs_sh".
14450 Note that you should not swap to existing guest swap partitions unless
14452 you know what you are doing. They may contain hibernation information,
14453 or other information that the guest doesn't want you to trash. You
14454 also risk leaking information about the host to the guest this way.
14455 Instead, attach a new host device to the guest and swap on that.
14456 This function returns 0 on success or -1 on error.
14458 (Added in 1.0.66)
14460 guestfs_swapon_file
14462 int
14463 guestfs_swapon_file (guestfs_h *g,
14464 const char *file);
14465 This command enables swap to a file. See "guestfs_swapon_device" for
14467 other notes.
14468 This function returns 0 on success or -1 on error.
14470 (Added in 1.0.66)
14472 guestfs_swapon_label
14474 int
14475 guestfs_swapon_label (guestfs_h *g,
14476 const char *label);
14477 This command enables swap to a labeled swap partition. See
14479 "guestfs_swapon_device" for other notes.
14480 This function returns 0 on success or -1 on error.
14482 (Added in 1.0.66)
14484 guestfs_swapon_uuid
14486 int
14487 guestfs_swapon_uuid (guestfs_h *g,
14488 const char *uuid);
14489 This command enables swap to a swap partition with the given UUID. See
14491 "guestfs_swapon_device" for other notes.
14492 This function returns 0 on success or -1 on error.
14494 This function depends on the feature "linuxfsuuid". See also
14496 "guestfs_feature_available".
14497 (Added in 1.0.66)
14499 guestfs_sync
14501 int
14502 guestfs_sync (guestfs_h *g);
14503 This syncs the disk, so that any writes are flushed through to the
14505 underlying disk image.
14506 You should always call this if you have modified a disk image, before
14508 closing the handle.
14509 This function returns 0 on success or -1 on error.
14511 (Added in 0.3)
14513 guestfs_syslinux
14515 int
14516 guestfs_syslinux (guestfs_h *g,
14517 const char *device,
14518 ...);
14519 You may supply a list of optional arguments to this call. Use zero or
14521 more of the following pairs of parameters, and terminate the list with
14522 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14523 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14525 Install the SYSLINUX bootloader on "device".
14527 The device parameter must be either a whole disk formatted as a FAT
14529 filesystem, or a partition formatted as a FAT filesystem. In the
14530 latter case, the partition should be marked as "active"
14531 ("guestfs_part_set_bootable") and a Master Boot Record must be
14532 installed (eg. using "guestfs_pwrite_device") on the first sector of
14533 the whole disk. The SYSLINUX package comes with some suitable Master
14534 Boot Records. See the syslinux(1) man page for further information.
14535 The optional arguments are:
14537 directory
14539 Install SYSLINUX in the named subdirectory, instead of in the root
14540 directory of the FAT filesystem.
14541 Additional configuration can be supplied to SYSLINUX by placing a file
14543 called syslinux.cfg on the FAT filesystem, either in the root
14544 directory, or under directory if that optional argument is being used.
14545 For further information about the contents of this file, see
14546 syslinux(1).
14547 See also "guestfs_extlinux".
14549 This function returns 0 on success or -1 on error.
14551 This function depends on the feature "syslinux". See also
14553 "guestfs_feature_available".
14554 (Added in 1.21.27)
14556 guestfs_syslinux_va
14558 int
14559 guestfs_syslinux_va (guestfs_h *g,
14560 const char *device,
14561 va_list args);
14562 This is the "va_list variant" of "guestfs_syslinux".
14564 See "CALLS WITH OPTIONAL ARGUMENTS".
14566 guestfs_syslinux_argv
14568 int
14569 guestfs_syslinux_argv (guestfs_h *g,
14570 const char *device,
14571 const struct guestfs_syslinux_argv *optargs);
14572 This is the "argv variant" of "guestfs_syslinux".
14574 See "CALLS WITH OPTIONAL ARGUMENTS".
14576 guestfs_tail
14578 char **
14579 guestfs_tail (guestfs_h *g,
14580 const char *path);
14581 This command returns up to the last 10 lines of a file as a list of
14583 strings.
14584 This function returns a NULL-terminated array of strings (like
14586 environ(3)), or NULL if there was an error. The caller must free the
14587 strings and the array after use.
14588 Because of the message protocol, there is a transfer limit of somewhere
14590 between 2MB and 4MB. See "PROTOCOL LIMITS".
14591 (Added in 1.0.54)
14593 guestfs_tail_n
14595 char **
14596 guestfs_tail_n (guestfs_h *g,
14597 int nrlines,
14598 const char *path);
14599 If the parameter "nrlines" is a positive number, this returns the last
14601 "nrlines" lines of the file "path".
14602 If the parameter "nrlines" is a negative number, this returns lines
14604 from the file "path", starting with the "-nrlines"th line.
14605 If the parameter "nrlines" is zero, this returns an empty list.
14607 This function returns a NULL-terminated array of strings (like
14609 environ(3)), or NULL if there was an error. The caller must free the
14610 strings and the array after use.
14611 Because of the message protocol, there is a transfer limit of somewhere
14613 between 2MB and 4MB. See "PROTOCOL LIMITS".
14614 (Added in 1.0.54)
14616 guestfs_tar_in
14618 int
14619 guestfs_tar_in (guestfs_h *g,
14620 const char *tarfile,
14621 const char *directory);
14622 This function is provided for backwards compatibility with earlier
14624 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
14625 optional arguments.
14626 (Added in 1.0.3)
14628 guestfs_tar_in_opts
14630 int
14631 guestfs_tar_in_opts (guestfs_h *g,
14632 const char *tarfile,
14633 const char *directory,
14634 ...);
14635 You may supply a list of optional arguments to this call. Use zero or
14637 more of the following pairs of parameters, and terminate the list with
14638 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14639 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
14641 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
14642 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
14643 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
14644 This command uploads and unpacks local file "tarfile" into directory.
14646 The optional "compress" flag controls compression. If not given, then
14648 the input should be an uncompressed tar file. Otherwise one of the
14649 following strings may be given to select the compression type of the
14650 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
14651 all builds of libguestfs will support all of these compression types).
14652 The other optional arguments are:
14654 "xattrs"
14656 If set to true, extended attributes are restored from the tar file.
14657 "selinux"
14659 If set to true, SELinux contexts are restored from the tar file.
14660 "acls"
14662 If set to true, POSIX ACLs are restored from the tar file.
14663 This function returns 0 on success or -1 on error.
14665 (Added in 1.0.3)
14667 guestfs_tar_in_opts_va
14669 int
14670 guestfs_tar_in_opts_va (guestfs_h *g,
14671 const char *tarfile,
14672 const char *directory,
14673 va_list args);
14674 This is the "va_list variant" of "guestfs_tar_in_opts".
14676 See "CALLS WITH OPTIONAL ARGUMENTS".
14678 guestfs_tar_in_opts_argv
14680 int
14681 guestfs_tar_in_opts_argv (guestfs_h *g,
14682 const char *tarfile,
14683 const char *directory,
14684 const struct guestfs_tar_in_opts_argv *optargs);
14685 This is the "argv variant" of "guestfs_tar_in_opts".
14687 See "CALLS WITH OPTIONAL ARGUMENTS".
14689 guestfs_tar_out
14691 int
14692 guestfs_tar_out (guestfs_h *g,
14693 const char *directory,
14694 const char *tarfile);
14695 This function is provided for backwards compatibility with earlier
14697 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
14698 optional arguments.
14699 (Added in 1.0.3)
14701 guestfs_tar_out_opts
14703 int
14704 guestfs_tar_out_opts (guestfs_h *g,
14705 const char *directory,
14706 const char *tarfile,
14707 ...);
14708 You may supply a list of optional arguments to this call. Use zero or
14710 more of the following pairs of parameters, and terminate the list with
14711 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14712 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
14714 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
14715 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
14716 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
14717 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
14718 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
14719 This command packs the contents of directory and downloads it to local
14721 file "tarfile".
14722 The optional "compress" flag controls compression. If not given, then
14724 the output will be an uncompressed tar file. Otherwise one of the
14725 following strings may be given to select the compression type of the
14726 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
14727 all builds of libguestfs will support all of these compression types).
14728 The other optional arguments are:
14730 "excludes"
14732 A list of wildcards. Files are excluded if they match any of the
14733 wildcards.
14734 "numericowner"
14736 If set to true, the output tar file will contain UID/GID numbers
14737 instead of user/group names.
14738 "xattrs"
14740 If set to true, extended attributes are saved in the output tar.
14741 "selinux"
14743 If set to true, SELinux contexts are saved in the output tar.
14744 "acls"
14746 If set to true, POSIX ACLs are saved in the output tar.
14747 This function returns 0 on success or -1 on error.
14749 (Added in 1.0.3)
14751 guestfs_tar_out_opts_va
14753 int
14754 guestfs_tar_out_opts_va (guestfs_h *g,
14755 const char *directory,
14756 const char *tarfile,
14757 va_list args);
14758 This is the "va_list variant" of "guestfs_tar_out_opts".
14760 See "CALLS WITH OPTIONAL ARGUMENTS".
14762 guestfs_tar_out_opts_argv
14764 int
14765 guestfs_tar_out_opts_argv (guestfs_h *g,
14766 const char *directory,
14767 const char *tarfile,
14768 const struct guestfs_tar_out_opts_argv *optargs);
14769 This is the "argv variant" of "guestfs_tar_out_opts".
14771 See "CALLS WITH OPTIONAL ARGUMENTS".
14773 guestfs_tgz_in
14775 int
14776 guestfs_tgz_in (guestfs_h *g,
14777 const char *tarball,
14778 const char *directory);
14779 This function is deprecated. In new code, use the "guestfs_tar_in"
14781 call instead.
14782 Deprecated functions will not be removed from the API, but the fact
14784 that they are deprecated indicates that there are problems with correct
14785 use of these functions.
14786 This command uploads and unpacks local file "tarball" (a gzip
14788 compressed tar file) into directory.
14789 This function returns 0 on success or -1 on error.
14791 (Added in 1.0.3)
14793 guestfs_tgz_out
14795 int
14796 guestfs_tgz_out (guestfs_h *g,
14797 const char *directory,
14798 const char *tarball);
14799 This function is deprecated. In new code, use the "guestfs_tar_out"
14801 call instead.
14802 Deprecated functions will not be removed from the API, but the fact
14804 that they are deprecated indicates that there are problems with correct
14805 use of these functions.
14806 This command packs the contents of directory and downloads it to local
14808 file "tarball".
14809 This function returns 0 on success or -1 on error.
14811 (Added in 1.0.3)
14813 guestfs_touch
14815 int
14816 guestfs_touch (guestfs_h *g,
14817 const char *path);
14818 Touch acts like the touch(1) command. It can be used to update the
14820 timestamps on a file, or, if the file does not exist, to create a new
14821 zero-length file.
14822 This command only works on regular files, and will fail on other file
14824 types such as directories, symbolic links, block special etc.
14825 This function returns 0 on success or -1 on error.
14827 (Added in 0.3)
14829 guestfs_truncate
14831 int
14832 guestfs_truncate (guestfs_h *g,
14833 const char *path);
14834 This command truncates "path" to a zero-length file. The file must
14836 exist already.
14837 This function returns 0 on success or -1 on error.
14839 (Added in 1.0.77)
14841 guestfs_truncate_size
14843 int
14844 guestfs_truncate_size (guestfs_h *g,
14845 const char *path,
14846 int64_t size);
14847 This command truncates "path" to size "size" bytes. The file must
14849 exist already.
14850 If the current file size is less than "size" then the file is extended
14852 to the required size with zero bytes. This creates a sparse file (ie.
14853 disk blocks are not allocated for the file until you write to it). To
14854 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
14855 This function returns 0 on success or -1 on error.
14857 (Added in 1.0.77)
14859 guestfs_tune2fs
14861 int
14862 guestfs_tune2fs (guestfs_h *g,
14863 const char *device,
14864 ...);
14865 You may supply a list of optional arguments to this call. Use zero or
14867 more of the following pairs of parameters, and terminate the list with
14868 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14869 GUESTFS_TUNE2FS_FORCE, int force,
14871 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
14872 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
14873 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
14874 GUESTFS_TUNE2FS_GROUP, int64_t group,
14875 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
14876 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
14877 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
14878 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
14879 GUESTFS_TUNE2FS_USER, int64_t user,
14880 This call allows you to adjust various filesystem parameters of an
14882 ext2/ext3/ext4 filesystem called "device".
14883 The optional parameters are:
14885 "force"
14887 Force tune2fs to complete the operation even in the face of errors.
14888 This is the same as the tune2fs "-f" option.
14889 "maxmountcount"
14891 Set the number of mounts after which the filesystem is checked by
14892 e2fsck(8). If this is 0 then the number of mounts is disregarded.
14893 This is the same as the tune2fs "-c" option.
14894 "mountcount"
14896 Set the number of times the filesystem has been mounted. This is
14897 the same as the tune2fs "-C" option.
14898 "errorbehavior"
14900 Change the behavior of the kernel code when errors are detected.
14901 Possible values currently are: "continue", "remount-ro", "panic".
14902 In practice these options don't really make any difference,
14903 particularly for write errors.
14904 This is the same as the tune2fs "-e" option.
14906 "group"
14908 Set the group which can use reserved filesystem blocks. This is
14909 the same as the tune2fs "-g" option except that it can only be
14910 specified as a number.
14911 "intervalbetweenchecks"
14913 Adjust the maximal time between two filesystem checks (in seconds).
14914 If the option is passed as 0 then time-dependent checking is
14915 disabled.
14916 This is the same as the tune2fs "-i" option.
14918 "reservedblockspercentage"
14920 Set the percentage of the filesystem which may only be allocated by
14921 privileged processes. This is the same as the tune2fs "-m" option.
14922 "lastmounteddirectory"
14924 Set the last mounted directory. This is the same as the tune2fs
14925 "-M" option.
14926 "reservedblockscount" Set the number of reserved filesystem blocks.
14928 This is the same as the tune2fs "-r" option.
14929 "user"
14930 Set the user who can use the reserved filesystem blocks. This is
14931 the same as the tune2fs "-u" option except that it can only be
14932 specified as a number.
14933 To get the current values of filesystem parameters, see
14935 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
14936 tune2fs(8) man page.
14937 This function returns 0 on success or -1 on error.
14939 (Added in 1.15.4)
14941 guestfs_tune2fs_va
14943 int
14944 guestfs_tune2fs_va (guestfs_h *g,
14945 const char *device,
14946 va_list args);
14947 This is the "va_list variant" of "guestfs_tune2fs".
14949 See "CALLS WITH OPTIONAL ARGUMENTS".
14951 guestfs_tune2fs_argv
14953 int
14954 guestfs_tune2fs_argv (guestfs_h *g,
14955 const char *device,
14956 const struct guestfs_tune2fs_argv *optargs);
14957 This is the "argv variant" of "guestfs_tune2fs".
14959 See "CALLS WITH OPTIONAL ARGUMENTS".
14961 guestfs_tune2fs_l
14963 char **
14964 guestfs_tune2fs_l (guestfs_h *g,
14965 const char *device);
14966 This returns the contents of the ext2, ext3 or ext4 filesystem
14968 superblock on "device".
14969 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
14971 for more details. The list of fields returned isn't clearly defined,
14972 and depends on both the version of "tune2fs" that libguestfs was built
14973 against, and the filesystem itself.
14974 This function returns a NULL-terminated array of strings, or NULL if
14976 there was an error. The array of strings will always have length
14977 "2n+1", where "n" keys and values alternate, followed by the trailing
14978 NULL entry. The caller must free the strings and the array after use.
14979 (Added in 1.9.2)
14981 guestfs_txz_in
14983 int
14984 guestfs_txz_in (guestfs_h *g,
14985 const char *tarball,
14986 const char *directory);
14987 This function is deprecated. In new code, use the "guestfs_tar_in"
14989 call instead.
14990 Deprecated functions will not be removed from the API, but the fact
14992 that they are deprecated indicates that there are problems with correct
14993 use of these functions.
14994 This command uploads and unpacks local file "tarball" (an xz compressed
14996 tar file) into directory.
14997 This function returns 0 on success or -1 on error.
14999 This function depends on the feature "xz". See also
15001 "guestfs_feature_available".
15002 (Added in 1.3.2)
15004 guestfs_txz_out
15006 int
15007 guestfs_txz_out (guestfs_h *g,
15008 const char *directory,
15009 const char *tarball);
15010 This function is deprecated. In new code, use the "guestfs_tar_out"
15012 call instead.
15013 Deprecated functions will not be removed from the API, but the fact
15015 that they are deprecated indicates that there are problems with correct
15016 use of these functions.
15017 This command packs the contents of directory and downloads it to local
15019 file "tarball" (as an xz compressed tar archive).
15020 This function returns 0 on success or -1 on error.
15022 This function depends on the feature "xz". See also
15024 "guestfs_feature_available".
15025 (Added in 1.3.2)
15027 guestfs_umask
15029 int
15030 guestfs_umask (guestfs_h *g,
15031 int mask);
15032 This function sets the mask used for creating new files and device
15034 nodes to "mask & 0777".
15035 Typical umask values would be 022 which creates new files with
15037 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15038 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15039 The default umask is 022. This is important because it means that
15041 directories and device nodes will be created with 0644 or 0755 mode
15042 even if you specify 0777.
15043 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15045 "guestfs_mkdir".
15046 This call returns the previous umask.
15048 On error this function returns -1.
15050 (Added in 1.0.55)
15052 guestfs_umount
15054 int
15055 guestfs_umount (guestfs_h *g,
15056 const char *pathordevice);
15057 This function is provided for backwards compatibility with earlier
15059 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15060 optional arguments.
15061 (Added in 0.8)
15063 guestfs_umount_opts
15065 int
15066 guestfs_umount_opts (guestfs_h *g,
15067 const char *pathordevice,
15068 ...);
15069 You may supply a list of optional arguments to this call. Use zero or
15071 more of the following pairs of parameters, and terminate the list with
15072 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15073 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15075 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15076 This unmounts the given filesystem. The filesystem may be specified
15078 either by its mountpoint (path) or the device which contains the
15079 filesystem.
15080 This function returns 0 on success or -1 on error.
15082 (Added in 0.8)
15084 guestfs_umount_opts_va
15086 int
15087 guestfs_umount_opts_va (guestfs_h *g,
15088 const char *pathordevice,
15089 va_list args);
15090 This is the "va_list variant" of "guestfs_umount_opts".
15092 See "CALLS WITH OPTIONAL ARGUMENTS".
15094 guestfs_umount_opts_argv
15096 int
15097 guestfs_umount_opts_argv (guestfs_h *g,
15098 const char *pathordevice,
15099 const struct guestfs_umount_opts_argv *optargs);
15100 This is the "argv variant" of "guestfs_umount_opts".
15102 See "CALLS WITH OPTIONAL ARGUMENTS".
15104 guestfs_umount_all
15106 int
15107 guestfs_umount_all (guestfs_h *g);
15108 This unmounts all mounted filesystems.
15110 Some internal mounts are not unmounted by this call.
15112 This function returns 0 on success or -1 on error.
15114 (Added in 0.8)
15116 guestfs_umount_local
15118 int
15119 guestfs_umount_local (guestfs_h *g,
15120 ...);
15121 You may supply a list of optional arguments to this call. Use zero or
15123 more of the following pairs of parameters, and terminate the list with
15124 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15125 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15127 If libguestfs is exporting the filesystem on a local mountpoint, then
15129 this unmounts it.
15130 See "MOUNT LOCAL" for full documentation.
15132 This function returns 0 on success or -1 on error.
15134 (Added in 1.17.22)
15136 guestfs_umount_local_va
15138 int
15139 guestfs_umount_local_va (guestfs_h *g,
15140 va_list args);
15141 This is the "va_list variant" of "guestfs_umount_local".
15143 See "CALLS WITH OPTIONAL ARGUMENTS".
15145 guestfs_umount_local_argv
15147 int
15148 guestfs_umount_local_argv (guestfs_h *g,
15149 const struct guestfs_umount_local_argv *optargs);
15150 This is the "argv variant" of "guestfs_umount_local".
15152 See "CALLS WITH OPTIONAL ARGUMENTS".
15154 guestfs_upload
15156 int
15157 guestfs_upload (guestfs_h *g,
15158 const char *filename,
15159 const char *remotefilename);
15160 Upload local file filename to remotefilename on the filesystem.
15162 filename can also be a named pipe.
15164 See also "guestfs_download".
15166 This function returns 0 on success or -1 on error.
15168 This long-running command can generate progress notification messages
15170 so that the caller can display a progress bar or indicator. To receive
15171 these messages, the caller must register a progress event callback.
15172 See "GUESTFS_EVENT_PROGRESS".
15173 (Added in 1.0.2)
15175 guestfs_upload_offset
15177 int
15178 guestfs_upload_offset (guestfs_h *g,
15179 const char *filename,
15180 const char *remotefilename,
15181 int64_t offset);
15182 Upload local file filename to remotefilename on the filesystem.
15184 remotefilename is overwritten starting at the byte "offset" specified.
15186 The intention is to overwrite parts of existing files or devices,
15187 although if a non-existent file is specified then it is created with a
15188 "hole" before "offset". The size of the data written is implicit in
15189 the size of the source filename.
15190 Note that there is no limit on the amount of data that can be uploaded
15192 with this call, unlike with "guestfs_pwrite", and this call always
15193 writes the full amount unless an error occurs.
15194 See also "guestfs_upload", "guestfs_pwrite".
15196 This function returns 0 on success or -1 on error.
15198 This long-running command can generate progress notification messages
15200 so that the caller can display a progress bar or indicator. To receive
15201 these messages, the caller must register a progress event callback.
15202 See "GUESTFS_EVENT_PROGRESS".
15203 (Added in 1.5.17)
15205 guestfs_user_cancel
15207 int
15208 guestfs_user_cancel (guestfs_h *g);
15209 This function cancels the current upload or download operation.
15211 Unlike most other libguestfs calls, this function is signal safe and
15213 thread safe. You can call it from a signal handler or from another
15214 thread, without needing to do any locking.
15215 The transfer that was in progress (if there is one) will stop shortly
15217 afterwards, and will return an error. The errno (see
15218 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15219 find out if the operation was cancelled or failed because of another
15220 error.
15221 No cleanup is performed: for example, if a file was being uploaded then
15223 after cancellation there may be a partially uploaded file. It is the
15224 caller’s responsibility to clean up if necessary.
15225 There are two common places that you might call "guestfs_user_cancel":
15227 In an interactive text-based program, you might call it from a "SIGINT"
15229 signal handler so that pressing "^C" cancels the current operation.
15230 (You also need to call "guestfs_set_pgroup" so that child processes
15231 don't receive the "^C" signal).
15232 In a graphical program, when the main thread is displaying a progress
15234 bar with a cancel button, wire up the cancel button to call this
15235 function.
15236 This function returns 0 on success or -1 on error.
15238 (Added in 1.11.18)
15240 guestfs_utimens
15242 int
15243 guestfs_utimens (guestfs_h *g,
15244 const char *path,
15245 int64_t atsecs,
15246 int64_t atnsecs,
15247 int64_t mtsecs,
15248 int64_t mtnsecs);
15249 This command sets the timestamps of a file with nanosecond precision.
15251 "atsecs, atnsecs" are the last access time (atime) in secs and
15253 nanoseconds from the epoch.
15254 "mtsecs, mtnsecs" are the last modification time (mtime) in secs and
15256 nanoseconds from the epoch.
15257 If the *nsecs field contains the special value "-1" then the
15259 corresponding timestamp is set to the current time. (The *secs field
15260 is ignored in this case).
15261 If the *nsecs field contains the special value "-2" then the
15263 corresponding timestamp is left unchanged. (The *secs field is ignored
15264 in this case).
15265 This function returns 0 on success or -1 on error.
15267 (Added in 1.0.77)
15269 guestfs_utsname
15271 struct guestfs_utsname *
15272 guestfs_utsname (guestfs_h *g);
15273 This returns the kernel version of the appliance, where this is
15275 available. This information is only useful for debugging. Nothing in
15276 the returned structure is defined by the API.
15277 This function returns a "struct guestfs_utsname *", or NULL if there
15279 was an error. The caller must call "guestfs_free_utsname" after use.
15280 (Added in 1.19.27)
15282 guestfs_version
15284 struct guestfs_version *
15285 guestfs_version (guestfs_h *g);
15286 Return the libguestfs version number that the program is linked
15288 against.
15289 Note that because of dynamic linking this is not necessarily the
15291 version of libguestfs that you compiled against. You can compile the
15292 program, and then at runtime dynamically link against a completely
15293 different libguestfs.so library.
15294 This call was added in version 1.0.58. In previous versions of
15296 libguestfs there was no way to get the version number. From C code you
15297 can use dynamic linker functions to find out if this symbol exists (if
15298 it doesn't, then it’s an earlier version).
15299 The call returns a structure with four elements. The first three
15301 ("major", "minor" and "release") are numbers and correspond to the
15302 usual version triplet. The fourth element ("extra") is a string and is
15303 normally empty, but may be used for distro-specific information.
15304 To construct the original version string:
15306 "$major.$minor.$release$extra"
15307 See also: "LIBGUESTFS VERSION NUMBERS".
15309 Note: Don't use this call to test for availability of features. In
15311 enterprise distributions we backport features from later versions into
15312 earlier versions, making this an unreliable way to test for features.
15313 Use "guestfs_available" or "guestfs_feature_available" instead.
15314 This function returns a "struct guestfs_version *", or NULL if there
15316 was an error. The caller must call "guestfs_free_version" after use.
15317 (Added in 1.0.58)
15319 guestfs_vfs_label
15321 char *
15322 guestfs_vfs_label (guestfs_h *g,
15323 const char *mountable);
15324 This returns the label of the filesystem on "mountable".
15326 If the filesystem is unlabeled, this returns the empty string.
15328 To find a filesystem from the label, use "guestfs_findfs_label".
15330 This function returns a string, or NULL on error. The caller must free
15332 the returned string after use.
15333 (Added in 1.3.18)
15335 guestfs_vfs_minimum_size
15337 int64_t
15338 guestfs_vfs_minimum_size (guestfs_h *g,
15339 const char *mountable);
15340 Get the minimum size of filesystem in bytes. This is the minimum
15342 possible size for filesystem shrinking.
15343 If getting minimum size of specified filesystem is not supported, this
15345 will fail and set errno as ENOTSUP.
15346 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15348 On error this function returns -1.
15350 (Added in 1.31.18)
15352 guestfs_vfs_type
15354 char *
15355 guestfs_vfs_type (guestfs_h *g,
15356 const char *mountable);
15357 This command gets the filesystem type corresponding to the filesystem
15359 on "mountable".
15360 For most filesystems, the result is the name of the Linux VFS module
15362 which would be used to mount this filesystem if you mounted it without
15363 specifying the filesystem type. For example a string such as "ext3" or
15364 "ntfs".
15365 This function returns a string, or NULL on error. The caller must free
15367 the returned string after use.
15368 (Added in 1.0.75)
15370 guestfs_vfs_uuid
15372 char *
15373 guestfs_vfs_uuid (guestfs_h *g,
15374 const char *mountable);
15375 This returns the filesystem UUID of the filesystem on "mountable".
15377 If the filesystem does not have a UUID, this returns the empty string.
15379 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15381 This function returns a string, or NULL on error. The caller must free
15383 the returned string after use.
15384 (Added in 1.3.18)
15386 guestfs_vg_activate
15388 int
15389 guestfs_vg_activate (guestfs_h *g,
15390 int activate,
15391 char *const *volgroups);
15392 This command activates or (if "activate" is false) deactivates all
15394 logical volumes in the listed volume groups "volgroups".
15395 This command is the same as running "vgchange -a y|n volgroups..."
15397 Note that if "volgroups" is an empty list then all volume groups are
15399 activated or deactivated.
15400 This function returns 0 on success or -1 on error.
15402 This function depends on the feature "lvm2". See also
15404 "guestfs_feature_available".
15405 (Added in 1.0.26)
15407 guestfs_vg_activate_all
15409 int
15410 guestfs_vg_activate_all (guestfs_h *g,
15411 int activate);
15412 This command activates or (if "activate" is false) deactivates all
15414 logical volumes in all volume groups.
15415 This command is the same as running "vgchange -a y|n"
15417 This function returns 0 on success or -1 on error.
15419 This function depends on the feature "lvm2". See also
15421 "guestfs_feature_available".
15422 (Added in 1.0.26)
15424 guestfs_vgchange_uuid
15426 int
15427 guestfs_vgchange_uuid (guestfs_h *g,
15428 const char *vg);
15429 Generate a new random UUID for the volume group "vg".
15431 This function returns 0 on success or -1 on error.
15433 This function depends on the feature "lvm2". See also
15435 "guestfs_feature_available".
15436 (Added in 1.19.26)
15438 guestfs_vgchange_uuid_all
15440 int
15441 guestfs_vgchange_uuid_all (guestfs_h *g);
15442 Generate new random UUIDs for all volume groups.
15444 This function returns 0 on success or -1 on error.
15446 This function depends on the feature "lvm2". See also
15448 "guestfs_feature_available".
15449 (Added in 1.19.26)
15451 guestfs_vgcreate
15453 int
15454 guestfs_vgcreate (guestfs_h *g,
15455 const char *volgroup,
15456 char *const *physvols);
15457 This creates an LVM volume group called "volgroup" from the non-empty
15459 list of physical volumes "physvols".
15460 This function returns 0 on success or -1 on error.
15462 This function depends on the feature "lvm2". See also
15464 "guestfs_feature_available".
15465 (Added in 0.8)
15467 guestfs_vglvuuids
15469 char **
15470 guestfs_vglvuuids (guestfs_h *g,
15471 const char *vgname);
15472 Given a VG called "vgname", this returns the UUIDs of all the logical
15474 volumes created in this volume group.
15475 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15477 associate logical volumes and volume groups.
15478 See also "guestfs_vgpvuuids".
15480 This function returns a NULL-terminated array of strings (like
15482 environ(3)), or NULL if there was an error. The caller must free the
15483 strings and the array after use.
15484 (Added in 1.0.87)
15486 guestfs_vgmeta
15488 char *
15489 guestfs_vgmeta (guestfs_h *g,
15490 const char *vgname,
15491 size_t *size_r);
15492 "vgname" is an LVM volume group. This command examines the volume
15494 group and returns its metadata.
15495 Note that the metadata is an internal structure used by LVM, subject to
15497 change at any time, and is provided for information only.
15498 This function returns a buffer, or NULL on error. The size of the
15500 returned buffer is written to *size_r. The caller must free the
15501 returned buffer after use.
15502 This function depends on the feature "lvm2". See also
15504 "guestfs_feature_available".
15505 (Added in 1.17.20)
15507 guestfs_vgpvuuids
15509 char **
15510 guestfs_vgpvuuids (guestfs_h *g,
15511 const char *vgname);
15512 Given a VG called "vgname", this returns the UUIDs of all the physical
15514 volumes that this volume group resides on.
15515 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15517 associate physical volumes and volume groups.
15518 See also "guestfs_vglvuuids".
15520 This function returns a NULL-terminated array of strings (like
15522 environ(3)), or NULL if there was an error. The caller must free the
15523 strings and the array after use.
15524 (Added in 1.0.87)
15526 guestfs_vgremove
15528 int
15529 guestfs_vgremove (guestfs_h *g,
15530 const char *vgname);
15531 Remove an LVM volume group "vgname", (for example "VG").
15533 This also forcibly removes all logical volumes in the volume group (if
15535 any).
15536 This function returns 0 on success or -1 on error.
15538 This function depends on the feature "lvm2". See also
15540 "guestfs_feature_available".
15541 (Added in 1.0.13)
15543 guestfs_vgrename
15545 int
15546 guestfs_vgrename (guestfs_h *g,
15547 const char *volgroup,
15548 const char *newvolgroup);
15549 Rename a volume group "volgroup" with the new name "newvolgroup".
15551 This function returns 0 on success or -1 on error.
15553 (Added in 1.0.83)
15555 guestfs_vgs
15557 char **
15558 guestfs_vgs (guestfs_h *g);
15559 List all the volumes groups detected. This is the equivalent of the
15561 vgs(8) command.
15562 This returns a list of just the volume group names that were detected
15564 (eg. "VolGroup00").
15565 See also "guestfs_vgs_full".
15567 This function returns a NULL-terminated array of strings (like
15569 environ(3)), or NULL if there was an error. The caller must free the
15570 strings and the array after use.
15571 This function depends on the feature "lvm2". See also
15573 "guestfs_feature_available".
15574 (Added in 0.4)
15576 guestfs_vgs_full
15578 struct guestfs_lvm_vg_list *
15579 guestfs_vgs_full (guestfs_h *g);
15580 List all the volumes groups detected. This is the equivalent of the
15582 vgs(8) command. The "full" version includes all fields.
15583 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
15585 there was an error. The caller must call "guestfs_free_lvm_vg_list"
15586 after use.
15587 This function depends on the feature "lvm2". See also
15589 "guestfs_feature_available".
15590 (Added in 0.4)
15592 guestfs_vgscan
15594 int
15595 guestfs_vgscan (guestfs_h *g);
15596 This rescans all block devices and rebuilds the list of LVM physical
15598 volumes, volume groups and logical volumes.
15599 This function returns 0 on success or -1 on error.
15601 (Added in 1.3.2)
15603 guestfs_vguuid
15605 char *
15606 guestfs_vguuid (guestfs_h *g,
15607 const char *vgname);
15608 This command returns the UUID of the LVM VG named "vgname".
15610 This function returns a string, or NULL on error. The caller must free
15612 the returned string after use.
15613 (Added in 1.0.87)
15615 guestfs_wait_ready
15617 int
15618 guestfs_wait_ready (guestfs_h *g);
15619 This function is deprecated. There is no replacement. Consult the API
15621 documentation in guestfs(3) for further information.
15622 Deprecated functions will not be removed from the API, but the fact
15624 that they are deprecated indicates that there are problems with correct
15625 use of these functions.
15626 This function is a no op.
15628 In versions of the API < 1.0.71 you had to call this function just
15630 after calling "guestfs_launch" to wait for the launch to complete.
15631 However this is no longer necessary because "guestfs_launch" now does
15632 the waiting.
15633 If you see any calls to this function in code then you can just remove
15635 them, unless you want to retain compatibility with older versions of
15636 the API.
15637 This function returns 0 on success or -1 on error.
15639 (Added in 0.3)
15641 guestfs_wc_c
15643 int
15644 guestfs_wc_c (guestfs_h *g,
15645 const char *path);
15646 This command counts the characters in a file, using the "wc -c"
15648 external command.
15649 On error this function returns -1.
15651 (Added in 1.0.54)
15653 guestfs_wc_l
15655 int
15656 guestfs_wc_l (guestfs_h *g,
15657 const char *path);
15658 This command counts the lines in a file, using the "wc -l" external
15660 command.
15661 On error this function returns -1.
15663 (Added in 1.0.54)
15665 guestfs_wc_w
15667 int
15668 guestfs_wc_w (guestfs_h *g,
15669 const char *path);
15670 This command counts the words in a file, using the "wc -w" external
15672 command.
15673 On error this function returns -1.
15675 (Added in 1.0.54)
15677 guestfs_wipefs
15679 int
15680 guestfs_wipefs (guestfs_h *g,
15681 const char *device);
15682 This command erases filesystem or RAID signatures from the specified
15684 "device" to make the filesystem invisible to libblkid.
15685 This does not erase the filesystem itself nor any other data from the
15687 "device".
15688 Compare with "guestfs_zero" which zeroes the first few blocks of a
15690 device.
15691 This function returns 0 on success or -1 on error.
15693 This function depends on the feature "wipefs". See also
15695 "guestfs_feature_available".
15696 (Added in 1.17.6)
15698 guestfs_write
15700 int
15701 guestfs_write (guestfs_h *g,
15702 const char *path,
15703 const char *content,
15704 size_t content_size);
15705 This call creates a file called "path". The content of the file is the
15707 string "content" (which can contain any 8 bit data).
15708 See also "guestfs_write_append".
15710 This function returns 0 on success or -1 on error.
15712 (Added in 1.3.14)
15714 guestfs_write_append
15716 int
15717 guestfs_write_append (guestfs_h *g,
15718 const char *path,
15719 const char *content,
15720 size_t content_size);
15721 This call appends "content" to the end of file "path". If "path" does
15723 not exist, then a new file is created.
15724 See also "guestfs_write".
15726 This function returns 0 on success or -1 on error.
15728 (Added in 1.11.18)
15730 guestfs_write_file
15732 int
15733 guestfs_write_file (guestfs_h *g,
15734 const char *path,
15735 const char *content,
15736 int size);
15737 This function is deprecated. In new code, use the "guestfs_write" call
15739 instead.
15740 Deprecated functions will not be removed from the API, but the fact
15742 that they are deprecated indicates that there are problems with correct
15743 use of these functions.
15744 This call creates a file called "path". The contents of the file is
15746 the string "content" (which can contain any 8 bit data), with length
15747 "size".
15748 As a special case, if "size" is 0 then the length is calculated using
15750 "strlen" (so in this case the content cannot contain embedded ASCII
15751 NULs).
15752 NB. Owing to a bug, writing content containing ASCII NUL characters
15754 does not work, even if the length is specified.
15755 This function returns 0 on success or -1 on error.
15757 Because of the message protocol, there is a transfer limit of somewhere
15759 between 2MB and 4MB. See "PROTOCOL LIMITS".
15760 (Added in 0.8)
15762 guestfs_xfs_admin
15764 int
15765 guestfs_xfs_admin (guestfs_h *g,
15766 const char *device,
15767 ...);
15768 You may supply a list of optional arguments to this call. Use zero or
15770 more of the following pairs of parameters, and terminate the list with
15771 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15772 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
15774 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
15775 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
15776 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
15777 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
15778 GUESTFS_XFS_ADMIN_LABEL, const char *label,
15779 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
15780 Change the parameters of the XFS filesystem on "device".
15782 Devices that are mounted cannot be modified. Administrators must
15784 unmount filesystems before this call can modify parameters.
15785 Some of the parameters of a mounted filesystem can be examined and
15787 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
15788 This function returns 0 on success or -1 on error.
15790 This function depends on the feature "xfs". See also
15792 "guestfs_feature_available".
15793 (Added in 1.19.33)
15795 guestfs_xfs_admin_va
15797 int
15798 guestfs_xfs_admin_va (guestfs_h *g,
15799 const char *device,
15800 va_list args);
15801 This is the "va_list variant" of "guestfs_xfs_admin".
15803 See "CALLS WITH OPTIONAL ARGUMENTS".
15805 guestfs_xfs_admin_argv
15807 int
15808 guestfs_xfs_admin_argv (guestfs_h *g,
15809 const char *device,
15810 const struct guestfs_xfs_admin_argv *optargs);
15811 This is the "argv variant" of "guestfs_xfs_admin".
15813 See "CALLS WITH OPTIONAL ARGUMENTS".
15815 guestfs_xfs_growfs
15817 int
15818 guestfs_xfs_growfs (guestfs_h *g,
15819 const char *path,
15820 ...);
15821 You may supply a list of optional arguments to this call. Use zero or
15823 more of the following pairs of parameters, and terminate the list with
15824 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15825 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
15827 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
15828 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
15829 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
15830 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
15831 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
15832 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
15833 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
15834 Grow the XFS filesystem mounted at "path".
15836 The returned struct contains geometry information. Missing fields are
15838 returned as "-1" (for numeric fields) or empty string.
15839 This function returns 0 on success or -1 on error.
15841 This function depends on the feature "xfs". See also
15843 "guestfs_feature_available".
15844 (Added in 1.19.28)
15846 guestfs_xfs_growfs_va
15848 int
15849 guestfs_xfs_growfs_va (guestfs_h *g,
15850 const char *path,
15851 va_list args);
15852 This is the "va_list variant" of "guestfs_xfs_growfs".
15854 See "CALLS WITH OPTIONAL ARGUMENTS".
15856 guestfs_xfs_growfs_argv
15858 int
15859 guestfs_xfs_growfs_argv (guestfs_h *g,
15860 const char *path,
15861 const struct guestfs_xfs_growfs_argv *optargs);
15862 This is the "argv variant" of "guestfs_xfs_growfs".
15864 See "CALLS WITH OPTIONAL ARGUMENTS".
15866 guestfs_xfs_info
15868 struct guestfs_xfsinfo *
15869 guestfs_xfs_info (guestfs_h *g,
15870 const char *pathordevice);
15871 "pathordevice" is a mounted XFS filesystem or a device containing an
15873 XFS filesystem. This command returns the geometry of the filesystem.
15874 The returned struct contains geometry information. Missing fields are
15876 returned as "-1" (for numeric fields) or empty string.
15877 This function returns a "struct guestfs_xfsinfo *", or NULL if there
15879 was an error. The caller must call "guestfs_free_xfsinfo" after use.
15880 This function depends on the feature "xfs". See also
15882 "guestfs_feature_available".
15883 (Added in 1.19.21)
15885 guestfs_xfs_repair
15887 int
15888 guestfs_xfs_repair (guestfs_h *g,
15889 const char *device,
15890 ...);
15891 You may supply a list of optional arguments to this call. Use zero or
15893 more of the following pairs of parameters, and terminate the list with
15894 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15895 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
15897 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
15898 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
15899 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
15900 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
15901 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
15902 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
15903 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
15904 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
15905 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
15906 Repair corrupt or damaged XFS filesystem on "device".
15908 The filesystem is specified using the "device" argument which should be
15910 the device name of the disk partition or volume containing the
15911 filesystem. If given the name of a block device, "xfs_repair" will
15912 attempt to find the raw device associated with the specified block
15913 device and will use the raw device instead.
15914 Regardless, the filesystem to be repaired must be unmounted, otherwise,
15916 the resulting filesystem may be inconsistent or corrupt.
15917 The returned status indicates whether filesystem corruption was
15919 detected (returns 1) or was not detected (returns 0).
15920 On error this function returns -1.
15922 This function depends on the feature "xfs". See also
15924 "guestfs_feature_available".
15925 (Added in 1.19.36)
15927 guestfs_xfs_repair_va
15929 int
15930 guestfs_xfs_repair_va (guestfs_h *g,
15931 const char *device,
15932 va_list args);
15933 This is the "va_list variant" of "guestfs_xfs_repair".
15935 See "CALLS WITH OPTIONAL ARGUMENTS".
15937 guestfs_xfs_repair_argv
15939 int
15940 guestfs_xfs_repair_argv (guestfs_h *g,
15941 const char *device,
15942 const struct guestfs_xfs_repair_argv *optargs);
15943 This is the "argv variant" of "guestfs_xfs_repair".
15945 See "CALLS WITH OPTIONAL ARGUMENTS".
15947 guestfs_yara_destroy
15949 int
15950 guestfs_yara_destroy (guestfs_h *g);
15951 Destroy previously loaded Yara rules in order to free libguestfs
15953 resources.
15954 This function returns 0 on success or -1 on error.
15956 This function depends on the feature "libyara". See also
15958 "guestfs_feature_available".
15959 (Added in 1.37.13)
15961 guestfs_yara_load
15963 int
15964 guestfs_yara_load (guestfs_h *g,
15965 const char *filename);
15966 Upload a set of Yara rules from local file filename.
15968 Yara rules allow to categorize files based on textual or binary
15970 patterns within their content. See "guestfs_yara_scan" to see how to
15971 scan files with the loaded rules.
15972 Rules can be in binary format, as when compiled with yarac command, or
15974 in source code format. In the latter case, the rules will be first
15975 compiled and then loaded.
15976 Rules in source code format cannot include external files. In such
15978 cases, it is recommended to compile them first.
15979 Previously loaded rules will be destroyed.
15981 This function returns 0 on success or -1 on error.
15983 This long-running command can generate progress notification messages
15985 so that the caller can display a progress bar or indicator. To receive
15986 these messages, the caller must register a progress event callback.
15987 See "GUESTFS_EVENT_PROGRESS".
15988 This function depends on the feature "libyara". See also
15990 "guestfs_feature_available".
15991 (Added in 1.37.13)
15993 guestfs_yara_scan
15995 struct guestfs_yara_detection_list *
15996 guestfs_yara_scan (guestfs_h *g,
15997 const char *path);
15998 Scan a file with the previously loaded Yara rules.
16000 For each matching rule, a "yara_detection" structure is returned.
16002 The "yara_detection" structure contains the following fields.
16004 "yara_name"
16006 Path of the file matching a Yara rule.
16007 "yara_rule"
16009 Identifier of the Yara rule which matched against the given file.
16010 This function returns a "struct guestfs_yara_detection_list *", or NULL
16012 if there was an error. The caller must call
16013 "guestfs_free_yara_detection_list" after use.
16014 This long-running command can generate progress notification messages
16016 so that the caller can display a progress bar or indicator. To receive
16017 these messages, the caller must register a progress event callback.
16018 See "GUESTFS_EVENT_PROGRESS".
16019 This function depends on the feature "libyara". See also
16021 "guestfs_feature_available".
16022 (Added in 1.37.13)
16024 guestfs_zegrep
16026 char **
16027 guestfs_zegrep (guestfs_h *g,
16028 const char *regex,
16029 const char *path);
16030 This function is deprecated. In new code, use the "guestfs_grep" call
16032 instead.
16033 Deprecated functions will not be removed from the API, but the fact
16035 that they are deprecated indicates that there are problems with correct
16036 use of these functions.
16037 This calls the external "zegrep" program and returns the matching
16039 lines.
16040 This function returns a NULL-terminated array of strings (like
16042 environ(3)), or NULL if there was an error. The caller must free the
16043 strings and the array after use.
16044 Because of the message protocol, there is a transfer limit of somewhere
16046 between 2MB and 4MB. See "PROTOCOL LIMITS".
16047 (Added in 1.0.66)
16049 guestfs_zegrepi
16051 char **
16052 guestfs_zegrepi (guestfs_h *g,
16053 const char *regex,
16054 const char *path);
16055 This function is deprecated. In new code, use the "guestfs_grep" call
16057 instead.
16058 Deprecated functions will not be removed from the API, but the fact
16060 that they are deprecated indicates that there are problems with correct
16061 use of these functions.
16062 This calls the external "zegrep -i" program and returns the matching
16064 lines.
16065 This function returns a NULL-terminated array of strings (like
16067 environ(3)), or NULL if there was an error. The caller must free the
16068 strings and the array after use.
16069 Because of the message protocol, there is a transfer limit of somewhere
16071 between 2MB and 4MB. See "PROTOCOL LIMITS".
16072 (Added in 1.0.66)
16074 guestfs_zero
16076 int
16077 guestfs_zero (guestfs_h *g,
16078 const char *device);
16079 This command writes zeroes over the first few blocks of "device".
16081 How many blocks are zeroed isn't specified (but it’s not enough to
16083 securely wipe the device). It should be sufficient to remove any
16084 partition tables, filesystem superblocks and so on.
16085 If blocks are already zero, then this command avoids writing zeroes.
16087 This prevents the underlying device from becoming non-sparse or growing
16088 unnecessarily.
16089 See also: "guestfs_zero_device", "guestfs_scrub_device",
16091 "guestfs_is_zero_device"
16092 This function returns 0 on success or -1 on error.
16094 This long-running command can generate progress notification messages
16096 so that the caller can display a progress bar or indicator. To receive
16097 these messages, the caller must register a progress event callback.
16098 See "GUESTFS_EVENT_PROGRESS".
16099 (Added in 1.0.16)
16101 guestfs_zero_device
16103 int
16104 guestfs_zero_device (guestfs_h *g,
16105 const char *device);
16106 This command writes zeroes over the entire "device". Compare with
16108 "guestfs_zero" which just zeroes the first few blocks of a device.
16109 If blocks are already zero, then this command avoids writing zeroes.
16111 This prevents the underlying device from becoming non-sparse or growing
16112 unnecessarily.
16113 This function returns 0 on success or -1 on error.
16115 This long-running command can generate progress notification messages
16117 so that the caller can display a progress bar or indicator. To receive
16118 these messages, the caller must register a progress event callback.
16119 See "GUESTFS_EVENT_PROGRESS".
16120 (Added in 1.3.1)
16122 guestfs_zero_free_space
16124 int
16125 guestfs_zero_free_space (guestfs_h *g,
16126 const char *directory);
16127 Zero the free space in the filesystem mounted on directory. The
16129 filesystem must be mounted read-write.
16130 The filesystem contents are not affected, but any free space in the
16132 filesystem is freed.
16133 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16135 either as an alternative to this, or after calling this, depending on
16136 your requirements.
16137 This function returns 0 on success or -1 on error.
16139 This long-running command can generate progress notification messages
16141 so that the caller can display a progress bar or indicator. To receive
16142 these messages, the caller must register a progress event callback.
16143 See "GUESTFS_EVENT_PROGRESS".
16144 (Added in 1.17.18)
16146 guestfs_zerofree
16148 int
16149 guestfs_zerofree (guestfs_h *g,
16150 const char *device);
16151 This runs the zerofree program on "device". This program claims to
16153 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16154 it possible to compress the filesystem more effectively.
16155 You should not run this program if the filesystem is mounted.
16157 It is possible that using this program can damage the filesystem or
16159 data on the filesystem.
16160 This function returns 0 on success or -1 on error.
16162 This function depends on the feature "zerofree". See also
16164 "guestfs_feature_available".
16165 (Added in 1.0.26)
16167 guestfs_zfgrep
16169 char **
16170 guestfs_zfgrep (guestfs_h *g,
16171 const char *pattern,
16172 const char *path);
16173 This function is deprecated. In new code, use the "guestfs_grep" call
16175 instead.
16176 Deprecated functions will not be removed from the API, but the fact
16178 that they are deprecated indicates that there are problems with correct
16179 use of these functions.
16180 This calls the external "zfgrep" program and returns the matching
16182 lines.
16183 This function returns a NULL-terminated array of strings (like
16185 environ(3)), or NULL if there was an error. The caller must free the
16186 strings and the array after use.
16187 Because of the message protocol, there is a transfer limit of somewhere
16189 between 2MB and 4MB. See "PROTOCOL LIMITS".
16190 (Added in 1.0.66)
16192 guestfs_zfgrepi
16194 char **
16195 guestfs_zfgrepi (guestfs_h *g,
16196 const char *pattern,
16197 const char *path);
16198 This function is deprecated. In new code, use the "guestfs_grep" call
16200 instead.
16201 Deprecated functions will not be removed from the API, but the fact
16203 that they are deprecated indicates that there are problems with correct
16204 use of these functions.
16205 This calls the external "zfgrep -i" program and returns the matching
16207 lines.
16208 This function returns a NULL-terminated array of strings (like
16210 environ(3)), or NULL if there was an error. The caller must free the
16211 strings and the array after use.
16212 Because of the message protocol, there is a transfer limit of somewhere
16214 between 2MB and 4MB. See "PROTOCOL LIMITS".
16215 (Added in 1.0.66)
16217 guestfs_zfile
16219 char *
16220 guestfs_zfile (guestfs_h *g,
16221 const char *meth,
16222 const char *path);
16223 This function is deprecated. In new code, use the "guestfs_file" call
16225 instead.
16226 Deprecated functions will not be removed from the API, but the fact
16228 that they are deprecated indicates that there are problems with correct
16229 use of these functions.
16230 This command runs file after first decompressing "path" using "method".
16232 "method" must be one of "gzip", "compress" or "bzip2".
16234 Since 1.0.63, use "guestfs_file" instead which can now process
16236 compressed files.
16237 This function returns a string, or NULL on error. The caller must free
16239 the returned string after use.
16240 (Added in 1.0.59)
16242 guestfs_zgrep
16244 char **
16245 guestfs_zgrep (guestfs_h *g,
16246 const char *regex,
16247 const char *path);
16248 This function is deprecated. In new code, use the "guestfs_grep" call
16250 instead.
16251 Deprecated functions will not be removed from the API, but the fact
16253 that they are deprecated indicates that there are problems with correct
16254 use of these functions.
16255 This calls the external "zgrep" program and returns the matching lines.
16257 This function returns a NULL-terminated array of strings (like
16259 environ(3)), or NULL if there was an error. The caller must free the
16260 strings and the array after use.
16261 Because of the message protocol, there is a transfer limit of somewhere
16263 between 2MB and 4MB. See "PROTOCOL LIMITS".
16264 (Added in 1.0.66)
16266 guestfs_zgrepi
16268 char **
16269 guestfs_zgrepi (guestfs_h *g,
16270 const char *regex,
16271 const char *path);
16272 This function is deprecated. In new code, use the "guestfs_grep" call
16274 instead.
16275 Deprecated functions will not be removed from the API, but the fact
16277 that they are deprecated indicates that there are problems with correct
16278 use of these functions.
16279 This calls the external "zgrep -i" program and returns the matching
16281 lines.
16282 This function returns a NULL-terminated array of strings (like
16284 environ(3)), or NULL if there was an error. The caller must free the
16285 strings and the array after use.
16286 Because of the message protocol, there is a transfer limit of somewhere
16288 between 2MB and 4MB. See "PROTOCOL LIMITS".
16289 (Added in 1.0.66)
16291
16293 guestfs_int_bool
16294 struct guestfs_int_bool {
16295 int32_t i;
16296 int32_t b;
16297 };
16298 struct guestfs_int_bool_list {
16300 uint32_t len; /* Number of elements in list. */
16301 struct guestfs_int_bool *val; /* Elements. */
16302 };
16303 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16305 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16306 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16308 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16309 void guestfs_free_int_bool (struct guestfs_int_bool *);
16311 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16312 guestfs_lvm_pv
16314 struct guestfs_lvm_pv {
16315 char *pv_name;
16316 /* The next field is NOT nul-terminated, be careful when printing it: */
16317 char pv_uuid[32];
16318 char *pv_fmt;
16319 uint64_t pv_size;
16320 uint64_t dev_size;
16321 uint64_t pv_free;
16322 uint64_t pv_used;
16323 char *pv_attr;
16324 int64_t pv_pe_count;
16325 int64_t pv_pe_alloc_count;
16326 char *pv_tags;
16327 uint64_t pe_start;
16328 int64_t pv_mda_count;
16329 uint64_t pv_mda_free;
16330 };
16331 struct guestfs_lvm_pv_list {
16333 uint32_t len; /* Number of elements in list. */
16334 struct guestfs_lvm_pv *val; /* Elements. */
16335 };
16336 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16338 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16339 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16341 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16342 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16344 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16345 guestfs_lvm_vg
16347 struct guestfs_lvm_vg {
16348 char *vg_name;
16349 /* The next field is NOT nul-terminated, be careful when printing it: */
16350 char vg_uuid[32];
16351 char *vg_fmt;
16352 char *vg_attr;
16353 uint64_t vg_size;
16354 uint64_t vg_free;
16355 char *vg_sysid;
16356 uint64_t vg_extent_size;
16357 int64_t vg_extent_count;
16358 int64_t vg_free_count;
16359 int64_t max_lv;
16360 int64_t max_pv;
16361 int64_t pv_count;
16362 int64_t lv_count;
16363 int64_t snap_count;
16364 int64_t vg_seqno;
16365 char *vg_tags;
16366 int64_t vg_mda_count;
16367 uint64_t vg_mda_free;
16368 };
16369 struct guestfs_lvm_vg_list {
16371 uint32_t len; /* Number of elements in list. */
16372 struct guestfs_lvm_vg *val; /* Elements. */
16373 };
16374 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16376 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16377 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16379 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16380 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16382 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16383 guestfs_lvm_lv
16385 struct guestfs_lvm_lv {
16386 char *lv_name;
16387 /* The next field is NOT nul-terminated, be careful when printing it: */
16388 char lv_uuid[32];
16389 char *lv_attr;
16390 int64_t lv_major;
16391 int64_t lv_minor;
16392 int64_t lv_kernel_major;
16393 int64_t lv_kernel_minor;
16394 uint64_t lv_size;
16395 int64_t seg_count;
16396 char *origin;
16397 /* The next field is [0..100] or -1 meaning 'not present': */
16398 float snap_percent;
16399 /* The next field is [0..100] or -1 meaning 'not present': */
16400 float copy_percent;
16401 char *move_pv;
16402 char *lv_tags;
16403 char *mirror_log;
16404 char *modules;
16405 };
16406 struct guestfs_lvm_lv_list {
16408 uint32_t len; /* Number of elements in list. */
16409 struct guestfs_lvm_lv *val; /* Elements. */
16410 };
16411 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16413 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16414 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16416 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16417 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16419 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16420 guestfs_stat
16422 struct guestfs_stat {
16423 int64_t dev;
16424 int64_t ino;
16425 int64_t mode;
16426 int64_t nlink;
16427 int64_t uid;
16428 int64_t gid;
16429 int64_t rdev;
16430 int64_t size;
16431 int64_t blksize;
16432 int64_t blocks;
16433 int64_t atime;
16434 int64_t mtime;
16435 int64_t ctime;
16436 };
16437 struct guestfs_stat_list {
16439 uint32_t len; /* Number of elements in list. */
16440 struct guestfs_stat *val; /* Elements. */
16441 };
16442 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16444 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16445 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16447 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16448 void guestfs_free_stat (struct guestfs_stat *);
16450 void guestfs_free_stat_list (struct guestfs_stat_list *);
16451 guestfs_statns
16453 struct guestfs_statns {
16454 int64_t st_dev;
16455 int64_t st_ino;
16456 int64_t st_mode;
16457 int64_t st_nlink;
16458 int64_t st_uid;
16459 int64_t st_gid;
16460 int64_t st_rdev;
16461 int64_t st_size;
16462 int64_t st_blksize;
16463 int64_t st_blocks;
16464 int64_t st_atime_sec;
16465 int64_t st_atime_nsec;
16466 int64_t st_mtime_sec;
16467 int64_t st_mtime_nsec;
16468 int64_t st_ctime_sec;
16469 int64_t st_ctime_nsec;
16470 int64_t st_spare1;
16471 int64_t st_spare2;
16472 int64_t st_spare3;
16473 int64_t st_spare4;
16474 int64_t st_spare5;
16475 int64_t st_spare6;
16476 };
16477 struct guestfs_statns_list {
16479 uint32_t len; /* Number of elements in list. */
16480 struct guestfs_statns *val; /* Elements. */
16481 };
16482 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16484 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16485 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16487 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16488 void guestfs_free_statns (struct guestfs_statns *);
16490 void guestfs_free_statns_list (struct guestfs_statns_list *);
16491 guestfs_statvfs
16493 struct guestfs_statvfs {
16494 int64_t bsize;
16495 int64_t frsize;
16496 int64_t blocks;
16497 int64_t bfree;
16498 int64_t bavail;
16499 int64_t files;
16500 int64_t ffree;
16501 int64_t favail;
16502 int64_t fsid;
16503 int64_t flag;
16504 int64_t namemax;
16505 };
16506 struct guestfs_statvfs_list {
16508 uint32_t len; /* Number of elements in list. */
16509 struct guestfs_statvfs *val; /* Elements. */
16510 };
16511 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16513 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16514 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16516 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16517 void guestfs_free_statvfs (struct guestfs_statvfs *);
16519 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16520 guestfs_dirent
16522 struct guestfs_dirent {
16523 int64_t ino;
16524 char ftyp;
16525 char *name;
16526 };
16527 struct guestfs_dirent_list {
16529 uint32_t len; /* Number of elements in list. */
16530 struct guestfs_dirent *val; /* Elements. */
16531 };
16532 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16534 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16535 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16537 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16538 void guestfs_free_dirent (struct guestfs_dirent *);
16540 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16541 guestfs_version
16543 struct guestfs_version {
16544 int64_t major;
16545 int64_t minor;
16546 int64_t release;
16547 char *extra;
16548 };
16549 struct guestfs_version_list {
16551 uint32_t len; /* Number of elements in list. */
16552 struct guestfs_version *val; /* Elements. */
16553 };
16554 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16556 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16557 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16559 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16560 void guestfs_free_version (struct guestfs_version *);
16562 void guestfs_free_version_list (struct guestfs_version_list *);
16563 guestfs_xattr
16565 struct guestfs_xattr {
16566 char *attrname;
16567 /* The next two fields describe a byte array. */
16568 uint32_t attrval_len;
16569 char *attrval;
16570 };
16571 struct guestfs_xattr_list {
16573 uint32_t len; /* Number of elements in list. */
16574 struct guestfs_xattr *val; /* Elements. */
16575 };
16576 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16578 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16579 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
16581 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
16582 void guestfs_free_xattr (struct guestfs_xattr *);
16584 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
16585 guestfs_inotify_event
16587 struct guestfs_inotify_event {
16588 int64_t in_wd;
16589 uint32_t in_mask;
16590 uint32_t in_cookie;
16591 char *in_name;
16592 };
16593 struct guestfs_inotify_event_list {
16595 uint32_t len; /* Number of elements in list. */
16596 struct guestfs_inotify_event *val; /* Elements. */
16597 };
16598 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
16600 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
16601 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
16603 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
16604 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
16606 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
16607 guestfs_partition
16609 struct guestfs_partition {
16610 int32_t part_num;
16611 uint64_t part_start;
16612 uint64_t part_end;
16613 uint64_t part_size;
16614 };
16615 struct guestfs_partition_list {
16617 uint32_t len; /* Number of elements in list. */
16618 struct guestfs_partition *val; /* Elements. */
16619 };
16620 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
16622 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
16623 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
16625 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
16626 void guestfs_free_partition (struct guestfs_partition *);
16628 void guestfs_free_partition_list (struct guestfs_partition_list *);
16629 guestfs_application
16631 struct guestfs_application {
16632 char *app_name;
16633 char *app_display_name;
16634 int32_t app_epoch;
16635 char *app_version;
16636 char *app_release;
16637 char *app_install_path;
16638 char *app_trans_path;
16639 char *app_publisher;
16640 char *app_url;
16641 char *app_source_package;
16642 char *app_summary;
16643 char *app_description;
16644 };
16645 struct guestfs_application_list {
16647 uint32_t len; /* Number of elements in list. */
16648 struct guestfs_application *val; /* Elements. */
16649 };
16650 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
16652 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
16653 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
16655 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
16656 void guestfs_free_application (struct guestfs_application *);
16658 void guestfs_free_application_list (struct guestfs_application_list *);
16659 guestfs_application2
16661 struct guestfs_application2 {
16662 char *app2_name;
16663 char *app2_display_name;
16664 int32_t app2_epoch;
16665 char *app2_version;
16666 char *app2_release;
16667 char *app2_arch;
16668 char *app2_install_path;
16669 char *app2_trans_path;
16670 char *app2_publisher;
16671 char *app2_url;
16672 char *app2_source_package;
16673 char *app2_summary;
16674 char *app2_description;
16675 char *app2_spare1;
16676 char *app2_spare2;
16677 char *app2_spare3;
16678 char *app2_spare4;
16679 };
16680 struct guestfs_application2_list {
16682 uint32_t len; /* Number of elements in list. */
16683 struct guestfs_application2 *val; /* Elements. */
16684 };
16685 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
16687 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
16688 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
16690 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
16691 void guestfs_free_application2 (struct guestfs_application2 *);
16693 void guestfs_free_application2_list (struct guestfs_application2_list *);
16694 guestfs_isoinfo
16696 struct guestfs_isoinfo {
16697 char *iso_system_id;
16698 char *iso_volume_id;
16699 uint32_t iso_volume_space_size;
16700 uint32_t iso_volume_set_size;
16701 uint32_t iso_volume_sequence_number;
16702 uint32_t iso_logical_block_size;
16703 char *iso_volume_set_id;
16704 char *iso_publisher_id;
16705 char *iso_data_preparer_id;
16706 char *iso_application_id;
16707 char *iso_copyright_file_id;
16708 char *iso_abstract_file_id;
16709 char *iso_bibliographic_file_id;
16710 int64_t iso_volume_creation_t;
16711 int64_t iso_volume_modification_t;
16712 int64_t iso_volume_expiration_t;
16713 int64_t iso_volume_effective_t;
16714 };
16715 struct guestfs_isoinfo_list {
16717 uint32_t len; /* Number of elements in list. */
16718 struct guestfs_isoinfo *val; /* Elements. */
16719 };
16720 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
16722 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
16723 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
16725 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
16726 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
16728 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
16729 guestfs_mdstat
16731 struct guestfs_mdstat {
16732 char *mdstat_device;
16733 int32_t mdstat_index;
16734 char *mdstat_flags;
16735 };
16736 struct guestfs_mdstat_list {
16738 uint32_t len; /* Number of elements in list. */
16739 struct guestfs_mdstat *val; /* Elements. */
16740 };
16741 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
16743 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
16744 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
16746 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
16747 void guestfs_free_mdstat (struct guestfs_mdstat *);
16749 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
16750 guestfs_btrfssubvolume
16752 struct guestfs_btrfssubvolume {
16753 uint64_t btrfssubvolume_id;
16754 uint64_t btrfssubvolume_top_level_id;
16755 char *btrfssubvolume_path;
16756 };
16757 struct guestfs_btrfssubvolume_list {
16759 uint32_t len; /* Number of elements in list. */
16760 struct guestfs_btrfssubvolume *val; /* Elements. */
16761 };
16762 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
16764 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
16765 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
16767 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
16768 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
16770 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
16771 guestfs_btrfsqgroup
16773 struct guestfs_btrfsqgroup {
16774 char *btrfsqgroup_id;
16775 uint64_t btrfsqgroup_rfer;
16776 uint64_t btrfsqgroup_excl;
16777 };
16778 struct guestfs_btrfsqgroup_list {
16780 uint32_t len; /* Number of elements in list. */
16781 struct guestfs_btrfsqgroup *val; /* Elements. */
16782 };
16783 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
16785 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
16786 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
16788 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
16789 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
16791 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
16792 guestfs_btrfsbalance
16794 struct guestfs_btrfsbalance {
16795 char *btrfsbalance_status;
16796 uint64_t btrfsbalance_total;
16797 uint64_t btrfsbalance_balanced;
16798 uint64_t btrfsbalance_considered;
16799 uint64_t btrfsbalance_left;
16800 };
16801 struct guestfs_btrfsbalance_list {
16803 uint32_t len; /* Number of elements in list. */
16804 struct guestfs_btrfsbalance *val; /* Elements. */
16805 };
16806 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
16808 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
16809 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
16811 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
16812 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
16814 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
16815 guestfs_btrfsscrub
16817 struct guestfs_btrfsscrub {
16818 uint64_t btrfsscrub_data_extents_scrubbed;
16819 uint64_t btrfsscrub_tree_extents_scrubbed;
16820 uint64_t btrfsscrub_data_bytes_scrubbed;
16821 uint64_t btrfsscrub_tree_bytes_scrubbed;
16822 uint64_t btrfsscrub_read_errors;
16823 uint64_t btrfsscrub_csum_errors;
16824 uint64_t btrfsscrub_verify_errors;
16825 uint64_t btrfsscrub_no_csum;
16826 uint64_t btrfsscrub_csum_discards;
16827 uint64_t btrfsscrub_super_errors;
16828 uint64_t btrfsscrub_malloc_errors;
16829 uint64_t btrfsscrub_uncorrectable_errors;
16830 uint64_t btrfsscrub_unverified_errors;
16831 uint64_t btrfsscrub_corrected_errors;
16832 uint64_t btrfsscrub_last_physical;
16833 };
16834 struct guestfs_btrfsscrub_list {
16836 uint32_t len; /* Number of elements in list. */
16837 struct guestfs_btrfsscrub *val; /* Elements. */
16838 };
16839 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
16841 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
16842 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
16844 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
16845 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
16847 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
16848 guestfs_xfsinfo
16850 struct guestfs_xfsinfo {
16851 char *xfs_mntpoint;
16852 uint32_t xfs_inodesize;
16853 uint32_t xfs_agcount;
16854 uint32_t xfs_agsize;
16855 uint32_t xfs_sectsize;
16856 uint32_t xfs_attr;
16857 uint32_t xfs_blocksize;
16858 uint64_t xfs_datablocks;
16859 uint32_t xfs_imaxpct;
16860 uint32_t xfs_sunit;
16861 uint32_t xfs_swidth;
16862 uint32_t xfs_dirversion;
16863 uint32_t xfs_dirblocksize;
16864 uint32_t xfs_cimode;
16865 char *xfs_logname;
16866 uint32_t xfs_logblocksize;
16867 uint32_t xfs_logblocks;
16868 uint32_t xfs_logversion;
16869 uint32_t xfs_logsectsize;
16870 uint32_t xfs_logsunit;
16871 uint32_t xfs_lazycount;
16872 char *xfs_rtname;
16873 uint32_t xfs_rtextsize;
16874 uint64_t xfs_rtblocks;
16875 uint64_t xfs_rtextents;
16876 };
16877 struct guestfs_xfsinfo_list {
16879 uint32_t len; /* Number of elements in list. */
16880 struct guestfs_xfsinfo *val; /* Elements. */
16881 };
16882 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
16884 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
16885 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
16887 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
16888 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
16890 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
16891 guestfs_utsname
16893 struct guestfs_utsname {
16894 char *uts_sysname;
16895 char *uts_release;
16896 char *uts_version;
16897 char *uts_machine;
16898 };
16899 struct guestfs_utsname_list {
16901 uint32_t len; /* Number of elements in list. */
16902 struct guestfs_utsname *val; /* Elements. */
16903 };
16904 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
16906 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
16907 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
16909 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
16910 void guestfs_free_utsname (struct guestfs_utsname *);
16912 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
16913 guestfs_hivex_node
16915 struct guestfs_hivex_node {
16916 int64_t hivex_node_h;
16917 };
16918 struct guestfs_hivex_node_list {
16920 uint32_t len; /* Number of elements in list. */
16921 struct guestfs_hivex_node *val; /* Elements. */
16922 };
16923 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
16925 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
16926 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
16928 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
16929 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
16931 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
16932 guestfs_hivex_value
16934 struct guestfs_hivex_value {
16935 int64_t hivex_value_h;
16936 };
16937 struct guestfs_hivex_value_list {
16939 uint32_t len; /* Number of elements in list. */
16940 struct guestfs_hivex_value *val; /* Elements. */
16941 };
16942 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
16944 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
16945 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
16947 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
16948 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
16950 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
16951 guestfs_internal_mountable
16953 struct guestfs_internal_mountable {
16954 int32_t im_type;
16955 char *im_device;
16956 char *im_volume;
16957 };
16958 struct guestfs_internal_mountable_list {
16960 uint32_t len; /* Number of elements in list. */
16961 struct guestfs_internal_mountable *val; /* Elements. */
16962 };
16963 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
16965 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
16966 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
16968 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
16969 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
16971 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
16972 guestfs_tsk_dirent
16974 struct guestfs_tsk_dirent {
16975 uint64_t tsk_inode;
16976 char tsk_type;
16977 int64_t tsk_size;
16978 char *tsk_name;
16979 uint32_t tsk_flags;
16980 int64_t tsk_atime_sec;
16981 int64_t tsk_atime_nsec;
16982 int64_t tsk_mtime_sec;
16983 int64_t tsk_mtime_nsec;
16984 int64_t tsk_ctime_sec;
16985 int64_t tsk_ctime_nsec;
16986 int64_t tsk_crtime_sec;
16987 int64_t tsk_crtime_nsec;
16988 int64_t tsk_nlink;
16989 char *tsk_link;
16990 int64_t tsk_spare1;
16991 };
16992 struct guestfs_tsk_dirent_list {
16994 uint32_t len; /* Number of elements in list. */
16995 struct guestfs_tsk_dirent *val; /* Elements. */
16996 };
16997 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
16999 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17000 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17002 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17003 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17005 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17006 guestfs_yara_detection
17008 struct guestfs_yara_detection {
17009 char *yara_name;
17010 char *yara_rule;
17011 };
17012 struct guestfs_yara_detection_list {
17014 uint32_t len; /* Number of elements in list. */
17015 struct guestfs_yara_detection *val; /* Elements. */
17016 };
17017 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17019 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17020 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17022 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17023 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17025 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17026
17028 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17029 Using "guestfs_available" you can test availability of the following
17030 groups of functions. This test queries the appliance to see if the
17031 appliance you are currently using supports the functionality.
17032 acl The following functions: "guestfs_acl_delete_def_file"
17034 "guestfs_acl_get_file" "guestfs_acl_set_file"
17035 blkdiscard
17037 The following functions: "guestfs_blkdiscard"
17038 blkdiscardzeroes
17040 The following functions: "guestfs_blkdiscardzeroes"
17041 btrfs
17043 The following functions: "guestfs_btrfs_balance_cancel"
17044 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17045 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17046 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17047 "guestfs_btrfs_filesystem_defragment"
17048 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17049 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17050 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17051 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17052 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17053 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17054 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17055 "guestfs_btrfs_rescue_chunk_recover"
17056 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17057 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17058 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17059 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17060 "guestfs_btrfs_subvolume_get_default"
17061 "guestfs_btrfs_subvolume_list"
17062 "guestfs_btrfs_subvolume_set_default"
17063 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17064 "guestfs_btrfstune_enable_extended_inode_refs"
17065 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17066 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17067 extlinux
17069 The following functions: "guestfs_extlinux"
17070 fstrim
17072 The following functions: "guestfs_fstrim"
17073 gdisk
17075 The following functions: "guestfs_part_expand_gpt"
17076 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17077 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17078 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17079 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17080 "guestfs_part_set_gpt_type"
17081 grub
17083 The following functions: "guestfs_grub_install"
17084 hivex
17086 The following functions: "guestfs_hivex_close"
17087 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17088 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17089 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17090 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17091 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17092 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17093 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17094 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17095 inotify
17097 The following functions: "guestfs_inotify_add_watch"
17098 "guestfs_inotify_close" "guestfs_inotify_files"
17099 "guestfs_inotify_init" "guestfs_inotify_read"
17100 "guestfs_inotify_rm_watch"
17101 journal
17103 The following functions: "guestfs_internal_journal_get"
17104 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17105 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17106 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17107 "guestfs_journal_skip"
17108 ldm The following functions: "guestfs_ldmtool_create_all"
17110 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17111 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17112 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17113 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17114 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17115 "guestfs_list_ldm_volumes"
17116 libtsk
17118 The following functions: "guestfs_internal_filesystem_walk"
17119 "guestfs_internal_find_inode"
17120 libyara
17122 The following functions: "guestfs_internal_yara_scan"
17123 "guestfs_yara_destroy" "guestfs_yara_load"
17124 linuxcaps
17126 The following functions: "guestfs_cap_get_file"
17127 "guestfs_cap_set_file"
17128 linuxfsuuid
17130 The following functions: "guestfs_mke2fs_JU"
17131 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17132 "guestfs_swapon_uuid"
17133 linuxmodules
17135 The following functions: "guestfs_modprobe"
17136 linuxxattrs
17138 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17139 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17140 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17141 "guestfs_removexattr" "guestfs_setxattr"
17142 luks
17144 The following functions: "guestfs_luks_add_key"
17145 "guestfs_luks_close" "guestfs_luks_format"
17146 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17147 "guestfs_luks_open" "guestfs_luks_open_ro"
17148 lvm2
17150 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17151 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17152 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17153 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17154 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17155 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17156 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17157 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17158 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17159 "guestfs_vgs" "guestfs_vgs_full"
17160 mdadm
17162 The following functions: "guestfs_md_create" "guestfs_md_detail"
17163 "guestfs_md_stat" "guestfs_md_stop"
17164 mknod
17166 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17167 "guestfs_mknod_b" "guestfs_mknod_c"
17168 ntfs3g
17170 The following functions: "guestfs_ntfs_3g_probe"
17171 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17172 ntfsprogs
17174 The following functions: "guestfs_ntfsresize"
17175 "guestfs_ntfsresize_size"
17176 rsync
17178 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17179 "guestfs_rsync_out"
17180 scrub
17182 The following functions: "guestfs_scrub_device"
17183 "guestfs_scrub_file" "guestfs_scrub_freespace"
17184 selinux
17186 The following functions: "guestfs_getcon" "guestfs_setcon"
17187 selinuxrelabel
17189 The following functions: "guestfs_selinux_relabel"
17190 sleuthkit
17192 The following functions: "guestfs_download_blocks"
17193 "guestfs_download_inode"
17194 squashfs
17196 The following functions: "guestfs_mksquashfs"
17197 syslinux
17199 The following functions: "guestfs_syslinux"
17200 wipefs
17202 The following functions: "guestfs_wipefs"
17203 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17205 "guestfs_xfs_info" "guestfs_xfs_repair"
17206 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17208 zerofree
17210 The following functions: "guestfs_zerofree"
17211 FILESYSTEM AVAILABLE
17213 The "guestfs_filesystem_available" call tests whether a filesystem type
17214 is supported by the appliance kernel.
17215 This is mainly useful as a negative test. If this returns true, it
17217 doesn't mean that a particular filesystem can be mounted, since
17218 filesystems can fail for other reasons such as it being a later version
17219 of the filesystem, or having incompatible features.
17220 GUESTFISH supported COMMAND
17222 In guestfish(3) there is a handy interactive command "supported" which
17223 prints out the available groups and whether they are supported by this
17224 build of libguestfs. Note however that you have to do "run" first.
17225 SINGLE CALLS AT COMPILE TIME
17227 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17228 function, such as:
17229 #define GUESTFS_HAVE_DD 1
17231 if "guestfs_dd" is available.
17233 Before version 1.5.8, if you needed to test whether a single libguestfs
17235 function is available at compile time, we recommended using build tools
17236 such as autoconf or cmake. For example in autotools you could use:
17237 AC_CHECK_LIB([guestfs],[guestfs_create])
17239 AC_CHECK_FUNCS([guestfs_dd])
17240 which would result in "HAVE_GUESTFS_DD" being either defined or not
17242 defined in your program.
17243 SINGLE CALLS AT RUN TIME
17245 Testing at compile time doesn't guarantee that a function really exists
17246 in the library. The reason is that you might be dynamically linked
17247 against a previous libguestfs.so (dynamic library) which doesn't have
17248 the call. This situation unfortunately results in a segmentation
17249 fault, which is a shortcoming of the C dynamic linking system itself.
17250 You can use dlopen(3) to test if a function is available at run time,
17252 as in this example program (note that you still need the compile time
17253 check as well):
17254 #include <stdio.h>
17256 #include <stdlib.h>
17257 #include <unistd.h>
17258 #include <dlfcn.h>
17259 #include <guestfs.h>
17260 main ()
17262 {
17263 #ifdef GUESTFS_HAVE_DD
17264 void *dl;
17265 int has_function;
17266 /* Test if the function guestfs_dd is really available. */
17268 dl = dlopen (NULL, RTLD_LAZY);
17269 if (!dl) {
17270 fprintf (stderr, "dlopen: %s\n", dlerror ());
17271 exit (EXIT_FAILURE);
17272 }
17273 has_function = dlsym (dl, "guestfs_dd") != NULL;
17274 dlclose (dl);
17275 if (!has_function)
17277 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17278 else {
17279 printf ("this libguestfs.so has guestfs_dd function\n");
17280 /* Now it's safe to call
17281 guestfs_dd (g, "foo", "bar");
17282 */
17283 }
17284 #else
17285 printf ("guestfs_dd function was not found at compile time\n");
17286 #endif
17287 }
17288 You may think the above is an awful lot of hassle, and it is. There
17290 are other ways outside of the C linking system to ensure that this kind
17291 of incompatibility never arises, such as using package versioning:
17292 Requires: libguestfs >= 1.0.80
17294
17296 A recent feature of the API is the introduction of calls which take
17297 optional arguments. In C these are declared 3 ways. The main way is
17298 as a call which takes variable arguments (ie. "..."), as in this
17299 example:
17300 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17302 Call this with a list of optional arguments, terminated by "-1". So to
17304 call with no optional arguments specified:
17305 guestfs_add_drive_opts (g, filename, -1);
17307 With a single optional argument:
17309 guestfs_add_drive_opts (g, filename,
17311 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17312 -1);
17313 With two:
17315 guestfs_add_drive_opts (g, filename,
17317 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17318 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17319 -1);
17320 and so forth. Don’t forget the terminating "-1" otherwise Bad Things
17322 will happen!
17323 USING va_list FOR OPTIONAL ARGUMENTS
17325 The second variant has the same name with the suffix "_va", which works
17326 the same way but takes a "va_list". See the C manual for details. For
17327 the example function, this is declared:
17328 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17330 va_list args);
17331 CONSTRUCTING OPTIONAL ARGUMENTS
17333 The third variant is useful where you need to construct these calls.
17334 You pass in a structure where you fill in the optional fields. The
17335 structure has a bitmask as the first element which you must set to
17336 indicate which fields you have filled in. For our example function the
17337 structure and call are declared:
17338 struct guestfs_add_drive_opts_argv {
17340 uint64_t bitmask;
17341 int readonly;
17342 const char *format;
17343 /* ... */
17344 };
17345 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17346 const struct guestfs_add_drive_opts_argv *optargs);
17347 You could call it like this:
17349 struct guestfs_add_drive_opts_argv optargs = {
17351 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17352 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17353 .readonly = 1,
17354 .format = "qcow2"
17355 };
17356 guestfs_add_drive_opts_argv (g, filename, &optargs);
17358 Notes:
17360 · The "_BITMASK" suffix on each option name when specifying the
17362 bitmask.
17363 · You do not need to fill in all fields of the structure.
17365 · There must be a one-to-one correspondence between fields of the
17367 structure that are filled in, and bits set in the bitmask.
17368 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17370 In other languages, optional arguments are expressed in the way that is
17371 natural for that language. We refer you to the language-specific
17372 documentation for more details on that.
17373 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17375
17377 SETTING CALLBACKS TO HANDLE EVENTS
17378 Note: This section documents the generic event mechanism introduced in
17379 libguestfs 1.10, which you should use in new code if possible. The old
17380 functions "guestfs_set_log_message_callback",
17381 "guestfs_set_subprocess_quit_callback",
17382 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17383 "guestfs_set_progress_callback" are no longer documented in this manual
17384 page. Because of the ABI guarantee, the old functions continue to
17385 work.
17386 Handles generate events when certain things happen, such as log
17388 messages being generated, progress messages during long-running
17389 operations, or the handle being closed. The API calls described below
17390 let you register a callback to be called when events happen. You can
17391 register multiple callbacks (for the same, different or overlapping
17392 sets of events), and individually remove callbacks. If callbacks are
17393 not removed, then they remain in force until the handle is closed.
17394 In the current implementation, events are only generated synchronously:
17396 that means that events (and hence callbacks) can only happen while you
17397 are in the middle of making another libguestfs call. The callback is
17398 called in the same thread.
17399 Events may contain a payload, usually nothing (void), an array of 64
17401 bit unsigned integers, or a message buffer. Payloads are discussed
17402 later on.
17403 CLASSES OF EVENTS
17405 GUESTFS_EVENT_CLOSE (payload type: void)
17406 The callback function will be called while the handle is being
17407 closed (synchronously from "guestfs_close").
17408 Note that libguestfs installs an atexit(3) handler to try to clean
17410 up handles that are open when the program exits. This means that
17411 this callback might be called indirectly from exit(3), which can
17412 cause unexpected problems in higher-level languages (eg. if your
17413 HLL interpreter has already been cleaned up by the time this is
17414 called, and if your callback then jumps into some HLL function).
17415 If no callback is registered: the handle is closed without any
17417 callback being invoked.
17418 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17420 The callback function will be called when the child process quits,
17421 either asynchronously or if killed by "guestfs_kill_subprocess".
17422 (This corresponds to a transition from any state to the CONFIG
17423 state).
17424 If no callback is registered: the event is ignored.
17426 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17428 The callback function will be called when the child process becomes
17429 ready first time after it has been launched. (This corresponds to
17430 a transition from LAUNCHING to the READY state).
17431 If no callback is registered: the event is ignored.
17433 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17435 Some long-running operations can generate progress messages. If
17436 this callback is registered, then it will be called each time a
17437 progress message is generated (usually two seconds after the
17438 operation started, and three times per second thereafter until it
17439 completes, although the frequency may change in future versions).
17440 The callback receives in the payload four unsigned 64 bit numbers
17442 which are (in order): "proc_nr", "serial", "position", "total".
17443 The units of "total" are not defined, although for some operations
17445 "total" may relate in some way to the amount of data to be
17446 transferred (eg. in bytes or megabytes), and "position" may be the
17447 portion which has been transferred.
17448 The only defined and stable parts of the API are:
17450 · The callback can display to the user some type of progress bar
17452 or indicator which shows the ratio of "position":"total".
17453 · 0 <= "position" <= "total"
17455 · If any progress notification is sent during a call, then a
17457 final progress notification is always sent when "position" =
17458 "total" (unless the call fails with an error).
17459 This is to simplify caller code, so callers can easily set the
17461 progress indicator to "100%" at the end of the operation,
17462 without requiring special code to detect this case.
17463 · For some calls we are unable to estimate the progress of the
17465 call, but we can still generate progress messages to indicate
17466 activity. This is known as "pulse mode", and is directly
17467 supported by certain progress bar implementations (eg.
17468 GtkProgressBar).
17469 For these calls, zero or more progress messages are generated
17471 with "position = 0" and "total = 1", followed by a final
17472 message with "position = total = 1".
17473 As noted above, if the call fails with an error then the final
17475 message may not be generated.
17476 The callback also receives the procedure number ("proc_nr") and
17478 serial number ("serial") of the call. These are only useful for
17479 debugging protocol issues, and the callback can normally ignore
17480 them. The callback may want to print these numbers in error
17481 messages or debugging messages.
17482 If no callback is registered: progress messages are discarded.
17484 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17486 The callback function is called whenever a log message is generated
17487 by qemu, the appliance kernel, guestfsd (daemon), or utility
17488 programs.
17489 If the verbose flag ("guestfs_set_verbose") is set before launch
17491 ("guestfs_launch") then additional debug messages are generated.
17492 If no callback is registered: the messages are discarded unless the
17494 verbose flag is set in which case they are sent to stderr. You can
17495 override the printing of verbose messages to stderr by setting up a
17496 callback.
17497 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17499 The callback function is called whenever a log message is generated
17500 by the library part of libguestfs.
17501 If the verbose flag ("guestfs_set_verbose") is set then additional
17503 debug messages are generated.
17504 If no callback is registered: the messages are discarded unless the
17506 verbose flag is set in which case they are sent to stderr. You can
17507 override the printing of verbose messages to stderr by setting up a
17508 callback.
17509 GUESTFS_EVENT_WARNING (payload type: message buffer)
17511 The callback function is called whenever a warning message is
17512 generated by the library part of libguestfs.
17513 If no callback is registered: the messages are printed to stderr.
17515 You can override the printing of warning messages to stderr by
17516 setting up a callback.
17517 GUESTFS_EVENT_TRACE (payload type: message buffer)
17519 The callback function is called whenever a trace message is
17520 generated. This only applies if the trace flag
17521 ("guestfs_set_trace") is set.
17522 If no callback is registered: the messages are sent to stderr. You
17524 can override the printing of trace messages to stderr by setting up
17525 a callback.
17526 GUESTFS_EVENT_ENTER (payload type: function name)
17528 The callback function is called whenever a libguestfs function is
17529 entered.
17530 The payload is a string which contains the name of the function
17532 that we are entering (not including "guestfs_" prefix).
17533 Note that libguestfs functions can call themselves, so you may see
17535 many events from a single call. A few libguestfs functions do not
17536 generate this event.
17537 If no callback is registered: the event is ignored.
17539 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17541 For any API function that opens a libvirt connection, this event
17542 may be generated to indicate that libvirt demands authentication
17543 information. See "LIBVIRT AUTHENTICATION" below.
17544 If no callback is registered: "virConnectAuthPtrDefault" is used
17546 (suitable for command-line programs only).
17547 EVENT API
17549 guestfs_set_event_callback
17550 int guestfs_set_event_callback (guestfs_h *g,
17552 guestfs_event_callback cb,
17553 uint64_t event_bitmask,
17554 int flags,
17555 void *opaque);
17556 This function registers a callback ("cb") for all event classes in the
17558 "event_bitmask".
17559 For example, to register for all log message events, you could call
17561 this function with the bitmask
17562 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17563 To register a single callback for all possible classes of events, use
17564 "GUESTFS_EVENT_ALL".
17565 "flags" should always be passed as 0.
17567 "opaque" is an opaque pointer which is passed to the callback. You can
17569 use it for any purpose.
17570 The return value is the event handle (an integer) which you can use to
17572 delete the callback (see below).
17573 If there is an error, this function returns "-1", and sets the error in
17575 the handle in the usual way (see "guestfs_last_error" etc.)
17576 Callbacks remain in effect until they are deleted, or until the handle
17578 is closed.
17579 In the case where multiple callbacks are registered for a particular
17581 event class, all of the callbacks are called. The order in which
17582 multiple callbacks are called is not defined.
17583 guestfs_delete_event_callback
17585 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
17587 Delete a callback that was previously registered. "event_handle"
17589 should be the integer that was returned by a previous call to
17590 "guestfs_set_event_callback" on the same handle.
17591 guestfs_event_to_string
17593 char *guestfs_event_to_string (uint64_t event);
17595 "event" is either a single event or a bitmask of events. This returns
17597 a string representation (useful for debugging or printing events).
17598 A single event is returned as the name in lower case, eg. "close".
17600 A bitmask of several events is returned as a comma-separated list, eg.
17602 "close,progress".
17603 If zero is passed, then the empty string "" is returned.
17605 On success this returns a string. On error it returns NULL and sets
17607 "errno".
17608 The returned string must be freed by the caller.
17610 guestfs_event_callback
17612 typedef void (*guestfs_event_callback) (
17614 guestfs_h *g,
17615 void *opaque,
17616 uint64_t event,
17617 int event_handle,
17618 int flags,
17619 const char *buf, size_t buf_len,
17620 const uint64_t *array, size_t array_len);
17621 This is the type of the event callback function that you have to
17623 provide.
17624 The basic parameters are: the handle ("g"), the opaque user pointer
17626 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
17627 handle, and "flags" which in the current API you should ignore.
17628 The remaining parameters contain the event payload (if any). Each
17630 event may contain a payload, which usually relates to the event class,
17631 but for future proofing your code should be written to handle any
17632 payload for any event class.
17633 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
17635 there is no message buffer). Note that this message buffer can contain
17636 arbitrary 8 bit data, including NUL bytes.
17637 "array" and "array_len" is an array of 64 bit unsigned integers. At
17639 the moment this is only used for progress messages.
17640 EXAMPLE: CAPTURING LOG MESSAGES
17642 A working program demonstrating this can be found in
17643 examples/debug-logging.c in the source of libguestfs.
17644 One motivation for the generic event API was to allow GUI programs to
17646 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
17647 unconditionally to "stderr".
17648 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
17650 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
17651 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
17652 must capture error messages separately).
17653 Programs have to set up a callback to capture the classes of events of
17655 interest:
17656 int eh =
17658 guestfs_set_event_callback
17659 (g, message_callback,
17660 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
17661 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
17662 0, NULL) == -1)
17663 if (eh == -1) {
17664 // handle error in the usual way
17665 }
17666 The callback can then direct messages to the appropriate place. In
17668 this example, messages are directed to syslog:
17669 static void
17671 message_callback (
17672 guestfs_h *g,
17673 void *opaque,
17674 uint64_t event,
17675 int event_handle,
17676 int flags,
17677 const char *buf, size_t buf_len,
17678 const uint64_t *array, size_t array_len)
17679 {
17680 const int priority = LOG_USER|LOG_INFO;
17681 if (buf_len > 0)
17682 syslog (priority, "event 0x%lx: %s", event, buf);
17683 }
17684 LIBVIRT AUTHENTICATION
17686 Some libguestfs API calls can open libvirt connections. Currently the
17687 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
17688 backend has been selected. Libvirt connections may require
17689 authentication, for example if they need to access a remote server or
17690 to access root services from non-root. Libvirt authentication happens
17691 via a callback mechanism, see
17692 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
17693 You may provide libvirt authentication data by registering a callback
17695 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
17696 If no such event is registered, then libguestfs uses a libvirt function
17698 that provides command-line prompts ("virConnectAuthPtrDefault"). This
17699 is only suitable for command-line libguestfs programs.
17700 To provide authentication, first call
17702 "guestfs_set_libvirt_supported_credentials" with the list of
17703 credentials your program knows how to provide. Second, register a
17704 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
17705 will be called when libvirt is requesting authentication information.
17706 In the event handler, call "guestfs_get_libvirt_requested_credentials"
17708 to get a list of the credentials that libvirt is asking for. You then
17709 need to ask (eg. the user) for each credential, and call
17710 "guestfs_set_libvirt_requested_credential" with the answer. Note that
17711 for each credential, additional information may be available via the
17712 calls "guestfs_get_libvirt_requested_credential_prompt",
17713 "guestfs_get_libvirt_requested_credential_challenge" or
17714 "guestfs_get_libvirt_requested_credential_defresult".
17715 The example program below should make this clearer.
17717 There is also a more substantial working example program supplied with
17719 the libguestfs sources, called libvirt-auth.c.
17720 main ()
17722 {
17723 guestfs_h *g;
17724 char *creds[] = { "authname", "passphrase", NULL };
17725 int r, eh;
17726 g = guestfs_create ();
17728 if (!g) exit (EXIT_FAILURE);
17729 /* Tell libvirt what credentials the program supports. */
17731 r = guestfs_set_libvirt_supported_credentials (g, creds);
17732 if (r == -1)
17733 exit (EXIT_FAILURE);
17734 /* Set up the event handler. */
17736 eh = guestfs_set_event_callback (
17737 g, do_auth,
17738 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
17739 if (eh == -1)
17740 exit (EXIT_FAILURE);
17741 /* An example of a call that may ask for credentials. */
17743 r = guestfs_add_domain (
17744 g, "dom",
17745 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
17746 -1);
17747 if (r == -1)
17748 exit (EXIT_FAILURE);
17749 exit (EXIT_SUCCESS);
17751 }
17752 static void
17754 do_auth (guestfs_h *g,
17755 void *opaque,
17756 uint64_t event,
17757 int event_handle,
17758 int flags,
17759 const char *buf, size_t buf_len,
17760 const uint64_t *array, size_t array_len)
17761 {
17762 char **creds;
17763 size_t i;
17764 char *prompt;
17765 char *reply;
17766 size_t replylen;
17767 int r;
17768 // buf will be the libvirt URI. buf_len may be ignored.
17770 printf ("Authentication required for libvirt conn '%s'\n",
17771 buf);
17772 // Ask libguestfs what credentials libvirt is demanding.
17774 creds = guestfs_get_libvirt_requested_credentials (g);
17775 if (creds == NULL)
17776 exit (EXIT_FAILURE);
17777 // Now ask the user for answers.
17779 for (i = 0; creds[i] != NULL; ++i)
17780 {
17781 if (strcmp (creds[i], "authname") == 0 ||
17782 strcmp (creds[i], "passphrase") == 0)
17783 {
17784 prompt =
17785 guestfs_get_libvirt_requested_credential_prompt (g, i);
17786 if (prompt && strcmp (prompt, "") != 0)
17787 printf ("%s: ", prompt);
17788 free (prompt);
17789 // Some code here to ask for the credential.
17791 // ...
17792 // Put the reply in 'reply', length 'replylen' (bytes).
17793 r = guestfs_set_libvirt_requested_credential (g, i,
17795 reply, replylen);
17796 if (r == -1)
17797 exit (EXIT_FAILURE);
17798 }
17799 free (creds[i]);
17801 }
17802 free (creds);
17804 }
17805
17807 Some operations can be cancelled by the caller while they are in
17808 progress. Currently only operations that involve uploading or
17809 downloading data can be cancelled (technically: operations that have
17810 "FileIn" or "FileOut" parameters in the generator).
17811 To cancel the transfer, call "guestfs_user_cancel". For more
17813 information, read the description of "guestfs_user_cancel".
17814
17816 You can attach named pieces of private data to the libguestfs handle,
17817 fetch them by name, and walk over them, for the lifetime of the handle.
17818 This is called the private data area and is only available from the C
17819 API.
17820 To attach a named piece of data, use the following call:
17822 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
17824 "key" is the name to associate with this data, and "data" is an
17826 arbitrary pointer (which can be "NULL"). Any previous item with the
17827 same key is overwritten.
17828 You can use any "key" string you want, but avoid keys beginning with an
17830 underscore character (libguestfs uses those for its own internal
17831 purposes, such as implementing language bindings). It is recommended
17832 that you prefix the key with some unique string to avoid collisions
17833 with other users.
17834 To retrieve the pointer, use:
17836 void *guestfs_get_private (guestfs_h *g, const char *key);
17838 This function returns "NULL" if either no data is found associated with
17840 "key", or if the user previously set the "key"’s "data" pointer to
17841 "NULL".
17842 Libguestfs does not try to look at or interpret the "data" pointer in
17844 any way. As far as libguestfs is concerned, it need not be a valid
17845 pointer at all. In particular, libguestfs does not try to free the
17846 data when the handle is closed. If the data must be freed, then the
17847 caller must either free it before calling "guestfs_close" or must set
17848 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
17849 To walk over all entries, use these two functions:
17851 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
17853 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
17855 "guestfs_first_private" returns the first key, pointer pair ("first"
17857 does not have any particular meaning -- keys are not returned in any
17858 defined order). A pointer to the key is returned in *key_rtn and the
17859 corresponding data pointer is returned from the function. "NULL" is
17860 returned if there are no keys stored in the handle.
17861 "guestfs_next_private" returns the next key, pointer pair. The return
17863 value of this function is "NULL" if there are no further entries to
17864 return.
17865 Notes about walking over entries:
17867 · You must not call "guestfs_set_private" while walking over the
17869 entries.
17870 · The handle maintains an internal iterator which is reset when you
17872 call "guestfs_first_private". This internal iterator is
17873 invalidated when you call "guestfs_set_private".
17874 · If you have set the data pointer associated with a key to "NULL",
17876 ie:
17877 guestfs_set_private (g, key, NULL);
17879 then that "key" is not returned when walking.
17881 · *key_rtn is only valid until the next call to
17883 "guestfs_first_private", "guestfs_next_private" or
17884 "guestfs_set_private".
17885 The following example code shows how to print all keys and data
17887 pointers that are associated with the handle "g":
17888 const char *key;
17890 void *data = guestfs_first_private (g, &key);
17891 while (data != NULL)
17892 {
17893 printf ("key = %s, data = %p\n", key, data);
17894 data = guestfs_next_private (g, &key);
17895 }
17896 More commonly you are only interested in keys that begin with an
17898 application-specific prefix "foo_". Modify the loop like so:
17899 const char *key;
17901 void *data = guestfs_first_private (g, &key);
17902 while (data != NULL)
17903 {
17904 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
17905 printf ("key = %s, data = %p\n", key, data);
17906 data = guestfs_next_private (g, &key);
17907 }
17908 If you need to modify keys while walking, then you have to jump back to
17910 the beginning of the loop. For example, to delete all keys prefixed
17911 with "foo_":
17912 const char *key;
17914 void *data;
17915 again:
17916 data = guestfs_first_private (g, &key);
17917 while (data != NULL)
17918 {
17919 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
17920 {
17921 guestfs_set_private (g, key, NULL);
17922 /* note that 'key' pointer is now invalid, and so is
17923 the internal iterator */
17924 goto again;
17925 }
17926 data = guestfs_next_private (g, &key);
17927 }
17928 Note that the above loop is guaranteed to terminate because the keys
17930 are being deleted, but other manipulations of keys within the loop
17931 might not terminate unless you also maintain an indication of which
17932 keys have been visited.
17933
17935 The libguestfs C library can be probed using systemtap or DTrace. This
17936 is true of any library, not just libguestfs. However libguestfs also
17937 contains static markers to help in probing internal operations.
17938 You can list all the static markers by doing:
17940 stap -l 'process("/usr/lib*/libguestfs.so.0")
17942 .provider("guestfs").mark("*")'
17943 Note: These static markers are not part of the stable API and may
17945 change in future versions.
17946 SYSTEMTAP SCRIPT EXAMPLE
17948 This script contains examples of displaying both the static markers and
17949 some ordinary C entry points:
17950 global last;
17952 function display_time () {
17954 now = gettimeofday_us ();
17955 delta = 0;
17956 if (last > 0)
17957 delta = now - last;
17958 last = now;
17959 printf ("%d (+%d):", now, delta);
17961 }
17962 probe begin {
17964 last = 0;
17965 printf ("ready\n");
17966 }
17967 /* Display all calls to static markers. */
17969 probe process("/usr/lib*/libguestfs.so.0")
17970 .provider("guestfs").mark("*") ? {
17971 display_time();
17972 printf ("\t%s %s\n", $$name, $$parms);
17973 }
17974 /* Display all calls to guestfs_mkfs* functions. */
17976 probe process("/usr/lib*/libguestfs.so.0")
17977 .function("guestfs_mkfs*") ? {
17978 display_time();
17979 printf ("\t%s %s\n", probefunc(), $$parms);
17980 }
17981 The script above can be saved to test.stap and run using the stap(1)
17983 program. Note that you either have to be root, or you have to add
17984 yourself to several special stap groups. Consult the systemtap
17985 documentation for more information.
17986 # stap /tmp/test.stap
17988 ready
17989 In another terminal, run a guestfish command such as this:
17991 guestfish -N fs
17993 In the first terminal, stap trace output similar to this is shown:
17995 1318248056692655 (+0): launch_start
17997 1318248056692850 (+195): launch_build_appliance_start
17998 1318248056818285 (+125435): launch_build_appliance_end
17999 1318248056838059 (+19774): launch_run_qemu
18000 1318248061071167 (+4233108): launch_end
18001 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
18002
18004 Since April 2010, libguestfs has started to make separate development
18005 and stable releases, along with corresponding branches in our git
18006 repository. These separate releases can be identified by version
18007 number:
18008 even numbers for stable: 1.2.x, 1.4.x, ...
18010 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18011 |
18012 v
18013 1 . 3 . 5
18014 ^ ^
18015 | |
18016 | `-------- sub-version
18017 |
18018 `------ always '1' because we don't change the ABI
18019 Thus "1.3.5" is the 5th update to the development branch "1.3".
18021 As time passes we cherry pick fixes from the development branch and
18023 backport those into the stable branch, the effect being that the stable
18024 branch should get more stable and less buggy over time. So the stable
18025 releases are ideal for people who don't need new features but would
18026 just like the software to work.
18027 Our criteria for backporting changes are:
18029 · Documentation changes which don’t affect any code are backported
18031 unless the documentation refers to a future feature which is not in
18032 stable.
18033 · Bug fixes which are not controversial, fix obvious problems, and
18035 have been well tested are backported.
18036 · Simple rearrangements of code which shouldn't affect how it works
18038 get backported. This is so that the code in the two branches
18039 doesn't get too far out of step, allowing us to backport future
18040 fixes more easily.
18041 · We don’t backport new features, new APIs, new tools etc, except in
18043 one exceptional case: the new feature is required in order to
18044 implement an important bug fix.
18045 A new stable branch starts when we think the new features in
18047 development are substantial and compelling enough over the current
18048 stable branch to warrant it. When that happens we create new stable
18049 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18050 oh release won't necessarily be so stable at this point, but by
18051 backporting fixes from development, that branch will stabilize over
18052 time.
18053
18055 PROTOCOL LIMITS
18056 Internally libguestfs uses a message-based protocol to pass API calls
18057 and their responses to and from a small "appliance" (see
18058 guestfs-internals(1) for plenty more detail about this). The maximum
18059 message size used by the protocol is slightly less than 4 MB. For some
18060 API calls you may need to be aware of this limit. The API calls which
18061 may be affected are individually documented, with a link back to this
18062 section of the documentation.
18063 In libguestfs < 1.19.32, several calls had to encode either their
18065 entire argument list or their entire return value (or sometimes both)
18066 in a single protocol message, and this gave them an arbitrary
18067 limitation on how much data they could handle. For example,
18068 "guestfs_cat" could only download a file if it was less than around 4
18069 MB in size. In later versions of libguestfs, some of these limits have
18070 been removed. The APIs which were previously limited but are now
18071 unlimited (except perhaps by available memory) are listed below. To
18072 find out if a specific API is subject to protocol limits, check for the
18073 warning in the API documentation which links to this section, and
18074 remember to check the version of the documentation that matches the
18075 version of libguestfs you are using.
18076 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18078 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18079 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18080 "guestfs_ls".
18081 See also "UPLOADING" and "DOWNLOADING" for further information about
18083 copying large amounts of data into or out of a filesystem.
18084 MAXIMUM NUMBER OF DISKS
18086 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18087 may be added by calling "guestfs_max_disks". In earlier versions of
18088 libguestfs (ie. where this call is not available) you should assume the
18089 maximum is 25.
18090 The rest of this section covers implementation details, which could
18092 change in future.
18093 When using virtio-scsi disks (the default if available in qemu) the
18095 current limit is 255 disks. When using virtio-blk (the old default)
18096 the limit is around 27 disks, but may vary according to implementation
18097 details and whether the network is enabled.
18098 Virtio-scsi as used by libguestfs is configured to use one target per
18100 disk, and 256 targets are available.
18101 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18103 31 slots, but some of these are used for other purposes.
18104 One virtual disk is used by libguestfs internally.
18106 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18108 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18109 the limit was 25. This has been fixed in more recent versions.
18110 In libguestfs ≥ 1.20 it is possible to hot plug disks. See
18112 "HOTPLUGGING".
18113 MAXIMUM NUMBER OF PARTITIONS PER DISK
18115 Virtio limits the maximum number of partitions per disk to 15.
18116 This is because it reserves 4 bits for the minor device number (thus
18118 /dev/vda, and /dev/vda1 through /dev/vda15).
18119 If you attach a disk with more than 15 partitions, the extra partitions
18121 are ignored by libguestfs.
18122 MAXIMUM SIZE OF A DISK
18124 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18125 We have tested block devices up to 1 exabyte (2**60 or
18127 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18128 host filesystem.
18129 Although libguestfs probably does not impose any limit, the underlying
18131 host storage will. If you store disk images on a host ext4 filesystem,
18132 then the maximum size will be limited by the maximum ext4 file size
18133 (currently 16 TB). If you store disk images as host logical volumes
18134 then you are limited by the maximum size of an LV.
18135 For the hugest disk image files, we recommend using XFS on the host for
18137 storage.
18138 MAXIMUM SIZE OF A PARTITION
18140 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18141 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18142 address a partition located beyond 2 TB on the disk.
18143 It is recommended that you use GPT partitions on disks which are larger
18145 than this size. GPT uses 64 bit sector numbers and so can address
18146 partitions which are theoretically larger than the largest disk we
18147 could support.
18148 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18150 This depends on the filesystem type. libguestfs itself does not impose
18151 any known limit. Consult Wikipedia or the filesystem documentation to
18152 find out what these limits are.
18153 MAXIMUM UPLOAD AND DOWNLOAD
18155 The API functions "guestfs_upload", "guestfs_download",
18156 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18157 uploads and downloads.
18158 INSPECTION LIMITS
18160 The inspection code has several arbitrary limits on things like the
18161 size of Windows Registry hive it will read, and the length of product
18162 name. These are intended to stop a malicious guest from consuming
18163 arbitrary amounts of memory and disk space on the host, and should not
18164 be reached in practice. See the source code for more information.
18165
18167 LIBGUESTFS_APPEND
18168 Pass additional options to the guest kernel.
18169 LIBGUESTFS_ATTACH_METHOD
18171 This is the old way to set "LIBGUESTFS_BACKEND".
18172 LIBGUESTFS_BACKEND
18174 Choose the default way to create the appliance. See
18175 "guestfs_set_backend" and "BACKEND".
18176 LIBGUESTFS_BACKEND_SETTINGS
18178 A colon-separated list of backend-specific settings. See
18179 "BACKEND", "BACKEND SETTINGS".
18180 LIBGUESTFS_CACHEDIR
18182 The location where libguestfs will cache its appliance, when using
18183 a supermin appliance. The appliance is cached and shared between
18184 all handles which have the same effective user ID.
18185 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18187 "TMPDIR" is not set, then /var/tmp is used.
18188 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18190 LIBGUESTFS_DEBUG
18192 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18193 same effect as calling "guestfs_set_verbose (g, 1)".
18194 LIBGUESTFS_HV
18196 Set the default hypervisor (usually qemu) binary that libguestfs
18197 uses. If not set, then the qemu which was found at compile time by
18198 the configure script is used.
18199 See also "QEMU WRAPPERS" above.
18201 LIBGUESTFS_MEMSIZE
18203 Set the memory allocated to the qemu process, in megabytes. For
18204 example:
18205 LIBGUESTFS_MEMSIZE=700
18207 LIBGUESTFS_PATH
18209 Set the path that libguestfs uses to search for a supermin
18210 appliance. See the discussion of paths in section "PATH" above.
18211 LIBGUESTFS_QEMU
18213 This is the old way to set "LIBGUESTFS_HV".
18214 LIBGUESTFS_TMPDIR
18216 The location where libguestfs will store temporary files used by
18217 each handle.
18218 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18220 "TMPDIR" is not set, then /tmp is used.
18221 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18223 LIBGUESTFS_TRACE
18225 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18226 same effect as calling "guestfs_set_trace (g, 1)".
18227 PATH
18229 Libguestfs may run some external programs, and relies on $PATH
18230 being set to a reasonable value. If using the libvirt backend,
18231 libvirt will not work at all unless $PATH contains the path of
18232 qemu/KVM. Note that PHP by default removes $PATH from the
18233 environment which tends to break everything.
18234 SUPERMIN_KERNEL
18236 SUPERMIN_KERNEL_VERSION
18237 SUPERMIN_MODULES
18238 These three environment variables allow the kernel that libguestfs
18239 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18240 set, then the most recent host kernel is chosen. For more
18241 information about kernel selection, see supermin(1).
18242 TMPDIR
18244 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18245 XDG_RUNTIME_DIR
18247 This directory represents a user-specific directory for storing
18248 non-essential runtime files.
18249 If it is set, then is used to store temporary sockets. Otherwise,
18251 /tmp is used.
18252 See also "get-sockdir",
18254 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18255
18257 Examples written in C: guestfs-examples(3).
18258 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18260 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18261 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18262 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18264 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18265 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18266 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18267 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18268 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18269 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18270 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18271 virt-win-reg(1).
18272 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18274 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18275 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18276 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18277 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18279 sd-journal(3).
18280 Website: http://libguestfs.org/
18282 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18284 disktype(1).
18285
18287 Richard W.M. Jones ("rjones at redhat dot com")
18288
18290 Copyright (C) 2009-2018 Red Hat Inc.
18291
18293 This library is free software; you can redistribute it and/or modify it
18294 under the terms of the GNU Lesser General Public License as published
18295 by the Free Software Foundation; either version 2 of the License, or
18296 (at your option) any later version.
18297 This library is distributed in the hope that it will be useful, but
18299 WITHOUT ANY WARRANTY; without even the implied warranty of
18300 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18301 Lesser General Public License for more details.
18302 You should have received a copy of the GNU Lesser General Public
18304 License along with this library; if not, write to the Free Software
18305 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18306 02110-1301 USA
18307
18309 To get a list of bugs against libguestfs, use this link:
18310 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18311 To report a new bug against libguestfs, use this link:
18313 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18314 When reporting a bug, please supply:
18316 · The version of libguestfs.
18318 · Where you got libguestfs (eg. which Linux distro, compiled from
18320 source, etc)
18321 · Describe the bug accurately and give a way to reproduce it.
18323 · Run libguestfs-test-tool(1) and paste the complete, unedited output
18325 into the bug report.
18326libguestfs-1.38.2 2018-05-15 guestfs(3)