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 and PID
6758 files.
6759 This is different from "guestfs_get_tmpdir", as we need shorter paths
6761 for sockets (due to the limited buffers of filenames for UNIX sockets),
6762 and "guestfs_get_tmpdir" may be too long for them. Furthermore,
6763 sockets and PID files must be accessible to such background services
6764 started by libguestfs that may not have permission to access the
6765 temporary directory returned by "guestfs_get_tmpdir".
6766 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6768 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6769 the default.
6770 This function returns a string, or NULL on error. The caller must free
6772 the returned string after use.
6773 (Added in 1.33.8)
6775 guestfs_get_state
6777 int
6778 guestfs_get_state (guestfs_h *g);
6779 This returns the current state as an opaque integer. This is only
6781 useful for printing debug and internal error messages.
6782 For more information on states, see guestfs(3).
6784 On error this function returns -1.
6786 (Added in 1.0.2)
6788 guestfs_get_tmpdir
6790 char *
6791 guestfs_get_tmpdir (guestfs_h *g);
6792 Get the directory used by the handle to store temporary files.
6794 This function returns a string, or NULL on error. The caller must free
6796 the returned string after use.
6797 (Added in 1.19.58)
6799 guestfs_get_trace
6801 int
6802 guestfs_get_trace (guestfs_h *g);
6803 Return the command trace flag.
6805 This function returns a C truth value on success or -1 on error.
6807 (Added in 1.0.69)
6809 guestfs_get_umask
6811 int
6812 guestfs_get_umask (guestfs_h *g);
6813 Return the current umask. By default the umask is 022 unless it has
6815 been set by calling "guestfs_umask".
6816 On error this function returns -1.
6818 (Added in 1.3.4)
6820 guestfs_get_verbose
6822 int
6823 guestfs_get_verbose (guestfs_h *g);
6824 This returns the verbose messages flag.
6826 This function returns a C truth value on success or -1 on error.
6828 (Added in 0.3)
6830 guestfs_getcon
6832 char *
6833 guestfs_getcon (guestfs_h *g);
6834 This function is deprecated. In new code, use the
6836 "guestfs_selinux_relabel" call instead.
6837 Deprecated functions will not be removed from the API, but the fact
6839 that they are deprecated indicates that there are problems with correct
6840 use of these functions.
6841 This gets the SELinux security context of the daemon.
6843 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6845 This function returns a string, or NULL on error. The caller must free
6847 the returned string after use.
6848 This function depends on the feature "selinux". See also
6850 "guestfs_feature_available".
6851 (Added in 1.0.67)
6853 guestfs_getxattr
6855 char *
6856 guestfs_getxattr (guestfs_h *g,
6857 const char *path,
6858 const char *name,
6859 size_t *size_r);
6860 Get a single extended attribute from file "path" named "name". This
6862 call follows symlinks. If you want to lookup an extended attribute for
6863 the symlink itself, use "guestfs_lgetxattr".
6864 Normally it is better to get all extended attributes from a file in one
6866 go by calling "guestfs_getxattrs". However some Linux filesystem
6867 implementations are buggy and do not provide a way to list out
6868 attributes. For these filesystems (notably ntfs-3g) you have to know
6869 the names of the extended attributes you want in advance and call this
6870 function.
6871 Extended attribute values are blobs of binary data. If there is no
6873 extended attribute named "name", this returns an error.
6874 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6876 This function returns a buffer, or NULL on error. The size of the
6878 returned buffer is written to *size_r. The caller must free the
6879 returned buffer after use.
6880 This function depends on the feature "linuxxattrs". See also
6882 "guestfs_feature_available".
6883 (Added in 1.7.24)
6885 guestfs_getxattrs
6887 struct guestfs_xattr_list *
6888 guestfs_getxattrs (guestfs_h *g,
6889 const char *path);
6890 This call lists the extended attributes of the file or directory
6892 "path".
6893 At the system call level, this is a combination of the listxattr(2) and
6895 getxattr(2) calls.
6896 See also: "guestfs_lgetxattrs", attr(5).
6898 This function returns a "struct guestfs_xattr_list *", or NULL if there
6900 was an error. The caller must call "guestfs_free_xattr_list" after
6901 use.
6902 This function depends on the feature "linuxxattrs". See also
6904 "guestfs_feature_available".
6905 (Added in 1.0.59)
6907 guestfs_glob_expand
6909 char **
6910 guestfs_glob_expand (guestfs_h *g,
6911 const char *pattern);
6912 This function is provided for backwards compatibility with earlier
6914 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
6915 with no optional arguments.
6916 (Added in 1.0.50)
6918 guestfs_glob_expand_opts
6920 char **
6921 guestfs_glob_expand_opts (guestfs_h *g,
6922 const char *pattern,
6923 ...);
6924 You may supply a list of optional arguments to this call. Use zero or
6926 more of the following pairs of parameters, and terminate the list with
6927 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6928 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
6930 This command searches for all the pathnames matching "pattern"
6932 according to the wildcard expansion rules used by the shell.
6933 If no paths match, then this returns an empty list (note: not an
6935 error).
6936 It is just a wrapper around the C glob(3) function with flags
6938 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
6939 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
6941 and it defaults to true. It can be explicitly set as off to return no
6942 trailing slashes in filenames of directories.
6943 Notice that there is no equivalent command for expanding a device name
6945 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
6946 etc functions instead.
6947 This function returns a NULL-terminated array of strings (like
6949 environ(3)), or NULL if there was an error. The caller must free the
6950 strings and the array after use.
6951 (Added in 1.0.50)
6953 guestfs_glob_expand_opts_va
6955 char **
6956 guestfs_glob_expand_opts_va (guestfs_h *g,
6957 const char *pattern,
6958 va_list args);
6959 This is the "va_list variant" of "guestfs_glob_expand_opts".
6961 See "CALLS WITH OPTIONAL ARGUMENTS".
6963 guestfs_glob_expand_opts_argv
6965 char **
6966 guestfs_glob_expand_opts_argv (guestfs_h *g,
6967 const char *pattern,
6968 const struct guestfs_glob_expand_opts_argv *optargs);
6969 This is the "argv variant" of "guestfs_glob_expand_opts".
6971 See "CALLS WITH OPTIONAL ARGUMENTS".
6973 guestfs_grep
6975 char **
6976 guestfs_grep (guestfs_h *g,
6977 const char *regex,
6978 const char *path);
6979 This function is provided for backwards compatibility with earlier
6981 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
6982 optional arguments.
6983 (Added in 1.0.66)
6985 guestfs_grep_opts
6987 char **
6988 guestfs_grep_opts (guestfs_h *g,
6989 const char *regex,
6990 const char *path,
6991 ...);
6992 You may supply a list of optional arguments to this call. Use zero or
6994 more of the following pairs of parameters, and terminate the list with
6995 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6996 GUESTFS_GREP_OPTS_EXTENDED, int extended,
6998 GUESTFS_GREP_OPTS_FIXED, int fixed,
6999 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
7000 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
7001 This calls the external grep(1) program and returns the matching lines.
7003 The optional flags are:
7005 "extended"
7007 Use extended regular expressions. This is the same as using the -E
7008 flag.
7009 "fixed"
7011 Match fixed (don't use regular expressions). This is the same as
7012 using the -F flag.
7013 "insensitive"
7015 Match case-insensitive. This is the same as using the -i flag.
7016 "compressed"
7018 Use zgrep(1) instead of grep(1). This allows the input to be
7019 compress- or gzip-compressed.
7020 This function returns a NULL-terminated array of strings (like
7022 environ(3)), or NULL if there was an error. The caller must free the
7023 strings and the array after use.
7024 Because of the message protocol, there is a transfer limit of somewhere
7026 between 2MB and 4MB. See "PROTOCOL LIMITS".
7027 (Added in 1.0.66)
7029 guestfs_grep_opts_va
7031 char **
7032 guestfs_grep_opts_va (guestfs_h *g,
7033 const char *regex,
7034 const char *path,
7035 va_list args);
7036 This is the "va_list variant" of "guestfs_grep_opts".
7038 See "CALLS WITH OPTIONAL ARGUMENTS".
7040 guestfs_grep_opts_argv
7042 char **
7043 guestfs_grep_opts_argv (guestfs_h *g,
7044 const char *regex,
7045 const char *path,
7046 const struct guestfs_grep_opts_argv *optargs);
7047 This is the "argv variant" of "guestfs_grep_opts".
7049 See "CALLS WITH OPTIONAL ARGUMENTS".
7051 guestfs_grepi
7053 char **
7054 guestfs_grepi (guestfs_h *g,
7055 const char *regex,
7056 const char *path);
7057 This function is deprecated. In new code, use the "guestfs_grep" call
7059 instead.
7060 Deprecated functions will not be removed from the API, but the fact
7062 that they are deprecated indicates that there are problems with correct
7063 use of these functions.
7064 This calls the external "grep -i" program and returns the matching
7066 lines.
7067 This function returns a NULL-terminated array of strings (like
7069 environ(3)), or NULL if there was an error. The caller must free the
7070 strings and the array after use.
7071 Because of the message protocol, there is a transfer limit of somewhere
7073 between 2MB and 4MB. See "PROTOCOL LIMITS".
7074 (Added in 1.0.66)
7076 guestfs_grub_install
7078 int
7079 guestfs_grub_install (guestfs_h *g,
7080 const char *root,
7081 const char *device);
7082 This command installs GRUB 1 (the Grand Unified Bootloader) on
7084 "device", with the root directory being "root".
7085 Notes:
7087 • There is currently no way in the API to install grub2, which is
7089 used by most modern Linux guests. It is possible to run the grub2
7090 command from the guest, although see the caveats in "RUNNING
7091 COMMANDS".
7092 • This uses grub-install(8) from the host. Unfortunately grub is not
7094 always compatible with itself, so this only works in rather narrow
7095 circumstances. Careful testing with each guest version is
7096 advisable.
7097 • If grub-install reports the error "No suitable drive was found in
7099 the generated device map." it may be that you need to create a
7100 /boot/grub/device.map file first that contains the mapping between
7101 grub device names and Linux device names. It is usually sufficient
7102 to create a file containing:
7103 (hd0) /dev/vda
7105 replacing /dev/vda with the name of the installation device.
7107 This function returns 0 on success or -1 on error.
7109 This function depends on the feature "grub". See also
7111 "guestfs_feature_available".
7112 (Added in 1.0.17)
7114 guestfs_head
7116 char **
7117 guestfs_head (guestfs_h *g,
7118 const char *path);
7119 This command returns up to the first 10 lines of a file as a list of
7121 strings.
7122 This function returns a NULL-terminated array of strings (like
7124 environ(3)), or NULL if there was an error. The caller must free the
7125 strings and the array after use.
7126 Because of the message protocol, there is a transfer limit of somewhere
7128 between 2MB and 4MB. See "PROTOCOL LIMITS".
7129 (Added in 1.0.54)
7131 guestfs_head_n
7133 char **
7134 guestfs_head_n (guestfs_h *g,
7135 int nrlines,
7136 const char *path);
7137 If the parameter "nrlines" is a positive number, this returns the first
7139 "nrlines" lines of the file "path".
7140 If the parameter "nrlines" is a negative number, this returns lines
7142 from the file "path", excluding the last "nrlines" lines.
7143 If the parameter "nrlines" is zero, this returns an empty list.
7145 This function returns a NULL-terminated array of strings (like
7147 environ(3)), or NULL if there was an error. The caller must free the
7148 strings and the array after use.
7149 Because of the message protocol, there is a transfer limit of somewhere
7151 between 2MB and 4MB. See "PROTOCOL LIMITS".
7152 (Added in 1.0.54)
7154 guestfs_hexdump
7156 char *
7157 guestfs_hexdump (guestfs_h *g,
7158 const char *path);
7159 This runs "hexdump -C" on the given "path". The result is the human-
7161 readable, canonical hex dump of the file.
7162 This function returns a string, or NULL on error. The caller must free
7164 the returned string after use.
7165 Because of the message protocol, there is a transfer limit of somewhere
7167 between 2MB and 4MB. See "PROTOCOL LIMITS".
7168 (Added in 1.0.22)
7170 guestfs_hivex_close
7172 int
7173 guestfs_hivex_close (guestfs_h *g);
7174 Close the current hivex handle.
7176 This is a wrapper around the hivex(3) call of the same name.
7178 This function returns 0 on success or -1 on error.
7180 This function depends on the feature "hivex". See also
7182 "guestfs_feature_available".
7183 (Added in 1.19.35)
7185 guestfs_hivex_commit
7187 int
7188 guestfs_hivex_commit (guestfs_h *g,
7189 const char *filename);
7190 Commit (write) changes to the hive.
7192 If the optional filename parameter is null, then the changes are
7194 written back to the same hive that was opened. If this is not null
7195 then they are written to the alternate filename given and the original
7196 hive is left untouched.
7197 This is a wrapper around the hivex(3) call of the same name.
7199 This function returns 0 on success or -1 on error.
7201 This function depends on the feature "hivex". See also
7203 "guestfs_feature_available".
7204 (Added in 1.19.35)
7206 guestfs_hivex_node_add_child
7208 int64_t
7209 guestfs_hivex_node_add_child (guestfs_h *g,
7210 int64_t parent,
7211 const char *name);
7212 Add a child node to "parent" named "name".
7214 This is a wrapper around the hivex(3) call of the same name.
7216 On error this function returns -1.
7218 This function depends on the feature "hivex". See also
7220 "guestfs_feature_available".
7221 (Added in 1.19.35)
7223 guestfs_hivex_node_children
7225 struct guestfs_hivex_node_list *
7226 guestfs_hivex_node_children (guestfs_h *g,
7227 int64_t nodeh);
7228 Return the list of nodes which are subkeys of "nodeh".
7230 This is a wrapper around the hivex(3) call of the same name.
7232 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7234 there was an error. The caller must call
7235 "guestfs_free_hivex_node_list" after use.
7236 This function depends on the feature "hivex". See also
7238 "guestfs_feature_available".
7239 (Added in 1.19.35)
7241 guestfs_hivex_node_delete_child
7243 int
7244 guestfs_hivex_node_delete_child (guestfs_h *g,
7245 int64_t nodeh);
7246 Delete "nodeh", recursively if necessary.
7248 This is a wrapper around the hivex(3) call of the same name.
7250 This function returns 0 on success or -1 on error.
7252 This function depends on the feature "hivex". See also
7254 "guestfs_feature_available".
7255 (Added in 1.19.35)
7257 guestfs_hivex_node_get_child
7259 int64_t
7260 guestfs_hivex_node_get_child (guestfs_h *g,
7261 int64_t nodeh,
7262 const char *name);
7263 Return the child of "nodeh" with the name "name", if it exists. This
7265 can return 0 meaning the name was not found.
7266 This is a wrapper around the hivex(3) call of the same name.
7268 On error this function returns -1.
7270 This function depends on the feature "hivex". See also
7272 "guestfs_feature_available".
7273 (Added in 1.19.35)
7275 guestfs_hivex_node_get_value
7277 int64_t
7278 guestfs_hivex_node_get_value (guestfs_h *g,
7279 int64_t nodeh,
7280 const char *key);
7281 Return the value attached to "nodeh" which has the name "key", if it
7283 exists. This can return 0 meaning the key was not found.
7284 This is a wrapper around the hivex(3) call of the same name.
7286 On error this function returns -1.
7288 This function depends on the feature "hivex". See also
7290 "guestfs_feature_available".
7291 (Added in 1.19.35)
7293 guestfs_hivex_node_name
7295 char *
7296 guestfs_hivex_node_name (guestfs_h *g,
7297 int64_t nodeh);
7298 Return the name of "nodeh".
7300 This is a wrapper around the hivex(3) call of the same name.
7302 This function returns a string, or NULL on error. The caller must free
7304 the returned string after use.
7305 This function depends on the feature "hivex". See also
7307 "guestfs_feature_available".
7308 (Added in 1.19.35)
7310 guestfs_hivex_node_parent
7312 int64_t
7313 guestfs_hivex_node_parent (guestfs_h *g,
7314 int64_t nodeh);
7315 Return the parent node of "nodeh".
7317 This is a wrapper around the hivex(3) call of the same name.
7319 On error this function returns -1.
7321 This function depends on the feature "hivex". See also
7323 "guestfs_feature_available".
7324 (Added in 1.19.35)
7326 guestfs_hivex_node_set_value
7328 int
7329 guestfs_hivex_node_set_value (guestfs_h *g,
7330 int64_t nodeh,
7331 const char *key,
7332 int64_t t,
7333 const char *val,
7334 size_t val_size);
7335 Set or replace a single value under the node "nodeh". The "key" is the
7337 name, "t" is the type, and "val" is the data.
7338 This is a wrapper around the hivex(3) call of the same name.
7340 This function returns 0 on success or -1 on error.
7342 This function depends on the feature "hivex". See also
7344 "guestfs_feature_available".
7345 (Added in 1.19.35)
7347 guestfs_hivex_node_values
7349 struct guestfs_hivex_value_list *
7350 guestfs_hivex_node_values (guestfs_h *g,
7351 int64_t nodeh);
7352 Return the array of (key, datatype, data) tuples attached to "nodeh".
7354 This is a wrapper around the hivex(3) call of the same name.
7356 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7358 there was an error. The caller must call
7359 "guestfs_free_hivex_value_list" after use.
7360 This function depends on the feature "hivex". See also
7362 "guestfs_feature_available".
7363 (Added in 1.19.35)
7365 guestfs_hivex_open
7367 int
7368 guestfs_hivex_open (guestfs_h *g,
7369 const char *filename,
7370 ...);
7371 You may supply a list of optional arguments to this call. Use zero or
7373 more of the following pairs of parameters, and terminate the list with
7374 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7375 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7377 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7378 GUESTFS_HIVEX_OPEN_WRITE, int write,
7379 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7380 Open the Windows Registry hive file named filename. If there was any
7382 previous hivex handle associated with this guestfs session, then it is
7383 closed.
7384 This is a wrapper around the hivex(3) call of the same name.
7386 This function returns 0 on success or -1 on error.
7388 This function depends on the feature "hivex". See also
7390 "guestfs_feature_available".
7391 (Added in 1.19.35)
7393 guestfs_hivex_open_va
7395 int
7396 guestfs_hivex_open_va (guestfs_h *g,
7397 const char *filename,
7398 va_list args);
7399 This is the "va_list variant" of "guestfs_hivex_open".
7401 See "CALLS WITH OPTIONAL ARGUMENTS".
7403 guestfs_hivex_open_argv
7405 int
7406 guestfs_hivex_open_argv (guestfs_h *g,
7407 const char *filename,
7408 const struct guestfs_hivex_open_argv *optargs);
7409 This is the "argv variant" of "guestfs_hivex_open".
7411 See "CALLS WITH OPTIONAL ARGUMENTS".
7413 guestfs_hivex_root
7415 int64_t
7416 guestfs_hivex_root (guestfs_h *g);
7417 Return the root node of the hive.
7419 This is a wrapper around the hivex(3) call of the same name.
7421 On error this function returns -1.
7423 This function depends on the feature "hivex". See also
7425 "guestfs_feature_available".
7426 (Added in 1.19.35)
7428 guestfs_hivex_value_key
7430 char *
7431 guestfs_hivex_value_key (guestfs_h *g,
7432 int64_t valueh);
7433 Return the key (name) field of a (key, datatype, data) tuple.
7435 This is a wrapper around the hivex(3) call of the same name.
7437 This function returns a string, or NULL on error. The caller must free
7439 the returned string after use.
7440 This function depends on the feature "hivex". See also
7442 "guestfs_feature_available".
7443 (Added in 1.19.35)
7445 guestfs_hivex_value_string
7447 char *
7448 guestfs_hivex_value_string (guestfs_h *g,
7449 int64_t valueh);
7450 This calls "guestfs_hivex_value_value" (which returns the data field
7452 from a hivex value tuple). It then assumes that the field is a
7453 UTF-16LE string and converts the result to UTF-8 (or if this is not
7454 possible, it returns an error).
7455 This is useful for reading strings out of the Windows registry.
7457 However it is not foolproof because the registry is not strongly-typed
7458 and fields can contain arbitrary or unexpected data.
7459 This function returns a string, or NULL on error. The caller must free
7461 the returned string after use.
7462 This function depends on the feature "hivex". See also
7464 "guestfs_feature_available".
7465 (Added in 1.37.22)
7467 guestfs_hivex_value_type
7469 int64_t
7470 guestfs_hivex_value_type (guestfs_h *g,
7471 int64_t valueh);
7472 Return the data type field from a (key, datatype, data) tuple.
7474 This is a wrapper around the hivex(3) call of the same name.
7476 On error this function returns -1.
7478 This function depends on the feature "hivex". See also
7480 "guestfs_feature_available".
7481 (Added in 1.19.35)
7483 guestfs_hivex_value_utf8
7485 char *
7486 guestfs_hivex_value_utf8 (guestfs_h *g,
7487 int64_t valueh);
7488 This function is deprecated. In new code, use the
7490 "guestfs_hivex_value_string" call instead.
7491 Deprecated functions will not be removed from the API, but the fact
7493 that they are deprecated indicates that there are problems with correct
7494 use of these functions.
7495 This calls "guestfs_hivex_value_value" (which returns the data field
7497 from a hivex value tuple). It then assumes that the field is a
7498 UTF-16LE string and converts the result to UTF-8 (or if this is not
7499 possible, it returns an error).
7500 This is useful for reading strings out of the Windows registry.
7502 However it is not foolproof because the registry is not strongly-typed
7503 and fields can contain arbitrary or unexpected data.
7504 This function returns a string, or NULL on error. The caller must free
7506 the returned string after use.
7507 This function depends on the feature "hivex". See also
7509 "guestfs_feature_available".
7510 (Added in 1.19.35)
7512 guestfs_hivex_value_value
7514 char *
7515 guestfs_hivex_value_value (guestfs_h *g,
7516 int64_t valueh,
7517 size_t *size_r);
7518 Return the data field of a (key, datatype, data) tuple.
7520 This is a wrapper around the hivex(3) call of the same name.
7522 See also: "guestfs_hivex_value_utf8".
7524 This function returns a buffer, or NULL on error. The size of the
7526 returned buffer is written to *size_r. The caller must free the
7527 returned buffer after use.
7528 This function depends on the feature "hivex". See also
7530 "guestfs_feature_available".
7531 (Added in 1.19.35)
7533 guestfs_initrd_cat
7535 char *
7536 guestfs_initrd_cat (guestfs_h *g,
7537 const char *initrdpath,
7538 const char *filename,
7539 size_t *size_r);
7540 This command unpacks the file filename from the initrd file called
7542 initrdpath. The filename must be given without the initial /
7543 character.
7544 For example, in guestfish you could use the following command to
7546 examine the boot script (usually called /init) contained in a Linux
7547 initrd or initramfs image:
7548 initrd-cat /boot/initrd-<version>.img init
7550 See also "guestfs_initrd_list".
7552 This function returns a buffer, or NULL on error. The size of the
7554 returned buffer is written to *size_r. The caller must free the
7555 returned buffer after use.
7556 Because of the message protocol, there is a transfer limit of somewhere
7558 between 2MB and 4MB. See "PROTOCOL LIMITS".
7559 (Added in 1.0.84)
7561 guestfs_initrd_list
7563 char **
7564 guestfs_initrd_list (guestfs_h *g,
7565 const char *path);
7566 This command lists out files contained in an initrd.
7568 The files are listed without any initial / character. The files are
7570 listed in the order they appear (not necessarily alphabetical).
7571 Directory names are listed as separate items.
7572 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7574 as initrd. We only support the newer initramfs format (compressed cpio
7575 files).
7576 This function returns a NULL-terminated array of strings (like
7578 environ(3)), or NULL if there was an error. The caller must free the
7579 strings and the array after use.
7580 (Added in 1.0.54)
7582 guestfs_inotify_add_watch
7584 int64_t
7585 guestfs_inotify_add_watch (guestfs_h *g,
7586 const char *path,
7587 int mask);
7588 Watch "path" for the events listed in "mask".
7590 Note that if "path" is a directory then events within that directory
7592 are watched, but this does not happen recursively (in subdirectories).
7593 Note for non-C or non-Linux callers: the inotify events are defined by
7595 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7596 On error this function returns -1.
7598 This function depends on the feature "inotify". See also
7600 "guestfs_feature_available".
7601 (Added in 1.0.66)
7603 guestfs_inotify_close
7605 int
7606 guestfs_inotify_close (guestfs_h *g);
7607 This closes the inotify handle which was previously opened by
7609 inotify_init. It removes all watches, throws away any pending events,
7610 and deallocates all resources.
7611 This function returns 0 on success or -1 on error.
7613 This function depends on the feature "inotify". See also
7615 "guestfs_feature_available".
7616 (Added in 1.0.66)
7618 guestfs_inotify_files
7620 char **
7621 guestfs_inotify_files (guestfs_h *g);
7622 This function is a helpful wrapper around "guestfs_inotify_read" which
7624 just returns a list of pathnames of objects that were touched. The
7625 returned pathnames are sorted and deduplicated.
7626 This function returns a NULL-terminated array of strings (like
7628 environ(3)), or NULL if there was an error. The caller must free the
7629 strings and the array after use.
7630 This function depends on the feature "inotify". See also
7632 "guestfs_feature_available".
7633 (Added in 1.0.66)
7635 guestfs_inotify_init
7637 int
7638 guestfs_inotify_init (guestfs_h *g,
7639 int maxevents);
7640 This command creates a new inotify handle. The inotify subsystem can
7642 be used to notify events which happen to objects in the guest
7643 filesystem.
7644 "maxevents" is the maximum number of events which will be queued up
7646 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7647 this is passed as 0, then the kernel (or previously set) default is
7648 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7649 limit, the kernel throws away events, but records the fact that it
7650 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7651 structure list (see "guestfs_inotify_read").
7652 Before any events are generated, you have to add some watches to the
7654 internal watch list. See: "guestfs_inotify_add_watch" and
7655 "guestfs_inotify_rm_watch".
7656 Queued up events should be read periodically by calling
7658 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7659 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7660 events out often enough then you risk the internal queue overflowing.
7661 The handle should be closed after use by calling
7663 "guestfs_inotify_close". This also removes any watches automatically.
7664 See also inotify(7) for an overview of the inotify interface as exposed
7666 by the Linux kernel, which is roughly what we expose via libguestfs.
7667 Note that there is one global inotify handle per libguestfs instance.
7668 This function returns 0 on success or -1 on error.
7670 This function depends on the feature "inotify". See also
7672 "guestfs_feature_available".
7673 (Added in 1.0.66)
7675 guestfs_inotify_read
7677 struct guestfs_inotify_event_list *
7678 guestfs_inotify_read (guestfs_h *g);
7679 Return the complete queue of events that have happened since the
7681 previous read call.
7682 If no events have happened, this returns an empty list.
7684 Note: In order to make sure that all events have been read, you must
7686 call this function repeatedly until it returns an empty list. The
7687 reason is that the call will read events up to the maximum appliance-
7688 to-host message size and leave remaining events in the queue.
7689 This function returns a "struct guestfs_inotify_event_list *", or NULL
7691 if there was an error. The caller must call
7692 "guestfs_free_inotify_event_list" after use.
7693 This function depends on the feature "inotify". See also
7695 "guestfs_feature_available".
7696 (Added in 1.0.66)
7698 guestfs_inotify_rm_watch
7700 int
7701 guestfs_inotify_rm_watch (guestfs_h *g,
7702 int wd);
7703 Remove a previously defined inotify watch. See
7705 "guestfs_inotify_add_watch".
7706 This function returns 0 on success or -1 on error.
7708 This function depends on the feature "inotify". See also
7710 "guestfs_feature_available".
7711 (Added in 1.0.66)
7713 guestfs_inspect_get_arch
7715 char *
7716 guestfs_inspect_get_arch (guestfs_h *g,
7717 const char *root);
7718 This returns the architecture of the inspected operating system. The
7720 possible return values are listed under "guestfs_file_architecture".
7721 If the architecture could not be determined, then the string "unknown"
7723 is returned.
7724 Please read "INSPECTION" for more details.
7726 This function returns a string, or NULL on error. The caller must free
7728 the returned string after use.
7729 (Added in 1.5.3)
7731 guestfs_inspect_get_build_id
7733 char *
7734 guestfs_inspect_get_build_id (guestfs_h *g,
7735 const char *root);
7736 This returns the build ID of the system, or the string "unknown" if the
7738 system does not have a build ID.
7739 For Windows, this gets the build number. Although it is returned as a
7741 string, it is (so far) always a number. See
7742 https://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions for
7743 some possible values.
7744 For Linux, this returns the "BUILD_ID" string from /etc/os-release,
7746 although this is not often used.
7747 Please read "INSPECTION" for more details.
7749 This function returns a string, or NULL on error. The caller must free
7751 the returned string after use.
7752 (Added in 1.49.8)
7754 guestfs_inspect_get_distro
7756 char *
7757 guestfs_inspect_get_distro (guestfs_h *g,
7758 const char *root);
7759 This returns the distro (distribution) of the inspected operating
7761 system.
7762 Currently defined distros are:
7764 "alpinelinux"
7766 Alpine Linux.
7767 "altlinux"
7769 ALT Linux.
7770 "archlinux"
7772 Arch Linux.
7773 "buildroot"
7775 Buildroot-derived distro, but not one we specifically recognize.
7776 "centos"
7778 CentOS.
7779 "cirros"
7781 Cirros.
7782 "coreos"
7784 CoreOS.
7785 "debian"
7787 Debian.
7788 "fedora"
7790 Fedora.
7791 "freebsd"
7793 FreeBSD.
7794 "freedos"
7796 FreeDOS.
7797 "frugalware"
7799 Frugalware.
7800 "gentoo"
7802 Gentoo.
7803 "kalilinux"
7805 Kali Linux.
7806 "kylin"
7808 Kylin.
7809 "linuxmint"
7811 Linux Mint.
7812 "mageia"
7814 Mageia.
7815 "mandriva"
7817 Mandriva.
7818 "meego"
7820 MeeGo.
7821 "msdos"
7823 Microsoft DOS.
7824 "neokylin"
7826 NeoKylin.
7827 "netbsd"
7829 NetBSD.
7830 "openbsd"
7832 OpenBSD.
7833 "openmandriva"
7835 OpenMandriva Lx.
7836 "opensuse"
7838 OpenSUSE.
7839 "oraclelinux"
7841 Oracle Linux.
7842 "pardus"
7844 Pardus.
7845 "pldlinux"
7847 PLD Linux.
7848 "redhat-based"
7850 Some Red Hat-derived distro.
7851 "rhel"
7853 Red Hat Enterprise Linux.
7854 "rocky"
7856 Rocky Linux.
7857 "scientificlinux"
7859 Scientific Linux.
7860 "slackware"
7862 Slackware.
7863 "sles"
7865 SuSE Linux Enterprise Server or Desktop.
7866 "suse-based"
7868 Some openSuSE-derived distro.
7869 "ttylinux"
7871 ttylinux.
7872 "ubuntu"
7874 Ubuntu.
7875 "unknown"
7877 The distro could not be determined.
7878 "voidlinux"
7880 Void Linux.
7881 "windows"
7883 Windows does not have distributions. This string is returned if
7884 the OS type is Windows.
7885 Future versions of libguestfs may return other strings here. The
7887 caller should be prepared to handle any string.
7888 Please read "INSPECTION" for more details.
7890 This function returns a string, or NULL on error. The caller must free
7892 the returned string after use.
7893 (Added in 1.5.3)
7895 guestfs_inspect_get_drive_mappings
7897 char **
7898 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7899 const char *root);
7900 This call is useful for Windows which uses a primitive system of
7902 assigning drive letters (like C:\) to partitions. This inspection API
7903 examines the Windows Registry to find out how disks/partitions are
7904 mapped to drive letters, and returns a hash table as in the example
7905 below:
7906 C => /dev/vda2
7908 E => /dev/vdb1
7909 F => /dev/vdc1
7910 Note that keys are drive letters. For Windows, the key is case
7912 insensitive and just contains the drive letter, without the customary
7913 colon separator character.
7914 In future we may support other operating systems that also used drive
7916 letters, but the keys for those might not be case insensitive and might
7917 be longer than 1 character. For example in OS-9, hard drives were
7918 named "h0", "h1" etc.
7919 For Windows guests, currently only hard drive mappings are returned.
7921 Removable disks (eg. DVD-ROMs) are ignored.
7922 For guests that do not use drive mappings, or if the drive mappings
7924 could not be determined, this returns an empty hash table.
7925 Please read "INSPECTION" for more details. See also
7927 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7928 This function returns a NULL-terminated array of strings, or NULL if
7930 there was an error. The array of strings will always have length
7931 "2n+1", where "n" keys and values alternate, followed by the trailing
7932 NULL entry. The caller must free the strings and the array after use.
7933 (Added in 1.9.17)
7935 guestfs_inspect_get_filesystems
7937 char **
7938 guestfs_inspect_get_filesystems (guestfs_h *g,
7939 const char *root);
7940 This returns a list of all the filesystems that we think are associated
7942 with this operating system. This includes the root filesystem, other
7943 ordinary filesystems, and non-mounted devices like swap partitions.
7944 In the case of a multi-boot virtual machine, it is possible for a
7946 filesystem to be shared between operating systems.
7947 Please read "INSPECTION" for more details. See also
7949 "guestfs_inspect_get_mountpoints".
7950 This function returns a NULL-terminated array of strings (like
7952 environ(3)), or NULL if there was an error. The caller must free the
7953 strings and the array after use.
7954 (Added in 1.5.3)
7956 guestfs_inspect_get_format
7958 char *
7959 guestfs_inspect_get_format (guestfs_h *g,
7960 const char *root);
7961 This function is deprecated. There is no replacement. Consult the API
7963 documentation in guestfs(3) for further information.
7964 Deprecated functions will not be removed from the API, but the fact
7966 that they are deprecated indicates that there are problems with correct
7967 use of these functions.
7968 Before libguestfs 1.38, there was some unreliable support for detecting
7970 installer CDs. This API would return:
7971 "installed"
7973 This is an installed operating system.
7974 "installer"
7976 The disk image being inspected is not an installed operating
7977 system, but a bootable install disk, live CD, or similar.
7978 "unknown"
7980 The format of this disk image is not known.
7981 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
7983 directly to detect installer CDs.
7984 Please read "INSPECTION" for more details.
7986 This function returns a string, or NULL on error. The caller must free
7988 the returned string after use.
7989 (Added in 1.9.4)
7991 guestfs_inspect_get_hostname
7993 char *
7994 guestfs_inspect_get_hostname (guestfs_h *g,
7995 const char *root);
7996 This function returns the hostname of the operating system as found by
7998 inspection of the guest’s configuration files.
7999 If the hostname could not be determined, then the string "unknown" is
8001 returned.
8002 Please read "INSPECTION" for more details.
8004 This function returns a string, or NULL on error. The caller must free
8006 the returned string after use.
8007 (Added in 1.7.9)
8009 guestfs_inspect_get_icon
8011 char *
8012 guestfs_inspect_get_icon (guestfs_h *g,
8013 const char *root,
8014 size_t *size_r,
8015 ...);
8016 You may supply a list of optional arguments to this call. Use zero or
8018 more of the following pairs of parameters, and terminate the list with
8019 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8020 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
8022 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
8023 This function returns an icon corresponding to the inspected operating
8025 system. The icon is returned as a buffer containing a PNG image (re-
8026 encoded to PNG if necessary).
8027 If it was not possible to get an icon this function returns a zero-
8029 length (non-NULL) buffer. Callers must check for this case.
8030 Libguestfs will start by looking for a file called /etc/favicon.png or
8032 C:\etc\favicon.png and if it has the correct format, the contents of
8033 this file will be returned. You can disable favicons by passing the
8034 optional "favicon" boolean as false (default is true).
8035 If finding the favicon fails, then we look in other places in the guest
8037 for a suitable icon.
8038 If the optional "highquality" boolean is true then only high quality
8040 icons are returned, which means only icons of high resolution with an
8041 alpha channel. The default (false) is to return any icon we can, even
8042 if it is of substandard quality.
8043 Notes:
8045 • Unlike most other inspection API calls, the guest’s disks must be
8047 mounted up before you call this, since it needs to read information
8048 from the guest filesystem during the call.
8049 • Security: The icon data comes from the untrusted guest, and should
8051 be treated with caution. PNG files have been known to contain
8052 exploits. Ensure that libpng (or other relevant libraries) are
8053 fully up to date before trying to process or display the icon.
8054 • The PNG image returned can be any size. It might not be square.
8056 Libguestfs tries to return the largest, highest quality icon
8057 available. The application must scale the icon to the required
8058 size.
8059 • Extracting icons from Windows guests requires the external
8061 wrestool(1) program from the "icoutils" package, and several
8062 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
8063 package. These must be installed separately.
8064 • Operating system icons are usually trademarks. Seek legal advice
8066 before using trademarks in applications.
8067 This function returns a buffer, or NULL on error. The size of the
8069 returned buffer is written to *size_r. The caller must free the
8070 returned buffer after use.
8071 (Added in 1.11.12)
8073 guestfs_inspect_get_icon_va
8075 char *
8076 guestfs_inspect_get_icon_va (guestfs_h *g,
8077 const char *root,
8078 size_t *size_r,
8079 va_list args);
8080 This is the "va_list variant" of "guestfs_inspect_get_icon".
8082 See "CALLS WITH OPTIONAL ARGUMENTS".
8084 guestfs_inspect_get_icon_argv
8086 char *
8087 guestfs_inspect_get_icon_argv (guestfs_h *g,
8088 const char *root,
8089 size_t *size_r,
8090 const struct guestfs_inspect_get_icon_argv *optargs);
8091 This is the "argv variant" of "guestfs_inspect_get_icon".
8093 See "CALLS WITH OPTIONAL ARGUMENTS".
8095 guestfs_inspect_get_major_version
8097 int
8098 guestfs_inspect_get_major_version (guestfs_h *g,
8099 const char *root);
8100 This returns the major version number of the inspected operating
8102 system.
8103 Windows uses a consistent versioning scheme which is not reflected in
8105 the popular public names used by the operating system. Notably the
8106 operating system known as "Windows 7" is really version 6.1 (ie. major
8107 = 6, minor = 1). You can find out the real versions corresponding to
8108 releases of Windows by consulting Wikipedia or MSDN.
8109 If the version could not be determined, then 0 is returned.
8111 Please read "INSPECTION" for more details.
8113 On error this function returns -1.
8115 (Added in 1.5.3)
8117 guestfs_inspect_get_minor_version
8119 int
8120 guestfs_inspect_get_minor_version (guestfs_h *g,
8121 const char *root);
8122 This returns the minor version number of the inspected operating
8124 system.
8125 If the version could not be determined, then 0 is returned.
8127 Please read "INSPECTION" for more details. See also
8129 "guestfs_inspect_get_major_version".
8130 On error this function returns -1.
8132 (Added in 1.5.3)
8134 guestfs_inspect_get_mountpoints
8136 char **
8137 guestfs_inspect_get_mountpoints (guestfs_h *g,
8138 const char *root);
8139 This returns a hash of where we think the filesystems associated with
8141 this operating system should be mounted. Callers should note that this
8142 is at best an educated guess made by reading configuration files such
8143 as /etc/fstab. In particular note that this may return filesystems
8144 which are non-existent or not mountable and callers should be prepared
8145 to handle or ignore failures if they try to mount them.
8146 Each element in the returned hashtable has a key which is the path of
8148 the mountpoint (eg. /boot) and a value which is the filesystem that
8149 would be mounted there (eg. /dev/sda1).
8150 Non-mounted devices such as swap devices are not returned in this list.
8152 For operating systems like Windows which still use drive letters, this
8154 call will only return an entry for the first drive "mounted on" /. For
8155 information about the mapping of drive letters to partitions, see
8156 "guestfs_inspect_get_drive_mappings".
8157 Please read "INSPECTION" for more details. See also
8159 "guestfs_inspect_get_filesystems".
8160 This function returns a NULL-terminated array of strings, or NULL if
8162 there was an error. The array of strings will always have length
8163 "2n+1", where "n" keys and values alternate, followed by the trailing
8164 NULL entry. The caller must free the strings and the array after use.
8165 (Added in 1.5.3)
8167 guestfs_inspect_get_osinfo
8169 char *
8170 guestfs_inspect_get_osinfo (guestfs_h *g,
8171 const char *root);
8172 This function returns a possible short ID for libosinfo corresponding
8174 to the guest.
8175 Note: The returned ID is only a guess by libguestfs, and nothing
8177 ensures that it actually exists in osinfo-db.
8178 If no ID could not be determined, then the string "unknown" is
8180 returned.
8181 This function returns a string, or NULL on error. The caller must free
8183 the returned string after use.
8184 (Added in 1.39.1)
8186 guestfs_inspect_get_package_format
8188 char *
8189 guestfs_inspect_get_package_format (guestfs_h *g,
8190 const char *root);
8191 This function and "guestfs_inspect_get_package_management" return the
8193 package format and package management tool used by the inspected
8194 operating system. For example for Fedora these functions would return
8195 "rpm" (package format), and "yum" or "dnf" (package management).
8196 This returns the string "unknown" if we could not determine the package
8198 format or if the operating system does not have a real packaging system
8199 (eg. Windows).
8200 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8202 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
8203 other strings.
8204 Please read "INSPECTION" for more details.
8206 This function returns a string, or NULL on error. The caller must free
8208 the returned string after use.
8209 (Added in 1.7.5)
8211 guestfs_inspect_get_package_management
8213 char *
8214 guestfs_inspect_get_package_management (guestfs_h *g,
8215 const char *root);
8216 "guestfs_inspect_get_package_format" and this function return the
8218 package format and package management tool used by the inspected
8219 operating system. For example for Fedora these functions would return
8220 "rpm" (package format), and "yum" or "dnf" (package management).
8221 This returns the string "unknown" if we could not determine the package
8223 management tool or if the operating system does not have a real
8224 packaging system (eg. Windows).
8225 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8227 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8228 "apk", "xbps". Future versions of libguestfs may return other strings.
8229 Please read "INSPECTION" for more details.
8231 This function returns a string, or NULL on error. The caller must free
8233 the returned string after use.
8234 (Added in 1.7.5)
8236 guestfs_inspect_get_product_name
8238 char *
8239 guestfs_inspect_get_product_name (guestfs_h *g,
8240 const char *root);
8241 This returns the product name of the inspected operating system. The
8243 product name is generally some freeform string which can be displayed
8244 to the user, but should not be parsed by programs.
8245 If the product name could not be determined, then the string "unknown"
8247 is returned.
8248 Please read "INSPECTION" for more details.
8250 This function returns a string, or NULL on error. The caller must free
8252 the returned string after use.
8253 (Added in 1.5.3)
8255 guestfs_inspect_get_product_variant
8257 char *
8258 guestfs_inspect_get_product_variant (guestfs_h *g,
8259 const char *root);
8260 This returns the product variant of the inspected operating system.
8262 For Windows guests, this returns the contents of the Registry key
8264 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8265 which is usually a string such as "Client" or "Server" (other values
8266 are possible). This can be used to distinguish consumer and enterprise
8267 versions of Windows that have the same version number (for example,
8268 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8269 is "Client" and the latter is "Server").
8270 For enterprise Linux guests, in future we intend this to return the
8272 product variant such as "Desktop", "Server" and so on. But this is not
8273 implemented at present.
8274 If the product variant could not be determined, then the string
8276 "unknown" is returned.
8277 Please read "INSPECTION" for more details. See also
8279 "guestfs_inspect_get_product_name",
8280 "guestfs_inspect_get_major_version".
8281 This function returns a string, or NULL on error. The caller must free
8283 the returned string after use.
8284 (Added in 1.9.13)
8286 guestfs_inspect_get_roots
8288 char **
8289 guestfs_inspect_get_roots (guestfs_h *g);
8290 This function is a convenient way to get the list of root devices, as
8292 returned from a previous call to "guestfs_inspect_os", but without
8293 redoing the whole inspection process.
8294 This returns an empty list if either no root devices were found or the
8296 caller has not called "guestfs_inspect_os".
8297 Please read "INSPECTION" for more details.
8299 This function returns a NULL-terminated array of strings (like
8301 environ(3)), or NULL if there was an error. The caller must free the
8302 strings and the array after use.
8303 (Added in 1.7.3)
8305 guestfs_inspect_get_type
8307 char *
8308 guestfs_inspect_get_type (guestfs_h *g,
8309 const char *root);
8310 This returns the type of the inspected operating system. Currently
8312 defined types are:
8313 "linux"
8315 Any Linux-based operating system.
8316 "windows"
8318 Any Microsoft Windows operating system.
8319 "freebsd"
8321 FreeBSD.
8322 "netbsd"
8324 NetBSD.
8325 "openbsd"
8327 OpenBSD.
8328 "hurd"
8330 GNU/Hurd.
8331 "dos"
8333 MS-DOS, FreeDOS and others.
8334 "minix"
8336 MINIX.
8337 "unknown"
8339 The operating system type could not be determined.
8340 Future versions of libguestfs may return other strings here. The
8342 caller should be prepared to handle any string.
8343 Please read "INSPECTION" for more details.
8345 This function returns a string, or NULL on error. The caller must free
8347 the returned string after use.
8348 (Added in 1.5.3)
8350 guestfs_inspect_get_windows_current_control_set
8352 char *
8353 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8354 const char *root);
8355 This returns the Windows CurrentControlSet of the inspected guest. The
8357 CurrentControlSet is a registry key name such as "ControlSet001".
8358 This call assumes that the guest is Windows and that the Registry could
8360 be examined by inspection. If this is not the case then an error is
8361 returned.
8362 Please read "INSPECTION" for more details.
8364 This function returns a string, or NULL on error. The caller must free
8366 the returned string after use.
8367 (Added in 1.9.17)
8369 guestfs_inspect_get_windows_software_hive
8371 char *
8372 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8373 const char *root);
8374 This returns the path to the hive (binary Windows Registry file)
8376 corresponding to HKLM\SOFTWARE.
8377 This call assumes that the guest is Windows and that the guest has a
8379 software hive file with the right name. If this is not the case then
8380 an error is returned. This call does not check that the hive is a
8381 valid Windows Registry hive.
8382 You can use "guestfs_hivex_open" to read or write to the hive.
8384 Please read "INSPECTION" for more details.
8386 This function returns a string, or NULL on error. The caller must free
8388 the returned string after use.
8389 (Added in 1.35.26)
8391 guestfs_inspect_get_windows_system_hive
8393 char *
8394 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8395 const char *root);
8396 This returns the path to the hive (binary Windows Registry file)
8398 corresponding to HKLM\SYSTEM.
8399 This call assumes that the guest is Windows and that the guest has a
8401 system hive file with the right name. If this is not the case then an
8402 error is returned. This call does not check that the hive is a valid
8403 Windows Registry hive.
8404 You can use "guestfs_hivex_open" to read or write to the hive.
8406 Please read "INSPECTION" for more details.
8408 This function returns a string, or NULL on error. The caller must free
8410 the returned string after use.
8411 (Added in 1.35.26)
8413 guestfs_inspect_get_windows_systemroot
8415 char *
8416 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8417 const char *root);
8418 This returns the Windows systemroot of the inspected guest. The
8420 systemroot is a directory path such as /WINDOWS.
8421 This call assumes that the guest is Windows and that the systemroot
8423 could be determined by inspection. If this is not the case then an
8424 error is returned.
8425 Please read "INSPECTION" for more details.
8427 This function returns a string, or NULL on error. The caller must free
8429 the returned string after use.
8430 (Added in 1.5.25)
8432 guestfs_inspect_is_live
8434 int
8435 guestfs_inspect_is_live (guestfs_h *g,
8436 const char *root);
8437 This function is deprecated. There is no replacement. Consult the API
8439 documentation in guestfs(3) for further information.
8440 Deprecated functions will not be removed from the API, but the fact
8442 that they are deprecated indicates that there are problems with correct
8443 use of these functions.
8444 This is deprecated and always returns "false".
8446 Please read "INSPECTION" for more details.
8448 This function returns a C truth value on success or -1 on error.
8450 (Added in 1.9.4)
8452 guestfs_inspect_is_multipart
8454 int
8455 guestfs_inspect_is_multipart (guestfs_h *g,
8456 const char *root);
8457 This function is deprecated. There is no replacement. Consult the API
8459 documentation in guestfs(3) for further information.
8460 Deprecated functions will not be removed from the API, but the fact
8462 that they are deprecated indicates that there are problems with correct
8463 use of these functions.
8464 This is deprecated and always returns "false".
8466 Please read "INSPECTION" for more details.
8468 This function returns a C truth value on success or -1 on error.
8470 (Added in 1.9.4)
8472 guestfs_inspect_is_netinst
8474 int
8475 guestfs_inspect_is_netinst (guestfs_h *g,
8476 const char *root);
8477 This function is deprecated. There is no replacement. Consult the API
8479 documentation in guestfs(3) for further information.
8480 Deprecated functions will not be removed from the API, but the fact
8482 that they are deprecated indicates that there are problems with correct
8483 use of these functions.
8484 This is deprecated and always returns "false".
8486 Please read "INSPECTION" for more details.
8488 This function returns a C truth value on success or -1 on error.
8490 (Added in 1.9.4)
8492 guestfs_inspect_list_applications
8494 struct guestfs_application_list *
8495 guestfs_inspect_list_applications (guestfs_h *g,
8496 const char *root);
8497 This function is deprecated. In new code, use the
8499 "guestfs_inspect_list_applications2" call instead.
8500 Deprecated functions will not be removed from the API, but the fact
8502 that they are deprecated indicates that there are problems with correct
8503 use of these functions.
8504 Return the list of applications installed in the operating system.
8506 Note: This call works differently from other parts of the inspection
8508 API. You have to call "guestfs_inspect_os", then
8509 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8510 calling this. Listing applications is a significantly more difficult
8511 operation which requires access to the full filesystem. Also note that
8512 unlike the other "guestfs_inspect_get_*" calls which are just returning
8513 data cached in the libguestfs handle, this call actually reads parts of
8514 the mounted filesystems during the call.
8515 This returns an empty list if the inspection code was not able to
8517 determine the list of applications.
8518 The application structure contains the following fields:
8520 "app_name"
8522 The name of the application. For Linux guests, this is the package
8523 name.
8524 "app_display_name"
8526 The display name of the application, sometimes localized to the
8527 install language of the guest operating system.
8528 If unavailable this is returned as an empty string "". Callers
8530 needing to display something can use "app_name" instead.
8531 "app_epoch"
8533 For package managers which use epochs, this contains the epoch of
8534 the package (an integer). If unavailable, this is returned as 0.
8535 "app_version"
8537 The version string of the application or package. If unavailable
8538 this is returned as an empty string "".
8539 "app_release"
8541 The release string of the application or package, for package
8542 managers that use this. If unavailable this is returned as an
8543 empty string "".
8544 "app_install_path"
8546 The installation path of the application (on operating systems such
8547 as Windows which use installation paths). This path is in the
8548 format used by the guest operating system, it is not a libguestfs
8549 path.
8550 If unavailable this is returned as an empty string "".
8552 "app_trans_path"
8554 The install path translated into a libguestfs path. If unavailable
8555 this is returned as an empty string "".
8556 "app_publisher"
8558 The name of the publisher of the application, for package managers
8559 that use this. If unavailable this is returned as an empty string
8560 "".
8561 "app_url"
8563 The URL (eg. upstream URL) of the application. If unavailable this
8564 is returned as an empty string "".
8565 "app_source_package"
8567 For packaging systems which support this, the name of the source
8568 package. If unavailable this is returned as an empty string "".
8569 "app_summary"
8571 A short (usually one line) description of the application or
8572 package. If unavailable this is returned as an empty string "".
8573 "app_description"
8575 A longer description of the application or package. If unavailable
8576 this is returned as an empty string "".
8577 Please read "INSPECTION" for more details.
8579 This function returns a "struct guestfs_application_list *", or NULL if
8581 there was an error. The caller must call
8582 "guestfs_free_application_list" after use.
8583 (Added in 1.7.8)
8585 guestfs_inspect_list_applications2
8587 struct guestfs_application2_list *
8588 guestfs_inspect_list_applications2 (guestfs_h *g,
8589 const char *root);
8590 Return the list of applications installed in the operating system.
8592 Note: This call works differently from other parts of the inspection
8594 API. You have to call "guestfs_inspect_os", then
8595 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8596 calling this. Listing applications is a significantly more difficult
8597 operation which requires access to the full filesystem. Also note that
8598 unlike the other "guestfs_inspect_get_*" calls which are just returning
8599 data cached in the libguestfs handle, this call actually reads parts of
8600 the mounted filesystems during the call.
8601 This returns an empty list if the inspection code was not able to
8603 determine the list of applications.
8604 The application structure contains the following fields:
8606 "app2_name"
8608 The name of the application. For Linux guests, this is the package
8609 name.
8610 "app2_display_name"
8612 The display name of the application, sometimes localized to the
8613 install language of the guest operating system.
8614 If unavailable this is returned as an empty string "". Callers
8616 needing to display something can use "app2_name" instead.
8617 "app2_epoch"
8619 For package managers which use epochs, this contains the epoch of
8620 the package (an integer). If unavailable, this is returned as 0.
8621 "app2_version"
8623 The version string of the application or package. If unavailable
8624 this is returned as an empty string "".
8625 "app2_release"
8627 The release string of the application or package, for package
8628 managers that use this. If unavailable this is returned as an
8629 empty string "".
8630 "app2_arch"
8632 The architecture string of the application or package, for package
8633 managers that use this. If unavailable this is returned as an
8634 empty string "".
8635 "app2_install_path"
8637 The installation path of the application (on operating systems such
8638 as Windows which use installation paths). This path is in the
8639 format used by the guest operating system, it is not a libguestfs
8640 path.
8641 If unavailable this is returned as an empty string "".
8643 "app2_trans_path"
8645 The install path translated into a libguestfs path. If unavailable
8646 this is returned as an empty string "".
8647 "app2_publisher"
8649 The name of the publisher of the application, for package managers
8650 that use this. If unavailable this is returned as an empty string
8651 "".
8652 "app2_url"
8654 The URL (eg. upstream URL) of the application. If unavailable this
8655 is returned as an empty string "".
8656 "app2_source_package"
8658 For packaging systems which support this, the name of the source
8659 package. If unavailable this is returned as an empty string "".
8660 "app2_summary"
8662 A short (usually one line) description of the application or
8663 package. If unavailable this is returned as an empty string "".
8664 "app2_description"
8666 A longer description of the application or package. If unavailable
8667 this is returned as an empty string "".
8668 Please read "INSPECTION" for more details.
8670 This function returns a "struct guestfs_application2_list *", or NULL
8672 if there was an error. The caller must call
8673 "guestfs_free_application2_list" after use.
8674 (Added in 1.19.56)
8676 guestfs_inspect_os
8678 char **
8679 guestfs_inspect_os (guestfs_h *g);
8680 This function uses other libguestfs functions and certain heuristics to
8682 inspect the disk(s) (usually disks belonging to a virtual machine),
8683 looking for operating systems.
8684 The list returned is empty if no operating systems were found.
8686 If one operating system was found, then this returns a list with a
8688 single element, which is the name of the root filesystem of this
8689 operating system. It is also possible for this function to return a
8690 list containing more than one element, indicating a dual-boot or multi-
8691 boot virtual machine, with each element being the root filesystem of
8692 one of the operating systems.
8693 You can pass the root string(s) returned to other
8695 "guestfs_inspect_get_*" functions in order to query further information
8696 about each operating system, such as the name and version.
8697 This function uses other libguestfs features such as "guestfs_mount_ro"
8699 and "guestfs_umount_all" in order to mount and unmount filesystems and
8700 look at the contents. This should be called with no disks currently
8701 mounted. The function may also use Augeas, so any existing Augeas
8702 handle will be closed.
8703 This function cannot decrypt encrypted disks. The caller must do that
8705 first (supplying the necessary keys) if the disk is encrypted.
8706 Please read "INSPECTION" for more details.
8708 See also "guestfs_list_filesystems".
8710 This function returns a NULL-terminated array of strings (like
8712 environ(3)), or NULL if there was an error. The caller must free the
8713 strings and the array after use.
8714 (Added in 1.5.3)
8716 guestfs_is_blockdev
8718 int
8719 guestfs_is_blockdev (guestfs_h *g,
8720 const char *path);
8721 This function is provided for backwards compatibility with earlier
8723 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8724 with no optional arguments.
8725 (Added in 1.5.10)
8727 guestfs_is_blockdev_opts
8729 int
8730 guestfs_is_blockdev_opts (guestfs_h *g,
8731 const char *path,
8732 ...);
8733 You may supply a list of optional arguments to this call. Use zero or
8735 more of the following pairs of parameters, and terminate the list with
8736 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8737 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8739 This returns "true" if and only if there is a block device with the
8741 given "path" name.
8742 If the optional flag "followsymlinks" is true, then a symlink (or chain
8744 of symlinks) that ends with a block device also causes the function to
8745 return true.
8746 This call only looks at files within the guest filesystem. Libguestfs
8748 partitions and block devices (eg. /dev/sda) cannot be used as the
8749 "path" parameter of this call.
8750 See also "guestfs_stat".
8752 This function returns a C truth value on success or -1 on error.
8754 (Added in 1.5.10)
8756 guestfs_is_blockdev_opts_va
8758 int
8759 guestfs_is_blockdev_opts_va (guestfs_h *g,
8760 const char *path,
8761 va_list args);
8762 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8764 See "CALLS WITH OPTIONAL ARGUMENTS".
8766 guestfs_is_blockdev_opts_argv
8768 int
8769 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8770 const char *path,
8771 const struct guestfs_is_blockdev_opts_argv *optargs);
8772 This is the "argv variant" of "guestfs_is_blockdev_opts".
8774 See "CALLS WITH OPTIONAL ARGUMENTS".
8776 guestfs_is_busy
8778 int
8779 guestfs_is_busy (guestfs_h *g);
8780 This always returns false. This function is deprecated with no
8782 replacement. Do not use this function.
8783 For more information on states, see guestfs(3).
8785 This function returns a C truth value on success or -1 on error.
8787 (Added in 1.0.2)
8789 guestfs_is_chardev
8791 int
8792 guestfs_is_chardev (guestfs_h *g,
8793 const char *path);
8794 This function is provided for backwards compatibility with earlier
8796 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8797 no optional arguments.
8798 (Added in 1.5.10)
8800 guestfs_is_chardev_opts
8802 int
8803 guestfs_is_chardev_opts (guestfs_h *g,
8804 const char *path,
8805 ...);
8806 You may supply a list of optional arguments to this call. Use zero or
8808 more of the following pairs of parameters, and terminate the list with
8809 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8810 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8812 This returns "true" if and only if there is a character device with the
8814 given "path" name.
8815 If the optional flag "followsymlinks" is true, then a symlink (or chain
8817 of symlinks) that ends with a chardev also causes the function to
8818 return true.
8819 See also "guestfs_stat".
8821 This function returns a C truth value on success or -1 on error.
8823 (Added in 1.5.10)
8825 guestfs_is_chardev_opts_va
8827 int
8828 guestfs_is_chardev_opts_va (guestfs_h *g,
8829 const char *path,
8830 va_list args);
8831 This is the "va_list variant" of "guestfs_is_chardev_opts".
8833 See "CALLS WITH OPTIONAL ARGUMENTS".
8835 guestfs_is_chardev_opts_argv
8837 int
8838 guestfs_is_chardev_opts_argv (guestfs_h *g,
8839 const char *path,
8840 const struct guestfs_is_chardev_opts_argv *optargs);
8841 This is the "argv variant" of "guestfs_is_chardev_opts".
8843 See "CALLS WITH OPTIONAL ARGUMENTS".
8845 guestfs_is_config
8847 int
8848 guestfs_is_config (guestfs_h *g);
8849 This returns true iff this handle is being configured (in the "CONFIG"
8851 state).
8852 For more information on states, see guestfs(3).
8854 This function returns a C truth value on success or -1 on error.
8856 (Added in 1.0.2)
8858 guestfs_is_dir
8860 int
8861 guestfs_is_dir (guestfs_h *g,
8862 const char *path);
8863 This function is provided for backwards compatibility with earlier
8865 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8866 optional arguments.
8867 (Added in 0.8)
8869 guestfs_is_dir_opts
8871 int
8872 guestfs_is_dir_opts (guestfs_h *g,
8873 const char *path,
8874 ...);
8875 You may supply a list of optional arguments to this call. Use zero or
8877 more of the following pairs of parameters, and terminate the list with
8878 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8879 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8881 This returns "true" if and only if there is a directory with the given
8883 "path" name. Note that it returns false for other objects like files.
8884 If the optional flag "followsymlinks" is true, then a symlink (or chain
8886 of symlinks) that ends with a directory also causes the function to
8887 return true.
8888 See also "guestfs_stat".
8890 This function returns a C truth value on success or -1 on error.
8892 (Added in 0.8)
8894 guestfs_is_dir_opts_va
8896 int
8897 guestfs_is_dir_opts_va (guestfs_h *g,
8898 const char *path,
8899 va_list args);
8900 This is the "va_list variant" of "guestfs_is_dir_opts".
8902 See "CALLS WITH OPTIONAL ARGUMENTS".
8904 guestfs_is_dir_opts_argv
8906 int
8907 guestfs_is_dir_opts_argv (guestfs_h *g,
8908 const char *path,
8909 const struct guestfs_is_dir_opts_argv *optargs);
8910 This is the "argv variant" of "guestfs_is_dir_opts".
8912 See "CALLS WITH OPTIONAL ARGUMENTS".
8914 guestfs_is_fifo
8916 int
8917 guestfs_is_fifo (guestfs_h *g,
8918 const char *path);
8919 This function is provided for backwards compatibility with earlier
8921 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8922 optional arguments.
8923 (Added in 1.5.10)
8925 guestfs_is_fifo_opts
8927 int
8928 guestfs_is_fifo_opts (guestfs_h *g,
8929 const char *path,
8930 ...);
8931 You may supply a list of optional arguments to this call. Use zero or
8933 more of the following pairs of parameters, and terminate the list with
8934 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8935 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8937 This returns "true" if and only if there is a FIFO (named pipe) with
8939 the given "path" name.
8940 If the optional flag "followsymlinks" is true, then a symlink (or chain
8942 of symlinks) that ends with a FIFO also causes the function to return
8943 true.
8944 See also "guestfs_stat".
8946 This function returns a C truth value on success or -1 on error.
8948 (Added in 1.5.10)
8950 guestfs_is_fifo_opts_va
8952 int
8953 guestfs_is_fifo_opts_va (guestfs_h *g,
8954 const char *path,
8955 va_list args);
8956 This is the "va_list variant" of "guestfs_is_fifo_opts".
8958 See "CALLS WITH OPTIONAL ARGUMENTS".
8960 guestfs_is_fifo_opts_argv
8962 int
8963 guestfs_is_fifo_opts_argv (guestfs_h *g,
8964 const char *path,
8965 const struct guestfs_is_fifo_opts_argv *optargs);
8966 This is the "argv variant" of "guestfs_is_fifo_opts".
8968 See "CALLS WITH OPTIONAL ARGUMENTS".
8970 guestfs_is_file
8972 int
8973 guestfs_is_file (guestfs_h *g,
8974 const char *path);
8975 This function is provided for backwards compatibility with earlier
8977 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
8978 optional arguments.
8979 (Added in 0.8)
8981 guestfs_is_file_opts
8983 int
8984 guestfs_is_file_opts (guestfs_h *g,
8985 const char *path,
8986 ...);
8987 You may supply a list of optional arguments to this call. Use zero or
8989 more of the following pairs of parameters, and terminate the list with
8990 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8991 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8993 This returns "true" if and only if there is a regular file with the
8995 given "path" name. Note that it returns false for other objects like
8996 directories.
8997 If the optional flag "followsymlinks" is true, then a symlink (or chain
8999 of symlinks) that ends with a file also causes the function to return
9000 true.
9001 See also "guestfs_stat".
9003 This function returns a C truth value on success or -1 on error.
9005 (Added in 0.8)
9007 guestfs_is_file_opts_va
9009 int
9010 guestfs_is_file_opts_va (guestfs_h *g,
9011 const char *path,
9012 va_list args);
9013 This is the "va_list variant" of "guestfs_is_file_opts".
9015 See "CALLS WITH OPTIONAL ARGUMENTS".
9017 guestfs_is_file_opts_argv
9019 int
9020 guestfs_is_file_opts_argv (guestfs_h *g,
9021 const char *path,
9022 const struct guestfs_is_file_opts_argv *optargs);
9023 This is the "argv variant" of "guestfs_is_file_opts".
9025 See "CALLS WITH OPTIONAL ARGUMENTS".
9027 guestfs_is_launching
9029 int
9030 guestfs_is_launching (guestfs_h *g);
9031 This returns true iff this handle is launching the subprocess (in the
9033 "LAUNCHING" state).
9034 For more information on states, see guestfs(3).
9036 This function returns a C truth value on success or -1 on error.
9038 (Added in 1.0.2)
9040 guestfs_is_lv
9042 int
9043 guestfs_is_lv (guestfs_h *g,
9044 const char *mountable);
9045 This command tests whether "mountable" is a logical volume, and returns
9047 true iff this is the case.
9048 This function returns a C truth value on success or -1 on error.
9050 (Added in 1.5.3)
9052 guestfs_is_ready
9054 int
9055 guestfs_is_ready (guestfs_h *g);
9056 This returns true iff this handle is ready to accept commands (in the
9058 "READY" state).
9059 For more information on states, see guestfs(3).
9061 This function returns a C truth value on success or -1 on error.
9063 (Added in 1.0.2)
9065 guestfs_is_socket
9067 int
9068 guestfs_is_socket (guestfs_h *g,
9069 const char *path);
9070 This function is provided for backwards compatibility with earlier
9072 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
9073 no optional arguments.
9074 (Added in 1.5.10)
9076 guestfs_is_socket_opts
9078 int
9079 guestfs_is_socket_opts (guestfs_h *g,
9080 const char *path,
9081 ...);
9082 You may supply a list of optional arguments to this call. Use zero or
9084 more of the following pairs of parameters, and terminate the list with
9085 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9086 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9088 This returns "true" if and only if there is a Unix domain socket with
9090 the given "path" name.
9091 If the optional flag "followsymlinks" is true, then a symlink (or chain
9093 of symlinks) that ends with a socket also causes the function to return
9094 true.
9095 See also "guestfs_stat".
9097 This function returns a C truth value on success or -1 on error.
9099 (Added in 1.5.10)
9101 guestfs_is_socket_opts_va
9103 int
9104 guestfs_is_socket_opts_va (guestfs_h *g,
9105 const char *path,
9106 va_list args);
9107 This is the "va_list variant" of "guestfs_is_socket_opts".
9109 See "CALLS WITH OPTIONAL ARGUMENTS".
9111 guestfs_is_socket_opts_argv
9113 int
9114 guestfs_is_socket_opts_argv (guestfs_h *g,
9115 const char *path,
9116 const struct guestfs_is_socket_opts_argv *optargs);
9117 This is the "argv variant" of "guestfs_is_socket_opts".
9119 See "CALLS WITH OPTIONAL ARGUMENTS".
9121 guestfs_is_symlink
9123 int
9124 guestfs_is_symlink (guestfs_h *g,
9125 const char *path);
9126 This returns "true" if and only if there is a symbolic link with the
9128 given "path" name.
9129 See also "guestfs_stat".
9131 This function returns a C truth value on success or -1 on error.
9133 (Added in 1.5.10)
9135 guestfs_is_whole_device
9137 int
9138 guestfs_is_whole_device (guestfs_h *g,
9139 const char *device);
9140 This returns "true" if and only if "device" refers to a whole block
9142 device. That is, not a partition or a logical device.
9143 This function returns a C truth value on success or -1 on error.
9145 (Added in 1.21.9)
9147 guestfs_is_zero
9149 int
9150 guestfs_is_zero (guestfs_h *g,
9151 const char *path);
9152 This returns true iff the file exists and the file is empty or it
9154 contains all zero bytes.
9155 This function returns a C truth value on success or -1 on error.
9157 (Added in 1.11.8)
9159 guestfs_is_zero_device
9161 int
9162 guestfs_is_zero_device (guestfs_h *g,
9163 const char *device);
9164 This returns true iff the device exists and contains all zero bytes.
9166 Note that for large devices this can take a long time to run.
9168 This function returns a C truth value on success or -1 on error.
9170 (Added in 1.11.8)
9172 guestfs_isoinfo
9174 struct guestfs_isoinfo *
9175 guestfs_isoinfo (guestfs_h *g,
9176 const char *isofile);
9177 This is the same as "guestfs_isoinfo_device" except that it works for
9179 an ISO file located inside some other mounted filesystem. Note that in
9180 the common case where you have added an ISO file as a libguestfs
9181 device, you would not call this. Instead you would call
9182 "guestfs_isoinfo_device".
9183 This function returns a "struct guestfs_isoinfo *", or NULL if there
9185 was an error. The caller must call "guestfs_free_isoinfo" after use.
9186 (Added in 1.17.19)
9188 guestfs_isoinfo_device
9190 struct guestfs_isoinfo *
9191 guestfs_isoinfo_device (guestfs_h *g,
9192 const char *device);
9193 "device" is an ISO device. This returns a struct of information read
9195 from the primary volume descriptor (the ISO equivalent of the
9196 superblock) of the device.
9197 Usually it is more efficient to use the isoinfo(1) command with the -d
9199 option on the host to analyze ISO files, instead of going through
9200 libguestfs.
9201 For information on the primary volume descriptor fields, see
9203 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9204 This function returns a "struct guestfs_isoinfo *", or NULL if there
9206 was an error. The caller must call "guestfs_free_isoinfo" after use.
9207 (Added in 1.17.19)
9209 guestfs_journal_close
9211 int
9212 guestfs_journal_close (guestfs_h *g);
9213 Close the journal handle.
9215 This function returns 0 on success or -1 on error.
9217 This function depends on the feature "journal". See also
9219 "guestfs_feature_available".
9220 (Added in 1.23.11)
9222 guestfs_journal_get
9224 struct guestfs_xattr_list *
9225 guestfs_journal_get (guestfs_h *g);
9226 Read the current journal entry. This returns all the fields in the
9228 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
9229 field name (a string).
9230 The "attrval" is the field value (a binary blob, often but not always a
9232 string). Please note that "attrval" is a byte array, not a
9233 \0-terminated C string.
9234 The length of data may be truncated to the data threshold (see:
9236 "guestfs_journal_set_data_threshold",
9237 "guestfs_journal_get_data_threshold").
9238 If you set the data threshold to unlimited (0) then this call can read
9240 a journal entry of any size, ie. it is not limited by the libguestfs
9241 protocol.
9242 This function returns a "struct guestfs_xattr_list *", or NULL if there
9244 was an error. The caller must call "guestfs_free_xattr_list" after
9245 use.
9246 This function depends on the feature "journal". See also
9248 "guestfs_feature_available".
9249 (Added in 1.23.11)
9251 guestfs_journal_get_data_threshold
9253 int64_t
9254 guestfs_journal_get_data_threshold (guestfs_h *g);
9255 Get the current data threshold for reading journal entries. This is a
9257 hint to the journal that it may truncate data fields to this size when
9258 reading them (note also that it may not truncate them). If this
9259 returns 0, then the threshold is unlimited.
9260 See also "guestfs_journal_set_data_threshold".
9262 On error this function returns -1.
9264 This function depends on the feature "journal". See also
9266 "guestfs_feature_available".
9267 (Added in 1.23.11)
9269 guestfs_journal_get_realtime_usec
9271 int64_t
9272 guestfs_journal_get_realtime_usec (guestfs_h *g);
9273 Get the realtime (wallclock) timestamp of the current journal entry.
9275 On error this function returns -1.
9277 This function depends on the feature "journal". See also
9279 "guestfs_feature_available".
9280 (Added in 1.27.18)
9282 guestfs_journal_next
9284 int
9285 guestfs_journal_next (guestfs_h *g);
9286 Move to the next journal entry. You have to call this at least once
9288 after opening the handle before you are able to read data.
9289 The returned boolean tells you if there are any more journal records to
9291 read. "true" means you can read the next record (eg. using
9292 "guestfs_journal_get"), and "false" means you have reached the end of
9293 the journal.
9294 This function returns a C truth value on success or -1 on error.
9296 This function depends on the feature "journal". See also
9298 "guestfs_feature_available".
9299 (Added in 1.23.11)
9301 guestfs_journal_open
9303 int
9304 guestfs_journal_open (guestfs_h *g,
9305 const char *directory);
9306 Open the systemd journal located in directory. Any previously opened
9308 journal handle is closed.
9309 The contents of the journal can be read using "guestfs_journal_next"
9311 and "guestfs_journal_get".
9312 After you have finished using the journal, you should close the handle
9314 by calling "guestfs_journal_close".
9315 This function returns 0 on success or -1 on error.
9317 This function depends on the feature "journal". See also
9319 "guestfs_feature_available".
9320 (Added in 1.23.11)
9322 guestfs_journal_set_data_threshold
9324 int
9325 guestfs_journal_set_data_threshold (guestfs_h *g,
9326 int64_t threshold);
9327 Set the data threshold for reading journal entries. This is a hint to
9329 the journal that it may truncate data fields to this size when reading
9330 them (note also that it may not truncate them). If you set this to 0,
9331 then the threshold is unlimited.
9332 See also "guestfs_journal_get_data_threshold".
9334 This function returns 0 on success or -1 on error.
9336 This function depends on the feature "journal". See also
9338 "guestfs_feature_available".
9339 (Added in 1.23.11)
9341 guestfs_journal_skip
9343 int64_t
9344 guestfs_journal_skip (guestfs_h *g,
9345 int64_t skip);
9346 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9348 The number of entries actually skipped is returned (note "rskip ≥ 0").
9350 If this is not the same as the absolute value of the skip parameter
9351 ("|skip|") you passed in then it means you have reached the end or the
9352 start of the journal.
9353 On error this function returns -1.
9355 This function depends on the feature "journal". See also
9357 "guestfs_feature_available".
9358 (Added in 1.23.11)
9360 guestfs_kill_subprocess
9362 int
9363 guestfs_kill_subprocess (guestfs_h *g);
9364 This function is deprecated. In new code, use the "guestfs_shutdown"
9366 call instead.
9367 Deprecated functions will not be removed from the API, but the fact
9369 that they are deprecated indicates that there are problems with correct
9370 use of these functions.
9371 This kills the hypervisor.
9373 Do not call this. See: "guestfs_shutdown" instead.
9375 This function returns 0 on success or -1 on error.
9377 (Added in 0.3)
9379 guestfs_launch
9381 int
9382 guestfs_launch (guestfs_h *g);
9383 You should call this after configuring the handle (eg. adding drives)
9385 but before performing any actions.
9386 Do not call "guestfs_launch" twice on the same handle. Although it
9388 will not give an error (for historical reasons), the precise behaviour
9389 when you do this is not well defined. Handles are very cheap to
9390 create, so create a new one for each launch.
9391 This function returns 0 on success or -1 on error.
9393 This long-running command can generate progress notification messages
9395 so that the caller can display a progress bar or indicator. To receive
9396 these messages, the caller must register a progress event callback.
9397 See "GUESTFS_EVENT_PROGRESS".
9398 (Added in 0.3)
9400 guestfs_lchown
9402 int
9403 guestfs_lchown (guestfs_h *g,
9404 int owner,
9405 int group,
9406 const char *path);
9407 Change the file owner to "owner" and group to "group". This is like
9409 "guestfs_chown" but if "path" is a symlink then the link itself is
9410 changed, not the target.
9411 Only numeric uid and gid are supported. If you want to use names, you
9413 will need to locate and parse the password file yourself (Augeas
9414 support makes this relatively easy).
9415 This function returns 0 on success or -1 on error.
9417 (Added in 1.0.77)
9419 guestfs_ldmtool_create_all
9421 int
9422 guestfs_ldmtool_create_all (guestfs_h *g);
9423 This function scans all block devices looking for Windows dynamic disk
9425 volumes and partitions, and creates devices for any that were found.
9426 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9428 return all devices.
9429 Note that you don't normally need to call this explicitly, since it is
9431 done automatically at "guestfs_launch" time.
9432 This function returns 0 on success or -1 on error.
9434 This function depends on the feature "ldm". See also
9436 "guestfs_feature_available".
9437 (Added in 1.20.0)
9439 guestfs_ldmtool_diskgroup_disks
9441 char **
9442 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9443 const char *diskgroup);
9444 Return the disks in a Windows dynamic disk group. The "diskgroup"
9446 parameter should be the GUID of a disk group, one element from the list
9447 returned by "guestfs_ldmtool_scan".
9448 This function returns a NULL-terminated array of strings (like
9450 environ(3)), or NULL if there was an error. The caller must free the
9451 strings and the array after use.
9452 This function depends on the feature "ldm". See also
9454 "guestfs_feature_available".
9455 (Added in 1.20.0)
9457 guestfs_ldmtool_diskgroup_name
9459 char *
9460 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9461 const char *diskgroup);
9462 Return the name of a Windows dynamic disk group. The "diskgroup"
9464 parameter should be the GUID of a disk group, one element from the list
9465 returned by "guestfs_ldmtool_scan".
9466 This function returns a string, or NULL on error. The caller must free
9468 the returned string after use.
9469 This function depends on the feature "ldm". See also
9471 "guestfs_feature_available".
9472 (Added in 1.20.0)
9474 guestfs_ldmtool_diskgroup_volumes
9476 char **
9477 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9478 const char *diskgroup);
9479 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9481 parameter should be the GUID of a disk group, one element from the list
9482 returned by "guestfs_ldmtool_scan".
9483 This function returns a NULL-terminated array of strings (like
9485 environ(3)), or NULL if there was an error. The caller must free the
9486 strings and the array after use.
9487 This function depends on the feature "ldm". See also
9489 "guestfs_feature_available".
9490 (Added in 1.20.0)
9492 guestfs_ldmtool_remove_all
9494 int
9495 guestfs_ldmtool_remove_all (guestfs_h *g);
9496 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9498 removes the device mapper mappings for all Windows dynamic disk volumes
9499 This function returns 0 on success or -1 on error.
9501 This function depends on the feature "ldm". See also
9503 "guestfs_feature_available".
9504 (Added in 1.20.0)
9506 guestfs_ldmtool_scan
9508 char **
9509 guestfs_ldmtool_scan (guestfs_h *g);
9510 This function scans for Windows dynamic disks. It returns a list of
9512 identifiers (GUIDs) for all disk groups that were found. These
9513 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9514 This function scans all block devices. To scan a subset of block
9516 devices, call "guestfs_ldmtool_scan_devices" instead.
9517 This function returns a NULL-terminated array of strings (like
9519 environ(3)), or NULL if there was an error. The caller must free the
9520 strings and the array after use.
9521 This function depends on the feature "ldm". See also
9523 "guestfs_feature_available".
9524 (Added in 1.20.0)
9526 guestfs_ldmtool_scan_devices
9528 char **
9529 guestfs_ldmtool_scan_devices (guestfs_h *g,
9530 char *const *devices);
9531 This function scans for Windows dynamic disks. It returns a list of
9533 identifiers (GUIDs) for all disk groups that were found. These
9534 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9535 The parameter "devices" is a list of block devices which are scanned.
9537 If this list is empty, all block devices are scanned.
9538 This function returns a NULL-terminated array of strings (like
9540 environ(3)), or NULL if there was an error. The caller must free the
9541 strings and the array after use.
9542 This function depends on the feature "ldm". See also
9544 "guestfs_feature_available".
9545 (Added in 1.20.0)
9547 guestfs_ldmtool_volume_hint
9549 char *
9550 guestfs_ldmtool_volume_hint (guestfs_h *g,
9551 const char *diskgroup,
9552 const char *volume);
9553 Return the hint field of the volume named "volume" in the disk group
9555 with GUID "diskgroup". This may not be defined, in which case the
9556 empty string is returned. The hint field is often, though not always,
9557 the name of a Windows drive, eg. "E:".
9558 This function returns a string, or NULL on error. The caller must free
9560 the returned string after use.
9561 This function depends on the feature "ldm". See also
9563 "guestfs_feature_available".
9564 (Added in 1.20.0)
9566 guestfs_ldmtool_volume_partitions
9568 char **
9569 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9570 const char *diskgroup,
9571 const char *volume);
9572 Return the list of partitions in the volume named "volume" in the disk
9574 group with GUID "diskgroup".
9575 This function returns a NULL-terminated array of strings (like
9577 environ(3)), or NULL if there was an error. The caller must free the
9578 strings and the array after use.
9579 This function depends on the feature "ldm". See also
9581 "guestfs_feature_available".
9582 (Added in 1.20.0)
9584 guestfs_ldmtool_volume_type
9586 char *
9587 guestfs_ldmtool_volume_type (guestfs_h *g,
9588 const char *diskgroup,
9589 const char *volume);
9590 Return the type of the volume named "volume" in the disk group with
9592 GUID "diskgroup".
9593 Possible volume types that can be returned here include: "simple",
9595 "spanned", "striped", "mirrored", "raid5". Other types may also be
9596 returned.
9597 This function returns a string, or NULL on error. The caller must free
9599 the returned string after use.
9600 This function depends on the feature "ldm". See also
9602 "guestfs_feature_available".
9603 (Added in 1.20.0)
9605 guestfs_lgetxattr
9607 char *
9608 guestfs_lgetxattr (guestfs_h *g,
9609 const char *path,
9610 const char *name,
9611 size_t *size_r);
9612 Get a single extended attribute from file "path" named "name". If
9614 "path" is a symlink, then this call returns an extended attribute from
9615 the symlink.
9616 Normally it is better to get all extended attributes from a file in one
9618 go by calling "guestfs_getxattrs". However some Linux filesystem
9619 implementations are buggy and do not provide a way to list out
9620 attributes. For these filesystems (notably ntfs-3g) you have to know
9621 the names of the extended attributes you want in advance and call this
9622 function.
9623 Extended attribute values are blobs of binary data. If there is no
9625 extended attribute named "name", this returns an error.
9626 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9628 This function returns a buffer, or NULL on error. The size of the
9630 returned buffer is written to *size_r. The caller must free the
9631 returned buffer after use.
9632 This function depends on the feature "linuxxattrs". See also
9634 "guestfs_feature_available".
9635 (Added in 1.7.24)
9637 guestfs_lgetxattrs
9639 struct guestfs_xattr_list *
9640 guestfs_lgetxattrs (guestfs_h *g,
9641 const char *path);
9642 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9644 link, then it returns the extended attributes of the link itself.
9645 This function returns a "struct guestfs_xattr_list *", or NULL if there
9647 was an error. The caller must call "guestfs_free_xattr_list" after
9648 use.
9649 This function depends on the feature "linuxxattrs". See also
9651 "guestfs_feature_available".
9652 (Added in 1.0.59)
9654 guestfs_list_9p
9656 char **
9657 guestfs_list_9p (guestfs_h *g);
9658 This function is deprecated. There is no replacement. Consult the API
9660 documentation in guestfs(3) for further information.
9661 Deprecated functions will not be removed from the API, but the fact
9663 that they are deprecated indicates that there are problems with correct
9664 use of these functions.
9665 This call does nothing and returns an error.
9667 This function returns a NULL-terminated array of strings (like
9669 environ(3)), or NULL if there was an error. The caller must free the
9670 strings and the array after use.
9671 (Added in 1.11.12)
9673 guestfs_list_devices
9675 char **
9676 guestfs_list_devices (guestfs_h *g);
9677 List all the block devices.
9679 The full block device names are returned, eg. /dev/sda.
9681 See also "guestfs_list_filesystems".
9683 This function returns a NULL-terminated array of strings (like
9685 environ(3)), or NULL if there was an error. The caller must free the
9686 strings and the array after use.
9687 (Added in 0.4)
9689 guestfs_list_disk_labels
9691 char **
9692 guestfs_list_disk_labels (guestfs_h *g);
9693 If you add drives using the optional "label" parameter of
9695 "guestfs_add_drive_opts", you can use this call to map between disk
9696 labels, and raw block device and partition names (like /dev/sda and
9697 /dev/sda1).
9698 This returns a hashtable, where keys are the disk labels (without the
9700 /dev/disk/guestfs prefix), and the values are the full raw block device
9701 and partition names (eg. /dev/sda and /dev/sda1).
9702 This function returns a NULL-terminated array of strings, or NULL if
9704 there was an error. The array of strings will always have length
9705 "2n+1", where "n" keys and values alternate, followed by the trailing
9706 NULL entry. The caller must free the strings and the array after use.
9707 (Added in 1.19.49)
9709 guestfs_list_dm_devices
9711 char **
9712 guestfs_list_dm_devices (guestfs_h *g);
9713 List all device mapper devices.
9715 The returned list contains /dev/mapper/* devices, eg. ones created by a
9717 previous call to "guestfs_luks_open".
9718 Device mapper devices which correspond to logical volumes are not
9720 returned in this list. Call "guestfs_lvs" if you want to list logical
9721 volumes.
9722 This function returns a NULL-terminated array of strings (like
9724 environ(3)), or NULL if there was an error. The caller must free the
9725 strings and the array after use.
9726 (Added in 1.11.15)
9728 guestfs_list_filesystems
9730 char **
9731 guestfs_list_filesystems (guestfs_h *g);
9732 This inspection command looks for filesystems on partitions, block
9734 devices and logical volumes, returning a list of "mountables"
9735 containing filesystems and their type.
9736 The return value is a hash, where the keys are the devices containing
9738 filesystems, and the values are the filesystem types. For example:
9739 "/dev/sda1" => "ntfs"
9741 "/dev/sda2" => "ext2"
9742 "/dev/vg_guest/lv_root" => "ext4"
9743 "/dev/vg_guest/lv_swap" => "swap"
9744 The key is not necessarily a block device. It may also be an opaque
9746 ‘mountable’ string which can be passed to "guestfs_mount".
9747 The value can have the special value "unknown", meaning the content of
9749 the device is undetermined or empty. "swap" means a Linux swap
9750 partition.
9751 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9753 might have included "guestfs_mount" and "guestfs_umount", and therefore
9754 you had to use this soon after launch and only when nothing else was
9755 mounted. This restriction is removed in libguestfs ≥ 1.38.
9756 Not all of the filesystems returned will be mountable. In particular,
9758 swap partitions are returned in the list. Also this command does not
9759 check that each filesystem found is valid and mountable, and some
9760 filesystems might be mountable but require special options.
9761 Filesystems may not all belong to a single logical operating system
9762 (use "guestfs_inspect_os" to look for OSes).
9763 This function returns a NULL-terminated array of strings, or NULL if
9765 there was an error. The array of strings will always have length
9766 "2n+1", where "n" keys and values alternate, followed by the trailing
9767 NULL entry. The caller must free the strings and the array after use.
9768 (Added in 1.5.15)
9770 guestfs_list_ldm_partitions
9772 char **
9773 guestfs_list_ldm_partitions (guestfs_h *g);
9774 This function returns all Windows dynamic disk partitions that were
9776 found at launch time. It returns a list of device names.
9777 This function returns a NULL-terminated array of strings (like
9779 environ(3)), or NULL if there was an error. The caller must free the
9780 strings and the array after use.
9781 This function depends on the feature "ldm". See also
9783 "guestfs_feature_available".
9784 (Added in 1.20.0)
9786 guestfs_list_ldm_volumes
9788 char **
9789 guestfs_list_ldm_volumes (guestfs_h *g);
9790 This function returns all Windows dynamic disk volumes that were found
9792 at launch time. It returns a list of device names.
9793 This function returns a NULL-terminated array of strings (like
9795 environ(3)), or NULL if there was an error. The caller must free the
9796 strings and the array after use.
9797 This function depends on the feature "ldm". See also
9799 "guestfs_feature_available".
9800 (Added in 1.20.0)
9802 guestfs_list_md_devices
9804 char **
9805 guestfs_list_md_devices (guestfs_h *g);
9806 List all Linux md devices.
9808 This function returns a NULL-terminated array of strings (like
9810 environ(3)), or NULL if there was an error. The caller must free the
9811 strings and the array after use.
9812 (Added in 1.15.4)
9814 guestfs_list_partitions
9816 char **
9817 guestfs_list_partitions (guestfs_h *g);
9818 List all the partitions detected on all block devices.
9820 The full partition device names are returned, eg. /dev/sda1
9822 This does not return logical volumes. For that you will need to call
9824 "guestfs_lvs".
9825 See also "guestfs_list_filesystems".
9827 This function returns a NULL-terminated array of strings (like
9829 environ(3)), or NULL if there was an error. The caller must free the
9830 strings and the array after use.
9831 (Added in 0.4)
9833 guestfs_ll
9835 char *
9836 guestfs_ll (guestfs_h *g,
9837 const char *directory);
9838 List the files in directory (relative to the root directory, there is
9840 no cwd) in the format of "ls -la".
9841 This command is mostly useful for interactive sessions. It is not
9843 intended that you try to parse the output string.
9844 This function returns a string, or NULL on error. The caller must free
9846 the returned string after use.
9847 (Added in 0.4)
9849 guestfs_llz
9851 char *
9852 guestfs_llz (guestfs_h *g,
9853 const char *directory);
9854 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9856 call instead.
9857 Deprecated functions will not be removed from the API, but the fact
9859 that they are deprecated indicates that there are problems with correct
9860 use of these functions.
9861 List the files in directory in the format of "ls -laZ".
9863 This command is mostly useful for interactive sessions. It is not
9865 intended that you try to parse the output string.
9866 This function returns a string, or NULL on error. The caller must free
9868 the returned string after use.
9869 (Added in 1.17.6)
9871 guestfs_ln
9873 int
9874 guestfs_ln (guestfs_h *g,
9875 const char *target,
9876 const char *linkname);
9877 This command creates a hard link.
9879 This function returns 0 on success or -1 on error.
9881 (Added in 1.0.66)
9883 guestfs_ln_f
9885 int
9886 guestfs_ln_f (guestfs_h *g,
9887 const char *target,
9888 const char *linkname);
9889 This command creates a hard link, removing the link "linkname" if it
9891 exists already.
9892 This function returns 0 on success or -1 on error.
9894 (Added in 1.0.66)
9896 guestfs_ln_s
9898 int
9899 guestfs_ln_s (guestfs_h *g,
9900 const char *target,
9901 const char *linkname);
9902 This command creates a symbolic link using the "ln -s" command.
9904 This function returns 0 on success or -1 on error.
9906 (Added in 1.0.66)
9908 guestfs_ln_sf
9910 int
9911 guestfs_ln_sf (guestfs_h *g,
9912 const char *target,
9913 const char *linkname);
9914 This command creates a symbolic link using the "ln -sf" command, The -f
9916 option removes the link ("linkname") if it exists already.
9917 This function returns 0 on success or -1 on error.
9919 (Added in 1.0.66)
9921 guestfs_lremovexattr
9923 int
9924 guestfs_lremovexattr (guestfs_h *g,
9925 const char *xattr,
9926 const char *path);
9927 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9929 link, then it removes an extended attribute of the link itself.
9930 This function returns 0 on success or -1 on error.
9932 This function depends on the feature "linuxxattrs". See also
9934 "guestfs_feature_available".
9935 (Added in 1.0.59)
9937 guestfs_ls
9939 char **
9940 guestfs_ls (guestfs_h *g,
9941 const char *directory);
9942 List the files in directory (relative to the root directory, there is
9944 no cwd). The "." and ".." entries are not returned, but hidden files
9945 are shown.
9946 This function returns a NULL-terminated array of strings (like
9948 environ(3)), or NULL if there was an error. The caller must free the
9949 strings and the array after use.
9950 (Added in 0.4)
9952 guestfs_ls0
9954 int
9955 guestfs_ls0 (guestfs_h *g,
9956 const char *dir,
9957 const char *filenames);
9958 This specialized command is used to get a listing of the filenames in
9960 the directory "dir". The list of filenames is written to the local
9961 file filenames (on the host).
9962 In the output file, the filenames are separated by "\0" characters.
9964 "." and ".." are not returned. The filenames are not sorted.
9966 This function returns 0 on success or -1 on error.
9968 (Added in 1.19.32)
9970 guestfs_lsetxattr
9972 int
9973 guestfs_lsetxattr (guestfs_h *g,
9974 const char *xattr,
9975 const char *val,
9976 int vallen,
9977 const char *path);
9978 This is the same as "guestfs_setxattr", but if "path" is a symbolic
9980 link, then it sets an extended attribute of the link itself.
9981 This function returns 0 on success or -1 on error.
9983 This function depends on the feature "linuxxattrs". See also
9985 "guestfs_feature_available".
9986 (Added in 1.0.59)
9988 guestfs_lstat
9990 struct guestfs_stat *
9991 guestfs_lstat (guestfs_h *g,
9992 const char *path);
9993 This function is deprecated. In new code, use the "guestfs_lstatns"
9995 call instead.
9996 Deprecated functions will not be removed from the API, but the fact
9998 that they are deprecated indicates that there are problems with correct
9999 use of these functions.
10000 Returns file information for the given "path".
10002 This is the same as "guestfs_stat" except that if "path" is a symbolic
10004 link, then the link is stat-ed, not the file it refers to.
10005 This is the same as the lstat(2) system call.
10007 This function returns a "struct guestfs_stat *", or NULL if there was
10009 an error. The caller must call "guestfs_free_stat" after use.
10010 (Added in 1.9.2)
10012 guestfs_lstatlist
10014 struct guestfs_stat_list *
10015 guestfs_lstatlist (guestfs_h *g,
10016 const char *path,
10017 char *const *names);
10018 This function is deprecated. In new code, use the
10020 "guestfs_lstatnslist" call instead.
10021 Deprecated functions will not be removed from the API, but the fact
10023 that they are deprecated indicates that there are problems with correct
10024 use of these functions.
10025 This call allows you to perform the "guestfs_lstat" operation on
10027 multiple files, where all files are in the directory "path". "names"
10028 is the list of files from this directory.
10029 On return you get a list of stat structs, with a one-to-one
10031 correspondence to the "names" list. If any name did not exist or could
10032 not be lstat'd, then the "st_ino" field of that structure is set to -1.
10033 This call is intended for programs that want to efficiently list a
10035 directory contents without making many round-trips. See also
10036 "guestfs_lxattrlist" for a similarly efficient call for getting
10037 extended attributes.
10038 This function returns a "struct guestfs_stat_list *", or NULL if there
10040 was an error. The caller must call "guestfs_free_stat_list" after use.
10041 (Added in 1.0.77)
10043 guestfs_lstatns
10045 struct guestfs_statns *
10046 guestfs_lstatns (guestfs_h *g,
10047 const char *path);
10048 Returns file information for the given "path".
10050 This is the same as "guestfs_statns" except that if "path" is a
10052 symbolic link, then the link is stat-ed, not the file it refers to.
10053 This is the same as the lstat(2) system call.
10055 This function returns a "struct guestfs_statns *", or NULL if there was
10057 an error. The caller must call "guestfs_free_statns" after use.
10058 (Added in 1.27.53)
10060 guestfs_lstatnslist
10062 struct guestfs_statns_list *
10063 guestfs_lstatnslist (guestfs_h *g,
10064 const char *path,
10065 char *const *names);
10066 This call allows you to perform the "guestfs_lstatns" operation on
10068 multiple files, where all files are in the directory "path". "names"
10069 is the list of files from this directory.
10070 On return you get a list of stat structs, with a one-to-one
10072 correspondence to the "names" list. If any name did not exist or could
10073 not be lstat'd, then the "st_ino" field of that structure is set to -1.
10074 This call is intended for programs that want to efficiently list a
10076 directory contents without making many round-trips. See also
10077 "guestfs_lxattrlist" for a similarly efficient call for getting
10078 extended attributes.
10079 This function returns a "struct guestfs_statns_list *", or NULL if
10081 there was an error. The caller must call "guestfs_free_statns_list"
10082 after use.
10083 (Added in 1.27.53)
10085 guestfs_luks_add_key
10087 int
10088 guestfs_luks_add_key (guestfs_h *g,
10089 const char *device,
10090 const char *key,
10091 const char *newkey,
10092 int keyslot);
10093 This command adds a new key on LUKS device "device". "key" is any
10095 existing key, and is used to access the device. "newkey" is the new
10096 key to add. "keyslot" is the key slot that will be replaced.
10097 Note that if "keyslot" already contains a key, then this command will
10099 fail. You have to use "guestfs_luks_kill_slot" first to remove that
10100 key.
10101 This function returns 0 on success or -1 on error.
10103 This function takes a key or passphrase parameter which could contain
10105 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10106 information.
10107 This function depends on the feature "luks". See also
10109 "guestfs_feature_available".
10110 (Added in 1.5.2)
10112 guestfs_luks_close
10114 int
10115 guestfs_luks_close (guestfs_h *g,
10116 const char *device);
10117 This function is deprecated. In new code, use the
10119 "guestfs_cryptsetup_close" call instead.
10120 Deprecated functions will not be removed from the API, but the fact
10122 that they are deprecated indicates that there are problems with correct
10123 use of these functions.
10124 This closes a LUKS device that was created earlier by
10126 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
10127 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10128 and not the name of the underlying block device.
10129 This function returns 0 on success or -1 on error.
10131 This function depends on the feature "luks". See also
10133 "guestfs_feature_available".
10134 (Added in 1.5.1)
10136 guestfs_luks_format
10138 int
10139 guestfs_luks_format (guestfs_h *g,
10140 const char *device,
10141 const char *key,
10142 int keyslot);
10143 This command erases existing data on "device" and formats the device as
10145 a LUKS encrypted device. "key" is the initial key, which is added to
10146 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
10147 This function returns 0 on success or -1 on error.
10149 This function takes a key or passphrase parameter which could contain
10151 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10152 information.
10153 This function depends on the feature "luks". See also
10155 "guestfs_feature_available".
10156 (Added in 1.5.2)
10158 guestfs_luks_format_cipher
10160 int
10161 guestfs_luks_format_cipher (guestfs_h *g,
10162 const char *device,
10163 const char *key,
10164 int keyslot,
10165 const char *cipher);
10166 This command is the same as "guestfs_luks_format" but it also allows
10168 you to set the "cipher" used.
10169 This function returns 0 on success or -1 on error.
10171 This function takes a key or passphrase parameter which could contain
10173 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10174 information.
10175 This function depends on the feature "luks". See also
10177 "guestfs_feature_available".
10178 (Added in 1.5.2)
10180 guestfs_luks_kill_slot
10182 int
10183 guestfs_luks_kill_slot (guestfs_h *g,
10184 const char *device,
10185 const char *key,
10186 int keyslot);
10187 This command deletes the key in key slot "keyslot" from the encrypted
10189 LUKS device "device". "key" must be one of the other keys.
10190 This function returns 0 on success or -1 on error.
10192 This function takes a key or passphrase parameter which could contain
10194 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10195 information.
10196 This function depends on the feature "luks". See also
10198 "guestfs_feature_available".
10199 (Added in 1.5.2)
10201 guestfs_luks_open
10203 int
10204 guestfs_luks_open (guestfs_h *g,
10205 const char *device,
10206 const char *key,
10207 const char *mapname);
10208 This function is deprecated. In new code, use the
10210 "guestfs_cryptsetup_open" call instead.
10211 Deprecated functions will not be removed from the API, but the fact
10213 that they are deprecated indicates that there are problems with correct
10214 use of these functions.
10215 This command opens a block device which has been encrypted according to
10217 the Linux Unified Key Setup (LUKS) standard.
10218 "device" is the encrypted block device or partition.
10220 The caller must supply one of the keys associated with the LUKS block
10222 device, in the "key" parameter.
10223 This creates a new block device called /dev/mapper/mapname. Reads and
10225 writes to this block device are decrypted from and encrypted to the
10226 underlying "device" respectively.
10227 If this block device contains LVM volume groups, then calling
10229 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10230 visible.
10231 Use "guestfs_list_dm_devices" to list all device mapper devices.
10233 This function returns 0 on success or -1 on error.
10235 This function takes a key or passphrase parameter which could contain
10237 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10238 information.
10239 This function depends on the feature "luks". See also
10241 "guestfs_feature_available".
10242 (Added in 1.5.1)
10244 guestfs_luks_open_ro
10246 int
10247 guestfs_luks_open_ro (guestfs_h *g,
10248 const char *device,
10249 const char *key,
10250 const char *mapname);
10251 This function is deprecated. In new code, use the
10253 "guestfs_cryptsetup_open" call instead.
10254 Deprecated functions will not be removed from the API, but the fact
10256 that they are deprecated indicates that there are problems with correct
10257 use of these functions.
10258 This is the same as "guestfs_luks_open" except that a read-only mapping
10260 is created.
10261 This function returns 0 on success or -1 on error.
10263 This function takes a key or passphrase parameter which could contain
10265 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10266 information.
10267 This function depends on the feature "luks". See also
10269 "guestfs_feature_available".
10270 (Added in 1.5.1)
10272 guestfs_luks_uuid
10274 char *
10275 guestfs_luks_uuid (guestfs_h *g,
10276 const char *device);
10277 This returns the UUID of the LUKS device "device".
10279 This function returns a string, or NULL on error. The caller must free
10281 the returned string after use.
10282 This function depends on the feature "luks". See also
10284 "guestfs_feature_available".
10285 (Added in 1.41.9)
10287 guestfs_lvcreate
10289 int
10290 guestfs_lvcreate (guestfs_h *g,
10291 const char *logvol,
10292 const char *volgroup,
10293 int mbytes);
10294 This creates an LVM logical volume called "logvol" on the volume group
10296 "volgroup", with "size" megabytes.
10297 This function returns 0 on success or -1 on error.
10299 This function depends on the feature "lvm2". See also
10301 "guestfs_feature_available".
10302 (Added in 0.8)
10304 guestfs_lvcreate_free
10306 int
10307 guestfs_lvcreate_free (guestfs_h *g,
10308 const char *logvol,
10309 const char *volgroup,
10310 int percent);
10311 Create an LVM logical volume called /dev/volgroup/logvol, using
10313 approximately "percent" % of the free space remaining in the volume
10314 group. Most usefully, when "percent" is 100 this will create the
10315 largest possible LV.
10316 This function returns 0 on success or -1 on error.
10318 This function depends on the feature "lvm2". See also
10320 "guestfs_feature_available".
10321 (Added in 1.17.18)
10323 guestfs_lvm_canonical_lv_name
10325 char *
10326 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10327 const char *lvname);
10328 This converts alternative naming schemes for LVs that you might find to
10330 the canonical name. For example, /dev/mapper/VG-LV is converted to
10331 /dev/VG/LV.
10332 This command returns an error if the "lvname" parameter does not refer
10334 to a logical volume. In this case errno will be set to "EINVAL".
10335 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10337 This function returns a string, or NULL on error. The caller must free
10339 the returned string after use.
10340 (Added in 1.5.24)
10342 guestfs_lvm_clear_filter
10344 int
10345 guestfs_lvm_clear_filter (guestfs_h *g);
10346 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10348 to see every block device.
10349 This command also clears the LVM cache and performs a volume group
10351 scan.
10352 This function returns 0 on success or -1 on error.
10354 (Added in 1.5.1)
10356 guestfs_lvm_remove_all
10358 int
10359 guestfs_lvm_remove_all (guestfs_h *g);
10360 This command removes all LVM logical volumes, volume groups and
10362 physical volumes.
10363 This function returns 0 on success or -1 on error.
10365 This function depends on the feature "lvm2". See also
10367 "guestfs_feature_available".
10368 (Added in 0.8)
10370 guestfs_lvm_scan
10372 int
10373 guestfs_lvm_scan (guestfs_h *g,
10374 int activate);
10375 This scans all block devices and rebuilds the list of LVM physical
10377 volumes, volume groups and logical volumes.
10378 If the "activate" parameter is "true" then newly found volume groups
10380 and logical volumes are activated, meaning the LV /dev/VG/LV devices
10381 become visible.
10382 When a libguestfs handle is launched it scans for existing devices, so
10384 you do not normally need to use this API. However it is useful when
10385 you have added a new device or deleted an existing device (such as when
10386 the "guestfs_luks_open" API is used).
10387 This function returns 0 on success or -1 on error.
10389 (Added in 1.39.8)
10391 guestfs_lvm_set_filter
10393 int
10394 guestfs_lvm_set_filter (guestfs_h *g,
10395 char *const *devices);
10396 This sets the LVM device filter so that LVM will only be able to "see"
10398 the block devices in the list "devices", and will ignore all other
10399 attached block devices.
10400 Where disk image(s) contain duplicate PVs or VGs, this command is
10402 useful to get LVM to ignore the duplicates, otherwise LVM can get
10403 confused. Note also there are two types of duplication possible:
10404 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10405 cloned but just happen to have the same name. In normal operation you
10406 cannot create this situation, but you can do it outside LVM, eg. by
10407 cloning disk images or by bit twiddling inside the LVM metadata.
10408 This command also clears the LVM cache and performs a volume group
10410 scan.
10411 You can filter whole block devices or individual partitions.
10413 You cannot use this if any VG is currently in use (eg. contains a
10415 mounted filesystem), even if you are not filtering out that VG.
10416 This function returns 0 on success or -1 on error.
10418 This function depends on the feature "lvm2". See also
10420 "guestfs_feature_available".
10421 (Added in 1.5.1)
10423 guestfs_lvremove
10425 int
10426 guestfs_lvremove (guestfs_h *g,
10427 const char *device);
10428 Remove an LVM logical volume "device", where "device" is the path to
10430 the LV, such as /dev/VG/LV.
10431 You can also remove all LVs in a volume group by specifying the VG
10433 name, /dev/VG.
10434 This function returns 0 on success or -1 on error.
10436 This function depends on the feature "lvm2". See also
10438 "guestfs_feature_available".
10439 (Added in 1.0.13)
10441 guestfs_lvrename
10443 int
10444 guestfs_lvrename (guestfs_h *g,
10445 const char *logvol,
10446 const char *newlogvol);
10447 Rename a logical volume "logvol" with the new name "newlogvol".
10449 This function returns 0 on success or -1 on error.
10451 (Added in 1.0.83)
10453 guestfs_lvresize
10455 int
10456 guestfs_lvresize (guestfs_h *g,
10457 const char *device,
10458 int mbytes);
10459 This resizes (expands or shrinks) an existing LVM logical volume to
10461 "mbytes". When reducing, data in the reduced part is lost.
10462 This function returns 0 on success or -1 on error.
10464 This function depends on the feature "lvm2". See also
10466 "guestfs_feature_available".
10467 (Added in 1.0.27)
10469 guestfs_lvresize_free
10471 int
10472 guestfs_lvresize_free (guestfs_h *g,
10473 const char *lv,
10474 int percent);
10475 This expands an existing logical volume "lv" so that it fills "pc" % of
10477 the remaining free space in the volume group. Commonly you would call
10478 this with pc = 100 which expands the logical volume as much as
10479 possible, using all remaining free space in the volume group.
10480 This function returns 0 on success or -1 on error.
10482 This function depends on the feature "lvm2". See also
10484 "guestfs_feature_available".
10485 (Added in 1.3.3)
10487 guestfs_lvs
10489 char **
10490 guestfs_lvs (guestfs_h *g);
10491 List all the logical volumes detected. This is the equivalent of the
10493 lvs(8) command.
10494 This returns a list of the logical volume device names (eg.
10496 /dev/VolGroup00/LogVol00).
10497 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10499 This function returns a NULL-terminated array of strings (like
10501 environ(3)), or NULL if there was an error. The caller must free the
10502 strings and the array after use.
10503 This function depends on the feature "lvm2". See also
10505 "guestfs_feature_available".
10506 (Added in 0.4)
10508 guestfs_lvs_full
10510 struct guestfs_lvm_lv_list *
10511 guestfs_lvs_full (guestfs_h *g);
10512 List all the logical volumes detected. This is the equivalent of the
10514 lvs(8) command. The "full" version includes all fields.
10515 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10517 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10518 after use.
10519 This function depends on the feature "lvm2". See also
10521 "guestfs_feature_available".
10522 (Added in 0.4)
10524 guestfs_lvuuid
10526 char *
10527 guestfs_lvuuid (guestfs_h *g,
10528 const char *device);
10529 This command returns the UUID of the LVM LV "device".
10531 This function returns a string, or NULL on error. The caller must free
10533 the returned string after use.
10534 (Added in 1.0.87)
10536 guestfs_lxattrlist
10538 struct guestfs_xattr_list *
10539 guestfs_lxattrlist (guestfs_h *g,
10540 const char *path,
10541 char *const *names);
10542 This call allows you to get the extended attributes of multiple files,
10544 where all files are in the directory "path". "names" is the list of
10545 files from this directory.
10546 On return you get a flat list of xattr structs which must be
10548 interpreted sequentially. The first xattr struct always has a zero-
10549 length "attrname". "attrval" in this struct is zero-length to indicate
10550 there was an error doing "guestfs_lgetxattr" for this file, or is a C
10551 string which is a decimal number (the number of following attributes
10552 for this file, which could be "0"). Then after the first xattr struct
10553 are the zero or more attributes for the first named file. This repeats
10554 for the second and subsequent files.
10555 This call is intended for programs that want to efficiently list a
10557 directory contents without making many round-trips. See also
10558 "guestfs_lstatlist" for a similarly efficient call for getting standard
10559 stats.
10560 This function returns a "struct guestfs_xattr_list *", or NULL if there
10562 was an error. The caller must call "guestfs_free_xattr_list" after
10563 use.
10564 This function depends on the feature "linuxxattrs". See also
10566 "guestfs_feature_available".
10567 (Added in 1.0.77)
10569 guestfs_max_disks
10571 int
10572 guestfs_max_disks (guestfs_h *g);
10573 Return the maximum number of disks that may be added to a handle (eg.
10575 by "guestfs_add_drive_opts" and similar calls).
10576 This function was added in libguestfs 1.19.7. In previous versions of
10578 libguestfs the limit was 25.
10579 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10581 On error this function returns -1.
10583 (Added in 1.19.7)
10585 guestfs_md_create
10587 int
10588 guestfs_md_create (guestfs_h *g,
10589 const char *name,
10590 char *const *devices,
10591 ...);
10592 You may supply a list of optional arguments to this call. Use zero or
10594 more of the following pairs of parameters, and terminate the list with
10595 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10596 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10598 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10599 GUESTFS_MD_CREATE_SPARE, int spare,
10600 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10601 GUESTFS_MD_CREATE_LEVEL, const char *level,
10602 Create a Linux md (RAID) device named "name" on the devices in the list
10604 "devices".
10605 The optional parameters are:
10607 "missingbitmap"
10609 A bitmap of missing devices. If a bit is set it means that a
10610 missing device is added to the array. The least significant bit
10611 corresponds to the first device in the array.
10612 As examples:
10614 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10616 resulting array would be "[<missing>, "/dev/sda"]".
10617 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10619 resulting array would be "["/dev/sda", <missing>]".
10620 This defaults to 0 (no missing devices).
10622 The length of "devices" + the number of bits set in "missingbitmap"
10624 must equal "nrdevices" + "spare".
10625 "nrdevices"
10627 The number of active RAID devices.
10628 If not set, this defaults to the length of "devices" plus the
10630 number of bits set in "missingbitmap".
10631 "spare"
10633 The number of spare devices.
10634 If not set, this defaults to 0.
10636 "chunk"
10638 The chunk size in bytes.
10639 The "chunk" parameter does not make sense, and should not be
10641 specified, when "level" is "raid1" (which is the default; see
10642 below).
10643 "level"
10645 The RAID level, which can be one of: "linear", "raid0", 0,
10646 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
10647 "raid10", 10. Some of these are synonymous, and more levels may be
10648 added in future.
10649 If not set, this defaults to "raid1".
10651 This function returns 0 on success or -1 on error.
10653 This function depends on the feature "mdadm". See also
10655 "guestfs_feature_available".
10656 (Added in 1.15.6)
10658 guestfs_md_create_va
10660 int
10661 guestfs_md_create_va (guestfs_h *g,
10662 const char *name,
10663 char *const *devices,
10664 va_list args);
10665 This is the "va_list variant" of "guestfs_md_create".
10667 See "CALLS WITH OPTIONAL ARGUMENTS".
10669 guestfs_md_create_argv
10671 int
10672 guestfs_md_create_argv (guestfs_h *g,
10673 const char *name,
10674 char *const *devices,
10675 const struct guestfs_md_create_argv *optargs);
10676 This is the "argv variant" of "guestfs_md_create".
10678 See "CALLS WITH OPTIONAL ARGUMENTS".
10680 guestfs_md_detail
10682 char **
10683 guestfs_md_detail (guestfs_h *g,
10684 const char *md);
10685 This command exposes the output of "mdadm -DY <md>". The following
10687 fields are usually present in the returned hash. Other fields may also
10688 be present.
10689 "level"
10691 The raid level of the MD device.
10692 "devices"
10694 The number of underlying devices in the MD device.
10695 "metadata"
10697 The metadata version used.
10698 "uuid"
10700 The UUID of the MD device.
10701 "name"
10703 The name of the MD device.
10704 This function returns a NULL-terminated array of strings, or NULL if
10706 there was an error. The array of strings will always have length
10707 "2n+1", where "n" keys and values alternate, followed by the trailing
10708 NULL entry. The caller must free the strings and the array after use.
10709 This function depends on the feature "mdadm". See also
10711 "guestfs_feature_available".
10712 (Added in 1.15.6)
10714 guestfs_md_stat
10716 struct guestfs_mdstat_list *
10717 guestfs_md_stat (guestfs_h *g,
10718 const char *md);
10719 This call returns a list of the underlying devices which make up the
10721 single software RAID array device "md".
10722 To get a list of software RAID devices, call "guestfs_list_md_devices".
10724 Each structure returned corresponds to one device along with additional
10726 status information:
10727 "mdstat_device"
10729 The name of the underlying device.
10730 "mdstat_index"
10732 The index of this device within the array.
10733 "mdstat_flags"
10735 Flags associated with this device. This is a string containing (in
10736 no specific order) zero or more of the following flags:
10737 "W" write-mostly
10739 "F" device is faulty
10741 "S" device is a RAID spare
10743 "R" replacement
10745 This function returns a "struct guestfs_mdstat_list *", or NULL if
10747 there was an error. The caller must call "guestfs_free_mdstat_list"
10748 after use.
10749 This function depends on the feature "mdadm". See also
10751 "guestfs_feature_available".
10752 (Added in 1.17.21)
10754 guestfs_md_stop
10756 int
10757 guestfs_md_stop (guestfs_h *g,
10758 const char *md);
10759 This command deactivates the MD array named "md". The device is
10761 stopped, but it is not destroyed or zeroed.
10762 This function returns 0 on success or -1 on error.
10764 This function depends on the feature "mdadm". See also
10766 "guestfs_feature_available".
10767 (Added in 1.15.6)
10769 guestfs_mkdir
10771 int
10772 guestfs_mkdir (guestfs_h *g,
10773 const char *path);
10774 Create a directory named "path".
10776 This function returns 0 on success or -1 on error.
10778 (Added in 0.8)
10780 guestfs_mkdir_mode
10782 int
10783 guestfs_mkdir_mode (guestfs_h *g,
10784 const char *path,
10785 int mode);
10786 This command creates a directory, setting the initial permissions of
10788 the directory to "mode".
10789 For common Linux filesystems, the actual mode which is set will be
10791 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10792 the mode in other ways.
10793 See also "guestfs_mkdir", "guestfs_umask"
10795 This function returns 0 on success or -1 on error.
10797 (Added in 1.0.77)
10799 guestfs_mkdir_p
10801 int
10802 guestfs_mkdir_p (guestfs_h *g,
10803 const char *path);
10804 Create a directory named "path", creating any parent directories as
10806 necessary. This is like the "mkdir -p" shell command.
10807 This function returns 0 on success or -1 on error.
10809 (Added in 0.8)
10811 guestfs_mkdtemp
10813 char *
10814 guestfs_mkdtemp (guestfs_h *g,
10815 const char *tmpl);
10816 This command creates a temporary directory. The "tmpl" parameter
10818 should be a full pathname for the temporary directory name with the
10819 final six characters being "XXXXXX".
10820 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10822 one being suitable for Windows filesystems.
10823 The name of the temporary directory that was created is returned.
10825 The temporary directory is created with mode 0700 and is owned by root.
10827 The caller is responsible for deleting the temporary directory and its
10829 contents after use.
10830 See also: mkdtemp(3)
10832 This function returns a string, or NULL on error. The caller must free
10834 the returned string after use.
10835 (Added in 1.0.54)
10837 guestfs_mke2fs
10839 int
10840 guestfs_mke2fs (guestfs_h *g,
10841 const char *device,
10842 ...);
10843 You may supply a list of optional arguments to this call. Use zero or
10845 more of the following pairs of parameters, and terminate the list with
10846 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10847 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10849 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10850 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10851 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10852 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10853 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10854 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10855 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10856 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10857 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10858 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10859 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10860 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10861 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10862 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10863 GUESTFS_MKE2FS_LABEL, const char *label,
10864 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10865 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10866 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10867 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10868 GUESTFS_MKE2FS_UUID, const char *uuid,
10869 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10870 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10871 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10872 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10873 GUESTFS_MKE2FS_TESTFS, int testfs,
10874 GUESTFS_MKE2FS_DISCARD, int discard,
10875 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10876 GUESTFS_MKE2FS_EXTENT, int extent,
10877 GUESTFS_MKE2FS_FILETYPE, int filetype,
10878 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10879 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10880 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10881 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10882 GUESTFS_MKE2FS_QUOTA, int quota,
10883 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10884 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10885 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10886 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10888 "device".
10889 The optional "blockscount" is the size of the filesystem in blocks. If
10891 omitted it defaults to the size of "device". Note if the filesystem is
10892 too small to contain a journal, "mke2fs" will silently create an ext2
10893 filesystem instead.
10894 This function returns 0 on success or -1 on error.
10896 (Added in 1.19.44)
10898 guestfs_mke2fs_va
10900 int
10901 guestfs_mke2fs_va (guestfs_h *g,
10902 const char *device,
10903 va_list args);
10904 This is the "va_list variant" of "guestfs_mke2fs".
10906 See "CALLS WITH OPTIONAL ARGUMENTS".
10908 guestfs_mke2fs_argv
10910 int
10911 guestfs_mke2fs_argv (guestfs_h *g,
10912 const char *device,
10913 const struct guestfs_mke2fs_argv *optargs);
10914 This is the "argv variant" of "guestfs_mke2fs".
10916 See "CALLS WITH OPTIONAL ARGUMENTS".
10918 guestfs_mke2fs_J
10920 int
10921 guestfs_mke2fs_J (guestfs_h *g,
10922 const char *fstype,
10923 int blocksize,
10924 const char *device,
10925 const char *journal);
10926 This function is deprecated. In new code, use the "guestfs_mke2fs"
10928 call instead.
10929 Deprecated functions will not be removed from the API, but the fact
10931 that they are deprecated indicates that there are problems with correct
10932 use of these functions.
10933 This creates an ext2/3/4 filesystem on "device" with an external
10935 journal on "journal". It is equivalent to the command:
10936 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10938 See also "guestfs_mke2journal".
10940 This function returns 0 on success or -1 on error.
10942 (Added in 1.0.68)
10944 guestfs_mke2fs_JL
10946 int
10947 guestfs_mke2fs_JL (guestfs_h *g,
10948 const char *fstype,
10949 int blocksize,
10950 const char *device,
10951 const char *label);
10952 This function is deprecated. In new code, use the "guestfs_mke2fs"
10954 call instead.
10955 Deprecated functions will not be removed from the API, but the fact
10957 that they are deprecated indicates that there are problems with correct
10958 use of these functions.
10959 This creates an ext2/3/4 filesystem on "device" with an external
10961 journal on the journal labeled "label".
10962 See also "guestfs_mke2journal_L".
10964 This function returns 0 on success or -1 on error.
10966 (Added in 1.0.68)
10968 guestfs_mke2fs_JU
10970 int
10971 guestfs_mke2fs_JU (guestfs_h *g,
10972 const char *fstype,
10973 int blocksize,
10974 const char *device,
10975 const char *uuid);
10976 This function is deprecated. In new code, use the "guestfs_mke2fs"
10978 call instead.
10979 Deprecated functions will not be removed from the API, but the fact
10981 that they are deprecated indicates that there are problems with correct
10982 use of these functions.
10983 This creates an ext2/3/4 filesystem on "device" with an external
10985 journal on the journal with UUID "uuid".
10986 See also "guestfs_mke2journal_U".
10988 This function returns 0 on success or -1 on error.
10990 This function depends on the feature "linuxfsuuid". See also
10992 "guestfs_feature_available".
10993 (Added in 1.0.68)
10995 guestfs_mke2journal
10997 int
10998 guestfs_mke2journal (guestfs_h *g,
10999 int blocksize,
11000 const char *device);
11001 This function is deprecated. In new code, use the "guestfs_mke2fs"
11003 call instead.
11004 Deprecated functions will not be removed from the API, but the fact
11006 that they are deprecated indicates that there are problems with correct
11007 use of these functions.
11008 This creates an ext2 external journal on "device". It is equivalent to
11010 the command:
11011 mke2fs -O journal_dev -b blocksize device
11013 This function returns 0 on success or -1 on error.
11015 (Added in 1.0.68)
11017 guestfs_mke2journal_L
11019 int
11020 guestfs_mke2journal_L (guestfs_h *g,
11021 int blocksize,
11022 const char *label,
11023 const char *device);
11024 This function is deprecated. In new code, use the "guestfs_mke2fs"
11026 call instead.
11027 Deprecated functions will not be removed from the API, but the fact
11029 that they are deprecated indicates that there are problems with correct
11030 use of these functions.
11031 This creates an ext2 external journal on "device" with label "label".
11033 This function returns 0 on success or -1 on error.
11035 (Added in 1.0.68)
11037 guestfs_mke2journal_U
11039 int
11040 guestfs_mke2journal_U (guestfs_h *g,
11041 int blocksize,
11042 const char *uuid,
11043 const char *device);
11044 This function is deprecated. In new code, use the "guestfs_mke2fs"
11046 call instead.
11047 Deprecated functions will not be removed from the API, but the fact
11049 that they are deprecated indicates that there are problems with correct
11050 use of these functions.
11051 This creates an ext2 external journal on "device" with UUID "uuid".
11053 This function returns 0 on success or -1 on error.
11055 This function depends on the feature "linuxfsuuid". See also
11057 "guestfs_feature_available".
11058 (Added in 1.0.68)
11060 guestfs_mkfifo
11062 int
11063 guestfs_mkfifo (guestfs_h *g,
11064 int mode,
11065 const char *path);
11066 This call creates a FIFO (named pipe) called "path" with mode "mode".
11068 It is just a convenient wrapper around "guestfs_mknod".
11069 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11071 The mode actually set is affected by the umask.
11073 This function returns 0 on success or -1 on error.
11075 This function depends on the feature "mknod". See also
11077 "guestfs_feature_available".
11078 (Added in 1.0.55)
11080 guestfs_mkfs
11082 int
11083 guestfs_mkfs (guestfs_h *g,
11084 const char *fstype,
11085 const char *device);
11086 This function is provided for backwards compatibility with earlier
11088 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
11089 optional arguments.
11090 (Added in 0.8)
11092 guestfs_mkfs_opts
11094 int
11095 guestfs_mkfs_opts (guestfs_h *g,
11096 const char *fstype,
11097 const char *device,
11098 ...);
11099 You may supply a list of optional arguments to this call. Use zero or
11101 more of the following pairs of parameters, and terminate the list with
11102 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11103 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
11105 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
11106 GUESTFS_MKFS_OPTS_INODE, int inode,
11107 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
11108 GUESTFS_MKFS_OPTS_LABEL, const char *label,
11109 This function creates a filesystem on "device". The filesystem type is
11111 "fstype", for example "ext3".
11112 The optional arguments are:
11114 "blocksize"
11116 The filesystem block size. Supported block sizes depend on the
11117 filesystem type, but typically they are 1024, 2048 or 4096 for
11118 Linux ext2/3 filesystems.
11119 For VFAT and NTFS the "blocksize" parameter is treated as the
11121 requested cluster size.
11122 For UFS block sizes, please see mkfs.ufs(8).
11124 "features"
11126 This passes the -O parameter to the external mkfs program.
11127 For certain filesystem types, this allows extra filesystem features
11129 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
11130 You cannot use this optional parameter with the "gfs" or "gfs2"
11132 filesystem type.
11133 "inode"
11135 This passes the -I parameter to the external mke2fs(8) program
11136 which sets the inode size (only for ext2/3/4 filesystems at
11137 present).
11138 "sectorsize"
11140 This passes the -S parameter to external mkfs.ufs(8) program, which
11141 sets sector size for ufs filesystem.
11142 This function returns 0 on success or -1 on error.
11144 (Added in 0.8)
11146 guestfs_mkfs_opts_va
11148 int
11149 guestfs_mkfs_opts_va (guestfs_h *g,
11150 const char *fstype,
11151 const char *device,
11152 va_list args);
11153 This is the "va_list variant" of "guestfs_mkfs_opts".
11155 See "CALLS WITH OPTIONAL ARGUMENTS".
11157 guestfs_mkfs_opts_argv
11159 int
11160 guestfs_mkfs_opts_argv (guestfs_h *g,
11161 const char *fstype,
11162 const char *device,
11163 const struct guestfs_mkfs_opts_argv *optargs);
11164 This is the "argv variant" of "guestfs_mkfs_opts".
11166 See "CALLS WITH OPTIONAL ARGUMENTS".
11168 guestfs_mkfs_b
11170 int
11171 guestfs_mkfs_b (guestfs_h *g,
11172 const char *fstype,
11173 int blocksize,
11174 const char *device);
11175 This function is deprecated. In new code, use the "guestfs_mkfs" call
11177 instead.
11178 Deprecated functions will not be removed from the API, but the fact
11180 that they are deprecated indicates that there are problems with correct
11181 use of these functions.
11182 This call is similar to "guestfs_mkfs", but it allows you to control
11184 the block size of the resulting filesystem. Supported block sizes
11185 depend on the filesystem type, but typically they are 1024, 2048 or
11186 4096 only.
11187 For VFAT and NTFS the "blocksize" parameter is treated as the requested
11189 cluster size.
11190 This function returns 0 on success or -1 on error.
11192 (Added in 1.0.68)
11194 guestfs_mkfs_btrfs
11196 int
11197 guestfs_mkfs_btrfs (guestfs_h *g,
11198 char *const *devices,
11199 ...);
11200 You may supply a list of optional arguments to this call. Use zero or
11202 more of the following pairs of parameters, and terminate the list with
11203 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11204 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11206 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11207 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11208 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11209 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11210 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11211 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11212 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11213 Create a btrfs filesystem, allowing all configurables to be set. For
11215 more information on the optional arguments, see mkfs.btrfs(8).
11216 Since btrfs filesystems can span multiple devices, this takes a non-
11218 empty list of devices.
11219 To create general filesystems, use "guestfs_mkfs".
11221 This function returns 0 on success or -1 on error.
11223 This function depends on the feature "btrfs". See also
11225 "guestfs_feature_available".
11226 (Added in 1.17.25)
11228 guestfs_mkfs_btrfs_va
11230 int
11231 guestfs_mkfs_btrfs_va (guestfs_h *g,
11232 char *const *devices,
11233 va_list args);
11234 This is the "va_list variant" of "guestfs_mkfs_btrfs".
11236 See "CALLS WITH OPTIONAL ARGUMENTS".
11238 guestfs_mkfs_btrfs_argv
11240 int
11241 guestfs_mkfs_btrfs_argv (guestfs_h *g,
11242 char *const *devices,
11243 const struct guestfs_mkfs_btrfs_argv *optargs);
11244 This is the "argv variant" of "guestfs_mkfs_btrfs".
11246 See "CALLS WITH OPTIONAL ARGUMENTS".
11248 guestfs_mklost_and_found
11250 int
11251 guestfs_mklost_and_found (guestfs_h *g,
11252 const char *mountpoint);
11253 Make the "lost+found" directory, normally in the root directory of an
11255 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
11256 to create the "lost+found" directory.
11257 This function returns 0 on success or -1 on error.
11259 (Added in 1.19.56)
11261 guestfs_mkmountpoint
11263 int
11264 guestfs_mkmountpoint (guestfs_h *g,
11265 const char *exemptpath);
11266 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11268 that can be used to create extra mountpoints before mounting the first
11269 filesystem.
11270 These calls are only necessary in some very limited circumstances,
11272 mainly the case where you want to mount a mix of unrelated and/or read-
11273 only filesystems together.
11274 For example, live CDs often contain a "Russian doll" nest of
11276 filesystems, an ISO outer layer, with a squashfs image inside, with an
11277 ext2/3 image inside that. You can unpack this as follows in guestfish:
11278 add-ro Fedora-11-i686-Live.iso
11280 run
11281 mkmountpoint /cd
11282 mkmountpoint /sqsh
11283 mkmountpoint /ext3fs
11284 mount /dev/sda /cd
11285 mount-loop /cd/LiveOS/squashfs.img /sqsh
11286 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11287 The inner filesystem is now unpacked under the /ext3fs mountpoint.
11289 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11291 You may get unexpected errors if you try to mix these calls. It is
11292 safest to manually unmount filesystems and remove mountpoints after
11293 use.
11294 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11296 first, so for this to work for manual mountpoints, you must ensure that
11297 the innermost mountpoints have the longest pathnames, as in the example
11298 code above.
11299 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11301 Autosync [see "guestfs_set_autosync", this is set by default on
11303 handles] can cause "guestfs_umount_all" to be called when the handle is
11304 closed which can also trigger these issues.
11305 This function returns 0 on success or -1 on error.
11307 (Added in 1.0.62)
11309 guestfs_mknod
11311 int
11312 guestfs_mknod (guestfs_h *g,
11313 int mode,
11314 int devmajor,
11315 int devminor,
11316 const char *path);
11317 This call creates block or character special devices, or named pipes
11319 (FIFOs).
11320 The "mode" parameter should be the mode, using the standard constants.
11322 "devmajor" and "devminor" are the device major and minor numbers, only
11323 used when creating block and character special devices.
11324 Note that, just like mknod(2), the mode must be bitwise OR'd with
11326 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11327 a regular file). These constants are available in the standard Linux
11328 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11329 "guestfs_mkfifo" which are wrappers around this command which bitwise
11330 OR in the appropriate constant for you.
11331 The mode actually set is affected by the umask.
11333 This function returns 0 on success or -1 on error.
11335 This function depends on the feature "mknod". See also
11337 "guestfs_feature_available".
11338 (Added in 1.0.55)
11340 guestfs_mknod_b
11342 int
11343 guestfs_mknod_b (guestfs_h *g,
11344 int mode,
11345 int devmajor,
11346 int devminor,
11347 const char *path);
11348 This call creates a block device node called "path" with mode "mode"
11350 and device major/minor "devmajor" and "devminor". It is just a
11351 convenient wrapper around "guestfs_mknod".
11352 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11354 The mode actually set is affected by the umask.
11356 This function returns 0 on success or -1 on error.
11358 This function depends on the feature "mknod". See also
11360 "guestfs_feature_available".
11361 (Added in 1.0.55)
11363 guestfs_mknod_c
11365 int
11366 guestfs_mknod_c (guestfs_h *g,
11367 int mode,
11368 int devmajor,
11369 int devminor,
11370 const char *path);
11371 This call creates a char device node called "path" with mode "mode" and
11373 device major/minor "devmajor" and "devminor". It is just a convenient
11374 wrapper around "guestfs_mknod".
11375 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11377 The mode actually set is affected by the umask.
11379 This function returns 0 on success or -1 on error.
11381 This function depends on the feature "mknod". See also
11383 "guestfs_feature_available".
11384 (Added in 1.0.55)
11386 guestfs_mksquashfs
11388 int
11389 guestfs_mksquashfs (guestfs_h *g,
11390 const char *path,
11391 const char *filename,
11392 ...);
11393 You may supply a list of optional arguments to this call. Use zero or
11395 more of the following pairs of parameters, and terminate the list with
11396 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11397 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11399 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11400 Create a squashfs filesystem for the specified "path".
11402 The optional "compress" flag controls compression. If not given, then
11404 the output compressed using "gzip". Otherwise one of the following
11405 strings may be given to select the compression type of the squashfs:
11406 "gzip", "lzma", "lzo", "lz4", "xz".
11407 The other optional arguments are:
11409 "excludes"
11411 A list of wildcards. Files are excluded if they match any of the
11412 wildcards.
11413 Please note that this API may fail when used to compress directories
11415 with large files, such as the resulting squashfs will be over 3GB big.
11416 This function returns 0 on success or -1 on error.
11418 This function depends on the feature "squashfs". See also
11420 "guestfs_feature_available".
11421 (Added in 1.35.25)
11423 guestfs_mksquashfs_va
11425 int
11426 guestfs_mksquashfs_va (guestfs_h *g,
11427 const char *path,
11428 const char *filename,
11429 va_list args);
11430 This is the "va_list variant" of "guestfs_mksquashfs".
11432 See "CALLS WITH OPTIONAL ARGUMENTS".
11434 guestfs_mksquashfs_argv
11436 int
11437 guestfs_mksquashfs_argv (guestfs_h *g,
11438 const char *path,
11439 const char *filename,
11440 const struct guestfs_mksquashfs_argv *optargs);
11441 This is the "argv variant" of "guestfs_mksquashfs".
11443 See "CALLS WITH OPTIONAL ARGUMENTS".
11445 guestfs_mkswap
11447 int
11448 guestfs_mkswap (guestfs_h *g,
11449 const char *device);
11450 This function is provided for backwards compatibility with earlier
11452 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11453 optional arguments.
11454 (Added in 1.0.55)
11456 guestfs_mkswap_opts
11458 int
11459 guestfs_mkswap_opts (guestfs_h *g,
11460 const char *device,
11461 ...);
11462 You may supply a list of optional arguments to this call. Use zero or
11464 more of the following pairs of parameters, and terminate the list with
11465 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11466 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11468 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11469 Create a Linux swap partition on "device".
11471 The option arguments "label" and "uuid" allow you to set the label
11473 and/or UUID of the new swap partition.
11474 This function returns 0 on success or -1 on error.
11476 (Added in 1.0.55)
11478 guestfs_mkswap_opts_va
11480 int
11481 guestfs_mkswap_opts_va (guestfs_h *g,
11482 const char *device,
11483 va_list args);
11484 This is the "va_list variant" of "guestfs_mkswap_opts".
11486 See "CALLS WITH OPTIONAL ARGUMENTS".
11488 guestfs_mkswap_opts_argv
11490 int
11491 guestfs_mkswap_opts_argv (guestfs_h *g,
11492 const char *device,
11493 const struct guestfs_mkswap_opts_argv *optargs);
11494 This is the "argv variant" of "guestfs_mkswap_opts".
11496 See "CALLS WITH OPTIONAL ARGUMENTS".
11498 guestfs_mkswap_L
11500 int
11501 guestfs_mkswap_L (guestfs_h *g,
11502 const char *label,
11503 const char *device);
11504 This function is deprecated. In new code, use the "guestfs_mkswap"
11506 call instead.
11507 Deprecated functions will not be removed from the API, but the fact
11509 that they are deprecated indicates that there are problems with correct
11510 use of these functions.
11511 Create a swap partition on "device" with label "label".
11513 Note that you cannot attach a swap label to a block device (eg.
11515 /dev/sda), just to a partition. This appears to be a limitation of the
11516 kernel or swap tools.
11517 This function returns 0 on success or -1 on error.
11519 (Added in 1.0.55)
11521 guestfs_mkswap_U
11523 int
11524 guestfs_mkswap_U (guestfs_h *g,
11525 const char *uuid,
11526 const char *device);
11527 This function is deprecated. In new code, use the "guestfs_mkswap"
11529 call instead.
11530 Deprecated functions will not be removed from the API, but the fact
11532 that they are deprecated indicates that there are problems with correct
11533 use of these functions.
11534 Create a swap partition on "device" with UUID "uuid".
11536 This function returns 0 on success or -1 on error.
11538 This function depends on the feature "linuxfsuuid". See also
11540 "guestfs_feature_available".
11541 (Added in 1.0.55)
11543 guestfs_mkswap_file
11545 int
11546 guestfs_mkswap_file (guestfs_h *g,
11547 const char *path);
11548 Create a swap file.
11550 This command just writes a swap file signature to an existing file. To
11552 create the file itself, use something like "guestfs_fallocate".
11553 This function returns 0 on success or -1 on error.
11555 (Added in 1.0.66)
11557 guestfs_mktemp
11559 char *
11560 guestfs_mktemp (guestfs_h *g,
11561 const char *tmpl,
11562 ...);
11563 You may supply a list of optional arguments to this call. Use zero or
11565 more of the following pairs of parameters, and terminate the list with
11566 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11567 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11569 This command creates a temporary file. The "tmpl" parameter should be
11571 a full pathname for the temporary directory name with the final six
11572 characters being "XXXXXX".
11573 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11575 one being suitable for Windows filesystems.
11576 The name of the temporary file that was created is returned.
11578 The temporary file is created with mode 0600 and is owned by root.
11580 The caller is responsible for deleting the temporary file after use.
11582 If the optional "suffix" parameter is given, then the suffix (eg.
11584 ".txt") is appended to the temporary name.
11585 See also: "guestfs_mkdtemp".
11587 This function returns a string, or NULL on error. The caller must free
11589 the returned string after use.
11590 (Added in 1.19.53)
11592 guestfs_mktemp_va
11594 char *
11595 guestfs_mktemp_va (guestfs_h *g,
11596 const char *tmpl,
11597 va_list args);
11598 This is the "va_list variant" of "guestfs_mktemp".
11600 See "CALLS WITH OPTIONAL ARGUMENTS".
11602 guestfs_mktemp_argv
11604 char *
11605 guestfs_mktemp_argv (guestfs_h *g,
11606 const char *tmpl,
11607 const struct guestfs_mktemp_argv *optargs);
11608 This is the "argv variant" of "guestfs_mktemp".
11610 See "CALLS WITH OPTIONAL ARGUMENTS".
11612 guestfs_modprobe
11614 int
11615 guestfs_modprobe (guestfs_h *g,
11616 const char *modulename);
11617 This loads a kernel module in the appliance.
11619 This function returns 0 on success or -1 on error.
11621 This function depends on the feature "linuxmodules". See also
11623 "guestfs_feature_available".
11624 (Added in 1.0.68)
11626 guestfs_mount
11628 int
11629 guestfs_mount (guestfs_h *g,
11630 const char *mountable,
11631 const char *mountpoint);
11632 Mount a guest disk at a position in the filesystem. Block devices are
11634 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11635 If those block devices contain partitions, they will have the usual
11636 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11637 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11638 "guestfs_inspect_get_mountpoints".
11639 The rules are the same as for mount(2): A filesystem must first be
11641 mounted on / before others can be mounted. Other filesystems can only
11642 be mounted on directories which already exist.
11643 The mounted filesystem is writable, if we have sufficient permissions
11645 on the underlying device.
11646 Before libguestfs 1.13.16, this call implicitly added the options
11648 "sync" and "noatime". The "sync" option greatly slowed writes and
11649 caused many problems for users. If your program might need to work
11650 with older versions of libguestfs, use "guestfs_mount_options" instead
11651 (using an empty string for the first parameter if you don't want any
11652 options).
11653 This function returns 0 on success or -1 on error.
11655 (Added in 0.3)
11657 guestfs_mount_9p
11659 int
11660 guestfs_mount_9p (guestfs_h *g,
11661 const char *mounttag,
11662 const char *mountpoint,
11663 ...);
11664 This function is deprecated. There is no replacement. Consult the API
11666 documentation in guestfs(3) for further information.
11667 Deprecated functions will not be removed from the API, but the fact
11669 that they are deprecated indicates that there are problems with correct
11670 use of these functions.
11671 You may supply a list of optional arguments to this call. Use zero or
11673 more of the following pairs of parameters, and terminate the list with
11674 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11675 GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11677 This call does nothing and returns an error.
11679 This function returns 0 on success or -1 on error.
11681 (Added in 1.11.12)
11683 guestfs_mount_9p_va
11685 int
11686 guestfs_mount_9p_va (guestfs_h *g,
11687 const char *mounttag,
11688 const char *mountpoint,
11689 va_list args);
11690 This is the "va_list variant" of "guestfs_mount_9p".
11692 See "CALLS WITH OPTIONAL ARGUMENTS".
11694 guestfs_mount_9p_argv
11696 int
11697 guestfs_mount_9p_argv (guestfs_h *g,
11698 const char *mounttag,
11699 const char *mountpoint,
11700 const struct guestfs_mount_9p_argv *optargs);
11701 This is the "argv variant" of "guestfs_mount_9p".
11703 See "CALLS WITH OPTIONAL ARGUMENTS".
11705 guestfs_mount_local
11707 int
11708 guestfs_mount_local (guestfs_h *g,
11709 const char *localmountpoint,
11710 ...);
11711 You may supply a list of optional arguments to this call. Use zero or
11713 more of the following pairs of parameters, and terminate the list with
11714 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11715 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11717 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11718 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11719 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11720 This call exports the libguestfs-accessible filesystem to a local
11722 mountpoint (directory) called "localmountpoint". Ordinary reads and
11723 writes to files and directories under "localmountpoint" are redirected
11724 through libguestfs.
11725 If the optional "readonly" flag is set to true, then writes to the
11727 filesystem return error "EROFS".
11728 "options" is a comma-separated list of mount options. See
11730 guestmount(1) for some useful options.
11731 "cachetimeout" sets the timeout (in seconds) for cached directory
11733 entries. The default is 60 seconds. See guestmount(1) for further
11734 information.
11735 If "debugcalls" is set to true, then additional debugging information
11737 is generated for every FUSE call.
11738 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11740 processing requests (access to it will block). You have to call
11741 "guestfs_mount_local_run" to run the main loop.
11742 See "MOUNT LOCAL" for full documentation.
11744 This function returns 0 on success or -1 on error.
11746 (Added in 1.17.22)
11748 guestfs_mount_local_va
11750 int
11751 guestfs_mount_local_va (guestfs_h *g,
11752 const char *localmountpoint,
11753 va_list args);
11754 This is the "va_list variant" of "guestfs_mount_local".
11756 See "CALLS WITH OPTIONAL ARGUMENTS".
11758 guestfs_mount_local_argv
11760 int
11761 guestfs_mount_local_argv (guestfs_h *g,
11762 const char *localmountpoint,
11763 const struct guestfs_mount_local_argv *optargs);
11764 This is the "argv variant" of "guestfs_mount_local".
11766 See "CALLS WITH OPTIONAL ARGUMENTS".
11768 guestfs_mount_local_run
11770 int
11771 guestfs_mount_local_run (guestfs_h *g);
11772 Run the main loop which translates kernel calls to libguestfs calls.
11774 This should only be called after "guestfs_mount_local" returns
11776 successfully. The call will not return until the filesystem is
11777 unmounted.
11778 Note you must not make concurrent libguestfs calls on the same handle
11780 from another thread.
11781 You may call this from a different thread than the one which called
11783 "guestfs_mount_local", subject to the usual rules for threads and
11784 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11785 See "MOUNT LOCAL" for full documentation.
11787 This function returns 0 on success or -1 on error.
11789 (Added in 1.17.22)
11791 guestfs_mount_loop
11793 int
11794 guestfs_mount_loop (guestfs_h *g,
11795 const char *file,
11796 const char *mountpoint);
11797 This command lets you mount file (a filesystem image in a file) on a
11799 mount point. It is entirely equivalent to the command "mount -o loop
11800 file mountpoint".
11801 This function returns 0 on success or -1 on error.
11803 (Added in 1.0.54)
11805 guestfs_mount_options
11807 int
11808 guestfs_mount_options (guestfs_h *g,
11809 const char *options,
11810 const char *mountable,
11811 const char *mountpoint);
11812 This is the same as the "guestfs_mount" command, but it allows you to
11814 set the mount options as for the mount(8) -o flag.
11815 If the "options" parameter is an empty string, then no options are
11817 passed (all options default to whatever the filesystem uses).
11818 This function returns 0 on success or -1 on error.
11820 (Added in 1.0.10)
11822 guestfs_mount_ro
11824 int
11825 guestfs_mount_ro (guestfs_h *g,
11826 const char *mountable,
11827 const char *mountpoint);
11828 This is the same as the "guestfs_mount" command, but it mounts the
11830 filesystem with the read-only (-o ro) flag.
11831 This function returns 0 on success or -1 on error.
11833 (Added in 1.0.10)
11835 guestfs_mount_vfs
11837 int
11838 guestfs_mount_vfs (guestfs_h *g,
11839 const char *options,
11840 const char *vfstype,
11841 const char *mountable,
11842 const char *mountpoint);
11843 This is the same as the "guestfs_mount" command, but it allows you to
11845 set both the mount options and the vfstype as for the mount(8) -o and
11846 -t flags.
11847 This function returns 0 on success or -1 on error.
11849 (Added in 1.0.10)
11851 guestfs_mountable_device
11853 char *
11854 guestfs_mountable_device (guestfs_h *g,
11855 const char *mountable);
11856 Returns the device name of a mountable. In quite a lot of cases, the
11858 mountable is the device name.
11859 However this doesn't apply for btrfs subvolumes, where the mountable is
11861 a combination of both the device name and the subvolume path (see also
11862 "guestfs_mountable_subvolume" to extract the subvolume path of the
11863 mountable if any).
11864 This function returns a string, or NULL on error. The caller must free
11866 the returned string after use.
11867 (Added in 1.33.15)
11869 guestfs_mountable_subvolume
11871 char *
11872 guestfs_mountable_subvolume (guestfs_h *g,
11873 const char *mountable);
11874 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11876 are a combination of both the device name and the subvolume path (see
11877 also "guestfs_mountable_device" to extract the device of the
11878 mountable).
11879 If the mountable does not represent a btrfs subvolume, then this
11881 function fails and the "errno" is set to "EINVAL".
11882 This function returns a string, or NULL on error. The caller must free
11884 the returned string after use.
11885 (Added in 1.33.15)
11887 guestfs_mountpoints
11889 char **
11890 guestfs_mountpoints (guestfs_h *g);
11891 This call is similar to "guestfs_mounts". That call returns a list of
11893 devices. This one returns a hash table (map) of device name to
11894 directory where the device is mounted.
11895 This function returns a NULL-terminated array of strings, or NULL if
11897 there was an error. The array of strings will always have length
11898 "2n+1", where "n" keys and values alternate, followed by the trailing
11899 NULL entry. The caller must free the strings and the array after use.
11900 (Added in 1.0.62)
11902 guestfs_mounts
11904 char **
11905 guestfs_mounts (guestfs_h *g);
11906 This returns the list of currently mounted filesystems. It returns the
11908 list of devices (eg. /dev/sda1, /dev/VG/LV).
11909 Some internal mounts are not shown.
11911 See also: "guestfs_mountpoints"
11913 This function returns a NULL-terminated array of strings (like
11915 environ(3)), or NULL if there was an error. The caller must free the
11916 strings and the array after use.
11917 (Added in 0.8)
11919 guestfs_mv
11921 int
11922 guestfs_mv (guestfs_h *g,
11923 const char *src,
11924 const char *dest);
11925 This moves a file from "src" to "dest" where "dest" is either a
11927 destination filename or destination directory.
11928 See also: "guestfs_rename".
11930 This function returns 0 on success or -1 on error.
11932 (Added in 1.0.18)
11934 guestfs_nr_devices
11936 int
11937 guestfs_nr_devices (guestfs_h *g);
11938 This returns the number of whole block devices that were added. This
11940 is the same as the number of devices that would be returned if you
11941 called "guestfs_list_devices".
11942 To find out the maximum number of devices that could be added, call
11944 "guestfs_max_disks".
11945 On error this function returns -1.
11947 (Added in 1.19.15)
11949 guestfs_ntfs_3g_probe
11951 int
11952 guestfs_ntfs_3g_probe (guestfs_h *g,
11953 int rw,
11954 const char *device);
11955 This command runs the ntfs-3g.probe(8) command which probes an NTFS
11957 "device" for mountability. (Not all NTFS volumes can be mounted read-
11958 write, and some cannot be mounted at all).
11959 "rw" is a boolean flag. Set it to true if you want to test if the
11961 volume can be mounted read-write. Set it to false if you want to test
11962 if the volume can be mounted read-only.
11963 The return value is an integer which 0 if the operation would succeed,
11965 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
11966 On error this function returns -1.
11968 This function depends on the feature "ntfs3g". See also
11970 "guestfs_feature_available".
11971 (Added in 1.0.43)
11973 guestfs_ntfscat_i
11975 int
11976 guestfs_ntfscat_i (guestfs_h *g,
11977 const char *device,
11978 int64_t inode,
11979 const char *filename);
11980 Download a file given its inode from a NTFS filesystem and save it as
11982 filename on the local machine.
11983 This allows to download some otherwise inaccessible files such as the
11985 ones within the $Extend folder.
11986 The filesystem from which to extract the file must be unmounted,
11988 otherwise the call will fail.
11989 This function returns 0 on success or -1 on error.
11991 This long-running command can generate progress notification messages
11993 so that the caller can display a progress bar or indicator. To receive
11994 these messages, the caller must register a progress event callback.
11995 See "GUESTFS_EVENT_PROGRESS".
11996 (Added in 1.33.14)
11998 guestfs_ntfsclone_in
12000 int
12001 guestfs_ntfsclone_in (guestfs_h *g,
12002 const char *backupfile,
12003 const char *device);
12004 Restore the "backupfile" (from a previous call to
12006 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
12007 of this device.
12008 This function returns 0 on success or -1 on error.
12010 This function depends on the feature "ntfs3g". See also
12012 "guestfs_feature_available".
12013 (Added in 1.17.9)
12015 guestfs_ntfsclone_out
12017 int
12018 guestfs_ntfsclone_out (guestfs_h *g,
12019 const char *device,
12020 const char *backupfile,
12021 ...);
12022 You may supply a list of optional arguments to this call. Use zero or
12024 more of the following pairs of parameters, and terminate the list with
12025 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12026 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
12028 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
12029 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
12030 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
12031 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
12032 Stream the NTFS filesystem "device" to the local file "backupfile".
12034 The format used for the backup file is a special format used by the
12035 ntfsclone(8) tool.
12036 If the optional "metadataonly" flag is true, then only the metadata is
12038 saved, losing all the user data (this is useful for diagnosing some
12039 filesystem problems).
12040 The optional "rescue", "ignorefscheck", "preservetimestamps" and
12042 "force" flags have precise meanings detailed in the ntfsclone(8) man
12043 page.
12044 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
12046 device.
12047 This function returns 0 on success or -1 on error.
12049 This function depends on the feature "ntfs3g". See also
12051 "guestfs_feature_available".
12052 (Added in 1.17.9)
12054 guestfs_ntfsclone_out_va
12056 int
12057 guestfs_ntfsclone_out_va (guestfs_h *g,
12058 const char *device,
12059 const char *backupfile,
12060 va_list args);
12061 This is the "va_list variant" of "guestfs_ntfsclone_out".
12063 See "CALLS WITH OPTIONAL ARGUMENTS".
12065 guestfs_ntfsclone_out_argv
12067 int
12068 guestfs_ntfsclone_out_argv (guestfs_h *g,
12069 const char *device,
12070 const char *backupfile,
12071 const struct guestfs_ntfsclone_out_argv *optargs);
12072 This is the "argv variant" of "guestfs_ntfsclone_out".
12074 See "CALLS WITH OPTIONAL ARGUMENTS".
12076 guestfs_ntfsfix
12078 int
12079 guestfs_ntfsfix (guestfs_h *g,
12080 const char *device,
12081 ...);
12082 You may supply a list of optional arguments to this call. Use zero or
12084 more of the following pairs of parameters, and terminate the list with
12085 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12086 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
12088 This command repairs some fundamental NTFS inconsistencies, resets the
12090 NTFS journal file, and schedules an NTFS consistency check for the
12091 first boot into Windows.
12092 This is not an equivalent of Windows "chkdsk". It does not scan the
12094 filesystem for inconsistencies.
12095 The optional "clearbadsectors" flag clears the list of bad sectors.
12097 This is useful after cloning a disk with bad sectors to a new disk.
12098 This function returns 0 on success or -1 on error.
12100 This function depends on the feature "ntfs3g". See also
12102 "guestfs_feature_available".
12103 (Added in 1.17.9)
12105 guestfs_ntfsfix_va
12107 int
12108 guestfs_ntfsfix_va (guestfs_h *g,
12109 const char *device,
12110 va_list args);
12111 This is the "va_list variant" of "guestfs_ntfsfix".
12113 See "CALLS WITH OPTIONAL ARGUMENTS".
12115 guestfs_ntfsfix_argv
12117 int
12118 guestfs_ntfsfix_argv (guestfs_h *g,
12119 const char *device,
12120 const struct guestfs_ntfsfix_argv *optargs);
12121 This is the "argv variant" of "guestfs_ntfsfix".
12123 See "CALLS WITH OPTIONAL ARGUMENTS".
12125 guestfs_ntfsresize
12127 int
12128 guestfs_ntfsresize (guestfs_h *g,
12129 const char *device);
12130 This function is provided for backwards compatibility with earlier
12132 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
12133 no optional arguments.
12134 (Added in 1.3.2)
12136 guestfs_ntfsresize_opts
12138 int
12139 guestfs_ntfsresize_opts (guestfs_h *g,
12140 const char *device,
12141 ...);
12142 You may supply a list of optional arguments to this call. Use zero or
12144 more of the following pairs of parameters, and terminate the list with
12145 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12146 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12148 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12149 This command resizes an NTFS filesystem, expanding or shrinking it to
12151 the size of the underlying device.
12152 The optional parameters are:
12154 "size"
12156 The new size (in bytes) of the filesystem. If omitted, the
12157 filesystem is resized to fit the container (eg. partition).
12158 "force"
12160 If this option is true, then force the resize of the filesystem
12161 even if the filesystem is marked as requiring a consistency check.
12162 After the resize operation, the filesystem is always marked as
12164 requiring a consistency check (for safety). You have to boot into
12165 Windows to perform this check and clear this condition. If you
12166 don't set the "force" option then it is not possible to call
12167 "guestfs_ntfsresize" multiple times on a single filesystem without
12168 booting into Windows between each resize.
12169 See also ntfsresize(8).
12171 This function returns 0 on success or -1 on error.
12173 This function depends on the feature "ntfsprogs". See also
12175 "guestfs_feature_available".
12176 (Added in 1.3.2)
12178 guestfs_ntfsresize_opts_va
12180 int
12181 guestfs_ntfsresize_opts_va (guestfs_h *g,
12182 const char *device,
12183 va_list args);
12184 This is the "va_list variant" of "guestfs_ntfsresize_opts".
12186 See "CALLS WITH OPTIONAL ARGUMENTS".
12188 guestfs_ntfsresize_opts_argv
12190 int
12191 guestfs_ntfsresize_opts_argv (guestfs_h *g,
12192 const char *device,
12193 const struct guestfs_ntfsresize_opts_argv *optargs);
12194 This is the "argv variant" of "guestfs_ntfsresize_opts".
12196 See "CALLS WITH OPTIONAL ARGUMENTS".
12198 guestfs_ntfsresize_size
12200 int
12201 guestfs_ntfsresize_size (guestfs_h *g,
12202 const char *device,
12203 int64_t size);
12204 This function is deprecated. In new code, use the "guestfs_ntfsresize"
12206 call instead.
12207 Deprecated functions will not be removed from the API, but the fact
12209 that they are deprecated indicates that there are problems with correct
12210 use of these functions.
12211 This command is the same as "guestfs_ntfsresize" except that it allows
12213 you to specify the new size (in bytes) explicitly.
12214 This function returns 0 on success or -1 on error.
12216 This function depends on the feature "ntfsprogs". See also
12218 "guestfs_feature_available".
12219 (Added in 1.3.14)
12221 guestfs_parse_environment
12223 int
12224 guestfs_parse_environment (guestfs_h *g);
12225 Parse the program’s environment and set flags in the handle
12227 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12228 flag is set in the handle.
12229 Most programs do not need to call this. It is done implicitly when you
12231 call "guestfs_create".
12232 See "ENVIRONMENT VARIABLES" for a list of environment variables that
12234 can affect libguestfs handles. See also "guestfs_create_flags", and
12235 "guestfs_parse_environment_list".
12236 This function returns 0 on success or -1 on error.
12238 (Added in 1.19.53)
12240 guestfs_parse_environment_list
12242 int
12243 guestfs_parse_environment_list (guestfs_h *g,
12244 char *const *environment);
12245 Parse the list of strings in the argument "environment" and set flags
12247 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
12248 string in the list, then the ‘verbose’ flag is set in the handle.
12249 This is the same as "guestfs_parse_environment" except that it parses
12251 an explicit list of strings instead of the program's environment.
12252 This function returns 0 on success or -1 on error.
12254 (Added in 1.19.53)
12256 guestfs_part_add
12258 int
12259 guestfs_part_add (guestfs_h *g,
12260 const char *device,
12261 const char *prlogex,
12262 int64_t startsect,
12263 int64_t endsect);
12264 This command adds a partition to "device". If there is no partition
12266 table on the device, call "guestfs_part_init" first.
12267 The "prlogex" parameter is the type of partition. Normally you should
12269 pass "p" or "primary" here, but MBR partition tables also support "l"
12270 (or "logical") and "e" (or "extended") partition types.
12271 "startsect" and "endsect" are the start and end of the partition in
12273 sectors. "endsect" may be negative, which means it counts backwards
12274 from the end of the disk (-1 is the last sector).
12275 Creating a partition which covers the whole disk is not so easy. Use
12277 "guestfs_part_disk" to do that.
12278 This function returns 0 on success or -1 on error.
12280 (Added in 1.0.78)
12282 guestfs_part_del
12284 int
12285 guestfs_part_del (guestfs_h *g,
12286 const char *device,
12287 int partnum);
12288 This command deletes the partition numbered "partnum" on "device".
12290 Note that in the case of MBR partitioning, deleting an extended
12292 partition also deletes any logical partitions it contains.
12293 This function returns 0 on success or -1 on error.
12295 (Added in 1.3.2)
12297 guestfs_part_disk
12299 int
12300 guestfs_part_disk (guestfs_h *g,
12301 const char *device,
12302 const char *parttype);
12303 This command is simply a combination of "guestfs_part_init" followed by
12305 "guestfs_part_add" to create a single primary partition covering the
12306 whole disk.
12307 "parttype" is the partition table type, usually "mbr" or "gpt", but
12309 other possible values are described in "guestfs_part_init".
12310 This function returns 0 on success or -1 on error.
12312 (Added in 1.0.78)
12314 guestfs_part_expand_gpt
12316 int
12317 guestfs_part_expand_gpt (guestfs_h *g,
12318 const char *device);
12319 Move backup GPT data structures to the end of the disk. This is useful
12321 in case of in-place image expand since disk space after backup GPT
12322 header is not usable. This is equivalent to "sgdisk -e".
12323 See also sgdisk(8).
12325 This function returns 0 on success or -1 on error.
12327 This function depends on the feature "gdisk". See also
12329 "guestfs_feature_available".
12330 (Added in 1.33.2)
12332 guestfs_part_get_bootable
12334 int
12335 guestfs_part_get_bootable (guestfs_h *g,
12336 const char *device,
12337 int partnum);
12338 This command returns true if the partition "partnum" on "device" has
12340 the bootable flag set.
12341 See also "guestfs_part_set_bootable".
12343 This function returns a C truth value on success or -1 on error.
12345 (Added in 1.3.2)
12347 guestfs_part_get_disk_guid
12349 char *
12350 guestfs_part_get_disk_guid (guestfs_h *g,
12351 const char *device);
12352 Return the disk identifier (GUID) of a GPT-partitioned "device".
12354 Behaviour is undefined for other partition types.
12355 This function returns a string, or NULL on error. The caller must free
12357 the returned string after use.
12358 This function depends on the feature "gdisk". See also
12360 "guestfs_feature_available".
12361 (Added in 1.33.2)
12363 guestfs_part_get_gpt_attributes
12365 int64_t
12366 guestfs_part_get_gpt_attributes (guestfs_h *g,
12367 const char *device,
12368 int partnum);
12369 Return the attribute flags of numbered GPT partition "partnum". An
12371 error is returned for MBR partitions.
12372 On error this function returns -1.
12374 This function depends on the feature "gdisk". See also
12376 "guestfs_feature_available".
12377 (Added in 1.21.1)
12379 guestfs_part_get_gpt_guid
12381 char *
12382 guestfs_part_get_gpt_guid (guestfs_h *g,
12383 const char *device,
12384 int partnum);
12385 Return the GUID of numbered GPT partition "partnum".
12387 This function returns a string, or NULL on error. The caller must free
12389 the returned string after use.
12390 This function depends on the feature "gdisk". See also
12392 "guestfs_feature_available".
12393 (Added in 1.29.25)
12395 guestfs_part_get_gpt_type
12397 char *
12398 guestfs_part_get_gpt_type (guestfs_h *g,
12399 const char *device,
12400 int partnum);
12401 Return the type GUID of numbered GPT partition "partnum". For MBR
12403 partitions, return an appropriate GUID corresponding to the MBR type.
12404 Behaviour is undefined for other partition types.
12405 This function returns a string, or NULL on error. The caller must free
12407 the returned string after use.
12408 This function depends on the feature "gdisk". See also
12410 "guestfs_feature_available".
12411 (Added in 1.21.1)
12413 guestfs_part_get_mbr_id
12415 int
12416 guestfs_part_get_mbr_id (guestfs_h *g,
12417 const char *device,
12418 int partnum);
12419 Returns the MBR type byte (also known as the ID byte) from the numbered
12421 partition "partnum".
12422 Note that only MBR (old DOS-style) partitions have type bytes. You
12424 will get undefined results for other partition table types (see
12425 "guestfs_part_get_parttype").
12426 On error this function returns -1.
12428 (Added in 1.3.2)
12430 guestfs_part_get_mbr_part_type
12432 char *
12433 guestfs_part_get_mbr_part_type (guestfs_h *g,
12434 const char *device,
12435 int partnum);
12436 This returns the partition type of an MBR partition numbered "partnum"
12438 on device "device".
12439 It returns "primary", "logical", or "extended".
12441 This function returns a string, or NULL on error. The caller must free
12443 the returned string after use.
12444 (Added in 1.29.32)
12446 guestfs_part_get_name
12448 char *
12449 guestfs_part_get_name (guestfs_h *g,
12450 const char *device,
12451 int partnum);
12452 This gets the partition name on partition numbered "partnum" on device
12454 "device". Note that partitions are numbered from 1.
12455 The partition name can only be read on certain types of partition
12457 table. This works on "gpt" but not on "mbr" partitions.
12458 This function returns a string, or NULL on error. The caller must free
12460 the returned string after use.
12461 (Added in 1.25.33)
12463 guestfs_part_get_parttype
12465 char *
12466 guestfs_part_get_parttype (guestfs_h *g,
12467 const char *device);
12468 This command examines the partition table on "device" and returns the
12470 partition table type (format) being used.
12471 Common return values include: "msdos" (a DOS/Windows style MBR
12473 partition table), "gpt" (a GPT/EFI-style partition table). Other
12474 values are possible, although unusual. See "guestfs_part_init" for a
12475 full list.
12476 This function returns a string, or NULL on error. The caller must free
12478 the returned string after use.
12479 (Added in 1.0.78)
12481 guestfs_part_init
12483 int
12484 guestfs_part_init (guestfs_h *g,
12485 const char *device,
12486 const char *parttype);
12487 This creates an empty partition table on "device" of one of the
12489 partition types listed below. Usually "parttype" should be either
12490 "msdos" or "gpt" (for large disks).
12491 Initially there are no partitions. Following this, you should call
12493 "guestfs_part_add" for each partition required.
12494 Possible values for "parttype" are:
12496 "efi"
12498 "gpt"
12499 Intel EFI / GPT partition table.
12500 This is recommended for >= 2 TB partitions that will be accessed
12502 from Linux and Intel-based Mac OS X. It also has limited backwards
12503 compatibility with the "mbr" format.
12504 "mbr"
12506 "msdos"
12507 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12508 and Windows. This partition type will only work for device sizes
12509 up to 2 TB. For large disks we recommend using "gpt".
12510 Other partition table types that may work but are not supported
12512 include:
12513 "aix"
12515 AIX disk labels.
12516 "amiga"
12518 "rdb"
12519 Amiga "Rigid Disk Block" format.
12520 "bsd"
12522 BSD disk labels.
12523 "dasd"
12525 DASD, used on IBM mainframes.
12526 "dvh"
12528 MIPS/SGI volumes.
12529 "mac"
12531 Old Mac partition format. Modern Macs use "gpt".
12532 "pc98"
12534 NEC PC-98 format, common in Japan apparently.
12535 "sun"
12537 Sun disk labels.
12538 This function returns 0 on success or -1 on error.
12540 (Added in 1.0.78)
12542 guestfs_part_list
12544 struct guestfs_partition_list *
12545 guestfs_part_list (guestfs_h *g,
12546 const char *device);
12547 This command parses the partition table on "device" and returns the
12549 list of partitions found.
12550 The fields in the returned structure are:
12552 "part_num"
12554 Partition number, counting from 1.
12555 "part_start"
12557 Start of the partition in bytes. To get sectors you have to divide
12558 by the device’s sector size, see "guestfs_blockdev_getss".
12559 "part_end"
12561 End of the partition in bytes.
12562 "part_size"
12564 Size of the partition in bytes.
12565 This function returns a "struct guestfs_partition_list *", or NULL if
12567 there was an error. The caller must call "guestfs_free_partition_list"
12568 after use.
12569 (Added in 1.0.78)
12571 guestfs_part_resize
12573 int
12574 guestfs_part_resize (guestfs_h *g,
12575 const char *device,
12576 int partnum,
12577 int64_t endsect);
12578 This command resizes the partition numbered "partnum" on "device" by
12580 moving the end position.
12581 Note that this does not modify any filesystem present in the partition.
12583 If you wish to do this, you will need to use filesystem resizing
12584 commands like "guestfs_resize2fs".
12585 When growing a partition you will want to grow the filesystem
12587 afterwards, but when shrinking, you need to shrink the filesystem
12588 before the partition.
12589 This function returns 0 on success or -1 on error.
12591 (Added in 1.37.20)
12593 guestfs_part_set_bootable
12595 int
12596 guestfs_part_set_bootable (guestfs_h *g,
12597 const char *device,
12598 int partnum,
12599 int bootable);
12600 This sets the bootable flag on partition numbered "partnum" on device
12602 "device". Note that partitions are numbered from 1.
12603 The bootable flag is used by some operating systems (notably Windows)
12605 to determine which partition to boot from. It is by no means
12606 universally recognized.
12607 This function returns 0 on success or -1 on error.
12609 (Added in 1.0.78)
12611 guestfs_part_set_disk_guid
12613 int
12614 guestfs_part_set_disk_guid (guestfs_h *g,
12615 const char *device,
12616 const char *guid);
12617 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12619 Return an error if the partition table of "device" isn't GPT, or if
12620 "guid" is not a valid GUID.
12621 This function returns 0 on success or -1 on error.
12623 This function depends on the feature "gdisk". See also
12625 "guestfs_feature_available".
12626 (Added in 1.33.2)
12628 guestfs_part_set_disk_guid_random
12630 int
12631 guestfs_part_set_disk_guid_random (guestfs_h *g,
12632 const char *device);
12633 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12635 randomly generated value. Return an error if the partition table of
12636 "device" isn't GPT.
12637 This function returns 0 on success or -1 on error.
12639 This function depends on the feature "gdisk". See also
12641 "guestfs_feature_available".
12642 (Added in 1.33.2)
12644 guestfs_part_set_gpt_attributes
12646 int
12647 guestfs_part_set_gpt_attributes (guestfs_h *g,
12648 const char *device,
12649 int partnum,
12650 int64_t attributes);
12651 Set the attribute flags of numbered GPT partition "partnum" to
12653 "attributes". Return an error if the partition table of "device" isn't
12654 GPT.
12655 See
12657 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12658 for a useful list of partition attributes.
12659 This function returns 0 on success or -1 on error.
12661 This function depends on the feature "gdisk". See also
12663 "guestfs_feature_available".
12664 (Added in 1.21.1)
12666 guestfs_part_set_gpt_guid
12668 int
12669 guestfs_part_set_gpt_guid (guestfs_h *g,
12670 const char *device,
12671 int partnum,
12672 const char *guid);
12673 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12675 error if the partition table of "device" isn't GPT, or if "guid" is not
12676 a valid GUID.
12677 This function returns 0 on success or -1 on error.
12679 This function depends on the feature "gdisk". See also
12681 "guestfs_feature_available".
12682 (Added in 1.29.25)
12684 guestfs_part_set_gpt_type
12686 int
12687 guestfs_part_set_gpt_type (guestfs_h *g,
12688 const char *device,
12689 int partnum,
12690 const char *guid);
12691 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12693 an error if the partition table of "device" isn't GPT, or if "guid" is
12694 not a valid GUID.
12695 See
12697 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12698 for a useful list of type GUIDs.
12699 This function returns 0 on success or -1 on error.
12701 This function depends on the feature "gdisk". See also
12703 "guestfs_feature_available".
12704 (Added in 1.21.1)
12706 guestfs_part_set_mbr_id
12708 int
12709 guestfs_part_set_mbr_id (guestfs_h *g,
12710 const char *device,
12711 int partnum,
12712 int idbyte);
12713 Sets the MBR type byte (also known as the ID byte) of the numbered
12715 partition "partnum" to "idbyte". Note that the type bytes quoted in
12716 most documentation are in fact hexadecimal numbers, but usually
12717 documented without any leading "0x" which might be confusing.
12718 Note that only MBR (old DOS-style) partitions have type bytes. You
12720 will get undefined results for other partition table types (see
12721 "guestfs_part_get_parttype").
12722 This function returns 0 on success or -1 on error.
12724 (Added in 1.3.2)
12726 guestfs_part_set_name
12728 int
12729 guestfs_part_set_name (guestfs_h *g,
12730 const char *device,
12731 int partnum,
12732 const char *name);
12733 This sets the partition name on partition numbered "partnum" on device
12735 "device". Note that partitions are numbered from 1.
12736 The partition name can only be set on certain types of partition table.
12738 This works on "gpt" but not on "mbr" partitions.
12739 This function returns 0 on success or -1 on error.
12741 (Added in 1.0.78)
12743 guestfs_part_to_dev
12745 char *
12746 guestfs_part_to_dev (guestfs_h *g,
12747 const char *partition);
12748 This function takes a partition name (eg. "/dev/sdb1") and removes the
12750 partition number, returning the device name (eg. "/dev/sdb").
12751 The named partition must exist, for example as a string returned from
12753 "guestfs_list_partitions".
12754 See also "guestfs_part_to_partnum", "guestfs_device_index".
12756 This function returns a string, or NULL on error. The caller must free
12758 the returned string after use.
12759 (Added in 1.5.15)
12761 guestfs_part_to_partnum
12763 int
12764 guestfs_part_to_partnum (guestfs_h *g,
12765 const char *partition);
12766 This function takes a partition name (eg. "/dev/sdb1") and returns the
12768 partition number (eg. 1).
12769 The named partition must exist, for example as a string returned from
12771 "guestfs_list_partitions".
12772 See also "guestfs_part_to_dev".
12774 On error this function returns -1.
12776 (Added in 1.13.25)
12778 guestfs_ping_daemon
12780 int
12781 guestfs_ping_daemon (guestfs_h *g);
12782 This is a test probe into the guestfs daemon running inside the
12784 libguestfs appliance. Calling this function checks that the daemon
12785 responds to the ping message, without affecting the daemon or attached
12786 block device(s) in any other way.
12787 This function returns 0 on success or -1 on error.
12789 (Added in 1.0.18)
12791 guestfs_pread
12793 char *
12794 guestfs_pread (guestfs_h *g,
12795 const char *path,
12796 int count,
12797 int64_t offset,
12798 size_t *size_r);
12799 This command lets you read part of a file. It reads "count" bytes of
12801 the file, starting at "offset", from file "path".
12802 This may read fewer bytes than requested. For further details see the
12804 pread(2) system call.
12805 See also "guestfs_pwrite", "guestfs_pread_device".
12807 This function returns a buffer, or NULL on error. The size of the
12809 returned buffer is written to *size_r. The caller must free the
12810 returned buffer after use.
12811 Because of the message protocol, there is a transfer limit of somewhere
12813 between 2MB and 4MB. See "PROTOCOL LIMITS".
12814 (Added in 1.0.77)
12816 guestfs_pread_device
12818 char *
12819 guestfs_pread_device (guestfs_h *g,
12820 const char *device,
12821 int count,
12822 int64_t offset,
12823 size_t *size_r);
12824 This command lets you read part of a block device. It reads "count"
12826 bytes of "device", starting at "offset".
12827 This may read fewer bytes than requested. For further details see the
12829 pread(2) system call.
12830 See also "guestfs_pread".
12832 This function returns a buffer, or NULL on error. The size of the
12834 returned buffer is written to *size_r. The caller must free the
12835 returned buffer after use.
12836 Because of the message protocol, there is a transfer limit of somewhere
12838 between 2MB and 4MB. See "PROTOCOL LIMITS".
12839 (Added in 1.5.21)
12841 guestfs_pvchange_uuid
12843 int
12844 guestfs_pvchange_uuid (guestfs_h *g,
12845 const char *device);
12846 Generate a new random UUID for the physical volume "device".
12848 This function returns 0 on success or -1 on error.
12850 This function depends on the feature "lvm2". See also
12852 "guestfs_feature_available".
12853 (Added in 1.19.26)
12855 guestfs_pvchange_uuid_all
12857 int
12858 guestfs_pvchange_uuid_all (guestfs_h *g);
12859 Generate new random UUIDs for all physical volumes.
12861 This function returns 0 on success or -1 on error.
12863 This function depends on the feature "lvm2". See also
12865 "guestfs_feature_available".
12866 (Added in 1.19.26)
12868 guestfs_pvcreate
12870 int
12871 guestfs_pvcreate (guestfs_h *g,
12872 const char *device);
12873 This creates an LVM physical volume on the named "device", where
12875 "device" should usually be a partition name such as /dev/sda1.
12876 This function returns 0 on success or -1 on error.
12878 This function depends on the feature "lvm2". See also
12880 "guestfs_feature_available".
12881 (Added in 0.8)
12883 guestfs_pvremove
12885 int
12886 guestfs_pvremove (guestfs_h *g,
12887 const char *device);
12888 This wipes a physical volume "device" so that LVM will no longer
12890 recognise it.
12891 The implementation uses the pvremove(8) command which refuses to wipe
12893 physical volumes that contain any volume groups, so you have to remove
12894 those first.
12895 This function returns 0 on success or -1 on error.
12897 This function depends on the feature "lvm2". See also
12899 "guestfs_feature_available".
12900 (Added in 1.0.13)
12902 guestfs_pvresize
12904 int
12905 guestfs_pvresize (guestfs_h *g,
12906 const char *device);
12907 This resizes (expands or shrinks) an existing LVM physical volume to
12909 match the new size of the underlying device.
12910 This function returns 0 on success or -1 on error.
12912 This function depends on the feature "lvm2". See also
12914 "guestfs_feature_available".
12915 (Added in 1.0.26)
12917 guestfs_pvresize_size
12919 int
12920 guestfs_pvresize_size (guestfs_h *g,
12921 const char *device,
12922 int64_t size);
12923 This command is the same as "guestfs_pvresize" except that it allows
12925 you to specify the new size (in bytes) explicitly.
12926 This function returns 0 on success or -1 on error.
12928 This function depends on the feature "lvm2". See also
12930 "guestfs_feature_available".
12931 (Added in 1.3.14)
12933 guestfs_pvs
12935 char **
12936 guestfs_pvs (guestfs_h *g);
12937 List all the physical volumes detected. This is the equivalent of the
12939 pvs(8) command.
12940 This returns a list of just the device names that contain PVs (eg.
12942 /dev/sda2).
12943 See also "guestfs_pvs_full".
12945 This function returns a NULL-terminated array of strings (like
12947 environ(3)), or NULL if there was an error. The caller must free the
12948 strings and the array after use.
12949 This function depends on the feature "lvm2". See also
12951 "guestfs_feature_available".
12952 (Added in 0.4)
12954 guestfs_pvs_full
12956 struct guestfs_lvm_pv_list *
12957 guestfs_pvs_full (guestfs_h *g);
12958 List all the physical volumes detected. This is the equivalent of the
12960 pvs(8) command. The "full" version includes all fields.
12961 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
12963 there was an error. The caller must call "guestfs_free_lvm_pv_list"
12964 after use.
12965 This function depends on the feature "lvm2". See also
12967 "guestfs_feature_available".
12968 (Added in 0.4)
12970 guestfs_pvuuid
12972 char *
12973 guestfs_pvuuid (guestfs_h *g,
12974 const char *device);
12975 This command returns the UUID of the LVM PV "device".
12977 This function returns a string, or NULL on error. The caller must free
12979 the returned string after use.
12980 (Added in 1.0.87)
12982 guestfs_pwrite
12984 int
12985 guestfs_pwrite (guestfs_h *g,
12986 const char *path,
12987 const char *content,
12988 size_t content_size,
12989 int64_t offset);
12990 This command writes to part of a file. It writes the data buffer
12992 "content" to the file "path" starting at offset "offset".
12993 This command implements the pwrite(2) system call, and like that system
12995 call it may not write the full data requested. The return value is the
12996 number of bytes that were actually written to the file. This could
12997 even be 0, although short writes are unlikely for regular files in
12998 ordinary circumstances.
12999 See also "guestfs_pread", "guestfs_pwrite_device".
13001 On error this function returns -1.
13003 Because of the message protocol, there is a transfer limit of somewhere
13005 between 2MB and 4MB. See "PROTOCOL LIMITS".
13006 (Added in 1.3.14)
13008 guestfs_pwrite_device
13010 int
13011 guestfs_pwrite_device (guestfs_h *g,
13012 const char *device,
13013 const char *content,
13014 size_t content_size,
13015 int64_t offset);
13016 This command writes to part of a device. It writes the data buffer
13018 "content" to "device" starting at offset "offset".
13019 This command implements the pwrite(2) system call, and like that system
13021 call it may not write the full data requested (although short writes to
13022 disk devices and partitions are probably impossible with standard Linux
13023 kernels).
13024 See also "guestfs_pwrite".
13026 On error this function returns -1.
13028 Because of the message protocol, there is a transfer limit of somewhere
13030 between 2MB and 4MB. See "PROTOCOL LIMITS".
13031 (Added in 1.5.20)
13033 guestfs_read_file
13035 char *
13036 guestfs_read_file (guestfs_h *g,
13037 const char *path,
13038 size_t *size_r);
13039 This calls returns the contents of the file "path" as a buffer.
13041 Unlike "guestfs_cat", this function can correctly handle files that
13043 contain embedded ASCII NUL characters.
13044 This function returns a buffer, or NULL on error. The size of the
13046 returned buffer is written to *size_r. The caller must free the
13047 returned buffer after use.
13048 (Added in 1.0.63)
13050 guestfs_read_lines
13052 char **
13053 guestfs_read_lines (guestfs_h *g,
13054 const char *path);
13055 Return the contents of the file named "path".
13057 The file contents are returned as a list of lines. Trailing "LF" and
13059 "CRLF" character sequences are not returned.
13060 Note that this function cannot correctly handle binary files
13062 (specifically, files containing "\0" character which is treated as end
13063 of string). For those you need to use the "guestfs_read_file" function
13064 and split the buffer into lines yourself.
13065 This function returns a NULL-terminated array of strings (like
13067 environ(3)), or NULL if there was an error. The caller must free the
13068 strings and the array after use.
13069 (Added in 0.7)
13071 guestfs_readdir
13073 struct guestfs_dirent_list *
13074 guestfs_readdir (guestfs_h *g,
13075 const char *dir);
13076 This returns the list of directory entries in directory "dir".
13078 All entries in the directory are returned, including "." and "..". The
13080 entries are not sorted, but returned in the same order as the
13081 underlying filesystem.
13082 Also this call returns basic file type information about each file.
13084 The "ftyp" field will contain one of the following characters:
13085 'b' Block special
13087 'c' Char special
13089 'd' Directory
13091 'f' FIFO (named pipe)
13093 'l' Symbolic link
13095 'r' Regular file
13097 's' Socket
13099 'u' Unknown file type
13101 '?' The readdir(3) call returned a "d_type" field with an unexpected
13103 value
13104 This function is primarily intended for use by programs. To get a
13106 simple list of names, use "guestfs_ls". To get a printable directory
13107 for human consumption, use "guestfs_ll".
13108 This function returns a "struct guestfs_dirent_list *", or NULL if
13110 there was an error. The caller must call "guestfs_free_dirent_list"
13111 after use.
13112 This long-running command can generate progress notification messages
13114 so that the caller can display a progress bar or indicator. To receive
13115 these messages, the caller must register a progress event callback.
13116 See "GUESTFS_EVENT_PROGRESS".
13117 (Added in 1.0.55)
13119 guestfs_readlink
13121 char *
13122 guestfs_readlink (guestfs_h *g,
13123 const char *path);
13124 This command reads the target of a symbolic link.
13126 This function returns a string, or NULL on error. The caller must free
13128 the returned string after use.
13129 (Added in 1.0.66)
13131 guestfs_readlinklist
13133 char **
13134 guestfs_readlinklist (guestfs_h *g,
13135 const char *path,
13136 char *const *names);
13137 This call allows you to do a "readlink" operation on multiple files,
13139 where all files are in the directory "path". "names" is the list of
13140 files from this directory.
13141 On return you get a list of strings, with a one-to-one correspondence
13143 to the "names" list. Each string is the value of the symbolic link.
13144 If the readlink(2) operation fails on any name, then the corresponding
13146 result string is the empty string "". However the whole operation is
13147 completed even if there were readlink(2) errors, and so you can call
13148 this function with names where you don't know if they are symbolic
13149 links already (albeit slightly less efficient).
13150 This call is intended for programs that want to efficiently list a
13152 directory contents without making many round-trips.
13153 This function returns a NULL-terminated array of strings (like
13155 environ(3)), or NULL if there was an error. The caller must free the
13156 strings and the array after use.
13157 (Added in 1.0.77)
13159 guestfs_realpath
13161 char *
13162 guestfs_realpath (guestfs_h *g,
13163 const char *path);
13164 Return the canonicalized absolute pathname of "path". The returned
13166 path has no ".", ".." or symbolic link path elements.
13167 This function returns a string, or NULL on error. The caller must free
13169 the returned string after use.
13170 (Added in 1.0.66)
13172 guestfs_remount
13174 int
13175 guestfs_remount (guestfs_h *g,
13176 const char *mountpoint,
13177 ...);
13178 You may supply a list of optional arguments to this call. Use zero or
13180 more of the following pairs of parameters, and terminate the list with
13181 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13182 GUESTFS_REMOUNT_RW, int rw,
13184 This call allows you to change the "rw" (readonly/read-write) flag on
13186 an already mounted filesystem at "mountpoint", converting a readonly
13187 filesystem to be read-write, or vice-versa.
13188 Note that at the moment you must supply the "optional" "rw" parameter.
13190 In future we may allow other flags to be adjusted.
13191 This function returns 0 on success or -1 on error.
13193 (Added in 1.23.2)
13195 guestfs_remount_va
13197 int
13198 guestfs_remount_va (guestfs_h *g,
13199 const char *mountpoint,
13200 va_list args);
13201 This is the "va_list variant" of "guestfs_remount".
13203 See "CALLS WITH OPTIONAL ARGUMENTS".
13205 guestfs_remount_argv
13207 int
13208 guestfs_remount_argv (guestfs_h *g,
13209 const char *mountpoint,
13210 const struct guestfs_remount_argv *optargs);
13211 This is the "argv variant" of "guestfs_remount".
13213 See "CALLS WITH OPTIONAL ARGUMENTS".
13215 guestfs_remove_drive
13217 int
13218 guestfs_remove_drive (guestfs_h *g,
13219 const char *label);
13220 This function is deprecated. There is no replacement. Consult the API
13222 documentation in guestfs(3) for further information.
13223 Deprecated functions will not be removed from the API, but the fact
13225 that they are deprecated indicates that there are problems with correct
13226 use of these functions.
13227 This call does nothing and returns an error.
13229 This function returns 0 on success or -1 on error.
13231 (Added in 1.19.49)
13233 guestfs_removexattr
13235 int
13236 guestfs_removexattr (guestfs_h *g,
13237 const char *xattr,
13238 const char *path);
13239 This call removes the extended attribute named "xattr" of the file
13241 "path".
13242 See also: "guestfs_lremovexattr", attr(5).
13244 This function returns 0 on success or -1 on error.
13246 This function depends on the feature "linuxxattrs". See also
13248 "guestfs_feature_available".
13249 (Added in 1.0.59)
13251 guestfs_rename
13253 int
13254 guestfs_rename (guestfs_h *g,
13255 const char *oldpath,
13256 const char *newpath);
13257 Rename a file to a new place on the same filesystem. This is the same
13259 as the Linux rename(2) system call. In most cases you are better to
13260 use "guestfs_mv" instead.
13261 This function returns 0 on success or -1 on error.
13263 (Added in 1.21.5)
13265 guestfs_resize2fs
13267 int
13268 guestfs_resize2fs (guestfs_h *g,
13269 const char *device);
13270 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13272 underlying device.
13273 See also "RESIZE2FS ERRORS".
13275 This function returns 0 on success or -1 on error.
13277 (Added in 1.0.27)
13279 guestfs_resize2fs_M
13281 int
13282 guestfs_resize2fs_M (guestfs_h *g,
13283 const char *device);
13284 This command is the same as "guestfs_resize2fs", but the filesystem is
13286 resized to its minimum size. This works like the -M option to the
13287 resize2fs(8) command.
13288 To get the resulting size of the filesystem you should call
13290 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13291 These two numbers, multiplied together, give the resulting size of the
13292 minimal filesystem in bytes.
13293 See also "RESIZE2FS ERRORS".
13295 This function returns 0 on success or -1 on error.
13297 (Added in 1.9.4)
13299 guestfs_resize2fs_size
13301 int
13302 guestfs_resize2fs_size (guestfs_h *g,
13303 const char *device,
13304 int64_t size);
13305 This command is the same as "guestfs_resize2fs" except that it allows
13307 you to specify the new size (in bytes) explicitly.
13308 See also "RESIZE2FS ERRORS".
13310 This function returns 0 on success or -1 on error.
13312 (Added in 1.3.14)
13314 guestfs_rm
13316 int
13317 guestfs_rm (guestfs_h *g,
13318 const char *path);
13319 Remove the single file "path".
13321 This function returns 0 on success or -1 on error.
13323 (Added in 0.8)
13325 guestfs_rm_f
13327 int
13328 guestfs_rm_f (guestfs_h *g,
13329 const char *path);
13330 Remove the file "path".
13332 If the file doesn't exist, that error is ignored. (Other errors, eg.
13334 I/O errors or bad paths, are not ignored)
13335 This call cannot remove directories. Use "guestfs_rmdir" to remove an
13337 empty directory, or "guestfs_rm_rf" to remove directories recursively.
13338 This function returns 0 on success or -1 on error.
13340 (Added in 1.19.42)
13342 guestfs_rm_rf
13344 int
13345 guestfs_rm_rf (guestfs_h *g,
13346 const char *path);
13347 Remove the file or directory "path", recursively removing the contents
13349 if its a directory. This is like the "rm -rf" shell command.
13350 This function returns 0 on success or -1 on error.
13352 (Added in 0.8)
13354 guestfs_rmdir
13356 int
13357 guestfs_rmdir (guestfs_h *g,
13358 const char *path);
13359 Remove the single directory "path".
13361 This function returns 0 on success or -1 on error.
13363 (Added in 0.8)
13365 guestfs_rmmountpoint
13367 int
13368 guestfs_rmmountpoint (guestfs_h *g,
13369 const char *exemptpath);
13370 This call removes a mountpoint that was previously created with
13372 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13373 This function returns 0 on success or -1 on error.
13375 (Added in 1.0.62)
13377 guestfs_rsync
13379 int
13380 guestfs_rsync (guestfs_h *g,
13381 const char *src,
13382 const char *dest,
13383 ...);
13384 You may supply a list of optional arguments to this call. Use zero or
13386 more of the following pairs of parameters, and terminate the list with
13387 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13388 GUESTFS_RSYNC_ARCHIVE, int archive,
13390 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13391 This call may be used to copy or synchronize two directories under the
13393 same libguestfs handle. This uses the rsync(1) program which uses a
13394 fast algorithm that avoids copying files unnecessarily.
13395 "src" and "dest" are the source and destination directories. Files are
13397 copied from "src" to "dest".
13398 The optional arguments are:
13400 "archive"
13402 Turns on archive mode. This is the same as passing the --archive
13403 flag to "rsync".
13404 "deletedest"
13406 Delete files at the destination that do not exist at the source.
13407 This function returns 0 on success or -1 on error.
13409 This function depends on the feature "rsync". See also
13411 "guestfs_feature_available".
13412 (Added in 1.19.29)
13414 guestfs_rsync_va
13416 int
13417 guestfs_rsync_va (guestfs_h *g,
13418 const char *src,
13419 const char *dest,
13420 va_list args);
13421 This is the "va_list variant" of "guestfs_rsync".
13423 See "CALLS WITH OPTIONAL ARGUMENTS".
13425 guestfs_rsync_argv
13427 int
13428 guestfs_rsync_argv (guestfs_h *g,
13429 const char *src,
13430 const char *dest,
13431 const struct guestfs_rsync_argv *optargs);
13432 This is the "argv variant" of "guestfs_rsync".
13434 See "CALLS WITH OPTIONAL ARGUMENTS".
13436 guestfs_rsync_in
13438 int
13439 guestfs_rsync_in (guestfs_h *g,
13440 const char *remote,
13441 const char *dest,
13442 ...);
13443 You may supply a list of optional arguments to this call. Use zero or
13445 more of the following pairs of parameters, and terminate the list with
13446 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13447 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13449 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13450 This call may be used to copy or synchronize the filesystem on the host
13452 or on a remote computer with the filesystem within libguestfs. This
13453 uses the rsync(1) program which uses a fast algorithm that avoids
13454 copying files unnecessarily.
13455 This call only works if the network is enabled. See
13457 "guestfs_set_network" or the --network option to various tools like
13458 guestfish(1).
13459 Files are copied from the remote server and directory specified by
13461 "remote" to the destination directory "dest".
13462 The format of the remote server string is defined by rsync(1). Note
13464 that there is no way to supply a password or passphrase so the target
13465 must be set up not to require one.
13466 The optional arguments are the same as those of "guestfs_rsync".
13468 This function returns 0 on success or -1 on error.
13470 This function depends on the feature "rsync". See also
13472 "guestfs_feature_available".
13473 (Added in 1.19.29)
13475 guestfs_rsync_in_va
13477 int
13478 guestfs_rsync_in_va (guestfs_h *g,
13479 const char *remote,
13480 const char *dest,
13481 va_list args);
13482 This is the "va_list variant" of "guestfs_rsync_in".
13484 See "CALLS WITH OPTIONAL ARGUMENTS".
13486 guestfs_rsync_in_argv
13488 int
13489 guestfs_rsync_in_argv (guestfs_h *g,
13490 const char *remote,
13491 const char *dest,
13492 const struct guestfs_rsync_in_argv *optargs);
13493 This is the "argv variant" of "guestfs_rsync_in".
13495 See "CALLS WITH OPTIONAL ARGUMENTS".
13497 guestfs_rsync_out
13499 int
13500 guestfs_rsync_out (guestfs_h *g,
13501 const char *src,
13502 const char *remote,
13503 ...);
13504 You may supply a list of optional arguments to this call. Use zero or
13506 more of the following pairs of parameters, and terminate the list with
13507 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13508 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13510 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13511 This call may be used to copy or synchronize the filesystem within
13513 libguestfs with a filesystem on the host or on a remote computer. This
13514 uses the rsync(1) program which uses a fast algorithm that avoids
13515 copying files unnecessarily.
13516 This call only works if the network is enabled. See
13518 "guestfs_set_network" or the --network option to various tools like
13519 guestfish(1).
13520 Files are copied from the source directory "src" to the remote server
13522 and directory specified by "remote".
13523 The format of the remote server string is defined by rsync(1). Note
13525 that there is no way to supply a password or passphrase so the target
13526 must be set up not to require one.
13527 The optional arguments are the same as those of "guestfs_rsync".
13529 Globbing does not happen on the "src" parameter. In programs which use
13531 the API directly you have to expand wildcards yourself (see
13532 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13533 (see "glob" in guestfish(1)), for example:
13534 ><fs> glob rsync-out /* rsync://remote/
13536 This function returns 0 on success or -1 on error.
13538 This function depends on the feature "rsync". See also
13540 "guestfs_feature_available".
13541 (Added in 1.19.29)
13543 guestfs_rsync_out_va
13545 int
13546 guestfs_rsync_out_va (guestfs_h *g,
13547 const char *src,
13548 const char *remote,
13549 va_list args);
13550 This is the "va_list variant" of "guestfs_rsync_out".
13552 See "CALLS WITH OPTIONAL ARGUMENTS".
13554 guestfs_rsync_out_argv
13556 int
13557 guestfs_rsync_out_argv (guestfs_h *g,
13558 const char *src,
13559 const char *remote,
13560 const struct guestfs_rsync_out_argv *optargs);
13561 This is the "argv variant" of "guestfs_rsync_out".
13563 See "CALLS WITH OPTIONAL ARGUMENTS".
13565 guestfs_scrub_device
13567 int
13568 guestfs_scrub_device (guestfs_h *g,
13569 const char *device);
13570 This command writes patterns over "device" to make data retrieval more
13572 difficult.
13573 It is an interface to the scrub(1) program. See that manual page for
13575 more details.
13576 This function returns 0 on success or -1 on error.
13578 This function depends on the feature "scrub". See also
13580 "guestfs_feature_available".
13581 (Added in 1.0.52)
13583 guestfs_scrub_file
13585 int
13586 guestfs_scrub_file (guestfs_h *g,
13587 const char *file);
13588 This command writes patterns over a file to make data retrieval more
13590 difficult.
13591 The file is removed after scrubbing.
13593 It is an interface to the scrub(1) program. See that manual page for
13595 more details.
13596 This function returns 0 on success or -1 on error.
13598 This function depends on the feature "scrub". See also
13600 "guestfs_feature_available".
13601 (Added in 1.0.52)
13603 guestfs_scrub_freespace
13605 int
13606 guestfs_scrub_freespace (guestfs_h *g,
13607 const char *dir);
13608 This command creates the directory "dir" and then fills it with files
13610 until the filesystem is full, and scrubs the files as for
13611 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13612 free space on the partition containing "dir".
13613 It is an interface to the scrub(1) program. See that manual page for
13615 more details.
13616 This function returns 0 on success or -1 on error.
13618 This function depends on the feature "scrub". See also
13620 "guestfs_feature_available".
13621 (Added in 1.0.52)
13623 guestfs_selinux_relabel
13625 int
13626 guestfs_selinux_relabel (guestfs_h *g,
13627 const char *specfile,
13628 const char *path,
13629 ...);
13630 You may supply a list of optional arguments to this call. Use zero or
13632 more of the following pairs of parameters, and terminate the list with
13633 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13634 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13636 SELinux relabel parts of the filesystem.
13638 The "specfile" parameter controls the policy spec file used. You have
13640 to parse "/etc/selinux/config" to find the correct SELinux policy and
13641 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13642 "/contexts/files/file_contexts".
13643 The required "path" parameter is the top level directory where
13645 relabelling starts. Normally you should pass "path" as "/" to relabel
13646 the whole guest filesystem.
13647 The optional "force" boolean controls whether the context is reset for
13649 customizable files, and also whether the user, role and range parts of
13650 the file context is changed.
13651 This function returns 0 on success or -1 on error.
13653 This function depends on the feature "selinuxrelabel". See also
13655 "guestfs_feature_available".
13656 (Added in 1.33.43)
13658 guestfs_selinux_relabel_va
13660 int
13661 guestfs_selinux_relabel_va (guestfs_h *g,
13662 const char *specfile,
13663 const char *path,
13664 va_list args);
13665 This is the "va_list variant" of "guestfs_selinux_relabel".
13667 See "CALLS WITH OPTIONAL ARGUMENTS".
13669 guestfs_selinux_relabel_argv
13671 int
13672 guestfs_selinux_relabel_argv (guestfs_h *g,
13673 const char *specfile,
13674 const char *path,
13675 const struct guestfs_selinux_relabel_argv *optargs);
13676 This is the "argv variant" of "guestfs_selinux_relabel".
13678 See "CALLS WITH OPTIONAL ARGUMENTS".
13680 guestfs_set_append
13682 int
13683 guestfs_set_append (guestfs_h *g,
13684 const char *append);
13685 This function is used to add additional options to the libguestfs
13687 appliance kernel command line.
13688 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13690 environment variable.
13691 Setting "append" to "NULL" means no additional options are passed
13693 (libguestfs always adds a few of its own).
13694 This function returns 0 on success or -1 on error.
13696 (Added in 1.0.26)
13698 guestfs_set_attach_method
13700 int
13701 guestfs_set_attach_method (guestfs_h *g,
13702 const char *backend);
13703 This function is deprecated. In new code, use the
13705 "guestfs_set_backend" call instead.
13706 Deprecated functions will not be removed from the API, but the fact
13708 that they are deprecated indicates that there are problems with correct
13709 use of these functions.
13710 Set the method that libguestfs uses to connect to the backend guestfsd
13712 daemon.
13713 See "BACKEND".
13715 This function returns 0 on success or -1 on error.
13717 (Added in 1.9.8)
13719 guestfs_set_autosync
13721 int
13722 guestfs_set_autosync (guestfs_h *g,
13723 int autosync);
13724 If "autosync" is true, this enables autosync. Libguestfs will make a
13726 best effort attempt to make filesystems consistent and synchronized
13727 when the handle is closed (also if the program exits without closing
13728 handles).
13729 This is enabled by default (since libguestfs 1.5.24, previously it was
13731 disabled by default).
13732 This function returns 0 on success or -1 on error.
13734 (Added in 0.3)
13736 guestfs_set_backend
13738 int
13739 guestfs_set_backend (guestfs_h *g,
13740 const char *backend);
13741 Set the method that libguestfs uses to connect to the backend guestfsd
13743 daemon.
13744 This handle property was previously called the "attach method".
13746 See "BACKEND".
13748 This function returns 0 on success or -1 on error.
13750 (Added in 1.21.26)
13752 guestfs_set_backend_setting
13754 int
13755 guestfs_set_backend_setting (guestfs_h *g,
13756 const char *name,
13757 const char *val);
13758 Append "name=value" to the backend settings string list. However if a
13760 string already exists matching "name" or beginning with "name=", then
13761 that setting is replaced.
13762 See "BACKEND", "BACKEND SETTINGS".
13764 This function returns 0 on success or -1 on error.
13766 (Added in 1.27.2)
13768 guestfs_set_backend_settings
13770 int
13771 guestfs_set_backend_settings (guestfs_h *g,
13772 char *const *settings);
13773 Set a list of zero or more settings which are passed through to the
13775 current backend. Each setting is a string which is interpreted in a
13776 backend-specific way, or ignored if not understood by the backend.
13777 The default value is an empty list, unless the environment variable
13779 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13780 This environment variable contains a colon-separated list of settings.
13781 This call replaces all backend settings. If you want to replace a
13783 single backend setting, see "guestfs_set_backend_setting". If you want
13784 to clear a single backend setting, see "guestfs_clear_backend_setting".
13785 See "BACKEND", "BACKEND SETTINGS".
13787 This function returns 0 on success or -1 on error.
13789 (Added in 1.25.24)
13791 guestfs_set_cachedir
13793 int
13794 guestfs_set_cachedir (guestfs_h *g,
13795 const char *cachedir);
13796 Set the directory used by the handle to store the appliance cache, when
13798 using a supermin appliance. The appliance is cached and shared between
13799 all handles which have the same effective user ID.
13800 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13802 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13803 default. Else if "TMPDIR" is set, then that is the default. Else
13804 /var/tmp is the default.
13805 This function returns 0 on success or -1 on error.
13807 (Added in 1.19.58)
13809 guestfs_set_direct
13811 int
13812 guestfs_set_direct (guestfs_h *g,
13813 int direct);
13814 This function is deprecated. In new code, use the
13816 "guestfs_internal_get_console_socket" call instead.
13817 Deprecated functions will not be removed from the API, but the fact
13819 that they are deprecated indicates that there are problems with correct
13820 use of these functions.
13821 If the direct appliance mode flag is enabled, then stdin and stdout are
13823 passed directly through to the appliance once it is launched.
13824 One consequence of this is that log messages aren't caught by the
13826 library and handled by "guestfs_set_log_message_callback", but go
13827 straight to stdout.
13828 You probably don't want to use this unless you know what you are doing.
13830 The default is disabled.
13832 This function returns 0 on success or -1 on error.
13834 (Added in 1.0.72)
13836 guestfs_set_e2attrs
13838 int
13839 guestfs_set_e2attrs (guestfs_h *g,
13840 const char *file,
13841 const char *attrs,
13842 ...);
13843 You may supply a list of optional arguments to this call. Use zero or
13845 more of the following pairs of parameters, and terminate the list with
13846 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13847 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13849 This sets or clears the file attributes "attrs" associated with the
13851 inode file.
13852 "attrs" is a string of characters representing file attributes. See
13854 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13855 attributes can be changed.
13856 If optional boolean "clear" is not present or false, then the "attrs"
13858 listed are set in the inode.
13859 If "clear" is true, then the "attrs" listed are cleared in the inode.
13861 In both cases, other attributes not present in the "attrs" string are
13863 left unchanged.
13864 These attributes are only present when the file is located on an
13866 ext2/3/4 filesystem. Using this call on other filesystem types will
13867 result in an error.
13868 This function returns 0 on success or -1 on error.
13870 (Added in 1.17.31)
13872 guestfs_set_e2attrs_va
13874 int
13875 guestfs_set_e2attrs_va (guestfs_h *g,
13876 const char *file,
13877 const char *attrs,
13878 va_list args);
13879 This is the "va_list variant" of "guestfs_set_e2attrs".
13881 See "CALLS WITH OPTIONAL ARGUMENTS".
13883 guestfs_set_e2attrs_argv
13885 int
13886 guestfs_set_e2attrs_argv (guestfs_h *g,
13887 const char *file,
13888 const char *attrs,
13889 const struct guestfs_set_e2attrs_argv *optargs);
13890 This is the "argv variant" of "guestfs_set_e2attrs".
13892 See "CALLS WITH OPTIONAL ARGUMENTS".
13894 guestfs_set_e2generation
13896 int
13897 guestfs_set_e2generation (guestfs_h *g,
13898 const char *file,
13899 int64_t generation);
13900 This sets the ext2 file generation of a file.
13902 See "guestfs_get_e2generation".
13904 This function returns 0 on success or -1 on error.
13906 (Added in 1.17.31)
13908 guestfs_set_e2label
13910 int
13911 guestfs_set_e2label (guestfs_h *g,
13912 const char *device,
13913 const char *label);
13914 This function is deprecated. In new code, use the "guestfs_set_label"
13916 call instead.
13917 Deprecated functions will not be removed from the API, but the fact
13919 that they are deprecated indicates that there are problems with correct
13920 use of these functions.
13921 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13923 to "label". Filesystem labels are limited to 16 characters.
13924 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13926 return the existing label on a filesystem.
13927 This function returns 0 on success or -1 on error.
13929 (Added in 1.0.15)
13931 guestfs_set_e2uuid
13933 int
13934 guestfs_set_e2uuid (guestfs_h *g,
13935 const char *device,
13936 const char *uuid);
13937 This function is deprecated. In new code, use the "guestfs_set_uuid"
13939 call instead.
13940 Deprecated functions will not be removed from the API, but the fact
13942 that they are deprecated indicates that there are problems with correct
13943 use of these functions.
13944 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
13946 "uuid". The format of the UUID and alternatives such as "clear",
13947 "random" and "time" are described in the tune2fs(8) manpage.
13948 You can use "guestfs_vfs_uuid" to return the existing UUID of a
13950 filesystem.
13951 This function returns 0 on success or -1 on error.
13953 (Added in 1.0.15)
13955 guestfs_set_hv
13957 int
13958 guestfs_set_hv (guestfs_h *g,
13959 const char *hv);
13960 Set the hypervisor binary that we will use. The hypervisor depends on
13962 the backend, but is usually the location of the qemu/KVM hypervisor.
13963 The default is chosen when the library was compiled by the configure
13965 script.
13966 You can also override this by setting the "LIBGUESTFS_HV" environment
13968 variable.
13969 Note that you should call this function as early as possible after
13971 creating the handle. This is because some pre-launch operations depend
13972 on testing qemu features (by running "qemu -help"). If the qemu binary
13973 changes, we don't retest features, and so you might see inconsistent
13974 results. Using the environment variable "LIBGUESTFS_HV" is safest of
13975 all since that picks the qemu binary at the same time as the handle is
13976 created.
13977 This function returns 0 on success or -1 on error.
13979 (Added in 1.23.17)
13981 guestfs_set_identifier
13983 int
13984 guestfs_set_identifier (guestfs_h *g,
13985 const char *identifier);
13986 This is an informative string which the caller may optionally set in
13988 the handle. It is printed in various places, allowing the current
13989 handle to be identified in debugging output.
13990 One important place is when tracing is enabled. If the identifier
13992 string is not an empty string, then trace messages change from this:
13993 libguestfs: trace: get_tmpdir
13995 libguestfs: trace: get_tmpdir = "/tmp"
13996 to this:
13998 libguestfs: trace: ID: get_tmpdir
14000 libguestfs: trace: ID: get_tmpdir = "/tmp"
14001 where "ID" is the identifier string set by this call.
14003 The identifier must only contain alphanumeric ASCII characters,
14005 underscore and minus sign. The default is the empty string.
14006 See also "guestfs_set_program", "guestfs_set_trace",
14008 "guestfs_get_identifier".
14009 This function returns 0 on success or -1 on error.
14011 (Added in 1.31.14)
14013 guestfs_set_label
14015 int
14016 guestfs_set_label (guestfs_h *g,
14017 const char *mountable,
14018 const char *label);
14019 Set the filesystem label on "mountable" to "label".
14021 Only some filesystem types support labels, and libguestfs supports
14023 setting labels on only a subset of these.
14024 ext2, ext3, ext4
14026 Labels are limited to 16 bytes.
14027 NTFS
14029 Labels are limited to 128 unicode characters.
14030 XFS The label is limited to 12 bytes. The filesystem must not be
14032 mounted when trying to set the label.
14033 btrfs
14035 The label is limited to 255 bytes and some characters are not
14036 allowed. Setting the label on a btrfs subvolume will set the label
14037 on its parent filesystem. The filesystem must not be mounted when
14038 trying to set the label.
14039 fat The label is limited to 11 bytes.
14041 swap
14043 The label is limited to 16 bytes.
14044 If there is no support for changing the label for the type of the
14046 specified filesystem, set_label will fail and set errno as ENOTSUP.
14047 To read the label on a filesystem, call "guestfs_vfs_label".
14049 This function returns 0 on success or -1 on error.
14051 (Added in 1.17.9)
14053 guestfs_set_libvirt_requested_credential
14055 int
14056 guestfs_set_libvirt_requested_credential (guestfs_h *g,
14057 int index,
14058 const char *cred,
14059 size_t cred_size);
14060 After requesting the "index"'th credential from the user, call this
14062 function to pass the answer back to libvirt.
14063 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14065 This function returns 0 on success or -1 on error.
14067 (Added in 1.19.52)
14069 guestfs_set_libvirt_supported_credentials
14071 int
14072 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
14073 char *const *creds);
14074 Call this function before setting an event handler for
14076 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
14077 that the program knows how to process.
14078 The "creds" list must be a non-empty list of strings. Possible strings
14080 are:
14081 "username"
14083 "authname"
14084 "language"
14085 "cnonce"
14086 "passphrase"
14087 "echoprompt"
14088 "noechoprompt"
14089 "realm"
14090 "external"
14091 See libvirt documentation for the meaning of these credential types.
14093 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14095 This function returns 0 on success or -1 on error.
14097 (Added in 1.19.52)
14099 guestfs_set_memsize
14101 int
14102 guestfs_set_memsize (guestfs_h *g,
14103 int memsize);
14104 This sets the memory size in megabytes allocated to the hypervisor.
14106 This only has any effect if called before "guestfs_launch".
14107 You can also change this by setting the environment variable
14109 "LIBGUESTFS_MEMSIZE" before the handle is created.
14110 For more information on the architecture of libguestfs, see guestfs(3).
14112 This function returns 0 on success or -1 on error.
14114 (Added in 1.0.55)
14116 guestfs_set_network
14118 int
14119 guestfs_set_network (guestfs_h *g,
14120 int network);
14121 If "network" is true, then the network is enabled in the libguestfs
14123 appliance. The default is false.
14124 This affects whether commands are able to access the network (see
14126 "RUNNING COMMANDS").
14127 You must call this before calling "guestfs_launch", otherwise it has no
14129 effect.
14130 This function returns 0 on success or -1 on error.
14132 (Added in 1.5.4)
14134 guestfs_set_path
14136 int
14137 guestfs_set_path (guestfs_h *g,
14138 const char *searchpath);
14139 Set the path that libguestfs searches for kernel and initrd.img.
14141 The default is "$libdir/guestfs" unless overridden by setting
14143 "LIBGUESTFS_PATH" environment variable.
14144 Setting "path" to "NULL" restores the default path.
14146 This function returns 0 on success or -1 on error.
14148 (Added in 0.3)
14150 guestfs_set_pgroup
14152 int
14153 guestfs_set_pgroup (guestfs_h *g,
14154 int pgroup);
14155 If "pgroup" is true, child processes are placed into their own process
14157 group.
14158 The practical upshot of this is that signals like "SIGINT" (from users
14160 pressing "^C") won't be received by the child process.
14161 The default for this flag is false, because usually you want "^C" to
14163 kill the subprocess. Guestfish sets this flag to true when used
14164 interactively, so that "^C" can cancel long-running commands gracefully
14165 (see "guestfs_user_cancel").
14166 This function returns 0 on success or -1 on error.
14168 (Added in 1.11.18)
14170 guestfs_set_program
14172 int
14173 guestfs_set_program (guestfs_h *g,
14174 const char *program);
14175 Set the program name. This is an informative string which the main
14177 program may optionally set in the handle.
14178 When the handle is created, the program name in the handle is set to
14180 the basename from "argv[0]". The program name can never be "NULL".
14181 This function returns 0 on success or -1 on error.
14183 (Added in 1.21.29)
14185 guestfs_set_qemu
14187 int
14188 guestfs_set_qemu (guestfs_h *g,
14189 const char *hv);
14190 This function is deprecated. In new code, use the "guestfs_set_hv"
14192 call instead.
14193 Deprecated functions will not be removed from the API, but the fact
14195 that they are deprecated indicates that there are problems with correct
14196 use of these functions.
14197 Set the hypervisor binary (usually qemu) that we will use.
14199 The default is chosen when the library was compiled by the configure
14201 script.
14202 You can also override this by setting the "LIBGUESTFS_HV" environment
14204 variable.
14205 Setting "hv" to "NULL" restores the default qemu binary.
14207 Note that you should call this function as early as possible after
14209 creating the handle. This is because some pre-launch operations depend
14210 on testing qemu features (by running "qemu -help"). If the qemu binary
14211 changes, we don't retest features, and so you might see inconsistent
14212 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14213 all since that picks the qemu binary at the same time as the handle is
14214 created.
14215 This function returns 0 on success or -1 on error.
14217 (Added in 1.0.6)
14219 guestfs_set_recovery_proc
14221 int
14222 guestfs_set_recovery_proc (guestfs_h *g,
14223 int recoveryproc);
14224 If this is called with the parameter "false" then "guestfs_launch" does
14226 not create a recovery process. The purpose of the recovery process is
14227 to stop runaway hypervisor processes in the case where the main program
14228 aborts abruptly.
14229 This only has any effect if called before "guestfs_launch", and the
14231 default is true.
14232 About the only time when you would want to disable this is if the main
14234 process will fork itself into the background ("daemonize" itself). In
14235 this case the recovery process thinks that the main program has
14236 disappeared and so kills the hypervisor, which is not very helpful.
14237 This function returns 0 on success or -1 on error.
14239 (Added in 1.0.77)
14241 guestfs_set_selinux
14243 int
14244 guestfs_set_selinux (guestfs_h *g,
14245 int selinux);
14246 This function is deprecated. In new code, use the
14248 "guestfs_selinux_relabel" call instead.
14249 Deprecated functions will not be removed from the API, but the fact
14251 that they are deprecated indicates that there are problems with correct
14252 use of these functions.
14253 This sets the selinux flag that is passed to the appliance at boot
14255 time. The default is "selinux=0" (disabled).
14256 Note that if SELinux is enabled, it is always in Permissive mode
14258 ("enforcing=0").
14259 For more information on the architecture of libguestfs, see guestfs(3).
14261 This function returns 0 on success or -1 on error.
14263 (Added in 1.0.67)
14265 guestfs_set_smp
14267 int
14268 guestfs_set_smp (guestfs_h *g,
14269 int smp);
14270 Change the number of virtual CPUs assigned to the appliance. The
14272 default is 1. Increasing this may improve performance, though often it
14273 has no effect.
14274 This function must be called before "guestfs_launch".
14276 This function returns 0 on success or -1 on error.
14278 (Added in 1.13.15)
14280 guestfs_set_tmpdir
14282 int
14283 guestfs_set_tmpdir (guestfs_h *g,
14284 const char *tmpdir);
14285 Set the directory used by the handle to store temporary files.
14287 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14289 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14290 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
14291 default.
14292 This function returns 0 on success or -1 on error.
14294 (Added in 1.19.58)
14296 guestfs_set_trace
14298 int
14299 guestfs_set_trace (guestfs_h *g,
14300 int trace);
14301 If the command trace flag is set to 1, then libguestfs calls,
14303 parameters and return values are traced.
14304 If you want to trace C API calls into libguestfs (and other libraries)
14306 then possibly a better way is to use the external ltrace(1) command.
14307 Command traces are disabled unless the environment variable
14309 "LIBGUESTFS_TRACE" is defined and set to 1.
14310 Trace messages are normally sent to "stderr", unless you register a
14312 callback to send them somewhere else (see
14313 "guestfs_set_event_callback").
14314 This function returns 0 on success or -1 on error.
14316 (Added in 1.0.69)
14318 guestfs_set_uuid
14320 int
14321 guestfs_set_uuid (guestfs_h *g,
14322 const char *device,
14323 const char *uuid);
14324 Set the filesystem UUID on "device" to "uuid". If this fails and the
14326 errno is ENOTSUP, means that there is no support for changing the UUID
14327 for the type of the specified filesystem.
14328 Only some filesystem types support setting UUIDs.
14330 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14332 This function returns 0 on success or -1 on error.
14334 (Added in 1.23.10)
14336 guestfs_set_uuid_random
14338 int
14339 guestfs_set_uuid_random (guestfs_h *g,
14340 const char *device);
14341 Set the filesystem UUID on "device" to a random UUID. If this fails
14343 and the errno is ENOTSUP, means that there is no support for changing
14344 the UUID for the type of the specified filesystem.
14345 Only some filesystem types support setting UUIDs.
14347 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14349 This function returns 0 on success or -1 on error.
14351 (Added in 1.29.50)
14353 guestfs_set_verbose
14355 int
14356 guestfs_set_verbose (guestfs_h *g,
14357 int verbose);
14358 If "verbose" is true, this turns on verbose messages.
14360 Verbose messages are disabled unless the environment variable
14362 "LIBGUESTFS_DEBUG" is defined and set to 1.
14363 Verbose messages are normally sent to "stderr", unless you register a
14365 callback to send them somewhere else (see
14366 "guestfs_set_event_callback").
14367 This function returns 0 on success or -1 on error.
14369 (Added in 0.3)
14371 guestfs_setcon
14373 int
14374 guestfs_setcon (guestfs_h *g,
14375 const char *context);
14376 This function is deprecated. In new code, use the
14378 "guestfs_selinux_relabel" call instead.
14379 Deprecated functions will not be removed from the API, but the fact
14381 that they are deprecated indicates that there are problems with correct
14382 use of these functions.
14383 This sets the SELinux security context of the daemon to the string
14385 "context".
14386 See the documentation about SELINUX in guestfs(3).
14388 This function returns 0 on success or -1 on error.
14390 This function depends on the feature "selinux". See also
14392 "guestfs_feature_available".
14393 (Added in 1.0.67)
14395 guestfs_setxattr
14397 int
14398 guestfs_setxattr (guestfs_h *g,
14399 const char *xattr,
14400 const char *val,
14401 int vallen,
14402 const char *path);
14403 This call sets the extended attribute named "xattr" of the file "path"
14405 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14406 data.
14407 See also: "guestfs_lsetxattr", attr(5).
14409 This function returns 0 on success or -1 on error.
14411 This function depends on the feature "linuxxattrs". See also
14413 "guestfs_feature_available".
14414 (Added in 1.0.59)
14416 guestfs_sfdisk
14418 int
14419 guestfs_sfdisk (guestfs_h *g,
14420 const char *device,
14421 int cyls,
14422 int heads,
14423 int sectors,
14424 char *const *lines);
14425 This function is deprecated. In new code, use the "guestfs_part_add"
14427 call instead.
14428 Deprecated functions will not be removed from the API, but the fact
14430 that they are deprecated indicates that there are problems with correct
14431 use of these functions.
14432 This is a direct interface to the sfdisk(8) program for creating
14434 partitions on block devices.
14435 "device" should be a block device, for example /dev/sda.
14437 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14439 sectors on the device, which are passed directly to sfdisk(8) as the
14440 -C, -H and -S parameters. If you pass 0 for any of these, then the
14441 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14442 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
14443 (or rather, the kernel) cannot work out the right geometry and you will
14444 need to tell it.
14445 "lines" is a list of lines that we feed to sfdisk(8). For more
14447 information refer to the sfdisk(8) manpage.
14448 To create a single partition occupying the whole disk, you would pass
14450 "lines" as a single element list, when the single element being the
14451 string "," (comma).
14452 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14454 This function returns 0 on success or -1 on error.
14456 (Added in 0.8)
14458 guestfs_sfdiskM
14460 int
14461 guestfs_sfdiskM (guestfs_h *g,
14462 const char *device,
14463 char *const *lines);
14464 This function is deprecated. In new code, use the "guestfs_part_add"
14466 call instead.
14467 Deprecated functions will not be removed from the API, but the fact
14469 that they are deprecated indicates that there are problems with correct
14470 use of these functions.
14471 This is a simplified interface to the "guestfs_sfdisk" command, where
14473 partition sizes are specified in megabytes only (rounded to the nearest
14474 cylinder) and you don't need to specify the cyls, heads and sectors
14475 parameters which were rarely if ever used anyway.
14476 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14478 "guestfs_part_disk"
14479 This function returns 0 on success or -1 on error.
14481 (Added in 1.0.55)
14483 guestfs_sfdisk_N
14485 int
14486 guestfs_sfdisk_N (guestfs_h *g,
14487 const char *device,
14488 int partnum,
14489 int cyls,
14490 int heads,
14491 int sectors,
14492 const char *line);
14493 This function is deprecated. In new code, use the "guestfs_part_add"
14495 call instead.
14496 Deprecated functions will not be removed from the API, but the fact
14498 that they are deprecated indicates that there are problems with correct
14499 use of these functions.
14500 This runs sfdisk(8) option to modify just the single partition "n"
14502 (note: "n" counts from 1).
14503 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14505 for the cyls/heads/sectors parameters.
14506 See also: "guestfs_part_add"
14508 This function returns 0 on success or -1 on error.
14510 (Added in 1.0.26)
14512 guestfs_sfdisk_disk_geometry
14514 char *
14515 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14516 const char *device);
14517 This displays the disk geometry of "device" read from the partition
14519 table. Especially in the case where the underlying block device has
14520 been resized, this can be different from the kernel’s idea of the
14521 geometry (see "guestfs_sfdisk_kernel_geometry").
14522 The result is in human-readable format, and not designed to be parsed.
14524 This function returns a string, or NULL on error. The caller must free
14526 the returned string after use.
14527 (Added in 1.0.26)
14529 guestfs_sfdisk_kernel_geometry
14531 char *
14532 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14533 const char *device);
14534 This displays the kernel’s idea of the geometry of "device".
14536 The result is in human-readable format, and not designed to be parsed.
14538 This function returns a string, or NULL on error. The caller must free
14540 the returned string after use.
14541 (Added in 1.0.26)
14543 guestfs_sfdisk_l
14545 char *
14546 guestfs_sfdisk_l (guestfs_h *g,
14547 const char *device);
14548 This function is deprecated. In new code, use the "guestfs_part_list"
14550 call instead.
14551 Deprecated functions will not be removed from the API, but the fact
14553 that they are deprecated indicates that there are problems with correct
14554 use of these functions.
14555 This displays the partition table on "device", in the human-readable
14557 output of the sfdisk(8) command. It is not intended to be parsed.
14558 See also: "guestfs_part_list"
14560 This function returns a string, or NULL on error. The caller must free
14562 the returned string after use.
14563 (Added in 1.0.26)
14565 guestfs_sh
14567 char *
14568 guestfs_sh (guestfs_h *g,
14569 const char *command);
14570 This call runs a command from the guest filesystem via the guest’s
14572 /bin/sh.
14573 This is like "guestfs_command", but passes the command to:
14575 /bin/sh -c "command"
14577 Depending on the guest’s shell, this usually results in wildcards being
14579 expanded, shell expressions being interpolated and so on.
14580 All the provisos about "guestfs_command" apply to this call.
14582 This function returns a string, or NULL on error. The caller must free
14584 the returned string after use.
14585 (Added in 1.0.50)
14587 guestfs_sh_lines
14589 char **
14590 guestfs_sh_lines (guestfs_h *g,
14591 const char *command);
14592 This is the same as "guestfs_sh", but splits the result into a list of
14594 lines.
14595 See also: "guestfs_command_lines"
14597 This function returns a NULL-terminated array of strings (like
14599 environ(3)), or NULL if there was an error. The caller must free the
14600 strings and the array after use.
14601 (Added in 1.0.50)
14603 guestfs_shutdown
14605 int
14606 guestfs_shutdown (guestfs_h *g);
14607 This is the opposite of "guestfs_launch". It performs an orderly
14609 shutdown of the backend process(es). If the autosync flag is set
14610 (which is the default) then the disk image is synchronized.
14611 If the subprocess exits with an error then this function will return an
14613 error, which should not be ignored (it may indicate that the disk image
14614 could not be written out properly).
14615 It is safe to call this multiple times. Extra calls are ignored.
14617 This call does not close or free up the handle. You still need to call
14619 "guestfs_close" afterwards.
14620 "guestfs_close" will call this if you don't do it explicitly, but note
14622 that any errors are ignored in that case.
14623 This function returns 0 on success or -1 on error.
14625 (Added in 1.19.16)
14627 guestfs_sleep
14629 int
14630 guestfs_sleep (guestfs_h *g,
14631 int secs);
14632 Sleep for "secs" seconds.
14634 This function returns 0 on success or -1 on error.
14636 (Added in 1.0.41)
14638 guestfs_stat
14640 struct guestfs_stat *
14641 guestfs_stat (guestfs_h *g,
14642 const char *path);
14643 This function is deprecated. In new code, use the "guestfs_statns"
14645 call instead.
14646 Deprecated functions will not be removed from the API, but the fact
14648 that they are deprecated indicates that there are problems with correct
14649 use of these functions.
14650 Returns file information for the given "path".
14652 This is the same as the stat(2) system call.
14654 This function returns a "struct guestfs_stat *", or NULL if there was
14656 an error. The caller must call "guestfs_free_stat" after use.
14657 (Added in 1.9.2)
14659 guestfs_statns
14661 struct guestfs_statns *
14662 guestfs_statns (guestfs_h *g,
14663 const char *path);
14664 Returns file information for the given "path".
14666 This is the same as the stat(2) system call.
14668 This function returns a "struct guestfs_statns *", or NULL if there was
14670 an error. The caller must call "guestfs_free_statns" after use.
14671 (Added in 1.27.53)
14673 guestfs_statvfs
14675 struct guestfs_statvfs *
14676 guestfs_statvfs (guestfs_h *g,
14677 const char *path);
14678 Returns file system statistics for any mounted file system. "path"
14680 should be a file or directory in the mounted file system (typically it
14681 is the mount point itself, but it doesn't need to be).
14682 This is the same as the statvfs(2) system call.
14684 This function returns a "struct guestfs_statvfs *", or NULL if there
14686 was an error. The caller must call "guestfs_free_statvfs" after use.
14687 (Added in 1.9.2)
14689 guestfs_strings
14691 char **
14692 guestfs_strings (guestfs_h *g,
14693 const char *path);
14694 This runs the strings(1) command on a file and returns the list of
14696 printable strings found.
14697 The "strings" command has, in the past, had problems with parsing
14699 untrusted files. These are mitigated in the current version of
14700 libguestfs, but see "CVE-2014-8484".
14701 This function returns a NULL-terminated array of strings (like
14703 environ(3)), or NULL if there was an error. The caller must free the
14704 strings and the array after use.
14705 Because of the message protocol, there is a transfer limit of somewhere
14707 between 2MB and 4MB. See "PROTOCOL LIMITS".
14708 (Added in 1.0.22)
14710 guestfs_strings_e
14712 char **
14713 guestfs_strings_e (guestfs_h *g,
14714 const char *encoding,
14715 const char *path);
14716 This is like the "guestfs_strings" command, but allows you to specify
14718 the encoding of strings that are looked for in the source file "path".
14719 Allowed encodings are:
14721 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14723 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14724 S Single 8-bit-byte characters.
14726 b 16-bit big endian strings such as those encoded in UTF-16BE or
14728 UCS-2BE.
14729 l (lower case letter L)
14731 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14732 for examining binaries in Windows guests.
14733 B 32-bit big endian such as UCS-4BE.
14735 L 32-bit little endian such as UCS-4LE.
14737 The returned strings are transcoded to UTF-8.
14739 The "strings" command has, in the past, had problems with parsing
14741 untrusted files. These are mitigated in the current version of
14742 libguestfs, but see "CVE-2014-8484".
14743 This function returns a NULL-terminated array of strings (like
14745 environ(3)), or NULL if there was an error. The caller must free the
14746 strings and the array after use.
14747 Because of the message protocol, there is a transfer limit of somewhere
14749 between 2MB and 4MB. See "PROTOCOL LIMITS".
14750 (Added in 1.0.22)
14752 guestfs_swapoff_device
14754 int
14755 guestfs_swapoff_device (guestfs_h *g,
14756 const char *device);
14757 This command disables the libguestfs appliance swap device or partition
14759 named "device". See "guestfs_swapon_device".
14760 This function returns 0 on success or -1 on error.
14762 (Added in 1.0.66)
14764 guestfs_swapoff_file
14766 int
14767 guestfs_swapoff_file (guestfs_h *g,
14768 const char *file);
14769 This command disables the libguestfs appliance swap on file.
14771 This function returns 0 on success or -1 on error.
14773 (Added in 1.0.66)
14775 guestfs_swapoff_label
14777 int
14778 guestfs_swapoff_label (guestfs_h *g,
14779 const char *label);
14780 This command disables the libguestfs appliance swap on labeled swap
14782 partition.
14783 This function returns 0 on success or -1 on error.
14785 (Added in 1.0.66)
14787 guestfs_swapoff_uuid
14789 int
14790 guestfs_swapoff_uuid (guestfs_h *g,
14791 const char *uuid);
14792 This command disables the libguestfs appliance swap partition with the
14794 given UUID.
14795 This function returns 0 on success or -1 on error.
14797 This function depends on the feature "linuxfsuuid". See also
14799 "guestfs_feature_available".
14800 (Added in 1.0.66)
14802 guestfs_swapon_device
14804 int
14805 guestfs_swapon_device (guestfs_h *g,
14806 const char *device);
14807 This command enables the libguestfs appliance to use the swap device or
14809 partition named "device". The increased memory is made available for
14810 all commands, for example those run using "guestfs_command" or
14811 "guestfs_sh".
14812 Note that you should not swap to existing guest swap partitions unless
14814 you know what you are doing. They may contain hibernation information,
14815 or other information that the guest doesn't want you to trash. You
14816 also risk leaking information about the host to the guest this way.
14817 Instead, attach a new host device to the guest and swap on that.
14818 This function returns 0 on success or -1 on error.
14820 (Added in 1.0.66)
14822 guestfs_swapon_file
14824 int
14825 guestfs_swapon_file (guestfs_h *g,
14826 const char *file);
14827 This command enables swap to a file. See "guestfs_swapon_device" for
14829 other notes.
14830 This function returns 0 on success or -1 on error.
14832 (Added in 1.0.66)
14834 guestfs_swapon_label
14836 int
14837 guestfs_swapon_label (guestfs_h *g,
14838 const char *label);
14839 This command enables swap to a labeled swap partition. See
14841 "guestfs_swapon_device" for other notes.
14842 This function returns 0 on success or -1 on error.
14844 (Added in 1.0.66)
14846 guestfs_swapon_uuid
14848 int
14849 guestfs_swapon_uuid (guestfs_h *g,
14850 const char *uuid);
14851 This command enables swap to a swap partition with the given UUID. See
14853 "guestfs_swapon_device" for other notes.
14854 This function returns 0 on success or -1 on error.
14856 This function depends on the feature "linuxfsuuid". See also
14858 "guestfs_feature_available".
14859 (Added in 1.0.66)
14861 guestfs_sync
14863 int
14864 guestfs_sync (guestfs_h *g);
14865 This syncs the disk, so that any writes are flushed through to the
14867 underlying disk image.
14868 You should always call this if you have modified a disk image, before
14870 closing the handle.
14871 This function returns 0 on success or -1 on error.
14873 (Added in 0.3)
14875 guestfs_syslinux
14877 int
14878 guestfs_syslinux (guestfs_h *g,
14879 const char *device,
14880 ...);
14881 You may supply a list of optional arguments to this call. Use zero or
14883 more of the following pairs of parameters, and terminate the list with
14884 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14885 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14887 Install the SYSLINUX bootloader on "device".
14889 The device parameter must be either a whole disk formatted as a FAT
14891 filesystem, or a partition formatted as a FAT filesystem. In the
14892 latter case, the partition should be marked as "active"
14893 ("guestfs_part_set_bootable") and a Master Boot Record must be
14894 installed (eg. using "guestfs_pwrite_device") on the first sector of
14895 the whole disk. The SYSLINUX package comes with some suitable Master
14896 Boot Records. See the syslinux(1) man page for further information.
14897 The optional arguments are:
14899 directory
14901 Install SYSLINUX in the named subdirectory, instead of in the root
14902 directory of the FAT filesystem.
14903 Additional configuration can be supplied to SYSLINUX by placing a file
14905 called syslinux.cfg on the FAT filesystem, either in the root
14906 directory, or under directory if that optional argument is being used.
14907 For further information about the contents of this file, see
14908 syslinux(1).
14909 See also "guestfs_extlinux".
14911 This function returns 0 on success or -1 on error.
14913 This function depends on the feature "syslinux". See also
14915 "guestfs_feature_available".
14916 (Added in 1.21.27)
14918 guestfs_syslinux_va
14920 int
14921 guestfs_syslinux_va (guestfs_h *g,
14922 const char *device,
14923 va_list args);
14924 This is the "va_list variant" of "guestfs_syslinux".
14926 See "CALLS WITH OPTIONAL ARGUMENTS".
14928 guestfs_syslinux_argv
14930 int
14931 guestfs_syslinux_argv (guestfs_h *g,
14932 const char *device,
14933 const struct guestfs_syslinux_argv *optargs);
14934 This is the "argv variant" of "guestfs_syslinux".
14936 See "CALLS WITH OPTIONAL ARGUMENTS".
14938 guestfs_tail
14940 char **
14941 guestfs_tail (guestfs_h *g,
14942 const char *path);
14943 This command returns up to the last 10 lines of a file as a list of
14945 strings.
14946 This function returns a NULL-terminated array of strings (like
14948 environ(3)), or NULL if there was an error. The caller must free the
14949 strings and the array after use.
14950 Because of the message protocol, there is a transfer limit of somewhere
14952 between 2MB and 4MB. See "PROTOCOL LIMITS".
14953 (Added in 1.0.54)
14955 guestfs_tail_n
14957 char **
14958 guestfs_tail_n (guestfs_h *g,
14959 int nrlines,
14960 const char *path);
14961 If the parameter "nrlines" is a positive number, this returns the last
14963 "nrlines" lines of the file "path".
14964 If the parameter "nrlines" is a negative number, this returns lines
14966 from the file "path", starting with the "-nrlines"'th line.
14967 If the parameter "nrlines" is zero, this returns an empty list.
14969 This function returns a NULL-terminated array of strings (like
14971 environ(3)), or NULL if there was an error. The caller must free the
14972 strings and the array after use.
14973 Because of the message protocol, there is a transfer limit of somewhere
14975 between 2MB and 4MB. See "PROTOCOL LIMITS".
14976 (Added in 1.0.54)
14978 guestfs_tar_in
14980 int
14981 guestfs_tar_in (guestfs_h *g,
14982 const char *tarfile,
14983 const char *directory);
14984 This function is provided for backwards compatibility with earlier
14986 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
14987 optional arguments.
14988 (Added in 1.0.3)
14990 guestfs_tar_in_opts
14992 int
14993 guestfs_tar_in_opts (guestfs_h *g,
14994 const char *tarfile,
14995 const char *directory,
14996 ...);
14997 You may supply a list of optional arguments to this call. Use zero or
14999 more of the following pairs of parameters, and terminate the list with
15000 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15001 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
15003 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
15004 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
15005 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
15006 This command uploads and unpacks local file "tarfile" into directory.
15008 The optional "compress" flag controls compression. If not given, then
15010 the input should be an uncompressed tar file. Otherwise one of the
15011 following strings may be given to select the compression type of the
15012 input file: "compress", "gzip", "bzip2", "xz", "lzop", "lzma", "zstd".
15013 (Note that not all builds of libguestfs will support all of these
15014 compression types).
15015 The other optional arguments are:
15017 "xattrs"
15019 If set to true, extended attributes are restored from the tar file.
15020 "selinux"
15022 If set to true, SELinux contexts are restored from the tar file.
15023 "acls"
15025 If set to true, POSIX ACLs are restored from the tar file.
15026 This function returns 0 on success or -1 on error.
15028 (Added in 1.0.3)
15030 guestfs_tar_in_opts_va
15032 int
15033 guestfs_tar_in_opts_va (guestfs_h *g,
15034 const char *tarfile,
15035 const char *directory,
15036 va_list args);
15037 This is the "va_list variant" of "guestfs_tar_in_opts".
15039 See "CALLS WITH OPTIONAL ARGUMENTS".
15041 guestfs_tar_in_opts_argv
15043 int
15044 guestfs_tar_in_opts_argv (guestfs_h *g,
15045 const char *tarfile,
15046 const char *directory,
15047 const struct guestfs_tar_in_opts_argv *optargs);
15048 This is the "argv variant" of "guestfs_tar_in_opts".
15050 See "CALLS WITH OPTIONAL ARGUMENTS".
15052 guestfs_tar_out
15054 int
15055 guestfs_tar_out (guestfs_h *g,
15056 const char *directory,
15057 const char *tarfile);
15058 This function is provided for backwards compatibility with earlier
15060 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
15061 optional arguments.
15062 (Added in 1.0.3)
15064 guestfs_tar_out_opts
15066 int
15067 guestfs_tar_out_opts (guestfs_h *g,
15068 const char *directory,
15069 const char *tarfile,
15070 ...);
15071 You may supply a list of optional arguments to this call. Use zero or
15073 more of the following pairs of parameters, and terminate the list with
15074 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15075 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
15077 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
15078 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
15079 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
15080 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
15081 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
15082 This command packs the contents of directory and downloads it to local
15084 file "tarfile".
15085 The optional "compress" flag controls compression. If not given, then
15087 the output will be an uncompressed tar file. Otherwise one of the
15088 following strings may be given to select the compression type of the
15089 output file: "compress", "gzip", "bzip2", "xz", "lzop", "lzma", "zstd".
15090 (Note that not all builds of libguestfs will support all of these
15091 compression types).
15092 The other optional arguments are:
15094 "excludes"
15096 A list of wildcards. Files are excluded if they match any of the
15097 wildcards.
15098 "numericowner"
15100 If set to true, the output tar file will contain UID/GID numbers
15101 instead of user/group names.
15102 "xattrs"
15104 If set to true, extended attributes are saved in the output tar.
15105 "selinux"
15107 If set to true, SELinux contexts are saved in the output tar.
15108 "acls"
15110 If set to true, POSIX ACLs are saved in the output tar.
15111 This function returns 0 on success or -1 on error.
15113 (Added in 1.0.3)
15115 guestfs_tar_out_opts_va
15117 int
15118 guestfs_tar_out_opts_va (guestfs_h *g,
15119 const char *directory,
15120 const char *tarfile,
15121 va_list args);
15122 This is the "va_list variant" of "guestfs_tar_out_opts".
15124 See "CALLS WITH OPTIONAL ARGUMENTS".
15126 guestfs_tar_out_opts_argv
15128 int
15129 guestfs_tar_out_opts_argv (guestfs_h *g,
15130 const char *directory,
15131 const char *tarfile,
15132 const struct guestfs_tar_out_opts_argv *optargs);
15133 This is the "argv variant" of "guestfs_tar_out_opts".
15135 See "CALLS WITH OPTIONAL ARGUMENTS".
15137 guestfs_tgz_in
15139 int
15140 guestfs_tgz_in (guestfs_h *g,
15141 const char *tarball,
15142 const char *directory);
15143 This function is deprecated. In new code, use the "guestfs_tar_in"
15145 call instead.
15146 Deprecated functions will not be removed from the API, but the fact
15148 that they are deprecated indicates that there are problems with correct
15149 use of these functions.
15150 This command uploads and unpacks local file "tarball" (a gzip
15152 compressed tar file) into directory.
15153 This function returns 0 on success or -1 on error.
15155 (Added in 1.0.3)
15157 guestfs_tgz_out
15159 int
15160 guestfs_tgz_out (guestfs_h *g,
15161 const char *directory,
15162 const char *tarball);
15163 This function is deprecated. In new code, use the "guestfs_tar_out"
15165 call instead.
15166 Deprecated functions will not be removed from the API, but the fact
15168 that they are deprecated indicates that there are problems with correct
15169 use of these functions.
15170 This command packs the contents of directory and downloads it to local
15172 file "tarball".
15173 This function returns 0 on success or -1 on error.
15175 (Added in 1.0.3)
15177 guestfs_touch
15179 int
15180 guestfs_touch (guestfs_h *g,
15181 const char *path);
15182 Touch acts like the touch(1) command. It can be used to update the
15184 timestamps on a file, or, if the file does not exist, to create a new
15185 zero-length file.
15186 This command only works on regular files, and will fail on other file
15188 types such as directories, symbolic links, block special etc.
15189 This function returns 0 on success or -1 on error.
15191 (Added in 0.3)
15193 guestfs_truncate
15195 int
15196 guestfs_truncate (guestfs_h *g,
15197 const char *path);
15198 This command truncates "path" to a zero-length file. The file must
15200 exist already.
15201 This function returns 0 on success or -1 on error.
15203 (Added in 1.0.77)
15205 guestfs_truncate_size
15207 int
15208 guestfs_truncate_size (guestfs_h *g,
15209 const char *path,
15210 int64_t size);
15211 This command truncates "path" to size "size" bytes. The file must
15213 exist already.
15214 If the current file size is less than "size" then the file is extended
15216 to the required size with zero bytes. This creates a sparse file (ie.
15217 disk blocks are not allocated for the file until you write to it). To
15218 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15219 This function returns 0 on success or -1 on error.
15221 (Added in 1.0.77)
15223 guestfs_tune2fs
15225 int
15226 guestfs_tune2fs (guestfs_h *g,
15227 const char *device,
15228 ...);
15229 You may supply a list of optional arguments to this call. Use zero or
15231 more of the following pairs of parameters, and terminate the list with
15232 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15233 GUESTFS_TUNE2FS_FORCE, int force,
15235 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15236 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15237 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15238 GUESTFS_TUNE2FS_GROUP, int64_t group,
15239 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15240 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15241 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15242 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15243 GUESTFS_TUNE2FS_USER, int64_t user,
15244 This call allows you to adjust various filesystem parameters of an
15246 ext2/ext3/ext4 filesystem called "device".
15247 The optional parameters are:
15249 "force"
15251 Force tune2fs to complete the operation even in the face of errors.
15252 This is the same as the tune2fs(8) "-f" option.
15253 "maxmountcount"
15255 Set the number of mounts after which the filesystem is checked by
15256 e2fsck(8). If this is 0 then the number of mounts is disregarded.
15257 This is the same as the tune2fs(8) "-c" option.
15258 "mountcount"
15260 Set the number of times the filesystem has been mounted. This is
15261 the same as the tune2fs(8) "-C" option.
15262 "errorbehavior"
15264 Change the behavior of the kernel code when errors are detected.
15265 Possible values currently are: "continue", "remount-ro", "panic".
15266 In practice these options don't really make any difference,
15267 particularly for write errors.
15268 This is the same as the tune2fs(8) "-e" option.
15270 "group"
15272 Set the group which can use reserved filesystem blocks. This is
15273 the same as the tune2fs(8) "-g" option except that it can only be
15274 specified as a number.
15275 "intervalbetweenchecks"
15277 Adjust the maximal time between two filesystem checks (in seconds).
15278 If the option is passed as 0 then time-dependent checking is
15279 disabled.
15280 This is the same as the tune2fs(8) "-i" option.
15282 "reservedblockspercentage"
15284 Set the percentage of the filesystem which may only be allocated by
15285 privileged processes. This is the same as the tune2fs(8) "-m"
15286 option.
15287 "lastmounteddirectory"
15289 Set the last mounted directory. This is the same as the tune2fs(8)
15290 "-M" option.
15291 "reservedblockscount" Set the number of reserved filesystem blocks.
15293 This is the same as the tune2fs(8) "-r" option.
15294 "user"
15295 Set the user who can use the reserved filesystem blocks. This is
15296 the same as the tune2fs(8) "-u" option except that it can only be
15297 specified as a number.
15298 To get the current values of filesystem parameters, see
15300 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
15301 tune2fs(8) man page.
15302 This function returns 0 on success or -1 on error.
15304 (Added in 1.15.4)
15306 guestfs_tune2fs_va
15308 int
15309 guestfs_tune2fs_va (guestfs_h *g,
15310 const char *device,
15311 va_list args);
15312 This is the "va_list variant" of "guestfs_tune2fs".
15314 See "CALLS WITH OPTIONAL ARGUMENTS".
15316 guestfs_tune2fs_argv
15318 int
15319 guestfs_tune2fs_argv (guestfs_h *g,
15320 const char *device,
15321 const struct guestfs_tune2fs_argv *optargs);
15322 This is the "argv variant" of "guestfs_tune2fs".
15324 See "CALLS WITH OPTIONAL ARGUMENTS".
15326 guestfs_tune2fs_l
15328 char **
15329 guestfs_tune2fs_l (guestfs_h *g,
15330 const char *device);
15331 This returns the contents of the ext2, ext3 or ext4 filesystem
15333 superblock on "device".
15334 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
15336 for more details. The list of fields returned isn't clearly defined,
15337 and depends on both the version of "tune2fs" that libguestfs was built
15338 against, and the filesystem itself.
15339 This function returns a NULL-terminated array of strings, or NULL if
15341 there was an error. The array of strings will always have length
15342 "2n+1", where "n" keys and values alternate, followed by the trailing
15343 NULL entry. The caller must free the strings and the array after use.
15344 (Added in 1.9.2)
15346 guestfs_txz_in
15348 int
15349 guestfs_txz_in (guestfs_h *g,
15350 const char *tarball,
15351 const char *directory);
15352 This function is deprecated. In new code, use the "guestfs_tar_in"
15354 call instead.
15355 Deprecated functions will not be removed from the API, but the fact
15357 that they are deprecated indicates that there are problems with correct
15358 use of these functions.
15359 This command uploads and unpacks local file "tarball" (an xz compressed
15361 tar file) into directory.
15362 This function returns 0 on success or -1 on error.
15364 This function depends on the feature "xz". See also
15366 "guestfs_feature_available".
15367 (Added in 1.3.2)
15369 guestfs_txz_out
15371 int
15372 guestfs_txz_out (guestfs_h *g,
15373 const char *directory,
15374 const char *tarball);
15375 This function is deprecated. In new code, use the "guestfs_tar_out"
15377 call instead.
15378 Deprecated functions will not be removed from the API, but the fact
15380 that they are deprecated indicates that there are problems with correct
15381 use of these functions.
15382 This command packs the contents of directory and downloads it to local
15384 file "tarball" (as an xz compressed tar archive).
15385 This function returns 0 on success or -1 on error.
15387 This function depends on the feature "xz". See also
15389 "guestfs_feature_available".
15390 (Added in 1.3.2)
15392 guestfs_umask
15394 int
15395 guestfs_umask (guestfs_h *g,
15396 int mask);
15397 This function sets the mask used for creating new files and device
15399 nodes to "mask & 0777".
15400 Typical umask values would be 022 which creates new files with
15402 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15403 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15404 The default umask is 022. This is important because it means that
15406 directories and device nodes will be created with 0644 or 0755 mode
15407 even if you specify 0777.
15408 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15410 "guestfs_mkdir".
15411 This call returns the previous umask.
15413 On error this function returns -1.
15415 (Added in 1.0.55)
15417 guestfs_umount
15419 int
15420 guestfs_umount (guestfs_h *g,
15421 const char *pathordevice);
15422 This function is provided for backwards compatibility with earlier
15424 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15425 optional arguments.
15426 (Added in 0.8)
15428 guestfs_umount_opts
15430 int
15431 guestfs_umount_opts (guestfs_h *g,
15432 const char *pathordevice,
15433 ...);
15434 You may supply a list of optional arguments to this call. Use zero or
15436 more of the following pairs of parameters, and terminate the list with
15437 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15438 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15440 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15441 This unmounts the given filesystem. The filesystem may be specified
15443 either by its mountpoint (path) or the device which contains the
15444 filesystem.
15445 This function returns 0 on success or -1 on error.
15447 (Added in 0.8)
15449 guestfs_umount_opts_va
15451 int
15452 guestfs_umount_opts_va (guestfs_h *g,
15453 const char *pathordevice,
15454 va_list args);
15455 This is the "va_list variant" of "guestfs_umount_opts".
15457 See "CALLS WITH OPTIONAL ARGUMENTS".
15459 guestfs_umount_opts_argv
15461 int
15462 guestfs_umount_opts_argv (guestfs_h *g,
15463 const char *pathordevice,
15464 const struct guestfs_umount_opts_argv *optargs);
15465 This is the "argv variant" of "guestfs_umount_opts".
15467 See "CALLS WITH OPTIONAL ARGUMENTS".
15469 guestfs_umount_all
15471 int
15472 guestfs_umount_all (guestfs_h *g);
15473 This unmounts all mounted filesystems.
15475 Some internal mounts are not unmounted by this call.
15477 This function returns 0 on success or -1 on error.
15479 (Added in 0.8)
15481 guestfs_umount_local
15483 int
15484 guestfs_umount_local (guestfs_h *g,
15485 ...);
15486 You may supply a list of optional arguments to this call. Use zero or
15488 more of the following pairs of parameters, and terminate the list with
15489 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15490 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15492 If libguestfs is exporting the filesystem on a local mountpoint, then
15494 this unmounts it.
15495 See "MOUNT LOCAL" for full documentation.
15497 This function returns 0 on success or -1 on error.
15499 (Added in 1.17.22)
15501 guestfs_umount_local_va
15503 int
15504 guestfs_umount_local_va (guestfs_h *g,
15505 va_list args);
15506 This is the "va_list variant" of "guestfs_umount_local".
15508 See "CALLS WITH OPTIONAL ARGUMENTS".
15510 guestfs_umount_local_argv
15512 int
15513 guestfs_umount_local_argv (guestfs_h *g,
15514 const struct guestfs_umount_local_argv *optargs);
15515 This is the "argv variant" of "guestfs_umount_local".
15517 See "CALLS WITH OPTIONAL ARGUMENTS".
15519 guestfs_upload
15521 int
15522 guestfs_upload (guestfs_h *g,
15523 const char *filename,
15524 const char *remotefilename);
15525 Upload local file filename to remotefilename on the filesystem.
15527 filename can also be a named pipe.
15529 See also "guestfs_download".
15531 This function returns 0 on success or -1 on error.
15533 This long-running command can generate progress notification messages
15535 so that the caller can display a progress bar or indicator. To receive
15536 these messages, the caller must register a progress event callback.
15537 See "GUESTFS_EVENT_PROGRESS".
15538 (Added in 1.0.2)
15540 guestfs_upload_offset
15542 int
15543 guestfs_upload_offset (guestfs_h *g,
15544 const char *filename,
15545 const char *remotefilename,
15546 int64_t offset);
15547 Upload local file filename to remotefilename on the filesystem.
15549 remotefilename is overwritten starting at the byte "offset" specified.
15551 The intention is to overwrite parts of existing files or devices,
15552 although if a non-existent file is specified then it is created with a
15553 "hole" before "offset". The size of the data written is implicit in
15554 the size of the source filename.
15555 Note that there is no limit on the amount of data that can be uploaded
15557 with this call, unlike with "guestfs_pwrite", and this call always
15558 writes the full amount unless an error occurs.
15559 See also "guestfs_upload", "guestfs_pwrite".
15561 This function returns 0 on success or -1 on error.
15563 This long-running command can generate progress notification messages
15565 so that the caller can display a progress bar or indicator. To receive
15566 these messages, the caller must register a progress event callback.
15567 See "GUESTFS_EVENT_PROGRESS".
15568 (Added in 1.5.17)
15570 guestfs_user_cancel
15572 int
15573 guestfs_user_cancel (guestfs_h *g);
15574 This function cancels the current upload or download operation.
15576 Unlike most other libguestfs calls, this function is signal safe and
15578 thread safe. You can call it from a signal handler or from another
15579 thread, without needing to do any locking.
15580 The transfer that was in progress (if there is one) will stop shortly
15582 afterwards, and will return an error. The errno (see
15583 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15584 find out if the operation was cancelled or failed because of another
15585 error.
15586 No cleanup is performed: for example, if a file was being uploaded then
15588 after cancellation there may be a partially uploaded file. It is the
15589 caller’s responsibility to clean up if necessary.
15590 There are two common places that you might call "guestfs_user_cancel":
15592 In an interactive text-based program, you might call it from a "SIGINT"
15594 signal handler so that pressing "^C" cancels the current operation.
15595 (You also need to call "guestfs_set_pgroup" so that child processes
15596 don't receive the "^C" signal).
15597 In a graphical program, when the main thread is displaying a progress
15599 bar with a cancel button, wire up the cancel button to call this
15600 function.
15601 This function returns 0 on success or -1 on error.
15603 (Added in 1.11.18)
15605 guestfs_utimens
15607 int
15608 guestfs_utimens (guestfs_h *g,
15609 const char *path,
15610 int64_t atsecs,
15611 int64_t atnsecs,
15612 int64_t mtsecs,
15613 int64_t mtnsecs);
15614 This command sets the timestamps of a file with nanosecond precision.
15616 "atsecs", "atnsecs" are the last access time (atime) in secs and
15618 nanoseconds from the epoch.
15619 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
15621 nanoseconds from the epoch.
15622 If the *nsecs field contains the special value -1 then the
15624 corresponding timestamp is set to the current time. (The *secs field
15625 is ignored in this case).
15626 If the *nsecs field contains the special value -2 then the
15628 corresponding timestamp is left unchanged. (The *secs field is ignored
15629 in this case).
15630 This function returns 0 on success or -1 on error.
15632 (Added in 1.0.77)
15634 guestfs_utsname
15636 struct guestfs_utsname *
15637 guestfs_utsname (guestfs_h *g);
15638 This returns the kernel version of the appliance, where this is
15640 available. This information is only useful for debugging. Nothing in
15641 the returned structure is defined by the API.
15642 This function returns a "struct guestfs_utsname *", or NULL if there
15644 was an error. The caller must call "guestfs_free_utsname" after use.
15645 (Added in 1.19.27)
15647 guestfs_version
15649 struct guestfs_version *
15650 guestfs_version (guestfs_h *g);
15651 Return the libguestfs version number that the program is linked
15653 against.
15654 Note that because of dynamic linking this is not necessarily the
15656 version of libguestfs that you compiled against. You can compile the
15657 program, and then at runtime dynamically link against a completely
15658 different libguestfs.so library.
15659 This call was added in version 1.0.58. In previous versions of
15661 libguestfs there was no way to get the version number. From C code you
15662 can use dynamic linker functions to find out if this symbol exists (if
15663 it doesn't, then it’s an earlier version).
15664 The call returns a structure with four elements. The first three
15666 ("major", "minor" and "release") are numbers and correspond to the
15667 usual version triplet. The fourth element ("extra") is a string and is
15668 normally empty, but may be used for distro-specific information.
15669 To construct the original version string:
15671 "$major.$minor.$release$extra"
15672 See also: "LIBGUESTFS VERSION NUMBERS".
15674 Note: Don't use this call to test for availability of features. In
15676 enterprise distributions we backport features from later versions into
15677 earlier versions, making this an unreliable way to test for features.
15678 Use "guestfs_available" or "guestfs_feature_available" instead.
15679 This function returns a "struct guestfs_version *", or NULL if there
15681 was an error. The caller must call "guestfs_free_version" after use.
15682 (Added in 1.0.58)
15684 guestfs_vfs_label
15686 char *
15687 guestfs_vfs_label (guestfs_h *g,
15688 const char *mountable);
15689 This returns the label of the filesystem on "mountable".
15691 If the filesystem is unlabeled, this returns the empty string.
15693 To find a filesystem from the label, use "guestfs_findfs_label".
15695 This function returns a string, or NULL on error. The caller must free
15697 the returned string after use.
15698 (Added in 1.3.18)
15700 guestfs_vfs_minimum_size
15702 int64_t
15703 guestfs_vfs_minimum_size (guestfs_h *g,
15704 const char *mountable);
15705 Get the minimum size of filesystem in bytes. This is the minimum
15707 possible size for filesystem shrinking.
15708 If getting minimum size of specified filesystem is not supported, this
15710 will fail and set errno as ENOTSUP.
15711 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15713 On error this function returns -1.
15715 (Added in 1.31.18)
15717 guestfs_vfs_type
15719 char *
15720 guestfs_vfs_type (guestfs_h *g,
15721 const char *mountable);
15722 This command gets the filesystem type corresponding to the filesystem
15724 on "mountable".
15725 For most filesystems, the result is the name of the Linux VFS module
15727 which would be used to mount this filesystem if you mounted it without
15728 specifying the filesystem type. For example a string such as "ext3" or
15729 "ntfs".
15730 This function returns a string, or NULL on error. The caller must free
15732 the returned string after use.
15733 (Added in 1.0.75)
15735 guestfs_vfs_uuid
15737 char *
15738 guestfs_vfs_uuid (guestfs_h *g,
15739 const char *mountable);
15740 This returns the filesystem UUID of the filesystem on "mountable".
15742 If the filesystem does not have a UUID, this returns the empty string.
15744 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15746 This function returns a string, or NULL on error. The caller must free
15748 the returned string after use.
15749 (Added in 1.3.18)
15751 guestfs_vg_activate
15753 int
15754 guestfs_vg_activate (guestfs_h *g,
15755 int activate,
15756 char *const *volgroups);
15757 This command activates or (if "activate" is false) deactivates all
15759 logical volumes in the listed volume groups "volgroups".
15760 This command is the same as running "vgchange -a y|n volgroups..."
15762 Note that if "volgroups" is an empty list then all volume groups are
15764 activated or deactivated.
15765 This function returns 0 on success or -1 on error.
15767 This function depends on the feature "lvm2". See also
15769 "guestfs_feature_available".
15770 (Added in 1.0.26)
15772 guestfs_vg_activate_all
15774 int
15775 guestfs_vg_activate_all (guestfs_h *g,
15776 int activate);
15777 This command activates or (if "activate" is false) deactivates all
15779 logical volumes in all volume groups.
15780 This command is the same as running "vgchange -a y|n"
15782 This function returns 0 on success or -1 on error.
15784 This function depends on the feature "lvm2". See also
15786 "guestfs_feature_available".
15787 (Added in 1.0.26)
15789 guestfs_vgchange_uuid
15791 int
15792 guestfs_vgchange_uuid (guestfs_h *g,
15793 const char *vg);
15794 Generate a new random UUID for the volume group "vg".
15796 This function returns 0 on success or -1 on error.
15798 This function depends on the feature "lvm2". See also
15800 "guestfs_feature_available".
15801 (Added in 1.19.26)
15803 guestfs_vgchange_uuid_all
15805 int
15806 guestfs_vgchange_uuid_all (guestfs_h *g);
15807 Generate new random UUIDs for all volume groups.
15809 This function returns 0 on success or -1 on error.
15811 This function depends on the feature "lvm2". See also
15813 "guestfs_feature_available".
15814 (Added in 1.19.26)
15816 guestfs_vgcreate
15818 int
15819 guestfs_vgcreate (guestfs_h *g,
15820 const char *volgroup,
15821 char *const *physvols);
15822 This creates an LVM volume group called "volgroup" from the non-empty
15824 list of physical volumes "physvols".
15825 This function returns 0 on success or -1 on error.
15827 This function depends on the feature "lvm2". See also
15829 "guestfs_feature_available".
15830 (Added in 0.8)
15832 guestfs_vglvuuids
15834 char **
15835 guestfs_vglvuuids (guestfs_h *g,
15836 const char *vgname);
15837 Given a VG called "vgname", this returns the UUIDs of all the logical
15839 volumes created in this volume group.
15840 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15842 associate logical volumes and volume groups.
15843 See also "guestfs_vgpvuuids".
15845 This function returns a NULL-terminated array of strings (like
15847 environ(3)), or NULL if there was an error. The caller must free the
15848 strings and the array after use.
15849 (Added in 1.0.87)
15851 guestfs_vgmeta
15853 char *
15854 guestfs_vgmeta (guestfs_h *g,
15855 const char *vgname,
15856 size_t *size_r);
15857 "vgname" is an LVM volume group. This command examines the volume
15859 group and returns its metadata.
15860 Note that the metadata is an internal structure used by LVM, subject to
15862 change at any time, and is provided for information only.
15863 This function returns a buffer, or NULL on error. The size of the
15865 returned buffer is written to *size_r. The caller must free the
15866 returned buffer after use.
15867 This function depends on the feature "lvm2". See also
15869 "guestfs_feature_available".
15870 (Added in 1.17.20)
15872 guestfs_vgpvuuids
15874 char **
15875 guestfs_vgpvuuids (guestfs_h *g,
15876 const char *vgname);
15877 Given a VG called "vgname", this returns the UUIDs of all the physical
15879 volumes that this volume group resides on.
15880 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15882 associate physical volumes and volume groups.
15883 See also "guestfs_vglvuuids".
15885 This function returns a NULL-terminated array of strings (like
15887 environ(3)), or NULL if there was an error. The caller must free the
15888 strings and the array after use.
15889 (Added in 1.0.87)
15891 guestfs_vgremove
15893 int
15894 guestfs_vgremove (guestfs_h *g,
15895 const char *vgname);
15896 Remove an LVM volume group "vgname", (for example "VG").
15898 This also forcibly removes all logical volumes in the volume group (if
15900 any).
15901 This function returns 0 on success or -1 on error.
15903 This function depends on the feature "lvm2". See also
15905 "guestfs_feature_available".
15906 (Added in 1.0.13)
15908 guestfs_vgrename
15910 int
15911 guestfs_vgrename (guestfs_h *g,
15912 const char *volgroup,
15913 const char *newvolgroup);
15914 Rename a volume group "volgroup" with the new name "newvolgroup".
15916 This function returns 0 on success or -1 on error.
15918 (Added in 1.0.83)
15920 guestfs_vgs
15922 char **
15923 guestfs_vgs (guestfs_h *g);
15924 List all the volumes groups detected. This is the equivalent of the
15926 vgs(8) command.
15927 This returns a list of just the volume group names that were detected
15929 (eg. "VolGroup00").
15930 See also "guestfs_vgs_full".
15932 This function returns a NULL-terminated array of strings (like
15934 environ(3)), or NULL if there was an error. The caller must free the
15935 strings and the array after use.
15936 This function depends on the feature "lvm2". See also
15938 "guestfs_feature_available".
15939 (Added in 0.4)
15941 guestfs_vgs_full
15943 struct guestfs_lvm_vg_list *
15944 guestfs_vgs_full (guestfs_h *g);
15945 List all the volumes groups detected. This is the equivalent of the
15947 vgs(8) command. The "full" version includes all fields.
15948 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
15950 there was an error. The caller must call "guestfs_free_lvm_vg_list"
15951 after use.
15952 This function depends on the feature "lvm2". See also
15954 "guestfs_feature_available".
15955 (Added in 0.4)
15957 guestfs_vgscan
15959 int
15960 guestfs_vgscan (guestfs_h *g);
15961 This function is deprecated. In new code, use the "guestfs_lvm_scan"
15963 call instead.
15964 Deprecated functions will not be removed from the API, but the fact
15966 that they are deprecated indicates that there are problems with correct
15967 use of these functions.
15968 This rescans all block devices and rebuilds the list of LVM physical
15970 volumes, volume groups and logical volumes.
15971 This function returns 0 on success or -1 on error.
15973 (Added in 1.3.2)
15975 guestfs_vguuid
15977 char *
15978 guestfs_vguuid (guestfs_h *g,
15979 const char *vgname);
15980 This command returns the UUID of the LVM VG named "vgname".
15982 This function returns a string, or NULL on error. The caller must free
15984 the returned string after use.
15985 (Added in 1.0.87)
15987 guestfs_wait_ready
15989 int
15990 guestfs_wait_ready (guestfs_h *g);
15991 This function is deprecated. There is no replacement. Consult the API
15993 documentation in guestfs(3) for further information.
15994 Deprecated functions will not be removed from the API, but the fact
15996 that they are deprecated indicates that there are problems with correct
15997 use of these functions.
15998 This function is a no op.
16000 In versions of the API < 1.0.71 you had to call this function just
16002 after calling "guestfs_launch" to wait for the launch to complete.
16003 However this is no longer necessary because "guestfs_launch" now does
16004 the waiting.
16005 If you see any calls to this function in code then you can just remove
16007 them, unless you want to retain compatibility with older versions of
16008 the API.
16009 This function returns 0 on success or -1 on error.
16011 (Added in 0.3)
16013 guestfs_wc_c
16015 int
16016 guestfs_wc_c (guestfs_h *g,
16017 const char *path);
16018 This command counts the characters in a file, using the "wc -c"
16020 external command.
16021 On error this function returns -1.
16023 (Added in 1.0.54)
16025 guestfs_wc_l
16027 int
16028 guestfs_wc_l (guestfs_h *g,
16029 const char *path);
16030 This command counts the lines in a file, using the "wc -l" external
16032 command.
16033 On error this function returns -1.
16035 (Added in 1.0.54)
16037 guestfs_wc_w
16039 int
16040 guestfs_wc_w (guestfs_h *g,
16041 const char *path);
16042 This command counts the words in a file, using the "wc -w" external
16044 command.
16045 On error this function returns -1.
16047 (Added in 1.0.54)
16049 guestfs_wipefs
16051 int
16052 guestfs_wipefs (guestfs_h *g,
16053 const char *device);
16054 This command erases filesystem or RAID signatures from the specified
16056 "device" to make the filesystem invisible to libblkid.
16057 This does not erase the filesystem itself nor any other data from the
16059 "device".
16060 Compare with "guestfs_zero" which zeroes the first few blocks of a
16062 device.
16063 This function returns 0 on success or -1 on error.
16065 This function depends on the feature "wipefs". See also
16067 "guestfs_feature_available".
16068 (Added in 1.17.6)
16070 guestfs_write
16072 int
16073 guestfs_write (guestfs_h *g,
16074 const char *path,
16075 const char *content,
16076 size_t content_size);
16077 This call creates a file called "path". The content of the file is the
16079 string "content" (which can contain any 8 bit data).
16080 See also "guestfs_write_append".
16082 This function returns 0 on success or -1 on error.
16084 (Added in 1.3.14)
16086 guestfs_write_append
16088 int
16089 guestfs_write_append (guestfs_h *g,
16090 const char *path,
16091 const char *content,
16092 size_t content_size);
16093 This call appends "content" to the end of file "path". If "path" does
16095 not exist, then a new file is created.
16096 See also "guestfs_write".
16098 This function returns 0 on success or -1 on error.
16100 (Added in 1.11.18)
16102 guestfs_write_file
16104 int
16105 guestfs_write_file (guestfs_h *g,
16106 const char *path,
16107 const char *content,
16108 int size);
16109 This function is deprecated. In new code, use the "guestfs_write" call
16111 instead.
16112 Deprecated functions will not be removed from the API, but the fact
16114 that they are deprecated indicates that there are problems with correct
16115 use of these functions.
16116 This call creates a file called "path". The contents of the file is
16118 the string "content" (which can contain any 8 bit data), with length
16119 "size".
16120 As a special case, if "size" is 0 then the length is calculated using
16122 "strlen" (so in this case the content cannot contain embedded ASCII
16123 NULs).
16124 NB. Owing to a bug, writing content containing ASCII NUL characters
16126 does not work, even if the length is specified.
16127 This function returns 0 on success or -1 on error.
16129 Because of the message protocol, there is a transfer limit of somewhere
16131 between 2MB and 4MB. See "PROTOCOL LIMITS".
16132 (Added in 0.8)
16134 guestfs_xfs_admin
16136 int
16137 guestfs_xfs_admin (guestfs_h *g,
16138 const char *device,
16139 ...);
16140 You may supply a list of optional arguments to this call. Use zero or
16142 more of the following pairs of parameters, and terminate the list with
16143 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16144 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16146 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16147 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16148 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16149 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16150 GUESTFS_XFS_ADMIN_LABEL, const char *label,
16151 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16152 Change the parameters of the XFS filesystem on "device".
16154 Devices that are mounted cannot be modified. Administrators must
16156 unmount filesystems before this call can modify parameters.
16157 Some of the parameters of a mounted filesystem can be examined and
16159 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16160 Beginning with XFS version 5, it is no longer possible to modify the
16162 lazy-counters setting (ie. "lazycounter" parameter has no effect).
16163 This function returns 0 on success or -1 on error.
16165 This function depends on the feature "xfs". See also
16167 "guestfs_feature_available".
16168 (Added in 1.19.33)
16170 guestfs_xfs_admin_va
16172 int
16173 guestfs_xfs_admin_va (guestfs_h *g,
16174 const char *device,
16175 va_list args);
16176 This is the "va_list variant" of "guestfs_xfs_admin".
16178 See "CALLS WITH OPTIONAL ARGUMENTS".
16180 guestfs_xfs_admin_argv
16182 int
16183 guestfs_xfs_admin_argv (guestfs_h *g,
16184 const char *device,
16185 const struct guestfs_xfs_admin_argv *optargs);
16186 This is the "argv variant" of "guestfs_xfs_admin".
16188 See "CALLS WITH OPTIONAL ARGUMENTS".
16190 guestfs_xfs_growfs
16192 int
16193 guestfs_xfs_growfs (guestfs_h *g,
16194 const char *path,
16195 ...);
16196 You may supply a list of optional arguments to this call. Use zero or
16198 more of the following pairs of parameters, and terminate the list with
16199 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16200 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16202 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16203 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16204 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16205 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16206 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16207 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16208 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16209 Grow the XFS filesystem mounted at "path".
16211 The returned struct contains geometry information. Missing fields are
16213 returned as -1 (for numeric fields) or empty string.
16214 This function returns 0 on success or -1 on error.
16216 This function depends on the feature "xfs". See also
16218 "guestfs_feature_available".
16219 (Added in 1.19.28)
16221 guestfs_xfs_growfs_va
16223 int
16224 guestfs_xfs_growfs_va (guestfs_h *g,
16225 const char *path,
16226 va_list args);
16227 This is the "va_list variant" of "guestfs_xfs_growfs".
16229 See "CALLS WITH OPTIONAL ARGUMENTS".
16231 guestfs_xfs_growfs_argv
16233 int
16234 guestfs_xfs_growfs_argv (guestfs_h *g,
16235 const char *path,
16236 const struct guestfs_xfs_growfs_argv *optargs);
16237 This is the "argv variant" of "guestfs_xfs_growfs".
16239 See "CALLS WITH OPTIONAL ARGUMENTS".
16241 guestfs_xfs_info
16243 struct guestfs_xfsinfo *
16244 guestfs_xfs_info (guestfs_h *g,
16245 const char *pathordevice);
16246 "pathordevice" is a mounted XFS filesystem or a device containing an
16248 XFS filesystem. This command returns the geometry of the filesystem.
16249 The returned struct contains geometry information. Missing fields are
16251 returned as -1 (for numeric fields) or empty string.
16252 This function returns a "struct guestfs_xfsinfo *", or NULL if there
16254 was an error. The caller must call "guestfs_free_xfsinfo" after use.
16255 This function depends on the feature "xfs". See also
16257 "guestfs_feature_available".
16258 (Added in 1.19.21)
16260 guestfs_xfs_repair
16262 int
16263 guestfs_xfs_repair (guestfs_h *g,
16264 const char *device,
16265 ...);
16266 You may supply a list of optional arguments to this call. Use zero or
16268 more of the following pairs of parameters, and terminate the list with
16269 -1 on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16270 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16272 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16273 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16274 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16275 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16276 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16277 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16278 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16279 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16280 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16281 Repair corrupt or damaged XFS filesystem on "device".
16283 The filesystem is specified using the "device" argument which should be
16285 the device name of the disk partition or volume containing the
16286 filesystem. If given the name of a block device, "xfs_repair" will
16287 attempt to find the raw device associated with the specified block
16288 device and will use the raw device instead.
16289 Regardless, the filesystem to be repaired must be unmounted, otherwise,
16291 the resulting filesystem may be inconsistent or corrupt.
16292 The returned status indicates whether filesystem corruption was
16294 detected (returns 1) or was not detected (returns 0).
16295 On error this function returns -1.
16297 This function depends on the feature "xfs". See also
16299 "guestfs_feature_available".
16300 (Added in 1.19.36)
16302 guestfs_xfs_repair_va
16304 int
16305 guestfs_xfs_repair_va (guestfs_h *g,
16306 const char *device,
16307 va_list args);
16308 This is the "va_list variant" of "guestfs_xfs_repair".
16310 See "CALLS WITH OPTIONAL ARGUMENTS".
16312 guestfs_xfs_repair_argv
16314 int
16315 guestfs_xfs_repair_argv (guestfs_h *g,
16316 const char *device,
16317 const struct guestfs_xfs_repair_argv *optargs);
16318 This is the "argv variant" of "guestfs_xfs_repair".
16320 See "CALLS WITH OPTIONAL ARGUMENTS".
16322 guestfs_yara_destroy
16324 int
16325 guestfs_yara_destroy (guestfs_h *g);
16326 Destroy previously loaded Yara rules in order to free libguestfs
16328 resources.
16329 This function returns 0 on success or -1 on error.
16331 This function depends on the feature "libyara". See also
16333 "guestfs_feature_available".
16334 (Added in 1.37.13)
16336 guestfs_yara_load
16338 int
16339 guestfs_yara_load (guestfs_h *g,
16340 const char *filename);
16341 Upload a set of Yara rules from local file filename.
16343 Yara rules allow to categorize files based on textual or binary
16345 patterns within their content. See "guestfs_yara_scan" to see how to
16346 scan files with the loaded rules.
16347 Rules can be in binary format, as when compiled with yarac command, or
16349 in source code format. In the latter case, the rules will be first
16350 compiled and then loaded.
16351 Rules in source code format cannot include external files. In such
16353 cases, it is recommended to compile them first.
16354 Previously loaded rules will be destroyed.
16356 This function returns 0 on success or -1 on error.
16358 This long-running command can generate progress notification messages
16360 so that the caller can display a progress bar or indicator. To receive
16361 these messages, the caller must register a progress event callback.
16362 See "GUESTFS_EVENT_PROGRESS".
16363 This function depends on the feature "libyara". See also
16365 "guestfs_feature_available".
16366 (Added in 1.37.13)
16368 guestfs_yara_scan
16370 struct guestfs_yara_detection_list *
16371 guestfs_yara_scan (guestfs_h *g,
16372 const char *path);
16373 Scan a file with the previously loaded Yara rules.
16375 For each matching rule, a "yara_detection" structure is returned.
16377 The "yara_detection" structure contains the following fields.
16379 "yara_name"
16381 Path of the file matching a Yara rule.
16382 "yara_rule"
16384 Identifier of the Yara rule which matched against the given file.
16385 This function returns a "struct guestfs_yara_detection_list *", or NULL
16387 if there was an error. The caller must call
16388 "guestfs_free_yara_detection_list" after use.
16389 This long-running command can generate progress notification messages
16391 so that the caller can display a progress bar or indicator. To receive
16392 these messages, the caller must register a progress event callback.
16393 See "GUESTFS_EVENT_PROGRESS".
16394 This function depends on the feature "libyara". See also
16396 "guestfs_feature_available".
16397 (Added in 1.37.13)
16399 guestfs_zegrep
16401 char **
16402 guestfs_zegrep (guestfs_h *g,
16403 const char *regex,
16404 const char *path);
16405 This function is deprecated. In new code, use the "guestfs_grep" call
16407 instead.
16408 Deprecated functions will not be removed from the API, but the fact
16410 that they are deprecated indicates that there are problems with correct
16411 use of these functions.
16412 This calls the external "zegrep" program and returns the matching
16414 lines.
16415 This function returns a NULL-terminated array of strings (like
16417 environ(3)), or NULL if there was an error. The caller must free the
16418 strings and the array after use.
16419 Because of the message protocol, there is a transfer limit of somewhere
16421 between 2MB and 4MB. See "PROTOCOL LIMITS".
16422 (Added in 1.0.66)
16424 guestfs_zegrepi
16426 char **
16427 guestfs_zegrepi (guestfs_h *g,
16428 const char *regex,
16429 const char *path);
16430 This function is deprecated. In new code, use the "guestfs_grep" call
16432 instead.
16433 Deprecated functions will not be removed from the API, but the fact
16435 that they are deprecated indicates that there are problems with correct
16436 use of these functions.
16437 This calls the external "zegrep -i" program and returns the matching
16439 lines.
16440 This function returns a NULL-terminated array of strings (like
16442 environ(3)), or NULL if there was an error. The caller must free the
16443 strings and the array after use.
16444 Because of the message protocol, there is a transfer limit of somewhere
16446 between 2MB and 4MB. See "PROTOCOL LIMITS".
16447 (Added in 1.0.66)
16449 guestfs_zero
16451 int
16452 guestfs_zero (guestfs_h *g,
16453 const char *device);
16454 This command writes zeroes over the first few blocks of "device".
16456 How many blocks are zeroed isn't specified (but it’s not enough to
16458 securely wipe the device). It should be sufficient to remove any
16459 partition tables, filesystem superblocks and so on.
16460 If blocks are already zero, then this command avoids writing zeroes.
16462 This prevents the underlying device from becoming non-sparse or growing
16463 unnecessarily.
16464 See also: "guestfs_zero_device", "guestfs_scrub_device",
16466 "guestfs_is_zero_device"
16467 This function returns 0 on success or -1 on error.
16469 This long-running command can generate progress notification messages
16471 so that the caller can display a progress bar or indicator. To receive
16472 these messages, the caller must register a progress event callback.
16473 See "GUESTFS_EVENT_PROGRESS".
16474 (Added in 1.0.16)
16476 guestfs_zero_device
16478 int
16479 guestfs_zero_device (guestfs_h *g,
16480 const char *device);
16481 This command writes zeroes over the entire "device". Compare with
16483 "guestfs_zero" which just zeroes the first few blocks of a device.
16484 If blocks are already zero, then this command avoids writing zeroes.
16486 This prevents the underlying device from becoming non-sparse or growing
16487 unnecessarily.
16488 This function returns 0 on success or -1 on error.
16490 This long-running command can generate progress notification messages
16492 so that the caller can display a progress bar or indicator. To receive
16493 these messages, the caller must register a progress event callback.
16494 See "GUESTFS_EVENT_PROGRESS".
16495 (Added in 1.3.1)
16497 guestfs_zero_free_space
16499 int
16500 guestfs_zero_free_space (guestfs_h *g,
16501 const char *directory);
16502 Zero the free space in the filesystem mounted on directory. The
16504 filesystem must be mounted read-write.
16505 The filesystem contents are not affected, but any free space in the
16507 filesystem is freed.
16508 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16510 either as an alternative to this, or after calling this, depending on
16511 your requirements.
16512 This function returns 0 on success or -1 on error.
16514 This long-running command can generate progress notification messages
16516 so that the caller can display a progress bar or indicator. To receive
16517 these messages, the caller must register a progress event callback.
16518 See "GUESTFS_EVENT_PROGRESS".
16519 (Added in 1.17.18)
16521 guestfs_zerofree
16523 int
16524 guestfs_zerofree (guestfs_h *g,
16525 const char *device);
16526 This runs the zerofree program on "device". This program claims to
16528 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16529 it possible to compress the filesystem more effectively.
16530 You should not run this program if the filesystem is mounted.
16532 It is possible that using this program can damage the filesystem or
16534 data on the filesystem.
16535 This function returns 0 on success or -1 on error.
16537 This function depends on the feature "zerofree". See also
16539 "guestfs_feature_available".
16540 (Added in 1.0.26)
16542 guestfs_zfgrep
16544 char **
16545 guestfs_zfgrep (guestfs_h *g,
16546 const char *pattern,
16547 const char *path);
16548 This function is deprecated. In new code, use the "guestfs_grep" call
16550 instead.
16551 Deprecated functions will not be removed from the API, but the fact
16553 that they are deprecated indicates that there are problems with correct
16554 use of these functions.
16555 This calls the external "zfgrep" program and returns the matching
16557 lines.
16558 This function returns a NULL-terminated array of strings (like
16560 environ(3)), or NULL if there was an error. The caller must free the
16561 strings and the array after use.
16562 Because of the message protocol, there is a transfer limit of somewhere
16564 between 2MB and 4MB. See "PROTOCOL LIMITS".
16565 (Added in 1.0.66)
16567 guestfs_zfgrepi
16569 char **
16570 guestfs_zfgrepi (guestfs_h *g,
16571 const char *pattern,
16572 const char *path);
16573 This function is deprecated. In new code, use the "guestfs_grep" call
16575 instead.
16576 Deprecated functions will not be removed from the API, but the fact
16578 that they are deprecated indicates that there are problems with correct
16579 use of these functions.
16580 This calls the external "zfgrep -i" program and returns the matching
16582 lines.
16583 This function returns a NULL-terminated array of strings (like
16585 environ(3)), or NULL if there was an error. The caller must free the
16586 strings and the array after use.
16587 Because of the message protocol, there is a transfer limit of somewhere
16589 between 2MB and 4MB. See "PROTOCOL LIMITS".
16590 (Added in 1.0.66)
16592 guestfs_zfile
16594 char *
16595 guestfs_zfile (guestfs_h *g,
16596 const char *meth,
16597 const char *path);
16598 This function is deprecated. In new code, use the "guestfs_file" call
16600 instead.
16601 Deprecated functions will not be removed from the API, but the fact
16603 that they are deprecated indicates that there are problems with correct
16604 use of these functions.
16605 This command runs file(1) after first decompressing "path" using
16607 "meth".
16608 "meth" must be one of "gzip", "compress" or "bzip2".
16610 Since 1.0.63, use "guestfs_file" instead which can now process
16612 compressed files.
16613 This function returns a string, or NULL on error. The caller must free
16615 the returned string after use.
16616 (Added in 1.0.59)
16618 guestfs_zgrep
16620 char **
16621 guestfs_zgrep (guestfs_h *g,
16622 const char *regex,
16623 const char *path);
16624 This function is deprecated. In new code, use the "guestfs_grep" call
16626 instead.
16627 Deprecated functions will not be removed from the API, but the fact
16629 that they are deprecated indicates that there are problems with correct
16630 use of these functions.
16631 This calls the external zgrep(1) program and returns the matching
16633 lines.
16634 This function returns a NULL-terminated array of strings (like
16636 environ(3)), or NULL if there was an error. The caller must free the
16637 strings and the array after use.
16638 Because of the message protocol, there is a transfer limit of somewhere
16640 between 2MB and 4MB. See "PROTOCOL LIMITS".
16641 (Added in 1.0.66)
16643 guestfs_zgrepi
16645 char **
16646 guestfs_zgrepi (guestfs_h *g,
16647 const char *regex,
16648 const char *path);
16649 This function is deprecated. In new code, use the "guestfs_grep" call
16651 instead.
16652 Deprecated functions will not be removed from the API, but the fact
16654 that they are deprecated indicates that there are problems with correct
16655 use of these functions.
16656 This calls the external "zgrep -i" program and returns the matching
16658 lines.
16659 This function returns a NULL-terminated array of strings (like
16661 environ(3)), or NULL if there was an error. The caller must free the
16662 strings and the array after use.
16663 Because of the message protocol, there is a transfer limit of somewhere
16665 between 2MB and 4MB. See "PROTOCOL LIMITS".
16666 (Added in 1.0.66)
16668
16670 guestfs_int_bool
16671 struct guestfs_int_bool {
16672 int32_t i;
16673 int32_t b;
16674 };
16675 struct guestfs_int_bool_list {
16677 uint32_t len; /* Number of elements in list. */
16678 struct guestfs_int_bool *val; /* Elements. */
16679 };
16680 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16682 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16683 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16685 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16686 void guestfs_free_int_bool (struct guestfs_int_bool *);
16688 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16689 guestfs_lvm_pv
16691 struct guestfs_lvm_pv {
16692 char *pv_name;
16693 /* The next field is NOT nul-terminated, be careful when printing it: */
16694 char pv_uuid[32];
16695 char *pv_fmt;
16696 uint64_t pv_size;
16697 uint64_t dev_size;
16698 uint64_t pv_free;
16699 uint64_t pv_used;
16700 char *pv_attr;
16701 int64_t pv_pe_count;
16702 int64_t pv_pe_alloc_count;
16703 char *pv_tags;
16704 uint64_t pe_start;
16705 int64_t pv_mda_count;
16706 uint64_t pv_mda_free;
16707 };
16708 struct guestfs_lvm_pv_list {
16710 uint32_t len; /* Number of elements in list. */
16711 struct guestfs_lvm_pv *val; /* Elements. */
16712 };
16713 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16715 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16716 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16718 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16719 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16721 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16722 guestfs_lvm_vg
16724 struct guestfs_lvm_vg {
16725 char *vg_name;
16726 /* The next field is NOT nul-terminated, be careful when printing it: */
16727 char vg_uuid[32];
16728 char *vg_fmt;
16729 char *vg_attr;
16730 uint64_t vg_size;
16731 uint64_t vg_free;
16732 char *vg_sysid;
16733 uint64_t vg_extent_size;
16734 int64_t vg_extent_count;
16735 int64_t vg_free_count;
16736 int64_t max_lv;
16737 int64_t max_pv;
16738 int64_t pv_count;
16739 int64_t lv_count;
16740 int64_t snap_count;
16741 int64_t vg_seqno;
16742 char *vg_tags;
16743 int64_t vg_mda_count;
16744 uint64_t vg_mda_free;
16745 };
16746 struct guestfs_lvm_vg_list {
16748 uint32_t len; /* Number of elements in list. */
16749 struct guestfs_lvm_vg *val; /* Elements. */
16750 };
16751 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16753 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16754 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16756 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16757 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16759 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16760 guestfs_lvm_lv
16762 struct guestfs_lvm_lv {
16763 char *lv_name;
16764 /* The next field is NOT nul-terminated, be careful when printing it: */
16765 char lv_uuid[32];
16766 char *lv_attr;
16767 int64_t lv_major;
16768 int64_t lv_minor;
16769 int64_t lv_kernel_major;
16770 int64_t lv_kernel_minor;
16771 uint64_t lv_size;
16772 int64_t seg_count;
16773 char *origin;
16774 /* The next field is [0..100] or -1 meaning 'not present': */
16775 float snap_percent;
16776 /* The next field is [0..100] or -1 meaning 'not present': */
16777 float copy_percent;
16778 char *move_pv;
16779 char *lv_tags;
16780 char *mirror_log;
16781 char *modules;
16782 };
16783 struct guestfs_lvm_lv_list {
16785 uint32_t len; /* Number of elements in list. */
16786 struct guestfs_lvm_lv *val; /* Elements. */
16787 };
16788 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16790 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16791 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16793 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16794 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16796 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16797 guestfs_stat
16799 struct guestfs_stat {
16800 int64_t dev;
16801 int64_t ino;
16802 int64_t mode;
16803 int64_t nlink;
16804 int64_t uid;
16805 int64_t gid;
16806 int64_t rdev;
16807 int64_t size;
16808 int64_t blksize;
16809 int64_t blocks;
16810 int64_t atime;
16811 int64_t mtime;
16812 int64_t ctime;
16813 };
16814 struct guestfs_stat_list {
16816 uint32_t len; /* Number of elements in list. */
16817 struct guestfs_stat *val; /* Elements. */
16818 };
16819 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16821 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16822 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16824 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16825 void guestfs_free_stat (struct guestfs_stat *);
16827 void guestfs_free_stat_list (struct guestfs_stat_list *);
16828 guestfs_statns
16830 struct guestfs_statns {
16831 int64_t st_dev;
16832 int64_t st_ino;
16833 int64_t st_mode;
16834 int64_t st_nlink;
16835 int64_t st_uid;
16836 int64_t st_gid;
16837 int64_t st_rdev;
16838 int64_t st_size;
16839 int64_t st_blksize;
16840 int64_t st_blocks;
16841 int64_t st_atime_sec;
16842 int64_t st_atime_nsec;
16843 int64_t st_mtime_sec;
16844 int64_t st_mtime_nsec;
16845 int64_t st_ctime_sec;
16846 int64_t st_ctime_nsec;
16847 int64_t st_spare1;
16848 int64_t st_spare2;
16849 int64_t st_spare3;
16850 int64_t st_spare4;
16851 int64_t st_spare5;
16852 int64_t st_spare6;
16853 };
16854 struct guestfs_statns_list {
16856 uint32_t len; /* Number of elements in list. */
16857 struct guestfs_statns *val; /* Elements. */
16858 };
16859 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16861 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16862 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16864 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16865 void guestfs_free_statns (struct guestfs_statns *);
16867 void guestfs_free_statns_list (struct guestfs_statns_list *);
16868 guestfs_statvfs
16870 struct guestfs_statvfs {
16871 int64_t bsize;
16872 int64_t frsize;
16873 int64_t blocks;
16874 int64_t bfree;
16875 int64_t bavail;
16876 int64_t files;
16877 int64_t ffree;
16878 int64_t favail;
16879 int64_t fsid;
16880 int64_t flag;
16881 int64_t namemax;
16882 };
16883 struct guestfs_statvfs_list {
16885 uint32_t len; /* Number of elements in list. */
16886 struct guestfs_statvfs *val; /* Elements. */
16887 };
16888 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16890 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16891 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16893 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16894 void guestfs_free_statvfs (struct guestfs_statvfs *);
16896 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16897 guestfs_dirent
16899 struct guestfs_dirent {
16900 int64_t ino;
16901 char ftyp;
16902 char *name;
16903 };
16904 struct guestfs_dirent_list {
16906 uint32_t len; /* Number of elements in list. */
16907 struct guestfs_dirent *val; /* Elements. */
16908 };
16909 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16911 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16912 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16914 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16915 void guestfs_free_dirent (struct guestfs_dirent *);
16917 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16918 guestfs_version
16920 struct guestfs_version {
16921 int64_t major;
16922 int64_t minor;
16923 int64_t release;
16924 char *extra;
16925 };
16926 struct guestfs_version_list {
16928 uint32_t len; /* Number of elements in list. */
16929 struct guestfs_version *val; /* Elements. */
16930 };
16931 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16933 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16934 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16936 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16937 void guestfs_free_version (struct guestfs_version *);
16939 void guestfs_free_version_list (struct guestfs_version_list *);
16940 guestfs_xattr
16942 struct guestfs_xattr {
16943 char *attrname;
16944 /* The next two fields describe a byte array. */
16945 uint32_t attrval_len;
16946 char *attrval;
16947 };
16948 struct guestfs_xattr_list {
16950 uint32_t len; /* Number of elements in list. */
16951 struct guestfs_xattr *val; /* Elements. */
16952 };
16953 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16955 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16956 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
16958 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
16959 void guestfs_free_xattr (struct guestfs_xattr *);
16961 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
16962 guestfs_inotify_event
16964 struct guestfs_inotify_event {
16965 int64_t in_wd;
16966 uint32_t in_mask;
16967 uint32_t in_cookie;
16968 char *in_name;
16969 };
16970 struct guestfs_inotify_event_list {
16972 uint32_t len; /* Number of elements in list. */
16973 struct guestfs_inotify_event *val; /* Elements. */
16974 };
16975 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
16977 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
16978 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
16980 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
16981 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
16983 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
16984 guestfs_partition
16986 struct guestfs_partition {
16987 int32_t part_num;
16988 uint64_t part_start;
16989 uint64_t part_end;
16990 uint64_t part_size;
16991 };
16992 struct guestfs_partition_list {
16994 uint32_t len; /* Number of elements in list. */
16995 struct guestfs_partition *val; /* Elements. */
16996 };
16997 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
16999 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
17000 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
17002 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
17003 void guestfs_free_partition (struct guestfs_partition *);
17005 void guestfs_free_partition_list (struct guestfs_partition_list *);
17006 guestfs_application
17008 struct guestfs_application {
17009 char *app_name;
17010 char *app_display_name;
17011 int32_t app_epoch;
17012 char *app_version;
17013 char *app_release;
17014 char *app_install_path;
17015 char *app_trans_path;
17016 char *app_publisher;
17017 char *app_url;
17018 char *app_source_package;
17019 char *app_summary;
17020 char *app_description;
17021 };
17022 struct guestfs_application_list {
17024 uint32_t len; /* Number of elements in list. */
17025 struct guestfs_application *val; /* Elements. */
17026 };
17027 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
17029 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
17030 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
17032 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
17033 void guestfs_free_application (struct guestfs_application *);
17035 void guestfs_free_application_list (struct guestfs_application_list *);
17036 guestfs_application2
17038 struct guestfs_application2 {
17039 char *app2_name;
17040 char *app2_display_name;
17041 int32_t app2_epoch;
17042 char *app2_version;
17043 char *app2_release;
17044 char *app2_arch;
17045 char *app2_install_path;
17046 char *app2_trans_path;
17047 char *app2_publisher;
17048 char *app2_url;
17049 char *app2_source_package;
17050 char *app2_summary;
17051 char *app2_description;
17052 char *app2_spare1;
17053 char *app2_spare2;
17054 char *app2_spare3;
17055 char *app2_spare4;
17056 };
17057 struct guestfs_application2_list {
17059 uint32_t len; /* Number of elements in list. */
17060 struct guestfs_application2 *val; /* Elements. */
17061 };
17062 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
17064 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
17065 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
17067 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
17068 void guestfs_free_application2 (struct guestfs_application2 *);
17070 void guestfs_free_application2_list (struct guestfs_application2_list *);
17071 guestfs_isoinfo
17073 struct guestfs_isoinfo {
17074 char *iso_system_id;
17075 char *iso_volume_id;
17076 uint32_t iso_volume_space_size;
17077 uint32_t iso_volume_set_size;
17078 uint32_t iso_volume_sequence_number;
17079 uint32_t iso_logical_block_size;
17080 char *iso_volume_set_id;
17081 char *iso_publisher_id;
17082 char *iso_data_preparer_id;
17083 char *iso_application_id;
17084 char *iso_copyright_file_id;
17085 char *iso_abstract_file_id;
17086 char *iso_bibliographic_file_id;
17087 int64_t iso_volume_creation_t;
17088 int64_t iso_volume_modification_t;
17089 int64_t iso_volume_expiration_t;
17090 int64_t iso_volume_effective_t;
17091 };
17092 struct guestfs_isoinfo_list {
17094 uint32_t len; /* Number of elements in list. */
17095 struct guestfs_isoinfo *val; /* Elements. */
17096 };
17097 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
17099 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
17100 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
17102 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
17103 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
17105 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
17106 guestfs_mdstat
17108 struct guestfs_mdstat {
17109 char *mdstat_device;
17110 int32_t mdstat_index;
17111 char *mdstat_flags;
17112 };
17113 struct guestfs_mdstat_list {
17115 uint32_t len; /* Number of elements in list. */
17116 struct guestfs_mdstat *val; /* Elements. */
17117 };
17118 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
17120 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
17121 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
17123 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
17124 void guestfs_free_mdstat (struct guestfs_mdstat *);
17126 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
17127 guestfs_btrfssubvolume
17129 struct guestfs_btrfssubvolume {
17130 uint64_t btrfssubvolume_id;
17131 uint64_t btrfssubvolume_top_level_id;
17132 char *btrfssubvolume_path;
17133 };
17134 struct guestfs_btrfssubvolume_list {
17136 uint32_t len; /* Number of elements in list. */
17137 struct guestfs_btrfssubvolume *val; /* Elements. */
17138 };
17139 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17141 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17142 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17144 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17145 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17147 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17148 guestfs_btrfsqgroup
17150 struct guestfs_btrfsqgroup {
17151 char *btrfsqgroup_id;
17152 uint64_t btrfsqgroup_rfer;
17153 uint64_t btrfsqgroup_excl;
17154 };
17155 struct guestfs_btrfsqgroup_list {
17157 uint32_t len; /* Number of elements in list. */
17158 struct guestfs_btrfsqgroup *val; /* Elements. */
17159 };
17160 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17162 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17163 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17165 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17166 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17168 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17169 guestfs_btrfsbalance
17171 struct guestfs_btrfsbalance {
17172 char *btrfsbalance_status;
17173 uint64_t btrfsbalance_total;
17174 uint64_t btrfsbalance_balanced;
17175 uint64_t btrfsbalance_considered;
17176 uint64_t btrfsbalance_left;
17177 };
17178 struct guestfs_btrfsbalance_list {
17180 uint32_t len; /* Number of elements in list. */
17181 struct guestfs_btrfsbalance *val; /* Elements. */
17182 };
17183 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17185 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17186 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17188 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17189 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17191 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17192 guestfs_btrfsscrub
17194 struct guestfs_btrfsscrub {
17195 uint64_t btrfsscrub_data_extents_scrubbed;
17196 uint64_t btrfsscrub_tree_extents_scrubbed;
17197 uint64_t btrfsscrub_data_bytes_scrubbed;
17198 uint64_t btrfsscrub_tree_bytes_scrubbed;
17199 uint64_t btrfsscrub_read_errors;
17200 uint64_t btrfsscrub_csum_errors;
17201 uint64_t btrfsscrub_verify_errors;
17202 uint64_t btrfsscrub_no_csum;
17203 uint64_t btrfsscrub_csum_discards;
17204 uint64_t btrfsscrub_super_errors;
17205 uint64_t btrfsscrub_malloc_errors;
17206 uint64_t btrfsscrub_uncorrectable_errors;
17207 uint64_t btrfsscrub_unverified_errors;
17208 uint64_t btrfsscrub_corrected_errors;
17209 uint64_t btrfsscrub_last_physical;
17210 };
17211 struct guestfs_btrfsscrub_list {
17213 uint32_t len; /* Number of elements in list. */
17214 struct guestfs_btrfsscrub *val; /* Elements. */
17215 };
17216 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17218 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17219 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17221 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17222 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17224 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17225 guestfs_xfsinfo
17227 struct guestfs_xfsinfo {
17228 char *xfs_mntpoint;
17229 uint32_t xfs_inodesize;
17230 uint32_t xfs_agcount;
17231 uint32_t xfs_agsize;
17232 uint32_t xfs_sectsize;
17233 uint32_t xfs_attr;
17234 uint32_t xfs_blocksize;
17235 uint64_t xfs_datablocks;
17236 uint32_t xfs_imaxpct;
17237 uint32_t xfs_sunit;
17238 uint32_t xfs_swidth;
17239 uint32_t xfs_dirversion;
17240 uint32_t xfs_dirblocksize;
17241 uint32_t xfs_cimode;
17242 char *xfs_logname;
17243 uint32_t xfs_logblocksize;
17244 uint32_t xfs_logblocks;
17245 uint32_t xfs_logversion;
17246 uint32_t xfs_logsectsize;
17247 uint32_t xfs_logsunit;
17248 uint32_t xfs_lazycount;
17249 char *xfs_rtname;
17250 uint32_t xfs_rtextsize;
17251 uint64_t xfs_rtblocks;
17252 uint64_t xfs_rtextents;
17253 };
17254 struct guestfs_xfsinfo_list {
17256 uint32_t len; /* Number of elements in list. */
17257 struct guestfs_xfsinfo *val; /* Elements. */
17258 };
17259 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17261 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17262 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17264 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17265 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17267 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17268 guestfs_utsname
17270 struct guestfs_utsname {
17271 char *uts_sysname;
17272 char *uts_release;
17273 char *uts_version;
17274 char *uts_machine;
17275 };
17276 struct guestfs_utsname_list {
17278 uint32_t len; /* Number of elements in list. */
17279 struct guestfs_utsname *val; /* Elements. */
17280 };
17281 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17283 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17284 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17286 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17287 void guestfs_free_utsname (struct guestfs_utsname *);
17289 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17290 guestfs_hivex_node
17292 struct guestfs_hivex_node {
17293 int64_t hivex_node_h;
17294 };
17295 struct guestfs_hivex_node_list {
17297 uint32_t len; /* Number of elements in list. */
17298 struct guestfs_hivex_node *val; /* Elements. */
17299 };
17300 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17302 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17303 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17305 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17306 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17308 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17309 guestfs_hivex_value
17311 struct guestfs_hivex_value {
17312 int64_t hivex_value_h;
17313 };
17314 struct guestfs_hivex_value_list {
17316 uint32_t len; /* Number of elements in list. */
17317 struct guestfs_hivex_value *val; /* Elements. */
17318 };
17319 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17321 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17322 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17324 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17325 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17327 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17328 guestfs_internal_mountable
17330 struct guestfs_internal_mountable {
17331 int32_t im_type;
17332 char *im_device;
17333 char *im_volume;
17334 };
17335 struct guestfs_internal_mountable_list {
17337 uint32_t len; /* Number of elements in list. */
17338 struct guestfs_internal_mountable *val; /* Elements. */
17339 };
17340 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17342 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17343 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17345 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17346 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17348 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17349 guestfs_tsk_dirent
17351 struct guestfs_tsk_dirent {
17352 uint64_t tsk_inode;
17353 char tsk_type;
17354 int64_t tsk_size;
17355 char *tsk_name;
17356 uint32_t tsk_flags;
17357 int64_t tsk_atime_sec;
17358 int64_t tsk_atime_nsec;
17359 int64_t tsk_mtime_sec;
17360 int64_t tsk_mtime_nsec;
17361 int64_t tsk_ctime_sec;
17362 int64_t tsk_ctime_nsec;
17363 int64_t tsk_crtime_sec;
17364 int64_t tsk_crtime_nsec;
17365 int64_t tsk_nlink;
17366 char *tsk_link;
17367 int64_t tsk_spare1;
17368 };
17369 struct guestfs_tsk_dirent_list {
17371 uint32_t len; /* Number of elements in list. */
17372 struct guestfs_tsk_dirent *val; /* Elements. */
17373 };
17374 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17376 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17377 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17379 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17380 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17382 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17383 guestfs_yara_detection
17385 struct guestfs_yara_detection {
17386 char *yara_name;
17387 char *yara_rule;
17388 };
17389 struct guestfs_yara_detection_list {
17391 uint32_t len; /* Number of elements in list. */
17392 struct guestfs_yara_detection *val; /* Elements. */
17393 };
17394 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17396 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17397 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17399 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17400 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17402 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17403
17405 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17406 Using "guestfs_available" you can test availability of the following
17407 groups of functions. This test queries the appliance to see if the
17408 appliance you are currently using supports the functionality.
17409 acl The following functions: "guestfs_acl_delete_def_file"
17411 "guestfs_acl_get_file" "guestfs_acl_set_file"
17412 blkdiscard
17414 The following functions: "guestfs_blkdiscard"
17415 blkdiscardzeroes
17417 The following functions: "guestfs_blkdiscardzeroes"
17418 btrfs
17420 The following functions: "guestfs_btrfs_balance_cancel"
17421 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17422 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17423 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17424 "guestfs_btrfs_filesystem_defragment"
17425 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17426 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17427 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17428 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17429 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17430 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17431 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17432 "guestfs_btrfs_rescue_chunk_recover"
17433 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17434 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17435 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17436 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17437 "guestfs_btrfs_subvolume_get_default"
17438 "guestfs_btrfs_subvolume_list"
17439 "guestfs_btrfs_subvolume_set_default"
17440 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17441 "guestfs_btrfstune_enable_extended_inode_refs"
17442 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17443 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17444 clevisluks
17446 The following functions: "guestfs_clevis_luks_unlock"
17447 extlinux
17449 The following functions: "guestfs_extlinux"
17450 f2fs
17452 The following functions: "guestfs_f2fs_expand"
17453 fstrim
17455 The following functions: "guestfs_fstrim"
17456 gdisk
17458 The following functions: "guestfs_part_expand_gpt"
17459 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17460 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17461 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17462 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17463 "guestfs_part_set_gpt_type"
17464 grub
17466 The following functions: "guestfs_grub_install"
17467 hivex
17469 The following functions: "guestfs_hivex_close"
17470 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17471 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17472 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17473 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17474 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17475 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17476 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17477 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17478 inotify
17480 The following functions: "guestfs_inotify_add_watch"
17481 "guestfs_inotify_close" "guestfs_inotify_files"
17482 "guestfs_inotify_init" "guestfs_inotify_read"
17483 "guestfs_inotify_rm_watch"
17484 journal
17486 The following functions: "guestfs_internal_journal_get"
17487 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17488 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17489 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17490 "guestfs_journal_skip"
17491 ldm The following functions: "guestfs_ldmtool_create_all"
17493 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17494 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17495 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17496 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17497 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17498 "guestfs_list_ldm_volumes"
17499 libtsk
17501 The following functions: "guestfs_internal_filesystem_walk"
17502 "guestfs_internal_find_inode"
17503 libyara
17505 The following functions: "guestfs_internal_yara_scan"
17506 "guestfs_yara_destroy" "guestfs_yara_load"
17507 linuxcaps
17509 The following functions: "guestfs_cap_get_file"
17510 "guestfs_cap_set_file"
17511 linuxfsuuid
17513 The following functions: "guestfs_mke2fs_JU"
17514 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17515 "guestfs_swapon_uuid"
17516 linuxmodules
17518 The following functions: "guestfs_modprobe"
17519 linuxxattrs
17521 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17522 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17523 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17524 "guestfs_removexattr" "guestfs_setxattr"
17525 luks
17527 The following functions: "guestfs_cryptsetup_close"
17528 "guestfs_cryptsetup_open" "guestfs_luks_add_key"
17529 "guestfs_luks_close" "guestfs_luks_format"
17530 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17531 "guestfs_luks_open" "guestfs_luks_open_ro" "guestfs_luks_uuid"
17532 lvm2
17534 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17535 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17536 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17537 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17538 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17539 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17540 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17541 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17542 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17543 "guestfs_vgs" "guestfs_vgs_full"
17544 mdadm
17546 The following functions: "guestfs_md_create" "guestfs_md_detail"
17547 "guestfs_md_stat" "guestfs_md_stop"
17548 mknod
17550 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17551 "guestfs_mknod_b" "guestfs_mknod_c"
17552 ntfs3g
17554 The following functions: "guestfs_ntfs_3g_probe"
17555 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17556 ntfsprogs
17558 The following functions: "guestfs_ntfsresize"
17559 "guestfs_ntfsresize_size"
17560 rsync
17562 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17563 "guestfs_rsync_out"
17564 scrub
17566 The following functions: "guestfs_scrub_device"
17567 "guestfs_scrub_file" "guestfs_scrub_freespace"
17568 selinux
17570 The following functions: "guestfs_getcon" "guestfs_setcon"
17571 selinuxrelabel
17573 The following functions: "guestfs_selinux_relabel"
17574 sleuthkit
17576 The following functions: "guestfs_download_blocks"
17577 "guestfs_download_inode"
17578 squashfs
17580 The following functions: "guestfs_mksquashfs"
17581 syslinux
17583 The following functions: "guestfs_syslinux"
17584 wipefs
17586 The following functions: "guestfs_wipefs"
17587 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17589 "guestfs_xfs_info" "guestfs_xfs_repair"
17590 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17592 zerofree
17594 The following functions: "guestfs_zerofree"
17595 FILESYSTEM AVAILABLE
17597 The "guestfs_filesystem_available" call tests whether a filesystem type
17598 is supported by the appliance kernel.
17599 This is mainly useful as a negative test. If this returns true, it
17601 doesn't mean that a particular filesystem can be mounted, since
17602 filesystems can fail for other reasons such as it being a later version
17603 of the filesystem, or having incompatible features.
17604 GUESTFISH supported COMMAND
17606 In guestfish(3) there is a handy interactive command "supported" which
17607 prints out the available groups and whether they are supported by this
17608 build of libguestfs. Note however that you have to do "run" first.
17609 SINGLE CALLS AT COMPILE TIME
17611 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17612 function, such as:
17613 #define GUESTFS_HAVE_DD 1
17615 if "guestfs_dd" is available.
17617 Before version 1.5.8, if you needed to test whether a single libguestfs
17619 function is available at compile time, we recommended using build tools
17620 such as autoconf or cmake. For example in autotools you could use:
17621 AC_CHECK_LIB([guestfs],[guestfs_create])
17623 AC_CHECK_FUNCS([guestfs_dd])
17624 which would result in "HAVE_GUESTFS_DD" being either defined or not
17626 defined in your program.
17627 SINGLE CALLS AT RUN TIME
17629 Testing at compile time doesn't guarantee that a function really exists
17630 in the library. The reason is that you might be dynamically linked
17631 against a previous libguestfs.so (dynamic library) which doesn't have
17632 the call. This situation unfortunately results in a segmentation
17633 fault, which is a shortcoming of the C dynamic linking system itself.
17634 You can use dlopen(3) to test if a function is available at run time,
17636 as in this example program (note that you still need the compile time
17637 check as well):
17638 #include <stdio.h>
17640 #include <stdlib.h>
17641 #include <unistd.h>
17642 #include <dlfcn.h>
17643 #include <guestfs.h>
17644 main ()
17646 {
17647 #ifdef GUESTFS_HAVE_DD
17648 void *dl;
17649 int has_function;
17650 /* Test if the function guestfs_dd is really available. */
17652 dl = dlopen (NULL, RTLD_LAZY);
17653 if (!dl) {
17654 fprintf (stderr, "dlopen: %s\n", dlerror ());
17655 exit (EXIT_FAILURE);
17656 }
17657 has_function = dlsym (dl, "guestfs_dd") != NULL;
17658 dlclose (dl);
17659 if (!has_function)
17661 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17662 else {
17663 printf ("this libguestfs.so has guestfs_dd function\n");
17664 /* Now it's safe to call
17665 guestfs_dd (g, "foo", "bar");
17666 */
17667 }
17668 #else
17669 printf ("guestfs_dd function was not found at compile time\n");
17670 #endif
17671 }
17672 You may think the above is an awful lot of hassle, and it is. There
17674 are other ways outside of the C linking system to ensure that this kind
17675 of incompatibility never arises, such as using package versioning:
17676 Requires: libguestfs >= 1.0.80
17678
17680 A recent feature of the API is the introduction of calls which take
17681 optional arguments. In C these are declared 3 ways. The main way is
17682 as a call which takes variable arguments (ie. "..."), as in this
17683 example:
17684 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17686 Call this with a list of optional arguments, terminated by -1. So to
17688 call with no optional arguments specified:
17689 guestfs_add_drive_opts (g, filename, -1);
17691 With a single optional argument:
17693 guestfs_add_drive_opts (g, filename,
17695 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17696 -1);
17697 With two:
17699 guestfs_add_drive_opts (g, filename,
17701 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17702 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17703 -1);
17704 and so forth. Don’t forget the terminating -1 otherwise Bad Things
17706 will happen!
17707 USING va_list FOR OPTIONAL ARGUMENTS
17709 The second variant has the same name with the suffix "_va", which works
17710 the same way but takes a "va_list". See the C manual for details. For
17711 the example function, this is declared:
17712 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17714 va_list args);
17715 CONSTRUCTING OPTIONAL ARGUMENTS
17717 The third variant is useful where you need to construct these calls.
17718 You pass in a structure where you fill in the optional fields. The
17719 structure has a bitmask as the first element which you must set to
17720 indicate which fields you have filled in. For our example function the
17721 structure and call are declared:
17722 struct guestfs_add_drive_opts_argv {
17724 uint64_t bitmask;
17725 int readonly;
17726 const char *format;
17727 /* ... */
17728 };
17729 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17730 const struct guestfs_add_drive_opts_argv *optargs);
17731 You could call it like this:
17733 struct guestfs_add_drive_opts_argv optargs = {
17735 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17736 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17737 .readonly = 1,
17738 .format = "qcow2"
17739 };
17740 guestfs_add_drive_opts_argv (g, filename, &optargs);
17742 Notes:
17744 • The "_BITMASK" suffix on each option name when specifying the
17746 bitmask.
17747 • You do not need to fill in all fields of the structure.
17749 • There must be a one-to-one correspondence between fields of the
17751 structure that are filled in, and bits set in the bitmask.
17752 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17754 In other languages, optional arguments are expressed in the way that is
17755 natural for that language. We refer you to the language-specific
17756 documentation for more details on that.
17757 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17759
17761 SETTING CALLBACKS TO HANDLE EVENTS
17762 Note: This section documents the generic event mechanism introduced in
17763 libguestfs 1.10, which you should use in new code if possible. The old
17764 functions "guestfs_set_log_message_callback",
17765 "guestfs_set_subprocess_quit_callback",
17766 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17767 "guestfs_set_progress_callback" are no longer documented in this manual
17768 page. Because of the ABI guarantee, the old functions continue to
17769 work.
17770 Handles generate events when certain things happen, such as log
17772 messages being generated, progress messages during long-running
17773 operations, or the handle being closed. The API calls described below
17774 let you register a callback to be called when events happen. You can
17775 register multiple callbacks (for the same, different or overlapping
17776 sets of events), and individually remove callbacks. If callbacks are
17777 not removed, then they remain in force until the handle is closed.
17778 In the current implementation, events are only generated synchronously:
17780 that means that events (and hence callbacks) can only happen while you
17781 are in the middle of making another libguestfs call. The callback is
17782 called in the same thread.
17783 Events may contain a payload, usually nothing (void), an array of 64
17785 bit unsigned integers, or a message buffer. Payloads are discussed
17786 later on.
17787 CLASSES OF EVENTS
17789 GUESTFS_EVENT_CLOSE (payload type: void)
17790 The callback function will be called while the handle is being
17791 closed (synchronously from "guestfs_close").
17792 Note that libguestfs installs an atexit(3) handler to try to clean
17794 up handles that are open when the program exits. This means that
17795 this callback might be called indirectly from exit(3), which can
17796 cause unexpected problems in higher-level languages (eg. if your
17797 HLL interpreter has already been cleaned up by the time this is
17798 called, and if your callback then jumps into some HLL function).
17799 If no callback is registered: the handle is closed without any
17801 callback being invoked.
17802 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17804 The callback function will be called when the child process quits,
17805 either asynchronously or if killed by "guestfs_kill_subprocess".
17806 (This corresponds to a transition from any state to the CONFIG
17807 state).
17808 If no callback is registered: the event is ignored.
17810 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17812 The callback function will be called when the child process becomes
17813 ready first time after it has been launched. (This corresponds to
17814 a transition from LAUNCHING to the READY state).
17815 If no callback is registered: the event is ignored.
17817 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17819 Some long-running operations can generate progress messages. If
17820 this callback is registered, then it will be called each time a
17821 progress message is generated (usually two seconds after the
17822 operation started, and three times per second thereafter until it
17823 completes, although the frequency may change in future versions).
17824 The callback receives in the payload four unsigned 64 bit numbers
17826 which are (in order): "proc_nr", "serial", "position", "total".
17827 The units of "total" are not defined, although for some operations
17829 "total" may relate in some way to the amount of data to be
17830 transferred (eg. in bytes or megabytes), and "position" may be the
17831 portion which has been transferred.
17832 The only defined and stable parts of the API are:
17834 • The callback can display to the user some type of progress bar
17836 or indicator which shows the ratio of "position":"total".
17837 • 0 <= "position" <= "total"
17839 • If any progress notification is sent during a call, then a
17841 final progress notification is always sent when "position" =
17842 "total" (unless the call fails with an error).
17843 This is to simplify caller code, so callers can easily set the
17845 progress indicator to "100%" at the end of the operation,
17846 without requiring special code to detect this case.
17847 • For some calls we are unable to estimate the progress of the
17849 call, but we can still generate progress messages to indicate
17850 activity. This is known as "pulse mode", and is directly
17851 supported by certain progress bar implementations (eg.
17852 GtkProgressBar).
17853 For these calls, zero or more progress messages are generated
17855 with "position = 0" and "total = 1", followed by a final
17856 message with "position = total = 1".
17857 As noted above, if the call fails with an error then the final
17859 message may not be generated.
17860 The callback also receives the procedure number ("proc_nr") and
17862 serial number ("serial") of the call. These are only useful for
17863 debugging protocol issues, and the callback can normally ignore
17864 them. The callback may want to print these numbers in error
17865 messages or debugging messages.
17866 If no callback is registered: progress messages are discarded.
17868 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17870 The callback function is called whenever a log message is generated
17871 by qemu, the appliance kernel, guestfsd (daemon), or utility
17872 programs.
17873 If the verbose flag ("guestfs_set_verbose") is set before launch
17875 ("guestfs_launch") then additional debug messages are generated.
17876 If no callback is registered: the messages are discarded unless the
17878 verbose flag is set in which case they are sent to stderr. You can
17879 override the printing of verbose messages to stderr by setting up a
17880 callback.
17881 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17883 The callback function is called whenever a log message is generated
17884 by the library part of libguestfs.
17885 If the verbose flag ("guestfs_set_verbose") is set then additional
17887 debug messages are generated.
17888 If no callback is registered: the messages are discarded unless the
17890 verbose flag is set in which case they are sent to stderr. You can
17891 override the printing of verbose messages to stderr by setting up a
17892 callback.
17893 GUESTFS_EVENT_WARNING (payload type: message buffer)
17895 The callback function is called whenever a warning message is
17896 generated by the library part of libguestfs.
17897 If no callback is registered: the messages are printed to stderr.
17899 You can override the printing of warning messages to stderr by
17900 setting up a callback.
17901 GUESTFS_EVENT_TRACE (payload type: message buffer)
17903 The callback function is called whenever a trace message is
17904 generated. This only applies if the trace flag
17905 ("guestfs_set_trace") is set.
17906 If no callback is registered: the messages are sent to stderr. You
17908 can override the printing of trace messages to stderr by setting up
17909 a callback.
17910 GUESTFS_EVENT_ENTER (payload type: function name)
17912 The callback function is called whenever a libguestfs function is
17913 entered.
17914 The payload is a string which contains the name of the function
17916 that we are entering (not including "guestfs_" prefix).
17917 Note that libguestfs functions can call themselves, so you may see
17919 many events from a single call. A few libguestfs functions do not
17920 generate this event.
17921 If no callback is registered: the event is ignored.
17923 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17925 For any API function that opens a libvirt connection, this event
17926 may be generated to indicate that libvirt demands authentication
17927 information. See "LIBVIRT AUTHENTICATION" below.
17928 If no callback is registered: "virConnectAuthPtrDefault" is used
17930 (suitable for command-line programs only).
17931 EVENT API
17933 guestfs_set_event_callback
17934 int guestfs_set_event_callback (guestfs_h *g,
17936 guestfs_event_callback cb,
17937 uint64_t event_bitmask,
17938 int flags,
17939 void *opaque);
17940 This function registers a callback ("cb") for all event classes in the
17942 "event_bitmask".
17943 For example, to register for all log message events, you could call
17945 this function with the bitmask
17946 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17947 To register a single callback for all possible classes of events, use
17948 "GUESTFS_EVENT_ALL".
17949 "flags" should always be passed as 0.
17951 "opaque" is an opaque pointer which is passed to the callback. You can
17953 use it for any purpose.
17954 The return value is the event handle (an integer) which you can use to
17956 delete the callback (see below).
17957 If there is an error, this function returns -1, and sets the error in
17959 the handle in the usual way (see "guestfs_last_error" etc.)
17960 Callbacks remain in effect until they are deleted, or until the handle
17962 is closed.
17963 In the case where multiple callbacks are registered for a particular
17965 event class, all of the callbacks are called. The order in which
17966 multiple callbacks are called is not defined.
17967 guestfs_delete_event_callback
17969 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
17971 Delete a callback that was previously registered. "event_handle"
17973 should be the integer that was returned by a previous call to
17974 "guestfs_set_event_callback" on the same handle.
17975 guestfs_event_to_string
17977 char *guestfs_event_to_string (uint64_t event);
17979 "event" is either a single event or a bitmask of events. This returns
17981 a string representation (useful for debugging or printing events).
17982 A single event is returned as the name in lower case, eg. "close".
17984 A bitmask of several events is returned as a comma-separated list, eg.
17986 "close,progress".
17987 If zero is passed, then the empty string "" is returned.
17989 On success this returns a string. On error it returns NULL and sets
17991 "errno".
17992 The returned string must be freed by the caller.
17994 guestfs_event_callback
17996 typedef void (*guestfs_event_callback) (
17998 guestfs_h *g,
17999 void *opaque,
18000 uint64_t event,
18001 int event_handle,
18002 int flags,
18003 const char *buf, size_t buf_len,
18004 const uint64_t *array, size_t array_len);
18005 This is the type of the event callback function that you have to
18007 provide.
18008 The basic parameters are: the handle ("g"), the opaque user pointer
18010 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
18011 handle, and "flags" which in the current API you should ignore.
18012 The remaining parameters contain the event payload (if any). Each
18014 event may contain a payload, which usually relates to the event class,
18015 but for future proofing your code should be written to handle any
18016 payload for any event class.
18017 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
18019 there is no message buffer). Note that this message buffer can contain
18020 arbitrary 8 bit data, including NUL bytes.
18021 "array" and "array_len" is an array of 64 bit unsigned integers. At
18023 the moment this is only used for progress messages.
18024 EXAMPLE: CAPTURING LOG MESSAGES
18026 A working program demonstrating this can be found in
18027 examples/debug-logging.c in the source of libguestfs.
18028 One motivation for the generic event API was to allow GUI programs to
18030 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
18031 unconditionally to "stderr".
18032 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
18034 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
18035 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
18036 must capture error messages separately).
18037 Programs have to set up a callback to capture the classes of events of
18039 interest:
18040 int eh =
18042 guestfs_set_event_callback
18043 (g, message_callback,
18044 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
18045 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
18046 0, NULL) == -1)
18047 if (eh == -1) {
18048 // handle error in the usual way
18049 }
18050 The callback can then direct messages to the appropriate place. In
18052 this example, messages are directed to syslog:
18053 static void
18055 message_callback (
18056 guestfs_h *g,
18057 void *opaque,
18058 uint64_t event,
18059 int event_handle,
18060 int flags,
18061 const char *buf, size_t buf_len,
18062 const uint64_t *array, size_t array_len)
18063 {
18064 const int priority = LOG_USER|LOG_INFO;
18065 if (buf_len > 0)
18066 syslog (priority, "event 0x%lx: %s", event, buf);
18067 }
18068 LIBVIRT AUTHENTICATION
18070 Some libguestfs API calls can open libvirt connections. Currently the
18071 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
18072 backend has been selected. Libvirt connections may require
18073 authentication, for example if they need to access a remote server or
18074 to access root services from non-root. Libvirt authentication happens
18075 via a callback mechanism, see
18076 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
18077 You may provide libvirt authentication data by registering a callback
18079 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
18080 If no such event is registered, then libguestfs uses a libvirt function
18082 that provides command-line prompts ("virConnectAuthPtrDefault"). This
18083 is only suitable for command-line libguestfs programs.
18084 To provide authentication, first call
18086 "guestfs_set_libvirt_supported_credentials" with the list of
18087 credentials your program knows how to provide. Second, register a
18088 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
18089 will be called when libvirt is requesting authentication information.
18090 In the event handler, call "guestfs_get_libvirt_requested_credentials"
18092 to get a list of the credentials that libvirt is asking for. You then
18093 need to ask (eg. the user) for each credential, and call
18094 "guestfs_set_libvirt_requested_credential" with the answer. Note that
18095 for each credential, additional information may be available via the
18096 calls "guestfs_get_libvirt_requested_credential_prompt",
18097 "guestfs_get_libvirt_requested_credential_challenge" or
18098 "guestfs_get_libvirt_requested_credential_defresult".
18099 The example program below should make this clearer.
18101 There is also a more substantial working example program supplied with
18103 the libguestfs sources, called libvirt-auth.c.
18104 main ()
18106 {
18107 guestfs_h *g;
18108 char *creds[] = { "authname", "passphrase", NULL };
18109 int r, eh;
18110 g = guestfs_create ();
18112 if (!g) exit (EXIT_FAILURE);
18113 /* Tell libvirt what credentials the program supports. */
18115 r = guestfs_set_libvirt_supported_credentials (g, creds);
18116 if (r == -1)
18117 exit (EXIT_FAILURE);
18118 /* Set up the event handler. */
18120 eh = guestfs_set_event_callback (
18121 g, do_auth,
18122 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
18123 if (eh == -1)
18124 exit (EXIT_FAILURE);
18125 /* An example of a call that may ask for credentials. */
18127 r = guestfs_add_domain (
18128 g, "dom",
18129 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
18130 -1);
18131 if (r == -1)
18132 exit (EXIT_FAILURE);
18133 exit (EXIT_SUCCESS);
18135 }
18136 static void
18138 do_auth (guestfs_h *g,
18139 void *opaque,
18140 uint64_t event,
18141 int event_handle,
18142 int flags,
18143 const char *buf, size_t buf_len,
18144 const uint64_t *array, size_t array_len)
18145 {
18146 char **creds;
18147 size_t i;
18148 char *prompt;
18149 char *reply;
18150 size_t replylen;
18151 int r;
18152 // buf will be the libvirt URI. buf_len may be ignored.
18154 printf ("Authentication required for libvirt conn '%s'\n",
18155 buf);
18156 // Ask libguestfs what credentials libvirt is demanding.
18158 creds = guestfs_get_libvirt_requested_credentials (g);
18159 if (creds == NULL)
18160 exit (EXIT_FAILURE);
18161 // Now ask the user for answers.
18163 for (i = 0; creds[i] != NULL; ++i)
18164 {
18165 if (strcmp (creds[i], "authname") == 0 ||
18166 strcmp (creds[i], "passphrase") == 0)
18167 {
18168 prompt =
18169 guestfs_get_libvirt_requested_credential_prompt (g, i);
18170 if (prompt && strcmp (prompt, "") != 0)
18171 printf ("%s: ", prompt);
18172 free (prompt);
18173 // Some code here to ask for the credential.
18175 // ...
18176 // Put the reply in 'reply', length 'replylen' (bytes).
18177 r = guestfs_set_libvirt_requested_credential (g, i,
18179 reply, replylen);
18180 if (r == -1)
18181 exit (EXIT_FAILURE);
18182 }
18183 free (creds[i]);
18185 }
18186 free (creds);
18188 }
18189
18191 Some operations can be cancelled by the caller while they are in
18192 progress. Currently only operations that involve uploading or
18193 downloading data can be cancelled (technically: operations that have
18194 "FileIn" or "FileOut" parameters in the generator).
18195 To cancel the transfer, call "guestfs_user_cancel". For more
18197 information, read the description of "guestfs_user_cancel".
18198
18200 You can attach named pieces of private data to the libguestfs handle,
18201 fetch them by name, and walk over them, for the lifetime of the handle.
18202 This is called the private data area and is only available from the C
18203 API.
18204 To attach a named piece of data, use the following call:
18206 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18208 "key" is the name to associate with this data, and "data" is an
18210 arbitrary pointer (which can be "NULL"). Any previous item with the
18211 same key is overwritten.
18212 You can use any "key" string you want, but avoid keys beginning with an
18214 underscore character (libguestfs uses those for its own internal
18215 purposes, such as implementing language bindings). It is recommended
18216 that you prefix the key with some unique string to avoid collisions
18217 with other users.
18218 To retrieve the pointer, use:
18220 void *guestfs_get_private (guestfs_h *g, const char *key);
18222 This function returns "NULL" if either no data is found associated with
18224 "key", or if the user previously set the "key"’s "data" pointer to
18225 "NULL".
18226 Libguestfs does not try to look at or interpret the "data" pointer in
18228 any way. As far as libguestfs is concerned, it need not be a valid
18229 pointer at all. In particular, libguestfs does not try to free the
18230 data when the handle is closed. If the data must be freed, then the
18231 caller must either free it before calling "guestfs_close" or must set
18232 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18233 To walk over all entries, use these two functions:
18235 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18237 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18239 "guestfs_first_private" returns the first key, pointer pair ("first"
18241 does not have any particular meaning -- keys are not returned in any
18242 defined order). A pointer to the key is returned in *key_rtn and the
18243 corresponding data pointer is returned from the function. "NULL" is
18244 returned if there are no keys stored in the handle.
18245 "guestfs_next_private" returns the next key, pointer pair. The return
18247 value of this function is "NULL" if there are no further entries to
18248 return.
18249 Notes about walking over entries:
18251 • You must not call "guestfs_set_private" while walking over the
18253 entries.
18254 • The handle maintains an internal iterator which is reset when you
18256 call "guestfs_first_private". This internal iterator is
18257 invalidated when you call "guestfs_set_private".
18258 • If you have set the data pointer associated with a key to "NULL",
18260 ie:
18261 guestfs_set_private (g, key, NULL);
18263 then that "key" is not returned when walking.
18265 • *key_rtn is only valid until the next call to
18267 "guestfs_first_private", "guestfs_next_private" or
18268 "guestfs_set_private".
18269 The following example code shows how to print all keys and data
18271 pointers that are associated with the handle "g":
18272 const char *key;
18274 void *data = guestfs_first_private (g, &key);
18275 while (data != NULL)
18276 {
18277 printf ("key = %s, data = %p\n", key, data);
18278 data = guestfs_next_private (g, &key);
18279 }
18280 More commonly you are only interested in keys that begin with an
18282 application-specific prefix "foo_". Modify the loop like so:
18283 const char *key;
18285 void *data = guestfs_first_private (g, &key);
18286 while (data != NULL)
18287 {
18288 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18289 printf ("key = %s, data = %p\n", key, data);
18290 data = guestfs_next_private (g, &key);
18291 }
18292 If you need to modify keys while walking, then you have to jump back to
18294 the beginning of the loop. For example, to delete all keys prefixed
18295 with "foo_":
18296 const char *key;
18298 void *data;
18299 again:
18300 data = guestfs_first_private (g, &key);
18301 while (data != NULL)
18302 {
18303 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18304 {
18305 guestfs_set_private (g, key, NULL);
18306 /* note that 'key' pointer is now invalid, and so is
18307 the internal iterator */
18308 goto again;
18309 }
18310 data = guestfs_next_private (g, &key);
18311 }
18312 Note that the above loop is guaranteed to terminate because the keys
18314 are being deleted, but other manipulations of keys within the loop
18315 might not terminate unless you also maintain an indication of which
18316 keys have been visited.
18317
18319 Since April 2010, libguestfs has started to make separate development
18320 and stable releases, along with corresponding branches in our git
18321 repository. These separate releases can be identified by version
18322 number:
18323 even numbers for stable: 1.2.x, 1.4.x, ...
18325 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18326 |
18327 v
18328 1 . 3 . 5
18329 ^ ^
18330 | |
18331 | `-------- sub-version
18332 |
18333 `------ always '1' because we don't change the ABI
18334 Thus "1.3.5" is the 5th update to the development branch "1.3".
18336 As time passes we cherry pick fixes from the development branch and
18338 backport those into the stable branch, the effect being that the stable
18339 branch should get more stable and less buggy over time. So the stable
18340 releases are ideal for people who don't need new features but would
18341 just like the software to work.
18342 Our criteria for backporting changes are:
18344 • Documentation changes which don’t affect any code are backported
18346 unless the documentation refers to a future feature which is not in
18347 stable.
18348 • Bug fixes which are not controversial, fix obvious problems, and
18350 have been well tested are backported.
18351 • Simple rearrangements of code which shouldn't affect how it works
18353 get backported. This is so that the code in the two branches
18354 doesn't get too far out of step, allowing us to backport future
18355 fixes more easily.
18356 • We don’t backport new features, new APIs, new tools etc, except in
18358 one exceptional case: the new feature is required in order to
18359 implement an important bug fix.
18360 A new stable branch starts when we think the new features in
18362 development are substantial and compelling enough over the current
18363 stable branch to warrant it. When that happens we create new stable
18364 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18365 oh release won't necessarily be so stable at this point, but by
18366 backporting fixes from development, that branch will stabilize over
18367 time.
18368
18370 PROTOCOL LIMITS
18371 Internally libguestfs uses a message-based protocol to pass API calls
18372 and their responses to and from a small "appliance" (see
18373 guestfs-internals(1) for plenty more detail about this). The maximum
18374 message size used by the protocol is slightly less than 4 MB. For some
18375 API calls you may need to be aware of this limit. The API calls which
18376 may be affected are individually documented, with a link back to this
18377 section of the documentation.
18378 In libguestfs < 1.19.32, several calls had to encode either their
18380 entire argument list or their entire return value (or sometimes both)
18381 in a single protocol message, and this gave them an arbitrary
18382 limitation on how much data they could handle. For example,
18383 "guestfs_cat" could only download a file if it was less than around 4
18384 MB in size. In later versions of libguestfs, some of these limits have
18385 been removed. The APIs which were previously limited but are now
18386 unlimited (except perhaps by available memory) are listed below. To
18387 find out if a specific API is subject to protocol limits, check for the
18388 warning in the API documentation which links to this section, and
18389 remember to check the version of the documentation that matches the
18390 version of libguestfs you are using.
18391 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18393 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18394 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18395 "guestfs_ls".
18396 See also "UPLOADING" and "DOWNLOADING" for further information about
18398 copying large amounts of data into or out of a filesystem.
18399 MAXIMUM NUMBER OF DISKS
18401 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18402 may be added by calling "guestfs_max_disks". In earlier versions of
18403 libguestfs (ie. where this call is not available) you should assume the
18404 maximum is 25.
18405 The rest of this section covers implementation details, which could
18407 change in future.
18408 When using virtio-scsi disks (the default if available in qemu) the
18410 current limit is 255 disks. When using virtio-blk (the old default)
18411 the limit is around 27 disks, but may vary according to implementation
18412 details and whether the network is enabled.
18413 Virtio-scsi as used by libguestfs is configured to use one target per
18415 disk, and 256 targets are available.
18416 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18418 31 slots, but some of these are used for other purposes.
18419 One virtual disk is used by libguestfs internally.
18421 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18423 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18424 the limit was 25. This has been fixed in more recent versions.
18425 MAXIMUM NUMBER OF PARTITIONS PER DISK
18427 Virtio limits the maximum number of partitions per disk to 15.
18428 This is because it reserves 4 bits for the minor device number (thus
18430 /dev/vda, and /dev/vda1 through /dev/vda15).
18431 If you attach a disk with more than 15 partitions, the extra partitions
18433 are ignored by libguestfs.
18434 MAXIMUM SIZE OF A DISK
18436 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18437 We have tested block devices up to 1 exabyte (2**60 or
18439 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18440 host filesystem.
18441 Although libguestfs probably does not impose any limit, the underlying
18443 host storage will. If you store disk images on a host ext4 filesystem,
18444 then the maximum size will be limited by the maximum ext4 file size
18445 (currently 16 TB). If you store disk images as host logical volumes
18446 then you are limited by the maximum size of an LV.
18447 For the hugest disk image files, we recommend using XFS on the host for
18449 storage.
18450 MAXIMUM SIZE OF A PARTITION
18452 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18453 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18454 address a partition located beyond 2 TB on the disk.
18455 It is recommended that you use GPT partitions on disks which are larger
18457 than this size. GPT uses 64 bit sector numbers and so can address
18458 partitions which are theoretically larger than the largest disk we
18459 could support.
18460 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18462 This depends on the filesystem type. libguestfs itself does not impose
18463 any known limit. Consult Wikipedia or the filesystem documentation to
18464 find out what these limits are.
18465 MAXIMUM UPLOAD AND DOWNLOAD
18467 The API functions "guestfs_upload", "guestfs_download",
18468 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18469 uploads and downloads.
18470 INSPECTION LIMITS
18472 The inspection code has several arbitrary limits on things like the
18473 size of Windows Registry hive it will read, and the length of product
18474 name. These are intended to stop a malicious guest from consuming
18475 arbitrary amounts of memory and disk space on the host, and should not
18476 be reached in practice. See the source code for more information.
18477
18479 Some of the tools support a --machine-readable option, which is
18480 generally used to make the output more machine friendly, for easier
18481 parsing for example. By default, this output goes to stdout.
18482 When using the --machine-readable option, the progress, information,
18484 warning, and error messages are also printed in JSON format for easier
18485 log tracking. Thus, it is highly recommended to redirect the machine-
18486 readable output to a different stream. The format of these JSON
18487 messages is like the following (actually printed within a single line,
18488 below it is indented for readability):
18489 {
18491 "message": "Finishing off",
18492 "timestamp": "2019-03-22T14:46:49.067294446+01:00",
18493 "type": "message"
18494 }
18495 "type" can be: "message" for progress messages, "info" for information
18497 messages, "warning" for warning messages, and "error" for error
18498 message. "timestamp" is the RFC 3339 timestamp of the message.
18499 In addition to that, a subset of these tools support an extra string
18501 passed to the --machine-readable option: this string specifies where
18502 the machine-readable output will go.
18503 The possible values are:
18505 fd:fd
18507 The output goes to the specified fd, which is a file descriptor
18508 already opened for writing.
18509 file:filename
18511 The output goes to the specified filename.
18512 stream:stdout
18514 The output goes to stdout. This is basically the same as the
18515 default behaviour of --machine-readable with no parameter, although
18516 stdout as output is specified explicitly.
18517 stream:stderr
18519 The output goes to stderr.
18520
18522 LIBGUESTFS_APPEND
18523 Pass additional options to the guest kernel.
18524 LIBGUESTFS_ATTACH_METHOD
18526 This is the old way to set "LIBGUESTFS_BACKEND".
18527 LIBGUESTFS_BACKEND
18529 Choose the default way to create the appliance. See
18530 "guestfs_set_backend" and "BACKEND".
18531 LIBGUESTFS_BACKEND_SETTINGS
18533 A colon-separated list of backend-specific settings. See
18534 "BACKEND", "BACKEND SETTINGS".
18535 LIBGUESTFS_CACHEDIR
18537 The location where libguestfs will cache its appliance, when using
18538 a supermin appliance. The appliance is cached and shared between
18539 all handles which have the same effective user ID.
18540 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18542 "TMPDIR" is not set, then /var/tmp is used.
18543 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18545 LIBGUESTFS_DEBUG
18547 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18548 same effect as calling "guestfs_set_verbose (g, 1)".
18549 LIBGUESTFS_HV
18551 Set the default hypervisor (usually qemu) binary that libguestfs
18552 uses. If not set, then the qemu which was found at compile time by
18553 the configure script is used.
18554 See also "QEMU WRAPPERS" above.
18556 LIBGUESTFS_MEMSIZE
18558 Set the memory allocated to the qemu process, in megabytes. For
18559 example:
18560 LIBGUESTFS_MEMSIZE=700
18562 LIBGUESTFS_PATH
18564 Set the path that libguestfs uses to search for a supermin
18565 appliance. See the discussion of paths in section "PATH" above.
18566 LIBGUESTFS_QEMU
18568 This is the old way to set "LIBGUESTFS_HV".
18569 LIBGUESTFS_TMPDIR
18571 The location where libguestfs will store temporary files used by
18572 each handle.
18573 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18575 "TMPDIR" is not set, then /tmp is used.
18576 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18578 LIBGUESTFS_TRACE
18580 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18581 same effect as calling "guestfs_set_trace (g, 1)".
18582 PATH
18584 Libguestfs may run some external programs, and relies on $PATH
18585 being set to a reasonable value. If using the libvirt backend,
18586 libvirt will not work at all unless $PATH contains the path of
18587 qemu/KVM. Note that PHP by default removes $PATH from the
18588 environment which tends to break everything.
18589 SUPERMIN_KERNEL
18591 SUPERMIN_KERNEL_VERSION
18592 SUPERMIN_MODULES
18593 These three environment variables allow the kernel that libguestfs
18594 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18595 set, then the most recent host kernel is chosen. For more
18596 information about kernel selection, see supermin(1).
18597 TMPDIR
18599 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18600 XDG_RUNTIME_DIR
18602 This directory represents a user-specific directory for storing
18603 non-essential runtime files.
18604 If it is set, then is used to store temporary sockets and PID
18606 files. Otherwise, /tmp is used.
18607 See also "guestfs_get_sockdir",
18609 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18610
18612 Examples written in C: guestfs-examples(3).
18613 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18615 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18616 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18617 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18619 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18620 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18621 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18622 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18623 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18624 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18625 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18626 virt-win-reg(1).
18627 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18629 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18630 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18631 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18632 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18634 sd-journal(3).
18635 Website: http://libguestfs.org/
18637 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18639 disktype(1).
18640
18642 Richard W.M. Jones ("rjones at redhat dot com")
18643
18645 Copyright (C) 2009-2023 Red Hat Inc.
18646
18648 This library is free software; you can redistribute it and/or modify it
18649 under the terms of the GNU Lesser General Public License as published
18650 by the Free Software Foundation; either version 2 of the License, or
18651 (at your option) any later version.
18652 This library is distributed in the hope that it will be useful, but
18654 WITHOUT ANY WARRANTY; without even the implied warranty of
18655 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18656 Lesser General Public License for more details.
18657 You should have received a copy of the GNU Lesser General Public
18659 License along with this library; if not, write to the Free Software
18660 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18661 02110-1301 USA
18662
18664 To get a list of bugs against libguestfs, use this link:
18665 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18666 To report a new bug against libguestfs, use this link:
18668 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18669 When reporting a bug, please supply:
18671 • The version of libguestfs.
18673 • Where you got libguestfs (eg. which Linux distro, compiled from
18675 source, etc)
18676 • Describe the bug accurately and give a way to reproduce it.
18678 • Run libguestfs-test-tool(1) and paste the complete, unedited output
18680 into the bug report.
18681libguestfs-1.51.9 2023-12-09 guestfs(3)