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 ("./autogen.sh && 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 gnulib
206 Gnulib is used as a portability library. A copy of gnulib is
207 included under here.
208 inspector
210 virt-inspector(1), the virtual machine image inspector.
211 lib Source code to the C library.
213 logo
215 Logo used on the website. The fish is called Arthur by the way.
216 m4 M4 macros used by autoconf. See "THE BUILD SYSTEM".
218 make-fs
220 virt-make-fs(1) command and documentation.
221 po Translations of simple gettext strings.
223 po-docs
225 The build infrastructure and PO files for translations of manpages
226 and POD files. Eventually this will be combined with the po
227 directory, but that is rather complicated.
228 rescue
230 virt-rescue(1) command and documentation.
231 resize
233 virt-resize(1) command and documentation.
234 sparsify
236 virt-sparsify(1) command and documentation.
237 sysprep
239 virt-sysprep(1) command and documentation.
240 tests
242 Tests.
243 test-data
245 Files and other test data used by the tests.
246 test-tool
248 Test tool for end users to test if their qemu/kernel combination
249 will work with libguestfs.
250 tmp Used for temporary files when running the tests (instead of /tmp
252 etc). The reason is so that you can run multiple parallel tests of
253 libguestfs without having one set of tests overwriting the
254 appliance created by another.
255 tools
257 Command line tools written in Perl (virt-win-reg(1) and many
258 others).
259 utils
261 Miscellaneous utilities, such as "boot-benchmark".
262 v2v Up to libguestfs > 1.42 this contained the virt-v2v(1) tool, but
264 this has now moved into a separate repository:
265 https://github.com/libguestfs/virt-v2v
266 website
268 The http://libguestfs.org website files.
269 csharp
271 erlang
272 gobject
273 golang
274 haskell
275 java
276 lua
277 ocaml
278 php
279 perl
280 python
281 ruby
282 Language bindings.
283 THE BUILD SYSTEM
285 Libguestfs uses the GNU autotools build system (autoconf, automake,
286 libtool).
287 The ./configure script is generated from configure.ac and
289 m4/guestfs-*.m4. Most of the configure script is split over many m4
290 macro files by topic, for example m4/guestfs-daemon.m4 deals with the
291 dependencies of the daemon.
292 The job of the top level Makefile.am is mainly to list the
294 subdirectories ("SUBDIRS") in the order they should be compiled.
295 common-rules.mk is included in every Makefile.am (top level and
297 subdirectories). subdir-rules.mk is included only in subdirectory
298 Makefile.am files.
299 There are many make targets. Use this command to list them all:
301 make help
303
305 ADDING A NEW API
306 Because large amounts of boilerplate code in libguestfs are generated,
307 this makes it easy to extend the libguestfs API.
308 To add a new API action there are two changes:
310 1. You need to add a description of the call (name, parameters, return
312 type, tests, documentation) to generator/actions_*.ml and possibly
313 generator/proc_nr.ml.
314 There are two sorts of API action, depending on whether the call
316 goes through to the daemon in the appliance, or is serviced
317 entirely by the library (see "ARCHITECTURE" in
318 guestfs-internals(1)). "guestfs_sync" in guestfs(3) is an example
319 of the former, since the sync is done in the appliance.
320 "guestfs_set_trace" in guestfs(3) is an example of the latter,
321 since a trace flag is maintained in the handle and all tracing is
322 done on the library side.
323 Most new actions are of the first type, and get added to the
325 "daemon_functions" list. Each function has a unique procedure
326 number used in the RPC protocol which is assigned to that action
327 when we publish libguestfs and cannot be reused. Take the latest
328 procedure number and increment it.
329 For library-only actions of the second type, add to the
331 "non_daemon_functions" list. Since these functions are serviced by
332 the library and do not travel over the RPC mechanism to the daemon,
333 these functions do not need a procedure number, and so the
334 procedure number is set to "-1".
335 2. Implement the action (in C):
337 For daemon actions, implement the function "do_<name>" in the
339 "daemon/" directory.
340 For library actions, implement the function "guestfs_impl_<name>"
342 in the "lib/" directory.
343 In either case, use another function as an example of what to do.
345 3. As an alternative to step 2: Since libguestfs 1.38, daemon actions
347 can be implemented in OCaml. You have to set the "impl = OCaml
348 ..." flag in the generator. Take a look at daemon/file.ml for an
349 example.
350 After making these changes, use "make" to compile.
352 Note that you don’t need to implement the RPC, language bindings,
354 manual pages or anything else. It’s all automatically generated from
355 the OCaml description.
356 Adding tests for an API
358 You can supply zero or as many tests as you want per API call. The
360 tests can either be added as part of the API description
361 (generator/actions_*.ml), or in some rarer cases you may want to drop a
362 script into "tests/*/". Note that adding a script to "tests/*/" is
363 slower, so if possible use the first method.
364 The following describes the test environment used when you add an API
366 test in actions_*.ml.
367 The test environment has 4 block devices:
369 /dev/sda 2 GB
371 General block device for testing.
372 /dev/sdb 2 GB
374 /dev/sdb1 is an ext2 filesystem used for testing filesystem write
375 operations.
376 /dev/sdc 10 MB
378 Used in a few tests where two block devices are needed.
379 /dev/sdd
381 ISO with fixed content (see images/test.iso).
382 To be able to run the tests in a reasonable amount of time, the
384 libguestfs appliance and block devices are reused between tests. So
385 don't try testing "guestfs_kill_subprocess" in guestfs(3) :-x
386 Each test starts with an initial scenario, selected using one of the
388 "Init*" expressions, described in generator/types.ml. These initialize
389 the disks mentioned above in a particular way as documented in
390 types.ml. You should not assume anything about the previous contents
391 of other disks that are not initialized.
392 You can add a prerequisite clause to any individual test. This is a
394 run-time check, which, if it fails, causes the test to be skipped.
395 Useful if testing a command which might not work on all variations of
396 libguestfs builds. A test that has prerequisite of "Always" means to
397 run unconditionally.
398 In addition, packagers can skip individual tests by setting environment
400 variables before running "make check".
401 SKIP_TEST_<CMD>_<NUM>=1
403 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command" in
405 guestfs(3).
406 or:
408 SKIP_TEST_<CMD>=1
410 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" in guestfs(3)
412 tests.
413 Packagers can run only certain tests by setting for example:
415 TEST_ONLY="vfs_type zerofree"
417 See tests/c-api/tests.c for more details of how these environment
419 variables work.
420 Debugging new APIs
422 Test new actions work before submitting them.
424 You can use guestfish to try out new commands.
426 Debugging the daemon is a problem because it runs inside a minimal
428 environment. However you can fprintf messages in the daemon to stderr,
429 and they will show up if you use "guestfish -v".
430 ADDING A NEW LANGUAGE BINDING
432 All language bindings must be generated by the generator (see the
433 generator subdirectory).
434 There is no documentation for this yet. We suggest you look at an
436 existing binding, eg. generator/ocaml.ml or generator/perl.ml.
437 Adding tests for language bindings
439 Language bindings should come with tests. Previously testing of
441 language bindings was rather ad-hoc, but we have been trying to
442 formalize the set of tests that every language binding should use.
443 Currently only the OCaml and Perl bindings actually implement the full
445 set of tests, and the OCaml bindings are canonical, so you should
446 emulate what the OCaml tests do.
447 This is the numbering scheme used by the tests:
449 - 000+ basic tests:
451 010 load the library
453 020 create
454 030 create-flags
455 040 create multiple handles
456 050 test setting and getting config properties
457 060 explicit close
458 065 implicit close (in GC'd languages)
459 070 optargs
460 080 version
461 090 retvalues
462 - 100 launch, create partitions and LVs and filesystems
464 - 400+ events:
466 410 close event
468 420 log messages
469 430 progress messages
470 - 800+ regression tests (specific to the language)
472 - 900+ any other custom tests for the language
474 To save time when running the tests, only 100, 430, 800+, 900+ should
476 launch the handle.
477 FORMATTING CODE
479 Our C source code generally adheres to some basic code-formatting
480 conventions. The existing code base is not totally consistent on this
481 front, but we do prefer that contributed code be formatted similarly.
482 In short, use spaces-not-TABs for indentation, use 2 spaces for each
483 indentation level, and other than that, follow the K&R style.
484 If you use Emacs, add the following to one of your start-up files
486 (e.g., ~/.emacs), to help ensure that you get indentation right:
487 ;;; In libguestfs, indent with spaces everywhere (not TABs).
489 ;;; Exceptions: Makefile and ChangeLog modes.
490 (add-hook 'find-file-hook
491 '(lambda () (if (and buffer-file-name
492 (string-match "/libguestfs\\>"
493 (buffer-file-name))
494 (not (string-equal mode-name "Change Log"))
495 (not (string-equal mode-name "Makefile")))
496 (setq indent-tabs-mode nil))))
497 ;;; When editing C sources in libguestfs, use this style.
499 (defun libguestfs-c-mode ()
500 "C mode with adjusted defaults for use with libguestfs."
501 (interactive)
502 (c-set-style "K&R")
503 (setq c-indent-level 2)
504 (setq c-basic-offset 2))
505 (add-hook 'c-mode-hook
506 '(lambda () (if (string-match "/libguestfs\\>"
507 (buffer-file-name))
508 (libguestfs-c-mode))))
509 TESTING YOUR CHANGES
511 Turn warnings into errors when developing to make warnings hard to
512 ignore:
513 ./configure --enable-werror
515 Useful targets are:
517 "make check"
519 Runs the regular test suite.
520 This is implemented using the regular automake "TESTS" target. See
522 the automake documentation for details.
523 "make check-valgrind"
525 Runs a subset of the test suite under valgrind.
526 See "VALGRIND" below.
528 "make check-valgrind-local-guests"
530 Runs a subset of the test suite under valgrind using locally
531 installed libvirt guests (read-only).
532 "make check-direct"
534 Runs all tests using default appliance back-end. This only has any
535 effect if a non-default backend was selected using "./configure
536 --with-default-backend=..."
537 "make check-valgrind-direct"
539 Run a subset of the test suite under valgrind using the default
540 appliance back-end.
541 "make check-uml"
543 Runs all tests using the User-Mode Linux backend.
544 As there is no standard location for the User-Mode Linux kernel,
546 you have to set "LIBGUESTFS_HV" to point to the kernel image, eg:
547 make check-uml LIBGUESTFS_HV=~/d/linux-um/vmlinux
549 "make check-valgrind-uml"
551 Runs all tests using the User-Mode Linux backend, under valgrind.
552 As above, you have to set "LIBGUESTFS_HV" to point to the kernel.
554 "make check-with-upstream-qemu"
556 Runs all tests using a local qemu binary. It looks for the qemu
557 binary in QEMUDIR (defaults to $HOME/d/qemu), but you can set this
558 to another directory on the command line, eg:
559 make check-with-upstream-qemu QEMUDIR=/usr/src/qemu
561 "make check-with-upstream-libvirt"
563 Runs all tests using a local libvirt. This only has any effect if
564 the libvirt backend was selected using "./configure
565 --with-default-backend=libvirt"
566 It looks for libvirt in LIBVIRTDIR (defaults to $HOME/d/libvirt),
568 but you can set this to another directory on the command line, eg:
569 make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt
571 "make check-slow"
573 Runs some slow/long-running tests which are not run by default.
574 To mark a test as slow/long-running:
576 · Add it to the list of "TESTS" in the Makefile.am, just like a
578 normal test.
579 · Modify the test so it checks if the "SLOW=1" environment
581 variable is set, and if not set it skips (ie. returns with exit
582 code 77). If using $TEST_FUNCTIONS, you can call the function
583 "slow_test" for this.
584 · Add a variable "SLOW_TESTS" to the Makefile.am listing the slow
586 tests.
587 · Add a rule to the Makefile.am:
589 check-slow:
591 $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
592 "sudo make check-root"
594 Runs some tests which require root privileges. These are supposed
595 to be safe, but take care. You have to run this as root (eg. using
596 sudo(8) explicitly).
597 To mark a test as requiring root:
599 · Add it to the list of "TESTS" in the Makefile.am, just like a
601 normal test.
602 · Modify the test so it checks if euid == 0, and if not set it
604 skips (ie. returns with exit code 77). If using
605 $TEST_FUNCTIONS, you can call the function "root_test" for
606 this.
607 · Add a variable "ROOT_TESTS" to the Makefile.am listing the root
609 tests.
610 · Add a rule to the Makefile.am:
612 check-root:
614 $(MAKE) check TESTS="$(ROOT_TESTS)"
615 "make check-all"
617 Equivalent to running all "make check*" rules except "check-root".
618 "make check-release"
620 Runs a subset of "make check*" rules that are required to pass
621 before a tarball can be released. Currently this is:
622 · check
624 · check-valgrind
626 · check-direct
628 · check-valgrind-direct
630 · check-slow
632 "make installcheck"
634 Run "make check" on the installed copy of libguestfs.
635 The version of installed libguestfs being tested, and the version
637 of the libguestfs source tree must be the same.
638 Do:
640 ./autogen.sh
642 make clean ||:
643 make
644 make installcheck
645 VALGRIND
647 When you do "make check-valgrind", it searches for any Makefile.am in
648 the tree that has a "check-valgrind:" target and runs it.
649 Writing the Makefile.am and tests correctly to use valgrind and working
651 with automake parallel tests is subtle.
652 If your tests are run via a shell script wrapper, then in the wrapper
654 use:
655 $VG virt-foo
657 and in the Makefile.am use:
659 check-valgrind:
661 make VG="@VG@" check
662 However, if your binaries run directly from the "TESTS" rule, you have
664 to modify the Makefile.am like this:
665 LOG_COMPILER = $(VG)
667 check-valgrind:
669 make VG="@VG@" check
670 In either case, check that the right program is being tested by
672 examining the tmp/valgrind* log files carefully.
673 SUBMITTING PATCHES
675 Submit patches to the mailing list:
676 http://www.redhat.com/mailman/listinfo/libguestfs and CC to
677 rjones@redhat.com.
678 You do not need to subscribe to the mailing list if you don’t want to.
680 There may be a short delay while your message is moderated.
681 DAEMON CUSTOM PRINTF FORMATTERS
683 In the daemon code we have created custom printf formatters %Q and %R,
684 which are used to do shell quoting.
685 %Q Simple shell quoted string. Any spaces or other shell characters
687 are escaped for you.
688 %R Same as %Q except the string is treated as a path which is prefixed
690 by the sysroot.
691 For example:
693 asprintf (&cmd, "cat %R", path);
695 would produce "cat /sysroot/some\ path\ with\ spaces"
697 Note: Do not use these when you are passing parameters to the
699 "command{,r,v,rv}()" functions. These parameters do NOT need to be
700 quoted because they are not passed via the shell (instead, straight to
701 exec). You probably want to use the "sysroot_path()" function however.
702 INTERNATIONALIZATION (I18N) SUPPORT
704 We support i18n (gettext anyhow) in the library.
705 However many messages come from the daemon, and we don’t translate
707 those at the moment. One reason is that the appliance generally has
708 all locale files removed from it, because they take up a lot of space.
709 So we'd have to readd some of those, as well as copying our PO files
710 into the appliance.
711 Debugging messages are never translated, since they are intended for
713 the programmers.
714
716 HOW OCAML PROGRAMS ARE COMPILED AND LINKED
717 Mostly this section is "how we make automake & ocamlopt work together"
718 since OCaml programs themselves are easy to compile.
719 Automake has no native support for OCaml programs, ocamlc nor ocamlopt.
721 What we do instead is to treat OCaml programs as C programs which
722 happen to contain these "other objects" ("DEPENDENCIES" in automake-
723 speak) that happen to be the OCaml objects. This works because OCaml
724 programs usually have C files for native bindings etc.
725 So a typical program is described as just its C sources:
727 virt_customize_SOURCES = ... crypt-c.c perl_edit-c.c
729 For programs that have no explicit C sources, we create an empty
731 dummy.c file, and list that instead:
732 virt_resize_SOURCES = dummy.c
734 The OCaml objects which contain most of the code are listed as automake
736 dependencies (other dependencies may also be listed):
737 virt_customize_DEPENDENCIES = ... customize_main.cmx
739 The only other special thing we need to do is to provide a custom link
741 command. This is needed because automake won't assemble the ocamlopt
742 command, the list of objects and the "-cclib" libraries in the correct
743 order otherwise.
744 virt_customize_LINK = \
746 $(top_srcdir)/ocaml-link.sh -cclib '-lutils -lgnu' -- ...
747 The actual rules, which you can examine in customize/Makefile.am, are a
749 little bit more complicated than this because they have to handle:
750 · Compiling for byte code or native code.
752 · The pattern rules needed to compile the OCaml sources to objects.
754 These are now kept in subdir-rules.mk at the top level, which is
756 included in every subdirectory Makefile.am.
757 · Adding OCaml sources files to "EXTRA_DIST".
759 Automake isn't aware of the complete list of sources for a binary,
761 so it will not add them all automatically.
762
764 MAINTAINER MAKEFILE TARGETS
765 These "make" targets probably won’t work and aren't useful unless you
766 are a libguestfs maintainer.
767 make maintainer-commit
769 This commits everything in the working directory with the commit
771 message "Version $(VERSION).". You must update configure.ac, clean and
772 rebuild first.
773 make maintainer-tag
775 This tags the current HEAD commit with the tag "v$(VERSION)" and one of
777 the messages:
778 Version $(VERSION) stable
780 Version $(VERSION) development
782 (See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for the difference
784 between a stable and development release.)
785 make maintainer-check-authors
787 Check that all authors (found in git commit messages) are included in
789 the generator/authors.ml file.
790 make maintainer-check-extra-dist
792 This rule must be run after "make dist" (so there is a tarball in the
794 working directory). It compares the contents of the tarball with the
795 contents of git to ensure that no files have been missed from
796 Makefile.am "EXTRA_DIST" rules.
797 make maintainer-upload-website
799 This is used by the software used to automate libguestfs releases to
801 copy the libguestfs website to another git repository before it is
802 uploaded to the web server.
803 MAKING A STABLE RELEASE
805 When we make a stable release, there are several steps documented here.
806 See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for general information
807 about the stable branch policy.
808 · Check "make && make check" works on at least:
810 Fedora (x86-64)
812 Debian (x86-64)
813 Ubuntu (x86-64)
814 Fedora (aarch64)
815 Fedora (ppc64)
816 Fedora (ppc64le)
817 · Check "./configure --without-libvirt" works.
818 · Finalize guestfs-release-notes.pod
820 · Push and pull from Zanata.
822 Run:
824 zanata push
826 to push the latest POT files to Zanata. Then run:
828 ./zanata-pull.sh
830 which is a wrapper to pull the latest translated *.po files.
832 · Consider updating gnulib to latest upstream version.
834 · Create new stable and development directories under
836 http://libguestfs.org/download.
837 · Edit website/index.html.in.
839 · Set the version (in configure.ac) to the new stable version, ie.
841 1.XX.0, and commit it:
842 ./localconfigure
844 make distclean -k
845 ./localconfigure
846 make && make dist
847 make maintainer-commit
848 make maintainer-tag
849 · Create the stable branch in git:
851 git branch stable-1.XX
853 git push origin stable-1.XX
854 · Do a full release of the stable branch.
856 · Set the version to the next development version and commit that.
858 Optionally do a full release of the development branch.
859
861 This section documents internal functions inside libguestfs and various
862 utilities. It is intended for libguestfs developers only.
863 This section is autogenerated from "/**" comments in source files,
865 which are marked up in POD format.
866 These functions are not publicly exported, and may change or be removed
868 at any time.
869 Subdirectory lib
871 File lib/actions-support.c
872 Helper functions for the actions code in lib/actions-*.c.
874 File lib/appliance-cpu.c
876 The appliance choice of CPU model.
878 Function "lib/appliance-cpu.c:guestfs_int_get_cpu_model"
880 const char *
882 guestfs_int_get_cpu_model (int kvm)
883 Return the right CPU model to use as the qemu "-cpu" parameter or its
885 equivalent in libvirt. This returns:
886 "host"
888 The literal string "host" means use "-cpu host".
889 some string
891 Some string such as "cortex-a57" means use "-cpu cortex-a57".
892 "NULL"
894 "NULL" means no "-cpu" option at all. Note returning "NULL" does
895 not indicate an error.
896 This is made unnecessarily hard and fragile because of two stupid
898 choices in QEMU:
899 · The default for "qemu-system-aarch64 -M virt" is to emulate a
901 "cortex-a15" (WTF?).
902 · We don't know for sure if KVM will work, but "-cpu host" is broken
904 with TCG, so we almost always pass a broken "-cpu" flag if KVM is
905 semi-broken in any way.
906 File lib/appliance-kcmdline.c
908 The appliance kernel command line.
910 Definition "lib/appliance-kcmdline.c:VALID_TERM"
912 #define VALID_TERM
914 Check that the $TERM environment variable is reasonable before we pass
916 it through to the appliance.
917 Function "lib/appliance-kcmdline.c:get_root_uuid"
919 static char *
921 get_root_uuid (guestfs_h *g, const char *appliance)
922 Given a disk image containing an extX filesystem, return the UUID. The
924 file(1) command does the hard work.
925 Function "lib/appliance-kcmdline.c:guestfs_int_appliance_command_line"
927 char *
929 guestfs_int_appliance_command_line (guestfs_h *g,
930 const char *appliance,
931 int flags)
932 Construct the Linux command line passed to the appliance. This is used
934 by the "direct" and "libvirt" backends, and is simply located in this
935 file because it's a convenient place for this common code.
936 The "appliance" parameter is the filename of the appliance (could be
938 NULL) from which we obtain the root UUID.
939 The "flags" parameter can contain the following flags logically or'd
941 together (or 0):
942 "APPLIANCE_COMMAND_LINE_IS_TCG"
944 If we are launching a qemu TCG guest (ie. KVM is known to be
945 disabled or unavailable). If you don't know, don't pass this flag.
946 Note that this function returns a newly allocated buffer which must be
948 freed by the caller.
949 File lib/appliance-uefi.c
951 Find the UEFI firmware needed to boot the appliance.
953 See also lib/uefi.c (autogenerated file) containing the firmware file
955 locations.
956 Function "lib/appliance-uefi.c:guestfs_int_get_uefi"
958 int
960 guestfs_int_get_uefi (guestfs_h *g, char *const *firmwares,
961 const char **firmware, char **code, char **vars,
962 int *flags)
963 Return the location of firmware needed to boot the appliance. This is
965 aarch64 only currently, since that's the only architecture where UEFI
966 is mandatory (and that only for RHEL).
967 "firmwares" is an optional list of allowed values for the firmware
969 autoselection of libvirt. It is "NULL" to indicate it is not supported.
970 *firmware is set to one of the strings in "firmwares" in case one can
971 be used.
972 *code is initialized with the path to the read-only UEFI code file.
974 *vars is initialized with the path to a copy of the UEFI vars file
975 (which is cleaned up automatically on exit).
976 In case a UEFI firmare is available, either *firmware is set to a
978 non-"NULL" value, or *code and *vars are.
979 *code and *vars should be freed by the caller, and *firmware must not.
981 If the function returns "-1" then there was a real error which should
983 cause appliance building to fail (no UEFI firmware is not an error).
984 See also virt-v2v.git/v2v/utils.ml:find_uefi_firmware
986 File lib/appliance.c
988 This file deals with building the libguestfs appliance.
990 Function "lib/appliance.c:guestfs_int_build_appliance"
992 int
994 guestfs_int_build_appliance (guestfs_h *g,
995 char **kernel_rtn,
996 char **initrd_rtn,
997 char **appliance_rtn)
998 Locate or build the appliance.
1000 This function locates or builds the appliance as necessary, handling
1002 the supermin appliance, caching of supermin-built appliances, or using
1003 either a fixed or old-style appliance.
1004 The return value is 0 = good, "-1" = error. Returned in
1006 "appliance.kernel" will be the name of the kernel to use,
1007 "appliance.initrd" the name of the initrd, "appliance.image" the name
1008 of the ext2 root filesystem. "appliance.image" can be "NULL", meaning
1009 that we are using an old-style (non-ext2) appliance. All three strings
1010 must be freed by the caller. However the referenced files themselves
1011 must not be deleted.
1012 The process is as follows:
1014 1. Look in "path" which contains a supermin appliance skeleton. If no
1016 element has this, skip straight to step 3.
1017 2. Call "supermin --build" to build the full appliance (if it needs to
1019 be rebuilt). If this is successful, return the full appliance.
1020 3. Check "path", looking for a fixed appliance. If one is found,
1022 return it.
1023 4. Check "path", looking for an old-style appliance. If one is found,
1025 return it.
1026 The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/
1028 and consists of up to four files:
1029 $TMPDIR/.guestfs-$UID/lock - the supermin lock file
1031 $TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
1032 $TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
1033 $TMPDIR/.guestfs-$UID/appliance.d/root - the appliance
1034 Multiple instances of libguestfs with the same UID may be racing to
1036 create an appliance. However (since supermin ≥ 5) supermin provides a
1037 --lock flag and atomic update of the appliance.d subdirectory.
1038 Function "lib/appliance.c:locate_or_build_appliance"
1040 static int
1042 locate_or_build_appliance (guestfs_h *g,
1043 struct appliance_files *appliance,
1044 const char *path)
1045 Check "path", looking for one of appliances: supermin appliance, fixed
1047 appliance or old-style appliance. If one of the fixed appliances is
1048 found, return it. If the supermin appliance skeleton is found, build
1049 and return appliance.
1050 Return values:
1052 1 = appliance is found, returns C<appliance>,
1054 0 = appliance not found,
1055 -1 = error which aborts the launch process.
1056 Function "lib/appliance.c:search_appliance"
1058 static int
1060 search_appliance (guestfs_h *g, struct appliance_files *appliance)
1061 Search elements of "g->path", returning the first "appliance" element
1063 which matches the predicate function "locate_or_build_appliance".
1064 Return values:
1066 1 = a path element matched, returns C<appliance>,
1068 0 = no path element matched,
1069 -1 = error which aborts the launch process.
1070 Function "lib/appliance.c:build_supermin_appliance"
1072 static int
1074 build_supermin_appliance (guestfs_h *g,
1075 const char *supermin_path,
1076 struct appliance_files *appliance)
1077 Build supermin appliance from "supermin_path" to $TMPDIR/.guestfs-$UID.
1079 Returns: 0 = built or "-1" = error (aborts launch).
1081 Function "lib/appliance.c:run_supermin_build"
1083 static int
1085 run_supermin_build (guestfs_h *g,
1086 const char *lockfile,
1087 const char *appliancedir,
1088 const char *supermin_path)
1089 Run "supermin --build" and tell it to generate the appliance.
1091 Function "lib/appliance.c:dir_contains_file"
1093 static int
1095 dir_contains_file (guestfs_h *g, const char *dir, const char *file)
1096 Returns true iff "file" is contained in "dir".
1098 Function "lib/appliance.c:dir_contains_files"
1100 static int
1102 dir_contains_files (guestfs_h *g, const char *dir, ...)
1103 Returns true iff every listed file is contained in "dir".
1105 File lib/command.c
1107 A wrapper for running external commands, loosely based on libvirt's
1109 "virCommand" interface.
1110 In outline to use this interface you must:
1112 1. Create a new command handle:
1114 struct command *cmd;
1116 cmd = guestfs_int_new_command (g);
1117 2. Either add arguments:
1119 guestfs_int_cmd_add_arg (cmd, "qemu-img");
1121 guestfs_int_cmd_add_arg (cmd, "info");
1122 guestfs_int_cmd_add_arg (cmd, filename);
1123 (NB: You don't need to add a "NULL" argument at the end.)
1125 3. Or construct a command using a mix of quoted and unquoted strings.
1127 (This is useful for system(3)/"popen("r")"-style shell commands,
1128 with the added safety of allowing args to be quoted properly).
1129 guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
1131 guestfs_int_cmd_add_string_quoted (cmd, filename);
1132 4. Set various flags, such as whether you want to capture errors in
1134 the regular libguestfs error log.
1135 5. Run the command. This is what does the fork(2) call, optionally
1137 loops over the output, and then does a waitpid(3) and returns the
1138 exit status of the command.
1139 r = guestfs_int_cmd_run (cmd);
1141 if (r == -1)
1142 // error
1143 // else test r using the WIF* functions
1144 6. Close the handle:
1146 guestfs_int_cmd_close (cmd);
1148 (or use "CLEANUP_CMD_CLOSE").
1150 Function "lib/command.c:guestfs_int_new_command"
1152 struct command *
1154 guestfs_int_new_command (guestfs_h *g)
1155 Create a new command handle.
1157 Function "lib/command.c:guestfs_int_cmd_add_arg"
1159 void
1161 guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)
1162 Add single arg (for "execv"-style command execution).
1164 Function "lib/command.c:guestfs_int_cmd_add_arg_format"
1166 void
1168 guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)
1169 Add single arg (for "execv"-style command execution) using a
1171 printf(3)-style format string.
1172 Function "lib/command.c:guestfs_int_cmd_add_string_unquoted"
1174 void
1176 guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)
1177 Add a string (for system(3)-style command execution).
1179 This variant adds the strings without quoting them, which is dangerous
1181 if the string contains untrusted content.
1182 Function "lib/command.c:guestfs_int_cmd_add_string_quoted"
1184 void
1186 guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)
1187 Add a string (for system(3)-style command execution).
1189 The string is enclosed in double quotes, with any special characters
1191 within the string which need escaping done. This is used to add a
1192 single argument to a system(3)-style command string.
1193 Function "lib/command.c:guestfs_int_cmd_set_stdout_callback"
1195 void
1197 guestfs_int_cmd_set_stdout_callback (struct command *cmd,
1198 cmd_stdout_callback stdout_callback,
1199 void *stdout_data, unsigned flags)
1200 Set a callback which will capture stdout.
1202 If flags contains "CMD_STDOUT_FLAG_LINE_BUFFER" (the default), then the
1204 callback is called line by line on the output. If there is a trailing
1205 "\n" then it is automatically removed before the callback is called.
1206 The line buffer is "\0"-terminated.
1207 If flags contains "CMD_STDOUT_FLAG_UNBUFFERED", then buffers are passed
1209 to the callback as it is received from the command. Note in this case
1210 the buffer is not "\0"-terminated, so you need to may attention to the
1211 length field in the callback.
1212 If flags contains "CMD_STDOUT_FLAG_WHOLE_BUFFER", then the callback is
1214 called exactly once, with the entire buffer. Note in this case the
1215 buffer is not "\0"-terminated, so you need to may attention to the
1216 length field in the callback.
1217 Function "lib/command.c:guestfs_int_cmd_set_stderr_to_stdout"
1219 void
1221 guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)
1222 Equivalent to adding "2>&1" to the end of the command. This is
1224 incompatible with the "capture_errors" flag, because it doesn't make
1225 sense to combine them.
1226 Function "lib/command.c:guestfs_int_cmd_clear_capture_errors"
1228 void
1230 guestfs_int_cmd_clear_capture_errors (struct command *cmd)
1231 Clear the "capture_errors" flag. This means that any errors will go to
1233 stderr, instead of being captured in the event log, and that is usually
1234 undesirable.
1235 Function "lib/command.c:guestfs_int_cmd_clear_close_files"
1237 void
1239 guestfs_int_cmd_clear_close_files (struct command *cmd)
1240 Don't close file descriptors after the fork.
1242 XXX Should allow single fds to be sent to child process.
1244 Function "lib/command.c:guestfs_int_cmd_set_child_callback"
1246 void
1248 guestfs_int_cmd_set_child_callback (struct command *cmd,
1249 cmd_child_callback child_callback,
1250 void *data)
1251 Set a function to be executed in the child, right before the execution.
1253 Can be used to setup the child, for example changing its current
1254 directory.
1255 Function "lib/command.c:guestfs_int_cmd_set_child_rlimit"
1257 void
1259 guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)
1260 Set up child rlimits, in case the process we are running could consume
1262 lots of space or time.
1263 Function "lib/command.c:finish_command"
1265 static void
1267 finish_command (struct command *cmd)
1268 Finish off the command by either "NULL"-terminating the argv array or
1270 adding a terminating "\0" to the string, or die with an internal error
1271 if no command has been added.
1272 Function "lib/command.c:loop"
1274 static int
1276 loop (struct command *cmd)
1277 The loop which reads errors and output and directs it either to the log
1279 or to the stdout callback as appropriate.
1280 Function "lib/command.c:guestfs_int_cmd_run"
1282 int
1284 guestfs_int_cmd_run (struct command *cmd)
1285 Fork, run the command, loop over the output, and waitpid.
1287 Returns the exit status. Test it using "WIF*" macros.
1289 On error: Calls "error" and returns "-1".
1291 Function "lib/command.c:guestfs_int_cmd_pipe_run"
1293 int
1295 guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)
1296 Fork and run the command, but don't wait. Roughly equivalent to
1298 "popen (..., "r"|"w")".
1299 Returns the file descriptor of the pipe, connected to stdout ("r") or
1301 stdin ("w") of the child process.
1302 After reading/writing to this pipe, call "guestfs_int_cmd_pipe_wait" to
1304 wait for the status of the child.
1305 Errors from the subcommand cannot be captured to the error log using
1307 this interface. Instead the caller should call
1308 "guestfs_int_cmd_get_pipe_errors" (after "guestfs_int_cmd_pipe_wait"
1309 returns an error).
1310 Function "lib/command.c:guestfs_int_cmd_pipe_wait"
1312 int
1314 guestfs_int_cmd_pipe_wait (struct command *cmd)
1315 Wait for a subprocess created by "guestfs_int_cmd_pipe_run" to finish.
1317 On error (eg. failed syscall) this returns "-1" and sets the error. If
1318 the subcommand fails, then use "WIF*" macros to check this, and call
1319 "guestfs_int_cmd_get_pipe_errors" to read the error messages printed by
1320 the child.
1321 Function "lib/command.c:guestfs_int_cmd_get_pipe_errors"
1323 char *
1325 guestfs_int_cmd_get_pipe_errors (struct command *cmd)
1326 Read the error messages printed by the child. The caller must free the
1328 returned buffer after use.
1329 Function "lib/command.c:guestfs_int_cmd_close"
1331 void
1333 guestfs_int_cmd_close (struct command *cmd)
1334 Close the "cmd" object and free all resources.
1336 Function "lib/command.c:process_line_buffer"
1338 static void
1340 process_line_buffer (struct command *cmd, int closed)
1341 Deal with buffering stdout for the callback.
1343 File lib/conn-socket.c
1345 This file handles connections to the child process where this is done
1347 over regular POSIX sockets.
1348 Function "lib/conn-socket.c:handle_log_message"
1350 static int
1352 handle_log_message (guestfs_h *g,
1353 struct connection_socket *conn)
1354 This is called if "conn->console_sock" becomes ready to read while we
1356 are doing one of the connection operations above. It reads and deals
1357 with the log message.
1358 Returns:
1360 1 log message(s) were handled successfully
1362 0 connection to appliance closed
1364 "-1"
1366 error
1367 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_listening"
1369 struct connection *
1371 guestfs_int_new_conn_socket_listening (guestfs_h *g,
1372 int daemon_accept_sock,
1373 int console_sock)
1374 Create a new socket connection, listening.
1376 Note that it's OK for "console_sock" to be passed as "-1", meaning
1378 there's no console available for this appliance.
1379 After calling this, "daemon_accept_sock" is owned by the connection,
1381 and will be closed properly either in "accept_connection" or
1382 "free_connection".
1383 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_connected"
1385 struct connection *
1387 guestfs_int_new_conn_socket_connected (guestfs_h *g,
1388 int daemon_sock,
1389 int console_sock)
1390 Create a new socket connection, connected.
1392 As above, but the caller passes us a connected "daemon_sock" and
1394 promises not to call "accept_connection".
1395 File lib/create.c
1397 APIs for creating empty disks.
1399 Mostly this consists of wrappers around the qemu-img(1) program.
1401 Definition "lib/create.c:VALID_FORMAT"
1403 #define VALID_FORMAT
1405 Check for valid backing format. Allow any "^[[:alnum]]+$" (in C
1407 locale), but limit the length to something reasonable.
1408 File lib/drives.c
1410 Drives added are stored in an array in the handle. Code here manages
1412 that array and the individual "struct drive" data.
1413 Function "lib/drives.c:create_overlay"
1415 static int
1417 create_overlay (guestfs_h *g, struct drive *drv)
1418 For readonly drives, create an overlay to protect the original drive
1420 content. Note we never need to clean up these overlays since they are
1421 created in the temporary directory and deleted when the handle is
1422 closed.
1423 Function "lib/drives.c:create_drive_file"
1425 static struct drive *
1427 create_drive_file (guestfs_h *g,
1428 const struct drive_create_data *data)
1429 Create and free the "struct drive".
1431 Function "lib/drives.c:create_drive_dev_null"
1433 static struct drive *
1435 create_drive_dev_null (guestfs_h *g,
1436 struct drive_create_data *data)
1437 Create the special /dev/null drive.
1439 Traditionally you have been able to use /dev/null as a filename, as
1441 many times as you like. Ancient KVM (RHEL 5) cannot handle adding
1442 /dev/null readonly. qemu 1.2 + virtio-scsi segfaults when you use any
1443 zero-sized file including /dev/null.
1444 Because of these problems, we replace /dev/null with a non-zero sized
1446 temporary file. This shouldn't make any difference since users are not
1447 supposed to try and access a null drive.
1448 Function "lib/drives.c:drive_to_string"
1450 static char *
1452 drive_to_string (guestfs_h *g, const struct drive *drv)
1453 Convert a "struct drive" to a string for debugging. The caller must
1455 free this string.
1456 Function "lib/drives.c:add_drive_to_handle_at"
1458 static void
1460 add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)
1461 Add "struct drive" to the "g->drives" vector at the given index
1463 "drv_index". If the array isn't large enough it is reallocated. The
1464 index must not contain a drive already.
1465 Function "lib/drives.c:add_drive_to_handle"
1467 static void
1469 add_drive_to_handle (guestfs_h *g, struct drive *d)
1470 Add struct drive to the end of the "g->drives" vector in the handle.
1472 Function "lib/drives.c:guestfs_int_add_dummy_appliance_drive"
1474 void
1476 guestfs_int_add_dummy_appliance_drive (guestfs_h *g)
1477 Called during launch to add a dummy slot to "g->drives".
1479 Function "lib/drives.c:guestfs_int_free_drives"
1481 void
1483 guestfs_int_free_drives (guestfs_h *g)
1484 Free up all the drives in the handle.
1486 Definition "lib/drives.c:VALID_FORMAT_IFACE"
1488 #define VALID_FORMAT_IFACE
1490 Check string parameter matches regular expression "^[-_[:alnum:]]+$"
1492 (in C locale).
1493 Definition "lib/drives.c:VALID_DISK_LABEL"
1495 #define VALID_DISK_LABEL
1497 Check the disk label is reasonable. It can't contain certain
1499 characters, eg. '/', ','. However be stricter here and ensure it's
1500 just alphabetic and ≤ 20 characters in length.
1501 Definition "lib/drives.c:VALID_HOSTNAME"
1503 #define VALID_HOSTNAME
1505 Check the server hostname is reasonable.
1507 Function "lib/drives.c:valid_port"
1509 static int
1511 valid_port (int port)
1512 Check the port number is reasonable.
1514 Function "lib/drives.c:valid_blocksize"
1516 static int
1518 valid_blocksize (int blocksize)
1519 Check the block size is reasonable. It can't be other then 512 or
1521 4096.
1522 Function "lib/drives.c:guestfs_impl_remove_drive"
1524 int
1526 guestfs_impl_remove_drive (guestfs_h *g, const char *label)
1527 This function implements "guestfs_remove_drive" in guestfs(3).
1529 Depending on whether we are hotplugging or not, this function does
1531 slightly different things: If not hotplugging, then the drive just
1532 disappears as if it had never been added. The later drives "move up"
1533 to fill the space. When hotplugging we have to do some complex stuff,
1534 and we usually end up leaving an empty ("NULL") slot in the "g->drives"
1535 vector.
1536 Function "lib/drives.c:guestfs_int_checkpoint_drives"
1538 size_t
1540 guestfs_int_checkpoint_drives (guestfs_h *g)
1541 Checkpoint and roll back drives, so that groups of drives can be added
1543 atomically. Only used by "guestfs_add_domain" in guestfs(3).
1544 Function "lib/drives.c:guestfs_impl_debug_drives"
1546 char **
1548 guestfs_impl_debug_drives (guestfs_h *g)
1549 Internal function to return the list of drives.
1551 File lib/errors.c
1553 This file handles errors, and also debug, trace and warning messages.
1555 Errors in libguestfs API calls are handled by setting an error message
1557 and optional errno in the handle. The caller has the choice of testing
1558 API calls to find out if they failed and then querying the last error
1559 from the handle, and/or getting a callback.
1560 From the point of view of the library source, generally you should use
1562 the "error" or "perrorf" macros along error paths, eg:
1563 if (something_bad) {
1565 error (g, "something bad happened");
1566 return -1;
1567 }
1568 Make sure to call the "error" or "perrorf" macro exactly once along
1570 each error path, since the handle can only store a single error and the
1571 previous error will be overwritten.
1572 Function "lib/errors.c:guestfs_int_warning"
1574 void
1576 guestfs_int_warning (guestfs_h *g, const char *fs, ...)
1577 Print a warning.
1579 Code should not call this function directly. Use the
1581 "warning (g, fs, ...)" macro.
1582 Warnings are printed unconditionally. We try to make these rare:
1584 Generally speaking, a warning should either be an error, or if it's not
1585 important for end users then it should be a debug message.
1586 Function "lib/errors.c:guestfs_int_debug"
1588 void
1590 guestfs_int_debug (guestfs_h *g, const char *fs, ...)
1591 Print a debug message.
1593 Code should not call this function directly. To add debug messages in
1595 the library, use the "debug (g, fs, ...)" macro. The macro checks if
1596 "g->verbose" is false and avoids the function call, meaning the macro
1597 is more efficient.
1598 Function "lib/errors.c:guestfs_int_trace"
1600 void
1602 guestfs_int_trace (guestfs_h *g, const char *fs, ...)
1603 Print a trace message.
1605 Do not call this function. All calls are generated automatically.
1607 Function "lib/errors.c:guestfs_int_error_errno"
1609 void
1611 guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)
1612 Set the last error and errno in the handle, and optionally raise the
1614 error callback if one is defined.
1615 If you don't need to set errno, use the "error (g, fs, ...)" macro
1617 instead of calling this directly. If you need to set errno then there
1618 is no macro wrapper, so calling this function directly is fine.
1619 Function "lib/errors.c:guestfs_int_perrorf"
1621 void
1623 guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)
1624 Similar to perror(3), but it sets the last error in the handle, raises
1626 the error callback if one is defined, and supports format strings.
1627 You should probably use the "perrorf (g, fs, ...)" macro instead of
1629 calling this directly.
1630 Function "lib/errors.c:guestfs_int_launch_failed_error"
1632 void
1634 guestfs_int_launch_failed_error (guestfs_h *g)
1635 Raise a launch failed error in a standard format.
1637 Since this is the most common error seen by people who have
1639 installation problems, buggy qemu, etc, and since no one reads the FAQ,
1640 describe in this error message what resources are available to debug
1641 launch problems.
1642 Function "lib/errors.c:guestfs_int_unexpected_close_error"
1644 void
1646 guestfs_int_unexpected_close_error (guestfs_h *g)
1647 Raise an error if the appliance unexpectedly crashes after launch.
1649 Function "lib/errors.c:guestfs_int_launch_timeout"
1651 void
1653 guestfs_int_launch_timeout (guestfs_h *g)
1654 Raise an error if the appliance hangs during launch.
1656 Function "lib/errors.c:guestfs_int_external_command_failed"
1658 void
1660 guestfs_int_external_command_failed (guestfs_h *g, int status,
1661 const char *cmd_name, const char *extra)
1662 Raise an error if an external command fails.
1664 "status" is the status code of the command (eg. returned from
1666 waitpid(2) or system(3)). This function turns the status code into an
1667 explanatory string.
1668 File lib/events.c
1670 Function "lib/events.c:replace_old_style_event_callback"
1672 static void
1674 replace_old_style_event_callback (guestfs_h *g,
1675 guestfs_event_callback cb,
1676 uint64_t event_bitmask,
1677 void *opaque,
1678 void *opaque2)
1679 Emulate old-style callback API.
1681 There were no event handles, so multiple callbacks per event were not
1683 supported. Calling the same "guestfs_set_*_callback" function would
1684 replace the existing event. Calling it with "cb == NULL" meant that
1685 the caller wanted to remove the callback.
1686 File lib/guestfs-internal-all.h
1688 This header contains definitions which are shared by all parts of
1690 libguestfs, ie. the daemon, the library, language bindings and virt
1691 tools (ie. all C code).
1692 If you need a definition used by only the library, put it in
1694 lib/guestfs-internal.h instead.
1695 If a definition is used by only a single tool, it should not be in any
1697 shared header file at all.
1698 File lib/guestfs-internal.h
1700 This header file is included in the libguestfs library (lib/) only.
1702 See also lib/guestfs-internal-all.h.
1704 Structure "lib/guestfs-internal.h:event"
1706 struct event {
1708 uint64_t event_bitmask;
1709 guestfs_event_callback cb;
1710 void *opaque;
1711 /* opaque2 is not exposed through the API, but is used internally to
1713 * emulate the old-style callback API.
1714 */
1715 void *opaque2;
1716 };
1717 This struct is used to maintain a list of events registered against the
1719 handle. See "g->events" in the handle.
1720 Structure "lib/guestfs-internal.h:drive"
1722 struct drive {
1724 /* Original source of the drive, eg. file:..., http:... */
1725 struct drive_source src;
1726 /* If the drive is readonly, then an overlay [a local file] is
1728 * created before launch to protect the original drive content, and
1729 * the filename is stored here. Backends should open this file if
1730 * it is non-NULL, else consult the original source above.
1731 *
1732 * Note that the overlay is in a backend-specific format, probably
1733 * different from the source format. eg. qcow2, UML COW.
1734 */
1735 char *overlay;
1736 /* Various per-drive flags. */
1738 bool readonly;
1739 char *iface;
1740 char *name;
1741 char *disk_label;
1742 char *cachemode;
1743 enum discard discard;
1744 bool copyonread;
1745 int blocksize;
1746 };
1747 There is one "struct drive" per drive, including hot-plugged drives.
1749 Structure "lib/guestfs-internal.h:backend_ops"
1751 struct backend_ops {
1753 /* Size (in bytes) of the per-handle data structure needed by this
1754 * backend. The data pointer is allocated and freed by libguestfs
1755 * and passed to the functions in the 'void *data' parameter.
1756 * Inside the data structure is opaque to libguestfs. Any strings
1757 * etc pointed to by it must be freed by the backend during
1758 * shutdown.
1759 */
1760 size_t data_size;
1761 /* Create a COW overlay on top of a drive. This must be a local
1763 * file, created in the temporary directory. This is called when
1764 * the drive is added to the handle.
1765 */
1766 char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);
1767 /* Launch and shut down. */
1769 int (*launch) (guestfs_h *g, void *data, const char *arg);
1770 int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);
1771 /* Miscellaneous. */
1773 int (*get_pid) (guestfs_h *g, void *data);
1774 int (*max_disks) (guestfs_h *g, void *data);
1775 /* Hotplugging drives. */
1777 int (*hot_add_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1778 int (*hot_remove_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1779 };
1780 Backend operations.
1782 Each backend (eg. libvirt, direct) defines some functions which get run
1784 at various places in the handle lifecycle (eg. at launch, shutdown).
1785 The backend defines this struct pointing to those functions.
1786 Structure "lib/guestfs-internal.h:connection"
1788 struct connection {
1790 const struct connection_ops *ops;
1791 /* In the real struct, private data used by each connection module
1793 * follows here.
1794 */
1795 };
1796 Connection module.
1798 A "connection" represents the appliance console connection plus the
1800 daemon connection. It hides the underlying representation (POSIX
1801 sockets, "virStreamPtr").
1802 Structure "lib/guestfs-internal.h:cached_feature"
1804 struct cached_feature {
1806 char *group;
1807 int result;
1808 };
1809 Cache of queried features.
1811 Used to cache the appliance features (see lib/available.c).
1813 Structure "lib/guestfs-internal.h:guestfs_h"
1815 struct guestfs_h {
1817 struct guestfs_h *next; /* Linked list of open handles. */
1818 enum state state; /* See the state machine diagram in guestfs(3)*/
1819 /* Lock acquired when entering any public guestfs_* function to
1821 * protect the handle.
1822 */
1823 gl_recursive_lock_define (, lock);
1824 /**** Configuration of the handle. ****/
1826 bool verbose; /* Debugging. */
1827 bool trace; /* Trace calls. */
1828 bool autosync; /* Autosync. */
1829 bool direct_mode; /* Direct mode. */
1830 bool recovery_proc; /* Create a recovery process. */
1831 bool enable_network; /* Enable the network. */
1832 bool selinux; /* selinux enabled? */
1833 bool pgroup; /* Create process group for children? */
1834 bool close_on_exit; /* Is this handle on the atexit list? */
1835 int smp; /* If > 1, -smp flag passed to hv. */
1837 int memsize; /* Size of RAM (megabytes). */
1838 char *path; /* Path to the appliance. */
1840 char *hv; /* Hypervisor (HV) binary. */
1841 char *append; /* Append to kernel command line. */
1842 struct hv_param *hv_params; /* Extra hv parameters. */
1844 char *program; /* Program name. */
1846 char *identifier; /* Handle identifier. */
1847 /* Array of drives added by add-drive* APIs.
1849 *
1850 * Before launch this list can be empty or contain some drives.
1851 *
1852 * During launch, a dummy slot may be added which represents the
1853 * slot taken up by the appliance drive.
1854 *
1855 * When hotplugging is supported by the backend, drives can be
1856 * added to the end of this list after launch. Also hot-removing a
1857 * drive causes a NULL slot to appear in the list.
1858 *
1859 * During shutdown, this list is deleted, so that each launch gets a
1860 * fresh set of drives (however callers: don't do this, create a new
1861 * handle each time).
1862 *
1863 * Always use ITER_DRIVES macro to iterate over this list!
1864 */
1865 struct drive **drives;
1866 size_t nr_drives;
1867 #define ITER_DRIVES(g,i,drv) \
1869 for (i = 0; i < (g)->nr_drives; ++i) \
1870 if (((drv) = (g)->drives[i]) != NULL)
1871 /* Backend. NB: Use guestfs_int_set_backend to change the backend. */
1873 char *backend; /* The full string, always non-NULL. */
1874 char *backend_arg; /* Pointer to the argument part. */
1875 const struct backend_ops *backend_ops;
1876 void *backend_data; /* Per-handle data. */
1877 char **backend_settings; /* Backend settings (can be NULL). */
1878 /**** Runtime information. ****/
1880 /* Temporary and cache directories. */
1881 /* The actual temporary directory - this is not created with the
1882 * handle, you have to call guestfs_int_lazy_make_tmpdir.
1883 */
1884 char *tmpdir;
1885 char *sockdir;
1886 /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
1887 char *env_tmpdir; /* $TMPDIR (NULL if not set) */
1888 char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/
1889 char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
1890 char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */
1891 /* Error handler, plus stack of old error handlers. */
1893 gl_tls_key_t error_data;
1894 /* Linked list of error_data structures allocated for this handle,
1896 * plus a mutex to protect the linked list.
1897 */
1898 gl_lock_define (, error_data_list_lock);
1899 struct error_data *error_data_list;
1900 /* Out of memory error handler. */
1902 guestfs_abort_cb abort_cb;
1903 /* Events. */
1905 struct event *events;
1906 size_t nr_events;
1907 /* Private data area. */
1909 struct hash_table *pda;
1910 struct pda_entry *pda_next;
1911 /* User cancelled transfer. Not signal-atomic, but it doesn't
1913 * matter for this case because we only care if it is != 0.
1914 */
1915 int user_cancel;
1916 struct timeval launch_t; /* The time that we called guestfs_launch. */
1918 /* Used by bindtests. */
1920 FILE *test_fp;
1921 /* Used to generate unique numbers, eg for temp files. To use this,
1923 * '++g->unique'. Note these are only unique per-handle, not
1924 * globally unique.
1925 */
1926 int unique;
1927 /*** Protocol. ***/
1929 struct connection *conn; /* Connection to appliance. */
1930 int msg_next_serial;
1931 #if HAVE_FUSE
1933 /**** Used by the mount-local APIs. ****/
1934 char *localmountpoint;
1935 struct fuse *fuse; /* FUSE handle. */
1936 int ml_dir_cache_timeout; /* Directory cache timeout. */
1937 Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
1938 int ml_read_only; /* If mounted read-only. */
1939 int ml_debug_calls; /* Extra debug info on each FUSE call. */
1940 #endif
1941 #ifdef HAVE_LIBVIRT_BACKEND
1943 /* Used by lib/libvirt-auth.c. */
1944 #define NR_CREDENTIAL_TYPES 9
1945 unsigned int nr_supported_credentials;
1946 int supported_credentials[NR_CREDENTIAL_TYPES];
1947 const char *saved_libvirt_uri; /* Doesn't need to be freed. */
1948 bool wrapper_warning_done;
1949 unsigned int nr_requested_credentials;
1950 virConnectCredentialPtr requested_credentials;
1951 #endif
1952 /* Cached features. */
1954 struct cached_feature *features;
1955 size_t nr_features;
1956 /* Used by lib/info.c. -1 = not tested or error; else 0 or 1. */
1958 int qemu_img_supports_U_option;
1959 };
1960 The libguestfs handle.
1962 Structure "lib/guestfs-internal.h:version"
1964 struct version {
1966 int v_major;
1967 int v_minor;
1968 int v_micro;
1969 };
1970 Used for storing major.minor.micro version numbers. See lib/version.c
1972 for more information.
1973 File lib/guid.c
1975 Function "lib/guid.c:guestfs_int_validate_guid"
1977 int
1979 guestfs_int_validate_guid (const char *str)
1980 Check whether a string supposed to contain a GUID actually contains it.
1982 It can recognize strings either as
1983 "{21EC2020-3AEA-1069-A2DD-08002B30309D}" or
1984 "21EC2020-3AEA-1069-A2DD-08002B30309D".
1985 File lib/handle.c
1987 This file deals with the "guestfs_h" handle, creating it, closing it,
1989 and initializing/setting/getting fields.
1990 Function "lib/handle.c:init_libguestfs"
1992 static void
1994 init_libguestfs (void)
1995 No initialization is required by libguestfs, but libvirt and libxml2
1997 require initialization if they might be called from multiple threads.
1998 Hence this constructor function which is called when libguestfs is
1999 first loaded.
2000 Function "lib/handle.c:shutdown_backend"
2002 static int
2004 shutdown_backend (guestfs_h *g, int check_for_errors)
2005 This function is the common path for shutting down the backend qemu
2007 process.
2008 "guestfs_shutdown" calls "shutdown_backend" with "check_for_errors=1".
2010 "guestfs_close" calls "shutdown_backend" with "check_for_errors=0".
2011 "check_for_errors" is a hint to the backend about whether we care about
2013 errors or not. In the libvirt case it can be used to optimize the
2014 shutdown for speed when we don't care.
2015 Function "lib/handle.c:close_handles"
2017 static void
2019 close_handles (void)
2020 Close all open handles (called from atexit(3)).
2022 Function "lib/handle.c:guestfs_int_get_backend_setting_bool"
2024 int
2026 guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)
2027 This is a convenience function, but we might consider exporting it as
2029 an API in future.
2030 File lib/info.c
2032 Function "lib/info.c:qemu_img_supports_U_option"
2034 static int
2036 qemu_img_supports_U_option (guestfs_h *g)
2037 Test if the qemu-img info command supports the "-U" option to disable
2039 locking. The result is memoized in the handle.
2040 Note this option was added in qemu 2.11. We can remove this test when
2042 we can assume everyone is using qemu >= 2.11.
2043 File lib/inspect-icon.c
2045 Function "lib/inspect-icon.c:guestfs_int_download_to_tmp"
2047 char *
2049 guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
2050 const char *extension,
2051 uint64_t max_size)
2052 Download a guest file to a local temporary file.
2054 The name of the temporary (downloaded) file is returned. The caller
2056 must free the pointer, but does not need to delete the temporary file.
2057 It will be deleted when the handle is closed.
2058 The name of the temporary file is randomly generated, but an extension
2060 can be specified using "extension" (or pass "NULL" for none).
2061 Refuse to download the guest file if it is larger than "max_size". On
2063 this and other errors, "NULL" is returned.
2064 File lib/launch-direct.c
2066 Implementation of the "direct" backend.
2068 For more details see "BACKENDS" in guestfs(3).
2070 Function "lib/launch-direct.c:add_drive_standard_params"
2072 static int
2074 add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
2075 struct qemuopts *qopts,
2076 size_t i, struct drive *drv)
2077 Add the standard elements of the "-drive" parameter.
2079 Function "lib/launch-direct.c:add_device_blocksize_params"
2081 static int
2083 add_device_blocksize_params (guestfs_h *g, struct qemuopts *qopts,
2084 struct drive *drv)
2085 Add the physical_block_size and logical_block_size elements of the
2087 "-device" parameter.
2088 File lib/launch-libvirt.c
2090 Function "lib/launch-libvirt.c:get_source_format_or_autodetect"
2092 static char *
2094 get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)
2095 Return "drv->src.format", but if it is "NULL", autodetect the format.
2097 libvirt has disabled the feature of detecting the disk format, unless
2099 the administrator sets "allow_disk_format_probing=1" in
2100 /etc/libvirt/qemu.conf. There is no way to detect if this option is
2101 set, so we have to do format detection here using "qemu-img" and pass
2102 that to libvirt.
2103 This can still be a security issue, so in most cases it is recommended
2105 the users pass the format to libguestfs which will faithfully pass that
2106 straight through to libvirt without doing autodetection.
2107 Caller must free the returned string. On error this function sets the
2109 error in the handle and returns "NULL".
2110 Function "lib/launch-libvirt.c:make_qcow2_overlay"
2112 static char *
2114 make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
2115 const char *format)
2116 Create a qcow2 format overlay, with the given "backing_drive" (file).
2118 The "format" parameter is the backing file format. The "format"
2119 parameter can be NULL, in this case the backing format will be
2120 determined automatically. This is used to create the appliance
2121 overlay, and also for read-only drives.
2122 File lib/launch.c
2124 This file implements "guestfs_launch" in guestfs(3).
2126 Most of the work is done by the backends (see "BACKEND" in guestfs(3)),
2128 which are implemented in lib/launch-direct.c, lib/launch-libvirt.c etc,
2129 so this file mostly passes calls through to the current backend.
2130 Function "lib/launch.c:guestfs_int_launch_send_progress"
2132 void
2134 guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)
2135 This function sends a launch progress message.
2137 Launching the appliance generates approximate progress messages.
2139 Currently these are defined as follows:
2140 0 / 12: launch clock starts
2142 3 / 12: appliance created
2143 6 / 12: detected that guest kernel started
2144 9 / 12: detected that /init script is running
2145 12 / 12: launch completed successfully
2146 Notes:
2148 1. This is not a documented ABI and the behaviour may be changed or
2150 removed in future.
2151 2. Messages are only sent if more than 5 seconds has elapsed since the
2153 launch clock started.
2154 3. There is a hack in lib/proto.c to make this work.
2156 Function "lib/launch.c:guestfs_int_timeval_diff"
2158 int64_t
2160 guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)
2161 Compute "y - x" and return the result in milliseconds.
2163 Approximately the same as this code:
2165 http://www.mpp.mpg.de/~huber/util/timevaldiff.c
2166 Function "lib/launch.c:guestfs_int_unblock_sigterm"
2168 void
2170 guestfs_int_unblock_sigterm (void)
2171 Unblock the "SIGTERM" signal. Call this after fork(2) so that the
2173 parent process can send "SIGTERM" to the child process in case
2174 "SIGTERM" is blocked. See https://bugzilla.redhat.com/1460338.
2175 Function "lib/launch.c:guestfs_impl_max_disks"
2177 int
2179 guestfs_impl_max_disks (guestfs_h *g)
2180 Returns the maximum number of disks allowed to be added to the backend
2182 (backend dependent).
2183 Function "lib/launch.c:guestfs_impl_wait_ready"
2185 int
2187 guestfs_impl_wait_ready (guestfs_h *g)
2188 Implementation of "guestfs_wait_ready" in guestfs(3). You had to call
2190 this function after launch in versions ≤ 1.0.70, but it is now an
2191 (almost) no-op.
2192 Function "lib/launch.c:guestfs_int_create_socketname"
2194 int
2196 guestfs_int_create_socketname (guestfs_h *g, const char *filename,
2197 char (*sockpath)[UNIX_PATH_MAX])
2198 Create the path for a socket with the selected filename in the tmpdir.
2200 Function "lib/launch.c:guestfs_int_register_backend"
2202 void
2204 guestfs_int_register_backend (const char *name, const struct backend_ops *ops)
2205 When the library is loaded, each backend calls this function to
2207 register itself in a global list.
2208 Function "lib/launch.c:guestfs_int_set_backend"
2210 int
2212 guestfs_int_set_backend (guestfs_h *g, const char *method)
2213 Implementation of "guestfs_set_backend" in guestfs(3).
2215 · Callers must ensure this is only called in the config state.
2217 · This shouldn't call "error" since it may be called early in handle
2219 initialization. It can return an error code however.
2220 File lib/private-data.c
2222 Implement a private data area where libguestfs C API users can attach
2224 arbitrary pieces of data to a "guestfs_h" handle.
2225 For more information see "PRIVATE DATA AREA" in guestfs(3).
2227 Language bindings do not generally expose this, largely because in non-
2229 C languages it is easy to associate data with handles in other ways
2230 (using hash tables or maps).
2231 Structure "lib/private-data.c:pda_entry"
2233 struct pda_entry {
2235 char *key; /* key */
2236 void *data; /* opaque user data pointer */
2237 };
2238 The private data area is internally stored as a gnulib hash table
2240 containing "pda_entry" structures.
2241 Note the private data area is allocated lazily, since the vast majority
2243 of callers will never use it. This means "g->pda" is likely to be
2244 "NULL".
2245 File lib/proto.c
2247 This is the code used to send and receive RPC messages and (for certain
2249 types of message) to perform file transfers. This code is driven from
2250 the generated actions (lib/actions-*.c). There are five different
2251 cases to consider:
2252 1. A non-daemon function (eg. "guestfs_set_verbose" in guestfs(3)).
2254 There is no RPC involved at all, it's all handled inside the
2255 library.
2256 2. A simple RPC (eg. "guestfs_mount" in guestfs(3)). We write the
2258 request, then read the reply. The sequence of calls is:
2259 guestfs_int_send
2261 guestfs_int_recv
2262 3. An RPC with "FileIn" parameters (eg. "guestfs_upload" in
2264 guestfs(3)). We write the request, then write the file(s), then
2265 read the reply. The sequence of calls is:
2266 guestfs_int_send
2268 guestfs_int_send_file (possibly multiple times)
2269 guestfs_int_recv
2270 4. An RPC with "FileOut" parameters (eg. "guestfs_download" in
2272 guestfs(3)). We write the request, then read the reply, then read
2273 the file(s). The sequence of calls is:
2274 guestfs_int_send
2276 guestfs_int_recv
2277 guestfs_int_recv_file (possibly multiple times)
2278 5. Both "FileIn" and "FileOut" parameters. There are no calls like
2280 this in the current API, but they would be implemented as a
2281 combination of cases 3 and 4.
2282 All read/write/etc operations are performed using the current
2284 connection module ("g->conn"). During operations the connection module
2285 transparently handles log messages that appear on the console.
2286 Function "lib/proto.c:child_cleanup"
2288 static void
2290 child_cleanup (guestfs_h *g)
2291 This is called if we detect EOF, ie. qemu died.
2293 Function "lib/proto.c:guestfs_int_progress_message_callback"
2295 void
2297 guestfs_int_progress_message_callback (guestfs_h *g,
2298 const guestfs_progress *message)
2299 Convenient wrapper to generate a progress message callback.
2301 Function "lib/proto.c:guestfs_int_log_message_callback"
2303 void
2305 guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)
2306 Connection modules call us back here when they get a log message.
2308 Function "lib/proto.c:check_daemon_socket"
2310 static ssize_t
2312 check_daemon_socket (guestfs_h *g)
2313 Before writing to the daemon socket, check the read side of the daemon
2315 socket for any of these conditions:
2316 error
2318 return -1
2319 daemon cancellation message
2321 return -2
2322 progress message
2324 handle it here
2325 end of input or appliance exited unexpectedly
2327 return 0
2328 anything else
2330 return 1
2331 Function "lib/proto.c:guestfs_int_send_file"
2333 int
2335 guestfs_int_send_file (guestfs_h *g, const char *filename)
2336 Send a file.
2338 Returns 0 on success, "-1" for error, "-2" if the daemon cancelled (we
2340 must read the error message).
2341 Function "lib/proto.c:send_file_data"
2343 static int
2345 send_file_data (guestfs_h *g, const char *buf, size_t len)
2346 Send a chunk of file data.
2348 Function "lib/proto.c:send_file_cancellation"
2350 static int
2352 send_file_cancellation (guestfs_h *g)
2353 Send a cancellation message.
2355 Function "lib/proto.c:send_file_complete"
2357 static int
2359 send_file_complete (guestfs_h *g)
2360 Send a file complete chunk.
2362 Function "lib/proto.c:recv_from_daemon"
2364 static int
2366 recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)
2367 This function reads a single message, file chunk, launch flag or
2369 cancellation flag from the daemon. If something was read, it returns
2370 0, otherwise "-1".
2371 Both "size_rtn" and "buf_rtn" must be passed by the caller as non-NULL.
2373 *size_rtn returns the size of the returned message or it may be
2375 "GUESTFS_LAUNCH_FLAG" or "GUESTFS_CANCEL_FLAG".
2376 *buf_rtn is returned containing the message (if any) or will be set to
2378 "NULL". *buf_rtn must be freed by the caller.
2379 This checks for EOF (appliance died) and passes that up through the
2381 child_cleanup function above.
2382 Log message, progress messages are handled transparently here.
2384 Function "lib/proto.c:guestfs_int_recv"
2386 int
2388 guestfs_int_recv (guestfs_h *g, const char *fn,
2389 guestfs_message_header *hdr,
2390 guestfs_message_error *err,
2391 xdrproc_t xdrp, char *ret)
2392 Receive a reply.
2394 Function "lib/proto.c:guestfs_int_recv_discard"
2396 int
2398 guestfs_int_recv_discard (guestfs_h *g, const char *fn)
2399 Same as "guestfs_int_recv", but it discards the reply message.
2401 Notes (XXX):
2403 · This returns an int, but all current callers ignore it.
2405 · The error string may end up being set twice on error paths.
2407 Function "lib/proto.c:guestfs_int_recv_file"
2409 int
2411 guestfs_int_recv_file (guestfs_h *g, const char *filename)
2412 Returns "-1" = error, 0 = EOF, ">0" = more data
2414 Function "lib/proto.c:receive_file_data"
2416 static ssize_t
2418 receive_file_data (guestfs_h *g, void **buf_r)
2419 Receive a chunk of file data.
2421 Returns "-1" = error, 0 = EOF, ">0" = more data
2423 File lib/qemu.c
2425 Functions to handle qemu versions and features.
2427 Function "lib/qemu.c:guestfs_int_test_qemu"
2429 struct qemu_data *
2431 guestfs_int_test_qemu (guestfs_h *g)
2432 Test that the qemu binary (or wrapper) runs, and do "qemu -help" and
2434 other commands so we can find out the version of qemu and what options
2435 this qemu supports.
2436 This caches the results in the cachedir so that as long as the qemu
2438 binary does not change, calling this is effectively free.
2439 Function "lib/qemu.c:cache_filename"
2441 static char *
2443 cache_filename (guestfs_h *g, const char *cachedir,
2444 const struct stat *statbuf, const char *suffix)
2445 Generate the filenames, for the stat file and the other cache files.
2447 By including the size and mtime in the filename we also ensure that the
2449 same user can use multiple versions of qemu without conflicts.
2450 Function "lib/qemu.c:parse_qemu_version"
2452 static void
2454 parse_qemu_version (guestfs_h *g, const char *qemu_help,
2455 struct version *qemu_version)
2456 Parse the first line of "qemu_help" into the major and minor version of
2458 qemu, but don't fail if parsing is not possible.
2459 Function "lib/qemu.c:parse_json"
2461 static void
2463 parse_json (guestfs_h *g, const char *json, json_t **treep)
2464 Parse the json output from QMP. But don't fail if parsing is not
2466 possible.
2467 Function "lib/qemu.c:parse_has_kvm"
2469 static void
2471 parse_has_kvm (guestfs_h *g, const char *json, bool *ret)
2472 Parse the json output from QMP query-kvm to find out if KVM is enabled
2474 on this machine. Don't fail if parsing is not possible, assume KVM is
2475 available.
2476 The JSON output looks like: {"return": {"enabled": true, "present":
2478 true}}
2479 Function "lib/qemu.c:generic_read_cache"
2481 static int
2483 generic_read_cache (guestfs_h *g, const char *filename, char **strp)
2484 Generic functions for reading and writing the cache files, used where
2486 we are just reading and writing plain text strings.
2487 Function "lib/qemu.c:generic_qmp_test"
2489 static int
2491 generic_qmp_test (guestfs_h *g, struct qemu_data *data,
2492 const char *qmp_command,
2493 char **outp)
2494 Run a generic QMP test on the QEMU binary.
2496 Function "lib/qemu.c:guestfs_int_qemu_version"
2498 struct version
2500 guestfs_int_qemu_version (guestfs_h *g, struct qemu_data *data)
2501 Return the parsed version of qemu.
2503 Function "lib/qemu.c:guestfs_int_qemu_supports"
2505 int
2507 guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data,
2508 const char *option)
2509 Test if option is supported by qemu command line (just by grepping the
2511 help text).
2512 Function "lib/qemu.c:guestfs_int_qemu_supports_device"
2514 int
2516 guestfs_int_qemu_supports_device (guestfs_h *g,
2517 const struct qemu_data *data,
2518 const char *device_name)
2519 Test if device is supported by qemu (currently just greps the "qemu
2521 -device ?" output).
2522 Function "lib/qemu.c:guestfs_int_qemu_mandatory_locking"
2524 int
2526 guestfs_int_qemu_mandatory_locking (guestfs_h *g,
2527 const struct qemu_data *data)
2528 Test if the qemu binary uses mandatory file locking, added in QEMU >=
2530 2.10 (but sometimes disabled).
2531 Function "lib/qemu.c:guestfs_int_qemu_escape_param"
2533 char *
2535 guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)
2536 Escape a qemu parameter.
2538 Every "," becomes ",,". The caller must free the returned string.
2540 XXX This functionality is now only used when constructing a qemu-img
2542 command in lib/create.c. We should extend the qemuopts library to
2543 cover this use case.
2544 Function "lib/qemu.c:guestfs_int_drive_source_qemu_param"
2546 char *
2548 guestfs_int_drive_source_qemu_param (guestfs_h *g,
2549 const struct drive_source *src)
2550 Useful function to format a drive + protocol for qemu.
2552 Note that the qemu parameter is the bit after "file=". It is not
2554 escaped here, but would usually be escaped if passed to qemu as part of
2555 a full -drive parameter (but not for qemu-img(1)).
2556 Function "lib/qemu.c:guestfs_int_discard_possible"
2558 bool
2560 guestfs_int_discard_possible (guestfs_h *g, struct drive *drv,
2561 const struct version *qemu_version)
2562 Test if discard is both supported by qemu AND possible with the
2564 underlying file or device. This returns 1 if discard is possible. It
2565 returns 0 if not possible and sets the error to the reason why.
2566 This function is called when the user set "discard == "enable"".
2568 Function "lib/qemu.c:guestfs_int_free_qemu_data"
2570 void
2572 guestfs_int_free_qemu_data (struct qemu_data *data)
2573 Free the "struct qemu_data".
2575 File lib/rescue.c
2577 Support for virt-rescue(1).
2579 File lib/stringsbuf.c
2581 An expandable NULL-terminated vector of strings (like "argv").
2583 Use the "DECLARE_STRINGSBUF" macro to declare the stringsbuf.
2585 Note: Don't confuse this with stringsbuf in the daemon which is a
2587 different type with different methods.
2588 Function "lib/stringsbuf.c:guestfs_int_add_string_nodup"
2590 void
2592 guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)
2593 Add a string to the end of the list.
2595 This doesn't call strdup(3) on the string, so the string itself is
2597 stored inside the vector.
2598 Function "lib/stringsbuf.c:guestfs_int_add_string"
2600 void
2602 guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)
2603 Add a string to the end of the list.
2605 This makes a copy of the string.
2607 Function "lib/stringsbuf.c:guestfs_int_add_sprintf"
2609 void
2611 guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
2612 const char *fs, ...)
2613 Add a string to the end of the list.
2615 Uses an sprintf-like format string when creating the string.
2617 Function "lib/stringsbuf.c:guestfs_int_end_stringsbuf"
2619 void
2621 guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)
2622 Finish the string buffer.
2624 This adds the terminating NULL to the end of the vector.
2626 Function "lib/stringsbuf.c:guestfs_int_free_stringsbuf"
2628 void
2630 guestfs_int_free_stringsbuf (struct stringsbuf *sb)
2631 Free the string buffer and the strings.
2633 File lib/tmpdirs.c
2635 Handle temporary directories.
2637 Function "lib/tmpdirs.c:set_abs_path"
2639 static int
2641 set_abs_path (guestfs_h *g, const char *ctxstr,
2642 const char *tmpdir, char **tmpdir_ret)
2643 We need to make all tmpdir paths absolute because lots of places in the
2645 code assume this. Do it at the time we set the path or read the
2646 environment variable (https://bugzilla.redhat.com/882417).
2647 The "ctxstr" parameter is a string displayed in error messages giving
2649 the context of the operation (eg. name of environment variable being
2650 used, or API function being called).
2651 Function "lib/tmpdirs.c:guestfs_impl_get_tmpdir"
2653 char *
2655 guestfs_impl_get_tmpdir (guestfs_h *g)
2656 Implements the "guestfs_get_tmpdir" API.
2658 Note this actually calculates the tmpdir, so it never returns "NULL".
2660 Function "lib/tmpdirs.c:guestfs_impl_get_cachedir"
2662 char *
2664 guestfs_impl_get_cachedir (guestfs_h *g)
2665 Implements the "guestfs_get_cachedir" API.
2667 Note this actually calculates the cachedir, so it never returns "NULL".
2669 Function "lib/tmpdirs.c:guestfs_impl_get_sockdir"
2671 char *
2673 guestfs_impl_get_sockdir (guestfs_h *g)
2674 Implements the "guestfs_get_sockdir" API.
2676 Note this actually calculates the sockdir, so it never returns "NULL".
2678 Function "lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir"
2680 int
2682 guestfs_int_lazy_make_tmpdir (guestfs_h *g)
2683 The "g->tmpdir" (per-handle temporary directory) is not created when
2685 the handle is created. Instead we create it lazily before the first
2686 time it is used, or during launch.
2687 Function "lib/tmpdirs.c:guestfs_int_make_temp_path"
2689 char *
2691 guestfs_int_make_temp_path (guestfs_h *g,
2692 const char *name, const char *extension)
2693 Generate unique temporary paths for temporary files.
2695 Returns a unique path or NULL on error.
2697 Function "lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir"
2699 char *
2701 guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)
2702 Create the supermin appliance directory under cachedir, if it does not
2704 exist.
2705 Sanity-check that the permissions on the cachedir are safe, in case it
2707 has been pre-created maliciously or tampered with.
2708 Returns the directory name which the caller must free.
2710 Function "lib/tmpdirs.c:guestfs_int_recursive_remove_dir"
2712 void
2714 guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)
2715 Recursively remove a temporary directory. If removal fails, just
2717 return (it's a temporary directory so it'll eventually be cleaned up by
2718 a temp cleaner).
2719 This is implemented using "rm -rf" because that's simpler and safer.
2721 File lib/umask.c
2723 Return current umask in a thread-safe way.
2725 glibc documents, but does not actually implement, a "getumask(3)" call.
2727 We use "Umask" from /proc/self/status for Linux ≥ 4.7. For older Linux
2729 and other Unix, this file implements an expensive but thread-safe way
2730 to get the current process's umask.
2731 Thanks to: Josh Stone, Jiri Jaburek, Eric Blake.
2733 Function "lib/umask.c:guestfs_int_getumask"
2735 int
2737 guestfs_int_getumask (guestfs_h *g)
2738 Returns the current process's umask. On failure, returns "-1" and sets
2740 the error in the guestfs handle.
2741 Function "lib/umask.c:get_umask_from_proc"
2743 static int
2745 get_umask_from_proc (guestfs_h *g)
2746 For Linux ≥ 4.7 get the umask from /proc/self/status.
2748 On failure this returns "-1". However if we could not open the /proc
2750 file or find the "Umask" entry in it, return "-2" which causes the
2751 fallback path to run.
2752 Function "lib/umask.c:get_umask_from_fork"
2754 static int
2756 get_umask_from_fork (guestfs_h *g)
2757 Fallback method of getting the umask using fork.
2759 File lib/unit-tests.c
2761 Unit tests of internal functions.
2763 These tests may use a libguestfs handle, but must not launch the
2765 handle. Also, avoid long-running tests.
2766 Function "lib/unit-tests.c:test_split"
2768 static void
2770 test_split (void)
2771 Test "guestfs_int_split_string".
2773 Function "lib/unit-tests.c:test_concat"
2775 static void
2777 test_concat (void)
2778 Test "guestfs_int_concat_strings".
2780 Function "lib/unit-tests.c:test_join"
2782 static void
2784 test_join (void)
2785 Test "guestfs_int_join_strings".
2787 Function "lib/unit-tests.c:test_validate_guid"
2789 static void
2791 test_validate_guid (void)
2792 Test "guestfs_int_validate_guid".
2794 Function "lib/unit-tests.c:test_drive_name"
2796 static void
2798 test_drive_name (void)
2799 Test "guestfs_int_drive_name".
2801 Function "lib/unit-tests.c:test_drive_index"
2803 static void
2805 test_drive_index (void)
2806 Test "guestfs_int_drive_index".
2808 Function "lib/unit-tests.c:test_getumask"
2810 static void
2812 test_getumask (void)
2813 Test "guestfs_int_getumask".
2815 Function "lib/unit-tests.c:test_command"
2817 static void
2819 test_command (void)
2820 Test "guestfs_int_new_command" etc.
2822 XXX These tests could be made much more thorough. So far we simply
2824 test that it's not obviously broken.
2825 Function "lib/unit-tests.c:test_qemu_escape_param"
2827 static void
2829 test_qemu_escape_param (void)
2830 Test "guestfs_int_qemu_escape_param"
2832 XXX I wanted to make this test run qemu, passing some parameters which
2834 need to be escaped, but I cannot think of a way to do that without
2835 launching a VM.
2836 Function "lib/unit-tests.c:test_timeval_diff"
2838 static void
2840 test_timeval_diff (void)
2841 Test "guestfs_int_timeval_diff".
2843 File lib/version.c
2845 This file provides simple version number management.
2847 Function "lib/version.c:guestfs_int_version_from_x_y"
2849 int
2851 guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)
2852 Parses a version from a string, looking for a "X.Y" pattern.
2854 Returns "-1" on failure (like failed integer parsing), 0 on missing
2856 match, and 1 on match and successful parsing. "v" is changed only on
2857 successful match.
2858 Function "lib/version.c:guestfs_int_version_from_x_y_re"
2860 int
2862 guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
2863 const char *str, const pcre *re)
2864 Parses a version from a string, using the specified "re" as regular
2866 expression which must provide (at least) two matches.
2867 Returns "-1" on failure (like failed integer parsing), 0 on missing
2869 match, and 1 on match and successful parsing. "v" is changed only on
2870 successful match.
2871 Function "lib/version.c:guestfs_int_version_from_x_y_or_x"
2873 int
2875 guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
2876 const char *str)
2877 Parses a version from a string, either looking for a "X.Y" pattern or
2879 considering it as whole integer.
2880 Returns "-1" on failure (like failed integer parsing), 0 on missing
2882 match, and 1 on match and successful parsing. "v" is changed only on
2883 successful match.
2884 Function "lib/version.c:guestfs_int_parse_unsigned_int"
2886 int
2888 guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)
2889 Parse small, unsigned ints, as used in version numbers.
2891 This will fail with an error if trailing characters are found after the
2893 integer.
2894 Returns ≥ 0 on success, or "-1" on failure.
2896 File lib/wait.c
2898 Function "lib/wait.c:guestfs_int_waitpid"
2900 int
2902 guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)
2903 A safe version of waitpid(3) which retries if "EINTR" is returned.
2905 Note: this only needs to be used in the library, or in programs that
2907 install a non-restartable "SIGCHLD" handler (which is not the case for
2908 any current libguestfs virt tools).
2909 If the main program installs a SIGCHLD handler and sets it to be non-
2911 restartable, then what can happen is the library is waiting in a wait
2912 syscall, the child exits, "SIGCHLD" is sent to the process, and the
2913 wait syscall returns "EINTR". Since the library cannot control the
2914 signal handler, we have to instead restart the wait syscall, which is
2915 the purpose of this wrapper.
2916 Function "lib/wait.c:guestfs_int_waitpid_noerror"
2918 void
2920 guestfs_int_waitpid_noerror (pid_t pid)
2921 Like "guestfs_int_waitpid", but ignore errors.
2923 Function "lib/wait.c:guestfs_int_wait4"
2925 int
2927 guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
2928 struct rusage *rusage, const char *errmsg)
2929 A safe version of wait4(2) which retries if "EINTR" is returned.
2931 File lib/whole-file.c
2933 Function "lib/whole-file.c:guestfs_int_read_whole_file"
2935 int
2937 guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
2938 char **data_r, size_t *size_r)
2939 Read the whole file "filename" into a memory buffer.
2941 The memory buffer is initialized and returned in "data_r". The size of
2943 the file in bytes is returned in "size_r". The return buffer must be
2944 freed by the caller.
2945 On error this sets the error in the handle and returns "-1".
2947 For the convenience of callers, the returned buffer is NUL-terminated
2949 (the NUL is not included in the size).
2950 The file must be a regular, local, trusted file. In particular, do not
2952 use this function to read files that might be under control of an
2953 untrusted user since that will lead to a denial-of-service attack.
2954 Subdirectory builder
2956 File builder/index-parser-c.c
2957 This file handles the interface between the C/lex/yacc index file
2959 parser, and the OCaml world. See builder/index_parser.ml for the OCaml
2960 type definition.
2961 Subdirectory common/edit
2963 File common/edit/file-edit.c
2964 This file implements common file editing in a range of utilities
2966 including guestfish(1), virt-edit(1), virt-customize(1) and
2967 virt-builder(1).
2968 It contains the code for both interactive-(editor-)based editing and
2970 non-interactive editing using Perl snippets.
2971 Function "common/edit/file-edit.c:edit_file_editor"
2973 int
2975 edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
2976 const char *backup_extension, int verbose)
2977 Edit "filename" using the specified "editor" application.
2979 If "backup_extension" is not null, then a copy of "filename" is saved
2981 with "backup_extension" appended to its file name.
2982 If "editor" is null, then the $EDITOR environment variable will be
2984 queried for the editor application, leaving "vi" as fallback if not
2985 set.
2986 Returns "-1" for failure, 0 on success, 1 if the editor did not change
2988 the file (e.g. the user closed the editor without saving).
2989 Function "common/edit/file-edit.c:edit_file_perl"
2991 int
2993 edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
2994 const char *backup_extension, int verbose)
2995 Edit "filename" running the specified "perl_expr" using Perl.
2997 If "backup_extension" is not null, then a copy of "filename" is saved
2999 with "backup_extension" appended to its file name.
3000 Returns "-1" for failure, 0 on success.
3002 Subdirectory common/mlxml
3004 File common/mlxml/xml-c.c
3005 Mini interface to libxml2.
3007 Subdirectory common/options
3009 File common/options/config.c
3010 This file parses the guestfish configuration file, usually
3012 ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.
3013 Note that "parse_config" is called very early, before command line
3015 parsing, before the "verbose" flag has been set, even before the global
3016 handle "g" is opened.
3017 File common/options/decrypt.c
3019 This file implements the decryption of disk images, usually done before
3021 mounting their partitions.
3022 Function "common/options/decrypt.c:make_mapname"
3024 static void
3026 make_mapname (const char *device, char *mapname, size_t len)
3027 Make a LUKS map name from the partition name, eg. "/dev/vda2" =>
3029 "luksvda2"
3030 Function "common/options/decrypt.c:inspect_do_decrypt"
3032 void
3034 inspect_do_decrypt (guestfs_h *g, struct key_store *ks)
3035 Simple implementation of decryption: look for any "crypto_LUKS"
3037 partitions and decrypt them, then rescan for VGs. This only works for
3038 Fedora whole-disk encryption. WIP to make this work for other
3039 encryption schemes.
3040 File common/options/display-options.c
3042 This file contains common code used to implement --short-options and
3044 --long-options in C virt tools. (The equivalent for OCaml virt tools
3045 is implemented by common/mltools/getopt.ml).
3046 These "hidden" options are used to implement bash tab completion.
3048 Function "common/options/display-options.c:display_short_options"
3050 void
3052 display_short_options (const char *format)
3053 Implements the internal "tool --short-options" flag, which just lists
3055 out the short options available. Used by bash completion.
3056 Function "common/options/display-options.c:display_long_options"
3058 void
3060 display_long_options (const struct option *long_options)
3061 Implements the internal "tool --long-options" flag, which just lists
3063 out the long options available. Used by bash completion.
3064 File common/options/domain.c
3066 Implements the guestfish (and other tools) -d option.
3068 Function "common/options/domain.c:add_libvirt_drives"
3070 int
3072 add_libvirt_drives (guestfs_h *g, const char *guest)
3073 This function is called when a user invokes "guestfish -d guest".
3075 Returns the number of drives added ("> 0"), or "-1" for failure.
3077 File common/options/inspect.c
3079 This file implements inspecting the guest and mounting the filesystems
3081 found in the right places. It is used by the guestfish(1) -i option
3082 and some utilities such as virt-cat(1).
3083 Function "common/options/inspect.c:inspect_mount_handle"
3085 void
3087 inspect_mount_handle (guestfs_h *g, struct key_store *ks)
3088 This function implements the -i option.
3090 Function "common/options/inspect.c:print_inspect_prompt"
3092 void
3094 print_inspect_prompt (void)
3095 This function is called only if "inspect_mount_root" was called, and
3097 only after we've printed the prompt in interactive mode.
3098 File common/options/keys.c
3100 Function "common/options/keys.c:read_key"
3102 char *
3104 read_key (const char *param)
3105 Read a passphrase ('Key') from /dev/tty with echo off.
3107 The caller (fish/cmds.c) will call free on the string afterwards.
3109 Based on the code in cryptsetup file lib/utils.c.
3110 File common/options/options.c
3112 This file contains common options parsing code used by guestfish and
3114 many other tools which share a common options syntax.
3115 For example, guestfish, virt-cat, virt-ls etc all support the -a
3117 option, and that is handled in all of those tools using a macro
3118 "OPTION_a" defined in fish/options.h.
3119 There are a lot of common global variables used, "drvs" accumulates the
3121 list of drives, "verbose" for the -v flag, and many more.
3122 Function "common/options/options.c:option_a"
3124 void
3126 option_a (const char *arg, const char *format, int blocksize,
3127 struct drv **drvsp)
3128 Handle the guestfish -a option on the command line.
3130 Function "common/options/options.c:option_d"
3132 void
3134 option_d (const char *arg, struct drv **drvsp)
3135 Handle the -d option when passed on the command line.
3137 Function "common/options/options.c:display_mountpoints_on_failure"
3139 static void
3141 display_mountpoints_on_failure (const char *mp_device,
3142 const char *user_supplied_options)
3143 If the -m option fails on any command, display a useful error message
3145 listing the mountpoints.
3146 File common/options/uri.c
3148 This file implements URI parsing for the -a option, in many utilities
3150 including guestfish(1), virt-cat(1), virt-builder(1),
3151 virt-customize(1), etc.
3152 Subdirectory common/parallel
3154 File common/parallel/domains.c
3155 This file is used by "virt-df" and some of the other tools when they
3157 are implicitly asked to operate over all libvirt domains (VMs), for
3158 example when "virt-df" is called without specifying any particular disk
3159 image.
3160 It hides the complexity of querying the list of domains from libvirt.
3162 Function "common/parallel/domains.c:free_domains"
3164 void
3166 free_domains (void)
3167 Frees up everything allocated by "get_all_libvirt_domains".
3169 Function "common/parallel/domains.c:get_all_libvirt_domains"
3171 void
3173 get_all_libvirt_domains (const char *libvirt_uri)
3174 Read all libguest guests into the global variables "domains" and
3176 "nr_domains". The guests are ordered by name. This exits on any
3177 error.
3178 File common/parallel/estimate-max-threads.c
3180 Function "common/parallel/estimate-max-threads.c:estimate_max_threads"
3182 size_t
3184 estimate_max_threads (void)
3185 This function uses the output of "free -m" to estimate how many
3187 libguestfs appliances could be safely started in parallel. Note that
3188 it always returns ≥ 1.
3189 Function "common/parallel/estimate-max-threads.c:read_line_from"
3191 static char *
3193 read_line_from (const char *cmd)
3194 Run external command and read the first line of output.
3196 File common/parallel/parallel.c
3198 This file is used by "virt-df" and some of the other tools when they
3200 need to run multiple parallel libguestfs instances to operate on a
3201 large number of libvirt domains efficiently.
3202 It implements a multithreaded work queue. In addition it reorders the
3204 output so the output still appears in the same order as the input (ie.
3205 still ordered alphabetically).
3206 Function "common/parallel/parallel.c:start_threads"
3208 int
3210 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
3211 Run the threads and work through the global list of libvirt domains.
3213 "option_P" is whatever the user passed in the -P option, or 0 if the
3215 user didn't use the -P option (in which case the number of threads is
3216 chosen heuristically).
3217 "options_handle" (which may be "NULL") is the global guestfs handle
3219 created by the options mini-library.
3220 The work function ("work") should do the work (inspecting the domain,
3222 etc.) on domain index "i". However it must not print out any result
3223 directly. Instead it prints anything it needs to the supplied "FILE
3224 *". The work function should return 0 on success or "-1" on error.
3225 The "start_threads" function returns 0 if all work items completed
3227 successfully, or "-1" if there was an error.
3228 Subdirectory common/progress
3230 File common/progress/progress.c
3231 This file implements the progress bar in guestfish(1), virt-resize(1)
3233 and virt-sparsify(1).
3234 Function "common/progress/progress.c:progress_bar_init"
3236 struct progress_bar *
3238 progress_bar_init (unsigned flags)
3239 Initialize a progress bar struct.
3241 It is intended that you can reuse the same struct for multiple commands
3243 (but only in a single thread). Call "progress_bar_reset" before each
3244 new command.
3245 Function "common/progress/progress.c:progress_bar_free"
3247 void
3249 progress_bar_free (struct progress_bar *bar)
3250 Free a progress bar struct.
3252 Function "common/progress/progress.c:progress_bar_reset"
3254 void
3256 progress_bar_reset (struct progress_bar *bar)
3257 This function should be called just before you issue any command.
3259 Function "common/progress/progress.c:estimate_remaining_time"
3261 static double
3263 estimate_remaining_time (struct progress_bar *bar, double ratio)
3264 Return remaining time estimate (in seconds) for current call.
3266 This returns the running mean estimate of remaining time, but if the
3268 latest estimate of total time is greater than two s.d.'s from the
3269 running mean then we don't print anything because we're not confident
3270 that the estimate is meaningful. (Returned value is <0.0 when nothing
3271 should be printed).
3272 Function "common/progress/progress.c:progress_bar_set"
3274 void
3276 progress_bar_set (struct progress_bar *bar,
3277 uint64_t position, uint64_t total)
3278 Set the position of the progress bar.
3280 This should be called from a "GUESTFS_EVENT_PROGRESS" event callback.
3282 Subdirectory common/qemuopts
3284 File common/qemuopts/qemuopts-tests.c
3285 Unit tests of internal functions.
3287 These tests may use a libguestfs handle, but must not launch the
3289 handle. Also, avoid long-running tests.
3290 File common/qemuopts/qemuopts.c
3292 Mini-library for writing qemu command lines and qemu config files.
3294 There are some shortcomings with the model used for qemu options which
3296 aren't clear until you try to convert options into a configuration
3297 file. However if we attempted to model the options in more detail then
3298 this library would be both very difficult to use and incompatible with
3299 older versions of qemu. Hopefully the current model is a decent
3300 compromise.
3301 For reference here are the problems:
3303 · There's inconsistency in qemu between options and config file, eg.
3305 "-smp 4" becomes:
3306 [smp-opts]
3308 cpus = "4"
3309 · Similar to the previous point, you can write either "-smp 4" or
3311 "-smp cpus=4" (although this won't work in very old qemu). When
3312 generating a config file you need to know the implicit key name.
3313 · In "-opt key=value,..." the "key" is really a tree/array specifier.
3315 The way this works is complicated but hinted at here:
3316 http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
3317 · Some options are syntactic sugar. eg. "-kernel foo" is sugar for
3319 "-machine kernel=foo".
3320 Function "common/qemuopts/qemuopts.c:qemuopts_create"
3322 struct qemuopts *
3324 qemuopts_create (void)
3325 Create an empty list of qemu options.
3327 The caller must eventually free the list by calling "qemuopts_free".
3329 Returns "NULL" on error, setting "errno".
3331 Function "common/qemuopts/qemuopts.c:qemuopts_free"
3333 void
3335 qemuopts_free (struct qemuopts *qopts)
3336 Free the list of qemu options.
3338 Function "common/qemuopts/qemuopts.c:qemuopts_add_flag"
3340 int
3342 qemuopts_add_flag (struct qemuopts *qopts, const char *flag)
3343 Add a command line flag which has no argument. eg:
3345 qemuopts_add_flag (qopts, "-no-user-config");
3347 Returns 0 on success. Returns "-1" on error, setting "errno".
3349 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg"
3351 int
3353 qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)
3354 Add a command line flag which has a single argument. eg:
3356 qemuopts_add_arg (qopts, "-m", "1024");
3358 Don't use this if the argument is a comma-separated list, since quoting
3360 will not be done properly. See "qemuopts_add_arg_list".
3361 Returns 0 on success. Returns "-1" on error, setting "errno".
3363 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_format"
3365 int
3367 qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
3368 const char *fs, ...)
3369 Add a command line flag which has a single formatted argument. eg:
3371 qemuopts_add_arg_format (qopts, "-m", "%d", 1024);
3373 Don't use this if the argument is a comma-separated list, since quoting
3375 will not be done properly. See "qemuopts_add_arg_list".
3376 Returns 0 on success. Returns "-1" on error, setting "errno".
3378 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote"
3380 int
3382 qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
3383 const char *value)
3384 This is like "qemuopts_add_arg" except that no quoting is done on the
3386 value.
3387 For "qemuopts_to_script" and "qemuopts_to_channel", this means that
3389 neither shell quoting nor qemu comma quoting is done on the value.
3390 For "qemuopts_to_argv" this means that qemu comma quoting is not done.
3392 "qemuopts_to_config*" will fail.
3394 You should use this with great care.
3396 Function "common/qemuopts/qemuopts.c:qemuopts_start_arg_list"
3398 int
3400 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
3401 Start an argument that takes a comma-separated list of fields.
3403 Typical usage is like this (with error handling omitted):
3405 qemuopts_start_arg_list (qopts, "-drive");
3407 qemuopts_append_arg_list (qopts, "file=foo");
3408 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
3409 qemuopts_end_arg_list (qopts);
3410 which would construct "-drive file=foo,if=ide"
3412 See also "qemuopts_add_arg_list" for a way to do simple cases in one
3414 call.
3415 Returns 0 on success. Returns "-1" on error, setting "errno".
3417 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_list"
3419 int
3421 qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
3422 const char *elem0, ...)
3423 Add a command line flag which has a list of arguments. eg:
3425 qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);
3427 This is turned into a comma-separated list, like: "-drive
3429 file=foo,if=ide". Note that this handles qemu quoting properly, so
3430 individual elements may contain commas and this will do the right
3431 thing.
3432 Returns 0 on success. Returns "-1" on error, setting "errno".
3434 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary"
3436 int
3438 qemuopts_set_binary (struct qemuopts *qopts, const char *binary)
3439 Set the qemu binary name.
3441 Returns 0 on success. Returns "-1" on error, setting "errno".
3443 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch"
3445 int
3447 qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)
3448 Set the qemu binary name to "qemu-system-[arch]".
3450 As a special case if "arch" is "NULL", the binary is set to the KVM
3452 binary for the current host architecture:
3453 qemuopts_set_binary_by_arch (qopts, NULL);
3455 Returns 0 on success. Returns "-1" on error, setting "errno".
3457 Function "common/qemuopts/qemuopts.c:qemuopts_to_script"
3459 int
3461 qemuopts_to_script (struct qemuopts *qopts, const char *filename)
3462 Write the qemu options to a script.
3464 "qemuopts_set_binary*" must be called first.
3466 The script file will start with "#!/bin/sh" and will be chmod to mode
3468 0755.
3469 Returns 0 on success. Returns "-1" on error, setting "errno".
3471 Function "common/qemuopts/qemuopts.c:shell_quote"
3473 static void
3475 shell_quote (const char *str, FILE *fp)
3476 Print "str" to "fp", shell-quoting it if necessary.
3478 Function "common/qemuopts/qemuopts.c:shell_and_comma_quote"
3480 static void
3482 shell_and_comma_quote (const char *str, FILE *fp)
3483 Print "str" to "fp" doing both shell and qemu comma quoting.
3485 Function "common/qemuopts/qemuopts.c:qemuopts_to_channel"
3487 int
3489 qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)
3490 Write the qemu options to a "FILE *fp".
3492 "qemuopts_set_binary*" must be called first.
3494 Only the qemu command line is written. The caller may need to add
3496 "#!/bin/sh" and may need to chmod the resulting file to 0755.
3497 Returns 0 on success. Returns "-1" on error, setting "errno".
3499 Function "common/qemuopts/qemuopts.c:qemuopts_to_argv"
3501 char **
3503 qemuopts_to_argv (struct qemuopts *qopts)
3504 Return a NULL-terminated argument list, of the kind that can be passed
3506 directly to execv(3).
3507 "qemuopts_set_binary*" must be called first. It will be returned as
3509 "argv[0]" in the returned list.
3510 The list of strings and the strings themselves must be freed by the
3512 caller.
3513 Returns "NULL" on error, setting "errno".
3515 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_file"
3517 int
3519 qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)
3520 Write the qemu options to a qemu config file, suitable for reading in
3522 using "qemu -readconfig filename".
3523 Note that qemu config files have limitations on content and quoting, so
3525 not all qemuopts structs can be written (this function returns an error
3526 in these cases). For more information see
3527 https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html
3528 https://bugs.launchpad.net/qemu/+bug/1686364
3529 Also, command line argument names and config file sections sometimes
3531 have different names. For example the equivalent of "-m 1024" is:
3532 [memory]
3534 size = "1024"
3535 This code does not attempt to convert between the two forms. You just
3537 need to know how to do that yourself.
3538 Returns 0 on success. Returns "-1" on error, setting "errno".
3540 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_channel"
3542 int
3544 qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)
3545 Same as "qemuopts_to_config_file", but this writes to a "FILE *fp".
3547 Subdirectory common/utils
3549 File common/utils/cleanups.c
3550 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3552 They are implemented using the "__attribute__((cleanup))" feature of
3553 gcc and clang. Typical usage is:
3554 fn ()
3556 {
3557 CLEANUP_FREE char *str = NULL;
3558 str = safe_asprintf (g, "foo");
3559 // str is freed automatically when the function returns
3560 }
3561 There are a few catches to be aware of with the cleanup mechanism:
3563 · If a cleanup variable is not initialized, then you can end up
3565 calling free(3) with an undefined value, resulting in the program
3566 crashing. For this reason, you should usually initialize every
3567 cleanup variable with something, eg. "NULL"
3568 · Don't mark variables holding return values as cleanup variables.
3570 · The "main()" function shouldn't use cleanup variables since it is
3572 normally exited by calling exit(3), and that doesn't call the
3573 cleanup handlers.
3574 The functions in this file are used internally by the "CLEANUP_*"
3576 macros. Don't call them directly.
3577 File common/utils/gnulib-cleanups.c
3579 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3581 They are implemented using the "__attribute__((cleanup))" feature of
3582 gcc and clang. Typical usage is:
3583 fn ()
3585 {
3586 CLEANUP_FREE char *str = NULL;
3587 str = safe_asprintf (g, "foo");
3588 // str is freed automatically when the function returns
3589 }
3590 There are a few catches to be aware of with the cleanup mechanism:
3592 · If a cleanup variable is not initialized, then you can end up
3594 calling free(3) with an undefined value, resulting in the program
3595 crashing. For this reason, you should usually initialize every
3596 cleanup variable with something, eg. "NULL"
3597 · Don't mark variables holding return values as cleanup variables.
3599 · The "main()" function shouldn't use cleanup variables since it is
3601 normally exited by calling exit(3), and that doesn't call the
3602 cleanup handlers.
3603 The functions in this file are used internally by the "CLEANUP_*"
3605 macros. Don't call them directly.
3606 File common/utils/guestfs-utils.h
3608 This header file is included in all "frontend" parts of libguestfs,
3610 namely the library, non-C language bindings, virt tools and tests.
3611 The daemon does not use this header. If you need a place to put
3613 something shared with absolutely everything including the daemon, put
3614 it in lib/guestfs-internal-all.h
3615 If a definition is only needed by a single component of libguestfs (eg.
3617 just the library, or just a single virt tool) then it should not be
3618 here!
3619 File common/utils/libxml2-writer-macros.h
3621 These macros make it easier to write XML. To use them correctly you
3623 must be aware of these assumptions:
3624 · The "xmlTextWriterPtr" is called "xo". It is used implicitly by
3626 all the macros.
3627 · On failure, a function called "xml_error" is called which you must
3629 define (usually as a macro). You must use "CLEANUP_*" macros in
3630 your functions if you want correct cleanup of local variables along
3631 the error path.
3632 · All the "bad" casting is hidden inside the macros.
3634 Definition "common/utils/libxml2-writer-macros.h:start_element"
3636 #define start_element
3638 To define an XML element use:
3640 start_element ("name") {
3642 ...
3643 } end_element ();
3644 which produces "<name>...</name>"
3646 Definition "common/utils/libxml2-writer-macros.h:empty_element"
3648 #define empty_element
3650 To define an empty element:
3652 empty_element ("name");
3654 which produces "<name/>"
3656 Definition "common/utils/libxml2-writer-macros.h:single_element"
3658 #define single_element
3660 To define a single element with no attributes containing some text:
3662 single_element ("name", text);
3664 which produces "<name>text</name>"
3666 Definition "common/utils/libxml2-writer-macros.h:single_element_format"
3668 #define single_element_format
3670 To define a single element with no attributes containing some text
3672 using a format string:
3673 single_element_format ("cores", "%d", nr_cores);
3675 which produces "<cores>4</cores>"
3677 Definition "common/utils/libxml2-writer-macros.h:attribute"
3679 #define attribute
3681 To define an XML element with attributes, use:
3683 start_element ("name") {
3685 attribute ("foo", "bar");
3686 attribute_format ("count", "%d", count);
3687 ...
3688 } end_element ();
3689 which produces "<name foo="bar" count="123">...</name>"
3691 Definition "common/utils/libxml2-writer-macros.h:attribute_ns"
3693 #define attribute_ns
3695 "attribute_ns (prefix, key, namespace_uri, value)" defines a namespaced
3697 attribute.
3698 Definition "common/utils/libxml2-writer-macros.h:string"
3700 #define string
3702 To define a verbatim string, use:
3704 string ("hello");
3706 Definition "common/utils/libxml2-writer-macros.h:string_format"
3708 #define string_format
3710 To define a verbatim string using a format string, use:
3712 string ("%s, world", greeting);
3714 Definition "common/utils/libxml2-writer-macros.h:base64"
3716 #define base64
3718 To write a string encoded as base64:
3720 base64 (data, size);
3722 Definition "common/utils/libxml2-writer-macros.h:comment"
3724 #define comment
3726 To define a comment in the XML, use:
3728 comment ("number of items = %d", nr_items);
3730 File common/utils/stringlists-utils.c
3732 Utility functions used by the library, tools and language bindings.
3734 These functions must not call internal library functions such as
3736 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3737 Function "common/utils/stringlists-utils.c:guestfs_int_split_string"
3739 char **
3741 guestfs_int_split_string (char sep, const char *str)
3742 Split string at separator character "sep", returning the list of
3744 strings. Returns "NULL" on memory allocation failure.
3745 Note (assuming "sep" is ":"):
3747 "str == NULL"
3749 aborts
3750 "str == """
3752 returns "[]"
3753 "str == "abc""
3755 returns "["abc"]"
3756 "str == ":""
3758 returns "["", ""]"
3759 File common/utils/utils.c
3761 Utility functions used by the library, tools and language bindings.
3763 These functions must not call internal library functions such as
3765 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3766 Function "common/utils/utils.c:guestfs_int_replace_string"
3768 char *
3770 guestfs_int_replace_string (const char *str, const char *s1, const char *s2)
3771 Replace every instance of "s1" appearing in "str" with "s2". A newly
3773 allocated string is returned which must be freed by the caller. If
3774 allocation fails this can return "NULL".
3775 For example:
3777 replace_string ("abcabb", "ab", "a");
3779 would return "acab".
3781 Function "common/utils/utils.c:guestfs_int_exit_status_to_string"
3783 char *
3785 guestfs_int_exit_status_to_string (int status, const char *cmd_name,
3786 char *buffer, size_t buflen)
3787 Translate a wait/system exit status into a printable string.
3789 Function "common/utils/utils.c:guestfs_int_random_string"
3791 int
3793 guestfs_int_random_string (char *ret, size_t len)
3794 Return a random string of characters.
3796 Notes:
3798 · The "ret" buffer must have length "len+1" in order to store the
3800 final "\0" character.
3801 · There is about 5 bits of randomness per output character (so about
3803 "5*len" bits of randomness in the resulting string).
3804 Function "common/utils/utils.c:guestfs_int_drive_name"
3806 char *
3808 guestfs_int_drive_name (size_t index, char *ret)
3809 This turns a drive index (eg. 27) into a drive name (eg. "ab").
3811 Drive indexes count from 0. The return buffer has to be large enough
3813 for the resulting string, and the returned pointer points to the *end*
3814 of the string.
3815 https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
3817 Function "common/utils/utils.c:guestfs_int_drive_index"
3819 ssize_t
3821 guestfs_int_drive_index (const char *name)
3822 The opposite of "guestfs_int_drive_name". Take a string like "ab" and
3824 return the index (eg 27).
3825 Note that you must remove any prefix such as "hd", "sd" etc, or any
3827 partition number before calling the function.
3828 Function "common/utils/utils.c:guestfs_int_is_true"
3830 int
3832 guestfs_int_is_true (const char *str)
3833 Similar to "Tcl_GetBoolean".
3835 Function "common/utils/utils.c:guestfs_int_string_is_valid"
3837 bool
3839 guestfs_int_string_is_valid (const char *str,
3840 size_t min_length, size_t max_length,
3841 int flags, const char *extra)
3842 Check a string for validity, that it contains only certain characters,
3844 and minimum and maximum length. This function is usually wrapped in a
3845 VALID_* macro, see lib/drives.c for an example.
3846 "str" is the string to check.
3848 "min_length" and "max_length" are the minimum and maximum length
3850 checks. 0 means no check.
3851 The flags control:
3853 "VALID_FLAG_ALPHA"
3855 7-bit ASCII-only alphabetic characters are permitted.
3856 "VALID_FLAG_DIGIT"
3858 7-bit ASCII-only digits are permitted.
3859 "extra" is a set of extra characters permitted, in addition to
3861 alphabetic and/or digits. ("extra = NULL" for no extra).
3862 Returns boolean "true" if the string is valid (passes all the tests),
3864 or "false" if not.
3865 Function "common/utils/utils.c:guestfs_int_fadvise_normal"
3867 void
3869 guestfs_int_fadvise_normal (int fd)
3870 Hint that we will read or write the file descriptor normally.
3872 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3874 and sets the per-file number of readahead pages to equal the block
3875 device readahead setting.
3876 It's OK to call this on a non-file since we ignore failure as it is
3878 only a hint.
3879 Function "common/utils/utils.c:guestfs_int_fadvise_sequential"
3881 void
3883 guestfs_int_fadvise_sequential (int fd)
3884 Hint that we will read or write the file descriptor sequentially.
3886 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3888 and sets the per-file number of readahead pages to twice the block
3889 device readahead setting.
3890 It's OK to call this on a non-file since we ignore failure as it is
3892 only a hint.
3893 Function "common/utils/utils.c:guestfs_int_fadvise_random"
3895 void
3897 guestfs_int_fadvise_random (int fd)
3898 Hint that we will read or write the file descriptor randomly.
3900 On Linux, this sets the "FMODE_RANDOM" flag on the file. The effect of
3902 this flag is to:
3903 · Disable normal sequential file readahead.
3905 · If any read of the file is done which misses in the page cache, 2MB
3907 are read into the page cache. [I think - I'm not sure I totally
3908 understand what this is doing]
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_fadvise_noreuse"
3914 void
3916 guestfs_int_fadvise_noreuse (int fd)
3917 Hint that we will access the data only once.
3919 On Linux, this does nothing.
3921 It's OK to call this on a non-file since we ignore failure as it is
3923 only a hint.
3924 Function "common/utils/utils.c:guestfs_int_fadvise_dontneed"
3926 void
3928 guestfs_int_fadvise_dontneed (int fd)
3929 Hint that we will not access the data in the near future.
3931 On Linux, this immediately writes out any dirty pages in the page cache
3933 and then invalidates (drops) all pages associated with this file from
3934 the page cache. Apparently it does this even if the file is opened or
3935 being used by other processes. This setting is not persistent; if you
3936 subsequently read the file it will be cached in the page cache as
3937 normal.
3938 It's OK to call this on a non-file since we ignore failure as it is
3940 only a hint.
3941 Function "common/utils/utils.c:guestfs_int_fadvise_willneed"
3943 void
3945 guestfs_int_fadvise_willneed (int fd)
3946 Hint that we will access the data in the near future.
3948 On Linux, this immediately reads the whole file into the page cache.
3950 This setting is not persistent; subsequently pages may be dropped from
3951 the page cache as normal.
3952 It's OK to call this on a non-file since we ignore failure as it is
3954 only a hint.
3955 Function "common/utils/utils.c:guestfs_int_shell_unquote"
3957 char *
3959 guestfs_int_shell_unquote (const char *str)
3960 Unquote a shell-quoted string.
3962 Augeas passes strings to us which may be quoted, eg. if they come from
3964 files in /etc/sysconfig. This function can do simple unquoting of
3965 these strings.
3966 Note this function does not do variable substitution, since that is
3968 impossible without knowing the file context and indeed the environment
3969 under which the shell script is run. Configuration files should not
3970 use complex quoting.
3971 "str" is the input string from Augeas, a string that may be single- or
3973 double-quoted or may not be quoted. The returned string is unquoted,
3974 and must be freed by the caller. "NULL" is returned on error and
3975 "errno" is set accordingly.
3976 For information on double-quoting in bash, see
3978 https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html
3979 Function "common/utils/utils.c:guestfs_int_is_reg"
3981 int
3983 guestfs_int_is_reg (int64_t mode)
3984 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3986 field represents a regular file.
3987 Function "common/utils/utils.c:guestfs_int_is_dir"
3989 int
3991 guestfs_int_is_dir (int64_t mode)
3992 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3994 field represents a directory.
3995 Function "common/utils/utils.c:guestfs_int_is_chr"
3997 int
3999 guestfs_int_is_chr (int64_t mode)
4000 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4002 field represents a char device.
4003 Function "common/utils/utils.c:guestfs_int_is_blk"
4005 int
4007 guestfs_int_is_blk (int64_t mode)
4008 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4010 field represents a block device.
4011 Function "common/utils/utils.c:guestfs_int_is_fifo"
4013 int
4015 guestfs_int_is_fifo (int64_t mode)
4016 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4018 field represents a named pipe (FIFO).
4019 Function "common/utils/utils.c:guestfs_int_is_lnk"
4021 int
4023 guestfs_int_is_lnk (int64_t mode)
4024 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4026 field represents a symbolic link.
4027 Function "common/utils/utils.c:guestfs_int_is_sock"
4029 int
4031 guestfs_int_is_sock (int64_t mode)
4032 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4034 field represents a Unix domain socket.
4035 Function "common/utils/utils.c:guestfs_int_full_path"
4037 char *
4039 guestfs_int_full_path (const char *dir, const char *name)
4040 Concatenate "dir" and "name" to create a path. This correctly handles
4042 the case of concatenating "/" + "filename" as well as "/dir" +
4043 "filename". "name" may be "NULL".
4044 The caller must free the returned path.
4046 This function sets "errno" and returns "NULL" on error.
4048 Function "common/utils/utils.c:guestfs_int_hexdump"
4050 void
4052 guestfs_int_hexdump (const void *data, size_t len, FILE *fp)
4053 Hexdump a block of memory to "FILE *", used for debugging.
4055 Subdirectory common/visit
4057 File common/visit/visit.c
4058 This file contains a recursive function for visiting all files and
4060 directories in a guestfs filesystem.
4061 Adapted from
4063 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/
4064 Function "common/visit/visit.c:visit"
4066 int
4068 visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)
4069 Visit every file and directory in a guestfs filesystem, starting at
4071 "dir".
4072 "dir" may be "/" to visit the entire filesystem, or may be some
4074 subdirectory. Symbolic links are not followed.
4075 The visitor function "f" is called once for every directory and every
4077 file. The parameters passed to "f" include the current directory name,
4078 the current file name (or "NULL" when we're visiting a directory), the
4079 "guestfs_statns" (file permissions etc), and the list of extended
4080 attributes of the file. The visitor function may return "-1" which
4081 causes the whole recursion to stop with an error.
4082 Also passed to this function is an "opaque" pointer which is passed
4084 through to the visitor function.
4085 Returns 0 if everything went OK, or "-1" if there was an error. Error
4087 handling is not particularly well defined. It will either set an error
4088 in the libguestfs handle or print an error on stderr, but there is no
4089 way for the caller to tell the difference.
4090 Subdirectory common/windows
4092 File common/windows/windows.c
4093 This file implements "win:" Windows file path support in guestfish(1).
4095 Function "common/windows/windows.c:is_windows"
4097 int
4099 is_windows (guestfs_h *g, const char *root)
4100 Checks whether "root" is a Windows installation.
4102 This relies on an already being done introspection.
4104 Function "common/windows/windows.c:windows_path"
4106 char *
4108 windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
4109 Resolves "path" as possible Windows path according to "root", giving a
4111 new path that can be used in libguestfs API calls.
4112 Notes:
4114 · "root" must be a Windows installation
4116 · relies on an already being done introspection
4118 · will unmount all the existing mount points and mount the Windows
4120 root (according to "readonly")
4121 · calls exit(3) on memory allocation failures
4123 Subdirectory daemon
4125 File daemon/command.c
4126 This file contains a number of useful functions for running external
4128 commands and capturing their output.
4129 Function "daemon/command.c:commandf"
4131 int
4133 commandf (char **stdoutput, char **stderror, unsigned flags,
4134 const char *name, ...)
4135 Run a command. Optionally capture stdout and stderr as strings.
4137 Returns 0 if the command ran successfully, or "-1" if there was any
4139 error.
4140 For a description of the "flags" see "commandrvf".
4142 There is also a macro "command(out,err,name,...)" which calls
4144 "commandf" with "flags=0".
4145 Function "daemon/command.c:commandrf"
4147 int
4149 commandrf (char **stdoutput, char **stderror, unsigned flags,
4150 const char *name, ...)
4151 Same as "command", but we allow the status code from the subcommand to
4153 be non-zero, and return that status code.
4154 We still return "-1" if there was some other error.
4156 There is also a macro "commandr(out,err,name,...)" which calls
4158 "commandrf" with "flags=0".
4159 Function "daemon/command.c:commandvf"
4161 int
4163 commandvf (char **stdoutput, char **stderror, unsigned flags,
4164 char const *const *argv)
4165 Same as "command", but passing in an argv array.
4167 There is also a macro "commandv(out,err,argv)" which calls "commandvf"
4169 with "flags=0".
4170 Function "daemon/command.c:commandrvf"
4172 int
4174 commandrvf (char **stdoutput, char **stderror, unsigned flags,
4175 char const* const *argv)
4176 This is a more sane version of system(3) for running external commands.
4178 It uses fork/execvp, so we don't need to worry about quoting of
4179 parameters, and it allows us to capture any error messages in a buffer.
4180 If "stdoutput" is not "NULL", then *stdoutput will return the stdout of
4182 the command as a string.
4183 If "stderror" is not "NULL", then *stderror will return the stderr of
4185 the command. If there is a final \n character, it is removed so you
4186 can use the error string directly in a call to "reply_with_error".
4187 Flags are:
4189 "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR"
4191 For broken external commands that send error messages to stdout
4192 (hello, parted) but that don't have any useful stdout information,
4193 use this flag to capture the error messages in the *stderror
4194 buffer. If using this flag, you should pass "stdoutput=NULL"
4195 because nothing could ever be captured in that buffer.
4196 "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN"
4198 For running external commands on chrooted files correctly (see
4199 https://bugzilla.redhat.com/579608) specifying this flag causes
4200 another process to be forked which chroots into sysroot and just
4201 copies the input file to stdin of the specified command. The file
4202 descriptor is ORed with the flags, and that file descriptor is
4203 always closed by this function. See daemon/hexdump.c for an
4204 example of usage.
4205 There is also a macro "commandrv(out,err,argv)" which calls
4207 "commandrvf" with "flags=0".
4208 File daemon/device-name-translation.c
4210 Function
4212 "daemon/device-name-translation.c:device_name_translation_init"
4213 void
4215 device_name_translation_init (void)
4216 Cache daemon disk mapping.
4218 When the daemon starts up, populate a cache with the contents of
4220 /dev/disk/by-path. It's easiest to use "ls -lv" here since the names
4221 are sorted awkwardly.
4222 Function "daemon/device-name-translation.c:device_name_translation"
4224 char *
4226 device_name_translation (const char *device)
4227 Perform device name translation.
4229 Libguestfs defines a few standard formats for device names. (see also
4231 "BLOCK DEVICE NAMING" in guestfs(3) and "guestfs_canonical_device_name"
4232 in guestfs(3)). They are:
4233 /dev/sdX[N]
4235 /dev/hdX[N]
4236 /dev/vdX[N]
4237 These mean the Nth partition on the Xth device. Because Linux no
4238 longer enumerates devices in the order they are passed to qemu, we
4239 must translate these by looking up the actual device using
4240 /dev/disk/by-path/
4241 /dev/mdX
4243 /dev/VG/LV
4244 /dev/mapper/...
4245 /dev/dm-N
4246 These are not translated here.
4247 It returns a newly allocated string which the caller must free.
4249 It returns "NULL" on error. Note it does not call "reply_with_*".
4251 We have to open the device and test for "ENXIO", because the device
4253 nodes may exist in the appliance.
4254 File daemon/guestfsd.c
4256 This is the guestfs daemon which runs inside the guestfs appliance.
4258 This file handles start up and connecting back to the library.
4259 Function "daemon/guestfsd.c:print_shell_quote"
4261 static int
4263 print_shell_quote (FILE *stream,
4264 const struct printf_info *info ATTRIBUTE_UNUSED,
4265 const void *const *args)
4266 printf helper function so we can use %Q ("quoted") and %R to print
4268 shell-quoted strings. See guestfs-hacking(1) for more details.
4269 File daemon/internal.c
4271 Internal functions that are not part of the public API.
4273 File daemon/utils-c.c
4275 Bindings for utility functions.
4277 Note that functions called from OCaml code must never call any of the
4279 "reply*" functions.
4280 File daemon/utils.c
4282 Miscellaneous utility functions used by the daemon.
4284 Function "daemon/utils.c:is_root_device_stat"
4286 static int
4288 is_root_device_stat (struct stat *statbuf)
4289 Return true iff device is the root device (and therefore should be
4291 ignored from the point of view of user calls).
4292 Function "daemon/utils.c:is_device_parameter"
4294 int
4296 is_device_parameter (const char *device)
4297 Parameters marked as "Device", "Dev_or_Path", etc can be passed a block
4299 device name. This function tests if the parameter is a block device
4300 name.
4301 It can also be used in daemon code to test if the string passed as a
4303 "Dev_or_Path" parameter is a device or path.
4304 Function "daemon/utils.c:sysroot_path"
4306 char *
4308 sysroot_path (const char *path)
4309 Turn "/path" into "/sysroot/path".
4311 Returns "NULL" on failure. The caller must check for this and call
4313 "reply_with_perror ("malloc")". The caller must also free the returned
4314 string.
4315 See also the custom %R printf formatter which does shell quoting too.
4317 Function "daemon/utils.c:sysroot_realpath"
4319 char *
4321 sysroot_realpath (const char *path)
4322 Resolve path within sysroot, calling "sysroot_path" on the resolved
4324 path.
4325 Returns "NULL" on failure. The caller must check for this and call
4327 "reply_with_perror ("malloc")". The caller must also free the returned
4328 string.
4329 See also the custom %R printf formatter which does shell quoting too.
4331 Function "daemon/utils.c:is_power_of_2"
4333 int
4335 is_power_of_2 (unsigned long v)
4336 Returns true if "v" is a power of 2.
4338 Uses the algorithm described at
4340 http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2
4341 Function "daemon/utils.c:split_lines_sb"
4343 struct stringsbuf
4345 split_lines_sb (char *str)
4346 Split an output string into a NULL-terminated list of lines, wrapped
4348 into a stringsbuf.
4349 Typically this is used where we have run an external command which has
4351 printed out a list of things, and we want to return an actual list.
4352 The corner cases here are quite tricky. Note in particular:
4354 "" returns "[]"
4356 "\n"
4358 returns "[""]"
4359 "a\nb"
4361 returns "["a"; "b"]"
4362 "a\nb\n"
4364 returns "["a"; "b"]"
4365 "a\nb\n\n"
4367 returns "["a"; "b"; ""]"
4368 The original string is written over and destroyed by this function
4370 (which is usually OK because it's the 'out' string from "command*()").
4371 You can free the original string, because "add_string()" strdups the
4372 strings.
4373 "argv" in the "struct stringsbuf" will be "NULL" in case of errors.
4375 Function "daemon/utils.c:trim"
4377 void
4379 trim (char *str)
4380 Skip leading and trailing whitespace, updating the original string in-
4382 place.
4383 Function "daemon/utils.c:parse_btrfsvol"
4385 int
4387 parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
4388 Parse the mountable descriptor for a btrfs subvolume. Don't call this
4390 directly; it is only used from the stubs.
4391 A btrfs subvolume is given as:
4393 btrfsvol:/dev/sda3/root
4395 where /dev/sda3 is a block device containing a btrfs filesystem, and
4397 root is the name of a subvolume on it. This function is passed the
4398 string following "btrfsvol:".
4399 On success, "mountable->device" and "mountable->volume" must be freed
4401 by the caller.
4402 Function "daemon/utils.c:mountable_to_string"
4404 char *
4406 mountable_to_string (const mountable_t *mountable)
4407 Convert a "mountable_t" back to its string representation
4409 This function can be used in an error path, so must not call
4411 "reply_with_error".
4412 Function "daemon/utils.c:prog_exists"
4414 int
4416 prog_exists (const char *prog)
4417 Check program exists and is executable on $PATH.
4419 Function "daemon/utils.c:random_name"
4421 int
4423 random_name (char *template)
4424 Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
4426 template to contain a randomly named file. Any 'X' characters after
4427 the final '/' in the template are replaced with random characters.
4428 Notes: You should probably use an 8.3 path, so it's compatible with all
4430 filesystems including basic FAT. Also this only substitutes lowercase
4431 ASCII letters and numbers, again for compatibility with lowest common
4432 denominator filesystems.
4433 This doesn't create a file or check whether or not the file exists (it
4435 would be extremely unlikely to exist as long as the RNG is working).
4436 If there is an error, "-1" is returned.
4438 Function "daemon/utils.c:udev_settle_file"
4440 void
4442 udev_settle_file (const char *file)
4443 LVM and other commands aren't synchronous, especially when udev is
4445 involved. eg. You can create or remove some device, but the "/dev"
4446 device node won't appear until some time later. This means that you
4447 get an error if you run one command followed by another.
4448 Use "udevadm settle" after certain commands, but don't be too fussed if
4450 it fails.
4451 Function "daemon/utils.c:make_exclude_from_file"
4453 char *
4455 make_exclude_from_file (const char *function, char *const *excludes)
4456 Turn list "excludes" into a temporary file, and return a string
4458 containing the temporary file name. Caller must unlink the file and
4459 free the string.
4460 "function" is the function that invoked this helper, and it is used
4462 mainly for errors/debugging.
4463 Function "daemon/utils.c:read_whole_file"
4465 char *
4467 read_whole_file (const char *filename, size_t *size_r)
4468 Read whole file into dynamically allocated array. If there is an
4470 error, DON'T call reply_with_perror, just return NULL. Returns a
4471 "\0"-terminated string. "size_r" can be specified to get the size of
4472 the returned data.
4473 Subdirectory fish
4475 File fish/alloc.c
4476 This file implements the guestfish "alloc" and "sparse" commands.
4478 Function "fish/alloc.c:alloc_disk"
4480 int
4482 alloc_disk (const char *filename, const char *size_str, int add, int sparse)
4483 This is the underlying allocation function. It's called from a few
4485 other places in guestfish.
4486 File fish/copy.c
4488 This file implements the guestfish commands "copy-in" and "copy-out".
4490 File fish/destpaths.c
4492 The file handles tab-completion of filesystem paths in guestfish.
4494 File fish/display.c
4496 The file implements the guestfish "display" command, for displaying
4498 graphical files (icons, images) in disk images.
4499 File fish/echo.c
4501 The file implements the guestfish "echo" command.
4503 File fish/edit.c
4505 guestfish "edit" command, suggested by Ján Ondrej.
4507 File fish/events.c
4509 This file implements the guestfish event-related commands, "event",
4511 "delete-event" and "list-events".
4512 File fish/fish.c
4514 guestfish, the guest filesystem shell. This file contains the main
4516 loop and utilities.
4517 Function "fish/fish.c:parse_command_line"
4519 static struct parsed_command
4521 parse_command_line (char *buf, int *exit_on_error_rtn)
4522 Parse a command string, splitting at whitespace, handling '!', '#' etc.
4524 This destructively updates "buf".
4525 "exit_on_error_rtn" is used to pass in the global "exit_on_error"
4527 setting and to return the local setting (eg. if the command begins with
4528 '-').
4529 Returns in "parsed_command.status":
4531 1 got a guestfish command (returned in
4533 "cmd_rtn"/"argv_rtn"/"pipe_rtn")
4534 0 no guestfish command, but otherwise OK
4536 "-1"
4538 an error
4539 Function "fish/fish.c:parse_quoted_string"
4541 static ssize_t
4543 parse_quoted_string (char *p)
4544 Parse double-quoted strings, replacing backslash escape sequences with
4546 the true character. Since the string is returned in place, the escapes
4547 must make the string shorter.
4548 Function "fish/fish.c:execute_and_inline"
4550 static int
4552 execute_and_inline (const char *cmd, int global_exit_on_error)
4553 Used to handle "<!" (execute command and inline result).
4555 Function "fish/fish.c:issue_command"
4557 int
4559 issue_command (const char *cmd, char *argv[], const char *pipecmd,
4560 int rc_exit_on_error_flag)
4561 Run a command.
4563 "rc_exit_on_error_flag" is the "exit_on_error" flag that we pass to the
4565 remote server (when issuing --remote commands). It does not cause
4566 "issue_command" itself to exit on error.
4567 Function "fish/fish.c:extended_help_message"
4569 void
4571 extended_help_message (void)
4572 Print an extended help message when the user types in an unknown
4574 command for the first command issued. A common case is the user doing:
4575 guestfish disk.img
4577 expecting guestfish to open disk.img (in fact, this tried to run a non-
4579 existent command "disk.img").
4580 Function "fish/fish.c:error_cb"
4582 static void
4584 error_cb (guestfs_h *g, void *data, const char *msg)
4585 Error callback. This replaces the standard libguestfs error handler.
4587 Function "fish/fish.c:free_n_strings"
4589 static void
4591 free_n_strings (char **str, size_t len)
4592 Free strings from a non-NULL terminated "char**".
4594 Function "fish/fish.c:decode_ps1"
4596 static char *
4598 decode_ps1 (const char *str)
4599 Decode "str" into the final printable prompt string.
4601 Function "fish/fish.c:win_prefix"
4603 char *
4605 win_prefix (const char *path)
4606 Resolve the special "win:..." form for Windows-specific paths. The
4608 generated code calls this for all device or path arguments.
4609 The function returns a newly allocated string, and the caller must free
4611 this string; else display an error and return "NULL".
4612 Function "fish/fish.c:file_in"
4614 char *
4616 file_in (const char *arg)
4617 Resolve the special "FileIn" paths ("-" or "-<<END" or filename).
4619 The caller (fish/cmds.c) will call "free_file_in" after the command has
4621 run which should clean up resources.
4622 Function "fish/fish.c:file_out"
4624 char *
4626 file_out (const char *arg)
4627 Resolve the special "FileOut" paths ("-" or filename).
4629 The caller (fish/cmds.c) will call "free (str)" after the command has
4631 run.
4632 Function "fish/fish.c:progress_callback"
4634 void
4636 progress_callback (guestfs_h *g, void *data,
4637 uint64_t event, int event_handle, int flags,
4638 const char *buf, size_t buf_len,
4639 const uint64_t *array, size_t array_len)
4640 Callback which displays a progress bar.
4642 File fish/glob.c
4644 This file implements the guestfish "glob" command.
4646 Function "fish/glob.c:expand_devicename"
4648 static char **
4650 expand_devicename (guestfs_h *g, const char *device)
4651 Glob-expand device patterns, such as "/dev/sd*"
4653 (https://bugzilla.redhat.com/635971).
4654 There is no "guestfs_glob_expand_device" function because the
4656 equivalent can be implemented using functions like
4657 "guestfs_list_devices".
4658 It's not immediately clear what it means to expand a pattern like
4660 "/dev/sd*". Should that include device name translation? Should the
4661 result include partitions as well as devices?
4662 Should "/dev/" + "*" return every possible device and filesystem? How
4664 about VGs? LVs?
4665 To solve this what we do is build up a list of every device, partition,
4667 etc., then glob against that list.
4668 Notes for future work (XXX):
4670 · This doesn't handle device name translation. It wouldn't be too
4672 hard to add.
4673 · Could have an API function for returning all device-like things.
4675 Function "fish/glob.c:add_strings_matching"
4677 static int
4679 add_strings_matching (char **pp, const char *glob,
4680 char ***ret, size_t *size_r)
4681 Using POSIX fnmatch(3), find strings in the list "pp" which match
4683 pattern "glob". Add strings which match to the "ret" array. *size_r
4684 is the current size of the "ret" array, which is updated with the new
4685 size.
4686 Function "fish/glob.c:single_element_list"
4688 static char **
4690 single_element_list (const char *element)
4691 Return a single element list containing "element".
4693 File fish/help.c
4695 The file implements the guestfish "help" command.
4697 Function "fish/help.c:display_help"
4699 int
4701 display_help (const char *cmd, size_t argc, char *argv[])
4702 The "help" command.
4704 This used to just list all commands, but that's not very useful.
4706 Instead display some useful context-sensitive help. This could be
4707 improved if we knew how many drives had been added already, and whether
4708 anything was mounted.
4709 File fish/hexedit.c
4711 This file implements the guestfish "hexedit" command.
4713 File fish/lcd.c
4715 Function "fish/lcd.c:run_lcd"
4717 int
4719 run_lcd (const char *cmd, size_t argc, char *argv[])
4720 guestfish "lcd" command (similar to the "lcd" command in BSD ftp).
4722 File fish/man.c
4724 Function "fish/man.c:run_man"
4726 int
4728 run_man (const char *cmd, size_t argc, char *argv[])
4729 guestfish "man" command
4731 File fish/more.c
4733 This file implements the guestfish "more" command.
4735 File fish/prep.c
4737 This file implements the guestfish -N option for creating pre-prepared
4739 disk layouts.
4740 File fish/rc.c
4742 This file implements guestfish remote (command) support.
4744 Function "fish/rc.c:rc_listen"
4746 void
4748 rc_listen (void)
4749 The remote control server (ie. "guestfish --listen").
4751 Function "fish/rc.c:rc_remote"
4753 int
4755 rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
4756 int exit_on_error)
4757 The remote control client (ie. "guestfish --remote").
4759 File fish/reopen.c
4761 This file implements the guestfish "reopen" command.
4763 File fish/setenv.c
4765 This file implements the guestfish "setenv" and "unsetenv" commands.
4767 File fish/supported.c
4769 This file implements the guestfish "supported" command.
4771 File fish/tilde.c
4773 This file implements tilde ("~") expansion of home directories in
4775 guestfish(1).
4776 Function "fish/tilde.c:try_tilde_expansion"
4778 char *
4780 try_tilde_expansion (char *str)
4781 This is called from the script loop if we find a candidate for
4783 "~username" (tilde-expansion).
4784 Function "fish/tilde.c:expand_home"
4786 static char *
4788 expand_home (char *orig, const char *append)
4789 Return $HOME + append string.
4791 Function "fish/tilde.c:find_home_for_username"
4793 static const char *
4795 find_home_for_username (const char *username, size_t ulen)
4796 Lookup "username" (of length "ulen"), return home directory if found,
4798 or "NULL" if not found.
4799 File fish/time.c
4801 This file implements the guestfish "time" command.
4803 Subdirectory python
4805 File python/handle.c
4806 This file contains a small number of functions that are written by
4808 hand. The majority of the bindings are generated (see
4809 python/actions-*.c).
4810
4812 guestfs(3), guestfs-building(1), guestfs-examples(3),
4813 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
4814 guestfs-testing(1), libguestfs-test-tool(1),
4815 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
4816
4818 Richard W.M. Jones ("rjones at redhat dot com")
4819
4821 Copyright (C) 2009-2020 Red Hat Inc.
4822
4824 This library is free software; you can redistribute it and/or modify it
4825 under the terms of the GNU Lesser General Public License as published
4826 by the Free Software Foundation; either version 2 of the License, or
4827 (at your option) any later version.
4828 This library is distributed in the hope that it will be useful, but
4830 WITHOUT ANY WARRANTY; without even the implied warranty of
4831 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4832 Lesser General Public License for more details.
4833 You should have received a copy of the GNU Lesser General Public
4835 License along with this library; if not, write to the Free Software
4836 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
4837 02110-1301 USA
4838
4840 To get a list of bugs against libguestfs, use this link:
4841 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
4842 To report a new bug against libguestfs, use this link:
4844 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
4845 When reporting a bug, please supply:
4847 · The version of libguestfs.
4849 · Where you got libguestfs (eg. which Linux distro, compiled from
4851 source, etc)
4852 · Describe the bug accurately and give a way to reproduce it.
4854 · Run libguestfs-test-tool(1) and paste the complete, unedited output
4856 into the bug report.
4857libguestfs-1.42.0 2020-03-09 guestfs-hacking(1)