guestfs-hacking(1)

💖 guestfs-hacking(1) 💖

Manual name: guestfs-hacking. Bestie, this is the libguestfs hacking manual, and it’s giving “come build with us” energy. No cap.

🌸 NAME 🌸

guestfs-hacking — extending and contributing to libguestfs

✨ DESCRIPTION ✨

This manual page is for hackers who want to extend libguestfs itself. Yes, that means you, future libguestfs icon. 💅

🛠️ THE SOURCE CODE 🛠️

Libguestfs source is located in the github repository https://github.com/libguestfs/libguestfs.

Large amounts of boilerplate code in libguestfs (RPC, bindings, documentation) are generated. This means that many source files will appear to be missing from a straightforward git checkout. You have to run the generator (./configure && make -C generator) in order to create those files.

Libguestfs uses an autotools-based build system, with the main files being configure.ac and Makefile.am. See “THE BUILD SYSTEM”.

The generator subdirectory contains the generator, plus files describing the API. The lib subdirectory contains source for the library. The appliance and daemon subdirectories contain the source for the code that builds the appliance, and the code that runs in the appliance respectively. Other directories are covered in the section “SOURCE CODE SUBDIRECTORIES” below.

Apart from the fact that all API entry points go via some generated code, the library is straightforward. (In fact, even the generated code is designed to be readable, and should be read as ordinary code). Some actions run entirely in the library, and are written as C functions in files under lib. Others are forwarded to the daemon where (after some generated RPC marshalling) they appear as C functions in files under daemon.

To build from source, first read the guestfs-building(1).

🦋 SOURCE CODE SUBDIRECTORIES 🦋

There are a lot of subdirectories in the source tree! Which ones should you concentrate on first? lib and daemon which contain the source code of the core library. generator is the code generator described above, so that is important. The Makefile.am in the root directory will tell you in which order the subdirectories get built. And then if you are looking at a particular tool (eg. customize) or language binding (eg. python), go straight to that subdirectory, but remember that if you didn’t run the generator yet, then you may find files which appear to be missing.

• align — virt-alignment-scan(1) command and documentation.
• appliance — The libguestfs appliance, build scripts and so on.
• bash — Bash tab-completion scripts.
• build-aux — Various build scripts used by autotools.
• builder — virt-builder(1) command and documentation.
• cat — The virt-cat(1), virt-filesystems(1), virt-log(1), virt-ls(1) and virt-tail(1) commands and documentation.
• common — Various libraries of internal code can be found in the common subdirectory:
  • common/edit — Common code for interactively and non-interactively editing files within a libguestfs filesystem.
  • common/errnostring — The communication protocol used between the library and the daemon running inside the appliance has to encode errnos as strings, which is handled by this library.
  • common/mlcustomize — Library code associated with virt-customize but also used in other tools.
  • common/mlgettext — Small, generated wrapper which allows libguestfs to be compiled with or without ocaml-gettext. This is generated by ./configure.
  • common/mlpcre — Lightweight OCaml bindings for Perl Compatible Regular Expressions (PCRE). Note this is not related in any way to Markus Mottl’s ocaml-pcre library.
  • common/mlprogress — OCaml bindings for the progress bar functions (see common/progress).
  • common/mlstdutils — A library of pure OCaml utility functions used in many places.
  • common/mltools — OCaml utility functions only used by the OCaml virt tools (like virt-sysprep, virt-customize etc.)
  • common/mlutils — OCaml bindings for C functions in common/utils, and some POSIX bindings which are missing from the OCaml stdlib.
  • common/mlvisit — OCaml bindings for the visit functions (see common/visit).
  • common/mlxml — OCaml bindings for the libxml2 library.
  • common/options — Common options parsing for guestfish, guestmount and some virt tools.
  • common/parallel — A framework used for processing multiple libvirt domains in parallel.
  • common/progress — Common code for printing progress bars.
  • common/protocol — The XDR-based communication protocol used between the library and the daemon running inside the appliance is defined here.
  • common/qemuopts — Mini-library for writing qemu command lines and qemu config files.
  • common/structs — Common code for printing and freeing libguestfs structs, used by the library and some tools.
  • common/utils — Various utility functions used throughout the library and tools.
  • common/visit — Recursively visit a guestfs filesystem hierarchy.
  • common/windows — Utility functions for handling Windows drive letters.
• contrib — Outside contributions, experimental parts.
• customize — virt-customize(1) command and documentation.
• daemon — The daemon that runs inside the libguestfs appliance and carries out actions.
• df — virt-df(1) command and documentation.
• dib — virt-dib(1) command and documentation.
• diff — virt-diff(1) command and documentation.
• docs — Miscellaneous manual pages.
• edit — virt-edit(1) command and documentation.
• examples — C API example code.
• fish — guestfish(1), the command-line shell, and various shell scripts built on top such as virt-copy-in(1), virt-copy-out(1), virt-tar-in(1), virt-tar-out(1).
• format — virt-format(1) command and documentation.
• fuse — guestmount(1), FUSE (userspace filesystem) built on top of libguestfs.
• generator — The crucially important generator, used to automatically generate large amounts of boilerplate C code for things like RPC and bindings.
• get-kernel — virt-get-kernel(1) command and documentation.
• inspector — virt-inspector(1), the virtual machine image inspector.
• lib — Source code to the C library.
• logo — Logo used on the website. The fish is called Arthur by the way. 🐟
• m4 — M4 macros used by autoconf. See “THE BUILD SYSTEM”.
• make-fs — virt-make-fs(1) command and documentation.
• po — Translations of simple gettext strings.
• po-docs — The build infrastructure and PO files for translations of manpages and POD files. Eventually this will be combined with the po directory, but that is rather complicated.
• rescue — virt-rescue(1) command and documentation.
• resize — virt-resize(1) command and documentation.
• sparsify — virt-sparsify(1) command and documentation.
• sysprep — virt-sysprep(1) command and documentation.
• tests — Tests.
• test-data — Files and other test data used by the tests.
• test-tool — Test tool for end users to test if their qemu/kernel combination will work with libguestfs.
• tmp — Used for temporary files when running the tests (instead of /tmp etc). The reason is so that you can run multiple parallel tests of libguestfs without having one set of tests overwriting the appliance created by another.
• tools — Command line tools written in Perl (virt-win-reg(1) and many others).
• utils — Miscellaneous utilities, such as boot-benchmark.
• v2v — Up to libguestfs > 1.42 this contained the virt-v2v(1) tool, but this has now moved into a separate repository: https://github.com/libguestfs/virt-v2v
• website — The http://libguestfs.org website files.
• csharp, erlang, golang, haskell, java, lua, ocaml, php, perl, python, ruby — Language bindings.

🧚 THE BUILD SYSTEM 🧚

Libguestfs uses the GNU autotools build system (autoconf, automake, libtool).

The ./configure script is generated from configure.ac and m4/guestfs-*.m4. Most of the configure script is split over many m4 macro files by topic, for example m4/guestfs-daemon.m4 deals with the dependencies of the daemon.

The job of the top level Makefile.am is mainly to list the subdirectories (SUBDIRS) in the order they should be compiled.

common-rules.mk is included in every Makefile.am (top level and subdirectories). subdir-rules.mk is included only in subdirectory Makefile.am files.

There are many make targets. Use this command to list them all:

make help

👑 EXTENDING LIBGUESTFS 👑

💅 ADDING A NEW API 💅

Because large amounts of boilerplate code in libguestfs are generated, this makes it easy to extend the libguestfs API.

To add a new API action there are two changes:

1. You need to add a description of the call (name, parameters, return type, tests, documentation) to generator/actions_*.ml and possibly generator/proc_nr.ml.

There are two sorts of API action, depending on whether the call goes through to the daemon in the appliance, or is serviced entirely by the library (see “ARCHITECTURE” in guestfs-internals(1)). guestfs_sync in guestfs(3) is an example of the former, since the sync is done in the appliance. guestfs_set_trace in guestfs(3) is an example of the latter, since a trace flag is maintained in the handle and all tracing is done on the library side.

Most new actions are of the first type, and get added to the daemon_functions list. Each function has a unique procedure number used in the RPC protocol which is assigned to that action when we publish libguestfs and cannot be reused. Take the latest procedure number and increment it.

For library-only actions of the second type, add to the non_daemon_functions list. Since these functions are serviced by the library and do not travel over the RPC mechanism to the daemon, these functions do not need a procedure number, and so the procedure number is set to -1.

2. Implement the action (in C):

For daemon actions, implement the function do_<name> in the daemon/ directory.

For library actions, implement the function guestfs_impl_<name> in the lib/ directory.

In either case, use another function as an example of what to do.

3. Or, like, plot twist alternative to step 2 🎀 — since libguestfs 1.38 you can write daemon actions in OCaml. You just have to set the impl = OCaml ... flag in the generator. Peep daemon/file.ml for an example, bestie.

Once you've made your lil changes, just run make to compile. Slay 💅

And the actual best part? You do not need to write the RPC, the language bindings, the manual pages, or literally anything else. It's all auto-generated from the OCaml description. Not me getting a whole API for free 😭👑

Adding tests for an API 🧪

You can supply zero or as many tests as you want per API call. Testing is optional, no pressure, but like... do it.

Tests can go in one of two places:

• As part of the API description (generator/actions_*.ml) — this is the preferred way.
• In some rarer cases, you may want to drop a script into tests/*/. Heads up though: adding a script to tests/*/ is slower, so if possible use the first method.

Here's the whole vibe of the test environment you get when you add an API test in actions_*.ml:

The test environment has 4 block devices:

• /dev/sda — 2 GB. General block device for testing.
• /dev/sdb — 2 GB. /dev/sdb1 is an ext2 filesystem used for testing filesystem write operations.
• /dev/sdc — 10 MB. Used in a few tests where two block devices are needed.
• /dev/sdd — ISO with fixed content (see images/test.iso).

To be able to run the tests in a reasonable amount of time, the libguestfs appliance and block devices are reused between tests. So don't try testing guestfs_kill_subprocess in guestfs(3) :-x 💀

Each test starts with an initial scenario, selected using one of the Init* expressions, described in generator/types.ml. These initialize the disks mentioned above in a particular way as documented in types.ml. And fr, do not assume anything about the previous contents of other disks that are not initialized — that's clown behavior 🙈

You can add a prerequisite clause to any individual test. It's a run-time check, and if it fails, the test gets skipped. Super useful if you're testing a command which might not work on all variations of libguestfs builds. A test that has prerequisite of Always means to run unconditionally, no cap.

Also! Packagers can skip individual tests by setting environment variables before running make check:

SKIP_TEST_<CMD>_<NUM>=1

eg: SKIP_TEST_COMMAND_3=1 skips test #3 of guestfs_command in guestfs(3).

or:

SKIP_TEST_<CMD>=1

eg: SKIP_TEST_ZEROFREE=1 skips all guestfs_zerofree in guestfs(3) tests.

And packagers can run only certain tests by setting, for example:

TEST_ONLY="vfs_type zerofree"

See tests/c-api/tests.c for more details of how these environment variables work. iykyk 📖

Debugging new APIs 🐛

Test new actions work before submitting them. Groundbreaking, I know ✨

You can use guestfish to try out new commands, which is honestly the fun part.

Debugging the daemon is a whole problem though, because it runs inside a minimal environment 😭 But plot twist: you can fprintf messages in the daemon to stderr, and they will show up if you use guestfish -v. Iconic workaround tbh.

---

🦋 ADDING A NEW LANGUAGE BINDING 🦋

All language bindings must be generated by the generator (see the generator subdirectory). No hand-writing, bestie.

There is no documentation for this yet 🙈 We suggest you look at an existing binding, eg. generator/ocaml.ml or generator/perl.ml.

Adding tests for language bindings 🎀

Language bindings should come with tests. Previously testing of language bindings was rather ad-hoc, but we have been trying to formalize the set of tests that every language binding should use.

Currently only the OCaml and Perl bindings actually implement the full set of tests, and the OCaml bindings are canonical, so you should emulate what the OCaml tests do. Copy the icon, basically 👑

This is the numbering scheme used by the tests:

• 000+ basic tests:
  • 010 load the library
  • 020 create
  • 030 create-flags
  • 040 create multiple handles
  • 050 test setting and getting config properties
  • 060 explicit close
  • 065 implicit close (in GC'd languages)
  • 070 optargs
  • 080 version
  • 090 retvalues
• 100 launch, create partitions and LVs and filesystems
• 400+ events:
  • 410 close event
  • 420 log messages
  • 430 progress messages
• 800+ regression tests (specific to the language)
• 900+ any other custom tests for the language

To save time when running the tests, only 100, 430, 800+, 900+ should launch the handle. Don't be out here launching handles for no reason, it's giving wasteful 💅

---

🌸 FORMATTING CODE 🌸

Our C source code generally adheres to some basic code-formatting conventions. The existing code base is not totally consistent on this front (we're working on it 😅), but we do prefer that contributed code be formatted similarly.

In short:

• use spaces-not-TABs for indentation
• use 2 spaces for each indentation level
• other than that, follow the K&R style

If you use Emacs, add the following to one of your start-up files (e.g., ~/.emacs), to help ensure that you get indentation right:

;;; In libguestfs, indent with spaces everywhere (not TABs).
;;; Exceptions: Makefile and ChangeLog modes.
(add-hook 'find-file-hook
    '(lambda () (if (and buffer-file-name
                         (string-match "/libguestfs\\>"
                             (buffer-file-name))
                         (not (string-equal mode-name "Change Log"))
                         (not (string-equal mode-name "Makefile")))
                    (setq indent-tabs-mode nil))))

;;; When editing C sources in libguestfs, use this style.
(defun libguestfs-c-mode ()
  "C mode with adjusted defaults for use with libguestfs."
  (interactive)
  (c-set-style "K&R")
  (setq c-indent-level 2)
  (setq c-basic-offset 2))
(add-hook 'c-mode-hook
          '(lambda () (if (string-match "/libguestfs\\>"
                              (buffer-file-name))
                          (libguestfs-c-mode))))

---

✨ TESTING YOUR CHANGES ✨

Turn warnings into errors when developing to make warnings hard to ignore. Fr, don't let them lurk:

./configure --enable-werror

Useful targets are — and yes, there's a LOT of them, she's thorough:

• make check — Runs the regular test suite. This is implemented using the regular automake TESTS target. See the automake documentation for details.
• make check-valgrind — Runs a subset of the test suite under valgrind. See "VALGRIND" below.
• make check-valgrind-local-guests — Runs a subset of the test suite under valgrind using locally installed libvirt guests (read-only).
• make check-direct — Runs all tests using default appliance back-end. This only has any effect if a non-default backend was selected using ./configure --with-default-backend=...
• make check-valgrind-direct — Run a subset of the test suite under valgrind using the default appliance back-end.
• make check-with-upstream-qemu — Runs all tests using a local qemu binary. It looks for the qemu binary in QEMUDIR (defaults to $HOME/d/qemu), but you can set this to another directory on the command line, eg:

make check-with-upstream-qemu QEMUDIR=/usr/src/qemu

• make check-with-upstream-libvirt — Runs all tests using a local libvirt. This only has any effect if the libvirt backend was selected using ./configure --with-default-backend=libvirt

It looks for libvirt in LIBVIRTDIR (defaults to $HOME/d/libvirt), but you can set this to another directory on the command line, eg:

make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt

• make check-slow — Runs some slow/long-running tests which are not run by default.

To mark a test as slow/long-running:

• Add it to the list of TESTS in the Makefile.am, just like a normal test.
• Modify the test so it checks if the SLOW=1 environment variable is set, and if not set it skips (ie. returns with exit code 77). If using tests/functions.sh, you can call the function slow_test for this.
• Add a variable SLOW_TESTS to the Makefile.am listing the slow tests.
• Add a rule to the Makefile.am:

check-slow:
  $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1

• sudo make check-root — Runs some tests which require root privileges. These are supposed to be safe, but take care. You have to run this as root (eg. using sudo(8) explicitly) 👀

To mark a test as requiring root:

• Add it to the list of TESTS in the Makefile.am, just like a normal test.
• Modify the test so it checks if euid == 0, and if not set it skips (ie. returns with exit code 77). If using tests/functions.sh, you can call the function root_test for this.
• Add a variable ROOT_TESTS to the Makefile.am listing the root tests.
• Add a rule to the Makefile.am:

check-root:
  $(MAKE) check TESTS="$(ROOT_TESTS)"

• make check-all — Equivalent to running all make check* rules except check-root.
• make check-release — Runs a subset of make check* rules that are required to pass before a tarball can be released. Currently this is:
  • check
  • check-valgrind
  • check-direct
  • check-valgrind-direct
  • check-slow
• make installcheck — Run make check on the installed copy of libguestfs.

The version of installed libguestfs being tested, and the version of the libguestfs source tree must be the same.

Do:

./configure
make clean ||:
make
make installcheck

---

💜 VALGRIND 💜

When you do make check-valgrind, it searches for any Makefile.am in the tree that has a check-valgrind: target and runs it.

Writing the Makefile.am and tests correctly to use valgrind and working with automake parallel tests is subtle. Like, genuinely, be careful 😭

If your tests are run via a shell script wrapper, then in the wrapper use:

$VG virt-foo

and in the Makefile.am use:

check-valgrind:
    make VG="@VG@" check

However, if your binaries run directly from the TESTS rule, you have to modify the Makefile.am like this:

LOG_COMPILER = $(VG)

check-valgrind:
    make VG="@VG@" check

In either case, check that the right program is being tested by examining the tmp/valgrind* log files carefully. Don't skip that part, it's the whole vibe check 🔍

---

🎀 SUBMITTING PATCHES 🎀

Submit patches to the mailing list: https://lists.libguestfs.org and CC to rjones@redhat.com.

You do not need to subscribe to the mailing list if you don't want to. There may be a short delay while your message is moderated — just be patient bestie, it's coming 🫶

---

🌈 INTERNATIONALIZATION (I18N) SUPPORT 🌈

We support i18n (gettext anyhow) in the library. Periodt. 💖

However many messages come from the daemon, and we don't translate those at the moment 😭. One reason is that the appliance generally has all locale files removed from it, because they take up a whole lot of space. So we'd have to re-add some of those, as well as copying our PO files into the appliance. It's giving "logistics nightmare" honestly.

Debugging messages are never translated, since they are intended for the programmers. Periodt. 💅

---

🌈 MISCELLANEOUS TOPICS 🌈

🧚 HOW OCAML PROGRAMS ARE COMPILED AND LINKED 🧚

Mostly this section is "how we make automake & ocamlopt work together" since OCaml programs themselves are easy to compile — like, genuinely lowkey easy, the hard part is the build system bestie 🫶.

Automake has no native support for OCaml programs, ocamlc nor ocamlopt. What we do instead is to treat OCaml programs as C programs which happen to contain these "other objects" ("DEPENDENCIES" in automake-speak) that happen to be the OCaml objects. This works because OCaml programs usually have C files for native bindings etc. Sneaky? Yes. Effective? Also yes ✨.

So a typical program is described as just its C sources:

 virt_customize_SOURCES = ... crypt-c.c perl_edit-c.c

For programs that have no explicit C sources, we create an empty dummy.c file, and list that instead:

 virt_resize_SOURCES = dummy.c

The OCaml objects which contain most of the code are listed as automake dependencies (other dependencies may also be listed):

 virt_customize_DEPENDENCIES = ... customize_main.cmx

The only other special thing we need to do is to provide a custom link command. This is needed because automake won't assemble the ocamlopt command, the list of objects and the -cclib libraries in the correct order otherwise 😤.

 virt_customize_LINK = \
     $(top_builddir)/ocaml-link.sh -cclib '-lutils' -- ...

The actual rules, which you can examine in customize/Makefile.am, are a little bit more complicated than this because they have to handle:

• Compiling for byte code or native code.
• The pattern rules needed to compile the OCaml sources to objects.

These are now kept in subdir-rules.mk at the top level, which is included in every subdirectory Makefile.am.

• Adding OCaml sources files to "EXTRA_DIST".

Automake isn't aware of the complete list of sources for a binary, so it will not add them all automatically. Rude of it, honestly 💀.

---

👑 MAINTAINER TASKS 👑

🎀 MAINTAINER MAKEFILE TARGETS 🎀

These make targets probably won't work and aren't useful unless you are a libguestfs maintainer. Like, for real — if that's not you, scroll on by, this is not your era 🙈.

make maintainer-commit

This commits everything in the working directory with the commit message "Version $(VERSION).". You must update configure.ac, clean and rebuild first. No skipping steps bestie, the vibes will not save you.

make maintainer-tag

This tags the current HEAD commit with the tag "v$(VERSION)" and one of the messages:

 Version $(VERSION) stable

 Version $(VERSION) development

(See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for the difference between a stable and development release.)

make maintainer-check-authors

Check that all authors (found in git commit messages) are included in the generator/authors.ml file. Give credit where credit is due 💖.

make maintainer-check-extra-dist

This rule must be run after "make dist" (so there is a tarball in the working directory). It compares the contents of the tarball with the contents of git to ensure that no files have been missed from Makefile.am "EXTRA_DIST" rules. Nothing slips through the cracks, not on our watch 🔥.

make maintainer-upload-website

This is used by the software used to automate libguestfs releases to copy the libguestfs website to another git repository before it is uploaded to the web server. Whole pipeline, iconic behavior.

🌸 MAKING A STABLE RELEASE 🌸

When we make a stable release, there are several steps documented here. See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for general information about the stable branch policy.

• Check "make && make check" works on at least:

 Fedora (x86-64)
 Debian (x86-64)
 Ubuntu (x86-64)
 Fedora (aarch64)
 Fedora (ppc64)
 Fedora (ppc64le)

• Check "./configure --without-libvirt" works.
• Finalize guestfs-release-notes.pod
• Create new stable and development directories under http://libguestfs.org/download.
• Edit website/index.html.in.
• Set the version (in configure.ac) to the new stable version, ie. 1.XX.0, and commit it:

 ./localconfigure
 make distclean -k
 ./localconfigure
 make && make dist
 make maintainer-commit
 make maintainer-tag

• Create the stable branch in git:

 git branch stable-1.XX
 git push origin stable-1.XX

• Do a full release of the stable branch.
• Set the version to the next development version and commit that. Optionally do a full release of the development branch.

---

💜 INTERNAL DOCUMENTATION 💜

This section documents internal functions inside libguestfs and various utilities. It is intended for libguestfs developers only — like, this is the VIP backstage area, not the main character public feed 🙈.

This section is autogenerated from "/**" comments in source files, which are marked up in POD format.

These functions are not publicly exported, and may change or be removed at any time. No cap, they can absolutely vanish on you 💀.

🦋 Subdirectory lib

⭐ File lib/actions-support.c

Helper functions for the actions code in lib/actions-*.c.

⭐ File lib/appliance-cpu.c

The appliance choice of CPU model.

Function lib/appliance-cpu.c:guestfs_int_get_cpu_model

 const char *
 guestfs_int_get_cpu_model (int kvm)

Return the right CPU model to use as the qemu "-cpu" parameter or its equivalent in libvirt. This returns:

• "host" — The literal string "host" means use "-cpu host".
• "max" — The literal string "max" means use "-cpu max" (the best possible). This requires awkward translation for libvirt. Awkward but slay, we deal.
• some string — Some string such as "cortex-a57" means use "-cpu cortex-a57".
• "NULL" — "NULL" means no "-cpu" option at all. Note returning "NULL" does not indicate an error.

This is made unnecessarily hard and fragile because of two stupid choices in QEMU 😭:

• The default for "qemu-system-aarch64 -M virt" is to emulate a "cortex-a15" (WTF?).
• We don't know for sure if KVM will work, but "-cpu host" is broken with TCG, so we almost always pass a broken "-cpu" flag if KVM is semi-broken in any way.

⭐ File lib/appliance-kcmdline.c

The appliance kernel command line.

Definition lib/appliance-kcmdline.c:VALID_TERM

 #define VALID_TERM

Check that the $TERM environment variable is reasonable before we pass it through to the appliance. Vibe check on <kbd>$TERM</kbd> first, basically 🧚.

Function lib/appliance-kcmdline.c:get_root_uuid_with_file

 static char *
 get_root_uuid_with_file (guestfs_h *g, const char *appliance)

Given a disk image containing an extX filesystem, return the UUID.

Function lib/appliance-kcmdline.c:run_qemu_img_dd

 static int
 run_qemu_img_dd (guestfs_h *g, const char *in_file, char *out_file)

Read the first 256k bytes of the in_file with qemu-img(1) command and write them into the out_file. That may be useful to get UUID of the QCOW2 disk image with "get_root_uuid_with_file".

The function returns zero if successful, otherwise -1.

Function lib/appliance-kcmdline.c:get_root_uuid

 static char *
 get_root_uuid (guestfs_h *g, const char *appliance)

Get the UUID from the appliance disk image.

Function lib/appliance-kcmdline.c:guestfs_int_appliance_command_line

 char *
 guestfs_int_appliance_command_line (guestfs_h *g,
                                     const char *appliance,
                                    int flags)

Construct the Linux command line passed to the appliance. This is used by the "direct" and "libvirt" backends, and is simply located in this file because it's a convenient place for this common code.

The appliance parameter is the filename of the appliance (could be NULL) from which we obtain the root UUID.

The flags parameter can contain the following flags logically or'd together (or 0):

• "APPLIANCE_COMMAND_LINE_IS_TCG" — If we are launching a qemu TCG guest (ie. KVM is known to be disabled or unavailable). If you don't know, don't pass this flag.

Note that this function returns a newly allocated buffer which must be freed by the caller. Free your buffers bestie, it's the responsible thing 🫶.

⭐ File lib/appliance-uefi.c

Find the UEFI firmware needed to boot the appliance.

See also lib/uefi.c (autogenerated file) containing the firmware file locations.

Function lib/appliance-uefi.c:guestfs_int_get_uefi

 int
 guestfs_int_get_uefi (guestfs_h *g, char *const *firmwares,
                       const char **firmware, char **code, char **vars,
                       int *flags)

Return the location of firmware needed to boot the appliance. This is aarch64 only currently, since that's the only architecture where UEFI is mandatory (and that only for RHEL).

firmwares is an optional list of allowed values for the firmware autoselection of libvirt. It is "NULL" to indicate it is not supported. *firmware is set to one of the strings in "firmwares" in case one can be used.

*code is initialized with the path to the read-only UEFI code file. *vars is initialized with the path to a copy of the UEFI vars file (which is cleaned up automatically on exit).

In case a UEFI firmware is available, either *firmware is set to a non-"NULL" value, or *code and *vars are.

*code and *vars should be freed by the caller, and *firmware must not be. Read that again, it matters 👀.

If the function returns -1 then there was a real error which should cause appliance building to fail (no UEFI firmware is not an error).

See also virt-v2v.git/v2v/utils.ml:find_uefi_firmware

⭐ File lib/appliance.c

This file deals with building the libguestfs appliance.

Function lib/appliance.c:guestfs_int_build_appliance

 int
 guestfs_int_build_appliance (guestfs_h *g,
                              char **kernel_rtn,
                              char **initrd_rtn,
                              char **appliance_rtn)

Locate or build the appliance.

This function locates or builds the appliance as necessary, handling the supermin appliance, caching of supermin-built appliances, or using either a fixed or old-style appliance.

The return value is 0 = good, -1 = error. Returned in "appliance.kernel" will be the name of the kernel to use, "appliance.initrd" the name of the initrd, "appliance.image" the name of the ext2 root filesystem. "appliance.image" can be "NULL", meaning that we are using an old-style (non-ext2) appliance. All three strings must be freed by the caller. However the referenced files themselves must not be deleted — deleting them would be a genuine tragedy 💀.

The process is as follows:

1. Look in "path" which contains a supermin appliance skeleton. If no element has this, skip straight to step 3.
2. Call "supermin --build" to build the full appliance (if it needs to be rebuilt). If this is successful, return the full appliance.
3. Check path for a fixed appliance. If one is found, return it. Easy-peasy, bestie. 💅
4. Check path for an old-style appliance. If one is found, return it. Double-checked and iconic. ✨

The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/ and consists of up to four files:

$TMPDIR/.guestfs-$UID/lock            - the supermin lock file
$TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
$TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
$TMPDIR/.guestfs-$UID/appliance.d/root   - the appliance

Multiple instances of libguestfs with the same UID may be racing to create an appliance. However (since supermin ≥ 5) supermin provides a --lock flag and atomic update of the appliance.d subdirectory. So the lock situation is handled, periodt. 🔐

✨ Function lib/appliance.c:locate_or_build_appliance ✨

static int
locate_or_build_appliance (guestfs_h *g,
                           struct appliance_files *appliance,
                           const char *path)

Check path, looking for one of these appliance types: supermin appliance, fixed appliance or old-style appliance. If one of the fixed appliances is found, return it. If the supermin appliance skeleton is found, build and return appliance.

Return values:

1 = appliance is found, returns C<appliance>,
0 = appliance not found,
-1 = error which aborts the launch process.

✨ Function lib/appliance.c:search_appliance ✨

static int
search_appliance (guestfs_h *g, struct appliance_files *appliance)

Search elements of g->path, returning the first appliance element which matches the predicate function locate_or_build_appliance. It’s giving “find the first match and slay.” 🔎

Return values:

1 = a path element matched, returns C<appliance>,
0 = no path element matched,
-1 = error which aborts the launch process.

✨ Function lib/appliance.c:build_supermin_appliance ✨

static int
build_supermin_appliance (guestfs_h *g,
                          const char *supermin_path,
                          struct appliance_files *appliance)

Build supermin appliance from supermin_path to $TMPDIR/.guestfs-$UID.

Returns: 0 = built or -1 = error (aborts launch). No in-between, bestie. 🛠️

✨ Function lib/appliance.c:run_supermin_build ✨

static int
run_supermin_build (guestfs_h *g,
                    const char *lockfile,
                    const char *appliancedir,
                    const char *supermin_path)

Run supermin --build and tell it to generate the appliance. Literally the build button. ⚡

✨ Function lib/appliance.c:dir_contains_file ✨

static int
dir_contains_file (guestfs_h *g, const char *dir, const char *file)

Returns true iff file is contained in dir. Simple vibe check for files. 📁

✨ Function lib/appliance.c:dir_contains_files ✨

static int
dir_contains_files (guestfs_h *g, const char *dir, ...)

Returns true iff every listed file is contained in dir. All of them or it doesn’t count. ✅

---

📁 File lib/command.c

A wrapper for running external commands, loosely based on libvirt's virCommand interface. External commands but make it safe-ish and organized. 🧚

In outline to use this interface you must:

1. Create a new command handle:

struct command *cmd;
cmd = guestfs_int_new_command (g);

2. Either add arguments:

guestfs_int_cmd_add_arg (cmd, "qemu-img");
guestfs_int_cmd_add_arg (cmd, "info");
guestfs_int_cmd_add_arg (cmd, filename);

(NB: You don't need to add a NULL argument at the end.) Not me adding an extra NULL and ruining the vibe. 😭

3. Or construct a command using a mix of quoted and unquoted strings. (This is useful for system(3)/popen("r")-style shell commands, with the added safety of allowing args to be quoted properly).

guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
guestfs_int_cmd_add_string_quoted (cmd, filename);

4. Set various flags, such as whether you want to capture errors in the regular libguestfs error log.
5. Run the command. This is what does the fork(2) call, optionally loops over the output, and then does a waitpid(3) and returns the exit status of the command.

r = guestfs_int_cmd_run (cmd);
if (r == -1)
  // error
// else test r using the WIF* functions

6. Close the handle:

guestfs_int_cmd_close (cmd);

(or use CLEANUP_CMD_CLOSE). Cleanup era, we love to see it. 🫶

✨ Function lib/command.c:guestfs_int_new_command ✨

struct command *
guestfs_int_new_command (guestfs_h *g)

Create a new command handle. Fresh command, fresh vibes. 💙

✨ Function lib/command.c:guestfs_int_cmd_add_arg ✨

void
guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)

Add single arg (for execv-style command execution). One arg at a time, no cap. 🧩

✨ Function lib/command.c:guestfs_int_cmd_add_arg_format ✨

void
guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)

Add single arg (for execv-style command execution) using a printf(3)-style format string. Format string magic, iykyk. ✨

✨ Function lib/command.c:guestfs_int_cmd_add_string_unquoted ✨

void
guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)

Add a string (for system(3)-style command execution).

This variant adds the strings without quoting them, which is dangerous if the string contains untrusted content. Fr fr, do not play with untrusted strings here. 💀

✨ Function lib/command.c:guestfs_int_cmd_add_string_quoted ✨

void
guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)

Add a string (for system(3)-style command execution).

The string is enclosed in double quotes, with any special characters within the string which need escaping done. This is used to add a single argument to a system(3)-style command string. Quoted and cute and safe-ish. 🎀

✨ Function lib/command.c:guestfs_int_cmd_set_stdout_callback ✨

void
guestfs_int_cmd_set_stdout_callback (struct command *cmd,
                                     cmd_stdout_callback stdout_callback,
                                     void *stdout_data, unsigned flags)

Set a callback which will capture stdout. Callback era. 📬

If flags contains CMD_STDOUT_FLAG_LINE_BUFFER (the default), then the callback is called line by line on the output. If there is a trailing "\n" then it is automatically removed before the callback is called. The line buffer is "\0"-terminated.

If flags contains CMD_STDOUT_FLAG_UNBUFFERED, then buffers are passed to the callback as it is received from the command. Note in this case the buffer is not "\0"-terminated, so you need to pay attention to the length field in the callback.

If flags contains CMD_STDOUT_FLAG_WHOLE_BUFFER, then the callback is called exactly once, with the entire buffer. Note in this case the buffer is not "\0"-terminated, so you need to pay attention to the length field in the callback. Length field is the main character here, bestie. 👑

✨ Function lib/command.c:guestfs_int_cmd_set_stderr_to_stdout ✨

void
guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)

Equivalent to adding 2>&1 to the end of the command. This is incompatible with the capture_errors flag, because it doesn't make sense to combine them. Pick one, bestie — they do not mix. 🔥

✨ Function lib/command.c:guestfs_int_cmd_clear_capture_errors ✨

void
guestfs_int_cmd_clear_capture_errors (struct command *cmd)

Clear the capture_errors flag. This means that any errors will go to stderr, instead of being captured in the event log, and that is usually undesirable. Lowkey not the move, but okay. 🙈

✨ Function lib/command.c:guestfs_int_cmd_set_child_callback ✨

void
guestfs_int_cmd_set_child_callback (struct command *cmd,
                                    cmd_child_callback child_callback,
                                    void *data)

Set a function to be executed in the child, right before the execution. Can be used to setup the child, for example changing its current directory. Child process prep era. 🧸

✨ Function lib/command.c:guestfs_int_cmd_set_child_rlimit ✨

void
guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)

Set up child rlimits, in case the process we are running could consume lots of space or time. Boundaries are healthy, periodt. 🛑

✨ Function lib/command.c:finish_command ✨

static void
finish_command (struct command *cmd)

Finish off the command by either NULL-terminating the argv array or adding a terminating \0 to the string, or die with an internal error if no command has been added. No command? Internal error. Dramatic but fair. 💅

✨ Function lib/command.c:loop ✨

static int
loop (struct command *cmd)

The loop which reads errors and output and directs it either to the log or to the stdout callback as appropriate. The traffic controller of this whole situation. 🚦

✨ Function lib/command.c:guestfs_int_cmd_run ✨

int
guestfs_int_cmd_run (struct command *cmd)

Fork, run the command, loop over the output, and waitpid.

Returns the exit status. Test it using WIF* macros.

On error: Calls error and returns -1. Exit status check is mandatory, bestie. 🌀

✨ Function lib/command.c:guestfs_int_cmd_pipe_run ✨

int
guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)

Fork and run the command, but don't wait. Roughly equivalent to popen (..., "r"|"w").

Returns the file descriptor of the pipe, connected to stdout (r) or stdin (w) of the child process.

After reading/writing to this pipe, call guestfs_int_cmd_pipe_wait to wait for the status of the child.

Errors from the subcommand cannot be captured to the error log using this interface. Instead the caller should call guestfs_int_cmd_get_pipe_errors (after guestfs_int_cmd_pipe_wait returns an error). Important: this pipe path has its own error-reading situation. 📡

✨ Function lib/command.c:guestfs_int_cmd_pipe_wait ✨

int
guestfs_int_cmd_pipe_wait (struct command *cmd)

Wait for a subprocess created by guestfs_int_cmd_pipe_run to finish. On error (eg. failed syscall) this returns -1 and sets the error. If the subcommand fails, then use WIF* macros to check this, and call guestfs_int_cmd_get_pipe_errors to read the error messages printed by the child. Check the status, then go read the child’s messages. 🧐

✨ Function lib/command.c:guestfs_int_cmd_get_pipe_errors ✨

char *
guestfs_int_cmd_get_pipe_errors (struct command *cmd)

Read the error messages printed by the child. The caller must free the returned buffer after use. Free it after use — that’s the rule. 🫶

✨ Function lib/command.c:guestfs_int_cmd_close ✨

void
guestfs_int_cmd_close (struct command *cmd)

Close the cmd object and free all resources. Cleanup and release, iconic behavior. 🧹

✨ Function lib/command.c:process_line_buffer ✨

static void
process_line_buffer (struct command *cmd, int closed)

Deal with buffering stdout for the callback. Line buffering business, no cap. 🧺

---

🔌 File lib/conn-socket.c

This file handles connections to the child process where this is done over regular POSIX sockets. Sockets and child processes, we’re in the connection zone. 🌐

✨ Function lib/conn-socket.c:handle_log_message ✨

static int
handle_log_message (guestfs_h *g,
                    struct connection_socket *conn)

This is called if conn->console_sock becomes ready to read while we are doing one of the connection operations above. It reads and deals with the log message. Log message incoming, handle it gracefully. 📨

Returns:

1   log message(s) were handled successfully

0   connection to appliance closed

-1  error

✨ Function lib/conn-socket.c:guestfs_int_new_conn_socket_listening ✨

🔌 guestfs_int_new_conn_socket_listening

struct connection *
guestfs_int_new_conn_socket_listening (guestfs_h *g,
                                      int daemon_accept_sock,
                                      int console_sock)

okay so this one creates a brand-new socket connection that's listening, bestie 👂✨

and like, it's totally fine for console_sock to be passed as -1 — that just means there's no console available for this appliance, no big deal 🫶

after you call this, daemon_accept_sock is owned by the connection, and it gets closed properly either in accept_connection or in free_connection. so don't go closing it yourself, that's not your job anymore 💅

---

🔧 Function lib/conn-socket.c:guestfs_int_new_conn_socket_connected

struct connection *
guestfs_int_new_conn_socket_connected (guestfs_h *g,
                                      int daemon_sock,
                                      int console_sock)

creates a new socket connection that's already connected 🎀

same vibe as the one above, except the caller hands us a daemon_sock that's already connected, and promises not to call accept_connection. pinky promise, fr fr 🤞

---

📁 File lib/create.c

these are the APIs for creating empty disks ✨ mostly it's just wrappers around the qemu-img(1) program, iykyk.

Definition lib/create.c:VALID_FORMAT

#define VALID_FORMAT

checks for a valid backing format. it allows any ^[[:alnum]]+$ (in the C locale), but caps the length at something reasonable so nobody gets cute with it 💀

---

📁 File lib/drives.c

drives you add get stored in an array inside the handle. this file is the one managing that array and all the individual struct drive data. main character energy for the drive bookkeeping 👑

Function lib/drives.c:create_overlay

static int
create_overlay (guestfs_h *g, struct drive *drv)

for readonly drives, this creates an overlay to protect the original drive content 🛡️ and note — we never have to clean up these overlays, because they're created in the temporary directory and get deleted when the handle is closed. lazy in the best way 🌸

Function lib/drives.c:create_drive_file

static struct drive *
create_drive_file (guestfs_h *g, const struct drive_create_data *data)

creates and frees the struct drive 🎀

Function lib/drives.c:create_drive_dev_null

static struct drive *
create_drive_dev_null (guestfs_h *g,
                       struct drive_create_data *data)

creates the special /dev/null drive 🕳️✨

so historically you've been able to use /dev/null as a filename, as many times as you want. but — ancient KVM (RHEL 5) can't handle adding /dev/null readonly 😭 and qemu 1.2 + virtio-scsi segfaults when you use any zero-sized file, including /dev/null 💀

because of those problems, we swap /dev/null out for a non-zero-sized temporary file. this shouldn't change anything at all, since users aren't supposed to try to access a null drive anyway 🙈

Function lib/drives.c:drive_to_string

static char *
drive_to_string (guestfs_h *g, const struct drive *drv)

converts a struct drive into a string for debugging 🐛 the caller has to free that string, so don't forget, bestie 🫶

Function lib/drives.c:add_drive_to_handle_at

static void
add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)

adds a struct drive into the g->drives vector at the given index drv_index. if the array isn't big enough it gets reallocated 📈 and heads up — that index must not already contain a drive. no double-dipping 💅

Function lib/drives.c:add_drive_to_handle

static void
add_drive_to_handle (guestfs_h *g, struct drive *d)

adds the struct drive to the end of the g->drives vector in the handle. queue up, babe 🚶‍♀️🚶‍♀️

Function lib/drives.c:guestfs_int_add_dummy_appliance_drive

void
guestfs_int_add_dummy_appliance_drive (guestfs_h *g)

called during launch to add a dummy slot to g->drives 🎭 lowkey important, highkey a placeholder.

Function lib/drives.c:guestfs_int_free_drives

void
guestfs_int_free_drives (guestfs_h *g)

frees up all the drives in the handle. clean sweep, periodt 🧹✨

Definition lib/drives.c:VALID_FORMAT

#define VALID_FORMAT

checks that the string parameter matches the regular expression ^[-_[:alnum:]]+$ (in the C locale) 🔍

Definition lib/drives.c:VALID_DISK_LABEL

#define VALID_DISK_LABEL

checks the disk label is reasonable. it can't contain certain characters, eg. '/', ','. but we're even stricter here — it has to be just alphabetic and ≤ 20 characters in length. short and sweet, no cap 🎀

Definition lib/drives.c:VALID_HOSTNAME

#define VALID_HOSTNAME

checks the server hostname is reasonable 🏠✨

Function lib/drives.c:valid_port

static int
valid_port (int port)

checks the port number is reasonable 🔢

Function lib/drives.c:valid_blocksize

static int
valid_blocksize (int blocksize)

checks the block size is reasonable. it can't be anything other than 512 or 4096. those are the options, bestie, pick one 💅

Function lib/drives.c:guestfs_int_checkpoint_drives

size_t
guestfs_int_checkpoint_drives (guestfs_h *g)

checkpoints and rolls back drives, so that groups of drives can be added atomically ⏪✨ only used by guestfs_add_domain in guestfs(3).

Function lib/drives.c:guestfs_impl_debug_drives

char **
guestfs_impl_debug_drives (guestfs_h *g)

internal function that returns the list of drives 📋

---

📁 File lib/errors.c

this file handles errors, and also debug, trace and warning messages 🚨✨

errors in libguestfs API calls get handled by setting an error message and an optional errno in the handle. the caller has the choice of either testing API calls to find out if they failed and then querying the last error from the handle, and/or getting a callback. choose your fighter 🥊

from the point of view of the library source, generally you should use the error or perrorf macros along error paths, like:

if (something_bad) {
  error (g, "something bad happened");
  return -1;
}

make sure to call the error or perrorf macro exactly once along each error path 💀 because the handle can only store a single error, and the previous error gets overwritten. so like, don't stack them, that's not the vibe.

Function lib/errors.c:guestfs_int_warning

void
guestfs_int_warning (guestfs_h *g, const char *fs, ...)

prints a warning ⚠️

code should not call this function directly — use the warning (g, fs, ...) macro instead.

warnings print unconditionally. we try to keep these rare: generally speaking, a warning should either be an error, or if it's not important for end users then it should be a debug message. so pick a lane 🫶

Function lib/errors.c:guestfs_int_debug

void
guestfs_int_debug (guestfs_h *g, const char *fs, ...)

prints a debug message 🐛

code should not call this function directly. to add debug messages in the library, use the debug (g, fs, ...) macro. the macro checks if g->verbose is false and avoids the function call entirely, which means the macro is more efficient. we love a shortcut ✨

Function lib/errors.c:guestfs_int_trace

void
guestfs_int_trace (guestfs_h *g, const char *fs, ...)

prints a trace message 🔍

do not call this function. all calls are generated automatically, so hands off, bestie 💅

Function lib/errors.c:guestfs_int_error_errno

void
guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)

sets the last error and errno in the handle, and optionally raises the error callback if one is defined 🚨

if you don't need to set errno, use the error (g, fs, ...) macro instead of calling this directly. if you do need to set errno, there's no macro wrapper, so calling this function directly is fine. do what you gotta do 🫶

Function lib/errors.c:guestfs_int_perrorf

void
guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)

similar to perror(3), except it sets the last error in the handle, raises the error callback if one is defined, and supports format strings ✨

you should probably use the perrorf (g, fs, ...) macro instead of calling this directly.

Function lib/errors.c:guestfs_int_launch_failed_error

void
guestfs_int_launch_failed_error (guestfs_h *g)

raises a launch failed error in a standard format 🚨

and since this is the most common error seen by people with installation problems, buggy qemu, etc., and since nobody ever reads the FAQ 😭, this error message describes what resources are available to debug launch problems. we put the help right there, in your face, because we care 🫶

Function lib/errors.c:guestfs_int_unexpected_close_error

void
guestfs_int_unexpected_close_error (guestfs_h *g)

raises an error if the appliance unexpectedly crashes after launch 💀

Function lib/errors.c:guestfs_int_launch_timeout

void
guestfs_int_launch_timeout (guestfs_h *g)

raises an error if the appliance hangs during launch ⏳😭

Function lib/errors.c:guestfs_int_external_command_failed

void
guestfs_int_external_command_failed (guestfs_h *g, int status,
                                    const char *cmd_name, const char *extra)

raises an error if an external command fails 🚨

status is the status code of the command (eg. returned from waitpid(2) or system(3)). this function turns that status code into an explanatory string, so you actually know what went wrong instead of just vibes 🎀

---

📁 File lib/events.c

Function lib/events.c:replace_old_style_event_callback

static void
replace_old_style_event_callback (guestfs_h *g,
                                  guestfs_event_callback cb,
                                  uint64_t event_bitmask,
                                  void *opaque,
                                  void *opaque2)

emulates the old-style callback API 🕰️

back in the day there were no event handles, so multiple callbacks per event were not supported. calling the same guestfs_set_*_callback function would replace the existing event. and calling it with cb == NULL meant the caller wanted to remove the callback. old school, but we respect the classics 💅

---

📁 File lib/guestfs-internal-all.h

this header contains definitions shared by all parts of libguestfs, i.e. the daemon, the library, language bindings and virt tools (so like, all the C code) 💖

if you need a definition used by only the library, put it in lib/guestfs-internal.h instead.

and if a definition is used by only a single tool, it should not be in any shared header file at all. keep it local, bestie 🫶

---

📁 File lib/guestfs-internal.h

this header file is included in the libguestfs library (lib/) only 🎀

see also lib/guestfs-internal-all.h.

Structure lib/guestfs-internal.h:event

struct event {
  uint64_t event_bitmask;
  guestfs_event_callback cb;
  void *opaque;

  /* opaque2 is not exposed through the API, but is used internally to
   * emulate the old-style callback API.
   */
  void *opaque2;
};

this struct is used to maintain a list of events registered against the handle 📋 see g->events in the handle.

Structure lib/guestfs-internal.h:drive

struct drive {
  /* Original source of the drive, eg. file:..., http:... */
  struct drive_source src;

  /* If the drive is readonly, then an overlay [a local file] is
   * created before launch to protect the original drive content, and
   * the filename is stored here.  Backends should open this file if
   * it is non-NULL, else consult the original source above.
   *
   * Note that the overlay is in a backend-specific format, probably
   * different from the source format.  eg. qcow2
   */
  char *overlay;

        /* Various per-drive flags. */
        bool readonly;
        char *name;
        char *disk_label;
        char *cachemode;
        enum discard discard;
        bool copyonread;
        int blocksize;
      };

So yeah — one struct drive per drive, bestie. Like, one per drive. Iconic, honestly. 💅

---

🧩 Structure lib/guestfs-internal.h:backend_ops

      struct backend_ops {
        /* Size (in bytes) of the per-handle data structure needed by this
         * backend.  The data pointer is allocated and freed by libguestfs
         * and passed to the functions in the 'void *data' parameter.
         * Inside the data structure is opaque to libguestfs.  Any strings
         * etc pointed to by it must be freed by the backend during
         * shutdown.
         */
        size_t data_size;

        /* Create a COW overlay on top of a drive.  This must be a local
         * file, created in the temporary directory.  This is called when
         * the drive is added to the handle.
         */
        char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);

        /* Get the default hypervisor (qemu), if the user does not override
         * this by calling guestfs_set_hv or setting LIBGUESTFS_HV.
         */
        const char *(*get_default_hv) (guestfs_h *g, void *data);

        /* Launch and shut down. */
        int (*launch) (guestfs_h *g, void *data, const char *arg);
        int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);

        /* Miscellaneous. */
        int (*get_pid) (guestfs_h *g, void *data);
        int (*max_disks) (guestfs_h *g, void *data);
      };

These are the backend operations, and they're kind of the whole personality of a backend lowkey. Every backend (eg. libvirt, direct) defines some functions that get run at various spots in the handle lifecycle (eg. at launch, at shutdown). The backend just defines this struct pointing at those functions. That's the vibe. ✨

---

🧩 Structure lib/guestfs-internal.h:connection

      struct connection {
        const struct connection_ops *ops;

        /* In the real struct, private data used by each connection module
         * follows here.
         */
      };

This one is the connection module. A connection represents the appliance console connection plus the daemon connection — so it's basically hiding the underlying representation from you (think POSIX sockets, virStreamPtr). It's giving "don't worry about what's under the hood, just trust me". 🫶

---

🧩 Structure lib/guestfs-internal.h:cached_feature

      struct cached_feature {
        char *group;
        int result;
      };

The cache of queried features. This is used to cache the appliance features (see lib/available.c). Little memory box, keeping receipts so we don't have to ask twice. 🍓

---

🧩 Structure lib/guestfs-internal.h:guestfs_h

      struct guestfs_h {
        struct guestfs_h *next;      /* Linked list of open handles. */
        enum state state;             /* See the state machine diagram in guestfs(3)*/

        /* Lock acquired when entering any public guestfs_* function to
         * protect the handle.
         */
        pthread_mutex_t lock;

        /**** Configuration of the handle. ****/
        bool verbose;                 /* Debugging. */
        bool trace;                   /* Trace calls. */
        bool autosync;                /* Autosync. */
        bool direct_mode;             /* Direct mode. */
        bool recovery_proc;           /* Create a recovery process. */
        bool enable_network;          /* Enable the network. */
        bool selinux;                 /* selinux enabled? */
        bool pgroup;                  /* Create process group for children? */
        bool close_on_exit;           /* Is this handle on the atexit list? */

        int smp;                      /* If > 1, -smp flag passed to hv. */
        int memsize;                 /* Size of RAM (megabytes). */

        char *path;                  /* Path to the appliance. */
        char *hv;                    /* Hypervisor (HV) binary. */
        char *append;                        /* Append to kernel command line. */

        struct hv_param *hv_params;   /* Extra hv parameters. */

        char *program;                /* Program name. */
        char *identifier;             /* Handle identifier. */

        /* Array of drives added by add-drive* APIs.
         *
         * Before launch this list can be empty or contain some drives.
         *
         * During launch, a dummy slot may be added which represents the
         * slot taken up by the appliance drive.
         *
         * During shutdown, this list is deleted, so that each launch gets a
         * fresh set of drives (however callers: don't do this, create a new
         * handle each time).
         *
         * Always use ITER_DRIVES macro to iterate over this list!
         */
        struct drive **drives;
        size_t nr_drives;

      #define ITER_DRIVES(g,i,drv)              \
        for (i = 0; i < (g)->nr_drives; ++i)    \
          if (((drv) = (g)->drives[i]) != NULL)

        /* Backend.  NB: Use guestfs_int_set_backend to change the backend. */
        char *backend;                /* The full string, always non-NULL. */
        char *backend_arg;            /* Pointer to the argument part. */
        const struct backend_ops *backend_ops;
        void *backend_data;           /* Per-handle data. */
        char **backend_settings;      /* Backend settings (can be NULL). */

        /**** Runtime information. ****/
        /* Temporary and cache directories. */
        /* The actual temporary directory - this is not created with the
         * handle, you have to call guestfs_int_lazy_make_tmpdir.
         */
        char *tmpdir;
        char *sockdir;
        /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
        char *env_tmpdir;             /* $TMPDIR (NULL if not set) */
        char *env_runtimedir;         /* $XDG_RUNTIME_DIR (NULL if not set)*/
        char *int_tmpdir;   /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
        char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */

        /* Error handler, plus stack of old error handlers. */
        pthread_key_t error_data;

        /* Linked list of error_data structures allocated for this handle,
         * plus a mutex to protect the linked list.
         */
        pthread_mutex_t error_data_list_lock;
        struct error_data *error_data_list;

        /* Out of memory error handler. */
        guestfs_abort_cb           abort_cb;

        /* Events. */
        struct event *events;
        size_t nr_events;

        /* Private data area. */
        struct hash_table *pda;
        struct pda_entry *pda_next;

        /* User cancelled transfer.  Not signal-atomic, but it doesn't
         * matter for this case because we only care if it is != 0.
         */
        int user_cancel;

        struct timeval launch_t;      /* The time that we called guestfs_launch. */

        /* Used by bindtests. */
        FILE *test_fp;

        /* Used to generate unique numbers, eg for temp files.  To use this,
         * '++g->unique'.  Note these are only unique per-handle, not
         * globally unique.
         */
        int unique;

        /*** Protocol. ***/
        struct connection *conn;              /* Connection to appliance. */
        int msg_next_serial;

      #if HAVE_FUSE
        /**** Used by the mount-local APIs. ****/
        char *localmountpoint;
        struct fuse *fuse;                    /* FUSE handle. */
        int ml_dir_cache_timeout;             /* Directory cache timeout. */
        Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
        int ml_read_only;                     /* If mounted read-only. */
        int ml_debug_calls;        /* Extra debug info on each FUSE call. */
      #endif

      #ifdef HAVE_LIBVIRT
        /* Used by lib/libvirt-auth.c. */
      #define NR_CREDENTIAL_TYPES 9
        unsigned int nr_supported_credentials;
        int supported_credentials[NR_CREDENTIAL_TYPES];
        const char *saved_libvirt_uri; /* Doesn't need to be freed. */
        bool wrapper_warning_done;
        unsigned int nr_requested_credentials;
        virConnectCredentialPtr requested_credentials;
      #endif

        /* Cached features. */
        struct cached_feature *features;
        size_t nr_features;

        /* Used by lib/info.c.  -1 = not tested or error; else 0 or 1. */
        int qemu_img_supports_U_option;
      };

THE libguestfs handle. 👑 Like genuinely, this is the main character of the entire library. Everything else is supporting cast. No notes.

---

🧩 Structure lib/guestfs-internal.h:version

      struct version {
        int v_major;
        int v_minor;
        int v_micro;
      };

Used for storing major.minor.micro version numbers — the classic trio. See lib/version.c for more information. 🎀

---

📁 File lib/guid.c

🔧 Function lib/guid.c:guestfs_int_validate_guid

      int
      guestfs_int_validate_guid (const char *str)

Check whether a string that's supposed to contain a GUID actually contains it — because sometimes a string is lying to you and honesty is a whole thing. 💀 It can recognize strings either as {21EC2020-3AEA-1069-A2DD-08002B30309D} or 21EC2020-3AEA-1069-A2DD-08002B30309D. Both fits, both slay. Curly braces optional, bestie.

---

📁 File lib/handle.c

This file deals with the guestfs_h handle — creating it, closing it, and initializing/setting/getting fields. Basically the handle's whole life admin. 🌸

🔧 Function lib/handle.c:init_libguestfs

      static void
      init_libguestfs (void)

No initialization is required by libguestfs itself, but libvirt and libxml2 do require initialization if they might be called from multiple threads. So we get this constructor function, which is called when libguestfs is first loaded. Considerate of us, tbh. 🫶

🔧 Function lib/handle.c:shutdown_backend

      static int
      shutdown_backend (guestfs_h *g, int check_for_errors)

This function is the common path for shutting down the backend qemu process. Both of the exit doors go through here:

• guestfs_shutdown calls shutdown_backend with check_for_errors=1.
• guestfs_close calls shutdown_backend with check_for_errors=0.

check_for_errors is basically a hint to the backend about whether we actually care about errors or not. In the libvirt case it can be used to optimize the shutdown for speed when we don't care — like, we're leaving, why are we checking the mirrors. 💅

🔧 Function lib/handle.c:close_handles

      static void
      close_handles (void)

Close all open handles (called from atexit(3)). The cleanup crew. 🧹

🔧 Function lib/handle.c:guestfs_int_get_backend_setting_bool

      int
      guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)

This is a convenience function, but we might consider exporting it as an API in future. For now it stays internal — private account, no public posting. 🙈

---

📁 File lib/info.c

🔧 Function lib/info.c:qemu_img_supports_U_option

      static int
      qemu_img_supports_U_option (guestfs_h *g)

Test if the qemu-img info command supports the -U option to disable locking. The result gets memoized in the handle, so we only ask once — queen behavior, honestly. 🍓

Ngl, this option was added in qemu 2.11. We can remove this test when we can assume everyone is using qemu >= 2.11.

---

📁 File lib/inspect-icon.c

🔧 Function lib/inspect-icon.c:guestfs_int_download_to_tmp

      char *
      guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
                                   const char *extension,
                                   uint64_t max_size)

Download a guest file to a local temporary file. Very "grab that for me real quick" energy. ✨

The name of the temporary (downloaded) file is returned. The caller must free the pointer, but does not need to delete the temporary file — it will be deleted when the handle is closed. So like, free the name, not the file. Two different things, don't mix them up bestie. 😭

The name of the temporary file is randomly generated, but an extension can be specified using extension (or pass NULL for none). Little random name, cute little extension. 🎀

...it flat-out refuses to download the guest file if it's bigger than max_size. And yeah, on this error and every other one? NULL comes back. 😭

---

🧚 lib/launch-direct.c

This is where the direct backend actually lives, bestie. The whole implementation, right here.

Need the deep lore? Go read BACKENDS in guestfs(3). ✨

lib/launch-direct.c:add_drive_standard_params

static int
add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
                           struct qemuopts *qopts,
                           size_t i, struct drive *drv)

It adds all the standard bits of the -drive parameter. The bread and butter of the drive string, basically. 🎀

lib/launch-direct.c:add_device_blocksize_params

static int
add_device_blocksize_params (guestfs_h *g, struct qemuopts *qopts,
                           struct drive *drv)

This one handles the physical_block_size and logical_block_size elements of the -device parameter. Very demure, very block-sized. 💅

lib/launch-direct.c:launch_passt

static int
launch_passt (guestfs_h *g, long *passt_pid, char (*sockpath)[UNIX_PATH_MAX])

Launches passt in a way that daemonizes it. Iconic behaviour honestly.

So, the terms, fr fr:

• On error → -1 is returned, and passt_pid and sockpath are not modified. (Respect for your variables, honestly.)
• On success → 0 is returned. passt_pid holds the PID of the passt background process, and sockpath holds the pathname of the unix domain socket where passt will accept a single connection. 🦋

---

🌸 lib/launch-libvirt.c

lib/launch-libvirt.c:get_source_format_or_autodetect

static char *
get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)

Returns drv->src.format, but if that's NULL it goes ahead and autodetects the format. Ngl, it's doing the most.

Here's the tea ☕: libvirt has disabled the whole disk-format-detection feature, unless the administrator sets allow_disk_format_probing=1 in /etc/libvirt/qemu.conf. And there's literally no way to check whether that option is set. So we just have to do the format detection ourselves here, using qemu-img, and pass the answer over to libvirt. 🙈

⚠️ Heads up, this can still be a security issue. So in most cases the recommendation is: users should pass the format to libguestfs, which will faithfully pass it straight through to libvirt without doing any autodetection at all. No cap. 🔥

The caller must free the returned string. And on error this function sets the error in the handle and returns NULL. Classic.

lib/launch-libvirt.c:make_qcow2_overlay

static char *
make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
                    const char *format)

Creates a qcow2 format overlay, with the given backing_drive (a file!). The format parameter is the backing file format. And format can be NULL — in that case the backing format gets determined automatically. ✨

What's it for? Creating the appliance overlay, and also for read-only drives. Multi-purpose queen. 👑

---

🎀 lib/launch.c

This file implements guestfs_launch from guestfs(3). Main character energy.

Most of the actual work is done by the backends (peep BACKEND in guestfs(3)), which live in lib/launch-direct.c, lib/launch-libvirt.c etc. So this file is mostly just passing calls through to the current backend. The middleman. The vibe coordinator. 🫶

lib/launch.c:guestfs_int_launch_send_progress

void
guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)

Sends a launch progress message. Launching the appliance generates approximate progress messages, and currently they're defined like this:

 0 / 12: launch clock starts
 3 / 12: appliance created
 6 / 12: detected that guest kernel started
 9 / 12: detected that /init script is running
12 / 12: launch completed successfully

Notes, bestie, read these:

1. This is not a documented ABI and the behaviour may be changed or removed in future. 💀
2. Messages are only sent if more than 5 seconds has elapsed since the launch clock started.
3. There is a hack in lib/proto.c to make this work. (iykyk)

lib/launch.c:guestfs_int_timeval_diff

int64_t
guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)

Computes y - x and hands you back the result in milliseconds. Math girl summer.

It's approximately the same as this code: http://www.mpp.mpg.de/~huber/util/timevaldiff.c

lib/launch.c:guestfs_int_unblock_sigterm

void
guestfs_int_unblock_sigterm (void)

Unblocks the SIGTERM signal. Call this after fork(2), so that the parent process can send SIGTERM to the child process in case SIGTERM was blocked. See https://bugzilla.redhat.com/1460338. 🐛

lib/launch.c:guestfs_impl_max_disks

int
guestfs_impl_max_disks (guestfs_h *g)

Returns the maximum number of disks that are allowed to be added to the backend. And yes, it's backend dependent — so like, don't assume. 🌈

lib/launch.c:guestfs_impl_wait_ready

int
guestfs_impl_wait_ready (guestfs_h *g)

Implementation of guestfs_wait_ready in guestfs(3). Fun history lesson: you had to call this function after launch in versions ≤ 1.0.70, but nowadays it's an (almost) no-op. Glow-up of the century. ✨

lib/launch.c:guestfs_int_register_backend

void
guestfs_int_register_backend (const char *name, const struct backend_ops *ops)

When the library is loaded, each backend calls this function to register itself in a global list. It's giving sign-up sheet at the group chat. 💖

lib/launch.c:guestfs_int_set_backend

int
guestfs_int_set_backend (guestfs_h *g, const char *method)

Implementation of guestfs_set_backend in guestfs(3). Two things you need to know:

• Callers must ensure this is only called in the config state.
• This shouldn't call error since it may be called early in handle initialization. It can return an error code however. 🤷‍♀️

lib/launch.c:guestfs_int_passt_runnable

bool
guestfs_int_passt_runnable (guestfs_h *g)

Returns true if we can call passt --help, and it exits with status 0 or 1. That's it, that's the check.

(And like — passt-0^20230222.g4ddbcb9-2.el9_2.x86_64 terminates with status 1 in response to --help, which is arguably wrong, and potentially subject to change, but honestly it doesn't really matter.) 💀

---

🦋 lib/private-data.c

This implements a private data area where libguestfs C API users can attach arbitrary little pieces of data to a guestfs_h handle. Cute, right?

Full details live in PRIVATE DATA AREA in guestfs(3). ✨

Oh, and language bindings don't generally expose this — largely because in non-C languages it's easy to associate data with handles in other ways (hash tables or maps, bestie). So they just don't. 🎀

Structure lib/private-data.c:pda_entry

struct pda_entry {
  char *key;                    /* key */
  void *data;                   /* opaque user data pointer */
};

Internally, the private data area is stored as a gnulib hash table containing pda_entry structures. Very organized of it.

📌 Note: the private data area is allocated lazily, since the vast majority of callers will never use it. Which means g->pda is likely to be NULL. Don't panic. 🙈

---

💜 lib/proto.c

Okay so this is the code that sends and receives RPC messages and — for certain types of message — performs file transfers. It's driven from the generated actions (lib/actions-*.c). There are five different cases to consider, and I'm gonna walk you through each one:

1. A non-daemon function (eg. guestfs_set_verbose in guestfs(3)). There is no RPC involved at all — it's all handled inside the library. Zero drama. 💅
2. A simple RPC (eg. guestfs_mount in guestfs(3)). We write the request, then read the reply. The sequence of calls is:

guestfs_int_send
guestfs_int_recv

3. An RPC with FileIn parameters (eg. guestfs_upload in guestfs(3)). We write the request, then write the file(s), then read the reply. The sequence of calls is:

guestfs_int_send
guestfs_int_send_file  (possibly multiple times)
guestfs_int_recv

4. An RPC with FileOut parameters (eg. guestfs_download in guestfs(3)). We write the request, then read the reply, then read the file(s). The sequence of calls is:

guestfs_int_send
guestfs_int_recv
guestfs_int_recv_file  (possibly multiple times)

5. Both FileIn and FileOut parameters. There are no calls like this in the current API, but if there were, they'd be implemented as a combination of cases 3 and 4. Combo meal. 🍓

All read/write/etc operations are performed using the current connection module (g->conn). And during operations, the connection module transparently handles log messages that appear on the console. So you don't have to worry about them. 🧚

lib/proto.c:child_cleanup

static void
child_cleanup (guestfs_h *g)

This gets called if we detect EOF, ie. qemu died. 😭 Rest in peace.

lib/proto.c:guestfs_int_progress_message_callback

void
guestfs_int_progress_message_callback (guestfs_h *g,
                                       const guestfs_progress *message)

A convenient little wrapper to generate a progress message callback. 🎀

lib/proto.c:guestfs_int_log_message_callback

void
guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)

Connection modules call us back here when they get a log message. That's the whole vibe. 💖

lib/proto.c:check_daemon_socket

static ssize_t
check_daemon_socket (guestfs_h *g)

Before writing to the daemon socket, it checks the read side of the daemon socket for any of these conditions:

• error → return -1
• daemon cancellation message → return -2
• progress message → handle it right here, right now
• end of input or appliance exited unexpectedly → return 0
• anything else → return 1

lib/proto.c:guestfs_int_send_file

int
guestfs_int_send_file (guestfs_h *g, const char *filename)

Sends a file. Returns 0 on success, -1 for error, and -2 if the daemon cancelled — in which case we must read the error message. Notes taken. 📝

lib/proto.c:send_file_data

static int
send_file_data (guestfs_h *g, const char *buf, size_t len)

Sends a chunk of file data. Chunk by chunk, bestie. 🧩

lib/proto.c:send_file_cancellation

static int
send_file_cancellation (guestfs_h *g)

Sends a cancellation message. ✨

lib/proto.c:send_file_complete

static int
send_file_complete (guestfs_h *g)

Sends a file complete chunk. The grand finale. 🎬

lib/proto.c:recv_from_daemon

static int
recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)

Reads a single message, file chunk, launch flag or cancellation flag from the daemon. If something was read, it returns 0; otherwise -1.

Both size_rtn and buf_rtn must be passed by the caller as non-NULL. Non-negotiable. 💅

*size_rtn returns the size of the returned message, or it may be GUESTFS_LAUNCH_FLAG or GUESTFS_CANCEL_FLAG.

*buf_rtn comes back containing the message (if any), or it'll be set to NULL. And *buf_rtn must be freed by the caller. Don't forget, I'm serious. 😭

This also checks for EOF (appliance died) and passes that up through the child_cleanup function above.

Log messages and progress messages are handled transparently right here. No extra work for you. 🫶

lib/proto.c:guestfs_int_recv

int
guestfs_int_recv (guestfs_h *g, const char *fn,
                  guestfs_message_header *hdr,
                  guestfs_message_error *err,
                  xdrproc_t xdrp, char *ret)

Receive a reply. That's it, that's the whole vibe — it sits there waiting for the daemon to say something back 💌

---

✨ Function lib/proto.c:guestfs_int_recv_discard ✨

int
guestfs_int_recv_discard (guestfs_h *g, const char *fn)

Literally the same as guestfs_int_recv, except it ghosts the reply message entirely — no reading it, no keeping it, just yeet 🙈

Notes (XXX), and bestie these are important:

• This returns an int, but every single current caller ignores it. She's giving decorative return value 💅
• The error string may end up being set twice on error paths. Not a bug we're fixing today, just a known little quirk.

---

🌸 Function lib/proto.c:guestfs_int_recv_file 🌸

int
guestfs_int_recv_file (guestfs_h *g, const char *filename)

Returns -1 = error, 0 = EOF, >0 = more data. That's the whole contract, no cap 🫶

---

🦋 Function lib/proto.c:receive_file_data 🦋

static ssize_t
receive_file_data (guestfs_h *g, void **buf_r)

Receive a chunk of file data. Little bite-sized bites of the file, mwah 🍓

Returns -1 = error, 0 = EOF, >0 = more data.

---

📁 File lib/qemu.c 📁

Functions to handle qemu versions and features. Yes queen, we're talking to qemu now 👑

⭐ Function lib/qemu.c:generic_qmp_test ⭐

static int
generic_qmp_test (guestfs_h *g,
                  const char *qemu, const char *qmp_command, char **outp)

Run a generic QMP test on the QEMU binary. Generic in the sense that you hand it a qmp_command and it goes and asks 🔍

⭐ Function lib/qemu.c:parse_has_kvm ⭐

static int
parse_has_kvm (guestfs_h *g, const char *json)

Parse the json output from QMP query-kvm to find out if KVM is enabled on this machine. She reads JSON so you don't have to 📖

The JSON output looks like: {"return": {"enabled": true, "present": true}}

⭐ Function lib/qemu.c:guestfs_int_platform_has_kvm ⭐

int
guestfs_int_platform_has_kvm (guestfs_h *g, const char *qemu)

Test if the platform supports KVM. That's the whole point of her ✨

Only qemu "knows" this fact reliably — quotes around knows because honestly, iconic — so we run qemu, query it using the QMP query-kvm command, and parse the JSON output from that command. Trust but verify, bestie 💅

⭐ Function lib/qemu.c:guestfs_int_qemu_escape_param ⭐

char *
guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)

Escape a qemu parameter. Every , becomes ,,. That's it, that's the escape 😭

The caller must free the returned string. Do not forget. She is yours now, you own her.

XXX This functionality is now only used when constructing a qemu-img command in lib/create.c. We should extend the qemuopts library to cover this use case. Lowkey a to-do list item that has been sitting there a while 🙈

⭐ Function lib/qemu.c:guestfs_int_drive_source_qemu_param ⭐

char *
guestfs_int_drive_source_qemu_param (guestfs_h *g,
                                     const struct drive_source *src)

Useful function to format a drive + protocol for qemu. She's a little formatter, she formats 🎀

Note that the qemu parameter is the bit after file=. It is not escaped here, but would usually be escaped if passed to qemu as part of a full -drive parameter (but not for qemu-img(1)). So like, know your context before you go escaping things ✋

⭐ Function lib/qemu.c:guestfs_int_discard_possible ⭐

bool
guestfs_int_discard_possible (guestfs_h *g, struct drive *drv)

Test if discard is possible with the underlying file or device. This returns 1 if discard is possible. It returns 0 if not possible and sets the error to the reason why. So on failure you get an explanation, we love transparency 💖

This function is called when the user set discard == "enable". So if you flipped that switch, this is the girl doing the vibe check ✅

---

📁 File lib/rescue.c 📁

Support for virt-rescue(1). That's the whole description, she's short and sweet 🧚

---

📁 File lib/stringsbuf.c 📁

An expandable NULL-terminated vector of strings (like argv). Growable, null-terminated, everything you could want 🌈

Use the DECLARE_STRINGSBUF macro to declare the stringsbuf.

Note: Don't confuse this with stringsbuf in the daemon which is a different type with different methods. Two girls, same name, completely different personalities 💀

🎀 Function lib/stringsbuf.c:guestfs_int_add_string_nodup 🎀

void
guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)

Add a string to the end of the list. The "nodup" is the whole personality:

This doesn't call strdup(3) on the string, so the string itself is stored inside the vector. No copy, no extra memory, just vibes 🫶

🎀 Function lib/stringsbuf.c:guestfs_int_add_string 🎀

void
guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)

Add a string to the end of the list.

This makes a copy of the string. Responsible queen behaviour 💅

🎀 Function lib/stringsbuf.c:guestfs_int_add_sprintf 🎀

void
guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
                         const char *fs, ...)

Add a string to the end of the list.

Uses an sprintf-like format string when creating the string. So you can be fancy about it ✨

🎀 Function lib/stringsbuf.c:guestfs_int_end_stringsbuf 🎀

void
guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)

Finish the string buffer.

This adds the terminating NULL to the end of the vector. She's done, she's terminated, she's complete 🎀

🎀 Function lib/stringsbuf.c:guestfs_int_free_stringsbuf 🎀

void
guestfs_int_free_stringsbuf (struct stringsbuf *sb)

Free the string buffer and the strings. Both. All of it. Clean up your room bestie 🧹

---

📁 File lib/tmpdirs.c 📁

Handle temporary directories. Someone has to 🫡

🦋 Function lib/tmpdirs.c:set_abs_path 🦋

static int
set_abs_path (guestfs_h *g, const char *ctxstr,
              const char *tmpdir, char **tmpdir_ret)

We need to make all tmpdir paths absolute because lots of places in the code assume this. Do it at the time we set the path or read the environment variable (https://bugzilla.redhat.com/882417). No relative paths in this house 🚫

The ctxstr parameter is a string displayed in error messages giving the context of the operation (eg. name of environment variable being used, or API function being called). So when things go wrong, at least you know where 🕵️

🦋 Function lib/tmpdirs.c:guestfs_impl_get_tmpdir 🦋

char *
guestfs_impl_get_tmpdir (guestfs_h *g)

Implements the guestfs_get_tmpdir API.

Note this actually calculates the tmpdir, so it never returns NULL. She always has an answer, love that for her 💖

🦋 Function lib/tmpdirs.c:guestfs_impl_get_cachedir 🦋

char *
guestfs_impl_get_cachedir (guestfs_h *g)

Implements the guestfs_get_cachedir API.

Note this actually calculates the cachedir, so it never returns NULL. Same energy, different directory 🎀

🦋 Function lib/tmpdirs.c:guestfs_impl_get_sockdir 🦋

char *
guestfs_impl_get_sockdir (guestfs_h *g)

Implements the guestfs_get_sockdir API.

Note this actually calculates the sockdir, so it never returns NULL. Three for three, she's consistent 👑

🦋 Function lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir 🦋

int
guestfs_int_lazy_make_tmpdir (guestfs_h *g)

The g->tmpdir (per-handle temporary directory) is not created when the handle is created. Instead we create it lazily before the first time it is used, or during launch. She is a procrastinator and honestly? Same 😭

🦋 Function lib/tmpdirs.c:guestfs_int_make_temp_path 🦋

char *
guestfs_int_make_temp_path (guestfs_h *g,
                            const char *name, const char *extension)

Generate unique temporary paths for temporary files.

Returns a unique path or NULL on error. Unique, bestie, no collisions allowed ✨

🦋 Function lib/tmpdirs.c:guestfs_int_create_socketname 🦋

int
guestfs_int_create_socketname (guestfs_h *g, const char *filename,
                               char (*sockpath)[UNIX_PATH_MAX])

Create the path for a socket with the selected filename in the sockdir. Note she writes into a char (*sockpath)[UNIX_PATH_MAX] because the bound is baked into the type. Built-in safety, we stan 🫶

🦋 Function lib/tmpdirs.c:guestfs_int_make_pid_path 🦋

char *
guestfs_int_make_pid_path (guestfs_h *g, const char *name)

Generate unique paths for PID files.

Returns a unique path or NULL on error. On success, the pathname points under sockdir and not tmpdir; daemons that write PID files after dropping privileges may not have access to tmpdir. That's the whole reason, bestie — privilege dropping means permissions change, so we park the PID file somewhere they can still reach 💅

🦋 Function lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir 🦋

char *
guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)

Create the supermin appliance directory under cachedir, if it does not exist.

Sanity-check that the permissions on the cachedir are safe, in case it has been pre-created maliciously or tampered with. Yes, genuinely, we check — because trust issues are load-bearing security features here. 🔥

Returns the directory name which the caller must free. Yours now, you free it 🎀

🦋 Function lib/tmpdirs.c:guestfs_int_recursive_remove_dir 🦋

void
guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)

Recursively remove a temporary directory. If removal fails, just return (it's a temporary directory so it'll eventually be cleaned up by a temp cleaner). Not gonna stress about it, the system has a janitor 🧹

This is implemented using rm -rf because that's simpler and safer. Simplest is best-est 💀

---

📁 File lib/umask.c 📁

Return current umask in a thread-safe way.

glibc documents, but does not actually implement, a getumask(3) call. Documented and unimplemented? Fake behaviour? We hate to see it 😭

We use Umask from /proc/self/status for Linux ≥ 4.7. For older Linux and other Unix, this file implements an expensive but thread-safe way to get the current process's umask. Expensive but correct, that's the trade 🤝

Thanks to: Josh Stone, Jiri Jaburek, Eric Blake. Shoutout kings 👑

💜 Function lib/umask.c:guestfs_int_getumask 💜

int
guestfs_int_getumask (guestfs_h *g)

Returns the current process's umask. On failure, returns -1 and sets the error in the guestfs handle. Always tell them when it goes wrong 💅

💜 Function lib/umask.c:get_umask_from_proc 💜

static int
get_umask_from_proc (guestfs_h *g)

For Linux ≥ 4.7 get the umask from /proc/self/status. The fast path, the slay path ✨

On failure this returns -1. However if we could not open the /proc file or find the Umask entry in it, return -2 which causes the fallback path to run. -2 is basically a bat signal saying "girl, go the other way" 🦇

💜 Function lib/umask.c:get_umask_from_fork 💜

static int
get_umask_from_fork (guestfs_h *g)

Fallback method of getting the umask using fork. Old school, but she works 🫶

---

📁 File lib/unit-tests.c 📁

Unit tests of internal functions.

These tests may use a libguestfs handle, but must not launch the handle. Also, avoid long-running tests. Fast and no launching, those are the rules periodt ✋

⭐ Function lib/unit-tests.c:test_split ⭐

static void
test_split (void)

Test guestfs_int_split_string. Split her, verify her 🎀

⭐ Function lib/unit-tests.c:test_concat ⭐

static void
test_concat (void)

Test guestfs_int_concat_strings.

⭐ Function lib/unit-tests.c:test_join ⭐

static void
test_join (void)

Test guestfs_int_join_strings.

⭐ Function lib/unit-tests.c:test_validate_guid ⭐

static void
test_validate_guid (void)

Test guestfs_int_validate_guid.

⭐ Function lib/unit-tests.c:test_drive_name ⭐

static void
test_drive_name (void)

Test guestfs_int_drive_name.

⭐ Function lib/unit-tests.c:test_drive_index ⭐

static void
test_drive_index (void)

Test guestfs_int_drive_index.

⭐ Function lib/unit-tests.c:test_getumask ⭐

static void
test_getumask (void)

Test guestfs_int_getumask.

⭐ Function lib/unit-tests.c:test_command ⭐

static void
test_command (void)

Test guestfs_int_new_command etc. Yeah, "etc.", she's covering a whole family of command helpers 👑

XXX These tests could be made much more thorough. So far we simply test that it's not obviously broken. Honestly? Same philosophy as my life rn 💀

⭐ Function lib/unit-tests.c:test_qemu_escape_param ⭐

static void
test_qemu_escape_param (void)

Test guestfs_int_qemu_escape_param

XXX I wanted to make this test run qemu, passing some parameters which need to be escaped, but I cannot think of a way to do that without launching a VM. And launching a VM in a unit test is a hard no 🙈

⭐ Function lib/unit-tests.c:test_timeval_diff ⭐

static void
test_timeval_diff (void)

Test guestfs_int_timeval_diff.

---

📁 File lib/version.c 📁

This file provides simple version number management. Simple! Version! Management! 🎀

🌸 Function lib/version.c:guestfs_int_version_from_x_y 🌸

int
guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)

guestfs_int_version_from_x_y_re 💅 — so this one also parses a version out of a string, but it uses the re you hand it as the regular expression, and that regex must provide at least two matches, okurrr?

Returns -1 on failure (like failed integer parsing), 0 on missing match, and 1 on match and successful parsing. And v? Only changed on a successful match. no cap.

int
guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
                                 const char *str, const pcre2_code *re)

---

guestfs_int_version_from_x_y_or_x ✨ — parses a version from a string, either looking for a X.Y pattern or just treating the whole thing as a whole integer. flexible queen behavior.

Returns -1 on failure (like failed integer parsing), 0 on missing match, and 1 on match and successful parsing. v is changed only on a successful match — same rules as above, periodt.

int
guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
                                   const char *str)

---

guestfs_int_parse_unsigned_int 🌸 — parses small, unsigned ints, the kind you see in version numbers.

Heads up: this will fail with an error if there are trailing characters hanging around after the integer. so 12abc? not it.

Returns ≥ 0 on success, or -1 on failure.

int
guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)

---

🧚 File lib/wait.c

guestfs_int_waitpid 💖 — a safe version of waitpid(3) that retries if EINTR comes back at it.

Lowkey important note: this only needs to be used in the library, or in programs that install a non-restartable SIGCHLD handler — and that's not the case for any current libguestfs virt tools. so like, chill.

Here's the whole situation, because it's giving "why though": if the main program installs a SIGCHLD handler and sets it to be non-restartable, then what can happen is the library is sitting there waiting in a wait syscall, the child exits, SIGCHLD gets sent to the process, and the wait syscall returns EINTR 😭. Since the library cannot control the signal handler, we have to instead restart the wait syscall — and that is literally the entire purpose of this wrapper.

int
guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)

---

guestfs_int_waitpid_noerror 🫶 — like guestfs_int_waitpid, but ignore errors. that's it, that's the function.

void
guestfs_int_waitpid_noerror (pid_t pid)

---

guestfs_int_wait4 ⭐ — a safe version of wait4(2) which retries if EINTR is returned. same energy, different syscall.

int
guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
                   struct rusage *rusage, const char *errmsg)

---

🦋 File lib/whole-file.c

guestfs_int_read_whole_file 👑 — reads the whole file filename into a memory buffer. the entire thing. no crumbs.

The memory buffer is initialized and returned in data_r, and the size of the file in bytes comes back in size_r. The return buffer must be freed by the caller — yes, you, bestie. free it.

On error this sets the error in the handle and returns -1.

For the convenience of callers, the returned buffer is NUL-terminated (the NUL is not included in the size 🎀).

⚠️ The file must be a regular, local, trusted file. In particular, do not use this function to read files that might be under the control of an untrusted user, since that will lead to a denial-of-service attack. fr fr, do not do it.

int
guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
                             char **data_r, size_t *size_r)

---

💜 Subdirectory common/edit

🌈 File common/edit/file-edit.c

This file implements common file editing across a whole range of utilities, including guestfish(1), virt-edit(1), virt-customize(1) and virt-builder(1). it's giving shared infrastructure, it's giving main character utility file.

It contains the code for both interactive-(editor-)based editing and non-interactive editing using Perl snippets. both flavors, iconic.

---

edit_file_editor 🍓 — edit filename using the editor application you specify.

If backup_extension is not null, then a copy of filename is saved with backup_extension appended to its file name. cute lil backup moment.

If editor is null, then the $EDITOR environment variable will be queried for the editor application, leaving vi as fallback if it's not set. classic.

Returns -1 for failure, 0 on success, and 1 if the editor did not change the file (e.g. the user closed the editor without saving 👀).

int
edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
                  const char *backup_extension, int verbose)

---

edit_file_perl 🎀 — edit filename by running the specified perl_expr using Perl.

If backup_extension is not null, then a copy of filename is saved with backup_extension appended to its file name — same backup behavior as its sibling above ✨.

Returns -1 for failure, 0 on success.

int
edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
                const char *backup_extension, int verbose)

---

🧚 Subdirectory common/options

💅 File common/options/config.c

This file parses the guestfish configuration file — usually ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.

⚠️ Note that parse_config is called very early: before command line parsing, before the verbose flag has been set, even before the global handle g is opened. like, THAT early. so don't go assuming things exist yet.

---

🌸 File common/options/decrypt.c

This file implements the decryption of disk images, usually done before mounting their partitions. very "unlock the door before you walk in" of it.

---

make_mapname — makes a LUKS map name from the partition or logical volume name, eg. /dev/vda2 => cryptvda2, or /dev/vg-ssd/lv-root7 => cryptvgssdlvroot7.

And here's the honest disclaimer: note that, in logical volume device names, c_isalnum() eliminates the / separator from between the VG and the LV, so this mapping is not unique; but for our purposes, it will do. good enough slay 💀

static char *
make_mapname (const char *device)

---

inspect_do_decrypt — the simple implementation of decryption: look for any encrypted partitions and decrypt them, then rescan for VGs. look, decrypt, rescan, periodt.

void
inspect_do_decrypt (guestfs_h *g, struct key_store *ks)

---

⭐ File common/options/display-options.c

This file contains common code used to implement --short-options and --long-options in C virt tools. (The equivalent for OCaml virt tools is implemented by common/mltools/getopt.ml — just so you know the lore.)

These "hidden" options are used to implement bash tab completion. iykyk 🔥

---

display_short_options — implements the internal tool --short-options flag, which just lists out the short options available. Used by bash completion. yes, that's why tab goes brrr.

void
display_short_options (const char *format)

---

display_long_options — implements the internal tool --long-options flag, which just lists out the long options available. Used by bash completion. same vibe, longer names 💖

void
display_long_options (const struct option *long_options)

---

🦋 File common/options/domain.c

Implements the guestfish (and other tools) -d option. short flag, big job.

---

add_libvirt_drives — this function is called when a user invokes guestfish -d guest.

Returns the number of drives added (> 0), or -1 for failure.

int
add_libvirt_drives (guestfs_h *g, const char *guest)

---

🌈 File common/options/inspect.c

This file implements inspecting the guest and mounting the filesystems found in the right places. It's used by the guestfish(1) -i option and some utilities such as virt-cat(1). it's the "find everything and put it where it belongs" file 👑

---

inspect_mount_handle — this function implements the -i option. that's the whole description bestie, it's a whole vibe in one function.

void
inspect_mount_handle (guestfs_h *g, struct key_store *ks)

---

print_inspect_prompt — this function is called only if inspect_mount_root was called, and only after we've printed the prompt in interactive mode. very specific conditions, respect them 🙈

void
print_inspect_prompt (void)

---

🍓 File common/options/keys.c

read_key — reads a passphrase (Key) from /dev/tty with echo off. your typing stays your business 🤫

The caller (fish/cmds.c) will call free on the string afterwards — so like, it's on them, but also don't forget.

The entered string is prefixed with text:... to avoid ambiguity (with libguestfs >= 1.60). Base64 encoding cannot be used here. just noting it before you ask.

Based on the code in cryptsetup file lib/utils.c. credit where it's due 🫶

char *
read_key (const char *param)

---

🧚 File common/options/options.c

This file contains common options parsing code used by guestfish and many other tools which share a common options syntax.

For example, guestfish, virt-cat, virt-ls etc all support the -a option, and that is handled in all of those tools using a macro OPTION_a defined in fish/options.h.

There are a lot of common global variables used: drvs accumulates the list of drives, verbose for the -v flag, and many more. so many more. it's giving shared state, it's giving "everything knows everything".

---

option_a — handles the guestfish -a option on the command line.

void
option_a (const char *arg, const char *format, int blocksize,
          struct drv **drvsp)

---

option_d — handles the -d option when passed on the command line.

void
option_d (const char *arg, struct drv **drvsp)

---

display_mountpoints_on_failure — if the -m option fails on any command, display a useful error message listing the mountpoints. basically the "here's what you could have mounted" note 😭 helpful though!

static void
display_mountpoints_on_failure (const char *mp_device,
                                const char *user_supplied_options)

---

💜 File common/options/uri.c

This file implements URI parsing for the -a option, in many utilities including guestfish(1), virt-cat(1), virt-builder(1), virt-customize(1), etc. URIs, handled, everywhere 🔥

---

🎀 Subdirectory common/parallel

✨ File common/parallel/domains.c

This file is used by virt-df and some of the other tools when they're implicitly asked to operate over all libvirt domains (VMs) — for example, when virt-df is called without specifying any particular disk image.

It hides the complexity of querying the list of domains from libvirt. it's the friend who does the talking to libvirt so you don't have to 💅

---

free_domains — frees up everything allocated by get_all_libvirt_domains. cleanup queen.

void
free_domains (void)

---

get_all_libvirt_domains — reads all libguest guests into the global variables domains and nr_domains. The guests are ordered by name. alphabetized, as they should be 🌸

⚠️ This exits on any error. not returns — exits. dramatic but honest.

void
get_all_libvirt_domains (const char *libvirt_uri)

---

💖 File common/parallel/estimate-max-threads.c

estimate_max_threads — this function uses the output of free -m to estimate how many libguestfs appliances could be safely started in parallel. Note that it always returns ≥ 1. always at least one, bestie, that's the floor 🫶

size_t
estimate_max_threads (void)

---

read_line_from 🦋 — static helper that reads a line from cmd.

static char *
read_line_from (const char *cmd)

Run an external command and read the first line of its output. Classic.

📁 Subdirectory common/parallel

🧵 File common/parallel/parallel.c

This file is the moment when virt-df and some of the other tools need to run a whole bunch of parallel libguestfs instances so they can operate on a huge number of libvirt domains without it taking a million years. Efficiency slay 💅

It implements a multithreaded work queue ✨ And on top of that, it reorders the output so the output still appears in the same order as the input — like, still ordered alphabetically. Bestie it remembers the order, that's so thoughtful 🫶

Function common/parallel/parallel.c:start_threads

int
start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)

Run the threads and work through the global list of libvirt domains. Go go go 🏃‍♀️

option_P is literally whatever the user passed in the -P option, or 0 if the user didn't use the -P option — and in that case the number of threads is chosen heuristically. Vibes-based threading, kind of iconic ngl.

options_handle (which may be NULL) is the global guestfs handle created by the options mini-library.

The work function (work) should do the work — inspecting the domain, etc. — on domain index i. But ⚠️ it must not print out any result directly. Instead it prints anything it needs to the supplied FILE *. The work function should return 0 on success or -1 on error.

The start_threads function returns 0 if all work items completed successfully, or -1 if there was an error. Simple as that 💖

---

📁 Subdirectory common/progress

📊 File common/progress/progress.c

This file implements the progress bar in guestfish(1), virt-resize(1) and virt-sparsify(1). The little bar that keeps you company while everything loads 🎀

Function common/progress/progress.c:progress_bar_init

struct progress_bar *
progress_bar_init (unsigned flags)

Initialize a progress bar struct.

It is intended that you can reuse the same struct for multiple commands (but only in a single thread). Call progress_bar_reset before each new command. Reuse era 🔥

Function common/progress/progress.c:progress_bar_free

void
progress_bar_free (struct progress_bar *bar)

Free a progress bar struct. Bye bestie 👋

Function common/progress/progress.c:progress_bar_reset

void
progress_bar_reset (struct progress_bar *bar)

This function should be called just before you issue any command.

Function common/progress/progress.c:estimate_remaining_time

static double
estimate_remaining_time (struct progress_bar *bar, double ratio)

Return remaining time estimate (in seconds) for current call.

This returns the running mean estimate of remaining time, but if the latest estimate of total time is greater than two s.d.'s from the running mean then we don't print anything because we're not confident that the estimate is meaningful. (Returned value is <0.0 when nothing should be printed). Honestly? Respect the humility 😭💀

Function common/progress/progress.c:progress_bar_set

void
progress_bar_set (struct progress_bar *bar,
                  uint64_t position, uint64_t total)

Set the position of the progress bar.

This should be called from a GUESTFS_EVENT_PROGRESS event callback.

---

📁 Subdirectory common/qemuopts

🧪 File common/qemuopts/qemuopts-tests.c

Unit tests of internal functions.

These tests may use a libguestfs handle, but must not launch the handle. Also, avoid long-running tests. Keep it speedy, we're not waiting around 🦋

⚙️ File common/qemuopts/qemuopts.c

Mini-library for writing qemu command lines and qemu config files.

There are some shortcomings with the model used for qemu options which aren't clear until you try to convert options into a configuration file. However if we attempted to model the options in more detail then this library would be both very difficult to use and incompatible with older versions of qemu. Hopefully the current model is a decent compromise. Compromise is growth 🌱

For reference here are the problems:

• There's inconsistency in qemu between options and config file, eg. -smp 4 becomes:

[smp-opts]
  cpus = "4"

• Similar to the previous point, you can write either -smp 4 or -smp cpus=4 (although this won't work in very old qemu). When generating a config file you need to know the implicit key name. Implicit keys are lowkey a jump scare 🙈
• In -opt key=value,... the key is really a tree/array specifier. The way this works is complicated but hinted at here: http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
• Some options are syntactic sugar. eg. -kernel foo is sugar for -machine kernel=foo.

Function common/qemuopts/qemuopts.c:qemuopts_create

struct qemuopts *
qemuopts_create (void)

Create an empty list of qemu options.

The caller must eventually free the list by calling qemuopts_free. Don't just leave it there ✨

Returns NULL on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_free

void
qemuopts_free (struct qemuopts *qopts)

Free the list of qemu options.

Function common/qemuopts/qemuopts.c:qemuopts_add_flag

int
qemuopts_add_flag (struct qemuopts *qopts, const char *flag)

Add a command line flag which has no argument. eg:

qemuopts_add_flag (qopts, "-no-user-config");

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_add_arg

int
qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)

Add a command line flag which has a single argument. eg:

qemuopts_add_arg (qopts, "-m", "1024");

Don't use this if the argument is a comma-separated list, since quoting will not be done properly. See qemuopts_add_arg_list. Quoting will betray you bestie 😭

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_add_arg_format

int
qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
                         const char *fs, ...)

Add a command line flag which has a single formatted argument. eg:

qemuopts_add_arg_format (qopts, "-m", "%d", 1024);

Don't use this if the argument is a comma-separated list, since quoting will not be done properly. See qemuopts_add_arg_list. Same warning, same energy 💀

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote

int
qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
                          const char *value)

This is like qemuopts_add_arg except that no quoting is done on the value.

For qemuopts_to_script and qemuopts_to_channel, this means that neither shell quoting nor qemu comma quoting is done on the value.

For qemuopts_to_argv this means that qemu comma quoting is not done.

qemuopts_to_config* will fail.

You should use this with great care. Like, Great Care. Main character danger energy 🔥

Function common/qemuopts/qemuopts.c:qemuopts_start_arg_list

int
qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)

Start an argument that takes a comma-separated list of fields.

Typical usage is like this (with error handling omitted):

qemuopts_start_arg_list (qopts, "-drive");
qemuopts_append_arg_list (qopts, "file=foo");
qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
qemuopts_end_arg_list (qopts);

which would construct -drive file=foo,if=ide 🎉

See also qemuopts_add_arg_list for a way to do simple cases in one call.

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_add_arg_list

int
qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
                       const char *elem0, ...)

Add a command line flag which has a list of arguments. eg:

qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);

This is turned into a comma-separated list, like: -drive file=foo,if=ide. Note that this handles qemu quoting properly, so individual elements may contain commas and this will do the right thing. It ate, no notes 💅

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_set_binary

int
qemuopts_set_binary (struct qemuopts *qopts, const char *binary)

Set the qemu binary name.

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch

int
qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)

Set the qemu binary name to qemu-system-[arch].

As a special case if arch is NULL, the binary is set to the KVM binary for the current host architecture:

qemuopts_set_binary_by_arch (qopts, NULL);

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_to_script

int
qemuopts_to_script (struct qemuopts *qopts, const char *filename)

Write the qemu options to a script.

qemuopts_set_binary* must be called first. Non-negotiable ✋

The script file will start with #!/bin/sh and will be chmod to mode 0755.

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:shell_quote

static void
shell_quote (const char *str, FILE *fp)

Print str to fp, shell-quoting it if necessary.

Function common/qemuopts/qemuopts.c:shell_and_comma_quote

static void
shell_and_comma_quote (const char *str, FILE *fp)

Print str to fp doing both shell and qemu comma quoting. Double duty queen 👑

Function common/qemuopts/qemuopts.c:qemuopts_to_channel

int
qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)

Write the qemu options to a FILE *fp.

qemuopts_set_binary* must be called first.

Only the qemu command line is written. The caller may need to add #!/bin/sh and may need to chmod the resulting file to 0755. DIY moment 🎀

Returns 0 on success. Returns -1 on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_to_argv

char **
qemuopts_to_argv (struct qemuopts *qopts)

Return a NULL-terminated argument list, of the kind that can be passed directly to execv(3).

qemuopts_set_binary* must be called first. It will be returned as argv[0] in the returned list.

The list of strings and the strings themselves must be freed by the caller. Yes, all of them. Every single one 🔍

Returns NULL on error, setting errno.

Function common/qemuopts/qemuopts.c:qemuopts_to_config_file

int
qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)

Write the qemu options to a qemu config file, suitable for reading in using qemu -readconfig filename.

Note that qemu config files have limitations on content and quoting, so not all qemuopts structs can be written (this function returns an error in these cases). For more information see https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html https://bugs.launchpad.net/qemu/+bug/1686364

Also, command line argument names and config file sections sometimes have different names. For example the equivalent of -m 1024 is:

[memory]
  size = "1024"

Same info, different outfit. Live with it 💜

Okay so this bit literally just doesn't try to convert between the two forms at all — you're on your own for that one, bestie, you just gotta know how to do it yourself.

Returns 0 on success. Returns -1 on error, setting errno. Classic.

Function common/qemuopts/qemuopts.c:qemuopts_to_config_channel

int
qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)

Same energy as qemuopts_to_config_file, except this one writes to a FILE *fp 🫶

---

💖 Subdirectory common/utils

🌸 File common/utils/cleanups.c

Libguestfs uses CLEANUP_* macros to simplify temporary allocations — like, it does your cleanup chores for you. They're implemented using the __attribute__((cleanup)) feature of gcc and clang. Typical usage is:

fn ()
{
  CLEANUP_FREE char *str = NULL;
  str = safe_asprintf (g, "foo");
  // str is freed automatically when the function returns
}

There are a few catches to be aware of with the cleanup mechanism (read these, seriously):

• If a cleanup variable is not initialized, then you can end up calling free(3) with an undefined value, resulting in the program crashing. For this reason, you should usually initialize every cleanup variable with something, eg. NULL
• Don't mark variables holding return values as cleanup variables.
• The main() function shouldn't use cleanup variables since it is normally exited by calling exit(3), and that doesn't call the cleanup handlers.

The functions in this file are used internally by the CLEANUP_* macros. Don't call them directly. Like, not even once 🙈

🦋 File common/utils/gnulib-cleanups.c

Yeah okay, so libguestfs uses CLEANUP_* macros to simplify temporary allocations (we're back here again, it's giving déjà vu 💀). They are implemented using the __attribute__((cleanup)) feature of gcc and clang. Typical usage is:

fn ()
{
  CLEANUP_FREE char *str = NULL;
  str = safe_asprintf (g, "foo");
  // str is freed automatically when the function returns
}

There are a few catches to be aware of with the cleanup mechanism:

• If a cleanup variable is not initialized, then you can end up calling free(3) with an undefined value, resulting in the program crashing. For this reason, you should usually initialize every cleanup variable with something, eg. NULL
• Don't mark variables holding return values as cleanup variables.
• The main() function shouldn't use cleanup variables since it is normally exited by calling exit(3), and that doesn't call the cleanup handlers.

The functions in this file are used internally by the CLEANUP_* macros. Don't call them directly — the macros handle it, bestie.

🎀 File common/utils/guestfs-utils.h

This header file is included in all "frontend" parts of libguestfs, namely the library, non-C language bindings, virt tools and tests.

The daemon does not use this header. If you need a place to put something shared with absolutely everything including the daemon, put it in lib/guestfs-internal-all.h

If a definition is only needed by a single component of libguestfs (eg. just the library, or just a single virt tool) then it should not be here! Putting it here is a crime and I will know 🌈

⭐ File common/utils/libxml2-writer-macros.h

These macros make it easier to write XML. To use them correctly you must be aware of these assumptions:

• The xmlTextWriterPtr is called xo. It is used implicitly by all the macros.
• On failure, a function called xml_error is called which you must define (usually as a macro). You must use CLEANUP_* macros in your functions if you want correct cleanup of local variables along the error path.
• All the "bad" casting is hidden inside the macros.

Definition common/utils/libxml2-writer-macros.h:start_element

#define start_element

To define an XML element use:

start_element ("name") {
  ...
} end_element ();

which produces <name>...</name>

Definition common/utils/libxml2-writer-macros.h:empty_element

#define empty_element

To define an empty element:

empty_element ("name");

which produces <name/>

Definition common/utils/libxml2-writer-macros.h:single_element

#define single_element

To define a single element with no attributes containing some text:

single_element ("name", text);

which produces <name>text</name>

Definition common/utils/libxml2-writer-macros.h:single_element_format

#define single_element_format

To define a single element with no attributes containing some text using a format string:

single_element_format ("cores", "%d", nr_cores);

which produces <cores>4</cores>

Definition common/utils/libxml2-writer-macros.h:attribute

#define attribute

To define an XML element with attributes, use:

start_element ("name") {
  attribute ("foo", "bar");
  attribute_format ("count", "%d", count);
  ...
} end_element ();

which produces <name foo="bar" count="123">...</name>

Definition common/utils/libxml2-writer-macros.h:attribute_ns

#define attribute_ns

attribute_ns (prefix, key, namespace_uri, value) defines a namespaced attribute. fancy ✨

Definition common/utils/libxml2-writer-macros.h:string

#define string

To define a verbatim string, use:

string ("hello");

Definition common/utils/libxml2-writer-macros.h:string_format

#define string_format

To define a verbatim string using a format string, use:

string ("%s, world", greeting);

Definition common/utils/libxml2-writer-macros.h:base64

#define base64

To write a string encoded as base64:

base64 (data, size);

Definition common/utils/libxml2-writer-macros.h:comment

#define comment

To define a comment in the XML, use:

comment ("number of items = %d", nr_items);

🧚 File common/utils/stringlists-utils.c

Utility functions used by the library, tools and language bindings.

These functions must not call internal library functions such as safe_*, error or perrorf, or any guestfs_int_*. Rules are rules 💅

Function common/utils/stringlists-utils.c:guestfs_int_split_string

char **
guestfs_int_split_string (char sep, const char *str)

Split string at separator character sep, returning the list of strings. Returns NULL on memory allocation failure.

Note (assuming sep is :):

• str == NULL — aborts 💀
• str == "" — returns []
• str == "abc" — returns ["abc"]
• str == ":" — returns ["", ""]

💜 File common/utils/utils.c

Utility functions used by the library, tools and language bindings.

These functions must not call internal library functions such as safe_*, error or perrorf, or any guestfs_int_*. Same rule as above, no cap.

Function common/utils/utils.c:guestfs_int_replace_string

char *
guestfs_int_replace_string (const char *str, const char *s1, const char *s2)

Replace every instance of s1 appearing in str with s2. A newly allocated string is returned which must be freed by the caller. If allocation fails this can return NULL.

For example:

replace_string ("abcabb", "ab", "a");

would return acab.

Function common/utils/utils.c:guestfs_int_exit_status_to_string

char *
guestfs_int_exit_status_to_string (int status, const char *cmd_name,
                                  char *buffer, size_t buflen)

Translate a wait/system exit status into a printable string.

Function common/utils/utils.c:guestfs_int_random_string

int
guestfs_int_random_string (char *ret, size_t len)

Return a random string of characters.

Notes:

• The ret buffer must have length len+1 in order to store the final \0 character.
• There is about 5 bits of randomness per output character (so about 5*len bits of randomness in the resulting string).

Function common/utils/utils.c:guestfs_int_drive_name

char *
guestfs_int_drive_name (size_t index, char *ret)

This turns a drive index (eg. 27) into a drive name (eg. ab).

Drive indexes count from 0. The return buffer has to be large enough for the resulting string, and the returned pointer points to the end of the string.

https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/

Function common/utils/utils.c:guestfs_int_drive_index

ssize_t
guestfs_int_drive_index (const char *name)

The opposite of guestfs_int_drive_name. Take a string like ab and return the index (eg 27).

Note that you must remove any prefix such as hd, sd etc, or any partition number before calling the function.

Function common/utils/utils.c:guestfs_int_is_true

int
guestfs_int_is_true (const char *str)

Similar to Tcl_GetBoolean.

Function common/utils/utils.c:guestfs_int_string_is_valid

bool
guestfs_int_string_is_valid (const char *str,
                             size_t min_length, size_t max_length,
                             int flags, const char *extra)

Check a string for validity, that it contains only certain characters, and minimum and maximum length. This function is usually wrapped in a VALID_* macro, see lib/drives.c for an example.

str is the string to check.

min_length and max_length are the minimum and maximum length checks. 0 means no check.

The flags control:

• VALID_FLAG_ALPHA — 7-bit ASCII-only alphabetic characters are permitted.
• VALID_FLAG_DIGIT — 7-bit ASCII-only digits are permitted.

extra is a set of extra characters permitted, in addition to alphabetic and/or digits. (extra = NULL for no extra).

Returns boolean true if the string is valid (passes all the tests), or false if not.

Function common/utils/utils.c:guestfs_int_fadvise_normal

void
guestfs_int_fadvise_normal (int fd)

Hint that we will read or write the file descriptor normally.

On Linux, this clears the FMODE_RANDOM flag on the file [see below] and sets the per-file number of readahead pages to equal the block device readahead setting.

It's OK to call this on a non-file since we ignore failure as it is only a hint. no stress 🌿

Function common/utils/utils.c:guestfs_int_fadvise_sequential

void
guestfs_int_fadvise_sequential (int fd)

Hint that we will read or write the file descriptor sequentially.

On Linux, this clears the FMODE_RANDOM flag on the file [see below] and sets the per-file number of readahead pages to twice the block device readahead setting.

It's OK to call this on a non-file since we ignore failure as it is only a hint.

Function common/utils/utils.c:guestfs_int_fadvise_random

void
guestfs_int_fadvise_random (int fd)

Hint that we will read or write the file descriptor randomly.

On Linux, this sets the FMODE_RANDOM flag on the file. The effect of this flag is to:

• Disable normal sequential file readahead.
• If any read of the file misses in the page cache, 2MB are read into the page cache. [I think — I'm not sure I totally understand what this is doing]

It's totally fine to call this on a non-file, bestie, because we just ignore failure — it's only a hint, no cap.

---

🔧 Function common/utils/utils.c:guestfs_int_fadvise_noreuse

void
guestfs_int_fadvise_noreuse (int fd)

A lil hint that we're only gonna access the data once.

On Linux, this literally does nothing. Iconic behaviour of a hint, honestly.

It's OK to call this on a non-file since we ignore failure — it's only a hint. 💅

🔧 Function common/utils/utils.c:guestfs_int_fadvise_dontneed

void
guestfs_int_fadvise_dontneed (int fd)

Hint that we will not be accessing the data in the near future.

On Linux, this immediately writes out any dirty pages in the page cache and then invalidates (drops) all pages associated with this file from the page cache. Apparently it does this even if the file is opened or being used by other processes. This setting is not persistent — if you subsequently read the file it'll be cached in the page cache as normal, so don't stress.

It's OK to call this on a non-file since we ignore failure since it's only a hint. 🫶

🔧 Function common/utils/utils.c:guestfs_int_fadvise_willneed

void
guestfs_int_fadvise_willneed (int fd)

Hint that we will access the data in the near future.

On Linux, this immediately reads the whole file into the page cache. This setting is not persistent; subsequently pages may be dropped from the page cache as normal.

It's OK to call this on a non-file since we ignore failure — only a hint, bestie. ✨

🔧 Function common/utils/utils.c:guestfs_int_shell_unquote

char *
guestfs_int_shell_unquote (const char *str)

Unquote a shell-quoted string. 🐚

Augeas passes strings to us which may be quoted, eg. if they come from files in /etc/sysconfig. This function can do simple unquoting of these strings.

Heads up: this function does not do variable substitution, since that's literally impossible without knowing the file context and indeed the environment under which the shell script is run. Configuration files should not use complex quoting. Periodt.

str is the input string from Augeas — a string that may be single- or double-quoted, or may not be quoted at all. The returned string is unquoted, and must be freed by the caller. NULL is returned on error and errno is set accordingly.

For the tea on double-quoting in bash, see https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html

🔧 Function common/utils/utils.c:guestfs_int_is_reg

int
guestfs_int_is_reg (int64_t mode)

Returns true if the guestfs_statns or guestfs_lstatns st_mode field represents a regular file. 📄

🔧 Function common/utils/utils.c:guestfs_int_is_dir

int
guestfs_int_is_dir (int64_t mode)

Returns true if the guestfs_statns or guestfs_lstatns st_mode field represents a directory. 📁

🔧 Function common/utils/utils.c:guestfs_int_is_chr

int
guestfs_int_is_chr (int64_t mode)

Returns true if the guestfs_statns or guestfs_lstatns st_mode field represents a char device. 🔤

🔧 Function common/utils/utils.c:guestfs_int_is_blk

int
guestfs_int_is_blk (int64_t mode)

Returns true if the guestfs_statns or guestfs_lstatns st_mode field represents a block device. 💽

🔧 Function common/utils/utils.c:guestfs_int_is_fifo

int
guestfs_int_is_fifo (int64_t mode)

Returns true if the guestfs_statns or guestfs_lstatns st_mode field represents a named pipe (FIFO). 🚰

🔧 Function common/utils/utils.c:guestfs_int_is_lnk

int
guestfs_int_is_lnk (int64_t mode)

Returns true if the guestfs_statns or guestfs_lstatns st_mode field represents a symbolic link. 🔗

🔧 Function common/utils/utils.c:guestfs_int_is_sock

int
guestfs_int_is_sock (int64_t mode)

Returns true if the guestfs_statns or guestfs_lstatns st_mode field represents a Unix domain socket. 🧦

🔧 Function common/utils/utils.c:guestfs_int_full_path

char *
guestfs_int_full_path (const char *dir, const char *name)

Concatenates dir and name to create a path. It correctly handles the case of concatenating / + filename as well as /dir + filename. And name may be NULL — we're flexible like that. 💁‍♀️

The caller must free the returned path.

This function sets errno and returns NULL on error.

🔧 Function common/utils/utils.c:guestfs_int_hexdump

void
guestfs_int_hexdump (const void *data, size_t len, FILE *fp)

Hexdumps a block of memory to FILE * — used for debugging. 🧚

🔧 Function common/utils/utils.c:guestfs_int_strerror

const char *
guestfs_int_strerror (int errnum, char *buf, size_t buflen)

Thread-safe strerror_r. 🧵

This is a wrapper around the two variants of strerror_r(3) in glibc since it's genuinely hard to use correctly (RHBZ#2030396).

The buffer you pass in should be large enough to store the error message (256 chars at least) and should be non-static. Note that the buffer might not be used — so use the return value, bestie. 🙈

---

📄 File common/utils/whole-file.c

🔧 Function common/utils/whole-file.c:read_whole_file

int
read_whole_file (const char *filename, char **data_r, size_t *size_r)

Reads the whole file filename into a memory buffer. 📥

The memory buffer is initialized and returned in data_r. The size of the file in bytes is returned in size_r. The returned buffer must be freed by the caller.

On error this prints an error on stderr and returns -1. Unlike the similar guestfs_int_read_whole_file, this does not use the libguestfs handle or call error().

For the convenience of callers, the returned buffer is NUL-terminated (the NUL is not included in the size). 🎀

Warning: the file must be a regular, local, trusted file. In particular, do not use this function to read files that might be under control of an untrusted user, since that will lead to a denial-of-service attack. Not cute, not slay, just don't. 💀

---

🗂️ Subdirectory common/visit

📄 File common/visit/visit.c

This file contains a recursive function for visiting all files and directories in a guestfs filesystem.

Adapted from https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/ — shoutout to the source, iykyk. 🫡

🔧 Function common/visit/visit.c:visit

int
visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)

Visit every file and directory in a guestfs filesystem, starting at dir. 🚶‍♀️

dir may be / to visit the entire filesystem, or may be some subdirectory. Symbolic links are not followed — no chasing rabbit holes.

The visitor function f is called once for every directory and every file. The parameters passed to f include the current directory name, the current file name (or NULL when we're visiting a directory), the guestfs_statns (file permissions etc), and the list of extended attributes of the file. The visitor function may return -1, which causes the whole recursion to stop with an error. 😭

Also passed to this function is an opaque pointer which is passed through to the visitor function.

Returns 0 if everything went OK, or -1 if there was an error. Error handling is not particularly well defined. It will either set an error in the libguestfs handle or print an error on stderr, but there is literally no way for the caller to tell the difference. 🙃

---

🗂️ Subdirectory common/windows

📄 File common/windows/windows.c

This file implements win: Windows file path support in guestfish(1). 🪟

🔧 Function common/windows/windows.c:is_windows

int
is_windows (guestfs_h *g, const char *root)

Checks whether root is a Windows installation.

This relies on an already being done introspection. 🔍

🔧 Function common/windows/windows.c:windows_path

char *
windows_path (guestfs_h *g, const char *root, const char *path, int readonly)

Resolves path as a possible Windows path according to root, giving a new path that can be used in libguestfs API calls. 🧭

Notes:

• root must be a Windows installation
• relies on an already being done introspection
• will unmount all the existing mount points and mount the Windows root (according to readonly)
• calls exit(3) on memory allocation failures

---

🗂️ Subdirectory daemon

📄 File daemon/command.c

This file contains a number of useful functions for running external commands and capturing their output. 🏃‍♀️💨

🔧 Function daemon/command.c:commandf

int
commandf (char **stdoutput, char **stderror, unsigned flags,
          const char *name, ...)

Run a command. Optionally capture stdout and stderr as strings. 📸

Returns 0 if the command ran successfully, or -1 if there was any error.

For a description of the flags see commandrvf.

There is also a macro command(out,err,name,...) which calls commandf with flags=0.

🔧 Function daemon/command.c:commandrf

int
commandrf (char **stdoutput, char **stderror, unsigned flags,
           const char *name, ...)

Same as command, but we allow the status code from the subcommand to be non-zero, and return that status code. 🤝

We still return -1 if there was some other error.

There is also a macro commandr(out,err,name,...) which calls commandrf with flags=0.

🔧 Function daemon/command.c:commandvf

int
commandvf (char **stdoutput, char **stderror, unsigned flags,
           char const *const *argv)

Same as command, but passing in an argv array. 🧾

There is also a macro commandv(out,err,argv) which calls commandvf with flags=0.

🔧 Function daemon/command.c:commandrvf

int
commandrvf (char **stdoutput, char **stderror, unsigned flags,
            char const* const *argv)

This is a more sane version of system(3) for running external commands. It uses fork/execvp, so we don't need to worry about quoting of parameters, and it lets us capture any error messages in a buffer. Lowkey a glow-up. ✨

If stdoutput is not NULL, then *stdoutput will return the stdout of the command as a string.

If stderror is not NULL, then *stderror will return the stderr of the command. If there is a final \n character, it is removed so you can use the error string directly in a call to reply_with_error. 🎀

Flags are:

• COMMAND_FLAG_FOLD_STDOUT_ON_STDERR — for broken external commands that send error messages to stdout (hello, parted) but that don't have any useful stdout information, use this flag to capture the error messages in the *stderror buffer. If using this flag, you should pass stdoutput=NULL because nothing could ever be captured in that buffer. 🫠
• COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN — okay so this one exists so we can run external commands on chrooted files correctly (there's a whole bug about it, go look: https://bugzilla.redhat.com/579608). If you pass this flag, another process gets forked, chroots into sysroot, and just copies the input file to stdin of the command you specified. The file descriptor gets ORed with the flags, and that fd is always closed by this function, no take-backs. There's a usage example chillin' in daemon/hexdump.c if you wanna see it irl.

There's also a macro commandrv(out,err,argv) that just calls commandrvf with flags=0. Cute, one less arg to type 💅

---

🗂️ File daemon/device-name-translation.c

Function daemon/device-name-translation.c:device_name_translation_init

void
device_name_translation_init (void)

Lowkey the cache for daemon disk mapping. When the daemon boots up, it fills a cache with the contents of /dev/disk/by-path. Honestly it's easiest to use ls -lv for this because the names sort in the most awkward way possible, iykyk 😭

Function daemon/device-name-translation.c:device_name_translation

char *
device_name_translation (const char *device)

Does the actual device name translation ✨ Libguestfs defines a handful of standard formats for device names (peep also "BLOCK DEVICE NAMING" in guestfs(3) and guestfs_canonical_device_name in guestfs(3)). Here they are, bestie:

• /dev/sdX[N]
• /dev/hdX[N]
• /dev/vdX[N]

These all mean the Nth partition on the Xth device. And because Linux doesn't enumerate devices in the order they get passed to qemu anymore (rude), we gotta translate these by looking up the actual device using /dev/disk/by-path/.

• /dev/mdX
• /dev/VG/LV
• /dev/mapper/...
• /dev/dm-N

These ones? Not translated here. Nope, not them.

It returns a newly allocated string, and the caller has to free it (their problem now 🫶). It returns NULL on error — and heads up, it does not call reply_with_*. We have to open the device and test for ENXIO, because the device nodes might already exist in the appliance.

---

🗂️ File daemon/guestfsd.c

This is the guestfs daemon, the one running inside the guestfs appliance. This file handles start up and connecting back to the library. Main character energy fr 🎀

Function daemon/guestfsd.c:shell_quote

void
shell_quote (const char *str, FILE *fp)

Writes str to the file fp, making sure it's shell quoted. Safe and sound ✨

Function daemon/guestfsd.c:sysroot_shell_quote

void
sysroot_shell_quote (const char *path, FILE *fp)

Writes sysroot + path to the file fp, also making sure it's shell quoted. Little rule though: the path must be an absolute path. No exceptions 🚨

---

🗂️ File daemon/initrd.c

Function daemon/initrd.c:skip_early_cpio_archive

static off_t
skip_early_cpio_archive (int fd, off_t offset, off_t file_size)

Okay so modern initramfs images are often several concatenated cpio archives glued together: one or more uncompressed "early cpio" archives (the kernel/dracut uses these to carry CPU microcode etc — see Documentation/x86/microcode.rst in the kernel sources), and then the main, compressed cpio archive with the actual real initramfs contents inside.

This function parses a single newc/crc format cpio archive starting at offset in fd, going up to and including its TRAILER!!! entry, and returns the offset of the byte right after it — rounded up to the next 512-byte boundary (because early cpio archives get padded to a block boundary before the next archive is appended). Returns -1 if the archive is truncated or malformed. 💀

Function daemon/initrd.c:detect_initrd

static int
detect_initrd (const char *path, off_t *offset_r,
               enum initrd_compression *compression_r)

Figures out where the "real" (possibly compressed) cpio archive actually starts inside path, skipping over any leading uncompressed early cpio archives, and detects its compression format (if there even is one) by staring at its magic bytes 🔮

Returns 0 on success, or -1 on error (and if it errors, it's already called reply_with_*).

---

🗂️ File daemon/internal.c

Internal functions that are not part of the public API. You didn't see them. 🙈

🗂️ File daemon/utils-c.c

Bindings for utility functions. Big note: functions called from OCaml code must never call any of the reply* functions. Like ever. Ground rules, periodt.

🗂️ File daemon/utils.c

Miscellaneous utility functions used by the daemon — the little grab-bag of helpers 🎀

Function daemon/utils.c:is_root_device_stat

static int
is_root_device_stat (struct stat *statbuf)

Returns true iff the device is the root device (which means it should be ignored from the point of view of user calls).

Function daemon/utils.c:is_device_parameter

int
is_device_parameter (const char *device)

Parameters marked as Device, Dev_or_Path, etc can be handed a block device name. This function tests whether the parameter is a block device name.

It can also be used in daemon code to test whether the string passed as a Dev_or_Path parameter is a device or a path. Versatile icon 💅

Function daemon/utils.c:sysroot_path

char *
sysroot_path (const char *path)

Turns /path into /sysroot/path. That's it, that's the whole job ✨

Returns NULL on failure — so the caller must check for that and call reply_with_perror ("malloc"). The caller also has to free the returned string.

See also the custom %R printf formatter, which does shell quoting too.

Function daemon/utils.c:sysroot_realpath

char *
sysroot_realpath (const char *path)

Resolves the path within sysroot, by calling sysroot_path on the resolved path.

Returns NULL on failure — caller must check for it and call reply_with_perror ("malloc"). And yep, caller must free the returned string.

See also the custom %R printf formatter, which does shell quoting too (same note as above, bestie).

Function daemon/utils.c:is_power_of_2

int
is_power_of_2 (unsigned long v)

Returns true if v is a power of 2 ⚡

Uses the algorithm described at http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2

Function daemon/utils.c:split_lines_sb

struct stringsbuf
split_lines_sb (char *str)

Splits an output string into a NULL-terminated list of lines, wrapped all cozy into a stringsbuf 🧚

Typically this is used when we've run an external command that printed out a list of things and we want to return an actual list.

The corner cases here are genuinely quite tricky, so note in particular:

• "" returns []
• "\n" returns [""]
• "a\nb" returns ["a"; "b"]
• "a\nb\n" returns ["a"; "b"]
• "a\nb\n\n" returns ["a"; "b"; ""]

The original string gets written over and destroyed by this function (which is usually fine because it's the 'out' string from command*()). You can free the original string, because add_string() strdups the strings. And "argv" in the struct stringsbuf will be NULL in case of errors.

Function daemon/utils.c:filter_list

char **
filter_list (bool (*p) (const char *str), char **strs)

Filters a list of strings. Returns a newly allocated list containing only the strings where p (str) == true.

Careful though: it does not copy the strings, so don't double-free them. Watch out 👀

Function daemon/utils.c:trim

void
trim (char *str)

Skips leading and trailing whitespace, updating the original string in-place. Glow-up, but in place ✨

Function daemon/utils.c:parse_btrfsvol

int
parse_btrfsvol (const char *desc_orig, mountable_t *mountable)

Parses the mountable descriptor for a btrfs subvolume. Don't call this directly, okay? It's only used from the stubs.

A btrfs subvolume is given like this:

btrfsvol:/dev/sda3/root

where /dev/sda3 is a block device containing a btrfs filesystem, and root is the name of a subvolume on it. This function gets passed the string following btrfsvol:.

On success, mountable->device and mountable->volume must be freed by the caller 🫶

Function daemon/utils.c:mountable_to_string

char *
mountable_to_string (const mountable_t *mountable)

Converts a mountable_t back to its string representation.

Because this function can be used in an error path, it must not call reply_with_error. Rules are rules 🚨

Function daemon/utils.c:prog_exists

int
prog_exists (const char *prog)

Checks that the program exists and is executable on $PATH. Vibe check for binaries 💅

Function daemon/utils.c:random_name

int
random_name (char *template)

You pass a template like /sysroot/XXXXXXXX.XXX. This updates the template to contain a randomly named file — any 'X' characters after the final / in the template get replaced with random characters 🎲

Notes, because there are always notes: you should probably use an 8.3 path, so it's compatible with all filesystems including basic FAT. Also, this only substitutes lowercase ASCII letters and numbers, again for compatibility with lowest common denominator filesystems 🍓

It doesn't create a file, and it doesn't check whether the file exists (it would be extremely unlikely to exist as long as the RNG is doing its job).

If there's an error, -1 is returned.

Function daemon/utils.c:udev_settle_file

void
udev_settle_file (const char *file)

LVM and other commands aren't synchronous, especially once udev is in the picture. Like, eg. you can create or remove some device, but the /dev device node won't show up until some time later 😭 Which means you get an error if you run one command followed by another.

Use udevadm settle after certain commands, but honestly don't be too fussed if it fails.

Function daemon/utils.c:make_exclude_from_file

char *
make_exclude_from_file (const char *function, char *const *excludes)

Turns the list excludes into a temporary file, and returns a string containing the temporary file name. The caller must unlink the file and free the string. Both. Don't forget 🫶

function is the function that invoked this helper, and it's used mainly for errors/debugging.

---

🗂️ File daemon/xattr.c

Function daemon/xattr.c:split_attr_names

static char **
split_attr_names (char *buf, size_t len)

So listxattr(2) returns the string "foo\0bar\0baz" of length len. (The last string in the list is \0-terminated, but that \0 isn't included in len — sneaky.)

This function splits it into a regular list of strings ✨

Note that the returned list contains pointers to the original strings inside buf, so be careful not to double-free them. Fr fr, be careful 💀

---

🐟 Subdirectory fish

🗂️ File fish/alloc.c

This file implements the guestfish alloc and sparse commands.

Function fish/alloc.c:alloc_disk

int
alloc_disk (const char *filename, const char *size_str, int add, int sparse)

This is the underlying allocation function, the one doing the actual work. It gets called from a few other places in guestfish too, so it's basically everywhere 👑

🗂️ File fish/copy.c

This file implements the guestfish commands copy-in and copy-out. Copy-paste era 💅

🗂️ File fish/destpaths.c

This file handles tab-completion of filesystem paths in guestfish. You're welcome, by the way — every time you hit Tab, this is the icon behind it ✨

🗂️ File fish/display.c

This file implements the guestfish display command, for displaying graphical files (icons, images) in disk images 🖼️

🗂️ File fish/echo.c

This file implements the guestfish echo command.

🗂️ File fish/edit.c

…and this one's a whole thing that keeps going in the next stretch, so hold that thought bestie 🫶

guestfish edit command, suggested by Ján Ondrej. 💅

File fish/events.c

This file implements the guestfish event-related commands, event, delete-event and list-events. ✨

File fish/fish.c

guestfish, the guest filesystem shell. This file contains the main loop and utilities.

Function fish/fish.c:parse_command_line

static struct parsed_command
parse_command_line (char *buf, int *exit_on_error_rtn)

Parse a command string, splitting at whitespace, handling !, # etc. This destructively updates buf.

exit_on_error_rtn is used to pass in the global exit_on_error setting and to return the local setting (eg. if the command begins with -).

Returns in parsed_command.status:

• 1 — got a guestfish command (returned in cmd_rtn/argv_rtn/pipe_rtn)
• 0 — no guestfish command, but otherwise OK
• -1 — an error

Function fish/fish.c:parse_quoted_string

static ssize_t
parse_quoted_string (char *p)

Parse double-quoted strings, replacing backslash escape sequences with the true character. Since the string is returned in place, the escapes must make the string shorter.

Function fish/fish.c:execute_and_inline

static int
execute_and_inline (const char *cmd, int global_exit_on_error)

Used to handle <! (execute command and inline result). 🫶

Function fish/fish.c:issue_command

int
issue_command (const char *cmd, char *argv[], const char *pipecmd,
               int rc_exit_on_error_flag)

Run a command.

rc_exit_on_error_flag is the exit_on_error flag that we pass to the remote server (when issuing --remote commands). It does not cause issue_command itself to exit on error.

Function fish/fish.c:extended_help_message

void
extended_help_message (void)

Print an extended help message when the user types in an unknown command for the first command issued. A common case is the user doing:

guestfish disk.img

expecting guestfish to open disk.img (in fact, this tried to run a non-existent command disk.img).

Function fish/fish.c:error_cb

static void
error_cb (guestfs_h *g, void *data, const char *msg)

Error callback. This replaces the standard libguestfs error handler.

Function fish/fish.c:free_n_strings

static void
free_n_strings (char **str, size_t len)

Free strings from a non-NULL terminated char**.

Function fish/fish.c:decode_ps1

static char *
decode_ps1 (const char *str)

Decode str into the final printable prompt string.

Function fish/fish.c:win_prefix

char *
win_prefix (const char *path)

Resolve the special win:... form for Windows-specific paths. The generated code calls this for all device or path arguments.

The function returns a newly allocated string, and the caller must free this string; else display an error and return NULL.

Function fish/fish.c:file_in

char *
file_in (const char *arg)

Resolve the special FileIn paths (- or -<<END or filename).

The caller (fish/cmds.c) will call free_file_in after the command has run which should clean up resources.

Function fish/fish.c:file_out

char *
file_out (const char *arg)

Resolve the special FileOut paths (- or filename).

The caller (fish/cmds.c) will call free (str) after the command has run.

Function fish/fish.c:progress_callback

void
progress_callback (guestfs_h *g, void *data,
                   uint64_t event, int event_handle, int flags,
                   const char *buf, size_t buf_len,
                   const uint64_t *array, size_t array_len)

Callback which displays a progress bar. ✨

File fish/glob.c

This file implements the guestfish glob command.

Function fish/glob.c:expand_devicename

static char **
expand_devicename (guestfs_h *g, const char *device)

Glob-expand device patterns, such as /dev/sd* (https://bugzilla.redhat.com/635971).

There is no guestfs_glob_expand_device function because the equivalent can be implemented using functions like guestfs_list_devices.

It's not immediately clear what it means to expand a pattern like /dev/sd*. Should that include device name translation? Should the result include partitions as well as devices?

Should /dev/ + * return every possible device and filesystem? How about VGs? LVs?

To solve this what we do is build up a list of every device, partition, etc., then glob against that list.

Notes for future work (XXX):

• This doesn't handle device name translation. It wouldn't be too hard to add.
• Could have an API function for returning all device-like things.

Function fish/glob.c:add_strings_matching

static int
add_strings_matching (char **pp, const char *glob,
                      char ***ret, size_t *size_r)

Using POSIX fnmatch(3), find strings in the list pp which match pattern glob. Add strings which match to the ret array. *size_r is the current size of the ret array, which is updated with the new size.

Function fish/glob.c:single_element_list

static char **
single_element_list (const char *element)

Return a single element list containing element.

File fish/help.c

The file implements the guestfish help command.

Function fish/help.c:display_help

int
display_help (const char *cmd, size_t argc, char *argv[])

The help command.

This used to just list all commands, but that's not very useful. Instead display some useful context-sensitive help. This could be improved if we knew how many drives had been added already, and whether anything was mounted. 🌸

File fish/hexedit.c

This file implements the guestfish hexedit command.

File fish/lcd.c

Function fish/lcd.c:run_lcd

int
run_lcd (const char *cmd, size_t argc, char *argv[])

guestfish lcd command (similar to the lcd command in BSD ftp).

File fish/man.c

Function fish/man.c:run_man

int
run_man (const char *cmd, size_t argc, char *argv[])

guestfish man command

File fish/more.c

This file implements the guestfish more command.

File fish/not.c

This file implements the guestfish not command.

File fish/prep.c

This file implements the guestfish -N option for creating pre-prepared disk layouts.

File fish/rc.c

This file implements guestfish remote (command) support.

Function fish/rc.c:rc_listen

void
rc_listen (void)

The remote control server (ie. guestfish --listen).

Function fish/rc.c:rc_remote

int
rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
           int exit_on_error)

The remote control client (ie. guestfish --remote).

File fish/reopen.c

This file implements the guestfish reopen command.

File fish/setenv.c

This file implements the guestfish setenv and unsetenv commands.

File fish/supported.c

This file implements the guestfish supported command.

File fish/tilde.c

This file implements tilde (~) expansion of home directories in guestfish(1).

Function fish/tilde.c:try_tilde_expansion

char *
try_tilde_expansion (char *str)

This is called from the script loop if we find a candidate for ~username (tilde-expansion).

Function fish/tilde.c:expand_home

static char *
expand_home (char *orig, const char *append)

Return $HOME + append string.

Function fish/tilde.c:find_home_for_username

static const char *
find_home_for_username (const char *username, size_t ulen)

Lookup username (of length ulen), return home directory if found, or NULL if not found.

File fish/time.c

This file implements the guestfish time command. ⏳

---

🐍 Subdirectory python

File python/handle.c

This file contains a small number of functions that are written by hand. The majority of the bindings are generated (see python/actions-*.c).

---

🌈 SEE ALSO

• guestfs(3)
• guestfs-building(1)
• guestfs-examples(3)
• guestfs-internals(1)
• guestfs-performance(1)
• guestfs-release-notes(1)
• guestfs-testing(1)
• libguestfs-test-tool(1)
• libguestfs-make-fixed-appliance(1)
• http://libguestfs.org/

👑 AUTHORS

Richard W.M. Jones (rjones at redhat dot com)

💖 COPYRIGHT

Copyright (C) 2009-2025 Red Hat Inc.

📜 LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

💀 BUGS

To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

When reporting a bug, please supply:

• The version of libguestfs.
• Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
• Describe the bug accurately and give a way to reproduce it.
• Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report.

---

That's the whole guestfs-hacking(1) page, bestie — source/version libguestfs-1.61.3, date 2026-09-16. Slay and bye! 💅✨