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 bundled
68 Embedded copies of other libraries, mostly for convenience (and the
69 embedded library is not widespread enough).
70 bundled/ocaml-augeas
72 Bindings for the Augeas library. These come from the ocaml-
73 augeas library http://git.annexia.org/?p=ocaml-augeas.git
74 cat The virt-cat(1), virt-filesystems(1), virt-log(1), virt-ls(1) and
76 virt-tail(1) commands and documentation.
77 common
79 Various libraries of internal code can be found in the common
80 subdirectory:
81 common/edit
83 Common code for interactively and non-interactively editing
84 files within a libguestfs filesystem.
85 common/errnostring
87 The communication protocol used between the library and the
88 daemon running inside the appliance has to encode errnos as
89 strings, which is handled by this library.
90 common/mlcustomize
92 Library code associated with "virt-customize" but also used in
93 other tools.
94 common/mlgettext
96 Small, generated wrapper which allows libguestfs to be compiled
97 with or without ocaml-gettext. This is generated by
98 ./configure.
99 common/mlpcre
101 Lightweight OCaml bindings for Perl Compatible Regular
102 Expressions (PCRE). Note this is not related in any way to
103 Markus Mottl's ocaml-pcre library.
104 common/mlprogress
106 OCaml bindings for the progress bar functions (see
107 common/progress).
108 common/mlstdutils
110 A library of pure OCaml utility functions used in many places.
111 common/mltools
113 OCaml utility functions only used by the OCaml virt tools (like
114 "virt-sysprep", "virt-customize" etc.)
115 common/mlutils
117 OCaml bindings for C functions in "common/utils", and some
118 POSIX bindings which are missing from the OCaml stdlib.
119 common/mlvisit
121 OCaml bindings for the visit functions (see common/visit).
122 common/mlxml
124 OCaml bindings for the libxml2 library.
125 common/options
127 Common options parsing for guestfish, guestmount and some virt
128 tools.
129 common/parallel
131 A framework used for processing multiple libvirt domains in
132 parallel.
133 common/progress
135 Common code for printing progress bars.
136 common/protocol
138 The XDR-based communication protocol used between the library
139 and the daemon running inside the appliance is defined here.
140 common/qemuopts
142 Mini-library for writing qemu command lines and qemu config
143 files.
144 common/structs
146 Common code for printing and freeing libguestfs structs, used
147 by the library and some tools.
148 common/utils
150 Various utility functions used throughout the library and
151 tools.
152 common/visit
154 Recursively visit a guestfs filesystem hierarchy.
155 common/windows
157 Utility functions for handling Windows drive letters.
158 contrib
160 Outside contributions, experimental parts.
161 customize
163 virt-customize(1) command and documentation.
164 daemon
166 The daemon that runs inside the libguestfs appliance and carries
167 out actions.
168 df virt-df(1) command and documentation.
170 dib virt-dib(1) command and documentation.
172 diff
174 virt-diff(1) command and documentation.
175 docs
177 Miscellaneous manual pages.
178 edit
180 virt-edit(1) command and documentation.
181 examples
183 C API example code.
184 fish
186 guestfish(1), the command-line shell, and various shell scripts
187 built on top such as virt-copy-in(1), virt-copy-out(1),
188 virt-tar-in(1), virt-tar-out(1).
189 format
191 virt-format(1) command and documentation.
192 fuse
194 guestmount(1), FUSE (userspace filesystem) built on top of
195 libguestfs.
196 generator
198 The crucially important generator, used to automatically generate
199 large amounts of boilerplate C code for things like RPC and
200 bindings.
201 get-kernel
203 virt-get-kernel(1) command and documentation.
204 inspector
206 virt-inspector(1), the virtual machine image inspector.
207 lib Source code to the C library.
209 logo
211 Logo used on the website. The fish is called Arthur by the way.
212 m4 M4 macros used by autoconf. See "THE BUILD SYSTEM".
214 make-fs
216 virt-make-fs(1) command and documentation.
217 po Translations of simple gettext strings.
219 po-docs
221 The build infrastructure and PO files for translations of manpages
222 and POD files. Eventually this will be combined with the po
223 directory, but that is rather complicated.
224 rescue
226 virt-rescue(1) command and documentation.
227 resize
229 virt-resize(1) command and documentation.
230 sparsify
232 virt-sparsify(1) command and documentation.
233 sysprep
235 virt-sysprep(1) command and documentation.
236 tests
238 Tests.
239 test-data
241 Files and other test data used by the tests.
242 test-tool
244 Test tool for end users to test if their qemu/kernel combination
245 will work with libguestfs.
246 tmp Used for temporary files when running the tests (instead of /tmp
248 etc). The reason is so that you can run multiple parallel tests of
249 libguestfs without having one set of tests overwriting the
250 appliance created by another.
251 tools
253 Command line tools written in Perl (virt-win-reg(1) and many
254 others).
255 utils
257 Miscellaneous utilities, such as "boot-benchmark".
258 v2v Up to libguestfs > 1.42 this contained the virt-v2v(1) tool, but
260 this has now moved into a separate repository:
261 https://github.com/libguestfs/virt-v2v
262 website
264 The http://libguestfs.org website files.
265 csharp
267 erlang
268 gobject
269 golang
270 haskell
271 java
272 lua
273 ocaml
274 php
275 perl
276 python
277 ruby
278 Language bindings.
279 THE BUILD SYSTEM
281 Libguestfs uses the GNU autotools build system (autoconf, automake,
282 libtool).
283 The ./configure script is generated from configure.ac and
285 m4/guestfs-*.m4. Most of the configure script is split over many m4
286 macro files by topic, for example m4/guestfs-daemon.m4 deals with the
287 dependencies of the daemon.
288 The job of the top level Makefile.am is mainly to list the
290 subdirectories ("SUBDIRS") in the order they should be compiled.
291 common-rules.mk is included in every Makefile.am (top level and
293 subdirectories). subdir-rules.mk is included only in subdirectory
294 Makefile.am files.
295 There are many make targets. Use this command to list them all:
297 make help
299
301 ADDING A NEW API
302 Because large amounts of boilerplate code in libguestfs are generated,
303 this makes it easy to extend the libguestfs API.
304 To add a new API action there are two changes:
306 1. You need to add a description of the call (name, parameters, return
308 type, tests, documentation) to generator/actions_*.ml and possibly
309 generator/proc_nr.ml.
310 There are two sorts of API action, depending on whether the call
312 goes through to the daemon in the appliance, or is serviced
313 entirely by the library (see "ARCHITECTURE" in
314 guestfs-internals(1)). "guestfs_sync" in guestfs(3) is an example
315 of the former, since the sync is done in the appliance.
316 "guestfs_set_trace" in guestfs(3) is an example of the latter,
317 since a trace flag is maintained in the handle and all tracing is
318 done on the library side.
319 Most new actions are of the first type, and get added to the
321 "daemon_functions" list. Each function has a unique procedure
322 number used in the RPC protocol which is assigned to that action
323 when we publish libguestfs and cannot be reused. Take the latest
324 procedure number and increment it.
325 For library-only actions of the second type, add to the
327 "non_daemon_functions" list. Since these functions are serviced by
328 the library and do not travel over the RPC mechanism to the daemon,
329 these functions do not need a procedure number, and so the
330 procedure number is set to "-1".
331 2. Implement the action (in C):
333 For daemon actions, implement the function "do_<name>" in the
335 "daemon/" directory.
336 For library actions, implement the function "guestfs_impl_<name>"
338 in the "lib/" directory.
339 In either case, use another function as an example of what to do.
341 3. As an alternative to step 2: Since libguestfs 1.38, daemon actions
343 can be implemented in OCaml. You have to set the "impl = OCaml
344 ..." flag in the generator. Take a look at daemon/file.ml for an
345 example.
346 After making these changes, use "make" to compile.
348 Note that you don’t need to implement the RPC, language bindings,
350 manual pages or anything else. It’s all automatically generated from
351 the OCaml description.
352 Adding tests for an API
354 You can supply zero or as many tests as you want per API call. The
356 tests can either be added as part of the API description
357 (generator/actions_*.ml), or in some rarer cases you may want to drop a
358 script into "tests/*/". Note that adding a script to "tests/*/" is
359 slower, so if possible use the first method.
360 The following describes the test environment used when you add an API
362 test in actions_*.ml.
363 The test environment has 4 block devices:
365 /dev/sda 2 GB
367 General block device for testing.
368 /dev/sdb 2 GB
370 /dev/sdb1 is an ext2 filesystem used for testing filesystem write
371 operations.
372 /dev/sdc 10 MB
374 Used in a few tests where two block devices are needed.
375 /dev/sdd
377 ISO with fixed content (see images/test.iso).
378 To be able to run the tests in a reasonable amount of time, the
380 libguestfs appliance and block devices are reused between tests. So
381 don't try testing "guestfs_kill_subprocess" in guestfs(3) :-x
382 Each test starts with an initial scenario, selected using one of the
384 "Init*" expressions, described in generator/types.ml. These initialize
385 the disks mentioned above in a particular way as documented in
386 types.ml. You should not assume anything about the previous contents
387 of other disks that are not initialized.
388 You can add a prerequisite clause to any individual test. This is a
390 run-time check, which, if it fails, causes the test to be skipped.
391 Useful if testing a command which might not work on all variations of
392 libguestfs builds. A test that has prerequisite of "Always" means to
393 run unconditionally.
394 In addition, packagers can skip individual tests by setting environment
396 variables before running "make check".
397 SKIP_TEST_<CMD>_<NUM>=1
399 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command" in
401 guestfs(3).
402 or:
404 SKIP_TEST_<CMD>=1
406 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" in guestfs(3)
408 tests.
409 Packagers can run only certain tests by setting for example:
411 TEST_ONLY="vfs_type zerofree"
413 See tests/c-api/tests.c for more details of how these environment
415 variables work.
416 Debugging new APIs
418 Test new actions work before submitting them.
420 You can use guestfish to try out new commands.
422 Debugging the daemon is a problem because it runs inside a minimal
424 environment. However you can fprintf messages in the daemon to stderr,
425 and they will show up if you use "guestfish -v".
426 ADDING A NEW LANGUAGE BINDING
428 All language bindings must be generated by the generator (see the
429 generator subdirectory).
430 There is no documentation for this yet. We suggest you look at an
432 existing binding, eg. generator/ocaml.ml or generator/perl.ml.
433 Adding tests for language bindings
435 Language bindings should come with tests. Previously testing of
437 language bindings was rather ad-hoc, but we have been trying to
438 formalize the set of tests that every language binding should use.
439 Currently only the OCaml and Perl bindings actually implement the full
441 set of tests, and the OCaml bindings are canonical, so you should
442 emulate what the OCaml tests do.
443 This is the numbering scheme used by the tests:
445 - 000+ basic tests:
447 010 load the library
449 020 create
450 030 create-flags
451 040 create multiple handles
452 050 test setting and getting config properties
453 060 explicit close
454 065 implicit close (in GC'd languages)
455 070 optargs
456 080 version
457 090 retvalues
458 - 100 launch, create partitions and LVs and filesystems
460 - 400+ events:
462 410 close event
464 420 log messages
465 430 progress messages
466 - 800+ regression tests (specific to the language)
468 - 900+ any other custom tests for the language
470 To save time when running the tests, only 100, 430, 800+, 900+ should
472 launch the handle.
473 FORMATTING CODE
475 Our C source code generally adheres to some basic code-formatting
476 conventions. The existing code base is not totally consistent on this
477 front, but we do prefer that contributed code be formatted similarly.
478 In short, use spaces-not-TABs for indentation, use 2 spaces for each
479 indentation level, and other than that, follow the K&R style.
480 If you use Emacs, add the following to one of your start-up files
482 (e.g., ~/.emacs), to help ensure that you get indentation right:
483 ;;; In libguestfs, indent with spaces everywhere (not TABs).
485 ;;; Exceptions: Makefile and ChangeLog modes.
486 (add-hook 'find-file-hook
487 '(lambda () (if (and buffer-file-name
488 (string-match "/libguestfs\\>"
489 (buffer-file-name))
490 (not (string-equal mode-name "Change Log"))
491 (not (string-equal mode-name "Makefile")))
492 (setq indent-tabs-mode nil))))
493 ;;; When editing C sources in libguestfs, use this style.
495 (defun libguestfs-c-mode ()
496 "C mode with adjusted defaults for use with libguestfs."
497 (interactive)
498 (c-set-style "K&R")
499 (setq c-indent-level 2)
500 (setq c-basic-offset 2))
501 (add-hook 'c-mode-hook
502 '(lambda () (if (string-match "/libguestfs\\>"
503 (buffer-file-name))
504 (libguestfs-c-mode))))
505 TESTING YOUR CHANGES
507 Turn warnings into errors when developing to make warnings hard to
508 ignore:
509 ./configure --enable-werror
511 Useful targets are:
513 "make check"
515 Runs the regular test suite.
516 This is implemented using the regular automake "TESTS" target. See
518 the automake documentation for details.
519 "make check-valgrind"
521 Runs a subset of the test suite under valgrind.
522 See "VALGRIND" below.
524 "make check-valgrind-local-guests"
526 Runs a subset of the test suite under valgrind using locally
527 installed libvirt guests (read-only).
528 "make check-direct"
530 Runs all tests using default appliance back-end. This only has any
531 effect if a non-default backend was selected using "./configure
532 --with-default-backend=..."
533 "make check-valgrind-direct"
535 Run a subset of the test suite under valgrind using the default
536 appliance back-end.
537 "make check-with-upstream-qemu"
539 Runs all tests using a local qemu binary. It looks for the qemu
540 binary in QEMUDIR (defaults to $HOME/d/qemu), but you can set this
541 to another directory on the command line, eg:
542 make check-with-upstream-qemu QEMUDIR=/usr/src/qemu
544 "make check-with-upstream-libvirt"
546 Runs all tests using a local libvirt. This only has any effect if
547 the libvirt backend was selected using "./configure
548 --with-default-backend=libvirt"
549 It looks for libvirt in LIBVIRTDIR (defaults to $HOME/d/libvirt),
551 but you can set this to another directory on the command line, eg:
552 make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt
554 "make check-slow"
556 Runs some slow/long-running tests which are not run by default.
557 To mark a test as slow/long-running:
559 • Add it to the list of "TESTS" in the Makefile.am, just like a
561 normal test.
562 • Modify the test so it checks if the "SLOW=1" environment
564 variable is set, and if not set it skips (ie. returns with exit
565 code 77). If using $TEST_FUNCTIONS, you can call the function
566 "slow_test" for this.
567 • Add a variable "SLOW_TESTS" to the Makefile.am listing the slow
569 tests.
570 • Add a rule to the Makefile.am:
572 check-slow:
574 $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
575 "sudo make check-root"
577 Runs some tests which require root privileges. These are supposed
578 to be safe, but take care. You have to run this as root (eg. using
579 sudo(8) explicitly).
580 To mark a test as requiring root:
582 • Add it to the list of "TESTS" in the Makefile.am, just like a
584 normal test.
585 • Modify the test so it checks if euid == 0, and if not set it
587 skips (ie. returns with exit code 77). If using
588 $TEST_FUNCTIONS, you can call the function "root_test" for
589 this.
590 • Add a variable "ROOT_TESTS" to the Makefile.am listing the root
592 tests.
593 • Add a rule to the Makefile.am:
595 check-root:
597 $(MAKE) check TESTS="$(ROOT_TESTS)"
598 "make check-all"
600 Equivalent to running all "make check*" rules except "check-root".
601 "make check-release"
603 Runs a subset of "make check*" rules that are required to pass
604 before a tarball can be released. Currently this is:
605 • check
607 • check-valgrind
609 • check-direct
611 • check-valgrind-direct
613 • check-slow
615 "make installcheck"
617 Run "make check" on the installed copy of libguestfs.
618 The version of installed libguestfs being tested, and the version
620 of the libguestfs source tree must be the same.
621 Do:
623 ./configure
625 make clean ||:
626 make
627 make installcheck
628 VALGRIND
630 When you do "make check-valgrind", it searches for any Makefile.am in
631 the tree that has a "check-valgrind:" target and runs it.
632 Writing the Makefile.am and tests correctly to use valgrind and working
634 with automake parallel tests is subtle.
635 If your tests are run via a shell script wrapper, then in the wrapper
637 use:
638 $VG virt-foo
640 and in the Makefile.am use:
642 check-valgrind:
644 make VG="@VG@" check
645 However, if your binaries run directly from the "TESTS" rule, you have
647 to modify the Makefile.am like this:
648 LOG_COMPILER = $(VG)
650 check-valgrind:
652 make VG="@VG@" check
653 In either case, check that the right program is being tested by
655 examining the tmp/valgrind* log files carefully.
656 SUBMITTING PATCHES
658 Submit patches to the mailing list:
659 http://www.redhat.com/mailman/listinfo/libguestfs and CC to
660 rjones@redhat.com.
661 You do not need to subscribe to the mailing list if you don’t want to.
663 There may be a short delay while your message is moderated.
664 DAEMON CUSTOM PRINTF FORMATTERS
666 In the daemon code we have created custom printf formatters %Q and %R,
667 which are used to do shell quoting.
668 %Q Simple shell quoted string. Any spaces or other shell characters
670 are escaped for you.
671 %R Same as %Q except the string is treated as a path which is prefixed
673 by the sysroot.
674 For example:
676 asprintf (&cmd, "cat %R", path);
678 would produce "cat /sysroot/some\ path\ with\ spaces"
680 Note: Do not use these when you are passing parameters to the
682 "command{,r,v,rv}()" functions. These parameters do NOT need to be
683 quoted because they are not passed via the shell (instead, straight to
684 exec). You probably want to use the "sysroot_path()" function however.
685 INTERNATIONALIZATION (I18N) SUPPORT
687 We support i18n (gettext anyhow) in the library.
688 However many messages come from the daemon, and we don’t translate
690 those at the moment. One reason is that the appliance generally has
691 all locale files removed from it, because they take up a lot of space.
692 So we'd have to readd some of those, as well as copying our PO files
693 into the appliance.
694 Debugging messages are never translated, since they are intended for
696 the programmers.
697
699 HOW OCAML PROGRAMS ARE COMPILED AND LINKED
700 Mostly this section is "how we make automake & ocamlopt work together"
701 since OCaml programs themselves are easy to compile.
702 Automake has no native support for OCaml programs, ocamlc nor ocamlopt.
704 What we do instead is to treat OCaml programs as C programs which
705 happen to contain these "other objects" ("DEPENDENCIES" in automake-
706 speak) that happen to be the OCaml objects. This works because OCaml
707 programs usually have C files for native bindings etc.
708 So a typical program is described as just its C sources:
710 virt_customize_SOURCES = ... crypt-c.c perl_edit-c.c
712 For programs that have no explicit C sources, we create an empty
714 dummy.c file, and list that instead:
715 virt_resize_SOURCES = dummy.c
717 The OCaml objects which contain most of the code are listed as automake
719 dependencies (other dependencies may also be listed):
720 virt_customize_DEPENDENCIES = ... customize_main.cmx
722 The only other special thing we need to do is to provide a custom link
724 command. This is needed because automake won't assemble the ocamlopt
725 command, the list of objects and the "-cclib" libraries in the correct
726 order otherwise.
727 virt_customize_LINK = \
729 $(top_builddir)/ocaml-link.sh -cclib '-lutils' -- ...
730 The actual rules, which you can examine in customize/Makefile.am, are a
732 little bit more complicated than this because they have to handle:
733 • Compiling for byte code or native code.
735 • The pattern rules needed to compile the OCaml sources to objects.
737 These are now kept in subdir-rules.mk at the top level, which is
739 included in every subdirectory Makefile.am.
740 • Adding OCaml sources files to "EXTRA_DIST".
742 Automake isn't aware of the complete list of sources for a binary,
744 so it will not add them all automatically.
745
747 MAINTAINER MAKEFILE TARGETS
748 These "make" targets probably won’t work and aren't useful unless you
749 are a libguestfs maintainer.
750 make maintainer-commit
752 This commits everything in the working directory with the commit
754 message "Version $(VERSION).". You must update configure.ac, clean and
755 rebuild first.
756 make maintainer-tag
758 This tags the current HEAD commit with the tag "v$(VERSION)" and one of
760 the messages:
761 Version $(VERSION) stable
763 Version $(VERSION) development
765 (See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for the difference
767 between a stable and development release.)
768 make maintainer-check-authors
770 Check that all authors (found in git commit messages) are included in
772 the generator/authors.ml file.
773 make maintainer-check-extra-dist
775 This rule must be run after "make dist" (so there is a tarball in the
777 working directory). It compares the contents of the tarball with the
778 contents of git to ensure that no files have been missed from
779 Makefile.am "EXTRA_DIST" rules.
780 make maintainer-upload-website
782 This is used by the software used to automate libguestfs releases to
784 copy the libguestfs website to another git repository before it is
785 uploaded to the web server.
786 MAKING A STABLE RELEASE
788 When we make a stable release, there are several steps documented here.
789 See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for general information
790 about the stable branch policy.
791 • Check "make && make check" works on at least:
793 Fedora (x86-64)
795 Debian (x86-64)
796 Ubuntu (x86-64)
797 Fedora (aarch64)
798 Fedora (ppc64)
799 Fedora (ppc64le)
800 • Check "./configure --without-libvirt" works.
801 • Finalize guestfs-release-notes.pod
803 • Create new stable and development directories under
805 http://libguestfs.org/download.
806 • Edit website/index.html.in.
808 • Set the version (in configure.ac) to the new stable version, ie.
810 1.XX.0, and commit it:
811 ./localconfigure
813 make distclean -k
814 ./localconfigure
815 make && make dist
816 make maintainer-commit
817 make maintainer-tag
818 • Create the stable branch in git:
820 git branch stable-1.XX
822 git push origin stable-1.XX
823 • Do a full release of the stable branch.
825 • Set the version to the next development version and commit that.
827 Optionally do a full release of the development branch.
828
830 This section documents internal functions inside libguestfs and various
831 utilities. It is intended for libguestfs developers only.
832 This section is autogenerated from "/**" comments in source files,
834 which are marked up in POD format.
835 These functions are not publicly exported, and may change or be removed
837 at any time.
838 Subdirectory lib
840 File lib/actions-support.c
841 Helper functions for the actions code in lib/actions-*.c.
843 File lib/appliance-cpu.c
845 The appliance choice of CPU model.
847 Function "lib/appliance-cpu.c:guestfs_int_get_cpu_model"
849 const char *
851 guestfs_int_get_cpu_model (int kvm)
852 Return the right CPU model to use as the qemu "-cpu" parameter or its
854 equivalent in libvirt. This returns:
855 "host"
857 The literal string "host" means use "-cpu host".
858 "max"
860 The literal string "max" means use "-cpu max" (the best possible).
861 This requires awkward translation for libvirt.
862 some string
864 Some string such as "cortex-a57" means use "-cpu cortex-a57".
865 "NULL"
867 "NULL" means no "-cpu" option at all. Note returning "NULL" does
868 not indicate an error.
869 This is made unnecessarily hard and fragile because of two stupid
871 choices in QEMU:
872 • The default for "qemu-system-aarch64 -M virt" is to emulate a
874 "cortex-a15" (WTF?).
875 • We don't know for sure if KVM will work, but "-cpu host" is broken
877 with TCG, so we almost always pass a broken "-cpu" flag if KVM is
878 semi-broken in any way.
879 File lib/appliance-kcmdline.c
881 The appliance kernel command line.
883 Definition "lib/appliance-kcmdline.c:VALID_TERM"
885 #define VALID_TERM
887 Check that the $TERM environment variable is reasonable before we pass
889 it through to the appliance.
890 Function "lib/appliance-kcmdline.c:get_root_uuid_with_file"
892 static char *
894 get_root_uuid_with_file (guestfs_h *g, const char *appliance)
895 Given a disk image containing an extX filesystem, return the UUID.
897 Function "lib/appliance-kcmdline.c:run_qemu_img_dd"
899 static int
901 run_qemu_img_dd (guestfs_h *g, const char *in_file, char *out_file)
902 Read the first 256k bytes of the in_file with qemu-img(1) command and
904 write them into the out_file. That may be useful to get UUID of the
905 QCOW2 disk image with "get_root_uuid_with_file".
906 The function returns zero if successful, otherwise -1.
908 Function "lib/appliance-kcmdline.c:get_root_uuid"
910 static char *
912 get_root_uuid (guestfs_h *g, const char *appliance)
913 Get the UUID from the appliance disk image.
915 Function "lib/appliance-kcmdline.c:guestfs_int_appliance_command_line"
917 char *
919 guestfs_int_appliance_command_line (guestfs_h *g,
920 const char *appliance,
921 int flags)
922 Construct the Linux command line passed to the appliance. This is used
924 by the "direct" and "libvirt" backends, and is simply located in this
925 file because it's a convenient place for this common code.
926 The "appliance" parameter is the filename of the appliance (could be
928 NULL) from which we obtain the root UUID.
929 The "flags" parameter can contain the following flags logically or'd
931 together (or 0):
932 "APPLIANCE_COMMAND_LINE_IS_TCG"
934 If we are launching a qemu TCG guest (ie. KVM is known to be
935 disabled or unavailable). If you don't know, don't pass this flag.
936 Note that this function returns a newly allocated buffer which must be
938 freed by the caller.
939 File lib/appliance-uefi.c
941 Find the UEFI firmware needed to boot the appliance.
943 See also lib/uefi.c (autogenerated file) containing the firmware file
945 locations.
946 Function "lib/appliance-uefi.c:guestfs_int_get_uefi"
948 int
950 guestfs_int_get_uefi (guestfs_h *g, char *const *firmwares,
951 const char **firmware, char **code, char **vars,
952 int *flags)
953 Return the location of firmware needed to boot the appliance. This is
955 aarch64 only currently, since that's the only architecture where UEFI
956 is mandatory (and that only for RHEL).
957 "firmwares" is an optional list of allowed values for the firmware
959 autoselection of libvirt. It is "NULL" to indicate it is not supported.
960 *firmware is set to one of the strings in "firmwares" in case one can
961 be used.
962 *code is initialized with the path to the read-only UEFI code file.
964 *vars is initialized with the path to a copy of the UEFI vars file
965 (which is cleaned up automatically on exit).
966 In case a UEFI firmware is available, either *firmware is set to a
968 non-"NULL" value, or *code and *vars are.
969 *code and *vars should be freed by the caller, and *firmware must not.
971 If the function returns "-1" then there was a real error which should
973 cause appliance building to fail (no UEFI firmware is not an error).
974 See also virt-v2v.git/v2v/utils.ml:find_uefi_firmware
976 File lib/appliance.c
978 This file deals with building the libguestfs appliance.
980 Function "lib/appliance.c:guestfs_int_build_appliance"
982 int
984 guestfs_int_build_appliance (guestfs_h *g,
985 char **kernel_rtn,
986 char **initrd_rtn,
987 char **appliance_rtn)
988 Locate or build the appliance.
990 This function locates or builds the appliance as necessary, handling
992 the supermin appliance, caching of supermin-built appliances, or using
993 either a fixed or old-style appliance.
994 The return value is 0 = good, "-1" = error. Returned in
996 "appliance.kernel" will be the name of the kernel to use,
997 "appliance.initrd" the name of the initrd, "appliance.image" the name
998 of the ext2 root filesystem. "appliance.image" can be "NULL", meaning
999 that we are using an old-style (non-ext2) appliance. All three strings
1000 must be freed by the caller. However the referenced files themselves
1001 must not be deleted.
1002 The process is as follows:
1004 1. Look in "path" which contains a supermin appliance skeleton. If no
1006 element has this, skip straight to step 3.
1007 2. Call "supermin --build" to build the full appliance (if it needs to
1009 be rebuilt). If this is successful, return the full appliance.
1010 3. Check "path", looking for a fixed appliance. If one is found,
1012 return it.
1013 4. Check "path", looking for an old-style appliance. If one is found,
1015 return it.
1016 The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/
1018 and consists of up to four files:
1019 $TMPDIR/.guestfs-$UID/lock - the supermin lock file
1021 $TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
1022 $TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
1023 $TMPDIR/.guestfs-$UID/appliance.d/root - the appliance
1024 Multiple instances of libguestfs with the same UID may be racing to
1026 create an appliance. However (since supermin ≥ 5) supermin provides a
1027 --lock flag and atomic update of the appliance.d subdirectory.
1028 Function "lib/appliance.c:locate_or_build_appliance"
1030 static int
1032 locate_or_build_appliance (guestfs_h *g,
1033 struct appliance_files *appliance,
1034 const char *path)
1035 Check "path", looking for one of appliances: supermin appliance, fixed
1037 appliance or old-style appliance. If one of the fixed appliances is
1038 found, return it. If the supermin appliance skeleton is found, build
1039 and return appliance.
1040 Return values:
1042 1 = appliance is found, returns C<appliance>,
1044 0 = appliance not found,
1045 -1 = error which aborts the launch process.
1046 Function "lib/appliance.c:search_appliance"
1048 static int
1050 search_appliance (guestfs_h *g, struct appliance_files *appliance)
1051 Search elements of "g->path", returning the first "appliance" element
1053 which matches the predicate function "locate_or_build_appliance".
1054 Return values:
1056 1 = a path element matched, returns C<appliance>,
1058 0 = no path element matched,
1059 -1 = error which aborts the launch process.
1060 Function "lib/appliance.c:build_supermin_appliance"
1062 static int
1064 build_supermin_appliance (guestfs_h *g,
1065 const char *supermin_path,
1066 struct appliance_files *appliance)
1067 Build supermin appliance from "supermin_path" to $TMPDIR/.guestfs-$UID.
1069 Returns: 0 = built or "-1" = error (aborts launch).
1071 Function "lib/appliance.c:run_supermin_build"
1073 static int
1075 run_supermin_build (guestfs_h *g,
1076 const char *lockfile,
1077 const char *appliancedir,
1078 const char *supermin_path)
1079 Run "supermin --build" and tell it to generate the appliance.
1081 Function "lib/appliance.c:dir_contains_file"
1083 static int
1085 dir_contains_file (guestfs_h *g, const char *dir, const char *file)
1086 Returns true iff "file" is contained in "dir".
1088 Function "lib/appliance.c:dir_contains_files"
1090 static int
1092 dir_contains_files (guestfs_h *g, const char *dir, ...)
1093 Returns true iff every listed file is contained in "dir".
1095 File lib/command.c
1097 A wrapper for running external commands, loosely based on libvirt's
1099 "virCommand" interface.
1100 In outline to use this interface you must:
1102 1. Create a new command handle:
1104 struct command *cmd;
1106 cmd = guestfs_int_new_command (g);
1107 2. Either add arguments:
1109 guestfs_int_cmd_add_arg (cmd, "qemu-img");
1111 guestfs_int_cmd_add_arg (cmd, "info");
1112 guestfs_int_cmd_add_arg (cmd, filename);
1113 (NB: You don't need to add a "NULL" argument at the end.)
1115 3. Or construct a command using a mix of quoted and unquoted strings.
1117 (This is useful for system(3)/"popen("r")"-style shell commands,
1118 with the added safety of allowing args to be quoted properly).
1119 guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
1121 guestfs_int_cmd_add_string_quoted (cmd, filename);
1122 4. Set various flags, such as whether you want to capture errors in
1124 the regular libguestfs error log.
1125 5. Run the command. This is what does the fork(2) call, optionally
1127 loops over the output, and then does a waitpid(3) and returns the
1128 exit status of the command.
1129 r = guestfs_int_cmd_run (cmd);
1131 if (r == -1)
1132 // error
1133 // else test r using the WIF* functions
1134 6. Close the handle:
1136 guestfs_int_cmd_close (cmd);
1138 (or use "CLEANUP_CMD_CLOSE").
1140 Function "lib/command.c:guestfs_int_new_command"
1142 struct command *
1144 guestfs_int_new_command (guestfs_h *g)
1145 Create a new command handle.
1147 Function "lib/command.c:guestfs_int_cmd_add_arg"
1149 void
1151 guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)
1152 Add single arg (for "execv"-style command execution).
1154 Function "lib/command.c:guestfs_int_cmd_add_arg_format"
1156 void
1158 guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)
1159 Add single arg (for "execv"-style command execution) using a
1161 printf(3)-style format string.
1162 Function "lib/command.c:guestfs_int_cmd_add_string_unquoted"
1164 void
1166 guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)
1167 Add a string (for system(3)-style command execution).
1169 This variant adds the strings without quoting them, which is dangerous
1171 if the string contains untrusted content.
1172 Function "lib/command.c:guestfs_int_cmd_add_string_quoted"
1174 void
1176 guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)
1177 Add a string (for system(3)-style command execution).
1179 The string is enclosed in double quotes, with any special characters
1181 within the string which need escaping done. This is used to add a
1182 single argument to a system(3)-style command string.
1183 Function "lib/command.c:guestfs_int_cmd_set_stdout_callback"
1185 void
1187 guestfs_int_cmd_set_stdout_callback (struct command *cmd,
1188 cmd_stdout_callback stdout_callback,
1189 void *stdout_data, unsigned flags)
1190 Set a callback which will capture stdout.
1192 If flags contains "CMD_STDOUT_FLAG_LINE_BUFFER" (the default), then the
1194 callback is called line by line on the output. If there is a trailing
1195 "\n" then it is automatically removed before the callback is called.
1196 The line buffer is "\0"-terminated.
1197 If flags contains "CMD_STDOUT_FLAG_UNBUFFERED", then buffers are passed
1199 to the callback as it is received from the command. Note in this case
1200 the buffer is not "\0"-terminated, so you need to may attention to the
1201 length field in the callback.
1202 If flags contains "CMD_STDOUT_FLAG_WHOLE_BUFFER", then the callback is
1204 called exactly once, with the entire buffer. Note in this case the
1205 buffer is not "\0"-terminated, so you need to may attention to the
1206 length field in the callback.
1207 Function "lib/command.c:guestfs_int_cmd_set_stderr_to_stdout"
1209 void
1211 guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)
1212 Equivalent to adding "2>&1" to the end of the command. This is
1214 incompatible with the "capture_errors" flag, because it doesn't make
1215 sense to combine them.
1216 Function "lib/command.c:guestfs_int_cmd_clear_capture_errors"
1218 void
1220 guestfs_int_cmd_clear_capture_errors (struct command *cmd)
1221 Clear the "capture_errors" flag. This means that any errors will go to
1223 stderr, instead of being captured in the event log, and that is usually
1224 undesirable.
1225 Function "lib/command.c:guestfs_int_cmd_clear_close_files"
1227 void
1229 guestfs_int_cmd_clear_close_files (struct command *cmd)
1230 Don't close file descriptors after the fork.
1232 XXX Should allow single fds to be sent to child process.
1234 Function "lib/command.c:guestfs_int_cmd_set_child_callback"
1236 void
1238 guestfs_int_cmd_set_child_callback (struct command *cmd,
1239 cmd_child_callback child_callback,
1240 void *data)
1241 Set a function to be executed in the child, right before the execution.
1243 Can be used to setup the child, for example changing its current
1244 directory.
1245 Function "lib/command.c:guestfs_int_cmd_set_child_rlimit"
1247 void
1249 guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)
1250 Set up child rlimits, in case the process we are running could consume
1252 lots of space or time.
1253 Function "lib/command.c:finish_command"
1255 static void
1257 finish_command (struct command *cmd)
1258 Finish off the command by either "NULL"-terminating the argv array or
1260 adding a terminating "\0" to the string, or die with an internal error
1261 if no command has been added.
1262 Function "lib/command.c:loop"
1264 static int
1266 loop (struct command *cmd)
1267 The loop which reads errors and output and directs it either to the log
1269 or to the stdout callback as appropriate.
1270 Function "lib/command.c:guestfs_int_cmd_run"
1272 int
1274 guestfs_int_cmd_run (struct command *cmd)
1275 Fork, run the command, loop over the output, and waitpid.
1277 Returns the exit status. Test it using "WIF*" macros.
1279 On error: Calls "error" and returns "-1".
1281 Function "lib/command.c:guestfs_int_cmd_pipe_run"
1283 int
1285 guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)
1286 Fork and run the command, but don't wait. Roughly equivalent to
1288 "popen (..., "r"|"w")".
1289 Returns the file descriptor of the pipe, connected to stdout ("r") or
1291 stdin ("w") of the child process.
1292 After reading/writing to this pipe, call "guestfs_int_cmd_pipe_wait" to
1294 wait for the status of the child.
1295 Errors from the subcommand cannot be captured to the error log using
1297 this interface. Instead the caller should call
1298 "guestfs_int_cmd_get_pipe_errors" (after "guestfs_int_cmd_pipe_wait"
1299 returns an error).
1300 Function "lib/command.c:guestfs_int_cmd_pipe_wait"
1302 int
1304 guestfs_int_cmd_pipe_wait (struct command *cmd)
1305 Wait for a subprocess created by "guestfs_int_cmd_pipe_run" to finish.
1307 On error (eg. failed syscall) this returns "-1" and sets the error. If
1308 the subcommand fails, then use "WIF*" macros to check this, and call
1309 "guestfs_int_cmd_get_pipe_errors" to read the error messages printed by
1310 the child.
1311 Function "lib/command.c:guestfs_int_cmd_get_pipe_errors"
1313 char *
1315 guestfs_int_cmd_get_pipe_errors (struct command *cmd)
1316 Read the error messages printed by the child. The caller must free the
1318 returned buffer after use.
1319 Function "lib/command.c:guestfs_int_cmd_close"
1321 void
1323 guestfs_int_cmd_close (struct command *cmd)
1324 Close the "cmd" object and free all resources.
1326 Function "lib/command.c:process_line_buffer"
1328 static void
1330 process_line_buffer (struct command *cmd, int closed)
1331 Deal with buffering stdout for the callback.
1333 File lib/conn-socket.c
1335 This file handles connections to the child process where this is done
1337 over regular POSIX sockets.
1338 Function "lib/conn-socket.c:handle_log_message"
1340 static int
1342 handle_log_message (guestfs_h *g,
1343 struct connection_socket *conn)
1344 This is called if "conn->console_sock" becomes ready to read while we
1346 are doing one of the connection operations above. It reads and deals
1347 with the log message.
1348 Returns:
1350 1 log message(s) were handled successfully
1352 0 connection to appliance closed
1354 "-1"
1356 error
1357 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_listening"
1359 struct connection *
1361 guestfs_int_new_conn_socket_listening (guestfs_h *g,
1362 int daemon_accept_sock,
1363 int console_sock)
1364 Create a new socket connection, listening.
1366 Note that it's OK for "console_sock" to be passed as "-1", meaning
1368 there's no console available for this appliance.
1369 After calling this, "daemon_accept_sock" is owned by the connection,
1371 and will be closed properly either in "accept_connection" or
1372 "free_connection".
1373 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_connected"
1375 struct connection *
1377 guestfs_int_new_conn_socket_connected (guestfs_h *g,
1378 int daemon_sock,
1379 int console_sock)
1380 Create a new socket connection, connected.
1382 As above, but the caller passes us a connected "daemon_sock" and
1384 promises not to call "accept_connection".
1385 File lib/create.c
1387 APIs for creating empty disks.
1389 Mostly this consists of wrappers around the qemu-img(1) program.
1391 Definition "lib/create.c:VALID_FORMAT"
1393 #define VALID_FORMAT
1395 Check for valid backing format. Allow any "^[[:alnum]]+$" (in C
1397 locale), but limit the length to something reasonable.
1398 File lib/drives.c
1400 Drives added are stored in an array in the handle. Code here manages
1402 that array and the individual "struct drive" data.
1403 Function "lib/drives.c:create_overlay"
1405 static int
1407 create_overlay (guestfs_h *g, struct drive *drv)
1408 For readonly drives, create an overlay to protect the original drive
1410 content. Note we never need to clean up these overlays since they are
1411 created in the temporary directory and deleted when the handle is
1412 closed.
1413 Function "lib/drives.c:create_drive_file"
1415 static struct drive *
1417 create_drive_file (guestfs_h *g,
1418 const struct drive_create_data *data)
1419 Create and free the "struct drive".
1421 Function "lib/drives.c:create_drive_dev_null"
1423 static struct drive *
1425 create_drive_dev_null (guestfs_h *g,
1426 struct drive_create_data *data)
1427 Create the special /dev/null drive.
1429 Traditionally you have been able to use /dev/null as a filename, as
1431 many times as you like. Ancient KVM (RHEL 5) cannot handle adding
1432 /dev/null readonly. qemu 1.2 + virtio-scsi segfaults when you use any
1433 zero-sized file including /dev/null.
1434 Because of these problems, we replace /dev/null with a non-zero sized
1436 temporary file. This shouldn't make any difference since users are not
1437 supposed to try and access a null drive.
1438 Function "lib/drives.c:drive_to_string"
1440 static char *
1442 drive_to_string (guestfs_h *g, const struct drive *drv)
1443 Convert a "struct drive" to a string for debugging. The caller must
1445 free this string.
1446 Function "lib/drives.c:add_drive_to_handle_at"
1448 static void
1450 add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)
1451 Add "struct drive" to the "g->drives" vector at the given index
1453 "drv_index". If the array isn't large enough it is reallocated. The
1454 index must not contain a drive already.
1455 Function "lib/drives.c:add_drive_to_handle"
1457 static void
1459 add_drive_to_handle (guestfs_h *g, struct drive *d)
1460 Add struct drive to the end of the "g->drives" vector in the handle.
1462 Function "lib/drives.c:guestfs_int_add_dummy_appliance_drive"
1464 void
1466 guestfs_int_add_dummy_appliance_drive (guestfs_h *g)
1467 Called during launch to add a dummy slot to "g->drives".
1469 Function "lib/drives.c:guestfs_int_free_drives"
1471 void
1473 guestfs_int_free_drives (guestfs_h *g)
1474 Free up all the drives in the handle.
1476 Definition "lib/drives.c:VALID_FORMAT_IFACE"
1478 #define VALID_FORMAT_IFACE
1480 Check string parameter matches regular expression "^[-_[:alnum:]]+$"
1482 (in C locale).
1483 Definition "lib/drives.c:VALID_DISK_LABEL"
1485 #define VALID_DISK_LABEL
1487 Check the disk label is reasonable. It can't contain certain
1489 characters, eg. '/', ','. However be stricter here and ensure it's
1490 just alphabetic and ≤ 20 characters in length.
1491 Definition "lib/drives.c:VALID_HOSTNAME"
1493 #define VALID_HOSTNAME
1495 Check the server hostname is reasonable.
1497 Function "lib/drives.c:valid_port"
1499 static int
1501 valid_port (int port)
1502 Check the port number is reasonable.
1504 Function "lib/drives.c:valid_blocksize"
1506 static int
1508 valid_blocksize (int blocksize)
1509 Check the block size is reasonable. It can't be other then 512 or
1511 4096.
1512 Function "lib/drives.c:guestfs_int_checkpoint_drives"
1514 size_t
1516 guestfs_int_checkpoint_drives (guestfs_h *g)
1517 Checkpoint and roll back drives, so that groups of drives can be added
1519 atomically. Only used by "guestfs_add_domain" in guestfs(3).
1520 Function "lib/drives.c:guestfs_impl_debug_drives"
1522 char **
1524 guestfs_impl_debug_drives (guestfs_h *g)
1525 Internal function to return the list of drives.
1527 File lib/errors.c
1529 This file handles errors, and also debug, trace and warning messages.
1531 Errors in libguestfs API calls are handled by setting an error message
1533 and optional errno in the handle. The caller has the choice of testing
1534 API calls to find out if they failed and then querying the last error
1535 from the handle, and/or getting a callback.
1536 From the point of view of the library source, generally you should use
1538 the "error" or "perrorf" macros along error paths, eg:
1539 if (something_bad) {
1541 error (g, "something bad happened");
1542 return -1;
1543 }
1544 Make sure to call the "error" or "perrorf" macro exactly once along
1546 each error path, since the handle can only store a single error and the
1547 previous error will be overwritten.
1548 Function "lib/errors.c:guestfs_int_warning"
1550 void
1552 guestfs_int_warning (guestfs_h *g, const char *fs, ...)
1553 Print a warning.
1555 Code should not call this function directly. Use the
1557 "warning (g, fs, ...)" macro.
1558 Warnings are printed unconditionally. We try to make these rare:
1560 Generally speaking, a warning should either be an error, or if it's not
1561 important for end users then it should be a debug message.
1562 Function "lib/errors.c:guestfs_int_debug"
1564 void
1566 guestfs_int_debug (guestfs_h *g, const char *fs, ...)
1567 Print a debug message.
1569 Code should not call this function directly. To add debug messages in
1571 the library, use the "debug (g, fs, ...)" macro. The macro checks if
1572 "g->verbose" is false and avoids the function call, meaning the macro
1573 is more efficient.
1574 Function "lib/errors.c:guestfs_int_trace"
1576 void
1578 guestfs_int_trace (guestfs_h *g, const char *fs, ...)
1579 Print a trace message.
1581 Do not call this function. All calls are generated automatically.
1583 Function "lib/errors.c:guestfs_int_error_errno"
1585 void
1587 guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)
1588 Set the last error and errno in the handle, and optionally raise the
1590 error callback if one is defined.
1591 If you don't need to set errno, use the "error (g, fs, ...)" macro
1593 instead of calling this directly. If you need to set errno then there
1594 is no macro wrapper, so calling this function directly is fine.
1595 Function "lib/errors.c:guestfs_int_perrorf"
1597 void
1599 guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)
1600 Similar to perror(3), but it sets the last error in the handle, raises
1602 the error callback if one is defined, and supports format strings.
1603 You should probably use the "perrorf (g, fs, ...)" macro instead of
1605 calling this directly.
1606 Function "lib/errors.c:guestfs_int_launch_failed_error"
1608 void
1610 guestfs_int_launch_failed_error (guestfs_h *g)
1611 Raise a launch failed error in a standard format.
1613 Since this is the most common error seen by people who have
1615 installation problems, buggy qemu, etc, and since no one reads the FAQ,
1616 describe in this error message what resources are available to debug
1617 launch problems.
1618 Function "lib/errors.c:guestfs_int_unexpected_close_error"
1620 void
1622 guestfs_int_unexpected_close_error (guestfs_h *g)
1623 Raise an error if the appliance unexpectedly crashes after launch.
1625 Function "lib/errors.c:guestfs_int_launch_timeout"
1627 void
1629 guestfs_int_launch_timeout (guestfs_h *g)
1630 Raise an error if the appliance hangs during launch.
1632 Function "lib/errors.c:guestfs_int_external_command_failed"
1634 void
1636 guestfs_int_external_command_failed (guestfs_h *g, int status,
1637 const char *cmd_name, const char *extra)
1638 Raise an error if an external command fails.
1640 "status" is the status code of the command (eg. returned from
1642 waitpid(2) or system(3)). This function turns the status code into an
1643 explanatory string.
1644 File lib/events.c
1646 Function "lib/events.c:replace_old_style_event_callback"
1648 static void
1650 replace_old_style_event_callback (guestfs_h *g,
1651 guestfs_event_callback cb,
1652 uint64_t event_bitmask,
1653 void *opaque,
1654 void *opaque2)
1655 Emulate old-style callback API.
1657 There were no event handles, so multiple callbacks per event were not
1659 supported. Calling the same "guestfs_set_*_callback" function would
1660 replace the existing event. Calling it with "cb == NULL" meant that
1661 the caller wanted to remove the callback.
1662 File lib/guestfs-internal-all.h
1664 This header contains definitions which are shared by all parts of
1666 libguestfs, ie. the daemon, the library, language bindings and virt
1667 tools (ie. all C code).
1668 If you need a definition used by only the library, put it in
1670 lib/guestfs-internal.h instead.
1671 If a definition is used by only a single tool, it should not be in any
1673 shared header file at all.
1674 File lib/guestfs-internal.h
1676 This header file is included in the libguestfs library (lib/) only.
1678 See also lib/guestfs-internal-all.h.
1680 Structure "lib/guestfs-internal.h:event"
1682 struct event {
1684 uint64_t event_bitmask;
1685 guestfs_event_callback cb;
1686 void *opaque;
1687 /* opaque2 is not exposed through the API, but is used internally to
1689 * emulate the old-style callback API.
1690 */
1691 void *opaque2;
1692 };
1693 This struct is used to maintain a list of events registered against the
1695 handle. See "g->events" in the handle.
1696 Structure "lib/guestfs-internal.h:drive"
1698 struct drive {
1700 /* Original source of the drive, eg. file:..., http:... */
1701 struct drive_source src;
1702 /* If the drive is readonly, then an overlay [a local file] is
1704 * created before launch to protect the original drive content, and
1705 * the filename is stored here. Backends should open this file if
1706 * it is non-NULL, else consult the original source above.
1707 *
1708 * Note that the overlay is in a backend-specific format, probably
1709 * different from the source format. eg. qcow2
1710 */
1711 char *overlay;
1712 /* Various per-drive flags. */
1714 bool readonly;
1715 char *iface;
1716 char *name;
1717 char *disk_label;
1718 char *cachemode;
1719 enum discard discard;
1720 bool copyonread;
1721 int blocksize;
1722 };
1723 There is one "struct drive" per drive.
1725 Structure "lib/guestfs-internal.h:backend_ops"
1727 struct backend_ops {
1729 /* Size (in bytes) of the per-handle data structure needed by this
1730 * backend. The data pointer is allocated and freed by libguestfs
1731 * and passed to the functions in the 'void *data' parameter.
1732 * Inside the data structure is opaque to libguestfs. Any strings
1733 * etc pointed to by it must be freed by the backend during
1734 * shutdown.
1735 */
1736 size_t data_size;
1737 /* Create a COW overlay on top of a drive. This must be a local
1739 * file, created in the temporary directory. This is called when
1740 * the drive is added to the handle.
1741 */
1742 char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);
1743 /* Launch and shut down. */
1745 int (*launch) (guestfs_h *g, void *data, const char *arg);
1746 int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);
1747 /* Miscellaneous. */
1749 int (*get_pid) (guestfs_h *g, void *data);
1750 int (*max_disks) (guestfs_h *g, void *data);
1751 };
1752 Backend operations.
1754 Each backend (eg. libvirt, direct) defines some functions which get run
1756 at various places in the handle lifecycle (eg. at launch, shutdown).
1757 The backend defines this struct pointing to those functions.
1758 Structure "lib/guestfs-internal.h:connection"
1760 struct connection {
1762 const struct connection_ops *ops;
1763 /* In the real struct, private data used by each connection module
1765 * follows here.
1766 */
1767 };
1768 Connection module.
1770 A "connection" represents the appliance console connection plus the
1772 daemon connection. It hides the underlying representation (POSIX
1773 sockets, "virStreamPtr").
1774 Structure "lib/guestfs-internal.h:cached_feature"
1776 struct cached_feature {
1778 char *group;
1779 int result;
1780 };
1781 Cache of queried features.
1783 Used to cache the appliance features (see lib/available.c).
1785 Structure "lib/guestfs-internal.h:guestfs_h"
1787 struct guestfs_h {
1789 struct guestfs_h *next; /* Linked list of open handles. */
1790 enum state state; /* See the state machine diagram in guestfs(3)*/
1791 /* Lock acquired when entering any public guestfs_* function to
1793 * protect the handle.
1794 */
1795 pthread_mutex_t lock;
1796 /**** Configuration of the handle. ****/
1798 bool verbose; /* Debugging. */
1799 bool trace; /* Trace calls. */
1800 bool autosync; /* Autosync. */
1801 bool direct_mode; /* Direct mode. */
1802 bool recovery_proc; /* Create a recovery process. */
1803 bool enable_network; /* Enable the network. */
1804 bool selinux; /* selinux enabled? */
1805 bool pgroup; /* Create process group for children? */
1806 bool close_on_exit; /* Is this handle on the atexit list? */
1807 int smp; /* If > 1, -smp flag passed to hv. */
1809 int memsize; /* Size of RAM (megabytes). */
1810 char *path; /* Path to the appliance. */
1812 char *hv; /* Hypervisor (HV) binary. */
1813 char *append; /* Append to kernel command line. */
1814 struct hv_param *hv_params; /* Extra hv parameters. */
1816 char *program; /* Program name. */
1818 char *identifier; /* Handle identifier. */
1819 /* Array of drives added by add-drive* APIs.
1821 *
1822 * Before launch this list can be empty or contain some drives.
1823 *
1824 * During launch, a dummy slot may be added which represents the
1825 * slot taken up by the appliance drive.
1826 *
1827 * During shutdown, this list is deleted, so that each launch gets a
1828 * fresh set of drives (however callers: don't do this, create a new
1829 * handle each time).
1830 *
1831 * Always use ITER_DRIVES macro to iterate over this list!
1832 */
1833 struct drive **drives;
1834 size_t nr_drives;
1835 #define ITER_DRIVES(g,i,drv) \
1837 for (i = 0; i < (g)->nr_drives; ++i) \
1838 if (((drv) = (g)->drives[i]) != NULL)
1839 /* Backend. NB: Use guestfs_int_set_backend to change the backend. */
1841 char *backend; /* The full string, always non-NULL. */
1842 char *backend_arg; /* Pointer to the argument part. */
1843 const struct backend_ops *backend_ops;
1844 void *backend_data; /* Per-handle data. */
1845 char **backend_settings; /* Backend settings (can be NULL). */
1846 /**** Runtime information. ****/
1848 /* Temporary and cache directories. */
1849 /* The actual temporary directory - this is not created with the
1850 * handle, you have to call guestfs_int_lazy_make_tmpdir.
1851 */
1852 char *tmpdir;
1853 char *sockdir;
1854 /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
1855 char *env_tmpdir; /* $TMPDIR (NULL if not set) */
1856 char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/
1857 char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
1858 char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */
1859 /* Error handler, plus stack of old error handlers. */
1861 pthread_key_t error_data;
1862 /* Linked list of error_data structures allocated for this handle,
1864 * plus a mutex to protect the linked list.
1865 */
1866 pthread_mutex_t error_data_list_lock;
1867 struct error_data *error_data_list;
1868 /* Out of memory error handler. */
1870 guestfs_abort_cb abort_cb;
1871 /* Events. */
1873 struct event *events;
1874 size_t nr_events;
1875 /* Private data area. */
1877 struct hash_table *pda;
1878 struct pda_entry *pda_next;
1879 /* User cancelled transfer. Not signal-atomic, but it doesn't
1881 * matter for this case because we only care if it is != 0.
1882 */
1883 int user_cancel;
1884 struct timeval launch_t; /* The time that we called guestfs_launch. */
1886 /* Used by bindtests. */
1888 FILE *test_fp;
1889 /* Used to generate unique numbers, eg for temp files. To use this,
1891 * '++g->unique'. Note these are only unique per-handle, not
1892 * globally unique.
1893 */
1894 int unique;
1895 /*** Protocol. ***/
1897 struct connection *conn; /* Connection to appliance. */
1898 int msg_next_serial;
1899 #if HAVE_FUSE
1901 /**** Used by the mount-local APIs. ****/
1902 char *localmountpoint;
1903 struct fuse *fuse; /* FUSE handle. */
1904 int ml_dir_cache_timeout; /* Directory cache timeout. */
1905 Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
1906 int ml_read_only; /* If mounted read-only. */
1907 int ml_debug_calls; /* Extra debug info on each FUSE call. */
1908 #endif
1909 #ifdef HAVE_LIBVIRT_BACKEND
1911 /* Used by lib/libvirt-auth.c. */
1912 #define NR_CREDENTIAL_TYPES 9
1913 unsigned int nr_supported_credentials;
1914 int supported_credentials[NR_CREDENTIAL_TYPES];
1915 const char *saved_libvirt_uri; /* Doesn't need to be freed. */
1916 bool wrapper_warning_done;
1917 unsigned int nr_requested_credentials;
1918 virConnectCredentialPtr requested_credentials;
1919 #endif
1920 /* Cached features. */
1922 struct cached_feature *features;
1923 size_t nr_features;
1924 /* Used by lib/info.c. -1 = not tested or error; else 0 or 1. */
1926 int qemu_img_supports_U_option;
1927 };
1928 The libguestfs handle.
1930 Structure "lib/guestfs-internal.h:version"
1932 struct version {
1934 int v_major;
1935 int v_minor;
1936 int v_micro;
1937 };
1938 Used for storing major.minor.micro version numbers. See lib/version.c
1940 for more information.
1941 File lib/guid.c
1943 Function "lib/guid.c:guestfs_int_validate_guid"
1945 int
1947 guestfs_int_validate_guid (const char *str)
1948 Check whether a string supposed to contain a GUID actually contains it.
1950 It can recognize strings either as
1951 "{21EC2020-3AEA-1069-A2DD-08002B30309D}" or
1952 "21EC2020-3AEA-1069-A2DD-08002B30309D".
1953 File lib/handle.c
1955 This file deals with the "guestfs_h" handle, creating it, closing it,
1957 and initializing/setting/getting fields.
1958 Function "lib/handle.c:init_libguestfs"
1960 static void
1962 init_libguestfs (void)
1963 No initialization is required by libguestfs, but libvirt and libxml2
1965 require initialization if they might be called from multiple threads.
1966 Hence this constructor function which is called when libguestfs is
1967 first loaded.
1968 Function "lib/handle.c:shutdown_backend"
1970 static int
1972 shutdown_backend (guestfs_h *g, int check_for_errors)
1973 This function is the common path for shutting down the backend qemu
1975 process.
1976 "guestfs_shutdown" calls "shutdown_backend" with "check_for_errors=1".
1978 "guestfs_close" calls "shutdown_backend" with "check_for_errors=0".
1979 "check_for_errors" is a hint to the backend about whether we care about
1981 errors or not. In the libvirt case it can be used to optimize the
1982 shutdown for speed when we don't care.
1983 Function "lib/handle.c:close_handles"
1985 static void
1987 close_handles (void)
1988 Close all open handles (called from atexit(3)).
1990 Function "lib/handle.c:guestfs_int_get_backend_setting_bool"
1992 int
1994 guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)
1995 This is a convenience function, but we might consider exporting it as
1997 an API in future.
1998 File lib/info.c
2000 Function "lib/info.c:qemu_img_supports_U_option"
2002 static int
2004 qemu_img_supports_U_option (guestfs_h *g)
2005 Test if the qemu-img info command supports the "-U" option to disable
2007 locking. The result is memoized in the handle.
2008 Note this option was added in qemu 2.11. We can remove this test when
2010 we can assume everyone is using qemu >= 2.11.
2011 File lib/inspect-icon.c
2013 Function "lib/inspect-icon.c:guestfs_int_download_to_tmp"
2015 char *
2017 guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
2018 const char *extension,
2019 uint64_t max_size)
2020 Download a guest file to a local temporary file.
2022 The name of the temporary (downloaded) file is returned. The caller
2024 must free the pointer, but does not need to delete the temporary file.
2025 It will be deleted when the handle is closed.
2026 The name of the temporary file is randomly generated, but an extension
2028 can be specified using "extension" (or pass "NULL" for none).
2029 Refuse to download the guest file if it is larger than "max_size". On
2031 this and other errors, "NULL" is returned.
2032 File lib/launch-direct.c
2034 Implementation of the "direct" backend.
2036 For more details see "BACKENDS" in guestfs(3).
2038 Function "lib/launch-direct.c:add_drive_standard_params"
2040 static int
2042 add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
2043 struct qemuopts *qopts,
2044 size_t i, struct drive *drv)
2045 Add the standard elements of the "-drive" parameter.
2047 Function "lib/launch-direct.c:add_device_blocksize_params"
2049 static int
2051 add_device_blocksize_params (guestfs_h *g, struct qemuopts *qopts,
2052 struct drive *drv)
2053 Add the physical_block_size and logical_block_size elements of the
2055 "-device" parameter.
2056 File lib/launch-libvirt.c
2058 Function "lib/launch-libvirt.c:get_source_format_or_autodetect"
2060 static char *
2062 get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)
2063 Return "drv->src.format", but if it is "NULL", autodetect the format.
2065 libvirt has disabled the feature of detecting the disk format, unless
2067 the administrator sets "allow_disk_format_probing=1" in
2068 /etc/libvirt/qemu.conf. There is no way to detect if this option is
2069 set, so we have to do format detection here using "qemu-img" and pass
2070 that to libvirt.
2071 This can still be a security issue, so in most cases it is recommended
2073 the users pass the format to libguestfs which will faithfully pass that
2074 straight through to libvirt without doing autodetection.
2075 Caller must free the returned string. On error this function sets the
2077 error in the handle and returns "NULL".
2078 Function "lib/launch-libvirt.c:make_qcow2_overlay"
2080 static char *
2082 make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
2083 const char *format)
2084 Create a qcow2 format overlay, with the given "backing_drive" (file).
2086 The "format" parameter is the backing file format. The "format"
2087 parameter can be NULL, in this case the backing format will be
2088 determined automatically. This is used to create the appliance
2089 overlay, and also for read-only drives.
2090 File lib/launch.c
2092 This file implements "guestfs_launch" in guestfs(3).
2094 Most of the work is done by the backends (see "BACKEND" in guestfs(3)),
2096 which are implemented in lib/launch-direct.c, lib/launch-libvirt.c etc,
2097 so this file mostly passes calls through to the current backend.
2098 Function "lib/launch.c:guestfs_int_launch_send_progress"
2100 void
2102 guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)
2103 This function sends a launch progress message.
2105 Launching the appliance generates approximate progress messages.
2107 Currently these are defined as follows:
2108 0 / 12: launch clock starts
2110 3 / 12: appliance created
2111 6 / 12: detected that guest kernel started
2112 9 / 12: detected that /init script is running
2113 12 / 12: launch completed successfully
2114 Notes:
2116 1. This is not a documented ABI and the behaviour may be changed or
2118 removed in future.
2119 2. Messages are only sent if more than 5 seconds has elapsed since the
2121 launch clock started.
2122 3. There is a hack in lib/proto.c to make this work.
2124 Function "lib/launch.c:guestfs_int_timeval_diff"
2126 int64_t
2128 guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)
2129 Compute "y - x" and return the result in milliseconds.
2131 Approximately the same as this code:
2133 http://www.mpp.mpg.de/~huber/util/timevaldiff.c
2134 Function "lib/launch.c:guestfs_int_unblock_sigterm"
2136 void
2138 guestfs_int_unblock_sigterm (void)
2139 Unblock the "SIGTERM" signal. Call this after fork(2) so that the
2141 parent process can send "SIGTERM" to the child process in case
2142 "SIGTERM" is blocked. See https://bugzilla.redhat.com/1460338.
2143 Function "lib/launch.c:guestfs_impl_max_disks"
2145 int
2147 guestfs_impl_max_disks (guestfs_h *g)
2148 Returns the maximum number of disks allowed to be added to the backend
2150 (backend dependent).
2151 Function "lib/launch.c:guestfs_impl_wait_ready"
2153 int
2155 guestfs_impl_wait_ready (guestfs_h *g)
2156 Implementation of "guestfs_wait_ready" in guestfs(3). You had to call
2158 this function after launch in versions ≤ 1.0.70, but it is now an
2159 (almost) no-op.
2160 Function "lib/launch.c:guestfs_int_create_socketname"
2162 int
2164 guestfs_int_create_socketname (guestfs_h *g, const char *filename,
2165 char (*sockpath)[UNIX_PATH_MAX])
2166 Create the path for a socket with the selected filename in the tmpdir.
2168 Function "lib/launch.c:guestfs_int_register_backend"
2170 void
2172 guestfs_int_register_backend (const char *name, const struct backend_ops *ops)
2173 When the library is loaded, each backend calls this function to
2175 register itself in a global list.
2176 Function "lib/launch.c:guestfs_int_set_backend"
2178 int
2180 guestfs_int_set_backend (guestfs_h *g, const char *method)
2181 Implementation of "guestfs_set_backend" in guestfs(3).
2183 • Callers must ensure this is only called in the config state.
2185 • This shouldn't call "error" since it may be called early in handle
2187 initialization. It can return an error code however.
2188 File lib/private-data.c
2190 Implement a private data area where libguestfs C API users can attach
2192 arbitrary pieces of data to a "guestfs_h" handle.
2193 For more information see "PRIVATE DATA AREA" in guestfs(3).
2195 Language bindings do not generally expose this, largely because in non-
2197 C languages it is easy to associate data with handles in other ways
2198 (using hash tables or maps).
2199 Structure "lib/private-data.c:pda_entry"
2201 struct pda_entry {
2203 char *key; /* key */
2204 void *data; /* opaque user data pointer */
2205 };
2206 The private data area is internally stored as a gnulib hash table
2208 containing "pda_entry" structures.
2209 Note the private data area is allocated lazily, since the vast majority
2211 of callers will never use it. This means "g->pda" is likely to be
2212 "NULL".
2213 File lib/proto.c
2215 This is the code used to send and receive RPC messages and (for certain
2217 types of message) to perform file transfers. This code is driven from
2218 the generated actions (lib/actions-*.c). There are five different
2219 cases to consider:
2220 1. A non-daemon function (eg. "guestfs_set_verbose" in guestfs(3)).
2222 There is no RPC involved at all, it's all handled inside the
2223 library.
2224 2. A simple RPC (eg. "guestfs_mount" in guestfs(3)). We write the
2226 request, then read the reply. The sequence of calls is:
2227 guestfs_int_send
2229 guestfs_int_recv
2230 3. An RPC with "FileIn" parameters (eg. "guestfs_upload" in
2232 guestfs(3)). We write the request, then write the file(s), then
2233 read the reply. The sequence of calls is:
2234 guestfs_int_send
2236 guestfs_int_send_file (possibly multiple times)
2237 guestfs_int_recv
2238 4. An RPC with "FileOut" parameters (eg. "guestfs_download" in
2240 guestfs(3)). We write the request, then read the reply, then read
2241 the file(s). The sequence of calls is:
2242 guestfs_int_send
2244 guestfs_int_recv
2245 guestfs_int_recv_file (possibly multiple times)
2246 5. Both "FileIn" and "FileOut" parameters. There are no calls like
2248 this in the current API, but they would be implemented as a
2249 combination of cases 3 and 4.
2250 All read/write/etc operations are performed using the current
2252 connection module ("g->conn"). During operations the connection module
2253 transparently handles log messages that appear on the console.
2254 Function "lib/proto.c:child_cleanup"
2256 static void
2258 child_cleanup (guestfs_h *g)
2259 This is called if we detect EOF, ie. qemu died.
2261 Function "lib/proto.c:guestfs_int_progress_message_callback"
2263 void
2265 guestfs_int_progress_message_callback (guestfs_h *g,
2266 const guestfs_progress *message)
2267 Convenient wrapper to generate a progress message callback.
2269 Function "lib/proto.c:guestfs_int_log_message_callback"
2271 void
2273 guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)
2274 Connection modules call us back here when they get a log message.
2276 Function "lib/proto.c:check_daemon_socket"
2278 static ssize_t
2280 check_daemon_socket (guestfs_h *g)
2281 Before writing to the daemon socket, check the read side of the daemon
2283 socket for any of these conditions:
2284 error
2286 return -1
2287 daemon cancellation message
2289 return -2
2290 progress message
2292 handle it here
2293 end of input or appliance exited unexpectedly
2295 return 0
2296 anything else
2298 return 1
2299 Function "lib/proto.c:guestfs_int_send_file"
2301 int
2303 guestfs_int_send_file (guestfs_h *g, const char *filename)
2304 Send a file.
2306 Returns 0 on success, "-1" for error, "-2" if the daemon cancelled (we
2308 must read the error message).
2309 Function "lib/proto.c:send_file_data"
2311 static int
2313 send_file_data (guestfs_h *g, const char *buf, size_t len)
2314 Send a chunk of file data.
2316 Function "lib/proto.c:send_file_cancellation"
2318 static int
2320 send_file_cancellation (guestfs_h *g)
2321 Send a cancellation message.
2323 Function "lib/proto.c:send_file_complete"
2325 static int
2327 send_file_complete (guestfs_h *g)
2328 Send a file complete chunk.
2330 Function "lib/proto.c:recv_from_daemon"
2332 static int
2334 recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)
2335 This function reads a single message, file chunk, launch flag or
2337 cancellation flag from the daemon. If something was read, it returns
2338 0, otherwise "-1".
2339 Both "size_rtn" and "buf_rtn" must be passed by the caller as non-NULL.
2341 *size_rtn returns the size of the returned message or it may be
2343 "GUESTFS_LAUNCH_FLAG" or "GUESTFS_CANCEL_FLAG".
2344 *buf_rtn is returned containing the message (if any) or will be set to
2346 "NULL". *buf_rtn must be freed by the caller.
2347 This checks for EOF (appliance died) and passes that up through the
2349 child_cleanup function above.
2350 Log message, progress messages are handled transparently here.
2352 Function "lib/proto.c:guestfs_int_recv"
2354 int
2356 guestfs_int_recv (guestfs_h *g, const char *fn,
2357 guestfs_message_header *hdr,
2358 guestfs_message_error *err,
2359 xdrproc_t xdrp, char *ret)
2360 Receive a reply.
2362 Function "lib/proto.c:guestfs_int_recv_discard"
2364 int
2366 guestfs_int_recv_discard (guestfs_h *g, const char *fn)
2367 Same as "guestfs_int_recv", but it discards the reply message.
2369 Notes (XXX):
2371 • This returns an int, but all current callers ignore it.
2373 • The error string may end up being set twice on error paths.
2375 Function "lib/proto.c:guestfs_int_recv_file"
2377 int
2379 guestfs_int_recv_file (guestfs_h *g, const char *filename)
2380 Returns "-1" = error, 0 = EOF, ">0" = more data
2382 Function "lib/proto.c:receive_file_data"
2384 static ssize_t
2386 receive_file_data (guestfs_h *g, void **buf_r)
2387 Receive a chunk of file data.
2389 Returns "-1" = error, 0 = EOF, ">0" = more data
2391 File lib/qemu.c
2393 Functions to handle qemu versions and features.
2395 Function "lib/qemu.c:guestfs_int_test_qemu"
2397 struct qemu_data *
2399 guestfs_int_test_qemu (guestfs_h *g)
2400 Test that the qemu binary (or wrapper) runs, and do "qemu -help" and
2402 other commands so we can find out the version of qemu and what options
2403 this qemu supports.
2404 This caches the results in the cachedir so that as long as the qemu
2406 binary does not change, calling this is effectively free.
2407 Function "lib/qemu.c:cache_filename"
2409 static char *
2411 cache_filename (guestfs_h *g, const char *cachedir,
2412 const struct stat *statbuf, const char *suffix)
2413 Generate the filenames, for the stat file and the other cache files.
2415 By including the size and mtime in the filename we also ensure that the
2417 same user can use multiple versions of qemu without conflicts.
2418 Function "lib/qemu.c:parse_qemu_version"
2420 static void
2422 parse_qemu_version (guestfs_h *g, const char *qemu_help,
2423 struct version *qemu_version)
2424 Parse the first line of "qemu_help" into the major and minor version of
2426 qemu, but don't fail if parsing is not possible.
2427 Function "lib/qemu.c:parse_json"
2429 static void
2431 parse_json (guestfs_h *g, const char *json, json_t **treep)
2432 Parse the json output from QMP. But don't fail if parsing is not
2434 possible.
2435 Function "lib/qemu.c:parse_has_kvm"
2437 static void
2439 parse_has_kvm (guestfs_h *g, const char *json, bool *ret)
2440 Parse the json output from QMP query-kvm to find out if KVM is enabled
2442 on this machine. Don't fail if parsing is not possible, assume KVM is
2443 available.
2444 The JSON output looks like: {"return": {"enabled": true, "present":
2446 true}}
2447 Function "lib/qemu.c:generic_read_cache"
2449 static int
2451 generic_read_cache (guestfs_h *g, const char *filename, char **strp)
2452 Generic functions for reading and writing the cache files, used where
2454 we are just reading and writing plain text strings.
2455 Function "lib/qemu.c:generic_qmp_test"
2457 static int
2459 generic_qmp_test (guestfs_h *g, struct qemu_data *data,
2460 const char *qmp_command,
2461 char **outp)
2462 Run a generic QMP test on the QEMU binary.
2464 Function "lib/qemu.c:guestfs_int_qemu_version"
2466 struct version
2468 guestfs_int_qemu_version (guestfs_h *g, struct qemu_data *data)
2469 Return the parsed version of qemu.
2471 Function "lib/qemu.c:guestfs_int_qemu_supports"
2473 int
2475 guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data,
2476 const char *option)
2477 Test if option is supported by qemu command line (just by grepping the
2479 help text).
2480 Function "lib/qemu.c:guestfs_int_qemu_supports_device"
2482 int
2484 guestfs_int_qemu_supports_device (guestfs_h *g,
2485 const struct qemu_data *data,
2486 const char *device_name)
2487 Test if device is supported by qemu (currently just greps the "qemu
2489 -device ?" output).
2490 Function "lib/qemu.c:guestfs_int_qemu_mandatory_locking"
2492 int
2494 guestfs_int_qemu_mandatory_locking (guestfs_h *g,
2495 const struct qemu_data *data)
2496 Test if the qemu binary uses mandatory file locking, added in QEMU >=
2498 2.10 (but sometimes disabled).
2499 Function "lib/qemu.c:guestfs_int_qemu_escape_param"
2501 char *
2503 guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)
2504 Escape a qemu parameter.
2506 Every "," becomes ",,". The caller must free the returned string.
2508 XXX This functionality is now only used when constructing a qemu-img
2510 command in lib/create.c. We should extend the qemuopts library to
2511 cover this use case.
2512 Function "lib/qemu.c:guestfs_int_drive_source_qemu_param"
2514 char *
2516 guestfs_int_drive_source_qemu_param (guestfs_h *g,
2517 const struct drive_source *src)
2518 Useful function to format a drive + protocol for qemu.
2520 Note that the qemu parameter is the bit after "file=". It is not
2522 escaped here, but would usually be escaped if passed to qemu as part of
2523 a full -drive parameter (but not for qemu-img(1)).
2524 Function "lib/qemu.c:guestfs_int_discard_possible"
2526 bool
2528 guestfs_int_discard_possible (guestfs_h *g, struct drive *drv,
2529 const struct version *qemu_version)
2530 Test if discard is both supported by qemu AND possible with the
2532 underlying file or device. This returns 1 if discard is possible. It
2533 returns 0 if not possible and sets the error to the reason why.
2534 This function is called when the user set "discard == "enable"".
2536 Function "lib/qemu.c:guestfs_int_free_qemu_data"
2538 void
2540 guestfs_int_free_qemu_data (struct qemu_data *data)
2541 Free the "struct qemu_data".
2543 File lib/rescue.c
2545 Support for virt-rescue(1).
2547 File lib/stringsbuf.c
2549 An expandable NULL-terminated vector of strings (like "argv").
2551 Use the "DECLARE_STRINGSBUF" macro to declare the stringsbuf.
2553 Note: Don't confuse this with stringsbuf in the daemon which is a
2555 different type with different methods.
2556 Function "lib/stringsbuf.c:guestfs_int_add_string_nodup"
2558 void
2560 guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)
2561 Add a string to the end of the list.
2563 This doesn't call strdup(3) on the string, so the string itself is
2565 stored inside the vector.
2566 Function "lib/stringsbuf.c:guestfs_int_add_string"
2568 void
2570 guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)
2571 Add a string to the end of the list.
2573 This makes a copy of the string.
2575 Function "lib/stringsbuf.c:guestfs_int_add_sprintf"
2577 void
2579 guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
2580 const char *fs, ...)
2581 Add a string to the end of the list.
2583 Uses an sprintf-like format string when creating the string.
2585 Function "lib/stringsbuf.c:guestfs_int_end_stringsbuf"
2587 void
2589 guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)
2590 Finish the string buffer.
2592 This adds the terminating NULL to the end of the vector.
2594 Function "lib/stringsbuf.c:guestfs_int_free_stringsbuf"
2596 void
2598 guestfs_int_free_stringsbuf (struct stringsbuf *sb)
2599 Free the string buffer and the strings.
2601 File lib/tmpdirs.c
2603 Handle temporary directories.
2605 Function "lib/tmpdirs.c:set_abs_path"
2607 static int
2609 set_abs_path (guestfs_h *g, const char *ctxstr,
2610 const char *tmpdir, char **tmpdir_ret)
2611 We need to make all tmpdir paths absolute because lots of places in the
2613 code assume this. Do it at the time we set the path or read the
2614 environment variable (https://bugzilla.redhat.com/882417).
2615 The "ctxstr" parameter is a string displayed in error messages giving
2617 the context of the operation (eg. name of environment variable being
2618 used, or API function being called).
2619 Function "lib/tmpdirs.c:guestfs_impl_get_tmpdir"
2621 char *
2623 guestfs_impl_get_tmpdir (guestfs_h *g)
2624 Implements the "guestfs_get_tmpdir" API.
2626 Note this actually calculates the tmpdir, so it never returns "NULL".
2628 Function "lib/tmpdirs.c:guestfs_impl_get_cachedir"
2630 char *
2632 guestfs_impl_get_cachedir (guestfs_h *g)
2633 Implements the "guestfs_get_cachedir" API.
2635 Note this actually calculates the cachedir, so it never returns "NULL".
2637 Function "lib/tmpdirs.c:guestfs_impl_get_sockdir"
2639 char *
2641 guestfs_impl_get_sockdir (guestfs_h *g)
2642 Implements the "guestfs_get_sockdir" API.
2644 Note this actually calculates the sockdir, so it never returns "NULL".
2646 Function "lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir"
2648 int
2650 guestfs_int_lazy_make_tmpdir (guestfs_h *g)
2651 The "g->tmpdir" (per-handle temporary directory) is not created when
2653 the handle is created. Instead we create it lazily before the first
2654 time it is used, or during launch.
2655 Function "lib/tmpdirs.c:guestfs_int_make_temp_path"
2657 char *
2659 guestfs_int_make_temp_path (guestfs_h *g,
2660 const char *name, const char *extension)
2661 Generate unique temporary paths for temporary files.
2663 Returns a unique path or NULL on error.
2665 Function "lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir"
2667 char *
2669 guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)
2670 Create the supermin appliance directory under cachedir, if it does not
2672 exist.
2673 Sanity-check that the permissions on the cachedir are safe, in case it
2675 has been pre-created maliciously or tampered with.
2676 Returns the directory name which the caller must free.
2678 Function "lib/tmpdirs.c:guestfs_int_recursive_remove_dir"
2680 void
2682 guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)
2683 Recursively remove a temporary directory. If removal fails, just
2685 return (it's a temporary directory so it'll eventually be cleaned up by
2686 a temp cleaner).
2687 This is implemented using "rm -rf" because that's simpler and safer.
2689 File lib/umask.c
2691 Return current umask in a thread-safe way.
2693 glibc documents, but does not actually implement, a "getumask(3)" call.
2695 We use "Umask" from /proc/self/status for Linux ≥ 4.7. For older Linux
2697 and other Unix, this file implements an expensive but thread-safe way
2698 to get the current process's umask.
2699 Thanks to: Josh Stone, Jiri Jaburek, Eric Blake.
2701 Function "lib/umask.c:guestfs_int_getumask"
2703 int
2705 guestfs_int_getumask (guestfs_h *g)
2706 Returns the current process's umask. On failure, returns "-1" and sets
2708 the error in the guestfs handle.
2709 Function "lib/umask.c:get_umask_from_proc"
2711 static int
2713 get_umask_from_proc (guestfs_h *g)
2714 For Linux ≥ 4.7 get the umask from /proc/self/status.
2716 On failure this returns "-1". However if we could not open the /proc
2718 file or find the "Umask" entry in it, return "-2" which causes the
2719 fallback path to run.
2720 Function "lib/umask.c:get_umask_from_fork"
2722 static int
2724 get_umask_from_fork (guestfs_h *g)
2725 Fallback method of getting the umask using fork.
2727 File lib/unit-tests.c
2729 Unit tests of internal functions.
2731 These tests may use a libguestfs handle, but must not launch the
2733 handle. Also, avoid long-running tests.
2734 Function "lib/unit-tests.c:test_split"
2736 static void
2738 test_split (void)
2739 Test "guestfs_int_split_string".
2741 Function "lib/unit-tests.c:test_concat"
2743 static void
2745 test_concat (void)
2746 Test "guestfs_int_concat_strings".
2748 Function "lib/unit-tests.c:test_join"
2750 static void
2752 test_join (void)
2753 Test "guestfs_int_join_strings".
2755 Function "lib/unit-tests.c:test_validate_guid"
2757 static void
2759 test_validate_guid (void)
2760 Test "guestfs_int_validate_guid".
2762 Function "lib/unit-tests.c:test_drive_name"
2764 static void
2766 test_drive_name (void)
2767 Test "guestfs_int_drive_name".
2769 Function "lib/unit-tests.c:test_drive_index"
2771 static void
2773 test_drive_index (void)
2774 Test "guestfs_int_drive_index".
2776 Function "lib/unit-tests.c:test_getumask"
2778 static void
2780 test_getumask (void)
2781 Test "guestfs_int_getumask".
2783 Function "lib/unit-tests.c:test_command"
2785 static void
2787 test_command (void)
2788 Test "guestfs_int_new_command" etc.
2790 XXX These tests could be made much more thorough. So far we simply
2792 test that it's not obviously broken.
2793 Function "lib/unit-tests.c:test_qemu_escape_param"
2795 static void
2797 test_qemu_escape_param (void)
2798 Test "guestfs_int_qemu_escape_param"
2800 XXX I wanted to make this test run qemu, passing some parameters which
2802 need to be escaped, but I cannot think of a way to do that without
2803 launching a VM.
2804 Function "lib/unit-tests.c:test_timeval_diff"
2806 static void
2808 test_timeval_diff (void)
2809 Test "guestfs_int_timeval_diff".
2811 File lib/version.c
2813 This file provides simple version number management.
2815 Function "lib/version.c:guestfs_int_version_from_x_y"
2817 int
2819 guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)
2820 Parses a version from a string, looking for a "X.Y" pattern.
2822 Returns "-1" on failure (like failed integer parsing), 0 on missing
2824 match, and 1 on match and successful parsing. "v" is changed only on
2825 successful match.
2826 Function "lib/version.c:guestfs_int_version_from_x_y_re"
2828 int
2830 guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
2831 const char *str, const pcre2_code *re)
2832 Parses a version from a string, using the specified "re" as regular
2834 expression which must provide (at least) two matches.
2835 Returns "-1" on failure (like failed integer parsing), 0 on missing
2837 match, and 1 on match and successful parsing. "v" is changed only on
2838 successful match.
2839 Function "lib/version.c:guestfs_int_version_from_x_y_or_x"
2841 int
2843 guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
2844 const char *str)
2845 Parses a version from a string, either looking for a "X.Y" pattern or
2847 considering it as whole integer.
2848 Returns "-1" on failure (like failed integer parsing), 0 on missing
2850 match, and 1 on match and successful parsing. "v" is changed only on
2851 successful match.
2852 Function "lib/version.c:guestfs_int_parse_unsigned_int"
2854 int
2856 guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)
2857 Parse small, unsigned ints, as used in version numbers.
2859 This will fail with an error if trailing characters are found after the
2861 integer.
2862 Returns ≥ 0 on success, or "-1" on failure.
2864 File lib/wait.c
2866 Function "lib/wait.c:guestfs_int_waitpid"
2868 int
2870 guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)
2871 A safe version of waitpid(3) which retries if "EINTR" is returned.
2873 Note: this only needs to be used in the library, or in programs that
2875 install a non-restartable "SIGCHLD" handler (which is not the case for
2876 any current libguestfs virt tools).
2877 If the main program installs a SIGCHLD handler and sets it to be non-
2879 restartable, then what can happen is the library is waiting in a wait
2880 syscall, the child exits, "SIGCHLD" is sent to the process, and the
2881 wait syscall returns "EINTR". Since the library cannot control the
2882 signal handler, we have to instead restart the wait syscall, which is
2883 the purpose of this wrapper.
2884 Function "lib/wait.c:guestfs_int_waitpid_noerror"
2886 void
2888 guestfs_int_waitpid_noerror (pid_t pid)
2889 Like "guestfs_int_waitpid", but ignore errors.
2891 Function "lib/wait.c:guestfs_int_wait4"
2893 int
2895 guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
2896 struct rusage *rusage, const char *errmsg)
2897 A safe version of wait4(2) which retries if "EINTR" is returned.
2899 File lib/whole-file.c
2901 Function "lib/whole-file.c:guestfs_int_read_whole_file"
2903 int
2905 guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
2906 char **data_r, size_t *size_r)
2907 Read the whole file "filename" into a memory buffer.
2909 The memory buffer is initialized and returned in "data_r". The size of
2911 the file in bytes is returned in "size_r". The return buffer must be
2912 freed by the caller.
2913 On error this sets the error in the handle and returns "-1".
2915 For the convenience of callers, the returned buffer is NUL-terminated
2917 (the NUL is not included in the size).
2918 The file must be a regular, local, trusted file. In particular, do not
2920 use this function to read files that might be under control of an
2921 untrusted user since that will lead to a denial-of-service attack.
2922 Subdirectory common/edit
2924 File common/edit/file-edit.c
2925 This file implements common file editing in a range of utilities
2927 including guestfish(1), virt-edit(1), virt-customize(1) and
2928 virt-builder(1).
2929 It contains the code for both interactive-(editor-)based editing and
2931 non-interactive editing using Perl snippets.
2932 Function "common/edit/file-edit.c:edit_file_editor"
2934 int
2936 edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
2937 const char *backup_extension, int verbose)
2938 Edit "filename" using the specified "editor" application.
2940 If "backup_extension" is not null, then a copy of "filename" is saved
2942 with "backup_extension" appended to its file name.
2943 If "editor" is null, then the $EDITOR environment variable will be
2945 queried for the editor application, leaving "vi" as fallback if not
2946 set.
2947 Returns "-1" for failure, 0 on success, 1 if the editor did not change
2949 the file (e.g. the user closed the editor without saving).
2950 Function "common/edit/file-edit.c:edit_file_perl"
2952 int
2954 edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
2955 const char *backup_extension, int verbose)
2956 Edit "filename" running the specified "perl_expr" using Perl.
2958 If "backup_extension" is not null, then a copy of "filename" is saved
2960 with "backup_extension" appended to its file name.
2961 Returns "-1" for failure, 0 on success.
2963 Subdirectory common/options
2965 File common/options/config.c
2966 This file parses the guestfish configuration file, usually
2968 ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.
2969 Note that "parse_config" is called very early, before command line
2971 parsing, before the "verbose" flag has been set, even before the global
2972 handle "g" is opened.
2973 File common/options/decrypt.c
2975 This file implements the decryption of disk images, usually done before
2977 mounting their partitions.
2978 Function "common/options/decrypt.c:make_mapname"
2980 static char *
2982 make_mapname (const char *device)
2983 Make a LUKS map name from the partition or logical volume name, eg.
2985 "/dev/vda2" => "cryptvda2", or "/dev/vg-ssd/lv-root7" =>
2986 "cryptvgssdlvroot7". Note that, in logical volume device names,
2987 c_isalnum() eliminates the "/" separator from between the VG and the
2988 LV, so this mapping is not unique; but for our purposes, it will do.
2989 Function "common/options/decrypt.c:inspect_do_decrypt"
2991 void
2993 inspect_do_decrypt (guestfs_h *g, struct key_store *ks)
2994 Simple implementation of decryption: look for any encrypted partitions
2996 and decrypt them, then rescan for VGs.
2997 File common/options/display-options.c
2999 This file contains common code used to implement --short-options and
3001 --long-options in C virt tools. (The equivalent for OCaml virt tools
3002 is implemented by common/mltools/getopt.ml).
3003 These "hidden" options are used to implement bash tab completion.
3005 Function "common/options/display-options.c:display_short_options"
3007 void
3009 display_short_options (const char *format)
3010 Implements the internal "tool --short-options" flag, which just lists
3012 out the short options available. Used by bash completion.
3013 Function "common/options/display-options.c:display_long_options"
3015 void
3017 display_long_options (const struct option *long_options)
3018 Implements the internal "tool --long-options" flag, which just lists
3020 out the long options available. Used by bash completion.
3021 File common/options/domain.c
3023 Implements the guestfish (and other tools) -d option.
3025 Function "common/options/domain.c:add_libvirt_drives"
3027 int
3029 add_libvirt_drives (guestfs_h *g, const char *guest)
3030 This function is called when a user invokes "guestfish -d guest".
3032 Returns the number of drives added ("> 0"), or "-1" for failure.
3034 File common/options/inspect.c
3036 This file implements inspecting the guest and mounting the filesystems
3038 found in the right places. It is used by the guestfish(1) -i option
3039 and some utilities such as virt-cat(1).
3040 Function "common/options/inspect.c:inspect_mount_handle"
3042 void
3044 inspect_mount_handle (guestfs_h *g, struct key_store *ks)
3045 This function implements the -i option.
3047 Function "common/options/inspect.c:print_inspect_prompt"
3049 void
3051 print_inspect_prompt (void)
3052 This function is called only if "inspect_mount_root" was called, and
3054 only after we've printed the prompt in interactive mode.
3055 File common/options/keys.c
3057 Function "common/options/keys.c:read_key"
3059 char *
3061 read_key (const char *param)
3062 Read a passphrase ('Key') from /dev/tty with echo off.
3064 The caller (fish/cmds.c) will call free on the string afterwards.
3066 Based on the code in cryptsetup file lib/utils.c.
3067 File common/options/options.c
3069 This file contains common options parsing code used by guestfish and
3071 many other tools which share a common options syntax.
3072 For example, guestfish, virt-cat, virt-ls etc all support the -a
3074 option, and that is handled in all of those tools using a macro
3075 "OPTION_a" defined in fish/options.h.
3076 There are a lot of common global variables used, "drvs" accumulates the
3078 list of drives, "verbose" for the -v flag, and many more.
3079 Function "common/options/options.c:option_a"
3081 void
3083 option_a (const char *arg, const char *format, int blocksize,
3084 struct drv **drvsp)
3085 Handle the guestfish -a option on the command line.
3087 Function "common/options/options.c:option_d"
3089 void
3091 option_d (const char *arg, struct drv **drvsp)
3092 Handle the -d option when passed on the command line.
3094 Function "common/options/options.c:display_mountpoints_on_failure"
3096 static void
3098 display_mountpoints_on_failure (const char *mp_device,
3099 const char *user_supplied_options)
3100 If the -m option fails on any command, display a useful error message
3102 listing the mountpoints.
3103 File common/options/uri.c
3105 This file implements URI parsing for the -a option, in many utilities
3107 including guestfish(1), virt-cat(1), virt-builder(1),
3108 virt-customize(1), etc.
3109 Subdirectory common/parallel
3111 File common/parallel/domains.c
3112 This file is used by "virt-df" and some of the other tools when they
3114 are implicitly asked to operate over all libvirt domains (VMs), for
3115 example when "virt-df" is called without specifying any particular disk
3116 image.
3117 It hides the complexity of querying the list of domains from libvirt.
3119 Function "common/parallel/domains.c:free_domains"
3121 void
3123 free_domains (void)
3124 Frees up everything allocated by "get_all_libvirt_domains".
3126 Function "common/parallel/domains.c:get_all_libvirt_domains"
3128 void
3130 get_all_libvirt_domains (const char *libvirt_uri)
3131 Read all libguest guests into the global variables "domains" and
3133 "nr_domains". The guests are ordered by name. This exits on any
3134 error.
3135 File common/parallel/estimate-max-threads.c
3137 Function "common/parallel/estimate-max-threads.c:estimate_max_threads"
3139 size_t
3141 estimate_max_threads (void)
3142 This function uses the output of "free -m" to estimate how many
3144 libguestfs appliances could be safely started in parallel. Note that
3145 it always returns ≥ 1.
3146 Function "common/parallel/estimate-max-threads.c:read_line_from"
3148 static char *
3150 read_line_from (const char *cmd)
3151 Run external command and read the first line of output.
3153 File common/parallel/parallel.c
3155 This file is used by "virt-df" and some of the other tools when they
3157 need to run multiple parallel libguestfs instances to operate on a
3158 large number of libvirt domains efficiently.
3159 It implements a multithreaded work queue. In addition it reorders the
3161 output so the output still appears in the same order as the input (ie.
3162 still ordered alphabetically).
3163 Function "common/parallel/parallel.c:start_threads"
3165 int
3167 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
3168 Run the threads and work through the global list of libvirt domains.
3170 "option_P" is whatever the user passed in the -P option, or 0 if the
3172 user didn't use the -P option (in which case the number of threads is
3173 chosen heuristically).
3174 "options_handle" (which may be "NULL") is the global guestfs handle
3176 created by the options mini-library.
3177 The work function ("work") should do the work (inspecting the domain,
3179 etc.) on domain index "i". However it must not print out any result
3180 directly. Instead it prints anything it needs to the supplied "FILE
3181 *". The work function should return 0 on success or "-1" on error.
3182 The "start_threads" function returns 0 if all work items completed
3184 successfully, or "-1" if there was an error.
3185 Subdirectory common/progress
3187 File common/progress/progress.c
3188 This file implements the progress bar in guestfish(1), virt-resize(1)
3190 and virt-sparsify(1).
3191 Function "common/progress/progress.c:progress_bar_init"
3193 struct progress_bar *
3195 progress_bar_init (unsigned flags)
3196 Initialize a progress bar struct.
3198 It is intended that you can reuse the same struct for multiple commands
3200 (but only in a single thread). Call "progress_bar_reset" before each
3201 new command.
3202 Function "common/progress/progress.c:progress_bar_free"
3204 void
3206 progress_bar_free (struct progress_bar *bar)
3207 Free a progress bar struct.
3209 Function "common/progress/progress.c:progress_bar_reset"
3211 void
3213 progress_bar_reset (struct progress_bar *bar)
3214 This function should be called just before you issue any command.
3216 Function "common/progress/progress.c:estimate_remaining_time"
3218 static double
3220 estimate_remaining_time (struct progress_bar *bar, double ratio)
3221 Return remaining time estimate (in seconds) for current call.
3223 This returns the running mean estimate of remaining time, but if the
3225 latest estimate of total time is greater than two s.d.'s from the
3226 running mean then we don't print anything because we're not confident
3227 that the estimate is meaningful. (Returned value is <0.0 when nothing
3228 should be printed).
3229 Function "common/progress/progress.c:progress_bar_set"
3231 void
3233 progress_bar_set (struct progress_bar *bar,
3234 uint64_t position, uint64_t total)
3235 Set the position of the progress bar.
3237 This should be called from a "GUESTFS_EVENT_PROGRESS" event callback.
3239 Subdirectory common/qemuopts
3241 File common/qemuopts/qemuopts-tests.c
3242 Unit tests of internal functions.
3244 These tests may use a libguestfs handle, but must not launch the
3246 handle. Also, avoid long-running tests.
3247 File common/qemuopts/qemuopts.c
3249 Mini-library for writing qemu command lines and qemu config files.
3251 There are some shortcomings with the model used for qemu options which
3253 aren't clear until you try to convert options into a configuration
3254 file. However if we attempted to model the options in more detail then
3255 this library would be both very difficult to use and incompatible with
3256 older versions of qemu. Hopefully the current model is a decent
3257 compromise.
3258 For reference here are the problems:
3260 • There's inconsistency in qemu between options and config file, eg.
3262 "-smp 4" becomes:
3263 [smp-opts]
3265 cpus = "4"
3266 • Similar to the previous point, you can write either "-smp 4" or
3268 "-smp cpus=4" (although this won't work in very old qemu). When
3269 generating a config file you need to know the implicit key name.
3270 • In "-opt key=value,..." the "key" is really a tree/array specifier.
3272 The way this works is complicated but hinted at here:
3273 http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
3274 • Some options are syntactic sugar. eg. "-kernel foo" is sugar for
3276 "-machine kernel=foo".
3277 Function "common/qemuopts/qemuopts.c:qemuopts_create"
3279 struct qemuopts *
3281 qemuopts_create (void)
3282 Create an empty list of qemu options.
3284 The caller must eventually free the list by calling "qemuopts_free".
3286 Returns "NULL" on error, setting "errno".
3288 Function "common/qemuopts/qemuopts.c:qemuopts_free"
3290 void
3292 qemuopts_free (struct qemuopts *qopts)
3293 Free the list of qemu options.
3295 Function "common/qemuopts/qemuopts.c:qemuopts_add_flag"
3297 int
3299 qemuopts_add_flag (struct qemuopts *qopts, const char *flag)
3300 Add a command line flag which has no argument. eg:
3302 qemuopts_add_flag (qopts, "-no-user-config");
3304 Returns 0 on success. Returns "-1" on error, setting "errno".
3306 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg"
3308 int
3310 qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)
3311 Add a command line flag which has a single argument. eg:
3313 qemuopts_add_arg (qopts, "-m", "1024");
3315 Don't use this if the argument is a comma-separated list, since quoting
3317 will not be done properly. See "qemuopts_add_arg_list".
3318 Returns 0 on success. Returns "-1" on error, setting "errno".
3320 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_format"
3322 int
3324 qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
3325 const char *fs, ...)
3326 Add a command line flag which has a single formatted argument. eg:
3328 qemuopts_add_arg_format (qopts, "-m", "%d", 1024);
3330 Don't use this if the argument is a comma-separated list, since quoting
3332 will not be done properly. See "qemuopts_add_arg_list".
3333 Returns 0 on success. Returns "-1" on error, setting "errno".
3335 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote"
3337 int
3339 qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
3340 const char *value)
3341 This is like "qemuopts_add_arg" except that no quoting is done on the
3343 value.
3344 For "qemuopts_to_script" and "qemuopts_to_channel", this means that
3346 neither shell quoting nor qemu comma quoting is done on the value.
3347 For "qemuopts_to_argv" this means that qemu comma quoting is not done.
3349 "qemuopts_to_config*" will fail.
3351 You should use this with great care.
3353 Function "common/qemuopts/qemuopts.c:qemuopts_start_arg_list"
3355 int
3357 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
3358 Start an argument that takes a comma-separated list of fields.
3360 Typical usage is like this (with error handling omitted):
3362 qemuopts_start_arg_list (qopts, "-drive");
3364 qemuopts_append_arg_list (qopts, "file=foo");
3365 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
3366 qemuopts_end_arg_list (qopts);
3367 which would construct "-drive file=foo,if=ide"
3369 See also "qemuopts_add_arg_list" for a way to do simple cases in one
3371 call.
3372 Returns 0 on success. Returns "-1" on error, setting "errno".
3374 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_list"
3376 int
3378 qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
3379 const char *elem0, ...)
3380 Add a command line flag which has a list of arguments. eg:
3382 qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);
3384 This is turned into a comma-separated list, like: "-drive
3386 file=foo,if=ide". Note that this handles qemu quoting properly, so
3387 individual elements may contain commas and this will do the right
3388 thing.
3389 Returns 0 on success. Returns "-1" on error, setting "errno".
3391 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary"
3393 int
3395 qemuopts_set_binary (struct qemuopts *qopts, const char *binary)
3396 Set the qemu binary name.
3398 Returns 0 on success. Returns "-1" on error, setting "errno".
3400 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch"
3402 int
3404 qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)
3405 Set the qemu binary name to "qemu-system-[arch]".
3407 As a special case if "arch" is "NULL", the binary is set to the KVM
3409 binary for the current host architecture:
3410 qemuopts_set_binary_by_arch (qopts, NULL);
3412 Returns 0 on success. Returns "-1" on error, setting "errno".
3414 Function "common/qemuopts/qemuopts.c:qemuopts_to_script"
3416 int
3418 qemuopts_to_script (struct qemuopts *qopts, const char *filename)
3419 Write the qemu options to a script.
3421 "qemuopts_set_binary*" must be called first.
3423 The script file will start with "#!/bin/sh" and will be chmod to mode
3425 0755.
3426 Returns 0 on success. Returns "-1" on error, setting "errno".
3428 Function "common/qemuopts/qemuopts.c:shell_quote"
3430 static void
3432 shell_quote (const char *str, FILE *fp)
3433 Print "str" to "fp", shell-quoting it if necessary.
3435 Function "common/qemuopts/qemuopts.c:shell_and_comma_quote"
3437 static void
3439 shell_and_comma_quote (const char *str, FILE *fp)
3440 Print "str" to "fp" doing both shell and qemu comma quoting.
3442 Function "common/qemuopts/qemuopts.c:qemuopts_to_channel"
3444 int
3446 qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)
3447 Write the qemu options to a "FILE *fp".
3449 "qemuopts_set_binary*" must be called first.
3451 Only the qemu command line is written. The caller may need to add
3453 "#!/bin/sh" and may need to chmod the resulting file to 0755.
3454 Returns 0 on success. Returns "-1" on error, setting "errno".
3456 Function "common/qemuopts/qemuopts.c:qemuopts_to_argv"
3458 char **
3460 qemuopts_to_argv (struct qemuopts *qopts)
3461 Return a NULL-terminated argument list, of the kind that can be passed
3463 directly to execv(3).
3464 "qemuopts_set_binary*" must be called first. It will be returned as
3466 "argv[0]" in the returned list.
3467 The list of strings and the strings themselves must be freed by the
3469 caller.
3470 Returns "NULL" on error, setting "errno".
3472 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_file"
3474 int
3476 qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)
3477 Write the qemu options to a qemu config file, suitable for reading in
3479 using "qemu -readconfig filename".
3480 Note that qemu config files have limitations on content and quoting, so
3482 not all qemuopts structs can be written (this function returns an error
3483 in these cases). For more information see
3484 https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html
3485 https://bugs.launchpad.net/qemu/+bug/1686364
3486 Also, command line argument names and config file sections sometimes
3488 have different names. For example the equivalent of "-m 1024" is:
3489 [memory]
3491 size = "1024"
3492 This code does not attempt to convert between the two forms. You just
3494 need to know how to do that yourself.
3495 Returns 0 on success. Returns "-1" on error, setting "errno".
3497 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_channel"
3499 int
3501 qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)
3502 Same as "qemuopts_to_config_file", but this writes to a "FILE *fp".
3504 Subdirectory common/utils
3506 File common/utils/cleanups.c
3507 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3509 They are implemented using the "__attribute__((cleanup))" feature of
3510 gcc and clang. Typical usage is:
3511 fn ()
3513 {
3514 CLEANUP_FREE char *str = NULL;
3515 str = safe_asprintf (g, "foo");
3516 // str is freed automatically when the function returns
3517 }
3518 There are a few catches to be aware of with the cleanup mechanism:
3520 • If a cleanup variable is not initialized, then you can end up
3522 calling free(3) with an undefined value, resulting in the program
3523 crashing. For this reason, you should usually initialize every
3524 cleanup variable with something, eg. "NULL"
3525 • Don't mark variables holding return values as cleanup variables.
3527 • The "main()" function shouldn't use cleanup variables since it is
3529 normally exited by calling exit(3), and that doesn't call the
3530 cleanup handlers.
3531 The functions in this file are used internally by the "CLEANUP_*"
3533 macros. Don't call them directly.
3534 File common/utils/gnulib-cleanups.c
3536 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3538 They are implemented using the "__attribute__((cleanup))" feature of
3539 gcc and clang. Typical usage is:
3540 fn ()
3542 {
3543 CLEANUP_FREE char *str = NULL;
3544 str = safe_asprintf (g, "foo");
3545 // str is freed automatically when the function returns
3546 }
3547 There are a few catches to be aware of with the cleanup mechanism:
3549 • If a cleanup variable is not initialized, then you can end up
3551 calling free(3) with an undefined value, resulting in the program
3552 crashing. For this reason, you should usually initialize every
3553 cleanup variable with something, eg. "NULL"
3554 • Don't mark variables holding return values as cleanup variables.
3556 • The "main()" function shouldn't use cleanup variables since it is
3558 normally exited by calling exit(3), and that doesn't call the
3559 cleanup handlers.
3560 The functions in this file are used internally by the "CLEANUP_*"
3562 macros. Don't call them directly.
3563 File common/utils/guestfs-utils.h
3565 This header file is included in all "frontend" parts of libguestfs,
3567 namely the library, non-C language bindings, virt tools and tests.
3568 The daemon does not use this header. If you need a place to put
3570 something shared with absolutely everything including the daemon, put
3571 it in lib/guestfs-internal-all.h
3572 If a definition is only needed by a single component of libguestfs (eg.
3574 just the library, or just a single virt tool) then it should not be
3575 here!
3576 File common/utils/libxml2-writer-macros.h
3578 These macros make it easier to write XML. To use them correctly you
3580 must be aware of these assumptions:
3581 • The "xmlTextWriterPtr" is called "xo". It is used implicitly by
3583 all the macros.
3584 • On failure, a function called "xml_error" is called which you must
3586 define (usually as a macro). You must use "CLEANUP_*" macros in
3587 your functions if you want correct cleanup of local variables along
3588 the error path.
3589 • All the "bad" casting is hidden inside the macros.
3591 Definition "common/utils/libxml2-writer-macros.h:start_element"
3593 #define start_element
3595 To define an XML element use:
3597 start_element ("name") {
3599 ...
3600 } end_element ();
3601 which produces "<name>...</name>"
3603 Definition "common/utils/libxml2-writer-macros.h:empty_element"
3605 #define empty_element
3607 To define an empty element:
3609 empty_element ("name");
3611 which produces "<name/>"
3613 Definition "common/utils/libxml2-writer-macros.h:single_element"
3615 #define single_element
3617 To define a single element with no attributes containing some text:
3619 single_element ("name", text);
3621 which produces "<name>text</name>"
3623 Definition "common/utils/libxml2-writer-macros.h:single_element_format"
3625 #define single_element_format
3627 To define a single element with no attributes containing some text
3629 using a format string:
3630 single_element_format ("cores", "%d", nr_cores);
3632 which produces "<cores>4</cores>"
3634 Definition "common/utils/libxml2-writer-macros.h:attribute"
3636 #define attribute
3638 To define an XML element with attributes, use:
3640 start_element ("name") {
3642 attribute ("foo", "bar");
3643 attribute_format ("count", "%d", count);
3644 ...
3645 } end_element ();
3646 which produces "<name foo="bar" count="123">...</name>"
3648 Definition "common/utils/libxml2-writer-macros.h:attribute_ns"
3650 #define attribute_ns
3652 "attribute_ns (prefix, key, namespace_uri, value)" defines a namespaced
3654 attribute.
3655 Definition "common/utils/libxml2-writer-macros.h:string"
3657 #define string
3659 To define a verbatim string, use:
3661 string ("hello");
3663 Definition "common/utils/libxml2-writer-macros.h:string_format"
3665 #define string_format
3667 To define a verbatim string using a format string, use:
3669 string ("%s, world", greeting);
3671 Definition "common/utils/libxml2-writer-macros.h:base64"
3673 #define base64
3675 To write a string encoded as base64:
3677 base64 (data, size);
3679 Definition "common/utils/libxml2-writer-macros.h:comment"
3681 #define comment
3683 To define a comment in the XML, use:
3685 comment ("number of items = %d", nr_items);
3687 File common/utils/stringlists-utils.c
3689 Utility functions used by the library, tools and language bindings.
3691 These functions must not call internal library functions such as
3693 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3694 Function "common/utils/stringlists-utils.c:guestfs_int_split_string"
3696 char **
3698 guestfs_int_split_string (char sep, const char *str)
3699 Split string at separator character "sep", returning the list of
3701 strings. Returns "NULL" on memory allocation failure.
3702 Note (assuming "sep" is ":"):
3704 "str == NULL"
3706 aborts
3707 "str == """
3709 returns "[]"
3710 "str == "abc""
3712 returns "["abc"]"
3713 "str == ":""
3715 returns "["", ""]"
3716 File common/utils/utils.c
3718 Utility functions used by the library, tools and language bindings.
3720 These functions must not call internal library functions such as
3722 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3723 Function "common/utils/utils.c:guestfs_int_replace_string"
3725 char *
3727 guestfs_int_replace_string (const char *str, const char *s1, const char *s2)
3728 Replace every instance of "s1" appearing in "str" with "s2". A newly
3730 allocated string is returned which must be freed by the caller. If
3731 allocation fails this can return "NULL".
3732 For example:
3734 replace_string ("abcabb", "ab", "a");
3736 would return "acab".
3738 Function "common/utils/utils.c:guestfs_int_exit_status_to_string"
3740 char *
3742 guestfs_int_exit_status_to_string (int status, const char *cmd_name,
3743 char *buffer, size_t buflen)
3744 Translate a wait/system exit status into a printable string.
3746 Function "common/utils/utils.c:guestfs_int_random_string"
3748 int
3750 guestfs_int_random_string (char *ret, size_t len)
3751 Return a random string of characters.
3753 Notes:
3755 • The "ret" buffer must have length "len+1" in order to store the
3757 final "\0" character.
3758 • There is about 5 bits of randomness per output character (so about
3760 "5*len" bits of randomness in the resulting string).
3761 Function "common/utils/utils.c:guestfs_int_drive_name"
3763 char *
3765 guestfs_int_drive_name (size_t index, char *ret)
3766 This turns a drive index (eg. 27) into a drive name (eg. "ab").
3768 Drive indexes count from 0. The return buffer has to be large enough
3770 for the resulting string, and the returned pointer points to the *end*
3771 of the string.
3772 https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
3774 Function "common/utils/utils.c:guestfs_int_drive_index"
3776 ssize_t
3778 guestfs_int_drive_index (const char *name)
3779 The opposite of "guestfs_int_drive_name". Take a string like "ab" and
3781 return the index (eg 27).
3782 Note that you must remove any prefix such as "hd", "sd" etc, or any
3784 partition number before calling the function.
3785 Function "common/utils/utils.c:guestfs_int_is_true"
3787 int
3789 guestfs_int_is_true (const char *str)
3790 Similar to "Tcl_GetBoolean".
3792 Function "common/utils/utils.c:guestfs_int_string_is_valid"
3794 bool
3796 guestfs_int_string_is_valid (const char *str,
3797 size_t min_length, size_t max_length,
3798 int flags, const char *extra)
3799 Check a string for validity, that it contains only certain characters,
3801 and minimum and maximum length. This function is usually wrapped in a
3802 VALID_* macro, see lib/drives.c for an example.
3803 "str" is the string to check.
3805 "min_length" and "max_length" are the minimum and maximum length
3807 checks. 0 means no check.
3808 The flags control:
3810 "VALID_FLAG_ALPHA"
3812 7-bit ASCII-only alphabetic characters are permitted.
3813 "VALID_FLAG_DIGIT"
3815 7-bit ASCII-only digits are permitted.
3816 "extra" is a set of extra characters permitted, in addition to
3818 alphabetic and/or digits. ("extra = NULL" for no extra).
3819 Returns boolean "true" if the string is valid (passes all the tests),
3821 or "false" if not.
3822 Function "common/utils/utils.c:guestfs_int_fadvise_normal"
3824 void
3826 guestfs_int_fadvise_normal (int fd)
3827 Hint that we will read or write the file descriptor normally.
3829 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3831 and sets the per-file number of readahead pages to equal the block
3832 device readahead setting.
3833 It's OK to call this on a non-file since we ignore failure as it is
3835 only a hint.
3836 Function "common/utils/utils.c:guestfs_int_fadvise_sequential"
3838 void
3840 guestfs_int_fadvise_sequential (int fd)
3841 Hint that we will read or write the file descriptor sequentially.
3843 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3845 and sets the per-file number of readahead pages to twice the block
3846 device readahead setting.
3847 It's OK to call this on a non-file since we ignore failure as it is
3849 only a hint.
3850 Function "common/utils/utils.c:guestfs_int_fadvise_random"
3852 void
3854 guestfs_int_fadvise_random (int fd)
3855 Hint that we will read or write the file descriptor randomly.
3857 On Linux, this sets the "FMODE_RANDOM" flag on the file. The effect of
3859 this flag is to:
3860 • Disable normal sequential file readahead.
3862 • If any read of the file is done which misses in the page cache, 2MB
3864 are read into the page cache. [I think - I'm not sure I totally
3865 understand what this is doing]
3866 It's OK to call this on a non-file since we ignore failure as it is
3868 only a hint.
3869 Function "common/utils/utils.c:guestfs_int_fadvise_noreuse"
3871 void
3873 guestfs_int_fadvise_noreuse (int fd)
3874 Hint that we will access the data only once.
3876 On Linux, this does nothing.
3878 It's OK to call this on a non-file since we ignore failure as it is
3880 only a hint.
3881 Function "common/utils/utils.c:guestfs_int_fadvise_dontneed"
3883 void
3885 guestfs_int_fadvise_dontneed (int fd)
3886 Hint that we will not access the data in the near future.
3888 On Linux, this immediately writes out any dirty pages in the page cache
3890 and then invalidates (drops) all pages associated with this file from
3891 the page cache. Apparently it does this even if the file is opened or
3892 being used by other processes. This setting is not persistent; if you
3893 subsequently read the file it will be cached in the page cache as
3894 normal.
3895 It's OK to call this on a non-file since we ignore failure as it is
3897 only a hint.
3898 Function "common/utils/utils.c:guestfs_int_fadvise_willneed"
3900 void
3902 guestfs_int_fadvise_willneed (int fd)
3903 Hint that we will access the data in the near future.
3905 On Linux, this immediately reads the whole file into the page cache.
3907 This setting is not persistent; subsequently pages may be dropped from
3908 the page cache as normal.
3909 It's OK to call this on a non-file since we ignore failure as it is
3911 only a hint.
3912 Function "common/utils/utils.c:guestfs_int_shell_unquote"
3914 char *
3916 guestfs_int_shell_unquote (const char *str)
3917 Unquote a shell-quoted string.
3919 Augeas passes strings to us which may be quoted, eg. if they come from
3921 files in /etc/sysconfig. This function can do simple unquoting of
3922 these strings.
3923 Note this function does not do variable substitution, since that is
3925 impossible without knowing the file context and indeed the environment
3926 under which the shell script is run. Configuration files should not
3927 use complex quoting.
3928 "str" is the input string from Augeas, a string that may be single- or
3930 double-quoted or may not be quoted. The returned string is unquoted,
3931 and must be freed by the caller. "NULL" is returned on error and
3932 "errno" is set accordingly.
3933 For information on double-quoting in bash, see
3935 https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html
3936 Function "common/utils/utils.c:guestfs_int_is_reg"
3938 int
3940 guestfs_int_is_reg (int64_t mode)
3941 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3943 field represents a regular file.
3944 Function "common/utils/utils.c:guestfs_int_is_dir"
3946 int
3948 guestfs_int_is_dir (int64_t mode)
3949 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3951 field represents a directory.
3952 Function "common/utils/utils.c:guestfs_int_is_chr"
3954 int
3956 guestfs_int_is_chr (int64_t mode)
3957 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3959 field represents a char device.
3960 Function "common/utils/utils.c:guestfs_int_is_blk"
3962 int
3964 guestfs_int_is_blk (int64_t mode)
3965 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3967 field represents a block device.
3968 Function "common/utils/utils.c:guestfs_int_is_fifo"
3970 int
3972 guestfs_int_is_fifo (int64_t mode)
3973 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3975 field represents a named pipe (FIFO).
3976 Function "common/utils/utils.c:guestfs_int_is_lnk"
3978 int
3980 guestfs_int_is_lnk (int64_t mode)
3981 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3983 field represents a symbolic link.
3984 Function "common/utils/utils.c:guestfs_int_is_sock"
3986 int
3988 guestfs_int_is_sock (int64_t mode)
3989 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3991 field represents a Unix domain socket.
3992 Function "common/utils/utils.c:guestfs_int_full_path"
3994 char *
3996 guestfs_int_full_path (const char *dir, const char *name)
3997 Concatenate "dir" and "name" to create a path. This correctly handles
3999 the case of concatenating "/" + "filename" as well as "/dir" +
4000 "filename". "name" may be "NULL".
4001 The caller must free the returned path.
4003 This function sets "errno" and returns "NULL" on error.
4005 Function "common/utils/utils.c:guestfs_int_hexdump"
4007 void
4009 guestfs_int_hexdump (const void *data, size_t len, FILE *fp)
4010 Hexdump a block of memory to "FILE *", used for debugging.
4012 Function "common/utils/utils.c:guestfs_int_strerror"
4014 const char *
4016 guestfs_int_strerror (int errnum, char *buf, size_t buflen)
4017 Thread-safe strerror_r.
4019 This is a wrapper around the two variants of strerror_r(3) in glibc
4021 since it is hard to use correctly (RHBZ#2030396).
4022 The buffer passed in should be large enough to store the error message
4024 (256 chars at least) and should be non-static. Note that the buffer
4025 might not be used, use the return value.
4026 Subdirectory common/visit
4028 File common/visit/visit.c
4029 This file contains a recursive function for visiting all files and
4031 directories in a guestfs filesystem.
4032 Adapted from
4034 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/
4035 Function "common/visit/visit.c:visit"
4037 int
4039 visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)
4040 Visit every file and directory in a guestfs filesystem, starting at
4042 "dir".
4043 "dir" may be "/" to visit the entire filesystem, or may be some
4045 subdirectory. Symbolic links are not followed.
4046 The visitor function "f" is called once for every directory and every
4048 file. The parameters passed to "f" include the current directory name,
4049 the current file name (or "NULL" when we're visiting a directory), the
4050 "guestfs_statns" (file permissions etc), and the list of extended
4051 attributes of the file. The visitor function may return "-1" which
4052 causes the whole recursion to stop with an error.
4053 Also passed to this function is an "opaque" pointer which is passed
4055 through to the visitor function.
4056 Returns 0 if everything went OK, or "-1" if there was an error. Error
4058 handling is not particularly well defined. It will either set an error
4059 in the libguestfs handle or print an error on stderr, but there is no
4060 way for the caller to tell the difference.
4061 Subdirectory common/windows
4063 File common/windows/windows.c
4064 This file implements "win:" Windows file path support in guestfish(1).
4066 Function "common/windows/windows.c:is_windows"
4068 int
4070 is_windows (guestfs_h *g, const char *root)
4071 Checks whether "root" is a Windows installation.
4073 This relies on an already being done introspection.
4075 Function "common/windows/windows.c:windows_path"
4077 char *
4079 windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
4080 Resolves "path" as possible Windows path according to "root", giving a
4082 new path that can be used in libguestfs API calls.
4083 Notes:
4085 • "root" must be a Windows installation
4087 • relies on an already being done introspection
4089 • will unmount all the existing mount points and mount the Windows
4091 root (according to "readonly")
4092 • calls exit(3) on memory allocation failures
4094 Subdirectory daemon
4096 File daemon/command.c
4097 This file contains a number of useful functions for running external
4099 commands and capturing their output.
4100 Function "daemon/command.c:commandf"
4102 int
4104 commandf (char **stdoutput, char **stderror, unsigned flags,
4105 const char *name, ...)
4106 Run a command. Optionally capture stdout and stderr as strings.
4108 Returns 0 if the command ran successfully, or "-1" if there was any
4110 error.
4111 For a description of the "flags" see "commandrvf".
4113 There is also a macro "command(out,err,name,...)" which calls
4115 "commandf" with "flags=0".
4116 Function "daemon/command.c:commandrf"
4118 int
4120 commandrf (char **stdoutput, char **stderror, unsigned flags,
4121 const char *name, ...)
4122 Same as "command", but we allow the status code from the subcommand to
4124 be non-zero, and return that status code.
4125 We still return "-1" if there was some other error.
4127 There is also a macro "commandr(out,err,name,...)" which calls
4129 "commandrf" with "flags=0".
4130 Function "daemon/command.c:commandvf"
4132 int
4134 commandvf (char **stdoutput, char **stderror, unsigned flags,
4135 char const *const *argv)
4136 Same as "command", but passing in an argv array.
4138 There is also a macro "commandv(out,err,argv)" which calls "commandvf"
4140 with "flags=0".
4141 Function "daemon/command.c:commandrvf"
4143 int
4145 commandrvf (char **stdoutput, char **stderror, unsigned flags,
4146 char const* const *argv)
4147 This is a more sane version of system(3) for running external commands.
4149 It uses fork/execvp, so we don't need to worry about quoting of
4150 parameters, and it allows us to capture any error messages in a buffer.
4151 If "stdoutput" is not "NULL", then *stdoutput will return the stdout of
4153 the command as a string.
4154 If "stderror" is not "NULL", then *stderror will return the stderr of
4156 the command. If there is a final \n character, it is removed so you
4157 can use the error string directly in a call to "reply_with_error".
4158 Flags are:
4160 "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR"
4162 For broken external commands that send error messages to stdout
4163 (hello, parted) but that don't have any useful stdout information,
4164 use this flag to capture the error messages in the *stderror
4165 buffer. If using this flag, you should pass "stdoutput=NULL"
4166 because nothing could ever be captured in that buffer.
4167 "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN"
4169 For running external commands on chrooted files correctly (see
4170 https://bugzilla.redhat.com/579608) specifying this flag causes
4171 another process to be forked which chroots into sysroot and just
4172 copies the input file to stdin of the specified command. The file
4173 descriptor is ORed with the flags, and that file descriptor is
4174 always closed by this function. See daemon/hexdump.c for an
4175 example of usage.
4176 There is also a macro "commandrv(out,err,argv)" which calls
4178 "commandrvf" with "flags=0".
4179 File daemon/device-name-translation.c
4181 Function
4183 "daemon/device-name-translation.c:device_name_translation_init"
4184 void
4186 device_name_translation_init (void)
4187 Cache daemon disk mapping.
4189 When the daemon starts up, populate a cache with the contents of
4191 /dev/disk/by-path. It's easiest to use "ls -lv" here since the names
4192 are sorted awkwardly.
4193 Function "daemon/device-name-translation.c:device_name_translation"
4195 char *
4197 device_name_translation (const char *device)
4198 Perform device name translation.
4200 Libguestfs defines a few standard formats for device names. (see also
4202 "BLOCK DEVICE NAMING" in guestfs(3) and "guestfs_canonical_device_name"
4203 in guestfs(3)). They are:
4204 /dev/sdX[N]
4206 /dev/hdX[N]
4207 /dev/vdX[N]
4208 These mean the Nth partition on the Xth device. Because Linux no
4209 longer enumerates devices in the order they are passed to qemu, we
4210 must translate these by looking up the actual device using
4211 /dev/disk/by-path/
4212 /dev/mdX
4214 /dev/VG/LV
4215 /dev/mapper/...
4216 /dev/dm-N
4217 These are not translated here.
4218 It returns a newly allocated string which the caller must free.
4220 It returns "NULL" on error. Note it does not call "reply_with_*".
4222 We have to open the device and test for "ENXIO", because the device
4224 nodes may exist in the appliance.
4225 File daemon/guestfsd.c
4227 This is the guestfs daemon which runs inside the guestfs appliance.
4229 This file handles start up and connecting back to the library.
4230 Function "daemon/guestfsd.c:print_shell_quote"
4232 static int
4234 print_shell_quote (FILE *stream,
4235 const struct printf_info *info ATTRIBUTE_UNUSED,
4236 const void *const *args)
4237 printf helper function so we can use %Q ("quoted") and %R to print
4239 shell-quoted strings. See guestfs-hacking(1) for more details.
4240 File daemon/internal.c
4242 Internal functions that are not part of the public API.
4244 File daemon/utils-c.c
4246 Bindings for utility functions.
4248 Note that functions called from OCaml code must never call any of the
4250 "reply*" functions.
4251 File daemon/utils.c
4253 Miscellaneous utility functions used by the daemon.
4255 Function "daemon/utils.c:is_root_device_stat"
4257 static int
4259 is_root_device_stat (struct stat *statbuf)
4260 Return true iff device is the root device (and therefore should be
4262 ignored from the point of view of user calls).
4263 Function "daemon/utils.c:is_device_parameter"
4265 int
4267 is_device_parameter (const char *device)
4268 Parameters marked as "Device", "Dev_or_Path", etc can be passed a block
4270 device name. This function tests if the parameter is a block device
4271 name.
4272 It can also be used in daemon code to test if the string passed as a
4274 "Dev_or_Path" parameter is a device or path.
4275 Function "daemon/utils.c:sysroot_path"
4277 char *
4279 sysroot_path (const char *path)
4280 Turn "/path" into "/sysroot/path".
4282 Returns "NULL" on failure. The caller must check for this and call
4284 "reply_with_perror ("malloc")". The caller must also free the returned
4285 string.
4286 See also the custom %R printf formatter which does shell quoting too.
4288 Function "daemon/utils.c:sysroot_realpath"
4290 char *
4292 sysroot_realpath (const char *path)
4293 Resolve path within sysroot, calling "sysroot_path" on the resolved
4295 path.
4296 Returns "NULL" on failure. The caller must check for this and call
4298 "reply_with_perror ("malloc")". The caller must also free the returned
4299 string.
4300 See also the custom %R printf formatter which does shell quoting too.
4302 Function "daemon/utils.c:is_power_of_2"
4304 int
4306 is_power_of_2 (unsigned long v)
4307 Returns true if "v" is a power of 2.
4309 Uses the algorithm described at
4311 http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2
4312 Function "daemon/utils.c:split_lines_sb"
4314 struct stringsbuf
4316 split_lines_sb (char *str)
4317 Split an output string into a NULL-terminated list of lines, wrapped
4319 into a stringsbuf.
4320 Typically this is used where we have run an external command which has
4322 printed out a list of things, and we want to return an actual list.
4323 The corner cases here are quite tricky. Note in particular:
4325 "" returns "[]"
4327 "\n"
4329 returns "[""]"
4330 "a\nb"
4332 returns "["a"; "b"]"
4333 "a\nb\n"
4335 returns "["a"; "b"]"
4336 "a\nb\n\n"
4338 returns "["a"; "b"; ""]"
4339 The original string is written over and destroyed by this function
4341 (which is usually OK because it's the 'out' string from "command*()").
4342 You can free the original string, because "add_string()" strdups the
4343 strings.
4344 "argv" in the "struct stringsbuf" will be "NULL" in case of errors.
4346 Function "daemon/utils.c:filter_list"
4348 char **
4350 filter_list (bool (*p) (const char *str), char **strs)
4351 Filter a list of strings. Returns a newly allocated list of only the
4353 strings where "p (str) == true".
4354 Note it does not copy the strings, be careful not to double-free them.
4356 Function "daemon/utils.c:trim"
4358 void
4360 trim (char *str)
4361 Skip leading and trailing whitespace, updating the original string in-
4363 place.
4364 Function "daemon/utils.c:parse_btrfsvol"
4366 int
4368 parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
4369 Parse the mountable descriptor for a btrfs subvolume. Don't call this
4371 directly; it is only used from the stubs.
4372 A btrfs subvolume is given as:
4374 btrfsvol:/dev/sda3/root
4376 where /dev/sda3 is a block device containing a btrfs filesystem, and
4378 root is the name of a subvolume on it. This function is passed the
4379 string following "btrfsvol:".
4380 On success, "mountable->device" and "mountable->volume" must be freed
4382 by the caller.
4383 Function "daemon/utils.c:mountable_to_string"
4385 char *
4387 mountable_to_string (const mountable_t *mountable)
4388 Convert a "mountable_t" back to its string representation
4390 This function can be used in an error path, so must not call
4392 "reply_with_error".
4393 Function "daemon/utils.c:prog_exists"
4395 int
4397 prog_exists (const char *prog)
4398 Check program exists and is executable on $PATH.
4400 Function "daemon/utils.c:random_name"
4402 int
4404 random_name (char *template)
4405 Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
4407 template to contain a randomly named file. Any 'X' characters after
4408 the final '/' in the template are replaced with random characters.
4409 Notes: You should probably use an 8.3 path, so it's compatible with all
4411 filesystems including basic FAT. Also this only substitutes lowercase
4412 ASCII letters and numbers, again for compatibility with lowest common
4413 denominator filesystems.
4414 This doesn't create a file or check whether or not the file exists (it
4416 would be extremely unlikely to exist as long as the RNG is working).
4417 If there is an error, "-1" is returned.
4419 Function "daemon/utils.c:udev_settle_file"
4421 void
4423 udev_settle_file (const char *file)
4424 LVM and other commands aren't synchronous, especially when udev is
4426 involved. eg. You can create or remove some device, but the "/dev"
4427 device node won't appear until some time later. This means that you
4428 get an error if you run one command followed by another.
4429 Use "udevadm settle" after certain commands, but don't be too fussed if
4431 it fails.
4432 Function "daemon/utils.c:make_exclude_from_file"
4434 char *
4436 make_exclude_from_file (const char *function, char *const *excludes)
4437 Turn list "excludes" into a temporary file, and return a string
4439 containing the temporary file name. Caller must unlink the file and
4440 free the string.
4441 "function" is the function that invoked this helper, and it is used
4443 mainly for errors/debugging.
4444 Function "daemon/utils.c:read_whole_file"
4446 char *
4448 read_whole_file (const char *filename, size_t *size_r)
4449 Read whole file into dynamically allocated array. If there is an
4451 error, DON'T call reply_with_perror, just return NULL. Returns a
4452 "\0"-terminated string. "size_r" can be specified to get the size of
4453 the returned data.
4454 File daemon/xattr.c
4456 Function "daemon/xattr.c:split_attr_names"
4458 static char **
4460 split_attr_names (char *buf, size_t len)
4461 listxattr(2) returns the string "foo\0bar\0baz" of length "len". (The
4463 last string in the list is \0-terminated but the \0 is not included in
4464 "len").
4465 This function splits it into a regular list of strings.
4467 Note that the returned list contains pointers to the original strings
4469 in "buf" so be careful that you do not double-free them.
4470 Subdirectory fish
4472 File fish/alloc.c
4473 This file implements the guestfish "alloc" and "sparse" commands.
4475 Function "fish/alloc.c:alloc_disk"
4477 int
4479 alloc_disk (const char *filename, const char *size_str, int add, int sparse)
4480 This is the underlying allocation function. It's called from a few
4482 other places in guestfish.
4483 File fish/copy.c
4485 This file implements the guestfish commands "copy-in" and "copy-out".
4487 File fish/destpaths.c
4489 The file handles tab-completion of filesystem paths in guestfish.
4491 File fish/display.c
4493 The file implements the guestfish "display" command, for displaying
4495 graphical files (icons, images) in disk images.
4496 File fish/echo.c
4498 The file implements the guestfish "echo" command.
4500 File fish/edit.c
4502 guestfish "edit" command, suggested by Ján Ondrej.
4504 File fish/events.c
4506 This file implements the guestfish event-related commands, "event",
4508 "delete-event" and "list-events".
4509 File fish/fish.c
4511 guestfish, the guest filesystem shell. This file contains the main
4513 loop and utilities.
4514 Function "fish/fish.c:parse_command_line"
4516 static struct parsed_command
4518 parse_command_line (char *buf, int *exit_on_error_rtn)
4519 Parse a command string, splitting at whitespace, handling '!', '#' etc.
4521 This destructively updates "buf".
4522 "exit_on_error_rtn" is used to pass in the global "exit_on_error"
4524 setting and to return the local setting (eg. if the command begins with
4525 '-').
4526 Returns in "parsed_command.status":
4528 1 got a guestfish command (returned in
4530 "cmd_rtn"/"argv_rtn"/"pipe_rtn")
4531 0 no guestfish command, but otherwise OK
4533 "-1"
4535 an error
4536 Function "fish/fish.c:parse_quoted_string"
4538 static ssize_t
4540 parse_quoted_string (char *p)
4541 Parse double-quoted strings, replacing backslash escape sequences with
4543 the true character. Since the string is returned in place, the escapes
4544 must make the string shorter.
4545 Function "fish/fish.c:execute_and_inline"
4547 static int
4549 execute_and_inline (const char *cmd, int global_exit_on_error)
4550 Used to handle "<!" (execute command and inline result).
4552 Function "fish/fish.c:issue_command"
4554 int
4556 issue_command (const char *cmd, char *argv[], const char *pipecmd,
4557 int rc_exit_on_error_flag)
4558 Run a command.
4560 "rc_exit_on_error_flag" is the "exit_on_error" flag that we pass to the
4562 remote server (when issuing --remote commands). It does not cause
4563 "issue_command" itself to exit on error.
4564 Function "fish/fish.c:extended_help_message"
4566 void
4568 extended_help_message (void)
4569 Print an extended help message when the user types in an unknown
4571 command for the first command issued. A common case is the user doing:
4572 guestfish disk.img
4574 expecting guestfish to open disk.img (in fact, this tried to run a non-
4576 existent command "disk.img").
4577 Function "fish/fish.c:error_cb"
4579 static void
4581 error_cb (guestfs_h *g, void *data, const char *msg)
4582 Error callback. This replaces the standard libguestfs error handler.
4584 Function "fish/fish.c:free_n_strings"
4586 static void
4588 free_n_strings (char **str, size_t len)
4589 Free strings from a non-NULL terminated "char**".
4591 Function "fish/fish.c:decode_ps1"
4593 static char *
4595 decode_ps1 (const char *str)
4596 Decode "str" into the final printable prompt string.
4598 Function "fish/fish.c:win_prefix"
4600 char *
4602 win_prefix (const char *path)
4603 Resolve the special "win:..." form for Windows-specific paths. The
4605 generated code calls this for all device or path arguments.
4606 The function returns a newly allocated string, and the caller must free
4608 this string; else display an error and return "NULL".
4609 Function "fish/fish.c:file_in"
4611 char *
4613 file_in (const char *arg)
4614 Resolve the special "FileIn" paths ("-" or "-<<END" or filename).
4616 The caller (fish/cmds.c) will call "free_file_in" after the command has
4618 run which should clean up resources.
4619 Function "fish/fish.c:file_out"
4621 char *
4623 file_out (const char *arg)
4624 Resolve the special "FileOut" paths ("-" or filename).
4626 The caller (fish/cmds.c) will call "free (str)" after the command has
4628 run.
4629 Function "fish/fish.c:progress_callback"
4631 void
4633 progress_callback (guestfs_h *g, void *data,
4634 uint64_t event, int event_handle, int flags,
4635 const char *buf, size_t buf_len,
4636 const uint64_t *array, size_t array_len)
4637 Callback which displays a progress bar.
4639 File fish/glob.c
4641 This file implements the guestfish "glob" command.
4643 Function "fish/glob.c:expand_devicename"
4645 static char **
4647 expand_devicename (guestfs_h *g, const char *device)
4648 Glob-expand device patterns, such as "/dev/sd*"
4650 (https://bugzilla.redhat.com/635971).
4651 There is no "guestfs_glob_expand_device" function because the
4653 equivalent can be implemented using functions like
4654 "guestfs_list_devices".
4655 It's not immediately clear what it means to expand a pattern like
4657 "/dev/sd*". Should that include device name translation? Should the
4658 result include partitions as well as devices?
4659 Should "/dev/" + "*" return every possible device and filesystem? How
4661 about VGs? LVs?
4662 To solve this what we do is build up a list of every device, partition,
4664 etc., then glob against that list.
4665 Notes for future work (XXX):
4667 • This doesn't handle device name translation. It wouldn't be too
4669 hard to add.
4670 • Could have an API function for returning all device-like things.
4672 Function "fish/glob.c:add_strings_matching"
4674 static int
4676 add_strings_matching (char **pp, const char *glob,
4677 char ***ret, size_t *size_r)
4678 Using POSIX fnmatch(3), find strings in the list "pp" which match
4680 pattern "glob". Add strings which match to the "ret" array. *size_r
4681 is the current size of the "ret" array, which is updated with the new
4682 size.
4683 Function "fish/glob.c:single_element_list"
4685 static char **
4687 single_element_list (const char *element)
4688 Return a single element list containing "element".
4690 File fish/help.c
4692 The file implements the guestfish "help" command.
4694 Function "fish/help.c:display_help"
4696 int
4698 display_help (const char *cmd, size_t argc, char *argv[])
4699 The "help" command.
4701 This used to just list all commands, but that's not very useful.
4703 Instead display some useful context-sensitive help. This could be
4704 improved if we knew how many drives had been added already, and whether
4705 anything was mounted.
4706 File fish/hexedit.c
4708 This file implements the guestfish "hexedit" command.
4710 File fish/lcd.c
4712 Function "fish/lcd.c:run_lcd"
4714 int
4716 run_lcd (const char *cmd, size_t argc, char *argv[])
4717 guestfish "lcd" command (similar to the "lcd" command in BSD ftp).
4719 File fish/man.c
4721 Function "fish/man.c:run_man"
4723 int
4725 run_man (const char *cmd, size_t argc, char *argv[])
4726 guestfish "man" command
4728 File fish/more.c
4730 This file implements the guestfish "more" command.
4732 File fish/prep.c
4734 This file implements the guestfish -N option for creating pre-prepared
4736 disk layouts.
4737 File fish/rc.c
4739 This file implements guestfish remote (command) support.
4741 Function "fish/rc.c:rc_listen"
4743 void
4745 rc_listen (void)
4746 The remote control server (ie. "guestfish --listen").
4748 Function "fish/rc.c:rc_remote"
4750 int
4752 rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
4753 int exit_on_error)
4754 The remote control client (ie. "guestfish --remote").
4756 File fish/reopen.c
4758 This file implements the guestfish "reopen" command.
4760 File fish/setenv.c
4762 This file implements the guestfish "setenv" and "unsetenv" commands.
4764 File fish/supported.c
4766 This file implements the guestfish "supported" command.
4768 File fish/tilde.c
4770 This file implements tilde ("~") expansion of home directories in
4772 guestfish(1).
4773 Function "fish/tilde.c:try_tilde_expansion"
4775 char *
4777 try_tilde_expansion (char *str)
4778 This is called from the script loop if we find a candidate for
4780 "~username" (tilde-expansion).
4781 Function "fish/tilde.c:expand_home"
4783 static char *
4785 expand_home (char *orig, const char *append)
4786 Return $HOME + append string.
4788 Function "fish/tilde.c:find_home_for_username"
4790 static const char *
4792 find_home_for_username (const char *username, size_t ulen)
4793 Lookup "username" (of length "ulen"), return home directory if found,
4795 or "NULL" if not found.
4796 File fish/time.c
4798 This file implements the guestfish "time" command.
4800 Subdirectory python
4802 File python/handle.c
4803 This file contains a small number of functions that are written by
4805 hand. The majority of the bindings are generated (see
4806 python/actions-*.c).
4807
4809 guestfs(3), guestfs-building(1), guestfs-examples(3),
4810 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
4811 guestfs-testing(1), libguestfs-test-tool(1),
4812 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
4813
4815 Richard W.M. Jones ("rjones at redhat dot com")
4816
4818 Copyright (C) 2009-2020 Red Hat Inc.
4819
4821 This library is free software; you can redistribute it and/or modify it
4822 under the terms of the GNU Lesser General Public License as published
4823 by the Free Software Foundation; either version 2 of the License, or
4824 (at your option) any later version.
4825 This library is distributed in the hope that it will be useful, but
4827 WITHOUT ANY WARRANTY; without even the implied warranty of
4828 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4829 Lesser General Public License for more details.
4830 You should have received a copy of the GNU Lesser General Public
4832 License along with this library; if not, write to the Free Software
4833 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
4834 02110-1301 USA
4835
4837 To get a list of bugs against libguestfs, use this link:
4838 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
4839 To report a new bug against libguestfs, use this link:
4841 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
4842 When reporting a bug, please supply:
4844 • The version of libguestfs.
4846 • Where you got libguestfs (eg. which Linux distro, compiled from
4848 source, etc)
4849 • Describe the bug accurately and give a way to reproduce it.
4851 • Run libguestfs-test-tool(1) and paste the complete, unedited output
4853 into the bug report.
4854libguestfs-1.48.3 2022-05-26 guestfs-hacking(1)