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 MOUNTING
175 Before you can read or write files, create directories and so on in a
176 disk image that contains filesystems, you have to mount those
177 filesystems using "guestfs_mount" or "guestfs_mount_ro". If you
178 already know that a disk image contains (for example) one partition
179 with a filesystem on that partition, then you can mount it directly:
180 guestfs_mount (g, "/dev/sda1", "/");
182 where /dev/sda1 means literally the first partition (1) of the first
184 disk image that we added (/dev/sda). If the disk contains Linux LVM2
185 logical volumes you could refer to those instead (eg. /dev/VG/LV).
186 Note that these are libguestfs virtual devices, and are nothing to do
187 with host devices.
188 If you are given a disk image and you don’t know what it contains then
190 you have to find out. Libguestfs can do that too: use
191 "guestfs_list_partitions" and "guestfs_lvs" to list possible partitions
192 and LVs, and either try mounting each to see what is mountable, or else
193 examine them with "guestfs_vfs_type" or "guestfs_file". To list just
194 filesystems, use "guestfs_list_filesystems".
195 Libguestfs also has a set of APIs for inspection of unknown disk images
197 (see "INSPECTION" below). You might also want to look at higher level
198 programs built on top of libguestfs, in particular virt-inspector(1).
199 To mount a filesystem read-only, use "guestfs_mount_ro". There are
201 several other variations of the "guestfs_mount_*" call.
202 FILESYSTEM ACCESS AND MODIFICATION
204 The majority of the libguestfs API consists of fairly low-level calls
205 for accessing and modifying the files, directories, symlinks etc on
206 mounted filesystems. There are over a hundred such calls which you can
207 find listed in detail below in this man page, and we don't even pretend
208 to cover them all in this overview.
209 Specify filenames as full paths, starting with "/" and including the
211 mount point.
212 For example, if you mounted a filesystem at "/" and you want to read
214 the file called "etc/passwd" then you could do:
215 char *data = guestfs_cat (g, "/etc/passwd");
217 This would return "data" as a newly allocated buffer containing the
219 full content of that file (with some conditions: see also "DOWNLOADING"
220 below), or "NULL" if there was an error.
221 As another example, to create a top-level directory on that filesystem
223 called "var" you would do:
224 guestfs_mkdir (g, "/var");
226 To create a symlink you could do:
228 guestfs_ln_s (g, "/etc/init.d/portmap",
230 "/etc/rc3.d/S30portmap");
231 Libguestfs will reject attempts to use relative paths and there is no
233 concept of a current working directory.
234 Libguestfs can return errors in many situations: for example if the
236 filesystem isn't writable, or if a file or directory that you requested
237 doesn't exist. If you are using the C API (documented here) you have
238 to check for those error conditions after each call. (Other language
239 bindings turn these errors into exceptions).
240 File writes are affected by the per-handle umask, set by calling
242 "guestfs_umask" and defaulting to 022. See "UMASK".
243 Since libguestfs 1.18, it is possible to mount the libguestfs
245 filesystem on a local directory, subject to some restrictions. See
246 "MOUNT LOCAL" below.
247 PARTITIONING
249 Libguestfs contains API calls to read, create and modify partition
250 tables on disk images.
251 In the common case where you want to create a single partition covering
253 the whole disk, you should use the "guestfs_part_disk" call:
254 const char *parttype = "mbr";
256 if (disk_is_larger_than_2TB)
257 parttype = "gpt";
258 guestfs_part_disk (g, "/dev/sda", parttype);
259 Obviously this effectively wipes anything that was on that disk image
261 before.
262 LVM2
264 Libguestfs provides access to a large part of the LVM2 API, such as
265 "guestfs_lvcreate" and "guestfs_vgremove". It won't make much sense
266 unless you familiarize yourself with the concepts of physical volumes,
267 volume groups and logical volumes.
268 This author strongly recommends reading the LVM HOWTO, online at
270 http://tldp.org/HOWTO/LVM-HOWTO/.
271 DOWNLOADING
273 Use "guestfs_cat" to download small, text only files. This call cannot
274 handle files containing any ASCII NUL ("\0") characters. However the
275 API is very simple to use.
276 "guestfs_read_file" can be used to read files which contain arbitrary 8
278 bit data, since it returns a (pointer, size) pair.
279 "guestfs_download" can be used to download any file, with no limits on
281 content or size.
282 To download multiple files, see "guestfs_tar_out" and
284 "guestfs_tgz_out".
285 UPLOADING
287 To write a small file with fixed content, use "guestfs_write". To
288 create a file of all zeroes, use "guestfs_truncate_size" (sparse) or
289 "guestfs_fallocate64" (with all disk blocks allocated). There are a
290 variety of other functions for creating test files, for example
291 "guestfs_fill" and "guestfs_fill_pattern".
292 To upload a single file, use "guestfs_upload". This call has no limits
294 on file content or size.
295 To upload multiple files, see "guestfs_tar_in" and "guestfs_tgz_in".
297 However the fastest way to upload large numbers of arbitrary files is
299 to turn them into a squashfs or CD ISO (see mksquashfs(8) and
300 mkisofs(8)), then attach this using "guestfs_add_drive_ro". If you add
301 the drive in a predictable way (eg. adding it last after all other
302 drives) then you can get the device name from "guestfs_list_devices"
303 and mount it directly using "guestfs_mount_ro". Note that squashfs
304 images are sometimes non-portable between kernel versions, and they
305 don't support labels or UUIDs. If you want to pre-build an image or
306 you need to mount it using a label or UUID, use an ISO image instead.
307 COPYING
309 There are various different commands for copying between files and
310 devices and in and out of the guest filesystem. These are summarised
311 in the table below.
312 file to file
314 Use "guestfs_cp" to copy a single file, or "guestfs_cp_a" to copy
315 directories recursively.
316 To copy part of a file (offset and size) use
318 "guestfs_copy_file_to_file".
319 file to device
321 device to file
322 device to device
323 Use "guestfs_copy_file_to_device", "guestfs_copy_device_to_file",
324 or "guestfs_copy_device_to_device".
325 Example: duplicate the contents of an LV:
327 guestfs_copy_device_to_device (g,
329 "/dev/VG/Original", "/dev/VG/Copy",
330 /* -1 marks the end of the list of optional parameters */
331 -1);
332 The destination (/dev/VG/Copy) must be at least as large as the
334 source (/dev/VG/Original). To copy less than the whole source
335 device, use the optional "size" parameter:
336 guestfs_copy_device_to_device (g,
338 "/dev/VG/Original", "/dev/VG/Copy",
339 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
340 -1);
341 file on the host to file or device
343 Use "guestfs_upload". See "UPLOADING" above.
344 file or device to file on the host
346 Use "guestfs_download". See "DOWNLOADING" above.
347 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
349 Calls like "guestfs_upload", "guestfs_download", "guestfs_tar_in",
350 "guestfs_tar_out" etc appear to only take filenames as arguments, so it
351 appears you can only upload and download to files. However many
352 Un*x-like hosts let you use the special device files /dev/stdin,
353 /dev/stdout, /dev/stderr and /dev/fd/N to read and write from stdin,
354 stdout, stderr, and arbitrary file descriptor N.
355 For example, virt-cat(1) writes its output to stdout by doing:
357 guestfs_download (g, filename, "/dev/stdout");
359 and you can write tar output to a file descriptor "fd" by doing:
361 char devfd[64];
363 snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
364 guestfs_tar_out (g, "/", devfd);
365 LISTING FILES
367 "guestfs_ll" is just designed for humans to read (mainly when using the
368 guestfish(1)-equivalent command "ll").
369 "guestfs_ls" is a quick way to get a list of files in a directory from
371 programs, as a flat list of strings.
372 "guestfs_readdir" is a programmatic way to get a list of files in a
374 directory, plus additional information about each one. It is more
375 equivalent to using the readdir(3) call on a local filesystem.
376 "guestfs_find" and "guestfs_find0" can be used to recursively list
378 files.
379 RUNNING COMMANDS
381 Although libguestfs is primarily an API for manipulating files inside
382 guest images, we also provide some limited facilities for running
383 commands inside guests.
384 There are many limitations to this:
386 • The kernel version that the command runs under will be different
388 from what it expects.
389 • If the command needs to communicate with daemons, then most likely
391 they won't be running.
392 • The command will be running in limited memory.
394 • The network may not be available unless you enable it (see
396 "guestfs_set_network").
397 • Only supports Linux guests (not Windows, BSD, etc).
399 • Architecture limitations (eg. won’t work for a PPC guest on an X86
401 host).
402 • For SELinux guests, you may need to relabel the guest after
404 creating new files. See "SELINUX" below.
405 • Security: It is not safe to run commands from untrusted, possibly
407 malicious guests. These commands may attempt to exploit your
408 program by sending unexpected output. They could also try to
409 exploit the Linux kernel or qemu provided by the libguestfs
410 appliance. They could use the network provided by the libguestfs
411 appliance to bypass ordinary network partitions and firewalls.
412 They could use the elevated privileges or different SELinux context
413 of your program to their advantage.
414 A secure alternative is to use libguestfs to install a "firstboot"
416 script (a script which runs when the guest next boots normally),
417 and to have this script run the commands you want in the normal
418 context of the running guest, network security and so on. For
419 information about other security issues, see guestfs-security(1).
420 The two main API calls to run commands are "guestfs_command" and
422 "guestfs_sh" (there are also variations).
423 The difference is that "guestfs_sh" runs commands using the shell, so
425 any shell globs, redirections, etc will work.
426 CONFIGURATION FILES
428 To read and write configuration files in Linux guest filesystems, we
429 strongly recommend using Augeas. For example, Augeas understands how
430 to read and write, say, a Linux shadow password file or X.org
431 configuration file, and so avoids you having to write that code.
432 The main Augeas calls are bound through the "guestfs_aug_*" APIs. We
434 don't document Augeas itself here because there is excellent
435 documentation on the http://augeas.net/ website.
436 If you don’t want to use Augeas (you fool!) then try calling
438 "guestfs_read_lines" to get the file as a list of lines which you can
439 iterate over.
440 SYSTEMD JOURNAL FILES
442 To read the systemd journal from a Linux guest, use the
443 "guestfs_journal_*" APIs starting with "guestfs_journal_open".
444 Consult the journal documentation here: sd-journal(3),
446 sd_journal_open(3).
447 SELINUX
449 We support SELinux guests. However it is not possible to load the
450 SELinux policy of the guest into the appliance kernel. Therefore the
451 strategy for dealing with SELinux guests is to relabel them after
452 making changes.
453 In libguestfs ≥ 1.34 there is a new API, "guestfs_setfiles", which can
455 be used for this. To properly use this API you have to parse the guest
456 SELinux configuration. See the virt-customize(1) module
457 customize/SELinux_relabel.ml for how to do this.
458 A simpler but slower alternative is to touch /.autorelabel in the
460 guest, which means that the guest will relabel itself at next boot.
461 Libguestfs ≤ 1.32 had APIs "guestfs_set_selinux",
463 "guestfs_get_selinux", "guestfs_setcon" and "guestfs_getcon". These
464 did not work properly, are deprecated, and should not be used in new
465 code.
466 UMASK
468 Certain calls are affected by the current file mode creation mask (the
469 "umask"). In particular ones which create files or directories, such
470 as "guestfs_touch", "guestfs_mknod" or "guestfs_mkdir". This affects
471 either the default mode that the file is created with or modifies the
472 mode that you supply.
473 The default umask is 022, so files are created with modes such as 0644
475 and directories with 0755.
476 There are two ways to avoid being affected by umask. Either set umask
478 to 0 (call "guestfs_umask (g, 0)" early after launching). Or call
479 "guestfs_chmod" after creating each file or directory.
480 For more information about umask, see umask(2).
482 LABELS AND UUIDS
484 Many filesystems, devices and logical volumes support either labels
485 (short strings like "BOOT" which might not be unique) and/or UUIDs
486 (globally unique IDs).
487 For filesystems, use "guestfs_vfs_label" or "guestfs_vfs_uuid" to read
489 the label or UUID. Some filesystems let you call "guestfs_set_label"
490 or "guestfs_set_uuid" to change the label or UUID.
491 You can locate a filesystem by its label or UUID using
493 "guestfs_findfs_label" or "guestfs_findfs_uuid".
494 For LVM2 (which supports only UUIDs), there is a rich set of APIs for
496 fetching UUIDs, fetching UUIDs of the contained objects, and changing
497 UUIDs. See: "guestfs_lvuuid", "guestfs_vguuid", "guestfs_pvuuid",
498 "guestfs_vglvuuids", "guestfs_vgpvuuids", "guestfs_vgchange_uuid",
499 "guestfs_vgchange_uuid_all", "guestfs_pvchange_uuid",
500 "guestfs_pvchange_uuid_all".
501 Note when cloning a filesystem, device or whole guest, it is a good
503 idea to set new randomly generated UUIDs on the copy.
504 ENCRYPTED DISKS
506 Libguestfs allows you to access Linux guests which have been encrypted
507 using whole disk encryption that conforms to the Linux Unified Key
508 Setup (LUKS) standard. This includes nearly all whole disk encryption
509 systems used by modern Linux guests. Windows BitLocker is also
510 supported.
511 Use "guestfs_vfs_type" to identify encrypted block devices. For LUKS
513 it returns the string "crypto_LUKS". For Windows BitLocker it returns
514 "BitLocker".
515 Then open these devices by calling "guestfs_cryptsetup_open".
517 Obviously you will require the passphrase!
518 Passphrase-less unlocking is supported for LUKS (not BitLocker) block
520 devices that have been encrypted with network-bound disk encryption
521 (NBDE), using Clevis on the Linux guest side, and Tang on a separate
522 Linux server. Open such devices with "guestfs_clevis_luks_unlock".
523 The appliance will need networking enabled (refer to
524 "guestfs_set_network") and actual connectivity to the Tang servers
525 noted in the "tang" Clevis pins that are bound to the LUKS header.
526 (This includes the ability to resolve the names of the Tang servers.)
527 Opening an encrypted device creates a new device mapper device called
529 /dev/mapper/mapname (where "mapname" is the string you supply to
530 "guestfs_cryptsetup_open" or "guestfs_clevis_luks_unlock"). Reads and
531 writes to this mapper device are decrypted from and encrypted to the
532 underlying block device respectively.
533 LVM volume groups on the device can be made visible by calling
535 "guestfs_vgscan" followed by "guestfs_vg_activate_all". The logical
536 volume(s) can now be mounted in the usual way.
537 Use the reverse process to close an encrypted device. Unmount any
539 logical volumes on it, deactivate the volume groups by calling
540 "guestfs_vg_activate (g, 0, ["/dev/VG"])". Then close the mapper
541 device by calling "guestfs_cryptsetup_close" on the /dev/mapper/mapname
542 device (not the underlying encrypted block device).
543 MOUNT LOCAL
545 In libguestfs ≥ 1.18, it is possible to mount the libguestfs filesystem
546 on a local directory and access it using ordinary POSIX calls and
547 programs.
548 Availability of this is subject to a number of restrictions: it
550 requires FUSE (the Filesystem in USErspace), and libfuse must also have
551 been available when libguestfs was compiled. FUSE may require that a
552 kernel module is loaded, and it may be necessary to add the current
553 user to a special "fuse" group. See the documentation for your
554 distribution and http://fuse.sf.net for further information.
555 The call to mount the libguestfs filesystem on a local directory is
557 "guestfs_mount_local" (q.v.) followed by "guestfs_mount_local_run".
558 The latter does not return until you unmount the filesystem. The
559 reason is that the call enters the FUSE main loop and processes kernel
560 requests, turning them into libguestfs calls. An alternative design
561 would have been to create a background thread to do this, but
562 libguestfs doesn't require pthreads. This way is also more flexible:
563 for example the user can create another thread for
564 "guestfs_mount_local_run".
565 "guestfs_mount_local" needs a certain amount of time to set up the
567 mountpoint. The mountpoint is not ready to use until the call returns.
568 At this point, accesses to the filesystem will block until the main
569 loop is entered (ie. "guestfs_mount_local_run"). So if you need to
570 start another process to access the filesystem, put the fork between
571 "guestfs_mount_local" and "guestfs_mount_local_run".
572 MOUNT LOCAL COMPATIBILITY
574 Since local mounting was only added in libguestfs 1.18, and may not be
576 available even in these builds, you should consider writing code so
577 that it doesn't depend on this feature, and can fall back to using
578 libguestfs file system calls.
579 If libguestfs was compiled without support for "guestfs_mount_local"
581 then calling it will return an error with errno set to "ENOTSUP" (see
582 "guestfs_last_errno").
583 MOUNT LOCAL PERFORMANCE
585 Libguestfs on top of FUSE performs quite poorly. For best performance
587 do not use it. Use ordinary libguestfs filesystem calls, upload,
588 download etc. instead.
589 REMOTE STORAGE
591 CEPH
592 Libguestfs can access Ceph (librbd/RBD) disks.
594 To do this, set the optional "protocol" and "server" parameters of
596 "guestfs_add_drive_opts" like this:
597 char **servers = { "ceph1.example.org:3000", /* ... */, NULL };
599 guestfs_add_drive_opts (g, "pool/image",
600 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
601 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "rbd",
602 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
603 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "rbduser",
604 GUESTFS_ADD_DRIVE_OPTS_SECRET, "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
605 -1);
606 "servers" (the "server" parameter) is a list of one or more Ceph
608 servers. The server string is documented in "guestfs_add_drive_opts".
609 The "username" and "secret" parameters are also optional, and if not
610 given, then no authentication will be used.
611 An encrypted RBD disk -- directly opening which would require the
613 "username" and "secret" parameters -- cannot be accessed if the
614 following conditions all hold:
615 • the backend is libvirt,
617 • the image specified by the "filename" parameter is different from
619 the encrypted RBD disk,
620 • the image specified by the "filename" parameter has qcow2 format,
622 • the encrypted RBD disk is specified as a backing file at some level
624 in the qcow2 backing chain.
625 This limitation is due to libvirt's (justified) separate handling of
627 disks vs. secrets. When the RBD username and secret are provided
628 inside a qcow2 backing file specification, libvirt does not construct
629 an ephemeral secret object from those, for Ceph authentication. Refer
630 to https://bugzilla.redhat.com/2033247.
631 FTP, HTTP AND TFTP
633 Libguestfs can access remote disks over FTP, FTPS, HTTP, HTTPS or TFTP
635 protocols.
636 To do this, set the optional "protocol" and "server" parameters of
638 "guestfs_add_drive_opts" like this:
639 char **servers = { "www.example.org", NULL };
641 guestfs_add_drive_opts (g, "/disk.img",
642 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
643 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "http",
644 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
645 -1);
646 The "protocol" can be one of "ftp", "ftps", "http", "https" or "tftp".
648 "servers" (the "server" parameter) is a list which must have a single
650 element. The single element is a string defining the web, FTP or TFTP
651 server. The format of this string is documented in
652 "guestfs_add_drive_opts".
653 GLUSTER
655 Libguestfs can access Gluster disks.
657 To do this, set the optional "protocol" and "server" parameters of
659 "guestfs_add_drive_opts" like this:
660 char **servers = { "gluster.example.org:24007", NULL };
662 guestfs_add_drive_opts (g, "volname/image",
663 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
664 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "gluster",
665 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
666 -1);
667 "servers" (the "server" parameter) is a list which must have a single
669 element. The single element is a string defining the Gluster server.
670 The format of this string is documented in "guestfs_add_drive_opts".
671 Note that gluster usually requires the client process (ie. libguestfs)
673 to run as root and will give unfathomable errors if it is not (eg. "No
674 data available").
675 ISCSI
677 Libguestfs can access iSCSI disks remotely.
679 To do this, set the optional "protocol" and "server" parameters like
681 this:
682 char **server = { "iscsi.example.org:3000", NULL };
684 guestfs_add_drive_opts (g, "target-iqn-name/lun",
685 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
686 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "iscsi",
687 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
688 -1);
689 The "server" parameter is a list which must have a single element. The
691 single element is a string defining the iSCSI server. The format of
692 this string is documented in "guestfs_add_drive_opts".
693 NETWORK BLOCK DEVICE
695 Libguestfs can access Network Block Device (NBD) disks remotely.
697 To do this, set the optional "protocol" and "server" parameters of
699 "guestfs_add_drive_opts" like this:
700 char **server = { "nbd.example.org:3000", NULL };
702 guestfs_add_drive_opts (g, "" /* export name - see below */,
703 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
704 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
705 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
706 -1);
707 Notes:
709 • "server" is in fact a list of servers. For NBD you must always
711 supply a list with a single element. (Other remote protocols
712 require zero or more than one server, hence the requirement for
713 this parameter to be a list).
714 • The "server" string is documented in "guestfs_add_drive_opts". To
716 connect to a local qemu-nbd instance over a Unix domain socket, use
717 "unix:/path/to/socket".
718 • The "filename" parameter is the NBD export name. Use an empty
720 string to mean the default export. Many NBD servers, including
721 qemu-nbd, do not support export names.
722 • If using qemu-nbd as your server, you should always specify the
724 "-t" option. The reason is that libguestfs may open several
725 connections to the server.
726 • The libvirt backend requires that you set the "format" parameter of
728 "guestfs_add_drive_opts" accurately when you use writable NBD
729 disks.
730 • The libvirt backend has a bug that stops Unix domain socket
732 connections from working:
733 https://bugzilla.redhat.com/show_bug.cgi?id=922888
734 • The direct backend does not support readonly connections because of
736 a bug in qemu: https://bugs.launchpad.net/qemu/+bug/1155677
737 SHEEPDOG
739 Libguestfs can access Sheepdog disks.
741 To do this, set the optional "protocol" and "server" parameters of
743 "guestfs_add_drive_opts" like this:
744 char **servers = { /* optional servers ... */ NULL };
746 guestfs_add_drive_opts (g, "volume",
747 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
748 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "sheepdog",
749 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
750 -1);
751 The optional list of "servers" may be zero or more server addresses
753 ("hostname:port"). The format of the server strings is documented in
754 "guestfs_add_drive_opts".
755 SSH
757 Libguestfs can access disks over a Secure Shell (SSH) connection.
759 To do this, set the "protocol" and "server" and (optionally) "username"
761 parameters of "guestfs_add_drive_opts" like this:
762 char **server = { "remote.example.com", NULL };
764 guestfs_add_drive_opts (g, "/path/to/disk.img",
765 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
766 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "ssh",
767 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
768 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "remoteuser",
769 -1);
770 The format of the server string is documented in
772 "guestfs_add_drive_opts".
773 INSPECTION
775 Libguestfs has APIs for inspecting an unknown disk image to find out if
776 it contains operating systems, an install CD or a live CD.
777 Add all disks belonging to the unknown virtual machine and call
779 "guestfs_launch" in the usual way.
780 Then call "guestfs_inspect_os". This function uses other libguestfs
782 calls and certain heuristics, and returns a list of operating systems
783 that were found. An empty list means none were found. A single
784 element is the root filesystem of the operating system. For dual- or
785 multi-boot guests, multiple roots can be returned, each one
786 corresponding to a separate operating system. (Multi-boot virtual
787 machines are extremely rare in the world of virtualization, but since
788 this scenario can happen, we have built libguestfs to deal with it.)
789 For each root, you can then call various "guestfs_inspect_get_*"
791 functions to get additional details about that operating system. For
792 example, call "guestfs_inspect_get_type" to return the string "windows"
793 or "linux" for Windows and Linux-based operating systems respectively.
794 Un*x-like and Linux-based operating systems usually consist of several
796 filesystems which are mounted at boot time (for example, a separate
797 boot partition mounted on /boot). The inspection rules are able to
798 detect how filesystems correspond to mount points. Call
799 "guestfs_inspect_get_mountpoints" to get this mapping. It might return
800 a hash table like this example:
801 /boot => /dev/sda1
803 / => /dev/vg_guest/lv_root
804 /usr => /dev/vg_guest/lv_usr
805 The caller can then make calls to "guestfs_mount" to mount the
807 filesystems as suggested.
808 Be careful to mount filesystems in the right order (eg. / before /usr).
810 Sorting the keys of the hash by length, shortest first, should work.
811 Inspection currently only works for some common operating systems.
813 Contributors are welcome to send patches for other operating systems
814 that we currently cannot detect.
815 Encrypted disks must be opened before inspection. See "ENCRYPTED
817 DISKS" for more details. The "guestfs_inspect_os" function just
818 ignores any encrypted devices.
819 A note on the implementation: The call "guestfs_inspect_os" performs
821 inspection and caches the results in the guest handle. Subsequent
822 calls to "guestfs_inspect_get_*" return this cached information, but do
823 not re-read the disks. If you change the content of the guest disks,
824 you can redo inspection by calling "guestfs_inspect_os" again.
825 ("guestfs_inspect_list_applications2" works a little differently from
826 the other calls and does read the disks. See documentation for that
827 function for details).
828 INSPECTING INSTALL DISKS
830 Libguestfs (since 1.9.4) can detect some install disks, install CDs,
832 live CDs and more.
833 Further information is available about the operating system that can be
835 installed using the regular inspection APIs like
836 "guestfs_inspect_get_product_name", "guestfs_inspect_get_major_version"
837 etc.
838 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
840 Libguestfs can mount NTFS partitions. It does this using the
841 http://www.ntfs-3g.org/ driver.
842 DRIVE LETTERS AND PATHS
844 DOS and Windows still use drive letters, and the filesystems are always
846 treated as case insensitive by Windows itself, and therefore you might
847 find a Windows configuration file referring to a path like
848 "c:\windows\system32". When the filesystem is mounted in libguestfs,
849 that directory might be referred to as /WINDOWS/System32.
850 Drive letter mappings can be found using inspection (see "INSPECTION"
852 and "guestfs_inspect_get_drive_mappings")
853 Dealing with separator characters (backslash vs forward slash) is
855 outside the scope of libguestfs, but usually a simple character
856 replacement will work.
857 To resolve the case insensitivity of paths, call
859 "guestfs_case_sensitive_path".
860 LONG FILENAMES ON NTFS
862 NTFS supports filenames up to 255 characters long. "Character" means a
864 2 byte UTF-16 codepoint which can encode the most common Unicode
865 codepoints.
866 Most Linux filesystems support filenames up to 255 bytes. This means
868 you may get an error:
869 File name too long
871 when you copy a file from NTFS to a Linux filesystem if the name, when
873 reencoded as UTF-8, would exceed 255 bytes in length.
874 This will most often happen when using non-ASCII names that are longer
876 than ~127 characters (eg. Greek, Cyrillic) or longer than ~85
877 characters (Asian languages).
878 A workaround is not to try to store such long filenames on Linux native
880 filesystems. Since the tar(1) format can store unlimited length
881 filenames, keep the files in a tarball.
882 ACCESSING THE WINDOWS REGISTRY
884 Libguestfs also provides some help for decoding Windows Registry "hive"
886 files, through a separate C library called hivex(3).
887 Before libguestfs 1.19.35 you had to download the hive file, operate on
889 it locally using hivex, and upload it again. Since this version, we
890 have included the major hivex APIs directly in the libguestfs API (see
891 "guestfs_hivex_open"). This means that if you have opened a Windows
892 guest, you can read and write the registry directly.
893 See also virt-win-reg(1).
895 SYMLINKS ON NTFS-3G FILESYSTEMS
897 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
899 provide something which looks like a Linux symlink. The way it tries
900 to do the rewriting is described here:
901 http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
903 The essential problem is that ntfs-3g simply does not have enough
905 information to do a correct job. NTFS links can contain drive letters
906 and references to external device GUIDs that ntfs-3g has no way of
907 resolving. It is almost certainly the case that libguestfs callers
908 should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
909 NTFS volumes).
910 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
912 "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
913 attribute, and read the raw reparse data from that (you can find the
914 format documented in various places around the web).
915 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
917 There are other useful extended attributes that can be read from
919 ntfs-3g filesystems (using "guestfs_getxattr"). See:
920 http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
922 WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP
924 Windows guests which have been hibernated (instead of fully shut down)
926 cannot be mounted. This is a limitation of ntfs-3g. You will see an
927 error like this:
928 The disk contains an unclean file system (0, 0).
930 Metadata kept in Windows cache, refused to mount.
931 Failed to mount '/dev/sda2': Operation not permitted
932 The NTFS partition is in an unsafe state. Please resume
933 and shutdown Windows fully (no hibernation or fast
934 restarting), or mount the volume read-only with the
935 'ro' mount option.
936 In Windows 8, the shutdown button does not shut down the guest at all.
938 Instead it usually hibernates the guest. This is known as "fast
939 startup".
940 Some suggested workarounds are:
942 • Mount read-only (eg. "guestfs_mount_ro").
944 • On Windows 8, turn off fast startup. It is in the Control Panel →
946 Power Options → Choose what the power buttons do → Change settings
947 that are currently unavailable → Turn on fast startup.
948 • On Windows 7 and earlier, shut the guest off properly instead of
950 hibernating it.
951 RESIZE2FS ERRORS
953 The "guestfs_resize2fs", "guestfs_resize2fs_size" and
954 "guestfs_resize2fs_M" calls are used to resize ext2/3/4 filesystems.
955 The underlying program (resize2fs(8)) requires that the filesystem is
957 clean and recently fsck'd before you can resize it. Also, if the
958 resize operation fails for some reason, then you had to call fsck the
959 filesystem again to fix it.
960 In libguestfs "lt" 1.17.14, you usually had to call "guestfs_e2fsck_f"
962 before the resize. However, in "ge" 1.17.14, e2fsck(8) is called
963 automatically before the resize, so you no longer need to do this.
964 The resize2fs(8) program can still fail, in which case it prints an
966 error message similar to:
967 Please run 'e2fsck -fy <device>' to fix the filesystem
969 after the aborted resize operation.
970 You can do this by calling "guestfs_e2fsck" with the "forceall" option.
972 However in the context of disk images, it is usually better to avoid
973 this situation, eg. by rolling back to an earlier snapshot, or by
974 copying and resizing and on failure going back to the original.
975 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
977 Although we don’t want to discourage you from using the C API, we will
978 mention here that the same API is also available in other languages.
979 The API is broadly identical in all supported languages. This means
981 that the C call "guestfs_add_drive_ro(g,file)" is
982 "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
983 and "g#add_drive_ro file" in OCaml. In other words, a straightforward,
984 predictable isomorphism between each language.
985 Error messages are automatically transformed into exceptions if the
987 language supports it.
988 We don’t try to "object orientify" parts of the API in OO languages,
990 although contributors are welcome to write higher level APIs above what
991 we provide in their favourite languages if they wish.
992 C++ You can use the guestfs.h header file from C++ programs. The C++
994 API is identical to the C API. C++ classes and exceptions are not
995 used.
996 C# The C# bindings are highly experimental. Please read the warnings
998 at the top of csharp/Libguestfs.cs.
999 Erlang
1001 See guestfs-erlang(3).
1002 GObject
1004 Experimental GObject bindings (with GObject Introspection support)
1005 are available.
1006 See guestfs-gobject(3).
1008 Go See guestfs-golang(3).
1010 Haskell
1012 This language binding is working but incomplete:
1013 • Functions with optional arguments are not bound. Implementing
1015 optional arguments in Haskell seems to be very complex.
1016 • Events are not bound.
1018 • Functions with the following return types are not bound:
1020 • Any function returning a struct.
1022 • Any function returning a list of structs.
1024 • A few functions that return fixed length buffers
1026 (specifically ones declared "RBufferOut" in the generator).
1027 • A tiny number of obscure functions that return constant
1029 strings (specifically ones declared "RConstOptString" in
1030 the generator).
1031 Java
1033 Full documentation is contained in the Javadoc which is distributed
1034 with libguestfs. For examples, see guestfs-java(3).
1035 Lua See guestfs-lua(3).
1037 OCaml
1039 See guestfs-ocaml(3).
1040 Perl
1042 See guestfs-perl(3) and Sys::Guestfs(3).
1043 PHP For documentation see "README-PHP" supplied with libguestfs sources
1045 or in the php-libguestfs package for your distribution.
1046 The PHP binding only works correctly on 64 bit machines.
1048 Python
1050 See guestfs-python(3).
1051 Ruby
1053 See guestfs-ruby(3).
1054 For JRuby, use the Java bindings.
1056 shell scripts
1058 See guestfish(1).
1059 LIBGUESTFS GOTCHAS
1061 http://en.wikipedia.org/wiki/Gotcha_(programming): "A feature of a
1062 system [...] that works in the way it is documented but is
1063 counterintuitive and almost invites mistakes."
1064 Since we developed libguestfs and the associated tools, there are
1066 several things we would have designed differently, but are now stuck
1067 with for backwards compatibility or other reasons. If there is ever a
1068 libguestfs 2.0 release, you can expect these to change. Beware of
1069 them.
1070 Read-only should be the default.
1072 In guestfish(3), --ro should be the default, and you should have to
1073 specify --rw if you want to make changes to the image.
1074 This would reduce the potential to corrupt live VM images.
1076 Note that many filesystems change the disk when you just mount and
1078 unmount, even if you didn't perform any writes. You need to use
1079 "guestfs_add_drive_ro" to guarantee that the disk is not changed.
1080 guestfish command line is hard to use.
1082 guestfish disk.img doesn't do what people expect (open disk.img for
1083 examination). It tries to run a guestfish command disk.img which
1084 doesn't exist, so it fails. In earlier versions of guestfish the
1085 error message was also unintuitive, but we have corrected this
1086 since. Like the Bourne shell, we should have used "guestfish -c
1087 command" to run commands.
1088 guestfish megabyte modifiers don’t work right on all commands
1090 In recent guestfish you can use "1M" to mean 1 megabyte (and
1091 similarly for other modifiers). What guestfish actually does is to
1092 multiply the number part by the modifier part and pass the result
1093 to the C API. However this doesn't work for a few APIs which
1094 aren't expecting bytes, but are already expecting some other unit
1095 (eg. megabytes).
1096 The most common is "guestfs_lvcreate". The guestfish command:
1098 lvcreate LV VG 100M
1100 does not do what you might expect. Instead because
1102 "guestfs_lvcreate" is already expecting megabytes, this tries to
1103 create a 100 terabyte (100 megabytes * megabytes) logical volume.
1104 The error message you get from this is also a little obscure.
1105 This could be fixed in the generator by specially marking
1107 parameters and return values which take bytes or other units.
1108 Ambiguity between devices and paths
1110 There is a subtle ambiguity in the API between a device name (eg.
1111 /dev/sdb2) and a similar pathname. A file might just happen to be
1112 called "sdb2" in the directory /dev (consider some non-Unix VM
1113 image).
1114 In the current API we usually resolve this ambiguity by having two
1116 separate calls, for example "guestfs_checksum" and
1117 "guestfs_checksum_device". Some API calls are ambiguous and
1118 (incorrectly) resolve the problem by detecting if the path supplied
1119 begins with /dev/.
1120 To avoid both the ambiguity and the need to duplicate some calls,
1122 we could make paths/devices into structured names. One way to do
1123 this would be to use a notation like grub ("hd(0,0)"), although
1124 nobody really likes this aspect of grub. Another way would be to
1125 use a structured type, equivalent to this OCaml type:
1126 type path = Path of string | Device of int | Partition of int * int
1128 which would allow you to pass arguments like:
1130 Path "/foo/bar"
1132 Device 1 (* /dev/sdb, or perhaps /dev/sda *)
1133 Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
1134 Path "/dev/sdb2" (* not a device *)
1135 As you can see there are still problems to resolve even with this
1137 representation. Also consider how it might work in guestfish.
1138 KEYS AND PASSPHRASES
1140 Certain libguestfs calls take a parameter that contains sensitive key
1141 material, passed in as a C string.
1142 In the future we would hope to change the libguestfs implementation so
1144 that keys are mlock(2)-ed into physical RAM, and thus can never end up
1145 in swap. However this is not done at the moment, because of the
1146 complexity of such an implementation.
1147 Therefore you should be aware that any key parameter you pass to
1149 libguestfs might end up being written out to the swap partition. If
1150 this is a concern, scrub the swap partition or don't use libguestfs on
1151 encrypted devices.
1152 MULTIPLE HANDLES AND MULTIPLE THREADS
1154 All high-level libguestfs actions are synchronous. If you want to use
1155 libguestfs asynchronously then you must create a thread.
1156 Threads in libguestfs ≥ 1.38
1158 In libguestfs ≥ 1.38, each handle ("guestfs_h") contains a lock which
1160 is acquired automatically when you call a libguestfs function. The
1161 practical effect of this is you can call libguestfs functions with the
1162 same handle from multiple threads without needing to do any locking.
1163 Also in libguestfs ≥ 1.38, the last error on the handle
1165 ("guestfs_last_error", "guestfs_last_errno") is stored in thread-local
1166 storage, so it is safe to write code like:
1167 if (guestfs_add_drive_ro (g, drive) == -1)
1169 fprintf (stderr, "error was: %s\n", guestfs_last_error (g));
1170 even when other threads may be concurrently using the same handle "g".
1172 Threads in libguestfs < 1.38
1174 In libguestfs < 1.38, you must use the handle only from a single
1176 thread. Either use the handle exclusively from one thread, or provide
1177 your own mutex so that two threads cannot issue calls on the same
1178 handle at the same time. Even apparently innocent functions like
1179 "guestfs_get_trace" are not safe to be called from multiple threads
1180 without a mutex in libguestfs < 1.38.
1181 Use "guestfs_set_identifier" to make it simpler to identify threads in
1183 trace output.
1184 PATH
1186 Libguestfs needs a supermin appliance, which it finds by looking along
1187 an internal path.
1188 By default it looks for these in the directory "$libdir/guestfs" (eg.
1190 /usr/local/lib/guestfs or /usr/lib64/guestfs).
1191 Use "guestfs_set_path" or set the environment variable
1193 "LIBGUESTFS_PATH" to change the directories that libguestfs will search
1194 in. The value is a colon-separated list of paths. The current
1195 directory is not searched unless the path contains an empty element or
1196 ".". For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
1197 current directory and then /usr/lib/guestfs.
1198 QEMU WRAPPERS
1200 If you want to compile your own qemu, run qemu from a non-standard
1201 location, or pass extra arguments to qemu, then you can write a shell-
1202 script wrapper around qemu.
1203 There is one important rule to remember: you must "exec qemu" as the
1205 last command in the shell script (so that qemu replaces the shell and
1206 becomes the direct child of the libguestfs-using program). If you
1207 don't do this, then the qemu process won't be cleaned up correctly.
1208 Here is an example of a wrapper, where I have built my own copy of qemu
1210 from source:
1211 #!/bin/sh -
1213 qemudir=/home/rjones/d/qemu
1214 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1215 Save this script as /tmp/qemu.wrapper (or wherever), "chmod +x", and
1217 then use it by setting the LIBGUESTFS_HV environment variable. For
1218 example:
1219 LIBGUESTFS_HV=/tmp/qemu.wrapper guestfish
1221 Note that libguestfs also calls qemu with the -help and -version
1223 options in order to determine features.
1224 Wrappers can also be used to edit the options passed to qemu. In the
1226 following example, the "-machine ..." option ("-machine" and the
1227 following argument) are removed from the command line and replaced with
1228 "-machine pc,accel=tcg". The while loop iterates over the options
1229 until it finds the right one to remove, putting the remaining options
1230 into the "args" array.
1231 #!/bin/bash -
1233 i=0
1235 while [ $# -gt 0 ]; do
1236 case "$1" in
1237 -machine)
1238 shift 2;;
1239 *)
1240 args[i]="$1"
1241 (( i++ ))
1242 shift ;;
1243 esac
1244 done
1245 exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
1247 BACKEND
1249 The backend (previously known as the "attach method") controls how
1250 libguestfs creates and/or connects to the backend daemon, eg. by
1251 starting qemu directly, or using libvirt to manage an appliance,
1252 running User-Mode Linux, or connecting to an already running daemon.
1253 You can set the backend by calling "guestfs_set_backend", or by setting
1255 the environment variable "LIBGUESTFS_BACKEND".
1256 Possible backends are described below:
1258 "direct"
1260 "appliance"
1261 Run qemu directly to launch an appliance.
1262 "direct" and "appliance" are synonyms.
1264 This is the ordinary method and normally the default, but see the
1266 note below.
1267 "libvirt"
1269 "libvirt:null"
1270 "libvirt:URI"
1271 Use libvirt to launch and manage the appliance.
1272 "libvirt" causes libguestfs to choose a suitable URI for creating
1274 session guests. If using the libvirt backend, you almost always
1275 should use this.
1276 "libvirt:null" causes libguestfs to use the "NULL" connection URI,
1278 which causes libvirt to try to guess what the user meant. You
1279 probably don't want to use this.
1280 "libvirt:URI" uses URI as the libvirt connection URI (see
1282 http://libvirt.org/uri.html). The typical libvirt backend with a
1283 URI would be "libvirt:qemu:///session"
1284 The libvirt backend supports more features, including sVirt.
1286 "direct" is usually the default backend. However since libguestfs ≥
1288 1.19.24, libguestfs can be built with a different default by doing:
1289 ./configure --with-default-backend=...
1291 To find out if libguestfs was compiled with a different default
1293 backend, do:
1294 unset LIBGUESTFS_BACKEND
1296 guestfish get-backend
1297 BACKEND SETTINGS
1299 Each backend can be configured by passing a list of strings. You can
1300 either call "guestfs_set_backend_settings" with a list of strings, or
1301 set the "LIBGUESTFS_BACKEND_SETTINGS" environment variable to a colon-
1302 separated list of strings (before creating the handle).
1303 force_tcg
1305 Using:
1307 export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
1309 will force the direct and libvirt backends to use TCG (software
1311 emulation) instead of KVM (hardware accelerated virtualization).
1312 force_kvm
1314 Using:
1316 export LIBGUESTFS_BACKEND_SETTINGS=force_kvm
1318 will force the direct and libvirt backends to use KVM (hardware
1320 accelerated virtualization) instead of TCG (software emulation).
1321 gdb
1323 The direct backend supports:
1325 export LIBGUESTFS_BACKEND_SETTINGS=gdb
1327 When this is set, qemu will not start running the appliance
1329 immediately. It will wait for you to connect to it using gdb:
1330 $ gdb
1332 (gdb) symbol-file /path/to/vmlinux
1333 (gdb) target remote tcp::1234
1334 (gdb) cont
1335 You can then debug the appliance kernel, which is useful to debug boot
1337 failures (especially ones where there are no debug messages printed -
1338 tip: look in the kernel "log_buf").
1339 On Fedora, install "kernel-debuginfo" for the "vmlinux" file
1341 (containing symbols). Make sure the symbols precisely match the kernel
1342 being used.
1343 ABI GUARANTEE
1345 We guarantee the libguestfs ABI (binary interface), for public, high-
1346 level actions as outlined in this section. Although we will deprecate
1347 some actions, for example if they get replaced by newer calls, we will
1348 keep the old actions forever. This allows you the developer to program
1349 in confidence against the libguestfs API.
1350 BLOCK DEVICE NAMING
1352 Libguestfs defines /dev/sd* as the standard naming scheme for devices
1353 passed to API calls. So /dev/sda means "the first device added by
1354 "guestfs_add_drive_opts"", and /dev/sdb3 means "the third partition on
1355 the second device".
1356 Internally device names are sometimes translated, but this should not
1358 be visible at the API level.
1359 DISK LABELS
1361 In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1363 using the optional "label" parameter to "guestfs_add_drive_opts".
1364 (Note that disk labels are different from and not related to filesystem
1365 labels).
1366 Not all versions of libguestfs support setting a disk label, and when
1368 it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1369 When you add a disk with a label, it can either be addressed using
1371 /dev/sd*, or using /dev/disk/guestfs/label. Partitions on the disk can
1372 be addressed using /dev/disk/guestfs/labelpartnum.
1373 Listing devices ("guestfs_list_devices") and partitions
1375 ("guestfs_list_partitions") returns the block device names. However
1376 you can use "guestfs_list_disk_labels" to map disk labels to block
1377 device and partition names.
1378 NULL DISKS
1380 When adding a disk using, eg., "guestfs_add_drive", you can set the
1381 filename to "/dev/null". This string is treated specially by
1382 libguestfs, causing it to add a "null disk".
1383 A null disk has the following properties:
1385 • A null disk will appear as a normal device, eg. in calls to
1387 "guestfs_list_devices".
1388 • You may add "/dev/null" multiple times.
1390 • You should not try to access a null disk in any way. For example,
1392 you shouldn't try to read it or mount it.
1393 Null disks are used for three main purposes:
1395 1. Performance testing of libguestfs (see guestfs-performance(1)).
1397 2. The internal test suite.
1399 3. If you want to use libguestfs APIs that don’t refer to disks, since
1401 libguestfs requires that at least one disk is added, you should add
1402 a null disk.
1403 For example, to test if a feature is available, use code like this:
1405 guestfs_h *g;
1407 char **groups = [ "btrfs", NULL ];
1408 g = guestfs_create ();
1410 guestfs_add_drive (g, "/dev/null");
1411 guestfs_launch (g);
1412 if (guestfs_available (g, groups) == 0) {
1413 // group(s) are available
1414 } else {
1415 // group(s) are not available
1416 }
1417 guestfs_close (g);
1418 DISK IMAGE FORMATS
1420 Virtual disks come in a variety of formats. Some common formats are
1421 listed below.
1422 Note that libguestfs itself is not responsible for handling the disk
1424 format: this is done using qemu(1). If support for a particular format
1425 is missing or broken, this has to be fixed in qemu.
1426 COMMON VIRTUAL DISK IMAGE FORMATS
1428 raw Raw format is simply a dump of the sequential bytes of the virtual
1430 hard disk. There is no header, container, compression or
1431 processing of any sort.
1432 Since raw format requires no translation to read or write, it is
1434 both fast and very well supported by qemu and all other
1435 hypervisors. You can consider it to be a universal format that any
1436 hypervisor can access.
1437 Raw format files are not compressed and so take up the full space
1439 of the original disk image even when they are empty. A variation
1440 (on Linux/Unix at least) is to not store ranges of all-zero bytes
1441 by storing the file as a sparse file. This "variant format" is
1442 sometimes called raw sparse. Many utilities, including
1443 virt-sparsify(1), can make raw disk images sparse.
1444 qcow2
1446 Qcow2 is the native disk image format used by qemu. Internally it
1447 uses a two-level directory structure so that only blocks containing
1448 data are stored in the file. It also has many other features such
1449 as compression, snapshots and backing files.
1450 There are at least two distinct variants of this format, although
1452 qemu (and hence libguestfs) handles both transparently to the user.
1453 vmdk
1455 VMDK is VMware’s native disk image format. There are many
1456 variations. Modern qemu (hence libguestfs) supports most
1457 variations, but you should be aware that older versions of qemu had
1458 some very bad data-corrupting bugs in this area.
1459 Note that VMware ESX exposes files with the name guest-flat.vmdk.
1461 These are not VMDK. They are raw format files which happen to have
1462 a ".vmdk" extension.
1463 vdi VDI is VirtualBox’s native disk image format. Qemu (hence
1465 libguestfs) has generally good support for this.
1466 vpc
1468 vhd VPC (old) and VHD (modern) are the native disk image format of
1469 Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1470 Obsolete formats
1472 The following formats are obsolete and should not be used: qcow
1473 (aka qcow1), cow, bochs.
1474 DETECTING THE FORMAT OF A DISK IMAGE
1476 Firstly note there is a security issue with auto-detecting the format
1478 of a disk image. It may or may not apply in your use case. Read
1479 "CVE-2010-3851" below.
1480 Libguestfs offers an API to get the format of a disk image
1482 ("guestfs_disk_format"), and it is safest to use this.
1483 Don’t be tempted to try parsing the text / human-readable output of
1485 "qemu-img" since it cannot be parsed reliably and securely. Also do
1486 not use the "file" command since the output of that changes over time.
1487
1489 guestfs_h *
1490 "guestfs_h" is the opaque type representing a connection handle.
1491 Create a handle by calling "guestfs_create" or "guestfs_create_flags".
1492 Call "guestfs_close" to free the handle and release all resources used.
1493 For information on using multiple handles and threads, see the section
1495 "MULTIPLE HANDLES AND MULTIPLE THREADS" above.
1496 guestfs_create
1498 guestfs_h *guestfs_create (void);
1499 Create a connection handle.
1501 On success this returns a non-NULL pointer to a handle. On error it
1503 returns NULL.
1504 You have to "configure" the handle after creating it. This includes
1506 calling "guestfs_add_drive_opts" (or one of the equivalent calls) on
1507 the handle at least once.
1508 After configuring the handle, you have to call "guestfs_launch".
1510 You may also want to configure error handling for the handle. See the
1512 "ERROR HANDLING" section below.
1513 guestfs_create_flags
1515 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
1516 Create a connection handle, supplying extra flags and extra arguments
1518 to control how the handle is created.
1519 On success this returns a non-NULL pointer to a handle. On error it
1521 returns NULL.
1522 "guestfs_create" is equivalent to calling guestfs_create_flags(0).
1524 The following flags may be logically ORed together. (Currently no
1526 extra arguments are used).
1527 "GUESTFS_CREATE_NO_ENVIRONMENT"
1529 Don’t parse any environment variables (such as "LIBGUESTFS_DEBUG"
1530 etc).
1531 You can call "guestfs_parse_environment" or
1533 "guestfs_parse_environment_list" afterwards to parse environment
1534 variables. Alternately, don't call these functions if you want the
1535 handle to be unaffected by environment variables. See the example
1536 below.
1537 The default (if this flag is not given) is to implicitly call
1539 "guestfs_parse_environment".
1540 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT"
1542 Don’t try to close the handle in an atexit(3) handler if the
1543 program exits without explicitly closing the handle.
1544 The default (if this flag is not given) is to install such an
1546 atexit handler.
1547 USING "GUESTFS_CREATE_NO_ENVIRONMENT"
1549 You might use "GUESTFS_CREATE_NO_ENVIRONMENT" and an explicit call to
1551 "guestfs_parse_environment" like this:
1552 guestfs_h *g;
1554 int r;
1555 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
1557 if (!g) {
1558 perror ("guestfs_create_flags");
1559 exit (EXIT_FAILURE);
1560 }
1561 r = guestfs_parse_environment (g);
1562 if (r == -1)
1563 exit (EXIT_FAILURE);
1564 Or to create a handle which is unaffected by environment variables,
1566 omit the call to "guestfs_parse_environment" from the above code.
1567 The above code has another advantage which is that any errors from
1569 parsing the environment are passed through the error handler, whereas
1570 "guestfs_create" prints errors on stderr and ignores them.
1571 guestfs_close
1573 void guestfs_close (guestfs_h *g);
1574 This closes the connection handle and frees up all resources used. If
1576 a close callback was set on the handle, then it is called.
1577 The correct way to close the handle is:
1579 if (guestfs_shutdown (g) == -1) {
1581 /* handle write errors here */
1582 }
1583 guestfs_close (g);
1584 "guestfs_shutdown" is only needed if all of the following are true:
1586 1. one or more disks were added in read-write mode, and
1588 2. guestfs_launch was called, and
1590 3. you made some changes, and
1592 4. you have a way to handle write errors (eg. by exiting with an error
1594 code or reporting something to the user).
1595
1597 API functions can return errors. For example, almost all functions
1598 that return "int" will return -1 to indicate an error.
1599 Additional information is available for errors: an error message string
1601 and optionally an error number (errno) if the thing that failed was a
1602 system call.
1603 You can get at the additional information about the last error on the
1605 handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1606 setting up an error handler with "guestfs_set_error_handler".
1607 When the handle is created, a default error handler is installed which
1609 prints the error message string to "stderr". For small short-running
1610 command line programs it is sufficient to do:
1611 if (guestfs_launch (g) == -1)
1613 exit (EXIT_FAILURE);
1614 since the default error handler will ensure that an error message has
1616 been printed to "stderr" before the program exits.
1617 For other programs the caller will almost certainly want to install an
1619 alternate error handler or do error handling in-line as in the example
1620 below. The non-C language bindings all install NULL error handlers and
1621 turn errors into exceptions using code similar to this:
1622 const char *msg;
1624 int errnum;
1625 /* This disables the default behaviour of printing errors
1627 on stderr. */
1628 guestfs_set_error_handler (g, NULL, NULL);
1629 if (guestfs_launch (g) == -1) {
1631 /* Examine the error message and print it, throw it,
1632 etc. */
1633 msg = guestfs_last_error (g);
1634 errnum = guestfs_last_errno (g);
1635 fprintf (stderr, "%s", msg);
1637 if (errnum != 0)
1638 fprintf (stderr, ": %s", strerror (errnum));
1639 fprintf (stderr, "\n");
1640 /* ... */
1642 }
1643 "guestfs_create" returns "NULL" if the handle cannot be created, and
1645 because there is no handle if this happens there is no way to get
1646 additional error information. Since libguestfs ≥ 1.20, you can use
1647 "guestfs_create_flags" to properly deal with errors during handle
1648 creation, although the vast majority of programs can continue to use
1649 "guestfs_create" and not worry about this situation.
1650 Out of memory errors are handled differently. The default action is to
1652 call abort(3). If this is undesirable, then you can set a handler
1653 using "guestfs_set_out_of_memory_handler".
1654 guestfs_last_error
1656 const char *guestfs_last_error (guestfs_h *g);
1657 This returns the last error message that happened on "g". If there has
1659 not been an error since the handle was created, then this returns
1660 "NULL".
1661 Note the returned string does not have a newline character at the end.
1663 Most error messages are single lines. Some are split over multiple
1664 lines and contain "\n" characters within the string but not at the end.
1665 The lifetime of the returned string is until the next error occurs on
1667 the same handle, or "guestfs_close" is called. If you need to keep it
1668 longer, copy it.
1669 guestfs_last_errno
1671 int guestfs_last_errno (guestfs_h *g);
1672 This returns the last error number (errno) that happened on "g".
1674 If successful, an errno integer not equal to zero is returned.
1676 In many cases the special errno "ENOTSUP" is returned if you tried to
1678 call a function or use a feature which is not supported.
1679 If no error number is available, this returns 0. This call can return
1681 0 in three situations:
1682 1. There has not been any error on the handle.
1684 2. There has been an error but the errno was meaningless. This
1686 corresponds to the case where the error did not come from a failed
1687 system call, but for some other reason.
1688 3. There was an error from a failed system call, but for some reason
1690 the errno was not captured and returned. This usually indicates a
1691 bug in libguestfs.
1692 Libguestfs tries to convert the errno from inside the appliance into a
1694 corresponding errno for the caller (not entirely trivial: the appliance
1695 might be running a completely different operating system from the
1696 library and error numbers are not standardized across Un*xen). If this
1697 could not be done, then the error is translated to "EINVAL". In
1698 practice this should only happen in very rare circumstances.
1699 guestfs_set_error_handler
1701 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1702 void *opaque,
1703 const char *msg);
1704 void guestfs_set_error_handler (guestfs_h *g,
1705 guestfs_error_handler_cb cb,
1706 void *opaque);
1707 The callback "cb" will be called if there is an error. The parameters
1709 passed to the callback are an opaque data pointer and the error message
1710 string.
1711 "errno" is not passed to the callback. To get that the callback must
1713 call "guestfs_last_errno".
1714 Note that the message string "msg" is freed as soon as the callback
1716 function returns, so if you want to stash it somewhere you must make
1717 your own copy.
1718 The default handler prints messages on "stderr".
1720 If you set "cb" to "NULL" then no handler is called.
1722 guestfs_get_error_handler
1724 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1725 void **opaque_rtn);
1726 Returns the current error handler callback.
1728 guestfs_push_error_handler
1730 void guestfs_push_error_handler (guestfs_h *g,
1731 guestfs_error_handler_cb cb,
1732 void *opaque);
1733 This is the same as "guestfs_set_error_handler", except that the old
1735 error handler is stashed away in a stack inside the handle. You can
1736 restore the previous error handler by calling
1737 "guestfs_pop_error_handler".
1738 Use the following code to temporarily disable errors around a function:
1740 guestfs_push_error_handler (g, NULL, NULL);
1742 guestfs_mkdir (g, "/foo"); /* We don't care if this fails. */
1743 guestfs_pop_error_handler (g);
1744 guestfs_pop_error_handler
1746 void guestfs_pop_error_handler (guestfs_h *g);
1747 Restore the previous error handler (see "guestfs_push_error_handler").
1749 If you pop the stack too many times, then the default error handler is
1751 restored.
1752 guestfs_set_out_of_memory_handler
1754 typedef void (*guestfs_abort_cb) (void);
1755 void guestfs_set_out_of_memory_handler (guestfs_h *g,
1756 guestfs_abort_cb);
1757 The callback "cb" will be called if there is an out of memory
1759 situation. Note this callback must not return.
1760 The default is to call abort(3).
1762 You cannot set "cb" to "NULL". You can’t ignore out of memory
1764 situations.
1765 guestfs_get_out_of_memory_handler
1767 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1768 This returns the current out of memory handler.
1770
1772 guestfs_acl_delete_def_file
1773 int
1774 guestfs_acl_delete_def_file (guestfs_h *g,
1775 const char *dir);
1776 This function deletes the default POSIX Access Control List (ACL)
1778 attached to directory "dir".
1779 This function returns 0 on success or -1 on error.
1781 This function depends on the feature "acl". See also
1783 "guestfs_feature_available".
1784 (Added in 1.19.63)
1786 guestfs_acl_get_file
1788 char *
1789 guestfs_acl_get_file (guestfs_h *g,
1790 const char *path,
1791 const char *acltype);
1792 This function returns the POSIX Access Control List (ACL) attached to
1794 "path". The ACL is returned in "long text form" (see acl(5)).
1795 The "acltype" parameter may be:
1797 "access"
1799 Return the ordinary (access) ACL for any file, directory or other
1800 filesystem object.
1801 "default"
1803 Return the default ACL. Normally this only makes sense if "path"
1804 is a directory.
1805 This function returns a string, or NULL on error. The caller must free
1807 the returned string after use.
1808 This function depends on the feature "acl". See also
1810 "guestfs_feature_available".
1811 (Added in 1.19.63)
1813 guestfs_acl_set_file
1815 int
1816 guestfs_acl_set_file (guestfs_h *g,
1817 const char *path,
1818 const char *acltype,
1819 const char *acl);
1820 This function sets the POSIX Access Control List (ACL) attached to
1822 "path".
1823 The "acltype" parameter may be:
1825 "access"
1827 Set the ordinary (access) ACL for any file, directory or other
1828 filesystem object.
1829 "default"
1831 Set the default ACL. Normally this only makes sense if "path" is a
1832 directory.
1833 The "acl" parameter is the new ACL in either "long text form" or "short
1835 text form" (see acl(5)). The new ACL completely replaces any previous
1836 ACL on the file. The ACL must contain the full Unix permissions (eg.
1837 "u::rwx,g::rx,o::rx").
1838 If you are specifying individual users or groups, then the mask field
1840 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1841 "g:ID:..." field(s). A full ACL string might therefore look like this:
1842 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1844 \ Unix permissions / \mask/ \ ACL /
1845 You should use numeric UIDs and GIDs. To map usernames and groupnames
1847 to the correct numeric ID in the context of the guest, use the Augeas
1848 functions (see "guestfs_aug_init").
1849 This function returns 0 on success or -1 on error.
1851 This function depends on the feature "acl". See also
1853 "guestfs_feature_available".
1854 (Added in 1.19.63)
1856 guestfs_add_cdrom
1858 int
1859 guestfs_add_cdrom (guestfs_h *g,
1860 const char *filename);
1861 This function is deprecated. In new code, use the
1863 "guestfs_add_drive_ro" call instead.
1864 Deprecated functions will not be removed from the API, but the fact
1866 that they are deprecated indicates that there are problems with correct
1867 use of these functions.
1868 This function adds a virtual CD-ROM disk image to the guest.
1870 The image is added as read-only drive, so this function is equivalent
1872 of "guestfs_add_drive_ro".
1873 This function returns 0 on success or -1 on error.
1875 (Added in 0.3)
1877 guestfs_add_domain
1879 int
1880 guestfs_add_domain (guestfs_h *g,
1881 const char *dom,
1882 ...);
1883 You may supply a list of optional arguments to this call. Use zero or
1885 more of the following pairs of parameters, and terminate the list with
1886 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
1887 GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
1889 GUESTFS_ADD_DOMAIN_READONLY, int readonly,
1890 GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
1891 GUESTFS_ADD_DOMAIN_LIVE, int live,
1892 GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
1893 GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
1894 GUESTFS_ADD_DOMAIN_CACHEMODE, const char *cachemode,
1895 GUESTFS_ADD_DOMAIN_DISCARD, const char *discard,
1896 GUESTFS_ADD_DOMAIN_COPYONREAD, int copyonread,
1897 This function adds the disk(s) attached to the named libvirt domain
1899 "dom". It works by connecting to libvirt, requesting the domain and
1900 domain XML from libvirt, parsing it for disks, and calling
1901 "guestfs_add_drive_opts" on each one.
1902 The number of disks added is returned. This operation is atomic: if an
1904 error is returned, then no disks are added.
1905 This function does some minimal checks to make sure the libvirt domain
1907 is not running (unless "readonly" is true). In a future version we
1908 will try to acquire the libvirt lock on each disk.
1909 Disks must be accessible locally. This often means that adding disks
1911 from a remote libvirt connection (see https://libvirt.org/remote.html)
1912 will fail unless those disks are accessible via the same device path
1913 locally too.
1914 The optional "libvirturi" parameter sets the libvirt URI (see
1916 https://libvirt.org/uri.html). If this is not set then we connect to
1917 the default libvirt URI (or one set through an environment variable,
1918 see the libvirt documentation for full details).
1919 The optional "live" flag is ignored in libguestfs ≥ 1.48.
1921 If the "allowuuid" flag is true (default is false) then a UUID may be
1923 passed instead of the domain name. The "dom" string is treated as a
1924 UUID first and looked up, and if that lookup fails then we treat "dom"
1925 as a name as usual.
1926 The optional "readonlydisk" parameter controls what we do for disks
1928 which are marked <readonly/> in the libvirt XML. Possible values are:
1929 readonlydisk = "error"
1931 If "readonly" is false:
1932 The whole call is aborted with an error if any disk with the
1934 <readonly/> flag is found.
1935 If "readonly" is true:
1937 Disks with the <readonly/> flag are added read-only.
1939 readonlydisk = "read"
1941 If "readonly" is false:
1942 Disks with the <readonly/> flag are added read-only. Other disks
1944 are added read/write.
1945 If "readonly" is true:
1947 Disks with the <readonly/> flag are added read-only.
1949 readonlydisk = "write" (default)
1951 If "readonly" is false:
1952 Disks with the <readonly/> flag are added read/write.
1954 If "readonly" is true:
1956 Disks with the <readonly/> flag are added read-only.
1958 readonlydisk = "ignore"
1960 If "readonly" is true or false:
1961 Disks with the <readonly/> flag are skipped.
1963 If present, the value of "logical_block_size" attribute of <blockio/>
1965 tag in libvirt XML will be passed as "blocksize" parameter to
1966 "guestfs_add_drive_opts".
1967 The other optional parameters are passed directly through to
1969 "guestfs_add_drive_opts".
1970 On error this function returns -1.
1972 (Added in 1.7.4)
1974 guestfs_add_domain_va
1976 int
1977 guestfs_add_domain_va (guestfs_h *g,
1978 const char *dom,
1979 va_list args);
1980 This is the "va_list variant" of "guestfs_add_domain".
1982 See "CALLS WITH OPTIONAL ARGUMENTS".
1984 guestfs_add_domain_argv
1986 int
1987 guestfs_add_domain_argv (guestfs_h *g,
1988 const char *dom,
1989 const struct guestfs_add_domain_argv *optargs);
1990 This is the "argv variant" of "guestfs_add_domain".
1992 See "CALLS WITH OPTIONAL ARGUMENTS".
1994 guestfs_add_drive
1996 int
1997 guestfs_add_drive (guestfs_h *g,
1998 const char *filename);
1999 This function is provided for backwards compatibility with earlier
2001 versions of libguestfs. It simply calls "guestfs_add_drive_opts" with
2002 no optional arguments.
2003 (Added in 0.3)
2005 guestfs_add_drive_opts
2007 int
2008 guestfs_add_drive_opts (guestfs_h *g,
2009 const char *filename,
2010 ...);
2011 You may supply a list of optional arguments to this call. Use zero or
2013 more of the following pairs of parameters, and terminate the list with
2014 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2015 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2017 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2018 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2019 GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2020 GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2021 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2022 GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2023 GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2024 GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2025 GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2026 GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2027 GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2028 GUESTFS_ADD_DRIVE_OPTS_BLOCKSIZE, int blocksize,
2029 This function adds a disk image called filename to the handle.
2031 filename may be a regular host file or a host device.
2032 When this function is called before "guestfs_launch" (the usual case)
2034 then the first time you call this function, the disk appears in the API
2035 as /dev/sda, the second time as /dev/sdb, and so on.
2036 You don't necessarily need to be root when using libguestfs. However
2038 you obviously do need sufficient permissions to access the filename for
2039 whatever operations you want to perform (ie. read access if you just
2040 want to read the image or write access if you want to modify the
2041 image).
2042 This call checks that filename exists.
2044 filename may be the special string "/dev/null". See "NULL DISKS".
2046 The optional arguments are:
2048 "readonly"
2050 If true then the image is treated as read-only. Writes are still
2051 allowed, but they are stored in a temporary snapshot overlay which
2052 is discarded at the end. The disk that you add is not modified.
2053 "format"
2055 This forces the image format. If you omit this (or use
2056 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2057 automatically detected. Possible formats include "raw" and
2058 "qcow2".
2059 Automatic detection of the format opens you up to a potential
2061 security hole when dealing with untrusted raw-format images. See
2062 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
2063 security hole.
2064 "iface"
2066 This rarely-used option lets you emulate the behaviour of the
2067 deprecated "guestfs_add_drive_with_if" call (q.v.)
2068 "name"
2070 This field used to be passed as a hint for guest inspection, but it
2071 is no longer used.
2072 "label"
2074 Give the disk a label. The label should be a unique, short string
2075 using only ASCII characters "[a-zA-Z]". As well as its usual name
2076 in the API (such as /dev/sda), the drive will also be named
2077 /dev/disk/guestfs/label.
2078 See "DISK LABELS".
2080 "protocol"
2082 The optional protocol argument can be used to select an alternate
2083 source protocol.
2084 See also: "REMOTE STORAGE".
2086 "protocol = "file""
2088 filename is interpreted as a local file or device. This is the
2089 default if the optional protocol parameter is omitted.
2090 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
2092 Connect to a remote FTP, HTTP or TFTP server. The "server"
2093 parameter must also be supplied - see below.
2094 See also: "FTP, HTTP AND TFTP"
2096 "protocol = "gluster""
2098 Connect to the GlusterFS server. The "server" parameter must
2099 also be supplied - see below.
2100 See also: "GLUSTER"
2102 "protocol = "iscsi""
2104 Connect to the iSCSI server. The "server" parameter must also
2105 be supplied - see below. The "username" parameter may be
2106 supplied. See below. The "secret" parameter may be supplied.
2107 See below.
2108 See also: "ISCSI".
2110 "protocol = "nbd""
2112 Connect to the Network Block Device server. The "server"
2113 parameter must also be supplied - see below.
2114 See also: "NETWORK BLOCK DEVICE".
2116 "protocol = "rbd""
2118 Connect to the Ceph (librbd/RBD) server. The "server"
2119 parameter must also be supplied - see below. The "username"
2120 parameter may be supplied. See below. The "secret" parameter
2121 may be supplied. See below.
2122 See also: "CEPH".
2124 "protocol = "sheepdog""
2126 Connect to the Sheepdog server. The "server" parameter may
2127 also be supplied - see below.
2128 See also: "SHEEPDOG".
2130 "protocol = "ssh""
2132 Connect to the Secure Shell (ssh) server.
2133 The "server" parameter must be supplied. The "username"
2135 parameter may be supplied. See below.
2136 See also: "SSH".
2138 "server"
2140 For protocols which require access to a remote server, this is a
2141 list of server(s).
2142 Protocol Number of servers required
2144 -------- --------------------------
2145 file List must be empty or param not used at all
2146 ftp|ftps|http|https|tftp Exactly one
2147 gluster Exactly one
2148 iscsi Exactly one
2149 nbd Exactly one
2150 rbd Zero or more
2151 sheepdog Zero or more
2152 ssh Exactly one
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 "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
2168 "tftp" protocols, this specifies the remote username.
2169 If not given, then the local username is used for "ssh", and no
2171 authentication is attempted for ceph. But note this sometimes may
2172 give unexpected results, for example if using the libvirt backend
2173 and if the libvirt backend is configured to start the qemu
2174 appliance as a special user such as "qemu.qemu". If in doubt,
2175 specify the remote username you want.
2176 "secret"
2178 For the "rbd" protocol only, this specifies the ‘secret’ to use
2179 when connecting to the remote device. It must be base64 encoded.
2180 If not given, then a secret matching the given username will be
2182 looked up in the default keychain locations, or if no username is
2183 given, then no authentication will be used.
2184 "cachemode"
2186 Choose whether or not libguestfs will obey sync operations (safe
2187 but slow) or not (unsafe but fast). The possible values for this
2188 string are:
2189 "cachemode = "writeback""
2191 This is the default.
2192 Write operations in the API do not return until a write(2) call
2194 has completed in the host [but note this does not imply that
2195 anything gets written to disk].
2196 Sync operations in the API, including implicit syncs caused by
2198 filesystem journalling, will not return until an fdatasync(2)
2199 call has completed in the host, indicating that data has been
2200 committed to disk.
2201 "cachemode = "unsafe""
2203 In this mode, there are no guarantees. Libguestfs may cache
2204 anything and ignore sync requests. This is suitable only for
2205 scratch or temporary disks.
2206 "discard"
2208 Enable or disable discard (a.k.a. trim or unmap) support on this
2209 drive. If enabled, operations such as "guestfs_fstrim" will be
2210 able to discard / make thin / punch holes in the underlying host
2211 file or device.
2212 Possible discard settings are:
2214 "discard = "disable""
2216 Disable discard support. This is the default.
2217 "discard = "enable""
2219 Enable discard support. Fail if discard is not possible.
2220 "discard = "besteffort""
2222 Enable discard support if possible, but don't fail if it is not
2223 supported.
2224 Since not all backends and not all underlying systems support
2226 discard, this is a good choice if you want to use discard if
2227 possible, but don't mind if it doesn't work.
2228 "copyonread"
2230 The boolean parameter "copyonread" enables copy-on-read support.
2231 This only affects disk formats which have backing files, and causes
2232 reads to be stored in the overlay layer, speeding up multiple reads
2233 of the same area of disk.
2234 The default is false.
2236 "blocksize"
2238 This parameter sets the sector size of the disk. Possible values
2239 are 512 (the default if the parameter is omitted) or 4096. Use
2240 4096 when handling an "Advanced Format" disk that uses 4K sector
2241 size (https://en.wikipedia.org/wiki/Advanced_Format).
2242 Only a subset of the backends support this parameter (currently
2244 only the libvirt and direct backends do).
2245 This function returns 0 on success or -1 on error.
2247 (Added in 0.3)
2249 guestfs_add_drive_opts_va
2251 int
2252 guestfs_add_drive_opts_va (guestfs_h *g,
2253 const char *filename,
2254 va_list args);
2255 This is the "va_list variant" of "guestfs_add_drive_opts".
2257 See "CALLS WITH OPTIONAL ARGUMENTS".
2259 guestfs_add_drive_opts_argv
2261 int
2262 guestfs_add_drive_opts_argv (guestfs_h *g,
2263 const char *filename,
2264 const struct guestfs_add_drive_opts_argv *optargs);
2265 This is the "argv variant" of "guestfs_add_drive_opts".
2267 See "CALLS WITH OPTIONAL ARGUMENTS".
2269 guestfs_add_drive_ro
2271 int
2272 guestfs_add_drive_ro (guestfs_h *g,
2273 const char *filename);
2274 This function is the equivalent of calling "guestfs_add_drive_opts"
2276 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2277 so the disk is added read-only, with the format being detected
2278 automatically.
2279 This function returns 0 on success or -1 on error.
2281 (Added in 1.0.38)
2283 guestfs_add_drive_ro_with_if
2285 int
2286 guestfs_add_drive_ro_with_if (guestfs_h *g,
2287 const char *filename,
2288 const char *iface);
2289 This function is deprecated. In new code, use the "guestfs_add_drive"
2291 call instead.
2292 Deprecated functions will not be removed from the API, but the fact
2294 that they are deprecated indicates that there are problems with correct
2295 use of these functions.
2296 This is the same as "guestfs_add_drive_ro" but it allows you to specify
2298 the QEMU interface emulation to use at run time. Both the direct and
2299 the libvirt backends ignore "iface".
2300 This function returns 0 on success or -1 on error.
2302 (Added in 1.0.84)
2304 guestfs_add_drive_scratch
2306 int
2307 guestfs_add_drive_scratch (guestfs_h *g,
2308 int64_t size,
2309 ...);
2310 You may supply a list of optional arguments to this call. Use zero or
2312 more of the following pairs of parameters, and terminate the list with
2313 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2314 GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2316 GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2317 GUESTFS_ADD_DRIVE_SCRATCH_BLOCKSIZE, int blocksize,
2318 This command adds a temporary scratch drive to the handle. The "size"
2320 parameter is the virtual size (in bytes). The scratch drive is blank
2321 initially (all reads return zeroes until you start writing to it). The
2322 drive is deleted when the handle is closed.
2323 The optional arguments "name", "label" and "blocksize" are passed
2325 through to "guestfs_add_drive_opts".
2326 This function returns 0 on success or -1 on error.
2328 (Added in 1.23.10)
2330 guestfs_add_drive_scratch_va
2332 int
2333 guestfs_add_drive_scratch_va (guestfs_h *g,
2334 int64_t size,
2335 va_list args);
2336 This is the "va_list variant" of "guestfs_add_drive_scratch".
2338 See "CALLS WITH OPTIONAL ARGUMENTS".
2340 guestfs_add_drive_scratch_argv
2342 int
2343 guestfs_add_drive_scratch_argv (guestfs_h *g,
2344 int64_t size,
2345 const struct guestfs_add_drive_scratch_argv *optargs);
2346 This is the "argv variant" of "guestfs_add_drive_scratch".
2348 See "CALLS WITH OPTIONAL ARGUMENTS".
2350 guestfs_add_drive_with_if
2352 int
2353 guestfs_add_drive_with_if (guestfs_h *g,
2354 const char *filename,
2355 const char *iface);
2356 This function is deprecated. In new code, use the "guestfs_add_drive"
2358 call instead.
2359 Deprecated functions will not be removed from the API, but the fact
2361 that they are deprecated indicates that there are problems with correct
2362 use of these functions.
2363 This is the same as "guestfs_add_drive" but it allows you to specify
2365 the QEMU interface emulation to use at run time. Both the direct and
2366 the libvirt backends ignore "iface".
2367 This function returns 0 on success or -1 on error.
2369 (Added in 1.0.84)
2371 guestfs_add_libvirt_dom
2373 int
2374 guestfs_add_libvirt_dom (guestfs_h *g,
2375 void * /* really virDomainPtr */ dom,
2376 ...);
2377 You may supply a list of optional arguments to this call. Use zero or
2379 more of the following pairs of parameters, and terminate the list with
2380 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2381 GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2383 GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2384 GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2385 GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2386 GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2387 GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2388 GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2389 This function adds the disk(s) attached to the libvirt domain "dom".
2391 It works by requesting the domain XML from libvirt, parsing it for
2392 disks, and calling "guestfs_add_drive_opts" on each one.
2393 In the C API we declare "void *dom", but really it has type
2395 "virDomainPtr dom". This is so we don't need <libvirt.h>.
2396 The number of disks added is returned. This operation is atomic: if an
2398 error is returned, then no disks are added.
2399 This function does some minimal checks to make sure the libvirt domain
2401 is not running (unless "readonly" is true). In a future version we
2402 will try to acquire the libvirt lock on each disk.
2403 Disks must be accessible locally. This often means that adding disks
2405 from a remote libvirt connection (see https://libvirt.org/remote.html)
2406 will fail unless those disks are accessible via the same device path
2407 locally too.
2408 The optional "live" flag is ignored in libguestfs ≥ 1.48.
2410 The optional "readonlydisk" parameter controls what we do for disks
2412 which are marked <readonly/> in the libvirt XML. See
2413 "guestfs_add_domain" for possible values.
2414 If present, the value of "logical_block_size" attribute of <blockio/>
2416 tag in libvirt XML will be passed as "blocksize" parameter to
2417 "guestfs_add_drive_opts".
2418 The other optional parameters are passed directly through to
2420 "guestfs_add_drive_opts".
2421 On error this function returns -1.
2423 (Added in 1.29.14)
2425 guestfs_add_libvirt_dom_va
2427 int
2428 guestfs_add_libvirt_dom_va (guestfs_h *g,
2429 void * /* really virDomainPtr */ dom,
2430 va_list args);
2431 This is the "va_list variant" of "guestfs_add_libvirt_dom".
2433 See "CALLS WITH OPTIONAL ARGUMENTS".
2435 guestfs_add_libvirt_dom_argv
2437 int
2438 guestfs_add_libvirt_dom_argv (guestfs_h *g,
2439 void * /* really virDomainPtr */ dom,
2440 const struct guestfs_add_libvirt_dom_argv *optargs);
2441 This is the "argv variant" of "guestfs_add_libvirt_dom".
2443 See "CALLS WITH OPTIONAL ARGUMENTS".
2445 guestfs_aug_clear
2447 int
2448 guestfs_aug_clear (guestfs_h *g,
2449 const char *augpath);
2450 Set the value associated with "path" to "NULL". This is the same as
2452 the augtool(1) "clear" command.
2453 This function returns 0 on success or -1 on error.
2455 (Added in 1.3.4)
2457 guestfs_aug_close
2459 int
2460 guestfs_aug_close (guestfs_h *g);
2461 Close the current Augeas handle and free up any resources used by it.
2463 After calling this, you have to call "guestfs_aug_init" again before
2464 you can use any other Augeas functions.
2465 This function returns 0 on success or -1 on error.
2467 (Added in 0.7)
2469 guestfs_aug_defnode
2471 struct guestfs_int_bool *
2472 guestfs_aug_defnode (guestfs_h *g,
2473 const char *name,
2474 const char *expr,
2475 const char *val);
2476 Defines a variable "name" whose value is the result of evaluating
2478 "expr".
2479 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2481 to calling "guestfs_aug_set" "expr", "val". "name" will be the nodeset
2482 containing that single node.
2483 On success this returns a pair containing the number of nodes in the
2485 nodeset, and a boolean flag if a node was created.
2486 This function returns a "struct guestfs_int_bool *", or NULL if there
2488 was an error. The caller must call "guestfs_free_int_bool" after use.
2489 (Added in 0.7)
2491 guestfs_aug_defvar
2493 int
2494 guestfs_aug_defvar (guestfs_h *g,
2495 const char *name,
2496 const char *expr);
2497 Defines an Augeas variable "name" whose value is the result of
2499 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2500 On success this returns the number of nodes in "expr", or 0 if "expr"
2502 evaluates to something which is not a nodeset.
2503 On error this function returns -1.
2505 (Added in 0.7)
2507 guestfs_aug_get
2509 char *
2510 guestfs_aug_get (guestfs_h *g,
2511 const char *augpath);
2512 Look up the value associated with "path". If "path" matches exactly
2514 one node, the "value" is returned.
2515 This function returns a string, or NULL on error. The caller must free
2517 the returned string after use.
2518 (Added in 0.7)
2520 guestfs_aug_init
2522 int
2523 guestfs_aug_init (guestfs_h *g,
2524 const char *root,
2525 int flags);
2526 Create a new Augeas handle for editing configuration files. If there
2528 was any previous Augeas handle associated with this guestfs session,
2529 then it is closed.
2530 You must call this before using any other "guestfs_aug_*" commands.
2532 "root" is the filesystem root. "root" must not be NULL, use / instead.
2534 The flags are the same as the flags defined in <augeas.h>, the logical
2536 or of the following integers:
2537 "AUG_SAVE_BACKUP" = 1
2539 Keep the original file with a ".augsave" extension.
2540 "AUG_SAVE_NEWFILE" = 2
2542 Save changes into a file with extension ".augnew", and do not
2543 overwrite original. Overrides "AUG_SAVE_BACKUP".
2544 "AUG_TYPE_CHECK" = 4
2546 Typecheck lenses.
2547 This option is only useful when debugging Augeas lenses. Use of
2549 this option may require additional memory for the libguestfs
2550 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2551 environment variable or call "guestfs_set_memsize".
2552 "AUG_NO_STDINC" = 8
2554 Do not use standard load path for modules.
2555 "AUG_SAVE_NOOP" = 16
2557 Make save a no-op, just record what would have been changed.
2558 "AUG_NO_LOAD" = 32
2560 Do not load the tree in "guestfs_aug_init".
2561 To close the handle, you can call "guestfs_aug_close".
2563 To find out more about Augeas, see http://augeas.net/.
2565 This function returns 0 on success or -1 on error.
2567 (Added in 0.7)
2569 guestfs_aug_insert
2571 int
2572 guestfs_aug_insert (guestfs_h *g,
2573 const char *augpath,
2574 const char *label,
2575 int before);
2576 Create a new sibling "label" for "path", inserting it into the tree
2578 before or after "path" (depending on the boolean flag "before").
2579 "path" must match exactly one existing node in the tree, and "label"
2581 must be a label, ie. not contain /, "*" or end with a bracketed index
2582 "[N]".
2583 This function returns 0 on success or -1 on error.
2585 (Added in 0.7)
2587 guestfs_aug_label
2589 char *
2590 guestfs_aug_label (guestfs_h *g,
2591 const char *augpath);
2592 The label (name of the last element) of the Augeas path expression
2594 "augpath" is returned. "augpath" must match exactly one node, else
2595 this function returns an error.
2596 This function returns a string, or NULL on error. The caller must free
2598 the returned string after use.
2599 (Added in 1.23.14)
2601 guestfs_aug_load
2603 int
2604 guestfs_aug_load (guestfs_h *g);
2605 Load files into the tree.
2607 See "aug_load" in the Augeas documentation for the full gory details.
2609 This function returns 0 on success or -1 on error.
2611 (Added in 0.7)
2613 guestfs_aug_ls
2615 char **
2616 guestfs_aug_ls (guestfs_h *g,
2617 const char *augpath);
2618 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2620 sorting the resulting nodes into alphabetical order.
2621 This function returns a NULL-terminated array of strings (like
2623 environ(3)), or NULL if there was an error. The caller must free the
2624 strings and the array after use.
2625 (Added in 0.8)
2627 guestfs_aug_match
2629 char **
2630 guestfs_aug_match (guestfs_h *g,
2631 const char *augpath);
2632 Returns a list of paths which match the path expression "path". The
2634 returned paths are sufficiently qualified so that they match exactly
2635 one node in the current tree.
2636 This function returns a NULL-terminated array of strings (like
2638 environ(3)), or NULL if there was an error. The caller must free the
2639 strings and the array after use.
2640 (Added in 0.7)
2642 guestfs_aug_mv
2644 int
2645 guestfs_aug_mv (guestfs_h *g,
2646 const char *src,
2647 const char *dest);
2648 Move the node "src" to "dest". "src" must match exactly one node.
2650 "dest" is overwritten if it exists.
2651 This function returns 0 on success or -1 on error.
2653 (Added in 0.7)
2655 guestfs_aug_rm
2657 int
2658 guestfs_aug_rm (guestfs_h *g,
2659 const char *augpath);
2660 Remove "path" and all of its children.
2662 On success this returns the number of entries which were removed.
2664 On error this function returns -1.
2666 (Added in 0.7)
2668 guestfs_aug_save
2670 int
2671 guestfs_aug_save (guestfs_h *g);
2672 This writes all pending changes to disk.
2674 The flags which were passed to "guestfs_aug_init" affect exactly how
2676 files are saved.
2677 This function returns 0 on success or -1 on error.
2679 (Added in 0.7)
2681 guestfs_aug_set
2683 int
2684 guestfs_aug_set (guestfs_h *g,
2685 const char *augpath,
2686 const char *val);
2687 Set the value associated with "augpath" to "val".
2689 In the Augeas API, it is possible to clear a node by setting the value
2691 to NULL. Due to an oversight in the libguestfs API you cannot do that
2692 with this call. Instead you must use the "guestfs_aug_clear" call.
2693 This function returns 0 on success or -1 on error.
2695 (Added in 0.7)
2697 guestfs_aug_setm
2699 int
2700 guestfs_aug_setm (guestfs_h *g,
2701 const char *base,
2702 const char *sub,
2703 const char *val);
2704 Change multiple Augeas nodes in a single operation. "base" is an
2706 expression matching multiple nodes. "sub" is a path expression
2707 relative to "base". All nodes matching "base" are found, and then for
2708 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2709 which case the "base" nodes are modified.
2710 This returns the number of nodes modified.
2712 On error this function returns -1.
2714 (Added in 1.23.14)
2716 guestfs_aug_transform
2718 int
2719 guestfs_aug_transform (guestfs_h *g,
2720 const char *lens,
2721 const char *file,
2722 ...);
2723 You may supply a list of optional arguments to this call. Use zero or
2725 more of the following pairs of parameters, and terminate the list with
2726 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2727 GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2729 Add an Augeas transformation for the specified "lens" so it can handle
2731 "file".
2732 If "remove" is true ("false" by default), then the transformation is
2734 removed.
2735 This function returns 0 on success or -1 on error.
2737 (Added in 1.35.2)
2739 guestfs_aug_transform_va
2741 int
2742 guestfs_aug_transform_va (guestfs_h *g,
2743 const char *lens,
2744 const char *file,
2745 va_list args);
2746 This is the "va_list variant" of "guestfs_aug_transform".
2748 See "CALLS WITH OPTIONAL ARGUMENTS".
2750 guestfs_aug_transform_argv
2752 int
2753 guestfs_aug_transform_argv (guestfs_h *g,
2754 const char *lens,
2755 const char *file,
2756 const struct guestfs_aug_transform_argv *optargs);
2757 This is the "argv variant" of "guestfs_aug_transform".
2759 See "CALLS WITH OPTIONAL ARGUMENTS".
2761 guestfs_available
2763 int
2764 guestfs_available (guestfs_h *g,
2765 char *const *groups);
2766 This command is used to check the availability of some groups of
2768 functionality in the appliance, which not all builds of the libguestfs
2769 appliance will be able to provide.
2770 The libguestfs groups, and the functions that those groups correspond
2772 to, are listed in "AVAILABILITY". You can also fetch this list at
2773 runtime by calling "guestfs_available_all_groups".
2774 The argument "groups" is a list of group names, eg: "["inotify",
2776 "augeas"]" would check for the availability of the Linux inotify
2777 functions and Augeas (configuration file editing) functions.
2778 The command returns no error if all requested groups are available.
2780 It fails with an error if one or more of the requested groups is
2782 unavailable in the appliance.
2783 If an unknown group name is included in the list of groups then an
2785 error is always returned.
2786 Notes:
2788 • "guestfs_feature_available" is the same as this call, but with a
2790 slightly simpler to use API: that call returns a boolean true/false
2791 instead of throwing an error.
2792 • You must call "guestfs_launch" before calling this function.
2794 The reason is because we don't know what groups are supported by
2796 the appliance/daemon until it is running and can be queried.
2797 • If a group of functions is available, this does not necessarily
2799 mean that they will work. You still have to check for errors when
2800 calling individual API functions even if they are available.
2801 • It is usually the job of distro packagers to build complete
2803 functionality into the libguestfs appliance. Upstream libguestfs,
2804 if built from source with all requirements satisfied, will support
2805 everything.
2806 • This call was added in version 1.0.80. In previous versions of
2808 libguestfs all you could do would be to speculatively execute a
2809 command to find out if the daemon implemented it. See also
2810 "guestfs_version".
2811 See also "guestfs_filesystem_available".
2813 This function returns 0 on success or -1 on error.
2815 (Added in 1.0.80)
2817 guestfs_available_all_groups
2819 char **
2820 guestfs_available_all_groups (guestfs_h *g);
2821 This command returns a list of all optional groups that this daemon
2823 knows about. Note this returns both supported and unsupported groups.
2824 To find out which ones the daemon can actually support you have to call
2825 "guestfs_available" / "guestfs_feature_available" on each member of the
2826 returned list.
2827 See also "guestfs_available", "guestfs_feature_available" and
2829 "AVAILABILITY".
2830 This function returns a NULL-terminated array of strings (like
2832 environ(3)), or NULL if there was an error. The caller must free the
2833 strings and the array after use.
2834 (Added in 1.3.15)
2836 guestfs_base64_in
2838 int
2839 guestfs_base64_in (guestfs_h *g,
2840 const char *base64file,
2841 const char *filename);
2842 This command uploads base64-encoded data from "base64file" to filename.
2844 This function returns 0 on success or -1 on error.
2846 (Added in 1.3.5)
2848 guestfs_base64_out
2850 int
2851 guestfs_base64_out (guestfs_h *g,
2852 const char *filename,
2853 const char *base64file);
2854 This command downloads the contents of filename, writing it out to
2856 local file "base64file" encoded as base64.
2857 This function returns 0 on success or -1 on error.
2859 (Added in 1.3.5)
2861 guestfs_blkdiscard
2863 int
2864 guestfs_blkdiscard (guestfs_h *g,
2865 const char *device);
2866 This discards all blocks on the block device "device", giving the free
2868 space back to the host.
2869 This operation requires support in libguestfs, the host filesystem,
2871 qemu and the host kernel. If this support isn't present it may give an
2872 error or even appear to run but do nothing. You must also set the
2873 "discard" attribute on the underlying drive (see
2874 "guestfs_add_drive_opts").
2875 This function returns 0 on success or -1 on error.
2877 This function depends on the feature "blkdiscard". See also
2879 "guestfs_feature_available".
2880 (Added in 1.25.44)
2882 guestfs_blkdiscardzeroes
2884 int
2885 guestfs_blkdiscardzeroes (guestfs_h *g,
2886 const char *device);
2887 This call returns true if blocks on "device" that have been discarded
2889 by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
2890 when read the next time.
2891 If it returns false, then it may be that discarded blocks are read as
2893 stale or random data.
2894 This function returns a C truth value on success or -1 on error.
2896 This function depends on the feature "blkdiscardzeroes". See also
2898 "guestfs_feature_available".
2899 (Added in 1.25.44)
2901 guestfs_blkid
2903 char **
2904 guestfs_blkid (guestfs_h *g,
2905 const char *device);
2906 This command returns block device attributes for "device". The
2908 following fields are usually present in the returned hash. Other fields
2909 may also be present.
2910 "UUID"
2912 The uuid of this device.
2913 "LABEL"
2915 The label of this device.
2916 "VERSION"
2918 The version of blkid command.
2919 "TYPE"
2921 The filesystem type or RAID of this device.
2922 "USAGE"
2924 The usage of this device, for example "filesystem" or "raid".
2925 This function returns a NULL-terminated array of strings, or NULL if
2927 there was an error. The array of strings will always have length
2928 "2n+1", where "n" keys and values alternate, followed by the trailing
2929 NULL entry. The caller must free the strings and the array after use.
2930 (Added in 1.15.9)
2932 guestfs_blockdev_flushbufs
2934 int
2935 guestfs_blockdev_flushbufs (guestfs_h *g,
2936 const char *device);
2937 This tells the kernel to flush internal buffers associated with
2939 "device".
2940 This uses the blockdev(8) command.
2942 This function returns 0 on success or -1 on error.
2944 (Added in 1.9.3)
2946 guestfs_blockdev_getbsz
2948 int
2949 guestfs_blockdev_getbsz (guestfs_h *g,
2950 const char *device);
2951 This returns the block size of a device.
2953 Note: this is different from both size in blocks and filesystem block
2955 size. Also this setting is not really used by anything. You should
2956 probably not use it for anything. Filesystems have their own idea
2957 about what block size to choose.
2958 This uses the blockdev(8) command.
2960 On error this function returns -1.
2962 (Added in 1.9.3)
2964 guestfs_blockdev_getro
2966 int
2967 guestfs_blockdev_getro (guestfs_h *g,
2968 const char *device);
2969 Returns a boolean indicating if the block device is read-only (true if
2971 read-only, false if not).
2972 This uses the blockdev(8) command.
2974 This function returns a C truth value on success or -1 on error.
2976 (Added in 1.9.3)
2978 guestfs_blockdev_getsize64
2980 int64_t
2981 guestfs_blockdev_getsize64 (guestfs_h *g,
2982 const char *device);
2983 This returns the size of the device in bytes.
2985 See also "guestfs_blockdev_getsz".
2987 This uses the blockdev(8) command.
2989 On error this function returns -1.
2991 (Added in 1.9.3)
2993 guestfs_blockdev_getss
2995 int
2996 guestfs_blockdev_getss (guestfs_h *g,
2997 const char *device);
2998 This returns the size of sectors on a block device. Usually 512, but
3000 can be larger for modern devices.
3001 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
3003 for that).
3004 This uses the blockdev(8) command.
3006 On error this function returns -1.
3008 (Added in 1.9.3)
3010 guestfs_blockdev_getsz
3012 int64_t
3013 guestfs_blockdev_getsz (guestfs_h *g,
3014 const char *device);
3015 This returns the size of the device in units of 512-byte sectors (even
3017 if the sectorsize isn't 512 bytes ... weird).
3018 See also "guestfs_blockdev_getss" for the real sector size of the
3020 device, and "guestfs_blockdev_getsize64" for the more useful size in
3021 bytes.
3022 This uses the blockdev(8) command.
3024 On error this function returns -1.
3026 (Added in 1.9.3)
3028 guestfs_blockdev_rereadpt
3030 int
3031 guestfs_blockdev_rereadpt (guestfs_h *g,
3032 const char *device);
3033 Reread the partition table on "device".
3035 This uses the blockdev(8) command.
3037 This function returns 0 on success or -1 on error.
3039 (Added in 1.9.3)
3041 guestfs_blockdev_setbsz
3043 int
3044 guestfs_blockdev_setbsz (guestfs_h *g,
3045 const char *device,
3046 int blocksize);
3047 This function is deprecated. There is no replacement. Consult the API
3049 documentation in guestfs(3) for further information.
3050 Deprecated functions will not be removed from the API, but the fact
3052 that they are deprecated indicates that there are problems with correct
3053 use of these functions.
3054 This call does nothing and has never done anything because of a bug in
3056 blockdev. Do not use it.
3057 If you need to set the filesystem block size, use the "blocksize"
3059 option of "guestfs_mkfs".
3060 This function returns 0 on success or -1 on error.
3062 (Added in 1.9.3)
3064 guestfs_blockdev_setra
3066 int
3067 guestfs_blockdev_setra (guestfs_h *g,
3068 const char *device,
3069 int sectors);
3070 Set readahead (in 512-byte sectors) for the device.
3072 This uses the blockdev(8) command.
3074 This function returns 0 on success or -1 on error.
3076 (Added in 1.29.10)
3078 guestfs_blockdev_setro
3080 int
3081 guestfs_blockdev_setro (guestfs_h *g,
3082 const char *device);
3083 Sets the block device named "device" to read-only.
3085 This uses the blockdev(8) command.
3087 This function returns 0 on success or -1 on error.
3089 (Added in 1.9.3)
3091 guestfs_blockdev_setrw
3093 int
3094 guestfs_blockdev_setrw (guestfs_h *g,
3095 const char *device);
3096 Sets the block device named "device" to read-write.
3098 This uses the blockdev(8) command.
3100 This function returns 0 on success or -1 on error.
3102 (Added in 1.9.3)
3104 guestfs_btrfs_balance_cancel
3106 int
3107 guestfs_btrfs_balance_cancel (guestfs_h *g,
3108 const char *path);
3109 Cancel 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_pause
3120 int
3121 guestfs_btrfs_balance_pause (guestfs_h *g,
3122 const char *path);
3123 Pause a running 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_resume
3134 int
3135 guestfs_btrfs_balance_resume (guestfs_h *g,
3136 const char *path);
3137 Resume a paused balance on a btrfs filesystem.
3139 This function returns 0 on success or -1 on error.
3141 This function depends on the feature "btrfs". See also
3143 "guestfs_feature_available".
3144 (Added in 1.29.22)
3146 guestfs_btrfs_balance_status
3148 struct guestfs_btrfsbalance *
3149 guestfs_btrfs_balance_status (guestfs_h *g,
3150 const char *path);
3151 Show the status of a running or paused balance on a btrfs filesystem.
3153 This function returns a "struct guestfs_btrfsbalance *", or NULL if
3155 there was an error. The caller must call "guestfs_free_btrfsbalance"
3156 after use.
3157 This function depends on the feature "btrfs". See also
3159 "guestfs_feature_available".
3160 (Added in 1.29.26)
3162 guestfs_btrfs_device_add
3164 int
3165 guestfs_btrfs_device_add (guestfs_h *g,
3166 char *const *devices,
3167 const char *fs);
3168 Add the list of device(s) in "devices" to the btrfs filesystem mounted
3170 at "fs". If "devices" is an empty list, this does nothing.
3171 This function returns 0 on success or -1 on error.
3173 This function depends on the feature "btrfs". See also
3175 "guestfs_feature_available".
3176 (Added in 1.17.35)
3178 guestfs_btrfs_device_delete
3180 int
3181 guestfs_btrfs_device_delete (guestfs_h *g,
3182 char *const *devices,
3183 const char *fs);
3184 Remove the "devices" from the btrfs filesystem mounted at "fs". If
3186 "devices" is an empty list, this does nothing.
3187 This function returns 0 on success or -1 on error.
3189 This function depends on the feature "btrfs". See also
3191 "guestfs_feature_available".
3192 (Added in 1.17.35)
3194 guestfs_btrfs_filesystem_balance
3196 int
3197 guestfs_btrfs_filesystem_balance (guestfs_h *g,
3198 const char *fs);
3199 Balance the chunks in the btrfs filesystem mounted at "fs" across the
3201 underlying devices.
3202 This function returns 0 on success or -1 on error.
3204 This function depends on the feature "btrfs". See also
3206 "guestfs_feature_available".
3207 (Added in 1.17.35)
3209 guestfs_btrfs_filesystem_defragment
3211 int
3212 guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3213 const char *path,
3214 ...);
3215 You may supply a list of optional arguments to this call. Use zero or
3217 more of the following pairs of parameters, and terminate the list with
3218 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3219 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3221 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3222 Defragment a file or directory on a btrfs filesystem. compress is one
3224 of zlib or lzo.
3225 This function returns 0 on success or -1 on error.
3227 This function depends on the feature "btrfs". See also
3229 "guestfs_feature_available".
3230 (Added in 1.29.22)
3232 guestfs_btrfs_filesystem_defragment_va
3234 int
3235 guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3236 const char *path,
3237 va_list args);
3238 This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3240 See "CALLS WITH OPTIONAL ARGUMENTS".
3242 guestfs_btrfs_filesystem_defragment_argv
3244 int
3245 guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3246 const char *path,
3247 const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3248 This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3250 See "CALLS WITH OPTIONAL ARGUMENTS".
3252 guestfs_btrfs_filesystem_resize
3254 int
3255 guestfs_btrfs_filesystem_resize (guestfs_h *g,
3256 const char *mountpoint,
3257 ...);
3258 You may supply a list of optional arguments to this call. Use zero or
3260 more of the following pairs of parameters, and terminate the list with
3261 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3262 GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3264 This command resizes a btrfs filesystem.
3266 Note that unlike other resize calls, the filesystem has to be mounted
3268 and the parameter is the mountpoint not the device (this is a
3269 requirement of btrfs itself).
3270 The optional parameters are:
3272 "size"
3274 The new size (in bytes) of the filesystem. If omitted, the
3275 filesystem is resized to the maximum size.
3276 See also btrfs(8).
3278 This function returns 0 on success or -1 on error.
3280 This function depends on the feature "btrfs". See also
3282 "guestfs_feature_available".
3283 (Added in 1.11.17)
3285 guestfs_btrfs_filesystem_resize_va
3287 int
3288 guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3289 const char *mountpoint,
3290 va_list args);
3291 This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3293 See "CALLS WITH OPTIONAL ARGUMENTS".
3295 guestfs_btrfs_filesystem_resize_argv
3297 int
3298 guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3299 const char *mountpoint,
3300 const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3301 This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3303 See "CALLS WITH OPTIONAL ARGUMENTS".
3305 guestfs_btrfs_filesystem_show
3307 char **
3308 guestfs_btrfs_filesystem_show (guestfs_h *g,
3309 const char *device);
3310 Show all the devices where the filesystems in "device" is spanned over.
3312 If not all the devices for the filesystems are present, then this
3314 function fails and the "errno" is set to "ENODEV".
3315 This function returns a NULL-terminated array of strings (like
3317 environ(3)), or NULL if there was an error. The caller must free the
3318 strings and the array after use.
3319 This function depends on the feature "btrfs". See also
3321 "guestfs_feature_available".
3322 (Added in 1.33.29)
3324 guestfs_btrfs_filesystem_sync
3326 int
3327 guestfs_btrfs_filesystem_sync (guestfs_h *g,
3328 const char *fs);
3329 Force sync on the btrfs filesystem mounted at "fs".
3331 This function returns 0 on success or -1 on error.
3333 This function depends on the feature "btrfs". See also
3335 "guestfs_feature_available".
3336 (Added in 1.17.35)
3338 guestfs_btrfs_fsck
3340 int
3341 guestfs_btrfs_fsck (guestfs_h *g,
3342 const char *device,
3343 ...);
3344 You may supply a list of optional arguments to this call. Use zero or
3346 more of the following pairs of parameters, and terminate the list with
3347 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3348 GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3350 GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3351 Used to check a btrfs filesystem, "device" is the device file where the
3353 filesystem is stored.
3354 This function returns 0 on success or -1 on error.
3356 This function depends on the feature "btrfs". See also
3358 "guestfs_feature_available".
3359 (Added in 1.17.43)
3361 guestfs_btrfs_fsck_va
3363 int
3364 guestfs_btrfs_fsck_va (guestfs_h *g,
3365 const char *device,
3366 va_list args);
3367 This is the "va_list variant" of "guestfs_btrfs_fsck".
3369 See "CALLS WITH OPTIONAL ARGUMENTS".
3371 guestfs_btrfs_fsck_argv
3373 int
3374 guestfs_btrfs_fsck_argv (guestfs_h *g,
3375 const char *device,
3376 const struct guestfs_btrfs_fsck_argv *optargs);
3377 This is the "argv variant" of "guestfs_btrfs_fsck".
3379 See "CALLS WITH OPTIONAL ARGUMENTS".
3381 guestfs_btrfs_image
3383 int
3384 guestfs_btrfs_image (guestfs_h *g,
3385 char *const *source,
3386 const char *image,
3387 ...);
3388 You may supply a list of optional arguments to this call. Use zero or
3390 more of the following pairs of parameters, and terminate the list with
3391 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3392 GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3394 This is used to create an image of a btrfs filesystem. All data will
3396 be zeroed, but metadata and the like is preserved.
3397 This function returns 0 on success or -1 on error.
3399 This function depends on the feature "btrfs". See also
3401 "guestfs_feature_available".
3402 (Added in 1.29.32)
3404 guestfs_btrfs_image_va
3406 int
3407 guestfs_btrfs_image_va (guestfs_h *g,
3408 char *const *source,
3409 const char *image,
3410 va_list args);
3411 This is the "va_list variant" of "guestfs_btrfs_image".
3413 See "CALLS WITH OPTIONAL ARGUMENTS".
3415 guestfs_btrfs_image_argv
3417 int
3418 guestfs_btrfs_image_argv (guestfs_h *g,
3419 char *const *source,
3420 const char *image,
3421 const struct guestfs_btrfs_image_argv *optargs);
3422 This is the "argv variant" of "guestfs_btrfs_image".
3424 See "CALLS WITH OPTIONAL ARGUMENTS".
3426 guestfs_btrfs_qgroup_assign
3428 int
3429 guestfs_btrfs_qgroup_assign (guestfs_h *g,
3430 const char *src,
3431 const char *dst,
3432 const char *path);
3433 Add qgroup "src" to parent qgroup "dst". This command can group several
3435 qgroups into a parent qgroup to share common limit.
3436 This function returns 0 on success or -1 on error.
3438 This function depends on the feature "btrfs". See also
3440 "guestfs_feature_available".
3441 (Added in 1.29.17)
3443 guestfs_btrfs_qgroup_create
3445 int
3446 guestfs_btrfs_qgroup_create (guestfs_h *g,
3447 const char *qgroupid,
3448 const char *subvolume);
3449 Create a quota group (qgroup) for subvolume at "subvolume".
3451 This function returns 0 on success or -1 on error.
3453 This function depends on the feature "btrfs". See also
3455 "guestfs_feature_available".
3456 (Added in 1.29.17)
3458 guestfs_btrfs_qgroup_destroy
3460 int
3461 guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3462 const char *qgroupid,
3463 const char *subvolume);
3464 Destroy a quota group.
3466 This function returns 0 on success or -1 on error.
3468 This function depends on the feature "btrfs". See also
3470 "guestfs_feature_available".
3471 (Added in 1.29.17)
3473 guestfs_btrfs_qgroup_limit
3475 int
3476 guestfs_btrfs_qgroup_limit (guestfs_h *g,
3477 const char *subvolume,
3478 int64_t size);
3479 Limit the size of the subvolume with path "subvolume".
3481 This function returns 0 on success or -1 on error.
3483 This function depends on the feature "btrfs". See also
3485 "guestfs_feature_available".
3486 (Added in 1.29.17)
3488 guestfs_btrfs_qgroup_remove
3490 int
3491 guestfs_btrfs_qgroup_remove (guestfs_h *g,
3492 const char *src,
3493 const char *dst,
3494 const char *path);
3495 Remove qgroup "src" from the parent qgroup "dst".
3497 This function returns 0 on success or -1 on error.
3499 This function depends on the feature "btrfs". See also
3501 "guestfs_feature_available".
3502 (Added in 1.29.17)
3504 guestfs_btrfs_qgroup_show
3506 struct guestfs_btrfsqgroup_list *
3507 guestfs_btrfs_qgroup_show (guestfs_h *g,
3508 const char *path);
3509 Show all subvolume quota groups in a btrfs filesystem, including their
3511 usages.
3512 This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3514 there was an error. The caller must call
3515 "guestfs_free_btrfsqgroup_list" after use.
3516 This function depends on the feature "btrfs". See also
3518 "guestfs_feature_available".
3519 (Added in 1.29.17)
3521 guestfs_btrfs_quota_enable
3523 int
3524 guestfs_btrfs_quota_enable (guestfs_h *g,
3525 const char *fs,
3526 int enable);
3527 Enable or disable subvolume quota support for filesystem which contains
3529 "path".
3530 This function returns 0 on success or -1 on error.
3532 This function depends on the feature "btrfs". See also
3534 "guestfs_feature_available".
3535 (Added in 1.29.17)
3537 guestfs_btrfs_quota_rescan
3539 int
3540 guestfs_btrfs_quota_rescan (guestfs_h *g,
3541 const char *fs);
3542 Trash all qgroup numbers and scan the metadata again with the current
3544 config.
3545 This function returns 0 on success or -1 on error.
3547 This function depends on the feature "btrfs". See also
3549 "guestfs_feature_available".
3550 (Added in 1.29.17)
3552 guestfs_btrfs_replace
3554 int
3555 guestfs_btrfs_replace (guestfs_h *g,
3556 const char *srcdev,
3557 const char *targetdev,
3558 const char *mntpoint);
3559 Replace device of a btrfs filesystem. On a live filesystem, duplicate
3561 the data to the target device which is currently stored on the source
3562 device. After completion of the operation, the source device is wiped
3563 out and removed from the filesystem.
3564 The "targetdev" needs to be same size or larger than the "srcdev".
3566 Devices which are currently mounted are never allowed to be used as the
3567 "targetdev".
3568 This function returns 0 on success or -1 on error.
3570 This function depends on the feature "btrfs". See also
3572 "guestfs_feature_available".
3573 (Added in 1.29.48)
3575 guestfs_btrfs_rescue_chunk_recover
3577 int
3578 guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3579 const char *device);
3580 Recover the chunk tree of btrfs filesystem by scanning the devices one
3582 by one.
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_rescue_super_recover
3592 int
3593 guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3594 const char *device);
3595 Recover bad superblocks from good copies.
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_cancel
3606 int
3607 guestfs_btrfs_scrub_cancel (guestfs_h *g,
3608 const char *path);
3609 Cancel a running scrub on a btrfs filesystem.
3611 This function returns 0 on success or -1 on error.
3613 This function depends on the feature "btrfs". See also
3615 "guestfs_feature_available".
3616 (Added in 1.29.22)
3618 guestfs_btrfs_scrub_resume
3620 int
3621 guestfs_btrfs_scrub_resume (guestfs_h *g,
3622 const char *path);
3623 Resume a previously canceled or interrupted scrub on a btrfs
3625 filesystem.
3626 This function returns 0 on success or -1 on error.
3628 This function depends on the feature "btrfs". See also
3630 "guestfs_feature_available".
3631 (Added in 1.29.22)
3633 guestfs_btrfs_scrub_start
3635 int
3636 guestfs_btrfs_scrub_start (guestfs_h *g,
3637 const char *path);
3638 Reads all the data and metadata on the filesystem, and uses checksums
3640 and the duplicate copies from RAID storage to identify and repair any
3641 corrupt data.
3642 This function returns 0 on success or -1 on error.
3644 This function depends on the feature "btrfs". See also
3646 "guestfs_feature_available".
3647 (Added in 1.29.22)
3649 guestfs_btrfs_scrub_status
3651 struct guestfs_btrfsscrub *
3652 guestfs_btrfs_scrub_status (guestfs_h *g,
3653 const char *path);
3654 Show status of running or finished scrub on a btrfs filesystem.
3656 This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3658 was an error. The caller must call "guestfs_free_btrfsscrub" after
3659 use.
3660 This function depends on the feature "btrfs". See also
3662 "guestfs_feature_available".
3663 (Added in 1.29.26)
3665 guestfs_btrfs_set_seeding
3667 int
3668 guestfs_btrfs_set_seeding (guestfs_h *g,
3669 const char *device,
3670 int seeding);
3671 Enable or disable the seeding feature of a device that contains a btrfs
3673 filesystem.
3674 This function returns 0 on success or -1 on error.
3676 This function depends on the feature "btrfs". See also
3678 "guestfs_feature_available".
3679 (Added in 1.17.43)
3681 guestfs_btrfs_subvolume_create
3683 int
3684 guestfs_btrfs_subvolume_create (guestfs_h *g,
3685 const char *dest);
3686 This function is provided for backwards compatibility with earlier
3688 versions of libguestfs. It simply calls
3689 "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3690 (Added in 1.17.35)
3692 guestfs_btrfs_subvolume_create_opts
3694 int
3695 guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3696 const char *dest,
3697 ...);
3698 You may supply a list of optional arguments to this call. Use zero or
3700 more of the following pairs of parameters, and terminate the list with
3701 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3702 GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3704 Create a btrfs subvolume. The "dest" argument is the destination
3706 directory and the name of the subvolume, in the form
3707 /path/to/dest/name. The optional parameter "qgroupid" represents the
3708 qgroup which the newly created subvolume will be added to.
3709 This function returns 0 on success or -1 on error.
3711 This function depends on the feature "btrfs". See also
3713 "guestfs_feature_available".
3714 (Added in 1.17.35)
3716 guestfs_btrfs_subvolume_create_opts_va
3718 int
3719 guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3720 const char *dest,
3721 va_list args);
3722 This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3724 See "CALLS WITH OPTIONAL ARGUMENTS".
3726 guestfs_btrfs_subvolume_create_opts_argv
3728 int
3729 guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3730 const char *dest,
3731 const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3732 This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3734 See "CALLS WITH OPTIONAL ARGUMENTS".
3736 guestfs_btrfs_subvolume_delete
3738 int
3739 guestfs_btrfs_subvolume_delete (guestfs_h *g,
3740 const char *subvolume);
3741 Delete the named btrfs subvolume or snapshot.
3743 This function returns 0 on success or -1 on error.
3745 This function depends on the feature "btrfs". See also
3747 "guestfs_feature_available".
3748 (Added in 1.17.35)
3750 guestfs_btrfs_subvolume_get_default
3752 int64_t
3753 guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3754 const char *fs);
3755 Get the default subvolume or snapshot of a filesystem mounted at
3757 "mountpoint".
3758 On error this function returns -1.
3760 This function depends on the feature "btrfs". See also
3762 "guestfs_feature_available".
3763 (Added in 1.29.17)
3765 guestfs_btrfs_subvolume_list
3767 struct guestfs_btrfssubvolume_list *
3768 guestfs_btrfs_subvolume_list (guestfs_h *g,
3769 const char *fs);
3770 List the btrfs snapshots and subvolumes of the btrfs filesystem which
3772 is mounted at "fs".
3773 This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3775 if there was an error. The caller must call
3776 "guestfs_free_btrfssubvolume_list" after use.
3777 This function depends on the feature "btrfs". See also
3779 "guestfs_feature_available".
3780 (Added in 1.17.35)
3782 guestfs_btrfs_subvolume_set_default
3784 int
3785 guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3786 int64_t id,
3787 const char *fs);
3788 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3790 default. See "guestfs_btrfs_subvolume_list" to get a list of
3791 subvolumes.
3792 This function returns 0 on success or -1 on error.
3794 This function depends on the feature "btrfs". See also
3796 "guestfs_feature_available".
3797 (Added in 1.17.35)
3799 guestfs_btrfs_subvolume_show
3801 char **
3802 guestfs_btrfs_subvolume_show (guestfs_h *g,
3803 const char *subvolume);
3804 Return detailed information of the subvolume.
3806 This function returns a NULL-terminated array of strings, or NULL if
3808 there was an error. The array of strings will always have length
3809 "2n+1", where "n" keys and values alternate, followed by the trailing
3810 NULL entry. The caller must free the strings and the array after use.
3811 This function depends on the feature "btrfs". See also
3813 "guestfs_feature_available".
3814 (Added in 1.29.17)
3816 guestfs_btrfs_subvolume_snapshot
3818 int
3819 guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3820 const char *source,
3821 const char *dest);
3822 This function is provided for backwards compatibility with earlier
3824 versions of libguestfs. It simply calls
3825 "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3826 (Added in 1.17.35)
3828 guestfs_btrfs_subvolume_snapshot_opts
3830 int
3831 guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3832 const char *source,
3833 const char *dest,
3834 ...);
3835 You may supply a list of optional arguments to this call. Use zero or
3837 more of the following pairs of parameters, and terminate the list with
3838 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3839 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3841 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3842 Create a snapshot of the btrfs subvolume "source". The "dest" argument
3844 is the destination directory and the name of the snapshot, in the form
3845 /path/to/dest/name. By default the newly created snapshot is writable,
3846 if the value of optional parameter "ro" is true, then a readonly
3847 snapshot is created. The optional parameter "qgroupid" represents the
3848 qgroup which the newly created snapshot will be added to.
3849 This function returns 0 on success or -1 on error.
3851 This function depends on the feature "btrfs". See also
3853 "guestfs_feature_available".
3854 (Added in 1.17.35)
3856 guestfs_btrfs_subvolume_snapshot_opts_va
3858 int
3859 guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
3860 const char *source,
3861 const char *dest,
3862 va_list args);
3863 This is the "va_list variant" of
3865 "guestfs_btrfs_subvolume_snapshot_opts".
3866 See "CALLS WITH OPTIONAL ARGUMENTS".
3868 guestfs_btrfs_subvolume_snapshot_opts_argv
3870 int
3871 guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
3872 const char *source,
3873 const char *dest,
3874 const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
3875 This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
3877 See "CALLS WITH OPTIONAL ARGUMENTS".
3879 guestfs_btrfstune_enable_extended_inode_refs
3881 int
3882 guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
3883 const char *device);
3884 This will Enable extended inode 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_enable_skinny_metadata_extent_refs
3895 int
3896 guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
3897 const char *device);
3898 This enable skinny metadata extent refs.
3900 This function returns 0 on success or -1 on error.
3902 This function depends on the feature "btrfs". See also
3904 "guestfs_feature_available".
3905 (Added in 1.29.29)
3907 guestfs_btrfstune_seeding
3909 int
3910 guestfs_btrfstune_seeding (guestfs_h *g,
3911 const char *device,
3912 int seeding);
3913 Enable seeding of a btrfs device, this will force a fs readonly so that
3915 you can use it to build other filesystems.
3916 This function returns 0 on success or -1 on error.
3918 This function depends on the feature "btrfs". See also
3920 "guestfs_feature_available".
3921 (Added in 1.29.29)
3923 guestfs_c_pointer
3925 int64_t
3926 guestfs_c_pointer (guestfs_h *g);
3927 In non-C language bindings, this allows you to retrieve the underlying
3929 C pointer to the handle (ie. "guestfs_h *"). The purpose of this is to
3930 allow other libraries to interwork with libguestfs.
3931 On error this function returns -1.
3933 (Added in 1.29.17)
3935 guestfs_canonical_device_name
3937 char *
3938 guestfs_canonical_device_name (guestfs_h *g,
3939 const char *device);
3940 This utility function is useful when displaying device names to the
3942 user. It takes a number of irregular device names and returns them in
3943 a consistent format:
3944 /dev/hdX
3946 /dev/vdX
3947 These are returned as /dev/sdX. Note this works for device names
3948 and partition names. This is approximately the reverse of the
3949 algorithm described in "BLOCK DEVICE NAMING".
3950 /dev/mapper/VG-LV
3952 /dev/dm-N
3953 Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
3954 Other strings are returned unmodified.
3956 This function returns a string, or NULL on error. The caller must free
3958 the returned string after use.
3959 (Added in 1.19.7)
3961 guestfs_cap_get_file
3963 char *
3964 guestfs_cap_get_file (guestfs_h *g,
3965 const char *path);
3966 This function returns the Linux capabilities attached to "path". The
3968 capabilities set is returned in text form (see cap_to_text(3)).
3969 If no capabilities are attached to a file, an empty string is returned.
3971 This function returns a string, or NULL on error. The caller must free
3973 the returned string after use.
3974 This function depends on the feature "linuxcaps". See also
3976 "guestfs_feature_available".
3977 (Added in 1.19.63)
3979 guestfs_cap_set_file
3981 int
3982 guestfs_cap_set_file (guestfs_h *g,
3983 const char *path,
3984 const char *cap);
3985 This function sets the Linux capabilities attached to "path". The
3987 capabilities set "cap" should be passed in text form (see
3988 cap_from_text(3)).
3989 This function returns 0 on success or -1 on error.
3991 This function depends on the feature "linuxcaps". See also
3993 "guestfs_feature_available".
3994 (Added in 1.19.63)
3996 guestfs_case_sensitive_path
3998 char *
3999 guestfs_case_sensitive_path (guestfs_h *g,
4000 const char *path);
4001 This can be used to resolve case insensitive paths on a filesystem
4003 which is case sensitive. The use case is to resolve paths which you
4004 have read from Windows configuration files or the Windows Registry, to
4005 the true path.
4006 The command handles a peculiarity of the Linux ntfs-3g filesystem
4008 driver (and probably others), which is that although the underlying
4009 filesystem is case-insensitive, the driver exports the filesystem to
4010 Linux as case-sensitive.
4011 One consequence of this is that special directories such as C:\windows
4013 may appear as /WINDOWS or /windows (or other things) depending on the
4014 precise details of how they were created. In Windows itself this would
4015 not be a problem.
4016 Bug or feature? You decide:
4018 https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4019 "guestfs_case_sensitive_path" attempts to resolve the true case of each
4021 element in the path. It will return a resolved path if either the full
4022 path or its parent directory exists. If the parent directory exists but
4023 the full path does not, the case of the parent directory will be
4024 correctly resolved, and the remainder appended unmodified. For example,
4025 if the file "/Windows/System32/netkvm.sys" exists:
4026 "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4028 "Windows/System32/netkvm.sys"
4029 "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4031 "Windows/System32/NoSuchFile"
4032 "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4034 ERROR
4035 Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4037 cannot be used to check for the existence of a file.
4038 Note: This function does not handle drive names, backslashes etc.
4040 See also "guestfs_realpath".
4042 This function returns a string, or NULL on error. The caller must free
4044 the returned string after use.
4045 (Added in 1.0.75)
4047 guestfs_cat
4049 char *
4050 guestfs_cat (guestfs_h *g,
4051 const char *path);
4052 Return the contents of the file named "path".
4054 Because, in C, this function returns a "char *", there is no way to
4056 differentiate between a "\0" character in a file and end of string. To
4057 handle binary files, use the "guestfs_read_file" or "guestfs_download"
4058 functions.
4059 This function returns a string, or NULL on error. The caller must free
4061 the returned string after use.
4062 (Added in 0.4)
4064 guestfs_checksum
4066 char *
4067 guestfs_checksum (guestfs_h *g,
4068 const char *csumtype,
4069 const char *path);
4070 This call computes the MD5, SHAx or CRC checksum of the file named
4072 "path".
4073 The type of checksum to compute is given by the "csumtype" parameter
4075 which must have one of the following values:
4076 "crc"
4078 Compute the cyclic redundancy check (CRC) specified by POSIX for
4079 the "cksum" command.
4080 "md5"
4082 Compute the MD5 hash (using the md5sum(1) program).
4083 "sha1"
4085 Compute the SHA1 hash (using the sha1sum(1) program).
4086 "sha224"
4088 Compute the SHA224 hash (using the sha224sum(1) program).
4089 "sha256"
4091 Compute the SHA256 hash (using the sha256sum(1) program).
4092 "sha384"
4094 Compute the SHA384 hash (using the sha384sum(1) program).
4095 "sha512"
4097 Compute the SHA512 hash (using the sha512sum(1) program).
4098 The checksum is returned as a printable string.
4100 To get the checksum for a device, use "guestfs_checksum_device".
4102 To get the checksums for many files, use "guestfs_checksums_out".
4104 This function returns a string, or NULL on error. The caller must free
4106 the returned string after use.
4107 (Added in 1.0.2)
4109 guestfs_checksum_device
4111 char *
4112 guestfs_checksum_device (guestfs_h *g,
4113 const char *csumtype,
4114 const char *device);
4115 This call computes the MD5, SHAx or CRC checksum of the contents of the
4117 device named "device". For the types of checksums supported see the
4118 "guestfs_checksum" command.
4119 This function returns a string, or NULL on error. The caller must free
4121 the returned string after use.
4122 (Added in 1.3.2)
4124 guestfs_checksums_out
4126 int
4127 guestfs_checksums_out (guestfs_h *g,
4128 const char *csumtype,
4129 const char *directory,
4130 const char *sumsfile);
4131 This command computes the checksums of all regular files in directory
4133 and then emits a list of those checksums to the local output file
4134 "sumsfile".
4135 This can be used for verifying the integrity of a virtual machine.
4137 However to be properly secure you should pay attention to the output of
4138 the checksum command (it uses the ones from GNU coreutils). In
4139 particular when the filename is not printable, coreutils uses a special
4140 backslash syntax. For more information, see the GNU coreutils info
4141 file.
4142 This function returns 0 on success or -1 on error.
4144 (Added in 1.3.7)
4146 guestfs_chmod
4148 int
4149 guestfs_chmod (guestfs_h *g,
4150 int mode,
4151 const char *path);
4152 Change the mode (permissions) of "path" to "mode". Only numeric modes
4154 are supported.
4155 Note: When using this command from guestfish, "mode" by default would
4157 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4158 700.
4159 The mode actually set is affected by the umask.
4161 This function returns 0 on success or -1 on error.
4163 (Added in 0.8)
4165 guestfs_chown
4167 int
4168 guestfs_chown (guestfs_h *g,
4169 int owner,
4170 int group,
4171 const char *path);
4172 Change the file owner to "owner" and group to "group".
4174 Only numeric uid and gid are supported. If you want to use names, you
4176 will need to locate and parse the password file yourself (Augeas
4177 support makes this relatively easy).
4178 This function returns 0 on success or -1 on error.
4180 (Added in 0.8)
4182 guestfs_clear_backend_setting
4184 int
4185 guestfs_clear_backend_setting (guestfs_h *g,
4186 const char *name);
4187 If there is a backend setting string matching "name" or beginning with
4189 "name=", then that string is removed from the backend settings.
4190 This call returns the number of strings which were removed (which may
4192 be 0, 1 or greater than 1).
4193 See "BACKEND", "BACKEND SETTINGS".
4195 On error this function returns -1.
4197 (Added in 1.27.2)
4199 guestfs_clevis_luks_unlock
4201 int
4202 guestfs_clevis_luks_unlock (guestfs_h *g,
4203 const char *device,
4204 const char *mapname);
4205 This command opens a block device that has been encrypted according to
4207 the Linux Unified Key Setup (LUKS) standard, using network-bound disk
4208 encryption (NBDE).
4209 "device" is the encrypted block device.
4211 The appliance will connect to the Tang servers noted in the tree of
4213 Clevis pins that is bound to a keyslot of the LUKS header. The Clevis
4214 pin tree may comprise "sss" (redudancy) pins as internal nodes
4215 (optionally), and "tang" pins as leaves. "tpm2" pins are not
4216 supported. The appliance unlocks the encrypted block device by
4217 combining responses from the Tang servers with metadata from the LUKS
4218 header; there is no "key" parameter.
4219 This command will fail if networking has not been enabled for the
4221 appliance. Refer to "guestfs_set_network".
4222 The command creates a new block device called /dev/mapper/mapname.
4224 Reads and writes to this block device are decrypted from and encrypted
4225 to the underlying "device" respectively. Close the decrypted block
4226 device with "guestfs_cryptsetup_close".
4227 "mapname" cannot be "control" because that name is reserved by device-
4229 mapper.
4230 If this block device contains LVM volume groups, then calling
4232 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
4233 visible.
4234 Use "guestfs_list_dm_devices" to list all device mapper devices.
4236 This function returns 0 on success or -1 on error.
4238 This function depends on the feature "clevisluks". See also
4240 "guestfs_feature_available".
4241 (Added in 1.49.3)
4243 guestfs_command
4245 char *
4246 guestfs_command (guestfs_h *g,
4247 char *const *arguments);
4248 This call runs a command from the guest filesystem. The filesystem
4250 must be mounted, and must contain a compatible operating system (ie.
4251 something Linux, with the same or compatible processor architecture).
4252 The single parameter is an argv-style list of arguments. The first
4254 element is the name of the program to run. Subsequent elements are
4255 parameters. The list must be non-empty (ie. must contain a program
4256 name). Note that the command runs directly, and is not invoked via the
4257 shell (see "guestfs_sh").
4258 The return value is anything printed to stdout by the command.
4260 If the command returns a non-zero exit status, then this function
4262 returns an error message. The error message string is the content of
4263 stderr from the command.
4264 The $PATH environment variable will contain at least /usr/bin and /bin.
4266 If you require a program from another location, you should provide the
4267 full path in the first parameter.
4268 Shared libraries and data files required by the program must be
4270 available on filesystems which are mounted in the correct places. It
4271 is the caller’s responsibility to ensure all filesystems that are
4272 needed are mounted at the right locations.
4273 This function returns a string, or NULL on error. The caller must free
4275 the returned string after use.
4276 Because of the message protocol, there is a transfer limit of somewhere
4278 between 2MB and 4MB. See "PROTOCOL LIMITS".
4279 (Added in 1.9.1)
4281 guestfs_command_lines
4283 char **
4284 guestfs_command_lines (guestfs_h *g,
4285 char *const *arguments);
4286 This is the same as "guestfs_command", but splits the result into a
4288 list of lines.
4289 See also: "guestfs_sh_lines"
4291 This function returns a NULL-terminated array of strings (like
4293 environ(3)), or NULL if there was an error. The caller must free the
4294 strings and the array after use.
4295 Because of the message protocol, there is a transfer limit of somewhere
4297 between 2MB and 4MB. See "PROTOCOL LIMITS".
4298 (Added in 1.9.1)
4300 guestfs_compress_device_out
4302 int
4303 guestfs_compress_device_out (guestfs_h *g,
4304 const char *ctype,
4305 const char *device,
4306 const char *zdevice,
4307 ...);
4308 You may supply a list of optional arguments to this call. Use zero or
4310 more of the following pairs of parameters, and terminate the list with
4311 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4312 GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4314 This command compresses "device" and writes it out to the local file
4316 "zdevice".
4317 The "ctype" and optional "level" parameters have the same meaning as in
4319 "guestfs_compress_out".
4320 This function returns 0 on success or -1 on error.
4322 (Added in 1.13.15)
4324 guestfs_compress_device_out_va
4326 int
4327 guestfs_compress_device_out_va (guestfs_h *g,
4328 const char *ctype,
4329 const char *device,
4330 const char *zdevice,
4331 va_list args);
4332 This is the "va_list variant" of "guestfs_compress_device_out".
4334 See "CALLS WITH OPTIONAL ARGUMENTS".
4336 guestfs_compress_device_out_argv
4338 int
4339 guestfs_compress_device_out_argv (guestfs_h *g,
4340 const char *ctype,
4341 const char *device,
4342 const char *zdevice,
4343 const struct guestfs_compress_device_out_argv *optargs);
4344 This is the "argv variant" of "guestfs_compress_device_out".
4346 See "CALLS WITH OPTIONAL ARGUMENTS".
4348 guestfs_compress_out
4350 int
4351 guestfs_compress_out (guestfs_h *g,
4352 const char *ctype,
4353 const char *file,
4354 const char *zfile,
4355 ...);
4356 You may supply a list of optional arguments to this call. Use zero or
4358 more of the following pairs of parameters, and terminate the list with
4359 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4360 GUESTFS_COMPRESS_OUT_LEVEL, int level,
4362 This command compresses file and writes it out to the local file zfile.
4364 The compression program used is controlled by the "ctype" parameter.
4366 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4367 Some compression types may not be supported by particular builds of
4368 libguestfs, in which case you will get an error containing the
4369 substring "not supported".
4370 The optional "level" parameter controls compression level. The meaning
4372 and default for this parameter depends on the compression program being
4373 used.
4374 This function returns 0 on success or -1 on error.
4376 (Added in 1.13.15)
4378 guestfs_compress_out_va
4380 int
4381 guestfs_compress_out_va (guestfs_h *g,
4382 const char *ctype,
4383 const char *file,
4384 const char *zfile,
4385 va_list args);
4386 This is the "va_list variant" of "guestfs_compress_out".
4388 See "CALLS WITH OPTIONAL ARGUMENTS".
4390 guestfs_compress_out_argv
4392 int
4393 guestfs_compress_out_argv (guestfs_h *g,
4394 const char *ctype,
4395 const char *file,
4396 const char *zfile,
4397 const struct guestfs_compress_out_argv *optargs);
4398 This is the "argv variant" of "guestfs_compress_out".
4400 See "CALLS WITH OPTIONAL ARGUMENTS".
4402 guestfs_config
4404 int
4405 guestfs_config (guestfs_h *g,
4406 const char *hvparam,
4407 const char *hvvalue);
4408 This can be used to add arbitrary hypervisor parameters of the form
4410 -param value. Actually it’s not quite arbitrary - we prevent you from
4411 setting some parameters which would interfere with parameters that we
4412 use.
4413 The first character of "hvparam" string must be a "-" (dash).
4415 "hvvalue" can be NULL.
4417 This function returns 0 on success or -1 on error.
4419 (Added in 0.3)
4421 guestfs_copy_attributes
4423 int
4424 guestfs_copy_attributes (guestfs_h *g,
4425 const char *src,
4426 const char *dest,
4427 ...);
4428 You may supply a list of optional arguments to this call. Use zero or
4430 more of the following pairs of parameters, and terminate the list with
4431 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4432 GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4434 GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4435 GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4436 GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4437 Copy the attributes of a path (which can be a file or a directory) to
4439 another path.
4440 By default no attribute is copied, so make sure to specify any (or
4442 "all" to copy everything).
4443 The optional arguments specify which attributes can be copied:
4445 "mode"
4447 Copy part of the file mode from "source" to "destination". Only the
4448 UNIX permissions and the sticky/setuid/setgid bits can be copied.
4449 "xattributes"
4451 Copy the Linux extended attributes (xattrs) from "source" to
4452 "destination". This flag does nothing if the linuxxattrs feature
4453 is not available (see "guestfs_feature_available").
4454 "ownership"
4456 Copy the owner uid and the group gid of "source" to "destination".
4457 "all"
4459 Copy all the attributes from "source" to "destination". Enabling it
4460 enables all the other flags, if they are not specified already.
4461 This function returns 0 on success or -1 on error.
4463 (Added in 1.25.21)
4465 guestfs_copy_attributes_va
4467 int
4468 guestfs_copy_attributes_va (guestfs_h *g,
4469 const char *src,
4470 const char *dest,
4471 va_list args);
4472 This is the "va_list variant" of "guestfs_copy_attributes".
4474 See "CALLS WITH OPTIONAL ARGUMENTS".
4476 guestfs_copy_attributes_argv
4478 int
4479 guestfs_copy_attributes_argv (guestfs_h *g,
4480 const char *src,
4481 const char *dest,
4482 const struct guestfs_copy_attributes_argv *optargs);
4483 This is the "argv variant" of "guestfs_copy_attributes".
4485 See "CALLS WITH OPTIONAL ARGUMENTS".
4487 guestfs_copy_device_to_device
4489 int
4490 guestfs_copy_device_to_device (guestfs_h *g,
4491 const char *src,
4492 const char *dest,
4493 ...);
4494 You may supply a list of optional arguments to this call. Use zero or
4496 more of the following pairs of parameters, and terminate the list with
4497 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4498 GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4500 GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4501 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4502 GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4503 GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4504 The four calls "guestfs_copy_device_to_device",
4506 "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4507 "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4508 a destination (device|file).
4509 Partial copies can be made since you can specify optionally the source
4511 offset, destination offset and size to copy. These values are all
4512 specified in bytes. If not given, the offsets both default to zero,
4513 and the size defaults to copying as much as possible until we hit the
4514 end of the source.
4515 The source and destination may be the same object. However overlapping
4517 regions may not be copied correctly.
4518 If the destination is a file, it is created if required. If the
4520 destination file is not large enough, it is extended.
4521 If the destination is a file and the "append" flag is not set, then the
4523 destination file is truncated. If the "append" flag is set, then the
4524 copy appends to the destination file. The "append" flag currently
4525 cannot be set for devices.
4526 If the "sparse" flag is true then the call avoids writing blocks that
4528 contain only zeroes, which can help in some situations where the
4529 backing disk is thin-provisioned. Note that unless the target is
4530 already zeroed, using this option will result in incorrect copying.
4531 This function returns 0 on success or -1 on error.
4533 This long-running command can generate progress notification messages
4535 so that the caller can display a progress bar or indicator. To receive
4536 these messages, the caller must register a progress event callback.
4537 See "GUESTFS_EVENT_PROGRESS".
4538 (Added in 1.13.25)
4540 guestfs_copy_device_to_device_va
4542 int
4543 guestfs_copy_device_to_device_va (guestfs_h *g,
4544 const char *src,
4545 const char *dest,
4546 va_list args);
4547 This is the "va_list variant" of "guestfs_copy_device_to_device".
4549 See "CALLS WITH OPTIONAL ARGUMENTS".
4551 guestfs_copy_device_to_device_argv
4553 int
4554 guestfs_copy_device_to_device_argv (guestfs_h *g,
4555 const char *src,
4556 const char *dest,
4557 const struct guestfs_copy_device_to_device_argv *optargs);
4558 This is the "argv variant" of "guestfs_copy_device_to_device".
4560 See "CALLS WITH OPTIONAL ARGUMENTS".
4562 guestfs_copy_device_to_file
4564 int
4565 guestfs_copy_device_to_file (guestfs_h *g,
4566 const char *src,
4567 const char *dest,
4568 ...);
4569 You may supply a list of optional arguments to this call. Use zero or
4571 more of the following pairs of parameters, and terminate the list with
4572 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4573 GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4575 GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4576 GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4577 GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4578 GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4579 See "guestfs_copy_device_to_device" for a general overview of this
4581 call.
4582 This function returns 0 on success or -1 on error.
4584 This long-running command can generate progress notification messages
4586 so that the caller can display a progress bar or indicator. To receive
4587 these messages, the caller must register a progress event callback.
4588 See "GUESTFS_EVENT_PROGRESS".
4589 (Added in 1.13.25)
4591 guestfs_copy_device_to_file_va
4593 int
4594 guestfs_copy_device_to_file_va (guestfs_h *g,
4595 const char *src,
4596 const char *dest,
4597 va_list args);
4598 This is the "va_list variant" of "guestfs_copy_device_to_file".
4600 See "CALLS WITH OPTIONAL ARGUMENTS".
4602 guestfs_copy_device_to_file_argv
4604 int
4605 guestfs_copy_device_to_file_argv (guestfs_h *g,
4606 const char *src,
4607 const char *dest,
4608 const struct guestfs_copy_device_to_file_argv *optargs);
4609 This is the "argv variant" of "guestfs_copy_device_to_file".
4611 See "CALLS WITH OPTIONAL ARGUMENTS".
4613 guestfs_copy_file_to_device
4615 int
4616 guestfs_copy_file_to_device (guestfs_h *g,
4617 const char *src,
4618 const char *dest,
4619 ...);
4620 You may supply a list of optional arguments to this call. Use zero or
4622 more of the following pairs of parameters, and terminate the list with
4623 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4624 GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4626 GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4627 GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4628 GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4629 GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4630 See "guestfs_copy_device_to_device" for a general overview of this
4632 call.
4633 This function returns 0 on success or -1 on error.
4635 This long-running command can generate progress notification messages
4637 so that the caller can display a progress bar or indicator. To receive
4638 these messages, the caller must register a progress event callback.
4639 See "GUESTFS_EVENT_PROGRESS".
4640 (Added in 1.13.25)
4642 guestfs_copy_file_to_device_va
4644 int
4645 guestfs_copy_file_to_device_va (guestfs_h *g,
4646 const char *src,
4647 const char *dest,
4648 va_list args);
4649 This is the "va_list variant" of "guestfs_copy_file_to_device".
4651 See "CALLS WITH OPTIONAL ARGUMENTS".
4653 guestfs_copy_file_to_device_argv
4655 int
4656 guestfs_copy_file_to_device_argv (guestfs_h *g,
4657 const char *src,
4658 const char *dest,
4659 const struct guestfs_copy_file_to_device_argv *optargs);
4660 This is the "argv variant" of "guestfs_copy_file_to_device".
4662 See "CALLS WITH OPTIONAL ARGUMENTS".
4664 guestfs_copy_file_to_file
4666 int
4667 guestfs_copy_file_to_file (guestfs_h *g,
4668 const char *src,
4669 const char *dest,
4670 ...);
4671 You may supply a list of optional arguments to this call. Use zero or
4673 more of the following pairs of parameters, and terminate the list with
4674 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4675 GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4677 GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4678 GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4679 GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4680 GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4681 See "guestfs_copy_device_to_device" for a general overview of this
4683 call.
4684 This is not the function you want for copying files. This is for
4686 copying blocks within existing files. See "guestfs_cp", "guestfs_cp_a"
4687 and "guestfs_mv" for general file copying and moving functions.
4688 This function returns 0 on success or -1 on error.
4690 This long-running command can generate progress notification messages
4692 so that the caller can display a progress bar or indicator. To receive
4693 these messages, the caller must register a progress event callback.
4694 See "GUESTFS_EVENT_PROGRESS".
4695 (Added in 1.13.25)
4697 guestfs_copy_file_to_file_va
4699 int
4700 guestfs_copy_file_to_file_va (guestfs_h *g,
4701 const char *src,
4702 const char *dest,
4703 va_list args);
4704 This is the "va_list variant" of "guestfs_copy_file_to_file".
4706 See "CALLS WITH OPTIONAL ARGUMENTS".
4708 guestfs_copy_file_to_file_argv
4710 int
4711 guestfs_copy_file_to_file_argv (guestfs_h *g,
4712 const char *src,
4713 const char *dest,
4714 const struct guestfs_copy_file_to_file_argv *optargs);
4715 This is the "argv variant" of "guestfs_copy_file_to_file".
4717 See "CALLS WITH OPTIONAL ARGUMENTS".
4719 guestfs_copy_in
4721 int
4722 guestfs_copy_in (guestfs_h *g,
4723 const char *localpath,
4724 const char *remotedir);
4725 "guestfs_copy_in" copies local files or directories recursively into
4727 the disk image, placing them in the directory called "remotedir" (which
4728 must exist).
4729 Wildcards cannot be used.
4731 This function returns 0 on success or -1 on error.
4733 (Added in 1.29.24)
4735 guestfs_copy_out
4737 int
4738 guestfs_copy_out (guestfs_h *g,
4739 const char *remotepath,
4740 const char *localdir);
4741 "guestfs_copy_out" copies remote files or directories recursively out
4743 of the disk image, placing them on the host disk in a local directory
4744 called "localdir" (which must exist).
4745 To download to the current directory, use "." as in:
4747 C<guestfs_copy_out> /home .
4749 Wildcards cannot be used.
4751 This function returns 0 on success or -1 on error.
4753 (Added in 1.29.24)
4755 guestfs_copy_size
4757 int
4758 guestfs_copy_size (guestfs_h *g,
4759 const char *src,
4760 const char *dest,
4761 int64_t size);
4762 This function is deprecated. In new code, use the
4764 "guestfs_copy_device_to_device" call instead.
4765 Deprecated functions will not be removed from the API, but the fact
4767 that they are deprecated indicates that there are problems with correct
4768 use of these functions.
4769 This command copies exactly "size" bytes from one source device or file
4771 "src" to another destination device or file "dest".
4772 Note this will fail if the source is too short or if the destination is
4774 not large enough.
4775 This function returns 0 on success or -1 on error.
4777 This long-running command can generate progress notification messages
4779 so that the caller can display a progress bar or indicator. To receive
4780 these messages, the caller must register a progress event callback.
4781 See "GUESTFS_EVENT_PROGRESS".
4782 (Added in 1.0.87)
4784 guestfs_cp
4786 int
4787 guestfs_cp (guestfs_h *g,
4788 const char *src,
4789 const char *dest);
4790 This copies a file from "src" to "dest" where "dest" is either a
4792 destination filename or destination directory.
4793 This function returns 0 on success or -1 on error.
4795 (Added in 1.0.18)
4797 guestfs_cp_a
4799 int
4800 guestfs_cp_a (guestfs_h *g,
4801 const char *src,
4802 const char *dest);
4803 This copies a file or directory from "src" to "dest" recursively using
4805 the "cp -a" command.
4806 This function returns 0 on success or -1 on error.
4808 (Added in 1.0.18)
4810 guestfs_cp_r
4812 int
4813 guestfs_cp_r (guestfs_h *g,
4814 const char *src,
4815 const char *dest);
4816 This copies a file or directory from "src" to "dest" recursively using
4818 the "cp -rP" command.
4819 Most users should use "guestfs_cp_a" instead. This command is useful
4821 when you don't want to preserve permissions, because the target
4822 filesystem does not support it (primarily when writing to DOS FAT
4823 filesystems).
4824 This function returns 0 on success or -1 on error.
4826 (Added in 1.21.38)
4828 guestfs_cpio_out
4830 int
4831 guestfs_cpio_out (guestfs_h *g,
4832 const char *directory,
4833 const char *cpiofile,
4834 ...);
4835 You may supply a list of optional arguments to this call. Use zero or
4837 more of the following pairs of parameters, and terminate the list with
4838 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4839 GUESTFS_CPIO_OUT_FORMAT, const char *format,
4841 This command packs the contents of directory and downloads it to local
4843 file "cpiofile".
4844 The optional "format" parameter can be used to select the format. Only
4846 the following formats are currently permitted:
4847 "newc"
4849 New (SVR4) portable format. This format happens to be compatible
4850 with the cpio-like format used by the Linux kernel for initramfs.
4851 This is the default format.
4853 "crc"
4855 New (SVR4) portable format with a checksum.
4856 This function returns 0 on success or -1 on error.
4858 (Added in 1.27.9)
4860 guestfs_cpio_out_va
4862 int
4863 guestfs_cpio_out_va (guestfs_h *g,
4864 const char *directory,
4865 const char *cpiofile,
4866 va_list args);
4867 This is the "va_list variant" of "guestfs_cpio_out".
4869 See "CALLS WITH OPTIONAL ARGUMENTS".
4871 guestfs_cpio_out_argv
4873 int
4874 guestfs_cpio_out_argv (guestfs_h *g,
4875 const char *directory,
4876 const char *cpiofile,
4877 const struct guestfs_cpio_out_argv *optargs);
4878 This is the "argv variant" of "guestfs_cpio_out".
4880 See "CALLS WITH OPTIONAL ARGUMENTS".
4882 guestfs_cryptsetup_close
4884 int
4885 guestfs_cryptsetup_close (guestfs_h *g,
4886 const char *device);
4887 This closes an encrypted device that was created earlier by
4889 "guestfs_cryptsetup_open". The "device" parameter must be the name of
4890 the mapping device (ie. /dev/mapper/mapname) and not the name of the
4891 underlying block device.
4892 This function returns 0 on success or -1 on error.
4894 This function depends on the feature "luks". See also
4896 "guestfs_feature_available".
4897 (Added in 1.43.2)
4899 guestfs_cryptsetup_open
4901 int
4902 guestfs_cryptsetup_open (guestfs_h *g,
4903 const char *device,
4904 const char *key,
4905 const char *mapname,
4906 ...);
4907 You may supply a list of optional arguments to this call. Use zero or
4909 more of the following pairs of parameters, and terminate the list with
4910 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4911 GUESTFS_CRYPTSETUP_OPEN_READONLY, int readonly,
4913 GUESTFS_CRYPTSETUP_OPEN_CRYPTTYPE, const char *crypttype,
4914 This command opens a block device which has been encrypted according to
4916 the Linux Unified Key Setup (LUKS) standard, Windows BitLocker, or some
4917 other types.
4918 "device" is the encrypted block device or partition.
4920 The caller must supply one of the keys associated with the encrypted
4922 block device, in the "key" parameter.
4923 This creates a new block device called /dev/mapper/mapname. Reads and
4925 writes to this block device are decrypted from and encrypted to the
4926 underlying "device" respectively.
4927 "mapname" cannot be "control" because that name is reserved by device-
4929 mapper.
4930 If the optional "crypttype" parameter is not present then libguestfs
4932 tries to guess the correct type (for example LUKS or BitLocker).
4933 However you can override this by specifying one of the following types:
4934 "luks"
4936 A Linux LUKS device.
4937 "bitlk"
4939 A Windows BitLocker device.
4940 The optional "readonly" flag, if set to true, creates a read-only
4942 mapping.
4943 If this block device contains LVM volume groups, then calling
4945 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
4946 visible.
4947 Use "guestfs_list_dm_devices" to list all device mapper devices.
4949 This function returns 0 on success or -1 on error.
4951 This function takes a key or passphrase parameter which could contain
4953 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
4954 information.
4955 This function depends on the feature "luks". See also
4957 "guestfs_feature_available".
4958 (Added in 1.43.2)
4960 guestfs_cryptsetup_open_va
4962 int
4963 guestfs_cryptsetup_open_va (guestfs_h *g,
4964 const char *device,
4965 const char *key,
4966 const char *mapname,
4967 va_list args);
4968 This is the "va_list variant" of "guestfs_cryptsetup_open".
4970 See "CALLS WITH OPTIONAL ARGUMENTS".
4972 guestfs_cryptsetup_open_argv
4974 int
4975 guestfs_cryptsetup_open_argv (guestfs_h *g,
4976 const char *device,
4977 const char *key,
4978 const char *mapname,
4979 const struct guestfs_cryptsetup_open_argv *optargs);
4980 This is the "argv variant" of "guestfs_cryptsetup_open".
4982 See "CALLS WITH OPTIONAL ARGUMENTS".
4984 guestfs_dd
4986 int
4987 guestfs_dd (guestfs_h *g,
4988 const char *src,
4989 const char *dest);
4990 This function is deprecated. In new code, use the
4992 "guestfs_copy_device_to_device" call instead.
4993 Deprecated functions will not be removed from the API, but the fact
4995 that they are deprecated indicates that there are problems with correct
4996 use of these functions.
4997 This command copies from one source device or file "src" to another
4999 destination device or file "dest". Normally you would use this to copy
5000 to or from a device or partition, for example to duplicate a
5001 filesystem.
5002 If the destination is a device, it must be as large or larger than the
5004 source file or device, otherwise the copy will fail. This command
5005 cannot do partial copies (see "guestfs_copy_device_to_device").
5006 This function returns 0 on success or -1 on error.
5008 (Added in 1.0.80)
5010 guestfs_device_index
5012 int
5013 guestfs_device_index (guestfs_h *g,
5014 const char *device);
5015 This function takes a device name (eg. "/dev/sdb") and returns the
5017 index of the device in the list of devices.
5018 Index numbers start from 0. The named device must exist, for example
5020 as a string returned from "guestfs_list_devices".
5021 See also "guestfs_list_devices", "guestfs_part_to_dev",
5023 "guestfs_device_name".
5024 On error this function returns -1.
5026 (Added in 1.19.7)
5028 guestfs_device_name
5030 char *
5031 guestfs_device_name (guestfs_h *g,
5032 int index);
5033 This function takes a device index and returns the device name. For
5035 example index 0 will return the string "/dev/sda".
5036 The drive index must have been added to the handle.
5038 See also "guestfs_list_devices", "guestfs_part_to_dev",
5040 "guestfs_device_index".
5041 This function returns a string, or NULL on error. The caller must free
5043 the returned string after use.
5044 (Added in 1.49.1)
5046 guestfs_df
5048 char *
5049 guestfs_df (guestfs_h *g);
5050 This command runs the df(1) command to report disk space used.
5052 This command is mostly useful for interactive sessions. It is not
5054 intended that you try to parse the output string. Use
5055 "guestfs_statvfs" from programs.
5056 This function returns a string, or NULL on error. The caller must free
5058 the returned string after use.
5059 (Added in 1.0.54)
5061 guestfs_df_h
5063 char *
5064 guestfs_df_h (guestfs_h *g);
5065 This command runs the "df -h" command to report disk space used in
5067 human-readable format.
5068 This command is mostly useful for interactive sessions. It is not
5070 intended that you try to parse the output string. Use
5071 "guestfs_statvfs" from programs.
5072 This function returns a string, or NULL on error. The caller must free
5074 the returned string after use.
5075 (Added in 1.0.54)
5077 guestfs_disk_create
5079 int
5080 guestfs_disk_create (guestfs_h *g,
5081 const char *filename,
5082 const char *format,
5083 int64_t size,
5084 ...);
5085 You may supply a list of optional arguments to this call. Use zero or
5087 more of the following pairs of parameters, and terminate the list with
5088 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5089 GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
5091 GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
5092 GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
5093 GUESTFS_DISK_CREATE_COMPAT, const char *compat,
5094 GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
5095 Create a blank disk image called filename (a host file) with format
5097 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
5098 If used with the optional "backingfile" parameter, then a snapshot is
5100 created on top of the backing file. In this case, "size" must be
5101 passed as -1. The size of the snapshot is the same as the size of the
5102 backing file, which is discovered automatically. You are encouraged to
5103 also pass "backingformat" to describe the format of "backingfile".
5104 If filename refers to a block device, then the device is formatted.
5106 The "size" is ignored since block devices have an intrinsic size.
5107 The other optional parameters are:
5109 "preallocation"
5111 If format is "raw", then this can be either "off" (or "sparse") or
5112 "full" to create a sparse or fully allocated file respectively.
5113 The default is "off".
5114 If format is "qcow2", then this can be "off" (or "sparse"),
5116 "metadata" or "full". Preallocating metadata can be faster when
5117 doing lots of writes, but uses more space. The default is "off".
5118 "compat"
5120 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5121 supported by qemu ≥ 1.1.
5122 "clustersize"
5124 "qcow2" only: Change the qcow2 cluster size. The default is 65536
5125 (bytes) and this setting may be any power of two between 512 and
5126 2097152.
5127 Note that this call does not add the new disk to the handle. You may
5129 need to call "guestfs_add_drive_opts" separately.
5130 This function returns 0 on success or -1 on error.
5132 (Added in 1.25.31)
5134 guestfs_disk_create_va
5136 int
5137 guestfs_disk_create_va (guestfs_h *g,
5138 const char *filename,
5139 const char *format,
5140 int64_t size,
5141 va_list args);
5142 This is the "va_list variant" of "guestfs_disk_create".
5144 See "CALLS WITH OPTIONAL ARGUMENTS".
5146 guestfs_disk_create_argv
5148 int
5149 guestfs_disk_create_argv (guestfs_h *g,
5150 const char *filename,
5151 const char *format,
5152 int64_t size,
5153 const struct guestfs_disk_create_argv *optargs);
5154 This is the "argv variant" of "guestfs_disk_create".
5156 See "CALLS WITH OPTIONAL ARGUMENTS".
5158 guestfs_disk_format
5160 char *
5161 guestfs_disk_format (guestfs_h *g,
5162 const char *filename);
5163 Detect and return the format of the disk image called filename.
5165 filename can also be a host device, etc. If the format of the image
5166 could not be detected, then "unknown" is returned.
5167 Note that detecting the disk format can be insecure under some
5169 circumstances. See "CVE-2010-3851".
5170 See also: "DISK IMAGE FORMATS"
5172 This function returns a string, or NULL on error. The caller must free
5174 the returned string after use.
5175 (Added in 1.19.38)
5177 guestfs_disk_has_backing_file
5179 int
5180 guestfs_disk_has_backing_file (guestfs_h *g,
5181 const char *filename);
5182 Detect and return whether the disk image filename has a backing file.
5184 Note that detecting disk features can be insecure under some
5186 circumstances. See "CVE-2010-3851".
5187 This function returns a C truth value on success or -1 on error.
5189 (Added in 1.19.39)
5191 guestfs_disk_virtual_size
5193 int64_t
5194 guestfs_disk_virtual_size (guestfs_h *g,
5195 const char *filename);
5196 Detect and return the virtual size in bytes of the disk image called
5198 filename.
5199 Note that detecting disk features can be insecure under some
5201 circumstances. See "CVE-2010-3851".
5202 On error this function returns -1.
5204 (Added in 1.19.39)
5206 guestfs_dmesg
5208 char *
5209 guestfs_dmesg (guestfs_h *g);
5210 This returns the kernel messages (dmesg(1) output) from the guest
5212 kernel. This is sometimes useful for extended debugging of problems.
5213 Another way to get the same information is to enable verbose messages
5215 with "guestfs_set_verbose" or by setting the environment variable
5216 "LIBGUESTFS_DEBUG=1" before running the program.
5217 This function returns a string, or NULL on error. The caller must free
5219 the returned string after use.
5220 (Added in 1.0.18)
5222 guestfs_download
5224 int
5225 guestfs_download (guestfs_h *g,
5226 const char *remotefilename,
5227 const char *filename);
5228 Download file remotefilename and save it as filename on the local
5230 machine.
5231 filename can also be a named pipe.
5233 See also "guestfs_upload", "guestfs_cat".
5235 This function returns 0 on success or -1 on error.
5237 This long-running command can generate progress notification messages
5239 so that the caller can display a progress bar or indicator. To receive
5240 these messages, the caller must register a progress event callback.
5241 See "GUESTFS_EVENT_PROGRESS".
5242 (Added in 1.0.2)
5244 guestfs_download_blocks
5246 int
5247 guestfs_download_blocks (guestfs_h *g,
5248 const char *device,
5249 int64_t start,
5250 int64_t stop,
5251 const char *filename,
5252 ...);
5253 You may supply a list of optional arguments to this call. Use zero or
5255 more of the following pairs of parameters, and terminate the list with
5256 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5257 GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5259 Download the data units from start address to stop from the disk
5261 partition (eg. /dev/sda1) and save them as filename on the local
5262 machine.
5263 The use of this API on sparse disk image formats such as QCOW, may
5265 result in large zero-filled files downloaded on the host.
5266 The size of a data unit varies across filesystem implementations. On
5268 NTFS filesystems data units are referred as clusters while on ExtX ones
5269 they are referred as fragments.
5270 If the optional "unallocated" flag is true (default is false), only the
5272 unallocated blocks will be extracted. This is useful to detect hidden
5273 data or to retrieve deleted files which data units have not been
5274 overwritten yet.
5275 This function returns 0 on success or -1 on error.
5277 This long-running command can generate progress notification messages
5279 so that the caller can display a progress bar or indicator. To receive
5280 these messages, the caller must register a progress event callback.
5281 See "GUESTFS_EVENT_PROGRESS".
5282 This function depends on the feature "sleuthkit". See also
5284 "guestfs_feature_available".
5285 (Added in 1.33.45)
5287 guestfs_download_blocks_va
5289 int
5290 guestfs_download_blocks_va (guestfs_h *g,
5291 const char *device,
5292 int64_t start,
5293 int64_t stop,
5294 const char *filename,
5295 va_list args);
5296 This is the "va_list variant" of "guestfs_download_blocks".
5298 See "CALLS WITH OPTIONAL ARGUMENTS".
5300 guestfs_download_blocks_argv
5302 int
5303 guestfs_download_blocks_argv (guestfs_h *g,
5304 const char *device,
5305 int64_t start,
5306 int64_t stop,
5307 const char *filename,
5308 const struct guestfs_download_blocks_argv *optargs);
5309 This is the "argv variant" of "guestfs_download_blocks".
5311 See "CALLS WITH OPTIONAL ARGUMENTS".
5313 guestfs_download_inode
5315 int
5316 guestfs_download_inode (guestfs_h *g,
5317 const char *device,
5318 int64_t inode,
5319 const char *filename);
5320 Download a file given its inode from the disk partition (eg. /dev/sda1)
5322 and save it as filename on the local machine.
5323 It is not required to mount the disk to run this command.
5325 The command is capable of downloading deleted or inaccessible files.
5327 This function returns 0 on success or -1 on error.
5329 This long-running command can generate progress notification messages
5331 so that the caller can display a progress bar or indicator. To receive
5332 these messages, the caller must register a progress event callback.
5333 See "GUESTFS_EVENT_PROGRESS".
5334 This function depends on the feature "sleuthkit". See also
5336 "guestfs_feature_available".
5337 (Added in 1.33.14)
5339 guestfs_download_offset
5341 int
5342 guestfs_download_offset (guestfs_h *g,
5343 const char *remotefilename,
5344 const char *filename,
5345 int64_t offset,
5346 int64_t size);
5347 Download file remotefilename and save it as filename on the local
5349 machine.
5350 remotefilename is read for "size" bytes starting at "offset" (this
5352 region must be within the file or device).
5353 Note that there is no limit on the amount of data that can be
5355 downloaded with this call, unlike with "guestfs_pread", and this call
5356 always reads the full amount unless an error occurs.
5357 See also "guestfs_download", "guestfs_pread".
5359 This function returns 0 on success or -1 on error.
5361 This long-running command can generate progress notification messages
5363 so that the caller can display a progress bar or indicator. To receive
5364 these messages, the caller must register a progress event callback.
5365 See "GUESTFS_EVENT_PROGRESS".
5366 (Added in 1.5.17)
5368 guestfs_drop_caches
5370 int
5371 guestfs_drop_caches (guestfs_h *g,
5372 int whattodrop);
5373 This instructs the guest kernel to drop its page cache, and/or dentries
5375 and inode caches. The parameter "whattodrop" tells the kernel what
5376 precisely to drop, see https://linux-mm.org/Drop_Caches
5377 Setting "whattodrop" to 3 should drop everything.
5379 This automatically calls sync(2) before the operation, so that the
5381 maximum guest memory is freed.
5382 This function returns 0 on success or -1 on error.
5384 (Added in 1.0.18)
5386 guestfs_du
5388 int64_t
5389 guestfs_du (guestfs_h *g,
5390 const char *path);
5391 This command runs the "du -s" command to estimate file space usage for
5393 "path".
5394 "path" can be a file or a directory. If "path" is a directory then the
5396 estimate includes the contents of the directory and all subdirectories
5397 (recursively).
5398 The result is the estimated size in kilobytes (ie. units of 1024
5400 bytes).
5401 On error this function returns -1.
5403 This long-running command can generate progress notification messages
5405 so that the caller can display a progress bar or indicator. To receive
5406 these messages, the caller must register a progress event callback.
5407 See "GUESTFS_EVENT_PROGRESS".
5408 (Added in 1.0.54)
5410 guestfs_e2fsck
5412 int
5413 guestfs_e2fsck (guestfs_h *g,
5414 const char *device,
5415 ...);
5416 You may supply a list of optional arguments to this call. Use zero or
5418 more of the following pairs of parameters, and terminate the list with
5419 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5420 GUESTFS_E2FSCK_CORRECT, int correct,
5422 GUESTFS_E2FSCK_FORCEALL, int forceall,
5423 This runs the ext2/ext3 filesystem checker on "device". It can take
5425 the following optional arguments:
5426 "correct"
5428 Automatically repair the file system. This option will cause e2fsck
5429 to automatically fix any filesystem problems that can be safely
5430 fixed without human intervention.
5431 This option may not be specified at the same time as the "forceall"
5433 option.
5434 "forceall"
5436 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5437 used non-interactively.
5438 This option may not be specified at the same time as the "correct"
5440 option.
5441 This function returns 0 on success or -1 on error.
5443 (Added in 1.15.17)
5445 guestfs_e2fsck_va
5447 int
5448 guestfs_e2fsck_va (guestfs_h *g,
5449 const char *device,
5450 va_list args);
5451 This is the "va_list variant" of "guestfs_e2fsck".
5453 See "CALLS WITH OPTIONAL ARGUMENTS".
5455 guestfs_e2fsck_argv
5457 int
5458 guestfs_e2fsck_argv (guestfs_h *g,
5459 const char *device,
5460 const struct guestfs_e2fsck_argv *optargs);
5461 This is the "argv variant" of "guestfs_e2fsck".
5463 See "CALLS WITH OPTIONAL ARGUMENTS".
5465 guestfs_e2fsck_f
5467 int
5468 guestfs_e2fsck_f (guestfs_h *g,
5469 const char *device);
5470 This function is deprecated. In new code, use the "guestfs_e2fsck"
5472 call instead.
5473 Deprecated functions will not be removed from the API, but the fact
5475 that they are deprecated indicates that there are problems with correct
5476 use of these functions.
5477 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5479 checker on "device", noninteractively (-p), even if the filesystem
5480 appears to be clean (-f).
5481 This function returns 0 on success or -1 on error.
5483 (Added in 1.0.29)
5485 guestfs_echo_daemon
5487 char *
5488 guestfs_echo_daemon (guestfs_h *g,
5489 char *const *words);
5490 This command concatenates the list of "words" passed with single spaces
5492 between them and returns the resulting string.
5493 You can use this command to test the connection through to the daemon.
5495 See also "guestfs_ping_daemon".
5497 This function returns a string, or NULL on error. The caller must free
5499 the returned string after use.
5500 (Added in 1.0.69)
5502 guestfs_egrep
5504 char **
5505 guestfs_egrep (guestfs_h *g,
5506 const char *regex,
5507 const char *path);
5508 This function is deprecated. In new code, use the "guestfs_grep" call
5510 instead.
5511 Deprecated functions will not be removed from the API, but the fact
5513 that they are deprecated indicates that there are problems with correct
5514 use of these functions.
5515 This calls the external egrep(1) program and returns the matching
5517 lines.
5518 This function returns a NULL-terminated array of strings (like
5520 environ(3)), or NULL if there was an error. The caller must free the
5521 strings and the array after use.
5522 Because of the message protocol, there is a transfer limit of somewhere
5524 between 2MB and 4MB. See "PROTOCOL LIMITS".
5525 (Added in 1.0.66)
5527 guestfs_egrepi
5529 char **
5530 guestfs_egrepi (guestfs_h *g,
5531 const char *regex,
5532 const char *path);
5533 This function is deprecated. In new code, use the "guestfs_grep" call
5535 instead.
5536 Deprecated functions will not be removed from the API, but the fact
5538 that they are deprecated indicates that there are problems with correct
5539 use of these functions.
5540 This calls the external "egrep -i" program and returns the matching
5542 lines.
5543 This function returns a NULL-terminated array of strings (like
5545 environ(3)), or NULL if there was an error. The caller must free the
5546 strings and the array after use.
5547 Because of the message protocol, there is a transfer limit of somewhere
5549 between 2MB and 4MB. See "PROTOCOL LIMITS".
5550 (Added in 1.0.66)
5552 guestfs_equal
5554 int
5555 guestfs_equal (guestfs_h *g,
5556 const char *file1,
5557 const char *file2);
5558 This compares the two files file1 and file2 and returns true if their
5560 content is exactly equal, or false otherwise.
5561 The external cmp(1) program is used for the comparison.
5563 This function returns a C truth value on success or -1 on error.
5565 (Added in 1.0.18)
5567 guestfs_exists
5569 int
5570 guestfs_exists (guestfs_h *g,
5571 const char *path);
5572 This returns "true" if and only if there is a file, directory (or
5574 anything) with the given "path" name.
5575 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5577 This function returns a C truth value on success or -1 on error.
5579 (Added in 0.8)
5581 guestfs_extlinux
5583 int
5584 guestfs_extlinux (guestfs_h *g,
5585 const char *directory);
5586 Install the SYSLINUX bootloader on the device mounted at directory.
5588 Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5589 used on an ext2/3/4 or btrfs filesystem.
5590 The directory parameter can be either a mountpoint, or a directory
5592 within the mountpoint.
5593 You also have to mark the partition as "active"
5595 ("guestfs_part_set_bootable") and a Master Boot Record must be
5596 installed (eg. using "guestfs_pwrite_device") on the first sector of
5597 the whole disk. The SYSLINUX package comes with some suitable Master
5598 Boot Records. See the extlinux(1) man page for further information.
5599 Additional configuration can be supplied to SYSLINUX by placing a file
5601 called extlinux.conf on the filesystem under directory. For further
5602 information about the contents of this file, see extlinux(1).
5603 See also "guestfs_syslinux".
5605 This function returns 0 on success or -1 on error.
5607 This function depends on the feature "extlinux". See also
5609 "guestfs_feature_available".
5610 (Added in 1.21.27)
5612 guestfs_f2fs_expand
5614 int
5615 guestfs_f2fs_expand (guestfs_h *g,
5616 const char *device);
5617 This expands a f2fs filesystem to match the size of the underlying
5619 device.
5620 This function returns 0 on success or -1 on error.
5622 This function depends on the feature "f2fs". See also
5624 "guestfs_feature_available".
5625 (Added in 1.39.3)
5627 guestfs_fallocate
5629 int
5630 guestfs_fallocate (guestfs_h *g,
5631 const char *path,
5632 int len);
5633 This function is deprecated. In new code, use the
5635 "guestfs_fallocate64" call instead.
5636 Deprecated functions will not be removed from the API, but the fact
5638 that they are deprecated indicates that there are problems with correct
5639 use of these functions.
5640 This command preallocates a file (containing zero bytes) named "path"
5642 of size "len" bytes. If the file exists already, it is overwritten.
5643 Do not confuse this with the guestfish-specific "alloc" command which
5645 allocates a file in the host and attaches it as a device.
5646 This function returns 0 on success or -1 on error.
5648 (Added in 1.0.66)
5650 guestfs_fallocate64
5652 int
5653 guestfs_fallocate64 (guestfs_h *g,
5654 const char *path,
5655 int64_t len);
5656 This command preallocates a file (containing zero bytes) named "path"
5658 of size "len" bytes. If the file exists already, it is overwritten.
5659 Note that this call allocates disk blocks for the file. To create a
5661 sparse file use "guestfs_truncate_size" instead.
5662 The deprecated call "guestfs_fallocate" does the same, but owing to an
5664 oversight it only allowed 30 bit lengths to be specified, effectively
5665 limiting the maximum size of files created through that call to 1GB.
5666 Do not confuse this with the guestfish-specific "alloc" and "sparse"
5668 commands which create a file in the host and attach it as a device.
5669 This function returns 0 on success or -1 on error.
5671 (Added in 1.3.17)
5673 guestfs_feature_available
5675 int
5676 guestfs_feature_available (guestfs_h *g,
5677 char *const *groups);
5678 This is the same as "guestfs_available", but unlike that call it
5680 returns a simple true/false boolean result, instead of throwing an
5681 exception if a feature is not found. For other documentation see
5682 "guestfs_available".
5683 This function returns a C truth value on success or -1 on error.
5685 (Added in 1.21.26)
5687 guestfs_fgrep
5689 char **
5690 guestfs_fgrep (guestfs_h *g,
5691 const char *pattern,
5692 const char *path);
5693 This function is deprecated. In new code, use the "guestfs_grep" call
5695 instead.
5696 Deprecated functions will not be removed from the API, but the fact
5698 that they are deprecated indicates that there are problems with correct
5699 use of these functions.
5700 This calls the external fgrep(1) program and returns the matching
5702 lines.
5703 This function returns a NULL-terminated array of strings (like
5705 environ(3)), or NULL if there was an error. The caller must free the
5706 strings and the array after use.
5707 Because of the message protocol, there is a transfer limit of somewhere
5709 between 2MB and 4MB. See "PROTOCOL LIMITS".
5710 (Added in 1.0.66)
5712 guestfs_fgrepi
5714 char **
5715 guestfs_fgrepi (guestfs_h *g,
5716 const char *pattern,
5717 const char *path);
5718 This function is deprecated. In new code, use the "guestfs_grep" call
5720 instead.
5721 Deprecated functions will not be removed from the API, but the fact
5723 that they are deprecated indicates that there are problems with correct
5724 use of these functions.
5725 This calls the external "fgrep -i" program and returns the matching
5727 lines.
5728 This function returns a NULL-terminated array of strings (like
5730 environ(3)), or NULL if there was an error. The caller must free the
5731 strings and the array after use.
5732 Because of the message protocol, there is a transfer limit of somewhere
5734 between 2MB and 4MB. See "PROTOCOL LIMITS".
5735 (Added in 1.0.66)
5737 guestfs_file
5739 char *
5740 guestfs_file (guestfs_h *g,
5741 const char *path);
5742 This call uses the standard file(1) command to determine the type or
5744 contents of the file.
5745 This call will also transparently look inside various types of
5747 compressed file.
5748 The filename is not prepended to the output (like the file command -b
5750 option).
5751 The output depends on the output of the underlying file(1) command and
5753 it can change in future in ways beyond our control. In other words,
5754 the output is not guaranteed by the ABI.
5755 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5757 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5758 This function returns a string, or NULL on error. The caller must free
5760 the returned string after use.
5761 (Added in 1.9.1)
5763 guestfs_file_architecture
5765 char *
5766 guestfs_file_architecture (guestfs_h *g,
5767 const char *filename);
5768 This detects the architecture of the binary filename, and returns it if
5770 known.
5771 Currently defined architectures are:
5773 "aarch64"
5775 64 bit ARM.
5776 "arm"
5778 32 bit ARM.
5779 "i386"
5781 This string is returned for all 32 bit i386, i486, i586, i686
5782 binaries irrespective of the precise processor requirements of the
5783 binary.
5784 "ia64"
5786 Intel Itanium.
5787 "ppc"
5789 32 bit Power PC.
5790 "ppc64"
5792 64 bit Power PC (big endian).
5793 "ppc64le"
5795 64 bit Power PC (little endian).
5796 "riscv32"
5798 "riscv64"
5799 "riscv128"
5800 RISC-V 32-, 64- or 128-bit variants.
5801 "s390"
5803 31 bit IBM S/390.
5804 "s390x"
5806 64 bit IBM S/390.
5807 "sparc"
5809 32 bit SPARC.
5810 "sparc64"
5812 64 bit SPARC V9 and above.
5813 "x86_64"
5815 64 bit x86-64.
5816 Libguestfs may return other architecture strings in future.
5818 The function works on at least the following types of files:
5820 • many types of Un*x and Linux binary
5822 • many types of Un*x and Linux shared library
5824 • Windows Win32 and Win64 binaries
5826 • Windows Win32 and Win64 DLLs
5828 Win32 binaries and DLLs return "i386".
5830 Win64 binaries and DLLs return "x86_64".
5832 • Linux kernel modules
5834 • Linux new-style initrd images
5836 • some non-x86 Linux vmlinuz kernels
5838 What it can't do currently:
5840 • static libraries (libfoo.a)
5842 • Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5844 • x86 Linux vmlinuz kernels
5846 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5848 and compressed code, and are horribly hard to unpack. If you want
5849 to find the architecture of a kernel, use the architecture of the
5850 associated initrd or kernel module(s) instead.
5851 This function returns a string, or NULL on error. The caller must free
5853 the returned string after use.
5854 (Added in 1.5.3)
5856 guestfs_filesize
5858 int64_t
5859 guestfs_filesize (guestfs_h *g,
5860 const char *file);
5861 This command returns the size of file in bytes.
5863 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5865 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
5866 devices, use "guestfs_blockdev_getsize64".
5867 On error this function returns -1.
5869 (Added in 1.0.82)
5871 guestfs_filesystem_available
5873 int
5874 guestfs_filesystem_available (guestfs_h *g,
5875 const char *filesystem);
5876 Check whether libguestfs supports the named filesystem. The argument
5878 "filesystem" is a filesystem name, such as "ext3".
5879 You must call "guestfs_launch" before using this command.
5881 This is mainly useful as a negative test. If this returns true, it
5883 doesn't mean that a particular filesystem can be created or mounted,
5884 since filesystems can fail for other reasons such as it being a later
5885 version of the filesystem, or having incompatible features, or lacking
5886 the right mkfs.<fs> tool.
5887 See also "guestfs_available", "guestfs_feature_available",
5889 "AVAILABILITY".
5890 This function returns a C truth value on success or -1 on error.
5892 (Added in 1.19.5)
5894 guestfs_filesystem_walk
5896 struct guestfs_tsk_dirent_list *
5897 guestfs_filesystem_walk (guestfs_h *g,
5898 const char *device);
5899 Walk through the internal structures of a disk partition (eg.
5901 /dev/sda1) in order to return a list of all the files and directories
5902 stored within.
5903 It is not necessary to mount the disk partition to run this command.
5905 All entries in the filesystem are returned. This function can list
5907 deleted or unaccessible files. The entries are not sorted.
5908 The "tsk_dirent" structure contains the following fields.
5910 "tsk_inode"
5912 Filesystem reference number of the node. It might be 0 if the node
5913 has been deleted.
5914 "tsk_type"
5916 Basic file type information. See below for a detailed list of
5917 values.
5918 "tsk_size"
5920 File size in bytes. It might be -1 if the node has been deleted.
5921 "tsk_name"
5923 The file path relative to its directory.
5924 "tsk_flags"
5926 Bitfield containing extra information regarding the entry. It
5927 contains the logical OR of the following values:
5928 0x0001
5930 If set to 1, the file is allocated and visible within the
5931 filesystem. Otherwise, the file has been deleted. Under
5932 certain circumstances, the function "download_inode" can be
5933 used to recover deleted files.
5934 0x0002
5936 Filesystem such as NTFS and Ext2 or greater, separate the file
5937 name from the metadata structure. The bit is set to 1 when the
5938 file name is in an unallocated state and the metadata structure
5939 is in an allocated one. This generally implies the metadata
5940 has been reallocated to a new file. Therefore, information
5941 such as file type, file size, timestamps, number of links and
5942 symlink target might not correspond with the ones of the
5943 original deleted entry.
5944 0x0004
5946 The bit is set to 1 when the file is compressed using
5947 filesystem native compression support (NTFS). The API is not
5948 able to detect application level compression.
5949 "tsk_atime_sec"
5951 "tsk_atime_nsec"
5952 "tsk_mtime_sec"
5953 "tsk_mtime_nsec"
5954 "tsk_ctime_sec"
5955 "tsk_ctime_nsec"
5956 "tsk_crtime_sec"
5957 "tsk_crtime_nsec"
5958 Respectively, access, modification, last status change and creation
5959 time in Unix format in seconds and nanoseconds.
5960 "tsk_nlink"
5962 Number of file names pointing to this entry.
5963 "tsk_link"
5965 If the entry is a symbolic link, this field will contain the path
5966 to the target file.
5967 The "tsk_type" field will contain one of the following characters:
5969 'b' Block special
5971 'c' Char special
5973 'd' Directory
5975 'f' FIFO (named pipe)
5977 'l' Symbolic link
5979 'r' Regular file
5981 's' Socket
5983 'h' Shadow inode (Solaris)
5985 'w' Whiteout inode (BSD)
5987 'u' Unknown file type
5989 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
5991 there was an error. The caller must call
5992 "guestfs_free_tsk_dirent_list" after use.
5993 This long-running command can generate progress notification messages
5995 so that the caller can display a progress bar or indicator. To receive
5996 these messages, the caller must register a progress event callback.
5997 See "GUESTFS_EVENT_PROGRESS".
5998 This function depends on the feature "libtsk". See also
6000 "guestfs_feature_available".
6001 (Added in 1.33.39)
6003 guestfs_fill
6005 int
6006 guestfs_fill (guestfs_h *g,
6007 int c,
6008 int len,
6009 const char *path);
6010 This command creates a new file called "path". The initial content of
6012 the file is "len" octets of "c", where "c" must be a number in the
6013 range "[0..255]".
6014 To fill a file with zero bytes (sparsely), it is much more efficient to
6016 use "guestfs_truncate_size". To create a file with a pattern of
6017 repeating bytes use "guestfs_fill_pattern".
6018 This function returns 0 on success or -1 on error.
6020 This long-running command can generate progress notification messages
6022 so that the caller can display a progress bar or indicator. To receive
6023 these messages, the caller must register a progress event callback.
6024 See "GUESTFS_EVENT_PROGRESS".
6025 (Added in 1.0.79)
6027 guestfs_fill_dir
6029 int
6030 guestfs_fill_dir (guestfs_h *g,
6031 const char *dir,
6032 int nr);
6033 This function, useful for testing filesystems, creates "nr" empty files
6035 in the directory "dir" with names 00000000 through "nr-1" (ie. each
6036 file name is 8 digits long padded with zeroes).
6037 This function returns 0 on success or -1 on error.
6039 (Added in 1.19.32)
6041 guestfs_fill_pattern
6043 int
6044 guestfs_fill_pattern (guestfs_h *g,
6045 const char *pattern,
6046 int len,
6047 const char *path);
6048 This function is like "guestfs_fill" except that it creates a new file
6050 of length "len" containing the repeating pattern of bytes in "pattern".
6051 The pattern is truncated if necessary to ensure the length of the file
6052 is exactly "len" bytes.
6053 This function returns 0 on success or -1 on error.
6055 This long-running command can generate progress notification messages
6057 so that the caller can display a progress bar or indicator. To receive
6058 these messages, the caller must register a progress event callback.
6059 See "GUESTFS_EVENT_PROGRESS".
6060 (Added in 1.3.12)
6062 guestfs_find
6064 char **
6065 guestfs_find (guestfs_h *g,
6066 const char *directory);
6067 This command lists out all files and directories, recursively, starting
6069 at directory. It is essentially equivalent to running the shell
6070 command "find directory -print" but some post-processing happens on the
6071 output, described below.
6072 This returns a list of strings without any prefix. Thus if the
6074 directory structure was:
6075 /tmp/a
6077 /tmp/b
6078 /tmp/c/d
6079 then the returned list from "guestfs_find" /tmp would be 4 elements:
6081 a
6083 b
6084 c
6085 c/d
6086 If directory is not a directory, then this command returns an error.
6088 The returned list is sorted.
6090 This function returns a NULL-terminated array of strings (like
6092 environ(3)), or NULL if there was an error. The caller must free the
6093 strings and the array after use.
6094 (Added in 1.0.27)
6096 guestfs_find0
6098 int
6099 guestfs_find0 (guestfs_h *g,
6100 const char *directory,
6101 const char *files);
6102 This command lists out all files and directories, recursively, starting
6104 at directory, placing the resulting list in the external file called
6105 files.
6106 This command works the same way as "guestfs_find" with the following
6108 exceptions:
6109 • The resulting list is written to an external file.
6111 • Items (filenames) in the result are separated by "\0" characters.
6113 See find(1) option -print0.
6114 • The result list is not sorted.
6116 This function returns 0 on success or -1 on error.
6118 (Added in 1.0.74)
6120 guestfs_find_inode
6122 struct guestfs_tsk_dirent_list *
6123 guestfs_find_inode (guestfs_h *g,
6124 const char *device,
6125 int64_t inode);
6126 Searches all the entries associated with the given inode.
6128 For each entry, a "tsk_dirent" structure is returned. See
6130 "filesystem_walk" for more information about "tsk_dirent" structures.
6131 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6133 there was an error. The caller must call
6134 "guestfs_free_tsk_dirent_list" after use.
6135 This long-running command can generate progress notification messages
6137 so that the caller can display a progress bar or indicator. To receive
6138 these messages, the caller must register a progress event callback.
6139 See "GUESTFS_EVENT_PROGRESS".
6140 This function depends on the feature "libtsk". See also
6142 "guestfs_feature_available".
6143 (Added in 1.35.6)
6145 guestfs_findfs_label
6147 char *
6148 guestfs_findfs_label (guestfs_h *g,
6149 const char *label);
6150 This command searches the filesystems and returns the one which has the
6152 given label. An error is returned if no such filesystem can be found.
6153 To find the label of a filesystem, use "guestfs_vfs_label".
6155 This function returns a string, or NULL on error. The caller must free
6157 the returned string after use.
6158 (Added in 1.5.3)
6160 guestfs_findfs_uuid
6162 char *
6163 guestfs_findfs_uuid (guestfs_h *g,
6164 const char *uuid);
6165 This command searches the filesystems and returns the one which has the
6167 given UUID. An error is returned if no such filesystem can be found.
6168 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6170 This function returns a string, or NULL on error. The caller must free
6172 the returned string after use.
6173 (Added in 1.5.3)
6175 guestfs_fsck
6177 int
6178 guestfs_fsck (guestfs_h *g,
6179 const char *fstype,
6180 const char *device);
6181 This runs the filesystem checker (fsck) on "device" which should have
6183 filesystem type "fstype".
6184 The returned integer is the status. See fsck(8) for the list of status
6186 codes from "fsck".
6187 Notes:
6189 • Multiple status codes can be summed together.
6191 • A non-zero return code can mean "success", for example if errors
6193 have been corrected on the filesystem.
6194 • Checking or repairing NTFS volumes is not supported (by linux-
6196 ntfs).
6197 This command is entirely equivalent to running "fsck -a -t fstype
6199 device".
6200 On error this function returns -1.
6202 (Added in 1.0.16)
6204 guestfs_fstrim
6206 int
6207 guestfs_fstrim (guestfs_h *g,
6208 const char *mountpoint,
6209 ...);
6210 You may supply a list of optional arguments to this call. Use zero or
6212 more of the following pairs of parameters, and terminate the list with
6213 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6214 GUESTFS_FSTRIM_OFFSET, int64_t offset,
6216 GUESTFS_FSTRIM_LENGTH, int64_t length,
6217 GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6218 Trim the free space in the filesystem mounted on "mountpoint". The
6220 filesystem must be mounted read-write.
6221 The filesystem contents are not affected, but any free space in the
6223 filesystem is "trimmed", that is, given back to the host device, thus
6224 making disk images more sparse, allowing unused space in qcow2 files to
6225 be reused, etc.
6226 This operation requires support in libguestfs, the mounted filesystem,
6228 the host filesystem, qemu and the host kernel. If this support isn't
6229 present it may give an error or even appear to run but do nothing.
6230 In the case where the kernel vfs driver does not support trimming, this
6232 call will fail with errno set to "ENOTSUP". Currently this happens
6233 when trying to trim FAT filesystems.
6234 See also "guestfs_zero_free_space". That is a slightly different
6236 operation that turns free space in the filesystem into zeroes. It is
6237 valid to call "guestfs_fstrim" either instead of, or after calling
6238 "guestfs_zero_free_space".
6239 This function returns 0 on success or -1 on error.
6241 This function depends on the feature "fstrim". See also
6243 "guestfs_feature_available".
6244 (Added in 1.19.6)
6246 guestfs_fstrim_va
6248 int
6249 guestfs_fstrim_va (guestfs_h *g,
6250 const char *mountpoint,
6251 va_list args);
6252 This is the "va_list variant" of "guestfs_fstrim".
6254 See "CALLS WITH OPTIONAL ARGUMENTS".
6256 guestfs_fstrim_argv
6258 int
6259 guestfs_fstrim_argv (guestfs_h *g,
6260 const char *mountpoint,
6261 const struct guestfs_fstrim_argv *optargs);
6262 This is the "argv variant" of "guestfs_fstrim".
6264 See "CALLS WITH OPTIONAL ARGUMENTS".
6266 guestfs_get_append
6268 const char *
6269 guestfs_get_append (guestfs_h *g);
6270 Return the additional kernel options which are added to the libguestfs
6272 appliance kernel command line.
6273 If "NULL" then no options are added.
6275 This function returns a string which may be NULL. There is no way to
6277 return an error from this function. The string is owned by the guest
6278 handle and must not be freed.
6279 (Added in 1.0.26)
6281 guestfs_get_attach_method
6283 char *
6284 guestfs_get_attach_method (guestfs_h *g);
6285 This function is deprecated. In new code, use the
6287 "guestfs_get_backend" call instead.
6288 Deprecated functions will not be removed from the API, but the fact
6290 that they are deprecated indicates that there are problems with correct
6291 use of these functions.
6292 Return the current backend.
6294 See "guestfs_set_backend" and "BACKEND".
6296 This function returns a string, or NULL on error. The caller must free
6298 the returned string after use.
6299 (Added in 1.9.8)
6301 guestfs_get_autosync
6303 int
6304 guestfs_get_autosync (guestfs_h *g);
6305 Get the autosync flag.
6307 This function returns a C truth value on success or -1 on error.
6309 (Added in 0.3)
6311 guestfs_get_backend
6313 char *
6314 guestfs_get_backend (guestfs_h *g);
6315 Return the current backend.
6317 This handle property was previously called the "attach method".
6319 See "guestfs_set_backend" and "BACKEND".
6321 This function returns a string, or NULL on error. The caller must free
6323 the returned string after use.
6324 (Added in 1.21.26)
6326 guestfs_get_backend_setting
6328 char *
6329 guestfs_get_backend_setting (guestfs_h *g,
6330 const char *name);
6331 Find a backend setting string which is either "name" or begins with
6333 "name=". If "name", this returns the string "1". If "name=", this
6334 returns the part after the equals sign (which may be an empty string).
6335 If no such setting is found, this function throws an error. The errno
6337 (see "guestfs_last_errno") will be "ESRCH" in this case.
6338 See "BACKEND", "BACKEND SETTINGS".
6340 This function returns a string, or NULL on error. The caller must free
6342 the returned string after use.
6343 (Added in 1.27.2)
6345 guestfs_get_backend_settings
6347 char **
6348 guestfs_get_backend_settings (guestfs_h *g);
6349 Return the current backend settings.
6351 This call returns all backend settings strings. If you want to find a
6353 single backend setting, see "guestfs_get_backend_setting".
6354 See "BACKEND", "BACKEND SETTINGS".
6356 This function returns a NULL-terminated array of strings (like
6358 environ(3)), or NULL if there was an error. The caller must free the
6359 strings and the array after use.
6360 (Added in 1.25.24)
6362 guestfs_get_cachedir
6364 char *
6365 guestfs_get_cachedir (guestfs_h *g);
6366 Get the directory used by the handle to store the appliance cache.
6368 This function returns a string, or NULL on error. The caller must free
6370 the returned string after use.
6371 (Added in 1.19.58)
6373 guestfs_get_direct
6375 int
6376 guestfs_get_direct (guestfs_h *g);
6377 This function is deprecated. In new code, use the
6379 "guestfs_internal_get_console_socket" call instead.
6380 Deprecated functions will not be removed from the API, but the fact
6382 that they are deprecated indicates that there are problems with correct
6383 use of these functions.
6384 Return the direct appliance mode flag.
6386 This function returns a C truth value on success or -1 on error.
6388 (Added in 1.0.72)
6390 guestfs_get_e2attrs
6392 char *
6393 guestfs_get_e2attrs (guestfs_h *g,
6394 const char *file);
6395 This returns the file attributes associated with file.
6397 The attributes are a set of bits associated with each inode which
6399 affect the behaviour of the file. The attributes are returned as a
6400 string of letters (described below). The string may be empty,
6401 indicating that no file attributes are set for this file.
6402 These attributes are only present when the file is located on an
6404 ext2/3/4 filesystem. Using this call on other filesystem types will
6405 result in an error.
6406 The characters (file attributes) in the returned string are currently:
6408 'A' When the file is accessed, its atime is not modified.
6410 'a' The file is append-only.
6412 'c' The file is compressed on-disk.
6414 'D' (Directories only.) Changes to this directory are written
6416 synchronously to disk.
6417 'd' The file is not a candidate for backup (see dump(8)).
6419 'E' The file has compression errors.
6421 'e' The file is using extents.
6423 'h' The file is storing its blocks in units of the filesystem blocksize
6425 instead of sectors.
6426 'I' (Directories only.) The directory is using hashed trees.
6428 'i' The file is immutable. It cannot be modified, deleted or renamed.
6430 No link can be created to this file.
6431 'j' The file is data-journaled.
6433 's' When the file is deleted, all its blocks will be zeroed.
6435 'S' Changes to this file are written synchronously to disk.
6437 'T' (Directories only.) This is a hint to the block allocator that
6439 subdirectories contained in this directory should be spread across
6440 blocks. If not present, the block allocator will try to group
6441 subdirectories together.
6442 't' For a file, this disables tail-merging. (Not used by upstream
6444 implementations of ext2.)
6445 'u' When the file is deleted, its blocks will be saved, allowing the
6447 file to be undeleted.
6448 'X' The raw contents of the compressed file may be accessed.
6450 'Z' The compressed file is dirty.
6452 More file attributes may be added to this list later. Not all file
6454 attributes may be set for all kinds of files. For detailed
6455 information, consult the chattr(1) man page.
6456 See also "guestfs_set_e2attrs".
6458 Don't confuse these attributes with extended attributes (see
6460 "guestfs_getxattr").
6461 This function returns a string, or NULL on error. The caller must free
6463 the returned string after use.
6464 (Added in 1.17.31)
6466 guestfs_get_e2generation
6468 int64_t
6469 guestfs_get_e2generation (guestfs_h *g,
6470 const char *file);
6471 This returns the ext2 file generation of a file. The generation (which
6473 used to be called the "version") is a number associated with an inode.
6474 This is most commonly used by NFS servers.
6475 The generation is only present when the file is located on an ext2/3/4
6477 filesystem. Using this call on other filesystem types will result in
6478 an error.
6479 See "guestfs_set_e2generation".
6481 On error this function returns -1.
6483 (Added in 1.17.31)
6485 guestfs_get_e2label
6487 char *
6488 guestfs_get_e2label (guestfs_h *g,
6489 const char *device);
6490 This function is deprecated. In new code, use the "guestfs_vfs_label"
6492 call instead.
6493 Deprecated functions will not be removed from the API, but the fact
6495 that they are deprecated indicates that there are problems with correct
6496 use of these functions.
6497 This returns the ext2/3/4 filesystem label of the filesystem on
6499 "device".
6500 This function returns a string, or NULL on error. The caller must free
6502 the returned string after use.
6503 (Added in 1.0.15)
6505 guestfs_get_e2uuid
6507 char *
6508 guestfs_get_e2uuid (guestfs_h *g,
6509 const char *device);
6510 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
6512 call instead.
6513 Deprecated functions will not be removed from the API, but the fact
6515 that they are deprecated indicates that there are problems with correct
6516 use of these functions.
6517 This returns the ext2/3/4 filesystem UUID of the filesystem on
6519 "device".
6520 This function returns a string, or NULL on error. The caller must free
6522 the returned string after use.
6523 (Added in 1.0.15)
6525 guestfs_get_hv
6527 char *
6528 guestfs_get_hv (guestfs_h *g);
6529 Return the current hypervisor binary.
6531 This is always non-NULL. If it wasn't set already, then this will
6533 return the default qemu binary name.
6534 This function returns a string, or NULL on error. The caller must free
6536 the returned string after use.
6537 (Added in 1.23.17)
6539 guestfs_get_identifier
6541 const char *
6542 guestfs_get_identifier (guestfs_h *g);
6543 Get the handle identifier. See "guestfs_set_identifier".
6545 This function returns a string, or NULL on error. The string is owned
6547 by the guest handle and must not be freed.
6548 (Added in 1.31.14)
6550 guestfs_get_libvirt_requested_credential_challenge
6552 char *
6553 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6554 int index);
6555 Get the challenge (provided by libvirt) for the "index"'th requested
6557 credential. If libvirt did not provide a challenge, this returns the
6558 empty string "".
6559 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6561 This function returns a string, or NULL on error. The caller must free
6563 the returned string after use.
6564 (Added in 1.19.52)
6566 guestfs_get_libvirt_requested_credential_defresult
6568 char *
6569 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6570 int index);
6571 Get the default result (provided by libvirt) for the "index"'th
6573 requested credential. If libvirt did not provide a default result,
6574 this returns the empty string "".
6575 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6577 This function returns a string, or NULL on error. The caller must free
6579 the returned string after use.
6580 (Added in 1.19.52)
6582 guestfs_get_libvirt_requested_credential_prompt
6584 char *
6585 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6586 int index);
6587 Get the prompt (provided by libvirt) for the "index"'th requested
6589 credential. If libvirt did not provide a prompt, this returns the
6590 empty string "".
6591 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6593 This function returns a string, or NULL on error. The caller must free
6595 the returned string after use.
6596 (Added in 1.19.52)
6598 guestfs_get_libvirt_requested_credentials
6600 char **
6601 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6602 This should only be called during the event callback for events of type
6604 "GUESTFS_EVENT_LIBVIRT_AUTH".
6605 Return the list of credentials requested by libvirt. Possible values
6607 are a subset of the strings provided when you called
6608 "guestfs_set_libvirt_supported_credentials".
6609 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6611 This function returns a NULL-terminated array of strings (like
6613 environ(3)), or NULL if there was an error. The caller must free the
6614 strings and the array after use.
6615 (Added in 1.19.52)
6617 guestfs_get_memsize
6619 int
6620 guestfs_get_memsize (guestfs_h *g);
6621 This gets the memory size in megabytes allocated to the hypervisor.
6623 If "guestfs_set_memsize" was not called on this handle, and if
6625 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6626 default value for memsize.
6627 For more information on the architecture of libguestfs, see guestfs(3).
6629 On error this function returns -1.
6631 (Added in 1.0.55)
6633 guestfs_get_network
6635 int
6636 guestfs_get_network (guestfs_h *g);
6637 This returns the enable network flag.
6639 This function returns a C truth value on success or -1 on error.
6641 (Added in 1.5.4)
6643 guestfs_get_path
6645 const char *
6646 guestfs_get_path (guestfs_h *g);
6647 Return the current search path.
6649 This is always non-NULL. If it wasn't set already, then this will
6651 return the default path.
6652 This function returns a string, or NULL on error. The string is owned
6654 by the guest handle and must not be freed.
6655 (Added in 0.3)
6657 guestfs_get_pgroup
6659 int
6660 guestfs_get_pgroup (guestfs_h *g);
6661 This returns the process group flag.
6663 This function returns a C truth value on success or -1 on error.
6665 (Added in 1.11.18)
6667 guestfs_get_pid
6669 int
6670 guestfs_get_pid (guestfs_h *g);
6671 Return the process ID of the hypervisor. If there is no hypervisor
6673 running, then this will return an error.
6674 This is an internal call used for debugging and testing.
6676 On error this function returns -1.
6678 (Added in 1.0.56)
6680 guestfs_get_program
6682 const char *
6683 guestfs_get_program (guestfs_h *g);
6684 Get the program name. See "guestfs_set_program".
6686 This function returns a string, or NULL on error. The string is owned
6688 by the guest handle and must not be freed.
6689 (Added in 1.21.29)
6691 guestfs_get_qemu
6693 const char *
6694 guestfs_get_qemu (guestfs_h *g);
6695 This function is deprecated. In new code, use the "guestfs_get_hv"
6697 call instead.
6698 Deprecated functions will not be removed from the API, but the fact
6700 that they are deprecated indicates that there are problems with correct
6701 use of these functions.
6702 Return the current hypervisor binary (usually qemu).
6704 This is always non-NULL. If it wasn't set already, then this will
6706 return the default qemu binary name.
6707 This function returns a string, or NULL on error. The string is owned
6709 by the guest handle and must not be freed.
6710 (Added in 1.0.6)
6712 guestfs_get_recovery_proc
6714 int
6715 guestfs_get_recovery_proc (guestfs_h *g);
6716 Return the recovery process enabled flag.
6718 This function returns a C truth value on success or -1 on error.
6720 (Added in 1.0.77)
6722 guestfs_get_selinux
6724 int
6725 guestfs_get_selinux (guestfs_h *g);
6726 This function is deprecated. In new code, use the
6728 "guestfs_selinux_relabel" call instead.
6729 Deprecated functions will not be removed from the API, but the fact
6731 that they are deprecated indicates that there are problems with correct
6732 use of these functions.
6733 This returns the current setting of the selinux flag which is passed to
6735 the appliance at boot time. See "guestfs_set_selinux".
6736 For more information on the architecture of libguestfs, see guestfs(3).
6738 This function returns a C truth value on success or -1 on error.
6740 (Added in 1.0.67)
6742 guestfs_get_smp
6744 int
6745 guestfs_get_smp (guestfs_h *g);
6746 This returns the number of virtual CPUs assigned to the appliance.
6748 On error this function returns -1.
6750 (Added in 1.13.15)
6752 guestfs_get_sockdir
6754 char *
6755 guestfs_get_sockdir (guestfs_h *g);
6756 Get the directory used by the handle to store temporary socket files.
6758 This is different from "guestfs_get_tmpdir", as we need shorter paths
6760 for sockets (due to the limited buffers of filenames for UNIX sockets),
6761 and "guestfs_get_tmpdir" may be too long for them.
6762 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6764 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6765 the default.
6766 This function returns a string, or NULL on error. The caller must free
6768 the returned string after use.
6769 (Added in 1.33.8)
6771 guestfs_get_state
6773 int
6774 guestfs_get_state (guestfs_h *g);
6775 This returns the current state as an opaque integer. This is only
6777 useful for printing debug and internal error messages.
6778 For more information on states, see guestfs(3).
6780 On error this function returns -1.
6782 (Added in 1.0.2)
6784 guestfs_get_tmpdir
6786 char *
6787 guestfs_get_tmpdir (guestfs_h *g);
6788 Get the directory used by the handle to store temporary files.
6790 This function returns a string, or NULL on error. The caller must free
6792 the returned string after use.
6793 (Added in 1.19.58)
6795 guestfs_get_trace
6797 int
6798 guestfs_get_trace (guestfs_h *g);
6799 Return the command trace flag.
6801 This function returns a C truth value on success or -1 on error.
6803 (Added in 1.0.69)
6805 guestfs_get_umask
6807 int
6808 guestfs_get_umask (guestfs_h *g);
6809 Return the current umask. By default the umask is 022 unless it has
6811 been set by calling "guestfs_umask".
6812 On error this function returns -1.
6814 (Added in 1.3.4)
6816 guestfs_get_verbose
6818 int
6819 guestfs_get_verbose (guestfs_h *g);
6820 This returns the verbose messages flag.
6822 This function returns a C truth value on success or -1 on error.
6824 (Added in 0.3)
6826 guestfs_getcon
6828 char *
6829 guestfs_getcon (guestfs_h *g);
6830 This function is deprecated. In new code, use the
6832 "guestfs_selinux_relabel" call instead.
6833 Deprecated functions will not be removed from the API, but the fact
6835 that they are deprecated indicates that there are problems with correct
6836 use of these functions.
6837 This gets the SELinux security context of the daemon.
6839 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6841 This function returns a string, or NULL on error. The caller must free
6843 the returned string after use.
6844 This function depends on the feature "selinux". See also
6846 "guestfs_feature_available".
6847 (Added in 1.0.67)
6849 guestfs_getxattr
6851 char *
6852 guestfs_getxattr (guestfs_h *g,
6853 const char *path,
6854 const char *name,
6855 size_t *size_r);
6856 Get a single extended attribute from file "path" named "name". This
6858 call follows symlinks. If you want to lookup an extended attribute for
6859 the symlink itself, use "guestfs_lgetxattr".
6860 Normally it is better to get all extended attributes from a file in one
6862 go by calling "guestfs_getxattrs". However some Linux filesystem
6863 implementations are buggy and do not provide a way to list out
6864 attributes. For these filesystems (notably ntfs-3g) you have to know
6865 the names of the extended attributes you want in advance and call this
6866 function.
6867 Extended attribute values are blobs of binary data. If there is no
6869 extended attribute named "name", this returns an error.
6870 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6872 This function returns a buffer, or NULL on error. The size of the
6874 returned buffer is written to *size_r. The caller must free the
6875 returned buffer after use.
6876 This function depends on the feature "linuxxattrs". See also
6878 "guestfs_feature_available".
6879 (Added in 1.7.24)
6881 guestfs_getxattrs
6883 struct guestfs_xattr_list *
6884 guestfs_getxattrs (guestfs_h *g,
6885 const char *path);
6886 This call lists the extended attributes of the file or directory
6888 "path".
6889 At the system call level, this is a combination of the listxattr(2) and
6891 getxattr(2) calls.
6892 See also: "guestfs_lgetxattrs", attr(5).
6894 This function returns a "struct guestfs_xattr_list *", or NULL if there
6896 was an error. The caller must call "guestfs_free_xattr_list" after
6897 use.
6898 This function depends on the feature "linuxxattrs". See also
6900 "guestfs_feature_available".
6901 (Added in 1.0.59)
6903 guestfs_glob_expand
6905 char **
6906 guestfs_glob_expand (guestfs_h *g,
6907 const char *pattern);
6908 This function is provided for backwards compatibility with earlier
6910 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
6911 with no optional arguments.
6912 (Added in 1.0.50)
6914 guestfs_glob_expand_opts
6916 char **
6917 guestfs_glob_expand_opts (guestfs_h *g,
6918 const char *pattern,
6919 ...);
6920 You may supply a list of optional arguments to this call. Use zero or
6922 more of the following pairs of parameters, and terminate the list with
6923 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6924 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
6926 This command searches for all the pathnames matching "pattern"
6928 according to the wildcard expansion rules used by the shell.
6929 If no paths match, then this returns an empty list (note: not an
6931 error).
6932 It is just a wrapper around the C glob(3) function with flags
6934 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
6935 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
6937 and it defaults to true. It can be explicitly set as off to return no
6938 trailing slashes in filenames of directories.
6939 Notice that there is no equivalent command for expanding a device name
6941 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
6942 etc functions instead.
6943 This function returns a NULL-terminated array of strings (like
6945 environ(3)), or NULL if there was an error. The caller must free the
6946 strings and the array after use.
6947 (Added in 1.0.50)
6949 guestfs_glob_expand_opts_va
6951 char **
6952 guestfs_glob_expand_opts_va (guestfs_h *g,
6953 const char *pattern,
6954 va_list args);
6955 This is the "va_list variant" of "guestfs_glob_expand_opts".
6957 See "CALLS WITH OPTIONAL ARGUMENTS".
6959 guestfs_glob_expand_opts_argv
6961 char **
6962 guestfs_glob_expand_opts_argv (guestfs_h *g,
6963 const char *pattern,
6964 const struct guestfs_glob_expand_opts_argv *optargs);
6965 This is the "argv variant" of "guestfs_glob_expand_opts".
6967 See "CALLS WITH OPTIONAL ARGUMENTS".
6969 guestfs_grep
6971 char **
6972 guestfs_grep (guestfs_h *g,
6973 const char *regex,
6974 const char *path);
6975 This function is provided for backwards compatibility with earlier
6977 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
6978 optional arguments.
6979 (Added in 1.0.66)
6981 guestfs_grep_opts
6983 char **
6984 guestfs_grep_opts (guestfs_h *g,
6985 const char *regex,
6986 const char *path,
6987 ...);
6988 You may supply a list of optional arguments to this call. Use zero or
6990 more of the following pairs of parameters, and terminate the list with
6991 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6992 GUESTFS_GREP_OPTS_EXTENDED, int extended,
6994 GUESTFS_GREP_OPTS_FIXED, int fixed,
6995 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
6996 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
6997 This calls the external grep(1) program and returns the matching lines.
6999 The optional flags are:
7001 "extended"
7003 Use extended regular expressions. This is the same as using the -E
7004 flag.
7005 "fixed"
7007 Match fixed (don't use regular expressions). This is the same as
7008 using the -F flag.
7009 "insensitive"
7011 Match case-insensitive. This is the same as using the -i flag.
7012 "compressed"
7014 Use zgrep(1) instead of grep(1). This allows the input to be
7015 compress- or gzip-compressed.
7016 This function returns a NULL-terminated array of strings (like
7018 environ(3)), or NULL if there was an error. The caller must free the
7019 strings and the array after use.
7020 Because of the message protocol, there is a transfer limit of somewhere
7022 between 2MB and 4MB. See "PROTOCOL LIMITS".
7023 (Added in 1.0.66)
7025 guestfs_grep_opts_va
7027 char **
7028 guestfs_grep_opts_va (guestfs_h *g,
7029 const char *regex,
7030 const char *path,
7031 va_list args);
7032 This is the "va_list variant" of "guestfs_grep_opts".
7034 See "CALLS WITH OPTIONAL ARGUMENTS".
7036 guestfs_grep_opts_argv
7038 char **
7039 guestfs_grep_opts_argv (guestfs_h *g,
7040 const char *regex,
7041 const char *path,
7042 const struct guestfs_grep_opts_argv *optargs);
7043 This is the "argv variant" of "guestfs_grep_opts".
7045 See "CALLS WITH OPTIONAL ARGUMENTS".
7047 guestfs_grepi
7049 char **
7050 guestfs_grepi (guestfs_h *g,
7051 const char *regex,
7052 const char *path);
7053 This function is deprecated. In new code, use the "guestfs_grep" call
7055 instead.
7056 Deprecated functions will not be removed from the API, but the fact
7058 that they are deprecated indicates that there are problems with correct
7059 use of these functions.
7060 This calls the external "grep -i" program and returns the matching
7062 lines.
7063 This function returns a NULL-terminated array of strings (like
7065 environ(3)), or NULL if there was an error. The caller must free the
7066 strings and the array after use.
7067 Because of the message protocol, there is a transfer limit of somewhere
7069 between 2MB and 4MB. See "PROTOCOL LIMITS".
7070 (Added in 1.0.66)
7072 guestfs_grub_install
7074 int
7075 guestfs_grub_install (guestfs_h *g,
7076 const char *root,
7077 const char *device);
7078 This command installs GRUB 1 (the Grand Unified Bootloader) on
7080 "device", with the root directory being "root".
7081 Notes:
7083 • There is currently no way in the API to install grub2, which is
7085 used by most modern Linux guests. It is possible to run the grub2
7086 command from the guest, although see the caveats in "RUNNING
7087 COMMANDS".
7088 • This uses grub-install(8) from the host. Unfortunately grub is not
7090 always compatible with itself, so this only works in rather narrow
7091 circumstances. Careful testing with each guest version is
7092 advisable.
7093 • If grub-install reports the error "No suitable drive was found in
7095 the generated device map." it may be that you need to create a
7096 /boot/grub/device.map file first that contains the mapping between
7097 grub device names and Linux device names. It is usually sufficient
7098 to create a file containing:
7099 (hd0) /dev/vda
7101 replacing /dev/vda with the name of the installation device.
7103 This function returns 0 on success or -1 on error.
7105 This function depends on the feature "grub". See also
7107 "guestfs_feature_available".
7108 (Added in 1.0.17)
7110 guestfs_head
7112 char **
7113 guestfs_head (guestfs_h *g,
7114 const char *path);
7115 This command returns up to the first 10 lines of a file as a list of
7117 strings.
7118 This function returns a NULL-terminated array of strings (like
7120 environ(3)), or NULL if there was an error. The caller must free the
7121 strings and the array after use.
7122 Because of the message protocol, there is a transfer limit of somewhere
7124 between 2MB and 4MB. See "PROTOCOL LIMITS".
7125 (Added in 1.0.54)
7127 guestfs_head_n
7129 char **
7130 guestfs_head_n (guestfs_h *g,
7131 int nrlines,
7132 const char *path);
7133 If the parameter "nrlines" is a positive number, this returns the first
7135 "nrlines" lines of the file "path".
7136 If the parameter "nrlines" is a negative number, this returns lines
7138 from the file "path", excluding the last "nrlines" lines.
7139 If the parameter "nrlines" is zero, this returns an empty list.
7141 This function returns a NULL-terminated array of strings (like
7143 environ(3)), or NULL if there was an error. The caller must free the
7144 strings and the array after use.
7145 Because of the message protocol, there is a transfer limit of somewhere
7147 between 2MB and 4MB. See "PROTOCOL LIMITS".
7148 (Added in 1.0.54)
7150 guestfs_hexdump
7152 char *
7153 guestfs_hexdump (guestfs_h *g,
7154 const char *path);
7155 This runs "hexdump -C" on the given "path". The result is the human-
7157 readable, canonical hex dump of the file.
7158 This function returns a string, or NULL on error. The caller must free
7160 the returned string after use.
7161 Because of the message protocol, there is a transfer limit of somewhere
7163 between 2MB and 4MB. See "PROTOCOL LIMITS".
7164 (Added in 1.0.22)
7166 guestfs_hivex_close
7168 int
7169 guestfs_hivex_close (guestfs_h *g);
7170 Close the current hivex handle.
7172 This is a wrapper around the hivex(3) call of the same name.
7174 This function returns 0 on success or -1 on error.
7176 This function depends on the feature "hivex". See also
7178 "guestfs_feature_available".
7179 (Added in 1.19.35)
7181 guestfs_hivex_commit
7183 int
7184 guestfs_hivex_commit (guestfs_h *g,
7185 const char *filename);
7186 Commit (write) changes to the hive.
7188 If the optional filename parameter is null, then the changes are
7190 written back to the same hive that was opened. If this is not null
7191 then they are written to the alternate filename given and the original
7192 hive is left untouched.
7193 This is a wrapper around the hivex(3) call of the same name.
7195 This function returns 0 on success or -1 on error.
7197 This function depends on the feature "hivex". See also
7199 "guestfs_feature_available".
7200 (Added in 1.19.35)
7202 guestfs_hivex_node_add_child
7204 int64_t
7205 guestfs_hivex_node_add_child (guestfs_h *g,
7206 int64_t parent,
7207 const char *name);
7208 Add a child node to "parent" named "name".
7210 This is a wrapper around the hivex(3) call of the same name.
7212 On error this function returns -1.
7214 This function depends on the feature "hivex". See also
7216 "guestfs_feature_available".
7217 (Added in 1.19.35)
7219 guestfs_hivex_node_children
7221 struct guestfs_hivex_node_list *
7222 guestfs_hivex_node_children (guestfs_h *g,
7223 int64_t nodeh);
7224 Return the list of nodes which are subkeys of "nodeh".
7226 This is a wrapper around the hivex(3) call of the same name.
7228 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7230 there was an error. The caller must call
7231 "guestfs_free_hivex_node_list" after use.
7232 This function depends on the feature "hivex". See also
7234 "guestfs_feature_available".
7235 (Added in 1.19.35)
7237 guestfs_hivex_node_delete_child
7239 int
7240 guestfs_hivex_node_delete_child (guestfs_h *g,
7241 int64_t nodeh);
7242 Delete "nodeh", recursively if necessary.
7244 This is a wrapper around the hivex(3) call of the same name.
7246 This function returns 0 on success or -1 on error.
7248 This function depends on the feature "hivex". See also
7250 "guestfs_feature_available".
7251 (Added in 1.19.35)
7253 guestfs_hivex_node_get_child
7255 int64_t
7256 guestfs_hivex_node_get_child (guestfs_h *g,
7257 int64_t nodeh,
7258 const char *name);
7259 Return the child of "nodeh" with the name "name", if it exists. This
7261 can return 0 meaning the name was not found.
7262 This is a wrapper around the hivex(3) call of the same name.
7264 On error this function returns -1.
7266 This function depends on the feature "hivex". See also
7268 "guestfs_feature_available".
7269 (Added in 1.19.35)
7271 guestfs_hivex_node_get_value
7273 int64_t
7274 guestfs_hivex_node_get_value (guestfs_h *g,
7275 int64_t nodeh,
7276 const char *key);
7277 Return the value attached to "nodeh" which has the name "key", if it
7279 exists. This can return 0 meaning the key was not found.
7280 This is a wrapper around the hivex(3) call of the same name.
7282 On error this function returns -1.
7284 This function depends on the feature "hivex". See also
7286 "guestfs_feature_available".
7287 (Added in 1.19.35)
7289 guestfs_hivex_node_name
7291 char *
7292 guestfs_hivex_node_name (guestfs_h *g,
7293 int64_t nodeh);
7294 Return the name of "nodeh".
7296 This is a wrapper around the hivex(3) call of the same name.
7298 This function returns a string, or NULL on error. The caller must free
7300 the returned string after use.
7301 This function depends on the feature "hivex". See also
7303 "guestfs_feature_available".
7304 (Added in 1.19.35)
7306 guestfs_hivex_node_parent
7308 int64_t
7309 guestfs_hivex_node_parent (guestfs_h *g,
7310 int64_t nodeh);
7311 Return the parent node of "nodeh".
7313 This is a wrapper around the hivex(3) call of the same name.
7315 On error this function returns -1.
7317 This function depends on the feature "hivex". See also
7319 "guestfs_feature_available".
7320 (Added in 1.19.35)
7322 guestfs_hivex_node_set_value
7324 int
7325 guestfs_hivex_node_set_value (guestfs_h *g,
7326 int64_t nodeh,
7327 const char *key,
7328 int64_t t,
7329 const char *val,
7330 size_t val_size);
7331 Set or replace a single value under the node "nodeh". The "key" is the
7333 name, "t" is the type, and "val" is the data.
7334 This is a wrapper around the hivex(3) call of the same name.
7336 This function returns 0 on success or -1 on error.
7338 This function depends on the feature "hivex". See also
7340 "guestfs_feature_available".
7341 (Added in 1.19.35)
7343 guestfs_hivex_node_values
7345 struct guestfs_hivex_value_list *
7346 guestfs_hivex_node_values (guestfs_h *g,
7347 int64_t nodeh);
7348 Return the array of (key, datatype, data) tuples attached to "nodeh".
7350 This is a wrapper around the hivex(3) call of the same name.
7352 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7354 there was an error. The caller must call
7355 "guestfs_free_hivex_value_list" after use.
7356 This function depends on the feature "hivex". See also
7358 "guestfs_feature_available".
7359 (Added in 1.19.35)
7361 guestfs_hivex_open
7363 int
7364 guestfs_hivex_open (guestfs_h *g,
7365 const char *filename,
7366 ...);
7367 You may supply a list of optional arguments to this call. Use zero or
7369 more of the following pairs of parameters, and terminate the list with
7370 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7371 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7373 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7374 GUESTFS_HIVEX_OPEN_WRITE, int write,
7375 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7376 Open the Windows Registry hive file named filename. If there was any
7378 previous hivex handle associated with this guestfs session, then it is
7379 closed.
7380 This is a wrapper around the hivex(3) call of the same name.
7382 This function returns 0 on success or -1 on error.
7384 This function depends on the feature "hivex". See also
7386 "guestfs_feature_available".
7387 (Added in 1.19.35)
7389 guestfs_hivex_open_va
7391 int
7392 guestfs_hivex_open_va (guestfs_h *g,
7393 const char *filename,
7394 va_list args);
7395 This is the "va_list variant" of "guestfs_hivex_open".
7397 See "CALLS WITH OPTIONAL ARGUMENTS".
7399 guestfs_hivex_open_argv
7401 int
7402 guestfs_hivex_open_argv (guestfs_h *g,
7403 const char *filename,
7404 const struct guestfs_hivex_open_argv *optargs);
7405 This is the "argv variant" of "guestfs_hivex_open".
7407 See "CALLS WITH OPTIONAL ARGUMENTS".
7409 guestfs_hivex_root
7411 int64_t
7412 guestfs_hivex_root (guestfs_h *g);
7413 Return the root node of the hive.
7415 This is a wrapper around the hivex(3) call of the same name.
7417 On error this function returns -1.
7419 This function depends on the feature "hivex". See also
7421 "guestfs_feature_available".
7422 (Added in 1.19.35)
7424 guestfs_hivex_value_key
7426 char *
7427 guestfs_hivex_value_key (guestfs_h *g,
7428 int64_t valueh);
7429 Return the key (name) field of a (key, datatype, data) tuple.
7431 This is a wrapper around the hivex(3) call of the same name.
7433 This function returns a string, or NULL on error. The caller must free
7435 the returned string after use.
7436 This function depends on the feature "hivex". See also
7438 "guestfs_feature_available".
7439 (Added in 1.19.35)
7441 guestfs_hivex_value_string
7443 char *
7444 guestfs_hivex_value_string (guestfs_h *g,
7445 int64_t valueh);
7446 This calls "guestfs_hivex_value_value" (which returns the data field
7448 from a hivex value tuple). It then assumes that the field is a
7449 UTF-16LE string and converts the result to UTF-8 (or if this is not
7450 possible, it returns an error).
7451 This is useful for reading strings out of the Windows registry.
7453 However it is not foolproof because the registry is not strongly-typed
7454 and fields can contain arbitrary or unexpected data.
7455 This function returns a string, or NULL on error. The caller must free
7457 the returned string after use.
7458 This function depends on the feature "hivex". See also
7460 "guestfs_feature_available".
7461 (Added in 1.37.22)
7463 guestfs_hivex_value_type
7465 int64_t
7466 guestfs_hivex_value_type (guestfs_h *g,
7467 int64_t valueh);
7468 Return the data type field from a (key, datatype, data) tuple.
7470 This is a wrapper around the hivex(3) call of the same name.
7472 On error this function returns -1.
7474 This function depends on the feature "hivex". See also
7476 "guestfs_feature_available".
7477 (Added in 1.19.35)
7479 guestfs_hivex_value_utf8
7481 char *
7482 guestfs_hivex_value_utf8 (guestfs_h *g,
7483 int64_t valueh);
7484 This function is deprecated. In new code, use the
7486 "guestfs_hivex_value_string" call instead.
7487 Deprecated functions will not be removed from the API, but the fact
7489 that they are deprecated indicates that there are problems with correct
7490 use of these functions.
7491 This calls "guestfs_hivex_value_value" (which returns the data field
7493 from a hivex value tuple). It then assumes that the field is a
7494 UTF-16LE string and converts the result to UTF-8 (or if this is not
7495 possible, it returns an error).
7496 This is useful for reading strings out of the Windows registry.
7498 However it is not foolproof because the registry is not strongly-typed
7499 and fields can contain arbitrary or unexpected data.
7500 This function returns a string, or NULL on error. The caller must free
7502 the returned string after use.
7503 This function depends on the feature "hivex". See also
7505 "guestfs_feature_available".
7506 (Added in 1.19.35)
7508 guestfs_hivex_value_value
7510 char *
7511 guestfs_hivex_value_value (guestfs_h *g,
7512 int64_t valueh,
7513 size_t *size_r);
7514 Return the data field of a (key, datatype, data) tuple.
7516 This is a wrapper around the hivex(3) call of the same name.
7518 See also: "guestfs_hivex_value_utf8".
7520 This function returns a buffer, or NULL on error. The size of the
7522 returned buffer is written to *size_r. The caller must free the
7523 returned buffer after use.
7524 This function depends on the feature "hivex". See also
7526 "guestfs_feature_available".
7527 (Added in 1.19.35)
7529 guestfs_initrd_cat
7531 char *
7532 guestfs_initrd_cat (guestfs_h *g,
7533 const char *initrdpath,
7534 const char *filename,
7535 size_t *size_r);
7536 This command unpacks the file filename from the initrd file called
7538 initrdpath. The filename must be given without the initial /
7539 character.
7540 For example, in guestfish you could use the following command to
7542 examine the boot script (usually called /init) contained in a Linux
7543 initrd or initramfs image:
7544 initrd-cat /boot/initrd-<version>.img init
7546 See also "guestfs_initrd_list".
7548 This function returns a buffer, or NULL on error. The size of the
7550 returned buffer is written to *size_r. The caller must free the
7551 returned buffer after use.
7552 Because of the message protocol, there is a transfer limit of somewhere
7554 between 2MB and 4MB. See "PROTOCOL LIMITS".
7555 (Added in 1.0.84)
7557 guestfs_initrd_list
7559 char **
7560 guestfs_initrd_list (guestfs_h *g,
7561 const char *path);
7562 This command lists out files contained in an initrd.
7564 The files are listed without any initial / character. The files are
7566 listed in the order they appear (not necessarily alphabetical).
7567 Directory names are listed as separate items.
7568 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7570 as initrd. We only support the newer initramfs format (compressed cpio
7571 files).
7572 This function returns a NULL-terminated array of strings (like
7574 environ(3)), or NULL if there was an error. The caller must free the
7575 strings and the array after use.
7576 (Added in 1.0.54)
7578 guestfs_inotify_add_watch
7580 int64_t
7581 guestfs_inotify_add_watch (guestfs_h *g,
7582 const char *path,
7583 int mask);
7584 Watch "path" for the events listed in "mask".
7586 Note that if "path" is a directory then events within that directory
7588 are watched, but this does not happen recursively (in subdirectories).
7589 Note for non-C or non-Linux callers: the inotify events are defined by
7591 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7592 On error this function returns -1.
7594 This function depends on the feature "inotify". See also
7596 "guestfs_feature_available".
7597 (Added in 1.0.66)
7599 guestfs_inotify_close
7601 int
7602 guestfs_inotify_close (guestfs_h *g);
7603 This closes the inotify handle which was previously opened by
7605 inotify_init. It removes all watches, throws away any pending events,
7606 and deallocates all resources.
7607 This function returns 0 on success or -1 on error.
7609 This function depends on the feature "inotify". See also
7611 "guestfs_feature_available".
7612 (Added in 1.0.66)
7614 guestfs_inotify_files
7616 char **
7617 guestfs_inotify_files (guestfs_h *g);
7618 This function is a helpful wrapper around "guestfs_inotify_read" which
7620 just returns a list of pathnames of objects that were touched. The
7621 returned pathnames are sorted and deduplicated.
7622 This function returns a NULL-terminated array of strings (like
7624 environ(3)), or NULL if there was an error. The caller must free the
7625 strings and the array after use.
7626 This function depends on the feature "inotify". See also
7628 "guestfs_feature_available".
7629 (Added in 1.0.66)
7631 guestfs_inotify_init
7633 int
7634 guestfs_inotify_init (guestfs_h *g,
7635 int maxevents);
7636 This command creates a new inotify handle. The inotify subsystem can
7638 be used to notify events which happen to objects in the guest
7639 filesystem.
7640 "maxevents" is the maximum number of events which will be queued up
7642 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7643 this is passed as 0, then the kernel (or previously set) default is
7644 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7645 limit, the kernel throws away events, but records the fact that it
7646 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7647 structure list (see "guestfs_inotify_read").
7648 Before any events are generated, you have to add some watches to the
7650 internal watch list. See: "guestfs_inotify_add_watch" and
7651 "guestfs_inotify_rm_watch".
7652 Queued up events should be read periodically by calling
7654 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7655 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7656 events out often enough then you risk the internal queue overflowing.
7657 The handle should be closed after use by calling
7659 "guestfs_inotify_close". This also removes any watches automatically.
7660 See also inotify(7) for an overview of the inotify interface as exposed
7662 by the Linux kernel, which is roughly what we expose via libguestfs.
7663 Note that there is one global inotify handle per libguestfs instance.
7664 This function returns 0 on success or -1 on error.
7666 This function depends on the feature "inotify". See also
7668 "guestfs_feature_available".
7669 (Added in 1.0.66)
7671 guestfs_inotify_read
7673 struct guestfs_inotify_event_list *
7674 guestfs_inotify_read (guestfs_h *g);
7675 Return the complete queue of events that have happened since the
7677 previous read call.
7678 If no events have happened, this returns an empty list.
7680 Note: In order to make sure that all events have been read, you must
7682 call this function repeatedly until it returns an empty list. The
7683 reason is that the call will read events up to the maximum appliance-
7684 to-host message size and leave remaining events in the queue.
7685 This function returns a "struct guestfs_inotify_event_list *", or NULL
7687 if there was an error. The caller must call
7688 "guestfs_free_inotify_event_list" after use.
7689 This function depends on the feature "inotify". See also
7691 "guestfs_feature_available".
7692 (Added in 1.0.66)
7694 guestfs_inotify_rm_watch
7696 int
7697 guestfs_inotify_rm_watch (guestfs_h *g,
7698 int wd);
7699 Remove a previously defined inotify watch. See
7701 "guestfs_inotify_add_watch".
7702 This function returns 0 on success or -1 on error.
7704 This function depends on the feature "inotify". See also
7706 "guestfs_feature_available".
7707 (Added in 1.0.66)
7709 guestfs_inspect_get_arch
7711 char *
7712 guestfs_inspect_get_arch (guestfs_h *g,
7713 const char *root);
7714 This returns the architecture of the inspected operating system. The
7716 possible return values are listed under "guestfs_file_architecture".
7717 If the architecture could not be determined, then the string "unknown"
7719 is returned.
7720 Please read "INSPECTION" for more details.
7722 This function returns a string, or NULL on error. The caller must free
7724 the returned string after use.
7725 (Added in 1.5.3)
7727 guestfs_inspect_get_build_id
7729 char *
7730 guestfs_inspect_get_build_id (guestfs_h *g,
7731 const char *root);
7732 This returns the build ID of the system, or the string "unknown" if the
7734 system does not have a build ID.
7735 For Windows, this gets the build number. Although it is returned as a
7737 string, it is (so far) always a number. See
7738 https://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions for
7739 some possible values.
7740 For Linux, this returns the "BUILD_ID" string from /etc/os-release,
7742 although this is not often used.
7743 Please read "INSPECTION" for more details.
7745 This function returns a string, or NULL on error. The caller must free
7747 the returned string after use.
7748 (Added in 1.49.8)
7750 guestfs_inspect_get_distro
7752 char *
7753 guestfs_inspect_get_distro (guestfs_h *g,
7754 const char *root);
7755 This returns the distro (distribution) of the inspected operating
7757 system.
7758 Currently defined distros are:
7760 "alpinelinux"
7762 Alpine Linux.
7763 "altlinux"
7765 ALT Linux.
7766 "archlinux"
7768 Arch Linux.
7769 "buildroot"
7771 Buildroot-derived distro, but not one we specifically recognize.
7772 "centos"
7774 CentOS.
7775 "cirros"
7777 Cirros.
7778 "coreos"
7780 CoreOS.
7781 "debian"
7783 Debian.
7784 "fedora"
7786 Fedora.
7787 "freebsd"
7789 FreeBSD.
7790 "freedos"
7792 FreeDOS.
7793 "frugalware"
7795 Frugalware.
7796 "gentoo"
7798 Gentoo.
7799 "kalilinux"
7801 Kali Linux.
7802 "kylin"
7804 Kylin.
7805 "linuxmint"
7807 Linux Mint.
7808 "mageia"
7810 Mageia.
7811 "mandriva"
7813 Mandriva.
7814 "meego"
7816 MeeGo.
7817 "msdos"
7819 Microsoft DOS.
7820 "neokylin"
7822 NeoKylin.
7823 "netbsd"
7825 NetBSD.
7826 "openbsd"
7828 OpenBSD.
7829 "openmandriva"
7831 OpenMandriva Lx.
7832 "opensuse"
7834 OpenSUSE.
7835 "oraclelinux"
7837 Oracle Linux.
7838 "pardus"
7840 Pardus.
7841 "pldlinux"
7843 PLD Linux.
7844 "redhat-based"
7846 Some Red Hat-derived distro.
7847 "rhel"
7849 Red Hat Enterprise Linux.
7850 "rocky"
7852 Rocky Linux.
7853 "scientificlinux"
7855 Scientific Linux.
7856 "slackware"
7858 Slackware.
7859 "sles"
7861 SuSE Linux Enterprise Server or Desktop.
7862 "suse-based"
7864 Some openSuSE-derived distro.
7865 "ttylinux"
7867 ttylinux.
7868 "ubuntu"
7870 Ubuntu.
7871 "unknown"
7873 The distro could not be determined.
7874 "voidlinux"
7876 Void Linux.
7877 "windows"
7879 Windows does not have distributions. This string is returned if
7880 the OS type is Windows.
7881 Future versions of libguestfs may return other strings here. The
7883 caller should be prepared to handle any string.
7884 Please read "INSPECTION" for more details.
7886 This function returns a string, or NULL on error. The caller must free
7888 the returned string after use.
7889 (Added in 1.5.3)
7891 guestfs_inspect_get_drive_mappings
7893 char **
7894 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7895 const char *root);
7896 This call is useful for Windows which uses a primitive system of
7898 assigning drive letters (like C:\) to partitions. This inspection API
7899 examines the Windows Registry to find out how disks/partitions are
7900 mapped to drive letters, and returns a hash table as in the example
7901 below:
7902 C => /dev/vda2
7904 E => /dev/vdb1
7905 F => /dev/vdc1
7906 Note that keys are drive letters. For Windows, the key is case
7908 insensitive and just contains the drive letter, without the customary
7909 colon separator character.
7910 In future we may support other operating systems that also used drive
7912 letters, but the keys for those might not be case insensitive and might
7913 be longer than 1 character. For example in OS-9, hard drives were
7914 named "h0", "h1" etc.
7915 For Windows guests, currently only hard drive mappings are returned.
7917 Removable disks (eg. DVD-ROMs) are ignored.
7918 For guests that do not use drive mappings, or if the drive mappings
7920 could not be determined, this returns an empty hash table.
7921 Please read "INSPECTION" for more details. See also
7923 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7924 This function returns a NULL-terminated array of strings, or NULL if
7926 there was an error. The array of strings will always have length
7927 "2n+1", where "n" keys and values alternate, followed by the trailing
7928 NULL entry. The caller must free the strings and the array after use.
7929 (Added in 1.9.17)
7931 guestfs_inspect_get_filesystems
7933 char **
7934 guestfs_inspect_get_filesystems (guestfs_h *g,
7935 const char *root);
7936 This returns a list of all the filesystems that we think are associated
7938 with this operating system. This includes the root filesystem, other
7939 ordinary filesystems, and non-mounted devices like swap partitions.
7940 In the case of a multi-boot virtual machine, it is possible for a
7942 filesystem to be shared between operating systems.
7943 Please read "INSPECTION" for more details. See also
7945 "guestfs_inspect_get_mountpoints".
7946 This function returns a NULL-terminated array of strings (like
7948 environ(3)), or NULL if there was an error. The caller must free the
7949 strings and the array after use.
7950 (Added in 1.5.3)
7952 guestfs_inspect_get_format
7954 char *
7955 guestfs_inspect_get_format (guestfs_h *g,
7956 const char *root);
7957 This function is deprecated. There is no replacement. Consult the API
7959 documentation in guestfs(3) for further information.
7960 Deprecated functions will not be removed from the API, but the fact
7962 that they are deprecated indicates that there are problems with correct
7963 use of these functions.
7964 Before libguestfs 1.38, there was some unreliable support for detecting
7966 installer CDs. This API would return:
7967 "installed"
7969 This is an installed operating system.
7970 "installer"
7972 The disk image being inspected is not an installed operating
7973 system, but a bootable install disk, live CD, or similar.
7974 "unknown"
7976 The format of this disk image is not known.
7977 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
7979 directly to detect installer CDs.
7980 Please read "INSPECTION" for more details.
7982 This function returns a string, or NULL on error. The caller must free
7984 the returned string after use.
7985 (Added in 1.9.4)
7987 guestfs_inspect_get_hostname
7989 char *
7990 guestfs_inspect_get_hostname (guestfs_h *g,
7991 const char *root);
7992 This function returns the hostname of the operating system as found by
7994 inspection of the guest’s configuration files.
7995 If the hostname could not be determined, then the string "unknown" is
7997 returned.
7998 Please read "INSPECTION" for more details.
8000 This function returns a string, or NULL on error. The caller must free
8002 the returned string after use.
8003 (Added in 1.7.9)
8005 guestfs_inspect_get_icon
8007 char *
8008 guestfs_inspect_get_icon (guestfs_h *g,
8009 const char *root,
8010 size_t *size_r,
8011 ...);
8012 You may supply a list of optional arguments to this call. Use zero or
8014 more of the following pairs of parameters, and terminate the list with
8015 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8016 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
8018 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
8019 This function returns an icon corresponding to the inspected operating
8021 system. The icon is returned as a buffer containing a PNG image (re-
8022 encoded to PNG if necessary).
8023 If it was not possible to get an icon this function returns a zero-
8025 length (non-NULL) buffer. Callers must check for this case.
8026 Libguestfs will start by looking for a file called /etc/favicon.png or
8028 C:\etc\favicon.png and if it has the correct format, the contents of
8029 this file will be returned. You can disable favicons by passing the
8030 optional "favicon" boolean as false (default is true).
8031 If finding the favicon fails, then we look in other places in the guest
8033 for a suitable icon.
8034 If the optional "highquality" boolean is true then only high quality
8036 icons are returned, which means only icons of high resolution with an
8037 alpha channel. The default (false) is to return any icon we can, even
8038 if it is of substandard quality.
8039 Notes:
8041 • Unlike most other inspection API calls, the guest’s disks must be
8043 mounted up before you call this, since it needs to read information
8044 from the guest filesystem during the call.
8045 • Security: The icon data comes from the untrusted guest, and should
8047 be treated with caution. PNG files have been known to contain
8048 exploits. Ensure that libpng (or other relevant libraries) are
8049 fully up to date before trying to process or display the icon.
8050 • The PNG image returned can be any size. It might not be square.
8052 Libguestfs tries to return the largest, highest quality icon
8053 available. The application must scale the icon to the required
8054 size.
8055 • Extracting icons from Windows guests requires the external
8057 wrestool(1) program from the "icoutils" package, and several
8058 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
8059 package. These must be installed separately.
8060 • Operating system icons are usually trademarks. Seek legal advice
8062 before using trademarks in applications.
8063 This function returns a buffer, or NULL on error. The size of the
8065 returned buffer is written to *size_r. The caller must free the
8066 returned buffer after use.
8067 (Added in 1.11.12)
8069 guestfs_inspect_get_icon_va
8071 char *
8072 guestfs_inspect_get_icon_va (guestfs_h *g,
8073 const char *root,
8074 size_t *size_r,
8075 va_list args);
8076 This is the "va_list variant" of "guestfs_inspect_get_icon".
8078 See "CALLS WITH OPTIONAL ARGUMENTS".
8080 guestfs_inspect_get_icon_argv
8082 char *
8083 guestfs_inspect_get_icon_argv (guestfs_h *g,
8084 const char *root,
8085 size_t *size_r,
8086 const struct guestfs_inspect_get_icon_argv *optargs);
8087 This is the "argv variant" of "guestfs_inspect_get_icon".
8089 See "CALLS WITH OPTIONAL ARGUMENTS".
8091 guestfs_inspect_get_major_version
8093 int
8094 guestfs_inspect_get_major_version (guestfs_h *g,
8095 const char *root);
8096 This returns the major version number of the inspected operating
8098 system.
8099 Windows uses a consistent versioning scheme which is not reflected in
8101 the popular public names used by the operating system. Notably the
8102 operating system known as "Windows 7" is really version 6.1 (ie. major
8103 = 6, minor = 1). You can find out the real versions corresponding to
8104 releases of Windows by consulting Wikipedia or MSDN.
8105 If the version could not be determined, then 0 is returned.
8107 Please read "INSPECTION" for more details.
8109 On error this function returns -1.
8111 (Added in 1.5.3)
8113 guestfs_inspect_get_minor_version
8115 int
8116 guestfs_inspect_get_minor_version (guestfs_h *g,
8117 const char *root);
8118 This returns the minor version number of the inspected operating
8120 system.
8121 If the version could not be determined, then 0 is returned.
8123 Please read "INSPECTION" for more details. See also
8125 "guestfs_inspect_get_major_version".
8126 On error this function returns -1.
8128 (Added in 1.5.3)
8130 guestfs_inspect_get_mountpoints
8132 char **
8133 guestfs_inspect_get_mountpoints (guestfs_h *g,
8134 const char *root);
8135 This returns a hash of where we think the filesystems associated with
8137 this operating system should be mounted. Callers should note that this
8138 is at best an educated guess made by reading configuration files such
8139 as /etc/fstab. In particular note that this may return filesystems
8140 which are non-existent or not mountable and callers should be prepared
8141 to handle or ignore failures if they try to mount them.
8142 Each element in the returned hashtable has a key which is the path of
8144 the mountpoint (eg. /boot) and a value which is the filesystem that
8145 would be mounted there (eg. /dev/sda1).
8146 Non-mounted devices such as swap devices are not returned in this list.
8148 For operating systems like Windows which still use drive letters, this
8150 call will only return an entry for the first drive "mounted on" /. For
8151 information about the mapping of drive letters to partitions, see
8152 "guestfs_inspect_get_drive_mappings".
8153 Please read "INSPECTION" for more details. See also
8155 "guestfs_inspect_get_filesystems".
8156 This function returns a NULL-terminated array of strings, or NULL if
8158 there was an error. The array of strings will always have length
8159 "2n+1", where "n" keys and values alternate, followed by the trailing
8160 NULL entry. The caller must free the strings and the array after use.
8161 (Added in 1.5.3)
8163 guestfs_inspect_get_osinfo
8165 char *
8166 guestfs_inspect_get_osinfo (guestfs_h *g,
8167 const char *root);
8168 This function returns a possible short ID for libosinfo corresponding
8170 to the guest.
8171 Note: The returned ID is only a guess by libguestfs, and nothing
8173 ensures that it actually exists in osinfo-db.
8174 If no ID could not be determined, then the string "unknown" is
8176 returned.
8177 This function returns a string, or NULL on error. The caller must free
8179 the returned string after use.
8180 (Added in 1.39.1)
8182 guestfs_inspect_get_package_format
8184 char *
8185 guestfs_inspect_get_package_format (guestfs_h *g,
8186 const char *root);
8187 This function and "guestfs_inspect_get_package_management" return the
8189 package format and package management tool used by the inspected
8190 operating system. For example for Fedora these functions would return
8191 "rpm" (package format), and "yum" or "dnf" (package management).
8192 This returns the string "unknown" if we could not determine the package
8194 format or if the operating system does not have a real packaging system
8195 (eg. Windows).
8196 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8198 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
8199 other strings.
8200 Please read "INSPECTION" for more details.
8202 This function returns a string, or NULL on error. The caller must free
8204 the returned string after use.
8205 (Added in 1.7.5)
8207 guestfs_inspect_get_package_management
8209 char *
8210 guestfs_inspect_get_package_management (guestfs_h *g,
8211 const char *root);
8212 "guestfs_inspect_get_package_format" and this function return the
8214 package format and package management tool used by the inspected
8215 operating system. For example for Fedora these functions would return
8216 "rpm" (package format), and "yum" or "dnf" (package management).
8217 This returns the string "unknown" if we could not determine the package
8219 management tool or if the operating system does not have a real
8220 packaging system (eg. Windows).
8221 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8223 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8224 "apk", "xbps". Future versions of libguestfs may return other strings.
8225 Please read "INSPECTION" for more details.
8227 This function returns a string, or NULL on error. The caller must free
8229 the returned string after use.
8230 (Added in 1.7.5)
8232 guestfs_inspect_get_product_name
8234 char *
8235 guestfs_inspect_get_product_name (guestfs_h *g,
8236 const char *root);
8237 This returns the product name of the inspected operating system. The
8239 product name is generally some freeform string which can be displayed
8240 to the user, but should not be parsed by programs.
8241 If the product name could not be determined, then the string "unknown"
8243 is returned.
8244 Please read "INSPECTION" for more details.
8246 This function returns a string, or NULL on error. The caller must free
8248 the returned string after use.
8249 (Added in 1.5.3)
8251 guestfs_inspect_get_product_variant
8253 char *
8254 guestfs_inspect_get_product_variant (guestfs_h *g,
8255 const char *root);
8256 This returns the product variant of the inspected operating system.
8258 For Windows guests, this returns the contents of the Registry key
8260 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8261 which is usually a string such as "Client" or "Server" (other values
8262 are possible). This can be used to distinguish consumer and enterprise
8263 versions of Windows that have the same version number (for example,
8264 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8265 is "Client" and the latter is "Server").
8266 For enterprise Linux guests, in future we intend this to return the
8268 product variant such as "Desktop", "Server" and so on. But this is not
8269 implemented at present.
8270 If the product variant could not be determined, then the string
8272 "unknown" is returned.
8273 Please read "INSPECTION" for more details. See also
8275 "guestfs_inspect_get_product_name",
8276 "guestfs_inspect_get_major_version".
8277 This function returns a string, or NULL on error. The caller must free
8279 the returned string after use.
8280 (Added in 1.9.13)
8282 guestfs_inspect_get_roots
8284 char **
8285 guestfs_inspect_get_roots (guestfs_h *g);
8286 This function is a convenient way to get the list of root devices, as
8288 returned from a previous call to "guestfs_inspect_os", but without
8289 redoing the whole inspection process.
8290 This returns an empty list if either no root devices were found or the
8292 caller has not called "guestfs_inspect_os".
8293 Please read "INSPECTION" for more details.
8295 This function returns a NULL-terminated array of strings (like
8297 environ(3)), or NULL if there was an error. The caller must free the
8298 strings and the array after use.
8299 (Added in 1.7.3)
8301 guestfs_inspect_get_type
8303 char *
8304 guestfs_inspect_get_type (guestfs_h *g,
8305 const char *root);
8306 This returns the type of the inspected operating system. Currently
8308 defined types are:
8309 "linux"
8311 Any Linux-based operating system.
8312 "windows"
8314 Any Microsoft Windows operating system.
8315 "freebsd"
8317 FreeBSD.
8318 "netbsd"
8320 NetBSD.
8321 "openbsd"
8323 OpenBSD.
8324 "hurd"
8326 GNU/Hurd.
8327 "dos"
8329 MS-DOS, FreeDOS and others.
8330 "minix"
8332 MINIX.
8333 "unknown"
8335 The operating system type could not be determined.
8336 Future versions of libguestfs may return other strings here. The
8338 caller should be prepared to handle any string.
8339 Please read "INSPECTION" for more details.
8341 This function returns a string, or NULL on error. The caller must free
8343 the returned string after use.
8344 (Added in 1.5.3)
8346 guestfs_inspect_get_windows_current_control_set
8348 char *
8349 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8350 const char *root);
8351 This returns the Windows CurrentControlSet of the inspected guest. The
8353 CurrentControlSet is a registry key name such as "ControlSet001".
8354 This call assumes that the guest is Windows and that the Registry could
8356 be examined by inspection. If this is not the case then an error is
8357 returned.
8358 Please read "INSPECTION" for more details.
8360 This function returns a string, or NULL on error. The caller must free
8362 the returned string after use.
8363 (Added in 1.9.17)
8365 guestfs_inspect_get_windows_software_hive
8367 char *
8368 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8369 const char *root);
8370 This returns the path to the hive (binary Windows Registry file)
8372 corresponding to HKLM\SOFTWARE.
8373 This call assumes that the guest is Windows and that the guest has a
8375 software hive file with the right name. If this is not the case then
8376 an error is returned. This call does not check that the hive is a
8377 valid Windows Registry hive.
8378 You can use "guestfs_hivex_open" to read or write to the hive.
8380 Please read "INSPECTION" for more details.
8382 This function returns a string, or NULL on error. The caller must free
8384 the returned string after use.
8385 (Added in 1.35.26)
8387 guestfs_inspect_get_windows_system_hive
8389 char *
8390 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8391 const char *root);
8392 This returns the path to the hive (binary Windows Registry file)
8394 corresponding to HKLM\SYSTEM.
8395 This call assumes that the guest is Windows and that the guest has a
8397 system hive file with the right name. If this is not the case then an
8398 error is returned. This call does not check that the hive is a valid
8399 Windows Registry hive.
8400 You can use "guestfs_hivex_open" to read or write to the hive.
8402 Please read "INSPECTION" for more details.
8404 This function returns a string, or NULL on error. The caller must free
8406 the returned string after use.
8407 (Added in 1.35.26)
8409 guestfs_inspect_get_windows_systemroot
8411 char *
8412 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8413 const char *root);
8414 This returns the Windows systemroot of the inspected guest. The
8416 systemroot is a directory path such as /WINDOWS.
8417 This call assumes that the guest is Windows and that the systemroot
8419 could be determined by inspection. If this is not the case then an
8420 error is returned.
8421 Please read "INSPECTION" for more details.
8423 This function returns a string, or NULL on error. The caller must free
8425 the returned string after use.
8426 (Added in 1.5.25)
8428 guestfs_inspect_is_live
8430 int
8431 guestfs_inspect_is_live (guestfs_h *g,
8432 const char *root);
8433 This function is deprecated. There is no replacement. Consult the API
8435 documentation in guestfs(3) for further information.
8436 Deprecated functions will not be removed from the API, but the fact
8438 that they are deprecated indicates that there are problems with correct
8439 use of these functions.
8440 This is deprecated and always returns "false".
8442 Please read "INSPECTION" for more details.
8444 This function returns a C truth value on success or -1 on error.
8446 (Added in 1.9.4)
8448 guestfs_inspect_is_multipart
8450 int
8451 guestfs_inspect_is_multipart (guestfs_h *g,
8452 const char *root);
8453 This function is deprecated. There is no replacement. Consult the API
8455 documentation in guestfs(3) for further information.
8456 Deprecated functions will not be removed from the API, but the fact
8458 that they are deprecated indicates that there are problems with correct
8459 use of these functions.
8460 This is deprecated and always returns "false".
8462 Please read "INSPECTION" for more details.
8464 This function returns a C truth value on success or -1 on error.
8466 (Added in 1.9.4)
8468 guestfs_inspect_is_netinst
8470 int
8471 guestfs_inspect_is_netinst (guestfs_h *g,
8472 const char *root);
8473 This function is deprecated. There is no replacement. Consult the API
8475 documentation in guestfs(3) for further information.
8476 Deprecated functions will not be removed from the API, but the fact
8478 that they are deprecated indicates that there are problems with correct
8479 use of these functions.
8480 This is deprecated and always returns "false".
8482 Please read "INSPECTION" for more details.
8484 This function returns a C truth value on success or -1 on error.
8486 (Added in 1.9.4)
8488 guestfs_inspect_list_applications
8490 struct guestfs_application_list *
8491 guestfs_inspect_list_applications (guestfs_h *g,
8492 const char *root);
8493 This function is deprecated. In new code, use the
8495 "guestfs_inspect_list_applications2" call instead.
8496 Deprecated functions will not be removed from the API, but the fact
8498 that they are deprecated indicates that there are problems with correct
8499 use of these functions.
8500 Return the list of applications installed in the operating system.
8502 Note: This call works differently from other parts of the inspection
8504 API. You have to call "guestfs_inspect_os", then
8505 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8506 calling this. Listing applications is a significantly more difficult
8507 operation which requires access to the full filesystem. Also note that
8508 unlike the other "guestfs_inspect_get_*" calls which are just returning
8509 data cached in the libguestfs handle, this call actually reads parts of
8510 the mounted filesystems during the call.
8511 This returns an empty list if the inspection code was not able to
8513 determine the list of applications.
8514 The application structure contains the following fields:
8516 "app_name"
8518 The name of the application. For Linux guests, this is the package
8519 name.
8520 "app_display_name"
8522 The display name of the application, sometimes localized to the
8523 install language of the guest operating system.
8524 If unavailable this is returned as an empty string "". Callers
8526 needing to display something can use "app_name" instead.
8527 "app_epoch"
8529 For package managers which use epochs, this contains the epoch of
8530 the package (an integer). If unavailable, this is returned as 0.
8531 "app_version"
8533 The version string of the application or package. If unavailable
8534 this is returned as an empty string "".
8535 "app_release"
8537 The release string of the application or package, for package
8538 managers that use this. If unavailable this is returned as an
8539 empty string "".
8540 "app_install_path"
8542 The installation path of the application (on operating systems such
8543 as Windows which use installation paths). This path is in the
8544 format used by the guest operating system, it is not a libguestfs
8545 path.
8546 If unavailable this is returned as an empty string "".
8548 "app_trans_path"
8550 The install path translated into a libguestfs path. If unavailable
8551 this is returned as an empty string "".
8552 "app_publisher"
8554 The name of the publisher of the application, for package managers
8555 that use this. If unavailable this is returned as an empty string
8556 "".
8557 "app_url"
8559 The URL (eg. upstream URL) of the application. If unavailable this
8560 is returned as an empty string "".
8561 "app_source_package"
8563 For packaging systems which support this, the name of the source
8564 package. If unavailable this is returned as an empty string "".
8565 "app_summary"
8567 A short (usually one line) description of the application or
8568 package. If unavailable this is returned as an empty string "".
8569 "app_description"
8571 A longer description of the application or package. If unavailable
8572 this is returned as an empty string "".
8573 Please read "INSPECTION" for more details.
8575 This function returns a "struct guestfs_application_list *", or NULL if
8577 there was an error. The caller must call
8578 "guestfs_free_application_list" after use.
8579 (Added in 1.7.8)
8581 guestfs_inspect_list_applications2
8583 struct guestfs_application2_list *
8584 guestfs_inspect_list_applications2 (guestfs_h *g,
8585 const char *root);
8586 Return the list of applications installed in the operating system.
8588 Note: This call works differently from other parts of the inspection
8590 API. You have to call "guestfs_inspect_os", then
8591 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8592 calling this. Listing applications is a significantly more difficult
8593 operation which requires access to the full filesystem. Also note that
8594 unlike the other "guestfs_inspect_get_*" calls which are just returning
8595 data cached in the libguestfs handle, this call actually reads parts of
8596 the mounted filesystems during the call.
8597 This returns an empty list if the inspection code was not able to
8599 determine the list of applications.
8600 The application structure contains the following fields:
8602 "app2_name"
8604 The name of the application. For Linux guests, this is the package
8605 name.
8606 "app2_display_name"
8608 The display name of the application, sometimes localized to the
8609 install language of the guest operating system.
8610 If unavailable this is returned as an empty string "". Callers
8612 needing to display something can use "app2_name" instead.
8613 "app2_epoch"
8615 For package managers which use epochs, this contains the epoch of
8616 the package (an integer). If unavailable, this is returned as 0.
8617 "app2_version"
8619 The version string of the application or package. If unavailable
8620 this is returned as an empty string "".
8621 "app2_release"
8623 The release string of the application or package, for package
8624 managers that use this. If unavailable this is returned as an
8625 empty string "".
8626 "app2_arch"
8628 The architecture string of the application or package, for package
8629 managers that use this. If unavailable this is returned as an
8630 empty string "".
8631 "app2_install_path"
8633 The installation path of the application (on operating systems such
8634 as Windows which use installation paths). This path is in the
8635 format used by the guest operating system, it is not a libguestfs
8636 path.
8637 If unavailable this is returned as an empty string "".
8639 "app2_trans_path"
8641 The install path translated into a libguestfs path. If unavailable
8642 this is returned as an empty string "".
8643 "app2_publisher"
8645 The name of the publisher of the application, for package managers
8646 that use this. If unavailable this is returned as an empty string
8647 "".
8648 "app2_url"
8650 The URL (eg. upstream URL) of the application. If unavailable this
8651 is returned as an empty string "".
8652 "app2_source_package"
8654 For packaging systems which support this, the name of the source
8655 package. If unavailable this is returned as an empty string "".
8656 "app2_summary"
8658 A short (usually one line) description of the application or
8659 package. If unavailable this is returned as an empty string "".
8660 "app2_description"
8662 A longer description of the application or package. If unavailable
8663 this is returned as an empty string "".
8664 Please read "INSPECTION" for more details.
8666 This function returns a "struct guestfs_application2_list *", or NULL
8668 if there was an error. The caller must call
8669 "guestfs_free_application2_list" after use.
8670 (Added in 1.19.56)
8672 guestfs_inspect_os
8674 char **
8675 guestfs_inspect_os (guestfs_h *g);
8676 This function uses other libguestfs functions and certain heuristics to
8678 inspect the disk(s) (usually disks belonging to a virtual machine),
8679 looking for operating systems.
8680 The list returned is empty if no operating systems were found.
8682 If one operating system was found, then this returns a list with a
8684 single element, which is the name of the root filesystem of this
8685 operating system. It is also possible for this function to return a
8686 list containing more than one element, indicating a dual-boot or multi-
8687 boot virtual machine, with each element being the root filesystem of
8688 one of the operating systems.
8689 You can pass the root string(s) returned to other
8691 "guestfs_inspect_get_*" functions in order to query further information
8692 about each operating system, such as the name and version.
8693 This function uses other libguestfs features such as "guestfs_mount_ro"
8695 and "guestfs_umount_all" in order to mount and unmount filesystems and
8696 look at the contents. This should be called with no disks currently
8697 mounted. The function may also use Augeas, so any existing Augeas
8698 handle will be closed.
8699 This function cannot decrypt encrypted disks. The caller must do that
8701 first (supplying the necessary keys) if the disk is encrypted.
8702 Please read "INSPECTION" for more details.
8704 See also "guestfs_list_filesystems".
8706 This function returns a NULL-terminated array of strings (like
8708 environ(3)), or NULL if there was an error. The caller must free the
8709 strings and the array after use.
8710 (Added in 1.5.3)
8712 guestfs_is_blockdev
8714 int
8715 guestfs_is_blockdev (guestfs_h *g,
8716 const char *path);
8717 This function is provided for backwards compatibility with earlier
8719 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8720 with no optional arguments.
8721 (Added in 1.5.10)
8723 guestfs_is_blockdev_opts
8725 int
8726 guestfs_is_blockdev_opts (guestfs_h *g,
8727 const char *path,
8728 ...);
8729 You may supply a list of optional arguments to this call. Use zero or
8731 more of the following pairs of parameters, and terminate the list with
8732 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8733 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8735 This returns "true" if and only if there is a block device with the
8737 given "path" name.
8738 If the optional flag "followsymlinks" is true, then a symlink (or chain
8740 of symlinks) that ends with a block device also causes the function to
8741 return true.
8742 This call only looks at files within the guest filesystem. Libguestfs
8744 partitions and block devices (eg. /dev/sda) cannot be used as the
8745 "path" parameter of this call.
8746 See also "guestfs_stat".
8748 This function returns a C truth value on success or -1 on error.
8750 (Added in 1.5.10)
8752 guestfs_is_blockdev_opts_va
8754 int
8755 guestfs_is_blockdev_opts_va (guestfs_h *g,
8756 const char *path,
8757 va_list args);
8758 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8760 See "CALLS WITH OPTIONAL ARGUMENTS".
8762 guestfs_is_blockdev_opts_argv
8764 int
8765 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8766 const char *path,
8767 const struct guestfs_is_blockdev_opts_argv *optargs);
8768 This is the "argv variant" of "guestfs_is_blockdev_opts".
8770 See "CALLS WITH OPTIONAL ARGUMENTS".
8772 guestfs_is_busy
8774 int
8775 guestfs_is_busy (guestfs_h *g);
8776 This always returns false. This function is deprecated with no
8778 replacement. Do not use this function.
8779 For more information on states, see guestfs(3).
8781 This function returns a C truth value on success or -1 on error.
8783 (Added in 1.0.2)
8785 guestfs_is_chardev
8787 int
8788 guestfs_is_chardev (guestfs_h *g,
8789 const char *path);
8790 This function is provided for backwards compatibility with earlier
8792 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8793 no optional arguments.
8794 (Added in 1.5.10)
8796 guestfs_is_chardev_opts
8798 int
8799 guestfs_is_chardev_opts (guestfs_h *g,
8800 const char *path,
8801 ...);
8802 You may supply a list of optional arguments to this call. Use zero or
8804 more of the following pairs of parameters, and terminate the list with
8805 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8806 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8808 This returns "true" if and only if there is a character device with the
8810 given "path" name.
8811 If the optional flag "followsymlinks" is true, then a symlink (or chain
8813 of symlinks) that ends with a chardev also causes the function to
8814 return true.
8815 See also "guestfs_stat".
8817 This function returns a C truth value on success or -1 on error.
8819 (Added in 1.5.10)
8821 guestfs_is_chardev_opts_va
8823 int
8824 guestfs_is_chardev_opts_va (guestfs_h *g,
8825 const char *path,
8826 va_list args);
8827 This is the "va_list variant" of "guestfs_is_chardev_opts".
8829 See "CALLS WITH OPTIONAL ARGUMENTS".
8831 guestfs_is_chardev_opts_argv
8833 int
8834 guestfs_is_chardev_opts_argv (guestfs_h *g,
8835 const char *path,
8836 const struct guestfs_is_chardev_opts_argv *optargs);
8837 This is the "argv variant" of "guestfs_is_chardev_opts".
8839 See "CALLS WITH OPTIONAL ARGUMENTS".
8841 guestfs_is_config
8843 int
8844 guestfs_is_config (guestfs_h *g);
8845 This returns true iff this handle is being configured (in the "CONFIG"
8847 state).
8848 For more information on states, see guestfs(3).
8850 This function returns a C truth value on success or -1 on error.
8852 (Added in 1.0.2)
8854 guestfs_is_dir
8856 int
8857 guestfs_is_dir (guestfs_h *g,
8858 const char *path);
8859 This function is provided for backwards compatibility with earlier
8861 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8862 optional arguments.
8863 (Added in 0.8)
8865 guestfs_is_dir_opts
8867 int
8868 guestfs_is_dir_opts (guestfs_h *g,
8869 const char *path,
8870 ...);
8871 You may supply a list of optional arguments to this call. Use zero or
8873 more of the following pairs of parameters, and terminate the list with
8874 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8875 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8877 This returns "true" if and only if there is a directory with the given
8879 "path" name. Note that it returns false for other objects like files.
8880 If the optional flag "followsymlinks" is true, then a symlink (or chain
8882 of symlinks) that ends with a directory also causes the function to
8883 return true.
8884 See also "guestfs_stat".
8886 This function returns a C truth value on success or -1 on error.
8888 (Added in 0.8)
8890 guestfs_is_dir_opts_va
8892 int
8893 guestfs_is_dir_opts_va (guestfs_h *g,
8894 const char *path,
8895 va_list args);
8896 This is the "va_list variant" of "guestfs_is_dir_opts".
8898 See "CALLS WITH OPTIONAL ARGUMENTS".
8900 guestfs_is_dir_opts_argv
8902 int
8903 guestfs_is_dir_opts_argv (guestfs_h *g,
8904 const char *path,
8905 const struct guestfs_is_dir_opts_argv *optargs);
8906 This is the "argv variant" of "guestfs_is_dir_opts".
8908 See "CALLS WITH OPTIONAL ARGUMENTS".
8910 guestfs_is_fifo
8912 int
8913 guestfs_is_fifo (guestfs_h *g,
8914 const char *path);
8915 This function is provided for backwards compatibility with earlier
8917 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8918 optional arguments.
8919 (Added in 1.5.10)
8921 guestfs_is_fifo_opts
8923 int
8924 guestfs_is_fifo_opts (guestfs_h *g,
8925 const char *path,
8926 ...);
8927 You may supply a list of optional arguments to this call. Use zero or
8929 more of the following pairs of parameters, and terminate the list with
8930 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8931 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8933 This returns "true" if and only if there is a FIFO (named pipe) with
8935 the given "path" name.
8936 If the optional flag "followsymlinks" is true, then a symlink (or chain
8938 of symlinks) that ends with a FIFO also causes the function to return
8939 true.
8940 See also "guestfs_stat".
8942 This function returns a C truth value on success or -1 on error.
8944 (Added in 1.5.10)
8946 guestfs_is_fifo_opts_va
8948 int
8949 guestfs_is_fifo_opts_va (guestfs_h *g,
8950 const char *path,
8951 va_list args);
8952 This is the "va_list variant" of "guestfs_is_fifo_opts".
8954 See "CALLS WITH OPTIONAL ARGUMENTS".
8956 guestfs_is_fifo_opts_argv
8958 int
8959 guestfs_is_fifo_opts_argv (guestfs_h *g,
8960 const char *path,
8961 const struct guestfs_is_fifo_opts_argv *optargs);
8962 This is the "argv variant" of "guestfs_is_fifo_opts".
8964 See "CALLS WITH OPTIONAL ARGUMENTS".
8966 guestfs_is_file
8968 int
8969 guestfs_is_file (guestfs_h *g,
8970 const char *path);
8971 This function is provided for backwards compatibility with earlier
8973 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
8974 optional arguments.
8975 (Added in 0.8)
8977 guestfs_is_file_opts
8979 int
8980 guestfs_is_file_opts (guestfs_h *g,
8981 const char *path,
8982 ...);
8983 You may supply a list of optional arguments to this call. Use zero or
8985 more of the following pairs of parameters, and terminate the list with
8986 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8987 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8989 This returns "true" if and only if there is a regular file with the
8991 given "path" name. Note that it returns false for other objects like
8992 directories.
8993 If the optional flag "followsymlinks" is true, then a symlink (or chain
8995 of symlinks) that ends with a file also causes the function to return
8996 true.
8997 See also "guestfs_stat".
8999 This function returns a C truth value on success or -1 on error.
9001 (Added in 0.8)
9003 guestfs_is_file_opts_va
9005 int
9006 guestfs_is_file_opts_va (guestfs_h *g,
9007 const char *path,
9008 va_list args);
9009 This is the "va_list variant" of "guestfs_is_file_opts".
9011 See "CALLS WITH OPTIONAL ARGUMENTS".
9013 guestfs_is_file_opts_argv
9015 int
9016 guestfs_is_file_opts_argv (guestfs_h *g,
9017 const char *path,
9018 const struct guestfs_is_file_opts_argv *optargs);
9019 This is the "argv variant" of "guestfs_is_file_opts".
9021 See "CALLS WITH OPTIONAL ARGUMENTS".
9023 guestfs_is_launching
9025 int
9026 guestfs_is_launching (guestfs_h *g);
9027 This returns true iff this handle is launching the subprocess (in the
9029 "LAUNCHING" state).
9030 For more information on states, see guestfs(3).
9032 This function returns a C truth value on success or -1 on error.
9034 (Added in 1.0.2)
9036 guestfs_is_lv
9038 int
9039 guestfs_is_lv (guestfs_h *g,
9040 const char *mountable);
9041 This command tests whether "mountable" is a logical volume, and returns
9043 true iff this is the case.
9044 This function returns a C truth value on success or -1 on error.
9046 (Added in 1.5.3)
9048 guestfs_is_ready
9050 int
9051 guestfs_is_ready (guestfs_h *g);
9052 This returns true iff this handle is ready to accept commands (in the
9054 "READY" state).
9055 For more information on states, see guestfs(3).
9057 This function returns a C truth value on success or -1 on error.
9059 (Added in 1.0.2)
9061 guestfs_is_socket
9063 int
9064 guestfs_is_socket (guestfs_h *g,
9065 const char *path);
9066 This function is provided for backwards compatibility with earlier
9068 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
9069 no optional arguments.
9070 (Added in 1.5.10)
9072 guestfs_is_socket_opts
9074 int
9075 guestfs_is_socket_opts (guestfs_h *g,
9076 const char *path,
9077 ...);
9078 You may supply a list of optional arguments to this call. Use zero or
9080 more of the following pairs of parameters, and terminate the list with
9081 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9082 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9084 This returns "true" if and only if there is a Unix domain socket with
9086 the given "path" name.
9087 If the optional flag "followsymlinks" is true, then a symlink (or chain
9089 of symlinks) that ends with a socket also causes the function to return
9090 true.
9091 See also "guestfs_stat".
9093 This function returns a C truth value on success or -1 on error.
9095 (Added in 1.5.10)
9097 guestfs_is_socket_opts_va
9099 int
9100 guestfs_is_socket_opts_va (guestfs_h *g,
9101 const char *path,
9102 va_list args);
9103 This is the "va_list variant" of "guestfs_is_socket_opts".
9105 See "CALLS WITH OPTIONAL ARGUMENTS".
9107 guestfs_is_socket_opts_argv
9109 int
9110 guestfs_is_socket_opts_argv (guestfs_h *g,
9111 const char *path,
9112 const struct guestfs_is_socket_opts_argv *optargs);
9113 This is the "argv variant" of "guestfs_is_socket_opts".
9115 See "CALLS WITH OPTIONAL ARGUMENTS".
9117 guestfs_is_symlink
9119 int
9120 guestfs_is_symlink (guestfs_h *g,
9121 const char *path);
9122 This returns "true" if and only if there is a symbolic link with the
9124 given "path" name.
9125 See also "guestfs_stat".
9127 This function returns a C truth value on success or -1 on error.
9129 (Added in 1.5.10)
9131 guestfs_is_whole_device
9133 int
9134 guestfs_is_whole_device (guestfs_h *g,
9135 const char *device);
9136 This returns "true" if and only if "device" refers to a whole block
9138 device. That is, not a partition or a logical device.
9139 This function returns a C truth value on success or -1 on error.
9141 (Added in 1.21.9)
9143 guestfs_is_zero
9145 int
9146 guestfs_is_zero (guestfs_h *g,
9147 const char *path);
9148 This returns true iff the file exists and the file is empty or it
9150 contains all zero bytes.
9151 This function returns a C truth value on success or -1 on error.
9153 (Added in 1.11.8)
9155 guestfs_is_zero_device
9157 int
9158 guestfs_is_zero_device (guestfs_h *g,
9159 const char *device);
9160 This returns true iff the device exists and contains all zero bytes.
9162 Note that for large devices this can take a long time to run.
9164 This function returns a C truth value on success or -1 on error.
9166 (Added in 1.11.8)
9168 guestfs_isoinfo
9170 struct guestfs_isoinfo *
9171 guestfs_isoinfo (guestfs_h *g,
9172 const char *isofile);
9173 This is the same as "guestfs_isoinfo_device" except that it works for
9175 an ISO file located inside some other mounted filesystem. Note that in
9176 the common case where you have added an ISO file as a libguestfs
9177 device, you would not call this. Instead you would call
9178 "guestfs_isoinfo_device".
9179 This function returns a "struct guestfs_isoinfo *", or NULL if there
9181 was an error. The caller must call "guestfs_free_isoinfo" after use.
9182 (Added in 1.17.19)
9184 guestfs_isoinfo_device
9186 struct guestfs_isoinfo *
9187 guestfs_isoinfo_device (guestfs_h *g,
9188 const char *device);
9189 "device" is an ISO device. This returns a struct of information read
9191 from the primary volume descriptor (the ISO equivalent of the
9192 superblock) of the device.
9193 Usually it is more efficient to use the isoinfo(1) command with the -d
9195 option on the host to analyze ISO files, instead of going through
9196 libguestfs.
9197 For information on the primary volume descriptor fields, see
9199 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9200 This function returns a "struct guestfs_isoinfo *", or NULL if there
9202 was an error. The caller must call "guestfs_free_isoinfo" after use.
9203 (Added in 1.17.19)
9205 guestfs_journal_close
9207 int
9208 guestfs_journal_close (guestfs_h *g);
9209 Close the journal handle.
9211 This function returns 0 on success or -1 on error.
9213 This function depends on the feature "journal". See also
9215 "guestfs_feature_available".
9216 (Added in 1.23.11)
9218 guestfs_journal_get
9220 struct guestfs_xattr_list *
9221 guestfs_journal_get (guestfs_h *g);
9222 Read the current journal entry. This returns all the fields in the
9224 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
9225 field name (a string).
9226 The "attrval" is the field value (a binary blob, often but not always a
9228 string). Please note that "attrval" is a byte array, not a
9229 \0-terminated C string.
9230 The length of data may be truncated to the data threshold (see:
9232 "guestfs_journal_set_data_threshold",
9233 "guestfs_journal_get_data_threshold").
9234 If you set the data threshold to unlimited (0) then this call can read
9236 a journal entry of any size, ie. it is not limited by the libguestfs
9237 protocol.
9238 This function returns a "struct guestfs_xattr_list *", or NULL if there
9240 was an error. The caller must call "guestfs_free_xattr_list" after
9241 use.
9242 This function depends on the feature "journal". See also
9244 "guestfs_feature_available".
9245 (Added in 1.23.11)
9247 guestfs_journal_get_data_threshold
9249 int64_t
9250 guestfs_journal_get_data_threshold (guestfs_h *g);
9251 Get the current data threshold for reading journal entries. This is a
9253 hint to the journal that it may truncate data fields to this size when
9254 reading them (note also that it may not truncate them). If this
9255 returns 0, then the threshold is unlimited.
9256 See also "guestfs_journal_set_data_threshold".
9258 On error this function returns -1.
9260 This function depends on the feature "journal". See also
9262 "guestfs_feature_available".
9263 (Added in 1.23.11)
9265 guestfs_journal_get_realtime_usec
9267 int64_t
9268 guestfs_journal_get_realtime_usec (guestfs_h *g);
9269 Get the realtime (wallclock) timestamp of the current journal entry.
9271 On error this function returns -1.
9273 This function depends on the feature "journal". See also
9275 "guestfs_feature_available".
9276 (Added in 1.27.18)
9278 guestfs_journal_next
9280 int
9281 guestfs_journal_next (guestfs_h *g);
9282 Move to the next journal entry. You have to call this at least once
9284 after opening the handle before you are able to read data.
9285 The returned boolean tells you if there are any more journal records to
9287 read. "true" means you can read the next record (eg. using
9288 "guestfs_journal_get"), and "false" means you have reached the end of
9289 the journal.
9290 This function returns a C truth value on success or -1 on error.
9292 This function depends on the feature "journal". See also
9294 "guestfs_feature_available".
9295 (Added in 1.23.11)
9297 guestfs_journal_open
9299 int
9300 guestfs_journal_open (guestfs_h *g,
9301 const char *directory);
9302 Open the systemd journal located in directory. Any previously opened
9304 journal handle is closed.
9305 The contents of the journal can be read using "guestfs_journal_next"
9307 and "guestfs_journal_get".
9308 After you have finished using the journal, you should close the handle
9310 by calling "guestfs_journal_close".
9311 This function returns 0 on success or -1 on error.
9313 This function depends on the feature "journal". See also
9315 "guestfs_feature_available".
9316 (Added in 1.23.11)
9318 guestfs_journal_set_data_threshold
9320 int
9321 guestfs_journal_set_data_threshold (guestfs_h *g,
9322 int64_t threshold);
9323 Set the data threshold for reading journal entries. This is a hint to
9325 the journal that it may truncate data fields to this size when reading
9326 them (note also that it may not truncate them). If you set this to 0,
9327 then the threshold is unlimited.
9328 See also "guestfs_journal_get_data_threshold".
9330 This function returns 0 on success or -1 on error.
9332 This function depends on the feature "journal". See also
9334 "guestfs_feature_available".
9335 (Added in 1.23.11)
9337 guestfs_journal_skip
9339 int64_t
9340 guestfs_journal_skip (guestfs_h *g,
9341 int64_t skip);
9342 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9344 The number of entries actually skipped is returned (note "rskip ≥ 0").
9346 If this is not the same as the absolute value of the skip parameter
9347 ("|skip|") you passed in then it means you have reached the end or the
9348 start of the journal.
9349 On error this function returns -1.
9351 This function depends on the feature "journal". See also
9353 "guestfs_feature_available".
9354 (Added in 1.23.11)
9356 guestfs_kill_subprocess
9358 int
9359 guestfs_kill_subprocess (guestfs_h *g);
9360 This function is deprecated. In new code, use the "guestfs_shutdown"
9362 call instead.
9363 Deprecated functions will not be removed from the API, but the fact
9365 that they are deprecated indicates that there are problems with correct
9366 use of these functions.
9367 This kills the hypervisor.
9369 Do not call this. See: "guestfs_shutdown" instead.
9371 This function returns 0 on success or -1 on error.
9373 (Added in 0.3)
9375 guestfs_launch
9377 int
9378 guestfs_launch (guestfs_h *g);
9379 You should call this after configuring the handle (eg. adding drives)
9381 but before performing any actions.
9382 Do not call "guestfs_launch" twice on the same handle. Although it
9384 will not give an error (for historical reasons), the precise behaviour
9385 when you do this is not well defined. Handles are very cheap to
9386 create, so create a new one for each launch.
9387 This function returns 0 on success or -1 on error.
9389 This long-running command can generate progress notification messages
9391 so that the caller can display a progress bar or indicator. To receive
9392 these messages, the caller must register a progress event callback.
9393 See "GUESTFS_EVENT_PROGRESS".
9394 (Added in 0.3)
9396 guestfs_lchown
9398 int
9399 guestfs_lchown (guestfs_h *g,
9400 int owner,
9401 int group,
9402 const char *path);
9403 Change the file owner to "owner" and group to "group". This is like
9405 "guestfs_chown" but if "path" is a symlink then the link itself is
9406 changed, not the target.
9407 Only numeric uid and gid are supported. If you want to use names, you
9409 will need to locate and parse the password file yourself (Augeas
9410 support makes this relatively easy).
9411 This function returns 0 on success or -1 on error.
9413 (Added in 1.0.77)
9415 guestfs_ldmtool_create_all
9417 int
9418 guestfs_ldmtool_create_all (guestfs_h *g);
9419 This function scans all block devices looking for Windows dynamic disk
9421 volumes and partitions, and creates devices for any that were found.
9422 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9424 return all devices.
9425 Note that you don't normally need to call this explicitly, since it is
9427 done automatically at "guestfs_launch" time.
9428 This function returns 0 on success or -1 on error.
9430 This function depends on the feature "ldm". See also
9432 "guestfs_feature_available".
9433 (Added in 1.20.0)
9435 guestfs_ldmtool_diskgroup_disks
9437 char **
9438 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9439 const char *diskgroup);
9440 Return the disks in a Windows dynamic disk group. The "diskgroup"
9442 parameter should be the GUID of a disk group, one element from the list
9443 returned by "guestfs_ldmtool_scan".
9444 This function returns a NULL-terminated array of strings (like
9446 environ(3)), or NULL if there was an error. The caller must free the
9447 strings and the array after use.
9448 This function depends on the feature "ldm". See also
9450 "guestfs_feature_available".
9451 (Added in 1.20.0)
9453 guestfs_ldmtool_diskgroup_name
9455 char *
9456 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9457 const char *diskgroup);
9458 Return the name of a Windows dynamic disk group. The "diskgroup"
9460 parameter should be the GUID of a disk group, one element from the list
9461 returned by "guestfs_ldmtool_scan".
9462 This function returns a string, or NULL on error. The caller must free
9464 the returned string after use.
9465 This function depends on the feature "ldm". See also
9467 "guestfs_feature_available".
9468 (Added in 1.20.0)
9470 guestfs_ldmtool_diskgroup_volumes
9472 char **
9473 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9474 const char *diskgroup);
9475 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9477 parameter should be the GUID of a disk group, one element from the list
9478 returned by "guestfs_ldmtool_scan".
9479 This function returns a NULL-terminated array of strings (like
9481 environ(3)), or NULL if there was an error. The caller must free the
9482 strings and the array after use.
9483 This function depends on the feature "ldm". See also
9485 "guestfs_feature_available".
9486 (Added in 1.20.0)
9488 guestfs_ldmtool_remove_all
9490 int
9491 guestfs_ldmtool_remove_all (guestfs_h *g);
9492 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9494 removes the device mapper mappings for all Windows dynamic disk volumes
9495 This function returns 0 on success or -1 on error.
9497 This function depends on the feature "ldm". See also
9499 "guestfs_feature_available".
9500 (Added in 1.20.0)
9502 guestfs_ldmtool_scan
9504 char **
9505 guestfs_ldmtool_scan (guestfs_h *g);
9506 This function scans for Windows dynamic disks. It returns a list of
9508 identifiers (GUIDs) for all disk groups that were found. These
9509 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9510 This function scans all block devices. To scan a subset of block
9512 devices, call "guestfs_ldmtool_scan_devices" instead.
9513 This function returns a NULL-terminated array of strings (like
9515 environ(3)), or NULL if there was an error. The caller must free the
9516 strings and the array after use.
9517 This function depends on the feature "ldm". See also
9519 "guestfs_feature_available".
9520 (Added in 1.20.0)
9522 guestfs_ldmtool_scan_devices
9524 char **
9525 guestfs_ldmtool_scan_devices (guestfs_h *g,
9526 char *const *devices);
9527 This function scans for Windows dynamic disks. It returns a list of
9529 identifiers (GUIDs) for all disk groups that were found. These
9530 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9531 The parameter "devices" is a list of block devices which are scanned.
9533 If this list is empty, all block devices are scanned.
9534 This function returns a NULL-terminated array of strings (like
9536 environ(3)), or NULL if there was an error. The caller must free the
9537 strings and the array after use.
9538 This function depends on the feature "ldm". See also
9540 "guestfs_feature_available".
9541 (Added in 1.20.0)
9543 guestfs_ldmtool_volume_hint
9545 char *
9546 guestfs_ldmtool_volume_hint (guestfs_h *g,
9547 const char *diskgroup,
9548 const char *volume);
9549 Return the hint field of the volume named "volume" in the disk group
9551 with GUID "diskgroup". This may not be defined, in which case the
9552 empty string is returned. The hint field is often, though not always,
9553 the name of a Windows drive, eg. "E:".
9554 This function returns a string, or NULL on error. The caller must free
9556 the returned string after use.
9557 This function depends on the feature "ldm". See also
9559 "guestfs_feature_available".
9560 (Added in 1.20.0)
9562 guestfs_ldmtool_volume_partitions
9564 char **
9565 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9566 const char *diskgroup,
9567 const char *volume);
9568 Return the list of partitions in the volume named "volume" in the disk
9570 group with GUID "diskgroup".
9571 This function returns a NULL-terminated array of strings (like
9573 environ(3)), or NULL if there was an error. The caller must free the
9574 strings and the array after use.
9575 This function depends on the feature "ldm". See also
9577 "guestfs_feature_available".
9578 (Added in 1.20.0)
9580 guestfs_ldmtool_volume_type
9582 char *
9583 guestfs_ldmtool_volume_type (guestfs_h *g,
9584 const char *diskgroup,
9585 const char *volume);
9586 Return the type of the volume named "volume" in the disk group with
9588 GUID "diskgroup".
9589 Possible volume types that can be returned here include: "simple",
9591 "spanned", "striped", "mirrored", "raid5". Other types may also be
9592 returned.
9593 This function returns a string, or NULL on error. The caller must free
9595 the returned string after use.
9596 This function depends on the feature "ldm". See also
9598 "guestfs_feature_available".
9599 (Added in 1.20.0)
9601 guestfs_lgetxattr
9603 char *
9604 guestfs_lgetxattr (guestfs_h *g,
9605 const char *path,
9606 const char *name,
9607 size_t *size_r);
9608 Get a single extended attribute from file "path" named "name". If
9610 "path" is a symlink, then this call returns an extended attribute from
9611 the symlink.
9612 Normally it is better to get all extended attributes from a file in one
9614 go by calling "guestfs_getxattrs". However some Linux filesystem
9615 implementations are buggy and do not provide a way to list out
9616 attributes. For these filesystems (notably ntfs-3g) you have to know
9617 the names of the extended attributes you want in advance and call this
9618 function.
9619 Extended attribute values are blobs of binary data. If there is no
9621 extended attribute named "name", this returns an error.
9622 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9624 This function returns a buffer, or NULL on error. The size of the
9626 returned buffer is written to *size_r. The caller must free the
9627 returned buffer after use.
9628 This function depends on the feature "linuxxattrs". See also
9630 "guestfs_feature_available".
9631 (Added in 1.7.24)
9633 guestfs_lgetxattrs
9635 struct guestfs_xattr_list *
9636 guestfs_lgetxattrs (guestfs_h *g,
9637 const char *path);
9638 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9640 link, then it returns the extended attributes of the link itself.
9641 This function returns a "struct guestfs_xattr_list *", or NULL if there
9643 was an error. The caller must call "guestfs_free_xattr_list" after
9644 use.
9645 This function depends on the feature "linuxxattrs". See also
9647 "guestfs_feature_available".
9648 (Added in 1.0.59)
9650 guestfs_list_9p
9652 char **
9653 guestfs_list_9p (guestfs_h *g);
9654 This function is deprecated. There is no replacement. Consult the API
9656 documentation in guestfs(3) for further information.
9657 Deprecated functions will not be removed from the API, but the fact
9659 that they are deprecated indicates that there are problems with correct
9660 use of these functions.
9661 This call does nothing and returns an error.
9663 This function returns a NULL-terminated array of strings (like
9665 environ(3)), or NULL if there was an error. The caller must free the
9666 strings and the array after use.
9667 (Added in 1.11.12)
9669 guestfs_list_devices
9671 char **
9672 guestfs_list_devices (guestfs_h *g);
9673 List all the block devices.
9675 The full block device names are returned, eg. /dev/sda.
9677 See also "guestfs_list_filesystems".
9679 This function returns a NULL-terminated array of strings (like
9681 environ(3)), or NULL if there was an error. The caller must free the
9682 strings and the array after use.
9683 (Added in 0.4)
9685 guestfs_list_disk_labels
9687 char **
9688 guestfs_list_disk_labels (guestfs_h *g);
9689 If you add drives using the optional "label" parameter of
9691 "guestfs_add_drive_opts", you can use this call to map between disk
9692 labels, and raw block device and partition names (like /dev/sda and
9693 /dev/sda1).
9694 This returns a hashtable, where keys are the disk labels (without the
9696 /dev/disk/guestfs prefix), and the values are the full raw block device
9697 and partition names (eg. /dev/sda and /dev/sda1).
9698 This function returns a NULL-terminated array of strings, or NULL if
9700 there was an error. The array of strings will always have length
9701 "2n+1", where "n" keys and values alternate, followed by the trailing
9702 NULL entry. The caller must free the strings and the array after use.
9703 (Added in 1.19.49)
9705 guestfs_list_dm_devices
9707 char **
9708 guestfs_list_dm_devices (guestfs_h *g);
9709 List all device mapper devices.
9711 The returned list contains /dev/mapper/* devices, eg. ones created by a
9713 previous call to "guestfs_luks_open".
9714 Device mapper devices which correspond to logical volumes are not
9716 returned in this list. Call "guestfs_lvs" if you want to list logical
9717 volumes.
9718 This function returns a NULL-terminated array of strings (like
9720 environ(3)), or NULL if there was an error. The caller must free the
9721 strings and the array after use.
9722 (Added in 1.11.15)
9724 guestfs_list_filesystems
9726 char **
9727 guestfs_list_filesystems (guestfs_h *g);
9728 This inspection command looks for filesystems on partitions, block
9730 devices and logical volumes, returning a list of "mountables"
9731 containing filesystems and their type.
9732 The return value is a hash, where the keys are the devices containing
9734 filesystems, and the values are the filesystem types. For example:
9735 "/dev/sda1" => "ntfs"
9737 "/dev/sda2" => "ext2"
9738 "/dev/vg_guest/lv_root" => "ext4"
9739 "/dev/vg_guest/lv_swap" => "swap"
9740 The key is not necessarily a block device. It may also be an opaque
9742 ‘mountable’ string which can be passed to "guestfs_mount".
9743 The value can have the special value "unknown", meaning the content of
9745 the device is undetermined or empty. "swap" means a Linux swap
9746 partition.
9747 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9749 might have included "guestfs_mount" and "guestfs_umount", and therefore
9750 you had to use this soon after launch and only when nothing else was
9751 mounted. This restriction is removed in libguestfs ≥ 1.38.
9752 Not all of the filesystems returned will be mountable. In particular,
9754 swap partitions are returned in the list. Also this command does not
9755 check that each filesystem found is valid and mountable, and some
9756 filesystems might be mountable but require special options.
9757 Filesystems may not all belong to a single logical operating system
9758 (use "guestfs_inspect_os" to look for OSes).
9759 This function returns a NULL-terminated array of strings, or NULL if
9761 there was an error. The array of strings will always have length
9762 "2n+1", where "n" keys and values alternate, followed by the trailing
9763 NULL entry. The caller must free the strings and the array after use.
9764 (Added in 1.5.15)
9766 guestfs_list_ldm_partitions
9768 char **
9769 guestfs_list_ldm_partitions (guestfs_h *g);
9770 This function returns all Windows dynamic disk partitions that were
9772 found at launch time. It returns a list of device names.
9773 This function returns a NULL-terminated array of strings (like
9775 environ(3)), or NULL if there was an error. The caller must free the
9776 strings and the array after use.
9777 This function depends on the feature "ldm". See also
9779 "guestfs_feature_available".
9780 (Added in 1.20.0)
9782 guestfs_list_ldm_volumes
9784 char **
9785 guestfs_list_ldm_volumes (guestfs_h *g);
9786 This function returns all Windows dynamic disk volumes that were found
9788 at launch time. It returns a list of device names.
9789 This function returns a NULL-terminated array of strings (like
9791 environ(3)), or NULL if there was an error. The caller must free the
9792 strings and the array after use.
9793 This function depends on the feature "ldm". See also
9795 "guestfs_feature_available".
9796 (Added in 1.20.0)
9798 guestfs_list_md_devices
9800 char **
9801 guestfs_list_md_devices (guestfs_h *g);
9802 List all Linux md devices.
9804 This function returns a NULL-terminated array of strings (like
9806 environ(3)), or NULL if there was an error. The caller must free the
9807 strings and the array after use.
9808 (Added in 1.15.4)
9810 guestfs_list_partitions
9812 char **
9813 guestfs_list_partitions (guestfs_h *g);
9814 List all the partitions detected on all block devices.
9816 The full partition device names are returned, eg. /dev/sda1
9818 This does not return logical volumes. For that you will need to call
9820 "guestfs_lvs".
9821 See also "guestfs_list_filesystems".
9823 This function returns a NULL-terminated array of strings (like
9825 environ(3)), or NULL if there was an error. The caller must free the
9826 strings and the array after use.
9827 (Added in 0.4)
9829 guestfs_ll
9831 char *
9832 guestfs_ll (guestfs_h *g,
9833 const char *directory);
9834 List the files in directory (relative to the root directory, there is
9836 no cwd) in the format of "ls -la".
9837 This command is mostly useful for interactive sessions. It is not
9839 intended that you try to parse the output string.
9840 This function returns a string, or NULL on error. The caller must free
9842 the returned string after use.
9843 (Added in 0.4)
9845 guestfs_llz
9847 char *
9848 guestfs_llz (guestfs_h *g,
9849 const char *directory);
9850 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9852 call instead.
9853 Deprecated functions will not be removed from the API, but the fact
9855 that they are deprecated indicates that there are problems with correct
9856 use of these functions.
9857 List the files in directory in the format of "ls -laZ".
9859 This command is mostly useful for interactive sessions. It is not
9861 intended that you try to parse the output string.
9862 This function returns a string, or NULL on error. The caller must free
9864 the returned string after use.
9865 (Added in 1.17.6)
9867 guestfs_ln
9869 int
9870 guestfs_ln (guestfs_h *g,
9871 const char *target,
9872 const char *linkname);
9873 This command creates a hard link.
9875 This function returns 0 on success or -1 on error.
9877 (Added in 1.0.66)
9879 guestfs_ln_f
9881 int
9882 guestfs_ln_f (guestfs_h *g,
9883 const char *target,
9884 const char *linkname);
9885 This command creates a hard link, removing the link "linkname" if it
9887 exists already.
9888 This function returns 0 on success or -1 on error.
9890 (Added in 1.0.66)
9892 guestfs_ln_s
9894 int
9895 guestfs_ln_s (guestfs_h *g,
9896 const char *target,
9897 const char *linkname);
9898 This command creates a symbolic link using the "ln -s" command.
9900 This function returns 0 on success or -1 on error.
9902 (Added in 1.0.66)
9904 guestfs_ln_sf
9906 int
9907 guestfs_ln_sf (guestfs_h *g,
9908 const char *target,
9909 const char *linkname);
9910 This command creates a symbolic link using the "ln -sf" command, The -f
9912 option removes the link ("linkname") if it exists already.
9913 This function returns 0 on success or -1 on error.
9915 (Added in 1.0.66)
9917 guestfs_lremovexattr
9919 int
9920 guestfs_lremovexattr (guestfs_h *g,
9921 const char *xattr,
9922 const char *path);
9923 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9925 link, then it removes an extended attribute of the link itself.
9926 This function returns 0 on success or -1 on error.
9928 This function depends on the feature "linuxxattrs". See also
9930 "guestfs_feature_available".
9931 (Added in 1.0.59)
9933 guestfs_ls
9935 char **
9936 guestfs_ls (guestfs_h *g,
9937 const char *directory);
9938 List the files in directory (relative to the root directory, there is
9940 no cwd). The "." and ".." entries are not returned, but hidden files
9941 are shown.
9942 This function returns a NULL-terminated array of strings (like
9944 environ(3)), or NULL if there was an error. The caller must free the
9945 strings and the array after use.
9946 (Added in 0.4)
9948 guestfs_ls0
9950 int
9951 guestfs_ls0 (guestfs_h *g,
9952 const char *dir,
9953 const char *filenames);
9954 This specialized command is used to get a listing of the filenames in
9956 the directory "dir". The list of filenames is written to the local
9957 file filenames (on the host).
9958 In the output file, the filenames are separated by "\0" characters.
9960 "." and ".." are not returned. The filenames are not sorted.
9962 This function returns 0 on success or -1 on error.
9964 (Added in 1.19.32)
9966 guestfs_lsetxattr
9968 int
9969 guestfs_lsetxattr (guestfs_h *g,
9970 const char *xattr,
9971 const char *val,
9972 int vallen,
9973 const char *path);
9974 This is the same as "guestfs_setxattr", but if "path" is a symbolic
9976 link, then it sets an extended attribute of the link itself.
9977 This function returns 0 on success or -1 on error.
9979 This function depends on the feature "linuxxattrs". See also
9981 "guestfs_feature_available".
9982 (Added in 1.0.59)
9984 guestfs_lstat
9986 struct guestfs_stat *
9987 guestfs_lstat (guestfs_h *g,
9988 const char *path);
9989 This function is deprecated. In new code, use the "guestfs_lstatns"
9991 call instead.
9992 Deprecated functions will not be removed from the API, but the fact
9994 that they are deprecated indicates that there are problems with correct
9995 use of these functions.
9996 Returns file information for the given "path".
9998 This is the same as "guestfs_stat" except that if "path" is a symbolic
10000 link, then the link is stat-ed, not the file it refers to.
10001 This is the same as the lstat(2) system call.
10003 This function returns a "struct guestfs_stat *", or NULL if there was
10005 an error. The caller must call "guestfs_free_stat" after use.
10006 (Added in 1.9.2)
10008 guestfs_lstatlist
10010 struct guestfs_stat_list *
10011 guestfs_lstatlist (guestfs_h *g,
10012 const char *path,
10013 char *const *names);
10014 This function is deprecated. In new code, use the
10016 "guestfs_lstatnslist" call instead.
10017 Deprecated functions will not be removed from the API, but the fact
10019 that they are deprecated indicates that there are problems with correct
10020 use of these functions.
10021 This call allows you to perform the "guestfs_lstat" operation on
10023 multiple files, where all files are in the directory "path". "names"
10024 is the list of files from this directory.
10025 On return you get a list of stat structs, with a one-to-one
10027 correspondence to the "names" list. If any name did not exist or could
10028 not be lstat'd, then the "st_ino" field of that structure is set to -1.
10029 This call is intended for programs that want to efficiently list a
10031 directory contents without making many round-trips. See also
10032 "guestfs_lxattrlist" for a similarly efficient call for getting
10033 extended attributes.
10034 This function returns a "struct guestfs_stat_list *", or NULL if there
10036 was an error. The caller must call "guestfs_free_stat_list" after use.
10037 (Added in 1.0.77)
10039 guestfs_lstatns
10041 struct guestfs_statns *
10042 guestfs_lstatns (guestfs_h *g,
10043 const char *path);
10044 Returns file information for the given "path".
10046 This is the same as "guestfs_statns" except that if "path" is a
10048 symbolic link, then the link is stat-ed, not the file it refers to.
10049 This is the same as the lstat(2) system call.
10051 This function returns a "struct guestfs_statns *", or NULL if there was
10053 an error. The caller must call "guestfs_free_statns" after use.
10054 (Added in 1.27.53)
10056 guestfs_lstatnslist
10058 struct guestfs_statns_list *
10059 guestfs_lstatnslist (guestfs_h *g,
10060 const char *path,
10061 char *const *names);
10062 This call allows you to perform the "guestfs_lstatns" operation on
10064 multiple files, where all files are in the directory "path". "names"
10065 is the list of files from this directory.
10066 On return you get a list of stat structs, with a one-to-one
10068 correspondence to the "names" list. If any name did not exist or could
10069 not be lstat'd, then the "st_ino" field of that structure is set to -1.
10070 This call is intended for programs that want to efficiently list a
10072 directory contents without making many round-trips. See also
10073 "guestfs_lxattrlist" for a similarly efficient call for getting
10074 extended attributes.
10075 This function returns a "struct guestfs_statns_list *", or NULL if
10077 there was an error. The caller must call "guestfs_free_statns_list"
10078 after use.
10079 (Added in 1.27.53)
10081 guestfs_luks_add_key
10083 int
10084 guestfs_luks_add_key (guestfs_h *g,
10085 const char *device,
10086 const char *key,
10087 const char *newkey,
10088 int keyslot);
10089 This command adds a new key on LUKS device "device". "key" is any
10091 existing key, and is used to access the device. "newkey" is the new
10092 key to add. "keyslot" is the key slot that will be replaced.
10093 Note that if "keyslot" already contains a key, then this command will
10095 fail. You have to use "guestfs_luks_kill_slot" first to remove that
10096 key.
10097 This function returns 0 on success or -1 on error.
10099 This function takes a key or passphrase parameter which could contain
10101 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10102 information.
10103 This function depends on the feature "luks". See also
10105 "guestfs_feature_available".
10106 (Added in 1.5.2)
10108 guestfs_luks_close
10110 int
10111 guestfs_luks_close (guestfs_h *g,
10112 const char *device);
10113 This function is deprecated. In new code, use the
10115 "guestfs_cryptsetup_close" call instead.
10116 Deprecated functions will not be removed from the API, but the fact
10118 that they are deprecated indicates that there are problems with correct
10119 use of these functions.
10120 This closes a LUKS device that was created earlier by
10122 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
10123 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10124 and not the name of the underlying block device.
10125 This function returns 0 on success or -1 on error.
10127 This function depends on the feature "luks". See also
10129 "guestfs_feature_available".
10130 (Added in 1.5.1)
10132 guestfs_luks_format
10134 int
10135 guestfs_luks_format (guestfs_h *g,
10136 const char *device,
10137 const char *key,
10138 int keyslot);
10139 This command erases existing data on "device" and formats the device as
10141 a LUKS encrypted device. "key" is the initial key, which is added to
10142 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
10143 This function returns 0 on success or -1 on error.
10145 This function takes a key or passphrase parameter which could contain
10147 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10148 information.
10149 This function depends on the feature "luks". See also
10151 "guestfs_feature_available".
10152 (Added in 1.5.2)
10154 guestfs_luks_format_cipher
10156 int
10157 guestfs_luks_format_cipher (guestfs_h *g,
10158 const char *device,
10159 const char *key,
10160 int keyslot,
10161 const char *cipher);
10162 This command is the same as "guestfs_luks_format" but it also allows
10164 you to set the "cipher" used.
10165 This function returns 0 on success or -1 on error.
10167 This function takes a key or passphrase parameter which could contain
10169 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10170 information.
10171 This function depends on the feature "luks". See also
10173 "guestfs_feature_available".
10174 (Added in 1.5.2)
10176 guestfs_luks_kill_slot
10178 int
10179 guestfs_luks_kill_slot (guestfs_h *g,
10180 const char *device,
10181 const char *key,
10182 int keyslot);
10183 This command deletes the key in key slot "keyslot" from the encrypted
10185 LUKS device "device". "key" must be one of the other keys.
10186 This function returns 0 on success or -1 on error.
10188 This function takes a key or passphrase parameter which could contain
10190 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10191 information.
10192 This function depends on the feature "luks". See also
10194 "guestfs_feature_available".
10195 (Added in 1.5.2)
10197 guestfs_luks_open
10199 int
10200 guestfs_luks_open (guestfs_h *g,
10201 const char *device,
10202 const char *key,
10203 const char *mapname);
10204 This function is deprecated. In new code, use the
10206 "guestfs_cryptsetup_open" call instead.
10207 Deprecated functions will not be removed from the API, but the fact
10209 that they are deprecated indicates that there are problems with correct
10210 use of these functions.
10211 This command opens a block device which has been encrypted according to
10213 the Linux Unified Key Setup (LUKS) standard.
10214 "device" is the encrypted block device or partition.
10216 The caller must supply one of the keys associated with the LUKS block
10218 device, in the "key" parameter.
10219 This creates a new block device called /dev/mapper/mapname. Reads and
10221 writes to this block device are decrypted from and encrypted to the
10222 underlying "device" respectively.
10223 If this block device contains LVM volume groups, then calling
10225 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10226 visible.
10227 Use "guestfs_list_dm_devices" to list all device mapper devices.
10229 This function returns 0 on success or -1 on error.
10231 This function takes a key or passphrase parameter which could contain
10233 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10234 information.
10235 This function depends on the feature "luks". See also
10237 "guestfs_feature_available".
10238 (Added in 1.5.1)
10240 guestfs_luks_open_ro
10242 int
10243 guestfs_luks_open_ro (guestfs_h *g,
10244 const char *device,
10245 const char *key,
10246 const char *mapname);
10247 This function is deprecated. In new code, use the
10249 "guestfs_cryptsetup_open" call instead.
10250 Deprecated functions will not be removed from the API, but the fact
10252 that they are deprecated indicates that there are problems with correct
10253 use of these functions.
10254 This is the same as "guestfs_luks_open" except that a read-only mapping
10256 is created.
10257 This function returns 0 on success or -1 on error.
10259 This function takes a key or passphrase parameter which could contain
10261 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10262 information.
10263 This function depends on the feature "luks". See also
10265 "guestfs_feature_available".
10266 (Added in 1.5.1)
10268 guestfs_luks_uuid
10270 char *
10271 guestfs_luks_uuid (guestfs_h *g,
10272 const char *device);
10273 This returns the UUID of the LUKS device "device".
10275 This function returns a string, or NULL on error. The caller must free
10277 the returned string after use.
10278 This function depends on the feature "luks". See also
10280 "guestfs_feature_available".
10281 (Added in 1.41.9)
10283 guestfs_lvcreate
10285 int
10286 guestfs_lvcreate (guestfs_h *g,
10287 const char *logvol,
10288 const char *volgroup,
10289 int mbytes);
10290 This creates an LVM logical volume called "logvol" on the volume group
10292 "volgroup", with "size" megabytes.
10293 This function returns 0 on success or -1 on error.
10295 This function depends on the feature "lvm2". See also
10297 "guestfs_feature_available".
10298 (Added in 0.8)
10300 guestfs_lvcreate_free
10302 int
10303 guestfs_lvcreate_free (guestfs_h *g,
10304 const char *logvol,
10305 const char *volgroup,
10306 int percent);
10307 Create an LVM logical volume called /dev/volgroup/logvol, using
10309 approximately "percent" % of the free space remaining in the volume
10310 group. Most usefully, when "percent" is 100 this will create the
10311 largest possible LV.
10312 This function returns 0 on success or -1 on error.
10314 This function depends on the feature "lvm2". See also
10316 "guestfs_feature_available".
10317 (Added in 1.17.18)
10319 guestfs_lvm_canonical_lv_name
10321 char *
10322 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10323 const char *lvname);
10324 This converts alternative naming schemes for LVs that you might find to
10326 the canonical name. For example, /dev/mapper/VG-LV is converted to
10327 /dev/VG/LV.
10328 This command returns an error if the "lvname" parameter does not refer
10330 to a logical volume. In this case errno will be set to "EINVAL".
10331 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10333 This function returns a string, or NULL on error. The caller must free
10335 the returned string after use.
10336 (Added in 1.5.24)
10338 guestfs_lvm_clear_filter
10340 int
10341 guestfs_lvm_clear_filter (guestfs_h *g);
10342 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10344 to see every block device.
10345 This command also clears the LVM cache and performs a volume group
10347 scan.
10348 This function returns 0 on success or -1 on error.
10350 (Added in 1.5.1)
10352 guestfs_lvm_remove_all
10354 int
10355 guestfs_lvm_remove_all (guestfs_h *g);
10356 This command removes all LVM logical volumes, volume groups and
10358 physical volumes.
10359 This function returns 0 on success or -1 on error.
10361 This function depends on the feature "lvm2". See also
10363 "guestfs_feature_available".
10364 (Added in 0.8)
10366 guestfs_lvm_scan
10368 int
10369 guestfs_lvm_scan (guestfs_h *g,
10370 int activate);
10371 This scans all block devices and rebuilds the list of LVM physical
10373 volumes, volume groups and logical volumes.
10374 If the "activate" parameter is "true" then newly found volume groups
10376 and logical volumes are activated, meaning the LV /dev/VG/LV devices
10377 become visible.
10378 When a libguestfs handle is launched it scans for existing devices, so
10380 you do not normally need to use this API. However it is useful when
10381 you have added a new device or deleted an existing device (such as when
10382 the "guestfs_luks_open" API is used).
10383 This function returns 0 on success or -1 on error.
10385 (Added in 1.39.8)
10387 guestfs_lvm_set_filter
10389 int
10390 guestfs_lvm_set_filter (guestfs_h *g,
10391 char *const *devices);
10392 This sets the LVM device filter so that LVM will only be able to "see"
10394 the block devices in the list "devices", and will ignore all other
10395 attached block devices.
10396 Where disk image(s) contain duplicate PVs or VGs, this command is
10398 useful to get LVM to ignore the duplicates, otherwise LVM can get
10399 confused. Note also there are two types of duplication possible:
10400 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10401 cloned but just happen to have the same name. In normal operation you
10402 cannot create this situation, but you can do it outside LVM, eg. by
10403 cloning disk images or by bit twiddling inside the LVM metadata.
10404 This command also clears the LVM cache and performs a volume group
10406 scan.
10407 You can filter whole block devices or individual partitions.
10409 You cannot use this if any VG is currently in use (eg. contains a
10411 mounted filesystem), even if you are not filtering out that VG.
10412 This function returns 0 on success or -1 on error.
10414 This function depends on the feature "lvm2". See also
10416 "guestfs_feature_available".
10417 (Added in 1.5.1)
10419 guestfs_lvremove
10421 int
10422 guestfs_lvremove (guestfs_h *g,
10423 const char *device);
10424 Remove an LVM logical volume "device", where "device" is the path to
10426 the LV, such as /dev/VG/LV.
10427 You can also remove all LVs in a volume group by specifying the VG
10429 name, /dev/VG.
10430 This function returns 0 on success or -1 on error.
10432 This function depends on the feature "lvm2". See also
10434 "guestfs_feature_available".
10435 (Added in 1.0.13)
10437 guestfs_lvrename
10439 int
10440 guestfs_lvrename (guestfs_h *g,
10441 const char *logvol,
10442 const char *newlogvol);
10443 Rename a logical volume "logvol" with the new name "newlogvol".
10445 This function returns 0 on success or -1 on error.
10447 (Added in 1.0.83)
10449 guestfs_lvresize
10451 int
10452 guestfs_lvresize (guestfs_h *g,
10453 const char *device,
10454 int mbytes);
10455 This resizes (expands or shrinks) an existing LVM logical volume to
10457 "mbytes". When reducing, data in the reduced part is lost.
10458 This function returns 0 on success or -1 on error.
10460 This function depends on the feature "lvm2". See also
10462 "guestfs_feature_available".
10463 (Added in 1.0.27)
10465 guestfs_lvresize_free
10467 int
10468 guestfs_lvresize_free (guestfs_h *g,
10469 const char *lv,
10470 int percent);
10471 This expands an existing logical volume "lv" so that it fills "pc" % of
10473 the remaining free space in the volume group. Commonly you would call
10474 this with pc = 100 which expands the logical volume as much as
10475 possible, using all remaining free space in the volume group.
10476 This function returns 0 on success or -1 on error.
10478 This function depends on the feature "lvm2". See also
10480 "guestfs_feature_available".
10481 (Added in 1.3.3)
10483 guestfs_lvs
10485 char **
10486 guestfs_lvs (guestfs_h *g);
10487 List all the logical volumes detected. This is the equivalent of the
10489 lvs(8) command.
10490 This returns a list of the logical volume device names (eg.
10492 /dev/VolGroup00/LogVol00).
10493 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10495 This function returns a NULL-terminated array of strings (like
10497 environ(3)), or NULL if there was an error. The caller must free the
10498 strings and the array after use.
10499 This function depends on the feature "lvm2". See also
10501 "guestfs_feature_available".
10502 (Added in 0.4)
10504 guestfs_lvs_full
10506 struct guestfs_lvm_lv_list *
10507 guestfs_lvs_full (guestfs_h *g);
10508 List all the logical volumes detected. This is the equivalent of the
10510 lvs(8) command. The "full" version includes all fields.
10511 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10513 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10514 after use.
10515 This function depends on the feature "lvm2". See also
10517 "guestfs_feature_available".
10518 (Added in 0.4)
10520 guestfs_lvuuid
10522 char *
10523 guestfs_lvuuid (guestfs_h *g,
10524 const char *device);
10525 This command returns the UUID of the LVM LV "device".
10527 This function returns a string, or NULL on error. The caller must free
10529 the returned string after use.
10530 (Added in 1.0.87)
10532 guestfs_lxattrlist
10534 struct guestfs_xattr_list *
10535 guestfs_lxattrlist (guestfs_h *g,
10536 const char *path,
10537 char *const *names);
10538 This call allows you to get the extended attributes of multiple files,
10540 where all files are in the directory "path". "names" is the list of
10541 files from this directory.
10542 On return you get a flat list of xattr structs which must be
10544 interpreted sequentially. The first xattr struct always has a zero-
10545 length "attrname". "attrval" in this struct is zero-length to indicate
10546 there was an error doing "guestfs_lgetxattr" for this file, or is a C
10547 string which is a decimal number (the number of following attributes
10548 for this file, which could be "0"). Then after the first xattr struct
10549 are the zero or more attributes for the first named file. This repeats
10550 for the second and subsequent files.
10551 This call is intended for programs that want to efficiently list a
10553 directory contents without making many round-trips. See also
10554 "guestfs_lstatlist" for a similarly efficient call for getting standard
10555 stats.
10556 This function returns a "struct guestfs_xattr_list *", or NULL if there
10558 was an error. The caller must call "guestfs_free_xattr_list" after
10559 use.
10560 This function depends on the feature "linuxxattrs". See also
10562 "guestfs_feature_available".
10563 (Added in 1.0.77)
10565 guestfs_max_disks
10567 int
10568 guestfs_max_disks (guestfs_h *g);
10569 Return the maximum number of disks that may be added to a handle (eg.
10571 by "guestfs_add_drive_opts" and similar calls).
10572 This function was added in libguestfs 1.19.7. In previous versions of
10574 libguestfs the limit was 25.
10575 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10577 On error this function returns -1.
10579 (Added in 1.19.7)
10581 guestfs_md_create
10583 int
10584 guestfs_md_create (guestfs_h *g,
10585 const char *name,
10586 char *const *devices,
10587 ...);
10588 You may supply a list of optional arguments to this call. Use zero or
10590 more of the following pairs of parameters, and terminate the list with
10591 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10592 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10594 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10595 GUESTFS_MD_CREATE_SPARE, int spare,
10596 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10597 GUESTFS_MD_CREATE_LEVEL, const char *level,
10598 Create a Linux md (RAID) device named "name" on the devices in the list
10600 "devices".
10601 The optional parameters are:
10603 "missingbitmap"
10605 A bitmap of missing devices. If a bit is set it means that a
10606 missing device is added to the array. The least significant bit
10607 corresponds to the first device in the array.
10608 As examples:
10610 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10612 resulting array would be "[<missing>, "/dev/sda"]".
10613 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10615 resulting array would be "["/dev/sda", <missing>]".
10616 This defaults to 0 (no missing devices).
10618 The length of "devices" + the number of bits set in "missingbitmap"
10620 must equal "nrdevices" + "spare".
10621 "nrdevices"
10623 The number of active RAID devices.
10624 If not set, this defaults to the length of "devices" plus the
10626 number of bits set in "missingbitmap".
10627 "spare"
10629 The number of spare devices.
10630 If not set, this defaults to 0.
10632 "chunk"
10634 The chunk size in bytes.
10635 The "chunk" parameter does not make sense, and should not be
10637 specified, when "level" is "raid1" (which is the default; see
10638 below).
10639 "level"
10641 The RAID level, which can be one of: "linear", "raid0", 0,
10642 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
10643 "raid10", 10. Some of these are synonymous, and more levels may be
10644 added in future.
10645 If not set, this defaults to "raid1".
10647 This function returns 0 on success or -1 on error.
10649 This function depends on the feature "mdadm". See also
10651 "guestfs_feature_available".
10652 (Added in 1.15.6)
10654 guestfs_md_create_va
10656 int
10657 guestfs_md_create_va (guestfs_h *g,
10658 const char *name,
10659 char *const *devices,
10660 va_list args);
10661 This is the "va_list variant" of "guestfs_md_create".
10663 See "CALLS WITH OPTIONAL ARGUMENTS".
10665 guestfs_md_create_argv
10667 int
10668 guestfs_md_create_argv (guestfs_h *g,
10669 const char *name,
10670 char *const *devices,
10671 const struct guestfs_md_create_argv *optargs);
10672 This is the "argv variant" of "guestfs_md_create".
10674 See "CALLS WITH OPTIONAL ARGUMENTS".
10676 guestfs_md_detail
10678 char **
10679 guestfs_md_detail (guestfs_h *g,
10680 const char *md);
10681 This command exposes the output of "mdadm -DY <md>". The following
10683 fields are usually present in the returned hash. Other fields may also
10684 be present.
10685 "level"
10687 The raid level of the MD device.
10688 "devices"
10690 The number of underlying devices in the MD device.
10691 "metadata"
10693 The metadata version used.
10694 "uuid"
10696 The UUID of the MD device.
10697 "name"
10699 The name of the MD device.
10700 This function returns a NULL-terminated array of strings, or NULL if
10702 there was an error. The array of strings will always have length
10703 "2n+1", where "n" keys and values alternate, followed by the trailing
10704 NULL entry. The caller must free the strings and the array after use.
10705 This function depends on the feature "mdadm". See also
10707 "guestfs_feature_available".
10708 (Added in 1.15.6)
10710 guestfs_md_stat
10712 struct guestfs_mdstat_list *
10713 guestfs_md_stat (guestfs_h *g,
10714 const char *md);
10715 This call returns a list of the underlying devices which make up the
10717 single software RAID array device "md".
10718 To get a list of software RAID devices, call "guestfs_list_md_devices".
10720 Each structure returned corresponds to one device along with additional
10722 status information:
10723 "mdstat_device"
10725 The name of the underlying device.
10726 "mdstat_index"
10728 The index of this device within the array.
10729 "mdstat_flags"
10731 Flags associated with this device. This is a string containing (in
10732 no specific order) zero or more of the following flags:
10733 "W" write-mostly
10735 "F" device is faulty
10737 "S" device is a RAID spare
10739 "R" replacement
10741 This function returns a "struct guestfs_mdstat_list *", or NULL if
10743 there was an error. The caller must call "guestfs_free_mdstat_list"
10744 after use.
10745 This function depends on the feature "mdadm". See also
10747 "guestfs_feature_available".
10748 (Added in 1.17.21)
10750 guestfs_md_stop
10752 int
10753 guestfs_md_stop (guestfs_h *g,
10754 const char *md);
10755 This command deactivates the MD array named "md". The device is
10757 stopped, but it is not destroyed or zeroed.
10758 This function returns 0 on success or -1 on error.
10760 This function depends on the feature "mdadm". See also
10762 "guestfs_feature_available".
10763 (Added in 1.15.6)
10765 guestfs_mkdir
10767 int
10768 guestfs_mkdir (guestfs_h *g,
10769 const char *path);
10770 Create a directory named "path".
10772 This function returns 0 on success or -1 on error.
10774 (Added in 0.8)
10776 guestfs_mkdir_mode
10778 int
10779 guestfs_mkdir_mode (guestfs_h *g,
10780 const char *path,
10781 int mode);
10782 This command creates a directory, setting the initial permissions of
10784 the directory to "mode".
10785 For common Linux filesystems, the actual mode which is set will be
10787 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10788 the mode in other ways.
10789 See also "guestfs_mkdir", "guestfs_umask"
10791 This function returns 0 on success or -1 on error.
10793 (Added in 1.0.77)
10795 guestfs_mkdir_p
10797 int
10798 guestfs_mkdir_p (guestfs_h *g,
10799 const char *path);
10800 Create a directory named "path", creating any parent directories as
10802 necessary. This is like the "mkdir -p" shell command.
10803 This function returns 0 on success or -1 on error.
10805 (Added in 0.8)
10807 guestfs_mkdtemp
10809 char *
10810 guestfs_mkdtemp (guestfs_h *g,
10811 const char *tmpl);
10812 This command creates a temporary directory. The "tmpl" parameter
10814 should be a full pathname for the temporary directory name with the
10815 final six characters being "XXXXXX".
10816 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10818 one being suitable for Windows filesystems.
10819 The name of the temporary directory that was created is returned.
10821 The temporary directory is created with mode 0700 and is owned by root.
10823 The caller is responsible for deleting the temporary directory and its
10825 contents after use.
10826 See also: mkdtemp(3)
10828 This function returns a string, or NULL on error. The caller must free
10830 the returned string after use.
10831 (Added in 1.0.54)
10833 guestfs_mke2fs
10835 int
10836 guestfs_mke2fs (guestfs_h *g,
10837 const char *device,
10838 ...);
10839 You may supply a list of optional arguments to this call. Use zero or
10841 more of the following pairs of parameters, and terminate the list with
10842 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10843 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10845 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10846 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10847 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10848 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10849 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10850 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10851 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10852 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10853 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10854 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10855 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10856 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10857 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10858 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10859 GUESTFS_MKE2FS_LABEL, const char *label,
10860 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10861 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10862 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10863 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10864 GUESTFS_MKE2FS_UUID, const char *uuid,
10865 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10866 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10867 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10868 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10869 GUESTFS_MKE2FS_TESTFS, int testfs,
10870 GUESTFS_MKE2FS_DISCARD, int discard,
10871 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10872 GUESTFS_MKE2FS_EXTENT, int extent,
10873 GUESTFS_MKE2FS_FILETYPE, int filetype,
10874 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10875 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10876 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10877 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10878 GUESTFS_MKE2FS_QUOTA, int quota,
10879 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10880 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10881 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10882 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10884 "device".
10885 The optional "blockscount" is the size of the filesystem in blocks. If
10887 omitted it defaults to the size of "device". Note if the filesystem is
10888 too small to contain a journal, "mke2fs" will silently create an ext2
10889 filesystem instead.
10890 This function returns 0 on success or -1 on error.
10892 (Added in 1.19.44)
10894 guestfs_mke2fs_va
10896 int
10897 guestfs_mke2fs_va (guestfs_h *g,
10898 const char *device,
10899 va_list args);
10900 This is the "va_list variant" of "guestfs_mke2fs".
10902 See "CALLS WITH OPTIONAL ARGUMENTS".
10904 guestfs_mke2fs_argv
10906 int
10907 guestfs_mke2fs_argv (guestfs_h *g,
10908 const char *device,
10909 const struct guestfs_mke2fs_argv *optargs);
10910 This is the "argv variant" of "guestfs_mke2fs".
10912 See "CALLS WITH OPTIONAL ARGUMENTS".
10914 guestfs_mke2fs_J
10916 int
10917 guestfs_mke2fs_J (guestfs_h *g,
10918 const char *fstype,
10919 int blocksize,
10920 const char *device,
10921 const char *journal);
10922 This function is deprecated. In new code, use the "guestfs_mke2fs"
10924 call instead.
10925 Deprecated functions will not be removed from the API, but the fact
10927 that they are deprecated indicates that there are problems with correct
10928 use of these functions.
10929 This creates an ext2/3/4 filesystem on "device" with an external
10931 journal on "journal". It is equivalent to the command:
10932 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10934 See also "guestfs_mke2journal".
10936 This function returns 0 on success or -1 on error.
10938 (Added in 1.0.68)
10940 guestfs_mke2fs_JL
10942 int
10943 guestfs_mke2fs_JL (guestfs_h *g,
10944 const char *fstype,
10945 int blocksize,
10946 const char *device,
10947 const char *label);
10948 This function is deprecated. In new code, use the "guestfs_mke2fs"
10950 call instead.
10951 Deprecated functions will not be removed from the API, but the fact
10953 that they are deprecated indicates that there are problems with correct
10954 use of these functions.
10955 This creates an ext2/3/4 filesystem on "device" with an external
10957 journal on the journal labeled "label".
10958 See also "guestfs_mke2journal_L".
10960 This function returns 0 on success or -1 on error.
10962 (Added in 1.0.68)
10964 guestfs_mke2fs_JU
10966 int
10967 guestfs_mke2fs_JU (guestfs_h *g,
10968 const char *fstype,
10969 int blocksize,
10970 const char *device,
10971 const char *uuid);
10972 This function is deprecated. In new code, use the "guestfs_mke2fs"
10974 call instead.
10975 Deprecated functions will not be removed from the API, but the fact
10977 that they are deprecated indicates that there are problems with correct
10978 use of these functions.
10979 This creates an ext2/3/4 filesystem on "device" with an external
10981 journal on the journal with UUID "uuid".
10982 See also "guestfs_mke2journal_U".
10984 This function returns 0 on success or -1 on error.
10986 This function depends on the feature "linuxfsuuid". See also
10988 "guestfs_feature_available".
10989 (Added in 1.0.68)
10991 guestfs_mke2journal
10993 int
10994 guestfs_mke2journal (guestfs_h *g,
10995 int blocksize,
10996 const char *device);
10997 This function is deprecated. In new code, use the "guestfs_mke2fs"
10999 call instead.
11000 Deprecated functions will not be removed from the API, but the fact
11002 that they are deprecated indicates that there are problems with correct
11003 use of these functions.
11004 This creates an ext2 external journal on "device". It is equivalent to
11006 the command:
11007 mke2fs -O journal_dev -b blocksize device
11009 This function returns 0 on success or -1 on error.
11011 (Added in 1.0.68)
11013 guestfs_mke2journal_L
11015 int
11016 guestfs_mke2journal_L (guestfs_h *g,
11017 int blocksize,
11018 const char *label,
11019 const char *device);
11020 This function is deprecated. In new code, use the "guestfs_mke2fs"
11022 call instead.
11023 Deprecated functions will not be removed from the API, but the fact
11025 that they are deprecated indicates that there are problems with correct
11026 use of these functions.
11027 This creates an ext2 external journal on "device" with label "label".
11029 This function returns 0 on success or -1 on error.
11031 (Added in 1.0.68)
11033 guestfs_mke2journal_U
11035 int
11036 guestfs_mke2journal_U (guestfs_h *g,
11037 int blocksize,
11038 const char *uuid,
11039 const char *device);
11040 This function is deprecated. In new code, use the "guestfs_mke2fs"
11042 call instead.
11043 Deprecated functions will not be removed from the API, but the fact
11045 that they are deprecated indicates that there are problems with correct
11046 use of these functions.
11047 This creates an ext2 external journal on "device" with UUID "uuid".
11049 This function returns 0 on success or -1 on error.
11051 This function depends on the feature "linuxfsuuid". See also
11053 "guestfs_feature_available".
11054 (Added in 1.0.68)
11056 guestfs_mkfifo
11058 int
11059 guestfs_mkfifo (guestfs_h *g,
11060 int mode,
11061 const char *path);
11062 This call creates a FIFO (named pipe) called "path" with mode "mode".
11064 It is just a convenient wrapper around "guestfs_mknod".
11065 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11067 The mode actually set is affected by the umask.
11069 This function returns 0 on success or -1 on error.
11071 This function depends on the feature "mknod". See also
11073 "guestfs_feature_available".
11074 (Added in 1.0.55)
11076 guestfs_mkfs
11078 int
11079 guestfs_mkfs (guestfs_h *g,
11080 const char *fstype,
11081 const char *device);
11082 This function is provided for backwards compatibility with earlier
11084 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
11085 optional arguments.
11086 (Added in 0.8)
11088 guestfs_mkfs_opts
11090 int
11091 guestfs_mkfs_opts (guestfs_h *g,
11092 const char *fstype,
11093 const char *device,
11094 ...);
11095 You may supply a list of optional arguments to this call. Use zero or
11097 more of the following pairs of parameters, and terminate the list with
11098 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11099 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
11101 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
11102 GUESTFS_MKFS_OPTS_INODE, int inode,
11103 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
11104 GUESTFS_MKFS_OPTS_LABEL, const char *label,
11105 This function creates a filesystem on "device". The filesystem type is
11107 "fstype", for example "ext3".
11108 The optional arguments are:
11110 "blocksize"
11112 The filesystem block size. Supported block sizes depend on the
11113 filesystem type, but typically they are 1024, 2048 or 4096 for
11114 Linux ext2/3 filesystems.
11115 For VFAT and NTFS the "blocksize" parameter is treated as the
11117 requested cluster size.
11118 For UFS block sizes, please see mkfs.ufs(8).
11120 "features"
11122 This passes the -O parameter to the external mkfs program.
11123 For certain filesystem types, this allows extra filesystem features
11125 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
11126 You cannot use this optional parameter with the "gfs" or "gfs2"
11128 filesystem type.
11129 "inode"
11131 This passes the -I parameter to the external mke2fs(8) program
11132 which sets the inode size (only for ext2/3/4 filesystems at
11133 present).
11134 "sectorsize"
11136 This passes the -S parameter to external mkfs.ufs(8) program, which
11137 sets sector size for ufs filesystem.
11138 This function returns 0 on success or -1 on error.
11140 (Added in 0.8)
11142 guestfs_mkfs_opts_va
11144 int
11145 guestfs_mkfs_opts_va (guestfs_h *g,
11146 const char *fstype,
11147 const char *device,
11148 va_list args);
11149 This is the "va_list variant" of "guestfs_mkfs_opts".
11151 See "CALLS WITH OPTIONAL ARGUMENTS".
11153 guestfs_mkfs_opts_argv
11155 int
11156 guestfs_mkfs_opts_argv (guestfs_h *g,
11157 const char *fstype,
11158 const char *device,
11159 const struct guestfs_mkfs_opts_argv *optargs);
11160 This is the "argv variant" of "guestfs_mkfs_opts".
11162 See "CALLS WITH OPTIONAL ARGUMENTS".
11164 guestfs_mkfs_b
11166 int
11167 guestfs_mkfs_b (guestfs_h *g,
11168 const char *fstype,
11169 int blocksize,
11170 const char *device);
11171 This function is deprecated. In new code, use the "guestfs_mkfs" call
11173 instead.
11174 Deprecated functions will not be removed from the API, but the fact
11176 that they are deprecated indicates that there are problems with correct
11177 use of these functions.
11178 This call is similar to "guestfs_mkfs", but it allows you to control
11180 the block size of the resulting filesystem. Supported block sizes
11181 depend on the filesystem type, but typically they are 1024, 2048 or
11182 4096 only.
11183 For VFAT and NTFS the "blocksize" parameter is treated as the requested
11185 cluster size.
11186 This function returns 0 on success or -1 on error.
11188 (Added in 1.0.68)
11190 guestfs_mkfs_btrfs
11192 int
11193 guestfs_mkfs_btrfs (guestfs_h *g,
11194 char *const *devices,
11195 ...);
11196 You may supply a list of optional arguments to this call. Use zero or
11198 more of the following pairs of parameters, and terminate the list with
11199 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11200 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11202 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11203 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11204 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11205 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11206 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11207 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11208 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11209 Create a btrfs filesystem, allowing all configurables to be set. For
11211 more information on the optional arguments, see mkfs.btrfs(8).
11212 Since btrfs filesystems can span multiple devices, this takes a non-
11214 empty list of devices.
11215 To create general filesystems, use "guestfs_mkfs".
11217 This function returns 0 on success or -1 on error.
11219 This function depends on the feature "btrfs". See also
11221 "guestfs_feature_available".
11222 (Added in 1.17.25)
11224 guestfs_mkfs_btrfs_va
11226 int
11227 guestfs_mkfs_btrfs_va (guestfs_h *g,
11228 char *const *devices,
11229 va_list args);
11230 This is the "va_list variant" of "guestfs_mkfs_btrfs".
11232 See "CALLS WITH OPTIONAL ARGUMENTS".
11234 guestfs_mkfs_btrfs_argv
11236 int
11237 guestfs_mkfs_btrfs_argv (guestfs_h *g,
11238 char *const *devices,
11239 const struct guestfs_mkfs_btrfs_argv *optargs);
11240 This is the "argv variant" of "guestfs_mkfs_btrfs".
11242 See "CALLS WITH OPTIONAL ARGUMENTS".
11244 guestfs_mklost_and_found
11246 int
11247 guestfs_mklost_and_found (guestfs_h *g,
11248 const char *mountpoint);
11249 Make the "lost+found" directory, normally in the root directory of an
11251 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
11252 to create the "lost+found" directory.
11253 This function returns 0 on success or -1 on error.
11255 (Added in 1.19.56)
11257 guestfs_mkmountpoint
11259 int
11260 guestfs_mkmountpoint (guestfs_h *g,
11261 const char *exemptpath);
11262 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11264 that can be used to create extra mountpoints before mounting the first
11265 filesystem.
11266 These calls are only necessary in some very limited circumstances,
11268 mainly the case where you want to mount a mix of unrelated and/or read-
11269 only filesystems together.
11270 For example, live CDs often contain a "Russian doll" nest of
11272 filesystems, an ISO outer layer, with a squashfs image inside, with an
11273 ext2/3 image inside that. You can unpack this as follows in guestfish:
11274 add-ro Fedora-11-i686-Live.iso
11276 run
11277 mkmountpoint /cd
11278 mkmountpoint /sqsh
11279 mkmountpoint /ext3fs
11280 mount /dev/sda /cd
11281 mount-loop /cd/LiveOS/squashfs.img /sqsh
11282 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11283 The inner filesystem is now unpacked under the /ext3fs mountpoint.
11285 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11287 You may get unexpected errors if you try to mix these calls. It is
11288 safest to manually unmount filesystems and remove mountpoints after
11289 use.
11290 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11292 first, so for this to work for manual mountpoints, you must ensure that
11293 the innermost mountpoints have the longest pathnames, as in the example
11294 code above.
11295 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11297 Autosync [see "guestfs_set_autosync", this is set by default on
11299 handles] can cause "guestfs_umount_all" to be called when the handle is
11300 closed which can also trigger these issues.
11301 This function returns 0 on success or -1 on error.
11303 (Added in 1.0.62)
11305 guestfs_mknod
11307 int
11308 guestfs_mknod (guestfs_h *g,
11309 int mode,
11310 int devmajor,
11311 int devminor,
11312 const char *path);
11313 This call creates block or character special devices, or named pipes
11315 (FIFOs).
11316 The "mode" parameter should be the mode, using the standard constants.
11318 "devmajor" and "devminor" are the device major and minor numbers, only
11319 used when creating block and character special devices.
11320 Note that, just like mknod(2), the mode must be bitwise OR'd with
11322 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11323 a regular file). These constants are available in the standard Linux
11324 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11325 "guestfs_mkfifo" which are wrappers around this command which bitwise
11326 OR in the appropriate constant for you.
11327 The mode actually set is affected by the umask.
11329 This function returns 0 on success or -1 on error.
11331 This function depends on the feature "mknod". See also
11333 "guestfs_feature_available".
11334 (Added in 1.0.55)
11336 guestfs_mknod_b
11338 int
11339 guestfs_mknod_b (guestfs_h *g,
11340 int mode,
11341 int devmajor,
11342 int devminor,
11343 const char *path);
11344 This call creates a block device node called "path" with mode "mode"
11346 and device major/minor "devmajor" and "devminor". It is just a
11347 convenient wrapper around "guestfs_mknod".
11348 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11350 The mode actually set is affected by the umask.
11352 This function returns 0 on success or -1 on error.
11354 This function depends on the feature "mknod". See also
11356 "guestfs_feature_available".
11357 (Added in 1.0.55)
11359 guestfs_mknod_c
11361 int
11362 guestfs_mknod_c (guestfs_h *g,
11363 int mode,
11364 int devmajor,
11365 int devminor,
11366 const char *path);
11367 This call creates a char device node called "path" with mode "mode" and
11369 device major/minor "devmajor" and "devminor". It is just a convenient
11370 wrapper around "guestfs_mknod".
11371 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11373 The mode actually set is affected by the umask.
11375 This function returns 0 on success or -1 on error.
11377 This function depends on the feature "mknod". See also
11379 "guestfs_feature_available".
11380 (Added in 1.0.55)
11382 guestfs_mksquashfs
11384 int
11385 guestfs_mksquashfs (guestfs_h *g,
11386 const char *path,
11387 const char *filename,
11388 ...);
11389 You may supply a list of optional arguments to this call. Use zero or
11391 more of the following pairs of parameters, and terminate the list with
11392 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11393 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11395 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11396 Create a squashfs filesystem for the specified "path".
11398 The optional "compress" flag controls compression. If not given, then
11400 the output compressed using "gzip". Otherwise one of the following
11401 strings may be given to select the compression type of the squashfs:
11402 "gzip", "lzma", "lzo", "lz4", "xz".
11403 The other optional arguments are:
11405 "excludes"
11407 A list of wildcards. Files are excluded if they match any of the
11408 wildcards.
11409 Please note that this API may fail when used to compress directories
11411 with large files, such as the resulting squashfs will be over 3GB big.
11412 This function returns 0 on success or -1 on error.
11414 This function depends on the feature "squashfs". See also
11416 "guestfs_feature_available".
11417 (Added in 1.35.25)
11419 guestfs_mksquashfs_va
11421 int
11422 guestfs_mksquashfs_va (guestfs_h *g,
11423 const char *path,
11424 const char *filename,
11425 va_list args);
11426 This is the "va_list variant" of "guestfs_mksquashfs".
11428 See "CALLS WITH OPTIONAL ARGUMENTS".
11430 guestfs_mksquashfs_argv
11432 int
11433 guestfs_mksquashfs_argv (guestfs_h *g,
11434 const char *path,
11435 const char *filename,
11436 const struct guestfs_mksquashfs_argv *optargs);
11437 This is the "argv variant" of "guestfs_mksquashfs".
11439 See "CALLS WITH OPTIONAL ARGUMENTS".
11441 guestfs_mkswap
11443 int
11444 guestfs_mkswap (guestfs_h *g,
11445 const char *device);
11446 This function is provided for backwards compatibility with earlier
11448 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11449 optional arguments.
11450 (Added in 1.0.55)
11452 guestfs_mkswap_opts
11454 int
11455 guestfs_mkswap_opts (guestfs_h *g,
11456 const char *device,
11457 ...);
11458 You may supply a list of optional arguments to this call. Use zero or
11460 more of the following pairs of parameters, and terminate the list with
11461 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11462 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11464 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11465 Create a Linux swap partition on "device".
11467 The option arguments "label" and "uuid" allow you to set the label
11469 and/or UUID of the new swap partition.
11470 This function returns 0 on success or -1 on error.
11472 (Added in 1.0.55)
11474 guestfs_mkswap_opts_va
11476 int
11477 guestfs_mkswap_opts_va (guestfs_h *g,
11478 const char *device,
11479 va_list args);
11480 This is the "va_list variant" of "guestfs_mkswap_opts".
11482 See "CALLS WITH OPTIONAL ARGUMENTS".
11484 guestfs_mkswap_opts_argv
11486 int
11487 guestfs_mkswap_opts_argv (guestfs_h *g,
11488 const char *device,
11489 const struct guestfs_mkswap_opts_argv *optargs);
11490 This is the "argv variant" of "guestfs_mkswap_opts".
11492 See "CALLS WITH OPTIONAL ARGUMENTS".
11494 guestfs_mkswap_L
11496 int
11497 guestfs_mkswap_L (guestfs_h *g,
11498 const char *label,
11499 const char *device);
11500 This function is deprecated. In new code, use the "guestfs_mkswap"
11502 call instead.
11503 Deprecated functions will not be removed from the API, but the fact
11505 that they are deprecated indicates that there are problems with correct
11506 use of these functions.
11507 Create a swap partition on "device" with label "label".
11509 Note that you cannot attach a swap label to a block device (eg.
11511 /dev/sda), just to a partition. This appears to be a limitation of the
11512 kernel or swap tools.
11513 This function returns 0 on success or -1 on error.
11515 (Added in 1.0.55)
11517 guestfs_mkswap_U
11519 int
11520 guestfs_mkswap_U (guestfs_h *g,
11521 const char *uuid,
11522 const char *device);
11523 This function is deprecated. In new code, use the "guestfs_mkswap"
11525 call instead.
11526 Deprecated functions will not be removed from the API, but the fact
11528 that they are deprecated indicates that there are problems with correct
11529 use of these functions.
11530 Create a swap partition on "device" with UUID "uuid".
11532 This function returns 0 on success or -1 on error.
11534 This function depends on the feature "linuxfsuuid". See also
11536 "guestfs_feature_available".
11537 (Added in 1.0.55)
11539 guestfs_mkswap_file
11541 int
11542 guestfs_mkswap_file (guestfs_h *g,
11543 const char *path);
11544 Create a swap file.
11546 This command just writes a swap file signature to an existing file. To
11548 create the file itself, use something like "guestfs_fallocate".
11549 This function returns 0 on success or -1 on error.
11551 (Added in 1.0.66)
11553 guestfs_mktemp
11555 char *
11556 guestfs_mktemp (guestfs_h *g,
11557 const char *tmpl,
11558 ...);
11559 You may supply a list of optional arguments to this call. Use zero or
11561 more of the following pairs of parameters, and terminate the list with
11562 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11563 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11565 This command creates a temporary file. The "tmpl" parameter should be
11567 a full pathname for the temporary directory name with the final six
11568 characters being "XXXXXX".
11569 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11571 one being suitable for Windows filesystems.
11572 The name of the temporary file that was created is returned.
11574 The temporary file is created with mode 0600 and is owned by root.
11576 The caller is responsible for deleting the temporary file after use.
11578 If the optional "suffix" parameter is given, then the suffix (eg.
11580 ".txt") is appended to the temporary name.
11581 See also: "guestfs_mkdtemp".
11583 This function returns a string, or NULL on error. The caller must free
11585 the returned string after use.
11586 (Added in 1.19.53)
11588 guestfs_mktemp_va
11590 char *
11591 guestfs_mktemp_va (guestfs_h *g,
11592 const char *tmpl,
11593 va_list args);
11594 This is the "va_list variant" of "guestfs_mktemp".
11596 See "CALLS WITH OPTIONAL ARGUMENTS".
11598 guestfs_mktemp_argv
11600 char *
11601 guestfs_mktemp_argv (guestfs_h *g,
11602 const char *tmpl,
11603 const struct guestfs_mktemp_argv *optargs);
11604 This is the "argv variant" of "guestfs_mktemp".
11606 See "CALLS WITH OPTIONAL ARGUMENTS".
11608 guestfs_modprobe
11610 int
11611 guestfs_modprobe (guestfs_h *g,
11612 const char *modulename);
11613 This loads a kernel module in the appliance.
11615 This function returns 0 on success or -1 on error.
11617 This function depends on the feature "linuxmodules". See also
11619 "guestfs_feature_available".
11620 (Added in 1.0.68)
11622 guestfs_mount
11624 int
11625 guestfs_mount (guestfs_h *g,
11626 const char *mountable,
11627 const char *mountpoint);
11628 Mount a guest disk at a position in the filesystem. Block devices are
11630 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11631 If those block devices contain partitions, they will have the usual
11632 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11633 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11634 "guestfs_inspect_get_mountpoints".
11635 The rules are the same as for mount(2): A filesystem must first be
11637 mounted on / before others can be mounted. Other filesystems can only
11638 be mounted on directories which already exist.
11639 The mounted filesystem is writable, if we have sufficient permissions
11641 on the underlying device.
11642 Before libguestfs 1.13.16, this call implicitly added the options
11644 "sync" and "noatime". The "sync" option greatly slowed writes and
11645 caused many problems for users. If your program might need to work
11646 with older versions of libguestfs, use "guestfs_mount_options" instead
11647 (using an empty string for the first parameter if you don't want any
11648 options).
11649 This function returns 0 on success or -1 on error.
11651 (Added in 0.3)
11653 guestfs_mount_9p
11655 int
11656 guestfs_mount_9p (guestfs_h *g,
11657 const char *mounttag,
11658 const char *mountpoint,
11659 ...);
11660 This function is deprecated. There is no replacement. Consult the API
11662 documentation in guestfs(3) for further information.
11663 Deprecated functions will not be removed from the API, but the fact
11665 that they are deprecated indicates that there are problems with correct
11666 use of these functions.
11667 You may supply a list of optional arguments to this call. Use zero or
11669 more of the following pairs of parameters, and terminate the list with
11670 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11671 GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11673 This call does nothing and returns an error.
11675 This function returns 0 on success or -1 on error.
11677 (Added in 1.11.12)
11679 guestfs_mount_9p_va
11681 int
11682 guestfs_mount_9p_va (guestfs_h *g,
11683 const char *mounttag,
11684 const char *mountpoint,
11685 va_list args);
11686 This is the "va_list variant" of "guestfs_mount_9p".
11688 See "CALLS WITH OPTIONAL ARGUMENTS".
11690 guestfs_mount_9p_argv
11692 int
11693 guestfs_mount_9p_argv (guestfs_h *g,
11694 const char *mounttag,
11695 const char *mountpoint,
11696 const struct guestfs_mount_9p_argv *optargs);
11697 This is the "argv variant" of "guestfs_mount_9p".
11699 See "CALLS WITH OPTIONAL ARGUMENTS".
11701 guestfs_mount_local
11703 int
11704 guestfs_mount_local (guestfs_h *g,
11705 const char *localmountpoint,
11706 ...);
11707 You may supply a list of optional arguments to this call. Use zero or
11709 more of the following pairs of parameters, and terminate the list with
11710 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11711 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11713 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11714 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11715 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11716 This call exports the libguestfs-accessible filesystem to a local
11718 mountpoint (directory) called "localmountpoint". Ordinary reads and
11719 writes to files and directories under "localmountpoint" are redirected
11720 through libguestfs.
11721 If the optional "readonly" flag is set to true, then writes to the
11723 filesystem return error "EROFS".
11724 "options" is a comma-separated list of mount options. See
11726 guestmount(1) for some useful options.
11727 "cachetimeout" sets the timeout (in seconds) for cached directory
11729 entries. The default is 60 seconds. See guestmount(1) for further
11730 information.
11731 If "debugcalls" is set to true, then additional debugging information
11733 is generated for every FUSE call.
11734 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11736 processing requests (access to it will block). You have to call
11737 "guestfs_mount_local_run" to run the main loop.
11738 See "MOUNT LOCAL" for full documentation.
11740 This function returns 0 on success or -1 on error.
11742 (Added in 1.17.22)
11744 guestfs_mount_local_va
11746 int
11747 guestfs_mount_local_va (guestfs_h *g,
11748 const char *localmountpoint,
11749 va_list args);
11750 This is the "va_list variant" of "guestfs_mount_local".
11752 See "CALLS WITH OPTIONAL ARGUMENTS".
11754 guestfs_mount_local_argv
11756 int
11757 guestfs_mount_local_argv (guestfs_h *g,
11758 const char *localmountpoint,
11759 const struct guestfs_mount_local_argv *optargs);
11760 This is the "argv variant" of "guestfs_mount_local".
11762 See "CALLS WITH OPTIONAL ARGUMENTS".
11764 guestfs_mount_local_run
11766 int
11767 guestfs_mount_local_run (guestfs_h *g);
11768 Run the main loop which translates kernel calls to libguestfs calls.
11770 This should only be called after "guestfs_mount_local" returns
11772 successfully. The call will not return until the filesystem is
11773 unmounted.
11774 Note you must not make concurrent libguestfs calls on the same handle
11776 from another thread.
11777 You may call this from a different thread than the one which called
11779 "guestfs_mount_local", subject to the usual rules for threads and
11780 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11781 See "MOUNT LOCAL" for full documentation.
11783 This function returns 0 on success or -1 on error.
11785 (Added in 1.17.22)
11787 guestfs_mount_loop
11789 int
11790 guestfs_mount_loop (guestfs_h *g,
11791 const char *file,
11792 const char *mountpoint);
11793 This command lets you mount file (a filesystem image in a file) on a
11795 mount point. It is entirely equivalent to the command "mount -o loop
11796 file mountpoint".
11797 This function returns 0 on success or -1 on error.
11799 (Added in 1.0.54)
11801 guestfs_mount_options
11803 int
11804 guestfs_mount_options (guestfs_h *g,
11805 const char *options,
11806 const char *mountable,
11807 const char *mountpoint);
11808 This is the same as the "guestfs_mount" command, but it allows you to
11810 set the mount options as for the mount(8) -o flag.
11811 If the "options" parameter is an empty string, then no options are
11813 passed (all options default to whatever the filesystem uses).
11814 This function returns 0 on success or -1 on error.
11816 (Added in 1.0.10)
11818 guestfs_mount_ro
11820 int
11821 guestfs_mount_ro (guestfs_h *g,
11822 const char *mountable,
11823 const char *mountpoint);
11824 This is the same as the "guestfs_mount" command, but it mounts the
11826 filesystem with the read-only (-o ro) flag.
11827 This function returns 0 on success or -1 on error.
11829 (Added in 1.0.10)
11831 guestfs_mount_vfs
11833 int
11834 guestfs_mount_vfs (guestfs_h *g,
11835 const char *options,
11836 const char *vfstype,
11837 const char *mountable,
11838 const char *mountpoint);
11839 This is the same as the "guestfs_mount" command, but it allows you to
11841 set both the mount options and the vfstype as for the mount(8) -o and
11842 -t flags.
11843 This function returns 0 on success or -1 on error.
11845 (Added in 1.0.10)
11847 guestfs_mountable_device
11849 char *
11850 guestfs_mountable_device (guestfs_h *g,
11851 const char *mountable);
11852 Returns the device name of a mountable. In quite a lot of cases, the
11854 mountable is the device name.
11855 However this doesn't apply for btrfs subvolumes, where the mountable is
11857 a combination of both the device name and the subvolume path (see also
11858 "guestfs_mountable_subvolume" to extract the subvolume path of the
11859 mountable if any).
11860 This function returns a string, or NULL on error. The caller must free
11862 the returned string after use.
11863 (Added in 1.33.15)
11865 guestfs_mountable_subvolume
11867 char *
11868 guestfs_mountable_subvolume (guestfs_h *g,
11869 const char *mountable);
11870 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11872 are a combination of both the device name and the subvolume path (see
11873 also "guestfs_mountable_device" to extract the device of the
11874 mountable).
11875 If the mountable does not represent a btrfs subvolume, then this
11877 function fails and the "errno" is set to "EINVAL".
11878 This function returns a string, or NULL on error. The caller must free
11880 the returned string after use.
11881 (Added in 1.33.15)
11883 guestfs_mountpoints
11885 char **
11886 guestfs_mountpoints (guestfs_h *g);
11887 This call is similar to "guestfs_mounts". That call returns a list of
11889 devices. This one returns a hash table (map) of device name to
11890 directory where the device is mounted.
11891 This function returns a NULL-terminated array of strings, or NULL if
11893 there was an error. The array of strings will always have length
11894 "2n+1", where "n" keys and values alternate, followed by the trailing
11895 NULL entry. The caller must free the strings and the array after use.
11896 (Added in 1.0.62)
11898 guestfs_mounts
11900 char **
11901 guestfs_mounts (guestfs_h *g);
11902 This returns the list of currently mounted filesystems. It returns the
11904 list of devices (eg. /dev/sda1, /dev/VG/LV).
11905 Some internal mounts are not shown.
11907 See also: "guestfs_mountpoints"
11909 This function returns a NULL-terminated array of strings (like
11911 environ(3)), or NULL if there was an error. The caller must free the
11912 strings and the array after use.
11913 (Added in 0.8)
11915 guestfs_mv
11917 int
11918 guestfs_mv (guestfs_h *g,
11919 const char *src,
11920 const char *dest);
11921 This moves a file from "src" to "dest" where "dest" is either a
11923 destination filename or destination directory.
11924 See also: "guestfs_rename".
11926 This function returns 0 on success or -1 on error.
11928 (Added in 1.0.18)
11930 guestfs_nr_devices
11932 int
11933 guestfs_nr_devices (guestfs_h *g);
11934 This returns the number of whole block devices that were added. This
11936 is the same as the number of devices that would be returned if you
11937 called "guestfs_list_devices".
11938 To find out the maximum number of devices that could be added, call
11940 "guestfs_max_disks".
11941 On error this function returns -1.
11943 (Added in 1.19.15)
11945 guestfs_ntfs_3g_probe
11947 int
11948 guestfs_ntfs_3g_probe (guestfs_h *g,
11949 int rw,
11950 const char *device);
11951 This command runs the ntfs-3g.probe(8) command which probes an NTFS
11953 "device" for mountability. (Not all NTFS volumes can be mounted read-
11954 write, and some cannot be mounted at all).
11955 "rw" is a boolean flag. Set it to true if you want to test if the
11957 volume can be mounted read-write. Set it to false if you want to test
11958 if the volume can be mounted read-only.
11959 The return value is an integer which 0 if the operation would succeed,
11961 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
11962 On error this function returns -1.
11964 This function depends on the feature "ntfs3g". See also
11966 "guestfs_feature_available".
11967 (Added in 1.0.43)
11969 guestfs_ntfscat_i
11971 int
11972 guestfs_ntfscat_i (guestfs_h *g,
11973 const char *device,
11974 int64_t inode,
11975 const char *filename);
11976 Download a file given its inode from a NTFS filesystem and save it as
11978 filename on the local machine.
11979 This allows to download some otherwise inaccessible files such as the
11981 ones within the $Extend folder.
11982 The filesystem from which to extract the file must be unmounted,
11984 otherwise the call will fail.
11985 This function returns 0 on success or -1 on error.
11987 This long-running command can generate progress notification messages
11989 so that the caller can display a progress bar or indicator. To receive
11990 these messages, the caller must register a progress event callback.
11991 See "GUESTFS_EVENT_PROGRESS".
11992 (Added in 1.33.14)
11994 guestfs_ntfsclone_in
11996 int
11997 guestfs_ntfsclone_in (guestfs_h *g,
11998 const char *backupfile,
11999 const char *device);
12000 Restore the "backupfile" (from a previous call to
12002 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
12003 of this device.
12004 This function returns 0 on success or -1 on error.
12006 This function depends on the feature "ntfs3g". See also
12008 "guestfs_feature_available".
12009 (Added in 1.17.9)
12011 guestfs_ntfsclone_out
12013 int
12014 guestfs_ntfsclone_out (guestfs_h *g,
12015 const char *device,
12016 const char *backupfile,
12017 ...);
12018 You may supply a list of optional arguments to this call. Use zero or
12020 more of the following pairs of parameters, and terminate the list with
12021 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12022 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
12024 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
12025 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
12026 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
12027 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
12028 Stream the NTFS filesystem "device" to the local file "backupfile".
12030 The format used for the backup file is a special format used by the
12031 ntfsclone(8) tool.
12032 If the optional "metadataonly" flag is true, then only the metadata is
12034 saved, losing all the user data (this is useful for diagnosing some
12035 filesystem problems).
12036 The optional "rescue", "ignorefscheck", "preservetimestamps" and
12038 "force" flags have precise meanings detailed in the ntfsclone(8) man
12039 page.
12040 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
12042 device.
12043 This function returns 0 on success or -1 on error.
12045 This function depends on the feature "ntfs3g". See also
12047 "guestfs_feature_available".
12048 (Added in 1.17.9)
12050 guestfs_ntfsclone_out_va
12052 int
12053 guestfs_ntfsclone_out_va (guestfs_h *g,
12054 const char *device,
12055 const char *backupfile,
12056 va_list args);
12057 This is the "va_list variant" of "guestfs_ntfsclone_out".
12059 See "CALLS WITH OPTIONAL ARGUMENTS".
12061 guestfs_ntfsclone_out_argv
12063 int
12064 guestfs_ntfsclone_out_argv (guestfs_h *g,
12065 const char *device,
12066 const char *backupfile,
12067 const struct guestfs_ntfsclone_out_argv *optargs);
12068 This is the "argv variant" of "guestfs_ntfsclone_out".
12070 See "CALLS WITH OPTIONAL ARGUMENTS".
12072 guestfs_ntfsfix
12074 int
12075 guestfs_ntfsfix (guestfs_h *g,
12076 const char *device,
12077 ...);
12078 You may supply a list of optional arguments to this call. Use zero or
12080 more of the following pairs of parameters, and terminate the list with
12081 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12082 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
12084 This command repairs some fundamental NTFS inconsistencies, resets the
12086 NTFS journal file, and schedules an NTFS consistency check for the
12087 first boot into Windows.
12088 This is not an equivalent of Windows "chkdsk". It does not scan the
12090 filesystem for inconsistencies.
12091 The optional "clearbadsectors" flag clears the list of bad sectors.
12093 This is useful after cloning a disk with bad sectors to a new disk.
12094 This function returns 0 on success or -1 on error.
12096 This function depends on the feature "ntfs3g". See also
12098 "guestfs_feature_available".
12099 (Added in 1.17.9)
12101 guestfs_ntfsfix_va
12103 int
12104 guestfs_ntfsfix_va (guestfs_h *g,
12105 const char *device,
12106 va_list args);
12107 This is the "va_list variant" of "guestfs_ntfsfix".
12109 See "CALLS WITH OPTIONAL ARGUMENTS".
12111 guestfs_ntfsfix_argv
12113 int
12114 guestfs_ntfsfix_argv (guestfs_h *g,
12115 const char *device,
12116 const struct guestfs_ntfsfix_argv *optargs);
12117 This is the "argv variant" of "guestfs_ntfsfix".
12119 See "CALLS WITH OPTIONAL ARGUMENTS".
12121 guestfs_ntfsresize
12123 int
12124 guestfs_ntfsresize (guestfs_h *g,
12125 const char *device);
12126 This function is provided for backwards compatibility with earlier
12128 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
12129 no optional arguments.
12130 (Added in 1.3.2)
12132 guestfs_ntfsresize_opts
12134 int
12135 guestfs_ntfsresize_opts (guestfs_h *g,
12136 const char *device,
12137 ...);
12138 You may supply a list of optional arguments to this call. Use zero or
12140 more of the following pairs of parameters, and terminate the list with
12141 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12142 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12144 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12145 This command resizes an NTFS filesystem, expanding or shrinking it to
12147 the size of the underlying device.
12148 The optional parameters are:
12150 "size"
12152 The new size (in bytes) of the filesystem. If omitted, the
12153 filesystem is resized to fit the container (eg. partition).
12154 "force"
12156 If this option is true, then force the resize of the filesystem
12157 even if the filesystem is marked as requiring a consistency check.
12158 After the resize operation, the filesystem is always marked as
12160 requiring a consistency check (for safety). You have to boot into
12161 Windows to perform this check and clear this condition. If you
12162 don't set the "force" option then it is not possible to call
12163 "guestfs_ntfsresize" multiple times on a single filesystem without
12164 booting into Windows between each resize.
12165 See also ntfsresize(8).
12167 This function returns 0 on success or -1 on error.
12169 This function depends on the feature "ntfsprogs". See also
12171 "guestfs_feature_available".
12172 (Added in 1.3.2)
12174 guestfs_ntfsresize_opts_va
12176 int
12177 guestfs_ntfsresize_opts_va (guestfs_h *g,
12178 const char *device,
12179 va_list args);
12180 This is the "va_list variant" of "guestfs_ntfsresize_opts".
12182 See "CALLS WITH OPTIONAL ARGUMENTS".
12184 guestfs_ntfsresize_opts_argv
12186 int
12187 guestfs_ntfsresize_opts_argv (guestfs_h *g,
12188 const char *device,
12189 const struct guestfs_ntfsresize_opts_argv *optargs);
12190 This is the "argv variant" of "guestfs_ntfsresize_opts".
12192 See "CALLS WITH OPTIONAL ARGUMENTS".
12194 guestfs_ntfsresize_size
12196 int
12197 guestfs_ntfsresize_size (guestfs_h *g,
12198 const char *device,
12199 int64_t size);
12200 This function is deprecated. In new code, use the "guestfs_ntfsresize"
12202 call instead.
12203 Deprecated functions will not be removed from the API, but the fact
12205 that they are deprecated indicates that there are problems with correct
12206 use of these functions.
12207 This command is the same as "guestfs_ntfsresize" except that it allows
12209 you to specify the new size (in bytes) explicitly.
12210 This function returns 0 on success or -1 on error.
12212 This function depends on the feature "ntfsprogs". See also
12214 "guestfs_feature_available".
12215 (Added in 1.3.14)
12217 guestfs_parse_environment
12219 int
12220 guestfs_parse_environment (guestfs_h *g);
12221 Parse the program’s environment and set flags in the handle
12223 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12224 flag is set in the handle.
12225 Most programs do not need to call this. It is done implicitly when you
12227 call "guestfs_create".
12228 See "ENVIRONMENT VARIABLES" for a list of environment variables that
12230 can affect libguestfs handles. See also "guestfs_create_flags", and
12231 "guestfs_parse_environment_list".
12232 This function returns 0 on success or -1 on error.
12234 (Added in 1.19.53)
12236 guestfs_parse_environment_list
12238 int
12239 guestfs_parse_environment_list (guestfs_h *g,
12240 char *const *environment);
12241 Parse the list of strings in the argument "environment" and set flags
12243 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
12244 string in the list, then the ‘verbose’ flag is set in the handle.
12245 This is the same as "guestfs_parse_environment" except that it parses
12247 an explicit list of strings instead of the program's environment.
12248 This function returns 0 on success or -1 on error.
12250 (Added in 1.19.53)
12252 guestfs_part_add
12254 int
12255 guestfs_part_add (guestfs_h *g,
12256 const char *device,
12257 const char *prlogex,
12258 int64_t startsect,
12259 int64_t endsect);
12260 This command adds a partition to "device". If there is no partition
12262 table on the device, call "guestfs_part_init" first.
12263 The "prlogex" parameter is the type of partition. Normally you should
12265 pass "p" or "primary" here, but MBR partition tables also support "l"
12266 (or "logical") and "e" (or "extended") partition types.
12267 "startsect" and "endsect" are the start and end of the partition in
12269 sectors. "endsect" may be negative, which means it counts backwards
12270 from the end of the disk (-1 is the last sector).
12271 Creating a partition which covers the whole disk is not so easy. Use
12273 "guestfs_part_disk" to do that.
12274 This function returns 0 on success or -1 on error.
12276 (Added in 1.0.78)
12278 guestfs_part_del
12280 int
12281 guestfs_part_del (guestfs_h *g,
12282 const char *device,
12283 int partnum);
12284 This command deletes the partition numbered "partnum" on "device".
12286 Note that in the case of MBR partitioning, deleting an extended
12288 partition also deletes any logical partitions it contains.
12289 This function returns 0 on success or -1 on error.
12291 (Added in 1.3.2)
12293 guestfs_part_disk
12295 int
12296 guestfs_part_disk (guestfs_h *g,
12297 const char *device,
12298 const char *parttype);
12299 This command is simply a combination of "guestfs_part_init" followed by
12301 "guestfs_part_add" to create a single primary partition covering the
12302 whole disk.
12303 "parttype" is the partition table type, usually "mbr" or "gpt", but
12305 other possible values are described in "guestfs_part_init".
12306 This function returns 0 on success or -1 on error.
12308 (Added in 1.0.78)
12310 guestfs_part_expand_gpt
12312 int
12313 guestfs_part_expand_gpt (guestfs_h *g,
12314 const char *device);
12315 Move backup GPT data structures to the end of the disk. This is useful
12317 in case of in-place image expand since disk space after backup GPT
12318 header is not usable. This is equivalent to "sgdisk -e".
12319 See also sgdisk(8).
12321 This function returns 0 on success or -1 on error.
12323 This function depends on the feature "gdisk". See also
12325 "guestfs_feature_available".
12326 (Added in 1.33.2)
12328 guestfs_part_get_bootable
12330 int
12331 guestfs_part_get_bootable (guestfs_h *g,
12332 const char *device,
12333 int partnum);
12334 This command returns true if the partition "partnum" on "device" has
12336 the bootable flag set.
12337 See also "guestfs_part_set_bootable".
12339 This function returns a C truth value on success or -1 on error.
12341 (Added in 1.3.2)
12343 guestfs_part_get_disk_guid
12345 char *
12346 guestfs_part_get_disk_guid (guestfs_h *g,
12347 const char *device);
12348 Return the disk identifier (GUID) of a GPT-partitioned "device".
12350 Behaviour is undefined for other partition types.
12351 This function returns a string, or NULL on error. The caller must free
12353 the returned string after use.
12354 This function depends on the feature "gdisk". See also
12356 "guestfs_feature_available".
12357 (Added in 1.33.2)
12359 guestfs_part_get_gpt_attributes
12361 int64_t
12362 guestfs_part_get_gpt_attributes (guestfs_h *g,
12363 const char *device,
12364 int partnum);
12365 Return the attribute flags of numbered GPT partition "partnum". An
12367 error is returned for MBR partitions.
12368 On error this function returns -1.
12370 This function depends on the feature "gdisk". See also
12372 "guestfs_feature_available".
12373 (Added in 1.21.1)
12375 guestfs_part_get_gpt_guid
12377 char *
12378 guestfs_part_get_gpt_guid (guestfs_h *g,
12379 const char *device,
12380 int partnum);
12381 Return the GUID of numbered GPT partition "partnum".
12383 This function returns a string, or NULL on error. The caller must free
12385 the returned string after use.
12386 This function depends on the feature "gdisk". See also
12388 "guestfs_feature_available".
12389 (Added in 1.29.25)
12391 guestfs_part_get_gpt_type
12393 char *
12394 guestfs_part_get_gpt_type (guestfs_h *g,
12395 const char *device,
12396 int partnum);
12397 Return the type GUID of numbered GPT partition "partnum". For MBR
12399 partitions, return an appropriate GUID corresponding to the MBR type.
12400 Behaviour is undefined for other partition types.
12401 This function returns a string, or NULL on error. The caller must free
12403 the returned string after use.
12404 This function depends on the feature "gdisk". See also
12406 "guestfs_feature_available".
12407 (Added in 1.21.1)
12409 guestfs_part_get_mbr_id
12411 int
12412 guestfs_part_get_mbr_id (guestfs_h *g,
12413 const char *device,
12414 int partnum);
12415 Returns the MBR type byte (also known as the ID byte) from the numbered
12417 partition "partnum".
12418 Note that only MBR (old DOS-style) partitions have type bytes. You
12420 will get undefined results for other partition table types (see
12421 "guestfs_part_get_parttype").
12422 On error this function returns -1.
12424 (Added in 1.3.2)
12426 guestfs_part_get_mbr_part_type
12428 char *
12429 guestfs_part_get_mbr_part_type (guestfs_h *g,
12430 const char *device,
12431 int partnum);
12432 This returns the partition type of an MBR partition numbered "partnum"
12434 on device "device".
12435 It returns "primary", "logical", or "extended".
12437 This function returns a string, or NULL on error. The caller must free
12439 the returned string after use.
12440 (Added in 1.29.32)
12442 guestfs_part_get_name
12444 char *
12445 guestfs_part_get_name (guestfs_h *g,
12446 const char *device,
12447 int partnum);
12448 This gets the partition name on partition numbered "partnum" on device
12450 "device". Note that partitions are numbered from 1.
12451 The partition name can only be read on certain types of partition
12453 table. This works on "gpt" but not on "mbr" partitions.
12454 This function returns a string, or NULL on error. The caller must free
12456 the returned string after use.
12457 (Added in 1.25.33)
12459 guestfs_part_get_parttype
12461 char *
12462 guestfs_part_get_parttype (guestfs_h *g,
12463 const char *device);
12464 This command examines the partition table on "device" and returns the
12466 partition table type (format) being used.
12467 Common return values include: "msdos" (a DOS/Windows style MBR
12469 partition table), "gpt" (a GPT/EFI-style partition table). Other
12470 values are possible, although unusual. See "guestfs_part_init" for a
12471 full list.
12472 This function returns a string, or NULL on error. The caller must free
12474 the returned string after use.
12475 (Added in 1.0.78)
12477 guestfs_part_init
12479 int
12480 guestfs_part_init (guestfs_h *g,
12481 const char *device,
12482 const char *parttype);
12483 This creates an empty partition table on "device" of one of the
12485 partition types listed below. Usually "parttype" should be either
12486 "msdos" or "gpt" (for large disks).
12487 Initially there are no partitions. Following this, you should call
12489 "guestfs_part_add" for each partition required.
12490 Possible values for "parttype" are:
12492 "efi"
12494 "gpt"
12495 Intel EFI / GPT partition table.
12496 This is recommended for >= 2 TB partitions that will be accessed
12498 from Linux and Intel-based Mac OS X. It also has limited backwards
12499 compatibility with the "mbr" format.
12500 "mbr"
12502 "msdos"
12503 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12504 and Windows. This partition type will only work for device sizes
12505 up to 2 TB. For large disks we recommend using "gpt".
12506 Other partition table types that may work but are not supported
12508 include:
12509 "aix"
12511 AIX disk labels.
12512 "amiga"
12514 "rdb"
12515 Amiga "Rigid Disk Block" format.
12516 "bsd"
12518 BSD disk labels.
12519 "dasd"
12521 DASD, used on IBM mainframes.
12522 "dvh"
12524 MIPS/SGI volumes.
12525 "mac"
12527 Old Mac partition format. Modern Macs use "gpt".
12528 "pc98"
12530 NEC PC-98 format, common in Japan apparently.
12531 "sun"
12533 Sun disk labels.
12534 This function returns 0 on success or -1 on error.
12536 (Added in 1.0.78)
12538 guestfs_part_list
12540 struct guestfs_partition_list *
12541 guestfs_part_list (guestfs_h *g,
12542 const char *device);
12543 This command parses the partition table on "device" and returns the
12545 list of partitions found.
12546 The fields in the returned structure are:
12548 "part_num"
12550 Partition number, counting from 1.
12551 "part_start"
12553 Start of the partition in bytes. To get sectors you have to divide
12554 by the device’s sector size, see "guestfs_blockdev_getss".
12555 "part_end"
12557 End of the partition in bytes.
12558 "part_size"
12560 Size of the partition in bytes.
12561 This function returns a "struct guestfs_partition_list *", or NULL if
12563 there was an error. The caller must call "guestfs_free_partition_list"
12564 after use.
12565 (Added in 1.0.78)
12567 guestfs_part_resize
12569 int
12570 guestfs_part_resize (guestfs_h *g,
12571 const char *device,
12572 int partnum,
12573 int64_t endsect);
12574 This command resizes the partition numbered "partnum" on "device" by
12576 moving the end position.
12577 Note that this does not modify any filesystem present in the partition.
12579 If you wish to do this, you will need to use filesystem resizing
12580 commands like "guestfs_resize2fs".
12581 When growing a partition you will want to grow the filesystem
12583 afterwards, but when shrinking, you need to shrink the filesystem
12584 before the partition.
12585 This function returns 0 on success or -1 on error.
12587 (Added in 1.37.20)
12589 guestfs_part_set_bootable
12591 int
12592 guestfs_part_set_bootable (guestfs_h *g,
12593 const char *device,
12594 int partnum,
12595 int bootable);
12596 This sets the bootable flag on partition numbered "partnum" on device
12598 "device". Note that partitions are numbered from 1.
12599 The bootable flag is used by some operating systems (notably Windows)
12601 to determine which partition to boot from. It is by no means
12602 universally recognized.
12603 This function returns 0 on success or -1 on error.
12605 (Added in 1.0.78)
12607 guestfs_part_set_disk_guid
12609 int
12610 guestfs_part_set_disk_guid (guestfs_h *g,
12611 const char *device,
12612 const char *guid);
12613 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12615 Return an error if the partition table of "device" isn't GPT, or if
12616 "guid" is not a valid GUID.
12617 This function returns 0 on success or -1 on error.
12619 This function depends on the feature "gdisk". See also
12621 "guestfs_feature_available".
12622 (Added in 1.33.2)
12624 guestfs_part_set_disk_guid_random
12626 int
12627 guestfs_part_set_disk_guid_random (guestfs_h *g,
12628 const char *device);
12629 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12631 randomly generated value. Return an error if the partition table of
12632 "device" isn't GPT.
12633 This function returns 0 on success or -1 on error.
12635 This function depends on the feature "gdisk". See also
12637 "guestfs_feature_available".
12638 (Added in 1.33.2)
12640 guestfs_part_set_gpt_attributes
12642 int
12643 guestfs_part_set_gpt_attributes (guestfs_h *g,
12644 const char *device,
12645 int partnum,
12646 int64_t attributes);
12647 Set the attribute flags of numbered GPT partition "partnum" to
12649 "attributes". Return an error if the partition table of "device" isn't
12650 GPT.
12651 See
12653 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12654 for a useful list of partition attributes.
12655 This function returns 0 on success or -1 on error.
12657 This function depends on the feature "gdisk". See also
12659 "guestfs_feature_available".
12660 (Added in 1.21.1)
12662 guestfs_part_set_gpt_guid
12664 int
12665 guestfs_part_set_gpt_guid (guestfs_h *g,
12666 const char *device,
12667 int partnum,
12668 const char *guid);
12669 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12671 error if the partition table of "device" isn't GPT, or if "guid" is not
12672 a valid GUID.
12673 This function returns 0 on success or -1 on error.
12675 This function depends on the feature "gdisk". See also
12677 "guestfs_feature_available".
12678 (Added in 1.29.25)
12680 guestfs_part_set_gpt_type
12682 int
12683 guestfs_part_set_gpt_type (guestfs_h *g,
12684 const char *device,
12685 int partnum,
12686 const char *guid);
12687 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12689 an error if the partition table of "device" isn't GPT, or if "guid" is
12690 not a valid GUID.
12691 See
12693 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12694 for a useful list of type GUIDs.
12695 This function returns 0 on success or -1 on error.
12697 This function depends on the feature "gdisk". See also
12699 "guestfs_feature_available".
12700 (Added in 1.21.1)
12702 guestfs_part_set_mbr_id
12704 int
12705 guestfs_part_set_mbr_id (guestfs_h *g,
12706 const char *device,
12707 int partnum,
12708 int idbyte);
12709 Sets the MBR type byte (also known as the ID byte) of the numbered
12711 partition "partnum" to "idbyte". Note that the type bytes quoted in
12712 most documentation are in fact hexadecimal numbers, but usually
12713 documented without any leading "0x" which might be confusing.
12714 Note that only MBR (old DOS-style) partitions have type bytes. You
12716 will get undefined results for other partition table types (see
12717 "guestfs_part_get_parttype").
12718 This function returns 0 on success or -1 on error.
12720 (Added in 1.3.2)
12722 guestfs_part_set_name
12724 int
12725 guestfs_part_set_name (guestfs_h *g,
12726 const char *device,
12727 int partnum,
12728 const char *name);
12729 This sets the partition name on partition numbered "partnum" on device
12731 "device". Note that partitions are numbered from 1.
12732 The partition name can only be set on certain types of partition table.
12734 This works on "gpt" but not on "mbr" partitions.
12735 This function returns 0 on success or -1 on error.
12737 (Added in 1.0.78)
12739 guestfs_part_to_dev
12741 char *
12742 guestfs_part_to_dev (guestfs_h *g,
12743 const char *partition);
12744 This function takes a partition name (eg. "/dev/sdb1") and removes the
12746 partition number, returning the device name (eg. "/dev/sdb").
12747 The named partition must exist, for example as a string returned from
12749 "guestfs_list_partitions".
12750 See also "guestfs_part_to_partnum", "guestfs_device_index".
12752 This function returns a string, or NULL on error. The caller must free
12754 the returned string after use.
12755 (Added in 1.5.15)
12757 guestfs_part_to_partnum
12759 int
12760 guestfs_part_to_partnum (guestfs_h *g,
12761 const char *partition);
12762 This function takes a partition name (eg. "/dev/sdb1") and returns the
12764 partition number (eg. 1).
12765 The named partition must exist, for example as a string returned from
12767 "guestfs_list_partitions".
12768 See also "guestfs_part_to_dev".
12770 On error this function returns -1.
12772 (Added in 1.13.25)
12774 guestfs_ping_daemon
12776 int
12777 guestfs_ping_daemon (guestfs_h *g);
12778 This is a test probe into the guestfs daemon running inside the
12780 libguestfs appliance. Calling this function checks that the daemon
12781 responds to the ping message, without affecting the daemon or attached
12782 block device(s) in any other way.
12783 This function returns 0 on success or -1 on error.
12785 (Added in 1.0.18)
12787 guestfs_pread
12789 char *
12790 guestfs_pread (guestfs_h *g,
12791 const char *path,
12792 int count,
12793 int64_t offset,
12794 size_t *size_r);
12795 This command lets you read part of a file. It reads "count" bytes of
12797 the file, starting at "offset", from file "path".
12798 This may read fewer bytes than requested. For further details see the
12800 pread(2) system call.
12801 See also "guestfs_pwrite", "guestfs_pread_device".
12803 This function returns a buffer, or NULL on error. The size of the
12805 returned buffer is written to *size_r. The caller must free the
12806 returned buffer after use.
12807 Because of the message protocol, there is a transfer limit of somewhere
12809 between 2MB and 4MB. See "PROTOCOL LIMITS".
12810 (Added in 1.0.77)
12812 guestfs_pread_device
12814 char *
12815 guestfs_pread_device (guestfs_h *g,
12816 const char *device,
12817 int count,
12818 int64_t offset,
12819 size_t *size_r);
12820 This command lets you read part of a block device. It reads "count"
12822 bytes of "device", starting at "offset".
12823 This may read fewer bytes than requested. For further details see the
12825 pread(2) system call.
12826 See also "guestfs_pread".
12828 This function returns a buffer, or NULL on error. The size of the
12830 returned buffer is written to *size_r. The caller must free the
12831 returned buffer after use.
12832 Because of the message protocol, there is a transfer limit of somewhere
12834 between 2MB and 4MB. See "PROTOCOL LIMITS".
12835 (Added in 1.5.21)
12837 guestfs_pvchange_uuid
12839 int
12840 guestfs_pvchange_uuid (guestfs_h *g,
12841 const char *device);
12842 Generate a new random UUID for the physical volume "device".
12844 This function returns 0 on success or -1 on error.
12846 This function depends on the feature "lvm2". See also
12848 "guestfs_feature_available".
12849 (Added in 1.19.26)
12851 guestfs_pvchange_uuid_all
12853 int
12854 guestfs_pvchange_uuid_all (guestfs_h *g);
12855 Generate new random UUIDs for all physical volumes.
12857 This function returns 0 on success or -1 on error.
12859 This function depends on the feature "lvm2". See also
12861 "guestfs_feature_available".
12862 (Added in 1.19.26)
12864 guestfs_pvcreate
12866 int
12867 guestfs_pvcreate (guestfs_h *g,
12868 const char *device);
12869 This creates an LVM physical volume on the named "device", where
12871 "device" should usually be a partition name such as /dev/sda1.
12872 This function returns 0 on success or -1 on error.
12874 This function depends on the feature "lvm2". See also
12876 "guestfs_feature_available".
12877 (Added in 0.8)
12879 guestfs_pvremove
12881 int
12882 guestfs_pvremove (guestfs_h *g,
12883 const char *device);
12884 This wipes a physical volume "device" so that LVM will no longer
12886 recognise it.
12887 The implementation uses the pvremove(8) command which refuses to wipe
12889 physical volumes that contain any volume groups, so you have to remove
12890 those first.
12891 This function returns 0 on success or -1 on error.
12893 This function depends on the feature "lvm2". See also
12895 "guestfs_feature_available".
12896 (Added in 1.0.13)
12898 guestfs_pvresize
12900 int
12901 guestfs_pvresize (guestfs_h *g,
12902 const char *device);
12903 This resizes (expands or shrinks) an existing LVM physical volume to
12905 match the new size of the underlying device.
12906 This function returns 0 on success or -1 on error.
12908 This function depends on the feature "lvm2". See also
12910 "guestfs_feature_available".
12911 (Added in 1.0.26)
12913 guestfs_pvresize_size
12915 int
12916 guestfs_pvresize_size (guestfs_h *g,
12917 const char *device,
12918 int64_t size);
12919 This command is the same as "guestfs_pvresize" except that it allows
12921 you to specify the new size (in bytes) explicitly.
12922 This function returns 0 on success or -1 on error.
12924 This function depends on the feature "lvm2". See also
12926 "guestfs_feature_available".
12927 (Added in 1.3.14)
12929 guestfs_pvs
12931 char **
12932 guestfs_pvs (guestfs_h *g);
12933 List all the physical volumes detected. This is the equivalent of the
12935 pvs(8) command.
12936 This returns a list of just the device names that contain PVs (eg.
12938 /dev/sda2).
12939 See also "guestfs_pvs_full".
12941 This function returns a NULL-terminated array of strings (like
12943 environ(3)), or NULL if there was an error. The caller must free the
12944 strings and the array after use.
12945 This function depends on the feature "lvm2". See also
12947 "guestfs_feature_available".
12948 (Added in 0.4)
12950 guestfs_pvs_full
12952 struct guestfs_lvm_pv_list *
12953 guestfs_pvs_full (guestfs_h *g);
12954 List all the physical volumes detected. This is the equivalent of the
12956 pvs(8) command. The "full" version includes all fields.
12957 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
12959 there was an error. The caller must call "guestfs_free_lvm_pv_list"
12960 after use.
12961 This function depends on the feature "lvm2". See also
12963 "guestfs_feature_available".
12964 (Added in 0.4)
12966 guestfs_pvuuid
12968 char *
12969 guestfs_pvuuid (guestfs_h *g,
12970 const char *device);
12971 This command returns the UUID of the LVM PV "device".
12973 This function returns a string, or NULL on error. The caller must free
12975 the returned string after use.
12976 (Added in 1.0.87)
12978 guestfs_pwrite
12980 int
12981 guestfs_pwrite (guestfs_h *g,
12982 const char *path,
12983 const char *content,
12984 size_t content_size,
12985 int64_t offset);
12986 This command writes to part of a file. It writes the data buffer
12988 "content" to the file "path" starting at offset "offset".
12989 This command implements the pwrite(2) system call, and like that system
12991 call it may not write the full data requested. The return value is the
12992 number of bytes that were actually written to the file. This could
12993 even be 0, although short writes are unlikely for regular files in
12994 ordinary circumstances.
12995 See also "guestfs_pread", "guestfs_pwrite_device".
12997 On error this function returns -1.
12999 Because of the message protocol, there is a transfer limit of somewhere
13001 between 2MB and 4MB. See "PROTOCOL LIMITS".
13002 (Added in 1.3.14)
13004 guestfs_pwrite_device
13006 int
13007 guestfs_pwrite_device (guestfs_h *g,
13008 const char *device,
13009 const char *content,
13010 size_t content_size,
13011 int64_t offset);
13012 This command writes to part of a device. It writes the data buffer
13014 "content" to "device" starting at offset "offset".
13015 This command implements the pwrite(2) system call, and like that system
13017 call it may not write the full data requested (although short writes to
13018 disk devices and partitions are probably impossible with standard Linux
13019 kernels).
13020 See also "guestfs_pwrite".
13022 On error this function returns -1.
13024 Because of the message protocol, there is a transfer limit of somewhere
13026 between 2MB and 4MB. See "PROTOCOL LIMITS".
13027 (Added in 1.5.20)
13029 guestfs_read_file
13031 char *
13032 guestfs_read_file (guestfs_h *g,
13033 const char *path,
13034 size_t *size_r);
13035 This calls returns the contents of the file "path" as a buffer.
13037 Unlike "guestfs_cat", this function can correctly handle files that
13039 contain embedded ASCII NUL characters.
13040 This function returns a buffer, or NULL on error. The size of the
13042 returned buffer is written to *size_r. The caller must free the
13043 returned buffer after use.
13044 (Added in 1.0.63)
13046 guestfs_read_lines
13048 char **
13049 guestfs_read_lines (guestfs_h *g,
13050 const char *path);
13051 Return the contents of the file named "path".
13053 The file contents are returned as a list of lines. Trailing "LF" and
13055 "CRLF" character sequences are not returned.
13056 Note that this function cannot correctly handle binary files
13058 (specifically, files containing "\0" character which is treated as end
13059 of string). For those you need to use the "guestfs_read_file" function
13060 and split the buffer into lines yourself.
13061 This function returns a NULL-terminated array of strings (like
13063 environ(3)), or NULL if there was an error. The caller must free the
13064 strings and the array after use.
13065 (Added in 0.7)
13067 guestfs_readdir
13069 struct guestfs_dirent_list *
13070 guestfs_readdir (guestfs_h *g,
13071 const char *dir);
13072 This returns the list of directory entries in directory "dir".
13074 All entries in the directory are returned, including "." and "..". The
13076 entries are not sorted, but returned in the same order as the
13077 underlying filesystem.
13078 Also this call returns basic file type information about each file.
13080 The "ftyp" field will contain one of the following characters:
13081 'b' Block special
13083 'c' Char special
13085 'd' Directory
13087 'f' FIFO (named pipe)
13089 'l' Symbolic link
13091 'r' Regular file
13093 's' Socket
13095 'u' Unknown file type
13097 '?' The readdir(3) call returned a "d_type" field with an unexpected
13099 value
13100 This function is primarily intended for use by programs. To get a
13102 simple list of names, use "guestfs_ls". To get a printable directory
13103 for human consumption, use "guestfs_ll".
13104 This function returns a "struct guestfs_dirent_list *", or NULL if
13106 there was an error. The caller must call "guestfs_free_dirent_list"
13107 after use.
13108 This long-running command can generate progress notification messages
13110 so that the caller can display a progress bar or indicator. To receive
13111 these messages, the caller must register a progress event callback.
13112 See "GUESTFS_EVENT_PROGRESS".
13113 (Added in 1.0.55)
13115 guestfs_readlink
13117 char *
13118 guestfs_readlink (guestfs_h *g,
13119 const char *path);
13120 This command reads the target of a symbolic link.
13122 This function returns a string, or NULL on error. The caller must free
13124 the returned string after use.
13125 (Added in 1.0.66)
13127 guestfs_readlinklist
13129 char **
13130 guestfs_readlinklist (guestfs_h *g,
13131 const char *path,
13132 char *const *names);
13133 This call allows you to do a "readlink" operation on multiple files,
13135 where all files are in the directory "path". "names" is the list of
13136 files from this directory.
13137 On return you get a list of strings, with a one-to-one correspondence
13139 to the "names" list. Each string is the value of the symbolic link.
13140 If the readlink(2) operation fails on any name, then the corresponding
13142 result string is the empty string "". However the whole operation is
13143 completed even if there were readlink(2) errors, and so you can call
13144 this function with names where you don't know if they are symbolic
13145 links already (albeit slightly less efficient).
13146 This call is intended for programs that want to efficiently list a
13148 directory contents without making many round-trips.
13149 This function returns a NULL-terminated array of strings (like
13151 environ(3)), or NULL if there was an error. The caller must free the
13152 strings and the array after use.
13153 (Added in 1.0.77)
13155 guestfs_realpath
13157 char *
13158 guestfs_realpath (guestfs_h *g,
13159 const char *path);
13160 Return the canonicalized absolute pathname of "path". The returned
13162 path has no ".", ".." or symbolic link path elements.
13163 This function returns a string, or NULL on error. The caller must free
13165 the returned string after use.
13166 (Added in 1.0.66)
13168 guestfs_remount
13170 int
13171 guestfs_remount (guestfs_h *g,
13172 const char *mountpoint,
13173 ...);
13174 You may supply a list of optional arguments to this call. Use zero or
13176 more of the following pairs of parameters, and terminate the list with
13177 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13178 GUESTFS_REMOUNT_RW, int rw,
13180 This call allows you to change the "rw" (readonly/read-write) flag on
13182 an already mounted filesystem at "mountpoint", converting a readonly
13183 filesystem to be read-write, or vice-versa.
13184 Note that at the moment you must supply the "optional" "rw" parameter.
13186 In future we may allow other flags to be adjusted.
13187 This function returns 0 on success or -1 on error.
13189 (Added in 1.23.2)
13191 guestfs_remount_va
13193 int
13194 guestfs_remount_va (guestfs_h *g,
13195 const char *mountpoint,
13196 va_list args);
13197 This is the "va_list variant" of "guestfs_remount".
13199 See "CALLS WITH OPTIONAL ARGUMENTS".
13201 guestfs_remount_argv
13203 int
13204 guestfs_remount_argv (guestfs_h *g,
13205 const char *mountpoint,
13206 const struct guestfs_remount_argv *optargs);
13207 This is the "argv variant" of "guestfs_remount".
13209 See "CALLS WITH OPTIONAL ARGUMENTS".
13211 guestfs_remove_drive
13213 int
13214 guestfs_remove_drive (guestfs_h *g,
13215 const char *label);
13216 This function is deprecated. There is no replacement. Consult the API
13218 documentation in guestfs(3) for further information.
13219 Deprecated functions will not be removed from the API, but the fact
13221 that they are deprecated indicates that there are problems with correct
13222 use of these functions.
13223 This call does nothing and returns an error.
13225 This function returns 0 on success or -1 on error.
13227 (Added in 1.19.49)
13229 guestfs_removexattr
13231 int
13232 guestfs_removexattr (guestfs_h *g,
13233 const char *xattr,
13234 const char *path);
13235 This call removes the extended attribute named "xattr" of the file
13237 "path".
13238 See also: "guestfs_lremovexattr", attr(5).
13240 This function returns 0 on success or -1 on error.
13242 This function depends on the feature "linuxxattrs". See also
13244 "guestfs_feature_available".
13245 (Added in 1.0.59)
13247 guestfs_rename
13249 int
13250 guestfs_rename (guestfs_h *g,
13251 const char *oldpath,
13252 const char *newpath);
13253 Rename a file to a new place on the same filesystem. This is the same
13255 as the Linux rename(2) system call. In most cases you are better to
13256 use "guestfs_mv" instead.
13257 This function returns 0 on success or -1 on error.
13259 (Added in 1.21.5)
13261 guestfs_resize2fs
13263 int
13264 guestfs_resize2fs (guestfs_h *g,
13265 const char *device);
13266 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13268 underlying device.
13269 See also "RESIZE2FS ERRORS".
13271 This function returns 0 on success or -1 on error.
13273 (Added in 1.0.27)
13275 guestfs_resize2fs_M
13277 int
13278 guestfs_resize2fs_M (guestfs_h *g,
13279 const char *device);
13280 This command is the same as "guestfs_resize2fs", but the filesystem is
13282 resized to its minimum size. This works like the -M option to the
13283 resize2fs(8) command.
13284 To get the resulting size of the filesystem you should call
13286 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13287 These two numbers, multiplied together, give the resulting size of the
13288 minimal filesystem in bytes.
13289 See also "RESIZE2FS ERRORS".
13291 This function returns 0 on success or -1 on error.
13293 (Added in 1.9.4)
13295 guestfs_resize2fs_size
13297 int
13298 guestfs_resize2fs_size (guestfs_h *g,
13299 const char *device,
13300 int64_t size);
13301 This command is the same as "guestfs_resize2fs" except that it allows
13303 you to specify the new size (in bytes) explicitly.
13304 See also "RESIZE2FS ERRORS".
13306 This function returns 0 on success or -1 on error.
13308 (Added in 1.3.14)
13310 guestfs_rm
13312 int
13313 guestfs_rm (guestfs_h *g,
13314 const char *path);
13315 Remove the single file "path".
13317 This function returns 0 on success or -1 on error.
13319 (Added in 0.8)
13321 guestfs_rm_f
13323 int
13324 guestfs_rm_f (guestfs_h *g,
13325 const char *path);
13326 Remove the file "path".
13328 If the file doesn't exist, that error is ignored. (Other errors, eg.
13330 I/O errors or bad paths, are not ignored)
13331 This call cannot remove directories. Use "guestfs_rmdir" to remove an
13333 empty directory, or "guestfs_rm_rf" to remove directories recursively.
13334 This function returns 0 on success or -1 on error.
13336 (Added in 1.19.42)
13338 guestfs_rm_rf
13340 int
13341 guestfs_rm_rf (guestfs_h *g,
13342 const char *path);
13343 Remove the file or directory "path", recursively removing the contents
13345 if its a directory. This is like the "rm -rf" shell command.
13346 This function returns 0 on success or -1 on error.
13348 (Added in 0.8)
13350 guestfs_rmdir
13352 int
13353 guestfs_rmdir (guestfs_h *g,
13354 const char *path);
13355 Remove the single directory "path".
13357 This function returns 0 on success or -1 on error.
13359 (Added in 0.8)
13361 guestfs_rmmountpoint
13363 int
13364 guestfs_rmmountpoint (guestfs_h *g,
13365 const char *exemptpath);
13366 This call removes a mountpoint that was previously created with
13368 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13369 This function returns 0 on success or -1 on error.
13371 (Added in 1.0.62)
13373 guestfs_rsync
13375 int
13376 guestfs_rsync (guestfs_h *g,
13377 const char *src,
13378 const char *dest,
13379 ...);
13380 You may supply a list of optional arguments to this call. Use zero or
13382 more of the following pairs of parameters, and terminate the list with
13383 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13384 GUESTFS_RSYNC_ARCHIVE, int archive,
13386 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13387 This call may be used to copy or synchronize two directories under the
13389 same libguestfs handle. This uses the rsync(1) program which uses a
13390 fast algorithm that avoids copying files unnecessarily.
13391 "src" and "dest" are the source and destination directories. Files are
13393 copied from "src" to "dest".
13394 The optional arguments are:
13396 "archive"
13398 Turns on archive mode. This is the same as passing the --archive
13399 flag to "rsync".
13400 "deletedest"
13402 Delete files at the destination that do not exist at the source.
13403 This function returns 0 on success or -1 on error.
13405 This function depends on the feature "rsync". See also
13407 "guestfs_feature_available".
13408 (Added in 1.19.29)
13410 guestfs_rsync_va
13412 int
13413 guestfs_rsync_va (guestfs_h *g,
13414 const char *src,
13415 const char *dest,
13416 va_list args);
13417 This is the "va_list variant" of "guestfs_rsync".
13419 See "CALLS WITH OPTIONAL ARGUMENTS".
13421 guestfs_rsync_argv
13423 int
13424 guestfs_rsync_argv (guestfs_h *g,
13425 const char *src,
13426 const char *dest,
13427 const struct guestfs_rsync_argv *optargs);
13428 This is the "argv variant" of "guestfs_rsync".
13430 See "CALLS WITH OPTIONAL ARGUMENTS".
13432 guestfs_rsync_in
13434 int
13435 guestfs_rsync_in (guestfs_h *g,
13436 const char *remote,
13437 const char *dest,
13438 ...);
13439 You may supply a list of optional arguments to this call. Use zero or
13441 more of the following pairs of parameters, and terminate the list with
13442 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13443 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13445 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13446 This call may be used to copy or synchronize the filesystem on the host
13448 or on a remote computer with the filesystem within libguestfs. This
13449 uses the rsync(1) program which uses a fast algorithm that avoids
13450 copying files unnecessarily.
13451 This call only works if the network is enabled. See
13453 "guestfs_set_network" or the --network option to various tools like
13454 guestfish(1).
13455 Files are copied from the remote server and directory specified by
13457 "remote" to the destination directory "dest".
13458 The format of the remote server string is defined by rsync(1). Note
13460 that there is no way to supply a password or passphrase so the target
13461 must be set up not to require one.
13462 The optional arguments are the same as those of "guestfs_rsync".
13464 This function returns 0 on success or -1 on error.
13466 This function depends on the feature "rsync". See also
13468 "guestfs_feature_available".
13469 (Added in 1.19.29)
13471 guestfs_rsync_in_va
13473 int
13474 guestfs_rsync_in_va (guestfs_h *g,
13475 const char *remote,
13476 const char *dest,
13477 va_list args);
13478 This is the "va_list variant" of "guestfs_rsync_in".
13480 See "CALLS WITH OPTIONAL ARGUMENTS".
13482 guestfs_rsync_in_argv
13484 int
13485 guestfs_rsync_in_argv (guestfs_h *g,
13486 const char *remote,
13487 const char *dest,
13488 const struct guestfs_rsync_in_argv *optargs);
13489 This is the "argv variant" of "guestfs_rsync_in".
13491 See "CALLS WITH OPTIONAL ARGUMENTS".
13493 guestfs_rsync_out
13495 int
13496 guestfs_rsync_out (guestfs_h *g,
13497 const char *src,
13498 const char *remote,
13499 ...);
13500 You may supply a list of optional arguments to this call. Use zero or
13502 more of the following pairs of parameters, and terminate the list with
13503 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13504 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13506 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13507 This call may be used to copy or synchronize the filesystem within
13509 libguestfs with a filesystem on the host or on a remote computer. This
13510 uses the rsync(1) program which uses a fast algorithm that avoids
13511 copying files unnecessarily.
13512 This call only works if the network is enabled. See
13514 "guestfs_set_network" or the --network option to various tools like
13515 guestfish(1).
13516 Files are copied from the source directory "src" to the remote server
13518 and directory specified by "remote".
13519 The format of the remote server string is defined by rsync(1). Note
13521 that there is no way to supply a password or passphrase so the target
13522 must be set up not to require one.
13523 The optional arguments are the same as those of "guestfs_rsync".
13525 Globbing does not happen on the "src" parameter. In programs which use
13527 the API directly you have to expand wildcards yourself (see
13528 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13529 (see "glob" in guestfish(1)), for example:
13530 ><fs> glob rsync-out /* rsync://remote/
13532 This function returns 0 on success or -1 on error.
13534 This function depends on the feature "rsync". See also
13536 "guestfs_feature_available".
13537 (Added in 1.19.29)
13539 guestfs_rsync_out_va
13541 int
13542 guestfs_rsync_out_va (guestfs_h *g,
13543 const char *src,
13544 const char *remote,
13545 va_list args);
13546 This is the "va_list variant" of "guestfs_rsync_out".
13548 See "CALLS WITH OPTIONAL ARGUMENTS".
13550 guestfs_rsync_out_argv
13552 int
13553 guestfs_rsync_out_argv (guestfs_h *g,
13554 const char *src,
13555 const char *remote,
13556 const struct guestfs_rsync_out_argv *optargs);
13557 This is the "argv variant" of "guestfs_rsync_out".
13559 See "CALLS WITH OPTIONAL ARGUMENTS".
13561 guestfs_scrub_device
13563 int
13564 guestfs_scrub_device (guestfs_h *g,
13565 const char *device);
13566 This command writes patterns over "device" to make data retrieval more
13568 difficult.
13569 It is an interface to the scrub(1) program. See that manual page for
13571 more details.
13572 This function returns 0 on success or -1 on error.
13574 This function depends on the feature "scrub". See also
13576 "guestfs_feature_available".
13577 (Added in 1.0.52)
13579 guestfs_scrub_file
13581 int
13582 guestfs_scrub_file (guestfs_h *g,
13583 const char *file);
13584 This command writes patterns over a file to make data retrieval more
13586 difficult.
13587 The file is removed after scrubbing.
13589 It is an interface to the scrub(1) program. See that manual page for
13591 more details.
13592 This function returns 0 on success or -1 on error.
13594 This function depends on the feature "scrub". See also
13596 "guestfs_feature_available".
13597 (Added in 1.0.52)
13599 guestfs_scrub_freespace
13601 int
13602 guestfs_scrub_freespace (guestfs_h *g,
13603 const char *dir);
13604 This command creates the directory "dir" and then fills it with files
13606 until the filesystem is full, and scrubs the files as for
13607 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13608 free space on the partition containing "dir".
13609 It is an interface to the scrub(1) program. See that manual page for
13611 more details.
13612 This function returns 0 on success or -1 on error.
13614 This function depends on the feature "scrub". See also
13616 "guestfs_feature_available".
13617 (Added in 1.0.52)
13619 guestfs_selinux_relabel
13621 int
13622 guestfs_selinux_relabel (guestfs_h *g,
13623 const char *specfile,
13624 const char *path,
13625 ...);
13626 You may supply a list of optional arguments to this call. Use zero or
13628 more of the following pairs of parameters, and terminate the list with
13629 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13630 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13632 SELinux relabel parts of the filesystem.
13634 The "specfile" parameter controls the policy spec file used. You have
13636 to parse "/etc/selinux/config" to find the correct SELinux policy and
13637 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13638 "/contexts/files/file_contexts".
13639 The required "path" parameter is the top level directory where
13641 relabelling starts. Normally you should pass "path" as "/" to relabel
13642 the whole guest filesystem.
13643 The optional "force" boolean controls whether the context is reset for
13645 customizable files, and also whether the user, role and range parts of
13646 the file context is changed.
13647 This function returns 0 on success or -1 on error.
13649 This function depends on the feature "selinuxrelabel". See also
13651 "guestfs_feature_available".
13652 (Added in 1.33.43)
13654 guestfs_selinux_relabel_va
13656 int
13657 guestfs_selinux_relabel_va (guestfs_h *g,
13658 const char *specfile,
13659 const char *path,
13660 va_list args);
13661 This is the "va_list variant" of "guestfs_selinux_relabel".
13663 See "CALLS WITH OPTIONAL ARGUMENTS".
13665 guestfs_selinux_relabel_argv
13667 int
13668 guestfs_selinux_relabel_argv (guestfs_h *g,
13669 const char *specfile,
13670 const char *path,
13671 const struct guestfs_selinux_relabel_argv *optargs);
13672 This is the "argv variant" of "guestfs_selinux_relabel".
13674 See "CALLS WITH OPTIONAL ARGUMENTS".
13676 guestfs_set_append
13678 int
13679 guestfs_set_append (guestfs_h *g,
13680 const char *append);
13681 This function is used to add additional options to the libguestfs
13683 appliance kernel command line.
13684 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13686 environment variable.
13687 Setting "append" to "NULL" means no additional options are passed
13689 (libguestfs always adds a few of its own).
13690 This function returns 0 on success or -1 on error.
13692 (Added in 1.0.26)
13694 guestfs_set_attach_method
13696 int
13697 guestfs_set_attach_method (guestfs_h *g,
13698 const char *backend);
13699 This function is deprecated. In new code, use the
13701 "guestfs_set_backend" call instead.
13702 Deprecated functions will not be removed from the API, but the fact
13704 that they are deprecated indicates that there are problems with correct
13705 use of these functions.
13706 Set the method that libguestfs uses to connect to the backend guestfsd
13708 daemon.
13709 See "BACKEND".
13711 This function returns 0 on success or -1 on error.
13713 (Added in 1.9.8)
13715 guestfs_set_autosync
13717 int
13718 guestfs_set_autosync (guestfs_h *g,
13719 int autosync);
13720 If "autosync" is true, this enables autosync. Libguestfs will make a
13722 best effort attempt to make filesystems consistent and synchronized
13723 when the handle is closed (also if the program exits without closing
13724 handles).
13725 This is enabled by default (since libguestfs 1.5.24, previously it was
13727 disabled by default).
13728 This function returns 0 on success or -1 on error.
13730 (Added in 0.3)
13732 guestfs_set_backend
13734 int
13735 guestfs_set_backend (guestfs_h *g,
13736 const char *backend);
13737 Set the method that libguestfs uses to connect to the backend guestfsd
13739 daemon.
13740 This handle property was previously called the "attach method".
13742 See "BACKEND".
13744 This function returns 0 on success or -1 on error.
13746 (Added in 1.21.26)
13748 guestfs_set_backend_setting
13750 int
13751 guestfs_set_backend_setting (guestfs_h *g,
13752 const char *name,
13753 const char *val);
13754 Append "name=value" to the backend settings string list. However if a
13756 string already exists matching "name" or beginning with "name=", then
13757 that setting is replaced.
13758 See "BACKEND", "BACKEND SETTINGS".
13760 This function returns 0 on success or -1 on error.
13762 (Added in 1.27.2)
13764 guestfs_set_backend_settings
13766 int
13767 guestfs_set_backend_settings (guestfs_h *g,
13768 char *const *settings);
13769 Set a list of zero or more settings which are passed through to the
13771 current backend. Each setting is a string which is interpreted in a
13772 backend-specific way, or ignored if not understood by the backend.
13773 The default value is an empty list, unless the environment variable
13775 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13776 This environment variable contains a colon-separated list of settings.
13777 This call replaces all backend settings. If you want to replace a
13779 single backend setting, see "guestfs_set_backend_setting". If you want
13780 to clear a single backend setting, see "guestfs_clear_backend_setting".
13781 See "BACKEND", "BACKEND SETTINGS".
13783 This function returns 0 on success or -1 on error.
13785 (Added in 1.25.24)
13787 guestfs_set_cachedir
13789 int
13790 guestfs_set_cachedir (guestfs_h *g,
13791 const char *cachedir);
13792 Set the directory used by the handle to store the appliance cache, when
13794 using a supermin appliance. The appliance is cached and shared between
13795 all handles which have the same effective user ID.
13796 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13798 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13799 default. Else if "TMPDIR" is set, then that is the default. Else
13800 /var/tmp is the default.
13801 This function returns 0 on success or -1 on error.
13803 (Added in 1.19.58)
13805 guestfs_set_direct
13807 int
13808 guestfs_set_direct (guestfs_h *g,
13809 int direct);
13810 This function is deprecated. In new code, use the
13812 "guestfs_internal_get_console_socket" call instead.
13813 Deprecated functions will not be removed from the API, but the fact
13815 that they are deprecated indicates that there are problems with correct
13816 use of these functions.
13817 If the direct appliance mode flag is enabled, then stdin and stdout are
13819 passed directly through to the appliance once it is launched.
13820 One consequence of this is that log messages aren't caught by the
13822 library and handled by "guestfs_set_log_message_callback", but go
13823 straight to stdout.
13824 You probably don't want to use this unless you know what you are doing.
13826 The default is disabled.
13828 This function returns 0 on success or -1 on error.
13830 (Added in 1.0.72)
13832 guestfs_set_e2attrs
13834 int
13835 guestfs_set_e2attrs (guestfs_h *g,
13836 const char *file,
13837 const char *attrs,
13838 ...);
13839 You may supply a list of optional arguments to this call. Use zero or
13841 more of the following pairs of parameters, and terminate the list with
13842 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13843 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13845 This sets or clears the file attributes "attrs" associated with the
13847 inode file.
13848 "attrs" is a string of characters representing file attributes. See
13850 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13851 attributes can be changed.
13852 If optional boolean "clear" is not present or false, then the "attrs"
13854 listed are set in the inode.
13855 If "clear" is true, then the "attrs" listed are cleared in the inode.
13857 In both cases, other attributes not present in the "attrs" string are
13859 left unchanged.
13860 These attributes are only present when the file is located on an
13862 ext2/3/4 filesystem. Using this call on other filesystem types will
13863 result in an error.
13864 This function returns 0 on success or -1 on error.
13866 (Added in 1.17.31)
13868 guestfs_set_e2attrs_va
13870 int
13871 guestfs_set_e2attrs_va (guestfs_h *g,
13872 const char *file,
13873 const char *attrs,
13874 va_list args);
13875 This is the "va_list variant" of "guestfs_set_e2attrs".
13877 See "CALLS WITH OPTIONAL ARGUMENTS".
13879 guestfs_set_e2attrs_argv
13881 int
13882 guestfs_set_e2attrs_argv (guestfs_h *g,
13883 const char *file,
13884 const char *attrs,
13885 const struct guestfs_set_e2attrs_argv *optargs);
13886 This is the "argv variant" of "guestfs_set_e2attrs".
13888 See "CALLS WITH OPTIONAL ARGUMENTS".
13890 guestfs_set_e2generation
13892 int
13893 guestfs_set_e2generation (guestfs_h *g,
13894 const char *file,
13895 int64_t generation);
13896 This sets the ext2 file generation of a file.
13898 See "guestfs_get_e2generation".
13900 This function returns 0 on success or -1 on error.
13902 (Added in 1.17.31)
13904 guestfs_set_e2label
13906 int
13907 guestfs_set_e2label (guestfs_h *g,
13908 const char *device,
13909 const char *label);
13910 This function is deprecated. In new code, use the "guestfs_set_label"
13912 call instead.
13913 Deprecated functions will not be removed from the API, but the fact
13915 that they are deprecated indicates that there are problems with correct
13916 use of these functions.
13917 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13919 to "label". Filesystem labels are limited to 16 characters.
13920 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13922 return the existing label on a filesystem.
13923 This function returns 0 on success or -1 on error.
13925 (Added in 1.0.15)
13927 guestfs_set_e2uuid
13929 int
13930 guestfs_set_e2uuid (guestfs_h *g,
13931 const char *device,
13932 const char *uuid);
13933 This function is deprecated. In new code, use the "guestfs_set_uuid"
13935 call instead.
13936 Deprecated functions will not be removed from the API, but the fact
13938 that they are deprecated indicates that there are problems with correct
13939 use of these functions.
13940 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
13942 "uuid". The format of the UUID and alternatives such as "clear",
13943 "random" and "time" are described in the tune2fs(8) manpage.
13944 You can use "guestfs_vfs_uuid" to return the existing UUID of a
13946 filesystem.
13947 This function returns 0 on success or -1 on error.
13949 (Added in 1.0.15)
13951 guestfs_set_hv
13953 int
13954 guestfs_set_hv (guestfs_h *g,
13955 const char *hv);
13956 Set the hypervisor binary that we will use. The hypervisor depends on
13958 the backend, but is usually the location of the qemu/KVM hypervisor.
13959 The default is chosen when the library was compiled by the configure
13961 script.
13962 You can also override this by setting the "LIBGUESTFS_HV" environment
13964 variable.
13965 Note that you should call this function as early as possible after
13967 creating the handle. This is because some pre-launch operations depend
13968 on testing qemu features (by running "qemu -help"). If the qemu binary
13969 changes, we don't retest features, and so you might see inconsistent
13970 results. Using the environment variable "LIBGUESTFS_HV" is safest of
13971 all since that picks the qemu binary at the same time as the handle is
13972 created.
13973 This function returns 0 on success or -1 on error.
13975 (Added in 1.23.17)
13977 guestfs_set_identifier
13979 int
13980 guestfs_set_identifier (guestfs_h *g,
13981 const char *identifier);
13982 This is an informative string which the caller may optionally set in
13984 the handle. It is printed in various places, allowing the current
13985 handle to be identified in debugging output.
13986 One important place is when tracing is enabled. If the identifier
13988 string is not an empty string, then trace messages change from this:
13989 libguestfs: trace: get_tmpdir
13991 libguestfs: trace: get_tmpdir = "/tmp"
13992 to this:
13994 libguestfs: trace: ID: get_tmpdir
13996 libguestfs: trace: ID: get_tmpdir = "/tmp"
13997 where "ID" is the identifier string set by this call.
13999 The identifier must only contain alphanumeric ASCII characters,
14001 underscore and minus sign. The default is the empty string.
14002 See also "guestfs_set_program", "guestfs_set_trace",
14004 "guestfs_get_identifier".
14005 This function returns 0 on success or -1 on error.
14007 (Added in 1.31.14)
14009 guestfs_set_label
14011 int
14012 guestfs_set_label (guestfs_h *g,
14013 const char *mountable,
14014 const char *label);
14015 Set the filesystem label on "mountable" to "label".
14017 Only some filesystem types support labels, and libguestfs supports
14019 setting labels on only a subset of these.
14020 ext2, ext3, ext4
14022 Labels are limited to 16 bytes.
14023 NTFS
14025 Labels are limited to 128 unicode characters.
14026 XFS The label is limited to 12 bytes. The filesystem must not be
14028 mounted when trying to set the label.
14029 btrfs
14031 The label is limited to 255 bytes and some characters are not
14032 allowed. Setting the label on a btrfs subvolume will set the label
14033 on its parent filesystem. The filesystem must not be mounted when
14034 trying to set the label.
14035 fat The label is limited to 11 bytes.
14037 swap
14039 The label is limited to 16 bytes.
14040 If there is no support for changing the label for the type of the
14042 specified filesystem, set_label will fail and set errno as ENOTSUP.
14043 To read the label on a filesystem, call "guestfs_vfs_label".
14045 This function returns 0 on success or -1 on error.
14047 (Added in 1.17.9)
14049 guestfs_set_libvirt_requested_credential
14051 int
14052 guestfs_set_libvirt_requested_credential (guestfs_h *g,
14053 int index,
14054 const char *cred,
14055 size_t cred_size);
14056 After requesting the "index"'th credential from the user, call this
14058 function to pass the answer back to libvirt.
14059 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14061 This function returns 0 on success or -1 on error.
14063 (Added in 1.19.52)
14065 guestfs_set_libvirt_supported_credentials
14067 int
14068 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
14069 char *const *creds);
14070 Call this function before setting an event handler for
14072 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
14073 that the program knows how to process.
14074 The "creds" list must be a non-empty list of strings. Possible strings
14076 are:
14077 "username"
14079 "authname"
14080 "language"
14081 "cnonce"
14082 "passphrase"
14083 "echoprompt"
14084 "noechoprompt"
14085 "realm"
14086 "external"
14087 See libvirt documentation for the meaning of these credential types.
14089 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14091 This function returns 0 on success or -1 on error.
14093 (Added in 1.19.52)
14095 guestfs_set_memsize
14097 int
14098 guestfs_set_memsize (guestfs_h *g,
14099 int memsize);
14100 This sets the memory size in megabytes allocated to the hypervisor.
14102 This only has any effect if called before "guestfs_launch".
14103 You can also change this by setting the environment variable
14105 "LIBGUESTFS_MEMSIZE" before the handle is created.
14106 For more information on the architecture of libguestfs, see guestfs(3).
14108 This function returns 0 on success or -1 on error.
14110 (Added in 1.0.55)
14112 guestfs_set_network
14114 int
14115 guestfs_set_network (guestfs_h *g,
14116 int network);
14117 If "network" is true, then the network is enabled in the libguestfs
14119 appliance. The default is false.
14120 This affects whether commands are able to access the network (see
14122 "RUNNING COMMANDS").
14123 You must call this before calling "guestfs_launch", otherwise it has no
14125 effect.
14126 This function returns 0 on success or -1 on error.
14128 (Added in 1.5.4)
14130 guestfs_set_path
14132 int
14133 guestfs_set_path (guestfs_h *g,
14134 const char *searchpath);
14135 Set the path that libguestfs searches for kernel and initrd.img.
14137 The default is "$libdir/guestfs" unless overridden by setting
14139 "LIBGUESTFS_PATH" environment variable.
14140 Setting "path" to "NULL" restores the default path.
14142 This function returns 0 on success or -1 on error.
14144 (Added in 0.3)
14146 guestfs_set_pgroup
14148 int
14149 guestfs_set_pgroup (guestfs_h *g,
14150 int pgroup);
14151 If "pgroup" is true, child processes are placed into their own process
14153 group.
14154 The practical upshot of this is that signals like "SIGINT" (from users
14156 pressing "^C") won't be received by the child process.
14157 The default for this flag is false, because usually you want "^C" to
14159 kill the subprocess. Guestfish sets this flag to true when used
14160 interactively, so that "^C" can cancel long-running commands gracefully
14161 (see "guestfs_user_cancel").
14162 This function returns 0 on success or -1 on error.
14164 (Added in 1.11.18)
14166 guestfs_set_program
14168 int
14169 guestfs_set_program (guestfs_h *g,
14170 const char *program);
14171 Set the program name. This is an informative string which the main
14173 program may optionally set in the handle.
14174 When the handle is created, the program name in the handle is set to
14176 the basename from "argv[0]". The program name can never be "NULL".
14177 This function returns 0 on success or -1 on error.
14179 (Added in 1.21.29)
14181 guestfs_set_qemu
14183 int
14184 guestfs_set_qemu (guestfs_h *g,
14185 const char *hv);
14186 This function is deprecated. In new code, use the "guestfs_set_hv"
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 Set the hypervisor binary (usually qemu) that we will use.
14195 The default is chosen when the library was compiled by the configure
14197 script.
14198 You can also override this by setting the "LIBGUESTFS_HV" environment
14200 variable.
14201 Setting "hv" to "NULL" restores the default qemu binary.
14203 Note that you should call this function as early as possible after
14205 creating the handle. This is because some pre-launch operations depend
14206 on testing qemu features (by running "qemu -help"). If the qemu binary
14207 changes, we don't retest features, and so you might see inconsistent
14208 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14209 all since that picks the qemu binary at the same time as the handle is
14210 created.
14211 This function returns 0 on success or -1 on error.
14213 (Added in 1.0.6)
14215 guestfs_set_recovery_proc
14217 int
14218 guestfs_set_recovery_proc (guestfs_h *g,
14219 int recoveryproc);
14220 If this is called with the parameter "false" then "guestfs_launch" does
14222 not create a recovery process. The purpose of the recovery process is
14223 to stop runaway hypervisor processes in the case where the main program
14224 aborts abruptly.
14225 This only has any effect if called before "guestfs_launch", and the
14227 default is true.
14228 About the only time when you would want to disable this is if the main
14230 process will fork itself into the background ("daemonize" itself). In
14231 this case the recovery process thinks that the main program has
14232 disappeared and so kills the hypervisor, which is not very helpful.
14233 This function returns 0 on success or -1 on error.
14235 (Added in 1.0.77)
14237 guestfs_set_selinux
14239 int
14240 guestfs_set_selinux (guestfs_h *g,
14241 int selinux);
14242 This function is deprecated. In new code, use the
14244 "guestfs_selinux_relabel" call instead.
14245 Deprecated functions will not be removed from the API, but the fact
14247 that they are deprecated indicates that there are problems with correct
14248 use of these functions.
14249 This sets the selinux flag that is passed to the appliance at boot
14251 time. The default is "selinux=0" (disabled).
14252 Note that if SELinux is enabled, it is always in Permissive mode
14254 ("enforcing=0").
14255 For more information on the architecture of libguestfs, see guestfs(3).
14257 This function returns 0 on success or -1 on error.
14259 (Added in 1.0.67)
14261 guestfs_set_smp
14263 int
14264 guestfs_set_smp (guestfs_h *g,
14265 int smp);
14266 Change the number of virtual CPUs assigned to the appliance. The
14268 default is 1. Increasing this may improve performance, though often it
14269 has no effect.
14270 This function must be called before "guestfs_launch".
14272 This function returns 0 on success or -1 on error.
14274 (Added in 1.13.15)
14276 guestfs_set_tmpdir
14278 int
14279 guestfs_set_tmpdir (guestfs_h *g,
14280 const char *tmpdir);
14281 Set the directory used by the handle to store temporary files.
14283 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14285 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14286 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
14287 default.
14288 This function returns 0 on success or -1 on error.
14290 (Added in 1.19.58)
14292 guestfs_set_trace
14294 int
14295 guestfs_set_trace (guestfs_h *g,
14296 int trace);
14297 If the command trace flag is set to 1, then libguestfs calls,
14299 parameters and return values are traced.
14300 If you want to trace C API calls into libguestfs (and other libraries)
14302 then possibly a better way is to use the external ltrace(1) command.
14303 Command traces are disabled unless the environment variable
14305 "LIBGUESTFS_TRACE" is defined and set to 1.
14306 Trace messages are normally sent to "stderr", unless you register a
14308 callback to send them somewhere else (see
14309 "guestfs_set_event_callback").
14310 This function returns 0 on success or -1 on error.
14312 (Added in 1.0.69)
14314 guestfs_set_uuid
14316 int
14317 guestfs_set_uuid (guestfs_h *g,
14318 const char *device,
14319 const char *uuid);
14320 Set the filesystem UUID on "device" to "uuid". If this fails and the
14322 errno is ENOTSUP, means that there is no support for changing the UUID
14323 for the type of the specified filesystem.
14324 Only some filesystem types support setting UUIDs.
14326 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14328 This function returns 0 on success or -1 on error.
14330 (Added in 1.23.10)
14332 guestfs_set_uuid_random
14334 int
14335 guestfs_set_uuid_random (guestfs_h *g,
14336 const char *device);
14337 Set the filesystem UUID on "device" to a random UUID. If this fails
14339 and the errno is ENOTSUP, means that there is no support for changing
14340 the UUID for the type of the specified filesystem.
14341 Only some filesystem types support setting UUIDs.
14343 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14345 This function returns 0 on success or -1 on error.
14347 (Added in 1.29.50)
14349 guestfs_set_verbose
14351 int
14352 guestfs_set_verbose (guestfs_h *g,
14353 int verbose);
14354 If "verbose" is true, this turns on verbose messages.
14356 Verbose messages are disabled unless the environment variable
14358 "LIBGUESTFS_DEBUG" is defined and set to 1.
14359 Verbose messages are normally sent to "stderr", unless you register a
14361 callback to send them somewhere else (see
14362 "guestfs_set_event_callback").
14363 This function returns 0 on success or -1 on error.
14365 (Added in 0.3)
14367 guestfs_setcon
14369 int
14370 guestfs_setcon (guestfs_h *g,
14371 const char *context);
14372 This function is deprecated. In new code, use the
14374 "guestfs_selinux_relabel" call instead.
14375 Deprecated functions will not be removed from the API, but the fact
14377 that they are deprecated indicates that there are problems with correct
14378 use of these functions.
14379 This sets the SELinux security context of the daemon to the string
14381 "context".
14382 See the documentation about SELINUX in guestfs(3).
14384 This function returns 0 on success or -1 on error.
14386 This function depends on the feature "selinux". See also
14388 "guestfs_feature_available".
14389 (Added in 1.0.67)
14391 guestfs_setxattr
14393 int
14394 guestfs_setxattr (guestfs_h *g,
14395 const char *xattr,
14396 const char *val,
14397 int vallen,
14398 const char *path);
14399 This call sets the extended attribute named "xattr" of the file "path"
14401 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14402 data.
14403 See also: "guestfs_lsetxattr", attr(5).
14405 This function returns 0 on success or -1 on error.
14407 This function depends on the feature "linuxxattrs". See also
14409 "guestfs_feature_available".
14410 (Added in 1.0.59)
14412 guestfs_sfdisk
14414 int
14415 guestfs_sfdisk (guestfs_h *g,
14416 const char *device,
14417 int cyls,
14418 int heads,
14419 int sectors,
14420 char *const *lines);
14421 This function is deprecated. In new code, use the "guestfs_part_add"
14423 call instead.
14424 Deprecated functions will not be removed from the API, but the fact
14426 that they are deprecated indicates that there are problems with correct
14427 use of these functions.
14428 This is a direct interface to the sfdisk(8) program for creating
14430 partitions on block devices.
14431 "device" should be a block device, for example /dev/sda.
14433 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14435 sectors on the device, which are passed directly to sfdisk(8) as the
14436 -C, -H and -S parameters. If you pass 0 for any of these, then the
14437 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14438 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
14439 (or rather, the kernel) cannot work out the right geometry and you will
14440 need to tell it.
14441 "lines" is a list of lines that we feed to sfdisk(8). For more
14443 information refer to the sfdisk(8) manpage.
14444 To create a single partition occupying the whole disk, you would pass
14446 "lines" as a single element list, when the single element being the
14447 string "," (comma).
14448 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14450 This function returns 0 on success or -1 on error.
14452 (Added in 0.8)
14454 guestfs_sfdiskM
14456 int
14457 guestfs_sfdiskM (guestfs_h *g,
14458 const char *device,
14459 char *const *lines);
14460 This function is deprecated. In new code, use the "guestfs_part_add"
14462 call instead.
14463 Deprecated functions will not be removed from the API, but the fact
14465 that they are deprecated indicates that there are problems with correct
14466 use of these functions.
14467 This is a simplified interface to the "guestfs_sfdisk" command, where
14469 partition sizes are specified in megabytes only (rounded to the nearest
14470 cylinder) and you don't need to specify the cyls, heads and sectors
14471 parameters which were rarely if ever used anyway.
14472 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14474 "guestfs_part_disk"
14475 This function returns 0 on success or -1 on error.
14477 (Added in 1.0.55)
14479 guestfs_sfdisk_N
14481 int
14482 guestfs_sfdisk_N (guestfs_h *g,
14483 const char *device,
14484 int partnum,
14485 int cyls,
14486 int heads,
14487 int sectors,
14488 const char *line);
14489 This function is deprecated. In new code, use the "guestfs_part_add"
14491 call instead.
14492 Deprecated functions will not be removed from the API, but the fact
14494 that they are deprecated indicates that there are problems with correct
14495 use of these functions.
14496 This runs sfdisk(8) option to modify just the single partition "n"
14498 (note: "n" counts from 1).
14499 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14501 for the cyls/heads/sectors parameters.
14502 See also: "guestfs_part_add"
14504 This function returns 0 on success or -1 on error.
14506 (Added in 1.0.26)
14508 guestfs_sfdisk_disk_geometry
14510 char *
14511 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14512 const char *device);
14513 This displays the disk geometry of "device" read from the partition
14515 table. Especially in the case where the underlying block device has
14516 been resized, this can be different from the kernel’s idea of the
14517 geometry (see "guestfs_sfdisk_kernel_geometry").
14518 The result is in human-readable format, and not designed to be parsed.
14520 This function returns a string, or NULL on error. The caller must free
14522 the returned string after use.
14523 (Added in 1.0.26)
14525 guestfs_sfdisk_kernel_geometry
14527 char *
14528 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14529 const char *device);
14530 This displays the kernel’s idea of the geometry of "device".
14532 The result is in human-readable format, and not designed to be parsed.
14534 This function returns a string, or NULL on error. The caller must free
14536 the returned string after use.
14537 (Added in 1.0.26)
14539 guestfs_sfdisk_l
14541 char *
14542 guestfs_sfdisk_l (guestfs_h *g,
14543 const char *device);
14544 This function is deprecated. In new code, use the "guestfs_part_list"
14546 call instead.
14547 Deprecated functions will not be removed from the API, but the fact
14549 that they are deprecated indicates that there are problems with correct
14550 use of these functions.
14551 This displays the partition table on "device", in the human-readable
14553 output of the sfdisk(8) command. It is not intended to be parsed.
14554 See also: "guestfs_part_list"
14556 This function returns a string, or NULL on error. The caller must free
14558 the returned string after use.
14559 (Added in 1.0.26)
14561 guestfs_sh
14563 char *
14564 guestfs_sh (guestfs_h *g,
14565 const char *command);
14566 This call runs a command from the guest filesystem via the guest’s
14568 /bin/sh.
14569 This is like "guestfs_command", but passes the command to:
14571 /bin/sh -c "command"
14573 Depending on the guest’s shell, this usually results in wildcards being
14575 expanded, shell expressions being interpolated and so on.
14576 All the provisos about "guestfs_command" apply to this call.
14578 This function returns a string, or NULL on error. The caller must free
14580 the returned string after use.
14581 (Added in 1.0.50)
14583 guestfs_sh_lines
14585 char **
14586 guestfs_sh_lines (guestfs_h *g,
14587 const char *command);
14588 This is the same as "guestfs_sh", but splits the result into a list of
14590 lines.
14591 See also: "guestfs_command_lines"
14593 This function returns a NULL-terminated array of strings (like
14595 environ(3)), or NULL if there was an error. The caller must free the
14596 strings and the array after use.
14597 (Added in 1.0.50)
14599 guestfs_shutdown
14601 int
14602 guestfs_shutdown (guestfs_h *g);
14603 This is the opposite of "guestfs_launch". It performs an orderly
14605 shutdown of the backend process(es). If the autosync flag is set
14606 (which is the default) then the disk image is synchronized.
14607 If the subprocess exits with an error then this function will return an
14609 error, which should not be ignored (it may indicate that the disk image
14610 could not be written out properly).
14611 It is safe to call this multiple times. Extra calls are ignored.
14613 This call does not close or free up the handle. You still need to call
14615 "guestfs_close" afterwards.
14616 "guestfs_close" will call this if you don't do it explicitly, but note
14618 that any errors are ignored in that case.
14619 This function returns 0 on success or -1 on error.
14621 (Added in 1.19.16)
14623 guestfs_sleep
14625 int
14626 guestfs_sleep (guestfs_h *g,
14627 int secs);
14628 Sleep for "secs" seconds.
14630 This function returns 0 on success or -1 on error.
14632 (Added in 1.0.41)
14634 guestfs_stat
14636 struct guestfs_stat *
14637 guestfs_stat (guestfs_h *g,
14638 const char *path);
14639 This function is deprecated. In new code, use the "guestfs_statns"
14641 call instead.
14642 Deprecated functions will not be removed from the API, but the fact
14644 that they are deprecated indicates that there are problems with correct
14645 use of these functions.
14646 Returns file information for the given "path".
14648 This is the same as the stat(2) system call.
14650 This function returns a "struct guestfs_stat *", or NULL if there was
14652 an error. The caller must call "guestfs_free_stat" after use.
14653 (Added in 1.9.2)
14655 guestfs_statns
14657 struct guestfs_statns *
14658 guestfs_statns (guestfs_h *g,
14659 const char *path);
14660 Returns file information for the given "path".
14662 This is the same as the stat(2) system call.
14664 This function returns a "struct guestfs_statns *", or NULL if there was
14666 an error. The caller must call "guestfs_free_statns" after use.
14667 (Added in 1.27.53)
14669 guestfs_statvfs
14671 struct guestfs_statvfs *
14672 guestfs_statvfs (guestfs_h *g,
14673 const char *path);
14674 Returns file system statistics for any mounted file system. "path"
14676 should be a file or directory in the mounted file system (typically it
14677 is the mount point itself, but it doesn't need to be).
14678 This is the same as the statvfs(2) system call.
14680 This function returns a "struct guestfs_statvfs *", or NULL if there
14682 was an error. The caller must call "guestfs_free_statvfs" after use.
14683 (Added in 1.9.2)
14685 guestfs_strings
14687 char **
14688 guestfs_strings (guestfs_h *g,
14689 const char *path);
14690 This runs the strings(1) command on a file and returns the list of
14692 printable strings found.
14693 The "strings" command has, in the past, had problems with parsing
14695 untrusted files. These are mitigated in the current version of
14696 libguestfs, but see "CVE-2014-8484".
14697 This function returns a NULL-terminated array of strings (like
14699 environ(3)), or NULL if there was an error. The caller must free the
14700 strings and the array after use.
14701 Because of the message protocol, there is a transfer limit of somewhere
14703 between 2MB and 4MB. See "PROTOCOL LIMITS".
14704 (Added in 1.0.22)
14706 guestfs_strings_e
14708 char **
14709 guestfs_strings_e (guestfs_h *g,
14710 const char *encoding,
14711 const char *path);
14712 This is like the "guestfs_strings" command, but allows you to specify
14714 the encoding of strings that are looked for in the source file "path".
14715 Allowed encodings are:
14717 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14719 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14720 S Single 8-bit-byte characters.
14722 b 16-bit big endian strings such as those encoded in UTF-16BE or
14724 UCS-2BE.
14725 l (lower case letter L)
14727 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14728 for examining binaries in Windows guests.
14729 B 32-bit big endian such as UCS-4BE.
14731 L 32-bit little endian such as UCS-4LE.
14733 The returned strings are transcoded to UTF-8.
14735 The "strings" command has, in the past, had problems with parsing
14737 untrusted files. These are mitigated in the current version of
14738 libguestfs, but see "CVE-2014-8484".
14739 This function returns a NULL-terminated array of strings (like
14741 environ(3)), or NULL if there was an error. The caller must free the
14742 strings and the array after use.
14743 Because of the message protocol, there is a transfer limit of somewhere
14745 between 2MB and 4MB. See "PROTOCOL LIMITS".
14746 (Added in 1.0.22)
14748 guestfs_swapoff_device
14750 int
14751 guestfs_swapoff_device (guestfs_h *g,
14752 const char *device);
14753 This command disables the libguestfs appliance swap device or partition
14755 named "device". See "guestfs_swapon_device".
14756 This function returns 0 on success or -1 on error.
14758 (Added in 1.0.66)
14760 guestfs_swapoff_file
14762 int
14763 guestfs_swapoff_file (guestfs_h *g,
14764 const char *file);
14765 This command disables the libguestfs appliance swap on file.
14767 This function returns 0 on success or -1 on error.
14769 (Added in 1.0.66)
14771 guestfs_swapoff_label
14773 int
14774 guestfs_swapoff_label (guestfs_h *g,
14775 const char *label);
14776 This command disables the libguestfs appliance swap on labeled swap
14778 partition.
14779 This function returns 0 on success or -1 on error.
14781 (Added in 1.0.66)
14783 guestfs_swapoff_uuid
14785 int
14786 guestfs_swapoff_uuid (guestfs_h *g,
14787 const char *uuid);
14788 This command disables the libguestfs appliance swap partition with the
14790 given UUID.
14791 This function returns 0 on success or -1 on error.
14793 This function depends on the feature "linuxfsuuid". See also
14795 "guestfs_feature_available".
14796 (Added in 1.0.66)
14798 guestfs_swapon_device
14800 int
14801 guestfs_swapon_device (guestfs_h *g,
14802 const char *device);
14803 This command enables the libguestfs appliance to use the swap device or
14805 partition named "device". The increased memory is made available for
14806 all commands, for example those run using "guestfs_command" or
14807 "guestfs_sh".
14808 Note that you should not swap to existing guest swap partitions unless
14810 you know what you are doing. They may contain hibernation information,
14811 or other information that the guest doesn't want you to trash. You
14812 also risk leaking information about the host to the guest this way.
14813 Instead, attach a new host device to the guest and swap on that.
14814 This function returns 0 on success or -1 on error.
14816 (Added in 1.0.66)
14818 guestfs_swapon_file
14820 int
14821 guestfs_swapon_file (guestfs_h *g,
14822 const char *file);
14823 This command enables swap to a file. See "guestfs_swapon_device" for
14825 other notes.
14826 This function returns 0 on success or -1 on error.
14828 (Added in 1.0.66)
14830 guestfs_swapon_label
14832 int
14833 guestfs_swapon_label (guestfs_h *g,
14834 const char *label);
14835 This command enables swap to a labeled swap partition. See
14837 "guestfs_swapon_device" for other notes.
14838 This function returns 0 on success or -1 on error.
14840 (Added in 1.0.66)
14842 guestfs_swapon_uuid
14844 int
14845 guestfs_swapon_uuid (guestfs_h *g,
14846 const char *uuid);
14847 This command enables swap to a swap partition with the given UUID. See
14849 "guestfs_swapon_device" for other notes.
14850 This function returns 0 on success or -1 on error.
14852 This function depends on the feature "linuxfsuuid". See also
14854 "guestfs_feature_available".
14855 (Added in 1.0.66)
14857 guestfs_sync
14859 int
14860 guestfs_sync (guestfs_h *g);
14861 This syncs the disk, so that any writes are flushed through to the
14863 underlying disk image.
14864 You should always call this if you have modified a disk image, before
14866 closing the handle.
14867 This function returns 0 on success or -1 on error.
14869 (Added in 0.3)
14871 guestfs_syslinux
14873 int
14874 guestfs_syslinux (guestfs_h *g,
14875 const char *device,
14876 ...);
14877 You may supply a list of optional arguments to this call. Use zero or
14879 more of the following pairs of parameters, and terminate the list with
14880 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14881 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14883 Install the SYSLINUX bootloader on "device".
14885 The device parameter must be either a whole disk formatted as a FAT
14887 filesystem, or a partition formatted as a FAT filesystem. In the
14888 latter case, the partition should be marked as "active"
14889 ("guestfs_part_set_bootable") and a Master Boot Record must be
14890 installed (eg. using "guestfs_pwrite_device") on the first sector of
14891 the whole disk. The SYSLINUX package comes with some suitable Master
14892 Boot Records. See the syslinux(1) man page for further information.
14893 The optional arguments are:
14895 directory
14897 Install SYSLINUX in the named subdirectory, instead of in the root
14898 directory of the FAT filesystem.
14899 Additional configuration can be supplied to SYSLINUX by placing a file
14901 called syslinux.cfg on the FAT filesystem, either in the root
14902 directory, or under directory if that optional argument is being used.
14903 For further information about the contents of this file, see
14904 syslinux(1).
14905 See also "guestfs_extlinux".
14907 This function returns 0 on success or -1 on error.
14909 This function depends on the feature "syslinux". See also
14911 "guestfs_feature_available".
14912 (Added in 1.21.27)
14914 guestfs_syslinux_va
14916 int
14917 guestfs_syslinux_va (guestfs_h *g,
14918 const char *device,
14919 va_list args);
14920 This is the "va_list variant" of "guestfs_syslinux".
14922 See "CALLS WITH OPTIONAL ARGUMENTS".
14924 guestfs_syslinux_argv
14926 int
14927 guestfs_syslinux_argv (guestfs_h *g,
14928 const char *device,
14929 const struct guestfs_syslinux_argv *optargs);
14930 This is the "argv variant" of "guestfs_syslinux".
14932 See "CALLS WITH OPTIONAL ARGUMENTS".
14934 guestfs_tail
14936 char **
14937 guestfs_tail (guestfs_h *g,
14938 const char *path);
14939 This command returns up to the last 10 lines of a file as a list of
14941 strings.
14942 This function returns a NULL-terminated array of strings (like
14944 environ(3)), or NULL if there was an error. The caller must free the
14945 strings and the array after use.
14946 Because of the message protocol, there is a transfer limit of somewhere
14948 between 2MB and 4MB. See "PROTOCOL LIMITS".
14949 (Added in 1.0.54)
14951 guestfs_tail_n
14953 char **
14954 guestfs_tail_n (guestfs_h *g,
14955 int nrlines,
14956 const char *path);
14957 If the parameter "nrlines" is a positive number, this returns the last
14959 "nrlines" lines of the file "path".
14960 If the parameter "nrlines" is a negative number, this returns lines
14962 from the file "path", starting with the "-nrlines"'th line.
14963 If the parameter "nrlines" is zero, this returns an empty list.
14965 This function returns a NULL-terminated array of strings (like
14967 environ(3)), or NULL if there was an error. The caller must free the
14968 strings and the array after use.
14969 Because of the message protocol, there is a transfer limit of somewhere
14971 between 2MB and 4MB. See "PROTOCOL LIMITS".
14972 (Added in 1.0.54)
14974 guestfs_tar_in
14976 int
14977 guestfs_tar_in (guestfs_h *g,
14978 const char *tarfile,
14979 const char *directory);
14980 This function is provided for backwards compatibility with earlier
14982 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
14983 optional arguments.
14984 (Added in 1.0.3)
14986 guestfs_tar_in_opts
14988 int
14989 guestfs_tar_in_opts (guestfs_h *g,
14990 const char *tarfile,
14991 const char *directory,
14992 ...);
14993 You may supply a list of optional arguments to this call. Use zero or
14995 more of the following pairs of parameters, and terminate the list with
14996 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14997 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
14999 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
15000 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
15001 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
15002 This command uploads and unpacks local file "tarfile" into directory.
15004 The optional "compress" flag controls compression. If not given, then
15006 the input should be an uncompressed tar file. Otherwise one of the
15007 following strings may be given to select the compression type of the
15008 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15009 all builds of libguestfs will support all of these compression types).
15010 The other optional arguments are:
15012 "xattrs"
15014 If set to true, extended attributes are restored from the tar file.
15015 "selinux"
15017 If set to true, SELinux contexts are restored from the tar file.
15018 "acls"
15020 If set to true, POSIX ACLs are restored from the tar file.
15021 This function returns 0 on success or -1 on error.
15023 (Added in 1.0.3)
15025 guestfs_tar_in_opts_va
15027 int
15028 guestfs_tar_in_opts_va (guestfs_h *g,
15029 const char *tarfile,
15030 const char *directory,
15031 va_list args);
15032 This is the "va_list variant" of "guestfs_tar_in_opts".
15034 See "CALLS WITH OPTIONAL ARGUMENTS".
15036 guestfs_tar_in_opts_argv
15038 int
15039 guestfs_tar_in_opts_argv (guestfs_h *g,
15040 const char *tarfile,
15041 const char *directory,
15042 const struct guestfs_tar_in_opts_argv *optargs);
15043 This is the "argv variant" of "guestfs_tar_in_opts".
15045 See "CALLS WITH OPTIONAL ARGUMENTS".
15047 guestfs_tar_out
15049 int
15050 guestfs_tar_out (guestfs_h *g,
15051 const char *directory,
15052 const char *tarfile);
15053 This function is provided for backwards compatibility with earlier
15055 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
15056 optional arguments.
15057 (Added in 1.0.3)
15059 guestfs_tar_out_opts
15061 int
15062 guestfs_tar_out_opts (guestfs_h *g,
15063 const char *directory,
15064 const char *tarfile,
15065 ...);
15066 You may supply a list of optional arguments to this call. Use zero or
15068 more of the following pairs of parameters, and terminate the list with
15069 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15070 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
15072 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
15073 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
15074 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
15075 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
15076 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
15077 This command packs the contents of directory and downloads it to local
15079 file "tarfile".
15080 The optional "compress" flag controls compression. If not given, then
15082 the output will be an uncompressed tar file. Otherwise one of the
15083 following strings may be given to select the compression type of the
15084 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15085 all builds of libguestfs will support all of these compression types).
15086 The other optional arguments are:
15088 "excludes"
15090 A list of wildcards. Files are excluded if they match any of the
15091 wildcards.
15092 "numericowner"
15094 If set to true, the output tar file will contain UID/GID numbers
15095 instead of user/group names.
15096 "xattrs"
15098 If set to true, extended attributes are saved in the output tar.
15099 "selinux"
15101 If set to true, SELinux contexts are saved in the output tar.
15102 "acls"
15104 If set to true, POSIX ACLs are saved in the output tar.
15105 This function returns 0 on success or -1 on error.
15107 (Added in 1.0.3)
15109 guestfs_tar_out_opts_va
15111 int
15112 guestfs_tar_out_opts_va (guestfs_h *g,
15113 const char *directory,
15114 const char *tarfile,
15115 va_list args);
15116 This is the "va_list variant" of "guestfs_tar_out_opts".
15118 See "CALLS WITH OPTIONAL ARGUMENTS".
15120 guestfs_tar_out_opts_argv
15122 int
15123 guestfs_tar_out_opts_argv (guestfs_h *g,
15124 const char *directory,
15125 const char *tarfile,
15126 const struct guestfs_tar_out_opts_argv *optargs);
15127 This is the "argv variant" of "guestfs_tar_out_opts".
15129 See "CALLS WITH OPTIONAL ARGUMENTS".
15131 guestfs_tgz_in
15133 int
15134 guestfs_tgz_in (guestfs_h *g,
15135 const char *tarball,
15136 const char *directory);
15137 This function is deprecated. In new code, use the "guestfs_tar_in"
15139 call instead.
15140 Deprecated functions will not be removed from the API, but the fact
15142 that they are deprecated indicates that there are problems with correct
15143 use of these functions.
15144 This command uploads and unpacks local file "tarball" (a gzip
15146 compressed tar file) into directory.
15147 This function returns 0 on success or -1 on error.
15149 (Added in 1.0.3)
15151 guestfs_tgz_out
15153 int
15154 guestfs_tgz_out (guestfs_h *g,
15155 const char *directory,
15156 const char *tarball);
15157 This function is deprecated. In new code, use the "guestfs_tar_out"
15159 call instead.
15160 Deprecated functions will not be removed from the API, but the fact
15162 that they are deprecated indicates that there are problems with correct
15163 use of these functions.
15164 This command packs the contents of directory and downloads it to local
15166 file "tarball".
15167 This function returns 0 on success or -1 on error.
15169 (Added in 1.0.3)
15171 guestfs_touch
15173 int
15174 guestfs_touch (guestfs_h *g,
15175 const char *path);
15176 Touch acts like the touch(1) command. It can be used to update the
15178 timestamps on a file, or, if the file does not exist, to create a new
15179 zero-length file.
15180 This command only works on regular files, and will fail on other file
15182 types such as directories, symbolic links, block special etc.
15183 This function returns 0 on success or -1 on error.
15185 (Added in 0.3)
15187 guestfs_truncate
15189 int
15190 guestfs_truncate (guestfs_h *g,
15191 const char *path);
15192 This command truncates "path" to a zero-length file. The file must
15194 exist already.
15195 This function returns 0 on success or -1 on error.
15197 (Added in 1.0.77)
15199 guestfs_truncate_size
15201 int
15202 guestfs_truncate_size (guestfs_h *g,
15203 const char *path,
15204 int64_t size);
15205 This command truncates "path" to size "size" bytes. The file must
15207 exist already.
15208 If the current file size is less than "size" then the file is extended
15210 to the required size with zero bytes. This creates a sparse file (ie.
15211 disk blocks are not allocated for the file until you write to it). To
15212 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15213 This function returns 0 on success or -1 on error.
15215 (Added in 1.0.77)
15217 guestfs_tune2fs
15219 int
15220 guestfs_tune2fs (guestfs_h *g,
15221 const char *device,
15222 ...);
15223 You may supply a list of optional arguments to this call. Use zero or
15225 more of the following pairs of parameters, and terminate the list with
15226 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15227 GUESTFS_TUNE2FS_FORCE, int force,
15229 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15230 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15231 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15232 GUESTFS_TUNE2FS_GROUP, int64_t group,
15233 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15234 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15235 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15236 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15237 GUESTFS_TUNE2FS_USER, int64_t user,
15238 This call allows you to adjust various filesystem parameters of an
15240 ext2/ext3/ext4 filesystem called "device".
15241 The optional parameters are:
15243 "force"
15245 Force tune2fs to complete the operation even in the face of errors.
15246 This is the same as the tune2fs(8) "-f" option.
15247 "maxmountcount"
15249 Set the number of mounts after which the filesystem is checked by
15250 e2fsck(8). If this is 0 then the number of mounts is disregarded.
15251 This is the same as the tune2fs(8) "-c" option.
15252 "mountcount"
15254 Set the number of times the filesystem has been mounted. This is
15255 the same as the tune2fs(8) "-C" option.
15256 "errorbehavior"
15258 Change the behavior of the kernel code when errors are detected.
15259 Possible values currently are: "continue", "remount-ro", "panic".
15260 In practice these options don't really make any difference,
15261 particularly for write errors.
15262 This is the same as the tune2fs(8) "-e" option.
15264 "group"
15266 Set the group which can use reserved filesystem blocks. This is
15267 the same as the tune2fs(8) "-g" option except that it can only be
15268 specified as a number.
15269 "intervalbetweenchecks"
15271 Adjust the maximal time between two filesystem checks (in seconds).
15272 If the option is passed as 0 then time-dependent checking is
15273 disabled.
15274 This is the same as the tune2fs(8) "-i" option.
15276 "reservedblockspercentage"
15278 Set the percentage of the filesystem which may only be allocated by
15279 privileged processes. This is the same as the tune2fs(8) "-m"
15280 option.
15281 "lastmounteddirectory"
15283 Set the last mounted directory. This is the same as the tune2fs(8)
15284 "-M" option.
15285 "reservedblockscount" Set the number of reserved filesystem blocks.
15287 This is the same as the tune2fs(8) "-r" option.
15288 "user"
15289 Set the user who can use the reserved filesystem blocks. This is
15290 the same as the tune2fs(8) "-u" option except that it can only be
15291 specified as a number.
15292 To get the current values of filesystem parameters, see
15294 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
15295 tune2fs(8) man page.
15296 This function returns 0 on success or -1 on error.
15298 (Added in 1.15.4)
15300 guestfs_tune2fs_va
15302 int
15303 guestfs_tune2fs_va (guestfs_h *g,
15304 const char *device,
15305 va_list args);
15306 This is the "va_list variant" of "guestfs_tune2fs".
15308 See "CALLS WITH OPTIONAL ARGUMENTS".
15310 guestfs_tune2fs_argv
15312 int
15313 guestfs_tune2fs_argv (guestfs_h *g,
15314 const char *device,
15315 const struct guestfs_tune2fs_argv *optargs);
15316 This is the "argv variant" of "guestfs_tune2fs".
15318 See "CALLS WITH OPTIONAL ARGUMENTS".
15320 guestfs_tune2fs_l
15322 char **
15323 guestfs_tune2fs_l (guestfs_h *g,
15324 const char *device);
15325 This returns the contents of the ext2, ext3 or ext4 filesystem
15327 superblock on "device".
15328 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
15330 for more details. The list of fields returned isn't clearly defined,
15331 and depends on both the version of "tune2fs" that libguestfs was built
15332 against, and the filesystem itself.
15333 This function returns a NULL-terminated array of strings, or NULL if
15335 there was an error. The array of strings will always have length
15336 "2n+1", where "n" keys and values alternate, followed by the trailing
15337 NULL entry. The caller must free the strings and the array after use.
15338 (Added in 1.9.2)
15340 guestfs_txz_in
15342 int
15343 guestfs_txz_in (guestfs_h *g,
15344 const char *tarball,
15345 const char *directory);
15346 This function is deprecated. In new code, use the "guestfs_tar_in"
15348 call instead.
15349 Deprecated functions will not be removed from the API, but the fact
15351 that they are deprecated indicates that there are problems with correct
15352 use of these functions.
15353 This command uploads and unpacks local file "tarball" (an xz compressed
15355 tar file) into directory.
15356 This function returns 0 on success or -1 on error.
15358 This function depends on the feature "xz". See also
15360 "guestfs_feature_available".
15361 (Added in 1.3.2)
15363 guestfs_txz_out
15365 int
15366 guestfs_txz_out (guestfs_h *g,
15367 const char *directory,
15368 const char *tarball);
15369 This function is deprecated. In new code, use the "guestfs_tar_out"
15371 call instead.
15372 Deprecated functions will not be removed from the API, but the fact
15374 that they are deprecated indicates that there are problems with correct
15375 use of these functions.
15376 This command packs the contents of directory and downloads it to local
15378 file "tarball" (as an xz compressed tar archive).
15379 This function returns 0 on success or -1 on error.
15381 This function depends on the feature "xz". See also
15383 "guestfs_feature_available".
15384 (Added in 1.3.2)
15386 guestfs_umask
15388 int
15389 guestfs_umask (guestfs_h *g,
15390 int mask);
15391 This function sets the mask used for creating new files and device
15393 nodes to "mask & 0777".
15394 Typical umask values would be 022 which creates new files with
15396 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15397 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15398 The default umask is 022. This is important because it means that
15400 directories and device nodes will be created with 0644 or 0755 mode
15401 even if you specify 0777.
15402 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15404 "guestfs_mkdir".
15405 This call returns the previous umask.
15407 On error this function returns -1.
15409 (Added in 1.0.55)
15411 guestfs_umount
15413 int
15414 guestfs_umount (guestfs_h *g,
15415 const char *pathordevice);
15416 This function is provided for backwards compatibility with earlier
15418 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15419 optional arguments.
15420 (Added in 0.8)
15422 guestfs_umount_opts
15424 int
15425 guestfs_umount_opts (guestfs_h *g,
15426 const char *pathordevice,
15427 ...);
15428 You may supply a list of optional arguments to this call. Use zero or
15430 more of the following pairs of parameters, and terminate the list with
15431 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15432 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15434 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15435 This unmounts the given filesystem. The filesystem may be specified
15437 either by its mountpoint (path) or the device which contains the
15438 filesystem.
15439 This function returns 0 on success or -1 on error.
15441 (Added in 0.8)
15443 guestfs_umount_opts_va
15445 int
15446 guestfs_umount_opts_va (guestfs_h *g,
15447 const char *pathordevice,
15448 va_list args);
15449 This is the "va_list variant" of "guestfs_umount_opts".
15451 See "CALLS WITH OPTIONAL ARGUMENTS".
15453 guestfs_umount_opts_argv
15455 int
15456 guestfs_umount_opts_argv (guestfs_h *g,
15457 const char *pathordevice,
15458 const struct guestfs_umount_opts_argv *optargs);
15459 This is the "argv variant" of "guestfs_umount_opts".
15461 See "CALLS WITH OPTIONAL ARGUMENTS".
15463 guestfs_umount_all
15465 int
15466 guestfs_umount_all (guestfs_h *g);
15467 This unmounts all mounted filesystems.
15469 Some internal mounts are not unmounted by this call.
15471 This function returns 0 on success or -1 on error.
15473 (Added in 0.8)
15475 guestfs_umount_local
15477 int
15478 guestfs_umount_local (guestfs_h *g,
15479 ...);
15480 You may supply a list of optional arguments to this call. Use zero or
15482 more of the following pairs of parameters, and terminate the list with
15483 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15484 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15486 If libguestfs is exporting the filesystem on a local mountpoint, then
15488 this unmounts it.
15489 See "MOUNT LOCAL" for full documentation.
15491 This function returns 0 on success or -1 on error.
15493 (Added in 1.17.22)
15495 guestfs_umount_local_va
15497 int
15498 guestfs_umount_local_va (guestfs_h *g,
15499 va_list args);
15500 This is the "va_list variant" of "guestfs_umount_local".
15502 See "CALLS WITH OPTIONAL ARGUMENTS".
15504 guestfs_umount_local_argv
15506 int
15507 guestfs_umount_local_argv (guestfs_h *g,
15508 const struct guestfs_umount_local_argv *optargs);
15509 This is the "argv variant" of "guestfs_umount_local".
15511 See "CALLS WITH OPTIONAL ARGUMENTS".
15513 guestfs_upload
15515 int
15516 guestfs_upload (guestfs_h *g,
15517 const char *filename,
15518 const char *remotefilename);
15519 Upload local file filename to remotefilename on the filesystem.
15521 filename can also be a named pipe.
15523 See also "guestfs_download".
15525 This function returns 0 on success or -1 on error.
15527 This long-running command can generate progress notification messages
15529 so that the caller can display a progress bar or indicator. To receive
15530 these messages, the caller must register a progress event callback.
15531 See "GUESTFS_EVENT_PROGRESS".
15532 (Added in 1.0.2)
15534 guestfs_upload_offset
15536 int
15537 guestfs_upload_offset (guestfs_h *g,
15538 const char *filename,
15539 const char *remotefilename,
15540 int64_t offset);
15541 Upload local file filename to remotefilename on the filesystem.
15543 remotefilename is overwritten starting at the byte "offset" specified.
15545 The intention is to overwrite parts of existing files or devices,
15546 although if a non-existent file is specified then it is created with a
15547 "hole" before "offset". The size of the data written is implicit in
15548 the size of the source filename.
15549 Note that there is no limit on the amount of data that can be uploaded
15551 with this call, unlike with "guestfs_pwrite", and this call always
15552 writes the full amount unless an error occurs.
15553 See also "guestfs_upload", "guestfs_pwrite".
15555 This function returns 0 on success or -1 on error.
15557 This long-running command can generate progress notification messages
15559 so that the caller can display a progress bar or indicator. To receive
15560 these messages, the caller must register a progress event callback.
15561 See "GUESTFS_EVENT_PROGRESS".
15562 (Added in 1.5.17)
15564 guestfs_user_cancel
15566 int
15567 guestfs_user_cancel (guestfs_h *g);
15568 This function cancels the current upload or download operation.
15570 Unlike most other libguestfs calls, this function is signal safe and
15572 thread safe. You can call it from a signal handler or from another
15573 thread, without needing to do any locking.
15574 The transfer that was in progress (if there is one) will stop shortly
15576 afterwards, and will return an error. The errno (see
15577 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15578 find out if the operation was cancelled or failed because of another
15579 error.
15580 No cleanup is performed: for example, if a file was being uploaded then
15582 after cancellation there may be a partially uploaded file. It is the
15583 caller’s responsibility to clean up if necessary.
15584 There are two common places that you might call "guestfs_user_cancel":
15586 In an interactive text-based program, you might call it from a "SIGINT"
15588 signal handler so that pressing "^C" cancels the current operation.
15589 (You also need to call "guestfs_set_pgroup" so that child processes
15590 don't receive the "^C" signal).
15591 In a graphical program, when the main thread is displaying a progress
15593 bar with a cancel button, wire up the cancel button to call this
15594 function.
15595 This function returns 0 on success or -1 on error.
15597 (Added in 1.11.18)
15599 guestfs_utimens
15601 int
15602 guestfs_utimens (guestfs_h *g,
15603 const char *path,
15604 int64_t atsecs,
15605 int64_t atnsecs,
15606 int64_t mtsecs,
15607 int64_t mtnsecs);
15608 This command sets the timestamps of a file with nanosecond precision.
15610 "atsecs", "atnsecs" are the last access time (atime) in secs and
15612 nanoseconds from the epoch.
15613 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
15615 nanoseconds from the epoch.
15616 If the *nsecs field contains the special value -1 then the
15618 corresponding timestamp is set to the current time. (The *secs field
15619 is ignored in this case).
15620 If the *nsecs field contains the special value -2 then the
15622 corresponding timestamp is left unchanged. (The *secs field is ignored
15623 in this case).
15624 This function returns 0 on success or -1 on error.
15626 (Added in 1.0.77)
15628 guestfs_utsname
15630 struct guestfs_utsname *
15631 guestfs_utsname (guestfs_h *g);
15632 This returns the kernel version of the appliance, where this is
15634 available. This information is only useful for debugging. Nothing in
15635 the returned structure is defined by the API.
15636 This function returns a "struct guestfs_utsname *", or NULL if there
15638 was an error. The caller must call "guestfs_free_utsname" after use.
15639 (Added in 1.19.27)
15641 guestfs_version
15643 struct guestfs_version *
15644 guestfs_version (guestfs_h *g);
15645 Return the libguestfs version number that the program is linked
15647 against.
15648 Note that because of dynamic linking this is not necessarily the
15650 version of libguestfs that you compiled against. You can compile the
15651 program, and then at runtime dynamically link against a completely
15652 different libguestfs.so library.
15653 This call was added in version 1.0.58. In previous versions of
15655 libguestfs there was no way to get the version number. From C code you
15656 can use dynamic linker functions to find out if this symbol exists (if
15657 it doesn't, then it’s an earlier version).
15658 The call returns a structure with four elements. The first three
15660 ("major", "minor" and "release") are numbers and correspond to the
15661 usual version triplet. The fourth element ("extra") is a string and is
15662 normally empty, but may be used for distro-specific information.
15663 To construct the original version string:
15665 "$major.$minor.$release$extra"
15666 See also: "LIBGUESTFS VERSION NUMBERS".
15668 Note: Don't use this call to test for availability of features. In
15670 enterprise distributions we backport features from later versions into
15671 earlier versions, making this an unreliable way to test for features.
15672 Use "guestfs_available" or "guestfs_feature_available" instead.
15673 This function returns a "struct guestfs_version *", or NULL if there
15675 was an error. The caller must call "guestfs_free_version" after use.
15676 (Added in 1.0.58)
15678 guestfs_vfs_label
15680 char *
15681 guestfs_vfs_label (guestfs_h *g,
15682 const char *mountable);
15683 This returns the label of the filesystem on "mountable".
15685 If the filesystem is unlabeled, this returns the empty string.
15687 To find a filesystem from the label, use "guestfs_findfs_label".
15689 This function returns a string, or NULL on error. The caller must free
15691 the returned string after use.
15692 (Added in 1.3.18)
15694 guestfs_vfs_minimum_size
15696 int64_t
15697 guestfs_vfs_minimum_size (guestfs_h *g,
15698 const char *mountable);
15699 Get the minimum size of filesystem in bytes. This is the minimum
15701 possible size for filesystem shrinking.
15702 If getting minimum size of specified filesystem is not supported, this
15704 will fail and set errno as ENOTSUP.
15705 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15707 On error this function returns -1.
15709 (Added in 1.31.18)
15711 guestfs_vfs_type
15713 char *
15714 guestfs_vfs_type (guestfs_h *g,
15715 const char *mountable);
15716 This command gets the filesystem type corresponding to the filesystem
15718 on "mountable".
15719 For most filesystems, the result is the name of the Linux VFS module
15721 which would be used to mount this filesystem if you mounted it without
15722 specifying the filesystem type. For example a string such as "ext3" or
15723 "ntfs".
15724 This function returns a string, or NULL on error. The caller must free
15726 the returned string after use.
15727 (Added in 1.0.75)
15729 guestfs_vfs_uuid
15731 char *
15732 guestfs_vfs_uuid (guestfs_h *g,
15733 const char *mountable);
15734 This returns the filesystem UUID of the filesystem on "mountable".
15736 If the filesystem does not have a UUID, this returns the empty string.
15738 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15740 This function returns a string, or NULL on error. The caller must free
15742 the returned string after use.
15743 (Added in 1.3.18)
15745 guestfs_vg_activate
15747 int
15748 guestfs_vg_activate (guestfs_h *g,
15749 int activate,
15750 char *const *volgroups);
15751 This command activates or (if "activate" is false) deactivates all
15753 logical volumes in the listed volume groups "volgroups".
15754 This command is the same as running "vgchange -a y|n volgroups..."
15756 Note that if "volgroups" is an empty list then all volume groups are
15758 activated or deactivated.
15759 This function returns 0 on success or -1 on error.
15761 This function depends on the feature "lvm2". See also
15763 "guestfs_feature_available".
15764 (Added in 1.0.26)
15766 guestfs_vg_activate_all
15768 int
15769 guestfs_vg_activate_all (guestfs_h *g,
15770 int activate);
15771 This command activates or (if "activate" is false) deactivates all
15773 logical volumes in all volume groups.
15774 This command is the same as running "vgchange -a y|n"
15776 This function returns 0 on success or -1 on error.
15778 This function depends on the feature "lvm2". See also
15780 "guestfs_feature_available".
15781 (Added in 1.0.26)
15783 guestfs_vgchange_uuid
15785 int
15786 guestfs_vgchange_uuid (guestfs_h *g,
15787 const char *vg);
15788 Generate a new random UUID for the volume group "vg".
15790 This function returns 0 on success or -1 on error.
15792 This function depends on the feature "lvm2". See also
15794 "guestfs_feature_available".
15795 (Added in 1.19.26)
15797 guestfs_vgchange_uuid_all
15799 int
15800 guestfs_vgchange_uuid_all (guestfs_h *g);
15801 Generate new random UUIDs for all volume groups.
15803 This function returns 0 on success or -1 on error.
15805 This function depends on the feature "lvm2". See also
15807 "guestfs_feature_available".
15808 (Added in 1.19.26)
15810 guestfs_vgcreate
15812 int
15813 guestfs_vgcreate (guestfs_h *g,
15814 const char *volgroup,
15815 char *const *physvols);
15816 This creates an LVM volume group called "volgroup" from the non-empty
15818 list of physical volumes "physvols".
15819 This function returns 0 on success or -1 on error.
15821 This function depends on the feature "lvm2". See also
15823 "guestfs_feature_available".
15824 (Added in 0.8)
15826 guestfs_vglvuuids
15828 char **
15829 guestfs_vglvuuids (guestfs_h *g,
15830 const char *vgname);
15831 Given a VG called "vgname", this returns the UUIDs of all the logical
15833 volumes created in this volume group.
15834 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15836 associate logical volumes and volume groups.
15837 See also "guestfs_vgpvuuids".
15839 This function returns a NULL-terminated array of strings (like
15841 environ(3)), or NULL if there was an error. The caller must free the
15842 strings and the array after use.
15843 (Added in 1.0.87)
15845 guestfs_vgmeta
15847 char *
15848 guestfs_vgmeta (guestfs_h *g,
15849 const char *vgname,
15850 size_t *size_r);
15851 "vgname" is an LVM volume group. This command examines the volume
15853 group and returns its metadata.
15854 Note that the metadata is an internal structure used by LVM, subject to
15856 change at any time, and is provided for information only.
15857 This function returns a buffer, or NULL on error. The size of the
15859 returned buffer is written to *size_r. The caller must free the
15860 returned buffer after use.
15861 This function depends on the feature "lvm2". See also
15863 "guestfs_feature_available".
15864 (Added in 1.17.20)
15866 guestfs_vgpvuuids
15868 char **
15869 guestfs_vgpvuuids (guestfs_h *g,
15870 const char *vgname);
15871 Given a VG called "vgname", this returns the UUIDs of all the physical
15873 volumes that this volume group resides on.
15874 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15876 associate physical volumes and volume groups.
15877 See also "guestfs_vglvuuids".
15879 This function returns a NULL-terminated array of strings (like
15881 environ(3)), or NULL if there was an error. The caller must free the
15882 strings and the array after use.
15883 (Added in 1.0.87)
15885 guestfs_vgremove
15887 int
15888 guestfs_vgremove (guestfs_h *g,
15889 const char *vgname);
15890 Remove an LVM volume group "vgname", (for example "VG").
15892 This also forcibly removes all logical volumes in the volume group (if
15894 any).
15895 This function returns 0 on success or -1 on error.
15897 This function depends on the feature "lvm2". See also
15899 "guestfs_feature_available".
15900 (Added in 1.0.13)
15902 guestfs_vgrename
15904 int
15905 guestfs_vgrename (guestfs_h *g,
15906 const char *volgroup,
15907 const char *newvolgroup);
15908 Rename a volume group "volgroup" with the new name "newvolgroup".
15910 This function returns 0 on success or -1 on error.
15912 (Added in 1.0.83)
15914 guestfs_vgs
15916 char **
15917 guestfs_vgs (guestfs_h *g);
15918 List all the volumes groups detected. This is the equivalent of the
15920 vgs(8) command.
15921 This returns a list of just the volume group names that were detected
15923 (eg. "VolGroup00").
15924 See also "guestfs_vgs_full".
15926 This function returns a NULL-terminated array of strings (like
15928 environ(3)), or NULL if there was an error. The caller must free the
15929 strings and the array after use.
15930 This function depends on the feature "lvm2". See also
15932 "guestfs_feature_available".
15933 (Added in 0.4)
15935 guestfs_vgs_full
15937 struct guestfs_lvm_vg_list *
15938 guestfs_vgs_full (guestfs_h *g);
15939 List all the volumes groups detected. This is the equivalent of the
15941 vgs(8) command. The "full" version includes all fields.
15942 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
15944 there was an error. The caller must call "guestfs_free_lvm_vg_list"
15945 after use.
15946 This function depends on the feature "lvm2". See also
15948 "guestfs_feature_available".
15949 (Added in 0.4)
15951 guestfs_vgscan
15953 int
15954 guestfs_vgscan (guestfs_h *g);
15955 This function is deprecated. In new code, use the "guestfs_lvm_scan"
15957 call instead.
15958 Deprecated functions will not be removed from the API, but the fact
15960 that they are deprecated indicates that there are problems with correct
15961 use of these functions.
15962 This rescans all block devices and rebuilds the list of LVM physical
15964 volumes, volume groups and logical volumes.
15965 This function returns 0 on success or -1 on error.
15967 (Added in 1.3.2)
15969 guestfs_vguuid
15971 char *
15972 guestfs_vguuid (guestfs_h *g,
15973 const char *vgname);
15974 This command returns the UUID of the LVM VG named "vgname".
15976 This function returns a string, or NULL on error. The caller must free
15978 the returned string after use.
15979 (Added in 1.0.87)
15981 guestfs_wait_ready
15983 int
15984 guestfs_wait_ready (guestfs_h *g);
15985 This function is deprecated. There is no replacement. Consult the API
15987 documentation in guestfs(3) for further information.
15988 Deprecated functions will not be removed from the API, but the fact
15990 that they are deprecated indicates that there are problems with correct
15991 use of these functions.
15992 This function is a no op.
15994 In versions of the API < 1.0.71 you had to call this function just
15996 after calling "guestfs_launch" to wait for the launch to complete.
15997 However this is no longer necessary because "guestfs_launch" now does
15998 the waiting.
15999 If you see any calls to this function in code then you can just remove
16001 them, unless you want to retain compatibility with older versions of
16002 the API.
16003 This function returns 0 on success or -1 on error.
16005 (Added in 0.3)
16007 guestfs_wc_c
16009 int
16010 guestfs_wc_c (guestfs_h *g,
16011 const char *path);
16012 This command counts the characters in a file, using the "wc -c"
16014 external command.
16015 On error this function returns -1.
16017 (Added in 1.0.54)
16019 guestfs_wc_l
16021 int
16022 guestfs_wc_l (guestfs_h *g,
16023 const char *path);
16024 This command counts the lines in a file, using the "wc -l" external
16026 command.
16027 On error this function returns -1.
16029 (Added in 1.0.54)
16031 guestfs_wc_w
16033 int
16034 guestfs_wc_w (guestfs_h *g,
16035 const char *path);
16036 This command counts the words in a file, using the "wc -w" external
16038 command.
16039 On error this function returns -1.
16041 (Added in 1.0.54)
16043 guestfs_wipefs
16045 int
16046 guestfs_wipefs (guestfs_h *g,
16047 const char *device);
16048 This command erases filesystem or RAID signatures from the specified
16050 "device" to make the filesystem invisible to libblkid.
16051 This does not erase the filesystem itself nor any other data from the
16053 "device".
16054 Compare with "guestfs_zero" which zeroes the first few blocks of a
16056 device.
16057 This function returns 0 on success or -1 on error.
16059 This function depends on the feature "wipefs". See also
16061 "guestfs_feature_available".
16062 (Added in 1.17.6)
16064 guestfs_write
16066 int
16067 guestfs_write (guestfs_h *g,
16068 const char *path,
16069 const char *content,
16070 size_t content_size);
16071 This call creates a file called "path". The content of the file is the
16073 string "content" (which can contain any 8 bit data).
16074 See also "guestfs_write_append".
16076 This function returns 0 on success or -1 on error.
16078 (Added in 1.3.14)
16080 guestfs_write_append
16082 int
16083 guestfs_write_append (guestfs_h *g,
16084 const char *path,
16085 const char *content,
16086 size_t content_size);
16087 This call appends "content" to the end of file "path". If "path" does
16089 not exist, then a new file is created.
16090 See also "guestfs_write".
16092 This function returns 0 on success or -1 on error.
16094 (Added in 1.11.18)
16096 guestfs_write_file
16098 int
16099 guestfs_write_file (guestfs_h *g,
16100 const char *path,
16101 const char *content,
16102 int size);
16103 This function is deprecated. In new code, use the "guestfs_write" call
16105 instead.
16106 Deprecated functions will not be removed from the API, but the fact
16108 that they are deprecated indicates that there are problems with correct
16109 use of these functions.
16110 This call creates a file called "path". The contents of the file is
16112 the string "content" (which can contain any 8 bit data), with length
16113 "size".
16114 As a special case, if "size" is 0 then the length is calculated using
16116 "strlen" (so in this case the content cannot contain embedded ASCII
16117 NULs).
16118 NB. Owing to a bug, writing content containing ASCII NUL characters
16120 does not work, even if the length is specified.
16121 This function returns 0 on success or -1 on error.
16123 Because of the message protocol, there is a transfer limit of somewhere
16125 between 2MB and 4MB. See "PROTOCOL LIMITS".
16126 (Added in 0.8)
16128 guestfs_xfs_admin
16130 int
16131 guestfs_xfs_admin (guestfs_h *g,
16132 const char *device,
16133 ...);
16134 You may supply a list of optional arguments to this call. Use zero or
16136 more of the following pairs of parameters, and terminate the list with
16137 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16138 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16140 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16141 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16142 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16143 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16144 GUESTFS_XFS_ADMIN_LABEL, const char *label,
16145 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16146 Change the parameters of the XFS filesystem on "device".
16148 Devices that are mounted cannot be modified. Administrators must
16150 unmount filesystems before this call can modify parameters.
16151 Some of the parameters of a mounted filesystem can be examined and
16153 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16154 Beginning with XFS version 5, it is no longer possible to modify the
16156 lazy-counters setting (ie. "lazycounter" parameter has no effect).
16157 This function returns 0 on success or -1 on error.
16159 This function depends on the feature "xfs". See also
16161 "guestfs_feature_available".
16162 (Added in 1.19.33)
16164 guestfs_xfs_admin_va
16166 int
16167 guestfs_xfs_admin_va (guestfs_h *g,
16168 const char *device,
16169 va_list args);
16170 This is the "va_list variant" of "guestfs_xfs_admin".
16172 See "CALLS WITH OPTIONAL ARGUMENTS".
16174 guestfs_xfs_admin_argv
16176 int
16177 guestfs_xfs_admin_argv (guestfs_h *g,
16178 const char *device,
16179 const struct guestfs_xfs_admin_argv *optargs);
16180 This is the "argv variant" of "guestfs_xfs_admin".
16182 See "CALLS WITH OPTIONAL ARGUMENTS".
16184 guestfs_xfs_growfs
16186 int
16187 guestfs_xfs_growfs (guestfs_h *g,
16188 const char *path,
16189 ...);
16190 You may supply a list of optional arguments to this call. Use zero or
16192 more of the following pairs of parameters, and terminate the list with
16193 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16194 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16196 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16197 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16198 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16199 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16200 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16201 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16202 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16203 Grow the XFS filesystem mounted at "path".
16205 The returned struct contains geometry information. Missing fields are
16207 returned as -1 (for numeric fields) or empty string.
16208 This function returns 0 on success or -1 on error.
16210 This function depends on the feature "xfs". See also
16212 "guestfs_feature_available".
16213 (Added in 1.19.28)
16215 guestfs_xfs_growfs_va
16217 int
16218 guestfs_xfs_growfs_va (guestfs_h *g,
16219 const char *path,
16220 va_list args);
16221 This is the "va_list variant" of "guestfs_xfs_growfs".
16223 See "CALLS WITH OPTIONAL ARGUMENTS".
16225 guestfs_xfs_growfs_argv
16227 int
16228 guestfs_xfs_growfs_argv (guestfs_h *g,
16229 const char *path,
16230 const struct guestfs_xfs_growfs_argv *optargs);
16231 This is the "argv variant" of "guestfs_xfs_growfs".
16233 See "CALLS WITH OPTIONAL ARGUMENTS".
16235 guestfs_xfs_info
16237 struct guestfs_xfsinfo *
16238 guestfs_xfs_info (guestfs_h *g,
16239 const char *pathordevice);
16240 "pathordevice" is a mounted XFS filesystem or a device containing an
16242 XFS filesystem. This command returns the geometry of the filesystem.
16243 The returned struct contains geometry information. Missing fields are
16245 returned as -1 (for numeric fields) or empty string.
16246 This function returns a "struct guestfs_xfsinfo *", or NULL if there
16248 was an error. The caller must call "guestfs_free_xfsinfo" after use.
16249 This function depends on the feature "xfs". See also
16251 "guestfs_feature_available".
16252 (Added in 1.19.21)
16254 guestfs_xfs_repair
16256 int
16257 guestfs_xfs_repair (guestfs_h *g,
16258 const char *device,
16259 ...);
16260 You may supply a list of optional arguments to this call. Use zero or
16262 more of the following pairs of parameters, and terminate the list with
16263 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16264 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16266 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16267 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16268 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16269 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16270 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16271 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16272 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16273 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16274 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16275 Repair corrupt or damaged XFS filesystem on "device".
16277 The filesystem is specified using the "device" argument which should be
16279 the device name of the disk partition or volume containing the
16280 filesystem. If given the name of a block device, "xfs_repair" will
16281 attempt to find the raw device associated with the specified block
16282 device and will use the raw device instead.
16283 Regardless, the filesystem to be repaired must be unmounted, otherwise,
16285 the resulting filesystem may be inconsistent or corrupt.
16286 The returned status indicates whether filesystem corruption was
16288 detected (returns 1) or was not detected (returns 0).
16289 On error this function returns -1.
16291 This function depends on the feature "xfs". See also
16293 "guestfs_feature_available".
16294 (Added in 1.19.36)
16296 guestfs_xfs_repair_va
16298 int
16299 guestfs_xfs_repair_va (guestfs_h *g,
16300 const char *device,
16301 va_list args);
16302 This is the "va_list variant" of "guestfs_xfs_repair".
16304 See "CALLS WITH OPTIONAL ARGUMENTS".
16306 guestfs_xfs_repair_argv
16308 int
16309 guestfs_xfs_repair_argv (guestfs_h *g,
16310 const char *device,
16311 const struct guestfs_xfs_repair_argv *optargs);
16312 This is the "argv variant" of "guestfs_xfs_repair".
16314 See "CALLS WITH OPTIONAL ARGUMENTS".
16316 guestfs_yara_destroy
16318 int
16319 guestfs_yara_destroy (guestfs_h *g);
16320 Destroy previously loaded Yara rules in order to free libguestfs
16322 resources.
16323 This function returns 0 on success or -1 on error.
16325 This function depends on the feature "libyara". See also
16327 "guestfs_feature_available".
16328 (Added in 1.37.13)
16330 guestfs_yara_load
16332 int
16333 guestfs_yara_load (guestfs_h *g,
16334 const char *filename);
16335 Upload a set of Yara rules from local file filename.
16337 Yara rules allow to categorize files based on textual or binary
16339 patterns within their content. See "guestfs_yara_scan" to see how to
16340 scan files with the loaded rules.
16341 Rules can be in binary format, as when compiled with yarac command, or
16343 in source code format. In the latter case, the rules will be first
16344 compiled and then loaded.
16345 Rules in source code format cannot include external files. In such
16347 cases, it is recommended to compile them first.
16348 Previously loaded rules will be destroyed.
16350 This function returns 0 on success or -1 on error.
16352 This long-running command can generate progress notification messages
16354 so that the caller can display a progress bar or indicator. To receive
16355 these messages, the caller must register a progress event callback.
16356 See "GUESTFS_EVENT_PROGRESS".
16357 This function depends on the feature "libyara". See also
16359 "guestfs_feature_available".
16360 (Added in 1.37.13)
16362 guestfs_yara_scan
16364 struct guestfs_yara_detection_list *
16365 guestfs_yara_scan (guestfs_h *g,
16366 const char *path);
16367 Scan a file with the previously loaded Yara rules.
16369 For each matching rule, a "yara_detection" structure is returned.
16371 The "yara_detection" structure contains the following fields.
16373 "yara_name"
16375 Path of the file matching a Yara rule.
16376 "yara_rule"
16378 Identifier of the Yara rule which matched against the given file.
16379 This function returns a "struct guestfs_yara_detection_list *", or NULL
16381 if there was an error. The caller must call
16382 "guestfs_free_yara_detection_list" after use.
16383 This long-running command can generate progress notification messages
16385 so that the caller can display a progress bar or indicator. To receive
16386 these messages, the caller must register a progress event callback.
16387 See "GUESTFS_EVENT_PROGRESS".
16388 This function depends on the feature "libyara". See also
16390 "guestfs_feature_available".
16391 (Added in 1.37.13)
16393 guestfs_zegrep
16395 char **
16396 guestfs_zegrep (guestfs_h *g,
16397 const char *regex,
16398 const char *path);
16399 This function is deprecated. In new code, use the "guestfs_grep" call
16401 instead.
16402 Deprecated functions will not be removed from the API, but the fact
16404 that they are deprecated indicates that there are problems with correct
16405 use of these functions.
16406 This calls the external "zegrep" program and returns the matching
16408 lines.
16409 This function returns a NULL-terminated array of strings (like
16411 environ(3)), or NULL if there was an error. The caller must free the
16412 strings and the array after use.
16413 Because of the message protocol, there is a transfer limit of somewhere
16415 between 2MB and 4MB. See "PROTOCOL LIMITS".
16416 (Added in 1.0.66)
16418 guestfs_zegrepi
16420 char **
16421 guestfs_zegrepi (guestfs_h *g,
16422 const char *regex,
16423 const char *path);
16424 This function is deprecated. In new code, use the "guestfs_grep" call
16426 instead.
16427 Deprecated functions will not be removed from the API, but the fact
16429 that they are deprecated indicates that there are problems with correct
16430 use of these functions.
16431 This calls the external "zegrep -i" program and returns the matching
16433 lines.
16434 This function returns a NULL-terminated array of strings (like
16436 environ(3)), or NULL if there was an error. The caller must free the
16437 strings and the array after use.
16438 Because of the message protocol, there is a transfer limit of somewhere
16440 between 2MB and 4MB. See "PROTOCOL LIMITS".
16441 (Added in 1.0.66)
16443 guestfs_zero
16445 int
16446 guestfs_zero (guestfs_h *g,
16447 const char *device);
16448 This command writes zeroes over the first few blocks of "device".
16450 How many blocks are zeroed isn't specified (but it’s not enough to
16452 securely wipe the device). It should be sufficient to remove any
16453 partition tables, filesystem superblocks and so on.
16454 If blocks are already zero, then this command avoids writing zeroes.
16456 This prevents the underlying device from becoming non-sparse or growing
16457 unnecessarily.
16458 See also: "guestfs_zero_device", "guestfs_scrub_device",
16460 "guestfs_is_zero_device"
16461 This function returns 0 on success or -1 on error.
16463 This long-running command can generate progress notification messages
16465 so that the caller can display a progress bar or indicator. To receive
16466 these messages, the caller must register a progress event callback.
16467 See "GUESTFS_EVENT_PROGRESS".
16468 (Added in 1.0.16)
16470 guestfs_zero_device
16472 int
16473 guestfs_zero_device (guestfs_h *g,
16474 const char *device);
16475 This command writes zeroes over the entire "device". Compare with
16477 "guestfs_zero" which just zeroes the first few blocks of a device.
16478 If blocks are already zero, then this command avoids writing zeroes.
16480 This prevents the underlying device from becoming non-sparse or growing
16481 unnecessarily.
16482 This function returns 0 on success or -1 on error.
16484 This long-running command can generate progress notification messages
16486 so that the caller can display a progress bar or indicator. To receive
16487 these messages, the caller must register a progress event callback.
16488 See "GUESTFS_EVENT_PROGRESS".
16489 (Added in 1.3.1)
16491 guestfs_zero_free_space
16493 int
16494 guestfs_zero_free_space (guestfs_h *g,
16495 const char *directory);
16496 Zero the free space in the filesystem mounted on directory. The
16498 filesystem must be mounted read-write.
16499 The filesystem contents are not affected, but any free space in the
16501 filesystem is freed.
16502 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16504 either as an alternative to this, or after calling this, depending on
16505 your requirements.
16506 This function returns 0 on success or -1 on error.
16508 This long-running command can generate progress notification messages
16510 so that the caller can display a progress bar or indicator. To receive
16511 these messages, the caller must register a progress event callback.
16512 See "GUESTFS_EVENT_PROGRESS".
16513 (Added in 1.17.18)
16515 guestfs_zerofree
16517 int
16518 guestfs_zerofree (guestfs_h *g,
16519 const char *device);
16520 This runs the zerofree program on "device". This program claims to
16522 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16523 it possible to compress the filesystem more effectively.
16524 You should not run this program if the filesystem is mounted.
16526 It is possible that using this program can damage the filesystem or
16528 data on the filesystem.
16529 This function returns 0 on success or -1 on error.
16531 This function depends on the feature "zerofree". See also
16533 "guestfs_feature_available".
16534 (Added in 1.0.26)
16536 guestfs_zfgrep
16538 char **
16539 guestfs_zfgrep (guestfs_h *g,
16540 const char *pattern,
16541 const char *path);
16542 This function is deprecated. In new code, use the "guestfs_grep" call
16544 instead.
16545 Deprecated functions will not be removed from the API, but the fact
16547 that they are deprecated indicates that there are problems with correct
16548 use of these functions.
16549 This calls the external "zfgrep" program and returns the matching
16551 lines.
16552 This function returns a NULL-terminated array of strings (like
16554 environ(3)), or NULL if there was an error. The caller must free the
16555 strings and the array after use.
16556 Because of the message protocol, there is a transfer limit of somewhere
16558 between 2MB and 4MB. See "PROTOCOL LIMITS".
16559 (Added in 1.0.66)
16561 guestfs_zfgrepi
16563 char **
16564 guestfs_zfgrepi (guestfs_h *g,
16565 const char *pattern,
16566 const char *path);
16567 This function is deprecated. In new code, use the "guestfs_grep" call
16569 instead.
16570 Deprecated functions will not be removed from the API, but the fact
16572 that they are deprecated indicates that there are problems with correct
16573 use of these functions.
16574 This calls the external "zfgrep -i" program and returns the matching
16576 lines.
16577 This function returns a NULL-terminated array of strings (like
16579 environ(3)), or NULL if there was an error. The caller must free the
16580 strings and the array after use.
16581 Because of the message protocol, there is a transfer limit of somewhere
16583 between 2MB and 4MB. See "PROTOCOL LIMITS".
16584 (Added in 1.0.66)
16586 guestfs_zfile
16588 char *
16589 guestfs_zfile (guestfs_h *g,
16590 const char *meth,
16591 const char *path);
16592 This function is deprecated. In new code, use the "guestfs_file" call
16594 instead.
16595 Deprecated functions will not be removed from the API, but the fact
16597 that they are deprecated indicates that there are problems with correct
16598 use of these functions.
16599 This command runs file(1) after first decompressing "path" using
16601 "meth".
16602 "meth" must be one of "gzip", "compress" or "bzip2".
16604 Since 1.0.63, use "guestfs_file" instead which can now process
16606 compressed files.
16607 This function returns a string, or NULL on error. The caller must free
16609 the returned string after use.
16610 (Added in 1.0.59)
16612 guestfs_zgrep
16614 char **
16615 guestfs_zgrep (guestfs_h *g,
16616 const char *regex,
16617 const char *path);
16618 This function is deprecated. In new code, use the "guestfs_grep" call
16620 instead.
16621 Deprecated functions will not be removed from the API, but the fact
16623 that they are deprecated indicates that there are problems with correct
16624 use of these functions.
16625 This calls the external zgrep(1) program and returns the matching
16627 lines.
16628 This function returns a NULL-terminated array of strings (like
16630 environ(3)), or NULL if there was an error. The caller must free the
16631 strings and the array after use.
16632 Because of the message protocol, there is a transfer limit of somewhere
16634 between 2MB and 4MB. See "PROTOCOL LIMITS".
16635 (Added in 1.0.66)
16637 guestfs_zgrepi
16639 char **
16640 guestfs_zgrepi (guestfs_h *g,
16641 const char *regex,
16642 const char *path);
16643 This function is deprecated. In new code, use the "guestfs_grep" call
16645 instead.
16646 Deprecated functions will not be removed from the API, but the fact
16648 that they are deprecated indicates that there are problems with correct
16649 use of these functions.
16650 This calls the external "zgrep -i" program and returns the matching
16652 lines.
16653 This function returns a NULL-terminated array of strings (like
16655 environ(3)), or NULL if there was an error. The caller must free the
16656 strings and the array after use.
16657 Because of the message protocol, there is a transfer limit of somewhere
16659 between 2MB and 4MB. See "PROTOCOL LIMITS".
16660 (Added in 1.0.66)
16662
16664 guestfs_int_bool
16665 struct guestfs_int_bool {
16666 int32_t i;
16667 int32_t b;
16668 };
16669 struct guestfs_int_bool_list {
16671 uint32_t len; /* Number of elements in list. */
16672 struct guestfs_int_bool *val; /* Elements. */
16673 };
16674 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16676 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16677 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16679 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16680 void guestfs_free_int_bool (struct guestfs_int_bool *);
16682 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16683 guestfs_lvm_pv
16685 struct guestfs_lvm_pv {
16686 char *pv_name;
16687 /* The next field is NOT nul-terminated, be careful when printing it: */
16688 char pv_uuid[32];
16689 char *pv_fmt;
16690 uint64_t pv_size;
16691 uint64_t dev_size;
16692 uint64_t pv_free;
16693 uint64_t pv_used;
16694 char *pv_attr;
16695 int64_t pv_pe_count;
16696 int64_t pv_pe_alloc_count;
16697 char *pv_tags;
16698 uint64_t pe_start;
16699 int64_t pv_mda_count;
16700 uint64_t pv_mda_free;
16701 };
16702 struct guestfs_lvm_pv_list {
16704 uint32_t len; /* Number of elements in list. */
16705 struct guestfs_lvm_pv *val; /* Elements. */
16706 };
16707 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16709 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16710 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16712 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16713 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16715 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16716 guestfs_lvm_vg
16718 struct guestfs_lvm_vg {
16719 char *vg_name;
16720 /* The next field is NOT nul-terminated, be careful when printing it: */
16721 char vg_uuid[32];
16722 char *vg_fmt;
16723 char *vg_attr;
16724 uint64_t vg_size;
16725 uint64_t vg_free;
16726 char *vg_sysid;
16727 uint64_t vg_extent_size;
16728 int64_t vg_extent_count;
16729 int64_t vg_free_count;
16730 int64_t max_lv;
16731 int64_t max_pv;
16732 int64_t pv_count;
16733 int64_t lv_count;
16734 int64_t snap_count;
16735 int64_t vg_seqno;
16736 char *vg_tags;
16737 int64_t vg_mda_count;
16738 uint64_t vg_mda_free;
16739 };
16740 struct guestfs_lvm_vg_list {
16742 uint32_t len; /* Number of elements in list. */
16743 struct guestfs_lvm_vg *val; /* Elements. */
16744 };
16745 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16747 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16748 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16750 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16751 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16753 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16754 guestfs_lvm_lv
16756 struct guestfs_lvm_lv {
16757 char *lv_name;
16758 /* The next field is NOT nul-terminated, be careful when printing it: */
16759 char lv_uuid[32];
16760 char *lv_attr;
16761 int64_t lv_major;
16762 int64_t lv_minor;
16763 int64_t lv_kernel_major;
16764 int64_t lv_kernel_minor;
16765 uint64_t lv_size;
16766 int64_t seg_count;
16767 char *origin;
16768 /* The next field is [0..100] or -1 meaning 'not present': */
16769 float snap_percent;
16770 /* The next field is [0..100] or -1 meaning 'not present': */
16771 float copy_percent;
16772 char *move_pv;
16773 char *lv_tags;
16774 char *mirror_log;
16775 char *modules;
16776 };
16777 struct guestfs_lvm_lv_list {
16779 uint32_t len; /* Number of elements in list. */
16780 struct guestfs_lvm_lv *val; /* Elements. */
16781 };
16782 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16784 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16785 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16787 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16788 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16790 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16791 guestfs_stat
16793 struct guestfs_stat {
16794 int64_t dev;
16795 int64_t ino;
16796 int64_t mode;
16797 int64_t nlink;
16798 int64_t uid;
16799 int64_t gid;
16800 int64_t rdev;
16801 int64_t size;
16802 int64_t blksize;
16803 int64_t blocks;
16804 int64_t atime;
16805 int64_t mtime;
16806 int64_t ctime;
16807 };
16808 struct guestfs_stat_list {
16810 uint32_t len; /* Number of elements in list. */
16811 struct guestfs_stat *val; /* Elements. */
16812 };
16813 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16815 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16816 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16818 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16819 void guestfs_free_stat (struct guestfs_stat *);
16821 void guestfs_free_stat_list (struct guestfs_stat_list *);
16822 guestfs_statns
16824 struct guestfs_statns {
16825 int64_t st_dev;
16826 int64_t st_ino;
16827 int64_t st_mode;
16828 int64_t st_nlink;
16829 int64_t st_uid;
16830 int64_t st_gid;
16831 int64_t st_rdev;
16832 int64_t st_size;
16833 int64_t st_blksize;
16834 int64_t st_blocks;
16835 int64_t st_atime_sec;
16836 int64_t st_atime_nsec;
16837 int64_t st_mtime_sec;
16838 int64_t st_mtime_nsec;
16839 int64_t st_ctime_sec;
16840 int64_t st_ctime_nsec;
16841 int64_t st_spare1;
16842 int64_t st_spare2;
16843 int64_t st_spare3;
16844 int64_t st_spare4;
16845 int64_t st_spare5;
16846 int64_t st_spare6;
16847 };
16848 struct guestfs_statns_list {
16850 uint32_t len; /* Number of elements in list. */
16851 struct guestfs_statns *val; /* Elements. */
16852 };
16853 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16855 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16856 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16858 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16859 void guestfs_free_statns (struct guestfs_statns *);
16861 void guestfs_free_statns_list (struct guestfs_statns_list *);
16862 guestfs_statvfs
16864 struct guestfs_statvfs {
16865 int64_t bsize;
16866 int64_t frsize;
16867 int64_t blocks;
16868 int64_t bfree;
16869 int64_t bavail;
16870 int64_t files;
16871 int64_t ffree;
16872 int64_t favail;
16873 int64_t fsid;
16874 int64_t flag;
16875 int64_t namemax;
16876 };
16877 struct guestfs_statvfs_list {
16879 uint32_t len; /* Number of elements in list. */
16880 struct guestfs_statvfs *val; /* Elements. */
16881 };
16882 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16884 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16885 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16887 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16888 void guestfs_free_statvfs (struct guestfs_statvfs *);
16890 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16891 guestfs_dirent
16893 struct guestfs_dirent {
16894 int64_t ino;
16895 char ftyp;
16896 char *name;
16897 };
16898 struct guestfs_dirent_list {
16900 uint32_t len; /* Number of elements in list. */
16901 struct guestfs_dirent *val; /* Elements. */
16902 };
16903 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16905 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16906 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16908 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16909 void guestfs_free_dirent (struct guestfs_dirent *);
16911 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16912 guestfs_version
16914 struct guestfs_version {
16915 int64_t major;
16916 int64_t minor;
16917 int64_t release;
16918 char *extra;
16919 };
16920 struct guestfs_version_list {
16922 uint32_t len; /* Number of elements in list. */
16923 struct guestfs_version *val; /* Elements. */
16924 };
16925 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16927 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16928 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16930 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16931 void guestfs_free_version (struct guestfs_version *);
16933 void guestfs_free_version_list (struct guestfs_version_list *);
16934 guestfs_xattr
16936 struct guestfs_xattr {
16937 char *attrname;
16938 /* The next two fields describe a byte array. */
16939 uint32_t attrval_len;
16940 char *attrval;
16941 };
16942 struct guestfs_xattr_list {
16944 uint32_t len; /* Number of elements in list. */
16945 struct guestfs_xattr *val; /* Elements. */
16946 };
16947 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16949 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16950 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
16952 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
16953 void guestfs_free_xattr (struct guestfs_xattr *);
16955 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
16956 guestfs_inotify_event
16958 struct guestfs_inotify_event {
16959 int64_t in_wd;
16960 uint32_t in_mask;
16961 uint32_t in_cookie;
16962 char *in_name;
16963 };
16964 struct guestfs_inotify_event_list {
16966 uint32_t len; /* Number of elements in list. */
16967 struct guestfs_inotify_event *val; /* Elements. */
16968 };
16969 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
16971 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
16972 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
16974 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
16975 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
16977 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
16978 guestfs_partition
16980 struct guestfs_partition {
16981 int32_t part_num;
16982 uint64_t part_start;
16983 uint64_t part_end;
16984 uint64_t part_size;
16985 };
16986 struct guestfs_partition_list {
16988 uint32_t len; /* Number of elements in list. */
16989 struct guestfs_partition *val; /* Elements. */
16990 };
16991 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
16993 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
16994 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
16996 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
16997 void guestfs_free_partition (struct guestfs_partition *);
16999 void guestfs_free_partition_list (struct guestfs_partition_list *);
17000 guestfs_application
17002 struct guestfs_application {
17003 char *app_name;
17004 char *app_display_name;
17005 int32_t app_epoch;
17006 char *app_version;
17007 char *app_release;
17008 char *app_install_path;
17009 char *app_trans_path;
17010 char *app_publisher;
17011 char *app_url;
17012 char *app_source_package;
17013 char *app_summary;
17014 char *app_description;
17015 };
17016 struct guestfs_application_list {
17018 uint32_t len; /* Number of elements in list. */
17019 struct guestfs_application *val; /* Elements. */
17020 };
17021 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
17023 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
17024 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
17026 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
17027 void guestfs_free_application (struct guestfs_application *);
17029 void guestfs_free_application_list (struct guestfs_application_list *);
17030 guestfs_application2
17032 struct guestfs_application2 {
17033 char *app2_name;
17034 char *app2_display_name;
17035 int32_t app2_epoch;
17036 char *app2_version;
17037 char *app2_release;
17038 char *app2_arch;
17039 char *app2_install_path;
17040 char *app2_trans_path;
17041 char *app2_publisher;
17042 char *app2_url;
17043 char *app2_source_package;
17044 char *app2_summary;
17045 char *app2_description;
17046 char *app2_spare1;
17047 char *app2_spare2;
17048 char *app2_spare3;
17049 char *app2_spare4;
17050 };
17051 struct guestfs_application2_list {
17053 uint32_t len; /* Number of elements in list. */
17054 struct guestfs_application2 *val; /* Elements. */
17055 };
17056 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
17058 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
17059 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
17061 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
17062 void guestfs_free_application2 (struct guestfs_application2 *);
17064 void guestfs_free_application2_list (struct guestfs_application2_list *);
17065 guestfs_isoinfo
17067 struct guestfs_isoinfo {
17068 char *iso_system_id;
17069 char *iso_volume_id;
17070 uint32_t iso_volume_space_size;
17071 uint32_t iso_volume_set_size;
17072 uint32_t iso_volume_sequence_number;
17073 uint32_t iso_logical_block_size;
17074 char *iso_volume_set_id;
17075 char *iso_publisher_id;
17076 char *iso_data_preparer_id;
17077 char *iso_application_id;
17078 char *iso_copyright_file_id;
17079 char *iso_abstract_file_id;
17080 char *iso_bibliographic_file_id;
17081 int64_t iso_volume_creation_t;
17082 int64_t iso_volume_modification_t;
17083 int64_t iso_volume_expiration_t;
17084 int64_t iso_volume_effective_t;
17085 };
17086 struct guestfs_isoinfo_list {
17088 uint32_t len; /* Number of elements in list. */
17089 struct guestfs_isoinfo *val; /* Elements. */
17090 };
17091 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
17093 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
17094 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
17096 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
17097 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
17099 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
17100 guestfs_mdstat
17102 struct guestfs_mdstat {
17103 char *mdstat_device;
17104 int32_t mdstat_index;
17105 char *mdstat_flags;
17106 };
17107 struct guestfs_mdstat_list {
17109 uint32_t len; /* Number of elements in list. */
17110 struct guestfs_mdstat *val; /* Elements. */
17111 };
17112 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
17114 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
17115 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
17117 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
17118 void guestfs_free_mdstat (struct guestfs_mdstat *);
17120 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
17121 guestfs_btrfssubvolume
17123 struct guestfs_btrfssubvolume {
17124 uint64_t btrfssubvolume_id;
17125 uint64_t btrfssubvolume_top_level_id;
17126 char *btrfssubvolume_path;
17127 };
17128 struct guestfs_btrfssubvolume_list {
17130 uint32_t len; /* Number of elements in list. */
17131 struct guestfs_btrfssubvolume *val; /* Elements. */
17132 };
17133 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17135 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17136 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17138 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17139 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17141 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17142 guestfs_btrfsqgroup
17144 struct guestfs_btrfsqgroup {
17145 char *btrfsqgroup_id;
17146 uint64_t btrfsqgroup_rfer;
17147 uint64_t btrfsqgroup_excl;
17148 };
17149 struct guestfs_btrfsqgroup_list {
17151 uint32_t len; /* Number of elements in list. */
17152 struct guestfs_btrfsqgroup *val; /* Elements. */
17153 };
17154 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17156 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17157 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17159 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17160 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17162 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17163 guestfs_btrfsbalance
17165 struct guestfs_btrfsbalance {
17166 char *btrfsbalance_status;
17167 uint64_t btrfsbalance_total;
17168 uint64_t btrfsbalance_balanced;
17169 uint64_t btrfsbalance_considered;
17170 uint64_t btrfsbalance_left;
17171 };
17172 struct guestfs_btrfsbalance_list {
17174 uint32_t len; /* Number of elements in list. */
17175 struct guestfs_btrfsbalance *val; /* Elements. */
17176 };
17177 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17179 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17180 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17182 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17183 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17185 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17186 guestfs_btrfsscrub
17188 struct guestfs_btrfsscrub {
17189 uint64_t btrfsscrub_data_extents_scrubbed;
17190 uint64_t btrfsscrub_tree_extents_scrubbed;
17191 uint64_t btrfsscrub_data_bytes_scrubbed;
17192 uint64_t btrfsscrub_tree_bytes_scrubbed;
17193 uint64_t btrfsscrub_read_errors;
17194 uint64_t btrfsscrub_csum_errors;
17195 uint64_t btrfsscrub_verify_errors;
17196 uint64_t btrfsscrub_no_csum;
17197 uint64_t btrfsscrub_csum_discards;
17198 uint64_t btrfsscrub_super_errors;
17199 uint64_t btrfsscrub_malloc_errors;
17200 uint64_t btrfsscrub_uncorrectable_errors;
17201 uint64_t btrfsscrub_unverified_errors;
17202 uint64_t btrfsscrub_corrected_errors;
17203 uint64_t btrfsscrub_last_physical;
17204 };
17205 struct guestfs_btrfsscrub_list {
17207 uint32_t len; /* Number of elements in list. */
17208 struct guestfs_btrfsscrub *val; /* Elements. */
17209 };
17210 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17212 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17213 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17215 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17216 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17218 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17219 guestfs_xfsinfo
17221 struct guestfs_xfsinfo {
17222 char *xfs_mntpoint;
17223 uint32_t xfs_inodesize;
17224 uint32_t xfs_agcount;
17225 uint32_t xfs_agsize;
17226 uint32_t xfs_sectsize;
17227 uint32_t xfs_attr;
17228 uint32_t xfs_blocksize;
17229 uint64_t xfs_datablocks;
17230 uint32_t xfs_imaxpct;
17231 uint32_t xfs_sunit;
17232 uint32_t xfs_swidth;
17233 uint32_t xfs_dirversion;
17234 uint32_t xfs_dirblocksize;
17235 uint32_t xfs_cimode;
17236 char *xfs_logname;
17237 uint32_t xfs_logblocksize;
17238 uint32_t xfs_logblocks;
17239 uint32_t xfs_logversion;
17240 uint32_t xfs_logsectsize;
17241 uint32_t xfs_logsunit;
17242 uint32_t xfs_lazycount;
17243 char *xfs_rtname;
17244 uint32_t xfs_rtextsize;
17245 uint64_t xfs_rtblocks;
17246 uint64_t xfs_rtextents;
17247 };
17248 struct guestfs_xfsinfo_list {
17250 uint32_t len; /* Number of elements in list. */
17251 struct guestfs_xfsinfo *val; /* Elements. */
17252 };
17253 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17255 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17256 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17258 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17259 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17261 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17262 guestfs_utsname
17264 struct guestfs_utsname {
17265 char *uts_sysname;
17266 char *uts_release;
17267 char *uts_version;
17268 char *uts_machine;
17269 };
17270 struct guestfs_utsname_list {
17272 uint32_t len; /* Number of elements in list. */
17273 struct guestfs_utsname *val; /* Elements. */
17274 };
17275 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17277 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17278 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17280 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17281 void guestfs_free_utsname (struct guestfs_utsname *);
17283 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17284 guestfs_hivex_node
17286 struct guestfs_hivex_node {
17287 int64_t hivex_node_h;
17288 };
17289 struct guestfs_hivex_node_list {
17291 uint32_t len; /* Number of elements in list. */
17292 struct guestfs_hivex_node *val; /* Elements. */
17293 };
17294 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17296 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17297 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17299 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17300 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17302 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17303 guestfs_hivex_value
17305 struct guestfs_hivex_value {
17306 int64_t hivex_value_h;
17307 };
17308 struct guestfs_hivex_value_list {
17310 uint32_t len; /* Number of elements in list. */
17311 struct guestfs_hivex_value *val; /* Elements. */
17312 };
17313 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17315 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17316 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17318 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17319 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17321 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17322 guestfs_internal_mountable
17324 struct guestfs_internal_mountable {
17325 int32_t im_type;
17326 char *im_device;
17327 char *im_volume;
17328 };
17329 struct guestfs_internal_mountable_list {
17331 uint32_t len; /* Number of elements in list. */
17332 struct guestfs_internal_mountable *val; /* Elements. */
17333 };
17334 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17336 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17337 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17339 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17340 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17342 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17343 guestfs_tsk_dirent
17345 struct guestfs_tsk_dirent {
17346 uint64_t tsk_inode;
17347 char tsk_type;
17348 int64_t tsk_size;
17349 char *tsk_name;
17350 uint32_t tsk_flags;
17351 int64_t tsk_atime_sec;
17352 int64_t tsk_atime_nsec;
17353 int64_t tsk_mtime_sec;
17354 int64_t tsk_mtime_nsec;
17355 int64_t tsk_ctime_sec;
17356 int64_t tsk_ctime_nsec;
17357 int64_t tsk_crtime_sec;
17358 int64_t tsk_crtime_nsec;
17359 int64_t tsk_nlink;
17360 char *tsk_link;
17361 int64_t tsk_spare1;
17362 };
17363 struct guestfs_tsk_dirent_list {
17365 uint32_t len; /* Number of elements in list. */
17366 struct guestfs_tsk_dirent *val; /* Elements. */
17367 };
17368 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17370 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17371 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17373 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17374 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17376 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17377 guestfs_yara_detection
17379 struct guestfs_yara_detection {
17380 char *yara_name;
17381 char *yara_rule;
17382 };
17383 struct guestfs_yara_detection_list {
17385 uint32_t len; /* Number of elements in list. */
17386 struct guestfs_yara_detection *val; /* Elements. */
17387 };
17388 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17390 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17391 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17393 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17394 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17396 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17397
17399 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17400 Using "guestfs_available" you can test availability of the following
17401 groups of functions. This test queries the appliance to see if the
17402 appliance you are currently using supports the functionality.
17403 acl The following functions: "guestfs_acl_delete_def_file"
17405 "guestfs_acl_get_file" "guestfs_acl_set_file"
17406 blkdiscard
17408 The following functions: "guestfs_blkdiscard"
17409 blkdiscardzeroes
17411 The following functions: "guestfs_blkdiscardzeroes"
17412 btrfs
17414 The following functions: "guestfs_btrfs_balance_cancel"
17415 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17416 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17417 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17418 "guestfs_btrfs_filesystem_defragment"
17419 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17420 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17421 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17422 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17423 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17424 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17425 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17426 "guestfs_btrfs_rescue_chunk_recover"
17427 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17428 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17429 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17430 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17431 "guestfs_btrfs_subvolume_get_default"
17432 "guestfs_btrfs_subvolume_list"
17433 "guestfs_btrfs_subvolume_set_default"
17434 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17435 "guestfs_btrfstune_enable_extended_inode_refs"
17436 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17437 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17438 clevisluks
17440 The following functions: "guestfs_clevis_luks_unlock"
17441 extlinux
17443 The following functions: "guestfs_extlinux"
17444 f2fs
17446 The following functions: "guestfs_f2fs_expand"
17447 fstrim
17449 The following functions: "guestfs_fstrim"
17450 gdisk
17452 The following functions: "guestfs_part_expand_gpt"
17453 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17454 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17455 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17456 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17457 "guestfs_part_set_gpt_type"
17458 grub
17460 The following functions: "guestfs_grub_install"
17461 hivex
17463 The following functions: "guestfs_hivex_close"
17464 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17465 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17466 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17467 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17468 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17469 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17470 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17471 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17472 inotify
17474 The following functions: "guestfs_inotify_add_watch"
17475 "guestfs_inotify_close" "guestfs_inotify_files"
17476 "guestfs_inotify_init" "guestfs_inotify_read"
17477 "guestfs_inotify_rm_watch"
17478 journal
17480 The following functions: "guestfs_internal_journal_get"
17481 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17482 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17483 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17484 "guestfs_journal_skip"
17485 ldm The following functions: "guestfs_ldmtool_create_all"
17487 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17488 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17489 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17490 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17491 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17492 "guestfs_list_ldm_volumes"
17493 libtsk
17495 The following functions: "guestfs_internal_filesystem_walk"
17496 "guestfs_internal_find_inode"
17497 libyara
17499 The following functions: "guestfs_internal_yara_scan"
17500 "guestfs_yara_destroy" "guestfs_yara_load"
17501 linuxcaps
17503 The following functions: "guestfs_cap_get_file"
17504 "guestfs_cap_set_file"
17505 linuxfsuuid
17507 The following functions: "guestfs_mke2fs_JU"
17508 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17509 "guestfs_swapon_uuid"
17510 linuxmodules
17512 The following functions: "guestfs_modprobe"
17513 linuxxattrs
17515 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17516 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17517 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17518 "guestfs_removexattr" "guestfs_setxattr"
17519 luks
17521 The following functions: "guestfs_cryptsetup_close"
17522 "guestfs_cryptsetup_open" "guestfs_luks_add_key"
17523 "guestfs_luks_close" "guestfs_luks_format"
17524 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17525 "guestfs_luks_open" "guestfs_luks_open_ro" "guestfs_luks_uuid"
17526 lvm2
17528 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17529 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17530 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17531 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17532 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17533 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17534 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17535 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17536 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17537 "guestfs_vgs" "guestfs_vgs_full"
17538 mdadm
17540 The following functions: "guestfs_md_create" "guestfs_md_detail"
17541 "guestfs_md_stat" "guestfs_md_stop"
17542 mknod
17544 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17545 "guestfs_mknod_b" "guestfs_mknod_c"
17546 ntfs3g
17548 The following functions: "guestfs_ntfs_3g_probe"
17549 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17550 ntfsprogs
17552 The following functions: "guestfs_ntfsresize"
17553 "guestfs_ntfsresize_size"
17554 rsync
17556 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17557 "guestfs_rsync_out"
17558 scrub
17560 The following functions: "guestfs_scrub_device"
17561 "guestfs_scrub_file" "guestfs_scrub_freespace"
17562 selinux
17564 The following functions: "guestfs_getcon" "guestfs_setcon"
17565 selinuxrelabel
17567 The following functions: "guestfs_selinux_relabel"
17568 sleuthkit
17570 The following functions: "guestfs_download_blocks"
17571 "guestfs_download_inode"
17572 squashfs
17574 The following functions: "guestfs_mksquashfs"
17575 syslinux
17577 The following functions: "guestfs_syslinux"
17578 wipefs
17580 The following functions: "guestfs_wipefs"
17581 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17583 "guestfs_xfs_info" "guestfs_xfs_repair"
17584 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17586 zerofree
17588 The following functions: "guestfs_zerofree"
17589 FILESYSTEM AVAILABLE
17591 The "guestfs_filesystem_available" call tests whether a filesystem type
17592 is supported by the appliance kernel.
17593 This is mainly useful as a negative test. If this returns true, it
17595 doesn't mean that a particular filesystem can be mounted, since
17596 filesystems can fail for other reasons such as it being a later version
17597 of the filesystem, or having incompatible features.
17598 GUESTFISH supported COMMAND
17600 In guestfish(3) there is a handy interactive command "supported" which
17601 prints out the available groups and whether they are supported by this
17602 build of libguestfs. Note however that you have to do "run" first.
17603 SINGLE CALLS AT COMPILE TIME
17605 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17606 function, such as:
17607 #define GUESTFS_HAVE_DD 1
17609 if "guestfs_dd" is available.
17611 Before version 1.5.8, if you needed to test whether a single libguestfs
17613 function is available at compile time, we recommended using build tools
17614 such as autoconf or cmake. For example in autotools you could use:
17615 AC_CHECK_LIB([guestfs],[guestfs_create])
17617 AC_CHECK_FUNCS([guestfs_dd])
17618 which would result in "HAVE_GUESTFS_DD" being either defined or not
17620 defined in your program.
17621 SINGLE CALLS AT RUN TIME
17623 Testing at compile time doesn't guarantee that a function really exists
17624 in the library. The reason is that you might be dynamically linked
17625 against a previous libguestfs.so (dynamic library) which doesn't have
17626 the call. This situation unfortunately results in a segmentation
17627 fault, which is a shortcoming of the C dynamic linking system itself.
17628 You can use dlopen(3) to test if a function is available at run time,
17630 as in this example program (note that you still need the compile time
17631 check as well):
17632 #include <stdio.h>
17634 #include <stdlib.h>
17635 #include <unistd.h>
17636 #include <dlfcn.h>
17637 #include <guestfs.h>
17638 main ()
17640 {
17641 #ifdef GUESTFS_HAVE_DD
17642 void *dl;
17643 int has_function;
17644 /* Test if the function guestfs_dd is really available. */
17646 dl = dlopen (NULL, RTLD_LAZY);
17647 if (!dl) {
17648 fprintf (stderr, "dlopen: %s\n", dlerror ());
17649 exit (EXIT_FAILURE);
17650 }
17651 has_function = dlsym (dl, "guestfs_dd") != NULL;
17652 dlclose (dl);
17653 if (!has_function)
17655 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17656 else {
17657 printf ("this libguestfs.so has guestfs_dd function\n");
17658 /* Now it's safe to call
17659 guestfs_dd (g, "foo", "bar");
17660 */
17661 }
17662 #else
17663 printf ("guestfs_dd function was not found at compile time\n");
17664 #endif
17665 }
17666 You may think the above is an awful lot of hassle, and it is. There
17668 are other ways outside of the C linking system to ensure that this kind
17669 of incompatibility never arises, such as using package versioning:
17670 Requires: libguestfs >= 1.0.80
17672
17674 A recent feature of the API is the introduction of calls which take
17675 optional arguments. In C these are declared 3 ways. The main way is
17676 as a call which takes variable arguments (ie. "..."), as in this
17677 example:
17678 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17680 Call this with a list of optional arguments, terminated by -1. So to
17682 call with no optional arguments specified:
17683 guestfs_add_drive_opts (g, filename, -1);
17685 With a single optional argument:
17687 guestfs_add_drive_opts (g, filename,
17689 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17690 -1);
17691 With two:
17693 guestfs_add_drive_opts (g, filename,
17695 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17696 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17697 -1);
17698 and so forth. Don’t forget the terminating -1 otherwise Bad Things
17700 will happen!
17701 USING va_list FOR OPTIONAL ARGUMENTS
17703 The second variant has the same name with the suffix "_va", which works
17704 the same way but takes a "va_list". See the C manual for details. For
17705 the example function, this is declared:
17706 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17708 va_list args);
17709 CONSTRUCTING OPTIONAL ARGUMENTS
17711 The third variant is useful where you need to construct these calls.
17712 You pass in a structure where you fill in the optional fields. The
17713 structure has a bitmask as the first element which you must set to
17714 indicate which fields you have filled in. For our example function the
17715 structure and call are declared:
17716 struct guestfs_add_drive_opts_argv {
17718 uint64_t bitmask;
17719 int readonly;
17720 const char *format;
17721 /* ... */
17722 };
17723 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17724 const struct guestfs_add_drive_opts_argv *optargs);
17725 You could call it like this:
17727 struct guestfs_add_drive_opts_argv optargs = {
17729 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17730 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17731 .readonly = 1,
17732 .format = "qcow2"
17733 };
17734 guestfs_add_drive_opts_argv (g, filename, &optargs);
17736 Notes:
17738 • The "_BITMASK" suffix on each option name when specifying the
17740 bitmask.
17741 • You do not need to fill in all fields of the structure.
17743 • There must be a one-to-one correspondence between fields of the
17745 structure that are filled in, and bits set in the bitmask.
17746 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17748 In other languages, optional arguments are expressed in the way that is
17749 natural for that language. We refer you to the language-specific
17750 documentation for more details on that.
17751 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17753
17755 SETTING CALLBACKS TO HANDLE EVENTS
17756 Note: This section documents the generic event mechanism introduced in
17757 libguestfs 1.10, which you should use in new code if possible. The old
17758 functions "guestfs_set_log_message_callback",
17759 "guestfs_set_subprocess_quit_callback",
17760 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17761 "guestfs_set_progress_callback" are no longer documented in this manual
17762 page. Because of the ABI guarantee, the old functions continue to
17763 work.
17764 Handles generate events when certain things happen, such as log
17766 messages being generated, progress messages during long-running
17767 operations, or the handle being closed. The API calls described below
17768 let you register a callback to be called when events happen. You can
17769 register multiple callbacks (for the same, different or overlapping
17770 sets of events), and individually remove callbacks. If callbacks are
17771 not removed, then they remain in force until the handle is closed.
17772 In the current implementation, events are only generated synchronously:
17774 that means that events (and hence callbacks) can only happen while you
17775 are in the middle of making another libguestfs call. The callback is
17776 called in the same thread.
17777 Events may contain a payload, usually nothing (void), an array of 64
17779 bit unsigned integers, or a message buffer. Payloads are discussed
17780 later on.
17781 CLASSES OF EVENTS
17783 GUESTFS_EVENT_CLOSE (payload type: void)
17784 The callback function will be called while the handle is being
17785 closed (synchronously from "guestfs_close").
17786 Note that libguestfs installs an atexit(3) handler to try to clean
17788 up handles that are open when the program exits. This means that
17789 this callback might be called indirectly from exit(3), which can
17790 cause unexpected problems in higher-level languages (eg. if your
17791 HLL interpreter has already been cleaned up by the time this is
17792 called, and if your callback then jumps into some HLL function).
17793 If no callback is registered: the handle is closed without any
17795 callback being invoked.
17796 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17798 The callback function will be called when the child process quits,
17799 either asynchronously or if killed by "guestfs_kill_subprocess".
17800 (This corresponds to a transition from any state to the CONFIG
17801 state).
17802 If no callback is registered: the event is ignored.
17804 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17806 The callback function will be called when the child process becomes
17807 ready first time after it has been launched. (This corresponds to
17808 a transition from LAUNCHING to the READY state).
17809 If no callback is registered: the event is ignored.
17811 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17813 Some long-running operations can generate progress messages. If
17814 this callback is registered, then it will be called each time a
17815 progress message is generated (usually two seconds after the
17816 operation started, and three times per second thereafter until it
17817 completes, although the frequency may change in future versions).
17818 The callback receives in the payload four unsigned 64 bit numbers
17820 which are (in order): "proc_nr", "serial", "position", "total".
17821 The units of "total" are not defined, although for some operations
17823 "total" may relate in some way to the amount of data to be
17824 transferred (eg. in bytes or megabytes), and "position" may be the
17825 portion which has been transferred.
17826 The only defined and stable parts of the API are:
17828 • The callback can display to the user some type of progress bar
17830 or indicator which shows the ratio of "position":"total".
17831 • 0 <= "position" <= "total"
17833 • If any progress notification is sent during a call, then a
17835 final progress notification is always sent when "position" =
17836 "total" (unless the call fails with an error).
17837 This is to simplify caller code, so callers can easily set the
17839 progress indicator to "100%" at the end of the operation,
17840 without requiring special code to detect this case.
17841 • For some calls we are unable to estimate the progress of the
17843 call, but we can still generate progress messages to indicate
17844 activity. This is known as "pulse mode", and is directly
17845 supported by certain progress bar implementations (eg.
17846 GtkProgressBar).
17847 For these calls, zero or more progress messages are generated
17849 with "position = 0" and "total = 1", followed by a final
17850 message with "position = total = 1".
17851 As noted above, if the call fails with an error then the final
17853 message may not be generated.
17854 The callback also receives the procedure number ("proc_nr") and
17856 serial number ("serial") of the call. These are only useful for
17857 debugging protocol issues, and the callback can normally ignore
17858 them. The callback may want to print these numbers in error
17859 messages or debugging messages.
17860 If no callback is registered: progress messages are discarded.
17862 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17864 The callback function is called whenever a log message is generated
17865 by qemu, the appliance kernel, guestfsd (daemon), or utility
17866 programs.
17867 If the verbose flag ("guestfs_set_verbose") is set before launch
17869 ("guestfs_launch") then additional debug messages are generated.
17870 If no callback is registered: the messages are discarded unless the
17872 verbose flag is set in which case they are sent to stderr. You can
17873 override the printing of verbose messages to stderr by setting up a
17874 callback.
17875 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17877 The callback function is called whenever a log message is generated
17878 by the library part of libguestfs.
17879 If the verbose flag ("guestfs_set_verbose") is set then additional
17881 debug messages are generated.
17882 If no callback is registered: the messages are discarded unless the
17884 verbose flag is set in which case they are sent to stderr. You can
17885 override the printing of verbose messages to stderr by setting up a
17886 callback.
17887 GUESTFS_EVENT_WARNING (payload type: message buffer)
17889 The callback function is called whenever a warning message is
17890 generated by the library part of libguestfs.
17891 If no callback is registered: the messages are printed to stderr.
17893 You can override the printing of warning messages to stderr by
17894 setting up a callback.
17895 GUESTFS_EVENT_TRACE (payload type: message buffer)
17897 The callback function is called whenever a trace message is
17898 generated. This only applies if the trace flag
17899 ("guestfs_set_trace") is set.
17900 If no callback is registered: the messages are sent to stderr. You
17902 can override the printing of trace messages to stderr by setting up
17903 a callback.
17904 GUESTFS_EVENT_ENTER (payload type: function name)
17906 The callback function is called whenever a libguestfs function is
17907 entered.
17908 The payload is a string which contains the name of the function
17910 that we are entering (not including "guestfs_" prefix).
17911 Note that libguestfs functions can call themselves, so you may see
17913 many events from a single call. A few libguestfs functions do not
17914 generate this event.
17915 If no callback is registered: the event is ignored.
17917 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17919 For any API function that opens a libvirt connection, this event
17920 may be generated to indicate that libvirt demands authentication
17921 information. See "LIBVIRT AUTHENTICATION" below.
17922 If no callback is registered: "virConnectAuthPtrDefault" is used
17924 (suitable for command-line programs only).
17925 EVENT API
17927 guestfs_set_event_callback
17928 int guestfs_set_event_callback (guestfs_h *g,
17930 guestfs_event_callback cb,
17931 uint64_t event_bitmask,
17932 int flags,
17933 void *opaque);
17934 This function registers a callback ("cb") for all event classes in the
17936 "event_bitmask".
17937 For example, to register for all log message events, you could call
17939 this function with the bitmask
17940 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17941 To register a single callback for all possible classes of events, use
17942 "GUESTFS_EVENT_ALL".
17943 "flags" should always be passed as 0.
17945 "opaque" is an opaque pointer which is passed to the callback. You can
17947 use it for any purpose.
17948 The return value is the event handle (an integer) which you can use to
17950 delete the callback (see below).
17951 If there is an error, this function returns -1, and sets the error in
17953 the handle in the usual way (see "guestfs_last_error" etc.)
17954 Callbacks remain in effect until they are deleted, or until the handle
17956 is closed.
17957 In the case where multiple callbacks are registered for a particular
17959 event class, all of the callbacks are called. The order in which
17960 multiple callbacks are called is not defined.
17961 guestfs_delete_event_callback
17963 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
17965 Delete a callback that was previously registered. "event_handle"
17967 should be the integer that was returned by a previous call to
17968 "guestfs_set_event_callback" on the same handle.
17969 guestfs_event_to_string
17971 char *guestfs_event_to_string (uint64_t event);
17973 "event" is either a single event or a bitmask of events. This returns
17975 a string representation (useful for debugging or printing events).
17976 A single event is returned as the name in lower case, eg. "close".
17978 A bitmask of several events is returned as a comma-separated list, eg.
17980 "close,progress".
17981 If zero is passed, then the empty string "" is returned.
17983 On success this returns a string. On error it returns NULL and sets
17985 "errno".
17986 The returned string must be freed by the caller.
17988 guestfs_event_callback
17990 typedef void (*guestfs_event_callback) (
17992 guestfs_h *g,
17993 void *opaque,
17994 uint64_t event,
17995 int event_handle,
17996 int flags,
17997 const char *buf, size_t buf_len,
17998 const uint64_t *array, size_t array_len);
17999 This is the type of the event callback function that you have to
18001 provide.
18002 The basic parameters are: the handle ("g"), the opaque user pointer
18004 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
18005 handle, and "flags" which in the current API you should ignore.
18006 The remaining parameters contain the event payload (if any). Each
18008 event may contain a payload, which usually relates to the event class,
18009 but for future proofing your code should be written to handle any
18010 payload for any event class.
18011 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
18013 there is no message buffer). Note that this message buffer can contain
18014 arbitrary 8 bit data, including NUL bytes.
18015 "array" and "array_len" is an array of 64 bit unsigned integers. At
18017 the moment this is only used for progress messages.
18018 EXAMPLE: CAPTURING LOG MESSAGES
18020 A working program demonstrating this can be found in
18021 examples/debug-logging.c in the source of libguestfs.
18022 One motivation for the generic event API was to allow GUI programs to
18024 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
18025 unconditionally to "stderr".
18026 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
18028 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
18029 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
18030 must capture error messages separately).
18031 Programs have to set up a callback to capture the classes of events of
18033 interest:
18034 int eh =
18036 guestfs_set_event_callback
18037 (g, message_callback,
18038 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
18039 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
18040 0, NULL) == -1)
18041 if (eh == -1) {
18042 // handle error in the usual way
18043 }
18044 The callback can then direct messages to the appropriate place. In
18046 this example, messages are directed to syslog:
18047 static void
18049 message_callback (
18050 guestfs_h *g,
18051 void *opaque,
18052 uint64_t event,
18053 int event_handle,
18054 int flags,
18055 const char *buf, size_t buf_len,
18056 const uint64_t *array, size_t array_len)
18057 {
18058 const int priority = LOG_USER|LOG_INFO;
18059 if (buf_len > 0)
18060 syslog (priority, "event 0x%lx: %s", event, buf);
18061 }
18062 LIBVIRT AUTHENTICATION
18064 Some libguestfs API calls can open libvirt connections. Currently the
18065 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
18066 backend has been selected. Libvirt connections may require
18067 authentication, for example if they need to access a remote server or
18068 to access root services from non-root. Libvirt authentication happens
18069 via a callback mechanism, see
18070 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
18071 You may provide libvirt authentication data by registering a callback
18073 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
18074 If no such event is registered, then libguestfs uses a libvirt function
18076 that provides command-line prompts ("virConnectAuthPtrDefault"). This
18077 is only suitable for command-line libguestfs programs.
18078 To provide authentication, first call
18080 "guestfs_set_libvirt_supported_credentials" with the list of
18081 credentials your program knows how to provide. Second, register a
18082 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
18083 will be called when libvirt is requesting authentication information.
18084 In the event handler, call "guestfs_get_libvirt_requested_credentials"
18086 to get a list of the credentials that libvirt is asking for. You then
18087 need to ask (eg. the user) for each credential, and call
18088 "guestfs_set_libvirt_requested_credential" with the answer. Note that
18089 for each credential, additional information may be available via the
18090 calls "guestfs_get_libvirt_requested_credential_prompt",
18091 "guestfs_get_libvirt_requested_credential_challenge" or
18092 "guestfs_get_libvirt_requested_credential_defresult".
18093 The example program below should make this clearer.
18095 There is also a more substantial working example program supplied with
18097 the libguestfs sources, called libvirt-auth.c.
18098 main ()
18100 {
18101 guestfs_h *g;
18102 char *creds[] = { "authname", "passphrase", NULL };
18103 int r, eh;
18104 g = guestfs_create ();
18106 if (!g) exit (EXIT_FAILURE);
18107 /* Tell libvirt what credentials the program supports. */
18109 r = guestfs_set_libvirt_supported_credentials (g, creds);
18110 if (r == -1)
18111 exit (EXIT_FAILURE);
18112 /* Set up the event handler. */
18114 eh = guestfs_set_event_callback (
18115 g, do_auth,
18116 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
18117 if (eh == -1)
18118 exit (EXIT_FAILURE);
18119 /* An example of a call that may ask for credentials. */
18121 r = guestfs_add_domain (
18122 g, "dom",
18123 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
18124 -1);
18125 if (r == -1)
18126 exit (EXIT_FAILURE);
18127 exit (EXIT_SUCCESS);
18129 }
18130 static void
18132 do_auth (guestfs_h *g,
18133 void *opaque,
18134 uint64_t event,
18135 int event_handle,
18136 int flags,
18137 const char *buf, size_t buf_len,
18138 const uint64_t *array, size_t array_len)
18139 {
18140 char **creds;
18141 size_t i;
18142 char *prompt;
18143 char *reply;
18144 size_t replylen;
18145 int r;
18146 // buf will be the libvirt URI. buf_len may be ignored.
18148 printf ("Authentication required for libvirt conn '%s'\n",
18149 buf);
18150 // Ask libguestfs what credentials libvirt is demanding.
18152 creds = guestfs_get_libvirt_requested_credentials (g);
18153 if (creds == NULL)
18154 exit (EXIT_FAILURE);
18155 // Now ask the user for answers.
18157 for (i = 0; creds[i] != NULL; ++i)
18158 {
18159 if (strcmp (creds[i], "authname") == 0 ||
18160 strcmp (creds[i], "passphrase") == 0)
18161 {
18162 prompt =
18163 guestfs_get_libvirt_requested_credential_prompt (g, i);
18164 if (prompt && strcmp (prompt, "") != 0)
18165 printf ("%s: ", prompt);
18166 free (prompt);
18167 // Some code here to ask for the credential.
18169 // ...
18170 // Put the reply in 'reply', length 'replylen' (bytes).
18171 r = guestfs_set_libvirt_requested_credential (g, i,
18173 reply, replylen);
18174 if (r == -1)
18175 exit (EXIT_FAILURE);
18176 }
18177 free (creds[i]);
18179 }
18180 free (creds);
18182 }
18183
18185 Some operations can be cancelled by the caller while they are in
18186 progress. Currently only operations that involve uploading or
18187 downloading data can be cancelled (technically: operations that have
18188 "FileIn" or "FileOut" parameters in the generator).
18189 To cancel the transfer, call "guestfs_user_cancel". For more
18191 information, read the description of "guestfs_user_cancel".
18192
18194 You can attach named pieces of private data to the libguestfs handle,
18195 fetch them by name, and walk over them, for the lifetime of the handle.
18196 This is called the private data area and is only available from the C
18197 API.
18198 To attach a named piece of data, use the following call:
18200 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18202 "key" is the name to associate with this data, and "data" is an
18204 arbitrary pointer (which can be "NULL"). Any previous item with the
18205 same key is overwritten.
18206 You can use any "key" string you want, but avoid keys beginning with an
18208 underscore character (libguestfs uses those for its own internal
18209 purposes, such as implementing language bindings). It is recommended
18210 that you prefix the key with some unique string to avoid collisions
18211 with other users.
18212 To retrieve the pointer, use:
18214 void *guestfs_get_private (guestfs_h *g, const char *key);
18216 This function returns "NULL" if either no data is found associated with
18218 "key", or if the user previously set the "key"’s "data" pointer to
18219 "NULL".
18220 Libguestfs does not try to look at or interpret the "data" pointer in
18222 any way. As far as libguestfs is concerned, it need not be a valid
18223 pointer at all. In particular, libguestfs does not try to free the
18224 data when the handle is closed. If the data must be freed, then the
18225 caller must either free it before calling "guestfs_close" or must set
18226 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18227 To walk over all entries, use these two functions:
18229 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18231 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18233 "guestfs_first_private" returns the first key, pointer pair ("first"
18235 does not have any particular meaning -- keys are not returned in any
18236 defined order). A pointer to the key is returned in *key_rtn and the
18237 corresponding data pointer is returned from the function. "NULL" is
18238 returned if there are no keys stored in the handle.
18239 "guestfs_next_private" returns the next key, pointer pair. The return
18241 value of this function is "NULL" if there are no further entries to
18242 return.
18243 Notes about walking over entries:
18245 • You must not call "guestfs_set_private" while walking over the
18247 entries.
18248 • The handle maintains an internal iterator which is reset when you
18250 call "guestfs_first_private". This internal iterator is
18251 invalidated when you call "guestfs_set_private".
18252 • If you have set the data pointer associated with a key to "NULL",
18254 ie:
18255 guestfs_set_private (g, key, NULL);
18257 then that "key" is not returned when walking.
18259 • *key_rtn is only valid until the next call to
18261 "guestfs_first_private", "guestfs_next_private" or
18262 "guestfs_set_private".
18263 The following example code shows how to print all keys and data
18265 pointers that are associated with the handle "g":
18266 const char *key;
18268 void *data = guestfs_first_private (g, &key);
18269 while (data != NULL)
18270 {
18271 printf ("key = %s, data = %p\n", key, data);
18272 data = guestfs_next_private (g, &key);
18273 }
18274 More commonly you are only interested in keys that begin with an
18276 application-specific prefix "foo_". Modify the loop like so:
18277 const char *key;
18279 void *data = guestfs_first_private (g, &key);
18280 while (data != NULL)
18281 {
18282 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18283 printf ("key = %s, data = %p\n", key, data);
18284 data = guestfs_next_private (g, &key);
18285 }
18286 If you need to modify keys while walking, then you have to jump back to
18288 the beginning of the loop. For example, to delete all keys prefixed
18289 with "foo_":
18290 const char *key;
18292 void *data;
18293 again:
18294 data = guestfs_first_private (g, &key);
18295 while (data != NULL)
18296 {
18297 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18298 {
18299 guestfs_set_private (g, key, NULL);
18300 /* note that 'key' pointer is now invalid, and so is
18301 the internal iterator */
18302 goto again;
18303 }
18304 data = guestfs_next_private (g, &key);
18305 }
18306 Note that the above loop is guaranteed to terminate because the keys
18308 are being deleted, but other manipulations of keys within the loop
18309 might not terminate unless you also maintain an indication of which
18310 keys have been visited.
18311
18313 Since April 2010, libguestfs has started to make separate development
18314 and stable releases, along with corresponding branches in our git
18315 repository. These separate releases can be identified by version
18316 number:
18317 even numbers for stable: 1.2.x, 1.4.x, ...
18319 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18320 |
18321 v
18322 1 . 3 . 5
18323 ^ ^
18324 | |
18325 | `-------- sub-version
18326 |
18327 `------ always '1' because we don't change the ABI
18328 Thus "1.3.5" is the 5th update to the development branch "1.3".
18330 As time passes we cherry pick fixes from the development branch and
18332 backport those into the stable branch, the effect being that the stable
18333 branch should get more stable and less buggy over time. So the stable
18334 releases are ideal for people who don't need new features but would
18335 just like the software to work.
18336 Our criteria for backporting changes are:
18338 • Documentation changes which don’t affect any code are backported
18340 unless the documentation refers to a future feature which is not in
18341 stable.
18342 • Bug fixes which are not controversial, fix obvious problems, and
18344 have been well tested are backported.
18345 • Simple rearrangements of code which shouldn't affect how it works
18347 get backported. This is so that the code in the two branches
18348 doesn't get too far out of step, allowing us to backport future
18349 fixes more easily.
18350 • We don’t backport new features, new APIs, new tools etc, except in
18352 one exceptional case: the new feature is required in order to
18353 implement an important bug fix.
18354 A new stable branch starts when we think the new features in
18356 development are substantial and compelling enough over the current
18357 stable branch to warrant it. When that happens we create new stable
18358 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18359 oh release won't necessarily be so stable at this point, but by
18360 backporting fixes from development, that branch will stabilize over
18361 time.
18362
18364 PROTOCOL LIMITS
18365 Internally libguestfs uses a message-based protocol to pass API calls
18366 and their responses to and from a small "appliance" (see
18367 guestfs-internals(1) for plenty more detail about this). The maximum
18368 message size used by the protocol is slightly less than 4 MB. For some
18369 API calls you may need to be aware of this limit. The API calls which
18370 may be affected are individually documented, with a link back to this
18371 section of the documentation.
18372 In libguestfs < 1.19.32, several calls had to encode either their
18374 entire argument list or their entire return value (or sometimes both)
18375 in a single protocol message, and this gave them an arbitrary
18376 limitation on how much data they could handle. For example,
18377 "guestfs_cat" could only download a file if it was less than around 4
18378 MB in size. In later versions of libguestfs, some of these limits have
18379 been removed. The APIs which were previously limited but are now
18380 unlimited (except perhaps by available memory) are listed below. To
18381 find out if a specific API is subject to protocol limits, check for the
18382 warning in the API documentation which links to this section, and
18383 remember to check the version of the documentation that matches the
18384 version of libguestfs you are using.
18385 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18387 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18388 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18389 "guestfs_ls".
18390 See also "UPLOADING" and "DOWNLOADING" for further information about
18392 copying large amounts of data into or out of a filesystem.
18393 MAXIMUM NUMBER OF DISKS
18395 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18396 may be added by calling "guestfs_max_disks". In earlier versions of
18397 libguestfs (ie. where this call is not available) you should assume the
18398 maximum is 25.
18399 The rest of this section covers implementation details, which could
18401 change in future.
18402 When using virtio-scsi disks (the default if available in qemu) the
18404 current limit is 255 disks. When using virtio-blk (the old default)
18405 the limit is around 27 disks, but may vary according to implementation
18406 details and whether the network is enabled.
18407 Virtio-scsi as used by libguestfs is configured to use one target per
18409 disk, and 256 targets are available.
18410 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18412 31 slots, but some of these are used for other purposes.
18413 One virtual disk is used by libguestfs internally.
18415 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18417 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18418 the limit was 25. This has been fixed in more recent versions.
18419 MAXIMUM NUMBER OF PARTITIONS PER DISK
18421 Virtio limits the maximum number of partitions per disk to 15.
18422 This is because it reserves 4 bits for the minor device number (thus
18424 /dev/vda, and /dev/vda1 through /dev/vda15).
18425 If you attach a disk with more than 15 partitions, the extra partitions
18427 are ignored by libguestfs.
18428 MAXIMUM SIZE OF A DISK
18430 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18431 We have tested block devices up to 1 exabyte (2**60 or
18433 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18434 host filesystem.
18435 Although libguestfs probably does not impose any limit, the underlying
18437 host storage will. If you store disk images on a host ext4 filesystem,
18438 then the maximum size will be limited by the maximum ext4 file size
18439 (currently 16 TB). If you store disk images as host logical volumes
18440 then you are limited by the maximum size of an LV.
18441 For the hugest disk image files, we recommend using XFS on the host for
18443 storage.
18444 MAXIMUM SIZE OF A PARTITION
18446 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18447 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18448 address a partition located beyond 2 TB on the disk.
18449 It is recommended that you use GPT partitions on disks which are larger
18451 than this size. GPT uses 64 bit sector numbers and so can address
18452 partitions which are theoretically larger than the largest disk we
18453 could support.
18454 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18456 This depends on the filesystem type. libguestfs itself does not impose
18457 any known limit. Consult Wikipedia or the filesystem documentation to
18458 find out what these limits are.
18459 MAXIMUM UPLOAD AND DOWNLOAD
18461 The API functions "guestfs_upload", "guestfs_download",
18462 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18463 uploads and downloads.
18464 INSPECTION LIMITS
18466 The inspection code has several arbitrary limits on things like the
18467 size of Windows Registry hive it will read, and the length of product
18468 name. These are intended to stop a malicious guest from consuming
18469 arbitrary amounts of memory and disk space on the host, and should not
18470 be reached in practice. See the source code for more information.
18471
18473 Some of the tools support a --machine-readable option, which is
18474 generally used to make the output more machine friendly, for easier
18475 parsing for example. By default, this output goes to stdout.
18476 When using the --machine-readable option, the progress, information,
18478 warning, and error messages are also printed in JSON format for easier
18479 log tracking. Thus, it is highly recommended to redirect the machine-
18480 readable output to a different stream. The format of these JSON
18481 messages is like the following (actually printed within a single line,
18482 below it is indented for readability):
18483 {
18485 "message": "Finishing off",
18486 "timestamp": "2019-03-22T14:46:49.067294446+01:00",
18487 "type": "message"
18488 }
18489 "type" can be: "message" for progress messages, "info" for information
18491 messages, "warning" for warning messages, and "error" for error
18492 message. "timestamp" is the RFC 3339 timestamp of the message.
18493 In addition to that, a subset of these tools support an extra string
18495 passed to the --machine-readable option: this string specifies where
18496 the machine-readable output will go.
18497 The possible values are:
18499 fd:fd
18501 The output goes to the specified fd, which is a file descriptor
18502 already opened for writing.
18503 file:filename
18505 The output goes to the specified filename.
18506 stream:stdout
18508 The output goes to stdout. This is basically the same as the
18509 default behaviour of --machine-readable with no parameter, although
18510 stdout as output is specified explicitly.
18511 stream:stderr
18513 The output goes to stderr.
18514
18516 LIBGUESTFS_APPEND
18517 Pass additional options to the guest kernel.
18518 LIBGUESTFS_ATTACH_METHOD
18520 This is the old way to set "LIBGUESTFS_BACKEND".
18521 LIBGUESTFS_BACKEND
18523 Choose the default way to create the appliance. See
18524 "guestfs_set_backend" and "BACKEND".
18525 LIBGUESTFS_BACKEND_SETTINGS
18527 A colon-separated list of backend-specific settings. See
18528 "BACKEND", "BACKEND SETTINGS".
18529 LIBGUESTFS_CACHEDIR
18531 The location where libguestfs will cache its appliance, when using
18532 a supermin appliance. The appliance is cached and shared between
18533 all handles which have the same effective user ID.
18534 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18536 "TMPDIR" is not set, then /var/tmp is used.
18537 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18539 LIBGUESTFS_DEBUG
18541 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18542 same effect as calling "guestfs_set_verbose (g, 1)".
18543 LIBGUESTFS_HV
18545 Set the default hypervisor (usually qemu) binary that libguestfs
18546 uses. If not set, then the qemu which was found at compile time by
18547 the configure script is used.
18548 See also "QEMU WRAPPERS" above.
18550 LIBGUESTFS_MEMSIZE
18552 Set the memory allocated to the qemu process, in megabytes. For
18553 example:
18554 LIBGUESTFS_MEMSIZE=700
18556 LIBGUESTFS_PATH
18558 Set the path that libguestfs uses to search for a supermin
18559 appliance. See the discussion of paths in section "PATH" above.
18560 LIBGUESTFS_QEMU
18562 This is the old way to set "LIBGUESTFS_HV".
18563 LIBGUESTFS_TMPDIR
18565 The location where libguestfs will store temporary files used by
18566 each handle.
18567 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18569 "TMPDIR" is not set, then /tmp is used.
18570 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18572 LIBGUESTFS_TRACE
18574 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18575 same effect as calling "guestfs_set_trace (g, 1)".
18576 PATH
18578 Libguestfs may run some external programs, and relies on $PATH
18579 being set to a reasonable value. If using the libvirt backend,
18580 libvirt will not work at all unless $PATH contains the path of
18581 qemu/KVM. Note that PHP by default removes $PATH from the
18582 environment which tends to break everything.
18583 SUPERMIN_KERNEL
18585 SUPERMIN_KERNEL_VERSION
18586 SUPERMIN_MODULES
18587 These three environment variables allow the kernel that libguestfs
18588 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18589 set, then the most recent host kernel is chosen. For more
18590 information about kernel selection, see supermin(1).
18591 TMPDIR
18593 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18594 XDG_RUNTIME_DIR
18596 This directory represents a user-specific directory for storing
18597 non-essential runtime files.
18598 If it is set, then is used to store temporary sockets. Otherwise,
18600 /tmp is used.
18601 See also "get-sockdir",
18603 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18604
18606 Examples written in C: guestfs-examples(3).
18607 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18609 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18610 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18611 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18613 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18614 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18615 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18616 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18617 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18618 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18619 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18620 virt-win-reg(1).
18621 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18623 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18624 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18625 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18626 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18628 sd-journal(3).
18629 Website: http://libguestfs.org/
18631 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18633 disktype(1).
18634
18636 Richard W.M. Jones ("rjones at redhat dot com")
18637
18639 Copyright (C) 2009-2023 Red Hat Inc.
18640
18642 This library is free software; you can redistribute it and/or modify it
18643 under the terms of the GNU Lesser General Public License as published
18644 by the Free Software Foundation; either version 2 of the License, or
18645 (at your option) any later version.
18646 This library is distributed in the hope that it will be useful, but
18648 WITHOUT ANY WARRANTY; without even the implied warranty of
18649 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18650 Lesser General Public License for more details.
18651 You should have received a copy of the GNU Lesser General Public
18653 License along with this library; if not, write to the Free Software
18654 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18655 02110-1301 USA
18656
18658 To get a list of bugs against libguestfs, use this link:
18659 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18660 To report a new bug against libguestfs, use this link:
18662 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18663 When reporting a bug, please supply:
18665 • The version of libguestfs.
18667 • Where you got libguestfs (eg. which Linux distro, compiled from
18669 source, etc)
18670 • Describe the bug accurately and give a way to reproduce it.
18672 • Run libguestfs-test-tool(1) and paste the complete, unedited output
18674 into the bug report.
18675libguestfs-1.50.1 2023-02-21 guestfs(3)