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 Opening an encrypted device creates a new device mapper device called
520 /dev/mapper/mapname (where "mapname" is the string you supply to
521 "guestfs_cryptsetup_open"). Reads and writes to this mapper device are
522 decrypted from and encrypted to the underlying block device
523 respectively.
524 LVM volume groups on the device can be made visible by calling
526 "guestfs_vgscan" followed by "guestfs_vg_activate_all". The logical
527 volume(s) can now be mounted in the usual way.
528 Use the reverse process to close an encrypted device. Unmount any
530 logical volumes on it, deactivate the volume groups by calling
531 "guestfs_vg_activate (g, 0, ["/dev/VG"])". Then close the mapper
532 device by calling "guestfs_cryptsetup_close" on the /dev/mapper/mapname
533 device (not the underlying encrypted block device).
534 MOUNT LOCAL
536 In libguestfs ≥ 1.18, it is possible to mount the libguestfs filesystem
537 on a local directory and access it using ordinary POSIX calls and
538 programs.
539 Availability of this is subject to a number of restrictions: it
541 requires FUSE (the Filesystem in USErspace), and libfuse must also have
542 been available when libguestfs was compiled. FUSE may require that a
543 kernel module is loaded, and it may be necessary to add the current
544 user to a special "fuse" group. See the documentation for your
545 distribution and http://fuse.sf.net for further information.
546 The call to mount the libguestfs filesystem on a local directory is
548 "guestfs_mount_local" (q.v.) followed by "guestfs_mount_local_run".
549 The latter does not return until you unmount the filesystem. The
550 reason is that the call enters the FUSE main loop and processes kernel
551 requests, turning them into libguestfs calls. An alternative design
552 would have been to create a background thread to do this, but
553 libguestfs doesn't require pthreads. This way is also more flexible:
554 for example the user can create another thread for
555 "guestfs_mount_local_run".
556 "guestfs_mount_local" needs a certain amount of time to set up the
558 mountpoint. The mountpoint is not ready to use until the call returns.
559 At this point, accesses to the filesystem will block until the main
560 loop is entered (ie. "guestfs_mount_local_run"). So if you need to
561 start another process to access the filesystem, put the fork between
562 "guestfs_mount_local" and "guestfs_mount_local_run".
563 MOUNT LOCAL COMPATIBILITY
565 Since local mounting was only added in libguestfs 1.18, and may not be
567 available even in these builds, you should consider writing code so
568 that it doesn't depend on this feature, and can fall back to using
569 libguestfs file system calls.
570 If libguestfs was compiled without support for "guestfs_mount_local"
572 then calling it will return an error with errno set to "ENOTSUP" (see
573 "guestfs_last_errno").
574 MOUNT LOCAL PERFORMANCE
576 Libguestfs on top of FUSE performs quite poorly. For best performance
578 do not use it. Use ordinary libguestfs filesystem calls, upload,
579 download etc. instead.
580 REMOTE STORAGE
582 CEPH
583 Libguestfs can access Ceph (librbd/RBD) disks.
585 To do this, set the optional "protocol" and "server" parameters of
587 "guestfs_add_drive_opts" like this:
588 char **servers = { "ceph1.example.org:3000", /* ... */, NULL };
590 guestfs_add_drive_opts (g, "pool/image",
591 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
592 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "rbd",
593 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
594 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "rbduser",
595 GUESTFS_ADD_DRIVE_OPTS_SECRET, "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
596 -1);
597 "servers" (the "server" parameter) is a list of one or more Ceph
599 servers. The server string is documented in "guestfs_add_drive_opts".
600 The "username" and "secret" parameters are also optional, and if not
601 given, then no authentication will be used.
602 An encrypted RBD disk -- directly opening which would require the
604 "username" and "secret" parameters -- cannot be accessed if the
605 following conditions all hold:
606 • the backend is libvirt,
608 • the image specified by the "filename" parameter is different from
610 the encrypted RBD disk,
611 • the image specified by the "filename" parameter has qcow2 format,
613 • the encrypted RBD disk is specified as a backing file at some level
615 in the qcow2 backing chain.
616 This limitation is due to libvirt's (justified) separate handling of
618 disks vs. secrets. When the RBD username and secret are provided
619 inside a qcow2 backing file specification, libvirt does not construct
620 an ephemeral secret object from those, for Ceph authentication. Refer
621 to https://bugzilla.redhat.com/2033247.
622 FTP, HTTP AND TFTP
624 Libguestfs can access remote disks over FTP, FTPS, HTTP, HTTPS or TFTP
626 protocols.
627 To do this, set the optional "protocol" and "server" parameters of
629 "guestfs_add_drive_opts" like this:
630 char **servers = { "www.example.org", NULL };
632 guestfs_add_drive_opts (g, "/disk.img",
633 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
634 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "http",
635 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
636 -1);
637 The "protocol" can be one of "ftp", "ftps", "http", "https" or "tftp".
639 "servers" (the "server" parameter) is a list which must have a single
641 element. The single element is a string defining the web, FTP or TFTP
642 server. The format of this string is documented in
643 "guestfs_add_drive_opts".
644 GLUSTER
646 Libguestfs can access Gluster disks.
648 To do this, set the optional "protocol" and "server" parameters of
650 "guestfs_add_drive_opts" like this:
651 char **servers = { "gluster.example.org:24007", NULL };
653 guestfs_add_drive_opts (g, "volname/image",
654 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
655 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "gluster",
656 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
657 -1);
658 "servers" (the "server" parameter) is a list which must have a single
660 element. The single element is a string defining the Gluster server.
661 The format of this string is documented in "guestfs_add_drive_opts".
662 Note that gluster usually requires the client process (ie. libguestfs)
664 to run as root and will give unfathomable errors if it is not (eg. "No
665 data available").
666 ISCSI
668 Libguestfs can access iSCSI disks remotely.
670 To do this, set the optional "protocol" and "server" parameters like
672 this:
673 char **server = { "iscsi.example.org:3000", NULL };
675 guestfs_add_drive_opts (g, "target-iqn-name/lun",
676 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
677 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "iscsi",
678 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
679 -1);
680 The "server" parameter is a list which must have a single element. The
682 single element is a string defining the iSCSI server. The format of
683 this string is documented in "guestfs_add_drive_opts".
684 NETWORK BLOCK DEVICE
686 Libguestfs can access Network Block Device (NBD) disks remotely.
688 To do this, set the optional "protocol" and "server" parameters of
690 "guestfs_add_drive_opts" like this:
691 char **server = { "nbd.example.org:3000", NULL };
693 guestfs_add_drive_opts (g, "" /* export name - see below */,
694 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
695 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
696 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
697 -1);
698 Notes:
700 • "server" is in fact a list of servers. For NBD you must always
702 supply a list with a single element. (Other remote protocols
703 require zero or more than one server, hence the requirement for
704 this parameter to be a list).
705 • The "server" string is documented in "guestfs_add_drive_opts". To
707 connect to a local qemu-nbd instance over a Unix domain socket, use
708 "unix:/path/to/socket".
709 • The "filename" parameter is the NBD export name. Use an empty
711 string to mean the default export. Many NBD servers, including
712 qemu-nbd, do not support export names.
713 • If using qemu-nbd as your server, you should always specify the
715 "-t" option. The reason is that libguestfs may open several
716 connections to the server.
717 • The libvirt backend requires that you set the "format" parameter of
719 "guestfs_add_drive_opts" accurately when you use writable NBD
720 disks.
721 • The libvirt backend has a bug that stops Unix domain socket
723 connections from working:
724 https://bugzilla.redhat.com/show_bug.cgi?id=922888
725 • The direct backend does not support readonly connections because of
727 a bug in qemu: https://bugs.launchpad.net/qemu/+bug/1155677
728 SHEEPDOG
730 Libguestfs can access Sheepdog disks.
732 To do this, set the optional "protocol" and "server" parameters of
734 "guestfs_add_drive_opts" like this:
735 char **servers = { /* optional servers ... */ NULL };
737 guestfs_add_drive_opts (g, "volume",
738 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
739 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "sheepdog",
740 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
741 -1);
742 The optional list of "servers" may be zero or more server addresses
744 ("hostname:port"). The format of the server strings is documented in
745 "guestfs_add_drive_opts".
746 SSH
748 Libguestfs can access disks over a Secure Shell (SSH) connection.
750 To do this, set the "protocol" and "server" and (optionally) "username"
752 parameters of "guestfs_add_drive_opts" like this:
753 char **server = { "remote.example.com", NULL };
755 guestfs_add_drive_opts (g, "/path/to/disk.img",
756 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
757 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "ssh",
758 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
759 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "remoteuser",
760 -1);
761 The format of the server string is documented in
763 "guestfs_add_drive_opts".
764 INSPECTION
766 Libguestfs has APIs for inspecting an unknown disk image to find out if
767 it contains operating systems, an install CD or a live CD.
768 Add all disks belonging to the unknown virtual machine and call
770 "guestfs_launch" in the usual way.
771 Then call "guestfs_inspect_os". This function uses other libguestfs
773 calls and certain heuristics, and returns a list of operating systems
774 that were found. An empty list means none were found. A single
775 element is the root filesystem of the operating system. For dual- or
776 multi-boot guests, multiple roots can be returned, each one
777 corresponding to a separate operating system. (Multi-boot virtual
778 machines are extremely rare in the world of virtualization, but since
779 this scenario can happen, we have built libguestfs to deal with it.)
780 For each root, you can then call various "guestfs_inspect_get_*"
782 functions to get additional details about that operating system. For
783 example, call "guestfs_inspect_get_type" to return the string "windows"
784 or "linux" for Windows and Linux-based operating systems respectively.
785 Un*x-like and Linux-based operating systems usually consist of several
787 filesystems which are mounted at boot time (for example, a separate
788 boot partition mounted on /boot). The inspection rules are able to
789 detect how filesystems correspond to mount points. Call
790 "guestfs_inspect_get_mountpoints" to get this mapping. It might return
791 a hash table like this example:
792 /boot => /dev/sda1
794 / => /dev/vg_guest/lv_root
795 /usr => /dev/vg_guest/lv_usr
796 The caller can then make calls to "guestfs_mount" to mount the
798 filesystems as suggested.
799 Be careful to mount filesystems in the right order (eg. / before /usr).
801 Sorting the keys of the hash by length, shortest first, should work.
802 Inspection currently only works for some common operating systems.
804 Contributors are welcome to send patches for other operating systems
805 that we currently cannot detect.
806 Encrypted disks must be opened before inspection. See "ENCRYPTED
808 DISKS" for more details. The "guestfs_inspect_os" function just
809 ignores any encrypted devices.
810 A note on the implementation: The call "guestfs_inspect_os" performs
812 inspection and caches the results in the guest handle. Subsequent
813 calls to "guestfs_inspect_get_*" return this cached information, but do
814 not re-read the disks. If you change the content of the guest disks,
815 you can redo inspection by calling "guestfs_inspect_os" again.
816 ("guestfs_inspect_list_applications2" works a little differently from
817 the other calls and does read the disks. See documentation for that
818 function for details).
819 INSPECTING INSTALL DISKS
821 Libguestfs (since 1.9.4) can detect some install disks, install CDs,
823 live CDs and more.
824 Further information is available about the operating system that can be
826 installed using the regular inspection APIs like
827 "guestfs_inspect_get_product_name", "guestfs_inspect_get_major_version"
828 etc.
829 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
831 Libguestfs can mount NTFS partitions. It does this using the
832 http://www.ntfs-3g.org/ driver.
833 DRIVE LETTERS AND PATHS
835 DOS and Windows still use drive letters, and the filesystems are always
837 treated as case insensitive by Windows itself, and therefore you might
838 find a Windows configuration file referring to a path like
839 "c:\windows\system32". When the filesystem is mounted in libguestfs,
840 that directory might be referred to as /WINDOWS/System32.
841 Drive letter mappings can be found using inspection (see "INSPECTION"
843 and "guestfs_inspect_get_drive_mappings")
844 Dealing with separator characters (backslash vs forward slash) is
846 outside the scope of libguestfs, but usually a simple character
847 replacement will work.
848 To resolve the case insensitivity of paths, call
850 "guestfs_case_sensitive_path".
851 LONG FILENAMES ON NTFS
853 NTFS supports filenames up to 255 characters long. "Character" means a
855 2 byte UTF-16 codepoint which can encode the most common Unicode
856 codepoints.
857 Most Linux filesystems support filenames up to 255 bytes. This means
859 you may get an error:
860 File name too long
862 when you copy a file from NTFS to a Linux filesystem if the name, when
864 reencoded as UTF-8, would exceed 255 bytes in length.
865 This will most often happen when using non-ASCII names that are longer
867 than ~127 characters (eg. Greek, Cyrillic) or longer than ~85
868 characters (Asian languages).
869 A workaround is not to try to store such long filenames on Linux native
871 filesystems. Since the tar(1) format can store unlimited length
872 filenames, keep the files in a tarball.
873 ACCESSING THE WINDOWS REGISTRY
875 Libguestfs also provides some help for decoding Windows Registry "hive"
877 files, through a separate C library called hivex(3).
878 Before libguestfs 1.19.35 you had to download the hive file, operate on
880 it locally using hivex, and upload it again. Since this version, we
881 have included the major hivex APIs directly in the libguestfs API (see
882 "guestfs_hivex_open"). This means that if you have opened a Windows
883 guest, you can read and write the registry directly.
884 See also virt-win-reg(1).
886 SYMLINKS ON NTFS-3G FILESYSTEMS
888 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
890 provide something which looks like a Linux symlink. The way it tries
891 to do the rewriting is described here:
892 http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
894 The essential problem is that ntfs-3g simply does not have enough
896 information to do a correct job. NTFS links can contain drive letters
897 and references to external device GUIDs that ntfs-3g has no way of
898 resolving. It is almost certainly the case that libguestfs callers
899 should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
900 NTFS volumes).
901 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
903 "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
904 attribute, and read the raw reparse data from that (you can find the
905 format documented in various places around the web).
906 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
908 There are other useful extended attributes that can be read from
910 ntfs-3g filesystems (using "guestfs_getxattr"). See:
911 http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
913 WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP
915 Windows guests which have been hibernated (instead of fully shut down)
917 cannot be mounted. This is a limitation of ntfs-3g. You will see an
918 error like this:
919 The disk contains an unclean file system (0, 0).
921 Metadata kept in Windows cache, refused to mount.
922 Failed to mount '/dev/sda2': Operation not permitted
923 The NTFS partition is in an unsafe state. Please resume
924 and shutdown Windows fully (no hibernation or fast
925 restarting), or mount the volume read-only with the
926 'ro' mount option.
927 In Windows 8, the shutdown button does not shut down the guest at all.
929 Instead it usually hibernates the guest. This is known as "fast
930 startup".
931 Some suggested workarounds are:
933 • Mount read-only (eg. "guestfs_mount_ro").
935 • On Windows 8, turn off fast startup. It is in the Control Panel →
937 Power Options → Choose what the power buttons do → Change settings
938 that are currently unavailable → Turn on fast startup.
939 • On Windows 7 and earlier, shut the guest off properly instead of
941 hibernating it.
942 RESIZE2FS ERRORS
944 The "guestfs_resize2fs", "guestfs_resize2fs_size" and
945 "guestfs_resize2fs_M" calls are used to resize ext2/3/4 filesystems.
946 The underlying program (resize2fs(8)) requires that the filesystem is
948 clean and recently fsck'd before you can resize it. Also, if the
949 resize operation fails for some reason, then you had to call fsck the
950 filesystem again to fix it.
951 In libguestfs "lt" 1.17.14, you usually had to call "guestfs_e2fsck_f"
953 before the resize. However, in "ge" 1.17.14, e2fsck(8) is called
954 automatically before the resize, so you no longer need to do this.
955 The resize2fs(8) program can still fail, in which case it prints an
957 error message similar to:
958 Please run 'e2fsck -fy <device>' to fix the filesystem
960 after the aborted resize operation.
961 You can do this by calling "guestfs_e2fsck" with the "forceall" option.
963 However in the context of disk images, it is usually better to avoid
964 this situation, eg. by rolling back to an earlier snapshot, or by
965 copying and resizing and on failure going back to the original.
966 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
968 Although we don’t want to discourage you from using the C API, we will
969 mention here that the same API is also available in other languages.
970 The API is broadly identical in all supported languages. This means
972 that the C call "guestfs_add_drive_ro(g,file)" is
973 "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
974 and "g#add_drive_ro file" in OCaml. In other words, a straightforward,
975 predictable isomorphism between each language.
976 Error messages are automatically transformed into exceptions if the
978 language supports it.
979 We don’t try to "object orientify" parts of the API in OO languages,
981 although contributors are welcome to write higher level APIs above what
982 we provide in their favourite languages if they wish.
983 C++ You can use the guestfs.h header file from C++ programs. The C++
985 API is identical to the C API. C++ classes and exceptions are not
986 used.
987 C# The C# bindings are highly experimental. Please read the warnings
989 at the top of csharp/Libguestfs.cs.
990 Erlang
992 See guestfs-erlang(3).
993 GObject
995 Experimental GObject bindings (with GObject Introspection support)
996 are available.
997 See guestfs-gobject(3).
999 Go See guestfs-golang(3).
1001 Haskell
1003 This language binding is working but incomplete:
1004 • Functions with optional arguments are not bound. Implementing
1006 optional arguments in Haskell seems to be very complex.
1007 • Events are not bound.
1009 • Functions with the following return types are not bound:
1011 • Any function returning a struct.
1013 • Any function returning a list of structs.
1015 • A few functions that return fixed length buffers
1017 (specifically ones declared "RBufferOut" in the generator).
1018 • A tiny number of obscure functions that return constant
1020 strings (specifically ones declared "RConstOptString" in
1021 the generator).
1022 Java
1024 Full documentation is contained in the Javadoc which is distributed
1025 with libguestfs. For examples, see guestfs-java(3).
1026 Lua See guestfs-lua(3).
1028 OCaml
1030 See guestfs-ocaml(3).
1031 Perl
1033 See guestfs-perl(3) and Sys::Guestfs(3).
1034 PHP For documentation see "README-PHP" supplied with libguestfs sources
1036 or in the php-libguestfs package for your distribution.
1037 The PHP binding only works correctly on 64 bit machines.
1039 Python
1041 See guestfs-python(3).
1042 Ruby
1044 See guestfs-ruby(3).
1045 For JRuby, use the Java bindings.
1047 shell scripts
1049 See guestfish(1).
1050 LIBGUESTFS GOTCHAS
1052 http://en.wikipedia.org/wiki/Gotcha_(programming): "A feature of a
1053 system [...] that works in the way it is documented but is
1054 counterintuitive and almost invites mistakes."
1055 Since we developed libguestfs and the associated tools, there are
1057 several things we would have designed differently, but are now stuck
1058 with for backwards compatibility or other reasons. If there is ever a
1059 libguestfs 2.0 release, you can expect these to change. Beware of
1060 them.
1061 Read-only should be the default.
1063 In guestfish(3), --ro should be the default, and you should have to
1064 specify --rw if you want to make changes to the image.
1065 This would reduce the potential to corrupt live VM images.
1067 Note that many filesystems change the disk when you just mount and
1069 unmount, even if you didn't perform any writes. You need to use
1070 "guestfs_add_drive_ro" to guarantee that the disk is not changed.
1071 guestfish command line is hard to use.
1073 guestfish disk.img doesn't do what people expect (open disk.img for
1074 examination). It tries to run a guestfish command disk.img which
1075 doesn't exist, so it fails. In earlier versions of guestfish the
1076 error message was also unintuitive, but we have corrected this
1077 since. Like the Bourne shell, we should have used "guestfish -c
1078 command" to run commands.
1079 guestfish megabyte modifiers don’t work right on all commands
1081 In recent guestfish you can use "1M" to mean 1 megabyte (and
1082 similarly for other modifiers). What guestfish actually does is to
1083 multiply the number part by the modifier part and pass the result
1084 to the C API. However this doesn't work for a few APIs which
1085 aren't expecting bytes, but are already expecting some other unit
1086 (eg. megabytes).
1087 The most common is "guestfs_lvcreate". The guestfish command:
1089 lvcreate LV VG 100M
1091 does not do what you might expect. Instead because
1093 "guestfs_lvcreate" is already expecting megabytes, this tries to
1094 create a 100 terabyte (100 megabytes * megabytes) logical volume.
1095 The error message you get from this is also a little obscure.
1096 This could be fixed in the generator by specially marking
1098 parameters and return values which take bytes or other units.
1099 Ambiguity between devices and paths
1101 There is a subtle ambiguity in the API between a device name (eg.
1102 /dev/sdb2) and a similar pathname. A file might just happen to be
1103 called "sdb2" in the directory /dev (consider some non-Unix VM
1104 image).
1105 In the current API we usually resolve this ambiguity by having two
1107 separate calls, for example "guestfs_checksum" and
1108 "guestfs_checksum_device". Some API calls are ambiguous and
1109 (incorrectly) resolve the problem by detecting if the path supplied
1110 begins with /dev/.
1111 To avoid both the ambiguity and the need to duplicate some calls,
1113 we could make paths/devices into structured names. One way to do
1114 this would be to use a notation like grub ("hd(0,0)"), although
1115 nobody really likes this aspect of grub. Another way would be to
1116 use a structured type, equivalent to this OCaml type:
1117 type path = Path of string | Device of int | Partition of int * int
1119 which would allow you to pass arguments like:
1121 Path "/foo/bar"
1123 Device 1 (* /dev/sdb, or perhaps /dev/sda *)
1124 Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
1125 Path "/dev/sdb2" (* not a device *)
1126 As you can see there are still problems to resolve even with this
1128 representation. Also consider how it might work in guestfish.
1129 KEYS AND PASSPHRASES
1131 Certain libguestfs calls take a parameter that contains sensitive key
1132 material, passed in as a C string.
1133 In the future we would hope to change the libguestfs implementation so
1135 that keys are mlock(2)-ed into physical RAM, and thus can never end up
1136 in swap. However this is not done at the moment, because of the
1137 complexity of such an implementation.
1138 Therefore you should be aware that any key parameter you pass to
1140 libguestfs might end up being written out to the swap partition. If
1141 this is a concern, scrub the swap partition or don't use libguestfs on
1142 encrypted devices.
1143 MULTIPLE HANDLES AND MULTIPLE THREADS
1145 All high-level libguestfs actions are synchronous. If you want to use
1146 libguestfs asynchronously then you must create a thread.
1147 Threads in libguestfs ≥ 1.38
1149 In libguestfs ≥ 1.38, each handle ("guestfs_h") contains a lock which
1151 is acquired automatically when you call a libguestfs function. The
1152 practical effect of this is you can call libguestfs functions with the
1153 same handle from multiple threads without needing to do any locking.
1154 Also in libguestfs ≥ 1.38, the last error on the handle
1156 ("guestfs_last_error", "guestfs_last_errno") is stored in thread-local
1157 storage, so it is safe to write code like:
1158 if (guestfs_add_drive_ro (g, drive) == -1)
1160 fprintf (stderr, "error was: %s\n", guestfs_last_error (g));
1161 even when other threads may be concurrently using the same handle "g".
1163 Threads in libguestfs < 1.38
1165 In libguestfs < 1.38, you must use the handle only from a single
1167 thread. Either use the handle exclusively from one thread, or provide
1168 your own mutex so that two threads cannot issue calls on the same
1169 handle at the same time. Even apparently innocent functions like
1170 "guestfs_get_trace" are not safe to be called from multiple threads
1171 without a mutex in libguestfs < 1.38.
1172 Use "guestfs_set_identifier" to make it simpler to identify threads in
1174 trace output.
1175 PATH
1177 Libguestfs needs a supermin appliance, which it finds by looking along
1178 an internal path.
1179 By default it looks for these in the directory "$libdir/guestfs" (eg.
1181 /usr/local/lib/guestfs or /usr/lib64/guestfs).
1182 Use "guestfs_set_path" or set the environment variable
1184 "LIBGUESTFS_PATH" to change the directories that libguestfs will search
1185 in. The value is a colon-separated list of paths. The current
1186 directory is not searched unless the path contains an empty element or
1187 ".". For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
1188 current directory and then /usr/lib/guestfs.
1189 QEMU WRAPPERS
1191 If you want to compile your own qemu, run qemu from a non-standard
1192 location, or pass extra arguments to qemu, then you can write a shell-
1193 script wrapper around qemu.
1194 There is one important rule to remember: you must "exec qemu" as the
1196 last command in the shell script (so that qemu replaces the shell and
1197 becomes the direct child of the libguestfs-using program). If you
1198 don't do this, then the qemu process won't be cleaned up correctly.
1199 Here is an example of a wrapper, where I have built my own copy of qemu
1201 from source:
1202 #!/bin/sh -
1204 qemudir=/home/rjones/d/qemu
1205 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1206 Save this script as /tmp/qemu.wrapper (or wherever), "chmod +x", and
1208 then use it by setting the LIBGUESTFS_HV environment variable. For
1209 example:
1210 LIBGUESTFS_HV=/tmp/qemu.wrapper guestfish
1212 Note that libguestfs also calls qemu with the -help and -version
1214 options in order to determine features.
1215 Wrappers can also be used to edit the options passed to qemu. In the
1217 following example, the "-machine ..." option ("-machine" and the
1218 following argument) are removed from the command line and replaced with
1219 "-machine pc,accel=tcg". The while loop iterates over the options
1220 until it finds the right one to remove, putting the remaining options
1221 into the "args" array.
1222 #!/bin/bash -
1224 i=0
1226 while [ $# -gt 0 ]; do
1227 case "$1" in
1228 -machine)
1229 shift 2;;
1230 *)
1231 args[i]="$1"
1232 (( i++ ))
1233 shift ;;
1234 esac
1235 done
1236 exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
1238 BACKEND
1240 The backend (previously known as the "attach method") controls how
1241 libguestfs creates and/or connects to the backend daemon, eg. by
1242 starting qemu directly, or using libvirt to manage an appliance,
1243 running User-Mode Linux, or connecting to an already running daemon.
1244 You can set the backend by calling "guestfs_set_backend", or by setting
1246 the environment variable "LIBGUESTFS_BACKEND".
1247 Possible backends are described below:
1249 "direct"
1251 "appliance"
1252 Run qemu directly to launch an appliance.
1253 "direct" and "appliance" are synonyms.
1255 This is the ordinary method and normally the default, but see the
1257 note below.
1258 "libvirt"
1260 "libvirt:null"
1261 "libvirt:URI"
1262 Use libvirt to launch and manage the appliance.
1263 "libvirt" causes libguestfs to choose a suitable URI for creating
1265 session guests. If using the libvirt backend, you almost always
1266 should use this.
1267 "libvirt:null" causes libguestfs to use the "NULL" connection URI,
1269 which causes libvirt to try to guess what the user meant. You
1270 probably don't want to use this.
1271 "libvirt:URI" uses URI as the libvirt connection URI (see
1273 http://libvirt.org/uri.html). The typical libvirt backend with a
1274 URI would be "libvirt:qemu:///session"
1275 The libvirt backend supports more features, including sVirt.
1277 "direct" is usually the default backend. However since libguestfs ≥
1279 1.19.24, libguestfs can be built with a different default by doing:
1280 ./configure --with-default-backend=...
1282 To find out if libguestfs was compiled with a different default
1284 backend, do:
1285 unset LIBGUESTFS_BACKEND
1287 guestfish get-backend
1288 BACKEND SETTINGS
1290 Each backend can be configured by passing a list of strings. You can
1291 either call "guestfs_set_backend_settings" with a list of strings, or
1292 set the "LIBGUESTFS_BACKEND_SETTINGS" environment variable to a colon-
1293 separated list of strings (before creating the handle).
1294 force_tcg
1296 Using:
1298 export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
1300 will force the direct and libvirt backends to use TCG (software
1302 emulation) instead of KVM (hardware accelerated virtualization).
1303 force_kvm
1305 Using:
1307 export LIBGUESTFS_BACKEND_SETTINGS=force_kvm
1309 will force the direct and libvirt backends to use KVM (hardware
1311 accelerated virtualization) instead of TCG (software emulation).
1312 gdb
1314 The direct backend supports:
1316 export LIBGUESTFS_BACKEND_SETTINGS=gdb
1318 When this is set, qemu will not start running the appliance
1320 immediately. It will wait for you to connect to it using gdb:
1321 $ gdb
1323 (gdb) symbol-file /path/to/vmlinux
1324 (gdb) target remote tcp::1234
1325 (gdb) cont
1326 You can then debug the appliance kernel, which is useful to debug boot
1328 failures (especially ones where there are no debug messages printed -
1329 tip: look in the kernel "log_buf").
1330 On Fedora, install "kernel-debuginfo" for the "vmlinux" file
1332 (containing symbols). Make sure the symbols precisely match the kernel
1333 being used.
1334 ABI GUARANTEE
1336 We guarantee the libguestfs ABI (binary interface), for public, high-
1337 level actions as outlined in this section. Although we will deprecate
1338 some actions, for example if they get replaced by newer calls, we will
1339 keep the old actions forever. This allows you the developer to program
1340 in confidence against the libguestfs API.
1341 BLOCK DEVICE NAMING
1343 Libguestfs defines /dev/sd* as the standard naming scheme for devices
1344 passed to API calls. So /dev/sda means "the first device added by
1345 "guestfs_add_drive_opts"", and /dev/sdb3 means "the third partition on
1346 the second device".
1347 Internally device names are sometimes translated, but this should not
1349 be visible at the API level.
1350 DISK LABELS
1352 In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1354 using the optional "label" parameter to "guestfs_add_drive_opts".
1355 (Note that disk labels are different from and not related to filesystem
1356 labels).
1357 Not all versions of libguestfs support setting a disk label, and when
1359 it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1360 When you add a disk with a label, it can either be addressed using
1362 /dev/sd*, or using /dev/disk/guestfs/label. Partitions on the disk can
1363 be addressed using /dev/disk/guestfs/labelpartnum.
1364 Listing devices ("guestfs_list_devices") and partitions
1366 ("guestfs_list_partitions") returns the block device names. However
1367 you can use "guestfs_list_disk_labels" to map disk labels to block
1368 device and partition names.
1369 NULL DISKS
1371 When adding a disk using, eg., "guestfs_add_drive", you can set the
1372 filename to "/dev/null". This string is treated specially by
1373 libguestfs, causing it to add a "null disk".
1374 A null disk has the following properties:
1376 • A null disk will appear as a normal device, eg. in calls to
1378 "guestfs_list_devices".
1379 • You may add "/dev/null" multiple times.
1381 • You should not try to access a null disk in any way. For example,
1383 you shouldn't try to read it or mount it.
1384 Null disks are used for three main purposes:
1386 1. Performance testing of libguestfs (see guestfs-performance(1)).
1388 2. The internal test suite.
1390 3. If you want to use libguestfs APIs that don’t refer to disks, since
1392 libguestfs requires that at least one disk is added, you should add
1393 a null disk.
1394 For example, to test if a feature is available, use code like this:
1396 guestfs_h *g;
1398 char **groups = [ "btrfs", NULL ];
1399 g = guestfs_create ();
1401 guestfs_add_drive (g, "/dev/null");
1402 guestfs_launch (g);
1403 if (guestfs_available (g, groups) == 0) {
1404 // group(s) are available
1405 } else {
1406 // group(s) are not available
1407 }
1408 guestfs_close (g);
1409 DISK IMAGE FORMATS
1411 Virtual disks come in a variety of formats. Some common formats are
1412 listed below.
1413 Note that libguestfs itself is not responsible for handling the disk
1415 format: this is done using qemu(1). If support for a particular format
1416 is missing or broken, this has to be fixed in qemu.
1417 COMMON VIRTUAL DISK IMAGE FORMATS
1419 raw Raw format is simply a dump of the sequential bytes of the virtual
1421 hard disk. There is no header, container, compression or
1422 processing of any sort.
1423 Since raw format requires no translation to read or write, it is
1425 both fast and very well supported by qemu and all other
1426 hypervisors. You can consider it to be a universal format that any
1427 hypervisor can access.
1428 Raw format files are not compressed and so take up the full space
1430 of the original disk image even when they are empty. A variation
1431 (on Linux/Unix at least) is to not store ranges of all-zero bytes
1432 by storing the file as a sparse file. This "variant format" is
1433 sometimes called raw sparse. Many utilities, including
1434 virt-sparsify(1), can make raw disk images sparse.
1435 qcow2
1437 Qcow2 is the native disk image format used by qemu. Internally it
1438 uses a two-level directory structure so that only blocks containing
1439 data are stored in the file. It also has many other features such
1440 as compression, snapshots and backing files.
1441 There are at least two distinct variants of this format, although
1443 qemu (and hence libguestfs) handles both transparently to the user.
1444 vmdk
1446 VMDK is VMware’s native disk image format. There are many
1447 variations. Modern qemu (hence libguestfs) supports most
1448 variations, but you should be aware that older versions of qemu had
1449 some very bad data-corrupting bugs in this area.
1450 Note that VMware ESX exposes files with the name guest-flat.vmdk.
1452 These are not VMDK. They are raw format files which happen to have
1453 a ".vmdk" extension.
1454 vdi VDI is VirtualBox’s native disk image format. Qemu (hence
1456 libguestfs) has generally good support for this.
1457 vpc
1459 vhd VPC (old) and VHD (modern) are the native disk image format of
1460 Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1461 Obsolete formats
1463 The following formats are obsolete and should not be used: qcow
1464 (aka qcow1), cow, bochs.
1465 DETECTING THE FORMAT OF A DISK IMAGE
1467 Firstly note there is a security issue with auto-detecting the format
1469 of a disk image. It may or may not apply in your use case. Read
1470 "CVE-2010-3851" below.
1471 Libguestfs offers an API to get the format of a disk image
1473 ("guestfs_disk_format"), and it is safest to use this.
1474 Don’t be tempted to try parsing the text / human-readable output of
1476 "qemu-img" since it cannot be parsed reliably and securely. Also do
1477 not use the "file" command since the output of that changes over time.
1478
1480 guestfs_h *
1481 "guestfs_h" is the opaque type representing a connection handle.
1482 Create a handle by calling "guestfs_create" or "guestfs_create_flags".
1483 Call "guestfs_close" to free the handle and release all resources used.
1484 For information on using multiple handles and threads, see the section
1486 "MULTIPLE HANDLES AND MULTIPLE THREADS" above.
1487 guestfs_create
1489 guestfs_h *guestfs_create (void);
1490 Create a connection handle.
1492 On success this returns a non-NULL pointer to a handle. On error it
1494 returns NULL.
1495 You have to "configure" the handle after creating it. This includes
1497 calling "guestfs_add_drive_opts" (or one of the equivalent calls) on
1498 the handle at least once.
1499 After configuring the handle, you have to call "guestfs_launch".
1501 You may also want to configure error handling for the handle. See the
1503 "ERROR HANDLING" section below.
1504 guestfs_create_flags
1506 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
1507 Create a connection handle, supplying extra flags and extra arguments
1509 to control how the handle is created.
1510 On success this returns a non-NULL pointer to a handle. On error it
1512 returns NULL.
1513 "guestfs_create" is equivalent to calling guestfs_create_flags(0).
1515 The following flags may be logically ORed together. (Currently no
1517 extra arguments are used).
1518 "GUESTFS_CREATE_NO_ENVIRONMENT"
1520 Don’t parse any environment variables (such as "LIBGUESTFS_DEBUG"
1521 etc).
1522 You can call "guestfs_parse_environment" or
1524 "guestfs_parse_environment_list" afterwards to parse environment
1525 variables. Alternately, don't call these functions if you want the
1526 handle to be unaffected by environment variables. See the example
1527 below.
1528 The default (if this flag is not given) is to implicitly call
1530 "guestfs_parse_environment".
1531 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT"
1533 Don’t try to close the handle in an atexit(3) handler if the
1534 program exits without explicitly closing the handle.
1535 The default (if this flag is not given) is to install such an
1537 atexit handler.
1538 USING "GUESTFS_CREATE_NO_ENVIRONMENT"
1540 You might use "GUESTFS_CREATE_NO_ENVIRONMENT" and an explicit call to
1542 "guestfs_parse_environment" like this:
1543 guestfs_h *g;
1545 int r;
1546 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
1548 if (!g) {
1549 perror ("guestfs_create_flags");
1550 exit (EXIT_FAILURE);
1551 }
1552 r = guestfs_parse_environment (g);
1553 if (r == -1)
1554 exit (EXIT_FAILURE);
1555 Or to create a handle which is unaffected by environment variables,
1557 omit the call to "guestfs_parse_environment" from the above code.
1558 The above code has another advantage which is that any errors from
1560 parsing the environment are passed through the error handler, whereas
1561 "guestfs_create" prints errors on stderr and ignores them.
1562 guestfs_close
1564 void guestfs_close (guestfs_h *g);
1565 This closes the connection handle and frees up all resources used. If
1567 a close callback was set on the handle, then it is called.
1568 The correct way to close the handle is:
1570 if (guestfs_shutdown (g) == -1) {
1572 /* handle write errors here */
1573 }
1574 guestfs_close (g);
1575 "guestfs_shutdown" is only needed if all of the following are true:
1577 1. one or more disks were added in read-write mode, and
1579 2. guestfs_launch was called, and
1581 3. you made some changes, and
1583 4. you have a way to handle write errors (eg. by exiting with an error
1585 code or reporting something to the user).
1586
1588 API functions can return errors. For example, almost all functions
1589 that return "int" will return "-1" to indicate an error.
1590 Additional information is available for errors: an error message string
1592 and optionally an error number (errno) if the thing that failed was a
1593 system call.
1594 You can get at the additional information about the last error on the
1596 handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1597 setting up an error handler with "guestfs_set_error_handler".
1598 When the handle is created, a default error handler is installed which
1600 prints the error message string to "stderr". For small short-running
1601 command line programs it is sufficient to do:
1602 if (guestfs_launch (g) == -1)
1604 exit (EXIT_FAILURE);
1605 since the default error handler will ensure that an error message has
1607 been printed to "stderr" before the program exits.
1608 For other programs the caller will almost certainly want to install an
1610 alternate error handler or do error handling in-line as in the example
1611 below. The non-C language bindings all install NULL error handlers and
1612 turn errors into exceptions using code similar to this:
1613 const char *msg;
1615 int errnum;
1616 /* This disables the default behaviour of printing errors
1618 on stderr. */
1619 guestfs_set_error_handler (g, NULL, NULL);
1620 if (guestfs_launch (g) == -1) {
1622 /* Examine the error message and print it, throw it,
1623 etc. */
1624 msg = guestfs_last_error (g);
1625 errnum = guestfs_last_errno (g);
1626 fprintf (stderr, "%s", msg);
1628 if (errnum != 0)
1629 fprintf (stderr, ": %s", strerror (errnum));
1630 fprintf (stderr, "\n");
1631 /* ... */
1633 }
1634 "guestfs_create" returns "NULL" if the handle cannot be created, and
1636 because there is no handle if this happens there is no way to get
1637 additional error information. Since libguestfs ≥ 1.20, you can use
1638 "guestfs_create_flags" to properly deal with errors during handle
1639 creation, although the vast majority of programs can continue to use
1640 "guestfs_create" and not worry about this situation.
1641 Out of memory errors are handled differently. The default action is to
1643 call abort(3). If this is undesirable, then you can set a handler
1644 using "guestfs_set_out_of_memory_handler".
1645 guestfs_last_error
1647 const char *guestfs_last_error (guestfs_h *g);
1648 This returns the last error message that happened on "g". If there has
1650 not been an error since the handle was created, then this returns
1651 "NULL".
1652 Note the returned string does not have a newline character at the end.
1654 Most error messages are single lines. Some are split over multiple
1655 lines and contain "\n" characters within the string but not at the end.
1656 The lifetime of the returned string is until the next error occurs on
1658 the same handle, or "guestfs_close" is called. If you need to keep it
1659 longer, copy it.
1660 guestfs_last_errno
1662 int guestfs_last_errno (guestfs_h *g);
1663 This returns the last error number (errno) that happened on "g".
1665 If successful, an errno integer not equal to zero is returned.
1667 In many cases the special errno "ENOTSUP" is returned if you tried to
1669 call a function or use a feature which is not supported.
1670 If no error number is available, this returns 0. This call can return
1672 0 in three situations:
1673 1. There has not been any error on the handle.
1675 2. There has been an error but the errno was meaningless. This
1677 corresponds to the case where the error did not come from a failed
1678 system call, but for some other reason.
1679 3. There was an error from a failed system call, but for some reason
1681 the errno was not captured and returned. This usually indicates a
1682 bug in libguestfs.
1683 Libguestfs tries to convert the errno from inside the appliance into a
1685 corresponding errno for the caller (not entirely trivial: the appliance
1686 might be running a completely different operating system from the
1687 library and error numbers are not standardized across Un*xen). If this
1688 could not be done, then the error is translated to "EINVAL". In
1689 practice this should only happen in very rare circumstances.
1690 guestfs_set_error_handler
1692 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1693 void *opaque,
1694 const char *msg);
1695 void guestfs_set_error_handler (guestfs_h *g,
1696 guestfs_error_handler_cb cb,
1697 void *opaque);
1698 The callback "cb" will be called if there is an error. The parameters
1700 passed to the callback are an opaque data pointer and the error message
1701 string.
1702 "errno" is not passed to the callback. To get that the callback must
1704 call "guestfs_last_errno".
1705 Note that the message string "msg" is freed as soon as the callback
1707 function returns, so if you want to stash it somewhere you must make
1708 your own copy.
1709 The default handler prints messages on "stderr".
1711 If you set "cb" to "NULL" then no handler is called.
1713 guestfs_get_error_handler
1715 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1716 void **opaque_rtn);
1717 Returns the current error handler callback.
1719 guestfs_push_error_handler
1721 void guestfs_push_error_handler (guestfs_h *g,
1722 guestfs_error_handler_cb cb,
1723 void *opaque);
1724 This is the same as "guestfs_set_error_handler", except that the old
1726 error handler is stashed away in a stack inside the handle. You can
1727 restore the previous error handler by calling
1728 "guestfs_pop_error_handler".
1729 Use the following code to temporarily disable errors around a function:
1731 guestfs_push_error_handler (g, NULL, NULL);
1733 guestfs_mkdir (g, "/foo"); /* We don't care if this fails. */
1734 guestfs_pop_error_handler (g);
1735 guestfs_pop_error_handler
1737 void guestfs_pop_error_handler (guestfs_h *g);
1738 Restore the previous error handler (see "guestfs_push_error_handler").
1740 If you pop the stack too many times, then the default error handler is
1742 restored.
1743 guestfs_set_out_of_memory_handler
1745 typedef void (*guestfs_abort_cb) (void);
1746 void guestfs_set_out_of_memory_handler (guestfs_h *g,
1747 guestfs_abort_cb);
1748 The callback "cb" will be called if there is an out of memory
1750 situation. Note this callback must not return.
1751 The default is to call abort(3).
1753 You cannot set "cb" to "NULL". You can’t ignore out of memory
1755 situations.
1756 guestfs_get_out_of_memory_handler
1758 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1759 This returns the current out of memory handler.
1761
1763 guestfs_acl_delete_def_file
1764 int
1765 guestfs_acl_delete_def_file (guestfs_h *g,
1766 const char *dir);
1767 This function deletes the default POSIX Access Control List (ACL)
1769 attached to directory "dir".
1770 This function returns 0 on success or -1 on error.
1772 This function depends on the feature "acl". See also
1774 "guestfs_feature_available".
1775 (Added in 1.19.63)
1777 guestfs_acl_get_file
1779 char *
1780 guestfs_acl_get_file (guestfs_h *g,
1781 const char *path,
1782 const char *acltype);
1783 This function returns the POSIX Access Control List (ACL) attached to
1785 "path". The ACL is returned in "long text form" (see acl(5)).
1786 The "acltype" parameter may be:
1788 "access"
1790 Return the ordinary (access) ACL for any file, directory or other
1791 filesystem object.
1792 "default"
1794 Return the default ACL. Normally this only makes sense if "path"
1795 is a directory.
1796 This function returns a string, or NULL on error. The caller must free
1798 the returned string after use.
1799 This function depends on the feature "acl". See also
1801 "guestfs_feature_available".
1802 (Added in 1.19.63)
1804 guestfs_acl_set_file
1806 int
1807 guestfs_acl_set_file (guestfs_h *g,
1808 const char *path,
1809 const char *acltype,
1810 const char *acl);
1811 This function sets the POSIX Access Control List (ACL) attached to
1813 "path".
1814 The "acltype" parameter may be:
1816 "access"
1818 Set the ordinary (access) ACL for any file, directory or other
1819 filesystem object.
1820 "default"
1822 Set the default ACL. Normally this only makes sense if "path" is a
1823 directory.
1824 The "acl" parameter is the new ACL in either "long text form" or "short
1826 text form" (see acl(5)). The new ACL completely replaces any previous
1827 ACL on the file. The ACL must contain the full Unix permissions (eg.
1828 "u::rwx,g::rx,o::rx").
1829 If you are specifying individual users or groups, then the mask field
1831 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1832 "g:ID:..." field(s). A full ACL string might therefore look like this:
1833 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1835 \ Unix permissions / \mask/ \ ACL /
1836 You should use numeric UIDs and GIDs. To map usernames and groupnames
1838 to the correct numeric ID in the context of the guest, use the Augeas
1839 functions (see "guestfs_aug_init").
1840 This function returns 0 on success or -1 on error.
1842 This function depends on the feature "acl". See also
1844 "guestfs_feature_available".
1845 (Added in 1.19.63)
1847 guestfs_add_cdrom
1849 int
1850 guestfs_add_cdrom (guestfs_h *g,
1851 const char *filename);
1852 This function is deprecated. In new code, use the
1854 "guestfs_add_drive_ro" call instead.
1855 Deprecated functions will not be removed from the API, but the fact
1857 that they are deprecated indicates that there are problems with correct
1858 use of these functions.
1859 This function adds a virtual CD-ROM disk image to the guest.
1861 The image is added as read-only drive, so this function is equivalent
1863 of "guestfs_add_drive_ro".
1864 This function returns 0 on success or -1 on error.
1866 (Added in 0.3)
1868 guestfs_add_domain
1870 int
1871 guestfs_add_domain (guestfs_h *g,
1872 const char *dom,
1873 ...);
1874 You may supply a list of optional arguments to this call. Use zero or
1876 more of the following pairs of parameters, and terminate the list with
1877 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
1878 GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
1880 GUESTFS_ADD_DOMAIN_READONLY, int readonly,
1881 GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
1882 GUESTFS_ADD_DOMAIN_LIVE, int live,
1883 GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
1884 GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
1885 GUESTFS_ADD_DOMAIN_CACHEMODE, const char *cachemode,
1886 GUESTFS_ADD_DOMAIN_DISCARD, const char *discard,
1887 GUESTFS_ADD_DOMAIN_COPYONREAD, int copyonread,
1888 This function adds the disk(s) attached to the named libvirt domain
1890 "dom". It works by connecting to libvirt, requesting the domain and
1891 domain XML from libvirt, parsing it for disks, and calling
1892 "guestfs_add_drive_opts" on each one.
1893 The number of disks added is returned. This operation is atomic: if an
1895 error is returned, then no disks are added.
1896 This function does some minimal checks to make sure the libvirt domain
1898 is not running (unless "readonly" is true). In a future version we
1899 will try to acquire the libvirt lock on each disk.
1900 Disks must be accessible locally. This often means that adding disks
1902 from a remote libvirt connection (see https://libvirt.org/remote.html)
1903 will fail unless those disks are accessible via the same device path
1904 locally too.
1905 The optional "libvirturi" parameter sets the libvirt URI (see
1907 https://libvirt.org/uri.html). If this is not set then we connect to
1908 the default libvirt URI (or one set through an environment variable,
1909 see the libvirt documentation for full details).
1910 The optional "live" flag is ignored in libguestfs ≥ 1.48.
1912 If the "allowuuid" flag is true (default is false) then a UUID may be
1914 passed instead of the domain name. The "dom" string is treated as a
1915 UUID first and looked up, and if that lookup fails then we treat "dom"
1916 as a name as usual.
1917 The optional "readonlydisk" parameter controls what we do for disks
1919 which are marked <readonly/> in the libvirt XML. Possible values are:
1920 readonlydisk = "error"
1922 If "readonly" is false:
1923 The whole call is aborted with an error if any disk with the
1925 <readonly/> flag is found.
1926 If "readonly" is true:
1928 Disks with the <readonly/> flag are added read-only.
1930 readonlydisk = "read"
1932 If "readonly" is false:
1933 Disks with the <readonly/> flag are added read-only. Other disks
1935 are added read/write.
1936 If "readonly" is true:
1938 Disks with the <readonly/> flag are added read-only.
1940 readonlydisk = "write" (default)
1942 If "readonly" is false:
1943 Disks with the <readonly/> flag are added read/write.
1945 If "readonly" is true:
1947 Disks with the <readonly/> flag are added read-only.
1949 readonlydisk = "ignore"
1951 If "readonly" is true or false:
1952 Disks with the <readonly/> flag are skipped.
1954 If present, the value of "logical_block_size" attribute of <blockio/>
1956 tag in libvirt XML will be passed as "blocksize" parameter to
1957 "guestfs_add_drive_opts".
1958 The other optional parameters are passed directly through to
1960 "guestfs_add_drive_opts".
1961 On error this function returns -1.
1963 (Added in 1.7.4)
1965 guestfs_add_domain_va
1967 int
1968 guestfs_add_domain_va (guestfs_h *g,
1969 const char *dom,
1970 va_list args);
1971 This is the "va_list variant" of "guestfs_add_domain".
1973 See "CALLS WITH OPTIONAL ARGUMENTS".
1975 guestfs_add_domain_argv
1977 int
1978 guestfs_add_domain_argv (guestfs_h *g,
1979 const char *dom,
1980 const struct guestfs_add_domain_argv *optargs);
1981 This is the "argv variant" of "guestfs_add_domain".
1983 See "CALLS WITH OPTIONAL ARGUMENTS".
1985 guestfs_add_drive
1987 int
1988 guestfs_add_drive (guestfs_h *g,
1989 const char *filename);
1990 This function is provided for backwards compatibility with earlier
1992 versions of libguestfs. It simply calls "guestfs_add_drive_opts" with
1993 no optional arguments.
1994 (Added in 0.3)
1996 guestfs_add_drive_opts
1998 int
1999 guestfs_add_drive_opts (guestfs_h *g,
2000 const char *filename,
2001 ...);
2002 You may supply a list of optional arguments to this call. Use zero or
2004 more of the following pairs of parameters, and terminate the list with
2005 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2006 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2008 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2009 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2010 GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2011 GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2012 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2013 GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2014 GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2015 GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2016 GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2017 GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2018 GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2019 GUESTFS_ADD_DRIVE_OPTS_BLOCKSIZE, int blocksize,
2020 This function adds a disk image called filename to the handle.
2022 filename may be a regular host file or a host device.
2023 When this function is called before "guestfs_launch" (the usual case)
2025 then the first time you call this function, the disk appears in the API
2026 as /dev/sda, the second time as /dev/sdb, and so on.
2027 You don't necessarily need to be root when using libguestfs. However
2029 you obviously do need sufficient permissions to access the filename for
2030 whatever operations you want to perform (ie. read access if you just
2031 want to read the image or write access if you want to modify the
2032 image).
2033 This call checks that filename exists.
2035 filename may be the special string "/dev/null". See "NULL DISKS".
2037 The optional arguments are:
2039 "readonly"
2041 If true then the image is treated as read-only. Writes are still
2042 allowed, but they are stored in a temporary snapshot overlay which
2043 is discarded at the end. The disk that you add is not modified.
2044 "format"
2046 This forces the image format. If you omit this (or use
2047 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2048 automatically detected. Possible formats include "raw" and
2049 "qcow2".
2050 Automatic detection of the format opens you up to a potential
2052 security hole when dealing with untrusted raw-format images. See
2053 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
2054 security hole.
2055 "iface"
2057 This rarely-used option lets you emulate the behaviour of the
2058 deprecated "guestfs_add_drive_with_if" call (q.v.)
2059 "name"
2061 This field used to be passed as a hint for guest inspection, but it
2062 is no longer used.
2063 "label"
2065 Give the disk a label. The label should be a unique, short string
2066 using only ASCII characters "[a-zA-Z]". As well as its usual name
2067 in the API (such as /dev/sda), the drive will also be named
2068 /dev/disk/guestfs/label.
2069 See "DISK LABELS".
2071 "protocol"
2073 The optional protocol argument can be used to select an alternate
2074 source protocol.
2075 See also: "REMOTE STORAGE".
2077 "protocol = "file""
2079 filename is interpreted as a local file or device. This is the
2080 default if the optional protocol parameter is omitted.
2081 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
2083 Connect to a remote FTP, HTTP or TFTP server. The "server"
2084 parameter must also be supplied - see below.
2085 See also: "FTP, HTTP AND TFTP"
2087 "protocol = "gluster""
2089 Connect to the GlusterFS server. The "server" parameter must
2090 also be supplied - see below.
2091 See also: "GLUSTER"
2093 "protocol = "iscsi""
2095 Connect to the iSCSI server. The "server" parameter must also
2096 be supplied - see below. The "username" parameter may be
2097 supplied. See below. The "secret" parameter may be supplied.
2098 See below.
2099 See also: "ISCSI".
2101 "protocol = "nbd""
2103 Connect to the Network Block Device server. The "server"
2104 parameter must also be supplied - see below.
2105 See also: "NETWORK BLOCK DEVICE".
2107 "protocol = "rbd""
2109 Connect to the Ceph (librbd/RBD) server. The "server"
2110 parameter must also be supplied - see below. The "username"
2111 parameter may be supplied. See below. The "secret" parameter
2112 may be supplied. See below.
2113 See also: "CEPH".
2115 "protocol = "sheepdog""
2117 Connect to the Sheepdog server. The "server" parameter may
2118 also be supplied - see below.
2119 See also: "SHEEPDOG".
2121 "protocol = "ssh""
2123 Connect to the Secure Shell (ssh) server.
2124 The "server" parameter must be supplied. The "username"
2126 parameter may be supplied. See below.
2127 See also: "SSH".
2129 "server"
2131 For protocols which require access to a remote server, this is a
2132 list of server(s).
2133 Protocol Number of servers required
2135 -------- --------------------------
2136 file List must be empty or param not used at all
2137 ftp|ftps|http|https|tftp Exactly one
2138 gluster Exactly one
2139 iscsi Exactly one
2140 nbd Exactly one
2141 rbd Zero or more
2142 sheepdog Zero or more
2143 ssh Exactly one
2144 Each list element is a string specifying a server. The string must
2146 be in one of the following formats:
2147 hostname
2149 hostname:port
2150 tcp:hostname
2151 tcp:hostname:port
2152 unix:/path/to/socket
2153 If the port number is omitted, then the standard port number for
2155 the protocol is used (see /etc/services).
2156 "username"
2158 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
2159 "tftp" protocols, this specifies the remote username.
2160 If not given, then the local username is used for "ssh", and no
2162 authentication is attempted for ceph. But note this sometimes may
2163 give unexpected results, for example if using the libvirt backend
2164 and if the libvirt backend is configured to start the qemu
2165 appliance as a special user such as "qemu.qemu". If in doubt,
2166 specify the remote username you want.
2167 "secret"
2169 For the "rbd" protocol only, this specifies the ‘secret’ to use
2170 when connecting to the remote device. It must be base64 encoded.
2171 If not given, then a secret matching the given username will be
2173 looked up in the default keychain locations, or if no username is
2174 given, then no authentication will be used.
2175 "cachemode"
2177 Choose whether or not libguestfs will obey sync operations (safe
2178 but slow) or not (unsafe but fast). The possible values for this
2179 string are:
2180 "cachemode = "writeback""
2182 This is the default.
2183 Write operations in the API do not return until a write(2) call
2185 has completed in the host [but note this does not imply that
2186 anything gets written to disk].
2187 Sync operations in the API, including implicit syncs caused by
2189 filesystem journalling, will not return until an fdatasync(2)
2190 call has completed in the host, indicating that data has been
2191 committed to disk.
2192 "cachemode = "unsafe""
2194 In this mode, there are no guarantees. Libguestfs may cache
2195 anything and ignore sync requests. This is suitable only for
2196 scratch or temporary disks.
2197 "discard"
2199 Enable or disable discard (a.k.a. trim or unmap) support on this
2200 drive. If enabled, operations such as "guestfs_fstrim" will be
2201 able to discard / make thin / punch holes in the underlying host
2202 file or device.
2203 Possible discard settings are:
2205 "discard = "disable""
2207 Disable discard support. This is the default.
2208 "discard = "enable""
2210 Enable discard support. Fail if discard is not possible.
2211 "discard = "besteffort""
2213 Enable discard support if possible, but don't fail if it is not
2214 supported.
2215 Since not all backends and not all underlying systems support
2217 discard, this is a good choice if you want to use discard if
2218 possible, but don't mind if it doesn't work.
2219 "copyonread"
2221 The boolean parameter "copyonread" enables copy-on-read support.
2222 This only affects disk formats which have backing files, and causes
2223 reads to be stored in the overlay layer, speeding up multiple reads
2224 of the same area of disk.
2225 The default is false.
2227 "blocksize"
2229 This parameter sets the sector size of the disk. Possible values
2230 are 512 (the default if the parameter is omitted) or 4096. Use
2231 4096 when handling an "Advanced Format" disk that uses 4K sector
2232 size (https://en.wikipedia.org/wiki/Advanced_Format).
2233 Only a subset of the backends support this parameter (currently
2235 only the libvirt and direct backends do).
2236 This function returns 0 on success or -1 on error.
2238 (Added in 0.3)
2240 guestfs_add_drive_opts_va
2242 int
2243 guestfs_add_drive_opts_va (guestfs_h *g,
2244 const char *filename,
2245 va_list args);
2246 This is the "va_list variant" of "guestfs_add_drive_opts".
2248 See "CALLS WITH OPTIONAL ARGUMENTS".
2250 guestfs_add_drive_opts_argv
2252 int
2253 guestfs_add_drive_opts_argv (guestfs_h *g,
2254 const char *filename,
2255 const struct guestfs_add_drive_opts_argv *optargs);
2256 This is the "argv variant" of "guestfs_add_drive_opts".
2258 See "CALLS WITH OPTIONAL ARGUMENTS".
2260 guestfs_add_drive_ro
2262 int
2263 guestfs_add_drive_ro (guestfs_h *g,
2264 const char *filename);
2265 This function is the equivalent of calling "guestfs_add_drive_opts"
2267 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2268 so the disk is added read-only, with the format being detected
2269 automatically.
2270 This function returns 0 on success or -1 on error.
2272 (Added in 1.0.38)
2274 guestfs_add_drive_ro_with_if
2276 int
2277 guestfs_add_drive_ro_with_if (guestfs_h *g,
2278 const char *filename,
2279 const char *iface);
2280 This function is deprecated. In new code, use the "guestfs_add_drive"
2282 call instead.
2283 Deprecated functions will not be removed from the API, but the fact
2285 that they are deprecated indicates that there are problems with correct
2286 use of these functions.
2287 This is the same as "guestfs_add_drive_ro" but it allows you to specify
2289 the QEMU interface emulation to use at run time.
2290 This function returns 0 on success or -1 on error.
2292 (Added in 1.0.84)
2294 guestfs_add_drive_scratch
2296 int
2297 guestfs_add_drive_scratch (guestfs_h *g,
2298 int64_t size,
2299 ...);
2300 You may supply a list of optional arguments to this call. Use zero or
2302 more of the following pairs of parameters, and terminate the list with
2303 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2304 GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2306 GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2307 GUESTFS_ADD_DRIVE_SCRATCH_BLOCKSIZE, int blocksize,
2308 This command adds a temporary scratch drive to the handle. The "size"
2310 parameter is the virtual size (in bytes). The scratch drive is blank
2311 initially (all reads return zeroes until you start writing to it). The
2312 drive is deleted when the handle is closed.
2313 The optional arguments "name", "label" and "blocksize" are passed
2315 through to "guestfs_add_drive_opts".
2316 This function returns 0 on success or -1 on error.
2318 (Added in 1.23.10)
2320 guestfs_add_drive_scratch_va
2322 int
2323 guestfs_add_drive_scratch_va (guestfs_h *g,
2324 int64_t size,
2325 va_list args);
2326 This is the "va_list variant" of "guestfs_add_drive_scratch".
2328 See "CALLS WITH OPTIONAL ARGUMENTS".
2330 guestfs_add_drive_scratch_argv
2332 int
2333 guestfs_add_drive_scratch_argv (guestfs_h *g,
2334 int64_t size,
2335 const struct guestfs_add_drive_scratch_argv *optargs);
2336 This is the "argv variant" of "guestfs_add_drive_scratch".
2338 See "CALLS WITH OPTIONAL ARGUMENTS".
2340 guestfs_add_drive_with_if
2342 int
2343 guestfs_add_drive_with_if (guestfs_h *g,
2344 const char *filename,
2345 const char *iface);
2346 This function is deprecated. In new code, use the "guestfs_add_drive"
2348 call instead.
2349 Deprecated functions will not be removed from the API, but the fact
2351 that they are deprecated indicates that there are problems with correct
2352 use of these functions.
2353 This is the same as "guestfs_add_drive" but it allows you to specify
2355 the QEMU interface emulation to use at run time.
2356 This function returns 0 on success or -1 on error.
2358 (Added in 1.0.84)
2360 guestfs_add_libvirt_dom
2362 int
2363 guestfs_add_libvirt_dom (guestfs_h *g,
2364 void * /* really virDomainPtr */ dom,
2365 ...);
2366 You may supply a list of optional arguments to this call. Use zero or
2368 more of the following pairs of parameters, and terminate the list with
2369 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2370 GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2372 GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2373 GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2374 GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2375 GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2376 GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2377 GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2378 This function adds the disk(s) attached to the libvirt domain "dom".
2380 It works by requesting the domain XML from libvirt, parsing it for
2381 disks, and calling "guestfs_add_drive_opts" on each one.
2382 In the C API we declare "void *dom", but really it has type
2384 "virDomainPtr dom". This is so we don't need <libvirt.h>.
2385 The number of disks added is returned. This operation is atomic: if an
2387 error is returned, then no disks are added.
2388 This function does some minimal checks to make sure the libvirt domain
2390 is not running (unless "readonly" is true). In a future version we
2391 will try to acquire the libvirt lock on each disk.
2392 Disks must be accessible locally. This often means that adding disks
2394 from a remote libvirt connection (see https://libvirt.org/remote.html)
2395 will fail unless those disks are accessible via the same device path
2396 locally too.
2397 The optional "live" flag is ignored in libguestfs ≥ 1.48.
2399 The optional "readonlydisk" parameter controls what we do for disks
2401 which are marked <readonly/> in the libvirt XML. See
2402 "guestfs_add_domain" for possible values.
2403 If present, the value of "logical_block_size" attribute of <blockio/>
2405 tag in libvirt XML will be passed as "blocksize" parameter to
2406 "guestfs_add_drive_opts".
2407 The other optional parameters are passed directly through to
2409 "guestfs_add_drive_opts".
2410 On error this function returns -1.
2412 (Added in 1.29.14)
2414 guestfs_add_libvirt_dom_va
2416 int
2417 guestfs_add_libvirt_dom_va (guestfs_h *g,
2418 void * /* really virDomainPtr */ dom,
2419 va_list args);
2420 This is the "va_list variant" of "guestfs_add_libvirt_dom".
2422 See "CALLS WITH OPTIONAL ARGUMENTS".
2424 guestfs_add_libvirt_dom_argv
2426 int
2427 guestfs_add_libvirt_dom_argv (guestfs_h *g,
2428 void * /* really virDomainPtr */ dom,
2429 const struct guestfs_add_libvirt_dom_argv *optargs);
2430 This is the "argv variant" of "guestfs_add_libvirt_dom".
2432 See "CALLS WITH OPTIONAL ARGUMENTS".
2434 guestfs_aug_clear
2436 int
2437 guestfs_aug_clear (guestfs_h *g,
2438 const char *augpath);
2439 Set the value associated with "path" to "NULL". This is the same as
2441 the augtool(1) "clear" command.
2442 This function returns 0 on success or -1 on error.
2444 (Added in 1.3.4)
2446 guestfs_aug_close
2448 int
2449 guestfs_aug_close (guestfs_h *g);
2450 Close the current Augeas handle and free up any resources used by it.
2452 After calling this, you have to call "guestfs_aug_init" again before
2453 you can use any other Augeas functions.
2454 This function returns 0 on success or -1 on error.
2456 (Added in 0.7)
2458 guestfs_aug_defnode
2460 struct guestfs_int_bool *
2461 guestfs_aug_defnode (guestfs_h *g,
2462 const char *name,
2463 const char *expr,
2464 const char *val);
2465 Defines a variable "name" whose value is the result of evaluating
2467 "expr".
2468 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2470 to calling "guestfs_aug_set" "expr", "val". "name" will be the nodeset
2471 containing that single node.
2472 On success this returns a pair containing the number of nodes in the
2474 nodeset, and a boolean flag if a node was created.
2475 This function returns a "struct guestfs_int_bool *", or NULL if there
2477 was an error. The caller must call "guestfs_free_int_bool" after use.
2478 (Added in 0.7)
2480 guestfs_aug_defvar
2482 int
2483 guestfs_aug_defvar (guestfs_h *g,
2484 const char *name,
2485 const char *expr);
2486 Defines an Augeas variable "name" whose value is the result of
2488 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2489 On success this returns the number of nodes in "expr", or 0 if "expr"
2491 evaluates to something which is not a nodeset.
2492 On error this function returns -1.
2494 (Added in 0.7)
2496 guestfs_aug_get
2498 char *
2499 guestfs_aug_get (guestfs_h *g,
2500 const char *augpath);
2501 Look up the value associated with "path". If "path" matches exactly
2503 one node, the "value" is returned.
2504 This function returns a string, or NULL on error. The caller must free
2506 the returned string after use.
2507 (Added in 0.7)
2509 guestfs_aug_init
2511 int
2512 guestfs_aug_init (guestfs_h *g,
2513 const char *root,
2514 int flags);
2515 Create a new Augeas handle for editing configuration files. If there
2517 was any previous Augeas handle associated with this guestfs session,
2518 then it is closed.
2519 You must call this before using any other "guestfs_aug_*" commands.
2521 "root" is the filesystem root. "root" must not be NULL, use / instead.
2523 The flags are the same as the flags defined in <augeas.h>, the logical
2525 or of the following integers:
2526 "AUG_SAVE_BACKUP" = 1
2528 Keep the original file with a ".augsave" extension.
2529 "AUG_SAVE_NEWFILE" = 2
2531 Save changes into a file with extension ".augnew", and do not
2532 overwrite original. Overrides "AUG_SAVE_BACKUP".
2533 "AUG_TYPE_CHECK" = 4
2535 Typecheck lenses.
2536 This option is only useful when debugging Augeas lenses. Use of
2538 this option may require additional memory for the libguestfs
2539 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2540 environment variable or call "guestfs_set_memsize".
2541 "AUG_NO_STDINC" = 8
2543 Do not use standard load path for modules.
2544 "AUG_SAVE_NOOP" = 16
2546 Make save a no-op, just record what would have been changed.
2547 "AUG_NO_LOAD" = 32
2549 Do not load the tree in "guestfs_aug_init".
2550 To close the handle, you can call "guestfs_aug_close".
2552 To find out more about Augeas, see http://augeas.net/.
2554 This function returns 0 on success or -1 on error.
2556 (Added in 0.7)
2558 guestfs_aug_insert
2560 int
2561 guestfs_aug_insert (guestfs_h *g,
2562 const char *augpath,
2563 const char *label,
2564 int before);
2565 Create a new sibling "label" for "path", inserting it into the tree
2567 before or after "path" (depending on the boolean flag "before").
2568 "path" must match exactly one existing node in the tree, and "label"
2570 must be a label, ie. not contain /, "*" or end with a bracketed index
2571 "[N]".
2572 This function returns 0 on success or -1 on error.
2574 (Added in 0.7)
2576 guestfs_aug_label
2578 char *
2579 guestfs_aug_label (guestfs_h *g,
2580 const char *augpath);
2581 The label (name of the last element) of the Augeas path expression
2583 "augpath" is returned. "augpath" must match exactly one node, else
2584 this function returns an error.
2585 This function returns a string, or NULL on error. The caller must free
2587 the returned string after use.
2588 (Added in 1.23.14)
2590 guestfs_aug_load
2592 int
2593 guestfs_aug_load (guestfs_h *g);
2594 Load files into the tree.
2596 See "aug_load" in the Augeas documentation for the full gory details.
2598 This function returns 0 on success or -1 on error.
2600 (Added in 0.7)
2602 guestfs_aug_ls
2604 char **
2605 guestfs_aug_ls (guestfs_h *g,
2606 const char *augpath);
2607 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2609 sorting the resulting nodes into alphabetical order.
2610 This function returns a NULL-terminated array of strings (like
2612 environ(3)), or NULL if there was an error. The caller must free the
2613 strings and the array after use.
2614 (Added in 0.8)
2616 guestfs_aug_match
2618 char **
2619 guestfs_aug_match (guestfs_h *g,
2620 const char *augpath);
2621 Returns a list of paths which match the path expression "path". The
2623 returned paths are sufficiently qualified so that they match exactly
2624 one node in the current tree.
2625 This function returns a NULL-terminated array of strings (like
2627 environ(3)), or NULL if there was an error. The caller must free the
2628 strings and the array after use.
2629 (Added in 0.7)
2631 guestfs_aug_mv
2633 int
2634 guestfs_aug_mv (guestfs_h *g,
2635 const char *src,
2636 const char *dest);
2637 Move the node "src" to "dest". "src" must match exactly one node.
2639 "dest" is overwritten if it exists.
2640 This function returns 0 on success or -1 on error.
2642 (Added in 0.7)
2644 guestfs_aug_rm
2646 int
2647 guestfs_aug_rm (guestfs_h *g,
2648 const char *augpath);
2649 Remove "path" and all of its children.
2651 On success this returns the number of entries which were removed.
2653 On error this function returns -1.
2655 (Added in 0.7)
2657 guestfs_aug_save
2659 int
2660 guestfs_aug_save (guestfs_h *g);
2661 This writes all pending changes to disk.
2663 The flags which were passed to "guestfs_aug_init" affect exactly how
2665 files are saved.
2666 This function returns 0 on success or -1 on error.
2668 (Added in 0.7)
2670 guestfs_aug_set
2672 int
2673 guestfs_aug_set (guestfs_h *g,
2674 const char *augpath,
2675 const char *val);
2676 Set the value associated with "augpath" to "val".
2678 In the Augeas API, it is possible to clear a node by setting the value
2680 to NULL. Due to an oversight in the libguestfs API you cannot do that
2681 with this call. Instead you must use the "guestfs_aug_clear" call.
2682 This function returns 0 on success or -1 on error.
2684 (Added in 0.7)
2686 guestfs_aug_setm
2688 int
2689 guestfs_aug_setm (guestfs_h *g,
2690 const char *base,
2691 const char *sub,
2692 const char *val);
2693 Change multiple Augeas nodes in a single operation. "base" is an
2695 expression matching multiple nodes. "sub" is a path expression
2696 relative to "base". All nodes matching "base" are found, and then for
2697 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2698 which case the "base" nodes are modified.
2699 This returns the number of nodes modified.
2701 On error this function returns -1.
2703 (Added in 1.23.14)
2705 guestfs_aug_transform
2707 int
2708 guestfs_aug_transform (guestfs_h *g,
2709 const char *lens,
2710 const char *file,
2711 ...);
2712 You may supply a list of optional arguments to this call. Use zero or
2714 more of the following pairs of parameters, and terminate the list with
2715 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2716 GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2718 Add an Augeas transformation for the specified "lens" so it can handle
2720 "file".
2721 If "remove" is true ("false" by default), then the transformation is
2723 removed.
2724 This function returns 0 on success or -1 on error.
2726 (Added in 1.35.2)
2728 guestfs_aug_transform_va
2730 int
2731 guestfs_aug_transform_va (guestfs_h *g,
2732 const char *lens,
2733 const char *file,
2734 va_list args);
2735 This is the "va_list variant" of "guestfs_aug_transform".
2737 See "CALLS WITH OPTIONAL ARGUMENTS".
2739 guestfs_aug_transform_argv
2741 int
2742 guestfs_aug_transform_argv (guestfs_h *g,
2743 const char *lens,
2744 const char *file,
2745 const struct guestfs_aug_transform_argv *optargs);
2746 This is the "argv variant" of "guestfs_aug_transform".
2748 See "CALLS WITH OPTIONAL ARGUMENTS".
2750 guestfs_available
2752 int
2753 guestfs_available (guestfs_h *g,
2754 char *const *groups);
2755 This command is used to check the availability of some groups of
2757 functionality in the appliance, which not all builds of the libguestfs
2758 appliance will be able to provide.
2759 The libguestfs groups, and the functions that those groups correspond
2761 to, are listed in "AVAILABILITY". You can also fetch this list at
2762 runtime by calling "guestfs_available_all_groups".
2763 The argument "groups" is a list of group names, eg: "["inotify",
2765 "augeas"]" would check for the availability of the Linux inotify
2766 functions and Augeas (configuration file editing) functions.
2767 The command returns no error if all requested groups are available.
2769 It fails with an error if one or more of the requested groups is
2771 unavailable in the appliance.
2772 If an unknown group name is included in the list of groups then an
2774 error is always returned.
2775 Notes:
2777 • "guestfs_feature_available" is the same as this call, but with a
2779 slightly simpler to use API: that call returns a boolean true/false
2780 instead of throwing an error.
2781 • You must call "guestfs_launch" before calling this function.
2783 The reason is because we don't know what groups are supported by
2785 the appliance/daemon until it is running and can be queried.
2786 • If a group of functions is available, this does not necessarily
2788 mean that they will work. You still have to check for errors when
2789 calling individual API functions even if they are available.
2790 • It is usually the job of distro packagers to build complete
2792 functionality into the libguestfs appliance. Upstream libguestfs,
2793 if built from source with all requirements satisfied, will support
2794 everything.
2795 • This call was added in version 1.0.80. In previous versions of
2797 libguestfs all you could do would be to speculatively execute a
2798 command to find out if the daemon implemented it. See also
2799 "guestfs_version".
2800 See also "guestfs_filesystem_available".
2802 This function returns 0 on success or -1 on error.
2804 (Added in 1.0.80)
2806 guestfs_available_all_groups
2808 char **
2809 guestfs_available_all_groups (guestfs_h *g);
2810 This command returns a list of all optional groups that this daemon
2812 knows about. Note this returns both supported and unsupported groups.
2813 To find out which ones the daemon can actually support you have to call
2814 "guestfs_available" / "guestfs_feature_available" on each member of the
2815 returned list.
2816 See also "guestfs_available", "guestfs_feature_available" and
2818 "AVAILABILITY".
2819 This function returns a NULL-terminated array of strings (like
2821 environ(3)), or NULL if there was an error. The caller must free the
2822 strings and the array after use.
2823 (Added in 1.3.15)
2825 guestfs_base64_in
2827 int
2828 guestfs_base64_in (guestfs_h *g,
2829 const char *base64file,
2830 const char *filename);
2831 This command uploads base64-encoded data from "base64file" to filename.
2833 This function returns 0 on success or -1 on error.
2835 (Added in 1.3.5)
2837 guestfs_base64_out
2839 int
2840 guestfs_base64_out (guestfs_h *g,
2841 const char *filename,
2842 const char *base64file);
2843 This command downloads the contents of filename, writing it out to
2845 local file "base64file" encoded as base64.
2846 This function returns 0 on success or -1 on error.
2848 (Added in 1.3.5)
2850 guestfs_blkdiscard
2852 int
2853 guestfs_blkdiscard (guestfs_h *g,
2854 const char *device);
2855 This discards all blocks on the block device "device", giving the free
2857 space back to the host.
2858 This operation requires support in libguestfs, the host filesystem,
2860 qemu and the host kernel. If this support isn't present it may give an
2861 error or even appear to run but do nothing. You must also set the
2862 "discard" attribute on the underlying drive (see
2863 "guestfs_add_drive_opts").
2864 This function returns 0 on success or -1 on error.
2866 This function depends on the feature "blkdiscard". See also
2868 "guestfs_feature_available".
2869 (Added in 1.25.44)
2871 guestfs_blkdiscardzeroes
2873 int
2874 guestfs_blkdiscardzeroes (guestfs_h *g,
2875 const char *device);
2876 This call returns true if blocks on "device" that have been discarded
2878 by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
2879 when read the next time.
2880 If it returns false, then it may be that discarded blocks are read as
2882 stale or random data.
2883 This function returns a C truth value on success or -1 on error.
2885 This function depends on the feature "blkdiscardzeroes". See also
2887 "guestfs_feature_available".
2888 (Added in 1.25.44)
2890 guestfs_blkid
2892 char **
2893 guestfs_blkid (guestfs_h *g,
2894 const char *device);
2895 This command returns block device attributes for "device". The
2897 following fields are usually present in the returned hash. Other fields
2898 may also be present.
2899 "UUID"
2901 The uuid of this device.
2902 "LABEL"
2904 The label of this device.
2905 "VERSION"
2907 The version of blkid command.
2908 "TYPE"
2910 The filesystem type or RAID of this device.
2911 "USAGE"
2913 The usage of this device, for example "filesystem" or "raid".
2914 This function returns a NULL-terminated array of strings, or NULL if
2916 there was an error. The array of strings will always have length
2917 "2n+1", where "n" keys and values alternate, followed by the trailing
2918 NULL entry. The caller must free the strings and the array after use.
2919 (Added in 1.15.9)
2921 guestfs_blockdev_flushbufs
2923 int
2924 guestfs_blockdev_flushbufs (guestfs_h *g,
2925 const char *device);
2926 This tells the kernel to flush internal buffers associated with
2928 "device".
2929 This uses the blockdev(8) command.
2931 This function returns 0 on success or -1 on error.
2933 (Added in 1.9.3)
2935 guestfs_blockdev_getbsz
2937 int
2938 guestfs_blockdev_getbsz (guestfs_h *g,
2939 const char *device);
2940 This returns the block size of a device.
2942 Note: this is different from both size in blocks and filesystem block
2944 size. Also this setting is not really used by anything. You should
2945 probably not use it for anything. Filesystems have their own idea
2946 about what block size to choose.
2947 This uses the blockdev(8) command.
2949 On error this function returns -1.
2951 (Added in 1.9.3)
2953 guestfs_blockdev_getro
2955 int
2956 guestfs_blockdev_getro (guestfs_h *g,
2957 const char *device);
2958 Returns a boolean indicating if the block device is read-only (true if
2960 read-only, false if not).
2961 This uses the blockdev(8) command.
2963 This function returns a C truth value on success or -1 on error.
2965 (Added in 1.9.3)
2967 guestfs_blockdev_getsize64
2969 int64_t
2970 guestfs_blockdev_getsize64 (guestfs_h *g,
2971 const char *device);
2972 This returns the size of the device in bytes.
2974 See also "guestfs_blockdev_getsz".
2976 This uses the blockdev(8) command.
2978 On error this function returns -1.
2980 (Added in 1.9.3)
2982 guestfs_blockdev_getss
2984 int
2985 guestfs_blockdev_getss (guestfs_h *g,
2986 const char *device);
2987 This returns the size of sectors on a block device. Usually 512, but
2989 can be larger for modern devices.
2990 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
2992 for that).
2993 This uses the blockdev(8) command.
2995 On error this function returns -1.
2997 (Added in 1.9.3)
2999 guestfs_blockdev_getsz
3001 int64_t
3002 guestfs_blockdev_getsz (guestfs_h *g,
3003 const char *device);
3004 This returns the size of the device in units of 512-byte sectors (even
3006 if the sectorsize isn't 512 bytes ... weird).
3007 See also "guestfs_blockdev_getss" for the real sector size of the
3009 device, and "guestfs_blockdev_getsize64" for the more useful size in
3010 bytes.
3011 This uses the blockdev(8) command.
3013 On error this function returns -1.
3015 (Added in 1.9.3)
3017 guestfs_blockdev_rereadpt
3019 int
3020 guestfs_blockdev_rereadpt (guestfs_h *g,
3021 const char *device);
3022 Reread the partition table on "device".
3024 This uses the blockdev(8) command.
3026 This function returns 0 on success or -1 on error.
3028 (Added in 1.9.3)
3030 guestfs_blockdev_setbsz
3032 int
3033 guestfs_blockdev_setbsz (guestfs_h *g,
3034 const char *device,
3035 int blocksize);
3036 This function is deprecated. There is no replacement. Consult the API
3038 documentation in guestfs(3) for further information.
3039 Deprecated functions will not be removed from the API, but the fact
3041 that they are deprecated indicates that there are problems with correct
3042 use of these functions.
3043 This call does nothing and has never done anything because of a bug in
3045 blockdev. Do not use it.
3046 If you need to set the filesystem block size, use the "blocksize"
3048 option of "guestfs_mkfs".
3049 This function returns 0 on success or -1 on error.
3051 (Added in 1.9.3)
3053 guestfs_blockdev_setra
3055 int
3056 guestfs_blockdev_setra (guestfs_h *g,
3057 const char *device,
3058 int sectors);
3059 Set readahead (in 512-byte sectors) for the device.
3061 This uses the blockdev(8) command.
3063 This function returns 0 on success or -1 on error.
3065 (Added in 1.29.10)
3067 guestfs_blockdev_setro
3069 int
3070 guestfs_blockdev_setro (guestfs_h *g,
3071 const char *device);
3072 Sets the block device named "device" to read-only.
3074 This uses the blockdev(8) command.
3076 This function returns 0 on success or -1 on error.
3078 (Added in 1.9.3)
3080 guestfs_blockdev_setrw
3082 int
3083 guestfs_blockdev_setrw (guestfs_h *g,
3084 const char *device);
3085 Sets the block device named "device" to read-write.
3087 This uses the blockdev(8) command.
3089 This function returns 0 on success or -1 on error.
3091 (Added in 1.9.3)
3093 guestfs_btrfs_balance_cancel
3095 int
3096 guestfs_btrfs_balance_cancel (guestfs_h *g,
3097 const char *path);
3098 Cancel a running balance on a btrfs filesystem.
3100 This function returns 0 on success or -1 on error.
3102 This function depends on the feature "btrfs". See also
3104 "guestfs_feature_available".
3105 (Added in 1.29.22)
3107 guestfs_btrfs_balance_pause
3109 int
3110 guestfs_btrfs_balance_pause (guestfs_h *g,
3111 const char *path);
3112 Pause a running balance on a btrfs filesystem.
3114 This function returns 0 on success or -1 on error.
3116 This function depends on the feature "btrfs". See also
3118 "guestfs_feature_available".
3119 (Added in 1.29.22)
3121 guestfs_btrfs_balance_resume
3123 int
3124 guestfs_btrfs_balance_resume (guestfs_h *g,
3125 const char *path);
3126 Resume a paused balance on a btrfs filesystem.
3128 This function returns 0 on success or -1 on error.
3130 This function depends on the feature "btrfs". See also
3132 "guestfs_feature_available".
3133 (Added in 1.29.22)
3135 guestfs_btrfs_balance_status
3137 struct guestfs_btrfsbalance *
3138 guestfs_btrfs_balance_status (guestfs_h *g,
3139 const char *path);
3140 Show the status of a running or paused balance on a btrfs filesystem.
3142 This function returns a "struct guestfs_btrfsbalance *", or NULL if
3144 there was an error. The caller must call "guestfs_free_btrfsbalance"
3145 after use.
3146 This function depends on the feature "btrfs". See also
3148 "guestfs_feature_available".
3149 (Added in 1.29.26)
3151 guestfs_btrfs_device_add
3153 int
3154 guestfs_btrfs_device_add (guestfs_h *g,
3155 char *const *devices,
3156 const char *fs);
3157 Add the list of device(s) in "devices" to the btrfs filesystem mounted
3159 at "fs". If "devices" is an empty list, this does nothing.
3160 This function returns 0 on success or -1 on error.
3162 This function depends on the feature "btrfs". See also
3164 "guestfs_feature_available".
3165 (Added in 1.17.35)
3167 guestfs_btrfs_device_delete
3169 int
3170 guestfs_btrfs_device_delete (guestfs_h *g,
3171 char *const *devices,
3172 const char *fs);
3173 Remove the "devices" from the btrfs filesystem mounted at "fs". If
3175 "devices" is an empty list, this does nothing.
3176 This function returns 0 on success or -1 on error.
3178 This function depends on the feature "btrfs". See also
3180 "guestfs_feature_available".
3181 (Added in 1.17.35)
3183 guestfs_btrfs_filesystem_balance
3185 int
3186 guestfs_btrfs_filesystem_balance (guestfs_h *g,
3187 const char *fs);
3188 Balance the chunks in the btrfs filesystem mounted at "fs" across the
3190 underlying devices.
3191 This function returns 0 on success or -1 on error.
3193 This function depends on the feature "btrfs". See also
3195 "guestfs_feature_available".
3196 (Added in 1.17.35)
3198 guestfs_btrfs_filesystem_defragment
3200 int
3201 guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3202 const char *path,
3203 ...);
3204 You may supply a list of optional arguments to this call. Use zero or
3206 more of the following pairs of parameters, and terminate the list with
3207 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3208 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3210 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3211 Defragment a file or directory on a btrfs filesystem. compress is one
3213 of zlib or lzo.
3214 This function returns 0 on success or -1 on error.
3216 This function depends on the feature "btrfs". See also
3218 "guestfs_feature_available".
3219 (Added in 1.29.22)
3221 guestfs_btrfs_filesystem_defragment_va
3223 int
3224 guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3225 const char *path,
3226 va_list args);
3227 This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3229 See "CALLS WITH OPTIONAL ARGUMENTS".
3231 guestfs_btrfs_filesystem_defragment_argv
3233 int
3234 guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3235 const char *path,
3236 const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3237 This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3239 See "CALLS WITH OPTIONAL ARGUMENTS".
3241 guestfs_btrfs_filesystem_resize
3243 int
3244 guestfs_btrfs_filesystem_resize (guestfs_h *g,
3245 const char *mountpoint,
3246 ...);
3247 You may supply a list of optional arguments to this call. Use zero or
3249 more of the following pairs of parameters, and terminate the list with
3250 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3251 GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3253 This command resizes a btrfs filesystem.
3255 Note that unlike other resize calls, the filesystem has to be mounted
3257 and the parameter is the mountpoint not the device (this is a
3258 requirement of btrfs itself).
3259 The optional parameters are:
3261 "size"
3263 The new size (in bytes) of the filesystem. If omitted, the
3264 filesystem is resized to the maximum size.
3265 See also btrfs(8).
3267 This function returns 0 on success or -1 on error.
3269 This function depends on the feature "btrfs". See also
3271 "guestfs_feature_available".
3272 (Added in 1.11.17)
3274 guestfs_btrfs_filesystem_resize_va
3276 int
3277 guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3278 const char *mountpoint,
3279 va_list args);
3280 This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3282 See "CALLS WITH OPTIONAL ARGUMENTS".
3284 guestfs_btrfs_filesystem_resize_argv
3286 int
3287 guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3288 const char *mountpoint,
3289 const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3290 This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3292 See "CALLS WITH OPTIONAL ARGUMENTS".
3294 guestfs_btrfs_filesystem_show
3296 char **
3297 guestfs_btrfs_filesystem_show (guestfs_h *g,
3298 const char *device);
3299 Show all the devices where the filesystems in "device" is spanned over.
3301 If not all the devices for the filesystems are present, then this
3303 function fails and the "errno" is set to "ENODEV".
3304 This function returns a NULL-terminated array of strings (like
3306 environ(3)), or NULL if there was an error. The caller must free the
3307 strings and the array after use.
3308 This function depends on the feature "btrfs". See also
3310 "guestfs_feature_available".
3311 (Added in 1.33.29)
3313 guestfs_btrfs_filesystem_sync
3315 int
3316 guestfs_btrfs_filesystem_sync (guestfs_h *g,
3317 const char *fs);
3318 Force sync on the btrfs filesystem mounted at "fs".
3320 This function returns 0 on success or -1 on error.
3322 This function depends on the feature "btrfs". See also
3324 "guestfs_feature_available".
3325 (Added in 1.17.35)
3327 guestfs_btrfs_fsck
3329 int
3330 guestfs_btrfs_fsck (guestfs_h *g,
3331 const char *device,
3332 ...);
3333 You may supply a list of optional arguments to this call. Use zero or
3335 more of the following pairs of parameters, and terminate the list with
3336 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3337 GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3339 GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3340 Used to check a btrfs filesystem, "device" is the device file where the
3342 filesystem is stored.
3343 This function returns 0 on success or -1 on error.
3345 This function depends on the feature "btrfs". See also
3347 "guestfs_feature_available".
3348 (Added in 1.17.43)
3350 guestfs_btrfs_fsck_va
3352 int
3353 guestfs_btrfs_fsck_va (guestfs_h *g,
3354 const char *device,
3355 va_list args);
3356 This is the "va_list variant" of "guestfs_btrfs_fsck".
3358 See "CALLS WITH OPTIONAL ARGUMENTS".
3360 guestfs_btrfs_fsck_argv
3362 int
3363 guestfs_btrfs_fsck_argv (guestfs_h *g,
3364 const char *device,
3365 const struct guestfs_btrfs_fsck_argv *optargs);
3366 This is the "argv variant" of "guestfs_btrfs_fsck".
3368 See "CALLS WITH OPTIONAL ARGUMENTS".
3370 guestfs_btrfs_image
3372 int
3373 guestfs_btrfs_image (guestfs_h *g,
3374 char *const *source,
3375 const char *image,
3376 ...);
3377 You may supply a list of optional arguments to this call. Use zero or
3379 more of the following pairs of parameters, and terminate the list with
3380 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3381 GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3383 This is used to create an image of a btrfs filesystem. All data will
3385 be zeroed, but metadata and the like is preserved.
3386 This function returns 0 on success or -1 on error.
3388 This function depends on the feature "btrfs". See also
3390 "guestfs_feature_available".
3391 (Added in 1.29.32)
3393 guestfs_btrfs_image_va
3395 int
3396 guestfs_btrfs_image_va (guestfs_h *g,
3397 char *const *source,
3398 const char *image,
3399 va_list args);
3400 This is the "va_list variant" of "guestfs_btrfs_image".
3402 See "CALLS WITH OPTIONAL ARGUMENTS".
3404 guestfs_btrfs_image_argv
3406 int
3407 guestfs_btrfs_image_argv (guestfs_h *g,
3408 char *const *source,
3409 const char *image,
3410 const struct guestfs_btrfs_image_argv *optargs);
3411 This is the "argv variant" of "guestfs_btrfs_image".
3413 See "CALLS WITH OPTIONAL ARGUMENTS".
3415 guestfs_btrfs_qgroup_assign
3417 int
3418 guestfs_btrfs_qgroup_assign (guestfs_h *g,
3419 const char *src,
3420 const char *dst,
3421 const char *path);
3422 Add qgroup "src" to parent qgroup "dst". This command can group several
3424 qgroups into a parent qgroup to share common limit.
3425 This function returns 0 on success or -1 on error.
3427 This function depends on the feature "btrfs". See also
3429 "guestfs_feature_available".
3430 (Added in 1.29.17)
3432 guestfs_btrfs_qgroup_create
3434 int
3435 guestfs_btrfs_qgroup_create (guestfs_h *g,
3436 const char *qgroupid,
3437 const char *subvolume);
3438 Create a quota group (qgroup) for subvolume at "subvolume".
3440 This function returns 0 on success or -1 on error.
3442 This function depends on the feature "btrfs". See also
3444 "guestfs_feature_available".
3445 (Added in 1.29.17)
3447 guestfs_btrfs_qgroup_destroy
3449 int
3450 guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3451 const char *qgroupid,
3452 const char *subvolume);
3453 Destroy a quota group.
3455 This function returns 0 on success or -1 on error.
3457 This function depends on the feature "btrfs". See also
3459 "guestfs_feature_available".
3460 (Added in 1.29.17)
3462 guestfs_btrfs_qgroup_limit
3464 int
3465 guestfs_btrfs_qgroup_limit (guestfs_h *g,
3466 const char *subvolume,
3467 int64_t size);
3468 Limit the size of the subvolume with path "subvolume".
3470 This function returns 0 on success or -1 on error.
3472 This function depends on the feature "btrfs". See also
3474 "guestfs_feature_available".
3475 (Added in 1.29.17)
3477 guestfs_btrfs_qgroup_remove
3479 int
3480 guestfs_btrfs_qgroup_remove (guestfs_h *g,
3481 const char *src,
3482 const char *dst,
3483 const char *path);
3484 Remove qgroup "src" from the parent qgroup "dst".
3486 This function returns 0 on success or -1 on error.
3488 This function depends on the feature "btrfs". See also
3490 "guestfs_feature_available".
3491 (Added in 1.29.17)
3493 guestfs_btrfs_qgroup_show
3495 struct guestfs_btrfsqgroup_list *
3496 guestfs_btrfs_qgroup_show (guestfs_h *g,
3497 const char *path);
3498 Show all subvolume quota groups in a btrfs filesystem, including their
3500 usages.
3501 This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3503 there was an error. The caller must call
3504 "guestfs_free_btrfsqgroup_list" after use.
3505 This function depends on the feature "btrfs". See also
3507 "guestfs_feature_available".
3508 (Added in 1.29.17)
3510 guestfs_btrfs_quota_enable
3512 int
3513 guestfs_btrfs_quota_enable (guestfs_h *g,
3514 const char *fs,
3515 int enable);
3516 Enable or disable subvolume quota support for filesystem which contains
3518 "path".
3519 This function returns 0 on success or -1 on error.
3521 This function depends on the feature "btrfs". See also
3523 "guestfs_feature_available".
3524 (Added in 1.29.17)
3526 guestfs_btrfs_quota_rescan
3528 int
3529 guestfs_btrfs_quota_rescan (guestfs_h *g,
3530 const char *fs);
3531 Trash all qgroup numbers and scan the metadata again with the current
3533 config.
3534 This function returns 0 on success or -1 on error.
3536 This function depends on the feature "btrfs". See also
3538 "guestfs_feature_available".
3539 (Added in 1.29.17)
3541 guestfs_btrfs_replace
3543 int
3544 guestfs_btrfs_replace (guestfs_h *g,
3545 const char *srcdev,
3546 const char *targetdev,
3547 const char *mntpoint);
3548 Replace device of a btrfs filesystem. On a live filesystem, duplicate
3550 the data to the target device which is currently stored on the source
3551 device. After completion of the operation, the source device is wiped
3552 out and removed from the filesystem.
3553 The "targetdev" needs to be same size or larger than the "srcdev".
3555 Devices which are currently mounted are never allowed to be used as the
3556 "targetdev".
3557 This function returns 0 on success or -1 on error.
3559 This function depends on the feature "btrfs". See also
3561 "guestfs_feature_available".
3562 (Added in 1.29.48)
3564 guestfs_btrfs_rescue_chunk_recover
3566 int
3567 guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3568 const char *device);
3569 Recover the chunk tree of btrfs filesystem by scanning the devices one
3571 by one.
3572 This function returns 0 on success or -1 on error.
3574 This function depends on the feature "btrfs". See also
3576 "guestfs_feature_available".
3577 (Added in 1.29.22)
3579 guestfs_btrfs_rescue_super_recover
3581 int
3582 guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3583 const char *device);
3584 Recover bad superblocks from good copies.
3586 This function returns 0 on success or -1 on error.
3588 This function depends on the feature "btrfs". See also
3590 "guestfs_feature_available".
3591 (Added in 1.29.22)
3593 guestfs_btrfs_scrub_cancel
3595 int
3596 guestfs_btrfs_scrub_cancel (guestfs_h *g,
3597 const char *path);
3598 Cancel a running scrub on a btrfs filesystem.
3600 This function returns 0 on success or -1 on error.
3602 This function depends on the feature "btrfs". See also
3604 "guestfs_feature_available".
3605 (Added in 1.29.22)
3607 guestfs_btrfs_scrub_resume
3609 int
3610 guestfs_btrfs_scrub_resume (guestfs_h *g,
3611 const char *path);
3612 Resume a previously canceled or interrupted scrub on a btrfs
3614 filesystem.
3615 This function returns 0 on success or -1 on error.
3617 This function depends on the feature "btrfs". See also
3619 "guestfs_feature_available".
3620 (Added in 1.29.22)
3622 guestfs_btrfs_scrub_start
3624 int
3625 guestfs_btrfs_scrub_start (guestfs_h *g,
3626 const char *path);
3627 Reads all the data and metadata on the filesystem, and uses checksums
3629 and the duplicate copies from RAID storage to identify and repair any
3630 corrupt data.
3631 This function returns 0 on success or -1 on error.
3633 This function depends on the feature "btrfs". See also
3635 "guestfs_feature_available".
3636 (Added in 1.29.22)
3638 guestfs_btrfs_scrub_status
3640 struct guestfs_btrfsscrub *
3641 guestfs_btrfs_scrub_status (guestfs_h *g,
3642 const char *path);
3643 Show status of running or finished scrub on a btrfs filesystem.
3645 This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3647 was an error. The caller must call "guestfs_free_btrfsscrub" after
3648 use.
3649 This function depends on the feature "btrfs". See also
3651 "guestfs_feature_available".
3652 (Added in 1.29.26)
3654 guestfs_btrfs_set_seeding
3656 int
3657 guestfs_btrfs_set_seeding (guestfs_h *g,
3658 const char *device,
3659 int seeding);
3660 Enable or disable the seeding feature of a device that contains a btrfs
3662 filesystem.
3663 This function returns 0 on success or -1 on error.
3665 This function depends on the feature "btrfs". See also
3667 "guestfs_feature_available".
3668 (Added in 1.17.43)
3670 guestfs_btrfs_subvolume_create
3672 int
3673 guestfs_btrfs_subvolume_create (guestfs_h *g,
3674 const char *dest);
3675 This function is provided for backwards compatibility with earlier
3677 versions of libguestfs. It simply calls
3678 "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3679 (Added in 1.17.35)
3681 guestfs_btrfs_subvolume_create_opts
3683 int
3684 guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3685 const char *dest,
3686 ...);
3687 You may supply a list of optional arguments to this call. Use zero or
3689 more of the following pairs of parameters, and terminate the list with
3690 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3691 GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3693 Create a btrfs subvolume. The "dest" argument is the destination
3695 directory and the name of the subvolume, in the form
3696 /path/to/dest/name. The optional parameter "qgroupid" represents the
3697 qgroup which the newly created subvolume will be added to.
3698 This function returns 0 on success or -1 on error.
3700 This function depends on the feature "btrfs". See also
3702 "guestfs_feature_available".
3703 (Added in 1.17.35)
3705 guestfs_btrfs_subvolume_create_opts_va
3707 int
3708 guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3709 const char *dest,
3710 va_list args);
3711 This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3713 See "CALLS WITH OPTIONAL ARGUMENTS".
3715 guestfs_btrfs_subvolume_create_opts_argv
3717 int
3718 guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3719 const char *dest,
3720 const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3721 This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3723 See "CALLS WITH OPTIONAL ARGUMENTS".
3725 guestfs_btrfs_subvolume_delete
3727 int
3728 guestfs_btrfs_subvolume_delete (guestfs_h *g,
3729 const char *subvolume);
3730 Delete the named btrfs subvolume or snapshot.
3732 This function returns 0 on success or -1 on error.
3734 This function depends on the feature "btrfs". See also
3736 "guestfs_feature_available".
3737 (Added in 1.17.35)
3739 guestfs_btrfs_subvolume_get_default
3741 int64_t
3742 guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3743 const char *fs);
3744 Get the default subvolume or snapshot of a filesystem mounted at
3746 "mountpoint".
3747 On error this function returns -1.
3749 This function depends on the feature "btrfs". See also
3751 "guestfs_feature_available".
3752 (Added in 1.29.17)
3754 guestfs_btrfs_subvolume_list
3756 struct guestfs_btrfssubvolume_list *
3757 guestfs_btrfs_subvolume_list (guestfs_h *g,
3758 const char *fs);
3759 List the btrfs snapshots and subvolumes of the btrfs filesystem which
3761 is mounted at "fs".
3762 This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3764 if there was an error. The caller must call
3765 "guestfs_free_btrfssubvolume_list" after use.
3766 This function depends on the feature "btrfs". See also
3768 "guestfs_feature_available".
3769 (Added in 1.17.35)
3771 guestfs_btrfs_subvolume_set_default
3773 int
3774 guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3775 int64_t id,
3776 const char *fs);
3777 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3779 default. See "guestfs_btrfs_subvolume_list" to get a list of
3780 subvolumes.
3781 This function returns 0 on success or -1 on error.
3783 This function depends on the feature "btrfs". See also
3785 "guestfs_feature_available".
3786 (Added in 1.17.35)
3788 guestfs_btrfs_subvolume_show
3790 char **
3791 guestfs_btrfs_subvolume_show (guestfs_h *g,
3792 const char *subvolume);
3793 Return detailed information of the subvolume.
3795 This function returns a NULL-terminated array of strings, or NULL if
3797 there was an error. The array of strings will always have length
3798 "2n+1", where "n" keys and values alternate, followed by the trailing
3799 NULL entry. The caller must free the strings and the array after use.
3800 This function depends on the feature "btrfs". See also
3802 "guestfs_feature_available".
3803 (Added in 1.29.17)
3805 guestfs_btrfs_subvolume_snapshot
3807 int
3808 guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3809 const char *source,
3810 const char *dest);
3811 This function is provided for backwards compatibility with earlier
3813 versions of libguestfs. It simply calls
3814 "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3815 (Added in 1.17.35)
3817 guestfs_btrfs_subvolume_snapshot_opts
3819 int
3820 guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3821 const char *source,
3822 const char *dest,
3823 ...);
3824 You may supply a list of optional arguments to this call. Use zero or
3826 more of the following pairs of parameters, and terminate the list with
3827 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3828 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3830 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3831 Create a snapshot of the btrfs subvolume "source". The "dest" argument
3833 is the destination directory and the name of the snapshot, in the form
3834 /path/to/dest/name. By default the newly created snapshot is writable,
3835 if the value of optional parameter "ro" is true, then a readonly
3836 snapshot is created. The optional parameter "qgroupid" represents the
3837 qgroup which the newly created snapshot will be added to.
3838 This function returns 0 on success or -1 on error.
3840 This function depends on the feature "btrfs". See also
3842 "guestfs_feature_available".
3843 (Added in 1.17.35)
3845 guestfs_btrfs_subvolume_snapshot_opts_va
3847 int
3848 guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
3849 const char *source,
3850 const char *dest,
3851 va_list args);
3852 This is the "va_list variant" of
3854 "guestfs_btrfs_subvolume_snapshot_opts".
3855 See "CALLS WITH OPTIONAL ARGUMENTS".
3857 guestfs_btrfs_subvolume_snapshot_opts_argv
3859 int
3860 guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
3861 const char *source,
3862 const char *dest,
3863 const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
3864 This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
3866 See "CALLS WITH OPTIONAL ARGUMENTS".
3868 guestfs_btrfstune_enable_extended_inode_refs
3870 int
3871 guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
3872 const char *device);
3873 This will Enable extended inode refs.
3875 This function returns 0 on success or -1 on error.
3877 This function depends on the feature "btrfs". See also
3879 "guestfs_feature_available".
3880 (Added in 1.29.29)
3882 guestfs_btrfstune_enable_skinny_metadata_extent_refs
3884 int
3885 guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
3886 const char *device);
3887 This enable skinny metadata extent refs.
3889 This function returns 0 on success or -1 on error.
3891 This function depends on the feature "btrfs". See also
3893 "guestfs_feature_available".
3894 (Added in 1.29.29)
3896 guestfs_btrfstune_seeding
3898 int
3899 guestfs_btrfstune_seeding (guestfs_h *g,
3900 const char *device,
3901 int seeding);
3902 Enable seeding of a btrfs device, this will force a fs readonly so that
3904 you can use it to build other filesystems.
3905 This function returns 0 on success or -1 on error.
3907 This function depends on the feature "btrfs". See also
3909 "guestfs_feature_available".
3910 (Added in 1.29.29)
3912 guestfs_c_pointer
3914 int64_t
3915 guestfs_c_pointer (guestfs_h *g);
3916 In non-C language bindings, this allows you to retrieve the underlying
3918 C pointer to the handle (ie. "guestfs_h *"). The purpose of this is to
3919 allow other libraries to interwork with libguestfs.
3920 On error this function returns -1.
3922 (Added in 1.29.17)
3924 guestfs_canonical_device_name
3926 char *
3927 guestfs_canonical_device_name (guestfs_h *g,
3928 const char *device);
3929 This utility function is useful when displaying device names to the
3931 user. It takes a number of irregular device names and returns them in
3932 a consistent format:
3933 /dev/hdX
3935 /dev/vdX
3936 These are returned as /dev/sdX. Note this works for device names
3937 and partition names. This is approximately the reverse of the
3938 algorithm described in "BLOCK DEVICE NAMING".
3939 /dev/mapper/VG-LV
3941 /dev/dm-N
3942 Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
3943 Other strings are returned unmodified.
3945 This function returns a string, or NULL on error. The caller must free
3947 the returned string after use.
3948 (Added in 1.19.7)
3950 guestfs_cap_get_file
3952 char *
3953 guestfs_cap_get_file (guestfs_h *g,
3954 const char *path);
3955 This function returns the Linux capabilities attached to "path". The
3957 capabilities set is returned in text form (see cap_to_text(3)).
3958 If no capabilities are attached to a file, an empty string is returned.
3960 This function returns a string, or NULL on error. The caller must free
3962 the returned string after use.
3963 This function depends on the feature "linuxcaps". See also
3965 "guestfs_feature_available".
3966 (Added in 1.19.63)
3968 guestfs_cap_set_file
3970 int
3971 guestfs_cap_set_file (guestfs_h *g,
3972 const char *path,
3973 const char *cap);
3974 This function sets the Linux capabilities attached to "path". The
3976 capabilities set "cap" should be passed in text form (see
3977 cap_from_text(3)).
3978 This function returns 0 on success or -1 on error.
3980 This function depends on the feature "linuxcaps". See also
3982 "guestfs_feature_available".
3983 (Added in 1.19.63)
3985 guestfs_case_sensitive_path
3987 char *
3988 guestfs_case_sensitive_path (guestfs_h *g,
3989 const char *path);
3990 This can be used to resolve case insensitive paths on a filesystem
3992 which is case sensitive. The use case is to resolve paths which you
3993 have read from Windows configuration files or the Windows Registry, to
3994 the true path.
3995 The command handles a peculiarity of the Linux ntfs-3g filesystem
3997 driver (and probably others), which is that although the underlying
3998 filesystem is case-insensitive, the driver exports the filesystem to
3999 Linux as case-sensitive.
4000 One consequence of this is that special directories such as C:\windows
4002 may appear as /WINDOWS or /windows (or other things) depending on the
4003 precise details of how they were created. In Windows itself this would
4004 not be a problem.
4005 Bug or feature? You decide:
4007 https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4008 "guestfs_case_sensitive_path" attempts to resolve the true case of each
4010 element in the path. It will return a resolved path if either the full
4011 path or its parent directory exists. If the parent directory exists but
4012 the full path does not, the case of the parent directory will be
4013 correctly resolved, and the remainder appended unmodified. For example,
4014 if the file "/Windows/System32/netkvm.sys" exists:
4015 "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4017 "Windows/System32/netkvm.sys"
4018 "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4020 "Windows/System32/NoSuchFile"
4021 "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4023 ERROR
4024 Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4026 cannot be used to check for the existence of a file.
4027 Note: This function does not handle drive names, backslashes etc.
4029 See also "guestfs_realpath".
4031 This function returns a string, or NULL on error. The caller must free
4033 the returned string after use.
4034 (Added in 1.0.75)
4036 guestfs_cat
4038 char *
4039 guestfs_cat (guestfs_h *g,
4040 const char *path);
4041 Return the contents of the file named "path".
4043 Because, in C, this function returns a "char *", there is no way to
4045 differentiate between a "\0" character in a file and end of string. To
4046 handle binary files, use the "guestfs_read_file" or "guestfs_download"
4047 functions.
4048 This function returns a string, or NULL on error. The caller must free
4050 the returned string after use.
4051 (Added in 0.4)
4053 guestfs_checksum
4055 char *
4056 guestfs_checksum (guestfs_h *g,
4057 const char *csumtype,
4058 const char *path);
4059 This call computes the MD5, SHAx or CRC checksum of the file named
4061 "path".
4062 The type of checksum to compute is given by the "csumtype" parameter
4064 which must have one of the following values:
4065 "crc"
4067 Compute the cyclic redundancy check (CRC) specified by POSIX for
4068 the "cksum" command.
4069 "md5"
4071 Compute the MD5 hash (using the md5sum(1) program).
4072 "sha1"
4074 Compute the SHA1 hash (using the sha1sum(1) program).
4075 "sha224"
4077 Compute the SHA224 hash (using the sha224sum(1) program).
4078 "sha256"
4080 Compute the SHA256 hash (using the sha256sum(1) program).
4081 "sha384"
4083 Compute the SHA384 hash (using the sha384sum(1) program).
4084 "sha512"
4086 Compute the SHA512 hash (using the sha512sum(1) program).
4087 The checksum is returned as a printable string.
4089 To get the checksum for a device, use "guestfs_checksum_device".
4091 To get the checksums for many files, use "guestfs_checksums_out".
4093 This function returns a string, or NULL on error. The caller must free
4095 the returned string after use.
4096 (Added in 1.0.2)
4098 guestfs_checksum_device
4100 char *
4101 guestfs_checksum_device (guestfs_h *g,
4102 const char *csumtype,
4103 const char *device);
4104 This call computes the MD5, SHAx or CRC checksum of the contents of the
4106 device named "device". For the types of checksums supported see the
4107 "guestfs_checksum" command.
4108 This function returns a string, or NULL on error. The caller must free
4110 the returned string after use.
4111 (Added in 1.3.2)
4113 guestfs_checksums_out
4115 int
4116 guestfs_checksums_out (guestfs_h *g,
4117 const char *csumtype,
4118 const char *directory,
4119 const char *sumsfile);
4120 This command computes the checksums of all regular files in directory
4122 and then emits a list of those checksums to the local output file
4123 "sumsfile".
4124 This can be used for verifying the integrity of a virtual machine.
4126 However to be properly secure you should pay attention to the output of
4127 the checksum command (it uses the ones from GNU coreutils). In
4128 particular when the filename is not printable, coreutils uses a special
4129 backslash syntax. For more information, see the GNU coreutils info
4130 file.
4131 This function returns 0 on success or -1 on error.
4133 (Added in 1.3.7)
4135 guestfs_chmod
4137 int
4138 guestfs_chmod (guestfs_h *g,
4139 int mode,
4140 const char *path);
4141 Change the mode (permissions) of "path" to "mode". Only numeric modes
4143 are supported.
4144 Note: When using this command from guestfish, "mode" by default would
4146 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4147 700.
4148 The mode actually set is affected by the umask.
4150 This function returns 0 on success or -1 on error.
4152 (Added in 0.8)
4154 guestfs_chown
4156 int
4157 guestfs_chown (guestfs_h *g,
4158 int owner,
4159 int group,
4160 const char *path);
4161 Change the file owner to "owner" and group to "group".
4163 Only numeric uid and gid are supported. If you want to use names, you
4165 will need to locate and parse the password file yourself (Augeas
4166 support makes this relatively easy).
4167 This function returns 0 on success or -1 on error.
4169 (Added in 0.8)
4171 guestfs_clear_backend_setting
4173 int
4174 guestfs_clear_backend_setting (guestfs_h *g,
4175 const char *name);
4176 If there is a backend setting string matching "name" or beginning with
4178 "name=", then that string is removed from the backend settings.
4179 This call returns the number of strings which were removed (which may
4181 be 0, 1 or greater than 1).
4182 See "BACKEND", "BACKEND SETTINGS".
4184 On error this function returns -1.
4186 (Added in 1.27.2)
4188 guestfs_command
4190 char *
4191 guestfs_command (guestfs_h *g,
4192 char *const *arguments);
4193 This call runs a command from the guest filesystem. The filesystem
4195 must be mounted, and must contain a compatible operating system (ie.
4196 something Linux, with the same or compatible processor architecture).
4197 The single parameter is an argv-style list of arguments. The first
4199 element is the name of the program to run. Subsequent elements are
4200 parameters. The list must be non-empty (ie. must contain a program
4201 name). Note that the command runs directly, and is not invoked via the
4202 shell (see "guestfs_sh").
4203 The return value is anything printed to stdout by the command.
4205 If the command returns a non-zero exit status, then this function
4207 returns an error message. The error message string is the content of
4208 stderr from the command.
4209 The $PATH environment variable will contain at least /usr/bin and /bin.
4211 If you require a program from another location, you should provide the
4212 full path in the first parameter.
4213 Shared libraries and data files required by the program must be
4215 available on filesystems which are mounted in the correct places. It
4216 is the caller’s responsibility to ensure all filesystems that are
4217 needed are mounted at the right locations.
4218 This function returns a string, or NULL on error. The caller must free
4220 the returned string after use.
4221 Because of the message protocol, there is a transfer limit of somewhere
4223 between 2MB and 4MB. See "PROTOCOL LIMITS".
4224 (Added in 1.9.1)
4226 guestfs_command_lines
4228 char **
4229 guestfs_command_lines (guestfs_h *g,
4230 char *const *arguments);
4231 This is the same as "guestfs_command", but splits the result into a
4233 list of lines.
4234 See also: "guestfs_sh_lines"
4236 This function returns a NULL-terminated array of strings (like
4238 environ(3)), or NULL if there was an error. The caller must free the
4239 strings and the array after use.
4240 Because of the message protocol, there is a transfer limit of somewhere
4242 between 2MB and 4MB. See "PROTOCOL LIMITS".
4243 (Added in 1.9.1)
4245 guestfs_compress_device_out
4247 int
4248 guestfs_compress_device_out (guestfs_h *g,
4249 const char *ctype,
4250 const char *device,
4251 const char *zdevice,
4252 ...);
4253 You may supply a list of optional arguments to this call. Use zero or
4255 more of the following pairs of parameters, and terminate the list with
4256 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4257 GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4259 This command compresses "device" and writes it out to the local file
4261 "zdevice".
4262 The "ctype" and optional "level" parameters have the same meaning as in
4264 "guestfs_compress_out".
4265 This function returns 0 on success or -1 on error.
4267 (Added in 1.13.15)
4269 guestfs_compress_device_out_va
4271 int
4272 guestfs_compress_device_out_va (guestfs_h *g,
4273 const char *ctype,
4274 const char *device,
4275 const char *zdevice,
4276 va_list args);
4277 This is the "va_list variant" of "guestfs_compress_device_out".
4279 See "CALLS WITH OPTIONAL ARGUMENTS".
4281 guestfs_compress_device_out_argv
4283 int
4284 guestfs_compress_device_out_argv (guestfs_h *g,
4285 const char *ctype,
4286 const char *device,
4287 const char *zdevice,
4288 const struct guestfs_compress_device_out_argv *optargs);
4289 This is the "argv variant" of "guestfs_compress_device_out".
4291 See "CALLS WITH OPTIONAL ARGUMENTS".
4293 guestfs_compress_out
4295 int
4296 guestfs_compress_out (guestfs_h *g,
4297 const char *ctype,
4298 const char *file,
4299 const char *zfile,
4300 ...);
4301 You may supply a list of optional arguments to this call. Use zero or
4303 more of the following pairs of parameters, and terminate the list with
4304 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4305 GUESTFS_COMPRESS_OUT_LEVEL, int level,
4307 This command compresses file and writes it out to the local file zfile.
4309 The compression program used is controlled by the "ctype" parameter.
4311 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4312 Some compression types may not be supported by particular builds of
4313 libguestfs, in which case you will get an error containing the
4314 substring "not supported".
4315 The optional "level" parameter controls compression level. The meaning
4317 and default for this parameter depends on the compression program being
4318 used.
4319 This function returns 0 on success or -1 on error.
4321 (Added in 1.13.15)
4323 guestfs_compress_out_va
4325 int
4326 guestfs_compress_out_va (guestfs_h *g,
4327 const char *ctype,
4328 const char *file,
4329 const char *zfile,
4330 va_list args);
4331 This is the "va_list variant" of "guestfs_compress_out".
4333 See "CALLS WITH OPTIONAL ARGUMENTS".
4335 guestfs_compress_out_argv
4337 int
4338 guestfs_compress_out_argv (guestfs_h *g,
4339 const char *ctype,
4340 const char *file,
4341 const char *zfile,
4342 const struct guestfs_compress_out_argv *optargs);
4343 This is the "argv variant" of "guestfs_compress_out".
4345 See "CALLS WITH OPTIONAL ARGUMENTS".
4347 guestfs_config
4349 int
4350 guestfs_config (guestfs_h *g,
4351 const char *hvparam,
4352 const char *hvvalue);
4353 This can be used to add arbitrary hypervisor parameters of the form
4355 -param value. Actually it’s not quite arbitrary - we prevent you from
4356 setting some parameters which would interfere with parameters that we
4357 use.
4358 The first character of "hvparam" string must be a "-" (dash).
4360 "hvvalue" can be NULL.
4362 This function returns 0 on success or -1 on error.
4364 (Added in 0.3)
4366 guestfs_copy_attributes
4368 int
4369 guestfs_copy_attributes (guestfs_h *g,
4370 const char *src,
4371 const char *dest,
4372 ...);
4373 You may supply a list of optional arguments to this call. Use zero or
4375 more of the following pairs of parameters, and terminate the list with
4376 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4377 GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4379 GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4380 GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4381 GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4382 Copy the attributes of a path (which can be a file or a directory) to
4384 another path.
4385 By default no attribute is copied, so make sure to specify any (or
4387 "all" to copy everything).
4388 The optional arguments specify which attributes can be copied:
4390 "mode"
4392 Copy part of the file mode from "source" to "destination". Only the
4393 UNIX permissions and the sticky/setuid/setgid bits can be copied.
4394 "xattributes"
4396 Copy the Linux extended attributes (xattrs) from "source" to
4397 "destination". This flag does nothing if the linuxxattrs feature
4398 is not available (see "guestfs_feature_available").
4399 "ownership"
4401 Copy the owner uid and the group gid of "source" to "destination".
4402 "all"
4404 Copy all the attributes from "source" to "destination". Enabling it
4405 enables all the other flags, if they are not specified already.
4406 This function returns 0 on success or -1 on error.
4408 (Added in 1.25.21)
4410 guestfs_copy_attributes_va
4412 int
4413 guestfs_copy_attributes_va (guestfs_h *g,
4414 const char *src,
4415 const char *dest,
4416 va_list args);
4417 This is the "va_list variant" of "guestfs_copy_attributes".
4419 See "CALLS WITH OPTIONAL ARGUMENTS".
4421 guestfs_copy_attributes_argv
4423 int
4424 guestfs_copy_attributes_argv (guestfs_h *g,
4425 const char *src,
4426 const char *dest,
4427 const struct guestfs_copy_attributes_argv *optargs);
4428 This is the "argv variant" of "guestfs_copy_attributes".
4430 See "CALLS WITH OPTIONAL ARGUMENTS".
4432 guestfs_copy_device_to_device
4434 int
4435 guestfs_copy_device_to_device (guestfs_h *g,
4436 const char *src,
4437 const char *dest,
4438 ...);
4439 You may supply a list of optional arguments to this call. Use zero or
4441 more of the following pairs of parameters, and terminate the list with
4442 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4443 GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4445 GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4446 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4447 GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4448 GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4449 The four calls "guestfs_copy_device_to_device",
4451 "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4452 "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4453 a destination (device|file).
4454 Partial copies can be made since you can specify optionally the source
4456 offset, destination offset and size to copy. These values are all
4457 specified in bytes. If not given, the offsets both default to zero,
4458 and the size defaults to copying as much as possible until we hit the
4459 end of the source.
4460 The source and destination may be the same object. However overlapping
4462 regions may not be copied correctly.
4463 If the destination is a file, it is created if required. If the
4465 destination file is not large enough, it is extended.
4466 If the destination is a file and the "append" flag is not set, then the
4468 destination file is truncated. If the "append" flag is set, then the
4469 copy appends to the destination file. The "append" flag currently
4470 cannot be set for devices.
4471 If the "sparse" flag is true then the call avoids writing blocks that
4473 contain only zeroes, which can help in some situations where the
4474 backing disk is thin-provisioned. Note that unless the target is
4475 already zeroed, using this option will result in incorrect copying.
4476 This function returns 0 on success or -1 on error.
4478 This long-running command can generate progress notification messages
4480 so that the caller can display a progress bar or indicator. To receive
4481 these messages, the caller must register a progress event callback.
4482 See "GUESTFS_EVENT_PROGRESS".
4483 (Added in 1.13.25)
4485 guestfs_copy_device_to_device_va
4487 int
4488 guestfs_copy_device_to_device_va (guestfs_h *g,
4489 const char *src,
4490 const char *dest,
4491 va_list args);
4492 This is the "va_list variant" of "guestfs_copy_device_to_device".
4494 See "CALLS WITH OPTIONAL ARGUMENTS".
4496 guestfs_copy_device_to_device_argv
4498 int
4499 guestfs_copy_device_to_device_argv (guestfs_h *g,
4500 const char *src,
4501 const char *dest,
4502 const struct guestfs_copy_device_to_device_argv *optargs);
4503 This is the "argv variant" of "guestfs_copy_device_to_device".
4505 See "CALLS WITH OPTIONAL ARGUMENTS".
4507 guestfs_copy_device_to_file
4509 int
4510 guestfs_copy_device_to_file (guestfs_h *g,
4511 const char *src,
4512 const char *dest,
4513 ...);
4514 You may supply a list of optional arguments to this call. Use zero or
4516 more of the following pairs of parameters, and terminate the list with
4517 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4518 GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4520 GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4521 GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4522 GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4523 GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4524 See "guestfs_copy_device_to_device" for a general overview of this
4526 call.
4527 This function returns 0 on success or -1 on error.
4529 This long-running command can generate progress notification messages
4531 so that the caller can display a progress bar or indicator. To receive
4532 these messages, the caller must register a progress event callback.
4533 See "GUESTFS_EVENT_PROGRESS".
4534 (Added in 1.13.25)
4536 guestfs_copy_device_to_file_va
4538 int
4539 guestfs_copy_device_to_file_va (guestfs_h *g,
4540 const char *src,
4541 const char *dest,
4542 va_list args);
4543 This is the "va_list variant" of "guestfs_copy_device_to_file".
4545 See "CALLS WITH OPTIONAL ARGUMENTS".
4547 guestfs_copy_device_to_file_argv
4549 int
4550 guestfs_copy_device_to_file_argv (guestfs_h *g,
4551 const char *src,
4552 const char *dest,
4553 const struct guestfs_copy_device_to_file_argv *optargs);
4554 This is the "argv variant" of "guestfs_copy_device_to_file".
4556 See "CALLS WITH OPTIONAL ARGUMENTS".
4558 guestfs_copy_file_to_device
4560 int
4561 guestfs_copy_file_to_device (guestfs_h *g,
4562 const char *src,
4563 const char *dest,
4564 ...);
4565 You may supply a list of optional arguments to this call. Use zero or
4567 more of the following pairs of parameters, and terminate the list with
4568 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4569 GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4571 GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4572 GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4573 GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4574 GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4575 See "guestfs_copy_device_to_device" for a general overview of this
4577 call.
4578 This function returns 0 on success or -1 on error.
4580 This long-running command can generate progress notification messages
4582 so that the caller can display a progress bar or indicator. To receive
4583 these messages, the caller must register a progress event callback.
4584 See "GUESTFS_EVENT_PROGRESS".
4585 (Added in 1.13.25)
4587 guestfs_copy_file_to_device_va
4589 int
4590 guestfs_copy_file_to_device_va (guestfs_h *g,
4591 const char *src,
4592 const char *dest,
4593 va_list args);
4594 This is the "va_list variant" of "guestfs_copy_file_to_device".
4596 See "CALLS WITH OPTIONAL ARGUMENTS".
4598 guestfs_copy_file_to_device_argv
4600 int
4601 guestfs_copy_file_to_device_argv (guestfs_h *g,
4602 const char *src,
4603 const char *dest,
4604 const struct guestfs_copy_file_to_device_argv *optargs);
4605 This is the "argv variant" of "guestfs_copy_file_to_device".
4607 See "CALLS WITH OPTIONAL ARGUMENTS".
4609 guestfs_copy_file_to_file
4611 int
4612 guestfs_copy_file_to_file (guestfs_h *g,
4613 const char *src,
4614 const char *dest,
4615 ...);
4616 You may supply a list of optional arguments to this call. Use zero or
4618 more of the following pairs of parameters, and terminate the list with
4619 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4620 GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4622 GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4623 GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4624 GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4625 GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4626 See "guestfs_copy_device_to_device" for a general overview of this
4628 call.
4629 This is not the function you want for copying files. This is for
4631 copying blocks within existing files. See "guestfs_cp", "guestfs_cp_a"
4632 and "guestfs_mv" for general file copying and moving functions.
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_file_va
4644 int
4645 guestfs_copy_file_to_file_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_file".
4651 See "CALLS WITH OPTIONAL ARGUMENTS".
4653 guestfs_copy_file_to_file_argv
4655 int
4656 guestfs_copy_file_to_file_argv (guestfs_h *g,
4657 const char *src,
4658 const char *dest,
4659 const struct guestfs_copy_file_to_file_argv *optargs);
4660 This is the "argv variant" of "guestfs_copy_file_to_file".
4662 See "CALLS WITH OPTIONAL ARGUMENTS".
4664 guestfs_copy_in
4666 int
4667 guestfs_copy_in (guestfs_h *g,
4668 const char *localpath,
4669 const char *remotedir);
4670 "guestfs_copy_in" copies local files or directories recursively into
4672 the disk image, placing them in the directory called "remotedir" (which
4673 must exist).
4674 Wildcards cannot be used.
4676 This function returns 0 on success or -1 on error.
4678 (Added in 1.29.24)
4680 guestfs_copy_out
4682 int
4683 guestfs_copy_out (guestfs_h *g,
4684 const char *remotepath,
4685 const char *localdir);
4686 "guestfs_copy_out" copies remote files or directories recursively out
4688 of the disk image, placing them on the host disk in a local directory
4689 called "localdir" (which must exist).
4690 To download to the current directory, use "." as in:
4692 C<guestfs_copy_out> /home .
4694 Wildcards cannot be used.
4696 This function returns 0 on success or -1 on error.
4698 (Added in 1.29.24)
4700 guestfs_copy_size
4702 int
4703 guestfs_copy_size (guestfs_h *g,
4704 const char *src,
4705 const char *dest,
4706 int64_t size);
4707 This function is deprecated. In new code, use the
4709 "guestfs_copy_device_to_device" call instead.
4710 Deprecated functions will not be removed from the API, but the fact
4712 that they are deprecated indicates that there are problems with correct
4713 use of these functions.
4714 This command copies exactly "size" bytes from one source device or file
4716 "src" to another destination device or file "dest".
4717 Note this will fail if the source is too short or if the destination is
4719 not large enough.
4720 This function returns 0 on success or -1 on error.
4722 This long-running command can generate progress notification messages
4724 so that the caller can display a progress bar or indicator. To receive
4725 these messages, the caller must register a progress event callback.
4726 See "GUESTFS_EVENT_PROGRESS".
4727 (Added in 1.0.87)
4729 guestfs_cp
4731 int
4732 guestfs_cp (guestfs_h *g,
4733 const char *src,
4734 const char *dest);
4735 This copies a file from "src" to "dest" where "dest" is either a
4737 destination filename or destination directory.
4738 This function returns 0 on success or -1 on error.
4740 (Added in 1.0.18)
4742 guestfs_cp_a
4744 int
4745 guestfs_cp_a (guestfs_h *g,
4746 const char *src,
4747 const char *dest);
4748 This copies a file or directory from "src" to "dest" recursively using
4750 the "cp -a" command.
4751 This function returns 0 on success or -1 on error.
4753 (Added in 1.0.18)
4755 guestfs_cp_r
4757 int
4758 guestfs_cp_r (guestfs_h *g,
4759 const char *src,
4760 const char *dest);
4761 This copies a file or directory from "src" to "dest" recursively using
4763 the "cp -rP" command.
4764 Most users should use "guestfs_cp_a" instead. This command is useful
4766 when you don't want to preserve permissions, because the target
4767 filesystem does not support it (primarily when writing to DOS FAT
4768 filesystems).
4769 This function returns 0 on success or -1 on error.
4771 (Added in 1.21.38)
4773 guestfs_cpio_out
4775 int
4776 guestfs_cpio_out (guestfs_h *g,
4777 const char *directory,
4778 const char *cpiofile,
4779 ...);
4780 You may supply a list of optional arguments to this call. Use zero or
4782 more of the following pairs of parameters, and terminate the list with
4783 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4784 GUESTFS_CPIO_OUT_FORMAT, const char *format,
4786 This command packs the contents of directory and downloads it to local
4788 file "cpiofile".
4789 The optional "format" parameter can be used to select the format. Only
4791 the following formats are currently permitted:
4792 "newc"
4794 New (SVR4) portable format. This format happens to be compatible
4795 with the cpio-like format used by the Linux kernel for initramfs.
4796 This is the default format.
4798 "crc"
4800 New (SVR4) portable format with a checksum.
4801 This function returns 0 on success or -1 on error.
4803 (Added in 1.27.9)
4805 guestfs_cpio_out_va
4807 int
4808 guestfs_cpio_out_va (guestfs_h *g,
4809 const char *directory,
4810 const char *cpiofile,
4811 va_list args);
4812 This is the "va_list variant" of "guestfs_cpio_out".
4814 See "CALLS WITH OPTIONAL ARGUMENTS".
4816 guestfs_cpio_out_argv
4818 int
4819 guestfs_cpio_out_argv (guestfs_h *g,
4820 const char *directory,
4821 const char *cpiofile,
4822 const struct guestfs_cpio_out_argv *optargs);
4823 This is the "argv variant" of "guestfs_cpio_out".
4825 See "CALLS WITH OPTIONAL ARGUMENTS".
4827 guestfs_cryptsetup_close
4829 int
4830 guestfs_cryptsetup_close (guestfs_h *g,
4831 const char *device);
4832 This closes an encrypted device that was created earlier by
4834 "guestfs_cryptsetup_open". The "device" parameter must be the name of
4835 the mapping device (ie. /dev/mapper/mapname) and not the name of the
4836 underlying block device.
4837 This function returns 0 on success or -1 on error.
4839 This function depends on the feature "luks". See also
4841 "guestfs_feature_available".
4842 (Added in 1.43.2)
4844 guestfs_cryptsetup_open
4846 int
4847 guestfs_cryptsetup_open (guestfs_h *g,
4848 const char *device,
4849 const char *key,
4850 const char *mapname,
4851 ...);
4852 You may supply a list of optional arguments to this call. Use zero or
4854 more of the following pairs of parameters, and terminate the list with
4855 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4856 GUESTFS_CRYPTSETUP_OPEN_READONLY, int readonly,
4858 GUESTFS_CRYPTSETUP_OPEN_CRYPTTYPE, const char *crypttype,
4859 This command opens a block device which has been encrypted according to
4861 the Linux Unified Key Setup (LUKS) standard, Windows BitLocker, or some
4862 other types.
4863 "device" is the encrypted block device or partition.
4865 The caller must supply one of the keys associated with the encrypted
4867 block device, in the "key" parameter.
4868 This creates a new block device called /dev/mapper/mapname. Reads and
4870 writes to this block device are decrypted from and encrypted to the
4871 underlying "device" respectively.
4872 "mapname" cannot be "control" because that name is reserved by device-
4874 mapper.
4875 If the optional "crypttype" parameter is not present then libguestfs
4877 tries to guess the correct type (for example LUKS or BitLocker).
4878 However you can override this by specifying one of the following types:
4879 "luks"
4881 A Linux LUKS device.
4882 "bitlk"
4884 A Windows BitLocker device.
4885 The optional "readonly" flag, if set to true, creates a read-only
4887 mapping.
4888 If this block device contains LVM volume groups, then calling
4890 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
4891 visible.
4892 Use "guestfs_list_dm_devices" to list all device mapper devices.
4894 This function returns 0 on success or -1 on error.
4896 This function takes a key or passphrase parameter which could contain
4898 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
4899 information.
4900 This function depends on the feature "luks". See also
4902 "guestfs_feature_available".
4903 (Added in 1.43.2)
4905 guestfs_cryptsetup_open_va
4907 int
4908 guestfs_cryptsetup_open_va (guestfs_h *g,
4909 const char *device,
4910 const char *key,
4911 const char *mapname,
4912 va_list args);
4913 This is the "va_list variant" of "guestfs_cryptsetup_open".
4915 See "CALLS WITH OPTIONAL ARGUMENTS".
4917 guestfs_cryptsetup_open_argv
4919 int
4920 guestfs_cryptsetup_open_argv (guestfs_h *g,
4921 const char *device,
4922 const char *key,
4923 const char *mapname,
4924 const struct guestfs_cryptsetup_open_argv *optargs);
4925 This is the "argv variant" of "guestfs_cryptsetup_open".
4927 See "CALLS WITH OPTIONAL ARGUMENTS".
4929 guestfs_dd
4931 int
4932 guestfs_dd (guestfs_h *g,
4933 const char *src,
4934 const char *dest);
4935 This function is deprecated. In new code, use the
4937 "guestfs_copy_device_to_device" call instead.
4938 Deprecated functions will not be removed from the API, but the fact
4940 that they are deprecated indicates that there are problems with correct
4941 use of these functions.
4942 This command copies from one source device or file "src" to another
4944 destination device or file "dest". Normally you would use this to copy
4945 to or from a device or partition, for example to duplicate a
4946 filesystem.
4947 If the destination is a device, it must be as large or larger than the
4949 source file or device, otherwise the copy will fail. This command
4950 cannot do partial copies (see "guestfs_copy_device_to_device").
4951 This function returns 0 on success or -1 on error.
4953 (Added in 1.0.80)
4955 guestfs_device_index
4957 int
4958 guestfs_device_index (guestfs_h *g,
4959 const char *device);
4960 This function takes a device name (eg. "/dev/sdb") and returns the
4962 index of the device in the list of devices.
4963 Index numbers start from 0. The named device must exist, for example
4965 as a string returned from "guestfs_list_devices".
4966 See also "guestfs_list_devices", "guestfs_part_to_dev".
4968 On error this function returns -1.
4970 (Added in 1.19.7)
4972 guestfs_df
4974 char *
4975 guestfs_df (guestfs_h *g);
4976 This command runs the df(1) command to report disk space used.
4978 This command is mostly useful for interactive sessions. It is not
4980 intended that you try to parse the output string. Use
4981 "guestfs_statvfs" from programs.
4982 This function returns a string, or NULL on error. The caller must free
4984 the returned string after use.
4985 (Added in 1.0.54)
4987 guestfs_df_h
4989 char *
4990 guestfs_df_h (guestfs_h *g);
4991 This command runs the "df -h" command to report disk space used in
4993 human-readable format.
4994 This command is mostly useful for interactive sessions. It is not
4996 intended that you try to parse the output string. Use
4997 "guestfs_statvfs" from programs.
4998 This function returns a string, or NULL on error. The caller must free
5000 the returned string after use.
5001 (Added in 1.0.54)
5003 guestfs_disk_create
5005 int
5006 guestfs_disk_create (guestfs_h *g,
5007 const char *filename,
5008 const char *format,
5009 int64_t size,
5010 ...);
5011 You may supply a list of optional arguments to this call. Use zero or
5013 more of the following pairs of parameters, and terminate the list with
5014 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5015 GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
5017 GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
5018 GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
5019 GUESTFS_DISK_CREATE_COMPAT, const char *compat,
5020 GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
5021 Create a blank disk image called filename (a host file) with format
5023 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
5024 If used with the optional "backingfile" parameter, then a snapshot is
5026 created on top of the backing file. In this case, "size" must be
5027 passed as "-1". The size of the snapshot is the same as the size of
5028 the backing file, which is discovered automatically. You are
5029 encouraged to also pass "backingformat" to describe the format of
5030 "backingfile".
5031 If filename refers to a block device, then the device is formatted.
5033 The "size" is ignored since block devices have an intrinsic size.
5034 The other optional parameters are:
5036 "preallocation"
5038 If format is "raw", then this can be either "off" (or "sparse") or
5039 "full" to create a sparse or fully allocated file respectively.
5040 The default is "off".
5041 If format is "qcow2", then this can be "off" (or "sparse"),
5043 "metadata" or "full". Preallocating metadata can be faster when
5044 doing lots of writes, but uses more space. The default is "off".
5045 "compat"
5047 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5048 supported by qemu ≥ 1.1.
5049 "clustersize"
5051 "qcow2" only: Change the qcow2 cluster size. The default is 65536
5052 (bytes) and this setting may be any power of two between 512 and
5053 2097152.
5054 Note that this call does not add the new disk to the handle. You may
5056 need to call "guestfs_add_drive_opts" separately.
5057 This function returns 0 on success or -1 on error.
5059 (Added in 1.25.31)
5061 guestfs_disk_create_va
5063 int
5064 guestfs_disk_create_va (guestfs_h *g,
5065 const char *filename,
5066 const char *format,
5067 int64_t size,
5068 va_list args);
5069 This is the "va_list variant" of "guestfs_disk_create".
5071 See "CALLS WITH OPTIONAL ARGUMENTS".
5073 guestfs_disk_create_argv
5075 int
5076 guestfs_disk_create_argv (guestfs_h *g,
5077 const char *filename,
5078 const char *format,
5079 int64_t size,
5080 const struct guestfs_disk_create_argv *optargs);
5081 This is the "argv variant" of "guestfs_disk_create".
5083 See "CALLS WITH OPTIONAL ARGUMENTS".
5085 guestfs_disk_format
5087 char *
5088 guestfs_disk_format (guestfs_h *g,
5089 const char *filename);
5090 Detect and return the format of the disk image called filename.
5092 filename can also be a host device, etc. If the format of the image
5093 could not be detected, then "unknown" is returned.
5094 Note that detecting the disk format can be insecure under some
5096 circumstances. See "CVE-2010-3851".
5097 See also: "DISK IMAGE FORMATS"
5099 This function returns a string, or NULL on error. The caller must free
5101 the returned string after use.
5102 (Added in 1.19.38)
5104 guestfs_disk_has_backing_file
5106 int
5107 guestfs_disk_has_backing_file (guestfs_h *g,
5108 const char *filename);
5109 Detect and return whether the disk image filename has a backing file.
5111 Note that detecting disk features can be insecure under some
5113 circumstances. See "CVE-2010-3851".
5114 This function returns a C truth value on success or -1 on error.
5116 (Added in 1.19.39)
5118 guestfs_disk_virtual_size
5120 int64_t
5121 guestfs_disk_virtual_size (guestfs_h *g,
5122 const char *filename);
5123 Detect and return the virtual size in bytes of the disk image called
5125 filename.
5126 Note that detecting disk features can be insecure under some
5128 circumstances. See "CVE-2010-3851".
5129 On error this function returns -1.
5131 (Added in 1.19.39)
5133 guestfs_dmesg
5135 char *
5136 guestfs_dmesg (guestfs_h *g);
5137 This returns the kernel messages (dmesg(1) output) from the guest
5139 kernel. This is sometimes useful for extended debugging of problems.
5140 Another way to get the same information is to enable verbose messages
5142 with "guestfs_set_verbose" or by setting the environment variable
5143 "LIBGUESTFS_DEBUG=1" before running the program.
5144 This function returns a string, or NULL on error. The caller must free
5146 the returned string after use.
5147 (Added in 1.0.18)
5149 guestfs_download
5151 int
5152 guestfs_download (guestfs_h *g,
5153 const char *remotefilename,
5154 const char *filename);
5155 Download file remotefilename and save it as filename on the local
5157 machine.
5158 filename can also be a named pipe.
5160 See also "guestfs_upload", "guestfs_cat".
5162 This function returns 0 on success or -1 on error.
5164 This long-running command can generate progress notification messages
5166 so that the caller can display a progress bar or indicator. To receive
5167 these messages, the caller must register a progress event callback.
5168 See "GUESTFS_EVENT_PROGRESS".
5169 (Added in 1.0.2)
5171 guestfs_download_blocks
5173 int
5174 guestfs_download_blocks (guestfs_h *g,
5175 const char *device,
5176 int64_t start,
5177 int64_t stop,
5178 const char *filename,
5179 ...);
5180 You may supply a list of optional arguments to this call. Use zero or
5182 more of the following pairs of parameters, and terminate the list with
5183 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5184 GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5186 Download the data units from start address to stop from the disk
5188 partition (eg. /dev/sda1) and save them as filename on the local
5189 machine.
5190 The use of this API on sparse disk image formats such as QCOW, may
5192 result in large zero-filled files downloaded on the host.
5193 The size of a data unit varies across filesystem implementations. On
5195 NTFS filesystems data units are referred as clusters while on ExtX ones
5196 they are referred as fragments.
5197 If the optional "unallocated" flag is true (default is false), only the
5199 unallocated blocks will be extracted. This is useful to detect hidden
5200 data or to retrieve deleted files which data units have not been
5201 overwritten yet.
5202 This function returns 0 on success or -1 on error.
5204 This long-running command can generate progress notification messages
5206 so that the caller can display a progress bar or indicator. To receive
5207 these messages, the caller must register a progress event callback.
5208 See "GUESTFS_EVENT_PROGRESS".
5209 This function depends on the feature "sleuthkit". See also
5211 "guestfs_feature_available".
5212 (Added in 1.33.45)
5214 guestfs_download_blocks_va
5216 int
5217 guestfs_download_blocks_va (guestfs_h *g,
5218 const char *device,
5219 int64_t start,
5220 int64_t stop,
5221 const char *filename,
5222 va_list args);
5223 This is the "va_list variant" of "guestfs_download_blocks".
5225 See "CALLS WITH OPTIONAL ARGUMENTS".
5227 guestfs_download_blocks_argv
5229 int
5230 guestfs_download_blocks_argv (guestfs_h *g,
5231 const char *device,
5232 int64_t start,
5233 int64_t stop,
5234 const char *filename,
5235 const struct guestfs_download_blocks_argv *optargs);
5236 This is the "argv variant" of "guestfs_download_blocks".
5238 See "CALLS WITH OPTIONAL ARGUMENTS".
5240 guestfs_download_inode
5242 int
5243 guestfs_download_inode (guestfs_h *g,
5244 const char *device,
5245 int64_t inode,
5246 const char *filename);
5247 Download a file given its inode from the disk partition (eg. /dev/sda1)
5249 and save it as filename on the local machine.
5250 It is not required to mount the disk to run this command.
5252 The command is capable of downloading deleted or inaccessible files.
5254 This function returns 0 on success or -1 on error.
5256 This long-running command can generate progress notification messages
5258 so that the caller can display a progress bar or indicator. To receive
5259 these messages, the caller must register a progress event callback.
5260 See "GUESTFS_EVENT_PROGRESS".
5261 This function depends on the feature "sleuthkit". See also
5263 "guestfs_feature_available".
5264 (Added in 1.33.14)
5266 guestfs_download_offset
5268 int
5269 guestfs_download_offset (guestfs_h *g,
5270 const char *remotefilename,
5271 const char *filename,
5272 int64_t offset,
5273 int64_t size);
5274 Download file remotefilename and save it as filename on the local
5276 machine.
5277 remotefilename is read for "size" bytes starting at "offset" (this
5279 region must be within the file or device).
5280 Note that there is no limit on the amount of data that can be
5282 downloaded with this call, unlike with "guestfs_pread", and this call
5283 always reads the full amount unless an error occurs.
5284 See also "guestfs_download", "guestfs_pread".
5286 This function returns 0 on success or -1 on error.
5288 This long-running command can generate progress notification messages
5290 so that the caller can display a progress bar or indicator. To receive
5291 these messages, the caller must register a progress event callback.
5292 See "GUESTFS_EVENT_PROGRESS".
5293 (Added in 1.5.17)
5295 guestfs_drop_caches
5297 int
5298 guestfs_drop_caches (guestfs_h *g,
5299 int whattodrop);
5300 This instructs the guest kernel to drop its page cache, and/or dentries
5302 and inode caches. The parameter "whattodrop" tells the kernel what
5303 precisely to drop, see https://linux-mm.org/Drop_Caches
5304 Setting "whattodrop" to 3 should drop everything.
5306 This automatically calls sync(2) before the operation, so that the
5308 maximum guest memory is freed.
5309 This function returns 0 on success or -1 on error.
5311 (Added in 1.0.18)
5313 guestfs_du
5315 int64_t
5316 guestfs_du (guestfs_h *g,
5317 const char *path);
5318 This command runs the "du -s" command to estimate file space usage for
5320 "path".
5321 "path" can be a file or a directory. If "path" is a directory then the
5323 estimate includes the contents of the directory and all subdirectories
5324 (recursively).
5325 The result is the estimated size in kilobytes (ie. units of 1024
5327 bytes).
5328 On error this function returns -1.
5330 This long-running command can generate progress notification messages
5332 so that the caller can display a progress bar or indicator. To receive
5333 these messages, the caller must register a progress event callback.
5334 See "GUESTFS_EVENT_PROGRESS".
5335 (Added in 1.0.54)
5337 guestfs_e2fsck
5339 int
5340 guestfs_e2fsck (guestfs_h *g,
5341 const char *device,
5342 ...);
5343 You may supply a list of optional arguments to this call. Use zero or
5345 more of the following pairs of parameters, and terminate the list with
5346 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5347 GUESTFS_E2FSCK_CORRECT, int correct,
5349 GUESTFS_E2FSCK_FORCEALL, int forceall,
5350 This runs the ext2/ext3 filesystem checker on "device". It can take
5352 the following optional arguments:
5353 "correct"
5355 Automatically repair the file system. This option will cause e2fsck
5356 to automatically fix any filesystem problems that can be safely
5357 fixed without human intervention.
5358 This option may not be specified at the same time as the "forceall"
5360 option.
5361 "forceall"
5363 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5364 used non-interactively.
5365 This option may not be specified at the same time as the "correct"
5367 option.
5368 This function returns 0 on success or -1 on error.
5370 (Added in 1.15.17)
5372 guestfs_e2fsck_va
5374 int
5375 guestfs_e2fsck_va (guestfs_h *g,
5376 const char *device,
5377 va_list args);
5378 This is the "va_list variant" of "guestfs_e2fsck".
5380 See "CALLS WITH OPTIONAL ARGUMENTS".
5382 guestfs_e2fsck_argv
5384 int
5385 guestfs_e2fsck_argv (guestfs_h *g,
5386 const char *device,
5387 const struct guestfs_e2fsck_argv *optargs);
5388 This is the "argv variant" of "guestfs_e2fsck".
5390 See "CALLS WITH OPTIONAL ARGUMENTS".
5392 guestfs_e2fsck_f
5394 int
5395 guestfs_e2fsck_f (guestfs_h *g,
5396 const char *device);
5397 This function is deprecated. In new code, use the "guestfs_e2fsck"
5399 call instead.
5400 Deprecated functions will not be removed from the API, but the fact
5402 that they are deprecated indicates that there are problems with correct
5403 use of these functions.
5404 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5406 checker on "device", noninteractively (-p), even if the filesystem
5407 appears to be clean (-f).
5408 This function returns 0 on success or -1 on error.
5410 (Added in 1.0.29)
5412 guestfs_echo_daemon
5414 char *
5415 guestfs_echo_daemon (guestfs_h *g,
5416 char *const *words);
5417 This command concatenates the list of "words" passed with single spaces
5419 between them and returns the resulting string.
5420 You can use this command to test the connection through to the daemon.
5422 See also "guestfs_ping_daemon".
5424 This function returns a string, or NULL on error. The caller must free
5426 the returned string after use.
5427 (Added in 1.0.69)
5429 guestfs_egrep
5431 char **
5432 guestfs_egrep (guestfs_h *g,
5433 const char *regex,
5434 const char *path);
5435 This function is deprecated. In new code, use the "guestfs_grep" call
5437 instead.
5438 Deprecated functions will not be removed from the API, but the fact
5440 that they are deprecated indicates that there are problems with correct
5441 use of these functions.
5442 This calls the external egrep(1) program and returns the matching
5444 lines.
5445 This function returns a NULL-terminated array of strings (like
5447 environ(3)), or NULL if there was an error. The caller must free the
5448 strings and the array after use.
5449 Because of the message protocol, there is a transfer limit of somewhere
5451 between 2MB and 4MB. See "PROTOCOL LIMITS".
5452 (Added in 1.0.66)
5454 guestfs_egrepi
5456 char **
5457 guestfs_egrepi (guestfs_h *g,
5458 const char *regex,
5459 const char *path);
5460 This function is deprecated. In new code, use the "guestfs_grep" call
5462 instead.
5463 Deprecated functions will not be removed from the API, but the fact
5465 that they are deprecated indicates that there are problems with correct
5466 use of these functions.
5467 This calls the external "egrep -i" program and returns the matching
5469 lines.
5470 This function returns a NULL-terminated array of strings (like
5472 environ(3)), or NULL if there was an error. The caller must free the
5473 strings and the array after use.
5474 Because of the message protocol, there is a transfer limit of somewhere
5476 between 2MB and 4MB. See "PROTOCOL LIMITS".
5477 (Added in 1.0.66)
5479 guestfs_equal
5481 int
5482 guestfs_equal (guestfs_h *g,
5483 const char *file1,
5484 const char *file2);
5485 This compares the two files file1 and file2 and returns true if their
5487 content is exactly equal, or false otherwise.
5488 The external cmp(1) program is used for the comparison.
5490 This function returns a C truth value on success or -1 on error.
5492 (Added in 1.0.18)
5494 guestfs_exists
5496 int
5497 guestfs_exists (guestfs_h *g,
5498 const char *path);
5499 This returns "true" if and only if there is a file, directory (or
5501 anything) with the given "path" name.
5502 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5504 This function returns a C truth value on success or -1 on error.
5506 (Added in 0.8)
5508 guestfs_extlinux
5510 int
5511 guestfs_extlinux (guestfs_h *g,
5512 const char *directory);
5513 Install the SYSLINUX bootloader on the device mounted at directory.
5515 Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5516 used on an ext2/3/4 or btrfs filesystem.
5517 The directory parameter can be either a mountpoint, or a directory
5519 within the mountpoint.
5520 You also have to mark the partition as "active"
5522 ("guestfs_part_set_bootable") and a Master Boot Record must be
5523 installed (eg. using "guestfs_pwrite_device") on the first sector of
5524 the whole disk. The SYSLINUX package comes with some suitable Master
5525 Boot Records. See the extlinux(1) man page for further information.
5526 Additional configuration can be supplied to SYSLINUX by placing a file
5528 called extlinux.conf on the filesystem under directory. For further
5529 information about the contents of this file, see extlinux(1).
5530 See also "guestfs_syslinux".
5532 This function returns 0 on success or -1 on error.
5534 This function depends on the feature "extlinux". See also
5536 "guestfs_feature_available".
5537 (Added in 1.21.27)
5539 guestfs_f2fs_expand
5541 int
5542 guestfs_f2fs_expand (guestfs_h *g,
5543 const char *device);
5544 This expands a f2fs filesystem to match the size of the underlying
5546 device.
5547 This function returns 0 on success or -1 on error.
5549 This function depends on the feature "f2fs". See also
5551 "guestfs_feature_available".
5552 (Added in 1.39.3)
5554 guestfs_fallocate
5556 int
5557 guestfs_fallocate (guestfs_h *g,
5558 const char *path,
5559 int len);
5560 This function is deprecated. In new code, use the
5562 "guestfs_fallocate64" call instead.
5563 Deprecated functions will not be removed from the API, but the fact
5565 that they are deprecated indicates that there are problems with correct
5566 use of these functions.
5567 This command preallocates a file (containing zero bytes) named "path"
5569 of size "len" bytes. If the file exists already, it is overwritten.
5570 Do not confuse this with the guestfish-specific "alloc" command which
5572 allocates a file in the host and attaches it as a device.
5573 This function returns 0 on success or -1 on error.
5575 (Added in 1.0.66)
5577 guestfs_fallocate64
5579 int
5580 guestfs_fallocate64 (guestfs_h *g,
5581 const char *path,
5582 int64_t len);
5583 This command preallocates a file (containing zero bytes) named "path"
5585 of size "len" bytes. If the file exists already, it is overwritten.
5586 Note that this call allocates disk blocks for the file. To create a
5588 sparse file use "guestfs_truncate_size" instead.
5589 The deprecated call "guestfs_fallocate" does the same, but owing to an
5591 oversight it only allowed 30 bit lengths to be specified, effectively
5592 limiting the maximum size of files created through that call to 1GB.
5593 Do not confuse this with the guestfish-specific "alloc" and "sparse"
5595 commands which create a file in the host and attach it as a device.
5596 This function returns 0 on success or -1 on error.
5598 (Added in 1.3.17)
5600 guestfs_feature_available
5602 int
5603 guestfs_feature_available (guestfs_h *g,
5604 char *const *groups);
5605 This is the same as "guestfs_available", but unlike that call it
5607 returns a simple true/false boolean result, instead of throwing an
5608 exception if a feature is not found. For other documentation see
5609 "guestfs_available".
5610 This function returns a C truth value on success or -1 on error.
5612 (Added in 1.21.26)
5614 guestfs_fgrep
5616 char **
5617 guestfs_fgrep (guestfs_h *g,
5618 const char *pattern,
5619 const char *path);
5620 This function is deprecated. In new code, use the "guestfs_grep" call
5622 instead.
5623 Deprecated functions will not be removed from the API, but the fact
5625 that they are deprecated indicates that there are problems with correct
5626 use of these functions.
5627 This calls the external fgrep(1) program and returns the matching
5629 lines.
5630 This function returns a NULL-terminated array of strings (like
5632 environ(3)), or NULL if there was an error. The caller must free the
5633 strings and the array after use.
5634 Because of the message protocol, there is a transfer limit of somewhere
5636 between 2MB and 4MB. See "PROTOCOL LIMITS".
5637 (Added in 1.0.66)
5639 guestfs_fgrepi
5641 char **
5642 guestfs_fgrepi (guestfs_h *g,
5643 const char *pattern,
5644 const char *path);
5645 This function is deprecated. In new code, use the "guestfs_grep" call
5647 instead.
5648 Deprecated functions will not be removed from the API, but the fact
5650 that they are deprecated indicates that there are problems with correct
5651 use of these functions.
5652 This calls the external "fgrep -i" program and returns the matching
5654 lines.
5655 This function returns a NULL-terminated array of strings (like
5657 environ(3)), or NULL if there was an error. The caller must free the
5658 strings and the array after use.
5659 Because of the message protocol, there is a transfer limit of somewhere
5661 between 2MB and 4MB. See "PROTOCOL LIMITS".
5662 (Added in 1.0.66)
5664 guestfs_file
5666 char *
5667 guestfs_file (guestfs_h *g,
5668 const char *path);
5669 This call uses the standard file(1) command to determine the type or
5671 contents of the file.
5672 This call will also transparently look inside various types of
5674 compressed file.
5675 The exact command which runs is "file -zb path". Note in particular
5677 that the filename is not prepended to the output (the -b option).
5678 The output depends on the output of the underlying file(1) command and
5680 it can change in future in ways beyond our control. In other words,
5681 the output is not guaranteed by the ABI.
5682 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5684 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5685 This function returns a string, or NULL on error. The caller must free
5687 the returned string after use.
5688 (Added in 1.9.1)
5690 guestfs_file_architecture
5692 char *
5693 guestfs_file_architecture (guestfs_h *g,
5694 const char *filename);
5695 This detects the architecture of the binary filename, and returns it if
5697 known.
5698 Currently defined architectures are:
5700 "aarch64"
5702 64 bit ARM.
5703 "arm"
5705 32 bit ARM.
5706 "i386"
5708 This string is returned for all 32 bit i386, i486, i586, i686
5709 binaries irrespective of the precise processor requirements of the
5710 binary.
5711 "ia64"
5713 Intel Itanium.
5714 "ppc"
5716 32 bit Power PC.
5717 "ppc64"
5719 64 bit Power PC (big endian).
5720 "ppc64le"
5722 64 bit Power PC (little endian).
5723 "riscv32"
5725 "riscv64"
5726 "riscv128"
5727 RISC-V 32-, 64- or 128-bit variants.
5728 "s390"
5730 31 bit IBM S/390.
5731 "s390x"
5733 64 bit IBM S/390.
5734 "sparc"
5736 32 bit SPARC.
5737 "sparc64"
5739 64 bit SPARC V9 and above.
5740 "x86_64"
5742 64 bit x86-64.
5743 Libguestfs may return other architecture strings in future.
5745 The function works on at least the following types of files:
5747 • many types of Un*x and Linux binary
5749 • many types of Un*x and Linux shared library
5751 • Windows Win32 and Win64 binaries
5753 • Windows Win32 and Win64 DLLs
5755 Win32 binaries and DLLs return "i386".
5757 Win64 binaries and DLLs return "x86_64".
5759 • Linux kernel modules
5761 • Linux new-style initrd images
5763 • some non-x86 Linux vmlinuz kernels
5765 What it can't do currently:
5767 • static libraries (libfoo.a)
5769 • Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5771 • x86 Linux vmlinuz kernels
5773 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5775 and compressed code, and are horribly hard to unpack. If you want
5776 to find the architecture of a kernel, use the architecture of the
5777 associated initrd or kernel module(s) instead.
5778 This function returns a string, or NULL on error. The caller must free
5780 the returned string after use.
5781 (Added in 1.5.3)
5783 guestfs_filesize
5785 int64_t
5786 guestfs_filesize (guestfs_h *g,
5787 const char *file);
5788 This command returns the size of file in bytes.
5790 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5792 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
5793 devices, use "guestfs_blockdev_getsize64".
5794 On error this function returns -1.
5796 (Added in 1.0.82)
5798 guestfs_filesystem_available
5800 int
5801 guestfs_filesystem_available (guestfs_h *g,
5802 const char *filesystem);
5803 Check whether libguestfs supports the named filesystem. The argument
5805 "filesystem" is a filesystem name, such as "ext3".
5806 You must call "guestfs_launch" before using this command.
5808 This is mainly useful as a negative test. If this returns true, it
5810 doesn't mean that a particular filesystem can be created or mounted,
5811 since filesystems can fail for other reasons such as it being a later
5812 version of the filesystem, or having incompatible features, or lacking
5813 the right mkfs.<fs> tool.
5814 See also "guestfs_available", "guestfs_feature_available",
5816 "AVAILABILITY".
5817 This function returns a C truth value on success or -1 on error.
5819 (Added in 1.19.5)
5821 guestfs_filesystem_walk
5823 struct guestfs_tsk_dirent_list *
5824 guestfs_filesystem_walk (guestfs_h *g,
5825 const char *device);
5826 Walk through the internal structures of a disk partition (eg.
5828 /dev/sda1) in order to return a list of all the files and directories
5829 stored within.
5830 It is not necessary to mount the disk partition to run this command.
5832 All entries in the filesystem are returned. This function can list
5834 deleted or unaccessible files. The entries are not sorted.
5835 The "tsk_dirent" structure contains the following fields.
5837 "tsk_inode"
5839 Filesystem reference number of the node. It might be 0 if the node
5840 has been deleted.
5841 "tsk_type"
5843 Basic file type information. See below for a detailed list of
5844 values.
5845 "tsk_size"
5847 File size in bytes. It might be "-1" if the node has been deleted.
5848 "tsk_name"
5850 The file path relative to its directory.
5851 "tsk_flags"
5853 Bitfield containing extra information regarding the entry. It
5854 contains the logical OR of the following values:
5855 0x0001
5857 If set to 1, the file is allocated and visible within the
5858 filesystem. Otherwise, the file has been deleted. Under
5859 certain circumstances, the function "download_inode" can be
5860 used to recover deleted files.
5861 0x0002
5863 Filesystem such as NTFS and Ext2 or greater, separate the file
5864 name from the metadata structure. The bit is set to 1 when the
5865 file name is in an unallocated state and the metadata structure
5866 is in an allocated one. This generally implies the metadata
5867 has been reallocated to a new file. Therefore, information
5868 such as file type, file size, timestamps, number of links and
5869 symlink target might not correspond with the ones of the
5870 original deleted entry.
5871 0x0004
5873 The bit is set to 1 when the file is compressed using
5874 filesystem native compression support (NTFS). The API is not
5875 able to detect application level compression.
5876 "tsk_atime_sec"
5878 "tsk_atime_nsec"
5879 "tsk_mtime_sec"
5880 "tsk_mtime_nsec"
5881 "tsk_ctime_sec"
5882 "tsk_ctime_nsec"
5883 "tsk_crtime_sec"
5884 "tsk_crtime_nsec"
5885 Respectively, access, modification, last status change and creation
5886 time in Unix format in seconds and nanoseconds.
5887 "tsk_nlink"
5889 Number of file names pointing to this entry.
5890 "tsk_link"
5892 If the entry is a symbolic link, this field will contain the path
5893 to the target file.
5894 The "tsk_type" field will contain one of the following characters:
5896 'b' Block special
5898 'c' Char special
5900 'd' Directory
5902 'f' FIFO (named pipe)
5904 'l' Symbolic link
5906 'r' Regular file
5908 's' Socket
5910 'h' Shadow inode (Solaris)
5912 'w' Whiteout inode (BSD)
5914 'u' Unknown file type
5916 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
5918 there was an error. The caller must call
5919 "guestfs_free_tsk_dirent_list" after use.
5920 This long-running command can generate progress notification messages
5922 so that the caller can display a progress bar or indicator. To receive
5923 these messages, the caller must register a progress event callback.
5924 See "GUESTFS_EVENT_PROGRESS".
5925 This function depends on the feature "libtsk". See also
5927 "guestfs_feature_available".
5928 (Added in 1.33.39)
5930 guestfs_fill
5932 int
5933 guestfs_fill (guestfs_h *g,
5934 int c,
5935 int len,
5936 const char *path);
5937 This command creates a new file called "path". The initial content of
5939 the file is "len" octets of "c", where "c" must be a number in the
5940 range "[0..255]".
5941 To fill a file with zero bytes (sparsely), it is much more efficient to
5943 use "guestfs_truncate_size". To create a file with a pattern of
5944 repeating bytes use "guestfs_fill_pattern".
5945 This function returns 0 on success or -1 on error.
5947 This long-running command can generate progress notification messages
5949 so that the caller can display a progress bar or indicator. To receive
5950 these messages, the caller must register a progress event callback.
5951 See "GUESTFS_EVENT_PROGRESS".
5952 (Added in 1.0.79)
5954 guestfs_fill_dir
5956 int
5957 guestfs_fill_dir (guestfs_h *g,
5958 const char *dir,
5959 int nr);
5960 This function, useful for testing filesystems, creates "nr" empty files
5962 in the directory "dir" with names 00000000 through "nr-1" (ie. each
5963 file name is 8 digits long padded with zeroes).
5964 This function returns 0 on success or -1 on error.
5966 (Added in 1.19.32)
5968 guestfs_fill_pattern
5970 int
5971 guestfs_fill_pattern (guestfs_h *g,
5972 const char *pattern,
5973 int len,
5974 const char *path);
5975 This function is like "guestfs_fill" except that it creates a new file
5977 of length "len" containing the repeating pattern of bytes in "pattern".
5978 The pattern is truncated if necessary to ensure the length of the file
5979 is exactly "len" bytes.
5980 This function returns 0 on success or -1 on error.
5982 This long-running command can generate progress notification messages
5984 so that the caller can display a progress bar or indicator. To receive
5985 these messages, the caller must register a progress event callback.
5986 See "GUESTFS_EVENT_PROGRESS".
5987 (Added in 1.3.12)
5989 guestfs_find
5991 char **
5992 guestfs_find (guestfs_h *g,
5993 const char *directory);
5994 This command lists out all files and directories, recursively, starting
5996 at directory. It is essentially equivalent to running the shell
5997 command "find directory -print" but some post-processing happens on the
5998 output, described below.
5999 This returns a list of strings without any prefix. Thus if the
6001 directory structure was:
6002 /tmp/a
6004 /tmp/b
6005 /tmp/c/d
6006 then the returned list from "guestfs_find" /tmp would be 4 elements:
6008 a
6010 b
6011 c
6012 c/d
6013 If directory is not a directory, then this command returns an error.
6015 The returned list is sorted.
6017 This function returns a NULL-terminated array of strings (like
6019 environ(3)), or NULL if there was an error. The caller must free the
6020 strings and the array after use.
6021 (Added in 1.0.27)
6023 guestfs_find0
6025 int
6026 guestfs_find0 (guestfs_h *g,
6027 const char *directory,
6028 const char *files);
6029 This command lists out all files and directories, recursively, starting
6031 at directory, placing the resulting list in the external file called
6032 files.
6033 This command works the same way as "guestfs_find" with the following
6035 exceptions:
6036 • The resulting list is written to an external file.
6038 • Items (filenames) in the result are separated by "\0" characters.
6040 See find(1) option -print0.
6041 • The result list is not sorted.
6043 This function returns 0 on success or -1 on error.
6045 (Added in 1.0.74)
6047 guestfs_find_inode
6049 struct guestfs_tsk_dirent_list *
6050 guestfs_find_inode (guestfs_h *g,
6051 const char *device,
6052 int64_t inode);
6053 Searches all the entries associated with the given inode.
6055 For each entry, a "tsk_dirent" structure is returned. See
6057 "filesystem_walk" for more information about "tsk_dirent" structures.
6058 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6060 there was an error. The caller must call
6061 "guestfs_free_tsk_dirent_list" after use.
6062 This long-running command can generate progress notification messages
6064 so that the caller can display a progress bar or indicator. To receive
6065 these messages, the caller must register a progress event callback.
6066 See "GUESTFS_EVENT_PROGRESS".
6067 This function depends on the feature "libtsk". See also
6069 "guestfs_feature_available".
6070 (Added in 1.35.6)
6072 guestfs_findfs_label
6074 char *
6075 guestfs_findfs_label (guestfs_h *g,
6076 const char *label);
6077 This command searches the filesystems and returns the one which has the
6079 given label. An error is returned if no such filesystem can be found.
6080 To find the label of a filesystem, use "guestfs_vfs_label".
6082 This function returns a string, or NULL on error. The caller must free
6084 the returned string after use.
6085 (Added in 1.5.3)
6087 guestfs_findfs_uuid
6089 char *
6090 guestfs_findfs_uuid (guestfs_h *g,
6091 const char *uuid);
6092 This command searches the filesystems and returns the one which has the
6094 given UUID. An error is returned if no such filesystem can be found.
6095 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6097 This function returns a string, or NULL on error. The caller must free
6099 the returned string after use.
6100 (Added in 1.5.3)
6102 guestfs_fsck
6104 int
6105 guestfs_fsck (guestfs_h *g,
6106 const char *fstype,
6107 const char *device);
6108 This runs the filesystem checker (fsck) on "device" which should have
6110 filesystem type "fstype".
6111 The returned integer is the status. See fsck(8) for the list of status
6113 codes from "fsck".
6114 Notes:
6116 • Multiple status codes can be summed together.
6118 • A non-zero return code can mean "success", for example if errors
6120 have been corrected on the filesystem.
6121 • Checking or repairing NTFS volumes is not supported (by linux-
6123 ntfs).
6124 This command is entirely equivalent to running "fsck -a -t fstype
6126 device".
6127 On error this function returns -1.
6129 (Added in 1.0.16)
6131 guestfs_fstrim
6133 int
6134 guestfs_fstrim (guestfs_h *g,
6135 const char *mountpoint,
6136 ...);
6137 You may supply a list of optional arguments to this call. Use zero or
6139 more of the following pairs of parameters, and terminate the list with
6140 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6141 GUESTFS_FSTRIM_OFFSET, int64_t offset,
6143 GUESTFS_FSTRIM_LENGTH, int64_t length,
6144 GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6145 Trim the free space in the filesystem mounted on "mountpoint". The
6147 filesystem must be mounted read-write.
6148 The filesystem contents are not affected, but any free space in the
6150 filesystem is "trimmed", that is, given back to the host device, thus
6151 making disk images more sparse, allowing unused space in qcow2 files to
6152 be reused, etc.
6153 This operation requires support in libguestfs, the mounted filesystem,
6155 the host filesystem, qemu and the host kernel. If this support isn't
6156 present it may give an error or even appear to run but do nothing.
6157 In the case where the kernel vfs driver does not support trimming, this
6159 call will fail with errno set to "ENOTSUP". Currently this happens
6160 when trying to trim FAT filesystems.
6161 See also "guestfs_zero_free_space". That is a slightly different
6163 operation that turns free space in the filesystem into zeroes. It is
6164 valid to call "guestfs_fstrim" either instead of, or after calling
6165 "guestfs_zero_free_space".
6166 This function returns 0 on success or -1 on error.
6168 This function depends on the feature "fstrim". See also
6170 "guestfs_feature_available".
6171 (Added in 1.19.6)
6173 guestfs_fstrim_va
6175 int
6176 guestfs_fstrim_va (guestfs_h *g,
6177 const char *mountpoint,
6178 va_list args);
6179 This is the "va_list variant" of "guestfs_fstrim".
6181 See "CALLS WITH OPTIONAL ARGUMENTS".
6183 guestfs_fstrim_argv
6185 int
6186 guestfs_fstrim_argv (guestfs_h *g,
6187 const char *mountpoint,
6188 const struct guestfs_fstrim_argv *optargs);
6189 This is the "argv variant" of "guestfs_fstrim".
6191 See "CALLS WITH OPTIONAL ARGUMENTS".
6193 guestfs_get_append
6195 const char *
6196 guestfs_get_append (guestfs_h *g);
6197 Return the additional kernel options which are added to the libguestfs
6199 appliance kernel command line.
6200 If "NULL" then no options are added.
6202 This function returns a string which may be NULL. There is no way to
6204 return an error from this function. The string is owned by the guest
6205 handle and must not be freed.
6206 (Added in 1.0.26)
6208 guestfs_get_attach_method
6210 char *
6211 guestfs_get_attach_method (guestfs_h *g);
6212 This function is deprecated. In new code, use the
6214 "guestfs_get_backend" call instead.
6215 Deprecated functions will not be removed from the API, but the fact
6217 that they are deprecated indicates that there are problems with correct
6218 use of these functions.
6219 Return the current backend.
6221 See "guestfs_set_backend" and "BACKEND".
6223 This function returns a string, or NULL on error. The caller must free
6225 the returned string after use.
6226 (Added in 1.9.8)
6228 guestfs_get_autosync
6230 int
6231 guestfs_get_autosync (guestfs_h *g);
6232 Get the autosync flag.
6234 This function returns a C truth value on success or -1 on error.
6236 (Added in 0.3)
6238 guestfs_get_backend
6240 char *
6241 guestfs_get_backend (guestfs_h *g);
6242 Return the current backend.
6244 This handle property was previously called the "attach method".
6246 See "guestfs_set_backend" and "BACKEND".
6248 This function returns a string, or NULL on error. The caller must free
6250 the returned string after use.
6251 (Added in 1.21.26)
6253 guestfs_get_backend_setting
6255 char *
6256 guestfs_get_backend_setting (guestfs_h *g,
6257 const char *name);
6258 Find a backend setting string which is either "name" or begins with
6260 "name=". If "name", this returns the string "1". If "name=", this
6261 returns the part after the equals sign (which may be an empty string).
6262 If no such setting is found, this function throws an error. The errno
6264 (see "guestfs_last_errno") will be "ESRCH" in this case.
6265 See "BACKEND", "BACKEND SETTINGS".
6267 This function returns a string, or NULL on error. The caller must free
6269 the returned string after use.
6270 (Added in 1.27.2)
6272 guestfs_get_backend_settings
6274 char **
6275 guestfs_get_backend_settings (guestfs_h *g);
6276 Return the current backend settings.
6278 This call returns all backend settings strings. If you want to find a
6280 single backend setting, see "guestfs_get_backend_setting".
6281 See "BACKEND", "BACKEND SETTINGS".
6283 This function returns a NULL-terminated array of strings (like
6285 environ(3)), or NULL if there was an error. The caller must free the
6286 strings and the array after use.
6287 (Added in 1.25.24)
6289 guestfs_get_cachedir
6291 char *
6292 guestfs_get_cachedir (guestfs_h *g);
6293 Get the directory used by the handle to store the appliance cache.
6295 This function returns a string, or NULL on error. The caller must free
6297 the returned string after use.
6298 (Added in 1.19.58)
6300 guestfs_get_direct
6302 int
6303 guestfs_get_direct (guestfs_h *g);
6304 This function is deprecated. In new code, use the
6306 "guestfs_internal_get_console_socket" call instead.
6307 Deprecated functions will not be removed from the API, but the fact
6309 that they are deprecated indicates that there are problems with correct
6310 use of these functions.
6311 Return the direct appliance mode flag.
6313 This function returns a C truth value on success or -1 on error.
6315 (Added in 1.0.72)
6317 guestfs_get_e2attrs
6319 char *
6320 guestfs_get_e2attrs (guestfs_h *g,
6321 const char *file);
6322 This returns the file attributes associated with file.
6324 The attributes are a set of bits associated with each inode which
6326 affect the behaviour of the file. The attributes are returned as a
6327 string of letters (described below). The string may be empty,
6328 indicating that no file attributes are set for this file.
6329 These attributes are only present when the file is located on an
6331 ext2/3/4 filesystem. Using this call on other filesystem types will
6332 result in an error.
6333 The characters (file attributes) in the returned string are currently:
6335 'A' When the file is accessed, its atime is not modified.
6337 'a' The file is append-only.
6339 'c' The file is compressed on-disk.
6341 'D' (Directories only.) Changes to this directory are written
6343 synchronously to disk.
6344 'd' The file is not a candidate for backup (see dump(8)).
6346 'E' The file has compression errors.
6348 'e' The file is using extents.
6350 'h' The file is storing its blocks in units of the filesystem blocksize
6352 instead of sectors.
6353 'I' (Directories only.) The directory is using hashed trees.
6355 'i' The file is immutable. It cannot be modified, deleted or renamed.
6357 No link can be created to this file.
6358 'j' The file is data-journaled.
6360 's' When the file is deleted, all its blocks will be zeroed.
6362 'S' Changes to this file are written synchronously to disk.
6364 'T' (Directories only.) This is a hint to the block allocator that
6366 subdirectories contained in this directory should be spread across
6367 blocks. If not present, the block allocator will try to group
6368 subdirectories together.
6369 't' For a file, this disables tail-merging. (Not used by upstream
6371 implementations of ext2.)
6372 'u' When the file is deleted, its blocks will be saved, allowing the
6374 file to be undeleted.
6375 'X' The raw contents of the compressed file may be accessed.
6377 'Z' The compressed file is dirty.
6379 More file attributes may be added to this list later. Not all file
6381 attributes may be set for all kinds of files. For detailed
6382 information, consult the chattr(1) man page.
6383 See also "guestfs_set_e2attrs".
6385 Don't confuse these attributes with extended attributes (see
6387 "guestfs_getxattr").
6388 This function returns a string, or NULL on error. The caller must free
6390 the returned string after use.
6391 (Added in 1.17.31)
6393 guestfs_get_e2generation
6395 int64_t
6396 guestfs_get_e2generation (guestfs_h *g,
6397 const char *file);
6398 This returns the ext2 file generation of a file. The generation (which
6400 used to be called the "version") is a number associated with an inode.
6401 This is most commonly used by NFS servers.
6402 The generation is only present when the file is located on an ext2/3/4
6404 filesystem. Using this call on other filesystem types will result in
6405 an error.
6406 See "guestfs_set_e2generation".
6408 On error this function returns -1.
6410 (Added in 1.17.31)
6412 guestfs_get_e2label
6414 char *
6415 guestfs_get_e2label (guestfs_h *g,
6416 const char *device);
6417 This function is deprecated. In new code, use the "guestfs_vfs_label"
6419 call instead.
6420 Deprecated functions will not be removed from the API, but the fact
6422 that they are deprecated indicates that there are problems with correct
6423 use of these functions.
6424 This returns the ext2/3/4 filesystem label of the filesystem on
6426 "device".
6427 This function returns a string, or NULL on error. The caller must free
6429 the returned string after use.
6430 (Added in 1.0.15)
6432 guestfs_get_e2uuid
6434 char *
6435 guestfs_get_e2uuid (guestfs_h *g,
6436 const char *device);
6437 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
6439 call instead.
6440 Deprecated functions will not be removed from the API, but the fact
6442 that they are deprecated indicates that there are problems with correct
6443 use of these functions.
6444 This returns the ext2/3/4 filesystem UUID of the filesystem on
6446 "device".
6447 This function returns a string, or NULL on error. The caller must free
6449 the returned string after use.
6450 (Added in 1.0.15)
6452 guestfs_get_hv
6454 char *
6455 guestfs_get_hv (guestfs_h *g);
6456 Return the current hypervisor binary.
6458 This is always non-NULL. If it wasn't set already, then this will
6460 return the default qemu binary name.
6461 This function returns a string, or NULL on error. The caller must free
6463 the returned string after use.
6464 (Added in 1.23.17)
6466 guestfs_get_identifier
6468 const char *
6469 guestfs_get_identifier (guestfs_h *g);
6470 Get the handle identifier. See "guestfs_set_identifier".
6472 This function returns a string, or NULL on error. The string is owned
6474 by the guest handle and must not be freed.
6475 (Added in 1.31.14)
6477 guestfs_get_libvirt_requested_credential_challenge
6479 char *
6480 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6481 int index);
6482 Get the challenge (provided by libvirt) for the "index"'th requested
6484 credential. If libvirt did not provide a challenge, this returns the
6485 empty string "".
6486 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6488 This function returns a string, or NULL on error. The caller must free
6490 the returned string after use.
6491 (Added in 1.19.52)
6493 guestfs_get_libvirt_requested_credential_defresult
6495 char *
6496 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6497 int index);
6498 Get the default result (provided by libvirt) for the "index"'th
6500 requested credential. If libvirt did not provide a default result,
6501 this returns the empty string "".
6502 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6504 This function returns a string, or NULL on error. The caller must free
6506 the returned string after use.
6507 (Added in 1.19.52)
6509 guestfs_get_libvirt_requested_credential_prompt
6511 char *
6512 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6513 int index);
6514 Get the prompt (provided by libvirt) for the "index"'th requested
6516 credential. If libvirt did not provide a prompt, this returns the
6517 empty string "".
6518 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6520 This function returns a string, or NULL on error. The caller must free
6522 the returned string after use.
6523 (Added in 1.19.52)
6525 guestfs_get_libvirt_requested_credentials
6527 char **
6528 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6529 This should only be called during the event callback for events of type
6531 "GUESTFS_EVENT_LIBVIRT_AUTH".
6532 Return the list of credentials requested by libvirt. Possible values
6534 are a subset of the strings provided when you called
6535 "guestfs_set_libvirt_supported_credentials".
6536 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6538 This function returns a NULL-terminated array of strings (like
6540 environ(3)), or NULL if there was an error. The caller must free the
6541 strings and the array after use.
6542 (Added in 1.19.52)
6544 guestfs_get_memsize
6546 int
6547 guestfs_get_memsize (guestfs_h *g);
6548 This gets the memory size in megabytes allocated to the hypervisor.
6550 If "guestfs_set_memsize" was not called on this handle, and if
6552 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6553 default value for memsize.
6554 For more information on the architecture of libguestfs, see guestfs(3).
6556 On error this function returns -1.
6558 (Added in 1.0.55)
6560 guestfs_get_network
6562 int
6563 guestfs_get_network (guestfs_h *g);
6564 This returns the enable network flag.
6566 This function returns a C truth value on success or -1 on error.
6568 (Added in 1.5.4)
6570 guestfs_get_path
6572 const char *
6573 guestfs_get_path (guestfs_h *g);
6574 Return the current search path.
6576 This is always non-NULL. If it wasn't set already, then this will
6578 return the default path.
6579 This function returns a string, or NULL on error. The string is owned
6581 by the guest handle and must not be freed.
6582 (Added in 0.3)
6584 guestfs_get_pgroup
6586 int
6587 guestfs_get_pgroup (guestfs_h *g);
6588 This returns the process group flag.
6590 This function returns a C truth value on success or -1 on error.
6592 (Added in 1.11.18)
6594 guestfs_get_pid
6596 int
6597 guestfs_get_pid (guestfs_h *g);
6598 Return the process ID of the hypervisor. If there is no hypervisor
6600 running, then this will return an error.
6601 This is an internal call used for debugging and testing.
6603 On error this function returns -1.
6605 (Added in 1.0.56)
6607 guestfs_get_program
6609 const char *
6610 guestfs_get_program (guestfs_h *g);
6611 Get the program name. See "guestfs_set_program".
6613 This function returns a string, or NULL on error. The string is owned
6615 by the guest handle and must not be freed.
6616 (Added in 1.21.29)
6618 guestfs_get_qemu
6620 const char *
6621 guestfs_get_qemu (guestfs_h *g);
6622 This function is deprecated. In new code, use the "guestfs_get_hv"
6624 call instead.
6625 Deprecated functions will not be removed from the API, but the fact
6627 that they are deprecated indicates that there are problems with correct
6628 use of these functions.
6629 Return the current hypervisor binary (usually qemu).
6631 This is always non-NULL. If it wasn't set already, then this will
6633 return the default qemu binary name.
6634 This function returns a string, or NULL on error. The string is owned
6636 by the guest handle and must not be freed.
6637 (Added in 1.0.6)
6639 guestfs_get_recovery_proc
6641 int
6642 guestfs_get_recovery_proc (guestfs_h *g);
6643 Return the recovery process enabled flag.
6645 This function returns a C truth value on success or -1 on error.
6647 (Added in 1.0.77)
6649 guestfs_get_selinux
6651 int
6652 guestfs_get_selinux (guestfs_h *g);
6653 This function is deprecated. In new code, use the
6655 "guestfs_selinux_relabel" call instead.
6656 Deprecated functions will not be removed from the API, but the fact
6658 that they are deprecated indicates that there are problems with correct
6659 use of these functions.
6660 This returns the current setting of the selinux flag which is passed to
6662 the appliance at boot time. See "guestfs_set_selinux".
6663 For more information on the architecture of libguestfs, see guestfs(3).
6665 This function returns a C truth value on success or -1 on error.
6667 (Added in 1.0.67)
6669 guestfs_get_smp
6671 int
6672 guestfs_get_smp (guestfs_h *g);
6673 This returns the number of virtual CPUs assigned to the appliance.
6675 On error this function returns -1.
6677 (Added in 1.13.15)
6679 guestfs_get_sockdir
6681 char *
6682 guestfs_get_sockdir (guestfs_h *g);
6683 Get the directory used by the handle to store temporary socket files.
6685 This is different from "guestfs_get_tmpdir", as we need shorter paths
6687 for sockets (due to the limited buffers of filenames for UNIX sockets),
6688 and "guestfs_get_tmpdir" may be too long for them.
6689 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6691 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6692 the default.
6693 This function returns a string, or NULL on error. The caller must free
6695 the returned string after use.
6696 (Added in 1.33.8)
6698 guestfs_get_state
6700 int
6701 guestfs_get_state (guestfs_h *g);
6702 This returns the current state as an opaque integer. This is only
6704 useful for printing debug and internal error messages.
6705 For more information on states, see guestfs(3).
6707 On error this function returns -1.
6709 (Added in 1.0.2)
6711 guestfs_get_tmpdir
6713 char *
6714 guestfs_get_tmpdir (guestfs_h *g);
6715 Get the directory used by the handle to store temporary files.
6717 This function returns a string, or NULL on error. The caller must free
6719 the returned string after use.
6720 (Added in 1.19.58)
6722 guestfs_get_trace
6724 int
6725 guestfs_get_trace (guestfs_h *g);
6726 Return the command trace flag.
6728 This function returns a C truth value on success or -1 on error.
6730 (Added in 1.0.69)
6732 guestfs_get_umask
6734 int
6735 guestfs_get_umask (guestfs_h *g);
6736 Return the current umask. By default the umask is 022 unless it has
6738 been set by calling "guestfs_umask".
6739 On error this function returns -1.
6741 (Added in 1.3.4)
6743 guestfs_get_verbose
6745 int
6746 guestfs_get_verbose (guestfs_h *g);
6747 This returns the verbose messages flag.
6749 This function returns a C truth value on success or -1 on error.
6751 (Added in 0.3)
6753 guestfs_getcon
6755 char *
6756 guestfs_getcon (guestfs_h *g);
6757 This function is deprecated. In new code, use the
6759 "guestfs_selinux_relabel" call instead.
6760 Deprecated functions will not be removed from the API, but the fact
6762 that they are deprecated indicates that there are problems with correct
6763 use of these functions.
6764 This gets the SELinux security context of the daemon.
6766 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6768 This function returns a string, or NULL on error. The caller must free
6770 the returned string after use.
6771 This function depends on the feature "selinux". See also
6773 "guestfs_feature_available".
6774 (Added in 1.0.67)
6776 guestfs_getxattr
6778 char *
6779 guestfs_getxattr (guestfs_h *g,
6780 const char *path,
6781 const char *name,
6782 size_t *size_r);
6783 Get a single extended attribute from file "path" named "name". This
6785 call follows symlinks. If you want to lookup an extended attribute for
6786 the symlink itself, use "guestfs_lgetxattr".
6787 Normally it is better to get all extended attributes from a file in one
6789 go by calling "guestfs_getxattrs". However some Linux filesystem
6790 implementations are buggy and do not provide a way to list out
6791 attributes. For these filesystems (notably ntfs-3g) you have to know
6792 the names of the extended attributes you want in advance and call this
6793 function.
6794 Extended attribute values are blobs of binary data. If there is no
6796 extended attribute named "name", this returns an error.
6797 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6799 This function returns a buffer, or NULL on error. The size of the
6801 returned buffer is written to *size_r. The caller must free the
6802 returned buffer after use.
6803 This function depends on the feature "linuxxattrs". See also
6805 "guestfs_feature_available".
6806 (Added in 1.7.24)
6808 guestfs_getxattrs
6810 struct guestfs_xattr_list *
6811 guestfs_getxattrs (guestfs_h *g,
6812 const char *path);
6813 This call lists the extended attributes of the file or directory
6815 "path".
6816 At the system call level, this is a combination of the listxattr(2) and
6818 getxattr(2) calls.
6819 See also: "guestfs_lgetxattrs", attr(5).
6821 This function returns a "struct guestfs_xattr_list *", or NULL if there
6823 was an error. The caller must call "guestfs_free_xattr_list" after
6824 use.
6825 This function depends on the feature "linuxxattrs". See also
6827 "guestfs_feature_available".
6828 (Added in 1.0.59)
6830 guestfs_glob_expand
6832 char **
6833 guestfs_glob_expand (guestfs_h *g,
6834 const char *pattern);
6835 This function is provided for backwards compatibility with earlier
6837 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
6838 with no optional arguments.
6839 (Added in 1.0.50)
6841 guestfs_glob_expand_opts
6843 char **
6844 guestfs_glob_expand_opts (guestfs_h *g,
6845 const char *pattern,
6846 ...);
6847 You may supply a list of optional arguments to this call. Use zero or
6849 more of the following pairs of parameters, and terminate the list with
6850 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6851 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
6853 This command searches for all the pathnames matching "pattern"
6855 according to the wildcard expansion rules used by the shell.
6856 If no paths match, then this returns an empty list (note: not an
6858 error).
6859 It is just a wrapper around the C glob(3) function with flags
6861 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
6862 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
6864 and it defaults to true. It can be explicitly set as off to return no
6865 trailing slashes in filenames of directories.
6866 Notice that there is no equivalent command for expanding a device name
6868 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
6869 etc functions instead.
6870 This function returns a NULL-terminated array of strings (like
6872 environ(3)), or NULL if there was an error. The caller must free the
6873 strings and the array after use.
6874 (Added in 1.0.50)
6876 guestfs_glob_expand_opts_va
6878 char **
6879 guestfs_glob_expand_opts_va (guestfs_h *g,
6880 const char *pattern,
6881 va_list args);
6882 This is the "va_list variant" of "guestfs_glob_expand_opts".
6884 See "CALLS WITH OPTIONAL ARGUMENTS".
6886 guestfs_glob_expand_opts_argv
6888 char **
6889 guestfs_glob_expand_opts_argv (guestfs_h *g,
6890 const char *pattern,
6891 const struct guestfs_glob_expand_opts_argv *optargs);
6892 This is the "argv variant" of "guestfs_glob_expand_opts".
6894 See "CALLS WITH OPTIONAL ARGUMENTS".
6896 guestfs_grep
6898 char **
6899 guestfs_grep (guestfs_h *g,
6900 const char *regex,
6901 const char *path);
6902 This function is provided for backwards compatibility with earlier
6904 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
6905 optional arguments.
6906 (Added in 1.0.66)
6908 guestfs_grep_opts
6910 char **
6911 guestfs_grep_opts (guestfs_h *g,
6912 const char *regex,
6913 const char *path,
6914 ...);
6915 You may supply a list of optional arguments to this call. Use zero or
6917 more of the following pairs of parameters, and terminate the list with
6918 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6919 GUESTFS_GREP_OPTS_EXTENDED, int extended,
6921 GUESTFS_GREP_OPTS_FIXED, int fixed,
6922 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
6923 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
6924 This calls the external grep(1) program and returns the matching lines.
6926 The optional flags are:
6928 "extended"
6930 Use extended regular expressions. This is the same as using the -E
6931 flag.
6932 "fixed"
6934 Match fixed (don't use regular expressions). This is the same as
6935 using the -F flag.
6936 "insensitive"
6938 Match case-insensitive. This is the same as using the -i flag.
6939 "compressed"
6941 Use zgrep(1) instead of grep(1). This allows the input to be
6942 compress- or gzip-compressed.
6943 This function returns a NULL-terminated array of strings (like
6945 environ(3)), or NULL if there was an error. The caller must free the
6946 strings and the array after use.
6947 Because of the message protocol, there is a transfer limit of somewhere
6949 between 2MB and 4MB. See "PROTOCOL LIMITS".
6950 (Added in 1.0.66)
6952 guestfs_grep_opts_va
6954 char **
6955 guestfs_grep_opts_va (guestfs_h *g,
6956 const char *regex,
6957 const char *path,
6958 va_list args);
6959 This is the "va_list variant" of "guestfs_grep_opts".
6961 See "CALLS WITH OPTIONAL ARGUMENTS".
6963 guestfs_grep_opts_argv
6965 char **
6966 guestfs_grep_opts_argv (guestfs_h *g,
6967 const char *regex,
6968 const char *path,
6969 const struct guestfs_grep_opts_argv *optargs);
6970 This is the "argv variant" of "guestfs_grep_opts".
6972 See "CALLS WITH OPTIONAL ARGUMENTS".
6974 guestfs_grepi
6976 char **
6977 guestfs_grepi (guestfs_h *g,
6978 const char *regex,
6979 const char *path);
6980 This function is deprecated. In new code, use the "guestfs_grep" call
6982 instead.
6983 Deprecated functions will not be removed from the API, but the fact
6985 that they are deprecated indicates that there are problems with correct
6986 use of these functions.
6987 This calls the external "grep -i" program and returns the matching
6989 lines.
6990 This function returns a NULL-terminated array of strings (like
6992 environ(3)), or NULL if there was an error. The caller must free the
6993 strings and the array after use.
6994 Because of the message protocol, there is a transfer limit of somewhere
6996 between 2MB and 4MB. See "PROTOCOL LIMITS".
6997 (Added in 1.0.66)
6999 guestfs_grub_install
7001 int
7002 guestfs_grub_install (guestfs_h *g,
7003 const char *root,
7004 const char *device);
7005 This command installs GRUB 1 (the Grand Unified Bootloader) on
7007 "device", with the root directory being "root".
7008 Notes:
7010 • There is currently no way in the API to install grub2, which is
7012 used by most modern Linux guests. It is possible to run the grub2
7013 command from the guest, although see the caveats in "RUNNING
7014 COMMANDS".
7015 • This uses grub-install(8) from the host. Unfortunately grub is not
7017 always compatible with itself, so this only works in rather narrow
7018 circumstances. Careful testing with each guest version is
7019 advisable.
7020 • If grub-install reports the error "No suitable drive was found in
7022 the generated device map." it may be that you need to create a
7023 /boot/grub/device.map file first that contains the mapping between
7024 grub device names and Linux device names. It is usually sufficient
7025 to create a file containing:
7026 (hd0) /dev/vda
7028 replacing /dev/vda with the name of the installation device.
7030 This function returns 0 on success or -1 on error.
7032 This function depends on the feature "grub". See also
7034 "guestfs_feature_available".
7035 (Added in 1.0.17)
7037 guestfs_head
7039 char **
7040 guestfs_head (guestfs_h *g,
7041 const char *path);
7042 This command returns up to the first 10 lines of a file as a list of
7044 strings.
7045 This function returns a NULL-terminated array of strings (like
7047 environ(3)), or NULL if there was an error. The caller must free the
7048 strings and the array after use.
7049 Because of the message protocol, there is a transfer limit of somewhere
7051 between 2MB and 4MB. See "PROTOCOL LIMITS".
7052 (Added in 1.0.54)
7054 guestfs_head_n
7056 char **
7057 guestfs_head_n (guestfs_h *g,
7058 int nrlines,
7059 const char *path);
7060 If the parameter "nrlines" is a positive number, this returns the first
7062 "nrlines" lines of the file "path".
7063 If the parameter "nrlines" is a negative number, this returns lines
7065 from the file "path", excluding the last "nrlines" lines.
7066 If the parameter "nrlines" is zero, this returns an empty list.
7068 This function returns a NULL-terminated array of strings (like
7070 environ(3)), or NULL if there was an error. The caller must free the
7071 strings and the array after use.
7072 Because of the message protocol, there is a transfer limit of somewhere
7074 between 2MB and 4MB. See "PROTOCOL LIMITS".
7075 (Added in 1.0.54)
7077 guestfs_hexdump
7079 char *
7080 guestfs_hexdump (guestfs_h *g,
7081 const char *path);
7082 This runs "hexdump -C" on the given "path". The result is the human-
7084 readable, canonical hex dump of the file.
7085 This function returns a string, or NULL on error. The caller must free
7087 the returned string after use.
7088 Because of the message protocol, there is a transfer limit of somewhere
7090 between 2MB and 4MB. See "PROTOCOL LIMITS".
7091 (Added in 1.0.22)
7093 guestfs_hivex_close
7095 int
7096 guestfs_hivex_close (guestfs_h *g);
7097 Close the current hivex handle.
7099 This is a wrapper around the hivex(3) call of the same name.
7101 This function returns 0 on success or -1 on error.
7103 This function depends on the feature "hivex". See also
7105 "guestfs_feature_available".
7106 (Added in 1.19.35)
7108 guestfs_hivex_commit
7110 int
7111 guestfs_hivex_commit (guestfs_h *g,
7112 const char *filename);
7113 Commit (write) changes to the hive.
7115 If the optional filename parameter is null, then the changes are
7117 written back to the same hive that was opened. If this is not null
7118 then they are written to the alternate filename given and the original
7119 hive is left untouched.
7120 This is a wrapper around the hivex(3) call of the same name.
7122 This function returns 0 on success or -1 on error.
7124 This function depends on the feature "hivex". See also
7126 "guestfs_feature_available".
7127 (Added in 1.19.35)
7129 guestfs_hivex_node_add_child
7131 int64_t
7132 guestfs_hivex_node_add_child (guestfs_h *g,
7133 int64_t parent,
7134 const char *name);
7135 Add a child node to "parent" named "name".
7137 This is a wrapper around the hivex(3) call of the same name.
7139 On error this function returns -1.
7141 This function depends on the feature "hivex". See also
7143 "guestfs_feature_available".
7144 (Added in 1.19.35)
7146 guestfs_hivex_node_children
7148 struct guestfs_hivex_node_list *
7149 guestfs_hivex_node_children (guestfs_h *g,
7150 int64_t nodeh);
7151 Return the list of nodes which are subkeys of "nodeh".
7153 This is a wrapper around the hivex(3) call of the same name.
7155 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7157 there was an error. The caller must call
7158 "guestfs_free_hivex_node_list" after use.
7159 This function depends on the feature "hivex". See also
7161 "guestfs_feature_available".
7162 (Added in 1.19.35)
7164 guestfs_hivex_node_delete_child
7166 int
7167 guestfs_hivex_node_delete_child (guestfs_h *g,
7168 int64_t nodeh);
7169 Delete "nodeh", recursively if necessary.
7171 This is a wrapper around the hivex(3) call of the same name.
7173 This function returns 0 on success or -1 on error.
7175 This function depends on the feature "hivex". See also
7177 "guestfs_feature_available".
7178 (Added in 1.19.35)
7180 guestfs_hivex_node_get_child
7182 int64_t
7183 guestfs_hivex_node_get_child (guestfs_h *g,
7184 int64_t nodeh,
7185 const char *name);
7186 Return the child of "nodeh" with the name "name", if it exists. This
7188 can return 0 meaning the name was not found.
7189 This is a wrapper around the hivex(3) call of the same name.
7191 On error this function returns -1.
7193 This function depends on the feature "hivex". See also
7195 "guestfs_feature_available".
7196 (Added in 1.19.35)
7198 guestfs_hivex_node_get_value
7200 int64_t
7201 guestfs_hivex_node_get_value (guestfs_h *g,
7202 int64_t nodeh,
7203 const char *key);
7204 Return the value attached to "nodeh" which has the name "key", if it
7206 exists. This can return 0 meaning the key was not found.
7207 This is a wrapper around the hivex(3) call of the same name.
7209 On error this function returns -1.
7211 This function depends on the feature "hivex". See also
7213 "guestfs_feature_available".
7214 (Added in 1.19.35)
7216 guestfs_hivex_node_name
7218 char *
7219 guestfs_hivex_node_name (guestfs_h *g,
7220 int64_t nodeh);
7221 Return the name of "nodeh".
7223 This is a wrapper around the hivex(3) call of the same name.
7225 This function returns a string, or NULL on error. The caller must free
7227 the returned string after use.
7228 This function depends on the feature "hivex". See also
7230 "guestfs_feature_available".
7231 (Added in 1.19.35)
7233 guestfs_hivex_node_parent
7235 int64_t
7236 guestfs_hivex_node_parent (guestfs_h *g,
7237 int64_t nodeh);
7238 Return the parent node of "nodeh".
7240 This is a wrapper around the hivex(3) call of the same name.
7242 On error this function returns -1.
7244 This function depends on the feature "hivex". See also
7246 "guestfs_feature_available".
7247 (Added in 1.19.35)
7249 guestfs_hivex_node_set_value
7251 int
7252 guestfs_hivex_node_set_value (guestfs_h *g,
7253 int64_t nodeh,
7254 const char *key,
7255 int64_t t,
7256 const char *val,
7257 size_t val_size);
7258 Set or replace a single value under the node "nodeh". The "key" is the
7260 name, "t" is the type, and "val" is the data.
7261 This is a wrapper around the hivex(3) call of the same name.
7263 This function returns 0 on success or -1 on error.
7265 This function depends on the feature "hivex". See also
7267 "guestfs_feature_available".
7268 (Added in 1.19.35)
7270 guestfs_hivex_node_values
7272 struct guestfs_hivex_value_list *
7273 guestfs_hivex_node_values (guestfs_h *g,
7274 int64_t nodeh);
7275 Return the array of (key, datatype, data) tuples attached to "nodeh".
7277 This is a wrapper around the hivex(3) call of the same name.
7279 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7281 there was an error. The caller must call
7282 "guestfs_free_hivex_value_list" after use.
7283 This function depends on the feature "hivex". See also
7285 "guestfs_feature_available".
7286 (Added in 1.19.35)
7288 guestfs_hivex_open
7290 int
7291 guestfs_hivex_open (guestfs_h *g,
7292 const char *filename,
7293 ...);
7294 You may supply a list of optional arguments to this call. Use zero or
7296 more of the following pairs of parameters, and terminate the list with
7297 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7298 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7300 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7301 GUESTFS_HIVEX_OPEN_WRITE, int write,
7302 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7303 Open the Windows Registry hive file named filename. If there was any
7305 previous hivex handle associated with this guestfs session, then it is
7306 closed.
7307 This is a wrapper around the hivex(3) call of the same name.
7309 This function returns 0 on success or -1 on error.
7311 This function depends on the feature "hivex". See also
7313 "guestfs_feature_available".
7314 (Added in 1.19.35)
7316 guestfs_hivex_open_va
7318 int
7319 guestfs_hivex_open_va (guestfs_h *g,
7320 const char *filename,
7321 va_list args);
7322 This is the "va_list variant" of "guestfs_hivex_open".
7324 See "CALLS WITH OPTIONAL ARGUMENTS".
7326 guestfs_hivex_open_argv
7328 int
7329 guestfs_hivex_open_argv (guestfs_h *g,
7330 const char *filename,
7331 const struct guestfs_hivex_open_argv *optargs);
7332 This is the "argv variant" of "guestfs_hivex_open".
7334 See "CALLS WITH OPTIONAL ARGUMENTS".
7336 guestfs_hivex_root
7338 int64_t
7339 guestfs_hivex_root (guestfs_h *g);
7340 Return the root node of the hive.
7342 This is a wrapper around the hivex(3) call of the same name.
7344 On error this function returns -1.
7346 This function depends on the feature "hivex". See also
7348 "guestfs_feature_available".
7349 (Added in 1.19.35)
7351 guestfs_hivex_value_key
7353 char *
7354 guestfs_hivex_value_key (guestfs_h *g,
7355 int64_t valueh);
7356 Return the key (name) field of a (key, datatype, data) tuple.
7358 This is a wrapper around the hivex(3) call of the same name.
7360 This function returns a string, or NULL on error. The caller must free
7362 the returned string after use.
7363 This function depends on the feature "hivex". See also
7365 "guestfs_feature_available".
7366 (Added in 1.19.35)
7368 guestfs_hivex_value_string
7370 char *
7371 guestfs_hivex_value_string (guestfs_h *g,
7372 int64_t valueh);
7373 This calls "guestfs_hivex_value_value" (which returns the data field
7375 from a hivex value tuple). It then assumes that the field is a
7376 UTF-16LE string and converts the result to UTF-8 (or if this is not
7377 possible, it returns an error).
7378 This is useful for reading strings out of the Windows registry.
7380 However it is not foolproof because the registry is not strongly-typed
7381 and fields can contain arbitrary or unexpected data.
7382 This function returns a string, or NULL on error. The caller must free
7384 the returned string after use.
7385 This function depends on the feature "hivex". See also
7387 "guestfs_feature_available".
7388 (Added in 1.37.22)
7390 guestfs_hivex_value_type
7392 int64_t
7393 guestfs_hivex_value_type (guestfs_h *g,
7394 int64_t valueh);
7395 Return the data type field from a (key, datatype, data) tuple.
7397 This is a wrapper around the hivex(3) call of the same name.
7399 On error this function returns -1.
7401 This function depends on the feature "hivex". See also
7403 "guestfs_feature_available".
7404 (Added in 1.19.35)
7406 guestfs_hivex_value_utf8
7408 char *
7409 guestfs_hivex_value_utf8 (guestfs_h *g,
7410 int64_t valueh);
7411 This function is deprecated. In new code, use the
7413 "guestfs_hivex_value_string" call instead.
7414 Deprecated functions will not be removed from the API, but the fact
7416 that they are deprecated indicates that there are problems with correct
7417 use of these functions.
7418 This calls "guestfs_hivex_value_value" (which returns the data field
7420 from a hivex value tuple). It then assumes that the field is a
7421 UTF-16LE string and converts the result to UTF-8 (or if this is not
7422 possible, it returns an error).
7423 This is useful for reading strings out of the Windows registry.
7425 However it is not foolproof because the registry is not strongly-typed
7426 and fields can contain arbitrary or unexpected data.
7427 This function returns a string, or NULL on error. The caller must free
7429 the returned string after use.
7430 This function depends on the feature "hivex". See also
7432 "guestfs_feature_available".
7433 (Added in 1.19.35)
7435 guestfs_hivex_value_value
7437 char *
7438 guestfs_hivex_value_value (guestfs_h *g,
7439 int64_t valueh,
7440 size_t *size_r);
7441 Return the data field of a (key, datatype, data) tuple.
7443 This is a wrapper around the hivex(3) call of the same name.
7445 See also: "guestfs_hivex_value_utf8".
7447 This function returns a buffer, or NULL on error. The size of the
7449 returned buffer is written to *size_r. The caller must free the
7450 returned buffer after use.
7451 This function depends on the feature "hivex". See also
7453 "guestfs_feature_available".
7454 (Added in 1.19.35)
7456 guestfs_initrd_cat
7458 char *
7459 guestfs_initrd_cat (guestfs_h *g,
7460 const char *initrdpath,
7461 const char *filename,
7462 size_t *size_r);
7463 This command unpacks the file filename from the initrd file called
7465 initrdpath. The filename must be given without the initial /
7466 character.
7467 For example, in guestfish you could use the following command to
7469 examine the boot script (usually called /init) contained in a Linux
7470 initrd or initramfs image:
7471 initrd-cat /boot/initrd-<version>.img init
7473 See also "guestfs_initrd_list".
7475 This function returns a buffer, or NULL on error. The size of the
7477 returned buffer is written to *size_r. The caller must free the
7478 returned buffer after use.
7479 Because of the message protocol, there is a transfer limit of somewhere
7481 between 2MB and 4MB. See "PROTOCOL LIMITS".
7482 (Added in 1.0.84)
7484 guestfs_initrd_list
7486 char **
7487 guestfs_initrd_list (guestfs_h *g,
7488 const char *path);
7489 This command lists out files contained in an initrd.
7491 The files are listed without any initial / character. The files are
7493 listed in the order they appear (not necessarily alphabetical).
7494 Directory names are listed as separate items.
7495 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7497 as initrd. We only support the newer initramfs format (compressed cpio
7498 files).
7499 This function returns a NULL-terminated array of strings (like
7501 environ(3)), or NULL if there was an error. The caller must free the
7502 strings and the array after use.
7503 (Added in 1.0.54)
7505 guestfs_inotify_add_watch
7507 int64_t
7508 guestfs_inotify_add_watch (guestfs_h *g,
7509 const char *path,
7510 int mask);
7511 Watch "path" for the events listed in "mask".
7513 Note that if "path" is a directory then events within that directory
7515 are watched, but this does not happen recursively (in subdirectories).
7516 Note for non-C or non-Linux callers: the inotify events are defined by
7518 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7519 On error this function returns -1.
7521 This function depends on the feature "inotify". See also
7523 "guestfs_feature_available".
7524 (Added in 1.0.66)
7526 guestfs_inotify_close
7528 int
7529 guestfs_inotify_close (guestfs_h *g);
7530 This closes the inotify handle which was previously opened by
7532 inotify_init. It removes all watches, throws away any pending events,
7533 and deallocates all resources.
7534 This function returns 0 on success or -1 on error.
7536 This function depends on the feature "inotify". See also
7538 "guestfs_feature_available".
7539 (Added in 1.0.66)
7541 guestfs_inotify_files
7543 char **
7544 guestfs_inotify_files (guestfs_h *g);
7545 This function is a helpful wrapper around "guestfs_inotify_read" which
7547 just returns a list of pathnames of objects that were touched. The
7548 returned pathnames are sorted and deduplicated.
7549 This function returns a NULL-terminated array of strings (like
7551 environ(3)), or NULL if there was an error. The caller must free the
7552 strings and the array after use.
7553 This function depends on the feature "inotify". See also
7555 "guestfs_feature_available".
7556 (Added in 1.0.66)
7558 guestfs_inotify_init
7560 int
7561 guestfs_inotify_init (guestfs_h *g,
7562 int maxevents);
7563 This command creates a new inotify handle. The inotify subsystem can
7565 be used to notify events which happen to objects in the guest
7566 filesystem.
7567 "maxevents" is the maximum number of events which will be queued up
7569 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7570 this is passed as 0, then the kernel (or previously set) default is
7571 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7572 limit, the kernel throws away events, but records the fact that it
7573 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7574 structure list (see "guestfs_inotify_read").
7575 Before any events are generated, you have to add some watches to the
7577 internal watch list. See: "guestfs_inotify_add_watch" and
7578 "guestfs_inotify_rm_watch".
7579 Queued up events should be read periodically by calling
7581 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7582 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7583 events out often enough then you risk the internal queue overflowing.
7584 The handle should be closed after use by calling
7586 "guestfs_inotify_close". This also removes any watches automatically.
7587 See also inotify(7) for an overview of the inotify interface as exposed
7589 by the Linux kernel, which is roughly what we expose via libguestfs.
7590 Note that there is one global inotify handle per libguestfs instance.
7591 This function returns 0 on success or -1 on error.
7593 This function depends on the feature "inotify". See also
7595 "guestfs_feature_available".
7596 (Added in 1.0.66)
7598 guestfs_inotify_read
7600 struct guestfs_inotify_event_list *
7601 guestfs_inotify_read (guestfs_h *g);
7602 Return the complete queue of events that have happened since the
7604 previous read call.
7605 If no events have happened, this returns an empty list.
7607 Note: In order to make sure that all events have been read, you must
7609 call this function repeatedly until it returns an empty list. The
7610 reason is that the call will read events up to the maximum appliance-
7611 to-host message size and leave remaining events in the queue.
7612 This function returns a "struct guestfs_inotify_event_list *", or NULL
7614 if there was an error. The caller must call
7615 "guestfs_free_inotify_event_list" after use.
7616 This function depends on the feature "inotify". See also
7618 "guestfs_feature_available".
7619 (Added in 1.0.66)
7621 guestfs_inotify_rm_watch
7623 int
7624 guestfs_inotify_rm_watch (guestfs_h *g,
7625 int wd);
7626 Remove a previously defined inotify watch. See
7628 "guestfs_inotify_add_watch".
7629 This function returns 0 on success or -1 on error.
7631 This function depends on the feature "inotify". See also
7633 "guestfs_feature_available".
7634 (Added in 1.0.66)
7636 guestfs_inspect_get_arch
7638 char *
7639 guestfs_inspect_get_arch (guestfs_h *g,
7640 const char *root);
7641 This returns the architecture of the inspected operating system. The
7643 possible return values are listed under "guestfs_file_architecture".
7644 If the architecture could not be determined, then the string "unknown"
7646 is returned.
7647 Please read "INSPECTION" for more details.
7649 This function returns a string, or NULL on error. The caller must free
7651 the returned string after use.
7652 (Added in 1.5.3)
7654 guestfs_inspect_get_distro
7656 char *
7657 guestfs_inspect_get_distro (guestfs_h *g,
7658 const char *root);
7659 This returns the distro (distribution) of the inspected operating
7661 system.
7662 Currently defined distros are:
7664 "alpinelinux"
7666 Alpine Linux.
7667 "altlinux"
7669 ALT Linux.
7670 "archlinux"
7672 Arch Linux.
7673 "buildroot"
7675 Buildroot-derived distro, but not one we specifically recognize.
7676 "centos"
7678 CentOS.
7679 "cirros"
7681 Cirros.
7682 "coreos"
7684 CoreOS.
7685 "debian"
7687 Debian.
7688 "fedora"
7690 Fedora.
7691 "freebsd"
7693 FreeBSD.
7694 "freedos"
7696 FreeDOS.
7697 "frugalware"
7699 Frugalware.
7700 "gentoo"
7702 Gentoo.
7703 "kalilinux"
7705 Kali Linux.
7706 "kylin"
7708 Kylin.
7709 "linuxmint"
7711 Linux Mint.
7712 "mageia"
7714 Mageia.
7715 "mandriva"
7717 Mandriva.
7718 "meego"
7720 MeeGo.
7721 "msdos"
7723 Microsoft DOS.
7724 "neokylin"
7726 NeoKylin.
7727 "netbsd"
7729 NetBSD.
7730 "openbsd"
7732 OpenBSD.
7733 "openmandriva"
7735 OpenMandriva Lx.
7736 "opensuse"
7738 OpenSUSE.
7739 "oraclelinux"
7741 Oracle Linux.
7742 "pardus"
7744 Pardus.
7745 "pldlinux"
7747 PLD Linux.
7748 "redhat-based"
7750 Some Red Hat-derived distro.
7751 "rhel"
7753 Red Hat Enterprise Linux.
7754 "rocky"
7756 Rocky Linux.
7757 "scientificlinux"
7759 Scientific Linux.
7760 "slackware"
7762 Slackware.
7763 "sles"
7765 SuSE Linux Enterprise Server or Desktop.
7766 "suse-based"
7768 Some openSuSE-derived distro.
7769 "ttylinux"
7771 ttylinux.
7772 "ubuntu"
7774 Ubuntu.
7775 "unknown"
7777 The distro could not be determined.
7778 "voidlinux"
7780 Void Linux.
7781 "windows"
7783 Windows does not have distributions. This string is returned if
7784 the OS type is Windows.
7785 Future versions of libguestfs may return other strings here. The
7787 caller should be prepared to handle any string.
7788 Please read "INSPECTION" for more details.
7790 This function returns a string, or NULL on error. The caller must free
7792 the returned string after use.
7793 (Added in 1.5.3)
7795 guestfs_inspect_get_drive_mappings
7797 char **
7798 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7799 const char *root);
7800 This call is useful for Windows which uses a primitive system of
7802 assigning drive letters (like C:\) to partitions. This inspection API
7803 examines the Windows Registry to find out how disks/partitions are
7804 mapped to drive letters, and returns a hash table as in the example
7805 below:
7806 C => /dev/vda2
7808 E => /dev/vdb1
7809 F => /dev/vdc1
7810 Note that keys are drive letters. For Windows, the key is case
7812 insensitive and just contains the drive letter, without the customary
7813 colon separator character.
7814 In future we may support other operating systems that also used drive
7816 letters, but the keys for those might not be case insensitive and might
7817 be longer than 1 character. For example in OS-9, hard drives were
7818 named "h0", "h1" etc.
7819 For Windows guests, currently only hard drive mappings are returned.
7821 Removable disks (eg. DVD-ROMs) are ignored.
7822 For guests that do not use drive mappings, or if the drive mappings
7824 could not be determined, this returns an empty hash table.
7825 Please read "INSPECTION" for more details. See also
7827 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7828 This function returns a NULL-terminated array of strings, or NULL if
7830 there was an error. The array of strings will always have length
7831 "2n+1", where "n" keys and values alternate, followed by the trailing
7832 NULL entry. The caller must free the strings and the array after use.
7833 (Added in 1.9.17)
7835 guestfs_inspect_get_filesystems
7837 char **
7838 guestfs_inspect_get_filesystems (guestfs_h *g,
7839 const char *root);
7840 This returns a list of all the filesystems that we think are associated
7842 with this operating system. This includes the root filesystem, other
7843 ordinary filesystems, and non-mounted devices like swap partitions.
7844 In the case of a multi-boot virtual machine, it is possible for a
7846 filesystem to be shared between operating systems.
7847 Please read "INSPECTION" for more details. See also
7849 "guestfs_inspect_get_mountpoints".
7850 This function returns a NULL-terminated array of strings (like
7852 environ(3)), or NULL if there was an error. The caller must free the
7853 strings and the array after use.
7854 (Added in 1.5.3)
7856 guestfs_inspect_get_format
7858 char *
7859 guestfs_inspect_get_format (guestfs_h *g,
7860 const char *root);
7861 This function is deprecated. There is no replacement. Consult the API
7863 documentation in guestfs(3) for further information.
7864 Deprecated functions will not be removed from the API, but the fact
7866 that they are deprecated indicates that there are problems with correct
7867 use of these functions.
7868 Before libguestfs 1.38, there was some unreliable support for detecting
7870 installer CDs. This API would return:
7871 "installed"
7873 This is an installed operating system.
7874 "installer"
7876 The disk image being inspected is not an installed operating
7877 system, but a bootable install disk, live CD, or similar.
7878 "unknown"
7880 The format of this disk image is not known.
7881 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
7883 directly to detect installer CDs.
7884 Please read "INSPECTION" for more details.
7886 This function returns a string, or NULL on error. The caller must free
7888 the returned string after use.
7889 (Added in 1.9.4)
7891 guestfs_inspect_get_hostname
7893 char *
7894 guestfs_inspect_get_hostname (guestfs_h *g,
7895 const char *root);
7896 This function returns the hostname of the operating system as found by
7898 inspection of the guest’s configuration files.
7899 If the hostname could not be determined, then the string "unknown" is
7901 returned.
7902 Please read "INSPECTION" for more details.
7904 This function returns a string, or NULL on error. The caller must free
7906 the returned string after use.
7907 (Added in 1.7.9)
7909 guestfs_inspect_get_icon
7911 char *
7912 guestfs_inspect_get_icon (guestfs_h *g,
7913 const char *root,
7914 size_t *size_r,
7915 ...);
7916 You may supply a list of optional arguments to this call. Use zero or
7918 more of the following pairs of parameters, and terminate the list with
7919 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7920 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
7922 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
7923 This function returns an icon corresponding to the inspected operating
7925 system. The icon is returned as a buffer containing a PNG image (re-
7926 encoded to PNG if necessary).
7927 If it was not possible to get an icon this function returns a zero-
7929 length (non-NULL) buffer. Callers must check for this case.
7930 Libguestfs will start by looking for a file called /etc/favicon.png or
7932 C:\etc\favicon.png and if it has the correct format, the contents of
7933 this file will be returned. You can disable favicons by passing the
7934 optional "favicon" boolean as false (default is true).
7935 If finding the favicon fails, then we look in other places in the guest
7937 for a suitable icon.
7938 If the optional "highquality" boolean is true then only high quality
7940 icons are returned, which means only icons of high resolution with an
7941 alpha channel. The default (false) is to return any icon we can, even
7942 if it is of substandard quality.
7943 Notes:
7945 • Unlike most other inspection API calls, the guest’s disks must be
7947 mounted up before you call this, since it needs to read information
7948 from the guest filesystem during the call.
7949 • Security: The icon data comes from the untrusted guest, and should
7951 be treated with caution. PNG files have been known to contain
7952 exploits. Ensure that libpng (or other relevant libraries) are
7953 fully up to date before trying to process or display the icon.
7954 • The PNG image returned can be any size. It might not be square.
7956 Libguestfs tries to return the largest, highest quality icon
7957 available. The application must scale the icon to the required
7958 size.
7959 • Extracting icons from Windows guests requires the external
7961 wrestool(1) program from the "icoutils" package, and several
7962 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
7963 package. These must be installed separately.
7964 • Operating system icons are usually trademarks. Seek legal advice
7966 before using trademarks in applications.
7967 This function returns a buffer, or NULL on error. The size of the
7969 returned buffer is written to *size_r. The caller must free the
7970 returned buffer after use.
7971 (Added in 1.11.12)
7973 guestfs_inspect_get_icon_va
7975 char *
7976 guestfs_inspect_get_icon_va (guestfs_h *g,
7977 const char *root,
7978 size_t *size_r,
7979 va_list args);
7980 This is the "va_list variant" of "guestfs_inspect_get_icon".
7982 See "CALLS WITH OPTIONAL ARGUMENTS".
7984 guestfs_inspect_get_icon_argv
7986 char *
7987 guestfs_inspect_get_icon_argv (guestfs_h *g,
7988 const char *root,
7989 size_t *size_r,
7990 const struct guestfs_inspect_get_icon_argv *optargs);
7991 This is the "argv variant" of "guestfs_inspect_get_icon".
7993 See "CALLS WITH OPTIONAL ARGUMENTS".
7995 guestfs_inspect_get_major_version
7997 int
7998 guestfs_inspect_get_major_version (guestfs_h *g,
7999 const char *root);
8000 This returns the major version number of the inspected operating
8002 system.
8003 Windows uses a consistent versioning scheme which is not reflected in
8005 the popular public names used by the operating system. Notably the
8006 operating system known as "Windows 7" is really version 6.1 (ie. major
8007 = 6, minor = 1). You can find out the real versions corresponding to
8008 releases of Windows by consulting Wikipedia or MSDN.
8009 If the version could not be determined, then 0 is returned.
8011 Please read "INSPECTION" for more details.
8013 On error this function returns -1.
8015 (Added in 1.5.3)
8017 guestfs_inspect_get_minor_version
8019 int
8020 guestfs_inspect_get_minor_version (guestfs_h *g,
8021 const char *root);
8022 This returns the minor version number of the inspected operating
8024 system.
8025 If the version could not be determined, then 0 is returned.
8027 Please read "INSPECTION" for more details. See also
8029 "guestfs_inspect_get_major_version".
8030 On error this function returns -1.
8032 (Added in 1.5.3)
8034 guestfs_inspect_get_mountpoints
8036 char **
8037 guestfs_inspect_get_mountpoints (guestfs_h *g,
8038 const char *root);
8039 This returns a hash of where we think the filesystems associated with
8041 this operating system should be mounted. Callers should note that this
8042 is at best an educated guess made by reading configuration files such
8043 as /etc/fstab. In particular note that this may return filesystems
8044 which are non-existent or not mountable and callers should be prepared
8045 to handle or ignore failures if they try to mount them.
8046 Each element in the returned hashtable has a key which is the path of
8048 the mountpoint (eg. /boot) and a value which is the filesystem that
8049 would be mounted there (eg. /dev/sda1).
8050 Non-mounted devices such as swap devices are not returned in this list.
8052 For operating systems like Windows which still use drive letters, this
8054 call will only return an entry for the first drive "mounted on" /. For
8055 information about the mapping of drive letters to partitions, see
8056 "guestfs_inspect_get_drive_mappings".
8057 Please read "INSPECTION" for more details. See also
8059 "guestfs_inspect_get_filesystems".
8060 This function returns a NULL-terminated array of strings, or NULL if
8062 there was an error. The array of strings will always have length
8063 "2n+1", where "n" keys and values alternate, followed by the trailing
8064 NULL entry. The caller must free the strings and the array after use.
8065 (Added in 1.5.3)
8067 guestfs_inspect_get_osinfo
8069 char *
8070 guestfs_inspect_get_osinfo (guestfs_h *g,
8071 const char *root);
8072 This function returns a possible short ID for libosinfo corresponding
8074 to the guest.
8075 Note: The returned ID is only a guess by libguestfs, and nothing
8077 ensures that it actually exists in osinfo-db.
8078 If no ID could not be determined, then the string "unknown" is
8080 returned.
8081 This function returns a string, or NULL on error. The caller must free
8083 the returned string after use.
8084 (Added in 1.39.1)
8086 guestfs_inspect_get_package_format
8088 char *
8089 guestfs_inspect_get_package_format (guestfs_h *g,
8090 const char *root);
8091 This function and "guestfs_inspect_get_package_management" return the
8093 package format and package management tool used by the inspected
8094 operating system. For example for Fedora these functions would return
8095 "rpm" (package format), and "yum" or "dnf" (package management).
8096 This returns the string "unknown" if we could not determine the package
8098 format or if the operating system does not have a real packaging system
8099 (eg. Windows).
8100 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8102 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
8103 other strings.
8104 Please read "INSPECTION" for more details.
8106 This function returns a string, or NULL on error. The caller must free
8108 the returned string after use.
8109 (Added in 1.7.5)
8111 guestfs_inspect_get_package_management
8113 char *
8114 guestfs_inspect_get_package_management (guestfs_h *g,
8115 const char *root);
8116 "guestfs_inspect_get_package_format" and this function return the
8118 package format and package management tool used by the inspected
8119 operating system. For example for Fedora these functions would return
8120 "rpm" (package format), and "yum" or "dnf" (package management).
8121 This returns the string "unknown" if we could not determine the package
8123 management tool or if the operating system does not have a real
8124 packaging system (eg. Windows).
8125 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8127 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8128 "apk", "xbps". Future versions of libguestfs may return other strings.
8129 Please read "INSPECTION" for more details.
8131 This function returns a string, or NULL on error. The caller must free
8133 the returned string after use.
8134 (Added in 1.7.5)
8136 guestfs_inspect_get_product_name
8138 char *
8139 guestfs_inspect_get_product_name (guestfs_h *g,
8140 const char *root);
8141 This returns the product name of the inspected operating system. The
8143 product name is generally some freeform string which can be displayed
8144 to the user, but should not be parsed by programs.
8145 If the product name could not be determined, then the string "unknown"
8147 is returned.
8148 Please read "INSPECTION" for more details.
8150 This function returns a string, or NULL on error. The caller must free
8152 the returned string after use.
8153 (Added in 1.5.3)
8155 guestfs_inspect_get_product_variant
8157 char *
8158 guestfs_inspect_get_product_variant (guestfs_h *g,
8159 const char *root);
8160 This returns the product variant of the inspected operating system.
8162 For Windows guests, this returns the contents of the Registry key
8164 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8165 which is usually a string such as "Client" or "Server" (other values
8166 are possible). This can be used to distinguish consumer and enterprise
8167 versions of Windows that have the same version number (for example,
8168 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8169 is "Client" and the latter is "Server").
8170 For enterprise Linux guests, in future we intend this to return the
8172 product variant such as "Desktop", "Server" and so on. But this is not
8173 implemented at present.
8174 If the product variant could not be determined, then the string
8176 "unknown" is returned.
8177 Please read "INSPECTION" for more details. See also
8179 "guestfs_inspect_get_product_name",
8180 "guestfs_inspect_get_major_version".
8181 This function returns a string, or NULL on error. The caller must free
8183 the returned string after use.
8184 (Added in 1.9.13)
8186 guestfs_inspect_get_roots
8188 char **
8189 guestfs_inspect_get_roots (guestfs_h *g);
8190 This function is a convenient way to get the list of root devices, as
8192 returned from a previous call to "guestfs_inspect_os", but without
8193 redoing the whole inspection process.
8194 This returns an empty list if either no root devices were found or the
8196 caller has not called "guestfs_inspect_os".
8197 Please read "INSPECTION" for more details.
8199 This function returns a NULL-terminated array of strings (like
8201 environ(3)), or NULL if there was an error. The caller must free the
8202 strings and the array after use.
8203 (Added in 1.7.3)
8205 guestfs_inspect_get_type
8207 char *
8208 guestfs_inspect_get_type (guestfs_h *g,
8209 const char *root);
8210 This returns the type of the inspected operating system. Currently
8212 defined types are:
8213 "linux"
8215 Any Linux-based operating system.
8216 "windows"
8218 Any Microsoft Windows operating system.
8219 "freebsd"
8221 FreeBSD.
8222 "netbsd"
8224 NetBSD.
8225 "openbsd"
8227 OpenBSD.
8228 "hurd"
8230 GNU/Hurd.
8231 "dos"
8233 MS-DOS, FreeDOS and others.
8234 "minix"
8236 MINIX.
8237 "unknown"
8239 The operating system type could not be determined.
8240 Future versions of libguestfs may return other strings here. The
8242 caller should be prepared to handle any string.
8243 Please read "INSPECTION" for more details.
8245 This function returns a string, or NULL on error. The caller must free
8247 the returned string after use.
8248 (Added in 1.5.3)
8250 guestfs_inspect_get_windows_current_control_set
8252 char *
8253 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8254 const char *root);
8255 This returns the Windows CurrentControlSet of the inspected guest. The
8257 CurrentControlSet is a registry key name such as "ControlSet001".
8258 This call assumes that the guest is Windows and that the Registry could
8260 be examined by inspection. If this is not the case then an error is
8261 returned.
8262 Please read "INSPECTION" for more details.
8264 This function returns a string, or NULL on error. The caller must free
8266 the returned string after use.
8267 (Added in 1.9.17)
8269 guestfs_inspect_get_windows_software_hive
8271 char *
8272 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8273 const char *root);
8274 This returns the path to the hive (binary Windows Registry file)
8276 corresponding to HKLM\SOFTWARE.
8277 This call assumes that the guest is Windows and that the guest has a
8279 software hive file with the right name. If this is not the case then
8280 an error is returned. This call does not check that the hive is a
8281 valid Windows Registry hive.
8282 You can use "guestfs_hivex_open" to read or write to the hive.
8284 Please read "INSPECTION" for more details.
8286 This function returns a string, or NULL on error. The caller must free
8288 the returned string after use.
8289 (Added in 1.35.26)
8291 guestfs_inspect_get_windows_system_hive
8293 char *
8294 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8295 const char *root);
8296 This returns the path to the hive (binary Windows Registry file)
8298 corresponding to HKLM\SYSTEM.
8299 This call assumes that the guest is Windows and that the guest has a
8301 system hive file with the right name. If this is not the case then an
8302 error is returned. This call does not check that the hive is a valid
8303 Windows Registry hive.
8304 You can use "guestfs_hivex_open" to read or write to the hive.
8306 Please read "INSPECTION" for more details.
8308 This function returns a string, or NULL on error. The caller must free
8310 the returned string after use.
8311 (Added in 1.35.26)
8313 guestfs_inspect_get_windows_systemroot
8315 char *
8316 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8317 const char *root);
8318 This returns the Windows systemroot of the inspected guest. The
8320 systemroot is a directory path such as /WINDOWS.
8321 This call assumes that the guest is Windows and that the systemroot
8323 could be determined by inspection. If this is not the case then an
8324 error is returned.
8325 Please read "INSPECTION" for more details.
8327 This function returns a string, or NULL on error. The caller must free
8329 the returned string after use.
8330 (Added in 1.5.25)
8332 guestfs_inspect_is_live
8334 int
8335 guestfs_inspect_is_live (guestfs_h *g,
8336 const char *root);
8337 This function is deprecated. There is no replacement. Consult the API
8339 documentation in guestfs(3) for further information.
8340 Deprecated functions will not be removed from the API, but the fact
8342 that they are deprecated indicates that there are problems with correct
8343 use of these functions.
8344 This is deprecated and always returns "false".
8346 Please read "INSPECTION" for more details.
8348 This function returns a C truth value on success or -1 on error.
8350 (Added in 1.9.4)
8352 guestfs_inspect_is_multipart
8354 int
8355 guestfs_inspect_is_multipart (guestfs_h *g,
8356 const char *root);
8357 This function is deprecated. There is no replacement. Consult the API
8359 documentation in guestfs(3) for further information.
8360 Deprecated functions will not be removed from the API, but the fact
8362 that they are deprecated indicates that there are problems with correct
8363 use of these functions.
8364 This is deprecated and always returns "false".
8366 Please read "INSPECTION" for more details.
8368 This function returns a C truth value on success or -1 on error.
8370 (Added in 1.9.4)
8372 guestfs_inspect_is_netinst
8374 int
8375 guestfs_inspect_is_netinst (guestfs_h *g,
8376 const char *root);
8377 This function is deprecated. There is no replacement. Consult the API
8379 documentation in guestfs(3) for further information.
8380 Deprecated functions will not be removed from the API, but the fact
8382 that they are deprecated indicates that there are problems with correct
8383 use of these functions.
8384 This is deprecated and always returns "false".
8386 Please read "INSPECTION" for more details.
8388 This function returns a C truth value on success or -1 on error.
8390 (Added in 1.9.4)
8392 guestfs_inspect_list_applications
8394 struct guestfs_application_list *
8395 guestfs_inspect_list_applications (guestfs_h *g,
8396 const char *root);
8397 This function is deprecated. In new code, use the
8399 "guestfs_inspect_list_applications2" call instead.
8400 Deprecated functions will not be removed from the API, but the fact
8402 that they are deprecated indicates that there are problems with correct
8403 use of these functions.
8404 Return the list of applications installed in the operating system.
8406 Note: This call works differently from other parts of the inspection
8408 API. You have to call "guestfs_inspect_os", then
8409 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8410 calling this. Listing applications is a significantly more difficult
8411 operation which requires access to the full filesystem. Also note that
8412 unlike the other "guestfs_inspect_get_*" calls which are just returning
8413 data cached in the libguestfs handle, this call actually reads parts of
8414 the mounted filesystems during the call.
8415 This returns an empty list if the inspection code was not able to
8417 determine the list of applications.
8418 The application structure contains the following fields:
8420 "app_name"
8422 The name of the application. For Linux guests, this is the package
8423 name.
8424 "app_display_name"
8426 The display name of the application, sometimes localized to the
8427 install language of the guest operating system.
8428 If unavailable this is returned as an empty string "". Callers
8430 needing to display something can use "app_name" instead.
8431 "app_epoch"
8433 For package managers which use epochs, this contains the epoch of
8434 the package (an integer). If unavailable, this is returned as 0.
8435 "app_version"
8437 The version string of the application or package. If unavailable
8438 this is returned as an empty string "".
8439 "app_release"
8441 The release string of the application or package, for package
8442 managers that use this. If unavailable this is returned as an
8443 empty string "".
8444 "app_install_path"
8446 The installation path of the application (on operating systems such
8447 as Windows which use installation paths). This path is in the
8448 format used by the guest operating system, it is not a libguestfs
8449 path.
8450 If unavailable this is returned as an empty string "".
8452 "app_trans_path"
8454 The install path translated into a libguestfs path. If unavailable
8455 this is returned as an empty string "".
8456 "app_publisher"
8458 The name of the publisher of the application, for package managers
8459 that use this. If unavailable this is returned as an empty string
8460 "".
8461 "app_url"
8463 The URL (eg. upstream URL) of the application. If unavailable this
8464 is returned as an empty string "".
8465 "app_source_package"
8467 For packaging systems which support this, the name of the source
8468 package. If unavailable this is returned as an empty string "".
8469 "app_summary"
8471 A short (usually one line) description of the application or
8472 package. If unavailable this is returned as an empty string "".
8473 "app_description"
8475 A longer description of the application or package. If unavailable
8476 this is returned as an empty string "".
8477 Please read "INSPECTION" for more details.
8479 This function returns a "struct guestfs_application_list *", or NULL if
8481 there was an error. The caller must call
8482 "guestfs_free_application_list" after use.
8483 (Added in 1.7.8)
8485 guestfs_inspect_list_applications2
8487 struct guestfs_application2_list *
8488 guestfs_inspect_list_applications2 (guestfs_h *g,
8489 const char *root);
8490 Return the list of applications installed in the operating system.
8492 Note: This call works differently from other parts of the inspection
8494 API. You have to call "guestfs_inspect_os", then
8495 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8496 calling this. Listing applications is a significantly more difficult
8497 operation which requires access to the full filesystem. Also note that
8498 unlike the other "guestfs_inspect_get_*" calls which are just returning
8499 data cached in the libguestfs handle, this call actually reads parts of
8500 the mounted filesystems during the call.
8501 This returns an empty list if the inspection code was not able to
8503 determine the list of applications.
8504 The application structure contains the following fields:
8506 "app2_name"
8508 The name of the application. For Linux guests, this is the package
8509 name.
8510 "app2_display_name"
8512 The display name of the application, sometimes localized to the
8513 install language of the guest operating system.
8514 If unavailable this is returned as an empty string "". Callers
8516 needing to display something can use "app2_name" instead.
8517 "app2_epoch"
8519 For package managers which use epochs, this contains the epoch of
8520 the package (an integer). If unavailable, this is returned as 0.
8521 "app2_version"
8523 The version string of the application or package. If unavailable
8524 this is returned as an empty string "".
8525 "app2_release"
8527 The release string of the application or package, for package
8528 managers that use this. If unavailable this is returned as an
8529 empty string "".
8530 "app2_arch"
8532 The architecture string of the application or package, for package
8533 managers that use this. If unavailable this is returned as an
8534 empty string "".
8535 "app2_install_path"
8537 The installation path of the application (on operating systems such
8538 as Windows which use installation paths). This path is in the
8539 format used by the guest operating system, it is not a libguestfs
8540 path.
8541 If unavailable this is returned as an empty string "".
8543 "app2_trans_path"
8545 The install path translated into a libguestfs path. If unavailable
8546 this is returned as an empty string "".
8547 "app2_publisher"
8549 The name of the publisher of the application, for package managers
8550 that use this. If unavailable this is returned as an empty string
8551 "".
8552 "app2_url"
8554 The URL (eg. upstream URL) of the application. If unavailable this
8555 is returned as an empty string "".
8556 "app2_source_package"
8558 For packaging systems which support this, the name of the source
8559 package. If unavailable this is returned as an empty string "".
8560 "app2_summary"
8562 A short (usually one line) description of the application or
8563 package. If unavailable this is returned as an empty string "".
8564 "app2_description"
8566 A longer description of the application or package. If unavailable
8567 this is returned as an empty string "".
8568 Please read "INSPECTION" for more details.
8570 This function returns a "struct guestfs_application2_list *", or NULL
8572 if there was an error. The caller must call
8573 "guestfs_free_application2_list" after use.
8574 (Added in 1.19.56)
8576 guestfs_inspect_os
8578 char **
8579 guestfs_inspect_os (guestfs_h *g);
8580 This function uses other libguestfs functions and certain heuristics to
8582 inspect the disk(s) (usually disks belonging to a virtual machine),
8583 looking for operating systems.
8584 The list returned is empty if no operating systems were found.
8586 If one operating system was found, then this returns a list with a
8588 single element, which is the name of the root filesystem of this
8589 operating system. It is also possible for this function to return a
8590 list containing more than one element, indicating a dual-boot or multi-
8591 boot virtual machine, with each element being the root filesystem of
8592 one of the operating systems.
8593 You can pass the root string(s) returned to other
8595 "guestfs_inspect_get_*" functions in order to query further information
8596 about each operating system, such as the name and version.
8597 This function uses other libguestfs features such as "guestfs_mount_ro"
8599 and "guestfs_umount_all" in order to mount and unmount filesystems and
8600 look at the contents. This should be called with no disks currently
8601 mounted. The function may also use Augeas, so any existing Augeas
8602 handle will be closed.
8603 This function cannot decrypt encrypted disks. The caller must do that
8605 first (supplying the necessary keys) if the disk is encrypted.
8606 Please read "INSPECTION" for more details.
8608 See also "guestfs_list_filesystems".
8610 This function returns a NULL-terminated array of strings (like
8612 environ(3)), or NULL if there was an error. The caller must free the
8613 strings and the array after use.
8614 (Added in 1.5.3)
8616 guestfs_is_blockdev
8618 int
8619 guestfs_is_blockdev (guestfs_h *g,
8620 const char *path);
8621 This function is provided for backwards compatibility with earlier
8623 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8624 with no optional arguments.
8625 (Added in 1.5.10)
8627 guestfs_is_blockdev_opts
8629 int
8630 guestfs_is_blockdev_opts (guestfs_h *g,
8631 const char *path,
8632 ...);
8633 You may supply a list of optional arguments to this call. Use zero or
8635 more of the following pairs of parameters, and terminate the list with
8636 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8637 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8639 This returns "true" if and only if there is a block device with the
8641 given "path" name.
8642 If the optional flag "followsymlinks" is true, then a symlink (or chain
8644 of symlinks) that ends with a block device also causes the function to
8645 return true.
8646 This call only looks at files within the guest filesystem. Libguestfs
8648 partitions and block devices (eg. /dev/sda) cannot be used as the
8649 "path" parameter of this call.
8650 See also "guestfs_stat".
8652 This function returns a C truth value on success or -1 on error.
8654 (Added in 1.5.10)
8656 guestfs_is_blockdev_opts_va
8658 int
8659 guestfs_is_blockdev_opts_va (guestfs_h *g,
8660 const char *path,
8661 va_list args);
8662 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8664 See "CALLS WITH OPTIONAL ARGUMENTS".
8666 guestfs_is_blockdev_opts_argv
8668 int
8669 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8670 const char *path,
8671 const struct guestfs_is_blockdev_opts_argv *optargs);
8672 This is the "argv variant" of "guestfs_is_blockdev_opts".
8674 See "CALLS WITH OPTIONAL ARGUMENTS".
8676 guestfs_is_busy
8678 int
8679 guestfs_is_busy (guestfs_h *g);
8680 This always returns false. This function is deprecated with no
8682 replacement. Do not use this function.
8683 For more information on states, see guestfs(3).
8685 This function returns a C truth value on success or -1 on error.
8687 (Added in 1.0.2)
8689 guestfs_is_chardev
8691 int
8692 guestfs_is_chardev (guestfs_h *g,
8693 const char *path);
8694 This function is provided for backwards compatibility with earlier
8696 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8697 no optional arguments.
8698 (Added in 1.5.10)
8700 guestfs_is_chardev_opts
8702 int
8703 guestfs_is_chardev_opts (guestfs_h *g,
8704 const char *path,
8705 ...);
8706 You may supply a list of optional arguments to this call. Use zero or
8708 more of the following pairs of parameters, and terminate the list with
8709 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8710 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8712 This returns "true" if and only if there is a character device with the
8714 given "path" name.
8715 If the optional flag "followsymlinks" is true, then a symlink (or chain
8717 of symlinks) that ends with a chardev also causes the function to
8718 return true.
8719 See also "guestfs_stat".
8721 This function returns a C truth value on success or -1 on error.
8723 (Added in 1.5.10)
8725 guestfs_is_chardev_opts_va
8727 int
8728 guestfs_is_chardev_opts_va (guestfs_h *g,
8729 const char *path,
8730 va_list args);
8731 This is the "va_list variant" of "guestfs_is_chardev_opts".
8733 See "CALLS WITH OPTIONAL ARGUMENTS".
8735 guestfs_is_chardev_opts_argv
8737 int
8738 guestfs_is_chardev_opts_argv (guestfs_h *g,
8739 const char *path,
8740 const struct guestfs_is_chardev_opts_argv *optargs);
8741 This is the "argv variant" of "guestfs_is_chardev_opts".
8743 See "CALLS WITH OPTIONAL ARGUMENTS".
8745 guestfs_is_config
8747 int
8748 guestfs_is_config (guestfs_h *g);
8749 This returns true iff this handle is being configured (in the "CONFIG"
8751 state).
8752 For more information on states, see guestfs(3).
8754 This function returns a C truth value on success or -1 on error.
8756 (Added in 1.0.2)
8758 guestfs_is_dir
8760 int
8761 guestfs_is_dir (guestfs_h *g,
8762 const char *path);
8763 This function is provided for backwards compatibility with earlier
8765 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8766 optional arguments.
8767 (Added in 0.8)
8769 guestfs_is_dir_opts
8771 int
8772 guestfs_is_dir_opts (guestfs_h *g,
8773 const char *path,
8774 ...);
8775 You may supply a list of optional arguments to this call. Use zero or
8777 more of the following pairs of parameters, and terminate the list with
8778 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8779 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8781 This returns "true" if and only if there is a directory with the given
8783 "path" name. Note that it returns false for other objects like files.
8784 If the optional flag "followsymlinks" is true, then a symlink (or chain
8786 of symlinks) that ends with a directory also causes the function to
8787 return true.
8788 See also "guestfs_stat".
8790 This function returns a C truth value on success or -1 on error.
8792 (Added in 0.8)
8794 guestfs_is_dir_opts_va
8796 int
8797 guestfs_is_dir_opts_va (guestfs_h *g,
8798 const char *path,
8799 va_list args);
8800 This is the "va_list variant" of "guestfs_is_dir_opts".
8802 See "CALLS WITH OPTIONAL ARGUMENTS".
8804 guestfs_is_dir_opts_argv
8806 int
8807 guestfs_is_dir_opts_argv (guestfs_h *g,
8808 const char *path,
8809 const struct guestfs_is_dir_opts_argv *optargs);
8810 This is the "argv variant" of "guestfs_is_dir_opts".
8812 See "CALLS WITH OPTIONAL ARGUMENTS".
8814 guestfs_is_fifo
8816 int
8817 guestfs_is_fifo (guestfs_h *g,
8818 const char *path);
8819 This function is provided for backwards compatibility with earlier
8821 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8822 optional arguments.
8823 (Added in 1.5.10)
8825 guestfs_is_fifo_opts
8827 int
8828 guestfs_is_fifo_opts (guestfs_h *g,
8829 const char *path,
8830 ...);
8831 You may supply a list of optional arguments to this call. Use zero or
8833 more of the following pairs of parameters, and terminate the list with
8834 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8835 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8837 This returns "true" if and only if there is a FIFO (named pipe) with
8839 the given "path" name.
8840 If the optional flag "followsymlinks" is true, then a symlink (or chain
8842 of symlinks) that ends with a FIFO also causes the function to return
8843 true.
8844 See also "guestfs_stat".
8846 This function returns a C truth value on success or -1 on error.
8848 (Added in 1.5.10)
8850 guestfs_is_fifo_opts_va
8852 int
8853 guestfs_is_fifo_opts_va (guestfs_h *g,
8854 const char *path,
8855 va_list args);
8856 This is the "va_list variant" of "guestfs_is_fifo_opts".
8858 See "CALLS WITH OPTIONAL ARGUMENTS".
8860 guestfs_is_fifo_opts_argv
8862 int
8863 guestfs_is_fifo_opts_argv (guestfs_h *g,
8864 const char *path,
8865 const struct guestfs_is_fifo_opts_argv *optargs);
8866 This is the "argv variant" of "guestfs_is_fifo_opts".
8868 See "CALLS WITH OPTIONAL ARGUMENTS".
8870 guestfs_is_file
8872 int
8873 guestfs_is_file (guestfs_h *g,
8874 const char *path);
8875 This function is provided for backwards compatibility with earlier
8877 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
8878 optional arguments.
8879 (Added in 0.8)
8881 guestfs_is_file_opts
8883 int
8884 guestfs_is_file_opts (guestfs_h *g,
8885 const char *path,
8886 ...);
8887 You may supply a list of optional arguments to this call. Use zero or
8889 more of the following pairs of parameters, and terminate the list with
8890 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8891 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8893 This returns "true" if and only if there is a regular file with the
8895 given "path" name. Note that it returns false for other objects like
8896 directories.
8897 If the optional flag "followsymlinks" is true, then a symlink (or chain
8899 of symlinks) that ends with a file also causes the function to return
8900 true.
8901 See also "guestfs_stat".
8903 This function returns a C truth value on success or -1 on error.
8905 (Added in 0.8)
8907 guestfs_is_file_opts_va
8909 int
8910 guestfs_is_file_opts_va (guestfs_h *g,
8911 const char *path,
8912 va_list args);
8913 This is the "va_list variant" of "guestfs_is_file_opts".
8915 See "CALLS WITH OPTIONAL ARGUMENTS".
8917 guestfs_is_file_opts_argv
8919 int
8920 guestfs_is_file_opts_argv (guestfs_h *g,
8921 const char *path,
8922 const struct guestfs_is_file_opts_argv *optargs);
8923 This is the "argv variant" of "guestfs_is_file_opts".
8925 See "CALLS WITH OPTIONAL ARGUMENTS".
8927 guestfs_is_launching
8929 int
8930 guestfs_is_launching (guestfs_h *g);
8931 This returns true iff this handle is launching the subprocess (in the
8933 "LAUNCHING" state).
8934 For more information on states, see guestfs(3).
8936 This function returns a C truth value on success or -1 on error.
8938 (Added in 1.0.2)
8940 guestfs_is_lv
8942 int
8943 guestfs_is_lv (guestfs_h *g,
8944 const char *mountable);
8945 This command tests whether "mountable" is a logical volume, and returns
8947 true iff this is the case.
8948 This function returns a C truth value on success or -1 on error.
8950 (Added in 1.5.3)
8952 guestfs_is_ready
8954 int
8955 guestfs_is_ready (guestfs_h *g);
8956 This returns true iff this handle is ready to accept commands (in the
8958 "READY" state).
8959 For more information on states, see guestfs(3).
8961 This function returns a C truth value on success or -1 on error.
8963 (Added in 1.0.2)
8965 guestfs_is_socket
8967 int
8968 guestfs_is_socket (guestfs_h *g,
8969 const char *path);
8970 This function is provided for backwards compatibility with earlier
8972 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
8973 no optional arguments.
8974 (Added in 1.5.10)
8976 guestfs_is_socket_opts
8978 int
8979 guestfs_is_socket_opts (guestfs_h *g,
8980 const char *path,
8981 ...);
8982 You may supply a list of optional arguments to this call. Use zero or
8984 more of the following pairs of parameters, and terminate the list with
8985 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8986 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8988 This returns "true" if and only if there is a Unix domain socket with
8990 the given "path" name.
8991 If the optional flag "followsymlinks" is true, then a symlink (or chain
8993 of symlinks) that ends with a socket also causes the function to return
8994 true.
8995 See also "guestfs_stat".
8997 This function returns a C truth value on success or -1 on error.
8999 (Added in 1.5.10)
9001 guestfs_is_socket_opts_va
9003 int
9004 guestfs_is_socket_opts_va (guestfs_h *g,
9005 const char *path,
9006 va_list args);
9007 This is the "va_list variant" of "guestfs_is_socket_opts".
9009 See "CALLS WITH OPTIONAL ARGUMENTS".
9011 guestfs_is_socket_opts_argv
9013 int
9014 guestfs_is_socket_opts_argv (guestfs_h *g,
9015 const char *path,
9016 const struct guestfs_is_socket_opts_argv *optargs);
9017 This is the "argv variant" of "guestfs_is_socket_opts".
9019 See "CALLS WITH OPTIONAL ARGUMENTS".
9021 guestfs_is_symlink
9023 int
9024 guestfs_is_symlink (guestfs_h *g,
9025 const char *path);
9026 This returns "true" if and only if there is a symbolic link with the
9028 given "path" name.
9029 See also "guestfs_stat".
9031 This function returns a C truth value on success or -1 on error.
9033 (Added in 1.5.10)
9035 guestfs_is_whole_device
9037 int
9038 guestfs_is_whole_device (guestfs_h *g,
9039 const char *device);
9040 This returns "true" if and only if "device" refers to a whole block
9042 device. That is, not a partition or a logical device.
9043 This function returns a C truth value on success or -1 on error.
9045 (Added in 1.21.9)
9047 guestfs_is_zero
9049 int
9050 guestfs_is_zero (guestfs_h *g,
9051 const char *path);
9052 This returns true iff the file exists and the file is empty or it
9054 contains all zero bytes.
9055 This function returns a C truth value on success or -1 on error.
9057 (Added in 1.11.8)
9059 guestfs_is_zero_device
9061 int
9062 guestfs_is_zero_device (guestfs_h *g,
9063 const char *device);
9064 This returns true iff the device exists and contains all zero bytes.
9066 Note that for large devices this can take a long time to run.
9068 This function returns a C truth value on success or -1 on error.
9070 (Added in 1.11.8)
9072 guestfs_isoinfo
9074 struct guestfs_isoinfo *
9075 guestfs_isoinfo (guestfs_h *g,
9076 const char *isofile);
9077 This is the same as "guestfs_isoinfo_device" except that it works for
9079 an ISO file located inside some other mounted filesystem. Note that in
9080 the common case where you have added an ISO file as a libguestfs
9081 device, you would not call this. Instead you would call
9082 "guestfs_isoinfo_device".
9083 This function returns a "struct guestfs_isoinfo *", or NULL if there
9085 was an error. The caller must call "guestfs_free_isoinfo" after use.
9086 (Added in 1.17.19)
9088 guestfs_isoinfo_device
9090 struct guestfs_isoinfo *
9091 guestfs_isoinfo_device (guestfs_h *g,
9092 const char *device);
9093 "device" is an ISO device. This returns a struct of information read
9095 from the primary volume descriptor (the ISO equivalent of the
9096 superblock) of the device.
9097 Usually it is more efficient to use the isoinfo(1) command with the -d
9099 option on the host to analyze ISO files, instead of going through
9100 libguestfs.
9101 For information on the primary volume descriptor fields, see
9103 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9104 This function returns a "struct guestfs_isoinfo *", or NULL if there
9106 was an error. The caller must call "guestfs_free_isoinfo" after use.
9107 (Added in 1.17.19)
9109 guestfs_journal_close
9111 int
9112 guestfs_journal_close (guestfs_h *g);
9113 Close the journal handle.
9115 This function returns 0 on success or -1 on error.
9117 This function depends on the feature "journal". See also
9119 "guestfs_feature_available".
9120 (Added in 1.23.11)
9122 guestfs_journal_get
9124 struct guestfs_xattr_list *
9125 guestfs_journal_get (guestfs_h *g);
9126 Read the current journal entry. This returns all the fields in the
9128 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
9129 field name (a string).
9130 The "attrval" is the field value (a binary blob, often but not always a
9132 string). Please note that "attrval" is a byte array, not a
9133 \0-terminated C string.
9134 The length of data may be truncated to the data threshold (see:
9136 "guestfs_journal_set_data_threshold",
9137 "guestfs_journal_get_data_threshold").
9138 If you set the data threshold to unlimited (0) then this call can read
9140 a journal entry of any size, ie. it is not limited by the libguestfs
9141 protocol.
9142 This function returns a "struct guestfs_xattr_list *", or NULL if there
9144 was an error. The caller must call "guestfs_free_xattr_list" after
9145 use.
9146 This function depends on the feature "journal". See also
9148 "guestfs_feature_available".
9149 (Added in 1.23.11)
9151 guestfs_journal_get_data_threshold
9153 int64_t
9154 guestfs_journal_get_data_threshold (guestfs_h *g);
9155 Get the current data threshold for reading journal entries. This is a
9157 hint to the journal that it may truncate data fields to this size when
9158 reading them (note also that it may not truncate them). If this
9159 returns 0, then the threshold is unlimited.
9160 See also "guestfs_journal_set_data_threshold".
9162 On error this function returns -1.
9164 This function depends on the feature "journal". See also
9166 "guestfs_feature_available".
9167 (Added in 1.23.11)
9169 guestfs_journal_get_realtime_usec
9171 int64_t
9172 guestfs_journal_get_realtime_usec (guestfs_h *g);
9173 Get the realtime (wallclock) timestamp of the current journal entry.
9175 On error this function returns -1.
9177 This function depends on the feature "journal". See also
9179 "guestfs_feature_available".
9180 (Added in 1.27.18)
9182 guestfs_journal_next
9184 int
9185 guestfs_journal_next (guestfs_h *g);
9186 Move to the next journal entry. You have to call this at least once
9188 after opening the handle before you are able to read data.
9189 The returned boolean tells you if there are any more journal records to
9191 read. "true" means you can read the next record (eg. using
9192 "guestfs_journal_get"), and "false" means you have reached the end of
9193 the journal.
9194 This function returns a C truth value on success or -1 on error.
9196 This function depends on the feature "journal". See also
9198 "guestfs_feature_available".
9199 (Added in 1.23.11)
9201 guestfs_journal_open
9203 int
9204 guestfs_journal_open (guestfs_h *g,
9205 const char *directory);
9206 Open the systemd journal located in directory. Any previously opened
9208 journal handle is closed.
9209 The contents of the journal can be read using "guestfs_journal_next"
9211 and "guestfs_journal_get".
9212 After you have finished using the journal, you should close the handle
9214 by calling "guestfs_journal_close".
9215 This function returns 0 on success or -1 on error.
9217 This function depends on the feature "journal". See also
9219 "guestfs_feature_available".
9220 (Added in 1.23.11)
9222 guestfs_journal_set_data_threshold
9224 int
9225 guestfs_journal_set_data_threshold (guestfs_h *g,
9226 int64_t threshold);
9227 Set the data threshold for reading journal entries. This is a hint to
9229 the journal that it may truncate data fields to this size when reading
9230 them (note also that it may not truncate them). If you set this to 0,
9231 then the threshold is unlimited.
9232 See also "guestfs_journal_get_data_threshold".
9234 This function returns 0 on success or -1 on error.
9236 This function depends on the feature "journal". See also
9238 "guestfs_feature_available".
9239 (Added in 1.23.11)
9241 guestfs_journal_skip
9243 int64_t
9244 guestfs_journal_skip (guestfs_h *g,
9245 int64_t skip);
9246 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9248 The number of entries actually skipped is returned (note "rskip ≥ 0").
9250 If this is not the same as the absolute value of the skip parameter
9251 ("|skip|") you passed in then it means you have reached the end or the
9252 start of the journal.
9253 On error this function returns -1.
9255 This function depends on the feature "journal". See also
9257 "guestfs_feature_available".
9258 (Added in 1.23.11)
9260 guestfs_kill_subprocess
9262 int
9263 guestfs_kill_subprocess (guestfs_h *g);
9264 This function is deprecated. In new code, use the "guestfs_shutdown"
9266 call instead.
9267 Deprecated functions will not be removed from the API, but the fact
9269 that they are deprecated indicates that there are problems with correct
9270 use of these functions.
9271 This kills the hypervisor.
9273 Do not call this. See: "guestfs_shutdown" instead.
9275 This function returns 0 on success or -1 on error.
9277 (Added in 0.3)
9279 guestfs_launch
9281 int
9282 guestfs_launch (guestfs_h *g);
9283 You should call this after configuring the handle (eg. adding drives)
9285 but before performing any actions.
9286 Do not call "guestfs_launch" twice on the same handle. Although it
9288 will not give an error (for historical reasons), the precise behaviour
9289 when you do this is not well defined. Handles are very cheap to
9290 create, so create a new one for each launch.
9291 This function returns 0 on success or -1 on error.
9293 This long-running command can generate progress notification messages
9295 so that the caller can display a progress bar or indicator. To receive
9296 these messages, the caller must register a progress event callback.
9297 See "GUESTFS_EVENT_PROGRESS".
9298 (Added in 0.3)
9300 guestfs_lchown
9302 int
9303 guestfs_lchown (guestfs_h *g,
9304 int owner,
9305 int group,
9306 const char *path);
9307 Change the file owner to "owner" and group to "group". This is like
9309 "guestfs_chown" but if "path" is a symlink then the link itself is
9310 changed, not the target.
9311 Only numeric uid and gid are supported. If you want to use names, you
9313 will need to locate and parse the password file yourself (Augeas
9314 support makes this relatively easy).
9315 This function returns 0 on success or -1 on error.
9317 (Added in 1.0.77)
9319 guestfs_ldmtool_create_all
9321 int
9322 guestfs_ldmtool_create_all (guestfs_h *g);
9323 This function scans all block devices looking for Windows dynamic disk
9325 volumes and partitions, and creates devices for any that were found.
9326 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9328 return all devices.
9329 Note that you don't normally need to call this explicitly, since it is
9331 done automatically at "guestfs_launch" time.
9332 This function returns 0 on success or -1 on error.
9334 This function depends on the feature "ldm". See also
9336 "guestfs_feature_available".
9337 (Added in 1.20.0)
9339 guestfs_ldmtool_diskgroup_disks
9341 char **
9342 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9343 const char *diskgroup);
9344 Return the disks in a Windows dynamic disk group. The "diskgroup"
9346 parameter should be the GUID of a disk group, one element from the list
9347 returned by "guestfs_ldmtool_scan".
9348 This function returns a NULL-terminated array of strings (like
9350 environ(3)), or NULL if there was an error. The caller must free the
9351 strings and the array after use.
9352 This function depends on the feature "ldm". See also
9354 "guestfs_feature_available".
9355 (Added in 1.20.0)
9357 guestfs_ldmtool_diskgroup_name
9359 char *
9360 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9361 const char *diskgroup);
9362 Return the name of a Windows dynamic disk group. The "diskgroup"
9364 parameter should be the GUID of a disk group, one element from the list
9365 returned by "guestfs_ldmtool_scan".
9366 This function returns a string, or NULL on error. The caller must free
9368 the returned string after use.
9369 This function depends on the feature "ldm". See also
9371 "guestfs_feature_available".
9372 (Added in 1.20.0)
9374 guestfs_ldmtool_diskgroup_volumes
9376 char **
9377 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9378 const char *diskgroup);
9379 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9381 parameter should be the GUID of a disk group, one element from the list
9382 returned by "guestfs_ldmtool_scan".
9383 This function returns a NULL-terminated array of strings (like
9385 environ(3)), or NULL if there was an error. The caller must free the
9386 strings and the array after use.
9387 This function depends on the feature "ldm". See also
9389 "guestfs_feature_available".
9390 (Added in 1.20.0)
9392 guestfs_ldmtool_remove_all
9394 int
9395 guestfs_ldmtool_remove_all (guestfs_h *g);
9396 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9398 removes the device mapper mappings for all Windows dynamic disk volumes
9399 This function returns 0 on success or -1 on error.
9401 This function depends on the feature "ldm". See also
9403 "guestfs_feature_available".
9404 (Added in 1.20.0)
9406 guestfs_ldmtool_scan
9408 char **
9409 guestfs_ldmtool_scan (guestfs_h *g);
9410 This function scans for Windows dynamic disks. It returns a list of
9412 identifiers (GUIDs) for all disk groups that were found. These
9413 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9414 This function scans all block devices. To scan a subset of block
9416 devices, call "guestfs_ldmtool_scan_devices" instead.
9417 This function returns a NULL-terminated array of strings (like
9419 environ(3)), or NULL if there was an error. The caller must free the
9420 strings and the array after use.
9421 This function depends on the feature "ldm". See also
9423 "guestfs_feature_available".
9424 (Added in 1.20.0)
9426 guestfs_ldmtool_scan_devices
9428 char **
9429 guestfs_ldmtool_scan_devices (guestfs_h *g,
9430 char *const *devices);
9431 This function scans for Windows dynamic disks. It returns a list of
9433 identifiers (GUIDs) for all disk groups that were found. These
9434 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9435 The parameter "devices" is a list of block devices which are scanned.
9437 If this list is empty, all block devices are scanned.
9438 This function returns a NULL-terminated array of strings (like
9440 environ(3)), or NULL if there was an error. The caller must free the
9441 strings and the array after use.
9442 This function depends on the feature "ldm". See also
9444 "guestfs_feature_available".
9445 (Added in 1.20.0)
9447 guestfs_ldmtool_volume_hint
9449 char *
9450 guestfs_ldmtool_volume_hint (guestfs_h *g,
9451 const char *diskgroup,
9452 const char *volume);
9453 Return the hint field of the volume named "volume" in the disk group
9455 with GUID "diskgroup". This may not be defined, in which case the
9456 empty string is returned. The hint field is often, though not always,
9457 the name of a Windows drive, eg. "E:".
9458 This function returns a string, or NULL on error. The caller must free
9460 the returned string after use.
9461 This function depends on the feature "ldm". See also
9463 "guestfs_feature_available".
9464 (Added in 1.20.0)
9466 guestfs_ldmtool_volume_partitions
9468 char **
9469 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9470 const char *diskgroup,
9471 const char *volume);
9472 Return the list of partitions in the volume named "volume" in the disk
9474 group with GUID "diskgroup".
9475 This function returns a NULL-terminated array of strings (like
9477 environ(3)), or NULL if there was an error. The caller must free the
9478 strings and the array after use.
9479 This function depends on the feature "ldm". See also
9481 "guestfs_feature_available".
9482 (Added in 1.20.0)
9484 guestfs_ldmtool_volume_type
9486 char *
9487 guestfs_ldmtool_volume_type (guestfs_h *g,
9488 const char *diskgroup,
9489 const char *volume);
9490 Return the type of the volume named "volume" in the disk group with
9492 GUID "diskgroup".
9493 Possible volume types that can be returned here include: "simple",
9495 "spanned", "striped", "mirrored", "raid5". Other types may also be
9496 returned.
9497 This function returns a string, or NULL on error. The caller must free
9499 the returned string after use.
9500 This function depends on the feature "ldm". See also
9502 "guestfs_feature_available".
9503 (Added in 1.20.0)
9505 guestfs_lgetxattr
9507 char *
9508 guestfs_lgetxattr (guestfs_h *g,
9509 const char *path,
9510 const char *name,
9511 size_t *size_r);
9512 Get a single extended attribute from file "path" named "name". If
9514 "path" is a symlink, then this call returns an extended attribute from
9515 the symlink.
9516 Normally it is better to get all extended attributes from a file in one
9518 go by calling "guestfs_getxattrs". However some Linux filesystem
9519 implementations are buggy and do not provide a way to list out
9520 attributes. For these filesystems (notably ntfs-3g) you have to know
9521 the names of the extended attributes you want in advance and call this
9522 function.
9523 Extended attribute values are blobs of binary data. If there is no
9525 extended attribute named "name", this returns an error.
9526 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9528 This function returns a buffer, or NULL on error. The size of the
9530 returned buffer is written to *size_r. The caller must free the
9531 returned buffer after use.
9532 This function depends on the feature "linuxxattrs". See also
9534 "guestfs_feature_available".
9535 (Added in 1.7.24)
9537 guestfs_lgetxattrs
9539 struct guestfs_xattr_list *
9540 guestfs_lgetxattrs (guestfs_h *g,
9541 const char *path);
9542 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9544 link, then it returns the extended attributes of the link itself.
9545 This function returns a "struct guestfs_xattr_list *", or NULL if there
9547 was an error. The caller must call "guestfs_free_xattr_list" after
9548 use.
9549 This function depends on the feature "linuxxattrs". See also
9551 "guestfs_feature_available".
9552 (Added in 1.0.59)
9554 guestfs_list_9p
9556 char **
9557 guestfs_list_9p (guestfs_h *g);
9558 This function is deprecated. There is no replacement. Consult the API
9560 documentation in guestfs(3) for further information.
9561 Deprecated functions will not be removed from the API, but the fact
9563 that they are deprecated indicates that there are problems with correct
9564 use of these functions.
9565 This call does nothing and returns an error.
9567 This function returns a NULL-terminated array of strings (like
9569 environ(3)), or NULL if there was an error. The caller must free the
9570 strings and the array after use.
9571 (Added in 1.11.12)
9573 guestfs_list_devices
9575 char **
9576 guestfs_list_devices (guestfs_h *g);
9577 List all the block devices.
9579 The full block device names are returned, eg. /dev/sda.
9581 See also "guestfs_list_filesystems".
9583 This function returns a NULL-terminated array of strings (like
9585 environ(3)), or NULL if there was an error. The caller must free the
9586 strings and the array after use.
9587 (Added in 0.4)
9589 guestfs_list_disk_labels
9591 char **
9592 guestfs_list_disk_labels (guestfs_h *g);
9593 If you add drives using the optional "label" parameter of
9595 "guestfs_add_drive_opts", you can use this call to map between disk
9596 labels, and raw block device and partition names (like /dev/sda and
9597 /dev/sda1).
9598 This returns a hashtable, where keys are the disk labels (without the
9600 /dev/disk/guestfs prefix), and the values are the full raw block device
9601 and partition names (eg. /dev/sda and /dev/sda1).
9602 This function returns a NULL-terminated array of strings, or NULL if
9604 there was an error. The array of strings will always have length
9605 "2n+1", where "n" keys and values alternate, followed by the trailing
9606 NULL entry. The caller must free the strings and the array after use.
9607 (Added in 1.19.49)
9609 guestfs_list_dm_devices
9611 char **
9612 guestfs_list_dm_devices (guestfs_h *g);
9613 List all device mapper devices.
9615 The returned list contains /dev/mapper/* devices, eg. ones created by a
9617 previous call to "guestfs_luks_open".
9618 Device mapper devices which correspond to logical volumes are not
9620 returned in this list. Call "guestfs_lvs" if you want to list logical
9621 volumes.
9622 This function returns a NULL-terminated array of strings (like
9624 environ(3)), or NULL if there was an error. The caller must free the
9625 strings and the array after use.
9626 (Added in 1.11.15)
9628 guestfs_list_filesystems
9630 char **
9631 guestfs_list_filesystems (guestfs_h *g);
9632 This inspection command looks for filesystems on partitions, block
9634 devices and logical volumes, returning a list of "mountables"
9635 containing filesystems and their type.
9636 The return value is a hash, where the keys are the devices containing
9638 filesystems, and the values are the filesystem types. For example:
9639 "/dev/sda1" => "ntfs"
9641 "/dev/sda2" => "ext2"
9642 "/dev/vg_guest/lv_root" => "ext4"
9643 "/dev/vg_guest/lv_swap" => "swap"
9644 The key is not necessarily a block device. It may also be an opaque
9646 ‘mountable’ string which can be passed to "guestfs_mount".
9647 The value can have the special value "unknown", meaning the content of
9649 the device is undetermined or empty. "swap" means a Linux swap
9650 partition.
9651 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9653 might have included "guestfs_mount" and "guestfs_umount", and therefore
9654 you had to use this soon after launch and only when nothing else was
9655 mounted. This restriction is removed in libguestfs ≥ 1.38.
9656 Not all of the filesystems returned will be mountable. In particular,
9658 swap partitions are returned in the list. Also this command does not
9659 check that each filesystem found is valid and mountable, and some
9660 filesystems might be mountable but require special options.
9661 Filesystems may not all belong to a single logical operating system
9662 (use "guestfs_inspect_os" to look for OSes).
9663 This function returns a NULL-terminated array of strings, or NULL if
9665 there was an error. The array of strings will always have length
9666 "2n+1", where "n" keys and values alternate, followed by the trailing
9667 NULL entry. The caller must free the strings and the array after use.
9668 (Added in 1.5.15)
9670 guestfs_list_ldm_partitions
9672 char **
9673 guestfs_list_ldm_partitions (guestfs_h *g);
9674 This function returns all Windows dynamic disk partitions that were
9676 found at launch time. It returns a list of device names.
9677 This function returns a NULL-terminated array of strings (like
9679 environ(3)), or NULL if there was an error. The caller must free the
9680 strings and the array after use.
9681 This function depends on the feature "ldm". See also
9683 "guestfs_feature_available".
9684 (Added in 1.20.0)
9686 guestfs_list_ldm_volumes
9688 char **
9689 guestfs_list_ldm_volumes (guestfs_h *g);
9690 This function returns all Windows dynamic disk volumes that were found
9692 at launch time. It returns a list of device names.
9693 This function returns a NULL-terminated array of strings (like
9695 environ(3)), or NULL if there was an error. The caller must free the
9696 strings and the array after use.
9697 This function depends on the feature "ldm". See also
9699 "guestfs_feature_available".
9700 (Added in 1.20.0)
9702 guestfs_list_md_devices
9704 char **
9705 guestfs_list_md_devices (guestfs_h *g);
9706 List all Linux md devices.
9708 This function returns a NULL-terminated array of strings (like
9710 environ(3)), or NULL if there was an error. The caller must free the
9711 strings and the array after use.
9712 (Added in 1.15.4)
9714 guestfs_list_partitions
9716 char **
9717 guestfs_list_partitions (guestfs_h *g);
9718 List all the partitions detected on all block devices.
9720 The full partition device names are returned, eg. /dev/sda1
9722 This does not return logical volumes. For that you will need to call
9724 "guestfs_lvs".
9725 See also "guestfs_list_filesystems".
9727 This function returns a NULL-terminated array of strings (like
9729 environ(3)), or NULL if there was an error. The caller must free the
9730 strings and the array after use.
9731 (Added in 0.4)
9733 guestfs_ll
9735 char *
9736 guestfs_ll (guestfs_h *g,
9737 const char *directory);
9738 List the files in directory (relative to the root directory, there is
9740 no cwd) in the format of "ls -la".
9741 This command is mostly useful for interactive sessions. It is not
9743 intended that you try to parse the output string.
9744 This function returns a string, or NULL on error. The caller must free
9746 the returned string after use.
9747 (Added in 0.4)
9749 guestfs_llz
9751 char *
9752 guestfs_llz (guestfs_h *g,
9753 const char *directory);
9754 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9756 call instead.
9757 Deprecated functions will not be removed from the API, but the fact
9759 that they are deprecated indicates that there are problems with correct
9760 use of these functions.
9761 List the files in directory in the format of "ls -laZ".
9763 This command is mostly useful for interactive sessions. It is not
9765 intended that you try to parse the output string.
9766 This function returns a string, or NULL on error. The caller must free
9768 the returned string after use.
9769 (Added in 1.17.6)
9771 guestfs_ln
9773 int
9774 guestfs_ln (guestfs_h *g,
9775 const char *target,
9776 const char *linkname);
9777 This command creates a hard link.
9779 This function returns 0 on success or -1 on error.
9781 (Added in 1.0.66)
9783 guestfs_ln_f
9785 int
9786 guestfs_ln_f (guestfs_h *g,
9787 const char *target,
9788 const char *linkname);
9789 This command creates a hard link, removing the link "linkname" if it
9791 exists already.
9792 This function returns 0 on success or -1 on error.
9794 (Added in 1.0.66)
9796 guestfs_ln_s
9798 int
9799 guestfs_ln_s (guestfs_h *g,
9800 const char *target,
9801 const char *linkname);
9802 This command creates a symbolic link using the "ln -s" command.
9804 This function returns 0 on success or -1 on error.
9806 (Added in 1.0.66)
9808 guestfs_ln_sf
9810 int
9811 guestfs_ln_sf (guestfs_h *g,
9812 const char *target,
9813 const char *linkname);
9814 This command creates a symbolic link using the "ln -sf" command, The -f
9816 option removes the link ("linkname") if it exists already.
9817 This function returns 0 on success or -1 on error.
9819 (Added in 1.0.66)
9821 guestfs_lremovexattr
9823 int
9824 guestfs_lremovexattr (guestfs_h *g,
9825 const char *xattr,
9826 const char *path);
9827 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9829 link, then it removes an extended attribute of the link itself.
9830 This function returns 0 on success or -1 on error.
9832 This function depends on the feature "linuxxattrs". See also
9834 "guestfs_feature_available".
9835 (Added in 1.0.59)
9837 guestfs_ls
9839 char **
9840 guestfs_ls (guestfs_h *g,
9841 const char *directory);
9842 List the files in directory (relative to the root directory, there is
9844 no cwd). The "." and ".." entries are not returned, but hidden files
9845 are shown.
9846 This function returns a NULL-terminated array of strings (like
9848 environ(3)), or NULL if there was an error. The caller must free the
9849 strings and the array after use.
9850 (Added in 0.4)
9852 guestfs_ls0
9854 int
9855 guestfs_ls0 (guestfs_h *g,
9856 const char *dir,
9857 const char *filenames);
9858 This specialized command is used to get a listing of the filenames in
9860 the directory "dir". The list of filenames is written to the local
9861 file filenames (on the host).
9862 In the output file, the filenames are separated by "\0" characters.
9864 "." and ".." are not returned. The filenames are not sorted.
9866 This function returns 0 on success or -1 on error.
9868 (Added in 1.19.32)
9870 guestfs_lsetxattr
9872 int
9873 guestfs_lsetxattr (guestfs_h *g,
9874 const char *xattr,
9875 const char *val,
9876 int vallen,
9877 const char *path);
9878 This is the same as "guestfs_setxattr", but if "path" is a symbolic
9880 link, then it sets an extended attribute of the link itself.
9881 This function returns 0 on success or -1 on error.
9883 This function depends on the feature "linuxxattrs". See also
9885 "guestfs_feature_available".
9886 (Added in 1.0.59)
9888 guestfs_lstat
9890 struct guestfs_stat *
9891 guestfs_lstat (guestfs_h *g,
9892 const char *path);
9893 This function is deprecated. In new code, use the "guestfs_lstatns"
9895 call instead.
9896 Deprecated functions will not be removed from the API, but the fact
9898 that they are deprecated indicates that there are problems with correct
9899 use of these functions.
9900 Returns file information for the given "path".
9902 This is the same as "guestfs_stat" except that if "path" is a symbolic
9904 link, then the link is stat-ed, not the file it refers to.
9905 This is the same as the lstat(2) system call.
9907 This function returns a "struct guestfs_stat *", or NULL if there was
9909 an error. The caller must call "guestfs_free_stat" after use.
9910 (Added in 1.9.2)
9912 guestfs_lstatlist
9914 struct guestfs_stat_list *
9915 guestfs_lstatlist (guestfs_h *g,
9916 const char *path,
9917 char *const *names);
9918 This function is deprecated. In new code, use the
9920 "guestfs_lstatnslist" call instead.
9921 Deprecated functions will not be removed from the API, but the fact
9923 that they are deprecated indicates that there are problems with correct
9924 use of these functions.
9925 This call allows you to perform the "guestfs_lstat" operation on
9927 multiple files, where all files are in the directory "path". "names"
9928 is the list of files from this directory.
9929 On return you get a list of stat structs, with a one-to-one
9931 correspondence to the "names" list. If any name did not exist or could
9932 not be lstat'd, then the "st_ino" field of that structure is set to
9933 "-1".
9934 This call is intended for programs that want to efficiently list a
9936 directory contents without making many round-trips. See also
9937 "guestfs_lxattrlist" for a similarly efficient call for getting
9938 extended attributes.
9939 This function returns a "struct guestfs_stat_list *", or NULL if there
9941 was an error. The caller must call "guestfs_free_stat_list" after use.
9942 (Added in 1.0.77)
9944 guestfs_lstatns
9946 struct guestfs_statns *
9947 guestfs_lstatns (guestfs_h *g,
9948 const char *path);
9949 Returns file information for the given "path".
9951 This is the same as "guestfs_statns" except that if "path" is a
9953 symbolic link, then the link is stat-ed, not the file it refers to.
9954 This is the same as the lstat(2) system call.
9956 This function returns a "struct guestfs_statns *", or NULL if there was
9958 an error. The caller must call "guestfs_free_statns" after use.
9959 (Added in 1.27.53)
9961 guestfs_lstatnslist
9963 struct guestfs_statns_list *
9964 guestfs_lstatnslist (guestfs_h *g,
9965 const char *path,
9966 char *const *names);
9967 This call allows you to perform the "guestfs_lstatns" operation on
9969 multiple files, where all files are in the directory "path". "names"
9970 is the list of files from this directory.
9971 On return you get a list of stat structs, with a one-to-one
9973 correspondence to the "names" list. If any name did not exist or could
9974 not be lstat'd, then the "st_ino" field of that structure is set to
9975 "-1".
9976 This call is intended for programs that want to efficiently list a
9978 directory contents without making many round-trips. See also
9979 "guestfs_lxattrlist" for a similarly efficient call for getting
9980 extended attributes.
9981 This function returns a "struct guestfs_statns_list *", or NULL if
9983 there was an error. The caller must call "guestfs_free_statns_list"
9984 after use.
9985 (Added in 1.27.53)
9987 guestfs_luks_add_key
9989 int
9990 guestfs_luks_add_key (guestfs_h *g,
9991 const char *device,
9992 const char *key,
9993 const char *newkey,
9994 int keyslot);
9995 This command adds a new key on LUKS device "device". "key" is any
9997 existing key, and is used to access the device. "newkey" is the new
9998 key to add. "keyslot" is the key slot that will be replaced.
9999 Note that if "keyslot" already contains a key, then this command will
10001 fail. You have to use "guestfs_luks_kill_slot" first to remove that
10002 key.
10003 This function returns 0 on success or -1 on error.
10005 This function takes a key or passphrase parameter which could contain
10007 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10008 information.
10009 This function depends on the feature "luks". See also
10011 "guestfs_feature_available".
10012 (Added in 1.5.2)
10014 guestfs_luks_close
10016 int
10017 guestfs_luks_close (guestfs_h *g,
10018 const char *device);
10019 This function is deprecated. In new code, use the
10021 "guestfs_cryptsetup_close" call instead.
10022 Deprecated functions will not be removed from the API, but the fact
10024 that they are deprecated indicates that there are problems with correct
10025 use of these functions.
10026 This closes a LUKS device that was created earlier by
10028 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
10029 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10030 and not the name of the underlying block device.
10031 This function returns 0 on success or -1 on error.
10033 This function depends on the feature "luks". See also
10035 "guestfs_feature_available".
10036 (Added in 1.5.1)
10038 guestfs_luks_format
10040 int
10041 guestfs_luks_format (guestfs_h *g,
10042 const char *device,
10043 const char *key,
10044 int keyslot);
10045 This command erases existing data on "device" and formats the device as
10047 a LUKS encrypted device. "key" is the initial key, which is added to
10048 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
10049 This function returns 0 on success or -1 on error.
10051 This function takes a key or passphrase parameter which could contain
10053 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10054 information.
10055 This function depends on the feature "luks". See also
10057 "guestfs_feature_available".
10058 (Added in 1.5.2)
10060 guestfs_luks_format_cipher
10062 int
10063 guestfs_luks_format_cipher (guestfs_h *g,
10064 const char *device,
10065 const char *key,
10066 int keyslot,
10067 const char *cipher);
10068 This command is the same as "guestfs_luks_format" but it also allows
10070 you to set the "cipher" used.
10071 This function returns 0 on success or -1 on error.
10073 This function takes a key or passphrase parameter which could contain
10075 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10076 information.
10077 This function depends on the feature "luks". See also
10079 "guestfs_feature_available".
10080 (Added in 1.5.2)
10082 guestfs_luks_kill_slot
10084 int
10085 guestfs_luks_kill_slot (guestfs_h *g,
10086 const char *device,
10087 const char *key,
10088 int keyslot);
10089 This command deletes the key in key slot "keyslot" from the encrypted
10091 LUKS device "device". "key" must be one of the other keys.
10092 This function returns 0 on success or -1 on error.
10094 This function takes a key or passphrase parameter which could contain
10096 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10097 information.
10098 This function depends on the feature "luks". See also
10100 "guestfs_feature_available".
10101 (Added in 1.5.2)
10103 guestfs_luks_open
10105 int
10106 guestfs_luks_open (guestfs_h *g,
10107 const char *device,
10108 const char *key,
10109 const char *mapname);
10110 This function is deprecated. In new code, use the
10112 "guestfs_cryptsetup_open" call instead.
10113 Deprecated functions will not be removed from the API, but the fact
10115 that they are deprecated indicates that there are problems with correct
10116 use of these functions.
10117 This command opens a block device which has been encrypted according to
10119 the Linux Unified Key Setup (LUKS) standard.
10120 "device" is the encrypted block device or partition.
10122 The caller must supply one of the keys associated with the LUKS block
10124 device, in the "key" parameter.
10125 This creates a new block device called /dev/mapper/mapname. Reads and
10127 writes to this block device are decrypted from and encrypted to the
10128 underlying "device" respectively.
10129 If this block device contains LVM volume groups, then calling
10131 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10132 visible.
10133 Use "guestfs_list_dm_devices" to list all device mapper devices.
10135 This function returns 0 on success or -1 on error.
10137 This function takes a key or passphrase parameter which could contain
10139 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10140 information.
10141 This function depends on the feature "luks". See also
10143 "guestfs_feature_available".
10144 (Added in 1.5.1)
10146 guestfs_luks_open_ro
10148 int
10149 guestfs_luks_open_ro (guestfs_h *g,
10150 const char *device,
10151 const char *key,
10152 const char *mapname);
10153 This function is deprecated. In new code, use the
10155 "guestfs_cryptsetup_open" call instead.
10156 Deprecated functions will not be removed from the API, but the fact
10158 that they are deprecated indicates that there are problems with correct
10159 use of these functions.
10160 This is the same as "guestfs_luks_open" except that a read-only mapping
10162 is created.
10163 This function returns 0 on success or -1 on error.
10165 This function takes a key or passphrase parameter which could contain
10167 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10168 information.
10169 This function depends on the feature "luks". See also
10171 "guestfs_feature_available".
10172 (Added in 1.5.1)
10174 guestfs_luks_uuid
10176 char *
10177 guestfs_luks_uuid (guestfs_h *g,
10178 const char *device);
10179 This returns the UUID of the LUKS device "device".
10181 This function returns a string, or NULL on error. The caller must free
10183 the returned string after use.
10184 This function depends on the feature "luks". See also
10186 "guestfs_feature_available".
10187 (Added in 1.41.9)
10189 guestfs_lvcreate
10191 int
10192 guestfs_lvcreate (guestfs_h *g,
10193 const char *logvol,
10194 const char *volgroup,
10195 int mbytes);
10196 This creates an LVM logical volume called "logvol" on the volume group
10198 "volgroup", with "size" megabytes.
10199 This function returns 0 on success or -1 on error.
10201 This function depends on the feature "lvm2". See also
10203 "guestfs_feature_available".
10204 (Added in 0.8)
10206 guestfs_lvcreate_free
10208 int
10209 guestfs_lvcreate_free (guestfs_h *g,
10210 const char *logvol,
10211 const char *volgroup,
10212 int percent);
10213 Create an LVM logical volume called /dev/volgroup/logvol, using
10215 approximately "percent" % of the free space remaining in the volume
10216 group. Most usefully, when "percent" is 100 this will create the
10217 largest possible LV.
10218 This function returns 0 on success or -1 on error.
10220 This function depends on the feature "lvm2". See also
10222 "guestfs_feature_available".
10223 (Added in 1.17.18)
10225 guestfs_lvm_canonical_lv_name
10227 char *
10228 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10229 const char *lvname);
10230 This converts alternative naming schemes for LVs that you might find to
10232 the canonical name. For example, /dev/mapper/VG-LV is converted to
10233 /dev/VG/LV.
10234 This command returns an error if the "lvname" parameter does not refer
10236 to a logical volume. In this case errno will be set to "EINVAL".
10237 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10239 This function returns a string, or NULL on error. The caller must free
10241 the returned string after use.
10242 (Added in 1.5.24)
10244 guestfs_lvm_clear_filter
10246 int
10247 guestfs_lvm_clear_filter (guestfs_h *g);
10248 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10250 to see every block device.
10251 This command also clears the LVM cache and performs a volume group
10253 scan.
10254 This function returns 0 on success or -1 on error.
10256 (Added in 1.5.1)
10258 guestfs_lvm_remove_all
10260 int
10261 guestfs_lvm_remove_all (guestfs_h *g);
10262 This command removes all LVM logical volumes, volume groups and
10264 physical volumes.
10265 This function returns 0 on success or -1 on error.
10267 This function depends on the feature "lvm2". See also
10269 "guestfs_feature_available".
10270 (Added in 0.8)
10272 guestfs_lvm_scan
10274 int
10275 guestfs_lvm_scan (guestfs_h *g,
10276 int activate);
10277 This scans all block devices and rebuilds the list of LVM physical
10279 volumes, volume groups and logical volumes.
10280 If the "activate" parameter is "true" then newly found volume groups
10282 and logical volumes are activated, meaning the LV /dev/VG/LV devices
10283 become visible.
10284 When a libguestfs handle is launched it scans for existing devices, so
10286 you do not normally need to use this API. However it is useful when
10287 you have added a new device or deleted an existing device (such as when
10288 the "guestfs_luks_open" API is used).
10289 This function returns 0 on success or -1 on error.
10291 (Added in 1.39.8)
10293 guestfs_lvm_set_filter
10295 int
10296 guestfs_lvm_set_filter (guestfs_h *g,
10297 char *const *devices);
10298 This sets the LVM device filter so that LVM will only be able to "see"
10300 the block devices in the list "devices", and will ignore all other
10301 attached block devices.
10302 Where disk image(s) contain duplicate PVs or VGs, this command is
10304 useful to get LVM to ignore the duplicates, otherwise LVM can get
10305 confused. Note also there are two types of duplication possible:
10306 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10307 cloned but just happen to have the same name. In normal operation you
10308 cannot create this situation, but you can do it outside LVM, eg. by
10309 cloning disk images or by bit twiddling inside the LVM metadata.
10310 This command also clears the LVM cache and performs a volume group
10312 scan.
10313 You can filter whole block devices or individual partitions.
10315 You cannot use this if any VG is currently in use (eg. contains a
10317 mounted filesystem), even if you are not filtering out that VG.
10318 This function returns 0 on success or -1 on error.
10320 This function depends on the feature "lvm2". See also
10322 "guestfs_feature_available".
10323 (Added in 1.5.1)
10325 guestfs_lvremove
10327 int
10328 guestfs_lvremove (guestfs_h *g,
10329 const char *device);
10330 Remove an LVM logical volume "device", where "device" is the path to
10332 the LV, such as /dev/VG/LV.
10333 You can also remove all LVs in a volume group by specifying the VG
10335 name, /dev/VG.
10336 This function returns 0 on success or -1 on error.
10338 This function depends on the feature "lvm2". See also
10340 "guestfs_feature_available".
10341 (Added in 1.0.13)
10343 guestfs_lvrename
10345 int
10346 guestfs_lvrename (guestfs_h *g,
10347 const char *logvol,
10348 const char *newlogvol);
10349 Rename a logical volume "logvol" with the new name "newlogvol".
10351 This function returns 0 on success or -1 on error.
10353 (Added in 1.0.83)
10355 guestfs_lvresize
10357 int
10358 guestfs_lvresize (guestfs_h *g,
10359 const char *device,
10360 int mbytes);
10361 This resizes (expands or shrinks) an existing LVM logical volume to
10363 "mbytes". When reducing, data in the reduced part is lost.
10364 This function returns 0 on success or -1 on error.
10366 This function depends on the feature "lvm2". See also
10368 "guestfs_feature_available".
10369 (Added in 1.0.27)
10371 guestfs_lvresize_free
10373 int
10374 guestfs_lvresize_free (guestfs_h *g,
10375 const char *lv,
10376 int percent);
10377 This expands an existing logical volume "lv" so that it fills "pc" % of
10379 the remaining free space in the volume group. Commonly you would call
10380 this with pc = 100 which expands the logical volume as much as
10381 possible, using all remaining free space in the volume group.
10382 This function returns 0 on success or -1 on error.
10384 This function depends on the feature "lvm2". See also
10386 "guestfs_feature_available".
10387 (Added in 1.3.3)
10389 guestfs_lvs
10391 char **
10392 guestfs_lvs (guestfs_h *g);
10393 List all the logical volumes detected. This is the equivalent of the
10395 lvs(8) command.
10396 This returns a list of the logical volume device names (eg.
10398 /dev/VolGroup00/LogVol00).
10399 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10401 This function returns a NULL-terminated array of strings (like
10403 environ(3)), or NULL if there was an error. The caller must free the
10404 strings and the array after use.
10405 This function depends on the feature "lvm2". See also
10407 "guestfs_feature_available".
10408 (Added in 0.4)
10410 guestfs_lvs_full
10412 struct guestfs_lvm_lv_list *
10413 guestfs_lvs_full (guestfs_h *g);
10414 List all the logical volumes detected. This is the equivalent of the
10416 lvs(8) command. The "full" version includes all fields.
10417 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10419 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10420 after use.
10421 This function depends on the feature "lvm2". See also
10423 "guestfs_feature_available".
10424 (Added in 0.4)
10426 guestfs_lvuuid
10428 char *
10429 guestfs_lvuuid (guestfs_h *g,
10430 const char *device);
10431 This command returns the UUID of the LVM LV "device".
10433 This function returns a string, or NULL on error. The caller must free
10435 the returned string after use.
10436 (Added in 1.0.87)
10438 guestfs_lxattrlist
10440 struct guestfs_xattr_list *
10441 guestfs_lxattrlist (guestfs_h *g,
10442 const char *path,
10443 char *const *names);
10444 This call allows you to get the extended attributes of multiple files,
10446 where all files are in the directory "path". "names" is the list of
10447 files from this directory.
10448 On return you get a flat list of xattr structs which must be
10450 interpreted sequentially. The first xattr struct always has a zero-
10451 length "attrname". "attrval" in this struct is zero-length to indicate
10452 there was an error doing "guestfs_lgetxattr" for this file, or is a C
10453 string which is a decimal number (the number of following attributes
10454 for this file, which could be "0"). Then after the first xattr struct
10455 are the zero or more attributes for the first named file. This repeats
10456 for the second and subsequent files.
10457 This call is intended for programs that want to efficiently list a
10459 directory contents without making many round-trips. See also
10460 "guestfs_lstatlist" for a similarly efficient call for getting standard
10461 stats.
10462 This function returns a "struct guestfs_xattr_list *", or NULL if there
10464 was an error. The caller must call "guestfs_free_xattr_list" after
10465 use.
10466 This function depends on the feature "linuxxattrs". See also
10468 "guestfs_feature_available".
10469 (Added in 1.0.77)
10471 guestfs_max_disks
10473 int
10474 guestfs_max_disks (guestfs_h *g);
10475 Return the maximum number of disks that may be added to a handle (eg.
10477 by "guestfs_add_drive_opts" and similar calls).
10478 This function was added in libguestfs 1.19.7. In previous versions of
10480 libguestfs the limit was 25.
10481 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10483 On error this function returns -1.
10485 (Added in 1.19.7)
10487 guestfs_md_create
10489 int
10490 guestfs_md_create (guestfs_h *g,
10491 const char *name,
10492 char *const *devices,
10493 ...);
10494 You may supply a list of optional arguments to this call. Use zero or
10496 more of the following pairs of parameters, and terminate the list with
10497 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10498 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10500 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10501 GUESTFS_MD_CREATE_SPARE, int spare,
10502 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10503 GUESTFS_MD_CREATE_LEVEL, const char *level,
10504 Create a Linux md (RAID) device named "name" on the devices in the list
10506 "devices".
10507 The optional parameters are:
10509 "missingbitmap"
10511 A bitmap of missing devices. If a bit is set it means that a
10512 missing device is added to the array. The least significant bit
10513 corresponds to the first device in the array.
10514 As examples:
10516 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10518 resulting array would be "[<missing>, "/dev/sda"]".
10519 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10521 resulting array would be "["/dev/sda", <missing>]".
10522 This defaults to 0 (no missing devices).
10524 The length of "devices" + the number of bits set in "missingbitmap"
10526 must equal "nrdevices" + "spare".
10527 "nrdevices"
10529 The number of active RAID devices.
10530 If not set, this defaults to the length of "devices" plus the
10532 number of bits set in "missingbitmap".
10533 "spare"
10535 The number of spare devices.
10536 If not set, this defaults to 0.
10538 "chunk"
10540 The chunk size in bytes.
10541 The "chunk" parameter does not make sense, and should not be
10543 specified, when "level" is "raid1" (which is the default; see
10544 below).
10545 "level"
10547 The RAID level, which can be one of: "linear", "raid0", 0,
10548 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
10549 "raid10", 10. Some of these are synonymous, and more levels may be
10550 added in future.
10551 If not set, this defaults to "raid1".
10553 This function returns 0 on success or -1 on error.
10555 This function depends on the feature "mdadm". See also
10557 "guestfs_feature_available".
10558 (Added in 1.15.6)
10560 guestfs_md_create_va
10562 int
10563 guestfs_md_create_va (guestfs_h *g,
10564 const char *name,
10565 char *const *devices,
10566 va_list args);
10567 This is the "va_list variant" of "guestfs_md_create".
10569 See "CALLS WITH OPTIONAL ARGUMENTS".
10571 guestfs_md_create_argv
10573 int
10574 guestfs_md_create_argv (guestfs_h *g,
10575 const char *name,
10576 char *const *devices,
10577 const struct guestfs_md_create_argv *optargs);
10578 This is the "argv variant" of "guestfs_md_create".
10580 See "CALLS WITH OPTIONAL ARGUMENTS".
10582 guestfs_md_detail
10584 char **
10585 guestfs_md_detail (guestfs_h *g,
10586 const char *md);
10587 This command exposes the output of "mdadm -DY <md>". The following
10589 fields are usually present in the returned hash. Other fields may also
10590 be present.
10591 "level"
10593 The raid level of the MD device.
10594 "devices"
10596 The number of underlying devices in the MD device.
10597 "metadata"
10599 The metadata version used.
10600 "uuid"
10602 The UUID of the MD device.
10603 "name"
10605 The name of the MD device.
10606 This function returns a NULL-terminated array of strings, or NULL if
10608 there was an error. The array of strings will always have length
10609 "2n+1", where "n" keys and values alternate, followed by the trailing
10610 NULL entry. The caller must free the strings and the array after use.
10611 This function depends on the feature "mdadm". See also
10613 "guestfs_feature_available".
10614 (Added in 1.15.6)
10616 guestfs_md_stat
10618 struct guestfs_mdstat_list *
10619 guestfs_md_stat (guestfs_h *g,
10620 const char *md);
10621 This call returns a list of the underlying devices which make up the
10623 single software RAID array device "md".
10624 To get a list of software RAID devices, call "guestfs_list_md_devices".
10626 Each structure returned corresponds to one device along with additional
10628 status information:
10629 "mdstat_device"
10631 The name of the underlying device.
10632 "mdstat_index"
10634 The index of this device within the array.
10635 "mdstat_flags"
10637 Flags associated with this device. This is a string containing (in
10638 no specific order) zero or more of the following flags:
10639 "W" write-mostly
10641 "F" device is faulty
10643 "S" device is a RAID spare
10645 "R" replacement
10647 This function returns a "struct guestfs_mdstat_list *", or NULL if
10649 there was an error. The caller must call "guestfs_free_mdstat_list"
10650 after use.
10651 This function depends on the feature "mdadm". See also
10653 "guestfs_feature_available".
10654 (Added in 1.17.21)
10656 guestfs_md_stop
10658 int
10659 guestfs_md_stop (guestfs_h *g,
10660 const char *md);
10661 This command deactivates the MD array named "md". The device is
10663 stopped, but it is not destroyed or zeroed.
10664 This function returns 0 on success or -1 on error.
10666 This function depends on the feature "mdadm". See also
10668 "guestfs_feature_available".
10669 (Added in 1.15.6)
10671 guestfs_mkdir
10673 int
10674 guestfs_mkdir (guestfs_h *g,
10675 const char *path);
10676 Create a directory named "path".
10678 This function returns 0 on success or -1 on error.
10680 (Added in 0.8)
10682 guestfs_mkdir_mode
10684 int
10685 guestfs_mkdir_mode (guestfs_h *g,
10686 const char *path,
10687 int mode);
10688 This command creates a directory, setting the initial permissions of
10690 the directory to "mode".
10691 For common Linux filesystems, the actual mode which is set will be
10693 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10694 the mode in other ways.
10695 See also "guestfs_mkdir", "guestfs_umask"
10697 This function returns 0 on success or -1 on error.
10699 (Added in 1.0.77)
10701 guestfs_mkdir_p
10703 int
10704 guestfs_mkdir_p (guestfs_h *g,
10705 const char *path);
10706 Create a directory named "path", creating any parent directories as
10708 necessary. This is like the "mkdir -p" shell command.
10709 This function returns 0 on success or -1 on error.
10711 (Added in 0.8)
10713 guestfs_mkdtemp
10715 char *
10716 guestfs_mkdtemp (guestfs_h *g,
10717 const char *tmpl);
10718 This command creates a temporary directory. The "tmpl" parameter
10720 should be a full pathname for the temporary directory name with the
10721 final six characters being "XXXXXX".
10722 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10724 one being suitable for Windows filesystems.
10725 The name of the temporary directory that was created is returned.
10727 The temporary directory is created with mode 0700 and is owned by root.
10729 The caller is responsible for deleting the temporary directory and its
10731 contents after use.
10732 See also: mkdtemp(3)
10734 This function returns a string, or NULL on error. The caller must free
10736 the returned string after use.
10737 (Added in 1.0.54)
10739 guestfs_mke2fs
10741 int
10742 guestfs_mke2fs (guestfs_h *g,
10743 const char *device,
10744 ...);
10745 You may supply a list of optional arguments to this call. Use zero or
10747 more of the following pairs of parameters, and terminate the list with
10748 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10749 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10751 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10752 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10753 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10754 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10755 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10756 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10757 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10758 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10759 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10760 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10761 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10762 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10763 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10764 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10765 GUESTFS_MKE2FS_LABEL, const char *label,
10766 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10767 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10768 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10769 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10770 GUESTFS_MKE2FS_UUID, const char *uuid,
10771 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10772 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10773 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10774 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10775 GUESTFS_MKE2FS_TESTFS, int testfs,
10776 GUESTFS_MKE2FS_DISCARD, int discard,
10777 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10778 GUESTFS_MKE2FS_EXTENT, int extent,
10779 GUESTFS_MKE2FS_FILETYPE, int filetype,
10780 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10781 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10782 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10783 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10784 GUESTFS_MKE2FS_QUOTA, int quota,
10785 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10786 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10787 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10788 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10790 "device".
10791 The optional "blockscount" is the size of the filesystem in blocks. If
10793 omitted it defaults to the size of "device". Note if the filesystem is
10794 too small to contain a journal, "mke2fs" will silently create an ext2
10795 filesystem instead.
10796 This function returns 0 on success or -1 on error.
10798 (Added in 1.19.44)
10800 guestfs_mke2fs_va
10802 int
10803 guestfs_mke2fs_va (guestfs_h *g,
10804 const char *device,
10805 va_list args);
10806 This is the "va_list variant" of "guestfs_mke2fs".
10808 See "CALLS WITH OPTIONAL ARGUMENTS".
10810 guestfs_mke2fs_argv
10812 int
10813 guestfs_mke2fs_argv (guestfs_h *g,
10814 const char *device,
10815 const struct guestfs_mke2fs_argv *optargs);
10816 This is the "argv variant" of "guestfs_mke2fs".
10818 See "CALLS WITH OPTIONAL ARGUMENTS".
10820 guestfs_mke2fs_J
10822 int
10823 guestfs_mke2fs_J (guestfs_h *g,
10824 const char *fstype,
10825 int blocksize,
10826 const char *device,
10827 const char *journal);
10828 This function is deprecated. In new code, use the "guestfs_mke2fs"
10830 call instead.
10831 Deprecated functions will not be removed from the API, but the fact
10833 that they are deprecated indicates that there are problems with correct
10834 use of these functions.
10835 This creates an ext2/3/4 filesystem on "device" with an external
10837 journal on "journal". It is equivalent to the command:
10838 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10840 See also "guestfs_mke2journal".
10842 This function returns 0 on success or -1 on error.
10844 (Added in 1.0.68)
10846 guestfs_mke2fs_JL
10848 int
10849 guestfs_mke2fs_JL (guestfs_h *g,
10850 const char *fstype,
10851 int blocksize,
10852 const char *device,
10853 const char *label);
10854 This function is deprecated. In new code, use the "guestfs_mke2fs"
10856 call instead.
10857 Deprecated functions will not be removed from the API, but the fact
10859 that they are deprecated indicates that there are problems with correct
10860 use of these functions.
10861 This creates an ext2/3/4 filesystem on "device" with an external
10863 journal on the journal labeled "label".
10864 See also "guestfs_mke2journal_L".
10866 This function returns 0 on success or -1 on error.
10868 (Added in 1.0.68)
10870 guestfs_mke2fs_JU
10872 int
10873 guestfs_mke2fs_JU (guestfs_h *g,
10874 const char *fstype,
10875 int blocksize,
10876 const char *device,
10877 const char *uuid);
10878 This function is deprecated. In new code, use the "guestfs_mke2fs"
10880 call instead.
10881 Deprecated functions will not be removed from the API, but the fact
10883 that they are deprecated indicates that there are problems with correct
10884 use of these functions.
10885 This creates an ext2/3/4 filesystem on "device" with an external
10887 journal on the journal with UUID "uuid".
10888 See also "guestfs_mke2journal_U".
10890 This function returns 0 on success or -1 on error.
10892 This function depends on the feature "linuxfsuuid". See also
10894 "guestfs_feature_available".
10895 (Added in 1.0.68)
10897 guestfs_mke2journal
10899 int
10900 guestfs_mke2journal (guestfs_h *g,
10901 int blocksize,
10902 const char *device);
10903 This function is deprecated. In new code, use the "guestfs_mke2fs"
10905 call instead.
10906 Deprecated functions will not be removed from the API, but the fact
10908 that they are deprecated indicates that there are problems with correct
10909 use of these functions.
10910 This creates an ext2 external journal on "device". It is equivalent to
10912 the command:
10913 mke2fs -O journal_dev -b blocksize device
10915 This function returns 0 on success or -1 on error.
10917 (Added in 1.0.68)
10919 guestfs_mke2journal_L
10921 int
10922 guestfs_mke2journal_L (guestfs_h *g,
10923 int blocksize,
10924 const char *label,
10925 const char *device);
10926 This function is deprecated. In new code, use the "guestfs_mke2fs"
10928 call instead.
10929 Deprecated functions will not be removed from the API, but the fact
10931 that they are deprecated indicates that there are problems with correct
10932 use of these functions.
10933 This creates an ext2 external journal on "device" with label "label".
10935 This function returns 0 on success or -1 on error.
10937 (Added in 1.0.68)
10939 guestfs_mke2journal_U
10941 int
10942 guestfs_mke2journal_U (guestfs_h *g,
10943 int blocksize,
10944 const char *uuid,
10945 const char *device);
10946 This function is deprecated. In new code, use the "guestfs_mke2fs"
10948 call instead.
10949 Deprecated functions will not be removed from the API, but the fact
10951 that they are deprecated indicates that there are problems with correct
10952 use of these functions.
10953 This creates an ext2 external journal on "device" with UUID "uuid".
10955 This function returns 0 on success or -1 on error.
10957 This function depends on the feature "linuxfsuuid". See also
10959 "guestfs_feature_available".
10960 (Added in 1.0.68)
10962 guestfs_mkfifo
10964 int
10965 guestfs_mkfifo (guestfs_h *g,
10966 int mode,
10967 const char *path);
10968 This call creates a FIFO (named pipe) called "path" with mode "mode".
10970 It is just a convenient wrapper around "guestfs_mknod".
10971 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
10973 The mode actually set is affected by the umask.
10975 This function returns 0 on success or -1 on error.
10977 This function depends on the feature "mknod". See also
10979 "guestfs_feature_available".
10980 (Added in 1.0.55)
10982 guestfs_mkfs
10984 int
10985 guestfs_mkfs (guestfs_h *g,
10986 const char *fstype,
10987 const char *device);
10988 This function is provided for backwards compatibility with earlier
10990 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
10991 optional arguments.
10992 (Added in 0.8)
10994 guestfs_mkfs_opts
10996 int
10997 guestfs_mkfs_opts (guestfs_h *g,
10998 const char *fstype,
10999 const char *device,
11000 ...);
11001 You may supply a list of optional arguments to this call. Use zero or
11003 more of the following pairs of parameters, and terminate the list with
11004 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11005 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
11007 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
11008 GUESTFS_MKFS_OPTS_INODE, int inode,
11009 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
11010 GUESTFS_MKFS_OPTS_LABEL, const char *label,
11011 This function creates a filesystem on "device". The filesystem type is
11013 "fstype", for example "ext3".
11014 The optional arguments are:
11016 "blocksize"
11018 The filesystem block size. Supported block sizes depend on the
11019 filesystem type, but typically they are 1024, 2048 or 4096 for
11020 Linux ext2/3 filesystems.
11021 For VFAT and NTFS the "blocksize" parameter is treated as the
11023 requested cluster size.
11024 For UFS block sizes, please see mkfs.ufs(8).
11026 "features"
11028 This passes the -O parameter to the external mkfs program.
11029 For certain filesystem types, this allows extra filesystem features
11031 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
11032 You cannot use this optional parameter with the "gfs" or "gfs2"
11034 filesystem type.
11035 "inode"
11037 This passes the -I parameter to the external mke2fs(8) program
11038 which sets the inode size (only for ext2/3/4 filesystems at
11039 present).
11040 "sectorsize"
11042 This passes the -S parameter to external mkfs.ufs(8) program, which
11043 sets sector size for ufs filesystem.
11044 This function returns 0 on success or -1 on error.
11046 (Added in 0.8)
11048 guestfs_mkfs_opts_va
11050 int
11051 guestfs_mkfs_opts_va (guestfs_h *g,
11052 const char *fstype,
11053 const char *device,
11054 va_list args);
11055 This is the "va_list variant" of "guestfs_mkfs_opts".
11057 See "CALLS WITH OPTIONAL ARGUMENTS".
11059 guestfs_mkfs_opts_argv
11061 int
11062 guestfs_mkfs_opts_argv (guestfs_h *g,
11063 const char *fstype,
11064 const char *device,
11065 const struct guestfs_mkfs_opts_argv *optargs);
11066 This is the "argv variant" of "guestfs_mkfs_opts".
11068 See "CALLS WITH OPTIONAL ARGUMENTS".
11070 guestfs_mkfs_b
11072 int
11073 guestfs_mkfs_b (guestfs_h *g,
11074 const char *fstype,
11075 int blocksize,
11076 const char *device);
11077 This function is deprecated. In new code, use the "guestfs_mkfs" call
11079 instead.
11080 Deprecated functions will not be removed from the API, but the fact
11082 that they are deprecated indicates that there are problems with correct
11083 use of these functions.
11084 This call is similar to "guestfs_mkfs", but it allows you to control
11086 the block size of the resulting filesystem. Supported block sizes
11087 depend on the filesystem type, but typically they are 1024, 2048 or
11088 4096 only.
11089 For VFAT and NTFS the "blocksize" parameter is treated as the requested
11091 cluster size.
11092 This function returns 0 on success or -1 on error.
11094 (Added in 1.0.68)
11096 guestfs_mkfs_btrfs
11098 int
11099 guestfs_mkfs_btrfs (guestfs_h *g,
11100 char *const *devices,
11101 ...);
11102 You may supply a list of optional arguments to this call. Use zero or
11104 more of the following pairs of parameters, and terminate the list with
11105 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11106 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11108 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11109 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11110 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11111 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11112 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11113 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11114 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11115 Create a btrfs filesystem, allowing all configurables to be set. For
11117 more information on the optional arguments, see mkfs.btrfs(8).
11118 Since btrfs filesystems can span multiple devices, this takes a non-
11120 empty list of devices.
11121 To create general filesystems, use "guestfs_mkfs".
11123 This function returns 0 on success or -1 on error.
11125 This function depends on the feature "btrfs". See also
11127 "guestfs_feature_available".
11128 (Added in 1.17.25)
11130 guestfs_mkfs_btrfs_va
11132 int
11133 guestfs_mkfs_btrfs_va (guestfs_h *g,
11134 char *const *devices,
11135 va_list args);
11136 This is the "va_list variant" of "guestfs_mkfs_btrfs".
11138 See "CALLS WITH OPTIONAL ARGUMENTS".
11140 guestfs_mkfs_btrfs_argv
11142 int
11143 guestfs_mkfs_btrfs_argv (guestfs_h *g,
11144 char *const *devices,
11145 const struct guestfs_mkfs_btrfs_argv *optargs);
11146 This is the "argv variant" of "guestfs_mkfs_btrfs".
11148 See "CALLS WITH OPTIONAL ARGUMENTS".
11150 guestfs_mklost_and_found
11152 int
11153 guestfs_mklost_and_found (guestfs_h *g,
11154 const char *mountpoint);
11155 Make the "lost+found" directory, normally in the root directory of an
11157 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
11158 to create the "lost+found" directory.
11159 This function returns 0 on success or -1 on error.
11161 (Added in 1.19.56)
11163 guestfs_mkmountpoint
11165 int
11166 guestfs_mkmountpoint (guestfs_h *g,
11167 const char *exemptpath);
11168 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11170 that can be used to create extra mountpoints before mounting the first
11171 filesystem.
11172 These calls are only necessary in some very limited circumstances,
11174 mainly the case where you want to mount a mix of unrelated and/or read-
11175 only filesystems together.
11176 For example, live CDs often contain a "Russian doll" nest of
11178 filesystems, an ISO outer layer, with a squashfs image inside, with an
11179 ext2/3 image inside that. You can unpack this as follows in guestfish:
11180 add-ro Fedora-11-i686-Live.iso
11182 run
11183 mkmountpoint /cd
11184 mkmountpoint /sqsh
11185 mkmountpoint /ext3fs
11186 mount /dev/sda /cd
11187 mount-loop /cd/LiveOS/squashfs.img /sqsh
11188 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11189 The inner filesystem is now unpacked under the /ext3fs mountpoint.
11191 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11193 You may get unexpected errors if you try to mix these calls. It is
11194 safest to manually unmount filesystems and remove mountpoints after
11195 use.
11196 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11198 first, so for this to work for manual mountpoints, you must ensure that
11199 the innermost mountpoints have the longest pathnames, as in the example
11200 code above.
11201 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11203 Autosync [see "guestfs_set_autosync", this is set by default on
11205 handles] can cause "guestfs_umount_all" to be called when the handle is
11206 closed which can also trigger these issues.
11207 This function returns 0 on success or -1 on error.
11209 (Added in 1.0.62)
11211 guestfs_mknod
11213 int
11214 guestfs_mknod (guestfs_h *g,
11215 int mode,
11216 int devmajor,
11217 int devminor,
11218 const char *path);
11219 This call creates block or character special devices, or named pipes
11221 (FIFOs).
11222 The "mode" parameter should be the mode, using the standard constants.
11224 "devmajor" and "devminor" are the device major and minor numbers, only
11225 used when creating block and character special devices.
11226 Note that, just like mknod(2), the mode must be bitwise OR'd with
11228 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11229 a regular file). These constants are available in the standard Linux
11230 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11231 "guestfs_mkfifo" which are wrappers around this command which bitwise
11232 OR in the appropriate constant for you.
11233 The mode actually set is affected by the umask.
11235 This function returns 0 on success or -1 on error.
11237 This function depends on the feature "mknod". See also
11239 "guestfs_feature_available".
11240 (Added in 1.0.55)
11242 guestfs_mknod_b
11244 int
11245 guestfs_mknod_b (guestfs_h *g,
11246 int mode,
11247 int devmajor,
11248 int devminor,
11249 const char *path);
11250 This call creates a block device node called "path" with mode "mode"
11252 and device major/minor "devmajor" and "devminor". It is just a
11253 convenient wrapper around "guestfs_mknod".
11254 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11256 The mode actually set is affected by the umask.
11258 This function returns 0 on success or -1 on error.
11260 This function depends on the feature "mknod". See also
11262 "guestfs_feature_available".
11263 (Added in 1.0.55)
11265 guestfs_mknod_c
11267 int
11268 guestfs_mknod_c (guestfs_h *g,
11269 int mode,
11270 int devmajor,
11271 int devminor,
11272 const char *path);
11273 This call creates a char device node called "path" with mode "mode" and
11275 device major/minor "devmajor" and "devminor". It is just a convenient
11276 wrapper around "guestfs_mknod".
11277 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11279 The mode actually set is affected by the umask.
11281 This function returns 0 on success or -1 on error.
11283 This function depends on the feature "mknod". See also
11285 "guestfs_feature_available".
11286 (Added in 1.0.55)
11288 guestfs_mksquashfs
11290 int
11291 guestfs_mksquashfs (guestfs_h *g,
11292 const char *path,
11293 const char *filename,
11294 ...);
11295 You may supply a list of optional arguments to this call. Use zero or
11297 more of the following pairs of parameters, and terminate the list with
11298 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11299 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11301 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11302 Create a squashfs filesystem for the specified "path".
11304 The optional "compress" flag controls compression. If not given, then
11306 the output compressed using "gzip". Otherwise one of the following
11307 strings may be given to select the compression type of the squashfs:
11308 "gzip", "lzma", "lzo", "lz4", "xz".
11309 The other optional arguments are:
11311 "excludes"
11313 A list of wildcards. Files are excluded if they match any of the
11314 wildcards.
11315 Please note that this API may fail when used to compress directories
11317 with large files, such as the resulting squashfs will be over 3GB big.
11318 This function returns 0 on success or -1 on error.
11320 This function depends on the feature "squashfs". See also
11322 "guestfs_feature_available".
11323 (Added in 1.35.25)
11325 guestfs_mksquashfs_va
11327 int
11328 guestfs_mksquashfs_va (guestfs_h *g,
11329 const char *path,
11330 const char *filename,
11331 va_list args);
11332 This is the "va_list variant" of "guestfs_mksquashfs".
11334 See "CALLS WITH OPTIONAL ARGUMENTS".
11336 guestfs_mksquashfs_argv
11338 int
11339 guestfs_mksquashfs_argv (guestfs_h *g,
11340 const char *path,
11341 const char *filename,
11342 const struct guestfs_mksquashfs_argv *optargs);
11343 This is the "argv variant" of "guestfs_mksquashfs".
11345 See "CALLS WITH OPTIONAL ARGUMENTS".
11347 guestfs_mkswap
11349 int
11350 guestfs_mkswap (guestfs_h *g,
11351 const char *device);
11352 This function is provided for backwards compatibility with earlier
11354 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11355 optional arguments.
11356 (Added in 1.0.55)
11358 guestfs_mkswap_opts
11360 int
11361 guestfs_mkswap_opts (guestfs_h *g,
11362 const char *device,
11363 ...);
11364 You may supply a list of optional arguments to this call. Use zero or
11366 more of the following pairs of parameters, and terminate the list with
11367 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11368 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11370 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11371 Create a Linux swap partition on "device".
11373 The option arguments "label" and "uuid" allow you to set the label
11375 and/or UUID of the new swap partition.
11376 This function returns 0 on success or -1 on error.
11378 (Added in 1.0.55)
11380 guestfs_mkswap_opts_va
11382 int
11383 guestfs_mkswap_opts_va (guestfs_h *g,
11384 const char *device,
11385 va_list args);
11386 This is the "va_list variant" of "guestfs_mkswap_opts".
11388 See "CALLS WITH OPTIONAL ARGUMENTS".
11390 guestfs_mkswap_opts_argv
11392 int
11393 guestfs_mkswap_opts_argv (guestfs_h *g,
11394 const char *device,
11395 const struct guestfs_mkswap_opts_argv *optargs);
11396 This is the "argv variant" of "guestfs_mkswap_opts".
11398 See "CALLS WITH OPTIONAL ARGUMENTS".
11400 guestfs_mkswap_L
11402 int
11403 guestfs_mkswap_L (guestfs_h *g,
11404 const char *label,
11405 const char *device);
11406 This function is deprecated. In new code, use the "guestfs_mkswap"
11408 call instead.
11409 Deprecated functions will not be removed from the API, but the fact
11411 that they are deprecated indicates that there are problems with correct
11412 use of these functions.
11413 Create a swap partition on "device" with label "label".
11415 Note that you cannot attach a swap label to a block device (eg.
11417 /dev/sda), just to a partition. This appears to be a limitation of the
11418 kernel or swap tools.
11419 This function returns 0 on success or -1 on error.
11421 (Added in 1.0.55)
11423 guestfs_mkswap_U
11425 int
11426 guestfs_mkswap_U (guestfs_h *g,
11427 const char *uuid,
11428 const char *device);
11429 This function is deprecated. In new code, use the "guestfs_mkswap"
11431 call instead.
11432 Deprecated functions will not be removed from the API, but the fact
11434 that they are deprecated indicates that there are problems with correct
11435 use of these functions.
11436 Create a swap partition on "device" with UUID "uuid".
11438 This function returns 0 on success or -1 on error.
11440 This function depends on the feature "linuxfsuuid". See also
11442 "guestfs_feature_available".
11443 (Added in 1.0.55)
11445 guestfs_mkswap_file
11447 int
11448 guestfs_mkswap_file (guestfs_h *g,
11449 const char *path);
11450 Create a swap file.
11452 This command just writes a swap file signature to an existing file. To
11454 create the file itself, use something like "guestfs_fallocate".
11455 This function returns 0 on success or -1 on error.
11457 (Added in 1.0.66)
11459 guestfs_mktemp
11461 char *
11462 guestfs_mktemp (guestfs_h *g,
11463 const char *tmpl,
11464 ...);
11465 You may supply a list of optional arguments to this call. Use zero or
11467 more of the following pairs of parameters, and terminate the list with
11468 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11469 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11471 This command creates a temporary file. The "tmpl" parameter should be
11473 a full pathname for the temporary directory name with the final six
11474 characters being "XXXXXX".
11475 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11477 one being suitable for Windows filesystems.
11478 The name of the temporary file that was created is returned.
11480 The temporary file is created with mode 0600 and is owned by root.
11482 The caller is responsible for deleting the temporary file after use.
11484 If the optional "suffix" parameter is given, then the suffix (eg.
11486 ".txt") is appended to the temporary name.
11487 See also: "guestfs_mkdtemp".
11489 This function returns a string, or NULL on error. The caller must free
11491 the returned string after use.
11492 (Added in 1.19.53)
11494 guestfs_mktemp_va
11496 char *
11497 guestfs_mktemp_va (guestfs_h *g,
11498 const char *tmpl,
11499 va_list args);
11500 This is the "va_list variant" of "guestfs_mktemp".
11502 See "CALLS WITH OPTIONAL ARGUMENTS".
11504 guestfs_mktemp_argv
11506 char *
11507 guestfs_mktemp_argv (guestfs_h *g,
11508 const char *tmpl,
11509 const struct guestfs_mktemp_argv *optargs);
11510 This is the "argv variant" of "guestfs_mktemp".
11512 See "CALLS WITH OPTIONAL ARGUMENTS".
11514 guestfs_modprobe
11516 int
11517 guestfs_modprobe (guestfs_h *g,
11518 const char *modulename);
11519 This loads a kernel module in the appliance.
11521 This function returns 0 on success or -1 on error.
11523 This function depends on the feature "linuxmodules". See also
11525 "guestfs_feature_available".
11526 (Added in 1.0.68)
11528 guestfs_mount
11530 int
11531 guestfs_mount (guestfs_h *g,
11532 const char *mountable,
11533 const char *mountpoint);
11534 Mount a guest disk at a position in the filesystem. Block devices are
11536 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11537 If those block devices contain partitions, they will have the usual
11538 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11539 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11540 "guestfs_inspect_get_mountpoints".
11541 The rules are the same as for mount(2): A filesystem must first be
11543 mounted on / before others can be mounted. Other filesystems can only
11544 be mounted on directories which already exist.
11545 The mounted filesystem is writable, if we have sufficient permissions
11547 on the underlying device.
11548 Before libguestfs 1.13.16, this call implicitly added the options
11550 "sync" and "noatime". The "sync" option greatly slowed writes and
11551 caused many problems for users. If your program might need to work
11552 with older versions of libguestfs, use "guestfs_mount_options" instead
11553 (using an empty string for the first parameter if you don't want any
11554 options).
11555 This function returns 0 on success or -1 on error.
11557 (Added in 0.3)
11559 guestfs_mount_9p
11561 int
11562 guestfs_mount_9p (guestfs_h *g,
11563 const char *mounttag,
11564 const char *mountpoint,
11565 ...);
11566 This function is deprecated. There is no replacement. Consult the API
11568 documentation in guestfs(3) for further information.
11569 Deprecated functions will not be removed from the API, but the fact
11571 that they are deprecated indicates that there are problems with correct
11572 use of these functions.
11573 You may supply a list of optional arguments to this call. Use zero or
11575 more of the following pairs of parameters, and terminate the list with
11576 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11577 GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11579 This call does nothing and returns an error.
11581 This function returns 0 on success or -1 on error.
11583 (Added in 1.11.12)
11585 guestfs_mount_9p_va
11587 int
11588 guestfs_mount_9p_va (guestfs_h *g,
11589 const char *mounttag,
11590 const char *mountpoint,
11591 va_list args);
11592 This is the "va_list variant" of "guestfs_mount_9p".
11594 See "CALLS WITH OPTIONAL ARGUMENTS".
11596 guestfs_mount_9p_argv
11598 int
11599 guestfs_mount_9p_argv (guestfs_h *g,
11600 const char *mounttag,
11601 const char *mountpoint,
11602 const struct guestfs_mount_9p_argv *optargs);
11603 This is the "argv variant" of "guestfs_mount_9p".
11605 See "CALLS WITH OPTIONAL ARGUMENTS".
11607 guestfs_mount_local
11609 int
11610 guestfs_mount_local (guestfs_h *g,
11611 const char *localmountpoint,
11612 ...);
11613 You may supply a list of optional arguments to this call. Use zero or
11615 more of the following pairs of parameters, and terminate the list with
11616 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11617 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11619 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11620 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11621 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11622 This call exports the libguestfs-accessible filesystem to a local
11624 mountpoint (directory) called "localmountpoint". Ordinary reads and
11625 writes to files and directories under "localmountpoint" are redirected
11626 through libguestfs.
11627 If the optional "readonly" flag is set to true, then writes to the
11629 filesystem return error "EROFS".
11630 "options" is a comma-separated list of mount options. See
11632 guestmount(1) for some useful options.
11633 "cachetimeout" sets the timeout (in seconds) for cached directory
11635 entries. The default is 60 seconds. See guestmount(1) for further
11636 information.
11637 If "debugcalls" is set to true, then additional debugging information
11639 is generated for every FUSE call.
11640 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11642 processing requests (access to it will block). You have to call
11643 "guestfs_mount_local_run" to run the main loop.
11644 See "MOUNT LOCAL" for full documentation.
11646 This function returns 0 on success or -1 on error.
11648 (Added in 1.17.22)
11650 guestfs_mount_local_va
11652 int
11653 guestfs_mount_local_va (guestfs_h *g,
11654 const char *localmountpoint,
11655 va_list args);
11656 This is the "va_list variant" of "guestfs_mount_local".
11658 See "CALLS WITH OPTIONAL ARGUMENTS".
11660 guestfs_mount_local_argv
11662 int
11663 guestfs_mount_local_argv (guestfs_h *g,
11664 const char *localmountpoint,
11665 const struct guestfs_mount_local_argv *optargs);
11666 This is the "argv variant" of "guestfs_mount_local".
11668 See "CALLS WITH OPTIONAL ARGUMENTS".
11670 guestfs_mount_local_run
11672 int
11673 guestfs_mount_local_run (guestfs_h *g);
11674 Run the main loop which translates kernel calls to libguestfs calls.
11676 This should only be called after "guestfs_mount_local" returns
11678 successfully. The call will not return until the filesystem is
11679 unmounted.
11680 Note you must not make concurrent libguestfs calls on the same handle
11682 from another thread.
11683 You may call this from a different thread than the one which called
11685 "guestfs_mount_local", subject to the usual rules for threads and
11686 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11687 See "MOUNT LOCAL" for full documentation.
11689 This function returns 0 on success or -1 on error.
11691 (Added in 1.17.22)
11693 guestfs_mount_loop
11695 int
11696 guestfs_mount_loop (guestfs_h *g,
11697 const char *file,
11698 const char *mountpoint);
11699 This command lets you mount file (a filesystem image in a file) on a
11701 mount point. It is entirely equivalent to the command "mount -o loop
11702 file mountpoint".
11703 This function returns 0 on success or -1 on error.
11705 (Added in 1.0.54)
11707 guestfs_mount_options
11709 int
11710 guestfs_mount_options (guestfs_h *g,
11711 const char *options,
11712 const char *mountable,
11713 const char *mountpoint);
11714 This is the same as the "guestfs_mount" command, but it allows you to
11716 set the mount options as for the mount(8) -o flag.
11717 If the "options" parameter is an empty string, then no options are
11719 passed (all options default to whatever the filesystem uses).
11720 This function returns 0 on success or -1 on error.
11722 (Added in 1.0.10)
11724 guestfs_mount_ro
11726 int
11727 guestfs_mount_ro (guestfs_h *g,
11728 const char *mountable,
11729 const char *mountpoint);
11730 This is the same as the "guestfs_mount" command, but it mounts the
11732 filesystem with the read-only (-o ro) flag.
11733 This function returns 0 on success or -1 on error.
11735 (Added in 1.0.10)
11737 guestfs_mount_vfs
11739 int
11740 guestfs_mount_vfs (guestfs_h *g,
11741 const char *options,
11742 const char *vfstype,
11743 const char *mountable,
11744 const char *mountpoint);
11745 This is the same as the "guestfs_mount" command, but it allows you to
11747 set both the mount options and the vfstype as for the mount(8) -o and
11748 -t flags.
11749 This function returns 0 on success or -1 on error.
11751 (Added in 1.0.10)
11753 guestfs_mountable_device
11755 char *
11756 guestfs_mountable_device (guestfs_h *g,
11757 const char *mountable);
11758 Returns the device name of a mountable. In quite a lot of cases, the
11760 mountable is the device name.
11761 However this doesn't apply for btrfs subvolumes, where the mountable is
11763 a combination of both the device name and the subvolume path (see also
11764 "guestfs_mountable_subvolume" to extract the subvolume path of the
11765 mountable if any).
11766 This function returns a string, or NULL on error. The caller must free
11768 the returned string after use.
11769 (Added in 1.33.15)
11771 guestfs_mountable_subvolume
11773 char *
11774 guestfs_mountable_subvolume (guestfs_h *g,
11775 const char *mountable);
11776 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11778 are a combination of both the device name and the subvolume path (see
11779 also "guestfs_mountable_device" to extract the device of the
11780 mountable).
11781 If the mountable does not represent a btrfs subvolume, then this
11783 function fails and the "errno" is set to "EINVAL".
11784 This function returns a string, or NULL on error. The caller must free
11786 the returned string after use.
11787 (Added in 1.33.15)
11789 guestfs_mountpoints
11791 char **
11792 guestfs_mountpoints (guestfs_h *g);
11793 This call is similar to "guestfs_mounts". That call returns a list of
11795 devices. This one returns a hash table (map) of device name to
11796 directory where the device is mounted.
11797 This function returns a NULL-terminated array of strings, or NULL if
11799 there was an error. The array of strings will always have length
11800 "2n+1", where "n" keys and values alternate, followed by the trailing
11801 NULL entry. The caller must free the strings and the array after use.
11802 (Added in 1.0.62)
11804 guestfs_mounts
11806 char **
11807 guestfs_mounts (guestfs_h *g);
11808 This returns the list of currently mounted filesystems. It returns the
11810 list of devices (eg. /dev/sda1, /dev/VG/LV).
11811 Some internal mounts are not shown.
11813 See also: "guestfs_mountpoints"
11815 This function returns a NULL-terminated array of strings (like
11817 environ(3)), or NULL if there was an error. The caller must free the
11818 strings and the array after use.
11819 (Added in 0.8)
11821 guestfs_mv
11823 int
11824 guestfs_mv (guestfs_h *g,
11825 const char *src,
11826 const char *dest);
11827 This moves a file from "src" to "dest" where "dest" is either a
11829 destination filename or destination directory.
11830 See also: "guestfs_rename".
11832 This function returns 0 on success or -1 on error.
11834 (Added in 1.0.18)
11836 guestfs_nr_devices
11838 int
11839 guestfs_nr_devices (guestfs_h *g);
11840 This returns the number of whole block devices that were added. This
11842 is the same as the number of devices that would be returned if you
11843 called "guestfs_list_devices".
11844 To find out the maximum number of devices that could be added, call
11846 "guestfs_max_disks".
11847 On error this function returns -1.
11849 (Added in 1.19.15)
11851 guestfs_ntfs_3g_probe
11853 int
11854 guestfs_ntfs_3g_probe (guestfs_h *g,
11855 int rw,
11856 const char *device);
11857 This command runs the ntfs-3g.probe(8) command which probes an NTFS
11859 "device" for mountability. (Not all NTFS volumes can be mounted read-
11860 write, and some cannot be mounted at all).
11861 "rw" is a boolean flag. Set it to true if you want to test if the
11863 volume can be mounted read-write. Set it to false if you want to test
11864 if the volume can be mounted read-only.
11865 The return value is an integer which 0 if the operation would succeed,
11867 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
11868 On error this function returns -1.
11870 This function depends on the feature "ntfs3g". See also
11872 "guestfs_feature_available".
11873 (Added in 1.0.43)
11875 guestfs_ntfscat_i
11877 int
11878 guestfs_ntfscat_i (guestfs_h *g,
11879 const char *device,
11880 int64_t inode,
11881 const char *filename);
11882 Download a file given its inode from a NTFS filesystem and save it as
11884 filename on the local machine.
11885 This allows to download some otherwise inaccessible files such as the
11887 ones within the $Extend folder.
11888 The filesystem from which to extract the file must be unmounted,
11890 otherwise the call will fail.
11891 This function returns 0 on success or -1 on error.
11893 This long-running command can generate progress notification messages
11895 so that the caller can display a progress bar or indicator. To receive
11896 these messages, the caller must register a progress event callback.
11897 See "GUESTFS_EVENT_PROGRESS".
11898 (Added in 1.33.14)
11900 guestfs_ntfsclone_in
11902 int
11903 guestfs_ntfsclone_in (guestfs_h *g,
11904 const char *backupfile,
11905 const char *device);
11906 Restore the "backupfile" (from a previous call to
11908 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
11909 of this device.
11910 This function returns 0 on success or -1 on error.
11912 This function depends on the feature "ntfs3g". See also
11914 "guestfs_feature_available".
11915 (Added in 1.17.9)
11917 guestfs_ntfsclone_out
11919 int
11920 guestfs_ntfsclone_out (guestfs_h *g,
11921 const char *device,
11922 const char *backupfile,
11923 ...);
11924 You may supply a list of optional arguments to this call. Use zero or
11926 more of the following pairs of parameters, and terminate the list with
11927 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11928 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
11930 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
11931 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
11932 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
11933 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
11934 Stream the NTFS filesystem "device" to the local file "backupfile".
11936 The format used for the backup file is a special format used by the
11937 ntfsclone(8) tool.
11938 If the optional "metadataonly" flag is true, then only the metadata is
11940 saved, losing all the user data (this is useful for diagnosing some
11941 filesystem problems).
11942 The optional "rescue", "ignorefscheck", "preservetimestamps" and
11944 "force" flags have precise meanings detailed in the ntfsclone(8) man
11945 page.
11946 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
11948 device.
11949 This function returns 0 on success or -1 on error.
11951 This function depends on the feature "ntfs3g". See also
11953 "guestfs_feature_available".
11954 (Added in 1.17.9)
11956 guestfs_ntfsclone_out_va
11958 int
11959 guestfs_ntfsclone_out_va (guestfs_h *g,
11960 const char *device,
11961 const char *backupfile,
11962 va_list args);
11963 This is the "va_list variant" of "guestfs_ntfsclone_out".
11965 See "CALLS WITH OPTIONAL ARGUMENTS".
11967 guestfs_ntfsclone_out_argv
11969 int
11970 guestfs_ntfsclone_out_argv (guestfs_h *g,
11971 const char *device,
11972 const char *backupfile,
11973 const struct guestfs_ntfsclone_out_argv *optargs);
11974 This is the "argv variant" of "guestfs_ntfsclone_out".
11976 See "CALLS WITH OPTIONAL ARGUMENTS".
11978 guestfs_ntfsfix
11980 int
11981 guestfs_ntfsfix (guestfs_h *g,
11982 const char *device,
11983 ...);
11984 You may supply a list of optional arguments to this call. Use zero or
11986 more of the following pairs of parameters, and terminate the list with
11987 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11988 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
11990 This command repairs some fundamental NTFS inconsistencies, resets the
11992 NTFS journal file, and schedules an NTFS consistency check for the
11993 first boot into Windows.
11994 This is not an equivalent of Windows "chkdsk". It does not scan the
11996 filesystem for inconsistencies.
11997 The optional "clearbadsectors" flag clears the list of bad sectors.
11999 This is useful after cloning a disk with bad sectors to a new disk.
12000 This function returns 0 on success or -1 on error.
12002 This function depends on the feature "ntfs3g". See also
12004 "guestfs_feature_available".
12005 (Added in 1.17.9)
12007 guestfs_ntfsfix_va
12009 int
12010 guestfs_ntfsfix_va (guestfs_h *g,
12011 const char *device,
12012 va_list args);
12013 This is the "va_list variant" of "guestfs_ntfsfix".
12015 See "CALLS WITH OPTIONAL ARGUMENTS".
12017 guestfs_ntfsfix_argv
12019 int
12020 guestfs_ntfsfix_argv (guestfs_h *g,
12021 const char *device,
12022 const struct guestfs_ntfsfix_argv *optargs);
12023 This is the "argv variant" of "guestfs_ntfsfix".
12025 See "CALLS WITH OPTIONAL ARGUMENTS".
12027 guestfs_ntfsresize
12029 int
12030 guestfs_ntfsresize (guestfs_h *g,
12031 const char *device);
12032 This function is provided for backwards compatibility with earlier
12034 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
12035 no optional arguments.
12036 (Added in 1.3.2)
12038 guestfs_ntfsresize_opts
12040 int
12041 guestfs_ntfsresize_opts (guestfs_h *g,
12042 const char *device,
12043 ...);
12044 You may supply a list of optional arguments to this call. Use zero or
12046 more of the following pairs of parameters, and terminate the list with
12047 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12048 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12050 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12051 This command resizes an NTFS filesystem, expanding or shrinking it to
12053 the size of the underlying device.
12054 The optional parameters are:
12056 "size"
12058 The new size (in bytes) of the filesystem. If omitted, the
12059 filesystem is resized to fit the container (eg. partition).
12060 "force"
12062 If this option is true, then force the resize of the filesystem
12063 even if the filesystem is marked as requiring a consistency check.
12064 After the resize operation, the filesystem is always marked as
12066 requiring a consistency check (for safety). You have to boot into
12067 Windows to perform this check and clear this condition. If you
12068 don't set the "force" option then it is not possible to call
12069 "guestfs_ntfsresize" multiple times on a single filesystem without
12070 booting into Windows between each resize.
12071 See also ntfsresize(8).
12073 This function returns 0 on success or -1 on error.
12075 This function depends on the feature "ntfsprogs". See also
12077 "guestfs_feature_available".
12078 (Added in 1.3.2)
12080 guestfs_ntfsresize_opts_va
12082 int
12083 guestfs_ntfsresize_opts_va (guestfs_h *g,
12084 const char *device,
12085 va_list args);
12086 This is the "va_list variant" of "guestfs_ntfsresize_opts".
12088 See "CALLS WITH OPTIONAL ARGUMENTS".
12090 guestfs_ntfsresize_opts_argv
12092 int
12093 guestfs_ntfsresize_opts_argv (guestfs_h *g,
12094 const char *device,
12095 const struct guestfs_ntfsresize_opts_argv *optargs);
12096 This is the "argv variant" of "guestfs_ntfsresize_opts".
12098 See "CALLS WITH OPTIONAL ARGUMENTS".
12100 guestfs_ntfsresize_size
12102 int
12103 guestfs_ntfsresize_size (guestfs_h *g,
12104 const char *device,
12105 int64_t size);
12106 This function is deprecated. In new code, use the "guestfs_ntfsresize"
12108 call instead.
12109 Deprecated functions will not be removed from the API, but the fact
12111 that they are deprecated indicates that there are problems with correct
12112 use of these functions.
12113 This command is the same as "guestfs_ntfsresize" except that it allows
12115 you to specify the new size (in bytes) explicitly.
12116 This function returns 0 on success or -1 on error.
12118 This function depends on the feature "ntfsprogs". See also
12120 "guestfs_feature_available".
12121 (Added in 1.3.14)
12123 guestfs_parse_environment
12125 int
12126 guestfs_parse_environment (guestfs_h *g);
12127 Parse the program’s environment and set flags in the handle
12129 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12130 flag is set in the handle.
12131 Most programs do not need to call this. It is done implicitly when you
12133 call "guestfs_create".
12134 See "ENVIRONMENT VARIABLES" for a list of environment variables that
12136 can affect libguestfs handles. See also "guestfs_create_flags", and
12137 "guestfs_parse_environment_list".
12138 This function returns 0 on success or -1 on error.
12140 (Added in 1.19.53)
12142 guestfs_parse_environment_list
12144 int
12145 guestfs_parse_environment_list (guestfs_h *g,
12146 char *const *environment);
12147 Parse the list of strings in the argument "environment" and set flags
12149 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
12150 string in the list, then the ‘verbose’ flag is set in the handle.
12151 This is the same as "guestfs_parse_environment" except that it parses
12153 an explicit list of strings instead of the program's environment.
12154 This function returns 0 on success or -1 on error.
12156 (Added in 1.19.53)
12158 guestfs_part_add
12160 int
12161 guestfs_part_add (guestfs_h *g,
12162 const char *device,
12163 const char *prlogex,
12164 int64_t startsect,
12165 int64_t endsect);
12166 This command adds a partition to "device". If there is no partition
12168 table on the device, call "guestfs_part_init" first.
12169 The "prlogex" parameter is the type of partition. Normally you should
12171 pass "p" or "primary" here, but MBR partition tables also support "l"
12172 (or "logical") and "e" (or "extended") partition types.
12173 "startsect" and "endsect" are the start and end of the partition in
12175 sectors. "endsect" may be negative, which means it counts backwards
12176 from the end of the disk ("-1" is the last sector).
12177 Creating a partition which covers the whole disk is not so easy. Use
12179 "guestfs_part_disk" to do that.
12180 This function returns 0 on success or -1 on error.
12182 (Added in 1.0.78)
12184 guestfs_part_del
12186 int
12187 guestfs_part_del (guestfs_h *g,
12188 const char *device,
12189 int partnum);
12190 This command deletes the partition numbered "partnum" on "device".
12192 Note that in the case of MBR partitioning, deleting an extended
12194 partition also deletes any logical partitions it contains.
12195 This function returns 0 on success or -1 on error.
12197 (Added in 1.3.2)
12199 guestfs_part_disk
12201 int
12202 guestfs_part_disk (guestfs_h *g,
12203 const char *device,
12204 const char *parttype);
12205 This command is simply a combination of "guestfs_part_init" followed by
12207 "guestfs_part_add" to create a single primary partition covering the
12208 whole disk.
12209 "parttype" is the partition table type, usually "mbr" or "gpt", but
12211 other possible values are described in "guestfs_part_init".
12212 This function returns 0 on success or -1 on error.
12214 (Added in 1.0.78)
12216 guestfs_part_expand_gpt
12218 int
12219 guestfs_part_expand_gpt (guestfs_h *g,
12220 const char *device);
12221 Move backup GPT data structures to the end of the disk. This is useful
12223 in case of in-place image expand since disk space after backup GPT
12224 header is not usable. This is equivalent to "sgdisk -e".
12225 See also sgdisk(8).
12227 This function returns 0 on success or -1 on error.
12229 This function depends on the feature "gdisk". See also
12231 "guestfs_feature_available".
12232 (Added in 1.33.2)
12234 guestfs_part_get_bootable
12236 int
12237 guestfs_part_get_bootable (guestfs_h *g,
12238 const char *device,
12239 int partnum);
12240 This command returns true if the partition "partnum" on "device" has
12242 the bootable flag set.
12243 See also "guestfs_part_set_bootable".
12245 This function returns a C truth value on success or -1 on error.
12247 (Added in 1.3.2)
12249 guestfs_part_get_disk_guid
12251 char *
12252 guestfs_part_get_disk_guid (guestfs_h *g,
12253 const char *device);
12254 Return the disk identifier (GUID) of a GPT-partitioned "device".
12256 Behaviour is undefined for other partition types.
12257 This function returns a string, or NULL on error. The caller must free
12259 the returned string after use.
12260 This function depends on the feature "gdisk". See also
12262 "guestfs_feature_available".
12263 (Added in 1.33.2)
12265 guestfs_part_get_gpt_attributes
12267 int64_t
12268 guestfs_part_get_gpt_attributes (guestfs_h *g,
12269 const char *device,
12270 int partnum);
12271 Return the attribute flags of numbered GPT partition "partnum". An
12273 error is returned for MBR partitions.
12274 On error this function returns -1.
12276 This function depends on the feature "gdisk". See also
12278 "guestfs_feature_available".
12279 (Added in 1.21.1)
12281 guestfs_part_get_gpt_guid
12283 char *
12284 guestfs_part_get_gpt_guid (guestfs_h *g,
12285 const char *device,
12286 int partnum);
12287 Return the GUID of numbered GPT partition "partnum".
12289 This function returns a string, or NULL on error. The caller must free
12291 the returned string after use.
12292 This function depends on the feature "gdisk". See also
12294 "guestfs_feature_available".
12295 (Added in 1.29.25)
12297 guestfs_part_get_gpt_type
12299 char *
12300 guestfs_part_get_gpt_type (guestfs_h *g,
12301 const char *device,
12302 int partnum);
12303 Return the type GUID of numbered GPT partition "partnum". For MBR
12305 partitions, return an appropriate GUID corresponding to the MBR type.
12306 Behaviour is undefined for other partition types.
12307 This function returns a string, or NULL on error. The caller must free
12309 the returned string after use.
12310 This function depends on the feature "gdisk". See also
12312 "guestfs_feature_available".
12313 (Added in 1.21.1)
12315 guestfs_part_get_mbr_id
12317 int
12318 guestfs_part_get_mbr_id (guestfs_h *g,
12319 const char *device,
12320 int partnum);
12321 Returns the MBR type byte (also known as the ID byte) from the numbered
12323 partition "partnum".
12324 Note that only MBR (old DOS-style) partitions have type bytes. You
12326 will get undefined results for other partition table types (see
12327 "guestfs_part_get_parttype").
12328 On error this function returns -1.
12330 (Added in 1.3.2)
12332 guestfs_part_get_mbr_part_type
12334 char *
12335 guestfs_part_get_mbr_part_type (guestfs_h *g,
12336 const char *device,
12337 int partnum);
12338 This returns the partition type of an MBR partition numbered "partnum"
12340 on device "device".
12341 It returns "primary", "logical", or "extended".
12343 This function returns a string, or NULL on error. The caller must free
12345 the returned string after use.
12346 (Added in 1.29.32)
12348 guestfs_part_get_name
12350 char *
12351 guestfs_part_get_name (guestfs_h *g,
12352 const char *device,
12353 int partnum);
12354 This gets the partition name on partition numbered "partnum" on device
12356 "device". Note that partitions are numbered from 1.
12357 The partition name can only be read on certain types of partition
12359 table. This works on "gpt" but not on "mbr" partitions.
12360 This function returns a string, or NULL on error. The caller must free
12362 the returned string after use.
12363 (Added in 1.25.33)
12365 guestfs_part_get_parttype
12367 char *
12368 guestfs_part_get_parttype (guestfs_h *g,
12369 const char *device);
12370 This command examines the partition table on "device" and returns the
12372 partition table type (format) being used.
12373 Common return values include: "msdos" (a DOS/Windows style MBR
12375 partition table), "gpt" (a GPT/EFI-style partition table). Other
12376 values are possible, although unusual. See "guestfs_part_init" for a
12377 full list.
12378 This function returns a string, or NULL on error. The caller must free
12380 the returned string after use.
12381 (Added in 1.0.78)
12383 guestfs_part_init
12385 int
12386 guestfs_part_init (guestfs_h *g,
12387 const char *device,
12388 const char *parttype);
12389 This creates an empty partition table on "device" of one of the
12391 partition types listed below. Usually "parttype" should be either
12392 "msdos" or "gpt" (for large disks).
12393 Initially there are no partitions. Following this, you should call
12395 "guestfs_part_add" for each partition required.
12396 Possible values for "parttype" are:
12398 "efi"
12400 "gpt"
12401 Intel EFI / GPT partition table.
12402 This is recommended for >= 2 TB partitions that will be accessed
12404 from Linux and Intel-based Mac OS X. It also has limited backwards
12405 compatibility with the "mbr" format.
12406 "mbr"
12408 "msdos"
12409 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12410 and Windows. This partition type will only work for device sizes
12411 up to 2 TB. For large disks we recommend using "gpt".
12412 Other partition table types that may work but are not supported
12414 include:
12415 "aix"
12417 AIX disk labels.
12418 "amiga"
12420 "rdb"
12421 Amiga "Rigid Disk Block" format.
12422 "bsd"
12424 BSD disk labels.
12425 "dasd"
12427 DASD, used on IBM mainframes.
12428 "dvh"
12430 MIPS/SGI volumes.
12431 "mac"
12433 Old Mac partition format. Modern Macs use "gpt".
12434 "pc98"
12436 NEC PC-98 format, common in Japan apparently.
12437 "sun"
12439 Sun disk labels.
12440 This function returns 0 on success or -1 on error.
12442 (Added in 1.0.78)
12444 guestfs_part_list
12446 struct guestfs_partition_list *
12447 guestfs_part_list (guestfs_h *g,
12448 const char *device);
12449 This command parses the partition table on "device" and returns the
12451 list of partitions found.
12452 The fields in the returned structure are:
12454 "part_num"
12456 Partition number, counting from 1.
12457 "part_start"
12459 Start of the partition in bytes. To get sectors you have to divide
12460 by the device’s sector size, see "guestfs_blockdev_getss".
12461 "part_end"
12463 End of the partition in bytes.
12464 "part_size"
12466 Size of the partition in bytes.
12467 This function returns a "struct guestfs_partition_list *", or NULL if
12469 there was an error. The caller must call "guestfs_free_partition_list"
12470 after use.
12471 (Added in 1.0.78)
12473 guestfs_part_resize
12475 int
12476 guestfs_part_resize (guestfs_h *g,
12477 const char *device,
12478 int partnum,
12479 int64_t endsect);
12480 This command resizes the partition numbered "partnum" on "device" by
12482 moving the end position.
12483 Note that this does not modify any filesystem present in the partition.
12485 If you wish to do this, you will need to use filesystem resizing
12486 commands like "guestfs_resize2fs".
12487 When growing a partition you will want to grow the filesystem
12489 afterwards, but when shrinking, you need to shrink the filesystem
12490 before the partition.
12491 This function returns 0 on success or -1 on error.
12493 (Added in 1.37.20)
12495 guestfs_part_set_bootable
12497 int
12498 guestfs_part_set_bootable (guestfs_h *g,
12499 const char *device,
12500 int partnum,
12501 int bootable);
12502 This sets the bootable flag on partition numbered "partnum" on device
12504 "device". Note that partitions are numbered from 1.
12505 The bootable flag is used by some operating systems (notably Windows)
12507 to determine which partition to boot from. It is by no means
12508 universally recognized.
12509 This function returns 0 on success or -1 on error.
12511 (Added in 1.0.78)
12513 guestfs_part_set_disk_guid
12515 int
12516 guestfs_part_set_disk_guid (guestfs_h *g,
12517 const char *device,
12518 const char *guid);
12519 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12521 Return an error if the partition table of "device" isn't GPT, or if
12522 "guid" is not a valid GUID.
12523 This function returns 0 on success or -1 on error.
12525 This function depends on the feature "gdisk". See also
12527 "guestfs_feature_available".
12528 (Added in 1.33.2)
12530 guestfs_part_set_disk_guid_random
12532 int
12533 guestfs_part_set_disk_guid_random (guestfs_h *g,
12534 const char *device);
12535 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12537 randomly generated value. Return an error if the partition table of
12538 "device" isn't GPT.
12539 This function returns 0 on success or -1 on error.
12541 This function depends on the feature "gdisk". See also
12543 "guestfs_feature_available".
12544 (Added in 1.33.2)
12546 guestfs_part_set_gpt_attributes
12548 int
12549 guestfs_part_set_gpt_attributes (guestfs_h *g,
12550 const char *device,
12551 int partnum,
12552 int64_t attributes);
12553 Set the attribute flags of numbered GPT partition "partnum" to
12555 "attributes". Return an error if the partition table of "device" isn't
12556 GPT.
12557 See
12559 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12560 for a useful list of partition attributes.
12561 This function returns 0 on success or -1 on error.
12563 This function depends on the feature "gdisk". See also
12565 "guestfs_feature_available".
12566 (Added in 1.21.1)
12568 guestfs_part_set_gpt_guid
12570 int
12571 guestfs_part_set_gpt_guid (guestfs_h *g,
12572 const char *device,
12573 int partnum,
12574 const char *guid);
12575 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12577 error if the partition table of "device" isn't GPT, or if "guid" is not
12578 a valid GUID.
12579 This function returns 0 on success or -1 on error.
12581 This function depends on the feature "gdisk". See also
12583 "guestfs_feature_available".
12584 (Added in 1.29.25)
12586 guestfs_part_set_gpt_type
12588 int
12589 guestfs_part_set_gpt_type (guestfs_h *g,
12590 const char *device,
12591 int partnum,
12592 const char *guid);
12593 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12595 an error if the partition table of "device" isn't GPT, or if "guid" is
12596 not a valid GUID.
12597 See
12599 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12600 for a useful list of type GUIDs.
12601 This function returns 0 on success or -1 on error.
12603 This function depends on the feature "gdisk". See also
12605 "guestfs_feature_available".
12606 (Added in 1.21.1)
12608 guestfs_part_set_mbr_id
12610 int
12611 guestfs_part_set_mbr_id (guestfs_h *g,
12612 const char *device,
12613 int partnum,
12614 int idbyte);
12615 Sets the MBR type byte (also known as the ID byte) of the numbered
12617 partition "partnum" to "idbyte". Note that the type bytes quoted in
12618 most documentation are in fact hexadecimal numbers, but usually
12619 documented without any leading "0x" which might be confusing.
12620 Note that only MBR (old DOS-style) partitions have type bytes. You
12622 will get undefined results for other partition table types (see
12623 "guestfs_part_get_parttype").
12624 This function returns 0 on success or -1 on error.
12626 (Added in 1.3.2)
12628 guestfs_part_set_name
12630 int
12631 guestfs_part_set_name (guestfs_h *g,
12632 const char *device,
12633 int partnum,
12634 const char *name);
12635 This sets the partition name on partition numbered "partnum" on device
12637 "device". Note that partitions are numbered from 1.
12638 The partition name can only be set on certain types of partition table.
12640 This works on "gpt" but not on "mbr" partitions.
12641 This function returns 0 on success or -1 on error.
12643 (Added in 1.0.78)
12645 guestfs_part_to_dev
12647 char *
12648 guestfs_part_to_dev (guestfs_h *g,
12649 const char *partition);
12650 This function takes a partition name (eg. "/dev/sdb1") and removes the
12652 partition number, returning the device name (eg. "/dev/sdb").
12653 The named partition must exist, for example as a string returned from
12655 "guestfs_list_partitions".
12656 See also "guestfs_part_to_partnum", "guestfs_device_index".
12658 This function returns a string, or NULL on error. The caller must free
12660 the returned string after use.
12661 (Added in 1.5.15)
12663 guestfs_part_to_partnum
12665 int
12666 guestfs_part_to_partnum (guestfs_h *g,
12667 const char *partition);
12668 This function takes a partition name (eg. "/dev/sdb1") and returns the
12670 partition number (eg. 1).
12671 The named partition must exist, for example as a string returned from
12673 "guestfs_list_partitions".
12674 See also "guestfs_part_to_dev".
12676 On error this function returns -1.
12678 (Added in 1.13.25)
12680 guestfs_ping_daemon
12682 int
12683 guestfs_ping_daemon (guestfs_h *g);
12684 This is a test probe into the guestfs daemon running inside the
12686 libguestfs appliance. Calling this function checks that the daemon
12687 responds to the ping message, without affecting the daemon or attached
12688 block device(s) in any other way.
12689 This function returns 0 on success or -1 on error.
12691 (Added in 1.0.18)
12693 guestfs_pread
12695 char *
12696 guestfs_pread (guestfs_h *g,
12697 const char *path,
12698 int count,
12699 int64_t offset,
12700 size_t *size_r);
12701 This command lets you read part of a file. It reads "count" bytes of
12703 the file, starting at "offset", from file "path".
12704 This may read fewer bytes than requested. For further details see the
12706 pread(2) system call.
12707 See also "guestfs_pwrite", "guestfs_pread_device".
12709 This function returns a buffer, or NULL on error. The size of the
12711 returned buffer is written to *size_r. The caller must free the
12712 returned buffer after use.
12713 Because of the message protocol, there is a transfer limit of somewhere
12715 between 2MB and 4MB. See "PROTOCOL LIMITS".
12716 (Added in 1.0.77)
12718 guestfs_pread_device
12720 char *
12721 guestfs_pread_device (guestfs_h *g,
12722 const char *device,
12723 int count,
12724 int64_t offset,
12725 size_t *size_r);
12726 This command lets you read part of a block device. It reads "count"
12728 bytes of "device", starting at "offset".
12729 This may read fewer bytes than requested. For further details see the
12731 pread(2) system call.
12732 See also "guestfs_pread".
12734 This function returns a buffer, or NULL on error. The size of the
12736 returned buffer is written to *size_r. The caller must free the
12737 returned buffer after use.
12738 Because of the message protocol, there is a transfer limit of somewhere
12740 between 2MB and 4MB. See "PROTOCOL LIMITS".
12741 (Added in 1.5.21)
12743 guestfs_pvchange_uuid
12745 int
12746 guestfs_pvchange_uuid (guestfs_h *g,
12747 const char *device);
12748 Generate a new random UUID for the physical volume "device".
12750 This function returns 0 on success or -1 on error.
12752 This function depends on the feature "lvm2". See also
12754 "guestfs_feature_available".
12755 (Added in 1.19.26)
12757 guestfs_pvchange_uuid_all
12759 int
12760 guestfs_pvchange_uuid_all (guestfs_h *g);
12761 Generate new random UUIDs for all physical volumes.
12763 This function returns 0 on success or -1 on error.
12765 This function depends on the feature "lvm2". See also
12767 "guestfs_feature_available".
12768 (Added in 1.19.26)
12770 guestfs_pvcreate
12772 int
12773 guestfs_pvcreate (guestfs_h *g,
12774 const char *device);
12775 This creates an LVM physical volume on the named "device", where
12777 "device" should usually be a partition name such as /dev/sda1.
12778 This function returns 0 on success or -1 on error.
12780 This function depends on the feature "lvm2". See also
12782 "guestfs_feature_available".
12783 (Added in 0.8)
12785 guestfs_pvremove
12787 int
12788 guestfs_pvremove (guestfs_h *g,
12789 const char *device);
12790 This wipes a physical volume "device" so that LVM will no longer
12792 recognise it.
12793 The implementation uses the pvremove(8) command which refuses to wipe
12795 physical volumes that contain any volume groups, so you have to remove
12796 those first.
12797 This function returns 0 on success or -1 on error.
12799 This function depends on the feature "lvm2". See also
12801 "guestfs_feature_available".
12802 (Added in 1.0.13)
12804 guestfs_pvresize
12806 int
12807 guestfs_pvresize (guestfs_h *g,
12808 const char *device);
12809 This resizes (expands or shrinks) an existing LVM physical volume to
12811 match the new size of the underlying device.
12812 This function returns 0 on success or -1 on error.
12814 This function depends on the feature "lvm2". See also
12816 "guestfs_feature_available".
12817 (Added in 1.0.26)
12819 guestfs_pvresize_size
12821 int
12822 guestfs_pvresize_size (guestfs_h *g,
12823 const char *device,
12824 int64_t size);
12825 This command is the same as "guestfs_pvresize" except that it allows
12827 you to specify the new size (in bytes) explicitly.
12828 This function returns 0 on success or -1 on error.
12830 This function depends on the feature "lvm2". See also
12832 "guestfs_feature_available".
12833 (Added in 1.3.14)
12835 guestfs_pvs
12837 char **
12838 guestfs_pvs (guestfs_h *g);
12839 List all the physical volumes detected. This is the equivalent of the
12841 pvs(8) command.
12842 This returns a list of just the device names that contain PVs (eg.
12844 /dev/sda2).
12845 See also "guestfs_pvs_full".
12847 This function returns a NULL-terminated array of strings (like
12849 environ(3)), or NULL if there was an error. The caller must free the
12850 strings and the array after use.
12851 This function depends on the feature "lvm2". See also
12853 "guestfs_feature_available".
12854 (Added in 0.4)
12856 guestfs_pvs_full
12858 struct guestfs_lvm_pv_list *
12859 guestfs_pvs_full (guestfs_h *g);
12860 List all the physical volumes detected. This is the equivalent of the
12862 pvs(8) command. The "full" version includes all fields.
12863 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
12865 there was an error. The caller must call "guestfs_free_lvm_pv_list"
12866 after use.
12867 This function depends on the feature "lvm2". See also
12869 "guestfs_feature_available".
12870 (Added in 0.4)
12872 guestfs_pvuuid
12874 char *
12875 guestfs_pvuuid (guestfs_h *g,
12876 const char *device);
12877 This command returns the UUID of the LVM PV "device".
12879 This function returns a string, or NULL on error. The caller must free
12881 the returned string after use.
12882 (Added in 1.0.87)
12884 guestfs_pwrite
12886 int
12887 guestfs_pwrite (guestfs_h *g,
12888 const char *path,
12889 const char *content,
12890 size_t content_size,
12891 int64_t offset);
12892 This command writes to part of a file. It writes the data buffer
12894 "content" to the file "path" starting at offset "offset".
12895 This command implements the pwrite(2) system call, and like that system
12897 call it may not write the full data requested. The return value is the
12898 number of bytes that were actually written to the file. This could
12899 even be 0, although short writes are unlikely for regular files in
12900 ordinary circumstances.
12901 See also "guestfs_pread", "guestfs_pwrite_device".
12903 On error this function returns -1.
12905 Because of the message protocol, there is a transfer limit of somewhere
12907 between 2MB and 4MB. See "PROTOCOL LIMITS".
12908 (Added in 1.3.14)
12910 guestfs_pwrite_device
12912 int
12913 guestfs_pwrite_device (guestfs_h *g,
12914 const char *device,
12915 const char *content,
12916 size_t content_size,
12917 int64_t offset);
12918 This command writes to part of a device. It writes the data buffer
12920 "content" to "device" starting at offset "offset".
12921 This command implements the pwrite(2) system call, and like that system
12923 call it may not write the full data requested (although short writes to
12924 disk devices and partitions are probably impossible with standard Linux
12925 kernels).
12926 See also "guestfs_pwrite".
12928 On error this function returns -1.
12930 Because of the message protocol, there is a transfer limit of somewhere
12932 between 2MB and 4MB. See "PROTOCOL LIMITS".
12933 (Added in 1.5.20)
12935 guestfs_read_file
12937 char *
12938 guestfs_read_file (guestfs_h *g,
12939 const char *path,
12940 size_t *size_r);
12941 This calls returns the contents of the file "path" as a buffer.
12943 Unlike "guestfs_cat", this function can correctly handle files that
12945 contain embedded ASCII NUL characters.
12946 This function returns a buffer, or NULL on error. The size of the
12948 returned buffer is written to *size_r. The caller must free the
12949 returned buffer after use.
12950 (Added in 1.0.63)
12952 guestfs_read_lines
12954 char **
12955 guestfs_read_lines (guestfs_h *g,
12956 const char *path);
12957 Return the contents of the file named "path".
12959 The file contents are returned as a list of lines. Trailing "LF" and
12961 "CRLF" character sequences are not returned.
12962 Note that this function cannot correctly handle binary files
12964 (specifically, files containing "\0" character which is treated as end
12965 of string). For those you need to use the "guestfs_read_file" function
12966 and split the buffer into lines yourself.
12967 This function returns a NULL-terminated array of strings (like
12969 environ(3)), or NULL if there was an error. The caller must free the
12970 strings and the array after use.
12971 (Added in 0.7)
12973 guestfs_readdir
12975 struct guestfs_dirent_list *
12976 guestfs_readdir (guestfs_h *g,
12977 const char *dir);
12978 This returns the list of directory entries in directory "dir".
12980 All entries in the directory are returned, including "." and "..". The
12982 entries are not sorted, but returned in the same order as the
12983 underlying filesystem.
12984 Also this call returns basic file type information about each file.
12986 The "ftyp" field will contain one of the following characters:
12987 'b' Block special
12989 'c' Char special
12991 'd' Directory
12993 'f' FIFO (named pipe)
12995 'l' Symbolic link
12997 'r' Regular file
12999 's' Socket
13001 'u' Unknown file type
13003 '?' The readdir(3) call returned a "d_type" field with an unexpected
13005 value
13006 This function is primarily intended for use by programs. To get a
13008 simple list of names, use "guestfs_ls". To get a printable directory
13009 for human consumption, use "guestfs_ll".
13010 This function returns a "struct guestfs_dirent_list *", or NULL if
13012 there was an error. The caller must call "guestfs_free_dirent_list"
13013 after use.
13014 Because of the message protocol, there is a transfer limit of somewhere
13016 between 2MB and 4MB. See "PROTOCOL LIMITS".
13017 (Added in 1.0.55)
13019 guestfs_readlink
13021 char *
13022 guestfs_readlink (guestfs_h *g,
13023 const char *path);
13024 This command reads the target of a symbolic link.
13026 This function returns a string, or NULL on error. The caller must free
13028 the returned string after use.
13029 (Added in 1.0.66)
13031 guestfs_readlinklist
13033 char **
13034 guestfs_readlinklist (guestfs_h *g,
13035 const char *path,
13036 char *const *names);
13037 This call allows you to do a "readlink" operation on multiple files,
13039 where all files are in the directory "path". "names" is the list of
13040 files from this directory.
13041 On return you get a list of strings, with a one-to-one correspondence
13043 to the "names" list. Each string is the value of the symbolic link.
13044 If the readlink(2) operation fails on any name, then the corresponding
13046 result string is the empty string "". However the whole operation is
13047 completed even if there were readlink(2) errors, and so you can call
13048 this function with names where you don't know if they are symbolic
13049 links already (albeit slightly less efficient).
13050 This call is intended for programs that want to efficiently list a
13052 directory contents without making many round-trips.
13053 This function returns a NULL-terminated array of strings (like
13055 environ(3)), or NULL if there was an error. The caller must free the
13056 strings and the array after use.
13057 (Added in 1.0.77)
13059 guestfs_realpath
13061 char *
13062 guestfs_realpath (guestfs_h *g,
13063 const char *path);
13064 Return the canonicalized absolute pathname of "path". The returned
13066 path has no ".", ".." or symbolic link path elements.
13067 This function returns a string, or NULL on error. The caller must free
13069 the returned string after use.
13070 (Added in 1.0.66)
13072 guestfs_remount
13074 int
13075 guestfs_remount (guestfs_h *g,
13076 const char *mountpoint,
13077 ...);
13078 You may supply a list of optional arguments to this call. Use zero or
13080 more of the following pairs of parameters, and terminate the list with
13081 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13082 GUESTFS_REMOUNT_RW, int rw,
13084 This call allows you to change the "rw" (readonly/read-write) flag on
13086 an already mounted filesystem at "mountpoint", converting a readonly
13087 filesystem to be read-write, or vice-versa.
13088 Note that at the moment you must supply the "optional" "rw" parameter.
13090 In future we may allow other flags to be adjusted.
13091 This function returns 0 on success or -1 on error.
13093 (Added in 1.23.2)
13095 guestfs_remount_va
13097 int
13098 guestfs_remount_va (guestfs_h *g,
13099 const char *mountpoint,
13100 va_list args);
13101 This is the "va_list variant" of "guestfs_remount".
13103 See "CALLS WITH OPTIONAL ARGUMENTS".
13105 guestfs_remount_argv
13107 int
13108 guestfs_remount_argv (guestfs_h *g,
13109 const char *mountpoint,
13110 const struct guestfs_remount_argv *optargs);
13111 This is the "argv variant" of "guestfs_remount".
13113 See "CALLS WITH OPTIONAL ARGUMENTS".
13115 guestfs_remove_drive
13117 int
13118 guestfs_remove_drive (guestfs_h *g,
13119 const char *label);
13120 This function is deprecated. There is no replacement. Consult the API
13122 documentation in guestfs(3) for further information.
13123 Deprecated functions will not be removed from the API, but the fact
13125 that they are deprecated indicates that there are problems with correct
13126 use of these functions.
13127 This call does nothing and returns an error.
13129 This function returns 0 on success or -1 on error.
13131 (Added in 1.19.49)
13133 guestfs_removexattr
13135 int
13136 guestfs_removexattr (guestfs_h *g,
13137 const char *xattr,
13138 const char *path);
13139 This call removes the extended attribute named "xattr" of the file
13141 "path".
13142 See also: "guestfs_lremovexattr", attr(5).
13144 This function returns 0 on success or -1 on error.
13146 This function depends on the feature "linuxxattrs". See also
13148 "guestfs_feature_available".
13149 (Added in 1.0.59)
13151 guestfs_rename
13153 int
13154 guestfs_rename (guestfs_h *g,
13155 const char *oldpath,
13156 const char *newpath);
13157 Rename a file to a new place on the same filesystem. This is the same
13159 as the Linux rename(2) system call. In most cases you are better to
13160 use "guestfs_mv" instead.
13161 This function returns 0 on success or -1 on error.
13163 (Added in 1.21.5)
13165 guestfs_resize2fs
13167 int
13168 guestfs_resize2fs (guestfs_h *g,
13169 const char *device);
13170 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13172 underlying device.
13173 See also "RESIZE2FS ERRORS".
13175 This function returns 0 on success or -1 on error.
13177 (Added in 1.0.27)
13179 guestfs_resize2fs_M
13181 int
13182 guestfs_resize2fs_M (guestfs_h *g,
13183 const char *device);
13184 This command is the same as "guestfs_resize2fs", but the filesystem is
13186 resized to its minimum size. This works like the -M option to the
13187 resize2fs(8) command.
13188 To get the resulting size of the filesystem you should call
13190 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13191 These two numbers, multiplied together, give the resulting size of the
13192 minimal filesystem in bytes.
13193 See also "RESIZE2FS ERRORS".
13195 This function returns 0 on success or -1 on error.
13197 (Added in 1.9.4)
13199 guestfs_resize2fs_size
13201 int
13202 guestfs_resize2fs_size (guestfs_h *g,
13203 const char *device,
13204 int64_t size);
13205 This command is the same as "guestfs_resize2fs" except that it allows
13207 you to specify the new size (in bytes) explicitly.
13208 See also "RESIZE2FS ERRORS".
13210 This function returns 0 on success or -1 on error.
13212 (Added in 1.3.14)
13214 guestfs_rm
13216 int
13217 guestfs_rm (guestfs_h *g,
13218 const char *path);
13219 Remove the single file "path".
13221 This function returns 0 on success or -1 on error.
13223 (Added in 0.8)
13225 guestfs_rm_f
13227 int
13228 guestfs_rm_f (guestfs_h *g,
13229 const char *path);
13230 Remove the file "path".
13232 If the file doesn't exist, that error is ignored. (Other errors, eg.
13234 I/O errors or bad paths, are not ignored)
13235 This call cannot remove directories. Use "guestfs_rmdir" to remove an
13237 empty directory, or "guestfs_rm_rf" to remove directories recursively.
13238 This function returns 0 on success or -1 on error.
13240 (Added in 1.19.42)
13242 guestfs_rm_rf
13244 int
13245 guestfs_rm_rf (guestfs_h *g,
13246 const char *path);
13247 Remove the file or directory "path", recursively removing the contents
13249 if its a directory. This is like the "rm -rf" shell command.
13250 This function returns 0 on success or -1 on error.
13252 (Added in 0.8)
13254 guestfs_rmdir
13256 int
13257 guestfs_rmdir (guestfs_h *g,
13258 const char *path);
13259 Remove the single directory "path".
13261 This function returns 0 on success or -1 on error.
13263 (Added in 0.8)
13265 guestfs_rmmountpoint
13267 int
13268 guestfs_rmmountpoint (guestfs_h *g,
13269 const char *exemptpath);
13270 This call removes a mountpoint that was previously created with
13272 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13273 This function returns 0 on success or -1 on error.
13275 (Added in 1.0.62)
13277 guestfs_rsync
13279 int
13280 guestfs_rsync (guestfs_h *g,
13281 const char *src,
13282 const char *dest,
13283 ...);
13284 You may supply a list of optional arguments to this call. Use zero or
13286 more of the following pairs of parameters, and terminate the list with
13287 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13288 GUESTFS_RSYNC_ARCHIVE, int archive,
13290 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13291 This call may be used to copy or synchronize two directories under the
13293 same libguestfs handle. This uses the rsync(1) program which uses a
13294 fast algorithm that avoids copying files unnecessarily.
13295 "src" and "dest" are the source and destination directories. Files are
13297 copied from "src" to "dest".
13298 The optional arguments are:
13300 "archive"
13302 Turns on archive mode. This is the same as passing the --archive
13303 flag to "rsync".
13304 "deletedest"
13306 Delete files at the destination that do not exist at the source.
13307 This function returns 0 on success or -1 on error.
13309 This function depends on the feature "rsync". See also
13311 "guestfs_feature_available".
13312 (Added in 1.19.29)
13314 guestfs_rsync_va
13316 int
13317 guestfs_rsync_va (guestfs_h *g,
13318 const char *src,
13319 const char *dest,
13320 va_list args);
13321 This is the "va_list variant" of "guestfs_rsync".
13323 See "CALLS WITH OPTIONAL ARGUMENTS".
13325 guestfs_rsync_argv
13327 int
13328 guestfs_rsync_argv (guestfs_h *g,
13329 const char *src,
13330 const char *dest,
13331 const struct guestfs_rsync_argv *optargs);
13332 This is the "argv variant" of "guestfs_rsync".
13334 See "CALLS WITH OPTIONAL ARGUMENTS".
13336 guestfs_rsync_in
13338 int
13339 guestfs_rsync_in (guestfs_h *g,
13340 const char *remote,
13341 const char *dest,
13342 ...);
13343 You may supply a list of optional arguments to this call. Use zero or
13345 more of the following pairs of parameters, and terminate the list with
13346 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13347 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13349 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13350 This call may be used to copy or synchronize the filesystem on the host
13352 or on a remote computer with the filesystem within libguestfs. This
13353 uses the rsync(1) program which uses a fast algorithm that avoids
13354 copying files unnecessarily.
13355 This call only works if the network is enabled. See
13357 "guestfs_set_network" or the --network option to various tools like
13358 guestfish(1).
13359 Files are copied from the remote server and directory specified by
13361 "remote" to the destination directory "dest".
13362 The format of the remote server string is defined by rsync(1). Note
13364 that there is no way to supply a password or passphrase so the target
13365 must be set up not to require one.
13366 The optional arguments are the same as those of "guestfs_rsync".
13368 This function returns 0 on success or -1 on error.
13370 This function depends on the feature "rsync". See also
13372 "guestfs_feature_available".
13373 (Added in 1.19.29)
13375 guestfs_rsync_in_va
13377 int
13378 guestfs_rsync_in_va (guestfs_h *g,
13379 const char *remote,
13380 const char *dest,
13381 va_list args);
13382 This is the "va_list variant" of "guestfs_rsync_in".
13384 See "CALLS WITH OPTIONAL ARGUMENTS".
13386 guestfs_rsync_in_argv
13388 int
13389 guestfs_rsync_in_argv (guestfs_h *g,
13390 const char *remote,
13391 const char *dest,
13392 const struct guestfs_rsync_in_argv *optargs);
13393 This is the "argv variant" of "guestfs_rsync_in".
13395 See "CALLS WITH OPTIONAL ARGUMENTS".
13397 guestfs_rsync_out
13399 int
13400 guestfs_rsync_out (guestfs_h *g,
13401 const char *src,
13402 const char *remote,
13403 ...);
13404 You may supply a list of optional arguments to this call. Use zero or
13406 more of the following pairs of parameters, and terminate the list with
13407 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13408 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13410 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13411 This call may be used to copy or synchronize the filesystem within
13413 libguestfs with a filesystem on the host or on a remote computer. This
13414 uses the rsync(1) program which uses a fast algorithm that avoids
13415 copying files unnecessarily.
13416 This call only works if the network is enabled. See
13418 "guestfs_set_network" or the --network option to various tools like
13419 guestfish(1).
13420 Files are copied from the source directory "src" to the remote server
13422 and directory specified by "remote".
13423 The format of the remote server string is defined by rsync(1). Note
13425 that there is no way to supply a password or passphrase so the target
13426 must be set up not to require one.
13427 The optional arguments are the same as those of "guestfs_rsync".
13429 Globbing does not happen on the "src" parameter. In programs which use
13431 the API directly you have to expand wildcards yourself (see
13432 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13433 (see "glob" in guestfish(1)), for example:
13434 ><fs> glob rsync-out /* rsync://remote/
13436 This function returns 0 on success or -1 on error.
13438 This function depends on the feature "rsync". See also
13440 "guestfs_feature_available".
13441 (Added in 1.19.29)
13443 guestfs_rsync_out_va
13445 int
13446 guestfs_rsync_out_va (guestfs_h *g,
13447 const char *src,
13448 const char *remote,
13449 va_list args);
13450 This is the "va_list variant" of "guestfs_rsync_out".
13452 See "CALLS WITH OPTIONAL ARGUMENTS".
13454 guestfs_rsync_out_argv
13456 int
13457 guestfs_rsync_out_argv (guestfs_h *g,
13458 const char *src,
13459 const char *remote,
13460 const struct guestfs_rsync_out_argv *optargs);
13461 This is the "argv variant" of "guestfs_rsync_out".
13463 See "CALLS WITH OPTIONAL ARGUMENTS".
13465 guestfs_scrub_device
13467 int
13468 guestfs_scrub_device (guestfs_h *g,
13469 const char *device);
13470 This command writes patterns over "device" to make data retrieval more
13472 difficult.
13473 It is an interface to the scrub(1) program. See that manual page for
13475 more details.
13476 This function returns 0 on success or -1 on error.
13478 This function depends on the feature "scrub". See also
13480 "guestfs_feature_available".
13481 (Added in 1.0.52)
13483 guestfs_scrub_file
13485 int
13486 guestfs_scrub_file (guestfs_h *g,
13487 const char *file);
13488 This command writes patterns over a file to make data retrieval more
13490 difficult.
13491 The file is removed after scrubbing.
13493 It is an interface to the scrub(1) program. See that manual page for
13495 more details.
13496 This function returns 0 on success or -1 on error.
13498 This function depends on the feature "scrub". See also
13500 "guestfs_feature_available".
13501 (Added in 1.0.52)
13503 guestfs_scrub_freespace
13505 int
13506 guestfs_scrub_freespace (guestfs_h *g,
13507 const char *dir);
13508 This command creates the directory "dir" and then fills it with files
13510 until the filesystem is full, and scrubs the files as for
13511 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13512 free space on the partition containing "dir".
13513 It is an interface to the scrub(1) program. See that manual page for
13515 more details.
13516 This function returns 0 on success or -1 on error.
13518 This function depends on the feature "scrub". See also
13520 "guestfs_feature_available".
13521 (Added in 1.0.52)
13523 guestfs_selinux_relabel
13525 int
13526 guestfs_selinux_relabel (guestfs_h *g,
13527 const char *specfile,
13528 const char *path,
13529 ...);
13530 You may supply a list of optional arguments to this call. Use zero or
13532 more of the following pairs of parameters, and terminate the list with
13533 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13534 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13536 SELinux relabel parts of the filesystem.
13538 The "specfile" parameter controls the policy spec file used. You have
13540 to parse "/etc/selinux/config" to find the correct SELinux policy and
13541 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13542 "/contexts/files/file_contexts".
13543 The required "path" parameter is the top level directory where
13545 relabelling starts. Normally you should pass "path" as "/" to relabel
13546 the whole guest filesystem.
13547 The optional "force" boolean controls whether the context is reset for
13549 customizable files, and also whether the user, role and range parts of
13550 the file context is changed.
13551 This function returns 0 on success or -1 on error.
13553 This function depends on the feature "selinuxrelabel". See also
13555 "guestfs_feature_available".
13556 (Added in 1.33.43)
13558 guestfs_selinux_relabel_va
13560 int
13561 guestfs_selinux_relabel_va (guestfs_h *g,
13562 const char *specfile,
13563 const char *path,
13564 va_list args);
13565 This is the "va_list variant" of "guestfs_selinux_relabel".
13567 See "CALLS WITH OPTIONAL ARGUMENTS".
13569 guestfs_selinux_relabel_argv
13571 int
13572 guestfs_selinux_relabel_argv (guestfs_h *g,
13573 const char *specfile,
13574 const char *path,
13575 const struct guestfs_selinux_relabel_argv *optargs);
13576 This is the "argv variant" of "guestfs_selinux_relabel".
13578 See "CALLS WITH OPTIONAL ARGUMENTS".
13580 guestfs_set_append
13582 int
13583 guestfs_set_append (guestfs_h *g,
13584 const char *append);
13585 This function is used to add additional options to the libguestfs
13587 appliance kernel command line.
13588 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13590 environment variable.
13591 Setting "append" to "NULL" means no additional options are passed
13593 (libguestfs always adds a few of its own).
13594 This function returns 0 on success or -1 on error.
13596 (Added in 1.0.26)
13598 guestfs_set_attach_method
13600 int
13601 guestfs_set_attach_method (guestfs_h *g,
13602 const char *backend);
13603 This function is deprecated. In new code, use the
13605 "guestfs_set_backend" call instead.
13606 Deprecated functions will not be removed from the API, but the fact
13608 that they are deprecated indicates that there are problems with correct
13609 use of these functions.
13610 Set the method that libguestfs uses to connect to the backend guestfsd
13612 daemon.
13613 See "BACKEND".
13615 This function returns 0 on success or -1 on error.
13617 (Added in 1.9.8)
13619 guestfs_set_autosync
13621 int
13622 guestfs_set_autosync (guestfs_h *g,
13623 int autosync);
13624 If "autosync" is true, this enables autosync. Libguestfs will make a
13626 best effort attempt to make filesystems consistent and synchronized
13627 when the handle is closed (also if the program exits without closing
13628 handles).
13629 This is enabled by default (since libguestfs 1.5.24, previously it was
13631 disabled by default).
13632 This function returns 0 on success or -1 on error.
13634 (Added in 0.3)
13636 guestfs_set_backend
13638 int
13639 guestfs_set_backend (guestfs_h *g,
13640 const char *backend);
13641 Set the method that libguestfs uses to connect to the backend guestfsd
13643 daemon.
13644 This handle property was previously called the "attach method".
13646 See "BACKEND".
13648 This function returns 0 on success or -1 on error.
13650 (Added in 1.21.26)
13652 guestfs_set_backend_setting
13654 int
13655 guestfs_set_backend_setting (guestfs_h *g,
13656 const char *name,
13657 const char *val);
13658 Append "name=value" to the backend settings string list. However if a
13660 string already exists matching "name" or beginning with "name=", then
13661 that setting is replaced.
13662 See "BACKEND", "BACKEND SETTINGS".
13664 This function returns 0 on success or -1 on error.
13666 (Added in 1.27.2)
13668 guestfs_set_backend_settings
13670 int
13671 guestfs_set_backend_settings (guestfs_h *g,
13672 char *const *settings);
13673 Set a list of zero or more settings which are passed through to the
13675 current backend. Each setting is a string which is interpreted in a
13676 backend-specific way, or ignored if not understood by the backend.
13677 The default value is an empty list, unless the environment variable
13679 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13680 This environment variable contains a colon-separated list of settings.
13681 This call replaces all backend settings. If you want to replace a
13683 single backend setting, see "guestfs_set_backend_setting". If you want
13684 to clear a single backend setting, see "guestfs_clear_backend_setting".
13685 See "BACKEND", "BACKEND SETTINGS".
13687 This function returns 0 on success or -1 on error.
13689 (Added in 1.25.24)
13691 guestfs_set_cachedir
13693 int
13694 guestfs_set_cachedir (guestfs_h *g,
13695 const char *cachedir);
13696 Set the directory used by the handle to store the appliance cache, when
13698 using a supermin appliance. The appliance is cached and shared between
13699 all handles which have the same effective user ID.
13700 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13702 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13703 default. Else if "TMPDIR" is set, then that is the default. Else
13704 /var/tmp is the default.
13705 This function returns 0 on success or -1 on error.
13707 (Added in 1.19.58)
13709 guestfs_set_direct
13711 int
13712 guestfs_set_direct (guestfs_h *g,
13713 int direct);
13714 This function is deprecated. In new code, use the
13716 "guestfs_internal_get_console_socket" call instead.
13717 Deprecated functions will not be removed from the API, but the fact
13719 that they are deprecated indicates that there are problems with correct
13720 use of these functions.
13721 If the direct appliance mode flag is enabled, then stdin and stdout are
13723 passed directly through to the appliance once it is launched.
13724 One consequence of this is that log messages aren't caught by the
13726 library and handled by "guestfs_set_log_message_callback", but go
13727 straight to stdout.
13728 You probably don't want to use this unless you know what you are doing.
13730 The default is disabled.
13732 This function returns 0 on success or -1 on error.
13734 (Added in 1.0.72)
13736 guestfs_set_e2attrs
13738 int
13739 guestfs_set_e2attrs (guestfs_h *g,
13740 const char *file,
13741 const char *attrs,
13742 ...);
13743 You may supply a list of optional arguments to this call. Use zero or
13745 more of the following pairs of parameters, and terminate the list with
13746 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13747 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13749 This sets or clears the file attributes "attrs" associated with the
13751 inode file.
13752 "attrs" is a string of characters representing file attributes. See
13754 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13755 attributes can be changed.
13756 If optional boolean "clear" is not present or false, then the "attrs"
13758 listed are set in the inode.
13759 If "clear" is true, then the "attrs" listed are cleared in the inode.
13761 In both cases, other attributes not present in the "attrs" string are
13763 left unchanged.
13764 These attributes are only present when the file is located on an
13766 ext2/3/4 filesystem. Using this call on other filesystem types will
13767 result in an error.
13768 This function returns 0 on success or -1 on error.
13770 (Added in 1.17.31)
13772 guestfs_set_e2attrs_va
13774 int
13775 guestfs_set_e2attrs_va (guestfs_h *g,
13776 const char *file,
13777 const char *attrs,
13778 va_list args);
13779 This is the "va_list variant" of "guestfs_set_e2attrs".
13781 See "CALLS WITH OPTIONAL ARGUMENTS".
13783 guestfs_set_e2attrs_argv
13785 int
13786 guestfs_set_e2attrs_argv (guestfs_h *g,
13787 const char *file,
13788 const char *attrs,
13789 const struct guestfs_set_e2attrs_argv *optargs);
13790 This is the "argv variant" of "guestfs_set_e2attrs".
13792 See "CALLS WITH OPTIONAL ARGUMENTS".
13794 guestfs_set_e2generation
13796 int
13797 guestfs_set_e2generation (guestfs_h *g,
13798 const char *file,
13799 int64_t generation);
13800 This sets the ext2 file generation of a file.
13802 See "guestfs_get_e2generation".
13804 This function returns 0 on success or -1 on error.
13806 (Added in 1.17.31)
13808 guestfs_set_e2label
13810 int
13811 guestfs_set_e2label (guestfs_h *g,
13812 const char *device,
13813 const char *label);
13814 This function is deprecated. In new code, use the "guestfs_set_label"
13816 call instead.
13817 Deprecated functions will not be removed from the API, but the fact
13819 that they are deprecated indicates that there are problems with correct
13820 use of these functions.
13821 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13823 to "label". Filesystem labels are limited to 16 characters.
13824 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13826 return the existing label on a filesystem.
13827 This function returns 0 on success or -1 on error.
13829 (Added in 1.0.15)
13831 guestfs_set_e2uuid
13833 int
13834 guestfs_set_e2uuid (guestfs_h *g,
13835 const char *device,
13836 const char *uuid);
13837 This function is deprecated. In new code, use the "guestfs_set_uuid"
13839 call instead.
13840 Deprecated functions will not be removed from the API, but the fact
13842 that they are deprecated indicates that there are problems with correct
13843 use of these functions.
13844 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
13846 "uuid". The format of the UUID and alternatives such as "clear",
13847 "random" and "time" are described in the tune2fs(8) manpage.
13848 You can use "guestfs_vfs_uuid" to return the existing UUID of a
13850 filesystem.
13851 This function returns 0 on success or -1 on error.
13853 (Added in 1.0.15)
13855 guestfs_set_hv
13857 int
13858 guestfs_set_hv (guestfs_h *g,
13859 const char *hv);
13860 Set the hypervisor binary that we will use. The hypervisor depends on
13862 the backend, but is usually the location of the qemu/KVM hypervisor.
13863 The default is chosen when the library was compiled by the configure
13865 script.
13866 You can also override this by setting the "LIBGUESTFS_HV" environment
13868 variable.
13869 Note that you should call this function as early as possible after
13871 creating the handle. This is because some pre-launch operations depend
13872 on testing qemu features (by running "qemu -help"). If the qemu binary
13873 changes, we don't retest features, and so you might see inconsistent
13874 results. Using the environment variable "LIBGUESTFS_HV" is safest of
13875 all since that picks the qemu binary at the same time as the handle is
13876 created.
13877 This function returns 0 on success or -1 on error.
13879 (Added in 1.23.17)
13881 guestfs_set_identifier
13883 int
13884 guestfs_set_identifier (guestfs_h *g,
13885 const char *identifier);
13886 This is an informative string which the caller may optionally set in
13888 the handle. It is printed in various places, allowing the current
13889 handle to be identified in debugging output.
13890 One important place is when tracing is enabled. If the identifier
13892 string is not an empty string, then trace messages change from this:
13893 libguestfs: trace: get_tmpdir
13895 libguestfs: trace: get_tmpdir = "/tmp"
13896 to this:
13898 libguestfs: trace: ID: get_tmpdir
13900 libguestfs: trace: ID: get_tmpdir = "/tmp"
13901 where "ID" is the identifier string set by this call.
13903 The identifier must only contain alphanumeric ASCII characters,
13905 underscore and minus sign. The default is the empty string.
13906 See also "guestfs_set_program", "guestfs_set_trace",
13908 "guestfs_get_identifier".
13909 This function returns 0 on success or -1 on error.
13911 (Added in 1.31.14)
13913 guestfs_set_label
13915 int
13916 guestfs_set_label (guestfs_h *g,
13917 const char *mountable,
13918 const char *label);
13919 Set the filesystem label on "mountable" to "label".
13921 Only some filesystem types support labels, and libguestfs supports
13923 setting labels on only a subset of these.
13924 ext2, ext3, ext4
13926 Labels are limited to 16 bytes.
13927 NTFS
13929 Labels are limited to 128 unicode characters.
13930 XFS The label is limited to 12 bytes. The filesystem must not be
13932 mounted when trying to set the label.
13933 btrfs
13935 The label is limited to 255 bytes and some characters are not
13936 allowed. Setting the label on a btrfs subvolume will set the label
13937 on its parent filesystem. The filesystem must not be mounted when
13938 trying to set the label.
13939 fat The label is limited to 11 bytes.
13941 swap
13943 The label is limited to 16 bytes.
13944 If there is no support for changing the label for the type of the
13946 specified filesystem, set_label will fail and set errno as ENOTSUP.
13947 To read the label on a filesystem, call "guestfs_vfs_label".
13949 This function returns 0 on success or -1 on error.
13951 (Added in 1.17.9)
13953 guestfs_set_libvirt_requested_credential
13955 int
13956 guestfs_set_libvirt_requested_credential (guestfs_h *g,
13957 int index,
13958 const char *cred,
13959 size_t cred_size);
13960 After requesting the "index"'th credential from the user, call this
13962 function to pass the answer back to libvirt.
13963 See "LIBVIRT AUTHENTICATION" for documentation and example code.
13965 This function returns 0 on success or -1 on error.
13967 (Added in 1.19.52)
13969 guestfs_set_libvirt_supported_credentials
13971 int
13972 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
13973 char *const *creds);
13974 Call this function before setting an event handler for
13976 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
13977 that the program knows how to process.
13978 The "creds" list must be a non-empty list of strings. Possible strings
13980 are:
13981 "username"
13983 "authname"
13984 "language"
13985 "cnonce"
13986 "passphrase"
13987 "echoprompt"
13988 "noechoprompt"
13989 "realm"
13990 "external"
13991 See libvirt documentation for the meaning of these credential types.
13993 See "LIBVIRT AUTHENTICATION" for documentation and example code.
13995 This function returns 0 on success or -1 on error.
13997 (Added in 1.19.52)
13999 guestfs_set_memsize
14001 int
14002 guestfs_set_memsize (guestfs_h *g,
14003 int memsize);
14004 This sets the memory size in megabytes allocated to the hypervisor.
14006 This only has any effect if called before "guestfs_launch".
14007 You can also change this by setting the environment variable
14009 "LIBGUESTFS_MEMSIZE" before the handle is created.
14010 For more information on the architecture of libguestfs, see guestfs(3).
14012 This function returns 0 on success or -1 on error.
14014 (Added in 1.0.55)
14016 guestfs_set_network
14018 int
14019 guestfs_set_network (guestfs_h *g,
14020 int network);
14021 If "network" is true, then the network is enabled in the libguestfs
14023 appliance. The default is false.
14024 This affects whether commands are able to access the network (see
14026 "RUNNING COMMANDS").
14027 You must call this before calling "guestfs_launch", otherwise it has no
14029 effect.
14030 This function returns 0 on success or -1 on error.
14032 (Added in 1.5.4)
14034 guestfs_set_path
14036 int
14037 guestfs_set_path (guestfs_h *g,
14038 const char *searchpath);
14039 Set the path that libguestfs searches for kernel and initrd.img.
14041 The default is "$libdir/guestfs" unless overridden by setting
14043 "LIBGUESTFS_PATH" environment variable.
14044 Setting "path" to "NULL" restores the default path.
14046 This function returns 0 on success or -1 on error.
14048 (Added in 0.3)
14050 guestfs_set_pgroup
14052 int
14053 guestfs_set_pgroup (guestfs_h *g,
14054 int pgroup);
14055 If "pgroup" is true, child processes are placed into their own process
14057 group.
14058 The practical upshot of this is that signals like "SIGINT" (from users
14060 pressing "^C") won't be received by the child process.
14061 The default for this flag is false, because usually you want "^C" to
14063 kill the subprocess. Guestfish sets this flag to true when used
14064 interactively, so that "^C" can cancel long-running commands gracefully
14065 (see "guestfs_user_cancel").
14066 This function returns 0 on success or -1 on error.
14068 (Added in 1.11.18)
14070 guestfs_set_program
14072 int
14073 guestfs_set_program (guestfs_h *g,
14074 const char *program);
14075 Set the program name. This is an informative string which the main
14077 program may optionally set in the handle.
14078 When the handle is created, the program name in the handle is set to
14080 the basename from "argv[0]". The program name can never be "NULL".
14081 This function returns 0 on success or -1 on error.
14083 (Added in 1.21.29)
14085 guestfs_set_qemu
14087 int
14088 guestfs_set_qemu (guestfs_h *g,
14089 const char *hv);
14090 This function is deprecated. In new code, use the "guestfs_set_hv"
14092 call instead.
14093 Deprecated functions will not be removed from the API, but the fact
14095 that they are deprecated indicates that there are problems with correct
14096 use of these functions.
14097 Set the hypervisor binary (usually qemu) that we will use.
14099 The default is chosen when the library was compiled by the configure
14101 script.
14102 You can also override this by setting the "LIBGUESTFS_HV" environment
14104 variable.
14105 Setting "hv" to "NULL" restores the default qemu binary.
14107 Note that you should call this function as early as possible after
14109 creating the handle. This is because some pre-launch operations depend
14110 on testing qemu features (by running "qemu -help"). If the qemu binary
14111 changes, we don't retest features, and so you might see inconsistent
14112 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14113 all since that picks the qemu binary at the same time as the handle is
14114 created.
14115 This function returns 0 on success or -1 on error.
14117 (Added in 1.0.6)
14119 guestfs_set_recovery_proc
14121 int
14122 guestfs_set_recovery_proc (guestfs_h *g,
14123 int recoveryproc);
14124 If this is called with the parameter "false" then "guestfs_launch" does
14126 not create a recovery process. The purpose of the recovery process is
14127 to stop runaway hypervisor processes in the case where the main program
14128 aborts abruptly.
14129 This only has any effect if called before "guestfs_launch", and the
14131 default is true.
14132 About the only time when you would want to disable this is if the main
14134 process will fork itself into the background ("daemonize" itself). In
14135 this case the recovery process thinks that the main program has
14136 disappeared and so kills the hypervisor, which is not very helpful.
14137 This function returns 0 on success or -1 on error.
14139 (Added in 1.0.77)
14141 guestfs_set_selinux
14143 int
14144 guestfs_set_selinux (guestfs_h *g,
14145 int selinux);
14146 This function is deprecated. In new code, use the
14148 "guestfs_selinux_relabel" call instead.
14149 Deprecated functions will not be removed from the API, but the fact
14151 that they are deprecated indicates that there are problems with correct
14152 use of these functions.
14153 This sets the selinux flag that is passed to the appliance at boot
14155 time. The default is "selinux=0" (disabled).
14156 Note that if SELinux is enabled, it is always in Permissive mode
14158 ("enforcing=0").
14159 For more information on the architecture of libguestfs, see guestfs(3).
14161 This function returns 0 on success or -1 on error.
14163 (Added in 1.0.67)
14165 guestfs_set_smp
14167 int
14168 guestfs_set_smp (guestfs_h *g,
14169 int smp);
14170 Change the number of virtual CPUs assigned to the appliance. The
14172 default is 1. Increasing this may improve performance, though often it
14173 has no effect.
14174 This function must be called before "guestfs_launch".
14176 This function returns 0 on success or -1 on error.
14178 (Added in 1.13.15)
14180 guestfs_set_tmpdir
14182 int
14183 guestfs_set_tmpdir (guestfs_h *g,
14184 const char *tmpdir);
14185 Set the directory used by the handle to store temporary files.
14187 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14189 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14190 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
14191 default.
14192 This function returns 0 on success or -1 on error.
14194 (Added in 1.19.58)
14196 guestfs_set_trace
14198 int
14199 guestfs_set_trace (guestfs_h *g,
14200 int trace);
14201 If the command trace flag is set to 1, then libguestfs calls,
14203 parameters and return values are traced.
14204 If you want to trace C API calls into libguestfs (and other libraries)
14206 then possibly a better way is to use the external ltrace(1) command.
14207 Command traces are disabled unless the environment variable
14209 "LIBGUESTFS_TRACE" is defined and set to 1.
14210 Trace messages are normally sent to "stderr", unless you register a
14212 callback to send them somewhere else (see
14213 "guestfs_set_event_callback").
14214 This function returns 0 on success or -1 on error.
14216 (Added in 1.0.69)
14218 guestfs_set_uuid
14220 int
14221 guestfs_set_uuid (guestfs_h *g,
14222 const char *device,
14223 const char *uuid);
14224 Set the filesystem UUID on "device" to "uuid". If this fails and the
14226 errno is ENOTSUP, means that there is no support for changing the UUID
14227 for the type of the specified filesystem.
14228 Only some filesystem types support setting UUIDs.
14230 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14232 This function returns 0 on success or -1 on error.
14234 (Added in 1.23.10)
14236 guestfs_set_uuid_random
14238 int
14239 guestfs_set_uuid_random (guestfs_h *g,
14240 const char *device);
14241 Set the filesystem UUID on "device" to a random UUID. If this fails
14243 and the errno is ENOTSUP, means that there is no support for changing
14244 the UUID for the type of the specified filesystem.
14245 Only some filesystem types support setting UUIDs.
14247 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14249 This function returns 0 on success or -1 on error.
14251 (Added in 1.29.50)
14253 guestfs_set_verbose
14255 int
14256 guestfs_set_verbose (guestfs_h *g,
14257 int verbose);
14258 If "verbose" is true, this turns on verbose messages.
14260 Verbose messages are disabled unless the environment variable
14262 "LIBGUESTFS_DEBUG" is defined and set to 1.
14263 Verbose messages are normally sent to "stderr", unless you register a
14265 callback to send them somewhere else (see
14266 "guestfs_set_event_callback").
14267 This function returns 0 on success or -1 on error.
14269 (Added in 0.3)
14271 guestfs_setcon
14273 int
14274 guestfs_setcon (guestfs_h *g,
14275 const char *context);
14276 This function is deprecated. In new code, use the
14278 "guestfs_selinux_relabel" call instead.
14279 Deprecated functions will not be removed from the API, but the fact
14281 that they are deprecated indicates that there are problems with correct
14282 use of these functions.
14283 This sets the SELinux security context of the daemon to the string
14285 "context".
14286 See the documentation about SELINUX in guestfs(3).
14288 This function returns 0 on success or -1 on error.
14290 This function depends on the feature "selinux". See also
14292 "guestfs_feature_available".
14293 (Added in 1.0.67)
14295 guestfs_setxattr
14297 int
14298 guestfs_setxattr (guestfs_h *g,
14299 const char *xattr,
14300 const char *val,
14301 int vallen,
14302 const char *path);
14303 This call sets the extended attribute named "xattr" of the file "path"
14305 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14306 data.
14307 See also: "guestfs_lsetxattr", attr(5).
14309 This function returns 0 on success or -1 on error.
14311 This function depends on the feature "linuxxattrs". See also
14313 "guestfs_feature_available".
14314 (Added in 1.0.59)
14316 guestfs_sfdisk
14318 int
14319 guestfs_sfdisk (guestfs_h *g,
14320 const char *device,
14321 int cyls,
14322 int heads,
14323 int sectors,
14324 char *const *lines);
14325 This function is deprecated. In new code, use the "guestfs_part_add"
14327 call instead.
14328 Deprecated functions will not be removed from the API, but the fact
14330 that they are deprecated indicates that there are problems with correct
14331 use of these functions.
14332 This is a direct interface to the sfdisk(8) program for creating
14334 partitions on block devices.
14335 "device" should be a block device, for example /dev/sda.
14337 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14339 sectors on the device, which are passed directly to sfdisk(8) as the
14340 -C, -H and -S parameters. If you pass 0 for any of these, then the
14341 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14342 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
14343 (or rather, the kernel) cannot work out the right geometry and you will
14344 need to tell it.
14345 "lines" is a list of lines that we feed to sfdisk(8). For more
14347 information refer to the sfdisk(8) manpage.
14348 To create a single partition occupying the whole disk, you would pass
14350 "lines" as a single element list, when the single element being the
14351 string "," (comma).
14352 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14354 This function returns 0 on success or -1 on error.
14356 (Added in 0.8)
14358 guestfs_sfdiskM
14360 int
14361 guestfs_sfdiskM (guestfs_h *g,
14362 const char *device,
14363 char *const *lines);
14364 This function is deprecated. In new code, use the "guestfs_part_add"
14366 call instead.
14367 Deprecated functions will not be removed from the API, but the fact
14369 that they are deprecated indicates that there are problems with correct
14370 use of these functions.
14371 This is a simplified interface to the "guestfs_sfdisk" command, where
14373 partition sizes are specified in megabytes only (rounded to the nearest
14374 cylinder) and you don't need to specify the cyls, heads and sectors
14375 parameters which were rarely if ever used anyway.
14376 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14378 "guestfs_part_disk"
14379 This function returns 0 on success or -1 on error.
14381 (Added in 1.0.55)
14383 guestfs_sfdisk_N
14385 int
14386 guestfs_sfdisk_N (guestfs_h *g,
14387 const char *device,
14388 int partnum,
14389 int cyls,
14390 int heads,
14391 int sectors,
14392 const char *line);
14393 This function is deprecated. In new code, use the "guestfs_part_add"
14395 call instead.
14396 Deprecated functions will not be removed from the API, but the fact
14398 that they are deprecated indicates that there are problems with correct
14399 use of these functions.
14400 This runs sfdisk(8) option to modify just the single partition "n"
14402 (note: "n" counts from 1).
14403 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14405 for the cyls/heads/sectors parameters.
14406 See also: "guestfs_part_add"
14408 This function returns 0 on success or -1 on error.
14410 (Added in 1.0.26)
14412 guestfs_sfdisk_disk_geometry
14414 char *
14415 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14416 const char *device);
14417 This displays the disk geometry of "device" read from the partition
14419 table. Especially in the case where the underlying block device has
14420 been resized, this can be different from the kernel’s idea of the
14421 geometry (see "guestfs_sfdisk_kernel_geometry").
14422 The result is in human-readable format, and not designed to be parsed.
14424 This function returns a string, or NULL on error. The caller must free
14426 the returned string after use.
14427 (Added in 1.0.26)
14429 guestfs_sfdisk_kernel_geometry
14431 char *
14432 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14433 const char *device);
14434 This displays the kernel’s idea of the geometry of "device".
14436 The result is in human-readable format, and not designed to be parsed.
14438 This function returns a string, or NULL on error. The caller must free
14440 the returned string after use.
14441 (Added in 1.0.26)
14443 guestfs_sfdisk_l
14445 char *
14446 guestfs_sfdisk_l (guestfs_h *g,
14447 const char *device);
14448 This function is deprecated. In new code, use the "guestfs_part_list"
14450 call instead.
14451 Deprecated functions will not be removed from the API, but the fact
14453 that they are deprecated indicates that there are problems with correct
14454 use of these functions.
14455 This displays the partition table on "device", in the human-readable
14457 output of the sfdisk(8) command. It is not intended to be parsed.
14458 See also: "guestfs_part_list"
14460 This function returns a string, or NULL on error. The caller must free
14462 the returned string after use.
14463 (Added in 1.0.26)
14465 guestfs_sh
14467 char *
14468 guestfs_sh (guestfs_h *g,
14469 const char *command);
14470 This call runs a command from the guest filesystem via the guest’s
14472 /bin/sh.
14473 This is like "guestfs_command", but passes the command to:
14475 /bin/sh -c "command"
14477 Depending on the guest’s shell, this usually results in wildcards being
14479 expanded, shell expressions being interpolated and so on.
14480 All the provisos about "guestfs_command" apply to this call.
14482 This function returns a string, or NULL on error. The caller must free
14484 the returned string after use.
14485 (Added in 1.0.50)
14487 guestfs_sh_lines
14489 char **
14490 guestfs_sh_lines (guestfs_h *g,
14491 const char *command);
14492 This is the same as "guestfs_sh", but splits the result into a list of
14494 lines.
14495 See also: "guestfs_command_lines"
14497 This function returns a NULL-terminated array of strings (like
14499 environ(3)), or NULL if there was an error. The caller must free the
14500 strings and the array after use.
14501 (Added in 1.0.50)
14503 guestfs_shutdown
14505 int
14506 guestfs_shutdown (guestfs_h *g);
14507 This is the opposite of "guestfs_launch". It performs an orderly
14509 shutdown of the backend process(es). If the autosync flag is set
14510 (which is the default) then the disk image is synchronized.
14511 If the subprocess exits with an error then this function will return an
14513 error, which should not be ignored (it may indicate that the disk image
14514 could not be written out properly).
14515 It is safe to call this multiple times. Extra calls are ignored.
14517 This call does not close or free up the handle. You still need to call
14519 "guestfs_close" afterwards.
14520 "guestfs_close" will call this if you don't do it explicitly, but note
14522 that any errors are ignored in that case.
14523 This function returns 0 on success or -1 on error.
14525 (Added in 1.19.16)
14527 guestfs_sleep
14529 int
14530 guestfs_sleep (guestfs_h *g,
14531 int secs);
14532 Sleep for "secs" seconds.
14534 This function returns 0 on success or -1 on error.
14536 (Added in 1.0.41)
14538 guestfs_stat
14540 struct guestfs_stat *
14541 guestfs_stat (guestfs_h *g,
14542 const char *path);
14543 This function is deprecated. In new code, use the "guestfs_statns"
14545 call instead.
14546 Deprecated functions will not be removed from the API, but the fact
14548 that they are deprecated indicates that there are problems with correct
14549 use of these functions.
14550 Returns file information for the given "path".
14552 This is the same as the stat(2) system call.
14554 This function returns a "struct guestfs_stat *", or NULL if there was
14556 an error. The caller must call "guestfs_free_stat" after use.
14557 (Added in 1.9.2)
14559 guestfs_statns
14561 struct guestfs_statns *
14562 guestfs_statns (guestfs_h *g,
14563 const char *path);
14564 Returns file information for the given "path".
14566 This is the same as the stat(2) system call.
14568 This function returns a "struct guestfs_statns *", or NULL if there was
14570 an error. The caller must call "guestfs_free_statns" after use.
14571 (Added in 1.27.53)
14573 guestfs_statvfs
14575 struct guestfs_statvfs *
14576 guestfs_statvfs (guestfs_h *g,
14577 const char *path);
14578 Returns file system statistics for any mounted file system. "path"
14580 should be a file or directory in the mounted file system (typically it
14581 is the mount point itself, but it doesn't need to be).
14582 This is the same as the statvfs(2) system call.
14584 This function returns a "struct guestfs_statvfs *", or NULL if there
14586 was an error. The caller must call "guestfs_free_statvfs" after use.
14587 (Added in 1.9.2)
14589 guestfs_strings
14591 char **
14592 guestfs_strings (guestfs_h *g,
14593 const char *path);
14594 This runs the strings(1) command on a file and returns the list of
14596 printable strings found.
14597 The "strings" command has, in the past, had problems with parsing
14599 untrusted files. These are mitigated in the current version of
14600 libguestfs, but see "CVE-2014-8484".
14601 This function returns a NULL-terminated array of strings (like
14603 environ(3)), or NULL if there was an error. The caller must free the
14604 strings and the array after use.
14605 Because of the message protocol, there is a transfer limit of somewhere
14607 between 2MB and 4MB. See "PROTOCOL LIMITS".
14608 (Added in 1.0.22)
14610 guestfs_strings_e
14612 char **
14613 guestfs_strings_e (guestfs_h *g,
14614 const char *encoding,
14615 const char *path);
14616 This is like the "guestfs_strings" command, but allows you to specify
14618 the encoding of strings that are looked for in the source file "path".
14619 Allowed encodings are:
14621 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14623 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14624 S Single 8-bit-byte characters.
14626 b 16-bit big endian strings such as those encoded in UTF-16BE or
14628 UCS-2BE.
14629 l (lower case letter L)
14631 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14632 for examining binaries in Windows guests.
14633 B 32-bit big endian such as UCS-4BE.
14635 L 32-bit little endian such as UCS-4LE.
14637 The returned strings are transcoded to UTF-8.
14639 The "strings" command has, in the past, had problems with parsing
14641 untrusted files. These are mitigated in the current version of
14642 libguestfs, but see "CVE-2014-8484".
14643 This function returns a NULL-terminated array of strings (like
14645 environ(3)), or NULL if there was an error. The caller must free the
14646 strings and the array after use.
14647 Because of the message protocol, there is a transfer limit of somewhere
14649 between 2MB and 4MB. See "PROTOCOL LIMITS".
14650 (Added in 1.0.22)
14652 guestfs_swapoff_device
14654 int
14655 guestfs_swapoff_device (guestfs_h *g,
14656 const char *device);
14657 This command disables the libguestfs appliance swap device or partition
14659 named "device". See "guestfs_swapon_device".
14660 This function returns 0 on success or -1 on error.
14662 (Added in 1.0.66)
14664 guestfs_swapoff_file
14666 int
14667 guestfs_swapoff_file (guestfs_h *g,
14668 const char *file);
14669 This command disables the libguestfs appliance swap on file.
14671 This function returns 0 on success or -1 on error.
14673 (Added in 1.0.66)
14675 guestfs_swapoff_label
14677 int
14678 guestfs_swapoff_label (guestfs_h *g,
14679 const char *label);
14680 This command disables the libguestfs appliance swap on labeled swap
14682 partition.
14683 This function returns 0 on success or -1 on error.
14685 (Added in 1.0.66)
14687 guestfs_swapoff_uuid
14689 int
14690 guestfs_swapoff_uuid (guestfs_h *g,
14691 const char *uuid);
14692 This command disables the libguestfs appliance swap partition with the
14694 given UUID.
14695 This function returns 0 on success or -1 on error.
14697 This function depends on the feature "linuxfsuuid". See also
14699 "guestfs_feature_available".
14700 (Added in 1.0.66)
14702 guestfs_swapon_device
14704 int
14705 guestfs_swapon_device (guestfs_h *g,
14706 const char *device);
14707 This command enables the libguestfs appliance to use the swap device or
14709 partition named "device". The increased memory is made available for
14710 all commands, for example those run using "guestfs_command" or
14711 "guestfs_sh".
14712 Note that you should not swap to existing guest swap partitions unless
14714 you know what you are doing. They may contain hibernation information,
14715 or other information that the guest doesn't want you to trash. You
14716 also risk leaking information about the host to the guest this way.
14717 Instead, attach a new host device to the guest and swap on that.
14718 This function returns 0 on success or -1 on error.
14720 (Added in 1.0.66)
14722 guestfs_swapon_file
14724 int
14725 guestfs_swapon_file (guestfs_h *g,
14726 const char *file);
14727 This command enables swap to a file. See "guestfs_swapon_device" for
14729 other notes.
14730 This function returns 0 on success or -1 on error.
14732 (Added in 1.0.66)
14734 guestfs_swapon_label
14736 int
14737 guestfs_swapon_label (guestfs_h *g,
14738 const char *label);
14739 This command enables swap to a labeled swap partition. See
14741 "guestfs_swapon_device" for other notes.
14742 This function returns 0 on success or -1 on error.
14744 (Added in 1.0.66)
14746 guestfs_swapon_uuid
14748 int
14749 guestfs_swapon_uuid (guestfs_h *g,
14750 const char *uuid);
14751 This command enables swap to a swap partition with the given UUID. See
14753 "guestfs_swapon_device" for other notes.
14754 This function returns 0 on success or -1 on error.
14756 This function depends on the feature "linuxfsuuid". See also
14758 "guestfs_feature_available".
14759 (Added in 1.0.66)
14761 guestfs_sync
14763 int
14764 guestfs_sync (guestfs_h *g);
14765 This syncs the disk, so that any writes are flushed through to the
14767 underlying disk image.
14768 You should always call this if you have modified a disk image, before
14770 closing the handle.
14771 This function returns 0 on success or -1 on error.
14773 (Added in 0.3)
14775 guestfs_syslinux
14777 int
14778 guestfs_syslinux (guestfs_h *g,
14779 const char *device,
14780 ...);
14781 You may supply a list of optional arguments to this call. Use zero or
14783 more of the following pairs of parameters, and terminate the list with
14784 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14785 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14787 Install the SYSLINUX bootloader on "device".
14789 The device parameter must be either a whole disk formatted as a FAT
14791 filesystem, or a partition formatted as a FAT filesystem. In the
14792 latter case, the partition should be marked as "active"
14793 ("guestfs_part_set_bootable") and a Master Boot Record must be
14794 installed (eg. using "guestfs_pwrite_device") on the first sector of
14795 the whole disk. The SYSLINUX package comes with some suitable Master
14796 Boot Records. See the syslinux(1) man page for further information.
14797 The optional arguments are:
14799 directory
14801 Install SYSLINUX in the named subdirectory, instead of in the root
14802 directory of the FAT filesystem.
14803 Additional configuration can be supplied to SYSLINUX by placing a file
14805 called syslinux.cfg on the FAT filesystem, either in the root
14806 directory, or under directory if that optional argument is being used.
14807 For further information about the contents of this file, see
14808 syslinux(1).
14809 See also "guestfs_extlinux".
14811 This function returns 0 on success or -1 on error.
14813 This function depends on the feature "syslinux". See also
14815 "guestfs_feature_available".
14816 (Added in 1.21.27)
14818 guestfs_syslinux_va
14820 int
14821 guestfs_syslinux_va (guestfs_h *g,
14822 const char *device,
14823 va_list args);
14824 This is the "va_list variant" of "guestfs_syslinux".
14826 See "CALLS WITH OPTIONAL ARGUMENTS".
14828 guestfs_syslinux_argv
14830 int
14831 guestfs_syslinux_argv (guestfs_h *g,
14832 const char *device,
14833 const struct guestfs_syslinux_argv *optargs);
14834 This is the "argv variant" of "guestfs_syslinux".
14836 See "CALLS WITH OPTIONAL ARGUMENTS".
14838 guestfs_tail
14840 char **
14841 guestfs_tail (guestfs_h *g,
14842 const char *path);
14843 This command returns up to the last 10 lines of a file as a list of
14845 strings.
14846 This function returns a NULL-terminated array of strings (like
14848 environ(3)), or NULL if there was an error. The caller must free the
14849 strings and the array after use.
14850 Because of the message protocol, there is a transfer limit of somewhere
14852 between 2MB and 4MB. See "PROTOCOL LIMITS".
14853 (Added in 1.0.54)
14855 guestfs_tail_n
14857 char **
14858 guestfs_tail_n (guestfs_h *g,
14859 int nrlines,
14860 const char *path);
14861 If the parameter "nrlines" is a positive number, this returns the last
14863 "nrlines" lines of the file "path".
14864 If the parameter "nrlines" is a negative number, this returns lines
14866 from the file "path", starting with the "-nrlines"'th line.
14867 If the parameter "nrlines" is zero, this returns an empty list.
14869 This function returns a NULL-terminated array of strings (like
14871 environ(3)), or NULL if there was an error. The caller must free the
14872 strings and the array after use.
14873 Because of the message protocol, there is a transfer limit of somewhere
14875 between 2MB and 4MB. See "PROTOCOL LIMITS".
14876 (Added in 1.0.54)
14878 guestfs_tar_in
14880 int
14881 guestfs_tar_in (guestfs_h *g,
14882 const char *tarfile,
14883 const char *directory);
14884 This function is provided for backwards compatibility with earlier
14886 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
14887 optional arguments.
14888 (Added in 1.0.3)
14890 guestfs_tar_in_opts
14892 int
14893 guestfs_tar_in_opts (guestfs_h *g,
14894 const char *tarfile,
14895 const char *directory,
14896 ...);
14897 You may supply a list of optional arguments to this call. Use zero or
14899 more of the following pairs of parameters, and terminate the list with
14900 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14901 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
14903 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
14904 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
14905 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
14906 This command uploads and unpacks local file "tarfile" into directory.
14908 The optional "compress" flag controls compression. If not given, then
14910 the input should be an uncompressed tar file. Otherwise one of the
14911 following strings may be given to select the compression type of the
14912 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
14913 all builds of libguestfs will support all of these compression types).
14914 The other optional arguments are:
14916 "xattrs"
14918 If set to true, extended attributes are restored from the tar file.
14919 "selinux"
14921 If set to true, SELinux contexts are restored from the tar file.
14922 "acls"
14924 If set to true, POSIX ACLs are restored from the tar file.
14925 This function returns 0 on success or -1 on error.
14927 (Added in 1.0.3)
14929 guestfs_tar_in_opts_va
14931 int
14932 guestfs_tar_in_opts_va (guestfs_h *g,
14933 const char *tarfile,
14934 const char *directory,
14935 va_list args);
14936 This is the "va_list variant" of "guestfs_tar_in_opts".
14938 See "CALLS WITH OPTIONAL ARGUMENTS".
14940 guestfs_tar_in_opts_argv
14942 int
14943 guestfs_tar_in_opts_argv (guestfs_h *g,
14944 const char *tarfile,
14945 const char *directory,
14946 const struct guestfs_tar_in_opts_argv *optargs);
14947 This is the "argv variant" of "guestfs_tar_in_opts".
14949 See "CALLS WITH OPTIONAL ARGUMENTS".
14951 guestfs_tar_out
14953 int
14954 guestfs_tar_out (guestfs_h *g,
14955 const char *directory,
14956 const char *tarfile);
14957 This function is provided for backwards compatibility with earlier
14959 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
14960 optional arguments.
14961 (Added in 1.0.3)
14963 guestfs_tar_out_opts
14965 int
14966 guestfs_tar_out_opts (guestfs_h *g,
14967 const char *directory,
14968 const char *tarfile,
14969 ...);
14970 You may supply a list of optional arguments to this call. Use zero or
14972 more of the following pairs of parameters, and terminate the list with
14973 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14974 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
14976 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
14977 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
14978 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
14979 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
14980 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
14981 This command packs the contents of directory and downloads it to local
14983 file "tarfile".
14984 The optional "compress" flag controls compression. If not given, then
14986 the output will be an uncompressed tar file. Otherwise one of the
14987 following strings may be given to select the compression type of the
14988 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
14989 all builds of libguestfs will support all of these compression types).
14990 The other optional arguments are:
14992 "excludes"
14994 A list of wildcards. Files are excluded if they match any of the
14995 wildcards.
14996 "numericowner"
14998 If set to true, the output tar file will contain UID/GID numbers
14999 instead of user/group names.
15000 "xattrs"
15002 If set to true, extended attributes are saved in the output tar.
15003 "selinux"
15005 If set to true, SELinux contexts are saved in the output tar.
15006 "acls"
15008 If set to true, POSIX ACLs are saved in the output tar.
15009 This function returns 0 on success or -1 on error.
15011 (Added in 1.0.3)
15013 guestfs_tar_out_opts_va
15015 int
15016 guestfs_tar_out_opts_va (guestfs_h *g,
15017 const char *directory,
15018 const char *tarfile,
15019 va_list args);
15020 This is the "va_list variant" of "guestfs_tar_out_opts".
15022 See "CALLS WITH OPTIONAL ARGUMENTS".
15024 guestfs_tar_out_opts_argv
15026 int
15027 guestfs_tar_out_opts_argv (guestfs_h *g,
15028 const char *directory,
15029 const char *tarfile,
15030 const struct guestfs_tar_out_opts_argv *optargs);
15031 This is the "argv variant" of "guestfs_tar_out_opts".
15033 See "CALLS WITH OPTIONAL ARGUMENTS".
15035 guestfs_tgz_in
15037 int
15038 guestfs_tgz_in (guestfs_h *g,
15039 const char *tarball,
15040 const char *directory);
15041 This function is deprecated. In new code, use the "guestfs_tar_in"
15043 call instead.
15044 Deprecated functions will not be removed from the API, but the fact
15046 that they are deprecated indicates that there are problems with correct
15047 use of these functions.
15048 This command uploads and unpacks local file "tarball" (a gzip
15050 compressed tar file) into directory.
15051 This function returns 0 on success or -1 on error.
15053 (Added in 1.0.3)
15055 guestfs_tgz_out
15057 int
15058 guestfs_tgz_out (guestfs_h *g,
15059 const char *directory,
15060 const char *tarball);
15061 This function is deprecated. In new code, use the "guestfs_tar_out"
15063 call instead.
15064 Deprecated functions will not be removed from the API, but the fact
15066 that they are deprecated indicates that there are problems with correct
15067 use of these functions.
15068 This command packs the contents of directory and downloads it to local
15070 file "tarball".
15071 This function returns 0 on success or -1 on error.
15073 (Added in 1.0.3)
15075 guestfs_touch
15077 int
15078 guestfs_touch (guestfs_h *g,
15079 const char *path);
15080 Touch acts like the touch(1) command. It can be used to update the
15082 timestamps on a file, or, if the file does not exist, to create a new
15083 zero-length file.
15084 This command only works on regular files, and will fail on other file
15086 types such as directories, symbolic links, block special etc.
15087 This function returns 0 on success or -1 on error.
15089 (Added in 0.3)
15091 guestfs_truncate
15093 int
15094 guestfs_truncate (guestfs_h *g,
15095 const char *path);
15096 This command truncates "path" to a zero-length file. The file must
15098 exist already.
15099 This function returns 0 on success or -1 on error.
15101 (Added in 1.0.77)
15103 guestfs_truncate_size
15105 int
15106 guestfs_truncate_size (guestfs_h *g,
15107 const char *path,
15108 int64_t size);
15109 This command truncates "path" to size "size" bytes. The file must
15111 exist already.
15112 If the current file size is less than "size" then the file is extended
15114 to the required size with zero bytes. This creates a sparse file (ie.
15115 disk blocks are not allocated for the file until you write to it). To
15116 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15117 This function returns 0 on success or -1 on error.
15119 (Added in 1.0.77)
15121 guestfs_tune2fs
15123 int
15124 guestfs_tune2fs (guestfs_h *g,
15125 const char *device,
15126 ...);
15127 You may supply a list of optional arguments to this call. Use zero or
15129 more of the following pairs of parameters, and terminate the list with
15130 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15131 GUESTFS_TUNE2FS_FORCE, int force,
15133 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15134 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15135 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15136 GUESTFS_TUNE2FS_GROUP, int64_t group,
15137 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15138 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15139 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15140 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15141 GUESTFS_TUNE2FS_USER, int64_t user,
15142 This call allows you to adjust various filesystem parameters of an
15144 ext2/ext3/ext4 filesystem called "device".
15145 The optional parameters are:
15147 "force"
15149 Force tune2fs to complete the operation even in the face of errors.
15150 This is the same as the tune2fs(8) "-f" option.
15151 "maxmountcount"
15153 Set the number of mounts after which the filesystem is checked by
15154 e2fsck(8). If this is 0 then the number of mounts is disregarded.
15155 This is the same as the tune2fs(8) "-c" option.
15156 "mountcount"
15158 Set the number of times the filesystem has been mounted. This is
15159 the same as the tune2fs(8) "-C" option.
15160 "errorbehavior"
15162 Change the behavior of the kernel code when errors are detected.
15163 Possible values currently are: "continue", "remount-ro", "panic".
15164 In practice these options don't really make any difference,
15165 particularly for write errors.
15166 This is the same as the tune2fs(8) "-e" option.
15168 "group"
15170 Set the group which can use reserved filesystem blocks. This is
15171 the same as the tune2fs(8) "-g" option except that it can only be
15172 specified as a number.
15173 "intervalbetweenchecks"
15175 Adjust the maximal time between two filesystem checks (in seconds).
15176 If the option is passed as 0 then time-dependent checking is
15177 disabled.
15178 This is the same as the tune2fs(8) "-i" option.
15180 "reservedblockspercentage"
15182 Set the percentage of the filesystem which may only be allocated by
15183 privileged processes. This is the same as the tune2fs(8) "-m"
15184 option.
15185 "lastmounteddirectory"
15187 Set the last mounted directory. This is the same as the tune2fs(8)
15188 "-M" option.
15189 "reservedblockscount" Set the number of reserved filesystem blocks.
15191 This is the same as the tune2fs(8) "-r" option.
15192 "user"
15193 Set the user who can use the reserved filesystem blocks. This is
15194 the same as the tune2fs(8) "-u" option except that it can only be
15195 specified as a number.
15196 To get the current values of filesystem parameters, see
15198 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
15199 tune2fs(8) man page.
15200 This function returns 0 on success or -1 on error.
15202 (Added in 1.15.4)
15204 guestfs_tune2fs_va
15206 int
15207 guestfs_tune2fs_va (guestfs_h *g,
15208 const char *device,
15209 va_list args);
15210 This is the "va_list variant" of "guestfs_tune2fs".
15212 See "CALLS WITH OPTIONAL ARGUMENTS".
15214 guestfs_tune2fs_argv
15216 int
15217 guestfs_tune2fs_argv (guestfs_h *g,
15218 const char *device,
15219 const struct guestfs_tune2fs_argv *optargs);
15220 This is the "argv variant" of "guestfs_tune2fs".
15222 See "CALLS WITH OPTIONAL ARGUMENTS".
15224 guestfs_tune2fs_l
15226 char **
15227 guestfs_tune2fs_l (guestfs_h *g,
15228 const char *device);
15229 This returns the contents of the ext2, ext3 or ext4 filesystem
15231 superblock on "device".
15232 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
15234 for more details. The list of fields returned isn't clearly defined,
15235 and depends on both the version of "tune2fs" that libguestfs was built
15236 against, and the filesystem itself.
15237 This function returns a NULL-terminated array of strings, or NULL if
15239 there was an error. The array of strings will always have length
15240 "2n+1", where "n" keys and values alternate, followed by the trailing
15241 NULL entry. The caller must free the strings and the array after use.
15242 (Added in 1.9.2)
15244 guestfs_txz_in
15246 int
15247 guestfs_txz_in (guestfs_h *g,
15248 const char *tarball,
15249 const char *directory);
15250 This function is deprecated. In new code, use the "guestfs_tar_in"
15252 call instead.
15253 Deprecated functions will not be removed from the API, but the fact
15255 that they are deprecated indicates that there are problems with correct
15256 use of these functions.
15257 This command uploads and unpacks local file "tarball" (an xz compressed
15259 tar file) into directory.
15260 This function returns 0 on success or -1 on error.
15262 This function depends on the feature "xz". See also
15264 "guestfs_feature_available".
15265 (Added in 1.3.2)
15267 guestfs_txz_out
15269 int
15270 guestfs_txz_out (guestfs_h *g,
15271 const char *directory,
15272 const char *tarball);
15273 This function is deprecated. In new code, use the "guestfs_tar_out"
15275 call instead.
15276 Deprecated functions will not be removed from the API, but the fact
15278 that they are deprecated indicates that there are problems with correct
15279 use of these functions.
15280 This command packs the contents of directory and downloads it to local
15282 file "tarball" (as an xz compressed tar archive).
15283 This function returns 0 on success or -1 on error.
15285 This function depends on the feature "xz". See also
15287 "guestfs_feature_available".
15288 (Added in 1.3.2)
15290 guestfs_umask
15292 int
15293 guestfs_umask (guestfs_h *g,
15294 int mask);
15295 This function sets the mask used for creating new files and device
15297 nodes to "mask & 0777".
15298 Typical umask values would be 022 which creates new files with
15300 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15301 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15302 The default umask is 022. This is important because it means that
15304 directories and device nodes will be created with 0644 or 0755 mode
15305 even if you specify 0777.
15306 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15308 "guestfs_mkdir".
15309 This call returns the previous umask.
15311 On error this function returns -1.
15313 (Added in 1.0.55)
15315 guestfs_umount
15317 int
15318 guestfs_umount (guestfs_h *g,
15319 const char *pathordevice);
15320 This function is provided for backwards compatibility with earlier
15322 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15323 optional arguments.
15324 (Added in 0.8)
15326 guestfs_umount_opts
15328 int
15329 guestfs_umount_opts (guestfs_h *g,
15330 const char *pathordevice,
15331 ...);
15332 You may supply a list of optional arguments to this call. Use zero or
15334 more of the following pairs of parameters, and terminate the list with
15335 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15336 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15338 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15339 This unmounts the given filesystem. The filesystem may be specified
15341 either by its mountpoint (path) or the device which contains the
15342 filesystem.
15343 This function returns 0 on success or -1 on error.
15345 (Added in 0.8)
15347 guestfs_umount_opts_va
15349 int
15350 guestfs_umount_opts_va (guestfs_h *g,
15351 const char *pathordevice,
15352 va_list args);
15353 This is the "va_list variant" of "guestfs_umount_opts".
15355 See "CALLS WITH OPTIONAL ARGUMENTS".
15357 guestfs_umount_opts_argv
15359 int
15360 guestfs_umount_opts_argv (guestfs_h *g,
15361 const char *pathordevice,
15362 const struct guestfs_umount_opts_argv *optargs);
15363 This is the "argv variant" of "guestfs_umount_opts".
15365 See "CALLS WITH OPTIONAL ARGUMENTS".
15367 guestfs_umount_all
15369 int
15370 guestfs_umount_all (guestfs_h *g);
15371 This unmounts all mounted filesystems.
15373 Some internal mounts are not unmounted by this call.
15375 This function returns 0 on success or -1 on error.
15377 (Added in 0.8)
15379 guestfs_umount_local
15381 int
15382 guestfs_umount_local (guestfs_h *g,
15383 ...);
15384 You may supply a list of optional arguments to this call. Use zero or
15386 more of the following pairs of parameters, and terminate the list with
15387 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15388 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15390 If libguestfs is exporting the filesystem on a local mountpoint, then
15392 this unmounts it.
15393 See "MOUNT LOCAL" for full documentation.
15395 This function returns 0 on success or -1 on error.
15397 (Added in 1.17.22)
15399 guestfs_umount_local_va
15401 int
15402 guestfs_umount_local_va (guestfs_h *g,
15403 va_list args);
15404 This is the "va_list variant" of "guestfs_umount_local".
15406 See "CALLS WITH OPTIONAL ARGUMENTS".
15408 guestfs_umount_local_argv
15410 int
15411 guestfs_umount_local_argv (guestfs_h *g,
15412 const struct guestfs_umount_local_argv *optargs);
15413 This is the "argv variant" of "guestfs_umount_local".
15415 See "CALLS WITH OPTIONAL ARGUMENTS".
15417 guestfs_upload
15419 int
15420 guestfs_upload (guestfs_h *g,
15421 const char *filename,
15422 const char *remotefilename);
15423 Upload local file filename to remotefilename on the filesystem.
15425 filename can also be a named pipe.
15427 See also "guestfs_download".
15429 This function returns 0 on success or -1 on error.
15431 This long-running command can generate progress notification messages
15433 so that the caller can display a progress bar or indicator. To receive
15434 these messages, the caller must register a progress event callback.
15435 See "GUESTFS_EVENT_PROGRESS".
15436 (Added in 1.0.2)
15438 guestfs_upload_offset
15440 int
15441 guestfs_upload_offset (guestfs_h *g,
15442 const char *filename,
15443 const char *remotefilename,
15444 int64_t offset);
15445 Upload local file filename to remotefilename on the filesystem.
15447 remotefilename is overwritten starting at the byte "offset" specified.
15449 The intention is to overwrite parts of existing files or devices,
15450 although if a non-existent file is specified then it is created with a
15451 "hole" before "offset". The size of the data written is implicit in
15452 the size of the source filename.
15453 Note that there is no limit on the amount of data that can be uploaded
15455 with this call, unlike with "guestfs_pwrite", and this call always
15456 writes the full amount unless an error occurs.
15457 See also "guestfs_upload", "guestfs_pwrite".
15459 This function returns 0 on success or -1 on error.
15461 This long-running command can generate progress notification messages
15463 so that the caller can display a progress bar or indicator. To receive
15464 these messages, the caller must register a progress event callback.
15465 See "GUESTFS_EVENT_PROGRESS".
15466 (Added in 1.5.17)
15468 guestfs_user_cancel
15470 int
15471 guestfs_user_cancel (guestfs_h *g);
15472 This function cancels the current upload or download operation.
15474 Unlike most other libguestfs calls, this function is signal safe and
15476 thread safe. You can call it from a signal handler or from another
15477 thread, without needing to do any locking.
15478 The transfer that was in progress (if there is one) will stop shortly
15480 afterwards, and will return an error. The errno (see
15481 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15482 find out if the operation was cancelled or failed because of another
15483 error.
15484 No cleanup is performed: for example, if a file was being uploaded then
15486 after cancellation there may be a partially uploaded file. It is the
15487 caller’s responsibility to clean up if necessary.
15488 There are two common places that you might call "guestfs_user_cancel":
15490 In an interactive text-based program, you might call it from a "SIGINT"
15492 signal handler so that pressing "^C" cancels the current operation.
15493 (You also need to call "guestfs_set_pgroup" so that child processes
15494 don't receive the "^C" signal).
15495 In a graphical program, when the main thread is displaying a progress
15497 bar with a cancel button, wire up the cancel button to call this
15498 function.
15499 This function returns 0 on success or -1 on error.
15501 (Added in 1.11.18)
15503 guestfs_utimens
15505 int
15506 guestfs_utimens (guestfs_h *g,
15507 const char *path,
15508 int64_t atsecs,
15509 int64_t atnsecs,
15510 int64_t mtsecs,
15511 int64_t mtnsecs);
15512 This command sets the timestamps of a file with nanosecond precision.
15514 "atsecs", "atnsecs" are the last access time (atime) in secs and
15516 nanoseconds from the epoch.
15517 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
15519 nanoseconds from the epoch.
15520 If the *nsecs field contains the special value "-1" then the
15522 corresponding timestamp is set to the current time. (The *secs field
15523 is ignored in this case).
15524 If the *nsecs field contains the special value "-2" then the
15526 corresponding timestamp is left unchanged. (The *secs field is ignored
15527 in this case).
15528 This function returns 0 on success or -1 on error.
15530 (Added in 1.0.77)
15532 guestfs_utsname
15534 struct guestfs_utsname *
15535 guestfs_utsname (guestfs_h *g);
15536 This returns the kernel version of the appliance, where this is
15538 available. This information is only useful for debugging. Nothing in
15539 the returned structure is defined by the API.
15540 This function returns a "struct guestfs_utsname *", or NULL if there
15542 was an error. The caller must call "guestfs_free_utsname" after use.
15543 (Added in 1.19.27)
15545 guestfs_version
15547 struct guestfs_version *
15548 guestfs_version (guestfs_h *g);
15549 Return the libguestfs version number that the program is linked
15551 against.
15552 Note that because of dynamic linking this is not necessarily the
15554 version of libguestfs that you compiled against. You can compile the
15555 program, and then at runtime dynamically link against a completely
15556 different libguestfs.so library.
15557 This call was added in version 1.0.58. In previous versions of
15559 libguestfs there was no way to get the version number. From C code you
15560 can use dynamic linker functions to find out if this symbol exists (if
15561 it doesn't, then it’s an earlier version).
15562 The call returns a structure with four elements. The first three
15564 ("major", "minor" and "release") are numbers and correspond to the
15565 usual version triplet. The fourth element ("extra") is a string and is
15566 normally empty, but may be used for distro-specific information.
15567 To construct the original version string:
15569 "$major.$minor.$release$extra"
15570 See also: "LIBGUESTFS VERSION NUMBERS".
15572 Note: Don't use this call to test for availability of features. In
15574 enterprise distributions we backport features from later versions into
15575 earlier versions, making this an unreliable way to test for features.
15576 Use "guestfs_available" or "guestfs_feature_available" instead.
15577 This function returns a "struct guestfs_version *", or NULL if there
15579 was an error. The caller must call "guestfs_free_version" after use.
15580 (Added in 1.0.58)
15582 guestfs_vfs_label
15584 char *
15585 guestfs_vfs_label (guestfs_h *g,
15586 const char *mountable);
15587 This returns the label of the filesystem on "mountable".
15589 If the filesystem is unlabeled, this returns the empty string.
15591 To find a filesystem from the label, use "guestfs_findfs_label".
15593 This function returns a string, or NULL on error. The caller must free
15595 the returned string after use.
15596 (Added in 1.3.18)
15598 guestfs_vfs_minimum_size
15600 int64_t
15601 guestfs_vfs_minimum_size (guestfs_h *g,
15602 const char *mountable);
15603 Get the minimum size of filesystem in bytes. This is the minimum
15605 possible size for filesystem shrinking.
15606 If getting minimum size of specified filesystem is not supported, this
15608 will fail and set errno as ENOTSUP.
15609 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15611 On error this function returns -1.
15613 (Added in 1.31.18)
15615 guestfs_vfs_type
15617 char *
15618 guestfs_vfs_type (guestfs_h *g,
15619 const char *mountable);
15620 This command gets the filesystem type corresponding to the filesystem
15622 on "mountable".
15623 For most filesystems, the result is the name of the Linux VFS module
15625 which would be used to mount this filesystem if you mounted it without
15626 specifying the filesystem type. For example a string such as "ext3" or
15627 "ntfs".
15628 This function returns a string, or NULL on error. The caller must free
15630 the returned string after use.
15631 (Added in 1.0.75)
15633 guestfs_vfs_uuid
15635 char *
15636 guestfs_vfs_uuid (guestfs_h *g,
15637 const char *mountable);
15638 This returns the filesystem UUID of the filesystem on "mountable".
15640 If the filesystem does not have a UUID, this returns the empty string.
15642 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15644 This function returns a string, or NULL on error. The caller must free
15646 the returned string after use.
15647 (Added in 1.3.18)
15649 guestfs_vg_activate
15651 int
15652 guestfs_vg_activate (guestfs_h *g,
15653 int activate,
15654 char *const *volgroups);
15655 This command activates or (if "activate" is false) deactivates all
15657 logical volumes in the listed volume groups "volgroups".
15658 This command is the same as running "vgchange -a y|n volgroups..."
15660 Note that if "volgroups" is an empty list then all volume groups are
15662 activated or deactivated.
15663 This function returns 0 on success or -1 on error.
15665 This function depends on the feature "lvm2". See also
15667 "guestfs_feature_available".
15668 (Added in 1.0.26)
15670 guestfs_vg_activate_all
15672 int
15673 guestfs_vg_activate_all (guestfs_h *g,
15674 int activate);
15675 This command activates or (if "activate" is false) deactivates all
15677 logical volumes in all volume groups.
15678 This command is the same as running "vgchange -a y|n"
15680 This function returns 0 on success or -1 on error.
15682 This function depends on the feature "lvm2". See also
15684 "guestfs_feature_available".
15685 (Added in 1.0.26)
15687 guestfs_vgchange_uuid
15689 int
15690 guestfs_vgchange_uuid (guestfs_h *g,
15691 const char *vg);
15692 Generate a new random UUID for the volume group "vg".
15694 This function returns 0 on success or -1 on error.
15696 This function depends on the feature "lvm2". See also
15698 "guestfs_feature_available".
15699 (Added in 1.19.26)
15701 guestfs_vgchange_uuid_all
15703 int
15704 guestfs_vgchange_uuid_all (guestfs_h *g);
15705 Generate new random UUIDs for all volume groups.
15707 This function returns 0 on success or -1 on error.
15709 This function depends on the feature "lvm2". See also
15711 "guestfs_feature_available".
15712 (Added in 1.19.26)
15714 guestfs_vgcreate
15716 int
15717 guestfs_vgcreate (guestfs_h *g,
15718 const char *volgroup,
15719 char *const *physvols);
15720 This creates an LVM volume group called "volgroup" from the non-empty
15722 list of physical volumes "physvols".
15723 This function returns 0 on success or -1 on error.
15725 This function depends on the feature "lvm2". See also
15727 "guestfs_feature_available".
15728 (Added in 0.8)
15730 guestfs_vglvuuids
15732 char **
15733 guestfs_vglvuuids (guestfs_h *g,
15734 const char *vgname);
15735 Given a VG called "vgname", this returns the UUIDs of all the logical
15737 volumes created in this volume group.
15738 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15740 associate logical volumes and volume groups.
15741 See also "guestfs_vgpvuuids".
15743 This function returns a NULL-terminated array of strings (like
15745 environ(3)), or NULL if there was an error. The caller must free the
15746 strings and the array after use.
15747 (Added in 1.0.87)
15749 guestfs_vgmeta
15751 char *
15752 guestfs_vgmeta (guestfs_h *g,
15753 const char *vgname,
15754 size_t *size_r);
15755 "vgname" is an LVM volume group. This command examines the volume
15757 group and returns its metadata.
15758 Note that the metadata is an internal structure used by LVM, subject to
15760 change at any time, and is provided for information only.
15761 This function returns a buffer, or NULL on error. The size of the
15763 returned buffer is written to *size_r. The caller must free the
15764 returned buffer after use.
15765 This function depends on the feature "lvm2". See also
15767 "guestfs_feature_available".
15768 (Added in 1.17.20)
15770 guestfs_vgpvuuids
15772 char **
15773 guestfs_vgpvuuids (guestfs_h *g,
15774 const char *vgname);
15775 Given a VG called "vgname", this returns the UUIDs of all the physical
15777 volumes that this volume group resides on.
15778 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15780 associate physical volumes and volume groups.
15781 See also "guestfs_vglvuuids".
15783 This function returns a NULL-terminated array of strings (like
15785 environ(3)), or NULL if there was an error. The caller must free the
15786 strings and the array after use.
15787 (Added in 1.0.87)
15789 guestfs_vgremove
15791 int
15792 guestfs_vgremove (guestfs_h *g,
15793 const char *vgname);
15794 Remove an LVM volume group "vgname", (for example "VG").
15796 This also forcibly removes all logical volumes in the volume group (if
15798 any).
15799 This function returns 0 on success or -1 on error.
15801 This function depends on the feature "lvm2". See also
15803 "guestfs_feature_available".
15804 (Added in 1.0.13)
15806 guestfs_vgrename
15808 int
15809 guestfs_vgrename (guestfs_h *g,
15810 const char *volgroup,
15811 const char *newvolgroup);
15812 Rename a volume group "volgroup" with the new name "newvolgroup".
15814 This function returns 0 on success or -1 on error.
15816 (Added in 1.0.83)
15818 guestfs_vgs
15820 char **
15821 guestfs_vgs (guestfs_h *g);
15822 List all the volumes groups detected. This is the equivalent of the
15824 vgs(8) command.
15825 This returns a list of just the volume group names that were detected
15827 (eg. "VolGroup00").
15828 See also "guestfs_vgs_full".
15830 This function returns a NULL-terminated array of strings (like
15832 environ(3)), or NULL if there was an error. The caller must free the
15833 strings and the array after use.
15834 This function depends on the feature "lvm2". See also
15836 "guestfs_feature_available".
15837 (Added in 0.4)
15839 guestfs_vgs_full
15841 struct guestfs_lvm_vg_list *
15842 guestfs_vgs_full (guestfs_h *g);
15843 List all the volumes groups detected. This is the equivalent of the
15845 vgs(8) command. The "full" version includes all fields.
15846 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
15848 there was an error. The caller must call "guestfs_free_lvm_vg_list"
15849 after use.
15850 This function depends on the feature "lvm2". See also
15852 "guestfs_feature_available".
15853 (Added in 0.4)
15855 guestfs_vgscan
15857 int
15858 guestfs_vgscan (guestfs_h *g);
15859 This function is deprecated. In new code, use the "guestfs_lvm_scan"
15861 call instead.
15862 Deprecated functions will not be removed from the API, but the fact
15864 that they are deprecated indicates that there are problems with correct
15865 use of these functions.
15866 This rescans all block devices and rebuilds the list of LVM physical
15868 volumes, volume groups and logical volumes.
15869 This function returns 0 on success or -1 on error.
15871 (Added in 1.3.2)
15873 guestfs_vguuid
15875 char *
15876 guestfs_vguuid (guestfs_h *g,
15877 const char *vgname);
15878 This command returns the UUID of the LVM VG named "vgname".
15880 This function returns a string, or NULL on error. The caller must free
15882 the returned string after use.
15883 (Added in 1.0.87)
15885 guestfs_wait_ready
15887 int
15888 guestfs_wait_ready (guestfs_h *g);
15889 This function is deprecated. There is no replacement. Consult the API
15891 documentation in guestfs(3) for further information.
15892 Deprecated functions will not be removed from the API, but the fact
15894 that they are deprecated indicates that there are problems with correct
15895 use of these functions.
15896 This function is a no op.
15898 In versions of the API < 1.0.71 you had to call this function just
15900 after calling "guestfs_launch" to wait for the launch to complete.
15901 However this is no longer necessary because "guestfs_launch" now does
15902 the waiting.
15903 If you see any calls to this function in code then you can just remove
15905 them, unless you want to retain compatibility with older versions of
15906 the API.
15907 This function returns 0 on success or -1 on error.
15909 (Added in 0.3)
15911 guestfs_wc_c
15913 int
15914 guestfs_wc_c (guestfs_h *g,
15915 const char *path);
15916 This command counts the characters in a file, using the "wc -c"
15918 external command.
15919 On error this function returns -1.
15921 (Added in 1.0.54)
15923 guestfs_wc_l
15925 int
15926 guestfs_wc_l (guestfs_h *g,
15927 const char *path);
15928 This command counts the lines in a file, using the "wc -l" external
15930 command.
15931 On error this function returns -1.
15933 (Added in 1.0.54)
15935 guestfs_wc_w
15937 int
15938 guestfs_wc_w (guestfs_h *g,
15939 const char *path);
15940 This command counts the words in a file, using the "wc -w" external
15942 command.
15943 On error this function returns -1.
15945 (Added in 1.0.54)
15947 guestfs_wipefs
15949 int
15950 guestfs_wipefs (guestfs_h *g,
15951 const char *device);
15952 This command erases filesystem or RAID signatures from the specified
15954 "device" to make the filesystem invisible to libblkid.
15955 This does not erase the filesystem itself nor any other data from the
15957 "device".
15958 Compare with "guestfs_zero" which zeroes the first few blocks of a
15960 device.
15961 This function returns 0 on success or -1 on error.
15963 This function depends on the feature "wipefs". See also
15965 "guestfs_feature_available".
15966 (Added in 1.17.6)
15968 guestfs_write
15970 int
15971 guestfs_write (guestfs_h *g,
15972 const char *path,
15973 const char *content,
15974 size_t content_size);
15975 This call creates a file called "path". The content of the file is the
15977 string "content" (which can contain any 8 bit data).
15978 See also "guestfs_write_append".
15980 This function returns 0 on success or -1 on error.
15982 (Added in 1.3.14)
15984 guestfs_write_append
15986 int
15987 guestfs_write_append (guestfs_h *g,
15988 const char *path,
15989 const char *content,
15990 size_t content_size);
15991 This call appends "content" to the end of file "path". If "path" does
15993 not exist, then a new file is created.
15994 See also "guestfs_write".
15996 This function returns 0 on success or -1 on error.
15998 (Added in 1.11.18)
16000 guestfs_write_file
16002 int
16003 guestfs_write_file (guestfs_h *g,
16004 const char *path,
16005 const char *content,
16006 int size);
16007 This function is deprecated. In new code, use the "guestfs_write" call
16009 instead.
16010 Deprecated functions will not be removed from the API, but the fact
16012 that they are deprecated indicates that there are problems with correct
16013 use of these functions.
16014 This call creates a file called "path". The contents of the file is
16016 the string "content" (which can contain any 8 bit data), with length
16017 "size".
16018 As a special case, if "size" is 0 then the length is calculated using
16020 "strlen" (so in this case the content cannot contain embedded ASCII
16021 NULs).
16022 NB. Owing to a bug, writing content containing ASCII NUL characters
16024 does not work, even if the length is specified.
16025 This function returns 0 on success or -1 on error.
16027 Because of the message protocol, there is a transfer limit of somewhere
16029 between 2MB and 4MB. See "PROTOCOL LIMITS".
16030 (Added in 0.8)
16032 guestfs_xfs_admin
16034 int
16035 guestfs_xfs_admin (guestfs_h *g,
16036 const char *device,
16037 ...);
16038 You may supply a list of optional arguments to this call. Use zero or
16040 more of the following pairs of parameters, and terminate the list with
16041 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16042 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16044 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16045 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16046 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16047 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16048 GUESTFS_XFS_ADMIN_LABEL, const char *label,
16049 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16050 Change the parameters of the XFS filesystem on "device".
16052 Devices that are mounted cannot be modified. Administrators must
16054 unmount filesystems before this call can modify parameters.
16055 Some of the parameters of a mounted filesystem can be examined and
16057 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16058 Beginning with XFS version 5, it is no longer possible to modify the
16060 lazy-counters setting (ie. "lazycounter" parameter has no effect).
16061 This function returns 0 on success or -1 on error.
16063 This function depends on the feature "xfs". See also
16065 "guestfs_feature_available".
16066 (Added in 1.19.33)
16068 guestfs_xfs_admin_va
16070 int
16071 guestfs_xfs_admin_va (guestfs_h *g,
16072 const char *device,
16073 va_list args);
16074 This is the "va_list variant" of "guestfs_xfs_admin".
16076 See "CALLS WITH OPTIONAL ARGUMENTS".
16078 guestfs_xfs_admin_argv
16080 int
16081 guestfs_xfs_admin_argv (guestfs_h *g,
16082 const char *device,
16083 const struct guestfs_xfs_admin_argv *optargs);
16084 This is the "argv variant" of "guestfs_xfs_admin".
16086 See "CALLS WITH OPTIONAL ARGUMENTS".
16088 guestfs_xfs_growfs
16090 int
16091 guestfs_xfs_growfs (guestfs_h *g,
16092 const char *path,
16093 ...);
16094 You may supply a list of optional arguments to this call. Use zero or
16096 more of the following pairs of parameters, and terminate the list with
16097 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16098 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16100 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16101 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16102 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16103 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16104 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16105 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16106 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16107 Grow the XFS filesystem mounted at "path".
16109 The returned struct contains geometry information. Missing fields are
16111 returned as "-1" (for numeric fields) or empty string.
16112 This function returns 0 on success or -1 on error.
16114 This function depends on the feature "xfs". See also
16116 "guestfs_feature_available".
16117 (Added in 1.19.28)
16119 guestfs_xfs_growfs_va
16121 int
16122 guestfs_xfs_growfs_va (guestfs_h *g,
16123 const char *path,
16124 va_list args);
16125 This is the "va_list variant" of "guestfs_xfs_growfs".
16127 See "CALLS WITH OPTIONAL ARGUMENTS".
16129 guestfs_xfs_growfs_argv
16131 int
16132 guestfs_xfs_growfs_argv (guestfs_h *g,
16133 const char *path,
16134 const struct guestfs_xfs_growfs_argv *optargs);
16135 This is the "argv variant" of "guestfs_xfs_growfs".
16137 See "CALLS WITH OPTIONAL ARGUMENTS".
16139 guestfs_xfs_info
16141 struct guestfs_xfsinfo *
16142 guestfs_xfs_info (guestfs_h *g,
16143 const char *pathordevice);
16144 "pathordevice" is a mounted XFS filesystem or a device containing an
16146 XFS filesystem. This command returns the geometry of the filesystem.
16147 The returned struct contains geometry information. Missing fields are
16149 returned as "-1" (for numeric fields) or empty string.
16150 This function returns a "struct guestfs_xfsinfo *", or NULL if there
16152 was an error. The caller must call "guestfs_free_xfsinfo" after use.
16153 This function depends on the feature "xfs". See also
16155 "guestfs_feature_available".
16156 (Added in 1.19.21)
16158 guestfs_xfs_repair
16160 int
16161 guestfs_xfs_repair (guestfs_h *g,
16162 const char *device,
16163 ...);
16164 You may supply a list of optional arguments to this call. Use zero or
16166 more of the following pairs of parameters, and terminate the list with
16167 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16168 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16170 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16171 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16172 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16173 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16174 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16175 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16176 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16177 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16178 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16179 Repair corrupt or damaged XFS filesystem on "device".
16181 The filesystem is specified using the "device" argument which should be
16183 the device name of the disk partition or volume containing the
16184 filesystem. If given the name of a block device, "xfs_repair" will
16185 attempt to find the raw device associated with the specified block
16186 device and will use the raw device instead.
16187 Regardless, the filesystem to be repaired must be unmounted, otherwise,
16189 the resulting filesystem may be inconsistent or corrupt.
16190 The returned status indicates whether filesystem corruption was
16192 detected (returns 1) or was not detected (returns 0).
16193 On error this function returns -1.
16195 This function depends on the feature "xfs". See also
16197 "guestfs_feature_available".
16198 (Added in 1.19.36)
16200 guestfs_xfs_repair_va
16202 int
16203 guestfs_xfs_repair_va (guestfs_h *g,
16204 const char *device,
16205 va_list args);
16206 This is the "va_list variant" of "guestfs_xfs_repair".
16208 See "CALLS WITH OPTIONAL ARGUMENTS".
16210 guestfs_xfs_repair_argv
16212 int
16213 guestfs_xfs_repair_argv (guestfs_h *g,
16214 const char *device,
16215 const struct guestfs_xfs_repair_argv *optargs);
16216 This is the "argv variant" of "guestfs_xfs_repair".
16218 See "CALLS WITH OPTIONAL ARGUMENTS".
16220 guestfs_yara_destroy
16222 int
16223 guestfs_yara_destroy (guestfs_h *g);
16224 Destroy previously loaded Yara rules in order to free libguestfs
16226 resources.
16227 This function returns 0 on success or -1 on error.
16229 This function depends on the feature "libyara". See also
16231 "guestfs_feature_available".
16232 (Added in 1.37.13)
16234 guestfs_yara_load
16236 int
16237 guestfs_yara_load (guestfs_h *g,
16238 const char *filename);
16239 Upload a set of Yara rules from local file filename.
16241 Yara rules allow to categorize files based on textual or binary
16243 patterns within their content. See "guestfs_yara_scan" to see how to
16244 scan files with the loaded rules.
16245 Rules can be in binary format, as when compiled with yarac command, or
16247 in source code format. In the latter case, the rules will be first
16248 compiled and then loaded.
16249 Rules in source code format cannot include external files. In such
16251 cases, it is recommended to compile them first.
16252 Previously loaded rules will be destroyed.
16254 This function returns 0 on success or -1 on error.
16256 This long-running command can generate progress notification messages
16258 so that the caller can display a progress bar or indicator. To receive
16259 these messages, the caller must register a progress event callback.
16260 See "GUESTFS_EVENT_PROGRESS".
16261 This function depends on the feature "libyara". See also
16263 "guestfs_feature_available".
16264 (Added in 1.37.13)
16266 guestfs_yara_scan
16268 struct guestfs_yara_detection_list *
16269 guestfs_yara_scan (guestfs_h *g,
16270 const char *path);
16271 Scan a file with the previously loaded Yara rules.
16273 For each matching rule, a "yara_detection" structure is returned.
16275 The "yara_detection" structure contains the following fields.
16277 "yara_name"
16279 Path of the file matching a Yara rule.
16280 "yara_rule"
16282 Identifier of the Yara rule which matched against the given file.
16283 This function returns a "struct guestfs_yara_detection_list *", or NULL
16285 if there was an error. The caller must call
16286 "guestfs_free_yara_detection_list" after use.
16287 This long-running command can generate progress notification messages
16289 so that the caller can display a progress bar or indicator. To receive
16290 these messages, the caller must register a progress event callback.
16291 See "GUESTFS_EVENT_PROGRESS".
16292 This function depends on the feature "libyara". See also
16294 "guestfs_feature_available".
16295 (Added in 1.37.13)
16297 guestfs_zegrep
16299 char **
16300 guestfs_zegrep (guestfs_h *g,
16301 const char *regex,
16302 const char *path);
16303 This function is deprecated. In new code, use the "guestfs_grep" call
16305 instead.
16306 Deprecated functions will not be removed from the API, but the fact
16308 that they are deprecated indicates that there are problems with correct
16309 use of these functions.
16310 This calls the external "zegrep" program and returns the matching
16312 lines.
16313 This function returns a NULL-terminated array of strings (like
16315 environ(3)), or NULL if there was an error. The caller must free the
16316 strings and the array after use.
16317 Because of the message protocol, there is a transfer limit of somewhere
16319 between 2MB and 4MB. See "PROTOCOL LIMITS".
16320 (Added in 1.0.66)
16322 guestfs_zegrepi
16324 char **
16325 guestfs_zegrepi (guestfs_h *g,
16326 const char *regex,
16327 const char *path);
16328 This function is deprecated. In new code, use the "guestfs_grep" call
16330 instead.
16331 Deprecated functions will not be removed from the API, but the fact
16333 that they are deprecated indicates that there are problems with correct
16334 use of these functions.
16335 This calls the external "zegrep -i" program and returns the matching
16337 lines.
16338 This function returns a NULL-terminated array of strings (like
16340 environ(3)), or NULL if there was an error. The caller must free the
16341 strings and the array after use.
16342 Because of the message protocol, there is a transfer limit of somewhere
16344 between 2MB and 4MB. See "PROTOCOL LIMITS".
16345 (Added in 1.0.66)
16347 guestfs_zero
16349 int
16350 guestfs_zero (guestfs_h *g,
16351 const char *device);
16352 This command writes zeroes over the first few blocks of "device".
16354 How many blocks are zeroed isn't specified (but it’s not enough to
16356 securely wipe the device). It should be sufficient to remove any
16357 partition tables, filesystem superblocks and so on.
16358 If blocks are already zero, then this command avoids writing zeroes.
16360 This prevents the underlying device from becoming non-sparse or growing
16361 unnecessarily.
16362 See also: "guestfs_zero_device", "guestfs_scrub_device",
16364 "guestfs_is_zero_device"
16365 This function returns 0 on success or -1 on error.
16367 This long-running command can generate progress notification messages
16369 so that the caller can display a progress bar or indicator. To receive
16370 these messages, the caller must register a progress event callback.
16371 See "GUESTFS_EVENT_PROGRESS".
16372 (Added in 1.0.16)
16374 guestfs_zero_device
16376 int
16377 guestfs_zero_device (guestfs_h *g,
16378 const char *device);
16379 This command writes zeroes over the entire "device". Compare with
16381 "guestfs_zero" which just zeroes the first few blocks of a device.
16382 If blocks are already zero, then this command avoids writing zeroes.
16384 This prevents the underlying device from becoming non-sparse or growing
16385 unnecessarily.
16386 This function returns 0 on success or -1 on error.
16388 This long-running command can generate progress notification messages
16390 so that the caller can display a progress bar or indicator. To receive
16391 these messages, the caller must register a progress event callback.
16392 See "GUESTFS_EVENT_PROGRESS".
16393 (Added in 1.3.1)
16395 guestfs_zero_free_space
16397 int
16398 guestfs_zero_free_space (guestfs_h *g,
16399 const char *directory);
16400 Zero the free space in the filesystem mounted on directory. The
16402 filesystem must be mounted read-write.
16403 The filesystem contents are not affected, but any free space in the
16405 filesystem is freed.
16406 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16408 either as an alternative to this, or after calling this, depending on
16409 your requirements.
16410 This function returns 0 on success or -1 on error.
16412 This long-running command can generate progress notification messages
16414 so that the caller can display a progress bar or indicator. To receive
16415 these messages, the caller must register a progress event callback.
16416 See "GUESTFS_EVENT_PROGRESS".
16417 (Added in 1.17.18)
16419 guestfs_zerofree
16421 int
16422 guestfs_zerofree (guestfs_h *g,
16423 const char *device);
16424 This runs the zerofree program on "device". This program claims to
16426 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16427 it possible to compress the filesystem more effectively.
16428 You should not run this program if the filesystem is mounted.
16430 It is possible that using this program can damage the filesystem or
16432 data on the filesystem.
16433 This function returns 0 on success or -1 on error.
16435 This function depends on the feature "zerofree". See also
16437 "guestfs_feature_available".
16438 (Added in 1.0.26)
16440 guestfs_zfgrep
16442 char **
16443 guestfs_zfgrep (guestfs_h *g,
16444 const char *pattern,
16445 const char *path);
16446 This function is deprecated. In new code, use the "guestfs_grep" call
16448 instead.
16449 Deprecated functions will not be removed from the API, but the fact
16451 that they are deprecated indicates that there are problems with correct
16452 use of these functions.
16453 This calls the external "zfgrep" program and returns the matching
16455 lines.
16456 This function returns a NULL-terminated array of strings (like
16458 environ(3)), or NULL if there was an error. The caller must free the
16459 strings and the array after use.
16460 Because of the message protocol, there is a transfer limit of somewhere
16462 between 2MB and 4MB. See "PROTOCOL LIMITS".
16463 (Added in 1.0.66)
16465 guestfs_zfgrepi
16467 char **
16468 guestfs_zfgrepi (guestfs_h *g,
16469 const char *pattern,
16470 const char *path);
16471 This function is deprecated. In new code, use the "guestfs_grep" call
16473 instead.
16474 Deprecated functions will not be removed from the API, but the fact
16476 that they are deprecated indicates that there are problems with correct
16477 use of these functions.
16478 This calls the external "zfgrep -i" program and returns the matching
16480 lines.
16481 This function returns a NULL-terminated array of strings (like
16483 environ(3)), or NULL if there was an error. The caller must free the
16484 strings and the array after use.
16485 Because of the message protocol, there is a transfer limit of somewhere
16487 between 2MB and 4MB. See "PROTOCOL LIMITS".
16488 (Added in 1.0.66)
16490 guestfs_zfile
16492 char *
16493 guestfs_zfile (guestfs_h *g,
16494 const char *meth,
16495 const char *path);
16496 This function is deprecated. In new code, use the "guestfs_file" call
16498 instead.
16499 Deprecated functions will not be removed from the API, but the fact
16501 that they are deprecated indicates that there are problems with correct
16502 use of these functions.
16503 This command runs file(1) after first decompressing "path" using
16505 "meth".
16506 "meth" must be one of "gzip", "compress" or "bzip2".
16508 Since 1.0.63, use "guestfs_file" instead which can now process
16510 compressed files.
16511 This function returns a string, or NULL on error. The caller must free
16513 the returned string after use.
16514 (Added in 1.0.59)
16516 guestfs_zgrep
16518 char **
16519 guestfs_zgrep (guestfs_h *g,
16520 const char *regex,
16521 const char *path);
16522 This function is deprecated. In new code, use the "guestfs_grep" call
16524 instead.
16525 Deprecated functions will not be removed from the API, but the fact
16527 that they are deprecated indicates that there are problems with correct
16528 use of these functions.
16529 This calls the external zgrep(1) program and returns the matching
16531 lines.
16532 This function returns a NULL-terminated array of strings (like
16534 environ(3)), or NULL if there was an error. The caller must free the
16535 strings and the array after use.
16536 Because of the message protocol, there is a transfer limit of somewhere
16538 between 2MB and 4MB. See "PROTOCOL LIMITS".
16539 (Added in 1.0.66)
16541 guestfs_zgrepi
16543 char **
16544 guestfs_zgrepi (guestfs_h *g,
16545 const char *regex,
16546 const char *path);
16547 This function is deprecated. In new code, use the "guestfs_grep" call
16549 instead.
16550 Deprecated functions will not be removed from the API, but the fact
16552 that they are deprecated indicates that there are problems with correct
16553 use of these functions.
16554 This calls the external "zgrep -i" program and returns the matching
16556 lines.
16557 This function returns a NULL-terminated array of strings (like
16559 environ(3)), or NULL if there was an error. The caller must free the
16560 strings and the array after use.
16561 Because of the message protocol, there is a transfer limit of somewhere
16563 between 2MB and 4MB. See "PROTOCOL LIMITS".
16564 (Added in 1.0.66)
16566
16568 guestfs_int_bool
16569 struct guestfs_int_bool {
16570 int32_t i;
16571 int32_t b;
16572 };
16573 struct guestfs_int_bool_list {
16575 uint32_t len; /* Number of elements in list. */
16576 struct guestfs_int_bool *val; /* Elements. */
16577 };
16578 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16580 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16581 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16583 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16584 void guestfs_free_int_bool (struct guestfs_int_bool *);
16586 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16587 guestfs_lvm_pv
16589 struct guestfs_lvm_pv {
16590 char *pv_name;
16591 /* The next field is NOT nul-terminated, be careful when printing it: */
16592 char pv_uuid[32];
16593 char *pv_fmt;
16594 uint64_t pv_size;
16595 uint64_t dev_size;
16596 uint64_t pv_free;
16597 uint64_t pv_used;
16598 char *pv_attr;
16599 int64_t pv_pe_count;
16600 int64_t pv_pe_alloc_count;
16601 char *pv_tags;
16602 uint64_t pe_start;
16603 int64_t pv_mda_count;
16604 uint64_t pv_mda_free;
16605 };
16606 struct guestfs_lvm_pv_list {
16608 uint32_t len; /* Number of elements in list. */
16609 struct guestfs_lvm_pv *val; /* Elements. */
16610 };
16611 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16613 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16614 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16616 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16617 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16619 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16620 guestfs_lvm_vg
16622 struct guestfs_lvm_vg {
16623 char *vg_name;
16624 /* The next field is NOT nul-terminated, be careful when printing it: */
16625 char vg_uuid[32];
16626 char *vg_fmt;
16627 char *vg_attr;
16628 uint64_t vg_size;
16629 uint64_t vg_free;
16630 char *vg_sysid;
16631 uint64_t vg_extent_size;
16632 int64_t vg_extent_count;
16633 int64_t vg_free_count;
16634 int64_t max_lv;
16635 int64_t max_pv;
16636 int64_t pv_count;
16637 int64_t lv_count;
16638 int64_t snap_count;
16639 int64_t vg_seqno;
16640 char *vg_tags;
16641 int64_t vg_mda_count;
16642 uint64_t vg_mda_free;
16643 };
16644 struct guestfs_lvm_vg_list {
16646 uint32_t len; /* Number of elements in list. */
16647 struct guestfs_lvm_vg *val; /* Elements. */
16648 };
16649 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16651 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16652 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16654 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16655 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16657 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16658 guestfs_lvm_lv
16660 struct guestfs_lvm_lv {
16661 char *lv_name;
16662 /* The next field is NOT nul-terminated, be careful when printing it: */
16663 char lv_uuid[32];
16664 char *lv_attr;
16665 int64_t lv_major;
16666 int64_t lv_minor;
16667 int64_t lv_kernel_major;
16668 int64_t lv_kernel_minor;
16669 uint64_t lv_size;
16670 int64_t seg_count;
16671 char *origin;
16672 /* The next field is [0..100] or -1 meaning 'not present': */
16673 float snap_percent;
16674 /* The next field is [0..100] or -1 meaning 'not present': */
16675 float copy_percent;
16676 char *move_pv;
16677 char *lv_tags;
16678 char *mirror_log;
16679 char *modules;
16680 };
16681 struct guestfs_lvm_lv_list {
16683 uint32_t len; /* Number of elements in list. */
16684 struct guestfs_lvm_lv *val; /* Elements. */
16685 };
16686 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16688 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16689 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16691 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16692 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16694 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16695 guestfs_stat
16697 struct guestfs_stat {
16698 int64_t dev;
16699 int64_t ino;
16700 int64_t mode;
16701 int64_t nlink;
16702 int64_t uid;
16703 int64_t gid;
16704 int64_t rdev;
16705 int64_t size;
16706 int64_t blksize;
16707 int64_t blocks;
16708 int64_t atime;
16709 int64_t mtime;
16710 int64_t ctime;
16711 };
16712 struct guestfs_stat_list {
16714 uint32_t len; /* Number of elements in list. */
16715 struct guestfs_stat *val; /* Elements. */
16716 };
16717 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16719 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16720 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16722 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16723 void guestfs_free_stat (struct guestfs_stat *);
16725 void guestfs_free_stat_list (struct guestfs_stat_list *);
16726 guestfs_statns
16728 struct guestfs_statns {
16729 int64_t st_dev;
16730 int64_t st_ino;
16731 int64_t st_mode;
16732 int64_t st_nlink;
16733 int64_t st_uid;
16734 int64_t st_gid;
16735 int64_t st_rdev;
16736 int64_t st_size;
16737 int64_t st_blksize;
16738 int64_t st_blocks;
16739 int64_t st_atime_sec;
16740 int64_t st_atime_nsec;
16741 int64_t st_mtime_sec;
16742 int64_t st_mtime_nsec;
16743 int64_t st_ctime_sec;
16744 int64_t st_ctime_nsec;
16745 int64_t st_spare1;
16746 int64_t st_spare2;
16747 int64_t st_spare3;
16748 int64_t st_spare4;
16749 int64_t st_spare5;
16750 int64_t st_spare6;
16751 };
16752 struct guestfs_statns_list {
16754 uint32_t len; /* Number of elements in list. */
16755 struct guestfs_statns *val; /* Elements. */
16756 };
16757 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16759 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16760 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16762 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16763 void guestfs_free_statns (struct guestfs_statns *);
16765 void guestfs_free_statns_list (struct guestfs_statns_list *);
16766 guestfs_statvfs
16768 struct guestfs_statvfs {
16769 int64_t bsize;
16770 int64_t frsize;
16771 int64_t blocks;
16772 int64_t bfree;
16773 int64_t bavail;
16774 int64_t files;
16775 int64_t ffree;
16776 int64_t favail;
16777 int64_t fsid;
16778 int64_t flag;
16779 int64_t namemax;
16780 };
16781 struct guestfs_statvfs_list {
16783 uint32_t len; /* Number of elements in list. */
16784 struct guestfs_statvfs *val; /* Elements. */
16785 };
16786 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16788 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16789 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16791 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16792 void guestfs_free_statvfs (struct guestfs_statvfs *);
16794 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16795 guestfs_dirent
16797 struct guestfs_dirent {
16798 int64_t ino;
16799 char ftyp;
16800 char *name;
16801 };
16802 struct guestfs_dirent_list {
16804 uint32_t len; /* Number of elements in list. */
16805 struct guestfs_dirent *val; /* Elements. */
16806 };
16807 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16809 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16810 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16812 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16813 void guestfs_free_dirent (struct guestfs_dirent *);
16815 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16816 guestfs_version
16818 struct guestfs_version {
16819 int64_t major;
16820 int64_t minor;
16821 int64_t release;
16822 char *extra;
16823 };
16824 struct guestfs_version_list {
16826 uint32_t len; /* Number of elements in list. */
16827 struct guestfs_version *val; /* Elements. */
16828 };
16829 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16831 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16832 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16834 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16835 void guestfs_free_version (struct guestfs_version *);
16837 void guestfs_free_version_list (struct guestfs_version_list *);
16838 guestfs_xattr
16840 struct guestfs_xattr {
16841 char *attrname;
16842 /* The next two fields describe a byte array. */
16843 uint32_t attrval_len;
16844 char *attrval;
16845 };
16846 struct guestfs_xattr_list {
16848 uint32_t len; /* Number of elements in list. */
16849 struct guestfs_xattr *val; /* Elements. */
16850 };
16851 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16853 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16854 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
16856 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
16857 void guestfs_free_xattr (struct guestfs_xattr *);
16859 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
16860 guestfs_inotify_event
16862 struct guestfs_inotify_event {
16863 int64_t in_wd;
16864 uint32_t in_mask;
16865 uint32_t in_cookie;
16866 char *in_name;
16867 };
16868 struct guestfs_inotify_event_list {
16870 uint32_t len; /* Number of elements in list. */
16871 struct guestfs_inotify_event *val; /* Elements. */
16872 };
16873 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
16875 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
16876 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
16878 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
16879 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
16881 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
16882 guestfs_partition
16884 struct guestfs_partition {
16885 int32_t part_num;
16886 uint64_t part_start;
16887 uint64_t part_end;
16888 uint64_t part_size;
16889 };
16890 struct guestfs_partition_list {
16892 uint32_t len; /* Number of elements in list. */
16893 struct guestfs_partition *val; /* Elements. */
16894 };
16895 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
16897 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
16898 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
16900 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
16901 void guestfs_free_partition (struct guestfs_partition *);
16903 void guestfs_free_partition_list (struct guestfs_partition_list *);
16904 guestfs_application
16906 struct guestfs_application {
16907 char *app_name;
16908 char *app_display_name;
16909 int32_t app_epoch;
16910 char *app_version;
16911 char *app_release;
16912 char *app_install_path;
16913 char *app_trans_path;
16914 char *app_publisher;
16915 char *app_url;
16916 char *app_source_package;
16917 char *app_summary;
16918 char *app_description;
16919 };
16920 struct guestfs_application_list {
16922 uint32_t len; /* Number of elements in list. */
16923 struct guestfs_application *val; /* Elements. */
16924 };
16925 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
16927 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
16928 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
16930 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
16931 void guestfs_free_application (struct guestfs_application *);
16933 void guestfs_free_application_list (struct guestfs_application_list *);
16934 guestfs_application2
16936 struct guestfs_application2 {
16937 char *app2_name;
16938 char *app2_display_name;
16939 int32_t app2_epoch;
16940 char *app2_version;
16941 char *app2_release;
16942 char *app2_arch;
16943 char *app2_install_path;
16944 char *app2_trans_path;
16945 char *app2_publisher;
16946 char *app2_url;
16947 char *app2_source_package;
16948 char *app2_summary;
16949 char *app2_description;
16950 char *app2_spare1;
16951 char *app2_spare2;
16952 char *app2_spare3;
16953 char *app2_spare4;
16954 };
16955 struct guestfs_application2_list {
16957 uint32_t len; /* Number of elements in list. */
16958 struct guestfs_application2 *val; /* Elements. */
16959 };
16960 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
16962 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
16963 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
16965 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
16966 void guestfs_free_application2 (struct guestfs_application2 *);
16968 void guestfs_free_application2_list (struct guestfs_application2_list *);
16969 guestfs_isoinfo
16971 struct guestfs_isoinfo {
16972 char *iso_system_id;
16973 char *iso_volume_id;
16974 uint32_t iso_volume_space_size;
16975 uint32_t iso_volume_set_size;
16976 uint32_t iso_volume_sequence_number;
16977 uint32_t iso_logical_block_size;
16978 char *iso_volume_set_id;
16979 char *iso_publisher_id;
16980 char *iso_data_preparer_id;
16981 char *iso_application_id;
16982 char *iso_copyright_file_id;
16983 char *iso_abstract_file_id;
16984 char *iso_bibliographic_file_id;
16985 int64_t iso_volume_creation_t;
16986 int64_t iso_volume_modification_t;
16987 int64_t iso_volume_expiration_t;
16988 int64_t iso_volume_effective_t;
16989 };
16990 struct guestfs_isoinfo_list {
16992 uint32_t len; /* Number of elements in list. */
16993 struct guestfs_isoinfo *val; /* Elements. */
16994 };
16995 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
16997 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
16998 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
17000 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
17001 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
17003 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
17004 guestfs_mdstat
17006 struct guestfs_mdstat {
17007 char *mdstat_device;
17008 int32_t mdstat_index;
17009 char *mdstat_flags;
17010 };
17011 struct guestfs_mdstat_list {
17013 uint32_t len; /* Number of elements in list. */
17014 struct guestfs_mdstat *val; /* Elements. */
17015 };
17016 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
17018 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
17019 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
17021 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
17022 void guestfs_free_mdstat (struct guestfs_mdstat *);
17024 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
17025 guestfs_btrfssubvolume
17027 struct guestfs_btrfssubvolume {
17028 uint64_t btrfssubvolume_id;
17029 uint64_t btrfssubvolume_top_level_id;
17030 char *btrfssubvolume_path;
17031 };
17032 struct guestfs_btrfssubvolume_list {
17034 uint32_t len; /* Number of elements in list. */
17035 struct guestfs_btrfssubvolume *val; /* Elements. */
17036 };
17037 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17039 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17040 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17042 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17043 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17045 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17046 guestfs_btrfsqgroup
17048 struct guestfs_btrfsqgroup {
17049 char *btrfsqgroup_id;
17050 uint64_t btrfsqgroup_rfer;
17051 uint64_t btrfsqgroup_excl;
17052 };
17053 struct guestfs_btrfsqgroup_list {
17055 uint32_t len; /* Number of elements in list. */
17056 struct guestfs_btrfsqgroup *val; /* Elements. */
17057 };
17058 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17060 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17061 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17063 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17064 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17066 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17067 guestfs_btrfsbalance
17069 struct guestfs_btrfsbalance {
17070 char *btrfsbalance_status;
17071 uint64_t btrfsbalance_total;
17072 uint64_t btrfsbalance_balanced;
17073 uint64_t btrfsbalance_considered;
17074 uint64_t btrfsbalance_left;
17075 };
17076 struct guestfs_btrfsbalance_list {
17078 uint32_t len; /* Number of elements in list. */
17079 struct guestfs_btrfsbalance *val; /* Elements. */
17080 };
17081 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17083 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17084 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17086 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17087 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17089 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17090 guestfs_btrfsscrub
17092 struct guestfs_btrfsscrub {
17093 uint64_t btrfsscrub_data_extents_scrubbed;
17094 uint64_t btrfsscrub_tree_extents_scrubbed;
17095 uint64_t btrfsscrub_data_bytes_scrubbed;
17096 uint64_t btrfsscrub_tree_bytes_scrubbed;
17097 uint64_t btrfsscrub_read_errors;
17098 uint64_t btrfsscrub_csum_errors;
17099 uint64_t btrfsscrub_verify_errors;
17100 uint64_t btrfsscrub_no_csum;
17101 uint64_t btrfsscrub_csum_discards;
17102 uint64_t btrfsscrub_super_errors;
17103 uint64_t btrfsscrub_malloc_errors;
17104 uint64_t btrfsscrub_uncorrectable_errors;
17105 uint64_t btrfsscrub_unverified_errors;
17106 uint64_t btrfsscrub_corrected_errors;
17107 uint64_t btrfsscrub_last_physical;
17108 };
17109 struct guestfs_btrfsscrub_list {
17111 uint32_t len; /* Number of elements in list. */
17112 struct guestfs_btrfsscrub *val; /* Elements. */
17113 };
17114 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17116 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17117 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17119 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17120 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17122 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17123 guestfs_xfsinfo
17125 struct guestfs_xfsinfo {
17126 char *xfs_mntpoint;
17127 uint32_t xfs_inodesize;
17128 uint32_t xfs_agcount;
17129 uint32_t xfs_agsize;
17130 uint32_t xfs_sectsize;
17131 uint32_t xfs_attr;
17132 uint32_t xfs_blocksize;
17133 uint64_t xfs_datablocks;
17134 uint32_t xfs_imaxpct;
17135 uint32_t xfs_sunit;
17136 uint32_t xfs_swidth;
17137 uint32_t xfs_dirversion;
17138 uint32_t xfs_dirblocksize;
17139 uint32_t xfs_cimode;
17140 char *xfs_logname;
17141 uint32_t xfs_logblocksize;
17142 uint32_t xfs_logblocks;
17143 uint32_t xfs_logversion;
17144 uint32_t xfs_logsectsize;
17145 uint32_t xfs_logsunit;
17146 uint32_t xfs_lazycount;
17147 char *xfs_rtname;
17148 uint32_t xfs_rtextsize;
17149 uint64_t xfs_rtblocks;
17150 uint64_t xfs_rtextents;
17151 };
17152 struct guestfs_xfsinfo_list {
17154 uint32_t len; /* Number of elements in list. */
17155 struct guestfs_xfsinfo *val; /* Elements. */
17156 };
17157 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17159 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17160 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17162 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17163 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17165 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17166 guestfs_utsname
17168 struct guestfs_utsname {
17169 char *uts_sysname;
17170 char *uts_release;
17171 char *uts_version;
17172 char *uts_machine;
17173 };
17174 struct guestfs_utsname_list {
17176 uint32_t len; /* Number of elements in list. */
17177 struct guestfs_utsname *val; /* Elements. */
17178 };
17179 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17181 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17182 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17184 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17185 void guestfs_free_utsname (struct guestfs_utsname *);
17187 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17188 guestfs_hivex_node
17190 struct guestfs_hivex_node {
17191 int64_t hivex_node_h;
17192 };
17193 struct guestfs_hivex_node_list {
17195 uint32_t len; /* Number of elements in list. */
17196 struct guestfs_hivex_node *val; /* Elements. */
17197 };
17198 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17200 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17201 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17203 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17204 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17206 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17207 guestfs_hivex_value
17209 struct guestfs_hivex_value {
17210 int64_t hivex_value_h;
17211 };
17212 struct guestfs_hivex_value_list {
17214 uint32_t len; /* Number of elements in list. */
17215 struct guestfs_hivex_value *val; /* Elements. */
17216 };
17217 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17219 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17220 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17222 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17223 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17225 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17226 guestfs_internal_mountable
17228 struct guestfs_internal_mountable {
17229 int32_t im_type;
17230 char *im_device;
17231 char *im_volume;
17232 };
17233 struct guestfs_internal_mountable_list {
17235 uint32_t len; /* Number of elements in list. */
17236 struct guestfs_internal_mountable *val; /* Elements. */
17237 };
17238 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17240 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17241 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17243 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17244 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17246 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17247 guestfs_tsk_dirent
17249 struct guestfs_tsk_dirent {
17250 uint64_t tsk_inode;
17251 char tsk_type;
17252 int64_t tsk_size;
17253 char *tsk_name;
17254 uint32_t tsk_flags;
17255 int64_t tsk_atime_sec;
17256 int64_t tsk_atime_nsec;
17257 int64_t tsk_mtime_sec;
17258 int64_t tsk_mtime_nsec;
17259 int64_t tsk_ctime_sec;
17260 int64_t tsk_ctime_nsec;
17261 int64_t tsk_crtime_sec;
17262 int64_t tsk_crtime_nsec;
17263 int64_t tsk_nlink;
17264 char *tsk_link;
17265 int64_t tsk_spare1;
17266 };
17267 struct guestfs_tsk_dirent_list {
17269 uint32_t len; /* Number of elements in list. */
17270 struct guestfs_tsk_dirent *val; /* Elements. */
17271 };
17272 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17274 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17275 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17277 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17278 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17280 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17281 guestfs_yara_detection
17283 struct guestfs_yara_detection {
17284 char *yara_name;
17285 char *yara_rule;
17286 };
17287 struct guestfs_yara_detection_list {
17289 uint32_t len; /* Number of elements in list. */
17290 struct guestfs_yara_detection *val; /* Elements. */
17291 };
17292 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17294 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17295 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17297 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17298 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17300 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17301
17303 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17304 Using "guestfs_available" you can test availability of the following
17305 groups of functions. This test queries the appliance to see if the
17306 appliance you are currently using supports the functionality.
17307 acl The following functions: "guestfs_acl_delete_def_file"
17309 "guestfs_acl_get_file" "guestfs_acl_set_file"
17310 blkdiscard
17312 The following functions: "guestfs_blkdiscard"
17313 blkdiscardzeroes
17315 The following functions: "guestfs_blkdiscardzeroes"
17316 btrfs
17318 The following functions: "guestfs_btrfs_balance_cancel"
17319 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17320 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17321 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17322 "guestfs_btrfs_filesystem_defragment"
17323 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17324 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17325 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17326 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17327 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17328 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17329 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17330 "guestfs_btrfs_rescue_chunk_recover"
17331 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17332 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17333 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17334 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17335 "guestfs_btrfs_subvolume_get_default"
17336 "guestfs_btrfs_subvolume_list"
17337 "guestfs_btrfs_subvolume_set_default"
17338 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17339 "guestfs_btrfstune_enable_extended_inode_refs"
17340 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17341 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17342 extlinux
17344 The following functions: "guestfs_extlinux"
17345 f2fs
17347 The following functions: "guestfs_f2fs_expand"
17348 fstrim
17350 The following functions: "guestfs_fstrim"
17351 gdisk
17353 The following functions: "guestfs_part_expand_gpt"
17354 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17355 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17356 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17357 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17358 "guestfs_part_set_gpt_type"
17359 grub
17361 The following functions: "guestfs_grub_install"
17362 hivex
17364 The following functions: "guestfs_hivex_close"
17365 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17366 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17367 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17368 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17369 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17370 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17371 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17372 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17373 inotify
17375 The following functions: "guestfs_inotify_add_watch"
17376 "guestfs_inotify_close" "guestfs_inotify_files"
17377 "guestfs_inotify_init" "guestfs_inotify_read"
17378 "guestfs_inotify_rm_watch"
17379 journal
17381 The following functions: "guestfs_internal_journal_get"
17382 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17383 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17384 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17385 "guestfs_journal_skip"
17386 ldm The following functions: "guestfs_ldmtool_create_all"
17388 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17389 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17390 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17391 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17392 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17393 "guestfs_list_ldm_volumes"
17394 libtsk
17396 The following functions: "guestfs_internal_filesystem_walk"
17397 "guestfs_internal_find_inode"
17398 libyara
17400 The following functions: "guestfs_internal_yara_scan"
17401 "guestfs_yara_destroy" "guestfs_yara_load"
17402 linuxcaps
17404 The following functions: "guestfs_cap_get_file"
17405 "guestfs_cap_set_file"
17406 linuxfsuuid
17408 The following functions: "guestfs_mke2fs_JU"
17409 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17410 "guestfs_swapon_uuid"
17411 linuxmodules
17413 The following functions: "guestfs_modprobe"
17414 linuxxattrs
17416 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17417 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17418 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17419 "guestfs_removexattr" "guestfs_setxattr"
17420 luks
17422 The following functions: "guestfs_cryptsetup_close"
17423 "guestfs_cryptsetup_open" "guestfs_luks_add_key"
17424 "guestfs_luks_close" "guestfs_luks_format"
17425 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17426 "guestfs_luks_open" "guestfs_luks_open_ro" "guestfs_luks_uuid"
17427 lvm2
17429 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17430 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17431 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17432 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17433 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17434 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17435 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17436 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17437 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17438 "guestfs_vgs" "guestfs_vgs_full"
17439 mdadm
17441 The following functions: "guestfs_md_create" "guestfs_md_detail"
17442 "guestfs_md_stat" "guestfs_md_stop"
17443 mknod
17445 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17446 "guestfs_mknod_b" "guestfs_mknod_c"
17447 ntfs3g
17449 The following functions: "guestfs_ntfs_3g_probe"
17450 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17451 ntfsprogs
17453 The following functions: "guestfs_ntfsresize"
17454 "guestfs_ntfsresize_size"
17455 rsync
17457 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17458 "guestfs_rsync_out"
17459 scrub
17461 The following functions: "guestfs_scrub_device"
17462 "guestfs_scrub_file" "guestfs_scrub_freespace"
17463 selinux
17465 The following functions: "guestfs_getcon" "guestfs_setcon"
17466 selinuxrelabel
17468 The following functions: "guestfs_selinux_relabel"
17469 sleuthkit
17471 The following functions: "guestfs_download_blocks"
17472 "guestfs_download_inode"
17473 squashfs
17475 The following functions: "guestfs_mksquashfs"
17476 syslinux
17478 The following functions: "guestfs_syslinux"
17479 wipefs
17481 The following functions: "guestfs_wipefs"
17482 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17484 "guestfs_xfs_info" "guestfs_xfs_repair"
17485 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17487 zerofree
17489 The following functions: "guestfs_zerofree"
17490 FILESYSTEM AVAILABLE
17492 The "guestfs_filesystem_available" call tests whether a filesystem type
17493 is supported by the appliance kernel.
17494 This is mainly useful as a negative test. If this returns true, it
17496 doesn't mean that a particular filesystem can be mounted, since
17497 filesystems can fail for other reasons such as it being a later version
17498 of the filesystem, or having incompatible features.
17499 GUESTFISH supported COMMAND
17501 In guestfish(3) there is a handy interactive command "supported" which
17502 prints out the available groups and whether they are supported by this
17503 build of libguestfs. Note however that you have to do "run" first.
17504 SINGLE CALLS AT COMPILE TIME
17506 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17507 function, such as:
17508 #define GUESTFS_HAVE_DD 1
17510 if "guestfs_dd" is available.
17512 Before version 1.5.8, if you needed to test whether a single libguestfs
17514 function is available at compile time, we recommended using build tools
17515 such as autoconf or cmake. For example in autotools you could use:
17516 AC_CHECK_LIB([guestfs],[guestfs_create])
17518 AC_CHECK_FUNCS([guestfs_dd])
17519 which would result in "HAVE_GUESTFS_DD" being either defined or not
17521 defined in your program.
17522 SINGLE CALLS AT RUN TIME
17524 Testing at compile time doesn't guarantee that a function really exists
17525 in the library. The reason is that you might be dynamically linked
17526 against a previous libguestfs.so (dynamic library) which doesn't have
17527 the call. This situation unfortunately results in a segmentation
17528 fault, which is a shortcoming of the C dynamic linking system itself.
17529 You can use dlopen(3) to test if a function is available at run time,
17531 as in this example program (note that you still need the compile time
17532 check as well):
17533 #include <stdio.h>
17535 #include <stdlib.h>
17536 #include <unistd.h>
17537 #include <dlfcn.h>
17538 #include <guestfs.h>
17539 main ()
17541 {
17542 #ifdef GUESTFS_HAVE_DD
17543 void *dl;
17544 int has_function;
17545 /* Test if the function guestfs_dd is really available. */
17547 dl = dlopen (NULL, RTLD_LAZY);
17548 if (!dl) {
17549 fprintf (stderr, "dlopen: %s\n", dlerror ());
17550 exit (EXIT_FAILURE);
17551 }
17552 has_function = dlsym (dl, "guestfs_dd") != NULL;
17553 dlclose (dl);
17554 if (!has_function)
17556 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17557 else {
17558 printf ("this libguestfs.so has guestfs_dd function\n");
17559 /* Now it's safe to call
17560 guestfs_dd (g, "foo", "bar");
17561 */
17562 }
17563 #else
17564 printf ("guestfs_dd function was not found at compile time\n");
17565 #endif
17566 }
17567 You may think the above is an awful lot of hassle, and it is. There
17569 are other ways outside of the C linking system to ensure that this kind
17570 of incompatibility never arises, such as using package versioning:
17571 Requires: libguestfs >= 1.0.80
17573
17575 A recent feature of the API is the introduction of calls which take
17576 optional arguments. In C these are declared 3 ways. The main way is
17577 as a call which takes variable arguments (ie. "..."), as in this
17578 example:
17579 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17581 Call this with a list of optional arguments, terminated by "-1". So to
17583 call with no optional arguments specified:
17584 guestfs_add_drive_opts (g, filename, -1);
17586 With a single optional argument:
17588 guestfs_add_drive_opts (g, filename,
17590 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17591 -1);
17592 With two:
17594 guestfs_add_drive_opts (g, filename,
17596 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17597 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17598 -1);
17599 and so forth. Don’t forget the terminating "-1" otherwise Bad Things
17601 will happen!
17602 USING va_list FOR OPTIONAL ARGUMENTS
17604 The second variant has the same name with the suffix "_va", which works
17605 the same way but takes a "va_list". See the C manual for details. For
17606 the example function, this is declared:
17607 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17609 va_list args);
17610 CONSTRUCTING OPTIONAL ARGUMENTS
17612 The third variant is useful where you need to construct these calls.
17613 You pass in a structure where you fill in the optional fields. The
17614 structure has a bitmask as the first element which you must set to
17615 indicate which fields you have filled in. For our example function the
17616 structure and call are declared:
17617 struct guestfs_add_drive_opts_argv {
17619 uint64_t bitmask;
17620 int readonly;
17621 const char *format;
17622 /* ... */
17623 };
17624 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17625 const struct guestfs_add_drive_opts_argv *optargs);
17626 You could call it like this:
17628 struct guestfs_add_drive_opts_argv optargs = {
17630 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17631 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17632 .readonly = 1,
17633 .format = "qcow2"
17634 };
17635 guestfs_add_drive_opts_argv (g, filename, &optargs);
17637 Notes:
17639 • The "_BITMASK" suffix on each option name when specifying the
17641 bitmask.
17642 • You do not need to fill in all fields of the structure.
17644 • There must be a one-to-one correspondence between fields of the
17646 structure that are filled in, and bits set in the bitmask.
17647 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17649 In other languages, optional arguments are expressed in the way that is
17650 natural for that language. We refer you to the language-specific
17651 documentation for more details on that.
17652 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17654
17656 SETTING CALLBACKS TO HANDLE EVENTS
17657 Note: This section documents the generic event mechanism introduced in
17658 libguestfs 1.10, which you should use in new code if possible. The old
17659 functions "guestfs_set_log_message_callback",
17660 "guestfs_set_subprocess_quit_callback",
17661 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17662 "guestfs_set_progress_callback" are no longer documented in this manual
17663 page. Because of the ABI guarantee, the old functions continue to
17664 work.
17665 Handles generate events when certain things happen, such as log
17667 messages being generated, progress messages during long-running
17668 operations, or the handle being closed. The API calls described below
17669 let you register a callback to be called when events happen. You can
17670 register multiple callbacks (for the same, different or overlapping
17671 sets of events), and individually remove callbacks. If callbacks are
17672 not removed, then they remain in force until the handle is closed.
17673 In the current implementation, events are only generated synchronously:
17675 that means that events (and hence callbacks) can only happen while you
17676 are in the middle of making another libguestfs call. The callback is
17677 called in the same thread.
17678 Events may contain a payload, usually nothing (void), an array of 64
17680 bit unsigned integers, or a message buffer. Payloads are discussed
17681 later on.
17682 CLASSES OF EVENTS
17684 GUESTFS_EVENT_CLOSE (payload type: void)
17685 The callback function will be called while the handle is being
17686 closed (synchronously from "guestfs_close").
17687 Note that libguestfs installs an atexit(3) handler to try to clean
17689 up handles that are open when the program exits. This means that
17690 this callback might be called indirectly from exit(3), which can
17691 cause unexpected problems in higher-level languages (eg. if your
17692 HLL interpreter has already been cleaned up by the time this is
17693 called, and if your callback then jumps into some HLL function).
17694 If no callback is registered: the handle is closed without any
17696 callback being invoked.
17697 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17699 The callback function will be called when the child process quits,
17700 either asynchronously or if killed by "guestfs_kill_subprocess".
17701 (This corresponds to a transition from any state to the CONFIG
17702 state).
17703 If no callback is registered: the event is ignored.
17705 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17707 The callback function will be called when the child process becomes
17708 ready first time after it has been launched. (This corresponds to
17709 a transition from LAUNCHING to the READY state).
17710 If no callback is registered: the event is ignored.
17712 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17714 Some long-running operations can generate progress messages. If
17715 this callback is registered, then it will be called each time a
17716 progress message is generated (usually two seconds after the
17717 operation started, and three times per second thereafter until it
17718 completes, although the frequency may change in future versions).
17719 The callback receives in the payload four unsigned 64 bit numbers
17721 which are (in order): "proc_nr", "serial", "position", "total".
17722 The units of "total" are not defined, although for some operations
17724 "total" may relate in some way to the amount of data to be
17725 transferred (eg. in bytes or megabytes), and "position" may be the
17726 portion which has been transferred.
17727 The only defined and stable parts of the API are:
17729 • The callback can display to the user some type of progress bar
17731 or indicator which shows the ratio of "position":"total".
17732 • 0 <= "position" <= "total"
17734 • If any progress notification is sent during a call, then a
17736 final progress notification is always sent when "position" =
17737 "total" (unless the call fails with an error).
17738 This is to simplify caller code, so callers can easily set the
17740 progress indicator to "100%" at the end of the operation,
17741 without requiring special code to detect this case.
17742 • For some calls we are unable to estimate the progress of the
17744 call, but we can still generate progress messages to indicate
17745 activity. This is known as "pulse mode", and is directly
17746 supported by certain progress bar implementations (eg.
17747 GtkProgressBar).
17748 For these calls, zero or more progress messages are generated
17750 with "position = 0" and "total = 1", followed by a final
17751 message with "position = total = 1".
17752 As noted above, if the call fails with an error then the final
17754 message may not be generated.
17755 The callback also receives the procedure number ("proc_nr") and
17757 serial number ("serial") of the call. These are only useful for
17758 debugging protocol issues, and the callback can normally ignore
17759 them. The callback may want to print these numbers in error
17760 messages or debugging messages.
17761 If no callback is registered: progress messages are discarded.
17763 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17765 The callback function is called whenever a log message is generated
17766 by qemu, the appliance kernel, guestfsd (daemon), or utility
17767 programs.
17768 If the verbose flag ("guestfs_set_verbose") is set before launch
17770 ("guestfs_launch") then additional debug messages are generated.
17771 If no callback is registered: the messages are discarded unless the
17773 verbose flag is set in which case they are sent to stderr. You can
17774 override the printing of verbose messages to stderr by setting up a
17775 callback.
17776 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17778 The callback function is called whenever a log message is generated
17779 by the library part of libguestfs.
17780 If the verbose flag ("guestfs_set_verbose") is set then additional
17782 debug messages are generated.
17783 If no callback is registered: the messages are discarded unless the
17785 verbose flag is set in which case they are sent to stderr. You can
17786 override the printing of verbose messages to stderr by setting up a
17787 callback.
17788 GUESTFS_EVENT_WARNING (payload type: message buffer)
17790 The callback function is called whenever a warning message is
17791 generated by the library part of libguestfs.
17792 If no callback is registered: the messages are printed to stderr.
17794 You can override the printing of warning messages to stderr by
17795 setting up a callback.
17796 GUESTFS_EVENT_TRACE (payload type: message buffer)
17798 The callback function is called whenever a trace message is
17799 generated. This only applies if the trace flag
17800 ("guestfs_set_trace") is set.
17801 If no callback is registered: the messages are sent to stderr. You
17803 can override the printing of trace messages to stderr by setting up
17804 a callback.
17805 GUESTFS_EVENT_ENTER (payload type: function name)
17807 The callback function is called whenever a libguestfs function is
17808 entered.
17809 The payload is a string which contains the name of the function
17811 that we are entering (not including "guestfs_" prefix).
17812 Note that libguestfs functions can call themselves, so you may see
17814 many events from a single call. A few libguestfs functions do not
17815 generate this event.
17816 If no callback is registered: the event is ignored.
17818 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17820 For any API function that opens a libvirt connection, this event
17821 may be generated to indicate that libvirt demands authentication
17822 information. See "LIBVIRT AUTHENTICATION" below.
17823 If no callback is registered: "virConnectAuthPtrDefault" is used
17825 (suitable for command-line programs only).
17826 EVENT API
17828 guestfs_set_event_callback
17829 int guestfs_set_event_callback (guestfs_h *g,
17831 guestfs_event_callback cb,
17832 uint64_t event_bitmask,
17833 int flags,
17834 void *opaque);
17835 This function registers a callback ("cb") for all event classes in the
17837 "event_bitmask".
17838 For example, to register for all log message events, you could call
17840 this function with the bitmask
17841 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17842 To register a single callback for all possible classes of events, use
17843 "GUESTFS_EVENT_ALL".
17844 "flags" should always be passed as 0.
17846 "opaque" is an opaque pointer which is passed to the callback. You can
17848 use it for any purpose.
17849 The return value is the event handle (an integer) which you can use to
17851 delete the callback (see below).
17852 If there is an error, this function returns "-1", and sets the error in
17854 the handle in the usual way (see "guestfs_last_error" etc.)
17855 Callbacks remain in effect until they are deleted, or until the handle
17857 is closed.
17858 In the case where multiple callbacks are registered for a particular
17860 event class, all of the callbacks are called. The order in which
17861 multiple callbacks are called is not defined.
17862 guestfs_delete_event_callback
17864 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
17866 Delete a callback that was previously registered. "event_handle"
17868 should be the integer that was returned by a previous call to
17869 "guestfs_set_event_callback" on the same handle.
17870 guestfs_event_to_string
17872 char *guestfs_event_to_string (uint64_t event);
17874 "event" is either a single event or a bitmask of events. This returns
17876 a string representation (useful for debugging or printing events).
17877 A single event is returned as the name in lower case, eg. "close".
17879 A bitmask of several events is returned as a comma-separated list, eg.
17881 "close,progress".
17882 If zero is passed, then the empty string "" is returned.
17884 On success this returns a string. On error it returns NULL and sets
17886 "errno".
17887 The returned string must be freed by the caller.
17889 guestfs_event_callback
17891 typedef void (*guestfs_event_callback) (
17893 guestfs_h *g,
17894 void *opaque,
17895 uint64_t event,
17896 int event_handle,
17897 int flags,
17898 const char *buf, size_t buf_len,
17899 const uint64_t *array, size_t array_len);
17900 This is the type of the event callback function that you have to
17902 provide.
17903 The basic parameters are: the handle ("g"), the opaque user pointer
17905 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
17906 handle, and "flags" which in the current API you should ignore.
17907 The remaining parameters contain the event payload (if any). Each
17909 event may contain a payload, which usually relates to the event class,
17910 but for future proofing your code should be written to handle any
17911 payload for any event class.
17912 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
17914 there is no message buffer). Note that this message buffer can contain
17915 arbitrary 8 bit data, including NUL bytes.
17916 "array" and "array_len" is an array of 64 bit unsigned integers. At
17918 the moment this is only used for progress messages.
17919 EXAMPLE: CAPTURING LOG MESSAGES
17921 A working program demonstrating this can be found in
17922 examples/debug-logging.c in the source of libguestfs.
17923 One motivation for the generic event API was to allow GUI programs to
17925 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
17926 unconditionally to "stderr".
17927 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
17929 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
17930 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
17931 must capture error messages separately).
17932 Programs have to set up a callback to capture the classes of events of
17934 interest:
17935 int eh =
17937 guestfs_set_event_callback
17938 (g, message_callback,
17939 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
17940 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
17941 0, NULL) == -1)
17942 if (eh == -1) {
17943 // handle error in the usual way
17944 }
17945 The callback can then direct messages to the appropriate place. In
17947 this example, messages are directed to syslog:
17948 static void
17950 message_callback (
17951 guestfs_h *g,
17952 void *opaque,
17953 uint64_t event,
17954 int event_handle,
17955 int flags,
17956 const char *buf, size_t buf_len,
17957 const uint64_t *array, size_t array_len)
17958 {
17959 const int priority = LOG_USER|LOG_INFO;
17960 if (buf_len > 0)
17961 syslog (priority, "event 0x%lx: %s", event, buf);
17962 }
17963 LIBVIRT AUTHENTICATION
17965 Some libguestfs API calls can open libvirt connections. Currently the
17966 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
17967 backend has been selected. Libvirt connections may require
17968 authentication, for example if they need to access a remote server or
17969 to access root services from non-root. Libvirt authentication happens
17970 via a callback mechanism, see
17971 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
17972 You may provide libvirt authentication data by registering a callback
17974 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
17975 If no such event is registered, then libguestfs uses a libvirt function
17977 that provides command-line prompts ("virConnectAuthPtrDefault"). This
17978 is only suitable for command-line libguestfs programs.
17979 To provide authentication, first call
17981 "guestfs_set_libvirt_supported_credentials" with the list of
17982 credentials your program knows how to provide. Second, register a
17983 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
17984 will be called when libvirt is requesting authentication information.
17985 In the event handler, call "guestfs_get_libvirt_requested_credentials"
17987 to get a list of the credentials that libvirt is asking for. You then
17988 need to ask (eg. the user) for each credential, and call
17989 "guestfs_set_libvirt_requested_credential" with the answer. Note that
17990 for each credential, additional information may be available via the
17991 calls "guestfs_get_libvirt_requested_credential_prompt",
17992 "guestfs_get_libvirt_requested_credential_challenge" or
17993 "guestfs_get_libvirt_requested_credential_defresult".
17994 The example program below should make this clearer.
17996 There is also a more substantial working example program supplied with
17998 the libguestfs sources, called libvirt-auth.c.
17999 main ()
18001 {
18002 guestfs_h *g;
18003 char *creds[] = { "authname", "passphrase", NULL };
18004 int r, eh;
18005 g = guestfs_create ();
18007 if (!g) exit (EXIT_FAILURE);
18008 /* Tell libvirt what credentials the program supports. */
18010 r = guestfs_set_libvirt_supported_credentials (g, creds);
18011 if (r == -1)
18012 exit (EXIT_FAILURE);
18013 /* Set up the event handler. */
18015 eh = guestfs_set_event_callback (
18016 g, do_auth,
18017 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
18018 if (eh == -1)
18019 exit (EXIT_FAILURE);
18020 /* An example of a call that may ask for credentials. */
18022 r = guestfs_add_domain (
18023 g, "dom",
18024 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
18025 -1);
18026 if (r == -1)
18027 exit (EXIT_FAILURE);
18028 exit (EXIT_SUCCESS);
18030 }
18031 static void
18033 do_auth (guestfs_h *g,
18034 void *opaque,
18035 uint64_t event,
18036 int event_handle,
18037 int flags,
18038 const char *buf, size_t buf_len,
18039 const uint64_t *array, size_t array_len)
18040 {
18041 char **creds;
18042 size_t i;
18043 char *prompt;
18044 char *reply;
18045 size_t replylen;
18046 int r;
18047 // buf will be the libvirt URI. buf_len may be ignored.
18049 printf ("Authentication required for libvirt conn '%s'\n",
18050 buf);
18051 // Ask libguestfs what credentials libvirt is demanding.
18053 creds = guestfs_get_libvirt_requested_credentials (g);
18054 if (creds == NULL)
18055 exit (EXIT_FAILURE);
18056 // Now ask the user for answers.
18058 for (i = 0; creds[i] != NULL; ++i)
18059 {
18060 if (strcmp (creds[i], "authname") == 0 ||
18061 strcmp (creds[i], "passphrase") == 0)
18062 {
18063 prompt =
18064 guestfs_get_libvirt_requested_credential_prompt (g, i);
18065 if (prompt && strcmp (prompt, "") != 0)
18066 printf ("%s: ", prompt);
18067 free (prompt);
18068 // Some code here to ask for the credential.
18070 // ...
18071 // Put the reply in 'reply', length 'replylen' (bytes).
18072 r = guestfs_set_libvirt_requested_credential (g, i,
18074 reply, replylen);
18075 if (r == -1)
18076 exit (EXIT_FAILURE);
18077 }
18078 free (creds[i]);
18080 }
18081 free (creds);
18083 }
18084
18086 Some operations can be cancelled by the caller while they are in
18087 progress. Currently only operations that involve uploading or
18088 downloading data can be cancelled (technically: operations that have
18089 "FileIn" or "FileOut" parameters in the generator).
18090 To cancel the transfer, call "guestfs_user_cancel". For more
18092 information, read the description of "guestfs_user_cancel".
18093
18095 You can attach named pieces of private data to the libguestfs handle,
18096 fetch them by name, and walk over them, for the lifetime of the handle.
18097 This is called the private data area and is only available from the C
18098 API.
18099 To attach a named piece of data, use the following call:
18101 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18103 "key" is the name to associate with this data, and "data" is an
18105 arbitrary pointer (which can be "NULL"). Any previous item with the
18106 same key is overwritten.
18107 You can use any "key" string you want, but avoid keys beginning with an
18109 underscore character (libguestfs uses those for its own internal
18110 purposes, such as implementing language bindings). It is recommended
18111 that you prefix the key with some unique string to avoid collisions
18112 with other users.
18113 To retrieve the pointer, use:
18115 void *guestfs_get_private (guestfs_h *g, const char *key);
18117 This function returns "NULL" if either no data is found associated with
18119 "key", or if the user previously set the "key"’s "data" pointer to
18120 "NULL".
18121 Libguestfs does not try to look at or interpret the "data" pointer in
18123 any way. As far as libguestfs is concerned, it need not be a valid
18124 pointer at all. In particular, libguestfs does not try to free the
18125 data when the handle is closed. If the data must be freed, then the
18126 caller must either free it before calling "guestfs_close" or must set
18127 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18128 To walk over all entries, use these two functions:
18130 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18132 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18134 "guestfs_first_private" returns the first key, pointer pair ("first"
18136 does not have any particular meaning -- keys are not returned in any
18137 defined order). A pointer to the key is returned in *key_rtn and the
18138 corresponding data pointer is returned from the function. "NULL" is
18139 returned if there are no keys stored in the handle.
18140 "guestfs_next_private" returns the next key, pointer pair. The return
18142 value of this function is "NULL" if there are no further entries to
18143 return.
18144 Notes about walking over entries:
18146 • You must not call "guestfs_set_private" while walking over the
18148 entries.
18149 • The handle maintains an internal iterator which is reset when you
18151 call "guestfs_first_private". This internal iterator is
18152 invalidated when you call "guestfs_set_private".
18153 • If you have set the data pointer associated with a key to "NULL",
18155 ie:
18156 guestfs_set_private (g, key, NULL);
18158 then that "key" is not returned when walking.
18160 • *key_rtn is only valid until the next call to
18162 "guestfs_first_private", "guestfs_next_private" or
18163 "guestfs_set_private".
18164 The following example code shows how to print all keys and data
18166 pointers that are associated with the handle "g":
18167 const char *key;
18169 void *data = guestfs_first_private (g, &key);
18170 while (data != NULL)
18171 {
18172 printf ("key = %s, data = %p\n", key, data);
18173 data = guestfs_next_private (g, &key);
18174 }
18175 More commonly you are only interested in keys that begin with an
18177 application-specific prefix "foo_". Modify the loop like so:
18178 const char *key;
18180 void *data = guestfs_first_private (g, &key);
18181 while (data != NULL)
18182 {
18183 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18184 printf ("key = %s, data = %p\n", key, data);
18185 data = guestfs_next_private (g, &key);
18186 }
18187 If you need to modify keys while walking, then you have to jump back to
18189 the beginning of the loop. For example, to delete all keys prefixed
18190 with "foo_":
18191 const char *key;
18193 void *data;
18194 again:
18195 data = guestfs_first_private (g, &key);
18196 while (data != NULL)
18197 {
18198 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18199 {
18200 guestfs_set_private (g, key, NULL);
18201 /* note that 'key' pointer is now invalid, and so is
18202 the internal iterator */
18203 goto again;
18204 }
18205 data = guestfs_next_private (g, &key);
18206 }
18207 Note that the above loop is guaranteed to terminate because the keys
18209 are being deleted, but other manipulations of keys within the loop
18210 might not terminate unless you also maintain an indication of which
18211 keys have been visited.
18212
18214 The libguestfs C library can be probed using systemtap or DTrace. This
18215 is true of any library, not just libguestfs. However libguestfs also
18216 contains static markers to help in probing internal operations.
18217 You can list all the static markers by doing:
18219 stap -l 'process("/usr/lib*/libguestfs.so.0")
18221 .provider("guestfs").mark("*")'
18222 Note: These static markers are not part of the stable API and may
18224 change in future versions.
18225 SYSTEMTAP SCRIPT EXAMPLE
18227 This script contains examples of displaying both the static markers and
18228 some ordinary C entry points:
18229 global last;
18231 function display_time () {
18233 now = gettimeofday_us ();
18234 delta = 0;
18235 if (last > 0)
18236 delta = now - last;
18237 last = now;
18238 printf ("%d (+%d):", now, delta);
18240 }
18241 probe begin {
18243 last = 0;
18244 printf ("ready\n");
18245 }
18246 /* Display all calls to static markers. */
18248 probe process("/usr/lib*/libguestfs.so.0")
18249 .provider("guestfs").mark("*") ? {
18250 display_time();
18251 printf ("\t%s %s\n", $$name, $$parms);
18252 }
18253 /* Display all calls to guestfs_mkfs* functions. */
18255 probe process("/usr/lib*/libguestfs.so.0")
18256 .function("guestfs_mkfs*") ? {
18257 display_time();
18258 printf ("\t%s %s\n", probefunc(), $$parms);
18259 }
18260 The script above can be saved to test.stap and run using the stap(1)
18262 program. Note that you either have to be root, or you have to add
18263 yourself to several special stap groups. Consult the systemtap
18264 documentation for more information.
18265 # stap /tmp/test.stap
18267 ready
18268 In another terminal, run a guestfish command such as this:
18270 guestfish -N fs
18272 In the first terminal, stap trace output similar to this is shown:
18274 1318248056692655 (+0): launch_start
18276 1318248056692850 (+195): launch_build_appliance_start
18277 1318248056818285 (+125435): launch_build_appliance_end
18278 1318248056838059 (+19774): launch_run_qemu
18279 1318248061071167 (+4233108): launch_end
18280 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
18281
18283 Since April 2010, libguestfs has started to make separate development
18284 and stable releases, along with corresponding branches in our git
18285 repository. These separate releases can be identified by version
18286 number:
18287 even numbers for stable: 1.2.x, 1.4.x, ...
18289 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18290 |
18291 v
18292 1 . 3 . 5
18293 ^ ^
18294 | |
18295 | `-------- sub-version
18296 |
18297 `------ always '1' because we don't change the ABI
18298 Thus "1.3.5" is the 5th update to the development branch "1.3".
18300 As time passes we cherry pick fixes from the development branch and
18302 backport those into the stable branch, the effect being that the stable
18303 branch should get more stable and less buggy over time. So the stable
18304 releases are ideal for people who don't need new features but would
18305 just like the software to work.
18306 Our criteria for backporting changes are:
18308 • Documentation changes which don’t affect any code are backported
18310 unless the documentation refers to a future feature which is not in
18311 stable.
18312 • Bug fixes which are not controversial, fix obvious problems, and
18314 have been well tested are backported.
18315 • Simple rearrangements of code which shouldn't affect how it works
18317 get backported. This is so that the code in the two branches
18318 doesn't get too far out of step, allowing us to backport future
18319 fixes more easily.
18320 • We don’t backport new features, new APIs, new tools etc, except in
18322 one exceptional case: the new feature is required in order to
18323 implement an important bug fix.
18324 A new stable branch starts when we think the new features in
18326 development are substantial and compelling enough over the current
18327 stable branch to warrant it. When that happens we create new stable
18328 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18329 oh release won't necessarily be so stable at this point, but by
18330 backporting fixes from development, that branch will stabilize over
18331 time.
18332
18334 PROTOCOL LIMITS
18335 Internally libguestfs uses a message-based protocol to pass API calls
18336 and their responses to and from a small "appliance" (see
18337 guestfs-internals(1) for plenty more detail about this). The maximum
18338 message size used by the protocol is slightly less than 4 MB. For some
18339 API calls you may need to be aware of this limit. The API calls which
18340 may be affected are individually documented, with a link back to this
18341 section of the documentation.
18342 In libguestfs < 1.19.32, several calls had to encode either their
18344 entire argument list or their entire return value (or sometimes both)
18345 in a single protocol message, and this gave them an arbitrary
18346 limitation on how much data they could handle. For example,
18347 "guestfs_cat" could only download a file if it was less than around 4
18348 MB in size. In later versions of libguestfs, some of these limits have
18349 been removed. The APIs which were previously limited but are now
18350 unlimited (except perhaps by available memory) are listed below. To
18351 find out if a specific API is subject to protocol limits, check for the
18352 warning in the API documentation which links to this section, and
18353 remember to check the version of the documentation that matches the
18354 version of libguestfs you are using.
18355 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18357 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18358 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18359 "guestfs_ls".
18360 See also "UPLOADING" and "DOWNLOADING" for further information about
18362 copying large amounts of data into or out of a filesystem.
18363 MAXIMUM NUMBER OF DISKS
18365 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18366 may be added by calling "guestfs_max_disks". In earlier versions of
18367 libguestfs (ie. where this call is not available) you should assume the
18368 maximum is 25.
18369 The rest of this section covers implementation details, which could
18371 change in future.
18372 When using virtio-scsi disks (the default if available in qemu) the
18374 current limit is 255 disks. When using virtio-blk (the old default)
18375 the limit is around 27 disks, but may vary according to implementation
18376 details and whether the network is enabled.
18377 Virtio-scsi as used by libguestfs is configured to use one target per
18379 disk, and 256 targets are available.
18380 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18382 31 slots, but some of these are used for other purposes.
18383 One virtual disk is used by libguestfs internally.
18385 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18387 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18388 the limit was 25. This has been fixed in more recent versions.
18389 MAXIMUM NUMBER OF PARTITIONS PER DISK
18391 Virtio limits the maximum number of partitions per disk to 15.
18392 This is because it reserves 4 bits for the minor device number (thus
18394 /dev/vda, and /dev/vda1 through /dev/vda15).
18395 If you attach a disk with more than 15 partitions, the extra partitions
18397 are ignored by libguestfs.
18398 MAXIMUM SIZE OF A DISK
18400 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18401 We have tested block devices up to 1 exabyte (2**60 or
18403 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18404 host filesystem.
18405 Although libguestfs probably does not impose any limit, the underlying
18407 host storage will. If you store disk images on a host ext4 filesystem,
18408 then the maximum size will be limited by the maximum ext4 file size
18409 (currently 16 TB). If you store disk images as host logical volumes
18410 then you are limited by the maximum size of an LV.
18411 For the hugest disk image files, we recommend using XFS on the host for
18413 storage.
18414 MAXIMUM SIZE OF A PARTITION
18416 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18417 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18418 address a partition located beyond 2 TB on the disk.
18419 It is recommended that you use GPT partitions on disks which are larger
18421 than this size. GPT uses 64 bit sector numbers and so can address
18422 partitions which are theoretically larger than the largest disk we
18423 could support.
18424 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18426 This depends on the filesystem type. libguestfs itself does not impose
18427 any known limit. Consult Wikipedia or the filesystem documentation to
18428 find out what these limits are.
18429 MAXIMUM UPLOAD AND DOWNLOAD
18431 The API functions "guestfs_upload", "guestfs_download",
18432 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18433 uploads and downloads.
18434 INSPECTION LIMITS
18436 The inspection code has several arbitrary limits on things like the
18437 size of Windows Registry hive it will read, and the length of product
18438 name. These are intended to stop a malicious guest from consuming
18439 arbitrary amounts of memory and disk space on the host, and should not
18440 be reached in practice. See the source code for more information.
18441
18443 Some of the tools support a --machine-readable option, which is
18444 generally used to make the output more machine friendly, for easier
18445 parsing for example. By default, this output goes to stdout.
18446 When using the --machine-readable option, the progress, information,
18448 warning, and error messages are also printed in JSON format for easier
18449 log tracking. Thus, it is highly recommended to redirect the machine-
18450 readable output to a different stream. The format of these JSON
18451 messages is like the following (actually printed within a single line,
18452 below it is indented for readability):
18453 {
18455 "message": "Finishing off",
18456 "timestamp": "2019-03-22T14:46:49.067294446+01:00",
18457 "type": "message"
18458 }
18459 "type" can be: "message" for progress messages, "info" for information
18461 messages, "warning" for warning messages, and "error" for error
18462 message. "timestamp" is the RFC 3339 timestamp of the message.
18463 In addition to that, a subset of these tools support an extra string
18465 passed to the --machine-readable option: this string specifies where
18466 the machine-readable output will go.
18467 The possible values are:
18469 fd:fd
18471 The output goes to the specified fd, which is a file descriptor
18472 already opened for writing.
18473 file:filename
18475 The output goes to the specified filename.
18476 stream:stdout
18478 The output goes to stdout. This is basically the same as the
18479 default behaviour of --machine-readable with no parameter, although
18480 stdout as output is specified explicitly.
18481 stream:stderr
18483 The output goes to stderr.
18484
18486 LIBGUESTFS_APPEND
18487 Pass additional options to the guest kernel.
18488 LIBGUESTFS_ATTACH_METHOD
18490 This is the old way to set "LIBGUESTFS_BACKEND".
18491 LIBGUESTFS_BACKEND
18493 Choose the default way to create the appliance. See
18494 "guestfs_set_backend" and "BACKEND".
18495 LIBGUESTFS_BACKEND_SETTINGS
18497 A colon-separated list of backend-specific settings. See
18498 "BACKEND", "BACKEND SETTINGS".
18499 LIBGUESTFS_CACHEDIR
18501 The location where libguestfs will cache its appliance, when using
18502 a supermin appliance. The appliance is cached and shared between
18503 all handles which have the same effective user ID.
18504 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18506 "TMPDIR" is not set, then /var/tmp is used.
18507 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18509 LIBGUESTFS_DEBUG
18511 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18512 same effect as calling "guestfs_set_verbose (g, 1)".
18513 LIBGUESTFS_HV
18515 Set the default hypervisor (usually qemu) binary that libguestfs
18516 uses. If not set, then the qemu which was found at compile time by
18517 the configure script is used.
18518 See also "QEMU WRAPPERS" above.
18520 LIBGUESTFS_MEMSIZE
18522 Set the memory allocated to the qemu process, in megabytes. For
18523 example:
18524 LIBGUESTFS_MEMSIZE=700
18526 LIBGUESTFS_PATH
18528 Set the path that libguestfs uses to search for a supermin
18529 appliance. See the discussion of paths in section "PATH" above.
18530 LIBGUESTFS_QEMU
18532 This is the old way to set "LIBGUESTFS_HV".
18533 LIBGUESTFS_TMPDIR
18535 The location where libguestfs will store temporary files used by
18536 each handle.
18537 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18539 "TMPDIR" is not set, then /tmp is used.
18540 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18542 LIBGUESTFS_TRACE
18544 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18545 same effect as calling "guestfs_set_trace (g, 1)".
18546 PATH
18548 Libguestfs may run some external programs, and relies on $PATH
18549 being set to a reasonable value. If using the libvirt backend,
18550 libvirt will not work at all unless $PATH contains the path of
18551 qemu/KVM. Note that PHP by default removes $PATH from the
18552 environment which tends to break everything.
18553 SUPERMIN_KERNEL
18555 SUPERMIN_KERNEL_VERSION
18556 SUPERMIN_MODULES
18557 These three environment variables allow the kernel that libguestfs
18558 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18559 set, then the most recent host kernel is chosen. For more
18560 information about kernel selection, see supermin(1).
18561 TMPDIR
18563 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18564 XDG_RUNTIME_DIR
18566 This directory represents a user-specific directory for storing
18567 non-essential runtime files.
18568 If it is set, then is used to store temporary sockets. Otherwise,
18570 /tmp is used.
18571 See also "get-sockdir",
18573 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18574
18576 Examples written in C: guestfs-examples(3).
18577 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18579 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18580 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18581 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18583 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18584 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18585 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18586 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18587 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18588 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18589 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18590 virt-win-reg(1).
18591 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18593 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18594 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18595 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18596 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18598 sd-journal(3).
18599 Website: http://libguestfs.org/
18601 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18603 disktype(1).
18604
18606 Richard W.M. Jones ("rjones at redhat dot com")
18607
18609 Copyright (C) 2009-2020 Red Hat Inc.
18610
18612 This library is free software; you can redistribute it and/or modify it
18613 under the terms of the GNU Lesser General Public License as published
18614 by the Free Software Foundation; either version 2 of the License, or
18615 (at your option) any later version.
18616 This library is distributed in the hope that it will be useful, but
18618 WITHOUT ANY WARRANTY; without even the implied warranty of
18619 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18620 Lesser General Public License for more details.
18621 You should have received a copy of the GNU Lesser General Public
18623 License along with this library; if not, write to the Free Software
18624 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18625 02110-1301 USA
18626
18628 To get a list of bugs against libguestfs, use this link:
18629 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18630 To report a new bug against libguestfs, use this link:
18632 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18633 When reporting a bug, please supply:
18635 • The version of libguestfs.
18637 • Where you got libguestfs (eg. which Linux distro, compiled from
18639 source, etc)
18640 • Describe the bug accurately and give a way to reproduce it.
18642 • Run libguestfs-test-tool(1) and paste the complete, unedited output
18644 into the bug report.
18645libguestfs-1.48.3 2022-05-26 guestfs(3)