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 http://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 http://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 The other optional parameters are passed directly through to
2101 "guestfs_add_drive_opts".
2102 On error this function returns -1.
2104 (Added in 1.7.4)
2106 guestfs_add_domain_va
2108 int
2109 guestfs_add_domain_va (guestfs_h *g,
2110 const char *dom,
2111 va_list args);
2112 This is the "va_list variant" of "guestfs_add_domain".
2114 See "CALLS WITH OPTIONAL ARGUMENTS".
2116 guestfs_add_domain_argv
2118 int
2119 guestfs_add_domain_argv (guestfs_h *g,
2120 const char *dom,
2121 const struct guestfs_add_domain_argv *optargs);
2122 This is the "argv variant" of "guestfs_add_domain".
2124 See "CALLS WITH OPTIONAL ARGUMENTS".
2126 guestfs_add_drive
2128 int
2129 guestfs_add_drive (guestfs_h *g,
2130 const char *filename);
2131 This function is provided for backwards compatibility with earlier
2133 versions of libguestfs. It simply calls "guestfs_add_drive_opts" with
2134 no optional arguments.
2135 (Added in 0.3)
2137 guestfs_add_drive_opts
2139 int
2140 guestfs_add_drive_opts (guestfs_h *g,
2141 const char *filename,
2142 ...);
2143 You may supply a list of optional arguments to this call. Use zero or
2145 more of the following pairs of parameters, and terminate the list with
2146 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2147 GUESTFS_ADD_DRIVE_OPTS_READONLY, int readonly,
2149 GUESTFS_ADD_DRIVE_OPTS_FORMAT, const char *format,
2150 GUESTFS_ADD_DRIVE_OPTS_IFACE, const char *iface,
2151 GUESTFS_ADD_DRIVE_OPTS_NAME, const char *name,
2152 GUESTFS_ADD_DRIVE_OPTS_LABEL, const char *label,
2153 GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, const char *protocol,
2154 GUESTFS_ADD_DRIVE_OPTS_SERVER, char *const *server,
2155 GUESTFS_ADD_DRIVE_OPTS_USERNAME, const char *username,
2156 GUESTFS_ADD_DRIVE_OPTS_SECRET, const char *secret,
2157 GUESTFS_ADD_DRIVE_OPTS_CACHEMODE, const char *cachemode,
2158 GUESTFS_ADD_DRIVE_OPTS_DISCARD, const char *discard,
2159 GUESTFS_ADD_DRIVE_OPTS_COPYONREAD, int copyonread,
2160 This function adds a disk image called filename to the handle.
2162 filename may be a regular host file or a host device.
2163 When this function is called before "guestfs_launch" (the usual case)
2165 then the first time you call this function, the disk appears in the API
2166 as /dev/sda, the second time as /dev/sdb, and so on.
2167 In libguestfs ≥ 1.20 you can also call this function after launch (with
2169 some restrictions). This is called "hotplugging". When hotplugging,
2170 you must specify a "label" so that the new disk gets a predictable
2171 name. For more information see "HOTPLUGGING".
2172 You don't necessarily need to be root when using libguestfs. However
2174 you obviously do need sufficient permissions to access the filename for
2175 whatever operations you want to perform (ie. read access if you just
2176 want to read the image or write access if you want to modify the
2177 image).
2178 This call checks that filename exists.
2180 filename may be the special string "/dev/null". See "NULL DISKS".
2182 The optional arguments are:
2184 "readonly"
2186 If true then the image is treated as read-only. Writes are still
2187 allowed, but they are stored in a temporary snapshot overlay which
2188 is discarded at the end. The disk that you add is not modified.
2189 "format"
2191 This forces the image format. If you omit this (or use
2192 "guestfs_add_drive" or "guestfs_add_drive_ro") then the format is
2193 automatically detected. Possible formats include "raw" and
2194 "qcow2".
2195 Automatic detection of the format opens you up to a potential
2197 security hole when dealing with untrusted raw-format images. See
2198 CVE-2010-3851 and RHBZ#642934. Specifying the format closes this
2199 security hole.
2200 "iface"
2202 This rarely-used option lets you emulate the behaviour of the
2203 deprecated "guestfs_add_drive_with_if" call (q.v.)
2204 "name"
2206 The name the drive had in the original guest, e.g. /dev/sdb. This
2207 is used as a hint to the guest inspection process if it is
2208 available.
2209 "label"
2211 Give the disk a label. The label should be a unique, short string
2212 using only ASCII characters "[a-zA-Z]". As well as its usual name
2213 in the API (such as /dev/sda), the drive will also be named
2214 /dev/disk/guestfs/label.
2215 See "DISK LABELS".
2217 "protocol"
2219 The optional protocol argument can be used to select an alternate
2220 source protocol.
2221 See also: "REMOTE STORAGE".
2223 "protocol = "file""
2225 filename is interpreted as a local file or device. This is the
2226 default if the optional protocol parameter is omitted.
2227 "protocol = "ftp"|"ftps"|"http"|"https"|"tftp""
2229 Connect to a remote FTP, HTTP or TFTP server. The "server"
2230 parameter must also be supplied - see below.
2231 See also: "FTP, HTTP AND TFTP"
2233 "protocol = "gluster""
2235 Connect to the GlusterFS server. The "server" parameter must
2236 also be supplied - see below.
2237 See also: "GLUSTER"
2239 "protocol = "iscsi""
2241 Connect to the iSCSI server. The "server" parameter must also
2242 be supplied - see below. The "username" parameter may be
2243 supplied. See below. The "secret" parameter may be supplied.
2244 See below.
2245 See also: "ISCSI".
2247 "protocol = "nbd""
2249 Connect to the Network Block Device server. The "server"
2250 parameter must also be supplied - see below.
2251 See also: "NETWORK BLOCK DEVICE".
2253 "protocol = "rbd""
2255 Connect to the Ceph (librbd/RBD) server. The "server"
2256 parameter must also be supplied - see below. The "username"
2257 parameter may be supplied. See below. The "secret" parameter
2258 may be supplied. See below.
2259 See also: "CEPH".
2261 "protocol = "sheepdog""
2263 Connect to the Sheepdog server. The "server" parameter may
2264 also be supplied - see below.
2265 See also: "SHEEPDOG".
2267 "protocol = "ssh""
2269 Connect to the Secure Shell (ssh) server.
2270 The "server" parameter must be supplied. The "username"
2272 parameter may be supplied. See below.
2273 See also: "SSH".
2275 "server"
2277 For protocols which require access to a remote server, this is a
2278 list of server(s).
2279 Protocol Number of servers required
2281 -------- --------------------------
2282 file List must be empty or param not used at all
2283 ftp|ftps|http|https|tftp Exactly one
2284 gluster Exactly one
2285 iscsi Exactly one
2286 nbd Exactly one
2287 rbd Zero or more
2288 sheepdog Zero or more
2289 ssh Exactly one
2290 Each list element is a string specifying a server. The string must
2292 be in one of the following formats:
2293 hostname
2295 hostname:port
2296 tcp:hostname
2297 tcp:hostname:port
2298 unix:/path/to/socket
2299 If the port number is omitted, then the standard port number for
2301 the protocol is used (see /etc/services).
2302 "username"
2304 For the "ftp", "ftps", "http", "https", "iscsi", "rbd", "ssh" and
2305 "tftp" protocols, this specifies the remote username.
2306 If not given, then the local username is used for "ssh", and no
2308 authentication is attempted for ceph. But note this sometimes may
2309 give unexpected results, for example if using the libvirt backend
2310 and if the libvirt backend is configured to start the qemu
2311 appliance as a special user such as "qemu.qemu". If in doubt,
2312 specify the remote username you want.
2313 "secret"
2315 For the "rbd" protocol only, this specifies the ‘secret’ to use
2316 when connecting to the remote device. It must be base64 encoded.
2317 If not given, then a secret matching the given username will be
2319 looked up in the default keychain locations, or if no username is
2320 given, then no authentication will be used.
2321 "cachemode"
2323 Choose whether or not libguestfs will obey sync operations (safe
2324 but slow) or not (unsafe but fast). The possible values for this
2325 string are:
2326 "cachemode = "writeback""
2328 This is the default.
2329 Write operations in the API do not return until a write(2) call
2331 has completed in the host [but note this does not imply that
2332 anything gets written to disk].
2333 Sync operations in the API, including implicit syncs caused by
2335 filesystem journalling, will not return until an fdatasync(2)
2336 call has completed in the host, indicating that data has been
2337 committed to disk.
2338 "cachemode = "unsafe""
2340 In this mode, there are no guarantees. Libguestfs may cache
2341 anything and ignore sync requests. This is suitable only for
2342 scratch or temporary disks.
2343 "discard"
2345 Enable or disable discard (a.k.a. trim or unmap) support on this
2346 drive. If enabled, operations such as "guestfs_fstrim" will be
2347 able to discard / make thin / punch holes in the underlying host
2348 file or device.
2349 Possible discard settings are:
2351 "discard = "disable""
2353 Disable discard support. This is the default.
2354 "discard = "enable""
2356 Enable discard support. Fail if discard is not possible.
2357 "discard = "besteffort""
2359 Enable discard support if possible, but don't fail if it is not
2360 supported.
2361 Since not all backends and not all underlying systems support
2363 discard, this is a good choice if you want to use discard if
2364 possible, but don't mind if it doesn't work.
2365 "copyonread"
2367 The boolean parameter "copyonread" enables copy-on-read support.
2368 This only affects disk formats which have backing files, and causes
2369 reads to be stored in the overlay layer, speeding up multiple reads
2370 of the same area of disk.
2371 The default is false.
2373 This function returns 0 on success or -1 on error.
2375 (Added in 0.3)
2377 guestfs_add_drive_opts_va
2379 int
2380 guestfs_add_drive_opts_va (guestfs_h *g,
2381 const char *filename,
2382 va_list args);
2383 This is the "va_list variant" of "guestfs_add_drive_opts".
2385 See "CALLS WITH OPTIONAL ARGUMENTS".
2387 guestfs_add_drive_opts_argv
2389 int
2390 guestfs_add_drive_opts_argv (guestfs_h *g,
2391 const char *filename,
2392 const struct guestfs_add_drive_opts_argv *optargs);
2393 This is the "argv variant" of "guestfs_add_drive_opts".
2395 See "CALLS WITH OPTIONAL ARGUMENTS".
2397 guestfs_add_drive_ro
2399 int
2400 guestfs_add_drive_ro (guestfs_h *g,
2401 const char *filename);
2402 This function is the equivalent of calling "guestfs_add_drive_opts"
2404 with the optional parameter "GUESTFS_ADD_DRIVE_OPTS_READONLY" set to 1,
2405 so the disk is added read-only, with the format being detected
2406 automatically.
2407 This function returns 0 on success or -1 on error.
2409 (Added in 1.0.38)
2411 guestfs_add_drive_ro_with_if
2413 int
2414 guestfs_add_drive_ro_with_if (guestfs_h *g,
2415 const char *filename,
2416 const char *iface);
2417 This function is deprecated. In new code, use the "guestfs_add_drive"
2419 call instead.
2420 Deprecated functions will not be removed from the API, but the fact
2422 that they are deprecated indicates that there are problems with correct
2423 use of these functions.
2424 This is the same as "guestfs_add_drive_ro" but it allows you to specify
2426 the QEMU interface emulation to use at run time.
2427 This function returns 0 on success or -1 on error.
2429 (Added in 1.0.84)
2431 guestfs_add_drive_scratch
2433 int
2434 guestfs_add_drive_scratch (guestfs_h *g,
2435 int64_t size,
2436 ...);
2437 You may supply a list of optional arguments to this call. Use zero or
2439 more of the following pairs of parameters, and terminate the list with
2440 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2441 GUESTFS_ADD_DRIVE_SCRATCH_NAME, const char *name,
2443 GUESTFS_ADD_DRIVE_SCRATCH_LABEL, const char *label,
2444 This command adds a temporary scratch drive to the handle. The "size"
2446 parameter is the virtual size (in bytes). The scratch drive is blank
2447 initially (all reads return zeroes until you start writing to it). The
2448 drive is deleted when the handle is closed.
2449 The optional arguments "name" and "label" are passed through to
2451 "guestfs_add_drive".
2452 This function returns 0 on success or -1 on error.
2454 (Added in 1.23.10)
2456 guestfs_add_drive_scratch_va
2458 int
2459 guestfs_add_drive_scratch_va (guestfs_h *g,
2460 int64_t size,
2461 va_list args);
2462 This is the "va_list variant" of "guestfs_add_drive_scratch".
2464 See "CALLS WITH OPTIONAL ARGUMENTS".
2466 guestfs_add_drive_scratch_argv
2468 int
2469 guestfs_add_drive_scratch_argv (guestfs_h *g,
2470 int64_t size,
2471 const struct guestfs_add_drive_scratch_argv *optargs);
2472 This is the "argv variant" of "guestfs_add_drive_scratch".
2474 See "CALLS WITH OPTIONAL ARGUMENTS".
2476 guestfs_add_drive_with_if
2478 int
2479 guestfs_add_drive_with_if (guestfs_h *g,
2480 const char *filename,
2481 const char *iface);
2482 This function is deprecated. In new code, use the "guestfs_add_drive"
2484 call instead.
2485 Deprecated functions will not be removed from the API, but the fact
2487 that they are deprecated indicates that there are problems with correct
2488 use of these functions.
2489 This is the same as "guestfs_add_drive" but it allows you to specify
2491 the QEMU interface emulation to use at run time.
2492 This function returns 0 on success or -1 on error.
2494 (Added in 1.0.84)
2496 guestfs_add_libvirt_dom
2498 int
2499 guestfs_add_libvirt_dom (guestfs_h *g,
2500 void * /* really virDomainPtr */ dom,
2501 ...);
2502 You may supply a list of optional arguments to this call. Use zero or
2504 more of the following pairs of parameters, and terminate the list with
2505 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2506 GUESTFS_ADD_LIBVIRT_DOM_READONLY, int readonly,
2508 GUESTFS_ADD_LIBVIRT_DOM_IFACE, const char *iface,
2509 GUESTFS_ADD_LIBVIRT_DOM_LIVE, int live,
2510 GUESTFS_ADD_LIBVIRT_DOM_READONLYDISK, const char *readonlydisk,
2511 GUESTFS_ADD_LIBVIRT_DOM_CACHEMODE, const char *cachemode,
2512 GUESTFS_ADD_LIBVIRT_DOM_DISCARD, const char *discard,
2513 GUESTFS_ADD_LIBVIRT_DOM_COPYONREAD, int copyonread,
2514 This function adds the disk(s) attached to the libvirt domain "dom".
2516 It works by requesting the domain XML from libvirt, parsing it for
2517 disks, and calling "guestfs_add_drive_opts" on each one.
2518 In the C API we declare "void *dom", but really it has type
2520 "virDomainPtr dom". This is so we don't need <libvirt.h>.
2521 The number of disks added is returned. This operation is atomic: if an
2523 error is returned, then no disks are added.
2524 This function does some minimal checks to make sure the libvirt domain
2526 is not running (unless "readonly" is true). In a future version we
2527 will try to acquire the libvirt lock on each disk.
2528 Disks must be accessible locally. This often means that adding disks
2530 from a remote libvirt connection (see http://libvirt.org/remote.html)
2531 will fail unless those disks are accessible via the same device path
2532 locally too.
2533 The optional "live" flag controls whether this call will try to connect
2535 to a running virtual machine "guestfsd" process if it sees a suitable
2536 <channel> element in the libvirt XML definition. The default (if the
2537 flag is omitted) is never to try. See "ATTACHING TO RUNNING DAEMONS"
2538 for more information.
2539 The optional "readonlydisk" parameter controls what we do for disks
2541 which are marked <readonly/> in the libvirt XML. See
2542 "guestfs_add_domain" for possible values.
2543 The other optional parameters are passed directly through to
2545 "guestfs_add_drive_opts".
2546 On error this function returns -1.
2548 (Added in 1.29.14)
2550 guestfs_add_libvirt_dom_va
2552 int
2553 guestfs_add_libvirt_dom_va (guestfs_h *g,
2554 void * /* really virDomainPtr */ dom,
2555 va_list args);
2556 This is the "va_list variant" of "guestfs_add_libvirt_dom".
2558 See "CALLS WITH OPTIONAL ARGUMENTS".
2560 guestfs_add_libvirt_dom_argv
2562 int
2563 guestfs_add_libvirt_dom_argv (guestfs_h *g,
2564 void * /* really virDomainPtr */ dom,
2565 const struct guestfs_add_libvirt_dom_argv *optargs);
2566 This is the "argv variant" of "guestfs_add_libvirt_dom".
2568 See "CALLS WITH OPTIONAL ARGUMENTS".
2570 guestfs_aug_clear
2572 int
2573 guestfs_aug_clear (guestfs_h *g,
2574 const char *augpath);
2575 Set the value associated with "path" to "NULL". This is the same as
2577 the augtool(1) "clear" command.
2578 This function returns 0 on success or -1 on error.
2580 (Added in 1.3.4)
2582 guestfs_aug_close
2584 int
2585 guestfs_aug_close (guestfs_h *g);
2586 Close the current Augeas handle and free up any resources used by it.
2588 After calling this, you have to call "guestfs_aug_init" again before
2589 you can use any other Augeas functions.
2590 This function returns 0 on success or -1 on error.
2592 (Added in 0.7)
2594 guestfs_aug_defnode
2596 struct guestfs_int_bool *
2597 guestfs_aug_defnode (guestfs_h *g,
2598 const char *name,
2599 const char *expr,
2600 const char *val);
2601 Defines a variable "name" whose value is the result of evaluating
2603 "expr".
2604 If "expr" evaluates to an empty nodeset, a node is created, equivalent
2606 to calling "guestfs_aug_set" "expr", "value". "name" will be the
2607 nodeset containing that single node.
2608 On success this returns a pair containing the number of nodes in the
2610 nodeset, and a boolean flag if a node was created.
2611 This function returns a "struct guestfs_int_bool *", or NULL if there
2613 was an error. The caller must call "guestfs_free_int_bool" after use.
2614 (Added in 0.7)
2616 guestfs_aug_defvar
2618 int
2619 guestfs_aug_defvar (guestfs_h *g,
2620 const char *name,
2621 const char *expr);
2622 Defines an Augeas variable "name" whose value is the result of
2624 evaluating "expr". If "expr" is NULL, then "name" is undefined.
2625 On success this returns the number of nodes in "expr", or 0 if "expr"
2627 evaluates to something which is not a nodeset.
2628 On error this function returns -1.
2630 (Added in 0.7)
2632 guestfs_aug_get
2634 char *
2635 guestfs_aug_get (guestfs_h *g,
2636 const char *augpath);
2637 Look up the value associated with "path". If "path" matches exactly
2639 one node, the "value" is returned.
2640 This function returns a string, or NULL on error. The caller must free
2642 the returned string after use.
2643 (Added in 0.7)
2645 guestfs_aug_init
2647 int
2648 guestfs_aug_init (guestfs_h *g,
2649 const char *root,
2650 int flags);
2651 Create a new Augeas handle for editing configuration files. If there
2653 was any previous Augeas handle associated with this guestfs session,
2654 then it is closed.
2655 You must call this before using any other "guestfs_aug_*" commands.
2657 "root" is the filesystem root. "root" must not be NULL, use / instead.
2659 The flags are the same as the flags defined in <augeas.h>, the logical
2661 or of the following integers:
2662 "AUG_SAVE_BACKUP" = 1
2664 Keep the original file with a ".augsave" extension.
2665 "AUG_SAVE_NEWFILE" = 2
2667 Save changes into a file with extension ".augnew", and do not
2668 overwrite original. Overrides "AUG_SAVE_BACKUP".
2669 "AUG_TYPE_CHECK" = 4
2671 Typecheck lenses.
2672 This option is only useful when debugging Augeas lenses. Use of
2674 this option may require additional memory for the libguestfs
2675 appliance. You may need to set the "LIBGUESTFS_MEMSIZE"
2676 environment variable or call "guestfs_set_memsize".
2677 "AUG_NO_STDINC" = 8
2679 Do not use standard load path for modules.
2680 "AUG_SAVE_NOOP" = 16
2682 Make save a no-op, just record what would have been changed.
2683 "AUG_NO_LOAD" = 32
2685 Do not load the tree in "guestfs_aug_init".
2686 To close the handle, you can call "guestfs_aug_close".
2688 To find out more about Augeas, see http://augeas.net/.
2690 This function returns 0 on success or -1 on error.
2692 (Added in 0.7)
2694 guestfs_aug_insert
2696 int
2697 guestfs_aug_insert (guestfs_h *g,
2698 const char *augpath,
2699 const char *label,
2700 int before);
2701 Create a new sibling "label" for "path", inserting it into the tree
2703 before or after "path" (depending on the boolean flag "before").
2704 "path" must match exactly one existing node in the tree, and "label"
2706 must be a label, ie. not contain /, "*" or end with a bracketed index
2707 "[N]".
2708 This function returns 0 on success or -1 on error.
2710 (Added in 0.7)
2712 guestfs_aug_label
2714 char *
2715 guestfs_aug_label (guestfs_h *g,
2716 const char *augpath);
2717 The label (name of the last element) of the Augeas path expression
2719 "augpath" is returned. "augpath" must match exactly one node, else
2720 this function returns an error.
2721 This function returns a string, or NULL on error. The caller must free
2723 the returned string after use.
2724 (Added in 1.23.14)
2726 guestfs_aug_load
2728 int
2729 guestfs_aug_load (guestfs_h *g);
2730 Load files into the tree.
2732 See "aug_load" in the Augeas documentation for the full gory details.
2734 This function returns 0 on success or -1 on error.
2736 (Added in 0.7)
2738 guestfs_aug_ls
2740 char **
2741 guestfs_aug_ls (guestfs_h *g,
2742 const char *augpath);
2743 This is just a shortcut for listing "guestfs_aug_match" "path/*" and
2745 sorting the resulting nodes into alphabetical order.
2746 This function returns a NULL-terminated array of strings (like
2748 environ(3)), or NULL if there was an error. The caller must free the
2749 strings and the array after use.
2750 (Added in 0.8)
2752 guestfs_aug_match
2754 char **
2755 guestfs_aug_match (guestfs_h *g,
2756 const char *augpath);
2757 Returns a list of paths which match the path expression "path". The
2759 returned paths are sufficiently qualified so that they match exactly
2760 one node in the current tree.
2761 This function returns a NULL-terminated array of strings (like
2763 environ(3)), or NULL if there was an error. The caller must free the
2764 strings and the array after use.
2765 (Added in 0.7)
2767 guestfs_aug_mv
2769 int
2770 guestfs_aug_mv (guestfs_h *g,
2771 const char *src,
2772 const char *dest);
2773 Move the node "src" to "dest". "src" must match exactly one node.
2775 "dest" is overwritten if it exists.
2776 This function returns 0 on success or -1 on error.
2778 (Added in 0.7)
2780 guestfs_aug_rm
2782 int
2783 guestfs_aug_rm (guestfs_h *g,
2784 const char *augpath);
2785 Remove "path" and all of its children.
2787 On success this returns the number of entries which were removed.
2789 On error this function returns -1.
2791 (Added in 0.7)
2793 guestfs_aug_save
2795 int
2796 guestfs_aug_save (guestfs_h *g);
2797 This writes all pending changes to disk.
2799 The flags which were passed to "guestfs_aug_init" affect exactly how
2801 files are saved.
2802 This function returns 0 on success or -1 on error.
2804 (Added in 0.7)
2806 guestfs_aug_set
2808 int
2809 guestfs_aug_set (guestfs_h *g,
2810 const char *augpath,
2811 const char *val);
2812 Set the value associated with "path" to "val".
2814 In the Augeas API, it is possible to clear a node by setting the value
2816 to NULL. Due to an oversight in the libguestfs API you cannot do that
2817 with this call. Instead you must use the "guestfs_aug_clear" call.
2818 This function returns 0 on success or -1 on error.
2820 (Added in 0.7)
2822 guestfs_aug_setm
2824 int
2825 guestfs_aug_setm (guestfs_h *g,
2826 const char *base,
2827 const char *sub,
2828 const char *val);
2829 Change multiple Augeas nodes in a single operation. "base" is an
2831 expression matching multiple nodes. "sub" is a path expression
2832 relative to "base". All nodes matching "base" are found, and then for
2833 each node, "sub" is changed to "val". "sub" may also be "NULL" in
2834 which case the "base" nodes are modified.
2835 This returns the number of nodes modified.
2837 On error this function returns -1.
2839 (Added in 1.23.14)
2841 guestfs_aug_transform
2843 int
2844 guestfs_aug_transform (guestfs_h *g,
2845 const char *lens,
2846 const char *file,
2847 ...);
2848 You may supply a list of optional arguments to this call. Use zero or
2850 more of the following pairs of parameters, and terminate the list with
2851 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
2852 GUESTFS_AUG_TRANSFORM_REMOVE, int remove,
2854 Add an Augeas transformation for the specified "lens" so it can handle
2856 "file".
2857 If "remove" is true ("false" by default), then the transformation is
2859 removed.
2860 This function returns 0 on success or -1 on error.
2862 (Added in 1.35.2)
2864 guestfs_aug_transform_va
2866 int
2867 guestfs_aug_transform_va (guestfs_h *g,
2868 const char *lens,
2869 const char *file,
2870 va_list args);
2871 This is the "va_list variant" of "guestfs_aug_transform".
2873 See "CALLS WITH OPTIONAL ARGUMENTS".
2875 guestfs_aug_transform_argv
2877 int
2878 guestfs_aug_transform_argv (guestfs_h *g,
2879 const char *lens,
2880 const char *file,
2881 const struct guestfs_aug_transform_argv *optargs);
2882 This is the "argv variant" of "guestfs_aug_transform".
2884 See "CALLS WITH OPTIONAL ARGUMENTS".
2886 guestfs_available
2888 int
2889 guestfs_available (guestfs_h *g,
2890 char *const *groups);
2891 This command is used to check the availability of some groups of
2893 functionality in the appliance, which not all builds of the libguestfs
2894 appliance will be able to provide.
2895 The libguestfs groups, and the functions that those groups correspond
2897 to, are listed in "AVAILABILITY". You can also fetch this list at
2898 runtime by calling "guestfs_available_all_groups".
2899 The argument "groups" is a list of group names, eg: "["inotify",
2901 "augeas"]" would check for the availability of the Linux inotify
2902 functions and Augeas (configuration file editing) functions.
2903 The command returns no error if all requested groups are available.
2905 It fails with an error if one or more of the requested groups is
2907 unavailable in the appliance.
2908 If an unknown group name is included in the list of groups then an
2910 error is always returned.
2911 Notes:
2913 · "guestfs_feature_available" is the same as this call, but with a
2915 slightly simpler to use API: that call returns a boolean true/false
2916 instead of throwing an error.
2917 · You must call "guestfs_launch" before calling this function.
2919 The reason is because we don't know what groups are supported by
2921 the appliance/daemon until it is running and can be queried.
2922 · If a group of functions is available, this does not necessarily
2924 mean that they will work. You still have to check for errors when
2925 calling individual API functions even if they are available.
2926 · It is usually the job of distro packagers to build complete
2928 functionality into the libguestfs appliance. Upstream libguestfs,
2929 if built from source with all requirements satisfied, will support
2930 everything.
2931 · This call was added in version 1.0.80. In previous versions of
2933 libguestfs all you could do would be to speculatively execute a
2934 command to find out if the daemon implemented it. See also
2935 "guestfs_version".
2936 See also "guestfs_filesystem_available".
2938 This function returns 0 on success or -1 on error.
2940 (Added in 1.0.80)
2942 guestfs_available_all_groups
2944 char **
2945 guestfs_available_all_groups (guestfs_h *g);
2946 This command returns a list of all optional groups that this daemon
2948 knows about. Note this returns both supported and unsupported groups.
2949 To find out which ones the daemon can actually support you have to call
2950 "guestfs_available" / "guestfs_feature_available" on each member of the
2951 returned list.
2952 See also "guestfs_available", "guestfs_feature_available" and
2954 "AVAILABILITY".
2955 This function returns a NULL-terminated array of strings (like
2957 environ(3)), or NULL if there was an error. The caller must free the
2958 strings and the array after use.
2959 (Added in 1.3.15)
2961 guestfs_base64_in
2963 int
2964 guestfs_base64_in (guestfs_h *g,
2965 const char *base64file,
2966 const char *filename);
2967 This command uploads base64-encoded data from "base64file" to filename.
2969 This function returns 0 on success or -1 on error.
2971 (Added in 1.3.5)
2973 guestfs_base64_out
2975 int
2976 guestfs_base64_out (guestfs_h *g,
2977 const char *filename,
2978 const char *base64file);
2979 This command downloads the contents of filename, writing it out to
2981 local file "base64file" encoded as base64.
2982 This function returns 0 on success or -1 on error.
2984 (Added in 1.3.5)
2986 guestfs_blkdiscard
2988 int
2989 guestfs_blkdiscard (guestfs_h *g,
2990 const char *device);
2991 This discards all blocks on the block device "device", giving the free
2993 space back to the host.
2994 This operation requires support in libguestfs, the host filesystem,
2996 qemu and the host kernel. If this support isn't present it may give an
2997 error or even appear to run but do nothing. You must also set the
2998 "discard" attribute on the underlying drive (see
2999 "guestfs_add_drive_opts").
3000 This function returns 0 on success or -1 on error.
3002 This function depends on the feature "blkdiscard". See also
3004 "guestfs_feature_available".
3005 (Added in 1.25.44)
3007 guestfs_blkdiscardzeroes
3009 int
3010 guestfs_blkdiscardzeroes (guestfs_h *g,
3011 const char *device);
3012 This call returns true if blocks on "device" that have been discarded
3014 by a call to "guestfs_blkdiscard" are returned as blocks of zero bytes
3015 when read the next time.
3016 If it returns false, then it may be that discarded blocks are read as
3018 stale or random data.
3019 This function returns a C truth value on success or -1 on error.
3021 This function depends on the feature "blkdiscardzeroes". See also
3023 "guestfs_feature_available".
3024 (Added in 1.25.44)
3026 guestfs_blkid
3028 char **
3029 guestfs_blkid (guestfs_h *g,
3030 const char *device);
3031 This command returns block device attributes for "device". The
3033 following fields are usually present in the returned hash. Other fields
3034 may also be present.
3035 "UUID"
3037 The uuid of this device.
3038 "LABEL"
3040 The label of this device.
3041 "VERSION"
3043 The version of blkid command.
3044 "TYPE"
3046 The filesystem type or RAID of this device.
3047 "USAGE"
3049 The usage of this device, for example "filesystem" or "raid".
3050 This function returns a NULL-terminated array of strings, or NULL if
3052 there was an error. The array of strings will always have length
3053 "2n+1", where "n" keys and values alternate, followed by the trailing
3054 NULL entry. The caller must free the strings and the array after use.
3055 (Added in 1.15.9)
3057 guestfs_blockdev_flushbufs
3059 int
3060 guestfs_blockdev_flushbufs (guestfs_h *g,
3061 const char *device);
3062 This tells the kernel to flush internal buffers associated with
3064 "device".
3065 This uses the blockdev(8) command.
3067 This function returns 0 on success or -1 on error.
3069 (Added in 1.9.3)
3071 guestfs_blockdev_getbsz
3073 int
3074 guestfs_blockdev_getbsz (guestfs_h *g,
3075 const char *device);
3076 This returns the block size of a device.
3078 Note: this is different from both size in blocks and filesystem block
3080 size. Also this setting is not really used by anything. You should
3081 probably not use it for anything. Filesystems have their own idea
3082 about what block size to choose.
3083 This uses the blockdev(8) command.
3085 On error this function returns -1.
3087 (Added in 1.9.3)
3089 guestfs_blockdev_getro
3091 int
3092 guestfs_blockdev_getro (guestfs_h *g,
3093 const char *device);
3094 Returns a boolean indicating if the block device is read-only (true if
3096 read-only, false if not).
3097 This uses the blockdev(8) command.
3099 This function returns a C truth value on success or -1 on error.
3101 (Added in 1.9.3)
3103 guestfs_blockdev_getsize64
3105 int64_t
3106 guestfs_blockdev_getsize64 (guestfs_h *g,
3107 const char *device);
3108 This returns the size of the device in bytes.
3110 See also "guestfs_blockdev_getsz".
3112 This uses the blockdev(8) command.
3114 On error this function returns -1.
3116 (Added in 1.9.3)
3118 guestfs_blockdev_getss
3120 int
3121 guestfs_blockdev_getss (guestfs_h *g,
3122 const char *device);
3123 This returns the size of sectors on a block device. Usually 512, but
3125 can be larger for modern devices.
3126 (Note, this is not the size in sectors, use "guestfs_blockdev_getsz"
3128 for that).
3129 This uses the blockdev(8) command.
3131 On error this function returns -1.
3133 (Added in 1.9.3)
3135 guestfs_blockdev_getsz
3137 int64_t
3138 guestfs_blockdev_getsz (guestfs_h *g,
3139 const char *device);
3140 This returns the size of the device in units of 512-byte sectors (even
3142 if the sectorsize isn't 512 bytes ... weird).
3143 See also "guestfs_blockdev_getss" for the real sector size of the
3145 device, and "guestfs_blockdev_getsize64" for the more useful size in
3146 bytes.
3147 This uses the blockdev(8) command.
3149 On error this function returns -1.
3151 (Added in 1.9.3)
3153 guestfs_blockdev_rereadpt
3155 int
3156 guestfs_blockdev_rereadpt (guestfs_h *g,
3157 const char *device);
3158 Reread the partition table on "device".
3160 This uses the blockdev(8) command.
3162 This function returns 0 on success or -1 on error.
3164 (Added in 1.9.3)
3166 guestfs_blockdev_setbsz
3168 int
3169 guestfs_blockdev_setbsz (guestfs_h *g,
3170 const char *device,
3171 int blocksize);
3172 This function is deprecated. There is no replacement. Consult the API
3174 documentation in guestfs(3) for further information.
3175 Deprecated functions will not be removed from the API, but the fact
3177 that they are deprecated indicates that there are problems with correct
3178 use of these functions.
3179 This call does nothing and has never done anything because of a bug in
3181 blockdev. Do not use it.
3182 If you need to set the filesystem block size, use the "blocksize"
3184 option of "guestfs_mkfs".
3185 This function returns 0 on success or -1 on error.
3187 (Added in 1.9.3)
3189 guestfs_blockdev_setra
3191 int
3192 guestfs_blockdev_setra (guestfs_h *g,
3193 const char *device,
3194 int sectors);
3195 Set readahead (in 512-byte sectors) for the device.
3197 This uses the blockdev(8) command.
3199 This function returns 0 on success or -1 on error.
3201 (Added in 1.29.10)
3203 guestfs_blockdev_setro
3205 int
3206 guestfs_blockdev_setro (guestfs_h *g,
3207 const char *device);
3208 Sets the block device named "device" to read-only.
3210 This uses the blockdev(8) command.
3212 This function returns 0 on success or -1 on error.
3214 (Added in 1.9.3)
3216 guestfs_blockdev_setrw
3218 int
3219 guestfs_blockdev_setrw (guestfs_h *g,
3220 const char *device);
3221 Sets the block device named "device" to read-write.
3223 This uses the blockdev(8) command.
3225 This function returns 0 on success or -1 on error.
3227 (Added in 1.9.3)
3229 guestfs_btrfs_balance_cancel
3231 int
3232 guestfs_btrfs_balance_cancel (guestfs_h *g,
3233 const char *path);
3234 Cancel a running balance on a btrfs filesystem.
3236 This function returns 0 on success or -1 on error.
3238 This function depends on the feature "btrfs". See also
3240 "guestfs_feature_available".
3241 (Added in 1.29.22)
3243 guestfs_btrfs_balance_pause
3245 int
3246 guestfs_btrfs_balance_pause (guestfs_h *g,
3247 const char *path);
3248 Pause a running balance on a btrfs filesystem.
3250 This function returns 0 on success or -1 on error.
3252 This function depends on the feature "btrfs". See also
3254 "guestfs_feature_available".
3255 (Added in 1.29.22)
3257 guestfs_btrfs_balance_resume
3259 int
3260 guestfs_btrfs_balance_resume (guestfs_h *g,
3261 const char *path);
3262 Resume a paused balance on a btrfs filesystem.
3264 This function returns 0 on success or -1 on error.
3266 This function depends on the feature "btrfs". See also
3268 "guestfs_feature_available".
3269 (Added in 1.29.22)
3271 guestfs_btrfs_balance_status
3273 struct guestfs_btrfsbalance *
3274 guestfs_btrfs_balance_status (guestfs_h *g,
3275 const char *path);
3276 Show the status of a running or paused balance on a btrfs filesystem.
3278 This function returns a "struct guestfs_btrfsbalance *", or NULL if
3280 there was an error. The caller must call "guestfs_free_btrfsbalance"
3281 after use.
3282 This function depends on the feature "btrfs". See also
3284 "guestfs_feature_available".
3285 (Added in 1.29.26)
3287 guestfs_btrfs_device_add
3289 int
3290 guestfs_btrfs_device_add (guestfs_h *g,
3291 char *const *devices,
3292 const char *fs);
3293 Add the list of device(s) in "devices" to the btrfs filesystem mounted
3295 at "fs". If "devices" is an empty list, this does nothing.
3296 This function returns 0 on success or -1 on error.
3298 This function depends on the feature "btrfs". See also
3300 "guestfs_feature_available".
3301 (Added in 1.17.35)
3303 guestfs_btrfs_device_delete
3305 int
3306 guestfs_btrfs_device_delete (guestfs_h *g,
3307 char *const *devices,
3308 const char *fs);
3309 Remove the "devices" from the btrfs filesystem mounted at "fs". If
3311 "devices" is an empty list, this does nothing.
3312 This function returns 0 on success or -1 on error.
3314 This function depends on the feature "btrfs". See also
3316 "guestfs_feature_available".
3317 (Added in 1.17.35)
3319 guestfs_btrfs_filesystem_balance
3321 int
3322 guestfs_btrfs_filesystem_balance (guestfs_h *g,
3323 const char *fs);
3324 Balance the chunks in the btrfs filesystem mounted at "fs" across the
3326 underlying devices.
3327 This function returns 0 on success or -1 on error.
3329 This function depends on the feature "btrfs". See also
3331 "guestfs_feature_available".
3332 (Added in 1.17.35)
3334 guestfs_btrfs_filesystem_defragment
3336 int
3337 guestfs_btrfs_filesystem_defragment (guestfs_h *g,
3338 const char *path,
3339 ...);
3340 You may supply a list of optional arguments to this call. Use zero or
3342 more of the following pairs of parameters, and terminate the list with
3343 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3344 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_FLUSH, int flush,
3346 GUESTFS_BTRFS_FILESYSTEM_DEFRAGMENT_COMPRESS, const char *compress,
3347 Defragment a file or directory on a btrfs filesystem. compress is one
3349 of zlib or lzo.
3350 This function returns 0 on success or -1 on error.
3352 This function depends on the feature "btrfs". See also
3354 "guestfs_feature_available".
3355 (Added in 1.29.22)
3357 guestfs_btrfs_filesystem_defragment_va
3359 int
3360 guestfs_btrfs_filesystem_defragment_va (guestfs_h *g,
3361 const char *path,
3362 va_list args);
3363 This is the "va_list variant" of "guestfs_btrfs_filesystem_defragment".
3365 See "CALLS WITH OPTIONAL ARGUMENTS".
3367 guestfs_btrfs_filesystem_defragment_argv
3369 int
3370 guestfs_btrfs_filesystem_defragment_argv (guestfs_h *g,
3371 const char *path,
3372 const struct guestfs_btrfs_filesystem_defragment_argv *optargs);
3373 This is the "argv variant" of "guestfs_btrfs_filesystem_defragment".
3375 See "CALLS WITH OPTIONAL ARGUMENTS".
3377 guestfs_btrfs_filesystem_resize
3379 int
3380 guestfs_btrfs_filesystem_resize (guestfs_h *g,
3381 const char *mountpoint,
3382 ...);
3383 You may supply a list of optional arguments to this call. Use zero or
3385 more of the following pairs of parameters, and terminate the list with
3386 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3387 GUESTFS_BTRFS_FILESYSTEM_RESIZE_SIZE, int64_t size,
3389 This command resizes a btrfs filesystem.
3391 Note that unlike other resize calls, the filesystem has to be mounted
3393 and the parameter is the mountpoint not the device (this is a
3394 requirement of btrfs itself).
3395 The optional parameters are:
3397 "size"
3399 The new size (in bytes) of the filesystem. If omitted, the
3400 filesystem is resized to the maximum size.
3401 See also btrfs(8).
3403 This function returns 0 on success or -1 on error.
3405 This function depends on the feature "btrfs". See also
3407 "guestfs_feature_available".
3408 (Added in 1.11.17)
3410 guestfs_btrfs_filesystem_resize_va
3412 int
3413 guestfs_btrfs_filesystem_resize_va (guestfs_h *g,
3414 const char *mountpoint,
3415 va_list args);
3416 This is the "va_list variant" of "guestfs_btrfs_filesystem_resize".
3418 See "CALLS WITH OPTIONAL ARGUMENTS".
3420 guestfs_btrfs_filesystem_resize_argv
3422 int
3423 guestfs_btrfs_filesystem_resize_argv (guestfs_h *g,
3424 const char *mountpoint,
3425 const struct guestfs_btrfs_filesystem_resize_argv *optargs);
3426 This is the "argv variant" of "guestfs_btrfs_filesystem_resize".
3428 See "CALLS WITH OPTIONAL ARGUMENTS".
3430 guestfs_btrfs_filesystem_show
3432 char **
3433 guestfs_btrfs_filesystem_show (guestfs_h *g,
3434 const char *device);
3435 Show all the devices where the filesystems in "device" is spanned over.
3437 If not all the devices for the filesystems are present, then this
3439 function fails and the "errno" is set to "ENODEV".
3440 This function returns a NULL-terminated array of strings (like
3442 environ(3)), or NULL if there was an error. The caller must free the
3443 strings and the array after use.
3444 This function depends on the feature "btrfs". See also
3446 "guestfs_feature_available".
3447 (Added in 1.33.29)
3449 guestfs_btrfs_filesystem_sync
3451 int
3452 guestfs_btrfs_filesystem_sync (guestfs_h *g,
3453 const char *fs);
3454 Force sync on the btrfs filesystem mounted at "fs".
3456 This function returns 0 on success or -1 on error.
3458 This function depends on the feature "btrfs". See also
3460 "guestfs_feature_available".
3461 (Added in 1.17.35)
3463 guestfs_btrfs_fsck
3465 int
3466 guestfs_btrfs_fsck (guestfs_h *g,
3467 const char *device,
3468 ...);
3469 You may supply a list of optional arguments to this call. Use zero or
3471 more of the following pairs of parameters, and terminate the list with
3472 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3473 GUESTFS_BTRFS_FSCK_SUPERBLOCK, int64_t superblock,
3475 GUESTFS_BTRFS_FSCK_REPAIR, int repair,
3476 Used to check a btrfs filesystem, "device" is the device file where the
3478 filesystem is stored.
3479 This function returns 0 on success or -1 on error.
3481 This function depends on the feature "btrfs". See also
3483 "guestfs_feature_available".
3484 (Added in 1.17.43)
3486 guestfs_btrfs_fsck_va
3488 int
3489 guestfs_btrfs_fsck_va (guestfs_h *g,
3490 const char *device,
3491 va_list args);
3492 This is the "va_list variant" of "guestfs_btrfs_fsck".
3494 See "CALLS WITH OPTIONAL ARGUMENTS".
3496 guestfs_btrfs_fsck_argv
3498 int
3499 guestfs_btrfs_fsck_argv (guestfs_h *g,
3500 const char *device,
3501 const struct guestfs_btrfs_fsck_argv *optargs);
3502 This is the "argv variant" of "guestfs_btrfs_fsck".
3504 See "CALLS WITH OPTIONAL ARGUMENTS".
3506 guestfs_btrfs_image
3508 int
3509 guestfs_btrfs_image (guestfs_h *g,
3510 char *const *source,
3511 const char *image,
3512 ...);
3513 You may supply a list of optional arguments to this call. Use zero or
3515 more of the following pairs of parameters, and terminate the list with
3516 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3517 GUESTFS_BTRFS_IMAGE_COMPRESSLEVEL, int compresslevel,
3519 This is used to create an image of a btrfs filesystem. All data will
3521 be zeroed, but metadata and the like is preserved.
3522 This function returns 0 on success or -1 on error.
3524 This function depends on the feature "btrfs". See also
3526 "guestfs_feature_available".
3527 (Added in 1.29.32)
3529 guestfs_btrfs_image_va
3531 int
3532 guestfs_btrfs_image_va (guestfs_h *g,
3533 char *const *source,
3534 const char *image,
3535 va_list args);
3536 This is the "va_list variant" of "guestfs_btrfs_image".
3538 See "CALLS WITH OPTIONAL ARGUMENTS".
3540 guestfs_btrfs_image_argv
3542 int
3543 guestfs_btrfs_image_argv (guestfs_h *g,
3544 char *const *source,
3545 const char *image,
3546 const struct guestfs_btrfs_image_argv *optargs);
3547 This is the "argv variant" of "guestfs_btrfs_image".
3549 See "CALLS WITH OPTIONAL ARGUMENTS".
3551 guestfs_btrfs_qgroup_assign
3553 int
3554 guestfs_btrfs_qgroup_assign (guestfs_h *g,
3555 const char *src,
3556 const char *dst,
3557 const char *path);
3558 Add qgroup "src" to parent qgroup "dst". This command can group several
3560 qgroups into a parent qgroup to share common limit.
3561 This function returns 0 on success or -1 on error.
3563 This function depends on the feature "btrfs". See also
3565 "guestfs_feature_available".
3566 (Added in 1.29.17)
3568 guestfs_btrfs_qgroup_create
3570 int
3571 guestfs_btrfs_qgroup_create (guestfs_h *g,
3572 const char *qgroupid,
3573 const char *subvolume);
3574 Create a quota group (qgroup) for subvolume at "subvolume".
3576 This function returns 0 on success or -1 on error.
3578 This function depends on the feature "btrfs". See also
3580 "guestfs_feature_available".
3581 (Added in 1.29.17)
3583 guestfs_btrfs_qgroup_destroy
3585 int
3586 guestfs_btrfs_qgroup_destroy (guestfs_h *g,
3587 const char *qgroupid,
3588 const char *subvolume);
3589 Destroy a quota group.
3591 This function returns 0 on success or -1 on error.
3593 This function depends on the feature "btrfs". See also
3595 "guestfs_feature_available".
3596 (Added in 1.29.17)
3598 guestfs_btrfs_qgroup_limit
3600 int
3601 guestfs_btrfs_qgroup_limit (guestfs_h *g,
3602 const char *subvolume,
3603 int64_t size);
3604 Limit the size of the subvolume with path "subvolume".
3606 This function returns 0 on success or -1 on error.
3608 This function depends on the feature "btrfs". See also
3610 "guestfs_feature_available".
3611 (Added in 1.29.17)
3613 guestfs_btrfs_qgroup_remove
3615 int
3616 guestfs_btrfs_qgroup_remove (guestfs_h *g,
3617 const char *src,
3618 const char *dst,
3619 const char *path);
3620 Remove qgroup "src" from the parent qgroup "dst".
3622 This function returns 0 on success or -1 on error.
3624 This function depends on the feature "btrfs". See also
3626 "guestfs_feature_available".
3627 (Added in 1.29.17)
3629 guestfs_btrfs_qgroup_show
3631 struct guestfs_btrfsqgroup_list *
3632 guestfs_btrfs_qgroup_show (guestfs_h *g,
3633 const char *path);
3634 Show all subvolume quota groups in a btrfs filesystem, including their
3636 usages.
3637 This function returns a "struct guestfs_btrfsqgroup_list *", or NULL if
3639 there was an error. The caller must call
3640 "guestfs_free_btrfsqgroup_list" after use.
3641 This function depends on the feature "btrfs". See also
3643 "guestfs_feature_available".
3644 (Added in 1.29.17)
3646 guestfs_btrfs_quota_enable
3648 int
3649 guestfs_btrfs_quota_enable (guestfs_h *g,
3650 const char *fs,
3651 int enable);
3652 Enable or disable subvolume quota support for filesystem which contains
3654 "path".
3655 This function returns 0 on success or -1 on error.
3657 This function depends on the feature "btrfs". See also
3659 "guestfs_feature_available".
3660 (Added in 1.29.17)
3662 guestfs_btrfs_quota_rescan
3664 int
3665 guestfs_btrfs_quota_rescan (guestfs_h *g,
3666 const char *fs);
3667 Trash all qgroup numbers and scan the metadata again with the current
3669 config.
3670 This function returns 0 on success or -1 on error.
3672 This function depends on the feature "btrfs". See also
3674 "guestfs_feature_available".
3675 (Added in 1.29.17)
3677 guestfs_btrfs_replace
3679 int
3680 guestfs_btrfs_replace (guestfs_h *g,
3681 const char *srcdev,
3682 const char *targetdev,
3683 const char *mntpoint);
3684 Replace device of a btrfs filesystem. On a live filesystem, duplicate
3686 the data to the target device which is currently stored on the source
3687 device. After completion of the operation, the source device is wiped
3688 out and removed from the filesystem.
3689 The "targetdev" needs to be same size or larger than the "srcdev".
3691 Devices which are currently mounted are never allowed to be used as the
3692 "targetdev".
3693 This function returns 0 on success or -1 on error.
3695 This function depends on the feature "btrfs". See also
3697 "guestfs_feature_available".
3698 (Added in 1.29.48)
3700 guestfs_btrfs_rescue_chunk_recover
3702 int
3703 guestfs_btrfs_rescue_chunk_recover (guestfs_h *g,
3704 const char *device);
3705 Recover the chunk tree of btrfs filesystem by scanning the devices one
3707 by one.
3708 This function returns 0 on success or -1 on error.
3710 This function depends on the feature "btrfs". See also
3712 "guestfs_feature_available".
3713 (Added in 1.29.22)
3715 guestfs_btrfs_rescue_super_recover
3717 int
3718 guestfs_btrfs_rescue_super_recover (guestfs_h *g,
3719 const char *device);
3720 Recover bad superblocks from good copies.
3722 This function returns 0 on success or -1 on error.
3724 This function depends on the feature "btrfs". See also
3726 "guestfs_feature_available".
3727 (Added in 1.29.22)
3729 guestfs_btrfs_scrub_cancel
3731 int
3732 guestfs_btrfs_scrub_cancel (guestfs_h *g,
3733 const char *path);
3734 Cancel a running scrub on a btrfs filesystem.
3736 This function returns 0 on success or -1 on error.
3738 This function depends on the feature "btrfs". See also
3740 "guestfs_feature_available".
3741 (Added in 1.29.22)
3743 guestfs_btrfs_scrub_resume
3745 int
3746 guestfs_btrfs_scrub_resume (guestfs_h *g,
3747 const char *path);
3748 Resume a previously canceled or interrupted scrub on a btrfs
3750 filesystem.
3751 This function returns 0 on success or -1 on error.
3753 This function depends on the feature "btrfs". See also
3755 "guestfs_feature_available".
3756 (Added in 1.29.22)
3758 guestfs_btrfs_scrub_start
3760 int
3761 guestfs_btrfs_scrub_start (guestfs_h *g,
3762 const char *path);
3763 Reads all the data and metadata on the filesystem, and uses checksums
3765 and the duplicate copies from RAID storage to identify and repair any
3766 corrupt data.
3767 This function returns 0 on success or -1 on error.
3769 This function depends on the feature "btrfs". See also
3771 "guestfs_feature_available".
3772 (Added in 1.29.22)
3774 guestfs_btrfs_scrub_status
3776 struct guestfs_btrfsscrub *
3777 guestfs_btrfs_scrub_status (guestfs_h *g,
3778 const char *path);
3779 Show status of running or finished scrub on a btrfs filesystem.
3781 This function returns a "struct guestfs_btrfsscrub *", or NULL if there
3783 was an error. The caller must call "guestfs_free_btrfsscrub" after
3784 use.
3785 This function depends on the feature "btrfs". See also
3787 "guestfs_feature_available".
3788 (Added in 1.29.26)
3790 guestfs_btrfs_set_seeding
3792 int
3793 guestfs_btrfs_set_seeding (guestfs_h *g,
3794 const char *device,
3795 int seeding);
3796 Enable or disable the seeding feature of a device that contains a btrfs
3798 filesystem.
3799 This function returns 0 on success or -1 on error.
3801 This function depends on the feature "btrfs". See also
3803 "guestfs_feature_available".
3804 (Added in 1.17.43)
3806 guestfs_btrfs_subvolume_create
3808 int
3809 guestfs_btrfs_subvolume_create (guestfs_h *g,
3810 const char *dest);
3811 This function is provided for backwards compatibility with earlier
3813 versions of libguestfs. It simply calls
3814 "guestfs_btrfs_subvolume_create_opts" with no optional arguments.
3815 (Added in 1.17.35)
3817 guestfs_btrfs_subvolume_create_opts
3819 int
3820 guestfs_btrfs_subvolume_create_opts (guestfs_h *g,
3821 const char *dest,
3822 ...);
3823 You may supply a list of optional arguments to this call. Use zero or
3825 more of the following pairs of parameters, and terminate the list with
3826 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3827 GUESTFS_BTRFS_SUBVOLUME_CREATE_OPTS_QGROUPID, const char *qgroupid,
3829 Create a btrfs subvolume. The "dest" argument is the destination
3831 directory and the name of the subvolume, in the form
3832 /path/to/dest/name. The optional parameter "qgroupid" represents the
3833 qgroup which the newly created subvolume will be added to.
3834 This function returns 0 on success or -1 on error.
3836 This function depends on the feature "btrfs". See also
3838 "guestfs_feature_available".
3839 (Added in 1.17.35)
3841 guestfs_btrfs_subvolume_create_opts_va
3843 int
3844 guestfs_btrfs_subvolume_create_opts_va (guestfs_h *g,
3845 const char *dest,
3846 va_list args);
3847 This is the "va_list variant" of "guestfs_btrfs_subvolume_create_opts".
3849 See "CALLS WITH OPTIONAL ARGUMENTS".
3851 guestfs_btrfs_subvolume_create_opts_argv
3853 int
3854 guestfs_btrfs_subvolume_create_opts_argv (guestfs_h *g,
3855 const char *dest,
3856 const struct guestfs_btrfs_subvolume_create_opts_argv *optargs);
3857 This is the "argv variant" of "guestfs_btrfs_subvolume_create_opts".
3859 See "CALLS WITH OPTIONAL ARGUMENTS".
3861 guestfs_btrfs_subvolume_delete
3863 int
3864 guestfs_btrfs_subvolume_delete (guestfs_h *g,
3865 const char *subvolume);
3866 Delete the named btrfs subvolume or snapshot.
3868 This function returns 0 on success or -1 on error.
3870 This function depends on the feature "btrfs". See also
3872 "guestfs_feature_available".
3873 (Added in 1.17.35)
3875 guestfs_btrfs_subvolume_get_default
3877 int64_t
3878 guestfs_btrfs_subvolume_get_default (guestfs_h *g,
3879 const char *fs);
3880 Get the default subvolume or snapshot of a filesystem mounted at
3882 "mountpoint".
3883 On error this function returns -1.
3885 This function depends on the feature "btrfs". See also
3887 "guestfs_feature_available".
3888 (Added in 1.29.17)
3890 guestfs_btrfs_subvolume_list
3892 struct guestfs_btrfssubvolume_list *
3893 guestfs_btrfs_subvolume_list (guestfs_h *g,
3894 const char *fs);
3895 List the btrfs snapshots and subvolumes of the btrfs filesystem which
3897 is mounted at "fs".
3898 This function returns a "struct guestfs_btrfssubvolume_list *", or NULL
3900 if there was an error. The caller must call
3901 "guestfs_free_btrfssubvolume_list" after use.
3902 This function depends on the feature "btrfs". See also
3904 "guestfs_feature_available".
3905 (Added in 1.17.35)
3907 guestfs_btrfs_subvolume_set_default
3909 int
3910 guestfs_btrfs_subvolume_set_default (guestfs_h *g,
3911 int64_t id,
3912 const char *fs);
3913 Set the subvolume of the btrfs filesystem "fs" which will be mounted by
3915 default. See "guestfs_btrfs_subvolume_list" to get a list of
3916 subvolumes.
3917 This function returns 0 on success or -1 on error.
3919 This function depends on the feature "btrfs". See also
3921 "guestfs_feature_available".
3922 (Added in 1.17.35)
3924 guestfs_btrfs_subvolume_show
3926 char **
3927 guestfs_btrfs_subvolume_show (guestfs_h *g,
3928 const char *subvolume);
3929 Return detailed information of the subvolume.
3931 This function returns a NULL-terminated array of strings, or NULL if
3933 there was an error. The array of strings will always have length
3934 "2n+1", where "n" keys and values alternate, followed by the trailing
3935 NULL entry. The caller must free the strings and the array after use.
3936 This function depends on the feature "btrfs". See also
3938 "guestfs_feature_available".
3939 (Added in 1.29.17)
3941 guestfs_btrfs_subvolume_snapshot
3943 int
3944 guestfs_btrfs_subvolume_snapshot (guestfs_h *g,
3945 const char *source,
3946 const char *dest);
3947 This function is provided for backwards compatibility with earlier
3949 versions of libguestfs. It simply calls
3950 "guestfs_btrfs_subvolume_snapshot_opts" with no optional arguments.
3951 (Added in 1.17.35)
3953 guestfs_btrfs_subvolume_snapshot_opts
3955 int
3956 guestfs_btrfs_subvolume_snapshot_opts (guestfs_h *g,
3957 const char *source,
3958 const char *dest,
3959 ...);
3960 You may supply a list of optional arguments to this call. Use zero or
3962 more of the following pairs of parameters, and terminate the list with
3963 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
3964 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_RO, int ro,
3966 GUESTFS_BTRFS_SUBVOLUME_SNAPSHOT_OPTS_QGROUPID, const char *qgroupid,
3967 Create a snapshot of the btrfs subvolume "source". The "dest" argument
3969 is the destination directory and the name of the snapshot, in the form
3970 /path/to/dest/name. By default the newly created snapshot is writable,
3971 if the value of optional parameter "ro" is true, then a readonly
3972 snapshot is created. The optional parameter "qgroupid" represents the
3973 qgroup which the newly created snapshot will be added to.
3974 This function returns 0 on success or -1 on error.
3976 This function depends on the feature "btrfs". See also
3978 "guestfs_feature_available".
3979 (Added in 1.17.35)
3981 guestfs_btrfs_subvolume_snapshot_opts_va
3983 int
3984 guestfs_btrfs_subvolume_snapshot_opts_va (guestfs_h *g,
3985 const char *source,
3986 const char *dest,
3987 va_list args);
3988 This is the "va_list variant" of
3990 "guestfs_btrfs_subvolume_snapshot_opts".
3991 See "CALLS WITH OPTIONAL ARGUMENTS".
3993 guestfs_btrfs_subvolume_snapshot_opts_argv
3995 int
3996 guestfs_btrfs_subvolume_snapshot_opts_argv (guestfs_h *g,
3997 const char *source,
3998 const char *dest,
3999 const struct guestfs_btrfs_subvolume_snapshot_opts_argv *optargs);
4000 This is the "argv variant" of "guestfs_btrfs_subvolume_snapshot_opts".
4002 See "CALLS WITH OPTIONAL ARGUMENTS".
4004 guestfs_btrfstune_enable_extended_inode_refs
4006 int
4007 guestfs_btrfstune_enable_extended_inode_refs (guestfs_h *g,
4008 const char *device);
4009 This will Enable extended inode refs.
4011 This function returns 0 on success or -1 on error.
4013 This function depends on the feature "btrfs". See also
4015 "guestfs_feature_available".
4016 (Added in 1.29.29)
4018 guestfs_btrfstune_enable_skinny_metadata_extent_refs
4020 int
4021 guestfs_btrfstune_enable_skinny_metadata_extent_refs (guestfs_h *g,
4022 const char *device);
4023 This enable skinny metadata extent refs.
4025 This function returns 0 on success or -1 on error.
4027 This function depends on the feature "btrfs". See also
4029 "guestfs_feature_available".
4030 (Added in 1.29.29)
4032 guestfs_btrfstune_seeding
4034 int
4035 guestfs_btrfstune_seeding (guestfs_h *g,
4036 const char *device,
4037 int seeding);
4038 Enable seeding of a btrfs device, this will force a fs readonly so that
4040 you can use it to build other filesystems.
4041 This function returns 0 on success or -1 on error.
4043 This function depends on the feature "btrfs". See also
4045 "guestfs_feature_available".
4046 (Added in 1.29.29)
4048 guestfs_c_pointer
4050 int64_t
4051 guestfs_c_pointer (guestfs_h *g);
4052 In non-C language bindings, this allows you to retrieve the underlying
4054 C pointer to the handle (ie. "guestfs_h *"). The purpose of this is to
4055 allow other libraries to interwork with libguestfs.
4056 On error this function returns -1.
4058 (Added in 1.29.17)
4060 guestfs_canonical_device_name
4062 char *
4063 guestfs_canonical_device_name (guestfs_h *g,
4064 const char *device);
4065 This utility function is useful when displaying device names to the
4067 user. It takes a number of irregular device names and returns them in
4068 a consistent format:
4069 /dev/hdX
4071 /dev/vdX
4072 These are returned as /dev/sdX. Note this works for device names
4073 and partition names. This is approximately the reverse of the
4074 algorithm described in "BLOCK DEVICE NAMING".
4075 /dev/mapper/VG-LV
4077 /dev/dm-N
4078 Converted to /dev/VG/LV form using "guestfs_lvm_canonical_lv_name".
4079 Other strings are returned unmodified.
4081 This function returns a string, or NULL on error. The caller must free
4083 the returned string after use.
4084 (Added in 1.19.7)
4086 guestfs_cap_get_file
4088 char *
4089 guestfs_cap_get_file (guestfs_h *g,
4090 const char *path);
4091 This function returns the Linux capabilities attached to "path". The
4093 capabilities set is returned in text form (see cap_to_text(3)).
4094 If no capabilities are attached to a file, an empty string is returned.
4096 This function returns a string, or NULL on error. The caller must free
4098 the returned string after use.
4099 This function depends on the feature "linuxcaps". See also
4101 "guestfs_feature_available".
4102 (Added in 1.19.63)
4104 guestfs_cap_set_file
4106 int
4107 guestfs_cap_set_file (guestfs_h *g,
4108 const char *path,
4109 const char *cap);
4110 This function sets the Linux capabilities attached to "path". The
4112 capabilities set "cap" should be passed in text form (see
4113 cap_from_text(3)).
4114 This function returns 0 on success or -1 on error.
4116 This function depends on the feature "linuxcaps". See also
4118 "guestfs_feature_available".
4119 (Added in 1.19.63)
4121 guestfs_case_sensitive_path
4123 char *
4124 guestfs_case_sensitive_path (guestfs_h *g,
4125 const char *path);
4126 This can be used to resolve case insensitive paths on a filesystem
4128 which is case sensitive. The use case is to resolve paths which you
4129 have read from Windows configuration files or the Windows Registry, to
4130 the true path.
4131 The command handles a peculiarity of the Linux ntfs-3g filesystem
4133 driver (and probably others), which is that although the underlying
4134 filesystem is case-insensitive, the driver exports the filesystem to
4135 Linux as case-sensitive.
4136 One consequence of this is that special directories such as C:\windows
4138 may appear as /WINDOWS or /windows (or other things) depending on the
4139 precise details of how they were created. In Windows itself this would
4140 not be a problem.
4141 Bug or feature? You decide:
4143 http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1
4144 "guestfs_case_sensitive_path" attempts to resolve the true case of each
4146 element in the path. It will return a resolved path if either the full
4147 path or its parent directory exists. If the parent directory exists but
4148 the full path does not, the case of the parent directory will be
4149 correctly resolved, and the remainder appended unmodified. For example,
4150 if the file "/Windows/System32/netkvm.sys" exists:
4151 "guestfs_case_sensitive_path" ("/windows/system32/netkvm.sys")
4153 "Windows/System32/netkvm.sys"
4154 "guestfs_case_sensitive_path" ("/windows/system32/NoSuchFile")
4156 "Windows/System32/NoSuchFile"
4157 "guestfs_case_sensitive_path" ("/windows/system33/netkvm.sys")
4159 ERROR
4160 Note: Because of the above behaviour, "guestfs_case_sensitive_path"
4162 cannot be used to check for the existence of a file.
4163 Note: This function does not handle drive names, backslashes etc.
4165 See also "guestfs_realpath".
4167 This function returns a string, or NULL on error. The caller must free
4169 the returned string after use.
4170 (Added in 1.0.75)
4172 guestfs_cat
4174 char *
4175 guestfs_cat (guestfs_h *g,
4176 const char *path);
4177 Return the contents of the file named "path".
4179 Because, in C, this function returns a "char *", there is no way to
4181 differentiate between a "\0" character in a file and end of string. To
4182 handle binary files, use the "guestfs_read_file" or "guestfs_download"
4183 functions.
4184 This function returns a string, or NULL on error. The caller must free
4186 the returned string after use.
4187 (Added in 0.4)
4189 guestfs_checksum
4191 char *
4192 guestfs_checksum (guestfs_h *g,
4193 const char *csumtype,
4194 const char *path);
4195 This call computes the MD5, SHAx or CRC checksum of the file named
4197 "path".
4198 The type of checksum to compute is given by the "csumtype" parameter
4200 which must have one of the following values:
4201 "crc"
4203 Compute the cyclic redundancy check (CRC) specified by POSIX for
4204 the "cksum" command.
4205 "md5"
4207 Compute the MD5 hash (using the "md5sum" program).
4208 "sha1"
4210 Compute the SHA1 hash (using the "sha1sum" program).
4211 "sha224"
4213 Compute the SHA224 hash (using the "sha224sum" program).
4214 "sha256"
4216 Compute the SHA256 hash (using the "sha256sum" program).
4217 "sha384"
4219 Compute the SHA384 hash (using the "sha384sum" program).
4220 "sha512"
4222 Compute the SHA512 hash (using the "sha512sum" program).
4223 The checksum is returned as a printable string.
4225 To get the checksum for a device, use "guestfs_checksum_device".
4227 To get the checksums for many files, use "guestfs_checksums_out".
4229 This function returns a string, or NULL on error. The caller must free
4231 the returned string after use.
4232 (Added in 1.0.2)
4234 guestfs_checksum_device
4236 char *
4237 guestfs_checksum_device (guestfs_h *g,
4238 const char *csumtype,
4239 const char *device);
4240 This call computes the MD5, SHAx or CRC checksum of the contents of the
4242 device named "device". For the types of checksums supported see the
4243 "guestfs_checksum" command.
4244 This function returns a string, or NULL on error. The caller must free
4246 the returned string after use.
4247 (Added in 1.3.2)
4249 guestfs_checksums_out
4251 int
4252 guestfs_checksums_out (guestfs_h *g,
4253 const char *csumtype,
4254 const char *directory,
4255 const char *sumsfile);
4256 This command computes the checksums of all regular files in directory
4258 and then emits a list of those checksums to the local output file
4259 "sumsfile".
4260 This can be used for verifying the integrity of a virtual machine.
4262 However to be properly secure you should pay attention to the output of
4263 the checksum command (it uses the ones from GNU coreutils). In
4264 particular when the filename is not printable, coreutils uses a special
4265 backslash syntax. For more information, see the GNU coreutils info
4266 file.
4267 This function returns 0 on success or -1 on error.
4269 (Added in 1.3.7)
4271 guestfs_chmod
4273 int
4274 guestfs_chmod (guestfs_h *g,
4275 int mode,
4276 const char *path);
4277 Change the mode (permissions) of "path" to "mode". Only numeric modes
4279 are supported.
4280 Note: When using this command from guestfish, "mode" by default would
4282 be decimal, unless you prefix it with 0 to get octal, ie. use 0700 not
4283 700.
4284 The mode actually set is affected by the umask.
4286 This function returns 0 on success or -1 on error.
4288 (Added in 0.8)
4290 guestfs_chown
4292 int
4293 guestfs_chown (guestfs_h *g,
4294 int owner,
4295 int group,
4296 const char *path);
4297 Change the file owner to "owner" and group to "group".
4299 Only numeric uid and gid are supported. If you want to use names, you
4301 will need to locate and parse the password file yourself (Augeas
4302 support makes this relatively easy).
4303 This function returns 0 on success or -1 on error.
4305 (Added in 0.8)
4307 guestfs_clear_backend_setting
4309 int
4310 guestfs_clear_backend_setting (guestfs_h *g,
4311 const char *name);
4312 If there is a backend setting string matching "name" or beginning with
4314 "name=", then that string is removed from the backend settings.
4315 This call returns the number of strings which were removed (which may
4317 be 0, 1 or greater than 1).
4318 See "BACKEND", "BACKEND SETTINGS".
4320 On error this function returns -1.
4322 (Added in 1.27.2)
4324 guestfs_command
4326 char *
4327 guestfs_command (guestfs_h *g,
4328 char *const *arguments);
4329 This call runs a command from the guest filesystem. The filesystem
4331 must be mounted, and must contain a compatible operating system (ie.
4332 something Linux, with the same or compatible processor architecture).
4333 The single parameter is an argv-style list of arguments. The first
4335 element is the name of the program to run. Subsequent elements are
4336 parameters. The list must be non-empty (ie. must contain a program
4337 name). Note that the command runs directly, and is not invoked via the
4338 shell (see "guestfs_sh").
4339 The return value is anything printed to stdout by the command.
4341 If the command returns a non-zero exit status, then this function
4343 returns an error message. The error message string is the content of
4344 stderr from the command.
4345 The $PATH environment variable will contain at least /usr/bin and /bin.
4347 If you require a program from another location, you should provide the
4348 full path in the first parameter.
4349 Shared libraries and data files required by the program must be
4351 available on filesystems which are mounted in the correct places. It
4352 is the caller’s responsibility to ensure all filesystems that are
4353 needed are mounted at the right locations.
4354 This function returns a string, or NULL on error. The caller must free
4356 the returned string after use.
4357 Because of the message protocol, there is a transfer limit of somewhere
4359 between 2MB and 4MB. See "PROTOCOL LIMITS".
4360 (Added in 1.9.1)
4362 guestfs_command_lines
4364 char **
4365 guestfs_command_lines (guestfs_h *g,
4366 char *const *arguments);
4367 This is the same as "guestfs_command", but splits the result into a
4369 list of lines.
4370 See also: "guestfs_sh_lines"
4372 This function returns a NULL-terminated array of strings (like
4374 environ(3)), or NULL if there was an error. The caller must free the
4375 strings and the array 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_compress_device_out
4383 int
4384 guestfs_compress_device_out (guestfs_h *g,
4385 const char *ctype,
4386 const char *device,
4387 const char *zdevice,
4388 ...);
4389 You may supply a list of optional arguments to this call. Use zero or
4391 more of the following pairs of parameters, and terminate the list with
4392 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4393 GUESTFS_COMPRESS_DEVICE_OUT_LEVEL, int level,
4395 This command compresses "device" and writes it out to the local file
4397 "zdevice".
4398 The "ctype" and optional "level" parameters have the same meaning as in
4400 "guestfs_compress_out".
4401 This function returns 0 on success or -1 on error.
4403 (Added in 1.13.15)
4405 guestfs_compress_device_out_va
4407 int
4408 guestfs_compress_device_out_va (guestfs_h *g,
4409 const char *ctype,
4410 const char *device,
4411 const char *zdevice,
4412 va_list args);
4413 This is the "va_list variant" of "guestfs_compress_device_out".
4415 See "CALLS WITH OPTIONAL ARGUMENTS".
4417 guestfs_compress_device_out_argv
4419 int
4420 guestfs_compress_device_out_argv (guestfs_h *g,
4421 const char *ctype,
4422 const char *device,
4423 const char *zdevice,
4424 const struct guestfs_compress_device_out_argv *optargs);
4425 This is the "argv variant" of "guestfs_compress_device_out".
4427 See "CALLS WITH OPTIONAL ARGUMENTS".
4429 guestfs_compress_out
4431 int
4432 guestfs_compress_out (guestfs_h *g,
4433 const char *ctype,
4434 const char *file,
4435 const char *zfile,
4436 ...);
4437 You may supply a list of optional arguments to this call. Use zero or
4439 more of the following pairs of parameters, and terminate the list with
4440 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4441 GUESTFS_COMPRESS_OUT_LEVEL, int level,
4443 This command compresses file and writes it out to the local file zfile.
4445 The compression program used is controlled by the "ctype" parameter.
4447 Currently this includes: "compress", "gzip", "bzip2", "xz" or "lzop".
4448 Some compression types may not be supported by particular builds of
4449 libguestfs, in which case you will get an error containing the
4450 substring "not supported".
4451 The optional "level" parameter controls compression level. The meaning
4453 and default for this parameter depends on the compression program being
4454 used.
4455 This function returns 0 on success or -1 on error.
4457 (Added in 1.13.15)
4459 guestfs_compress_out_va
4461 int
4462 guestfs_compress_out_va (guestfs_h *g,
4463 const char *ctype,
4464 const char *file,
4465 const char *zfile,
4466 va_list args);
4467 This is the "va_list variant" of "guestfs_compress_out".
4469 See "CALLS WITH OPTIONAL ARGUMENTS".
4471 guestfs_compress_out_argv
4473 int
4474 guestfs_compress_out_argv (guestfs_h *g,
4475 const char *ctype,
4476 const char *file,
4477 const char *zfile,
4478 const struct guestfs_compress_out_argv *optargs);
4479 This is the "argv variant" of "guestfs_compress_out".
4481 See "CALLS WITH OPTIONAL ARGUMENTS".
4483 guestfs_config
4485 int
4486 guestfs_config (guestfs_h *g,
4487 const char *hvparam,
4488 const char *hvvalue);
4489 This can be used to add arbitrary hypervisor parameters of the form
4491 -param value. Actually it’s not quite arbitrary - we prevent you from
4492 setting some parameters which would interfere with parameters that we
4493 use.
4494 The first character of "hvparam" string must be a "-" (dash).
4496 "hvvalue" can be NULL.
4498 This function returns 0 on success or -1 on error.
4500 (Added in 0.3)
4502 guestfs_copy_attributes
4504 int
4505 guestfs_copy_attributes (guestfs_h *g,
4506 const char *src,
4507 const char *dest,
4508 ...);
4509 You may supply a list of optional arguments to this call. Use zero or
4511 more of the following pairs of parameters, and terminate the list with
4512 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4513 GUESTFS_COPY_ATTRIBUTES_ALL, int all,
4515 GUESTFS_COPY_ATTRIBUTES_MODE, int mode,
4516 GUESTFS_COPY_ATTRIBUTES_XATTRIBUTES, int xattributes,
4517 GUESTFS_COPY_ATTRIBUTES_OWNERSHIP, int ownership,
4518 Copy the attributes of a path (which can be a file or a directory) to
4520 another path.
4521 By default "no" attribute is copied, so make sure to specify any (or
4523 "all" to copy everything).
4524 The optional arguments specify which attributes can be copied:
4526 "mode"
4528 Copy part of the file mode from "source" to "destination". Only the
4529 UNIX permissions and the sticky/setuid/setgid bits can be copied.
4530 "xattributes"
4532 Copy the Linux extended attributes (xattrs) from "source" to
4533 "destination". This flag does nothing if the linuxxattrs feature
4534 is not available (see "guestfs_feature_available").
4535 "ownership"
4537 Copy the owner uid and the group gid of "source" to "destination".
4538 "all"
4540 Copy all the attributes from "source" to "destination". Enabling it
4541 enables all the other flags, if they are not specified already.
4542 This function returns 0 on success or -1 on error.
4544 (Added in 1.25.21)
4546 guestfs_copy_attributes_va
4548 int
4549 guestfs_copy_attributes_va (guestfs_h *g,
4550 const char *src,
4551 const char *dest,
4552 va_list args);
4553 This is the "va_list variant" of "guestfs_copy_attributes".
4555 See "CALLS WITH OPTIONAL ARGUMENTS".
4557 guestfs_copy_attributes_argv
4559 int
4560 guestfs_copy_attributes_argv (guestfs_h *g,
4561 const char *src,
4562 const char *dest,
4563 const struct guestfs_copy_attributes_argv *optargs);
4564 This is the "argv variant" of "guestfs_copy_attributes".
4566 See "CALLS WITH OPTIONAL ARGUMENTS".
4568 guestfs_copy_device_to_device
4570 int
4571 guestfs_copy_device_to_device (guestfs_h *g,
4572 const char *src,
4573 const char *dest,
4574 ...);
4575 You may supply a list of optional arguments to this call. Use zero or
4577 more of the following pairs of parameters, and terminate the list with
4578 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4579 GUESTFS_COPY_DEVICE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4581 GUESTFS_COPY_DEVICE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4582 GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, int64_t size,
4583 GUESTFS_COPY_DEVICE_TO_DEVICE_SPARSE, int sparse,
4584 GUESTFS_COPY_DEVICE_TO_DEVICE_APPEND, int append,
4585 The four calls "guestfs_copy_device_to_device",
4587 "guestfs_copy_device_to_file", "guestfs_copy_file_to_device", and
4588 "guestfs_copy_file_to_file" let you copy from a source (device|file) to
4589 a destination (device|file).
4590 Partial copies can be made since you can specify optionally the source
4592 offset, destination offset and size to copy. These values are all
4593 specified in bytes. If not given, the offsets both default to zero,
4594 and the size defaults to copying as much as possible until we hit the
4595 end of the source.
4596 The source and destination may be the same object. However overlapping
4598 regions may not be copied correctly.
4599 If the destination is a file, it is created if required. If the
4601 destination file is not large enough, it is extended.
4602 If the destination is a file and the "append" flag is not set, then the
4604 destination file is truncated. If the "append" flag is set, then the
4605 copy appends to the destination file. The "append" flag currently
4606 cannot be set for devices.
4607 If the "sparse" flag is true then the call avoids writing blocks that
4609 contain only zeroes, which can help in some situations where the
4610 backing disk is thin-provisioned. Note that unless the target is
4611 already zeroed, using this option will result in incorrect copying.
4612 This function returns 0 on success or -1 on error.
4614 This long-running command can generate progress notification messages
4616 so that the caller can display a progress bar or indicator. To receive
4617 these messages, the caller must register a progress event callback.
4618 See "GUESTFS_EVENT_PROGRESS".
4619 (Added in 1.13.25)
4621 guestfs_copy_device_to_device_va
4623 int
4624 guestfs_copy_device_to_device_va (guestfs_h *g,
4625 const char *src,
4626 const char *dest,
4627 va_list args);
4628 This is the "va_list variant" of "guestfs_copy_device_to_device".
4630 See "CALLS WITH OPTIONAL ARGUMENTS".
4632 guestfs_copy_device_to_device_argv
4634 int
4635 guestfs_copy_device_to_device_argv (guestfs_h *g,
4636 const char *src,
4637 const char *dest,
4638 const struct guestfs_copy_device_to_device_argv *optargs);
4639 This is the "argv variant" of "guestfs_copy_device_to_device".
4641 See "CALLS WITH OPTIONAL ARGUMENTS".
4643 guestfs_copy_device_to_file
4645 int
4646 guestfs_copy_device_to_file (guestfs_h *g,
4647 const char *src,
4648 const char *dest,
4649 ...);
4650 You may supply a list of optional arguments to this call. Use zero or
4652 more of the following pairs of parameters, and terminate the list with
4653 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4654 GUESTFS_COPY_DEVICE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4656 GUESTFS_COPY_DEVICE_TO_FILE_DESTOFFSET, int64_t destoffset,
4657 GUESTFS_COPY_DEVICE_TO_FILE_SIZE, int64_t size,
4658 GUESTFS_COPY_DEVICE_TO_FILE_SPARSE, int sparse,
4659 GUESTFS_COPY_DEVICE_TO_FILE_APPEND, int append,
4660 See "guestfs_copy_device_to_device" for a general overview of this
4662 call.
4663 This function returns 0 on success or -1 on error.
4665 This long-running command can generate progress notification messages
4667 so that the caller can display a progress bar or indicator. To receive
4668 these messages, the caller must register a progress event callback.
4669 See "GUESTFS_EVENT_PROGRESS".
4670 (Added in 1.13.25)
4672 guestfs_copy_device_to_file_va
4674 int
4675 guestfs_copy_device_to_file_va (guestfs_h *g,
4676 const char *src,
4677 const char *dest,
4678 va_list args);
4679 This is the "va_list variant" of "guestfs_copy_device_to_file".
4681 See "CALLS WITH OPTIONAL ARGUMENTS".
4683 guestfs_copy_device_to_file_argv
4685 int
4686 guestfs_copy_device_to_file_argv (guestfs_h *g,
4687 const char *src,
4688 const char *dest,
4689 const struct guestfs_copy_device_to_file_argv *optargs);
4690 This is the "argv variant" of "guestfs_copy_device_to_file".
4692 See "CALLS WITH OPTIONAL ARGUMENTS".
4694 guestfs_copy_file_to_device
4696 int
4697 guestfs_copy_file_to_device (guestfs_h *g,
4698 const char *src,
4699 const char *dest,
4700 ...);
4701 You may supply a list of optional arguments to this call. Use zero or
4703 more of the following pairs of parameters, and terminate the list with
4704 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4705 GUESTFS_COPY_FILE_TO_DEVICE_SRCOFFSET, int64_t srcoffset,
4707 GUESTFS_COPY_FILE_TO_DEVICE_DESTOFFSET, int64_t destoffset,
4708 GUESTFS_COPY_FILE_TO_DEVICE_SIZE, int64_t size,
4709 GUESTFS_COPY_FILE_TO_DEVICE_SPARSE, int sparse,
4710 GUESTFS_COPY_FILE_TO_DEVICE_APPEND, int append,
4711 See "guestfs_copy_device_to_device" for a general overview of this
4713 call.
4714 This function returns 0 on success or -1 on error.
4716 This long-running command can generate progress notification messages
4718 so that the caller can display a progress bar or indicator. To receive
4719 these messages, the caller must register a progress event callback.
4720 See "GUESTFS_EVENT_PROGRESS".
4721 (Added in 1.13.25)
4723 guestfs_copy_file_to_device_va
4725 int
4726 guestfs_copy_file_to_device_va (guestfs_h *g,
4727 const char *src,
4728 const char *dest,
4729 va_list args);
4730 This is the "va_list variant" of "guestfs_copy_file_to_device".
4732 See "CALLS WITH OPTIONAL ARGUMENTS".
4734 guestfs_copy_file_to_device_argv
4736 int
4737 guestfs_copy_file_to_device_argv (guestfs_h *g,
4738 const char *src,
4739 const char *dest,
4740 const struct guestfs_copy_file_to_device_argv *optargs);
4741 This is the "argv variant" of "guestfs_copy_file_to_device".
4743 See "CALLS WITH OPTIONAL ARGUMENTS".
4745 guestfs_copy_file_to_file
4747 int
4748 guestfs_copy_file_to_file (guestfs_h *g,
4749 const char *src,
4750 const char *dest,
4751 ...);
4752 You may supply a list of optional arguments to this call. Use zero or
4754 more of the following pairs of parameters, and terminate the list with
4755 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4756 GUESTFS_COPY_FILE_TO_FILE_SRCOFFSET, int64_t srcoffset,
4758 GUESTFS_COPY_FILE_TO_FILE_DESTOFFSET, int64_t destoffset,
4759 GUESTFS_COPY_FILE_TO_FILE_SIZE, int64_t size,
4760 GUESTFS_COPY_FILE_TO_FILE_SPARSE, int sparse,
4761 GUESTFS_COPY_FILE_TO_FILE_APPEND, int append,
4762 See "guestfs_copy_device_to_device" for a general overview of this
4764 call.
4765 This is not the function you want for copying files. This is for
4767 copying blocks within existing files. See "guestfs_cp", "guestfs_cp_a"
4768 and "guestfs_mv" for general file copying and moving functions.
4769 This function returns 0 on success or -1 on error.
4771 This long-running command can generate progress notification messages
4773 so that the caller can display a progress bar or indicator. To receive
4774 these messages, the caller must register a progress event callback.
4775 See "GUESTFS_EVENT_PROGRESS".
4776 (Added in 1.13.25)
4778 guestfs_copy_file_to_file_va
4780 int
4781 guestfs_copy_file_to_file_va (guestfs_h *g,
4782 const char *src,
4783 const char *dest,
4784 va_list args);
4785 This is the "va_list variant" of "guestfs_copy_file_to_file".
4787 See "CALLS WITH OPTIONAL ARGUMENTS".
4789 guestfs_copy_file_to_file_argv
4791 int
4792 guestfs_copy_file_to_file_argv (guestfs_h *g,
4793 const char *src,
4794 const char *dest,
4795 const struct guestfs_copy_file_to_file_argv *optargs);
4796 This is the "argv variant" of "guestfs_copy_file_to_file".
4798 See "CALLS WITH OPTIONAL ARGUMENTS".
4800 guestfs_copy_in
4802 int
4803 guestfs_copy_in (guestfs_h *g,
4804 const char *localpath,
4805 const char *remotedir);
4806 "guestfs_copy_in" copies local files or directories recursively into
4808 the disk image, placing them in the directory called "remotedir" (which
4809 must exist).
4810 Wildcards cannot be used.
4812 This function returns 0 on success or -1 on error.
4814 (Added in 1.29.24)
4816 guestfs_copy_out
4818 int
4819 guestfs_copy_out (guestfs_h *g,
4820 const char *remotepath,
4821 const char *localdir);
4822 "guestfs_copy_out" copies remote files or directories recursively out
4824 of the disk image, placing them on the host disk in a local directory
4825 called "localdir" (which must exist).
4826 To download to the current directory, use "." as in:
4828 C<guestfs_copy_out> /home .
4830 Wildcards cannot be used.
4832 This function returns 0 on success or -1 on error.
4834 (Added in 1.29.24)
4836 guestfs_copy_size
4838 int
4839 guestfs_copy_size (guestfs_h *g,
4840 const char *src,
4841 const char *dest,
4842 int64_t size);
4843 This function is deprecated. In new code, use the
4845 "guestfs_copy_device_to_device" call instead.
4846 Deprecated functions will not be removed from the API, but the fact
4848 that they are deprecated indicates that there are problems with correct
4849 use of these functions.
4850 This command copies exactly "size" bytes from one source device or file
4852 "src" to another destination device or file "dest".
4853 Note this will fail if the source is too short or if the destination is
4855 not large enough.
4856 This function returns 0 on success or -1 on error.
4858 This long-running command can generate progress notification messages
4860 so that the caller can display a progress bar or indicator. To receive
4861 these messages, the caller must register a progress event callback.
4862 See "GUESTFS_EVENT_PROGRESS".
4863 (Added in 1.0.87)
4865 guestfs_cp
4867 int
4868 guestfs_cp (guestfs_h *g,
4869 const char *src,
4870 const char *dest);
4871 This copies a file from "src" to "dest" where "dest" is either a
4873 destination filename or destination directory.
4874 This function returns 0 on success or -1 on error.
4876 (Added in 1.0.18)
4878 guestfs_cp_a
4880 int
4881 guestfs_cp_a (guestfs_h *g,
4882 const char *src,
4883 const char *dest);
4884 This copies a file or directory from "src" to "dest" recursively using
4886 the "cp -a" command.
4887 This function returns 0 on success or -1 on error.
4889 (Added in 1.0.18)
4891 guestfs_cp_r
4893 int
4894 guestfs_cp_r (guestfs_h *g,
4895 const char *src,
4896 const char *dest);
4897 This copies a file or directory from "src" to "dest" recursively using
4899 the "cp -rP" command.
4900 Most users should use "guestfs_cp_a" instead. This command is useful
4902 when you don't want to preserve permissions, because the target
4903 filesystem does not support it (primarily when writing to DOS FAT
4904 filesystems).
4905 This function returns 0 on success or -1 on error.
4907 (Added in 1.21.38)
4909 guestfs_cpio_out
4911 int
4912 guestfs_cpio_out (guestfs_h *g,
4913 const char *directory,
4914 const char *cpiofile,
4915 ...);
4916 You may supply a list of optional arguments to this call. Use zero or
4918 more of the following pairs of parameters, and terminate the list with
4919 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
4920 GUESTFS_CPIO_OUT_FORMAT, const char *format,
4922 This command packs the contents of directory and downloads it to local
4924 file "cpiofile".
4925 The optional "format" parameter can be used to select the format. Only
4927 the following formats are currently permitted:
4928 "newc"
4930 New (SVR4) portable format. This format happens to be compatible
4931 with the cpio-like format used by the Linux kernel for initramfs.
4932 This is the default format.
4934 "crc"
4936 New (SVR4) portable format with a checksum.
4937 This function returns 0 on success or -1 on error.
4939 (Added in 1.27.9)
4941 guestfs_cpio_out_va
4943 int
4944 guestfs_cpio_out_va (guestfs_h *g,
4945 const char *directory,
4946 const char *cpiofile,
4947 va_list args);
4948 This is the "va_list variant" of "guestfs_cpio_out".
4950 See "CALLS WITH OPTIONAL ARGUMENTS".
4952 guestfs_cpio_out_argv
4954 int
4955 guestfs_cpio_out_argv (guestfs_h *g,
4956 const char *directory,
4957 const char *cpiofile,
4958 const struct guestfs_cpio_out_argv *optargs);
4959 This is the "argv variant" of "guestfs_cpio_out".
4961 See "CALLS WITH OPTIONAL ARGUMENTS".
4963 guestfs_dd
4965 int
4966 guestfs_dd (guestfs_h *g,
4967 const char *src,
4968 const char *dest);
4969 This function is deprecated. In new code, use the
4971 "guestfs_copy_device_to_device" call instead.
4972 Deprecated functions will not be removed from the API, but the fact
4974 that they are deprecated indicates that there are problems with correct
4975 use of these functions.
4976 This command copies from one source device or file "src" to another
4978 destination device or file "dest". Normally you would use this to copy
4979 to or from a device or partition, for example to duplicate a
4980 filesystem.
4981 If the destination is a device, it must be as large or larger than the
4983 source file or device, otherwise the copy will fail. This command
4984 cannot do partial copies (see "guestfs_copy_device_to_device").
4985 This function returns 0 on success or -1 on error.
4987 (Added in 1.0.80)
4989 guestfs_device_index
4991 int
4992 guestfs_device_index (guestfs_h *g,
4993 const char *device);
4994 This function takes a device name (eg. "/dev/sdb") and returns the
4996 index of the device in the list of devices.
4997 Index numbers start from 0. The named device must exist, for example
4999 as a string returned from "guestfs_list_devices".
5000 See also "guestfs_list_devices", "guestfs_part_to_dev".
5002 On error this function returns -1.
5004 (Added in 1.19.7)
5006 guestfs_df
5008 char *
5009 guestfs_df (guestfs_h *g);
5010 This command runs the "df" command to report disk space used.
5012 This command is mostly useful for interactive sessions. It is not
5014 intended that you try to parse the output string. Use
5015 "guestfs_statvfs" from programs.
5016 This function returns a string, or NULL on error. The caller must free
5018 the returned string after use.
5019 (Added in 1.0.54)
5021 guestfs_df_h
5023 char *
5024 guestfs_df_h (guestfs_h *g);
5025 This command runs the "df -h" command to report disk space used in
5027 human-readable format.
5028 This command is mostly useful for interactive sessions. It is not
5030 intended that you try to parse the output string. Use
5031 "guestfs_statvfs" from programs.
5032 This function returns a string, or NULL on error. The caller must free
5034 the returned string after use.
5035 (Added in 1.0.54)
5037 guestfs_disk_create
5039 int
5040 guestfs_disk_create (guestfs_h *g,
5041 const char *filename,
5042 const char *format,
5043 int64_t size,
5044 ...);
5045 You may supply a list of optional arguments to this call. Use zero or
5047 more of the following pairs of parameters, and terminate the list with
5048 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5049 GUESTFS_DISK_CREATE_BACKINGFILE, const char *backingfile,
5051 GUESTFS_DISK_CREATE_BACKINGFORMAT, const char *backingformat,
5052 GUESTFS_DISK_CREATE_PREALLOCATION, const char *preallocation,
5053 GUESTFS_DISK_CREATE_COMPAT, const char *compat,
5054 GUESTFS_DISK_CREATE_CLUSTERSIZE, int clustersize,
5055 Create a blank disk image called filename (a host file) with format
5057 "format" (usually "raw" or "qcow2"). The size is "size" bytes.
5058 If used with the optional "backingfile" parameter, then a snapshot is
5060 created on top of the backing file. In this case, "size" must be
5061 passed as "-1". The size of the snapshot is the same as the size of
5062 the backing file, which is discovered automatically. You are
5063 encouraged to also pass "backingformat" to describe the format of
5064 "backingfile".
5065 If filename refers to a block device, then the device is formatted.
5067 The "size" is ignored since block devices have an intrinsic size.
5068 The other optional parameters are:
5070 "preallocation"
5072 If format is "raw", then this can be either "off" (or "sparse") or
5073 "full" to create a sparse or fully allocated file respectively.
5074 The default is "off".
5075 If format is "qcow2", then this can be "off" (or "sparse"),
5077 "metadata" or "full". Preallocating metadata can be faster when
5078 doing lots of writes, but uses more space. The default is "off".
5079 "compat"
5081 "qcow2" only: Pass the string 1.1 to use the advanced qcow2 format
5082 supported by qemu ≥ 1.1.
5083 "clustersize"
5085 "qcow2" only: Change the qcow2 cluster size. The default is 65536
5086 (bytes) and this setting may be any power of two between 512 and
5087 2097152.
5088 Note that this call does not add the new disk to the handle. You may
5090 need to call "guestfs_add_drive_opts" separately.
5091 This function returns 0 on success or -1 on error.
5093 (Added in 1.25.31)
5095 guestfs_disk_create_va
5097 int
5098 guestfs_disk_create_va (guestfs_h *g,
5099 const char *filename,
5100 const char *format,
5101 int64_t size,
5102 va_list args);
5103 This is the "va_list variant" of "guestfs_disk_create".
5105 See "CALLS WITH OPTIONAL ARGUMENTS".
5107 guestfs_disk_create_argv
5109 int
5110 guestfs_disk_create_argv (guestfs_h *g,
5111 const char *filename,
5112 const char *format,
5113 int64_t size,
5114 const struct guestfs_disk_create_argv *optargs);
5115 This is the "argv variant" of "guestfs_disk_create".
5117 See "CALLS WITH OPTIONAL ARGUMENTS".
5119 guestfs_disk_format
5121 char *
5122 guestfs_disk_format (guestfs_h *g,
5123 const char *filename);
5124 Detect and return the format of the disk image called filename.
5126 filename can also be a host device, etc. If the format of the image
5127 could not be detected, then "unknown" is returned.
5128 Note that detecting the disk format can be insecure under some
5130 circumstances. See "CVE-2010-3851".
5131 See also: "DISK IMAGE FORMATS"
5133 This function returns a string, or NULL on error. The caller must free
5135 the returned string after use.
5136 (Added in 1.19.38)
5138 guestfs_disk_has_backing_file
5140 int
5141 guestfs_disk_has_backing_file (guestfs_h *g,
5142 const char *filename);
5143 Detect and return whether the disk image filename has a backing file.
5145 Note that detecting disk features can be insecure under some
5147 circumstances. See "CVE-2010-3851".
5148 This function returns a C truth value on success or -1 on error.
5150 (Added in 1.19.39)
5152 guestfs_disk_virtual_size
5154 int64_t
5155 guestfs_disk_virtual_size (guestfs_h *g,
5156 const char *filename);
5157 Detect and return the virtual size in bytes of the disk image called
5159 filename.
5160 Note that detecting disk features can be insecure under some
5162 circumstances. See "CVE-2010-3851".
5163 On error this function returns -1.
5165 (Added in 1.19.39)
5167 guestfs_dmesg
5169 char *
5170 guestfs_dmesg (guestfs_h *g);
5171 This returns the kernel messages ("dmesg" output) from the guest
5173 kernel. This is sometimes useful for extended debugging of problems.
5174 Another way to get the same information is to enable verbose messages
5176 with "guestfs_set_verbose" or by setting the environment variable
5177 "LIBGUESTFS_DEBUG=1" before running the program.
5178 This function returns a string, or NULL on error. The caller must free
5180 the returned string after use.
5181 (Added in 1.0.18)
5183 guestfs_download
5185 int
5186 guestfs_download (guestfs_h *g,
5187 const char *remotefilename,
5188 const char *filename);
5189 Download file remotefilename and save it as filename on the local
5191 machine.
5192 filename can also be a named pipe.
5194 See also "guestfs_upload", "guestfs_cat".
5196 This function returns 0 on success or -1 on error.
5198 This long-running command can generate progress notification messages
5200 so that the caller can display a progress bar or indicator. To receive
5201 these messages, the caller must register a progress event callback.
5202 See "GUESTFS_EVENT_PROGRESS".
5203 (Added in 1.0.2)
5205 guestfs_download_blocks
5207 int
5208 guestfs_download_blocks (guestfs_h *g,
5209 const char *device,
5210 int64_t start,
5211 int64_t stop,
5212 const char *filename,
5213 ...);
5214 You may supply a list of optional arguments to this call. Use zero or
5216 more of the following pairs of parameters, and terminate the list with
5217 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5218 GUESTFS_DOWNLOAD_BLOCKS_UNALLOCATED, int unallocated,
5220 Download the data units from start address to stop from the disk
5222 partition (eg. /dev/sda1) and save them as filename on the local
5223 machine.
5224 The use of this API on sparse disk image formats such as QCOW, may
5226 result in large zero-filled files downloaded on the host.
5227 The size of a data unit varies across filesystem implementations. On
5229 NTFS filesystems data units are referred as clusters while on ExtX ones
5230 they are referred as fragments.
5231 If the optional "unallocated" flag is true (default is false), only the
5233 unallocated blocks will be extracted. This is useful to detect hidden
5234 data or to retrieve deleted files which data units have not been
5235 overwritten yet.
5236 This function returns 0 on success or -1 on error.
5238 This long-running command can generate progress notification messages
5240 so that the caller can display a progress bar or indicator. To receive
5241 these messages, the caller must register a progress event callback.
5242 See "GUESTFS_EVENT_PROGRESS".
5243 This function depends on the feature "sleuthkit". See also
5245 "guestfs_feature_available".
5246 (Added in 1.33.45)
5248 guestfs_download_blocks_va
5250 int
5251 guestfs_download_blocks_va (guestfs_h *g,
5252 const char *device,
5253 int64_t start,
5254 int64_t stop,
5255 const char *filename,
5256 va_list args);
5257 This is the "va_list variant" of "guestfs_download_blocks".
5259 See "CALLS WITH OPTIONAL ARGUMENTS".
5261 guestfs_download_blocks_argv
5263 int
5264 guestfs_download_blocks_argv (guestfs_h *g,
5265 const char *device,
5266 int64_t start,
5267 int64_t stop,
5268 const char *filename,
5269 const struct guestfs_download_blocks_argv *optargs);
5270 This is the "argv variant" of "guestfs_download_blocks".
5272 See "CALLS WITH OPTIONAL ARGUMENTS".
5274 guestfs_download_inode
5276 int
5277 guestfs_download_inode (guestfs_h *g,
5278 const char *device,
5279 int64_t inode,
5280 const char *filename);
5281 Download a file given its inode from the disk partition (eg. /dev/sda1)
5283 and save it as filename on the local machine.
5284 It is not required to mount the disk to run this command.
5286 The command is capable of downloading deleted or inaccessible files.
5288 This function returns 0 on success or -1 on error.
5290 This long-running command can generate progress notification messages
5292 so that the caller can display a progress bar or indicator. To receive
5293 these messages, the caller must register a progress event callback.
5294 See "GUESTFS_EVENT_PROGRESS".
5295 This function depends on the feature "sleuthkit". See also
5297 "guestfs_feature_available".
5298 (Added in 1.33.14)
5300 guestfs_download_offset
5302 int
5303 guestfs_download_offset (guestfs_h *g,
5304 const char *remotefilename,
5305 const char *filename,
5306 int64_t offset,
5307 int64_t size);
5308 Download file remotefilename and save it as filename on the local
5310 machine.
5311 remotefilename is read for "size" bytes starting at "offset" (this
5313 region must be within the file or device).
5314 Note that there is no limit on the amount of data that can be
5316 downloaded with this call, unlike with "guestfs_pread", and this call
5317 always reads the full amount unless an error occurs.
5318 See also "guestfs_download", "guestfs_pread".
5320 This function returns 0 on success or -1 on error.
5322 This long-running command can generate progress notification messages
5324 so that the caller can display a progress bar or indicator. To receive
5325 these messages, the caller must register a progress event callback.
5326 See "GUESTFS_EVENT_PROGRESS".
5327 (Added in 1.5.17)
5329 guestfs_drop_caches
5331 int
5332 guestfs_drop_caches (guestfs_h *g,
5333 int whattodrop);
5334 This instructs the guest kernel to drop its page cache, and/or dentries
5336 and inode caches. The parameter "whattodrop" tells the kernel what
5337 precisely to drop, see http://linux-mm.org/Drop_Caches
5338 Setting "whattodrop" to 3 should drop everything.
5340 This automatically calls sync(2) before the operation, so that the
5342 maximum guest memory is freed.
5343 This function returns 0 on success or -1 on error.
5345 (Added in 1.0.18)
5347 guestfs_du
5349 int64_t
5350 guestfs_du (guestfs_h *g,
5351 const char *path);
5352 This command runs the "du -s" command to estimate file space usage for
5354 "path".
5355 "path" can be a file or a directory. If "path" is a directory then the
5357 estimate includes the contents of the directory and all subdirectories
5358 (recursively).
5359 The result is the estimated size in kilobytes (ie. units of 1024
5361 bytes).
5362 On error this function returns -1.
5364 This long-running command can generate progress notification messages
5366 so that the caller can display a progress bar or indicator. To receive
5367 these messages, the caller must register a progress event callback.
5368 See "GUESTFS_EVENT_PROGRESS".
5369 (Added in 1.0.54)
5371 guestfs_e2fsck
5373 int
5374 guestfs_e2fsck (guestfs_h *g,
5375 const char *device,
5376 ...);
5377 You may supply a list of optional arguments to this call. Use zero or
5379 more of the following pairs of parameters, and terminate the list with
5380 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
5381 GUESTFS_E2FSCK_CORRECT, int correct,
5383 GUESTFS_E2FSCK_FORCEALL, int forceall,
5384 This runs the ext2/ext3 filesystem checker on "device". It can take
5386 the following optional arguments:
5387 "correct"
5389 Automatically repair the file system. This option will cause e2fsck
5390 to automatically fix any filesystem problems that can be safely
5391 fixed without human intervention.
5392 This option may not be specified at the same time as the "forceall"
5394 option.
5395 "forceall"
5397 Assume an answer of ‘yes’ to all questions; allows e2fsck to be
5398 used non-interactively.
5399 This option may not be specified at the same time as the "correct"
5401 option.
5402 This function returns 0 on success or -1 on error.
5404 (Added in 1.15.17)
5406 guestfs_e2fsck_va
5408 int
5409 guestfs_e2fsck_va (guestfs_h *g,
5410 const char *device,
5411 va_list args);
5412 This is the "va_list variant" of "guestfs_e2fsck".
5414 See "CALLS WITH OPTIONAL ARGUMENTS".
5416 guestfs_e2fsck_argv
5418 int
5419 guestfs_e2fsck_argv (guestfs_h *g,
5420 const char *device,
5421 const struct guestfs_e2fsck_argv *optargs);
5422 This is the "argv variant" of "guestfs_e2fsck".
5424 See "CALLS WITH OPTIONAL ARGUMENTS".
5426 guestfs_e2fsck_f
5428 int
5429 guestfs_e2fsck_f (guestfs_h *g,
5430 const char *device);
5431 This function is deprecated. In new code, use the "guestfs_e2fsck"
5433 call instead.
5434 Deprecated functions will not be removed from the API, but the fact
5436 that they are deprecated indicates that there are problems with correct
5437 use of these functions.
5438 This runs "e2fsck -p -f device", ie. runs the ext2/ext3 filesystem
5440 checker on "device", noninteractively (-p), even if the filesystem
5441 appears to be clean (-f).
5442 This function returns 0 on success or -1 on error.
5444 (Added in 1.0.29)
5446 guestfs_echo_daemon
5448 char *
5449 guestfs_echo_daemon (guestfs_h *g,
5450 char *const *words);
5451 This command concatenates the list of "words" passed with single spaces
5453 between them and returns the resulting string.
5454 You can use this command to test the connection through to the daemon.
5456 See also "guestfs_ping_daemon".
5458 This function returns a string, or NULL on error. The caller must free
5460 the returned string after use.
5461 (Added in 1.0.69)
5463 guestfs_egrep
5465 char **
5466 guestfs_egrep (guestfs_h *g,
5467 const char *regex,
5468 const char *path);
5469 This function is deprecated. In new code, use the "guestfs_grep" call
5471 instead.
5472 Deprecated functions will not be removed from the API, but the fact
5474 that they are deprecated indicates that there are problems with correct
5475 use of these functions.
5476 This calls the external "egrep" program and returns the matching lines.
5478 This function returns a NULL-terminated array of strings (like
5480 environ(3)), or NULL if there was an error. The caller must free the
5481 strings and the array after use.
5482 Because of the message protocol, there is a transfer limit of somewhere
5484 between 2MB and 4MB. See "PROTOCOL LIMITS".
5485 (Added in 1.0.66)
5487 guestfs_egrepi
5489 char **
5490 guestfs_egrepi (guestfs_h *g,
5491 const char *regex,
5492 const char *path);
5493 This function is deprecated. In new code, use the "guestfs_grep" call
5495 instead.
5496 Deprecated functions will not be removed from the API, but the fact
5498 that they are deprecated indicates that there are problems with correct
5499 use of these functions.
5500 This calls the external "egrep -i" program and returns the matching
5502 lines.
5503 This function returns a NULL-terminated array of strings (like
5505 environ(3)), or NULL if there was an error. The caller must free the
5506 strings and the array after use.
5507 Because of the message protocol, there is a transfer limit of somewhere
5509 between 2MB and 4MB. See "PROTOCOL LIMITS".
5510 (Added in 1.0.66)
5512 guestfs_equal
5514 int
5515 guestfs_equal (guestfs_h *g,
5516 const char *file1,
5517 const char *file2);
5518 This compares the two files file1 and file2 and returns true if their
5520 content is exactly equal, or false otherwise.
5521 The external cmp(1) program is used for the comparison.
5523 This function returns a C truth value on success or -1 on error.
5525 (Added in 1.0.18)
5527 guestfs_exists
5529 int
5530 guestfs_exists (guestfs_h *g,
5531 const char *path);
5532 This returns "true" if and only if there is a file, directory (or
5534 anything) with the given "path" name.
5535 See also "guestfs_is_file", "guestfs_is_dir", "guestfs_stat".
5537 This function returns a C truth value on success or -1 on error.
5539 (Added in 0.8)
5541 guestfs_extlinux
5543 int
5544 guestfs_extlinux (guestfs_h *g,
5545 const char *directory);
5546 Install the SYSLINUX bootloader on the device mounted at directory.
5548 Unlike "guestfs_syslinux" which requires a FAT filesystem, this can be
5549 used on an ext2/3/4 or btrfs filesystem.
5550 The directory parameter can be either a mountpoint, or a directory
5552 within the mountpoint.
5553 You also have to mark the partition as "active"
5555 ("guestfs_part_set_bootable") and a Master Boot Record must be
5556 installed (eg. using "guestfs_pwrite_device") on the first sector of
5557 the whole disk. The SYSLINUX package comes with some suitable Master
5558 Boot Records. See the extlinux(1) man page for further information.
5559 Additional configuration can be supplied to SYSLINUX by placing a file
5561 called extlinux.conf on the filesystem under directory. For further
5562 information about the contents of this file, see extlinux(1).
5563 See also "guestfs_syslinux".
5565 This function returns 0 on success or -1 on error.
5567 This function depends on the feature "extlinux". See also
5569 "guestfs_feature_available".
5570 (Added in 1.21.27)
5572 guestfs_f2fs_expand
5574 int
5575 guestfs_f2fs_expand (guestfs_h *g,
5576 const char *device);
5577 This expands a f2fs filesystem to match the size of the underlying
5579 device.
5580 This function returns 0 on success or -1 on error.
5582 This function depends on the feature "f2fs". See also
5584 "guestfs_feature_available".
5585 (Added in 1.39.3)
5587 guestfs_fallocate
5589 int
5590 guestfs_fallocate (guestfs_h *g,
5591 const char *path,
5592 int len);
5593 This function is deprecated. In new code, use the
5595 "guestfs_fallocate64" call instead.
5596 Deprecated functions will not be removed from the API, but the fact
5598 that they are deprecated indicates that there are problems with correct
5599 use of these functions.
5600 This command preallocates a file (containing zero bytes) named "path"
5602 of size "len" bytes. If the file exists already, it is overwritten.
5603 Do not confuse this with the guestfish-specific "alloc" command which
5605 allocates a file in the host and attaches it as a device.
5606 This function returns 0 on success or -1 on error.
5608 (Added in 1.0.66)
5610 guestfs_fallocate64
5612 int
5613 guestfs_fallocate64 (guestfs_h *g,
5614 const char *path,
5615 int64_t len);
5616 This command preallocates a file (containing zero bytes) named "path"
5618 of size "len" bytes. If the file exists already, it is overwritten.
5619 Note that this call allocates disk blocks for the file. To create a
5621 sparse file use "guestfs_truncate_size" instead.
5622 The deprecated call "guestfs_fallocate" does the same, but owing to an
5624 oversight it only allowed 30 bit lengths to be specified, effectively
5625 limiting the maximum size of files created through that call to 1GB.
5626 Do not confuse this with the guestfish-specific "alloc" and "sparse"
5628 commands which create a file in the host and attach it as a device.
5629 This function returns 0 on success or -1 on error.
5631 (Added in 1.3.17)
5633 guestfs_feature_available
5635 int
5636 guestfs_feature_available (guestfs_h *g,
5637 char *const *groups);
5638 This is the same as "guestfs_available", but unlike that call it
5640 returns a simple true/false boolean result, instead of throwing an
5641 exception if a feature is not found. For other documentation see
5642 "guestfs_available".
5643 This function returns a C truth value on success or -1 on error.
5645 (Added in 1.21.26)
5647 guestfs_fgrep
5649 char **
5650 guestfs_fgrep (guestfs_h *g,
5651 const char *pattern,
5652 const char *path);
5653 This function is deprecated. In new code, use the "guestfs_grep" call
5655 instead.
5656 Deprecated functions will not be removed from the API, but the fact
5658 that they are deprecated indicates that there are problems with correct
5659 use of these functions.
5660 This calls the external "fgrep" program and returns the matching lines.
5662 This function returns a NULL-terminated array of strings (like
5664 environ(3)), or NULL if there was an error. The caller must free the
5665 strings and the array after use.
5666 Because of the message protocol, there is a transfer limit of somewhere
5668 between 2MB and 4MB. See "PROTOCOL LIMITS".
5669 (Added in 1.0.66)
5671 guestfs_fgrepi
5673 char **
5674 guestfs_fgrepi (guestfs_h *g,
5675 const char *pattern,
5676 const char *path);
5677 This function is deprecated. In new code, use the "guestfs_grep" call
5679 instead.
5680 Deprecated functions will not be removed from the API, but the fact
5682 that they are deprecated indicates that there are problems with correct
5683 use of these functions.
5684 This calls the external "fgrep -i" program and returns the matching
5686 lines.
5687 This function returns a NULL-terminated array of strings (like
5689 environ(3)), or NULL if there was an error. The caller must free the
5690 strings and the array after use.
5691 Because of the message protocol, there is a transfer limit of somewhere
5693 between 2MB and 4MB. See "PROTOCOL LIMITS".
5694 (Added in 1.0.66)
5696 guestfs_file
5698 char *
5699 guestfs_file (guestfs_h *g,
5700 const char *path);
5701 This call uses the standard file(1) command to determine the type or
5703 contents of the file.
5704 This call will also transparently look inside various types of
5706 compressed file.
5707 The exact command which runs is "file -zb path". Note in particular
5709 that the filename is not prepended to the output (the -b option).
5710 The output depends on the output of the underlying file(1) command and
5712 it can change in future in ways beyond our control. In other words,
5713 the output is not guaranteed by the ABI.
5714 See also: file(1), "guestfs_vfs_type", "guestfs_lstat",
5716 "guestfs_is_file", "guestfs_is_blockdev" (etc), "guestfs_is_zero".
5717 This function returns a string, or NULL on error. The caller must free
5719 the returned string after use.
5720 (Added in 1.9.1)
5722 guestfs_file_architecture
5724 char *
5725 guestfs_file_architecture (guestfs_h *g,
5726 const char *filename);
5727 This detects the architecture of the binary filename, and returns it if
5729 known.
5730 Currently defined architectures are:
5732 "aarch64"
5734 64 bit ARM.
5735 "arm"
5737 32 bit ARM.
5738 "i386"
5740 This string is returned for all 32 bit i386, i486, i586, i686
5741 binaries irrespective of the precise processor requirements of the
5742 binary.
5743 "ia64"
5745 Intel Itanium.
5746 "ppc"
5748 32 bit Power PC.
5749 "ppc64"
5751 64 bit Power PC (big endian).
5752 "ppc64le"
5754 64 bit Power PC (little endian).
5755 "riscv32"
5757 "riscv64"
5758 "riscv128"
5759 RISC-V 32-, 64- or 128-bit variants.
5760 "s390"
5762 31 bit IBM S/390.
5763 "s390x"
5765 64 bit IBM S/390.
5766 "sparc"
5768 32 bit SPARC.
5769 "sparc64"
5771 64 bit SPARC V9 and above.
5772 "x86_64"
5774 64 bit x86-64.
5775 Libguestfs may return other architecture strings in future.
5777 The function works on at least the following types of files:
5779 · many types of Un*x and Linux binary
5781 · many types of Un*x and Linux shared library
5783 · Windows Win32 and Win64 binaries
5785 · Windows Win32 and Win64 DLLs
5787 Win32 binaries and DLLs return "i386".
5789 Win64 binaries and DLLs return "x86_64".
5791 · Linux kernel modules
5793 · Linux new-style initrd images
5795 · some non-x86 Linux vmlinuz kernels
5797 What it can't do currently:
5799 · static libraries (libfoo.a)
5801 · Linux old-style initrd as compressed ext2 filesystem (RHEL 3)
5803 · x86 Linux vmlinuz kernels
5805 x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32-
5807 and compressed code, and are horribly hard to unpack. If you want
5808 to find the architecture of a kernel, use the architecture of the
5809 associated initrd or kernel module(s) instead.
5810 This function returns a string, or NULL on error. The caller must free
5812 the returned string after use.
5813 (Added in 1.5.3)
5815 guestfs_filesize
5817 int64_t
5818 guestfs_filesize (guestfs_h *g,
5819 const char *file);
5820 This command returns the size of file in bytes.
5822 To get other stats about a file, use "guestfs_stat", "guestfs_lstat",
5824 "guestfs_is_dir", "guestfs_is_file" etc. To get the size of block
5825 devices, use "guestfs_blockdev_getsize64".
5826 On error this function returns -1.
5828 (Added in 1.0.82)
5830 guestfs_filesystem_available
5832 int
5833 guestfs_filesystem_available (guestfs_h *g,
5834 const char *filesystem);
5835 Check whether libguestfs supports the named filesystem. The argument
5837 "filesystem" is a filesystem name, such as "ext3".
5838 You must call "guestfs_launch" before using this command.
5840 This is mainly useful as a negative test. If this returns true, it
5842 doesn't mean that a particular filesystem can be created or mounted,
5843 since filesystems can fail for other reasons such as it being a later
5844 version of the filesystem, or having incompatible features, or lacking
5845 the right mkfs.<fs> tool.
5846 See also "guestfs_available", "guestfs_feature_available",
5848 "AVAILABILITY".
5849 This function returns a C truth value on success or -1 on error.
5851 (Added in 1.19.5)
5853 guestfs_filesystem_walk
5855 struct guestfs_tsk_dirent_list *
5856 guestfs_filesystem_walk (guestfs_h *g,
5857 const char *device);
5858 Walk through the internal structures of a disk partition (eg.
5860 /dev/sda1) in order to return a list of all the files and directories
5861 stored within.
5862 It is not necessary to mount the disk partition to run this command.
5864 All entries in the filesystem are returned. This function can list
5866 deleted or unaccessible files. The entries are not sorted.
5867 The "tsk_dirent" structure contains the following fields.
5869 "tsk_inode"
5871 Filesystem reference number of the node. It might be 0 if the node
5872 has been deleted.
5873 "tsk_type"
5875 Basic file type information. See below for a detailed list of
5876 values.
5877 "tsk_size"
5879 File size in bytes. It might be "-1" if the node has been deleted.
5880 "tsk_name"
5882 The file path relative to its directory.
5883 "tsk_flags"
5885 Bitfield containing extra information regarding the entry. It
5886 contains the logical OR of the following values:
5887 0x0001
5889 If set to 1, the file is allocated and visible within the
5890 filesystem. Otherwise, the file has been deleted. Under
5891 certain circumstances, the function "download_inode" can be
5892 used to recover deleted files.
5893 0x0002
5895 Filesystem such as NTFS and Ext2 or greater, separate the file
5896 name from the metadata structure. The bit is set to 1 when the
5897 file name is in an unallocated state and the metadata structure
5898 is in an allocated one. This generally implies the metadata
5899 has been reallocated to a new file. Therefore, information
5900 such as file type, file size, timestamps, number of links and
5901 symlink target might not correspond with the ones of the
5902 original deleted entry.
5903 0x0004
5905 The bit is set to 1 when the file is compressed using
5906 filesystem native compression support (NTFS). The API is not
5907 able to detect application level compression.
5908 "tsk_atime_sec"
5910 "tsk_atime_nsec"
5911 "tsk_mtime_sec"
5912 "tsk_mtime_nsec"
5913 "tsk_ctime_sec"
5914 "tsk_ctime_nsec"
5915 "tsk_crtime_sec"
5916 "tsk_crtime_nsec"
5917 Respectively, access, modification, last status change and creation
5918 time in Unix format in seconds and nanoseconds.
5919 "tsk_nlink"
5921 Number of file names pointing to this entry.
5922 "tsk_link"
5924 If the entry is a symbolic link, this field will contain the path
5925 to the target file.
5926 The "tsk_type" field will contain one of the following characters:
5928 'b' Block special
5930 'c' Char special
5932 'd' Directory
5934 'f' FIFO (named pipe)
5936 'l' Symbolic link
5938 'r' Regular file
5940 's' Socket
5942 'h' Shadow inode (Solaris)
5944 'w' Whiteout inode (BSD)
5946 'u' Unknown file type
5948 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
5950 there was an error. The caller must call
5951 "guestfs_free_tsk_dirent_list" after use.
5952 This long-running command can generate progress notification messages
5954 so that the caller can display a progress bar or indicator. To receive
5955 these messages, the caller must register a progress event callback.
5956 See "GUESTFS_EVENT_PROGRESS".
5957 This function depends on the feature "libtsk". See also
5959 "guestfs_feature_available".
5960 (Added in 1.33.39)
5962 guestfs_fill
5964 int
5965 guestfs_fill (guestfs_h *g,
5966 int c,
5967 int len,
5968 const char *path);
5969 This command creates a new file called "path". The initial content of
5971 the file is "len" octets of "c", where "c" must be a number in the
5972 range "[0..255]".
5973 To fill a file with zero bytes (sparsely), it is much more efficient to
5975 use "guestfs_truncate_size". To create a file with a pattern of
5976 repeating bytes use "guestfs_fill_pattern".
5977 This function returns 0 on success or -1 on error.
5979 This long-running command can generate progress notification messages
5981 so that the caller can display a progress bar or indicator. To receive
5982 these messages, the caller must register a progress event callback.
5983 See "GUESTFS_EVENT_PROGRESS".
5984 (Added in 1.0.79)
5986 guestfs_fill_dir
5988 int
5989 guestfs_fill_dir (guestfs_h *g,
5990 const char *dir,
5991 int nr);
5992 This function, useful for testing filesystems, creates "nr" empty files
5994 in the directory "dir" with names 00000000 through "nr-1" (ie. each
5995 file name is 8 digits long padded with zeroes).
5996 This function returns 0 on success or -1 on error.
5998 (Added in 1.19.32)
6000 guestfs_fill_pattern
6002 int
6003 guestfs_fill_pattern (guestfs_h *g,
6004 const char *pattern,
6005 int len,
6006 const char *path);
6007 This function is like "guestfs_fill" except that it creates a new file
6009 of length "len" containing the repeating pattern of bytes in "pattern".
6010 The pattern is truncated if necessary to ensure the length of the file
6011 is exactly "len" bytes.
6012 This function returns 0 on success or -1 on error.
6014 This long-running command can generate progress notification messages
6016 so that the caller can display a progress bar or indicator. To receive
6017 these messages, the caller must register a progress event callback.
6018 See "GUESTFS_EVENT_PROGRESS".
6019 (Added in 1.3.12)
6021 guestfs_find
6023 char **
6024 guestfs_find (guestfs_h *g,
6025 const char *directory);
6026 This command lists out all files and directories, recursively, starting
6028 at directory. It is essentially equivalent to running the shell
6029 command "find directory -print" but some post-processing happens on the
6030 output, described below.
6031 This returns a list of strings without any prefix. Thus if the
6033 directory structure was:
6034 /tmp/a
6036 /tmp/b
6037 /tmp/c/d
6038 then the returned list from "guestfs_find" /tmp would be 4 elements:
6040 a
6042 b
6043 c
6044 c/d
6045 If directory is not a directory, then this command returns an error.
6047 The returned list is sorted.
6049 This function returns a NULL-terminated array of strings (like
6051 environ(3)), or NULL if there was an error. The caller must free the
6052 strings and the array after use.
6053 (Added in 1.0.27)
6055 guestfs_find0
6057 int
6058 guestfs_find0 (guestfs_h *g,
6059 const char *directory,
6060 const char *files);
6061 This command lists out all files and directories, recursively, starting
6063 at directory, placing the resulting list in the external file called
6064 files.
6065 This command works the same way as "guestfs_find" with the following
6067 exceptions:
6068 · The resulting list is written to an external file.
6070 · Items (filenames) in the result are separated by "\0" characters.
6072 See find(1) option -print0.
6073 · The result list is not sorted.
6075 This function returns 0 on success or -1 on error.
6077 (Added in 1.0.74)
6079 guestfs_find_inode
6081 struct guestfs_tsk_dirent_list *
6082 guestfs_find_inode (guestfs_h *g,
6083 const char *device,
6084 int64_t inode);
6085 Searches all the entries associated with the given inode.
6087 For each entry, a "tsk_dirent" structure is returned. See
6089 "filesystem_walk" for more information about "tsk_dirent" structures.
6090 This function returns a "struct guestfs_tsk_dirent_list *", or NULL if
6092 there was an error. The caller must call
6093 "guestfs_free_tsk_dirent_list" after use.
6094 This long-running command can generate progress notification messages
6096 so that the caller can display a progress bar or indicator. To receive
6097 these messages, the caller must register a progress event callback.
6098 See "GUESTFS_EVENT_PROGRESS".
6099 This function depends on the feature "libtsk". See also
6101 "guestfs_feature_available".
6102 (Added in 1.35.6)
6104 guestfs_findfs_label
6106 char *
6107 guestfs_findfs_label (guestfs_h *g,
6108 const char *label);
6109 This command searches the filesystems and returns the one which has the
6111 given label. An error is returned if no such filesystem can be found.
6112 To find the label of a filesystem, use "guestfs_vfs_label".
6114 This function returns a string, or NULL on error. The caller must free
6116 the returned string after use.
6117 (Added in 1.5.3)
6119 guestfs_findfs_uuid
6121 char *
6122 guestfs_findfs_uuid (guestfs_h *g,
6123 const char *uuid);
6124 This command searches the filesystems and returns the one which has the
6126 given UUID. An error is returned if no such filesystem can be found.
6127 To find the UUID of a filesystem, use "guestfs_vfs_uuid".
6129 This function returns a string, or NULL on error. The caller must free
6131 the returned string after use.
6132 (Added in 1.5.3)
6134 guestfs_fsck
6136 int
6137 guestfs_fsck (guestfs_h *g,
6138 const char *fstype,
6139 const char *device);
6140 This runs the filesystem checker (fsck) on "device" which should have
6142 filesystem type "fstype".
6143 The returned integer is the status. See fsck(8) for the list of status
6145 codes from "fsck".
6146 Notes:
6148 · Multiple status codes can be summed together.
6150 · A non-zero return code can mean "success", for example if errors
6152 have been corrected on the filesystem.
6153 · Checking or repairing NTFS volumes is not supported (by linux-
6155 ntfs).
6156 This command is entirely equivalent to running "fsck -a -t fstype
6158 device".
6159 On error this function returns -1.
6161 (Added in 1.0.16)
6163 guestfs_fstrim
6165 int
6166 guestfs_fstrim (guestfs_h *g,
6167 const char *mountpoint,
6168 ...);
6169 You may supply a list of optional arguments to this call. Use zero or
6171 more of the following pairs of parameters, and terminate the list with
6172 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6173 GUESTFS_FSTRIM_OFFSET, int64_t offset,
6175 GUESTFS_FSTRIM_LENGTH, int64_t length,
6176 GUESTFS_FSTRIM_MINIMUMFREEEXTENT, int64_t minimumfreeextent,
6177 Trim the free space in the filesystem mounted on "mountpoint". The
6179 filesystem must be mounted read-write.
6180 The filesystem contents are not affected, but any free space in the
6182 filesystem is "trimmed", that is, given back to the host device, thus
6183 making disk images more sparse, allowing unused space in qcow2 files to
6184 be reused, etc.
6185 This operation requires support in libguestfs, the mounted filesystem,
6187 the host filesystem, qemu and the host kernel. If this support isn't
6188 present it may give an error or even appear to run but do nothing.
6189 In the case where the kernel vfs driver does not support trimming, this
6191 call will fail with errno set to "ENOTSUP". Currently this happens
6192 when trying to trim FAT filesystems.
6193 See also "guestfs_zero_free_space". That is a slightly different
6195 operation that turns free space in the filesystem into zeroes. It is
6196 valid to call "guestfs_fstrim" either instead of, or after calling
6197 "guestfs_zero_free_space".
6198 This function returns 0 on success or -1 on error.
6200 This function depends on the feature "fstrim". See also
6202 "guestfs_feature_available".
6203 (Added in 1.19.6)
6205 guestfs_fstrim_va
6207 int
6208 guestfs_fstrim_va (guestfs_h *g,
6209 const char *mountpoint,
6210 va_list args);
6211 This is the "va_list variant" of "guestfs_fstrim".
6213 See "CALLS WITH OPTIONAL ARGUMENTS".
6215 guestfs_fstrim_argv
6217 int
6218 guestfs_fstrim_argv (guestfs_h *g,
6219 const char *mountpoint,
6220 const struct guestfs_fstrim_argv *optargs);
6221 This is the "argv variant" of "guestfs_fstrim".
6223 See "CALLS WITH OPTIONAL ARGUMENTS".
6225 guestfs_get_append
6227 const char *
6228 guestfs_get_append (guestfs_h *g);
6229 Return the additional kernel options which are added to the libguestfs
6231 appliance kernel command line.
6232 If "NULL" then no options are added.
6234 This function returns a string which may be NULL. There is no way to
6236 return an error from this function. The string is owned by the guest
6237 handle and must not be freed.
6238 (Added in 1.0.26)
6240 guestfs_get_attach_method
6242 char *
6243 guestfs_get_attach_method (guestfs_h *g);
6244 This function is deprecated. In new code, use the
6246 "guestfs_get_backend" call instead.
6247 Deprecated functions will not be removed from the API, but the fact
6249 that they are deprecated indicates that there are problems with correct
6250 use of these functions.
6251 Return the current backend.
6253 See "guestfs_set_backend" and "BACKEND".
6255 This function returns a string, or NULL on error. The caller must free
6257 the returned string after use.
6258 (Added in 1.9.8)
6260 guestfs_get_autosync
6262 int
6263 guestfs_get_autosync (guestfs_h *g);
6264 Get the autosync flag.
6266 This function returns a C truth value on success or -1 on error.
6268 (Added in 0.3)
6270 guestfs_get_backend
6272 char *
6273 guestfs_get_backend (guestfs_h *g);
6274 Return the current backend.
6276 This handle property was previously called the "attach method".
6278 See "guestfs_set_backend" and "BACKEND".
6280 This function returns a string, or NULL on error. The caller must free
6282 the returned string after use.
6283 (Added in 1.21.26)
6285 guestfs_get_backend_setting
6287 char *
6288 guestfs_get_backend_setting (guestfs_h *g,
6289 const char *name);
6290 Find a backend setting string which is either "name" or begins with
6292 "name=". If "name", this returns the string "1". If "name=", this
6293 returns the part after the equals sign (which may be an empty string).
6294 If no such setting is found, this function throws an error. The errno
6296 (see "guestfs_last_errno") will be "ESRCH" in this case.
6297 See "BACKEND", "BACKEND SETTINGS".
6299 This function returns a string, or NULL on error. The caller must free
6301 the returned string after use.
6302 (Added in 1.27.2)
6304 guestfs_get_backend_settings
6306 char **
6307 guestfs_get_backend_settings (guestfs_h *g);
6308 Return the current backend settings.
6310 This call returns all backend settings strings. If you want to find a
6312 single backend setting, see "guestfs_get_backend_setting".
6313 See "BACKEND", "BACKEND SETTINGS".
6315 This function returns a NULL-terminated array of strings (like
6317 environ(3)), or NULL if there was an error. The caller must free the
6318 strings and the array after use.
6319 (Added in 1.25.24)
6321 guestfs_get_cachedir
6323 char *
6324 guestfs_get_cachedir (guestfs_h *g);
6325 Get the directory used by the handle to store the appliance cache.
6327 This function returns a string, or NULL on error. The caller must free
6329 the returned string after use.
6330 (Added in 1.19.58)
6332 guestfs_get_direct
6334 int
6335 guestfs_get_direct (guestfs_h *g);
6336 This function is deprecated. In new code, use the
6338 "guestfs_internal_get_console_socket" call instead.
6339 Deprecated functions will not be removed from the API, but the fact
6341 that they are deprecated indicates that there are problems with correct
6342 use of these functions.
6343 Return the direct appliance mode flag.
6345 This function returns a C truth value on success or -1 on error.
6347 (Added in 1.0.72)
6349 guestfs_get_e2attrs
6351 char *
6352 guestfs_get_e2attrs (guestfs_h *g,
6353 const char *file);
6354 This returns the file attributes associated with file.
6356 The attributes are a set of bits associated with each inode which
6358 affect the behaviour of the file. The attributes are returned as a
6359 string of letters (described below). The string may be empty,
6360 indicating that no file attributes are set for this file.
6361 These attributes are only present when the file is located on an
6363 ext2/3/4 filesystem. Using this call on other filesystem types will
6364 result in an error.
6365 The characters (file attributes) in the returned string are currently:
6367 'A' When the file is accessed, its atime is not modified.
6369 'a' The file is append-only.
6371 'c' The file is compressed on-disk.
6373 'D' (Directories only.) Changes to this directory are written
6375 synchronously to disk.
6376 'd' The file is not a candidate for backup (see dump(8)).
6378 'E' The file has compression errors.
6380 'e' The file is using extents.
6382 'h' The file is storing its blocks in units of the filesystem blocksize
6384 instead of sectors.
6385 'I' (Directories only.) The directory is using hashed trees.
6387 'i' The file is immutable. It cannot be modified, deleted or renamed.
6389 No link can be created to this file.
6390 'j' The file is data-journaled.
6392 's' When the file is deleted, all its blocks will be zeroed.
6394 'S' Changes to this file are written synchronously to disk.
6396 'T' (Directories only.) This is a hint to the block allocator that
6398 subdirectories contained in this directory should be spread across
6399 blocks. If not present, the block allocator will try to group
6400 subdirectories together.
6401 't' For a file, this disables tail-merging. (Not used by upstream
6403 implementations of ext2.)
6404 'u' When the file is deleted, its blocks will be saved, allowing the
6406 file to be undeleted.
6407 'X' The raw contents of the compressed file may be accessed.
6409 'Z' The compressed file is dirty.
6411 More file attributes may be added to this list later. Not all file
6413 attributes may be set for all kinds of files. For detailed
6414 information, consult the chattr(1) man page.
6415 See also "guestfs_set_e2attrs".
6417 Don't confuse these attributes with extended attributes (see
6419 "guestfs_getxattr").
6420 This function returns a string, or NULL on error. The caller must free
6422 the returned string after use.
6423 (Added in 1.17.31)
6425 guestfs_get_e2generation
6427 int64_t
6428 guestfs_get_e2generation (guestfs_h *g,
6429 const char *file);
6430 This returns the ext2 file generation of a file. The generation (which
6432 used to be called the "version") is a number associated with an inode.
6433 This is most commonly used by NFS servers.
6434 The generation is only present when the file is located on an ext2/3/4
6436 filesystem. Using this call on other filesystem types will result in
6437 an error.
6438 See "guestfs_set_e2generation".
6440 On error this function returns -1.
6442 (Added in 1.17.31)
6444 guestfs_get_e2label
6446 char *
6447 guestfs_get_e2label (guestfs_h *g,
6448 const char *device);
6449 This function is deprecated. In new code, use the "guestfs_vfs_label"
6451 call instead.
6452 Deprecated functions will not be removed from the API, but the fact
6454 that they are deprecated indicates that there are problems with correct
6455 use of these functions.
6456 This returns the ext2/3/4 filesystem label of the filesystem on
6458 "device".
6459 This function returns a string, or NULL on error. The caller must free
6461 the returned string after use.
6462 (Added in 1.0.15)
6464 guestfs_get_e2uuid
6466 char *
6467 guestfs_get_e2uuid (guestfs_h *g,
6468 const char *device);
6469 This function is deprecated. In new code, use the "guestfs_vfs_uuid"
6471 call instead.
6472 Deprecated functions will not be removed from the API, but the fact
6474 that they are deprecated indicates that there are problems with correct
6475 use of these functions.
6476 This returns the ext2/3/4 filesystem UUID of the filesystem on
6478 "device".
6479 This function returns a string, or NULL on error. The caller must free
6481 the returned string after use.
6482 (Added in 1.0.15)
6484 guestfs_get_hv
6486 char *
6487 guestfs_get_hv (guestfs_h *g);
6488 Return the current hypervisor binary.
6490 This is always non-NULL. If it wasn't set already, then this will
6492 return the default qemu binary name.
6493 This function returns a string, or NULL on error. The caller must free
6495 the returned string after use.
6496 (Added in 1.23.17)
6498 guestfs_get_identifier
6500 const char *
6501 guestfs_get_identifier (guestfs_h *g);
6502 Get the handle identifier. See "guestfs_set_identifier".
6504 This function returns a string, or NULL on error. The string is owned
6506 by the guest handle and must not be freed.
6507 (Added in 1.31.14)
6509 guestfs_get_libvirt_requested_credential_challenge
6511 char *
6512 guestfs_get_libvirt_requested_credential_challenge (guestfs_h *g,
6513 int index);
6514 Get the challenge (provided by libvirt) for the "index"'th requested
6516 credential. If libvirt did not provide a challenge, this returns the
6517 empty string "".
6518 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6520 This function returns a string, or NULL on error. The caller must free
6522 the returned string after use.
6523 (Added in 1.19.52)
6525 guestfs_get_libvirt_requested_credential_defresult
6527 char *
6528 guestfs_get_libvirt_requested_credential_defresult (guestfs_h *g,
6529 int index);
6530 Get the default result (provided by libvirt) for the "index"'th
6532 requested credential. If libvirt did not provide a default result,
6533 this returns the empty string "".
6534 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6536 This function returns a string, or NULL on error. The caller must free
6538 the returned string after use.
6539 (Added in 1.19.52)
6541 guestfs_get_libvirt_requested_credential_prompt
6543 char *
6544 guestfs_get_libvirt_requested_credential_prompt (guestfs_h *g,
6545 int index);
6546 Get the prompt (provided by libvirt) for the "index"'th requested
6548 credential. If libvirt did not provide a prompt, this returns the
6549 empty string "".
6550 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6552 This function returns a string, or NULL on error. The caller must free
6554 the returned string after use.
6555 (Added in 1.19.52)
6557 guestfs_get_libvirt_requested_credentials
6559 char **
6560 guestfs_get_libvirt_requested_credentials (guestfs_h *g);
6561 This should only be called during the event callback for events of type
6563 "GUESTFS_EVENT_LIBVIRT_AUTH".
6564 Return the list of credentials requested by libvirt. Possible values
6566 are a subset of the strings provided when you called
6567 "guestfs_set_libvirt_supported_credentials".
6568 See "LIBVIRT AUTHENTICATION" for documentation and example code.
6570 This function returns a NULL-terminated array of strings (like
6572 environ(3)), or NULL if there was an error. The caller must free the
6573 strings and the array after use.
6574 (Added in 1.19.52)
6576 guestfs_get_memsize
6578 int
6579 guestfs_get_memsize (guestfs_h *g);
6580 This gets the memory size in megabytes allocated to the hypervisor.
6582 If "guestfs_set_memsize" was not called on this handle, and if
6584 "LIBGUESTFS_MEMSIZE" was not set, then this returns the compiled-in
6585 default value for memsize.
6586 For more information on the architecture of libguestfs, see guestfs(3).
6588 On error this function returns -1.
6590 (Added in 1.0.55)
6592 guestfs_get_network
6594 int
6595 guestfs_get_network (guestfs_h *g);
6596 This returns the enable network flag.
6598 This function returns a C truth value on success or -1 on error.
6600 (Added in 1.5.4)
6602 guestfs_get_path
6604 const char *
6605 guestfs_get_path (guestfs_h *g);
6606 Return the current search path.
6608 This is always non-NULL. If it wasn't set already, then this will
6610 return the default path.
6611 This function returns a string, or NULL on error. The string is owned
6613 by the guest handle and must not be freed.
6614 (Added in 0.3)
6616 guestfs_get_pgroup
6618 int
6619 guestfs_get_pgroup (guestfs_h *g);
6620 This returns the process group flag.
6622 This function returns a C truth value on success or -1 on error.
6624 (Added in 1.11.18)
6626 guestfs_get_pid
6628 int
6629 guestfs_get_pid (guestfs_h *g);
6630 Return the process ID of the hypervisor. If there is no hypervisor
6632 running, then this will return an error.
6633 This is an internal call used for debugging and testing.
6635 On error this function returns -1.
6637 (Added in 1.0.56)
6639 guestfs_get_program
6641 const char *
6642 guestfs_get_program (guestfs_h *g);
6643 Get the program name. See "guestfs_set_program".
6645 This function returns a string, or NULL on error. The string is owned
6647 by the guest handle and must not be freed.
6648 (Added in 1.21.29)
6650 guestfs_get_qemu
6652 const char *
6653 guestfs_get_qemu (guestfs_h *g);
6654 This function is deprecated. In new code, use the "guestfs_get_hv"
6656 call instead.
6657 Deprecated functions will not be removed from the API, but the fact
6659 that they are deprecated indicates that there are problems with correct
6660 use of these functions.
6661 Return the current hypervisor binary (usually qemu).
6663 This is always non-NULL. If it wasn't set already, then this will
6665 return the default qemu binary name.
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.0.6)
6671 guestfs_get_recovery_proc
6673 int
6674 guestfs_get_recovery_proc (guestfs_h *g);
6675 Return the recovery process enabled flag.
6677 This function returns a C truth value on success or -1 on error.
6679 (Added in 1.0.77)
6681 guestfs_get_selinux
6683 int
6684 guestfs_get_selinux (guestfs_h *g);
6685 This function is deprecated. In new code, use the
6687 "guestfs_selinux_relabel" call instead.
6688 Deprecated functions will not be removed from the API, but the fact
6690 that they are deprecated indicates that there are problems with correct
6691 use of these functions.
6692 This returns the current setting of the selinux flag which is passed to
6694 the appliance at boot time. See "guestfs_set_selinux".
6695 For more information on the architecture of libguestfs, see guestfs(3).
6697 This function returns a C truth value on success or -1 on error.
6699 (Added in 1.0.67)
6701 guestfs_get_smp
6703 int
6704 guestfs_get_smp (guestfs_h *g);
6705 This returns the number of virtual CPUs assigned to the appliance.
6707 On error this function returns -1.
6709 (Added in 1.13.15)
6711 guestfs_get_sockdir
6713 char *
6714 guestfs_get_sockdir (guestfs_h *g);
6715 Get the directory used by the handle to store temporary socket files.
6717 This is different from "guestfs_tmpdir", as we need shorter paths for
6719 sockets (due to the limited buffers of filenames for UNIX sockets), and
6720 "guestfs_tmpdir" may be too long for them.
6721 The environment variable "XDG_RUNTIME_DIR" controls the default value:
6723 If "XDG_RUNTIME_DIR" is set, then that is the default. Else /tmp is
6724 the default.
6725 This function returns a string, or NULL on error. The caller must free
6727 the returned string after use.
6728 (Added in 1.33.8)
6730 guestfs_get_state
6732 int
6733 guestfs_get_state (guestfs_h *g);
6734 This returns the current state as an opaque integer. This is only
6736 useful for printing debug and internal error messages.
6737 For more information on states, see guestfs(3).
6739 On error this function returns -1.
6741 (Added in 1.0.2)
6743 guestfs_get_tmpdir
6745 char *
6746 guestfs_get_tmpdir (guestfs_h *g);
6747 Get the directory used by the handle to store temporary files.
6749 This function returns a string, or NULL on error. The caller must free
6751 the returned string after use.
6752 (Added in 1.19.58)
6754 guestfs_get_trace
6756 int
6757 guestfs_get_trace (guestfs_h *g);
6758 Return the command trace flag.
6760 This function returns a C truth value on success or -1 on error.
6762 (Added in 1.0.69)
6764 guestfs_get_umask
6766 int
6767 guestfs_get_umask (guestfs_h *g);
6768 Return the current umask. By default the umask is 022 unless it has
6770 been set by calling "guestfs_umask".
6771 On error this function returns -1.
6773 (Added in 1.3.4)
6775 guestfs_get_verbose
6777 int
6778 guestfs_get_verbose (guestfs_h *g);
6779 This returns the verbose messages flag.
6781 This function returns a C truth value on success or -1 on error.
6783 (Added in 0.3)
6785 guestfs_getcon
6787 char *
6788 guestfs_getcon (guestfs_h *g);
6789 This function is deprecated. In new code, use the
6791 "guestfs_selinux_relabel" call instead.
6792 Deprecated functions will not be removed from the API, but the fact
6794 that they are deprecated indicates that there are problems with correct
6795 use of these functions.
6796 This gets the SELinux security context of the daemon.
6798 See the documentation about SELINUX in guestfs(3), and "guestfs_setcon"
6800 This function returns a string, or NULL on error. The caller must free
6802 the returned string after use.
6803 This function depends on the feature "selinux". See also
6805 "guestfs_feature_available".
6806 (Added in 1.0.67)
6808 guestfs_getxattr
6810 char *
6811 guestfs_getxattr (guestfs_h *g,
6812 const char *path,
6813 const char *name,
6814 size_t *size_r);
6815 Get a single extended attribute from file "path" named "name". This
6817 call follows symlinks. If you want to lookup an extended attribute for
6818 the symlink itself, use "guestfs_lgetxattr".
6819 Normally it is better to get all extended attributes from a file in one
6821 go by calling "guestfs_getxattrs". However some Linux filesystem
6822 implementations are buggy and do not provide a way to list out
6823 attributes. For these filesystems (notably ntfs-3g) you have to know
6824 the names of the extended attributes you want in advance and call this
6825 function.
6826 Extended attribute values are blobs of binary data. If there is no
6828 extended attribute named "name", this returns an error.
6829 See also: "guestfs_getxattrs", "guestfs_lgetxattr", attr(5).
6831 This function returns a buffer, or NULL on error. The size of the
6833 returned buffer is written to *size_r. The caller must free the
6834 returned buffer after use.
6835 This function depends on the feature "linuxxattrs". See also
6837 "guestfs_feature_available".
6838 (Added in 1.7.24)
6840 guestfs_getxattrs
6842 struct guestfs_xattr_list *
6843 guestfs_getxattrs (guestfs_h *g,
6844 const char *path);
6845 This call lists the extended attributes of the file or directory
6847 "path".
6848 At the system call level, this is a combination of the listxattr(2) and
6850 getxattr(2) calls.
6851 See also: "guestfs_lgetxattrs", attr(5).
6853 This function returns a "struct guestfs_xattr_list *", or NULL if there
6855 was an error. The caller must call "guestfs_free_xattr_list" after
6856 use.
6857 This function depends on the feature "linuxxattrs". See also
6859 "guestfs_feature_available".
6860 (Added in 1.0.59)
6862 guestfs_glob_expand
6864 char **
6865 guestfs_glob_expand (guestfs_h *g,
6866 const char *pattern);
6867 This function is provided for backwards compatibility with earlier
6869 versions of libguestfs. It simply calls "guestfs_glob_expand_opts"
6870 with no optional arguments.
6871 (Added in 1.0.50)
6873 guestfs_glob_expand_opts
6875 char **
6876 guestfs_glob_expand_opts (guestfs_h *g,
6877 const char *pattern,
6878 ...);
6879 You may supply a list of optional arguments to this call. Use zero or
6881 more of the following pairs of parameters, and terminate the list with
6882 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6883 GUESTFS_GLOB_EXPAND_OPTS_DIRECTORYSLASH, int directoryslash,
6885 This command searches for all the pathnames matching "pattern"
6887 according to the wildcard expansion rules used by the shell.
6888 If no paths match, then this returns an empty list (note: not an
6890 error).
6891 It is just a wrapper around the C glob(3) function with flags
6893 "GLOB_MARK|GLOB_BRACE". See that manual page for more details.
6894 "directoryslash" controls whether use the "GLOB_MARK" flag for glob(3),
6896 and it defaults to true. It can be explicitly set as off to return no
6897 trailing slashes in filenames of directories.
6898 Notice that there is no equivalent command for expanding a device name
6900 (eg. /dev/sd*). Use "guestfs_list_devices", "guestfs_list_partitions"
6901 etc functions instead.
6902 This function returns a NULL-terminated array of strings (like
6904 environ(3)), or NULL if there was an error. The caller must free the
6905 strings and the array after use.
6906 (Added in 1.0.50)
6908 guestfs_glob_expand_opts_va
6910 char **
6911 guestfs_glob_expand_opts_va (guestfs_h *g,
6912 const char *pattern,
6913 va_list args);
6914 This is the "va_list variant" of "guestfs_glob_expand_opts".
6916 See "CALLS WITH OPTIONAL ARGUMENTS".
6918 guestfs_glob_expand_opts_argv
6920 char **
6921 guestfs_glob_expand_opts_argv (guestfs_h *g,
6922 const char *pattern,
6923 const struct guestfs_glob_expand_opts_argv *optargs);
6924 This is the "argv variant" of "guestfs_glob_expand_opts".
6926 See "CALLS WITH OPTIONAL ARGUMENTS".
6928 guestfs_grep
6930 char **
6931 guestfs_grep (guestfs_h *g,
6932 const char *regex,
6933 const char *path);
6934 This function is provided for backwards compatibility with earlier
6936 versions of libguestfs. It simply calls "guestfs_grep_opts" with no
6937 optional arguments.
6938 (Added in 1.0.66)
6940 guestfs_grep_opts
6942 char **
6943 guestfs_grep_opts (guestfs_h *g,
6944 const char *regex,
6945 const char *path,
6946 ...);
6947 You may supply a list of optional arguments to this call. Use zero or
6949 more of the following pairs of parameters, and terminate the list with
6950 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
6951 GUESTFS_GREP_OPTS_EXTENDED, int extended,
6953 GUESTFS_GREP_OPTS_FIXED, int fixed,
6954 GUESTFS_GREP_OPTS_INSENSITIVE, int insensitive,
6955 GUESTFS_GREP_OPTS_COMPRESSED, int compressed,
6956 This calls the external "grep" program and returns the matching lines.
6958 The optional flags are:
6960 "extended"
6962 Use extended regular expressions. This is the same as using the -E
6963 flag.
6964 "fixed"
6966 Match fixed (don't use regular expressions). This is the same as
6967 using the -F flag.
6968 "insensitive"
6970 Match case-insensitive. This is the same as using the -i flag.
6971 "compressed"
6973 Use "zgrep" instead of "grep". This allows the input to be
6974 compress- or gzip-compressed.
6975 This function returns a NULL-terminated array of strings (like
6977 environ(3)), or NULL if there was an error. The caller must free the
6978 strings and the array after use.
6979 Because of the message protocol, there is a transfer limit of somewhere
6981 between 2MB and 4MB. See "PROTOCOL LIMITS".
6982 (Added in 1.0.66)
6984 guestfs_grep_opts_va
6986 char **
6987 guestfs_grep_opts_va (guestfs_h *g,
6988 const char *regex,
6989 const char *path,
6990 va_list args);
6991 This is the "va_list variant" of "guestfs_grep_opts".
6993 See "CALLS WITH OPTIONAL ARGUMENTS".
6995 guestfs_grep_opts_argv
6997 char **
6998 guestfs_grep_opts_argv (guestfs_h *g,
6999 const char *regex,
7000 const char *path,
7001 const struct guestfs_grep_opts_argv *optargs);
7002 This is the "argv variant" of "guestfs_grep_opts".
7004 See "CALLS WITH OPTIONAL ARGUMENTS".
7006 guestfs_grepi
7008 char **
7009 guestfs_grepi (guestfs_h *g,
7010 const char *regex,
7011 const char *path);
7012 This function is deprecated. In new code, use the "guestfs_grep" call
7014 instead.
7015 Deprecated functions will not be removed from the API, but the fact
7017 that they are deprecated indicates that there are problems with correct
7018 use of these functions.
7019 This calls the external "grep -i" program and returns the matching
7021 lines.
7022 This function returns a NULL-terminated array of strings (like
7024 environ(3)), or NULL if there was an error. The caller must free the
7025 strings and the array after use.
7026 Because of the message protocol, there is a transfer limit of somewhere
7028 between 2MB and 4MB. See "PROTOCOL LIMITS".
7029 (Added in 1.0.66)
7031 guestfs_grub_install
7033 int
7034 guestfs_grub_install (guestfs_h *g,
7035 const char *root,
7036 const char *device);
7037 This command installs GRUB 1 (the Grand Unified Bootloader) on
7039 "device", with the root directory being "root".
7040 Notes:
7042 · There is currently no way in the API to install grub2, which is
7044 used by most modern Linux guests. It is possible to run the grub2
7045 command from the guest, although see the caveats in "RUNNING
7046 COMMANDS".
7047 · This uses "grub-install" from the host. Unfortunately grub is not
7049 always compatible with itself, so this only works in rather narrow
7050 circumstances. Careful testing with each guest version is
7051 advisable.
7052 · If grub-install reports the error "No suitable drive was found in
7054 the generated device map." it may be that you need to create a
7055 /boot/grub/device.map file first that contains the mapping between
7056 grub device names and Linux device names. It is usually sufficient
7057 to create a file containing:
7058 (hd0) /dev/vda
7060 replacing /dev/vda with the name of the installation device.
7062 This function returns 0 on success or -1 on error.
7064 This function depends on the feature "grub". See also
7066 "guestfs_feature_available".
7067 (Added in 1.0.17)
7069 guestfs_head
7071 char **
7072 guestfs_head (guestfs_h *g,
7073 const char *path);
7074 This command returns up to the first 10 lines of a file as a list of
7076 strings.
7077 This function returns a NULL-terminated array of strings (like
7079 environ(3)), or NULL if there was an error. The caller must free the
7080 strings and the array after use.
7081 Because of the message protocol, there is a transfer limit of somewhere
7083 between 2MB and 4MB. See "PROTOCOL LIMITS".
7084 (Added in 1.0.54)
7086 guestfs_head_n
7088 char **
7089 guestfs_head_n (guestfs_h *g,
7090 int nrlines,
7091 const char *path);
7092 If the parameter "nrlines" is a positive number, this returns the first
7094 "nrlines" lines of the file "path".
7095 If the parameter "nrlines" is a negative number, this returns lines
7097 from the file "path", excluding the last "nrlines" lines.
7098 If the parameter "nrlines" is zero, this returns an empty list.
7100 This function returns a NULL-terminated array of strings (like
7102 environ(3)), or NULL if there was an error. The caller must free the
7103 strings and the array after use.
7104 Because of the message protocol, there is a transfer limit of somewhere
7106 between 2MB and 4MB. See "PROTOCOL LIMITS".
7107 (Added in 1.0.54)
7109 guestfs_hexdump
7111 char *
7112 guestfs_hexdump (guestfs_h *g,
7113 const char *path);
7114 This runs "hexdump -C" on the given "path". The result is the human-
7116 readable, canonical hex dump of the file.
7117 This function returns a string, or NULL on error. The caller must free
7119 the returned string after use.
7120 Because of the message protocol, there is a transfer limit of somewhere
7122 between 2MB and 4MB. See "PROTOCOL LIMITS".
7123 (Added in 1.0.22)
7125 guestfs_hivex_close
7127 int
7128 guestfs_hivex_close (guestfs_h *g);
7129 Close the current hivex handle.
7131 This is a wrapper around the hivex(3) call of the same name.
7133 This function returns 0 on success or -1 on error.
7135 This function depends on the feature "hivex". See also
7137 "guestfs_feature_available".
7138 (Added in 1.19.35)
7140 guestfs_hivex_commit
7142 int
7143 guestfs_hivex_commit (guestfs_h *g,
7144 const char *filename);
7145 Commit (write) changes to the hive.
7147 If the optional filename parameter is null, then the changes are
7149 written back to the same hive that was opened. If this is not null
7150 then they are written to the alternate filename given and the original
7151 hive is left untouched.
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_node_add_child
7163 int64_t
7164 guestfs_hivex_node_add_child (guestfs_h *g,
7165 int64_t parent,
7166 const char *name);
7167 Add a child node to "parent" named "name".
7169 This is a wrapper around the hivex(3) call of the same name.
7171 On error this function returns -1.
7173 This function depends on the feature "hivex". See also
7175 "guestfs_feature_available".
7176 (Added in 1.19.35)
7178 guestfs_hivex_node_children
7180 struct guestfs_hivex_node_list *
7181 guestfs_hivex_node_children (guestfs_h *g,
7182 int64_t nodeh);
7183 Return the list of nodes which are subkeys of "nodeh".
7185 This is a wrapper around the hivex(3) call of the same name.
7187 This function returns a "struct guestfs_hivex_node_list *", or NULL if
7189 there was an error. The caller must call
7190 "guestfs_free_hivex_node_list" after use.
7191 This function depends on the feature "hivex". See also
7193 "guestfs_feature_available".
7194 (Added in 1.19.35)
7196 guestfs_hivex_node_delete_child
7198 int
7199 guestfs_hivex_node_delete_child (guestfs_h *g,
7200 int64_t nodeh);
7201 Delete "nodeh", recursively if necessary.
7203 This is a wrapper around the hivex(3) call of the same name.
7205 This function returns 0 on success or -1 on error.
7207 This function depends on the feature "hivex". See also
7209 "guestfs_feature_available".
7210 (Added in 1.19.35)
7212 guestfs_hivex_node_get_child
7214 int64_t
7215 guestfs_hivex_node_get_child (guestfs_h *g,
7216 int64_t nodeh,
7217 const char *name);
7218 Return the child of "nodeh" with the name "name", if it exists. This
7220 can return 0 meaning the name was not found.
7221 This is a wrapper around the hivex(3) call of the same name.
7223 On error this function returns -1.
7225 This function depends on the feature "hivex". See also
7227 "guestfs_feature_available".
7228 (Added in 1.19.35)
7230 guestfs_hivex_node_get_value
7232 int64_t
7233 guestfs_hivex_node_get_value (guestfs_h *g,
7234 int64_t nodeh,
7235 const char *key);
7236 Return the value attached to "nodeh" which has the name "key", if it
7238 exists. This can return 0 meaning the key was not found.
7239 This is a wrapper around the hivex(3) call of the same name.
7241 On error this function returns -1.
7243 This function depends on the feature "hivex". See also
7245 "guestfs_feature_available".
7246 (Added in 1.19.35)
7248 guestfs_hivex_node_name
7250 char *
7251 guestfs_hivex_node_name (guestfs_h *g,
7252 int64_t nodeh);
7253 Return the name of "nodeh".
7255 This is a wrapper around the hivex(3) call of the same name.
7257 This function returns a string, or NULL on error. The caller must free
7259 the returned string after use.
7260 This function depends on the feature "hivex". See also
7262 "guestfs_feature_available".
7263 (Added in 1.19.35)
7265 guestfs_hivex_node_parent
7267 int64_t
7268 guestfs_hivex_node_parent (guestfs_h *g,
7269 int64_t nodeh);
7270 Return the parent node of "nodeh".
7272 This is a wrapper around the hivex(3) call of the same name.
7274 On error this function returns -1.
7276 This function depends on the feature "hivex". See also
7278 "guestfs_feature_available".
7279 (Added in 1.19.35)
7281 guestfs_hivex_node_set_value
7283 int
7284 guestfs_hivex_node_set_value (guestfs_h *g,
7285 int64_t nodeh,
7286 const char *key,
7287 int64_t t,
7288 const char *val,
7289 size_t val_size);
7290 Set or replace a single value under the node "nodeh". The "key" is the
7292 name, "t" is the type, and "val" is the data.
7293 This is a wrapper around the hivex(3) call of the same name.
7295 This function returns 0 on success or -1 on error.
7297 This function depends on the feature "hivex". See also
7299 "guestfs_feature_available".
7300 (Added in 1.19.35)
7302 guestfs_hivex_node_values
7304 struct guestfs_hivex_value_list *
7305 guestfs_hivex_node_values (guestfs_h *g,
7306 int64_t nodeh);
7307 Return the array of (key, datatype, data) tuples attached to "nodeh".
7309 This is a wrapper around the hivex(3) call of the same name.
7311 This function returns a "struct guestfs_hivex_value_list *", or NULL if
7313 there was an error. The caller must call
7314 "guestfs_free_hivex_value_list" after use.
7315 This function depends on the feature "hivex". See also
7317 "guestfs_feature_available".
7318 (Added in 1.19.35)
7320 guestfs_hivex_open
7322 int
7323 guestfs_hivex_open (guestfs_h *g,
7324 const char *filename,
7325 ...);
7326 You may supply a list of optional arguments to this call. Use zero or
7328 more of the following pairs of parameters, and terminate the list with
7329 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7330 GUESTFS_HIVEX_OPEN_VERBOSE, int verbose,
7332 GUESTFS_HIVEX_OPEN_DEBUG, int debug,
7333 GUESTFS_HIVEX_OPEN_WRITE, int write,
7334 GUESTFS_HIVEX_OPEN_UNSAFE, int unsafe,
7335 Open the Windows Registry hive file named filename. If there was any
7337 previous hivex handle associated with this guestfs session, then it is
7338 closed.
7339 This is a wrapper around the hivex(3) call of the same name.
7341 This function returns 0 on success or -1 on error.
7343 This function depends on the feature "hivex". See also
7345 "guestfs_feature_available".
7346 (Added in 1.19.35)
7348 guestfs_hivex_open_va
7350 int
7351 guestfs_hivex_open_va (guestfs_h *g,
7352 const char *filename,
7353 va_list args);
7354 This is the "va_list variant" of "guestfs_hivex_open".
7356 See "CALLS WITH OPTIONAL ARGUMENTS".
7358 guestfs_hivex_open_argv
7360 int
7361 guestfs_hivex_open_argv (guestfs_h *g,
7362 const char *filename,
7363 const struct guestfs_hivex_open_argv *optargs);
7364 This is the "argv variant" of "guestfs_hivex_open".
7366 See "CALLS WITH OPTIONAL ARGUMENTS".
7368 guestfs_hivex_root
7370 int64_t
7371 guestfs_hivex_root (guestfs_h *g);
7372 Return the root node of the hive.
7374 This is a wrapper around the hivex(3) call of the same name.
7376 On error this function returns -1.
7378 This function depends on the feature "hivex". See also
7380 "guestfs_feature_available".
7381 (Added in 1.19.35)
7383 guestfs_hivex_value_key
7385 char *
7386 guestfs_hivex_value_key (guestfs_h *g,
7387 int64_t valueh);
7388 Return the key (name) field of a (key, datatype, data) tuple.
7390 This is a wrapper around the hivex(3) call of the same name.
7392 This function returns a string, or NULL on error. The caller must free
7394 the returned string after use.
7395 This function depends on the feature "hivex". See also
7397 "guestfs_feature_available".
7398 (Added in 1.19.35)
7400 guestfs_hivex_value_string
7402 char *
7403 guestfs_hivex_value_string (guestfs_h *g,
7404 int64_t valueh);
7405 This calls "guestfs_hivex_value_value" (which returns the data field
7407 from a hivex value tuple). It then assumes that the field is a
7408 UTF-16LE string and converts the result to UTF-8 (or if this is not
7409 possible, it returns an error).
7410 This is useful for reading strings out of the Windows registry.
7412 However it is not foolproof because the registry is not strongly-typed
7413 and fields can contain arbitrary or unexpected data.
7414 This function returns a string, or NULL on error. The caller must free
7416 the returned string after use.
7417 This function depends on the feature "hivex". See also
7419 "guestfs_feature_available".
7420 (Added in 1.37.22)
7422 guestfs_hivex_value_type
7424 int64_t
7425 guestfs_hivex_value_type (guestfs_h *g,
7426 int64_t valueh);
7427 Return the data type field from a (key, datatype, data) tuple.
7429 This is a wrapper around the hivex(3) call of the same name.
7431 On error this function returns -1.
7433 This function depends on the feature "hivex". See also
7435 "guestfs_feature_available".
7436 (Added in 1.19.35)
7438 guestfs_hivex_value_utf8
7440 char *
7441 guestfs_hivex_value_utf8 (guestfs_h *g,
7442 int64_t valueh);
7443 This function is deprecated. In new code, use the
7445 "guestfs_hivex_value_string" call instead.
7446 Deprecated functions will not be removed from the API, but the fact
7448 that they are deprecated indicates that there are problems with correct
7449 use of these functions.
7450 This calls "guestfs_hivex_value_value" (which returns the data field
7452 from a hivex value tuple). It then assumes that the field is a
7453 UTF-16LE string and converts the result to UTF-8 (or if this is not
7454 possible, it returns an error).
7455 This is useful for reading strings out of the Windows registry.
7457 However it is not foolproof because the registry is not strongly-typed
7458 and fields can contain arbitrary or unexpected data.
7459 This function returns a string, or NULL on error. The caller must free
7461 the returned string after use.
7462 This function depends on the feature "hivex". See also
7464 "guestfs_feature_available".
7465 (Added in 1.19.35)
7467 guestfs_hivex_value_value
7469 char *
7470 guestfs_hivex_value_value (guestfs_h *g,
7471 int64_t valueh,
7472 size_t *size_r);
7473 Return the data field of a (key, datatype, data) tuple.
7475 This is a wrapper around the hivex(3) call of the same name.
7477 See also: "guestfs_hivex_value_utf8".
7479 This function returns a buffer, or NULL on error. The size of the
7481 returned buffer is written to *size_r. The caller must free the
7482 returned buffer after use.
7483 This function depends on the feature "hivex". See also
7485 "guestfs_feature_available".
7486 (Added in 1.19.35)
7488 guestfs_initrd_cat
7490 char *
7491 guestfs_initrd_cat (guestfs_h *g,
7492 const char *initrdpath,
7493 const char *filename,
7494 size_t *size_r);
7495 This command unpacks the file filename from the initrd file called
7497 initrdpath. The filename must be given without the initial /
7498 character.
7499 For example, in guestfish you could use the following command to
7501 examine the boot script (usually called /init) contained in a Linux
7502 initrd or initramfs image:
7503 initrd-cat /boot/initrd-<version>.img init
7505 See also "guestfs_initrd_list".
7507 This function returns a buffer, or NULL on error. The size of the
7509 returned buffer is written to *size_r. The caller must free the
7510 returned buffer after use.
7511 Because of the message protocol, there is a transfer limit of somewhere
7513 between 2MB and 4MB. See "PROTOCOL LIMITS".
7514 (Added in 1.0.84)
7516 guestfs_initrd_list
7518 char **
7519 guestfs_initrd_list (guestfs_h *g,
7520 const char *path);
7521 This command lists out files contained in an initrd.
7523 The files are listed without any initial / character. The files are
7525 listed in the order they appear (not necessarily alphabetical).
7526 Directory names are listed as separate items.
7527 Old Linux kernels (2.4 and earlier) used a compressed ext2 filesystem
7529 as initrd. We only support the newer initramfs format (compressed cpio
7530 files).
7531 This function returns a NULL-terminated array of strings (like
7533 environ(3)), or NULL if there was an error. The caller must free the
7534 strings and the array after use.
7535 (Added in 1.0.54)
7537 guestfs_inotify_add_watch
7539 int64_t
7540 guestfs_inotify_add_watch (guestfs_h *g,
7541 const char *path,
7542 int mask);
7543 Watch "path" for the events listed in "mask".
7545 Note that if "path" is a directory then events within that directory
7547 are watched, but this does not happen recursively (in subdirectories).
7548 Note for non-C or non-Linux callers: the inotify events are defined by
7550 the Linux kernel ABI and are listed in /usr/include/sys/inotify.h.
7551 On error this function returns -1.
7553 This function depends on the feature "inotify". See also
7555 "guestfs_feature_available".
7556 (Added in 1.0.66)
7558 guestfs_inotify_close
7560 int
7561 guestfs_inotify_close (guestfs_h *g);
7562 This closes the inotify handle which was previously opened by
7564 inotify_init. It removes all watches, throws away any pending events,
7565 and deallocates all resources.
7566 This function returns 0 on success or -1 on error.
7568 This function depends on the feature "inotify". See also
7570 "guestfs_feature_available".
7571 (Added in 1.0.66)
7573 guestfs_inotify_files
7575 char **
7576 guestfs_inotify_files (guestfs_h *g);
7577 This function is a helpful wrapper around "guestfs_inotify_read" which
7579 just returns a list of pathnames of objects that were touched. The
7580 returned pathnames are sorted and deduplicated.
7581 This function returns a NULL-terminated array of strings (like
7583 environ(3)), or NULL if there was an error. The caller must free the
7584 strings and the array after use.
7585 This function depends on the feature "inotify". See also
7587 "guestfs_feature_available".
7588 (Added in 1.0.66)
7590 guestfs_inotify_init
7592 int
7593 guestfs_inotify_init (guestfs_h *g,
7594 int maxevents);
7595 This command creates a new inotify handle. The inotify subsystem can
7597 be used to notify events which happen to objects in the guest
7598 filesystem.
7599 "maxevents" is the maximum number of events which will be queued up
7601 between calls to "guestfs_inotify_read" or "guestfs_inotify_files". If
7602 this is passed as 0, then the kernel (or previously set) default is
7603 used. For Linux 2.6.29 the default was 16384 events. Beyond this
7604 limit, the kernel throws away events, but records the fact that it
7605 threw them away by setting a flag "IN_Q_OVERFLOW" in the returned
7606 structure list (see "guestfs_inotify_read").
7607 Before any events are generated, you have to add some watches to the
7609 internal watch list. See: "guestfs_inotify_add_watch" and
7610 "guestfs_inotify_rm_watch".
7611 Queued up events should be read periodically by calling
7613 "guestfs_inotify_read" (or "guestfs_inotify_files" which is just a
7614 helpful wrapper around "guestfs_inotify_read"). If you don't read the
7615 events out often enough then you risk the internal queue overflowing.
7616 The handle should be closed after use by calling
7618 "guestfs_inotify_close". This also removes any watches automatically.
7619 See also inotify(7) for an overview of the inotify interface as exposed
7621 by the Linux kernel, which is roughly what we expose via libguestfs.
7622 Note that there is one global inotify handle per libguestfs instance.
7623 This function returns 0 on success or -1 on error.
7625 This function depends on the feature "inotify". See also
7627 "guestfs_feature_available".
7628 (Added in 1.0.66)
7630 guestfs_inotify_read
7632 struct guestfs_inotify_event_list *
7633 guestfs_inotify_read (guestfs_h *g);
7634 Return the complete queue of events that have happened since the
7636 previous read call.
7637 If no events have happened, this returns an empty list.
7639 Note: In order to make sure that all events have been read, you must
7641 call this function repeatedly until it returns an empty list. The
7642 reason is that the call will read events up to the maximum appliance-
7643 to-host message size and leave remaining events in the queue.
7644 This function returns a "struct guestfs_inotify_event_list *", or NULL
7646 if there was an error. The caller must call
7647 "guestfs_free_inotify_event_list" after use.
7648 This function depends on the feature "inotify". See also
7650 "guestfs_feature_available".
7651 (Added in 1.0.66)
7653 guestfs_inotify_rm_watch
7655 int
7656 guestfs_inotify_rm_watch (guestfs_h *g,
7657 int wd);
7658 Remove a previously defined inotify watch. See
7660 "guestfs_inotify_add_watch".
7661 This function returns 0 on success or -1 on error.
7663 This function depends on the feature "inotify". See also
7665 "guestfs_feature_available".
7666 (Added in 1.0.66)
7668 guestfs_inspect_get_arch
7670 char *
7671 guestfs_inspect_get_arch (guestfs_h *g,
7672 const char *root);
7673 This returns the architecture of the inspected operating system. The
7675 possible return values are listed under "guestfs_file_architecture".
7676 If the architecture could not be determined, then the string "unknown"
7678 is returned.
7679 Please read "INSPECTION" for more details.
7681 This function returns a string, or NULL on error. The caller must free
7683 the returned string after use.
7684 (Added in 1.5.3)
7686 guestfs_inspect_get_distro
7688 char *
7689 guestfs_inspect_get_distro (guestfs_h *g,
7690 const char *root);
7691 This returns the distro (distribution) of the inspected operating
7693 system.
7694 Currently defined distros are:
7696 "alpinelinux"
7698 Alpine Linux.
7699 "altlinux"
7701 ALT Linux.
7702 "archlinux"
7704 Arch Linux.
7705 "buildroot"
7707 Buildroot-derived distro, but not one we specifically recognize.
7708 "centos"
7710 CentOS.
7711 "cirros"
7713 Cirros.
7714 "coreos"
7716 CoreOS.
7717 "debian"
7719 Debian.
7720 "fedora"
7722 Fedora.
7723 "freebsd"
7725 FreeBSD.
7726 "freedos"
7728 FreeDOS.
7729 "frugalware"
7731 Frugalware.
7732 "gentoo"
7734 Gentoo.
7735 "kalilinux"
7737 Kali Linux.
7738 "linuxmint"
7740 Linux Mint.
7741 "mageia"
7743 Mageia.
7744 "mandriva"
7746 Mandriva.
7747 "meego"
7749 MeeGo.
7750 "msdos"
7752 Microsoft DOS.
7753 "neokylin"
7755 NeoKylin.
7756 "netbsd"
7758 NetBSD.
7759 "openbsd"
7761 OpenBSD.
7762 "opensuse"
7764 OpenSUSE.
7765 "oraclelinux"
7767 Oracle Linux.
7768 "pardus"
7770 Pardus.
7771 "pldlinux"
7773 PLD Linux.
7774 "redhat-based"
7776 Some Red Hat-derived distro.
7777 "rhel"
7779 Red Hat Enterprise Linux.
7780 "scientificlinux"
7782 Scientific Linux.
7783 "slackware"
7785 Slackware.
7786 "sles"
7788 SuSE Linux Enterprise Server or Desktop.
7789 "suse-based"
7791 Some openSuSE-derived distro.
7792 "ttylinux"
7794 ttylinux.
7795 "ubuntu"
7797 Ubuntu.
7798 "unknown"
7800 The distro could not be determined.
7801 "voidlinux"
7803 Void Linux.
7804 "windows"
7806 Windows does not have distributions. This string is returned if
7807 the OS type is Windows.
7808 Future versions of libguestfs may return other strings here. The
7810 caller should be prepared to handle any string.
7811 Please read "INSPECTION" for more details.
7813 This function returns a string, or NULL on error. The caller must free
7815 the returned string after use.
7816 (Added in 1.5.3)
7818 guestfs_inspect_get_drive_mappings
7820 char **
7821 guestfs_inspect_get_drive_mappings (guestfs_h *g,
7822 const char *root);
7823 This call is useful for Windows which uses a primitive system of
7825 assigning drive letters (like C:\) to partitions. This inspection API
7826 examines the Windows Registry to find out how disks/partitions are
7827 mapped to drive letters, and returns a hash table as in the example
7828 below:
7829 C => /dev/vda2
7831 E => /dev/vdb1
7832 F => /dev/vdc1
7833 Note that keys are drive letters. For Windows, the key is case
7835 insensitive and just contains the drive letter, without the customary
7836 colon separator character.
7837 In future we may support other operating systems that also used drive
7839 letters, but the keys for those might not be case insensitive and might
7840 be longer than 1 character. For example in OS-9, hard drives were
7841 named "h0", "h1" etc.
7842 For Windows guests, currently only hard drive mappings are returned.
7844 Removable disks (eg. DVD-ROMs) are ignored.
7845 For guests that do not use drive mappings, or if the drive mappings
7847 could not be determined, this returns an empty hash table.
7848 Please read "INSPECTION" for more details. See also
7850 "guestfs_inspect_get_mountpoints", "guestfs_inspect_get_filesystems".
7851 This function returns a NULL-terminated array of strings, or NULL if
7853 there was an error. The array of strings will always have length
7854 "2n+1", where "n" keys and values alternate, followed by the trailing
7855 NULL entry. The caller must free the strings and the array after use.
7856 (Added in 1.9.17)
7858 guestfs_inspect_get_filesystems
7860 char **
7861 guestfs_inspect_get_filesystems (guestfs_h *g,
7862 const char *root);
7863 This returns a list of all the filesystems that we think are associated
7865 with this operating system. This includes the root filesystem, other
7866 ordinary filesystems, and non-mounted devices like swap partitions.
7867 In the case of a multi-boot virtual machine, it is possible for a
7869 filesystem to be shared between operating systems.
7870 Please read "INSPECTION" for more details. See also
7872 "guestfs_inspect_get_mountpoints".
7873 This function returns a NULL-terminated array of strings (like
7875 environ(3)), or NULL if there was an error. The caller must free the
7876 strings and the array after use.
7877 (Added in 1.5.3)
7879 guestfs_inspect_get_format
7881 char *
7882 guestfs_inspect_get_format (guestfs_h *g,
7883 const char *root);
7884 This function is deprecated. There is no replacement. Consult the API
7886 documentation in guestfs(3) for further information.
7887 Deprecated functions will not be removed from the API, but the fact
7889 that they are deprecated indicates that there are problems with correct
7890 use of these functions.
7891 Before libguestfs 1.38, there was some unreliable support for detecting
7893 installer CDs. This API would return:
7894 "installed"
7896 This is an installed operating system.
7897 "installer"
7899 The disk image being inspected is not an installed operating
7900 system, but a bootable install disk, live CD, or similar.
7901 "unknown"
7903 The format of this disk image is not known.
7904 In libguestfs ≥ 1.38, this only returns "installed". Use libosinfo
7906 directly to detect installer CDs.
7907 Please read "INSPECTION" for more details.
7909 This function returns a string, or NULL on error. The caller must free
7911 the returned string after use.
7912 (Added in 1.9.4)
7914 guestfs_inspect_get_hostname
7916 char *
7917 guestfs_inspect_get_hostname (guestfs_h *g,
7918 const char *root);
7919 This function returns the hostname of the operating system as found by
7921 inspection of the guest’s configuration files.
7922 If the hostname could not be determined, then the string "unknown" is
7924 returned.
7925 Please read "INSPECTION" for more details.
7927 This function returns a string, or NULL on error. The caller must free
7929 the returned string after use.
7930 (Added in 1.7.9)
7932 guestfs_inspect_get_icon
7934 char *
7935 guestfs_inspect_get_icon (guestfs_h *g,
7936 const char *root,
7937 size_t *size_r,
7938 ...);
7939 You may supply a list of optional arguments to this call. Use zero or
7941 more of the following pairs of parameters, and terminate the list with
7942 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
7943 GUESTFS_INSPECT_GET_ICON_FAVICON, int favicon,
7945 GUESTFS_INSPECT_GET_ICON_HIGHQUALITY, int highquality,
7946 This function returns an icon corresponding to the inspected operating
7948 system. The icon is returned as a buffer containing a PNG image (re-
7949 encoded to PNG if necessary).
7950 If it was not possible to get an icon this function returns a zero-
7952 length (non-NULL) buffer. Callers must check for this case.
7953 Libguestfs will start by looking for a file called /etc/favicon.png or
7955 C:\etc\favicon.png and if it has the correct format, the contents of
7956 this file will be returned. You can disable favicons by passing the
7957 optional "favicon" boolean as false (default is true).
7958 If finding the favicon fails, then we look in other places in the guest
7960 for a suitable icon.
7961 If the optional "highquality" boolean is true then only high quality
7963 icons are returned, which means only icons of high resolution with an
7964 alpha channel. The default (false) is to return any icon we can, even
7965 if it is of substandard quality.
7966 Notes:
7968 · Unlike most other inspection API calls, the guest’s disks must be
7970 mounted up before you call this, since it needs to read information
7971 from the guest filesystem during the call.
7972 · Security: The icon data comes from the untrusted guest, and should
7974 be treated with caution. PNG files have been known to contain
7975 exploits. Ensure that libpng (or other relevant libraries) are
7976 fully up to date before trying to process or display the icon.
7977 · The PNG image returned can be any size. It might not be square.
7979 Libguestfs tries to return the largest, highest quality icon
7980 available. The application must scale the icon to the required
7981 size.
7982 · Extracting icons from Windows guests requires the external
7984 "wrestool" program from the "icoutils" package, and several
7985 programs ("bmptopnm", "pnmtopng", "pamcut") from the "netpbm"
7986 package. These must be installed separately.
7987 · Operating system icons are usually trademarks. Seek legal advice
7989 before using trademarks in applications.
7990 This function returns a buffer, or NULL on error. The size of the
7992 returned buffer is written to *size_r. The caller must free the
7993 returned buffer after use.
7994 (Added in 1.11.12)
7996 guestfs_inspect_get_icon_va
7998 char *
7999 guestfs_inspect_get_icon_va (guestfs_h *g,
8000 const char *root,
8001 size_t *size_r,
8002 va_list args);
8003 This is the "va_list variant" of "guestfs_inspect_get_icon".
8005 See "CALLS WITH OPTIONAL ARGUMENTS".
8007 guestfs_inspect_get_icon_argv
8009 char *
8010 guestfs_inspect_get_icon_argv (guestfs_h *g,
8011 const char *root,
8012 size_t *size_r,
8013 const struct guestfs_inspect_get_icon_argv *optargs);
8014 This is the "argv variant" of "guestfs_inspect_get_icon".
8016 See "CALLS WITH OPTIONAL ARGUMENTS".
8018 guestfs_inspect_get_major_version
8020 int
8021 guestfs_inspect_get_major_version (guestfs_h *g,
8022 const char *root);
8023 This returns the major version number of the inspected operating
8025 system.
8026 Windows uses a consistent versioning scheme which is not reflected in
8028 the popular public names used by the operating system. Notably the
8029 operating system known as "Windows 7" is really version 6.1 (ie. major
8030 = 6, minor = 1). You can find out the real versions corresponding to
8031 releases of Windows by consulting Wikipedia or MSDN.
8032 If the version could not be determined, then 0 is returned.
8034 Please read "INSPECTION" for more details.
8036 On error this function returns -1.
8038 (Added in 1.5.3)
8040 guestfs_inspect_get_minor_version
8042 int
8043 guestfs_inspect_get_minor_version (guestfs_h *g,
8044 const char *root);
8045 This returns the minor version number of the inspected operating
8047 system.
8048 If the version could not be determined, then 0 is returned.
8050 Please read "INSPECTION" for more details. See also
8052 "guestfs_inspect_get_major_version".
8053 On error this function returns -1.
8055 (Added in 1.5.3)
8057 guestfs_inspect_get_mountpoints
8059 char **
8060 guestfs_inspect_get_mountpoints (guestfs_h *g,
8061 const char *root);
8062 This returns a hash of where we think the filesystems associated with
8064 this operating system should be mounted. Callers should note that this
8065 is at best an educated guess made by reading configuration files such
8066 as /etc/fstab. In particular note that this may return filesystems
8067 which are non-existent or not mountable and callers should be prepared
8068 to handle or ignore failures if they try to mount them.
8069 Each element in the returned hashtable has a key which is the path of
8071 the mountpoint (eg. /boot) and a value which is the filesystem that
8072 would be mounted there (eg. /dev/sda1).
8073 Non-mounted devices such as swap devices are not returned in this list.
8075 For operating systems like Windows which still use drive letters, this
8077 call will only return an entry for the first drive "mounted on" /. For
8078 information about the mapping of drive letters to partitions, see
8079 "guestfs_inspect_get_drive_mappings".
8080 Please read "INSPECTION" for more details. See also
8082 "guestfs_inspect_get_filesystems".
8083 This function returns a NULL-terminated array of strings, or NULL if
8085 there was an error. The array of strings will always have length
8086 "2n+1", where "n" keys and values alternate, followed by the trailing
8087 NULL entry. The caller must free the strings and the array after use.
8088 (Added in 1.5.3)
8090 guestfs_inspect_get_osinfo
8092 char *
8093 guestfs_inspect_get_osinfo (guestfs_h *g,
8094 const char *root);
8095 This function returns a possible short ID for libosinfo corresponding
8097 to the guest.
8098 Note: The returned ID is only a guess by libguestfs, and nothing
8100 ensures that it actually exists in osinfo-db.
8101 If no ID could not be determined, then the string "unknown" is
8103 returned.
8104 This function returns a string, or NULL on error. The caller must free
8106 the returned string after use.
8107 (Added in 1.39.1)
8109 guestfs_inspect_get_package_format
8111 char *
8112 guestfs_inspect_get_package_format (guestfs_h *g,
8113 const char *root);
8114 This function and "guestfs_inspect_get_package_management" return the
8116 package format and package management tool used by the inspected
8117 operating system. For example for Fedora these functions would return
8118 "rpm" (package format), and "yum" or "dnf" (package management).
8119 This returns the string "unknown" if we could not determine the package
8121 format or if the operating system does not have a real packaging system
8122 (eg. Windows).
8123 Possible strings include: "rpm", "deb", "ebuild", "pisi", "pacman",
8125 "pkgsrc", "apk", "xbps". Future versions of libguestfs may return
8126 other strings.
8127 Please read "INSPECTION" for more details.
8129 This function returns a string, or NULL on error. The caller must free
8131 the returned string after use.
8132 (Added in 1.7.5)
8134 guestfs_inspect_get_package_management
8136 char *
8137 guestfs_inspect_get_package_management (guestfs_h *g,
8138 const char *root);
8139 "guestfs_inspect_get_package_format" and this function return the
8141 package format and package management tool used by the inspected
8142 operating system. For example for Fedora these functions would return
8143 "rpm" (package format), and "yum" or "dnf" (package management).
8144 This returns the string "unknown" if we could not determine the package
8146 management tool or if the operating system does not have a real
8147 packaging system (eg. Windows).
8148 Possible strings include: "yum", "dnf", "up2date", "apt" (for all
8150 Debian derivatives), "portage", "pisi", "pacman", "urpmi", "zypper",
8151 "apk", "xbps". Future versions of libguestfs may return other strings.
8152 Please read "INSPECTION" for more details.
8154 This function returns a string, or NULL on error. The caller must free
8156 the returned string after use.
8157 (Added in 1.7.5)
8159 guestfs_inspect_get_product_name
8161 char *
8162 guestfs_inspect_get_product_name (guestfs_h *g,
8163 const char *root);
8164 This returns the product name of the inspected operating system. The
8166 product name is generally some freeform string which can be displayed
8167 to the user, but should not be parsed by programs.
8168 If the product name could not be determined, then the string "unknown"
8170 is returned.
8171 Please read "INSPECTION" for more details.
8173 This function returns a string, or NULL on error. The caller must free
8175 the returned string after use.
8176 (Added in 1.5.3)
8178 guestfs_inspect_get_product_variant
8180 char *
8181 guestfs_inspect_get_product_variant (guestfs_h *g,
8182 const char *root);
8183 This returns the product variant of the inspected operating system.
8185 For Windows guests, this returns the contents of the Registry key
8187 "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType"
8188 which is usually a string such as "Client" or "Server" (other values
8189 are possible). This can be used to distinguish consumer and enterprise
8190 versions of Windows that have the same version number (for example,
8191 Windows 7 and Windows 2008 Server are both version 6.1, but the former
8192 is "Client" and the latter is "Server").
8193 For enterprise Linux guests, in future we intend this to return the
8195 product variant such as "Desktop", "Server" and so on. But this is not
8196 implemented at present.
8197 If the product variant could not be determined, then the string
8199 "unknown" is returned.
8200 Please read "INSPECTION" for more details. See also
8202 "guestfs_inspect_get_product_name",
8203 "guestfs_inspect_get_major_version".
8204 This function returns a string, or NULL on error. The caller must free
8206 the returned string after use.
8207 (Added in 1.9.13)
8209 guestfs_inspect_get_roots
8211 char **
8212 guestfs_inspect_get_roots (guestfs_h *g);
8213 This function is a convenient way to get the list of root devices, as
8215 returned from a previous call to "guestfs_inspect_os", but without
8216 redoing the whole inspection process.
8217 This returns an empty list if either no root devices were found or the
8219 caller has not called "guestfs_inspect_os".
8220 Please read "INSPECTION" for more details.
8222 This function returns a NULL-terminated array of strings (like
8224 environ(3)), or NULL if there was an error. The caller must free the
8225 strings and the array after use.
8226 (Added in 1.7.3)
8228 guestfs_inspect_get_type
8230 char *
8231 guestfs_inspect_get_type (guestfs_h *g,
8232 const char *root);
8233 This returns the type of the inspected operating system. Currently
8235 defined types are:
8236 "linux"
8238 Any Linux-based operating system.
8239 "windows"
8241 Any Microsoft Windows operating system.
8242 "freebsd"
8244 FreeBSD.
8245 "netbsd"
8247 NetBSD.
8248 "openbsd"
8250 OpenBSD.
8251 "hurd"
8253 GNU/Hurd.
8254 "dos"
8256 MS-DOS, FreeDOS and others.
8257 "minix"
8259 MINIX.
8260 "unknown"
8262 The operating system type could not be determined.
8263 Future versions of libguestfs may return other strings here. The
8265 caller should be prepared to handle any string.
8266 Please read "INSPECTION" for more details.
8268 This function returns a string, or NULL on error. The caller must free
8270 the returned string after use.
8271 (Added in 1.5.3)
8273 guestfs_inspect_get_windows_current_control_set
8275 char *
8276 guestfs_inspect_get_windows_current_control_set (guestfs_h *g,
8277 const char *root);
8278 This returns the Windows CurrentControlSet of the inspected guest. The
8280 CurrentControlSet is a registry key name such as "ControlSet001".
8281 This call assumes that the guest is Windows and that the Registry could
8283 be examined by inspection. If this is not the case then an error is
8284 returned.
8285 Please read "INSPECTION" for more details.
8287 This function returns a string, or NULL on error. The caller must free
8289 the returned string after use.
8290 (Added in 1.9.17)
8292 guestfs_inspect_get_windows_software_hive
8294 char *
8295 guestfs_inspect_get_windows_software_hive (guestfs_h *g,
8296 const char *root);
8297 This returns the path to the hive (binary Windows Registry file)
8299 corresponding to HKLM\SOFTWARE.
8300 This call assumes that the guest is Windows and that the guest has a
8302 software hive file with the right name. If this is not the case then
8303 an error is returned. This call does not check that the hive is a
8304 valid Windows Registry hive.
8305 You can use "guestfs_hivex_open" to read or write to the hive.
8307 Please read "INSPECTION" for more details.
8309 This function returns a string, or NULL on error. The caller must free
8311 the returned string after use.
8312 (Added in 1.35.26)
8314 guestfs_inspect_get_windows_system_hive
8316 char *
8317 guestfs_inspect_get_windows_system_hive (guestfs_h *g,
8318 const char *root);
8319 This returns the path to the hive (binary Windows Registry file)
8321 corresponding to HKLM\SYSTEM.
8322 This call assumes that the guest is Windows and that the guest has a
8324 system hive file with the right name. If this is not the case then an
8325 error is returned. This call does not check that the hive is a valid
8326 Windows Registry hive.
8327 You can use "guestfs_hivex_open" to read or write to the hive.
8329 Please read "INSPECTION" for more details.
8331 This function returns a string, or NULL on error. The caller must free
8333 the returned string after use.
8334 (Added in 1.35.26)
8336 guestfs_inspect_get_windows_systemroot
8338 char *
8339 guestfs_inspect_get_windows_systemroot (guestfs_h *g,
8340 const char *root);
8341 This returns the Windows systemroot of the inspected guest. The
8343 systemroot is a directory path such as /WINDOWS.
8344 This call assumes that the guest is Windows and that the systemroot
8346 could be determined by inspection. If this is not the case then an
8347 error is returned.
8348 Please read "INSPECTION" for more details.
8350 This function returns a string, or NULL on error. The caller must free
8352 the returned string after use.
8353 (Added in 1.5.25)
8355 guestfs_inspect_is_live
8357 int
8358 guestfs_inspect_is_live (guestfs_h *g,
8359 const char *root);
8360 This function is deprecated. There is no replacement. Consult the API
8362 documentation in guestfs(3) for further information.
8363 Deprecated functions will not be removed from the API, but the fact
8365 that they are deprecated indicates that there are problems with correct
8366 use of these functions.
8367 This is deprecated and always returns "false".
8369 Please read "INSPECTION" for more details.
8371 This function returns a C truth value on success or -1 on error.
8373 (Added in 1.9.4)
8375 guestfs_inspect_is_multipart
8377 int
8378 guestfs_inspect_is_multipart (guestfs_h *g,
8379 const char *root);
8380 This function is deprecated. There is no replacement. Consult the API
8382 documentation in guestfs(3) for further information.
8383 Deprecated functions will not be removed from the API, but the fact
8385 that they are deprecated indicates that there are problems with correct
8386 use of these functions.
8387 This is deprecated and always returns "false".
8389 Please read "INSPECTION" for more details.
8391 This function returns a C truth value on success or -1 on error.
8393 (Added in 1.9.4)
8395 guestfs_inspect_is_netinst
8397 int
8398 guestfs_inspect_is_netinst (guestfs_h *g,
8399 const char *root);
8400 This function is deprecated. There is no replacement. Consult the API
8402 documentation in guestfs(3) for further information.
8403 Deprecated functions will not be removed from the API, but the fact
8405 that they are deprecated indicates that there are problems with correct
8406 use of these functions.
8407 This is deprecated and always returns "false".
8409 Please read "INSPECTION" for more details.
8411 This function returns a C truth value on success or -1 on error.
8413 (Added in 1.9.4)
8415 guestfs_inspect_list_applications
8417 struct guestfs_application_list *
8418 guestfs_inspect_list_applications (guestfs_h *g,
8419 const char *root);
8420 This function is deprecated. In new code, use the
8422 "guestfs_inspect_list_applications2" call instead.
8423 Deprecated functions will not be removed from the API, but the fact
8425 that they are deprecated indicates that there are problems with correct
8426 use of these functions.
8427 Return the list of applications installed in the operating system.
8429 Note: This call works differently from other parts of the inspection
8431 API. You have to call "guestfs_inspect_os", then
8432 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8433 calling this. Listing applications is a significantly more difficult
8434 operation which requires access to the full filesystem. Also note that
8435 unlike the other "guestfs_inspect_get_*" calls which are just returning
8436 data cached in the libguestfs handle, this call actually reads parts of
8437 the mounted filesystems during the call.
8438 This returns an empty list if the inspection code was not able to
8440 determine the list of applications.
8441 The application structure contains the following fields:
8443 "app_name"
8445 The name of the application. For Red Hat-derived and Debian-
8446 derived Linux guests, this is the package name.
8447 "app_display_name"
8449 The display name of the application, sometimes localized to the
8450 install language of the guest operating system.
8451 If unavailable this is returned as an empty string "". Callers
8453 needing to display something can use "app_name" instead.
8454 "app_epoch"
8456 For package managers which use epochs, this contains the epoch of
8457 the package (an integer). If unavailable, this is returned as 0.
8458 "app_version"
8460 The version string of the application or package. If unavailable
8461 this is returned as an empty string "".
8462 "app_release"
8464 The release string of the application or package, for package
8465 managers that use this. If unavailable this is returned as an
8466 empty string "".
8467 "app_install_path"
8469 The installation path of the application (on operating systems such
8470 as Windows which use installation paths). This path is in the
8471 format used by the guest operating system, it is not a libguestfs
8472 path.
8473 If unavailable this is returned as an empty string "".
8475 "app_trans_path"
8477 The install path translated into a libguestfs path. If unavailable
8478 this is returned as an empty string "".
8479 "app_publisher"
8481 The name of the publisher of the application, for package managers
8482 that use this. If unavailable this is returned as an empty string
8483 "".
8484 "app_url"
8486 The URL (eg. upstream URL) of the application. If unavailable this
8487 is returned as an empty string "".
8488 "app_source_package"
8490 For packaging systems which support this, the name of the source
8491 package. If unavailable this is returned as an empty string "".
8492 "app_summary"
8494 A short (usually one line) description of the application or
8495 package. If unavailable this is returned as an empty string "".
8496 "app_description"
8498 A longer description of the application or package. If unavailable
8499 this is returned as an empty string "".
8500 Please read "INSPECTION" for more details.
8502 This function returns a "struct guestfs_application_list *", or NULL if
8504 there was an error. The caller must call
8505 "guestfs_free_application_list" after use.
8506 (Added in 1.7.8)
8508 guestfs_inspect_list_applications2
8510 struct guestfs_application2_list *
8511 guestfs_inspect_list_applications2 (guestfs_h *g,
8512 const char *root);
8513 Return the list of applications installed in the operating system.
8515 Note: This call works differently from other parts of the inspection
8517 API. You have to call "guestfs_inspect_os", then
8518 "guestfs_inspect_get_mountpoints", then mount up the disks, before
8519 calling this. Listing applications is a significantly more difficult
8520 operation which requires access to the full filesystem. Also note that
8521 unlike the other "guestfs_inspect_get_*" calls which are just returning
8522 data cached in the libguestfs handle, this call actually reads parts of
8523 the mounted filesystems during the call.
8524 This returns an empty list if the inspection code was not able to
8526 determine the list of applications.
8527 The application structure contains the following fields:
8529 "app2_name"
8531 The name of the application. For Red Hat-derived and Debian-
8532 derived Linux guests, this is the package name.
8533 "app2_display_name"
8535 The display name of the application, sometimes localized to the
8536 install language of the guest operating system.
8537 If unavailable this is returned as an empty string "". Callers
8539 needing to display something can use "app2_name" instead.
8540 "app2_epoch"
8542 For package managers which use epochs, this contains the epoch of
8543 the package (an integer). If unavailable, this is returned as 0.
8544 "app2_version"
8546 The version string of the application or package. If unavailable
8547 this is returned as an empty string "".
8548 "app2_release"
8550 The release string of the application or package, for package
8551 managers that use this. If unavailable this is returned as an
8552 empty string "".
8553 "app2_arch"
8555 The architecture string of the application or package, for package
8556 managers that use this. If unavailable this is returned as an
8557 empty string "".
8558 "app2_install_path"
8560 The installation path of the application (on operating systems such
8561 as Windows which use installation paths). This path is in the
8562 format used by the guest operating system, it is not a libguestfs
8563 path.
8564 If unavailable this is returned as an empty string "".
8566 "app2_trans_path"
8568 The install path translated into a libguestfs path. If unavailable
8569 this is returned as an empty string "".
8570 "app2_publisher"
8572 The name of the publisher of the application, for package managers
8573 that use this. If unavailable this is returned as an empty string
8574 "".
8575 "app2_url"
8577 The URL (eg. upstream URL) of the application. If unavailable this
8578 is returned as an empty string "".
8579 "app2_source_package"
8581 For packaging systems which support this, the name of the source
8582 package. If unavailable this is returned as an empty string "".
8583 "app2_summary"
8585 A short (usually one line) description of the application or
8586 package. If unavailable this is returned as an empty string "".
8587 "app2_description"
8589 A longer description of the application or package. If unavailable
8590 this is returned as an empty string "".
8591 Please read "INSPECTION" for more details.
8593 This function returns a "struct guestfs_application2_list *", or NULL
8595 if there was an error. The caller must call
8596 "guestfs_free_application2_list" after use.
8597 (Added in 1.19.56)
8599 guestfs_inspect_os
8601 char **
8602 guestfs_inspect_os (guestfs_h *g);
8603 This function uses other libguestfs functions and certain heuristics to
8605 inspect the disk(s) (usually disks belonging to a virtual machine),
8606 looking for operating systems.
8607 The list returned is empty if no operating systems were found.
8609 If one operating system was found, then this returns a list with a
8611 single element, which is the name of the root filesystem of this
8612 operating system. It is also possible for this function to return a
8613 list containing more than one element, indicating a dual-boot or multi-
8614 boot virtual machine, with each element being the root filesystem of
8615 one of the operating systems.
8616 You can pass the root string(s) returned to other
8618 "guestfs_inspect_get_*" functions in order to query further information
8619 about each operating system, such as the name and version.
8620 This function uses other libguestfs features such as "guestfs_mount_ro"
8622 and "guestfs_umount_all" in order to mount and unmount filesystems and
8623 look at the contents. This should be called with no disks currently
8624 mounted. The function may also use Augeas, so any existing Augeas
8625 handle will be closed.
8626 This function cannot decrypt encrypted disks. The caller must do that
8628 first (supplying the necessary keys) if the disk is encrypted.
8629 Please read "INSPECTION" for more details.
8631 See also "guestfs_list_filesystems".
8633 This function returns a NULL-terminated array of strings (like
8635 environ(3)), or NULL if there was an error. The caller must free the
8636 strings and the array after use.
8637 (Added in 1.5.3)
8639 guestfs_is_blockdev
8641 int
8642 guestfs_is_blockdev (guestfs_h *g,
8643 const char *path);
8644 This function is provided for backwards compatibility with earlier
8646 versions of libguestfs. It simply calls "guestfs_is_blockdev_opts"
8647 with no optional arguments.
8648 (Added in 1.5.10)
8650 guestfs_is_blockdev_opts
8652 int
8653 guestfs_is_blockdev_opts (guestfs_h *g,
8654 const char *path,
8655 ...);
8656 You may supply a list of optional arguments to this call. Use zero or
8658 more of the following pairs of parameters, and terminate the list with
8659 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8660 GUESTFS_IS_BLOCKDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8662 This returns "true" if and only if there is a block device with the
8664 given "path" name.
8665 If the optional flag "followsymlinks" is true, then a symlink (or chain
8667 of symlinks) that ends with a block device also causes the function to
8668 return true.
8669 This call only looks at files within the guest filesystem. Libguestfs
8671 partitions and block devices (eg. /dev/sda) cannot be used as the
8672 "path" parameter of this call.
8673 See also "guestfs_stat".
8675 This function returns a C truth value on success or -1 on error.
8677 (Added in 1.5.10)
8679 guestfs_is_blockdev_opts_va
8681 int
8682 guestfs_is_blockdev_opts_va (guestfs_h *g,
8683 const char *path,
8684 va_list args);
8685 This is the "va_list variant" of "guestfs_is_blockdev_opts".
8687 See "CALLS WITH OPTIONAL ARGUMENTS".
8689 guestfs_is_blockdev_opts_argv
8691 int
8692 guestfs_is_blockdev_opts_argv (guestfs_h *g,
8693 const char *path,
8694 const struct guestfs_is_blockdev_opts_argv *optargs);
8695 This is the "argv variant" of "guestfs_is_blockdev_opts".
8697 See "CALLS WITH OPTIONAL ARGUMENTS".
8699 guestfs_is_busy
8701 int
8702 guestfs_is_busy (guestfs_h *g);
8703 This always returns false. This function is deprecated with no
8705 replacement. Do not use this function.
8706 For more information on states, see guestfs(3).
8708 This function returns a C truth value on success or -1 on error.
8710 (Added in 1.0.2)
8712 guestfs_is_chardev
8714 int
8715 guestfs_is_chardev (guestfs_h *g,
8716 const char *path);
8717 This function is provided for backwards compatibility with earlier
8719 versions of libguestfs. It simply calls "guestfs_is_chardev_opts" with
8720 no optional arguments.
8721 (Added in 1.5.10)
8723 guestfs_is_chardev_opts
8725 int
8726 guestfs_is_chardev_opts (guestfs_h *g,
8727 const char *path,
8728 ...);
8729 You may supply a list of optional arguments to this call. Use zero or
8731 more of the following pairs of parameters, and terminate the list with
8732 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8733 GUESTFS_IS_CHARDEV_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8735 This returns "true" if and only if there is a character device with the
8737 given "path" name.
8738 If the optional flag "followsymlinks" is true, then a symlink (or chain
8740 of symlinks) that ends with a chardev also causes the function to
8741 return true.
8742 See also "guestfs_stat".
8744 This function returns a C truth value on success or -1 on error.
8746 (Added in 1.5.10)
8748 guestfs_is_chardev_opts_va
8750 int
8751 guestfs_is_chardev_opts_va (guestfs_h *g,
8752 const char *path,
8753 va_list args);
8754 This is the "va_list variant" of "guestfs_is_chardev_opts".
8756 See "CALLS WITH OPTIONAL ARGUMENTS".
8758 guestfs_is_chardev_opts_argv
8760 int
8761 guestfs_is_chardev_opts_argv (guestfs_h *g,
8762 const char *path,
8763 const struct guestfs_is_chardev_opts_argv *optargs);
8764 This is the "argv variant" of "guestfs_is_chardev_opts".
8766 See "CALLS WITH OPTIONAL ARGUMENTS".
8768 guestfs_is_config
8770 int
8771 guestfs_is_config (guestfs_h *g);
8772 This returns true iff this handle is being configured (in the "CONFIG"
8774 state).
8775 For more information on states, see guestfs(3).
8777 This function returns a C truth value on success or -1 on error.
8779 (Added in 1.0.2)
8781 guestfs_is_dir
8783 int
8784 guestfs_is_dir (guestfs_h *g,
8785 const char *path);
8786 This function is provided for backwards compatibility with earlier
8788 versions of libguestfs. It simply calls "guestfs_is_dir_opts" with no
8789 optional arguments.
8790 (Added in 0.8)
8792 guestfs_is_dir_opts
8794 int
8795 guestfs_is_dir_opts (guestfs_h *g,
8796 const char *path,
8797 ...);
8798 You may supply a list of optional arguments to this call. Use zero or
8800 more of the following pairs of parameters, and terminate the list with
8801 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8802 GUESTFS_IS_DIR_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8804 This returns "true" if and only if there is a directory with the given
8806 "path" name. Note that it returns false for other objects like files.
8807 If the optional flag "followsymlinks" is true, then a symlink (or chain
8809 of symlinks) that ends with a directory also causes the function to
8810 return true.
8811 See also "guestfs_stat".
8813 This function returns a C truth value on success or -1 on error.
8815 (Added in 0.8)
8817 guestfs_is_dir_opts_va
8819 int
8820 guestfs_is_dir_opts_va (guestfs_h *g,
8821 const char *path,
8822 va_list args);
8823 This is the "va_list variant" of "guestfs_is_dir_opts".
8825 See "CALLS WITH OPTIONAL ARGUMENTS".
8827 guestfs_is_dir_opts_argv
8829 int
8830 guestfs_is_dir_opts_argv (guestfs_h *g,
8831 const char *path,
8832 const struct guestfs_is_dir_opts_argv *optargs);
8833 This is the "argv variant" of "guestfs_is_dir_opts".
8835 See "CALLS WITH OPTIONAL ARGUMENTS".
8837 guestfs_is_fifo
8839 int
8840 guestfs_is_fifo (guestfs_h *g,
8841 const char *path);
8842 This function is provided for backwards compatibility with earlier
8844 versions of libguestfs. It simply calls "guestfs_is_fifo_opts" with no
8845 optional arguments.
8846 (Added in 1.5.10)
8848 guestfs_is_fifo_opts
8850 int
8851 guestfs_is_fifo_opts (guestfs_h *g,
8852 const char *path,
8853 ...);
8854 You may supply a list of optional arguments to this call. Use zero or
8856 more of the following pairs of parameters, and terminate the list with
8857 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8858 GUESTFS_IS_FIFO_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8860 This returns "true" if and only if there is a FIFO (named pipe) with
8862 the given "path" name.
8863 If the optional flag "followsymlinks" is true, then a symlink (or chain
8865 of symlinks) that ends with a FIFO also causes the function to return
8866 true.
8867 See also "guestfs_stat".
8869 This function returns a C truth value on success or -1 on error.
8871 (Added in 1.5.10)
8873 guestfs_is_fifo_opts_va
8875 int
8876 guestfs_is_fifo_opts_va (guestfs_h *g,
8877 const char *path,
8878 va_list args);
8879 This is the "va_list variant" of "guestfs_is_fifo_opts".
8881 See "CALLS WITH OPTIONAL ARGUMENTS".
8883 guestfs_is_fifo_opts_argv
8885 int
8886 guestfs_is_fifo_opts_argv (guestfs_h *g,
8887 const char *path,
8888 const struct guestfs_is_fifo_opts_argv *optargs);
8889 This is the "argv variant" of "guestfs_is_fifo_opts".
8891 See "CALLS WITH OPTIONAL ARGUMENTS".
8893 guestfs_is_file
8895 int
8896 guestfs_is_file (guestfs_h *g,
8897 const char *path);
8898 This function is provided for backwards compatibility with earlier
8900 versions of libguestfs. It simply calls "guestfs_is_file_opts" with no
8901 optional arguments.
8902 (Added in 0.8)
8904 guestfs_is_file_opts
8906 int
8907 guestfs_is_file_opts (guestfs_h *g,
8908 const char *path,
8909 ...);
8910 You may supply a list of optional arguments to this call. Use zero or
8912 more of the following pairs of parameters, and terminate the list with
8913 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
8914 GUESTFS_IS_FILE_OPTS_FOLLOWSYMLINKS, int followsymlinks,
8916 This returns "true" if and only if there is a regular file with the
8918 given "path" name. Note that it returns false for other objects like
8919 directories.
8920 If the optional flag "followsymlinks" is true, then a symlink (or chain
8922 of symlinks) that ends with a file also causes the function to return
8923 true.
8924 See also "guestfs_stat".
8926 This function returns a C truth value on success or -1 on error.
8928 (Added in 0.8)
8930 guestfs_is_file_opts_va
8932 int
8933 guestfs_is_file_opts_va (guestfs_h *g,
8934 const char *path,
8935 va_list args);
8936 This is the "va_list variant" of "guestfs_is_file_opts".
8938 See "CALLS WITH OPTIONAL ARGUMENTS".
8940 guestfs_is_file_opts_argv
8942 int
8943 guestfs_is_file_opts_argv (guestfs_h *g,
8944 const char *path,
8945 const struct guestfs_is_file_opts_argv *optargs);
8946 This is the "argv variant" of "guestfs_is_file_opts".
8948 See "CALLS WITH OPTIONAL ARGUMENTS".
8950 guestfs_is_launching
8952 int
8953 guestfs_is_launching (guestfs_h *g);
8954 This returns true iff this handle is launching the subprocess (in the
8956 "LAUNCHING" state).
8957 For more information on states, see guestfs(3).
8959 This function returns a C truth value on success or -1 on error.
8961 (Added in 1.0.2)
8963 guestfs_is_lv
8965 int
8966 guestfs_is_lv (guestfs_h *g,
8967 const char *mountable);
8968 This command tests whether "mountable" is a logical volume, and returns
8970 true iff this is the case.
8971 This function returns a C truth value on success or -1 on error.
8973 (Added in 1.5.3)
8975 guestfs_is_ready
8977 int
8978 guestfs_is_ready (guestfs_h *g);
8979 This returns true iff this handle is ready to accept commands (in the
8981 "READY" state).
8982 For more information on states, see guestfs(3).
8984 This function returns a C truth value on success or -1 on error.
8986 (Added in 1.0.2)
8988 guestfs_is_socket
8990 int
8991 guestfs_is_socket (guestfs_h *g,
8992 const char *path);
8993 This function is provided for backwards compatibility with earlier
8995 versions of libguestfs. It simply calls "guestfs_is_socket_opts" with
8996 no optional arguments.
8997 (Added in 1.5.10)
8999 guestfs_is_socket_opts
9001 int
9002 guestfs_is_socket_opts (guestfs_h *g,
9003 const char *path,
9004 ...);
9005 You may supply a list of optional arguments to this call. Use zero or
9007 more of the following pairs of parameters, and terminate the list with
9008 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
9009 GUESTFS_IS_SOCKET_OPTS_FOLLOWSYMLINKS, int followsymlinks,
9011 This returns "true" if and only if there is a Unix domain socket with
9013 the given "path" name.
9014 If the optional flag "followsymlinks" is true, then a symlink (or chain
9016 of symlinks) that ends with a socket also causes the function to return
9017 true.
9018 See also "guestfs_stat".
9020 This function returns a C truth value on success or -1 on error.
9022 (Added in 1.5.10)
9024 guestfs_is_socket_opts_va
9026 int
9027 guestfs_is_socket_opts_va (guestfs_h *g,
9028 const char *path,
9029 va_list args);
9030 This is the "va_list variant" of "guestfs_is_socket_opts".
9032 See "CALLS WITH OPTIONAL ARGUMENTS".
9034 guestfs_is_socket_opts_argv
9036 int
9037 guestfs_is_socket_opts_argv (guestfs_h *g,
9038 const char *path,
9039 const struct guestfs_is_socket_opts_argv *optargs);
9040 This is the "argv variant" of "guestfs_is_socket_opts".
9042 See "CALLS WITH OPTIONAL ARGUMENTS".
9044 guestfs_is_symlink
9046 int
9047 guestfs_is_symlink (guestfs_h *g,
9048 const char *path);
9049 This returns "true" if and only if there is a symbolic link with the
9051 given "path" name.
9052 See also "guestfs_stat".
9054 This function returns a C truth value on success or -1 on error.
9056 (Added in 1.5.10)
9058 guestfs_is_whole_device
9060 int
9061 guestfs_is_whole_device (guestfs_h *g,
9062 const char *device);
9063 This returns "true" if and only if "device" refers to a whole block
9065 device. That is, not a partition or a logical device.
9066 This function returns a C truth value on success or -1 on error.
9068 (Added in 1.21.9)
9070 guestfs_is_zero
9072 int
9073 guestfs_is_zero (guestfs_h *g,
9074 const char *path);
9075 This returns true iff the file exists and the file is empty or it
9077 contains all zero bytes.
9078 This function returns a C truth value on success or -1 on error.
9080 (Added in 1.11.8)
9082 guestfs_is_zero_device
9084 int
9085 guestfs_is_zero_device (guestfs_h *g,
9086 const char *device);
9087 This returns true iff the device exists and contains all zero bytes.
9089 Note that for large devices this can take a long time to run.
9091 This function returns a C truth value on success or -1 on error.
9093 (Added in 1.11.8)
9095 guestfs_isoinfo
9097 struct guestfs_isoinfo *
9098 guestfs_isoinfo (guestfs_h *g,
9099 const char *isofile);
9100 This is the same as "guestfs_isoinfo_device" except that it works for
9102 an ISO file located inside some other mounted filesystem. Note that in
9103 the common case where you have added an ISO file as a libguestfs
9104 device, you would not call this. Instead you would call
9105 "guestfs_isoinfo_device".
9106 This function returns a "struct guestfs_isoinfo *", or NULL if there
9108 was an error. The caller must call "guestfs_free_isoinfo" after use.
9109 (Added in 1.17.19)
9111 guestfs_isoinfo_device
9113 struct guestfs_isoinfo *
9114 guestfs_isoinfo_device (guestfs_h *g,
9115 const char *device);
9116 "device" is an ISO device. This returns a struct of information read
9118 from the primary volume descriptor (the ISO equivalent of the
9119 superblock) of the device.
9120 Usually it is more efficient to use the isoinfo(1) command with the -d
9122 option on the host to analyze ISO files, instead of going through
9123 libguestfs.
9124 For information on the primary volume descriptor fields, see
9126 http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor
9127 This function returns a "struct guestfs_isoinfo *", or NULL if there
9129 was an error. The caller must call "guestfs_free_isoinfo" after use.
9130 (Added in 1.17.19)
9132 guestfs_journal_close
9134 int
9135 guestfs_journal_close (guestfs_h *g);
9136 Close the journal handle.
9138 This function returns 0 on success or -1 on error.
9140 This function depends on the feature "journal". See also
9142 "guestfs_feature_available".
9143 (Added in 1.23.11)
9145 guestfs_journal_get
9147 struct guestfs_xattr_list *
9148 guestfs_journal_get (guestfs_h *g);
9149 Read the current journal entry. This returns all the fields in the
9151 journal as a set of "(attrname, attrval)" pairs. The "attrname" is the
9152 field name (a string).
9153 The "attrval" is the field value (a binary blob, often but not always a
9155 string). Please note that "attrval" is a byte array, not a
9156 \0-terminated C string.
9157 The length of data may be truncated to the data threshold (see:
9159 "guestfs_journal_set_data_threshold",
9160 "guestfs_journal_get_data_threshold").
9161 If you set the data threshold to unlimited (0) then this call can read
9163 a journal entry of any size, ie. it is not limited by the libguestfs
9164 protocol.
9165 This function returns a "struct guestfs_xattr_list *", or NULL if there
9167 was an error. The caller must call "guestfs_free_xattr_list" after
9168 use.
9169 This function depends on the feature "journal". See also
9171 "guestfs_feature_available".
9172 (Added in 1.23.11)
9174 guestfs_journal_get_data_threshold
9176 int64_t
9177 guestfs_journal_get_data_threshold (guestfs_h *g);
9178 Get the current data threshold for reading journal entries. This is a
9180 hint to the journal that it may truncate data fields to this size when
9181 reading them (note also that it may not truncate them). If this
9182 returns 0, then the threshold is unlimited.
9183 See also "guestfs_journal_set_data_threshold".
9185 On error this function returns -1.
9187 This function depends on the feature "journal". See also
9189 "guestfs_feature_available".
9190 (Added in 1.23.11)
9192 guestfs_journal_get_realtime_usec
9194 int64_t
9195 guestfs_journal_get_realtime_usec (guestfs_h *g);
9196 Get the realtime (wallclock) timestamp of the current journal entry.
9198 On error this function returns -1.
9200 This function depends on the feature "journal". See also
9202 "guestfs_feature_available".
9203 (Added in 1.27.18)
9205 guestfs_journal_next
9207 int
9208 guestfs_journal_next (guestfs_h *g);
9209 Move to the next journal entry. You have to call this at least once
9211 after opening the handle before you are able to read data.
9212 The returned boolean tells you if there are any more journal records to
9214 read. "true" means you can read the next record (eg. using
9215 "guestfs_journal_get"), and "false" means you have reached the end of
9216 the journal.
9217 This function returns a C truth value on success or -1 on error.
9219 This function depends on the feature "journal". See also
9221 "guestfs_feature_available".
9222 (Added in 1.23.11)
9224 guestfs_journal_open
9226 int
9227 guestfs_journal_open (guestfs_h *g,
9228 const char *directory);
9229 Open the systemd journal located in directory. Any previously opened
9231 journal handle is closed.
9232 The contents of the journal can be read using "guestfs_journal_next"
9234 and "guestfs_journal_get".
9235 After you have finished using the journal, you should close the handle
9237 by calling "guestfs_journal_close".
9238 This function returns 0 on success or -1 on error.
9240 This function depends on the feature "journal". See also
9242 "guestfs_feature_available".
9243 (Added in 1.23.11)
9245 guestfs_journal_set_data_threshold
9247 int
9248 guestfs_journal_set_data_threshold (guestfs_h *g,
9249 int64_t threshold);
9250 Set the data threshold for reading journal entries. This is a hint to
9252 the journal that it may truncate data fields to this size when reading
9253 them (note also that it may not truncate them). If you set this to 0,
9254 then the threshold is unlimited.
9255 See also "guestfs_journal_get_data_threshold".
9257 This function returns 0 on success or -1 on error.
9259 This function depends on the feature "journal". See also
9261 "guestfs_feature_available".
9262 (Added in 1.23.11)
9264 guestfs_journal_skip
9266 int64_t
9267 guestfs_journal_skip (guestfs_h *g,
9268 int64_t skip);
9269 Skip forwards ("skip ≥ 0") or backwards ("skip < 0") in the journal.
9271 The number of entries actually skipped is returned (note "rskip ≥ 0").
9273 If this is not the same as the absolute value of the skip parameter
9274 ("|skip|") you passed in then it means you have reached the end or the
9275 start of the journal.
9276 On error this function returns -1.
9278 This function depends on the feature "journal". See also
9280 "guestfs_feature_available".
9281 (Added in 1.23.11)
9283 guestfs_kill_subprocess
9285 int
9286 guestfs_kill_subprocess (guestfs_h *g);
9287 This function is deprecated. In new code, use the "guestfs_shutdown"
9289 call instead.
9290 Deprecated functions will not be removed from the API, but the fact
9292 that they are deprecated indicates that there are problems with correct
9293 use of these functions.
9294 This kills the hypervisor.
9296 Do not call this. See: "guestfs_shutdown" instead.
9298 This function returns 0 on success or -1 on error.
9300 (Added in 0.3)
9302 guestfs_launch
9304 int
9305 guestfs_launch (guestfs_h *g);
9306 You should call this after configuring the handle (eg. adding drives)
9308 but before performing any actions.
9309 Do not call "guestfs_launch" twice on the same handle. Although it
9311 will not give an error (for historical reasons), the precise behaviour
9312 when you do this is not well defined. Handles are very cheap to
9313 create, so create a new one for each launch.
9314 This function returns 0 on success or -1 on error.
9316 This long-running command can generate progress notification messages
9318 so that the caller can display a progress bar or indicator. To receive
9319 these messages, the caller must register a progress event callback.
9320 See "GUESTFS_EVENT_PROGRESS".
9321 (Added in 0.3)
9323 guestfs_lchown
9325 int
9326 guestfs_lchown (guestfs_h *g,
9327 int owner,
9328 int group,
9329 const char *path);
9330 Change the file owner to "owner" and group to "group". This is like
9332 "guestfs_chown" but if "path" is a symlink then the link itself is
9333 changed, not the target.
9334 Only numeric uid and gid are supported. If you want to use names, you
9336 will need to locate and parse the password file yourself (Augeas
9337 support makes this relatively easy).
9338 This function returns 0 on success or -1 on error.
9340 (Added in 1.0.77)
9342 guestfs_ldmtool_create_all
9344 int
9345 guestfs_ldmtool_create_all (guestfs_h *g);
9346 This function scans all block devices looking for Windows dynamic disk
9348 volumes and partitions, and creates devices for any that were found.
9349 Call "guestfs_list_ldm_volumes" and "guestfs_list_ldm_partitions" to
9351 return all devices.
9352 Note that you don't normally need to call this explicitly, since it is
9354 done automatically at "guestfs_launch" time. However you might want to
9355 call this function if you have hotplugged disks or have just created a
9356 Windows dynamic disk.
9357 This function returns 0 on success or -1 on error.
9359 This function depends on the feature "ldm". See also
9361 "guestfs_feature_available".
9362 (Added in 1.20.0)
9364 guestfs_ldmtool_diskgroup_disks
9366 char **
9367 guestfs_ldmtool_diskgroup_disks (guestfs_h *g,
9368 const char *diskgroup);
9369 Return the disks in a Windows dynamic disk group. The "diskgroup"
9371 parameter should be the GUID of a disk group, one element from the list
9372 returned by "guestfs_ldmtool_scan".
9373 This function returns a NULL-terminated array of strings (like
9375 environ(3)), or NULL if there was an error. The caller must free the
9376 strings and the array after use.
9377 This function depends on the feature "ldm". See also
9379 "guestfs_feature_available".
9380 (Added in 1.20.0)
9382 guestfs_ldmtool_diskgroup_name
9384 char *
9385 guestfs_ldmtool_diskgroup_name (guestfs_h *g,
9386 const char *diskgroup);
9387 Return the name of a Windows dynamic disk group. The "diskgroup"
9389 parameter should be the GUID of a disk group, one element from the list
9390 returned by "guestfs_ldmtool_scan".
9391 This function returns a string, or NULL on error. The caller must free
9393 the returned string after use.
9394 This function depends on the feature "ldm". See also
9396 "guestfs_feature_available".
9397 (Added in 1.20.0)
9399 guestfs_ldmtool_diskgroup_volumes
9401 char **
9402 guestfs_ldmtool_diskgroup_volumes (guestfs_h *g,
9403 const char *diskgroup);
9404 Return the volumes in a Windows dynamic disk group. The "diskgroup"
9406 parameter should be the GUID of a disk group, one element from the list
9407 returned by "guestfs_ldmtool_scan".
9408 This function returns a NULL-terminated array of strings (like
9410 environ(3)), or NULL if there was an error. The caller must free the
9411 strings and the array after use.
9412 This function depends on the feature "ldm". See also
9414 "guestfs_feature_available".
9415 (Added in 1.20.0)
9417 guestfs_ldmtool_remove_all
9419 int
9420 guestfs_ldmtool_remove_all (guestfs_h *g);
9421 This is essentially the opposite of "guestfs_ldmtool_create_all". It
9423 removes the device mapper mappings for all Windows dynamic disk volumes
9424 This function returns 0 on success or -1 on error.
9426 This function depends on the feature "ldm". See also
9428 "guestfs_feature_available".
9429 (Added in 1.20.0)
9431 guestfs_ldmtool_scan
9433 char **
9434 guestfs_ldmtool_scan (guestfs_h *g);
9435 This function scans for Windows dynamic disks. It returns a list of
9437 identifiers (GUIDs) for all disk groups that were found. These
9438 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9439 This function scans all block devices. To scan a subset of block
9441 devices, call "guestfs_ldmtool_scan_devices" instead.
9442 This function returns a NULL-terminated array of strings (like
9444 environ(3)), or NULL if there was an error. The caller must free the
9445 strings and the array after use.
9446 This function depends on the feature "ldm". See also
9448 "guestfs_feature_available".
9449 (Added in 1.20.0)
9451 guestfs_ldmtool_scan_devices
9453 char **
9454 guestfs_ldmtool_scan_devices (guestfs_h *g,
9455 char *const *devices);
9456 This function scans for Windows dynamic disks. It returns a list of
9458 identifiers (GUIDs) for all disk groups that were found. These
9459 identifiers can be passed to other "guestfs_ldmtool_*" functions.
9460 The parameter "devices" is a list of block devices which are scanned.
9462 If this list is empty, all block devices are scanned.
9463 This function returns a NULL-terminated array of strings (like
9465 environ(3)), or NULL if there was an error. The caller must free the
9466 strings and the array after use.
9467 This function depends on the feature "ldm". See also
9469 "guestfs_feature_available".
9470 (Added in 1.20.0)
9472 guestfs_ldmtool_volume_hint
9474 char *
9475 guestfs_ldmtool_volume_hint (guestfs_h *g,
9476 const char *diskgroup,
9477 const char *volume);
9478 Return the hint field of the volume named "volume" in the disk group
9480 with GUID "diskgroup". This may not be defined, in which case the
9481 empty string is returned. The hint field is often, though not always,
9482 the name of a Windows drive, eg. "E:".
9483 This function returns a string, or NULL on error. The caller must free
9485 the returned string after use.
9486 This function depends on the feature "ldm". See also
9488 "guestfs_feature_available".
9489 (Added in 1.20.0)
9491 guestfs_ldmtool_volume_partitions
9493 char **
9494 guestfs_ldmtool_volume_partitions (guestfs_h *g,
9495 const char *diskgroup,
9496 const char *volume);
9497 Return the list of partitions in the volume named "volume" in the disk
9499 group with GUID "diskgroup".
9500 This function returns a NULL-terminated array of strings (like
9502 environ(3)), or NULL if there was an error. The caller must free the
9503 strings and the array after use.
9504 This function depends on the feature "ldm". See also
9506 "guestfs_feature_available".
9507 (Added in 1.20.0)
9509 guestfs_ldmtool_volume_type
9511 char *
9512 guestfs_ldmtool_volume_type (guestfs_h *g,
9513 const char *diskgroup,
9514 const char *volume);
9515 Return the type of the volume named "volume" in the disk group with
9517 GUID "diskgroup".
9518 Possible volume types that can be returned here include: "simple",
9520 "spanned", "striped", "mirrored", "raid5". Other types may also be
9521 returned.
9522 This function returns a string, or NULL on error. The caller must free
9524 the returned string after use.
9525 This function depends on the feature "ldm". See also
9527 "guestfs_feature_available".
9528 (Added in 1.20.0)
9530 guestfs_lgetxattr
9532 char *
9533 guestfs_lgetxattr (guestfs_h *g,
9534 const char *path,
9535 const char *name,
9536 size_t *size_r);
9537 Get a single extended attribute from file "path" named "name". If
9539 "path" is a symlink, then this call returns an extended attribute from
9540 the symlink.
9541 Normally it is better to get all extended attributes from a file in one
9543 go by calling "guestfs_getxattrs". However some Linux filesystem
9544 implementations are buggy and do not provide a way to list out
9545 attributes. For these filesystems (notably ntfs-3g) you have to know
9546 the names of the extended attributes you want in advance and call this
9547 function.
9548 Extended attribute values are blobs of binary data. If there is no
9550 extended attribute named "name", this returns an error.
9551 See also: "guestfs_lgetxattrs", "guestfs_getxattr", attr(5).
9553 This function returns a buffer, or NULL on error. The size of the
9555 returned buffer is written to *size_r. The caller must free the
9556 returned buffer after use.
9557 This function depends on the feature "linuxxattrs". See also
9559 "guestfs_feature_available".
9560 (Added in 1.7.24)
9562 guestfs_lgetxattrs
9564 struct guestfs_xattr_list *
9565 guestfs_lgetxattrs (guestfs_h *g,
9566 const char *path);
9567 This is the same as "guestfs_getxattrs", but if "path" is a symbolic
9569 link, then it returns the extended attributes of the link itself.
9570 This function returns a "struct guestfs_xattr_list *", or NULL if there
9572 was an error. The caller must call "guestfs_free_xattr_list" after
9573 use.
9574 This function depends on the feature "linuxxattrs". See also
9576 "guestfs_feature_available".
9577 (Added in 1.0.59)
9579 guestfs_list_9p
9581 char **
9582 guestfs_list_9p (guestfs_h *g);
9583 List all 9p filesystems attached to the guest. A list of mount tags is
9585 returned.
9586 This function returns a NULL-terminated array of strings (like
9588 environ(3)), or NULL if there was an error. The caller must free the
9589 strings and the array after use.
9590 (Added in 1.11.12)
9592 guestfs_list_devices
9594 char **
9595 guestfs_list_devices (guestfs_h *g);
9596 List all the block devices.
9598 The full block device names are returned, eg. /dev/sda.
9600 See also "guestfs_list_filesystems".
9602 This function returns a NULL-terminated array of strings (like
9604 environ(3)), or NULL if there was an error. The caller must free the
9605 strings and the array after use.
9606 (Added in 0.4)
9608 guestfs_list_disk_labels
9610 char **
9611 guestfs_list_disk_labels (guestfs_h *g);
9612 If you add drives using the optional "label" parameter of
9614 "guestfs_add_drive_opts", you can use this call to map between disk
9615 labels, and raw block device and partition names (like /dev/sda and
9616 /dev/sda1).
9617 This returns a hashtable, where keys are the disk labels (without the
9619 /dev/disk/guestfs prefix), and the values are the full raw block device
9620 and partition names (eg. /dev/sda and /dev/sda1).
9621 This function returns a NULL-terminated array of strings, or NULL if
9623 there was an error. The array of strings will always have length
9624 "2n+1", where "n" keys and values alternate, followed by the trailing
9625 NULL entry. The caller must free the strings and the array after use.
9626 (Added in 1.19.49)
9628 guestfs_list_dm_devices
9630 char **
9631 guestfs_list_dm_devices (guestfs_h *g);
9632 List all device mapper devices.
9634 The returned list contains /dev/mapper/* devices, eg. ones created by a
9636 previous call to "guestfs_luks_open".
9637 Device mapper devices which correspond to logical volumes are not
9639 returned in this list. Call "guestfs_lvs" if you want to list logical
9640 volumes.
9641 This function returns a NULL-terminated array of strings (like
9643 environ(3)), or NULL if there was an error. The caller must free the
9644 strings and the array after use.
9645 (Added in 1.11.15)
9647 guestfs_list_filesystems
9649 char **
9650 guestfs_list_filesystems (guestfs_h *g);
9651 This inspection command looks for filesystems on partitions, block
9653 devices and logical volumes, returning a list of "mountables"
9654 containing filesystems and their type.
9655 The return value is a hash, where the keys are the devices containing
9657 filesystems, and the values are the filesystem types. For example:
9658 "/dev/sda1" => "ntfs"
9660 "/dev/sda2" => "ext2"
9661 "/dev/vg_guest/lv_root" => "ext4"
9662 "/dev/vg_guest/lv_swap" => "swap"
9663 The key is not necessarily a block device. It may also be an opaque
9665 ‘mountable’ string which can be passed to "guestfs_mount".
9666 The value can have the special value "unknown", meaning the content of
9668 the device is undetermined or empty. "swap" means a Linux swap
9669 partition.
9670 In libguestfs ≤ 1.36 this command ran other libguestfs commands, which
9672 might have included "guestfs_mount" and "guestfs_umount", and therefore
9673 you had to use this soon after launch and only when nothing else was
9674 mounted. This restriction is removed in libguestfs ≥ 1.38.
9675 Not all of the filesystems returned will be mountable. In particular,
9677 swap partitions are returned in the list. Also this command does not
9678 check that each filesystem found is valid and mountable, and some
9679 filesystems might be mountable but require special options.
9680 Filesystems may not all belong to a single logical operating system
9681 (use "guestfs_inspect_os" to look for OSes).
9682 This function returns a NULL-terminated array of strings, or NULL if
9684 there was an error. The array of strings will always have length
9685 "2n+1", where "n" keys and values alternate, followed by the trailing
9686 NULL entry. The caller must free the strings and the array after use.
9687 (Added in 1.5.15)
9689 guestfs_list_ldm_partitions
9691 char **
9692 guestfs_list_ldm_partitions (guestfs_h *g);
9693 This function returns all Windows dynamic disk partitions that were
9695 found at launch time. It returns a list of device names.
9696 This function returns a NULL-terminated array of strings (like
9698 environ(3)), or NULL if there was an error. The caller must free the
9699 strings and the array after use.
9700 This function depends on the feature "ldm". See also
9702 "guestfs_feature_available".
9703 (Added in 1.20.0)
9705 guestfs_list_ldm_volumes
9707 char **
9708 guestfs_list_ldm_volumes (guestfs_h *g);
9709 This function returns all Windows dynamic disk volumes that were found
9711 at launch time. It returns a list of device names.
9712 This function returns a NULL-terminated array of strings (like
9714 environ(3)), or NULL if there was an error. The caller must free the
9715 strings and the array after use.
9716 This function depends on the feature "ldm". See also
9718 "guestfs_feature_available".
9719 (Added in 1.20.0)
9721 guestfs_list_md_devices
9723 char **
9724 guestfs_list_md_devices (guestfs_h *g);
9725 List all Linux md devices.
9727 This function returns a NULL-terminated array of strings (like
9729 environ(3)), or NULL if there was an error. The caller must free the
9730 strings and the array after use.
9731 (Added in 1.15.4)
9733 guestfs_list_partitions
9735 char **
9736 guestfs_list_partitions (guestfs_h *g);
9737 List all the partitions detected on all block devices.
9739 The full partition device names are returned, eg. /dev/sda1
9741 This does not return logical volumes. For that you will need to call
9743 "guestfs_lvs".
9744 See also "guestfs_list_filesystems".
9746 This function returns a NULL-terminated array of strings (like
9748 environ(3)), or NULL if there was an error. The caller must free the
9749 strings and the array after use.
9750 (Added in 0.4)
9752 guestfs_ll
9754 char *
9755 guestfs_ll (guestfs_h *g,
9756 const char *directory);
9757 List the files in directory (relative to the root directory, there is
9759 no cwd) in the format of 'ls -la'.
9760 This command is mostly useful for interactive sessions. It is not
9762 intended that you try to parse the output string.
9763 This function returns a string, or NULL on error. The caller must free
9765 the returned string after use.
9766 (Added in 0.4)
9768 guestfs_llz
9770 char *
9771 guestfs_llz (guestfs_h *g,
9772 const char *directory);
9773 This function is deprecated. In new code, use the "guestfs_lgetxattrs"
9775 call instead.
9776 Deprecated functions will not be removed from the API, but the fact
9778 that they are deprecated indicates that there are problems with correct
9779 use of these functions.
9780 List the files in directory in the format of 'ls -laZ'.
9782 This command is mostly useful for interactive sessions. It is not
9784 intended that you try to parse the output string.
9785 This function returns a string, or NULL on error. The caller must free
9787 the returned string after use.
9788 (Added in 1.17.6)
9790 guestfs_ln
9792 int
9793 guestfs_ln (guestfs_h *g,
9794 const char *target,
9795 const char *linkname);
9796 This command creates a hard link using the "ln" command.
9798 This function returns 0 on success or -1 on error.
9800 (Added in 1.0.66)
9802 guestfs_ln_f
9804 int
9805 guestfs_ln_f (guestfs_h *g,
9806 const char *target,
9807 const char *linkname);
9808 This command creates a hard link using the "ln -f" command. The -f
9810 option removes the link ("linkname") if it exists already.
9811 This function returns 0 on success or -1 on error.
9813 (Added in 1.0.66)
9815 guestfs_ln_s
9817 int
9818 guestfs_ln_s (guestfs_h *g,
9819 const char *target,
9820 const char *linkname);
9821 This command creates a symbolic link using the "ln -s" command.
9823 This function returns 0 on success or -1 on error.
9825 (Added in 1.0.66)
9827 guestfs_ln_sf
9829 int
9830 guestfs_ln_sf (guestfs_h *g,
9831 const char *target,
9832 const char *linkname);
9833 This command creates a symbolic link using the "ln -sf" command, The -f
9835 option removes the link ("linkname") if it exists already.
9836 This function returns 0 on success or -1 on error.
9838 (Added in 1.0.66)
9840 guestfs_lremovexattr
9842 int
9843 guestfs_lremovexattr (guestfs_h *g,
9844 const char *xattr,
9845 const char *path);
9846 This is the same as "guestfs_removexattr", but if "path" is a symbolic
9848 link, then it removes an extended attribute of the link itself.
9849 This function returns 0 on success or -1 on error.
9851 This function depends on the feature "linuxxattrs". See also
9853 "guestfs_feature_available".
9854 (Added in 1.0.59)
9856 guestfs_ls
9858 char **
9859 guestfs_ls (guestfs_h *g,
9860 const char *directory);
9861 List the files in directory (relative to the root directory, there is
9863 no cwd). The '.' and '..' entries are not returned, but hidden files
9864 are shown.
9865 This function returns a NULL-terminated array of strings (like
9867 environ(3)), or NULL if there was an error. The caller must free the
9868 strings and the array after use.
9869 (Added in 0.4)
9871 guestfs_ls0
9873 int
9874 guestfs_ls0 (guestfs_h *g,
9875 const char *dir,
9876 const char *filenames);
9877 This specialized command is used to get a listing of the filenames in
9879 the directory "dir". The list of filenames is written to the local
9880 file filenames (on the host).
9881 In the output file, the filenames are separated by "\0" characters.
9883 "." and ".." are not returned. The filenames are not sorted.
9885 This function returns 0 on success or -1 on error.
9887 (Added in 1.19.32)
9889 guestfs_lsetxattr
9891 int
9892 guestfs_lsetxattr (guestfs_h *g,
9893 const char *xattr,
9894 const char *val,
9895 int vallen,
9896 const char *path);
9897 This is the same as "guestfs_setxattr", but if "path" is a symbolic
9899 link, then it sets an extended attribute of the link itself.
9900 This function returns 0 on success or -1 on error.
9902 This function depends on the feature "linuxxattrs". See also
9904 "guestfs_feature_available".
9905 (Added in 1.0.59)
9907 guestfs_lstat
9909 struct guestfs_stat *
9910 guestfs_lstat (guestfs_h *g,
9911 const char *path);
9912 This function is deprecated. In new code, use the "guestfs_lstatns"
9914 call instead.
9915 Deprecated functions will not be removed from the API, but the fact
9917 that they are deprecated indicates that there are problems with correct
9918 use of these functions.
9919 Returns file information for the given "path".
9921 This is the same as "guestfs_stat" except that if "path" is a symbolic
9923 link, then the link is stat-ed, not the file it refers to.
9924 This is the same as the lstat(2) system call.
9926 This function returns a "struct guestfs_stat *", or NULL if there was
9928 an error. The caller must call "guestfs_free_stat" after use.
9929 (Added in 1.9.2)
9931 guestfs_lstatlist
9933 struct guestfs_stat_list *
9934 guestfs_lstatlist (guestfs_h *g,
9935 const char *path,
9936 char *const *names);
9937 This function is deprecated. In new code, use the
9939 "guestfs_lstatnslist" call instead.
9940 Deprecated functions will not be removed from the API, but the fact
9942 that they are deprecated indicates that there are problems with correct
9943 use of these functions.
9944 This call allows you to perform the "guestfs_lstat" operation on
9946 multiple files, where all files are in the directory "path". "names"
9947 is the list of files from this directory.
9948 On return you get a list of stat structs, with a one-to-one
9950 correspondence to the "names" list. If any name did not exist or could
9951 not be lstat'd, then the "st_ino" field of that structure is set to
9952 "-1".
9953 This call is intended for programs that want to efficiently list a
9955 directory contents without making many round-trips. See also
9956 "guestfs_lxattrlist" for a similarly efficient call for getting
9957 extended attributes.
9958 This function returns a "struct guestfs_stat_list *", or NULL if there
9960 was an error. The caller must call "guestfs_free_stat_list" after use.
9961 (Added in 1.0.77)
9963 guestfs_lstatns
9965 struct guestfs_statns *
9966 guestfs_lstatns (guestfs_h *g,
9967 const char *path);
9968 Returns file information for the given "path".
9970 This is the same as "guestfs_statns" except that if "path" is a
9972 symbolic link, then the link is stat-ed, not the file it refers to.
9973 This is the same as the lstat(2) system call.
9975 This function returns a "struct guestfs_statns *", or NULL if there was
9977 an error. The caller must call "guestfs_free_statns" after use.
9978 (Added in 1.27.53)
9980 guestfs_lstatnslist
9982 struct guestfs_statns_list *
9983 guestfs_lstatnslist (guestfs_h *g,
9984 const char *path,
9985 char *const *names);
9986 This call allows you to perform the "guestfs_lstatns" operation on
9988 multiple files, where all files are in the directory "path". "names"
9989 is the list of files from this directory.
9990 On return you get a list of stat structs, with a one-to-one
9992 correspondence to the "names" list. If any name did not exist or could
9993 not be lstat'd, then the "st_ino" field of that structure is set to
9994 "-1".
9995 This call is intended for programs that want to efficiently list a
9997 directory contents without making many round-trips. See also
9998 "guestfs_lxattrlist" for a similarly efficient call for getting
9999 extended attributes.
10000 This function returns a "struct guestfs_statns_list *", or NULL if
10002 there was an error. The caller must call "guestfs_free_statns_list"
10003 after use.
10004 (Added in 1.27.53)
10006 guestfs_luks_add_key
10008 int
10009 guestfs_luks_add_key (guestfs_h *g,
10010 const char *device,
10011 const char *key,
10012 const char *newkey,
10013 int keyslot);
10014 This command adds a new key on LUKS device "device". "key" is any
10016 existing key, and is used to access the device. "newkey" is the new
10017 key to add. "keyslot" is the key slot that will be replaced.
10018 Note that if "keyslot" already contains a key, then this command will
10020 fail. You have to use "guestfs_luks_kill_slot" first to remove that
10021 key.
10022 This function returns 0 on success or -1 on error.
10024 This function takes a key or passphrase parameter which could contain
10026 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10027 information.
10028 This function depends on the feature "luks". See also
10030 "guestfs_feature_available".
10031 (Added in 1.5.2)
10033 guestfs_luks_close
10035 int
10036 guestfs_luks_close (guestfs_h *g,
10037 const char *device);
10038 This closes a LUKS device that was created earlier by
10040 "guestfs_luks_open" or "guestfs_luks_open_ro". The "device" parameter
10041 must be the name of the LUKS mapping device (ie. /dev/mapper/mapname)
10042 and not the name of the underlying block device.
10043 This function returns 0 on success or -1 on error.
10045 This function depends on the feature "luks". See also
10047 "guestfs_feature_available".
10048 (Added in 1.5.1)
10050 guestfs_luks_format
10052 int
10053 guestfs_luks_format (guestfs_h *g,
10054 const char *device,
10055 const char *key,
10056 int keyslot);
10057 This command erases existing data on "device" and formats the device as
10059 a LUKS encrypted device. "key" is the initial key, which is added to
10060 key slot "slot". (LUKS supports 8 key slots, numbered 0-7).
10061 This function returns 0 on success or -1 on error.
10063 This function takes a key or passphrase parameter which could contain
10065 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10066 information.
10067 This function depends on the feature "luks". See also
10069 "guestfs_feature_available".
10070 (Added in 1.5.2)
10072 guestfs_luks_format_cipher
10074 int
10075 guestfs_luks_format_cipher (guestfs_h *g,
10076 const char *device,
10077 const char *key,
10078 int keyslot,
10079 const char *cipher);
10080 This command is the same as "guestfs_luks_format" but it also allows
10082 you to set the "cipher" used.
10083 This function returns 0 on success or -1 on error.
10085 This function takes a key or passphrase parameter which could contain
10087 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10088 information.
10089 This function depends on the feature "luks". See also
10091 "guestfs_feature_available".
10092 (Added in 1.5.2)
10094 guestfs_luks_kill_slot
10096 int
10097 guestfs_luks_kill_slot (guestfs_h *g,
10098 const char *device,
10099 const char *key,
10100 int keyslot);
10101 This command deletes the key in key slot "keyslot" from the encrypted
10103 LUKS device "device". "key" must be one of the other keys.
10104 This function returns 0 on success or -1 on error.
10106 This function takes a key or passphrase parameter which could contain
10108 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10109 information.
10110 This function depends on the feature "luks". See also
10112 "guestfs_feature_available".
10113 (Added in 1.5.2)
10115 guestfs_luks_open
10117 int
10118 guestfs_luks_open (guestfs_h *g,
10119 const char *device,
10120 const char *key,
10121 const char *mapname);
10122 This command opens a block device which has been encrypted according to
10124 the Linux Unified Key Setup (LUKS) standard.
10125 "device" is the encrypted block device or partition.
10127 The caller must supply one of the keys associated with the LUKS block
10129 device, in the "key" parameter.
10130 This creates a new block device called /dev/mapper/mapname. Reads and
10132 writes to this block device are decrypted from and encrypted to the
10133 underlying "device" respectively.
10134 If this block device contains LVM volume groups, then calling
10136 "guestfs_lvm_scan" with the "activate" parameter "true" will make them
10137 visible.
10138 Use "guestfs_list_dm_devices" to list all device mapper devices.
10140 This function returns 0 on success or -1 on error.
10142 This function takes a key or passphrase parameter which could contain
10144 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10145 information.
10146 This function depends on the feature "luks". See also
10148 "guestfs_feature_available".
10149 (Added in 1.5.1)
10151 guestfs_luks_open_ro
10153 int
10154 guestfs_luks_open_ro (guestfs_h *g,
10155 const char *device,
10156 const char *key,
10157 const char *mapname);
10158 This is the same as "guestfs_luks_open" except that a read-only mapping
10160 is created.
10161 This function returns 0 on success or -1 on error.
10163 This function takes a key or passphrase parameter which could contain
10165 sensitive material. Read the section "KEYS AND PASSPHRASES" for more
10166 information.
10167 This function depends on the feature "luks". See also
10169 "guestfs_feature_available".
10170 (Added in 1.5.1)
10172 guestfs_lvcreate
10174 int
10175 guestfs_lvcreate (guestfs_h *g,
10176 const char *logvol,
10177 const char *volgroup,
10178 int mbytes);
10179 This creates an LVM logical volume called "logvol" on the volume group
10181 "volgroup", with "size" megabytes.
10182 This function returns 0 on success or -1 on error.
10184 This function depends on the feature "lvm2". See also
10186 "guestfs_feature_available".
10187 (Added in 0.8)
10189 guestfs_lvcreate_free
10191 int
10192 guestfs_lvcreate_free (guestfs_h *g,
10193 const char *logvol,
10194 const char *volgroup,
10195 int percent);
10196 Create an LVM logical volume called /dev/volgroup/logvol, using
10198 approximately "percent" % of the free space remaining in the volume
10199 group. Most usefully, when "percent" is 100 this will create the
10200 largest possible LV.
10201 This function returns 0 on success or -1 on error.
10203 This function depends on the feature "lvm2". See also
10205 "guestfs_feature_available".
10206 (Added in 1.17.18)
10208 guestfs_lvm_canonical_lv_name
10210 char *
10211 guestfs_lvm_canonical_lv_name (guestfs_h *g,
10212 const char *lvname);
10213 This converts alternative naming schemes for LVs that you might find to
10215 the canonical name. For example, /dev/mapper/VG-LV is converted to
10216 /dev/VG/LV.
10217 This command returns an error if the "lvname" parameter does not refer
10219 to a logical volume.
10220 See also "guestfs_is_lv", "guestfs_canonical_device_name".
10222 This function returns a string, or NULL on error. The caller must free
10224 the returned string after use.
10225 (Added in 1.5.24)
10227 guestfs_lvm_clear_filter
10229 int
10230 guestfs_lvm_clear_filter (guestfs_h *g);
10231 This undoes the effect of "guestfs_lvm_set_filter". LVM will be able
10233 to see every block device.
10234 This command also clears the LVM cache and performs a volume group
10236 scan.
10237 This function returns 0 on success or -1 on error.
10239 (Added in 1.5.1)
10241 guestfs_lvm_remove_all
10243 int
10244 guestfs_lvm_remove_all (guestfs_h *g);
10245 This command removes all LVM logical volumes, volume groups and
10247 physical volumes.
10248 This function returns 0 on success or -1 on error.
10250 This function depends on the feature "lvm2". See also
10252 "guestfs_feature_available".
10253 (Added in 0.8)
10255 guestfs_lvm_scan
10257 int
10258 guestfs_lvm_scan (guestfs_h *g,
10259 int activate);
10260 This scans all block devices and rebuilds the list of LVM physical
10262 volumes, volume groups and logical volumes.
10263 If the "activate" parameter is "true" then newly found volume groups
10265 and logical volumes are activated, meaning the LV /dev/VG/LV devices
10266 become visible.
10267 When a libguestfs handle is launched it scans for existing devices, so
10269 you do not normally need to use this API. However it is useful when
10270 you have added a new device or deleted an existing device (such as when
10271 the "guestfs_luks_open" API is used).
10272 This function returns 0 on success or -1 on error.
10274 (Added in 1.39.8)
10276 guestfs_lvm_set_filter
10278 int
10279 guestfs_lvm_set_filter (guestfs_h *g,
10280 char *const *devices);
10281 This sets the LVM device filter so that LVM will only be able to "see"
10283 the block devices in the list "devices", and will ignore all other
10284 attached block devices.
10285 Where disk image(s) contain duplicate PVs or VGs, this command is
10287 useful to get LVM to ignore the duplicates, otherwise LVM can get
10288 confused. Note also there are two types of duplication possible:
10289 either cloned PVs/VGs which have identical UUIDs; or VGs that are not
10290 cloned but just happen to have the same name. In normal operation you
10291 cannot create this situation, but you can do it outside LVM, eg. by
10292 cloning disk images or by bit twiddling inside the LVM metadata.
10293 This command also clears the LVM cache and performs a volume group
10295 scan.
10296 You can filter whole block devices or individual partitions.
10298 You cannot use this if any VG is currently in use (eg. contains a
10300 mounted filesystem), even if you are not filtering out that VG.
10301 This function returns 0 on success or -1 on error.
10303 This function depends on the feature "lvm2". See also
10305 "guestfs_feature_available".
10306 (Added in 1.5.1)
10308 guestfs_lvremove
10310 int
10311 guestfs_lvremove (guestfs_h *g,
10312 const char *device);
10313 Remove an LVM logical volume "device", where "device" is the path to
10315 the LV, such as /dev/VG/LV.
10316 You can also remove all LVs in a volume group by specifying the VG
10318 name, /dev/VG.
10319 This function returns 0 on success or -1 on error.
10321 This function depends on the feature "lvm2". See also
10323 "guestfs_feature_available".
10324 (Added in 1.0.13)
10326 guestfs_lvrename
10328 int
10329 guestfs_lvrename (guestfs_h *g,
10330 const char *logvol,
10331 const char *newlogvol);
10332 Rename a logical volume "logvol" with the new name "newlogvol".
10334 This function returns 0 on success or -1 on error.
10336 (Added in 1.0.83)
10338 guestfs_lvresize
10340 int
10341 guestfs_lvresize (guestfs_h *g,
10342 const char *device,
10343 int mbytes);
10344 This resizes (expands or shrinks) an existing LVM logical volume to
10346 "mbytes". When reducing, data in the reduced part is lost.
10347 This function returns 0 on success or -1 on error.
10349 This function depends on the feature "lvm2". See also
10351 "guestfs_feature_available".
10352 (Added in 1.0.27)
10354 guestfs_lvresize_free
10356 int
10357 guestfs_lvresize_free (guestfs_h *g,
10358 const char *lv,
10359 int percent);
10360 This expands an existing logical volume "lv" so that it fills "pc"% of
10362 the remaining free space in the volume group. Commonly you would call
10363 this with pc = 100 which expands the logical volume as much as
10364 possible, using all remaining free space in the volume group.
10365 This function returns 0 on success or -1 on error.
10367 This function depends on the feature "lvm2". See also
10369 "guestfs_feature_available".
10370 (Added in 1.3.3)
10372 guestfs_lvs
10374 char **
10375 guestfs_lvs (guestfs_h *g);
10376 List all the logical volumes detected. This is the equivalent of the
10378 lvs(8) command.
10379 This returns a list of the logical volume device names (eg.
10381 /dev/VolGroup00/LogVol00).
10382 See also "guestfs_lvs_full", "guestfs_list_filesystems".
10384 This function returns a NULL-terminated array of strings (like
10386 environ(3)), or NULL if there was an error. The caller must free the
10387 strings and the array after use.
10388 This function depends on the feature "lvm2". See also
10390 "guestfs_feature_available".
10391 (Added in 0.4)
10393 guestfs_lvs_full
10395 struct guestfs_lvm_lv_list *
10396 guestfs_lvs_full (guestfs_h *g);
10397 List all the logical volumes detected. This is the equivalent of the
10399 lvs(8) command. The "full" version includes all fields.
10400 This function returns a "struct guestfs_lvm_lv_list *", or NULL if
10402 there was an error. The caller must call "guestfs_free_lvm_lv_list"
10403 after use.
10404 This function depends on the feature "lvm2". See also
10406 "guestfs_feature_available".
10407 (Added in 0.4)
10409 guestfs_lvuuid
10411 char *
10412 guestfs_lvuuid (guestfs_h *g,
10413 const char *device);
10414 This command returns the UUID of the LVM LV "device".
10416 This function returns a string, or NULL on error. The caller must free
10418 the returned string after use.
10419 (Added in 1.0.87)
10421 guestfs_lxattrlist
10423 struct guestfs_xattr_list *
10424 guestfs_lxattrlist (guestfs_h *g,
10425 const char *path,
10426 char *const *names);
10427 This call allows you to get the extended attributes of multiple files,
10429 where all files are in the directory "path". "names" is the list of
10430 files from this directory.
10431 On return you get a flat list of xattr structs which must be
10433 interpreted sequentially. The first xattr struct always has a zero-
10434 length "attrname". "attrval" in this struct is zero-length to indicate
10435 there was an error doing "lgetxattr" for this file, or is a C string
10436 which is a decimal number (the number of following attributes for this
10437 file, which could be "0"). Then after the first xattr struct are the
10438 zero or more attributes for the first named file. This repeats for the
10439 second and subsequent files.
10440 This call is intended for programs that want to efficiently list a
10442 directory contents without making many round-trips. See also
10443 "guestfs_lstatlist" for a similarly efficient call for getting standard
10444 stats.
10445 This function returns a "struct guestfs_xattr_list *", or NULL if there
10447 was an error. The caller must call "guestfs_free_xattr_list" after
10448 use.
10449 This function depends on the feature "linuxxattrs". See also
10451 "guestfs_feature_available".
10452 (Added in 1.0.77)
10454 guestfs_max_disks
10456 int
10457 guestfs_max_disks (guestfs_h *g);
10458 Return the maximum number of disks that may be added to a handle (eg.
10460 by "guestfs_add_drive_opts" and similar calls).
10461 This function was added in libguestfs 1.19.7. In previous versions of
10463 libguestfs the limit was 25.
10464 See "MAXIMUM NUMBER OF DISKS" for additional information on this topic.
10466 On error this function returns -1.
10468 (Added in 1.19.7)
10470 guestfs_md_create
10472 int
10473 guestfs_md_create (guestfs_h *g,
10474 const char *name,
10475 char *const *devices,
10476 ...);
10477 You may supply a list of optional arguments to this call. Use zero or
10479 more of the following pairs of parameters, and terminate the list with
10480 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10481 GUESTFS_MD_CREATE_MISSINGBITMAP, int64_t missingbitmap,
10483 GUESTFS_MD_CREATE_NRDEVICES, int nrdevices,
10484 GUESTFS_MD_CREATE_SPARE, int spare,
10485 GUESTFS_MD_CREATE_CHUNK, int64_t chunk,
10486 GUESTFS_MD_CREATE_LEVEL, const char *level,
10487 Create a Linux md (RAID) device named "name" on the devices in the list
10489 "devices".
10490 The optional parameters are:
10492 "missingbitmap"
10494 A bitmap of missing devices. If a bit is set it means that a
10495 missing device is added to the array. The least significant bit
10496 corresponds to the first device in the array.
10497 As examples:
10499 If "devices = ["/dev/sda"]" and "missingbitmap = 0x1" then the
10501 resulting array would be "[<missing>, "/dev/sda"]".
10502 If "devices = ["/dev/sda"]" and "missingbitmap = 0x2" then the
10504 resulting array would be "["/dev/sda", <missing>]".
10505 This defaults to 0 (no missing devices).
10507 The length of "devices" + the number of bits set in "missingbitmap"
10509 must equal "nrdevices" + "spare".
10510 "nrdevices"
10512 The number of active RAID devices.
10513 If not set, this defaults to the length of "devices" plus the
10515 number of bits set in "missingbitmap".
10516 "spare"
10518 The number of spare devices.
10519 If not set, this defaults to 0.
10521 "chunk"
10523 The chunk size in bytes.
10524 "level"
10526 The RAID level, which can be one of: linear, raid0, 0, stripe,
10527 raid1, 1, mirror, raid4, 4, raid5, 5, raid6, 6, raid10, 10. Some
10528 of these are synonymous, and more levels may be added in future.
10529 If not set, this defaults to "raid1".
10531 This function returns 0 on success or -1 on error.
10533 This function depends on the feature "mdadm". See also
10535 "guestfs_feature_available".
10536 (Added in 1.15.6)
10538 guestfs_md_create_va
10540 int
10541 guestfs_md_create_va (guestfs_h *g,
10542 const char *name,
10543 char *const *devices,
10544 va_list args);
10545 This is the "va_list variant" of "guestfs_md_create".
10547 See "CALLS WITH OPTIONAL ARGUMENTS".
10549 guestfs_md_create_argv
10551 int
10552 guestfs_md_create_argv (guestfs_h *g,
10553 const char *name,
10554 char *const *devices,
10555 const struct guestfs_md_create_argv *optargs);
10556 This is the "argv variant" of "guestfs_md_create".
10558 See "CALLS WITH OPTIONAL ARGUMENTS".
10560 guestfs_md_detail
10562 char **
10563 guestfs_md_detail (guestfs_h *g,
10564 const char *md);
10565 This command exposes the output of 'mdadm -DY <md>'. The following
10567 fields are usually present in the returned hash. Other fields may also
10568 be present.
10569 "level"
10571 The raid level of the MD device.
10572 "devices"
10574 The number of underlying devices in the MD device.
10575 "metadata"
10577 The metadata version used.
10578 "uuid"
10580 The UUID of the MD device.
10581 "name"
10583 The name of the MD device.
10584 This function returns a NULL-terminated array of strings, or NULL if
10586 there was an error. The array of strings will always have length
10587 "2n+1", where "n" keys and values alternate, followed by the trailing
10588 NULL entry. The caller must free the strings and the array after use.
10589 This function depends on the feature "mdadm". See also
10591 "guestfs_feature_available".
10592 (Added in 1.15.6)
10594 guestfs_md_stat
10596 struct guestfs_mdstat_list *
10597 guestfs_md_stat (guestfs_h *g,
10598 const char *md);
10599 This call returns a list of the underlying devices which make up the
10601 single software RAID array device "md".
10602 To get a list of software RAID devices, call "guestfs_list_md_devices".
10604 Each structure returned corresponds to one device along with additional
10606 status information:
10607 "mdstat_device"
10609 The name of the underlying device.
10610 "mdstat_index"
10612 The index of this device within the array.
10613 "mdstat_flags"
10615 Flags associated with this device. This is a string containing (in
10616 no specific order) zero or more of the following flags:
10617 "W" write-mostly
10619 "F" device is faulty
10621 "S" device is a RAID spare
10623 "R" replacement
10625 This function returns a "struct guestfs_mdstat_list *", or NULL if
10627 there was an error. The caller must call "guestfs_free_mdstat_list"
10628 after use.
10629 This function depends on the feature "mdadm". See also
10631 "guestfs_feature_available".
10632 (Added in 1.17.21)
10634 guestfs_md_stop
10636 int
10637 guestfs_md_stop (guestfs_h *g,
10638 const char *md);
10639 This command deactivates the MD array named "md". The device is
10641 stopped, but it is not destroyed or zeroed.
10642 This function returns 0 on success or -1 on error.
10644 This function depends on the feature "mdadm". See also
10646 "guestfs_feature_available".
10647 (Added in 1.15.6)
10649 guestfs_mkdir
10651 int
10652 guestfs_mkdir (guestfs_h *g,
10653 const char *path);
10654 Create a directory named "path".
10656 This function returns 0 on success or -1 on error.
10658 (Added in 0.8)
10660 guestfs_mkdir_mode
10662 int
10663 guestfs_mkdir_mode (guestfs_h *g,
10664 const char *path,
10665 int mode);
10666 This command creates a directory, setting the initial permissions of
10668 the directory to "mode".
10669 For common Linux filesystems, the actual mode which is set will be
10671 "mode & ~umask & 01777". Non-native-Linux filesystems may interpret
10672 the mode in other ways.
10673 See also "guestfs_mkdir", "guestfs_umask"
10675 This function returns 0 on success or -1 on error.
10677 (Added in 1.0.77)
10679 guestfs_mkdir_p
10681 int
10682 guestfs_mkdir_p (guestfs_h *g,
10683 const char *path);
10684 Create a directory named "path", creating any parent directories as
10686 necessary. This is like the "mkdir -p" shell command.
10687 This function returns 0 on success or -1 on error.
10689 (Added in 0.8)
10691 guestfs_mkdtemp
10693 char *
10694 guestfs_mkdtemp (guestfs_h *g,
10695 const char *tmpl);
10696 This command creates a temporary directory. The "tmpl" parameter
10698 should be a full pathname for the temporary directory name with the
10699 final six characters being "XXXXXX".
10700 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
10702 one being suitable for Windows filesystems.
10703 The name of the temporary directory that was created is returned.
10705 The temporary directory is created with mode 0700 and is owned by root.
10707 The caller is responsible for deleting the temporary directory and its
10709 contents after use.
10710 See also: mkdtemp(3)
10712 This function returns a string, or NULL on error. The caller must free
10714 the returned string after use.
10715 (Added in 1.0.54)
10717 guestfs_mke2fs
10719 int
10720 guestfs_mke2fs (guestfs_h *g,
10721 const char *device,
10722 ...);
10723 You may supply a list of optional arguments to this call. Use zero or
10725 more of the following pairs of parameters, and terminate the list with
10726 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10727 GUESTFS_MKE2FS_BLOCKSCOUNT, int64_t blockscount,
10729 GUESTFS_MKE2FS_BLOCKSIZE, int64_t blocksize,
10730 GUESTFS_MKE2FS_FRAGSIZE, int64_t fragsize,
10731 GUESTFS_MKE2FS_BLOCKSPERGROUP, int64_t blockspergroup,
10732 GUESTFS_MKE2FS_NUMBEROFGROUPS, int64_t numberofgroups,
10733 GUESTFS_MKE2FS_BYTESPERINODE, int64_t bytesperinode,
10734 GUESTFS_MKE2FS_INODESIZE, int64_t inodesize,
10735 GUESTFS_MKE2FS_JOURNALSIZE, int64_t journalsize,
10736 GUESTFS_MKE2FS_NUMBEROFINODES, int64_t numberofinodes,
10737 GUESTFS_MKE2FS_STRIDESIZE, int64_t stridesize,
10738 GUESTFS_MKE2FS_STRIPEWIDTH, int64_t stripewidth,
10739 GUESTFS_MKE2FS_MAXONLINERESIZE, int64_t maxonlineresize,
10740 GUESTFS_MKE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
10741 GUESTFS_MKE2FS_MMPUPDATEINTERVAL, int mmpupdateinterval,
10742 GUESTFS_MKE2FS_JOURNALDEVICE, const char *journaldevice,
10743 GUESTFS_MKE2FS_LABEL, const char *label,
10744 GUESTFS_MKE2FS_LASTMOUNTEDDIR, const char *lastmounteddir,
10745 GUESTFS_MKE2FS_CREATOROS, const char *creatoros,
10746 GUESTFS_MKE2FS_FSTYPE, const char *fstype,
10747 GUESTFS_MKE2FS_USAGETYPE, const char *usagetype,
10748 GUESTFS_MKE2FS_UUID, const char *uuid,
10749 GUESTFS_MKE2FS_FORCECREATE, int forcecreate,
10750 GUESTFS_MKE2FS_WRITESBANDGROUPONLY, int writesbandgrouponly,
10751 GUESTFS_MKE2FS_LAZYITABLEINIT, int lazyitableinit,
10752 GUESTFS_MKE2FS_LAZYJOURNALINIT, int lazyjournalinit,
10753 GUESTFS_MKE2FS_TESTFS, int testfs,
10754 GUESTFS_MKE2FS_DISCARD, int discard,
10755 GUESTFS_MKE2FS_QUOTATYPE, int quotatype,
10756 GUESTFS_MKE2FS_EXTENT, int extent,
10757 GUESTFS_MKE2FS_FILETYPE, int filetype,
10758 GUESTFS_MKE2FS_FLEXBG, int flexbg,
10759 GUESTFS_MKE2FS_HASJOURNAL, int hasjournal,
10760 GUESTFS_MKE2FS_JOURNALDEV, int journaldev,
10761 GUESTFS_MKE2FS_LARGEFILE, int largefile,
10762 GUESTFS_MKE2FS_QUOTA, int quota,
10763 GUESTFS_MKE2FS_RESIZEINODE, int resizeinode,
10764 GUESTFS_MKE2FS_SPARSESUPER, int sparsesuper,
10765 GUESTFS_MKE2FS_UNINITBG, int uninitbg,
10766 "mke2fs" is used to create an ext2, ext3, or ext4 filesystem on
10768 "device".
10769 The optional "blockscount" is the size of the filesystem in blocks. If
10771 omitted it defaults to the size of "device". Note if the filesystem is
10772 too small to contain a journal, "mke2fs" will silently create an ext2
10773 filesystem instead.
10774 This function returns 0 on success or -1 on error.
10776 (Added in 1.19.44)
10778 guestfs_mke2fs_va
10780 int
10781 guestfs_mke2fs_va (guestfs_h *g,
10782 const char *device,
10783 va_list args);
10784 This is the "va_list variant" of "guestfs_mke2fs".
10786 See "CALLS WITH OPTIONAL ARGUMENTS".
10788 guestfs_mke2fs_argv
10790 int
10791 guestfs_mke2fs_argv (guestfs_h *g,
10792 const char *device,
10793 const struct guestfs_mke2fs_argv *optargs);
10794 This is the "argv variant" of "guestfs_mke2fs".
10796 See "CALLS WITH OPTIONAL ARGUMENTS".
10798 guestfs_mke2fs_J
10800 int
10801 guestfs_mke2fs_J (guestfs_h *g,
10802 const char *fstype,
10803 int blocksize,
10804 const char *device,
10805 const char *journal);
10806 This function is deprecated. In new code, use the "guestfs_mke2fs"
10808 call instead.
10809 Deprecated functions will not be removed from the API, but the fact
10811 that they are deprecated indicates that there are problems with correct
10812 use of these functions.
10813 This creates an ext2/3/4 filesystem on "device" with an external
10815 journal on "journal". It is equivalent to the command:
10816 mke2fs -t fstype -b blocksize -J device=<journal> <device>
10818 See also "guestfs_mke2journal".
10820 This function returns 0 on success or -1 on error.
10822 (Added in 1.0.68)
10824 guestfs_mke2fs_JL
10826 int
10827 guestfs_mke2fs_JL (guestfs_h *g,
10828 const char *fstype,
10829 int blocksize,
10830 const char *device,
10831 const char *label);
10832 This function is deprecated. In new code, use the "guestfs_mke2fs"
10834 call instead.
10835 Deprecated functions will not be removed from the API, but the fact
10837 that they are deprecated indicates that there are problems with correct
10838 use of these functions.
10839 This creates an ext2/3/4 filesystem on "device" with an external
10841 journal on the journal labeled "label".
10842 See also "guestfs_mke2journal_L".
10844 This function returns 0 on success or -1 on error.
10846 (Added in 1.0.68)
10848 guestfs_mke2fs_JU
10850 int
10851 guestfs_mke2fs_JU (guestfs_h *g,
10852 const char *fstype,
10853 int blocksize,
10854 const char *device,
10855 const char *uuid);
10856 This function is deprecated. In new code, use the "guestfs_mke2fs"
10858 call instead.
10859 Deprecated functions will not be removed from the API, but the fact
10861 that they are deprecated indicates that there are problems with correct
10862 use of these functions.
10863 This creates an ext2/3/4 filesystem on "device" with an external
10865 journal on the journal with UUID "uuid".
10866 See also "guestfs_mke2journal_U".
10868 This function returns 0 on success or -1 on error.
10870 This function depends on the feature "linuxfsuuid". See also
10872 "guestfs_feature_available".
10873 (Added in 1.0.68)
10875 guestfs_mke2journal
10877 int
10878 guestfs_mke2journal (guestfs_h *g,
10879 int blocksize,
10880 const char *device);
10881 This function is deprecated. In new code, use the "guestfs_mke2fs"
10883 call instead.
10884 Deprecated functions will not be removed from the API, but the fact
10886 that they are deprecated indicates that there are problems with correct
10887 use of these functions.
10888 This creates an ext2 external journal on "device". It is equivalent to
10890 the command:
10891 mke2fs -O journal_dev -b blocksize device
10893 This function returns 0 on success or -1 on error.
10895 (Added in 1.0.68)
10897 guestfs_mke2journal_L
10899 int
10900 guestfs_mke2journal_L (guestfs_h *g,
10901 int blocksize,
10902 const char *label,
10903 const char *device);
10904 This function is deprecated. In new code, use the "guestfs_mke2fs"
10906 call instead.
10907 Deprecated functions will not be removed from the API, but the fact
10909 that they are deprecated indicates that there are problems with correct
10910 use of these functions.
10911 This creates an ext2 external journal on "device" with label "label".
10913 This function returns 0 on success or -1 on error.
10915 (Added in 1.0.68)
10917 guestfs_mke2journal_U
10919 int
10920 guestfs_mke2journal_U (guestfs_h *g,
10921 int blocksize,
10922 const char *uuid,
10923 const char *device);
10924 This function is deprecated. In new code, use the "guestfs_mke2fs"
10926 call instead.
10927 Deprecated functions will not be removed from the API, but the fact
10929 that they are deprecated indicates that there are problems with correct
10930 use of these functions.
10931 This creates an ext2 external journal on "device" with UUID "uuid".
10933 This function returns 0 on success or -1 on error.
10935 This function depends on the feature "linuxfsuuid". See also
10937 "guestfs_feature_available".
10938 (Added in 1.0.68)
10940 guestfs_mkfifo
10942 int
10943 guestfs_mkfifo (guestfs_h *g,
10944 int mode,
10945 const char *path);
10946 This call creates a FIFO (named pipe) called "path" with mode "mode".
10948 It is just a convenient wrapper around "guestfs_mknod".
10949 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
10951 The mode actually set is affected by the umask.
10953 This function returns 0 on success or -1 on error.
10955 This function depends on the feature "mknod". See also
10957 "guestfs_feature_available".
10958 (Added in 1.0.55)
10960 guestfs_mkfs
10962 int
10963 guestfs_mkfs (guestfs_h *g,
10964 const char *fstype,
10965 const char *device);
10966 This function is provided for backwards compatibility with earlier
10968 versions of libguestfs. It simply calls "guestfs_mkfs_opts" with no
10969 optional arguments.
10970 (Added in 0.8)
10972 guestfs_mkfs_opts
10974 int
10975 guestfs_mkfs_opts (guestfs_h *g,
10976 const char *fstype,
10977 const char *device,
10978 ...);
10979 You may supply a list of optional arguments to this call. Use zero or
10981 more of the following pairs of parameters, and terminate the list with
10982 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
10983 GUESTFS_MKFS_OPTS_BLOCKSIZE, int blocksize,
10985 GUESTFS_MKFS_OPTS_FEATURES, const char *features,
10986 GUESTFS_MKFS_OPTS_INODE, int inode,
10987 GUESTFS_MKFS_OPTS_SECTORSIZE, int sectorsize,
10988 GUESTFS_MKFS_OPTS_LABEL, const char *label,
10989 This function creates a filesystem on "device". The filesystem type is
10991 "fstype", for example "ext3".
10992 The optional arguments are:
10994 "blocksize"
10996 The filesystem block size. Supported block sizes depend on the
10997 filesystem type, but typically they are 1024, 2048 or 4096 for
10998 Linux ext2/3 filesystems.
10999 For VFAT and NTFS the "blocksize" parameter is treated as the
11001 requested cluster size.
11002 For UFS block sizes, please see mkfs.ufs(8).
11004 "features"
11006 This passes the -O parameter to the external mkfs program.
11007 For certain filesystem types, this allows extra filesystem features
11009 to be selected. See mke2fs(8) and mkfs.ufs(8) for more details.
11010 You cannot use this optional parameter with the "gfs" or "gfs2"
11012 filesystem type.
11013 "inode"
11015 This passes the -I parameter to the external mke2fs(8) program
11016 which sets the inode size (only for ext2/3/4 filesystems at
11017 present).
11018 "sectorsize"
11020 This passes the -S parameter to external mkfs.ufs(8) program, which
11021 sets sector size for ufs filesystem.
11022 This function returns 0 on success or -1 on error.
11024 (Added in 0.8)
11026 guestfs_mkfs_opts_va
11028 int
11029 guestfs_mkfs_opts_va (guestfs_h *g,
11030 const char *fstype,
11031 const char *device,
11032 va_list args);
11033 This is the "va_list variant" of "guestfs_mkfs_opts".
11035 See "CALLS WITH OPTIONAL ARGUMENTS".
11037 guestfs_mkfs_opts_argv
11039 int
11040 guestfs_mkfs_opts_argv (guestfs_h *g,
11041 const char *fstype,
11042 const char *device,
11043 const struct guestfs_mkfs_opts_argv *optargs);
11044 This is the "argv variant" of "guestfs_mkfs_opts".
11046 See "CALLS WITH OPTIONAL ARGUMENTS".
11048 guestfs_mkfs_b
11050 int
11051 guestfs_mkfs_b (guestfs_h *g,
11052 const char *fstype,
11053 int blocksize,
11054 const char *device);
11055 This function is deprecated. In new code, use the "guestfs_mkfs" call
11057 instead.
11058 Deprecated functions will not be removed from the API, but the fact
11060 that they are deprecated indicates that there are problems with correct
11061 use of these functions.
11062 This call is similar to "guestfs_mkfs", but it allows you to control
11064 the block size of the resulting filesystem. Supported block sizes
11065 depend on the filesystem type, but typically they are 1024, 2048 or
11066 4096 only.
11067 For VFAT and NTFS the "blocksize" parameter is treated as the requested
11069 cluster size.
11070 This function returns 0 on success or -1 on error.
11072 (Added in 1.0.68)
11074 guestfs_mkfs_btrfs
11076 int
11077 guestfs_mkfs_btrfs (guestfs_h *g,
11078 char *const *devices,
11079 ...);
11080 You may supply a list of optional arguments to this call. Use zero or
11082 more of the following pairs of parameters, and terminate the list with
11083 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11084 GUESTFS_MKFS_BTRFS_ALLOCSTART, int64_t allocstart,
11086 GUESTFS_MKFS_BTRFS_BYTECOUNT, int64_t bytecount,
11087 GUESTFS_MKFS_BTRFS_DATATYPE, const char *datatype,
11088 GUESTFS_MKFS_BTRFS_LEAFSIZE, int leafsize,
11089 GUESTFS_MKFS_BTRFS_LABEL, const char *label,
11090 GUESTFS_MKFS_BTRFS_METADATA, const char *metadata,
11091 GUESTFS_MKFS_BTRFS_NODESIZE, int nodesize,
11092 GUESTFS_MKFS_BTRFS_SECTORSIZE, int sectorsize,
11093 Create a btrfs filesystem, allowing all configurables to be set. For
11095 more information on the optional arguments, see mkfs.btrfs(8).
11096 Since btrfs filesystems can span multiple devices, this takes a non-
11098 empty list of devices.
11099 To create general filesystems, use "guestfs_mkfs".
11101 This function returns 0 on success or -1 on error.
11103 This function depends on the feature "btrfs". See also
11105 "guestfs_feature_available".
11106 (Added in 1.17.25)
11108 guestfs_mkfs_btrfs_va
11110 int
11111 guestfs_mkfs_btrfs_va (guestfs_h *g,
11112 char *const *devices,
11113 va_list args);
11114 This is the "va_list variant" of "guestfs_mkfs_btrfs".
11116 See "CALLS WITH OPTIONAL ARGUMENTS".
11118 guestfs_mkfs_btrfs_argv
11120 int
11121 guestfs_mkfs_btrfs_argv (guestfs_h *g,
11122 char *const *devices,
11123 const struct guestfs_mkfs_btrfs_argv *optargs);
11124 This is the "argv variant" of "guestfs_mkfs_btrfs".
11126 See "CALLS WITH OPTIONAL ARGUMENTS".
11128 guestfs_mklost_and_found
11130 int
11131 guestfs_mklost_and_found (guestfs_h *g,
11132 const char *mountpoint);
11133 Make the "lost+found" directory, normally in the root directory of an
11135 ext2/3/4 filesystem. "mountpoint" is the directory under which we try
11136 to create the "lost+found" directory.
11137 This function returns 0 on success or -1 on error.
11139 (Added in 1.19.56)
11141 guestfs_mkmountpoint
11143 int
11144 guestfs_mkmountpoint (guestfs_h *g,
11145 const char *exemptpath);
11146 "guestfs_mkmountpoint" and "guestfs_rmmountpoint" are specialized calls
11148 that can be used to create extra mountpoints before mounting the first
11149 filesystem.
11150 These calls are only necessary in some very limited circumstances,
11152 mainly the case where you want to mount a mix of unrelated and/or read-
11153 only filesystems together.
11154 For example, live CDs often contain a "Russian doll" nest of
11156 filesystems, an ISO outer layer, with a squashfs image inside, with an
11157 ext2/3 image inside that. You can unpack this as follows in guestfish:
11158 add-ro Fedora-11-i686-Live.iso
11160 run
11161 mkmountpoint /cd
11162 mkmountpoint /sqsh
11163 mkmountpoint /ext3fs
11164 mount /dev/sda /cd
11165 mount-loop /cd/LiveOS/squashfs.img /sqsh
11166 mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs
11167 The inner filesystem is now unpacked under the /ext3fs mountpoint.
11169 "guestfs_mkmountpoint" is not compatible with "guestfs_umount_all".
11171 You may get unexpected errors if you try to mix these calls. It is
11172 safest to manually unmount filesystems and remove mountpoints after
11173 use.
11174 "guestfs_umount_all" unmounts filesystems by sorting the paths longest
11176 first, so for this to work for manual mountpoints, you must ensure that
11177 the innermost mountpoints have the longest pathnames, as in the example
11178 code above.
11179 For more details see https://bugzilla.redhat.com/show_bug.cgi?id=599503
11181 Autosync [see "guestfs_set_autosync", this is set by default on
11183 handles] can cause "guestfs_umount_all" to be called when the handle is
11184 closed which can also trigger these issues.
11185 This function returns 0 on success or -1 on error.
11187 (Added in 1.0.62)
11189 guestfs_mknod
11191 int
11192 guestfs_mknod (guestfs_h *g,
11193 int mode,
11194 int devmajor,
11195 int devminor,
11196 const char *path);
11197 This call creates block or character special devices, or named pipes
11199 (FIFOs).
11200 The "mode" parameter should be the mode, using the standard constants.
11202 "devmajor" and "devminor" are the device major and minor numbers, only
11203 used when creating block and character special devices.
11204 Note that, just like mknod(2), the mode must be bitwise OR'd with
11206 S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call just creates
11207 a regular file). These constants are available in the standard Linux
11208 header files, or you can use "guestfs_mknod_b", "guestfs_mknod_c" or
11209 "guestfs_mkfifo" which are wrappers around this command which bitwise
11210 OR in the appropriate constant for you.
11211 The mode actually set is affected by the umask.
11213 This function returns 0 on success or -1 on error.
11215 This function depends on the feature "mknod". See also
11217 "guestfs_feature_available".
11218 (Added in 1.0.55)
11220 guestfs_mknod_b
11222 int
11223 guestfs_mknod_b (guestfs_h *g,
11224 int mode,
11225 int devmajor,
11226 int devminor,
11227 const char *path);
11228 This call creates a block device node called "path" with mode "mode"
11230 and device major/minor "devmajor" and "devminor". It is just a
11231 convenient wrapper around "guestfs_mknod".
11232 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11234 The mode actually set is affected by the umask.
11236 This function returns 0 on success or -1 on error.
11238 This function depends on the feature "mknod". See also
11240 "guestfs_feature_available".
11241 (Added in 1.0.55)
11243 guestfs_mknod_c
11245 int
11246 guestfs_mknod_c (guestfs_h *g,
11247 int mode,
11248 int devmajor,
11249 int devminor,
11250 const char *path);
11251 This call creates a char device node called "path" with mode "mode" and
11253 device major/minor "devmajor" and "devminor". It is just a convenient
11254 wrapper around "guestfs_mknod".
11255 Unlike with "guestfs_mknod", "mode" must contain only permissions bits.
11257 The mode actually set is affected by the umask.
11259 This function returns 0 on success or -1 on error.
11261 This function depends on the feature "mknod". See also
11263 "guestfs_feature_available".
11264 (Added in 1.0.55)
11266 guestfs_mksquashfs
11268 int
11269 guestfs_mksquashfs (guestfs_h *g,
11270 const char *path,
11271 const char *filename,
11272 ...);
11273 You may supply a list of optional arguments to this call. Use zero or
11275 more of the following pairs of parameters, and terminate the list with
11276 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11277 GUESTFS_MKSQUASHFS_COMPRESS, const char *compress,
11279 GUESTFS_MKSQUASHFS_EXCLUDES, char *const *excludes,
11280 Create a squashfs filesystem for the specified "path".
11282 The optional "compress" flag controls compression. If not given, then
11284 the output compressed using "gzip". Otherwise one of the following
11285 strings may be given to select the compression type of the squashfs:
11286 "gzip", "lzma", "lzo", "lz4", "xz".
11287 The other optional arguments are:
11289 "excludes"
11291 A list of wildcards. Files are excluded if they match any of the
11292 wildcards.
11293 Please note that this API may fail when used to compress directories
11295 with large files, such as the resulting squashfs will be over 3GB big.
11296 This function returns 0 on success or -1 on error.
11298 This function depends on the feature "squashfs". See also
11300 "guestfs_feature_available".
11301 (Added in 1.35.25)
11303 guestfs_mksquashfs_va
11305 int
11306 guestfs_mksquashfs_va (guestfs_h *g,
11307 const char *path,
11308 const char *filename,
11309 va_list args);
11310 This is the "va_list variant" of "guestfs_mksquashfs".
11312 See "CALLS WITH OPTIONAL ARGUMENTS".
11314 guestfs_mksquashfs_argv
11316 int
11317 guestfs_mksquashfs_argv (guestfs_h *g,
11318 const char *path,
11319 const char *filename,
11320 const struct guestfs_mksquashfs_argv *optargs);
11321 This is the "argv variant" of "guestfs_mksquashfs".
11323 See "CALLS WITH OPTIONAL ARGUMENTS".
11325 guestfs_mkswap
11327 int
11328 guestfs_mkswap (guestfs_h *g,
11329 const char *device);
11330 This function is provided for backwards compatibility with earlier
11332 versions of libguestfs. It simply calls "guestfs_mkswap_opts" with no
11333 optional arguments.
11334 (Added in 1.0.55)
11336 guestfs_mkswap_opts
11338 int
11339 guestfs_mkswap_opts (guestfs_h *g,
11340 const char *device,
11341 ...);
11342 You may supply a list of optional arguments to this call. Use zero or
11344 more of the following pairs of parameters, and terminate the list with
11345 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11346 GUESTFS_MKSWAP_OPTS_LABEL, const char *label,
11348 GUESTFS_MKSWAP_OPTS_UUID, const char *uuid,
11349 Create a Linux swap partition on "device".
11351 The option arguments "label" and "uuid" allow you to set the label
11353 and/or UUID of the new swap partition.
11354 This function returns 0 on success or -1 on error.
11356 (Added in 1.0.55)
11358 guestfs_mkswap_opts_va
11360 int
11361 guestfs_mkswap_opts_va (guestfs_h *g,
11362 const char *device,
11363 va_list args);
11364 This is the "va_list variant" of "guestfs_mkswap_opts".
11366 See "CALLS WITH OPTIONAL ARGUMENTS".
11368 guestfs_mkswap_opts_argv
11370 int
11371 guestfs_mkswap_opts_argv (guestfs_h *g,
11372 const char *device,
11373 const struct guestfs_mkswap_opts_argv *optargs);
11374 This is the "argv variant" of "guestfs_mkswap_opts".
11376 See "CALLS WITH OPTIONAL ARGUMENTS".
11378 guestfs_mkswap_L
11380 int
11381 guestfs_mkswap_L (guestfs_h *g,
11382 const char *label,
11383 const char *device);
11384 This function is deprecated. In new code, use the "guestfs_mkswap"
11386 call instead.
11387 Deprecated functions will not be removed from the API, but the fact
11389 that they are deprecated indicates that there are problems with correct
11390 use of these functions.
11391 Create a swap partition on "device" with label "label".
11393 Note that you cannot attach a swap label to a block device (eg.
11395 /dev/sda), just to a partition. This appears to be a limitation of the
11396 kernel or swap tools.
11397 This function returns 0 on success or -1 on error.
11399 (Added in 1.0.55)
11401 guestfs_mkswap_U
11403 int
11404 guestfs_mkswap_U (guestfs_h *g,
11405 const char *uuid,
11406 const char *device);
11407 This function is deprecated. In new code, use the "guestfs_mkswap"
11409 call instead.
11410 Deprecated functions will not be removed from the API, but the fact
11412 that they are deprecated indicates that there are problems with correct
11413 use of these functions.
11414 Create a swap partition on "device" with UUID "uuid".
11416 This function returns 0 on success or -1 on error.
11418 This function depends on the feature "linuxfsuuid". See also
11420 "guestfs_feature_available".
11421 (Added in 1.0.55)
11423 guestfs_mkswap_file
11425 int
11426 guestfs_mkswap_file (guestfs_h *g,
11427 const char *path);
11428 Create a swap file.
11430 This command just writes a swap file signature to an existing file. To
11432 create the file itself, use something like "guestfs_fallocate".
11433 This function returns 0 on success or -1 on error.
11435 (Added in 1.0.66)
11437 guestfs_mktemp
11439 char *
11440 guestfs_mktemp (guestfs_h *g,
11441 const char *tmpl,
11442 ...);
11443 You may supply a list of optional arguments to this call. Use zero or
11445 more of the following pairs of parameters, and terminate the list with
11446 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11447 GUESTFS_MKTEMP_SUFFIX, const char *suffix,
11449 This command creates a temporary file. The "tmpl" parameter should be
11451 a full pathname for the temporary directory name with the final six
11452 characters being "XXXXXX".
11453 For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX", the second
11455 one being suitable for Windows filesystems.
11456 The name of the temporary file that was created is returned.
11458 The temporary file is created with mode 0600 and is owned by root.
11460 The caller is responsible for deleting the temporary file after use.
11462 If the optional "suffix" parameter is given, then the suffix (eg.
11464 ".txt") is appended to the temporary name.
11465 See also: "guestfs_mkdtemp".
11467 This function returns a string, or NULL on error. The caller must free
11469 the returned string after use.
11470 (Added in 1.19.53)
11472 guestfs_mktemp_va
11474 char *
11475 guestfs_mktemp_va (guestfs_h *g,
11476 const char *tmpl,
11477 va_list args);
11478 This is the "va_list variant" of "guestfs_mktemp".
11480 See "CALLS WITH OPTIONAL ARGUMENTS".
11482 guestfs_mktemp_argv
11484 char *
11485 guestfs_mktemp_argv (guestfs_h *g,
11486 const char *tmpl,
11487 const struct guestfs_mktemp_argv *optargs);
11488 This is the "argv variant" of "guestfs_mktemp".
11490 See "CALLS WITH OPTIONAL ARGUMENTS".
11492 guestfs_modprobe
11494 int
11495 guestfs_modprobe (guestfs_h *g,
11496 const char *modulename);
11497 This loads a kernel module in the appliance.
11499 This function returns 0 on success or -1 on error.
11501 This function depends on the feature "linuxmodules". See also
11503 "guestfs_feature_available".
11504 (Added in 1.0.68)
11506 guestfs_mount
11508 int
11509 guestfs_mount (guestfs_h *g,
11510 const char *mountable,
11511 const char *mountpoint);
11512 Mount a guest disk at a position in the filesystem. Block devices are
11514 named /dev/sda, /dev/sdb and so on, as they were added to the guest.
11515 If those block devices contain partitions, they will have the usual
11516 names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used, or
11517 ‘mountable’ strings returned by "guestfs_list_filesystems" or
11518 "guestfs_inspect_get_mountpoints".
11519 The rules are the same as for mount(2): A filesystem must first be
11521 mounted on / before others can be mounted. Other filesystems can only
11522 be mounted on directories which already exist.
11523 The mounted filesystem is writable, if we have sufficient permissions
11525 on the underlying device.
11526 Before libguestfs 1.13.16, this call implicitly added the options
11528 "sync" and "noatime". The "sync" option greatly slowed writes and
11529 caused many problems for users. If your program might need to work
11530 with older versions of libguestfs, use "guestfs_mount_options" instead
11531 (using an empty string for the first parameter if you don't want any
11532 options).
11533 This function returns 0 on success or -1 on error.
11535 (Added in 0.3)
11537 guestfs_mount_9p
11539 int
11540 guestfs_mount_9p (guestfs_h *g,
11541 const char *mounttag,
11542 const char *mountpoint,
11543 ...);
11544 You may supply a list of optional arguments to this call. Use zero or
11546 more of the following pairs of parameters, and terminate the list with
11547 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11548 GUESTFS_MOUNT_9P_OPTIONS, const char *options,
11550 Mount the virtio-9p filesystem with the tag "mounttag" on the directory
11552 "mountpoint".
11553 If required, "trans=virtio" will be automatically added to the options.
11555 Any other options required can be passed in the optional "options"
11556 parameter.
11557 This function returns 0 on success or -1 on error.
11559 (Added in 1.11.12)
11561 guestfs_mount_9p_va
11563 int
11564 guestfs_mount_9p_va (guestfs_h *g,
11565 const char *mounttag,
11566 const char *mountpoint,
11567 va_list args);
11568 This is the "va_list variant" of "guestfs_mount_9p".
11570 See "CALLS WITH OPTIONAL ARGUMENTS".
11572 guestfs_mount_9p_argv
11574 int
11575 guestfs_mount_9p_argv (guestfs_h *g,
11576 const char *mounttag,
11577 const char *mountpoint,
11578 const struct guestfs_mount_9p_argv *optargs);
11579 This is the "argv variant" of "guestfs_mount_9p".
11581 See "CALLS WITH OPTIONAL ARGUMENTS".
11583 guestfs_mount_local
11585 int
11586 guestfs_mount_local (guestfs_h *g,
11587 const char *localmountpoint,
11588 ...);
11589 You may supply a list of optional arguments to this call. Use zero or
11591 more of the following pairs of parameters, and terminate the list with
11592 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11593 GUESTFS_MOUNT_LOCAL_READONLY, int readonly,
11595 GUESTFS_MOUNT_LOCAL_OPTIONS, const char *options,
11596 GUESTFS_MOUNT_LOCAL_CACHETIMEOUT, int cachetimeout,
11597 GUESTFS_MOUNT_LOCAL_DEBUGCALLS, int debugcalls,
11598 This call exports the libguestfs-accessible filesystem to a local
11600 mountpoint (directory) called "localmountpoint". Ordinary reads and
11601 writes to files and directories under "localmountpoint" are redirected
11602 through libguestfs.
11603 If the optional "readonly" flag is set to true, then writes to the
11605 filesystem return error "EROFS".
11606 "options" is a comma-separated list of mount options. See
11608 guestmount(1) for some useful options.
11609 "cachetimeout" sets the timeout (in seconds) for cached directory
11611 entries. The default is 60 seconds. See guestmount(1) for further
11612 information.
11613 If "debugcalls" is set to true, then additional debugging information
11615 is generated for every FUSE call.
11616 When "guestfs_mount_local" returns, the filesystem is ready, but is not
11618 processing requests (access to it will block). You have to call
11619 "guestfs_mount_local_run" to run the main loop.
11620 See "MOUNT LOCAL" for full documentation.
11622 This function returns 0 on success or -1 on error.
11624 (Added in 1.17.22)
11626 guestfs_mount_local_va
11628 int
11629 guestfs_mount_local_va (guestfs_h *g,
11630 const char *localmountpoint,
11631 va_list args);
11632 This is the "va_list variant" of "guestfs_mount_local".
11634 See "CALLS WITH OPTIONAL ARGUMENTS".
11636 guestfs_mount_local_argv
11638 int
11639 guestfs_mount_local_argv (guestfs_h *g,
11640 const char *localmountpoint,
11641 const struct guestfs_mount_local_argv *optargs);
11642 This is the "argv variant" of "guestfs_mount_local".
11644 See "CALLS WITH OPTIONAL ARGUMENTS".
11646 guestfs_mount_local_run
11648 int
11649 guestfs_mount_local_run (guestfs_h *g);
11650 Run the main loop which translates kernel calls to libguestfs calls.
11652 This should only be called after "guestfs_mount_local" returns
11654 successfully. The call will not return until the filesystem is
11655 unmounted.
11656 Note you must not make concurrent libguestfs calls on the same handle
11658 from another thread.
11659 You may call this from a different thread than the one which called
11661 "guestfs_mount_local", subject to the usual rules for threads and
11662 libguestfs (see "MULTIPLE HANDLES AND MULTIPLE THREADS").
11663 See "MOUNT LOCAL" for full documentation.
11665 This function returns 0 on success or -1 on error.
11667 (Added in 1.17.22)
11669 guestfs_mount_loop
11671 int
11672 guestfs_mount_loop (guestfs_h *g,
11673 const char *file,
11674 const char *mountpoint);
11675 This command lets you mount file (a filesystem image in a file) on a
11677 mount point. It is entirely equivalent to the command "mount -o loop
11678 file mountpoint".
11679 This function returns 0 on success or -1 on error.
11681 (Added in 1.0.54)
11683 guestfs_mount_options
11685 int
11686 guestfs_mount_options (guestfs_h *g,
11687 const char *options,
11688 const char *mountable,
11689 const char *mountpoint);
11690 This is the same as the "guestfs_mount" command, but it allows you to
11692 set the mount options as for the mount(8) -o flag.
11693 If the "options" parameter is an empty string, then no options are
11695 passed (all options default to whatever the filesystem uses).
11696 This function returns 0 on success or -1 on error.
11698 (Added in 1.0.10)
11700 guestfs_mount_ro
11702 int
11703 guestfs_mount_ro (guestfs_h *g,
11704 const char *mountable,
11705 const char *mountpoint);
11706 This is the same as the "guestfs_mount" command, but it mounts the
11708 filesystem with the read-only (-o ro) flag.
11709 This function returns 0 on success or -1 on error.
11711 (Added in 1.0.10)
11713 guestfs_mount_vfs
11715 int
11716 guestfs_mount_vfs (guestfs_h *g,
11717 const char *options,
11718 const char *vfstype,
11719 const char *mountable,
11720 const char *mountpoint);
11721 This is the same as the "guestfs_mount" command, but it allows you to
11723 set both the mount options and the vfstype as for the mount(8) -o and
11724 -t flags.
11725 This function returns 0 on success or -1 on error.
11727 (Added in 1.0.10)
11729 guestfs_mountable_device
11731 char *
11732 guestfs_mountable_device (guestfs_h *g,
11733 const char *mountable);
11734 Returns the device name of a mountable. In quite a lot of cases, the
11736 mountable is the device name.
11737 However this doesn't apply for btrfs subvolumes, where the mountable is
11739 a combination of both the device name and the subvolume path (see also
11740 "guestfs_mountable_subvolume" to extract the subvolume path of the
11741 mountable if any).
11742 This function returns a string, or NULL on error. The caller must free
11744 the returned string after use.
11745 (Added in 1.33.15)
11747 guestfs_mountable_subvolume
11749 char *
11750 guestfs_mountable_subvolume (guestfs_h *g,
11751 const char *mountable);
11752 Returns the subvolume path of a mountable. Btrfs subvolumes mountables
11754 are a combination of both the device name and the subvolume path (see
11755 also "guestfs_mountable_device" to extract the device of the
11756 mountable).
11757 If the mountable does not represent a btrfs subvolume, then this
11759 function fails and the "errno" is set to "EINVAL".
11760 This function returns a string, or NULL on error. The caller must free
11762 the returned string after use.
11763 (Added in 1.33.15)
11765 guestfs_mountpoints
11767 char **
11768 guestfs_mountpoints (guestfs_h *g);
11769 This call is similar to "guestfs_mounts". That call returns a list of
11771 devices. This one returns a hash table (map) of device name to
11772 directory where the device is mounted.
11773 This function returns a NULL-terminated array of strings, or NULL if
11775 there was an error. The array of strings will always have length
11776 "2n+1", where "n" keys and values alternate, followed by the trailing
11777 NULL entry. The caller must free the strings and the array after use.
11778 (Added in 1.0.62)
11780 guestfs_mounts
11782 char **
11783 guestfs_mounts (guestfs_h *g);
11784 This returns the list of currently mounted filesystems. It returns the
11786 list of devices (eg. /dev/sda1, /dev/VG/LV).
11787 Some internal mounts are not shown.
11789 See also: "guestfs_mountpoints"
11791 This function returns a NULL-terminated array of strings (like
11793 environ(3)), or NULL if there was an error. The caller must free the
11794 strings and the array after use.
11795 (Added in 0.8)
11797 guestfs_mv
11799 int
11800 guestfs_mv (guestfs_h *g,
11801 const char *src,
11802 const char *dest);
11803 This moves a file from "src" to "dest" where "dest" is either a
11805 destination filename or destination directory.
11806 See also: "guestfs_rename".
11808 This function returns 0 on success or -1 on error.
11810 (Added in 1.0.18)
11812 guestfs_nr_devices
11814 int
11815 guestfs_nr_devices (guestfs_h *g);
11816 This returns the number of whole block devices that were added. This
11818 is the same as the number of devices that would be returned if you
11819 called "guestfs_list_devices".
11820 To find out the maximum number of devices that could be added, call
11822 "guestfs_max_disks".
11823 On error this function returns -1.
11825 (Added in 1.19.15)
11827 guestfs_ntfs_3g_probe
11829 int
11830 guestfs_ntfs_3g_probe (guestfs_h *g,
11831 int rw,
11832 const char *device);
11833 This command runs the ntfs-3g.probe(8) command which probes an NTFS
11835 "device" for mountability. (Not all NTFS volumes can be mounted read-
11836 write, and some cannot be mounted at all).
11837 "rw" is a boolean flag. Set it to true if you want to test if the
11839 volume can be mounted read-write. Set it to false if you want to test
11840 if the volume can be mounted read-only.
11841 The return value is an integer which 0 if the operation would succeed,
11843 or some non-zero value documented in the ntfs-3g.probe(8) manual page.
11844 On error this function returns -1.
11846 This function depends on the feature "ntfs3g". See also
11848 "guestfs_feature_available".
11849 (Added in 1.0.43)
11851 guestfs_ntfscat_i
11853 int
11854 guestfs_ntfscat_i (guestfs_h *g,
11855 const char *device,
11856 int64_t inode,
11857 const char *filename);
11858 Download a file given its inode from a NTFS filesystem and save it as
11860 filename on the local machine.
11861 This allows to download some otherwise inaccessible files such as the
11863 ones within the $Extend folder.
11864 The filesystem from which to extract the file must be unmounted,
11866 otherwise the call will fail.
11867 This function returns 0 on success or -1 on error.
11869 This long-running command can generate progress notification messages
11871 so that the caller can display a progress bar or indicator. To receive
11872 these messages, the caller must register a progress event callback.
11873 See "GUESTFS_EVENT_PROGRESS".
11874 (Added in 1.33.14)
11876 guestfs_ntfsclone_in
11878 int
11879 guestfs_ntfsclone_in (guestfs_h *g,
11880 const char *backupfile,
11881 const char *device);
11882 Restore the "backupfile" (from a previous call to
11884 "guestfs_ntfsclone_out") to "device", overwriting any existing contents
11885 of this device.
11886 This function returns 0 on success or -1 on error.
11888 This function depends on the feature "ntfs3g". See also
11890 "guestfs_feature_available".
11891 (Added in 1.17.9)
11893 guestfs_ntfsclone_out
11895 int
11896 guestfs_ntfsclone_out (guestfs_h *g,
11897 const char *device,
11898 const char *backupfile,
11899 ...);
11900 You may supply a list of optional arguments to this call. Use zero or
11902 more of the following pairs of parameters, and terminate the list with
11903 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11904 GUESTFS_NTFSCLONE_OUT_METADATAONLY, int metadataonly,
11906 GUESTFS_NTFSCLONE_OUT_RESCUE, int rescue,
11907 GUESTFS_NTFSCLONE_OUT_IGNOREFSCHECK, int ignorefscheck,
11908 GUESTFS_NTFSCLONE_OUT_PRESERVETIMESTAMPS, int preservetimestamps,
11909 GUESTFS_NTFSCLONE_OUT_FORCE, int force,
11910 Stream the NTFS filesystem "device" to the local file "backupfile".
11912 The format used for the backup file is a special format used by the
11913 ntfsclone(8) tool.
11914 If the optional "metadataonly" flag is true, then only the metadata is
11916 saved, losing all the user data (this is useful for diagnosing some
11917 filesystem problems).
11918 The optional "rescue", "ignorefscheck", "preservetimestamps" and
11920 "force" flags have precise meanings detailed in the ntfsclone(8) man
11921 page.
11922 Use "guestfs_ntfsclone_in" to restore the file back to a libguestfs
11924 device.
11925 This function returns 0 on success or -1 on error.
11927 This function depends on the feature "ntfs3g". See also
11929 "guestfs_feature_available".
11930 (Added in 1.17.9)
11932 guestfs_ntfsclone_out_va
11934 int
11935 guestfs_ntfsclone_out_va (guestfs_h *g,
11936 const char *device,
11937 const char *backupfile,
11938 va_list args);
11939 This is the "va_list variant" of "guestfs_ntfsclone_out".
11941 See "CALLS WITH OPTIONAL ARGUMENTS".
11943 guestfs_ntfsclone_out_argv
11945 int
11946 guestfs_ntfsclone_out_argv (guestfs_h *g,
11947 const char *device,
11948 const char *backupfile,
11949 const struct guestfs_ntfsclone_out_argv *optargs);
11950 This is the "argv variant" of "guestfs_ntfsclone_out".
11952 See "CALLS WITH OPTIONAL ARGUMENTS".
11954 guestfs_ntfsfix
11956 int
11957 guestfs_ntfsfix (guestfs_h *g,
11958 const char *device,
11959 ...);
11960 You may supply a list of optional arguments to this call. Use zero or
11962 more of the following pairs of parameters, and terminate the list with
11963 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
11964 GUESTFS_NTFSFIX_CLEARBADSECTORS, int clearbadsectors,
11966 This command repairs some fundamental NTFS inconsistencies, resets the
11968 NTFS journal file, and schedules an NTFS consistency check for the
11969 first boot into Windows.
11970 This is not an equivalent of Windows "chkdsk". It does not scan the
11972 filesystem for inconsistencies.
11973 The optional "clearbadsectors" flag clears the list of bad sectors.
11975 This is useful after cloning a disk with bad sectors to a new disk.
11976 This function returns 0 on success or -1 on error.
11978 This function depends on the feature "ntfs3g". See also
11980 "guestfs_feature_available".
11981 (Added in 1.17.9)
11983 guestfs_ntfsfix_va
11985 int
11986 guestfs_ntfsfix_va (guestfs_h *g,
11987 const char *device,
11988 va_list args);
11989 This is the "va_list variant" of "guestfs_ntfsfix".
11991 See "CALLS WITH OPTIONAL ARGUMENTS".
11993 guestfs_ntfsfix_argv
11995 int
11996 guestfs_ntfsfix_argv (guestfs_h *g,
11997 const char *device,
11998 const struct guestfs_ntfsfix_argv *optargs);
11999 This is the "argv variant" of "guestfs_ntfsfix".
12001 See "CALLS WITH OPTIONAL ARGUMENTS".
12003 guestfs_ntfsresize
12005 int
12006 guestfs_ntfsresize (guestfs_h *g,
12007 const char *device);
12008 This function is provided for backwards compatibility with earlier
12010 versions of libguestfs. It simply calls "guestfs_ntfsresize_opts" with
12011 no optional arguments.
12012 (Added in 1.3.2)
12014 guestfs_ntfsresize_opts
12016 int
12017 guestfs_ntfsresize_opts (guestfs_h *g,
12018 const char *device,
12019 ...);
12020 You may supply a list of optional arguments to this call. Use zero or
12022 more of the following pairs of parameters, and terminate the list with
12023 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
12024 GUESTFS_NTFSRESIZE_OPTS_SIZE, int64_t size,
12026 GUESTFS_NTFSRESIZE_OPTS_FORCE, int force,
12027 This command resizes an NTFS filesystem, expanding or shrinking it to
12029 the size of the underlying device.
12030 The optional parameters are:
12032 "size"
12034 The new size (in bytes) of the filesystem. If omitted, the
12035 filesystem is resized to fit the container (eg. partition).
12036 "force"
12038 If this option is true, then force the resize of the filesystem
12039 even if the filesystem is marked as requiring a consistency check.
12040 After the resize operation, the filesystem is always marked as
12042 requiring a consistency check (for safety). You have to boot into
12043 Windows to perform this check and clear this condition. If you
12044 don't set the "force" option then it is not possible to call
12045 "guestfs_ntfsresize" multiple times on a single filesystem without
12046 booting into Windows between each resize.
12047 See also ntfsresize(8).
12049 This function returns 0 on success or -1 on error.
12051 This function depends on the feature "ntfsprogs". See also
12053 "guestfs_feature_available".
12054 (Added in 1.3.2)
12056 guestfs_ntfsresize_opts_va
12058 int
12059 guestfs_ntfsresize_opts_va (guestfs_h *g,
12060 const char *device,
12061 va_list args);
12062 This is the "va_list variant" of "guestfs_ntfsresize_opts".
12064 See "CALLS WITH OPTIONAL ARGUMENTS".
12066 guestfs_ntfsresize_opts_argv
12068 int
12069 guestfs_ntfsresize_opts_argv (guestfs_h *g,
12070 const char *device,
12071 const struct guestfs_ntfsresize_opts_argv *optargs);
12072 This is the "argv variant" of "guestfs_ntfsresize_opts".
12074 See "CALLS WITH OPTIONAL ARGUMENTS".
12076 guestfs_ntfsresize_size
12078 int
12079 guestfs_ntfsresize_size (guestfs_h *g,
12080 const char *device,
12081 int64_t size);
12082 This function is deprecated. In new code, use the "guestfs_ntfsresize"
12084 call instead.
12085 Deprecated functions will not be removed from the API, but the fact
12087 that they are deprecated indicates that there are problems with correct
12088 use of these functions.
12089 This command is the same as "guestfs_ntfsresize" except that it allows
12091 you to specify the new size (in bytes) explicitly.
12092 This function returns 0 on success or -1 on error.
12094 This function depends on the feature "ntfsprogs". See also
12096 "guestfs_feature_available".
12097 (Added in 1.3.14)
12099 guestfs_parse_environment
12101 int
12102 guestfs_parse_environment (guestfs_h *g);
12103 Parse the program’s environment and set flags in the handle
12105 accordingly. For example if "LIBGUESTFS_DEBUG=1" then the ‘verbose’
12106 flag is set in the handle.
12107 Most programs do not need to call this. It is done implicitly when you
12109 call "guestfs_create".
12110 See "ENVIRONMENT VARIABLES" for a list of environment variables that
12112 can affect libguestfs handles. See also "guestfs_create_flags", and
12113 "guestfs_parse_environment_list".
12114 This function returns 0 on success or -1 on error.
12116 (Added in 1.19.53)
12118 guestfs_parse_environment_list
12120 int
12121 guestfs_parse_environment_list (guestfs_h *g,
12122 char *const *environment);
12123 Parse the list of strings in the argument "environment" and set flags
12125 in the handle accordingly. For example if "LIBGUESTFS_DEBUG=1" is a
12126 string in the list, then the ‘verbose’ flag is set in the handle.
12127 This is the same as "guestfs_parse_environment" except that it parses
12129 an explicit list of strings instead of the program's environment.
12130 This function returns 0 on success or -1 on error.
12132 (Added in 1.19.53)
12134 guestfs_part_add
12136 int
12137 guestfs_part_add (guestfs_h *g,
12138 const char *device,
12139 const char *prlogex,
12140 int64_t startsect,
12141 int64_t endsect);
12142 This command adds a partition to "device". If there is no partition
12144 table on the device, call "guestfs_part_init" first.
12145 The "prlogex" parameter is the type of partition. Normally you should
12147 pass "p" or "primary" here, but MBR partition tables also support "l"
12148 (or "logical") and "e" (or "extended") partition types.
12149 "startsect" and "endsect" are the start and end of the partition in
12151 sectors. "endsect" may be negative, which means it counts backwards
12152 from the end of the disk ("-1" is the last sector).
12153 Creating a partition which covers the whole disk is not so easy. Use
12155 "guestfs_part_disk" to do that.
12156 This function returns 0 on success or -1 on error.
12158 (Added in 1.0.78)
12160 guestfs_part_del
12162 int
12163 guestfs_part_del (guestfs_h *g,
12164 const char *device,
12165 int partnum);
12166 This command deletes the partition numbered "partnum" on "device".
12168 Note that in the case of MBR partitioning, deleting an extended
12170 partition also deletes any logical partitions it contains.
12171 This function returns 0 on success or -1 on error.
12173 (Added in 1.3.2)
12175 guestfs_part_disk
12177 int
12178 guestfs_part_disk (guestfs_h *g,
12179 const char *device,
12180 const char *parttype);
12181 This command is simply a combination of "guestfs_part_init" followed by
12183 "guestfs_part_add" to create a single primary partition covering the
12184 whole disk.
12185 "parttype" is the partition table type, usually "mbr" or "gpt", but
12187 other possible values are described in "guestfs_part_init".
12188 This function returns 0 on success or -1 on error.
12190 (Added in 1.0.78)
12192 guestfs_part_expand_gpt
12194 int
12195 guestfs_part_expand_gpt (guestfs_h *g,
12196 const char *device);
12197 Move backup GPT data structures to the end of the disk. This is useful
12199 in case of in-place image expand since disk space after backup GPT
12200 header is not usable. This is equivalent to "sgdisk -e".
12201 See also sgdisk(8).
12203 This function returns 0 on success or -1 on error.
12205 This function depends on the feature "gdisk". See also
12207 "guestfs_feature_available".
12208 (Added in 1.33.2)
12210 guestfs_part_get_bootable
12212 int
12213 guestfs_part_get_bootable (guestfs_h *g,
12214 const char *device,
12215 int partnum);
12216 This command returns true if the partition "partnum" on "device" has
12218 the bootable flag set.
12219 See also "guestfs_part_set_bootable".
12221 This function returns a C truth value on success or -1 on error.
12223 (Added in 1.3.2)
12225 guestfs_part_get_disk_guid
12227 char *
12228 guestfs_part_get_disk_guid (guestfs_h *g,
12229 const char *device);
12230 Return the disk identifier (GUID) of a GPT-partitioned "device".
12232 Behaviour is undefined for other partition types.
12233 This function returns a string, or NULL on error. The caller must free
12235 the returned string after use.
12236 This function depends on the feature "gdisk". See also
12238 "guestfs_feature_available".
12239 (Added in 1.33.2)
12241 guestfs_part_get_gpt_attributes
12243 int64_t
12244 guestfs_part_get_gpt_attributes (guestfs_h *g,
12245 const char *device,
12246 int partnum);
12247 Return the attribute flags of numbered GPT partition "partnum". An
12249 error is returned for MBR partitions.
12250 On error this function returns -1.
12252 This function depends on the feature "gdisk". See also
12254 "guestfs_feature_available".
12255 (Added in 1.21.1)
12257 guestfs_part_get_gpt_guid
12259 char *
12260 guestfs_part_get_gpt_guid (guestfs_h *g,
12261 const char *device,
12262 int partnum);
12263 Return the GUID of numbered GPT partition "partnum".
12265 This function returns a string, or NULL on error. The caller must free
12267 the returned string after use.
12268 This function depends on the feature "gdisk". See also
12270 "guestfs_feature_available".
12271 (Added in 1.29.25)
12273 guestfs_part_get_gpt_type
12275 char *
12276 guestfs_part_get_gpt_type (guestfs_h *g,
12277 const char *device,
12278 int partnum);
12279 Return the type GUID of numbered GPT partition "partnum". For MBR
12281 partitions, return an appropriate GUID corresponding to the MBR type.
12282 Behaviour is undefined for other partition types.
12283 This function returns a string, or NULL on error. The caller must free
12285 the returned string after use.
12286 This function depends on the feature "gdisk". See also
12288 "guestfs_feature_available".
12289 (Added in 1.21.1)
12291 guestfs_part_get_mbr_id
12293 int
12294 guestfs_part_get_mbr_id (guestfs_h *g,
12295 const char *device,
12296 int partnum);
12297 Returns the MBR type byte (also known as the ID byte) from the numbered
12299 partition "partnum".
12300 Note that only MBR (old DOS-style) partitions have type bytes. You
12302 will get undefined results for other partition table types (see
12303 "guestfs_part_get_parttype").
12304 On error this function returns -1.
12306 (Added in 1.3.2)
12308 guestfs_part_get_mbr_part_type
12310 char *
12311 guestfs_part_get_mbr_part_type (guestfs_h *g,
12312 const char *device,
12313 int partnum);
12314 This returns the partition type of an MBR partition numbered "partnum"
12316 on device "device".
12317 It returns "primary", "logical", or "extended".
12319 This function returns a string, or NULL on error. The caller must free
12321 the returned string after use.
12322 (Added in 1.29.32)
12324 guestfs_part_get_name
12326 char *
12327 guestfs_part_get_name (guestfs_h *g,
12328 const char *device,
12329 int partnum);
12330 This gets the partition name on partition numbered "partnum" on device
12332 "device". Note that partitions are numbered from 1.
12333 The partition name can only be read on certain types of partition
12335 table. This works on "gpt" but not on "mbr" partitions.
12336 This function returns a string, or NULL on error. The caller must free
12338 the returned string after use.
12339 (Added in 1.25.33)
12341 guestfs_part_get_parttype
12343 char *
12344 guestfs_part_get_parttype (guestfs_h *g,
12345 const char *device);
12346 This command examines the partition table on "device" and returns the
12348 partition table type (format) being used.
12349 Common return values include: "msdos" (a DOS/Windows style MBR
12351 partition table), "gpt" (a GPT/EFI-style partition table). Other
12352 values are possible, although unusual. See "guestfs_part_init" for a
12353 full list.
12354 This function returns a string, or NULL on error. The caller must free
12356 the returned string after use.
12357 (Added in 1.0.78)
12359 guestfs_part_init
12361 int
12362 guestfs_part_init (guestfs_h *g,
12363 const char *device,
12364 const char *parttype);
12365 This creates an empty partition table on "device" of one of the
12367 partition types listed below. Usually "parttype" should be either
12368 "msdos" or "gpt" (for large disks).
12369 Initially there are no partitions. Following this, you should call
12371 "guestfs_part_add" for each partition required.
12372 Possible values for "parttype" are:
12374 efi
12376 gpt Intel EFI / GPT partition table.
12377 This is recommended for >= 2 TB partitions that will be accessed
12379 from Linux and Intel-based Mac OS X. It also has limited backwards
12380 compatibility with the "mbr" format.
12381 mbr
12383 msdos
12384 The standard PC "Master Boot Record" (MBR) format used by MS-DOS
12385 and Windows. This partition type will only work for device sizes
12386 up to 2 TB. For large disks we recommend using "gpt".
12387 Other partition table types that may work but are not supported
12389 include:
12390 aix AIX disk labels.
12392 amiga
12394 rdb Amiga "Rigid Disk Block" format.
12395 bsd BSD disk labels.
12397 dasd
12399 DASD, used on IBM mainframes.
12400 dvh MIPS/SGI volumes.
12402 mac Old Mac partition format. Modern Macs use "gpt".
12404 pc98
12406 NEC PC-98 format, common in Japan apparently.
12407 sun Sun disk labels.
12409 This function returns 0 on success or -1 on error.
12411 (Added in 1.0.78)
12413 guestfs_part_list
12415 struct guestfs_partition_list *
12416 guestfs_part_list (guestfs_h *g,
12417 const char *device);
12418 This command parses the partition table on "device" and returns the
12420 list of partitions found.
12421 The fields in the returned structure are:
12423 part_num
12425 Partition number, counting from 1.
12426 part_start
12428 Start of the partition in bytes. To get sectors you have to divide
12429 by the device’s sector size, see "guestfs_blockdev_getss".
12430 part_end
12432 End of the partition in bytes.
12433 part_size
12435 Size of the partition in bytes.
12436 This function returns a "struct guestfs_partition_list *", or NULL if
12438 there was an error. The caller must call "guestfs_free_partition_list"
12439 after use.
12440 (Added in 1.0.78)
12442 guestfs_part_resize
12444 int
12445 guestfs_part_resize (guestfs_h *g,
12446 const char *device,
12447 int partnum,
12448 int64_t endsect);
12449 This command resizes the partition numbered "partnum" on "device" by
12451 moving the end position.
12452 Note that this does not modify any filesystem present in the partition.
12454 If you wish to do this, you will need to use filesystem resizing
12455 commands like "guestfs_resize2fs".
12456 When growing a partition you will want to grow the filesystem
12458 afterwards, but when shrinking, you need to shrink the filesystem
12459 before the partition.
12460 This function returns 0 on success or -1 on error.
12462 (Added in 1.37.20)
12464 guestfs_part_set_bootable
12466 int
12467 guestfs_part_set_bootable (guestfs_h *g,
12468 const char *device,
12469 int partnum,
12470 int bootable);
12471 This sets the bootable flag on partition numbered "partnum" on device
12473 "device". Note that partitions are numbered from 1.
12474 The bootable flag is used by some operating systems (notably Windows)
12476 to determine which partition to boot from. It is by no means
12477 universally recognized.
12478 This function returns 0 on success or -1 on error.
12480 (Added in 1.0.78)
12482 guestfs_part_set_disk_guid
12484 int
12485 guestfs_part_set_disk_guid (guestfs_h *g,
12486 const char *device,
12487 const char *guid);
12488 Set the disk identifier (GUID) of a GPT-partitioned "device" to "guid".
12490 Return an error if the partition table of "device" isn't GPT, or if
12491 "guid" is not a valid GUID.
12492 This function returns 0 on success or -1 on error.
12494 This function depends on the feature "gdisk". See also
12496 "guestfs_feature_available".
12497 (Added in 1.33.2)
12499 guestfs_part_set_disk_guid_random
12501 int
12502 guestfs_part_set_disk_guid_random (guestfs_h *g,
12503 const char *device);
12504 Set the disk identifier (GUID) of a GPT-partitioned "device" to a
12506 randomly generated value. Return an error if the partition table of
12507 "device" isn't GPT.
12508 This function returns 0 on success or -1 on error.
12510 This function depends on the feature "gdisk". See also
12512 "guestfs_feature_available".
12513 (Added in 1.33.2)
12515 guestfs_part_set_gpt_attributes
12517 int
12518 guestfs_part_set_gpt_attributes (guestfs_h *g,
12519 const char *device,
12520 int partnum,
12521 int64_t attributes);
12522 Set the attribute flags of numbered GPT partition "partnum" to
12524 "attributes". Return an error if the partition table of "device" isn't
12525 GPT.
12526 See
12528 https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries
12529 for a useful list of partition attributes.
12530 This function returns 0 on success or -1 on error.
12532 This function depends on the feature "gdisk". See also
12534 "guestfs_feature_available".
12535 (Added in 1.21.1)
12537 guestfs_part_set_gpt_guid
12539 int
12540 guestfs_part_set_gpt_guid (guestfs_h *g,
12541 const char *device,
12542 int partnum,
12543 const char *guid);
12544 Set the GUID of numbered GPT partition "partnum" to "guid". Return an
12546 error if the partition table of "device" isn't GPT, or if "guid" is not
12547 a valid GUID.
12548 This function returns 0 on success or -1 on error.
12550 This function depends on the feature "gdisk". See also
12552 "guestfs_feature_available".
12553 (Added in 1.29.25)
12555 guestfs_part_set_gpt_type
12557 int
12558 guestfs_part_set_gpt_type (guestfs_h *g,
12559 const char *device,
12560 int partnum,
12561 const char *guid);
12562 Set the type GUID of numbered GPT partition "partnum" to "guid". Return
12564 an error if the partition table of "device" isn't GPT, or if "guid" is
12565 not a valid GUID.
12566 See
12568 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
12569 for a useful list of type GUIDs.
12570 This function returns 0 on success or -1 on error.
12572 This function depends on the feature "gdisk". See also
12574 "guestfs_feature_available".
12575 (Added in 1.21.1)
12577 guestfs_part_set_mbr_id
12579 int
12580 guestfs_part_set_mbr_id (guestfs_h *g,
12581 const char *device,
12582 int partnum,
12583 int idbyte);
12584 Sets the MBR type byte (also known as the ID byte) of the numbered
12586 partition "partnum" to "idbyte". Note that the type bytes quoted in
12587 most documentation are in fact hexadecimal numbers, but usually
12588 documented without any leading "0x" which might be confusing.
12589 Note that only MBR (old DOS-style) partitions have type bytes. You
12591 will get undefined results for other partition table types (see
12592 "guestfs_part_get_parttype").
12593 This function returns 0 on success or -1 on error.
12595 (Added in 1.3.2)
12597 guestfs_part_set_name
12599 int
12600 guestfs_part_set_name (guestfs_h *g,
12601 const char *device,
12602 int partnum,
12603 const char *name);
12604 This sets the partition name on partition numbered "partnum" on device
12606 "device". Note that partitions are numbered from 1.
12607 The partition name can only be set on certain types of partition table.
12609 This works on "gpt" but not on "mbr" partitions.
12610 This function returns 0 on success or -1 on error.
12612 (Added in 1.0.78)
12614 guestfs_part_to_dev
12616 char *
12617 guestfs_part_to_dev (guestfs_h *g,
12618 const char *partition);
12619 This function takes a partition name (eg. "/dev/sdb1") and removes the
12621 partition number, returning the device name (eg. "/dev/sdb").
12622 The named partition must exist, for example as a string returned from
12624 "guestfs_list_partitions".
12625 See also "guestfs_part_to_partnum", "guestfs_device_index".
12627 This function returns a string, or NULL on error. The caller must free
12629 the returned string after use.
12630 (Added in 1.5.15)
12632 guestfs_part_to_partnum
12634 int
12635 guestfs_part_to_partnum (guestfs_h *g,
12636 const char *partition);
12637 This function takes a partition name (eg. "/dev/sdb1") and returns the
12639 partition number (eg. 1).
12640 The named partition must exist, for example as a string returned from
12642 "guestfs_list_partitions".
12643 See also "guestfs_part_to_dev".
12645 On error this function returns -1.
12647 (Added in 1.13.25)
12649 guestfs_ping_daemon
12651 int
12652 guestfs_ping_daemon (guestfs_h *g);
12653 This is a test probe into the guestfs daemon running inside the
12655 libguestfs appliance. Calling this function checks that the daemon
12656 responds to the ping message, without affecting the daemon or attached
12657 block device(s) in any other way.
12658 This function returns 0 on success or -1 on error.
12660 (Added in 1.0.18)
12662 guestfs_pread
12664 char *
12665 guestfs_pread (guestfs_h *g,
12666 const char *path,
12667 int count,
12668 int64_t offset,
12669 size_t *size_r);
12670 This command lets you read part of a file. It reads "count" bytes of
12672 the file, starting at "offset", from file "path".
12673 This may read fewer bytes than requested. For further details see the
12675 pread(2) system call.
12676 See also "guestfs_pwrite", "guestfs_pread_device".
12678 This function returns a buffer, or NULL on error. The size of the
12680 returned buffer is written to *size_r. The caller must free the
12681 returned buffer after use.
12682 Because of the message protocol, there is a transfer limit of somewhere
12684 between 2MB and 4MB. See "PROTOCOL LIMITS".
12685 (Added in 1.0.77)
12687 guestfs_pread_device
12689 char *
12690 guestfs_pread_device (guestfs_h *g,
12691 const char *device,
12692 int count,
12693 int64_t offset,
12694 size_t *size_r);
12695 This command lets you read part of a block device. It reads "count"
12697 bytes of "device", starting at "offset".
12698 This may read fewer bytes than requested. For further details see the
12700 pread(2) system call.
12701 See also "guestfs_pread".
12703 This function returns a buffer, or NULL on error. The size of the
12705 returned buffer is written to *size_r. The caller must free the
12706 returned buffer after use.
12707 Because of the message protocol, there is a transfer limit of somewhere
12709 between 2MB and 4MB. See "PROTOCOL LIMITS".
12710 (Added in 1.5.21)
12712 guestfs_pvchange_uuid
12714 int
12715 guestfs_pvchange_uuid (guestfs_h *g,
12716 const char *device);
12717 Generate a new random UUID for the physical volume "device".
12719 This function returns 0 on success or -1 on error.
12721 This function depends on the feature "lvm2". See also
12723 "guestfs_feature_available".
12724 (Added in 1.19.26)
12726 guestfs_pvchange_uuid_all
12728 int
12729 guestfs_pvchange_uuid_all (guestfs_h *g);
12730 Generate new random UUIDs for all physical volumes.
12732 This function returns 0 on success or -1 on error.
12734 This function depends on the feature "lvm2". See also
12736 "guestfs_feature_available".
12737 (Added in 1.19.26)
12739 guestfs_pvcreate
12741 int
12742 guestfs_pvcreate (guestfs_h *g,
12743 const char *device);
12744 This creates an LVM physical volume on the named "device", where
12746 "device" should usually be a partition name such as /dev/sda1.
12747 This function returns 0 on success or -1 on error.
12749 This function depends on the feature "lvm2". See also
12751 "guestfs_feature_available".
12752 (Added in 0.8)
12754 guestfs_pvremove
12756 int
12757 guestfs_pvremove (guestfs_h *g,
12758 const char *device);
12759 This wipes a physical volume "device" so that LVM will no longer
12761 recognise it.
12762 The implementation uses the "pvremove" command which refuses to wipe
12764 physical volumes that contain any volume groups, so you have to remove
12765 those first.
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.0.13)
12773 guestfs_pvresize
12775 int
12776 guestfs_pvresize (guestfs_h *g,
12777 const char *device);
12778 This resizes (expands or shrinks) an existing LVM physical volume to
12780 match the new size of the underlying device.
12781 This function returns 0 on success or -1 on error.
12783 This function depends on the feature "lvm2". See also
12785 "guestfs_feature_available".
12786 (Added in 1.0.26)
12788 guestfs_pvresize_size
12790 int
12791 guestfs_pvresize_size (guestfs_h *g,
12792 const char *device,
12793 int64_t size);
12794 This command is the same as "guestfs_pvresize" except that it allows
12796 you to specify the new size (in bytes) explicitly.
12797 This function returns 0 on success or -1 on error.
12799 This function depends on the feature "lvm2". See also
12801 "guestfs_feature_available".
12802 (Added in 1.3.14)
12804 guestfs_pvs
12806 char **
12807 guestfs_pvs (guestfs_h *g);
12808 List all the physical volumes detected. This is the equivalent of the
12810 pvs(8) command.
12811 This returns a list of just the device names that contain PVs (eg.
12813 /dev/sda2).
12814 See also "guestfs_pvs_full".
12816 This function returns a NULL-terminated array of strings (like
12818 environ(3)), or NULL if there was an error. The caller must free the
12819 strings and the array after use.
12820 This function depends on the feature "lvm2". See also
12822 "guestfs_feature_available".
12823 (Added in 0.4)
12825 guestfs_pvs_full
12827 struct guestfs_lvm_pv_list *
12828 guestfs_pvs_full (guestfs_h *g);
12829 List all the physical volumes detected. This is the equivalent of the
12831 pvs(8) command. The "full" version includes all fields.
12832 This function returns a "struct guestfs_lvm_pv_list *", or NULL if
12834 there was an error. The caller must call "guestfs_free_lvm_pv_list"
12835 after use.
12836 This function depends on the feature "lvm2". See also
12838 "guestfs_feature_available".
12839 (Added in 0.4)
12841 guestfs_pvuuid
12843 char *
12844 guestfs_pvuuid (guestfs_h *g,
12845 const char *device);
12846 This command returns the UUID of the LVM PV "device".
12848 This function returns a string, or NULL on error. The caller must free
12850 the returned string after use.
12851 (Added in 1.0.87)
12853 guestfs_pwrite
12855 int
12856 guestfs_pwrite (guestfs_h *g,
12857 const char *path,
12858 const char *content,
12859 size_t content_size,
12860 int64_t offset);
12861 This command writes to part of a file. It writes the data buffer
12863 "content" to the file "path" starting at offset "offset".
12864 This command implements the pwrite(2) system call, and like that system
12866 call it may not write the full data requested. The return value is the
12867 number of bytes that were actually written to the file. This could
12868 even be 0, although short writes are unlikely for regular files in
12869 ordinary circumstances.
12870 See also "guestfs_pread", "guestfs_pwrite_device".
12872 On error this function returns -1.
12874 Because of the message protocol, there is a transfer limit of somewhere
12876 between 2MB and 4MB. See "PROTOCOL LIMITS".
12877 (Added in 1.3.14)
12879 guestfs_pwrite_device
12881 int
12882 guestfs_pwrite_device (guestfs_h *g,
12883 const char *device,
12884 const char *content,
12885 size_t content_size,
12886 int64_t offset);
12887 This command writes to part of a device. It writes the data buffer
12889 "content" to "device" starting at offset "offset".
12890 This command implements the pwrite(2) system call, and like that system
12892 call it may not write the full data requested (although short writes to
12893 disk devices and partitions are probably impossible with standard Linux
12894 kernels).
12895 See also "guestfs_pwrite".
12897 On error this function returns -1.
12899 Because of the message protocol, there is a transfer limit of somewhere
12901 between 2MB and 4MB. See "PROTOCOL LIMITS".
12902 (Added in 1.5.20)
12904 guestfs_read_file
12906 char *
12907 guestfs_read_file (guestfs_h *g,
12908 const char *path,
12909 size_t *size_r);
12910 This calls returns the contents of the file "path" as a buffer.
12912 Unlike "guestfs_cat", this function can correctly handle files that
12914 contain embedded ASCII NUL characters.
12915 This function returns a buffer, or NULL on error. The size of the
12917 returned buffer is written to *size_r. The caller must free the
12918 returned buffer after use.
12919 (Added in 1.0.63)
12921 guestfs_read_lines
12923 char **
12924 guestfs_read_lines (guestfs_h *g,
12925 const char *path);
12926 Return the contents of the file named "path".
12928 The file contents are returned as a list of lines. Trailing "LF" and
12930 "CRLF" character sequences are not returned.
12931 Note that this function cannot correctly handle binary files
12933 (specifically, files containing "\0" character which is treated as end
12934 of string). For those you need to use the "guestfs_read_file" function
12935 and split the buffer into lines yourself.
12936 This function returns a NULL-terminated array of strings (like
12938 environ(3)), or NULL if there was an error. The caller must free the
12939 strings and the array after use.
12940 (Added in 0.7)
12942 guestfs_readdir
12944 struct guestfs_dirent_list *
12945 guestfs_readdir (guestfs_h *g,
12946 const char *dir);
12947 This returns the list of directory entries in directory "dir".
12949 All entries in the directory are returned, including "." and "..". The
12951 entries are not sorted, but returned in the same order as the
12952 underlying filesystem.
12953 Also this call returns basic file type information about each file.
12955 The "ftyp" field will contain one of the following characters:
12956 'b' Block special
12958 'c' Char special
12960 'd' Directory
12962 'f' FIFO (named pipe)
12964 'l' Symbolic link
12966 'r' Regular file
12968 's' Socket
12970 'u' Unknown file type
12972 '?' The readdir(3) call returned a "d_type" field with an unexpected
12974 value
12975 This function is primarily intended for use by programs. To get a
12977 simple list of names, use "guestfs_ls". To get a printable directory
12978 for human consumption, use "guestfs_ll".
12979 This function returns a "struct guestfs_dirent_list *", or NULL if
12981 there was an error. The caller must call "guestfs_free_dirent_list"
12982 after use.
12983 Because of the message protocol, there is a transfer limit of somewhere
12985 between 2MB and 4MB. See "PROTOCOL LIMITS".
12986 (Added in 1.0.55)
12988 guestfs_readlink
12990 char *
12991 guestfs_readlink (guestfs_h *g,
12992 const char *path);
12993 This command reads the target of a symbolic link.
12995 This function returns a string, or NULL on error. The caller must free
12997 the returned string after use.
12998 (Added in 1.0.66)
13000 guestfs_readlinklist
13002 char **
13003 guestfs_readlinklist (guestfs_h *g,
13004 const char *path,
13005 char *const *names);
13006 This call allows you to do a "readlink" operation on multiple files,
13008 where all files are in the directory "path". "names" is the list of
13009 files from this directory.
13010 On return you get a list of strings, with a one-to-one correspondence
13012 to the "names" list. Each string is the value of the symbolic link.
13013 If the readlink(2) operation fails on any name, then the corresponding
13015 result string is the empty string "". However the whole operation is
13016 completed even if there were readlink(2) errors, and so you can call
13017 this function with names where you don't know if they are symbolic
13018 links already (albeit slightly less efficient).
13019 This call is intended for programs that want to efficiently list a
13021 directory contents without making many round-trips.
13022 This function returns a NULL-terminated array of strings (like
13024 environ(3)), or NULL if there was an error. The caller must free the
13025 strings and the array after use.
13026 (Added in 1.0.77)
13028 guestfs_realpath
13030 char *
13031 guestfs_realpath (guestfs_h *g,
13032 const char *path);
13033 Return the canonicalized absolute pathname of "path". The returned
13035 path has no ".", ".." or symbolic link path elements.
13036 This function returns a string, or NULL on error. The caller must free
13038 the returned string after use.
13039 (Added in 1.0.66)
13041 guestfs_remount
13043 int
13044 guestfs_remount (guestfs_h *g,
13045 const char *mountpoint,
13046 ...);
13047 You may supply a list of optional arguments to this call. Use zero or
13049 more of the following pairs of parameters, and terminate the list with
13050 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13051 GUESTFS_REMOUNT_RW, int rw,
13053 This call allows you to change the "rw" (readonly/read-write) flag on
13055 an already mounted filesystem at "mountpoint", converting a readonly
13056 filesystem to be read-write, or vice-versa.
13057 Note that at the moment you must supply the "optional" "rw" parameter.
13059 In future we may allow other flags to be adjusted.
13060 This function returns 0 on success or -1 on error.
13062 (Added in 1.23.2)
13064 guestfs_remount_va
13066 int
13067 guestfs_remount_va (guestfs_h *g,
13068 const char *mountpoint,
13069 va_list args);
13070 This is the "va_list variant" of "guestfs_remount".
13072 See "CALLS WITH OPTIONAL ARGUMENTS".
13074 guestfs_remount_argv
13076 int
13077 guestfs_remount_argv (guestfs_h *g,
13078 const char *mountpoint,
13079 const struct guestfs_remount_argv *optargs);
13080 This is the "argv variant" of "guestfs_remount".
13082 See "CALLS WITH OPTIONAL ARGUMENTS".
13084 guestfs_remove_drive
13086 int
13087 guestfs_remove_drive (guestfs_h *g,
13088 const char *label);
13089 This function is conceptually the opposite of "guestfs_add_drive_opts".
13091 It removes the drive that was previously added with label "label".
13092 Note that in order to remove drives, you have to add them with labels
13094 (see the optional "label" argument to "guestfs_add_drive_opts"). If
13095 you didn't use a label, then they cannot be removed.
13096 You can call this function before or after launching the handle. If
13098 called after launch, if the backend supports it, we try to hot unplug
13099 the drive: see "HOTPLUGGING". The disk must not be in use (eg.
13100 mounted) when you do this. We try to detect if the disk is in use and
13101 stop you from doing this.
13102 This function returns 0 on success or -1 on error.
13104 (Added in 1.19.49)
13106 guestfs_removexattr
13108 int
13109 guestfs_removexattr (guestfs_h *g,
13110 const char *xattr,
13111 const char *path);
13112 This call removes the extended attribute named "xattr" of the file
13114 "path".
13115 See also: "guestfs_lremovexattr", attr(5).
13117 This function returns 0 on success or -1 on error.
13119 This function depends on the feature "linuxxattrs". See also
13121 "guestfs_feature_available".
13122 (Added in 1.0.59)
13124 guestfs_rename
13126 int
13127 guestfs_rename (guestfs_h *g,
13128 const char *oldpath,
13129 const char *newpath);
13130 Rename a file to a new place on the same filesystem. This is the same
13132 as the Linux rename(2) system call. In most cases you are better to
13133 use "guestfs_mv" instead.
13134 This function returns 0 on success or -1 on error.
13136 (Added in 1.21.5)
13138 guestfs_resize2fs
13140 int
13141 guestfs_resize2fs (guestfs_h *g,
13142 const char *device);
13143 This resizes an ext2, ext3 or ext4 filesystem to match the size of the
13145 underlying device.
13146 See also "RESIZE2FS ERRORS".
13148 This function returns 0 on success or -1 on error.
13150 (Added in 1.0.27)
13152 guestfs_resize2fs_M
13154 int
13155 guestfs_resize2fs_M (guestfs_h *g,
13156 const char *device);
13157 This command is the same as "guestfs_resize2fs", but the filesystem is
13159 resized to its minimum size. This works like the -M option to the
13160 "resize2fs" command.
13161 To get the resulting size of the filesystem you should call
13163 "guestfs_tune2fs_l" and read the "Block size" and "Block count" values.
13164 These two numbers, multiplied together, give the resulting size of the
13165 minimal filesystem in bytes.
13166 See also "RESIZE2FS ERRORS".
13168 This function returns 0 on success or -1 on error.
13170 (Added in 1.9.4)
13172 guestfs_resize2fs_size
13174 int
13175 guestfs_resize2fs_size (guestfs_h *g,
13176 const char *device,
13177 int64_t size);
13178 This command is the same as "guestfs_resize2fs" except that it allows
13180 you to specify the new size (in bytes) explicitly.
13181 See also "RESIZE2FS ERRORS".
13183 This function returns 0 on success or -1 on error.
13185 (Added in 1.3.14)
13187 guestfs_rm
13189 int
13190 guestfs_rm (guestfs_h *g,
13191 const char *path);
13192 Remove the single file "path".
13194 This function returns 0 on success or -1 on error.
13196 (Added in 0.8)
13198 guestfs_rm_f
13200 int
13201 guestfs_rm_f (guestfs_h *g,
13202 const char *path);
13203 Remove the file "path".
13205 If the file doesn't exist, that error is ignored. (Other errors, eg.
13207 I/O errors or bad paths, are not ignored)
13208 This call cannot remove directories. Use "guestfs_rmdir" to remove an
13210 empty directory, or "guestfs_rm_rf" to remove directories recursively.
13211 This function returns 0 on success or -1 on error.
13213 (Added in 1.19.42)
13215 guestfs_rm_rf
13217 int
13218 guestfs_rm_rf (guestfs_h *g,
13219 const char *path);
13220 Remove the file or directory "path", recursively removing the contents
13222 if its a directory. This is like the "rm -rf" shell command.
13223 This function returns 0 on success or -1 on error.
13225 (Added in 0.8)
13227 guestfs_rmdir
13229 int
13230 guestfs_rmdir (guestfs_h *g,
13231 const char *path);
13232 Remove the single directory "path".
13234 This function returns 0 on success or -1 on error.
13236 (Added in 0.8)
13238 guestfs_rmmountpoint
13240 int
13241 guestfs_rmmountpoint (guestfs_h *g,
13242 const char *exemptpath);
13243 This call removes a mountpoint that was previously created with
13245 "guestfs_mkmountpoint". See "guestfs_mkmountpoint" for full details.
13246 This function returns 0 on success or -1 on error.
13248 (Added in 1.0.62)
13250 guestfs_rsync
13252 int
13253 guestfs_rsync (guestfs_h *g,
13254 const char *src,
13255 const char *dest,
13256 ...);
13257 You may supply a list of optional arguments to this call. Use zero or
13259 more of the following pairs of parameters, and terminate the list with
13260 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13261 GUESTFS_RSYNC_ARCHIVE, int archive,
13263 GUESTFS_RSYNC_DELETEDEST, int deletedest,
13264 This call may be used to copy or synchronize two directories under the
13266 same libguestfs handle. This uses the rsync(1) program which uses a
13267 fast algorithm that avoids copying files unnecessarily.
13268 "src" and "dest" are the source and destination directories. Files are
13270 copied from "src" to "dest".
13271 The optional arguments are:
13273 "archive"
13275 Turns on archive mode. This is the same as passing the --archive
13276 flag to "rsync".
13277 "deletedest"
13279 Delete files at the destination that do not exist at the source.
13280 This function returns 0 on success or -1 on error.
13282 This function depends on the feature "rsync". See also
13284 "guestfs_feature_available".
13285 (Added in 1.19.29)
13287 guestfs_rsync_va
13289 int
13290 guestfs_rsync_va (guestfs_h *g,
13291 const char *src,
13292 const char *dest,
13293 va_list args);
13294 This is the "va_list variant" of "guestfs_rsync".
13296 See "CALLS WITH OPTIONAL ARGUMENTS".
13298 guestfs_rsync_argv
13300 int
13301 guestfs_rsync_argv (guestfs_h *g,
13302 const char *src,
13303 const char *dest,
13304 const struct guestfs_rsync_argv *optargs);
13305 This is the "argv variant" of "guestfs_rsync".
13307 See "CALLS WITH OPTIONAL ARGUMENTS".
13309 guestfs_rsync_in
13311 int
13312 guestfs_rsync_in (guestfs_h *g,
13313 const char *remote,
13314 const char *dest,
13315 ...);
13316 You may supply a list of optional arguments to this call. Use zero or
13318 more of the following pairs of parameters, and terminate the list with
13319 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13320 GUESTFS_RSYNC_IN_ARCHIVE, int archive,
13322 GUESTFS_RSYNC_IN_DELETEDEST, int deletedest,
13323 This call may be used to copy or synchronize the filesystem on the host
13325 or on a remote computer with the filesystem within libguestfs. This
13326 uses the rsync(1) program which uses a fast algorithm that avoids
13327 copying files unnecessarily.
13328 This call only works if the network is enabled. See
13330 "guestfs_set_network" or the --network option to various tools like
13331 guestfish(1).
13332 Files are copied from the remote server and directory specified by
13334 "remote" to the destination directory "dest".
13335 The format of the remote server string is defined by rsync(1). Note
13337 that there is no way to supply a password or passphrase so the target
13338 must be set up not to require one.
13339 The optional arguments are the same as those of "guestfs_rsync".
13341 This function returns 0 on success or -1 on error.
13343 This function depends on the feature "rsync". See also
13345 "guestfs_feature_available".
13346 (Added in 1.19.29)
13348 guestfs_rsync_in_va
13350 int
13351 guestfs_rsync_in_va (guestfs_h *g,
13352 const char *remote,
13353 const char *dest,
13354 va_list args);
13355 This is the "va_list variant" of "guestfs_rsync_in".
13357 See "CALLS WITH OPTIONAL ARGUMENTS".
13359 guestfs_rsync_in_argv
13361 int
13362 guestfs_rsync_in_argv (guestfs_h *g,
13363 const char *remote,
13364 const char *dest,
13365 const struct guestfs_rsync_in_argv *optargs);
13366 This is the "argv variant" of "guestfs_rsync_in".
13368 See "CALLS WITH OPTIONAL ARGUMENTS".
13370 guestfs_rsync_out
13372 int
13373 guestfs_rsync_out (guestfs_h *g,
13374 const char *src,
13375 const char *remote,
13376 ...);
13377 You may supply a list of optional arguments to this call. Use zero or
13379 more of the following pairs of parameters, and terminate the list with
13380 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13381 GUESTFS_RSYNC_OUT_ARCHIVE, int archive,
13383 GUESTFS_RSYNC_OUT_DELETEDEST, int deletedest,
13384 This call may be used to copy or synchronize the filesystem within
13386 libguestfs with a filesystem on the host or on a remote computer. This
13387 uses the rsync(1) program which uses a fast algorithm that avoids
13388 copying files unnecessarily.
13389 This call only works if the network is enabled. See
13391 "guestfs_set_network" or the --network option to various tools like
13392 guestfish(1).
13393 Files are copied from the source directory "src" to the remote server
13395 and directory specified by "remote".
13396 The format of the remote server string is defined by rsync(1). Note
13398 that there is no way to supply a password or passphrase so the target
13399 must be set up not to require one.
13400 The optional arguments are the same as those of "guestfs_rsync".
13402 Globbing does not happen on the "src" parameter. In programs which use
13404 the API directly you have to expand wildcards yourself (see
13405 "guestfs_glob_expand"). In guestfish you can use the "glob" command
13406 (see "glob" in guestfish(1)), for example:
13407 ><fs> glob rsync-out /* rsync://remote/
13409 This function returns 0 on success or -1 on error.
13411 This function depends on the feature "rsync". See also
13413 "guestfs_feature_available".
13414 (Added in 1.19.29)
13416 guestfs_rsync_out_va
13418 int
13419 guestfs_rsync_out_va (guestfs_h *g,
13420 const char *src,
13421 const char *remote,
13422 va_list args);
13423 This is the "va_list variant" of "guestfs_rsync_out".
13425 See "CALLS WITH OPTIONAL ARGUMENTS".
13427 guestfs_rsync_out_argv
13429 int
13430 guestfs_rsync_out_argv (guestfs_h *g,
13431 const char *src,
13432 const char *remote,
13433 const struct guestfs_rsync_out_argv *optargs);
13434 This is the "argv variant" of "guestfs_rsync_out".
13436 See "CALLS WITH OPTIONAL ARGUMENTS".
13438 guestfs_scrub_device
13440 int
13441 guestfs_scrub_device (guestfs_h *g,
13442 const char *device);
13443 This command writes patterns over "device" to make data retrieval more
13445 difficult.
13446 It is an interface to the scrub(1) program. See that manual page for
13448 more details.
13449 This function returns 0 on success or -1 on error.
13451 This function depends on the feature "scrub". See also
13453 "guestfs_feature_available".
13454 (Added in 1.0.52)
13456 guestfs_scrub_file
13458 int
13459 guestfs_scrub_file (guestfs_h *g,
13460 const char *file);
13461 This command writes patterns over a file to make data retrieval more
13463 difficult.
13464 The file is removed after scrubbing.
13466 It is an interface to the scrub(1) program. See that manual page for
13468 more details.
13469 This function returns 0 on success or -1 on error.
13471 This function depends on the feature "scrub". See also
13473 "guestfs_feature_available".
13474 (Added in 1.0.52)
13476 guestfs_scrub_freespace
13478 int
13479 guestfs_scrub_freespace (guestfs_h *g,
13480 const char *dir);
13481 This command creates the directory "dir" and then fills it with files
13483 until the filesystem is full, and scrubs the files as for
13484 "guestfs_scrub_file", and deletes them. The intention is to scrub any
13485 free space on the partition containing "dir".
13486 It is an interface to the scrub(1) program. See that manual page for
13488 more details.
13489 This function returns 0 on success or -1 on error.
13491 This function depends on the feature "scrub". See also
13493 "guestfs_feature_available".
13494 (Added in 1.0.52)
13496 guestfs_selinux_relabel
13498 int
13499 guestfs_selinux_relabel (guestfs_h *g,
13500 const char *specfile,
13501 const char *path,
13502 ...);
13503 You may supply a list of optional arguments to this call. Use zero or
13505 more of the following pairs of parameters, and terminate the list with
13506 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13507 GUESTFS_SELINUX_RELABEL_FORCE, int force,
13509 SELinux relabel parts of the filesystem.
13511 The "specfile" parameter controls the policy spec file used. You have
13513 to parse "/etc/selinux/config" to find the correct SELinux policy and
13514 then pass the spec file, usually: "/etc/selinux/" + selinuxtype +
13515 "/contexts/files/file_contexts".
13516 The required "path" parameter is the top level directory where
13518 relabelling starts. Normally you should pass "path" as "/" to relabel
13519 the whole guest filesystem.
13520 The optional "force" boolean controls whether the context is reset for
13522 customizable files, and also whether the user, role and range parts of
13523 the file context is changed.
13524 This function returns 0 on success or -1 on error.
13526 This function depends on the feature "selinuxrelabel". See also
13528 "guestfs_feature_available".
13529 (Added in 1.33.43)
13531 guestfs_selinux_relabel_va
13533 int
13534 guestfs_selinux_relabel_va (guestfs_h *g,
13535 const char *specfile,
13536 const char *path,
13537 va_list args);
13538 This is the "va_list variant" of "guestfs_selinux_relabel".
13540 See "CALLS WITH OPTIONAL ARGUMENTS".
13542 guestfs_selinux_relabel_argv
13544 int
13545 guestfs_selinux_relabel_argv (guestfs_h *g,
13546 const char *specfile,
13547 const char *path,
13548 const struct guestfs_selinux_relabel_argv *optargs);
13549 This is the "argv variant" of "guestfs_selinux_relabel".
13551 See "CALLS WITH OPTIONAL ARGUMENTS".
13553 guestfs_set_append
13555 int
13556 guestfs_set_append (guestfs_h *g,
13557 const char *append);
13558 This function is used to add additional options to the libguestfs
13560 appliance kernel command line.
13561 The default is "NULL" unless overridden by setting "LIBGUESTFS_APPEND"
13563 environment variable.
13564 Setting "append" to "NULL" means no additional options are passed
13566 (libguestfs always adds a few of its own).
13567 This function returns 0 on success or -1 on error.
13569 (Added in 1.0.26)
13571 guestfs_set_attach_method
13573 int
13574 guestfs_set_attach_method (guestfs_h *g,
13575 const char *backend);
13576 This function is deprecated. In new code, use the
13578 "guestfs_set_backend" call instead.
13579 Deprecated functions will not be removed from the API, but the fact
13581 that they are deprecated indicates that there are problems with correct
13582 use of these functions.
13583 Set the method that libguestfs uses to connect to the backend guestfsd
13585 daemon.
13586 See "BACKEND".
13588 This function returns 0 on success or -1 on error.
13590 (Added in 1.9.8)
13592 guestfs_set_autosync
13594 int
13595 guestfs_set_autosync (guestfs_h *g,
13596 int autosync);
13597 If "autosync" is true, this enables autosync. Libguestfs will make a
13599 best effort attempt to make filesystems consistent and synchronized
13600 when the handle is closed (also if the program exits without closing
13601 handles).
13602 This is enabled by default (since libguestfs 1.5.24, previously it was
13604 disabled by default).
13605 This function returns 0 on success or -1 on error.
13607 (Added in 0.3)
13609 guestfs_set_backend
13611 int
13612 guestfs_set_backend (guestfs_h *g,
13613 const char *backend);
13614 Set the method that libguestfs uses to connect to the backend guestfsd
13616 daemon.
13617 This handle property was previously called the "attach method".
13619 See "BACKEND".
13621 This function returns 0 on success or -1 on error.
13623 (Added in 1.21.26)
13625 guestfs_set_backend_setting
13627 int
13628 guestfs_set_backend_setting (guestfs_h *g,
13629 const char *name,
13630 const char *val);
13631 Append "name=value" to the backend settings string list. However if a
13633 string already exists matching "name" or beginning with "name=", then
13634 that setting is replaced.
13635 See "BACKEND", "BACKEND SETTINGS".
13637 This function returns 0 on success or -1 on error.
13639 (Added in 1.27.2)
13641 guestfs_set_backend_settings
13643 int
13644 guestfs_set_backend_settings (guestfs_h *g,
13645 char *const *settings);
13646 Set a list of zero or more settings which are passed through to the
13648 current backend. Each setting is a string which is interpreted in a
13649 backend-specific way, or ignored if not understood by the backend.
13650 The default value is an empty list, unless the environment variable
13652 "LIBGUESTFS_BACKEND_SETTINGS" was set when the handle was created.
13653 This environment variable contains a colon-separated list of settings.
13654 This call replaces all backend settings. If you want to replace a
13656 single backend setting, see "guestfs_set_backend_setting". If you want
13657 to clear a single backend setting, see "guestfs_clear_backend_setting".
13658 See "BACKEND", "BACKEND SETTINGS".
13660 This function returns 0 on success or -1 on error.
13662 (Added in 1.25.24)
13664 guestfs_set_cachedir
13666 int
13667 guestfs_set_cachedir (guestfs_h *g,
13668 const char *cachedir);
13669 Set the directory used by the handle to store the appliance cache, when
13671 using a supermin appliance. The appliance is cached and shared between
13672 all handles which have the same effective user ID.
13673 The environment variables "LIBGUESTFS_CACHEDIR" and "TMPDIR" control
13675 the default value: If "LIBGUESTFS_CACHEDIR" is set, then that is the
13676 default. Else if "TMPDIR" is set, then that is the default. Else
13677 /var/tmp is the default.
13678 This function returns 0 on success or -1 on error.
13680 (Added in 1.19.58)
13682 guestfs_set_direct
13684 int
13685 guestfs_set_direct (guestfs_h *g,
13686 int direct);
13687 This function is deprecated. In new code, use the
13689 "guestfs_internal_get_console_socket" call instead.
13690 Deprecated functions will not be removed from the API, but the fact
13692 that they are deprecated indicates that there are problems with correct
13693 use of these functions.
13694 If the direct appliance mode flag is enabled, then stdin and stdout are
13696 passed directly through to the appliance once it is launched.
13697 One consequence of this is that log messages aren't caught by the
13699 library and handled by "guestfs_set_log_message_callback", but go
13700 straight to stdout.
13701 You probably don't want to use this unless you know what you are doing.
13703 The default is disabled.
13705 This function returns 0 on success or -1 on error.
13707 (Added in 1.0.72)
13709 guestfs_set_e2attrs
13711 int
13712 guestfs_set_e2attrs (guestfs_h *g,
13713 const char *file,
13714 const char *attrs,
13715 ...);
13716 You may supply a list of optional arguments to this call. Use zero or
13718 more of the following pairs of parameters, and terminate the list with
13719 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
13720 GUESTFS_SET_E2ATTRS_CLEAR, int clear,
13722 This sets or clears the file attributes "attrs" associated with the
13724 inode file.
13725 "attrs" is a string of characters representing file attributes. See
13727 "guestfs_get_e2attrs" for a list of possible attributes. Not all
13728 attributes can be changed.
13729 If optional boolean "clear" is not present or false, then the "attrs"
13731 listed are set in the inode.
13732 If "clear" is true, then the "attrs" listed are cleared in the inode.
13734 In both cases, other attributes not present in the "attrs" string are
13736 left unchanged.
13737 These attributes are only present when the file is located on an
13739 ext2/3/4 filesystem. Using this call on other filesystem types will
13740 result in an error.
13741 This function returns 0 on success or -1 on error.
13743 (Added in 1.17.31)
13745 guestfs_set_e2attrs_va
13747 int
13748 guestfs_set_e2attrs_va (guestfs_h *g,
13749 const char *file,
13750 const char *attrs,
13751 va_list args);
13752 This is the "va_list variant" of "guestfs_set_e2attrs".
13754 See "CALLS WITH OPTIONAL ARGUMENTS".
13756 guestfs_set_e2attrs_argv
13758 int
13759 guestfs_set_e2attrs_argv (guestfs_h *g,
13760 const char *file,
13761 const char *attrs,
13762 const struct guestfs_set_e2attrs_argv *optargs);
13763 This is the "argv variant" of "guestfs_set_e2attrs".
13765 See "CALLS WITH OPTIONAL ARGUMENTS".
13767 guestfs_set_e2generation
13769 int
13770 guestfs_set_e2generation (guestfs_h *g,
13771 const char *file,
13772 int64_t generation);
13773 This sets the ext2 file generation of a file.
13775 See "guestfs_get_e2generation".
13777 This function returns 0 on success or -1 on error.
13779 (Added in 1.17.31)
13781 guestfs_set_e2label
13783 int
13784 guestfs_set_e2label (guestfs_h *g,
13785 const char *device,
13786 const char *label);
13787 This function is deprecated. In new code, use the "guestfs_set_label"
13789 call instead.
13790 Deprecated functions will not be removed from the API, but the fact
13792 that they are deprecated indicates that there are problems with correct
13793 use of these functions.
13794 This sets the ext2/3/4 filesystem label of the filesystem on "device"
13796 to "label". Filesystem labels are limited to 16 characters.
13797 You can use either "guestfs_tune2fs_l" or "guestfs_get_e2label" to
13799 return the existing label on a filesystem.
13800 This function returns 0 on success or -1 on error.
13802 (Added in 1.0.15)
13804 guestfs_set_e2uuid
13806 int
13807 guestfs_set_e2uuid (guestfs_h *g,
13808 const char *device,
13809 const char *uuid);
13810 This function is deprecated. In new code, use the "guestfs_set_uuid"
13812 call instead.
13813 Deprecated functions will not be removed from the API, but the fact
13815 that they are deprecated indicates that there are problems with correct
13816 use of these functions.
13817 This sets the ext2/3/4 filesystem UUID of the filesystem on "device" to
13819 "uuid". The format of the UUID and alternatives such as "clear",
13820 "random" and "time" are described in the tune2fs(8) manpage.
13821 You can use "guestfs_vfs_uuid" to return the existing UUID of a
13823 filesystem.
13824 This function returns 0 on success or -1 on error.
13826 (Added in 1.0.15)
13828 guestfs_set_hv
13830 int
13831 guestfs_set_hv (guestfs_h *g,
13832 const char *hv);
13833 Set the hypervisor binary that we will use. The hypervisor depends on
13835 the backend, but is usually the location of the qemu/KVM hypervisor.
13836 For the uml backend, it is the location of the "linux" or "vmlinux"
13837 binary.
13838 The default is chosen when the library was compiled by the configure
13840 script.
13841 You can also override this by setting the "LIBGUESTFS_HV" environment
13843 variable.
13844 Note that you should call this function as early as possible after
13846 creating the handle. This is because some pre-launch operations depend
13847 on testing qemu features (by running "qemu -help"). If the qemu binary
13848 changes, we don't retest features, and so you might see inconsistent
13849 results. Using the environment variable "LIBGUESTFS_HV" is safest of
13850 all since that picks the qemu binary at the same time as the handle is
13851 created.
13852 This function returns 0 on success or -1 on error.
13854 (Added in 1.23.17)
13856 guestfs_set_identifier
13858 int
13859 guestfs_set_identifier (guestfs_h *g,
13860 const char *identifier);
13861 This is an informative string which the caller may optionally set in
13863 the handle. It is printed in various places, allowing the current
13864 handle to be identified in debugging output.
13865 One important place is when tracing is enabled. If the identifier
13867 string is not an empty string, then trace messages change from this:
13868 libguestfs: trace: get_tmpdir
13870 libguestfs: trace: get_tmpdir = "/tmp"
13871 to this:
13873 libguestfs: trace: ID: get_tmpdir
13875 libguestfs: trace: ID: get_tmpdir = "/tmp"
13876 where "ID" is the identifier string set by this call.
13878 The identifier must only contain alphanumeric ASCII characters,
13880 underscore and minus sign. The default is the empty string.
13881 See also "guestfs_set_program", "guestfs_set_trace",
13883 "guestfs_get_identifier".
13884 This function returns 0 on success or -1 on error.
13886 (Added in 1.31.14)
13888 guestfs_set_label
13890 int
13891 guestfs_set_label (guestfs_h *g,
13892 const char *mountable,
13893 const char *label);
13894 Set the filesystem label on "mountable" to "label".
13896 Only some filesystem types support labels, and libguestfs supports
13898 setting labels on only a subset of these.
13899 ext2, ext3, ext4
13901 Labels are limited to 16 bytes.
13902 NTFS
13904 Labels are limited to 128 unicode characters.
13905 XFS The label is limited to 12 bytes. The filesystem must not be
13907 mounted when trying to set the label.
13908 btrfs
13910 The label is limited to 255 bytes and some characters are not
13911 allowed. Setting the label on a btrfs subvolume will set the label
13912 on its parent filesystem. The filesystem must not be mounted when
13913 trying to set the label.
13914 fat The label is limited to 11 bytes.
13916 swap
13918 The label is limited to 16 bytes.
13919 If there is no support for changing the label for the type of the
13921 specified filesystem, set_label will fail and set errno as ENOTSUP.
13922 To read the label on a filesystem, call "guestfs_vfs_label".
13924 This function returns 0 on success or -1 on error.
13926 (Added in 1.17.9)
13928 guestfs_set_libvirt_requested_credential
13930 int
13931 guestfs_set_libvirt_requested_credential (guestfs_h *g,
13932 int index,
13933 const char *cred,
13934 size_t cred_size);
13935 After requesting the "index"'th credential from the user, call this
13937 function to pass the answer back to libvirt.
13938 See "LIBVIRT AUTHENTICATION" for documentation and example code.
13940 This function returns 0 on success or -1 on error.
13942 (Added in 1.19.52)
13944 guestfs_set_libvirt_supported_credentials
13946 int
13947 guestfs_set_libvirt_supported_credentials (guestfs_h *g,
13948 char *const *creds);
13949 Call this function before setting an event handler for
13951 "GUESTFS_EVENT_LIBVIRT_AUTH", to supply the list of credential types
13952 that the program knows how to process.
13953 The "creds" list must be a non-empty list of strings. Possible strings
13955 are:
13956 "username"
13958 "authname"
13959 "language"
13960 "cnonce"
13961 "passphrase"
13962 "echoprompt"
13963 "noechoprompt"
13964 "realm"
13965 "external"
13966 See libvirt documentation for the meaning of these credential types.
13968 See "LIBVIRT AUTHENTICATION" for documentation and example code.
13970 This function returns 0 on success or -1 on error.
13972 (Added in 1.19.52)
13974 guestfs_set_memsize
13976 int
13977 guestfs_set_memsize (guestfs_h *g,
13978 int memsize);
13979 This sets the memory size in megabytes allocated to the hypervisor.
13981 This only has any effect if called before "guestfs_launch".
13982 You can also change this by setting the environment variable
13984 "LIBGUESTFS_MEMSIZE" before the handle is created.
13985 For more information on the architecture of libguestfs, see guestfs(3).
13987 This function returns 0 on success or -1 on error.
13989 (Added in 1.0.55)
13991 guestfs_set_network
13993 int
13994 guestfs_set_network (guestfs_h *g,
13995 int network);
13996 If "network" is true, then the network is enabled in the libguestfs
13998 appliance. The default is false.
13999 This affects whether commands are able to access the network (see
14001 "RUNNING COMMANDS").
14002 You must call this before calling "guestfs_launch", otherwise it has no
14004 effect.
14005 This function returns 0 on success or -1 on error.
14007 (Added in 1.5.4)
14009 guestfs_set_path
14011 int
14012 guestfs_set_path (guestfs_h *g,
14013 const char *searchpath);
14014 Set the path that libguestfs searches for kernel and initrd.img.
14016 The default is "$libdir/guestfs" unless overridden by setting
14018 "LIBGUESTFS_PATH" environment variable.
14019 Setting "path" to "NULL" restores the default path.
14021 This function returns 0 on success or -1 on error.
14023 (Added in 0.3)
14025 guestfs_set_pgroup
14027 int
14028 guestfs_set_pgroup (guestfs_h *g,
14029 int pgroup);
14030 If "pgroup" is true, child processes are placed into their own process
14032 group.
14033 The practical upshot of this is that signals like "SIGINT" (from users
14035 pressing "^C") won't be received by the child process.
14036 The default for this flag is false, because usually you want "^C" to
14038 kill the subprocess. Guestfish sets this flag to true when used
14039 interactively, so that "^C" can cancel long-running commands gracefully
14040 (see "guestfs_user_cancel").
14041 This function returns 0 on success or -1 on error.
14043 (Added in 1.11.18)
14045 guestfs_set_program
14047 int
14048 guestfs_set_program (guestfs_h *g,
14049 const char *program);
14050 Set the program name. This is an informative string which the main
14052 program may optionally set in the handle.
14053 When the handle is created, the program name in the handle is set to
14055 the basename from "argv[0]". The program name can never be "NULL".
14056 This function returns 0 on success or -1 on error.
14058 (Added in 1.21.29)
14060 guestfs_set_qemu
14062 int
14063 guestfs_set_qemu (guestfs_h *g,
14064 const char *hv);
14065 This function is deprecated. In new code, use the "guestfs_set_hv"
14067 call instead.
14068 Deprecated functions will not be removed from the API, but the fact
14070 that they are deprecated indicates that there are problems with correct
14071 use of these functions.
14072 Set the hypervisor binary (usually qemu) that we will use.
14074 The default is chosen when the library was compiled by the configure
14076 script.
14077 You can also override this by setting the "LIBGUESTFS_HV" environment
14079 variable.
14080 Setting "hv" to "NULL" restores the default qemu binary.
14082 Note that you should call this function as early as possible after
14084 creating the handle. This is because some pre-launch operations depend
14085 on testing qemu features (by running "qemu -help"). If the qemu binary
14086 changes, we don't retest features, and so you might see inconsistent
14087 results. Using the environment variable "LIBGUESTFS_HV" is safest of
14088 all since that picks the qemu binary at the same time as the handle is
14089 created.
14090 This function returns 0 on success or -1 on error.
14092 (Added in 1.0.6)
14094 guestfs_set_recovery_proc
14096 int
14097 guestfs_set_recovery_proc (guestfs_h *g,
14098 int recoveryproc);
14099 If this is called with the parameter "false" then "guestfs_launch" does
14101 not create a recovery process. The purpose of the recovery process is
14102 to stop runaway hypervisor processes in the case where the main program
14103 aborts abruptly.
14104 This only has any effect if called before "guestfs_launch", and the
14106 default is true.
14107 About the only time when you would want to disable this is if the main
14109 process will fork itself into the background ("daemonize" itself). In
14110 this case the recovery process thinks that the main program has
14111 disappeared and so kills the hypervisor, which is not very helpful.
14112 This function returns 0 on success or -1 on error.
14114 (Added in 1.0.77)
14116 guestfs_set_selinux
14118 int
14119 guestfs_set_selinux (guestfs_h *g,
14120 int selinux);
14121 This function is deprecated. In new code, use the
14123 "guestfs_selinux_relabel" call instead.
14124 Deprecated functions will not be removed from the API, but the fact
14126 that they are deprecated indicates that there are problems with correct
14127 use of these functions.
14128 This sets the selinux flag that is passed to the appliance at boot
14130 time. The default is "selinux=0" (disabled).
14131 Note that if SELinux is enabled, it is always in Permissive mode
14133 ("enforcing=0").
14134 For more information on the architecture of libguestfs, see guestfs(3).
14136 This function returns 0 on success or -1 on error.
14138 (Added in 1.0.67)
14140 guestfs_set_smp
14142 int
14143 guestfs_set_smp (guestfs_h *g,
14144 int smp);
14145 Change the number of virtual CPUs assigned to the appliance. The
14147 default is 1. Increasing this may improve performance, though often it
14148 has no effect.
14149 This function must be called before "guestfs_launch".
14151 This function returns 0 on success or -1 on error.
14153 (Added in 1.13.15)
14155 guestfs_set_tmpdir
14157 int
14158 guestfs_set_tmpdir (guestfs_h *g,
14159 const char *tmpdir);
14160 Set the directory used by the handle to store temporary files.
14162 The environment variables "LIBGUESTFS_TMPDIR" and "TMPDIR" control the
14164 default value: If "LIBGUESTFS_TMPDIR" is set, then that is the default.
14165 Else if "TMPDIR" is set, then that is the default. Else /tmp is the
14166 default.
14167 This function returns 0 on success or -1 on error.
14169 (Added in 1.19.58)
14171 guestfs_set_trace
14173 int
14174 guestfs_set_trace (guestfs_h *g,
14175 int trace);
14176 If the command trace flag is set to 1, then libguestfs calls,
14178 parameters and return values are traced.
14179 If you want to trace C API calls into libguestfs (and other libraries)
14181 then possibly a better way is to use the external ltrace(1) command.
14182 Command traces are disabled unless the environment variable
14184 "LIBGUESTFS_TRACE" is defined and set to 1.
14185 Trace messages are normally sent to "stderr", unless you register a
14187 callback to send them somewhere else (see
14188 "guestfs_set_event_callback").
14189 This function returns 0 on success or -1 on error.
14191 (Added in 1.0.69)
14193 guestfs_set_uuid
14195 int
14196 guestfs_set_uuid (guestfs_h *g,
14197 const char *device,
14198 const char *uuid);
14199 Set the filesystem UUID on "device" to "uuid". If this fails and the
14201 errno is ENOTSUP, means that there is no support for changing the UUID
14202 for the type of the specified filesystem.
14203 Only some filesystem types support setting UUIDs.
14205 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14207 This function returns 0 on success or -1 on error.
14209 (Added in 1.23.10)
14211 guestfs_set_uuid_random
14213 int
14214 guestfs_set_uuid_random (guestfs_h *g,
14215 const char *device);
14216 Set the filesystem UUID on "device" to a random UUID. If this fails
14218 and the errno is ENOTSUP, means that there is no support for changing
14219 the UUID for the type of the specified filesystem.
14220 Only some filesystem types support setting UUIDs.
14222 To read the UUID on a filesystem, call "guestfs_vfs_uuid".
14224 This function returns 0 on success or -1 on error.
14226 (Added in 1.29.50)
14228 guestfs_set_verbose
14230 int
14231 guestfs_set_verbose (guestfs_h *g,
14232 int verbose);
14233 If "verbose" is true, this turns on verbose messages.
14235 Verbose messages are disabled unless the environment variable
14237 "LIBGUESTFS_DEBUG" is defined and set to 1.
14238 Verbose messages are normally sent to "stderr", unless you register a
14240 callback to send them somewhere else (see
14241 "guestfs_set_event_callback").
14242 This function returns 0 on success or -1 on error.
14244 (Added in 0.3)
14246 guestfs_setcon
14248 int
14249 guestfs_setcon (guestfs_h *g,
14250 const char *context);
14251 This function is deprecated. In new code, use the
14253 "guestfs_selinux_relabel" call instead.
14254 Deprecated functions will not be removed from the API, but the fact
14256 that they are deprecated indicates that there are problems with correct
14257 use of these functions.
14258 This sets the SELinux security context of the daemon to the string
14260 "context".
14261 See the documentation about SELINUX in guestfs(3).
14263 This function returns 0 on success or -1 on error.
14265 This function depends on the feature "selinux". See also
14267 "guestfs_feature_available".
14268 (Added in 1.0.67)
14270 guestfs_setxattr
14272 int
14273 guestfs_setxattr (guestfs_h *g,
14274 const char *xattr,
14275 const char *val,
14276 int vallen,
14277 const char *path);
14278 This call sets the extended attribute named "xattr" of the file "path"
14280 to the value "val" (of length "vallen"). The value is arbitrary 8 bit
14281 data.
14282 See also: "guestfs_lsetxattr", attr(5).
14284 This function returns 0 on success or -1 on error.
14286 This function depends on the feature "linuxxattrs". See also
14288 "guestfs_feature_available".
14289 (Added in 1.0.59)
14291 guestfs_sfdisk
14293 int
14294 guestfs_sfdisk (guestfs_h *g,
14295 const char *device,
14296 int cyls,
14297 int heads,
14298 int sectors,
14299 char *const *lines);
14300 This function is deprecated. In new code, use the "guestfs_part_add"
14302 call instead.
14303 Deprecated functions will not be removed from the API, but the fact
14305 that they are deprecated indicates that there are problems with correct
14306 use of these functions.
14307 This is a direct interface to the sfdisk(8) program for creating
14309 partitions on block devices.
14310 "device" should be a block device, for example /dev/sda.
14312 "cyls", "heads" and "sectors" are the number of cylinders, heads and
14314 sectors on the device, which are passed directly to sfdisk as the -C,
14315 -H and -S parameters. If you pass 0 for any of these, then the
14316 corresponding parameter is omitted. Usually for ‘large’ disks, you can
14317 just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or
14318 rather, the kernel) cannot work out the right geometry and you will
14319 need to tell it.
14320 "lines" is a list of lines that we feed to "sfdisk". For more
14322 information refer to the sfdisk(8) manpage.
14323 To create a single partition occupying the whole disk, you would pass
14325 "lines" as a single element list, when the single element being the
14326 string "," (comma).
14327 See also: "guestfs_sfdisk_l", "guestfs_sfdisk_N", "guestfs_part_init"
14329 This function returns 0 on success or -1 on error.
14331 (Added in 0.8)
14333 guestfs_sfdiskM
14335 int
14336 guestfs_sfdiskM (guestfs_h *g,
14337 const char *device,
14338 char *const *lines);
14339 This function is deprecated. In new code, use the "guestfs_part_add"
14341 call instead.
14342 Deprecated functions will not be removed from the API, but the fact
14344 that they are deprecated indicates that there are problems with correct
14345 use of these functions.
14346 This is a simplified interface to the "guestfs_sfdisk" command, where
14348 partition sizes are specified in megabytes only (rounded to the nearest
14349 cylinder) and you don't need to specify the cyls, heads and sectors
14350 parameters which were rarely if ever used anyway.
14351 See also: "guestfs_sfdisk", the sfdisk(8) manpage and
14353 "guestfs_part_disk"
14354 This function returns 0 on success or -1 on error.
14356 (Added in 1.0.55)
14358 guestfs_sfdisk_N
14360 int
14361 guestfs_sfdisk_N (guestfs_h *g,
14362 const char *device,
14363 int partnum,
14364 int cyls,
14365 int heads,
14366 int sectors,
14367 const char *line);
14368 This function is deprecated. In new code, use the "guestfs_part_add"
14370 call instead.
14371 Deprecated functions will not be removed from the API, but the fact
14373 that they are deprecated indicates that there are problems with correct
14374 use of these functions.
14375 This runs sfdisk(8) option to modify just the single partition "n"
14377 (note: "n" counts from 1).
14378 For other parameters, see "guestfs_sfdisk". You should usually pass 0
14380 for the cyls/heads/sectors parameters.
14381 See also: "guestfs_part_add"
14383 This function returns 0 on success or -1 on error.
14385 (Added in 1.0.26)
14387 guestfs_sfdisk_disk_geometry
14389 char *
14390 guestfs_sfdisk_disk_geometry (guestfs_h *g,
14391 const char *device);
14392 This displays the disk geometry of "device" read from the partition
14394 table. Especially in the case where the underlying block device has
14395 been resized, this can be different from the kernel’s idea of the
14396 geometry (see "guestfs_sfdisk_kernel_geometry").
14397 The result is in human-readable format, and not designed to be parsed.
14399 This function returns a string, or NULL on error. The caller must free
14401 the returned string after use.
14402 (Added in 1.0.26)
14404 guestfs_sfdisk_kernel_geometry
14406 char *
14407 guestfs_sfdisk_kernel_geometry (guestfs_h *g,
14408 const char *device);
14409 This displays the kernel’s idea of the geometry of "device".
14411 The result is in human-readable format, and not designed to be parsed.
14413 This function returns a string, or NULL on error. The caller must free
14415 the returned string after use.
14416 (Added in 1.0.26)
14418 guestfs_sfdisk_l
14420 char *
14421 guestfs_sfdisk_l (guestfs_h *g,
14422 const char *device);
14423 This function is deprecated. In new code, use the "guestfs_part_list"
14425 call instead.
14426 Deprecated functions will not be removed from the API, but the fact
14428 that they are deprecated indicates that there are problems with correct
14429 use of these functions.
14430 This displays the partition table on "device", in the human-readable
14432 output of the sfdisk(8) command. It is not intended to be parsed.
14433 See also: "guestfs_part_list"
14435 This function returns a string, or NULL on error. The caller must free
14437 the returned string after use.
14438 (Added in 1.0.26)
14440 guestfs_sh
14442 char *
14443 guestfs_sh (guestfs_h *g,
14444 const char *command);
14445 This call runs a command from the guest filesystem via the guest’s
14447 /bin/sh.
14448 This is like "guestfs_command", but passes the command to:
14450 /bin/sh -c "command"
14452 Depending on the guest’s shell, this usually results in wildcards being
14454 expanded, shell expressions being interpolated and so on.
14455 All the provisos about "guestfs_command" apply to this call.
14457 This function returns a string, or NULL on error. The caller must free
14459 the returned string after use.
14460 (Added in 1.0.50)
14462 guestfs_sh_lines
14464 char **
14465 guestfs_sh_lines (guestfs_h *g,
14466 const char *command);
14467 This is the same as "guestfs_sh", but splits the result into a list of
14469 lines.
14470 See also: "guestfs_command_lines"
14472 This function returns a NULL-terminated array of strings (like
14474 environ(3)), or NULL if there was an error. The caller must free the
14475 strings and the array after use.
14476 (Added in 1.0.50)
14478 guestfs_shutdown
14480 int
14481 guestfs_shutdown (guestfs_h *g);
14482 This is the opposite of "guestfs_launch". It performs an orderly
14484 shutdown of the backend process(es). If the autosync flag is set
14485 (which is the default) then the disk image is synchronized.
14486 If the subprocess exits with an error then this function will return an
14488 error, which should not be ignored (it may indicate that the disk image
14489 could not be written out properly).
14490 It is safe to call this multiple times. Extra calls are ignored.
14492 This call does not close or free up the handle. You still need to call
14494 "guestfs_close" afterwards.
14495 "guestfs_close" will call this if you don't do it explicitly, but note
14497 that any errors are ignored in that case.
14498 This function returns 0 on success or -1 on error.
14500 (Added in 1.19.16)
14502 guestfs_sleep
14504 int
14505 guestfs_sleep (guestfs_h *g,
14506 int secs);
14507 Sleep for "secs" seconds.
14509 This function returns 0 on success or -1 on error.
14511 (Added in 1.0.41)
14513 guestfs_stat
14515 struct guestfs_stat *
14516 guestfs_stat (guestfs_h *g,
14517 const char *path);
14518 This function is deprecated. In new code, use the "guestfs_statns"
14520 call instead.
14521 Deprecated functions will not be removed from the API, but the fact
14523 that they are deprecated indicates that there are problems with correct
14524 use of these functions.
14525 Returns file information for the given "path".
14527 This is the same as the stat(2) system call.
14529 This function returns a "struct guestfs_stat *", or NULL if there was
14531 an error. The caller must call "guestfs_free_stat" after use.
14532 (Added in 1.9.2)
14534 guestfs_statns
14536 struct guestfs_statns *
14537 guestfs_statns (guestfs_h *g,
14538 const char *path);
14539 Returns file information for the given "path".
14541 This is the same as the stat(2) system call.
14543 This function returns a "struct guestfs_statns *", or NULL if there was
14545 an error. The caller must call "guestfs_free_statns" after use.
14546 (Added in 1.27.53)
14548 guestfs_statvfs
14550 struct guestfs_statvfs *
14551 guestfs_statvfs (guestfs_h *g,
14552 const char *path);
14553 Returns file system statistics for any mounted file system. "path"
14555 should be a file or directory in the mounted file system (typically it
14556 is the mount point itself, but it doesn't need to be).
14557 This is the same as the statvfs(2) system call.
14559 This function returns a "struct guestfs_statvfs *", or NULL if there
14561 was an error. The caller must call "guestfs_free_statvfs" after use.
14562 (Added in 1.9.2)
14564 guestfs_strings
14566 char **
14567 guestfs_strings (guestfs_h *g,
14568 const char *path);
14569 This runs the strings(1) command on a file and returns the list of
14571 printable strings found.
14572 The "strings" command has, in the past, had problems with parsing
14574 untrusted files. These are mitigated in the current version of
14575 libguestfs, but see "CVE-2014-8484".
14576 This function returns a NULL-terminated array of strings (like
14578 environ(3)), or NULL if there was an error. The caller must free the
14579 strings and the array after use.
14580 Because of the message protocol, there is a transfer limit of somewhere
14582 between 2MB and 4MB. See "PROTOCOL LIMITS".
14583 (Added in 1.0.22)
14585 guestfs_strings_e
14587 char **
14588 guestfs_strings_e (guestfs_h *g,
14589 const char *encoding,
14590 const char *path);
14591 This is like the "guestfs_strings" command, but allows you to specify
14593 the encoding of strings that are looked for in the source file "path".
14594 Allowed encodings are:
14596 s Single 7-bit-byte characters like ASCII and the ASCII-compatible
14598 parts of ISO-8859-X (this is what "guestfs_strings" uses).
14599 S Single 8-bit-byte characters.
14601 b 16-bit big endian strings such as those encoded in UTF-16BE or
14603 UCS-2BE.
14604 l (lower case letter L)
14606 16-bit little endian such as UTF-16LE and UCS-2LE. This is useful
14607 for examining binaries in Windows guests.
14608 B 32-bit big endian such as UCS-4BE.
14610 L 32-bit little endian such as UCS-4LE.
14612 The returned strings are transcoded to UTF-8.
14614 The "strings" command has, in the past, had problems with parsing
14616 untrusted files. These are mitigated in the current version of
14617 libguestfs, but see "CVE-2014-8484".
14618 This function returns a NULL-terminated array of strings (like
14620 environ(3)), or NULL if there was an error. The caller must free the
14621 strings and the array after use.
14622 Because of the message protocol, there is a transfer limit of somewhere
14624 between 2MB and 4MB. See "PROTOCOL LIMITS".
14625 (Added in 1.0.22)
14627 guestfs_swapoff_device
14629 int
14630 guestfs_swapoff_device (guestfs_h *g,
14631 const char *device);
14632 This command disables the libguestfs appliance swap device or partition
14634 named "device". See "guestfs_swapon_device".
14635 This function returns 0 on success or -1 on error.
14637 (Added in 1.0.66)
14639 guestfs_swapoff_file
14641 int
14642 guestfs_swapoff_file (guestfs_h *g,
14643 const char *file);
14644 This command disables the libguestfs appliance swap on file.
14646 This function returns 0 on success or -1 on error.
14648 (Added in 1.0.66)
14650 guestfs_swapoff_label
14652 int
14653 guestfs_swapoff_label (guestfs_h *g,
14654 const char *label);
14655 This command disables the libguestfs appliance swap on labeled swap
14657 partition.
14658 This function returns 0 on success or -1 on error.
14660 (Added in 1.0.66)
14662 guestfs_swapoff_uuid
14664 int
14665 guestfs_swapoff_uuid (guestfs_h *g,
14666 const char *uuid);
14667 This command disables the libguestfs appliance swap partition with the
14669 given UUID.
14670 This function returns 0 on success or -1 on error.
14672 This function depends on the feature "linuxfsuuid". See also
14674 "guestfs_feature_available".
14675 (Added in 1.0.66)
14677 guestfs_swapon_device
14679 int
14680 guestfs_swapon_device (guestfs_h *g,
14681 const char *device);
14682 This command enables the libguestfs appliance to use the swap device or
14684 partition named "device". The increased memory is made available for
14685 all commands, for example those run using "guestfs_command" or
14686 "guestfs_sh".
14687 Note that you should not swap to existing guest swap partitions unless
14689 you know what you are doing. They may contain hibernation information,
14690 or other information that the guest doesn't want you to trash. You
14691 also risk leaking information about the host to the guest this way.
14692 Instead, attach a new host device to the guest and swap on that.
14693 This function returns 0 on success or -1 on error.
14695 (Added in 1.0.66)
14697 guestfs_swapon_file
14699 int
14700 guestfs_swapon_file (guestfs_h *g,
14701 const char *file);
14702 This command enables swap to a file. See "guestfs_swapon_device" for
14704 other notes.
14705 This function returns 0 on success or -1 on error.
14707 (Added in 1.0.66)
14709 guestfs_swapon_label
14711 int
14712 guestfs_swapon_label (guestfs_h *g,
14713 const char *label);
14714 This command enables swap to a labeled swap partition. See
14716 "guestfs_swapon_device" for other notes.
14717 This function returns 0 on success or -1 on error.
14719 (Added in 1.0.66)
14721 guestfs_swapon_uuid
14723 int
14724 guestfs_swapon_uuid (guestfs_h *g,
14725 const char *uuid);
14726 This command enables swap to a swap partition with the given UUID. See
14728 "guestfs_swapon_device" for other notes.
14729 This function returns 0 on success or -1 on error.
14731 This function depends on the feature "linuxfsuuid". See also
14733 "guestfs_feature_available".
14734 (Added in 1.0.66)
14736 guestfs_sync
14738 int
14739 guestfs_sync (guestfs_h *g);
14740 This syncs the disk, so that any writes are flushed through to the
14742 underlying disk image.
14743 You should always call this if you have modified a disk image, before
14745 closing the handle.
14746 This function returns 0 on success or -1 on error.
14748 (Added in 0.3)
14750 guestfs_syslinux
14752 int
14753 guestfs_syslinux (guestfs_h *g,
14754 const char *device,
14755 ...);
14756 You may supply a list of optional arguments to this call. Use zero or
14758 more of the following pairs of parameters, and terminate the list with
14759 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14760 GUESTFS_SYSLINUX_DIRECTORY, const char *directory,
14762 Install the SYSLINUX bootloader on "device".
14764 The device parameter must be either a whole disk formatted as a FAT
14766 filesystem, or a partition formatted as a FAT filesystem. In the
14767 latter case, the partition should be marked as "active"
14768 ("guestfs_part_set_bootable") and a Master Boot Record must be
14769 installed (eg. using "guestfs_pwrite_device") on the first sector of
14770 the whole disk. The SYSLINUX package comes with some suitable Master
14771 Boot Records. See the syslinux(1) man page for further information.
14772 The optional arguments are:
14774 directory
14776 Install SYSLINUX in the named subdirectory, instead of in the root
14777 directory of the FAT filesystem.
14778 Additional configuration can be supplied to SYSLINUX by placing a file
14780 called syslinux.cfg on the FAT filesystem, either in the root
14781 directory, or under directory if that optional argument is being used.
14782 For further information about the contents of this file, see
14783 syslinux(1).
14784 See also "guestfs_extlinux".
14786 This function returns 0 on success or -1 on error.
14788 This function depends on the feature "syslinux". See also
14790 "guestfs_feature_available".
14791 (Added in 1.21.27)
14793 guestfs_syslinux_va
14795 int
14796 guestfs_syslinux_va (guestfs_h *g,
14797 const char *device,
14798 va_list args);
14799 This is the "va_list variant" of "guestfs_syslinux".
14801 See "CALLS WITH OPTIONAL ARGUMENTS".
14803 guestfs_syslinux_argv
14805 int
14806 guestfs_syslinux_argv (guestfs_h *g,
14807 const char *device,
14808 const struct guestfs_syslinux_argv *optargs);
14809 This is the "argv variant" of "guestfs_syslinux".
14811 See "CALLS WITH OPTIONAL ARGUMENTS".
14813 guestfs_tail
14815 char **
14816 guestfs_tail (guestfs_h *g,
14817 const char *path);
14818 This command returns up to the last 10 lines of a file as a list of
14820 strings.
14821 This function returns a NULL-terminated array of strings (like
14823 environ(3)), or NULL if there was an error. The caller must free the
14824 strings and the array after use.
14825 Because of the message protocol, there is a transfer limit of somewhere
14827 between 2MB and 4MB. See "PROTOCOL LIMITS".
14828 (Added in 1.0.54)
14830 guestfs_tail_n
14832 char **
14833 guestfs_tail_n (guestfs_h *g,
14834 int nrlines,
14835 const char *path);
14836 If the parameter "nrlines" is a positive number, this returns the last
14838 "nrlines" lines of the file "path".
14839 If the parameter "nrlines" is a negative number, this returns lines
14841 from the file "path", starting with the "-nrlines"th line.
14842 If the parameter "nrlines" is zero, this returns an empty list.
14844 This function returns a NULL-terminated array of strings (like
14846 environ(3)), or NULL if there was an error. The caller must free the
14847 strings and the array after use.
14848 Because of the message protocol, there is a transfer limit of somewhere
14850 between 2MB and 4MB. See "PROTOCOL LIMITS".
14851 (Added in 1.0.54)
14853 guestfs_tar_in
14855 int
14856 guestfs_tar_in (guestfs_h *g,
14857 const char *tarfile,
14858 const char *directory);
14859 This function is provided for backwards compatibility with earlier
14861 versions of libguestfs. It simply calls "guestfs_tar_in_opts" with no
14862 optional arguments.
14863 (Added in 1.0.3)
14865 guestfs_tar_in_opts
14867 int
14868 guestfs_tar_in_opts (guestfs_h *g,
14869 const char *tarfile,
14870 const char *directory,
14871 ...);
14872 You may supply a list of optional arguments to this call. Use zero or
14874 more of the following pairs of parameters, and terminate the list with
14875 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14876 GUESTFS_TAR_IN_OPTS_COMPRESS, const char *compress,
14878 GUESTFS_TAR_IN_OPTS_XATTRS, int xattrs,
14879 GUESTFS_TAR_IN_OPTS_SELINUX, int selinux,
14880 GUESTFS_TAR_IN_OPTS_ACLS, int acls,
14881 This command uploads and unpacks local file "tarfile" into directory.
14883 The optional "compress" flag controls compression. If not given, then
14885 the input should be an uncompressed tar file. Otherwise one of the
14886 following strings may be given to select the compression type of the
14887 input file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
14888 all builds of libguestfs will support all of these compression types).
14889 The other optional arguments are:
14891 "xattrs"
14893 If set to true, extended attributes are restored from the tar file.
14894 "selinux"
14896 If set to true, SELinux contexts are restored from the tar file.
14897 "acls"
14899 If set to true, POSIX ACLs are restored from the tar file.
14900 This function returns 0 on success or -1 on error.
14902 (Added in 1.0.3)
14904 guestfs_tar_in_opts_va
14906 int
14907 guestfs_tar_in_opts_va (guestfs_h *g,
14908 const char *tarfile,
14909 const char *directory,
14910 va_list args);
14911 This is the "va_list variant" of "guestfs_tar_in_opts".
14913 See "CALLS WITH OPTIONAL ARGUMENTS".
14915 guestfs_tar_in_opts_argv
14917 int
14918 guestfs_tar_in_opts_argv (guestfs_h *g,
14919 const char *tarfile,
14920 const char *directory,
14921 const struct guestfs_tar_in_opts_argv *optargs);
14922 This is the "argv variant" of "guestfs_tar_in_opts".
14924 See "CALLS WITH OPTIONAL ARGUMENTS".
14926 guestfs_tar_out
14928 int
14929 guestfs_tar_out (guestfs_h *g,
14930 const char *directory,
14931 const char *tarfile);
14932 This function is provided for backwards compatibility with earlier
14934 versions of libguestfs. It simply calls "guestfs_tar_out_opts" with no
14935 optional arguments.
14936 (Added in 1.0.3)
14938 guestfs_tar_out_opts
14940 int
14941 guestfs_tar_out_opts (guestfs_h *g,
14942 const char *directory,
14943 const char *tarfile,
14944 ...);
14945 You may supply a list of optional arguments to this call. Use zero or
14947 more of the following pairs of parameters, and terminate the list with
14948 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
14949 GUESTFS_TAR_OUT_OPTS_COMPRESS, const char *compress,
14951 GUESTFS_TAR_OUT_OPTS_NUMERICOWNER, int numericowner,
14952 GUESTFS_TAR_OUT_OPTS_EXCLUDES, char *const *excludes,
14953 GUESTFS_TAR_OUT_OPTS_XATTRS, int xattrs,
14954 GUESTFS_TAR_OUT_OPTS_SELINUX, int selinux,
14955 GUESTFS_TAR_OUT_OPTS_ACLS, int acls,
14956 This command packs the contents of directory and downloads it to local
14958 file "tarfile".
14959 The optional "compress" flag controls compression. If not given, then
14961 the output will be an uncompressed tar file. Otherwise one of the
14962 following strings may be given to select the compression type of the
14963 output file: "compress", "gzip", "bzip2", "xz", "lzop". (Note that not
14964 all builds of libguestfs will support all of these compression types).
14965 The other optional arguments are:
14967 "excludes"
14969 A list of wildcards. Files are excluded if they match any of the
14970 wildcards.
14971 "numericowner"
14973 If set to true, the output tar file will contain UID/GID numbers
14974 instead of user/group names.
14975 "xattrs"
14977 If set to true, extended attributes are saved in the output tar.
14978 "selinux"
14980 If set to true, SELinux contexts are saved in the output tar.
14981 "acls"
14983 If set to true, POSIX ACLs are saved in the output tar.
14984 This function returns 0 on success or -1 on error.
14986 (Added in 1.0.3)
14988 guestfs_tar_out_opts_va
14990 int
14991 guestfs_tar_out_opts_va (guestfs_h *g,
14992 const char *directory,
14993 const char *tarfile,
14994 va_list args);
14995 This is the "va_list variant" of "guestfs_tar_out_opts".
14997 See "CALLS WITH OPTIONAL ARGUMENTS".
14999 guestfs_tar_out_opts_argv
15001 int
15002 guestfs_tar_out_opts_argv (guestfs_h *g,
15003 const char *directory,
15004 const char *tarfile,
15005 const struct guestfs_tar_out_opts_argv *optargs);
15006 This is the "argv variant" of "guestfs_tar_out_opts".
15008 See "CALLS WITH OPTIONAL ARGUMENTS".
15010 guestfs_tgz_in
15012 int
15013 guestfs_tgz_in (guestfs_h *g,
15014 const char *tarball,
15015 const char *directory);
15016 This function is deprecated. In new code, use the "guestfs_tar_in"
15018 call instead.
15019 Deprecated functions will not be removed from the API, but the fact
15021 that they are deprecated indicates that there are problems with correct
15022 use of these functions.
15023 This command uploads and unpacks local file "tarball" (a gzip
15025 compressed tar file) into directory.
15026 This function returns 0 on success or -1 on error.
15028 (Added in 1.0.3)
15030 guestfs_tgz_out
15032 int
15033 guestfs_tgz_out (guestfs_h *g,
15034 const char *directory,
15035 const char *tarball);
15036 This function is deprecated. In new code, use the "guestfs_tar_out"
15038 call instead.
15039 Deprecated functions will not be removed from the API, but the fact
15041 that they are deprecated indicates that there are problems with correct
15042 use of these functions.
15043 This command packs the contents of directory and downloads it to local
15045 file "tarball".
15046 This function returns 0 on success or -1 on error.
15048 (Added in 1.0.3)
15050 guestfs_touch
15052 int
15053 guestfs_touch (guestfs_h *g,
15054 const char *path);
15055 Touch acts like the touch(1) command. It can be used to update the
15057 timestamps on a file, or, if the file does not exist, to create a new
15058 zero-length file.
15059 This command only works on regular files, and will fail on other file
15061 types such as directories, symbolic links, block special etc.
15062 This function returns 0 on success or -1 on error.
15064 (Added in 0.3)
15066 guestfs_truncate
15068 int
15069 guestfs_truncate (guestfs_h *g,
15070 const char *path);
15071 This command truncates "path" to a zero-length file. The file must
15073 exist already.
15074 This function returns 0 on success or -1 on error.
15076 (Added in 1.0.77)
15078 guestfs_truncate_size
15080 int
15081 guestfs_truncate_size (guestfs_h *g,
15082 const char *path,
15083 int64_t size);
15084 This command truncates "path" to size "size" bytes. The file must
15086 exist already.
15087 If the current file size is less than "size" then the file is extended
15089 to the required size with zero bytes. This creates a sparse file (ie.
15090 disk blocks are not allocated for the file until you write to it). To
15091 create a non-sparse file of zeroes, use "guestfs_fallocate64" instead.
15092 This function returns 0 on success or -1 on error.
15094 (Added in 1.0.77)
15096 guestfs_tune2fs
15098 int
15099 guestfs_tune2fs (guestfs_h *g,
15100 const char *device,
15101 ...);
15102 You may supply a list of optional arguments to this call. Use zero or
15104 more of the following pairs of parameters, and terminate the list with
15105 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15106 GUESTFS_TUNE2FS_FORCE, int force,
15108 GUESTFS_TUNE2FS_MAXMOUNTCOUNT, int maxmountcount,
15109 GUESTFS_TUNE2FS_MOUNTCOUNT, int mountcount,
15110 GUESTFS_TUNE2FS_ERRORBEHAVIOR, const char *errorbehavior,
15111 GUESTFS_TUNE2FS_GROUP, int64_t group,
15112 GUESTFS_TUNE2FS_INTERVALBETWEENCHECKS, int intervalbetweenchecks,
15113 GUESTFS_TUNE2FS_RESERVEDBLOCKSPERCENTAGE, int reservedblockspercentage,
15114 GUESTFS_TUNE2FS_LASTMOUNTEDDIRECTORY, const char *lastmounteddirectory,
15115 GUESTFS_TUNE2FS_RESERVEDBLOCKSCOUNT, int64_t reservedblockscount,
15116 GUESTFS_TUNE2FS_USER, int64_t user,
15117 This call allows you to adjust various filesystem parameters of an
15119 ext2/ext3/ext4 filesystem called "device".
15120 The optional parameters are:
15122 "force"
15124 Force tune2fs to complete the operation even in the face of errors.
15125 This is the same as the tune2fs "-f" option.
15126 "maxmountcount"
15128 Set the number of mounts after which the filesystem is checked by
15129 e2fsck(8). If this is 0 then the number of mounts is disregarded.
15130 This is the same as the tune2fs "-c" option.
15131 "mountcount"
15133 Set the number of times the filesystem has been mounted. This is
15134 the same as the tune2fs "-C" option.
15135 "errorbehavior"
15137 Change the behavior of the kernel code when errors are detected.
15138 Possible values currently are: "continue", "remount-ro", "panic".
15139 In practice these options don't really make any difference,
15140 particularly for write errors.
15141 This is the same as the tune2fs "-e" option.
15143 "group"
15145 Set the group which can use reserved filesystem blocks. This is
15146 the same as the tune2fs "-g" option except that it can only be
15147 specified as a number.
15148 "intervalbetweenchecks"
15150 Adjust the maximal time between two filesystem checks (in seconds).
15151 If the option is passed as 0 then time-dependent checking is
15152 disabled.
15153 This is the same as the tune2fs "-i" option.
15155 "reservedblockspercentage"
15157 Set the percentage of the filesystem which may only be allocated by
15158 privileged processes. This is the same as the tune2fs "-m" option.
15159 "lastmounteddirectory"
15161 Set the last mounted directory. This is the same as the tune2fs
15162 "-M" option.
15163 "reservedblockscount" Set the number of reserved filesystem blocks.
15165 This is the same as the tune2fs "-r" option.
15166 "user"
15167 Set the user who can use the reserved filesystem blocks. This is
15168 the same as the tune2fs "-u" option except that it can only be
15169 specified as a number.
15170 To get the current values of filesystem parameters, see
15172 "guestfs_tune2fs_l". For precise details of how tune2fs works, see the
15173 tune2fs(8) man page.
15174 This function returns 0 on success or -1 on error.
15176 (Added in 1.15.4)
15178 guestfs_tune2fs_va
15180 int
15181 guestfs_tune2fs_va (guestfs_h *g,
15182 const char *device,
15183 va_list args);
15184 This is the "va_list variant" of "guestfs_tune2fs".
15186 See "CALLS WITH OPTIONAL ARGUMENTS".
15188 guestfs_tune2fs_argv
15190 int
15191 guestfs_tune2fs_argv (guestfs_h *g,
15192 const char *device,
15193 const struct guestfs_tune2fs_argv *optargs);
15194 This is the "argv variant" of "guestfs_tune2fs".
15196 See "CALLS WITH OPTIONAL ARGUMENTS".
15198 guestfs_tune2fs_l
15200 char **
15201 guestfs_tune2fs_l (guestfs_h *g,
15202 const char *device);
15203 This returns the contents of the ext2, ext3 or ext4 filesystem
15205 superblock on "device".
15206 It is the same as running "tune2fs -l device". See tune2fs(8) manpage
15208 for more details. The list of fields returned isn't clearly defined,
15209 and depends on both the version of "tune2fs" that libguestfs was built
15210 against, and the filesystem itself.
15211 This function returns a NULL-terminated array of strings, or NULL if
15213 there was an error. The array of strings will always have length
15214 "2n+1", where "n" keys and values alternate, followed by the trailing
15215 NULL entry. The caller must free the strings and the array after use.
15216 (Added in 1.9.2)
15218 guestfs_txz_in
15220 int
15221 guestfs_txz_in (guestfs_h *g,
15222 const char *tarball,
15223 const char *directory);
15224 This function is deprecated. In new code, use the "guestfs_tar_in"
15226 call instead.
15227 Deprecated functions will not be removed from the API, but the fact
15229 that they are deprecated indicates that there are problems with correct
15230 use of these functions.
15231 This command uploads and unpacks local file "tarball" (an xz compressed
15233 tar file) into directory.
15234 This function returns 0 on success or -1 on error.
15236 This function depends on the feature "xz". See also
15238 "guestfs_feature_available".
15239 (Added in 1.3.2)
15241 guestfs_txz_out
15243 int
15244 guestfs_txz_out (guestfs_h *g,
15245 const char *directory,
15246 const char *tarball);
15247 This function is deprecated. In new code, use the "guestfs_tar_out"
15249 call instead.
15250 Deprecated functions will not be removed from the API, but the fact
15252 that they are deprecated indicates that there are problems with correct
15253 use of these functions.
15254 This command packs the contents of directory and downloads it to local
15256 file "tarball" (as an xz compressed tar archive).
15257 This function returns 0 on success or -1 on error.
15259 This function depends on the feature "xz". See also
15261 "guestfs_feature_available".
15262 (Added in 1.3.2)
15264 guestfs_umask
15266 int
15267 guestfs_umask (guestfs_h *g,
15268 int mask);
15269 This function sets the mask used for creating new files and device
15271 nodes to "mask & 0777".
15272 Typical umask values would be 022 which creates new files with
15274 permissions like "-rw-r--r--" or "-rwxr-xr-x", and 002 which creates
15275 new files with permissions like "-rw-rw-r--" or "-rwxrwxr-x".
15276 The default umask is 022. This is important because it means that
15278 directories and device nodes will be created with 0644 or 0755 mode
15279 even if you specify 0777.
15280 See also "guestfs_get_umask", umask(2), "guestfs_mknod",
15282 "guestfs_mkdir".
15283 This call returns the previous umask.
15285 On error this function returns -1.
15287 (Added in 1.0.55)
15289 guestfs_umount
15291 int
15292 guestfs_umount (guestfs_h *g,
15293 const char *pathordevice);
15294 This function is provided for backwards compatibility with earlier
15296 versions of libguestfs. It simply calls "guestfs_umount_opts" with no
15297 optional arguments.
15298 (Added in 0.8)
15300 guestfs_umount_opts
15302 int
15303 guestfs_umount_opts (guestfs_h *g,
15304 const char *pathordevice,
15305 ...);
15306 You may supply a list of optional arguments to this call. Use zero or
15308 more of the following pairs of parameters, and terminate the list with
15309 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15310 GUESTFS_UMOUNT_OPTS_FORCE, int force,
15312 GUESTFS_UMOUNT_OPTS_LAZYUNMOUNT, int lazyunmount,
15313 This unmounts the given filesystem. The filesystem may be specified
15315 either by its mountpoint (path) or the device which contains the
15316 filesystem.
15317 This function returns 0 on success or -1 on error.
15319 (Added in 0.8)
15321 guestfs_umount_opts_va
15323 int
15324 guestfs_umount_opts_va (guestfs_h *g,
15325 const char *pathordevice,
15326 va_list args);
15327 This is the "va_list variant" of "guestfs_umount_opts".
15329 See "CALLS WITH OPTIONAL ARGUMENTS".
15331 guestfs_umount_opts_argv
15333 int
15334 guestfs_umount_opts_argv (guestfs_h *g,
15335 const char *pathordevice,
15336 const struct guestfs_umount_opts_argv *optargs);
15337 This is the "argv variant" of "guestfs_umount_opts".
15339 See "CALLS WITH OPTIONAL ARGUMENTS".
15341 guestfs_umount_all
15343 int
15344 guestfs_umount_all (guestfs_h *g);
15345 This unmounts all mounted filesystems.
15347 Some internal mounts are not unmounted by this call.
15349 This function returns 0 on success or -1 on error.
15351 (Added in 0.8)
15353 guestfs_umount_local
15355 int
15356 guestfs_umount_local (guestfs_h *g,
15357 ...);
15358 You may supply a list of optional arguments to this call. Use zero or
15360 more of the following pairs of parameters, and terminate the list with
15361 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
15362 GUESTFS_UMOUNT_LOCAL_RETRY, int retry,
15364 If libguestfs is exporting the filesystem on a local mountpoint, then
15366 this unmounts it.
15367 See "MOUNT LOCAL" for full documentation.
15369 This function returns 0 on success or -1 on error.
15371 (Added in 1.17.22)
15373 guestfs_umount_local_va
15375 int
15376 guestfs_umount_local_va (guestfs_h *g,
15377 va_list args);
15378 This is the "va_list variant" of "guestfs_umount_local".
15380 See "CALLS WITH OPTIONAL ARGUMENTS".
15382 guestfs_umount_local_argv
15384 int
15385 guestfs_umount_local_argv (guestfs_h *g,
15386 const struct guestfs_umount_local_argv *optargs);
15387 This is the "argv variant" of "guestfs_umount_local".
15389 See "CALLS WITH OPTIONAL ARGUMENTS".
15391 guestfs_upload
15393 int
15394 guestfs_upload (guestfs_h *g,
15395 const char *filename,
15396 const char *remotefilename);
15397 Upload local file filename to remotefilename on the filesystem.
15399 filename can also be a named pipe.
15401 See also "guestfs_download".
15403 This function returns 0 on success or -1 on error.
15405 This long-running command can generate progress notification messages
15407 so that the caller can display a progress bar or indicator. To receive
15408 these messages, the caller must register a progress event callback.
15409 See "GUESTFS_EVENT_PROGRESS".
15410 (Added in 1.0.2)
15412 guestfs_upload_offset
15414 int
15415 guestfs_upload_offset (guestfs_h *g,
15416 const char *filename,
15417 const char *remotefilename,
15418 int64_t offset);
15419 Upload local file filename to remotefilename on the filesystem.
15421 remotefilename is overwritten starting at the byte "offset" specified.
15423 The intention is to overwrite parts of existing files or devices,
15424 although if a non-existent file is specified then it is created with a
15425 "hole" before "offset". The size of the data written is implicit in
15426 the size of the source filename.
15427 Note that there is no limit on the amount of data that can be uploaded
15429 with this call, unlike with "guestfs_pwrite", and this call always
15430 writes the full amount unless an error occurs.
15431 See also "guestfs_upload", "guestfs_pwrite".
15433 This function returns 0 on success or -1 on error.
15435 This long-running command can generate progress notification messages
15437 so that the caller can display a progress bar or indicator. To receive
15438 these messages, the caller must register a progress event callback.
15439 See "GUESTFS_EVENT_PROGRESS".
15440 (Added in 1.5.17)
15442 guestfs_user_cancel
15444 int
15445 guestfs_user_cancel (guestfs_h *g);
15446 This function cancels the current upload or download operation.
15448 Unlike most other libguestfs calls, this function is signal safe and
15450 thread safe. You can call it from a signal handler or from another
15451 thread, without needing to do any locking.
15452 The transfer that was in progress (if there is one) will stop shortly
15454 afterwards, and will return an error. The errno (see
15455 "guestfs_last_errno") is set to "EINTR", so you can test for this to
15456 find out if the operation was cancelled or failed because of another
15457 error.
15458 No cleanup is performed: for example, if a file was being uploaded then
15460 after cancellation there may be a partially uploaded file. It is the
15461 caller’s responsibility to clean up if necessary.
15462 There are two common places that you might call "guestfs_user_cancel":
15464 In an interactive text-based program, you might call it from a "SIGINT"
15466 signal handler so that pressing "^C" cancels the current operation.
15467 (You also need to call "guestfs_set_pgroup" so that child processes
15468 don't receive the "^C" signal).
15469 In a graphical program, when the main thread is displaying a progress
15471 bar with a cancel button, wire up the cancel button to call this
15472 function.
15473 This function returns 0 on success or -1 on error.
15475 (Added in 1.11.18)
15477 guestfs_utimens
15479 int
15480 guestfs_utimens (guestfs_h *g,
15481 const char *path,
15482 int64_t atsecs,
15483 int64_t atnsecs,
15484 int64_t mtsecs,
15485 int64_t mtnsecs);
15486 This command sets the timestamps of a file with nanosecond precision.
15488 "atsecs, atnsecs" are the last access time (atime) in secs and
15490 nanoseconds from the epoch.
15491 "mtsecs, mtnsecs" are the last modification time (mtime) in secs and
15493 nanoseconds from the epoch.
15494 If the *nsecs field contains the special value "-1" then the
15496 corresponding timestamp is set to the current time. (The *secs field
15497 is ignored in this case).
15498 If the *nsecs field contains the special value "-2" then the
15500 corresponding timestamp is left unchanged. (The *secs field is ignored
15501 in this case).
15502 This function returns 0 on success or -1 on error.
15504 (Added in 1.0.77)
15506 guestfs_utsname
15508 struct guestfs_utsname *
15509 guestfs_utsname (guestfs_h *g);
15510 This returns the kernel version of the appliance, where this is
15512 available. This information is only useful for debugging. Nothing in
15513 the returned structure is defined by the API.
15514 This function returns a "struct guestfs_utsname *", or NULL if there
15516 was an error. The caller must call "guestfs_free_utsname" after use.
15517 (Added in 1.19.27)
15519 guestfs_version
15521 struct guestfs_version *
15522 guestfs_version (guestfs_h *g);
15523 Return the libguestfs version number that the program is linked
15525 against.
15526 Note that because of dynamic linking this is not necessarily the
15528 version of libguestfs that you compiled against. You can compile the
15529 program, and then at runtime dynamically link against a completely
15530 different libguestfs.so library.
15531 This call was added in version 1.0.58. In previous versions of
15533 libguestfs there was no way to get the version number. From C code you
15534 can use dynamic linker functions to find out if this symbol exists (if
15535 it doesn't, then it’s an earlier version).
15536 The call returns a structure with four elements. The first three
15538 ("major", "minor" and "release") are numbers and correspond to the
15539 usual version triplet. The fourth element ("extra") is a string and is
15540 normally empty, but may be used for distro-specific information.
15541 To construct the original version string:
15543 "$major.$minor.$release$extra"
15544 See also: "LIBGUESTFS VERSION NUMBERS".
15546 Note: Don't use this call to test for availability of features. In
15548 enterprise distributions we backport features from later versions into
15549 earlier versions, making this an unreliable way to test for features.
15550 Use "guestfs_available" or "guestfs_feature_available" instead.
15551 This function returns a "struct guestfs_version *", or NULL if there
15553 was an error. The caller must call "guestfs_free_version" after use.
15554 (Added in 1.0.58)
15556 guestfs_vfs_label
15558 char *
15559 guestfs_vfs_label (guestfs_h *g,
15560 const char *mountable);
15561 This returns the label of the filesystem on "mountable".
15563 If the filesystem is unlabeled, this returns the empty string.
15565 To find a filesystem from the label, use "guestfs_findfs_label".
15567 This function returns a string, or NULL on error. The caller must free
15569 the returned string after use.
15570 (Added in 1.3.18)
15572 guestfs_vfs_minimum_size
15574 int64_t
15575 guestfs_vfs_minimum_size (guestfs_h *g,
15576 const char *mountable);
15577 Get the minimum size of filesystem in bytes. This is the minimum
15579 possible size for filesystem shrinking.
15580 If getting minimum size of specified filesystem is not supported, this
15582 will fail and set errno as ENOTSUP.
15583 See also ntfsresize(8), resize2fs(8), btrfs(8), xfs_info(8).
15585 On error this function returns -1.
15587 (Added in 1.31.18)
15589 guestfs_vfs_type
15591 char *
15592 guestfs_vfs_type (guestfs_h *g,
15593 const char *mountable);
15594 This command gets the filesystem type corresponding to the filesystem
15596 on "mountable".
15597 For most filesystems, the result is the name of the Linux VFS module
15599 which would be used to mount this filesystem if you mounted it without
15600 specifying the filesystem type. For example a string such as "ext3" or
15601 "ntfs".
15602 This function returns a string, or NULL on error. The caller must free
15604 the returned string after use.
15605 (Added in 1.0.75)
15607 guestfs_vfs_uuid
15609 char *
15610 guestfs_vfs_uuid (guestfs_h *g,
15611 const char *mountable);
15612 This returns the filesystem UUID of the filesystem on "mountable".
15614 If the filesystem does not have a UUID, this returns the empty string.
15616 To find a filesystem from the UUID, use "guestfs_findfs_uuid".
15618 This function returns a string, or NULL on error. The caller must free
15620 the returned string after use.
15621 (Added in 1.3.18)
15623 guestfs_vg_activate
15625 int
15626 guestfs_vg_activate (guestfs_h *g,
15627 int activate,
15628 char *const *volgroups);
15629 This command activates or (if "activate" is false) deactivates all
15631 logical volumes in the listed volume groups "volgroups".
15632 This command is the same as running "vgchange -a y|n volgroups..."
15634 Note that if "volgroups" is an empty list then all volume groups are
15636 activated or deactivated.
15637 This function returns 0 on success or -1 on error.
15639 This function depends on the feature "lvm2". See also
15641 "guestfs_feature_available".
15642 (Added in 1.0.26)
15644 guestfs_vg_activate_all
15646 int
15647 guestfs_vg_activate_all (guestfs_h *g,
15648 int activate);
15649 This command activates or (if "activate" is false) deactivates all
15651 logical volumes in all volume groups.
15652 This command is the same as running "vgchange -a y|n"
15654 This function returns 0 on success or -1 on error.
15656 This function depends on the feature "lvm2". See also
15658 "guestfs_feature_available".
15659 (Added in 1.0.26)
15661 guestfs_vgchange_uuid
15663 int
15664 guestfs_vgchange_uuid (guestfs_h *g,
15665 const char *vg);
15666 Generate a new random UUID for the volume group "vg".
15668 This function returns 0 on success or -1 on error.
15670 This function depends on the feature "lvm2". See also
15672 "guestfs_feature_available".
15673 (Added in 1.19.26)
15675 guestfs_vgchange_uuid_all
15677 int
15678 guestfs_vgchange_uuid_all (guestfs_h *g);
15679 Generate new random UUIDs for all volume groups.
15681 This function returns 0 on success or -1 on error.
15683 This function depends on the feature "lvm2". See also
15685 "guestfs_feature_available".
15686 (Added in 1.19.26)
15688 guestfs_vgcreate
15690 int
15691 guestfs_vgcreate (guestfs_h *g,
15692 const char *volgroup,
15693 char *const *physvols);
15694 This creates an LVM volume group called "volgroup" from the non-empty
15696 list of physical volumes "physvols".
15697 This function returns 0 on success or -1 on error.
15699 This function depends on the feature "lvm2". See also
15701 "guestfs_feature_available".
15702 (Added in 0.8)
15704 guestfs_vglvuuids
15706 char **
15707 guestfs_vglvuuids (guestfs_h *g,
15708 const char *vgname);
15709 Given a VG called "vgname", this returns the UUIDs of all the logical
15711 volumes created in this volume group.
15712 You can use this along with "guestfs_lvs" and "guestfs_lvuuid" calls to
15714 associate logical volumes and volume groups.
15715 See also "guestfs_vgpvuuids".
15717 This function returns a NULL-terminated array of strings (like
15719 environ(3)), or NULL if there was an error. The caller must free the
15720 strings and the array after use.
15721 (Added in 1.0.87)
15723 guestfs_vgmeta
15725 char *
15726 guestfs_vgmeta (guestfs_h *g,
15727 const char *vgname,
15728 size_t *size_r);
15729 "vgname" is an LVM volume group. This command examines the volume
15731 group and returns its metadata.
15732 Note that the metadata is an internal structure used by LVM, subject to
15734 change at any time, and is provided for information only.
15735 This function returns a buffer, or NULL on error. The size of the
15737 returned buffer is written to *size_r. The caller must free the
15738 returned buffer after use.
15739 This function depends on the feature "lvm2". See also
15741 "guestfs_feature_available".
15742 (Added in 1.17.20)
15744 guestfs_vgpvuuids
15746 char **
15747 guestfs_vgpvuuids (guestfs_h *g,
15748 const char *vgname);
15749 Given a VG called "vgname", this returns the UUIDs of all the physical
15751 volumes that this volume group resides on.
15752 You can use this along with "guestfs_pvs" and "guestfs_pvuuid" calls to
15754 associate physical volumes and volume groups.
15755 See also "guestfs_vglvuuids".
15757 This function returns a NULL-terminated array of strings (like
15759 environ(3)), or NULL if there was an error. The caller must free the
15760 strings and the array after use.
15761 (Added in 1.0.87)
15763 guestfs_vgremove
15765 int
15766 guestfs_vgremove (guestfs_h *g,
15767 const char *vgname);
15768 Remove an LVM volume group "vgname", (for example "VG").
15770 This also forcibly removes all logical volumes in the volume group (if
15772 any).
15773 This function returns 0 on success or -1 on error.
15775 This function depends on the feature "lvm2". See also
15777 "guestfs_feature_available".
15778 (Added in 1.0.13)
15780 guestfs_vgrename
15782 int
15783 guestfs_vgrename (guestfs_h *g,
15784 const char *volgroup,
15785 const char *newvolgroup);
15786 Rename a volume group "volgroup" with the new name "newvolgroup".
15788 This function returns 0 on success or -1 on error.
15790 (Added in 1.0.83)
15792 guestfs_vgs
15794 char **
15795 guestfs_vgs (guestfs_h *g);
15796 List all the volumes groups detected. This is the equivalent of the
15798 vgs(8) command.
15799 This returns a list of just the volume group names that were detected
15801 (eg. "VolGroup00").
15802 See also "guestfs_vgs_full".
15804 This function returns a NULL-terminated array of strings (like
15806 environ(3)), or NULL if there was an error. The caller must free the
15807 strings and the array after use.
15808 This function depends on the feature "lvm2". See also
15810 "guestfs_feature_available".
15811 (Added in 0.4)
15813 guestfs_vgs_full
15815 struct guestfs_lvm_vg_list *
15816 guestfs_vgs_full (guestfs_h *g);
15817 List all the volumes groups detected. This is the equivalent of the
15819 vgs(8) command. The "full" version includes all fields.
15820 This function returns a "struct guestfs_lvm_vg_list *", or NULL if
15822 there was an error. The caller must call "guestfs_free_lvm_vg_list"
15823 after use.
15824 This function depends on the feature "lvm2". See also
15826 "guestfs_feature_available".
15827 (Added in 0.4)
15829 guestfs_vgscan
15831 int
15832 guestfs_vgscan (guestfs_h *g);
15833 This function is deprecated. In new code, use the "guestfs_lvm_scan"
15835 call instead.
15836 Deprecated functions will not be removed from the API, but the fact
15838 that they are deprecated indicates that there are problems with correct
15839 use of these functions.
15840 This rescans all block devices and rebuilds the list of LVM physical
15842 volumes, volume groups and logical volumes.
15843 This function returns 0 on success or -1 on error.
15845 (Added in 1.3.2)
15847 guestfs_vguuid
15849 char *
15850 guestfs_vguuid (guestfs_h *g,
15851 const char *vgname);
15852 This command returns the UUID of the LVM VG named "vgname".
15854 This function returns a string, or NULL on error. The caller must free
15856 the returned string after use.
15857 (Added in 1.0.87)
15859 guestfs_wait_ready
15861 int
15862 guestfs_wait_ready (guestfs_h *g);
15863 This function is deprecated. There is no replacement. Consult the API
15865 documentation in guestfs(3) for further information.
15866 Deprecated functions will not be removed from the API, but the fact
15868 that they are deprecated indicates that there are problems with correct
15869 use of these functions.
15870 This function is a no op.
15872 In versions of the API < 1.0.71 you had to call this function just
15874 after calling "guestfs_launch" to wait for the launch to complete.
15875 However this is no longer necessary because "guestfs_launch" now does
15876 the waiting.
15877 If you see any calls to this function in code then you can just remove
15879 them, unless you want to retain compatibility with older versions of
15880 the API.
15881 This function returns 0 on success or -1 on error.
15883 (Added in 0.3)
15885 guestfs_wc_c
15887 int
15888 guestfs_wc_c (guestfs_h *g,
15889 const char *path);
15890 This command counts the characters in a file, using the "wc -c"
15892 external command.
15893 On error this function returns -1.
15895 (Added in 1.0.54)
15897 guestfs_wc_l
15899 int
15900 guestfs_wc_l (guestfs_h *g,
15901 const char *path);
15902 This command counts the lines in a file, using the "wc -l" external
15904 command.
15905 On error this function returns -1.
15907 (Added in 1.0.54)
15909 guestfs_wc_w
15911 int
15912 guestfs_wc_w (guestfs_h *g,
15913 const char *path);
15914 This command counts the words in a file, using the "wc -w" external
15916 command.
15917 On error this function returns -1.
15919 (Added in 1.0.54)
15921 guestfs_wipefs
15923 int
15924 guestfs_wipefs (guestfs_h *g,
15925 const char *device);
15926 This command erases filesystem or RAID signatures from the specified
15928 "device" to make the filesystem invisible to libblkid.
15929 This does not erase the filesystem itself nor any other data from the
15931 "device".
15932 Compare with "guestfs_zero" which zeroes the first few blocks of a
15934 device.
15935 This function returns 0 on success or -1 on error.
15937 This function depends on the feature "wipefs". See also
15939 "guestfs_feature_available".
15940 (Added in 1.17.6)
15942 guestfs_write
15944 int
15945 guestfs_write (guestfs_h *g,
15946 const char *path,
15947 const char *content,
15948 size_t content_size);
15949 This call creates a file called "path". The content of the file is the
15951 string "content" (which can contain any 8 bit data).
15952 See also "guestfs_write_append".
15954 This function returns 0 on success or -1 on error.
15956 (Added in 1.3.14)
15958 guestfs_write_append
15960 int
15961 guestfs_write_append (guestfs_h *g,
15962 const char *path,
15963 const char *content,
15964 size_t content_size);
15965 This call appends "content" to the end of file "path". If "path" does
15967 not exist, then a new file is created.
15968 See also "guestfs_write".
15970 This function returns 0 on success or -1 on error.
15972 (Added in 1.11.18)
15974 guestfs_write_file
15976 int
15977 guestfs_write_file (guestfs_h *g,
15978 const char *path,
15979 const char *content,
15980 int size);
15981 This function is deprecated. In new code, use the "guestfs_write" call
15983 instead.
15984 Deprecated functions will not be removed from the API, but the fact
15986 that they are deprecated indicates that there are problems with correct
15987 use of these functions.
15988 This call creates a file called "path". The contents of the file is
15990 the string "content" (which can contain any 8 bit data), with length
15991 "size".
15992 As a special case, if "size" is 0 then the length is calculated using
15994 "strlen" (so in this case the content cannot contain embedded ASCII
15995 NULs).
15996 NB. Owing to a bug, writing content containing ASCII NUL characters
15998 does not work, even if the length is specified.
15999 This function returns 0 on success or -1 on error.
16001 Because of the message protocol, there is a transfer limit of somewhere
16003 between 2MB and 4MB. See "PROTOCOL LIMITS".
16004 (Added in 0.8)
16006 guestfs_xfs_admin
16008 int
16009 guestfs_xfs_admin (guestfs_h *g,
16010 const char *device,
16011 ...);
16012 You may supply a list of optional arguments to this call. Use zero or
16014 more of the following pairs of parameters, and terminate the list with
16015 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16016 GUESTFS_XFS_ADMIN_EXTUNWRITTEN, int extunwritten,
16018 GUESTFS_XFS_ADMIN_IMGFILE, int imgfile,
16019 GUESTFS_XFS_ADMIN_V2LOG, int v2log,
16020 GUESTFS_XFS_ADMIN_PROJID32BIT, int projid32bit,
16021 GUESTFS_XFS_ADMIN_LAZYCOUNTER, int lazycounter,
16022 GUESTFS_XFS_ADMIN_LABEL, const char *label,
16023 GUESTFS_XFS_ADMIN_UUID, const char *uuid,
16024 Change the parameters of the XFS filesystem on "device".
16026 Devices that are mounted cannot be modified. Administrators must
16028 unmount filesystems before this call can modify parameters.
16029 Some of the parameters of a mounted filesystem can be examined and
16031 modified using the "guestfs_xfs_info" and "guestfs_xfs_growfs" calls.
16032 This function returns 0 on success or -1 on error.
16034 This function depends on the feature "xfs". See also
16036 "guestfs_feature_available".
16037 (Added in 1.19.33)
16039 guestfs_xfs_admin_va
16041 int
16042 guestfs_xfs_admin_va (guestfs_h *g,
16043 const char *device,
16044 va_list args);
16045 This is the "va_list variant" of "guestfs_xfs_admin".
16047 See "CALLS WITH OPTIONAL ARGUMENTS".
16049 guestfs_xfs_admin_argv
16051 int
16052 guestfs_xfs_admin_argv (guestfs_h *g,
16053 const char *device,
16054 const struct guestfs_xfs_admin_argv *optargs);
16055 This is the "argv variant" of "guestfs_xfs_admin".
16057 See "CALLS WITH OPTIONAL ARGUMENTS".
16059 guestfs_xfs_growfs
16061 int
16062 guestfs_xfs_growfs (guestfs_h *g,
16063 const char *path,
16064 ...);
16065 You may supply a list of optional arguments to this call. Use zero or
16067 more of the following pairs of parameters, and terminate the list with
16068 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16069 GUESTFS_XFS_GROWFS_DATASEC, int datasec,
16071 GUESTFS_XFS_GROWFS_LOGSEC, int logsec,
16072 GUESTFS_XFS_GROWFS_RTSEC, int rtsec,
16073 GUESTFS_XFS_GROWFS_DATASIZE, int64_t datasize,
16074 GUESTFS_XFS_GROWFS_LOGSIZE, int64_t logsize,
16075 GUESTFS_XFS_GROWFS_RTSIZE, int64_t rtsize,
16076 GUESTFS_XFS_GROWFS_RTEXTSIZE, int64_t rtextsize,
16077 GUESTFS_XFS_GROWFS_MAXPCT, int maxpct,
16078 Grow the XFS filesystem mounted at "path".
16080 The returned struct contains geometry information. Missing fields are
16082 returned as "-1" (for numeric fields) or empty string.
16083 This function returns 0 on success or -1 on error.
16085 This function depends on the feature "xfs". See also
16087 "guestfs_feature_available".
16088 (Added in 1.19.28)
16090 guestfs_xfs_growfs_va
16092 int
16093 guestfs_xfs_growfs_va (guestfs_h *g,
16094 const char *path,
16095 va_list args);
16096 This is the "va_list variant" of "guestfs_xfs_growfs".
16098 See "CALLS WITH OPTIONAL ARGUMENTS".
16100 guestfs_xfs_growfs_argv
16102 int
16103 guestfs_xfs_growfs_argv (guestfs_h *g,
16104 const char *path,
16105 const struct guestfs_xfs_growfs_argv *optargs);
16106 This is the "argv variant" of "guestfs_xfs_growfs".
16108 See "CALLS WITH OPTIONAL ARGUMENTS".
16110 guestfs_xfs_info
16112 struct guestfs_xfsinfo *
16113 guestfs_xfs_info (guestfs_h *g,
16114 const char *pathordevice);
16115 "pathordevice" is a mounted XFS filesystem or a device containing an
16117 XFS filesystem. This command returns the geometry of the filesystem.
16118 The returned struct contains geometry information. Missing fields are
16120 returned as "-1" (for numeric fields) or empty string.
16121 This function returns a "struct guestfs_xfsinfo *", or NULL if there
16123 was an error. The caller must call "guestfs_free_xfsinfo" after use.
16124 This function depends on the feature "xfs". See also
16126 "guestfs_feature_available".
16127 (Added in 1.19.21)
16129 guestfs_xfs_repair
16131 int
16132 guestfs_xfs_repair (guestfs_h *g,
16133 const char *device,
16134 ...);
16135 You may supply a list of optional arguments to this call. Use zero or
16137 more of the following pairs of parameters, and terminate the list with
16138 "-1" on its own. See "CALLS WITH OPTIONAL ARGUMENTS".
16139 GUESTFS_XFS_REPAIR_FORCELOGZERO, int forcelogzero,
16141 GUESTFS_XFS_REPAIR_NOMODIFY, int nomodify,
16142 GUESTFS_XFS_REPAIR_NOPREFETCH, int noprefetch,
16143 GUESTFS_XFS_REPAIR_FORCEGEOMETRY, int forcegeometry,
16144 GUESTFS_XFS_REPAIR_MAXMEM, int64_t maxmem,
16145 GUESTFS_XFS_REPAIR_IHASHSIZE, int64_t ihashsize,
16146 GUESTFS_XFS_REPAIR_BHASHSIZE, int64_t bhashsize,
16147 GUESTFS_XFS_REPAIR_AGSTRIDE, int64_t agstride,
16148 GUESTFS_XFS_REPAIR_LOGDEV, const char *logdev,
16149 GUESTFS_XFS_REPAIR_RTDEV, const char *rtdev,
16150 Repair corrupt or damaged XFS filesystem on "device".
16152 The filesystem is specified using the "device" argument which should be
16154 the device name of the disk partition or volume containing the
16155 filesystem. If given the name of a block device, "xfs_repair" will
16156 attempt to find the raw device associated with the specified block
16157 device and will use the raw device instead.
16158 Regardless, the filesystem to be repaired must be unmounted, otherwise,
16160 the resulting filesystem may be inconsistent or corrupt.
16161 The returned status indicates whether filesystem corruption was
16163 detected (returns 1) or was not detected (returns 0).
16164 On error this function returns -1.
16166 This function depends on the feature "xfs". See also
16168 "guestfs_feature_available".
16169 (Added in 1.19.36)
16171 guestfs_xfs_repair_va
16173 int
16174 guestfs_xfs_repair_va (guestfs_h *g,
16175 const char *device,
16176 va_list args);
16177 This is the "va_list variant" of "guestfs_xfs_repair".
16179 See "CALLS WITH OPTIONAL ARGUMENTS".
16181 guestfs_xfs_repair_argv
16183 int
16184 guestfs_xfs_repair_argv (guestfs_h *g,
16185 const char *device,
16186 const struct guestfs_xfs_repair_argv *optargs);
16187 This is the "argv variant" of "guestfs_xfs_repair".
16189 See "CALLS WITH OPTIONAL ARGUMENTS".
16191 guestfs_yara_destroy
16193 int
16194 guestfs_yara_destroy (guestfs_h *g);
16195 Destroy previously loaded Yara rules in order to free libguestfs
16197 resources.
16198 This function returns 0 on success or -1 on error.
16200 This function depends on the feature "libyara". See also
16202 "guestfs_feature_available".
16203 (Added in 1.37.13)
16205 guestfs_yara_load
16207 int
16208 guestfs_yara_load (guestfs_h *g,
16209 const char *filename);
16210 Upload a set of Yara rules from local file filename.
16212 Yara rules allow to categorize files based on textual or binary
16214 patterns within their content. See "guestfs_yara_scan" to see how to
16215 scan files with the loaded rules.
16216 Rules can be in binary format, as when compiled with yarac command, or
16218 in source code format. In the latter case, the rules will be first
16219 compiled and then loaded.
16220 Rules in source code format cannot include external files. In such
16222 cases, it is recommended to compile them first.
16223 Previously loaded rules will be destroyed.
16225 This function returns 0 on success or -1 on error.
16227 This long-running command can generate progress notification messages
16229 so that the caller can display a progress bar or indicator. To receive
16230 these messages, the caller must register a progress event callback.
16231 See "GUESTFS_EVENT_PROGRESS".
16232 This function depends on the feature "libyara". See also
16234 "guestfs_feature_available".
16235 (Added in 1.37.13)
16237 guestfs_yara_scan
16239 struct guestfs_yara_detection_list *
16240 guestfs_yara_scan (guestfs_h *g,
16241 const char *path);
16242 Scan a file with the previously loaded Yara rules.
16244 For each matching rule, a "yara_detection" structure is returned.
16246 The "yara_detection" structure contains the following fields.
16248 "yara_name"
16250 Path of the file matching a Yara rule.
16251 "yara_rule"
16253 Identifier of the Yara rule which matched against the given file.
16254 This function returns a "struct guestfs_yara_detection_list *", or NULL
16256 if there was an error. The caller must call
16257 "guestfs_free_yara_detection_list" after use.
16258 This long-running command can generate progress notification messages
16260 so that the caller can display a progress bar or indicator. To receive
16261 these messages, the caller must register a progress event callback.
16262 See "GUESTFS_EVENT_PROGRESS".
16263 This function depends on the feature "libyara". See also
16265 "guestfs_feature_available".
16266 (Added in 1.37.13)
16268 guestfs_zegrep
16270 char **
16271 guestfs_zegrep (guestfs_h *g,
16272 const char *regex,
16273 const char *path);
16274 This function is deprecated. In new code, use the "guestfs_grep" call
16276 instead.
16277 Deprecated functions will not be removed from the API, but the fact
16279 that they are deprecated indicates that there are problems with correct
16280 use of these functions.
16281 This calls the external "zegrep" program and returns the matching
16283 lines.
16284 This function returns a NULL-terminated array of strings (like
16286 environ(3)), or NULL if there was an error. The caller must free the
16287 strings and the array after use.
16288 Because of the message protocol, there is a transfer limit of somewhere
16290 between 2MB and 4MB. See "PROTOCOL LIMITS".
16291 (Added in 1.0.66)
16293 guestfs_zegrepi
16295 char **
16296 guestfs_zegrepi (guestfs_h *g,
16297 const char *regex,
16298 const char *path);
16299 This function is deprecated. In new code, use the "guestfs_grep" call
16301 instead.
16302 Deprecated functions will not be removed from the API, but the fact
16304 that they are deprecated indicates that there are problems with correct
16305 use of these functions.
16306 This calls the external "zegrep -i" program and returns the matching
16308 lines.
16309 This function returns a NULL-terminated array of strings (like
16311 environ(3)), or NULL if there was an error. The caller must free the
16312 strings and the array after use.
16313 Because of the message protocol, there is a transfer limit of somewhere
16315 between 2MB and 4MB. See "PROTOCOL LIMITS".
16316 (Added in 1.0.66)
16318 guestfs_zero
16320 int
16321 guestfs_zero (guestfs_h *g,
16322 const char *device);
16323 This command writes zeroes over the first few blocks of "device".
16325 How many blocks are zeroed isn't specified (but it’s not enough to
16327 securely wipe the device). It should be sufficient to remove any
16328 partition tables, filesystem superblocks and so on.
16329 If blocks are already zero, then this command avoids writing zeroes.
16331 This prevents the underlying device from becoming non-sparse or growing
16332 unnecessarily.
16333 See also: "guestfs_zero_device", "guestfs_scrub_device",
16335 "guestfs_is_zero_device"
16336 This function returns 0 on success or -1 on error.
16338 This long-running command can generate progress notification messages
16340 so that the caller can display a progress bar or indicator. To receive
16341 these messages, the caller must register a progress event callback.
16342 See "GUESTFS_EVENT_PROGRESS".
16343 (Added in 1.0.16)
16345 guestfs_zero_device
16347 int
16348 guestfs_zero_device (guestfs_h *g,
16349 const char *device);
16350 This command writes zeroes over the entire "device". Compare with
16352 "guestfs_zero" which just zeroes the first few blocks of a device.
16353 If blocks are already zero, then this command avoids writing zeroes.
16355 This prevents the underlying device from becoming non-sparse or growing
16356 unnecessarily.
16357 This function returns 0 on success or -1 on error.
16359 This long-running command can generate progress notification messages
16361 so that the caller can display a progress bar or indicator. To receive
16362 these messages, the caller must register a progress event callback.
16363 See "GUESTFS_EVENT_PROGRESS".
16364 (Added in 1.3.1)
16366 guestfs_zero_free_space
16368 int
16369 guestfs_zero_free_space (guestfs_h *g,
16370 const char *directory);
16371 Zero the free space in the filesystem mounted on directory. The
16373 filesystem must be mounted read-write.
16374 The filesystem contents are not affected, but any free space in the
16376 filesystem is freed.
16377 Free space is not "trimmed". You may want to call "guestfs_fstrim"
16379 either as an alternative to this, or after calling this, depending on
16380 your requirements.
16381 This function returns 0 on success or -1 on error.
16383 This long-running command can generate progress notification messages
16385 so that the caller can display a progress bar or indicator. To receive
16386 these messages, the caller must register a progress event callback.
16387 See "GUESTFS_EVENT_PROGRESS".
16388 (Added in 1.17.18)
16390 guestfs_zerofree
16392 int
16393 guestfs_zerofree (guestfs_h *g,
16394 const char *device);
16395 This runs the zerofree program on "device". This program claims to
16397 zero unused inodes and disk blocks on an ext2/3 filesystem, thus making
16398 it possible to compress the filesystem more effectively.
16399 You should not run this program if the filesystem is mounted.
16401 It is possible that using this program can damage the filesystem or
16403 data on the filesystem.
16404 This function returns 0 on success or -1 on error.
16406 This function depends on the feature "zerofree". See also
16408 "guestfs_feature_available".
16409 (Added in 1.0.26)
16411 guestfs_zfgrep
16413 char **
16414 guestfs_zfgrep (guestfs_h *g,
16415 const char *pattern,
16416 const char *path);
16417 This function is deprecated. In new code, use the "guestfs_grep" call
16419 instead.
16420 Deprecated functions will not be removed from the API, but the fact
16422 that they are deprecated indicates that there are problems with correct
16423 use of these functions.
16424 This calls the external "zfgrep" program and returns the matching
16426 lines.
16427 This function returns a NULL-terminated array of strings (like
16429 environ(3)), or NULL if there was an error. The caller must free the
16430 strings and the array after use.
16431 Because of the message protocol, there is a transfer limit of somewhere
16433 between 2MB and 4MB. See "PROTOCOL LIMITS".
16434 (Added in 1.0.66)
16436 guestfs_zfgrepi
16438 char **
16439 guestfs_zfgrepi (guestfs_h *g,
16440 const char *pattern,
16441 const char *path);
16442 This function is deprecated. In new code, use the "guestfs_grep" call
16444 instead.
16445 Deprecated functions will not be removed from the API, but the fact
16447 that they are deprecated indicates that there are problems with correct
16448 use of these functions.
16449 This calls the external "zfgrep -i" program and returns the matching
16451 lines.
16452 This function returns a NULL-terminated array of strings (like
16454 environ(3)), or NULL if there was an error. The caller must free the
16455 strings and the array after use.
16456 Because of the message protocol, there is a transfer limit of somewhere
16458 between 2MB and 4MB. See "PROTOCOL LIMITS".
16459 (Added in 1.0.66)
16461 guestfs_zfile
16463 char *
16464 guestfs_zfile (guestfs_h *g,
16465 const char *meth,
16466 const char *path);
16467 This function is deprecated. In new code, use the "guestfs_file" call
16469 instead.
16470 Deprecated functions will not be removed from the API, but the fact
16472 that they are deprecated indicates that there are problems with correct
16473 use of these functions.
16474 This command runs file after first decompressing "path" using "method".
16476 "method" must be one of "gzip", "compress" or "bzip2".
16478 Since 1.0.63, use "guestfs_file" instead which can now process
16480 compressed files.
16481 This function returns a string, or NULL on error. The caller must free
16483 the returned string after use.
16484 (Added in 1.0.59)
16486 guestfs_zgrep
16488 char **
16489 guestfs_zgrep (guestfs_h *g,
16490 const char *regex,
16491 const char *path);
16492 This function is deprecated. In new code, use the "guestfs_grep" call
16494 instead.
16495 Deprecated functions will not be removed from the API, but the fact
16497 that they are deprecated indicates that there are problems with correct
16498 use of these functions.
16499 This calls the external "zgrep" program and returns the matching lines.
16501 This function returns a NULL-terminated array of strings (like
16503 environ(3)), or NULL if there was an error. The caller must free the
16504 strings and the array after use.
16505 Because of the message protocol, there is a transfer limit of somewhere
16507 between 2MB and 4MB. See "PROTOCOL LIMITS".
16508 (Added in 1.0.66)
16510 guestfs_zgrepi
16512 char **
16513 guestfs_zgrepi (guestfs_h *g,
16514 const char *regex,
16515 const char *path);
16516 This function is deprecated. In new code, use the "guestfs_grep" call
16518 instead.
16519 Deprecated functions will not be removed from the API, but the fact
16521 that they are deprecated indicates that there are problems with correct
16522 use of these functions.
16523 This calls the external "zgrep -i" program and returns the matching
16525 lines.
16526 This function returns a NULL-terminated array of strings (like
16528 environ(3)), or NULL if there was an error. The caller must free the
16529 strings and the array after use.
16530 Because of the message protocol, there is a transfer limit of somewhere
16532 between 2MB and 4MB. See "PROTOCOL LIMITS".
16533 (Added in 1.0.66)
16535
16537 guestfs_int_bool
16538 struct guestfs_int_bool {
16539 int32_t i;
16540 int32_t b;
16541 };
16542 struct guestfs_int_bool_list {
16544 uint32_t len; /* Number of elements in list. */
16545 struct guestfs_int_bool *val; /* Elements. */
16546 };
16547 int guestfs_compare_int_bool (const struct guestfs_int_bool *, const struct guestfs_int_bool *);
16549 int guestfs_compare_int_bool_list (const struct guestfs_int_bool_list *, const struct guestfs_int_bool_list *);
16550 struct guestfs_int_bool *guestfs_copy_int_bool (const struct guestfs_int_bool *);
16552 struct guestfs_int_bool_list *guestfs_copy_int_bool_list (const struct guestfs_int_bool_list *);
16553 void guestfs_free_int_bool (struct guestfs_int_bool *);
16555 void guestfs_free_int_bool_list (struct guestfs_int_bool_list *);
16556 guestfs_lvm_pv
16558 struct guestfs_lvm_pv {
16559 char *pv_name;
16560 /* The next field is NOT nul-terminated, be careful when printing it: */
16561 char pv_uuid[32];
16562 char *pv_fmt;
16563 uint64_t pv_size;
16564 uint64_t dev_size;
16565 uint64_t pv_free;
16566 uint64_t pv_used;
16567 char *pv_attr;
16568 int64_t pv_pe_count;
16569 int64_t pv_pe_alloc_count;
16570 char *pv_tags;
16571 uint64_t pe_start;
16572 int64_t pv_mda_count;
16573 uint64_t pv_mda_free;
16574 };
16575 struct guestfs_lvm_pv_list {
16577 uint32_t len; /* Number of elements in list. */
16578 struct guestfs_lvm_pv *val; /* Elements. */
16579 };
16580 int guestfs_compare_lvm_pv (const struct guestfs_lvm_pv *, const struct guestfs_lvm_pv *);
16582 int guestfs_compare_lvm_pv_list (const struct guestfs_lvm_pv_list *, const struct guestfs_lvm_pv_list *);
16583 struct guestfs_lvm_pv *guestfs_copy_lvm_pv (const struct guestfs_lvm_pv *);
16585 struct guestfs_lvm_pv_list *guestfs_copy_lvm_pv_list (const struct guestfs_lvm_pv_list *);
16586 void guestfs_free_lvm_pv (struct guestfs_lvm_pv *);
16588 void guestfs_free_lvm_pv_list (struct guestfs_lvm_pv_list *);
16589 guestfs_lvm_vg
16591 struct guestfs_lvm_vg {
16592 char *vg_name;
16593 /* The next field is NOT nul-terminated, be careful when printing it: */
16594 char vg_uuid[32];
16595 char *vg_fmt;
16596 char *vg_attr;
16597 uint64_t vg_size;
16598 uint64_t vg_free;
16599 char *vg_sysid;
16600 uint64_t vg_extent_size;
16601 int64_t vg_extent_count;
16602 int64_t vg_free_count;
16603 int64_t max_lv;
16604 int64_t max_pv;
16605 int64_t pv_count;
16606 int64_t lv_count;
16607 int64_t snap_count;
16608 int64_t vg_seqno;
16609 char *vg_tags;
16610 int64_t vg_mda_count;
16611 uint64_t vg_mda_free;
16612 };
16613 struct guestfs_lvm_vg_list {
16615 uint32_t len; /* Number of elements in list. */
16616 struct guestfs_lvm_vg *val; /* Elements. */
16617 };
16618 int guestfs_compare_lvm_vg (const struct guestfs_lvm_vg *, const struct guestfs_lvm_vg *);
16620 int guestfs_compare_lvm_vg_list (const struct guestfs_lvm_vg_list *, const struct guestfs_lvm_vg_list *);
16621 struct guestfs_lvm_vg *guestfs_copy_lvm_vg (const struct guestfs_lvm_vg *);
16623 struct guestfs_lvm_vg_list *guestfs_copy_lvm_vg_list (const struct guestfs_lvm_vg_list *);
16624 void guestfs_free_lvm_vg (struct guestfs_lvm_vg *);
16626 void guestfs_free_lvm_vg_list (struct guestfs_lvm_vg_list *);
16627 guestfs_lvm_lv
16629 struct guestfs_lvm_lv {
16630 char *lv_name;
16631 /* The next field is NOT nul-terminated, be careful when printing it: */
16632 char lv_uuid[32];
16633 char *lv_attr;
16634 int64_t lv_major;
16635 int64_t lv_minor;
16636 int64_t lv_kernel_major;
16637 int64_t lv_kernel_minor;
16638 uint64_t lv_size;
16639 int64_t seg_count;
16640 char *origin;
16641 /* The next field is [0..100] or -1 meaning 'not present': */
16642 float snap_percent;
16643 /* The next field is [0..100] or -1 meaning 'not present': */
16644 float copy_percent;
16645 char *move_pv;
16646 char *lv_tags;
16647 char *mirror_log;
16648 char *modules;
16649 };
16650 struct guestfs_lvm_lv_list {
16652 uint32_t len; /* Number of elements in list. */
16653 struct guestfs_lvm_lv *val; /* Elements. */
16654 };
16655 int guestfs_compare_lvm_lv (const struct guestfs_lvm_lv *, const struct guestfs_lvm_lv *);
16657 int guestfs_compare_lvm_lv_list (const struct guestfs_lvm_lv_list *, const struct guestfs_lvm_lv_list *);
16658 struct guestfs_lvm_lv *guestfs_copy_lvm_lv (const struct guestfs_lvm_lv *);
16660 struct guestfs_lvm_lv_list *guestfs_copy_lvm_lv_list (const struct guestfs_lvm_lv_list *);
16661 void guestfs_free_lvm_lv (struct guestfs_lvm_lv *);
16663 void guestfs_free_lvm_lv_list (struct guestfs_lvm_lv_list *);
16664 guestfs_stat
16666 struct guestfs_stat {
16667 int64_t dev;
16668 int64_t ino;
16669 int64_t mode;
16670 int64_t nlink;
16671 int64_t uid;
16672 int64_t gid;
16673 int64_t rdev;
16674 int64_t size;
16675 int64_t blksize;
16676 int64_t blocks;
16677 int64_t atime;
16678 int64_t mtime;
16679 int64_t ctime;
16680 };
16681 struct guestfs_stat_list {
16683 uint32_t len; /* Number of elements in list. */
16684 struct guestfs_stat *val; /* Elements. */
16685 };
16686 int guestfs_compare_stat (const struct guestfs_stat *, const struct guestfs_stat *);
16688 int guestfs_compare_stat_list (const struct guestfs_stat_list *, const struct guestfs_stat_list *);
16689 struct guestfs_stat *guestfs_copy_stat (const struct guestfs_stat *);
16691 struct guestfs_stat_list *guestfs_copy_stat_list (const struct guestfs_stat_list *);
16692 void guestfs_free_stat (struct guestfs_stat *);
16694 void guestfs_free_stat_list (struct guestfs_stat_list *);
16695 guestfs_statns
16697 struct guestfs_statns {
16698 int64_t st_dev;
16699 int64_t st_ino;
16700 int64_t st_mode;
16701 int64_t st_nlink;
16702 int64_t st_uid;
16703 int64_t st_gid;
16704 int64_t st_rdev;
16705 int64_t st_size;
16706 int64_t st_blksize;
16707 int64_t st_blocks;
16708 int64_t st_atime_sec;
16709 int64_t st_atime_nsec;
16710 int64_t st_mtime_sec;
16711 int64_t st_mtime_nsec;
16712 int64_t st_ctime_sec;
16713 int64_t st_ctime_nsec;
16714 int64_t st_spare1;
16715 int64_t st_spare2;
16716 int64_t st_spare3;
16717 int64_t st_spare4;
16718 int64_t st_spare5;
16719 int64_t st_spare6;
16720 };
16721 struct guestfs_statns_list {
16723 uint32_t len; /* Number of elements in list. */
16724 struct guestfs_statns *val; /* Elements. */
16725 };
16726 int guestfs_compare_statns (const struct guestfs_statns *, const struct guestfs_statns *);
16728 int guestfs_compare_statns_list (const struct guestfs_statns_list *, const struct guestfs_statns_list *);
16729 struct guestfs_statns *guestfs_copy_statns (const struct guestfs_statns *);
16731 struct guestfs_statns_list *guestfs_copy_statns_list (const struct guestfs_statns_list *);
16732 void guestfs_free_statns (struct guestfs_statns *);
16734 void guestfs_free_statns_list (struct guestfs_statns_list *);
16735 guestfs_statvfs
16737 struct guestfs_statvfs {
16738 int64_t bsize;
16739 int64_t frsize;
16740 int64_t blocks;
16741 int64_t bfree;
16742 int64_t bavail;
16743 int64_t files;
16744 int64_t ffree;
16745 int64_t favail;
16746 int64_t fsid;
16747 int64_t flag;
16748 int64_t namemax;
16749 };
16750 struct guestfs_statvfs_list {
16752 uint32_t len; /* Number of elements in list. */
16753 struct guestfs_statvfs *val; /* Elements. */
16754 };
16755 int guestfs_compare_statvfs (const struct guestfs_statvfs *, const struct guestfs_statvfs *);
16757 int guestfs_compare_statvfs_list (const struct guestfs_statvfs_list *, const struct guestfs_statvfs_list *);
16758 struct guestfs_statvfs *guestfs_copy_statvfs (const struct guestfs_statvfs *);
16760 struct guestfs_statvfs_list *guestfs_copy_statvfs_list (const struct guestfs_statvfs_list *);
16761 void guestfs_free_statvfs (struct guestfs_statvfs *);
16763 void guestfs_free_statvfs_list (struct guestfs_statvfs_list *);
16764 guestfs_dirent
16766 struct guestfs_dirent {
16767 int64_t ino;
16768 char ftyp;
16769 char *name;
16770 };
16771 struct guestfs_dirent_list {
16773 uint32_t len; /* Number of elements in list. */
16774 struct guestfs_dirent *val; /* Elements. */
16775 };
16776 int guestfs_compare_dirent (const struct guestfs_dirent *, const struct guestfs_dirent *);
16778 int guestfs_compare_dirent_list (const struct guestfs_dirent_list *, const struct guestfs_dirent_list *);
16779 struct guestfs_dirent *guestfs_copy_dirent (const struct guestfs_dirent *);
16781 struct guestfs_dirent_list *guestfs_copy_dirent_list (const struct guestfs_dirent_list *);
16782 void guestfs_free_dirent (struct guestfs_dirent *);
16784 void guestfs_free_dirent_list (struct guestfs_dirent_list *);
16785 guestfs_version
16787 struct guestfs_version {
16788 int64_t major;
16789 int64_t minor;
16790 int64_t release;
16791 char *extra;
16792 };
16793 struct guestfs_version_list {
16795 uint32_t len; /* Number of elements in list. */
16796 struct guestfs_version *val; /* Elements. */
16797 };
16798 int guestfs_compare_version (const struct guestfs_version *, const struct guestfs_version *);
16800 int guestfs_compare_version_list (const struct guestfs_version_list *, const struct guestfs_version_list *);
16801 struct guestfs_version *guestfs_copy_version (const struct guestfs_version *);
16803 struct guestfs_version_list *guestfs_copy_version_list (const struct guestfs_version_list *);
16804 void guestfs_free_version (struct guestfs_version *);
16806 void guestfs_free_version_list (struct guestfs_version_list *);
16807 guestfs_xattr
16809 struct guestfs_xattr {
16810 char *attrname;
16811 /* The next two fields describe a byte array. */
16812 uint32_t attrval_len;
16813 char *attrval;
16814 };
16815 struct guestfs_xattr_list {
16817 uint32_t len; /* Number of elements in list. */
16818 struct guestfs_xattr *val; /* Elements. */
16819 };
16820 int guestfs_compare_xattr (const struct guestfs_xattr *, const struct guestfs_xattr *);
16822 int guestfs_compare_xattr_list (const struct guestfs_xattr_list *, const struct guestfs_xattr_list *);
16823 struct guestfs_xattr *guestfs_copy_xattr (const struct guestfs_xattr *);
16825 struct guestfs_xattr_list *guestfs_copy_xattr_list (const struct guestfs_xattr_list *);
16826 void guestfs_free_xattr (struct guestfs_xattr *);
16828 void guestfs_free_xattr_list (struct guestfs_xattr_list *);
16829 guestfs_inotify_event
16831 struct guestfs_inotify_event {
16832 int64_t in_wd;
16833 uint32_t in_mask;
16834 uint32_t in_cookie;
16835 char *in_name;
16836 };
16837 struct guestfs_inotify_event_list {
16839 uint32_t len; /* Number of elements in list. */
16840 struct guestfs_inotify_event *val; /* Elements. */
16841 };
16842 int guestfs_compare_inotify_event (const struct guestfs_inotify_event *, const struct guestfs_inotify_event *);
16844 int guestfs_compare_inotify_event_list (const struct guestfs_inotify_event_list *, const struct guestfs_inotify_event_list *);
16845 struct guestfs_inotify_event *guestfs_copy_inotify_event (const struct guestfs_inotify_event *);
16847 struct guestfs_inotify_event_list *guestfs_copy_inotify_event_list (const struct guestfs_inotify_event_list *);
16848 void guestfs_free_inotify_event (struct guestfs_inotify_event *);
16850 void guestfs_free_inotify_event_list (struct guestfs_inotify_event_list *);
16851 guestfs_partition
16853 struct guestfs_partition {
16854 int32_t part_num;
16855 uint64_t part_start;
16856 uint64_t part_end;
16857 uint64_t part_size;
16858 };
16859 struct guestfs_partition_list {
16861 uint32_t len; /* Number of elements in list. */
16862 struct guestfs_partition *val; /* Elements. */
16863 };
16864 int guestfs_compare_partition (const struct guestfs_partition *, const struct guestfs_partition *);
16866 int guestfs_compare_partition_list (const struct guestfs_partition_list *, const struct guestfs_partition_list *);
16867 struct guestfs_partition *guestfs_copy_partition (const struct guestfs_partition *);
16869 struct guestfs_partition_list *guestfs_copy_partition_list (const struct guestfs_partition_list *);
16870 void guestfs_free_partition (struct guestfs_partition *);
16872 void guestfs_free_partition_list (struct guestfs_partition_list *);
16873 guestfs_application
16875 struct guestfs_application {
16876 char *app_name;
16877 char *app_display_name;
16878 int32_t app_epoch;
16879 char *app_version;
16880 char *app_release;
16881 char *app_install_path;
16882 char *app_trans_path;
16883 char *app_publisher;
16884 char *app_url;
16885 char *app_source_package;
16886 char *app_summary;
16887 char *app_description;
16888 };
16889 struct guestfs_application_list {
16891 uint32_t len; /* Number of elements in list. */
16892 struct guestfs_application *val; /* Elements. */
16893 };
16894 int guestfs_compare_application (const struct guestfs_application *, const struct guestfs_application *);
16896 int guestfs_compare_application_list (const struct guestfs_application_list *, const struct guestfs_application_list *);
16897 struct guestfs_application *guestfs_copy_application (const struct guestfs_application *);
16899 struct guestfs_application_list *guestfs_copy_application_list (const struct guestfs_application_list *);
16900 void guestfs_free_application (struct guestfs_application *);
16902 void guestfs_free_application_list (struct guestfs_application_list *);
16903 guestfs_application2
16905 struct guestfs_application2 {
16906 char *app2_name;
16907 char *app2_display_name;
16908 int32_t app2_epoch;
16909 char *app2_version;
16910 char *app2_release;
16911 char *app2_arch;
16912 char *app2_install_path;
16913 char *app2_trans_path;
16914 char *app2_publisher;
16915 char *app2_url;
16916 char *app2_source_package;
16917 char *app2_summary;
16918 char *app2_description;
16919 char *app2_spare1;
16920 char *app2_spare2;
16921 char *app2_spare3;
16922 char *app2_spare4;
16923 };
16924 struct guestfs_application2_list {
16926 uint32_t len; /* Number of elements in list. */
16927 struct guestfs_application2 *val; /* Elements. */
16928 };
16929 int guestfs_compare_application2 (const struct guestfs_application2 *, const struct guestfs_application2 *);
16931 int guestfs_compare_application2_list (const struct guestfs_application2_list *, const struct guestfs_application2_list *);
16932 struct guestfs_application2 *guestfs_copy_application2 (const struct guestfs_application2 *);
16934 struct guestfs_application2_list *guestfs_copy_application2_list (const struct guestfs_application2_list *);
16935 void guestfs_free_application2 (struct guestfs_application2 *);
16937 void guestfs_free_application2_list (struct guestfs_application2_list *);
16938 guestfs_isoinfo
16940 struct guestfs_isoinfo {
16941 char *iso_system_id;
16942 char *iso_volume_id;
16943 uint32_t iso_volume_space_size;
16944 uint32_t iso_volume_set_size;
16945 uint32_t iso_volume_sequence_number;
16946 uint32_t iso_logical_block_size;
16947 char *iso_volume_set_id;
16948 char *iso_publisher_id;
16949 char *iso_data_preparer_id;
16950 char *iso_application_id;
16951 char *iso_copyright_file_id;
16952 char *iso_abstract_file_id;
16953 char *iso_bibliographic_file_id;
16954 int64_t iso_volume_creation_t;
16955 int64_t iso_volume_modification_t;
16956 int64_t iso_volume_expiration_t;
16957 int64_t iso_volume_effective_t;
16958 };
16959 struct guestfs_isoinfo_list {
16961 uint32_t len; /* Number of elements in list. */
16962 struct guestfs_isoinfo *val; /* Elements. */
16963 };
16964 int guestfs_compare_isoinfo (const struct guestfs_isoinfo *, const struct guestfs_isoinfo *);
16966 int guestfs_compare_isoinfo_list (const struct guestfs_isoinfo_list *, const struct guestfs_isoinfo_list *);
16967 struct guestfs_isoinfo *guestfs_copy_isoinfo (const struct guestfs_isoinfo *);
16969 struct guestfs_isoinfo_list *guestfs_copy_isoinfo_list (const struct guestfs_isoinfo_list *);
16970 void guestfs_free_isoinfo (struct guestfs_isoinfo *);
16972 void guestfs_free_isoinfo_list (struct guestfs_isoinfo_list *);
16973 guestfs_mdstat
16975 struct guestfs_mdstat {
16976 char *mdstat_device;
16977 int32_t mdstat_index;
16978 char *mdstat_flags;
16979 };
16980 struct guestfs_mdstat_list {
16982 uint32_t len; /* Number of elements in list. */
16983 struct guestfs_mdstat *val; /* Elements. */
16984 };
16985 int guestfs_compare_mdstat (const struct guestfs_mdstat *, const struct guestfs_mdstat *);
16987 int guestfs_compare_mdstat_list (const struct guestfs_mdstat_list *, const struct guestfs_mdstat_list *);
16988 struct guestfs_mdstat *guestfs_copy_mdstat (const struct guestfs_mdstat *);
16990 struct guestfs_mdstat_list *guestfs_copy_mdstat_list (const struct guestfs_mdstat_list *);
16991 void guestfs_free_mdstat (struct guestfs_mdstat *);
16993 void guestfs_free_mdstat_list (struct guestfs_mdstat_list *);
16994 guestfs_btrfssubvolume
16996 struct guestfs_btrfssubvolume {
16997 uint64_t btrfssubvolume_id;
16998 uint64_t btrfssubvolume_top_level_id;
16999 char *btrfssubvolume_path;
17000 };
17001 struct guestfs_btrfssubvolume_list {
17003 uint32_t len; /* Number of elements in list. */
17004 struct guestfs_btrfssubvolume *val; /* Elements. */
17005 };
17006 int guestfs_compare_btrfssubvolume (const struct guestfs_btrfssubvolume *, const struct guestfs_btrfssubvolume *);
17008 int guestfs_compare_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *, const struct guestfs_btrfssubvolume_list *);
17009 struct guestfs_btrfssubvolume *guestfs_copy_btrfssubvolume (const struct guestfs_btrfssubvolume *);
17011 struct guestfs_btrfssubvolume_list *guestfs_copy_btrfssubvolume_list (const struct guestfs_btrfssubvolume_list *);
17012 void guestfs_free_btrfssubvolume (struct guestfs_btrfssubvolume *);
17014 void guestfs_free_btrfssubvolume_list (struct guestfs_btrfssubvolume_list *);
17015 guestfs_btrfsqgroup
17017 struct guestfs_btrfsqgroup {
17018 char *btrfsqgroup_id;
17019 uint64_t btrfsqgroup_rfer;
17020 uint64_t btrfsqgroup_excl;
17021 };
17022 struct guestfs_btrfsqgroup_list {
17024 uint32_t len; /* Number of elements in list. */
17025 struct guestfs_btrfsqgroup *val; /* Elements. */
17026 };
17027 int guestfs_compare_btrfsqgroup (const struct guestfs_btrfsqgroup *, const struct guestfs_btrfsqgroup *);
17029 int guestfs_compare_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *, const struct guestfs_btrfsqgroup_list *);
17030 struct guestfs_btrfsqgroup *guestfs_copy_btrfsqgroup (const struct guestfs_btrfsqgroup *);
17032 struct guestfs_btrfsqgroup_list *guestfs_copy_btrfsqgroup_list (const struct guestfs_btrfsqgroup_list *);
17033 void guestfs_free_btrfsqgroup (struct guestfs_btrfsqgroup *);
17035 void guestfs_free_btrfsqgroup_list (struct guestfs_btrfsqgroup_list *);
17036 guestfs_btrfsbalance
17038 struct guestfs_btrfsbalance {
17039 char *btrfsbalance_status;
17040 uint64_t btrfsbalance_total;
17041 uint64_t btrfsbalance_balanced;
17042 uint64_t btrfsbalance_considered;
17043 uint64_t btrfsbalance_left;
17044 };
17045 struct guestfs_btrfsbalance_list {
17047 uint32_t len; /* Number of elements in list. */
17048 struct guestfs_btrfsbalance *val; /* Elements. */
17049 };
17050 int guestfs_compare_btrfsbalance (const struct guestfs_btrfsbalance *, const struct guestfs_btrfsbalance *);
17052 int guestfs_compare_btrfsbalance_list (const struct guestfs_btrfsbalance_list *, const struct guestfs_btrfsbalance_list *);
17053 struct guestfs_btrfsbalance *guestfs_copy_btrfsbalance (const struct guestfs_btrfsbalance *);
17055 struct guestfs_btrfsbalance_list *guestfs_copy_btrfsbalance_list (const struct guestfs_btrfsbalance_list *);
17056 void guestfs_free_btrfsbalance (struct guestfs_btrfsbalance *);
17058 void guestfs_free_btrfsbalance_list (struct guestfs_btrfsbalance_list *);
17059 guestfs_btrfsscrub
17061 struct guestfs_btrfsscrub {
17062 uint64_t btrfsscrub_data_extents_scrubbed;
17063 uint64_t btrfsscrub_tree_extents_scrubbed;
17064 uint64_t btrfsscrub_data_bytes_scrubbed;
17065 uint64_t btrfsscrub_tree_bytes_scrubbed;
17066 uint64_t btrfsscrub_read_errors;
17067 uint64_t btrfsscrub_csum_errors;
17068 uint64_t btrfsscrub_verify_errors;
17069 uint64_t btrfsscrub_no_csum;
17070 uint64_t btrfsscrub_csum_discards;
17071 uint64_t btrfsscrub_super_errors;
17072 uint64_t btrfsscrub_malloc_errors;
17073 uint64_t btrfsscrub_uncorrectable_errors;
17074 uint64_t btrfsscrub_unverified_errors;
17075 uint64_t btrfsscrub_corrected_errors;
17076 uint64_t btrfsscrub_last_physical;
17077 };
17078 struct guestfs_btrfsscrub_list {
17080 uint32_t len; /* Number of elements in list. */
17081 struct guestfs_btrfsscrub *val; /* Elements. */
17082 };
17083 int guestfs_compare_btrfsscrub (const struct guestfs_btrfsscrub *, const struct guestfs_btrfsscrub *);
17085 int guestfs_compare_btrfsscrub_list (const struct guestfs_btrfsscrub_list *, const struct guestfs_btrfsscrub_list *);
17086 struct guestfs_btrfsscrub *guestfs_copy_btrfsscrub (const struct guestfs_btrfsscrub *);
17088 struct guestfs_btrfsscrub_list *guestfs_copy_btrfsscrub_list (const struct guestfs_btrfsscrub_list *);
17089 void guestfs_free_btrfsscrub (struct guestfs_btrfsscrub *);
17091 void guestfs_free_btrfsscrub_list (struct guestfs_btrfsscrub_list *);
17092 guestfs_xfsinfo
17094 struct guestfs_xfsinfo {
17095 char *xfs_mntpoint;
17096 uint32_t xfs_inodesize;
17097 uint32_t xfs_agcount;
17098 uint32_t xfs_agsize;
17099 uint32_t xfs_sectsize;
17100 uint32_t xfs_attr;
17101 uint32_t xfs_blocksize;
17102 uint64_t xfs_datablocks;
17103 uint32_t xfs_imaxpct;
17104 uint32_t xfs_sunit;
17105 uint32_t xfs_swidth;
17106 uint32_t xfs_dirversion;
17107 uint32_t xfs_dirblocksize;
17108 uint32_t xfs_cimode;
17109 char *xfs_logname;
17110 uint32_t xfs_logblocksize;
17111 uint32_t xfs_logblocks;
17112 uint32_t xfs_logversion;
17113 uint32_t xfs_logsectsize;
17114 uint32_t xfs_logsunit;
17115 uint32_t xfs_lazycount;
17116 char *xfs_rtname;
17117 uint32_t xfs_rtextsize;
17118 uint64_t xfs_rtblocks;
17119 uint64_t xfs_rtextents;
17120 };
17121 struct guestfs_xfsinfo_list {
17123 uint32_t len; /* Number of elements in list. */
17124 struct guestfs_xfsinfo *val; /* Elements. */
17125 };
17126 int guestfs_compare_xfsinfo (const struct guestfs_xfsinfo *, const struct guestfs_xfsinfo *);
17128 int guestfs_compare_xfsinfo_list (const struct guestfs_xfsinfo_list *, const struct guestfs_xfsinfo_list *);
17129 struct guestfs_xfsinfo *guestfs_copy_xfsinfo (const struct guestfs_xfsinfo *);
17131 struct guestfs_xfsinfo_list *guestfs_copy_xfsinfo_list (const struct guestfs_xfsinfo_list *);
17132 void guestfs_free_xfsinfo (struct guestfs_xfsinfo *);
17134 void guestfs_free_xfsinfo_list (struct guestfs_xfsinfo_list *);
17135 guestfs_utsname
17137 struct guestfs_utsname {
17138 char *uts_sysname;
17139 char *uts_release;
17140 char *uts_version;
17141 char *uts_machine;
17142 };
17143 struct guestfs_utsname_list {
17145 uint32_t len; /* Number of elements in list. */
17146 struct guestfs_utsname *val; /* Elements. */
17147 };
17148 int guestfs_compare_utsname (const struct guestfs_utsname *, const struct guestfs_utsname *);
17150 int guestfs_compare_utsname_list (const struct guestfs_utsname_list *, const struct guestfs_utsname_list *);
17151 struct guestfs_utsname *guestfs_copy_utsname (const struct guestfs_utsname *);
17153 struct guestfs_utsname_list *guestfs_copy_utsname_list (const struct guestfs_utsname_list *);
17154 void guestfs_free_utsname (struct guestfs_utsname *);
17156 void guestfs_free_utsname_list (struct guestfs_utsname_list *);
17157 guestfs_hivex_node
17159 struct guestfs_hivex_node {
17160 int64_t hivex_node_h;
17161 };
17162 struct guestfs_hivex_node_list {
17164 uint32_t len; /* Number of elements in list. */
17165 struct guestfs_hivex_node *val; /* Elements. */
17166 };
17167 int guestfs_compare_hivex_node (const struct guestfs_hivex_node *, const struct guestfs_hivex_node *);
17169 int guestfs_compare_hivex_node_list (const struct guestfs_hivex_node_list *, const struct guestfs_hivex_node_list *);
17170 struct guestfs_hivex_node *guestfs_copy_hivex_node (const struct guestfs_hivex_node *);
17172 struct guestfs_hivex_node_list *guestfs_copy_hivex_node_list (const struct guestfs_hivex_node_list *);
17173 void guestfs_free_hivex_node (struct guestfs_hivex_node *);
17175 void guestfs_free_hivex_node_list (struct guestfs_hivex_node_list *);
17176 guestfs_hivex_value
17178 struct guestfs_hivex_value {
17179 int64_t hivex_value_h;
17180 };
17181 struct guestfs_hivex_value_list {
17183 uint32_t len; /* Number of elements in list. */
17184 struct guestfs_hivex_value *val; /* Elements. */
17185 };
17186 int guestfs_compare_hivex_value (const struct guestfs_hivex_value *, const struct guestfs_hivex_value *);
17188 int guestfs_compare_hivex_value_list (const struct guestfs_hivex_value_list *, const struct guestfs_hivex_value_list *);
17189 struct guestfs_hivex_value *guestfs_copy_hivex_value (const struct guestfs_hivex_value *);
17191 struct guestfs_hivex_value_list *guestfs_copy_hivex_value_list (const struct guestfs_hivex_value_list *);
17192 void guestfs_free_hivex_value (struct guestfs_hivex_value *);
17194 void guestfs_free_hivex_value_list (struct guestfs_hivex_value_list *);
17195 guestfs_internal_mountable
17197 struct guestfs_internal_mountable {
17198 int32_t im_type;
17199 char *im_device;
17200 char *im_volume;
17201 };
17202 struct guestfs_internal_mountable_list {
17204 uint32_t len; /* Number of elements in list. */
17205 struct guestfs_internal_mountable *val; /* Elements. */
17206 };
17207 int guestfs_compare_internal_mountable (const struct guestfs_internal_mountable *, const struct guestfs_internal_mountable *);
17209 int guestfs_compare_internal_mountable_list (const struct guestfs_internal_mountable_list *, const struct guestfs_internal_mountable_list *);
17210 struct guestfs_internal_mountable *guestfs_copy_internal_mountable (const struct guestfs_internal_mountable *);
17212 struct guestfs_internal_mountable_list *guestfs_copy_internal_mountable_list (const struct guestfs_internal_mountable_list *);
17213 void guestfs_free_internal_mountable (struct guestfs_internal_mountable *);
17215 void guestfs_free_internal_mountable_list (struct guestfs_internal_mountable_list *);
17216 guestfs_tsk_dirent
17218 struct guestfs_tsk_dirent {
17219 uint64_t tsk_inode;
17220 char tsk_type;
17221 int64_t tsk_size;
17222 char *tsk_name;
17223 uint32_t tsk_flags;
17224 int64_t tsk_atime_sec;
17225 int64_t tsk_atime_nsec;
17226 int64_t tsk_mtime_sec;
17227 int64_t tsk_mtime_nsec;
17228 int64_t tsk_ctime_sec;
17229 int64_t tsk_ctime_nsec;
17230 int64_t tsk_crtime_sec;
17231 int64_t tsk_crtime_nsec;
17232 int64_t tsk_nlink;
17233 char *tsk_link;
17234 int64_t tsk_spare1;
17235 };
17236 struct guestfs_tsk_dirent_list {
17238 uint32_t len; /* Number of elements in list. */
17239 struct guestfs_tsk_dirent *val; /* Elements. */
17240 };
17241 int guestfs_compare_tsk_dirent (const struct guestfs_tsk_dirent *, const struct guestfs_tsk_dirent *);
17243 int guestfs_compare_tsk_dirent_list (const struct guestfs_tsk_dirent_list *, const struct guestfs_tsk_dirent_list *);
17244 struct guestfs_tsk_dirent *guestfs_copy_tsk_dirent (const struct guestfs_tsk_dirent *);
17246 struct guestfs_tsk_dirent_list *guestfs_copy_tsk_dirent_list (const struct guestfs_tsk_dirent_list *);
17247 void guestfs_free_tsk_dirent (struct guestfs_tsk_dirent *);
17249 void guestfs_free_tsk_dirent_list (struct guestfs_tsk_dirent_list *);
17250 guestfs_yara_detection
17252 struct guestfs_yara_detection {
17253 char *yara_name;
17254 char *yara_rule;
17255 };
17256 struct guestfs_yara_detection_list {
17258 uint32_t len; /* Number of elements in list. */
17259 struct guestfs_yara_detection *val; /* Elements. */
17260 };
17261 int guestfs_compare_yara_detection (const struct guestfs_yara_detection *, const struct guestfs_yara_detection *);
17263 int guestfs_compare_yara_detection_list (const struct guestfs_yara_detection_list *, const struct guestfs_yara_detection_list *);
17264 struct guestfs_yara_detection *guestfs_copy_yara_detection (const struct guestfs_yara_detection *);
17266 struct guestfs_yara_detection_list *guestfs_copy_yara_detection_list (const struct guestfs_yara_detection_list *);
17267 void guestfs_free_yara_detection (struct guestfs_yara_detection *);
17269 void guestfs_free_yara_detection_list (struct guestfs_yara_detection_list *);
17270
17272 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
17273 Using "guestfs_available" you can test availability of the following
17274 groups of functions. This test queries the appliance to see if the
17275 appliance you are currently using supports the functionality.
17276 acl The following functions: "guestfs_acl_delete_def_file"
17278 "guestfs_acl_get_file" "guestfs_acl_set_file"
17279 blkdiscard
17281 The following functions: "guestfs_blkdiscard"
17282 blkdiscardzeroes
17284 The following functions: "guestfs_blkdiscardzeroes"
17285 btrfs
17287 The following functions: "guestfs_btrfs_balance_cancel"
17288 "guestfs_btrfs_balance_pause" "guestfs_btrfs_balance_resume"
17289 "guestfs_btrfs_balance_status" "guestfs_btrfs_device_add"
17290 "guestfs_btrfs_device_delete" "guestfs_btrfs_filesystem_balance"
17291 "guestfs_btrfs_filesystem_defragment"
17292 "guestfs_btrfs_filesystem_resize" "guestfs_btrfs_filesystem_show"
17293 "guestfs_btrfs_filesystem_sync" "guestfs_btrfs_fsck"
17294 "guestfs_btrfs_image" "guestfs_btrfs_qgroup_assign"
17295 "guestfs_btrfs_qgroup_create" "guestfs_btrfs_qgroup_destroy"
17296 "guestfs_btrfs_qgroup_limit" "guestfs_btrfs_qgroup_remove"
17297 "guestfs_btrfs_qgroup_show" "guestfs_btrfs_quota_enable"
17298 "guestfs_btrfs_quota_rescan" "guestfs_btrfs_replace"
17299 "guestfs_btrfs_rescue_chunk_recover"
17300 "guestfs_btrfs_rescue_super_recover" "guestfs_btrfs_scrub_cancel"
17301 "guestfs_btrfs_scrub_resume" "guestfs_btrfs_scrub_start"
17302 "guestfs_btrfs_scrub_status" "guestfs_btrfs_set_seeding"
17303 "guestfs_btrfs_subvolume_create" "guestfs_btrfs_subvolume_delete"
17304 "guestfs_btrfs_subvolume_get_default"
17305 "guestfs_btrfs_subvolume_list"
17306 "guestfs_btrfs_subvolume_set_default"
17307 "guestfs_btrfs_subvolume_show" "guestfs_btrfs_subvolume_snapshot"
17308 "guestfs_btrfstune_enable_extended_inode_refs"
17309 "guestfs_btrfstune_enable_skinny_metadata_extent_refs"
17310 "guestfs_btrfstune_seeding" "guestfs_mkfs_btrfs"
17311 extlinux
17313 The following functions: "guestfs_extlinux"
17314 f2fs
17316 The following functions: "guestfs_f2fs_expand"
17317 fstrim
17319 The following functions: "guestfs_fstrim"
17320 gdisk
17322 The following functions: "guestfs_part_expand_gpt"
17323 "guestfs_part_get_disk_guid" "guestfs_part_get_gpt_attributes"
17324 "guestfs_part_get_gpt_guid" "guestfs_part_get_gpt_type"
17325 "guestfs_part_set_disk_guid" "guestfs_part_set_disk_guid_random"
17326 "guestfs_part_set_gpt_attributes" "guestfs_part_set_gpt_guid"
17327 "guestfs_part_set_gpt_type"
17328 grub
17330 The following functions: "guestfs_grub_install"
17331 hivex
17333 The following functions: "guestfs_hivex_close"
17334 "guestfs_hivex_commit" "guestfs_hivex_node_add_child"
17335 "guestfs_hivex_node_children" "guestfs_hivex_node_delete_child"
17336 "guestfs_hivex_node_get_child" "guestfs_hivex_node_get_value"
17337 "guestfs_hivex_node_name" "guestfs_hivex_node_parent"
17338 "guestfs_hivex_node_set_value" "guestfs_hivex_node_values"
17339 "guestfs_hivex_open" "guestfs_hivex_root" "guestfs_hivex_value_key"
17340 "guestfs_hivex_value_string" "guestfs_hivex_value_type"
17341 "guestfs_hivex_value_utf8" "guestfs_hivex_value_value"
17342 inotify
17344 The following functions: "guestfs_inotify_add_watch"
17345 "guestfs_inotify_close" "guestfs_inotify_files"
17346 "guestfs_inotify_init" "guestfs_inotify_read"
17347 "guestfs_inotify_rm_watch"
17348 journal
17350 The following functions: "guestfs_internal_journal_get"
17351 "guestfs_journal_close" "guestfs_journal_get_data_threshold"
17352 "guestfs_journal_get_realtime_usec" "guestfs_journal_next"
17353 "guestfs_journal_open" "guestfs_journal_set_data_threshold"
17354 "guestfs_journal_skip"
17355 ldm The following functions: "guestfs_ldmtool_create_all"
17357 "guestfs_ldmtool_diskgroup_disks" "guestfs_ldmtool_diskgroup_name"
17358 "guestfs_ldmtool_diskgroup_volumes" "guestfs_ldmtool_remove_all"
17359 "guestfs_ldmtool_scan" "guestfs_ldmtool_scan_devices"
17360 "guestfs_ldmtool_volume_hint" "guestfs_ldmtool_volume_partitions"
17361 "guestfs_ldmtool_volume_type" "guestfs_list_ldm_partitions"
17362 "guestfs_list_ldm_volumes"
17363 libtsk
17365 The following functions: "guestfs_internal_filesystem_walk"
17366 "guestfs_internal_find_inode"
17367 libyara
17369 The following functions: "guestfs_internal_yara_scan"
17370 "guestfs_yara_destroy" "guestfs_yara_load"
17371 linuxcaps
17373 The following functions: "guestfs_cap_get_file"
17374 "guestfs_cap_set_file"
17375 linuxfsuuid
17377 The following functions: "guestfs_mke2fs_JU"
17378 "guestfs_mke2journal_U" "guestfs_mkswap_U" "guestfs_swapoff_uuid"
17379 "guestfs_swapon_uuid"
17380 linuxmodules
17382 The following functions: "guestfs_modprobe"
17383 linuxxattrs
17385 The following functions: "guestfs_getxattr" "guestfs_getxattrs"
17386 "guestfs_internal_lxattrlist" "guestfs_lgetxattr"
17387 "guestfs_lgetxattrs" "guestfs_lremovexattr" "guestfs_lsetxattr"
17388 "guestfs_removexattr" "guestfs_setxattr"
17389 luks
17391 The following functions: "guestfs_luks_add_key"
17392 "guestfs_luks_close" "guestfs_luks_format"
17393 "guestfs_luks_format_cipher" "guestfs_luks_kill_slot"
17394 "guestfs_luks_open" "guestfs_luks_open_ro"
17395 lvm2
17397 The following functions: "guestfs_lvcreate" "guestfs_lvcreate_free"
17398 "guestfs_lvm_remove_all" "guestfs_lvm_set_filter"
17399 "guestfs_lvremove" "guestfs_lvresize" "guestfs_lvresize_free"
17400 "guestfs_lvs" "guestfs_lvs_full" "guestfs_pvchange_uuid"
17401 "guestfs_pvchange_uuid_all" "guestfs_pvcreate" "guestfs_pvremove"
17402 "guestfs_pvresize" "guestfs_pvresize_size" "guestfs_pvs"
17403 "guestfs_pvs_full" "guestfs_vg_activate" "guestfs_vg_activate_all"
17404 "guestfs_vgchange_uuid" "guestfs_vgchange_uuid_all"
17405 "guestfs_vgcreate" "guestfs_vgmeta" "guestfs_vgremove"
17406 "guestfs_vgs" "guestfs_vgs_full"
17407 mdadm
17409 The following functions: "guestfs_md_create" "guestfs_md_detail"
17410 "guestfs_md_stat" "guestfs_md_stop"
17411 mknod
17413 The following functions: "guestfs_mkfifo" "guestfs_mknod"
17414 "guestfs_mknod_b" "guestfs_mknod_c"
17415 ntfs3g
17417 The following functions: "guestfs_ntfs_3g_probe"
17418 "guestfs_ntfsclone_in" "guestfs_ntfsclone_out" "guestfs_ntfsfix"
17419 ntfsprogs
17421 The following functions: "guestfs_ntfsresize"
17422 "guestfs_ntfsresize_size"
17423 rsync
17425 The following functions: "guestfs_rsync" "guestfs_rsync_in"
17426 "guestfs_rsync_out"
17427 scrub
17429 The following functions: "guestfs_scrub_device"
17430 "guestfs_scrub_file" "guestfs_scrub_freespace"
17431 selinux
17433 The following functions: "guestfs_getcon" "guestfs_setcon"
17434 selinuxrelabel
17436 The following functions: "guestfs_selinux_relabel"
17437 sleuthkit
17439 The following functions: "guestfs_download_blocks"
17440 "guestfs_download_inode"
17441 squashfs
17443 The following functions: "guestfs_mksquashfs"
17444 syslinux
17446 The following functions: "guestfs_syslinux"
17447 wipefs
17449 The following functions: "guestfs_wipefs"
17450 xfs The following functions: "guestfs_xfs_admin" "guestfs_xfs_growfs"
17452 "guestfs_xfs_info" "guestfs_xfs_repair"
17453 xz The following functions: "guestfs_txz_in" "guestfs_txz_out"
17455 zerofree
17457 The following functions: "guestfs_zerofree"
17458 FILESYSTEM AVAILABLE
17460 The "guestfs_filesystem_available" call tests whether a filesystem type
17461 is supported by the appliance kernel.
17462 This is mainly useful as a negative test. If this returns true, it
17464 doesn't mean that a particular filesystem can be mounted, since
17465 filesystems can fail for other reasons such as it being a later version
17466 of the filesystem, or having incompatible features.
17467 GUESTFISH supported COMMAND
17469 In guestfish(3) there is a handy interactive command "supported" which
17470 prints out the available groups and whether they are supported by this
17471 build of libguestfs. Note however that you have to do "run" first.
17472 SINGLE CALLS AT COMPILE TIME
17474 Since version 1.5.8, "<guestfs.h>" defines symbols for each C API
17475 function, such as:
17476 #define GUESTFS_HAVE_DD 1
17478 if "guestfs_dd" is available.
17480 Before version 1.5.8, if you needed to test whether a single libguestfs
17482 function is available at compile time, we recommended using build tools
17483 such as autoconf or cmake. For example in autotools you could use:
17484 AC_CHECK_LIB([guestfs],[guestfs_create])
17486 AC_CHECK_FUNCS([guestfs_dd])
17487 which would result in "HAVE_GUESTFS_DD" being either defined or not
17489 defined in your program.
17490 SINGLE CALLS AT RUN TIME
17492 Testing at compile time doesn't guarantee that a function really exists
17493 in the library. The reason is that you might be dynamically linked
17494 against a previous libguestfs.so (dynamic library) which doesn't have
17495 the call. This situation unfortunately results in a segmentation
17496 fault, which is a shortcoming of the C dynamic linking system itself.
17497 You can use dlopen(3) to test if a function is available at run time,
17499 as in this example program (note that you still need the compile time
17500 check as well):
17501 #include <stdio.h>
17503 #include <stdlib.h>
17504 #include <unistd.h>
17505 #include <dlfcn.h>
17506 #include <guestfs.h>
17507 main ()
17509 {
17510 #ifdef GUESTFS_HAVE_DD
17511 void *dl;
17512 int has_function;
17513 /* Test if the function guestfs_dd is really available. */
17515 dl = dlopen (NULL, RTLD_LAZY);
17516 if (!dl) {
17517 fprintf (stderr, "dlopen: %s\n", dlerror ());
17518 exit (EXIT_FAILURE);
17519 }
17520 has_function = dlsym (dl, "guestfs_dd") != NULL;
17521 dlclose (dl);
17522 if (!has_function)
17524 printf ("this libguestfs.so does NOT have guestfs_dd function\n");
17525 else {
17526 printf ("this libguestfs.so has guestfs_dd function\n");
17527 /* Now it's safe to call
17528 guestfs_dd (g, "foo", "bar");
17529 */
17530 }
17531 #else
17532 printf ("guestfs_dd function was not found at compile time\n");
17533 #endif
17534 }
17535 You may think the above is an awful lot of hassle, and it is. There
17537 are other ways outside of the C linking system to ensure that this kind
17538 of incompatibility never arises, such as using package versioning:
17539 Requires: libguestfs >= 1.0.80
17541
17543 A recent feature of the API is the introduction of calls which take
17544 optional arguments. In C these are declared 3 ways. The main way is
17545 as a call which takes variable arguments (ie. "..."), as in this
17546 example:
17547 int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
17549 Call this with a list of optional arguments, terminated by "-1". So to
17551 call with no optional arguments specified:
17552 guestfs_add_drive_opts (g, filename, -1);
17554 With a single optional argument:
17556 guestfs_add_drive_opts (g, filename,
17558 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17559 -1);
17560 With two:
17562 guestfs_add_drive_opts (g, filename,
17564 GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
17565 GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
17566 -1);
17567 and so forth. Don’t forget the terminating "-1" otherwise Bad Things
17569 will happen!
17570 USING va_list FOR OPTIONAL ARGUMENTS
17572 The second variant has the same name with the suffix "_va", which works
17573 the same way but takes a "va_list". See the C manual for details. For
17574 the example function, this is declared:
17575 int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
17577 va_list args);
17578 CONSTRUCTING OPTIONAL ARGUMENTS
17580 The third variant is useful where you need to construct these calls.
17581 You pass in a structure where you fill in the optional fields. The
17582 structure has a bitmask as the first element which you must set to
17583 indicate which fields you have filled in. For our example function the
17584 structure and call are declared:
17585 struct guestfs_add_drive_opts_argv {
17587 uint64_t bitmask;
17588 int readonly;
17589 const char *format;
17590 /* ... */
17591 };
17592 int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
17593 const struct guestfs_add_drive_opts_argv *optargs);
17594 You could call it like this:
17596 struct guestfs_add_drive_opts_argv optargs = {
17598 .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
17599 GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
17600 .readonly = 1,
17601 .format = "qcow2"
17602 };
17603 guestfs_add_drive_opts_argv (g, filename, &optargs);
17605 Notes:
17607 · The "_BITMASK" suffix on each option name when specifying the
17609 bitmask.
17610 · You do not need to fill in all fields of the structure.
17612 · There must be a one-to-one correspondence between fields of the
17614 structure that are filled in, and bits set in the bitmask.
17615 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
17617 In other languages, optional arguments are expressed in the way that is
17618 natural for that language. We refer you to the language-specific
17619 documentation for more details on that.
17620 For guestfish, see "OPTIONAL ARGUMENTS" in guestfish(1).
17622
17624 SETTING CALLBACKS TO HANDLE EVENTS
17625 Note: This section documents the generic event mechanism introduced in
17626 libguestfs 1.10, which you should use in new code if possible. The old
17627 functions "guestfs_set_log_message_callback",
17628 "guestfs_set_subprocess_quit_callback",
17629 "guestfs_set_launch_done_callback", "guestfs_set_close_callback" and
17630 "guestfs_set_progress_callback" are no longer documented in this manual
17631 page. Because of the ABI guarantee, the old functions continue to
17632 work.
17633 Handles generate events when certain things happen, such as log
17635 messages being generated, progress messages during long-running
17636 operations, or the handle being closed. The API calls described below
17637 let you register a callback to be called when events happen. You can
17638 register multiple callbacks (for the same, different or overlapping
17639 sets of events), and individually remove callbacks. If callbacks are
17640 not removed, then they remain in force until the handle is closed.
17641 In the current implementation, events are only generated synchronously:
17643 that means that events (and hence callbacks) can only happen while you
17644 are in the middle of making another libguestfs call. The callback is
17645 called in the same thread.
17646 Events may contain a payload, usually nothing (void), an array of 64
17648 bit unsigned integers, or a message buffer. Payloads are discussed
17649 later on.
17650 CLASSES OF EVENTS
17652 GUESTFS_EVENT_CLOSE (payload type: void)
17653 The callback function will be called while the handle is being
17654 closed (synchronously from "guestfs_close").
17655 Note that libguestfs installs an atexit(3) handler to try to clean
17657 up handles that are open when the program exits. This means that
17658 this callback might be called indirectly from exit(3), which can
17659 cause unexpected problems in higher-level languages (eg. if your
17660 HLL interpreter has already been cleaned up by the time this is
17661 called, and if your callback then jumps into some HLL function).
17662 If no callback is registered: the handle is closed without any
17664 callback being invoked.
17665 GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
17667 The callback function will be called when the child process quits,
17668 either asynchronously or if killed by "guestfs_kill_subprocess".
17669 (This corresponds to a transition from any state to the CONFIG
17670 state).
17671 If no callback is registered: the event is ignored.
17673 GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
17675 The callback function will be called when the child process becomes
17676 ready first time after it has been launched. (This corresponds to
17677 a transition from LAUNCHING to the READY state).
17678 If no callback is registered: the event is ignored.
17680 GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
17682 Some long-running operations can generate progress messages. If
17683 this callback is registered, then it will be called each time a
17684 progress message is generated (usually two seconds after the
17685 operation started, and three times per second thereafter until it
17686 completes, although the frequency may change in future versions).
17687 The callback receives in the payload four unsigned 64 bit numbers
17689 which are (in order): "proc_nr", "serial", "position", "total".
17690 The units of "total" are not defined, although for some operations
17692 "total" may relate in some way to the amount of data to be
17693 transferred (eg. in bytes or megabytes), and "position" may be the
17694 portion which has been transferred.
17695 The only defined and stable parts of the API are:
17697 · The callback can display to the user some type of progress bar
17699 or indicator which shows the ratio of "position":"total".
17700 · 0 <= "position" <= "total"
17702 · If any progress notification is sent during a call, then a
17704 final progress notification is always sent when "position" =
17705 "total" (unless the call fails with an error).
17706 This is to simplify caller code, so callers can easily set the
17708 progress indicator to "100%" at the end of the operation,
17709 without requiring special code to detect this case.
17710 · For some calls we are unable to estimate the progress of the
17712 call, but we can still generate progress messages to indicate
17713 activity. This is known as "pulse mode", and is directly
17714 supported by certain progress bar implementations (eg.
17715 GtkProgressBar).
17716 For these calls, zero or more progress messages are generated
17718 with "position = 0" and "total = 1", followed by a final
17719 message with "position = total = 1".
17720 As noted above, if the call fails with an error then the final
17722 message may not be generated.
17723 The callback also receives the procedure number ("proc_nr") and
17725 serial number ("serial") of the call. These are only useful for
17726 debugging protocol issues, and the callback can normally ignore
17727 them. The callback may want to print these numbers in error
17728 messages or debugging messages.
17729 If no callback is registered: progress messages are discarded.
17731 GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
17733 The callback function is called whenever a log message is generated
17734 by qemu, the appliance kernel, guestfsd (daemon), or utility
17735 programs.
17736 If the verbose flag ("guestfs_set_verbose") is set before launch
17738 ("guestfs_launch") then additional debug messages are generated.
17739 If no callback is registered: the messages are discarded unless the
17741 verbose flag is set in which case they are sent to stderr. You can
17742 override the printing of verbose messages to stderr by setting up a
17743 callback.
17744 GUESTFS_EVENT_LIBRARY (payload type: message buffer)
17746 The callback function is called whenever a log message is generated
17747 by the library part of libguestfs.
17748 If the verbose flag ("guestfs_set_verbose") is set then additional
17750 debug messages are generated.
17751 If no callback is registered: the messages are discarded unless the
17753 verbose flag is set in which case they are sent to stderr. You can
17754 override the printing of verbose messages to stderr by setting up a
17755 callback.
17756 GUESTFS_EVENT_WARNING (payload type: message buffer)
17758 The callback function is called whenever a warning message is
17759 generated by the library part of libguestfs.
17760 If no callback is registered: the messages are printed to stderr.
17762 You can override the printing of warning messages to stderr by
17763 setting up a callback.
17764 GUESTFS_EVENT_TRACE (payload type: message buffer)
17766 The callback function is called whenever a trace message is
17767 generated. This only applies if the trace flag
17768 ("guestfs_set_trace") is set.
17769 If no callback is registered: the messages are sent to stderr. You
17771 can override the printing of trace messages to stderr by setting up
17772 a callback.
17773 GUESTFS_EVENT_ENTER (payload type: function name)
17775 The callback function is called whenever a libguestfs function is
17776 entered.
17777 The payload is a string which contains the name of the function
17779 that we are entering (not including "guestfs_" prefix).
17780 Note that libguestfs functions can call themselves, so you may see
17782 many events from a single call. A few libguestfs functions do not
17783 generate this event.
17784 If no callback is registered: the event is ignored.
17786 GUESTFS_EVENT_LIBVIRT_AUTH (payload type: libvirt URI)
17788 For any API function that opens a libvirt connection, this event
17789 may be generated to indicate that libvirt demands authentication
17790 information. See "LIBVIRT AUTHENTICATION" below.
17791 If no callback is registered: "virConnectAuthPtrDefault" is used
17793 (suitable for command-line programs only).
17794 EVENT API
17796 guestfs_set_event_callback
17797 int guestfs_set_event_callback (guestfs_h *g,
17799 guestfs_event_callback cb,
17800 uint64_t event_bitmask,
17801 int flags,
17802 void *opaque);
17803 This function registers a callback ("cb") for all event classes in the
17805 "event_bitmask".
17806 For example, to register for all log message events, you could call
17808 this function with the bitmask
17809 "GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_WARNING".
17810 To register a single callback for all possible classes of events, use
17811 "GUESTFS_EVENT_ALL".
17812 "flags" should always be passed as 0.
17814 "opaque" is an opaque pointer which is passed to the callback. You can
17816 use it for any purpose.
17817 The return value is the event handle (an integer) which you can use to
17819 delete the callback (see below).
17820 If there is an error, this function returns "-1", and sets the error in
17822 the handle in the usual way (see "guestfs_last_error" etc.)
17823 Callbacks remain in effect until they are deleted, or until the handle
17825 is closed.
17826 In the case where multiple callbacks are registered for a particular
17828 event class, all of the callbacks are called. The order in which
17829 multiple callbacks are called is not defined.
17830 guestfs_delete_event_callback
17832 void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
17834 Delete a callback that was previously registered. "event_handle"
17836 should be the integer that was returned by a previous call to
17837 "guestfs_set_event_callback" on the same handle.
17838 guestfs_event_to_string
17840 char *guestfs_event_to_string (uint64_t event);
17842 "event" is either a single event or a bitmask of events. This returns
17844 a string representation (useful for debugging or printing events).
17845 A single event is returned as the name in lower case, eg. "close".
17847 A bitmask of several events is returned as a comma-separated list, eg.
17849 "close,progress".
17850 If zero is passed, then the empty string "" is returned.
17852 On success this returns a string. On error it returns NULL and sets
17854 "errno".
17855 The returned string must be freed by the caller.
17857 guestfs_event_callback
17859 typedef void (*guestfs_event_callback) (
17861 guestfs_h *g,
17862 void *opaque,
17863 uint64_t event,
17864 int event_handle,
17865 int flags,
17866 const char *buf, size_t buf_len,
17867 const uint64_t *array, size_t array_len);
17868 This is the type of the event callback function that you have to
17870 provide.
17871 The basic parameters are: the handle ("g"), the opaque user pointer
17873 ("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the event
17874 handle, and "flags" which in the current API you should ignore.
17875 The remaining parameters contain the event payload (if any). Each
17877 event may contain a payload, which usually relates to the event class,
17878 but for future proofing your code should be written to handle any
17879 payload for any event class.
17880 "buf" and "buf_len" contain a message buffer (if "buf_len == 0", then
17882 there is no message buffer). Note that this message buffer can contain
17883 arbitrary 8 bit data, including NUL bytes.
17884 "array" and "array_len" is an array of 64 bit unsigned integers. At
17886 the moment this is only used for progress messages.
17887 EXAMPLE: CAPTURING LOG MESSAGES
17889 A working program demonstrating this can be found in
17890 examples/debug-logging.c in the source of libguestfs.
17891 One motivation for the generic event API was to allow GUI programs to
17893 capture debug and other messages. In libguestfs ≤ 1.8 these were sent
17894 unconditionally to "stderr".
17895 Events associated with log messages are: "GUESTFS_EVENT_LIBRARY",
17897 "GUESTFS_EVENT_APPLIANCE", "GUESTFS_EVENT_WARNING" and
17898 "GUESTFS_EVENT_TRACE". (Note that error messages are not events; you
17899 must capture error messages separately).
17900 Programs have to set up a callback to capture the classes of events of
17902 interest:
17903 int eh =
17905 guestfs_set_event_callback
17906 (g, message_callback,
17907 GUESTFS_EVENT_LIBRARY | GUESTFS_EVENT_APPLIANCE |
17908 GUESTFS_EVENT_WARNING | GUESTFS_EVENT_TRACE,
17909 0, NULL) == -1)
17910 if (eh == -1) {
17911 // handle error in the usual way
17912 }
17913 The callback can then direct messages to the appropriate place. In
17915 this example, messages are directed to syslog:
17916 static void
17918 message_callback (
17919 guestfs_h *g,
17920 void *opaque,
17921 uint64_t event,
17922 int event_handle,
17923 int flags,
17924 const char *buf, size_t buf_len,
17925 const uint64_t *array, size_t array_len)
17926 {
17927 const int priority = LOG_USER|LOG_INFO;
17928 if (buf_len > 0)
17929 syslog (priority, "event 0x%lx: %s", event, buf);
17930 }
17931 LIBVIRT AUTHENTICATION
17933 Some libguestfs API calls can open libvirt connections. Currently the
17934 only ones are "guestfs_add_domain"; and "guestfs_launch" if the libvirt
17935 backend has been selected. Libvirt connections may require
17936 authentication, for example if they need to access a remote server or
17937 to access root services from non-root. Libvirt authentication happens
17938 via a callback mechanism, see
17939 http://libvirt.org/guide/html/Application_Development_Guide-Connections.html
17940 You may provide libvirt authentication data by registering a callback
17942 for events of type "GUESTFS_EVENT_LIBVIRT_AUTH".
17943 If no such event is registered, then libguestfs uses a libvirt function
17945 that provides command-line prompts ("virConnectAuthPtrDefault"). This
17946 is only suitable for command-line libguestfs programs.
17947 To provide authentication, first call
17949 "guestfs_set_libvirt_supported_credentials" with the list of
17950 credentials your program knows how to provide. Second, register a
17951 callback for the "GUESTFS_EVENT_LIBVIRT_AUTH" event. The event handler
17952 will be called when libvirt is requesting authentication information.
17953 In the event handler, call "guestfs_get_libvirt_requested_credentials"
17955 to get a list of the credentials that libvirt is asking for. You then
17956 need to ask (eg. the user) for each credential, and call
17957 "guestfs_set_libvirt_requested_credential" with the answer. Note that
17958 for each credential, additional information may be available via the
17959 calls "guestfs_get_libvirt_requested_credential_prompt",
17960 "guestfs_get_libvirt_requested_credential_challenge" or
17961 "guestfs_get_libvirt_requested_credential_defresult".
17962 The example program below should make this clearer.
17964 There is also a more substantial working example program supplied with
17966 the libguestfs sources, called libvirt-auth.c.
17967 main ()
17969 {
17970 guestfs_h *g;
17971 char *creds[] = { "authname", "passphrase", NULL };
17972 int r, eh;
17973 g = guestfs_create ();
17975 if (!g) exit (EXIT_FAILURE);
17976 /* Tell libvirt what credentials the program supports. */
17978 r = guestfs_set_libvirt_supported_credentials (g, creds);
17979 if (r == -1)
17980 exit (EXIT_FAILURE);
17981 /* Set up the event handler. */
17983 eh = guestfs_set_event_callback (
17984 g, do_auth,
17985 GUESTFS_EVENT_LIBVIRT_AUTH, 0, NULL);
17986 if (eh == -1)
17987 exit (EXIT_FAILURE);
17988 /* An example of a call that may ask for credentials. */
17990 r = guestfs_add_domain (
17991 g, "dom",
17992 GUESTFS_ADD_DOMAIN_LIBVIRTURI, "qemu:///system",
17993 -1);
17994 if (r == -1)
17995 exit (EXIT_FAILURE);
17996 exit (EXIT_SUCCESS);
17998 }
17999 static void
18001 do_auth (guestfs_h *g,
18002 void *opaque,
18003 uint64_t event,
18004 int event_handle,
18005 int flags,
18006 const char *buf, size_t buf_len,
18007 const uint64_t *array, size_t array_len)
18008 {
18009 char **creds;
18010 size_t i;
18011 char *prompt;
18012 char *reply;
18013 size_t replylen;
18014 int r;
18015 // buf will be the libvirt URI. buf_len may be ignored.
18017 printf ("Authentication required for libvirt conn '%s'\n",
18018 buf);
18019 // Ask libguestfs what credentials libvirt is demanding.
18021 creds = guestfs_get_libvirt_requested_credentials (g);
18022 if (creds == NULL)
18023 exit (EXIT_FAILURE);
18024 // Now ask the user for answers.
18026 for (i = 0; creds[i] != NULL; ++i)
18027 {
18028 if (strcmp (creds[i], "authname") == 0 ||
18029 strcmp (creds[i], "passphrase") == 0)
18030 {
18031 prompt =
18032 guestfs_get_libvirt_requested_credential_prompt (g, i);
18033 if (prompt && strcmp (prompt, "") != 0)
18034 printf ("%s: ", prompt);
18035 free (prompt);
18036 // Some code here to ask for the credential.
18038 // ...
18039 // Put the reply in 'reply', length 'replylen' (bytes).
18040 r = guestfs_set_libvirt_requested_credential (g, i,
18042 reply, replylen);
18043 if (r == -1)
18044 exit (EXIT_FAILURE);
18045 }
18046 free (creds[i]);
18048 }
18049 free (creds);
18051 }
18052
18054 Some operations can be cancelled by the caller while they are in
18055 progress. Currently only operations that involve uploading or
18056 downloading data can be cancelled (technically: operations that have
18057 "FileIn" or "FileOut" parameters in the generator).
18058 To cancel the transfer, call "guestfs_user_cancel". For more
18060 information, read the description of "guestfs_user_cancel".
18061
18063 You can attach named pieces of private data to the libguestfs handle,
18064 fetch them by name, and walk over them, for the lifetime of the handle.
18065 This is called the private data area and is only available from the C
18066 API.
18067 To attach a named piece of data, use the following call:
18069 void guestfs_set_private (guestfs_h *g, const char *key, void *data);
18071 "key" is the name to associate with this data, and "data" is an
18073 arbitrary pointer (which can be "NULL"). Any previous item with the
18074 same key is overwritten.
18075 You can use any "key" string you want, but avoid keys beginning with an
18077 underscore character (libguestfs uses those for its own internal
18078 purposes, such as implementing language bindings). It is recommended
18079 that you prefix the key with some unique string to avoid collisions
18080 with other users.
18081 To retrieve the pointer, use:
18083 void *guestfs_get_private (guestfs_h *g, const char *key);
18085 This function returns "NULL" if either no data is found associated with
18087 "key", or if the user previously set the "key"’s "data" pointer to
18088 "NULL".
18089 Libguestfs does not try to look at or interpret the "data" pointer in
18091 any way. As far as libguestfs is concerned, it need not be a valid
18092 pointer at all. In particular, libguestfs does not try to free the
18093 data when the handle is closed. If the data must be freed, then the
18094 caller must either free it before calling "guestfs_close" or must set
18095 up a close callback to do it (see "GUESTFS_EVENT_CLOSE").
18096 To walk over all entries, use these two functions:
18098 void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
18100 void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
18102 "guestfs_first_private" returns the first key, pointer pair ("first"
18104 does not have any particular meaning -- keys are not returned in any
18105 defined order). A pointer to the key is returned in *key_rtn and the
18106 corresponding data pointer is returned from the function. "NULL" is
18107 returned if there are no keys stored in the handle.
18108 "guestfs_next_private" returns the next key, pointer pair. The return
18110 value of this function is "NULL" if there are no further entries to
18111 return.
18112 Notes about walking over entries:
18114 · You must not call "guestfs_set_private" while walking over the
18116 entries.
18117 · The handle maintains an internal iterator which is reset when you
18119 call "guestfs_first_private". This internal iterator is
18120 invalidated when you call "guestfs_set_private".
18121 · If you have set the data pointer associated with a key to "NULL",
18123 ie:
18124 guestfs_set_private (g, key, NULL);
18126 then that "key" is not returned when walking.
18128 · *key_rtn is only valid until the next call to
18130 "guestfs_first_private", "guestfs_next_private" or
18131 "guestfs_set_private".
18132 The following example code shows how to print all keys and data
18134 pointers that are associated with the handle "g":
18135 const char *key;
18137 void *data = guestfs_first_private (g, &key);
18138 while (data != NULL)
18139 {
18140 printf ("key = %s, data = %p\n", key, data);
18141 data = guestfs_next_private (g, &key);
18142 }
18143 More commonly you are only interested in keys that begin with an
18145 application-specific prefix "foo_". Modify the loop like so:
18146 const char *key;
18148 void *data = guestfs_first_private (g, &key);
18149 while (data != NULL)
18150 {
18151 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18152 printf ("key = %s, data = %p\n", key, data);
18153 data = guestfs_next_private (g, &key);
18154 }
18155 If you need to modify keys while walking, then you have to jump back to
18157 the beginning of the loop. For example, to delete all keys prefixed
18158 with "foo_":
18159 const char *key;
18161 void *data;
18162 again:
18163 data = guestfs_first_private (g, &key);
18164 while (data != NULL)
18165 {
18166 if (strncmp (key, "foo_", strlen ("foo_")) == 0)
18167 {
18168 guestfs_set_private (g, key, NULL);
18169 /* note that 'key' pointer is now invalid, and so is
18170 the internal iterator */
18171 goto again;
18172 }
18173 data = guestfs_next_private (g, &key);
18174 }
18175 Note that the above loop is guaranteed to terminate because the keys
18177 are being deleted, but other manipulations of keys within the loop
18178 might not terminate unless you also maintain an indication of which
18179 keys have been visited.
18180
18182 The libguestfs C library can be probed using systemtap or DTrace. This
18183 is true of any library, not just libguestfs. However libguestfs also
18184 contains static markers to help in probing internal operations.
18185 You can list all the static markers by doing:
18187 stap -l 'process("/usr/lib*/libguestfs.so.0")
18189 .provider("guestfs").mark("*")'
18190 Note: These static markers are not part of the stable API and may
18192 change in future versions.
18193 SYSTEMTAP SCRIPT EXAMPLE
18195 This script contains examples of displaying both the static markers and
18196 some ordinary C entry points:
18197 global last;
18199 function display_time () {
18201 now = gettimeofday_us ();
18202 delta = 0;
18203 if (last > 0)
18204 delta = now - last;
18205 last = now;
18206 printf ("%d (+%d):", now, delta);
18208 }
18209 probe begin {
18211 last = 0;
18212 printf ("ready\n");
18213 }
18214 /* Display all calls to static markers. */
18216 probe process("/usr/lib*/libguestfs.so.0")
18217 .provider("guestfs").mark("*") ? {
18218 display_time();
18219 printf ("\t%s %s\n", $$name, $$parms);
18220 }
18221 /* Display all calls to guestfs_mkfs* functions. */
18223 probe process("/usr/lib*/libguestfs.so.0")
18224 .function("guestfs_mkfs*") ? {
18225 display_time();
18226 printf ("\t%s %s\n", probefunc(), $$parms);
18227 }
18228 The script above can be saved to test.stap and run using the stap(1)
18230 program. Note that you either have to be root, or you have to add
18231 yourself to several special stap groups. Consult the systemtap
18232 documentation for more information.
18233 # stap /tmp/test.stap
18235 ready
18236 In another terminal, run a guestfish command such as this:
18238 guestfish -N fs
18240 In the first terminal, stap trace output similar to this is shown:
18242 1318248056692655 (+0): launch_start
18244 1318248056692850 (+195): launch_build_appliance_start
18245 1318248056818285 (+125435): launch_build_appliance_end
18246 1318248056838059 (+19774): launch_run_qemu
18247 1318248061071167 (+4233108): launch_end
18248 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
18249
18251 Since April 2010, libguestfs has started to make separate development
18252 and stable releases, along with corresponding branches in our git
18253 repository. These separate releases can be identified by version
18254 number:
18255 even numbers for stable: 1.2.x, 1.4.x, ...
18257 .-------- odd numbers for development: 1.3.x, 1.5.x, ...
18258 |
18259 v
18260 1 . 3 . 5
18261 ^ ^
18262 | |
18263 | `-------- sub-version
18264 |
18265 `------ always '1' because we don't change the ABI
18266 Thus "1.3.5" is the 5th update to the development branch "1.3".
18268 As time passes we cherry pick fixes from the development branch and
18270 backport those into the stable branch, the effect being that the stable
18271 branch should get more stable and less buggy over time. So the stable
18272 releases are ideal for people who don't need new features but would
18273 just like the software to work.
18274 Our criteria for backporting changes are:
18276 · Documentation changes which don’t affect any code are backported
18278 unless the documentation refers to a future feature which is not in
18279 stable.
18280 · Bug fixes which are not controversial, fix obvious problems, and
18282 have been well tested are backported.
18283 · Simple rearrangements of code which shouldn't affect how it works
18285 get backported. This is so that the code in the two branches
18286 doesn't get too far out of step, allowing us to backport future
18287 fixes more easily.
18288 · We don’t backport new features, new APIs, new tools etc, except in
18290 one exceptional case: the new feature is required in order to
18291 implement an important bug fix.
18292 A new stable branch starts when we think the new features in
18294 development are substantial and compelling enough over the current
18295 stable branch to warrant it. When that happens we create new stable
18296 and development versions 1.N.0 and 1.(N+1).0 [N is even]. The new dot-
18297 oh release won't necessarily be so stable at this point, but by
18298 backporting fixes from development, that branch will stabilize over
18299 time.
18300
18302 PROTOCOL LIMITS
18303 Internally libguestfs uses a message-based protocol to pass API calls
18304 and their responses to and from a small "appliance" (see
18305 guestfs-internals(1) for plenty more detail about this). The maximum
18306 message size used by the protocol is slightly less than 4 MB. For some
18307 API calls you may need to be aware of this limit. The API calls which
18308 may be affected are individually documented, with a link back to this
18309 section of the documentation.
18310 In libguestfs < 1.19.32, several calls had to encode either their
18312 entire argument list or their entire return value (or sometimes both)
18313 in a single protocol message, and this gave them an arbitrary
18314 limitation on how much data they could handle. For example,
18315 "guestfs_cat" could only download a file if it was less than around 4
18316 MB in size. In later versions of libguestfs, some of these limits have
18317 been removed. The APIs which were previously limited but are now
18318 unlimited (except perhaps by available memory) are listed below. To
18319 find out if a specific API is subject to protocol limits, check for the
18320 warning in the API documentation which links to this section, and
18321 remember to check the version of the documentation that matches the
18322 version of libguestfs you are using.
18323 "guestfs_cat", "guestfs_find", "guestfs_read_file",
18325 "guestfs_read_lines", "guestfs_write", "guestfs_write_append",
18326 "guestfs_lstatlist", "guestfs_lxattrlist", "guestfs_readlinklist",
18327 "guestfs_ls".
18328 See also "UPLOADING" and "DOWNLOADING" for further information about
18330 copying large amounts of data into or out of a filesystem.
18331 MAXIMUM NUMBER OF DISKS
18333 In libguestfs ≥ 1.19.7, you can query the maximum number of disks that
18334 may be added by calling "guestfs_max_disks". In earlier versions of
18335 libguestfs (ie. where this call is not available) you should assume the
18336 maximum is 25.
18337 The rest of this section covers implementation details, which could
18339 change in future.
18340 When using virtio-scsi disks (the default if available in qemu) the
18342 current limit is 255 disks. When using virtio-blk (the old default)
18343 the limit is around 27 disks, but may vary according to implementation
18344 details and whether the network is enabled.
18345 Virtio-scsi as used by libguestfs is configured to use one target per
18347 disk, and 256 targets are available.
18348 Virtio-blk consumes 1 virtual PCI slot per disk, and PCI is limited to
18350 31 slots, but some of these are used for other purposes.
18351 One virtual disk is used by libguestfs internally.
18353 Before libguestfs 1.19.7, disk names had to be a single character (eg.
18355 /dev/sda through /dev/sdz), and since one disk is reserved, that meant
18356 the limit was 25. This has been fixed in more recent versions.
18357 In libguestfs ≥ 1.20 it is possible to hot plug disks. See
18359 "HOTPLUGGING".
18360 MAXIMUM NUMBER OF PARTITIONS PER DISK
18362 Virtio limits the maximum number of partitions per disk to 15.
18363 This is because it reserves 4 bits for the minor device number (thus
18365 /dev/vda, and /dev/vda1 through /dev/vda15).
18366 If you attach a disk with more than 15 partitions, the extra partitions
18368 are ignored by libguestfs.
18369 MAXIMUM SIZE OF A DISK
18371 Probably the limit is between 2**63-1 and 2**64-1 bytes.
18372 We have tested block devices up to 1 exabyte (2**60 or
18374 1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
18375 host filesystem.
18376 Although libguestfs probably does not impose any limit, the underlying
18378 host storage will. If you store disk images on a host ext4 filesystem,
18379 then the maximum size will be limited by the maximum ext4 file size
18380 (currently 16 TB). If you store disk images as host logical volumes
18381 then you are limited by the maximum size of an LV.
18382 For the hugest disk image files, we recommend using XFS on the host for
18384 storage.
18385 MAXIMUM SIZE OF A PARTITION
18387 The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
18388 numbers. Assuming a 512 byte sector size, this means that MBR cannot
18389 address a partition located beyond 2 TB on the disk.
18390 It is recommended that you use GPT partitions on disks which are larger
18392 than this size. GPT uses 64 bit sector numbers and so can address
18393 partitions which are theoretically larger than the largest disk we
18394 could support.
18395 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
18397 This depends on the filesystem type. libguestfs itself does not impose
18398 any known limit. Consult Wikipedia or the filesystem documentation to
18399 find out what these limits are.
18400 MAXIMUM UPLOAD AND DOWNLOAD
18402 The API functions "guestfs_upload", "guestfs_download",
18403 "guestfs_tar_in", "guestfs_tar_out" and the like allow unlimited sized
18404 uploads and downloads.
18405 INSPECTION LIMITS
18407 The inspection code has several arbitrary limits on things like the
18408 size of Windows Registry hive it will read, and the length of product
18409 name. These are intended to stop a malicious guest from consuming
18410 arbitrary amounts of memory and disk space on the host, and should not
18411 be reached in practice. See the source code for more information.
18412
18414 Some of the tools support a --machine-readable option, which is
18415 generally used to make the output more machine friendly, for easier
18416 parsing for example. By default, this output goes to stdout.
18417 In addition to that, a subset of these tools support an extra string
18419 passed to the --machine-readable option: this string specifies where
18420 the machine-readable output will go.
18421 The possible values are:
18423 file:filename
18425 The output goes to the specified filename.
18426 stream:stdout
18428 The output goes to stdout. This is basically the same as the
18429 default behaviour of --machine-readable with no parameter, although
18430 stdout as output is specified explicitly.
18431 stream:stderr
18433 The output goes to stderr.
18434
18436 LIBGUESTFS_APPEND
18437 Pass additional options to the guest kernel.
18438 LIBGUESTFS_ATTACH_METHOD
18440 This is the old way to set "LIBGUESTFS_BACKEND".
18441 LIBGUESTFS_BACKEND
18443 Choose the default way to create the appliance. See
18444 "guestfs_set_backend" and "BACKEND".
18445 LIBGUESTFS_BACKEND_SETTINGS
18447 A colon-separated list of backend-specific settings. See
18448 "BACKEND", "BACKEND SETTINGS".
18449 LIBGUESTFS_CACHEDIR
18451 The location where libguestfs will cache its appliance, when using
18452 a supermin appliance. The appliance is cached and shared between
18453 all handles which have the same effective user ID.
18454 If "LIBGUESTFS_CACHEDIR" is not set, then "TMPDIR" is used. If
18456 "TMPDIR" is not set, then /var/tmp is used.
18457 See also "LIBGUESTFS_TMPDIR", "guestfs_set_cachedir".
18459 LIBGUESTFS_DEBUG
18461 Set "LIBGUESTFS_DEBUG=1" to enable verbose messages. This has the
18462 same effect as calling "guestfs_set_verbose (g, 1)".
18463 LIBGUESTFS_HV
18465 Set the default hypervisor (usually qemu) binary that libguestfs
18466 uses. If not set, then the qemu which was found at compile time by
18467 the configure script is used.
18468 See also "QEMU WRAPPERS" above.
18470 LIBGUESTFS_MEMSIZE
18472 Set the memory allocated to the qemu process, in megabytes. For
18473 example:
18474 LIBGUESTFS_MEMSIZE=700
18476 LIBGUESTFS_PATH
18478 Set the path that libguestfs uses to search for a supermin
18479 appliance. See the discussion of paths in section "PATH" above.
18480 LIBGUESTFS_QEMU
18482 This is the old way to set "LIBGUESTFS_HV".
18483 LIBGUESTFS_TMPDIR
18485 The location where libguestfs will store temporary files used by
18486 each handle.
18487 If "LIBGUESTFS_TMPDIR" is not set, then "TMPDIR" is used. If
18489 "TMPDIR" is not set, then /tmp is used.
18490 See also "LIBGUESTFS_CACHEDIR", "guestfs_set_tmpdir".
18492 LIBGUESTFS_TRACE
18494 Set "LIBGUESTFS_TRACE=1" to enable command traces. This has the
18495 same effect as calling "guestfs_set_trace (g, 1)".
18496 PATH
18498 Libguestfs may run some external programs, and relies on $PATH
18499 being set to a reasonable value. If using the libvirt backend,
18500 libvirt will not work at all unless $PATH contains the path of
18501 qemu/KVM. Note that PHP by default removes $PATH from the
18502 environment which tends to break everything.
18503 SUPERMIN_KERNEL
18505 SUPERMIN_KERNEL_VERSION
18506 SUPERMIN_MODULES
18507 These three environment variables allow the kernel that libguestfs
18508 uses in the appliance to be selected. If $SUPERMIN_KERNEL is not
18509 set, then the most recent host kernel is chosen. For more
18510 information about kernel selection, see supermin(1).
18511 TMPDIR
18513 See "LIBGUESTFS_CACHEDIR", "LIBGUESTFS_TMPDIR".
18514 XDG_RUNTIME_DIR
18516 This directory represents a user-specific directory for storing
18517 non-essential runtime files.
18518 If it is set, then is used to store temporary sockets. Otherwise,
18520 /tmp is used.
18521 See also "get-sockdir",
18523 http://www.freedesktop.org/wiki/Specifications/basedir-spec/.
18524
18526 Examples written in C: guestfs-examples(3).
18527 Language bindings: guestfs-erlang(3), guestfs-gobject(3),
18529 guestfs-golang(3), guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3),
18530 guestfs-perl(3), guestfs-python(3), guestfs-ruby(3).
18531 Tools: guestfish(1), guestmount(1), virt-alignment-scan(1),
18533 virt-builder(1), virt-builder-repository(1), virt-cat(1),
18534 virt-copy-in(1), virt-copy-out(1), virt-customize(1), virt-df(1),
18535 virt-diff(1), virt-edit(1), virt-filesystems(1), virt-format(1),
18536 virt-inspector(1), virt-list-filesystems(1), virt-list-partitions(1),
18537 virt-log(1), virt-ls(1), virt-make-fs(1), virt-p2v(1), virt-rescue(1),
18538 virt-resize(1), virt-sparsify(1), virt-sysprep(1), virt-tail(1),
18539 virt-tar(1), virt-tar-in(1), virt-tar-out(1), virt-v2v(1),
18540 virt-win-reg(1).
18541 Other libguestfs topics: guestfs-building(1), guestfs-faq(1),
18543 guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1),
18544 guestfs-release-notes(1), guestfs-security(1), guestfs-testing(1),
18545 libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1).
18546 Related manual pages: supermin(1), qemu(1), hivex(3), stap(1),
18548 sd-journal(3).
18549 Website: http://libguestfs.org/
18551 Tools with a similar purpose: fdisk(8), parted(8), kpartx(8), lvm(8),
18553 disktype(1).
18554
18556 Richard W.M. Jones ("rjones at redhat dot com")
18557
18559 Copyright (C) 2009-2019 Red Hat Inc.
18560
18562 This library is free software; you can redistribute it and/or modify it
18563 under the terms of the GNU Lesser General Public License as published
18564 by the Free Software Foundation; either version 2 of the License, or
18565 (at your option) any later version.
18566 This library is distributed in the hope that it will be useful, but
18568 WITHOUT ANY WARRANTY; without even the implied warranty of
18569 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18570 Lesser General Public License for more details.
18571 You should have received a copy of the GNU Lesser General Public
18573 License along with this library; if not, write to the Free Software
18574 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18575 02110-1301 USA
18576
18578 To get a list of bugs against libguestfs, use this link:
18579 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
18580 To report a new bug against libguestfs, use this link:
18582 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
18583 When reporting a bug, please supply:
18585 · The version of libguestfs.
18587 · Where you got libguestfs (eg. which Linux distro, compiled from
18589 source, etc)
18590 · Describe the bug accurately and give a way to reproduce it.
18592 · Run libguestfs-test-tool(1) and paste the complete, unedited output
18594 into the bug report.
18595libguestfs-1.40.2 2019-02-07 guestfs(3)