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
5102 the backing file, which is discovered automatically. You are
5103 encouraged to also pass "backingformat" to describe the format of
5104 "backingfile".
5105 If filename refers to a block device, then the device is formatted.
5107 The "size" is ignored since block devices have an intrinsic size.
5108 The other optional parameters are:
5110 "preallocation"
5112 If format is "raw", then this can be either "off" (or "sparse") or
5113 "full" to create a sparse or fully allocated file respectively.
5114 The default is "off".
5115 If format is "qcow2", then this can be "off" (or "sparse"),
5117 "metadata" or "full". Preallocating metadata can be faster when
5118 doing lots of writes, but uses more space. The default is "off".
5119 "compat"
5121 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5122 supported by qemu ≥ 1.1.
5123 "clustersize"
5125 "qcow2" only: Change the qcow2 cluster size. The default is 65536
5126 (bytes) and this setting may be any power of two between 512 and
5127 2097152.
5128 Note that this call does not add the new disk to the handle. You may
5130 need to call "guestfs_add_drive_opts" separately.
5131 This function returns 0 on success or -1 on error.
5133 (Added in 1.25.31)
5135 guestfs_disk_create_va
5137 int
5138 guestfs_disk_create_va (guestfs_h *g,
5139 const char *filename,
5140 const char *format,
5141 int64_t size,
5142 va_list args);
5143 This is the "va_list variant" of "guestfs_disk_create".
5145 See "CALLS WITH OPTIONAL ARGUMENTS".
5147 guestfs_disk_create_argv
5149 int
5150 guestfs_disk_create_argv (guestfs_h *g,
5151 const char *filename,
5152 const char *format,
5153 int64_t size,
5154 const struct guestfs_disk_create_argv *optargs);
5155 This is the "argv variant" of "guestfs_disk_create".
5157 See "CALLS WITH OPTIONAL ARGUMENTS".
5159 guestfs_disk_format
5161 char *
5162 guestfs_disk_format (guestfs_h *g,
5163 const char *filename);
5164 Detect and return the format of the disk image called filename.
5166 filename can also be a host device, etc. If the format of the image
5167 could not be detected, then "unknown" is returned.
5168 Note that detecting the disk format can be insecure under some
5170 circumstances. See "CVE-2010-3851".
5171 See also: "DISK IMAGE FORMATS"
5173 This function returns a string, or NULL on error. The caller must free
5175 the returned string after use.
5176 (Added in 1.19.38)
5178 guestfs_disk_has_backing_file
5180 int
5181 guestfs_disk_has_backing_file (guestfs_h *g,
5182 const char *filename);
5183 Detect and return whether the disk image filename has a backing file.
5185 Note that detecting disk features can be insecure under some
5187 circumstances. See "CVE-2010-3851".
5188 This function returns a C truth value on success or -1 on error.
5190 (Added in 1.19.39)
5192 guestfs_disk_virtual_size
5194 int64_t
5195 guestfs_disk_virtual_size (guestfs_h *g,
5196 const char *filename);
5197 Detect and return the virtual size in bytes of the disk image called
5199 filename.
5200 Note that detecting disk features can be insecure under some
5202 circumstances. See "CVE-2010-3851".
5203 On error this function returns -1.
5205 (Added in 1.19.39)
5207 guestfs_dmesg
5209 char *
5210 guestfs_dmesg (guestfs_h *g);
5211 This returns the kernel messages (dmesg(1) output) from the guest
5213 kernel. This is sometimes useful for extended debugging of problems.
5214 Another way to get the same information is to enable verbose messages
5216 with "guestfs_set_verbose" or by setting the environment variable
5217 "LIBGUESTFS_DEBUG=1" before running the program.
5218 This function returns a string, or NULL on error. The caller must free
5220 the returned string after use.
5221 (Added in 1.0.18)
5223 guestfs_download
5225 int
5226 guestfs_download (guestfs_h *g,
5227 const char *remotefilename,
5228 const char *filename);
5229 Download file remotefilename and save it as filename on the local
5231 machine.
5232 filename can also be a named pipe.
5234 See also "guestfs_upload", "guestfs_cat".
5236 This function returns 0 on success or -1 on error.
5238 This long-running command can generate progress notification messages
5240 so that the caller can display a progress bar or indicator. To receive
5241 these messages, the caller must register a progress event callback.
5242 See "GUESTFS_EVENT_PROGRESS".
5243 (Added in 1.0.2)
5245 guestfs_download_blocks
5247 int
5248 guestfs_download_blocks (guestfs_h *g,
5249 const char *device,
5250 int64_t start,
5251 int64_t stop,
5252 const char *filename,
5253 ...);
5254 You may supply a list of optional arguments to this call. Use zero or
5256 more of the following pairs of parameters, and terminate the list with
5257 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5258 GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5260 Download the data units from start address to stop from the disk
5262 partition (eg. /dev/sda1) and save them as filename on the local
5263 machine.
5264 The use of this API on sparse disk image formats such as QCOW, may
5266 result in large zero-filled files downloaded on the host.
5267 The size of a data unit varies across filesystem implementations. On
5269 NTFS filesystems data units are referred as clusters while on ExtX ones
5270 they are referred as fragments.
5271 If the optional "unallocated" flag is true (default is false), only the
5273 unallocated blocks will be extracted. This is useful to detect hidden
5274 data or to retrieve deleted files which data units have not been
5275 overwritten yet.
5276 This function returns 0 on success or -1 on error.
5278 This long-running command can generate progress notification messages
5280 so that the caller can display a progress bar or indicator. To receive
5281 these messages, the caller must register a progress event callback.
5282 See "GUESTFS_EVENT_PROGRESS".
5283 This function depends on the feature "sleuthkit". See also
5285 "guestfs_feature_available".
5286 (Added in 1.33.45)
5288 guestfs_download_blocks_va
5290 int
5291 guestfs_download_blocks_va (guestfs_h *g,
5292 const char *device,
5293 int64_t start,
5294 int64_t stop,
5295 const char *filename,
5296 va_list args);
5297 This is the "va_list variant" of "guestfs_download_blocks".
5299 See "CALLS WITH OPTIONAL ARGUMENTS".
5301 guestfs_download_blocks_argv
5303 int
5304 guestfs_download_blocks_argv (guestfs_h *g,
5305 const char *device,
5306 int64_t start,
5307 int64_t stop,
5308 const char *filename,
5309 const struct guestfs_download_blocks_argv *optargs);
5310 This is the "argv variant" of "guestfs_download_blocks".
5312 See "CALLS WITH OPTIONAL ARGUMENTS".
5314 guestfs_download_inode
5316 int
5317 guestfs_download_inode (guestfs_h *g,
5318 const char *device,
5319 int64_t inode,
5320 const char *filename);
5321 Download a file given its inode from the disk partition (eg. /dev/sda1)
5323 and save it as filename on the local machine.
5324 It is not required to mount the disk to run this command.
5326 The command is capable of downloading deleted or inaccessible files.
5328 This function returns 0 on success or -1 on error.
5330 This long-running command can generate progress notification messages
5332 so that the caller can display a progress bar or indicator. To receive
5333 these messages, the caller must register a progress event callback.
5334 See "GUESTFS_EVENT_PROGRESS".
5335 This function depends on the feature "sleuthkit". See also
5337 "guestfs_feature_available".
5338 (Added in 1.33.14)
5340 guestfs_download_offset
5342 int
5343 guestfs_download_offset (guestfs_h *g,
5344 const char *remotefilename,
5345 const char *filename,
5346 int64_t offset,
5347 int64_t size);
5348 Download file remotefilename and save it as filename on the local
5350 machine.
5351 remotefilename is read for "size" bytes starting at "offset" (this
5353 region must be within the file or device).
5354 Note that there is no limit on the amount of data that can be
5356 downloaded with this call, unlike with "guestfs_pread", and this call
5357 always reads the full amount unless an error occurs.
5358 See also "guestfs_download", "guestfs_pread".
5360 This function returns 0 on success or -1 on error.
5362 This long-running command can generate progress notification messages
5364 so that the caller can display a progress bar or indicator. To receive
5365 these messages, the caller must register a progress event callback.
5366 See "GUESTFS_EVENT_PROGRESS".
5367 (Added in 1.5.17)
5369 guestfs_drop_caches
5371 int
5372 guestfs_drop_caches (guestfs_h *g,
5373 int whattodrop);
5374 This instructs the guest kernel to drop its page cache, and/or dentries
5376 and inode caches. The parameter "whattodrop" tells the kernel what
5377 precisely to drop, see https://linux-mm.org/Drop_Caches
5378 Setting "whattodrop" to 3 should drop everything.
5380 This automatically calls sync(2) before the operation, so that the
5382 maximum guest memory is freed.
5383 This function returns 0 on success or -1 on error.
5385 (Added in 1.0.18)
5387 guestfs_du
5389 int64_t
5390 guestfs_du (guestfs_h *g,
5391 const char *path);
5392 This command runs the "du -s" command to estimate file space usage for
5394 "path".
5395 "path" can be a file or a directory. If "path" is a directory then the
5397 estimate includes the contents of the directory and all subdirectories
5398 (recursively).
5399 The result is the estimated size in kilobytes (ie. units of 1024
5401 bytes).
5402 On error this function returns -1.
5404 This long-running command can generate progress notification messages
5406 so that the caller can display a progress bar or indicator. To receive
5407 these messages, the caller must register a progress event callback.
5408 See "GUESTFS_EVENT_PROGRESS".
5409 (Added in 1.0.54)
5411 guestfs_e2fsck
5413 int
5414 guestfs_e2fsck (guestfs_h *g,
5415 const char *device,
5416 ...);
5417 You may supply a list of optional arguments to this call. Use zero or
5419 more of the following pairs of parameters, and terminate the list with
5420 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5421 GUESTFS_E2FSCK_CORRECT, int correct,
5423 GUESTFS_E2FSCK_FORCEALL, int forceall,
5424 This runs the ext2/ext3 filesystem checker on "device". It can take
5426 the following optional arguments:
5427 "correct"
5429 Automatically repair the file system. This option will cause e2fsck
5430 to automatically fix any filesystem problems that can be safely
5431 fixed without human intervention.
5432 This option may not be specified at the same time as the "forceall"
5434 option.
5435 "forceall"
5437 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5438 used non-interactively.
5439 This option may not be specified at the same time as the "correct"
5441 option.
5442 This function returns 0 on success or -1 on error.
5444 (Added in 1.15.17)
5446 guestfs_e2fsck_va
5448 int
5449 guestfs_e2fsck_va (guestfs_h *g,
5450 const char *device,
5451 va_list args);
5452 This is the "va_list variant" of "guestfs_e2fsck".
5454 See "CALLS WITH OPTIONAL ARGUMENTS".
5456 guestfs_e2fsck_argv
5458 int
5459 guestfs_e2fsck_argv (guestfs_h *g,
5460 const char *device,
5461 const struct guestfs_e2fsck_argv *optargs);
5462 This is the "argv variant" of "guestfs_e2fsck".
5464 See "CALLS WITH OPTIONAL ARGUMENTS".
5466 guestfs_e2fsck_f
5468 int
5469 guestfs_e2fsck_f (guestfs_h *g,
5470 const char *device);
5471 This function is deprecated. In new code, use the "guestfs_e2fsck"
5473 call instead.
5474 Deprecated functions will not be removed from the API, but the fact
5476 that they are deprecated indicates that there are problems with correct
5477 use of these functions.
5478 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5480 checker on "device", noninteractively (-p), even if the filesystem
5481 appears to be clean (-f).
5482 This function returns 0 on success or -1 on error.
5484 (Added in 1.0.29)
5486 guestfs_echo_daemon
5488 char *
5489 guestfs_echo_daemon (guestfs_h *g,
5490 char *const *words);
5491 This command concatenates the list of "words" passed with single spaces
5493 between them and returns the resulting string.
5494 You can use this command to test the connection through to the daemon.
5496 See also "guestfs_ping_daemon".
5498 This function returns a string, or NULL on error. The caller must free
5500 the returned string after use.
5501 (Added in 1.0.69)
5503 guestfs_egrep
5505 char **
5506 guestfs_egrep (guestfs_h *g,
5507 const char *regex,
5508 const char *path);
5509 This function is deprecated. In new code, use the "guestfs_grep" call
5511 instead.
5512 Deprecated functions will not be removed from the API, but the fact
5514 that they are deprecated indicates that there are problems with correct
5515 use of these functions.
5516 This calls the external egrep(1) program and returns the matching
5518 lines.
5519 This function returns a NULL-terminated array of strings (like
5521 environ(3)), or NULL if there was an error. The caller must free the
5522 strings and the array after use.
5523 Because of the message protocol, there is a transfer limit of somewhere
5525 between 2MB and 4MB. See "PROTOCOL LIMITS".
5526 (Added in 1.0.66)
5528 guestfs_egrepi
5530 char **
5531 guestfs_egrepi (guestfs_h *g,
5532 const char *regex,
5533 const char *path);
5534 This function is deprecated. In new code, use the "guestfs_grep" call
5536 instead.
5537 Deprecated functions will not be removed from the API, but the fact
5539 that they are deprecated indicates that there are problems with correct
5540 use of these functions.
5541 This calls the external "egrep -i" program and returns the matching
5543 lines.
5544 This function returns a NULL-terminated array of strings (like
5546 environ(3)), or NULL if there was an error. The caller must free the
5547 strings and the array after use.
5548 Because of the message protocol, there is a transfer limit of somewhere
5550 between 2MB and 4MB. See "PROTOCOL LIMITS".
5551 (Added in 1.0.66)
5553 guestfs_equal
5555 int
5556 guestfs_equal (guestfs_h *g,
5557 const char *file1,
5558 const char *file2);
5559 This compares the two files file1 and file2 and returns true if their
5561 content is exactly equal, or false otherwise.
5562 The external cmp(1) program is used for the comparison.
5564 This function returns a C truth value on success or -1 on error.
5566 (Added in 1.0.18)
5568 guestfs_exists
5570 int
5571 guestfs_exists (guestfs_h *g,
5572 const char *path);
5573 This returns "true" if and only if there is a file, directory (or
5575 anything) with the given "path" name.
5576 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5578 This function returns a C truth value on success or -1 on error.
5580 (Added in 0.8)
5582 guestfs_extlinux
5584 int
5585 guestfs_extlinux (guestfs_h *g,
5586 const char *directory);
5587 Install the SYSLINUX bootloader on the device mounted at directory.
5589 Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5590 used on an ext2/3/4 or btrfs filesystem.
5591 The directory parameter can be either a mountpoint, or a directory
5593 within the mountpoint.
5594 You also have to mark the partition as "active"
5596 ("guestfs_part_set_bootable") and a Master Boot Record must be
5597 installed (eg. using "guestfs_pwrite_device") on the first sector of
5598 the whole disk. The SYSLINUX package comes with some suitable Master
5599 Boot Records. See the extlinux(1) man page for further information.
5600 Additional configuration can be supplied to SYSLINUX by placing a file
5602 called extlinux.conf on the filesystem under directory. For further
5603 information about the contents of this file, see extlinux(1).
5604 See also "guestfs_syslinux".
5606 This function returns 0 on success or -1 on error.
5608 This function depends on the feature "extlinux". See also
5610 "guestfs_feature_available".
5611 (Added in 1.21.27)
5613 guestfs_f2fs_expand
5615 int
5616 guestfs_f2fs_expand (guestfs_h *g,
5617 const char *device);
5618 This expands a f2fs filesystem to match the size of the underlying
5620 device.
5621 This function returns 0 on success or -1 on error.
5623 This function depends on the feature "f2fs". See also
5625 "guestfs_feature_available".
5626 (Added in 1.39.3)
5628 guestfs_fallocate
5630 int
5631 guestfs_fallocate (guestfs_h *g,
5632 const char *path,
5633 int len);
5634 This function is deprecated. In new code, use the
5636 "guestfs_fallocate64" call instead.
5637 Deprecated functions will not be removed from the API, but the fact
5639 that they are deprecated indicates that there are problems with correct
5640 use of these functions.
5641 This command preallocates a file (containing zero bytes) named "path"
5643 of size "len" bytes. If the file exists already, it is overwritten.
5644 Do not confuse this with the guestfish-specific "alloc" command which
5646 allocates a file in the host and attaches it as a device.
5647 This function returns 0 on success or -1 on error.
5649 (Added in 1.0.66)
5651 guestfs_fallocate64
5653 int
5654 guestfs_fallocate64 (guestfs_h *g,
5655 const char *path,
5656 int64_t len);
5657 This command preallocates a file (containing zero bytes) named "path"
5659 of size "len" bytes. If the file exists already, it is overwritten.
5660 Note that this call allocates disk blocks for the file. To create a
5662 sparse file use "guestfs_truncate_size" instead.
5663 The deprecated call "guestfs_fallocate" does the same, but owing to an
5665 oversight it only allowed 30 bit lengths to be specified, effectively
5666 limiting the maximum size of files created through that call to 1GB.
5667 Do not confuse this with the guestfish-specific "alloc" and "sparse"
5669 commands which create a file in the host and attach it as a device.
5670 This function returns 0 on success or -1 on error.
5672 (Added in 1.3.17)
5674 guestfs_feature_available
5676 int
5677 guestfs_feature_available (guestfs_h *g,
5678 char *const *groups);
5679 This is the same as "guestfs_available", but unlike that call it
5681 returns a simple true/false boolean result, instead of throwing an
5682 exception if a feature is not found. For other documentation see
5683 "guestfs_available".
5684 This function returns a C truth value on success or -1 on error.
5686 (Added in 1.21.26)
5688 guestfs_fgrep
5690 char **
5691 guestfs_fgrep (guestfs_h *g,
5692 const char *pattern,
5693 const char *path);
5694 This function is deprecated. In new code, use the "guestfs_grep" call
5696 instead.
5697 Deprecated functions will not be removed from the API, but the fact
5699 that they are deprecated indicates that there are problems with correct
5700 use of these functions.
5701 This calls the external fgrep(1) program and returns the matching
5703 lines.
5704 This function returns a NULL-terminated array of strings (like
5706 environ(3)), or NULL if there was an error. The caller must free the
5707 strings and the array after use.
5708 Because of the message protocol, there is a transfer limit of somewhere
5710 between 2MB and 4MB. See "PROTOCOL LIMITS".
5711 (Added in 1.0.66)
5713 guestfs_fgrepi
5715 char **
5716 guestfs_fgrepi (guestfs_h *g,
5717 const char *pattern,
5718 const char *path);
5719 This function is deprecated. In new code, use the "guestfs_grep" call
5721 instead.
5722 Deprecated functions will not be removed from the API, but the fact
5724 that they are deprecated indicates that there are problems with correct
5725 use of these functions.
5726 This calls the external "fgrep -i" program and returns the matching
5728 lines.
5729 This function returns a NULL-terminated array of strings (like
5731 environ(3)), or NULL if there was an error. The caller must free the
5732 strings and the array after use.
5733 Because of the message protocol, there is a transfer limit of somewhere
5735 between 2MB and 4MB. See "PROTOCOL LIMITS".
5736 (Added in 1.0.66)
5738 guestfs_file
5740 char *
5741 guestfs_file (guestfs_h *g,
5742 const char *path);
5743 This call uses the standard file(1) command to determine the type or
5745 contents of the file.
5746 This call will also transparently look inside various types of
5748 compressed file.
5749 The filename is not prepended to the output (like the file command -b
5751 option).
5752 The output depends on the output of the underlying file(1) command and
5754 it can change in future in ways beyond our control. In other words,
5755 the output is not guaranteed by the ABI.
5756 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5758 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5759 This function returns a string, or NULL on error. The caller must free
5761 the returned string after use.
5762 (Added in 1.9.1)
5764 guestfs_file_architecture
5766 char *
5767 guestfs_file_architecture (guestfs_h *g,
5768 const char *filename);
5769 This detects the architecture of the binary filename, and returns it if
5771 known.
5772 Currently defined architectures are:
5774 "aarch64"
5776 64 bit ARM.
5777 "arm"
5779 32 bit ARM.
5780 "i386"
5782 This string is returned for all 32 bit i386, i486, i586, i686
5783 binaries irrespective of the precise processor requirements of the
5784 binary.
5785 "ia64"
5787 Intel Itanium.
5788 "ppc"
5790 32 bit Power PC.
5791 "ppc64"
5793 64 bit Power PC (big endian).
5794 "ppc64le"
5796 64 bit Power PC (little endian).
5797 "riscv32"
5799 "riscv64"
5800 "riscv128"
5801 RISC-V 32-, 64- or 128-bit variants.
5802 "s390"
5804 31 bit IBM S/390.
5805 "s390x"
5807 64 bit IBM S/390.
5808 "sparc"
5810 32 bit SPARC.
5811 "sparc64"
5813 64 bit SPARC V9 and above.
5814 "x86_64"
5816 64 bit x86-64.
5817 Libguestfs may return other architecture strings in future.
5819 The function works on at least the following types of files:
5821 • many types of Un*x and Linux binary
5823 • many types of Un*x and Linux shared library
5825 • Windows Win32 and Win64 binaries
5827 • Windows Win32 and Win64 DLLs
5829 Win32 binaries and DLLs return "i386".
5831 Win64 binaries and DLLs return "x86_64".
5833 • Linux kernel modules
5835 • Linux new-style initrd images
5837 • some non-x86 Linux vmlinuz kernels
5839 What it can't do currently:
5841 • static libraries (libfoo.a)
5843 • Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5845 • x86 Linux vmlinuz kernels
5847 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5849 and compressed code, and are horribly hard to unpack. If you want
5850 to find the architecture of a kernel, use the architecture of the
5851 associated initrd or kernel module(s) instead.
5852 This function returns a string, or NULL on error. The caller must free
5854 the returned string after use.
5855 (Added in 1.5.3)
5857 guestfs_filesize
5859 int64_t
5860 guestfs_filesize (guestfs_h *g,
5861 const char *file);
5862 This command returns the size of file in bytes.
5864 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5866 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
5867 devices, use "guestfs_blockdev_getsize64".
5868 On error this function returns -1.
5870 (Added in 1.0.82)
5872 guestfs_filesystem_available
5874 int
5875 guestfs_filesystem_available (guestfs_h *g,
5876 const char *filesystem);
5877 Check whether libguestfs supports the named filesystem. The argument
5879 "filesystem" is a filesystem name, such as "ext3".
5880 You must call "guestfs_launch" before using this command.
5882 This is mainly useful as a negative test. If this returns true, it
5884 doesn't mean that a particular filesystem can be created or mounted,
5885 since filesystems can fail for other reasons such as it being a later
5886 version of the filesystem, or having incompatible features, or lacking
5887 the right mkfs.<fs> tool.
5888 See also "guestfs_available", "guestfs_feature_available",
5890 "AVAILABILITY".
5891 This function returns a C truth value on success or -1 on error.
5893 (Added in 1.19.5)
5895 guestfs_filesystem_walk
5897 struct guestfs_tsk_dirent_list *
5898 guestfs_filesystem_walk (guestfs_h *g,
5899 const char *device);
5900 Walk through the internal structures of a disk partition (eg.
5902 /dev/sda1) in order to return a list of all the files and directories
5903 stored within.
5904 It is not necessary to mount the disk partition to run this command.
5906 All entries in the filesystem are returned. This function can list
5908 deleted or unaccessible files. The entries are not sorted.
5909 The "tsk_dirent" structure contains the following fields.
5911 "tsk_inode"
5913 Filesystem reference number of the node. It might be 0 if the node
5914 has been deleted.
5915 "tsk_type"
5917 Basic file type information. See below for a detailed list of
5918 values.
5919 "tsk_size"
5921 File size in bytes. It might be "-1" if the node has been deleted.
5922 "tsk_name"
5924 The file path relative to its directory.
5925 "tsk_flags"
5927 Bitfield containing extra information regarding the entry. It
5928 contains the logical OR of the following values:
5929 0x0001
5931 If set to 1, the file is allocated and visible within the
5932 filesystem. Otherwise, the file has been deleted. Under
5933 certain circumstances, the function "download_inode" can be
5934 used to recover deleted files.
5935 0x0002
5937 Filesystem such as NTFS and Ext2 or greater, separate the file
5938 name from the metadata structure. The bit is set to 1 when the
5939 file name is in an unallocated state and the metadata structure
5940 is in an allocated one. This generally implies the metadata
5941 has been reallocated to a new file. Therefore, information
5942 such as file type, file size, timestamps, number of links and
5943 symlink target might not correspond with the ones of the
5944 original deleted entry.
5945 0x0004
5947 The bit is set to 1 when the file is compressed using
5948 filesystem native compression support (NTFS). The API is not
5949 able to detect application level compression.
5950 "tsk_atime_sec"
5952 "tsk_atime_nsec"
5953 "tsk_mtime_sec"
5954 "tsk_mtime_nsec"
5955 "tsk_ctime_sec"
5956 "tsk_ctime_nsec"
5957 "tsk_crtime_sec"
5958 "tsk_crtime_nsec"
5959 Respectively, access, modification, last status change and creation
5960 time in Unix format in seconds and nanoseconds.
5961 "tsk_nlink"
5963 Number of file names pointing to this entry.
5964 "tsk_link"
5966 If the entry is a symbolic link, this field will contain the path
5967 to the target file.
5968 The "tsk_type" field will contain one of the following characters:
5970 'b' Block special
5972 'c' Char special
5974 'd' Directory
5976 'f' FIFO (named pipe)
5978 'l' Symbolic link
5980 'r' Regular file
5982 's' Socket
5984 'h' Shadow inode (Solaris)
5986 'w' Whiteout inode (BSD)
5988 'u' Unknown file type
5990 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
5992 there was an error. The caller must call
5993 "guestfs_free_tsk_dirent_list" after use.
5994 This long-running command can generate progress notification messages
5996 so that the caller can display a progress bar or indicator. To receive
5997 these messages, the caller must register a progress event callback.
5998 See "GUESTFS_EVENT_PROGRESS".
5999 This function depends on the feature "libtsk". See also
6001 "guestfs_feature_available".
6002 (Added in 1.33.39)
6004 guestfs_fill
6006 int
6007 guestfs_fill (guestfs_h *g,
6008 int c,
6009 int len,
6010 const char *path);
6011 This command creates a new file called "path". The initial content of
6013 the file is "len" octets of "c", where "c" must be a number in the
6014 range "[0..255]".
6015 To fill a file with zero bytes (sparsely), it is much more efficient to
6017 use "guestfs_truncate_size". To create a file with a pattern of
6018 repeating bytes use "guestfs_fill_pattern".
6019 This function returns 0 on success or -1 on error.
6021 This long-running command can generate progress notification messages
6023 so that the caller can display a progress bar or indicator. To receive
6024 these messages, the caller must register a progress event callback.
6025 See "GUESTFS_EVENT_PROGRESS".
6026 (Added in 1.0.79)
6028 guestfs_fill_dir
6030 int
6031 guestfs_fill_dir (guestfs_h *g,
6032 const char *dir,
6033 int nr);
6034 This function, useful for testing filesystems, creates "nr" empty files
6036 in the directory "dir" with names 00000000 through "nr-1" (ie. each
6037 file name is 8 digits long padded with zeroes).
6038 This function returns 0 on success or -1 on error.
6040 (Added in 1.19.32)
6042 guestfs_fill_pattern
6044 int
6045 guestfs_fill_pattern (guestfs_h *g,
6046 const char *pattern,
6047 int len,
6048 const char *path);
6049 This function is like "guestfs_fill" except that it creates a new file
6051 of length "len" containing the repeating pattern of bytes in "pattern".
6052 The pattern is truncated if necessary to ensure the length of the file
6053 is exactly "len" bytes.
6054 This function returns 0 on success or -1 on error.
6056 This long-running command can generate progress notification messages
6058 so that the caller can display a progress bar or indicator. To receive
6059 these messages, the caller must register a progress event callback.
6060 See "GUESTFS_EVENT_PROGRESS".
6061 (Added in 1.3.12)
6063 guestfs_find
6065 char **
6066 guestfs_find (guestfs_h *g,
6067 const char *directory);
6068 This command lists out all files and directories, recursively, starting
6070 at directory. It is essentially equivalent to running the shell
6071 command "find directory -print" but some post-processing happens on the
6072 output, described below.
6073 This returns a list of strings without any prefix. Thus if the
6075 directory structure was:
6076 /tmp/a
6078 /tmp/b
6079 /tmp/c/d
6080 then the returned list from "guestfs_find" /tmp would be 4 elements:
6082 a
6084 b
6085 c
6086 c/d
6087 If directory is not a directory, then this command returns an error.
6089 The returned list is sorted.
6091 This function returns a NULL-terminated array of strings (like
6093 environ(3)), or NULL if there was an error. The caller must free the
6094 strings and the array after use.
6095 (Added in 1.0.27)
6097 guestfs_find0
6099 int
6100 guestfs_find0 (guestfs_h *g,
6101 const char *directory,
6102 const char *files);
6103 This command lists out all files and directories, recursively, starting
6105 at directory, placing the resulting list in the external file called
6106 files.
6107 This command works the same way as "guestfs_find" with the following
6109 exceptions:
6110 • The resulting list is written to an external file.
6112 • Items (filenames) in the result are separated by "\0" characters.
6114 See find(1) option -print0.
6115 • The result list is not sorted.
6117 This function returns 0 on success or -1 on error.
6119 (Added in 1.0.74)
6121 guestfs_find_inode
6123 struct guestfs_tsk_dirent_list *
6124 guestfs_find_inode (guestfs_h *g,
6125 const char *device,
6126 int64_t inode);
6127 Searches all the entries associated with the given inode.
6129 For each entry, a "tsk_dirent" structure is returned. See
6131 "filesystem_walk" for more information about "tsk_dirent" structures.
6132 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6134 there was an error. The caller must call
6135 "guestfs_free_tsk_dirent_list" after use.
6136 This long-running command can generate progress notification messages
6138 so that the caller can display a progress bar or indicator. To receive
6139 these messages, the caller must register a progress event callback.
6140 See "GUESTFS_EVENT_PROGRESS".
6141 This function depends on the feature "libtsk". See also
6143 "guestfs_feature_available".
6144 (Added in 1.35.6)
6146 guestfs_findfs_label
6148 char *
6149 guestfs_findfs_label (guestfs_h *g,
6150 const char *label);
6151 This command searches the filesystems and returns the one which has the
6153 given label. An error is returned if no such filesystem can be found.
6154 To find the label of a filesystem, use "guestfs_vfs_label".
6156 This function returns a string, or NULL on error. The caller must free
6158 the returned string after use.
6159 (Added in 1.5.3)
6161 guestfs_findfs_uuid
6163 char *
6164 guestfs_findfs_uuid (guestfs_h *g,
6165 const char *uuid);
6166 This command searches the filesystems and returns the one which has the
6168 given UUID. An error is returned if no such filesystem can be found.
6169 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6171 This function returns a string, or NULL on error. The caller must free
6173 the returned string after use.
6174 (Added in 1.5.3)
6176 guestfs_fsck
6178 int
6179 guestfs_fsck (guestfs_h *g,
6180 const char *fstype,
6181 const char *device);
6182 This runs the filesystem checker (fsck) on "device" which should have
6184 filesystem type "fstype".
6185 The returned integer is the status. See fsck(8) for the list of status
6187 codes from "fsck".
6188 Notes:
6190 • Multiple status codes can be summed together.
6192 • A non-zero return code can mean "success", for example if errors
6194 have been corrected on the filesystem.
6195 • Checking or repairing NTFS volumes is not supported (by linux-
6197 ntfs).
6198 This command is entirely equivalent to running "fsck -a -t fstype
6200 device".
6201 On error this function returns -1.
6203 (Added in 1.0.16)
6205 guestfs_fstrim
6207 int
6208 guestfs_fstrim (guestfs_h *g,
6209 const char *mountpoint,
6210 ...);
6211 You may supply a list of optional arguments to this call. Use zero or
6213 more of the following pairs of parameters, and terminate the list with
6214 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6215 GUESTFS_FSTRIM_OFFSET, int64_t offset,
6217 GUESTFS_FSTRIM_LENGTH, int64_t length,
6218 GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6219 Trim the free space in the filesystem mounted on "mountpoint". The
6221 filesystem must be mounted read-write.
6222 The filesystem contents are not affected, but any free space in the
6224 filesystem is "trimmed", that is, given back to the host device, thus
6225 making disk images more sparse, allowing unused space in qcow2 files to
6226 be reused, etc.
6227 This operation requires support in libguestfs, the mounted filesystem,
6229 the host filesystem, qemu and the host kernel. If this support isn't
6230 present it may give an error or even appear to run but do nothing.
6231 In the case where the kernel vfs driver does not support trimming, this
6233 call will fail with errno set to "ENOTSUP". Currently this happens
6234 when trying to trim FAT filesystems.
6235 See also "guestfs_zero_free_space". That is a slightly different
6237 operation that turns free space in the filesystem into zeroes. It is
6238 valid to call "guestfs_fstrim" either instead of, or after calling
6239 "guestfs_zero_free_space".
6240 This function returns 0 on success or -1 on error.
6242 This function depends on the feature "fstrim". See also
6244 "guestfs_feature_available".
6245 (Added in 1.19.6)
6247 guestfs_fstrim_va
6249 int
6250 guestfs_fstrim_va (guestfs_h *g,
6251 const char *mountpoint,
6252 va_list args);
6253 This is the "va_list variant" of "guestfs_fstrim".
6255 See "CALLS WITH OPTIONAL ARGUMENTS".
6257 guestfs_fstrim_argv
6259 int
6260 guestfs_fstrim_argv (guestfs_h *g,
6261 const char *mountpoint,
6262 const struct guestfs_fstrim_argv *optargs);
6263 This is the "argv variant" of "guestfs_fstrim".
6265 See "CALLS WITH OPTIONAL ARGUMENTS".
6267 guestfs_get_append
6269 const char *
6270 guestfs_get_append (guestfs_h *g);
6271 Return the additional kernel options which are added to the libguestfs
6273 appliance kernel command line.
6274 If "NULL" then no options are added.
6276 This function returns a string which may be NULL. There is no way to
6278 return an error from this function. The string is owned by the guest
6279 handle and must not be freed.
6280 (Added in 1.0.26)
6282 guestfs_get_attach_method
6284 char *
6285 guestfs_get_attach_method (guestfs_h *g);
6286 This function is deprecated. In new code, use the
6288 "guestfs_get_backend" call instead.
6289 Deprecated functions will not be removed from the API, but the fact
6291 that they are deprecated indicates that there are problems with correct
6292 use of these functions.
6293 Return the current backend.
6295 See "guestfs_set_backend" and "BACKEND".
6297 This function returns a string, or NULL on error. The caller must free
6299 the returned string after use.
6300 (Added in 1.9.8)
6302 guestfs_get_autosync
6304 int
6305 guestfs_get_autosync (guestfs_h *g);
6306 Get the autosync flag.
6308 This function returns a C truth value on success or -1 on error.
6310 (Added in 0.3)
6312 guestfs_get_backend
6314 char *
6315 guestfs_get_backend (guestfs_h *g);
6316 Return the current backend.
6318 This handle property was previously called the "attach method".
6320 See "guestfs_set_backend" and "BACKEND".
6322 This function returns a string, or NULL on error. The caller must free
6324 the returned string after use.
6325 (Added in 1.21.26)
6327 guestfs_get_backend_setting
6329 char *
6330 guestfs_get_backend_setting (guestfs_h *g,
6331 const char *name);
6332 Find a backend setting string which is either "name" or begins with
6334 "name=". If "name", this returns the string "1". If "name=", this
6335 returns the part after the equals sign (which may be an empty string).
6336 If no such setting is found, this function throws an error. The errno
6338 (see "guestfs_last_errno") will be "ESRCH" in this case.
6339 See "BACKEND", "BACKEND SETTINGS".
6341 This function returns a string, or NULL on error. The caller must free
6343 the returned string after use.
6344 (Added in 1.27.2)
6346 guestfs_get_backend_settings
6348 char **
6349 guestfs_get_backend_settings (guestfs_h *g);
6350 Return the current backend settings.
6352 This call returns all backend settings strings. If you want to find a
6354 single backend setting, see "guestfs_get_backend_setting".
6355 See "BACKEND", "BACKEND SETTINGS".
6357 This function returns a NULL-terminated array of strings (like
6359 environ(3)), or NULL if there was an error. The caller must free the
6360 strings and the array after use.
6361 (Added in 1.25.24)
6363 guestfs_get_cachedir
6365 char *
6366 guestfs_get_cachedir (guestfs_h *g);
6367 Get the directory used by the handle to store the appliance cache.
6369 This function returns a string, or NULL on error. The caller must free
6371 the returned string after use.
6372 (Added in 1.19.58)
6374 guestfs_get_direct
6376 int
6377 guestfs_get_direct (guestfs_h *g);
6378 This function is deprecated. In new code, use the
6380 "guestfs_internal_get_console_socket" call instead.
6381 Deprecated functions will not be removed from the API, but the fact
6383 that they are deprecated indicates that there are problems with correct
6384 use of these functions.
6385 Return the direct appliance mode flag.
6387 This function returns a C truth value on success or -1 on error.
6389 (Added in 1.0.72)
6391 guestfs_get_e2attrs
6393 char *
6394 guestfs_get_e2attrs (guestfs_h *g,
6395 const char *file);
6396 This returns the file attributes associated with file.
6398 The attributes are a set of bits associated with each inode which
6400 affect the behaviour of the file. The attributes are returned as a
6401 string of letters (described below). The string may be empty,
6402 indicating that no file attributes are set for this file.
6403 These attributes are only present when the file is located on an
6405 ext2/3/4 filesystem. Using this call on other filesystem types will
6406 result in an error.
6407 The characters (file attributes) in the returned string are currently:
6409 'A' When the file is accessed, its atime is not modified.
6411 'a' The file is append-only.
6413 'c' The file is compressed on-disk.
6415 'D' (Directories only.) Changes to this directory are written
6417 synchronously to disk.
6418 'd' The file is not a candidate for backup (see dump(8)).
6420 'E' The file has compression errors.
6422 'e' The file is using extents.
6424 'h' The file is storing its blocks in units of the filesystem blocksize
6426 instead of sectors.
6427 'I' (Directories only.) The directory is using hashed trees.
6429 'i' The file is immutable. It cannot be modified, deleted or renamed.
6431 No link can be created to this file.
6432 'j' The file is data-journaled.
6434 's' When the file is deleted, all its blocks will be zeroed.
6436 'S' Changes to this file are written synchronously to disk.
6438 'T' (Directories only.) This is a hint to the block allocator that
6440 subdirectories contained in this directory should be spread across
6441 blocks. If not present, the block allocator will try to group
6442 subdirectories together.
6443 't' For a file, this disables tail-merging. (Not used by upstream
6445 implementations of ext2.)
6446 'u' When the file is deleted, its blocks will be saved, allowing the
6448 file to be undeleted.
6449 'X' The raw contents of the compressed file may be accessed.
6451 'Z' The compressed file is dirty.
6453 More file attributes may be added to this list later. Not all file
6455 attributes may be set for all kinds of files. For detailed
6456 information, consult the chattr(1) man page.
6457 See also "guestfs_set_e2attrs".
6459 Don't confuse these attributes with extended attributes (see
6461 "guestfs_getxattr").
6462 This function returns a string, or NULL on error. The caller must free
6464 the returned string after use.
6465 (Added in 1.17.31)
6467 guestfs_get_e2generation
6469 int64_t
6470 guestfs_get_e2generation (guestfs_h *g,
6471 const char *file);
6472 This returns the ext2 file generation of a file. The generation (which
6474 used to be called the "version") is a number associated with an inode.
6475 This is most commonly used by NFS servers.
6476 The generation is only present when the file is located on an ext2/3/4
6478 filesystem. Using this call on other filesystem types will result in
6479 an error.
6480 See "guestfs_set_e2generation".
6482 On error this function returns -1.
6484 (Added in 1.17.31)
6486 guestfs_get_e2label
6488 char *
6489 guestfs_get_e2label (guestfs_h *g,
6490 const char *device);
6491 This function is deprecated. In new code, use the "guestfs_vfs_label"
6493 call instead.
6494 Deprecated functions will not be removed from the API, but the fact
6496 that they are deprecated indicates that there are problems with correct
6497 use of these functions.
6498 This returns the ext2/3/4 filesystem label of the filesystem on
6500 "device".
6501 This function returns a string, or NULL on error. The caller must free
6503 the returned string after use.
6504 (Added in 1.0.15)
6506 guestfs_get_e2uuid
6508 char *
6509 guestfs_get_e2uuid (guestfs_h *g,
6510 const char *device);
6511 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
6513 call instead.
6514 Deprecated functions will not be removed from the API, but the fact
6516 that they are deprecated indicates that there are problems with correct
6517 use of these functions.
6518 This returns the ext2/3/4 filesystem UUID of the filesystem on
6520 "device".
6521 This function returns a string, or NULL on error. The caller must free
6523 the returned string after use.
6524 (Added in 1.0.15)
6526 guestfs_get_hv
6528 char *
6529 guestfs_get_hv (guestfs_h *g);
6530 Return the current hypervisor binary.
6532 This is always non-NULL. If it wasn't set already, then this will
6534 return the default qemu binary name.
6535 This function returns a string, or NULL on error. The caller must free
6537 the returned string after use.
6538 (Added in 1.23.17)
6540 guestfs_get_identifier
6542 const char *
6543 guestfs_get_identifier (guestfs_h *g);
6544 Get the handle identifier. See "guestfs_set_identifier".
6546 This function returns a string, or NULL on error. The string is owned
6548 by the guest handle and must not be freed.
6549 (Added in 1.31.14)
6551 guestfs_get_libvirt_requested_credential_challenge
6553 char *
6554 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6555 int index);
6556 Get the challenge (provided by libvirt) for the "index"'th requested
6558 credential. If libvirt did not provide a challenge, this returns the
6559 empty string "".
6560 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6562 This function returns a string, or NULL on error. The caller must free
6564 the returned string after use.
6565 (Added in 1.19.52)
6567 guestfs_get_libvirt_requested_credential_defresult
6569 char *
6570 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6571 int index);
6572 Get the default result (provided by libvirt) for the "index"'th
6574 requested credential. If libvirt did not provide a default result,
6575 this returns the empty string "".
6576 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6578 This function returns a string, or NULL on error. The caller must free
6580 the returned string after use.
6581 (Added in 1.19.52)
6583 guestfs_get_libvirt_requested_credential_prompt
6585 char *
6586 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6587 int index);
6588 Get the prompt (provided by libvirt) for the "index"'th requested
6590 credential. If libvirt did not provide a prompt, this returns the
6591 empty string "".
6592 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6594 This function returns a string, or NULL on error. The caller must free
6596 the returned string after use.
6597 (Added in 1.19.52)
6599 guestfs_get_libvirt_requested_credentials
6601 char **
6602 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6603 This should only be called during the event callback for events of type
6605 "GUESTFS_EVENT_LIBVIRT_AUTH".
6606 Return the list of credentials requested by libvirt. Possible values
6608 are a subset of the strings provided when you called
6609 "guestfs_set_libvirt_supported_credentials".
6610 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6612 This function returns a NULL-terminated array of strings (like
6614 environ(3)), or NULL if there was an error. The caller must free the
6615 strings and the array after use.
6616 (Added in 1.19.52)
6618 guestfs_get_memsize
6620 int
6621 guestfs_get_memsize (guestfs_h *g);
6622 This gets the memory size in megabytes allocated to the hypervisor.
6624 If "guestfs_set_memsize" was not called on this handle, and if
6626 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6627 default value for memsize.
6628 For more information on the architecture of libguestfs, see guestfs(3).
6630 On error this function returns -1.
6632 (Added in 1.0.55)
6634 guestfs_get_network
6636 int
6637 guestfs_get_network (guestfs_h *g);
6638 This returns the enable network flag.
6640 This function returns a C truth value on success or -1 on error.
6642 (Added in 1.5.4)
6644 guestfs_get_path
6646 const char *
6647 guestfs_get_path (guestfs_h *g);
6648 Return the current search path.
6650 This is always non-NULL. If it wasn't set already, then this will
6652 return the default path.
6653 This function returns a string, or NULL on error. The string is owned
6655 by the guest handle and must not be freed.
6656 (Added in 0.3)
6658 guestfs_get_pgroup
6660 int
6661 guestfs_get_pgroup (guestfs_h *g);
6662 This returns the process group flag.
6664 This function returns a C truth value on success or -1 on error.
6666 (Added in 1.11.18)
6668 guestfs_get_pid
6670 int
6671 guestfs_get_pid (guestfs_h *g);
6672 Return the process ID of the hypervisor. If there is no hypervisor
6674 running, then this will return an error.
6675 This is an internal call used for debugging and testing.
6677 On error this function returns -1.
6679 (Added in 1.0.56)
6681 guestfs_get_program
6683 const char *
6684 guestfs_get_program (guestfs_h *g);
6685 Get the program name. See "guestfs_set_program".
6687 This function returns a string, or NULL on error. The string is owned
6689 by the guest handle and must not be freed.
6690 (Added in 1.21.29)
6692 guestfs_get_qemu
6694 const char *
6695 guestfs_get_qemu (guestfs_h *g);
6696 This function is deprecated. In new code, use the "guestfs_get_hv"
6698 call instead.
6699 Deprecated functions will not be removed from the API, but the fact
6701 that they are deprecated indicates that there are problems with correct
6702 use of these functions.
6703 Return the current hypervisor binary (usually qemu).
6705 This is always non-NULL. If it wasn't set already, then this will
6707 return the default qemu binary name.
6708 This function returns a string, or NULL on error. The string is owned
6710 by the guest handle and must not be freed.
6711 (Added in 1.0.6)
6713 guestfs_get_recovery_proc
6715 int
6716 guestfs_get_recovery_proc (guestfs_h *g);
6717 Return the recovery process enabled flag.
6719 This function returns a C truth value on success or -1 on error.
6721 (Added in 1.0.77)
6723 guestfs_get_selinux
6725 int
6726 guestfs_get_selinux (guestfs_h *g);
6727 This function is deprecated. In new code, use the
6729 "guestfs_selinux_relabel" call instead.
6730 Deprecated functions will not be removed from the API, but the fact
6732 that they are deprecated indicates that there are problems with correct
6733 use of these functions.
6734 This returns the current setting of the selinux flag which is passed to
6736 the appliance at boot time. See "guestfs_set_selinux".
6737 For more information on the architecture of libguestfs, see guestfs(3).
6739 This function returns a C truth value on success or -1 on error.
6741 (Added in 1.0.67)
6743 guestfs_get_smp
6745 int
6746 guestfs_get_smp (guestfs_h *g);
6747 This returns the number of virtual CPUs assigned to the appliance.
6749 On error this function returns -1.
6751 (Added in 1.13.15)
6753 guestfs_get_sockdir
6755 char *
6756 guestfs_get_sockdir (guestfs_h *g);
6757 Get the directory used by the handle to store temporary socket 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.
6763 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6765 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6766 the default.
6767 This function returns a string, or NULL on error. The caller must free
6769 the returned string after use.
6770 (Added in 1.33.8)
6772 guestfs_get_state
6774 int
6775 guestfs_get_state (guestfs_h *g);
6776 This returns the current state as an opaque integer. This is only
6778 useful for printing debug and internal error messages.
6779 For more information on states, see guestfs(3).
6781 On error this function returns -1.
6783 (Added in 1.0.2)
6785 guestfs_get_tmpdir
6787 char *
6788 guestfs_get_tmpdir (guestfs_h *g);
6789 Get the directory used by the handle to store temporary files.
6791 This function returns a string, or NULL on error. The caller must free
6793 the returned string after use.
6794 (Added in 1.19.58)
6796 guestfs_get_trace
6798 int
6799 guestfs_get_trace (guestfs_h *g);
6800 Return the command trace flag.
6802 This function returns a C truth value on success or -1 on error.
6804 (Added in 1.0.69)
6806 guestfs_get_umask
6808 int
6809 guestfs_get_umask (guestfs_h *g);
6810 Return the current umask. By default the umask is 022 unless it has
6812 been set by calling "guestfs_umask".
6813 On error this function returns -1.
6815 (Added in 1.3.4)
6817 guestfs_get_verbose
6819 int
6820 guestfs_get_verbose (guestfs_h *g);
6821 This returns the verbose messages flag.
6823 This function returns a C truth value on success or -1 on error.
6825 (Added in 0.3)
6827 guestfs_getcon
6829 char *
6830 guestfs_getcon (guestfs_h *g);
6831 This function is deprecated. In new code, use the
6833 "guestfs_selinux_relabel" call instead.
6834 Deprecated functions will not be removed from the API, but the fact
6836 that they are deprecated indicates that there are problems with correct
6837 use of these functions.
6838 This gets the SELinux security context of the daemon.
6840 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6842 This function returns a string, or NULL on error. The caller must free
6844 the returned string after use.
6845 This function depends on the feature "selinux". See also
6847 "guestfs_feature_available".
6848 (Added in 1.0.67)
6850 guestfs_getxattr
6852 char *
6853 guestfs_getxattr (guestfs_h *g,
6854 const char *path,
6855 const char *name,
6856 size_t *size_r);
6857 Get a single extended attribute from file "path" named "name". This
6859 call follows symlinks. If you want to lookup an extended attribute for
6860 the symlink itself, use "guestfs_lgetxattr".
6861 Normally it is better to get all extended attributes from a file in one
6863 go by calling "guestfs_getxattrs". However some Linux filesystem
6864 implementations are buggy and do not provide a way to list out
6865 attributes. For these filesystems (notably ntfs-3g) you have to know
6866 the names of the extended attributes you want in advance and call this
6867 function.
6868 Extended attribute values are blobs of binary data. If there is no
6870 extended attribute named "name", this returns an error.
6871 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6873 This function returns a buffer, or NULL on error. The size of the
6875 returned buffer is written to *size_r. The caller must free the
6876 returned buffer after use.
6877 This function depends on the feature "linuxxattrs". See also
6879 "guestfs_feature_available".
6880 (Added in 1.7.24)
6882 guestfs_getxattrs
6884 struct guestfs_xattr_list *
6885 guestfs_getxattrs (guestfs_h *g,
6886 const char *path);
6887 This call lists the extended attributes of the file or directory
6889 "path".
6890 At the system call level, this is a combination of the listxattr(2) and
6892 getxattr(2) calls.
6893 See also: "guestfs_lgetxattrs", attr(5).
6895 This function returns a "struct guestfs_xattr_list *", or NULL if there
6897 was an error. The caller must call "guestfs_free_xattr_list" after
6898 use.
6899 This function depends on the feature "linuxxattrs". See also
6901 "guestfs_feature_available".
6902 (Added in 1.0.59)
6904 guestfs_glob_expand
6906 char **
6907 guestfs_glob_expand (guestfs_h *g,
6908 const char *pattern);
6909 This function is provided for backwards compatibility with earlier
6911 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
6912 with no optional arguments.
6913 (Added in 1.0.50)
6915 guestfs_glob_expand_opts
6917 char **
6918 guestfs_glob_expand_opts (guestfs_h *g,
6919 const char *pattern,
6920 ...);
6921 You may supply a list of optional arguments to this call. Use zero or
6923 more of the following pairs of parameters, and terminate the list with
6924 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6925 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
6927 This command searches for all the pathnames matching "pattern"
6929 according to the wildcard expansion rules used by the shell.
6930 If no paths match, then this returns an empty list (note: not an
6932 error).
6933 It is just a wrapper around the C glob(3) function with flags
6935 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
6936 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
6938 and it defaults to true. It can be explicitly set as off to return no
6939 trailing slashes in filenames of directories.
6940 Notice that there is no equivalent command for expanding a device name
6942 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
6943 etc functions instead.
6944 This function returns a NULL-terminated array of strings (like
6946 environ(3)), or NULL if there was an error. The caller must free the
6947 strings and the array after use.
6948 (Added in 1.0.50)
6950 guestfs_glob_expand_opts_va
6952 char **
6953 guestfs_glob_expand_opts_va (guestfs_h *g,
6954 const char *pattern,
6955 va_list args);
6956 This is the "va_list variant" of "guestfs_glob_expand_opts".
6958 See "CALLS WITH OPTIONAL ARGUMENTS".
6960 guestfs_glob_expand_opts_argv
6962 char **
6963 guestfs_glob_expand_opts_argv (guestfs_h *g,
6964 const char *pattern,
6965 const struct guestfs_glob_expand_opts_argv *optargs);
6966 This is the "argv variant" of "guestfs_glob_expand_opts".
6968 See "CALLS WITH OPTIONAL ARGUMENTS".
6970 guestfs_grep
6972 char **
6973 guestfs_grep (guestfs_h *g,
6974 const char *regex,
6975 const char *path);
6976 This function is provided for backwards compatibility with earlier
6978 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
6979 optional arguments.
6980 (Added in 1.0.66)
6982 guestfs_grep_opts
6984 char **
6985 guestfs_grep_opts (guestfs_h *g,
6986 const char *regex,
6987 const char *path,
6988 ...);
6989 You may supply a list of optional arguments to this call. Use zero or
6991 more of the following pairs of parameters, and terminate the list with
6992 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6993 GUESTFS_GREP_OPTS_EXTENDED, int extended,
6995 GUESTFS_GREP_OPTS_FIXED, int fixed,
6996 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
6997 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
6998 This calls the external grep(1) program and returns the matching lines.
7000 The optional flags are:
7002 "extended"
7004 Use extended regular expressions. This is the same as using the -E
7005 flag.
7006 "fixed"
7008 Match fixed (don't use regular expressions). This is the same as
7009 using the -F flag.
7010 "insensitive"
7012 Match case-insensitive. This is the same as using the -i flag.
7013 "compressed"
7015 Use zgrep(1) instead of grep(1). This allows the input to be
7016 compress- or gzip-compressed.
7017 This function returns a NULL-terminated array of strings (like
7019 environ(3)), or NULL if there was an error. The caller must free the
7020 strings and the array after use.
7021 Because of the message protocol, there is a transfer limit of somewhere
7023 between 2MB and 4MB. See "PROTOCOL LIMITS".
7024 (Added in 1.0.66)
7026 guestfs_grep_opts_va
7028 char **
7029 guestfs_grep_opts_va (guestfs_h *g,
7030 const char *regex,
7031 const char *path,
7032 va_list args);
7033 This is the "va_list variant" of "guestfs_grep_opts".
7035 See "CALLS WITH OPTIONAL ARGUMENTS".
7037 guestfs_grep_opts_argv
7039 char **
7040 guestfs_grep_opts_argv (guestfs_h *g,
7041 const char *regex,
7042 const char *path,
7043 const struct guestfs_grep_opts_argv *optargs);
7044 This is the "argv variant" of "guestfs_grep_opts".
7046 See "CALLS WITH OPTIONAL ARGUMENTS".
7048 guestfs_grepi
7050 char **
7051 guestfs_grepi (guestfs_h *g,
7052 const char *regex,
7053 const char *path);
7054 This function is deprecated. In new code, use the "guestfs_grep" call
7056 instead.
7057 Deprecated functions will not be removed from the API, but the fact
7059 that they are deprecated indicates that there are problems with correct
7060 use of these functions.
7061 This calls the external "grep -i" program and returns the matching
7063 lines.
7064 This function returns a NULL-terminated array of strings (like
7066 environ(3)), or NULL if there was an error. The caller must free the
7067 strings and the array after use.
7068 Because of the message protocol, there is a transfer limit of somewhere
7070 between 2MB and 4MB. See "PROTOCOL LIMITS".
7071 (Added in 1.0.66)
7073 guestfs_grub_install
7075 int
7076 guestfs_grub_install (guestfs_h *g,
7077 const char *root,
7078 const char *device);
7079 This command installs GRUB 1 (the Grand Unified Bootloader) on
7081 "device", with the root directory being "root".
7082 Notes:
7084 • There is currently no way in the API to install grub2, which is
7086 used by most modern Linux guests. It is possible to run the grub2
7087 command from the guest, although see the caveats in "RUNNING
7088 COMMANDS".
7089 • This uses grub-install(8) from the host. Unfortunately grub is not
7091 always compatible with itself, so this only works in rather narrow
7092 circumstances. Careful testing with each guest version is
7093 advisable.
7094 • If grub-install reports the error "No suitable drive was found in
7096 the generated device map." it may be that you need to create a
7097 /boot/grub/device.map file first that contains the mapping between
7098 grub device names and Linux device names. It is usually sufficient
7099 to create a file containing:
7100 (hd0) /dev/vda
7102 replacing /dev/vda with the name of the installation device.
7104 This function returns 0 on success or -1 on error.
7106 This function depends on the feature "grub". See also
7108 "guestfs_feature_available".
7109 (Added in 1.0.17)
7111 guestfs_head
7113 char **
7114 guestfs_head (guestfs_h *g,
7115 const char *path);
7116 This command returns up to the first 10 lines of a file as a list of
7118 strings.
7119 This function returns a NULL-terminated array of strings (like
7121 environ(3)), or NULL if there was an error. The caller must free the
7122 strings and the array after use.
7123 Because of the message protocol, there is a transfer limit of somewhere
7125 between 2MB and 4MB. See "PROTOCOL LIMITS".
7126 (Added in 1.0.54)
7128 guestfs_head_n
7130 char **
7131 guestfs_head_n (guestfs_h *g,
7132 int nrlines,
7133 const char *path);
7134 If the parameter "nrlines" is a positive number, this returns the first
7136 "nrlines" lines of the file "path".
7137 If the parameter "nrlines" is a negative number, this returns lines
7139 from the file "path", excluding the last "nrlines" lines.
7140 If the parameter "nrlines" is zero, this returns an empty list.
7142 This function returns a NULL-terminated array of strings (like
7144 environ(3)), or NULL if there was an error. The caller must free the
7145 strings and the array after use.
7146 Because of the message protocol, there is a transfer limit of somewhere
7148 between 2MB and 4MB. See "PROTOCOL LIMITS".
7149 (Added in 1.0.54)
7151 guestfs_hexdump
7153 char *
7154 guestfs_hexdump (guestfs_h *g,
7155 const char *path);
7156 This runs "hexdump -C" on the given "path". The result is the human-
7158 readable, canonical hex dump of the file.
7159 This function returns a string, or NULL on error. The caller must free
7161 the returned string after use.
7162 Because of the message protocol, there is a transfer limit of somewhere
7164 between 2MB and 4MB. See "PROTOCOL LIMITS".
7165 (Added in 1.0.22)
7167 guestfs_hivex_close
7169 int
7170 guestfs_hivex_close (guestfs_h *g);
7171 Close the current hivex handle.
7173 This is a wrapper around the hivex(3) call of the same name.
7175 This function returns 0 on success or -1 on error.
7177 This function depends on the feature "hivex". See also
7179 "guestfs_feature_available".
7180 (Added in 1.19.35)
7182 guestfs_hivex_commit
7184 int
7185 guestfs_hivex_commit (guestfs_h *g,
7186 const char *filename);
7187 Commit (write) changes to the hive.
7189 If the optional filename parameter is null, then the changes are
7191 written back to the same hive that was opened. If this is not null
7192 then they are written to the alternate filename given and the original
7193 hive is left untouched.
7194 This is a wrapper around the hivex(3) call of the same name.
7196 This function returns 0 on success or -1 on error.
7198 This function depends on the feature "hivex". See also
7200 "guestfs_feature_available".
7201 (Added in 1.19.35)
7203 guestfs_hivex_node_add_child
7205 int64_t
7206 guestfs_hivex_node_add_child (guestfs_h *g,
7207 int64_t parent,
7208 const char *name);
7209 Add a child node to "parent" named "name".
7211 This is a wrapper around the hivex(3) call of the same name.
7213 On error this function returns -1.
7215 This function depends on the feature "hivex". See also
7217 "guestfs_feature_available".
7218 (Added in 1.19.35)
7220 guestfs_hivex_node_children
7222 struct guestfs_hivex_node_list *
7223 guestfs_hivex_node_children (guestfs_h *g,
7224 int64_t nodeh);
7225 Return the list of nodes which are subkeys of "nodeh".
7227 This is a wrapper around the hivex(3) call of the same name.
7229 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7231 there was an error. The caller must call
7232 "guestfs_free_hivex_node_list" after use.
7233 This function depends on the feature "hivex". See also
7235 "guestfs_feature_available".
7236 (Added in 1.19.35)
7238 guestfs_hivex_node_delete_child
7240 int
7241 guestfs_hivex_node_delete_child (guestfs_h *g,
7242 int64_t nodeh);
7243 Delete "nodeh", recursively if necessary.
7245 This is a wrapper around the hivex(3) call of the same name.
7247 This function returns 0 on success or -1 on error.
7249 This function depends on the feature "hivex". See also
7251 "guestfs_feature_available".
7252 (Added in 1.19.35)
7254 guestfs_hivex_node_get_child
7256 int64_t
7257 guestfs_hivex_node_get_child (guestfs_h *g,
7258 int64_t nodeh,
7259 const char *name);
7260 Return the child of "nodeh" with the name "name", if it exists. This
7262 can return 0 meaning the name was not found.
7263 This is a wrapper around the hivex(3) call of the same name.
7265 On error this function returns -1.
7267 This function depends on the feature "hivex". See also
7269 "guestfs_feature_available".
7270 (Added in 1.19.35)
7272 guestfs_hivex_node_get_value
7274 int64_t
7275 guestfs_hivex_node_get_value (guestfs_h *g,
7276 int64_t nodeh,
7277 const char *key);
7278 Return the value attached to "nodeh" which has the name "key", if it
7280 exists. This can return 0 meaning the key was not found.
7281 This is a wrapper around the hivex(3) call of the same name.
7283 On error this function returns -1.
7285 This function depends on the feature "hivex". See also
7287 "guestfs_feature_available".
7288 (Added in 1.19.35)
7290 guestfs_hivex_node_name
7292 char *
7293 guestfs_hivex_node_name (guestfs_h *g,
7294 int64_t nodeh);
7295 Return the name of "nodeh".
7297 This is a wrapper around the hivex(3) call of the same name.
7299 This function returns a string, or NULL on error. The caller must free
7301 the returned string after use.
7302 This function depends on the feature "hivex". See also
7304 "guestfs_feature_available".
7305 (Added in 1.19.35)
7307 guestfs_hivex_node_parent
7309 int64_t
7310 guestfs_hivex_node_parent (guestfs_h *g,
7311 int64_t nodeh);
7312 Return the parent node of "nodeh".
7314 This is a wrapper around the hivex(3) call of the same name.
7316 On error this function returns -1.
7318 This function depends on the feature "hivex". See also
7320 "guestfs_feature_available".
7321 (Added in 1.19.35)
7323 guestfs_hivex_node_set_value
7325 int
7326 guestfs_hivex_node_set_value (guestfs_h *g,
7327 int64_t nodeh,
7328 const char *key,
7329 int64_t t,
7330 const char *val,
7331 size_t val_size);
7332 Set or replace a single value under the node "nodeh". The "key" is the
7334 name, "t" is the type, and "val" is the data.
7335 This is a wrapper around the hivex(3) call of the same name.
7337 This function returns 0 on success or -1 on error.
7339 This function depends on the feature "hivex". See also
7341 "guestfs_feature_available".
7342 (Added in 1.19.35)
7344 guestfs_hivex_node_values
7346 struct guestfs_hivex_value_list *
7347 guestfs_hivex_node_values (guestfs_h *g,
7348 int64_t nodeh);
7349 Return the array of (key, datatype, data) tuples attached to "nodeh".
7351 This is a wrapper around the hivex(3) call of the same name.
7353 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7355 there was an error. The caller must call
7356 "guestfs_free_hivex_value_list" after use.
7357 This function depends on the feature "hivex". See also
7359 "guestfs_feature_available".
7360 (Added in 1.19.35)
7362 guestfs_hivex_open
7364 int
7365 guestfs_hivex_open (guestfs_h *g,
7366 const char *filename,
7367 ...);
7368 You may supply a list of optional arguments to this call. Use zero or
7370 more of the following pairs of parameters, and terminate the list with
7371 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7372 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7374 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7375 GUESTFS_HIVEX_OPEN_WRITE, int write,
7376 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7377 Open the Windows Registry hive file named filename. If there was any
7379 previous hivex handle associated with this guestfs session, then it is
7380 closed.
7381 This is a wrapper around the hivex(3) call of the same name.
7383 This function returns 0 on success or -1 on error.
7385 This function depends on the feature "hivex". See also
7387 "guestfs_feature_available".
7388 (Added in 1.19.35)
7390 guestfs_hivex_open_va
7392 int
7393 guestfs_hivex_open_va (guestfs_h *g,
7394 const char *filename,
7395 va_list args);
7396 This is the "va_list variant" of "guestfs_hivex_open".
7398 See "CALLS WITH OPTIONAL ARGUMENTS".
7400 guestfs_hivex_open_argv
7402 int
7403 guestfs_hivex_open_argv (guestfs_h *g,
7404 const char *filename,
7405 const struct guestfs_hivex_open_argv *optargs);
7406 This is the "argv variant" of "guestfs_hivex_open".
7408 See "CALLS WITH OPTIONAL ARGUMENTS".
7410 guestfs_hivex_root
7412 int64_t
7413 guestfs_hivex_root (guestfs_h *g);
7414 Return the root node of the hive.
7416 This is a wrapper around the hivex(3) call of the same name.
7418 On error this function returns -1.
7420 This function depends on the feature "hivex". See also
7422 "guestfs_feature_available".
7423 (Added in 1.19.35)
7425 guestfs_hivex_value_key
7427 char *
7428 guestfs_hivex_value_key (guestfs_h *g,
7429 int64_t valueh);
7430 Return the key (name) field of a (key, datatype, data) tuple.
7432 This is a wrapper around the hivex(3) call of the same name.
7434 This function returns a string, or NULL on error. The caller must free
7436 the returned string after use.
7437 This function depends on the feature "hivex". See also
7439 "guestfs_feature_available".
7440 (Added in 1.19.35)
7442 guestfs_hivex_value_string
7444 char *
7445 guestfs_hivex_value_string (guestfs_h *g,
7446 int64_t valueh);
7447 This calls "guestfs_hivex_value_value" (which returns the data field
7449 from a hivex value tuple). It then assumes that the field is a
7450 UTF-16LE string and converts the result to UTF-8 (or if this is not
7451 possible, it returns an error).
7452 This is useful for reading strings out of the Windows registry.
7454 However it is not foolproof because the registry is not strongly-typed
7455 and fields can contain arbitrary or unexpected data.
7456 This function returns a string, or NULL on error. The caller must free
7458 the returned string after use.
7459 This function depends on the feature "hivex". See also
7461 "guestfs_feature_available".
7462 (Added in 1.37.22)
7464 guestfs_hivex_value_type
7466 int64_t
7467 guestfs_hivex_value_type (guestfs_h *g,
7468 int64_t valueh);
7469 Return the data type field from a (key, datatype, data) tuple.
7471 This is a wrapper around the hivex(3) call of the same name.
7473 On error this function returns -1.
7475 This function depends on the feature "hivex". See also
7477 "guestfs_feature_available".
7478 (Added in 1.19.35)
7480 guestfs_hivex_value_utf8
7482 char *
7483 guestfs_hivex_value_utf8 (guestfs_h *g,
7484 int64_t valueh);
7485 This function is deprecated. In new code, use the
7487 "guestfs_hivex_value_string" call instead.
7488 Deprecated functions will not be removed from the API, but the fact
7490 that they are deprecated indicates that there are problems with correct
7491 use of these functions.
7492 This calls "guestfs_hivex_value_value" (which returns the data field
7494 from a hivex value tuple). It then assumes that the field is a
7495 UTF-16LE string and converts the result to UTF-8 (or if this is not
7496 possible, it returns an error).
7497 This is useful for reading strings out of the Windows registry.
7499 However it is not foolproof because the registry is not strongly-typed
7500 and fields can contain arbitrary or unexpected data.
7501 This function returns a string, or NULL on error. The caller must free
7503 the returned string after use.
7504 This function depends on the feature "hivex". See also
7506 "guestfs_feature_available".
7507 (Added in 1.19.35)
7509 guestfs_hivex_value_value
7511 char *
7512 guestfs_hivex_value_value (guestfs_h *g,
7513 int64_t valueh,
7514 size_t *size_r);
7515 Return the data field of a (key, datatype, data) tuple.
7517 This is a wrapper around the hivex(3) call of the same name.
7519 See also: "guestfs_hivex_value_utf8".
7521 This function returns a buffer, or NULL on error. The size of the
7523 returned buffer is written to *size_r. The caller must free the
7524 returned buffer after use.
7525 This function depends on the feature "hivex". See also
7527 "guestfs_feature_available".
7528 (Added in 1.19.35)
7530 guestfs_initrd_cat
7532 char *
7533 guestfs_initrd_cat (guestfs_h *g,
7534 const char *initrdpath,
7535 const char *filename,
7536 size_t *size_r);
7537 This command unpacks the file filename from the initrd file called
7539 initrdpath. The filename must be given without the initial /
7540 character.
7541 For example, in guestfish you could use the following command to
7543 examine the boot script (usually called /init) contained in a Linux
7544 initrd or initramfs image:
7545 initrd-cat /boot/initrd-<version>.img init
7547 See also "guestfs_initrd_list".
7549 This function returns a buffer, or NULL on error. The size of the
7551 returned buffer is written to *size_r. The caller must free the
7552 returned buffer after use.
7553 Because of the message protocol, there is a transfer limit of somewhere
7555 between 2MB and 4MB. See "PROTOCOL LIMITS".
7556 (Added in 1.0.84)
7558 guestfs_initrd_list
7560 char **
7561 guestfs_initrd_list (guestfs_h *g,
7562 const char *path);
7563 This command lists out files contained in an initrd.
7565 The files are listed without any initial / character. The files are
7567 listed in the order they appear (not necessarily alphabetical).
7568 Directory names are listed as separate items.
7569 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7571 as initrd. We only support the newer initramfs format (compressed cpio
7572 files).
7573 This function returns a NULL-terminated array of strings (like
7575 environ(3)), or NULL if there was an error. The caller must free the
7576 strings and the array after use.
7577 (Added in 1.0.54)
7579 guestfs_inotify_add_watch
7581 int64_t
7582 guestfs_inotify_add_watch (guestfs_h *g,
7583 const char *path,
7584 int mask);
7585 Watch "path" for the events listed in "mask".
7587 Note that if "path" is a directory then events within that directory
7589 are watched, but this does not happen recursively (in subdirectories).
7590 Note for non-C or non-Linux callers: the inotify events are defined by
7592 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7593 On error this function returns -1.
7595 This function depends on the feature "inotify". See also
7597 "guestfs_feature_available".
7598 (Added in 1.0.66)
7600 guestfs_inotify_close
7602 int
7603 guestfs_inotify_close (guestfs_h *g);
7604 This closes the inotify handle which was previously opened by
7606 inotify_init. It removes all watches, throws away any pending events,
7607 and deallocates all resources.
7608 This function returns 0 on success or -1 on error.
7610 This function depends on the feature "inotify". See also
7612 "guestfs_feature_available".
7613 (Added in 1.0.66)
7615 guestfs_inotify_files
7617 char **
7618 guestfs_inotify_files (guestfs_h *g);
7619 This function is a helpful wrapper around "guestfs_inotify_read" which
7621 just returns a list of pathnames of objects that were touched. The
7622 returned pathnames are sorted and deduplicated.
7623 This function returns a NULL-terminated array of strings (like
7625 environ(3)), or NULL if there was an error. The caller must free the
7626 strings and the array after use.
7627 This function depends on the feature "inotify". See also
7629 "guestfs_feature_available".
7630 (Added in 1.0.66)
7632 guestfs_inotify_init
7634 int
7635 guestfs_inotify_init (guestfs_h *g,
7636 int maxevents);
7637 This command creates a new inotify handle. The inotify subsystem can
7639 be used to notify events which happen to objects in the guest
7640 filesystem.
7641 "maxevents" is the maximum number of events which will be queued up
7643 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7644 this is passed as 0, then the kernel (or previously set) default is
7645 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7646 limit, the kernel throws away events, but records the fact that it
7647 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7648 structure list (see "guestfs_inotify_read").
7649 Before any events are generated, you have to add some watches to the
7651 internal watch list. See: "guestfs_inotify_add_watch" and
7652 "guestfs_inotify_rm_watch".
7653 Queued up events should be read periodically by calling
7655 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7656 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7657 events out often enough then you risk the internal queue overflowing.
7658 The handle should be closed after use by calling
7660 "guestfs_inotify_close". This also removes any watches automatically.
7661 See also inotify(7) for an overview of the inotify interface as exposed
7663 by the Linux kernel, which is roughly what we expose via libguestfs.
7664 Note that there is one global inotify handle per libguestfs instance.
7665 This function returns 0 on success or -1 on error.
7667 This function depends on the feature "inotify". See also
7669 "guestfs_feature_available".
7670 (Added in 1.0.66)
7672 guestfs_inotify_read
7674 struct guestfs_inotify_event_list *
7675 guestfs_inotify_read (guestfs_h *g);
7676 Return the complete queue of events that have happened since the
7678 previous read call.
7679 If no events have happened, this returns an empty list.
7681 Note: In order to make sure that all events have been read, you must
7683 call this function repeatedly until it returns an empty list. The
7684 reason is that the call will read events up to the maximum appliance-
7685 to-host message size and leave remaining events in the queue.
7686 This function returns a "struct guestfs_inotify_event_list *", or NULL
7688 if there was an error. The caller must call
7689 "guestfs_free_inotify_event_list" after use.
7690 This function depends on the feature "inotify". See also
7692 "guestfs_feature_available".
7693 (Added in 1.0.66)
7695 guestfs_inotify_rm_watch
7697 int
7698 guestfs_inotify_rm_watch (guestfs_h *g,
7699 int wd);
7700 Remove a previously defined inotify watch. See
7702 "guestfs_inotify_add_watch".
7703 This function returns 0 on success or -1 on error.
7705 This function depends on the feature "inotify". See also
7707 "guestfs_feature_available".
7708 (Added in 1.0.66)
7710 guestfs_inspect_get_arch
7712 char *
7713 guestfs_inspect_get_arch (guestfs_h *g,
7714 const char *root);
7715 This returns the architecture of the inspected operating system. The
7717 possible return values are listed under "guestfs_file_architecture".
7718 If the architecture could not be determined, then the string "unknown"
7720 is returned.
7721 Please read "INSPECTION" for more details.
7723 This function returns a string, or NULL on error. The caller must free
7725 the returned string after use.
7726 (Added in 1.5.3)
7728 guestfs_inspect_get_build_id
7730 char *
7731 guestfs_inspect_get_build_id (guestfs_h *g,
7732 const char *root);
7733 This returns the build ID of the system, or the string "unknown" if the
7735 system does not have a build ID.
7736 For Windows, this gets the build number. Although it is returned as a
7738 string, it is (so far) always a number. See
7739 https://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions for
7740 some possible values.
7741 For Linux, this returns the "BUILD_ID" string from /etc/os-release,
7743 although this is not often used.
7744 Please read "INSPECTION" for more details.
7746 This function returns a string, or NULL on error. The caller must free
7748 the returned string after use.
7749 (Added in 1.49.8)
7751 guestfs_inspect_get_distro
7753 char *
7754 guestfs_inspect_get_distro (guestfs_h *g,
7755 const char *root);
7756 This returns the distro (distribution) of the inspected operating
7758 system.
7759 Currently defined distros are:
7761 "alpinelinux"
7763 Alpine Linux.
7764 "altlinux"
7766 ALT Linux.
7767 "archlinux"
7769 Arch Linux.
7770 "buildroot"
7772 Buildroot-derived distro, but not one we specifically recognize.
7773 "centos"
7775 CentOS.
7776 "cirros"
7778 Cirros.
7779 "coreos"
7781 CoreOS.
7782 "debian"
7784 Debian.
7785 "fedora"
7787 Fedora.
7788 "freebsd"
7790 FreeBSD.
7791 "freedos"
7793 FreeDOS.
7794 "frugalware"
7796 Frugalware.
7797 "gentoo"
7799 Gentoo.
7800 "kalilinux"
7802 Kali Linux.
7803 "kylin"
7805 Kylin.
7806 "linuxmint"
7808 Linux Mint.
7809 "mageia"
7811 Mageia.
7812 "mandriva"
7814 Mandriva.
7815 "meego"
7817 MeeGo.
7818 "msdos"
7820 Microsoft DOS.
7821 "neokylin"
7823 NeoKylin.
7824 "netbsd"
7826 NetBSD.
7827 "openbsd"
7829 OpenBSD.
7830 "openmandriva"
7832 OpenMandriva Lx.
7833 "opensuse"
7835 OpenSUSE.
7836 "oraclelinux"
7838 Oracle Linux.
7839 "pardus"
7841 Pardus.
7842 "pldlinux"
7844 PLD Linux.
7845 "redhat-based"
7847 Some Red Hat-derived distro.
7848 "rhel"
7850 Red Hat Enterprise Linux.
7851 "rocky"
7853 Rocky Linux.
7854 "scientificlinux"
7856 Scientific Linux.
7857 "slackware"
7859 Slackware.
7860 "sles"
7862 SuSE Linux Enterprise Server or Desktop.
7863 "suse-based"
7865 Some openSuSE-derived distro.
7866 "ttylinux"
7868 ttylinux.
7869 "ubuntu"
7871 Ubuntu.
7872 "unknown"
7874 The distro could not be determined.
7875 "voidlinux"
7877 Void Linux.
7878 "windows"
7880 Windows does not have distributions. This string is returned if
7881 the OS type is Windows.
7882 Future versions of libguestfs may return other strings here. The
7884 caller should be prepared to handle any string.
7885 Please read "INSPECTION" for more details.
7887 This function returns a string, or NULL on error. The caller must free
7889 the returned string after use.
7890 (Added in 1.5.3)
7892 guestfs_inspect_get_drive_mappings
7894 char **
7895 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7896 const char *root);
7897 This call is useful for Windows which uses a primitive system of
7899 assigning drive letters (like C:\) to partitions. This inspection API
7900 examines the Windows Registry to find out how disks/partitions are
7901 mapped to drive letters, and returns a hash table as in the example
7902 below:
7903 C => /dev/vda2
7905 E => /dev/vdb1
7906 F => /dev/vdc1
7907 Note that keys are drive letters. For Windows, the key is case
7909 insensitive and just contains the drive letter, without the customary
7910 colon separator character.
7911 In future we may support other operating systems that also used drive
7913 letters, but the keys for those might not be case insensitive and might
7914 be longer than 1 character. For example in OS-9, hard drives were
7915 named "h0", "h1" etc.
7916 For Windows guests, currently only hard drive mappings are returned.
7918 Removable disks (eg. DVD-ROMs) are ignored.
7919 For guests that do not use drive mappings, or if the drive mappings
7921 could not be determined, this returns an empty hash table.
7922 Please read "INSPECTION" for more details. See also
7924 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7925 This function returns a NULL-terminated array of strings, or NULL if
7927 there was an error. The array of strings will always have length
7928 "2n+1", where "n" keys and values alternate, followed by the trailing
7929 NULL entry. The caller must free the strings and the array after use.
7930 (Added in 1.9.17)
7932 guestfs_inspect_get_filesystems
7934 char **
7935 guestfs_inspect_get_filesystems (guestfs_h *g,
7936 const char *root);
7937 This returns a list of all the filesystems that we think are associated
7939 with this operating system. This includes the root filesystem, other
7940 ordinary filesystems, and non-mounted devices like swap partitions.
7941 In the case of a multi-boot virtual machine, it is possible for a
7943 filesystem to be shared between operating systems.
7944 Please read "INSPECTION" for more details. See also
7946 "guestfs_inspect_get_mountpoints".
7947 This function returns a NULL-terminated array of strings (like
7949 environ(3)), or NULL if there was an error. The caller must free the
7950 strings and the array after use.
7951 (Added in 1.5.3)
7953 guestfs_inspect_get_format
7955 char *
7956 guestfs_inspect_get_format (guestfs_h *g,
7957 const char *root);
7958 This function is deprecated. There is no replacement. Consult the API
7960 documentation in guestfs(3) for further information.
7961 Deprecated functions will not be removed from the API, but the fact
7963 that they are deprecated indicates that there are problems with correct
7964 use of these functions.
7965 Before libguestfs 1.38, there was some unreliable support for detecting
7967 installer CDs. This API would return:
7968 "installed"
7970 This is an installed operating system.
7971 "installer"
7973 The disk image being inspected is not an installed operating
7974 system, but a bootable install disk, live CD, or similar.
7975 "unknown"
7977 The format of this disk image is not known.
7978 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
7980 directly to detect installer CDs.
7981 Please read "INSPECTION" for more details.
7983 This function returns a string, or NULL on error. The caller must free
7985 the returned string after use.
7986 (Added in 1.9.4)
7988 guestfs_inspect_get_hostname
7990 char *
7991 guestfs_inspect_get_hostname (guestfs_h *g,
7992 const char *root);
7993 This function returns the hostname of the operating system as found by
7995 inspection of the guest’s configuration files.
7996 If the hostname could not be determined, then the string "unknown" is
7998 returned.
7999 Please read "INSPECTION" for more details.
8001 This function returns a string, or NULL on error. The caller must free
8003 the returned string after use.
8004 (Added in 1.7.9)
8006 guestfs_inspect_get_icon
8008 char *
8009 guestfs_inspect_get_icon (guestfs_h *g,
8010 const char *root,
8011 size_t *size_r,
8012 ...);
8013 You may supply a list of optional arguments to this call. Use zero or
8015 more of the following pairs of parameters, and terminate the list with
8016 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8017 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
8019 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
8020 This function returns an icon corresponding to the inspected operating
8022 system. The icon is returned as a buffer containing a PNG image (re-
8023 encoded to PNG if necessary).
8024 If it was not possible to get an icon this function returns a zero-
8026 length (non-NULL) buffer. Callers must check for this case.
8027 Libguestfs will start by looking for a file called /etc/favicon.png or
8029 C:\etc\favicon.png and if it has the correct format, the contents of
8030 this file will be returned. You can disable favicons by passing the
8031 optional "favicon" boolean as false (default is true).
8032 If finding the favicon fails, then we look in other places in the guest
8034 for a suitable icon.
8035 If the optional "highquality" boolean is true then only high quality
8037 icons are returned, which means only icons of high resolution with an
8038 alpha channel. The default (false) is to return any icon we can, even
8039 if it is of substandard quality.
8040 Notes:
8042 • Unlike most other inspection API calls, the guest’s disks must be
8044 mounted up before you call this, since it needs to read information
8045 from the guest filesystem during the call.
8046 • Security: The icon data comes from the untrusted guest, and should
8048 be treated with caution. PNG files have been known to contain
8049 exploits. Ensure that libpng (or other relevant libraries) are
8050 fully up to date before trying to process or display the icon.
8051 • The PNG image returned can be any size. It might not be square.
8053 Libguestfs tries to return the largest, highest quality icon
8054 available. The application must scale the icon to the required
8055 size.
8056 • Extracting icons from Windows guests requires the external
8058 wrestool(1) program from the "icoutils" package, and several
8059 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
8060 package. These must be installed separately.
8061 • Operating system icons are usually trademarks. Seek legal advice
8063 before using trademarks in applications.
8064 This function returns a buffer, or NULL on error. The size of the
8066 returned buffer is written to *size_r. The caller must free the
8067 returned buffer after use.
8068 (Added in 1.11.12)
8070 guestfs_inspect_get_icon_va
8072 char *
8073 guestfs_inspect_get_icon_va (guestfs_h *g,
8074 const char *root,
8075 size_t *size_r,
8076 va_list args);
8077 This is the "va_list variant" of "guestfs_inspect_get_icon".
8079 See "CALLS WITH OPTIONAL ARGUMENTS".
8081 guestfs_inspect_get_icon_argv
8083 char *
8084 guestfs_inspect_get_icon_argv (guestfs_h *g,
8085 const char *root,
8086 size_t *size_r,
8087 const struct guestfs_inspect_get_icon_argv *optargs);
8088 This is the "argv variant" of "guestfs_inspect_get_icon".
8090 See "CALLS WITH OPTIONAL ARGUMENTS".
8092 guestfs_inspect_get_major_version
8094 int
8095 guestfs_inspect_get_major_version (guestfs_h *g,
8096 const char *root);
8097 This returns the major version number of the inspected operating
8099 system.
8100 Windows uses a consistent versioning scheme which is not reflected in
8102 the popular public names used by the operating system. Notably the
8103 operating system known as "Windows 7" is really version 6.1 (ie. major
8104 = 6, minor = 1). You can find out the real versions corresponding to
8105 releases of Windows by consulting Wikipedia or MSDN.
8106 If the version could not be determined, then 0 is returned.
8108 Please read "INSPECTION" for more details.
8110 On error this function returns -1.
8112 (Added in 1.5.3)
8114 guestfs_inspect_get_minor_version
8116 int
8117 guestfs_inspect_get_minor_version (guestfs_h *g,
8118 const char *root);
8119 This returns the minor version number of the inspected operating
8121 system.
8122 If the version could not be determined, then 0 is returned.
8124 Please read "INSPECTION" for more details. See also
8126 "guestfs_inspect_get_major_version".
8127 On error this function returns -1.
8129 (Added in 1.5.3)
8131 guestfs_inspect_get_mountpoints
8133 char **
8134 guestfs_inspect_get_mountpoints (guestfs_h *g,
8135 const char *root);
8136 This returns a hash of where we think the filesystems associated with
8138 this operating system should be mounted. Callers should note that this
8139 is at best an educated guess made by reading configuration files such
8140 as /etc/fstab. In particular note that this may return filesystems
8141 which are non-existent or not mountable and callers should be prepared
8142 to handle or ignore failures if they try to mount them.
8143 Each element in the returned hashtable has a key which is the path of
8145 the mountpoint (eg. /boot) and a value which is the filesystem that
8146 would be mounted there (eg. /dev/sda1).
8147 Non-mounted devices such as swap devices are not returned in this list.
8149 For operating systems like Windows which still use drive letters, this
8151 call will only return an entry for the first drive "mounted on" /. For
8152 information about the mapping of drive letters to partitions, see
8153 "guestfs_inspect_get_drive_mappings".
8154 Please read "INSPECTION" for more details. See also
8156 "guestfs_inspect_get_filesystems".
8157 This function returns a NULL-terminated array of strings, or NULL if
8159 there was an error. The array of strings will always have length
8160 "2n+1", where "n" keys and values alternate, followed by the trailing
8161 NULL entry. The caller must free the strings and the array after use.
8162 (Added in 1.5.3)
8164 guestfs_inspect_get_osinfo
8166 char *
8167 guestfs_inspect_get_osinfo (guestfs_h *g,
8168 const char *root);
8169 This function returns a possible short ID for libosinfo corresponding
8171 to the guest.
8172 Note: The returned ID is only a guess by libguestfs, and nothing
8174 ensures that it actually exists in osinfo-db.
8175 If no ID could not be determined, then the string "unknown" is
8177 returned.
8178 This function returns a string, or NULL on error. The caller must free
8180 the returned string after use.
8181 (Added in 1.39.1)
8183 guestfs_inspect_get_package_format
8185 char *
8186 guestfs_inspect_get_package_format (guestfs_h *g,
8187 const char *root);
8188 This function and "guestfs_inspect_get_package_management" return the
8190 package format and package management tool used by the inspected
8191 operating system. For example for Fedora these functions would return
8192 "rpm" (package format), and "yum" or "dnf" (package management).
8193 This returns the string "unknown" if we could not determine the package
8195 format or if the operating system does not have a real packaging system
8196 (eg. Windows).
8197 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8199 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
8200 other strings.
8201 Please read "INSPECTION" for more details.
8203 This function returns a string, or NULL on error. The caller must free
8205 the returned string after use.
8206 (Added in 1.7.5)
8208 guestfs_inspect_get_package_management
8210 char *
8211 guestfs_inspect_get_package_management (guestfs_h *g,
8212 const char *root);
8213 "guestfs_inspect_get_package_format" and this function return the
8215 package format and package management tool used by the inspected
8216 operating system. For example for Fedora these functions would return
8217 "rpm" (package format), and "yum" or "dnf" (package management).
8218 This returns the string "unknown" if we could not determine the package
8220 management tool or if the operating system does not have a real
8221 packaging system (eg. Windows).
8222 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8224 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8225 "apk", "xbps". Future versions of libguestfs may return other strings.
8226 Please read "INSPECTION" for more details.
8228 This function returns a string, or NULL on error. The caller must free
8230 the returned string after use.
8231 (Added in 1.7.5)
8233 guestfs_inspect_get_product_name
8235 char *
8236 guestfs_inspect_get_product_name (guestfs_h *g,
8237 const char *root);
8238 This returns the product name of the inspected operating system. The
8240 product name is generally some freeform string which can be displayed
8241 to the user, but should not be parsed by programs.
8242 If the product name could not be determined, then the string "unknown"
8244 is returned.
8245 Please read "INSPECTION" for more details.
8247 This function returns a string, or NULL on error. The caller must free
8249 the returned string after use.
8250 (Added in 1.5.3)
8252 guestfs_inspect_get_product_variant
8254 char *
8255 guestfs_inspect_get_product_variant (guestfs_h *g,
8256 const char *root);
8257 This returns the product variant of the inspected operating system.
8259 For Windows guests, this returns the contents of the Registry key
8261 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8262 which is usually a string such as "Client" or "Server" (other values
8263 are possible). This can be used to distinguish consumer and enterprise
8264 versions of Windows that have the same version number (for example,
8265 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8266 is "Client" and the latter is "Server").
8267 For enterprise Linux guests, in future we intend this to return the
8269 product variant such as "Desktop", "Server" and so on. But this is not
8270 implemented at present.
8271 If the product variant could not be determined, then the string
8273 "unknown" is returned.
8274 Please read "INSPECTION" for more details. See also
8276 "guestfs_inspect_get_product_name",
8277 "guestfs_inspect_get_major_version".
8278 This function returns a string, or NULL on error. The caller must free
8280 the returned string after use.
8281 (Added in 1.9.13)
8283 guestfs_inspect_get_roots
8285 char **
8286 guestfs_inspect_get_roots (guestfs_h *g);
8287 This function is a convenient way to get the list of root devices, as
8289 returned from a previous call to "guestfs_inspect_os", but without
8290 redoing the whole inspection process.
8291 This returns an empty list if either no root devices were found or the
8293 caller has not called "guestfs_inspect_os".
8294 Please read "INSPECTION" for more details.
8296 This function returns a NULL-terminated array of strings (like
8298 environ(3)), or NULL if there was an error. The caller must free the
8299 strings and the array after use.
8300 (Added in 1.7.3)
8302 guestfs_inspect_get_type
8304 char *
8305 guestfs_inspect_get_type (guestfs_h *g,
8306 const char *root);
8307 This returns the type of the inspected operating system. Currently
8309 defined types are:
8310 "linux"
8312 Any Linux-based operating system.
8313 "windows"
8315 Any Microsoft Windows operating system.
8316 "freebsd"
8318 FreeBSD.
8319 "netbsd"
8321 NetBSD.
8322 "openbsd"
8324 OpenBSD.
8325 "hurd"
8327 GNU/Hurd.
8328 "dos"
8330 MS-DOS, FreeDOS and others.
8331 "minix"
8333 MINIX.
8334 "unknown"
8336 The operating system type could not be determined.
8337 Future versions of libguestfs may return other strings here. The
8339 caller should be prepared to handle any string.
8340 Please read "INSPECTION" for more details.
8342 This function returns a string, or NULL on error. The caller must free
8344 the returned string after use.
8345 (Added in 1.5.3)
8347 guestfs_inspect_get_windows_current_control_set
8349 char *
8350 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8351 const char *root);
8352 This returns the Windows CurrentControlSet of the inspected guest. The
8354 CurrentControlSet is a registry key name such as "ControlSet001".
8355 This call assumes that the guest is Windows and that the Registry could
8357 be examined by inspection. If this is not the case then an error is
8358 returned.
8359 Please read "INSPECTION" for more details.
8361 This function returns a string, or NULL on error. The caller must free
8363 the returned string after use.
8364 (Added in 1.9.17)
8366 guestfs_inspect_get_windows_software_hive
8368 char *
8369 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8370 const char *root);
8371 This returns the path to the hive (binary Windows Registry file)
8373 corresponding to HKLM\SOFTWARE.
8374 This call assumes that the guest is Windows and that the guest has a
8376 software hive file with the right name. If this is not the case then
8377 an error is returned. This call does not check that the hive is a
8378 valid Windows Registry hive.
8379 You can use "guestfs_hivex_open" to read or write to the hive.
8381 Please read "INSPECTION" for more details.
8383 This function returns a string, or NULL on error. The caller must free
8385 the returned string after use.
8386 (Added in 1.35.26)
8388 guestfs_inspect_get_windows_system_hive
8390 char *
8391 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8392 const char *root);
8393 This returns the path to the hive (binary Windows Registry file)
8395 corresponding to HKLM\SYSTEM.
8396 This call assumes that the guest is Windows and that the guest has a
8398 system hive file with the right name. If this is not the case then an
8399 error is returned. This call does not check that the hive is a valid
8400 Windows Registry hive.
8401 You can use "guestfs_hivex_open" to read or write to the hive.
8403 Please read "INSPECTION" for more details.
8405 This function returns a string, or NULL on error. The caller must free
8407 the returned string after use.
8408 (Added in 1.35.26)
8410 guestfs_inspect_get_windows_systemroot
8412 char *
8413 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8414 const char *root);
8415 This returns the Windows systemroot of the inspected guest. The
8417 systemroot is a directory path such as /WINDOWS.
8418 This call assumes that the guest is Windows and that the systemroot
8420 could be determined by inspection. If this is not the case then an
8421 error is returned.
8422 Please read "INSPECTION" for more details.
8424 This function returns a string, or NULL on error. The caller must free
8426 the returned string after use.
8427 (Added in 1.5.25)
8429 guestfs_inspect_is_live
8431 int
8432 guestfs_inspect_is_live (guestfs_h *g,
8433 const char *root);
8434 This function is deprecated. There is no replacement. Consult the API
8436 documentation in guestfs(3) for further information.
8437 Deprecated functions will not be removed from the API, but the fact
8439 that they are deprecated indicates that there are problems with correct
8440 use of these functions.
8441 This is deprecated and always returns "false".
8443 Please read "INSPECTION" for more details.
8445 This function returns a C truth value on success or -1 on error.
8447 (Added in 1.9.4)
8449 guestfs_inspect_is_multipart
8451 int
8452 guestfs_inspect_is_multipart (guestfs_h *g,
8453 const char *root);
8454 This function is deprecated. There is no replacement. Consult the API
8456 documentation in guestfs(3) for further information.
8457 Deprecated functions will not be removed from the API, but the fact
8459 that they are deprecated indicates that there are problems with correct
8460 use of these functions.
8461 This is deprecated and always returns "false".
8463 Please read "INSPECTION" for more details.
8465 This function returns a C truth value on success or -1 on error.
8467 (Added in 1.9.4)
8469 guestfs_inspect_is_netinst
8471 int
8472 guestfs_inspect_is_netinst (guestfs_h *g,
8473 const char *root);
8474 This function is deprecated. There is no replacement. Consult the API
8476 documentation in guestfs(3) for further information.
8477 Deprecated functions will not be removed from the API, but the fact
8479 that they are deprecated indicates that there are problems with correct
8480 use of these functions.
8481 This is deprecated and always returns "false".
8483 Please read "INSPECTION" for more details.
8485 This function returns a C truth value on success or -1 on error.
8487 (Added in 1.9.4)
8489 guestfs_inspect_list_applications
8491 struct guestfs_application_list *
8492 guestfs_inspect_list_applications (guestfs_h *g,
8493 const char *root);
8494 This function is deprecated. In new code, use the
8496 "guestfs_inspect_list_applications2" call instead.
8497 Deprecated functions will not be removed from the API, but the fact
8499 that they are deprecated indicates that there are problems with correct
8500 use of these functions.
8501 Return the list of applications installed in the operating system.
8503 Note: This call works differently from other parts of the inspection
8505 API. You have to call "guestfs_inspect_os", then
8506 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8507 calling this. Listing applications is a significantly more difficult
8508 operation which requires access to the full filesystem. Also note that
8509 unlike the other "guestfs_inspect_get_*" calls which are just returning
8510 data cached in the libguestfs handle, this call actually reads parts of
8511 the mounted filesystems during the call.
8512 This returns an empty list if the inspection code was not able to
8514 determine the list of applications.
8515 The application structure contains the following fields:
8517 "app_name"
8519 The name of the application. For Linux guests, this is the package
8520 name.
8521 "app_display_name"
8523 The display name of the application, sometimes localized to the
8524 install language of the guest operating system.
8525 If unavailable this is returned as an empty string "". Callers
8527 needing to display something can use "app_name" instead.
8528 "app_epoch"
8530 For package managers which use epochs, this contains the epoch of
8531 the package (an integer). If unavailable, this is returned as 0.
8532 "app_version"
8534 The version string of the application or package. If unavailable
8535 this is returned as an empty string "".
8536 "app_release"
8538 The release string of the application or package, for package
8539 managers that use this. If unavailable this is returned as an
8540 empty string "".
8541 "app_install_path"
8543 The installation path of the application (on operating systems such
8544 as Windows which use installation paths). This path is in the
8545 format used by the guest operating system, it is not a libguestfs
8546 path.
8547 If unavailable this is returned as an empty string "".
8549 "app_trans_path"
8551 The install path translated into a libguestfs path. If unavailable
8552 this is returned as an empty string "".
8553 "app_publisher"
8555 The name of the publisher of the application, for package managers
8556 that use this. If unavailable this is returned as an empty string
8557 "".
8558 "app_url"
8560 The URL (eg. upstream URL) of the application. If unavailable this
8561 is returned as an empty string "".
8562 "app_source_package"
8564 For packaging systems which support this, the name of the source
8565 package. If unavailable this is returned as an empty string "".
8566 "app_summary"
8568 A short (usually one line) description of the application or
8569 package. If unavailable this is returned as an empty string "".
8570 "app_description"
8572 A longer description of the application or package. If unavailable
8573 this is returned as an empty string "".
8574 Please read "INSPECTION" for more details.
8576 This function returns a "struct guestfs_application_list *", or NULL if
8578 there was an error. The caller must call
8579 "guestfs_free_application_list" after use.
8580 (Added in 1.7.8)
8582 guestfs_inspect_list_applications2
8584 struct guestfs_application2_list *
8585 guestfs_inspect_list_applications2 (guestfs_h *g,
8586 const char *root);
8587 Return the list of applications installed in the operating system.
8589 Note: This call works differently from other parts of the inspection
8591 API. You have to call "guestfs_inspect_os", then
8592 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8593 calling this. Listing applications is a significantly more difficult
8594 operation which requires access to the full filesystem. Also note that
8595 unlike the other "guestfs_inspect_get_*" calls which are just returning
8596 data cached in the libguestfs handle, this call actually reads parts of
8597 the mounted filesystems during the call.
8598 This returns an empty list if the inspection code was not able to
8600 determine the list of applications.
8601 The application structure contains the following fields:
8603 "app2_name"
8605 The name of the application. For Linux guests, this is the package
8606 name.
8607 "app2_display_name"
8609 The display name of the application, sometimes localized to the
8610 install language of the guest operating system.
8611 If unavailable this is returned as an empty string "". Callers
8613 needing to display something can use "app2_name" instead.
8614 "app2_epoch"
8616 For package managers which use epochs, this contains the epoch of
8617 the package (an integer). If unavailable, this is returned as 0.
8618 "app2_version"
8620 The version string of the application or package. If unavailable
8621 this is returned as an empty string "".
8622 "app2_release"
8624 The release string of the application or package, for package
8625 managers that use this. If unavailable this is returned as an
8626 empty string "".
8627 "app2_arch"
8629 The architecture string of the application or package, for package
8630 managers that use this. If unavailable this is returned as an
8631 empty string "".
8632 "app2_install_path"
8634 The installation path of the application (on operating systems such
8635 as Windows which use installation paths). This path is in the
8636 format used by the guest operating system, it is not a libguestfs
8637 path.
8638 If unavailable this is returned as an empty string "".
8640 "app2_trans_path"
8642 The install path translated into a libguestfs path. If unavailable
8643 this is returned as an empty string "".
8644 "app2_publisher"
8646 The name of the publisher of the application, for package managers
8647 that use this. If unavailable this is returned as an empty string
8648 "".
8649 "app2_url"
8651 The URL (eg. upstream URL) of the application. If unavailable this
8652 is returned as an empty string "".
8653 "app2_source_package"
8655 For packaging systems which support this, the name of the source
8656 package. If unavailable this is returned as an empty string "".
8657 "app2_summary"
8659 A short (usually one line) description of the application or
8660 package. If unavailable this is returned as an empty string "".
8661 "app2_description"
8663 A longer description of the application or package. If unavailable
8664 this is returned as an empty string "".
8665 Please read "INSPECTION" for more details.
8667 This function returns a "struct guestfs_application2_list *", or NULL
8669 if there was an error. The caller must call
8670 "guestfs_free_application2_list" after use.
8671 (Added in 1.19.56)
8673 guestfs_inspect_os
8675 char **
8676 guestfs_inspect_os (guestfs_h *g);
8677 This function uses other libguestfs functions and certain heuristics to
8679 inspect the disk(s) (usually disks belonging to a virtual machine),
8680 looking for operating systems.
8681 The list returned is empty if no operating systems were found.
8683 If one operating system was found, then this returns a list with a
8685 single element, which is the name of the root filesystem of this
8686 operating system. It is also possible for this function to return a
8687 list containing more than one element, indicating a dual-boot or multi-
8688 boot virtual machine, with each element being the root filesystem of
8689 one of the operating systems.
8690 You can pass the root string(s) returned to other
8692 "guestfs_inspect_get_*" functions in order to query further information
8693 about each operating system, such as the name and version.
8694 This function uses other libguestfs features such as "guestfs_mount_ro"
8696 and "guestfs_umount_all" in order to mount and unmount filesystems and
8697 look at the contents. This should be called with no disks currently
8698 mounted. The function may also use Augeas, so any existing Augeas
8699 handle will be closed.
8700 This function cannot decrypt encrypted disks. The caller must do that
8702 first (supplying the necessary keys) if the disk is encrypted.
8703 Please read "INSPECTION" for more details.
8705 See also "guestfs_list_filesystems".
8707 This function returns a NULL-terminated array of strings (like
8709 environ(3)), or NULL if there was an error. The caller must free the
8710 strings and the array after use.
8711 (Added in 1.5.3)
8713 guestfs_is_blockdev
8715 int
8716 guestfs_is_blockdev (guestfs_h *g,
8717 const char *path);
8718 This function is provided for backwards compatibility with earlier
8720 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8721 with no optional arguments.
8722 (Added in 1.5.10)
8724 guestfs_is_blockdev_opts
8726 int
8727 guestfs_is_blockdev_opts (guestfs_h *g,
8728 const char *path,
8729 ...);
8730 You may supply a list of optional arguments to this call. Use zero or
8732 more of the following pairs of parameters, and terminate the list with
8733 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8734 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8736 This returns "true" if and only if there is a block device with the
8738 given "path" name.
8739 If the optional flag "followsymlinks" is true, then a symlink (or chain
8741 of symlinks) that ends with a block device also causes the function to
8742 return true.
8743 This call only looks at files within the guest filesystem. Libguestfs
8745 partitions and block devices (eg. /dev/sda) cannot be used as the
8746 "path" parameter of this call.
8747 See also "guestfs_stat".
8749 This function returns a C truth value on success or -1 on error.
8751 (Added in 1.5.10)
8753 guestfs_is_blockdev_opts_va
8755 int
8756 guestfs_is_blockdev_opts_va (guestfs_h *g,
8757 const char *path,
8758 va_list args);
8759 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8761 See "CALLS WITH OPTIONAL ARGUMENTS".
8763 guestfs_is_blockdev_opts_argv
8765 int
8766 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8767 const char *path,
8768 const struct guestfs_is_blockdev_opts_argv *optargs);
8769 This is the "argv variant" of "guestfs_is_blockdev_opts".
8771 See "CALLS WITH OPTIONAL ARGUMENTS".
8773 guestfs_is_busy
8775 int
8776 guestfs_is_busy (guestfs_h *g);
8777 This always returns false. This function is deprecated with no
8779 replacement. Do not use this function.
8780 For more information on states, see guestfs(3).
8782 This function returns a C truth value on success or -1 on error.
8784 (Added in 1.0.2)
8786 guestfs_is_chardev
8788 int
8789 guestfs_is_chardev (guestfs_h *g,
8790 const char *path);
8791 This function is provided for backwards compatibility with earlier
8793 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8794 no optional arguments.
8795 (Added in 1.5.10)
8797 guestfs_is_chardev_opts
8799 int
8800 guestfs_is_chardev_opts (guestfs_h *g,
8801 const char *path,
8802 ...);
8803 You may supply a list of optional arguments to this call. Use zero or
8805 more of the following pairs of parameters, and terminate the list with
8806 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8807 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8809 This returns "true" if and only if there is a character device with the
8811 given "path" name.
8812 If the optional flag "followsymlinks" is true, then a symlink (or chain
8814 of symlinks) that ends with a chardev also causes the function to
8815 return true.
8816 See also "guestfs_stat".
8818 This function returns a C truth value on success or -1 on error.
8820 (Added in 1.5.10)
8822 guestfs_is_chardev_opts_va
8824 int
8825 guestfs_is_chardev_opts_va (guestfs_h *g,
8826 const char *path,
8827 va_list args);
8828 This is the "va_list variant" of "guestfs_is_chardev_opts".
8830 See "CALLS WITH OPTIONAL ARGUMENTS".
8832 guestfs_is_chardev_opts_argv
8834 int
8835 guestfs_is_chardev_opts_argv (guestfs_h *g,
8836 const char *path,
8837 const struct guestfs_is_chardev_opts_argv *optargs);
8838 This is the "argv variant" of "guestfs_is_chardev_opts".
8840 See "CALLS WITH OPTIONAL ARGUMENTS".
8842 guestfs_is_config
8844 int
8845 guestfs_is_config (guestfs_h *g);
8846 This returns true iff this handle is being configured (in the "CONFIG"
8848 state).
8849 For more information on states, see guestfs(3).
8851 This function returns a C truth value on success or -1 on error.
8853 (Added in 1.0.2)
8855 guestfs_is_dir
8857 int
8858 guestfs_is_dir (guestfs_h *g,
8859 const char *path);
8860 This function is provided for backwards compatibility with earlier
8862 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8863 optional arguments.
8864 (Added in 0.8)
8866 guestfs_is_dir_opts
8868 int
8869 guestfs_is_dir_opts (guestfs_h *g,
8870 const char *path,
8871 ...);
8872 You may supply a list of optional arguments to this call. Use zero or
8874 more of the following pairs of parameters, and terminate the list with
8875 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8876 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8878 This returns "true" if and only if there is a directory with the given
8880 "path" name. Note that it returns false for other objects like files.
8881 If the optional flag "followsymlinks" is true, then a symlink (or chain
8883 of symlinks) that ends with a directory also causes the function to
8884 return true.
8885 See also "guestfs_stat".
8887 This function returns a C truth value on success or -1 on error.
8889 (Added in 0.8)
8891 guestfs_is_dir_opts_va
8893 int
8894 guestfs_is_dir_opts_va (guestfs_h *g,
8895 const char *path,
8896 va_list args);
8897 This is the "va_list variant" of "guestfs_is_dir_opts".
8899 See "CALLS WITH OPTIONAL ARGUMENTS".
8901 guestfs_is_dir_opts_argv
8903 int
8904 guestfs_is_dir_opts_argv (guestfs_h *g,
8905 const char *path,
8906 const struct guestfs_is_dir_opts_argv *optargs);
8907 This is the "argv variant" of "guestfs_is_dir_opts".
8909 See "CALLS WITH OPTIONAL ARGUMENTS".
8911 guestfs_is_fifo
8913 int
8914 guestfs_is_fifo (guestfs_h *g,
8915 const char *path);
8916 This function is provided for backwards compatibility with earlier
8918 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8919 optional arguments.
8920 (Added in 1.5.10)
8922 guestfs_is_fifo_opts
8924 int
8925 guestfs_is_fifo_opts (guestfs_h *g,
8926 const char *path,
8927 ...);
8928 You may supply a list of optional arguments to this call. Use zero or
8930 more of the following pairs of parameters, and terminate the list with
8931 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8932 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8934 This returns "true" if and only if there is a FIFO (named pipe) with
8936 the given "path" name.
8937 If the optional flag "followsymlinks" is true, then a symlink (or chain
8939 of symlinks) that ends with a FIFO also causes the function to return
8940 true.
8941 See also "guestfs_stat".
8943 This function returns a C truth value on success or -1 on error.
8945 (Added in 1.5.10)
8947 guestfs_is_fifo_opts_va
8949 int
8950 guestfs_is_fifo_opts_va (guestfs_h *g,
8951 const char *path,
8952 va_list args);
8953 This is the "va_list variant" of "guestfs_is_fifo_opts".
8955 See "CALLS WITH OPTIONAL ARGUMENTS".
8957 guestfs_is_fifo_opts_argv
8959 int
8960 guestfs_is_fifo_opts_argv (guestfs_h *g,
8961 const char *path,
8962 const struct guestfs_is_fifo_opts_argv *optargs);
8963 This is the "argv variant" of "guestfs_is_fifo_opts".
8965 See "CALLS WITH OPTIONAL ARGUMENTS".
8967 guestfs_is_file
8969 int
8970 guestfs_is_file (guestfs_h *g,
8971 const char *path);
8972 This function is provided for backwards compatibility with earlier
8974 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
8975 optional arguments.
8976 (Added in 0.8)
8978 guestfs_is_file_opts
8980 int
8981 guestfs_is_file_opts (guestfs_h *g,
8982 const char *path,
8983 ...);
8984 You may supply a list of optional arguments to this call. Use zero or
8986 more of the following pairs of parameters, and terminate the list with
8987 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8988 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8990 This returns "true" if and only if there is a regular file with the
8992 given "path" name. Note that it returns false for other objects like
8993 directories.
8994 If the optional flag "followsymlinks" is true, then a symlink (or chain
8996 of symlinks) that ends with a file also causes the function to return
8997 true.
8998 See also "guestfs_stat".
9000 This function returns a C truth value on success or -1 on error.
9002 (Added in 0.8)
9004 guestfs_is_file_opts_va
9006 int
9007 guestfs_is_file_opts_va (guestfs_h *g,
9008 const char *path,
9009 va_list args);
9010 This is the "va_list variant" of "guestfs_is_file_opts".
9012 See "CALLS WITH OPTIONAL ARGUMENTS".
9014 guestfs_is_file_opts_argv
9016 int
9017 guestfs_is_file_opts_argv (guestfs_h *g,
9018 const char *path,
9019 const struct guestfs_is_file_opts_argv *optargs);
9020 This is the "argv variant" of "guestfs_is_file_opts".
9022 See "CALLS WITH OPTIONAL ARGUMENTS".
9024 guestfs_is_launching
9026 int
9027 guestfs_is_launching (guestfs_h *g);
9028 This returns true iff this handle is launching the subprocess (in the
9030 "LAUNCHING" state).
9031 For more information on states, see guestfs(3).
9033 This function returns a C truth value on success or -1 on error.
9035 (Added in 1.0.2)
9037 guestfs_is_lv
9039 int
9040 guestfs_is_lv (guestfs_h *g,
9041 const char *mountable);
9042 This command tests whether "mountable" is a logical volume, and returns
9044 true iff this is the case.
9045 This function returns a C truth value on success or -1 on error.
9047 (Added in 1.5.3)
9049 guestfs_is_ready
9051 int
9052 guestfs_is_ready (guestfs_h *g);
9053 This returns true iff this handle is ready to accept commands (in the
9055 "READY" state).
9056 For more information on states, see guestfs(3).
9058 This function returns a C truth value on success or -1 on error.
9060 (Added in 1.0.2)
9062 guestfs_is_socket
9064 int
9065 guestfs_is_socket (guestfs_h *g,
9066 const char *path);
9067 This function is provided for backwards compatibility with earlier
9069 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
9070 no optional arguments.
9071 (Added in 1.5.10)
9073 guestfs_is_socket_opts
9075 int
9076 guestfs_is_socket_opts (guestfs_h *g,
9077 const char *path,
9078 ...);
9079 You may supply a list of optional arguments to this call. Use zero or
9081 more of the following pairs of parameters, and terminate the list with
9082 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9083 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9085 This returns "true" if and only if there is a Unix domain socket with
9087 the given "path" name.
9088 If the optional flag "followsymlinks" is true, then a symlink (or chain
9090 of symlinks) that ends with a socket also causes the function to return
9091 true.
9092 See also "guestfs_stat".
9094 This function returns a C truth value on success or -1 on error.
9096 (Added in 1.5.10)
9098 guestfs_is_socket_opts_va
9100 int
9101 guestfs_is_socket_opts_va (guestfs_h *g,
9102 const char *path,
9103 va_list args);
9104 This is the "va_list variant" of "guestfs_is_socket_opts".
9106 See "CALLS WITH OPTIONAL ARGUMENTS".
9108 guestfs_is_socket_opts_argv
9110 int
9111 guestfs_is_socket_opts_argv (guestfs_h *g,
9112 const char *path,
9113 const struct guestfs_is_socket_opts_argv *optargs);
9114 This is the "argv variant" of "guestfs_is_socket_opts".
9116 See "CALLS WITH OPTIONAL ARGUMENTS".
9118 guestfs_is_symlink
9120 int
9121 guestfs_is_symlink (guestfs_h *g,
9122 const char *path);
9123 This returns "true" if and only if there is a symbolic link with the
9125 given "path" name.
9126 See also "guestfs_stat".
9128 This function returns a C truth value on success or -1 on error.
9130 (Added in 1.5.10)
9132 guestfs_is_whole_device
9134 int
9135 guestfs_is_whole_device (guestfs_h *g,
9136 const char *device);
9137 This returns "true" if and only if "device" refers to a whole block
9139 device. That is, not a partition or a logical device.
9140 This function returns a C truth value on success or -1 on error.
9142 (Added in 1.21.9)
9144 guestfs_is_zero
9146 int
9147 guestfs_is_zero (guestfs_h *g,
9148 const char *path);
9149 This returns true iff the file exists and the file is empty or it
9151 contains all zero bytes.
9152 This function returns a C truth value on success or -1 on error.
9154 (Added in 1.11.8)
9156 guestfs_is_zero_device
9158 int
9159 guestfs_is_zero_device (guestfs_h *g,
9160 const char *device);
9161 This returns true iff the device exists and contains all zero bytes.
9163 Note that for large devices this can take a long time to run.
9165 This function returns a C truth value on success or -1 on error.
9167 (Added in 1.11.8)
9169 guestfs_isoinfo
9171 struct guestfs_isoinfo *
9172 guestfs_isoinfo (guestfs_h *g,
9173 const char *isofile);
9174 This is the same as "guestfs_isoinfo_device" except that it works for
9176 an ISO file located inside some other mounted filesystem. Note that in
9177 the common case where you have added an ISO file as a libguestfs
9178 device, you would not call this. Instead you would call
9179 "guestfs_isoinfo_device".
9180 This function returns a "struct guestfs_isoinfo *", or NULL if there
9182 was an error. The caller must call "guestfs_free_isoinfo" after use.
9183 (Added in 1.17.19)
9185 guestfs_isoinfo_device
9187 struct guestfs_isoinfo *
9188 guestfs_isoinfo_device (guestfs_h *g,
9189 const char *device);
9190 "device" is an ISO device. This returns a struct of information read
9192 from the primary volume descriptor (the ISO equivalent of the
9193 superblock) of the device.
9194 Usually it is more efficient to use the isoinfo(1) command with the -d
9196 option on the host to analyze ISO files, instead of going through
9197 libguestfs.
9198 For information on the primary volume descriptor fields, see
9200 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9201 This function returns a "struct guestfs_isoinfo *", or NULL if there
9203 was an error. The caller must call "guestfs_free_isoinfo" after use.
9204 (Added in 1.17.19)
9206 guestfs_journal_close
9208 int
9209 guestfs_journal_close (guestfs_h *g);
9210 Close the journal handle.
9212 This function returns 0 on success or -1 on error.
9214 This function depends on the feature "journal". See also
9216 "guestfs_feature_available".
9217 (Added in 1.23.11)
9219 guestfs_journal_get
9221 struct guestfs_xattr_list *
9222 guestfs_journal_get (guestfs_h *g);
9223 Read the current journal entry. This returns all the fields in the
9225 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
9226 field name (a string).
9227 The "attrval" is the field value (a binary blob, often but not always a
9229 string). Please note that "attrval" is a byte array, not a
9230 \0-terminated C string.
9231 The length of data may be truncated to the data threshold (see:
9233 "guestfs_journal_set_data_threshold",
9234 "guestfs_journal_get_data_threshold").
9235 If you set the data threshold to unlimited (0) then this call can read
9237 a journal entry of any size, ie. it is not limited by the libguestfs
9238 protocol.
9239 This function returns a "struct guestfs_xattr_list *", or NULL if there
9241 was an error. The caller must call "guestfs_free_xattr_list" after
9242 use.
9243 This function depends on the feature "journal". See also
9245 "guestfs_feature_available".
9246 (Added in 1.23.11)
9248 guestfs_journal_get_data_threshold
9250 int64_t
9251 guestfs_journal_get_data_threshold (guestfs_h *g);
9252 Get the current data threshold for reading journal entries. This is a
9254 hint to the journal that it may truncate data fields to this size when
9255 reading them (note also that it may not truncate them). If this
9256 returns 0, then the threshold is unlimited.
9257 See also "guestfs_journal_set_data_threshold".
9259 On error this function returns -1.
9261 This function depends on the feature "journal". See also
9263 "guestfs_feature_available".
9264 (Added in 1.23.11)
9266 guestfs_journal_get_realtime_usec
9268 int64_t
9269 guestfs_journal_get_realtime_usec (guestfs_h *g);
9270 Get the realtime (wallclock) timestamp of the current journal entry.
9272 On error this function returns -1.
9274 This function depends on the feature "journal". See also
9276 "guestfs_feature_available".
9277 (Added in 1.27.18)
9279 guestfs_journal_next
9281 int
9282 guestfs_journal_next (guestfs_h *g);
9283 Move to the next journal entry. You have to call this at least once
9285 after opening the handle before you are able to read data.
9286 The returned boolean tells you if there are any more journal records to
9288 read. "true" means you can read the next record (eg. using
9289 "guestfs_journal_get"), and "false" means you have reached the end of
9290 the journal.
9291 This function returns a C truth value on success or -1 on error.
9293 This function depends on the feature "journal". See also
9295 "guestfs_feature_available".
9296 (Added in 1.23.11)
9298 guestfs_journal_open
9300 int
9301 guestfs_journal_open (guestfs_h *g,
9302 const char *directory);
9303 Open the systemd journal located in directory. Any previously opened
9305 journal handle is closed.
9306 The contents of the journal can be read using "guestfs_journal_next"
9308 and "guestfs_journal_get".
9309 After you have finished using the journal, you should close the handle
9311 by calling "guestfs_journal_close".
9312 This function returns 0 on success or -1 on error.
9314 This function depends on the feature "journal". See also
9316 "guestfs_feature_available".
9317 (Added in 1.23.11)
9319 guestfs_journal_set_data_threshold
9321 int
9322 guestfs_journal_set_data_threshold (guestfs_h *g,
9323 int64_t threshold);
9324 Set the data threshold for reading journal entries. This is a hint to
9326 the journal that it may truncate data fields to this size when reading
9327 them (note also that it may not truncate them). If you set this to 0,
9328 then the threshold is unlimited.
9329 See also "guestfs_journal_get_data_threshold".
9331 This function returns 0 on success or -1 on error.
9333 This function depends on the feature "journal". See also
9335 "guestfs_feature_available".
9336 (Added in 1.23.11)
9338 guestfs_journal_skip
9340 int64_t
9341 guestfs_journal_skip (guestfs_h *g,
9342 int64_t skip);
9343 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9345 The number of entries actually skipped is returned (note "rskip ≥ 0").
9347 If this is not the same as the absolute value of the skip parameter
9348 ("|skip|") you passed in then it means you have reached the end or the
9349 start of the journal.
9350 On error this function returns -1.
9352 This function depends on the feature "journal". See also
9354 "guestfs_feature_available".
9355 (Added in 1.23.11)
9357 guestfs_kill_subprocess
9359 int
9360 guestfs_kill_subprocess (guestfs_h *g);
9361 This function is deprecated. In new code, use the "guestfs_shutdown"
9363 call instead.
9364 Deprecated functions will not be removed from the API, but the fact
9366 that they are deprecated indicates that there are problems with correct
9367 use of these functions.
9368 This kills the hypervisor.
9370 Do not call this. See: "guestfs_shutdown" instead.
9372 This function returns 0 on success or -1 on error.
9374 (Added in 0.3)
9376 guestfs_launch
9378 int
9379 guestfs_launch (guestfs_h *g);
9380 You should call this after configuring the handle (eg. adding drives)
9382 but before performing any actions.
9383 Do not call "guestfs_launch" twice on the same handle. Although it
9385 will not give an error (for historical reasons), the precise behaviour
9386 when you do this is not well defined. Handles are very cheap to
9387 create, so create a new one for each launch.
9388 This function returns 0 on success or -1 on error.
9390 This long-running command can generate progress notification messages
9392 so that the caller can display a progress bar or indicator. To receive
9393 these messages, the caller must register a progress event callback.
9394 See "GUESTFS_EVENT_PROGRESS".
9395 (Added in 0.3)
9397 guestfs_lchown
9399 int
9400 guestfs_lchown (guestfs_h *g,
9401 int owner,
9402 int group,
9403 const char *path);
9404 Change the file owner to "owner" and group to "group". This is like
9406 "guestfs_chown" but if "path" is a symlink then the link itself is
9407 changed, not the target.
9408 Only numeric uid and gid are supported. If you want to use names, you
9410 will need to locate and parse the password file yourself (Augeas
9411 support makes this relatively easy).
9412 This function returns 0 on success or -1 on error.
9414 (Added in 1.0.77)
9416 guestfs_ldmtool_create_all
9418 int
9419 guestfs_ldmtool_create_all (guestfs_h *g);
9420 This function scans all block devices looking for Windows dynamic disk
9422 volumes and partitions, and creates devices for any that were found.
9423 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9425 return all devices.
9426 Note that you don't normally need to call this explicitly, since it is
9428 done automatically at "guestfs_launch" time.
9429 This function returns 0 on success or -1 on error.
9431 This function depends on the feature "ldm". See also
9433 "guestfs_feature_available".
9434 (Added in 1.20.0)
9436 guestfs_ldmtool_diskgroup_disks
9438 char **
9439 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9440 const char *diskgroup);
9441 Return the disks in a Windows dynamic disk group. The "diskgroup"
9443 parameter should be the GUID of a disk group, one element from the list
9444 returned by "guestfs_ldmtool_scan".
9445 This function returns a NULL-terminated array of strings (like
9447 environ(3)), or NULL if there was an error. The caller must free the
9448 strings and the array after use.
9449 This function depends on the feature "ldm". See also
9451 "guestfs_feature_available".
9452 (Added in 1.20.0)
9454 guestfs_ldmtool_diskgroup_name
9456 char *
9457 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9458 const char *diskgroup);
9459 Return the name of a Windows dynamic disk group. The "diskgroup"
9461 parameter should be the GUID of a disk group, one element from the list
9462 returned by "guestfs_ldmtool_scan".
9463 This function returns a string, or NULL on error. The caller must free
9465 the returned string after use.
9466 This function depends on the feature "ldm". See also
9468 "guestfs_feature_available".
9469 (Added in 1.20.0)
9471 guestfs_ldmtool_diskgroup_volumes
9473 char **
9474 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9475 const char *diskgroup);
9476 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9478 parameter should be the GUID of a disk group, one element from the list
9479 returned by "guestfs_ldmtool_scan".
9480 This function returns a NULL-terminated array of strings (like
9482 environ(3)), or NULL if there was an error. The caller must free the
9483 strings and the array after use.
9484 This function depends on the feature "ldm". See also
9486 "guestfs_feature_available".
9487 (Added in 1.20.0)
9489 guestfs_ldmtool_remove_all
9491 int
9492 guestfs_ldmtool_remove_all (guestfs_h *g);
9493 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9495 removes the device mapper mappings for all Windows dynamic disk volumes
9496 This function returns 0 on success or -1 on error.
9498 This function depends on the feature "ldm". See also
9500 "guestfs_feature_available".
9501 (Added in 1.20.0)
9503 guestfs_ldmtool_scan
9505 char **
9506 guestfs_ldmtool_scan (guestfs_h *g);
9507 This function scans for Windows dynamic disks. It returns a list of
9509 identifiers (GUIDs) for all disk groups that were found. These
9510 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9511 This function scans all block devices. To scan a subset of block
9513 devices, call "guestfs_ldmtool_scan_devices" instead.
9514 This function returns a NULL-terminated array of strings (like
9516 environ(3)), or NULL if there was an error. The caller must free the
9517 strings and the array after use.
9518 This function depends on the feature "ldm". See also
9520 "guestfs_feature_available".
9521 (Added in 1.20.0)
9523 guestfs_ldmtool_scan_devices
9525 char **
9526 guestfs_ldmtool_scan_devices (guestfs_h *g,
9527 char *const *devices);
9528 This function scans for Windows dynamic disks. It returns a list of
9530 identifiers (GUIDs) for all disk groups that were found. These
9531 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9532 The parameter "devices" is a list of block devices which are scanned.
9534 If this list is empty, all block devices are scanned.
9535 This function returns a NULL-terminated array of strings (like
9537 environ(3)), or NULL if there was an error. The caller must free the
9538 strings and the array after use.
9539 This function depends on the feature "ldm". See also
9541 "guestfs_feature_available".
9542 (Added in 1.20.0)
9544 guestfs_ldmtool_volume_hint
9546 char *
9547 guestfs_ldmtool_volume_hint (guestfs_h *g,
9548 const char *diskgroup,
9549 const char *volume);
9550 Return the hint field of the volume named "volume" in the disk group
9552 with GUID "diskgroup". This may not be defined, in which case the
9553 empty string is returned. The hint field is often, though not always,
9554 the name of a Windows drive, eg. "E:".
9555 This function returns a string, or NULL on error. The caller must free
9557 the returned string after use.
9558 This function depends on the feature "ldm". See also
9560 "guestfs_feature_available".
9561 (Added in 1.20.0)
9563 guestfs_ldmtool_volume_partitions
9565 char **
9566 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9567 const char *diskgroup,
9568 const char *volume);
9569 Return the list of partitions in the volume named "volume" in the disk
9571 group with GUID "diskgroup".
9572 This function returns a NULL-terminated array of strings (like
9574 environ(3)), or NULL if there was an error. The caller must free the
9575 strings and the array after use.
9576 This function depends on the feature "ldm". See also
9578 "guestfs_feature_available".
9579 (Added in 1.20.0)
9581 guestfs_ldmtool_volume_type
9583 char *
9584 guestfs_ldmtool_volume_type (guestfs_h *g,
9585 const char *diskgroup,
9586 const char *volume);
9587 Return the type of the volume named "volume" in the disk group with
9589 GUID "diskgroup".
9590 Possible volume types that can be returned here include: "simple",
9592 "spanned", "striped", "mirrored", "raid5". Other types may also be
9593 returned.
9594 This function returns a string, or NULL on error. The caller must free
9596 the returned string after use.
9597 This function depends on the feature "ldm". See also
9599 "guestfs_feature_available".
9600 (Added in 1.20.0)
9602 guestfs_lgetxattr
9604 char *
9605 guestfs_lgetxattr (guestfs_h *g,
9606 const char *path,
9607 const char *name,
9608 size_t *size_r);
9609 Get a single extended attribute from file "path" named "name". If
9611 "path" is a symlink, then this call returns an extended attribute from
9612 the symlink.
9613 Normally it is better to get all extended attributes from a file in one
9615 go by calling "guestfs_getxattrs". However some Linux filesystem
9616 implementations are buggy and do not provide a way to list out
9617 attributes. For these filesystems (notably ntfs-3g) you have to know
9618 the names of the extended attributes you want in advance and call this
9619 function.
9620 Extended attribute values are blobs of binary data. If there is no
9622 extended attribute named "name", this returns an error.
9623 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9625 This function returns a buffer, or NULL on error. The size of the
9627 returned buffer is written to *size_r. The caller must free the
9628 returned buffer after use.
9629 This function depends on the feature "linuxxattrs". See also
9631 "guestfs_feature_available".
9632 (Added in 1.7.24)
9634 guestfs_lgetxattrs
9636 struct guestfs_xattr_list *
9637 guestfs_lgetxattrs (guestfs_h *g,
9638 const char *path);
9639 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9641 link, then it returns the extended attributes of the link itself.
9642 This function returns a "struct guestfs_xattr_list *", or NULL if there
9644 was an error. The caller must call "guestfs_free_xattr_list" after
9645 use.
9646 This function depends on the feature "linuxxattrs". See also
9648 "guestfs_feature_available".
9649 (Added in 1.0.59)
9651 guestfs_list_9p
9653 char **
9654 guestfs_list_9p (guestfs_h *g);
9655 This function is deprecated. There is no replacement. Consult the API
9657 documentation in guestfs(3) for further information.
9658 Deprecated functions will not be removed from the API, but the fact
9660 that they are deprecated indicates that there are problems with correct
9661 use of these functions.
9662 This call does nothing and returns an error.
9664 This function returns a NULL-terminated array of strings (like
9666 environ(3)), or NULL if there was an error. The caller must free the
9667 strings and the array after use.
9668 (Added in 1.11.12)
9670 guestfs_list_devices
9672 char **
9673 guestfs_list_devices (guestfs_h *g);
9674 List all the block devices.
9676 The full block device names are returned, eg. /dev/sda.
9678 See also "guestfs_list_filesystems".
9680 This function returns a NULL-terminated array of strings (like
9682 environ(3)), or NULL if there was an error. The caller must free the
9683 strings and the array after use.
9684 (Added in 0.4)
9686 guestfs_list_disk_labels
9688 char **
9689 guestfs_list_disk_labels (guestfs_h *g);
9690 If you add drives using the optional "label" parameter of
9692 "guestfs_add_drive_opts", you can use this call to map between disk
9693 labels, and raw block device and partition names (like /dev/sda and
9694 /dev/sda1).
9695 This returns a hashtable, where keys are the disk labels (without the
9697 /dev/disk/guestfs prefix), and the values are the full raw block device
9698 and partition names (eg. /dev/sda and /dev/sda1).
9699 This function returns a NULL-terminated array of strings, or NULL if
9701 there was an error. The array of strings will always have length
9702 "2n+1", where "n" keys and values alternate, followed by the trailing
9703 NULL entry. The caller must free the strings and the array after use.
9704 (Added in 1.19.49)
9706 guestfs_list_dm_devices
9708 char **
9709 guestfs_list_dm_devices (guestfs_h *g);
9710 List all device mapper devices.
9712 The returned list contains /dev/mapper/* devices, eg. ones created by a
9714 previous call to "guestfs_luks_open".
9715 Device mapper devices which correspond to logical volumes are not
9717 returned in this list. Call "guestfs_lvs" if you want to list logical
9718 volumes.
9719 This function returns a NULL-terminated array of strings (like
9721 environ(3)), or NULL if there was an error. The caller must free the
9722 strings and the array after use.
9723 (Added in 1.11.15)
9725 guestfs_list_filesystems
9727 char **
9728 guestfs_list_filesystems (guestfs_h *g);
9729 This inspection command looks for filesystems on partitions, block
9731 devices and logical volumes, returning a list of "mountables"
9732 containing filesystems and their type.
9733 The return value is a hash, where the keys are the devices containing
9735 filesystems, and the values are the filesystem types. For example:
9736 "/dev/sda1" => "ntfs"
9738 "/dev/sda2" => "ext2"
9739 "/dev/vg_guest/lv_root" => "ext4"
9740 "/dev/vg_guest/lv_swap" => "swap"
9741 The key is not necessarily a block device. It may also be an opaque
9743 ‘mountable’ string which can be passed to "guestfs_mount".
9744 The value can have the special value "unknown", meaning the content of
9746 the device is undetermined or empty. "swap" means a Linux swap
9747 partition.
9748 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9750 might have included "guestfs_mount" and "guestfs_umount", and therefore
9751 you had to use this soon after launch and only when nothing else was
9752 mounted. This restriction is removed in libguestfs ≥ 1.38.
9753 Not all of the filesystems returned will be mountable. In particular,
9755 swap partitions are returned in the list. Also this command does not
9756 check that each filesystem found is valid and mountable, and some
9757 filesystems might be mountable but require special options.
9758 Filesystems may not all belong to a single logical operating system
9759 (use "guestfs_inspect_os" to look for OSes).
9760 This function returns a NULL-terminated array of strings, or NULL if
9762 there was an error. The array of strings will always have length
9763 "2n+1", where "n" keys and values alternate, followed by the trailing
9764 NULL entry. The caller must free the strings and the array after use.
9765 (Added in 1.5.15)
9767 guestfs_list_ldm_partitions
9769 char **
9770 guestfs_list_ldm_partitions (guestfs_h *g);
9771 This function returns all Windows dynamic disk partitions that were
9773 found at launch time. It returns a list of device names.
9774 This function returns a NULL-terminated array of strings (like
9776 environ(3)), or NULL if there was an error. The caller must free the
9777 strings and the array after use.
9778 This function depends on the feature "ldm". See also
9780 "guestfs_feature_available".
9781 (Added in 1.20.0)
9783 guestfs_list_ldm_volumes
9785 char **
9786 guestfs_list_ldm_volumes (guestfs_h *g);
9787 This function returns all Windows dynamic disk volumes that were found
9789 at launch time. It returns a list of device names.
9790 This function returns a NULL-terminated array of strings (like
9792 environ(3)), or NULL if there was an error. The caller must free the
9793 strings and the array after use.
9794 This function depends on the feature "ldm". See also
9796 "guestfs_feature_available".
9797 (Added in 1.20.0)
9799 guestfs_list_md_devices
9801 char **
9802 guestfs_list_md_devices (guestfs_h *g);
9803 List all Linux md devices.
9805 This function returns a NULL-terminated array of strings (like
9807 environ(3)), or NULL if there was an error. The caller must free the
9808 strings and the array after use.
9809 (Added in 1.15.4)
9811 guestfs_list_partitions
9813 char **
9814 guestfs_list_partitions (guestfs_h *g);
9815 List all the partitions detected on all block devices.
9817 The full partition device names are returned, eg. /dev/sda1
9819 This does not return logical volumes. For that you will need to call
9821 "guestfs_lvs".
9822 See also "guestfs_list_filesystems".
9824 This function returns a NULL-terminated array of strings (like
9826 environ(3)), or NULL if there was an error. The caller must free the
9827 strings and the array after use.
9828 (Added in 0.4)
9830 guestfs_ll
9832 char *
9833 guestfs_ll (guestfs_h *g,
9834 const char *directory);
9835 List the files in directory (relative to the root directory, there is
9837 no cwd) in the format of "ls -la".
9838 This command is mostly useful for interactive sessions. It is not
9840 intended that you try to parse the output string.
9841 This function returns a string, or NULL on error. The caller must free
9843 the returned string after use.
9844 (Added in 0.4)
9846 guestfs_llz
9848 char *
9849 guestfs_llz (guestfs_h *g,
9850 const char *directory);
9851 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9853 call instead.
9854 Deprecated functions will not be removed from the API, but the fact
9856 that they are deprecated indicates that there are problems with correct
9857 use of these functions.
9858 List the files in directory in the format of "ls -laZ".
9860 This command is mostly useful for interactive sessions. It is not
9862 intended that you try to parse the output string.
9863 This function returns a string, or NULL on error. The caller must free
9865 the returned string after use.
9866 (Added in 1.17.6)
9868 guestfs_ln
9870 int
9871 guestfs_ln (guestfs_h *g,
9872 const char *target,
9873 const char *linkname);
9874 This command creates a hard link.
9876 This function returns 0 on success or -1 on error.
9878 (Added in 1.0.66)
9880 guestfs_ln_f
9882 int
9883 guestfs_ln_f (guestfs_h *g,
9884 const char *target,
9885 const char *linkname);
9886 This command creates a hard link, removing the link "linkname" if it
9888 exists already.
9889 This function returns 0 on success or -1 on error.
9891 (Added in 1.0.66)
9893 guestfs_ln_s
9895 int
9896 guestfs_ln_s (guestfs_h *g,
9897 const char *target,
9898 const char *linkname);
9899 This command creates a symbolic link using the "ln -s" command.
9901 This function returns 0 on success or -1 on error.
9903 (Added in 1.0.66)
9905 guestfs_ln_sf
9907 int
9908 guestfs_ln_sf (guestfs_h *g,
9909 const char *target,
9910 const char *linkname);
9911 This command creates a symbolic link using the "ln -sf" command, The -f
9913 option removes the link ("linkname") if it exists already.
9914 This function returns 0 on success or -1 on error.
9916 (Added in 1.0.66)
9918 guestfs_lremovexattr
9920 int
9921 guestfs_lremovexattr (guestfs_h *g,
9922 const char *xattr,
9923 const char *path);
9924 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9926 link, then it removes an extended attribute of the link itself.
9927 This function returns 0 on success or -1 on error.
9929 This function depends on the feature "linuxxattrs". See also
9931 "guestfs_feature_available".
9932 (Added in 1.0.59)
9934 guestfs_ls
9936 char **
9937 guestfs_ls (guestfs_h *g,
9938 const char *directory);
9939 List the files in directory (relative to the root directory, there is
9941 no cwd). The "." and ".." entries are not returned, but hidden files
9942 are shown.
9943 This function returns a NULL-terminated array of strings (like
9945 environ(3)), or NULL if there was an error. The caller must free the
9946 strings and the array after use.
9947 (Added in 0.4)
9949 guestfs_ls0
9951 int
9952 guestfs_ls0 (guestfs_h *g,
9953 const char *dir,
9954 const char *filenames);
9955 This specialized command is used to get a listing of the filenames in
9957 the directory "dir". The list of filenames is written to the local
9958 file filenames (on the host).
9959 In the output file, the filenames are separated by "\0" characters.
9961 "." and ".." are not returned. The filenames are not sorted.
9963 This function returns 0 on success or -1 on error.
9965 (Added in 1.19.32)
9967 guestfs_lsetxattr
9969 int
9970 guestfs_lsetxattr (guestfs_h *g,
9971 const char *xattr,
9972 const char *val,
9973 int vallen,
9974 const char *path);
9975 This is the same as "guestfs_setxattr", but if "path" is a symbolic
9977 link, then it sets an extended attribute of the link itself.
9978 This function returns 0 on success or -1 on error.
9980 This function depends on the feature "linuxxattrs". See also
9982 "guestfs_feature_available".
9983 (Added in 1.0.59)
9985 guestfs_lstat
9987 struct guestfs_stat *
9988 guestfs_lstat (guestfs_h *g,
9989 const char *path);
9990 This function is deprecated. In new code, use the "guestfs_lstatns"
9992 call instead.
9993 Deprecated functions will not be removed from the API, but the fact
9995 that they are deprecated indicates that there are problems with correct
9996 use of these functions.
9997 Returns file information for the given "path".
9999 This is the same as "guestfs_stat" except that if "path" is a symbolic
10001 link, then the link is stat-ed, not the file it refers to.
10002 This is the same as the lstat(2) system call.
10004 This function returns a "struct guestfs_stat *", or NULL if there was
10006 an error. The caller must call "guestfs_free_stat" after use.
10007 (Added in 1.9.2)
10009 guestfs_lstatlist
10011 struct guestfs_stat_list *
10012 guestfs_lstatlist (guestfs_h *g,
10013 const char *path,
10014 char *const *names);
10015 This function is deprecated. In new code, use the
10017 "guestfs_lstatnslist" call instead.
10018 Deprecated functions will not be removed from the API, but the fact
10020 that they are deprecated indicates that there are problems with correct
10021 use of these functions.
10022 This call allows you to perform the "guestfs_lstat" operation on
10024 multiple files, where all files are in the directory "path". "names"
10025 is the list of files from this directory.
10026 On return you get a list of stat structs, with a one-to-one
10028 correspondence to the "names" list. If any name did not exist or could
10029 not be lstat'd, then the "st_ino" field of that structure is set to
10030 "-1".
10031 This call is intended for programs that want to efficiently list a
10033 directory contents without making many round-trips. See also
10034 "guestfs_lxattrlist" for a similarly efficient call for getting
10035 extended attributes.
10036 This function returns a "struct guestfs_stat_list *", or NULL if there
10038 was an error. The caller must call "guestfs_free_stat_list" after use.
10039 (Added in 1.0.77)
10041 guestfs_lstatns
10043 struct guestfs_statns *
10044 guestfs_lstatns (guestfs_h *g,
10045 const char *path);
10046 Returns file information for the given "path".
10048 This is the same as "guestfs_statns" except that if "path" is a
10050 symbolic link, then the link is stat-ed, not the file it refers to.
10051 This is the same as the lstat(2) system call.
10053 This function returns a "struct guestfs_statns *", or NULL if there was
10055 an error. The caller must call "guestfs_free_statns" after use.
10056 (Added in 1.27.53)
10058 guestfs_lstatnslist
10060 struct guestfs_statns_list *
10061 guestfs_lstatnslist (guestfs_h *g,
10062 const char *path,
10063 char *const *names);
10064 This call allows you to perform the "guestfs_lstatns" operation on
10066 multiple files, where all files are in the directory "path". "names"
10067 is the list of files from this directory.
10068 On return you get a list of stat structs, with a one-to-one
10070 correspondence to the "names" list. If any name did not exist or could
10071 not be lstat'd, then the "st_ino" field of that structure is set to
10072 "-1".
10073 This call is intended for programs that want to efficiently list a
10075 directory contents without making many round-trips. See also
10076 "guestfs_lxattrlist" for a similarly efficient call for getting
10077 extended attributes.
10078 This function returns a "struct guestfs_statns_list *", or NULL if
10080 there was an error. The caller must call "guestfs_free_statns_list"
10081 after use.
10082 (Added in 1.27.53)
10084 guestfs_luks_add_key
10086 int
10087 guestfs_luks_add_key (guestfs_h *g,
10088 const char *device,
10089 const char *key,
10090 const char *newkey,
10091 int keyslot);
10092 This command adds a new key on LUKS device "device". "key" is any
10094 existing key, and is used to access the device. "newkey" is the new
10095 key to add. "keyslot" is the key slot that will be replaced.
10096 Note that if "keyslot" already contains a key, then this command will
10098 fail. You have to use "guestfs_luks_kill_slot" first to remove that
10099 key.
10100 This function returns 0 on success or -1 on error.
10102 This function takes a key or passphrase parameter which could contain
10104 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10105 information.
10106 This function depends on the feature "luks". See also
10108 "guestfs_feature_available".
10109 (Added in 1.5.2)
10111 guestfs_luks_close
10113 int
10114 guestfs_luks_close (guestfs_h *g,
10115 const char *device);
10116 This function is deprecated. In new code, use the
10118 "guestfs_cryptsetup_close" call instead.
10119 Deprecated functions will not be removed from the API, but the fact
10121 that they are deprecated indicates that there are problems with correct
10122 use of these functions.
10123 This closes a LUKS device that was created earlier by
10125 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
10126 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10127 and not the name of the underlying block device.
10128 This function returns 0 on success or -1 on error.
10130 This function depends on the feature "luks". See also
10132 "guestfs_feature_available".
10133 (Added in 1.5.1)
10135 guestfs_luks_format
10137 int
10138 guestfs_luks_format (guestfs_h *g,
10139 const char *device,
10140 const char *key,
10141 int keyslot);
10142 This command erases existing data on "device" and formats the device as
10144 a LUKS encrypted device. "key" is the initial key, which is added to
10145 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
10146 This function returns 0 on success or -1 on error.
10148 This function takes a key or passphrase parameter which could contain
10150 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10151 information.
10152 This function depends on the feature "luks". See also
10154 "guestfs_feature_available".
10155 (Added in 1.5.2)
10157 guestfs_luks_format_cipher
10159 int
10160 guestfs_luks_format_cipher (guestfs_h *g,
10161 const char *device,
10162 const char *key,
10163 int keyslot,
10164 const char *cipher);
10165 This command is the same as "guestfs_luks_format" but it also allows
10167 you to set the "cipher" used.
10168 This function returns 0 on success or -1 on error.
10170 This function takes a key or passphrase parameter which could contain
10172 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10173 information.
10174 This function depends on the feature "luks". See also
10176 "guestfs_feature_available".
10177 (Added in 1.5.2)
10179 guestfs_luks_kill_slot
10181 int
10182 guestfs_luks_kill_slot (guestfs_h *g,
10183 const char *device,
10184 const char *key,
10185 int keyslot);
10186 This command deletes the key in key slot "keyslot" from the encrypted
10188 LUKS device "device". "key" must be one of the other keys.
10189 This function returns 0 on success or -1 on error.
10191 This function takes a key or passphrase parameter which could contain
10193 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10194 information.
10195 This function depends on the feature "luks". See also
10197 "guestfs_feature_available".
10198 (Added in 1.5.2)
10200 guestfs_luks_open
10202 int
10203 guestfs_luks_open (guestfs_h *g,
10204 const char *device,
10205 const char *key,
10206 const char *mapname);
10207 This function is deprecated. In new code, use the
10209 "guestfs_cryptsetup_open" call instead.
10210 Deprecated functions will not be removed from the API, but the fact
10212 that they are deprecated indicates that there are problems with correct
10213 use of these functions.
10214 This command opens a block device which has been encrypted according to
10216 the Linux Unified Key Setup (LUKS) standard.
10217 "device" is the encrypted block device or partition.
10219 The caller must supply one of the keys associated with the LUKS block
10221 device, in the "key" parameter.
10222 This creates a new block device called /dev/mapper/mapname. Reads and
10224 writes to this block device are decrypted from and encrypted to the
10225 underlying "device" respectively.
10226 If this block device contains LVM volume groups, then calling
10228 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10229 visible.
10230 Use "guestfs_list_dm_devices" to list all device mapper devices.
10232 This function returns 0 on success or -1 on error.
10234 This function takes a key or passphrase parameter which could contain
10236 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10237 information.
10238 This function depends on the feature "luks". See also
10240 "guestfs_feature_available".
10241 (Added in 1.5.1)
10243 guestfs_luks_open_ro
10245 int
10246 guestfs_luks_open_ro (guestfs_h *g,
10247 const char *device,
10248 const char *key,
10249 const char *mapname);
10250 This function is deprecated. In new code, use the
10252 "guestfs_cryptsetup_open" call instead.
10253 Deprecated functions will not be removed from the API, but the fact
10255 that they are deprecated indicates that there are problems with correct
10256 use of these functions.
10257 This is the same as "guestfs_luks_open" except that a read-only mapping
10259 is created.
10260 This function returns 0 on success or -1 on error.
10262 This function takes a key or passphrase parameter which could contain
10264 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10265 information.
10266 This function depends on the feature "luks". See also
10268 "guestfs_feature_available".
10269 (Added in 1.5.1)
10271 guestfs_luks_uuid
10273 char *
10274 guestfs_luks_uuid (guestfs_h *g,
10275 const char *device);
10276 This returns the UUID of the LUKS device "device".
10278 This function returns a string, or NULL on error. The caller must free
10280 the returned string after use.
10281 This function depends on the feature "luks". See also
10283 "guestfs_feature_available".
10284 (Added in 1.41.9)
10286 guestfs_lvcreate
10288 int
10289 guestfs_lvcreate (guestfs_h *g,
10290 const char *logvol,
10291 const char *volgroup,
10292 int mbytes);
10293 This creates an LVM logical volume called "logvol" on the volume group
10295 "volgroup", with "size" megabytes.
10296 This function returns 0 on success or -1 on error.
10298 This function depends on the feature "lvm2". See also
10300 "guestfs_feature_available".
10301 (Added in 0.8)
10303 guestfs_lvcreate_free
10305 int
10306 guestfs_lvcreate_free (guestfs_h *g,
10307 const char *logvol,
10308 const char *volgroup,
10309 int percent);
10310 Create an LVM logical volume called /dev/volgroup/logvol, using
10312 approximately "percent" % of the free space remaining in the volume
10313 group. Most usefully, when "percent" is 100 this will create the
10314 largest possible LV.
10315 This function returns 0 on success or -1 on error.
10317 This function depends on the feature "lvm2". See also
10319 "guestfs_feature_available".
10320 (Added in 1.17.18)
10322 guestfs_lvm_canonical_lv_name
10324 char *
10325 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10326 const char *lvname);
10327 This converts alternative naming schemes for LVs that you might find to
10329 the canonical name. For example, /dev/mapper/VG-LV is converted to
10330 /dev/VG/LV.
10331 This command returns an error if the "lvname" parameter does not refer
10333 to a logical volume. In this case errno will be set to "EINVAL".
10334 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10336 This function returns a string, or NULL on error. The caller must free
10338 the returned string after use.
10339 (Added in 1.5.24)
10341 guestfs_lvm_clear_filter
10343 int
10344 guestfs_lvm_clear_filter (guestfs_h *g);
10345 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10347 to see every block device.
10348 This command also clears the LVM cache and performs a volume group
10350 scan.
10351 This function returns 0 on success or -1 on error.
10353 (Added in 1.5.1)
10355 guestfs_lvm_remove_all
10357 int
10358 guestfs_lvm_remove_all (guestfs_h *g);
10359 This command removes all LVM logical volumes, volume groups and
10361 physical volumes.
10362 This function returns 0 on success or -1 on error.
10364 This function depends on the feature "lvm2". See also
10366 "guestfs_feature_available".
10367 (Added in 0.8)
10369 guestfs_lvm_scan
10371 int
10372 guestfs_lvm_scan (guestfs_h *g,
10373 int activate);
10374 This scans all block devices and rebuilds the list of LVM physical
10376 volumes, volume groups and logical volumes.
10377 If the "activate" parameter is "true" then newly found volume groups
10379 and logical volumes are activated, meaning the LV /dev/VG/LV devices
10380 become visible.
10381 When a libguestfs handle is launched it scans for existing devices, so
10383 you do not normally need to use this API. However it is useful when
10384 you have added a new device or deleted an existing device (such as when
10385 the "guestfs_luks_open" API is used).
10386 This function returns 0 on success or -1 on error.
10388 (Added in 1.39.8)
10390 guestfs_lvm_set_filter
10392 int
10393 guestfs_lvm_set_filter (guestfs_h *g,
10394 char *const *devices);
10395 This sets the LVM device filter so that LVM will only be able to "see"
10397 the block devices in the list "devices", and will ignore all other
10398 attached block devices.
10399 Where disk image(s) contain duplicate PVs or VGs, this command is
10401 useful to get LVM to ignore the duplicates, otherwise LVM can get
10402 confused. Note also there are two types of duplication possible:
10403 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10404 cloned but just happen to have the same name. In normal operation you
10405 cannot create this situation, but you can do it outside LVM, eg. by
10406 cloning disk images or by bit twiddling inside the LVM metadata.
10407 This command also clears the LVM cache and performs a volume group
10409 scan.
10410 You can filter whole block devices or individual partitions.
10412 You cannot use this if any VG is currently in use (eg. contains a
10414 mounted filesystem), even if you are not filtering out that VG.
10415 This function returns 0 on success or -1 on error.
10417 This function depends on the feature "lvm2". See also
10419 "guestfs_feature_available".
10420 (Added in 1.5.1)
10422 guestfs_lvremove
10424 int
10425 guestfs_lvremove (guestfs_h *g,
10426 const char *device);
10427 Remove an LVM logical volume "device", where "device" is the path to
10429 the LV, such as /dev/VG/LV.
10430 You can also remove all LVs in a volume group by specifying the VG
10432 name, /dev/VG.
10433 This function returns 0 on success or -1 on error.
10435 This function depends on the feature "lvm2". See also
10437 "guestfs_feature_available".
10438 (Added in 1.0.13)
10440 guestfs_lvrename
10442 int
10443 guestfs_lvrename (guestfs_h *g,
10444 const char *logvol,
10445 const char *newlogvol);
10446 Rename a logical volume "logvol" with the new name "newlogvol".
10448 This function returns 0 on success or -1 on error.
10450 (Added in 1.0.83)
10452 guestfs_lvresize
10454 int
10455 guestfs_lvresize (guestfs_h *g,
10456 const char *device,
10457 int mbytes);
10458 This resizes (expands or shrinks) an existing LVM logical volume to
10460 "mbytes". When reducing, data in the reduced part is lost.
10461 This function returns 0 on success or -1 on error.
10463 This function depends on the feature "lvm2". See also
10465 "guestfs_feature_available".
10466 (Added in 1.0.27)
10468 guestfs_lvresize_free
10470 int
10471 guestfs_lvresize_free (guestfs_h *g,
10472 const char *lv,
10473 int percent);
10474 This expands an existing logical volume "lv" so that it fills "pc" % of
10476 the remaining free space in the volume group. Commonly you would call
10477 this with pc = 100 which expands the logical volume as much as
10478 possible, using all remaining free space in the volume group.
10479 This function returns 0 on success or -1 on error.
10481 This function depends on the feature "lvm2". See also
10483 "guestfs_feature_available".
10484 (Added in 1.3.3)
10486 guestfs_lvs
10488 char **
10489 guestfs_lvs (guestfs_h *g);
10490 List all the logical volumes detected. This is the equivalent of the
10492 lvs(8) command.
10493 This returns a list of the logical volume device names (eg.
10495 /dev/VolGroup00/LogVol00).
10496 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10498 This function returns a NULL-terminated array of strings (like
10500 environ(3)), or NULL if there was an error. The caller must free the
10501 strings and the array after use.
10502 This function depends on the feature "lvm2". See also
10504 "guestfs_feature_available".
10505 (Added in 0.4)
10507 guestfs_lvs_full
10509 struct guestfs_lvm_lv_list *
10510 guestfs_lvs_full (guestfs_h *g);
10511 List all the logical volumes detected. This is the equivalent of the
10513 lvs(8) command. The "full" version includes all fields.
10514 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10516 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10517 after use.
10518 This function depends on the feature "lvm2". See also
10520 "guestfs_feature_available".
10521 (Added in 0.4)
10523 guestfs_lvuuid
10525 char *
10526 guestfs_lvuuid (guestfs_h *g,
10527 const char *device);
10528 This command returns the UUID of the LVM LV "device".
10530 This function returns a string, or NULL on error. The caller must free
10532 the returned string after use.
10533 (Added in 1.0.87)
10535 guestfs_lxattrlist
10537 struct guestfs_xattr_list *
10538 guestfs_lxattrlist (guestfs_h *g,
10539 const char *path,
10540 char *const *names);
10541 This call allows you to get the extended attributes of multiple files,
10543 where all files are in the directory "path". "names" is the list of
10544 files from this directory.
10545 On return you get a flat list of xattr structs which must be
10547 interpreted sequentially. The first xattr struct always has a zero-
10548 length "attrname". "attrval" in this struct is zero-length to indicate
10549 there was an error doing "guestfs_lgetxattr" for this file, or is a C
10550 string which is a decimal number (the number of following attributes
10551 for this file, which could be "0"). Then after the first xattr struct
10552 are the zero or more attributes for the first named file. This repeats
10553 for the second and subsequent files.
10554 This call is intended for programs that want to efficiently list a
10556 directory contents without making many round-trips. See also
10557 "guestfs_lstatlist" for a similarly efficient call for getting standard
10558 stats.
10559 This function returns a "struct guestfs_xattr_list *", or NULL if there
10561 was an error. The caller must call "guestfs_free_xattr_list" after
10562 use.
10563 This function depends on the feature "linuxxattrs". See also
10565 "guestfs_feature_available".
10566 (Added in 1.0.77)
10568 guestfs_max_disks
10570 int
10571 guestfs_max_disks (guestfs_h *g);
10572 Return the maximum number of disks that may be added to a handle (eg.
10574 by "guestfs_add_drive_opts" and similar calls).
10575 This function was added in libguestfs 1.19.7. In previous versions of
10577 libguestfs the limit was 25.
10578 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10580 On error this function returns -1.
10582 (Added in 1.19.7)
10584 guestfs_md_create
10586 int
10587 guestfs_md_create (guestfs_h *g,
10588 const char *name,
10589 char *const *devices,
10590 ...);
10591 You may supply a list of optional arguments to this call. Use zero or
10593 more of the following pairs of parameters, and terminate the list with
10594 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10595 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10597 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10598 GUESTFS_MD_CREATE_SPARE, int spare,
10599 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10600 GUESTFS_MD_CREATE_LEVEL, const char *level,
10601 Create a Linux md (RAID) device named "name" on the devices in the list
10603 "devices".
10604 The optional parameters are:
10606 "missingbitmap"
10608 A bitmap of missing devices. If a bit is set it means that a
10609 missing device is added to the array. The least significant bit
10610 corresponds to the first device in the array.
10611 As examples:
10613 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10615 resulting array would be "[<missing>, "/dev/sda"]".
10616 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10618 resulting array would be "["/dev/sda", <missing>]".
10619 This defaults to 0 (no missing devices).
10621 The length of "devices" + the number of bits set in "missingbitmap"
10623 must equal "nrdevices" + "spare".
10624 "nrdevices"
10626 The number of active RAID devices.
10627 If not set, this defaults to the length of "devices" plus the
10629 number of bits set in "missingbitmap".
10630 "spare"
10632 The number of spare devices.
10633 If not set, this defaults to 0.
10635 "chunk"
10637 The chunk size in bytes.
10638 The "chunk" parameter does not make sense, and should not be
10640 specified, when "level" is "raid1" (which is the default; see
10641 below).
10642 "level"
10644 The RAID level, which can be one of: "linear", "raid0", 0,
10645 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
10646 "raid10", 10. Some of these are synonymous, and more levels may be
10647 added in future.
10648 If not set, this defaults to "raid1".
10650 This function returns 0 on success or -1 on error.
10652 This function depends on the feature "mdadm". See also
10654 "guestfs_feature_available".
10655 (Added in 1.15.6)
10657 guestfs_md_create_va
10659 int
10660 guestfs_md_create_va (guestfs_h *g,
10661 const char *name,
10662 char *const *devices,
10663 va_list args);
10664 This is the "va_list variant" of "guestfs_md_create".
10666 See "CALLS WITH OPTIONAL ARGUMENTS".
10668 guestfs_md_create_argv
10670 int
10671 guestfs_md_create_argv (guestfs_h *g,
10672 const char *name,
10673 char *const *devices,
10674 const struct guestfs_md_create_argv *optargs);
10675 This is the "argv variant" of "guestfs_md_create".
10677 See "CALLS WITH OPTIONAL ARGUMENTS".
10679 guestfs_md_detail
10681 char **
10682 guestfs_md_detail (guestfs_h *g,
10683 const char *md);
10684 This command exposes the output of "mdadm -DY <md>". The following
10686 fields are usually present in the returned hash. Other fields may also
10687 be present.
10688 "level"
10690 The raid level of the MD device.
10691 "devices"
10693 The number of underlying devices in the MD device.
10694 "metadata"
10696 The metadata version used.
10697 "uuid"
10699 The UUID of the MD device.
10700 "name"
10702 The name of the MD device.
10703 This function returns a NULL-terminated array of strings, or NULL if
10705 there was an error. The array of strings will always have length
10706 "2n+1", where "n" keys and values alternate, followed by the trailing
10707 NULL entry. The caller must free the strings and the array after use.
10708 This function depends on the feature "mdadm". See also
10710 "guestfs_feature_available".
10711 (Added in 1.15.6)
10713 guestfs_md_stat
10715 struct guestfs_mdstat_list *
10716 guestfs_md_stat (guestfs_h *g,
10717 const char *md);
10718 This call returns a list of the underlying devices which make up the
10720 single software RAID array device "md".
10721 To get a list of software RAID devices, call "guestfs_list_md_devices".
10723 Each structure returned corresponds to one device along with additional
10725 status information:
10726 "mdstat_device"
10728 The name of the underlying device.
10729 "mdstat_index"
10731 The index of this device within the array.
10732 "mdstat_flags"
10734 Flags associated with this device. This is a string containing (in
10735 no specific order) zero or more of the following flags:
10736 "W" write-mostly
10738 "F" device is faulty
10740 "S" device is a RAID spare
10742 "R" replacement
10744 This function returns a "struct guestfs_mdstat_list *", or NULL if
10746 there was an error. The caller must call "guestfs_free_mdstat_list"
10747 after use.
10748 This function depends on the feature "mdadm". See also
10750 "guestfs_feature_available".
10751 (Added in 1.17.21)
10753 guestfs_md_stop
10755 int
10756 guestfs_md_stop (guestfs_h *g,
10757 const char *md);
10758 This command deactivates the MD array named "md". The device is
10760 stopped, but it is not destroyed or zeroed.
10761 This function returns 0 on success or -1 on error.
10763 This function depends on the feature "mdadm". See also
10765 "guestfs_feature_available".
10766 (Added in 1.15.6)
10768 guestfs_mkdir
10770 int
10771 guestfs_mkdir (guestfs_h *g,
10772 const char *path);
10773 Create a directory named "path".
10775 This function returns 0 on success or -1 on error.
10777 (Added in 0.8)
10779 guestfs_mkdir_mode
10781 int
10782 guestfs_mkdir_mode (guestfs_h *g,
10783 const char *path,
10784 int mode);
10785 This command creates a directory, setting the initial permissions of
10787 the directory to "mode".
10788 For common Linux filesystems, the actual mode which is set will be
10790 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10791 the mode in other ways.
10792 See also "guestfs_mkdir", "guestfs_umask"
10794 This function returns 0 on success or -1 on error.
10796 (Added in 1.0.77)
10798 guestfs_mkdir_p
10800 int
10801 guestfs_mkdir_p (guestfs_h *g,
10802 const char *path);
10803 Create a directory named "path", creating any parent directories as
10805 necessary. This is like the "mkdir -p" shell command.
10806 This function returns 0 on success or -1 on error.
10808 (Added in 0.8)
10810 guestfs_mkdtemp
10812 char *
10813 guestfs_mkdtemp (guestfs_h *g,
10814 const char *tmpl);
10815 This command creates a temporary directory. The "tmpl" parameter
10817 should be a full pathname for the temporary directory name with the
10818 final six characters being "XXXXXX".
10819 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10821 one being suitable for Windows filesystems.
10822 The name of the temporary directory that was created is returned.
10824 The temporary directory is created with mode 0700 and is owned by root.
10826 The caller is responsible for deleting the temporary directory and its
10828 contents after use.
10829 See also: mkdtemp(3)
10831 This function returns a string, or NULL on error. The caller must free
10833 the returned string after use.
10834 (Added in 1.0.54)
10836 guestfs_mke2fs
10838 int
10839 guestfs_mke2fs (guestfs_h *g,
10840 const char *device,
10841 ...);
10842 You may supply a list of optional arguments to this call. Use zero or
10844 more of the following pairs of parameters, and terminate the list with
10845 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10846 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10848 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10849 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10850 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10851 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10852 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10853 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10854 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10855 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10856 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10857 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10858 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10859 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10860 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10861 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10862 GUESTFS_MKE2FS_LABEL, const char *label,
10863 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10864 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10865 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10866 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10867 GUESTFS_MKE2FS_UUID, const char *uuid,
10868 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10869 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10870 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10871 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10872 GUESTFS_MKE2FS_TESTFS, int testfs,
10873 GUESTFS_MKE2FS_DISCARD, int discard,
10874 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10875 GUESTFS_MKE2FS_EXTENT, int extent,
10876 GUESTFS_MKE2FS_FILETYPE, int filetype,
10877 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10878 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10879 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10880 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10881 GUESTFS_MKE2FS_QUOTA, int quota,
10882 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10883 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10884 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10885 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10887 "device".
10888 The optional "blockscount" is the size of the filesystem in blocks. If
10890 omitted it defaults to the size of "device". Note if the filesystem is
10891 too small to contain a journal, "mke2fs" will silently create an ext2
10892 filesystem instead.
10893 This function returns 0 on success or -1 on error.
10895 (Added in 1.19.44)
10897 guestfs_mke2fs_va
10899 int
10900 guestfs_mke2fs_va (guestfs_h *g,
10901 const char *device,
10902 va_list args);
10903 This is the "va_list variant" of "guestfs_mke2fs".
10905 See "CALLS WITH OPTIONAL ARGUMENTS".
10907 guestfs_mke2fs_argv
10909 int
10910 guestfs_mke2fs_argv (guestfs_h *g,
10911 const char *device,
10912 const struct guestfs_mke2fs_argv *optargs);
10913 This is the "argv variant" of "guestfs_mke2fs".
10915 See "CALLS WITH OPTIONAL ARGUMENTS".
10917 guestfs_mke2fs_J
10919 int
10920 guestfs_mke2fs_J (guestfs_h *g,
10921 const char *fstype,
10922 int blocksize,
10923 const char *device,
10924 const char *journal);
10925 This function is deprecated. In new code, use the "guestfs_mke2fs"
10927 call instead.
10928 Deprecated functions will not be removed from the API, but the fact
10930 that they are deprecated indicates that there are problems with correct
10931 use of these functions.
10932 This creates an ext2/3/4 filesystem on "device" with an external
10934 journal on "journal". It is equivalent to the command:
10935 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10937 See also "guestfs_mke2journal".
10939 This function returns 0 on success or -1 on error.
10941 (Added in 1.0.68)
10943 guestfs_mke2fs_JL
10945 int
10946 guestfs_mke2fs_JL (guestfs_h *g,
10947 const char *fstype,
10948 int blocksize,
10949 const char *device,
10950 const char *label);
10951 This function is deprecated. In new code, use the "guestfs_mke2fs"
10953 call instead.
10954 Deprecated functions will not be removed from the API, but the fact
10956 that they are deprecated indicates that there are problems with correct
10957 use of these functions.
10958 This creates an ext2/3/4 filesystem on "device" with an external
10960 journal on the journal labeled "label".
10961 See also "guestfs_mke2journal_L".
10963 This function returns 0 on success or -1 on error.
10965 (Added in 1.0.68)
10967 guestfs_mke2fs_JU
10969 int
10970 guestfs_mke2fs_JU (guestfs_h *g,
10971 const char *fstype,
10972 int blocksize,
10973 const char *device,
10974 const char *uuid);
10975 This function is deprecated. In new code, use the "guestfs_mke2fs"
10977 call instead.
10978 Deprecated functions will not be removed from the API, but the fact
10980 that they are deprecated indicates that there are problems with correct
10981 use of these functions.
10982 This creates an ext2/3/4 filesystem on "device" with an external
10984 journal on the journal with UUID "uuid".
10985 See also "guestfs_mke2journal_U".
10987 This function returns 0 on success or -1 on error.
10989 This function depends on the feature "linuxfsuuid". See also
10991 "guestfs_feature_available".
10992 (Added in 1.0.68)
10994 guestfs_mke2journal
10996 int
10997 guestfs_mke2journal (guestfs_h *g,
10998 int blocksize,
10999 const char *device);
11000 This function is deprecated. In new code, use the "guestfs_mke2fs"
11002 call instead.
11003 Deprecated functions will not be removed from the API, but the fact
11005 that they are deprecated indicates that there are problems with correct
11006 use of these functions.
11007 This creates an ext2 external journal on "device". It is equivalent to
11009 the command:
11010 mke2fs -O journal_dev -b blocksize device
11012 This function returns 0 on success or -1 on error.
11014 (Added in 1.0.68)
11016 guestfs_mke2journal_L
11018 int
11019 guestfs_mke2journal_L (guestfs_h *g,
11020 int blocksize,
11021 const char *label,
11022 const char *device);
11023 This function is deprecated. In new code, use the "guestfs_mke2fs"
11025 call instead.
11026 Deprecated functions will not be removed from the API, but the fact
11028 that they are deprecated indicates that there are problems with correct
11029 use of these functions.
11030 This creates an ext2 external journal on "device" with label "label".
11032 This function returns 0 on success or -1 on error.
11034 (Added in 1.0.68)
11036 guestfs_mke2journal_U
11038 int
11039 guestfs_mke2journal_U (guestfs_h *g,
11040 int blocksize,
11041 const char *uuid,
11042 const char *device);
11043 This function is deprecated. In new code, use the "guestfs_mke2fs"
11045 call instead.
11046 Deprecated functions will not be removed from the API, but the fact
11048 that they are deprecated indicates that there are problems with correct
11049 use of these functions.
11050 This creates an ext2 external journal on "device" with UUID "uuid".
11052 This function returns 0 on success or -1 on error.
11054 This function depends on the feature "linuxfsuuid". See also
11056 "guestfs_feature_available".
11057 (Added in 1.0.68)
11059 guestfs_mkfifo
11061 int
11062 guestfs_mkfifo (guestfs_h *g,
11063 int mode,
11064 const char *path);
11065 This call creates a FIFO (named pipe) called "path" with mode "mode".
11067 It is just a convenient wrapper around "guestfs_mknod".
11068 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11070 The mode actually set is affected by the umask.
11072 This function returns 0 on success or -1 on error.
11074 This function depends on the feature "mknod". See also
11076 "guestfs_feature_available".
11077 (Added in 1.0.55)
11079 guestfs_mkfs
11081 int
11082 guestfs_mkfs (guestfs_h *g,
11083 const char *fstype,
11084 const char *device);
11085 This function is provided for backwards compatibility with earlier
11087 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
11088 optional arguments.
11089 (Added in 0.8)
11091 guestfs_mkfs_opts
11093 int
11094 guestfs_mkfs_opts (guestfs_h *g,
11095 const char *fstype,
11096 const char *device,
11097 ...);
11098 You may supply a list of optional arguments to this call. Use zero or
11100 more of the following pairs of parameters, and terminate the list with
11101 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11102 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
11104 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
11105 GUESTFS_MKFS_OPTS_INODE, int inode,
11106 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
11107 GUESTFS_MKFS_OPTS_LABEL, const char *label,
11108 This function creates a filesystem on "device". The filesystem type is
11110 "fstype", for example "ext3".
11111 The optional arguments are:
11113 "blocksize"
11115 The filesystem block size. Supported block sizes depend on the
11116 filesystem type, but typically they are 1024, 2048 or 4096 for
11117 Linux ext2/3 filesystems.
11118 For VFAT and NTFS the "blocksize" parameter is treated as the
11120 requested cluster size.
11121 For UFS block sizes, please see mkfs.ufs(8).
11123 "features"
11125 This passes the -O parameter to the external mkfs program.
11126 For certain filesystem types, this allows extra filesystem features
11128 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
11129 You cannot use this optional parameter with the "gfs" or "gfs2"
11131 filesystem type.
11132 "inode"
11134 This passes the -I parameter to the external mke2fs(8) program
11135 which sets the inode size (only for ext2/3/4 filesystems at
11136 present).
11137 "sectorsize"
11139 This passes the -S parameter to external mkfs.ufs(8) program, which
11140 sets sector size for ufs filesystem.
11141 This function returns 0 on success or -1 on error.
11143 (Added in 0.8)
11145 guestfs_mkfs_opts_va
11147 int
11148 guestfs_mkfs_opts_va (guestfs_h *g,
11149 const char *fstype,
11150 const char *device,
11151 va_list args);
11152 This is the "va_list variant" of "guestfs_mkfs_opts".
11154 See "CALLS WITH OPTIONAL ARGUMENTS".
11156 guestfs_mkfs_opts_argv
11158 int
11159 guestfs_mkfs_opts_argv (guestfs_h *g,
11160 const char *fstype,
11161 const char *device,
11162 const struct guestfs_mkfs_opts_argv *optargs);
11163 This is the "argv variant" of "guestfs_mkfs_opts".
11165 See "CALLS WITH OPTIONAL ARGUMENTS".
11167 guestfs_mkfs_b
11169 int
11170 guestfs_mkfs_b (guestfs_h *g,
11171 const char *fstype,
11172 int blocksize,
11173 const char *device);
11174 This function is deprecated. In new code, use the "guestfs_mkfs" call
11176 instead.
11177 Deprecated functions will not be removed from the API, but the fact
11179 that they are deprecated indicates that there are problems with correct
11180 use of these functions.
11181 This call is similar to "guestfs_mkfs", but it allows you to control
11183 the block size of the resulting filesystem. Supported block sizes
11184 depend on the filesystem type, but typically they are 1024, 2048 or
11185 4096 only.
11186 For VFAT and NTFS the "blocksize" parameter is treated as the requested
11188 cluster size.
11189 This function returns 0 on success or -1 on error.
11191 (Added in 1.0.68)
11193 guestfs_mkfs_btrfs
11195 int
11196 guestfs_mkfs_btrfs (guestfs_h *g,
11197 char *const *devices,
11198 ...);
11199 You may supply a list of optional arguments to this call. Use zero or
11201 more of the following pairs of parameters, and terminate the list with
11202 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11203 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11205 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11206 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11207 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11208 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11209 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11210 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11211 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11212 Create a btrfs filesystem, allowing all configurables to be set. For
11214 more information on the optional arguments, see mkfs.btrfs(8).
11215 Since btrfs filesystems can span multiple devices, this takes a non-
11217 empty list of devices.
11218 To create general filesystems, use "guestfs_mkfs".
11220 This function returns 0 on success or -1 on error.
11222 This function depends on the feature "btrfs". See also
11224 "guestfs_feature_available".
11225 (Added in 1.17.25)
11227 guestfs_mkfs_btrfs_va
11229 int
11230 guestfs_mkfs_btrfs_va (guestfs_h *g,
11231 char *const *devices,
11232 va_list args);
11233 This is the "va_list variant" of "guestfs_mkfs_btrfs".
11235 See "CALLS WITH OPTIONAL ARGUMENTS".
11237 guestfs_mkfs_btrfs_argv
11239 int
11240 guestfs_mkfs_btrfs_argv (guestfs_h *g,
11241 char *const *devices,
11242 const struct guestfs_mkfs_btrfs_argv *optargs);
11243 This is the "argv variant" of "guestfs_mkfs_btrfs".
11245 See "CALLS WITH OPTIONAL ARGUMENTS".
11247 guestfs_mklost_and_found
11249 int
11250 guestfs_mklost_and_found (guestfs_h *g,
11251 const char *mountpoint);
11252 Make the "lost+found" directory, normally in the root directory of an
11254 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
11255 to create the "lost+found" directory.
11256 This function returns 0 on success or -1 on error.
11258 (Added in 1.19.56)
11260 guestfs_mkmountpoint
11262 int
11263 guestfs_mkmountpoint (guestfs_h *g,
11264 const char *exemptpath);
11265 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11267 that can be used to create extra mountpoints before mounting the first
11268 filesystem.
11269 These calls are only necessary in some very limited circumstances,
11271 mainly the case where you want to mount a mix of unrelated and/or read-
11272 only filesystems together.
11273 For example, live CDs often contain a "Russian doll" nest of
11275 filesystems, an ISO outer layer, with a squashfs image inside, with an
11276 ext2/3 image inside that. You can unpack this as follows in guestfish:
11277 add-ro Fedora-11-i686-Live.iso
11279 run
11280 mkmountpoint /cd
11281 mkmountpoint /sqsh
11282 mkmountpoint /ext3fs
11283 mount /dev/sda /cd
11284 mount-loop /cd/LiveOS/squashfs.img /sqsh
11285 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11286 The inner filesystem is now unpacked under the /ext3fs mountpoint.
11288 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11290 You may get unexpected errors if you try to mix these calls. It is
11291 safest to manually unmount filesystems and remove mountpoints after
11292 use.
11293 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11295 first, so for this to work for manual mountpoints, you must ensure that
11296 the innermost mountpoints have the longest pathnames, as in the example
11297 code above.
11298 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11300 Autosync [see "guestfs_set_autosync", this is set by default on
11302 handles] can cause "guestfs_umount_all" to be called when the handle is
11303 closed which can also trigger these issues.
11304 This function returns 0 on success or -1 on error.
11306 (Added in 1.0.62)
11308 guestfs_mknod
11310 int
11311 guestfs_mknod (guestfs_h *g,
11312 int mode,
11313 int devmajor,
11314 int devminor,
11315 const char *path);
11316 This call creates block or character special devices, or named pipes
11318 (FIFOs).
11319 The "mode" parameter should be the mode, using the standard constants.
11321 "devmajor" and "devminor" are the device major and minor numbers, only
11322 used when creating block and character special devices.
11323 Note that, just like mknod(2), the mode must be bitwise OR'd with
11325 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11326 a regular file). These constants are available in the standard Linux
11327 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11328 "guestfs_mkfifo" which are wrappers around this command which bitwise
11329 OR in the appropriate constant for you.
11330 The mode actually set is affected by the umask.
11332 This function returns 0 on success or -1 on error.
11334 This function depends on the feature "mknod". See also
11336 "guestfs_feature_available".
11337 (Added in 1.0.55)
11339 guestfs_mknod_b
11341 int
11342 guestfs_mknod_b (guestfs_h *g,
11343 int mode,
11344 int devmajor,
11345 int devminor,
11346 const char *path);
11347 This call creates a block device node called "path" with mode "mode"
11349 and device major/minor "devmajor" and "devminor". It is just a
11350 convenient wrapper around "guestfs_mknod".
11351 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11353 The mode actually set is affected by the umask.
11355 This function returns 0 on success or -1 on error.
11357 This function depends on the feature "mknod". See also
11359 "guestfs_feature_available".
11360 (Added in 1.0.55)
11362 guestfs_mknod_c
11364 int
11365 guestfs_mknod_c (guestfs_h *g,
11366 int mode,
11367 int devmajor,
11368 int devminor,
11369 const char *path);
11370 This call creates a char device node called "path" with mode "mode" and
11372 device major/minor "devmajor" and "devminor". It is just a convenient
11373 wrapper around "guestfs_mknod".
11374 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11376 The mode actually set is affected by the umask.
11378 This function returns 0 on success or -1 on error.
11380 This function depends on the feature "mknod". See also
11382 "guestfs_feature_available".
11383 (Added in 1.0.55)
11385 guestfs_mksquashfs
11387 int
11388 guestfs_mksquashfs (guestfs_h *g,
11389 const char *path,
11390 const char *filename,
11391 ...);
11392 You may supply a list of optional arguments to this call. Use zero or
11394 more of the following pairs of parameters, and terminate the list with
11395 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11396 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11398 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11399 Create a squashfs filesystem for the specified "path".
11401 The optional "compress" flag controls compression. If not given, then
11403 the output compressed using "gzip". Otherwise one of the following
11404 strings may be given to select the compression type of the squashfs:
11405 "gzip", "lzma", "lzo", "lz4", "xz".
11406 The other optional arguments are:
11408 "excludes"
11410 A list of wildcards. Files are excluded if they match any of the
11411 wildcards.
11412 Please note that this API may fail when used to compress directories
11414 with large files, such as the resulting squashfs will be over 3GB big.
11415 This function returns 0 on success or -1 on error.
11417 This function depends on the feature "squashfs". See also
11419 "guestfs_feature_available".
11420 (Added in 1.35.25)
11422 guestfs_mksquashfs_va
11424 int
11425 guestfs_mksquashfs_va (guestfs_h *g,
11426 const char *path,
11427 const char *filename,
11428 va_list args);
11429 This is the "va_list variant" of "guestfs_mksquashfs".
11431 See "CALLS WITH OPTIONAL ARGUMENTS".
11433 guestfs_mksquashfs_argv
11435 int
11436 guestfs_mksquashfs_argv (guestfs_h *g,
11437 const char *path,
11438 const char *filename,
11439 const struct guestfs_mksquashfs_argv *optargs);
11440 This is the "argv variant" of "guestfs_mksquashfs".
11442 See "CALLS WITH OPTIONAL ARGUMENTS".
11444 guestfs_mkswap
11446 int
11447 guestfs_mkswap (guestfs_h *g,
11448 const char *device);
11449 This function is provided for backwards compatibility with earlier
11451 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11452 optional arguments.
11453 (Added in 1.0.55)
11455 guestfs_mkswap_opts
11457 int
11458 guestfs_mkswap_opts (guestfs_h *g,
11459 const char *device,
11460 ...);
11461 You may supply a list of optional arguments to this call. Use zero or
11463 more of the following pairs of parameters, and terminate the list with
11464 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11465 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11467 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11468 Create a Linux swap partition on "device".
11470 The option arguments "label" and "uuid" allow you to set the label
11472 and/or UUID of the new swap partition.
11473 This function returns 0 on success or -1 on error.
11475 (Added in 1.0.55)
11477 guestfs_mkswap_opts_va
11479 int
11480 guestfs_mkswap_opts_va (guestfs_h *g,
11481 const char *device,
11482 va_list args);
11483 This is the "va_list variant" of "guestfs_mkswap_opts".
11485 See "CALLS WITH OPTIONAL ARGUMENTS".
11487 guestfs_mkswap_opts_argv
11489 int
11490 guestfs_mkswap_opts_argv (guestfs_h *g,
11491 const char *device,
11492 const struct guestfs_mkswap_opts_argv *optargs);
11493 This is the "argv variant" of "guestfs_mkswap_opts".
11495 See "CALLS WITH OPTIONAL ARGUMENTS".
11497 guestfs_mkswap_L
11499 int
11500 guestfs_mkswap_L (guestfs_h *g,
11501 const char *label,
11502 const char *device);
11503 This function is deprecated. In new code, use the "guestfs_mkswap"
11505 call instead.
11506 Deprecated functions will not be removed from the API, but the fact
11508 that they are deprecated indicates that there are problems with correct
11509 use of these functions.
11510 Create a swap partition on "device" with label "label".
11512 Note that you cannot attach a swap label to a block device (eg.
11514 /dev/sda), just to a partition. This appears to be a limitation of the
11515 kernel or swap tools.
11516 This function returns 0 on success or -1 on error.
11518 (Added in 1.0.55)
11520 guestfs_mkswap_U
11522 int
11523 guestfs_mkswap_U (guestfs_h *g,
11524 const char *uuid,
11525 const char *device);
11526 This function is deprecated. In new code, use the "guestfs_mkswap"
11528 call instead.
11529 Deprecated functions will not be removed from the API, but the fact
11531 that they are deprecated indicates that there are problems with correct
11532 use of these functions.
11533 Create a swap partition on "device" with UUID "uuid".
11535 This function returns 0 on success or -1 on error.
11537 This function depends on the feature "linuxfsuuid". See also
11539 "guestfs_feature_available".
11540 (Added in 1.0.55)
11542 guestfs_mkswap_file
11544 int
11545 guestfs_mkswap_file (guestfs_h *g,
11546 const char *path);
11547 Create a swap file.
11549 This command just writes a swap file signature to an existing file. To
11551 create the file itself, use something like "guestfs_fallocate".
11552 This function returns 0 on success or -1 on error.
11554 (Added in 1.0.66)
11556 guestfs_mktemp
11558 char *
11559 guestfs_mktemp (guestfs_h *g,
11560 const char *tmpl,
11561 ...);
11562 You may supply a list of optional arguments to this call. Use zero or
11564 more of the following pairs of parameters, and terminate the list with
11565 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11566 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11568 This command creates a temporary file. The "tmpl" parameter should be
11570 a full pathname for the temporary directory name with the final six
11571 characters being "XXXXXX".
11572 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11574 one being suitable for Windows filesystems.
11575 The name of the temporary file that was created is returned.
11577 The temporary file is created with mode 0600 and is owned by root.
11579 The caller is responsible for deleting the temporary file after use.
11581 If the optional "suffix" parameter is given, then the suffix (eg.
11583 ".txt") is appended to the temporary name.
11584 See also: "guestfs_mkdtemp".
11586 This function returns a string, or NULL on error. The caller must free
11588 the returned string after use.
11589 (Added in 1.19.53)
11591 guestfs_mktemp_va
11593 char *
11594 guestfs_mktemp_va (guestfs_h *g,
11595 const char *tmpl,
11596 va_list args);
11597 This is the "va_list variant" of "guestfs_mktemp".
11599 See "CALLS WITH OPTIONAL ARGUMENTS".
11601 guestfs_mktemp_argv
11603 char *
11604 guestfs_mktemp_argv (guestfs_h *g,
11605 const char *tmpl,
11606 const struct guestfs_mktemp_argv *optargs);
11607 This is the "argv variant" of "guestfs_mktemp".
11609 See "CALLS WITH OPTIONAL ARGUMENTS".
11611 guestfs_modprobe
11613 int
11614 guestfs_modprobe (guestfs_h *g,
11615 const char *modulename);
11616 This loads a kernel module in the appliance.
11618 This function returns 0 on success or -1 on error.
11620 This function depends on the feature "linuxmodules". See also
11622 "guestfs_feature_available".
11623 (Added in 1.0.68)
11625 guestfs_mount
11627 int
11628 guestfs_mount (guestfs_h *g,
11629 const char *mountable,
11630 const char *mountpoint);
11631 Mount a guest disk at a position in the filesystem. Block devices are
11633 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11634 If those block devices contain partitions, they will have the usual
11635 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11636 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11637 "guestfs_inspect_get_mountpoints".
11638 The rules are the same as for mount(2): A filesystem must first be
11640 mounted on / before others can be mounted. Other filesystems can only
11641 be mounted on directories which already exist.
11642 The mounted filesystem is writable, if we have sufficient permissions
11644 on the underlying device.
11645 Before libguestfs 1.13.16, this call implicitly added the options
11647 "sync" and "noatime". The "sync" option greatly slowed writes and
11648 caused many problems for users. If your program might need to work
11649 with older versions of libguestfs, use "guestfs_mount_options" instead
11650 (using an empty string for the first parameter if you don't want any
11651 options).
11652 This function returns 0 on success or -1 on error.
11654 (Added in 0.3)
11656 guestfs_mount_9p
11658 int
11659 guestfs_mount_9p (guestfs_h *g,
11660 const char *mounttag,
11661 const char *mountpoint,
11662 ...);
11663 This function is deprecated. There is no replacement. Consult the API
11665 documentation in guestfs(3) for further information.
11666 Deprecated functions will not be removed from the API, but the fact
11668 that they are deprecated indicates that there are problems with correct
11669 use of these functions.
11670 You may supply a list of optional arguments to this call. Use zero or
11672 more of the following pairs of parameters, and terminate the list with
11673 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11674 GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11676 This call does nothing and returns an error.
11678 This function returns 0 on success or -1 on error.
11680 (Added in 1.11.12)
11682 guestfs_mount_9p_va
11684 int
11685 guestfs_mount_9p_va (guestfs_h *g,
11686 const char *mounttag,
11687 const char *mountpoint,
11688 va_list args);
11689 This is the "va_list variant" of "guestfs_mount_9p".
11691 See "CALLS WITH OPTIONAL ARGUMENTS".
11693 guestfs_mount_9p_argv
11695 int
11696 guestfs_mount_9p_argv (guestfs_h *g,
11697 const char *mounttag,
11698 const char *mountpoint,
11699 const struct guestfs_mount_9p_argv *optargs);
11700 This is the "argv variant" of "guestfs_mount_9p".
11702 See "CALLS WITH OPTIONAL ARGUMENTS".
11704 guestfs_mount_local
11706 int
11707 guestfs_mount_local (guestfs_h *g,
11708 const char *localmountpoint,
11709 ...);
11710 You may supply a list of optional arguments to this call. Use zero or
11712 more of the following pairs of parameters, and terminate the list with
11713 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11714 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11716 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11717 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11718 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11719 This call exports the libguestfs-accessible filesystem to a local
11721 mountpoint (directory) called "localmountpoint". Ordinary reads and
11722 writes to files and directories under "localmountpoint" are redirected
11723 through libguestfs.
11724 If the optional "readonly" flag is set to true, then writes to the
11726 filesystem return error "EROFS".
11727 "options" is a comma-separated list of mount options. See
11729 guestmount(1) for some useful options.
11730 "cachetimeout" sets the timeout (in seconds) for cached directory
11732 entries. The default is 60 seconds. See guestmount(1) for further
11733 information.
11734 If "debugcalls" is set to true, then additional debugging information
11736 is generated for every FUSE call.
11737 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11739 processing requests (access to it will block). You have to call
11740 "guestfs_mount_local_run" to run the main loop.
11741 See "MOUNT LOCAL" for full documentation.
11743 This function returns 0 on success or -1 on error.
11745 (Added in 1.17.22)
11747 guestfs_mount_local_va
11749 int
11750 guestfs_mount_local_va (guestfs_h *g,
11751 const char *localmountpoint,
11752 va_list args);
11753 This is the "va_list variant" of "guestfs_mount_local".
11755 See "CALLS WITH OPTIONAL ARGUMENTS".
11757 guestfs_mount_local_argv
11759 int
11760 guestfs_mount_local_argv (guestfs_h *g,
11761 const char *localmountpoint,
11762 const struct guestfs_mount_local_argv *optargs);
11763 This is the "argv variant" of "guestfs_mount_local".
11765 See "CALLS WITH OPTIONAL ARGUMENTS".
11767 guestfs_mount_local_run
11769 int
11770 guestfs_mount_local_run (guestfs_h *g);
11771 Run the main loop which translates kernel calls to libguestfs calls.
11773 This should only be called after "guestfs_mount_local" returns
11775 successfully. The call will not return until the filesystem is
11776 unmounted.
11777 Note you must not make concurrent libguestfs calls on the same handle
11779 from another thread.
11780 You may call this from a different thread than the one which called
11782 "guestfs_mount_local", subject to the usual rules for threads and
11783 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11784 See "MOUNT LOCAL" for full documentation.
11786 This function returns 0 on success or -1 on error.
11788 (Added in 1.17.22)
11790 guestfs_mount_loop
11792 int
11793 guestfs_mount_loop (guestfs_h *g,
11794 const char *file,
11795 const char *mountpoint);
11796 This command lets you mount file (a filesystem image in a file) on a
11798 mount point. It is entirely equivalent to the command "mount -o loop
11799 file mountpoint".
11800 This function returns 0 on success or -1 on error.
11802 (Added in 1.0.54)
11804 guestfs_mount_options
11806 int
11807 guestfs_mount_options (guestfs_h *g,
11808 const char *options,
11809 const char *mountable,
11810 const char *mountpoint);
11811 This is the same as the "guestfs_mount" command, but it allows you to
11813 set the mount options as for the mount(8) -o flag.
11814 If the "options" parameter is an empty string, then no options are
11816 passed (all options default to whatever the filesystem uses).
11817 This function returns 0 on success or -1 on error.
11819 (Added in 1.0.10)
11821 guestfs_mount_ro
11823 int
11824 guestfs_mount_ro (guestfs_h *g,
11825 const char *mountable,
11826 const char *mountpoint);
11827 This is the same as the "guestfs_mount" command, but it mounts the
11829 filesystem with the read-only (-o ro) flag.
11830 This function returns 0 on success or -1 on error.
11832 (Added in 1.0.10)
11834 guestfs_mount_vfs
11836 int
11837 guestfs_mount_vfs (guestfs_h *g,
11838 const char *options,
11839 const char *vfstype,
11840 const char *mountable,
11841 const char *mountpoint);
11842 This is the same as the "guestfs_mount" command, but it allows you to
11844 set both the mount options and the vfstype as for the mount(8) -o and
11845 -t flags.
11846 This function returns 0 on success or -1 on error.
11848 (Added in 1.0.10)
11850 guestfs_mountable_device
11852 char *
11853 guestfs_mountable_device (guestfs_h *g,
11854 const char *mountable);
11855 Returns the device name of a mountable. In quite a lot of cases, the
11857 mountable is the device name.
11858 However this doesn't apply for btrfs subvolumes, where the mountable is
11860 a combination of both the device name and the subvolume path (see also
11861 "guestfs_mountable_subvolume" to extract the subvolume path of the
11862 mountable if any).
11863 This function returns a string, or NULL on error. The caller must free
11865 the returned string after use.
11866 (Added in 1.33.15)
11868 guestfs_mountable_subvolume
11870 char *
11871 guestfs_mountable_subvolume (guestfs_h *g,
11872 const char *mountable);
11873 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11875 are a combination of both the device name and the subvolume path (see
11876 also "guestfs_mountable_device" to extract the device of the
11877 mountable).
11878 If the mountable does not represent a btrfs subvolume, then this
11880 function fails and the "errno" is set to "EINVAL".
11881 This function returns a string, or NULL on error. The caller must free
11883 the returned string after use.
11884 (Added in 1.33.15)
11886 guestfs_mountpoints
11888 char **
11889 guestfs_mountpoints (guestfs_h *g);
11890 This call is similar to "guestfs_mounts". That call returns a list of
11892 devices. This one returns a hash table (map) of device name to
11893 directory where the device is mounted.
11894 This function returns a NULL-terminated array of strings, or NULL if
11896 there was an error. The array of strings will always have length
11897 "2n+1", where "n" keys and values alternate, followed by the trailing
11898 NULL entry. The caller must free the strings and the array after use.
11899 (Added in 1.0.62)
11901 guestfs_mounts
11903 char **
11904 guestfs_mounts (guestfs_h *g);
11905 This returns the list of currently mounted filesystems. It returns the
11907 list of devices (eg. /dev/sda1, /dev/VG/LV).
11908 Some internal mounts are not shown.
11910 See also: "guestfs_mountpoints"
11912 This function returns a NULL-terminated array of strings (like
11914 environ(3)), or NULL if there was an error. The caller must free the
11915 strings and the array after use.
11916 (Added in 0.8)
11918 guestfs_mv
11920 int
11921 guestfs_mv (guestfs_h *g,
11922 const char *src,
11923 const char *dest);
11924 This moves a file from "src" to "dest" where "dest" is either a
11926 destination filename or destination directory.
11927 See also: "guestfs_rename".
11929 This function returns 0 on success or -1 on error.
11931 (Added in 1.0.18)
11933 guestfs_nr_devices
11935 int
11936 guestfs_nr_devices (guestfs_h *g);
11937 This returns the number of whole block devices that were added. This
11939 is the same as the number of devices that would be returned if you
11940 called "guestfs_list_devices".
11941 To find out the maximum number of devices that could be added, call
11943 "guestfs_max_disks".
11944 On error this function returns -1.
11946 (Added in 1.19.15)
11948 guestfs_ntfs_3g_probe
11950 int
11951 guestfs_ntfs_3g_probe (guestfs_h *g,
11952 int rw,
11953 const char *device);
11954 This command runs the ntfs-3g.probe(8) command which probes an NTFS
11956 "device" for mountability. (Not all NTFS volumes can be mounted read-
11957 write, and some cannot be mounted at all).
11958 "rw" is a boolean flag. Set it to true if you want to test if the
11960 volume can be mounted read-write. Set it to false if you want to test
11961 if the volume can be mounted read-only.
11962 The return value is an integer which 0 if the operation would succeed,
11964 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
11965 On error this function returns -1.
11967 This function depends on the feature "ntfs3g". See also
11969 "guestfs_feature_available".
11970 (Added in 1.0.43)
11972 guestfs_ntfscat_i
11974 int
11975 guestfs_ntfscat_i (guestfs_h *g,
11976 const char *device,
11977 int64_t inode,
11978 const char *filename);
11979 Download a file given its inode from a NTFS filesystem and save it as
11981 filename on the local machine.
11982 This allows to download some otherwise inaccessible files such as the
11984 ones within the $Extend folder.
11985 The filesystem from which to extract the file must be unmounted,
11987 otherwise the call will fail.
11988 This function returns 0 on success or -1 on error.
11990 This long-running command can generate progress notification messages
11992 so that the caller can display a progress bar or indicator. To receive
11993 these messages, the caller must register a progress event callback.
11994 See "GUESTFS_EVENT_PROGRESS".
11995 (Added in 1.33.14)
11997 guestfs_ntfsclone_in
11999 int
12000 guestfs_ntfsclone_in (guestfs_h *g,
12001 const char *backupfile,
12002 const char *device);
12003 Restore the "backupfile" (from a previous call to
12005 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
12006 of this device.
12007 This function returns 0 on success or -1 on error.
12009 This function depends on the feature "ntfs3g". See also
12011 "guestfs_feature_available".
12012 (Added in 1.17.9)
12014 guestfs_ntfsclone_out
12016 int
12017 guestfs_ntfsclone_out (guestfs_h *g,
12018 const char *device,
12019 const char *backupfile,
12020 ...);
12021 You may supply a list of optional arguments to this call. Use zero or
12023 more of the following pairs of parameters, and terminate the list with
12024 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12025 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
12027 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
12028 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
12029 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
12030 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
12031 Stream the NTFS filesystem "device" to the local file "backupfile".
12033 The format used for the backup file is a special format used by the
12034 ntfsclone(8) tool.
12035 If the optional "metadataonly" flag is true, then only the metadata is
12037 saved, losing all the user data (this is useful for diagnosing some
12038 filesystem problems).
12039 The optional "rescue", "ignorefscheck", "preservetimestamps" and
12041 "force" flags have precise meanings detailed in the ntfsclone(8) man
12042 page.
12043 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
12045 device.
12046 This function returns 0 on success or -1 on error.
12048 This function depends on the feature "ntfs3g". See also
12050 "guestfs_feature_available".
12051 (Added in 1.17.9)
12053 guestfs_ntfsclone_out_va
12055 int
12056 guestfs_ntfsclone_out_va (guestfs_h *g,
12057 const char *device,
12058 const char *backupfile,
12059 va_list args);
12060 This is the "va_list variant" of "guestfs_ntfsclone_out".
12062 See "CALLS WITH OPTIONAL ARGUMENTS".
12064 guestfs_ntfsclone_out_argv
12066 int
12067 guestfs_ntfsclone_out_argv (guestfs_h *g,
12068 const char *device,
12069 const char *backupfile,
12070 const struct guestfs_ntfsclone_out_argv *optargs);
12071 This is the "argv variant" of "guestfs_ntfsclone_out".
12073 See "CALLS WITH OPTIONAL ARGUMENTS".
12075 guestfs_ntfsfix
12077 int
12078 guestfs_ntfsfix (guestfs_h *g,
12079 const char *device,
12080 ...);
12081 You may supply a list of optional arguments to this call. Use zero or
12083 more of the following pairs of parameters, and terminate the list with
12084 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12085 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
12087 This command repairs some fundamental NTFS inconsistencies, resets the
12089 NTFS journal file, and schedules an NTFS consistency check for the
12090 first boot into Windows.
12091 This is not an equivalent of Windows "chkdsk". It does not scan the
12093 filesystem for inconsistencies.
12094 The optional "clearbadsectors" flag clears the list of bad sectors.
12096 This is useful after cloning a disk with bad sectors to a new disk.
12097 This function returns 0 on success or -1 on error.
12099 This function depends on the feature "ntfs3g". See also
12101 "guestfs_feature_available".
12102 (Added in 1.17.9)
12104 guestfs_ntfsfix_va
12106 int
12107 guestfs_ntfsfix_va (guestfs_h *g,
12108 const char *device,
12109 va_list args);
12110 This is the "va_list variant" of "guestfs_ntfsfix".
12112 See "CALLS WITH OPTIONAL ARGUMENTS".
12114 guestfs_ntfsfix_argv
12116 int
12117 guestfs_ntfsfix_argv (guestfs_h *g,
12118 const char *device,
12119 const struct guestfs_ntfsfix_argv *optargs);
12120 This is the "argv variant" of "guestfs_ntfsfix".
12122 See "CALLS WITH OPTIONAL ARGUMENTS".
12124 guestfs_ntfsresize
12126 int
12127 guestfs_ntfsresize (guestfs_h *g,
12128 const char *device);
12129 This function is provided for backwards compatibility with earlier
12131 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
12132 no optional arguments.
12133 (Added in 1.3.2)
12135 guestfs_ntfsresize_opts
12137 int
12138 guestfs_ntfsresize_opts (guestfs_h *g,
12139 const char *device,
12140 ...);
12141 You may supply a list of optional arguments to this call. Use zero or
12143 more of the following pairs of parameters, and terminate the list with
12144 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12145 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12147 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12148 This command resizes an NTFS filesystem, expanding or shrinking it to
12150 the size of the underlying device.
12151 The optional parameters are:
12153 "size"
12155 The new size (in bytes) of the filesystem. If omitted, the
12156 filesystem is resized to fit the container (eg. partition).
12157 "force"
12159 If this option is true, then force the resize of the filesystem
12160 even if the filesystem is marked as requiring a consistency check.
12161 After the resize operation, the filesystem is always marked as
12163 requiring a consistency check (for safety). You have to boot into
12164 Windows to perform this check and clear this condition. If you
12165 don't set the "force" option then it is not possible to call
12166 "guestfs_ntfsresize" multiple times on a single filesystem without
12167 booting into Windows between each resize.
12168 See also ntfsresize(8).
12170 This function returns 0 on success or -1 on error.
12172 This function depends on the feature "ntfsprogs". See also
12174 "guestfs_feature_available".
12175 (Added in 1.3.2)
12177 guestfs_ntfsresize_opts_va
12179 int
12180 guestfs_ntfsresize_opts_va (guestfs_h *g,
12181 const char *device,
12182 va_list args);
12183 This is the "va_list variant" of "guestfs_ntfsresize_opts".
12185 See "CALLS WITH OPTIONAL ARGUMENTS".
12187 guestfs_ntfsresize_opts_argv
12189 int
12190 guestfs_ntfsresize_opts_argv (guestfs_h *g,
12191 const char *device,
12192 const struct guestfs_ntfsresize_opts_argv *optargs);
12193 This is the "argv variant" of "guestfs_ntfsresize_opts".
12195 See "CALLS WITH OPTIONAL ARGUMENTS".
12197 guestfs_ntfsresize_size
12199 int
12200 guestfs_ntfsresize_size (guestfs_h *g,
12201 const char *device,
12202 int64_t size);
12203 This function is deprecated. In new code, use the "guestfs_ntfsresize"
12205 call instead.
12206 Deprecated functions will not be removed from the API, but the fact
12208 that they are deprecated indicates that there are problems with correct
12209 use of these functions.
12210 This command is the same as "guestfs_ntfsresize" except that it allows
12212 you to specify the new size (in bytes) explicitly.
12213 This function returns 0 on success or -1 on error.
12215 This function depends on the feature "ntfsprogs". See also
12217 "guestfs_feature_available".
12218 (Added in 1.3.14)
12220 guestfs_parse_environment
12222 int
12223 guestfs_parse_environment (guestfs_h *g);
12224 Parse the program’s environment and set flags in the handle
12226 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12227 flag is set in the handle.
12228 Most programs do not need to call this. It is done implicitly when you
12230 call "guestfs_create".
12231 See "ENVIRONMENT VARIABLES" for a list of environment variables that
12233 can affect libguestfs handles. See also "guestfs_create_flags", and
12234 "guestfs_parse_environment_list".
12235 This function returns 0 on success or -1 on error.
12237 (Added in 1.19.53)
12239 guestfs_parse_environment_list
12241 int
12242 guestfs_parse_environment_list (guestfs_h *g,
12243 char *const *environment);
12244 Parse the list of strings in the argument "environment" and set flags
12246 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
12247 string in the list, then the ‘verbose’ flag is set in the handle.
12248 This is the same as "guestfs_parse_environment" except that it parses
12250 an explicit list of strings instead of the program's environment.
12251 This function returns 0 on success or -1 on error.
12253 (Added in 1.19.53)
12255 guestfs_part_add
12257 int
12258 guestfs_part_add (guestfs_h *g,
12259 const char *device,
12260 const char *prlogex,
12261 int64_t startsect,
12262 int64_t endsect);
12263 This command adds a partition to "device". If there is no partition
12265 table on the device, call "guestfs_part_init" first.
12266 The "prlogex" parameter is the type of partition. Normally you should
12268 pass "p" or "primary" here, but MBR partition tables also support "l"
12269 (or "logical") and "e" (or "extended") partition types.
12270 "startsect" and "endsect" are the start and end of the partition in
12272 sectors. "endsect" may be negative, which means it counts backwards
12273 from the end of the disk ("-1" is the last sector).
12274 Creating a partition which covers the whole disk is not so easy. Use
12276 "guestfs_part_disk" to do that.
12277 This function returns 0 on success or -1 on error.
12279 (Added in 1.0.78)
12281 guestfs_part_del
12283 int
12284 guestfs_part_del (guestfs_h *g,
12285 const char *device,
12286 int partnum);
12287 This command deletes the partition numbered "partnum" on "device".
12289 Note that in the case of MBR partitioning, deleting an extended
12291 partition also deletes any logical partitions it contains.
12292 This function returns 0 on success or -1 on error.
12294 (Added in 1.3.2)
12296 guestfs_part_disk
12298 int
12299 guestfs_part_disk (guestfs_h *g,
12300 const char *device,
12301 const char *parttype);
12302 This command is simply a combination of "guestfs_part_init" followed by
12304 "guestfs_part_add" to create a single primary partition covering the
12305 whole disk.
12306 "parttype" is the partition table type, usually "mbr" or "gpt", but
12308 other possible values are described in "guestfs_part_init".
12309 This function returns 0 on success or -1 on error.
12311 (Added in 1.0.78)
12313 guestfs_part_expand_gpt
12315 int
12316 guestfs_part_expand_gpt (guestfs_h *g,
12317 const char *device);
12318 Move backup GPT data structures to the end of the disk. This is useful
12320 in case of in-place image expand since disk space after backup GPT
12321 header is not usable. This is equivalent to "sgdisk -e".
12322 See also sgdisk(8).
12324 This function returns 0 on success or -1 on error.
12326 This function depends on the feature "gdisk". See also
12328 "guestfs_feature_available".
12329 (Added in 1.33.2)
12331 guestfs_part_get_bootable
12333 int
12334 guestfs_part_get_bootable (guestfs_h *g,
12335 const char *device,
12336 int partnum);
12337 This command returns true if the partition "partnum" on "device" has
12339 the bootable flag set.
12340 See also "guestfs_part_set_bootable".
12342 This function returns a C truth value on success or -1 on error.
12344 (Added in 1.3.2)
12346 guestfs_part_get_disk_guid
12348 char *
12349 guestfs_part_get_disk_guid (guestfs_h *g,
12350 const char *device);
12351 Return the disk identifier (GUID) of a GPT-partitioned "device".
12353 Behaviour is undefined for other partition types.
12354 This function returns a string, or NULL on error. The caller must free
12356 the returned string after use.
12357 This function depends on the feature "gdisk". See also
12359 "guestfs_feature_available".
12360 (Added in 1.33.2)
12362 guestfs_part_get_gpt_attributes
12364 int64_t
12365 guestfs_part_get_gpt_attributes (guestfs_h *g,
12366 const char *device,
12367 int partnum);
12368 Return the attribute flags of numbered GPT partition "partnum". An
12370 error is returned for MBR partitions.
12371 On error this function returns -1.
12373 This function depends on the feature "gdisk". See also
12375 "guestfs_feature_available".
12376 (Added in 1.21.1)
12378 guestfs_part_get_gpt_guid
12380 char *
12381 guestfs_part_get_gpt_guid (guestfs_h *g,
12382 const char *device,
12383 int partnum);
12384 Return the GUID of numbered GPT partition "partnum".
12386 This function returns a string, or NULL on error. The caller must free
12388 the returned string after use.
12389 This function depends on the feature "gdisk". See also
12391 "guestfs_feature_available".
12392 (Added in 1.29.25)
12394 guestfs_part_get_gpt_type
12396 char *
12397 guestfs_part_get_gpt_type (guestfs_h *g,
12398 const char *device,
12399 int partnum);
12400 Return the type GUID of numbered GPT partition "partnum". For MBR
12402 partitions, return an appropriate GUID corresponding to the MBR type.
12403 Behaviour is undefined for other partition types.
12404 This function returns a string, or NULL on error. The caller must free
12406 the returned string after use.
12407 This function depends on the feature "gdisk". See also
12409 "guestfs_feature_available".
12410 (Added in 1.21.1)
12412 guestfs_part_get_mbr_id
12414 int
12415 guestfs_part_get_mbr_id (guestfs_h *g,
12416 const char *device,
12417 int partnum);
12418 Returns the MBR type byte (also known as the ID byte) from the numbered
12420 partition "partnum".
12421 Note that only MBR (old DOS-style) partitions have type bytes. You
12423 will get undefined results for other partition table types (see
12424 "guestfs_part_get_parttype").
12425 On error this function returns -1.
12427 (Added in 1.3.2)
12429 guestfs_part_get_mbr_part_type
12431 char *
12432 guestfs_part_get_mbr_part_type (guestfs_h *g,
12433 const char *device,
12434 int partnum);
12435 This returns the partition type of an MBR partition numbered "partnum"
12437 on device "device".
12438 It returns "primary", "logical", or "extended".
12440 This function returns a string, or NULL on error. The caller must free
12442 the returned string after use.
12443 (Added in 1.29.32)
12445 guestfs_part_get_name
12447 char *
12448 guestfs_part_get_name (guestfs_h *g,
12449 const char *device,
12450 int partnum);
12451 This gets the partition name on partition numbered "partnum" on device
12453 "device". Note that partitions are numbered from 1.
12454 The partition name can only be read on certain types of partition
12456 table. This works on "gpt" but not on "mbr" partitions.
12457 This function returns a string, or NULL on error. The caller must free
12459 the returned string after use.
12460 (Added in 1.25.33)
12462 guestfs_part_get_parttype
12464 char *
12465 guestfs_part_get_parttype (guestfs_h *g,
12466 const char *device);
12467 This command examines the partition table on "device" and returns the
12469 partition table type (format) being used.
12470 Common return values include: "msdos" (a DOS/Windows style MBR
12472 partition table), "gpt" (a GPT/EFI-style partition table). Other
12473 values are possible, although unusual. See "guestfs_part_init" for a
12474 full list.
12475 This function returns a string, or NULL on error. The caller must free
12477 the returned string after use.
12478 (Added in 1.0.78)
12480 guestfs_part_init
12482 int
12483 guestfs_part_init (guestfs_h *g,
12484 const char *device,
12485 const char *parttype);
12486 This creates an empty partition table on "device" of one of the
12488 partition types listed below. Usually "parttype" should be either
12489 "msdos" or "gpt" (for large disks).
12490 Initially there are no partitions. Following this, you should call
12492 "guestfs_part_add" for each partition required.
12493 Possible values for "parttype" are:
12495 "efi"
12497 "gpt"
12498 Intel EFI / GPT partition table.
12499 This is recommended for >= 2 TB partitions that will be accessed
12501 from Linux and Intel-based Mac OS X. It also has limited backwards
12502 compatibility with the "mbr" format.
12503 "mbr"
12505 "msdos"
12506 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12507 and Windows. This partition type will only work for device sizes
12508 up to 2 TB. For large disks we recommend using "gpt".
12509 Other partition table types that may work but are not supported
12511 include:
12512 "aix"
12514 AIX disk labels.
12515 "amiga"
12517 "rdb"
12518 Amiga "Rigid Disk Block" format.
12519 "bsd"
12521 BSD disk labels.
12522 "dasd"
12524 DASD, used on IBM mainframes.
12525 "dvh"
12527 MIPS/SGI volumes.
12528 "mac"
12530 Old Mac partition format. Modern Macs use "gpt".
12531 "pc98"
12533 NEC PC-98 format, common in Japan apparently.
12534 "sun"
12536 Sun disk labels.
12537 This function returns 0 on success or -1 on error.
12539 (Added in 1.0.78)
12541 guestfs_part_list
12543 struct guestfs_partition_list *
12544 guestfs_part_list (guestfs_h *g,
12545 const char *device);
12546 This command parses the partition table on "device" and returns the
12548 list of partitions found.
12549 The fields in the returned structure are:
12551 "part_num"
12553 Partition number, counting from 1.
12554 "part_start"
12556 Start of the partition in bytes. To get sectors you have to divide
12557 by the device’s sector size, see "guestfs_blockdev_getss".
12558 "part_end"
12560 End of the partition in bytes.
12561 "part_size"
12563 Size of the partition in bytes.
12564 This function returns a "struct guestfs_partition_list *", or NULL if
12566 there was an error. The caller must call "guestfs_free_partition_list"
12567 after use.
12568 (Added in 1.0.78)
12570 guestfs_part_resize
12572 int
12573 guestfs_part_resize (guestfs_h *g,
12574 const char *device,
12575 int partnum,
12576 int64_t endsect);
12577 This command resizes the partition numbered "partnum" on "device" by
12579 moving the end position.
12580 Note that this does not modify any filesystem present in the partition.
12582 If you wish to do this, you will need to use filesystem resizing
12583 commands like "guestfs_resize2fs".
12584 When growing a partition you will want to grow the filesystem
12586 afterwards, but when shrinking, you need to shrink the filesystem
12587 before the partition.
12588 This function returns 0 on success or -1 on error.
12590 (Added in 1.37.20)
12592 guestfs_part_set_bootable
12594 int
12595 guestfs_part_set_bootable (guestfs_h *g,
12596 const char *device,
12597 int partnum,
12598 int bootable);
12599 This sets the bootable flag on partition numbered "partnum" on device
12601 "device". Note that partitions are numbered from 1.
12602 The bootable flag is used by some operating systems (notably Windows)
12604 to determine which partition to boot from. It is by no means
12605 universally recognized.
12606 This function returns 0 on success or -1 on error.
12608 (Added in 1.0.78)
12610 guestfs_part_set_disk_guid
12612 int
12613 guestfs_part_set_disk_guid (guestfs_h *g,
12614 const char *device,
12615 const char *guid);
12616 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12618 Return an error if the partition table of "device" isn't GPT, or if
12619 "guid" is not a valid GUID.
12620 This function returns 0 on success or -1 on error.
12622 This function depends on the feature "gdisk". See also
12624 "guestfs_feature_available".
12625 (Added in 1.33.2)
12627 guestfs_part_set_disk_guid_random
12629 int
12630 guestfs_part_set_disk_guid_random (guestfs_h *g,
12631 const char *device);
12632 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12634 randomly generated value. Return an error if the partition table of
12635 "device" isn't GPT.
12636 This function returns 0 on success or -1 on error.
12638 This function depends on the feature "gdisk". See also
12640 "guestfs_feature_available".
12641 (Added in 1.33.2)
12643 guestfs_part_set_gpt_attributes
12645 int
12646 guestfs_part_set_gpt_attributes (guestfs_h *g,
12647 const char *device,
12648 int partnum,
12649 int64_t attributes);
12650 Set the attribute flags of numbered GPT partition "partnum" to
12652 "attributes". Return an error if the partition table of "device" isn't
12653 GPT.
12654 See
12656 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12657 for a useful list of partition attributes.
12658 This function returns 0 on success or -1 on error.
12660 This function depends on the feature "gdisk". See also
12662 "guestfs_feature_available".
12663 (Added in 1.21.1)
12665 guestfs_part_set_gpt_guid
12667 int
12668 guestfs_part_set_gpt_guid (guestfs_h *g,
12669 const char *device,
12670 int partnum,
12671 const char *guid);
12672 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12674 error if the partition table of "device" isn't GPT, or if "guid" is not
12675 a valid GUID.
12676 This function returns 0 on success or -1 on error.
12678 This function depends on the feature "gdisk". See also
12680 "guestfs_feature_available".
12681 (Added in 1.29.25)
12683 guestfs_part_set_gpt_type
12685 int
12686 guestfs_part_set_gpt_type (guestfs_h *g,
12687 const char *device,
12688 int partnum,
12689 const char *guid);
12690 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12692 an error if the partition table of "device" isn't GPT, or if "guid" is
12693 not a valid GUID.
12694 See
12696 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12697 for a useful list of type GUIDs.
12698 This function returns 0 on success or -1 on error.
12700 This function depends on the feature "gdisk". See also
12702 "guestfs_feature_available".
12703 (Added in 1.21.1)
12705 guestfs_part_set_mbr_id
12707 int
12708 guestfs_part_set_mbr_id (guestfs_h *g,
12709 const char *device,
12710 int partnum,
12711 int idbyte);
12712 Sets the MBR type byte (also known as the ID byte) of the numbered
12714 partition "partnum" to "idbyte". Note that the type bytes quoted in
12715 most documentation are in fact hexadecimal numbers, but usually
12716 documented without any leading "0x" which might be confusing.
12717 Note that only MBR (old DOS-style) partitions have type bytes. You
12719 will get undefined results for other partition table types (see
12720 "guestfs_part_get_parttype").
12721 This function returns 0 on success or -1 on error.
12723 (Added in 1.3.2)
12725 guestfs_part_set_name
12727 int
12728 guestfs_part_set_name (guestfs_h *g,
12729 const char *device,
12730 int partnum,
12731 const char *name);
12732 This sets the partition name on partition numbered "partnum" on device
12734 "device". Note that partitions are numbered from 1.
12735 The partition name can only be set on certain types of partition table.
12737 This works on "gpt" but not on "mbr" partitions.
12738 This function returns 0 on success or -1 on error.
12740 (Added in 1.0.78)
12742 guestfs_part_to_dev
12744 char *
12745 guestfs_part_to_dev (guestfs_h *g,
12746 const char *partition);
12747 This function takes a partition name (eg. "/dev/sdb1") and removes the
12749 partition number, returning the device name (eg. "/dev/sdb").
12750 The named partition must exist, for example as a string returned from
12752 "guestfs_list_partitions".
12753 See also "guestfs_part_to_partnum", "guestfs_device_index".
12755 This function returns a string, or NULL on error. The caller must free
12757 the returned string after use.
12758 (Added in 1.5.15)
12760 guestfs_part_to_partnum
12762 int
12763 guestfs_part_to_partnum (guestfs_h *g,
12764 const char *partition);
12765 This function takes a partition name (eg. "/dev/sdb1") and returns the
12767 partition number (eg. 1).
12768 The named partition must exist, for example as a string returned from
12770 "guestfs_list_partitions".
12771 See also "guestfs_part_to_dev".
12773 On error this function returns -1.
12775 (Added in 1.13.25)
12777 guestfs_ping_daemon
12779 int
12780 guestfs_ping_daemon (guestfs_h *g);
12781 This is a test probe into the guestfs daemon running inside the
12783 libguestfs appliance. Calling this function checks that the daemon
12784 responds to the ping message, without affecting the daemon or attached
12785 block device(s) in any other way.
12786 This function returns 0 on success or -1 on error.
12788 (Added in 1.0.18)
12790 guestfs_pread
12792 char *
12793 guestfs_pread (guestfs_h *g,
12794 const char *path,
12795 int count,
12796 int64_t offset,
12797 size_t *size_r);
12798 This command lets you read part of a file. It reads "count" bytes of
12800 the file, starting at "offset", from file "path".
12801 This may read fewer bytes than requested. For further details see the
12803 pread(2) system call.
12804 See also "guestfs_pwrite", "guestfs_pread_device".
12806 This function returns a buffer, or NULL on error. The size of the
12808 returned buffer is written to *size_r. The caller must free the
12809 returned buffer after use.
12810 Because of the message protocol, there is a transfer limit of somewhere
12812 between 2MB and 4MB. See "PROTOCOL LIMITS".
12813 (Added in 1.0.77)
12815 guestfs_pread_device
12817 char *
12818 guestfs_pread_device (guestfs_h *g,
12819 const char *device,
12820 int count,
12821 int64_t offset,
12822 size_t *size_r);
12823 This command lets you read part of a block device. It reads "count"
12825 bytes of "device", starting at "offset".
12826 This may read fewer bytes than requested. For further details see the
12828 pread(2) system call.
12829 See also "guestfs_pread".
12831 This function returns a buffer, or NULL on error. The size of the
12833 returned buffer is written to *size_r. The caller must free the
12834 returned buffer after use.
12835 Because of the message protocol, there is a transfer limit of somewhere
12837 between 2MB and 4MB. See "PROTOCOL LIMITS".
12838 (Added in 1.5.21)
12840 guestfs_pvchange_uuid
12842 int
12843 guestfs_pvchange_uuid (guestfs_h *g,
12844 const char *device);
12845 Generate a new random UUID for the physical volume "device".
12847 This function returns 0 on success or -1 on error.
12849 This function depends on the feature "lvm2". See also
12851 "guestfs_feature_available".
12852 (Added in 1.19.26)
12854 guestfs_pvchange_uuid_all
12856 int
12857 guestfs_pvchange_uuid_all (guestfs_h *g);
12858 Generate new random UUIDs for all physical volumes.
12860 This function returns 0 on success or -1 on error.
12862 This function depends on the feature "lvm2". See also
12864 "guestfs_feature_available".
12865 (Added in 1.19.26)
12867 guestfs_pvcreate
12869 int
12870 guestfs_pvcreate (guestfs_h *g,
12871 const char *device);
12872 This creates an LVM physical volume on the named "device", where
12874 "device" should usually be a partition name such as /dev/sda1.
12875 This function returns 0 on success or -1 on error.
12877 This function depends on the feature "lvm2". See also
12879 "guestfs_feature_available".
12880 (Added in 0.8)
12882 guestfs_pvremove
12884 int
12885 guestfs_pvremove (guestfs_h *g,
12886 const char *device);
12887 This wipes a physical volume "device" so that LVM will no longer
12889 recognise it.
12890 The implementation uses the pvremove(8) command which refuses to wipe
12892 physical volumes that contain any volume groups, so you have to remove
12893 those first.
12894 This function returns 0 on success or -1 on error.
12896 This function depends on the feature "lvm2". See also
12898 "guestfs_feature_available".
12899 (Added in 1.0.13)
12901 guestfs_pvresize
12903 int
12904 guestfs_pvresize (guestfs_h *g,
12905 const char *device);
12906 This resizes (expands or shrinks) an existing LVM physical volume to
12908 match the new size of the underlying device.
12909 This function returns 0 on success or -1 on error.
12911 This function depends on the feature "lvm2". See also
12913 "guestfs_feature_available".
12914 (Added in 1.0.26)
12916 guestfs_pvresize_size
12918 int
12919 guestfs_pvresize_size (guestfs_h *g,
12920 const char *device,
12921 int64_t size);
12922 This command is the same as "guestfs_pvresize" except that it allows
12924 you to specify the new size (in bytes) explicitly.
12925 This function returns 0 on success or -1 on error.
12927 This function depends on the feature "lvm2". See also
12929 "guestfs_feature_available".
12930 (Added in 1.3.14)
12932 guestfs_pvs
12934 char **
12935 guestfs_pvs (guestfs_h *g);
12936 List all the physical volumes detected. This is the equivalent of the
12938 pvs(8) command.
12939 This returns a list of just the device names that contain PVs (eg.
12941 /dev/sda2).
12942 See also "guestfs_pvs_full".
12944 This function returns a NULL-terminated array of strings (like
12946 environ(3)), or NULL if there was an error. The caller must free the
12947 strings and the array after use.
12948 This function depends on the feature "lvm2". See also
12950 "guestfs_feature_available".
12951 (Added in 0.4)
12953 guestfs_pvs_full
12955 struct guestfs_lvm_pv_list *
12956 guestfs_pvs_full (guestfs_h *g);
12957 List all the physical volumes detected. This is the equivalent of the
12959 pvs(8) command. The "full" version includes all fields.
12960 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
12962 there was an error. The caller must call "guestfs_free_lvm_pv_list"
12963 after use.
12964 This function depends on the feature "lvm2". See also
12966 "guestfs_feature_available".
12967 (Added in 0.4)
12969 guestfs_pvuuid
12971 char *
12972 guestfs_pvuuid (guestfs_h *g,
12973 const char *device);
12974 This command returns the UUID of the LVM PV "device".
12976 This function returns a string, or NULL on error. The caller must free
12978 the returned string after use.
12979 (Added in 1.0.87)
12981 guestfs_pwrite
12983 int
12984 guestfs_pwrite (guestfs_h *g,
12985 const char *path,
12986 const char *content,
12987 size_t content_size,
12988 int64_t offset);
12989 This command writes to part of a file. It writes the data buffer
12991 "content" to the file "path" starting at offset "offset".
12992 This command implements the pwrite(2) system call, and like that system
12994 call it may not write the full data requested. The return value is the
12995 number of bytes that were actually written to the file. This could
12996 even be 0, although short writes are unlikely for regular files in
12997 ordinary circumstances.
12998 See also "guestfs_pread", "guestfs_pwrite_device".
13000 On error this function returns -1.
13002 Because of the message protocol, there is a transfer limit of somewhere
13004 between 2MB and 4MB. See "PROTOCOL LIMITS".
13005 (Added in 1.3.14)
13007 guestfs_pwrite_device
13009 int
13010 guestfs_pwrite_device (guestfs_h *g,
13011 const char *device,
13012 const char *content,
13013 size_t content_size,
13014 int64_t offset);
13015 This command writes to part of a device. It writes the data buffer
13017 "content" to "device" starting at offset "offset".
13018 This command implements the pwrite(2) system call, and like that system
13020 call it may not write the full data requested (although short writes to
13021 disk devices and partitions are probably impossible with standard Linux
13022 kernels).
13023 See also "guestfs_pwrite".
13025 On error this function returns -1.
13027 Because of the message protocol, there is a transfer limit of somewhere
13029 between 2MB and 4MB. See "PROTOCOL LIMITS".
13030 (Added in 1.5.20)
13032 guestfs_read_file
13034 char *
13035 guestfs_read_file (guestfs_h *g,
13036 const char *path,
13037 size_t *size_r);
13038 This calls returns the contents of the file "path" as a buffer.
13040 Unlike "guestfs_cat", this function can correctly handle files that
13042 contain embedded ASCII NUL characters.
13043 This function returns a buffer, or NULL on error. The size of the
13045 returned buffer is written to *size_r. The caller must free the
13046 returned buffer after use.
13047 (Added in 1.0.63)
13049 guestfs_read_lines
13051 char **
13052 guestfs_read_lines (guestfs_h *g,
13053 const char *path);
13054 Return the contents of the file named "path".
13056 The file contents are returned as a list of lines. Trailing "LF" and
13058 "CRLF" character sequences are not returned.
13059 Note that this function cannot correctly handle binary files
13061 (specifically, files containing "\0" character which is treated as end
13062 of string). For those you need to use the "guestfs_read_file" function
13063 and split the buffer into lines yourself.
13064 This function returns a NULL-terminated array of strings (like
13066 environ(3)), or NULL if there was an error. The caller must free the
13067 strings and the array after use.
13068 (Added in 0.7)
13070 guestfs_readdir
13072 struct guestfs_dirent_list *
13073 guestfs_readdir (guestfs_h *g,
13074 const char *dir);
13075 This returns the list of directory entries in directory "dir".
13077 All entries in the directory are returned, including "." and "..". The
13079 entries are not sorted, but returned in the same order as the
13080 underlying filesystem.
13081 Also this call returns basic file type information about each file.
13083 The "ftyp" field will contain one of the following characters:
13084 'b' Block special
13086 'c' Char special
13088 'd' Directory
13090 'f' FIFO (named pipe)
13092 'l' Symbolic link
13094 'r' Regular file
13096 's' Socket
13098 'u' Unknown file type
13100 '?' The readdir(3) call returned a "d_type" field with an unexpected
13102 value
13103 This function is primarily intended for use by programs. To get a
13105 simple list of names, use "guestfs_ls". To get a printable directory
13106 for human consumption, use "guestfs_ll".
13107 This function returns a "struct guestfs_dirent_list *", or NULL if
13109 there was an error. The caller must call "guestfs_free_dirent_list"
13110 after use.
13111 This long-running command can generate progress notification messages
13113 so that the caller can display a progress bar or indicator. To receive
13114 these messages, the caller must register a progress event callback.
13115 See "GUESTFS_EVENT_PROGRESS".
13116 (Added in 1.0.55)
13118 guestfs_readlink
13120 char *
13121 guestfs_readlink (guestfs_h *g,
13122 const char *path);
13123 This command reads the target of a symbolic link.
13125 This function returns a string, or NULL on error. The caller must free
13127 the returned string after use.
13128 (Added in 1.0.66)
13130 guestfs_readlinklist
13132 char **
13133 guestfs_readlinklist (guestfs_h *g,
13134 const char *path,
13135 char *const *names);
13136 This call allows you to do a "readlink" operation on multiple files,
13138 where all files are in the directory "path". "names" is the list of
13139 files from this directory.
13140 On return you get a list of strings, with a one-to-one correspondence
13142 to the "names" list. Each string is the value of the symbolic link.
13143 If the readlink(2) operation fails on any name, then the corresponding
13145 result string is the empty string "". However the whole operation is
13146 completed even if there were readlink(2) errors, and so you can call
13147 this function with names where you don't know if they are symbolic
13148 links already (albeit slightly less efficient).
13149 This call is intended for programs that want to efficiently list a
13151 directory contents without making many round-trips.
13152 This function returns a NULL-terminated array of strings (like
13154 environ(3)), or NULL if there was an error. The caller must free the
13155 strings and the array after use.
13156 (Added in 1.0.77)
13158 guestfs_realpath
13160 char *
13161 guestfs_realpath (guestfs_h *g,
13162 const char *path);
13163 Return the canonicalized absolute pathname of "path". The returned
13165 path has no ".", ".." or symbolic link path elements.
13166 This function returns a string, or NULL on error. The caller must free
13168 the returned string after use.
13169 (Added in 1.0.66)
13171 guestfs_remount
13173 int
13174 guestfs_remount (guestfs_h *g,
13175 const char *mountpoint,
13176 ...);
13177 You may supply a list of optional arguments to this call. Use zero or
13179 more of the following pairs of parameters, and terminate the list with
13180 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13181 GUESTFS_REMOUNT_RW, int rw,
13183 This call allows you to change the "rw" (readonly/read-write) flag on
13185 an already mounted filesystem at "mountpoint", converting a readonly
13186 filesystem to be read-write, or vice-versa.
13187 Note that at the moment you must supply the "optional" "rw" parameter.
13189 In future we may allow other flags to be adjusted.
13190 This function returns 0 on success or -1 on error.
13192 (Added in 1.23.2)
13194 guestfs_remount_va
13196 int
13197 guestfs_remount_va (guestfs_h *g,
13198 const char *mountpoint,
13199 va_list args);
13200 This is the "va_list variant" of "guestfs_remount".
13202 See "CALLS WITH OPTIONAL ARGUMENTS".
13204 guestfs_remount_argv
13206 int
13207 guestfs_remount_argv (guestfs_h *g,
13208 const char *mountpoint,
13209 const struct guestfs_remount_argv *optargs);
13210 This is the "argv variant" of "guestfs_remount".
13212 See "CALLS WITH OPTIONAL ARGUMENTS".
13214 guestfs_remove_drive
13216 int
13217 guestfs_remove_drive (guestfs_h *g,
13218 const char *label);
13219 This function is deprecated. There is no replacement. Consult the API
13221 documentation in guestfs(3) for further information.
13222 Deprecated functions will not be removed from the API, but the fact
13224 that they are deprecated indicates that there are problems with correct
13225 use of these functions.
13226 This call does nothing and returns an error.
13228 This function returns 0 on success or -1 on error.
13230 (Added in 1.19.49)
13232 guestfs_removexattr
13234 int
13235 guestfs_removexattr (guestfs_h *g,
13236 const char *xattr,
13237 const char *path);
13238 This call removes the extended attribute named "xattr" of the file
13240 "path".
13241 See also: "guestfs_lremovexattr", attr(5).
13243 This function returns 0 on success or -1 on error.
13245 This function depends on the feature "linuxxattrs". See also
13247 "guestfs_feature_available".
13248 (Added in 1.0.59)
13250 guestfs_rename
13252 int
13253 guestfs_rename (guestfs_h *g,
13254 const char *oldpath,
13255 const char *newpath);
13256 Rename a file to a new place on the same filesystem. This is the same
13258 as the Linux rename(2) system call. In most cases you are better to
13259 use "guestfs_mv" instead.
13260 This function returns 0 on success or -1 on error.
13262 (Added in 1.21.5)
13264 guestfs_resize2fs
13266 int
13267 guestfs_resize2fs (guestfs_h *g,
13268 const char *device);
13269 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13271 underlying device.
13272 See also "RESIZE2FS ERRORS".
13274 This function returns 0 on success or -1 on error.
13276 (Added in 1.0.27)
13278 guestfs_resize2fs_M
13280 int
13281 guestfs_resize2fs_M (guestfs_h *g,
13282 const char *device);
13283 This command is the same as "guestfs_resize2fs", but the filesystem is
13285 resized to its minimum size. This works like the -M option to the
13286 resize2fs(8) command.
13287 To get the resulting size of the filesystem you should call
13289 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13290 These two numbers, multiplied together, give the resulting size of the
13291 minimal filesystem in bytes.
13292 See also "RESIZE2FS ERRORS".
13294 This function returns 0 on success or -1 on error.
13296 (Added in 1.9.4)
13298 guestfs_resize2fs_size
13300 int
13301 guestfs_resize2fs_size (guestfs_h *g,
13302 const char *device,
13303 int64_t size);
13304 This command is the same as "guestfs_resize2fs" except that it allows
13306 you to specify the new size (in bytes) explicitly.
13307 See also "RESIZE2FS ERRORS".
13309 This function returns 0 on success or -1 on error.
13311 (Added in 1.3.14)
13313 guestfs_rm
13315 int
13316 guestfs_rm (guestfs_h *g,
13317 const char *path);
13318 Remove the single file "path".
13320 This function returns 0 on success or -1 on error.
13322 (Added in 0.8)
13324 guestfs_rm_f
13326 int
13327 guestfs_rm_f (guestfs_h *g,
13328 const char *path);
13329 Remove the file "path".
13331 If the file doesn't exist, that error is ignored. (Other errors, eg.
13333 I/O errors or bad paths, are not ignored)
13334 This call cannot remove directories. Use "guestfs_rmdir" to remove an
13336 empty directory, or "guestfs_rm_rf" to remove directories recursively.
13337 This function returns 0 on success or -1 on error.
13339 (Added in 1.19.42)
13341 guestfs_rm_rf
13343 int
13344 guestfs_rm_rf (guestfs_h *g,
13345 const char *path);
13346 Remove the file or directory "path", recursively removing the contents
13348 if its a directory. This is like the "rm -rf" shell command.
13349 This function returns 0 on success or -1 on error.
13351 (Added in 0.8)
13353 guestfs_rmdir
13355 int
13356 guestfs_rmdir (guestfs_h *g,
13357 const char *path);
13358 Remove the single directory "path".
13360 This function returns 0 on success or -1 on error.
13362 (Added in 0.8)
13364 guestfs_rmmountpoint
13366 int
13367 guestfs_rmmountpoint (guestfs_h *g,
13368 const char *exemptpath);
13369 This call removes a mountpoint that was previously created with
13371 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13372 This function returns 0 on success or -1 on error.
13374 (Added in 1.0.62)
13376 guestfs_rsync
13378 int
13379 guestfs_rsync (guestfs_h *g,
13380 const char *src,
13381 const char *dest,
13382 ...);
13383 You may supply a list of optional arguments to this call. Use zero or
13385 more of the following pairs of parameters, and terminate the list with
13386 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13387 GUESTFS_RSYNC_ARCHIVE, int archive,
13389 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13390 This call may be used to copy or synchronize two directories under the
13392 same libguestfs handle. This uses the rsync(1) program which uses a
13393 fast algorithm that avoids copying files unnecessarily.
13394 "src" and "dest" are the source and destination directories. Files are
13396 copied from "src" to "dest".
13397 The optional arguments are:
13399 "archive"
13401 Turns on archive mode. This is the same as passing the --archive
13402 flag to "rsync".
13403 "deletedest"
13405 Delete files at the destination that do not exist at the source.
13406 This function returns 0 on success or -1 on error.
13408 This function depends on the feature "rsync". See also
13410 "guestfs_feature_available".
13411 (Added in 1.19.29)
13413 guestfs_rsync_va
13415 int
13416 guestfs_rsync_va (guestfs_h *g,
13417 const char *src,
13418 const char *dest,
13419 va_list args);
13420 This is the "va_list variant" of "guestfs_rsync".
13422 See "CALLS WITH OPTIONAL ARGUMENTS".
13424 guestfs_rsync_argv
13426 int
13427 guestfs_rsync_argv (guestfs_h *g,
13428 const char *src,
13429 const char *dest,
13430 const struct guestfs_rsync_argv *optargs);
13431 This is the "argv variant" of "guestfs_rsync".
13433 See "CALLS WITH OPTIONAL ARGUMENTS".
13435 guestfs_rsync_in
13437 int
13438 guestfs_rsync_in (guestfs_h *g,
13439 const char *remote,
13440 const char *dest,
13441 ...);
13442 You may supply a list of optional arguments to this call. Use zero or
13444 more of the following pairs of parameters, and terminate the list with
13445 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13446 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13448 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13449 This call may be used to copy or synchronize the filesystem on the host
13451 or on a remote computer with the filesystem within libguestfs. This
13452 uses the rsync(1) program which uses a fast algorithm that avoids
13453 copying files unnecessarily.
13454 This call only works if the network is enabled. See
13456 "guestfs_set_network" or the --network option to various tools like
13457 guestfish(1).
13458 Files are copied from the remote server and directory specified by
13460 "remote" to the destination directory "dest".
13461 The format of the remote server string is defined by rsync(1). Note
13463 that there is no way to supply a password or passphrase so the target
13464 must be set up not to require one.
13465 The optional arguments are the same as those of "guestfs_rsync".
13467 This function returns 0 on success or -1 on error.
13469 This function depends on the feature "rsync". See also
13471 "guestfs_feature_available".
13472 (Added in 1.19.29)
13474 guestfs_rsync_in_va
13476 int
13477 guestfs_rsync_in_va (guestfs_h *g,
13478 const char *remote,
13479 const char *dest,
13480 va_list args);
13481 This is the "va_list variant" of "guestfs_rsync_in".
13483 See "CALLS WITH OPTIONAL ARGUMENTS".
13485 guestfs_rsync_in_argv
13487 int
13488 guestfs_rsync_in_argv (guestfs_h *g,
13489 const char *remote,
13490 const char *dest,
13491 const struct guestfs_rsync_in_argv *optargs);
13492 This is the "argv variant" of "guestfs_rsync_in".
13494 See "CALLS WITH OPTIONAL ARGUMENTS".
13496 guestfs_rsync_out
13498 int
13499 guestfs_rsync_out (guestfs_h *g,
13500 const char *src,
13501 const char *remote,
13502 ...);
13503 You may supply a list of optional arguments to this call. Use zero or
13505 more of the following pairs of parameters, and terminate the list with
13506 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13507 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13509 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13510 This call may be used to copy or synchronize the filesystem within
13512 libguestfs with a filesystem on the host or on a remote computer. This
13513 uses the rsync(1) program which uses a fast algorithm that avoids
13514 copying files unnecessarily.
13515 This call only works if the network is enabled. See
13517 "guestfs_set_network" or the --network option to various tools like
13518 guestfish(1).
13519 Files are copied from the source directory "src" to the remote server
13521 and directory specified by "remote".
13522 The format of the remote server string is defined by rsync(1). Note
13524 that there is no way to supply a password or passphrase so the target
13525 must be set up not to require one.
13526 The optional arguments are the same as those of "guestfs_rsync".
13528 Globbing does not happen on the "src" parameter. In programs which use
13530 the API directly you have to expand wildcards yourself (see
13531 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13532 (see "glob" in guestfish(1)), for example:
13533 ><fs> glob rsync-out /* rsync://remote/
13535 This function returns 0 on success or -1 on error.
13537 This function depends on the feature "rsync". See also
13539 "guestfs_feature_available".
13540 (Added in 1.19.29)
13542 guestfs_rsync_out_va
13544 int
13545 guestfs_rsync_out_va (guestfs_h *g,
13546 const char *src,
13547 const char *remote,
13548 va_list args);
13549 This is the "va_list variant" of "guestfs_rsync_out".
13551 See "CALLS WITH OPTIONAL ARGUMENTS".
13553 guestfs_rsync_out_argv
13555 int
13556 guestfs_rsync_out_argv (guestfs_h *g,
13557 const char *src,
13558 const char *remote,
13559 const struct guestfs_rsync_out_argv *optargs);
13560 This is the "argv variant" of "guestfs_rsync_out".
13562 See "CALLS WITH OPTIONAL ARGUMENTS".
13564 guestfs_scrub_device
13566 int
13567 guestfs_scrub_device (guestfs_h *g,
13568 const char *device);
13569 This command writes patterns over "device" to make data retrieval more
13571 difficult.
13572 It is an interface to the scrub(1) program. See that manual page for
13574 more details.
13575 This function returns 0 on success or -1 on error.
13577 This function depends on the feature "scrub". See also
13579 "guestfs_feature_available".
13580 (Added in 1.0.52)
13582 guestfs_scrub_file
13584 int
13585 guestfs_scrub_file (guestfs_h *g,
13586 const char *file);
13587 This command writes patterns over a file to make data retrieval more
13589 difficult.
13590 The file is removed after scrubbing.
13592 It is an interface to the scrub(1) program. See that manual page for
13594 more details.
13595 This function returns 0 on success or -1 on error.
13597 This function depends on the feature "scrub". See also
13599 "guestfs_feature_available".
13600 (Added in 1.0.52)
13602 guestfs_scrub_freespace
13604 int
13605 guestfs_scrub_freespace (guestfs_h *g,
13606 const char *dir);
13607 This command creates the directory "dir" and then fills it with files
13609 until the filesystem is full, and scrubs the files as for
13610 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13611 free space on the partition containing "dir".
13612 It is an interface to the scrub(1) program. See that manual page for
13614 more details.
13615 This function returns 0 on success or -1 on error.
13617 This function depends on the feature "scrub". See also
13619 "guestfs_feature_available".
13620 (Added in 1.0.52)
13622 guestfs_selinux_relabel
13624 int
13625 guestfs_selinux_relabel (guestfs_h *g,
13626 const char *specfile,
13627 const char *path,
13628 ...);
13629 You may supply a list of optional arguments to this call. Use zero or
13631 more of the following pairs of parameters, and terminate the list with
13632 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13633 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13635 SELinux relabel parts of the filesystem.
13637 The "specfile" parameter controls the policy spec file used. You have
13639 to parse "/etc/selinux/config" to find the correct SELinux policy and
13640 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13641 "/contexts/files/file_contexts".
13642 The required "path" parameter is the top level directory where
13644 relabelling starts. Normally you should pass "path" as "/" to relabel
13645 the whole guest filesystem.
13646 The optional "force" boolean controls whether the context is reset for
13648 customizable files, and also whether the user, role and range parts of
13649 the file context is changed.
13650 This function returns 0 on success or -1 on error.
13652 This function depends on the feature "selinuxrelabel". See also
13654 "guestfs_feature_available".
13655 (Added in 1.33.43)
13657 guestfs_selinux_relabel_va
13659 int
13660 guestfs_selinux_relabel_va (guestfs_h *g,
13661 const char *specfile,
13662 const char *path,
13663 va_list args);
13664 This is the "va_list variant" of "guestfs_selinux_relabel".
13666 See "CALLS WITH OPTIONAL ARGUMENTS".
13668 guestfs_selinux_relabel_argv
13670 int
13671 guestfs_selinux_relabel_argv (guestfs_h *g,
13672 const char *specfile,
13673 const char *path,
13674 const struct guestfs_selinux_relabel_argv *optargs);
13675 This is the "argv variant" of "guestfs_selinux_relabel".
13677 See "CALLS WITH OPTIONAL ARGUMENTS".
13679 guestfs_set_append
13681 int
13682 guestfs_set_append (guestfs_h *g,
13683 const char *append);
13684 This function is used to add additional options to the libguestfs
13686 appliance kernel command line.
13687 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13689 environment variable.
13690 Setting "append" to "NULL" means no additional options are passed
13692 (libguestfs always adds a few of its own).
13693 This function returns 0 on success or -1 on error.
13695 (Added in 1.0.26)
13697 guestfs_set_attach_method
13699 int
13700 guestfs_set_attach_method (guestfs_h *g,
13701 const char *backend);
13702 This function is deprecated. In new code, use the
13704 "guestfs_set_backend" call instead.
13705 Deprecated functions will not be removed from the API, but the fact
13707 that they are deprecated indicates that there are problems with correct
13708 use of these functions.
13709 Set the method that libguestfs uses to connect to the backend guestfsd
13711 daemon.
13712 See "BACKEND".
13714 This function returns 0 on success or -1 on error.
13716 (Added in 1.9.8)
13718 guestfs_set_autosync
13720 int
13721 guestfs_set_autosync (guestfs_h *g,
13722 int autosync);
13723 If "autosync" is true, this enables autosync. Libguestfs will make a
13725 best effort attempt to make filesystems consistent and synchronized
13726 when the handle is closed (also if the program exits without closing
13727 handles).
13728 This is enabled by default (since libguestfs 1.5.24, previously it was
13730 disabled by default).
13731 This function returns 0 on success or -1 on error.
13733 (Added in 0.3)
13735 guestfs_set_backend
13737 int
13738 guestfs_set_backend (guestfs_h *g,
13739 const char *backend);
13740 Set the method that libguestfs uses to connect to the backend guestfsd
13742 daemon.
13743 This handle property was previously called the "attach method".
13745 See "BACKEND".
13747 This function returns 0 on success or -1 on error.
13749 (Added in 1.21.26)
13751 guestfs_set_backend_setting
13753 int
13754 guestfs_set_backend_setting (guestfs_h *g,
13755 const char *name,
13756 const char *val);
13757 Append "name=value" to the backend settings string list. However if a
13759 string already exists matching "name" or beginning with "name=", then
13760 that setting is replaced.
13761 See "BACKEND", "BACKEND SETTINGS".
13763 This function returns 0 on success or -1 on error.
13765 (Added in 1.27.2)
13767 guestfs_set_backend_settings
13769 int
13770 guestfs_set_backend_settings (guestfs_h *g,
13771 char *const *settings);
13772 Set a list of zero or more settings which are passed through to the
13774 current backend. Each setting is a string which is interpreted in a
13775 backend-specific way, or ignored if not understood by the backend.
13776 The default value is an empty list, unless the environment variable
13778 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13779 This environment variable contains a colon-separated list of settings.
13780 This call replaces all backend settings. If you want to replace a
13782 single backend setting, see "guestfs_set_backend_setting". If you want
13783 to clear a single backend setting, see "guestfs_clear_backend_setting".
13784 See "BACKEND", "BACKEND SETTINGS".
13786 This function returns 0 on success or -1 on error.
13788 (Added in 1.25.24)
13790 guestfs_set_cachedir
13792 int
13793 guestfs_set_cachedir (guestfs_h *g,
13794 const char *cachedir);
13795 Set the directory used by the handle to store the appliance cache, when
13797 using a supermin appliance. The appliance is cached and shared between
13798 all handles which have the same effective user ID.
13799 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13801 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13802 default. Else if "TMPDIR" is set, then that is the default. Else
13803 /var/tmp is the default.
13804 This function returns 0 on success or -1 on error.
13806 (Added in 1.19.58)
13808 guestfs_set_direct
13810 int
13811 guestfs_set_direct (guestfs_h *g,
13812 int direct);
13813 This function is deprecated. In new code, use the
13815 "guestfs_internal_get_console_socket" call instead.
13816 Deprecated functions will not be removed from the API, but the fact
13818 that they are deprecated indicates that there are problems with correct
13819 use of these functions.
13820 If the direct appliance mode flag is enabled, then stdin and stdout are
13822 passed directly through to the appliance once it is launched.
13823 One consequence of this is that log messages aren't caught by the
13825 library and handled by "guestfs_set_log_message_callback", but go
13826 straight to stdout.
13827 You probably don't want to use this unless you know what you are doing.
13829 The default is disabled.
13831 This function returns 0 on success or -1 on error.
13833 (Added in 1.0.72)
13835 guestfs_set_e2attrs
13837 int
13838 guestfs_set_e2attrs (guestfs_h *g,
13839 const char *file,
13840 const char *attrs,
13841 ...);
13842 You may supply a list of optional arguments to this call. Use zero or
13844 more of the following pairs of parameters, and terminate the list with
13845 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13846 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13848 This sets or clears the file attributes "attrs" associated with the
13850 inode file.
13851 "attrs" is a string of characters representing file attributes. See
13853 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13854 attributes can be changed.
13855 If optional boolean "clear" is not present or false, then the "attrs"
13857 listed are set in the inode.
13858 If "clear" is true, then the "attrs" listed are cleared in the inode.
13860 In both cases, other attributes not present in the "attrs" string are
13862 left unchanged.
13863 These attributes are only present when the file is located on an
13865 ext2/3/4 filesystem. Using this call on other filesystem types will
13866 result in an error.
13867 This function returns 0 on success or -1 on error.
13869 (Added in 1.17.31)
13871 guestfs_set_e2attrs_va
13873 int
13874 guestfs_set_e2attrs_va (guestfs_h *g,
13875 const char *file,
13876 const char *attrs,
13877 va_list args);
13878 This is the "va_list variant" of "guestfs_set_e2attrs".
13880 See "CALLS WITH OPTIONAL ARGUMENTS".
13882 guestfs_set_e2attrs_argv
13884 int
13885 guestfs_set_e2attrs_argv (guestfs_h *g,
13886 const char *file,
13887 const char *attrs,
13888 const struct guestfs_set_e2attrs_argv *optargs);
13889 This is the "argv variant" of "guestfs_set_e2attrs".
13891 See "CALLS WITH OPTIONAL ARGUMENTS".
13893 guestfs_set_e2generation
13895 int
13896 guestfs_set_e2generation (guestfs_h *g,
13897 const char *file,
13898 int64_t generation);
13899 This sets the ext2 file generation of a file.
13901 See "guestfs_get_e2generation".
13903 This function returns 0 on success or -1 on error.
13905 (Added in 1.17.31)
13907 guestfs_set_e2label
13909 int
13910 guestfs_set_e2label (guestfs_h *g,
13911 const char *device,
13912 const char *label);
13913 This function is deprecated. In new code, use the "guestfs_set_label"
13915 call instead.
13916 Deprecated functions will not be removed from the API, but the fact
13918 that they are deprecated indicates that there are problems with correct
13919 use of these functions.
13920 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13922 to "label". Filesystem labels are limited to 16 characters.
13923 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13925 return the existing label on a filesystem.
13926 This function returns 0 on success or -1 on error.
13928 (Added in 1.0.15)
13930 guestfs_set_e2uuid
13932 int
13933 guestfs_set_e2uuid (guestfs_h *g,
13934 const char *device,
13935 const char *uuid);
13936 This function is deprecated. In new code, use the "guestfs_set_uuid"
13938 call instead.
13939 Deprecated functions will not be removed from the API, but the fact
13941 that they are deprecated indicates that there are problems with correct
13942 use of these functions.
13943 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
13945 "uuid". The format of the UUID and alternatives such as "clear",
13946 "random" and "time" are described in the tune2fs(8) manpage.
13947 You can use "guestfs_vfs_uuid" to return the existing UUID of a
13949 filesystem.
13950 This function returns 0 on success or -1 on error.
13952 (Added in 1.0.15)
13954 guestfs_set_hv
13956 int
13957 guestfs_set_hv (guestfs_h *g,
13958 const char *hv);
13959 Set the hypervisor binary that we will use. The hypervisor depends on
13961 the backend, but is usually the location of the qemu/KVM hypervisor.
13962 The default is chosen when the library was compiled by the configure
13964 script.
13965 You can also override this by setting the "LIBGUESTFS_HV" environment
13967 variable.
13968 Note that you should call this function as early as possible after
13970 creating the handle. This is because some pre-launch operations depend
13971 on testing qemu features (by running "qemu -help"). If the qemu binary
13972 changes, we don't retest features, and so you might see inconsistent
13973 results. Using the environment variable "LIBGUESTFS_HV" is safest of
13974 all since that picks the qemu binary at the same time as the handle is
13975 created.
13976 This function returns 0 on success or -1 on error.
13978 (Added in 1.23.17)
13980 guestfs_set_identifier
13982 int
13983 guestfs_set_identifier (guestfs_h *g,
13984 const char *identifier);
13985 This is an informative string which the caller may optionally set in
13987 the handle. It is printed in various places, allowing the current
13988 handle to be identified in debugging output.
13989 One important place is when tracing is enabled. If the identifier
13991 string is not an empty string, then trace messages change from this:
13992 libguestfs: trace: get_tmpdir
13994 libguestfs: trace: get_tmpdir = "/tmp"
13995 to this:
13997 libguestfs: trace: ID: get_tmpdir
13999 libguestfs: trace: ID: get_tmpdir = "/tmp"
14000 where "ID" is the identifier string set by this call.
14002 The identifier must only contain alphanumeric ASCII characters,
14004 underscore and minus sign. The default is the empty string.
14005 See also "guestfs_set_program", "guestfs_set_trace",
14007 "guestfs_get_identifier".
14008 This function returns 0 on success or -1 on error.
14010 (Added in 1.31.14)
14012 guestfs_set_label
14014 int
14015 guestfs_set_label (guestfs_h *g,
14016 const char *mountable,
14017 const char *label);
14018 Set the filesystem label on "mountable" to "label".
14020 Only some filesystem types support labels, and libguestfs supports
14022 setting labels on only a subset of these.
14023 ext2, ext3, ext4
14025 Labels are limited to 16 bytes.
14026 NTFS
14028 Labels are limited to 128 unicode characters.
14029 XFS The label is limited to 12 bytes. The filesystem must not be
14031 mounted when trying to set the label.
14032 btrfs
14034 The label is limited to 255 bytes and some characters are not
14035 allowed. Setting the label on a btrfs subvolume will set the label
14036 on its parent filesystem. The filesystem must not be mounted when
14037 trying to set the label.
14038 fat The label is limited to 11 bytes.
14040 swap
14042 The label is limited to 16 bytes.
14043 If there is no support for changing the label for the type of the
14045 specified filesystem, set_label will fail and set errno as ENOTSUP.
14046 To read the label on a filesystem, call "guestfs_vfs_label".
14048 This function returns 0 on success or -1 on error.
14050 (Added in 1.17.9)
14052 guestfs_set_libvirt_requested_credential
14054 int
14055 guestfs_set_libvirt_requested_credential (guestfs_h *g,
14056 int index,
14057 const char *cred,
14058 size_t cred_size);
14059 After requesting the "index"'th credential from the user, call this
14061 function to pass the answer back to libvirt.
14062 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14064 This function returns 0 on success or -1 on error.
14066 (Added in 1.19.52)
14068 guestfs_set_libvirt_supported_credentials
14070 int
14071 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
14072 char *const *creds);
14073 Call this function before setting an event handler for
14075 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
14076 that the program knows how to process.
14077 The "creds" list must be a non-empty list of strings. Possible strings
14079 are:
14080 "username"
14082 "authname"
14083 "language"
14084 "cnonce"
14085 "passphrase"
14086 "echoprompt"
14087 "noechoprompt"
14088 "realm"
14089 "external"
14090 See libvirt documentation for the meaning of these credential types.
14092 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14094 This function returns 0 on success or -1 on error.
14096 (Added in 1.19.52)
14098 guestfs_set_memsize
14100 int
14101 guestfs_set_memsize (guestfs_h *g,
14102 int memsize);
14103 This sets the memory size in megabytes allocated to the hypervisor.
14105 This only has any effect if called before "guestfs_launch".
14106 You can also change this by setting the environment variable
14108 "LIBGUESTFS_MEMSIZE" before the handle is created.
14109 For more information on the architecture of libguestfs, see guestfs(3).
14111 This function returns 0 on success or -1 on error.
14113 (Added in 1.0.55)
14115 guestfs_set_network
14117 int
14118 guestfs_set_network (guestfs_h *g,
14119 int network);
14120 If "network" is true, then the network is enabled in the libguestfs
14122 appliance. The default is false.
14123 This affects whether commands are able to access the network (see
14125 "RUNNING COMMANDS").
14126 You must call this before calling "guestfs_launch", otherwise it has no
14128 effect.
14129 This function returns 0 on success or -1 on error.
14131 (Added in 1.5.4)
14133 guestfs_set_path
14135 int
14136 guestfs_set_path (guestfs_h *g,
14137 const char *searchpath);
14138 Set the path that libguestfs searches for kernel and initrd.img.
14140 The default is "$libdir/guestfs" unless overridden by setting
14142 "LIBGUESTFS_PATH" environment variable.
14143 Setting "path" to "NULL" restores the default path.
14145 This function returns 0 on success or -1 on error.
14147 (Added in 0.3)
14149 guestfs_set_pgroup
14151 int
14152 guestfs_set_pgroup (guestfs_h *g,
14153 int pgroup);
14154 If "pgroup" is true, child processes are placed into their own process
14156 group.
14157 The practical upshot of this is that signals like "SIGINT" (from users
14159 pressing "^C") won't be received by the child process.
14160 The default for this flag is false, because usually you want "^C" to
14162 kill the subprocess. Guestfish sets this flag to true when used
14163 interactively, so that "^C" can cancel long-running commands gracefully
14164 (see "guestfs_user_cancel").
14165 This function returns 0 on success or -1 on error.
14167 (Added in 1.11.18)
14169 guestfs_set_program
14171 int
14172 guestfs_set_program (guestfs_h *g,
14173 const char *program);
14174 Set the program name. This is an informative string which the main
14176 program may optionally set in the handle.
14177 When the handle is created, the program name in the handle is set to
14179 the basename from "argv[0]". The program name can never be "NULL".
14180 This function returns 0 on success or -1 on error.
14182 (Added in 1.21.29)
14184 guestfs_set_qemu
14186 int
14187 guestfs_set_qemu (guestfs_h *g,
14188 const char *hv);
14189 This function is deprecated. In new code, use the "guestfs_set_hv"
14191 call instead.
14192 Deprecated functions will not be removed from the API, but the fact
14194 that they are deprecated indicates that there are problems with correct
14195 use of these functions.
14196 Set the hypervisor binary (usually qemu) that we will use.
14198 The default is chosen when the library was compiled by the configure
14200 script.
14201 You can also override this by setting the "LIBGUESTFS_HV" environment
14203 variable.
14204 Setting "hv" to "NULL" restores the default qemu binary.
14206 Note that you should call this function as early as possible after
14208 creating the handle. This is because some pre-launch operations depend
14209 on testing qemu features (by running "qemu -help"). If the qemu binary
14210 changes, we don't retest features, and so you might see inconsistent
14211 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14212 all since that picks the qemu binary at the same time as the handle is
14213 created.
14214 This function returns 0 on success or -1 on error.
14216 (Added in 1.0.6)
14218 guestfs_set_recovery_proc
14220 int
14221 guestfs_set_recovery_proc (guestfs_h *g,
14222 int recoveryproc);
14223 If this is called with the parameter "false" then "guestfs_launch" does
14225 not create a recovery process. The purpose of the recovery process is
14226 to stop runaway hypervisor processes in the case where the main program
14227 aborts abruptly.
14228 This only has any effect if called before "guestfs_launch", and the
14230 default is true.
14231 About the only time when you would want to disable this is if the main
14233 process will fork itself into the background ("daemonize" itself). In
14234 this case the recovery process thinks that the main program has
14235 disappeared and so kills the hypervisor, which is not very helpful.
14236 This function returns 0 on success or -1 on error.
14238 (Added in 1.0.77)
14240 guestfs_set_selinux
14242 int
14243 guestfs_set_selinux (guestfs_h *g,
14244 int selinux);
14245 This function is deprecated. In new code, use the
14247 "guestfs_selinux_relabel" call instead.
14248 Deprecated functions will not be removed from the API, but the fact
14250 that they are deprecated indicates that there are problems with correct
14251 use of these functions.
14252 This sets the selinux flag that is passed to the appliance at boot
14254 time. The default is "selinux=0" (disabled).
14255 Note that if SELinux is enabled, it is always in Permissive mode
14257 ("enforcing=0").
14258 For more information on the architecture of libguestfs, see guestfs(3).
14260 This function returns 0 on success or -1 on error.
14262 (Added in 1.0.67)
14264 guestfs_set_smp
14266 int
14267 guestfs_set_smp (guestfs_h *g,
14268 int smp);
14269 Change the number of virtual CPUs assigned to the appliance. The
14271 default is 1. Increasing this may improve performance, though often it
14272 has no effect.
14273 This function must be called before "guestfs_launch".
14275 This function returns 0 on success or -1 on error.
14277 (Added in 1.13.15)
14279 guestfs_set_tmpdir
14281 int
14282 guestfs_set_tmpdir (guestfs_h *g,
14283 const char *tmpdir);
14284 Set the directory used by the handle to store temporary files.
14286 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14288 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14289 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
14290 default.
14291 This function returns 0 on success or -1 on error.
14293 (Added in 1.19.58)
14295 guestfs_set_trace
14297 int
14298 guestfs_set_trace (guestfs_h *g,
14299 int trace);
14300 If the command trace flag is set to 1, then libguestfs calls,
14302 parameters and return values are traced.
14303 If you want to trace C API calls into libguestfs (and other libraries)
14305 then possibly a better way is to use the external ltrace(1) command.
14306 Command traces are disabled unless the environment variable
14308 "LIBGUESTFS_TRACE" is defined and set to 1.
14309 Trace messages are normally sent to "stderr", unless you register a
14311 callback to send them somewhere else (see
14312 "guestfs_set_event_callback").
14313 This function returns 0 on success or -1 on error.
14315 (Added in 1.0.69)
14317 guestfs_set_uuid
14319 int
14320 guestfs_set_uuid (guestfs_h *g,
14321 const char *device,
14322 const char *uuid);
14323 Set the filesystem UUID on "device" to "uuid". If this fails and the
14325 errno is ENOTSUP, means that there is no support for changing the UUID
14326 for the type of the specified filesystem.
14327 Only some filesystem types support setting UUIDs.
14329 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14331 This function returns 0 on success or -1 on error.
14333 (Added in 1.23.10)
14335 guestfs_set_uuid_random
14337 int
14338 guestfs_set_uuid_random (guestfs_h *g,
14339 const char *device);
14340 Set the filesystem UUID on "device" to a random UUID. If this fails
14342 and the errno is ENOTSUP, means that there is no support for changing
14343 the UUID for the type of the specified filesystem.
14344 Only some filesystem types support setting UUIDs.
14346 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14348 This function returns 0 on success or -1 on error.
14350 (Added in 1.29.50)
14352 guestfs_set_verbose
14354 int
14355 guestfs_set_verbose (guestfs_h *g,
14356 int verbose);
14357 If "verbose" is true, this turns on verbose messages.
14359 Verbose messages are disabled unless the environment variable
14361 "LIBGUESTFS_DEBUG" is defined and set to 1.
14362 Verbose messages are normally sent to "stderr", unless you register a
14364 callback to send them somewhere else (see
14365 "guestfs_set_event_callback").
14366 This function returns 0 on success or -1 on error.
14368 (Added in 0.3)
14370 guestfs_setcon
14372 int
14373 guestfs_setcon (guestfs_h *g,
14374 const char *context);
14375 This function is deprecated. In new code, use the
14377 "guestfs_selinux_relabel" call instead.
14378 Deprecated functions will not be removed from the API, but the fact
14380 that they are deprecated indicates that there are problems with correct
14381 use of these functions.
14382 This sets the SELinux security context of the daemon to the string
14384 "context".
14385 See the documentation about SELINUX in guestfs(3).
14387 This function returns 0 on success or -1 on error.
14389 This function depends on the feature "selinux". See also
14391 "guestfs_feature_available".
14392 (Added in 1.0.67)
14394 guestfs_setxattr
14396 int
14397 guestfs_setxattr (guestfs_h *g,
14398 const char *xattr,
14399 const char *val,
14400 int vallen,
14401 const char *path);
14402 This call sets the extended attribute named "xattr" of the file "path"
14404 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14405 data.
14406 See also: "guestfs_lsetxattr", attr(5).
14408 This function returns 0 on success or -1 on error.
14410 This function depends on the feature "linuxxattrs". See also
14412 "guestfs_feature_available".
14413 (Added in 1.0.59)
14415 guestfs_sfdisk
14417 int
14418 guestfs_sfdisk (guestfs_h *g,
14419 const char *device,
14420 int cyls,
14421 int heads,
14422 int sectors,
14423 char *const *lines);
14424 This function is deprecated. In new code, use the "guestfs_part_add"
14426 call instead.
14427 Deprecated functions will not be removed from the API, but the fact
14429 that they are deprecated indicates that there are problems with correct
14430 use of these functions.
14431 This is a direct interface to the sfdisk(8) program for creating
14433 partitions on block devices.
14434 "device" should be a block device, for example /dev/sda.
14436 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14438 sectors on the device, which are passed directly to sfdisk(8) as the
14439 -C, -H and -S parameters. If you pass 0 for any of these, then the
14440 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14441 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
14442 (or rather, the kernel) cannot work out the right geometry and you will
14443 need to tell it.
14444 "lines" is a list of lines that we feed to sfdisk(8). For more
14446 information refer to the sfdisk(8) manpage.
14447 To create a single partition occupying the whole disk, you would pass
14449 "lines" as a single element list, when the single element being the
14450 string "," (comma).
14451 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14453 This function returns 0 on success or -1 on error.
14455 (Added in 0.8)
14457 guestfs_sfdiskM
14459 int
14460 guestfs_sfdiskM (guestfs_h *g,
14461 const char *device,
14462 char *const *lines);
14463 This function is deprecated. In new code, use the "guestfs_part_add"
14465 call instead.
14466 Deprecated functions will not be removed from the API, but the fact
14468 that they are deprecated indicates that there are problems with correct
14469 use of these functions.
14470 This is a simplified interface to the "guestfs_sfdisk" command, where
14472 partition sizes are specified in megabytes only (rounded to the nearest
14473 cylinder) and you don't need to specify the cyls, heads and sectors
14474 parameters which were rarely if ever used anyway.
14475 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14477 "guestfs_part_disk"
14478 This function returns 0 on success or -1 on error.
14480 (Added in 1.0.55)
14482 guestfs_sfdisk_N
14484 int
14485 guestfs_sfdisk_N (guestfs_h *g,
14486 const char *device,
14487 int partnum,
14488 int cyls,
14489 int heads,
14490 int sectors,
14491 const char *line);
14492 This function is deprecated. In new code, use the "guestfs_part_add"
14494 call instead.
14495 Deprecated functions will not be removed from the API, but the fact
14497 that they are deprecated indicates that there are problems with correct
14498 use of these functions.
14499 This runs sfdisk(8) option to modify just the single partition "n"
14501 (note: "n" counts from 1).
14502 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14504 for the cyls/heads/sectors parameters.
14505 See also: "guestfs_part_add"
14507 This function returns 0 on success or -1 on error.
14509 (Added in 1.0.26)
14511 guestfs_sfdisk_disk_geometry
14513 char *
14514 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14515 const char *device);
14516 This displays the disk geometry of "device" read from the partition
14518 table. Especially in the case where the underlying block device has
14519 been resized, this can be different from the kernel’s idea of the
14520 geometry (see "guestfs_sfdisk_kernel_geometry").
14521 The result is in human-readable format, and not designed to be parsed.
14523 This function returns a string, or NULL on error. The caller must free
14525 the returned string after use.
14526 (Added in 1.0.26)
14528 guestfs_sfdisk_kernel_geometry
14530 char *
14531 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14532 const char *device);
14533 This displays the kernel’s idea of the geometry of "device".
14535 The result is in human-readable format, and not designed to be parsed.
14537 This function returns a string, or NULL on error. The caller must free
14539 the returned string after use.
14540 (Added in 1.0.26)
14542 guestfs_sfdisk_l
14544 char *
14545 guestfs_sfdisk_l (guestfs_h *g,
14546 const char *device);
14547 This function is deprecated. In new code, use the "guestfs_part_list"
14549 call instead.
14550 Deprecated functions will not be removed from the API, but the fact
14552 that they are deprecated indicates that there are problems with correct
14553 use of these functions.
14554 This displays the partition table on "device", in the human-readable
14556 output of the sfdisk(8) command. It is not intended to be parsed.
14557 See also: "guestfs_part_list"
14559 This function returns a string, or NULL on error. The caller must free
14561 the returned string after use.
14562 (Added in 1.0.26)
14564 guestfs_sh
14566 char *
14567 guestfs_sh (guestfs_h *g,
14568 const char *command);
14569 This call runs a command from the guest filesystem via the guest’s
14571 /bin/sh.
14572 This is like "guestfs_command", but passes the command to:
14574 /bin/sh -c "command"
14576 Depending on the guest’s shell, this usually results in wildcards being
14578 expanded, shell expressions being interpolated and so on.
14579 All the provisos about "guestfs_command" apply to this call.
14581 This function returns a string, or NULL on error. The caller must free
14583 the returned string after use.
14584 (Added in 1.0.50)
14586 guestfs_sh_lines
14588 char **
14589 guestfs_sh_lines (guestfs_h *g,
14590 const char *command);
14591 This is the same as "guestfs_sh", but splits the result into a list of
14593 lines.
14594 See also: "guestfs_command_lines"
14596 This function returns a NULL-terminated array of strings (like
14598 environ(3)), or NULL if there was an error. The caller must free the
14599 strings and the array after use.
14600 (Added in 1.0.50)
14602 guestfs_shutdown
14604 int
14605 guestfs_shutdown (guestfs_h *g);
14606 This is the opposite of "guestfs_launch". It performs an orderly
14608 shutdown of the backend process(es). If the autosync flag is set
14609 (which is the default) then the disk image is synchronized.
14610 If the subprocess exits with an error then this function will return an
14612 error, which should not be ignored (it may indicate that the disk image
14613 could not be written out properly).
14614 It is safe to call this multiple times. Extra calls are ignored.
14616 This call does not close or free up the handle. You still need to call
14618 "guestfs_close" afterwards.
14619 "guestfs_close" will call this if you don't do it explicitly, but note
14621 that any errors are ignored in that case.
14622 This function returns 0 on success or -1 on error.
14624 (Added in 1.19.16)
14626 guestfs_sleep
14628 int
14629 guestfs_sleep (guestfs_h *g,
14630 int secs);
14631 Sleep for "secs" seconds.
14633 This function returns 0 on success or -1 on error.
14635 (Added in 1.0.41)
14637 guestfs_stat
14639 struct guestfs_stat *
14640 guestfs_stat (guestfs_h *g,
14641 const char *path);
14642 This function is deprecated. In new code, use the "guestfs_statns"
14644 call instead.
14645 Deprecated functions will not be removed from the API, but the fact
14647 that they are deprecated indicates that there are problems with correct
14648 use of these functions.
14649 Returns file information for the given "path".
14651 This is the same as the stat(2) system call.
14653 This function returns a "struct guestfs_stat *", or NULL if there was
14655 an error. The caller must call "guestfs_free_stat" after use.
14656 (Added in 1.9.2)
14658 guestfs_statns
14660 struct guestfs_statns *
14661 guestfs_statns (guestfs_h *g,
14662 const char *path);
14663 Returns file information for the given "path".
14665 This is the same as the stat(2) system call.
14667 This function returns a "struct guestfs_statns *", or NULL if there was
14669 an error. The caller must call "guestfs_free_statns" after use.
14670 (Added in 1.27.53)
14672 guestfs_statvfs
14674 struct guestfs_statvfs *
14675 guestfs_statvfs (guestfs_h *g,
14676 const char *path);
14677 Returns file system statistics for any mounted file system. "path"
14679 should be a file or directory in the mounted file system (typically it
14680 is the mount point itself, but it doesn't need to be).
14681 This is the same as the statvfs(2) system call.
14683 This function returns a "struct guestfs_statvfs *", or NULL if there
14685 was an error. The caller must call "guestfs_free_statvfs" after use.
14686 (Added in 1.9.2)
14688 guestfs_strings
14690 char **
14691 guestfs_strings (guestfs_h *g,
14692 const char *path);
14693 This runs the strings(1) command on a file and returns the list of
14695 printable strings found.
14696 The "strings" command has, in the past, had problems with parsing
14698 untrusted files. These are mitigated in the current version of
14699 libguestfs, but see "CVE-2014-8484".
14700 This function returns a NULL-terminated array of strings (like
14702 environ(3)), or NULL if there was an error. The caller must free the
14703 strings and the array after use.
14704 Because of the message protocol, there is a transfer limit of somewhere
14706 between 2MB and 4MB. See "PROTOCOL LIMITS".
14707 (Added in 1.0.22)
14709 guestfs_strings_e
14711 char **
14712 guestfs_strings_e (guestfs_h *g,
14713 const char *encoding,
14714 const char *path);
14715 This is like the "guestfs_strings" command, but allows you to specify
14717 the encoding of strings that are looked for in the source file "path".
14718 Allowed encodings are:
14720 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14722 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14723 S Single 8-bit-byte characters.
14725 b 16-bit big endian strings such as those encoded in UTF-16BE or
14727 UCS-2BE.
14728 l (lower case letter L)
14730 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14731 for examining binaries in Windows guests.
14732 B 32-bit big endian such as UCS-4BE.
14734 L 32-bit little endian such as UCS-4LE.
14736 The returned strings are transcoded to UTF-8.
14738 The "strings" command has, in the past, had problems with parsing
14740 untrusted files. These are mitigated in the current version of
14741 libguestfs, but see "CVE-2014-8484".
14742 This function returns a NULL-terminated array of strings (like
14744 environ(3)), or NULL if there was an error. The caller must free the
14745 strings and the array after use.
14746 Because of the message protocol, there is a transfer limit of somewhere
14748 between 2MB and 4MB. See "PROTOCOL LIMITS".
14749 (Added in 1.0.22)
14751 guestfs_swapoff_device
14753 int
14754 guestfs_swapoff_device (guestfs_h *g,
14755 const char *device);
14756 This command disables the libguestfs appliance swap device or partition
14758 named "device". See "guestfs_swapon_device".
14759 This function returns 0 on success or -1 on error.
14761 (Added in 1.0.66)
14763 guestfs_swapoff_file
14765 int
14766 guestfs_swapoff_file (guestfs_h *g,
14767 const char *file);
14768 This command disables the libguestfs appliance swap on file.
14770 This function returns 0 on success or -1 on error.
14772 (Added in 1.0.66)
14774 guestfs_swapoff_label
14776 int
14777 guestfs_swapoff_label (guestfs_h *g,
14778 const char *label);
14779 This command disables the libguestfs appliance swap on labeled swap
14781 partition.
14782 This function returns 0 on success or -1 on error.
14784 (Added in 1.0.66)
14786 guestfs_swapoff_uuid
14788 int
14789 guestfs_swapoff_uuid (guestfs_h *g,
14790 const char *uuid);
14791 This command disables the libguestfs appliance swap partition with the
14793 given UUID.
14794 This function returns 0 on success or -1 on error.
14796 This function depends on the feature "linuxfsuuid". See also
14798 "guestfs_feature_available".
14799 (Added in 1.0.66)
14801 guestfs_swapon_device
14803 int
14804 guestfs_swapon_device (guestfs_h *g,
14805 const char *device);
14806 This command enables the libguestfs appliance to use the swap device or
14808 partition named "device". The increased memory is made available for
14809 all commands, for example those run using "guestfs_command" or
14810 "guestfs_sh".
14811 Note that you should not swap to existing guest swap partitions unless
14813 you know what you are doing. They may contain hibernation information,
14814 or other information that the guest doesn't want you to trash. You
14815 also risk leaking information about the host to the guest this way.
14816 Instead, attach a new host device to the guest and swap on that.
14817 This function returns 0 on success or -1 on error.
14819 (Added in 1.0.66)
14821 guestfs_swapon_file
14823 int
14824 guestfs_swapon_file (guestfs_h *g,
14825 const char *file);
14826 This command enables swap to a file. See "guestfs_swapon_device" for
14828 other notes.
14829 This function returns 0 on success or -1 on error.
14831 (Added in 1.0.66)
14833 guestfs_swapon_label
14835 int
14836 guestfs_swapon_label (guestfs_h *g,
14837 const char *label);
14838 This command enables swap to a labeled swap partition. See
14840 "guestfs_swapon_device" for other notes.
14841 This function returns 0 on success or -1 on error.
14843 (Added in 1.0.66)
14845 guestfs_swapon_uuid
14847 int
14848 guestfs_swapon_uuid (guestfs_h *g,
14849 const char *uuid);
14850 This command enables swap to a swap partition with the given UUID. See
14852 "guestfs_swapon_device" for other notes.
14853 This function returns 0 on success or -1 on error.
14855 This function depends on the feature "linuxfsuuid". See also
14857 "guestfs_feature_available".
14858 (Added in 1.0.66)
14860 guestfs_sync
14862 int
14863 guestfs_sync (guestfs_h *g);
14864 This syncs the disk, so that any writes are flushed through to the
14866 underlying disk image.
14867 You should always call this if you have modified a disk image, before
14869 closing the handle.
14870 This function returns 0 on success or -1 on error.
14872 (Added in 0.3)
14874 guestfs_syslinux
14876 int
14877 guestfs_syslinux (guestfs_h *g,
14878 const char *device,
14879 ...);
14880 You may supply a list of optional arguments to this call. Use zero or
14882 more of the following pairs of parameters, and terminate the list with
14883 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14884 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14886 Install the SYSLINUX bootloader on "device".
14888 The device parameter must be either a whole disk formatted as a FAT
14890 filesystem, or a partition formatted as a FAT filesystem. In the
14891 latter case, the partition should be marked as "active"
14892 ("guestfs_part_set_bootable") and a Master Boot Record must be
14893 installed (eg. using "guestfs_pwrite_device") on the first sector of
14894 the whole disk. The SYSLINUX package comes with some suitable Master
14895 Boot Records. See the syslinux(1) man page for further information.
14896 The optional arguments are:
14898 directory
14900 Install SYSLINUX in the named subdirectory, instead of in the root
14901 directory of the FAT filesystem.
14902 Additional configuration can be supplied to SYSLINUX by placing a file
14904 called syslinux.cfg on the FAT filesystem, either in the root
14905 directory, or under directory if that optional argument is being used.
14906 For further information about the contents of this file, see
14907 syslinux(1).
14908 See also "guestfs_extlinux".
14910 This function returns 0 on success or -1 on error.
14912 This function depends on the feature "syslinux". See also
14914 "guestfs_feature_available".
14915 (Added in 1.21.27)
14917 guestfs_syslinux_va
14919 int
14920 guestfs_syslinux_va (guestfs_h *g,
14921 const char *device,
14922 va_list args);
14923 This is the "va_list variant" of "guestfs_syslinux".
14925 See "CALLS WITH OPTIONAL ARGUMENTS".
14927 guestfs_syslinux_argv
14929 int
14930 guestfs_syslinux_argv (guestfs_h *g,
14931 const char *device,
14932 const struct guestfs_syslinux_argv *optargs);
14933 This is the "argv variant" of "guestfs_syslinux".
14935 See "CALLS WITH OPTIONAL ARGUMENTS".
14937 guestfs_tail
14939 char **
14940 guestfs_tail (guestfs_h *g,
14941 const char *path);
14942 This command returns up to the last 10 lines of a file as a list of
14944 strings.
14945 This function returns a NULL-terminated array of strings (like
14947 environ(3)), or NULL if there was an error. The caller must free the
14948 strings and the array after use.
14949 Because of the message protocol, there is a transfer limit of somewhere
14951 between 2MB and 4MB. See "PROTOCOL LIMITS".
14952 (Added in 1.0.54)
14954 guestfs_tail_n
14956 char **
14957 guestfs_tail_n (guestfs_h *g,
14958 int nrlines,
14959 const char *path);
14960 If the parameter "nrlines" is a positive number, this returns the last
14962 "nrlines" lines of the file "path".
14963 If the parameter "nrlines" is a negative number, this returns lines
14965 from the file "path", starting with the "-nrlines"'th line.
14966 If the parameter "nrlines" is zero, this returns an empty list.
14968 This function returns a NULL-terminated array of strings (like
14970 environ(3)), or NULL if there was an error. The caller must free the
14971 strings and the array after use.
14972 Because of the message protocol, there is a transfer limit of somewhere
14974 between 2MB and 4MB. See "PROTOCOL LIMITS".
14975 (Added in 1.0.54)
14977 guestfs_tar_in
14979 int
14980 guestfs_tar_in (guestfs_h *g,
14981 const char *tarfile,
14982 const char *directory);
14983 This function is provided for backwards compatibility with earlier
14985 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
14986 optional arguments.
14987 (Added in 1.0.3)
14989 guestfs_tar_in_opts
14991 int
14992 guestfs_tar_in_opts (guestfs_h *g,
14993 const char *tarfile,
14994 const char *directory,
14995 ...);
14996 You may supply a list of optional arguments to this call. Use zero or
14998 more of the following pairs of parameters, and terminate the list with
14999 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15000 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
15002 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
15003 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
15004 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
15005 This command uploads and unpacks local file "tarfile" into directory.
15007 The optional "compress" flag controls compression. If not given, then
15009 the input should be an uncompressed tar file. Otherwise one of the
15010 following strings may be given to select the compression type of the
15011 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15012 all builds of libguestfs will support all of these compression types).
15013 The other optional arguments are:
15015 "xattrs"
15017 If set to true, extended attributes are restored from the tar file.
15018 "selinux"
15020 If set to true, SELinux contexts are restored from the tar file.
15021 "acls"
15023 If set to true, POSIX ACLs are restored from the tar file.
15024 This function returns 0 on success or -1 on error.
15026 (Added in 1.0.3)
15028 guestfs_tar_in_opts_va
15030 int
15031 guestfs_tar_in_opts_va (guestfs_h *g,
15032 const char *tarfile,
15033 const char *directory,
15034 va_list args);
15035 This is the "va_list variant" of "guestfs_tar_in_opts".
15037 See "CALLS WITH OPTIONAL ARGUMENTS".
15039 guestfs_tar_in_opts_argv
15041 int
15042 guestfs_tar_in_opts_argv (guestfs_h *g,
15043 const char *tarfile,
15044 const char *directory,
15045 const struct guestfs_tar_in_opts_argv *optargs);
15046 This is the "argv variant" of "guestfs_tar_in_opts".
15048 See "CALLS WITH OPTIONAL ARGUMENTS".
15050 guestfs_tar_out
15052 int
15053 guestfs_tar_out (guestfs_h *g,
15054 const char *directory,
15055 const char *tarfile);
15056 This function is provided for backwards compatibility with earlier
15058 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
15059 optional arguments.
15060 (Added in 1.0.3)
15062 guestfs_tar_out_opts
15064 int
15065 guestfs_tar_out_opts (guestfs_h *g,
15066 const char *directory,
15067 const char *tarfile,
15068 ...);
15069 You may supply a list of optional arguments to this call. Use zero or
15071 more of the following pairs of parameters, and terminate the list with
15072 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15073 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
15075 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
15076 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
15077 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
15078 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
15079 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
15080 This command packs the contents of directory and downloads it to local
15082 file "tarfile".
15083 The optional "compress" flag controls compression. If not given, then
15085 the output will be an uncompressed tar file. Otherwise one of the
15086 following strings may be given to select the compression type of the
15087 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15088 all builds of libguestfs will support all of these compression types).
15089 The other optional arguments are:
15091 "excludes"
15093 A list of wildcards. Files are excluded if they match any of the
15094 wildcards.
15095 "numericowner"
15097 If set to true, the output tar file will contain UID/GID numbers
15098 instead of user/group names.
15099 "xattrs"
15101 If set to true, extended attributes are saved in the output tar.
15102 "selinux"
15104 If set to true, SELinux contexts are saved in the output tar.
15105 "acls"
15107 If set to true, POSIX ACLs are saved in the output tar.
15108 This function returns 0 on success or -1 on error.
15110 (Added in 1.0.3)
15112 guestfs_tar_out_opts_va
15114 int
15115 guestfs_tar_out_opts_va (guestfs_h *g,
15116 const char *directory,
15117 const char *tarfile,
15118 va_list args);
15119 This is the "va_list variant" of "guestfs_tar_out_opts".
15121 See "CALLS WITH OPTIONAL ARGUMENTS".
15123 guestfs_tar_out_opts_argv
15125 int
15126 guestfs_tar_out_opts_argv (guestfs_h *g,
15127 const char *directory,
15128 const char *tarfile,
15129 const struct guestfs_tar_out_opts_argv *optargs);
15130 This is the "argv variant" of "guestfs_tar_out_opts".
15132 See "CALLS WITH OPTIONAL ARGUMENTS".
15134 guestfs_tgz_in
15136 int
15137 guestfs_tgz_in (guestfs_h *g,
15138 const char *tarball,
15139 const char *directory);
15140 This function is deprecated. In new code, use the "guestfs_tar_in"
15142 call instead.
15143 Deprecated functions will not be removed from the API, but the fact
15145 that they are deprecated indicates that there are problems with correct
15146 use of these functions.
15147 This command uploads and unpacks local file "tarball" (a gzip
15149 compressed tar file) into directory.
15150 This function returns 0 on success or -1 on error.
15152 (Added in 1.0.3)
15154 guestfs_tgz_out
15156 int
15157 guestfs_tgz_out (guestfs_h *g,
15158 const char *directory,
15159 const char *tarball);
15160 This function is deprecated. In new code, use the "guestfs_tar_out"
15162 call instead.
15163 Deprecated functions will not be removed from the API, but the fact
15165 that they are deprecated indicates that there are problems with correct
15166 use of these functions.
15167 This command packs the contents of directory and downloads it to local
15169 file "tarball".
15170 This function returns 0 on success or -1 on error.
15172 (Added in 1.0.3)
15174 guestfs_touch
15176 int
15177 guestfs_touch (guestfs_h *g,
15178 const char *path);
15179 Touch acts like the touch(1) command. It can be used to update the
15181 timestamps on a file, or, if the file does not exist, to create a new
15182 zero-length file.
15183 This command only works on regular files, and will fail on other file
15185 types such as directories, symbolic links, block special etc.
15186 This function returns 0 on success or -1 on error.
15188 (Added in 0.3)
15190 guestfs_truncate
15192 int
15193 guestfs_truncate (guestfs_h *g,
15194 const char *path);
15195 This command truncates "path" to a zero-length file. The file must
15197 exist already.
15198 This function returns 0 on success or -1 on error.
15200 (Added in 1.0.77)
15202 guestfs_truncate_size
15204 int
15205 guestfs_truncate_size (guestfs_h *g,
15206 const char *path,
15207 int64_t size);
15208 This command truncates "path" to size "size" bytes. The file must
15210 exist already.
15211 If the current file size is less than "size" then the file is extended
15213 to the required size with zero bytes. This creates a sparse file (ie.
15214 disk blocks are not allocated for the file until you write to it). To
15215 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15216 This function returns 0 on success or -1 on error.
15218 (Added in 1.0.77)
15220 guestfs_tune2fs
15222 int
15223 guestfs_tune2fs (guestfs_h *g,
15224 const char *device,
15225 ...);
15226 You may supply a list of optional arguments to this call. Use zero or
15228 more of the following pairs of parameters, and terminate the list with
15229 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15230 GUESTFS_TUNE2FS_FORCE, int force,
15232 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15233 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15234 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15235 GUESTFS_TUNE2FS_GROUP, int64_t group,
15236 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15237 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15238 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15239 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15240 GUESTFS_TUNE2FS_USER, int64_t user,
15241 This call allows you to adjust various filesystem parameters of an
15243 ext2/ext3/ext4 filesystem called "device".
15244 The optional parameters are:
15246 "force"
15248 Force tune2fs to complete the operation even in the face of errors.
15249 This is the same as the tune2fs(8) "-f" option.
15250 "maxmountcount"
15252 Set the number of mounts after which the filesystem is checked by
15253 e2fsck(8). If this is 0 then the number of mounts is disregarded.
15254 This is the same as the tune2fs(8) "-c" option.
15255 "mountcount"
15257 Set the number of times the filesystem has been mounted. This is
15258 the same as the tune2fs(8) "-C" option.
15259 "errorbehavior"
15261 Change the behavior of the kernel code when errors are detected.
15262 Possible values currently are: "continue", "remount-ro", "panic".
15263 In practice these options don't really make any difference,
15264 particularly for write errors.
15265 This is the same as the tune2fs(8) "-e" option.
15267 "group"
15269 Set the group which can use reserved filesystem blocks. This is
15270 the same as the tune2fs(8) "-g" option except that it can only be
15271 specified as a number.
15272 "intervalbetweenchecks"
15274 Adjust the maximal time between two filesystem checks (in seconds).
15275 If the option is passed as 0 then time-dependent checking is
15276 disabled.
15277 This is the same as the tune2fs(8) "-i" option.
15279 "reservedblockspercentage"
15281 Set the percentage of the filesystem which may only be allocated by
15282 privileged processes. This is the same as the tune2fs(8) "-m"
15283 option.
15284 "lastmounteddirectory"
15286 Set the last mounted directory. This is the same as the tune2fs(8)
15287 "-M" option.
15288 "reservedblockscount" Set the number of reserved filesystem blocks.
15290 This is the same as the tune2fs(8) "-r" option.
15291 "user"
15292 Set the user who can use the reserved filesystem blocks. This is
15293 the same as the tune2fs(8) "-u" option except that it can only be
15294 specified as a number.
15295 To get the current values of filesystem parameters, see
15297 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
15298 tune2fs(8) man page.
15299 This function returns 0 on success or -1 on error.
15301 (Added in 1.15.4)
15303 guestfs_tune2fs_va
15305 int
15306 guestfs_tune2fs_va (guestfs_h *g,
15307 const char *device,
15308 va_list args);
15309 This is the "va_list variant" of "guestfs_tune2fs".
15311 See "CALLS WITH OPTIONAL ARGUMENTS".
15313 guestfs_tune2fs_argv
15315 int
15316 guestfs_tune2fs_argv (guestfs_h *g,
15317 const char *device,
15318 const struct guestfs_tune2fs_argv *optargs);
15319 This is the "argv variant" of "guestfs_tune2fs".
15321 See "CALLS WITH OPTIONAL ARGUMENTS".
15323 guestfs_tune2fs_l
15325 char **
15326 guestfs_tune2fs_l (guestfs_h *g,
15327 const char *device);
15328 This returns the contents of the ext2, ext3 or ext4 filesystem
15330 superblock on "device".
15331 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
15333 for more details. The list of fields returned isn't clearly defined,
15334 and depends on both the version of "tune2fs" that libguestfs was built
15335 against, and the filesystem itself.
15336 This function returns a NULL-terminated array of strings, or NULL if
15338 there was an error. The array of strings will always have length
15339 "2n+1", where "n" keys and values alternate, followed by the trailing
15340 NULL entry. The caller must free the strings and the array after use.
15341 (Added in 1.9.2)
15343 guestfs_txz_in
15345 int
15346 guestfs_txz_in (guestfs_h *g,
15347 const char *tarball,
15348 const char *directory);
15349 This function is deprecated. In new code, use the "guestfs_tar_in"
15351 call instead.
15352 Deprecated functions will not be removed from the API, but the fact
15354 that they are deprecated indicates that there are problems with correct
15355 use of these functions.
15356 This command uploads and unpacks local file "tarball" (an xz compressed
15358 tar file) into directory.
15359 This function returns 0 on success or -1 on error.
15361 This function depends on the feature "xz". See also
15363 "guestfs_feature_available".
15364 (Added in 1.3.2)
15366 guestfs_txz_out
15368 int
15369 guestfs_txz_out (guestfs_h *g,
15370 const char *directory,
15371 const char *tarball);
15372 This function is deprecated. In new code, use the "guestfs_tar_out"
15374 call instead.
15375 Deprecated functions will not be removed from the API, but the fact
15377 that they are deprecated indicates that there are problems with correct
15378 use of these functions.
15379 This command packs the contents of directory and downloads it to local
15381 file "tarball" (as an xz compressed tar archive).
15382 This function returns 0 on success or -1 on error.
15384 This function depends on the feature "xz". See also
15386 "guestfs_feature_available".
15387 (Added in 1.3.2)
15389 guestfs_umask
15391 int
15392 guestfs_umask (guestfs_h *g,
15393 int mask);
15394 This function sets the mask used for creating new files and device
15396 nodes to "mask & 0777".
15397 Typical umask values would be 022 which creates new files with
15399 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15400 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15401 The default umask is 022. This is important because it means that
15403 directories and device nodes will be created with 0644 or 0755 mode
15404 even if you specify 0777.
15405 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15407 "guestfs_mkdir".
15408 This call returns the previous umask.
15410 On error this function returns -1.
15412 (Added in 1.0.55)
15414 guestfs_umount
15416 int
15417 guestfs_umount (guestfs_h *g,
15418 const char *pathordevice);
15419 This function is provided for backwards compatibility with earlier
15421 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15422 optional arguments.
15423 (Added in 0.8)
15425 guestfs_umount_opts
15427 int
15428 guestfs_umount_opts (guestfs_h *g,
15429 const char *pathordevice,
15430 ...);
15431 You may supply a list of optional arguments to this call. Use zero or
15433 more of the following pairs of parameters, and terminate the list with
15434 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15435 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15437 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15438 This unmounts the given filesystem. The filesystem may be specified
15440 either by its mountpoint (path) or the device which contains the
15441 filesystem.
15442 This function returns 0 on success or -1 on error.
15444 (Added in 0.8)
15446 guestfs_umount_opts_va
15448 int
15449 guestfs_umount_opts_va (guestfs_h *g,
15450 const char *pathordevice,
15451 va_list args);
15452 This is the "va_list variant" of "guestfs_umount_opts".
15454 See "CALLS WITH OPTIONAL ARGUMENTS".
15456 guestfs_umount_opts_argv
15458 int
15459 guestfs_umount_opts_argv (guestfs_h *g,
15460 const char *pathordevice,
15461 const struct guestfs_umount_opts_argv *optargs);
15462 This is the "argv variant" of "guestfs_umount_opts".
15464 See "CALLS WITH OPTIONAL ARGUMENTS".
15466 guestfs_umount_all
15468 int
15469 guestfs_umount_all (guestfs_h *g);
15470 This unmounts all mounted filesystems.
15472 Some internal mounts are not unmounted by this call.
15474 This function returns 0 on success or -1 on error.
15476 (Added in 0.8)
15478 guestfs_umount_local
15480 int
15481 guestfs_umount_local (guestfs_h *g,
15482 ...);
15483 You may supply a list of optional arguments to this call. Use zero or
15485 more of the following pairs of parameters, and terminate the list with
15486 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15487 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15489 If libguestfs is exporting the filesystem on a local mountpoint, then
15491 this unmounts it.
15492 See "MOUNT LOCAL" for full documentation.
15494 This function returns 0 on success or -1 on error.
15496 (Added in 1.17.22)
15498 guestfs_umount_local_va
15500 int
15501 guestfs_umount_local_va (guestfs_h *g,
15502 va_list args);
15503 This is the "va_list variant" of "guestfs_umount_local".
15505 See "CALLS WITH OPTIONAL ARGUMENTS".
15507 guestfs_umount_local_argv
15509 int
15510 guestfs_umount_local_argv (guestfs_h *g,
15511 const struct guestfs_umount_local_argv *optargs);
15512 This is the "argv variant" of "guestfs_umount_local".
15514 See "CALLS WITH OPTIONAL ARGUMENTS".
15516 guestfs_upload
15518 int
15519 guestfs_upload (guestfs_h *g,
15520 const char *filename,
15521 const char *remotefilename);
15522 Upload local file filename to remotefilename on the filesystem.
15524 filename can also be a named pipe.
15526 See also "guestfs_download".
15528 This function returns 0 on success or -1 on error.
15530 This long-running command can generate progress notification messages
15532 so that the caller can display a progress bar or indicator. To receive
15533 these messages, the caller must register a progress event callback.
15534 See "GUESTFS_EVENT_PROGRESS".
15535 (Added in 1.0.2)
15537 guestfs_upload_offset
15539 int
15540 guestfs_upload_offset (guestfs_h *g,
15541 const char *filename,
15542 const char *remotefilename,
15543 int64_t offset);
15544 Upload local file filename to remotefilename on the filesystem.
15546 remotefilename is overwritten starting at the byte "offset" specified.
15548 The intention is to overwrite parts of existing files or devices,
15549 although if a non-existent file is specified then it is created with a
15550 "hole" before "offset". The size of the data written is implicit in
15551 the size of the source filename.
15552 Note that there is no limit on the amount of data that can be uploaded
15554 with this call, unlike with "guestfs_pwrite", and this call always
15555 writes the full amount unless an error occurs.
15556 See also "guestfs_upload", "guestfs_pwrite".
15558 This function returns 0 on success or -1 on error.
15560 This long-running command can generate progress notification messages
15562 so that the caller can display a progress bar or indicator. To receive
15563 these messages, the caller must register a progress event callback.
15564 See "GUESTFS_EVENT_PROGRESS".
15565 (Added in 1.5.17)
15567 guestfs_user_cancel
15569 int
15570 guestfs_user_cancel (guestfs_h *g);
15571 This function cancels the current upload or download operation.
15573 Unlike most other libguestfs calls, this function is signal safe and
15575 thread safe. You can call it from a signal handler or from another
15576 thread, without needing to do any locking.
15577 The transfer that was in progress (if there is one) will stop shortly
15579 afterwards, and will return an error. The errno (see
15580 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15581 find out if the operation was cancelled or failed because of another
15582 error.
15583 No cleanup is performed: for example, if a file was being uploaded then
15585 after cancellation there may be a partially uploaded file. It is the
15586 caller’s responsibility to clean up if necessary.
15587 There are two common places that you might call "guestfs_user_cancel":
15589 In an interactive text-based program, you might call it from a "SIGINT"
15591 signal handler so that pressing "^C" cancels the current operation.
15592 (You also need to call "guestfs_set_pgroup" so that child processes
15593 don't receive the "^C" signal).
15594 In a graphical program, when the main thread is displaying a progress
15596 bar with a cancel button, wire up the cancel button to call this
15597 function.
15598 This function returns 0 on success or -1 on error.
15600 (Added in 1.11.18)
15602 guestfs_utimens
15604 int
15605 guestfs_utimens (guestfs_h *g,
15606 const char *path,
15607 int64_t atsecs,
15608 int64_t atnsecs,
15609 int64_t mtsecs,
15610 int64_t mtnsecs);
15611 This command sets the timestamps of a file with nanosecond precision.
15613 "atsecs", "atnsecs" are the last access time (atime) in secs and
15615 nanoseconds from the epoch.
15616 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
15618 nanoseconds from the epoch.
15619 If the *nsecs field contains the special value "-1" then the
15621 corresponding timestamp is set to the current time. (The *secs field
15622 is ignored in this case).
15623 If the *nsecs field contains the special value "-2" then the
15625 corresponding timestamp is left unchanged. (The *secs field is ignored
15626 in this case).
15627 This function returns 0 on success or -1 on error.
15629 (Added in 1.0.77)
15631 guestfs_utsname
15633 struct guestfs_utsname *
15634 guestfs_utsname (guestfs_h *g);
15635 This returns the kernel version of the appliance, where this is
15637 available. This information is only useful for debugging. Nothing in
15638 the returned structure is defined by the API.
15639 This function returns a "struct guestfs_utsname *", or NULL if there
15641 was an error. The caller must call "guestfs_free_utsname" after use.
15642 (Added in 1.19.27)
15644 guestfs_version
15646 struct guestfs_version *
15647 guestfs_version (guestfs_h *g);
15648 Return the libguestfs version number that the program is linked
15650 against.
15651 Note that because of dynamic linking this is not necessarily the
15653 version of libguestfs that you compiled against. You can compile the
15654 program, and then at runtime dynamically link against a completely
15655 different libguestfs.so library.
15656 This call was added in version 1.0.58. In previous versions of
15658 libguestfs there was no way to get the version number. From C code you
15659 can use dynamic linker functions to find out if this symbol exists (if
15660 it doesn't, then it’s an earlier version).
15661 The call returns a structure with four elements. The first three
15663 ("major", "minor" and "release") are numbers and correspond to the
15664 usual version triplet. The fourth element ("extra") is a string and is
15665 normally empty, but may be used for distro-specific information.
15666 To construct the original version string:
15668 "$major.$minor.$release$extra"
15669 See also: "LIBGUESTFS VERSION NUMBERS".
15671 Note: Don't use this call to test for availability of features. In
15673 enterprise distributions we backport features from later versions into
15674 earlier versions, making this an unreliable way to test for features.
15675 Use "guestfs_available" or "guestfs_feature_available" instead.
15676 This function returns a "struct guestfs_version *", or NULL if there
15678 was an error. The caller must call "guestfs_free_version" after use.
15679 (Added in 1.0.58)
15681 guestfs_vfs_label
15683 char *
15684 guestfs_vfs_label (guestfs_h *g,
15685 const char *mountable);
15686 This returns the label of the filesystem on "mountable".
15688 If the filesystem is unlabeled, this returns the empty string.
15690 To find a filesystem from the label, use "guestfs_findfs_label".
15692 This function returns a string, or NULL on error. The caller must free
15694 the returned string after use.
15695 (Added in 1.3.18)
15697 guestfs_vfs_minimum_size
15699 int64_t
15700 guestfs_vfs_minimum_size (guestfs_h *g,
15701 const char *mountable);
15702 Get the minimum size of filesystem in bytes. This is the minimum
15704 possible size for filesystem shrinking.
15705 If getting minimum size of specified filesystem is not supported, this
15707 will fail and set errno as ENOTSUP.
15708 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15710 On error this function returns -1.
15712 (Added in 1.31.18)
15714 guestfs_vfs_type
15716 char *
15717 guestfs_vfs_type (guestfs_h *g,
15718 const char *mountable);
15719 This command gets the filesystem type corresponding to the filesystem
15721 on "mountable".
15722 For most filesystems, the result is the name of the Linux VFS module
15724 which would be used to mount this filesystem if you mounted it without
15725 specifying the filesystem type. For example a string such as "ext3" or
15726 "ntfs".
15727 This function returns a string, or NULL on error. The caller must free
15729 the returned string after use.
15730 (Added in 1.0.75)
15732 guestfs_vfs_uuid
15734 char *
15735 guestfs_vfs_uuid (guestfs_h *g,
15736 const char *mountable);
15737 This returns the filesystem UUID of the filesystem on "mountable".
15739 If the filesystem does not have a UUID, this returns the empty string.
15741 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15743 This function returns a string, or NULL on error. The caller must free
15745 the returned string after use.
15746 (Added in 1.3.18)
15748 guestfs_vg_activate
15750 int
15751 guestfs_vg_activate (guestfs_h *g,
15752 int activate,
15753 char *const *volgroups);
15754 This command activates or (if "activate" is false) deactivates all
15756 logical volumes in the listed volume groups "volgroups".
15757 This command is the same as running "vgchange -a y|n volgroups..."
15759 Note that if "volgroups" is an empty list then all volume groups are
15761 activated or deactivated.
15762 This function returns 0 on success or -1 on error.
15764 This function depends on the feature "lvm2". See also
15766 "guestfs_feature_available".
15767 (Added in 1.0.26)
15769 guestfs_vg_activate_all
15771 int
15772 guestfs_vg_activate_all (guestfs_h *g,
15773 int activate);
15774 This command activates or (if "activate" is false) deactivates all
15776 logical volumes in all volume groups.
15777 This command is the same as running "vgchange -a y|n"
15779 This function returns 0 on success or -1 on error.
15781 This function depends on the feature "lvm2". See also
15783 "guestfs_feature_available".
15784 (Added in 1.0.26)
15786 guestfs_vgchange_uuid
15788 int
15789 guestfs_vgchange_uuid (guestfs_h *g,
15790 const char *vg);
15791 Generate a new random UUID for the volume group "vg".
15793 This function returns 0 on success or -1 on error.
15795 This function depends on the feature "lvm2". See also
15797 "guestfs_feature_available".
15798 (Added in 1.19.26)
15800 guestfs_vgchange_uuid_all
15802 int
15803 guestfs_vgchange_uuid_all (guestfs_h *g);
15804 Generate new random UUIDs for all volume groups.
15806 This function returns 0 on success or -1 on error.
15808 This function depends on the feature "lvm2". See also
15810 "guestfs_feature_available".
15811 (Added in 1.19.26)
15813 guestfs_vgcreate
15815 int
15816 guestfs_vgcreate (guestfs_h *g,
15817 const char *volgroup,
15818 char *const *physvols);
15819 This creates an LVM volume group called "volgroup" from the non-empty
15821 list of physical volumes "physvols".
15822 This function returns 0 on success or -1 on error.
15824 This function depends on the feature "lvm2". See also
15826 "guestfs_feature_available".
15827 (Added in 0.8)
15829 guestfs_vglvuuids
15831 char **
15832 guestfs_vglvuuids (guestfs_h *g,
15833 const char *vgname);
15834 Given a VG called "vgname", this returns the UUIDs of all the logical
15836 volumes created in this volume group.
15837 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15839 associate logical volumes and volume groups.
15840 See also "guestfs_vgpvuuids".
15842 This function returns a NULL-terminated array of strings (like
15844 environ(3)), or NULL if there was an error. The caller must free the
15845 strings and the array after use.
15846 (Added in 1.0.87)
15848 guestfs_vgmeta
15850 char *
15851 guestfs_vgmeta (guestfs_h *g,
15852 const char *vgname,
15853 size_t *size_r);
15854 "vgname" is an LVM volume group. This command examines the volume
15856 group and returns its metadata.
15857 Note that the metadata is an internal structure used by LVM, subject to
15859 change at any time, and is provided for information only.
15860 This function returns a buffer, or NULL on error. The size of the
15862 returned buffer is written to *size_r. The caller must free the
15863 returned buffer after use.
15864 This function depends on the feature "lvm2". See also
15866 "guestfs_feature_available".
15867 (Added in 1.17.20)
15869 guestfs_vgpvuuids
15871 char **
15872 guestfs_vgpvuuids (guestfs_h *g,
15873 const char *vgname);
15874 Given a VG called "vgname", this returns the UUIDs of all the physical
15876 volumes that this volume group resides on.
15877 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15879 associate physical volumes and volume groups.
15880 See also "guestfs_vglvuuids".
15882 This function returns a NULL-terminated array of strings (like
15884 environ(3)), or NULL if there was an error. The caller must free the
15885 strings and the array after use.
15886 (Added in 1.0.87)
15888 guestfs_vgremove
15890 int
15891 guestfs_vgremove (guestfs_h *g,
15892 const char *vgname);
15893 Remove an LVM volume group "vgname", (for example "VG").
15895 This also forcibly removes all logical volumes in the volume group (if
15897 any).
15898 This function returns 0 on success or -1 on error.
15900 This function depends on the feature "lvm2". See also
15902 "guestfs_feature_available".
15903 (Added in 1.0.13)
15905 guestfs_vgrename
15907 int
15908 guestfs_vgrename (guestfs_h *g,
15909 const char *volgroup,
15910 const char *newvolgroup);
15911 Rename a volume group "volgroup" with the new name "newvolgroup".
15913 This function returns 0 on success or -1 on error.
15915 (Added in 1.0.83)
15917 guestfs_vgs
15919 char **
15920 guestfs_vgs (guestfs_h *g);
15921 List all the volumes groups detected. This is the equivalent of the
15923 vgs(8) command.
15924 This returns a list of just the volume group names that were detected
15926 (eg. "VolGroup00").
15927 See also "guestfs_vgs_full".
15929 This function returns a NULL-terminated array of strings (like
15931 environ(3)), or NULL if there was an error. The caller must free the
15932 strings and the array after use.
15933 This function depends on the feature "lvm2". See also
15935 "guestfs_feature_available".
15936 (Added in 0.4)
15938 guestfs_vgs_full
15940 struct guestfs_lvm_vg_list *
15941 guestfs_vgs_full (guestfs_h *g);
15942 List all the volumes groups detected. This is the equivalent of the
15944 vgs(8) command. The "full" version includes all fields.
15945 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
15947 there was an error. The caller must call "guestfs_free_lvm_vg_list"
15948 after use.
15949 This function depends on the feature "lvm2". See also
15951 "guestfs_feature_available".
15952 (Added in 0.4)
15954 guestfs_vgscan
15956 int
15957 guestfs_vgscan (guestfs_h *g);
15958 This function is deprecated. In new code, use the "guestfs_lvm_scan"
15960 call instead.
15961 Deprecated functions will not be removed from the API, but the fact
15963 that they are deprecated indicates that there are problems with correct
15964 use of these functions.
15965 This rescans all block devices and rebuilds the list of LVM physical
15967 volumes, volume groups and logical volumes.
15968 This function returns 0 on success or -1 on error.
15970 (Added in 1.3.2)
15972 guestfs_vguuid
15974 char *
15975 guestfs_vguuid (guestfs_h *g,
15976 const char *vgname);
15977 This command returns the UUID of the LVM VG named "vgname".
15979 This function returns a string, or NULL on error. The caller must free
15981 the returned string after use.
15982 (Added in 1.0.87)
15984 guestfs_wait_ready
15986 int
15987 guestfs_wait_ready (guestfs_h *g);
15988 This function is deprecated. There is no replacement. Consult the API
15990 documentation in guestfs(3) for further information.
15991 Deprecated functions will not be removed from the API, but the fact
15993 that they are deprecated indicates that there are problems with correct
15994 use of these functions.
15995 This function is a no op.
15997 In versions of the API < 1.0.71 you had to call this function just
15999 after calling "guestfs_launch" to wait for the launch to complete.
16000 However this is no longer necessary because "guestfs_launch" now does
16001 the waiting.
16002 If you see any calls to this function in code then you can just remove
16004 them, unless you want to retain compatibility with older versions of
16005 the API.
16006 This function returns 0 on success or -1 on error.
16008 (Added in 0.3)
16010 guestfs_wc_c
16012 int
16013 guestfs_wc_c (guestfs_h *g,
16014 const char *path);
16015 This command counts the characters in a file, using the "wc -c"
16017 external command.
16018 On error this function returns -1.
16020 (Added in 1.0.54)
16022 guestfs_wc_l
16024 int
16025 guestfs_wc_l (guestfs_h *g,
16026 const char *path);
16027 This command counts the lines in a file, using the "wc -l" external
16029 command.
16030 On error this function returns -1.
16032 (Added in 1.0.54)
16034 guestfs_wc_w
16036 int
16037 guestfs_wc_w (guestfs_h *g,
16038 const char *path);
16039 This command counts the words in a file, using the "wc -w" external
16041 command.
16042 On error this function returns -1.
16044 (Added in 1.0.54)
16046 guestfs_wipefs
16048 int
16049 guestfs_wipefs (guestfs_h *g,
16050 const char *device);
16051 This command erases filesystem or RAID signatures from the specified
16053 "device" to make the filesystem invisible to libblkid.
16054 This does not erase the filesystem itself nor any other data from the
16056 "device".
16057 Compare with "guestfs_zero" which zeroes the first few blocks of a
16059 device.
16060 This function returns 0 on success or -1 on error.
16062 This function depends on the feature "wipefs". See also
16064 "guestfs_feature_available".
16065 (Added in 1.17.6)
16067 guestfs_write
16069 int
16070 guestfs_write (guestfs_h *g,
16071 const char *path,
16072 const char *content,
16073 size_t content_size);
16074 This call creates a file called "path". The content of the file is the
16076 string "content" (which can contain any 8 bit data).
16077 See also "guestfs_write_append".
16079 This function returns 0 on success or -1 on error.
16081 (Added in 1.3.14)
16083 guestfs_write_append
16085 int
16086 guestfs_write_append (guestfs_h *g,
16087 const char *path,
16088 const char *content,
16089 size_t content_size);
16090 This call appends "content" to the end of file "path". If "path" does
16092 not exist, then a new file is created.
16093 See also "guestfs_write".
16095 This function returns 0 on success or -1 on error.
16097 (Added in 1.11.18)
16099 guestfs_write_file
16101 int
16102 guestfs_write_file (guestfs_h *g,
16103 const char *path,
16104 const char *content,
16105 int size);
16106 This function is deprecated. In new code, use the "guestfs_write" call
16108 instead.
16109 Deprecated functions will not be removed from the API, but the fact
16111 that they are deprecated indicates that there are problems with correct
16112 use of these functions.
16113 This call creates a file called "path". The contents of the file is
16115 the string "content" (which can contain any 8 bit data), with length
16116 "size".
16117 As a special case, if "size" is 0 then the length is calculated using
16119 "strlen" (so in this case the content cannot contain embedded ASCII
16120 NULs).
16121 NB. Owing to a bug, writing content containing ASCII NUL characters
16123 does not work, even if the length is specified.
16124 This function returns 0 on success or -1 on error.
16126 Because of the message protocol, there is a transfer limit of somewhere
16128 between 2MB and 4MB. See "PROTOCOL LIMITS".
16129 (Added in 0.8)
16131 guestfs_xfs_admin
16133 int
16134 guestfs_xfs_admin (guestfs_h *g,
16135 const char *device,
16136 ...);
16137 You may supply a list of optional arguments to this call. Use zero or
16139 more of the following pairs of parameters, and terminate the list with
16140 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16141 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16143 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16144 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16145 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16146 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16147 GUESTFS_XFS_ADMIN_LABEL, const char *label,
16148 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16149 Change the parameters of the XFS filesystem on "device".
16151 Devices that are mounted cannot be modified. Administrators must
16153 unmount filesystems before this call can modify parameters.
16154 Some of the parameters of a mounted filesystem can be examined and
16156 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16157 Beginning with XFS version 5, it is no longer possible to modify the
16159 lazy-counters setting (ie. "lazycounter" parameter has no effect).
16160 This function returns 0 on success or -1 on error.
16162 This function depends on the feature "xfs". See also
16164 "guestfs_feature_available".
16165 (Added in 1.19.33)
16167 guestfs_xfs_admin_va
16169 int
16170 guestfs_xfs_admin_va (guestfs_h *g,
16171 const char *device,
16172 va_list args);
16173 This is the "va_list variant" of "guestfs_xfs_admin".
16175 See "CALLS WITH OPTIONAL ARGUMENTS".
16177 guestfs_xfs_admin_argv
16179 int
16180 guestfs_xfs_admin_argv (guestfs_h *g,
16181 const char *device,
16182 const struct guestfs_xfs_admin_argv *optargs);
16183 This is the "argv variant" of "guestfs_xfs_admin".
16185 See "CALLS WITH OPTIONAL ARGUMENTS".
16187 guestfs_xfs_growfs
16189 int
16190 guestfs_xfs_growfs (guestfs_h *g,
16191 const char *path,
16192 ...);
16193 You may supply a list of optional arguments to this call. Use zero or
16195 more of the following pairs of parameters, and terminate the list with
16196 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16197 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16199 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16200 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16201 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16202 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16203 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16204 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16205 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16206 Grow the XFS filesystem mounted at "path".
16208 The returned struct contains geometry information. Missing fields are
16210 returned as "-1" (for numeric fields) or empty string.
16211 This function returns 0 on success or -1 on error.
16213 This function depends on the feature "xfs". See also
16215 "guestfs_feature_available".
16216 (Added in 1.19.28)
16218 guestfs_xfs_growfs_va
16220 int
16221 guestfs_xfs_growfs_va (guestfs_h *g,
16222 const char *path,
16223 va_list args);
16224 This is the "va_list variant" of "guestfs_xfs_growfs".
16226 See "CALLS WITH OPTIONAL ARGUMENTS".
16228 guestfs_xfs_growfs_argv
16230 int
16231 guestfs_xfs_growfs_argv (guestfs_h *g,
16232 const char *path,
16233 const struct guestfs_xfs_growfs_argv *optargs);
16234 This is the "argv variant" of "guestfs_xfs_growfs".
16236 See "CALLS WITH OPTIONAL ARGUMENTS".
16238 guestfs_xfs_info
16240 struct guestfs_xfsinfo *
16241 guestfs_xfs_info (guestfs_h *g,
16242 const char *pathordevice);
16243 "pathordevice" is a mounted XFS filesystem or a device containing an
16245 XFS filesystem. This command returns the geometry of the filesystem.
16246 The returned struct contains geometry information. Missing fields are
16248 returned as "-1" (for numeric fields) or empty string.
16249 This function returns a "struct guestfs_xfsinfo *", or NULL if there
16251 was an error. The caller must call "guestfs_free_xfsinfo" after use.
16252 This function depends on the feature "xfs". See also
16254 "guestfs_feature_available".
16255 (Added in 1.19.21)
16257 guestfs_xfs_repair
16259 int
16260 guestfs_xfs_repair (guestfs_h *g,
16261 const char *device,
16262 ...);
16263 You may supply a list of optional arguments to this call. Use zero or
16265 more of the following pairs of parameters, and terminate the list with
16266 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16267 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16269 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16270 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16271 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16272 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16273 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16274 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16275 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16276 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16277 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16278 Repair corrupt or damaged XFS filesystem on "device".
16280 The filesystem is specified using the "device" argument which should be
16282 the device name of the disk partition or volume containing the
16283 filesystem. If given the name of a block device, "xfs_repair" will
16284 attempt to find the raw device associated with the specified block
16285 device and will use the raw device instead.
16286 Regardless, the filesystem to be repaired must be unmounted, otherwise,
16288 the resulting filesystem may be inconsistent or corrupt.
16289 The returned status indicates whether filesystem corruption was
16291 detected (returns 1) or was not detected (returns 0).
16292 On error this function returns -1.
16294 This function depends on the feature "xfs". See also
16296 "guestfs_feature_available".
16297 (Added in 1.19.36)
16299 guestfs_xfs_repair_va
16301 int
16302 guestfs_xfs_repair_va (guestfs_h *g,
16303 const char *device,
16304 va_list args);
16305 This is the "va_list variant" of "guestfs_xfs_repair".
16307 See "CALLS WITH OPTIONAL ARGUMENTS".
16309 guestfs_xfs_repair_argv
16311 int
16312 guestfs_xfs_repair_argv (guestfs_h *g,
16313 const char *device,
16314 const struct guestfs_xfs_repair_argv *optargs);
16315 This is the "argv variant" of "guestfs_xfs_repair".
16317 See "CALLS WITH OPTIONAL ARGUMENTS".
16319 guestfs_yara_destroy
16321 int
16322 guestfs_yara_destroy (guestfs_h *g);
16323 Destroy previously loaded Yara rules in order to free libguestfs
16325 resources.
16326 This function returns 0 on success or -1 on error.
16328 This function depends on the feature "libyara". See also
16330 "guestfs_feature_available".
16331 (Added in 1.37.13)
16333 guestfs_yara_load
16335 int
16336 guestfs_yara_load (guestfs_h *g,
16337 const char *filename);
16338 Upload a set of Yara rules from local file filename.
16340 Yara rules allow to categorize files based on textual or binary
16342 patterns within their content. See "guestfs_yara_scan" to see how to
16343 scan files with the loaded rules.
16344 Rules can be in binary format, as when compiled with yarac command, or
16346 in source code format. In the latter case, the rules will be first
16347 compiled and then loaded.
16348 Rules in source code format cannot include external files. In such
16350 cases, it is recommended to compile them first.
16351 Previously loaded rules will be destroyed.
16353 This function returns 0 on success or -1 on error.
16355 This long-running command can generate progress notification messages
16357 so that the caller can display a progress bar or indicator. To receive
16358 these messages, the caller must register a progress event callback.
16359 See "GUESTFS_EVENT_PROGRESS".
16360 This function depends on the feature "libyara". See also
16362 "guestfs_feature_available".
16363 (Added in 1.37.13)
16365 guestfs_yara_scan
16367 struct guestfs_yara_detection_list *
16368 guestfs_yara_scan (guestfs_h *g,
16369 const char *path);
16370 Scan a file with the previously loaded Yara rules.
16372 For each matching rule, a "yara_detection" structure is returned.
16374 The "yara_detection" structure contains the following fields.
16376 "yara_name"
16378 Path of the file matching a Yara rule.
16379 "yara_rule"
16381 Identifier of the Yara rule which matched against the given file.
16382 This function returns a "struct guestfs_yara_detection_list *", or NULL
16384 if there was an error. The caller must call
16385 "guestfs_free_yara_detection_list" after use.
16386 This long-running command can generate progress notification messages
16388 so that the caller can display a progress bar or indicator. To receive
16389 these messages, the caller must register a progress event callback.
16390 See "GUESTFS_EVENT_PROGRESS".
16391 This function depends on the feature "libyara". See also
16393 "guestfs_feature_available".
16394 (Added in 1.37.13)
16396 guestfs_zegrep
16398 char **
16399 guestfs_zegrep (guestfs_h *g,
16400 const char *regex,
16401 const char *path);
16402 This function is deprecated. In new code, use the "guestfs_grep" call
16404 instead.
16405 Deprecated functions will not be removed from the API, but the fact
16407 that they are deprecated indicates that there are problems with correct
16408 use of these functions.
16409 This calls the external "zegrep" program and returns the matching
16411 lines.
16412 This function returns a NULL-terminated array of strings (like
16414 environ(3)), or NULL if there was an error. The caller must free the
16415 strings and the array after use.
16416 Because of the message protocol, there is a transfer limit of somewhere
16418 between 2MB and 4MB. See "PROTOCOL LIMITS".
16419 (Added in 1.0.66)
16421 guestfs_zegrepi
16423 char **
16424 guestfs_zegrepi (guestfs_h *g,
16425 const char *regex,
16426 const char *path);
16427 This function is deprecated. In new code, use the "guestfs_grep" call
16429 instead.
16430 Deprecated functions will not be removed from the API, but the fact
16432 that they are deprecated indicates that there are problems with correct
16433 use of these functions.
16434 This calls the external "zegrep -i" program and returns the matching
16436 lines.
16437 This function returns a NULL-terminated array of strings (like
16439 environ(3)), or NULL if there was an error. The caller must free the
16440 strings and the array after use.
16441 Because of the message protocol, there is a transfer limit of somewhere
16443 between 2MB and 4MB. See "PROTOCOL LIMITS".
16444 (Added in 1.0.66)
16446 guestfs_zero
16448 int
16449 guestfs_zero (guestfs_h *g,
16450 const char *device);
16451 This command writes zeroes over the first few blocks of "device".
16453 How many blocks are zeroed isn't specified (but it’s not enough to
16455 securely wipe the device). It should be sufficient to remove any
16456 partition tables, filesystem superblocks and so on.
16457 If blocks are already zero, then this command avoids writing zeroes.
16459 This prevents the underlying device from becoming non-sparse or growing
16460 unnecessarily.
16461 See also: "guestfs_zero_device", "guestfs_scrub_device",
16463 "guestfs_is_zero_device"
16464 This function returns 0 on success or -1 on error.
16466 This long-running command can generate progress notification messages
16468 so that the caller can display a progress bar or indicator. To receive
16469 these messages, the caller must register a progress event callback.
16470 See "GUESTFS_EVENT_PROGRESS".
16471 (Added in 1.0.16)
16473 guestfs_zero_device
16475 int
16476 guestfs_zero_device (guestfs_h *g,
16477 const char *device);
16478 This command writes zeroes over the entire "device". Compare with
16480 "guestfs_zero" which just zeroes the first few blocks of a device.
16481 If blocks are already zero, then this command avoids writing zeroes.
16483 This prevents the underlying device from becoming non-sparse or growing
16484 unnecessarily.
16485 This function returns 0 on success or -1 on error.
16487 This long-running command can generate progress notification messages
16489 so that the caller can display a progress bar or indicator. To receive
16490 these messages, the caller must register a progress event callback.
16491 See "GUESTFS_EVENT_PROGRESS".
16492 (Added in 1.3.1)
16494 guestfs_zero_free_space
16496 int
16497 guestfs_zero_free_space (guestfs_h *g,
16498 const char *directory);
16499 Zero the free space in the filesystem mounted on directory. The
16501 filesystem must be mounted read-write.
16502 The filesystem contents are not affected, but any free space in the
16504 filesystem is freed.
16505 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16507 either as an alternative to this, or after calling this, depending on
16508 your requirements.
16509 This function returns 0 on success or -1 on error.
16511 This long-running command can generate progress notification messages
16513 so that the caller can display a progress bar or indicator. To receive
16514 these messages, the caller must register a progress event callback.
16515 See "GUESTFS_EVENT_PROGRESS".
16516 (Added in 1.17.18)
16518 guestfs_zerofree
16520 int
16521 guestfs_zerofree (guestfs_h *g,
16522 const char *device);
16523 This runs the zerofree program on "device". This program claims to
16525 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16526 it possible to compress the filesystem more effectively.
16527 You should not run this program if the filesystem is mounted.
16529 It is possible that using this program can damage the filesystem or
16531 data on the filesystem.
16532 This function returns 0 on success or -1 on error.
16534 This function depends on the feature "zerofree". See also
16536 "guestfs_feature_available".
16537 (Added in 1.0.26)
16539 guestfs_zfgrep
16541 char **
16542 guestfs_zfgrep (guestfs_h *g,
16543 const char *pattern,
16544 const char *path);
16545 This function is deprecated. In new code, use the "guestfs_grep" call
16547 instead.
16548 Deprecated functions will not be removed from the API, but the fact
16550 that they are deprecated indicates that there are problems with correct
16551 use of these functions.
16552 This calls the external "zfgrep" program and returns the matching
16554 lines.
16555 This function returns a NULL-terminated array of strings (like
16557 environ(3)), or NULL if there was an error. The caller must free the
16558 strings and the array after use.
16559 Because of the message protocol, there is a transfer limit of somewhere
16561 between 2MB and 4MB. See "PROTOCOL LIMITS".
16562 (Added in 1.0.66)
16564 guestfs_zfgrepi
16566 char **
16567 guestfs_zfgrepi (guestfs_h *g,
16568 const char *pattern,
16569 const char *path);
16570 This function is deprecated. In new code, use the "guestfs_grep" call
16572 instead.
16573 Deprecated functions will not be removed from the API, but the fact
16575 that they are deprecated indicates that there are problems with correct
16576 use of these functions.
16577 This calls the external "zfgrep -i" program and returns the matching
16579 lines.
16580 This function returns a NULL-terminated array of strings (like
16582 environ(3)), or NULL if there was an error. The caller must free the
16583 strings and the array after use.
16584 Because of the message protocol, there is a transfer limit of somewhere
16586 between 2MB and 4MB. See "PROTOCOL LIMITS".
16587 (Added in 1.0.66)
16589 guestfs_zfile
16591 char *
16592 guestfs_zfile (guestfs_h *g,
16593 const char *meth,
16594 const char *path);
16595 This function is deprecated. In new code, use the "guestfs_file" call
16597 instead.
16598 Deprecated functions will not be removed from the API, but the fact
16600 that they are deprecated indicates that there are problems with correct
16601 use of these functions.
16602 This command runs file(1) after first decompressing "path" using
16604 "meth".
16605 "meth" must be one of "gzip", "compress" or "bzip2".
16607 Since 1.0.63, use "guestfs_file" instead which can now process
16609 compressed files.
16610 This function returns a string, or NULL on error. The caller must free
16612 the returned string after use.
16613 (Added in 1.0.59)
16615 guestfs_zgrep
16617 char **
16618 guestfs_zgrep (guestfs_h *g,
16619 const char *regex,
16620 const char *path);
16621 This function is deprecated. In new code, use the "guestfs_grep" call
16623 instead.
16624 Deprecated functions will not be removed from the API, but the fact
16626 that they are deprecated indicates that there are problems with correct
16627 use of these functions.
16628 This calls the external zgrep(1) program and returns the matching
16630 lines.
16631 This function returns a NULL-terminated array of strings (like
16633 environ(3)), or NULL if there was an error. The caller must free the
16634 strings and the array after use.
16635 Because of the message protocol, there is a transfer limit of somewhere
16637 between 2MB and 4MB. See "PROTOCOL LIMITS".
16638 (Added in 1.0.66)
16640 guestfs_zgrepi
16642 char **
16643 guestfs_zgrepi (guestfs_h *g,
16644 const char *regex,
16645 const char *path);
16646 This function is deprecated. In new code, use the "guestfs_grep" call
16648 instead.
16649 Deprecated functions will not be removed from the API, but the fact
16651 that they are deprecated indicates that there are problems with correct
16652 use of these functions.
16653 This calls the external "zgrep -i" program and returns the matching
16655 lines.
16656 This function returns a NULL-terminated array of strings (like
16658 environ(3)), or NULL if there was an error. The caller must free the
16659 strings and the array after use.
16660 Because of the message protocol, there is a transfer limit of somewhere
16662 between 2MB and 4MB. See "PROTOCOL LIMITS".
16663 (Added in 1.0.66)
16665
16667 guestfs_int_bool
16668 struct guestfs_int_bool {
16669 int32_t i;
16670 int32_t b;
16671 };
16672 struct guestfs_int_bool_list {
16674 uint32_t len; /* Number of elements in list. */
16675 struct guestfs_int_bool *val; /* Elements. */
16676 };
16677 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16679 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16680 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16682 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16683 void guestfs_free_int_bool (struct guestfs_int_bool *);
16685 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16686 guestfs_lvm_pv
16688 struct guestfs_lvm_pv {
16689 char *pv_name;
16690 /* The next field is NOT nul-terminated, be careful when printing it: */
16691 char pv_uuid[32];
16692 char *pv_fmt;
16693 uint64_t pv_size;
16694 uint64_t dev_size;
16695 uint64_t pv_free;
16696 uint64_t pv_used;
16697 char *pv_attr;
16698 int64_t pv_pe_count;
16699 int64_t pv_pe_alloc_count;
16700 char *pv_tags;
16701 uint64_t pe_start;
16702 int64_t pv_mda_count;
16703 uint64_t pv_mda_free;
16704 };
16705 struct guestfs_lvm_pv_list {
16707 uint32_t len; /* Number of elements in list. */
16708 struct guestfs_lvm_pv *val; /* Elements. */
16709 };
16710 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16712 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16713 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16715 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16716 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16718 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16719 guestfs_lvm_vg
16721 struct guestfs_lvm_vg {
16722 char *vg_name;
16723 /* The next field is NOT nul-terminated, be careful when printing it: */
16724 char vg_uuid[32];
16725 char *vg_fmt;
16726 char *vg_attr;
16727 uint64_t vg_size;
16728 uint64_t vg_free;
16729 char *vg_sysid;
16730 uint64_t vg_extent_size;
16731 int64_t vg_extent_count;
16732 int64_t vg_free_count;
16733 int64_t max_lv;
16734 int64_t max_pv;
16735 int64_t pv_count;
16736 int64_t lv_count;
16737 int64_t snap_count;
16738 int64_t vg_seqno;
16739 char *vg_tags;
16740 int64_t vg_mda_count;
16741 uint64_t vg_mda_free;
16742 };
16743 struct guestfs_lvm_vg_list {
16745 uint32_t len; /* Number of elements in list. */
16746 struct guestfs_lvm_vg *val; /* Elements. */
16747 };
16748 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16750 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16751 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16753 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16754 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16756 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16757 guestfs_lvm_lv
16759 struct guestfs_lvm_lv {
16760 char *lv_name;
16761 /* The next field is NOT nul-terminated, be careful when printing it: */
16762 char lv_uuid[32];
16763 char *lv_attr;
16764 int64_t lv_major;
16765 int64_t lv_minor;
16766 int64_t lv_kernel_major;
16767 int64_t lv_kernel_minor;
16768 uint64_t lv_size;
16769 int64_t seg_count;
16770 char *origin;
16771 /* The next field is [0..100] or -1 meaning 'not present': */
16772 float snap_percent;
16773 /* The next field is [0..100] or -1 meaning 'not present': */
16774 float copy_percent;
16775 char *move_pv;
16776 char *lv_tags;
16777 char *mirror_log;
16778 char *modules;
16779 };
16780 struct guestfs_lvm_lv_list {
16782 uint32_t len; /* Number of elements in list. */
16783 struct guestfs_lvm_lv *val; /* Elements. */
16784 };
16785 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16787 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16788 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16790 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16791 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16793 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16794 guestfs_stat
16796 struct guestfs_stat {
16797 int64_t dev;
16798 int64_t ino;
16799 int64_t mode;
16800 int64_t nlink;
16801 int64_t uid;
16802 int64_t gid;
16803 int64_t rdev;
16804 int64_t size;
16805 int64_t blksize;
16806 int64_t blocks;
16807 int64_t atime;
16808 int64_t mtime;
16809 int64_t ctime;
16810 };
16811 struct guestfs_stat_list {
16813 uint32_t len; /* Number of elements in list. */
16814 struct guestfs_stat *val; /* Elements. */
16815 };
16816 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16818 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16819 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16821 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16822 void guestfs_free_stat (struct guestfs_stat *);
16824 void guestfs_free_stat_list (struct guestfs_stat_list *);
16825 guestfs_statns
16827 struct guestfs_statns {
16828 int64_t st_dev;
16829 int64_t st_ino;
16830 int64_t st_mode;
16831 int64_t st_nlink;
16832 int64_t st_uid;
16833 int64_t st_gid;
16834 int64_t st_rdev;
16835 int64_t st_size;
16836 int64_t st_blksize;
16837 int64_t st_blocks;
16838 int64_t st_atime_sec;
16839 int64_t st_atime_nsec;
16840 int64_t st_mtime_sec;
16841 int64_t st_mtime_nsec;
16842 int64_t st_ctime_sec;
16843 int64_t st_ctime_nsec;
16844 int64_t st_spare1;
16845 int64_t st_spare2;
16846 int64_t st_spare3;
16847 int64_t st_spare4;
16848 int64_t st_spare5;
16849 int64_t st_spare6;
16850 };
16851 struct guestfs_statns_list {
16853 uint32_t len; /* Number of elements in list. */
16854 struct guestfs_statns *val; /* Elements. */
16855 };
16856 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16858 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16859 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16861 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16862 void guestfs_free_statns (struct guestfs_statns *);
16864 void guestfs_free_statns_list (struct guestfs_statns_list *);
16865 guestfs_statvfs
16867 struct guestfs_statvfs {
16868 int64_t bsize;
16869 int64_t frsize;
16870 int64_t blocks;
16871 int64_t bfree;
16872 int64_t bavail;
16873 int64_t files;
16874 int64_t ffree;
16875 int64_t favail;
16876 int64_t fsid;
16877 int64_t flag;
16878 int64_t namemax;
16879 };
16880 struct guestfs_statvfs_list {
16882 uint32_t len; /* Number of elements in list. */
16883 struct guestfs_statvfs *val; /* Elements. */
16884 };
16885 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16887 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16888 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16890 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16891 void guestfs_free_statvfs (struct guestfs_statvfs *);
16893 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16894 guestfs_dirent
16896 struct guestfs_dirent {
16897 int64_t ino;
16898 char ftyp;
16899 char *name;
16900 };
16901 struct guestfs_dirent_list {
16903 uint32_t len; /* Number of elements in list. */
16904 struct guestfs_dirent *val; /* Elements. */
16905 };
16906 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16908 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16909 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16911 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16912 void guestfs_free_dirent (struct guestfs_dirent *);
16914 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16915 guestfs_version
16917 struct guestfs_version {
16918 int64_t major;
16919 int64_t minor;
16920 int64_t release;
16921 char *extra;
16922 };
16923 struct guestfs_version_list {
16925 uint32_t len; /* Number of elements in list. */
16926 struct guestfs_version *val; /* Elements. */
16927 };
16928 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16930 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16931 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16933 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16934 void guestfs_free_version (struct guestfs_version *);
16936 void guestfs_free_version_list (struct guestfs_version_list *);
16937 guestfs_xattr
16939 struct guestfs_xattr {
16940 char *attrname;
16941 /* The next two fields describe a byte array. */
16942 uint32_t attrval_len;
16943 char *attrval;
16944 };
16945 struct guestfs_xattr_list {
16947 uint32_t len; /* Number of elements in list. */
16948 struct guestfs_xattr *val; /* Elements. */
16949 };
16950 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16952 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16953 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
16955 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
16956 void guestfs_free_xattr (struct guestfs_xattr *);
16958 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
16959 guestfs_inotify_event
16961 struct guestfs_inotify_event {
16962 int64_t in_wd;
16963 uint32_t in_mask;
16964 uint32_t in_cookie;
16965 char *in_name;
16966 };
16967 struct guestfs_inotify_event_list {
16969 uint32_t len; /* Number of elements in list. */
16970 struct guestfs_inotify_event *val; /* Elements. */
16971 };
16972 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
16974 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
16975 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
16977 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
16978 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
16980 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
16981 guestfs_partition
16983 struct guestfs_partition {
16984 int32_t part_num;
16985 uint64_t part_start;
16986 uint64_t part_end;
16987 uint64_t part_size;
16988 };
16989 struct guestfs_partition_list {
16991 uint32_t len; /* Number of elements in list. */
16992 struct guestfs_partition *val; /* Elements. */
16993 };
16994 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
16996 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
16997 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
16999 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
17000 void guestfs_free_partition (struct guestfs_partition *);
17002 void guestfs_free_partition_list (struct guestfs_partition_list *);
17003 guestfs_application
17005 struct guestfs_application {
17006 char *app_name;
17007 char *app_display_name;
17008 int32_t app_epoch;
17009 char *app_version;
17010 char *app_release;
17011 char *app_install_path;
17012 char *app_trans_path;
17013 char *app_publisher;
17014 char *app_url;
17015 char *app_source_package;
17016 char *app_summary;
17017 char *app_description;
17018 };
17019 struct guestfs_application_list {
17021 uint32_t len; /* Number of elements in list. */
17022 struct guestfs_application *val; /* Elements. */
17023 };
17024 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
17026 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
17027 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
17029 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
17030 void guestfs_free_application (struct guestfs_application *);
17032 void guestfs_free_application_list (struct guestfs_application_list *);
17033 guestfs_application2
17035 struct guestfs_application2 {
17036 char *app2_name;
17037 char *app2_display_name;
17038 int32_t app2_epoch;
17039 char *app2_version;
17040 char *app2_release;
17041 char *app2_arch;
17042 char *app2_install_path;
17043 char *app2_trans_path;
17044 char *app2_publisher;
17045 char *app2_url;
17046 char *app2_source_package;
17047 char *app2_summary;
17048 char *app2_description;
17049 char *app2_spare1;
17050 char *app2_spare2;
17051 char *app2_spare3;
17052 char *app2_spare4;
17053 };
17054 struct guestfs_application2_list {
17056 uint32_t len; /* Number of elements in list. */
17057 struct guestfs_application2 *val; /* Elements. */
17058 };
17059 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
17061 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
17062 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
17064 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
17065 void guestfs_free_application2 (struct guestfs_application2 *);
17067 void guestfs_free_application2_list (struct guestfs_application2_list *);
17068 guestfs_isoinfo
17070 struct guestfs_isoinfo {
17071 char *iso_system_id;
17072 char *iso_volume_id;
17073 uint32_t iso_volume_space_size;
17074 uint32_t iso_volume_set_size;
17075 uint32_t iso_volume_sequence_number;
17076 uint32_t iso_logical_block_size;
17077 char *iso_volume_set_id;
17078 char *iso_publisher_id;
17079 char *iso_data_preparer_id;
17080 char *iso_application_id;
17081 char *iso_copyright_file_id;
17082 char *iso_abstract_file_id;
17083 char *iso_bibliographic_file_id;
17084 int64_t iso_volume_creation_t;
17085 int64_t iso_volume_modification_t;
17086 int64_t iso_volume_expiration_t;
17087 int64_t iso_volume_effective_t;
17088 };
17089 struct guestfs_isoinfo_list {
17091 uint32_t len; /* Number of elements in list. */
17092 struct guestfs_isoinfo *val; /* Elements. */
17093 };
17094 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
17096 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
17097 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
17099 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
17100 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
17102 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
17103 guestfs_mdstat
17105 struct guestfs_mdstat {
17106 char *mdstat_device;
17107 int32_t mdstat_index;
17108 char *mdstat_flags;
17109 };
17110 struct guestfs_mdstat_list {
17112 uint32_t len; /* Number of elements in list. */
17113 struct guestfs_mdstat *val; /* Elements. */
17114 };
17115 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
17117 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
17118 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
17120 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
17121 void guestfs_free_mdstat (struct guestfs_mdstat *);
17123 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
17124 guestfs_btrfssubvolume
17126 struct guestfs_btrfssubvolume {
17127 uint64_t btrfssubvolume_id;
17128 uint64_t btrfssubvolume_top_level_id;
17129 char *btrfssubvolume_path;
17130 };
17131 struct guestfs_btrfssubvolume_list {
17133 uint32_t len; /* Number of elements in list. */
17134 struct guestfs_btrfssubvolume *val; /* Elements. */
17135 };
17136 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17138 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17139 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17141 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17142 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17144 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17145 guestfs_btrfsqgroup
17147 struct guestfs_btrfsqgroup {
17148 char *btrfsqgroup_id;
17149 uint64_t btrfsqgroup_rfer;
17150 uint64_t btrfsqgroup_excl;
17151 };
17152 struct guestfs_btrfsqgroup_list {
17154 uint32_t len; /* Number of elements in list. */
17155 struct guestfs_btrfsqgroup *val; /* Elements. */
17156 };
17157 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17159 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17160 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17162 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17163 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17165 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17166 guestfs_btrfsbalance
17168 struct guestfs_btrfsbalance {
17169 char *btrfsbalance_status;
17170 uint64_t btrfsbalance_total;
17171 uint64_t btrfsbalance_balanced;
17172 uint64_t btrfsbalance_considered;
17173 uint64_t btrfsbalance_left;
17174 };
17175 struct guestfs_btrfsbalance_list {
17177 uint32_t len; /* Number of elements in list. */
17178 struct guestfs_btrfsbalance *val; /* Elements. */
17179 };
17180 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17182 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17183 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17185 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17186 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17188 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17189 guestfs_btrfsscrub
17191 struct guestfs_btrfsscrub {
17192 uint64_t btrfsscrub_data_extents_scrubbed;
17193 uint64_t btrfsscrub_tree_extents_scrubbed;
17194 uint64_t btrfsscrub_data_bytes_scrubbed;
17195 uint64_t btrfsscrub_tree_bytes_scrubbed;
17196 uint64_t btrfsscrub_read_errors;
17197 uint64_t btrfsscrub_csum_errors;
17198 uint64_t btrfsscrub_verify_errors;
17199 uint64_t btrfsscrub_no_csum;
17200 uint64_t btrfsscrub_csum_discards;
17201 uint64_t btrfsscrub_super_errors;
17202 uint64_t btrfsscrub_malloc_errors;
17203 uint64_t btrfsscrub_uncorrectable_errors;
17204 uint64_t btrfsscrub_unverified_errors;
17205 uint64_t btrfsscrub_corrected_errors;
17206 uint64_t btrfsscrub_last_physical;
17207 };
17208 struct guestfs_btrfsscrub_list {
17210 uint32_t len; /* Number of elements in list. */
17211 struct guestfs_btrfsscrub *val; /* Elements. */
17212 };
17213 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17215 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17216 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17218 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17219 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17221 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17222 guestfs_xfsinfo
17224 struct guestfs_xfsinfo {
17225 char *xfs_mntpoint;
17226 uint32_t xfs_inodesize;
17227 uint32_t xfs_agcount;
17228 uint32_t xfs_agsize;
17229 uint32_t xfs_sectsize;
17230 uint32_t xfs_attr;
17231 uint32_t xfs_blocksize;
17232 uint64_t xfs_datablocks;
17233 uint32_t xfs_imaxpct;
17234 uint32_t xfs_sunit;
17235 uint32_t xfs_swidth;
17236 uint32_t xfs_dirversion;
17237 uint32_t xfs_dirblocksize;
17238 uint32_t xfs_cimode;
17239 char *xfs_logname;
17240 uint32_t xfs_logblocksize;
17241 uint32_t xfs_logblocks;
17242 uint32_t xfs_logversion;
17243 uint32_t xfs_logsectsize;
17244 uint32_t xfs_logsunit;
17245 uint32_t xfs_lazycount;
17246 char *xfs_rtname;
17247 uint32_t xfs_rtextsize;
17248 uint64_t xfs_rtblocks;
17249 uint64_t xfs_rtextents;
17250 };
17251 struct guestfs_xfsinfo_list {
17253 uint32_t len; /* Number of elements in list. */
17254 struct guestfs_xfsinfo *val; /* Elements. */
17255 };
17256 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17258 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17259 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17261 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17262 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17264 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17265 guestfs_utsname
17267 struct guestfs_utsname {
17268 char *uts_sysname;
17269 char *uts_release;
17270 char *uts_version;
17271 char *uts_machine;
17272 };
17273 struct guestfs_utsname_list {
17275 uint32_t len; /* Number of elements in list. */
17276 struct guestfs_utsname *val; /* Elements. */
17277 };
17278 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17280 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17281 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17283 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17284 void guestfs_free_utsname (struct guestfs_utsname *);
17286 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17287 guestfs_hivex_node
17289 struct guestfs_hivex_node {
17290 int64_t hivex_node_h;
17291 };
17292 struct guestfs_hivex_node_list {
17294 uint32_t len; /* Number of elements in list. */
17295 struct guestfs_hivex_node *val; /* Elements. */
17296 };
17297 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17299 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17300 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17302 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17303 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17305 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17306 guestfs_hivex_value
17308 struct guestfs_hivex_value {
17309 int64_t hivex_value_h;
17310 };
17311 struct guestfs_hivex_value_list {
17313 uint32_t len; /* Number of elements in list. */
17314 struct guestfs_hivex_value *val; /* Elements. */
17315 };
17316 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17318 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17319 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17321 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17322 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17324 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17325 guestfs_internal_mountable
17327 struct guestfs_internal_mountable {
17328 int32_t im_type;
17329 char *im_device;
17330 char *im_volume;
17331 };
17332 struct guestfs_internal_mountable_list {
17334 uint32_t len; /* Number of elements in list. */
17335 struct guestfs_internal_mountable *val; /* Elements. */
17336 };
17337 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17339 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17340 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17342 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17343 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17345 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17346 guestfs_tsk_dirent
17348 struct guestfs_tsk_dirent {
17349 uint64_t tsk_inode;
17350 char tsk_type;
17351 int64_t tsk_size;
17352 char *tsk_name;
17353 uint32_t tsk_flags;
17354 int64_t tsk_atime_sec;
17355 int64_t tsk_atime_nsec;
17356 int64_t tsk_mtime_sec;
17357 int64_t tsk_mtime_nsec;
17358 int64_t tsk_ctime_sec;
17359 int64_t tsk_ctime_nsec;
17360 int64_t tsk_crtime_sec;
17361 int64_t tsk_crtime_nsec;
17362 int64_t tsk_nlink;
17363 char *tsk_link;
17364 int64_t tsk_spare1;
17365 };
17366 struct guestfs_tsk_dirent_list {
17368 uint32_t len; /* Number of elements in list. */
17369 struct guestfs_tsk_dirent *val; /* Elements. */
17370 };
17371 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17373 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17374 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17376 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17377 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17379 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17380 guestfs_yara_detection
17382 struct guestfs_yara_detection {
17383 char *yara_name;
17384 char *yara_rule;
17385 };
17386 struct guestfs_yara_detection_list {
17388 uint32_t len; /* Number of elements in list. */
17389 struct guestfs_yara_detection *val; /* Elements. */
17390 };
17391 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17393 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17394 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17396 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17397 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17399 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17400
17402 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17403 Using "guestfs_available" you can test availability of the following
17404 groups of functions. This test queries the appliance to see if the
17405 appliance you are currently using supports the functionality.
17406 acl The following functions: "guestfs_acl_delete_def_file"
17408 "guestfs_acl_get_file" "guestfs_acl_set_file"
17409 blkdiscard
17411 The following functions: "guestfs_blkdiscard"
17412 blkdiscardzeroes
17414 The following functions: "guestfs_blkdiscardzeroes"
17415 btrfs
17417 The following functions: "guestfs_btrfs_balance_cancel"
17418 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17419 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17420 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17421 "guestfs_btrfs_filesystem_defragment"
17422 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17423 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17424 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17425 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17426 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17427 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17428 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17429 "guestfs_btrfs_rescue_chunk_recover"
17430 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17431 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17432 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17433 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17434 "guestfs_btrfs_subvolume_get_default"
17435 "guestfs_btrfs_subvolume_list"
17436 "guestfs_btrfs_subvolume_set_default"
17437 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17438 "guestfs_btrfstune_enable_extended_inode_refs"
17439 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17440 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17441 clevisluks
17443 The following functions: "guestfs_clevis_luks_unlock"
17444 extlinux
17446 The following functions: "guestfs_extlinux"
17447 f2fs
17449 The following functions: "guestfs_f2fs_expand"
17450 fstrim
17452 The following functions: "guestfs_fstrim"
17453 gdisk
17455 The following functions: "guestfs_part_expand_gpt"
17456 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17457 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17458 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17459 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17460 "guestfs_part_set_gpt_type"
17461 grub
17463 The following functions: "guestfs_grub_install"
17464 hivex
17466 The following functions: "guestfs_hivex_close"
17467 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17468 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17469 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17470 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17471 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17472 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17473 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17474 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17475 inotify
17477 The following functions: "guestfs_inotify_add_watch"
17478 "guestfs_inotify_close" "guestfs_inotify_files"
17479 "guestfs_inotify_init" "guestfs_inotify_read"
17480 "guestfs_inotify_rm_watch"
17481 journal
17483 The following functions: "guestfs_internal_journal_get"
17484 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17485 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17486 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17487 "guestfs_journal_skip"
17488 ldm The following functions: "guestfs_ldmtool_create_all"
17490 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17491 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17492 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17493 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17494 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17495 "guestfs_list_ldm_volumes"
17496 libtsk
17498 The following functions: "guestfs_internal_filesystem_walk"
17499 "guestfs_internal_find_inode"
17500 libyara
17502 The following functions: "guestfs_internal_yara_scan"
17503 "guestfs_yara_destroy" "guestfs_yara_load"
17504 linuxcaps
17506 The following functions: "guestfs_cap_get_file"
17507 "guestfs_cap_set_file"
17508 linuxfsuuid
17510 The following functions: "guestfs_mke2fs_JU"
17511 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17512 "guestfs_swapon_uuid"
17513 linuxmodules
17515 The following functions: "guestfs_modprobe"
17516 linuxxattrs
17518 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17519 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17520 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17521 "guestfs_removexattr" "guestfs_setxattr"
17522 luks
17524 The following functions: "guestfs_cryptsetup_close"
17525 "guestfs_cryptsetup_open" "guestfs_luks_add_key"
17526 "guestfs_luks_close" "guestfs_luks_format"
17527 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17528 "guestfs_luks_open" "guestfs_luks_open_ro" "guestfs_luks_uuid"
17529 lvm2
17531 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17532 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17533 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17534 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17535 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17536 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17537 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17538 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17539 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17540 "guestfs_vgs" "guestfs_vgs_full"
17541 mdadm
17543 The following functions: "guestfs_md_create" "guestfs_md_detail"
17544 "guestfs_md_stat" "guestfs_md_stop"
17545 mknod
17547 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17548 "guestfs_mknod_b" "guestfs_mknod_c"
17549 ntfs3g
17551 The following functions: "guestfs_ntfs_3g_probe"
17552 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17553 ntfsprogs
17555 The following functions: "guestfs_ntfsresize"
17556 "guestfs_ntfsresize_size"
17557 rsync
17559 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17560 "guestfs_rsync_out"
17561 scrub
17563 The following functions: "guestfs_scrub_device"
17564 "guestfs_scrub_file" "guestfs_scrub_freespace"
17565 selinux
17567 The following functions: "guestfs_getcon" "guestfs_setcon"
17568 selinuxrelabel
17570 The following functions: "guestfs_selinux_relabel"
17571 sleuthkit
17573 The following functions: "guestfs_download_blocks"
17574 "guestfs_download_inode"
17575 squashfs
17577 The following functions: "guestfs_mksquashfs"
17578 syslinux
17580 The following functions: "guestfs_syslinux"
17581 wipefs
17583 The following functions: "guestfs_wipefs"
17584 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17586 "guestfs_xfs_info" "guestfs_xfs_repair"
17587 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17589 zerofree
17591 The following functions: "guestfs_zerofree"
17592 FILESYSTEM AVAILABLE
17594 The "guestfs_filesystem_available" call tests whether a filesystem type
17595 is supported by the appliance kernel.
17596 This is mainly useful as a negative test. If this returns true, it
17598 doesn't mean that a particular filesystem can be mounted, since
17599 filesystems can fail for other reasons such as it being a later version
17600 of the filesystem, or having incompatible features.
17601 GUESTFISH supported COMMAND
17603 In guestfish(3) there is a handy interactive command "supported" which
17604 prints out the available groups and whether they are supported by this
17605 build of libguestfs. Note however that you have to do "run" first.
17606 SINGLE CALLS AT COMPILE TIME
17608 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17609 function, such as:
17610 #define GUESTFS_HAVE_DD 1
17612 if "guestfs_dd" is available.
17614 Before version 1.5.8, if you needed to test whether a single libguestfs
17616 function is available at compile time, we recommended using build tools
17617 such as autoconf or cmake. For example in autotools you could use:
17618 AC_CHECK_LIB([guestfs],[guestfs_create])
17620 AC_CHECK_FUNCS([guestfs_dd])
17621 which would result in "HAVE_GUESTFS_DD" being either defined or not
17623 defined in your program.
17624 SINGLE CALLS AT RUN TIME
17626 Testing at compile time doesn't guarantee that a function really exists
17627 in the library. The reason is that you might be dynamically linked
17628 against a previous libguestfs.so (dynamic library) which doesn't have
17629 the call. This situation unfortunately results in a segmentation
17630 fault, which is a shortcoming of the C dynamic linking system itself.
17631 You can use dlopen(3) to test if a function is available at run time,
17633 as in this example program (note that you still need the compile time
17634 check as well):
17635 #include <stdio.h>
17637 #include <stdlib.h>
17638 #include <unistd.h>
17639 #include <dlfcn.h>
17640 #include <guestfs.h>
17641 main ()
17643 {
17644 #ifdef GUESTFS_HAVE_DD
17645 void *dl;
17646 int has_function;
17647 /* Test if the function guestfs_dd is really available. */
17649 dl = dlopen (NULL, RTLD_LAZY);
17650 if (!dl) {
17651 fprintf (stderr, "dlopen: %s\n", dlerror ());
17652 exit (EXIT_FAILURE);
17653 }
17654 has_function = dlsym (dl, "guestfs_dd") != NULL;
17655 dlclose (dl);
17656 if (!has_function)
17658 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17659 else {
17660 printf ("this libguestfs.so has guestfs_dd function\n");
17661 /* Now it's safe to call
17662 guestfs_dd (g, "foo", "bar");
17663 */
17664 }
17665 #else
17666 printf ("guestfs_dd function was not found at compile time\n");
17667 #endif
17668 }
17669 You may think the above is an awful lot of hassle, and it is. There
17671 are other ways outside of the C linking system to ensure that this kind
17672 of incompatibility never arises, such as using package versioning:
17673 Requires: libguestfs >= 1.0.80
17675
17677 A recent feature of the API is the introduction of calls which take
17678 optional arguments. In C these are declared 3 ways. The main way is
17679 as a call which takes variable arguments (ie. "..."), as in this
17680 example:
17681 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17683 Call this with a list of optional arguments, terminated by "-1". So to
17685 call with no optional arguments specified:
17686 guestfs_add_drive_opts (g, filename, -1);
17688 With a single optional argument:
17690 guestfs_add_drive_opts (g, filename,
17692 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17693 -1);
17694 With two:
17696 guestfs_add_drive_opts (g, filename,
17698 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17699 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17700 -1);
17701 and so forth. Don’t forget the terminating "-1" otherwise Bad Things
17703 will happen!
17704 USING va_list FOR OPTIONAL ARGUMENTS
17706 The second variant has the same name with the suffix "_va", which works
17707 the same way but takes a "va_list". See the C manual for details. For
17708 the example function, this is declared:
17709 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17711 va_list args);
17712 CONSTRUCTING OPTIONAL ARGUMENTS
17714 The third variant is useful where you need to construct these calls.
17715 You pass in a structure where you fill in the optional fields. The
17716 structure has a bitmask as the first element which you must set to
17717 indicate which fields you have filled in. For our example function the
17718 structure and call are declared:
17719 struct guestfs_add_drive_opts_argv {
17721 uint64_t bitmask;
17722 int readonly;
17723 const char *format;
17724 /* ... */
17725 };
17726 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17727 const struct guestfs_add_drive_opts_argv *optargs);
17728 You could call it like this:
17730 struct guestfs_add_drive_opts_argv optargs = {
17732 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17733 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17734 .readonly = 1,
17735 .format = "qcow2"
17736 };
17737 guestfs_add_drive_opts_argv (g, filename, &optargs);
17739 Notes:
17741 • The "_BITMASK" suffix on each option name when specifying the
17743 bitmask.
17744 • You do not need to fill in all fields of the structure.
17746 • There must be a one-to-one correspondence between fields of the
17748 structure that are filled in, and bits set in the bitmask.
17749 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17751 In other languages, optional arguments are expressed in the way that is
17752 natural for that language. We refer you to the language-specific
17753 documentation for more details on that.
17754 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17756
17758 SETTING CALLBACKS TO HANDLE EVENTS
17759 Note: This section documents the generic event mechanism introduced in
17760 libguestfs 1.10, which you should use in new code if possible. The old
17761 functions "guestfs_set_log_message_callback",
17762 "guestfs_set_subprocess_quit_callback",
17763 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17764 "guestfs_set_progress_callback" are no longer documented in this manual
17765 page. Because of the ABI guarantee, the old functions continue to
17766 work.
17767 Handles generate events when certain things happen, such as log
17769 messages being generated, progress messages during long-running
17770 operations, or the handle being closed. The API calls described below
17771 let you register a callback to be called when events happen. You can
17772 register multiple callbacks (for the same, different or overlapping
17773 sets of events), and individually remove callbacks. If callbacks are
17774 not removed, then they remain in force until the handle is closed.
17775 In the current implementation, events are only generated synchronously:
17777 that means that events (and hence callbacks) can only happen while you
17778 are in the middle of making another libguestfs call. The callback is
17779 called in the same thread.
17780 Events may contain a payload, usually nothing (void), an array of 64
17782 bit unsigned integers, or a message buffer. Payloads are discussed
17783 later on.
17784 CLASSES OF EVENTS
17786 GUESTFS_EVENT_CLOSE (payload type: void)
17787 The callback function will be called while the handle is being
17788 closed (synchronously from "guestfs_close").
17789 Note that libguestfs installs an atexit(3) handler to try to clean
17791 up handles that are open when the program exits. This means that
17792 this callback might be called indirectly from exit(3), which can
17793 cause unexpected problems in higher-level languages (eg. if your
17794 HLL interpreter has already been cleaned up by the time this is
17795 called, and if your callback then jumps into some HLL function).
17796 If no callback is registered: the handle is closed without any
17798 callback being invoked.
17799 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17801 The callback function will be called when the child process quits,
17802 either asynchronously or if killed by "guestfs_kill_subprocess".
17803 (This corresponds to a transition from any state to the CONFIG
17804 state).
17805 If no callback is registered: the event is ignored.
17807 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17809 The callback function will be called when the child process becomes
17810 ready first time after it has been launched. (This corresponds to
17811 a transition from LAUNCHING to the READY state).
17812 If no callback is registered: the event is ignored.
17814 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17816 Some long-running operations can generate progress messages. If
17817 this callback is registered, then it will be called each time a
17818 progress message is generated (usually two seconds after the
17819 operation started, and three times per second thereafter until it
17820 completes, although the frequency may change in future versions).
17821 The callback receives in the payload four unsigned 64 bit numbers
17823 which are (in order): "proc_nr", "serial", "position", "total".
17824 The units of "total" are not defined, although for some operations
17826 "total" may relate in some way to the amount of data to be
17827 transferred (eg. in bytes or megabytes), and "position" may be the
17828 portion which has been transferred.
17829 The only defined and stable parts of the API are:
17831 • The callback can display to the user some type of progress bar
17833 or indicator which shows the ratio of "position":"total".
17834 • 0 <= "position" <= "total"
17836 • If any progress notification is sent during a call, then a
17838 final progress notification is always sent when "position" =
17839 "total" (unless the call fails with an error).
17840 This is to simplify caller code, so callers can easily set the
17842 progress indicator to "100%" at the end of the operation,
17843 without requiring special code to detect this case.
17844 • For some calls we are unable to estimate the progress of the
17846 call, but we can still generate progress messages to indicate
17847 activity. This is known as "pulse mode", and is directly
17848 supported by certain progress bar implementations (eg.
17849 GtkProgressBar).
17850 For these calls, zero or more progress messages are generated
17852 with "position = 0" and "total = 1", followed by a final
17853 message with "position = total = 1".
17854 As noted above, if the call fails with an error then the final
17856 message may not be generated.
17857 The callback also receives the procedure number ("proc_nr") and
17859 serial number ("serial") of the call. These are only useful for
17860 debugging protocol issues, and the callback can normally ignore
17861 them. The callback may want to print these numbers in error
17862 messages or debugging messages.
17863 If no callback is registered: progress messages are discarded.
17865 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17867 The callback function is called whenever a log message is generated
17868 by qemu, the appliance kernel, guestfsd (daemon), or utility
17869 programs.
17870 If the verbose flag ("guestfs_set_verbose") is set before launch
17872 ("guestfs_launch") then additional debug messages are generated.
17873 If no callback is registered: the messages are discarded unless the
17875 verbose flag is set in which case they are sent to stderr. You can
17876 override the printing of verbose messages to stderr by setting up a
17877 callback.
17878 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17880 The callback function is called whenever a log message is generated
17881 by the library part of libguestfs.
17882 If the verbose flag ("guestfs_set_verbose") is set then additional
17884 debug messages are generated.
17885 If no callback is registered: the messages are discarded unless the
17887 verbose flag is set in which case they are sent to stderr. You can
17888 override the printing of verbose messages to stderr by setting up a
17889 callback.
17890 GUESTFS_EVENT_WARNING (payload type: message buffer)
17892 The callback function is called whenever a warning message is
17893 generated by the library part of libguestfs.
17894 If no callback is registered: the messages are printed to stderr.
17896 You can override the printing of warning messages to stderr by
17897 setting up a callback.
17898 GUESTFS_EVENT_TRACE (payload type: message buffer)
17900 The callback function is called whenever a trace message is
17901 generated. This only applies if the trace flag
17902 ("guestfs_set_trace") is set.
17903 If no callback is registered: the messages are sent to stderr. You
17905 can override the printing of trace messages to stderr by setting up
17906 a callback.
17907 GUESTFS_EVENT_ENTER (payload type: function name)
17909 The callback function is called whenever a libguestfs function is
17910 entered.
17911 The payload is a string which contains the name of the function
17913 that we are entering (not including "guestfs_" prefix).
17914 Note that libguestfs functions can call themselves, so you may see
17916 many events from a single call. A few libguestfs functions do not
17917 generate this event.
17918 If no callback is registered: the event is ignored.
17920 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17922 For any API function that opens a libvirt connection, this event
17923 may be generated to indicate that libvirt demands authentication
17924 information. See "LIBVIRT AUTHENTICATION" below.
17925 If no callback is registered: "virConnectAuthPtrDefault" is used
17927 (suitable for command-line programs only).
17928 EVENT API
17930 guestfs_set_event_callback
17931 int guestfs_set_event_callback (guestfs_h *g,
17933 guestfs_event_callback cb,
17934 uint64_t event_bitmask,
17935 int flags,
17936 void *opaque);
17937 This function registers a callback ("cb") for all event classes in the
17939 "event_bitmask".
17940 For example, to register for all log message events, you could call
17942 this function with the bitmask
17943 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17944 To register a single callback for all possible classes of events, use
17945 "GUESTFS_EVENT_ALL".
17946 "flags" should always be passed as 0.
17948 "opaque" is an opaque pointer which is passed to the callback. You can
17950 use it for any purpose.
17951 The return value is the event handle (an integer) which you can use to
17953 delete the callback (see below).
17954 If there is an error, this function returns "-1", and sets the error in
17956 the handle in the usual way (see "guestfs_last_error" etc.)
17957 Callbacks remain in effect until they are deleted, or until the handle
17959 is closed.
17960 In the case where multiple callbacks are registered for a particular
17962 event class, all of the callbacks are called. The order in which
17963 multiple callbacks are called is not defined.
17964 guestfs_delete_event_callback
17966 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
17968 Delete a callback that was previously registered. "event_handle"
17970 should be the integer that was returned by a previous call to
17971 "guestfs_set_event_callback" on the same handle.
17972 guestfs_event_to_string
17974 char *guestfs_event_to_string (uint64_t event);
17976 "event" is either a single event or a bitmask of events. This returns
17978 a string representation (useful for debugging or printing events).
17979 A single event is returned as the name in lower case, eg. "close".
17981 A bitmask of several events is returned as a comma-separated list, eg.
17983 "close,progress".
17984 If zero is passed, then the empty string "" is returned.
17986 On success this returns a string. On error it returns NULL and sets
17988 "errno".
17989 The returned string must be freed by the caller.
17991 guestfs_event_callback
17993 typedef void (*guestfs_event_callback) (
17995 guestfs_h *g,
17996 void *opaque,
17997 uint64_t event,
17998 int event_handle,
17999 int flags,
18000 const char *buf, size_t buf_len,
18001 const uint64_t *array, size_t array_len);
18002 This is the type of the event callback function that you have to
18004 provide.
18005 The basic parameters are: the handle ("g"), the opaque user pointer
18007 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
18008 handle, and "flags" which in the current API you should ignore.
18009 The remaining parameters contain the event payload (if any). Each
18011 event may contain a payload, which usually relates to the event class,
18012 but for future proofing your code should be written to handle any
18013 payload for any event class.
18014 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
18016 there is no message buffer). Note that this message buffer can contain
18017 arbitrary 8 bit data, including NUL bytes.
18018 "array" and "array_len" is an array of 64 bit unsigned integers. At
18020 the moment this is only used for progress messages.
18021 EXAMPLE: CAPTURING LOG MESSAGES
18023 A working program demonstrating this can be found in
18024 examples/debug-logging.c in the source of libguestfs.
18025 One motivation for the generic event API was to allow GUI programs to
18027 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
18028 unconditionally to "stderr".
18029 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
18031 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
18032 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
18033 must capture error messages separately).
18034 Programs have to set up a callback to capture the classes of events of
18036 interest:
18037 int eh =
18039 guestfs_set_event_callback
18040 (g, message_callback,
18041 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
18042 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
18043 0, NULL) == -1)
18044 if (eh == -1) {
18045 // handle error in the usual way
18046 }
18047 The callback can then direct messages to the appropriate place. In
18049 this example, messages are directed to syslog:
18050 static void
18052 message_callback (
18053 guestfs_h *g,
18054 void *opaque,
18055 uint64_t event,
18056 int event_handle,
18057 int flags,
18058 const char *buf, size_t buf_len,
18059 const uint64_t *array, size_t array_len)
18060 {
18061 const int priority = LOG_USER|LOG_INFO;
18062 if (buf_len > 0)
18063 syslog (priority, "event 0x%lx: %s", event, buf);
18064 }
18065 LIBVIRT AUTHENTICATION
18067 Some libguestfs API calls can open libvirt connections. Currently the
18068 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
18069 backend has been selected. Libvirt connections may require
18070 authentication, for example if they need to access a remote server or
18071 to access root services from non-root. Libvirt authentication happens
18072 via a callback mechanism, see
18073 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
18074 You may provide libvirt authentication data by registering a callback
18076 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
18077 If no such event is registered, then libguestfs uses a libvirt function
18079 that provides command-line prompts ("virConnectAuthPtrDefault"). This
18080 is only suitable for command-line libguestfs programs.
18081 To provide authentication, first call
18083 "guestfs_set_libvirt_supported_credentials" with the list of
18084 credentials your program knows how to provide. Second, register a
18085 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
18086 will be called when libvirt is requesting authentication information.
18087 In the event handler, call "guestfs_get_libvirt_requested_credentials"
18089 to get a list of the credentials that libvirt is asking for. You then
18090 need to ask (eg. the user) for each credential, and call
18091 "guestfs_set_libvirt_requested_credential" with the answer. Note that
18092 for each credential, additional information may be available via the
18093 calls "guestfs_get_libvirt_requested_credential_prompt",
18094 "guestfs_get_libvirt_requested_credential_challenge" or
18095 "guestfs_get_libvirt_requested_credential_defresult".
18096 The example program below should make this clearer.
18098 There is also a more substantial working example program supplied with
18100 the libguestfs sources, called libvirt-auth.c.
18101 main ()
18103 {
18104 guestfs_h *g;
18105 char *creds[] = { "authname", "passphrase", NULL };
18106 int r, eh;
18107 g = guestfs_create ();
18109 if (!g) exit (EXIT_FAILURE);
18110 /* Tell libvirt what credentials the program supports. */
18112 r = guestfs_set_libvirt_supported_credentials (g, creds);
18113 if (r == -1)
18114 exit (EXIT_FAILURE);
18115 /* Set up the event handler. */
18117 eh = guestfs_set_event_callback (
18118 g, do_auth,
18119 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
18120 if (eh == -1)
18121 exit (EXIT_FAILURE);
18122 /* An example of a call that may ask for credentials. */
18124 r = guestfs_add_domain (
18125 g, "dom",
18126 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
18127 -1);
18128 if (r == -1)
18129 exit (EXIT_FAILURE);
18130 exit (EXIT_SUCCESS);
18132 }
18133 static void
18135 do_auth (guestfs_h *g,
18136 void *opaque,
18137 uint64_t event,
18138 int event_handle,
18139 int flags,
18140 const char *buf, size_t buf_len,
18141 const uint64_t *array, size_t array_len)
18142 {
18143 char **creds;
18144 size_t i;
18145 char *prompt;
18146 char *reply;
18147 size_t replylen;
18148 int r;
18149 // buf will be the libvirt URI. buf_len may be ignored.
18151 printf ("Authentication required for libvirt conn '%s'\n",
18152 buf);
18153 // Ask libguestfs what credentials libvirt is demanding.
18155 creds = guestfs_get_libvirt_requested_credentials (g);
18156 if (creds == NULL)
18157 exit (EXIT_FAILURE);
18158 // Now ask the user for answers.
18160 for (i = 0; creds[i] != NULL; ++i)
18161 {
18162 if (strcmp (creds[i], "authname") == 0 ||
18163 strcmp (creds[i], "passphrase") == 0)
18164 {
18165 prompt =
18166 guestfs_get_libvirt_requested_credential_prompt (g, i);
18167 if (prompt && strcmp (prompt, "") != 0)
18168 printf ("%s: ", prompt);
18169 free (prompt);
18170 // Some code here to ask for the credential.
18172 // ...
18173 // Put the reply in 'reply', length 'replylen' (bytes).
18174 r = guestfs_set_libvirt_requested_credential (g, i,
18176 reply, replylen);
18177 if (r == -1)
18178 exit (EXIT_FAILURE);
18179 }
18180 free (creds[i]);
18182 }
18183 free (creds);
18185 }
18186
18188 Some operations can be cancelled by the caller while they are in
18189 progress. Currently only operations that involve uploading or
18190 downloading data can be cancelled (technically: operations that have
18191 "FileIn" or "FileOut" parameters in the generator).
18192 To cancel the transfer, call "guestfs_user_cancel". For more
18194 information, read the description of "guestfs_user_cancel".
18195
18197 You can attach named pieces of private data to the libguestfs handle,
18198 fetch them by name, and walk over them, for the lifetime of the handle.
18199 This is called the private data area and is only available from the C
18200 API.
18201 To attach a named piece of data, use the following call:
18203 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18205 "key" is the name to associate with this data, and "data" is an
18207 arbitrary pointer (which can be "NULL"). Any previous item with the
18208 same key is overwritten.
18209 You can use any "key" string you want, but avoid keys beginning with an
18211 underscore character (libguestfs uses those for its own internal
18212 purposes, such as implementing language bindings). It is recommended
18213 that you prefix the key with some unique string to avoid collisions
18214 with other users.
18215 To retrieve the pointer, use:
18217 void *guestfs_get_private (guestfs_h *g, const char *key);
18219 This function returns "NULL" if either no data is found associated with
18221 "key", or if the user previously set the "key"’s "data" pointer to
18222 "NULL".
18223 Libguestfs does not try to look at or interpret the "data" pointer in
18225 any way. As far as libguestfs is concerned, it need not be a valid
18226 pointer at all. In particular, libguestfs does not try to free the
18227 data when the handle is closed. If the data must be freed, then the
18228 caller must either free it before calling "guestfs_close" or must set
18229 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18230 To walk over all entries, use these two functions:
18232 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18234 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18236 "guestfs_first_private" returns the first key, pointer pair ("first"
18238 does not have any particular meaning -- keys are not returned in any
18239 defined order). A pointer to the key is returned in *key_rtn and the
18240 corresponding data pointer is returned from the function. "NULL" is
18241 returned if there are no keys stored in the handle.
18242 "guestfs_next_private" returns the next key, pointer pair. The return
18244 value of this function is "NULL" if there are no further entries to
18245 return.
18246 Notes about walking over entries:
18248 • You must not call "guestfs_set_private" while walking over the
18250 entries.
18251 • The handle maintains an internal iterator which is reset when you
18253 call "guestfs_first_private". This internal iterator is
18254 invalidated when you call "guestfs_set_private".
18255 • If you have set the data pointer associated with a key to "NULL",
18257 ie:
18258 guestfs_set_private (g, key, NULL);
18260 then that "key" is not returned when walking.
18262 • *key_rtn is only valid until the next call to
18264 "guestfs_first_private", "guestfs_next_private" or
18265 "guestfs_set_private".
18266 The following example code shows how to print all keys and data
18268 pointers that are associated with the handle "g":
18269 const char *key;
18271 void *data = guestfs_first_private (g, &key);
18272 while (data != NULL)
18273 {
18274 printf ("key = %s, data = %p\n", key, data);
18275 data = guestfs_next_private (g, &key);
18276 }
18277 More commonly you are only interested in keys that begin with an
18279 application-specific prefix "foo_". Modify the loop like so:
18280 const char *key;
18282 void *data = guestfs_first_private (g, &key);
18283 while (data != NULL)
18284 {
18285 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18286 printf ("key = %s, data = %p\n", key, data);
18287 data = guestfs_next_private (g, &key);
18288 }
18289 If you need to modify keys while walking, then you have to jump back to
18291 the beginning of the loop. For example, to delete all keys prefixed
18292 with "foo_":
18293 const char *key;
18295 void *data;
18296 again:
18297 data = guestfs_first_private (g, &key);
18298 while (data != NULL)
18299 {
18300 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18301 {
18302 guestfs_set_private (g, key, NULL);
18303 /* note that 'key' pointer is now invalid, and so is
18304 the internal iterator */
18305 goto again;
18306 }
18307 data = guestfs_next_private (g, &key);
18308 }
18309 Note that the above loop is guaranteed to terminate because the keys
18311 are being deleted, but other manipulations of keys within the loop
18312 might not terminate unless you also maintain an indication of which
18313 keys have been visited.
18314
18316 Since April 2010, libguestfs has started to make separate development
18317 and stable releases, along with corresponding branches in our git
18318 repository. These separate releases can be identified by version
18319 number:
18320 even numbers for stable: 1.2.x, 1.4.x, ...
18322 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18323 |
18324 v
18325 1 . 3 . 5
18326 ^ ^
18327 | |
18328 | `-------- sub-version
18329 |
18330 `------ always '1' because we don't change the ABI
18331 Thus "1.3.5" is the 5th update to the development branch "1.3".
18333 As time passes we cherry pick fixes from the development branch and
18335 backport those into the stable branch, the effect being that the stable
18336 branch should get more stable and less buggy over time. So the stable
18337 releases are ideal for people who don't need new features but would
18338 just like the software to work.
18339 Our criteria for backporting changes are:
18341 • Documentation changes which don’t affect any code are backported
18343 unless the documentation refers to a future feature which is not in
18344 stable.
18345 • Bug fixes which are not controversial, fix obvious problems, and
18347 have been well tested are backported.
18348 • Simple rearrangements of code which shouldn't affect how it works
18350 get backported. This is so that the code in the two branches
18351 doesn't get too far out of step, allowing us to backport future
18352 fixes more easily.
18353 • We don’t backport new features, new APIs, new tools etc, except in
18355 one exceptional case: the new feature is required in order to
18356 implement an important bug fix.
18357 A new stable branch starts when we think the new features in
18359 development are substantial and compelling enough over the current
18360 stable branch to warrant it. When that happens we create new stable
18361 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18362 oh release won't necessarily be so stable at this point, but by
18363 backporting fixes from development, that branch will stabilize over
18364 time.
18365
18367 PROTOCOL LIMITS
18368 Internally libguestfs uses a message-based protocol to pass API calls
18369 and their responses to and from a small "appliance" (see
18370 guestfs-internals(1) for plenty more detail about this). The maximum
18371 message size used by the protocol is slightly less than 4 MB. For some
18372 API calls you may need to be aware of this limit. The API calls which
18373 may be affected are individually documented, with a link back to this
18374 section of the documentation.
18375 In libguestfs < 1.19.32, several calls had to encode either their
18377 entire argument list or their entire return value (or sometimes both)
18378 in a single protocol message, and this gave them an arbitrary
18379 limitation on how much data they could handle. For example,
18380 "guestfs_cat" could only download a file if it was less than around 4
18381 MB in size. In later versions of libguestfs, some of these limits have
18382 been removed. The APIs which were previously limited but are now
18383 unlimited (except perhaps by available memory) are listed below. To
18384 find out if a specific API is subject to protocol limits, check for the
18385 warning in the API documentation which links to this section, and
18386 remember to check the version of the documentation that matches the
18387 version of libguestfs you are using.
18388 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18390 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18391 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18392 "guestfs_ls".
18393 See also "UPLOADING" and "DOWNLOADING" for further information about
18395 copying large amounts of data into or out of a filesystem.
18396 MAXIMUM NUMBER OF DISKS
18398 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18399 may be added by calling "guestfs_max_disks". In earlier versions of
18400 libguestfs (ie. where this call is not available) you should assume the
18401 maximum is 25.
18402 The rest of this section covers implementation details, which could
18404 change in future.
18405 When using virtio-scsi disks (the default if available in qemu) the
18407 current limit is 255 disks. When using virtio-blk (the old default)
18408 the limit is around 27 disks, but may vary according to implementation
18409 details and whether the network is enabled.
18410 Virtio-scsi as used by libguestfs is configured to use one target per
18412 disk, and 256 targets are available.
18413 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18415 31 slots, but some of these are used for other purposes.
18416 One virtual disk is used by libguestfs internally.
18418 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18420 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18421 the limit was 25. This has been fixed in more recent versions.
18422 MAXIMUM NUMBER OF PARTITIONS PER DISK
18424 Virtio limits the maximum number of partitions per disk to 15.
18425 This is because it reserves 4 bits for the minor device number (thus
18427 /dev/vda, and /dev/vda1 through /dev/vda15).
18428 If you attach a disk with more than 15 partitions, the extra partitions
18430 are ignored by libguestfs.
18431 MAXIMUM SIZE OF A DISK
18433 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18434 We have tested block devices up to 1 exabyte (2**60 or
18436 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18437 host filesystem.
18438 Although libguestfs probably does not impose any limit, the underlying
18440 host storage will. If you store disk images on a host ext4 filesystem,
18441 then the maximum size will be limited by the maximum ext4 file size
18442 (currently 16 TB). If you store disk images as host logical volumes
18443 then you are limited by the maximum size of an LV.
18444 For the hugest disk image files, we recommend using XFS on the host for
18446 storage.
18447 MAXIMUM SIZE OF A PARTITION
18449 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18450 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18451 address a partition located beyond 2 TB on the disk.
18452 It is recommended that you use GPT partitions on disks which are larger
18454 than this size. GPT uses 64 bit sector numbers and so can address
18455 partitions which are theoretically larger than the largest disk we
18456 could support.
18457 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18459 This depends on the filesystem type. libguestfs itself does not impose
18460 any known limit. Consult Wikipedia or the filesystem documentation to
18461 find out what these limits are.
18462 MAXIMUM UPLOAD AND DOWNLOAD
18464 The API functions "guestfs_upload", "guestfs_download",
18465 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18466 uploads and downloads.
18467 INSPECTION LIMITS
18469 The inspection code has several arbitrary limits on things like the
18470 size of Windows Registry hive it will read, and the length of product
18471 name. These are intended to stop a malicious guest from consuming
18472 arbitrary amounts of memory and disk space on the host, and should not
18473 be reached in practice. See the source code for more information.
18474
18476 Some of the tools support a --machine-readable option, which is
18477 generally used to make the output more machine friendly, for easier
18478 parsing for example. By default, this output goes to stdout.
18479 When using the --machine-readable option, the progress, information,
18481 warning, and error messages are also printed in JSON format for easier
18482 log tracking. Thus, it is highly recommended to redirect the machine-
18483 readable output to a different stream. The format of these JSON
18484 messages is like the following (actually printed within a single line,
18485 below it is indented for readability):
18486 {
18488 "message": "Finishing off",
18489 "timestamp": "2019-03-22T14:46:49.067294446+01:00",
18490 "type": "message"
18491 }
18492 "type" can be: "message" for progress messages, "info" for information
18494 messages, "warning" for warning messages, and "error" for error
18495 message. "timestamp" is the RFC 3339 timestamp of the message.
18496 In addition to that, a subset of these tools support an extra string
18498 passed to the --machine-readable option: this string specifies where
18499 the machine-readable output will go.
18500 The possible values are:
18502 fd:fd
18504 The output goes to the specified fd, which is a file descriptor
18505 already opened for writing.
18506 file:filename
18508 The output goes to the specified filename.
18509 stream:stdout
18511 The output goes to stdout. This is basically the same as the
18512 default behaviour of --machine-readable with no parameter, although
18513 stdout as output is specified explicitly.
18514 stream:stderr
18516 The output goes to stderr.
18517
18519 LIBGUESTFS_APPEND
18520 Pass additional options to the guest kernel.
18521 LIBGUESTFS_ATTACH_METHOD
18523 This is the old way to set "LIBGUESTFS_BACKEND".
18524 LIBGUESTFS_BACKEND
18526 Choose the default way to create the appliance. See
18527 "guestfs_set_backend" and "BACKEND".
18528 LIBGUESTFS_BACKEND_SETTINGS
18530 A colon-separated list of backend-specific settings. See
18531 "BACKEND", "BACKEND SETTINGS".
18532 LIBGUESTFS_CACHEDIR
18534 The location where libguestfs will cache its appliance, when using
18535 a supermin appliance. The appliance is cached and shared between
18536 all handles which have the same effective user ID.
18537 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18539 "TMPDIR" is not set, then /var/tmp is used.
18540 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18542 LIBGUESTFS_DEBUG
18544 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18545 same effect as calling "guestfs_set_verbose (g, 1)".
18546 LIBGUESTFS_HV
18548 Set the default hypervisor (usually qemu) binary that libguestfs
18549 uses. If not set, then the qemu which was found at compile time by
18550 the configure script is used.
18551 See also "QEMU WRAPPERS" above.
18553 LIBGUESTFS_MEMSIZE
18555 Set the memory allocated to the qemu process, in megabytes. For
18556 example:
18557 LIBGUESTFS_MEMSIZE=700
18559 LIBGUESTFS_PATH
18561 Set the path that libguestfs uses to search for a supermin
18562 appliance. See the discussion of paths in section "PATH" above.
18563 LIBGUESTFS_QEMU
18565 This is the old way to set "LIBGUESTFS_HV".
18566 LIBGUESTFS_TMPDIR
18568 The location where libguestfs will store temporary files used by
18569 each handle.
18570 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18572 "TMPDIR" is not set, then /tmp is used.
18573 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18575 LIBGUESTFS_TRACE
18577 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18578 same effect as calling "guestfs_set_trace (g, 1)".
18579 PATH
18581 Libguestfs may run some external programs, and relies on $PATH
18582 being set to a reasonable value. If using the libvirt backend,
18583 libvirt will not work at all unless $PATH contains the path of
18584 qemu/KVM. Note that PHP by default removes $PATH from the
18585 environment which tends to break everything.
18586 SUPERMIN_KERNEL
18588 SUPERMIN_KERNEL_VERSION
18589 SUPERMIN_MODULES
18590 These three environment variables allow the kernel that libguestfs
18591 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18592 set, then the most recent host kernel is chosen. For more
18593 information about kernel selection, see supermin(1).
18594 TMPDIR
18596 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18597 XDG_RUNTIME_DIR
18599 This directory represents a user-specific directory for storing
18600 non-essential runtime files.
18601 If it is set, then is used to store temporary sockets. Otherwise,
18603 /tmp is used.
18604 See also "get-sockdir",
18606 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18607
18609 Examples written in C: guestfs-examples(3).
18610 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18612 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18613 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18614 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18616 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18617 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18618 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18619 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18620 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18621 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18622 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18623 virt-win-reg(1).
18624 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18626 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18627 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18628 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18629 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18631 sd-journal(3).
18632 Website: http://libguestfs.org/
18634 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18636 disktype(1).
18637
18639 Richard W.M. Jones ("rjones at redhat dot com")
18640
18642 Copyright (C) 2009-2020 Red Hat Inc.
18643
18645 This library is free software; you can redistribute it and/or modify it
18646 under the terms of the GNU Lesser General Public License as published
18647 by the Free Software Foundation; either version 2 of the License, or
18648 (at your option) any later version.
18649 This library is distributed in the hope that it will be useful, but
18651 WITHOUT ANY WARRANTY; without even the implied warranty of
18652 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18653 Lesser General Public License for more details.
18654 You should have received a copy of the GNU Lesser General Public
18656 License along with this library; if not, write to the Free Software
18657 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18658 02110-1301 USA
18659
18661 To get a list of bugs against libguestfs, use this link:
18662 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18663 To report a new bug against libguestfs, use this link:
18665 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18666 When reporting a bug, please supply:
18668 • The version of libguestfs.
18670 • Where you got libguestfs (eg. which Linux distro, compiled from
18672 source, etc)
18673 • Describe the bug accurately and give a way to reproduce it.
18675 • Run libguestfs-test-tool(1) and paste the complete, unedited output
18677 into the bug report.
18678libguestfs-1.49.9 2023-01-19 guestfs(3)