1guestfs-hacking(1) Virtualization Support guestfs-hacking(1)
2
6 guestfs-hacking - extending and contributing to libguestfs
7
9 This manual page is for hackers who want to extend libguestfs itself.
10
12 Libguestfs source is located in the github repository
13 https://github.com/libguestfs/libguestfs
14 Large amounts of boilerplate code in libguestfs (RPC, bindings,
16 documentation) are generated. This means that many source files will
17 appear to be missing from a straightforward git checkout. You have to
18 run the generator ("./configure && make -C generator") in order to
19 create those files.
20 Libguestfs uses an autotools-based build system, with the main files
22 being configure.ac and Makefile.am. See "THE BUILD SYSTEM".
23 The generator subdirectory contains the generator, plus files
25 describing the API. The lib subdirectory contains source for the
26 library. The appliance and daemon subdirectories contain the source
27 for the code that builds the appliance, and the code that runs in the
28 appliance respectively. Other directories are covered in the section
29 "SOURCE CODE SUBDIRECTORIES" below.
30 Apart from the fact that all API entry points go via some generated
32 code, the library is straightforward. (In fact, even the generated
33 code is designed to be readable, and should be read as ordinary code).
34 Some actions run entirely in the library, and are written as C
35 functions in files under lib. Others are forwarded to the daemon where
36 (after some generated RPC marshalling) they appear as C functions in
37 files under daemon.
38 To build from source, first read the guestfs-building(1).
40 SOURCE CODE SUBDIRECTORIES
42 There are a lot of subdirectories in the source tree! Which ones
43 should you concentrate on first? lib and daemon which contain the
44 source code of the core library. generator is the code generator
45 described above, so that is important. The Makefile.am in the root
46 directory will tell you in which order the subdirectories get built.
47 And then if you are looking at a particular tool (eg. customize) or
48 language binding (eg. python), go straight to that subdirectory, but
49 remember that if you didn't run the generator yet, then you may find
50 files which appear to be missing.
51 align
53 virt-alignment-scan(1) command and documentation.
54 appliance
56 The libguestfs appliance, build scripts and so on.
57 bash
59 Bash tab-completion scripts.
60 build-aux
62 Various build scripts used by autotools.
63 builder
65 virt-builder(1) command and documentation.
66 cat The virt-cat(1), virt-filesystems(1), virt-log(1), virt-ls(1) and
68 virt-tail(1) commands and documentation.
69 common
71 Various libraries of internal code can be found in the common
72 subdirectory:
73 common/edit
75 Common code for interactively and non-interactively editing
76 files within a libguestfs filesystem.
77 common/errnostring
79 The communication protocol used between the library and the
80 daemon running inside the appliance has to encode errnos as
81 strings, which is handled by this library.
82 common/mlcustomize
84 Library code associated with "virt-customize" but also used in
85 other tools.
86 common/mlgettext
88 Small, generated wrapper which allows libguestfs to be compiled
89 with or without ocaml-gettext. This is generated by
90 ./configure.
91 common/mlpcre
93 Lightweight OCaml bindings for Perl Compatible Regular
94 Expressions (PCRE). Note this is not related in any way to
95 Markus Mottl's ocaml-pcre library.
96 common/mlprogress
98 OCaml bindings for the progress bar functions (see
99 common/progress).
100 common/mlstdutils
102 A library of pure OCaml utility functions used in many places.
103 common/mltools
105 OCaml utility functions only used by the OCaml virt tools (like
106 "virt-sysprep", "virt-customize" etc.)
107 common/mlutils
109 OCaml bindings for C functions in "common/utils", and some
110 POSIX bindings which are missing from the OCaml stdlib.
111 common/mlvisit
113 OCaml bindings for the visit functions (see common/visit).
114 common/mlxml
116 OCaml bindings for the libxml2 library.
117 common/options
119 Common options parsing for guestfish, guestmount and some virt
120 tools.
121 common/parallel
123 A framework used for processing multiple libvirt domains in
124 parallel.
125 common/progress
127 Common code for printing progress bars.
128 common/protocol
130 The XDR-based communication protocol used between the library
131 and the daemon running inside the appliance is defined here.
132 common/qemuopts
134 Mini-library for writing qemu command lines and qemu config
135 files.
136 common/structs
138 Common code for printing and freeing libguestfs structs, used
139 by the library and some tools.
140 common/utils
142 Various utility functions used throughout the library and
143 tools.
144 common/visit
146 Recursively visit a guestfs filesystem hierarchy.
147 common/windows
149 Utility functions for handling Windows drive letters.
150 contrib
152 Outside contributions, experimental parts.
153 customize
155 virt-customize(1) command and documentation.
156 daemon
158 The daemon that runs inside the libguestfs appliance and carries
159 out actions.
160 df virt-df(1) command and documentation.
162 dib virt-dib(1) command and documentation.
164 diff
166 virt-diff(1) command and documentation.
167 docs
169 Miscellaneous manual pages.
170 edit
172 virt-edit(1) command and documentation.
173 examples
175 C API example code.
176 fish
178 guestfish(1), the command-line shell, and various shell scripts
179 built on top such as virt-copy-in(1), virt-copy-out(1),
180 virt-tar-in(1), virt-tar-out(1).
181 format
183 virt-format(1) command and documentation.
184 fuse
186 guestmount(1), FUSE (userspace filesystem) built on top of
187 libguestfs.
188 generator
190 The crucially important generator, used to automatically generate
191 large amounts of boilerplate C code for things like RPC and
192 bindings.
193 get-kernel
195 virt-get-kernel(1) command and documentation.
196 inspector
198 virt-inspector(1), the virtual machine image inspector.
199 lib Source code to the C library.
201 logo
203 Logo used on the website. The fish is called Arthur by the way.
204 m4 M4 macros used by autoconf. See "THE BUILD SYSTEM".
206 make-fs
208 virt-make-fs(1) command and documentation.
209 po Translations of simple gettext strings.
211 po-docs
213 The build infrastructure and PO files for translations of manpages
214 and POD files. Eventually this will be combined with the po
215 directory, but that is rather complicated.
216 rescue
218 virt-rescue(1) command and documentation.
219 resize
221 virt-resize(1) command and documentation.
222 sparsify
224 virt-sparsify(1) command and documentation.
225 sysprep
227 virt-sysprep(1) command and documentation.
228 tests
230 Tests.
231 test-data
233 Files and other test data used by the tests.
234 test-tool
236 Test tool for end users to test if their qemu/kernel combination
237 will work with libguestfs.
238 tmp Used for temporary files when running the tests (instead of /tmp
240 etc). The reason is so that you can run multiple parallel tests of
241 libguestfs without having one set of tests overwriting the
242 appliance created by another.
243 tools
245 Command line tools written in Perl (virt-win-reg(1) and many
246 others).
247 utils
249 Miscellaneous utilities, such as "boot-benchmark".
250 v2v Up to libguestfs > 1.42 this contained the virt-v2v(1) tool, but
252 this has now moved into a separate repository:
253 https://github.com/libguestfs/virt-v2v
254 website
256 The http://libguestfs.org website files.
257 csharp
259 erlang
260 gobject
261 golang
262 haskell
263 java
264 lua
265 ocaml
266 php
267 perl
268 python
269 ruby
270 Language bindings.
271 THE BUILD SYSTEM
273 Libguestfs uses the GNU autotools build system (autoconf, automake,
274 libtool).
275 The ./configure script is generated from configure.ac and
277 m4/guestfs-*.m4. Most of the configure script is split over many m4
278 macro files by topic, for example m4/guestfs-daemon.m4 deals with the
279 dependencies of the daemon.
280 The job of the top level Makefile.am is mainly to list the
282 subdirectories ("SUBDIRS") in the order they should be compiled.
283 common-rules.mk is included in every Makefile.am (top level and
285 subdirectories). subdir-rules.mk is included only in subdirectory
286 Makefile.am files.
287 There are many make targets. Use this command to list them all:
289 make help
291
293 ADDING A NEW API
294 Because large amounts of boilerplate code in libguestfs are generated,
295 this makes it easy to extend the libguestfs API.
296 To add a new API action there are two changes:
298 1. You need to add a description of the call (name, parameters, return
300 type, tests, documentation) to generator/actions_*.ml and possibly
301 generator/proc_nr.ml.
302 There are two sorts of API action, depending on whether the call
304 goes through to the daemon in the appliance, or is serviced
305 entirely by the library (see "ARCHITECTURE" in
306 guestfs-internals(1)). "guestfs_sync" in guestfs(3) is an example
307 of the former, since the sync is done in the appliance.
308 "guestfs_set_trace" in guestfs(3) is an example of the latter,
309 since a trace flag is maintained in the handle and all tracing is
310 done on the library side.
311 Most new actions are of the first type, and get added to the
313 "daemon_functions" list. Each function has a unique procedure
314 number used in the RPC protocol which is assigned to that action
315 when we publish libguestfs and cannot be reused. Take the latest
316 procedure number and increment it.
317 For library-only actions of the second type, add to the
319 "non_daemon_functions" list. Since these functions are serviced by
320 the library and do not travel over the RPC mechanism to the daemon,
321 these functions do not need a procedure number, and so the
322 procedure number is set to "-1".
323 2. Implement the action (in C):
325 For daemon actions, implement the function "do_<name>" in the
327 "daemon/" directory.
328 For library actions, implement the function "guestfs_impl_<name>"
330 in the "lib/" directory.
331 In either case, use another function as an example of what to do.
333 3. As an alternative to step 2: Since libguestfs 1.38, daemon actions
335 can be implemented in OCaml. You have to set the "impl = OCaml
336 ..." flag in the generator. Take a look at daemon/file.ml for an
337 example.
338 After making these changes, use "make" to compile.
340 Note that you don’t need to implement the RPC, language bindings,
342 manual pages or anything else. It’s all automatically generated from
343 the OCaml description.
344 Adding tests for an API
346 You can supply zero or as many tests as you want per API call. The
348 tests can either be added as part of the API description
349 (generator/actions_*.ml), or in some rarer cases you may want to drop a
350 script into "tests/*/". Note that adding a script to "tests/*/" is
351 slower, so if possible use the first method.
352 The following describes the test environment used when you add an API
354 test in actions_*.ml.
355 The test environment has 4 block devices:
357 /dev/sda 2 GB
359 General block device for testing.
360 /dev/sdb 2 GB
362 /dev/sdb1 is an ext2 filesystem used for testing filesystem write
363 operations.
364 /dev/sdc 10 MB
366 Used in a few tests where two block devices are needed.
367 /dev/sdd
369 ISO with fixed content (see images/test.iso).
370 To be able to run the tests in a reasonable amount of time, the
372 libguestfs appliance and block devices are reused between tests. So
373 don't try testing "guestfs_kill_subprocess" in guestfs(3) :-x
374 Each test starts with an initial scenario, selected using one of the
376 "Init*" expressions, described in generator/types.ml. These initialize
377 the disks mentioned above in a particular way as documented in
378 types.ml. You should not assume anything about the previous contents
379 of other disks that are not initialized.
380 You can add a prerequisite clause to any individual test. This is a
382 run-time check, which, if it fails, causes the test to be skipped.
383 Useful if testing a command which might not work on all variations of
384 libguestfs builds. A test that has prerequisite of "Always" means to
385 run unconditionally.
386 In addition, packagers can skip individual tests by setting environment
388 variables before running "make check".
389 SKIP_TEST_<CMD>_<NUM>=1
391 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command" in
393 guestfs(3).
394 or:
396 SKIP_TEST_<CMD>=1
398 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" in guestfs(3)
400 tests.
401 Packagers can run only certain tests by setting for example:
403 TEST_ONLY="vfs_type zerofree"
405 See tests/c-api/tests.c for more details of how these environment
407 variables work.
408 Debugging new APIs
410 Test new actions work before submitting them.
412 You can use guestfish to try out new commands.
414 Debugging the daemon is a problem because it runs inside a minimal
416 environment. However you can fprintf messages in the daemon to stderr,
417 and they will show up if you use "guestfish -v".
418 ADDING A NEW LANGUAGE BINDING
420 All language bindings must be generated by the generator (see the
421 generator subdirectory).
422 There is no documentation for this yet. We suggest you look at an
424 existing binding, eg. generator/ocaml.ml or generator/perl.ml.
425 Adding tests for language bindings
427 Language bindings should come with tests. Previously testing of
429 language bindings was rather ad-hoc, but we have been trying to
430 formalize the set of tests that every language binding should use.
431 Currently only the OCaml and Perl bindings actually implement the full
433 set of tests, and the OCaml bindings are canonical, so you should
434 emulate what the OCaml tests do.
435 This is the numbering scheme used by the tests:
437 - 000+ basic tests:
439 010 load the library
441 020 create
442 030 create-flags
443 040 create multiple handles
444 050 test setting and getting config properties
445 060 explicit close
446 065 implicit close (in GC'd languages)
447 070 optargs
448 080 version
449 090 retvalues
450 - 100 launch, create partitions and LVs and filesystems
452 - 400+ events:
454 410 close event
456 420 log messages
457 430 progress messages
458 - 800+ regression tests (specific to the language)
460 - 900+ any other custom tests for the language
462 To save time when running the tests, only 100, 430, 800+, 900+ should
464 launch the handle.
465 FORMATTING CODE
467 Our C source code generally adheres to some basic code-formatting
468 conventions. The existing code base is not totally consistent on this
469 front, but we do prefer that contributed code be formatted similarly.
470 In short, use spaces-not-TABs for indentation, use 2 spaces for each
471 indentation level, and other than that, follow the K&R style.
472 If you use Emacs, add the following to one of your start-up files
474 (e.g., ~/.emacs), to help ensure that you get indentation right:
475 ;;; In libguestfs, indent with spaces everywhere (not TABs).
477 ;;; Exceptions: Makefile and ChangeLog modes.
478 (add-hook 'find-file-hook
479 '(lambda () (if (and buffer-file-name
480 (string-match "/libguestfs\\>"
481 (buffer-file-name))
482 (not (string-equal mode-name "Change Log"))
483 (not (string-equal mode-name "Makefile")))
484 (setq indent-tabs-mode nil))))
485 ;;; When editing C sources in libguestfs, use this style.
487 (defun libguestfs-c-mode ()
488 "C mode with adjusted defaults for use with libguestfs."
489 (interactive)
490 (c-set-style "K&R")
491 (setq c-indent-level 2)
492 (setq c-basic-offset 2))
493 (add-hook 'c-mode-hook
494 '(lambda () (if (string-match "/libguestfs\\>"
495 (buffer-file-name))
496 (libguestfs-c-mode))))
497 TESTING YOUR CHANGES
499 Turn warnings into errors when developing to make warnings hard to
500 ignore:
501 ./configure --enable-werror
503 Useful targets are:
505 "make check"
507 Runs the regular test suite.
508 This is implemented using the regular automake "TESTS" target. See
510 the automake documentation for details.
511 "make check-valgrind"
513 Runs a subset of the test suite under valgrind.
514 See "VALGRIND" below.
516 "make check-valgrind-local-guests"
518 Runs a subset of the test suite under valgrind using locally
519 installed libvirt guests (read-only).
520 "make check-direct"
522 Runs all tests using default appliance back-end. This only has any
523 effect if a non-default backend was selected using "./configure
524 --with-default-backend=..."
525 "make check-valgrind-direct"
527 Run a subset of the test suite under valgrind using the default
528 appliance back-end.
529 "make check-with-upstream-qemu"
531 Runs all tests using a local qemu binary. It looks for the qemu
532 binary in QEMUDIR (defaults to $HOME/d/qemu), but you can set this
533 to another directory on the command line, eg:
534 make check-with-upstream-qemu QEMUDIR=/usr/src/qemu
536 "make check-with-upstream-libvirt"
538 Runs all tests using a local libvirt. This only has any effect if
539 the libvirt backend was selected using "./configure
540 --with-default-backend=libvirt"
541 It looks for libvirt in LIBVIRTDIR (defaults to $HOME/d/libvirt),
543 but you can set this to another directory on the command line, eg:
544 make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt
546 "make check-slow"
548 Runs some slow/long-running tests which are not run by default.
549 To mark a test as slow/long-running:
551 • Add it to the list of "TESTS" in the Makefile.am, just like a
553 normal test.
554 • Modify the test so it checks if the "SLOW=1" environment
556 variable is set, and if not set it skips (ie. returns with exit
557 code 77). If using $TEST_FUNCTIONS, you can call the function
558 "slow_test" for this.
559 • Add a variable "SLOW_TESTS" to the Makefile.am listing the slow
561 tests.
562 • Add a rule to the Makefile.am:
564 check-slow:
566 $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
567 "sudo make check-root"
569 Runs some tests which require root privileges. These are supposed
570 to be safe, but take care. You have to run this as root (eg. using
571 sudo(8) explicitly).
572 To mark a test as requiring root:
574 • Add it to the list of "TESTS" in the Makefile.am, just like a
576 normal test.
577 • Modify the test so it checks if euid == 0, and if not set it
579 skips (ie. returns with exit code 77). If using
580 $TEST_FUNCTIONS, you can call the function "root_test" for
581 this.
582 • Add a variable "ROOT_TESTS" to the Makefile.am listing the root
584 tests.
585 • Add a rule to the Makefile.am:
587 check-root:
589 $(MAKE) check TESTS="$(ROOT_TESTS)"
590 "make check-all"
592 Equivalent to running all "make check*" rules except "check-root".
593 "make check-release"
595 Runs a subset of "make check*" rules that are required to pass
596 before a tarball can be released. Currently this is:
597 • check
599 • check-valgrind
601 • check-direct
603 • check-valgrind-direct
605 • check-slow
607 "make installcheck"
609 Run "make check" on the installed copy of libguestfs.
610 The version of installed libguestfs being tested, and the version
612 of the libguestfs source tree must be the same.
613 Do:
615 ./configure
617 make clean ||:
618 make
619 make installcheck
620 VALGRIND
622 When you do "make check-valgrind", it searches for any Makefile.am in
623 the tree that has a "check-valgrind:" target and runs it.
624 Writing the Makefile.am and tests correctly to use valgrind and working
626 with automake parallel tests is subtle.
627 If your tests are run via a shell script wrapper, then in the wrapper
629 use:
630 $VG virt-foo
632 and in the Makefile.am use:
634 check-valgrind:
636 make VG="@VG@" check
637 However, if your binaries run directly from the "TESTS" rule, you have
639 to modify the Makefile.am like this:
640 LOG_COMPILER = $(VG)
642 check-valgrind:
644 make VG="@VG@" check
645 In either case, check that the right program is being tested by
647 examining the tmp/valgrind* log files carefully.
648 SUBMITTING PATCHES
650 Submit patches to the mailing list:
651 http://www.redhat.com/mailman/listinfo/libguestfs and CC to
652 rjones@redhat.com.
653 You do not need to subscribe to the mailing list if you don’t want to.
655 There may be a short delay while your message is moderated.
656 INTERNATIONALIZATION (I18N) SUPPORT
658 We support i18n (gettext anyhow) in the library.
659 However many messages come from the daemon, and we don’t translate
661 those at the moment. One reason is that the appliance generally has
662 all locale files removed from it, because they take up a lot of space.
663 So we'd have to readd some of those, as well as copying our PO files
664 into the appliance.
665 Debugging messages are never translated, since they are intended for
667 the programmers.
668
670 HOW OCAML PROGRAMS ARE COMPILED AND LINKED
671 Mostly this section is "how we make automake & ocamlopt work together"
672 since OCaml programs themselves are easy to compile.
673 Automake has no native support for OCaml programs, ocamlc nor ocamlopt.
675 What we do instead is to treat OCaml programs as C programs which
676 happen to contain these "other objects" ("DEPENDENCIES" in automake-
677 speak) that happen to be the OCaml objects. This works because OCaml
678 programs usually have C files for native bindings etc.
679 So a typical program is described as just its C sources:
681 virt_customize_SOURCES = ... crypt-c.c perl_edit-c.c
683 For programs that have no explicit C sources, we create an empty
685 dummy.c file, and list that instead:
686 virt_resize_SOURCES = dummy.c
688 The OCaml objects which contain most of the code are listed as automake
690 dependencies (other dependencies may also be listed):
691 virt_customize_DEPENDENCIES = ... customize_main.cmx
693 The only other special thing we need to do is to provide a custom link
695 command. This is needed because automake won't assemble the ocamlopt
696 command, the list of objects and the "-cclib" libraries in the correct
697 order otherwise.
698 virt_customize_LINK = \
700 $(top_builddir)/ocaml-link.sh -cclib '-lutils' -- ...
701 The actual rules, which you can examine in customize/Makefile.am, are a
703 little bit more complicated than this because they have to handle:
704 • Compiling for byte code or native code.
706 • The pattern rules needed to compile the OCaml sources to objects.
708 These are now kept in subdir-rules.mk at the top level, which is
710 included in every subdirectory Makefile.am.
711 • Adding OCaml sources files to "EXTRA_DIST".
713 Automake isn't aware of the complete list of sources for a binary,
715 so it will not add them all automatically.
716
718 MAINTAINER MAKEFILE TARGETS
719 These "make" targets probably won’t work and aren't useful unless you
720 are a libguestfs maintainer.
721 make maintainer-commit
723 This commits everything in the working directory with the commit
725 message "Version $(VERSION).". You must update configure.ac, clean and
726 rebuild first.
727 make maintainer-tag
729 This tags the current HEAD commit with the tag "v$(VERSION)" and one of
731 the messages:
732 Version $(VERSION) stable
734 Version $(VERSION) development
736 (See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for the difference
738 between a stable and development release.)
739 make maintainer-check-authors
741 Check that all authors (found in git commit messages) are included in
743 the generator/authors.ml file.
744 make maintainer-check-extra-dist
746 This rule must be run after "make dist" (so there is a tarball in the
748 working directory). It compares the contents of the tarball with the
749 contents of git to ensure that no files have been missed from
750 Makefile.am "EXTRA_DIST" rules.
751 make maintainer-upload-website
753 This is used by the software used to automate libguestfs releases to
755 copy the libguestfs website to another git repository before it is
756 uploaded to the web server.
757 MAKING A STABLE RELEASE
759 When we make a stable release, there are several steps documented here.
760 See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for general information
761 about the stable branch policy.
762 • Check "make && make check" works on at least:
764 Fedora (x86-64)
766 Debian (x86-64)
767 Ubuntu (x86-64)
768 Fedora (aarch64)
769 Fedora (ppc64)
770 Fedora (ppc64le)
771 • Check "./configure --without-libvirt" works.
772 • Finalize guestfs-release-notes.pod
774 • Create new stable and development directories under
776 http://libguestfs.org/download.
777 • Edit website/index.html.in.
779 • Set the version (in configure.ac) to the new stable version, ie.
781 1.XX.0, and commit it:
782 ./localconfigure
784 make distclean -k
785 ./localconfigure
786 make && make dist
787 make maintainer-commit
788 make maintainer-tag
789 • Create the stable branch in git:
791 git branch stable-1.XX
793 git push origin stable-1.XX
794 • Do a full release of the stable branch.
796 • Set the version to the next development version and commit that.
798 Optionally do a full release of the development branch.
799
801 This section documents internal functions inside libguestfs and various
802 utilities. It is intended for libguestfs developers only.
803 This section is autogenerated from "/**" comments in source files,
805 which are marked up in POD format.
806 These functions are not publicly exported, and may change or be removed
808 at any time.
809 Subdirectory lib
811 File lib/actions-support.c
812 Helper functions for the actions code in lib/actions-*.c.
814 File lib/appliance-cpu.c
816 The appliance choice of CPU model.
818 Function "lib/appliance-cpu.c:guestfs_int_get_cpu_model"
820 const char *
822 guestfs_int_get_cpu_model (int kvm)
823 Return the right CPU model to use as the qemu "-cpu" parameter or its
825 equivalent in libvirt. This returns:
826 "host"
828 The literal string "host" means use "-cpu host".
829 "max"
831 The literal string "max" means use "-cpu max" (the best possible).
832 This requires awkward translation for libvirt.
833 some string
835 Some string such as "cortex-a57" means use "-cpu cortex-a57".
836 "NULL"
838 "NULL" means no "-cpu" option at all. Note returning "NULL" does
839 not indicate an error.
840 This is made unnecessarily hard and fragile because of two stupid
842 choices in QEMU:
843 • The default for "qemu-system-aarch64 -M virt" is to emulate a
845 "cortex-a15" (WTF?).
846 • We don't know for sure if KVM will work, but "-cpu host" is broken
848 with TCG, so we almost always pass a broken "-cpu" flag if KVM is
849 semi-broken in any way.
850 File lib/appliance-kcmdline.c
852 The appliance kernel command line.
854 Definition "lib/appliance-kcmdline.c:VALID_TERM"
856 #define VALID_TERM
858 Check that the $TERM environment variable is reasonable before we pass
860 it through to the appliance.
861 Function "lib/appliance-kcmdline.c:get_root_uuid_with_file"
863 static char *
865 get_root_uuid_with_file (guestfs_h *g, const char *appliance)
866 Given a disk image containing an extX filesystem, return the UUID.
868 Function "lib/appliance-kcmdline.c:run_qemu_img_dd"
870 static int
872 run_qemu_img_dd (guestfs_h *g, const char *in_file, char *out_file)
873 Read the first 256k bytes of the in_file with qemu-img(1) command and
875 write them into the out_file. That may be useful to get UUID of the
876 QCOW2 disk image with "get_root_uuid_with_file".
877 The function returns zero if successful, otherwise -1.
879 Function "lib/appliance-kcmdline.c:get_root_uuid"
881 static char *
883 get_root_uuid (guestfs_h *g, const char *appliance)
884 Get the UUID from the appliance disk image.
886 Function "lib/appliance-kcmdline.c:guestfs_int_appliance_command_line"
888 char *
890 guestfs_int_appliance_command_line (guestfs_h *g,
891 const char *appliance,
892 int flags)
893 Construct the Linux command line passed to the appliance. This is used
895 by the "direct" and "libvirt" backends, and is simply located in this
896 file because it's a convenient place for this common code.
897 The "appliance" parameter is the filename of the appliance (could be
899 NULL) from which we obtain the root UUID.
900 The "flags" parameter can contain the following flags logically or'd
902 together (or 0):
903 "APPLIANCE_COMMAND_LINE_IS_TCG"
905 If we are launching a qemu TCG guest (ie. KVM is known to be
906 disabled or unavailable). If you don't know, don't pass this flag.
907 Note that this function returns a newly allocated buffer which must be
909 freed by the caller.
910 File lib/appliance-uefi.c
912 Find the UEFI firmware needed to boot the appliance.
914 See also lib/uefi.c (autogenerated file) containing the firmware file
916 locations.
917 Function "lib/appliance-uefi.c:guestfs_int_get_uefi"
919 int
921 guestfs_int_get_uefi (guestfs_h *g, char *const *firmwares,
922 const char **firmware, char **code, char **vars,
923 int *flags)
924 Return the location of firmware needed to boot the appliance. This is
926 aarch64 only currently, since that's the only architecture where UEFI
927 is mandatory (and that only for RHEL).
928 "firmwares" is an optional list of allowed values for the firmware
930 autoselection of libvirt. It is "NULL" to indicate it is not supported.
931 *firmware is set to one of the strings in "firmwares" in case one can
932 be used.
933 *code is initialized with the path to the read-only UEFI code file.
935 *vars is initialized with the path to a copy of the UEFI vars file
936 (which is cleaned up automatically on exit).
937 In case a UEFI firmware is available, either *firmware is set to a
939 non-"NULL" value, or *code and *vars are.
940 *code and *vars should be freed by the caller, and *firmware must not.
942 If the function returns "-1" then there was a real error which should
944 cause appliance building to fail (no UEFI firmware is not an error).
945 See also virt-v2v.git/v2v/utils.ml:find_uefi_firmware
947 File lib/appliance.c
949 This file deals with building the libguestfs appliance.
951 Function "lib/appliance.c:guestfs_int_build_appliance"
953 int
955 guestfs_int_build_appliance (guestfs_h *g,
956 char **kernel_rtn,
957 char **initrd_rtn,
958 char **appliance_rtn)
959 Locate or build the appliance.
961 This function locates or builds the appliance as necessary, handling
963 the supermin appliance, caching of supermin-built appliances, or using
964 either a fixed or old-style appliance.
965 The return value is 0 = good, "-1" = error. Returned in
967 "appliance.kernel" will be the name of the kernel to use,
968 "appliance.initrd" the name of the initrd, "appliance.image" the name
969 of the ext2 root filesystem. "appliance.image" can be "NULL", meaning
970 that we are using an old-style (non-ext2) appliance. All three strings
971 must be freed by the caller. However the referenced files themselves
972 must not be deleted.
973 The process is as follows:
975 1. Look in "path" which contains a supermin appliance skeleton. If no
977 element has this, skip straight to step 3.
978 2. Call "supermin --build" to build the full appliance (if it needs to
980 be rebuilt). If this is successful, return the full appliance.
981 3. Check "path", looking for a fixed appliance. If one is found,
983 return it.
984 4. Check "path", looking for an old-style appliance. If one is found,
986 return it.
987 The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/
989 and consists of up to four files:
990 $TMPDIR/.guestfs-$UID/lock - the supermin lock file
992 $TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
993 $TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
994 $TMPDIR/.guestfs-$UID/appliance.d/root - the appliance
995 Multiple instances of libguestfs with the same UID may be racing to
997 create an appliance. However (since supermin ≥ 5) supermin provides a
998 --lock flag and atomic update of the appliance.d subdirectory.
999 Function "lib/appliance.c:locate_or_build_appliance"
1001 static int
1003 locate_or_build_appliance (guestfs_h *g,
1004 struct appliance_files *appliance,
1005 const char *path)
1006 Check "path", looking for one of appliances: supermin appliance, fixed
1008 appliance or old-style appliance. If one of the fixed appliances is
1009 found, return it. If the supermin appliance skeleton is found, build
1010 and return appliance.
1011 Return values:
1013 1 = appliance is found, returns C<appliance>,
1015 0 = appliance not found,
1016 -1 = error which aborts the launch process.
1017 Function "lib/appliance.c:search_appliance"
1019 static int
1021 search_appliance (guestfs_h *g, struct appliance_files *appliance)
1022 Search elements of "g->path", returning the first "appliance" element
1024 which matches the predicate function "locate_or_build_appliance".
1025 Return values:
1027 1 = a path element matched, returns C<appliance>,
1029 0 = no path element matched,
1030 -1 = error which aborts the launch process.
1031 Function "lib/appliance.c:build_supermin_appliance"
1033 static int
1035 build_supermin_appliance (guestfs_h *g,
1036 const char *supermin_path,
1037 struct appliance_files *appliance)
1038 Build supermin appliance from "supermin_path" to $TMPDIR/.guestfs-$UID.
1040 Returns: 0 = built or "-1" = error (aborts launch).
1042 Function "lib/appliance.c:run_supermin_build"
1044 static int
1046 run_supermin_build (guestfs_h *g,
1047 const char *lockfile,
1048 const char *appliancedir,
1049 const char *supermin_path)
1050 Run "supermin --build" and tell it to generate the appliance.
1052 Function "lib/appliance.c:dir_contains_file"
1054 static int
1056 dir_contains_file (guestfs_h *g, const char *dir, const char *file)
1057 Returns true iff "file" is contained in "dir".
1059 Function "lib/appliance.c:dir_contains_files"
1061 static int
1063 dir_contains_files (guestfs_h *g, const char *dir, ...)
1064 Returns true iff every listed file is contained in "dir".
1066 File lib/command.c
1068 A wrapper for running external commands, loosely based on libvirt's
1070 "virCommand" interface.
1071 In outline to use this interface you must:
1073 1. Create a new command handle:
1075 struct command *cmd;
1077 cmd = guestfs_int_new_command (g);
1078 2. Either add arguments:
1080 guestfs_int_cmd_add_arg (cmd, "qemu-img");
1082 guestfs_int_cmd_add_arg (cmd, "info");
1083 guestfs_int_cmd_add_arg (cmd, filename);
1084 (NB: You don't need to add a "NULL" argument at the end.)
1086 3. Or construct a command using a mix of quoted and unquoted strings.
1088 (This is useful for system(3)/"popen("r")"-style shell commands,
1089 with the added safety of allowing args to be quoted properly).
1090 guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
1092 guestfs_int_cmd_add_string_quoted (cmd, filename);
1093 4. Set various flags, such as whether you want to capture errors in
1095 the regular libguestfs error log.
1096 5. Run the command. This is what does the fork(2) call, optionally
1098 loops over the output, and then does a waitpid(3) and returns the
1099 exit status of the command.
1100 r = guestfs_int_cmd_run (cmd);
1102 if (r == -1)
1103 // error
1104 // else test r using the WIF* functions
1105 6. Close the handle:
1107 guestfs_int_cmd_close (cmd);
1109 (or use "CLEANUP_CMD_CLOSE").
1111 Function "lib/command.c:guestfs_int_new_command"
1113 struct command *
1115 guestfs_int_new_command (guestfs_h *g)
1116 Create a new command handle.
1118 Function "lib/command.c:guestfs_int_cmd_add_arg"
1120 void
1122 guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)
1123 Add single arg (for "execv"-style command execution).
1125 Function "lib/command.c:guestfs_int_cmd_add_arg_format"
1127 void
1129 guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)
1130 Add single arg (for "execv"-style command execution) using a
1132 printf(3)-style format string.
1133 Function "lib/command.c:guestfs_int_cmd_add_string_unquoted"
1135 void
1137 guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)
1138 Add a string (for system(3)-style command execution).
1140 This variant adds the strings without quoting them, which is dangerous
1142 if the string contains untrusted content.
1143 Function "lib/command.c:guestfs_int_cmd_add_string_quoted"
1145 void
1147 guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)
1148 Add a string (for system(3)-style command execution).
1150 The string is enclosed in double quotes, with any special characters
1152 within the string which need escaping done. This is used to add a
1153 single argument to a system(3)-style command string.
1154 Function "lib/command.c:guestfs_int_cmd_set_stdout_callback"
1156 void
1158 guestfs_int_cmd_set_stdout_callback (struct command *cmd,
1159 cmd_stdout_callback stdout_callback,
1160 void *stdout_data, unsigned flags)
1161 Set a callback which will capture stdout.
1163 If flags contains "CMD_STDOUT_FLAG_LINE_BUFFER" (the default), then the
1165 callback is called line by line on the output. If there is a trailing
1166 "\n" then it is automatically removed before the callback is called.
1167 The line buffer is "\0"-terminated.
1168 If flags contains "CMD_STDOUT_FLAG_UNBUFFERED", then buffers are passed
1170 to the callback as it is received from the command. Note in this case
1171 the buffer is not "\0"-terminated, so you need to may attention to the
1172 length field in the callback.
1173 If flags contains "CMD_STDOUT_FLAG_WHOLE_BUFFER", then the callback is
1175 called exactly once, with the entire buffer. Note in this case the
1176 buffer is not "\0"-terminated, so you need to may attention to the
1177 length field in the callback.
1178 Function "lib/command.c:guestfs_int_cmd_set_stderr_to_stdout"
1180 void
1182 guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)
1183 Equivalent to adding "2>&1" to the end of the command. This is
1185 incompatible with the "capture_errors" flag, because it doesn't make
1186 sense to combine them.
1187 Function "lib/command.c:guestfs_int_cmd_clear_capture_errors"
1189 void
1191 guestfs_int_cmd_clear_capture_errors (struct command *cmd)
1192 Clear the "capture_errors" flag. This means that any errors will go to
1194 stderr, instead of being captured in the event log, and that is usually
1195 undesirable.
1196 Function "lib/command.c:guestfs_int_cmd_clear_close_files"
1198 void
1200 guestfs_int_cmd_clear_close_files (struct command *cmd)
1201 Don't close file descriptors after the fork.
1203 XXX Should allow single fds to be sent to child process.
1205 Function "lib/command.c:guestfs_int_cmd_set_child_callback"
1207 void
1209 guestfs_int_cmd_set_child_callback (struct command *cmd,
1210 cmd_child_callback child_callback,
1211 void *data)
1212 Set a function to be executed in the child, right before the execution.
1214 Can be used to setup the child, for example changing its current
1215 directory.
1216 Function "lib/command.c:guestfs_int_cmd_set_child_rlimit"
1218 void
1220 guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)
1221 Set up child rlimits, in case the process we are running could consume
1223 lots of space or time.
1224 Function "lib/command.c:finish_command"
1226 static void
1228 finish_command (struct command *cmd)
1229 Finish off the command by either "NULL"-terminating the argv array or
1231 adding a terminating "\0" to the string, or die with an internal error
1232 if no command has been added.
1233 Function "lib/command.c:loop"
1235 static int
1237 loop (struct command *cmd)
1238 The loop which reads errors and output and directs it either to the log
1240 or to the stdout callback as appropriate.
1241 Function "lib/command.c:guestfs_int_cmd_run"
1243 int
1245 guestfs_int_cmd_run (struct command *cmd)
1246 Fork, run the command, loop over the output, and waitpid.
1248 Returns the exit status. Test it using "WIF*" macros.
1250 On error: Calls "error" and returns "-1".
1252 Function "lib/command.c:guestfs_int_cmd_pipe_run"
1254 int
1256 guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)
1257 Fork and run the command, but don't wait. Roughly equivalent to
1259 "popen (..., "r"|"w")".
1260 Returns the file descriptor of the pipe, connected to stdout ("r") or
1262 stdin ("w") of the child process.
1263 After reading/writing to this pipe, call "guestfs_int_cmd_pipe_wait" to
1265 wait for the status of the child.
1266 Errors from the subcommand cannot be captured to the error log using
1268 this interface. Instead the caller should call
1269 "guestfs_int_cmd_get_pipe_errors" (after "guestfs_int_cmd_pipe_wait"
1270 returns an error).
1271 Function "lib/command.c:guestfs_int_cmd_pipe_wait"
1273 int
1275 guestfs_int_cmd_pipe_wait (struct command *cmd)
1276 Wait for a subprocess created by "guestfs_int_cmd_pipe_run" to finish.
1278 On error (eg. failed syscall) this returns "-1" and sets the error. If
1279 the subcommand fails, then use "WIF*" macros to check this, and call
1280 "guestfs_int_cmd_get_pipe_errors" to read the error messages printed by
1281 the child.
1282 Function "lib/command.c:guestfs_int_cmd_get_pipe_errors"
1284 char *
1286 guestfs_int_cmd_get_pipe_errors (struct command *cmd)
1287 Read the error messages printed by the child. The caller must free the
1289 returned buffer after use.
1290 Function "lib/command.c:guestfs_int_cmd_close"
1292 void
1294 guestfs_int_cmd_close (struct command *cmd)
1295 Close the "cmd" object and free all resources.
1297 Function "lib/command.c:process_line_buffer"
1299 static void
1301 process_line_buffer (struct command *cmd, int closed)
1302 Deal with buffering stdout for the callback.
1304 File lib/conn-socket.c
1306 This file handles connections to the child process where this is done
1308 over regular POSIX sockets.
1309 Function "lib/conn-socket.c:handle_log_message"
1311 static int
1313 handle_log_message (guestfs_h *g,
1314 struct connection_socket *conn)
1315 This is called if "conn->console_sock" becomes ready to read while we
1317 are doing one of the connection operations above. It reads and deals
1318 with the log message.
1319 Returns:
1321 1 log message(s) were handled successfully
1323 0 connection to appliance closed
1325 "-1"
1327 error
1328 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_listening"
1330 struct connection *
1332 guestfs_int_new_conn_socket_listening (guestfs_h *g,
1333 int daemon_accept_sock,
1334 int console_sock)
1335 Create a new socket connection, listening.
1337 Note that it's OK for "console_sock" to be passed as "-1", meaning
1339 there's no console available for this appliance.
1340 After calling this, "daemon_accept_sock" is owned by the connection,
1342 and will be closed properly either in "accept_connection" or
1343 "free_connection".
1344 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_connected"
1346 struct connection *
1348 guestfs_int_new_conn_socket_connected (guestfs_h *g,
1349 int daemon_sock,
1350 int console_sock)
1351 Create a new socket connection, connected.
1353 As above, but the caller passes us a connected "daemon_sock" and
1355 promises not to call "accept_connection".
1356 File lib/create.c
1358 APIs for creating empty disks.
1360 Mostly this consists of wrappers around the qemu-img(1) program.
1362 Definition "lib/create.c:VALID_FORMAT"
1364 #define VALID_FORMAT
1366 Check for valid backing format. Allow any "^[[:alnum]]+$" (in C
1368 locale), but limit the length to something reasonable.
1369 File lib/drives.c
1371 Drives added are stored in an array in the handle. Code here manages
1373 that array and the individual "struct drive" data.
1374 Function "lib/drives.c:create_overlay"
1376 static int
1378 create_overlay (guestfs_h *g, struct drive *drv)
1379 For readonly drives, create an overlay to protect the original drive
1381 content. Note we never need to clean up these overlays since they are
1382 created in the temporary directory and deleted when the handle is
1383 closed.
1384 Function "lib/drives.c:create_drive_file"
1386 static struct drive *
1388 create_drive_file (guestfs_h *g,
1389 const struct drive_create_data *data)
1390 Create and free the "struct drive".
1392 Function "lib/drives.c:create_drive_dev_null"
1394 static struct drive *
1396 create_drive_dev_null (guestfs_h *g,
1397 struct drive_create_data *data)
1398 Create the special /dev/null drive.
1400 Traditionally you have been able to use /dev/null as a filename, as
1402 many times as you like. Ancient KVM (RHEL 5) cannot handle adding
1403 /dev/null readonly. qemu 1.2 + virtio-scsi segfaults when you use any
1404 zero-sized file including /dev/null.
1405 Because of these problems, we replace /dev/null with a non-zero sized
1407 temporary file. This shouldn't make any difference since users are not
1408 supposed to try and access a null drive.
1409 Function "lib/drives.c:drive_to_string"
1411 static char *
1413 drive_to_string (guestfs_h *g, const struct drive *drv)
1414 Convert a "struct drive" to a string for debugging. The caller must
1416 free this string.
1417 Function "lib/drives.c:add_drive_to_handle_at"
1419 static void
1421 add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)
1422 Add "struct drive" to the "g->drives" vector at the given index
1424 "drv_index". If the array isn't large enough it is reallocated. The
1425 index must not contain a drive already.
1426 Function "lib/drives.c:add_drive_to_handle"
1428 static void
1430 add_drive_to_handle (guestfs_h *g, struct drive *d)
1431 Add struct drive to the end of the "g->drives" vector in the handle.
1433 Function "lib/drives.c:guestfs_int_add_dummy_appliance_drive"
1435 void
1437 guestfs_int_add_dummy_appliance_drive (guestfs_h *g)
1438 Called during launch to add a dummy slot to "g->drives".
1440 Function "lib/drives.c:guestfs_int_free_drives"
1442 void
1444 guestfs_int_free_drives (guestfs_h *g)
1445 Free up all the drives in the handle.
1447 Definition "lib/drives.c:VALID_FORMAT"
1449 #define VALID_FORMAT
1451 Check string parameter matches regular expression "^[-_[:alnum:]]+$"
1453 (in C locale).
1454 Definition "lib/drives.c:VALID_DISK_LABEL"
1456 #define VALID_DISK_LABEL
1458 Check the disk label is reasonable. It can't contain certain
1460 characters, eg. '/', ','. However be stricter here and ensure it's
1461 just alphabetic and ≤ 20 characters in length.
1462 Definition "lib/drives.c:VALID_HOSTNAME"
1464 #define VALID_HOSTNAME
1466 Check the server hostname is reasonable.
1468 Function "lib/drives.c:valid_port"
1470 static int
1472 valid_port (int port)
1473 Check the port number is reasonable.
1475 Function "lib/drives.c:valid_blocksize"
1477 static int
1479 valid_blocksize (int blocksize)
1480 Check the block size is reasonable. It can't be other then 512 or
1482 4096.
1483 Function "lib/drives.c:guestfs_int_checkpoint_drives"
1485 size_t
1487 guestfs_int_checkpoint_drives (guestfs_h *g)
1488 Checkpoint and roll back drives, so that groups of drives can be added
1490 atomically. Only used by "guestfs_add_domain" in guestfs(3).
1491 Function "lib/drives.c:guestfs_impl_debug_drives"
1493 char **
1495 guestfs_impl_debug_drives (guestfs_h *g)
1496 Internal function to return the list of drives.
1498 File lib/errors.c
1500 This file handles errors, and also debug, trace and warning messages.
1502 Errors in libguestfs API calls are handled by setting an error message
1504 and optional errno in the handle. The caller has the choice of testing
1505 API calls to find out if they failed and then querying the last error
1506 from the handle, and/or getting a callback.
1507 From the point of view of the library source, generally you should use
1509 the "error" or "perrorf" macros along error paths, eg:
1510 if (something_bad) {
1512 error (g, "something bad happened");
1513 return -1;
1514 }
1515 Make sure to call the "error" or "perrorf" macro exactly once along
1517 each error path, since the handle can only store a single error and the
1518 previous error will be overwritten.
1519 Function "lib/errors.c:guestfs_int_warning"
1521 void
1523 guestfs_int_warning (guestfs_h *g, const char *fs, ...)
1524 Print a warning.
1526 Code should not call this function directly. Use the
1528 "warning (g, fs, ...)" macro.
1529 Warnings are printed unconditionally. We try to make these rare:
1531 Generally speaking, a warning should either be an error, or if it's not
1532 important for end users then it should be a debug message.
1533 Function "lib/errors.c:guestfs_int_debug"
1535 void
1537 guestfs_int_debug (guestfs_h *g, const char *fs, ...)
1538 Print a debug message.
1540 Code should not call this function directly. To add debug messages in
1542 the library, use the "debug (g, fs, ...)" macro. The macro checks if
1543 "g->verbose" is false and avoids the function call, meaning the macro
1544 is more efficient.
1545 Function "lib/errors.c:guestfs_int_trace"
1547 void
1549 guestfs_int_trace (guestfs_h *g, const char *fs, ...)
1550 Print a trace message.
1552 Do not call this function. All calls are generated automatically.
1554 Function "lib/errors.c:guestfs_int_error_errno"
1556 void
1558 guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)
1559 Set the last error and errno in the handle, and optionally raise the
1561 error callback if one is defined.
1562 If you don't need to set errno, use the "error (g, fs, ...)" macro
1564 instead of calling this directly. If you need to set errno then there
1565 is no macro wrapper, so calling this function directly is fine.
1566 Function "lib/errors.c:guestfs_int_perrorf"
1568 void
1570 guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)
1571 Similar to perror(3), but it sets the last error in the handle, raises
1573 the error callback if one is defined, and supports format strings.
1574 You should probably use the "perrorf (g, fs, ...)" macro instead of
1576 calling this directly.
1577 Function "lib/errors.c:guestfs_int_launch_failed_error"
1579 void
1581 guestfs_int_launch_failed_error (guestfs_h *g)
1582 Raise a launch failed error in a standard format.
1584 Since this is the most common error seen by people who have
1586 installation problems, buggy qemu, etc, and since no one reads the FAQ,
1587 describe in this error message what resources are available to debug
1588 launch problems.
1589 Function "lib/errors.c:guestfs_int_unexpected_close_error"
1591 void
1593 guestfs_int_unexpected_close_error (guestfs_h *g)
1594 Raise an error if the appliance unexpectedly crashes after launch.
1596 Function "lib/errors.c:guestfs_int_launch_timeout"
1598 void
1600 guestfs_int_launch_timeout (guestfs_h *g)
1601 Raise an error if the appliance hangs during launch.
1603 Function "lib/errors.c:guestfs_int_external_command_failed"
1605 void
1607 guestfs_int_external_command_failed (guestfs_h *g, int status,
1608 const char *cmd_name, const char *extra)
1609 Raise an error if an external command fails.
1611 "status" is the status code of the command (eg. returned from
1613 waitpid(2) or system(3)). This function turns the status code into an
1614 explanatory string.
1615 File lib/events.c
1617 Function "lib/events.c:replace_old_style_event_callback"
1619 static void
1621 replace_old_style_event_callback (guestfs_h *g,
1622 guestfs_event_callback cb,
1623 uint64_t event_bitmask,
1624 void *opaque,
1625 void *opaque2)
1626 Emulate old-style callback API.
1628 There were no event handles, so multiple callbacks per event were not
1630 supported. Calling the same "guestfs_set_*_callback" function would
1631 replace the existing event. Calling it with "cb == NULL" meant that
1632 the caller wanted to remove the callback.
1633 File lib/guestfs-internal-all.h
1635 This header contains definitions which are shared by all parts of
1637 libguestfs, ie. the daemon, the library, language bindings and virt
1638 tools (ie. all C code).
1639 If you need a definition used by only the library, put it in
1641 lib/guestfs-internal.h instead.
1642 If a definition is used by only a single tool, it should not be in any
1644 shared header file at all.
1645 File lib/guestfs-internal.h
1647 This header file is included in the libguestfs library (lib/) only.
1649 See also lib/guestfs-internal-all.h.
1651 Structure "lib/guestfs-internal.h:event"
1653 struct event {
1655 uint64_t event_bitmask;
1656 guestfs_event_callback cb;
1657 void *opaque;
1658 /* opaque2 is not exposed through the API, but is used internally to
1660 * emulate the old-style callback API.
1661 */
1662 void *opaque2;
1663 };
1664 This struct is used to maintain a list of events registered against the
1666 handle. See "g->events" in the handle.
1667 Structure "lib/guestfs-internal.h:drive"
1669 struct drive {
1671 /* Original source of the drive, eg. file:..., http:... */
1672 struct drive_source src;
1673 /* If the drive is readonly, then an overlay [a local file] is
1675 * created before launch to protect the original drive content, and
1676 * the filename is stored here. Backends should open this file if
1677 * it is non-NULL, else consult the original source above.
1678 *
1679 * Note that the overlay is in a backend-specific format, probably
1680 * different from the source format. eg. qcow2
1681 */
1682 char *overlay;
1683 /* Various per-drive flags. */
1685 bool readonly;
1686 char *name;
1687 char *disk_label;
1688 char *cachemode;
1689 enum discard discard;
1690 bool copyonread;
1691 int blocksize;
1692 };
1693 There is one "struct drive" per drive.
1695 Structure "lib/guestfs-internal.h:backend_ops"
1697 struct backend_ops {
1699 /* Size (in bytes) of the per-handle data structure needed by this
1700 * backend. The data pointer is allocated and freed by libguestfs
1701 * and passed to the functions in the 'void *data' parameter.
1702 * Inside the data structure is opaque to libguestfs. Any strings
1703 * etc pointed to by it must be freed by the backend during
1704 * shutdown.
1705 */
1706 size_t data_size;
1707 /* Create a COW overlay on top of a drive. This must be a local
1709 * file, created in the temporary directory. This is called when
1710 * the drive is added to the handle.
1711 */
1712 char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);
1713 /* Launch and shut down. */
1715 int (*launch) (guestfs_h *g, void *data, const char *arg);
1716 int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);
1717 /* Miscellaneous. */
1719 int (*get_pid) (guestfs_h *g, void *data);
1720 int (*max_disks) (guestfs_h *g, void *data);
1721 };
1722 Backend operations.
1724 Each backend (eg. libvirt, direct) defines some functions which get run
1726 at various places in the handle lifecycle (eg. at launch, shutdown).
1727 The backend defines this struct pointing to those functions.
1728 Structure "lib/guestfs-internal.h:connection"
1730 struct connection {
1732 const struct connection_ops *ops;
1733 /* In the real struct, private data used by each connection module
1735 * follows here.
1736 */
1737 };
1738 Connection module.
1740 A "connection" represents the appliance console connection plus the
1742 daemon connection. It hides the underlying representation (POSIX
1743 sockets, "virStreamPtr").
1744 Structure "lib/guestfs-internal.h:cached_feature"
1746 struct cached_feature {
1748 char *group;
1749 int result;
1750 };
1751 Cache of queried features.
1753 Used to cache the appliance features (see lib/available.c).
1755 Structure "lib/guestfs-internal.h:guestfs_h"
1757 struct guestfs_h {
1759 struct guestfs_h *next; /* Linked list of open handles. */
1760 enum state state; /* See the state machine diagram in guestfs(3)*/
1761 /* Lock acquired when entering any public guestfs_* function to
1763 * protect the handle.
1764 */
1765 pthread_mutex_t lock;
1766 /**** Configuration of the handle. ****/
1768 bool verbose; /* Debugging. */
1769 bool trace; /* Trace calls. */
1770 bool autosync; /* Autosync. */
1771 bool direct_mode; /* Direct mode. */
1772 bool recovery_proc; /* Create a recovery process. */
1773 bool enable_network; /* Enable the network. */
1774 bool selinux; /* selinux enabled? */
1775 bool pgroup; /* Create process group for children? */
1776 bool close_on_exit; /* Is this handle on the atexit list? */
1777 int smp; /* If > 1, -smp flag passed to hv. */
1779 int memsize; /* Size of RAM (megabytes). */
1780 char *path; /* Path to the appliance. */
1782 char *hv; /* Hypervisor (HV) binary. */
1783 char *append; /* Append to kernel command line. */
1784 struct hv_param *hv_params; /* Extra hv parameters. */
1786 char *program; /* Program name. */
1788 char *identifier; /* Handle identifier. */
1789 /* Array of drives added by add-drive* APIs.
1791 *
1792 * Before launch this list can be empty or contain some drives.
1793 *
1794 * During launch, a dummy slot may be added which represents the
1795 * slot taken up by the appliance drive.
1796 *
1797 * During shutdown, this list is deleted, so that each launch gets a
1798 * fresh set of drives (however callers: don't do this, create a new
1799 * handle each time).
1800 *
1801 * Always use ITER_DRIVES macro to iterate over this list!
1802 */
1803 struct drive **drives;
1804 size_t nr_drives;
1805 #define ITER_DRIVES(g,i,drv) \
1807 for (i = 0; i < (g)->nr_drives; ++i) \
1808 if (((drv) = (g)->drives[i]) != NULL)
1809 /* Backend. NB: Use guestfs_int_set_backend to change the backend. */
1811 char *backend; /* The full string, always non-NULL. */
1812 char *backend_arg; /* Pointer to the argument part. */
1813 const struct backend_ops *backend_ops;
1814 void *backend_data; /* Per-handle data. */
1815 char **backend_settings; /* Backend settings (can be NULL). */
1816 /**** Runtime information. ****/
1818 /* Temporary and cache directories. */
1819 /* The actual temporary directory - this is not created with the
1820 * handle, you have to call guestfs_int_lazy_make_tmpdir.
1821 */
1822 char *tmpdir;
1823 char *sockdir;
1824 /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
1825 char *env_tmpdir; /* $TMPDIR (NULL if not set) */
1826 char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/
1827 char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
1828 char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */
1829 /* Error handler, plus stack of old error handlers. */
1831 pthread_key_t error_data;
1832 /* Linked list of error_data structures allocated for this handle,
1834 * plus a mutex to protect the linked list.
1835 */
1836 pthread_mutex_t error_data_list_lock;
1837 struct error_data *error_data_list;
1838 /* Out of memory error handler. */
1840 guestfs_abort_cb abort_cb;
1841 /* Events. */
1843 struct event *events;
1844 size_t nr_events;
1845 /* Private data area. */
1847 struct hash_table *pda;
1848 struct pda_entry *pda_next;
1849 /* User cancelled transfer. Not signal-atomic, but it doesn't
1851 * matter for this case because we only care if it is != 0.
1852 */
1853 int user_cancel;
1854 struct timeval launch_t; /* The time that we called guestfs_launch. */
1856 /* Used by bindtests. */
1858 FILE *test_fp;
1859 /* Used to generate unique numbers, eg for temp files. To use this,
1861 * '++g->unique'. Note these are only unique per-handle, not
1862 * globally unique.
1863 */
1864 int unique;
1865 /*** Protocol. ***/
1867 struct connection *conn; /* Connection to appliance. */
1868 int msg_next_serial;
1869 #if HAVE_FUSE
1871 /**** Used by the mount-local APIs. ****/
1872 char *localmountpoint;
1873 struct fuse *fuse; /* FUSE handle. */
1874 int ml_dir_cache_timeout; /* Directory cache timeout. */
1875 Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
1876 int ml_read_only; /* If mounted read-only. */
1877 int ml_debug_calls; /* Extra debug info on each FUSE call. */
1878 #endif
1879 #ifdef HAVE_LIBVIRT_BACKEND
1881 /* Used by lib/libvirt-auth.c. */
1882 #define NR_CREDENTIAL_TYPES 9
1883 unsigned int nr_supported_credentials;
1884 int supported_credentials[NR_CREDENTIAL_TYPES];
1885 const char *saved_libvirt_uri; /* Doesn't need to be freed. */
1886 bool wrapper_warning_done;
1887 unsigned int nr_requested_credentials;
1888 virConnectCredentialPtr requested_credentials;
1889 #endif
1890 /* Cached features. */
1892 struct cached_feature *features;
1893 size_t nr_features;
1894 /* Used by lib/info.c. -1 = not tested or error; else 0 or 1. */
1896 int qemu_img_supports_U_option;
1897 };
1898 The libguestfs handle.
1900 Structure "lib/guestfs-internal.h:version"
1902 struct version {
1904 int v_major;
1905 int v_minor;
1906 int v_micro;
1907 };
1908 Used for storing major.minor.micro version numbers. See lib/version.c
1910 for more information.
1911 File lib/guid.c
1913 Function "lib/guid.c:guestfs_int_validate_guid"
1915 int
1917 guestfs_int_validate_guid (const char *str)
1918 Check whether a string supposed to contain a GUID actually contains it.
1920 It can recognize strings either as
1921 "{21EC2020-3AEA-1069-A2DD-08002B30309D}" or
1922 "21EC2020-3AEA-1069-A2DD-08002B30309D".
1923 File lib/handle.c
1925 This file deals with the "guestfs_h" handle, creating it, closing it,
1927 and initializing/setting/getting fields.
1928 Function "lib/handle.c:init_libguestfs"
1930 static void
1932 init_libguestfs (void)
1933 No initialization is required by libguestfs, but libvirt and libxml2
1935 require initialization if they might be called from multiple threads.
1936 Hence this constructor function which is called when libguestfs is
1937 first loaded.
1938 Function "lib/handle.c:shutdown_backend"
1940 static int
1942 shutdown_backend (guestfs_h *g, int check_for_errors)
1943 This function is the common path for shutting down the backend qemu
1945 process.
1946 "guestfs_shutdown" calls "shutdown_backend" with "check_for_errors=1".
1948 "guestfs_close" calls "shutdown_backend" with "check_for_errors=0".
1949 "check_for_errors" is a hint to the backend about whether we care about
1951 errors or not. In the libvirt case it can be used to optimize the
1952 shutdown for speed when we don't care.
1953 Function "lib/handle.c:close_handles"
1955 static void
1957 close_handles (void)
1958 Close all open handles (called from atexit(3)).
1960 Function "lib/handle.c:guestfs_int_get_backend_setting_bool"
1962 int
1964 guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)
1965 This is a convenience function, but we might consider exporting it as
1967 an API in future.
1968 File lib/info.c
1970 Function "lib/info.c:qemu_img_supports_U_option"
1972 static int
1974 qemu_img_supports_U_option (guestfs_h *g)
1975 Test if the qemu-img info command supports the "-U" option to disable
1977 locking. The result is memoized in the handle.
1978 Note this option was added in qemu 2.11. We can remove this test when
1980 we can assume everyone is using qemu >= 2.11.
1981 File lib/inspect-icon.c
1983 Function "lib/inspect-icon.c:guestfs_int_download_to_tmp"
1985 char *
1987 guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
1988 const char *extension,
1989 uint64_t max_size)
1990 Download a guest file to a local temporary file.
1992 The name of the temporary (downloaded) file is returned. The caller
1994 must free the pointer, but does not need to delete the temporary file.
1995 It will be deleted when the handle is closed.
1996 The name of the temporary file is randomly generated, but an extension
1998 can be specified using "extension" (or pass "NULL" for none).
1999 Refuse to download the guest file if it is larger than "max_size". On
2001 this and other errors, "NULL" is returned.
2002 File lib/launch-direct.c
2004 Implementation of the "direct" backend.
2006 For more details see "BACKENDS" in guestfs(3).
2008 Function "lib/launch-direct.c:add_drive_standard_params"
2010 static int
2012 add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
2013 struct qemuopts *qopts,
2014 size_t i, struct drive *drv)
2015 Add the standard elements of the "-drive" parameter.
2017 Function "lib/launch-direct.c:add_device_blocksize_params"
2019 static int
2021 add_device_blocksize_params (guestfs_h *g, struct qemuopts *qopts,
2022 struct drive *drv)
2023 Add the physical_block_size and logical_block_size elements of the
2025 "-device" parameter.
2026 File lib/launch-libvirt.c
2028 Function "lib/launch-libvirt.c:get_source_format_or_autodetect"
2030 static char *
2032 get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)
2033 Return "drv->src.format", but if it is "NULL", autodetect the format.
2035 libvirt has disabled the feature of detecting the disk format, unless
2037 the administrator sets "allow_disk_format_probing=1" in
2038 /etc/libvirt/qemu.conf. There is no way to detect if this option is
2039 set, so we have to do format detection here using "qemu-img" and pass
2040 that to libvirt.
2041 This can still be a security issue, so in most cases it is recommended
2043 the users pass the format to libguestfs which will faithfully pass that
2044 straight through to libvirt without doing autodetection.
2045 Caller must free the returned string. On error this function sets the
2047 error in the handle and returns "NULL".
2048 Function "lib/launch-libvirt.c:make_qcow2_overlay"
2050 static char *
2052 make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
2053 const char *format)
2054 Create a qcow2 format overlay, with the given "backing_drive" (file).
2056 The "format" parameter is the backing file format. The "format"
2057 parameter can be NULL, in this case the backing format will be
2058 determined automatically. This is used to create the appliance
2059 overlay, and also for read-only drives.
2060 File lib/launch.c
2062 This file implements "guestfs_launch" in guestfs(3).
2064 Most of the work is done by the backends (see "BACKEND" in guestfs(3)),
2066 which are implemented in lib/launch-direct.c, lib/launch-libvirt.c etc,
2067 so this file mostly passes calls through to the current backend.
2068 Function "lib/launch.c:guestfs_int_launch_send_progress"
2070 void
2072 guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)
2073 This function sends a launch progress message.
2075 Launching the appliance generates approximate progress messages.
2077 Currently these are defined as follows:
2078 0 / 12: launch clock starts
2080 3 / 12: appliance created
2081 6 / 12: detected that guest kernel started
2082 9 / 12: detected that /init script is running
2083 12 / 12: launch completed successfully
2084 Notes:
2086 1. This is not a documented ABI and the behaviour may be changed or
2088 removed in future.
2089 2. Messages are only sent if more than 5 seconds has elapsed since the
2091 launch clock started.
2092 3. There is a hack in lib/proto.c to make this work.
2094 Function "lib/launch.c:guestfs_int_timeval_diff"
2096 int64_t
2098 guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)
2099 Compute "y - x" and return the result in milliseconds.
2101 Approximately the same as this code:
2103 http://www.mpp.mpg.de/~huber/util/timevaldiff.c
2104 Function "lib/launch.c:guestfs_int_unblock_sigterm"
2106 void
2108 guestfs_int_unblock_sigterm (void)
2109 Unblock the "SIGTERM" signal. Call this after fork(2) so that the
2111 parent process can send "SIGTERM" to the child process in case
2112 "SIGTERM" is blocked. See https://bugzilla.redhat.com/1460338.
2113 Function "lib/launch.c:guestfs_impl_max_disks"
2115 int
2117 guestfs_impl_max_disks (guestfs_h *g)
2118 Returns the maximum number of disks allowed to be added to the backend
2120 (backend dependent).
2121 Function "lib/launch.c:guestfs_impl_wait_ready"
2123 int
2125 guestfs_impl_wait_ready (guestfs_h *g)
2126 Implementation of "guestfs_wait_ready" in guestfs(3). You had to call
2128 this function after launch in versions ≤ 1.0.70, but it is now an
2129 (almost) no-op.
2130 Function "lib/launch.c:guestfs_int_create_socketname"
2132 int
2134 guestfs_int_create_socketname (guestfs_h *g, const char *filename,
2135 char (*sockpath)[UNIX_PATH_MAX])
2136 Create the path for a socket with the selected filename in the tmpdir.
2138 Function "lib/launch.c:guestfs_int_register_backend"
2140 void
2142 guestfs_int_register_backend (const char *name, const struct backend_ops *ops)
2143 When the library is loaded, each backend calls this function to
2145 register itself in a global list.
2146 Function "lib/launch.c:guestfs_int_set_backend"
2148 int
2150 guestfs_int_set_backend (guestfs_h *g, const char *method)
2151 Implementation of "guestfs_set_backend" in guestfs(3).
2153 • Callers must ensure this is only called in the config state.
2155 • This shouldn't call "error" since it may be called early in handle
2157 initialization. It can return an error code however.
2158 File lib/private-data.c
2160 Implement a private data area where libguestfs C API users can attach
2162 arbitrary pieces of data to a "guestfs_h" handle.
2163 For more information see "PRIVATE DATA AREA" in guestfs(3).
2165 Language bindings do not generally expose this, largely because in non-
2167 C languages it is easy to associate data with handles in other ways
2168 (using hash tables or maps).
2169 Structure "lib/private-data.c:pda_entry"
2171 struct pda_entry {
2173 char *key; /* key */
2174 void *data; /* opaque user data pointer */
2175 };
2176 The private data area is internally stored as a gnulib hash table
2178 containing "pda_entry" structures.
2179 Note the private data area is allocated lazily, since the vast majority
2181 of callers will never use it. This means "g->pda" is likely to be
2182 "NULL".
2183 File lib/proto.c
2185 This is the code used to send and receive RPC messages and (for certain
2187 types of message) to perform file transfers. This code is driven from
2188 the generated actions (lib/actions-*.c). There are five different
2189 cases to consider:
2190 1. A non-daemon function (eg. "guestfs_set_verbose" in guestfs(3)).
2192 There is no RPC involved at all, it's all handled inside the
2193 library.
2194 2. A simple RPC (eg. "guestfs_mount" in guestfs(3)). We write the
2196 request, then read the reply. The sequence of calls is:
2197 guestfs_int_send
2199 guestfs_int_recv
2200 3. An RPC with "FileIn" parameters (eg. "guestfs_upload" in
2202 guestfs(3)). We write the request, then write the file(s), then
2203 read the reply. The sequence of calls is:
2204 guestfs_int_send
2206 guestfs_int_send_file (possibly multiple times)
2207 guestfs_int_recv
2208 4. An RPC with "FileOut" parameters (eg. "guestfs_download" in
2210 guestfs(3)). We write the request, then read the reply, then read
2211 the file(s). The sequence of calls is:
2212 guestfs_int_send
2214 guestfs_int_recv
2215 guestfs_int_recv_file (possibly multiple times)
2216 5. Both "FileIn" and "FileOut" parameters. There are no calls like
2218 this in the current API, but they would be implemented as a
2219 combination of cases 3 and 4.
2220 All read/write/etc operations are performed using the current
2222 connection module ("g->conn"). During operations the connection module
2223 transparently handles log messages that appear on the console.
2224 Function "lib/proto.c:child_cleanup"
2226 static void
2228 child_cleanup (guestfs_h *g)
2229 This is called if we detect EOF, ie. qemu died.
2231 Function "lib/proto.c:guestfs_int_progress_message_callback"
2233 void
2235 guestfs_int_progress_message_callback (guestfs_h *g,
2236 const guestfs_progress *message)
2237 Convenient wrapper to generate a progress message callback.
2239 Function "lib/proto.c:guestfs_int_log_message_callback"
2241 void
2243 guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)
2244 Connection modules call us back here when they get a log message.
2246 Function "lib/proto.c:check_daemon_socket"
2248 static ssize_t
2250 check_daemon_socket (guestfs_h *g)
2251 Before writing to the daemon socket, check the read side of the daemon
2253 socket for any of these conditions:
2254 error
2256 return -1
2257 daemon cancellation message
2259 return -2
2260 progress message
2262 handle it here
2263 end of input or appliance exited unexpectedly
2265 return 0
2266 anything else
2268 return 1
2269 Function "lib/proto.c:guestfs_int_send_file"
2271 int
2273 guestfs_int_send_file (guestfs_h *g, const char *filename)
2274 Send a file.
2276 Returns 0 on success, "-1" for error, "-2" if the daemon cancelled (we
2278 must read the error message).
2279 Function "lib/proto.c:send_file_data"
2281 static int
2283 send_file_data (guestfs_h *g, const char *buf, size_t len)
2284 Send a chunk of file data.
2286 Function "lib/proto.c:send_file_cancellation"
2288 static int
2290 send_file_cancellation (guestfs_h *g)
2291 Send a cancellation message.
2293 Function "lib/proto.c:send_file_complete"
2295 static int
2297 send_file_complete (guestfs_h *g)
2298 Send a file complete chunk.
2300 Function "lib/proto.c:recv_from_daemon"
2302 static int
2304 recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)
2305 This function reads a single message, file chunk, launch flag or
2307 cancellation flag from the daemon. If something was read, it returns
2308 0, otherwise "-1".
2309 Both "size_rtn" and "buf_rtn" must be passed by the caller as non-NULL.
2311 *size_rtn returns the size of the returned message or it may be
2313 "GUESTFS_LAUNCH_FLAG" or "GUESTFS_CANCEL_FLAG".
2314 *buf_rtn is returned containing the message (if any) or will be set to
2316 "NULL". *buf_rtn must be freed by the caller.
2317 This checks for EOF (appliance died) and passes that up through the
2319 child_cleanup function above.
2320 Log message, progress messages are handled transparently here.
2322 Function "lib/proto.c:guestfs_int_recv"
2324 int
2326 guestfs_int_recv (guestfs_h *g, const char *fn,
2327 guestfs_message_header *hdr,
2328 guestfs_message_error *err,
2329 xdrproc_t xdrp, char *ret)
2330 Receive a reply.
2332 Function "lib/proto.c:guestfs_int_recv_discard"
2334 int
2336 guestfs_int_recv_discard (guestfs_h *g, const char *fn)
2337 Same as "guestfs_int_recv", but it discards the reply message.
2339 Notes (XXX):
2341 • This returns an int, but all current callers ignore it.
2343 • The error string may end up being set twice on error paths.
2345 Function "lib/proto.c:guestfs_int_recv_file"
2347 int
2349 guestfs_int_recv_file (guestfs_h *g, const char *filename)
2350 Returns "-1" = error, 0 = EOF, ">0" = more data
2352 Function "lib/proto.c:receive_file_data"
2354 static ssize_t
2356 receive_file_data (guestfs_h *g, void **buf_r)
2357 Receive a chunk of file data.
2359 Returns "-1" = error, 0 = EOF, ">0" = more data
2361 File lib/qemu.c
2363 Functions to handle qemu versions and features.
2365 Function "lib/qemu.c:guestfs_int_test_qemu"
2367 struct qemu_data *
2369 guestfs_int_test_qemu (guestfs_h *g)
2370 Test that the qemu binary (or wrapper) runs, and do "qemu -help" and
2372 other commands so we can find out the version of qemu and what options
2373 this qemu supports.
2374 This caches the results in the cachedir so that as long as the qemu
2376 binary does not change, calling this is effectively free.
2377 Function "lib/qemu.c:cache_filename"
2379 static char *
2381 cache_filename (guestfs_h *g, const char *cachedir,
2382 const struct stat *statbuf, const char *suffix)
2383 Generate the filenames, for the stat file and the other cache files.
2385 By including the size and mtime in the filename we also ensure that the
2387 same user can use multiple versions of qemu without conflicts.
2388 Function "lib/qemu.c:parse_qemu_version"
2390 static void
2392 parse_qemu_version (guestfs_h *g, const char *qemu_help,
2393 struct version *qemu_version)
2394 Parse the first line of "qemu_help" into the major and minor version of
2396 qemu, but don't fail if parsing is not possible.
2397 Function "lib/qemu.c:parse_json"
2399 static void
2401 parse_json (guestfs_h *g, const char *json, json_t **treep)
2402 Parse the json output from QMP. But don't fail if parsing is not
2404 possible.
2405 Function "lib/qemu.c:parse_has_kvm"
2407 static void
2409 parse_has_kvm (guestfs_h *g, const char *json, bool *ret)
2410 Parse the json output from QMP query-kvm to find out if KVM is enabled
2412 on this machine. Don't fail if parsing is not possible, assume KVM is
2413 available.
2414 The JSON output looks like: {"return": {"enabled": true, "present":
2416 true}}
2417 Function "lib/qemu.c:generic_read_cache"
2419 static int
2421 generic_read_cache (guestfs_h *g, const char *filename, char **strp)
2422 Generic functions for reading and writing the cache files, used where
2424 we are just reading and writing plain text strings.
2425 Function "lib/qemu.c:generic_qmp_test"
2427 static int
2429 generic_qmp_test (guestfs_h *g, struct qemu_data *data,
2430 const char *qmp_command,
2431 char **outp)
2432 Run a generic QMP test on the QEMU binary.
2434 Function "lib/qemu.c:guestfs_int_qemu_version"
2436 struct version
2438 guestfs_int_qemu_version (guestfs_h *g, struct qemu_data *data)
2439 Return the parsed version of qemu.
2441 Function "lib/qemu.c:guestfs_int_qemu_supports"
2443 int
2445 guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data,
2446 const char *option)
2447 Test if option is supported by qemu command line (just by grepping the
2449 help text).
2450 Function "lib/qemu.c:guestfs_int_qemu_supports_device"
2452 int
2454 guestfs_int_qemu_supports_device (guestfs_h *g,
2455 const struct qemu_data *data,
2456 const char *device_name)
2457 Test if device is supported by qemu (currently just greps the "qemu
2459 -device ?" output).
2460 Function "lib/qemu.c:guestfs_int_qemu_mandatory_locking"
2462 int
2464 guestfs_int_qemu_mandatory_locking (guestfs_h *g,
2465 const struct qemu_data *data)
2466 Test if the qemu binary uses mandatory file locking, added in QEMU >=
2468 2.10 (but sometimes disabled).
2469 Function "lib/qemu.c:guestfs_int_qemu_escape_param"
2471 char *
2473 guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)
2474 Escape a qemu parameter.
2476 Every "," becomes ",,". The caller must free the returned string.
2478 XXX This functionality is now only used when constructing a qemu-img
2480 command in lib/create.c. We should extend the qemuopts library to
2481 cover this use case.
2482 Function "lib/qemu.c:guestfs_int_drive_source_qemu_param"
2484 char *
2486 guestfs_int_drive_source_qemu_param (guestfs_h *g,
2487 const struct drive_source *src)
2488 Useful function to format a drive + protocol for qemu.
2490 Note that the qemu parameter is the bit after "file=". It is not
2492 escaped here, but would usually be escaped if passed to qemu as part of
2493 a full -drive parameter (but not for qemu-img(1)).
2494 Function "lib/qemu.c:guestfs_int_discard_possible"
2496 bool
2498 guestfs_int_discard_possible (guestfs_h *g, struct drive *drv,
2499 const struct version *qemu_version)
2500 Test if discard is both supported by qemu AND possible with the
2502 underlying file or device. This returns 1 if discard is possible. It
2503 returns 0 if not possible and sets the error to the reason why.
2504 This function is called when the user set "discard == "enable"".
2506 Function "lib/qemu.c:guestfs_int_free_qemu_data"
2508 void
2510 guestfs_int_free_qemu_data (struct qemu_data *data)
2511 Free the "struct qemu_data".
2513 File lib/rescue.c
2515 Support for virt-rescue(1).
2517 File lib/stringsbuf.c
2519 An expandable NULL-terminated vector of strings (like "argv").
2521 Use the "DECLARE_STRINGSBUF" macro to declare the stringsbuf.
2523 Note: Don't confuse this with stringsbuf in the daemon which is a
2525 different type with different methods.
2526 Function "lib/stringsbuf.c:guestfs_int_add_string_nodup"
2528 void
2530 guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)
2531 Add a string to the end of the list.
2533 This doesn't call strdup(3) on the string, so the string itself is
2535 stored inside the vector.
2536 Function "lib/stringsbuf.c:guestfs_int_add_string"
2538 void
2540 guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)
2541 Add a string to the end of the list.
2543 This makes a copy of the string.
2545 Function "lib/stringsbuf.c:guestfs_int_add_sprintf"
2547 void
2549 guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
2550 const char *fs, ...)
2551 Add a string to the end of the list.
2553 Uses an sprintf-like format string when creating the string.
2555 Function "lib/stringsbuf.c:guestfs_int_end_stringsbuf"
2557 void
2559 guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)
2560 Finish the string buffer.
2562 This adds the terminating NULL to the end of the vector.
2564 Function "lib/stringsbuf.c:guestfs_int_free_stringsbuf"
2566 void
2568 guestfs_int_free_stringsbuf (struct stringsbuf *sb)
2569 Free the string buffer and the strings.
2571 File lib/tmpdirs.c
2573 Handle temporary directories.
2575 Function "lib/tmpdirs.c:set_abs_path"
2577 static int
2579 set_abs_path (guestfs_h *g, const char *ctxstr,
2580 const char *tmpdir, char **tmpdir_ret)
2581 We need to make all tmpdir paths absolute because lots of places in the
2583 code assume this. Do it at the time we set the path or read the
2584 environment variable (https://bugzilla.redhat.com/882417).
2585 The "ctxstr" parameter is a string displayed in error messages giving
2587 the context of the operation (eg. name of environment variable being
2588 used, or API function being called).
2589 Function "lib/tmpdirs.c:guestfs_impl_get_tmpdir"
2591 char *
2593 guestfs_impl_get_tmpdir (guestfs_h *g)
2594 Implements the "guestfs_get_tmpdir" API.
2596 Note this actually calculates the tmpdir, so it never returns "NULL".
2598 Function "lib/tmpdirs.c:guestfs_impl_get_cachedir"
2600 char *
2602 guestfs_impl_get_cachedir (guestfs_h *g)
2603 Implements the "guestfs_get_cachedir" API.
2605 Note this actually calculates the cachedir, so it never returns "NULL".
2607 Function "lib/tmpdirs.c:guestfs_impl_get_sockdir"
2609 char *
2611 guestfs_impl_get_sockdir (guestfs_h *g)
2612 Implements the "guestfs_get_sockdir" API.
2614 Note this actually calculates the sockdir, so it never returns "NULL".
2616 Function "lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir"
2618 int
2620 guestfs_int_lazy_make_tmpdir (guestfs_h *g)
2621 The "g->tmpdir" (per-handle temporary directory) is not created when
2623 the handle is created. Instead we create it lazily before the first
2624 time it is used, or during launch.
2625 Function "lib/tmpdirs.c:guestfs_int_make_temp_path"
2627 char *
2629 guestfs_int_make_temp_path (guestfs_h *g,
2630 const char *name, const char *extension)
2631 Generate unique temporary paths for temporary files.
2633 Returns a unique path or NULL on error.
2635 Function "lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir"
2637 char *
2639 guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)
2640 Create the supermin appliance directory under cachedir, if it does not
2642 exist.
2643 Sanity-check that the permissions on the cachedir are safe, in case it
2645 has been pre-created maliciously or tampered with.
2646 Returns the directory name which the caller must free.
2648 Function "lib/tmpdirs.c:guestfs_int_recursive_remove_dir"
2650 void
2652 guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)
2653 Recursively remove a temporary directory. If removal fails, just
2655 return (it's a temporary directory so it'll eventually be cleaned up by
2656 a temp cleaner).
2657 This is implemented using "rm -rf" because that's simpler and safer.
2659 File lib/umask.c
2661 Return current umask in a thread-safe way.
2663 glibc documents, but does not actually implement, a "getumask(3)" call.
2665 We use "Umask" from /proc/self/status for Linux ≥ 4.7. For older Linux
2667 and other Unix, this file implements an expensive but thread-safe way
2668 to get the current process's umask.
2669 Thanks to: Josh Stone, Jiri Jaburek, Eric Blake.
2671 Function "lib/umask.c:guestfs_int_getumask"
2673 int
2675 guestfs_int_getumask (guestfs_h *g)
2676 Returns the current process's umask. On failure, returns "-1" and sets
2678 the error in the guestfs handle.
2679 Function "lib/umask.c:get_umask_from_proc"
2681 static int
2683 get_umask_from_proc (guestfs_h *g)
2684 For Linux ≥ 4.7 get the umask from /proc/self/status.
2686 On failure this returns "-1". However if we could not open the /proc
2688 file or find the "Umask" entry in it, return "-2" which causes the
2689 fallback path to run.
2690 Function "lib/umask.c:get_umask_from_fork"
2692 static int
2694 get_umask_from_fork (guestfs_h *g)
2695 Fallback method of getting the umask using fork.
2697 File lib/unit-tests.c
2699 Unit tests of internal functions.
2701 These tests may use a libguestfs handle, but must not launch the
2703 handle. Also, avoid long-running tests.
2704 Function "lib/unit-tests.c:test_split"
2706 static void
2708 test_split (void)
2709 Test "guestfs_int_split_string".
2711 Function "lib/unit-tests.c:test_concat"
2713 static void
2715 test_concat (void)
2716 Test "guestfs_int_concat_strings".
2718 Function "lib/unit-tests.c:test_join"
2720 static void
2722 test_join (void)
2723 Test "guestfs_int_join_strings".
2725 Function "lib/unit-tests.c:test_validate_guid"
2727 static void
2729 test_validate_guid (void)
2730 Test "guestfs_int_validate_guid".
2732 Function "lib/unit-tests.c:test_drive_name"
2734 static void
2736 test_drive_name (void)
2737 Test "guestfs_int_drive_name".
2739 Function "lib/unit-tests.c:test_drive_index"
2741 static void
2743 test_drive_index (void)
2744 Test "guestfs_int_drive_index".
2746 Function "lib/unit-tests.c:test_getumask"
2748 static void
2750 test_getumask (void)
2751 Test "guestfs_int_getumask".
2753 Function "lib/unit-tests.c:test_command"
2755 static void
2757 test_command (void)
2758 Test "guestfs_int_new_command" etc.
2760 XXX These tests could be made much more thorough. So far we simply
2762 test that it's not obviously broken.
2763 Function "lib/unit-tests.c:test_qemu_escape_param"
2765 static void
2767 test_qemu_escape_param (void)
2768 Test "guestfs_int_qemu_escape_param"
2770 XXX I wanted to make this test run qemu, passing some parameters which
2772 need to be escaped, but I cannot think of a way to do that without
2773 launching a VM.
2774 Function "lib/unit-tests.c:test_timeval_diff"
2776 static void
2778 test_timeval_diff (void)
2779 Test "guestfs_int_timeval_diff".
2781 File lib/version.c
2783 This file provides simple version number management.
2785 Function "lib/version.c:guestfs_int_version_from_x_y"
2787 int
2789 guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)
2790 Parses a version from a string, looking for a "X.Y" pattern.
2792 Returns "-1" on failure (like failed integer parsing), 0 on missing
2794 match, and 1 on match and successful parsing. "v" is changed only on
2795 successful match.
2796 Function "lib/version.c:guestfs_int_version_from_x_y_re"
2798 int
2800 guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
2801 const char *str, const pcre2_code *re)
2802 Parses a version from a string, using the specified "re" as regular
2804 expression which must provide (at least) two matches.
2805 Returns "-1" on failure (like failed integer parsing), 0 on missing
2807 match, and 1 on match and successful parsing. "v" is changed only on
2808 successful match.
2809 Function "lib/version.c:guestfs_int_version_from_x_y_or_x"
2811 int
2813 guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
2814 const char *str)
2815 Parses a version from a string, either looking for a "X.Y" pattern or
2817 considering it as whole integer.
2818 Returns "-1" on failure (like failed integer parsing), 0 on missing
2820 match, and 1 on match and successful parsing. "v" is changed only on
2821 successful match.
2822 Function "lib/version.c:guestfs_int_parse_unsigned_int"
2824 int
2826 guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)
2827 Parse small, unsigned ints, as used in version numbers.
2829 This will fail with an error if trailing characters are found after the
2831 integer.
2832 Returns ≥ 0 on success, or "-1" on failure.
2834 File lib/wait.c
2836 Function "lib/wait.c:guestfs_int_waitpid"
2838 int
2840 guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)
2841 A safe version of waitpid(3) which retries if "EINTR" is returned.
2843 Note: this only needs to be used in the library, or in programs that
2845 install a non-restartable "SIGCHLD" handler (which is not the case for
2846 any current libguestfs virt tools).
2847 If the main program installs a SIGCHLD handler and sets it to be non-
2849 restartable, then what can happen is the library is waiting in a wait
2850 syscall, the child exits, "SIGCHLD" is sent to the process, and the
2851 wait syscall returns "EINTR". Since the library cannot control the
2852 signal handler, we have to instead restart the wait syscall, which is
2853 the purpose of this wrapper.
2854 Function "lib/wait.c:guestfs_int_waitpid_noerror"
2856 void
2858 guestfs_int_waitpid_noerror (pid_t pid)
2859 Like "guestfs_int_waitpid", but ignore errors.
2861 Function "lib/wait.c:guestfs_int_wait4"
2863 int
2865 guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
2866 struct rusage *rusage, const char *errmsg)
2867 A safe version of wait4(2) which retries if "EINTR" is returned.
2869 File lib/whole-file.c
2871 Function "lib/whole-file.c:guestfs_int_read_whole_file"
2873 int
2875 guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
2876 char **data_r, size_t *size_r)
2877 Read the whole file "filename" into a memory buffer.
2879 The memory buffer is initialized and returned in "data_r". The size of
2881 the file in bytes is returned in "size_r". The return buffer must be
2882 freed by the caller.
2883 On error this sets the error in the handle and returns "-1".
2885 For the convenience of callers, the returned buffer is NUL-terminated
2887 (the NUL is not included in the size).
2888 The file must be a regular, local, trusted file. In particular, do not
2890 use this function to read files that might be under control of an
2891 untrusted user since that will lead to a denial-of-service attack.
2892 Subdirectory common/edit
2894 File common/edit/file-edit.c
2895 This file implements common file editing in a range of utilities
2897 including guestfish(1), virt-edit(1), virt-customize(1) and
2898 virt-builder(1).
2899 It contains the code for both interactive-(editor-)based editing and
2901 non-interactive editing using Perl snippets.
2902 Function "common/edit/file-edit.c:edit_file_editor"
2904 int
2906 edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
2907 const char *backup_extension, int verbose)
2908 Edit "filename" using the specified "editor" application.
2910 If "backup_extension" is not null, then a copy of "filename" is saved
2912 with "backup_extension" appended to its file name.
2913 If "editor" is null, then the $EDITOR environment variable will be
2915 queried for the editor application, leaving "vi" as fallback if not
2916 set.
2917 Returns "-1" for failure, 0 on success, 1 if the editor did not change
2919 the file (e.g. the user closed the editor without saving).
2920 Function "common/edit/file-edit.c:edit_file_perl"
2922 int
2924 edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
2925 const char *backup_extension, int verbose)
2926 Edit "filename" running the specified "perl_expr" using Perl.
2928 If "backup_extension" is not null, then a copy of "filename" is saved
2930 with "backup_extension" appended to its file name.
2931 Returns "-1" for failure, 0 on success.
2933 Subdirectory common/options
2935 File common/options/config.c
2936 This file parses the guestfish configuration file, usually
2938 ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.
2939 Note that "parse_config" is called very early, before command line
2941 parsing, before the "verbose" flag has been set, even before the global
2942 handle "g" is opened.
2943 File common/options/decrypt.c
2945 This file implements the decryption of disk images, usually done before
2947 mounting their partitions.
2948 Function "common/options/decrypt.c:make_mapname"
2950 static char *
2952 make_mapname (const char *device)
2953 Make a LUKS map name from the partition or logical volume name, eg.
2955 "/dev/vda2" => "cryptvda2", or "/dev/vg-ssd/lv-root7" =>
2956 "cryptvgssdlvroot7". Note that, in logical volume device names,
2957 c_isalnum() eliminates the "/" separator from between the VG and the
2958 LV, so this mapping is not unique; but for our purposes, it will do.
2959 Function "common/options/decrypt.c:inspect_do_decrypt"
2961 void
2963 inspect_do_decrypt (guestfs_h *g, struct key_store *ks)
2964 Simple implementation of decryption: look for any encrypted partitions
2966 and decrypt them, then rescan for VGs.
2967 File common/options/display-options.c
2969 This file contains common code used to implement --short-options and
2971 --long-options in C virt tools. (The equivalent for OCaml virt tools
2972 is implemented by common/mltools/getopt.ml).
2973 These "hidden" options are used to implement bash tab completion.
2975 Function "common/options/display-options.c:display_short_options"
2977 void
2979 display_short_options (const char *format)
2980 Implements the internal "tool --short-options" flag, which just lists
2982 out the short options available. Used by bash completion.
2983 Function "common/options/display-options.c:display_long_options"
2985 void
2987 display_long_options (const struct option *long_options)
2988 Implements the internal "tool --long-options" flag, which just lists
2990 out the long options available. Used by bash completion.
2991 File common/options/domain.c
2993 Implements the guestfish (and other tools) -d option.
2995 Function "common/options/domain.c:add_libvirt_drives"
2997 int
2999 add_libvirt_drives (guestfs_h *g, const char *guest)
3000 This function is called when a user invokes "guestfish -d guest".
3002 Returns the number of drives added ("> 0"), or "-1" for failure.
3004 File common/options/inspect.c
3006 This file implements inspecting the guest and mounting the filesystems
3008 found in the right places. It is used by the guestfish(1) -i option
3009 and some utilities such as virt-cat(1).
3010 Function "common/options/inspect.c:inspect_mount_handle"
3012 void
3014 inspect_mount_handle (guestfs_h *g, struct key_store *ks)
3015 This function implements the -i option.
3017 Function "common/options/inspect.c:print_inspect_prompt"
3019 void
3021 print_inspect_prompt (void)
3022 This function is called only if "inspect_mount_root" was called, and
3024 only after we've printed the prompt in interactive mode.
3025 File common/options/keys.c
3027 Function "common/options/keys.c:read_key"
3029 char *
3031 read_key (const char *param)
3032 Read a passphrase ('Key') from /dev/tty with echo off.
3034 The caller (fish/cmds.c) will call free on the string afterwards.
3036 Based on the code in cryptsetup file lib/utils.c.
3037 File common/options/options.c
3039 This file contains common options parsing code used by guestfish and
3041 many other tools which share a common options syntax.
3042 For example, guestfish, virt-cat, virt-ls etc all support the -a
3044 option, and that is handled in all of those tools using a macro
3045 "OPTION_a" defined in fish/options.h.
3046 There are a lot of common global variables used, "drvs" accumulates the
3048 list of drives, "verbose" for the -v flag, and many more.
3049 Function "common/options/options.c:option_a"
3051 void
3053 option_a (const char *arg, const char *format, int blocksize,
3054 struct drv **drvsp)
3055 Handle the guestfish -a option on the command line.
3057 Function "common/options/options.c:option_d"
3059 void
3061 option_d (const char *arg, struct drv **drvsp)
3062 Handle the -d option when passed on the command line.
3064 Function "common/options/options.c:display_mountpoints_on_failure"
3066 static void
3068 display_mountpoints_on_failure (const char *mp_device,
3069 const char *user_supplied_options)
3070 If the -m option fails on any command, display a useful error message
3072 listing the mountpoints.
3073 File common/options/uri.c
3075 This file implements URI parsing for the -a option, in many utilities
3077 including guestfish(1), virt-cat(1), virt-builder(1),
3078 virt-customize(1), etc.
3079 Subdirectory common/parallel
3081 File common/parallel/domains.c
3082 This file is used by "virt-df" and some of the other tools when they
3084 are implicitly asked to operate over all libvirt domains (VMs), for
3085 example when "virt-df" is called without specifying any particular disk
3086 image.
3087 It hides the complexity of querying the list of domains from libvirt.
3089 Function "common/parallel/domains.c:free_domains"
3091 void
3093 free_domains (void)
3094 Frees up everything allocated by "get_all_libvirt_domains".
3096 Function "common/parallel/domains.c:get_all_libvirt_domains"
3098 void
3100 get_all_libvirt_domains (const char *libvirt_uri)
3101 Read all libguest guests into the global variables "domains" and
3103 "nr_domains". The guests are ordered by name. This exits on any
3104 error.
3105 File common/parallel/estimate-max-threads.c
3107 Function "common/parallel/estimate-max-threads.c:estimate_max_threads"
3109 size_t
3111 estimate_max_threads (void)
3112 This function uses the output of "free -m" to estimate how many
3114 libguestfs appliances could be safely started in parallel. Note that
3115 it always returns ≥ 1.
3116 Function "common/parallel/estimate-max-threads.c:read_line_from"
3118 static char *
3120 read_line_from (const char *cmd)
3121 Run external command and read the first line of output.
3123 File common/parallel/parallel.c
3125 This file is used by "virt-df" and some of the other tools when they
3127 need to run multiple parallel libguestfs instances to operate on a
3128 large number of libvirt domains efficiently.
3129 It implements a multithreaded work queue. In addition it reorders the
3131 output so the output still appears in the same order as the input (ie.
3132 still ordered alphabetically).
3133 Function "common/parallel/parallel.c:start_threads"
3135 int
3137 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
3138 Run the threads and work through the global list of libvirt domains.
3140 "option_P" is whatever the user passed in the -P option, or 0 if the
3142 user didn't use the -P option (in which case the number of threads is
3143 chosen heuristically).
3144 "options_handle" (which may be "NULL") is the global guestfs handle
3146 created by the options mini-library.
3147 The work function ("work") should do the work (inspecting the domain,
3149 etc.) on domain index "i". However it must not print out any result
3150 directly. Instead it prints anything it needs to the supplied "FILE
3151 *". The work function should return 0 on success or "-1" on error.
3152 The "start_threads" function returns 0 if all work items completed
3154 successfully, or "-1" if there was an error.
3155 Subdirectory common/progress
3157 File common/progress/progress.c
3158 This file implements the progress bar in guestfish(1), virt-resize(1)
3160 and virt-sparsify(1).
3161 Function "common/progress/progress.c:progress_bar_init"
3163 struct progress_bar *
3165 progress_bar_init (unsigned flags)
3166 Initialize a progress bar struct.
3168 It is intended that you can reuse the same struct for multiple commands
3170 (but only in a single thread). Call "progress_bar_reset" before each
3171 new command.
3172 Function "common/progress/progress.c:progress_bar_free"
3174 void
3176 progress_bar_free (struct progress_bar *bar)
3177 Free a progress bar struct.
3179 Function "common/progress/progress.c:progress_bar_reset"
3181 void
3183 progress_bar_reset (struct progress_bar *bar)
3184 This function should be called just before you issue any command.
3186 Function "common/progress/progress.c:estimate_remaining_time"
3188 static double
3190 estimate_remaining_time (struct progress_bar *bar, double ratio)
3191 Return remaining time estimate (in seconds) for current call.
3193 This returns the running mean estimate of remaining time, but if the
3195 latest estimate of total time is greater than two s.d.'s from the
3196 running mean then we don't print anything because we're not confident
3197 that the estimate is meaningful. (Returned value is <0.0 when nothing
3198 should be printed).
3199 Function "common/progress/progress.c:progress_bar_set"
3201 void
3203 progress_bar_set (struct progress_bar *bar,
3204 uint64_t position, uint64_t total)
3205 Set the position of the progress bar.
3207 This should be called from a "GUESTFS_EVENT_PROGRESS" event callback.
3209 Subdirectory common/qemuopts
3211 File common/qemuopts/qemuopts-tests.c
3212 Unit tests of internal functions.
3214 These tests may use a libguestfs handle, but must not launch the
3216 handle. Also, avoid long-running tests.
3217 File common/qemuopts/qemuopts.c
3219 Mini-library for writing qemu command lines and qemu config files.
3221 There are some shortcomings with the model used for qemu options which
3223 aren't clear until you try to convert options into a configuration
3224 file. However if we attempted to model the options in more detail then
3225 this library would be both very difficult to use and incompatible with
3226 older versions of qemu. Hopefully the current model is a decent
3227 compromise.
3228 For reference here are the problems:
3230 • There's inconsistency in qemu between options and config file, eg.
3232 "-smp 4" becomes:
3233 [smp-opts]
3235 cpus = "4"
3236 • Similar to the previous point, you can write either "-smp 4" or
3238 "-smp cpus=4" (although this won't work in very old qemu). When
3239 generating a config file you need to know the implicit key name.
3240 • In "-opt key=value,..." the "key" is really a tree/array specifier.
3242 The way this works is complicated but hinted at here:
3243 http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
3244 • Some options are syntactic sugar. eg. "-kernel foo" is sugar for
3246 "-machine kernel=foo".
3247 Function "common/qemuopts/qemuopts.c:qemuopts_create"
3249 struct qemuopts *
3251 qemuopts_create (void)
3252 Create an empty list of qemu options.
3254 The caller must eventually free the list by calling "qemuopts_free".
3256 Returns "NULL" on error, setting "errno".
3258 Function "common/qemuopts/qemuopts.c:qemuopts_free"
3260 void
3262 qemuopts_free (struct qemuopts *qopts)
3263 Free the list of qemu options.
3265 Function "common/qemuopts/qemuopts.c:qemuopts_add_flag"
3267 int
3269 qemuopts_add_flag (struct qemuopts *qopts, const char *flag)
3270 Add a command line flag which has no argument. eg:
3272 qemuopts_add_flag (qopts, "-no-user-config");
3274 Returns 0 on success. Returns "-1" on error, setting "errno".
3276 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg"
3278 int
3280 qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)
3281 Add a command line flag which has a single argument. eg:
3283 qemuopts_add_arg (qopts, "-m", "1024");
3285 Don't use this if the argument is a comma-separated list, since quoting
3287 will not be done properly. See "qemuopts_add_arg_list".
3288 Returns 0 on success. Returns "-1" on error, setting "errno".
3290 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_format"
3292 int
3294 qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
3295 const char *fs, ...)
3296 Add a command line flag which has a single formatted argument. eg:
3298 qemuopts_add_arg_format (qopts, "-m", "%d", 1024);
3300 Don't use this if the argument is a comma-separated list, since quoting
3302 will not be done properly. See "qemuopts_add_arg_list".
3303 Returns 0 on success. Returns "-1" on error, setting "errno".
3305 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote"
3307 int
3309 qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
3310 const char *value)
3311 This is like "qemuopts_add_arg" except that no quoting is done on the
3313 value.
3314 For "qemuopts_to_script" and "qemuopts_to_channel", this means that
3316 neither shell quoting nor qemu comma quoting is done on the value.
3317 For "qemuopts_to_argv" this means that qemu comma quoting is not done.
3319 "qemuopts_to_config*" will fail.
3321 You should use this with great care.
3323 Function "common/qemuopts/qemuopts.c:qemuopts_start_arg_list"
3325 int
3327 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
3328 Start an argument that takes a comma-separated list of fields.
3330 Typical usage is like this (with error handling omitted):
3332 qemuopts_start_arg_list (qopts, "-drive");
3334 qemuopts_append_arg_list (qopts, "file=foo");
3335 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
3336 qemuopts_end_arg_list (qopts);
3337 which would construct "-drive file=foo,if=ide"
3339 See also "qemuopts_add_arg_list" for a way to do simple cases in one
3341 call.
3342 Returns 0 on success. Returns "-1" on error, setting "errno".
3344 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_list"
3346 int
3348 qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
3349 const char *elem0, ...)
3350 Add a command line flag which has a list of arguments. eg:
3352 qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);
3354 This is turned into a comma-separated list, like: "-drive
3356 file=foo,if=ide". Note that this handles qemu quoting properly, so
3357 individual elements may contain commas and this will do the right
3358 thing.
3359 Returns 0 on success. Returns "-1" on error, setting "errno".
3361 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary"
3363 int
3365 qemuopts_set_binary (struct qemuopts *qopts, const char *binary)
3366 Set the qemu binary name.
3368 Returns 0 on success. Returns "-1" on error, setting "errno".
3370 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch"
3372 int
3374 qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)
3375 Set the qemu binary name to "qemu-system-[arch]".
3377 As a special case if "arch" is "NULL", the binary is set to the KVM
3379 binary for the current host architecture:
3380 qemuopts_set_binary_by_arch (qopts, NULL);
3382 Returns 0 on success. Returns "-1" on error, setting "errno".
3384 Function "common/qemuopts/qemuopts.c:qemuopts_to_script"
3386 int
3388 qemuopts_to_script (struct qemuopts *qopts, const char *filename)
3389 Write the qemu options to a script.
3391 "qemuopts_set_binary*" must be called first.
3393 The script file will start with "#!/bin/sh" and will be chmod to mode
3395 0755.
3396 Returns 0 on success. Returns "-1" on error, setting "errno".
3398 Function "common/qemuopts/qemuopts.c:shell_quote"
3400 static void
3402 shell_quote (const char *str, FILE *fp)
3403 Print "str" to "fp", shell-quoting it if necessary.
3405 Function "common/qemuopts/qemuopts.c:shell_and_comma_quote"
3407 static void
3409 shell_and_comma_quote (const char *str, FILE *fp)
3410 Print "str" to "fp" doing both shell and qemu comma quoting.
3412 Function "common/qemuopts/qemuopts.c:qemuopts_to_channel"
3414 int
3416 qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)
3417 Write the qemu options to a "FILE *fp".
3419 "qemuopts_set_binary*" must be called first.
3421 Only the qemu command line is written. The caller may need to add
3423 "#!/bin/sh" and may need to chmod the resulting file to 0755.
3424 Returns 0 on success. Returns "-1" on error, setting "errno".
3426 Function "common/qemuopts/qemuopts.c:qemuopts_to_argv"
3428 char **
3430 qemuopts_to_argv (struct qemuopts *qopts)
3431 Return a NULL-terminated argument list, of the kind that can be passed
3433 directly to execv(3).
3434 "qemuopts_set_binary*" must be called first. It will be returned as
3436 "argv[0]" in the returned list.
3437 The list of strings and the strings themselves must be freed by the
3439 caller.
3440 Returns "NULL" on error, setting "errno".
3442 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_file"
3444 int
3446 qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)
3447 Write the qemu options to a qemu config file, suitable for reading in
3449 using "qemu -readconfig filename".
3450 Note that qemu config files have limitations on content and quoting, so
3452 not all qemuopts structs can be written (this function returns an error
3453 in these cases). For more information see
3454 https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html
3455 https://bugs.launchpad.net/qemu/+bug/1686364
3456 Also, command line argument names and config file sections sometimes
3458 have different names. For example the equivalent of "-m 1024" is:
3459 [memory]
3461 size = "1024"
3462 This code does not attempt to convert between the two forms. You just
3464 need to know how to do that yourself.
3465 Returns 0 on success. Returns "-1" on error, setting "errno".
3467 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_channel"
3469 int
3471 qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)
3472 Same as "qemuopts_to_config_file", but this writes to a "FILE *fp".
3474 Subdirectory common/utils
3476 File common/utils/cleanups.c
3477 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3479 They are implemented using the "__attribute__((cleanup))" feature of
3480 gcc and clang. Typical usage is:
3481 fn ()
3483 {
3484 CLEANUP_FREE char *str = NULL;
3485 str = safe_asprintf (g, "foo");
3486 // str is freed automatically when the function returns
3487 }
3488 There are a few catches to be aware of with the cleanup mechanism:
3490 • If a cleanup variable is not initialized, then you can end up
3492 calling free(3) with an undefined value, resulting in the program
3493 crashing. For this reason, you should usually initialize every
3494 cleanup variable with something, eg. "NULL"
3495 • Don't mark variables holding return values as cleanup variables.
3497 • The "main()" function shouldn't use cleanup variables since it is
3499 normally exited by calling exit(3), and that doesn't call the
3500 cleanup handlers.
3501 The functions in this file are used internally by the "CLEANUP_*"
3503 macros. Don't call them directly.
3504 File common/utils/gnulib-cleanups.c
3506 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3508 They are implemented using the "__attribute__((cleanup))" feature of
3509 gcc and clang. Typical usage is:
3510 fn ()
3512 {
3513 CLEANUP_FREE char *str = NULL;
3514 str = safe_asprintf (g, "foo");
3515 // str is freed automatically when the function returns
3516 }
3517 There are a few catches to be aware of with the cleanup mechanism:
3519 • If a cleanup variable is not initialized, then you can end up
3521 calling free(3) with an undefined value, resulting in the program
3522 crashing. For this reason, you should usually initialize every
3523 cleanup variable with something, eg. "NULL"
3524 • Don't mark variables holding return values as cleanup variables.
3526 • The "main()" function shouldn't use cleanup variables since it is
3528 normally exited by calling exit(3), and that doesn't call the
3529 cleanup handlers.
3530 The functions in this file are used internally by the "CLEANUP_*"
3532 macros. Don't call them directly.
3533 File common/utils/guestfs-utils.h
3535 This header file is included in all "frontend" parts of libguestfs,
3537 namely the library, non-C language bindings, virt tools and tests.
3538 The daemon does not use this header. If you need a place to put
3540 something shared with absolutely everything including the daemon, put
3541 it in lib/guestfs-internal-all.h
3542 If a definition is only needed by a single component of libguestfs (eg.
3544 just the library, or just a single virt tool) then it should not be
3545 here!
3546 File common/utils/libxml2-writer-macros.h
3548 These macros make it easier to write XML. To use them correctly you
3550 must be aware of these assumptions:
3551 • The "xmlTextWriterPtr" is called "xo". It is used implicitly by
3553 all the macros.
3554 • On failure, a function called "xml_error" is called which you must
3556 define (usually as a macro). You must use "CLEANUP_*" macros in
3557 your functions if you want correct cleanup of local variables along
3558 the error path.
3559 • All the "bad" casting is hidden inside the macros.
3561 Definition "common/utils/libxml2-writer-macros.h:start_element"
3563 #define start_element
3565 To define an XML element use:
3567 start_element ("name") {
3569 ...
3570 } end_element ();
3571 which produces "<name>...</name>"
3573 Definition "common/utils/libxml2-writer-macros.h:empty_element"
3575 #define empty_element
3577 To define an empty element:
3579 empty_element ("name");
3581 which produces "<name/>"
3583 Definition "common/utils/libxml2-writer-macros.h:single_element"
3585 #define single_element
3587 To define a single element with no attributes containing some text:
3589 single_element ("name", text);
3591 which produces "<name>text</name>"
3593 Definition "common/utils/libxml2-writer-macros.h:single_element_format"
3595 #define single_element_format
3597 To define a single element with no attributes containing some text
3599 using a format string:
3600 single_element_format ("cores", "%d", nr_cores);
3602 which produces "<cores>4</cores>"
3604 Definition "common/utils/libxml2-writer-macros.h:attribute"
3606 #define attribute
3608 To define an XML element with attributes, use:
3610 start_element ("name") {
3612 attribute ("foo", "bar");
3613 attribute_format ("count", "%d", count);
3614 ...
3615 } end_element ();
3616 which produces "<name foo="bar" count="123">...</name>"
3618 Definition "common/utils/libxml2-writer-macros.h:attribute_ns"
3620 #define attribute_ns
3622 "attribute_ns (prefix, key, namespace_uri, value)" defines a namespaced
3624 attribute.
3625 Definition "common/utils/libxml2-writer-macros.h:string"
3627 #define string
3629 To define a verbatim string, use:
3631 string ("hello");
3633 Definition "common/utils/libxml2-writer-macros.h:string_format"
3635 #define string_format
3637 To define a verbatim string using a format string, use:
3639 string ("%s, world", greeting);
3641 Definition "common/utils/libxml2-writer-macros.h:base64"
3643 #define base64
3645 To write a string encoded as base64:
3647 base64 (data, size);
3649 Definition "common/utils/libxml2-writer-macros.h:comment"
3651 #define comment
3653 To define a comment in the XML, use:
3655 comment ("number of items = %d", nr_items);
3657 File common/utils/stringlists-utils.c
3659 Utility functions used by the library, tools and language bindings.
3661 These functions must not call internal library functions such as
3663 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3664 Function "common/utils/stringlists-utils.c:guestfs_int_split_string"
3666 char **
3668 guestfs_int_split_string (char sep, const char *str)
3669 Split string at separator character "sep", returning the list of
3671 strings. Returns "NULL" on memory allocation failure.
3672 Note (assuming "sep" is ":"):
3674 "str == NULL"
3676 aborts
3677 "str == """
3679 returns "[]"
3680 "str == "abc""
3682 returns "["abc"]"
3683 "str == ":""
3685 returns "["", ""]"
3686 File common/utils/utils.c
3688 Utility functions used by the library, tools and language bindings.
3690 These functions must not call internal library functions such as
3692 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3693 Function "common/utils/utils.c:guestfs_int_replace_string"
3695 char *
3697 guestfs_int_replace_string (const char *str, const char *s1, const char *s2)
3698 Replace every instance of "s1" appearing in "str" with "s2". A newly
3700 allocated string is returned which must be freed by the caller. If
3701 allocation fails this can return "NULL".
3702 For example:
3704 replace_string ("abcabb", "ab", "a");
3706 would return "acab".
3708 Function "common/utils/utils.c:guestfs_int_exit_status_to_string"
3710 char *
3712 guestfs_int_exit_status_to_string (int status, const char *cmd_name,
3713 char *buffer, size_t buflen)
3714 Translate a wait/system exit status into a printable string.
3716 Function "common/utils/utils.c:guestfs_int_random_string"
3718 int
3720 guestfs_int_random_string (char *ret, size_t len)
3721 Return a random string of characters.
3723 Notes:
3725 • The "ret" buffer must have length "len+1" in order to store the
3727 final "\0" character.
3728 • There is about 5 bits of randomness per output character (so about
3730 "5*len" bits of randomness in the resulting string).
3731 Function "common/utils/utils.c:guestfs_int_drive_name"
3733 char *
3735 guestfs_int_drive_name (size_t index, char *ret)
3736 This turns a drive index (eg. 27) into a drive name (eg. "ab").
3738 Drive indexes count from 0. The return buffer has to be large enough
3740 for the resulting string, and the returned pointer points to the *end*
3741 of the string.
3742 https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
3744 Function "common/utils/utils.c:guestfs_int_drive_index"
3746 ssize_t
3748 guestfs_int_drive_index (const char *name)
3749 The opposite of "guestfs_int_drive_name". Take a string like "ab" and
3751 return the index (eg 27).
3752 Note that you must remove any prefix such as "hd", "sd" etc, or any
3754 partition number before calling the function.
3755 Function "common/utils/utils.c:guestfs_int_is_true"
3757 int
3759 guestfs_int_is_true (const char *str)
3760 Similar to "Tcl_GetBoolean".
3762 Function "common/utils/utils.c:guestfs_int_string_is_valid"
3764 bool
3766 guestfs_int_string_is_valid (const char *str,
3767 size_t min_length, size_t max_length,
3768 int flags, const char *extra)
3769 Check a string for validity, that it contains only certain characters,
3771 and minimum and maximum length. This function is usually wrapped in a
3772 VALID_* macro, see lib/drives.c for an example.
3773 "str" is the string to check.
3775 "min_length" and "max_length" are the minimum and maximum length
3777 checks. 0 means no check.
3778 The flags control:
3780 "VALID_FLAG_ALPHA"
3782 7-bit ASCII-only alphabetic characters are permitted.
3783 "VALID_FLAG_DIGIT"
3785 7-bit ASCII-only digits are permitted.
3786 "extra" is a set of extra characters permitted, in addition to
3788 alphabetic and/or digits. ("extra = NULL" for no extra).
3789 Returns boolean "true" if the string is valid (passes all the tests),
3791 or "false" if not.
3792 Function "common/utils/utils.c:guestfs_int_fadvise_normal"
3794 void
3796 guestfs_int_fadvise_normal (int fd)
3797 Hint that we will read or write the file descriptor normally.
3799 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3801 and sets the per-file number of readahead pages to equal the block
3802 device readahead setting.
3803 It's OK to call this on a non-file since we ignore failure as it is
3805 only a hint.
3806 Function "common/utils/utils.c:guestfs_int_fadvise_sequential"
3808 void
3810 guestfs_int_fadvise_sequential (int fd)
3811 Hint that we will read or write the file descriptor sequentially.
3813 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3815 and sets the per-file number of readahead pages to twice the block
3816 device readahead setting.
3817 It's OK to call this on a non-file since we ignore failure as it is
3819 only a hint.
3820 Function "common/utils/utils.c:guestfs_int_fadvise_random"
3822 void
3824 guestfs_int_fadvise_random (int fd)
3825 Hint that we will read or write the file descriptor randomly.
3827 On Linux, this sets the "FMODE_RANDOM" flag on the file. The effect of
3829 this flag is to:
3830 • Disable normal sequential file readahead.
3832 • If any read of the file is done which misses in the page cache, 2MB
3834 are read into the page cache. [I think - I'm not sure I totally
3835 understand what this is doing]
3836 It's OK to call this on a non-file since we ignore failure as it is
3838 only a hint.
3839 Function "common/utils/utils.c:guestfs_int_fadvise_noreuse"
3841 void
3843 guestfs_int_fadvise_noreuse (int fd)
3844 Hint that we will access the data only once.
3846 On Linux, this does nothing.
3848 It's OK to call this on a non-file since we ignore failure as it is
3850 only a hint.
3851 Function "common/utils/utils.c:guestfs_int_fadvise_dontneed"
3853 void
3855 guestfs_int_fadvise_dontneed (int fd)
3856 Hint that we will not access the data in the near future.
3858 On Linux, this immediately writes out any dirty pages in the page cache
3860 and then invalidates (drops) all pages associated with this file from
3861 the page cache. Apparently it does this even if the file is opened or
3862 being used by other processes. This setting is not persistent; if you
3863 subsequently read the file it will be cached in the page cache as
3864 normal.
3865 It's OK to call this on a non-file since we ignore failure as it is
3867 only a hint.
3868 Function "common/utils/utils.c:guestfs_int_fadvise_willneed"
3870 void
3872 guestfs_int_fadvise_willneed (int fd)
3873 Hint that we will access the data in the near future.
3875 On Linux, this immediately reads the whole file into the page cache.
3877 This setting is not persistent; subsequently pages may be dropped from
3878 the page cache as normal.
3879 It's OK to call this on a non-file since we ignore failure as it is
3881 only a hint.
3882 Function "common/utils/utils.c:guestfs_int_shell_unquote"
3884 char *
3886 guestfs_int_shell_unquote (const char *str)
3887 Unquote a shell-quoted string.
3889 Augeas passes strings to us which may be quoted, eg. if they come from
3891 files in /etc/sysconfig. This function can do simple unquoting of
3892 these strings.
3893 Note this function does not do variable substitution, since that is
3895 impossible without knowing the file context and indeed the environment
3896 under which the shell script is run. Configuration files should not
3897 use complex quoting.
3898 "str" is the input string from Augeas, a string that may be single- or
3900 double-quoted or may not be quoted. The returned string is unquoted,
3901 and must be freed by the caller. "NULL" is returned on error and
3902 "errno" is set accordingly.
3903 For information on double-quoting in bash, see
3905 https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html
3906 Function "common/utils/utils.c:guestfs_int_is_reg"
3908 int
3910 guestfs_int_is_reg (int64_t mode)
3911 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3913 field represents a regular file.
3914 Function "common/utils/utils.c:guestfs_int_is_dir"
3916 int
3918 guestfs_int_is_dir (int64_t mode)
3919 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3921 field represents a directory.
3922 Function "common/utils/utils.c:guestfs_int_is_chr"
3924 int
3926 guestfs_int_is_chr (int64_t mode)
3927 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3929 field represents a char device.
3930 Function "common/utils/utils.c:guestfs_int_is_blk"
3932 int
3934 guestfs_int_is_blk (int64_t mode)
3935 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3937 field represents a block device.
3938 Function "common/utils/utils.c:guestfs_int_is_fifo"
3940 int
3942 guestfs_int_is_fifo (int64_t mode)
3943 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3945 field represents a named pipe (FIFO).
3946 Function "common/utils/utils.c:guestfs_int_is_lnk"
3948 int
3950 guestfs_int_is_lnk (int64_t mode)
3951 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3953 field represents a symbolic link.
3954 Function "common/utils/utils.c:guestfs_int_is_sock"
3956 int
3958 guestfs_int_is_sock (int64_t mode)
3959 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3961 field represents a Unix domain socket.
3962 Function "common/utils/utils.c:guestfs_int_full_path"
3964 char *
3966 guestfs_int_full_path (const char *dir, const char *name)
3967 Concatenate "dir" and "name" to create a path. This correctly handles
3969 the case of concatenating "/" + "filename" as well as "/dir" +
3970 "filename". "name" may be "NULL".
3971 The caller must free the returned path.
3973 This function sets "errno" and returns "NULL" on error.
3975 Function "common/utils/utils.c:guestfs_int_hexdump"
3977 void
3979 guestfs_int_hexdump (const void *data, size_t len, FILE *fp)
3980 Hexdump a block of memory to "FILE *", used for debugging.
3982 Function "common/utils/utils.c:guestfs_int_strerror"
3984 const char *
3986 guestfs_int_strerror (int errnum, char *buf, size_t buflen)
3987 Thread-safe strerror_r.
3989 This is a wrapper around the two variants of strerror_r(3) in glibc
3991 since it is hard to use correctly (RHBZ#2030396).
3992 The buffer passed in should be large enough to store the error message
3994 (256 chars at least) and should be non-static. Note that the buffer
3995 might not be used, use the return value.
3996 Subdirectory common/visit
3998 File common/visit/visit.c
3999 This file contains a recursive function for visiting all files and
4001 directories in a guestfs filesystem.
4002 Adapted from
4004 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/
4005 Function "common/visit/visit.c:visit"
4007 int
4009 visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)
4010 Visit every file and directory in a guestfs filesystem, starting at
4012 "dir".
4013 "dir" may be "/" to visit the entire filesystem, or may be some
4015 subdirectory. Symbolic links are not followed.
4016 The visitor function "f" is called once for every directory and every
4018 file. The parameters passed to "f" include the current directory name,
4019 the current file name (or "NULL" when we're visiting a directory), the
4020 "guestfs_statns" (file permissions etc), and the list of extended
4021 attributes of the file. The visitor function may return "-1" which
4022 causes the whole recursion to stop with an error.
4023 Also passed to this function is an "opaque" pointer which is passed
4025 through to the visitor function.
4026 Returns 0 if everything went OK, or "-1" if there was an error. Error
4028 handling is not particularly well defined. It will either set an error
4029 in the libguestfs handle or print an error on stderr, but there is no
4030 way for the caller to tell the difference.
4031 Subdirectory common/windows
4033 File common/windows/windows.c
4034 This file implements "win:" Windows file path support in guestfish(1).
4036 Function "common/windows/windows.c:is_windows"
4038 int
4040 is_windows (guestfs_h *g, const char *root)
4041 Checks whether "root" is a Windows installation.
4043 This relies on an already being done introspection.
4045 Function "common/windows/windows.c:windows_path"
4047 char *
4049 windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
4050 Resolves "path" as possible Windows path according to "root", giving a
4052 new path that can be used in libguestfs API calls.
4053 Notes:
4055 • "root" must be a Windows installation
4057 • relies on an already being done introspection
4059 • will unmount all the existing mount points and mount the Windows
4061 root (according to "readonly")
4062 • calls exit(3) on memory allocation failures
4064 Subdirectory daemon
4066 File daemon/command.c
4067 This file contains a number of useful functions for running external
4069 commands and capturing their output.
4070 Function "daemon/command.c:commandf"
4072 int
4074 commandf (char **stdoutput, char **stderror, unsigned flags,
4075 const char *name, ...)
4076 Run a command. Optionally capture stdout and stderr as strings.
4078 Returns 0 if the command ran successfully, or "-1" if there was any
4080 error.
4081 For a description of the "flags" see "commandrvf".
4083 There is also a macro "command(out,err,name,...)" which calls
4085 "commandf" with "flags=0".
4086 Function "daemon/command.c:commandrf"
4088 int
4090 commandrf (char **stdoutput, char **stderror, unsigned flags,
4091 const char *name, ...)
4092 Same as "command", but we allow the status code from the subcommand to
4094 be non-zero, and return that status code.
4095 We still return "-1" if there was some other error.
4097 There is also a macro "commandr(out,err,name,...)" which calls
4099 "commandrf" with "flags=0".
4100 Function "daemon/command.c:commandvf"
4102 int
4104 commandvf (char **stdoutput, char **stderror, unsigned flags,
4105 char const *const *argv)
4106 Same as "command", but passing in an argv array.
4108 There is also a macro "commandv(out,err,argv)" which calls "commandvf"
4110 with "flags=0".
4111 Function "daemon/command.c:commandrvf"
4113 int
4115 commandrvf (char **stdoutput, char **stderror, unsigned flags,
4116 char const* const *argv)
4117 This is a more sane version of system(3) for running external commands.
4119 It uses fork/execvp, so we don't need to worry about quoting of
4120 parameters, and it allows us to capture any error messages in a buffer.
4121 If "stdoutput" is not "NULL", then *stdoutput will return the stdout of
4123 the command as a string.
4124 If "stderror" is not "NULL", then *stderror will return the stderr of
4126 the command. If there is a final \n character, it is removed so you
4127 can use the error string directly in a call to "reply_with_error".
4128 Flags are:
4130 "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR"
4132 For broken external commands that send error messages to stdout
4133 (hello, parted) but that don't have any useful stdout information,
4134 use this flag to capture the error messages in the *stderror
4135 buffer. If using this flag, you should pass "stdoutput=NULL"
4136 because nothing could ever be captured in that buffer.
4137 "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN"
4139 For running external commands on chrooted files correctly (see
4140 https://bugzilla.redhat.com/579608) specifying this flag causes
4141 another process to be forked which chroots into sysroot and just
4142 copies the input file to stdin of the specified command. The file
4143 descriptor is ORed with the flags, and that file descriptor is
4144 always closed by this function. See daemon/hexdump.c for an
4145 example of usage.
4146 There is also a macro "commandrv(out,err,argv)" which calls
4148 "commandrvf" with "flags=0".
4149 File daemon/device-name-translation.c
4151 Function
4153 "daemon/device-name-translation.c:device_name_translation_init"
4154 void
4156 device_name_translation_init (void)
4157 Cache daemon disk mapping.
4159 When the daemon starts up, populate a cache with the contents of
4161 /dev/disk/by-path. It's easiest to use "ls -lv" here since the names
4162 are sorted awkwardly.
4163 Function "daemon/device-name-translation.c:device_name_translation"
4165 char *
4167 device_name_translation (const char *device)
4168 Perform device name translation.
4170 Libguestfs defines a few standard formats for device names. (see also
4172 "BLOCK DEVICE NAMING" in guestfs(3) and "guestfs_canonical_device_name"
4173 in guestfs(3)). They are:
4174 /dev/sdX[N]
4176 /dev/hdX[N]
4177 /dev/vdX[N]
4178 These mean the Nth partition on the Xth device. Because Linux no
4179 longer enumerates devices in the order they are passed to qemu, we
4180 must translate these by looking up the actual device using
4181 /dev/disk/by-path/
4182 /dev/mdX
4184 /dev/VG/LV
4185 /dev/mapper/...
4186 /dev/dm-N
4187 These are not translated here.
4188 It returns a newly allocated string which the caller must free.
4190 It returns "NULL" on error. Note it does not call "reply_with_*".
4192 We have to open the device and test for "ENXIO", because the device
4194 nodes may exist in the appliance.
4195 File daemon/guestfsd.c
4197 This is the guestfs daemon which runs inside the guestfs appliance.
4199 This file handles start up and connecting back to the library.
4200 Function "daemon/guestfsd.c:shell_quote"
4202 void
4204 shell_quote (const char *str, FILE *fp)
4205 Write "str" to the file "fp", ensuring it is shell quoted.
4207 Function "daemon/guestfsd.c:sysroot_shell_quote"
4209 void
4211 sysroot_shell_quote (const char *path, FILE *fp)
4212 Write "sysroot" + "path" to the file "fp", ensuring it is shell quoted.
4214 The path must be an absolute path.
4215 File daemon/internal.c
4217 Internal functions that are not part of the public API.
4219 File daemon/utils-c.c
4221 Bindings for utility functions.
4223 Note that functions called from OCaml code must never call any of the
4225 "reply*" functions.
4226 File daemon/utils.c
4228 Miscellaneous utility functions used by the daemon.
4230 Function "daemon/utils.c:is_root_device_stat"
4232 static int
4234 is_root_device_stat (struct stat *statbuf)
4235 Return true iff device is the root device (and therefore should be
4237 ignored from the point of view of user calls).
4238 Function "daemon/utils.c:is_device_parameter"
4240 int
4242 is_device_parameter (const char *device)
4243 Parameters marked as "Device", "Dev_or_Path", etc can be passed a block
4245 device name. This function tests if the parameter is a block device
4246 name.
4247 It can also be used in daemon code to test if the string passed as a
4249 "Dev_or_Path" parameter is a device or path.
4250 Function "daemon/utils.c:sysroot_path"
4252 char *
4254 sysroot_path (const char *path)
4255 Turn "/path" into "/sysroot/path".
4257 Returns "NULL" on failure. The caller must check for this and call
4259 "reply_with_perror ("malloc")". The caller must also free the returned
4260 string.
4261 See also the custom %R printf formatter which does shell quoting too.
4263 Function "daemon/utils.c:sysroot_realpath"
4265 char *
4267 sysroot_realpath (const char *path)
4268 Resolve path within sysroot, calling "sysroot_path" on the resolved
4270 path.
4271 Returns "NULL" on failure. The caller must check for this and call
4273 "reply_with_perror ("malloc")". The caller must also free the returned
4274 string.
4275 See also the custom %R printf formatter which does shell quoting too.
4277 Function "daemon/utils.c:is_power_of_2"
4279 int
4281 is_power_of_2 (unsigned long v)
4282 Returns true if "v" is a power of 2.
4284 Uses the algorithm described at
4286 http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2
4287 Function "daemon/utils.c:split_lines_sb"
4289 struct stringsbuf
4291 split_lines_sb (char *str)
4292 Split an output string into a NULL-terminated list of lines, wrapped
4294 into a stringsbuf.
4295 Typically this is used where we have run an external command which has
4297 printed out a list of things, and we want to return an actual list.
4298 The corner cases here are quite tricky. Note in particular:
4300 "" returns "[]"
4302 "\n"
4304 returns "[""]"
4305 "a\nb"
4307 returns "["a"; "b"]"
4308 "a\nb\n"
4310 returns "["a"; "b"]"
4311 "a\nb\n\n"
4313 returns "["a"; "b"; ""]"
4314 The original string is written over and destroyed by this function
4316 (which is usually OK because it's the 'out' string from "command*()").
4317 You can free the original string, because "add_string()" strdups the
4318 strings.
4319 "argv" in the "struct stringsbuf" will be "NULL" in case of errors.
4321 Function "daemon/utils.c:filter_list"
4323 char **
4325 filter_list (bool (*p) (const char *str), char **strs)
4326 Filter a list of strings. Returns a newly allocated list of only the
4328 strings where "p (str) == true".
4329 Note it does not copy the strings, be careful not to double-free them.
4331 Function "daemon/utils.c:trim"
4333 void
4335 trim (char *str)
4336 Skip leading and trailing whitespace, updating the original string in-
4338 place.
4339 Function "daemon/utils.c:parse_btrfsvol"
4341 int
4343 parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
4344 Parse the mountable descriptor for a btrfs subvolume. Don't call this
4346 directly; it is only used from the stubs.
4347 A btrfs subvolume is given as:
4349 btrfsvol:/dev/sda3/root
4351 where /dev/sda3 is a block device containing a btrfs filesystem, and
4353 root is the name of a subvolume on it. This function is passed the
4354 string following "btrfsvol:".
4355 On success, "mountable->device" and "mountable->volume" must be freed
4357 by the caller.
4358 Function "daemon/utils.c:mountable_to_string"
4360 char *
4362 mountable_to_string (const mountable_t *mountable)
4363 Convert a "mountable_t" back to its string representation
4365 This function can be used in an error path, so must not call
4367 "reply_with_error".
4368 Function "daemon/utils.c:prog_exists"
4370 int
4372 prog_exists (const char *prog)
4373 Check program exists and is executable on $PATH.
4375 Function "daemon/utils.c:random_name"
4377 int
4379 random_name (char *template)
4380 Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
4382 template to contain a randomly named file. Any 'X' characters after
4383 the final '/' in the template are replaced with random characters.
4384 Notes: You should probably use an 8.3 path, so it's compatible with all
4386 filesystems including basic FAT. Also this only substitutes lowercase
4387 ASCII letters and numbers, again for compatibility with lowest common
4388 denominator filesystems.
4389 This doesn't create a file or check whether or not the file exists (it
4391 would be extremely unlikely to exist as long as the RNG is working).
4392 If there is an error, "-1" is returned.
4394 Function "daemon/utils.c:udev_settle_file"
4396 void
4398 udev_settle_file (const char *file)
4399 LVM and other commands aren't synchronous, especially when udev is
4401 involved. eg. You can create or remove some device, but the "/dev"
4402 device node won't appear until some time later. This means that you
4403 get an error if you run one command followed by another.
4404 Use "udevadm settle" after certain commands, but don't be too fussed if
4406 it fails.
4407 Function "daemon/utils.c:make_exclude_from_file"
4409 char *
4411 make_exclude_from_file (const char *function, char *const *excludes)
4412 Turn list "excludes" into a temporary file, and return a string
4414 containing the temporary file name. Caller must unlink the file and
4415 free the string.
4416 "function" is the function that invoked this helper, and it is used
4418 mainly for errors/debugging.
4419 Function "daemon/utils.c:read_whole_file"
4421 char *
4423 read_whole_file (const char *filename, size_t *size_r)
4424 Read whole file into dynamically allocated array. If there is an
4426 error, DON'T call reply_with_perror, just return NULL. Returns a
4427 "\0"-terminated string. "size_r" can be specified to get the size of
4428 the returned data.
4429 File daemon/xattr.c
4431 Function "daemon/xattr.c:split_attr_names"
4433 static char **
4435 split_attr_names (char *buf, size_t len)
4436 listxattr(2) returns the string "foo\0bar\0baz" of length "len". (The
4438 last string in the list is \0-terminated but the \0 is not included in
4439 "len").
4440 This function splits it into a regular list of strings.
4442 Note that the returned list contains pointers to the original strings
4444 in "buf" so be careful that you do not double-free them.
4445 Subdirectory fish
4447 File fish/alloc.c
4448 This file implements the guestfish "alloc" and "sparse" commands.
4450 Function "fish/alloc.c:alloc_disk"
4452 int
4454 alloc_disk (const char *filename, const char *size_str, int add, int sparse)
4455 This is the underlying allocation function. It's called from a few
4457 other places in guestfish.
4458 File fish/copy.c
4460 This file implements the guestfish commands "copy-in" and "copy-out".
4462 File fish/destpaths.c
4464 The file handles tab-completion of filesystem paths in guestfish.
4466 File fish/display.c
4468 The file implements the guestfish "display" command, for displaying
4470 graphical files (icons, images) in disk images.
4471 File fish/echo.c
4473 The file implements the guestfish "echo" command.
4475 File fish/edit.c
4477 guestfish "edit" command, suggested by Ján Ondrej.
4479 File fish/events.c
4481 This file implements the guestfish event-related commands, "event",
4483 "delete-event" and "list-events".
4484 File fish/fish.c
4486 guestfish, the guest filesystem shell. This file contains the main
4488 loop and utilities.
4489 Function "fish/fish.c:parse_command_line"
4491 static struct parsed_command
4493 parse_command_line (char *buf, int *exit_on_error_rtn)
4494 Parse a command string, splitting at whitespace, handling '!', '#' etc.
4496 This destructively updates "buf".
4497 "exit_on_error_rtn" is used to pass in the global "exit_on_error"
4499 setting and to return the local setting (eg. if the command begins with
4500 '-').
4501 Returns in "parsed_command.status":
4503 1 got a guestfish command (returned in
4505 "cmd_rtn"/"argv_rtn"/"pipe_rtn")
4506 0 no guestfish command, but otherwise OK
4508 "-1"
4510 an error
4511 Function "fish/fish.c:parse_quoted_string"
4513 static ssize_t
4515 parse_quoted_string (char *p)
4516 Parse double-quoted strings, replacing backslash escape sequences with
4518 the true character. Since the string is returned in place, the escapes
4519 must make the string shorter.
4520 Function "fish/fish.c:execute_and_inline"
4522 static int
4524 execute_and_inline (const char *cmd, int global_exit_on_error)
4525 Used to handle "<!" (execute command and inline result).
4527 Function "fish/fish.c:issue_command"
4529 int
4531 issue_command (const char *cmd, char *argv[], const char *pipecmd,
4532 int rc_exit_on_error_flag)
4533 Run a command.
4535 "rc_exit_on_error_flag" is the "exit_on_error" flag that we pass to the
4537 remote server (when issuing --remote commands). It does not cause
4538 "issue_command" itself to exit on error.
4539 Function "fish/fish.c:extended_help_message"
4541 void
4543 extended_help_message (void)
4544 Print an extended help message when the user types in an unknown
4546 command for the first command issued. A common case is the user doing:
4547 guestfish disk.img
4549 expecting guestfish to open disk.img (in fact, this tried to run a non-
4551 existent command "disk.img").
4552 Function "fish/fish.c:error_cb"
4554 static void
4556 error_cb (guestfs_h *g, void *data, const char *msg)
4557 Error callback. This replaces the standard libguestfs error handler.
4559 Function "fish/fish.c:free_n_strings"
4561 static void
4563 free_n_strings (char **str, size_t len)
4564 Free strings from a non-NULL terminated "char**".
4566 Function "fish/fish.c:decode_ps1"
4568 static char *
4570 decode_ps1 (const char *str)
4571 Decode "str" into the final printable prompt string.
4573 Function "fish/fish.c:win_prefix"
4575 char *
4577 win_prefix (const char *path)
4578 Resolve the special "win:..." form for Windows-specific paths. The
4580 generated code calls this for all device or path arguments.
4581 The function returns a newly allocated string, and the caller must free
4583 this string; else display an error and return "NULL".
4584 Function "fish/fish.c:file_in"
4586 char *
4588 file_in (const char *arg)
4589 Resolve the special "FileIn" paths ("-" or "-<<END" or filename).
4591 The caller (fish/cmds.c) will call "free_file_in" after the command has
4593 run which should clean up resources.
4594 Function "fish/fish.c:file_out"
4596 char *
4598 file_out (const char *arg)
4599 Resolve the special "FileOut" paths ("-" or filename).
4601 The caller (fish/cmds.c) will call "free (str)" after the command has
4603 run.
4604 Function "fish/fish.c:progress_callback"
4606 void
4608 progress_callback (guestfs_h *g, void *data,
4609 uint64_t event, int event_handle, int flags,
4610 const char *buf, size_t buf_len,
4611 const uint64_t *array, size_t array_len)
4612 Callback which displays a progress bar.
4614 File fish/glob.c
4616 This file implements the guestfish "glob" command.
4618 Function "fish/glob.c:expand_devicename"
4620 static char **
4622 expand_devicename (guestfs_h *g, const char *device)
4623 Glob-expand device patterns, such as "/dev/sd*"
4625 (https://bugzilla.redhat.com/635971).
4626 There is no "guestfs_glob_expand_device" function because the
4628 equivalent can be implemented using functions like
4629 "guestfs_list_devices".
4630 It's not immediately clear what it means to expand a pattern like
4632 "/dev/sd*". Should that include device name translation? Should the
4633 result include partitions as well as devices?
4634 Should "/dev/" + "*" return every possible device and filesystem? How
4636 about VGs? LVs?
4637 To solve this what we do is build up a list of every device, partition,
4639 etc., then glob against that list.
4640 Notes for future work (XXX):
4642 • This doesn't handle device name translation. It wouldn't be too
4644 hard to add.
4645 • Could have an API function for returning all device-like things.
4647 Function "fish/glob.c:add_strings_matching"
4649 static int
4651 add_strings_matching (char **pp, const char *glob,
4652 char ***ret, size_t *size_r)
4653 Using POSIX fnmatch(3), find strings in the list "pp" which match
4655 pattern "glob". Add strings which match to the "ret" array. *size_r
4656 is the current size of the "ret" array, which is updated with the new
4657 size.
4658 Function "fish/glob.c:single_element_list"
4660 static char **
4662 single_element_list (const char *element)
4663 Return a single element list containing "element".
4665 File fish/help.c
4667 The file implements the guestfish "help" command.
4669 Function "fish/help.c:display_help"
4671 int
4673 display_help (const char *cmd, size_t argc, char *argv[])
4674 The "help" command.
4676 This used to just list all commands, but that's not very useful.
4678 Instead display some useful context-sensitive help. This could be
4679 improved if we knew how many drives had been added already, and whether
4680 anything was mounted.
4681 File fish/hexedit.c
4683 This file implements the guestfish "hexedit" command.
4685 File fish/lcd.c
4687 Function "fish/lcd.c:run_lcd"
4689 int
4691 run_lcd (const char *cmd, size_t argc, char *argv[])
4692 guestfish "lcd" command (similar to the "lcd" command in BSD ftp).
4694 File fish/man.c
4696 Function "fish/man.c:run_man"
4698 int
4700 run_man (const char *cmd, size_t argc, char *argv[])
4701 guestfish "man" command
4703 File fish/more.c
4705 This file implements the guestfish "more" command.
4707 File fish/prep.c
4709 This file implements the guestfish -N option for creating pre-prepared
4711 disk layouts.
4712 File fish/rc.c
4714 This file implements guestfish remote (command) support.
4716 Function "fish/rc.c:rc_listen"
4718 void
4720 rc_listen (void)
4721 The remote control server (ie. "guestfish --listen").
4723 Function "fish/rc.c:rc_remote"
4725 int
4727 rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
4728 int exit_on_error)
4729 The remote control client (ie. "guestfish --remote").
4731 File fish/reopen.c
4733 This file implements the guestfish "reopen" command.
4735 File fish/setenv.c
4737 This file implements the guestfish "setenv" and "unsetenv" commands.
4739 File fish/supported.c
4741 This file implements the guestfish "supported" command.
4743 File fish/tilde.c
4745 This file implements tilde ("~") expansion of home directories in
4747 guestfish(1).
4748 Function "fish/tilde.c:try_tilde_expansion"
4750 char *
4752 try_tilde_expansion (char *str)
4753 This is called from the script loop if we find a candidate for
4755 "~username" (tilde-expansion).
4756 Function "fish/tilde.c:expand_home"
4758 static char *
4760 expand_home (char *orig, const char *append)
4761 Return $HOME + append string.
4763 Function "fish/tilde.c:find_home_for_username"
4765 static const char *
4767 find_home_for_username (const char *username, size_t ulen)
4768 Lookup "username" (of length "ulen"), return home directory if found,
4770 or "NULL" if not found.
4771 File fish/time.c
4773 This file implements the guestfish "time" command.
4775 Subdirectory python
4777 File python/handle.c
4778 This file contains a small number of functions that are written by
4780 hand. The majority of the bindings are generated (see
4781 python/actions-*.c).
4782
4784 guestfs(3), guestfs-building(1), guestfs-examples(3),
4785 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
4786 guestfs-testing(1), libguestfs-test-tool(1),
4787 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
4788
4790 Richard W.M. Jones ("rjones at redhat dot com")
4791
4793 Copyright (C) 2009-2020 Red Hat Inc.
4794
4796 This library is free software; you can redistribute it and/or modify it
4797 under the terms of the GNU Lesser General Public License as published
4798 by the Free Software Foundation; either version 2 of the License, or
4799 (at your option) any later version.
4800 This library is distributed in the hope that it will be useful, but
4802 WITHOUT ANY WARRANTY; without even the implied warranty of
4803 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4804 Lesser General Public License for more details.
4805 You should have received a copy of the GNU Lesser General Public
4807 License along with this library; if not, write to the Free Software
4808 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
4809 02110-1301 USA
4810
4812 To get a list of bugs against libguestfs, use this link:
4813 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
4814 To report a new bug against libguestfs, use this link:
4816 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
4817 When reporting a bug, please supply:
4819 • The version of libguestfs.
4821 • Where you got libguestfs (eg. which Linux distro, compiled from
4823 source, etc)
4824 • Describe the bug accurately and give a way to reproduce it.
4826 • Run libguestfs-test-tool(1) and paste the complete, unedited output
4828 into the bug report.
4829libguestfs-1.49.9 2023-01-19 guestfs-hacking(1)