1guestfs(3) Virtualization Support guestfs(3)
2
6 guestfs - Library for accessing and modifying virtual machine images
7
9 #include <guestfs.h>
10 guestfs_h *g = guestfs_create ();
12 guestfs_add_drive (g, "guest.img");
13 guestfs_launch (g);
14 guestfs_mount (g, "/dev/sda1", "/");
15 guestfs_touch (g, "/hello");
16 guestfs_umount (g, "/");
17 guestfs_shutdown (g);
18 guestfs_close (g);
19 cc prog.c -o prog -lguestfs
21 or:
22 cc prog.c -o prog `pkg-config libguestfs --cflags --libs`
23
25 Libguestfs is a library for accessing and modifying disk images and
26 virtual machines.
27 This manual page documents the C API.
29 If you are looking for an introduction to libguestfs, see the web site:
31 http://libguestfs.org/
32 Each virt tool has its own man page (for a full list, go to "SEE ALSO"
34 at the end of this file).
35 Other libguestfs manual pages:
37 guestfs-faq(1)
39 Frequently Asked Questions (FAQ).
40 guestfs-examples(3)
42 Examples of using the API from C. For examples in other languages,
43 see "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES" below.
44 guestfs-recipes(1)
46 Tips and recipes.
47 guestfs-performance(1)
49 Performance tips and solutions.
50 libguestfs-test-tool(1)
52 guestfs-testing(1)
53 Help testing libguestfs.
54 guestfs-building(1)
56 How to build libguestfs from source.
57 guestfs-hacking(1)
59 Contribute code to libguestfs.
60 guestfs-internals(1)
62 How libguestfs works.
63 guestfs-security(1)
65 Security information, including CVEs affecting libguestfs.
66
68 This section provides a gentler overview of the libguestfs API. We
69 also try to group API calls together, where that may not be obvious
70 from reading about the individual calls in the main section of this
71 manual.
72 HANDLES
74 Before you can use libguestfs calls, you have to create a handle. Then
75 you must add at least one disk image to the handle, followed by
76 launching the handle, then performing whatever operations you want, and
77 finally closing the handle. By convention we use the single letter "g"
78 for the name of the handle variable, although of course you can use any
79 name you want.
80 The general structure of all libguestfs-using programs looks like this:
82 guestfs_h *g = guestfs_create ();
84 /* Call guestfs_add_drive additional times if there are
86 * multiple disk images.
87 */
88 guestfs_add_drive (g, "guest.img");
89 /* Most manipulation calls won't work until you've launched
91 * the handle 'g'. You have to do this _after_ adding drives
92 * and _before_ other commands.
93 */
94 guestfs_launch (g);
95 /* Either: examine what partitions, LVs etc are available: */
97 char **partitions = guestfs_list_partitions (g);
98 char **logvols = guestfs_lvs (g);
99 /* Or: ask libguestfs to find filesystems for you: */
101 char **filesystems = guestfs_list_filesystems (g);
102 /* Or: use inspection (see INSPECTION section below). */
104 /* To access a filesystem in the image, you must mount it. */
106 guestfs_mount (g, "/dev/sda1", "/");
107 /* Now you can perform filesystem actions on the guest
109 * disk image.
110 */
111 guestfs_touch (g, "/hello");
112 /* Synchronize the disk. This is the opposite of guestfs_launch. */
114 guestfs_shutdown (g);
115 /* Close and free the handle 'g'. */
117 guestfs_close (g);
118 The code above doesn't include any error checking. In real code you
120 should check return values carefully for errors. In general all
121 functions that return integers return "-1" on error, and all functions
122 that return pointers return "NULL" on error. See section "ERROR
123 HANDLING" below for how to handle errors, and consult the documentation
124 for each function call below to see precisely how they return error
125 indications.
126 The code above does not free(3) the strings and arrays returned from
128 functions. Consult the documentation for each function to find out how
129 to free the return value.
130 See guestfs-examples(3) for fully worked examples.
132 DISK IMAGES
134 The image filename ("guest.img" in the example above) could be a disk
135 image from a virtual machine, a dd(1) copy of a physical hard disk, an
136 actual block device, or simply an empty file of zeroes that you have
137 created through posix_fallocate(3). Libguestfs lets you do useful
138 things to all of these.
139 The call you should use in modern code for adding drives is
141 "guestfs_add_drive_opts". To add a disk image, allowing writes, and
142 specifying that the format is raw, do:
143 guestfs_add_drive_opts (g, filename,
145 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
146 -1);
147 You can add a disk read-only using:
149 guestfs_add_drive_opts (g, filename,
151 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
152 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
153 -1);
154 or by calling the older function "guestfs_add_drive_ro". If you use
156 the readonly flag, libguestfs won't modify the file. (See also "DISK
157 IMAGE FORMATS" below).
158 Be extremely cautious if the disk image is in use, eg. if it is being
160 used by a virtual machine. Adding it read-write will almost certainly
161 cause disk corruption, but adding it read-only is safe.
162 You should usually add at least one disk image, and you may add
164 multiple disk images. If adding multiple disk images, they usually
165 have to be "related", ie. from the same guest. In the API, the disk
166 images are usually referred to as /dev/sda (for the first one you
167 added), /dev/sdb (for the second one you added), etc.
168 Once "guestfs_launch" has been called you cannot add any more images.
170 You can call "guestfs_list_devices" to get a list of the device names,
171 in the order that you added them. See also "BLOCK DEVICE NAMING"
172 below.
173 There are slightly different rules when hotplugging disks (in
175 libguestfs ≥ 1.20). See "HOTPLUGGING" below.
176 MOUNTING
178 Before you can read or write files, create directories and so on in a
179 disk image that contains filesystems, you have to mount those
180 filesystems using "guestfs_mount" or "guestfs_mount_ro". If you
181 already know that a disk image contains (for example) one partition
182 with a filesystem on that partition, then you can mount it directly:
183 guestfs_mount (g, "/dev/sda1", "/");
185 where /dev/sda1 means literally the first partition (1) of the first
187 disk image that we added (/dev/sda). If the disk contains Linux LVM2
188 logical volumes you could refer to those instead (eg. /dev/VG/LV).
189 Note that these are libguestfs virtual devices, and are nothing to do
190 with host devices.
191 If you are given a disk image and you don’t know what it contains then
193 you have to find out. Libguestfs can do that too: use
194 "guestfs_list_partitions" and "guestfs_lvs" to list possible partitions
195 and LVs, and either try mounting each to see what is mountable, or else
196 examine them with "guestfs_vfs_type" or "guestfs_file". To list just
197 filesystems, use "guestfs_list_filesystems".
198 Libguestfs also has a set of APIs for inspection of unknown disk images
200 (see "INSPECTION" below). You might also want to look at higher level
201 programs built on top of libguestfs, in particular virt-inspector(1).
202 To mount a filesystem read-only, use "guestfs_mount_ro". There are
204 several other variations of the "guestfs_mount_*" call.
205 FILESYSTEM ACCESS AND MODIFICATION
207 The majority of the libguestfs API consists of fairly low-level calls
208 for accessing and modifying the files, directories, symlinks etc on
209 mounted filesystems. There are over a hundred such calls which you can
210 find listed in detail below in this man page, and we don't even pretend
211 to cover them all in this overview.
212 Specify filenames as full paths, starting with "/" and including the
214 mount point.
215 For example, if you mounted a filesystem at "/" and you want to read
217 the file called "etc/passwd" then you could do:
218 char *data = guestfs_cat (g, "/etc/passwd");
220 This would return "data" as a newly allocated buffer containing the
222 full content of that file (with some conditions: see also "DOWNLOADING"
223 below), or "NULL" if there was an error.
224 As another example, to create a top-level directory on that filesystem
226 called "var" you would do:
227 guestfs_mkdir (g, "/var");
229 To create a symlink you could do:
231 guestfs_ln_s (g, "/etc/init.d/portmap",
233 "/etc/rc3.d/S30portmap");
234 Libguestfs will reject attempts to use relative paths and there is no
236 concept of a current working directory.
237 Libguestfs can return errors in many situations: for example if the
239 filesystem isn't writable, or if a file or directory that you requested
240 doesn't exist. If you are using the C API (documented here) you have
241 to check for those error conditions after each call. (Other language
242 bindings turn these errors into exceptions).
243 File writes are affected by the per-handle umask, set by calling
245 "guestfs_umask" and defaulting to 022. See "UMASK".
246 Since libguestfs 1.18, it is possible to mount the libguestfs
248 filesystem on a local directory, subject to some restrictions. See
249 "MOUNT LOCAL" below.
250 PARTITIONING
252 Libguestfs contains API calls to read, create and modify partition
253 tables on disk images.
254 In the common case where you want to create a single partition covering
256 the whole disk, you should use the "guestfs_part_disk" call:
257 const char *parttype = "mbr";
259 if (disk_is_larger_than_2TB)
260 parttype = "gpt";
261 guestfs_part_disk (g, "/dev/sda", parttype);
262 Obviously this effectively wipes anything that was on that disk image
264 before.
265 LVM2
267 Libguestfs provides access to a large part of the LVM2 API, such as
268 "guestfs_lvcreate" and "guestfs_vgremove". It won't make much sense
269 unless you familiarize yourself with the concepts of physical volumes,
270 volume groups and logical volumes.
271 This author strongly recommends reading the LVM HOWTO, online at
273 http://tldp.org/HOWTO/LVM-HOWTO/.
274 DOWNLOADING
276 Use "guestfs_cat" to download small, text only files. This call cannot
277 handle files containing any ASCII NUL ("\0") characters. However the
278 API is very simple to use.
279 "guestfs_read_file" can be used to read files which contain arbitrary 8
281 bit data, since it returns a (pointer, size) pair.
282 "guestfs_download" can be used to download any file, with no limits on
284 content or size.
285 To download multiple files, see "guestfs_tar_out" and
287 "guestfs_tgz_out".
288 UPLOADING
290 To write a small file with fixed content, use "guestfs_write". To
291 create a file of all zeroes, use "guestfs_truncate_size" (sparse) or
292 "guestfs_fallocate64" (with all disk blocks allocated). There are a
293 variety of other functions for creating test files, for example
294 "guestfs_fill" and "guestfs_fill_pattern".
295 To upload a single file, use "guestfs_upload". This call has no limits
297 on file content or size.
298 To upload multiple files, see "guestfs_tar_in" and "guestfs_tgz_in".
300 However the fastest way to upload large numbers of arbitrary files is
302 to turn them into a squashfs or CD ISO (see mksquashfs(8) and
303 mkisofs(8)), then attach this using "guestfs_add_drive_ro". If you add
304 the drive in a predictable way (eg. adding it last after all other
305 drives) then you can get the device name from "guestfs_list_devices"
306 and mount it directly using "guestfs_mount_ro". Note that squashfs
307 images are sometimes non-portable between kernel versions, and they
308 don't support labels or UUIDs. If you want to pre-build an image or
309 you need to mount it using a label or UUID, use an ISO image instead.
310 COPYING
312 There are various different commands for copying between files and
313 devices and in and out of the guest filesystem. These are summarised
314 in the table below.
315 file to file
317 Use "guestfs_cp" to copy a single file, or "guestfs_cp_a" to copy
318 directories recursively.
319 To copy part of a file (offset and size) use
321 "guestfs_copy_file_to_file".
322 file to device
324 device to file
325 device to device
326 Use "guestfs_copy_file_to_device", "guestfs_copy_device_to_file",
327 or "guestfs_copy_device_to_device".
328 Example: duplicate the contents of an LV:
330 guestfs_copy_device_to_device (g,
332 "/dev/VG/Original", "/dev/VG/Copy",
333 /* -1 marks the end of the list of optional parameters */
334 -1);
335 The destination (/dev/VG/Copy) must be at least as large as the
337 source (/dev/VG/Original). To copy less than the whole source
338 device, use the optional "size" parameter:
339 guestfs_copy_device_to_device (g,
341 "/dev/VG/Original", "/dev/VG/Copy",
342 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
343 -1);
344 file on the host to file or device
346 Use "guestfs_upload". See "UPLOADING" above.
347 file or device to file on the host
349 Use "guestfs_download". See "DOWNLOADING" above.
350 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
352 Calls like "guestfs_upload", "guestfs_download", "guestfs_tar_in",
353 "guestfs_tar_out" etc appear to only take filenames as arguments, so it
354 appears you can only upload and download to files. However many
355 Un*x-like hosts let you use the special device files /dev/stdin,
356 /dev/stdout, /dev/stderr and /dev/fd/N to read and write from stdin,
357 stdout, stderr, and arbitrary file descriptor N.
358 For example, virt-cat(1) writes its output to stdout by doing:
360 guestfs_download (g, filename, "/dev/stdout");
362 and you can write tar output to a file descriptor "fd" by doing:
364 char devfd[64];
366 snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
367 guestfs_tar_out (g, "/", devfd);
368 LISTING FILES
370 "guestfs_ll" is just designed for humans to read (mainly when using the
371 guestfish(1)-equivalent command "ll").
372 "guestfs_ls" is a quick way to get a list of files in a directory from
374 programs, as a flat list of strings.
375 "guestfs_readdir" is a programmatic way to get a list of files in a
377 directory, plus additional information about each one. It is more
378 equivalent to using the readdir(3) call on a local filesystem.
379 "guestfs_find" and "guestfs_find0" can be used to recursively list
381 files.
382 RUNNING COMMANDS
384 Although libguestfs is primarily an API for manipulating files inside
385 guest images, we also provide some limited facilities for running
386 commands inside guests.
387 There are many limitations to this:
389 · The kernel version that the command runs under will be different
391 from what it expects.
392 · If the command needs to communicate with daemons, then most likely
394 they won't be running.
395 · The command will be running in limited memory.
397 · The network may not be available unless you enable it (see
399 "guestfs_set_network").
400 · Only supports Linux guests (not Windows, BSD, etc).
402 · Architecture limitations (eg. won’t work for a PPC guest on an X86
404 host).
405 · For SELinux guests, you may need to relabel the guest after
407 creating new files. See "SELINUX" below.
408 · Security: It is not safe to run commands from untrusted, possibly
410 malicious guests. These commands may attempt to exploit your
411 program by sending unexpected output. They could also try to
412 exploit the Linux kernel or qemu provided by the libguestfs
413 appliance. They could use the network provided by the libguestfs
414 appliance to bypass ordinary network partitions and firewalls.
415 They could use the elevated privileges or different SELinux context
416 of your program to their advantage.
417 A secure alternative is to use libguestfs to install a "firstboot"
419 script (a script which runs when the guest next boots normally),
420 and to have this script run the commands you want in the normal
421 context of the running guest, network security and so on. For
422 information about other security issues, see guestfs-security(1).
423 The two main API calls to run commands are "guestfs_command" and
425 "guestfs_sh" (there are also variations).
426 The difference is that "guestfs_sh" runs commands using the shell, so
428 any shell globs, redirections, etc will work.
429 CONFIGURATION FILES
431 To read and write configuration files in Linux guest filesystems, we
432 strongly recommend using Augeas. For example, Augeas understands how
433 to read and write, say, a Linux shadow password file or X.org
434 configuration file, and so avoids you having to write that code.
435 The main Augeas calls are bound through the "guestfs_aug_*" APIs. We
437 don't document Augeas itself here because there is excellent
438 documentation on the http://augeas.net/ website.
439 If you don’t want to use Augeas (you fool!) then try calling
441 "guestfs_read_lines" to get the file as a list of lines which you can
442 iterate over.
443 SYSTEMD JOURNAL FILES
445 To read the systemd journal from a Linux guest, use the
446 "guestfs_journal_*" APIs starting with "guestfs_journal_open".
447 Consult the journal documentation here: sd-journal(3),
449 sd_journal_open(3).
450 SELINUX
452 We support SELinux guests. However it is not possible to load the
453 SELinux policy of the guest into the appliance kernel. Therefore the
454 strategy for dealing with SELinux guests is to relabel them after
455 making changes.
456 In libguestfs ≥ 1.34 there is a new API, "guestfs_setfiles", which can
458 be used for this. To properly use this API you have to parse the guest
459 SELinux configuration. See the virt-customize(1) module
460 customize/SELinux_relabel.ml for how to do this.
461 A simpler but slower alternative is to touch /.autorelabel in the
463 guest, which means that the guest will relabel itself at next boot.
464 Libguestfs ≤ 1.32 had APIs "guestfs_set_selinux",
466 "guestfs_get_selinux", "guestfs_setcon" and "guestfs_getcon". These
467 did not work properly, are deprecated, and should not be used in new
468 code.
469 UMASK
471 Certain calls are affected by the current file mode creation mask (the
472 "umask"). In particular ones which create files or directories, such
473 as "guestfs_touch", "guestfs_mknod" or "guestfs_mkdir". This affects
474 either the default mode that the file is created with or modifies the
475 mode that you supply.
476 The default umask is 022, so files are created with modes such as 0644
478 and directories with 0755.
479 There are two ways to avoid being affected by umask. Either set umask
481 to 0 (call "guestfs_umask (g, 0)" early after launching). Or call
482 "guestfs_chmod" after creating each file or directory.
483 For more information about umask, see umask(2).
485 LABELS AND UUIDS
487 Many filesystems, devices and logical volumes support either labels
488 (short strings like "BOOT" which might not be unique) and/or UUIDs
489 (globally unique IDs).
490 For filesystems, use "guestfs_vfs_label" or "guestfs_vfs_uuid" to read
492 the label or UUID. Some filesystems let you call "guestfs_set_label"
493 or "guestfs_set_uuid" to change the label or UUID.
494 You can locate a filesystem by its label or UUID using
496 "guestfs_findfs_label" or "guestfs_findfs_uuid".
497 For LVM2 (which supports only UUIDs), there is a rich set of APIs for
499 fetching UUIDs, fetching UUIDs of the contained objects, and changing
500 UUIDs. See: "guestfs_lvuuid", "guestfs_vguuid", "guestfs_pvuuid",
501 "guestfs_vglvuuids", "guestfs_vgpvuuids", "guestfs_vgchange_uuid",
502 "guestfs_vgchange_uuid_all", "guestfs_pvchange_uuid",
503 "guestfs_pvchange_uuid_all".
504 Note when cloning a filesystem, device or whole guest, it is a good
506 idea to set new randomly generated UUIDs on the copy.
507 ENCRYPTED DISKS
509 Libguestfs allows you to access Linux guests which have been encrypted
510 using whole disk encryption that conforms to the Linux Unified Key
511 Setup (LUKS) standard. This includes nearly all whole disk encryption
512 systems used by modern Linux guests.
513 Use "guestfs_vfs_type" to identify LUKS-encrypted block devices (it
515 returns the string "crypto_LUKS").
516 Then open these devices by calling "guestfs_luks_open". Obviously you
518 will require the passphrase!
519 Opening a LUKS device creates a new device mapper device called
521 /dev/mapper/mapname (where "mapname" is the string you supply to
522 "guestfs_luks_open"). Reads and writes to this mapper device are
523 decrypted from and encrypted to the underlying block device
524 respectively.
525 LVM volume groups on the device can be made visible by calling
527 "guestfs_vgscan" followed by "guestfs_vg_activate_all". The logical
528 volume(s) can now be mounted in the usual way.
529 Use the reverse process to close a LUKS device. Unmount any logical
531 volumes on it, deactivate the volume groups by calling
532 "guestfs_vg_activate (g, 0, ["/dev/VG"])". Then close the mapper
533 device by calling "guestfs_luks_close" on the /dev/mapper/mapname
534 device (not the underlying encrypted block device).
535 MOUNT LOCAL
537 In libguestfs ≥ 1.18, it is possible to mount the libguestfs filesystem
538 on a local directory and access it using ordinary POSIX calls and
539 programs.
540 Availability of this is subject to a number of restrictions: it
542 requires FUSE (the Filesystem in USErspace), and libfuse must also have
543 been available when libguestfs was compiled. FUSE may require that a
544 kernel module is loaded, and it may be necessary to add the current
545 user to a special "fuse" group. See the documentation for your
546 distribution and http://fuse.sf.net for further information.
547 The call to mount the libguestfs filesystem on a local directory is
549 "guestfs_mount_local" (q.v.) followed by "guestfs_mount_local_run".
550 The latter does not return until you unmount the filesystem. The
551 reason is that the call enters the FUSE main loop and processes kernel
552 requests, turning them into libguestfs calls. An alternative design
553 would have been to create a background thread to do this, but
554 libguestfs doesn't require pthreads. This way is also more flexible:
555 for example the user can create another thread for
556 "guestfs_mount_local_run".
557 "guestfs_mount_local" needs a certain amount of time to set up the
559 mountpoint. The mountpoint is not ready to use until the call returns.
560 At this point, accesses to the filesystem will block until the main
561 loop is entered (ie. "guestfs_mount_local_run"). So if you need to
562 start another process to access the filesystem, put the fork between
563 "guestfs_mount_local" and "guestfs_mount_local_run".
564 MOUNT LOCAL COMPATIBILITY
566 Since local mounting was only added in libguestfs 1.18, and may not be
568 available even in these builds, you should consider writing code so
569 that it doesn't depend on this feature, and can fall back to using
570 libguestfs file system calls.
571 If libguestfs was compiled without support for "guestfs_mount_local"
573 then calling it will return an error with errno set to "ENOTSUP" (see
574 "guestfs_last_errno").
575 MOUNT LOCAL PERFORMANCE
577 Libguestfs on top of FUSE performs quite poorly. For best performance
579 do not use it. Use ordinary libguestfs filesystem calls, upload,
580 download etc. instead.
581 HOTPLUGGING
583 In libguestfs ≥ 1.20, you may add drives and remove after calling
584 "guestfs_launch". There are some restrictions, see below. This is
585 called hotplugging.
586 Only a subset of the backends support hotplugging (currently only the
588 libvirt backend has support). It also requires that you use libvirt ≥
589 0.10.3 and qemu ≥ 1.2.
590 To hot-add a disk, simply call "guestfs_add_drive_opts" after
592 "guestfs_launch". It is mandatory to specify the "label" parameter so
593 that the newly added disk has a predictable name. For example:
594 if (guestfs_launch (g) == -1)
596 error ("launch failed");
597 if (guestfs_add_drive_opts (g, filename,
599 GUESTFS_ADD_DRIVE_OPTS_LABEL, "newdisk",
600 -1) == -1)
601 error ("hot-add of disk failed");
602 if (guestfs_part_disk ("/dev/disk/guestfs/newdisk", "mbr") == -1)
604 error ("partitioning of hot-added disk failed");
605 To hot-remove a disk, call "guestfs_remove_drive". You can call this
607 before or after "guestfs_launch". You can only remove disks that were
608 previously added with a label.
609 Backends that support hotplugging do not require that you add ≥ 1 disk
611 before calling launch. When hotplugging is supported you don't need to
612 add any disks.
613 REMOTE STORAGE
615 CEPH
616 Libguestfs can access Ceph (librbd/RBD) disks.
618 To do this, set the optional "protocol" and "server" parameters of
620 "guestfs_add_drive_opts" like this:
621 char **servers = { "ceph1.example.org:3000", /* ... */, NULL };
623 guestfs_add_drive_opts (g, "pool/image",
624 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
625 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "rbd",
626 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
627 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "rbduser",
628 GUESTFS_ADD_DRIVE_OPTS_SECRET, "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
629 -1);
630 "servers" (the "server" parameter) is a list of one or more Ceph
632 servers. The server string is documented in "guestfs_add_drive_opts".
633 The "username" and "secret" parameters are also optional, and if not
634 given, then no authentication will be used.
635 FTP, HTTP AND TFTP
637 Libguestfs can access remote disks over FTP, FTPS, HTTP, HTTPS or TFTP
639 protocols.
640 To do this, set the optional "protocol" and "server" parameters of
642 "guestfs_add_drive_opts" like this:
643 char **servers = { "www.example.org", NULL };
645 guestfs_add_drive_opts (g, "/disk.img",
646 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
647 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "http",
648 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
649 -1);
650 The "protocol" can be one of "ftp", "ftps", "http", "https" or "tftp".
652 "servers" (the "server" parameter) is a list which must have a single
654 element. The single element is a string defining the web, FTP or TFTP
655 server. The format of this string is documented in
656 "guestfs_add_drive_opts".
657 GLUSTER
659 Libguestfs can access Gluster disks.
661 To do this, set the optional "protocol" and "server" parameters of
663 "guestfs_add_drive_opts" like this:
664 char **servers = { "gluster.example.org:24007", NULL };
666 guestfs_add_drive_opts (g, "volname/image",
667 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
668 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "gluster",
669 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
670 -1);
671 "servers" (the "server" parameter) is a list which must have a single
673 element. The single element is a string defining the Gluster server.
674 The format of this string is documented in "guestfs_add_drive_opts".
675 Note that gluster usually requires the client process (ie. libguestfs)
677 to run as root and will give unfathomable errors if it is not (eg. "No
678 data available").
679 ISCSI
681 Libguestfs can access iSCSI disks remotely.
683 To do this, set the optional "protocol" and "server" parameters like
685 this:
686 char **server = { "iscsi.example.org:3000", NULL };
688 guestfs_add_drive_opts (g, "target-iqn-name/lun",
689 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
690 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "iscsi",
691 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
692 -1);
693 The "server" parameter is a list which must have a single element. The
695 single element is a string defining the iSCSI server. The format of
696 this string is documented in "guestfs_add_drive_opts".
697 NETWORK BLOCK DEVICE
699 Libguestfs can access Network Block Device (NBD) disks remotely.
701 To do this, set the optional "protocol" and "server" parameters of
703 "guestfs_add_drive_opts" like this:
704 char **server = { "nbd.example.org:3000", NULL };
706 guestfs_add_drive_opts (g, "" /* export name - see below */,
707 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
708 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
709 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
710 -1);
711 Notes:
713 · "server" is in fact a list of servers. For NBD you must always
715 supply a list with a single element. (Other remote protocols
716 require zero or more than one server, hence the requirement for
717 this parameter to be a list).
718 · The "server" string is documented in "guestfs_add_drive_opts". To
720 connect to a local qemu-nbd instance over a Unix domain socket, use
721 "unix:/path/to/socket".
722 · The "filename" parameter is the NBD export name. Use an empty
724 string to mean the default export. Many NBD servers, including
725 qemu-nbd, do not support export names.
726 · If using qemu-nbd as your server, you should always specify the
728 "-t" option. The reason is that libguestfs may open several
729 connections to the server.
730 · The libvirt backend requires that you set the "format" parameter of
732 "guestfs_add_drive_opts" accurately when you use writable NBD
733 disks.
734 · The libvirt backend has a bug that stops Unix domain socket
736 connections from working:
737 https://bugzilla.redhat.com/show_bug.cgi?id=922888
738 · The direct backend does not support readonly connections because of
740 a bug in qemu: https://bugs.launchpad.net/qemu/+bug/1155677
741 SHEEPDOG
743 Libguestfs can access Sheepdog disks.
745 To do this, set the optional "protocol" and "server" parameters of
747 "guestfs_add_drive_opts" like this:
748 char **servers = { /* optional servers ... */ NULL };
750 guestfs_add_drive_opts (g, "volume",
751 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
752 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "sheepdog",
753 GUESTFS_ADD_DRIVE_OPTS_SERVER, servers,
754 -1);
755 The optional list of "servers" may be zero or more server addresses
757 ("hostname:port"). The format of the server strings is documented in
758 "guestfs_add_drive_opts".
759 SSH
761 Libguestfs can access disks over a Secure Shell (SSH) connection.
763 To do this, set the "protocol" and "server" and (optionally) "username"
765 parameters of "guestfs_add_drive_opts" like this:
766 char **server = { "remote.example.com", NULL };
768 guestfs_add_drive_opts (g, "/path/to/disk.img",
769 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
770 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "ssh",
771 GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
772 GUESTFS_ADD_DRIVE_OPTS_USERNAME, "remoteuser",
773 -1);
774 The format of the server string is documented in
776 "guestfs_add_drive_opts".
777 INSPECTION
779 Libguestfs has APIs for inspecting an unknown disk image to find out if
780 it contains operating systems, an install CD or a live CD.
781 Add all disks belonging to the unknown virtual machine and call
783 "guestfs_launch" in the usual way.
784 Then call "guestfs_inspect_os". This function uses other libguestfs
786 calls and certain heuristics, and returns a list of operating systems
787 that were found. An empty list means none were found. A single
788 element is the root filesystem of the operating system. For dual- or
789 multi-boot guests, multiple roots can be returned, each one
790 corresponding to a separate operating system. (Multi-boot virtual
791 machines are extremely rare in the world of virtualization, but since
792 this scenario can happen, we have built libguestfs to deal with it.)
793 For each root, you can then call various "guestfs_inspect_get_*"
795 functions to get additional details about that operating system. For
796 example, call "guestfs_inspect_get_type" to return the string "windows"
797 or "linux" for Windows and Linux-based operating systems respectively.
798 Un*x-like and Linux-based operating systems usually consist of several
800 filesystems which are mounted at boot time (for example, a separate
801 boot partition mounted on /boot). The inspection rules are able to
802 detect how filesystems correspond to mount points. Call
803 "guestfs_inspect_get_mountpoints" to get this mapping. It might return
804 a hash table like this example:
805 /boot => /dev/sda1
807 / => /dev/vg_guest/lv_root
808 /usr => /dev/vg_guest/lv_usr
809 The caller can then make calls to "guestfs_mount" to mount the
811 filesystems as suggested.
812 Be careful to mount filesystems in the right order (eg. / before /usr).
814 Sorting the keys of the hash by length, shortest first, should work.
815 Inspection currently only works for some common operating systems.
817 Contributors are welcome to send patches for other operating systems
818 that we currently cannot detect.
819 Encrypted disks must be opened before inspection. See "ENCRYPTED
821 DISKS" for more details. The "guestfs_inspect_os" function just
822 ignores any encrypted devices.
823 A note on the implementation: The call "guestfs_inspect_os" performs
825 inspection and caches the results in the guest handle. Subsequent
826 calls to "guestfs_inspect_get_*" return this cached information, but do
827 not re-read the disks. If you change the content of the guest disks,
828 you can redo inspection by calling "guestfs_inspect_os" again.
829 ("guestfs_inspect_list_applications2" works a little differently from
830 the other calls and does read the disks. See documentation for that
831 function for details).
832 INSPECTING INSTALL DISKS
834 Libguestfs (since 1.9.4) can detect some install disks, install CDs,
836 live CDs and more.
837 Further information is available about the operating system that can be
839 installed using the regular inspection APIs like
840 "guestfs_inspect_get_product_name", "guestfs_inspect_get_major_version"
841 etc.
842 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
844 Libguestfs can mount NTFS partitions. It does this using the
845 http://www.ntfs-3g.org/ driver.
846 DRIVE LETTERS AND PATHS
848 DOS and Windows still use drive letters, and the filesystems are always
850 treated as case insensitive by Windows itself, and therefore you might
851 find a Windows configuration file referring to a path like
852 "c:\windows\system32". When the filesystem is mounted in libguestfs,
853 that directory might be referred to as /WINDOWS/System32.
854 Drive letter mappings can be found using inspection (see "INSPECTION"
856 and "guestfs_inspect_get_drive_mappings")
857 Dealing with separator characters (backslash vs forward slash) is
859 outside the scope of libguestfs, but usually a simple character
860 replacement will work.
861 To resolve the case insensitivity of paths, call
863 "guestfs_case_sensitive_path".
864 LONG FILENAMES ON NTFS
866 NTFS supports filenames up to 255 characters long. "Character" means a
868 2 byte UTF-16 codepoint which can encode the most common Unicode
869 codepoints.
870 Most Linux filesystems support filenames up to 255 bytes. This means
872 you may get an error:
873 File name too long
875 when you copy a file from NTFS to a Linux filesystem if the name, when
877 reencoded as UTF-8, would exceed 255 bytes in length.
878 This will most often happen when using non-ASCII names that are longer
880 than ~127 characters (eg. Greek, Cyrillic) or longer than ~85
881 characters (Asian languages).
882 A workaround is not to try to store such long filenames on Linux native
884 filesystems. Since the tar(1) format can store unlimited length
885 filenames, keep the files in a tarball.
886 ACCESSING THE WINDOWS REGISTRY
888 Libguestfs also provides some help for decoding Windows Registry "hive"
890 files, through a separate C library called hivex(3).
891 Before libguestfs 1.19.35 you had to download the hive file, operate on
893 it locally using hivex, and upload it again. Since this version, we
894 have included the major hivex APIs directly in the libguestfs API (see
895 "guestfs_hivex_open"). This means that if you have opened a Windows
896 guest, you can read and write the registry directly.
897 See also virt-win-reg(1).
899 SYMLINKS ON NTFS-3G FILESYSTEMS
901 Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links" to
903 provide something which looks like a Linux symlink. The way it tries
904 to do the rewriting is described here:
905 http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/
907 The essential problem is that ntfs-3g simply does not have enough
909 information to do a correct job. NTFS links can contain drive letters
910 and references to external device GUIDs that ntfs-3g has no way of
911 resolving. It is almost certainly the case that libguestfs callers
912 should ignore what ntfs-3g does (ie. don't use "guestfs_readlink" on
913 NTFS volumes).
914 Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
916 "guestfs_lgetxattr" to read the "system.ntfs_reparse_data" extended
917 attribute, and read the raw reparse data from that (you can find the
918 format documented in various places around the web).
919 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
921 There are other useful extended attributes that can be read from
923 ntfs-3g filesystems (using "guestfs_getxattr"). See:
924 http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/
926 WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP
928 Windows guests which have been hibernated (instead of fully shut down)
930 cannot be mounted. This is a limitation of ntfs-3g. You will see an
931 error like this:
932 The disk contains an unclean file system (0, 0).
934 Metadata kept in Windows cache, refused to mount.
935 Failed to mount '/dev/sda2': Operation not permitted
936 The NTFS partition is in an unsafe state. Please resume
937 and shutdown Windows fully (no hibernation or fast
938 restarting), or mount the volume read-only with the
939 'ro' mount option.
940 In Windows 8, the shutdown button does not shut down the guest at all.
942 Instead it usually hibernates the guest. This is known as "fast
943 startup".
944 Some suggested workarounds are:
946 · Mount read-only (eg. "guestfs_mount_ro").
948 · On Windows 8, turn off fast startup. It is in the Control Panel →
950 Power Options → Choose what the power buttons do → Change settings
951 that are currently unavailable → Turn on fast startup.
952 · On Windows 7 and earlier, shut the guest off properly instead of
954 hibernating it.
955 RESIZE2FS ERRORS
957 The "guestfs_resize2fs", "guestfs_resize2fs_size" and
958 "guestfs_resize2fs_M" calls are used to resize ext2/3/4 filesystems.
959 The underlying program (resize2fs(8)) requires that the filesystem is
961 clean and recently fsck'd before you can resize it. Also, if the
962 resize operation fails for some reason, then you had to call fsck the
963 filesystem again to fix it.
964 In libguestfs "lt" 1.17.14, you usually had to call "guestfs_e2fsck_f"
966 before the resize. However, in "ge" 1.17.14, e2fsck(8) is called
967 automatically before the resize, so you no longer need to do this.
968 The resize2fs(8) program can still fail, in which case it prints an
970 error message similar to:
971 Please run 'e2fsck -fy <device>' to fix the filesystem
973 after the aborted resize operation.
974 You can do this by calling "guestfs_e2fsck" with the "forceall" option.
976 However in the context of disk images, it is usually better to avoid
977 this situation, eg. by rolling back to an earlier snapshot, or by
978 copying and resizing and on failure going back to the original.
979 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
981 Although we don’t want to discourage you from using the C API, we will
982 mention here that the same API is also available in other languages.
983 The API is broadly identical in all supported languages. This means
985 that the C call "guestfs_add_drive_ro(g,file)" is
986 "$g->add_drive_ro($file)" in Perl, "g.add_drive_ro(file)" in Python,
987 and "g#add_drive_ro file" in OCaml. In other words, a straightforward,
988 predictable isomorphism between each language.
989 Error messages are automatically transformed into exceptions if the
991 language supports it.
992 We don’t try to "object orientify" parts of the API in OO languages,
994 although contributors are welcome to write higher level APIs above what
995 we provide in their favourite languages if they wish.
996 C++ You can use the guestfs.h header file from C++ programs. The C++
998 API is identical to the C API. C++ classes and exceptions are not
999 used.
1000 C# The C# bindings are highly experimental. Please read the warnings
1002 at the top of csharp/Libguestfs.cs.
1003 Erlang
1005 See guestfs-erlang(3).
1006 GObject
1008 Experimental GObject bindings (with GObject Introspection support)
1009 are available.
1010 See guestfs-gobject(3).
1012 Go See guestfs-golang(3).
1014 Haskell
1016 This language binding is working but incomplete:
1017 · Functions with optional arguments are not bound. Implementing
1019 optional arguments in Haskell seems to be very complex.
1020 · Events are not bound.
1022 · Functions with the following return types are not bound:
1024 · Any function returning a struct.
1026 · Any function returning a list of structs.
1028 · A few functions that return fixed length buffers
1030 (specifically ones declared "RBufferOut" in the generator).
1031 · A tiny number of obscure functions that return constant
1033 strings (specifically ones declared "RConstOptString" in
1034 the generator).
1035 Java
1037 Full documentation is contained in the Javadoc which is distributed
1038 with libguestfs. For examples, see guestfs-java(3).
1039 Lua See guestfs-lua(3).
1041 OCaml
1043 See guestfs-ocaml(3).
1044 Perl
1046 See guestfs-perl(3) and Sys::Guestfs(3).
1047 PHP For documentation see "README-PHP" supplied with libguestfs sources
1049 or in the php-libguestfs package for your distribution.
1050 The PHP binding only works correctly on 64 bit machines.
1052 Python
1054 See guestfs-python(3).
1055 Ruby
1057 See guestfs-ruby(3).
1058 For JRuby, use the Java bindings.
1060 shell scripts
1062 See guestfish(1).
1063 LIBGUESTFS GOTCHAS
1065 http://en.wikipedia.org/wiki/Gotcha_(programming): "A feature of a
1066 system [...] that works in the way it is documented but is
1067 counterintuitive and almost invites mistakes."
1068 Since we developed libguestfs and the associated tools, there are
1070 several things we would have designed differently, but are now stuck
1071 with for backwards compatibility or other reasons. If there is ever a
1072 libguestfs 2.0 release, you can expect these to change. Beware of
1073 them.
1074 Read-only should be the default.
1076 In guestfish(3), --ro should be the default, and you should have to
1077 specify --rw if you want to make changes to the image.
1078 This would reduce the potential to corrupt live VM images.
1080 Note that many filesystems change the disk when you just mount and
1082 unmount, even if you didn't perform any writes. You need to use
1083 "guestfs_add_drive_ro" to guarantee that the disk is not changed.
1084 guestfish command line is hard to use.
1086 guestfish disk.img doesn't do what people expect (open disk.img for
1087 examination). It tries to run a guestfish command disk.img which
1088 doesn't exist, so it fails. In earlier versions of guestfish the
1089 error message was also unintuitive, but we have corrected this
1090 since. Like the Bourne shell, we should have used "guestfish -c
1091 command" to run commands.
1092 guestfish megabyte modifiers don’t work right on all commands
1094 In recent guestfish you can use "1M" to mean 1 megabyte (and
1095 similarly for other modifiers). What guestfish actually does is to
1096 multiply the number part by the modifier part and pass the result
1097 to the C API. However this doesn't work for a few APIs which
1098 aren't expecting bytes, but are already expecting some other unit
1099 (eg. megabytes).
1100 The most common is "guestfs_lvcreate". The guestfish command:
1102 lvcreate LV VG 100M
1104 does not do what you might expect. Instead because
1106 "guestfs_lvcreate" is already expecting megabytes, this tries to
1107 create a 100 terabyte (100 megabytes * megabytes) logical volume.
1108 The error message you get from this is also a little obscure.
1109 This could be fixed in the generator by specially marking
1111 parameters and return values which take bytes or other units.
1112 Ambiguity between devices and paths
1114 There is a subtle ambiguity in the API between a device name (eg.
1115 /dev/sdb2) and a similar pathname. A file might just happen to be
1116 called "sdb2" in the directory /dev (consider some non-Unix VM
1117 image).
1118 In the current API we usually resolve this ambiguity by having two
1120 separate calls, for example "guestfs_checksum" and
1121 "guestfs_checksum_device". Some API calls are ambiguous and
1122 (incorrectly) resolve the problem by detecting if the path supplied
1123 begins with /dev/.
1124 To avoid both the ambiguity and the need to duplicate some calls,
1126 we could make paths/devices into structured names. One way to do
1127 this would be to use a notation like grub ("hd(0,0)"), although
1128 nobody really likes this aspect of grub. Another way would be to
1129 use a structured type, equivalent to this OCaml type:
1130 type path = Path of string | Device of int | Partition of int * int
1132 which would allow you to pass arguments like:
1134 Path "/foo/bar"
1136 Device 1 (* /dev/sdb, or perhaps /dev/sda *)
1137 Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
1138 Path "/dev/sdb2" (* not a device *)
1139 As you can see there are still problems to resolve even with this
1141 representation. Also consider how it might work in guestfish.
1142 KEYS AND PASSPHRASES
1144 Certain libguestfs calls take a parameter that contains sensitive key
1145 material, passed in as a C string.
1146 In the future we would hope to change the libguestfs implementation so
1148 that keys are mlock(2)-ed into physical RAM, and thus can never end up
1149 in swap. However this is not done at the moment, because of the
1150 complexity of such an implementation.
1151 Therefore you should be aware that any key parameter you pass to
1153 libguestfs might end up being written out to the swap partition. If
1154 this is a concern, scrub the swap partition or don't use libguestfs on
1155 encrypted devices.
1156 MULTIPLE HANDLES AND MULTIPLE THREADS
1158 All high-level libguestfs actions are synchronous. If you want to use
1159 libguestfs asynchronously then you must create a thread.
1160 Threads in libguestfs ≥ 1.38
1162 In libguestfs ≥ 1.38, each handle ("guestfs_h") contains a lock which
1164 is acquired automatically when you call a libguestfs function. The
1165 practical effect of this is you can call libguestfs functions with the
1166 same handle from multiple threads without needing to do any locking.
1167 Also in libguestfs ≥ 1.38, the last error on the handle
1169 ("guestfs_last_error", "guestfs_last_errno") is stored in thread-local
1170 storage, so it is safe to write code like:
1171 if (guestfs_add_drive_ro (g, drive) == -1)
1173 fprintf (stderr, "error was: %s\n", guestfs_last_error (g));
1174 even when other threads may be concurrently using the same handle "g".
1176 Threads in libguestfs < 1.38
1178 In libguestfs < 1.38, you must use the handle only from a single
1180 thread. Either use the handle exclusively from one thread, or provide
1181 your own mutex so that two threads cannot issue calls on the same
1182 handle at the same time. Even apparently innocent functions like
1183 "guestfs_get_trace" are not safe to be called from multiple threads
1184 without a mutex in libguestfs < 1.38.
1185 Use "guestfs_set_identifier" to make it simpler to identify threads in
1187 trace output.
1188 PATH
1190 Libguestfs needs a supermin appliance, which it finds by looking along
1191 an internal path.
1192 By default it looks for these in the directory "$libdir/guestfs" (eg.
1194 /usr/local/lib/guestfs or /usr/lib64/guestfs).
1195 Use "guestfs_set_path" or set the environment variable
1197 "LIBGUESTFS_PATH" to change the directories that libguestfs will search
1198 in. The value is a colon-separated list of paths. The current
1199 directory is not searched unless the path contains an empty element or
1200 ".". For example "LIBGUESTFS_PATH=:/usr/lib/guestfs" would search the
1201 current directory and then /usr/lib/guestfs.
1202 QEMU WRAPPERS
1204 If you want to compile your own qemu, run qemu from a non-standard
1205 location, or pass extra arguments to qemu, then you can write a shell-
1206 script wrapper around qemu.
1207 There is one important rule to remember: you must "exec qemu" as the
1209 last command in the shell script (so that qemu replaces the shell and
1210 becomes the direct child of the libguestfs-using program). If you
1211 don't do this, then the qemu process won't be cleaned up correctly.
1212 Here is an example of a wrapper, where I have built my own copy of qemu
1214 from source:
1215 #!/bin/sh -
1217 qemudir=/home/rjones/d/qemu
1218 exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
1219 Save this script as /tmp/qemu.wrapper (or wherever), "chmod +x", and
1221 then use it by setting the LIBGUESTFS_HV environment variable. For
1222 example:
1223 LIBGUESTFS_HV=/tmp/qemu.wrapper guestfish
1225 Note that libguestfs also calls qemu with the -help and -version
1227 options in order to determine features.
1228 Wrappers can also be used to edit the options passed to qemu. In the
1230 following example, the "-machine ..." option ("-machine" and the
1231 following argument) are removed from the command line and replaced with
1232 "-machine pc,accel=tcg". The while loop iterates over the options
1233 until it finds the right one to remove, putting the remaining options
1234 into the "args" array.
1235 #!/bin/bash -
1237 i=0
1239 while [ $# -gt 0 ]; do
1240 case "$1" in
1241 -machine)
1242 shift 2;;
1243 *)
1244 args[i]="$1"
1245 (( i++ ))
1246 shift ;;
1247 esac
1248 done
1249 exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
1251 BACKEND
1253 The backend (previously known as the "attach method") controls how
1254 libguestfs creates and/or connects to the backend daemon, eg. by
1255 starting qemu directly, or using libvirt to manage an appliance,
1256 running User-Mode Linux, or connecting to an already running daemon.
1257 You can set the backend by calling "guestfs_set_backend", or by setting
1259 the environment variable "LIBGUESTFS_BACKEND".
1260 Possible backends are described below:
1262 "direct"
1264 "appliance"
1265 Run qemu directly to launch an appliance.
1266 "direct" and "appliance" are synonyms.
1268 This is the ordinary method and normally the default, but see the
1270 note below.
1271 "libvirt"
1273 "libvirt:null"
1274 "libvirt:URI"
1275 Use libvirt to launch and manage the appliance.
1276 "libvirt" causes libguestfs to choose a suitable URI for creating
1278 session guests. If using the libvirt backend, you almost always
1279 should use this.
1280 "libvirt:null" causes libguestfs to use the "NULL" connection URI,
1282 which causes libvirt to try to guess what the user meant. You
1283 probably don't want to use this.
1284 "libvirt:URI" uses URI as the libvirt connection URI (see
1286 http://libvirt.org/uri.html). The typical libvirt backend with a
1287 URI would be "libvirt:qemu:///session"
1288 The libvirt backend supports more features, including hotplugging
1290 (see "HOTPLUGGING") and sVirt.
1291 "uml"
1293 Run the User-Mode Linux kernel. The location of the kernel is set
1294 using $LIBGUESTFS_HV or using the "guestfs_set_qemu" API (note that
1295 qemu is not involved, we just reuse the same variable in the handle
1296 for convenience).
1297 User-Mode Linux can be much faster, simpler and more lightweight
1299 than using a full-blown virtual machine, but it also has some
1300 shortcomings. See "USER-MODE LINUX BACKEND" below.
1301 "unix:path"
1303 Connect to the Unix domain socket path.
1304 This method lets you connect to an existing daemon or (using
1306 virtio-serial) to a live guest. For more information, see
1307 "ATTACHING TO RUNNING DAEMONS".
1308 "direct" is usually the default backend. However since libguestfs ≥
1310 1.19.24, libguestfs can be built with a different default by doing:
1311 ./configure --with-default-backend=...
1313 To find out if libguestfs was compiled with a different default
1315 backend, do:
1316 unset LIBGUESTFS_BACKEND
1318 guestfish get-backend
1319 BACKEND SETTINGS
1321 Each backend can be configured by passing a list of strings. You can
1322 either call "guestfs_set_backend_settings" with a list of strings, or
1323 set the "LIBGUESTFS_BACKEND_SETTINGS" environment variable to a colon-
1324 separated list of strings (before creating the handle).
1325 force_tcg
1327 Using:
1329 export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
1331 will force the direct and libvirt backends to use TCG (software
1333 emulation) instead of KVM (hardware accelerated virtualization).
1334 gdb
1336 The direct backend supports:
1338 export LIBGUESTFS_BACKEND_SETTINGS=gdb
1340 When this is set, qemu will not start running the appliance
1342 immediately. It will wait for you to connect to it using gdb:
1343 $ gdb
1345 (gdb) symbol-file /path/to/vmlinux
1346 (gdb) target remote tcp::1234
1347 (gdb) cont
1348 You can then debug the appliance kernel, which is useful to debug boot
1350 failures (especially ones where there are no debug messages printed -
1351 tip: look in the kernel "log_buf").
1352 On Fedora, install "kernel-debuginfo" for the "vmlinux" file
1354 (containing symbols). Make sure the symbols precisely match the kernel
1355 being used.
1356 ATTACHING TO RUNNING DAEMONS
1358 Note [4m(1): This is highly experimental and has a tendency to eat babies.
1359 Use with caution.
1360 Note [4m(2): This section explains how to attach to a running daemon from
1362 a low level perspective. For most users, simply using virt tools such
1363 as guestfish(1) with the --live option will "just work".
1364 Using guestfs_set_backend
1366 By calling "guestfs_set_backend" you can change how the library
1368 connects to the "guestfsd" daemon in "guestfs_launch" (read
1369 "ARCHITECTURE" in guestfs-internals(1) for some background).
1370 The normal backend is "direct", where a small appliance is created
1372 containing the daemon, and then the library connects to this.
1373 "libvirt" or "libvirt:URI" are alternatives that use libvirt to start
1374 the appliance.
1375 Setting the backend to "unix:path" (where path is the path of a Unix
1377 domain socket) causes "guestfs_launch" to connect to an existing daemon
1378 over the Unix domain socket.
1379 The normal use for this is to connect to a running virtual machine that
1381 contains a "guestfsd" daemon, and send commands so you can read and
1382 write files inside the live virtual machine.
1383 Using guestfs_add_domain with live flag
1385 "guestfs_add_domain" provides some help for getting the correct
1387 backend. If you pass the "live" option to this function, then (if the
1388 virtual machine is running) it will examine the libvirt XML looking for
1389 a virtio-serial channel to connect to:
1390 <domain>
1392 ...
1393 <devices>
1394 ...
1395 <channel type='unix'>
1396 <source mode='bind' path='/path/to/socket'/>
1397 <target type='virtio' name='org.libguestfs.channel.0'/>
1398 </channel>
1399 ...
1400 </devices>
1401 </domain>
1402 "guestfs_add_domain" extracts /path/to/socket and sets the backend to
1404 "unix:/path/to/socket".
1405 Some of the libguestfs tools (including guestfish) support a --live
1407 option which is passed through to "guestfs_add_domain" thus allowing
1408 you to attach to and modify live virtual machines.
1409 The virtual machine needs to have been set up beforehand so that it has
1411 the virtio-serial channel and so that guestfsd is running inside it.
1412 USER-MODE LINUX BACKEND
1414 Setting the following environment variables (or the equivalent in the
1415 API) selects the User-Mode Linux backend:
1416 export LIBGUESTFS_BACKEND=uml
1418 export LIBGUESTFS_HV=/path/to/vmlinux
1419 "vmlinux" (or it may be called "linux") is the Linux binary, compiled
1421 to run as a userspace process. Note that we reuse the qemu variable in
1422 the handle for convenience; qemu is not involved.
1423 User-Mode Linux can be faster and more lightweight than running a full-
1425 blown virtual machine as the backend (especially if you are already
1426 running libguestfs in a virtual machine or cloud instance), but it also
1427 has some shortcomings compared to the usual qemu/KVM-based backend.
1428 BUILDING USER-MODE LINUX FROM SOURCE
1430 Your Linux distro may provide UML in which case you can ignore this
1432 section.
1433 These instructions are adapted from:
1435 http://user-mode-linux.sourceforge.net/source.html
1436 1. Check out Linux sources
1438 Clone the Linux git repository or download the Linux source
1439 tarball.
1440 2. Configure the kernel
1442 Note: All ‘make’ commands must have "ARCH=um" added.
1443 make menuconfig ARCH=um
1445 Make sure any filesystem drivers that you need are compiled into
1447 the kernel.
1448 Currently, it needs a large amount of extra work to get modules
1450 working. It’s recommended that you disable module support in the
1451 kernel configuration, which will cause everything to be compiled
1452 into the image.
1453 3. Build the kernel
1455 make ARCH=um
1456 This will leave a file called "linux" or "vmlinux" in the top-level
1458 directory. This is the UML kernel. You should set "LIBGUESTFS_HV"
1459 to point to this file.
1460 USER-MODE LINUX DIFFERENCES FROM KVM
1462 UML only supports raw-format images
1464 Only plain raw-format images will work. No qcow2, no backing
1465 files.
1466 UML does not support any remote drives
1468 No NBD, etc.
1469 UML only works on ix86 and x86-64
1471 UML is experimental
1472 In particular, support for UML in libguestfs depends on support for
1473 UML in the upstream kernel. If UML was ever removed from the
1474 upstream Linux kernel, then we might remove it from libguestfs too.
1475 ABI GUARANTEE
1477 We guarantee the libguestfs ABI (binary interface), for public, high-
1478 level actions as outlined in this section. Although we will deprecate
1479 some actions, for example if they get replaced by newer calls, we will
1480 keep the old actions forever. This allows you the developer to program
1481 in confidence against the libguestfs API.
1482 BLOCK DEVICE NAMING
1484 Libguestfs defines /dev/sd* as the standard naming scheme for devices
1485 passed to API calls. So /dev/sda means "the first device added by
1486 "guestfs_add_drive_opts"", and /dev/sdb3 means "the third partition on
1487 the second device".
1488 Internally device names are sometimes translated, but this should not
1490 be visible at the API level.
1491 DISK LABELS
1493 In libguestfs ≥ 1.20, you can give a label to a disk when you add it,
1495 using the optional "label" parameter to "guestfs_add_drive_opts".
1496 (Note that disk labels are different from and not related to filesystem
1497 labels).
1498 Not all versions of libguestfs support setting a disk label, and when
1500 it is supported, it is limited to 20 ASCII characters "[a-zA-Z]".
1501 When you add a disk with a label, it can either be addressed using
1503 /dev/sd*, or using /dev/disk/guestfs/label. Partitions on the disk can
1504 be addressed using /dev/disk/guestfs/labelpartnum.
1505 Listing devices ("guestfs_list_devices") and partitions
1507 ("guestfs_list_partitions") returns the block device names. However
1508 you can use "guestfs_list_disk_labels" to map disk labels to block
1509 device and partition names.
1510 NULL DISKS
1512 When adding a disk using, eg., "guestfs_add_drive", you can set the
1513 filename to "/dev/null". This string is treated specially by
1514 libguestfs, causing it to add a "null disk".
1515 A null disk has the following properties:
1517 · A null disk will appear as a normal device, eg. in calls to
1519 "guestfs_list_devices".
1520 · You may add "/dev/null" multiple times.
1522 · You should not try to access a null disk in any way. For example,
1524 you shouldn't try to read it or mount it.
1525 Null disks are used for three main purposes:
1527 1. Performance testing of libguestfs (see guestfs-performance(1)).
1529 2. The internal test suite.
1531 3. If you want to use libguestfs APIs that don’t refer to disks, since
1533 libguestfs requires that at least one disk is added, you should add
1534 a null disk.
1535 For example, to test if a feature is available, use code like this:
1537 guestfs_h *g;
1539 char **groups = [ "btrfs", NULL ];
1540 g = guestfs_create ();
1542 guestfs_add_drive (g, "/dev/null");
1543 guestfs_launch (g);
1544 if (guestfs_available (g, groups) == 0) {
1545 // group(s) are available
1546 } else {
1547 // group(s) are not available
1548 }
1549 guestfs_close (g);
1550 DISK IMAGE FORMATS
1552 Virtual disks come in a variety of formats. Some common formats are
1553 listed below.
1554 Note that libguestfs itself is not responsible for handling the disk
1556 format: this is done using qemu(1). If support for a particular format
1557 is missing or broken, this has to be fixed in qemu.
1558 COMMON VIRTUAL DISK IMAGE FORMATS
1560 raw Raw format is simply a dump of the sequential bytes of the virtual
1562 hard disk. There is no header, container, compression or
1563 processing of any sort.
1564 Since raw format requires no translation to read or write, it is
1566 both fast and very well supported by qemu and all other
1567 hypervisors. You can consider it to be a universal format that any
1568 hypervisor can access.
1569 Raw format files are not compressed and so take up the full space
1571 of the original disk image even when they are empty. A variation
1572 (on Linux/Unix at least) is to not store ranges of all-zero bytes
1573 by storing the file as a sparse file. This "variant format" is
1574 sometimes called raw sparse. Many utilities, including
1575 virt-sparsify(1), can make raw disk images sparse.
1576 qcow2
1578 Qcow2 is the native disk image format used by qemu. Internally it
1579 uses a two-level directory structure so that only blocks containing
1580 data are stored in the file. It also has many other features such
1581 as compression, snapshots and backing files.
1582 There are at least two distinct variants of this format, although
1584 qemu (and hence libguestfs) handles both transparently to the user.
1585 vmdk
1587 VMDK is VMware’s native disk image format. There are many
1588 variations. Modern qemu (hence libguestfs) supports most
1589 variations, but you should be aware that older versions of qemu had
1590 some very bad data-corrupting bugs in this area.
1591 Note that VMware ESX exposes files with the name guest-flat.vmdk.
1593 These are not VMDK. They are raw format files which happen to have
1594 a ".vmdk" extension.
1595 vdi VDI is VirtualBox’s native disk image format. Qemu (hence
1597 libguestfs) has generally good support for this.
1598 vpc
1600 vhd VPC (old) and VHD (modern) are the native disk image format of
1601 Microsoft (and previously, Connectix) Virtual PC and Hyper-V.
1602 Obsolete formats
1604 The following formats are obsolete and should not be used: qcow
1605 (aka qcow1), cow, bochs.
1606 DETECTING THE FORMAT OF A DISK IMAGE
1608 Firstly note there is a security issue with auto-detecting the format
1610 of a disk image. It may or may not apply in your use case. Read
1611 "CVE-2010-3851" below.
1612 Libguestfs offers an API to get the format of a disk image
1614 ("guestfs_disk_format"), and it is safest to use this.
1615 Don’t be tempted to try parsing the text / human-readable output of
1617 "qemu-img" since it cannot be parsed reliably and securely. Also do
1618 not use the "file" command since the output of that changes over time.
1619
1621 guestfs_h *
1622 "guestfs_h" is the opaque type representing a connection handle.
1623 Create a handle by calling "guestfs_create" or "guestfs_create_flags".
1624 Call "guestfs_close" to free the handle and release all resources used.
1625 For information on using multiple handles and threads, see the section
1627 "MULTIPLE HANDLES AND MULTIPLE THREADS" above.
1628 guestfs_create
1630 guestfs_h *guestfs_create (void);
1631 Create a connection handle.
1633 On success this returns a non-NULL pointer to a handle. On error it
1635 returns NULL.
1636 You have to "configure" the handle after creating it. This includes
1638 calling "guestfs_add_drive_opts" (or one of the equivalent calls) on
1639 the handle at least once.
1640 After configuring the handle, you have to call "guestfs_launch".
1642 You may also want to configure error handling for the handle. See the
1644 "ERROR HANDLING" section below.
1645 guestfs_create_flags
1647 guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
1648 Create a connection handle, supplying extra flags and extra arguments
1650 to control how the handle is created.
1651 On success this returns a non-NULL pointer to a handle. On error it
1653 returns NULL.
1654 "guestfs_create" is equivalent to calling guestfs_create_flags(0).
1656 The following flags may be logically ORed together. (Currently no
1658 extra arguments are used).
1659 "GUESTFS_CREATE_NO_ENVIRONMENT"
1661 Don’t parse any environment variables (such as "LIBGUESTFS_DEBUG"
1662 etc).
1663 You can call "guestfs_parse_environment" or
1665 "guestfs_parse_environment_list" afterwards to parse environment
1666 variables. Alternately, don't call these functions if you want the
1667 handle to be unaffected by environment variables. See the example
1668 below.
1669 The default (if this flag is not given) is to implicitly call
1671 "guestfs_parse_environment".
1672 "GUESTFS_CREATE_NO_CLOSE_ON_EXIT"
1674 Don’t try to close the handle in an atexit(3) handler if the
1675 program exits without explicitly closing the handle.
1676 The default (if this flag is not given) is to install such an
1678 atexit handler.
1679 USING "GUESTFS_CREATE_NO_ENVIRONMENT"
1681 You might use "GUESTFS_CREATE_NO_ENVIRONMENT" and an explicit call to
1683 "guestfs_parse_environment" like this:
1684 guestfs_h *g;
1686 int r;
1687 g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
1689 if (!g) {
1690 perror ("guestfs_create_flags");
1691 exit (EXIT_FAILURE);
1692 }
1693 r = guestfs_parse_environment (g);
1694 if (r == -1)
1695 exit (EXIT_FAILURE);
1696 Or to create a handle which is unaffected by environment variables,
1698 omit the call to "guestfs_parse_environment" from the above code.
1699 The above code has another advantage which is that any errors from
1701 parsing the environment are passed through the error handler, whereas
1702 "guestfs_create" prints errors on stderr and ignores them.
1703 guestfs_close
1705 void guestfs_close (guestfs_h *g);
1706 This closes the connection handle and frees up all resources used. If
1708 a close callback was set on the handle, then it is called.
1709 The correct way to close the handle is:
1711 if (guestfs_shutdown (g) == -1) {
1713 /* handle write errors here */
1714 }
1715 guestfs_close (g);
1716 "guestfs_shutdown" is only needed if all of the following are true:
1718 1. one or more disks were added in read-write mode, and
1720 2. guestfs_launch was called, and
1722 3. you made some changes, and
1724 4. you have a way to handle write errors (eg. by exiting with an error
1726 code or reporting something to the user).
1727
1729 API functions can return errors. For example, almost all functions
1730 that return "int" will return "-1" to indicate an error.
1731 Additional information is available for errors: an error message string
1733 and optionally an error number (errno) if the thing that failed was a
1734 system call.
1735 You can get at the additional information about the last error on the
1737 handle by calling "guestfs_last_error", "guestfs_last_errno", and/or by
1738 setting up an error handler with "guestfs_set_error_handler".
1739 When the handle is created, a default error handler is installed which
1741 prints the error message string to "stderr". For small short-running
1742 command line programs it is sufficient to do:
1743 if (guestfs_launch (g) == -1)
1745 exit (EXIT_FAILURE);
1746 since the default error handler will ensure that an error message has
1748 been printed to "stderr" before the program exits.
1749 For other programs the caller will almost certainly want to install an
1751 alternate error handler or do error handling in-line as in the example
1752 below. The non-C language bindings all install NULL error handlers and
1753 turn errors into exceptions using code similar to this:
1754 const char *msg;
1756 int errnum;
1757 /* This disables the default behaviour of printing errors
1759 on stderr. */
1760 guestfs_set_error_handler (g, NULL, NULL);
1761 if (guestfs_launch (g) == -1) {
1763 /* Examine the error message and print it, throw it,
1764 etc. */
1765 msg = guestfs_last_error (g);
1766 errnum = guestfs_last_errno (g);
1767 fprintf (stderr, "%s", msg);
1769 if (errnum != 0)
1770 fprintf (stderr, ": %s", strerror (errnum));
1771 fprintf (stderr, "\n");
1772 /* ... */
1774 }
1775 "guestfs_create" returns "NULL" if the handle cannot be created, and
1777 because there is no handle if this happens there is no way to get
1778 additional error information. Since libguestfs ≥ 1.20, you can use
1779 "guestfs_create_flags" to properly deal with errors during handle
1780 creation, although the vast majority of programs can continue to use
1781 "guestfs_create" and not worry about this situation.
1782 Out of memory errors are handled differently. The default action is to
1784 call abort(3). If this is undesirable, then you can set a handler
1785 using "guestfs_set_out_of_memory_handler".
1786 guestfs_last_error
1788 const char *guestfs_last_error (guestfs_h *g);
1789 This returns the last error message that happened on "g". If there has
1791 not been an error since the handle was created, then this returns
1792 "NULL".
1793 Note the returned string does not have a newline character at the end.
1795 Most error messages are single lines. Some are split over multiple
1796 lines and contain "\n" characters within the string but not at the end.
1797 The lifetime of the returned string is until the next error occurs on
1799 the same handle, or "guestfs_close" is called. If you need to keep it
1800 longer, copy it.
1801 guestfs_last_errno
1803 int guestfs_last_errno (guestfs_h *g);
1804 This returns the last error number (errno) that happened on "g".
1806 If successful, an errno integer not equal to zero is returned.
1808 In many cases the special errno "ENOTSUP" is returned if you tried to
1810 call a function or use a feature which is not supported.
1811 If no error number is available, this returns 0. This call can return
1813 0 in three situations:
1814 1. There has not been any error on the handle.
1816 2. There has been an error but the errno was meaningless. This
1818 corresponds to the case where the error did not come from a failed
1819 system call, but for some other reason.
1820 3. There was an error from a failed system call, but for some reason
1822 the errno was not captured and returned. This usually indicates a
1823 bug in libguestfs.
1824 Libguestfs tries to convert the errno from inside the appliance into a
1826 corresponding errno for the caller (not entirely trivial: the appliance
1827 might be running a completely different operating system from the
1828 library and error numbers are not standardized across Un*xen). If this
1829 could not be done, then the error is translated to "EINVAL". In
1830 practice this should only happen in very rare circumstances.
1831 guestfs_set_error_handler
1833 typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
1834 void *opaque,
1835 const char *msg);
1836 void guestfs_set_error_handler (guestfs_h *g,
1837 guestfs_error_handler_cb cb,
1838 void *opaque);
1839 The callback "cb" will be called if there is an error. The parameters
1841 passed to the callback are an opaque data pointer and the error message
1842 string.
1843 "errno" is not passed to the callback. To get that the callback must
1845 call "guestfs_last_errno".
1846 Note that the message string "msg" is freed as soon as the callback
1848 function returns, so if you want to stash it somewhere you must make
1849 your own copy.
1850 The default handler prints messages on "stderr".
1852 If you set "cb" to "NULL" then no handler is called.
1854 guestfs_get_error_handler
1856 guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
1857 void **opaque_rtn);
1858 Returns the current error handler callback.
1860 guestfs_push_error_handler
1862 void guestfs_push_error_handler (guestfs_h *g,
1863 guestfs_error_handler_cb cb,
1864 void *opaque);
1865 This is the same as "guestfs_set_error_handler", except that the old
1867 error handler is stashed away in a stack inside the handle. You can
1868 restore the previous error handler by calling
1869 "guestfs_pop_error_handler".
1870 Use the following code to temporarily disable errors around a function:
1872 guestfs_push_error_handler (g, NULL, NULL);
1874 guestfs_mkdir (g, "/foo"); /* We don't care if this fails. */
1875 guestfs_pop_error_handler (g);
1876 guestfs_pop_error_handler
1878 void guestfs_pop_error_handler (guestfs_h *g);
1879 Restore the previous error handler (see "guestfs_push_error_handler").
1881 If you pop the stack too many times, then the default error handler is
1883 restored.
1884 guestfs_set_out_of_memory_handler
1886 typedef void (*guestfs_abort_cb) (void);
1887 void guestfs_set_out_of_memory_handler (guestfs_h *g,
1888 guestfs_abort_cb);
1889 The callback "cb" will be called if there is an out of memory
1891 situation. Note this callback must not return.
1892 The default is to call abort(3).
1894 You cannot set "cb" to "NULL". You can’t ignore out of memory
1896 situations.
1897 guestfs_get_out_of_memory_handler
1899 guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
1900 This returns the current out of memory handler.
1902
1904 guestfs_acl_delete_def_file
1905 int
1906 guestfs_acl_delete_def_file (guestfs_h *g,
1907 const char *dir);
1908 This function deletes the default POSIX Access Control List (ACL)
1910 attached to directory "dir".
1911 This function returns 0 on success or -1 on error.
1913 This function depends on the feature "acl". See also
1915 "guestfs_feature_available".
1916 (Added in 1.19.63)
1918 guestfs_acl_get_file
1920 char *
1921 guestfs_acl_get_file (guestfs_h *g,
1922 const char *path,
1923 const char *acltype);
1924 This function returns the POSIX Access Control List (ACL) attached to
1926 "path". The ACL is returned in "long text form" (see acl(5)).
1927 The "acltype" parameter may be:
1929 "access"
1931 Return the ordinary (access) ACL for any file, directory or other
1932 filesystem object.
1933 "default"
1935 Return the default ACL. Normally this only makes sense if "path"
1936 is a directory.
1937 This function returns a string, or NULL on error. The caller must free
1939 the returned string after use.
1940 This function depends on the feature "acl". See also
1942 "guestfs_feature_available".
1943 (Added in 1.19.63)
1945 guestfs_acl_set_file
1947 int
1948 guestfs_acl_set_file (guestfs_h *g,
1949 const char *path,
1950 const char *acltype,
1951 const char *acl);
1952 This function sets the POSIX Access Control List (ACL) attached to
1954 "path".
1955 The "acltype" parameter may be:
1957 "access"
1959 Set the ordinary (access) ACL for any file, directory or other
1960 filesystem object.
1961 "default"
1963 Set the default ACL. Normally this only makes sense if "path" is a
1964 directory.
1965 The "acl" parameter is the new ACL in either "long text form" or "short
1967 text form" (see acl(5)). The new ACL completely replaces any previous
1968 ACL on the file. The ACL must contain the full Unix permissions (eg.
1969 "u::rwx,g::rx,o::rx").
1970 If you are specifying individual users or groups, then the mask field
1972 is also required (eg. "m::rwx"), followed by the "u:ID:..." and/or
1973 "g:ID:..." field(s). A full ACL string might therefore look like this:
1974 u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
1976 \ Unix permissions / \mask/ \ ACL /
1977 You should use numeric UIDs and GIDs. To map usernames and groupnames
1979 to the correct numeric ID in the context of the guest, use the Augeas
1980 functions (see "guestfs_aug_init").
1981 This function returns 0 on success or -1 on error.
1983 This function depends on the feature "acl". See also
1985 "guestfs_feature_available".
1986 (Added in 1.19.63)
1988 guestfs_add_cdrom
1990 int
1991 guestfs_add_cdrom (guestfs_h *g,
1992 const char *filename);
1993 This function is deprecated. In new code, use the
1995 "guestfs_add_drive_ro" call instead.
1996 Deprecated functions will not be removed from the API, but the fact
1998 that they are deprecated indicates that there are problems with correct
1999 use of these functions.
2000 This function adds a virtual CD-ROM disk image to the guest.
2002 The image is added as read-only drive, so this function is equivalent
2004 of "guestfs_add_drive_ro".
2005 This function returns 0 on success or -1 on error.
2007 (Added in 0.3)
2009 guestfs_add_domain
2011 int
2012 guestfs_add_domain (guestfs_h *g,
2013 const char *dom,
2014 ...);
2015 You may supply a list of optional arguments to this call. Use zero or
2017 more of the following pairs of parameters, and terminate the list with
2018 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2019 GUESTFS_ADD_DOMAIN_LIBVIRTURI, const char *libvirturi,
2021 GUESTFS_ADD_DOMAIN_READONLY, int readonly,
2022 GUESTFS_ADD_DOMAIN_IFACE, const char *iface,
2023 GUESTFS_ADD_DOMAIN_LIVE, int live,
2024 GUESTFS_ADD_DOMAIN_ALLOWUUID, int allowuuid,
2025 GUESTFS_ADD_DOMAIN_READONLYDISK, const char *readonlydisk,
2026 GUESTFS_ADD_DOMAIN_CACHEMODE, const char *cachemode,
2027 GUESTFS_ADD_DOMAIN_DISCARD, const char *discard,
2028 GUESTFS_ADD_DOMAIN_COPYONREAD, int copyonread,
2029 This function adds the disk(s) attached to the named libvirt domain
2031 "dom". It works by connecting to libvirt, requesting the domain and
2032 domain XML from libvirt, parsing it for disks, and calling
2033 "guestfs_add_drive_opts" on each one.
2034 The number of disks added is returned. This operation is atomic: if an
2036 error is returned, then no disks are added.
2037 This function does some minimal checks to make sure the libvirt domain
2039 is not running (unless "readonly" is true). In a future version we
2040 will try to acquire the libvirt lock on each disk.
2041 Disks must be accessible locally. This often means that adding disks
2043 from a remote libvirt connection (see https://libvirt.org/remote.html)
2044 will fail unless those disks are accessible via the same device path
2045 locally too.
2046 The optional "libvirturi" parameter sets the libvirt URI (see
2048 https://libvirt.org/uri.html). If this is not set then we connect to
2049 the default libvirt URI (or one set through an environment variable,
2050 see the libvirt documentation for full details).
2051 The optional "live" flag controls whether this call will try to connect
2053 to a running virtual machine "guestfsd" process if it sees a suitable
2054 <channel> element in the libvirt XML definition. The default (if the
2055 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
2056 for more information.
2057 If the "allowuuid" flag is true (default is false) then a UUID may be
2059 passed instead of the domain name. The "dom" string is treated as a
2060 UUID first and looked up, and if that lookup fails then we treat "dom"
2061 as a name as usual.
2062 The optional "readonlydisk" parameter controls what we do for disks
2064 which are marked <readonly/> in the libvirt XML. Possible values are:
2065 readonlydisk = "error"
2067 If "readonly" is false:
2068 The whole call is aborted with an error if any disk with the
2070 <readonly/> flag is found.
2071 If "readonly" is true:
2073 Disks with the <readonly/> flag are added read-only.
2075 readonlydisk = "read"
2077 If "readonly" is false:
2078 Disks with the <readonly/> flag are added read-only. Other disks
2080 are added read/write.
2081 If "readonly" is true:
2083 Disks with the <readonly/> flag are added read-only.
2085 readonlydisk = "write" (default)
2087 If "readonly" is false:
2088 Disks with the <readonly/> flag are added read/write.
2090 If "readonly" is true:
2092 Disks with the <readonly/> flag are added read-only.
2094 readonlydisk = "ignore"
2096 If "readonly" is true or false:
2097 Disks with the <readonly/> flag are skipped.
2099 If present, the value of "logical_block_size" attribute of <blockio/>
2101 tag in libvirt XML will be passed as "blocksize" parameter to
2102 "guestfs_add_drive_opts".
2103 The other optional parameters are passed directly through to
2105 "guestfs_add_drive_opts".
2106 On error this function returns -1.
2108 (Added in 1.7.4)
2110 guestfs_add_domain_va
2112 int
2113 guestfs_add_domain_va (guestfs_h *g,
2114 const char *dom,
2115 va_list args);
2116 This is the "va_list variant" of "guestfs_add_domain".
2118 See "CALLS WITH OPTIONAL ARGUMENTS".
2120 guestfs_add_domain_argv
2122 int
2123 guestfs_add_domain_argv (guestfs_h *g,
2124 const char *dom,
2125 const struct guestfs_add_domain_argv *optargs);
2126 This is the "argv variant" of "guestfs_add_domain".
2128 See "CALLS WITH OPTIONAL ARGUMENTS".
2130 guestfs_add_drive
2132 int
2133 guestfs_add_drive (guestfs_h *g,
2134 const char *filename);
2135 This function is provided for backwards compatibility with earlier
2137 versions of libguestfs. It simply calls "guestfs_add_drive_opts" with
2138 no optional arguments.
2139 (Added in 0.3)
2141 guestfs_add_drive_opts
2143 int
2144 guestfs_add_drive_opts (guestfs_h *g,
2145 const char *filename,
2146 ...);
2147 You may supply a list of optional arguments to this call. Use zero or
2149 more of the following pairs of parameters, and terminate the list with
2150 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2151 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2153 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2154 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2155 GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2156 GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2157 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2158 GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2159 GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2160 GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2161 GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2162 GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2163 GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2164 GUESTFS_ADD_DRIVE_OPTS_BLOCKSIZE, int blocksize,
2165 This function adds a disk image called filename to the handle.
2167 filename may be a regular host file or a host device.
2168 When this function is called before "guestfs_launch" (the usual case)
2170 then the first time you call this function, the disk appears in the API
2171 as /dev/sda, the second time as /dev/sdb, and so on.
2172 In libguestfs ≥ 1.20 you can also call this function after launch (with
2174 some restrictions). This is called "hotplugging". When hotplugging,
2175 you must specify a "label" so that the new disk gets a predictable
2176 name. For more information see "HOTPLUGGING".
2177 You don't necessarily need to be root when using libguestfs. However
2179 you obviously do need sufficient permissions to access the filename for
2180 whatever operations you want to perform (ie. read access if you just
2181 want to read the image or write access if you want to modify the
2182 image).
2183 This call checks that filename exists.
2185 filename may be the special string "/dev/null". See "NULL DISKS".
2187 The optional arguments are:
2189 "readonly"
2191 If true then the image is treated as read-only. Writes are still
2192 allowed, but they are stored in a temporary snapshot overlay which
2193 is discarded at the end. The disk that you add is not modified.
2194 "format"
2196 This forces the image format. If you omit this (or use
2197 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2198 automatically detected. Possible formats include "raw" and
2199 "qcow2".
2200 Automatic detection of the format opens you up to a potential
2202 security hole when dealing with untrusted raw-format images. See
2203 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
2204 security hole.
2205 "iface"
2207 This rarely-used option lets you emulate the behaviour of the
2208 deprecated "guestfs_add_drive_with_if" call (q.v.)
2209 "name"
2211 The name the drive had in the original guest, e.g. /dev/sdb. This
2212 is used as a hint to the guest inspection process if it is
2213 available.
2214 "label"
2216 Give the disk a label. The label should be a unique, short string
2217 using only ASCII characters "[a-zA-Z]". As well as its usual name
2218 in the API (such as /dev/sda), the drive will also be named
2219 /dev/disk/guestfs/label.
2220 See "DISK LABELS".
2222 "protocol"
2224 The optional protocol argument can be used to select an alternate
2225 source protocol.
2226 See also: "REMOTE STORAGE".
2228 "protocol = "file""
2230 filename is interpreted as a local file or device. This is the
2231 default if the optional protocol parameter is omitted.
2232 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
2234 Connect to a remote FTP, HTTP or TFTP server. The "server"
2235 parameter must also be supplied - see below.
2236 See also: "FTP, HTTP AND TFTP"
2238 "protocol = "gluster""
2240 Connect to the GlusterFS server. The "server" parameter must
2241 also be supplied - see below.
2242 See also: "GLUSTER"
2244 "protocol = "iscsi""
2246 Connect to the iSCSI server. The "server" parameter must also
2247 be supplied - see below. The "username" parameter may be
2248 supplied. See below. The "secret" parameter may be supplied.
2249 See below.
2250 See also: "ISCSI".
2252 "protocol = "nbd""
2254 Connect to the Network Block Device server. The "server"
2255 parameter must also be supplied - see below.
2256 See also: "NETWORK BLOCK DEVICE".
2258 "protocol = "rbd""
2260 Connect to the Ceph (librbd/RBD) server. The "server"
2261 parameter must also be supplied - see below. The "username"
2262 parameter may be supplied. See below. The "secret" parameter
2263 may be supplied. See below.
2264 See also: "CEPH".
2266 "protocol = "sheepdog""
2268 Connect to the Sheepdog server. The "server" parameter may
2269 also be supplied - see below.
2270 See also: "SHEEPDOG".
2272 "protocol = "ssh""
2274 Connect to the Secure Shell (ssh) server.
2275 The "server" parameter must be supplied. The "username"
2277 parameter may be supplied. See below.
2278 See also: "SSH".
2280 "server"
2282 For protocols which require access to a remote server, this is a
2283 list of server(s).
2284 Protocol Number of servers required
2286 -------- --------------------------
2287 file List must be empty or param not used at all
2288 ftp|ftps|http|https|tftp Exactly one
2289 gluster Exactly one
2290 iscsi Exactly one
2291 nbd Exactly one
2292 rbd Zero or more
2293 sheepdog Zero or more
2294 ssh Exactly one
2295 Each list element is a string specifying a server. The string must
2297 be in one of the following formats:
2298 hostname
2300 hostname:port
2301 tcp:hostname
2302 tcp:hostname:port
2303 unix:/path/to/socket
2304 If the port number is omitted, then the standard port number for
2306 the protocol is used (see /etc/services).
2307 "username"
2309 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
2310 "tftp" protocols, this specifies the remote username.
2311 If not given, then the local username is used for "ssh", and no
2313 authentication is attempted for ceph. But note this sometimes may
2314 give unexpected results, for example if using the libvirt backend
2315 and if the libvirt backend is configured to start the qemu
2316 appliance as a special user such as "qemu.qemu". If in doubt,
2317 specify the remote username you want.
2318 "secret"
2320 For the "rbd" protocol only, this specifies the ‘secret’ to use
2321 when connecting to the remote device. It must be base64 encoded.
2322 If not given, then a secret matching the given username will be
2324 looked up in the default keychain locations, or if no username is
2325 given, then no authentication will be used.
2326 "cachemode"
2328 Choose whether or not libguestfs will obey sync operations (safe
2329 but slow) or not (unsafe but fast). The possible values for this
2330 string are:
2331 "cachemode = "writeback""
2333 This is the default.
2334 Write operations in the API do not return until a write(2) call
2336 has completed in the host [but note this does not imply that
2337 anything gets written to disk].
2338 Sync operations in the API, including implicit syncs caused by
2340 filesystem journalling, will not return until an fdatasync(2)
2341 call has completed in the host, indicating that data has been
2342 committed to disk.
2343 "cachemode = "unsafe""
2345 In this mode, there are no guarantees. Libguestfs may cache
2346 anything and ignore sync requests. This is suitable only for
2347 scratch or temporary disks.
2348 "discard"
2350 Enable or disable discard (a.k.a. trim or unmap) support on this
2351 drive. If enabled, operations such as "guestfs_fstrim" will be
2352 able to discard / make thin / punch holes in the underlying host
2353 file or device.
2354 Possible discard settings are:
2356 "discard = "disable""
2358 Disable discard support. This is the default.
2359 "discard = "enable""
2361 Enable discard support. Fail if discard is not possible.
2362 "discard = "besteffort""
2364 Enable discard support if possible, but don't fail if it is not
2365 supported.
2366 Since not all backends and not all underlying systems support
2368 discard, this is a good choice if you want to use discard if
2369 possible, but don't mind if it doesn't work.
2370 "copyonread"
2372 The boolean parameter "copyonread" enables copy-on-read support.
2373 This only affects disk formats which have backing files, and causes
2374 reads to be stored in the overlay layer, speeding up multiple reads
2375 of the same area of disk.
2376 The default is false.
2378 "blocksize"
2380 This parameter sets the sector size of the disk. Possible values
2381 are 512 (the default if the parameter is omitted) or 4096. Use
2382 4096 when handling an "Advanced Format" disk that uses 4K sector
2383 size (https://en.wikipedia.org/wiki/Advanced_Format).
2384 Only a subset of the backends support this parameter (currently
2386 only the libvirt and direct backends do).
2387 This function returns 0 on success or -1 on error.
2389 (Added in 0.3)
2391 guestfs_add_drive_opts_va
2393 int
2394 guestfs_add_drive_opts_va (guestfs_h *g,
2395 const char *filename,
2396 va_list args);
2397 This is the "va_list variant" of "guestfs_add_drive_opts".
2399 See "CALLS WITH OPTIONAL ARGUMENTS".
2401 guestfs_add_drive_opts_argv
2403 int
2404 guestfs_add_drive_opts_argv (guestfs_h *g,
2405 const char *filename,
2406 const struct guestfs_add_drive_opts_argv *optargs);
2407 This is the "argv variant" of "guestfs_add_drive_opts".
2409 See "CALLS WITH OPTIONAL ARGUMENTS".
2411 guestfs_add_drive_ro
2413 int
2414 guestfs_add_drive_ro (guestfs_h *g,
2415 const char *filename);
2416 This function is the equivalent of calling "guestfs_add_drive_opts"
2418 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2419 so the disk is added read-only, with the format being detected
2420 automatically.
2421 This function returns 0 on success or -1 on error.
2423 (Added in 1.0.38)
2425 guestfs_add_drive_ro_with_if
2427 int
2428 guestfs_add_drive_ro_with_if (guestfs_h *g,
2429 const char *filename,
2430 const char *iface);
2431 This function is deprecated. In new code, use the "guestfs_add_drive"
2433 call instead.
2434 Deprecated functions will not be removed from the API, but the fact
2436 that they are deprecated indicates that there are problems with correct
2437 use of these functions.
2438 This is the same as "guestfs_add_drive_ro" but it allows you to specify
2440 the QEMU interface emulation to use at run time.
2441 This function returns 0 on success or -1 on error.
2443 (Added in 1.0.84)
2445 guestfs_add_drive_scratch
2447 int
2448 guestfs_add_drive_scratch (guestfs_h *g,
2449 int64_t size,
2450 ...);
2451 You may supply a list of optional arguments to this call. Use zero or
2453 more of the following pairs of parameters, and terminate the list with
2454 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2455 GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2457 GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2458 GUESTFS_ADD_DRIVE_SCRATCH_BLOCKSIZE, int blocksize,
2459 This command adds a temporary scratch drive to the handle. The "size"
2461 parameter is the virtual size (in bytes). The scratch drive is blank
2462 initially (all reads return zeroes until you start writing to it). The
2463 drive is deleted when the handle is closed.
2464 The optional arguments "name", "label" and "blocksize" are passed
2466 through to "guestfs_add_drive_opts".
2467 This function returns 0 on success or -1 on error.
2469 (Added in 1.23.10)
2471 guestfs_add_drive_scratch_va
2473 int
2474 guestfs_add_drive_scratch_va (guestfs_h *g,
2475 int64_t size,
2476 va_list args);
2477 This is the "va_list variant" of "guestfs_add_drive_scratch".
2479 See "CALLS WITH OPTIONAL ARGUMENTS".
2481 guestfs_add_drive_scratch_argv
2483 int
2484 guestfs_add_drive_scratch_argv (guestfs_h *g,
2485 int64_t size,
2486 const struct guestfs_add_drive_scratch_argv *optargs);
2487 This is the "argv variant" of "guestfs_add_drive_scratch".
2489 See "CALLS WITH OPTIONAL ARGUMENTS".
2491 guestfs_add_drive_with_if
2493 int
2494 guestfs_add_drive_with_if (guestfs_h *g,
2495 const char *filename,
2496 const char *iface);
2497 This function is deprecated. In new code, use the "guestfs_add_drive"
2499 call instead.
2500 Deprecated functions will not be removed from the API, but the fact
2502 that they are deprecated indicates that there are problems with correct
2503 use of these functions.
2504 This is the same as "guestfs_add_drive" but it allows you to specify
2506 the QEMU interface emulation to use at run time.
2507 This function returns 0 on success or -1 on error.
2509 (Added in 1.0.84)
2511 guestfs_add_libvirt_dom
2513 int
2514 guestfs_add_libvirt_dom (guestfs_h *g,
2515 void * /* really virDomainPtr */ dom,
2516 ...);
2517 You may supply a list of optional arguments to this call. Use zero or
2519 more of the following pairs of parameters, and terminate the list with
2520 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2521 GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2523 GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2524 GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2525 GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2526 GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2527 GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2528 GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2529 This function adds the disk(s) attached to the libvirt domain "dom".
2531 It works by requesting the domain XML from libvirt, parsing it for
2532 disks, and calling "guestfs_add_drive_opts" on each one.
2533 In the C API we declare "void *dom", but really it has type
2535 "virDomainPtr dom". This is so we don't need <libvirt.h>.
2536 The number of disks added is returned. This operation is atomic: if an
2538 error is returned, then no disks are added.
2539 This function does some minimal checks to make sure the libvirt domain
2541 is not running (unless "readonly" is true). In a future version we
2542 will try to acquire the libvirt lock on each disk.
2543 Disks must be accessible locally. This often means that adding disks
2545 from a remote libvirt connection (see https://libvirt.org/remote.html)
2546 will fail unless those disks are accessible via the same device path
2547 locally too.
2548 The optional "live" flag controls whether this call will try to connect
2550 to a running virtual machine "guestfsd" process if it sees a suitable
2551 <channel> element in the libvirt XML definition. The default (if the
2552 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
2553 for more information.
2554 The optional "readonlydisk" parameter controls what we do for disks
2556 which are marked <readonly/> in the libvirt XML. See
2557 "guestfs_add_domain" for possible values.
2558 If present, the value of "logical_block_size" attribute of <blockio/>
2560 tag in libvirt XML will be passed as "blocksize" parameter to
2561 "guestfs_add_drive_opts".
2562 The other optional parameters are passed directly through to
2564 "guestfs_add_drive_opts".
2565 On error this function returns -1.
2567 (Added in 1.29.14)
2569 guestfs_add_libvirt_dom_va
2571 int
2572 guestfs_add_libvirt_dom_va (guestfs_h *g,
2573 void * /* really virDomainPtr */ dom,
2574 va_list args);
2575 This is the "va_list variant" of "guestfs_add_libvirt_dom".
2577 See "CALLS WITH OPTIONAL ARGUMENTS".
2579 guestfs_add_libvirt_dom_argv
2581 int
2582 guestfs_add_libvirt_dom_argv (guestfs_h *g,
2583 void * /* really virDomainPtr */ dom,
2584 const struct guestfs_add_libvirt_dom_argv *optargs);
2585 This is the "argv variant" of "guestfs_add_libvirt_dom".
2587 See "CALLS WITH OPTIONAL ARGUMENTS".
2589 guestfs_aug_clear
2591 int
2592 guestfs_aug_clear (guestfs_h *g,
2593 const char *augpath);
2594 Set the value associated with "path" to "NULL". This is the same as
2596 the augtool(1) "clear" command.
2597 This function returns 0 on success or -1 on error.
2599 (Added in 1.3.4)
2601 guestfs_aug_close
2603 int
2604 guestfs_aug_close (guestfs_h *g);
2605 Close the current Augeas handle and free up any resources used by it.
2607 After calling this, you have to call "guestfs_aug_init" again before
2608 you can use any other Augeas functions.
2609 This function returns 0 on success or -1 on error.
2611 (Added in 0.7)
2613 guestfs_aug_defnode
2615 struct guestfs_int_bool *
2616 guestfs_aug_defnode (guestfs_h *g,
2617 const char *name,
2618 const char *expr,
2619 const char *val);
2620 Defines a variable "name" whose value is the result of evaluating
2622 "expr".
2623 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2625 to calling "guestfs_aug_set" "expr", "val". "name" will be the nodeset
2626 containing that single node.
2627 On success this returns a pair containing the number of nodes in the
2629 nodeset, and a boolean flag if a node was created.
2630 This function returns a "struct guestfs_int_bool *", or NULL if there
2632 was an error. The caller must call "guestfs_free_int_bool" after use.
2633 (Added in 0.7)
2635 guestfs_aug_defvar
2637 int
2638 guestfs_aug_defvar (guestfs_h *g,
2639 const char *name,
2640 const char *expr);
2641 Defines an Augeas variable "name" whose value is the result of
2643 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2644 On success this returns the number of nodes in "expr", or 0 if "expr"
2646 evaluates to something which is not a nodeset.
2647 On error this function returns -1.
2649 (Added in 0.7)
2651 guestfs_aug_get
2653 char *
2654 guestfs_aug_get (guestfs_h *g,
2655 const char *augpath);
2656 Look up the value associated with "path". If "path" matches exactly
2658 one node, the "value" is returned.
2659 This function returns a string, or NULL on error. The caller must free
2661 the returned string after use.
2662 (Added in 0.7)
2664 guestfs_aug_init
2666 int
2667 guestfs_aug_init (guestfs_h *g,
2668 const char *root,
2669 int flags);
2670 Create a new Augeas handle for editing configuration files. If there
2672 was any previous Augeas handle associated with this guestfs session,
2673 then it is closed.
2674 You must call this before using any other "guestfs_aug_*" commands.
2676 "root" is the filesystem root. "root" must not be NULL, use / instead.
2678 The flags are the same as the flags defined in <augeas.h>, the logical
2680 or of the following integers:
2681 "AUG_SAVE_BACKUP" = 1
2683 Keep the original file with a ".augsave" extension.
2684 "AUG_SAVE_NEWFILE" = 2
2686 Save changes into a file with extension ".augnew", and do not
2687 overwrite original. Overrides "AUG_SAVE_BACKUP".
2688 "AUG_TYPE_CHECK" = 4
2690 Typecheck lenses.
2691 This option is only useful when debugging Augeas lenses. Use of
2693 this option may require additional memory for the libguestfs
2694 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2695 environment variable or call "guestfs_set_memsize".
2696 "AUG_NO_STDINC" = 8
2698 Do not use standard load path for modules.
2699 "AUG_SAVE_NOOP" = 16
2701 Make save a no-op, just record what would have been changed.
2702 "AUG_NO_LOAD" = 32
2704 Do not load the tree in "guestfs_aug_init".
2705 To close the handle, you can call "guestfs_aug_close".
2707 To find out more about Augeas, see http://augeas.net/.
2709 This function returns 0 on success or -1 on error.
2711 (Added in 0.7)
2713 guestfs_aug_insert
2715 int
2716 guestfs_aug_insert (guestfs_h *g,
2717 const char *augpath,
2718 const char *label,
2719 int before);
2720 Create a new sibling "label" for "path", inserting it into the tree
2722 before or after "path" (depending on the boolean flag "before").
2723 "path" must match exactly one existing node in the tree, and "label"
2725 must be a label, ie. not contain /, "*" or end with a bracketed index
2726 "[N]".
2727 This function returns 0 on success or -1 on error.
2729 (Added in 0.7)
2731 guestfs_aug_label
2733 char *
2734 guestfs_aug_label (guestfs_h *g,
2735 const char *augpath);
2736 The label (name of the last element) of the Augeas path expression
2738 "augpath" is returned. "augpath" must match exactly one node, else
2739 this function returns an error.
2740 This function returns a string, or NULL on error. The caller must free
2742 the returned string after use.
2743 (Added in 1.23.14)
2745 guestfs_aug_load
2747 int
2748 guestfs_aug_load (guestfs_h *g);
2749 Load files into the tree.
2751 See "aug_load" in the Augeas documentation for the full gory details.
2753 This function returns 0 on success or -1 on error.
2755 (Added in 0.7)
2757 guestfs_aug_ls
2759 char **
2760 guestfs_aug_ls (guestfs_h *g,
2761 const char *augpath);
2762 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2764 sorting the resulting nodes into alphabetical order.
2765 This function returns a NULL-terminated array of strings (like
2767 environ(3)), or NULL if there was an error. The caller must free the
2768 strings and the array after use.
2769 (Added in 0.8)
2771 guestfs_aug_match
2773 char **
2774 guestfs_aug_match (guestfs_h *g,
2775 const char *augpath);
2776 Returns a list of paths which match the path expression "path". The
2778 returned paths are sufficiently qualified so that they match exactly
2779 one node in the current tree.
2780 This function returns a NULL-terminated array of strings (like
2782 environ(3)), or NULL if there was an error. The caller must free the
2783 strings and the array after use.
2784 (Added in 0.7)
2786 guestfs_aug_mv
2788 int
2789 guestfs_aug_mv (guestfs_h *g,
2790 const char *src,
2791 const char *dest);
2792 Move the node "src" to "dest". "src" must match exactly one node.
2794 "dest" is overwritten if it exists.
2795 This function returns 0 on success or -1 on error.
2797 (Added in 0.7)
2799 guestfs_aug_rm
2801 int
2802 guestfs_aug_rm (guestfs_h *g,
2803 const char *augpath);
2804 Remove "path" and all of its children.
2806 On success this returns the number of entries which were removed.
2808 On error this function returns -1.
2810 (Added in 0.7)
2812 guestfs_aug_save
2814 int
2815 guestfs_aug_save (guestfs_h *g);
2816 This writes all pending changes to disk.
2818 The flags which were passed to "guestfs_aug_init" affect exactly how
2820 files are saved.
2821 This function returns 0 on success or -1 on error.
2823 (Added in 0.7)
2825 guestfs_aug_set
2827 int
2828 guestfs_aug_set (guestfs_h *g,
2829 const char *augpath,
2830 const char *val);
2831 Set the value associated with "augpath" to "val".
2833 In the Augeas API, it is possible to clear a node by setting the value
2835 to NULL. Due to an oversight in the libguestfs API you cannot do that
2836 with this call. Instead you must use the "guestfs_aug_clear" call.
2837 This function returns 0 on success or -1 on error.
2839 (Added in 0.7)
2841 guestfs_aug_setm
2843 int
2844 guestfs_aug_setm (guestfs_h *g,
2845 const char *base,
2846 const char *sub,
2847 const char *val);
2848 Change multiple Augeas nodes in a single operation. "base" is an
2850 expression matching multiple nodes. "sub" is a path expression
2851 relative to "base". All nodes matching "base" are found, and then for
2852 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2853 which case the "base" nodes are modified.
2854 This returns the number of nodes modified.
2856 On error this function returns -1.
2858 (Added in 1.23.14)
2860 guestfs_aug_transform
2862 int
2863 guestfs_aug_transform (guestfs_h *g,
2864 const char *lens,
2865 const char *file,
2866 ...);
2867 You may supply a list of optional arguments to this call. Use zero or
2869 more of the following pairs of parameters, and terminate the list with
2870 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2871 GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2873 Add an Augeas transformation for the specified "lens" so it can handle
2875 "file".
2876 If "remove" is true ("false" by default), then the transformation is
2878 removed.
2879 This function returns 0 on success or -1 on error.
2881 (Added in 1.35.2)
2883 guestfs_aug_transform_va
2885 int
2886 guestfs_aug_transform_va (guestfs_h *g,
2887 const char *lens,
2888 const char *file,
2889 va_list args);
2890 This is the "va_list variant" of "guestfs_aug_transform".
2892 See "CALLS WITH OPTIONAL ARGUMENTS".
2894 guestfs_aug_transform_argv
2896 int
2897 guestfs_aug_transform_argv (guestfs_h *g,
2898 const char *lens,
2899 const char *file,
2900 const struct guestfs_aug_transform_argv *optargs);
2901 This is the "argv variant" of "guestfs_aug_transform".
2903 See "CALLS WITH OPTIONAL ARGUMENTS".
2905 guestfs_available
2907 int
2908 guestfs_available (guestfs_h *g,
2909 char *const *groups);
2910 This command is used to check the availability of some groups of
2912 functionality in the appliance, which not all builds of the libguestfs
2913 appliance will be able to provide.
2914 The libguestfs groups, and the functions that those groups correspond
2916 to, are listed in "AVAILABILITY". You can also fetch this list at
2917 runtime by calling "guestfs_available_all_groups".
2918 The argument "groups" is a list of group names, eg: "["inotify",
2920 "augeas"]" would check for the availability of the Linux inotify
2921 functions and Augeas (configuration file editing) functions.
2922 The command returns no error if all requested groups are available.
2924 It fails with an error if one or more of the requested groups is
2926 unavailable in the appliance.
2927 If an unknown group name is included in the list of groups then an
2929 error is always returned.
2930 Notes:
2932 · "guestfs_feature_available" is the same as this call, but with a
2934 slightly simpler to use API: that call returns a boolean true/false
2935 instead of throwing an error.
2936 · You must call "guestfs_launch" before calling this function.
2938 The reason is because we don't know what groups are supported by
2940 the appliance/daemon until it is running and can be queried.
2941 · If a group of functions is available, this does not necessarily
2943 mean that they will work. You still have to check for errors when
2944 calling individual API functions even if they are available.
2945 · It is usually the job of distro packagers to build complete
2947 functionality into the libguestfs appliance. Upstream libguestfs,
2948 if built from source with all requirements satisfied, will support
2949 everything.
2950 · This call was added in version 1.0.80. In previous versions of
2952 libguestfs all you could do would be to speculatively execute a
2953 command to find out if the daemon implemented it. See also
2954 "guestfs_version".
2955 See also "guestfs_filesystem_available".
2957 This function returns 0 on success or -1 on error.
2959 (Added in 1.0.80)
2961 guestfs_available_all_groups
2963 char **
2964 guestfs_available_all_groups (guestfs_h *g);
2965 This command returns a list of all optional groups that this daemon
2967 knows about. Note this returns both supported and unsupported groups.
2968 To find out which ones the daemon can actually support you have to call
2969 "guestfs_available" / "guestfs_feature_available" on each member of the
2970 returned list.
2971 See also "guestfs_available", "guestfs_feature_available" and
2973 "AVAILABILITY".
2974 This function returns a NULL-terminated array of strings (like
2976 environ(3)), or NULL if there was an error. The caller must free the
2977 strings and the array after use.
2978 (Added in 1.3.15)
2980 guestfs_base64_in
2982 int
2983 guestfs_base64_in (guestfs_h *g,
2984 const char *base64file,
2985 const char *filename);
2986 This command uploads base64-encoded data from "base64file" to filename.
2988 This function returns 0 on success or -1 on error.
2990 (Added in 1.3.5)
2992 guestfs_base64_out
2994 int
2995 guestfs_base64_out (guestfs_h *g,
2996 const char *filename,
2997 const char *base64file);
2998 This command downloads the contents of filename, writing it out to
3000 local file "base64file" encoded as base64.
3001 This function returns 0 on success or -1 on error.
3003 (Added in 1.3.5)
3005 guestfs_blkdiscard
3007 int
3008 guestfs_blkdiscard (guestfs_h *g,
3009 const char *device);
3010 This discards all blocks on the block device "device", giving the free
3012 space back to the host.
3013 This operation requires support in libguestfs, the host filesystem,
3015 qemu and the host kernel. If this support isn't present it may give an
3016 error or even appear to run but do nothing. You must also set the
3017 "discard" attribute on the underlying drive (see
3018 "guestfs_add_drive_opts").
3019 This function returns 0 on success or -1 on error.
3021 This function depends on the feature "blkdiscard". See also
3023 "guestfs_feature_available".
3024 (Added in 1.25.44)
3026 guestfs_blkdiscardzeroes
3028 int
3029 guestfs_blkdiscardzeroes (guestfs_h *g,
3030 const char *device);
3031 This call returns true if blocks on "device" that have been discarded
3033 by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
3034 when read the next time.
3035 If it returns false, then it may be that discarded blocks are read as
3037 stale or random data.
3038 This function returns a C truth value on success or -1 on error.
3040 This function depends on the feature "blkdiscardzeroes". See also
3042 "guestfs_feature_available".
3043 (Added in 1.25.44)
3045 guestfs_blkid
3047 char **
3048 guestfs_blkid (guestfs_h *g,
3049 const char *device);
3050 This command returns block device attributes for "device". The
3052 following fields are usually present in the returned hash. Other fields
3053 may also be present.
3054 "UUID"
3056 The uuid of this device.
3057 "LABEL"
3059 The label of this device.
3060 "VERSION"
3062 The version of blkid command.
3063 "TYPE"
3065 The filesystem type or RAID of this device.
3066 "USAGE"
3068 The usage of this device, for example "filesystem" or "raid".
3069 This function returns a NULL-terminated array of strings, or NULL if
3071 there was an error. The array of strings will always have length
3072 "2n+1", where "n" keys and values alternate, followed by the trailing
3073 NULL entry. The caller must free the strings and the array after use.
3074 (Added in 1.15.9)
3076 guestfs_blockdev_flushbufs
3078 int
3079 guestfs_blockdev_flushbufs (guestfs_h *g,
3080 const char *device);
3081 This tells the kernel to flush internal buffers associated with
3083 "device".
3084 This uses the blockdev(8) command.
3086 This function returns 0 on success or -1 on error.
3088 (Added in 1.9.3)
3090 guestfs_blockdev_getbsz
3092 int
3093 guestfs_blockdev_getbsz (guestfs_h *g,
3094 const char *device);
3095 This returns the block size of a device.
3097 Note: this is different from both size in blocks and filesystem block
3099 size. Also this setting is not really used by anything. You should
3100 probably not use it for anything. Filesystems have their own idea
3101 about what block size to choose.
3102 This uses the blockdev(8) command.
3104 On error this function returns -1.
3106 (Added in 1.9.3)
3108 guestfs_blockdev_getro
3110 int
3111 guestfs_blockdev_getro (guestfs_h *g,
3112 const char *device);
3113 Returns a boolean indicating if the block device is read-only (true if
3115 read-only, false if not).
3116 This uses the blockdev(8) command.
3118 This function returns a C truth value on success or -1 on error.
3120 (Added in 1.9.3)
3122 guestfs_blockdev_getsize64
3124 int64_t
3125 guestfs_blockdev_getsize64 (guestfs_h *g,
3126 const char *device);
3127 This returns the size of the device in bytes.
3129 See also "guestfs_blockdev_getsz".
3131 This uses the blockdev(8) command.
3133 On error this function returns -1.
3135 (Added in 1.9.3)
3137 guestfs_blockdev_getss
3139 int
3140 guestfs_blockdev_getss (guestfs_h *g,
3141 const char *device);
3142 This returns the size of sectors on a block device. Usually 512, but
3144 can be larger for modern devices.
3145 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
3147 for that).
3148 This uses the blockdev(8) command.
3150 On error this function returns -1.
3152 (Added in 1.9.3)
3154 guestfs_blockdev_getsz
3156 int64_t
3157 guestfs_blockdev_getsz (guestfs_h *g,
3158 const char *device);
3159 This returns the size of the device in units of 512-byte sectors (even
3161 if the sectorsize isn't 512 bytes ... weird).
3162 See also "guestfs_blockdev_getss" for the real sector size of the
3164 device, and "guestfs_blockdev_getsize64" for the more useful size in
3165 bytes.
3166 This uses the blockdev(8) command.
3168 On error this function returns -1.
3170 (Added in 1.9.3)
3172 guestfs_blockdev_rereadpt
3174 int
3175 guestfs_blockdev_rereadpt (guestfs_h *g,
3176 const char *device);
3177 Reread the partition table on "device".
3179 This uses the blockdev(8) command.
3181 This function returns 0 on success or -1 on error.
3183 (Added in 1.9.3)
3185 guestfs_blockdev_setbsz
3187 int
3188 guestfs_blockdev_setbsz (guestfs_h *g,
3189 const char *device,
3190 int blocksize);
3191 This function is deprecated. There is no replacement. Consult the API
3193 documentation in guestfs(3) for further information.
3194 Deprecated functions will not be removed from the API, but the fact
3196 that they are deprecated indicates that there are problems with correct
3197 use of these functions.
3198 This call does nothing and has never done anything because of a bug in
3200 blockdev. Do not use it.
3201 If you need to set the filesystem block size, use the "blocksize"
3203 option of "guestfs_mkfs".
3204 This function returns 0 on success or -1 on error.
3206 (Added in 1.9.3)
3208 guestfs_blockdev_setra
3210 int
3211 guestfs_blockdev_setra (guestfs_h *g,
3212 const char *device,
3213 int sectors);
3214 Set readahead (in 512-byte sectors) for the device.
3216 This uses the blockdev(8) command.
3218 This function returns 0 on success or -1 on error.
3220 (Added in 1.29.10)
3222 guestfs_blockdev_setro
3224 int
3225 guestfs_blockdev_setro (guestfs_h *g,
3226 const char *device);
3227 Sets the block device named "device" to read-only.
3229 This uses the blockdev(8) command.
3231 This function returns 0 on success or -1 on error.
3233 (Added in 1.9.3)
3235 guestfs_blockdev_setrw
3237 int
3238 guestfs_blockdev_setrw (guestfs_h *g,
3239 const char *device);
3240 Sets the block device named "device" to read-write.
3242 This uses the blockdev(8) command.
3244 This function returns 0 on success or -1 on error.
3246 (Added in 1.9.3)
3248 guestfs_btrfs_balance_cancel
3250 int
3251 guestfs_btrfs_balance_cancel (guestfs_h *g,
3252 const char *path);
3253 Cancel a running balance on a btrfs filesystem.
3255 This function returns 0 on success or -1 on error.
3257 This function depends on the feature "btrfs". See also
3259 "guestfs_feature_available".
3260 (Added in 1.29.22)
3262 guestfs_btrfs_balance_pause
3264 int
3265 guestfs_btrfs_balance_pause (guestfs_h *g,
3266 const char *path);
3267 Pause a running balance on a btrfs filesystem.
3269 This function returns 0 on success or -1 on error.
3271 This function depends on the feature "btrfs". See also
3273 "guestfs_feature_available".
3274 (Added in 1.29.22)
3276 guestfs_btrfs_balance_resume
3278 int
3279 guestfs_btrfs_balance_resume (guestfs_h *g,
3280 const char *path);
3281 Resume a paused balance on a btrfs filesystem.
3283 This function returns 0 on success or -1 on error.
3285 This function depends on the feature "btrfs". See also
3287 "guestfs_feature_available".
3288 (Added in 1.29.22)
3290 guestfs_btrfs_balance_status
3292 struct guestfs_btrfsbalance *
3293 guestfs_btrfs_balance_status (guestfs_h *g,
3294 const char *path);
3295 Show the status of a running or paused balance on a btrfs filesystem.
3297 This function returns a "struct guestfs_btrfsbalance *", or NULL if
3299 there was an error. The caller must call "guestfs_free_btrfsbalance"
3300 after use.
3301 This function depends on the feature "btrfs". See also
3303 "guestfs_feature_available".
3304 (Added in 1.29.26)
3306 guestfs_btrfs_device_add
3308 int
3309 guestfs_btrfs_device_add (guestfs_h *g,
3310 char *const *devices,
3311 const char *fs);
3312 Add the list of device(s) in "devices" to the btrfs filesystem mounted
3314 at "fs". If "devices" is an empty list, this does nothing.
3315 This function returns 0 on success or -1 on error.
3317 This function depends on the feature "btrfs". See also
3319 "guestfs_feature_available".
3320 (Added in 1.17.35)
3322 guestfs_btrfs_device_delete
3324 int
3325 guestfs_btrfs_device_delete (guestfs_h *g,
3326 char *const *devices,
3327 const char *fs);
3328 Remove the "devices" from the btrfs filesystem mounted at "fs". If
3330 "devices" is an empty list, this does nothing.
3331 This function returns 0 on success or -1 on error.
3333 This function depends on the feature "btrfs". See also
3335 "guestfs_feature_available".
3336 (Added in 1.17.35)
3338 guestfs_btrfs_filesystem_balance
3340 int
3341 guestfs_btrfs_filesystem_balance (guestfs_h *g,
3342 const char *fs);
3343 Balance the chunks in the btrfs filesystem mounted at "fs" across the
3345 underlying devices.
3346 This function returns 0 on success or -1 on error.
3348 This function depends on the feature "btrfs". See also
3350 "guestfs_feature_available".
3351 (Added in 1.17.35)
3353 guestfs_btrfs_filesystem_defragment
3355 int
3356 guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3357 const char *path,
3358 ...);
3359 You may supply a list of optional arguments to this call. Use zero or
3361 more of the following pairs of parameters, and terminate the list with
3362 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3363 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3365 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3366 Defragment a file or directory on a btrfs filesystem. compress is one
3368 of zlib or lzo.
3369 This function returns 0 on success or -1 on error.
3371 This function depends on the feature "btrfs". See also
3373 "guestfs_feature_available".
3374 (Added in 1.29.22)
3376 guestfs_btrfs_filesystem_defragment_va
3378 int
3379 guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3380 const char *path,
3381 va_list args);
3382 This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3384 See "CALLS WITH OPTIONAL ARGUMENTS".
3386 guestfs_btrfs_filesystem_defragment_argv
3388 int
3389 guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3390 const char *path,
3391 const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3392 This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3394 See "CALLS WITH OPTIONAL ARGUMENTS".
3396 guestfs_btrfs_filesystem_resize
3398 int
3399 guestfs_btrfs_filesystem_resize (guestfs_h *g,
3400 const char *mountpoint,
3401 ...);
3402 You may supply a list of optional arguments to this call. Use zero or
3404 more of the following pairs of parameters, and terminate the list with
3405 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3406 GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3408 This command resizes a btrfs filesystem.
3410 Note that unlike other resize calls, the filesystem has to be mounted
3412 and the parameter is the mountpoint not the device (this is a
3413 requirement of btrfs itself).
3414 The optional parameters are:
3416 "size"
3418 The new size (in bytes) of the filesystem. If omitted, the
3419 filesystem is resized to the maximum size.
3420 See also btrfs(8).
3422 This function returns 0 on success or -1 on error.
3424 This function depends on the feature "btrfs". See also
3426 "guestfs_feature_available".
3427 (Added in 1.11.17)
3429 guestfs_btrfs_filesystem_resize_va
3431 int
3432 guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3433 const char *mountpoint,
3434 va_list args);
3435 This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3437 See "CALLS WITH OPTIONAL ARGUMENTS".
3439 guestfs_btrfs_filesystem_resize_argv
3441 int
3442 guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3443 const char *mountpoint,
3444 const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3445 This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3447 See "CALLS WITH OPTIONAL ARGUMENTS".
3449 guestfs_btrfs_filesystem_show
3451 char **
3452 guestfs_btrfs_filesystem_show (guestfs_h *g,
3453 const char *device);
3454 Show all the devices where the filesystems in "device" is spanned over.
3456 If not all the devices for the filesystems are present, then this
3458 function fails and the "errno" is set to "ENODEV".
3459 This function returns a NULL-terminated array of strings (like
3461 environ(3)), or NULL if there was an error. The caller must free the
3462 strings and the array after use.
3463 This function depends on the feature "btrfs". See also
3465 "guestfs_feature_available".
3466 (Added in 1.33.29)
3468 guestfs_btrfs_filesystem_sync
3470 int
3471 guestfs_btrfs_filesystem_sync (guestfs_h *g,
3472 const char *fs);
3473 Force sync on the btrfs filesystem mounted at "fs".
3475 This function returns 0 on success or -1 on error.
3477 This function depends on the feature "btrfs". See also
3479 "guestfs_feature_available".
3480 (Added in 1.17.35)
3482 guestfs_btrfs_fsck
3484 int
3485 guestfs_btrfs_fsck (guestfs_h *g,
3486 const char *device,
3487 ...);
3488 You may supply a list of optional arguments to this call. Use zero or
3490 more of the following pairs of parameters, and terminate the list with
3491 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3492 GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3494 GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3495 Used to check a btrfs filesystem, "device" is the device file where the
3497 filesystem is stored.
3498 This function returns 0 on success or -1 on error.
3500 This function depends on the feature "btrfs". See also
3502 "guestfs_feature_available".
3503 (Added in 1.17.43)
3505 guestfs_btrfs_fsck_va
3507 int
3508 guestfs_btrfs_fsck_va (guestfs_h *g,
3509 const char *device,
3510 va_list args);
3511 This is the "va_list variant" of "guestfs_btrfs_fsck".
3513 See "CALLS WITH OPTIONAL ARGUMENTS".
3515 guestfs_btrfs_fsck_argv
3517 int
3518 guestfs_btrfs_fsck_argv (guestfs_h *g,
3519 const char *device,
3520 const struct guestfs_btrfs_fsck_argv *optargs);
3521 This is the "argv variant" of "guestfs_btrfs_fsck".
3523 See "CALLS WITH OPTIONAL ARGUMENTS".
3525 guestfs_btrfs_image
3527 int
3528 guestfs_btrfs_image (guestfs_h *g,
3529 char *const *source,
3530 const char *image,
3531 ...);
3532 You may supply a list of optional arguments to this call. Use zero or
3534 more of the following pairs of parameters, and terminate the list with
3535 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3536 GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3538 This is used to create an image of a btrfs filesystem. All data will
3540 be zeroed, but metadata and the like is preserved.
3541 This function returns 0 on success or -1 on error.
3543 This function depends on the feature "btrfs". See also
3545 "guestfs_feature_available".
3546 (Added in 1.29.32)
3548 guestfs_btrfs_image_va
3550 int
3551 guestfs_btrfs_image_va (guestfs_h *g,
3552 char *const *source,
3553 const char *image,
3554 va_list args);
3555 This is the "va_list variant" of "guestfs_btrfs_image".
3557 See "CALLS WITH OPTIONAL ARGUMENTS".
3559 guestfs_btrfs_image_argv
3561 int
3562 guestfs_btrfs_image_argv (guestfs_h *g,
3563 char *const *source,
3564 const char *image,
3565 const struct guestfs_btrfs_image_argv *optargs);
3566 This is the "argv variant" of "guestfs_btrfs_image".
3568 See "CALLS WITH OPTIONAL ARGUMENTS".
3570 guestfs_btrfs_qgroup_assign
3572 int
3573 guestfs_btrfs_qgroup_assign (guestfs_h *g,
3574 const char *src,
3575 const char *dst,
3576 const char *path);
3577 Add qgroup "src" to parent qgroup "dst". This command can group several
3579 qgroups into a parent qgroup to share common limit.
3580 This function returns 0 on success or -1 on error.
3582 This function depends on the feature "btrfs". See also
3584 "guestfs_feature_available".
3585 (Added in 1.29.17)
3587 guestfs_btrfs_qgroup_create
3589 int
3590 guestfs_btrfs_qgroup_create (guestfs_h *g,
3591 const char *qgroupid,
3592 const char *subvolume);
3593 Create a quota group (qgroup) for subvolume at "subvolume".
3595 This function returns 0 on success or -1 on error.
3597 This function depends on the feature "btrfs". See also
3599 "guestfs_feature_available".
3600 (Added in 1.29.17)
3602 guestfs_btrfs_qgroup_destroy
3604 int
3605 guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3606 const char *qgroupid,
3607 const char *subvolume);
3608 Destroy a quota group.
3610 This function returns 0 on success or -1 on error.
3612 This function depends on the feature "btrfs". See also
3614 "guestfs_feature_available".
3615 (Added in 1.29.17)
3617 guestfs_btrfs_qgroup_limit
3619 int
3620 guestfs_btrfs_qgroup_limit (guestfs_h *g,
3621 const char *subvolume,
3622 int64_t size);
3623 Limit the size of the subvolume with path "subvolume".
3625 This function returns 0 on success or -1 on error.
3627 This function depends on the feature "btrfs". See also
3629 "guestfs_feature_available".
3630 (Added in 1.29.17)
3632 guestfs_btrfs_qgroup_remove
3634 int
3635 guestfs_btrfs_qgroup_remove (guestfs_h *g,
3636 const char *src,
3637 const char *dst,
3638 const char *path);
3639 Remove qgroup "src" from the parent qgroup "dst".
3641 This function returns 0 on success or -1 on error.
3643 This function depends on the feature "btrfs". See also
3645 "guestfs_feature_available".
3646 (Added in 1.29.17)
3648 guestfs_btrfs_qgroup_show
3650 struct guestfs_btrfsqgroup_list *
3651 guestfs_btrfs_qgroup_show (guestfs_h *g,
3652 const char *path);
3653 Show all subvolume quota groups in a btrfs filesystem, including their
3655 usages.
3656 This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3658 there was an error. The caller must call
3659 "guestfs_free_btrfsqgroup_list" after use.
3660 This function depends on the feature "btrfs". See also
3662 "guestfs_feature_available".
3663 (Added in 1.29.17)
3665 guestfs_btrfs_quota_enable
3667 int
3668 guestfs_btrfs_quota_enable (guestfs_h *g,
3669 const char *fs,
3670 int enable);
3671 Enable or disable subvolume quota support for filesystem which contains
3673 "path".
3674 This function returns 0 on success or -1 on error.
3676 This function depends on the feature "btrfs". See also
3678 "guestfs_feature_available".
3679 (Added in 1.29.17)
3681 guestfs_btrfs_quota_rescan
3683 int
3684 guestfs_btrfs_quota_rescan (guestfs_h *g,
3685 const char *fs);
3686 Trash all qgroup numbers and scan the metadata again with the current
3688 config.
3689 This function returns 0 on success or -1 on error.
3691 This function depends on the feature "btrfs". See also
3693 "guestfs_feature_available".
3694 (Added in 1.29.17)
3696 guestfs_btrfs_replace
3698 int
3699 guestfs_btrfs_replace (guestfs_h *g,
3700 const char *srcdev,
3701 const char *targetdev,
3702 const char *mntpoint);
3703 Replace device of a btrfs filesystem. On a live filesystem, duplicate
3705 the data to the target device which is currently stored on the source
3706 device. After completion of the operation, the source device is wiped
3707 out and removed from the filesystem.
3708 The "targetdev" needs to be same size or larger than the "srcdev".
3710 Devices which are currently mounted are never allowed to be used as the
3711 "targetdev".
3712 This function returns 0 on success or -1 on error.
3714 This function depends on the feature "btrfs". See also
3716 "guestfs_feature_available".
3717 (Added in 1.29.48)
3719 guestfs_btrfs_rescue_chunk_recover
3721 int
3722 guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3723 const char *device);
3724 Recover the chunk tree of btrfs filesystem by scanning the devices one
3726 by one.
3727 This function returns 0 on success or -1 on error.
3729 This function depends on the feature "btrfs". See also
3731 "guestfs_feature_available".
3732 (Added in 1.29.22)
3734 guestfs_btrfs_rescue_super_recover
3736 int
3737 guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3738 const char *device);
3739 Recover bad superblocks from good copies.
3741 This function returns 0 on success or -1 on error.
3743 This function depends on the feature "btrfs". See also
3745 "guestfs_feature_available".
3746 (Added in 1.29.22)
3748 guestfs_btrfs_scrub_cancel
3750 int
3751 guestfs_btrfs_scrub_cancel (guestfs_h *g,
3752 const char *path);
3753 Cancel a running scrub on a btrfs filesystem.
3755 This function returns 0 on success or -1 on error.
3757 This function depends on the feature "btrfs". See also
3759 "guestfs_feature_available".
3760 (Added in 1.29.22)
3762 guestfs_btrfs_scrub_resume
3764 int
3765 guestfs_btrfs_scrub_resume (guestfs_h *g,
3766 const char *path);
3767 Resume a previously canceled or interrupted scrub on a btrfs
3769 filesystem.
3770 This function returns 0 on success or -1 on error.
3772 This function depends on the feature "btrfs". See also
3774 "guestfs_feature_available".
3775 (Added in 1.29.22)
3777 guestfs_btrfs_scrub_start
3779 int
3780 guestfs_btrfs_scrub_start (guestfs_h *g,
3781 const char *path);
3782 Reads all the data and metadata on the filesystem, and uses checksums
3784 and the duplicate copies from RAID storage to identify and repair any
3785 corrupt data.
3786 This function returns 0 on success or -1 on error.
3788 This function depends on the feature "btrfs". See also
3790 "guestfs_feature_available".
3791 (Added in 1.29.22)
3793 guestfs_btrfs_scrub_status
3795 struct guestfs_btrfsscrub *
3796 guestfs_btrfs_scrub_status (guestfs_h *g,
3797 const char *path);
3798 Show status of running or finished scrub on a btrfs filesystem.
3800 This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3802 was an error. The caller must call "guestfs_free_btrfsscrub" after
3803 use.
3804 This function depends on the feature "btrfs". See also
3806 "guestfs_feature_available".
3807 (Added in 1.29.26)
3809 guestfs_btrfs_set_seeding
3811 int
3812 guestfs_btrfs_set_seeding (guestfs_h *g,
3813 const char *device,
3814 int seeding);
3815 Enable or disable the seeding feature of a device that contains a btrfs
3817 filesystem.
3818 This function returns 0 on success or -1 on error.
3820 This function depends on the feature "btrfs". See also
3822 "guestfs_feature_available".
3823 (Added in 1.17.43)
3825 guestfs_btrfs_subvolume_create
3827 int
3828 guestfs_btrfs_subvolume_create (guestfs_h *g,
3829 const char *dest);
3830 This function is provided for backwards compatibility with earlier
3832 versions of libguestfs. It simply calls
3833 "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3834 (Added in 1.17.35)
3836 guestfs_btrfs_subvolume_create_opts
3838 int
3839 guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3840 const char *dest,
3841 ...);
3842 You may supply a list of optional arguments to this call. Use zero or
3844 more of the following pairs of parameters, and terminate the list with
3845 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3846 GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3848 Create a btrfs subvolume. The "dest" argument is the destination
3850 directory and the name of the subvolume, in the form
3851 /path/to/dest/name. The optional parameter "qgroupid" represents the
3852 qgroup which the newly created subvolume will be added to.
3853 This function returns 0 on success or -1 on error.
3855 This function depends on the feature "btrfs". See also
3857 "guestfs_feature_available".
3858 (Added in 1.17.35)
3860 guestfs_btrfs_subvolume_create_opts_va
3862 int
3863 guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3864 const char *dest,
3865 va_list args);
3866 This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3868 See "CALLS WITH OPTIONAL ARGUMENTS".
3870 guestfs_btrfs_subvolume_create_opts_argv
3872 int
3873 guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3874 const char *dest,
3875 const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3876 This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3878 See "CALLS WITH OPTIONAL ARGUMENTS".
3880 guestfs_btrfs_subvolume_delete
3882 int
3883 guestfs_btrfs_subvolume_delete (guestfs_h *g,
3884 const char *subvolume);
3885 Delete the named btrfs subvolume or snapshot.
3887 This function returns 0 on success or -1 on error.
3889 This function depends on the feature "btrfs". See also
3891 "guestfs_feature_available".
3892 (Added in 1.17.35)
3894 guestfs_btrfs_subvolume_get_default
3896 int64_t
3897 guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3898 const char *fs);
3899 Get the default subvolume or snapshot of a filesystem mounted at
3901 "mountpoint".
3902 On error this function returns -1.
3904 This function depends on the feature "btrfs". See also
3906 "guestfs_feature_available".
3907 (Added in 1.29.17)
3909 guestfs_btrfs_subvolume_list
3911 struct guestfs_btrfssubvolume_list *
3912 guestfs_btrfs_subvolume_list (guestfs_h *g,
3913 const char *fs);
3914 List the btrfs snapshots and subvolumes of the btrfs filesystem which
3916 is mounted at "fs".
3917 This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3919 if there was an error. The caller must call
3920 "guestfs_free_btrfssubvolume_list" after use.
3921 This function depends on the feature "btrfs". See also
3923 "guestfs_feature_available".
3924 (Added in 1.17.35)
3926 guestfs_btrfs_subvolume_set_default
3928 int
3929 guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3930 int64_t id,
3931 const char *fs);
3932 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3934 default. See "guestfs_btrfs_subvolume_list" to get a list of
3935 subvolumes.
3936 This function returns 0 on success or -1 on error.
3938 This function depends on the feature "btrfs". See also
3940 "guestfs_feature_available".
3941 (Added in 1.17.35)
3943 guestfs_btrfs_subvolume_show
3945 char **
3946 guestfs_btrfs_subvolume_show (guestfs_h *g,
3947 const char *subvolume);
3948 Return detailed information of the subvolume.
3950 This function returns a NULL-terminated array of strings, or NULL if
3952 there was an error. The array of strings will always have length
3953 "2n+1", where "n" keys and values alternate, followed by the trailing
3954 NULL entry. The caller must free the strings and the array after use.
3955 This function depends on the feature "btrfs". See also
3957 "guestfs_feature_available".
3958 (Added in 1.29.17)
3960 guestfs_btrfs_subvolume_snapshot
3962 int
3963 guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3964 const char *source,
3965 const char *dest);
3966 This function is provided for backwards compatibility with earlier
3968 versions of libguestfs. It simply calls
3969 "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3970 (Added in 1.17.35)
3972 guestfs_btrfs_subvolume_snapshot_opts
3974 int
3975 guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3976 const char *source,
3977 const char *dest,
3978 ...);
3979 You may supply a list of optional arguments to this call. Use zero or
3981 more of the following pairs of parameters, and terminate the list with
3982 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3983 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3985 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3986 Create a snapshot of the btrfs subvolume "source". The "dest" argument
3988 is the destination directory and the name of the snapshot, in the form
3989 /path/to/dest/name. By default the newly created snapshot is writable,
3990 if the value of optional parameter "ro" is true, then a readonly
3991 snapshot is created. The optional parameter "qgroupid" represents the
3992 qgroup which the newly created snapshot will be added to.
3993 This function returns 0 on success or -1 on error.
3995 This function depends on the feature "btrfs". See also
3997 "guestfs_feature_available".
3998 (Added in 1.17.35)
4000 guestfs_btrfs_subvolume_snapshot_opts_va
4002 int
4003 guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
4004 const char *source,
4005 const char *dest,
4006 va_list args);
4007 This is the "va_list variant" of
4009 "guestfs_btrfs_subvolume_snapshot_opts".
4010 See "CALLS WITH OPTIONAL ARGUMENTS".
4012 guestfs_btrfs_subvolume_snapshot_opts_argv
4014 int
4015 guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
4016 const char *source,
4017 const char *dest,
4018 const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
4019 This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
4021 See "CALLS WITH OPTIONAL ARGUMENTS".
4023 guestfs_btrfstune_enable_extended_inode_refs
4025 int
4026 guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
4027 const char *device);
4028 This will Enable extended inode refs.
4030 This function returns 0 on success or -1 on error.
4032 This function depends on the feature "btrfs". See also
4034 "guestfs_feature_available".
4035 (Added in 1.29.29)
4037 guestfs_btrfstune_enable_skinny_metadata_extent_refs
4039 int
4040 guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
4041 const char *device);
4042 This enable skinny metadata extent refs.
4044 This function returns 0 on success or -1 on error.
4046 This function depends on the feature "btrfs". See also
4048 "guestfs_feature_available".
4049 (Added in 1.29.29)
4051 guestfs_btrfstune_seeding
4053 int
4054 guestfs_btrfstune_seeding (guestfs_h *g,
4055 const char *device,
4056 int seeding);
4057 Enable seeding of a btrfs device, this will force a fs readonly so that
4059 you can use it to build other filesystems.
4060 This function returns 0 on success or -1 on error.
4062 This function depends on the feature "btrfs". See also
4064 "guestfs_feature_available".
4065 (Added in 1.29.29)
4067 guestfs_c_pointer
4069 int64_t
4070 guestfs_c_pointer (guestfs_h *g);
4071 In non-C language bindings, this allows you to retrieve the underlying
4073 C pointer to the handle (ie. "guestfs_h *"). The purpose of this is to
4074 allow other libraries to interwork with libguestfs.
4075 On error this function returns -1.
4077 (Added in 1.29.17)
4079 guestfs_canonical_device_name
4081 char *
4082 guestfs_canonical_device_name (guestfs_h *g,
4083 const char *device);
4084 This utility function is useful when displaying device names to the
4086 user. It takes a number of irregular device names and returns them in
4087 a consistent format:
4088 /dev/hdX
4090 /dev/vdX
4091 These are returned as /dev/sdX. Note this works for device names
4092 and partition names. This is approximately the reverse of the
4093 algorithm described in "BLOCK DEVICE NAMING".
4094 /dev/mapper/VG-LV
4096 /dev/dm-N
4097 Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
4098 Other strings are returned unmodified.
4100 This function returns a string, or NULL on error. The caller must free
4102 the returned string after use.
4103 (Added in 1.19.7)
4105 guestfs_cap_get_file
4107 char *
4108 guestfs_cap_get_file (guestfs_h *g,
4109 const char *path);
4110 This function returns the Linux capabilities attached to "path". The
4112 capabilities set is returned in text form (see cap_to_text(3)).
4113 If no capabilities are attached to a file, an empty string is returned.
4115 This function returns a string, or NULL on error. The caller must free
4117 the returned string after use.
4118 This function depends on the feature "linuxcaps". See also
4120 "guestfs_feature_available".
4121 (Added in 1.19.63)
4123 guestfs_cap_set_file
4125 int
4126 guestfs_cap_set_file (guestfs_h *g,
4127 const char *path,
4128 const char *cap);
4129 This function sets the Linux capabilities attached to "path". The
4131 capabilities set "cap" should be passed in text form (see
4132 cap_from_text(3)).
4133 This function returns 0 on success or -1 on error.
4135 This function depends on the feature "linuxcaps". See also
4137 "guestfs_feature_available".
4138 (Added in 1.19.63)
4140 guestfs_case_sensitive_path
4142 char *
4143 guestfs_case_sensitive_path (guestfs_h *g,
4144 const char *path);
4145 This can be used to resolve case insensitive paths on a filesystem
4147 which is case sensitive. The use case is to resolve paths which you
4148 have read from Windows configuration files or the Windows Registry, to
4149 the true path.
4150 The command handles a peculiarity of the Linux ntfs-3g filesystem
4152 driver (and probably others), which is that although the underlying
4153 filesystem is case-insensitive, the driver exports the filesystem to
4154 Linux as case-sensitive.
4155 One consequence of this is that special directories such as C:\windows
4157 may appear as /WINDOWS or /windows (or other things) depending on the
4158 precise details of how they were created. In Windows itself this would
4159 not be a problem.
4160 Bug or feature? You decide:
4162 https://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4163 "guestfs_case_sensitive_path" attempts to resolve the true case of each
4165 element in the path. It will return a resolved path if either the full
4166 path or its parent directory exists. If the parent directory exists but
4167 the full path does not, the case of the parent directory will be
4168 correctly resolved, and the remainder appended unmodified. For example,
4169 if the file "/Windows/System32/netkvm.sys" exists:
4170 "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4172 "Windows/System32/netkvm.sys"
4173 "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4175 "Windows/System32/NoSuchFile"
4176 "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4178 ERROR
4179 Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4181 cannot be used to check for the existence of a file.
4182 Note: This function does not handle drive names, backslashes etc.
4184 See also "guestfs_realpath".
4186 This function returns a string, or NULL on error. The caller must free
4188 the returned string after use.
4189 (Added in 1.0.75)
4191 guestfs_cat
4193 char *
4194 guestfs_cat (guestfs_h *g,
4195 const char *path);
4196 Return the contents of the file named "path".
4198 Because, in C, this function returns a "char *", there is no way to
4200 differentiate between a "\0" character in a file and end of string. To
4201 handle binary files, use the "guestfs_read_file" or "guestfs_download"
4202 functions.
4203 This function returns a string, or NULL on error. The caller must free
4205 the returned string after use.
4206 (Added in 0.4)
4208 guestfs_checksum
4210 char *
4211 guestfs_checksum (guestfs_h *g,
4212 const char *csumtype,
4213 const char *path);
4214 This call computes the MD5, SHAx or CRC checksum of the file named
4216 "path".
4217 The type of checksum to compute is given by the "csumtype" parameter
4219 which must have one of the following values:
4220 "crc"
4222 Compute the cyclic redundancy check (CRC) specified by POSIX for
4223 the "cksum" command.
4224 "md5"
4226 Compute the MD5 hash (using the md5sum(1) program).
4227 "sha1"
4229 Compute the SHA1 hash (using the sha1sum(1) program).
4230 "sha224"
4232 Compute the SHA224 hash (using the sha224sum(1) program).
4233 "sha256"
4235 Compute the SHA256 hash (using the sha256sum(1) program).
4236 "sha384"
4238 Compute the SHA384 hash (using the sha384sum(1) program).
4239 "sha512"
4241 Compute the SHA512 hash (using the sha512sum(1) program).
4242 The checksum is returned as a printable string.
4244 To get the checksum for a device, use "guestfs_checksum_device".
4246 To get the checksums for many files, use "guestfs_checksums_out".
4248 This function returns a string, or NULL on error. The caller must free
4250 the returned string after use.
4251 (Added in 1.0.2)
4253 guestfs_checksum_device
4255 char *
4256 guestfs_checksum_device (guestfs_h *g,
4257 const char *csumtype,
4258 const char *device);
4259 This call computes the MD5, SHAx or CRC checksum of the contents of the
4261 device named "device". For the types of checksums supported see the
4262 "guestfs_checksum" command.
4263 This function returns a string, or NULL on error. The caller must free
4265 the returned string after use.
4266 (Added in 1.3.2)
4268 guestfs_checksums_out
4270 int
4271 guestfs_checksums_out (guestfs_h *g,
4272 const char *csumtype,
4273 const char *directory,
4274 const char *sumsfile);
4275 This command computes the checksums of all regular files in directory
4277 and then emits a list of those checksums to the local output file
4278 "sumsfile".
4279 This can be used for verifying the integrity of a virtual machine.
4281 However to be properly secure you should pay attention to the output of
4282 the checksum command (it uses the ones from GNU coreutils). In
4283 particular when the filename is not printable, coreutils uses a special
4284 backslash syntax. For more information, see the GNU coreutils info
4285 file.
4286 This function returns 0 on success or -1 on error.
4288 (Added in 1.3.7)
4290 guestfs_chmod
4292 int
4293 guestfs_chmod (guestfs_h *g,
4294 int mode,
4295 const char *path);
4296 Change the mode (permissions) of "path" to "mode". Only numeric modes
4298 are supported.
4299 Note: When using this command from guestfish, "mode" by default would
4301 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4302 700.
4303 The mode actually set is affected by the umask.
4305 This function returns 0 on success or -1 on error.
4307 (Added in 0.8)
4309 guestfs_chown
4311 int
4312 guestfs_chown (guestfs_h *g,
4313 int owner,
4314 int group,
4315 const char *path);
4316 Change the file owner to "owner" and group to "group".
4318 Only numeric uid and gid are supported. If you want to use names, you
4320 will need to locate and parse the password file yourself (Augeas
4321 support makes this relatively easy).
4322 This function returns 0 on success or -1 on error.
4324 (Added in 0.8)
4326 guestfs_clear_backend_setting
4328 int
4329 guestfs_clear_backend_setting (guestfs_h *g,
4330 const char *name);
4331 If there is a backend setting string matching "name" or beginning with
4333 "name=", then that string is removed from the backend settings.
4334 This call returns the number of strings which were removed (which may
4336 be 0, 1 or greater than 1).
4337 See "BACKEND", "BACKEND SETTINGS".
4339 On error this function returns -1.
4341 (Added in 1.27.2)
4343 guestfs_command
4345 char *
4346 guestfs_command (guestfs_h *g,
4347 char *const *arguments);
4348 This call runs a command from the guest filesystem. The filesystem
4350 must be mounted, and must contain a compatible operating system (ie.
4351 something Linux, with the same or compatible processor architecture).
4352 The single parameter is an argv-style list of arguments. The first
4354 element is the name of the program to run. Subsequent elements are
4355 parameters. The list must be non-empty (ie. must contain a program
4356 name). Note that the command runs directly, and is not invoked via the
4357 shell (see "guestfs_sh").
4358 The return value is anything printed to stdout by the command.
4360 If the command returns a non-zero exit status, then this function
4362 returns an error message. The error message string is the content of
4363 stderr from the command.
4364 The $PATH environment variable will contain at least /usr/bin and /bin.
4366 If you require a program from another location, you should provide the
4367 full path in the first parameter.
4368 Shared libraries and data files required by the program must be
4370 available on filesystems which are mounted in the correct places. It
4371 is the caller’s responsibility to ensure all filesystems that are
4372 needed are mounted at the right locations.
4373 This function returns a string, or NULL on error. The caller must free
4375 the returned string after use.
4376 Because of the message protocol, there is a transfer limit of somewhere
4378 between 2MB and 4MB. See "PROTOCOL LIMITS".
4379 (Added in 1.9.1)
4381 guestfs_command_lines
4383 char **
4384 guestfs_command_lines (guestfs_h *g,
4385 char *const *arguments);
4386 This is the same as "guestfs_command", but splits the result into a
4388 list of lines.
4389 See also: "guestfs_sh_lines"
4391 This function returns a NULL-terminated array of strings (like
4393 environ(3)), or NULL if there was an error. The caller must free the
4394 strings and the array after use.
4395 Because of the message protocol, there is a transfer limit of somewhere
4397 between 2MB and 4MB. See "PROTOCOL LIMITS".
4398 (Added in 1.9.1)
4400 guestfs_compress_device_out
4402 int
4403 guestfs_compress_device_out (guestfs_h *g,
4404 const char *ctype,
4405 const char *device,
4406 const char *zdevice,
4407 ...);
4408 You may supply a list of optional arguments to this call. Use zero or
4410 more of the following pairs of parameters, and terminate the list with
4411 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4412 GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4414 This command compresses "device" and writes it out to the local file
4416 "zdevice".
4417 The "ctype" and optional "level" parameters have the same meaning as in
4419 "guestfs_compress_out".
4420 This function returns 0 on success or -1 on error.
4422 (Added in 1.13.15)
4424 guestfs_compress_device_out_va
4426 int
4427 guestfs_compress_device_out_va (guestfs_h *g,
4428 const char *ctype,
4429 const char *device,
4430 const char *zdevice,
4431 va_list args);
4432 This is the "va_list variant" of "guestfs_compress_device_out".
4434 See "CALLS WITH OPTIONAL ARGUMENTS".
4436 guestfs_compress_device_out_argv
4438 int
4439 guestfs_compress_device_out_argv (guestfs_h *g,
4440 const char *ctype,
4441 const char *device,
4442 const char *zdevice,
4443 const struct guestfs_compress_device_out_argv *optargs);
4444 This is the "argv variant" of "guestfs_compress_device_out".
4446 See "CALLS WITH OPTIONAL ARGUMENTS".
4448 guestfs_compress_out
4450 int
4451 guestfs_compress_out (guestfs_h *g,
4452 const char *ctype,
4453 const char *file,
4454 const char *zfile,
4455 ...);
4456 You may supply a list of optional arguments to this call. Use zero or
4458 more of the following pairs of parameters, and terminate the list with
4459 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4460 GUESTFS_COMPRESS_OUT_LEVEL, int level,
4462 This command compresses file and writes it out to the local file zfile.
4464 The compression program used is controlled by the "ctype" parameter.
4466 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4467 Some compression types may not be supported by particular builds of
4468 libguestfs, in which case you will get an error containing the
4469 substring "not supported".
4470 The optional "level" parameter controls compression level. The meaning
4472 and default for this parameter depends on the compression program being
4473 used.
4474 This function returns 0 on success or -1 on error.
4476 (Added in 1.13.15)
4478 guestfs_compress_out_va
4480 int
4481 guestfs_compress_out_va (guestfs_h *g,
4482 const char *ctype,
4483 const char *file,
4484 const char *zfile,
4485 va_list args);
4486 This is the "va_list variant" of "guestfs_compress_out".
4488 See "CALLS WITH OPTIONAL ARGUMENTS".
4490 guestfs_compress_out_argv
4492 int
4493 guestfs_compress_out_argv (guestfs_h *g,
4494 const char *ctype,
4495 const char *file,
4496 const char *zfile,
4497 const struct guestfs_compress_out_argv *optargs);
4498 This is the "argv variant" of "guestfs_compress_out".
4500 See "CALLS WITH OPTIONAL ARGUMENTS".
4502 guestfs_config
4504 int
4505 guestfs_config (guestfs_h *g,
4506 const char *hvparam,
4507 const char *hvvalue);
4508 This can be used to add arbitrary hypervisor parameters of the form
4510 -param value. Actually it’s not quite arbitrary - we prevent you from
4511 setting some parameters which would interfere with parameters that we
4512 use.
4513 The first character of "hvparam" string must be a "-" (dash).
4515 "hvvalue" can be NULL.
4517 This function returns 0 on success or -1 on error.
4519 (Added in 0.3)
4521 guestfs_copy_attributes
4523 int
4524 guestfs_copy_attributes (guestfs_h *g,
4525 const char *src,
4526 const char *dest,
4527 ...);
4528 You may supply a list of optional arguments to this call. Use zero or
4530 more of the following pairs of parameters, and terminate the list with
4531 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4532 GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4534 GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4535 GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4536 GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4537 Copy the attributes of a path (which can be a file or a directory) to
4539 another path.
4540 By default no attribute is copied, so make sure to specify any (or
4542 "all" to copy everything).
4543 The optional arguments specify which attributes can be copied:
4545 "mode"
4547 Copy part of the file mode from "source" to "destination". Only the
4548 UNIX permissions and the sticky/setuid/setgid bits can be copied.
4549 "xattributes"
4551 Copy the Linux extended attributes (xattrs) from "source" to
4552 "destination". This flag does nothing if the linuxxattrs feature
4553 is not available (see "guestfs_feature_available").
4554 "ownership"
4556 Copy the owner uid and the group gid of "source" to "destination".
4557 "all"
4559 Copy all the attributes from "source" to "destination". Enabling it
4560 enables all the other flags, if they are not specified already.
4561 This function returns 0 on success or -1 on error.
4563 (Added in 1.25.21)
4565 guestfs_copy_attributes_va
4567 int
4568 guestfs_copy_attributes_va (guestfs_h *g,
4569 const char *src,
4570 const char *dest,
4571 va_list args);
4572 This is the "va_list variant" of "guestfs_copy_attributes".
4574 See "CALLS WITH OPTIONAL ARGUMENTS".
4576 guestfs_copy_attributes_argv
4578 int
4579 guestfs_copy_attributes_argv (guestfs_h *g,
4580 const char *src,
4581 const char *dest,
4582 const struct guestfs_copy_attributes_argv *optargs);
4583 This is the "argv variant" of "guestfs_copy_attributes".
4585 See "CALLS WITH OPTIONAL ARGUMENTS".
4587 guestfs_copy_device_to_device
4589 int
4590 guestfs_copy_device_to_device (guestfs_h *g,
4591 const char *src,
4592 const char *dest,
4593 ...);
4594 You may supply a list of optional arguments to this call. Use zero or
4596 more of the following pairs of parameters, and terminate the list with
4597 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4598 GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4600 GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4601 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4602 GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4603 GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4604 The four calls "guestfs_copy_device_to_device",
4606 "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4607 "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4608 a destination (device|file).
4609 Partial copies can be made since you can specify optionally the source
4611 offset, destination offset and size to copy. These values are all
4612 specified in bytes. If not given, the offsets both default to zero,
4613 and the size defaults to copying as much as possible until we hit the
4614 end of the source.
4615 The source and destination may be the same object. However overlapping
4617 regions may not be copied correctly.
4618 If the destination is a file, it is created if required. If the
4620 destination file is not large enough, it is extended.
4621 If the destination is a file and the "append" flag is not set, then the
4623 destination file is truncated. If the "append" flag is set, then the
4624 copy appends to the destination file. The "append" flag currently
4625 cannot be set for devices.
4626 If the "sparse" flag is true then the call avoids writing blocks that
4628 contain only zeroes, which can help in some situations where the
4629 backing disk is thin-provisioned. Note that unless the target is
4630 already zeroed, using this option will result in incorrect copying.
4631 This function returns 0 on success or -1 on error.
4633 This long-running command can generate progress notification messages
4635 so that the caller can display a progress bar or indicator. To receive
4636 these messages, the caller must register a progress event callback.
4637 See "GUESTFS_EVENT_PROGRESS".
4638 (Added in 1.13.25)
4640 guestfs_copy_device_to_device_va
4642 int
4643 guestfs_copy_device_to_device_va (guestfs_h *g,
4644 const char *src,
4645 const char *dest,
4646 va_list args);
4647 This is the "va_list variant" of "guestfs_copy_device_to_device".
4649 See "CALLS WITH OPTIONAL ARGUMENTS".
4651 guestfs_copy_device_to_device_argv
4653 int
4654 guestfs_copy_device_to_device_argv (guestfs_h *g,
4655 const char *src,
4656 const char *dest,
4657 const struct guestfs_copy_device_to_device_argv *optargs);
4658 This is the "argv variant" of "guestfs_copy_device_to_device".
4660 See "CALLS WITH OPTIONAL ARGUMENTS".
4662 guestfs_copy_device_to_file
4664 int
4665 guestfs_copy_device_to_file (guestfs_h *g,
4666 const char *src,
4667 const char *dest,
4668 ...);
4669 You may supply a list of optional arguments to this call. Use zero or
4671 more of the following pairs of parameters, and terminate the list with
4672 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4673 GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4675 GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4676 GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4677 GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4678 GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4679 See "guestfs_copy_device_to_device" for a general overview of this
4681 call.
4682 This function returns 0 on success or -1 on error.
4684 This long-running command can generate progress notification messages
4686 so that the caller can display a progress bar or indicator. To receive
4687 these messages, the caller must register a progress event callback.
4688 See "GUESTFS_EVENT_PROGRESS".
4689 (Added in 1.13.25)
4691 guestfs_copy_device_to_file_va
4693 int
4694 guestfs_copy_device_to_file_va (guestfs_h *g,
4695 const char *src,
4696 const char *dest,
4697 va_list args);
4698 This is the "va_list variant" of "guestfs_copy_device_to_file".
4700 See "CALLS WITH OPTIONAL ARGUMENTS".
4702 guestfs_copy_device_to_file_argv
4704 int
4705 guestfs_copy_device_to_file_argv (guestfs_h *g,
4706 const char *src,
4707 const char *dest,
4708 const struct guestfs_copy_device_to_file_argv *optargs);
4709 This is the "argv variant" of "guestfs_copy_device_to_file".
4711 See "CALLS WITH OPTIONAL ARGUMENTS".
4713 guestfs_copy_file_to_device
4715 int
4716 guestfs_copy_file_to_device (guestfs_h *g,
4717 const char *src,
4718 const char *dest,
4719 ...);
4720 You may supply a list of optional arguments to this call. Use zero or
4722 more of the following pairs of parameters, and terminate the list with
4723 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4724 GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4726 GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4727 GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4728 GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4729 GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4730 See "guestfs_copy_device_to_device" for a general overview of this
4732 call.
4733 This function returns 0 on success or -1 on error.
4735 This long-running command can generate progress notification messages
4737 so that the caller can display a progress bar or indicator. To receive
4738 these messages, the caller must register a progress event callback.
4739 See "GUESTFS_EVENT_PROGRESS".
4740 (Added in 1.13.25)
4742 guestfs_copy_file_to_device_va
4744 int
4745 guestfs_copy_file_to_device_va (guestfs_h *g,
4746 const char *src,
4747 const char *dest,
4748 va_list args);
4749 This is the "va_list variant" of "guestfs_copy_file_to_device".
4751 See "CALLS WITH OPTIONAL ARGUMENTS".
4753 guestfs_copy_file_to_device_argv
4755 int
4756 guestfs_copy_file_to_device_argv (guestfs_h *g,
4757 const char *src,
4758 const char *dest,
4759 const struct guestfs_copy_file_to_device_argv *optargs);
4760 This is the "argv variant" of "guestfs_copy_file_to_device".
4762 See "CALLS WITH OPTIONAL ARGUMENTS".
4764 guestfs_copy_file_to_file
4766 int
4767 guestfs_copy_file_to_file (guestfs_h *g,
4768 const char *src,
4769 const char *dest,
4770 ...);
4771 You may supply a list of optional arguments to this call. Use zero or
4773 more of the following pairs of parameters, and terminate the list with
4774 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4775 GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4777 GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4778 GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4779 GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4780 GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4781 See "guestfs_copy_device_to_device" for a general overview of this
4783 call.
4784 This is not the function you want for copying files. This is for
4786 copying blocks within existing files. See "guestfs_cp", "guestfs_cp_a"
4787 and "guestfs_mv" for general file copying and moving functions.
4788 This function returns 0 on success or -1 on error.
4790 This long-running command can generate progress notification messages
4792 so that the caller can display a progress bar or indicator. To receive
4793 these messages, the caller must register a progress event callback.
4794 See "GUESTFS_EVENT_PROGRESS".
4795 (Added in 1.13.25)
4797 guestfs_copy_file_to_file_va
4799 int
4800 guestfs_copy_file_to_file_va (guestfs_h *g,
4801 const char *src,
4802 const char *dest,
4803 va_list args);
4804 This is the "va_list variant" of "guestfs_copy_file_to_file".
4806 See "CALLS WITH OPTIONAL ARGUMENTS".
4808 guestfs_copy_file_to_file_argv
4810 int
4811 guestfs_copy_file_to_file_argv (guestfs_h *g,
4812 const char *src,
4813 const char *dest,
4814 const struct guestfs_copy_file_to_file_argv *optargs);
4815 This is the "argv variant" of "guestfs_copy_file_to_file".
4817 See "CALLS WITH OPTIONAL ARGUMENTS".
4819 guestfs_copy_in
4821 int
4822 guestfs_copy_in (guestfs_h *g,
4823 const char *localpath,
4824 const char *remotedir);
4825 "guestfs_copy_in" copies local files or directories recursively into
4827 the disk image, placing them in the directory called "remotedir" (which
4828 must exist).
4829 Wildcards cannot be used.
4831 This function returns 0 on success or -1 on error.
4833 (Added in 1.29.24)
4835 guestfs_copy_out
4837 int
4838 guestfs_copy_out (guestfs_h *g,
4839 const char *remotepath,
4840 const char *localdir);
4841 "guestfs_copy_out" copies remote files or directories recursively out
4843 of the disk image, placing them on the host disk in a local directory
4844 called "localdir" (which must exist).
4845 To download to the current directory, use "." as in:
4847 C<guestfs_copy_out> /home .
4849 Wildcards cannot be used.
4851 This function returns 0 on success or -1 on error.
4853 (Added in 1.29.24)
4855 guestfs_copy_size
4857 int
4858 guestfs_copy_size (guestfs_h *g,
4859 const char *src,
4860 const char *dest,
4861 int64_t size);
4862 This function is deprecated. In new code, use the
4864 "guestfs_copy_device_to_device" call instead.
4865 Deprecated functions will not be removed from the API, but the fact
4867 that they are deprecated indicates that there are problems with correct
4868 use of these functions.
4869 This command copies exactly "size" bytes from one source device or file
4871 "src" to another destination device or file "dest".
4872 Note this will fail if the source is too short or if the destination is
4874 not large enough.
4875 This function returns 0 on success or -1 on error.
4877 This long-running command can generate progress notification messages
4879 so that the caller can display a progress bar or indicator. To receive
4880 these messages, the caller must register a progress event callback.
4881 See "GUESTFS_EVENT_PROGRESS".
4882 (Added in 1.0.87)
4884 guestfs_cp
4886 int
4887 guestfs_cp (guestfs_h *g,
4888 const char *src,
4889 const char *dest);
4890 This copies a file from "src" to "dest" where "dest" is either a
4892 destination filename or destination directory.
4893 This function returns 0 on success or -1 on error.
4895 (Added in 1.0.18)
4897 guestfs_cp_a
4899 int
4900 guestfs_cp_a (guestfs_h *g,
4901 const char *src,
4902 const char *dest);
4903 This copies a file or directory from "src" to "dest" recursively using
4905 the "cp -a" command.
4906 This function returns 0 on success or -1 on error.
4908 (Added in 1.0.18)
4910 guestfs_cp_r
4912 int
4913 guestfs_cp_r (guestfs_h *g,
4914 const char *src,
4915 const char *dest);
4916 This copies a file or directory from "src" to "dest" recursively using
4918 the "cp -rP" command.
4919 Most users should use "guestfs_cp_a" instead. This command is useful
4921 when you don't want to preserve permissions, because the target
4922 filesystem does not support it (primarily when writing to DOS FAT
4923 filesystems).
4924 This function returns 0 on success or -1 on error.
4926 (Added in 1.21.38)
4928 guestfs_cpio_out
4930 int
4931 guestfs_cpio_out (guestfs_h *g,
4932 const char *directory,
4933 const char *cpiofile,
4934 ...);
4935 You may supply a list of optional arguments to this call. Use zero or
4937 more of the following pairs of parameters, and terminate the list with
4938 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4939 GUESTFS_CPIO_OUT_FORMAT, const char *format,
4941 This command packs the contents of directory and downloads it to local
4943 file "cpiofile".
4944 The optional "format" parameter can be used to select the format. Only
4946 the following formats are currently permitted:
4947 "newc"
4949 New (SVR4) portable format. This format happens to be compatible
4950 with the cpio-like format used by the Linux kernel for initramfs.
4951 This is the default format.
4953 "crc"
4955 New (SVR4) portable format with a checksum.
4956 This function returns 0 on success or -1 on error.
4958 (Added in 1.27.9)
4960 guestfs_cpio_out_va
4962 int
4963 guestfs_cpio_out_va (guestfs_h *g,
4964 const char *directory,
4965 const char *cpiofile,
4966 va_list args);
4967 This is the "va_list variant" of "guestfs_cpio_out".
4969 See "CALLS WITH OPTIONAL ARGUMENTS".
4971 guestfs_cpio_out_argv
4973 int
4974 guestfs_cpio_out_argv (guestfs_h *g,
4975 const char *directory,
4976 const char *cpiofile,
4977 const struct guestfs_cpio_out_argv *optargs);
4978 This is the "argv variant" of "guestfs_cpio_out".
4980 See "CALLS WITH OPTIONAL ARGUMENTS".
4982 guestfs_dd
4984 int
4985 guestfs_dd (guestfs_h *g,
4986 const char *src,
4987 const char *dest);
4988 This function is deprecated. In new code, use the
4990 "guestfs_copy_device_to_device" call instead.
4991 Deprecated functions will not be removed from the API, but the fact
4993 that they are deprecated indicates that there are problems with correct
4994 use of these functions.
4995 This command copies from one source device or file "src" to another
4997 destination device or file "dest". Normally you would use this to copy
4998 to or from a device or partition, for example to duplicate a
4999 filesystem.
5000 If the destination is a device, it must be as large or larger than the
5002 source file or device, otherwise the copy will fail. This command
5003 cannot do partial copies (see "guestfs_copy_device_to_device").
5004 This function returns 0 on success or -1 on error.
5006 (Added in 1.0.80)
5008 guestfs_device_index
5010 int
5011 guestfs_device_index (guestfs_h *g,
5012 const char *device);
5013 This function takes a device name (eg. "/dev/sdb") and returns the
5015 index of the device in the list of devices.
5016 Index numbers start from 0. The named device must exist, for example
5018 as a string returned from "guestfs_list_devices".
5019 See also "guestfs_list_devices", "guestfs_part_to_dev".
5021 On error this function returns -1.
5023 (Added in 1.19.7)
5025 guestfs_df
5027 char *
5028 guestfs_df (guestfs_h *g);
5029 This command runs the df(1) command to report disk space used.
5031 This command is mostly useful for interactive sessions. It is not
5033 intended that you try to parse the output string. Use
5034 "guestfs_statvfs" from programs.
5035 This function returns a string, or NULL on error. The caller must free
5037 the returned string after use.
5038 (Added in 1.0.54)
5040 guestfs_df_h
5042 char *
5043 guestfs_df_h (guestfs_h *g);
5044 This command runs the "df -h" command to report disk space used in
5046 human-readable format.
5047 This command is mostly useful for interactive sessions. It is not
5049 intended that you try to parse the output string. Use
5050 "guestfs_statvfs" from programs.
5051 This function returns a string, or NULL on error. The caller must free
5053 the returned string after use.
5054 (Added in 1.0.54)
5056 guestfs_disk_create
5058 int
5059 guestfs_disk_create (guestfs_h *g,
5060 const char *filename,
5061 const char *format,
5062 int64_t size,
5063 ...);
5064 You may supply a list of optional arguments to this call. Use zero or
5066 more of the following pairs of parameters, and terminate the list with
5067 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5068 GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
5070 GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
5071 GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
5072 GUESTFS_DISK_CREATE_COMPAT, const char *compat,
5073 GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
5074 Create a blank disk image called filename (a host file) with format
5076 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
5077 If used with the optional "backingfile" parameter, then a snapshot is
5079 created on top of the backing file. In this case, "size" must be
5080 passed as "-1". The size of the snapshot is the same as the size of
5081 the backing file, which is discovered automatically. You are
5082 encouraged to also pass "backingformat" to describe the format of
5083 "backingfile".
5084 If filename refers to a block device, then the device is formatted.
5086 The "size" is ignored since block devices have an intrinsic size.
5087 The other optional parameters are:
5089 "preallocation"
5091 If format is "raw", then this can be either "off" (or "sparse") or
5092 "full" to create a sparse or fully allocated file respectively.
5093 The default is "off".
5094 If format is "qcow2", then this can be "off" (or "sparse"),
5096 "metadata" or "full". Preallocating metadata can be faster when
5097 doing lots of writes, but uses more space. The default is "off".
5098 "compat"
5100 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5101 supported by qemu ≥ 1.1.
5102 "clustersize"
5104 "qcow2" only: Change the qcow2 cluster size. The default is 65536
5105 (bytes) and this setting may be any power of two between 512 and
5106 2097152.
5107 Note that this call does not add the new disk to the handle. You may
5109 need to call "guestfs_add_drive_opts" separately.
5110 This function returns 0 on success or -1 on error.
5112 (Added in 1.25.31)
5114 guestfs_disk_create_va
5116 int
5117 guestfs_disk_create_va (guestfs_h *g,
5118 const char *filename,
5119 const char *format,
5120 int64_t size,
5121 va_list args);
5122 This is the "va_list variant" of "guestfs_disk_create".
5124 See "CALLS WITH OPTIONAL ARGUMENTS".
5126 guestfs_disk_create_argv
5128 int
5129 guestfs_disk_create_argv (guestfs_h *g,
5130 const char *filename,
5131 const char *format,
5132 int64_t size,
5133 const struct guestfs_disk_create_argv *optargs);
5134 This is the "argv variant" of "guestfs_disk_create".
5136 See "CALLS WITH OPTIONAL ARGUMENTS".
5138 guestfs_disk_format
5140 char *
5141 guestfs_disk_format (guestfs_h *g,
5142 const char *filename);
5143 Detect and return the format of the disk image called filename.
5145 filename can also be a host device, etc. If the format of the image
5146 could not be detected, then "unknown" is returned.
5147 Note that detecting the disk format can be insecure under some
5149 circumstances. See "CVE-2010-3851".
5150 See also: "DISK IMAGE FORMATS"
5152 This function returns a string, or NULL on error. The caller must free
5154 the returned string after use.
5155 (Added in 1.19.38)
5157 guestfs_disk_has_backing_file
5159 int
5160 guestfs_disk_has_backing_file (guestfs_h *g,
5161 const char *filename);
5162 Detect and return whether the disk image filename has a backing file.
5164 Note that detecting disk features can be insecure under some
5166 circumstances. See "CVE-2010-3851".
5167 This function returns a C truth value on success or -1 on error.
5169 (Added in 1.19.39)
5171 guestfs_disk_virtual_size
5173 int64_t
5174 guestfs_disk_virtual_size (guestfs_h *g,
5175 const char *filename);
5176 Detect and return the virtual size in bytes of the disk image called
5178 filename.
5179 Note that detecting disk features can be insecure under some
5181 circumstances. See "CVE-2010-3851".
5182 On error this function returns -1.
5184 (Added in 1.19.39)
5186 guestfs_dmesg
5188 char *
5189 guestfs_dmesg (guestfs_h *g);
5190 This returns the kernel messages (dmesg(1) output) from the guest
5192 kernel. This is sometimes useful for extended debugging of problems.
5193 Another way to get the same information is to enable verbose messages
5195 with "guestfs_set_verbose" or by setting the environment variable
5196 "LIBGUESTFS_DEBUG=1" before running the program.
5197 This function returns a string, or NULL on error. The caller must free
5199 the returned string after use.
5200 (Added in 1.0.18)
5202 guestfs_download
5204 int
5205 guestfs_download (guestfs_h *g,
5206 const char *remotefilename,
5207 const char *filename);
5208 Download file remotefilename and save it as filename on the local
5210 machine.
5211 filename can also be a named pipe.
5213 See also "guestfs_upload", "guestfs_cat".
5215 This function returns 0 on success or -1 on error.
5217 This long-running command can generate progress notification messages
5219 so that the caller can display a progress bar or indicator. To receive
5220 these messages, the caller must register a progress event callback.
5221 See "GUESTFS_EVENT_PROGRESS".
5222 (Added in 1.0.2)
5224 guestfs_download_blocks
5226 int
5227 guestfs_download_blocks (guestfs_h *g,
5228 const char *device,
5229 int64_t start,
5230 int64_t stop,
5231 const char *filename,
5232 ...);
5233 You may supply a list of optional arguments to this call. Use zero or
5235 more of the following pairs of parameters, and terminate the list with
5236 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5237 GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5239 Download the data units from start address to stop from the disk
5241 partition (eg. /dev/sda1) and save them as filename on the local
5242 machine.
5243 The use of this API on sparse disk image formats such as QCOW, may
5245 result in large zero-filled files downloaded on the host.
5246 The size of a data unit varies across filesystem implementations. On
5248 NTFS filesystems data units are referred as clusters while on ExtX ones
5249 they are referred as fragments.
5250 If the optional "unallocated" flag is true (default is false), only the
5252 unallocated blocks will be extracted. This is useful to detect hidden
5253 data or to retrieve deleted files which data units have not been
5254 overwritten yet.
5255 This function returns 0 on success or -1 on error.
5257 This long-running command can generate progress notification messages
5259 so that the caller can display a progress bar or indicator. To receive
5260 these messages, the caller must register a progress event callback.
5261 See "GUESTFS_EVENT_PROGRESS".
5262 This function depends on the feature "sleuthkit". See also
5264 "guestfs_feature_available".
5265 (Added in 1.33.45)
5267 guestfs_download_blocks_va
5269 int
5270 guestfs_download_blocks_va (guestfs_h *g,
5271 const char *device,
5272 int64_t start,
5273 int64_t stop,
5274 const char *filename,
5275 va_list args);
5276 This is the "va_list variant" of "guestfs_download_blocks".
5278 See "CALLS WITH OPTIONAL ARGUMENTS".
5280 guestfs_download_blocks_argv
5282 int
5283 guestfs_download_blocks_argv (guestfs_h *g,
5284 const char *device,
5285 int64_t start,
5286 int64_t stop,
5287 const char *filename,
5288 const struct guestfs_download_blocks_argv *optargs);
5289 This is the "argv variant" of "guestfs_download_blocks".
5291 See "CALLS WITH OPTIONAL ARGUMENTS".
5293 guestfs_download_inode
5295 int
5296 guestfs_download_inode (guestfs_h *g,
5297 const char *device,
5298 int64_t inode,
5299 const char *filename);
5300 Download a file given its inode from the disk partition (eg. /dev/sda1)
5302 and save it as filename on the local machine.
5303 It is not required to mount the disk to run this command.
5305 The command is capable of downloading deleted or inaccessible files.
5307 This function returns 0 on success or -1 on error.
5309 This long-running command can generate progress notification messages
5311 so that the caller can display a progress bar or indicator. To receive
5312 these messages, the caller must register a progress event callback.
5313 See "GUESTFS_EVENT_PROGRESS".
5314 This function depends on the feature "sleuthkit". See also
5316 "guestfs_feature_available".
5317 (Added in 1.33.14)
5319 guestfs_download_offset
5321 int
5322 guestfs_download_offset (guestfs_h *g,
5323 const char *remotefilename,
5324 const char *filename,
5325 int64_t offset,
5326 int64_t size);
5327 Download file remotefilename and save it as filename on the local
5329 machine.
5330 remotefilename is read for "size" bytes starting at "offset" (this
5332 region must be within the file or device).
5333 Note that there is no limit on the amount of data that can be
5335 downloaded with this call, unlike with "guestfs_pread", and this call
5336 always reads the full amount unless an error occurs.
5337 See also "guestfs_download", "guestfs_pread".
5339 This function returns 0 on success or -1 on error.
5341 This long-running command can generate progress notification messages
5343 so that the caller can display a progress bar or indicator. To receive
5344 these messages, the caller must register a progress event callback.
5345 See "GUESTFS_EVENT_PROGRESS".
5346 (Added in 1.5.17)
5348 guestfs_drop_caches
5350 int
5351 guestfs_drop_caches (guestfs_h *g,
5352 int whattodrop);
5353 This instructs the guest kernel to drop its page cache, and/or dentries
5355 and inode caches. The parameter "whattodrop" tells the kernel what
5356 precisely to drop, see https://linux-mm.org/Drop_Caches
5357 Setting "whattodrop" to 3 should drop everything.
5359 This automatically calls sync(2) before the operation, so that the
5361 maximum guest memory is freed.
5362 This function returns 0 on success or -1 on error.
5364 (Added in 1.0.18)
5366 guestfs_du
5368 int64_t
5369 guestfs_du (guestfs_h *g,
5370 const char *path);
5371 This command runs the "du -s" command to estimate file space usage for
5373 "path".
5374 "path" can be a file or a directory. If "path" is a directory then the
5376 estimate includes the contents of the directory and all subdirectories
5377 (recursively).
5378 The result is the estimated size in kilobytes (ie. units of 1024
5380 bytes).
5381 On error this function returns -1.
5383 This long-running command can generate progress notification messages
5385 so that the caller can display a progress bar or indicator. To receive
5386 these messages, the caller must register a progress event callback.
5387 See "GUESTFS_EVENT_PROGRESS".
5388 (Added in 1.0.54)
5390 guestfs_e2fsck
5392 int
5393 guestfs_e2fsck (guestfs_h *g,
5394 const char *device,
5395 ...);
5396 You may supply a list of optional arguments to this call. Use zero or
5398 more of the following pairs of parameters, and terminate the list with
5399 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5400 GUESTFS_E2FSCK_CORRECT, int correct,
5402 GUESTFS_E2FSCK_FORCEALL, int forceall,
5403 This runs the ext2/ext3 filesystem checker on "device". It can take
5405 the following optional arguments:
5406 "correct"
5408 Automatically repair the file system. This option will cause e2fsck
5409 to automatically fix any filesystem problems that can be safely
5410 fixed without human intervention.
5411 This option may not be specified at the same time as the "forceall"
5413 option.
5414 "forceall"
5416 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5417 used non-interactively.
5418 This option may not be specified at the same time as the "correct"
5420 option.
5421 This function returns 0 on success or -1 on error.
5423 (Added in 1.15.17)
5425 guestfs_e2fsck_va
5427 int
5428 guestfs_e2fsck_va (guestfs_h *g,
5429 const char *device,
5430 va_list args);
5431 This is the "va_list variant" of "guestfs_e2fsck".
5433 See "CALLS WITH OPTIONAL ARGUMENTS".
5435 guestfs_e2fsck_argv
5437 int
5438 guestfs_e2fsck_argv (guestfs_h *g,
5439 const char *device,
5440 const struct guestfs_e2fsck_argv *optargs);
5441 This is the "argv variant" of "guestfs_e2fsck".
5443 See "CALLS WITH OPTIONAL ARGUMENTS".
5445 guestfs_e2fsck_f
5447 int
5448 guestfs_e2fsck_f (guestfs_h *g,
5449 const char *device);
5450 This function is deprecated. In new code, use the "guestfs_e2fsck"
5452 call instead.
5453 Deprecated functions will not be removed from the API, but the fact
5455 that they are deprecated indicates that there are problems with correct
5456 use of these functions.
5457 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5459 checker on "device", noninteractively (-p), even if the filesystem
5460 appears to be clean (-f).
5461 This function returns 0 on success or -1 on error.
5463 (Added in 1.0.29)
5465 guestfs_echo_daemon
5467 char *
5468 guestfs_echo_daemon (guestfs_h *g,
5469 char *const *words);
5470 This command concatenates the list of "words" passed with single spaces
5472 between them and returns the resulting string.
5473 You can use this command to test the connection through to the daemon.
5475 See also "guestfs_ping_daemon".
5477 This function returns a string, or NULL on error. The caller must free
5479 the returned string after use.
5480 (Added in 1.0.69)
5482 guestfs_egrep
5484 char **
5485 guestfs_egrep (guestfs_h *g,
5486 const char *regex,
5487 const char *path);
5488 This function is deprecated. In new code, use the "guestfs_grep" call
5490 instead.
5491 Deprecated functions will not be removed from the API, but the fact
5493 that they are deprecated indicates that there are problems with correct
5494 use of these functions.
5495 This calls the external egrep(1) program and returns the matching
5497 lines.
5498 This function returns a NULL-terminated array of strings (like
5500 environ(3)), or NULL if there was an error. The caller must free the
5501 strings and the array after use.
5502 Because of the message protocol, there is a transfer limit of somewhere
5504 between 2MB and 4MB. See "PROTOCOL LIMITS".
5505 (Added in 1.0.66)
5507 guestfs_egrepi
5509 char **
5510 guestfs_egrepi (guestfs_h *g,
5511 const char *regex,
5512 const char *path);
5513 This function is deprecated. In new code, use the "guestfs_grep" call
5515 instead.
5516 Deprecated functions will not be removed from the API, but the fact
5518 that they are deprecated indicates that there are problems with correct
5519 use of these functions.
5520 This calls the external "egrep -i" program and returns the matching
5522 lines.
5523 This function returns a NULL-terminated array of strings (like
5525 environ(3)), or NULL if there was an error. The caller must free the
5526 strings and the array after use.
5527 Because of the message protocol, there is a transfer limit of somewhere
5529 between 2MB and 4MB. See "PROTOCOL LIMITS".
5530 (Added in 1.0.66)
5532 guestfs_equal
5534 int
5535 guestfs_equal (guestfs_h *g,
5536 const char *file1,
5537 const char *file2);
5538 This compares the two files file1 and file2 and returns true if their
5540 content is exactly equal, or false otherwise.
5541 The external cmp(1) program is used for the comparison.
5543 This function returns a C truth value on success or -1 on error.
5545 (Added in 1.0.18)
5547 guestfs_exists
5549 int
5550 guestfs_exists (guestfs_h *g,
5551 const char *path);
5552 This returns "true" if and only if there is a file, directory (or
5554 anything) with the given "path" name.
5555 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5557 This function returns a C truth value on success or -1 on error.
5559 (Added in 0.8)
5561 guestfs_extlinux
5563 int
5564 guestfs_extlinux (guestfs_h *g,
5565 const char *directory);
5566 Install the SYSLINUX bootloader on the device mounted at directory.
5568 Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5569 used on an ext2/3/4 or btrfs filesystem.
5570 The directory parameter can be either a mountpoint, or a directory
5572 within the mountpoint.
5573 You also have to mark the partition as "active"
5575 ("guestfs_part_set_bootable") and a Master Boot Record must be
5576 installed (eg. using "guestfs_pwrite_device") on the first sector of
5577 the whole disk. The SYSLINUX package comes with some suitable Master
5578 Boot Records. See the extlinux(1) man page for further information.
5579 Additional configuration can be supplied to SYSLINUX by placing a file
5581 called extlinux.conf on the filesystem under directory. For further
5582 information about the contents of this file, see extlinux(1).
5583 See also "guestfs_syslinux".
5585 This function returns 0 on success or -1 on error.
5587 This function depends on the feature "extlinux". See also
5589 "guestfs_feature_available".
5590 (Added in 1.21.27)
5592 guestfs_f2fs_expand
5594 int
5595 guestfs_f2fs_expand (guestfs_h *g,
5596 const char *device);
5597 This expands a f2fs filesystem to match the size of the underlying
5599 device.
5600 This function returns 0 on success or -1 on error.
5602 This function depends on the feature "f2fs". See also
5604 "guestfs_feature_available".
5605 (Added in 1.39.3)
5607 guestfs_fallocate
5609 int
5610 guestfs_fallocate (guestfs_h *g,
5611 const char *path,
5612 int len);
5613 This function is deprecated. In new code, use the
5615 "guestfs_fallocate64" call instead.
5616 Deprecated functions will not be removed from the API, but the fact
5618 that they are deprecated indicates that there are problems with correct
5619 use of these functions.
5620 This command preallocates a file (containing zero bytes) named "path"
5622 of size "len" bytes. If the file exists already, it is overwritten.
5623 Do not confuse this with the guestfish-specific "alloc" command which
5625 allocates a file in the host and attaches it as a device.
5626 This function returns 0 on success or -1 on error.
5628 (Added in 1.0.66)
5630 guestfs_fallocate64
5632 int
5633 guestfs_fallocate64 (guestfs_h *g,
5634 const char *path,
5635 int64_t len);
5636 This command preallocates a file (containing zero bytes) named "path"
5638 of size "len" bytes. If the file exists already, it is overwritten.
5639 Note that this call allocates disk blocks for the file. To create a
5641 sparse file use "guestfs_truncate_size" instead.
5642 The deprecated call "guestfs_fallocate" does the same, but owing to an
5644 oversight it only allowed 30 bit lengths to be specified, effectively
5645 limiting the maximum size of files created through that call to 1GB.
5646 Do not confuse this with the guestfish-specific "alloc" and "sparse"
5648 commands which create a file in the host and attach it as a device.
5649 This function returns 0 on success or -1 on error.
5651 (Added in 1.3.17)
5653 guestfs_feature_available
5655 int
5656 guestfs_feature_available (guestfs_h *g,
5657 char *const *groups);
5658 This is the same as "guestfs_available", but unlike that call it
5660 returns a simple true/false boolean result, instead of throwing an
5661 exception if a feature is not found. For other documentation see
5662 "guestfs_available".
5663 This function returns a C truth value on success or -1 on error.
5665 (Added in 1.21.26)
5667 guestfs_fgrep
5669 char **
5670 guestfs_fgrep (guestfs_h *g,
5671 const char *pattern,
5672 const char *path);
5673 This function is deprecated. In new code, use the "guestfs_grep" call
5675 instead.
5676 Deprecated functions will not be removed from the API, but the fact
5678 that they are deprecated indicates that there are problems with correct
5679 use of these functions.
5680 This calls the external fgrep(1) program and returns the matching
5682 lines.
5683 This function returns a NULL-terminated array of strings (like
5685 environ(3)), or NULL if there was an error. The caller must free the
5686 strings and the array after use.
5687 Because of the message protocol, there is a transfer limit of somewhere
5689 between 2MB and 4MB. See "PROTOCOL LIMITS".
5690 (Added in 1.0.66)
5692 guestfs_fgrepi
5694 char **
5695 guestfs_fgrepi (guestfs_h *g,
5696 const char *pattern,
5697 const char *path);
5698 This function is deprecated. In new code, use the "guestfs_grep" call
5700 instead.
5701 Deprecated functions will not be removed from the API, but the fact
5703 that they are deprecated indicates that there are problems with correct
5704 use of these functions.
5705 This calls the external "fgrep -i" program and returns the matching
5707 lines.
5708 This function returns a NULL-terminated array of strings (like
5710 environ(3)), or NULL if there was an error. The caller must free the
5711 strings and the array after use.
5712 Because of the message protocol, there is a transfer limit of somewhere
5714 between 2MB and 4MB. See "PROTOCOL LIMITS".
5715 (Added in 1.0.66)
5717 guestfs_file
5719 char *
5720 guestfs_file (guestfs_h *g,
5721 const char *path);
5722 This call uses the standard file(1) command to determine the type or
5724 contents of the file.
5725 This call will also transparently look inside various types of
5727 compressed file.
5728 The exact command which runs is "file -zb path". Note in particular
5730 that the filename is not prepended to the output (the -b option).
5731 The output depends on the output of the underlying file(1) command and
5733 it can change in future in ways beyond our control. In other words,
5734 the output is not guaranteed by the ABI.
5735 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5737 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5738 This function returns a string, or NULL on error. The caller must free
5740 the returned string after use.
5741 (Added in 1.9.1)
5743 guestfs_file_architecture
5745 char *
5746 guestfs_file_architecture (guestfs_h *g,
5747 const char *filename);
5748 This detects the architecture of the binary filename, and returns it if
5750 known.
5751 Currently defined architectures are:
5753 "aarch64"
5755 64 bit ARM.
5756 "arm"
5758 32 bit ARM.
5759 "i386"
5761 This string is returned for all 32 bit i386, i486, i586, i686
5762 binaries irrespective of the precise processor requirements of the
5763 binary.
5764 "ia64"
5766 Intel Itanium.
5767 "ppc"
5769 32 bit Power PC.
5770 "ppc64"
5772 64 bit Power PC (big endian).
5773 "ppc64le"
5775 64 bit Power PC (little endian).
5776 "riscv32"
5778 "riscv64"
5779 "riscv128"
5780 RISC-V 32-, 64- or 128-bit variants.
5781 "s390"
5783 31 bit IBM S/390.
5784 "s390x"
5786 64 bit IBM S/390.
5787 "sparc"
5789 32 bit SPARC.
5790 "sparc64"
5792 64 bit SPARC V9 and above.
5793 "x86_64"
5795 64 bit x86-64.
5796 Libguestfs may return other architecture strings in future.
5798 The function works on at least the following types of files:
5800 · many types of Un*x and Linux binary
5802 · many types of Un*x and Linux shared library
5804 · Windows Win32 and Win64 binaries
5806 · Windows Win32 and Win64 DLLs
5808 Win32 binaries and DLLs return "i386".
5810 Win64 binaries and DLLs return "x86_64".
5812 · Linux kernel modules
5814 · Linux new-style initrd images
5816 · some non-x86 Linux vmlinuz kernels
5818 What it can't do currently:
5820 · static libraries (libfoo.a)
5822 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5824 · x86 Linux vmlinuz kernels
5826 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5828 and compressed code, and are horribly hard to unpack. If you want
5829 to find the architecture of a kernel, use the architecture of the
5830 associated initrd or kernel module(s) instead.
5831 This function returns a string, or NULL on error. The caller must free
5833 the returned string after use.
5834 (Added in 1.5.3)
5836 guestfs_filesize
5838 int64_t
5839 guestfs_filesize (guestfs_h *g,
5840 const char *file);
5841 This command returns the size of file in bytes.
5843 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5845 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
5846 devices, use "guestfs_blockdev_getsize64".
5847 On error this function returns -1.
5849 (Added in 1.0.82)
5851 guestfs_filesystem_available
5853 int
5854 guestfs_filesystem_available (guestfs_h *g,
5855 const char *filesystem);
5856 Check whether libguestfs supports the named filesystem. The argument
5858 "filesystem" is a filesystem name, such as "ext3".
5859 You must call "guestfs_launch" before using this command.
5861 This is mainly useful as a negative test. If this returns true, it
5863 doesn't mean that a particular filesystem can be created or mounted,
5864 since filesystems can fail for other reasons such as it being a later
5865 version of the filesystem, or having incompatible features, or lacking
5866 the right mkfs.<fs> tool.
5867 See also "guestfs_available", "guestfs_feature_available",
5869 "AVAILABILITY".
5870 This function returns a C truth value on success or -1 on error.
5872 (Added in 1.19.5)
5874 guestfs_filesystem_walk
5876 struct guestfs_tsk_dirent_list *
5877 guestfs_filesystem_walk (guestfs_h *g,
5878 const char *device);
5879 Walk through the internal structures of a disk partition (eg.
5881 /dev/sda1) in order to return a list of all the files and directories
5882 stored within.
5883 It is not necessary to mount the disk partition to run this command.
5885 All entries in the filesystem are returned. This function can list
5887 deleted or unaccessible files. The entries are not sorted.
5888 The "tsk_dirent" structure contains the following fields.
5890 "tsk_inode"
5892 Filesystem reference number of the node. It might be 0 if the node
5893 has been deleted.
5894 "tsk_type"
5896 Basic file type information. See below for a detailed list of
5897 values.
5898 "tsk_size"
5900 File size in bytes. It might be "-1" if the node has been deleted.
5901 "tsk_name"
5903 The file path relative to its directory.
5904 "tsk_flags"
5906 Bitfield containing extra information regarding the entry. It
5907 contains the logical OR of the following values:
5908 0x0001
5910 If set to 1, the file is allocated and visible within the
5911 filesystem. Otherwise, the file has been deleted. Under
5912 certain circumstances, the function "download_inode" can be
5913 used to recover deleted files.
5914 0x0002
5916 Filesystem such as NTFS and Ext2 or greater, separate the file
5917 name from the metadata structure. The bit is set to 1 when the
5918 file name is in an unallocated state and the metadata structure
5919 is in an allocated one. This generally implies the metadata
5920 has been reallocated to a new file. Therefore, information
5921 such as file type, file size, timestamps, number of links and
5922 symlink target might not correspond with the ones of the
5923 original deleted entry.
5924 0x0004
5926 The bit is set to 1 when the file is compressed using
5927 filesystem native compression support (NTFS). The API is not
5928 able to detect application level compression.
5929 "tsk_atime_sec"
5931 "tsk_atime_nsec"
5932 "tsk_mtime_sec"
5933 "tsk_mtime_nsec"
5934 "tsk_ctime_sec"
5935 "tsk_ctime_nsec"
5936 "tsk_crtime_sec"
5937 "tsk_crtime_nsec"
5938 Respectively, access, modification, last status change and creation
5939 time in Unix format in seconds and nanoseconds.
5940 "tsk_nlink"
5942 Number of file names pointing to this entry.
5943 "tsk_link"
5945 If the entry is a symbolic link, this field will contain the path
5946 to the target file.
5947 The "tsk_type" field will contain one of the following characters:
5949 'b' Block special
5951 'c' Char special
5953 'd' Directory
5955 'f' FIFO (named pipe)
5957 'l' Symbolic link
5959 'r' Regular file
5961 's' Socket
5963 'h' Shadow inode (Solaris)
5965 'w' Whiteout inode (BSD)
5967 'u' Unknown file type
5969 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
5971 there was an error. The caller must call
5972 "guestfs_free_tsk_dirent_list" after use.
5973 This long-running command can generate progress notification messages
5975 so that the caller can display a progress bar or indicator. To receive
5976 these messages, the caller must register a progress event callback.
5977 See "GUESTFS_EVENT_PROGRESS".
5978 This function depends on the feature "libtsk". See also
5980 "guestfs_feature_available".
5981 (Added in 1.33.39)
5983 guestfs_fill
5985 int
5986 guestfs_fill (guestfs_h *g,
5987 int c,
5988 int len,
5989 const char *path);
5990 This command creates a new file called "path". The initial content of
5992 the file is "len" octets of "c", where "c" must be a number in the
5993 range "[0..255]".
5994 To fill a file with zero bytes (sparsely), it is much more efficient to
5996 use "guestfs_truncate_size". To create a file with a pattern of
5997 repeating bytes use "guestfs_fill_pattern".
5998 This function returns 0 on success or -1 on error.
6000 This long-running command can generate progress notification messages
6002 so that the caller can display a progress bar or indicator. To receive
6003 these messages, the caller must register a progress event callback.
6004 See "GUESTFS_EVENT_PROGRESS".
6005 (Added in 1.0.79)
6007 guestfs_fill_dir
6009 int
6010 guestfs_fill_dir (guestfs_h *g,
6011 const char *dir,
6012 int nr);
6013 This function, useful for testing filesystems, creates "nr" empty files
6015 in the directory "dir" with names 00000000 through "nr-1" (ie. each
6016 file name is 8 digits long padded with zeroes).
6017 This function returns 0 on success or -1 on error.
6019 (Added in 1.19.32)
6021 guestfs_fill_pattern
6023 int
6024 guestfs_fill_pattern (guestfs_h *g,
6025 const char *pattern,
6026 int len,
6027 const char *path);
6028 This function is like "guestfs_fill" except that it creates a new file
6030 of length "len" containing the repeating pattern of bytes in "pattern".
6031 The pattern is truncated if necessary to ensure the length of the file
6032 is exactly "len" bytes.
6033 This function returns 0 on success or -1 on error.
6035 This long-running command can generate progress notification messages
6037 so that the caller can display a progress bar or indicator. To receive
6038 these messages, the caller must register a progress event callback.
6039 See "GUESTFS_EVENT_PROGRESS".
6040 (Added in 1.3.12)
6042 guestfs_find
6044 char **
6045 guestfs_find (guestfs_h *g,
6046 const char *directory);
6047 This command lists out all files and directories, recursively, starting
6049 at directory. It is essentially equivalent to running the shell
6050 command "find directory -print" but some post-processing happens on the
6051 output, described below.
6052 This returns a list of strings without any prefix. Thus if the
6054 directory structure was:
6055 /tmp/a
6057 /tmp/b
6058 /tmp/c/d
6059 then the returned list from "guestfs_find" /tmp would be 4 elements:
6061 a
6063 b
6064 c
6065 c/d
6066 If directory is not a directory, then this command returns an error.
6068 The returned list is sorted.
6070 This function returns a NULL-terminated array of strings (like
6072 environ(3)), or NULL if there was an error. The caller must free the
6073 strings and the array after use.
6074 (Added in 1.0.27)
6076 guestfs_find0
6078 int
6079 guestfs_find0 (guestfs_h *g,
6080 const char *directory,
6081 const char *files);
6082 This command lists out all files and directories, recursively, starting
6084 at directory, placing the resulting list in the external file called
6085 files.
6086 This command works the same way as "guestfs_find" with the following
6088 exceptions:
6089 · The resulting list is written to an external file.
6091 · Items (filenames) in the result are separated by "\0" characters.
6093 See find(1) option -print0.
6094 · The result list is not sorted.
6096 This function returns 0 on success or -1 on error.
6098 (Added in 1.0.74)
6100 guestfs_find_inode
6102 struct guestfs_tsk_dirent_list *
6103 guestfs_find_inode (guestfs_h *g,
6104 const char *device,
6105 int64_t inode);
6106 Searches all the entries associated with the given inode.
6108 For each entry, a "tsk_dirent" structure is returned. See
6110 "filesystem_walk" for more information about "tsk_dirent" structures.
6111 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6113 there was an error. The caller must call
6114 "guestfs_free_tsk_dirent_list" after use.
6115 This long-running command can generate progress notification messages
6117 so that the caller can display a progress bar or indicator. To receive
6118 these messages, the caller must register a progress event callback.
6119 See "GUESTFS_EVENT_PROGRESS".
6120 This function depends on the feature "libtsk". See also
6122 "guestfs_feature_available".
6123 (Added in 1.35.6)
6125 guestfs_findfs_label
6127 char *
6128 guestfs_findfs_label (guestfs_h *g,
6129 const char *label);
6130 This command searches the filesystems and returns the one which has the
6132 given label. An error is returned if no such filesystem can be found.
6133 To find the label of a filesystem, use "guestfs_vfs_label".
6135 This function returns a string, or NULL on error. The caller must free
6137 the returned string after use.
6138 (Added in 1.5.3)
6140 guestfs_findfs_uuid
6142 char *
6143 guestfs_findfs_uuid (guestfs_h *g,
6144 const char *uuid);
6145 This command searches the filesystems and returns the one which has the
6147 given UUID. An error is returned if no such filesystem can be found.
6148 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6150 This function returns a string, or NULL on error. The caller must free
6152 the returned string after use.
6153 (Added in 1.5.3)
6155 guestfs_fsck
6157 int
6158 guestfs_fsck (guestfs_h *g,
6159 const char *fstype,
6160 const char *device);
6161 This runs the filesystem checker (fsck) on "device" which should have
6163 filesystem type "fstype".
6164 The returned integer is the status. See fsck(8) for the list of status
6166 codes from "fsck".
6167 Notes:
6169 · Multiple status codes can be summed together.
6171 · A non-zero return code can mean "success", for example if errors
6173 have been corrected on the filesystem.
6174 · Checking or repairing NTFS volumes is not supported (by linux-
6176 ntfs).
6177 This command is entirely equivalent to running "fsck -a -t fstype
6179 device".
6180 On error this function returns -1.
6182 (Added in 1.0.16)
6184 guestfs_fstrim
6186 int
6187 guestfs_fstrim (guestfs_h *g,
6188 const char *mountpoint,
6189 ...);
6190 You may supply a list of optional arguments to this call. Use zero or
6192 more of the following pairs of parameters, and terminate the list with
6193 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6194 GUESTFS_FSTRIM_OFFSET, int64_t offset,
6196 GUESTFS_FSTRIM_LENGTH, int64_t length,
6197 GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6198 Trim the free space in the filesystem mounted on "mountpoint". The
6200 filesystem must be mounted read-write.
6201 The filesystem contents are not affected, but any free space in the
6203 filesystem is "trimmed", that is, given back to the host device, thus
6204 making disk images more sparse, allowing unused space in qcow2 files to
6205 be reused, etc.
6206 This operation requires support in libguestfs, the mounted filesystem,
6208 the host filesystem, qemu and the host kernel. If this support isn't
6209 present it may give an error or even appear to run but do nothing.
6210 In the case where the kernel vfs driver does not support trimming, this
6212 call will fail with errno set to "ENOTSUP". Currently this happens
6213 when trying to trim FAT filesystems.
6214 See also "guestfs_zero_free_space". That is a slightly different
6216 operation that turns free space in the filesystem into zeroes. It is
6217 valid to call "guestfs_fstrim" either instead of, or after calling
6218 "guestfs_zero_free_space".
6219 This function returns 0 on success or -1 on error.
6221 This function depends on the feature "fstrim". See also
6223 "guestfs_feature_available".
6224 (Added in 1.19.6)
6226 guestfs_fstrim_va
6228 int
6229 guestfs_fstrim_va (guestfs_h *g,
6230 const char *mountpoint,
6231 va_list args);
6232 This is the "va_list variant" of "guestfs_fstrim".
6234 See "CALLS WITH OPTIONAL ARGUMENTS".
6236 guestfs_fstrim_argv
6238 int
6239 guestfs_fstrim_argv (guestfs_h *g,
6240 const char *mountpoint,
6241 const struct guestfs_fstrim_argv *optargs);
6242 This is the "argv variant" of "guestfs_fstrim".
6244 See "CALLS WITH OPTIONAL ARGUMENTS".
6246 guestfs_get_append
6248 const char *
6249 guestfs_get_append (guestfs_h *g);
6250 Return the additional kernel options which are added to the libguestfs
6252 appliance kernel command line.
6253 If "NULL" then no options are added.
6255 This function returns a string which may be NULL. There is no way to
6257 return an error from this function. The string is owned by the guest
6258 handle and must not be freed.
6259 (Added in 1.0.26)
6261 guestfs_get_attach_method
6263 char *
6264 guestfs_get_attach_method (guestfs_h *g);
6265 This function is deprecated. In new code, use the
6267 "guestfs_get_backend" call instead.
6268 Deprecated functions will not be removed from the API, but the fact
6270 that they are deprecated indicates that there are problems with correct
6271 use of these functions.
6272 Return the current backend.
6274 See "guestfs_set_backend" and "BACKEND".
6276 This function returns a string, or NULL on error. The caller must free
6278 the returned string after use.
6279 (Added in 1.9.8)
6281 guestfs_get_autosync
6283 int
6284 guestfs_get_autosync (guestfs_h *g);
6285 Get the autosync flag.
6287 This function returns a C truth value on success or -1 on error.
6289 (Added in 0.3)
6291 guestfs_get_backend
6293 char *
6294 guestfs_get_backend (guestfs_h *g);
6295 Return the current backend.
6297 This handle property was previously called the "attach method".
6299 See "guestfs_set_backend" and "BACKEND".
6301 This function returns a string, or NULL on error. The caller must free
6303 the returned string after use.
6304 (Added in 1.21.26)
6306 guestfs_get_backend_setting
6308 char *
6309 guestfs_get_backend_setting (guestfs_h *g,
6310 const char *name);
6311 Find a backend setting string which is either "name" or begins with
6313 "name=". If "name", this returns the string "1". If "name=", this
6314 returns the part after the equals sign (which may be an empty string).
6315 If no such setting is found, this function throws an error. The errno
6317 (see "guestfs_last_errno") will be "ESRCH" in this case.
6318 See "BACKEND", "BACKEND SETTINGS".
6320 This function returns a string, or NULL on error. The caller must free
6322 the returned string after use.
6323 (Added in 1.27.2)
6325 guestfs_get_backend_settings
6327 char **
6328 guestfs_get_backend_settings (guestfs_h *g);
6329 Return the current backend settings.
6331 This call returns all backend settings strings. If you want to find a
6333 single backend setting, see "guestfs_get_backend_setting".
6334 See "BACKEND", "BACKEND SETTINGS".
6336 This function returns a NULL-terminated array of strings (like
6338 environ(3)), or NULL if there was an error. The caller must free the
6339 strings and the array after use.
6340 (Added in 1.25.24)
6342 guestfs_get_cachedir
6344 char *
6345 guestfs_get_cachedir (guestfs_h *g);
6346 Get the directory used by the handle to store the appliance cache.
6348 This function returns a string, or NULL on error. The caller must free
6350 the returned string after use.
6351 (Added in 1.19.58)
6353 guestfs_get_direct
6355 int
6356 guestfs_get_direct (guestfs_h *g);
6357 This function is deprecated. In new code, use the
6359 "guestfs_internal_get_console_socket" call instead.
6360 Deprecated functions will not be removed from the API, but the fact
6362 that they are deprecated indicates that there are problems with correct
6363 use of these functions.
6364 Return the direct appliance mode flag.
6366 This function returns a C truth value on success or -1 on error.
6368 (Added in 1.0.72)
6370 guestfs_get_e2attrs
6372 char *
6373 guestfs_get_e2attrs (guestfs_h *g,
6374 const char *file);
6375 This returns the file attributes associated with file.
6377 The attributes are a set of bits associated with each inode which
6379 affect the behaviour of the file. The attributes are returned as a
6380 string of letters (described below). The string may be empty,
6381 indicating that no file attributes are set for this file.
6382 These attributes are only present when the file is located on an
6384 ext2/3/4 filesystem. Using this call on other filesystem types will
6385 result in an error.
6386 The characters (file attributes) in the returned string are currently:
6388 'A' When the file is accessed, its atime is not modified.
6390 'a' The file is append-only.
6392 'c' The file is compressed on-disk.
6394 'D' (Directories only.) Changes to this directory are written
6396 synchronously to disk.
6397 'd' The file is not a candidate for backup (see dump(8)).
6399 'E' The file has compression errors.
6401 'e' The file is using extents.
6403 'h' The file is storing its blocks in units of the filesystem blocksize
6405 instead of sectors.
6406 'I' (Directories only.) The directory is using hashed trees.
6408 'i' The file is immutable. It cannot be modified, deleted or renamed.
6410 No link can be created to this file.
6411 'j' The file is data-journaled.
6413 's' When the file is deleted, all its blocks will be zeroed.
6415 'S' Changes to this file are written synchronously to disk.
6417 'T' (Directories only.) This is a hint to the block allocator that
6419 subdirectories contained in this directory should be spread across
6420 blocks. If not present, the block allocator will try to group
6421 subdirectories together.
6422 't' For a file, this disables tail-merging. (Not used by upstream
6424 implementations of ext2.)
6425 'u' When the file is deleted, its blocks will be saved, allowing the
6427 file to be undeleted.
6428 'X' The raw contents of the compressed file may be accessed.
6430 'Z' The compressed file is dirty.
6432 More file attributes may be added to this list later. Not all file
6434 attributes may be set for all kinds of files. For detailed
6435 information, consult the chattr(1) man page.
6436 See also "guestfs_set_e2attrs".
6438 Don't confuse these attributes with extended attributes (see
6440 "guestfs_getxattr").
6441 This function returns a string, or NULL on error. The caller must free
6443 the returned string after use.
6444 (Added in 1.17.31)
6446 guestfs_get_e2generation
6448 int64_t
6449 guestfs_get_e2generation (guestfs_h *g,
6450 const char *file);
6451 This returns the ext2 file generation of a file. The generation (which
6453 used to be called the "version") is a number associated with an inode.
6454 This is most commonly used by NFS servers.
6455 The generation is only present when the file is located on an ext2/3/4
6457 filesystem. Using this call on other filesystem types will result in
6458 an error.
6459 See "guestfs_set_e2generation".
6461 On error this function returns -1.
6463 (Added in 1.17.31)
6465 guestfs_get_e2label
6467 char *
6468 guestfs_get_e2label (guestfs_h *g,
6469 const char *device);
6470 This function is deprecated. In new code, use the "guestfs_vfs_label"
6472 call instead.
6473 Deprecated functions will not be removed from the API, but the fact
6475 that they are deprecated indicates that there are problems with correct
6476 use of these functions.
6477 This returns the ext2/3/4 filesystem label of the filesystem on
6479 "device".
6480 This function returns a string, or NULL on error. The caller must free
6482 the returned string after use.
6483 (Added in 1.0.15)
6485 guestfs_get_e2uuid
6487 char *
6488 guestfs_get_e2uuid (guestfs_h *g,
6489 const char *device);
6490 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
6492 call instead.
6493 Deprecated functions will not be removed from the API, but the fact
6495 that they are deprecated indicates that there are problems with correct
6496 use of these functions.
6497 This returns the ext2/3/4 filesystem UUID of the filesystem on
6499 "device".
6500 This function returns a string, or NULL on error. The caller must free
6502 the returned string after use.
6503 (Added in 1.0.15)
6505 guestfs_get_hv
6507 char *
6508 guestfs_get_hv (guestfs_h *g);
6509 Return the current hypervisor binary.
6511 This is always non-NULL. If it wasn't set already, then this will
6513 return the default qemu binary name.
6514 This function returns a string, or NULL on error. The caller must free
6516 the returned string after use.
6517 (Added in 1.23.17)
6519 guestfs_get_identifier
6521 const char *
6522 guestfs_get_identifier (guestfs_h *g);
6523 Get the handle identifier. See "guestfs_set_identifier".
6525 This function returns a string, or NULL on error. The string is owned
6527 by the guest handle and must not be freed.
6528 (Added in 1.31.14)
6530 guestfs_get_libvirt_requested_credential_challenge
6532 char *
6533 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6534 int index);
6535 Get the challenge (provided by libvirt) for the "index"'th requested
6537 credential. If libvirt did not provide a challenge, this returns the
6538 empty string "".
6539 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6541 This function returns a string, or NULL on error. The caller must free
6543 the returned string after use.
6544 (Added in 1.19.52)
6546 guestfs_get_libvirt_requested_credential_defresult
6548 char *
6549 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6550 int index);
6551 Get the default result (provided by libvirt) for the "index"'th
6553 requested credential. If libvirt did not provide a default result,
6554 this returns the empty string "".
6555 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6557 This function returns a string, or NULL on error. The caller must free
6559 the returned string after use.
6560 (Added in 1.19.52)
6562 guestfs_get_libvirt_requested_credential_prompt
6564 char *
6565 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6566 int index);
6567 Get the prompt (provided by libvirt) for the "index"'th requested
6569 credential. If libvirt did not provide a prompt, this returns the
6570 empty string "".
6571 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6573 This function returns a string, or NULL on error. The caller must free
6575 the returned string after use.
6576 (Added in 1.19.52)
6578 guestfs_get_libvirt_requested_credentials
6580 char **
6581 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6582 This should only be called during the event callback for events of type
6584 "GUESTFS_EVENT_LIBVIRT_AUTH".
6585 Return the list of credentials requested by libvirt. Possible values
6587 are a subset of the strings provided when you called
6588 "guestfs_set_libvirt_supported_credentials".
6589 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6591 This function returns a NULL-terminated array of strings (like
6593 environ(3)), or NULL if there was an error. The caller must free the
6594 strings and the array after use.
6595 (Added in 1.19.52)
6597 guestfs_get_memsize
6599 int
6600 guestfs_get_memsize (guestfs_h *g);
6601 This gets the memory size in megabytes allocated to the hypervisor.
6603 If "guestfs_set_memsize" was not called on this handle, and if
6605 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6606 default value for memsize.
6607 For more information on the architecture of libguestfs, see guestfs(3).
6609 On error this function returns -1.
6611 (Added in 1.0.55)
6613 guestfs_get_network
6615 int
6616 guestfs_get_network (guestfs_h *g);
6617 This returns the enable network flag.
6619 This function returns a C truth value on success or -1 on error.
6621 (Added in 1.5.4)
6623 guestfs_get_path
6625 const char *
6626 guestfs_get_path (guestfs_h *g);
6627 Return the current search path.
6629 This is always non-NULL. If it wasn't set already, then this will
6631 return the default path.
6632 This function returns a string, or NULL on error. The string is owned
6634 by the guest handle and must not be freed.
6635 (Added in 0.3)
6637 guestfs_get_pgroup
6639 int
6640 guestfs_get_pgroup (guestfs_h *g);
6641 This returns the process group flag.
6643 This function returns a C truth value on success or -1 on error.
6645 (Added in 1.11.18)
6647 guestfs_get_pid
6649 int
6650 guestfs_get_pid (guestfs_h *g);
6651 Return the process ID of the hypervisor. If there is no hypervisor
6653 running, then this will return an error.
6654 This is an internal call used for debugging and testing.
6656 On error this function returns -1.
6658 (Added in 1.0.56)
6660 guestfs_get_program
6662 const char *
6663 guestfs_get_program (guestfs_h *g);
6664 Get the program name. See "guestfs_set_program".
6666 This function returns a string, or NULL on error. The string is owned
6668 by the guest handle and must not be freed.
6669 (Added in 1.21.29)
6671 guestfs_get_qemu
6673 const char *
6674 guestfs_get_qemu (guestfs_h *g);
6675 This function is deprecated. In new code, use the "guestfs_get_hv"
6677 call instead.
6678 Deprecated functions will not be removed from the API, but the fact
6680 that they are deprecated indicates that there are problems with correct
6681 use of these functions.
6682 Return the current hypervisor binary (usually qemu).
6684 This is always non-NULL. If it wasn't set already, then this will
6686 return the default qemu binary name.
6687 This function returns a string, or NULL on error. The string is owned
6689 by the guest handle and must not be freed.
6690 (Added in 1.0.6)
6692 guestfs_get_recovery_proc
6694 int
6695 guestfs_get_recovery_proc (guestfs_h *g);
6696 Return the recovery process enabled flag.
6698 This function returns a C truth value on success or -1 on error.
6700 (Added in 1.0.77)
6702 guestfs_get_selinux
6704 int
6705 guestfs_get_selinux (guestfs_h *g);
6706 This function is deprecated. In new code, use the
6708 "guestfs_selinux_relabel" call instead.
6709 Deprecated functions will not be removed from the API, but the fact
6711 that they are deprecated indicates that there are problems with correct
6712 use of these functions.
6713 This returns the current setting of the selinux flag which is passed to
6715 the appliance at boot time. See "guestfs_set_selinux".
6716 For more information on the architecture of libguestfs, see guestfs(3).
6718 This function returns a C truth value on success or -1 on error.
6720 (Added in 1.0.67)
6722 guestfs_get_smp
6724 int
6725 guestfs_get_smp (guestfs_h *g);
6726 This returns the number of virtual CPUs assigned to the appliance.
6728 On error this function returns -1.
6730 (Added in 1.13.15)
6732 guestfs_get_sockdir
6734 char *
6735 guestfs_get_sockdir (guestfs_h *g);
6736 Get the directory used by the handle to store temporary socket files.
6738 This is different from "guestfs_get_tmpdir", as we need shorter paths
6740 for sockets (due to the limited buffers of filenames for UNIX sockets),
6741 and "guestfs_get_tmpdir" may be too long for them.
6742 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6744 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6745 the default.
6746 This function returns a string, or NULL on error. The caller must free
6748 the returned string after use.
6749 (Added in 1.33.8)
6751 guestfs_get_state
6753 int
6754 guestfs_get_state (guestfs_h *g);
6755 This returns the current state as an opaque integer. This is only
6757 useful for printing debug and internal error messages.
6758 For more information on states, see guestfs(3).
6760 On error this function returns -1.
6762 (Added in 1.0.2)
6764 guestfs_get_tmpdir
6766 char *
6767 guestfs_get_tmpdir (guestfs_h *g);
6768 Get the directory used by the handle to store temporary files.
6770 This function returns a string, or NULL on error. The caller must free
6772 the returned string after use.
6773 (Added in 1.19.58)
6775 guestfs_get_trace
6777 int
6778 guestfs_get_trace (guestfs_h *g);
6779 Return the command trace flag.
6781 This function returns a C truth value on success or -1 on error.
6783 (Added in 1.0.69)
6785 guestfs_get_umask
6787 int
6788 guestfs_get_umask (guestfs_h *g);
6789 Return the current umask. By default the umask is 022 unless it has
6791 been set by calling "guestfs_umask".
6792 On error this function returns -1.
6794 (Added in 1.3.4)
6796 guestfs_get_verbose
6798 int
6799 guestfs_get_verbose (guestfs_h *g);
6800 This returns the verbose messages flag.
6802 This function returns a C truth value on success or -1 on error.
6804 (Added in 0.3)
6806 guestfs_getcon
6808 char *
6809 guestfs_getcon (guestfs_h *g);
6810 This function is deprecated. In new code, use the
6812 "guestfs_selinux_relabel" call instead.
6813 Deprecated functions will not be removed from the API, but the fact
6815 that they are deprecated indicates that there are problems with correct
6816 use of these functions.
6817 This gets the SELinux security context of the daemon.
6819 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6821 This function returns a string, or NULL on error. The caller must free
6823 the returned string after use.
6824 This function depends on the feature "selinux". See also
6826 "guestfs_feature_available".
6827 (Added in 1.0.67)
6829 guestfs_getxattr
6831 char *
6832 guestfs_getxattr (guestfs_h *g,
6833 const char *path,
6834 const char *name,
6835 size_t *size_r);
6836 Get a single extended attribute from file "path" named "name". This
6838 call follows symlinks. If you want to lookup an extended attribute for
6839 the symlink itself, use "guestfs_lgetxattr".
6840 Normally it is better to get all extended attributes from a file in one
6842 go by calling "guestfs_getxattrs". However some Linux filesystem
6843 implementations are buggy and do not provide a way to list out
6844 attributes. For these filesystems (notably ntfs-3g) you have to know
6845 the names of the extended attributes you want in advance and call this
6846 function.
6847 Extended attribute values are blobs of binary data. If there is no
6849 extended attribute named "name", this returns an error.
6850 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6852 This function returns a buffer, or NULL on error. The size of the
6854 returned buffer is written to *size_r. The caller must free the
6855 returned buffer after use.
6856 This function depends on the feature "linuxxattrs". See also
6858 "guestfs_feature_available".
6859 (Added in 1.7.24)
6861 guestfs_getxattrs
6863 struct guestfs_xattr_list *
6864 guestfs_getxattrs (guestfs_h *g,
6865 const char *path);
6866 This call lists the extended attributes of the file or directory
6868 "path".
6869 At the system call level, this is a combination of the listxattr(2) and
6871 getxattr(2) calls.
6872 See also: "guestfs_lgetxattrs", attr(5).
6874 This function returns a "struct guestfs_xattr_list *", or NULL if there
6876 was an error. The caller must call "guestfs_free_xattr_list" after
6877 use.
6878 This function depends on the feature "linuxxattrs". See also
6880 "guestfs_feature_available".
6881 (Added in 1.0.59)
6883 guestfs_glob_expand
6885 char **
6886 guestfs_glob_expand (guestfs_h *g,
6887 const char *pattern);
6888 This function is provided for backwards compatibility with earlier
6890 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
6891 with no optional arguments.
6892 (Added in 1.0.50)
6894 guestfs_glob_expand_opts
6896 char **
6897 guestfs_glob_expand_opts (guestfs_h *g,
6898 const char *pattern,
6899 ...);
6900 You may supply a list of optional arguments to this call. Use zero or
6902 more of the following pairs of parameters, and terminate the list with
6903 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6904 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
6906 This command searches for all the pathnames matching "pattern"
6908 according to the wildcard expansion rules used by the shell.
6909 If no paths match, then this returns an empty list (note: not an
6911 error).
6912 It is just a wrapper around the C glob(3) function with flags
6914 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
6915 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
6917 and it defaults to true. It can be explicitly set as off to return no
6918 trailing slashes in filenames of directories.
6919 Notice that there is no equivalent command for expanding a device name
6921 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
6922 etc functions instead.
6923 This function returns a NULL-terminated array of strings (like
6925 environ(3)), or NULL if there was an error. The caller must free the
6926 strings and the array after use.
6927 (Added in 1.0.50)
6929 guestfs_glob_expand_opts_va
6931 char **
6932 guestfs_glob_expand_opts_va (guestfs_h *g,
6933 const char *pattern,
6934 va_list args);
6935 This is the "va_list variant" of "guestfs_glob_expand_opts".
6937 See "CALLS WITH OPTIONAL ARGUMENTS".
6939 guestfs_glob_expand_opts_argv
6941 char **
6942 guestfs_glob_expand_opts_argv (guestfs_h *g,
6943 const char *pattern,
6944 const struct guestfs_glob_expand_opts_argv *optargs);
6945 This is the "argv variant" of "guestfs_glob_expand_opts".
6947 See "CALLS WITH OPTIONAL ARGUMENTS".
6949 guestfs_grep
6951 char **
6952 guestfs_grep (guestfs_h *g,
6953 const char *regex,
6954 const char *path);
6955 This function is provided for backwards compatibility with earlier
6957 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
6958 optional arguments.
6959 (Added in 1.0.66)
6961 guestfs_grep_opts
6963 char **
6964 guestfs_grep_opts (guestfs_h *g,
6965 const char *regex,
6966 const char *path,
6967 ...);
6968 You may supply a list of optional arguments to this call. Use zero or
6970 more of the following pairs of parameters, and terminate the list with
6971 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6972 GUESTFS_GREP_OPTS_EXTENDED, int extended,
6974 GUESTFS_GREP_OPTS_FIXED, int fixed,
6975 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
6976 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
6977 This calls the external grep(1) program and returns the matching lines.
6979 The optional flags are:
6981 "extended"
6983 Use extended regular expressions. This is the same as using the -E
6984 flag.
6985 "fixed"
6987 Match fixed (don't use regular expressions). This is the same as
6988 using the -F flag.
6989 "insensitive"
6991 Match case-insensitive. This is the same as using the -i flag.
6992 "compressed"
6994 Use zgrep(1) instead of grep(1). This allows the input to be
6995 compress- or gzip-compressed.
6996 This function returns a NULL-terminated array of strings (like
6998 environ(3)), or NULL if there was an error. The caller must free the
6999 strings and the array after use.
7000 Because of the message protocol, there is a transfer limit of somewhere
7002 between 2MB and 4MB. See "PROTOCOL LIMITS".
7003 (Added in 1.0.66)
7005 guestfs_grep_opts_va
7007 char **
7008 guestfs_grep_opts_va (guestfs_h *g,
7009 const char *regex,
7010 const char *path,
7011 va_list args);
7012 This is the "va_list variant" of "guestfs_grep_opts".
7014 See "CALLS WITH OPTIONAL ARGUMENTS".
7016 guestfs_grep_opts_argv
7018 char **
7019 guestfs_grep_opts_argv (guestfs_h *g,
7020 const char *regex,
7021 const char *path,
7022 const struct guestfs_grep_opts_argv *optargs);
7023 This is the "argv variant" of "guestfs_grep_opts".
7025 See "CALLS WITH OPTIONAL ARGUMENTS".
7027 guestfs_grepi
7029 char **
7030 guestfs_grepi (guestfs_h *g,
7031 const char *regex,
7032 const char *path);
7033 This function is deprecated. In new code, use the "guestfs_grep" call
7035 instead.
7036 Deprecated functions will not be removed from the API, but the fact
7038 that they are deprecated indicates that there are problems with correct
7039 use of these functions.
7040 This calls the external "grep -i" program and returns the matching
7042 lines.
7043 This function returns a NULL-terminated array of strings (like
7045 environ(3)), or NULL if there was an error. The caller must free the
7046 strings and the array after use.
7047 Because of the message protocol, there is a transfer limit of somewhere
7049 between 2MB and 4MB. See "PROTOCOL LIMITS".
7050 (Added in 1.0.66)
7052 guestfs_grub_install
7054 int
7055 guestfs_grub_install (guestfs_h *g,
7056 const char *root,
7057 const char *device);
7058 This command installs GRUB 1 (the Grand Unified Bootloader) on
7060 "device", with the root directory being "root".
7061 Notes:
7063 · There is currently no way in the API to install grub2, which is
7065 used by most modern Linux guests. It is possible to run the grub2
7066 command from the guest, although see the caveats in "RUNNING
7067 COMMANDS".
7068 · This uses grub-install(8) from the host. Unfortunately grub is not
7070 always compatible with itself, so this only works in rather narrow
7071 circumstances. Careful testing with each guest version is
7072 advisable.
7073 · If grub-install reports the error "No suitable drive was found in
7075 the generated device map." it may be that you need to create a
7076 /boot/grub/device.map file first that contains the mapping between
7077 grub device names and Linux device names. It is usually sufficient
7078 to create a file containing:
7079 (hd0) /dev/vda
7081 replacing /dev/vda with the name of the installation device.
7083 This function returns 0 on success or -1 on error.
7085 This function depends on the feature "grub". See also
7087 "guestfs_feature_available".
7088 (Added in 1.0.17)
7090 guestfs_head
7092 char **
7093 guestfs_head (guestfs_h *g,
7094 const char *path);
7095 This command returns up to the first 10 lines of a file as a list of
7097 strings.
7098 This function returns a NULL-terminated array of strings (like
7100 environ(3)), or NULL if there was an error. The caller must free the
7101 strings and the array after use.
7102 Because of the message protocol, there is a transfer limit of somewhere
7104 between 2MB and 4MB. See "PROTOCOL LIMITS".
7105 (Added in 1.0.54)
7107 guestfs_head_n
7109 char **
7110 guestfs_head_n (guestfs_h *g,
7111 int nrlines,
7112 const char *path);
7113 If the parameter "nrlines" is a positive number, this returns the first
7115 "nrlines" lines of the file "path".
7116 If the parameter "nrlines" is a negative number, this returns lines
7118 from the file "path", excluding the last "nrlines" lines.
7119 If the parameter "nrlines" is zero, this returns an empty list.
7121 This function returns a NULL-terminated array of strings (like
7123 environ(3)), or NULL if there was an error. The caller must free the
7124 strings and the array after use.
7125 Because of the message protocol, there is a transfer limit of somewhere
7127 between 2MB and 4MB. See "PROTOCOL LIMITS".
7128 (Added in 1.0.54)
7130 guestfs_hexdump
7132 char *
7133 guestfs_hexdump (guestfs_h *g,
7134 const char *path);
7135 This runs "hexdump -C" on the given "path". The result is the human-
7137 readable, canonical hex dump of the file.
7138 This function returns a string, or NULL on error. The caller must free
7140 the returned string after use.
7141 Because of the message protocol, there is a transfer limit of somewhere
7143 between 2MB and 4MB. See "PROTOCOL LIMITS".
7144 (Added in 1.0.22)
7146 guestfs_hivex_close
7148 int
7149 guestfs_hivex_close (guestfs_h *g);
7150 Close the current hivex handle.
7152 This is a wrapper around the hivex(3) call of the same name.
7154 This function returns 0 on success or -1 on error.
7156 This function depends on the feature "hivex". See also
7158 "guestfs_feature_available".
7159 (Added in 1.19.35)
7161 guestfs_hivex_commit
7163 int
7164 guestfs_hivex_commit (guestfs_h *g,
7165 const char *filename);
7166 Commit (write) changes to the hive.
7168 If the optional filename parameter is null, then the changes are
7170 written back to the same hive that was opened. If this is not null
7171 then they are written to the alternate filename given and the original
7172 hive is left untouched.
7173 This is a wrapper around the hivex(3) call of the same name.
7175 This function returns 0 on success or -1 on error.
7177 This function depends on the feature "hivex". See also
7179 "guestfs_feature_available".
7180 (Added in 1.19.35)
7182 guestfs_hivex_node_add_child
7184 int64_t
7185 guestfs_hivex_node_add_child (guestfs_h *g,
7186 int64_t parent,
7187 const char *name);
7188 Add a child node to "parent" named "name".
7190 This is a wrapper around the hivex(3) call of the same name.
7192 On error this function returns -1.
7194 This function depends on the feature "hivex". See also
7196 "guestfs_feature_available".
7197 (Added in 1.19.35)
7199 guestfs_hivex_node_children
7201 struct guestfs_hivex_node_list *
7202 guestfs_hivex_node_children (guestfs_h *g,
7203 int64_t nodeh);
7204 Return the list of nodes which are subkeys of "nodeh".
7206 This is a wrapper around the hivex(3) call of the same name.
7208 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7210 there was an error. The caller must call
7211 "guestfs_free_hivex_node_list" after use.
7212 This function depends on the feature "hivex". See also
7214 "guestfs_feature_available".
7215 (Added in 1.19.35)
7217 guestfs_hivex_node_delete_child
7219 int
7220 guestfs_hivex_node_delete_child (guestfs_h *g,
7221 int64_t nodeh);
7222 Delete "nodeh", recursively if necessary.
7224 This is a wrapper around the hivex(3) call of the same name.
7226 This function returns 0 on success or -1 on error.
7228 This function depends on the feature "hivex". See also
7230 "guestfs_feature_available".
7231 (Added in 1.19.35)
7233 guestfs_hivex_node_get_child
7235 int64_t
7236 guestfs_hivex_node_get_child (guestfs_h *g,
7237 int64_t nodeh,
7238 const char *name);
7239 Return the child of "nodeh" with the name "name", if it exists. This
7241 can return 0 meaning the name was not found.
7242 This is a wrapper around the hivex(3) call of the same name.
7244 On error this function returns -1.
7246 This function depends on the feature "hivex". See also
7248 "guestfs_feature_available".
7249 (Added in 1.19.35)
7251 guestfs_hivex_node_get_value
7253 int64_t
7254 guestfs_hivex_node_get_value (guestfs_h *g,
7255 int64_t nodeh,
7256 const char *key);
7257 Return the value attached to "nodeh" which has the name "key", if it
7259 exists. This can return 0 meaning the key was not found.
7260 This is a wrapper around the hivex(3) call of the same name.
7262 On error this function returns -1.
7264 This function depends on the feature "hivex". See also
7266 "guestfs_feature_available".
7267 (Added in 1.19.35)
7269 guestfs_hivex_node_name
7271 char *
7272 guestfs_hivex_node_name (guestfs_h *g,
7273 int64_t nodeh);
7274 Return the name of "nodeh".
7276 This is a wrapper around the hivex(3) call of the same name.
7278 This function returns a string, or NULL on error. The caller must free
7280 the returned string after use.
7281 This function depends on the feature "hivex". See also
7283 "guestfs_feature_available".
7284 (Added in 1.19.35)
7286 guestfs_hivex_node_parent
7288 int64_t
7289 guestfs_hivex_node_parent (guestfs_h *g,
7290 int64_t nodeh);
7291 Return the parent node of "nodeh".
7293 This is a wrapper around the hivex(3) call of the same name.
7295 On error this function returns -1.
7297 This function depends on the feature "hivex". See also
7299 "guestfs_feature_available".
7300 (Added in 1.19.35)
7302 guestfs_hivex_node_set_value
7304 int
7305 guestfs_hivex_node_set_value (guestfs_h *g,
7306 int64_t nodeh,
7307 const char *key,
7308 int64_t t,
7309 const char *val,
7310 size_t val_size);
7311 Set or replace a single value under the node "nodeh". The "key" is the
7313 name, "t" is the type, and "val" is the data.
7314 This is a wrapper around the hivex(3) call of the same name.
7316 This function returns 0 on success or -1 on error.
7318 This function depends on the feature "hivex". See also
7320 "guestfs_feature_available".
7321 (Added in 1.19.35)
7323 guestfs_hivex_node_values
7325 struct guestfs_hivex_value_list *
7326 guestfs_hivex_node_values (guestfs_h *g,
7327 int64_t nodeh);
7328 Return the array of (key, datatype, data) tuples attached to "nodeh".
7330 This is a wrapper around the hivex(3) call of the same name.
7332 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7334 there was an error. The caller must call
7335 "guestfs_free_hivex_value_list" after use.
7336 This function depends on the feature "hivex". See also
7338 "guestfs_feature_available".
7339 (Added in 1.19.35)
7341 guestfs_hivex_open
7343 int
7344 guestfs_hivex_open (guestfs_h *g,
7345 const char *filename,
7346 ...);
7347 You may supply a list of optional arguments to this call. Use zero or
7349 more of the following pairs of parameters, and terminate the list with
7350 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7351 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7353 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7354 GUESTFS_HIVEX_OPEN_WRITE, int write,
7355 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7356 Open the Windows Registry hive file named filename. If there was any
7358 previous hivex handle associated with this guestfs session, then it is
7359 closed.
7360 This is a wrapper around the hivex(3) call of the same name.
7362 This function returns 0 on success or -1 on error.
7364 This function depends on the feature "hivex". See also
7366 "guestfs_feature_available".
7367 (Added in 1.19.35)
7369 guestfs_hivex_open_va
7371 int
7372 guestfs_hivex_open_va (guestfs_h *g,
7373 const char *filename,
7374 va_list args);
7375 This is the "va_list variant" of "guestfs_hivex_open".
7377 See "CALLS WITH OPTIONAL ARGUMENTS".
7379 guestfs_hivex_open_argv
7381 int
7382 guestfs_hivex_open_argv (guestfs_h *g,
7383 const char *filename,
7384 const struct guestfs_hivex_open_argv *optargs);
7385 This is the "argv variant" of "guestfs_hivex_open".
7387 See "CALLS WITH OPTIONAL ARGUMENTS".
7389 guestfs_hivex_root
7391 int64_t
7392 guestfs_hivex_root (guestfs_h *g);
7393 Return the root node of the hive.
7395 This is a wrapper around the hivex(3) call of the same name.
7397 On error this function returns -1.
7399 This function depends on the feature "hivex". See also
7401 "guestfs_feature_available".
7402 (Added in 1.19.35)
7404 guestfs_hivex_value_key
7406 char *
7407 guestfs_hivex_value_key (guestfs_h *g,
7408 int64_t valueh);
7409 Return the key (name) field of a (key, datatype, data) tuple.
7411 This is a wrapper around the hivex(3) call of the same name.
7413 This function returns a string, or NULL on error. The caller must free
7415 the returned string after use.
7416 This function depends on the feature "hivex". See also
7418 "guestfs_feature_available".
7419 (Added in 1.19.35)
7421 guestfs_hivex_value_string
7423 char *
7424 guestfs_hivex_value_string (guestfs_h *g,
7425 int64_t valueh);
7426 This calls "guestfs_hivex_value_value" (which returns the data field
7428 from a hivex value tuple). It then assumes that the field is a
7429 UTF-16LE string and converts the result to UTF-8 (or if this is not
7430 possible, it returns an error).
7431 This is useful for reading strings out of the Windows registry.
7433 However it is not foolproof because the registry is not strongly-typed
7434 and fields can contain arbitrary or unexpected data.
7435 This function returns a string, or NULL on error. The caller must free
7437 the returned string after use.
7438 This function depends on the feature "hivex". See also
7440 "guestfs_feature_available".
7441 (Added in 1.37.22)
7443 guestfs_hivex_value_type
7445 int64_t
7446 guestfs_hivex_value_type (guestfs_h *g,
7447 int64_t valueh);
7448 Return the data type field from a (key, datatype, data) tuple.
7450 This is a wrapper around the hivex(3) call of the same name.
7452 On error this function returns -1.
7454 This function depends on the feature "hivex". See also
7456 "guestfs_feature_available".
7457 (Added in 1.19.35)
7459 guestfs_hivex_value_utf8
7461 char *
7462 guestfs_hivex_value_utf8 (guestfs_h *g,
7463 int64_t valueh);
7464 This function is deprecated. In new code, use the
7466 "guestfs_hivex_value_string" call instead.
7467 Deprecated functions will not be removed from the API, but the fact
7469 that they are deprecated indicates that there are problems with correct
7470 use of these functions.
7471 This calls "guestfs_hivex_value_value" (which returns the data field
7473 from a hivex value tuple). It then assumes that the field is a
7474 UTF-16LE string and converts the result to UTF-8 (or if this is not
7475 possible, it returns an error).
7476 This is useful for reading strings out of the Windows registry.
7478 However it is not foolproof because the registry is not strongly-typed
7479 and fields can contain arbitrary or unexpected data.
7480 This function returns a string, or NULL on error. The caller must free
7482 the returned string after use.
7483 This function depends on the feature "hivex". See also
7485 "guestfs_feature_available".
7486 (Added in 1.19.35)
7488 guestfs_hivex_value_value
7490 char *
7491 guestfs_hivex_value_value (guestfs_h *g,
7492 int64_t valueh,
7493 size_t *size_r);
7494 Return the data field of a (key, datatype, data) tuple.
7496 This is a wrapper around the hivex(3) call of the same name.
7498 See also: "guestfs_hivex_value_utf8".
7500 This function returns a buffer, or NULL on error. The size of the
7502 returned buffer is written to *size_r. The caller must free the
7503 returned buffer after use.
7504 This function depends on the feature "hivex". See also
7506 "guestfs_feature_available".
7507 (Added in 1.19.35)
7509 guestfs_initrd_cat
7511 char *
7512 guestfs_initrd_cat (guestfs_h *g,
7513 const char *initrdpath,
7514 const char *filename,
7515 size_t *size_r);
7516 This command unpacks the file filename from the initrd file called
7518 initrdpath. The filename must be given without the initial /
7519 character.
7520 For example, in guestfish you could use the following command to
7522 examine the boot script (usually called /init) contained in a Linux
7523 initrd or initramfs image:
7524 initrd-cat /boot/initrd-<version>.img init
7526 See also "guestfs_initrd_list".
7528 This function returns a buffer, or NULL on error. The size of the
7530 returned buffer is written to *size_r. The caller must free the
7531 returned buffer after use.
7532 Because of the message protocol, there is a transfer limit of somewhere
7534 between 2MB and 4MB. See "PROTOCOL LIMITS".
7535 (Added in 1.0.84)
7537 guestfs_initrd_list
7539 char **
7540 guestfs_initrd_list (guestfs_h *g,
7541 const char *path);
7542 This command lists out files contained in an initrd.
7544 The files are listed without any initial / character. The files are
7546 listed in the order they appear (not necessarily alphabetical).
7547 Directory names are listed as separate items.
7548 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7550 as initrd. We only support the newer initramfs format (compressed cpio
7551 files).
7552 This function returns a NULL-terminated array of strings (like
7554 environ(3)), or NULL if there was an error. The caller must free the
7555 strings and the array after use.
7556 (Added in 1.0.54)
7558 guestfs_inotify_add_watch
7560 int64_t
7561 guestfs_inotify_add_watch (guestfs_h *g,
7562 const char *path,
7563 int mask);
7564 Watch "path" for the events listed in "mask".
7566 Note that if "path" is a directory then events within that directory
7568 are watched, but this does not happen recursively (in subdirectories).
7569 Note for non-C or non-Linux callers: the inotify events are defined by
7571 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7572 On error this function returns -1.
7574 This function depends on the feature "inotify". See also
7576 "guestfs_feature_available".
7577 (Added in 1.0.66)
7579 guestfs_inotify_close
7581 int
7582 guestfs_inotify_close (guestfs_h *g);
7583 This closes the inotify handle which was previously opened by
7585 inotify_init. It removes all watches, throws away any pending events,
7586 and deallocates all resources.
7587 This function returns 0 on success or -1 on error.
7589 This function depends on the feature "inotify". See also
7591 "guestfs_feature_available".
7592 (Added in 1.0.66)
7594 guestfs_inotify_files
7596 char **
7597 guestfs_inotify_files (guestfs_h *g);
7598 This function is a helpful wrapper around "guestfs_inotify_read" which
7600 just returns a list of pathnames of objects that were touched. The
7601 returned pathnames are sorted and deduplicated.
7602 This function returns a NULL-terminated array of strings (like
7604 environ(3)), or NULL if there was an error. The caller must free the
7605 strings and the array after use.
7606 This function depends on the feature "inotify". See also
7608 "guestfs_feature_available".
7609 (Added in 1.0.66)
7611 guestfs_inotify_init
7613 int
7614 guestfs_inotify_init (guestfs_h *g,
7615 int maxevents);
7616 This command creates a new inotify handle. The inotify subsystem can
7618 be used to notify events which happen to objects in the guest
7619 filesystem.
7620 "maxevents" is the maximum number of events which will be queued up
7622 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7623 this is passed as 0, then the kernel (or previously set) default is
7624 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7625 limit, the kernel throws away events, but records the fact that it
7626 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7627 structure list (see "guestfs_inotify_read").
7628 Before any events are generated, you have to add some watches to the
7630 internal watch list. See: "guestfs_inotify_add_watch" and
7631 "guestfs_inotify_rm_watch".
7632 Queued up events should be read periodically by calling
7634 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7635 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7636 events out often enough then you risk the internal queue overflowing.
7637 The handle should be closed after use by calling
7639 "guestfs_inotify_close". This also removes any watches automatically.
7640 See also inotify(7) for an overview of the inotify interface as exposed
7642 by the Linux kernel, which is roughly what we expose via libguestfs.
7643 Note that there is one global inotify handle per libguestfs instance.
7644 This function returns 0 on success or -1 on error.
7646 This function depends on the feature "inotify". See also
7648 "guestfs_feature_available".
7649 (Added in 1.0.66)
7651 guestfs_inotify_read
7653 struct guestfs_inotify_event_list *
7654 guestfs_inotify_read (guestfs_h *g);
7655 Return the complete queue of events that have happened since the
7657 previous read call.
7658 If no events have happened, this returns an empty list.
7660 Note: In order to make sure that all events have been read, you must
7662 call this function repeatedly until it returns an empty list. The
7663 reason is that the call will read events up to the maximum appliance-
7664 to-host message size and leave remaining events in the queue.
7665 This function returns a "struct guestfs_inotify_event_list *", or NULL
7667 if there was an error. The caller must call
7668 "guestfs_free_inotify_event_list" after use.
7669 This function depends on the feature "inotify". See also
7671 "guestfs_feature_available".
7672 (Added in 1.0.66)
7674 guestfs_inotify_rm_watch
7676 int
7677 guestfs_inotify_rm_watch (guestfs_h *g,
7678 int wd);
7679 Remove a previously defined inotify watch. See
7681 "guestfs_inotify_add_watch".
7682 This function returns 0 on success or -1 on error.
7684 This function depends on the feature "inotify". See also
7686 "guestfs_feature_available".
7687 (Added in 1.0.66)
7689 guestfs_inspect_get_arch
7691 char *
7692 guestfs_inspect_get_arch (guestfs_h *g,
7693 const char *root);
7694 This returns the architecture of the inspected operating system. The
7696 possible return values are listed under "guestfs_file_architecture".
7697 If the architecture could not be determined, then the string "unknown"
7699 is returned.
7700 Please read "INSPECTION" for more details.
7702 This function returns a string, or NULL on error. The caller must free
7704 the returned string after use.
7705 (Added in 1.5.3)
7707 guestfs_inspect_get_distro
7709 char *
7710 guestfs_inspect_get_distro (guestfs_h *g,
7711 const char *root);
7712 This returns the distro (distribution) of the inspected operating
7714 system.
7715 Currently defined distros are:
7717 "alpinelinux"
7719 Alpine Linux.
7720 "altlinux"
7722 ALT Linux.
7723 "archlinux"
7725 Arch Linux.
7726 "buildroot"
7728 Buildroot-derived distro, but not one we specifically recognize.
7729 "centos"
7731 CentOS.
7732 "cirros"
7734 Cirros.
7735 "coreos"
7737 CoreOS.
7738 "debian"
7740 Debian.
7741 "fedora"
7743 Fedora.
7744 "freebsd"
7746 FreeBSD.
7747 "freedos"
7749 FreeDOS.
7750 "frugalware"
7752 Frugalware.
7753 "gentoo"
7755 Gentoo.
7756 "kalilinux"
7758 Kali Linux.
7759 "linuxmint"
7761 Linux Mint.
7762 "mageia"
7764 Mageia.
7765 "mandriva"
7767 Mandriva.
7768 "meego"
7770 MeeGo.
7771 "msdos"
7773 Microsoft DOS.
7774 "neokylin"
7776 NeoKylin.
7777 "netbsd"
7779 NetBSD.
7780 "openbsd"
7782 OpenBSD.
7783 "openmandriva"
7785 OpenMandriva Lx.
7786 "opensuse"
7788 OpenSUSE.
7789 "oraclelinux"
7791 Oracle Linux.
7792 "pardus"
7794 Pardus.
7795 "pldlinux"
7797 PLD Linux.
7798 "redhat-based"
7800 Some Red Hat-derived distro.
7801 "rhel"
7803 Red Hat Enterprise Linux.
7804 "scientificlinux"
7806 Scientific Linux.
7807 "slackware"
7809 Slackware.
7810 "sles"
7812 SuSE Linux Enterprise Server or Desktop.
7813 "suse-based"
7815 Some openSuSE-derived distro.
7816 "ttylinux"
7818 ttylinux.
7819 "ubuntu"
7821 Ubuntu.
7822 "unknown"
7824 The distro could not be determined.
7825 "voidlinux"
7827 Void Linux.
7828 "windows"
7830 Windows does not have distributions. This string is returned if
7831 the OS type is Windows.
7832 Future versions of libguestfs may return other strings here. The
7834 caller should be prepared to handle any string.
7835 Please read "INSPECTION" for more details.
7837 This function returns a string, or NULL on error. The caller must free
7839 the returned string after use.
7840 (Added in 1.5.3)
7842 guestfs_inspect_get_drive_mappings
7844 char **
7845 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7846 const char *root);
7847 This call is useful for Windows which uses a primitive system of
7849 assigning drive letters (like C:\) to partitions. This inspection API
7850 examines the Windows Registry to find out how disks/partitions are
7851 mapped to drive letters, and returns a hash table as in the example
7852 below:
7853 C => /dev/vda2
7855 E => /dev/vdb1
7856 F => /dev/vdc1
7857 Note that keys are drive letters. For Windows, the key is case
7859 insensitive and just contains the drive letter, without the customary
7860 colon separator character.
7861 In future we may support other operating systems that also used drive
7863 letters, but the keys for those might not be case insensitive and might
7864 be longer than 1 character. For example in OS-9, hard drives were
7865 named "h0", "h1" etc.
7866 For Windows guests, currently only hard drive mappings are returned.
7868 Removable disks (eg. DVD-ROMs) are ignored.
7869 For guests that do not use drive mappings, or if the drive mappings
7871 could not be determined, this returns an empty hash table.
7872 Please read "INSPECTION" for more details. See also
7874 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7875 This function returns a NULL-terminated array of strings, or NULL if
7877 there was an error. The array of strings will always have length
7878 "2n+1", where "n" keys and values alternate, followed by the trailing
7879 NULL entry. The caller must free the strings and the array after use.
7880 (Added in 1.9.17)
7882 guestfs_inspect_get_filesystems
7884 char **
7885 guestfs_inspect_get_filesystems (guestfs_h *g,
7886 const char *root);
7887 This returns a list of all the filesystems that we think are associated
7889 with this operating system. This includes the root filesystem, other
7890 ordinary filesystems, and non-mounted devices like swap partitions.
7891 In the case of a multi-boot virtual machine, it is possible for a
7893 filesystem to be shared between operating systems.
7894 Please read "INSPECTION" for more details. See also
7896 "guestfs_inspect_get_mountpoints".
7897 This function returns a NULL-terminated array of strings (like
7899 environ(3)), or NULL if there was an error. The caller must free the
7900 strings and the array after use.
7901 (Added in 1.5.3)
7903 guestfs_inspect_get_format
7905 char *
7906 guestfs_inspect_get_format (guestfs_h *g,
7907 const char *root);
7908 This function is deprecated. There is no replacement. Consult the API
7910 documentation in guestfs(3) for further information.
7911 Deprecated functions will not be removed from the API, but the fact
7913 that they are deprecated indicates that there are problems with correct
7914 use of these functions.
7915 Before libguestfs 1.38, there was some unreliable support for detecting
7917 installer CDs. This API would return:
7918 "installed"
7920 This is an installed operating system.
7921 "installer"
7923 The disk image being inspected is not an installed operating
7924 system, but a bootable install disk, live CD, or similar.
7925 "unknown"
7927 The format of this disk image is not known.
7928 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
7930 directly to detect installer CDs.
7931 Please read "INSPECTION" for more details.
7933 This function returns a string, or NULL on error. The caller must free
7935 the returned string after use.
7936 (Added in 1.9.4)
7938 guestfs_inspect_get_hostname
7940 char *
7941 guestfs_inspect_get_hostname (guestfs_h *g,
7942 const char *root);
7943 This function returns the hostname of the operating system as found by
7945 inspection of the guest’s configuration files.
7946 If the hostname could not be determined, then the string "unknown" is
7948 returned.
7949 Please read "INSPECTION" for more details.
7951 This function returns a string, or NULL on error. The caller must free
7953 the returned string after use.
7954 (Added in 1.7.9)
7956 guestfs_inspect_get_icon
7958 char *
7959 guestfs_inspect_get_icon (guestfs_h *g,
7960 const char *root,
7961 size_t *size_r,
7962 ...);
7963 You may supply a list of optional arguments to this call. Use zero or
7965 more of the following pairs of parameters, and terminate the list with
7966 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7967 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
7969 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
7970 This function returns an icon corresponding to the inspected operating
7972 system. The icon is returned as a buffer containing a PNG image (re-
7973 encoded to PNG if necessary).
7974 If it was not possible to get an icon this function returns a zero-
7976 length (non-NULL) buffer. Callers must check for this case.
7977 Libguestfs will start by looking for a file called /etc/favicon.png or
7979 C:\etc\favicon.png and if it has the correct format, the contents of
7980 this file will be returned. You can disable favicons by passing the
7981 optional "favicon" boolean as false (default is true).
7982 If finding the favicon fails, then we look in other places in the guest
7984 for a suitable icon.
7985 If the optional "highquality" boolean is true then only high quality
7987 icons are returned, which means only icons of high resolution with an
7988 alpha channel. The default (false) is to return any icon we can, even
7989 if it is of substandard quality.
7990 Notes:
7992 · Unlike most other inspection API calls, the guest’s disks must be
7994 mounted up before you call this, since it needs to read information
7995 from the guest filesystem during the call.
7996 · Security: The icon data comes from the untrusted guest, and should
7998 be treated with caution. PNG files have been known to contain
7999 exploits. Ensure that libpng (or other relevant libraries) are
8000 fully up to date before trying to process or display the icon.
8001 · The PNG image returned can be any size. It might not be square.
8003 Libguestfs tries to return the largest, highest quality icon
8004 available. The application must scale the icon to the required
8005 size.
8006 · Extracting icons from Windows guests requires the external
8008 wrestool(1) program from the "icoutils" package, and several
8009 programs (bmptopnm(1), pnmtopng(1), pamcut(1)) from the "netpbm"
8010 package. These must be installed separately.
8011 · Operating system icons are usually trademarks. Seek legal advice
8013 before using trademarks in applications.
8014 This function returns a buffer, or NULL on error. The size of the
8016 returned buffer is written to *size_r. The caller must free the
8017 returned buffer after use.
8018 (Added in 1.11.12)
8020 guestfs_inspect_get_icon_va
8022 char *
8023 guestfs_inspect_get_icon_va (guestfs_h *g,
8024 const char *root,
8025 size_t *size_r,
8026 va_list args);
8027 This is the "va_list variant" of "guestfs_inspect_get_icon".
8029 See "CALLS WITH OPTIONAL ARGUMENTS".
8031 guestfs_inspect_get_icon_argv
8033 char *
8034 guestfs_inspect_get_icon_argv (guestfs_h *g,
8035 const char *root,
8036 size_t *size_r,
8037 const struct guestfs_inspect_get_icon_argv *optargs);
8038 This is the "argv variant" of "guestfs_inspect_get_icon".
8040 See "CALLS WITH OPTIONAL ARGUMENTS".
8042 guestfs_inspect_get_major_version
8044 int
8045 guestfs_inspect_get_major_version (guestfs_h *g,
8046 const char *root);
8047 This returns the major version number of the inspected operating
8049 system.
8050 Windows uses a consistent versioning scheme which is not reflected in
8052 the popular public names used by the operating system. Notably the
8053 operating system known as "Windows 7" is really version 6.1 (ie. major
8054 = 6, minor = 1). You can find out the real versions corresponding to
8055 releases of Windows by consulting Wikipedia or MSDN.
8056 If the version could not be determined, then 0 is returned.
8058 Please read "INSPECTION" for more details.
8060 On error this function returns -1.
8062 (Added in 1.5.3)
8064 guestfs_inspect_get_minor_version
8066 int
8067 guestfs_inspect_get_minor_version (guestfs_h *g,
8068 const char *root);
8069 This returns the minor version number of the inspected operating
8071 system.
8072 If the version could not be determined, then 0 is returned.
8074 Please read "INSPECTION" for more details. See also
8076 "guestfs_inspect_get_major_version".
8077 On error this function returns -1.
8079 (Added in 1.5.3)
8081 guestfs_inspect_get_mountpoints
8083 char **
8084 guestfs_inspect_get_mountpoints (guestfs_h *g,
8085 const char *root);
8086 This returns a hash of where we think the filesystems associated with
8088 this operating system should be mounted. Callers should note that this
8089 is at best an educated guess made by reading configuration files such
8090 as /etc/fstab. In particular note that this may return filesystems
8091 which are non-existent or not mountable and callers should be prepared
8092 to handle or ignore failures if they try to mount them.
8093 Each element in the returned hashtable has a key which is the path of
8095 the mountpoint (eg. /boot) and a value which is the filesystem that
8096 would be mounted there (eg. /dev/sda1).
8097 Non-mounted devices such as swap devices are not returned in this list.
8099 For operating systems like Windows which still use drive letters, this
8101 call will only return an entry for the first drive "mounted on" /. For
8102 information about the mapping of drive letters to partitions, see
8103 "guestfs_inspect_get_drive_mappings".
8104 Please read "INSPECTION" for more details. See also
8106 "guestfs_inspect_get_filesystems".
8107 This function returns a NULL-terminated array of strings, or NULL if
8109 there was an error. The array of strings will always have length
8110 "2n+1", where "n" keys and values alternate, followed by the trailing
8111 NULL entry. The caller must free the strings and the array after use.
8112 (Added in 1.5.3)
8114 guestfs_inspect_get_osinfo
8116 char *
8117 guestfs_inspect_get_osinfo (guestfs_h *g,
8118 const char *root);
8119 This function returns a possible short ID for libosinfo corresponding
8121 to the guest.
8122 Note: The returned ID is only a guess by libguestfs, and nothing
8124 ensures that it actually exists in osinfo-db.
8125 If no ID could not be determined, then the string "unknown" is
8127 returned.
8128 This function returns a string, or NULL on error. The caller must free
8130 the returned string after use.
8131 (Added in 1.39.1)
8133 guestfs_inspect_get_package_format
8135 char *
8136 guestfs_inspect_get_package_format (guestfs_h *g,
8137 const char *root);
8138 This function and "guestfs_inspect_get_package_management" return the
8140 package format and package management tool used by the inspected
8141 operating system. For example for Fedora these functions would return
8142 "rpm" (package format), and "yum" or "dnf" (package management).
8143 This returns the string "unknown" if we could not determine the package
8145 format or if the operating system does not have a real packaging system
8146 (eg. Windows).
8147 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8149 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
8150 other strings.
8151 Please read "INSPECTION" for more details.
8153 This function returns a string, or NULL on error. The caller must free
8155 the returned string after use.
8156 (Added in 1.7.5)
8158 guestfs_inspect_get_package_management
8160 char *
8161 guestfs_inspect_get_package_management (guestfs_h *g,
8162 const char *root);
8163 "guestfs_inspect_get_package_format" and this function return the
8165 package format and package management tool used by the inspected
8166 operating system. For example for Fedora these functions would return
8167 "rpm" (package format), and "yum" or "dnf" (package management).
8168 This returns the string "unknown" if we could not determine the package
8170 management tool or if the operating system does not have a real
8171 packaging system (eg. Windows).
8172 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8174 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8175 "apk", "xbps". Future versions of libguestfs may return other strings.
8176 Please read "INSPECTION" for more details.
8178 This function returns a string, or NULL on error. The caller must free
8180 the returned string after use.
8181 (Added in 1.7.5)
8183 guestfs_inspect_get_product_name
8185 char *
8186 guestfs_inspect_get_product_name (guestfs_h *g,
8187 const char *root);
8188 This returns the product name of the inspected operating system. The
8190 product name is generally some freeform string which can be displayed
8191 to the user, but should not be parsed by programs.
8192 If the product name could not be determined, then the string "unknown"
8194 is returned.
8195 Please read "INSPECTION" for more details.
8197 This function returns a string, or NULL on error. The caller must free
8199 the returned string after use.
8200 (Added in 1.5.3)
8202 guestfs_inspect_get_product_variant
8204 char *
8205 guestfs_inspect_get_product_variant (guestfs_h *g,
8206 const char *root);
8207 This returns the product variant of the inspected operating system.
8209 For Windows guests, this returns the contents of the Registry key
8211 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8212 which is usually a string such as "Client" or "Server" (other values
8213 are possible). This can be used to distinguish consumer and enterprise
8214 versions of Windows that have the same version number (for example,
8215 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8216 is "Client" and the latter is "Server").
8217 For enterprise Linux guests, in future we intend this to return the
8219 product variant such as "Desktop", "Server" and so on. But this is not
8220 implemented at present.
8221 If the product variant could not be determined, then the string
8223 "unknown" is returned.
8224 Please read "INSPECTION" for more details. See also
8226 "guestfs_inspect_get_product_name",
8227 "guestfs_inspect_get_major_version".
8228 This function returns a string, or NULL on error. The caller must free
8230 the returned string after use.
8231 (Added in 1.9.13)
8233 guestfs_inspect_get_roots
8235 char **
8236 guestfs_inspect_get_roots (guestfs_h *g);
8237 This function is a convenient way to get the list of root devices, as
8239 returned from a previous call to "guestfs_inspect_os", but without
8240 redoing the whole inspection process.
8241 This returns an empty list if either no root devices were found or the
8243 caller has not called "guestfs_inspect_os".
8244 Please read "INSPECTION" for more details.
8246 This function returns a NULL-terminated array of strings (like
8248 environ(3)), or NULL if there was an error. The caller must free the
8249 strings and the array after use.
8250 (Added in 1.7.3)
8252 guestfs_inspect_get_type
8254 char *
8255 guestfs_inspect_get_type (guestfs_h *g,
8256 const char *root);
8257 This returns the type of the inspected operating system. Currently
8259 defined types are:
8260 "linux"
8262 Any Linux-based operating system.
8263 "windows"
8265 Any Microsoft Windows operating system.
8266 "freebsd"
8268 FreeBSD.
8269 "netbsd"
8271 NetBSD.
8272 "openbsd"
8274 OpenBSD.
8275 "hurd"
8277 GNU/Hurd.
8278 "dos"
8280 MS-DOS, FreeDOS and others.
8281 "minix"
8283 MINIX.
8284 "unknown"
8286 The operating system type could not be determined.
8287 Future versions of libguestfs may return other strings here. The
8289 caller should be prepared to handle any string.
8290 Please read "INSPECTION" for more details.
8292 This function returns a string, or NULL on error. The caller must free
8294 the returned string after use.
8295 (Added in 1.5.3)
8297 guestfs_inspect_get_windows_current_control_set
8299 char *
8300 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8301 const char *root);
8302 This returns the Windows CurrentControlSet of the inspected guest. The
8304 CurrentControlSet is a registry key name such as "ControlSet001".
8305 This call assumes that the guest is Windows and that the Registry could
8307 be examined by inspection. If this is not the case then an error is
8308 returned.
8309 Please read "INSPECTION" for more details.
8311 This function returns a string, or NULL on error. The caller must free
8313 the returned string after use.
8314 (Added in 1.9.17)
8316 guestfs_inspect_get_windows_software_hive
8318 char *
8319 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8320 const char *root);
8321 This returns the path to the hive (binary Windows Registry file)
8323 corresponding to HKLM\SOFTWARE.
8324 This call assumes that the guest is Windows and that the guest has a
8326 software hive file with the right name. If this is not the case then
8327 an error is returned. This call does not check that the hive is a
8328 valid Windows Registry hive.
8329 You can use "guestfs_hivex_open" to read or write to the hive.
8331 Please read "INSPECTION" for more details.
8333 This function returns a string, or NULL on error. The caller must free
8335 the returned string after use.
8336 (Added in 1.35.26)
8338 guestfs_inspect_get_windows_system_hive
8340 char *
8341 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8342 const char *root);
8343 This returns the path to the hive (binary Windows Registry file)
8345 corresponding to HKLM\SYSTEM.
8346 This call assumes that the guest is Windows and that the guest has a
8348 system hive file with the right name. If this is not the case then an
8349 error is returned. This call does not check that the hive is a valid
8350 Windows Registry hive.
8351 You can use "guestfs_hivex_open" to read or write to the hive.
8353 Please read "INSPECTION" for more details.
8355 This function returns a string, or NULL on error. The caller must free
8357 the returned string after use.
8358 (Added in 1.35.26)
8360 guestfs_inspect_get_windows_systemroot
8362 char *
8363 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8364 const char *root);
8365 This returns the Windows systemroot of the inspected guest. The
8367 systemroot is a directory path such as /WINDOWS.
8368 This call assumes that the guest is Windows and that the systemroot
8370 could be determined by inspection. If this is not the case then an
8371 error is returned.
8372 Please read "INSPECTION" for more details.
8374 This function returns a string, or NULL on error. The caller must free
8376 the returned string after use.
8377 (Added in 1.5.25)
8379 guestfs_inspect_is_live
8381 int
8382 guestfs_inspect_is_live (guestfs_h *g,
8383 const char *root);
8384 This function is deprecated. There is no replacement. Consult the API
8386 documentation in guestfs(3) for further information.
8387 Deprecated functions will not be removed from the API, but the fact
8389 that they are deprecated indicates that there are problems with correct
8390 use of these functions.
8391 This is deprecated and always returns "false".
8393 Please read "INSPECTION" for more details.
8395 This function returns a C truth value on success or -1 on error.
8397 (Added in 1.9.4)
8399 guestfs_inspect_is_multipart
8401 int
8402 guestfs_inspect_is_multipart (guestfs_h *g,
8403 const char *root);
8404 This function is deprecated. There is no replacement. Consult the API
8406 documentation in guestfs(3) for further information.
8407 Deprecated functions will not be removed from the API, but the fact
8409 that they are deprecated indicates that there are problems with correct
8410 use of these functions.
8411 This is deprecated and always returns "false".
8413 Please read "INSPECTION" for more details.
8415 This function returns a C truth value on success or -1 on error.
8417 (Added in 1.9.4)
8419 guestfs_inspect_is_netinst
8421 int
8422 guestfs_inspect_is_netinst (guestfs_h *g,
8423 const char *root);
8424 This function is deprecated. There is no replacement. Consult the API
8426 documentation in guestfs(3) for further information.
8427 Deprecated functions will not be removed from the API, but the fact
8429 that they are deprecated indicates that there are problems with correct
8430 use of these functions.
8431 This is deprecated and always returns "false".
8433 Please read "INSPECTION" for more details.
8435 This function returns a C truth value on success or -1 on error.
8437 (Added in 1.9.4)
8439 guestfs_inspect_list_applications
8441 struct guestfs_application_list *
8442 guestfs_inspect_list_applications (guestfs_h *g,
8443 const char *root);
8444 This function is deprecated. In new code, use the
8446 "guestfs_inspect_list_applications2" call instead.
8447 Deprecated functions will not be removed from the API, but the fact
8449 that they are deprecated indicates that there are problems with correct
8450 use of these functions.
8451 Return the list of applications installed in the operating system.
8453 Note: This call works differently from other parts of the inspection
8455 API. You have to call "guestfs_inspect_os", then
8456 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8457 calling this. Listing applications is a significantly more difficult
8458 operation which requires access to the full filesystem. Also note that
8459 unlike the other "guestfs_inspect_get_*" calls which are just returning
8460 data cached in the libguestfs handle, this call actually reads parts of
8461 the mounted filesystems during the call.
8462 This returns an empty list if the inspection code was not able to
8464 determine the list of applications.
8465 The application structure contains the following fields:
8467 "app_name"
8469 The name of the application. For Linux guests, this is the package
8470 name.
8471 "app_display_name"
8473 The display name of the application, sometimes localized to the
8474 install language of the guest operating system.
8475 If unavailable this is returned as an empty string "". Callers
8477 needing to display something can use "app_name" instead.
8478 "app_epoch"
8480 For package managers which use epochs, this contains the epoch of
8481 the package (an integer). If unavailable, this is returned as 0.
8482 "app_version"
8484 The version string of the application or package. If unavailable
8485 this is returned as an empty string "".
8486 "app_release"
8488 The release string of the application or package, for package
8489 managers that use this. If unavailable this is returned as an
8490 empty string "".
8491 "app_install_path"
8493 The installation path of the application (on operating systems such
8494 as Windows which use installation paths). This path is in the
8495 format used by the guest operating system, it is not a libguestfs
8496 path.
8497 If unavailable this is returned as an empty string "".
8499 "app_trans_path"
8501 The install path translated into a libguestfs path. If unavailable
8502 this is returned as an empty string "".
8503 "app_publisher"
8505 The name of the publisher of the application, for package managers
8506 that use this. If unavailable this is returned as an empty string
8507 "".
8508 "app_url"
8510 The URL (eg. upstream URL) of the application. If unavailable this
8511 is returned as an empty string "".
8512 "app_source_package"
8514 For packaging systems which support this, the name of the source
8515 package. If unavailable this is returned as an empty string "".
8516 "app_summary"
8518 A short (usually one line) description of the application or
8519 package. If unavailable this is returned as an empty string "".
8520 "app_description"
8522 A longer description of the application or package. If unavailable
8523 this is returned as an empty string "".
8524 Please read "INSPECTION" for more details.
8526 This function returns a "struct guestfs_application_list *", or NULL if
8528 there was an error. The caller must call
8529 "guestfs_free_application_list" after use.
8530 (Added in 1.7.8)
8532 guestfs_inspect_list_applications2
8534 struct guestfs_application2_list *
8535 guestfs_inspect_list_applications2 (guestfs_h *g,
8536 const char *root);
8537 Return the list of applications installed in the operating system.
8539 Note: This call works differently from other parts of the inspection
8541 API. You have to call "guestfs_inspect_os", then
8542 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8543 calling this. Listing applications is a significantly more difficult
8544 operation which requires access to the full filesystem. Also note that
8545 unlike the other "guestfs_inspect_get_*" calls which are just returning
8546 data cached in the libguestfs handle, this call actually reads parts of
8547 the mounted filesystems during the call.
8548 This returns an empty list if the inspection code was not able to
8550 determine the list of applications.
8551 The application structure contains the following fields:
8553 "app2_name"
8555 The name of the application. For Linux guests, this is the package
8556 name.
8557 "app2_display_name"
8559 The display name of the application, sometimes localized to the
8560 install language of the guest operating system.
8561 If unavailable this is returned as an empty string "". Callers
8563 needing to display something can use "app2_name" instead.
8564 "app2_epoch"
8566 For package managers which use epochs, this contains the epoch of
8567 the package (an integer). If unavailable, this is returned as 0.
8568 "app2_version"
8570 The version string of the application or package. If unavailable
8571 this is returned as an empty string "".
8572 "app2_release"
8574 The release string of the application or package, for package
8575 managers that use this. If unavailable this is returned as an
8576 empty string "".
8577 "app2_arch"
8579 The architecture string of the application or package, for package
8580 managers that use this. If unavailable this is returned as an
8581 empty string "".
8582 "app2_install_path"
8584 The installation path of the application (on operating systems such
8585 as Windows which use installation paths). This path is in the
8586 format used by the guest operating system, it is not a libguestfs
8587 path.
8588 If unavailable this is returned as an empty string "".
8590 "app2_trans_path"
8592 The install path translated into a libguestfs path. If unavailable
8593 this is returned as an empty string "".
8594 "app2_publisher"
8596 The name of the publisher of the application, for package managers
8597 that use this. If unavailable this is returned as an empty string
8598 "".
8599 "app2_url"
8601 The URL (eg. upstream URL) of the application. If unavailable this
8602 is returned as an empty string "".
8603 "app2_source_package"
8605 For packaging systems which support this, the name of the source
8606 package. If unavailable this is returned as an empty string "".
8607 "app2_summary"
8609 A short (usually one line) description of the application or
8610 package. If unavailable this is returned as an empty string "".
8611 "app2_description"
8613 A longer description of the application or package. If unavailable
8614 this is returned as an empty string "".
8615 Please read "INSPECTION" for more details.
8617 This function returns a "struct guestfs_application2_list *", or NULL
8619 if there was an error. The caller must call
8620 "guestfs_free_application2_list" after use.
8621 (Added in 1.19.56)
8623 guestfs_inspect_os
8625 char **
8626 guestfs_inspect_os (guestfs_h *g);
8627 This function uses other libguestfs functions and certain heuristics to
8629 inspect the disk(s) (usually disks belonging to a virtual machine),
8630 looking for operating systems.
8631 The list returned is empty if no operating systems were found.
8633 If one operating system was found, then this returns a list with a
8635 single element, which is the name of the root filesystem of this
8636 operating system. It is also possible for this function to return a
8637 list containing more than one element, indicating a dual-boot or multi-
8638 boot virtual machine, with each element being the root filesystem of
8639 one of the operating systems.
8640 You can pass the root string(s) returned to other
8642 "guestfs_inspect_get_*" functions in order to query further information
8643 about each operating system, such as the name and version.
8644 This function uses other libguestfs features such as "guestfs_mount_ro"
8646 and "guestfs_umount_all" in order to mount and unmount filesystems and
8647 look at the contents. This should be called with no disks currently
8648 mounted. The function may also use Augeas, so any existing Augeas
8649 handle will be closed.
8650 This function cannot decrypt encrypted disks. The caller must do that
8652 first (supplying the necessary keys) if the disk is encrypted.
8653 Please read "INSPECTION" for more details.
8655 See also "guestfs_list_filesystems".
8657 This function returns a NULL-terminated array of strings (like
8659 environ(3)), or NULL if there was an error. The caller must free the
8660 strings and the array after use.
8661 (Added in 1.5.3)
8663 guestfs_is_blockdev
8665 int
8666 guestfs_is_blockdev (guestfs_h *g,
8667 const char *path);
8668 This function is provided for backwards compatibility with earlier
8670 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8671 with no optional arguments.
8672 (Added in 1.5.10)
8674 guestfs_is_blockdev_opts
8676 int
8677 guestfs_is_blockdev_opts (guestfs_h *g,
8678 const char *path,
8679 ...);
8680 You may supply a list of optional arguments to this call. Use zero or
8682 more of the following pairs of parameters, and terminate the list with
8683 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8684 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8686 This returns "true" if and only if there is a block device with the
8688 given "path" name.
8689 If the optional flag "followsymlinks" is true, then a symlink (or chain
8691 of symlinks) that ends with a block device also causes the function to
8692 return true.
8693 This call only looks at files within the guest filesystem. Libguestfs
8695 partitions and block devices (eg. /dev/sda) cannot be used as the
8696 "path" parameter of this call.
8697 See also "guestfs_stat".
8699 This function returns a C truth value on success or -1 on error.
8701 (Added in 1.5.10)
8703 guestfs_is_blockdev_opts_va
8705 int
8706 guestfs_is_blockdev_opts_va (guestfs_h *g,
8707 const char *path,
8708 va_list args);
8709 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8711 See "CALLS WITH OPTIONAL ARGUMENTS".
8713 guestfs_is_blockdev_opts_argv
8715 int
8716 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8717 const char *path,
8718 const struct guestfs_is_blockdev_opts_argv *optargs);
8719 This is the "argv variant" of "guestfs_is_blockdev_opts".
8721 See "CALLS WITH OPTIONAL ARGUMENTS".
8723 guestfs_is_busy
8725 int
8726 guestfs_is_busy (guestfs_h *g);
8727 This always returns false. This function is deprecated with no
8729 replacement. Do not use this function.
8730 For more information on states, see guestfs(3).
8732 This function returns a C truth value on success or -1 on error.
8734 (Added in 1.0.2)
8736 guestfs_is_chardev
8738 int
8739 guestfs_is_chardev (guestfs_h *g,
8740 const char *path);
8741 This function is provided for backwards compatibility with earlier
8743 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8744 no optional arguments.
8745 (Added in 1.5.10)
8747 guestfs_is_chardev_opts
8749 int
8750 guestfs_is_chardev_opts (guestfs_h *g,
8751 const char *path,
8752 ...);
8753 You may supply a list of optional arguments to this call. Use zero or
8755 more of the following pairs of parameters, and terminate the list with
8756 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8757 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8759 This returns "true" if and only if there is a character device with the
8761 given "path" name.
8762 If the optional flag "followsymlinks" is true, then a symlink (or chain
8764 of symlinks) that ends with a chardev also causes the function to
8765 return true.
8766 See also "guestfs_stat".
8768 This function returns a C truth value on success or -1 on error.
8770 (Added in 1.5.10)
8772 guestfs_is_chardev_opts_va
8774 int
8775 guestfs_is_chardev_opts_va (guestfs_h *g,
8776 const char *path,
8777 va_list args);
8778 This is the "va_list variant" of "guestfs_is_chardev_opts".
8780 See "CALLS WITH OPTIONAL ARGUMENTS".
8782 guestfs_is_chardev_opts_argv
8784 int
8785 guestfs_is_chardev_opts_argv (guestfs_h *g,
8786 const char *path,
8787 const struct guestfs_is_chardev_opts_argv *optargs);
8788 This is the "argv variant" of "guestfs_is_chardev_opts".
8790 See "CALLS WITH OPTIONAL ARGUMENTS".
8792 guestfs_is_config
8794 int
8795 guestfs_is_config (guestfs_h *g);
8796 This returns true iff this handle is being configured (in the "CONFIG"
8798 state).
8799 For more information on states, see guestfs(3).
8801 This function returns a C truth value on success or -1 on error.
8803 (Added in 1.0.2)
8805 guestfs_is_dir
8807 int
8808 guestfs_is_dir (guestfs_h *g,
8809 const char *path);
8810 This function is provided for backwards compatibility with earlier
8812 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8813 optional arguments.
8814 (Added in 0.8)
8816 guestfs_is_dir_opts
8818 int
8819 guestfs_is_dir_opts (guestfs_h *g,
8820 const char *path,
8821 ...);
8822 You may supply a list of optional arguments to this call. Use zero or
8824 more of the following pairs of parameters, and terminate the list with
8825 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8826 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8828 This returns "true" if and only if there is a directory with the given
8830 "path" name. Note that it returns false for other objects like files.
8831 If the optional flag "followsymlinks" is true, then a symlink (or chain
8833 of symlinks) that ends with a directory also causes the function to
8834 return true.
8835 See also "guestfs_stat".
8837 This function returns a C truth value on success or -1 on error.
8839 (Added in 0.8)
8841 guestfs_is_dir_opts_va
8843 int
8844 guestfs_is_dir_opts_va (guestfs_h *g,
8845 const char *path,
8846 va_list args);
8847 This is the "va_list variant" of "guestfs_is_dir_opts".
8849 See "CALLS WITH OPTIONAL ARGUMENTS".
8851 guestfs_is_dir_opts_argv
8853 int
8854 guestfs_is_dir_opts_argv (guestfs_h *g,
8855 const char *path,
8856 const struct guestfs_is_dir_opts_argv *optargs);
8857 This is the "argv variant" of "guestfs_is_dir_opts".
8859 See "CALLS WITH OPTIONAL ARGUMENTS".
8861 guestfs_is_fifo
8863 int
8864 guestfs_is_fifo (guestfs_h *g,
8865 const char *path);
8866 This function is provided for backwards compatibility with earlier
8868 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8869 optional arguments.
8870 (Added in 1.5.10)
8872 guestfs_is_fifo_opts
8874 int
8875 guestfs_is_fifo_opts (guestfs_h *g,
8876 const char *path,
8877 ...);
8878 You may supply a list of optional arguments to this call. Use zero or
8880 more of the following pairs of parameters, and terminate the list with
8881 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8882 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8884 This returns "true" if and only if there is a FIFO (named pipe) with
8886 the given "path" name.
8887 If the optional flag "followsymlinks" is true, then a symlink (or chain
8889 of symlinks) that ends with a FIFO also causes the function to return
8890 true.
8891 See also "guestfs_stat".
8893 This function returns a C truth value on success or -1 on error.
8895 (Added in 1.5.10)
8897 guestfs_is_fifo_opts_va
8899 int
8900 guestfs_is_fifo_opts_va (guestfs_h *g,
8901 const char *path,
8902 va_list args);
8903 This is the "va_list variant" of "guestfs_is_fifo_opts".
8905 See "CALLS WITH OPTIONAL ARGUMENTS".
8907 guestfs_is_fifo_opts_argv
8909 int
8910 guestfs_is_fifo_opts_argv (guestfs_h *g,
8911 const char *path,
8912 const struct guestfs_is_fifo_opts_argv *optargs);
8913 This is the "argv variant" of "guestfs_is_fifo_opts".
8915 See "CALLS WITH OPTIONAL ARGUMENTS".
8917 guestfs_is_file
8919 int
8920 guestfs_is_file (guestfs_h *g,
8921 const char *path);
8922 This function is provided for backwards compatibility with earlier
8924 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
8925 optional arguments.
8926 (Added in 0.8)
8928 guestfs_is_file_opts
8930 int
8931 guestfs_is_file_opts (guestfs_h *g,
8932 const char *path,
8933 ...);
8934 You may supply a list of optional arguments to this call. Use zero or
8936 more of the following pairs of parameters, and terminate the list with
8937 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8938 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8940 This returns "true" if and only if there is a regular file with the
8942 given "path" name. Note that it returns false for other objects like
8943 directories.
8944 If the optional flag "followsymlinks" is true, then a symlink (or chain
8946 of symlinks) that ends with a file also causes the function to return
8947 true.
8948 See also "guestfs_stat".
8950 This function returns a C truth value on success or -1 on error.
8952 (Added in 0.8)
8954 guestfs_is_file_opts_va
8956 int
8957 guestfs_is_file_opts_va (guestfs_h *g,
8958 const char *path,
8959 va_list args);
8960 This is the "va_list variant" of "guestfs_is_file_opts".
8962 See "CALLS WITH OPTIONAL ARGUMENTS".
8964 guestfs_is_file_opts_argv
8966 int
8967 guestfs_is_file_opts_argv (guestfs_h *g,
8968 const char *path,
8969 const struct guestfs_is_file_opts_argv *optargs);
8970 This is the "argv variant" of "guestfs_is_file_opts".
8972 See "CALLS WITH OPTIONAL ARGUMENTS".
8974 guestfs_is_launching
8976 int
8977 guestfs_is_launching (guestfs_h *g);
8978 This returns true iff this handle is launching the subprocess (in the
8980 "LAUNCHING" state).
8981 For more information on states, see guestfs(3).
8983 This function returns a C truth value on success or -1 on error.
8985 (Added in 1.0.2)
8987 guestfs_is_lv
8989 int
8990 guestfs_is_lv (guestfs_h *g,
8991 const char *mountable);
8992 This command tests whether "mountable" is a logical volume, and returns
8994 true iff this is the case.
8995 This function returns a C truth value on success or -1 on error.
8997 (Added in 1.5.3)
8999 guestfs_is_ready
9001 int
9002 guestfs_is_ready (guestfs_h *g);
9003 This returns true iff this handle is ready to accept commands (in the
9005 "READY" state).
9006 For more information on states, see guestfs(3).
9008 This function returns a C truth value on success or -1 on error.
9010 (Added in 1.0.2)
9012 guestfs_is_socket
9014 int
9015 guestfs_is_socket (guestfs_h *g,
9016 const char *path);
9017 This function is provided for backwards compatibility with earlier
9019 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
9020 no optional arguments.
9021 (Added in 1.5.10)
9023 guestfs_is_socket_opts
9025 int
9026 guestfs_is_socket_opts (guestfs_h *g,
9027 const char *path,
9028 ...);
9029 You may supply a list of optional arguments to this call. Use zero or
9031 more of the following pairs of parameters, and terminate the list with
9032 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9033 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9035 This returns "true" if and only if there is a Unix domain socket with
9037 the given "path" name.
9038 If the optional flag "followsymlinks" is true, then a symlink (or chain
9040 of symlinks) that ends with a socket also causes the function to return
9041 true.
9042 See also "guestfs_stat".
9044 This function returns a C truth value on success or -1 on error.
9046 (Added in 1.5.10)
9048 guestfs_is_socket_opts_va
9050 int
9051 guestfs_is_socket_opts_va (guestfs_h *g,
9052 const char *path,
9053 va_list args);
9054 This is the "va_list variant" of "guestfs_is_socket_opts".
9056 See "CALLS WITH OPTIONAL ARGUMENTS".
9058 guestfs_is_socket_opts_argv
9060 int
9061 guestfs_is_socket_opts_argv (guestfs_h *g,
9062 const char *path,
9063 const struct guestfs_is_socket_opts_argv *optargs);
9064 This is the "argv variant" of "guestfs_is_socket_opts".
9066 See "CALLS WITH OPTIONAL ARGUMENTS".
9068 guestfs_is_symlink
9070 int
9071 guestfs_is_symlink (guestfs_h *g,
9072 const char *path);
9073 This returns "true" if and only if there is a symbolic link with the
9075 given "path" name.
9076 See also "guestfs_stat".
9078 This function returns a C truth value on success or -1 on error.
9080 (Added in 1.5.10)
9082 guestfs_is_whole_device
9084 int
9085 guestfs_is_whole_device (guestfs_h *g,
9086 const char *device);
9087 This returns "true" if and only if "device" refers to a whole block
9089 device. That is, not a partition or a logical device.
9090 This function returns a C truth value on success or -1 on error.
9092 (Added in 1.21.9)
9094 guestfs_is_zero
9096 int
9097 guestfs_is_zero (guestfs_h *g,
9098 const char *path);
9099 This returns true iff the file exists and the file is empty or it
9101 contains all zero bytes.
9102 This function returns a C truth value on success or -1 on error.
9104 (Added in 1.11.8)
9106 guestfs_is_zero_device
9108 int
9109 guestfs_is_zero_device (guestfs_h *g,
9110 const char *device);
9111 This returns true iff the device exists and contains all zero bytes.
9113 Note that for large devices this can take a long time to run.
9115 This function returns a C truth value on success or -1 on error.
9117 (Added in 1.11.8)
9119 guestfs_isoinfo
9121 struct guestfs_isoinfo *
9122 guestfs_isoinfo (guestfs_h *g,
9123 const char *isofile);
9124 This is the same as "guestfs_isoinfo_device" except that it works for
9126 an ISO file located inside some other mounted filesystem. Note that in
9127 the common case where you have added an ISO file as a libguestfs
9128 device, you would not call this. Instead you would call
9129 "guestfs_isoinfo_device".
9130 This function returns a "struct guestfs_isoinfo *", or NULL if there
9132 was an error. The caller must call "guestfs_free_isoinfo" after use.
9133 (Added in 1.17.19)
9135 guestfs_isoinfo_device
9137 struct guestfs_isoinfo *
9138 guestfs_isoinfo_device (guestfs_h *g,
9139 const char *device);
9140 "device" is an ISO device. This returns a struct of information read
9142 from the primary volume descriptor (the ISO equivalent of the
9143 superblock) of the device.
9144 Usually it is more efficient to use the isoinfo(1) command with the -d
9146 option on the host to analyze ISO files, instead of going through
9147 libguestfs.
9148 For information on the primary volume descriptor fields, see
9150 https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9151 This function returns a "struct guestfs_isoinfo *", or NULL if there
9153 was an error. The caller must call "guestfs_free_isoinfo" after use.
9154 (Added in 1.17.19)
9156 guestfs_journal_close
9158 int
9159 guestfs_journal_close (guestfs_h *g);
9160 Close the journal handle.
9162 This function returns 0 on success or -1 on error.
9164 This function depends on the feature "journal". See also
9166 "guestfs_feature_available".
9167 (Added in 1.23.11)
9169 guestfs_journal_get
9171 struct guestfs_xattr_list *
9172 guestfs_journal_get (guestfs_h *g);
9173 Read the current journal entry. This returns all the fields in the
9175 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
9176 field name (a string).
9177 The "attrval" is the field value (a binary blob, often but not always a
9179 string). Please note that "attrval" is a byte array, not a
9180 \0-terminated C string.
9181 The length of data may be truncated to the data threshold (see:
9183 "guestfs_journal_set_data_threshold",
9184 "guestfs_journal_get_data_threshold").
9185 If you set the data threshold to unlimited (0) then this call can read
9187 a journal entry of any size, ie. it is not limited by the libguestfs
9188 protocol.
9189 This function returns a "struct guestfs_xattr_list *", or NULL if there
9191 was an error. The caller must call "guestfs_free_xattr_list" after
9192 use.
9193 This function depends on the feature "journal". See also
9195 "guestfs_feature_available".
9196 (Added in 1.23.11)
9198 guestfs_journal_get_data_threshold
9200 int64_t
9201 guestfs_journal_get_data_threshold (guestfs_h *g);
9202 Get the current data threshold for reading journal entries. This is a
9204 hint to the journal that it may truncate data fields to this size when
9205 reading them (note also that it may not truncate them). If this
9206 returns 0, then the threshold is unlimited.
9207 See also "guestfs_journal_set_data_threshold".
9209 On error this function returns -1.
9211 This function depends on the feature "journal". See also
9213 "guestfs_feature_available".
9214 (Added in 1.23.11)
9216 guestfs_journal_get_realtime_usec
9218 int64_t
9219 guestfs_journal_get_realtime_usec (guestfs_h *g);
9220 Get the realtime (wallclock) timestamp of the current journal entry.
9222 On error this function returns -1.
9224 This function depends on the feature "journal". See also
9226 "guestfs_feature_available".
9227 (Added in 1.27.18)
9229 guestfs_journal_next
9231 int
9232 guestfs_journal_next (guestfs_h *g);
9233 Move to the next journal entry. You have to call this at least once
9235 after opening the handle before you are able to read data.
9236 The returned boolean tells you if there are any more journal records to
9238 read. "true" means you can read the next record (eg. using
9239 "guestfs_journal_get"), and "false" means you have reached the end of
9240 the journal.
9241 This function returns a C truth value on success or -1 on error.
9243 This function depends on the feature "journal". See also
9245 "guestfs_feature_available".
9246 (Added in 1.23.11)
9248 guestfs_journal_open
9250 int
9251 guestfs_journal_open (guestfs_h *g,
9252 const char *directory);
9253 Open the systemd journal located in directory. Any previously opened
9255 journal handle is closed.
9256 The contents of the journal can be read using "guestfs_journal_next"
9258 and "guestfs_journal_get".
9259 After you have finished using the journal, you should close the handle
9261 by calling "guestfs_journal_close".
9262 This function returns 0 on success or -1 on error.
9264 This function depends on the feature "journal". See also
9266 "guestfs_feature_available".
9267 (Added in 1.23.11)
9269 guestfs_journal_set_data_threshold
9271 int
9272 guestfs_journal_set_data_threshold (guestfs_h *g,
9273 int64_t threshold);
9274 Set the data threshold for reading journal entries. This is a hint to
9276 the journal that it may truncate data fields to this size when reading
9277 them (note also that it may not truncate them). If you set this to 0,
9278 then the threshold is unlimited.
9279 See also "guestfs_journal_get_data_threshold".
9281 This function returns 0 on success or -1 on error.
9283 This function depends on the feature "journal". See also
9285 "guestfs_feature_available".
9286 (Added in 1.23.11)
9288 guestfs_journal_skip
9290 int64_t
9291 guestfs_journal_skip (guestfs_h *g,
9292 int64_t skip);
9293 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9295 The number of entries actually skipped is returned (note "rskip ≥ 0").
9297 If this is not the same as the absolute value of the skip parameter
9298 ("|skip|") you passed in then it means you have reached the end or the
9299 start of the journal.
9300 On error this function returns -1.
9302 This function depends on the feature "journal". See also
9304 "guestfs_feature_available".
9305 (Added in 1.23.11)
9307 guestfs_kill_subprocess
9309 int
9310 guestfs_kill_subprocess (guestfs_h *g);
9311 This function is deprecated. In new code, use the "guestfs_shutdown"
9313 call instead.
9314 Deprecated functions will not be removed from the API, but the fact
9316 that they are deprecated indicates that there are problems with correct
9317 use of these functions.
9318 This kills the hypervisor.
9320 Do not call this. See: "guestfs_shutdown" instead.
9322 This function returns 0 on success or -1 on error.
9324 (Added in 0.3)
9326 guestfs_launch
9328 int
9329 guestfs_launch (guestfs_h *g);
9330 You should call this after configuring the handle (eg. adding drives)
9332 but before performing any actions.
9333 Do not call "guestfs_launch" twice on the same handle. Although it
9335 will not give an error (for historical reasons), the precise behaviour
9336 when you do this is not well defined. Handles are very cheap to
9337 create, so create a new one for each launch.
9338 This function returns 0 on success or -1 on error.
9340 This long-running command can generate progress notification messages
9342 so that the caller can display a progress bar or indicator. To receive
9343 these messages, the caller must register a progress event callback.
9344 See "GUESTFS_EVENT_PROGRESS".
9345 (Added in 0.3)
9347 guestfs_lchown
9349 int
9350 guestfs_lchown (guestfs_h *g,
9351 int owner,
9352 int group,
9353 const char *path);
9354 Change the file owner to "owner" and group to "group". This is like
9356 "guestfs_chown" but if "path" is a symlink then the link itself is
9357 changed, not the target.
9358 Only numeric uid and gid are supported. If you want to use names, you
9360 will need to locate and parse the password file yourself (Augeas
9361 support makes this relatively easy).
9362 This function returns 0 on success or -1 on error.
9364 (Added in 1.0.77)
9366 guestfs_ldmtool_create_all
9368 int
9369 guestfs_ldmtool_create_all (guestfs_h *g);
9370 This function scans all block devices looking for Windows dynamic disk
9372 volumes and partitions, and creates devices for any that were found.
9373 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9375 return all devices.
9376 Note that you don't normally need to call this explicitly, since it is
9378 done automatically at "guestfs_launch" time. However you might want to
9379 call this function if you have hotplugged disks or have just created a
9380 Windows dynamic disk.
9381 This function returns 0 on success or -1 on error.
9383 This function depends on the feature "ldm". See also
9385 "guestfs_feature_available".
9386 (Added in 1.20.0)
9388 guestfs_ldmtool_diskgroup_disks
9390 char **
9391 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9392 const char *diskgroup);
9393 Return the disks in a Windows dynamic disk group. The "diskgroup"
9395 parameter should be the GUID of a disk group, one element from the list
9396 returned by "guestfs_ldmtool_scan".
9397 This function returns a NULL-terminated array of strings (like
9399 environ(3)), or NULL if there was an error. The caller must free the
9400 strings and the array after use.
9401 This function depends on the feature "ldm". See also
9403 "guestfs_feature_available".
9404 (Added in 1.20.0)
9406 guestfs_ldmtool_diskgroup_name
9408 char *
9409 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9410 const char *diskgroup);
9411 Return the name of a Windows dynamic disk group. The "diskgroup"
9413 parameter should be the GUID of a disk group, one element from the list
9414 returned by "guestfs_ldmtool_scan".
9415 This function returns a string, or NULL on error. The caller must free
9417 the returned string after use.
9418 This function depends on the feature "ldm". See also
9420 "guestfs_feature_available".
9421 (Added in 1.20.0)
9423 guestfs_ldmtool_diskgroup_volumes
9425 char **
9426 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9427 const char *diskgroup);
9428 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9430 parameter should be the GUID of a disk group, one element from the list
9431 returned by "guestfs_ldmtool_scan".
9432 This function returns a NULL-terminated array of strings (like
9434 environ(3)), or NULL if there was an error. The caller must free the
9435 strings and the array after use.
9436 This function depends on the feature "ldm". See also
9438 "guestfs_feature_available".
9439 (Added in 1.20.0)
9441 guestfs_ldmtool_remove_all
9443 int
9444 guestfs_ldmtool_remove_all (guestfs_h *g);
9445 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9447 removes the device mapper mappings for all Windows dynamic disk volumes
9448 This function returns 0 on success or -1 on error.
9450 This function depends on the feature "ldm". See also
9452 "guestfs_feature_available".
9453 (Added in 1.20.0)
9455 guestfs_ldmtool_scan
9457 char **
9458 guestfs_ldmtool_scan (guestfs_h *g);
9459 This function scans for Windows dynamic disks. It returns a list of
9461 identifiers (GUIDs) for all disk groups that were found. These
9462 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9463 This function scans all block devices. To scan a subset of block
9465 devices, call "guestfs_ldmtool_scan_devices" instead.
9466 This function returns a NULL-terminated array of strings (like
9468 environ(3)), or NULL if there was an error. The caller must free the
9469 strings and the array after use.
9470 This function depends on the feature "ldm". See also
9472 "guestfs_feature_available".
9473 (Added in 1.20.0)
9475 guestfs_ldmtool_scan_devices
9477 char **
9478 guestfs_ldmtool_scan_devices (guestfs_h *g,
9479 char *const *devices);
9480 This function scans for Windows dynamic disks. It returns a list of
9482 identifiers (GUIDs) for all disk groups that were found. These
9483 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9484 The parameter "devices" is a list of block devices which are scanned.
9486 If this list is empty, all block devices are scanned.
9487 This function returns a NULL-terminated array of strings (like
9489 environ(3)), or NULL if there was an error. The caller must free the
9490 strings and the array after use.
9491 This function depends on the feature "ldm". See also
9493 "guestfs_feature_available".
9494 (Added in 1.20.0)
9496 guestfs_ldmtool_volume_hint
9498 char *
9499 guestfs_ldmtool_volume_hint (guestfs_h *g,
9500 const char *diskgroup,
9501 const char *volume);
9502 Return the hint field of the volume named "volume" in the disk group
9504 with GUID "diskgroup". This may not be defined, in which case the
9505 empty string is returned. The hint field is often, though not always,
9506 the name of a Windows drive, eg. "E:".
9507 This function returns a string, or NULL on error. The caller must free
9509 the returned string after use.
9510 This function depends on the feature "ldm". See also
9512 "guestfs_feature_available".
9513 (Added in 1.20.0)
9515 guestfs_ldmtool_volume_partitions
9517 char **
9518 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9519 const char *diskgroup,
9520 const char *volume);
9521 Return the list of partitions in the volume named "volume" in the disk
9523 group with GUID "diskgroup".
9524 This function returns a NULL-terminated array of strings (like
9526 environ(3)), or NULL if there was an error. The caller must free the
9527 strings and the array after use.
9528 This function depends on the feature "ldm". See also
9530 "guestfs_feature_available".
9531 (Added in 1.20.0)
9533 guestfs_ldmtool_volume_type
9535 char *
9536 guestfs_ldmtool_volume_type (guestfs_h *g,
9537 const char *diskgroup,
9538 const char *volume);
9539 Return the type of the volume named "volume" in the disk group with
9541 GUID "diskgroup".
9542 Possible volume types that can be returned here include: "simple",
9544 "spanned", "striped", "mirrored", "raid5". Other types may also be
9545 returned.
9546 This function returns a string, or NULL on error. The caller must free
9548 the returned string after use.
9549 This function depends on the feature "ldm". See also
9551 "guestfs_feature_available".
9552 (Added in 1.20.0)
9554 guestfs_lgetxattr
9556 char *
9557 guestfs_lgetxattr (guestfs_h *g,
9558 const char *path,
9559 const char *name,
9560 size_t *size_r);
9561 Get a single extended attribute from file "path" named "name". If
9563 "path" is a symlink, then this call returns an extended attribute from
9564 the symlink.
9565 Normally it is better to get all extended attributes from a file in one
9567 go by calling "guestfs_getxattrs". However some Linux filesystem
9568 implementations are buggy and do not provide a way to list out
9569 attributes. For these filesystems (notably ntfs-3g) you have to know
9570 the names of the extended attributes you want in advance and call this
9571 function.
9572 Extended attribute values are blobs of binary data. If there is no
9574 extended attribute named "name", this returns an error.
9575 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9577 This function returns a buffer, or NULL on error. The size of the
9579 returned buffer is written to *size_r. The caller must free the
9580 returned buffer after use.
9581 This function depends on the feature "linuxxattrs". See also
9583 "guestfs_feature_available".
9584 (Added in 1.7.24)
9586 guestfs_lgetxattrs
9588 struct guestfs_xattr_list *
9589 guestfs_lgetxattrs (guestfs_h *g,
9590 const char *path);
9591 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9593 link, then it returns the extended attributes of the link itself.
9594 This function returns a "struct guestfs_xattr_list *", or NULL if there
9596 was an error. The caller must call "guestfs_free_xattr_list" after
9597 use.
9598 This function depends on the feature "linuxxattrs". See also
9600 "guestfs_feature_available".
9601 (Added in 1.0.59)
9603 guestfs_list_9p
9605 char **
9606 guestfs_list_9p (guestfs_h *g);
9607 List all 9p filesystems attached to the guest. A list of mount tags is
9609 returned.
9610 This function returns a NULL-terminated array of strings (like
9612 environ(3)), or NULL if there was an error. The caller must free the
9613 strings and the array after use.
9614 (Added in 1.11.12)
9616 guestfs_list_devices
9618 char **
9619 guestfs_list_devices (guestfs_h *g);
9620 List all the block devices.
9622 The full block device names are returned, eg. /dev/sda.
9624 See also "guestfs_list_filesystems".
9626 This function returns a NULL-terminated array of strings (like
9628 environ(3)), or NULL if there was an error. The caller must free the
9629 strings and the array after use.
9630 (Added in 0.4)
9632 guestfs_list_disk_labels
9634 char **
9635 guestfs_list_disk_labels (guestfs_h *g);
9636 If you add drives using the optional "label" parameter of
9638 "guestfs_add_drive_opts", you can use this call to map between disk
9639 labels, and raw block device and partition names (like /dev/sda and
9640 /dev/sda1).
9641 This returns a hashtable, where keys are the disk labels (without the
9643 /dev/disk/guestfs prefix), and the values are the full raw block device
9644 and partition names (eg. /dev/sda and /dev/sda1).
9645 This function returns a NULL-terminated array of strings, or NULL if
9647 there was an error. The array of strings will always have length
9648 "2n+1", where "n" keys and values alternate, followed by the trailing
9649 NULL entry. The caller must free the strings and the array after use.
9650 (Added in 1.19.49)
9652 guestfs_list_dm_devices
9654 char **
9655 guestfs_list_dm_devices (guestfs_h *g);
9656 List all device mapper devices.
9658 The returned list contains /dev/mapper/* devices, eg. ones created by a
9660 previous call to "guestfs_luks_open".
9661 Device mapper devices which correspond to logical volumes are not
9663 returned in this list. Call "guestfs_lvs" if you want to list logical
9664 volumes.
9665 This function returns a NULL-terminated array of strings (like
9667 environ(3)), or NULL if there was an error. The caller must free the
9668 strings and the array after use.
9669 (Added in 1.11.15)
9671 guestfs_list_filesystems
9673 char **
9674 guestfs_list_filesystems (guestfs_h *g);
9675 This inspection command looks for filesystems on partitions, block
9677 devices and logical volumes, returning a list of "mountables"
9678 containing filesystems and their type.
9679 The return value is a hash, where the keys are the devices containing
9681 filesystems, and the values are the filesystem types. For example:
9682 "/dev/sda1" => "ntfs"
9684 "/dev/sda2" => "ext2"
9685 "/dev/vg_guest/lv_root" => "ext4"
9686 "/dev/vg_guest/lv_swap" => "swap"
9687 The key is not necessarily a block device. It may also be an opaque
9689 ‘mountable’ string which can be passed to "guestfs_mount".
9690 The value can have the special value "unknown", meaning the content of
9692 the device is undetermined or empty. "swap" means a Linux swap
9693 partition.
9694 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9696 might have included "guestfs_mount" and "guestfs_umount", and therefore
9697 you had to use this soon after launch and only when nothing else was
9698 mounted. This restriction is removed in libguestfs ≥ 1.38.
9699 Not all of the filesystems returned will be mountable. In particular,
9701 swap partitions are returned in the list. Also this command does not
9702 check that each filesystem found is valid and mountable, and some
9703 filesystems might be mountable but require special options.
9704 Filesystems may not all belong to a single logical operating system
9705 (use "guestfs_inspect_os" to look for OSes).
9706 This function returns a NULL-terminated array of strings, or NULL if
9708 there was an error. The array of strings will always have length
9709 "2n+1", where "n" keys and values alternate, followed by the trailing
9710 NULL entry. The caller must free the strings and the array after use.
9711 (Added in 1.5.15)
9713 guestfs_list_ldm_partitions
9715 char **
9716 guestfs_list_ldm_partitions (guestfs_h *g);
9717 This function returns all Windows dynamic disk partitions that were
9719 found at launch time. It returns a list of device names.
9720 This function returns a NULL-terminated array of strings (like
9722 environ(3)), or NULL if there was an error. The caller must free the
9723 strings and the array after use.
9724 This function depends on the feature "ldm". See also
9726 "guestfs_feature_available".
9727 (Added in 1.20.0)
9729 guestfs_list_ldm_volumes
9731 char **
9732 guestfs_list_ldm_volumes (guestfs_h *g);
9733 This function returns all Windows dynamic disk volumes that were found
9735 at launch time. It returns a list of device names.
9736 This function returns a NULL-terminated array of strings (like
9738 environ(3)), or NULL if there was an error. The caller must free the
9739 strings and the array after use.
9740 This function depends on the feature "ldm". See also
9742 "guestfs_feature_available".
9743 (Added in 1.20.0)
9745 guestfs_list_md_devices
9747 char **
9748 guestfs_list_md_devices (guestfs_h *g);
9749 List all Linux md devices.
9751 This function returns a NULL-terminated array of strings (like
9753 environ(3)), or NULL if there was an error. The caller must free the
9754 strings and the array after use.
9755 (Added in 1.15.4)
9757 guestfs_list_partitions
9759 char **
9760 guestfs_list_partitions (guestfs_h *g);
9761 List all the partitions detected on all block devices.
9763 The full partition device names are returned, eg. /dev/sda1
9765 This does not return logical volumes. For that you will need to call
9767 "guestfs_lvs".
9768 See also "guestfs_list_filesystems".
9770 This function returns a NULL-terminated array of strings (like
9772 environ(3)), or NULL if there was an error. The caller must free the
9773 strings and the array after use.
9774 (Added in 0.4)
9776 guestfs_ll
9778 char *
9779 guestfs_ll (guestfs_h *g,
9780 const char *directory);
9781 List the files in directory (relative to the root directory, there is
9783 no cwd) in the format of "ls -la".
9784 This command is mostly useful for interactive sessions. It is not
9786 intended that you try to parse the output string.
9787 This function returns a string, or NULL on error. The caller must free
9789 the returned string after use.
9790 (Added in 0.4)
9792 guestfs_llz
9794 char *
9795 guestfs_llz (guestfs_h *g,
9796 const char *directory);
9797 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9799 call instead.
9800 Deprecated functions will not be removed from the API, but the fact
9802 that they are deprecated indicates that there are problems with correct
9803 use of these functions.
9804 List the files in directory in the format of "ls -laZ".
9806 This command is mostly useful for interactive sessions. It is not
9808 intended that you try to parse the output string.
9809 This function returns a string, or NULL on error. The caller must free
9811 the returned string after use.
9812 (Added in 1.17.6)
9814 guestfs_ln
9816 int
9817 guestfs_ln (guestfs_h *g,
9818 const char *target,
9819 const char *linkname);
9820 This command creates a hard link.
9822 This function returns 0 on success or -1 on error.
9824 (Added in 1.0.66)
9826 guestfs_ln_f
9828 int
9829 guestfs_ln_f (guestfs_h *g,
9830 const char *target,
9831 const char *linkname);
9832 This command creates a hard link, removing the link "linkname" if it
9834 exists already.
9835 This function returns 0 on success or -1 on error.
9837 (Added in 1.0.66)
9839 guestfs_ln_s
9841 int
9842 guestfs_ln_s (guestfs_h *g,
9843 const char *target,
9844 const char *linkname);
9845 This command creates a symbolic link using the "ln -s" command.
9847 This function returns 0 on success or -1 on error.
9849 (Added in 1.0.66)
9851 guestfs_ln_sf
9853 int
9854 guestfs_ln_sf (guestfs_h *g,
9855 const char *target,
9856 const char *linkname);
9857 This command creates a symbolic link using the "ln -sf" command, The -f
9859 option removes the link ("linkname") if it exists already.
9860 This function returns 0 on success or -1 on error.
9862 (Added in 1.0.66)
9864 guestfs_lremovexattr
9866 int
9867 guestfs_lremovexattr (guestfs_h *g,
9868 const char *xattr,
9869 const char *path);
9870 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9872 link, then it removes an extended attribute of the link itself.
9873 This function returns 0 on success or -1 on error.
9875 This function depends on the feature "linuxxattrs". See also
9877 "guestfs_feature_available".
9878 (Added in 1.0.59)
9880 guestfs_ls
9882 char **
9883 guestfs_ls (guestfs_h *g,
9884 const char *directory);
9885 List the files in directory (relative to the root directory, there is
9887 no cwd). The "." and ".." entries are not returned, but hidden files
9888 are shown.
9889 This function returns a NULL-terminated array of strings (like
9891 environ(3)), or NULL if there was an error. The caller must free the
9892 strings and the array after use.
9893 (Added in 0.4)
9895 guestfs_ls0
9897 int
9898 guestfs_ls0 (guestfs_h *g,
9899 const char *dir,
9900 const char *filenames);
9901 This specialized command is used to get a listing of the filenames in
9903 the directory "dir". The list of filenames is written to the local
9904 file filenames (on the host).
9905 In the output file, the filenames are separated by "\0" characters.
9907 "." and ".." are not returned. The filenames are not sorted.
9909 This function returns 0 on success or -1 on error.
9911 (Added in 1.19.32)
9913 guestfs_lsetxattr
9915 int
9916 guestfs_lsetxattr (guestfs_h *g,
9917 const char *xattr,
9918 const char *val,
9919 int vallen,
9920 const char *path);
9921 This is the same as "guestfs_setxattr", but if "path" is a symbolic
9923 link, then it sets an extended attribute of the link itself.
9924 This function returns 0 on success or -1 on error.
9926 This function depends on the feature "linuxxattrs". See also
9928 "guestfs_feature_available".
9929 (Added in 1.0.59)
9931 guestfs_lstat
9933 struct guestfs_stat *
9934 guestfs_lstat (guestfs_h *g,
9935 const char *path);
9936 This function is deprecated. In new code, use the "guestfs_lstatns"
9938 call instead.
9939 Deprecated functions will not be removed from the API, but the fact
9941 that they are deprecated indicates that there are problems with correct
9942 use of these functions.
9943 Returns file information for the given "path".
9945 This is the same as "guestfs_stat" except that if "path" is a symbolic
9947 link, then the link is stat-ed, not the file it refers to.
9948 This is the same as the lstat(2) system call.
9950 This function returns a "struct guestfs_stat *", or NULL if there was
9952 an error. The caller must call "guestfs_free_stat" after use.
9953 (Added in 1.9.2)
9955 guestfs_lstatlist
9957 struct guestfs_stat_list *
9958 guestfs_lstatlist (guestfs_h *g,
9959 const char *path,
9960 char *const *names);
9961 This function is deprecated. In new code, use the
9963 "guestfs_lstatnslist" call instead.
9964 Deprecated functions will not be removed from the API, but the fact
9966 that they are deprecated indicates that there are problems with correct
9967 use of these functions.
9968 This call allows you to perform the "guestfs_lstat" operation on
9970 multiple files, where all files are in the directory "path". "names"
9971 is the list of files from this directory.
9972 On return you get a list of stat structs, with a one-to-one
9974 correspondence to the "names" list. If any name did not exist or could
9975 not be lstat'd, then the "st_ino" field of that structure is set to
9976 "-1".
9977 This call is intended for programs that want to efficiently list a
9979 directory contents without making many round-trips. See also
9980 "guestfs_lxattrlist" for a similarly efficient call for getting
9981 extended attributes.
9982 This function returns a "struct guestfs_stat_list *", or NULL if there
9984 was an error. The caller must call "guestfs_free_stat_list" after use.
9985 (Added in 1.0.77)
9987 guestfs_lstatns
9989 struct guestfs_statns *
9990 guestfs_lstatns (guestfs_h *g,
9991 const char *path);
9992 Returns file information for the given "path".
9994 This is the same as "guestfs_statns" except that if "path" is a
9996 symbolic link, then the link is stat-ed, not the file it refers to.
9997 This is the same as the lstat(2) system call.
9999 This function returns a "struct guestfs_statns *", or NULL if there was
10001 an error. The caller must call "guestfs_free_statns" after use.
10002 (Added in 1.27.53)
10004 guestfs_lstatnslist
10006 struct guestfs_statns_list *
10007 guestfs_lstatnslist (guestfs_h *g,
10008 const char *path,
10009 char *const *names);
10010 This call allows you to perform the "guestfs_lstatns" operation on
10012 multiple files, where all files are in the directory "path". "names"
10013 is the list of files from this directory.
10014 On return you get a list of stat structs, with a one-to-one
10016 correspondence to the "names" list. If any name did not exist or could
10017 not be lstat'd, then the "st_ino" field of that structure is set to
10018 "-1".
10019 This call is intended for programs that want to efficiently list a
10021 directory contents without making many round-trips. See also
10022 "guestfs_lxattrlist" for a similarly efficient call for getting
10023 extended attributes.
10024 This function returns a "struct guestfs_statns_list *", or NULL if
10026 there was an error. The caller must call "guestfs_free_statns_list"
10027 after use.
10028 (Added in 1.27.53)
10030 guestfs_luks_add_key
10032 int
10033 guestfs_luks_add_key (guestfs_h *g,
10034 const char *device,
10035 const char *key,
10036 const char *newkey,
10037 int keyslot);
10038 This command adds a new key on LUKS device "device". "key" is any
10040 existing key, and is used to access the device. "newkey" is the new
10041 key to add. "keyslot" is the key slot that will be replaced.
10042 Note that if "keyslot" already contains a key, then this command will
10044 fail. You have to use "guestfs_luks_kill_slot" first to remove that
10045 key.
10046 This function returns 0 on success or -1 on error.
10048 This function takes a key or passphrase parameter which could contain
10050 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10051 information.
10052 This function depends on the feature "luks". See also
10054 "guestfs_feature_available".
10055 (Added in 1.5.2)
10057 guestfs_luks_close
10059 int
10060 guestfs_luks_close (guestfs_h *g,
10061 const char *device);
10062 This closes a LUKS device that was created earlier by
10064 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
10065 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10066 and not the name of the underlying block device.
10067 This function returns 0 on success or -1 on error.
10069 This function depends on the feature "luks". See also
10071 "guestfs_feature_available".
10072 (Added in 1.5.1)
10074 guestfs_luks_format
10076 int
10077 guestfs_luks_format (guestfs_h *g,
10078 const char *device,
10079 const char *key,
10080 int keyslot);
10081 This command erases existing data on "device" and formats the device as
10083 a LUKS encrypted device. "key" is the initial key, which is added to
10084 key slot "keyslot". (LUKS supports 8 key slots, numbered 0-7).
10085 This function returns 0 on success or -1 on error.
10087 This function takes a key or passphrase parameter which could contain
10089 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10090 information.
10091 This function depends on the feature "luks". See also
10093 "guestfs_feature_available".
10094 (Added in 1.5.2)
10096 guestfs_luks_format_cipher
10098 int
10099 guestfs_luks_format_cipher (guestfs_h *g,
10100 const char *device,
10101 const char *key,
10102 int keyslot,
10103 const char *cipher);
10104 This command is the same as "guestfs_luks_format" but it also allows
10106 you to set the "cipher" used.
10107 This function returns 0 on success or -1 on error.
10109 This function takes a key or passphrase parameter which could contain
10111 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10112 information.
10113 This function depends on the feature "luks". See also
10115 "guestfs_feature_available".
10116 (Added in 1.5.2)
10118 guestfs_luks_kill_slot
10120 int
10121 guestfs_luks_kill_slot (guestfs_h *g,
10122 const char *device,
10123 const char *key,
10124 int keyslot);
10125 This command deletes the key in key slot "keyslot" from the encrypted
10127 LUKS device "device". "key" must be one of the other keys.
10128 This function returns 0 on success or -1 on error.
10130 This function takes a key or passphrase parameter which could contain
10132 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10133 information.
10134 This function depends on the feature "luks". See also
10136 "guestfs_feature_available".
10137 (Added in 1.5.2)
10139 guestfs_luks_open
10141 int
10142 guestfs_luks_open (guestfs_h *g,
10143 const char *device,
10144 const char *key,
10145 const char *mapname);
10146 This command opens a block device which has been encrypted according to
10148 the Linux Unified Key Setup (LUKS) standard.
10149 "device" is the encrypted block device or partition.
10151 The caller must supply one of the keys associated with the LUKS block
10153 device, in the "key" parameter.
10154 This creates a new block device called /dev/mapper/mapname. Reads and
10156 writes to this block device are decrypted from and encrypted to the
10157 underlying "device" respectively.
10158 If this block device contains LVM volume groups, then calling
10160 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10161 visible.
10162 Use "guestfs_list_dm_devices" to list all device mapper devices.
10164 This function returns 0 on success or -1 on error.
10166 This function takes a key or passphrase parameter which could contain
10168 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10169 information.
10170 This function depends on the feature "luks". See also
10172 "guestfs_feature_available".
10173 (Added in 1.5.1)
10175 guestfs_luks_open_ro
10177 int
10178 guestfs_luks_open_ro (guestfs_h *g,
10179 const char *device,
10180 const char *key,
10181 const char *mapname);
10182 This is the same as "guestfs_luks_open" except that a read-only mapping
10184 is created.
10185 This function returns 0 on success or -1 on error.
10187 This function takes a key or passphrase parameter which could contain
10189 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10190 information.
10191 This function depends on the feature "luks". See also
10193 "guestfs_feature_available".
10194 (Added in 1.5.1)
10196 guestfs_luks_uuid
10198 char *
10199 guestfs_luks_uuid (guestfs_h *g,
10200 const char *device);
10201 This returns the UUID of the LUKS device "device".
10203 This function returns a string, or NULL on error. The caller must free
10205 the returned string after use.
10206 This function depends on the feature "luks". See also
10208 "guestfs_feature_available".
10209 (Added in 1.41.9)
10211 guestfs_lvcreate
10213 int
10214 guestfs_lvcreate (guestfs_h *g,
10215 const char *logvol,
10216 const char *volgroup,
10217 int mbytes);
10218 This creates an LVM logical volume called "logvol" on the volume group
10220 "volgroup", with "size" megabytes.
10221 This function returns 0 on success or -1 on error.
10223 This function depends on the feature "lvm2". See also
10225 "guestfs_feature_available".
10226 (Added in 0.8)
10228 guestfs_lvcreate_free
10230 int
10231 guestfs_lvcreate_free (guestfs_h *g,
10232 const char *logvol,
10233 const char *volgroup,
10234 int percent);
10235 Create an LVM logical volume called /dev/volgroup/logvol, using
10237 approximately "percent" % of the free space remaining in the volume
10238 group. Most usefully, when "percent" is 100 this will create the
10239 largest possible LV.
10240 This function returns 0 on success or -1 on error.
10242 This function depends on the feature "lvm2". See also
10244 "guestfs_feature_available".
10245 (Added in 1.17.18)
10247 guestfs_lvm_canonical_lv_name
10249 char *
10250 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10251 const char *lvname);
10252 This converts alternative naming schemes for LVs that you might find to
10254 the canonical name. For example, /dev/mapper/VG-LV is converted to
10255 /dev/VG/LV.
10256 This command returns an error if the "lvname" parameter does not refer
10258 to a logical volume.
10259 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10261 This function returns a string, or NULL on error. The caller must free
10263 the returned string after use.
10264 (Added in 1.5.24)
10266 guestfs_lvm_clear_filter
10268 int
10269 guestfs_lvm_clear_filter (guestfs_h *g);
10270 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10272 to see every block device.
10273 This command also clears the LVM cache and performs a volume group
10275 scan.
10276 This function returns 0 on success or -1 on error.
10278 (Added in 1.5.1)
10280 guestfs_lvm_remove_all
10282 int
10283 guestfs_lvm_remove_all (guestfs_h *g);
10284 This command removes all LVM logical volumes, volume groups and
10286 physical volumes.
10287 This function returns 0 on success or -1 on error.
10289 This function depends on the feature "lvm2". See also
10291 "guestfs_feature_available".
10292 (Added in 0.8)
10294 guestfs_lvm_scan
10296 int
10297 guestfs_lvm_scan (guestfs_h *g,
10298 int activate);
10299 This scans all block devices and rebuilds the list of LVM physical
10301 volumes, volume groups and logical volumes.
10302 If the "activate" parameter is "true" then newly found volume groups
10304 and logical volumes are activated, meaning the LV /dev/VG/LV devices
10305 become visible.
10306 When a libguestfs handle is launched it scans for existing devices, so
10308 you do not normally need to use this API. However it is useful when
10309 you have added a new device or deleted an existing device (such as when
10310 the "guestfs_luks_open" API is used).
10311 This function returns 0 on success or -1 on error.
10313 (Added in 1.39.8)
10315 guestfs_lvm_set_filter
10317 int
10318 guestfs_lvm_set_filter (guestfs_h *g,
10319 char *const *devices);
10320 This sets the LVM device filter so that LVM will only be able to "see"
10322 the block devices in the list "devices", and will ignore all other
10323 attached block devices.
10324 Where disk image(s) contain duplicate PVs or VGs, this command is
10326 useful to get LVM to ignore the duplicates, otherwise LVM can get
10327 confused. Note also there are two types of duplication possible:
10328 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10329 cloned but just happen to have the same name. In normal operation you
10330 cannot create this situation, but you can do it outside LVM, eg. by
10331 cloning disk images or by bit twiddling inside the LVM metadata.
10332 This command also clears the LVM cache and performs a volume group
10334 scan.
10335 You can filter whole block devices or individual partitions.
10337 You cannot use this if any VG is currently in use (eg. contains a
10339 mounted filesystem), even if you are not filtering out that VG.
10340 This function returns 0 on success or -1 on error.
10342 This function depends on the feature "lvm2". See also
10344 "guestfs_feature_available".
10345 (Added in 1.5.1)
10347 guestfs_lvremove
10349 int
10350 guestfs_lvremove (guestfs_h *g,
10351 const char *device);
10352 Remove an LVM logical volume "device", where "device" is the path to
10354 the LV, such as /dev/VG/LV.
10355 You can also remove all LVs in a volume group by specifying the VG
10357 name, /dev/VG.
10358 This function returns 0 on success or -1 on error.
10360 This function depends on the feature "lvm2". See also
10362 "guestfs_feature_available".
10363 (Added in 1.0.13)
10365 guestfs_lvrename
10367 int
10368 guestfs_lvrename (guestfs_h *g,
10369 const char *logvol,
10370 const char *newlogvol);
10371 Rename a logical volume "logvol" with the new name "newlogvol".
10373 This function returns 0 on success or -1 on error.
10375 (Added in 1.0.83)
10377 guestfs_lvresize
10379 int
10380 guestfs_lvresize (guestfs_h *g,
10381 const char *device,
10382 int mbytes);
10383 This resizes (expands or shrinks) an existing LVM logical volume to
10385 "mbytes". When reducing, data in the reduced part is lost.
10386 This function returns 0 on success or -1 on error.
10388 This function depends on the feature "lvm2". See also
10390 "guestfs_feature_available".
10391 (Added in 1.0.27)
10393 guestfs_lvresize_free
10395 int
10396 guestfs_lvresize_free (guestfs_h *g,
10397 const char *lv,
10398 int percent);
10399 This expands an existing logical volume "lv" so that it fills "pc" % of
10401 the remaining free space in the volume group. Commonly you would call
10402 this with pc = 100 which expands the logical volume as much as
10403 possible, using all remaining free space in the volume group.
10404 This function returns 0 on success or -1 on error.
10406 This function depends on the feature "lvm2". See also
10408 "guestfs_feature_available".
10409 (Added in 1.3.3)
10411 guestfs_lvs
10413 char **
10414 guestfs_lvs (guestfs_h *g);
10415 List all the logical volumes detected. This is the equivalent of the
10417 lvs(8) command.
10418 This returns a list of the logical volume device names (eg.
10420 /dev/VolGroup00/LogVol00).
10421 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10423 This function returns a NULL-terminated array of strings (like
10425 environ(3)), or NULL if there was an error. The caller must free the
10426 strings and the array after use.
10427 This function depends on the feature "lvm2". See also
10429 "guestfs_feature_available".
10430 (Added in 0.4)
10432 guestfs_lvs_full
10434 struct guestfs_lvm_lv_list *
10435 guestfs_lvs_full (guestfs_h *g);
10436 List all the logical volumes detected. This is the equivalent of the
10438 lvs(8) command. The "full" version includes all fields.
10439 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10441 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10442 after use.
10443 This function depends on the feature "lvm2". See also
10445 "guestfs_feature_available".
10446 (Added in 0.4)
10448 guestfs_lvuuid
10450 char *
10451 guestfs_lvuuid (guestfs_h *g,
10452 const char *device);
10453 This command returns the UUID of the LVM LV "device".
10455 This function returns a string, or NULL on error. The caller must free
10457 the returned string after use.
10458 (Added in 1.0.87)
10460 guestfs_lxattrlist
10462 struct guestfs_xattr_list *
10463 guestfs_lxattrlist (guestfs_h *g,
10464 const char *path,
10465 char *const *names);
10466 This call allows you to get the extended attributes of multiple files,
10468 where all files are in the directory "path". "names" is the list of
10469 files from this directory.
10470 On return you get a flat list of xattr structs which must be
10472 interpreted sequentially. The first xattr struct always has a zero-
10473 length "attrname". "attrval" in this struct is zero-length to indicate
10474 there was an error doing "guestfs_lgetxattr" for this file, or is a C
10475 string which is a decimal number (the number of following attributes
10476 for this file, which could be "0"). Then after the first xattr struct
10477 are the zero or more attributes for the first named file. This repeats
10478 for the second and subsequent files.
10479 This call is intended for programs that want to efficiently list a
10481 directory contents without making many round-trips. See also
10482 "guestfs_lstatlist" for a similarly efficient call for getting standard
10483 stats.
10484 This function returns a "struct guestfs_xattr_list *", or NULL if there
10486 was an error. The caller must call "guestfs_free_xattr_list" after
10487 use.
10488 This function depends on the feature "linuxxattrs". See also
10490 "guestfs_feature_available".
10491 (Added in 1.0.77)
10493 guestfs_max_disks
10495 int
10496 guestfs_max_disks (guestfs_h *g);
10497 Return the maximum number of disks that may be added to a handle (eg.
10499 by "guestfs_add_drive_opts" and similar calls).
10500 This function was added in libguestfs 1.19.7. In previous versions of
10502 libguestfs the limit was 25.
10503 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10505 On error this function returns -1.
10507 (Added in 1.19.7)
10509 guestfs_md_create
10511 int
10512 guestfs_md_create (guestfs_h *g,
10513 const char *name,
10514 char *const *devices,
10515 ...);
10516 You may supply a list of optional arguments to this call. Use zero or
10518 more of the following pairs of parameters, and terminate the list with
10519 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10520 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10522 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10523 GUESTFS_MD_CREATE_SPARE, int spare,
10524 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10525 GUESTFS_MD_CREATE_LEVEL, const char *level,
10526 Create a Linux md (RAID) device named "name" on the devices in the list
10528 "devices".
10529 The optional parameters are:
10531 "missingbitmap"
10533 A bitmap of missing devices. If a bit is set it means that a
10534 missing device is added to the array. The least significant bit
10535 corresponds to the first device in the array.
10536 As examples:
10538 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10540 resulting array would be "[<missing>, "/dev/sda"]".
10541 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10543 resulting array would be "["/dev/sda", <missing>]".
10544 This defaults to 0 (no missing devices).
10546 The length of "devices" + the number of bits set in "missingbitmap"
10548 must equal "nrdevices" + "spare".
10549 "nrdevices"
10551 The number of active RAID devices.
10552 If not set, this defaults to the length of "devices" plus the
10554 number of bits set in "missingbitmap".
10555 "spare"
10557 The number of spare devices.
10558 If not set, this defaults to 0.
10560 "chunk"
10562 The chunk size in bytes.
10563 "level"
10565 The RAID level, which can be one of: "linear", "raid0", 0,
10566 "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6,
10567 "raid10", 10. Some of these are synonymous, and more levels may be
10568 added in future.
10569 If not set, this defaults to "raid1".
10571 This function returns 0 on success or -1 on error.
10573 This function depends on the feature "mdadm". See also
10575 "guestfs_feature_available".
10576 (Added in 1.15.6)
10578 guestfs_md_create_va
10580 int
10581 guestfs_md_create_va (guestfs_h *g,
10582 const char *name,
10583 char *const *devices,
10584 va_list args);
10585 This is the "va_list variant" of "guestfs_md_create".
10587 See "CALLS WITH OPTIONAL ARGUMENTS".
10589 guestfs_md_create_argv
10591 int
10592 guestfs_md_create_argv (guestfs_h *g,
10593 const char *name,
10594 char *const *devices,
10595 const struct guestfs_md_create_argv *optargs);
10596 This is the "argv variant" of "guestfs_md_create".
10598 See "CALLS WITH OPTIONAL ARGUMENTS".
10600 guestfs_md_detail
10602 char **
10603 guestfs_md_detail (guestfs_h *g,
10604 const char *md);
10605 This command exposes the output of "mdadm -DY <md>". The following
10607 fields are usually present in the returned hash. Other fields may also
10608 be present.
10609 "level"
10611 The raid level of the MD device.
10612 "devices"
10614 The number of underlying devices in the MD device.
10615 "metadata"
10617 The metadata version used.
10618 "uuid"
10620 The UUID of the MD device.
10621 "name"
10623 The name of the MD device.
10624 This function returns a NULL-terminated array of strings, or NULL if
10626 there was an error. The array of strings will always have length
10627 "2n+1", where "n" keys and values alternate, followed by the trailing
10628 NULL entry. The caller must free the strings and the array after use.
10629 This function depends on the feature "mdadm". See also
10631 "guestfs_feature_available".
10632 (Added in 1.15.6)
10634 guestfs_md_stat
10636 struct guestfs_mdstat_list *
10637 guestfs_md_stat (guestfs_h *g,
10638 const char *md);
10639 This call returns a list of the underlying devices which make up the
10641 single software RAID array device "md".
10642 To get a list of software RAID devices, call "guestfs_list_md_devices".
10644 Each structure returned corresponds to one device along with additional
10646 status information:
10647 "mdstat_device"
10649 The name of the underlying device.
10650 "mdstat_index"
10652 The index of this device within the array.
10653 "mdstat_flags"
10655 Flags associated with this device. This is a string containing (in
10656 no specific order) zero or more of the following flags:
10657 "W" write-mostly
10659 "F" device is faulty
10661 "S" device is a RAID spare
10663 "R" replacement
10665 This function returns a "struct guestfs_mdstat_list *", or NULL if
10667 there was an error. The caller must call "guestfs_free_mdstat_list"
10668 after use.
10669 This function depends on the feature "mdadm". See also
10671 "guestfs_feature_available".
10672 (Added in 1.17.21)
10674 guestfs_md_stop
10676 int
10677 guestfs_md_stop (guestfs_h *g,
10678 const char *md);
10679 This command deactivates the MD array named "md". The device is
10681 stopped, but it is not destroyed or zeroed.
10682 This function returns 0 on success or -1 on error.
10684 This function depends on the feature "mdadm". See also
10686 "guestfs_feature_available".
10687 (Added in 1.15.6)
10689 guestfs_mkdir
10691 int
10692 guestfs_mkdir (guestfs_h *g,
10693 const char *path);
10694 Create a directory named "path".
10696 This function returns 0 on success or -1 on error.
10698 (Added in 0.8)
10700 guestfs_mkdir_mode
10702 int
10703 guestfs_mkdir_mode (guestfs_h *g,
10704 const char *path,
10705 int mode);
10706 This command creates a directory, setting the initial permissions of
10708 the directory to "mode".
10709 For common Linux filesystems, the actual mode which is set will be
10711 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10712 the mode in other ways.
10713 See also "guestfs_mkdir", "guestfs_umask"
10715 This function returns 0 on success or -1 on error.
10717 (Added in 1.0.77)
10719 guestfs_mkdir_p
10721 int
10722 guestfs_mkdir_p (guestfs_h *g,
10723 const char *path);
10724 Create a directory named "path", creating any parent directories as
10726 necessary. This is like the "mkdir -p" shell command.
10727 This function returns 0 on success or -1 on error.
10729 (Added in 0.8)
10731 guestfs_mkdtemp
10733 char *
10734 guestfs_mkdtemp (guestfs_h *g,
10735 const char *tmpl);
10736 This command creates a temporary directory. The "tmpl" parameter
10738 should be a full pathname for the temporary directory name with the
10739 final six characters being "XXXXXX".
10740 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10742 one being suitable for Windows filesystems.
10743 The name of the temporary directory that was created is returned.
10745 The temporary directory is created with mode 0700 and is owned by root.
10747 The caller is responsible for deleting the temporary directory and its
10749 contents after use.
10750 See also: mkdtemp(3)
10752 This function returns a string, or NULL on error. The caller must free
10754 the returned string after use.
10755 (Added in 1.0.54)
10757 guestfs_mke2fs
10759 int
10760 guestfs_mke2fs (guestfs_h *g,
10761 const char *device,
10762 ...);
10763 You may supply a list of optional arguments to this call. Use zero or
10765 more of the following pairs of parameters, and terminate the list with
10766 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10767 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10769 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10770 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10771 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10772 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10773 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10774 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10775 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10776 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10777 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10778 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10779 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10780 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10781 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10782 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10783 GUESTFS_MKE2FS_LABEL, const char *label,
10784 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10785 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10786 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10787 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10788 GUESTFS_MKE2FS_UUID, const char *uuid,
10789 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10790 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10791 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10792 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10793 GUESTFS_MKE2FS_TESTFS, int testfs,
10794 GUESTFS_MKE2FS_DISCARD, int discard,
10795 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10796 GUESTFS_MKE2FS_EXTENT, int extent,
10797 GUESTFS_MKE2FS_FILETYPE, int filetype,
10798 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10799 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10800 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10801 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10802 GUESTFS_MKE2FS_QUOTA, int quota,
10803 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10804 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10805 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10806 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10808 "device".
10809 The optional "blockscount" is the size of the filesystem in blocks. If
10811 omitted it defaults to the size of "device". Note if the filesystem is
10812 too small to contain a journal, "mke2fs" will silently create an ext2
10813 filesystem instead.
10814 This function returns 0 on success or -1 on error.
10816 (Added in 1.19.44)
10818 guestfs_mke2fs_va
10820 int
10821 guestfs_mke2fs_va (guestfs_h *g,
10822 const char *device,
10823 va_list args);
10824 This is the "va_list variant" of "guestfs_mke2fs".
10826 See "CALLS WITH OPTIONAL ARGUMENTS".
10828 guestfs_mke2fs_argv
10830 int
10831 guestfs_mke2fs_argv (guestfs_h *g,
10832 const char *device,
10833 const struct guestfs_mke2fs_argv *optargs);
10834 This is the "argv variant" of "guestfs_mke2fs".
10836 See "CALLS WITH OPTIONAL ARGUMENTS".
10838 guestfs_mke2fs_J
10840 int
10841 guestfs_mke2fs_J (guestfs_h *g,
10842 const char *fstype,
10843 int blocksize,
10844 const char *device,
10845 const char *journal);
10846 This function is deprecated. In new code, use the "guestfs_mke2fs"
10848 call instead.
10849 Deprecated functions will not be removed from the API, but the fact
10851 that they are deprecated indicates that there are problems with correct
10852 use of these functions.
10853 This creates an ext2/3/4 filesystem on "device" with an external
10855 journal on "journal". It is equivalent to the command:
10856 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10858 See also "guestfs_mke2journal".
10860 This function returns 0 on success or -1 on error.
10862 (Added in 1.0.68)
10864 guestfs_mke2fs_JL
10866 int
10867 guestfs_mke2fs_JL (guestfs_h *g,
10868 const char *fstype,
10869 int blocksize,
10870 const char *device,
10871 const char *label);
10872 This function is deprecated. In new code, use the "guestfs_mke2fs"
10874 call instead.
10875 Deprecated functions will not be removed from the API, but the fact
10877 that they are deprecated indicates that there are problems with correct
10878 use of these functions.
10879 This creates an ext2/3/4 filesystem on "device" with an external
10881 journal on the journal labeled "label".
10882 See also "guestfs_mke2journal_L".
10884 This function returns 0 on success or -1 on error.
10886 (Added in 1.0.68)
10888 guestfs_mke2fs_JU
10890 int
10891 guestfs_mke2fs_JU (guestfs_h *g,
10892 const char *fstype,
10893 int blocksize,
10894 const char *device,
10895 const char *uuid);
10896 This function is deprecated. In new code, use the "guestfs_mke2fs"
10898 call instead.
10899 Deprecated functions will not be removed from the API, but the fact
10901 that they are deprecated indicates that there are problems with correct
10902 use of these functions.
10903 This creates an ext2/3/4 filesystem on "device" with an external
10905 journal on the journal with UUID "uuid".
10906 See also "guestfs_mke2journal_U".
10908 This function returns 0 on success or -1 on error.
10910 This function depends on the feature "linuxfsuuid". See also
10912 "guestfs_feature_available".
10913 (Added in 1.0.68)
10915 guestfs_mke2journal
10917 int
10918 guestfs_mke2journal (guestfs_h *g,
10919 int blocksize,
10920 const char *device);
10921 This function is deprecated. In new code, use the "guestfs_mke2fs"
10923 call instead.
10924 Deprecated functions will not be removed from the API, but the fact
10926 that they are deprecated indicates that there are problems with correct
10927 use of these functions.
10928 This creates an ext2 external journal on "device". It is equivalent to
10930 the command:
10931 mke2fs -O journal_dev -b blocksize device
10933 This function returns 0 on success or -1 on error.
10935 (Added in 1.0.68)
10937 guestfs_mke2journal_L
10939 int
10940 guestfs_mke2journal_L (guestfs_h *g,
10941 int blocksize,
10942 const char *label,
10943 const char *device);
10944 This function is deprecated. In new code, use the "guestfs_mke2fs"
10946 call instead.
10947 Deprecated functions will not be removed from the API, but the fact
10949 that they are deprecated indicates that there are problems with correct
10950 use of these functions.
10951 This creates an ext2 external journal on "device" with label "label".
10953 This function returns 0 on success or -1 on error.
10955 (Added in 1.0.68)
10957 guestfs_mke2journal_U
10959 int
10960 guestfs_mke2journal_U (guestfs_h *g,
10961 int blocksize,
10962 const char *uuid,
10963 const char *device);
10964 This function is deprecated. In new code, use the "guestfs_mke2fs"
10966 call instead.
10967 Deprecated functions will not be removed from the API, but the fact
10969 that they are deprecated indicates that there are problems with correct
10970 use of these functions.
10971 This creates an ext2 external journal on "device" with UUID "uuid".
10973 This function returns 0 on success or -1 on error.
10975 This function depends on the feature "linuxfsuuid". See also
10977 "guestfs_feature_available".
10978 (Added in 1.0.68)
10980 guestfs_mkfifo
10982 int
10983 guestfs_mkfifo (guestfs_h *g,
10984 int mode,
10985 const char *path);
10986 This call creates a FIFO (named pipe) called "path" with mode "mode".
10988 It is just a convenient wrapper around "guestfs_mknod".
10989 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
10991 The mode actually set is affected by the umask.
10993 This function returns 0 on success or -1 on error.
10995 This function depends on the feature "mknod". See also
10997 "guestfs_feature_available".
10998 (Added in 1.0.55)
11000 guestfs_mkfs
11002 int
11003 guestfs_mkfs (guestfs_h *g,
11004 const char *fstype,
11005 const char *device);
11006 This function is provided for backwards compatibility with earlier
11008 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
11009 optional arguments.
11010 (Added in 0.8)
11012 guestfs_mkfs_opts
11014 int
11015 guestfs_mkfs_opts (guestfs_h *g,
11016 const char *fstype,
11017 const char *device,
11018 ...);
11019 You may supply a list of optional arguments to this call. Use zero or
11021 more of the following pairs of parameters, and terminate the list with
11022 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11023 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
11025 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
11026 GUESTFS_MKFS_OPTS_INODE, int inode,
11027 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
11028 GUESTFS_MKFS_OPTS_LABEL, const char *label,
11029 This function creates a filesystem on "device". The filesystem type is
11031 "fstype", for example "ext3".
11032 The optional arguments are:
11034 "blocksize"
11036 The filesystem block size. Supported block sizes depend on the
11037 filesystem type, but typically they are 1024, 2048 or 4096 for
11038 Linux ext2/3 filesystems.
11039 For VFAT and NTFS the "blocksize" parameter is treated as the
11041 requested cluster size.
11042 For UFS block sizes, please see mkfs.ufs(8).
11044 "features"
11046 This passes the -O parameter to the external mkfs program.
11047 For certain filesystem types, this allows extra filesystem features
11049 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
11050 You cannot use this optional parameter with the "gfs" or "gfs2"
11052 filesystem type.
11053 "inode"
11055 This passes the -I parameter to the external mke2fs(8) program
11056 which sets the inode size (only for ext2/3/4 filesystems at
11057 present).
11058 "sectorsize"
11060 This passes the -S parameter to external mkfs.ufs(8) program, which
11061 sets sector size for ufs filesystem.
11062 This function returns 0 on success or -1 on error.
11064 (Added in 0.8)
11066 guestfs_mkfs_opts_va
11068 int
11069 guestfs_mkfs_opts_va (guestfs_h *g,
11070 const char *fstype,
11071 const char *device,
11072 va_list args);
11073 This is the "va_list variant" of "guestfs_mkfs_opts".
11075 See "CALLS WITH OPTIONAL ARGUMENTS".
11077 guestfs_mkfs_opts_argv
11079 int
11080 guestfs_mkfs_opts_argv (guestfs_h *g,
11081 const char *fstype,
11082 const char *device,
11083 const struct guestfs_mkfs_opts_argv *optargs);
11084 This is the "argv variant" of "guestfs_mkfs_opts".
11086 See "CALLS WITH OPTIONAL ARGUMENTS".
11088 guestfs_mkfs_b
11090 int
11091 guestfs_mkfs_b (guestfs_h *g,
11092 const char *fstype,
11093 int blocksize,
11094 const char *device);
11095 This function is deprecated. In new code, use the "guestfs_mkfs" call
11097 instead.
11098 Deprecated functions will not be removed from the API, but the fact
11100 that they are deprecated indicates that there are problems with correct
11101 use of these functions.
11102 This call is similar to "guestfs_mkfs", but it allows you to control
11104 the block size of the resulting filesystem. Supported block sizes
11105 depend on the filesystem type, but typically they are 1024, 2048 or
11106 4096 only.
11107 For VFAT and NTFS the "blocksize" parameter is treated as the requested
11109 cluster size.
11110 This function returns 0 on success or -1 on error.
11112 (Added in 1.0.68)
11114 guestfs_mkfs_btrfs
11116 int
11117 guestfs_mkfs_btrfs (guestfs_h *g,
11118 char *const *devices,
11119 ...);
11120 You may supply a list of optional arguments to this call. Use zero or
11122 more of the following pairs of parameters, and terminate the list with
11123 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11124 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11126 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11127 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11128 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11129 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11130 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11131 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11132 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11133 Create a btrfs filesystem, allowing all configurables to be set. For
11135 more information on the optional arguments, see mkfs.btrfs(8).
11136 Since btrfs filesystems can span multiple devices, this takes a non-
11138 empty list of devices.
11139 To create general filesystems, use "guestfs_mkfs".
11141 This function returns 0 on success or -1 on error.
11143 This function depends on the feature "btrfs". See also
11145 "guestfs_feature_available".
11146 (Added in 1.17.25)
11148 guestfs_mkfs_btrfs_va
11150 int
11151 guestfs_mkfs_btrfs_va (guestfs_h *g,
11152 char *const *devices,
11153 va_list args);
11154 This is the "va_list variant" of "guestfs_mkfs_btrfs".
11156 See "CALLS WITH OPTIONAL ARGUMENTS".
11158 guestfs_mkfs_btrfs_argv
11160 int
11161 guestfs_mkfs_btrfs_argv (guestfs_h *g,
11162 char *const *devices,
11163 const struct guestfs_mkfs_btrfs_argv *optargs);
11164 This is the "argv variant" of "guestfs_mkfs_btrfs".
11166 See "CALLS WITH OPTIONAL ARGUMENTS".
11168 guestfs_mklost_and_found
11170 int
11171 guestfs_mklost_and_found (guestfs_h *g,
11172 const char *mountpoint);
11173 Make the "lost+found" directory, normally in the root directory of an
11175 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
11176 to create the "lost+found" directory.
11177 This function returns 0 on success or -1 on error.
11179 (Added in 1.19.56)
11181 guestfs_mkmountpoint
11183 int
11184 guestfs_mkmountpoint (guestfs_h *g,
11185 const char *exemptpath);
11186 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11188 that can be used to create extra mountpoints before mounting the first
11189 filesystem.
11190 These calls are only necessary in some very limited circumstances,
11192 mainly the case where you want to mount a mix of unrelated and/or read-
11193 only filesystems together.
11194 For example, live CDs often contain a "Russian doll" nest of
11196 filesystems, an ISO outer layer, with a squashfs image inside, with an
11197 ext2/3 image inside that. You can unpack this as follows in guestfish:
11198 add-ro Fedora-11-i686-Live.iso
11200 run
11201 mkmountpoint /cd
11202 mkmountpoint /sqsh
11203 mkmountpoint /ext3fs
11204 mount /dev/sda /cd
11205 mount-loop /cd/LiveOS/squashfs.img /sqsh
11206 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11207 The inner filesystem is now unpacked under the /ext3fs mountpoint.
11209 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11211 You may get unexpected errors if you try to mix these calls. It is
11212 safest to manually unmount filesystems and remove mountpoints after
11213 use.
11214 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11216 first, so for this to work for manual mountpoints, you must ensure that
11217 the innermost mountpoints have the longest pathnames, as in the example
11218 code above.
11219 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11221 Autosync [see "guestfs_set_autosync", this is set by default on
11223 handles] can cause "guestfs_umount_all" to be called when the handle is
11224 closed which can also trigger these issues.
11225 This function returns 0 on success or -1 on error.
11227 (Added in 1.0.62)
11229 guestfs_mknod
11231 int
11232 guestfs_mknod (guestfs_h *g,
11233 int mode,
11234 int devmajor,
11235 int devminor,
11236 const char *path);
11237 This call creates block or character special devices, or named pipes
11239 (FIFOs).
11240 The "mode" parameter should be the mode, using the standard constants.
11242 "devmajor" and "devminor" are the device major and minor numbers, only
11243 used when creating block and character special devices.
11244 Note that, just like mknod(2), the mode must be bitwise OR'd with
11246 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11247 a regular file). These constants are available in the standard Linux
11248 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11249 "guestfs_mkfifo" which are wrappers around this command which bitwise
11250 OR in the appropriate constant for you.
11251 The mode actually set is affected by the umask.
11253 This function returns 0 on success or -1 on error.
11255 This function depends on the feature "mknod". See also
11257 "guestfs_feature_available".
11258 (Added in 1.0.55)
11260 guestfs_mknod_b
11262 int
11263 guestfs_mknod_b (guestfs_h *g,
11264 int mode,
11265 int devmajor,
11266 int devminor,
11267 const char *path);
11268 This call creates a block device node called "path" with mode "mode"
11270 and device major/minor "devmajor" and "devminor". It is just a
11271 convenient wrapper around "guestfs_mknod".
11272 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11274 The mode actually set is affected by the umask.
11276 This function returns 0 on success or -1 on error.
11278 This function depends on the feature "mknod". See also
11280 "guestfs_feature_available".
11281 (Added in 1.0.55)
11283 guestfs_mknod_c
11285 int
11286 guestfs_mknod_c (guestfs_h *g,
11287 int mode,
11288 int devmajor,
11289 int devminor,
11290 const char *path);
11291 This call creates a char device node called "path" with mode "mode" and
11293 device major/minor "devmajor" and "devminor". It is just a convenient
11294 wrapper around "guestfs_mknod".
11295 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11297 The mode actually set is affected by the umask.
11299 This function returns 0 on success or -1 on error.
11301 This function depends on the feature "mknod". See also
11303 "guestfs_feature_available".
11304 (Added in 1.0.55)
11306 guestfs_mksquashfs
11308 int
11309 guestfs_mksquashfs (guestfs_h *g,
11310 const char *path,
11311 const char *filename,
11312 ...);
11313 You may supply a list of optional arguments to this call. Use zero or
11315 more of the following pairs of parameters, and terminate the list with
11316 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11317 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11319 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11320 Create a squashfs filesystem for the specified "path".
11322 The optional "compress" flag controls compression. If not given, then
11324 the output compressed using "gzip". Otherwise one of the following
11325 strings may be given to select the compression type of the squashfs:
11326 "gzip", "lzma", "lzo", "lz4", "xz".
11327 The other optional arguments are:
11329 "excludes"
11331 A list of wildcards. Files are excluded if they match any of the
11332 wildcards.
11333 Please note that this API may fail when used to compress directories
11335 with large files, such as the resulting squashfs will be over 3GB big.
11336 This function returns 0 on success or -1 on error.
11338 This function depends on the feature "squashfs". See also
11340 "guestfs_feature_available".
11341 (Added in 1.35.25)
11343 guestfs_mksquashfs_va
11345 int
11346 guestfs_mksquashfs_va (guestfs_h *g,
11347 const char *path,
11348 const char *filename,
11349 va_list args);
11350 This is the "va_list variant" of "guestfs_mksquashfs".
11352 See "CALLS WITH OPTIONAL ARGUMENTS".
11354 guestfs_mksquashfs_argv
11356 int
11357 guestfs_mksquashfs_argv (guestfs_h *g,
11358 const char *path,
11359 const char *filename,
11360 const struct guestfs_mksquashfs_argv *optargs);
11361 This is the "argv variant" of "guestfs_mksquashfs".
11363 See "CALLS WITH OPTIONAL ARGUMENTS".
11365 guestfs_mkswap
11367 int
11368 guestfs_mkswap (guestfs_h *g,
11369 const char *device);
11370 This function is provided for backwards compatibility with earlier
11372 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11373 optional arguments.
11374 (Added in 1.0.55)
11376 guestfs_mkswap_opts
11378 int
11379 guestfs_mkswap_opts (guestfs_h *g,
11380 const char *device,
11381 ...);
11382 You may supply a list of optional arguments to this call. Use zero or
11384 more of the following pairs of parameters, and terminate the list with
11385 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11386 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11388 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11389 Create a Linux swap partition on "device".
11391 The option arguments "label" and "uuid" allow you to set the label
11393 and/or UUID of the new swap partition.
11394 This function returns 0 on success or -1 on error.
11396 (Added in 1.0.55)
11398 guestfs_mkswap_opts_va
11400 int
11401 guestfs_mkswap_opts_va (guestfs_h *g,
11402 const char *device,
11403 va_list args);
11404 This is the "va_list variant" of "guestfs_mkswap_opts".
11406 See "CALLS WITH OPTIONAL ARGUMENTS".
11408 guestfs_mkswap_opts_argv
11410 int
11411 guestfs_mkswap_opts_argv (guestfs_h *g,
11412 const char *device,
11413 const struct guestfs_mkswap_opts_argv *optargs);
11414 This is the "argv variant" of "guestfs_mkswap_opts".
11416 See "CALLS WITH OPTIONAL ARGUMENTS".
11418 guestfs_mkswap_L
11420 int
11421 guestfs_mkswap_L (guestfs_h *g,
11422 const char *label,
11423 const char *device);
11424 This function is deprecated. In new code, use the "guestfs_mkswap"
11426 call instead.
11427 Deprecated functions will not be removed from the API, but the fact
11429 that they are deprecated indicates that there are problems with correct
11430 use of these functions.
11431 Create a swap partition on "device" with label "label".
11433 Note that you cannot attach a swap label to a block device (eg.
11435 /dev/sda), just to a partition. This appears to be a limitation of the
11436 kernel or swap tools.
11437 This function returns 0 on success or -1 on error.
11439 (Added in 1.0.55)
11441 guestfs_mkswap_U
11443 int
11444 guestfs_mkswap_U (guestfs_h *g,
11445 const char *uuid,
11446 const char *device);
11447 This function is deprecated. In new code, use the "guestfs_mkswap"
11449 call instead.
11450 Deprecated functions will not be removed from the API, but the fact
11452 that they are deprecated indicates that there are problems with correct
11453 use of these functions.
11454 Create a swap partition on "device" with UUID "uuid".
11456 This function returns 0 on success or -1 on error.
11458 This function depends on the feature "linuxfsuuid". See also
11460 "guestfs_feature_available".
11461 (Added in 1.0.55)
11463 guestfs_mkswap_file
11465 int
11466 guestfs_mkswap_file (guestfs_h *g,
11467 const char *path);
11468 Create a swap file.
11470 This command just writes a swap file signature to an existing file. To
11472 create the file itself, use something like "guestfs_fallocate".
11473 This function returns 0 on success or -1 on error.
11475 (Added in 1.0.66)
11477 guestfs_mktemp
11479 char *
11480 guestfs_mktemp (guestfs_h *g,
11481 const char *tmpl,
11482 ...);
11483 You may supply a list of optional arguments to this call. Use zero or
11485 more of the following pairs of parameters, and terminate the list with
11486 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11487 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11489 This command creates a temporary file. The "tmpl" parameter should be
11491 a full pathname for the temporary directory name with the final six
11492 characters being "XXXXXX".
11493 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11495 one being suitable for Windows filesystems.
11496 The name of the temporary file that was created is returned.
11498 The temporary file is created with mode 0600 and is owned by root.
11500 The caller is responsible for deleting the temporary file after use.
11502 If the optional "suffix" parameter is given, then the suffix (eg.
11504 ".txt") is appended to the temporary name.
11505 See also: "guestfs_mkdtemp".
11507 This function returns a string, or NULL on error. The caller must free
11509 the returned string after use.
11510 (Added in 1.19.53)
11512 guestfs_mktemp_va
11514 char *
11515 guestfs_mktemp_va (guestfs_h *g,
11516 const char *tmpl,
11517 va_list args);
11518 This is the "va_list variant" of "guestfs_mktemp".
11520 See "CALLS WITH OPTIONAL ARGUMENTS".
11522 guestfs_mktemp_argv
11524 char *
11525 guestfs_mktemp_argv (guestfs_h *g,
11526 const char *tmpl,
11527 const struct guestfs_mktemp_argv *optargs);
11528 This is the "argv variant" of "guestfs_mktemp".
11530 See "CALLS WITH OPTIONAL ARGUMENTS".
11532 guestfs_modprobe
11534 int
11535 guestfs_modprobe (guestfs_h *g,
11536 const char *modulename);
11537 This loads a kernel module in the appliance.
11539 This function returns 0 on success or -1 on error.
11541 This function depends on the feature "linuxmodules". See also
11543 "guestfs_feature_available".
11544 (Added in 1.0.68)
11546 guestfs_mount
11548 int
11549 guestfs_mount (guestfs_h *g,
11550 const char *mountable,
11551 const char *mountpoint);
11552 Mount a guest disk at a position in the filesystem. Block devices are
11554 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11555 If those block devices contain partitions, they will have the usual
11556 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11557 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11558 "guestfs_inspect_get_mountpoints".
11559 The rules are the same as for mount(2): A filesystem must first be
11561 mounted on / before others can be mounted. Other filesystems can only
11562 be mounted on directories which already exist.
11563 The mounted filesystem is writable, if we have sufficient permissions
11565 on the underlying device.
11566 Before libguestfs 1.13.16, this call implicitly added the options
11568 "sync" and "noatime". The "sync" option greatly slowed writes and
11569 caused many problems for users. If your program might need to work
11570 with older versions of libguestfs, use "guestfs_mount_options" instead
11571 (using an empty string for the first parameter if you don't want any
11572 options).
11573 This function returns 0 on success or -1 on error.
11575 (Added in 0.3)
11577 guestfs_mount_9p
11579 int
11580 guestfs_mount_9p (guestfs_h *g,
11581 const char *mounttag,
11582 const char *mountpoint,
11583 ...);
11584 You may supply a list of optional arguments to this call. Use zero or
11586 more of the following pairs of parameters, and terminate the list with
11587 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11588 GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11590 Mount the virtio-9p filesystem with the tag "mounttag" on the directory
11592 "mountpoint".
11593 If required, "trans=virtio" will be automatically added to the options.
11595 Any other options required can be passed in the optional "options"
11596 parameter.
11597 This function returns 0 on success or -1 on error.
11599 (Added in 1.11.12)
11601 guestfs_mount_9p_va
11603 int
11604 guestfs_mount_9p_va (guestfs_h *g,
11605 const char *mounttag,
11606 const char *mountpoint,
11607 va_list args);
11608 This is the "va_list variant" of "guestfs_mount_9p".
11610 See "CALLS WITH OPTIONAL ARGUMENTS".
11612 guestfs_mount_9p_argv
11614 int
11615 guestfs_mount_9p_argv (guestfs_h *g,
11616 const char *mounttag,
11617 const char *mountpoint,
11618 const struct guestfs_mount_9p_argv *optargs);
11619 This is the "argv variant" of "guestfs_mount_9p".
11621 See "CALLS WITH OPTIONAL ARGUMENTS".
11623 guestfs_mount_local
11625 int
11626 guestfs_mount_local (guestfs_h *g,
11627 const char *localmountpoint,
11628 ...);
11629 You may supply a list of optional arguments to this call. Use zero or
11631 more of the following pairs of parameters, and terminate the list with
11632 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11633 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11635 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11636 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11637 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11638 This call exports the libguestfs-accessible filesystem to a local
11640 mountpoint (directory) called "localmountpoint". Ordinary reads and
11641 writes to files and directories under "localmountpoint" are redirected
11642 through libguestfs.
11643 If the optional "readonly" flag is set to true, then writes to the
11645 filesystem return error "EROFS".
11646 "options" is a comma-separated list of mount options. See
11648 guestmount(1) for some useful options.
11649 "cachetimeout" sets the timeout (in seconds) for cached directory
11651 entries. The default is 60 seconds. See guestmount(1) for further
11652 information.
11653 If "debugcalls" is set to true, then additional debugging information
11655 is generated for every FUSE call.
11656 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11658 processing requests (access to it will block). You have to call
11659 "guestfs_mount_local_run" to run the main loop.
11660 See "MOUNT LOCAL" for full documentation.
11662 This function returns 0 on success or -1 on error.
11664 (Added in 1.17.22)
11666 guestfs_mount_local_va
11668 int
11669 guestfs_mount_local_va (guestfs_h *g,
11670 const char *localmountpoint,
11671 va_list args);
11672 This is the "va_list variant" of "guestfs_mount_local".
11674 See "CALLS WITH OPTIONAL ARGUMENTS".
11676 guestfs_mount_local_argv
11678 int
11679 guestfs_mount_local_argv (guestfs_h *g,
11680 const char *localmountpoint,
11681 const struct guestfs_mount_local_argv *optargs);
11682 This is the "argv variant" of "guestfs_mount_local".
11684 See "CALLS WITH OPTIONAL ARGUMENTS".
11686 guestfs_mount_local_run
11688 int
11689 guestfs_mount_local_run (guestfs_h *g);
11690 Run the main loop which translates kernel calls to libguestfs calls.
11692 This should only be called after "guestfs_mount_local" returns
11694 successfully. The call will not return until the filesystem is
11695 unmounted.
11696 Note you must not make concurrent libguestfs calls on the same handle
11698 from another thread.
11699 You may call this from a different thread than the one which called
11701 "guestfs_mount_local", subject to the usual rules for threads and
11702 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11703 See "MOUNT LOCAL" for full documentation.
11705 This function returns 0 on success or -1 on error.
11707 (Added in 1.17.22)
11709 guestfs_mount_loop
11711 int
11712 guestfs_mount_loop (guestfs_h *g,
11713 const char *file,
11714 const char *mountpoint);
11715 This command lets you mount file (a filesystem image in a file) on a
11717 mount point. It is entirely equivalent to the command "mount -o loop
11718 file mountpoint".
11719 This function returns 0 on success or -1 on error.
11721 (Added in 1.0.54)
11723 guestfs_mount_options
11725 int
11726 guestfs_mount_options (guestfs_h *g,
11727 const char *options,
11728 const char *mountable,
11729 const char *mountpoint);
11730 This is the same as the "guestfs_mount" command, but it allows you to
11732 set the mount options as for the mount(8) -o flag.
11733 If the "options" parameter is an empty string, then no options are
11735 passed (all options default to whatever the filesystem uses).
11736 This function returns 0 on success or -1 on error.
11738 (Added in 1.0.10)
11740 guestfs_mount_ro
11742 int
11743 guestfs_mount_ro (guestfs_h *g,
11744 const char *mountable,
11745 const char *mountpoint);
11746 This is the same as the "guestfs_mount" command, but it mounts the
11748 filesystem with the read-only (-o ro) flag.
11749 This function returns 0 on success or -1 on error.
11751 (Added in 1.0.10)
11753 guestfs_mount_vfs
11755 int
11756 guestfs_mount_vfs (guestfs_h *g,
11757 const char *options,
11758 const char *vfstype,
11759 const char *mountable,
11760 const char *mountpoint);
11761 This is the same as the "guestfs_mount" command, but it allows you to
11763 set both the mount options and the vfstype as for the mount(8) -o and
11764 -t flags.
11765 This function returns 0 on success or -1 on error.
11767 (Added in 1.0.10)
11769 guestfs_mountable_device
11771 char *
11772 guestfs_mountable_device (guestfs_h *g,
11773 const char *mountable);
11774 Returns the device name of a mountable. In quite a lot of cases, the
11776 mountable is the device name.
11777 However this doesn't apply for btrfs subvolumes, where the mountable is
11779 a combination of both the device name and the subvolume path (see also
11780 "guestfs_mountable_subvolume" to extract the subvolume path of the
11781 mountable if any).
11782 This function returns a string, or NULL on error. The caller must free
11784 the returned string after use.
11785 (Added in 1.33.15)
11787 guestfs_mountable_subvolume
11789 char *
11790 guestfs_mountable_subvolume (guestfs_h *g,
11791 const char *mountable);
11792 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11794 are a combination of both the device name and the subvolume path (see
11795 also "guestfs_mountable_device" to extract the device of the
11796 mountable).
11797 If the mountable does not represent a btrfs subvolume, then this
11799 function fails and the "errno" is set to "EINVAL".
11800 This function returns a string, or NULL on error. The caller must free
11802 the returned string after use.
11803 (Added in 1.33.15)
11805 guestfs_mountpoints
11807 char **
11808 guestfs_mountpoints (guestfs_h *g);
11809 This call is similar to "guestfs_mounts". That call returns a list of
11811 devices. This one returns a hash table (map) of device name to
11812 directory where the device is mounted.
11813 This function returns a NULL-terminated array of strings, or NULL if
11815 there was an error. The array of strings will always have length
11816 "2n+1", where "n" keys and values alternate, followed by the trailing
11817 NULL entry. The caller must free the strings and the array after use.
11818 (Added in 1.0.62)
11820 guestfs_mounts
11822 char **
11823 guestfs_mounts (guestfs_h *g);
11824 This returns the list of currently mounted filesystems. It returns the
11826 list of devices (eg. /dev/sda1, /dev/VG/LV).
11827 Some internal mounts are not shown.
11829 See also: "guestfs_mountpoints"
11831 This function returns a NULL-terminated array of strings (like
11833 environ(3)), or NULL if there was an error. The caller must free the
11834 strings and the array after use.
11835 (Added in 0.8)
11837 guestfs_mv
11839 int
11840 guestfs_mv (guestfs_h *g,
11841 const char *src,
11842 const char *dest);
11843 This moves a file from "src" to "dest" where "dest" is either a
11845 destination filename or destination directory.
11846 See also: "guestfs_rename".
11848 This function returns 0 on success or -1 on error.
11850 (Added in 1.0.18)
11852 guestfs_nr_devices
11854 int
11855 guestfs_nr_devices (guestfs_h *g);
11856 This returns the number of whole block devices that were added. This
11858 is the same as the number of devices that would be returned if you
11859 called "guestfs_list_devices".
11860 To find out the maximum number of devices that could be added, call
11862 "guestfs_max_disks".
11863 On error this function returns -1.
11865 (Added in 1.19.15)
11867 guestfs_ntfs_3g_probe
11869 int
11870 guestfs_ntfs_3g_probe (guestfs_h *g,
11871 int rw,
11872 const char *device);
11873 This command runs the ntfs-3g.probe(8) command which probes an NTFS
11875 "device" for mountability. (Not all NTFS volumes can be mounted read-
11876 write, and some cannot be mounted at all).
11877 "rw" is a boolean flag. Set it to true if you want to test if the
11879 volume can be mounted read-write. Set it to false if you want to test
11880 if the volume can be mounted read-only.
11881 The return value is an integer which 0 if the operation would succeed,
11883 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
11884 On error this function returns -1.
11886 This function depends on the feature "ntfs3g". See also
11888 "guestfs_feature_available".
11889 (Added in 1.0.43)
11891 guestfs_ntfscat_i
11893 int
11894 guestfs_ntfscat_i (guestfs_h *g,
11895 const char *device,
11896 int64_t inode,
11897 const char *filename);
11898 Download a file given its inode from a NTFS filesystem and save it as
11900 filename on the local machine.
11901 This allows to download some otherwise inaccessible files such as the
11903 ones within the $Extend folder.
11904 The filesystem from which to extract the file must be unmounted,
11906 otherwise the call will fail.
11907 This function returns 0 on success or -1 on error.
11909 This long-running command can generate progress notification messages
11911 so that the caller can display a progress bar or indicator. To receive
11912 these messages, the caller must register a progress event callback.
11913 See "GUESTFS_EVENT_PROGRESS".
11914 (Added in 1.33.14)
11916 guestfs_ntfsclone_in
11918 int
11919 guestfs_ntfsclone_in (guestfs_h *g,
11920 const char *backupfile,
11921 const char *device);
11922 Restore the "backupfile" (from a previous call to
11924 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
11925 of this device.
11926 This function returns 0 on success or -1 on error.
11928 This function depends on the feature "ntfs3g". See also
11930 "guestfs_feature_available".
11931 (Added in 1.17.9)
11933 guestfs_ntfsclone_out
11935 int
11936 guestfs_ntfsclone_out (guestfs_h *g,
11937 const char *device,
11938 const char *backupfile,
11939 ...);
11940 You may supply a list of optional arguments to this call. Use zero or
11942 more of the following pairs of parameters, and terminate the list with
11943 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11944 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
11946 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
11947 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
11948 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
11949 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
11950 Stream the NTFS filesystem "device" to the local file "backupfile".
11952 The format used for the backup file is a special format used by the
11953 ntfsclone(8) tool.
11954 If the optional "metadataonly" flag is true, then only the metadata is
11956 saved, losing all the user data (this is useful for diagnosing some
11957 filesystem problems).
11958 The optional "rescue", "ignorefscheck", "preservetimestamps" and
11960 "force" flags have precise meanings detailed in the ntfsclone(8) man
11961 page.
11962 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
11964 device.
11965 This function returns 0 on success or -1 on error.
11967 This function depends on the feature "ntfs3g". See also
11969 "guestfs_feature_available".
11970 (Added in 1.17.9)
11972 guestfs_ntfsclone_out_va
11974 int
11975 guestfs_ntfsclone_out_va (guestfs_h *g,
11976 const char *device,
11977 const char *backupfile,
11978 va_list args);
11979 This is the "va_list variant" of "guestfs_ntfsclone_out".
11981 See "CALLS WITH OPTIONAL ARGUMENTS".
11983 guestfs_ntfsclone_out_argv
11985 int
11986 guestfs_ntfsclone_out_argv (guestfs_h *g,
11987 const char *device,
11988 const char *backupfile,
11989 const struct guestfs_ntfsclone_out_argv *optargs);
11990 This is the "argv variant" of "guestfs_ntfsclone_out".
11992 See "CALLS WITH OPTIONAL ARGUMENTS".
11994 guestfs_ntfsfix
11996 int
11997 guestfs_ntfsfix (guestfs_h *g,
11998 const char *device,
11999 ...);
12000 You may supply a list of optional arguments to this call. Use zero or
12002 more of the following pairs of parameters, and terminate the list with
12003 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12004 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
12006 This command repairs some fundamental NTFS inconsistencies, resets the
12008 NTFS journal file, and schedules an NTFS consistency check for the
12009 first boot into Windows.
12010 This is not an equivalent of Windows "chkdsk". It does not scan the
12012 filesystem for inconsistencies.
12013 The optional "clearbadsectors" flag clears the list of bad sectors.
12015 This is useful after cloning a disk with bad sectors to a new disk.
12016 This function returns 0 on success or -1 on error.
12018 This function depends on the feature "ntfs3g". See also
12020 "guestfs_feature_available".
12021 (Added in 1.17.9)
12023 guestfs_ntfsfix_va
12025 int
12026 guestfs_ntfsfix_va (guestfs_h *g,
12027 const char *device,
12028 va_list args);
12029 This is the "va_list variant" of "guestfs_ntfsfix".
12031 See "CALLS WITH OPTIONAL ARGUMENTS".
12033 guestfs_ntfsfix_argv
12035 int
12036 guestfs_ntfsfix_argv (guestfs_h *g,
12037 const char *device,
12038 const struct guestfs_ntfsfix_argv *optargs);
12039 This is the "argv variant" of "guestfs_ntfsfix".
12041 See "CALLS WITH OPTIONAL ARGUMENTS".
12043 guestfs_ntfsresize
12045 int
12046 guestfs_ntfsresize (guestfs_h *g,
12047 const char *device);
12048 This function is provided for backwards compatibility with earlier
12050 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
12051 no optional arguments.
12052 (Added in 1.3.2)
12054 guestfs_ntfsresize_opts
12056 int
12057 guestfs_ntfsresize_opts (guestfs_h *g,
12058 const char *device,
12059 ...);
12060 You may supply a list of optional arguments to this call. Use zero or
12062 more of the following pairs of parameters, and terminate the list with
12063 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12064 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12066 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12067 This command resizes an NTFS filesystem, expanding or shrinking it to
12069 the size of the underlying device.
12070 The optional parameters are:
12072 "size"
12074 The new size (in bytes) of the filesystem. If omitted, the
12075 filesystem is resized to fit the container (eg. partition).
12076 "force"
12078 If this option is true, then force the resize of the filesystem
12079 even if the filesystem is marked as requiring a consistency check.
12080 After the resize operation, the filesystem is always marked as
12082 requiring a consistency check (for safety). You have to boot into
12083 Windows to perform this check and clear this condition. If you
12084 don't set the "force" option then it is not possible to call
12085 "guestfs_ntfsresize" multiple times on a single filesystem without
12086 booting into Windows between each resize.
12087 See also ntfsresize(8).
12089 This function returns 0 on success or -1 on error.
12091 This function depends on the feature "ntfsprogs". See also
12093 "guestfs_feature_available".
12094 (Added in 1.3.2)
12096 guestfs_ntfsresize_opts_va
12098 int
12099 guestfs_ntfsresize_opts_va (guestfs_h *g,
12100 const char *device,
12101 va_list args);
12102 This is the "va_list variant" of "guestfs_ntfsresize_opts".
12104 See "CALLS WITH OPTIONAL ARGUMENTS".
12106 guestfs_ntfsresize_opts_argv
12108 int
12109 guestfs_ntfsresize_opts_argv (guestfs_h *g,
12110 const char *device,
12111 const struct guestfs_ntfsresize_opts_argv *optargs);
12112 This is the "argv variant" of "guestfs_ntfsresize_opts".
12114 See "CALLS WITH OPTIONAL ARGUMENTS".
12116 guestfs_ntfsresize_size
12118 int
12119 guestfs_ntfsresize_size (guestfs_h *g,
12120 const char *device,
12121 int64_t size);
12122 This function is deprecated. In new code, use the "guestfs_ntfsresize"
12124 call instead.
12125 Deprecated functions will not be removed from the API, but the fact
12127 that they are deprecated indicates that there are problems with correct
12128 use of these functions.
12129 This command is the same as "guestfs_ntfsresize" except that it allows
12131 you to specify the new size (in bytes) explicitly.
12132 This function returns 0 on success or -1 on error.
12134 This function depends on the feature "ntfsprogs". See also
12136 "guestfs_feature_available".
12137 (Added in 1.3.14)
12139 guestfs_parse_environment
12141 int
12142 guestfs_parse_environment (guestfs_h *g);
12143 Parse the program’s environment and set flags in the handle
12145 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12146 flag is set in the handle.
12147 Most programs do not need to call this. It is done implicitly when you
12149 call "guestfs_create".
12150 See "ENVIRONMENT VARIABLES" for a list of environment variables that
12152 can affect libguestfs handles. See also "guestfs_create_flags", and
12153 "guestfs_parse_environment_list".
12154 This function returns 0 on success or -1 on error.
12156 (Added in 1.19.53)
12158 guestfs_parse_environment_list
12160 int
12161 guestfs_parse_environment_list (guestfs_h *g,
12162 char *const *environment);
12163 Parse the list of strings in the argument "environment" and set flags
12165 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
12166 string in the list, then the ‘verbose’ flag is set in the handle.
12167 This is the same as "guestfs_parse_environment" except that it parses
12169 an explicit list of strings instead of the program's environment.
12170 This function returns 0 on success or -1 on error.
12172 (Added in 1.19.53)
12174 guestfs_part_add
12176 int
12177 guestfs_part_add (guestfs_h *g,
12178 const char *device,
12179 const char *prlogex,
12180 int64_t startsect,
12181 int64_t endsect);
12182 This command adds a partition to "device". If there is no partition
12184 table on the device, call "guestfs_part_init" first.
12185 The "prlogex" parameter is the type of partition. Normally you should
12187 pass "p" or "primary" here, but MBR partition tables also support "l"
12188 (or "logical") and "e" (or "extended") partition types.
12189 "startsect" and "endsect" are the start and end of the partition in
12191 sectors. "endsect" may be negative, which means it counts backwards
12192 from the end of the disk ("-1" is the last sector).
12193 Creating a partition which covers the whole disk is not so easy. Use
12195 "guestfs_part_disk" to do that.
12196 This function returns 0 on success or -1 on error.
12198 (Added in 1.0.78)
12200 guestfs_part_del
12202 int
12203 guestfs_part_del (guestfs_h *g,
12204 const char *device,
12205 int partnum);
12206 This command deletes the partition numbered "partnum" on "device".
12208 Note that in the case of MBR partitioning, deleting an extended
12210 partition also deletes any logical partitions it contains.
12211 This function returns 0 on success or -1 on error.
12213 (Added in 1.3.2)
12215 guestfs_part_disk
12217 int
12218 guestfs_part_disk (guestfs_h *g,
12219 const char *device,
12220 const char *parttype);
12221 This command is simply a combination of "guestfs_part_init" followed by
12223 "guestfs_part_add" to create a single primary partition covering the
12224 whole disk.
12225 "parttype" is the partition table type, usually "mbr" or "gpt", but
12227 other possible values are described in "guestfs_part_init".
12228 This function returns 0 on success or -1 on error.
12230 (Added in 1.0.78)
12232 guestfs_part_expand_gpt
12234 int
12235 guestfs_part_expand_gpt (guestfs_h *g,
12236 const char *device);
12237 Move backup GPT data structures to the end of the disk. This is useful
12239 in case of in-place image expand since disk space after backup GPT
12240 header is not usable. This is equivalent to "sgdisk -e".
12241 See also sgdisk(8).
12243 This function returns 0 on success or -1 on error.
12245 This function depends on the feature "gdisk". See also
12247 "guestfs_feature_available".
12248 (Added in 1.33.2)
12250 guestfs_part_get_bootable
12252 int
12253 guestfs_part_get_bootable (guestfs_h *g,
12254 const char *device,
12255 int partnum);
12256 This command returns true if the partition "partnum" on "device" has
12258 the bootable flag set.
12259 See also "guestfs_part_set_bootable".
12261 This function returns a C truth value on success or -1 on error.
12263 (Added in 1.3.2)
12265 guestfs_part_get_disk_guid
12267 char *
12268 guestfs_part_get_disk_guid (guestfs_h *g,
12269 const char *device);
12270 Return the disk identifier (GUID) of a GPT-partitioned "device".
12272 Behaviour is undefined for other partition types.
12273 This function returns a string, or NULL on error. The caller must free
12275 the returned string after use.
12276 This function depends on the feature "gdisk". See also
12278 "guestfs_feature_available".
12279 (Added in 1.33.2)
12281 guestfs_part_get_gpt_attributes
12283 int64_t
12284 guestfs_part_get_gpt_attributes (guestfs_h *g,
12285 const char *device,
12286 int partnum);
12287 Return the attribute flags of numbered GPT partition "partnum". An
12289 error is returned for MBR partitions.
12290 On error this function returns -1.
12292 This function depends on the feature "gdisk". See also
12294 "guestfs_feature_available".
12295 (Added in 1.21.1)
12297 guestfs_part_get_gpt_guid
12299 char *
12300 guestfs_part_get_gpt_guid (guestfs_h *g,
12301 const char *device,
12302 int partnum);
12303 Return the GUID of numbered GPT partition "partnum".
12305 This function returns a string, or NULL on error. The caller must free
12307 the returned string after use.
12308 This function depends on the feature "gdisk". See also
12310 "guestfs_feature_available".
12311 (Added in 1.29.25)
12313 guestfs_part_get_gpt_type
12315 char *
12316 guestfs_part_get_gpt_type (guestfs_h *g,
12317 const char *device,
12318 int partnum);
12319 Return the type GUID of numbered GPT partition "partnum". For MBR
12321 partitions, return an appropriate GUID corresponding to the MBR type.
12322 Behaviour is undefined for other partition types.
12323 This function returns a string, or NULL on error. The caller must free
12325 the returned string after use.
12326 This function depends on the feature "gdisk". See also
12328 "guestfs_feature_available".
12329 (Added in 1.21.1)
12331 guestfs_part_get_mbr_id
12333 int
12334 guestfs_part_get_mbr_id (guestfs_h *g,
12335 const char *device,
12336 int partnum);
12337 Returns the MBR type byte (also known as the ID byte) from the numbered
12339 partition "partnum".
12340 Note that only MBR (old DOS-style) partitions have type bytes. You
12342 will get undefined results for other partition table types (see
12343 "guestfs_part_get_parttype").
12344 On error this function returns -1.
12346 (Added in 1.3.2)
12348 guestfs_part_get_mbr_part_type
12350 char *
12351 guestfs_part_get_mbr_part_type (guestfs_h *g,
12352 const char *device,
12353 int partnum);
12354 This returns the partition type of an MBR partition numbered "partnum"
12356 on device "device".
12357 It returns "primary", "logical", or "extended".
12359 This function returns a string, or NULL on error. The caller must free
12361 the returned string after use.
12362 (Added in 1.29.32)
12364 guestfs_part_get_name
12366 char *
12367 guestfs_part_get_name (guestfs_h *g,
12368 const char *device,
12369 int partnum);
12370 This gets the partition name on partition numbered "partnum" on device
12372 "device". Note that partitions are numbered from 1.
12373 The partition name can only be read on certain types of partition
12375 table. This works on "gpt" but not on "mbr" partitions.
12376 This function returns a string, or NULL on error. The caller must free
12378 the returned string after use.
12379 (Added in 1.25.33)
12381 guestfs_part_get_parttype
12383 char *
12384 guestfs_part_get_parttype (guestfs_h *g,
12385 const char *device);
12386 This command examines the partition table on "device" and returns the
12388 partition table type (format) being used.
12389 Common return values include: "msdos" (a DOS/Windows style MBR
12391 partition table), "gpt" (a GPT/EFI-style partition table). Other
12392 values are possible, although unusual. See "guestfs_part_init" for a
12393 full list.
12394 This function returns a string, or NULL on error. The caller must free
12396 the returned string after use.
12397 (Added in 1.0.78)
12399 guestfs_part_init
12401 int
12402 guestfs_part_init (guestfs_h *g,
12403 const char *device,
12404 const char *parttype);
12405 This creates an empty partition table on "device" of one of the
12407 partition types listed below. Usually "parttype" should be either
12408 "msdos" or "gpt" (for large disks).
12409 Initially there are no partitions. Following this, you should call
12411 "guestfs_part_add" for each partition required.
12412 Possible values for "parttype" are:
12414 "efi"
12416 "gpt"
12417 Intel EFI / GPT partition table.
12418 This is recommended for >= 2 TB partitions that will be accessed
12420 from Linux and Intel-based Mac OS X. It also has limited backwards
12421 compatibility with the "mbr" format.
12422 "mbr"
12424 "msdos"
12425 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12426 and Windows. This partition type will only work for device sizes
12427 up to 2 TB. For large disks we recommend using "gpt".
12428 Other partition table types that may work but are not supported
12430 include:
12431 "aix"
12433 AIX disk labels.
12434 "amiga"
12436 "rdb"
12437 Amiga "Rigid Disk Block" format.
12438 "bsd"
12440 BSD disk labels.
12441 "dasd"
12443 DASD, used on IBM mainframes.
12444 "dvh"
12446 MIPS/SGI volumes.
12447 "mac"
12449 Old Mac partition format. Modern Macs use "gpt".
12450 "pc98"
12452 NEC PC-98 format, common in Japan apparently.
12453 "sun"
12455 Sun disk labels.
12456 This function returns 0 on success or -1 on error.
12458 (Added in 1.0.78)
12460 guestfs_part_list
12462 struct guestfs_partition_list *
12463 guestfs_part_list (guestfs_h *g,
12464 const char *device);
12465 This command parses the partition table on "device" and returns the
12467 list of partitions found.
12468 The fields in the returned structure are:
12470 "part_num"
12472 Partition number, counting from 1.
12473 "part_start"
12475 Start of the partition in bytes. To get sectors you have to divide
12476 by the device’s sector size, see "guestfs_blockdev_getss".
12477 "part_end"
12479 End of the partition in bytes.
12480 "part_size"
12482 Size of the partition in bytes.
12483 This function returns a "struct guestfs_partition_list *", or NULL if
12485 there was an error. The caller must call "guestfs_free_partition_list"
12486 after use.
12487 (Added in 1.0.78)
12489 guestfs_part_resize
12491 int
12492 guestfs_part_resize (guestfs_h *g,
12493 const char *device,
12494 int partnum,
12495 int64_t endsect);
12496 This command resizes the partition numbered "partnum" on "device" by
12498 moving the end position.
12499 Note that this does not modify any filesystem present in the partition.
12501 If you wish to do this, you will need to use filesystem resizing
12502 commands like "guestfs_resize2fs".
12503 When growing a partition you will want to grow the filesystem
12505 afterwards, but when shrinking, you need to shrink the filesystem
12506 before the partition.
12507 This function returns 0 on success or -1 on error.
12509 (Added in 1.37.20)
12511 guestfs_part_set_bootable
12513 int
12514 guestfs_part_set_bootable (guestfs_h *g,
12515 const char *device,
12516 int partnum,
12517 int bootable);
12518 This sets the bootable flag on partition numbered "partnum" on device
12520 "device". Note that partitions are numbered from 1.
12521 The bootable flag is used by some operating systems (notably Windows)
12523 to determine which partition to boot from. It is by no means
12524 universally recognized.
12525 This function returns 0 on success or -1 on error.
12527 (Added in 1.0.78)
12529 guestfs_part_set_disk_guid
12531 int
12532 guestfs_part_set_disk_guid (guestfs_h *g,
12533 const char *device,
12534 const char *guid);
12535 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12537 Return an error if the partition table of "device" isn't GPT, or if
12538 "guid" is not a valid GUID.
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_disk_guid_random
12548 int
12549 guestfs_part_set_disk_guid_random (guestfs_h *g,
12550 const char *device);
12551 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12553 randomly generated value. Return an error if the partition table of
12554 "device" isn't GPT.
12555 This function returns 0 on success or -1 on error.
12557 This function depends on the feature "gdisk". See also
12559 "guestfs_feature_available".
12560 (Added in 1.33.2)
12562 guestfs_part_set_gpt_attributes
12564 int
12565 guestfs_part_set_gpt_attributes (guestfs_h *g,
12566 const char *device,
12567 int partnum,
12568 int64_t attributes);
12569 Set the attribute flags of numbered GPT partition "partnum" to
12571 "attributes". Return an error if the partition table of "device" isn't
12572 GPT.
12573 See
12575 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12576 for a useful list of partition attributes.
12577 This function returns 0 on success or -1 on error.
12579 This function depends on the feature "gdisk". See also
12581 "guestfs_feature_available".
12582 (Added in 1.21.1)
12584 guestfs_part_set_gpt_guid
12586 int
12587 guestfs_part_set_gpt_guid (guestfs_h *g,
12588 const char *device,
12589 int partnum,
12590 const char *guid);
12591 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12593 error if the partition table of "device" isn't GPT, or if "guid" is not
12594 a valid GUID.
12595 This function returns 0 on success or -1 on error.
12597 This function depends on the feature "gdisk". See also
12599 "guestfs_feature_available".
12600 (Added in 1.29.25)
12602 guestfs_part_set_gpt_type
12604 int
12605 guestfs_part_set_gpt_type (guestfs_h *g,
12606 const char *device,
12607 int partnum,
12608 const char *guid);
12609 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12611 an error if the partition table of "device" isn't GPT, or if "guid" is
12612 not a valid GUID.
12613 See
12615 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12616 for a useful list of type GUIDs.
12617 This function returns 0 on success or -1 on error.
12619 This function depends on the feature "gdisk". See also
12621 "guestfs_feature_available".
12622 (Added in 1.21.1)
12624 guestfs_part_set_mbr_id
12626 int
12627 guestfs_part_set_mbr_id (guestfs_h *g,
12628 const char *device,
12629 int partnum,
12630 int idbyte);
12631 Sets the MBR type byte (also known as the ID byte) of the numbered
12633 partition "partnum" to "idbyte". Note that the type bytes quoted in
12634 most documentation are in fact hexadecimal numbers, but usually
12635 documented without any leading "0x" which might be confusing.
12636 Note that only MBR (old DOS-style) partitions have type bytes. You
12638 will get undefined results for other partition table types (see
12639 "guestfs_part_get_parttype").
12640 This function returns 0 on success or -1 on error.
12642 (Added in 1.3.2)
12644 guestfs_part_set_name
12646 int
12647 guestfs_part_set_name (guestfs_h *g,
12648 const char *device,
12649 int partnum,
12650 const char *name);
12651 This sets the partition name on partition numbered "partnum" on device
12653 "device". Note that partitions are numbered from 1.
12654 The partition name can only be set on certain types of partition table.
12656 This works on "gpt" but not on "mbr" partitions.
12657 This function returns 0 on success or -1 on error.
12659 (Added in 1.0.78)
12661 guestfs_part_to_dev
12663 char *
12664 guestfs_part_to_dev (guestfs_h *g,
12665 const char *partition);
12666 This function takes a partition name (eg. "/dev/sdb1") and removes the
12668 partition number, returning the device name (eg. "/dev/sdb").
12669 The named partition must exist, for example as a string returned from
12671 "guestfs_list_partitions".
12672 See also "guestfs_part_to_partnum", "guestfs_device_index".
12674 This function returns a string, or NULL on error. The caller must free
12676 the returned string after use.
12677 (Added in 1.5.15)
12679 guestfs_part_to_partnum
12681 int
12682 guestfs_part_to_partnum (guestfs_h *g,
12683 const char *partition);
12684 This function takes a partition name (eg. "/dev/sdb1") and returns the
12686 partition number (eg. 1).
12687 The named partition must exist, for example as a string returned from
12689 "guestfs_list_partitions".
12690 See also "guestfs_part_to_dev".
12692 On error this function returns -1.
12694 (Added in 1.13.25)
12696 guestfs_ping_daemon
12698 int
12699 guestfs_ping_daemon (guestfs_h *g);
12700 This is a test probe into the guestfs daemon running inside the
12702 libguestfs appliance. Calling this function checks that the daemon
12703 responds to the ping message, without affecting the daemon or attached
12704 block device(s) in any other way.
12705 This function returns 0 on success or -1 on error.
12707 (Added in 1.0.18)
12709 guestfs_pread
12711 char *
12712 guestfs_pread (guestfs_h *g,
12713 const char *path,
12714 int count,
12715 int64_t offset,
12716 size_t *size_r);
12717 This command lets you read part of a file. It reads "count" bytes of
12719 the file, starting at "offset", from file "path".
12720 This may read fewer bytes than requested. For further details see the
12722 pread(2) system call.
12723 See also "guestfs_pwrite", "guestfs_pread_device".
12725 This function returns a buffer, or NULL on error. The size of the
12727 returned buffer is written to *size_r. The caller must free the
12728 returned buffer after use.
12729 Because of the message protocol, there is a transfer limit of somewhere
12731 between 2MB and 4MB. See "PROTOCOL LIMITS".
12732 (Added in 1.0.77)
12734 guestfs_pread_device
12736 char *
12737 guestfs_pread_device (guestfs_h *g,
12738 const char *device,
12739 int count,
12740 int64_t offset,
12741 size_t *size_r);
12742 This command lets you read part of a block device. It reads "count"
12744 bytes of "device", starting at "offset".
12745 This may read fewer bytes than requested. For further details see the
12747 pread(2) system call.
12748 See also "guestfs_pread".
12750 This function returns a buffer, or NULL on error. The size of the
12752 returned buffer is written to *size_r. The caller must free the
12753 returned buffer after use.
12754 Because of the message protocol, there is a transfer limit of somewhere
12756 between 2MB and 4MB. See "PROTOCOL LIMITS".
12757 (Added in 1.5.21)
12759 guestfs_pvchange_uuid
12761 int
12762 guestfs_pvchange_uuid (guestfs_h *g,
12763 const char *device);
12764 Generate a new random UUID for the physical volume "device".
12766 This function returns 0 on success or -1 on error.
12768 This function depends on the feature "lvm2". See also
12770 "guestfs_feature_available".
12771 (Added in 1.19.26)
12773 guestfs_pvchange_uuid_all
12775 int
12776 guestfs_pvchange_uuid_all (guestfs_h *g);
12777 Generate new random UUIDs for all physical volumes.
12779 This function returns 0 on success or -1 on error.
12781 This function depends on the feature "lvm2". See also
12783 "guestfs_feature_available".
12784 (Added in 1.19.26)
12786 guestfs_pvcreate
12788 int
12789 guestfs_pvcreate (guestfs_h *g,
12790 const char *device);
12791 This creates an LVM physical volume on the named "device", where
12793 "device" should usually be a partition name such as /dev/sda1.
12794 This function returns 0 on success or -1 on error.
12796 This function depends on the feature "lvm2". See also
12798 "guestfs_feature_available".
12799 (Added in 0.8)
12801 guestfs_pvremove
12803 int
12804 guestfs_pvremove (guestfs_h *g,
12805 const char *device);
12806 This wipes a physical volume "device" so that LVM will no longer
12808 recognise it.
12809 The implementation uses the pvremove(8) command which refuses to wipe
12811 physical volumes that contain any volume groups, so you have to remove
12812 those first.
12813 This function returns 0 on success or -1 on error.
12815 This function depends on the feature "lvm2". See also
12817 "guestfs_feature_available".
12818 (Added in 1.0.13)
12820 guestfs_pvresize
12822 int
12823 guestfs_pvresize (guestfs_h *g,
12824 const char *device);
12825 This resizes (expands or shrinks) an existing LVM physical volume to
12827 match the new size of the underlying device.
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.0.26)
12835 guestfs_pvresize_size
12837 int
12838 guestfs_pvresize_size (guestfs_h *g,
12839 const char *device,
12840 int64_t size);
12841 This command is the same as "guestfs_pvresize" except that it allows
12843 you to specify the new size (in bytes) explicitly.
12844 This function returns 0 on success or -1 on error.
12846 This function depends on the feature "lvm2". See also
12848 "guestfs_feature_available".
12849 (Added in 1.3.14)
12851 guestfs_pvs
12853 char **
12854 guestfs_pvs (guestfs_h *g);
12855 List all the physical volumes detected. This is the equivalent of the
12857 pvs(8) command.
12858 This returns a list of just the device names that contain PVs (eg.
12860 /dev/sda2).
12861 See also "guestfs_pvs_full".
12863 This function returns a NULL-terminated array of strings (like
12865 environ(3)), or NULL if there was an error. The caller must free the
12866 strings and the array after use.
12867 This function depends on the feature "lvm2". See also
12869 "guestfs_feature_available".
12870 (Added in 0.4)
12872 guestfs_pvs_full
12874 struct guestfs_lvm_pv_list *
12875 guestfs_pvs_full (guestfs_h *g);
12876 List all the physical volumes detected. This is the equivalent of the
12878 pvs(8) command. The "full" version includes all fields.
12879 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
12881 there was an error. The caller must call "guestfs_free_lvm_pv_list"
12882 after use.
12883 This function depends on the feature "lvm2". See also
12885 "guestfs_feature_available".
12886 (Added in 0.4)
12888 guestfs_pvuuid
12890 char *
12891 guestfs_pvuuid (guestfs_h *g,
12892 const char *device);
12893 This command returns the UUID of the LVM PV "device".
12895 This function returns a string, or NULL on error. The caller must free
12897 the returned string after use.
12898 (Added in 1.0.87)
12900 guestfs_pwrite
12902 int
12903 guestfs_pwrite (guestfs_h *g,
12904 const char *path,
12905 const char *content,
12906 size_t content_size,
12907 int64_t offset);
12908 This command writes to part of a file. It writes the data buffer
12910 "content" to the file "path" starting at offset "offset".
12911 This command implements the pwrite(2) system call, and like that system
12913 call it may not write the full data requested. The return value is the
12914 number of bytes that were actually written to the file. This could
12915 even be 0, although short writes are unlikely for regular files in
12916 ordinary circumstances.
12917 See also "guestfs_pread", "guestfs_pwrite_device".
12919 On error this function returns -1.
12921 Because of the message protocol, there is a transfer limit of somewhere
12923 between 2MB and 4MB. See "PROTOCOL LIMITS".
12924 (Added in 1.3.14)
12926 guestfs_pwrite_device
12928 int
12929 guestfs_pwrite_device (guestfs_h *g,
12930 const char *device,
12931 const char *content,
12932 size_t content_size,
12933 int64_t offset);
12934 This command writes to part of a device. It writes the data buffer
12936 "content" to "device" starting at offset "offset".
12937 This command implements the pwrite(2) system call, and like that system
12939 call it may not write the full data requested (although short writes to
12940 disk devices and partitions are probably impossible with standard Linux
12941 kernels).
12942 See also "guestfs_pwrite".
12944 On error this function returns -1.
12946 Because of the message protocol, there is a transfer limit of somewhere
12948 between 2MB and 4MB. See "PROTOCOL LIMITS".
12949 (Added in 1.5.20)
12951 guestfs_read_file
12953 char *
12954 guestfs_read_file (guestfs_h *g,
12955 const char *path,
12956 size_t *size_r);
12957 This calls returns the contents of the file "path" as a buffer.
12959 Unlike "guestfs_cat", this function can correctly handle files that
12961 contain embedded ASCII NUL characters.
12962 This function returns a buffer, or NULL on error. The size of the
12964 returned buffer is written to *size_r. The caller must free the
12965 returned buffer after use.
12966 (Added in 1.0.63)
12968 guestfs_read_lines
12970 char **
12971 guestfs_read_lines (guestfs_h *g,
12972 const char *path);
12973 Return the contents of the file named "path".
12975 The file contents are returned as a list of lines. Trailing "LF" and
12977 "CRLF" character sequences are not returned.
12978 Note that this function cannot correctly handle binary files
12980 (specifically, files containing "\0" character which is treated as end
12981 of string). For those you need to use the "guestfs_read_file" function
12982 and split the buffer into lines yourself.
12983 This function returns a NULL-terminated array of strings (like
12985 environ(3)), or NULL if there was an error. The caller must free the
12986 strings and the array after use.
12987 (Added in 0.7)
12989 guestfs_readdir
12991 struct guestfs_dirent_list *
12992 guestfs_readdir (guestfs_h *g,
12993 const char *dir);
12994 This returns the list of directory entries in directory "dir".
12996 All entries in the directory are returned, including "." and "..". The
12998 entries are not sorted, but returned in the same order as the
12999 underlying filesystem.
13000 Also this call returns basic file type information about each file.
13002 The "ftyp" field will contain one of the following characters:
13003 'b' Block special
13005 'c' Char special
13007 'd' Directory
13009 'f' FIFO (named pipe)
13011 'l' Symbolic link
13013 'r' Regular file
13015 's' Socket
13017 'u' Unknown file type
13019 '?' The readdir(3) call returned a "d_type" field with an unexpected
13021 value
13022 This function is primarily intended for use by programs. To get a
13024 simple list of names, use "guestfs_ls". To get a printable directory
13025 for human consumption, use "guestfs_ll".
13026 This function returns a "struct guestfs_dirent_list *", or NULL if
13028 there was an error. The caller must call "guestfs_free_dirent_list"
13029 after use.
13030 Because of the message protocol, there is a transfer limit of somewhere
13032 between 2MB and 4MB. See "PROTOCOL LIMITS".
13033 (Added in 1.0.55)
13035 guestfs_readlink
13037 char *
13038 guestfs_readlink (guestfs_h *g,
13039 const char *path);
13040 This command reads the target of a symbolic link.
13042 This function returns a string, or NULL on error. The caller must free
13044 the returned string after use.
13045 (Added in 1.0.66)
13047 guestfs_readlinklist
13049 char **
13050 guestfs_readlinklist (guestfs_h *g,
13051 const char *path,
13052 char *const *names);
13053 This call allows you to do a "readlink" operation on multiple files,
13055 where all files are in the directory "path". "names" is the list of
13056 files from this directory.
13057 On return you get a list of strings, with a one-to-one correspondence
13059 to the "names" list. Each string is the value of the symbolic link.
13060 If the readlink(2) operation fails on any name, then the corresponding
13062 result string is the empty string "". However the whole operation is
13063 completed even if there were readlink(2) errors, and so you can call
13064 this function with names where you don't know if they are symbolic
13065 links already (albeit slightly less efficient).
13066 This call is intended for programs that want to efficiently list a
13068 directory contents without making many round-trips.
13069 This function returns a NULL-terminated array of strings (like
13071 environ(3)), or NULL if there was an error. The caller must free the
13072 strings and the array after use.
13073 (Added in 1.0.77)
13075 guestfs_realpath
13077 char *
13078 guestfs_realpath (guestfs_h *g,
13079 const char *path);
13080 Return the canonicalized absolute pathname of "path". The returned
13082 path has no ".", ".." or symbolic link path elements.
13083 This function returns a string, or NULL on error. The caller must free
13085 the returned string after use.
13086 (Added in 1.0.66)
13088 guestfs_remount
13090 int
13091 guestfs_remount (guestfs_h *g,
13092 const char *mountpoint,
13093 ...);
13094 You may supply a list of optional arguments to this call. Use zero or
13096 more of the following pairs of parameters, and terminate the list with
13097 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13098 GUESTFS_REMOUNT_RW, int rw,
13100 This call allows you to change the "rw" (readonly/read-write) flag on
13102 an already mounted filesystem at "mountpoint", converting a readonly
13103 filesystem to be read-write, or vice-versa.
13104 Note that at the moment you must supply the "optional" "rw" parameter.
13106 In future we may allow other flags to be adjusted.
13107 This function returns 0 on success or -1 on error.
13109 (Added in 1.23.2)
13111 guestfs_remount_va
13113 int
13114 guestfs_remount_va (guestfs_h *g,
13115 const char *mountpoint,
13116 va_list args);
13117 This is the "va_list variant" of "guestfs_remount".
13119 See "CALLS WITH OPTIONAL ARGUMENTS".
13121 guestfs_remount_argv
13123 int
13124 guestfs_remount_argv (guestfs_h *g,
13125 const char *mountpoint,
13126 const struct guestfs_remount_argv *optargs);
13127 This is the "argv variant" of "guestfs_remount".
13129 See "CALLS WITH OPTIONAL ARGUMENTS".
13131 guestfs_remove_drive
13133 int
13134 guestfs_remove_drive (guestfs_h *g,
13135 const char *label);
13136 This function is conceptually the opposite of "guestfs_add_drive_opts".
13138 It removes the drive that was previously added with label "label".
13139 Note that in order to remove drives, you have to add them with labels
13141 (see the optional "label" argument to "guestfs_add_drive_opts"). If
13142 you didn't use a label, then they cannot be removed.
13143 You can call this function before or after launching the handle. If
13145 called after launch, if the backend supports it, we try to hot unplug
13146 the drive: see "HOTPLUGGING". The disk must not be in use (eg.
13147 mounted) when you do this. We try to detect if the disk is in use and
13148 stop you from doing this.
13149 This function returns 0 on success or -1 on error.
13151 (Added in 1.19.49)
13153 guestfs_removexattr
13155 int
13156 guestfs_removexattr (guestfs_h *g,
13157 const char *xattr,
13158 const char *path);
13159 This call removes the extended attribute named "xattr" of the file
13161 "path".
13162 See also: "guestfs_lremovexattr", attr(5).
13164 This function returns 0 on success or -1 on error.
13166 This function depends on the feature "linuxxattrs". See also
13168 "guestfs_feature_available".
13169 (Added in 1.0.59)
13171 guestfs_rename
13173 int
13174 guestfs_rename (guestfs_h *g,
13175 const char *oldpath,
13176 const char *newpath);
13177 Rename a file to a new place on the same filesystem. This is the same
13179 as the Linux rename(2) system call. In most cases you are better to
13180 use "guestfs_mv" instead.
13181 This function returns 0 on success or -1 on error.
13183 (Added in 1.21.5)
13185 guestfs_resize2fs
13187 int
13188 guestfs_resize2fs (guestfs_h *g,
13189 const char *device);
13190 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13192 underlying device.
13193 See also "RESIZE2FS ERRORS".
13195 This function returns 0 on success or -1 on error.
13197 (Added in 1.0.27)
13199 guestfs_resize2fs_M
13201 int
13202 guestfs_resize2fs_M (guestfs_h *g,
13203 const char *device);
13204 This command is the same as "guestfs_resize2fs", but the filesystem is
13206 resized to its minimum size. This works like the -M option to the
13207 resize2fs(8) command.
13208 To get the resulting size of the filesystem you should call
13210 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13211 These two numbers, multiplied together, give the resulting size of the
13212 minimal filesystem in bytes.
13213 See also "RESIZE2FS ERRORS".
13215 This function returns 0 on success or -1 on error.
13217 (Added in 1.9.4)
13219 guestfs_resize2fs_size
13221 int
13222 guestfs_resize2fs_size (guestfs_h *g,
13223 const char *device,
13224 int64_t size);
13225 This command is the same as "guestfs_resize2fs" except that it allows
13227 you to specify the new size (in bytes) explicitly.
13228 See also "RESIZE2FS ERRORS".
13230 This function returns 0 on success or -1 on error.
13232 (Added in 1.3.14)
13234 guestfs_rm
13236 int
13237 guestfs_rm (guestfs_h *g,
13238 const char *path);
13239 Remove the single file "path".
13241 This function returns 0 on success or -1 on error.
13243 (Added in 0.8)
13245 guestfs_rm_f
13247 int
13248 guestfs_rm_f (guestfs_h *g,
13249 const char *path);
13250 Remove the file "path".
13252 If the file doesn't exist, that error is ignored. (Other errors, eg.
13254 I/O errors or bad paths, are not ignored)
13255 This call cannot remove directories. Use "guestfs_rmdir" to remove an
13257 empty directory, or "guestfs_rm_rf" to remove directories recursively.
13258 This function returns 0 on success or -1 on error.
13260 (Added in 1.19.42)
13262 guestfs_rm_rf
13264 int
13265 guestfs_rm_rf (guestfs_h *g,
13266 const char *path);
13267 Remove the file or directory "path", recursively removing the contents
13269 if its a directory. This is like the "rm -rf" shell command.
13270 This function returns 0 on success or -1 on error.
13272 (Added in 0.8)
13274 guestfs_rmdir
13276 int
13277 guestfs_rmdir (guestfs_h *g,
13278 const char *path);
13279 Remove the single directory "path".
13281 This function returns 0 on success or -1 on error.
13283 (Added in 0.8)
13285 guestfs_rmmountpoint
13287 int
13288 guestfs_rmmountpoint (guestfs_h *g,
13289 const char *exemptpath);
13290 This call removes a mountpoint that was previously created with
13292 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13293 This function returns 0 on success or -1 on error.
13295 (Added in 1.0.62)
13297 guestfs_rsync
13299 int
13300 guestfs_rsync (guestfs_h *g,
13301 const char *src,
13302 const char *dest,
13303 ...);
13304 You may supply a list of optional arguments to this call. Use zero or
13306 more of the following pairs of parameters, and terminate the list with
13307 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13308 GUESTFS_RSYNC_ARCHIVE, int archive,
13310 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13311 This call may be used to copy or synchronize two directories under the
13313 same libguestfs handle. This uses the rsync(1) program which uses a
13314 fast algorithm that avoids copying files unnecessarily.
13315 "src" and "dest" are the source and destination directories. Files are
13317 copied from "src" to "dest".
13318 The optional arguments are:
13320 "archive"
13322 Turns on archive mode. This is the same as passing the --archive
13323 flag to "rsync".
13324 "deletedest"
13326 Delete files at the destination that do not exist at the source.
13327 This function returns 0 on success or -1 on error.
13329 This function depends on the feature "rsync". See also
13331 "guestfs_feature_available".
13332 (Added in 1.19.29)
13334 guestfs_rsync_va
13336 int
13337 guestfs_rsync_va (guestfs_h *g,
13338 const char *src,
13339 const char *dest,
13340 va_list args);
13341 This is the "va_list variant" of "guestfs_rsync".
13343 See "CALLS WITH OPTIONAL ARGUMENTS".
13345 guestfs_rsync_argv
13347 int
13348 guestfs_rsync_argv (guestfs_h *g,
13349 const char *src,
13350 const char *dest,
13351 const struct guestfs_rsync_argv *optargs);
13352 This is the "argv variant" of "guestfs_rsync".
13354 See "CALLS WITH OPTIONAL ARGUMENTS".
13356 guestfs_rsync_in
13358 int
13359 guestfs_rsync_in (guestfs_h *g,
13360 const char *remote,
13361 const char *dest,
13362 ...);
13363 You may supply a list of optional arguments to this call. Use zero or
13365 more of the following pairs of parameters, and terminate the list with
13366 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13367 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13369 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13370 This call may be used to copy or synchronize the filesystem on the host
13372 or on a remote computer with the filesystem within libguestfs. This
13373 uses the rsync(1) program which uses a fast algorithm that avoids
13374 copying files unnecessarily.
13375 This call only works if the network is enabled. See
13377 "guestfs_set_network" or the --network option to various tools like
13378 guestfish(1).
13379 Files are copied from the remote server and directory specified by
13381 "remote" to the destination directory "dest".
13382 The format of the remote server string is defined by rsync(1). Note
13384 that there is no way to supply a password or passphrase so the target
13385 must be set up not to require one.
13386 The optional arguments are the same as those of "guestfs_rsync".
13388 This function returns 0 on success or -1 on error.
13390 This function depends on the feature "rsync". See also
13392 "guestfs_feature_available".
13393 (Added in 1.19.29)
13395 guestfs_rsync_in_va
13397 int
13398 guestfs_rsync_in_va (guestfs_h *g,
13399 const char *remote,
13400 const char *dest,
13401 va_list args);
13402 This is the "va_list variant" of "guestfs_rsync_in".
13404 See "CALLS WITH OPTIONAL ARGUMENTS".
13406 guestfs_rsync_in_argv
13408 int
13409 guestfs_rsync_in_argv (guestfs_h *g,
13410 const char *remote,
13411 const char *dest,
13412 const struct guestfs_rsync_in_argv *optargs);
13413 This is the "argv variant" of "guestfs_rsync_in".
13415 See "CALLS WITH OPTIONAL ARGUMENTS".
13417 guestfs_rsync_out
13419 int
13420 guestfs_rsync_out (guestfs_h *g,
13421 const char *src,
13422 const char *remote,
13423 ...);
13424 You may supply a list of optional arguments to this call. Use zero or
13426 more of the following pairs of parameters, and terminate the list with
13427 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13428 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13430 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13431 This call may be used to copy or synchronize the filesystem within
13433 libguestfs with a filesystem on the host or on a remote computer. This
13434 uses the rsync(1) program which uses a fast algorithm that avoids
13435 copying files unnecessarily.
13436 This call only works if the network is enabled. See
13438 "guestfs_set_network" or the --network option to various tools like
13439 guestfish(1).
13440 Files are copied from the source directory "src" to the remote server
13442 and directory specified by "remote".
13443 The format of the remote server string is defined by rsync(1). Note
13445 that there is no way to supply a password or passphrase so the target
13446 must be set up not to require one.
13447 The optional arguments are the same as those of "guestfs_rsync".
13449 Globbing does not happen on the "src" parameter. In programs which use
13451 the API directly you have to expand wildcards yourself (see
13452 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13453 (see "glob" in guestfish(1)), for example:
13454 ><fs> glob rsync-out /* rsync://remote/
13456 This function returns 0 on success or -1 on error.
13458 This function depends on the feature "rsync". See also
13460 "guestfs_feature_available".
13461 (Added in 1.19.29)
13463 guestfs_rsync_out_va
13465 int
13466 guestfs_rsync_out_va (guestfs_h *g,
13467 const char *src,
13468 const char *remote,
13469 va_list args);
13470 This is the "va_list variant" of "guestfs_rsync_out".
13472 See "CALLS WITH OPTIONAL ARGUMENTS".
13474 guestfs_rsync_out_argv
13476 int
13477 guestfs_rsync_out_argv (guestfs_h *g,
13478 const char *src,
13479 const char *remote,
13480 const struct guestfs_rsync_out_argv *optargs);
13481 This is the "argv variant" of "guestfs_rsync_out".
13483 See "CALLS WITH OPTIONAL ARGUMENTS".
13485 guestfs_scrub_device
13487 int
13488 guestfs_scrub_device (guestfs_h *g,
13489 const char *device);
13490 This command writes patterns over "device" to make data retrieval more
13492 difficult.
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_file
13505 int
13506 guestfs_scrub_file (guestfs_h *g,
13507 const char *file);
13508 This command writes patterns over a file to make data retrieval more
13510 difficult.
13511 The file is removed after scrubbing.
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_scrub_freespace
13525 int
13526 guestfs_scrub_freespace (guestfs_h *g,
13527 const char *dir);
13528 This command creates the directory "dir" and then fills it with files
13530 until the filesystem is full, and scrubs the files as for
13531 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13532 free space on the partition containing "dir".
13533 It is an interface to the scrub(1) program. See that manual page for
13535 more details.
13536 This function returns 0 on success or -1 on error.
13538 This function depends on the feature "scrub". See also
13540 "guestfs_feature_available".
13541 (Added in 1.0.52)
13543 guestfs_selinux_relabel
13545 int
13546 guestfs_selinux_relabel (guestfs_h *g,
13547 const char *specfile,
13548 const char *path,
13549 ...);
13550 You may supply a list of optional arguments to this call. Use zero or
13552 more of the following pairs of parameters, and terminate the list with
13553 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13554 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13556 SELinux relabel parts of the filesystem.
13558 The "specfile" parameter controls the policy spec file used. You have
13560 to parse "/etc/selinux/config" to find the correct SELinux policy and
13561 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13562 "/contexts/files/file_contexts".
13563 The required "path" parameter is the top level directory where
13565 relabelling starts. Normally you should pass "path" as "/" to relabel
13566 the whole guest filesystem.
13567 The optional "force" boolean controls whether the context is reset for
13569 customizable files, and also whether the user, role and range parts of
13570 the file context is changed.
13571 This function returns 0 on success or -1 on error.
13573 This function depends on the feature "selinuxrelabel". See also
13575 "guestfs_feature_available".
13576 (Added in 1.33.43)
13578 guestfs_selinux_relabel_va
13580 int
13581 guestfs_selinux_relabel_va (guestfs_h *g,
13582 const char *specfile,
13583 const char *path,
13584 va_list args);
13585 This is the "va_list variant" of "guestfs_selinux_relabel".
13587 See "CALLS WITH OPTIONAL ARGUMENTS".
13589 guestfs_selinux_relabel_argv
13591 int
13592 guestfs_selinux_relabel_argv (guestfs_h *g,
13593 const char *specfile,
13594 const char *path,
13595 const struct guestfs_selinux_relabel_argv *optargs);
13596 This is the "argv variant" of "guestfs_selinux_relabel".
13598 See "CALLS WITH OPTIONAL ARGUMENTS".
13600 guestfs_set_append
13602 int
13603 guestfs_set_append (guestfs_h *g,
13604 const char *append);
13605 This function is used to add additional options to the libguestfs
13607 appliance kernel command line.
13608 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13610 environment variable.
13611 Setting "append" to "NULL" means no additional options are passed
13613 (libguestfs always adds a few of its own).
13614 This function returns 0 on success or -1 on error.
13616 (Added in 1.0.26)
13618 guestfs_set_attach_method
13620 int
13621 guestfs_set_attach_method (guestfs_h *g,
13622 const char *backend);
13623 This function is deprecated. In new code, use the
13625 "guestfs_set_backend" call instead.
13626 Deprecated functions will not be removed from the API, but the fact
13628 that they are deprecated indicates that there are problems with correct
13629 use of these functions.
13630 Set the method that libguestfs uses to connect to the backend guestfsd
13632 daemon.
13633 See "BACKEND".
13635 This function returns 0 on success or -1 on error.
13637 (Added in 1.9.8)
13639 guestfs_set_autosync
13641 int
13642 guestfs_set_autosync (guestfs_h *g,
13643 int autosync);
13644 If "autosync" is true, this enables autosync. Libguestfs will make a
13646 best effort attempt to make filesystems consistent and synchronized
13647 when the handle is closed (also if the program exits without closing
13648 handles).
13649 This is enabled by default (since libguestfs 1.5.24, previously it was
13651 disabled by default).
13652 This function returns 0 on success or -1 on error.
13654 (Added in 0.3)
13656 guestfs_set_backend
13658 int
13659 guestfs_set_backend (guestfs_h *g,
13660 const char *backend);
13661 Set the method that libguestfs uses to connect to the backend guestfsd
13663 daemon.
13664 This handle property was previously called the "attach method".
13666 See "BACKEND".
13668 This function returns 0 on success or -1 on error.
13670 (Added in 1.21.26)
13672 guestfs_set_backend_setting
13674 int
13675 guestfs_set_backend_setting (guestfs_h *g,
13676 const char *name,
13677 const char *val);
13678 Append "name=value" to the backend settings string list. However if a
13680 string already exists matching "name" or beginning with "name=", then
13681 that setting is replaced.
13682 See "BACKEND", "BACKEND SETTINGS".
13684 This function returns 0 on success or -1 on error.
13686 (Added in 1.27.2)
13688 guestfs_set_backend_settings
13690 int
13691 guestfs_set_backend_settings (guestfs_h *g,
13692 char *const *settings);
13693 Set a list of zero or more settings which are passed through to the
13695 current backend. Each setting is a string which is interpreted in a
13696 backend-specific way, or ignored if not understood by the backend.
13697 The default value is an empty list, unless the environment variable
13699 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13700 This environment variable contains a colon-separated list of settings.
13701 This call replaces all backend settings. If you want to replace a
13703 single backend setting, see "guestfs_set_backend_setting". If you want
13704 to clear a single backend setting, see "guestfs_clear_backend_setting".
13705 See "BACKEND", "BACKEND SETTINGS".
13707 This function returns 0 on success or -1 on error.
13709 (Added in 1.25.24)
13711 guestfs_set_cachedir
13713 int
13714 guestfs_set_cachedir (guestfs_h *g,
13715 const char *cachedir);
13716 Set the directory used by the handle to store the appliance cache, when
13718 using a supermin appliance. The appliance is cached and shared between
13719 all handles which have the same effective user ID.
13720 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13722 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13723 default. Else if "TMPDIR" is set, then that is the default. Else
13724 /var/tmp is the default.
13725 This function returns 0 on success or -1 on error.
13727 (Added in 1.19.58)
13729 guestfs_set_direct
13731 int
13732 guestfs_set_direct (guestfs_h *g,
13733 int direct);
13734 This function is deprecated. In new code, use the
13736 "guestfs_internal_get_console_socket" call instead.
13737 Deprecated functions will not be removed from the API, but the fact
13739 that they are deprecated indicates that there are problems with correct
13740 use of these functions.
13741 If the direct appliance mode flag is enabled, then stdin and stdout are
13743 passed directly through to the appliance once it is launched.
13744 One consequence of this is that log messages aren't caught by the
13746 library and handled by "guestfs_set_log_message_callback", but go
13747 straight to stdout.
13748 You probably don't want to use this unless you know what you are doing.
13750 The default is disabled.
13752 This function returns 0 on success or -1 on error.
13754 (Added in 1.0.72)
13756 guestfs_set_e2attrs
13758 int
13759 guestfs_set_e2attrs (guestfs_h *g,
13760 const char *file,
13761 const char *attrs,
13762 ...);
13763 You may supply a list of optional arguments to this call. Use zero or
13765 more of the following pairs of parameters, and terminate the list with
13766 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13767 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13769 This sets or clears the file attributes "attrs" associated with the
13771 inode file.
13772 "attrs" is a string of characters representing file attributes. See
13774 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13775 attributes can be changed.
13776 If optional boolean "clear" is not present or false, then the "attrs"
13778 listed are set in the inode.
13779 If "clear" is true, then the "attrs" listed are cleared in the inode.
13781 In both cases, other attributes not present in the "attrs" string are
13783 left unchanged.
13784 These attributes are only present when the file is located on an
13786 ext2/3/4 filesystem. Using this call on other filesystem types will
13787 result in an error.
13788 This function returns 0 on success or -1 on error.
13790 (Added in 1.17.31)
13792 guestfs_set_e2attrs_va
13794 int
13795 guestfs_set_e2attrs_va (guestfs_h *g,
13796 const char *file,
13797 const char *attrs,
13798 va_list args);
13799 This is the "va_list variant" of "guestfs_set_e2attrs".
13801 See "CALLS WITH OPTIONAL ARGUMENTS".
13803 guestfs_set_e2attrs_argv
13805 int
13806 guestfs_set_e2attrs_argv (guestfs_h *g,
13807 const char *file,
13808 const char *attrs,
13809 const struct guestfs_set_e2attrs_argv *optargs);
13810 This is the "argv variant" of "guestfs_set_e2attrs".
13812 See "CALLS WITH OPTIONAL ARGUMENTS".
13814 guestfs_set_e2generation
13816 int
13817 guestfs_set_e2generation (guestfs_h *g,
13818 const char *file,
13819 int64_t generation);
13820 This sets the ext2 file generation of a file.
13822 See "guestfs_get_e2generation".
13824 This function returns 0 on success or -1 on error.
13826 (Added in 1.17.31)
13828 guestfs_set_e2label
13830 int
13831 guestfs_set_e2label (guestfs_h *g,
13832 const char *device,
13833 const char *label);
13834 This function is deprecated. In new code, use the "guestfs_set_label"
13836 call instead.
13837 Deprecated functions will not be removed from the API, but the fact
13839 that they are deprecated indicates that there are problems with correct
13840 use of these functions.
13841 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13843 to "label". Filesystem labels are limited to 16 characters.
13844 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13846 return the existing label on a filesystem.
13847 This function returns 0 on success or -1 on error.
13849 (Added in 1.0.15)
13851 guestfs_set_e2uuid
13853 int
13854 guestfs_set_e2uuid (guestfs_h *g,
13855 const char *device,
13856 const char *uuid);
13857 This function is deprecated. In new code, use the "guestfs_set_uuid"
13859 call instead.
13860 Deprecated functions will not be removed from the API, but the fact
13862 that they are deprecated indicates that there are problems with correct
13863 use of these functions.
13864 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
13866 "uuid". The format of the UUID and alternatives such as "clear",
13867 "random" and "time" are described in the tune2fs(8) manpage.
13868 You can use "guestfs_vfs_uuid" to return the existing UUID of a
13870 filesystem.
13871 This function returns 0 on success or -1 on error.
13873 (Added in 1.0.15)
13875 guestfs_set_hv
13877 int
13878 guestfs_set_hv (guestfs_h *g,
13879 const char *hv);
13880 Set the hypervisor binary that we will use. The hypervisor depends on
13882 the backend, but is usually the location of the qemu/KVM hypervisor.
13883 For the uml backend, it is the location of the "linux" or "vmlinux"
13884 binary.
13885 The default is chosen when the library was compiled by the configure
13887 script.
13888 You can also override this by setting the "LIBGUESTFS_HV" environment
13890 variable.
13891 Note that you should call this function as early as possible after
13893 creating the handle. This is because some pre-launch operations depend
13894 on testing qemu features (by running "qemu -help"). If the qemu binary
13895 changes, we don't retest features, and so you might see inconsistent
13896 results. Using the environment variable "LIBGUESTFS_HV" is safest of
13897 all since that picks the qemu binary at the same time as the handle is
13898 created.
13899 This function returns 0 on success or -1 on error.
13901 (Added in 1.23.17)
13903 guestfs_set_identifier
13905 int
13906 guestfs_set_identifier (guestfs_h *g,
13907 const char *identifier);
13908 This is an informative string which the caller may optionally set in
13910 the handle. It is printed in various places, allowing the current
13911 handle to be identified in debugging output.
13912 One important place is when tracing is enabled. If the identifier
13914 string is not an empty string, then trace messages change from this:
13915 libguestfs: trace: get_tmpdir
13917 libguestfs: trace: get_tmpdir = "/tmp"
13918 to this:
13920 libguestfs: trace: ID: get_tmpdir
13922 libguestfs: trace: ID: get_tmpdir = "/tmp"
13923 where "ID" is the identifier string set by this call.
13925 The identifier must only contain alphanumeric ASCII characters,
13927 underscore and minus sign. The default is the empty string.
13928 See also "guestfs_set_program", "guestfs_set_trace",
13930 "guestfs_get_identifier".
13931 This function returns 0 on success or -1 on error.
13933 (Added in 1.31.14)
13935 guestfs_set_label
13937 int
13938 guestfs_set_label (guestfs_h *g,
13939 const char *mountable,
13940 const char *label);
13941 Set the filesystem label on "mountable" to "label".
13943 Only some filesystem types support labels, and libguestfs supports
13945 setting labels on only a subset of these.
13946 ext2, ext3, ext4
13948 Labels are limited to 16 bytes.
13949 NTFS
13951 Labels are limited to 128 unicode characters.
13952 XFS The label is limited to 12 bytes. The filesystem must not be
13954 mounted when trying to set the label.
13955 btrfs
13957 The label is limited to 255 bytes and some characters are not
13958 allowed. Setting the label on a btrfs subvolume will set the label
13959 on its parent filesystem. The filesystem must not be mounted when
13960 trying to set the label.
13961 fat The label is limited to 11 bytes.
13963 swap
13965 The label is limited to 16 bytes.
13966 If there is no support for changing the label for the type of the
13968 specified filesystem, set_label will fail and set errno as ENOTSUP.
13969 To read the label on a filesystem, call "guestfs_vfs_label".
13971 This function returns 0 on success or -1 on error.
13973 (Added in 1.17.9)
13975 guestfs_set_libvirt_requested_credential
13977 int
13978 guestfs_set_libvirt_requested_credential (guestfs_h *g,
13979 int index,
13980 const char *cred,
13981 size_t cred_size);
13982 After requesting the "index"'th credential from the user, call this
13984 function to pass the answer back to libvirt.
13985 See "LIBVIRT AUTHENTICATION" for documentation and example code.
13987 This function returns 0 on success or -1 on error.
13989 (Added in 1.19.52)
13991 guestfs_set_libvirt_supported_credentials
13993 int
13994 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
13995 char *const *creds);
13996 Call this function before setting an event handler for
13998 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
13999 that the program knows how to process.
14000 The "creds" list must be a non-empty list of strings. Possible strings
14002 are:
14003 "username"
14005 "authname"
14006 "language"
14007 "cnonce"
14008 "passphrase"
14009 "echoprompt"
14010 "noechoprompt"
14011 "realm"
14012 "external"
14013 See libvirt documentation for the meaning of these credential types.
14015 See "LIBVIRT AUTHENTICATION" for documentation and example code.
14017 This function returns 0 on success or -1 on error.
14019 (Added in 1.19.52)
14021 guestfs_set_memsize
14023 int
14024 guestfs_set_memsize (guestfs_h *g,
14025 int memsize);
14026 This sets the memory size in megabytes allocated to the hypervisor.
14028 This only has any effect if called before "guestfs_launch".
14029 You can also change this by setting the environment variable
14031 "LIBGUESTFS_MEMSIZE" before the handle is created.
14032 For more information on the architecture of libguestfs, see guestfs(3).
14034 This function returns 0 on success or -1 on error.
14036 (Added in 1.0.55)
14038 guestfs_set_network
14040 int
14041 guestfs_set_network (guestfs_h *g,
14042 int network);
14043 If "network" is true, then the network is enabled in the libguestfs
14045 appliance. The default is false.
14046 This affects whether commands are able to access the network (see
14048 "RUNNING COMMANDS").
14049 You must call this before calling "guestfs_launch", otherwise it has no
14051 effect.
14052 This function returns 0 on success or -1 on error.
14054 (Added in 1.5.4)
14056 guestfs_set_path
14058 int
14059 guestfs_set_path (guestfs_h *g,
14060 const char *searchpath);
14061 Set the path that libguestfs searches for kernel and initrd.img.
14063 The default is "$libdir/guestfs" unless overridden by setting
14065 "LIBGUESTFS_PATH" environment variable.
14066 Setting "path" to "NULL" restores the default path.
14068 This function returns 0 on success or -1 on error.
14070 (Added in 0.3)
14072 guestfs_set_pgroup
14074 int
14075 guestfs_set_pgroup (guestfs_h *g,
14076 int pgroup);
14077 If "pgroup" is true, child processes are placed into their own process
14079 group.
14080 The practical upshot of this is that signals like "SIGINT" (from users
14082 pressing "^C") won't be received by the child process.
14083 The default for this flag is false, because usually you want "^C" to
14085 kill the subprocess. Guestfish sets this flag to true when used
14086 interactively, so that "^C" can cancel long-running commands gracefully
14087 (see "guestfs_user_cancel").
14088 This function returns 0 on success or -1 on error.
14090 (Added in 1.11.18)
14092 guestfs_set_program
14094 int
14095 guestfs_set_program (guestfs_h *g,
14096 const char *program);
14097 Set the program name. This is an informative string which the main
14099 program may optionally set in the handle.
14100 When the handle is created, the program name in the handle is set to
14102 the basename from "argv[0]". The program name can never be "NULL".
14103 This function returns 0 on success or -1 on error.
14105 (Added in 1.21.29)
14107 guestfs_set_qemu
14109 int
14110 guestfs_set_qemu (guestfs_h *g,
14111 const char *hv);
14112 This function is deprecated. In new code, use the "guestfs_set_hv"
14114 call instead.
14115 Deprecated functions will not be removed from the API, but the fact
14117 that they are deprecated indicates that there are problems with correct
14118 use of these functions.
14119 Set the hypervisor binary (usually qemu) that we will use.
14121 The default is chosen when the library was compiled by the configure
14123 script.
14124 You can also override this by setting the "LIBGUESTFS_HV" environment
14126 variable.
14127 Setting "hv" to "NULL" restores the default qemu binary.
14129 Note that you should call this function as early as possible after
14131 creating the handle. This is because some pre-launch operations depend
14132 on testing qemu features (by running "qemu -help"). If the qemu binary
14133 changes, we don't retest features, and so you might see inconsistent
14134 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14135 all since that picks the qemu binary at the same time as the handle is
14136 created.
14137 This function returns 0 on success or -1 on error.
14139 (Added in 1.0.6)
14141 guestfs_set_recovery_proc
14143 int
14144 guestfs_set_recovery_proc (guestfs_h *g,
14145 int recoveryproc);
14146 If this is called with the parameter "false" then "guestfs_launch" does
14148 not create a recovery process. The purpose of the recovery process is
14149 to stop runaway hypervisor processes in the case where the main program
14150 aborts abruptly.
14151 This only has any effect if called before "guestfs_launch", and the
14153 default is true.
14154 About the only time when you would want to disable this is if the main
14156 process will fork itself into the background ("daemonize" itself). In
14157 this case the recovery process thinks that the main program has
14158 disappeared and so kills the hypervisor, which is not very helpful.
14159 This function returns 0 on success or -1 on error.
14161 (Added in 1.0.77)
14163 guestfs_set_selinux
14165 int
14166 guestfs_set_selinux (guestfs_h *g,
14167 int selinux);
14168 This function is deprecated. In new code, use the
14170 "guestfs_selinux_relabel" call instead.
14171 Deprecated functions will not be removed from the API, but the fact
14173 that they are deprecated indicates that there are problems with correct
14174 use of these functions.
14175 This sets the selinux flag that is passed to the appliance at boot
14177 time. The default is "selinux=0" (disabled).
14178 Note that if SELinux is enabled, it is always in Permissive mode
14180 ("enforcing=0").
14181 For more information on the architecture of libguestfs, see guestfs(3).
14183 This function returns 0 on success or -1 on error.
14185 (Added in 1.0.67)
14187 guestfs_set_smp
14189 int
14190 guestfs_set_smp (guestfs_h *g,
14191 int smp);
14192 Change the number of virtual CPUs assigned to the appliance. The
14194 default is 1. Increasing this may improve performance, though often it
14195 has no effect.
14196 This function must be called before "guestfs_launch".
14198 This function returns 0 on success or -1 on error.
14200 (Added in 1.13.15)
14202 guestfs_set_tmpdir
14204 int
14205 guestfs_set_tmpdir (guestfs_h *g,
14206 const char *tmpdir);
14207 Set the directory used by the handle to store temporary files.
14209 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14211 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14212 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
14213 default.
14214 This function returns 0 on success or -1 on error.
14216 (Added in 1.19.58)
14218 guestfs_set_trace
14220 int
14221 guestfs_set_trace (guestfs_h *g,
14222 int trace);
14223 If the command trace flag is set to 1, then libguestfs calls,
14225 parameters and return values are traced.
14226 If you want to trace C API calls into libguestfs (and other libraries)
14228 then possibly a better way is to use the external ltrace(1) command.
14229 Command traces are disabled unless the environment variable
14231 "LIBGUESTFS_TRACE" is defined and set to 1.
14232 Trace messages are normally sent to "stderr", unless you register a
14234 callback to send them somewhere else (see
14235 "guestfs_set_event_callback").
14236 This function returns 0 on success or -1 on error.
14238 (Added in 1.0.69)
14240 guestfs_set_uuid
14242 int
14243 guestfs_set_uuid (guestfs_h *g,
14244 const char *device,
14245 const char *uuid);
14246 Set the filesystem UUID on "device" to "uuid". If this fails and the
14248 errno is ENOTSUP, means that there is no support for changing the UUID
14249 for the type of the specified filesystem.
14250 Only some filesystem types support setting UUIDs.
14252 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14254 This function returns 0 on success or -1 on error.
14256 (Added in 1.23.10)
14258 guestfs_set_uuid_random
14260 int
14261 guestfs_set_uuid_random (guestfs_h *g,
14262 const char *device);
14263 Set the filesystem UUID on "device" to a random UUID. If this fails
14265 and the errno is ENOTSUP, means that there is no support for changing
14266 the UUID for the type of the specified filesystem.
14267 Only some filesystem types support setting UUIDs.
14269 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14271 This function returns 0 on success or -1 on error.
14273 (Added in 1.29.50)
14275 guestfs_set_verbose
14277 int
14278 guestfs_set_verbose (guestfs_h *g,
14279 int verbose);
14280 If "verbose" is true, this turns on verbose messages.
14282 Verbose messages are disabled unless the environment variable
14284 "LIBGUESTFS_DEBUG" is defined and set to 1.
14285 Verbose messages are normally sent to "stderr", unless you register a
14287 callback to send them somewhere else (see
14288 "guestfs_set_event_callback").
14289 This function returns 0 on success or -1 on error.
14291 (Added in 0.3)
14293 guestfs_setcon
14295 int
14296 guestfs_setcon (guestfs_h *g,
14297 const char *context);
14298 This function is deprecated. In new code, use the
14300 "guestfs_selinux_relabel" call instead.
14301 Deprecated functions will not be removed from the API, but the fact
14303 that they are deprecated indicates that there are problems with correct
14304 use of these functions.
14305 This sets the SELinux security context of the daemon to the string
14307 "context".
14308 See the documentation about SELINUX in guestfs(3).
14310 This function returns 0 on success or -1 on error.
14312 This function depends on the feature "selinux". See also
14314 "guestfs_feature_available".
14315 (Added in 1.0.67)
14317 guestfs_setxattr
14319 int
14320 guestfs_setxattr (guestfs_h *g,
14321 const char *xattr,
14322 const char *val,
14323 int vallen,
14324 const char *path);
14325 This call sets the extended attribute named "xattr" of the file "path"
14327 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14328 data.
14329 See also: "guestfs_lsetxattr", attr(5).
14331 This function returns 0 on success or -1 on error.
14333 This function depends on the feature "linuxxattrs". See also
14335 "guestfs_feature_available".
14336 (Added in 1.0.59)
14338 guestfs_sfdisk
14340 int
14341 guestfs_sfdisk (guestfs_h *g,
14342 const char *device,
14343 int cyls,
14344 int heads,
14345 int sectors,
14346 char *const *lines);
14347 This function is deprecated. In new code, use the "guestfs_part_add"
14349 call instead.
14350 Deprecated functions will not be removed from the API, but the fact
14352 that they are deprecated indicates that there are problems with correct
14353 use of these functions.
14354 This is a direct interface to the sfdisk(8) program for creating
14356 partitions on block devices.
14357 "device" should be a block device, for example /dev/sda.
14359 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14361 sectors on the device, which are passed directly to sfdisk(8) as the
14362 -C, -H and -S parameters. If you pass 0 for any of these, then the
14363 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14364 just pass 0 for these, but for small (floppy-sized) disks, sfdisk(8)
14365 (or rather, the kernel) cannot work out the right geometry and you will
14366 need to tell it.
14367 "lines" is a list of lines that we feed to sfdisk(8). For more
14369 information refer to the sfdisk(8) manpage.
14370 To create a single partition occupying the whole disk, you would pass
14372 "lines" as a single element list, when the single element being the
14373 string "," (comma).
14374 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14376 This function returns 0 on success or -1 on error.
14378 (Added in 0.8)
14380 guestfs_sfdiskM
14382 int
14383 guestfs_sfdiskM (guestfs_h *g,
14384 const char *device,
14385 char *const *lines);
14386 This function is deprecated. In new code, use the "guestfs_part_add"
14388 call instead.
14389 Deprecated functions will not be removed from the API, but the fact
14391 that they are deprecated indicates that there are problems with correct
14392 use of these functions.
14393 This is a simplified interface to the "guestfs_sfdisk" command, where
14395 partition sizes are specified in megabytes only (rounded to the nearest
14396 cylinder) and you don't need to specify the cyls, heads and sectors
14397 parameters which were rarely if ever used anyway.
14398 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14400 "guestfs_part_disk"
14401 This function returns 0 on success or -1 on error.
14403 (Added in 1.0.55)
14405 guestfs_sfdisk_N
14407 int
14408 guestfs_sfdisk_N (guestfs_h *g,
14409 const char *device,
14410 int partnum,
14411 int cyls,
14412 int heads,
14413 int sectors,
14414 const char *line);
14415 This function is deprecated. In new code, use the "guestfs_part_add"
14417 call instead.
14418 Deprecated functions will not be removed from the API, but the fact
14420 that they are deprecated indicates that there are problems with correct
14421 use of these functions.
14422 This runs sfdisk(8) option to modify just the single partition "n"
14424 (note: "n" counts from 1).
14425 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14427 for the cyls/heads/sectors parameters.
14428 See also: "guestfs_part_add"
14430 This function returns 0 on success or -1 on error.
14432 (Added in 1.0.26)
14434 guestfs_sfdisk_disk_geometry
14436 char *
14437 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14438 const char *device);
14439 This displays the disk geometry of "device" read from the partition
14441 table. Especially in the case where the underlying block device has
14442 been resized, this can be different from the kernel’s idea of the
14443 geometry (see "guestfs_sfdisk_kernel_geometry").
14444 The result is in human-readable format, and not designed to be parsed.
14446 This function returns a string, or NULL on error. The caller must free
14448 the returned string after use.
14449 (Added in 1.0.26)
14451 guestfs_sfdisk_kernel_geometry
14453 char *
14454 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14455 const char *device);
14456 This displays the kernel’s idea of the geometry of "device".
14458 The result is in human-readable format, and not designed to be parsed.
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_sfdisk_l
14467 char *
14468 guestfs_sfdisk_l (guestfs_h *g,
14469 const char *device);
14470 This function is deprecated. In new code, use the "guestfs_part_list"
14472 call instead.
14473 Deprecated functions will not be removed from the API, but the fact
14475 that they are deprecated indicates that there are problems with correct
14476 use of these functions.
14477 This displays the partition table on "device", in the human-readable
14479 output of the sfdisk(8) command. It is not intended to be parsed.
14480 See also: "guestfs_part_list"
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.26)
14487 guestfs_sh
14489 char *
14490 guestfs_sh (guestfs_h *g,
14491 const char *command);
14492 This call runs a command from the guest filesystem via the guest’s
14494 /bin/sh.
14495 This is like "guestfs_command", but passes the command to:
14497 /bin/sh -c "command"
14499 Depending on the guest’s shell, this usually results in wildcards being
14501 expanded, shell expressions being interpolated and so on.
14502 All the provisos about "guestfs_command" apply to this call.
14504 This function returns a string, or NULL on error. The caller must free
14506 the returned string after use.
14507 (Added in 1.0.50)
14509 guestfs_sh_lines
14511 char **
14512 guestfs_sh_lines (guestfs_h *g,
14513 const char *command);
14514 This is the same as "guestfs_sh", but splits the result into a list of
14516 lines.
14517 See also: "guestfs_command_lines"
14519 This function returns a NULL-terminated array of strings (like
14521 environ(3)), or NULL if there was an error. The caller must free the
14522 strings and the array after use.
14523 (Added in 1.0.50)
14525 guestfs_shutdown
14527 int
14528 guestfs_shutdown (guestfs_h *g);
14529 This is the opposite of "guestfs_launch". It performs an orderly
14531 shutdown of the backend process(es). If the autosync flag is set
14532 (which is the default) then the disk image is synchronized.
14533 If the subprocess exits with an error then this function will return an
14535 error, which should not be ignored (it may indicate that the disk image
14536 could not be written out properly).
14537 It is safe to call this multiple times. Extra calls are ignored.
14539 This call does not close or free up the handle. You still need to call
14541 "guestfs_close" afterwards.
14542 "guestfs_close" will call this if you don't do it explicitly, but note
14544 that any errors are ignored in that case.
14545 This function returns 0 on success or -1 on error.
14547 (Added in 1.19.16)
14549 guestfs_sleep
14551 int
14552 guestfs_sleep (guestfs_h *g,
14553 int secs);
14554 Sleep for "secs" seconds.
14556 This function returns 0 on success or -1 on error.
14558 (Added in 1.0.41)
14560 guestfs_stat
14562 struct guestfs_stat *
14563 guestfs_stat (guestfs_h *g,
14564 const char *path);
14565 This function is deprecated. In new code, use the "guestfs_statns"
14567 call instead.
14568 Deprecated functions will not be removed from the API, but the fact
14570 that they are deprecated indicates that there are problems with correct
14571 use of these functions.
14572 Returns file information for the given "path".
14574 This is the same as the stat(2) system call.
14576 This function returns a "struct guestfs_stat *", or NULL if there was
14578 an error. The caller must call "guestfs_free_stat" after use.
14579 (Added in 1.9.2)
14581 guestfs_statns
14583 struct guestfs_statns *
14584 guestfs_statns (guestfs_h *g,
14585 const char *path);
14586 Returns file information for the given "path".
14588 This is the same as the stat(2) system call.
14590 This function returns a "struct guestfs_statns *", or NULL if there was
14592 an error. The caller must call "guestfs_free_statns" after use.
14593 (Added in 1.27.53)
14595 guestfs_statvfs
14597 struct guestfs_statvfs *
14598 guestfs_statvfs (guestfs_h *g,
14599 const char *path);
14600 Returns file system statistics for any mounted file system. "path"
14602 should be a file or directory in the mounted file system (typically it
14603 is the mount point itself, but it doesn't need to be).
14604 This is the same as the statvfs(2) system call.
14606 This function returns a "struct guestfs_statvfs *", or NULL if there
14608 was an error. The caller must call "guestfs_free_statvfs" after use.
14609 (Added in 1.9.2)
14611 guestfs_strings
14613 char **
14614 guestfs_strings (guestfs_h *g,
14615 const char *path);
14616 This runs the strings(1) command on a file and returns the list of
14618 printable strings found.
14619 The "strings" command has, in the past, had problems with parsing
14621 untrusted files. These are mitigated in the current version of
14622 libguestfs, but see "CVE-2014-8484".
14623 This function returns a NULL-terminated array of strings (like
14625 environ(3)), or NULL if there was an error. The caller must free the
14626 strings and the array after use.
14627 Because of the message protocol, there is a transfer limit of somewhere
14629 between 2MB and 4MB. See "PROTOCOL LIMITS".
14630 (Added in 1.0.22)
14632 guestfs_strings_e
14634 char **
14635 guestfs_strings_e (guestfs_h *g,
14636 const char *encoding,
14637 const char *path);
14638 This is like the "guestfs_strings" command, but allows you to specify
14640 the encoding of strings that are looked for in the source file "path".
14641 Allowed encodings are:
14643 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14645 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14646 S Single 8-bit-byte characters.
14648 b 16-bit big endian strings such as those encoded in UTF-16BE or
14650 UCS-2BE.
14651 l (lower case letter L)
14653 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14654 for examining binaries in Windows guests.
14655 B 32-bit big endian such as UCS-4BE.
14657 L 32-bit little endian such as UCS-4LE.
14659 The returned strings are transcoded to UTF-8.
14661 The "strings" command has, in the past, had problems with parsing
14663 untrusted files. These are mitigated in the current version of
14664 libguestfs, but see "CVE-2014-8484".
14665 This function returns a NULL-terminated array of strings (like
14667 environ(3)), or NULL if there was an error. The caller must free the
14668 strings and the array after use.
14669 Because of the message protocol, there is a transfer limit of somewhere
14671 between 2MB and 4MB. See "PROTOCOL LIMITS".
14672 (Added in 1.0.22)
14674 guestfs_swapoff_device
14676 int
14677 guestfs_swapoff_device (guestfs_h *g,
14678 const char *device);
14679 This command disables the libguestfs appliance swap device or partition
14681 named "device". See "guestfs_swapon_device".
14682 This function returns 0 on success or -1 on error.
14684 (Added in 1.0.66)
14686 guestfs_swapoff_file
14688 int
14689 guestfs_swapoff_file (guestfs_h *g,
14690 const char *file);
14691 This command disables the libguestfs appliance swap on file.
14693 This function returns 0 on success or -1 on error.
14695 (Added in 1.0.66)
14697 guestfs_swapoff_label
14699 int
14700 guestfs_swapoff_label (guestfs_h *g,
14701 const char *label);
14702 This command disables the libguestfs appliance swap on labeled swap
14704 partition.
14705 This function returns 0 on success or -1 on error.
14707 (Added in 1.0.66)
14709 guestfs_swapoff_uuid
14711 int
14712 guestfs_swapoff_uuid (guestfs_h *g,
14713 const char *uuid);
14714 This command disables the libguestfs appliance swap partition with the
14716 given UUID.
14717 This function returns 0 on success or -1 on error.
14719 This function depends on the feature "linuxfsuuid". See also
14721 "guestfs_feature_available".
14722 (Added in 1.0.66)
14724 guestfs_swapon_device
14726 int
14727 guestfs_swapon_device (guestfs_h *g,
14728 const char *device);
14729 This command enables the libguestfs appliance to use the swap device or
14731 partition named "device". The increased memory is made available for
14732 all commands, for example those run using "guestfs_command" or
14733 "guestfs_sh".
14734 Note that you should not swap to existing guest swap partitions unless
14736 you know what you are doing. They may contain hibernation information,
14737 or other information that the guest doesn't want you to trash. You
14738 also risk leaking information about the host to the guest this way.
14739 Instead, attach a new host device to the guest and swap on that.
14740 This function returns 0 on success or -1 on error.
14742 (Added in 1.0.66)
14744 guestfs_swapon_file
14746 int
14747 guestfs_swapon_file (guestfs_h *g,
14748 const char *file);
14749 This command enables swap to a file. See "guestfs_swapon_device" for
14751 other notes.
14752 This function returns 0 on success or -1 on error.
14754 (Added in 1.0.66)
14756 guestfs_swapon_label
14758 int
14759 guestfs_swapon_label (guestfs_h *g,
14760 const char *label);
14761 This command enables swap to a labeled swap partition. See
14763 "guestfs_swapon_device" for other notes.
14764 This function returns 0 on success or -1 on error.
14766 (Added in 1.0.66)
14768 guestfs_swapon_uuid
14770 int
14771 guestfs_swapon_uuid (guestfs_h *g,
14772 const char *uuid);
14773 This command enables swap to a swap partition with the given UUID. See
14775 "guestfs_swapon_device" for other notes.
14776 This function returns 0 on success or -1 on error.
14778 This function depends on the feature "linuxfsuuid". See also
14780 "guestfs_feature_available".
14781 (Added in 1.0.66)
14783 guestfs_sync
14785 int
14786 guestfs_sync (guestfs_h *g);
14787 This syncs the disk, so that any writes are flushed through to the
14789 underlying disk image.
14790 You should always call this if you have modified a disk image, before
14792 closing the handle.
14793 This function returns 0 on success or -1 on error.
14795 (Added in 0.3)
14797 guestfs_syslinux
14799 int
14800 guestfs_syslinux (guestfs_h *g,
14801 const char *device,
14802 ...);
14803 You may supply a list of optional arguments to this call. Use zero or
14805 more of the following pairs of parameters, and terminate the list with
14806 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14807 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14809 Install the SYSLINUX bootloader on "device".
14811 The device parameter must be either a whole disk formatted as a FAT
14813 filesystem, or a partition formatted as a FAT filesystem. In the
14814 latter case, the partition should be marked as "active"
14815 ("guestfs_part_set_bootable") and a Master Boot Record must be
14816 installed (eg. using "guestfs_pwrite_device") on the first sector of
14817 the whole disk. The SYSLINUX package comes with some suitable Master
14818 Boot Records. See the syslinux(1) man page for further information.
14819 The optional arguments are:
14821 directory
14823 Install SYSLINUX in the named subdirectory, instead of in the root
14824 directory of the FAT filesystem.
14825 Additional configuration can be supplied to SYSLINUX by placing a file
14827 called syslinux.cfg on the FAT filesystem, either in the root
14828 directory, or under directory if that optional argument is being used.
14829 For further information about the contents of this file, see
14830 syslinux(1).
14831 See also "guestfs_extlinux".
14833 This function returns 0 on success or -1 on error.
14835 This function depends on the feature "syslinux". See also
14837 "guestfs_feature_available".
14838 (Added in 1.21.27)
14840 guestfs_syslinux_va
14842 int
14843 guestfs_syslinux_va (guestfs_h *g,
14844 const char *device,
14845 va_list args);
14846 This is the "va_list variant" of "guestfs_syslinux".
14848 See "CALLS WITH OPTIONAL ARGUMENTS".
14850 guestfs_syslinux_argv
14852 int
14853 guestfs_syslinux_argv (guestfs_h *g,
14854 const char *device,
14855 const struct guestfs_syslinux_argv *optargs);
14856 This is the "argv variant" of "guestfs_syslinux".
14858 See "CALLS WITH OPTIONAL ARGUMENTS".
14860 guestfs_tail
14862 char **
14863 guestfs_tail (guestfs_h *g,
14864 const char *path);
14865 This command returns up to the last 10 lines of a file as a list of
14867 strings.
14868 This function returns a NULL-terminated array of strings (like
14870 environ(3)), or NULL if there was an error. The caller must free the
14871 strings and the array after use.
14872 Because of the message protocol, there is a transfer limit of somewhere
14874 between 2MB and 4MB. See "PROTOCOL LIMITS".
14875 (Added in 1.0.54)
14877 guestfs_tail_n
14879 char **
14880 guestfs_tail_n (guestfs_h *g,
14881 int nrlines,
14882 const char *path);
14883 If the parameter "nrlines" is a positive number, this returns the last
14885 "nrlines" lines of the file "path".
14886 If the parameter "nrlines" is a negative number, this returns lines
14888 from the file "path", starting with the "-nrlines"'th line.
14889 If the parameter "nrlines" is zero, this returns an empty list.
14891 This function returns a NULL-terminated array of strings (like
14893 environ(3)), or NULL if there was an error. The caller must free the
14894 strings and the array after use.
14895 Because of the message protocol, there is a transfer limit of somewhere
14897 between 2MB and 4MB. See "PROTOCOL LIMITS".
14898 (Added in 1.0.54)
14900 guestfs_tar_in
14902 int
14903 guestfs_tar_in (guestfs_h *g,
14904 const char *tarfile,
14905 const char *directory);
14906 This function is provided for backwards compatibility with earlier
14908 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
14909 optional arguments.
14910 (Added in 1.0.3)
14912 guestfs_tar_in_opts
14914 int
14915 guestfs_tar_in_opts (guestfs_h *g,
14916 const char *tarfile,
14917 const char *directory,
14918 ...);
14919 You may supply a list of optional arguments to this call. Use zero or
14921 more of the following pairs of parameters, and terminate the list with
14922 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14923 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
14925 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
14926 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
14927 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
14928 This command uploads and unpacks local file "tarfile" into directory.
14930 The optional "compress" flag controls compression. If not given, then
14932 the input should be an uncompressed tar file. Otherwise one of the
14933 following strings may be given to select the compression type of the
14934 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
14935 all builds of libguestfs will support all of these compression types).
14936 The other optional arguments are:
14938 "xattrs"
14940 If set to true, extended attributes are restored from the tar file.
14941 "selinux"
14943 If set to true, SELinux contexts are restored from the tar file.
14944 "acls"
14946 If set to true, POSIX ACLs are restored from the tar file.
14947 This function returns 0 on success or -1 on error.
14949 (Added in 1.0.3)
14951 guestfs_tar_in_opts_va
14953 int
14954 guestfs_tar_in_opts_va (guestfs_h *g,
14955 const char *tarfile,
14956 const char *directory,
14957 va_list args);
14958 This is the "va_list variant" of "guestfs_tar_in_opts".
14960 See "CALLS WITH OPTIONAL ARGUMENTS".
14962 guestfs_tar_in_opts_argv
14964 int
14965 guestfs_tar_in_opts_argv (guestfs_h *g,
14966 const char *tarfile,
14967 const char *directory,
14968 const struct guestfs_tar_in_opts_argv *optargs);
14969 This is the "argv variant" of "guestfs_tar_in_opts".
14971 See "CALLS WITH OPTIONAL ARGUMENTS".
14973 guestfs_tar_out
14975 int
14976 guestfs_tar_out (guestfs_h *g,
14977 const char *directory,
14978 const char *tarfile);
14979 This function is provided for backwards compatibility with earlier
14981 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
14982 optional arguments.
14983 (Added in 1.0.3)
14985 guestfs_tar_out_opts
14987 int
14988 guestfs_tar_out_opts (guestfs_h *g,
14989 const char *directory,
14990 const char *tarfile,
14991 ...);
14992 You may supply a list of optional arguments to this call. Use zero or
14994 more of the following pairs of parameters, and terminate the list with
14995 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14996 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
14998 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
14999 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
15000 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
15001 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
15002 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
15003 This command packs the contents of directory and downloads it to local
15005 file "tarfile".
15006 The optional "compress" flag controls compression. If not given, then
15008 the output will be an uncompressed tar file. Otherwise one of the
15009 following strings may be given to select the compression type of the
15010 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
15011 all builds of libguestfs will support all of these compression types).
15012 The other optional arguments are:
15014 "excludes"
15016 A list of wildcards. Files are excluded if they match any of the
15017 wildcards.
15018 "numericowner"
15020 If set to true, the output tar file will contain UID/GID numbers
15021 instead of user/group names.
15022 "xattrs"
15024 If set to true, extended attributes are saved in the output tar.
15025 "selinux"
15027 If set to true, SELinux contexts are saved in the output tar.
15028 "acls"
15030 If set to true, POSIX ACLs are saved in the output tar.
15031 This function returns 0 on success or -1 on error.
15033 (Added in 1.0.3)
15035 guestfs_tar_out_opts_va
15037 int
15038 guestfs_tar_out_opts_va (guestfs_h *g,
15039 const char *directory,
15040 const char *tarfile,
15041 va_list args);
15042 This is the "va_list variant" of "guestfs_tar_out_opts".
15044 See "CALLS WITH OPTIONAL ARGUMENTS".
15046 guestfs_tar_out_opts_argv
15048 int
15049 guestfs_tar_out_opts_argv (guestfs_h *g,
15050 const char *directory,
15051 const char *tarfile,
15052 const struct guestfs_tar_out_opts_argv *optargs);
15053 This is the "argv variant" of "guestfs_tar_out_opts".
15055 See "CALLS WITH OPTIONAL ARGUMENTS".
15057 guestfs_tgz_in
15059 int
15060 guestfs_tgz_in (guestfs_h *g,
15061 const char *tarball,
15062 const char *directory);
15063 This function is deprecated. In new code, use the "guestfs_tar_in"
15065 call instead.
15066 Deprecated functions will not be removed from the API, but the fact
15068 that they are deprecated indicates that there are problems with correct
15069 use of these functions.
15070 This command uploads and unpacks local file "tarball" (a gzip
15072 compressed tar file) into directory.
15073 This function returns 0 on success or -1 on error.
15075 (Added in 1.0.3)
15077 guestfs_tgz_out
15079 int
15080 guestfs_tgz_out (guestfs_h *g,
15081 const char *directory,
15082 const char *tarball);
15083 This function is deprecated. In new code, use the "guestfs_tar_out"
15085 call instead.
15086 Deprecated functions will not be removed from the API, but the fact
15088 that they are deprecated indicates that there are problems with correct
15089 use of these functions.
15090 This command packs the contents of directory and downloads it to local
15092 file "tarball".
15093 This function returns 0 on success or -1 on error.
15095 (Added in 1.0.3)
15097 guestfs_touch
15099 int
15100 guestfs_touch (guestfs_h *g,
15101 const char *path);
15102 Touch acts like the touch(1) command. It can be used to update the
15104 timestamps on a file, or, if the file does not exist, to create a new
15105 zero-length file.
15106 This command only works on regular files, and will fail on other file
15108 types such as directories, symbolic links, block special etc.
15109 This function returns 0 on success or -1 on error.
15111 (Added in 0.3)
15113 guestfs_truncate
15115 int
15116 guestfs_truncate (guestfs_h *g,
15117 const char *path);
15118 This command truncates "path" to a zero-length file. The file must
15120 exist already.
15121 This function returns 0 on success or -1 on error.
15123 (Added in 1.0.77)
15125 guestfs_truncate_size
15127 int
15128 guestfs_truncate_size (guestfs_h *g,
15129 const char *path,
15130 int64_t size);
15131 This command truncates "path" to size "size" bytes. The file must
15133 exist already.
15134 If the current file size is less than "size" then the file is extended
15136 to the required size with zero bytes. This creates a sparse file (ie.
15137 disk blocks are not allocated for the file until you write to it). To
15138 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15139 This function returns 0 on success or -1 on error.
15141 (Added in 1.0.77)
15143 guestfs_tune2fs
15145 int
15146 guestfs_tune2fs (guestfs_h *g,
15147 const char *device,
15148 ...);
15149 You may supply a list of optional arguments to this call. Use zero or
15151 more of the following pairs of parameters, and terminate the list with
15152 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15153 GUESTFS_TUNE2FS_FORCE, int force,
15155 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15156 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15157 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15158 GUESTFS_TUNE2FS_GROUP, int64_t group,
15159 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15160 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15161 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15162 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15163 GUESTFS_TUNE2FS_USER, int64_t user,
15164 This call allows you to adjust various filesystem parameters of an
15166 ext2/ext3/ext4 filesystem called "device".
15167 The optional parameters are:
15169 "force"
15171 Force tune2fs to complete the operation even in the face of errors.
15172 This is the same as the tune2fs(8) "-f" option.
15173 "maxmountcount"
15175 Set the number of mounts after which the filesystem is checked by
15176 e2fsck(8). If this is 0 then the number of mounts is disregarded.
15177 This is the same as the tune2fs(8) "-c" option.
15178 "mountcount"
15180 Set the number of times the filesystem has been mounted. This is
15181 the same as the tune2fs(8) "-C" option.
15182 "errorbehavior"
15184 Change the behavior of the kernel code when errors are detected.
15185 Possible values currently are: "continue", "remount-ro", "panic".
15186 In practice these options don't really make any difference,
15187 particularly for write errors.
15188 This is the same as the tune2fs(8) "-e" option.
15190 "group"
15192 Set the group which can use reserved filesystem blocks. This is
15193 the same as the tune2fs(8) "-g" option except that it can only be
15194 specified as a number.
15195 "intervalbetweenchecks"
15197 Adjust the maximal time between two filesystem checks (in seconds).
15198 If the option is passed as 0 then time-dependent checking is
15199 disabled.
15200 This is the same as the tune2fs(8) "-i" option.
15202 "reservedblockspercentage"
15204 Set the percentage of the filesystem which may only be allocated by
15205 privileged processes. This is the same as the tune2fs(8) "-m"
15206 option.
15207 "lastmounteddirectory"
15209 Set the last mounted directory. This is the same as the tune2fs(8)
15210 "-M" option.
15211 "reservedblockscount" Set the number of reserved filesystem blocks.
15213 This is the same as the tune2fs(8) "-r" option.
15214 "user"
15215 Set the user who can use the reserved filesystem blocks. This is
15216 the same as the tune2fs(8) "-u" option except that it can only be
15217 specified as a number.
15218 To get the current values of filesystem parameters, see
15220 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
15221 tune2fs(8) man page.
15222 This function returns 0 on success or -1 on error.
15224 (Added in 1.15.4)
15226 guestfs_tune2fs_va
15228 int
15229 guestfs_tune2fs_va (guestfs_h *g,
15230 const char *device,
15231 va_list args);
15232 This is the "va_list variant" of "guestfs_tune2fs".
15234 See "CALLS WITH OPTIONAL ARGUMENTS".
15236 guestfs_tune2fs_argv
15238 int
15239 guestfs_tune2fs_argv (guestfs_h *g,
15240 const char *device,
15241 const struct guestfs_tune2fs_argv *optargs);
15242 This is the "argv variant" of "guestfs_tune2fs".
15244 See "CALLS WITH OPTIONAL ARGUMENTS".
15246 guestfs_tune2fs_l
15248 char **
15249 guestfs_tune2fs_l (guestfs_h *g,
15250 const char *device);
15251 This returns the contents of the ext2, ext3 or ext4 filesystem
15253 superblock on "device".
15254 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
15256 for more details. The list of fields returned isn't clearly defined,
15257 and depends on both the version of "tune2fs" that libguestfs was built
15258 against, and the filesystem itself.
15259 This function returns a NULL-terminated array of strings, or NULL if
15261 there was an error. The array of strings will always have length
15262 "2n+1", where "n" keys and values alternate, followed by the trailing
15263 NULL entry. The caller must free the strings and the array after use.
15264 (Added in 1.9.2)
15266 guestfs_txz_in
15268 int
15269 guestfs_txz_in (guestfs_h *g,
15270 const char *tarball,
15271 const char *directory);
15272 This function is deprecated. In new code, use the "guestfs_tar_in"
15274 call instead.
15275 Deprecated functions will not be removed from the API, but the fact
15277 that they are deprecated indicates that there are problems with correct
15278 use of these functions.
15279 This command uploads and unpacks local file "tarball" (an xz compressed
15281 tar file) into directory.
15282 This function returns 0 on success or -1 on error.
15284 This function depends on the feature "xz". See also
15286 "guestfs_feature_available".
15287 (Added in 1.3.2)
15289 guestfs_txz_out
15291 int
15292 guestfs_txz_out (guestfs_h *g,
15293 const char *directory,
15294 const char *tarball);
15295 This function is deprecated. In new code, use the "guestfs_tar_out"
15297 call instead.
15298 Deprecated functions will not be removed from the API, but the fact
15300 that they are deprecated indicates that there are problems with correct
15301 use of these functions.
15302 This command packs the contents of directory and downloads it to local
15304 file "tarball" (as an xz compressed tar archive).
15305 This function returns 0 on success or -1 on error.
15307 This function depends on the feature "xz". See also
15309 "guestfs_feature_available".
15310 (Added in 1.3.2)
15312 guestfs_umask
15314 int
15315 guestfs_umask (guestfs_h *g,
15316 int mask);
15317 This function sets the mask used for creating new files and device
15319 nodes to "mask & 0777".
15320 Typical umask values would be 022 which creates new files with
15322 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15323 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15324 The default umask is 022. This is important because it means that
15326 directories and device nodes will be created with 0644 or 0755 mode
15327 even if you specify 0777.
15328 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15330 "guestfs_mkdir".
15331 This call returns the previous umask.
15333 On error this function returns -1.
15335 (Added in 1.0.55)
15337 guestfs_umount
15339 int
15340 guestfs_umount (guestfs_h *g,
15341 const char *pathordevice);
15342 This function is provided for backwards compatibility with earlier
15344 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15345 optional arguments.
15346 (Added in 0.8)
15348 guestfs_umount_opts
15350 int
15351 guestfs_umount_opts (guestfs_h *g,
15352 const char *pathordevice,
15353 ...);
15354 You may supply a list of optional arguments to this call. Use zero or
15356 more of the following pairs of parameters, and terminate the list with
15357 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15358 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15360 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15361 This unmounts the given filesystem. The filesystem may be specified
15363 either by its mountpoint (path) or the device which contains the
15364 filesystem.
15365 This function returns 0 on success or -1 on error.
15367 (Added in 0.8)
15369 guestfs_umount_opts_va
15371 int
15372 guestfs_umount_opts_va (guestfs_h *g,
15373 const char *pathordevice,
15374 va_list args);
15375 This is the "va_list variant" of "guestfs_umount_opts".
15377 See "CALLS WITH OPTIONAL ARGUMENTS".
15379 guestfs_umount_opts_argv
15381 int
15382 guestfs_umount_opts_argv (guestfs_h *g,
15383 const char *pathordevice,
15384 const struct guestfs_umount_opts_argv *optargs);
15385 This is the "argv variant" of "guestfs_umount_opts".
15387 See "CALLS WITH OPTIONAL ARGUMENTS".
15389 guestfs_umount_all
15391 int
15392 guestfs_umount_all (guestfs_h *g);
15393 This unmounts all mounted filesystems.
15395 Some internal mounts are not unmounted by this call.
15397 This function returns 0 on success or -1 on error.
15399 (Added in 0.8)
15401 guestfs_umount_local
15403 int
15404 guestfs_umount_local (guestfs_h *g,
15405 ...);
15406 You may supply a list of optional arguments to this call. Use zero or
15408 more of the following pairs of parameters, and terminate the list with
15409 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15410 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15412 If libguestfs is exporting the filesystem on a local mountpoint, then
15414 this unmounts it.
15415 See "MOUNT LOCAL" for full documentation.
15417 This function returns 0 on success or -1 on error.
15419 (Added in 1.17.22)
15421 guestfs_umount_local_va
15423 int
15424 guestfs_umount_local_va (guestfs_h *g,
15425 va_list args);
15426 This is the "va_list variant" of "guestfs_umount_local".
15428 See "CALLS WITH OPTIONAL ARGUMENTS".
15430 guestfs_umount_local_argv
15432 int
15433 guestfs_umount_local_argv (guestfs_h *g,
15434 const struct guestfs_umount_local_argv *optargs);
15435 This is the "argv variant" of "guestfs_umount_local".
15437 See "CALLS WITH OPTIONAL ARGUMENTS".
15439 guestfs_upload
15441 int
15442 guestfs_upload (guestfs_h *g,
15443 const char *filename,
15444 const char *remotefilename);
15445 Upload local file filename to remotefilename on the filesystem.
15447 filename can also be a named pipe.
15449 See also "guestfs_download".
15451 This function returns 0 on success or -1 on error.
15453 This long-running command can generate progress notification messages
15455 so that the caller can display a progress bar or indicator. To receive
15456 these messages, the caller must register a progress event callback.
15457 See "GUESTFS_EVENT_PROGRESS".
15458 (Added in 1.0.2)
15460 guestfs_upload_offset
15462 int
15463 guestfs_upload_offset (guestfs_h *g,
15464 const char *filename,
15465 const char *remotefilename,
15466 int64_t offset);
15467 Upload local file filename to remotefilename on the filesystem.
15469 remotefilename is overwritten starting at the byte "offset" specified.
15471 The intention is to overwrite parts of existing files or devices,
15472 although if a non-existent file is specified then it is created with a
15473 "hole" before "offset". The size of the data written is implicit in
15474 the size of the source filename.
15475 Note that there is no limit on the amount of data that can be uploaded
15477 with this call, unlike with "guestfs_pwrite", and this call always
15478 writes the full amount unless an error occurs.
15479 See also "guestfs_upload", "guestfs_pwrite".
15481 This function returns 0 on success or -1 on error.
15483 This long-running command can generate progress notification messages
15485 so that the caller can display a progress bar or indicator. To receive
15486 these messages, the caller must register a progress event callback.
15487 See "GUESTFS_EVENT_PROGRESS".
15488 (Added in 1.5.17)
15490 guestfs_user_cancel
15492 int
15493 guestfs_user_cancel (guestfs_h *g);
15494 This function cancels the current upload or download operation.
15496 Unlike most other libguestfs calls, this function is signal safe and
15498 thread safe. You can call it from a signal handler or from another
15499 thread, without needing to do any locking.
15500 The transfer that was in progress (if there is one) will stop shortly
15502 afterwards, and will return an error. The errno (see
15503 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15504 find out if the operation was cancelled or failed because of another
15505 error.
15506 No cleanup is performed: for example, if a file was being uploaded then
15508 after cancellation there may be a partially uploaded file. It is the
15509 caller’s responsibility to clean up if necessary.
15510 There are two common places that you might call "guestfs_user_cancel":
15512 In an interactive text-based program, you might call it from a "SIGINT"
15514 signal handler so that pressing "^C" cancels the current operation.
15515 (You also need to call "guestfs_set_pgroup" so that child processes
15516 don't receive the "^C" signal).
15517 In a graphical program, when the main thread is displaying a progress
15519 bar with a cancel button, wire up the cancel button to call this
15520 function.
15521 This function returns 0 on success or -1 on error.
15523 (Added in 1.11.18)
15525 guestfs_utimens
15527 int
15528 guestfs_utimens (guestfs_h *g,
15529 const char *path,
15530 int64_t atsecs,
15531 int64_t atnsecs,
15532 int64_t mtsecs,
15533 int64_t mtnsecs);
15534 This command sets the timestamps of a file with nanosecond precision.
15536 "atsecs", "atnsecs" are the last access time (atime) in secs and
15538 nanoseconds from the epoch.
15539 "mtsecs", "mtnsecs" are the last modification time (mtime) in secs and
15541 nanoseconds from the epoch.
15542 If the *nsecs field contains the special value "-1" then the
15544 corresponding timestamp is set to the current time. (The *secs field
15545 is ignored in this case).
15546 If the *nsecs field contains the special value "-2" then the
15548 corresponding timestamp is left unchanged. (The *secs field is ignored
15549 in this case).
15550 This function returns 0 on success or -1 on error.
15552 (Added in 1.0.77)
15554 guestfs_utsname
15556 struct guestfs_utsname *
15557 guestfs_utsname (guestfs_h *g);
15558 This returns the kernel version of the appliance, where this is
15560 available. This information is only useful for debugging. Nothing in
15561 the returned structure is defined by the API.
15562 This function returns a "struct guestfs_utsname *", or NULL if there
15564 was an error. The caller must call "guestfs_free_utsname" after use.
15565 (Added in 1.19.27)
15567 guestfs_version
15569 struct guestfs_version *
15570 guestfs_version (guestfs_h *g);
15571 Return the libguestfs version number that the program is linked
15573 against.
15574 Note that because of dynamic linking this is not necessarily the
15576 version of libguestfs that you compiled against. You can compile the
15577 program, and then at runtime dynamically link against a completely
15578 different libguestfs.so library.
15579 This call was added in version 1.0.58. In previous versions of
15581 libguestfs there was no way to get the version number. From C code you
15582 can use dynamic linker functions to find out if this symbol exists (if
15583 it doesn't, then it’s an earlier version).
15584 The call returns a structure with four elements. The first three
15586 ("major", "minor" and "release") are numbers and correspond to the
15587 usual version triplet. The fourth element ("extra") is a string and is
15588 normally empty, but may be used for distro-specific information.
15589 To construct the original version string:
15591 "$major.$minor.$release$extra"
15592 See also: "LIBGUESTFS VERSION NUMBERS".
15594 Note: Don't use this call to test for availability of features. In
15596 enterprise distributions we backport features from later versions into
15597 earlier versions, making this an unreliable way to test for features.
15598 Use "guestfs_available" or "guestfs_feature_available" instead.
15599 This function returns a "struct guestfs_version *", or NULL if there
15601 was an error. The caller must call "guestfs_free_version" after use.
15602 (Added in 1.0.58)
15604 guestfs_vfs_label
15606 char *
15607 guestfs_vfs_label (guestfs_h *g,
15608 const char *mountable);
15609 This returns the label of the filesystem on "mountable".
15611 If the filesystem is unlabeled, this returns the empty string.
15613 To find a filesystem from the label, use "guestfs_findfs_label".
15615 This function returns a string, or NULL on error. The caller must free
15617 the returned string after use.
15618 (Added in 1.3.18)
15620 guestfs_vfs_minimum_size
15622 int64_t
15623 guestfs_vfs_minimum_size (guestfs_h *g,
15624 const char *mountable);
15625 Get the minimum size of filesystem in bytes. This is the minimum
15627 possible size for filesystem shrinking.
15628 If getting minimum size of specified filesystem is not supported, this
15630 will fail and set errno as ENOTSUP.
15631 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15633 On error this function returns -1.
15635 (Added in 1.31.18)
15637 guestfs_vfs_type
15639 char *
15640 guestfs_vfs_type (guestfs_h *g,
15641 const char *mountable);
15642 This command gets the filesystem type corresponding to the filesystem
15644 on "mountable".
15645 For most filesystems, the result is the name of the Linux VFS module
15647 which would be used to mount this filesystem if you mounted it without
15648 specifying the filesystem type. For example a string such as "ext3" or
15649 "ntfs".
15650 This function returns a string, or NULL on error. The caller must free
15652 the returned string after use.
15653 (Added in 1.0.75)
15655 guestfs_vfs_uuid
15657 char *
15658 guestfs_vfs_uuid (guestfs_h *g,
15659 const char *mountable);
15660 This returns the filesystem UUID of the filesystem on "mountable".
15662 If the filesystem does not have a UUID, this returns the empty string.
15664 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15666 This function returns a string, or NULL on error. The caller must free
15668 the returned string after use.
15669 (Added in 1.3.18)
15671 guestfs_vg_activate
15673 int
15674 guestfs_vg_activate (guestfs_h *g,
15675 int activate,
15676 char *const *volgroups);
15677 This command activates or (if "activate" is false) deactivates all
15679 logical volumes in the listed volume groups "volgroups".
15680 This command is the same as running "vgchange -a y|n volgroups..."
15682 Note that if "volgroups" is an empty list then all volume groups are
15684 activated or deactivated.
15685 This function returns 0 on success or -1 on error.
15687 This function depends on the feature "lvm2". See also
15689 "guestfs_feature_available".
15690 (Added in 1.0.26)
15692 guestfs_vg_activate_all
15694 int
15695 guestfs_vg_activate_all (guestfs_h *g,
15696 int activate);
15697 This command activates or (if "activate" is false) deactivates all
15699 logical volumes in all volume groups.
15700 This command is the same as running "vgchange -a y|n"
15702 This function returns 0 on success or -1 on error.
15704 This function depends on the feature "lvm2". See also
15706 "guestfs_feature_available".
15707 (Added in 1.0.26)
15709 guestfs_vgchange_uuid
15711 int
15712 guestfs_vgchange_uuid (guestfs_h *g,
15713 const char *vg);
15714 Generate a new random UUID for the volume group "vg".
15716 This function returns 0 on success or -1 on error.
15718 This function depends on the feature "lvm2". See also
15720 "guestfs_feature_available".
15721 (Added in 1.19.26)
15723 guestfs_vgchange_uuid_all
15725 int
15726 guestfs_vgchange_uuid_all (guestfs_h *g);
15727 Generate new random UUIDs for all volume groups.
15729 This function returns 0 on success or -1 on error.
15731 This function depends on the feature "lvm2". See also
15733 "guestfs_feature_available".
15734 (Added in 1.19.26)
15736 guestfs_vgcreate
15738 int
15739 guestfs_vgcreate (guestfs_h *g,
15740 const char *volgroup,
15741 char *const *physvols);
15742 This creates an LVM volume group called "volgroup" from the non-empty
15744 list of physical volumes "physvols".
15745 This function returns 0 on success or -1 on error.
15747 This function depends on the feature "lvm2". See also
15749 "guestfs_feature_available".
15750 (Added in 0.8)
15752 guestfs_vglvuuids
15754 char **
15755 guestfs_vglvuuids (guestfs_h *g,
15756 const char *vgname);
15757 Given a VG called "vgname", this returns the UUIDs of all the logical
15759 volumes created in this volume group.
15760 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15762 associate logical volumes and volume groups.
15763 See also "guestfs_vgpvuuids".
15765 This function returns a NULL-terminated array of strings (like
15767 environ(3)), or NULL if there was an error. The caller must free the
15768 strings and the array after use.
15769 (Added in 1.0.87)
15771 guestfs_vgmeta
15773 char *
15774 guestfs_vgmeta (guestfs_h *g,
15775 const char *vgname,
15776 size_t *size_r);
15777 "vgname" is an LVM volume group. This command examines the volume
15779 group and returns its metadata.
15780 Note that the metadata is an internal structure used by LVM, subject to
15782 change at any time, and is provided for information only.
15783 This function returns a buffer, or NULL on error. The size of the
15785 returned buffer is written to *size_r. The caller must free the
15786 returned buffer after use.
15787 This function depends on the feature "lvm2". See also
15789 "guestfs_feature_available".
15790 (Added in 1.17.20)
15792 guestfs_vgpvuuids
15794 char **
15795 guestfs_vgpvuuids (guestfs_h *g,
15796 const char *vgname);
15797 Given a VG called "vgname", this returns the UUIDs of all the physical
15799 volumes that this volume group resides on.
15800 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15802 associate physical volumes and volume groups.
15803 See also "guestfs_vglvuuids".
15805 This function returns a NULL-terminated array of strings (like
15807 environ(3)), or NULL if there was an error. The caller must free the
15808 strings and the array after use.
15809 (Added in 1.0.87)
15811 guestfs_vgremove
15813 int
15814 guestfs_vgremove (guestfs_h *g,
15815 const char *vgname);
15816 Remove an LVM volume group "vgname", (for example "VG").
15818 This also forcibly removes all logical volumes in the volume group (if
15820 any).
15821 This function returns 0 on success or -1 on error.
15823 This function depends on the feature "lvm2". See also
15825 "guestfs_feature_available".
15826 (Added in 1.0.13)
15828 guestfs_vgrename
15830 int
15831 guestfs_vgrename (guestfs_h *g,
15832 const char *volgroup,
15833 const char *newvolgroup);
15834 Rename a volume group "volgroup" with the new name "newvolgroup".
15836 This function returns 0 on success or -1 on error.
15838 (Added in 1.0.83)
15840 guestfs_vgs
15842 char **
15843 guestfs_vgs (guestfs_h *g);
15844 List all the volumes groups detected. This is the equivalent of the
15846 vgs(8) command.
15847 This returns a list of just the volume group names that were detected
15849 (eg. "VolGroup00").
15850 See also "guestfs_vgs_full".
15852 This function returns a NULL-terminated array of strings (like
15854 environ(3)), or NULL if there was an error. The caller must free the
15855 strings and the array after use.
15856 This function depends on the feature "lvm2". See also
15858 "guestfs_feature_available".
15859 (Added in 0.4)
15861 guestfs_vgs_full
15863 struct guestfs_lvm_vg_list *
15864 guestfs_vgs_full (guestfs_h *g);
15865 List all the volumes groups detected. This is the equivalent of the
15867 vgs(8) command. The "full" version includes all fields.
15868 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
15870 there was an error. The caller must call "guestfs_free_lvm_vg_list"
15871 after use.
15872 This function depends on the feature "lvm2". See also
15874 "guestfs_feature_available".
15875 (Added in 0.4)
15877 guestfs_vgscan
15879 int
15880 guestfs_vgscan (guestfs_h *g);
15881 This function is deprecated. In new code, use the "guestfs_lvm_scan"
15883 call instead.
15884 Deprecated functions will not be removed from the API, but the fact
15886 that they are deprecated indicates that there are problems with correct
15887 use of these functions.
15888 This rescans all block devices and rebuilds the list of LVM physical
15890 volumes, volume groups and logical volumes.
15891 This function returns 0 on success or -1 on error.
15893 (Added in 1.3.2)
15895 guestfs_vguuid
15897 char *
15898 guestfs_vguuid (guestfs_h *g,
15899 const char *vgname);
15900 This command returns the UUID of the LVM VG named "vgname".
15902 This function returns a string, or NULL on error. The caller must free
15904 the returned string after use.
15905 (Added in 1.0.87)
15907 guestfs_wait_ready
15909 int
15910 guestfs_wait_ready (guestfs_h *g);
15911 This function is deprecated. There is no replacement. Consult the API
15913 documentation in guestfs(3) for further information.
15914 Deprecated functions will not be removed from the API, but the fact
15916 that they are deprecated indicates that there are problems with correct
15917 use of these functions.
15918 This function is a no op.
15920 In versions of the API < 1.0.71 you had to call this function just
15922 after calling "guestfs_launch" to wait for the launch to complete.
15923 However this is no longer necessary because "guestfs_launch" now does
15924 the waiting.
15925 If you see any calls to this function in code then you can just remove
15927 them, unless you want to retain compatibility with older versions of
15928 the API.
15929 This function returns 0 on success or -1 on error.
15931 (Added in 0.3)
15933 guestfs_wc_c
15935 int
15936 guestfs_wc_c (guestfs_h *g,
15937 const char *path);
15938 This command counts the characters in a file, using the "wc -c"
15940 external command.
15941 On error this function returns -1.
15943 (Added in 1.0.54)
15945 guestfs_wc_l
15947 int
15948 guestfs_wc_l (guestfs_h *g,
15949 const char *path);
15950 This command counts the lines in a file, using the "wc -l" external
15952 command.
15953 On error this function returns -1.
15955 (Added in 1.0.54)
15957 guestfs_wc_w
15959 int
15960 guestfs_wc_w (guestfs_h *g,
15961 const char *path);
15962 This command counts the words in a file, using the "wc -w" external
15964 command.
15965 On error this function returns -1.
15967 (Added in 1.0.54)
15969 guestfs_wipefs
15971 int
15972 guestfs_wipefs (guestfs_h *g,
15973 const char *device);
15974 This command erases filesystem or RAID signatures from the specified
15976 "device" to make the filesystem invisible to libblkid.
15977 This does not erase the filesystem itself nor any other data from the
15979 "device".
15980 Compare with "guestfs_zero" which zeroes the first few blocks of a
15982 device.
15983 This function returns 0 on success or -1 on error.
15985 This function depends on the feature "wipefs". See also
15987 "guestfs_feature_available".
15988 (Added in 1.17.6)
15990 guestfs_write
15992 int
15993 guestfs_write (guestfs_h *g,
15994 const char *path,
15995 const char *content,
15996 size_t content_size);
15997 This call creates a file called "path". The content of the file is the
15999 string "content" (which can contain any 8 bit data).
16000 See also "guestfs_write_append".
16002 This function returns 0 on success or -1 on error.
16004 (Added in 1.3.14)
16006 guestfs_write_append
16008 int
16009 guestfs_write_append (guestfs_h *g,
16010 const char *path,
16011 const char *content,
16012 size_t content_size);
16013 This call appends "content" to the end of file "path". If "path" does
16015 not exist, then a new file is created.
16016 See also "guestfs_write".
16018 This function returns 0 on success or -1 on error.
16020 (Added in 1.11.18)
16022 guestfs_write_file
16024 int
16025 guestfs_write_file (guestfs_h *g,
16026 const char *path,
16027 const char *content,
16028 int size);
16029 This function is deprecated. In new code, use the "guestfs_write" call
16031 instead.
16032 Deprecated functions will not be removed from the API, but the fact
16034 that they are deprecated indicates that there are problems with correct
16035 use of these functions.
16036 This call creates a file called "path". The contents of the file is
16038 the string "content" (which can contain any 8 bit data), with length
16039 "size".
16040 As a special case, if "size" is 0 then the length is calculated using
16042 "strlen" (so in this case the content cannot contain embedded ASCII
16043 NULs).
16044 NB. Owing to a bug, writing content containing ASCII NUL characters
16046 does not work, even if the length is specified.
16047 This function returns 0 on success or -1 on error.
16049 Because of the message protocol, there is a transfer limit of somewhere
16051 between 2MB and 4MB. See "PROTOCOL LIMITS".
16052 (Added in 0.8)
16054 guestfs_xfs_admin
16056 int
16057 guestfs_xfs_admin (guestfs_h *g,
16058 const char *device,
16059 ...);
16060 You may supply a list of optional arguments to this call. Use zero or
16062 more of the following pairs of parameters, and terminate the list with
16063 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16064 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16066 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16067 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16068 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16069 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16070 GUESTFS_XFS_ADMIN_LABEL, const char *label,
16071 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16072 Change the parameters of the XFS filesystem on "device".
16074 Devices that are mounted cannot be modified. Administrators must
16076 unmount filesystems before this call can modify parameters.
16077 Some of the parameters of a mounted filesystem can be examined and
16079 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16080 This function returns 0 on success or -1 on error.
16082 This function depends on the feature "xfs". See also
16084 "guestfs_feature_available".
16085 (Added in 1.19.33)
16087 guestfs_xfs_admin_va
16089 int
16090 guestfs_xfs_admin_va (guestfs_h *g,
16091 const char *device,
16092 va_list args);
16093 This is the "va_list variant" of "guestfs_xfs_admin".
16095 See "CALLS WITH OPTIONAL ARGUMENTS".
16097 guestfs_xfs_admin_argv
16099 int
16100 guestfs_xfs_admin_argv (guestfs_h *g,
16101 const char *device,
16102 const struct guestfs_xfs_admin_argv *optargs);
16103 This is the "argv variant" of "guestfs_xfs_admin".
16105 See "CALLS WITH OPTIONAL ARGUMENTS".
16107 guestfs_xfs_growfs
16109 int
16110 guestfs_xfs_growfs (guestfs_h *g,
16111 const char *path,
16112 ...);
16113 You may supply a list of optional arguments to this call. Use zero or
16115 more of the following pairs of parameters, and terminate the list with
16116 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16117 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16119 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16120 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16121 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16122 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16123 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16124 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16125 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16126 Grow the XFS filesystem mounted at "path".
16128 The returned struct contains geometry information. Missing fields are
16130 returned as "-1" (for numeric fields) or empty string.
16131 This function returns 0 on success or -1 on error.
16133 This function depends on the feature "xfs". See also
16135 "guestfs_feature_available".
16136 (Added in 1.19.28)
16138 guestfs_xfs_growfs_va
16140 int
16141 guestfs_xfs_growfs_va (guestfs_h *g,
16142 const char *path,
16143 va_list args);
16144 This is the "va_list variant" of "guestfs_xfs_growfs".
16146 See "CALLS WITH OPTIONAL ARGUMENTS".
16148 guestfs_xfs_growfs_argv
16150 int
16151 guestfs_xfs_growfs_argv (guestfs_h *g,
16152 const char *path,
16153 const struct guestfs_xfs_growfs_argv *optargs);
16154 This is the "argv variant" of "guestfs_xfs_growfs".
16156 See "CALLS WITH OPTIONAL ARGUMENTS".
16158 guestfs_xfs_info
16160 struct guestfs_xfsinfo *
16161 guestfs_xfs_info (guestfs_h *g,
16162 const char *pathordevice);
16163 "pathordevice" is a mounted XFS filesystem or a device containing an
16165 XFS filesystem. This command returns the geometry of the filesystem.
16166 The returned struct contains geometry information. Missing fields are
16168 returned as "-1" (for numeric fields) or empty string.
16169 This function returns a "struct guestfs_xfsinfo *", or NULL if there
16171 was an error. The caller must call "guestfs_free_xfsinfo" after use.
16172 This function depends on the feature "xfs". See also
16174 "guestfs_feature_available".
16175 (Added in 1.19.21)
16177 guestfs_xfs_repair
16179 int
16180 guestfs_xfs_repair (guestfs_h *g,
16181 const char *device,
16182 ...);
16183 You may supply a list of optional arguments to this call. Use zero or
16185 more of the following pairs of parameters, and terminate the list with
16186 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16187 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16189 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16190 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16191 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16192 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16193 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16194 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16195 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16196 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16197 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16198 Repair corrupt or damaged XFS filesystem on "device".
16200 The filesystem is specified using the "device" argument which should be
16202 the device name of the disk partition or volume containing the
16203 filesystem. If given the name of a block device, "xfs_repair" will
16204 attempt to find the raw device associated with the specified block
16205 device and will use the raw device instead.
16206 Regardless, the filesystem to be repaired must be unmounted, otherwise,
16208 the resulting filesystem may be inconsistent or corrupt.
16209 The returned status indicates whether filesystem corruption was
16211 detected (returns 1) or was not detected (returns 0).
16212 On error this function returns -1.
16214 This function depends on the feature "xfs". See also
16216 "guestfs_feature_available".
16217 (Added in 1.19.36)
16219 guestfs_xfs_repair_va
16221 int
16222 guestfs_xfs_repair_va (guestfs_h *g,
16223 const char *device,
16224 va_list args);
16225 This is the "va_list variant" of "guestfs_xfs_repair".
16227 See "CALLS WITH OPTIONAL ARGUMENTS".
16229 guestfs_xfs_repair_argv
16231 int
16232 guestfs_xfs_repair_argv (guestfs_h *g,
16233 const char *device,
16234 const struct guestfs_xfs_repair_argv *optargs);
16235 This is the "argv variant" of "guestfs_xfs_repair".
16237 See "CALLS WITH OPTIONAL ARGUMENTS".
16239 guestfs_yara_destroy
16241 int
16242 guestfs_yara_destroy (guestfs_h *g);
16243 Destroy previously loaded Yara rules in order to free libguestfs
16245 resources.
16246 This function returns 0 on success or -1 on error.
16248 This function depends on the feature "libyara". See also
16250 "guestfs_feature_available".
16251 (Added in 1.37.13)
16253 guestfs_yara_load
16255 int
16256 guestfs_yara_load (guestfs_h *g,
16257 const char *filename);
16258 Upload a set of Yara rules from local file filename.
16260 Yara rules allow to categorize files based on textual or binary
16262 patterns within their content. See "guestfs_yara_scan" to see how to
16263 scan files with the loaded rules.
16264 Rules can be in binary format, as when compiled with yarac command, or
16266 in source code format. In the latter case, the rules will be first
16267 compiled and then loaded.
16268 Rules in source code format cannot include external files. In such
16270 cases, it is recommended to compile them first.
16271 Previously loaded rules will be destroyed.
16273 This function returns 0 on success or -1 on error.
16275 This long-running command can generate progress notification messages
16277 so that the caller can display a progress bar or indicator. To receive
16278 these messages, the caller must register a progress event callback.
16279 See "GUESTFS_EVENT_PROGRESS".
16280 This function depends on the feature "libyara". See also
16282 "guestfs_feature_available".
16283 (Added in 1.37.13)
16285 guestfs_yara_scan
16287 struct guestfs_yara_detection_list *
16288 guestfs_yara_scan (guestfs_h *g,
16289 const char *path);
16290 Scan a file with the previously loaded Yara rules.
16292 For each matching rule, a "yara_detection" structure is returned.
16294 The "yara_detection" structure contains the following fields.
16296 "yara_name"
16298 Path of the file matching a Yara rule.
16299 "yara_rule"
16301 Identifier of the Yara rule which matched against the given file.
16302 This function returns a "struct guestfs_yara_detection_list *", or NULL
16304 if there was an error. The caller must call
16305 "guestfs_free_yara_detection_list" after use.
16306 This long-running command can generate progress notification messages
16308 so that the caller can display a progress bar or indicator. To receive
16309 these messages, the caller must register a progress event callback.
16310 See "GUESTFS_EVENT_PROGRESS".
16311 This function depends on the feature "libyara". See also
16313 "guestfs_feature_available".
16314 (Added in 1.37.13)
16316 guestfs_zegrep
16318 char **
16319 guestfs_zegrep (guestfs_h *g,
16320 const char *regex,
16321 const char *path);
16322 This function is deprecated. In new code, use the "guestfs_grep" call
16324 instead.
16325 Deprecated functions will not be removed from the API, but the fact
16327 that they are deprecated indicates that there are problems with correct
16328 use of these functions.
16329 This calls the external "zegrep" program and returns the matching
16331 lines.
16332 This function returns a NULL-terminated array of strings (like
16334 environ(3)), or NULL if there was an error. The caller must free the
16335 strings and the array after use.
16336 Because of the message protocol, there is a transfer limit of somewhere
16338 between 2MB and 4MB. See "PROTOCOL LIMITS".
16339 (Added in 1.0.66)
16341 guestfs_zegrepi
16343 char **
16344 guestfs_zegrepi (guestfs_h *g,
16345 const char *regex,
16346 const char *path);
16347 This function is deprecated. In new code, use the "guestfs_grep" call
16349 instead.
16350 Deprecated functions will not be removed from the API, but the fact
16352 that they are deprecated indicates that there are problems with correct
16353 use of these functions.
16354 This calls the external "zegrep -i" program and returns the matching
16356 lines.
16357 This function returns a NULL-terminated array of strings (like
16359 environ(3)), or NULL if there was an error. The caller must free the
16360 strings and the array after use.
16361 Because of the message protocol, there is a transfer limit of somewhere
16363 between 2MB and 4MB. See "PROTOCOL LIMITS".
16364 (Added in 1.0.66)
16366 guestfs_zero
16368 int
16369 guestfs_zero (guestfs_h *g,
16370 const char *device);
16371 This command writes zeroes over the first few blocks of "device".
16373 How many blocks are zeroed isn't specified (but it’s not enough to
16375 securely wipe the device). It should be sufficient to remove any
16376 partition tables, filesystem superblocks and so on.
16377 If blocks are already zero, then this command avoids writing zeroes.
16379 This prevents the underlying device from becoming non-sparse or growing
16380 unnecessarily.
16381 See also: "guestfs_zero_device", "guestfs_scrub_device",
16383 "guestfs_is_zero_device"
16384 This function returns 0 on success or -1 on error.
16386 This long-running command can generate progress notification messages
16388 so that the caller can display a progress bar or indicator. To receive
16389 these messages, the caller must register a progress event callback.
16390 See "GUESTFS_EVENT_PROGRESS".
16391 (Added in 1.0.16)
16393 guestfs_zero_device
16395 int
16396 guestfs_zero_device (guestfs_h *g,
16397 const char *device);
16398 This command writes zeroes over the entire "device". Compare with
16400 "guestfs_zero" which just zeroes the first few blocks of a device.
16401 If blocks are already zero, then this command avoids writing zeroes.
16403 This prevents the underlying device from becoming non-sparse or growing
16404 unnecessarily.
16405 This function returns 0 on success or -1 on error.
16407 This long-running command can generate progress notification messages
16409 so that the caller can display a progress bar or indicator. To receive
16410 these messages, the caller must register a progress event callback.
16411 See "GUESTFS_EVENT_PROGRESS".
16412 (Added in 1.3.1)
16414 guestfs_zero_free_space
16416 int
16417 guestfs_zero_free_space (guestfs_h *g,
16418 const char *directory);
16419 Zero the free space in the filesystem mounted on directory. The
16421 filesystem must be mounted read-write.
16422 The filesystem contents are not affected, but any free space in the
16424 filesystem is freed.
16425 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16427 either as an alternative to this, or after calling this, depending on
16428 your requirements.
16429 This function returns 0 on success or -1 on error.
16431 This long-running command can generate progress notification messages
16433 so that the caller can display a progress bar or indicator. To receive
16434 these messages, the caller must register a progress event callback.
16435 See "GUESTFS_EVENT_PROGRESS".
16436 (Added in 1.17.18)
16438 guestfs_zerofree
16440 int
16441 guestfs_zerofree (guestfs_h *g,
16442 const char *device);
16443 This runs the zerofree program on "device". This program claims to
16445 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16446 it possible to compress the filesystem more effectively.
16447 You should not run this program if the filesystem is mounted.
16449 It is possible that using this program can damage the filesystem or
16451 data on the filesystem.
16452 This function returns 0 on success or -1 on error.
16454 This function depends on the feature "zerofree". See also
16456 "guestfs_feature_available".
16457 (Added in 1.0.26)
16459 guestfs_zfgrep
16461 char **
16462 guestfs_zfgrep (guestfs_h *g,
16463 const char *pattern,
16464 const char *path);
16465 This function is deprecated. In new code, use the "guestfs_grep" call
16467 instead.
16468 Deprecated functions will not be removed from the API, but the fact
16470 that they are deprecated indicates that there are problems with correct
16471 use of these functions.
16472 This calls the external "zfgrep" program and returns the matching
16474 lines.
16475 This function returns a NULL-terminated array of strings (like
16477 environ(3)), or NULL if there was an error. The caller must free the
16478 strings and the array after use.
16479 Because of the message protocol, there is a transfer limit of somewhere
16481 between 2MB and 4MB. See "PROTOCOL LIMITS".
16482 (Added in 1.0.66)
16484 guestfs_zfgrepi
16486 char **
16487 guestfs_zfgrepi (guestfs_h *g,
16488 const char *pattern,
16489 const char *path);
16490 This function is deprecated. In new code, use the "guestfs_grep" call
16492 instead.
16493 Deprecated functions will not be removed from the API, but the fact
16495 that they are deprecated indicates that there are problems with correct
16496 use of these functions.
16497 This calls the external "zfgrep -i" program and returns the matching
16499 lines.
16500 This function returns a NULL-terminated array of strings (like
16502 environ(3)), or NULL if there was an error. The caller must free the
16503 strings and the array after use.
16504 Because of the message protocol, there is a transfer limit of somewhere
16506 between 2MB and 4MB. See "PROTOCOL LIMITS".
16507 (Added in 1.0.66)
16509 guestfs_zfile
16511 char *
16512 guestfs_zfile (guestfs_h *g,
16513 const char *meth,
16514 const char *path);
16515 This function is deprecated. In new code, use the "guestfs_file" call
16517 instead.
16518 Deprecated functions will not be removed from the API, but the fact
16520 that they are deprecated indicates that there are problems with correct
16521 use of these functions.
16522 This command runs file(1) after first decompressing "path" using
16524 "meth".
16525 "meth" must be one of "gzip", "compress" or "bzip2".
16527 Since 1.0.63, use "guestfs_file" instead which can now process
16529 compressed files.
16530 This function returns a string, or NULL on error. The caller must free
16532 the returned string after use.
16533 (Added in 1.0.59)
16535 guestfs_zgrep
16537 char **
16538 guestfs_zgrep (guestfs_h *g,
16539 const char *regex,
16540 const char *path);
16541 This function is deprecated. In new code, use the "guestfs_grep" call
16543 instead.
16544 Deprecated functions will not be removed from the API, but the fact
16546 that they are deprecated indicates that there are problems with correct
16547 use of these functions.
16548 This calls the external zgrep(1) program and returns the matching
16550 lines.
16551 This function returns a NULL-terminated array of strings (like
16553 environ(3)), or NULL if there was an error. The caller must free the
16554 strings and the array after use.
16555 Because of the message protocol, there is a transfer limit of somewhere
16557 between 2MB and 4MB. See "PROTOCOL LIMITS".
16558 (Added in 1.0.66)
16560 guestfs_zgrepi
16562 char **
16563 guestfs_zgrepi (guestfs_h *g,
16564 const char *regex,
16565 const char *path);
16566 This function is deprecated. In new code, use the "guestfs_grep" call
16568 instead.
16569 Deprecated functions will not be removed from the API, but the fact
16571 that they are deprecated indicates that there are problems with correct
16572 use of these functions.
16573 This calls the external "zgrep -i" program and returns the matching
16575 lines.
16576 This function returns a NULL-terminated array of strings (like
16578 environ(3)), or NULL if there was an error. The caller must free the
16579 strings and the array after use.
16580 Because of the message protocol, there is a transfer limit of somewhere
16582 between 2MB and 4MB. See "PROTOCOL LIMITS".
16583 (Added in 1.0.66)
16585
16587 guestfs_int_bool
16588 struct guestfs_int_bool {
16589 int32_t i;
16590 int32_t b;
16591 };
16592 struct guestfs_int_bool_list {
16594 uint32_t len; /* Number of elements in list. */
16595 struct guestfs_int_bool *val; /* Elements. */
16596 };
16597 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16599 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16600 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16602 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16603 void guestfs_free_int_bool (struct guestfs_int_bool *);
16605 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16606 guestfs_lvm_pv
16608 struct guestfs_lvm_pv {
16609 char *pv_name;
16610 /* The next field is NOT nul-terminated, be careful when printing it: */
16611 char pv_uuid[32];
16612 char *pv_fmt;
16613 uint64_t pv_size;
16614 uint64_t dev_size;
16615 uint64_t pv_free;
16616 uint64_t pv_used;
16617 char *pv_attr;
16618 int64_t pv_pe_count;
16619 int64_t pv_pe_alloc_count;
16620 char *pv_tags;
16621 uint64_t pe_start;
16622 int64_t pv_mda_count;
16623 uint64_t pv_mda_free;
16624 };
16625 struct guestfs_lvm_pv_list {
16627 uint32_t len; /* Number of elements in list. */
16628 struct guestfs_lvm_pv *val; /* Elements. */
16629 };
16630 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16632 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16633 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16635 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16636 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16638 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16639 guestfs_lvm_vg
16641 struct guestfs_lvm_vg {
16642 char *vg_name;
16643 /* The next field is NOT nul-terminated, be careful when printing it: */
16644 char vg_uuid[32];
16645 char *vg_fmt;
16646 char *vg_attr;
16647 uint64_t vg_size;
16648 uint64_t vg_free;
16649 char *vg_sysid;
16650 uint64_t vg_extent_size;
16651 int64_t vg_extent_count;
16652 int64_t vg_free_count;
16653 int64_t max_lv;
16654 int64_t max_pv;
16655 int64_t pv_count;
16656 int64_t lv_count;
16657 int64_t snap_count;
16658 int64_t vg_seqno;
16659 char *vg_tags;
16660 int64_t vg_mda_count;
16661 uint64_t vg_mda_free;
16662 };
16663 struct guestfs_lvm_vg_list {
16665 uint32_t len; /* Number of elements in list. */
16666 struct guestfs_lvm_vg *val; /* Elements. */
16667 };
16668 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16670 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16671 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16673 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16674 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16676 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16677 guestfs_lvm_lv
16679 struct guestfs_lvm_lv {
16680 char *lv_name;
16681 /* The next field is NOT nul-terminated, be careful when printing it: */
16682 char lv_uuid[32];
16683 char *lv_attr;
16684 int64_t lv_major;
16685 int64_t lv_minor;
16686 int64_t lv_kernel_major;
16687 int64_t lv_kernel_minor;
16688 uint64_t lv_size;
16689 int64_t seg_count;
16690 char *origin;
16691 /* The next field is [0..100] or -1 meaning 'not present': */
16692 float snap_percent;
16693 /* The next field is [0..100] or -1 meaning 'not present': */
16694 float copy_percent;
16695 char *move_pv;
16696 char *lv_tags;
16697 char *mirror_log;
16698 char *modules;
16699 };
16700 struct guestfs_lvm_lv_list {
16702 uint32_t len; /* Number of elements in list. */
16703 struct guestfs_lvm_lv *val; /* Elements. */
16704 };
16705 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16707 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16708 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16710 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16711 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16713 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16714 guestfs_stat
16716 struct guestfs_stat {
16717 int64_t dev;
16718 int64_t ino;
16719 int64_t mode;
16720 int64_t nlink;
16721 int64_t uid;
16722 int64_t gid;
16723 int64_t rdev;
16724 int64_t size;
16725 int64_t blksize;
16726 int64_t blocks;
16727 int64_t atime;
16728 int64_t mtime;
16729 int64_t ctime;
16730 };
16731 struct guestfs_stat_list {
16733 uint32_t len; /* Number of elements in list. */
16734 struct guestfs_stat *val; /* Elements. */
16735 };
16736 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16738 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16739 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16741 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16742 void guestfs_free_stat (struct guestfs_stat *);
16744 void guestfs_free_stat_list (struct guestfs_stat_list *);
16745 guestfs_statns
16747 struct guestfs_statns {
16748 int64_t st_dev;
16749 int64_t st_ino;
16750 int64_t st_mode;
16751 int64_t st_nlink;
16752 int64_t st_uid;
16753 int64_t st_gid;
16754 int64_t st_rdev;
16755 int64_t st_size;
16756 int64_t st_blksize;
16757 int64_t st_blocks;
16758 int64_t st_atime_sec;
16759 int64_t st_atime_nsec;
16760 int64_t st_mtime_sec;
16761 int64_t st_mtime_nsec;
16762 int64_t st_ctime_sec;
16763 int64_t st_ctime_nsec;
16764 int64_t st_spare1;
16765 int64_t st_spare2;
16766 int64_t st_spare3;
16767 int64_t st_spare4;
16768 int64_t st_spare5;
16769 int64_t st_spare6;
16770 };
16771 struct guestfs_statns_list {
16773 uint32_t len; /* Number of elements in list. */
16774 struct guestfs_statns *val; /* Elements. */
16775 };
16776 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16778 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16779 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16781 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16782 void guestfs_free_statns (struct guestfs_statns *);
16784 void guestfs_free_statns_list (struct guestfs_statns_list *);
16785 guestfs_statvfs
16787 struct guestfs_statvfs {
16788 int64_t bsize;
16789 int64_t frsize;
16790 int64_t blocks;
16791 int64_t bfree;
16792 int64_t bavail;
16793 int64_t files;
16794 int64_t ffree;
16795 int64_t favail;
16796 int64_t fsid;
16797 int64_t flag;
16798 int64_t namemax;
16799 };
16800 struct guestfs_statvfs_list {
16802 uint32_t len; /* Number of elements in list. */
16803 struct guestfs_statvfs *val; /* Elements. */
16804 };
16805 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16807 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16808 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16810 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16811 void guestfs_free_statvfs (struct guestfs_statvfs *);
16813 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16814 guestfs_dirent
16816 struct guestfs_dirent {
16817 int64_t ino;
16818 char ftyp;
16819 char *name;
16820 };
16821 struct guestfs_dirent_list {
16823 uint32_t len; /* Number of elements in list. */
16824 struct guestfs_dirent *val; /* Elements. */
16825 };
16826 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16828 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16829 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16831 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16832 void guestfs_free_dirent (struct guestfs_dirent *);
16834 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16835 guestfs_version
16837 struct guestfs_version {
16838 int64_t major;
16839 int64_t minor;
16840 int64_t release;
16841 char *extra;
16842 };
16843 struct guestfs_version_list {
16845 uint32_t len; /* Number of elements in list. */
16846 struct guestfs_version *val; /* Elements. */
16847 };
16848 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16850 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16851 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16853 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16854 void guestfs_free_version (struct guestfs_version *);
16856 void guestfs_free_version_list (struct guestfs_version_list *);
16857 guestfs_xattr
16859 struct guestfs_xattr {
16860 char *attrname;
16861 /* The next two fields describe a byte array. */
16862 uint32_t attrval_len;
16863 char *attrval;
16864 };
16865 struct guestfs_xattr_list {
16867 uint32_t len; /* Number of elements in list. */
16868 struct guestfs_xattr *val; /* Elements. */
16869 };
16870 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16872 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16873 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
16875 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
16876 void guestfs_free_xattr (struct guestfs_xattr *);
16878 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
16879 guestfs_inotify_event
16881 struct guestfs_inotify_event {
16882 int64_t in_wd;
16883 uint32_t in_mask;
16884 uint32_t in_cookie;
16885 char *in_name;
16886 };
16887 struct guestfs_inotify_event_list {
16889 uint32_t len; /* Number of elements in list. */
16890 struct guestfs_inotify_event *val; /* Elements. */
16891 };
16892 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
16894 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
16895 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
16897 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
16898 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
16900 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
16901 guestfs_partition
16903 struct guestfs_partition {
16904 int32_t part_num;
16905 uint64_t part_start;
16906 uint64_t part_end;
16907 uint64_t part_size;
16908 };
16909 struct guestfs_partition_list {
16911 uint32_t len; /* Number of elements in list. */
16912 struct guestfs_partition *val; /* Elements. */
16913 };
16914 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
16916 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
16917 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
16919 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
16920 void guestfs_free_partition (struct guestfs_partition *);
16922 void guestfs_free_partition_list (struct guestfs_partition_list *);
16923 guestfs_application
16925 struct guestfs_application {
16926 char *app_name;
16927 char *app_display_name;
16928 int32_t app_epoch;
16929 char *app_version;
16930 char *app_release;
16931 char *app_install_path;
16932 char *app_trans_path;
16933 char *app_publisher;
16934 char *app_url;
16935 char *app_source_package;
16936 char *app_summary;
16937 char *app_description;
16938 };
16939 struct guestfs_application_list {
16941 uint32_t len; /* Number of elements in list. */
16942 struct guestfs_application *val; /* Elements. */
16943 };
16944 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
16946 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
16947 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
16949 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
16950 void guestfs_free_application (struct guestfs_application *);
16952 void guestfs_free_application_list (struct guestfs_application_list *);
16953 guestfs_application2
16955 struct guestfs_application2 {
16956 char *app2_name;
16957 char *app2_display_name;
16958 int32_t app2_epoch;
16959 char *app2_version;
16960 char *app2_release;
16961 char *app2_arch;
16962 char *app2_install_path;
16963 char *app2_trans_path;
16964 char *app2_publisher;
16965 char *app2_url;
16966 char *app2_source_package;
16967 char *app2_summary;
16968 char *app2_description;
16969 char *app2_spare1;
16970 char *app2_spare2;
16971 char *app2_spare3;
16972 char *app2_spare4;
16973 };
16974 struct guestfs_application2_list {
16976 uint32_t len; /* Number of elements in list. */
16977 struct guestfs_application2 *val; /* Elements. */
16978 };
16979 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
16981 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
16982 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
16984 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
16985 void guestfs_free_application2 (struct guestfs_application2 *);
16987 void guestfs_free_application2_list (struct guestfs_application2_list *);
16988 guestfs_isoinfo
16990 struct guestfs_isoinfo {
16991 char *iso_system_id;
16992 char *iso_volume_id;
16993 uint32_t iso_volume_space_size;
16994 uint32_t iso_volume_set_size;
16995 uint32_t iso_volume_sequence_number;
16996 uint32_t iso_logical_block_size;
16997 char *iso_volume_set_id;
16998 char *iso_publisher_id;
16999 char *iso_data_preparer_id;
17000 char *iso_application_id;
17001 char *iso_copyright_file_id;
17002 char *iso_abstract_file_id;
17003 char *iso_bibliographic_file_id;
17004 int64_t iso_volume_creation_t;
17005 int64_t iso_volume_modification_t;
17006 int64_t iso_volume_expiration_t;
17007 int64_t iso_volume_effective_t;
17008 };
17009 struct guestfs_isoinfo_list {
17011 uint32_t len; /* Number of elements in list. */
17012 struct guestfs_isoinfo *val; /* Elements. */
17013 };
17014 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
17016 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
17017 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
17019 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
17020 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
17022 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
17023 guestfs_mdstat
17025 struct guestfs_mdstat {
17026 char *mdstat_device;
17027 int32_t mdstat_index;
17028 char *mdstat_flags;
17029 };
17030 struct guestfs_mdstat_list {
17032 uint32_t len; /* Number of elements in list. */
17033 struct guestfs_mdstat *val; /* Elements. */
17034 };
17035 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
17037 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
17038 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
17040 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
17041 void guestfs_free_mdstat (struct guestfs_mdstat *);
17043 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
17044 guestfs_btrfssubvolume
17046 struct guestfs_btrfssubvolume {
17047 uint64_t btrfssubvolume_id;
17048 uint64_t btrfssubvolume_top_level_id;
17049 char *btrfssubvolume_path;
17050 };
17051 struct guestfs_btrfssubvolume_list {
17053 uint32_t len; /* Number of elements in list. */
17054 struct guestfs_btrfssubvolume *val; /* Elements. */
17055 };
17056 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17058 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17059 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17061 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17062 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17064 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17065 guestfs_btrfsqgroup
17067 struct guestfs_btrfsqgroup {
17068 char *btrfsqgroup_id;
17069 uint64_t btrfsqgroup_rfer;
17070 uint64_t btrfsqgroup_excl;
17071 };
17072 struct guestfs_btrfsqgroup_list {
17074 uint32_t len; /* Number of elements in list. */
17075 struct guestfs_btrfsqgroup *val; /* Elements. */
17076 };
17077 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17079 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17080 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17082 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17083 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17085 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17086 guestfs_btrfsbalance
17088 struct guestfs_btrfsbalance {
17089 char *btrfsbalance_status;
17090 uint64_t btrfsbalance_total;
17091 uint64_t btrfsbalance_balanced;
17092 uint64_t btrfsbalance_considered;
17093 uint64_t btrfsbalance_left;
17094 };
17095 struct guestfs_btrfsbalance_list {
17097 uint32_t len; /* Number of elements in list. */
17098 struct guestfs_btrfsbalance *val; /* Elements. */
17099 };
17100 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17102 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17103 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17105 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17106 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17108 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17109 guestfs_btrfsscrub
17111 struct guestfs_btrfsscrub {
17112 uint64_t btrfsscrub_data_extents_scrubbed;
17113 uint64_t btrfsscrub_tree_extents_scrubbed;
17114 uint64_t btrfsscrub_data_bytes_scrubbed;
17115 uint64_t btrfsscrub_tree_bytes_scrubbed;
17116 uint64_t btrfsscrub_read_errors;
17117 uint64_t btrfsscrub_csum_errors;
17118 uint64_t btrfsscrub_verify_errors;
17119 uint64_t btrfsscrub_no_csum;
17120 uint64_t btrfsscrub_csum_discards;
17121 uint64_t btrfsscrub_super_errors;
17122 uint64_t btrfsscrub_malloc_errors;
17123 uint64_t btrfsscrub_uncorrectable_errors;
17124 uint64_t btrfsscrub_unverified_errors;
17125 uint64_t btrfsscrub_corrected_errors;
17126 uint64_t btrfsscrub_last_physical;
17127 };
17128 struct guestfs_btrfsscrub_list {
17130 uint32_t len; /* Number of elements in list. */
17131 struct guestfs_btrfsscrub *val; /* Elements. */
17132 };
17133 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17135 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17136 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17138 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17139 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17141 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17142 guestfs_xfsinfo
17144 struct guestfs_xfsinfo {
17145 char *xfs_mntpoint;
17146 uint32_t xfs_inodesize;
17147 uint32_t xfs_agcount;
17148 uint32_t xfs_agsize;
17149 uint32_t xfs_sectsize;
17150 uint32_t xfs_attr;
17151 uint32_t xfs_blocksize;
17152 uint64_t xfs_datablocks;
17153 uint32_t xfs_imaxpct;
17154 uint32_t xfs_sunit;
17155 uint32_t xfs_swidth;
17156 uint32_t xfs_dirversion;
17157 uint32_t xfs_dirblocksize;
17158 uint32_t xfs_cimode;
17159 char *xfs_logname;
17160 uint32_t xfs_logblocksize;
17161 uint32_t xfs_logblocks;
17162 uint32_t xfs_logversion;
17163 uint32_t xfs_logsectsize;
17164 uint32_t xfs_logsunit;
17165 uint32_t xfs_lazycount;
17166 char *xfs_rtname;
17167 uint32_t xfs_rtextsize;
17168 uint64_t xfs_rtblocks;
17169 uint64_t xfs_rtextents;
17170 };
17171 struct guestfs_xfsinfo_list {
17173 uint32_t len; /* Number of elements in list. */
17174 struct guestfs_xfsinfo *val; /* Elements. */
17175 };
17176 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17178 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17179 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17181 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17182 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17184 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17185 guestfs_utsname
17187 struct guestfs_utsname {
17188 char *uts_sysname;
17189 char *uts_release;
17190 char *uts_version;
17191 char *uts_machine;
17192 };
17193 struct guestfs_utsname_list {
17195 uint32_t len; /* Number of elements in list. */
17196 struct guestfs_utsname *val; /* Elements. */
17197 };
17198 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17200 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17201 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17203 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17204 void guestfs_free_utsname (struct guestfs_utsname *);
17206 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17207 guestfs_hivex_node
17209 struct guestfs_hivex_node {
17210 int64_t hivex_node_h;
17211 };
17212 struct guestfs_hivex_node_list {
17214 uint32_t len; /* Number of elements in list. */
17215 struct guestfs_hivex_node *val; /* Elements. */
17216 };
17217 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17219 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17220 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17222 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17223 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17225 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17226 guestfs_hivex_value
17228 struct guestfs_hivex_value {
17229 int64_t hivex_value_h;
17230 };
17231 struct guestfs_hivex_value_list {
17233 uint32_t len; /* Number of elements in list. */
17234 struct guestfs_hivex_value *val; /* Elements. */
17235 };
17236 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17238 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17239 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17241 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17242 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17244 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17245 guestfs_internal_mountable
17247 struct guestfs_internal_mountable {
17248 int32_t im_type;
17249 char *im_device;
17250 char *im_volume;
17251 };
17252 struct guestfs_internal_mountable_list {
17254 uint32_t len; /* Number of elements in list. */
17255 struct guestfs_internal_mountable *val; /* Elements. */
17256 };
17257 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17259 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17260 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17262 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17263 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17265 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17266 guestfs_tsk_dirent
17268 struct guestfs_tsk_dirent {
17269 uint64_t tsk_inode;
17270 char tsk_type;
17271 int64_t tsk_size;
17272 char *tsk_name;
17273 uint32_t tsk_flags;
17274 int64_t tsk_atime_sec;
17275 int64_t tsk_atime_nsec;
17276 int64_t tsk_mtime_sec;
17277 int64_t tsk_mtime_nsec;
17278 int64_t tsk_ctime_sec;
17279 int64_t tsk_ctime_nsec;
17280 int64_t tsk_crtime_sec;
17281 int64_t tsk_crtime_nsec;
17282 int64_t tsk_nlink;
17283 char *tsk_link;
17284 int64_t tsk_spare1;
17285 };
17286 struct guestfs_tsk_dirent_list {
17288 uint32_t len; /* Number of elements in list. */
17289 struct guestfs_tsk_dirent *val; /* Elements. */
17290 };
17291 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17293 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17294 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17296 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17297 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17299 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17300 guestfs_yara_detection
17302 struct guestfs_yara_detection {
17303 char *yara_name;
17304 char *yara_rule;
17305 };
17306 struct guestfs_yara_detection_list {
17308 uint32_t len; /* Number of elements in list. */
17309 struct guestfs_yara_detection *val; /* Elements. */
17310 };
17311 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17313 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17314 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17316 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17317 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17319 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17320
17322 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17323 Using "guestfs_available" you can test availability of the following
17324 groups of functions. This test queries the appliance to see if the
17325 appliance you are currently using supports the functionality.
17326 acl The following functions: "guestfs_acl_delete_def_file"
17328 "guestfs_acl_get_file" "guestfs_acl_set_file"
17329 blkdiscard
17331 The following functions: "guestfs_blkdiscard"
17332 blkdiscardzeroes
17334 The following functions: "guestfs_blkdiscardzeroes"
17335 btrfs
17337 The following functions: "guestfs_btrfs_balance_cancel"
17338 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17339 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17340 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17341 "guestfs_btrfs_filesystem_defragment"
17342 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17343 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17344 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17345 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17346 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17347 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17348 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17349 "guestfs_btrfs_rescue_chunk_recover"
17350 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17351 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17352 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17353 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17354 "guestfs_btrfs_subvolume_get_default"
17355 "guestfs_btrfs_subvolume_list"
17356 "guestfs_btrfs_subvolume_set_default"
17357 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17358 "guestfs_btrfstune_enable_extended_inode_refs"
17359 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17360 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17361 extlinux
17363 The following functions: "guestfs_extlinux"
17364 f2fs
17366 The following functions: "guestfs_f2fs_expand"
17367 fstrim
17369 The following functions: "guestfs_fstrim"
17370 gdisk
17372 The following functions: "guestfs_part_expand_gpt"
17373 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17374 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17375 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17376 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17377 "guestfs_part_set_gpt_type"
17378 grub
17380 The following functions: "guestfs_grub_install"
17381 hivex
17383 The following functions: "guestfs_hivex_close"
17384 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17385 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17386 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17387 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17388 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17389 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17390 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17391 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17392 inotify
17394 The following functions: "guestfs_inotify_add_watch"
17395 "guestfs_inotify_close" "guestfs_inotify_files"
17396 "guestfs_inotify_init" "guestfs_inotify_read"
17397 "guestfs_inotify_rm_watch"
17398 journal
17400 The following functions: "guestfs_internal_journal_get"
17401 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17402 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17403 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17404 "guestfs_journal_skip"
17405 ldm The following functions: "guestfs_ldmtool_create_all"
17407 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17408 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17409 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17410 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17411 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17412 "guestfs_list_ldm_volumes"
17413 libtsk
17415 The following functions: "guestfs_internal_filesystem_walk"
17416 "guestfs_internal_find_inode"
17417 libyara
17419 The following functions: "guestfs_internal_yara_scan"
17420 "guestfs_yara_destroy" "guestfs_yara_load"
17421 linuxcaps
17423 The following functions: "guestfs_cap_get_file"
17424 "guestfs_cap_set_file"
17425 linuxfsuuid
17427 The following functions: "guestfs_mke2fs_JU"
17428 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17429 "guestfs_swapon_uuid"
17430 linuxmodules
17432 The following functions: "guestfs_modprobe"
17433 linuxxattrs
17435 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17436 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17437 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17438 "guestfs_removexattr" "guestfs_setxattr"
17439 luks
17441 The following functions: "guestfs_luks_add_key"
17442 "guestfs_luks_close" "guestfs_luks_format"
17443 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17444 "guestfs_luks_open" "guestfs_luks_open_ro" "guestfs_luks_uuid"
17445 lvm2
17447 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17448 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17449 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17450 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17451 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17452 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17453 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17454 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17455 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17456 "guestfs_vgs" "guestfs_vgs_full"
17457 mdadm
17459 The following functions: "guestfs_md_create" "guestfs_md_detail"
17460 "guestfs_md_stat" "guestfs_md_stop"
17461 mknod
17463 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17464 "guestfs_mknod_b" "guestfs_mknod_c"
17465 ntfs3g
17467 The following functions: "guestfs_ntfs_3g_probe"
17468 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17469 ntfsprogs
17471 The following functions: "guestfs_ntfsresize"
17472 "guestfs_ntfsresize_size"
17473 rsync
17475 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17476 "guestfs_rsync_out"
17477 scrub
17479 The following functions: "guestfs_scrub_device"
17480 "guestfs_scrub_file" "guestfs_scrub_freespace"
17481 selinux
17483 The following functions: "guestfs_getcon" "guestfs_setcon"
17484 selinuxrelabel
17486 The following functions: "guestfs_selinux_relabel"
17487 sleuthkit
17489 The following functions: "guestfs_download_blocks"
17490 "guestfs_download_inode"
17491 squashfs
17493 The following functions: "guestfs_mksquashfs"
17494 syslinux
17496 The following functions: "guestfs_syslinux"
17497 wipefs
17499 The following functions: "guestfs_wipefs"
17500 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17502 "guestfs_xfs_info" "guestfs_xfs_repair"
17503 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17505 zerofree
17507 The following functions: "guestfs_zerofree"
17508 FILESYSTEM AVAILABLE
17510 The "guestfs_filesystem_available" call tests whether a filesystem type
17511 is supported by the appliance kernel.
17512 This is mainly useful as a negative test. If this returns true, it
17514 doesn't mean that a particular filesystem can be mounted, since
17515 filesystems can fail for other reasons such as it being a later version
17516 of the filesystem, or having incompatible features.
17517 GUESTFISH supported COMMAND
17519 In guestfish(3) there is a handy interactive command "supported" which
17520 prints out the available groups and whether they are supported by this
17521 build of libguestfs. Note however that you have to do "run" first.
17522 SINGLE CALLS AT COMPILE TIME
17524 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17525 function, such as:
17526 #define GUESTFS_HAVE_DD 1
17528 if "guestfs_dd" is available.
17530 Before version 1.5.8, if you needed to test whether a single libguestfs
17532 function is available at compile time, we recommended using build tools
17533 such as autoconf or cmake. For example in autotools you could use:
17534 AC_CHECK_LIB([guestfs],[guestfs_create])
17536 AC_CHECK_FUNCS([guestfs_dd])
17537 which would result in "HAVE_GUESTFS_DD" being either defined or not
17539 defined in your program.
17540 SINGLE CALLS AT RUN TIME
17542 Testing at compile time doesn't guarantee that a function really exists
17543 in the library. The reason is that you might be dynamically linked
17544 against a previous libguestfs.so (dynamic library) which doesn't have
17545 the call. This situation unfortunately results in a segmentation
17546 fault, which is a shortcoming of the C dynamic linking system itself.
17547 You can use dlopen(3) to test if a function is available at run time,
17549 as in this example program (note that you still need the compile time
17550 check as well):
17551 #include <stdio.h>
17553 #include <stdlib.h>
17554 #include <unistd.h>
17555 #include <dlfcn.h>
17556 #include <guestfs.h>
17557 main ()
17559 {
17560 #ifdef GUESTFS_HAVE_DD
17561 void *dl;
17562 int has_function;
17563 /* Test if the function guestfs_dd is really available. */
17565 dl = dlopen (NULL, RTLD_LAZY);
17566 if (!dl) {
17567 fprintf (stderr, "dlopen: %s\n", dlerror ());
17568 exit (EXIT_FAILURE);
17569 }
17570 has_function = dlsym (dl, "guestfs_dd") != NULL;
17571 dlclose (dl);
17572 if (!has_function)
17574 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17575 else {
17576 printf ("this libguestfs.so has guestfs_dd function\n");
17577 /* Now it's safe to call
17578 guestfs_dd (g, "foo", "bar");
17579 */
17580 }
17581 #else
17582 printf ("guestfs_dd function was not found at compile time\n");
17583 #endif
17584 }
17585 You may think the above is an awful lot of hassle, and it is. There
17587 are other ways outside of the C linking system to ensure that this kind
17588 of incompatibility never arises, such as using package versioning:
17589 Requires: libguestfs >= 1.0.80
17591
17593 A recent feature of the API is the introduction of calls which take
17594 optional arguments. In C these are declared 3 ways. The main way is
17595 as a call which takes variable arguments (ie. "..."), as in this
17596 example:
17597 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17599 Call this with a list of optional arguments, terminated by "-1". So to
17601 call with no optional arguments specified:
17602 guestfs_add_drive_opts (g, filename, -1);
17604 With a single optional argument:
17606 guestfs_add_drive_opts (g, filename,
17608 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17609 -1);
17610 With two:
17612 guestfs_add_drive_opts (g, filename,
17614 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17615 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17616 -1);
17617 and so forth. Don’t forget the terminating "-1" otherwise Bad Things
17619 will happen!
17620 USING va_list FOR OPTIONAL ARGUMENTS
17622 The second variant has the same name with the suffix "_va", which works
17623 the same way but takes a "va_list". See the C manual for details. For
17624 the example function, this is declared:
17625 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17627 va_list args);
17628 CONSTRUCTING OPTIONAL ARGUMENTS
17630 The third variant is useful where you need to construct these calls.
17631 You pass in a structure where you fill in the optional fields. The
17632 structure has a bitmask as the first element which you must set to
17633 indicate which fields you have filled in. For our example function the
17634 structure and call are declared:
17635 struct guestfs_add_drive_opts_argv {
17637 uint64_t bitmask;
17638 int readonly;
17639 const char *format;
17640 /* ... */
17641 };
17642 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17643 const struct guestfs_add_drive_opts_argv *optargs);
17644 You could call it like this:
17646 struct guestfs_add_drive_opts_argv optargs = {
17648 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17649 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17650 .readonly = 1,
17651 .format = "qcow2"
17652 };
17653 guestfs_add_drive_opts_argv (g, filename, &optargs);
17655 Notes:
17657 · The "_BITMASK" suffix on each option name when specifying the
17659 bitmask.
17660 · You do not need to fill in all fields of the structure.
17662 · There must be a one-to-one correspondence between fields of the
17664 structure that are filled in, and bits set in the bitmask.
17665 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17667 In other languages, optional arguments are expressed in the way that is
17668 natural for that language. We refer you to the language-specific
17669 documentation for more details on that.
17670 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17672
17674 SETTING CALLBACKS TO HANDLE EVENTS
17675 Note: This section documents the generic event mechanism introduced in
17676 libguestfs 1.10, which you should use in new code if possible. The old
17677 functions "guestfs_set_log_message_callback",
17678 "guestfs_set_subprocess_quit_callback",
17679 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17680 "guestfs_set_progress_callback" are no longer documented in this manual
17681 page. Because of the ABI guarantee, the old functions continue to
17682 work.
17683 Handles generate events when certain things happen, such as log
17685 messages being generated, progress messages during long-running
17686 operations, or the handle being closed. The API calls described below
17687 let you register a callback to be called when events happen. You can
17688 register multiple callbacks (for the same, different or overlapping
17689 sets of events), and individually remove callbacks. If callbacks are
17690 not removed, then they remain in force until the handle is closed.
17691 In the current implementation, events are only generated synchronously:
17693 that means that events (and hence callbacks) can only happen while you
17694 are in the middle of making another libguestfs call. The callback is
17695 called in the same thread.
17696 Events may contain a payload, usually nothing (void), an array of 64
17698 bit unsigned integers, or a message buffer. Payloads are discussed
17699 later on.
17700 CLASSES OF EVENTS
17702 GUESTFS_EVENT_CLOSE (payload type: void)
17703 The callback function will be called while the handle is being
17704 closed (synchronously from "guestfs_close").
17705 Note that libguestfs installs an atexit(3) handler to try to clean
17707 up handles that are open when the program exits. This means that
17708 this callback might be called indirectly from exit(3), which can
17709 cause unexpected problems in higher-level languages (eg. if your
17710 HLL interpreter has already been cleaned up by the time this is
17711 called, and if your callback then jumps into some HLL function).
17712 If no callback is registered: the handle is closed without any
17714 callback being invoked.
17715 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17717 The callback function will be called when the child process quits,
17718 either asynchronously or if killed by "guestfs_kill_subprocess".
17719 (This corresponds to a transition from any state to the CONFIG
17720 state).
17721 If no callback is registered: the event is ignored.
17723 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17725 The callback function will be called when the child process becomes
17726 ready first time after it has been launched. (This corresponds to
17727 a transition from LAUNCHING to the READY state).
17728 If no callback is registered: the event is ignored.
17730 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17732 Some long-running operations can generate progress messages. If
17733 this callback is registered, then it will be called each time a
17734 progress message is generated (usually two seconds after the
17735 operation started, and three times per second thereafter until it
17736 completes, although the frequency may change in future versions).
17737 The callback receives in the payload four unsigned 64 bit numbers
17739 which are (in order): "proc_nr", "serial", "position", "total".
17740 The units of "total" are not defined, although for some operations
17742 "total" may relate in some way to the amount of data to be
17743 transferred (eg. in bytes or megabytes), and "position" may be the
17744 portion which has been transferred.
17745 The only defined and stable parts of the API are:
17747 · The callback can display to the user some type of progress bar
17749 or indicator which shows the ratio of "position":"total".
17750 · 0 <= "position" <= "total"
17752 · If any progress notification is sent during a call, then a
17754 final progress notification is always sent when "position" =
17755 "total" (unless the call fails with an error).
17756 This is to simplify caller code, so callers can easily set the
17758 progress indicator to "100%" at the end of the operation,
17759 without requiring special code to detect this case.
17760 · For some calls we are unable to estimate the progress of the
17762 call, but we can still generate progress messages to indicate
17763 activity. This is known as "pulse mode", and is directly
17764 supported by certain progress bar implementations (eg.
17765 GtkProgressBar).
17766 For these calls, zero or more progress messages are generated
17768 with "position = 0" and "total = 1", followed by a final
17769 message with "position = total = 1".
17770 As noted above, if the call fails with an error then the final
17772 message may not be generated.
17773 The callback also receives the procedure number ("proc_nr") and
17775 serial number ("serial") of the call. These are only useful for
17776 debugging protocol issues, and the callback can normally ignore
17777 them. The callback may want to print these numbers in error
17778 messages or debugging messages.
17779 If no callback is registered: progress messages are discarded.
17781 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17783 The callback function is called whenever a log message is generated
17784 by qemu, the appliance kernel, guestfsd (daemon), or utility
17785 programs.
17786 If the verbose flag ("guestfs_set_verbose") is set before launch
17788 ("guestfs_launch") then additional debug messages are generated.
17789 If no callback is registered: the messages are discarded unless the
17791 verbose flag is set in which case they are sent to stderr. You can
17792 override the printing of verbose messages to stderr by setting up a
17793 callback.
17794 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17796 The callback function is called whenever a log message is generated
17797 by the library part of libguestfs.
17798 If the verbose flag ("guestfs_set_verbose") is set then additional
17800 debug messages are generated.
17801 If no callback is registered: the messages are discarded unless the
17803 verbose flag is set in which case they are sent to stderr. You can
17804 override the printing of verbose messages to stderr by setting up a
17805 callback.
17806 GUESTFS_EVENT_WARNING (payload type: message buffer)
17808 The callback function is called whenever a warning message is
17809 generated by the library part of libguestfs.
17810 If no callback is registered: the messages are printed to stderr.
17812 You can override the printing of warning messages to stderr by
17813 setting up a callback.
17814 GUESTFS_EVENT_TRACE (payload type: message buffer)
17816 The callback function is called whenever a trace message is
17817 generated. This only applies if the trace flag
17818 ("guestfs_set_trace") is set.
17819 If no callback is registered: the messages are sent to stderr. You
17821 can override the printing of trace messages to stderr by setting up
17822 a callback.
17823 GUESTFS_EVENT_ENTER (payload type: function name)
17825 The callback function is called whenever a libguestfs function is
17826 entered.
17827 The payload is a string which contains the name of the function
17829 that we are entering (not including "guestfs_" prefix).
17830 Note that libguestfs functions can call themselves, so you may see
17832 many events from a single call. A few libguestfs functions do not
17833 generate this event.
17834 If no callback is registered: the event is ignored.
17836 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17838 For any API function that opens a libvirt connection, this event
17839 may be generated to indicate that libvirt demands authentication
17840 information. See "LIBVIRT AUTHENTICATION" below.
17841 If no callback is registered: "virConnectAuthPtrDefault" is used
17843 (suitable for command-line programs only).
17844 EVENT API
17846 guestfs_set_event_callback
17847 int guestfs_set_event_callback (guestfs_h *g,
17849 guestfs_event_callback cb,
17850 uint64_t event_bitmask,
17851 int flags,
17852 void *opaque);
17853 This function registers a callback ("cb") for all event classes in the
17855 "event_bitmask".
17856 For example, to register for all log message events, you could call
17858 this function with the bitmask
17859 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17860 To register a single callback for all possible classes of events, use
17861 "GUESTFS_EVENT_ALL".
17862 "flags" should always be passed as 0.
17864 "opaque" is an opaque pointer which is passed to the callback. You can
17866 use it for any purpose.
17867 The return value is the event handle (an integer) which you can use to
17869 delete the callback (see below).
17870 If there is an error, this function returns "-1", and sets the error in
17872 the handle in the usual way (see "guestfs_last_error" etc.)
17873 Callbacks remain in effect until they are deleted, or until the handle
17875 is closed.
17876 In the case where multiple callbacks are registered for a particular
17878 event class, all of the callbacks are called. The order in which
17879 multiple callbacks are called is not defined.
17880 guestfs_delete_event_callback
17882 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
17884 Delete a callback that was previously registered. "event_handle"
17886 should be the integer that was returned by a previous call to
17887 "guestfs_set_event_callback" on the same handle.
17888 guestfs_event_to_string
17890 char *guestfs_event_to_string (uint64_t event);
17892 "event" is either a single event or a bitmask of events. This returns
17894 a string representation (useful for debugging or printing events).
17895 A single event is returned as the name in lower case, eg. "close".
17897 A bitmask of several events is returned as a comma-separated list, eg.
17899 "close,progress".
17900 If zero is passed, then the empty string "" is returned.
17902 On success this returns a string. On error it returns NULL and sets
17904 "errno".
17905 The returned string must be freed by the caller.
17907 guestfs_event_callback
17909 typedef void (*guestfs_event_callback) (
17911 guestfs_h *g,
17912 void *opaque,
17913 uint64_t event,
17914 int event_handle,
17915 int flags,
17916 const char *buf, size_t buf_len,
17917 const uint64_t *array, size_t array_len);
17918 This is the type of the event callback function that you have to
17920 provide.
17921 The basic parameters are: the handle ("g"), the opaque user pointer
17923 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
17924 handle, and "flags" which in the current API you should ignore.
17925 The remaining parameters contain the event payload (if any). Each
17927 event may contain a payload, which usually relates to the event class,
17928 but for future proofing your code should be written to handle any
17929 payload for any event class.
17930 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
17932 there is no message buffer). Note that this message buffer can contain
17933 arbitrary 8 bit data, including NUL bytes.
17934 "array" and "array_len" is an array of 64 bit unsigned integers. At
17936 the moment this is only used for progress messages.
17937 EXAMPLE: CAPTURING LOG MESSAGES
17939 A working program demonstrating this can be found in
17940 examples/debug-logging.c in the source of libguestfs.
17941 One motivation for the generic event API was to allow GUI programs to
17943 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
17944 unconditionally to "stderr".
17945 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
17947 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
17948 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
17949 must capture error messages separately).
17950 Programs have to set up a callback to capture the classes of events of
17952 interest:
17953 int eh =
17955 guestfs_set_event_callback
17956 (g, message_callback,
17957 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
17958 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
17959 0, NULL) == -1)
17960 if (eh == -1) {
17961 // handle error in the usual way
17962 }
17963 The callback can then direct messages to the appropriate place. In
17965 this example, messages are directed to syslog:
17966 static void
17968 message_callback (
17969 guestfs_h *g,
17970 void *opaque,
17971 uint64_t event,
17972 int event_handle,
17973 int flags,
17974 const char *buf, size_t buf_len,
17975 const uint64_t *array, size_t array_len)
17976 {
17977 const int priority = LOG_USER|LOG_INFO;
17978 if (buf_len > 0)
17979 syslog (priority, "event 0x%lx: %s", event, buf);
17980 }
17981 LIBVIRT AUTHENTICATION
17983 Some libguestfs API calls can open libvirt connections. Currently the
17984 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
17985 backend has been selected. Libvirt connections may require
17986 authentication, for example if they need to access a remote server or
17987 to access root services from non-root. Libvirt authentication happens
17988 via a callback mechanism, see
17989 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
17990 You may provide libvirt authentication data by registering a callback
17992 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
17993 If no such event is registered, then libguestfs uses a libvirt function
17995 that provides command-line prompts ("virConnectAuthPtrDefault"). This
17996 is only suitable for command-line libguestfs programs.
17997 To provide authentication, first call
17999 "guestfs_set_libvirt_supported_credentials" with the list of
18000 credentials your program knows how to provide. Second, register a
18001 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
18002 will be called when libvirt is requesting authentication information.
18003 In the event handler, call "guestfs_get_libvirt_requested_credentials"
18005 to get a list of the credentials that libvirt is asking for. You then
18006 need to ask (eg. the user) for each credential, and call
18007 "guestfs_set_libvirt_requested_credential" with the answer. Note that
18008 for each credential, additional information may be available via the
18009 calls "guestfs_get_libvirt_requested_credential_prompt",
18010 "guestfs_get_libvirt_requested_credential_challenge" or
18011 "guestfs_get_libvirt_requested_credential_defresult".
18012 The example program below should make this clearer.
18014 There is also a more substantial working example program supplied with
18016 the libguestfs sources, called libvirt-auth.c.
18017 main ()
18019 {
18020 guestfs_h *g;
18021 char *creds[] = { "authname", "passphrase", NULL };
18022 int r, eh;
18023 g = guestfs_create ();
18025 if (!g) exit (EXIT_FAILURE);
18026 /* Tell libvirt what credentials the program supports. */
18028 r = guestfs_set_libvirt_supported_credentials (g, creds);
18029 if (r == -1)
18030 exit (EXIT_FAILURE);
18031 /* Set up the event handler. */
18033 eh = guestfs_set_event_callback (
18034 g, do_auth,
18035 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
18036 if (eh == -1)
18037 exit (EXIT_FAILURE);
18038 /* An example of a call that may ask for credentials. */
18040 r = guestfs_add_domain (
18041 g, "dom",
18042 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
18043 -1);
18044 if (r == -1)
18045 exit (EXIT_FAILURE);
18046 exit (EXIT_SUCCESS);
18048 }
18049 static void
18051 do_auth (guestfs_h *g,
18052 void *opaque,
18053 uint64_t event,
18054 int event_handle,
18055 int flags,
18056 const char *buf, size_t buf_len,
18057 const uint64_t *array, size_t array_len)
18058 {
18059 char **creds;
18060 size_t i;
18061 char *prompt;
18062 char *reply;
18063 size_t replylen;
18064 int r;
18065 // buf will be the libvirt URI. buf_len may be ignored.
18067 printf ("Authentication required for libvirt conn '%s'\n",
18068 buf);
18069 // Ask libguestfs what credentials libvirt is demanding.
18071 creds = guestfs_get_libvirt_requested_credentials (g);
18072 if (creds == NULL)
18073 exit (EXIT_FAILURE);
18074 // Now ask the user for answers.
18076 for (i = 0; creds[i] != NULL; ++i)
18077 {
18078 if (strcmp (creds[i], "authname") == 0 ||
18079 strcmp (creds[i], "passphrase") == 0)
18080 {
18081 prompt =
18082 guestfs_get_libvirt_requested_credential_prompt (g, i);
18083 if (prompt && strcmp (prompt, "") != 0)
18084 printf ("%s: ", prompt);
18085 free (prompt);
18086 // Some code here to ask for the credential.
18088 // ...
18089 // Put the reply in 'reply', length 'replylen' (bytes).
18090 r = guestfs_set_libvirt_requested_credential (g, i,
18092 reply, replylen);
18093 if (r == -1)
18094 exit (EXIT_FAILURE);
18095 }
18096 free (creds[i]);
18098 }
18099 free (creds);
18101 }
18102
18104 Some operations can be cancelled by the caller while they are in
18105 progress. Currently only operations that involve uploading or
18106 downloading data can be cancelled (technically: operations that have
18107 "FileIn" or "FileOut" parameters in the generator).
18108 To cancel the transfer, call "guestfs_user_cancel". For more
18110 information, read the description of "guestfs_user_cancel".
18111
18113 You can attach named pieces of private data to the libguestfs handle,
18114 fetch them by name, and walk over them, for the lifetime of the handle.
18115 This is called the private data area and is only available from the C
18116 API.
18117 To attach a named piece of data, use the following call:
18119 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18121 "key" is the name to associate with this data, and "data" is an
18123 arbitrary pointer (which can be "NULL"). Any previous item with the
18124 same key is overwritten.
18125 You can use any "key" string you want, but avoid keys beginning with an
18127 underscore character (libguestfs uses those for its own internal
18128 purposes, such as implementing language bindings). It is recommended
18129 that you prefix the key with some unique string to avoid collisions
18130 with other users.
18131 To retrieve the pointer, use:
18133 void *guestfs_get_private (guestfs_h *g, const char *key);
18135 This function returns "NULL" if either no data is found associated with
18137 "key", or if the user previously set the "key"’s "data" pointer to
18138 "NULL".
18139 Libguestfs does not try to look at or interpret the "data" pointer in
18141 any way. As far as libguestfs is concerned, it need not be a valid
18142 pointer at all. In particular, libguestfs does not try to free the
18143 data when the handle is closed. If the data must be freed, then the
18144 caller must either free it before calling "guestfs_close" or must set
18145 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18146 To walk over all entries, use these two functions:
18148 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18150 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18152 "guestfs_first_private" returns the first key, pointer pair ("first"
18154 does not have any particular meaning -- keys are not returned in any
18155 defined order). A pointer to the key is returned in *key_rtn and the
18156 corresponding data pointer is returned from the function. "NULL" is
18157 returned if there are no keys stored in the handle.
18158 "guestfs_next_private" returns the next key, pointer pair. The return
18160 value of this function is "NULL" if there are no further entries to
18161 return.
18162 Notes about walking over entries:
18164 · You must not call "guestfs_set_private" while walking over the
18166 entries.
18167 · The handle maintains an internal iterator which is reset when you
18169 call "guestfs_first_private". This internal iterator is
18170 invalidated when you call "guestfs_set_private".
18171 · If you have set the data pointer associated with a key to "NULL",
18173 ie:
18174 guestfs_set_private (g, key, NULL);
18176 then that "key" is not returned when walking.
18178 · *key_rtn is only valid until the next call to
18180 "guestfs_first_private", "guestfs_next_private" or
18181 "guestfs_set_private".
18182 The following example code shows how to print all keys and data
18184 pointers that are associated with the handle "g":
18185 const char *key;
18187 void *data = guestfs_first_private (g, &key);
18188 while (data != NULL)
18189 {
18190 printf ("key = %s, data = %p\n", key, data);
18191 data = guestfs_next_private (g, &key);
18192 }
18193 More commonly you are only interested in keys that begin with an
18195 application-specific prefix "foo_". Modify the loop like so:
18196 const char *key;
18198 void *data = guestfs_first_private (g, &key);
18199 while (data != NULL)
18200 {
18201 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18202 printf ("key = %s, data = %p\n", key, data);
18203 data = guestfs_next_private (g, &key);
18204 }
18205 If you need to modify keys while walking, then you have to jump back to
18207 the beginning of the loop. For example, to delete all keys prefixed
18208 with "foo_":
18209 const char *key;
18211 void *data;
18212 again:
18213 data = guestfs_first_private (g, &key);
18214 while (data != NULL)
18215 {
18216 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18217 {
18218 guestfs_set_private (g, key, NULL);
18219 /* note that 'key' pointer is now invalid, and so is
18220 the internal iterator */
18221 goto again;
18222 }
18223 data = guestfs_next_private (g, &key);
18224 }
18225 Note that the above loop is guaranteed to terminate because the keys
18227 are being deleted, but other manipulations of keys within the loop
18228 might not terminate unless you also maintain an indication of which
18229 keys have been visited.
18230
18232 The libguestfs C library can be probed using systemtap or DTrace. This
18233 is true of any library, not just libguestfs. However libguestfs also
18234 contains static markers to help in probing internal operations.
18235 You can list all the static markers by doing:
18237 stap -l 'process("/usr/lib*/libguestfs.so.0")
18239 .provider("guestfs").mark("*")'
18240 Note: These static markers are not part of the stable API and may
18242 change in future versions.
18243 SYSTEMTAP SCRIPT EXAMPLE
18245 This script contains examples of displaying both the static markers and
18246 some ordinary C entry points:
18247 global last;
18249 function display_time () {
18251 now = gettimeofday_us ();
18252 delta = 0;
18253 if (last > 0)
18254 delta = now - last;
18255 last = now;
18256 printf ("%d (+%d):", now, delta);
18258 }
18259 probe begin {
18261 last = 0;
18262 printf ("ready\n");
18263 }
18264 /* Display all calls to static markers. */
18266 probe process("/usr/lib*/libguestfs.so.0")
18267 .provider("guestfs").mark("*") ? {
18268 display_time();
18269 printf ("\t%s %s\n", $$name, $$parms);
18270 }
18271 /* Display all calls to guestfs_mkfs* functions. */
18273 probe process("/usr/lib*/libguestfs.so.0")
18274 .function("guestfs_mkfs*") ? {
18275 display_time();
18276 printf ("\t%s %s\n", probefunc(), $$parms);
18277 }
18278 The script above can be saved to test.stap and run using the stap(1)
18280 program. Note that you either have to be root, or you have to add
18281 yourself to several special stap groups. Consult the systemtap
18282 documentation for more information.
18283 # stap /tmp/test.stap
18285 ready
18286 In another terminal, run a guestfish command such as this:
18288 guestfish -N fs
18290 In the first terminal, stap trace output similar to this is shown:
18292 1318248056692655 (+0): launch_start
18294 1318248056692850 (+195): launch_build_appliance_start
18295 1318248056818285 (+125435): launch_build_appliance_end
18296 1318248056838059 (+19774): launch_run_qemu
18297 1318248061071167 (+4233108): launch_end
18298 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
18299
18301 Since April 2010, libguestfs has started to make separate development
18302 and stable releases, along with corresponding branches in our git
18303 repository. These separate releases can be identified by version
18304 number:
18305 even numbers for stable: 1.2.x, 1.4.x, ...
18307 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18308 |
18309 v
18310 1 . 3 . 5
18311 ^ ^
18312 | |
18313 | `-------- sub-version
18314 |
18315 `------ always '1' because we don't change the ABI
18316 Thus "1.3.5" is the 5th update to the development branch "1.3".
18318 As time passes we cherry pick fixes from the development branch and
18320 backport those into the stable branch, the effect being that the stable
18321 branch should get more stable and less buggy over time. So the stable
18322 releases are ideal for people who don't need new features but would
18323 just like the software to work.
18324 Our criteria for backporting changes are:
18326 · Documentation changes which don’t affect any code are backported
18328 unless the documentation refers to a future feature which is not in
18329 stable.
18330 · Bug fixes which are not controversial, fix obvious problems, and
18332 have been well tested are backported.
18333 · Simple rearrangements of code which shouldn't affect how it works
18335 get backported. This is so that the code in the two branches
18336 doesn't get too far out of step, allowing us to backport future
18337 fixes more easily.
18338 · We don’t backport new features, new APIs, new tools etc, except in
18340 one exceptional case: the new feature is required in order to
18341 implement an important bug fix.
18342 A new stable branch starts when we think the new features in
18344 development are substantial and compelling enough over the current
18345 stable branch to warrant it. When that happens we create new stable
18346 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18347 oh release won't necessarily be so stable at this point, but by
18348 backporting fixes from development, that branch will stabilize over
18349 time.
18350
18352 PROTOCOL LIMITS
18353 Internally libguestfs uses a message-based protocol to pass API calls
18354 and their responses to and from a small "appliance" (see
18355 guestfs-internals(1) for plenty more detail about this). The maximum
18356 message size used by the protocol is slightly less than 4 MB. For some
18357 API calls you may need to be aware of this limit. The API calls which
18358 may be affected are individually documented, with a link back to this
18359 section of the documentation.
18360 In libguestfs < 1.19.32, several calls had to encode either their
18362 entire argument list or their entire return value (or sometimes both)
18363 in a single protocol message, and this gave them an arbitrary
18364 limitation on how much data they could handle. For example,
18365 "guestfs_cat" could only download a file if it was less than around 4
18366 MB in size. In later versions of libguestfs, some of these limits have
18367 been removed. The APIs which were previously limited but are now
18368 unlimited (except perhaps by available memory) are listed below. To
18369 find out if a specific API is subject to protocol limits, check for the
18370 warning in the API documentation which links to this section, and
18371 remember to check the version of the documentation that matches the
18372 version of libguestfs you are using.
18373 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18375 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18376 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18377 "guestfs_ls".
18378 See also "UPLOADING" and "DOWNLOADING" for further information about
18380 copying large amounts of data into or out of a filesystem.
18381 MAXIMUM NUMBER OF DISKS
18383 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18384 may be added by calling "guestfs_max_disks". In earlier versions of
18385 libguestfs (ie. where this call is not available) you should assume the
18386 maximum is 25.
18387 The rest of this section covers implementation details, which could
18389 change in future.
18390 When using virtio-scsi disks (the default if available in qemu) the
18392 current limit is 255 disks. When using virtio-blk (the old default)
18393 the limit is around 27 disks, but may vary according to implementation
18394 details and whether the network is enabled.
18395 Virtio-scsi as used by libguestfs is configured to use one target per
18397 disk, and 256 targets are available.
18398 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18400 31 slots, but some of these are used for other purposes.
18401 One virtual disk is used by libguestfs internally.
18403 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18405 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18406 the limit was 25. This has been fixed in more recent versions.
18407 In libguestfs ≥ 1.20 it is possible to hot plug disks. See
18409 "HOTPLUGGING".
18410 MAXIMUM NUMBER OF PARTITIONS PER DISK
18412 Virtio limits the maximum number of partitions per disk to 15.
18413 This is because it reserves 4 bits for the minor device number (thus
18415 /dev/vda, and /dev/vda1 through /dev/vda15).
18416 If you attach a disk with more than 15 partitions, the extra partitions
18418 are ignored by libguestfs.
18419 MAXIMUM SIZE OF A DISK
18421 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18422 We have tested block devices up to 1 exabyte (2**60 or
18424 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18425 host filesystem.
18426 Although libguestfs probably does not impose any limit, the underlying
18428 host storage will. If you store disk images on a host ext4 filesystem,
18429 then the maximum size will be limited by the maximum ext4 file size
18430 (currently 16 TB). If you store disk images as host logical volumes
18431 then you are limited by the maximum size of an LV.
18432 For the hugest disk image files, we recommend using XFS on the host for
18434 storage.
18435 MAXIMUM SIZE OF A PARTITION
18437 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18438 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18439 address a partition located beyond 2 TB on the disk.
18440 It is recommended that you use GPT partitions on disks which are larger
18442 than this size. GPT uses 64 bit sector numbers and so can address
18443 partitions which are theoretically larger than the largest disk we
18444 could support.
18445 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18447 This depends on the filesystem type. libguestfs itself does not impose
18448 any known limit. Consult Wikipedia or the filesystem documentation to
18449 find out what these limits are.
18450 MAXIMUM UPLOAD AND DOWNLOAD
18452 The API functions "guestfs_upload", "guestfs_download",
18453 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18454 uploads and downloads.
18455 INSPECTION LIMITS
18457 The inspection code has several arbitrary limits on things like the
18458 size of Windows Registry hive it will read, and the length of product
18459 name. These are intended to stop a malicious guest from consuming
18460 arbitrary amounts of memory and disk space on the host, and should not
18461 be reached in practice. See the source code for more information.
18462
18464 Some of the tools support a --machine-readable option, which is
18465 generally used to make the output more machine friendly, for easier
18466 parsing for example. By default, this output goes to stdout.
18467 When using the --machine-readable option, the progress, information,
18469 warning, and error messages are also printed in JSON format for easier
18470 log tracking. Thus, it is highly recommended to redirect the machine-
18471 readable output to a different stream. The format of these JSON
18472 messages is like the following (actually printed within a single line,
18473 below it is indented for readability):
18474 {
18476 "message": "Finishing off",
18477 "timestamp": "2019-03-22T14:46:49.067294446+01:00",
18478 "type": "message"
18479 }
18480 "type" can be: "message" for progress messages, "info" for information
18482 messages, "warning" for warning messages, and "error" for error
18483 message. "timestamp" is the RFC 3339 timestamp of the message.
18484 In addition to that, a subset of these tools support an extra string
18486 passed to the --machine-readable option: this string specifies where
18487 the machine-readable output will go.
18488 The possible values are:
18490 fd:fd
18492 The output goes to the specified fd, which is a file descriptor
18493 already opened for writing.
18494 file:filename
18496 The output goes to the specified filename.
18497 stream:stdout
18499 The output goes to stdout. This is basically the same as the
18500 default behaviour of --machine-readable with no parameter, although
18501 stdout as output is specified explicitly.
18502 stream:stderr
18504 The output goes to stderr.
18505
18507 LIBGUESTFS_APPEND
18508 Pass additional options to the guest kernel.
18509 LIBGUESTFS_ATTACH_METHOD
18511 This is the old way to set "LIBGUESTFS_BACKEND".
18512 LIBGUESTFS_BACKEND
18514 Choose the default way to create the appliance. See
18515 "guestfs_set_backend" and "BACKEND".
18516 LIBGUESTFS_BACKEND_SETTINGS
18518 A colon-separated list of backend-specific settings. See
18519 "BACKEND", "BACKEND SETTINGS".
18520 LIBGUESTFS_CACHEDIR
18522 The location where libguestfs will cache its appliance, when using
18523 a supermin appliance. The appliance is cached and shared between
18524 all handles which have the same effective user ID.
18525 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18527 "TMPDIR" is not set, then /var/tmp is used.
18528 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18530 LIBGUESTFS_DEBUG
18532 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18533 same effect as calling "guestfs_set_verbose (g, 1)".
18534 LIBGUESTFS_HV
18536 Set the default hypervisor (usually qemu) binary that libguestfs
18537 uses. If not set, then the qemu which was found at compile time by
18538 the configure script is used.
18539 See also "QEMU WRAPPERS" above.
18541 LIBGUESTFS_MEMSIZE
18543 Set the memory allocated to the qemu process, in megabytes. For
18544 example:
18545 LIBGUESTFS_MEMSIZE=700
18547 LIBGUESTFS_PATH
18549 Set the path that libguestfs uses to search for a supermin
18550 appliance. See the discussion of paths in section "PATH" above.
18551 LIBGUESTFS_QEMU
18553 This is the old way to set "LIBGUESTFS_HV".
18554 LIBGUESTFS_TMPDIR
18556 The location where libguestfs will store temporary files used by
18557 each handle.
18558 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18560 "TMPDIR" is not set, then /tmp is used.
18561 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18563 LIBGUESTFS_TRACE
18565 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18566 same effect as calling "guestfs_set_trace (g, 1)".
18567 PATH
18569 Libguestfs may run some external programs, and relies on $PATH
18570 being set to a reasonable value. If using the libvirt backend,
18571 libvirt will not work at all unless $PATH contains the path of
18572 qemu/KVM. Note that PHP by default removes $PATH from the
18573 environment which tends to break everything.
18574 SUPERMIN_KERNEL
18576 SUPERMIN_KERNEL_VERSION
18577 SUPERMIN_MODULES
18578 These three environment variables allow the kernel that libguestfs
18579 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18580 set, then the most recent host kernel is chosen. For more
18581 information about kernel selection, see supermin(1).
18582 TMPDIR
18584 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18585 XDG_RUNTIME_DIR
18587 This directory represents a user-specific directory for storing
18588 non-essential runtime files.
18589 If it is set, then is used to store temporary sockets. Otherwise,
18591 /tmp is used.
18592 See also "get-sockdir",
18594 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18595
18597 Examples written in C: guestfs-examples(3).
18598 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18600 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18601 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18602 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18604 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18605 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18606 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18607 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18608 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18609 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18610 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18611 virt-win-reg(1).
18612 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18614 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18615 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18616 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18617 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18619 sd-journal(3).
18620 Website: http://libguestfs.org/
18622 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18624 disktype(1).
18625
18627 Richard W.M. Jones ("rjones at redhat dot com")
18628
18630 Copyright (C) 2009-2020 Red Hat Inc.
18631
18633 This library is free software; you can redistribute it and/or modify it
18634 under the terms of the GNU Lesser General Public License as published
18635 by the Free Software Foundation; either version 2 of the License, or
18636 (at your option) any later version.
18637 This library is distributed in the hope that it will be useful, but
18639 WITHOUT ANY WARRANTY; without even the implied warranty of
18640 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18641 Lesser General Public License for more details.
18642 You should have received a copy of the GNU Lesser General Public
18644 License along with this library; if not, write to the Free Software
18645 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18646 02110-1301 USA
18647
18649 To get a list of bugs against libguestfs, use this link:
18650 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18651 To report a new bug against libguestfs, use this link:
18653 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18654 When reporting a bug, please supply:
18656 · The version of libguestfs.
18658 · Where you got libguestfs (eg. which Linux distro, compiled from
18660 source, etc)
18661 · Describe the bug accurately and give a way to reproduce it.
18663 · Run libguestfs-test-tool(1) and paste the complete, unedited output
18665 into the bug report.
18666libguestfs-1.42.0 2020-03-09 guestfs(3)