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_builddir)/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 · Consider updating gnulib to latest upstream version.
822 · Create new stable and development directories under
824 http://libguestfs.org/download.
825 · Edit website/index.html.in.
827 · Set the version (in configure.ac) to the new stable version, ie.
829 1.XX.0, and commit it:
830 ./localconfigure
832 make distclean -k
833 ./localconfigure
834 make && make dist
835 make maintainer-commit
836 make maintainer-tag
837 · Create the stable branch in git:
839 git branch stable-1.XX
841 git push origin stable-1.XX
842 · Do a full release of the stable branch.
844 · Set the version to the next development version and commit that.
846 Optionally do a full release of the development branch.
847
849 This section documents internal functions inside libguestfs and various
850 utilities. It is intended for libguestfs developers only.
851 This section is autogenerated from "/**" comments in source files,
853 which are marked up in POD format.
854 These functions are not publicly exported, and may change or be removed
856 at any time.
857 Subdirectory lib
859 File lib/actions-support.c
860 Helper functions for the actions code in lib/actions-*.c.
862 File lib/appliance-cpu.c
864 The appliance choice of CPU model.
866 Function "lib/appliance-cpu.c:guestfs_int_get_cpu_model"
868 const char *
870 guestfs_int_get_cpu_model (int kvm)
871 Return the right CPU model to use as the qemu "-cpu" parameter or its
873 equivalent in libvirt. This returns:
874 "host"
876 The literal string "host" means use "-cpu host".
877 some string
879 Some string such as "cortex-a57" means use "-cpu cortex-a57".
880 "NULL"
882 "NULL" means no "-cpu" option at all. Note returning "NULL" does
883 not indicate an error.
884 This is made unnecessarily hard and fragile because of two stupid
886 choices in QEMU:
887 · The default for "qemu-system-aarch64 -M virt" is to emulate a
889 "cortex-a15" (WTF?).
890 · We don't know for sure if KVM will work, but "-cpu host" is broken
892 with TCG, so we almost always pass a broken "-cpu" flag if KVM is
893 semi-broken in any way.
894 File lib/appliance-kcmdline.c
896 The appliance kernel command line.
898 Definition "lib/appliance-kcmdline.c:VALID_TERM"
900 #define VALID_TERM
902 Check that the $TERM environment variable is reasonable before we pass
904 it through to the appliance.
905 Function "lib/appliance-kcmdline.c:get_root_uuid_with_file"
907 static char *
909 get_root_uuid_with_file (guestfs_h *g, const char *appliance)
910 Given a disk image containing an extX filesystem, return the UUID. The
912 file(1) command does the hard work.
913 Function "lib/appliance-kcmdline.c:run_qemu_img_dd"
915 static int
917 run_qemu_img_dd (guestfs_h *g, const char *in_file, char *out_file)
918 Read the first 256k bytes of the in_file with qemu-img(1) command and
920 write them into the out_file. That may be useful to get UUID of the
921 QCOW2 disk image with further file(1) command. The function returns
922 zero if successful, otherwise -1.
923 Function "lib/appliance-kcmdline.c:get_root_uuid"
925 static char *
927 get_root_uuid (guestfs_h *g, const char *appliance)
928 Get the UUID from the appliance disk image.
930 Function "lib/appliance-kcmdline.c:guestfs_int_appliance_command_line"
932 char *
934 guestfs_int_appliance_command_line (guestfs_h *g,
935 const char *appliance,
936 int flags)
937 Construct the Linux command line passed to the appliance. This is used
939 by the "direct" and "libvirt" backends, and is simply located in this
940 file because it's a convenient place for this common code.
941 The "appliance" parameter is the filename of the appliance (could be
943 NULL) from which we obtain the root UUID.
944 The "flags" parameter can contain the following flags logically or'd
946 together (or 0):
947 "APPLIANCE_COMMAND_LINE_IS_TCG"
949 If we are launching a qemu TCG guest (ie. KVM is known to be
950 disabled or unavailable). If you don't know, don't pass this flag.
951 Note that this function returns a newly allocated buffer which must be
953 freed by the caller.
954 File lib/appliance-uefi.c
956 Find the UEFI firmware needed to boot the appliance.
958 See also lib/uefi.c (autogenerated file) containing the firmware file
960 locations.
961 Function "lib/appliance-uefi.c:guestfs_int_get_uefi"
963 int
965 guestfs_int_get_uefi (guestfs_h *g, char *const *firmwares,
966 const char **firmware, char **code, char **vars,
967 int *flags)
968 Return the location of firmware needed to boot the appliance. This is
970 aarch64 only currently, since that's the only architecture where UEFI
971 is mandatory (and that only for RHEL).
972 "firmwares" is an optional list of allowed values for the firmware
974 autoselection of libvirt. It is "NULL" to indicate it is not supported.
975 *firmware is set to one of the strings in "firmwares" in case one can
976 be used.
977 *code is initialized with the path to the read-only UEFI code file.
979 *vars is initialized with the path to a copy of the UEFI vars file
980 (which is cleaned up automatically on exit).
981 In case a UEFI firmware is available, either *firmware is set to a
983 non-"NULL" value, or *code and *vars are.
984 *code and *vars should be freed by the caller, and *firmware must not.
986 If the function returns "-1" then there was a real error which should
988 cause appliance building to fail (no UEFI firmware is not an error).
989 See also virt-v2v.git/v2v/utils.ml:find_uefi_firmware
991 File lib/appliance.c
993 This file deals with building the libguestfs appliance.
995 Function "lib/appliance.c:guestfs_int_build_appliance"
997 int
999 guestfs_int_build_appliance (guestfs_h *g,
1000 char **kernel_rtn,
1001 char **initrd_rtn,
1002 char **appliance_rtn)
1003 Locate or build the appliance.
1005 This function locates or builds the appliance as necessary, handling
1007 the supermin appliance, caching of supermin-built appliances, or using
1008 either a fixed or old-style appliance.
1009 The return value is 0 = good, "-1" = error. Returned in
1011 "appliance.kernel" will be the name of the kernel to use,
1012 "appliance.initrd" the name of the initrd, "appliance.image" the name
1013 of the ext2 root filesystem. "appliance.image" can be "NULL", meaning
1014 that we are using an old-style (non-ext2) appliance. All three strings
1015 must be freed by the caller. However the referenced files themselves
1016 must not be deleted.
1017 The process is as follows:
1019 1. Look in "path" which contains a supermin appliance skeleton. If no
1021 element has this, skip straight to step 3.
1022 2. Call "supermin --build" to build the full appliance (if it needs to
1024 be rebuilt). If this is successful, return the full appliance.
1025 3. Check "path", looking for a fixed appliance. If one is found,
1027 return it.
1028 4. Check "path", looking for an old-style appliance. If one is found,
1030 return it.
1031 The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/
1033 and consists of up to four files:
1034 $TMPDIR/.guestfs-$UID/lock - the supermin lock file
1036 $TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
1037 $TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
1038 $TMPDIR/.guestfs-$UID/appliance.d/root - the appliance
1039 Multiple instances of libguestfs with the same UID may be racing to
1041 create an appliance. However (since supermin ≥ 5) supermin provides a
1042 --lock flag and atomic update of the appliance.d subdirectory.
1043 Function "lib/appliance.c:locate_or_build_appliance"
1045 static int
1047 locate_or_build_appliance (guestfs_h *g,
1048 struct appliance_files *appliance,
1049 const char *path)
1050 Check "path", looking for one of appliances: supermin appliance, fixed
1052 appliance or old-style appliance. If one of the fixed appliances is
1053 found, return it. If the supermin appliance skeleton is found, build
1054 and return appliance.
1055 Return values:
1057 1 = appliance is found, returns C<appliance>,
1059 0 = appliance not found,
1060 -1 = error which aborts the launch process.
1061 Function "lib/appliance.c:search_appliance"
1063 static int
1065 search_appliance (guestfs_h *g, struct appliance_files *appliance)
1066 Search elements of "g->path", returning the first "appliance" element
1068 which matches the predicate function "locate_or_build_appliance".
1069 Return values:
1071 1 = a path element matched, returns C<appliance>,
1073 0 = no path element matched,
1074 -1 = error which aborts the launch process.
1075 Function "lib/appliance.c:build_supermin_appliance"
1077 static int
1079 build_supermin_appliance (guestfs_h *g,
1080 const char *supermin_path,
1081 struct appliance_files *appliance)
1082 Build supermin appliance from "supermin_path" to $TMPDIR/.guestfs-$UID.
1084 Returns: 0 = built or "-1" = error (aborts launch).
1086 Function "lib/appliance.c:run_supermin_build"
1088 static int
1090 run_supermin_build (guestfs_h *g,
1091 const char *lockfile,
1092 const char *appliancedir,
1093 const char *supermin_path)
1094 Run "supermin --build" and tell it to generate the appliance.
1096 Function "lib/appliance.c:dir_contains_file"
1098 static int
1100 dir_contains_file (guestfs_h *g, const char *dir, const char *file)
1101 Returns true iff "file" is contained in "dir".
1103 Function "lib/appliance.c:dir_contains_files"
1105 static int
1107 dir_contains_files (guestfs_h *g, const char *dir, ...)
1108 Returns true iff every listed file is contained in "dir".
1110 File lib/command.c
1112 A wrapper for running external commands, loosely based on libvirt's
1114 "virCommand" interface.
1115 In outline to use this interface you must:
1117 1. Create a new command handle:
1119 struct command *cmd;
1121 cmd = guestfs_int_new_command (g);
1122 2. Either add arguments:
1124 guestfs_int_cmd_add_arg (cmd, "qemu-img");
1126 guestfs_int_cmd_add_arg (cmd, "info");
1127 guestfs_int_cmd_add_arg (cmd, filename);
1128 (NB: You don't need to add a "NULL" argument at the end.)
1130 3. Or construct a command using a mix of quoted and unquoted strings.
1132 (This is useful for system(3)/"popen("r")"-style shell commands,
1133 with the added safety of allowing args to be quoted properly).
1134 guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
1136 guestfs_int_cmd_add_string_quoted (cmd, filename);
1137 4. Set various flags, such as whether you want to capture errors in
1139 the regular libguestfs error log.
1140 5. Run the command. This is what does the fork(2) call, optionally
1142 loops over the output, and then does a waitpid(3) and returns the
1143 exit status of the command.
1144 r = guestfs_int_cmd_run (cmd);
1146 if (r == -1)
1147 // error
1148 // else test r using the WIF* functions
1149 6. Close the handle:
1151 guestfs_int_cmd_close (cmd);
1153 (or use "CLEANUP_CMD_CLOSE").
1155 Function "lib/command.c:guestfs_int_new_command"
1157 struct command *
1159 guestfs_int_new_command (guestfs_h *g)
1160 Create a new command handle.
1162 Function "lib/command.c:guestfs_int_cmd_add_arg"
1164 void
1166 guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)
1167 Add single arg (for "execv"-style command execution).
1169 Function "lib/command.c:guestfs_int_cmd_add_arg_format"
1171 void
1173 guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)
1174 Add single arg (for "execv"-style command execution) using a
1176 printf(3)-style format string.
1177 Function "lib/command.c:guestfs_int_cmd_add_string_unquoted"
1179 void
1181 guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)
1182 Add a string (for system(3)-style command execution).
1184 This variant adds the strings without quoting them, which is dangerous
1186 if the string contains untrusted content.
1187 Function "lib/command.c:guestfs_int_cmd_add_string_quoted"
1189 void
1191 guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)
1192 Add a string (for system(3)-style command execution).
1194 The string is enclosed in double quotes, with any special characters
1196 within the string which need escaping done. This is used to add a
1197 single argument to a system(3)-style command string.
1198 Function "lib/command.c:guestfs_int_cmd_set_stdout_callback"
1200 void
1202 guestfs_int_cmd_set_stdout_callback (struct command *cmd,
1203 cmd_stdout_callback stdout_callback,
1204 void *stdout_data, unsigned flags)
1205 Set a callback which will capture stdout.
1207 If flags contains "CMD_STDOUT_FLAG_LINE_BUFFER" (the default), then the
1209 callback is called line by line on the output. If there is a trailing
1210 "\n" then it is automatically removed before the callback is called.
1211 The line buffer is "\0"-terminated.
1212 If flags contains "CMD_STDOUT_FLAG_UNBUFFERED", then buffers are passed
1214 to the callback as it is received from the command. Note in this case
1215 the buffer is not "\0"-terminated, so you need to may attention to the
1216 length field in the callback.
1217 If flags contains "CMD_STDOUT_FLAG_WHOLE_BUFFER", then the callback is
1219 called exactly once, with the entire buffer. Note in this case the
1220 buffer is not "\0"-terminated, so you need to may attention to the
1221 length field in the callback.
1222 Function "lib/command.c:guestfs_int_cmd_set_stderr_to_stdout"
1224 void
1226 guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)
1227 Equivalent to adding "2>&1" to the end of the command. This is
1229 incompatible with the "capture_errors" flag, because it doesn't make
1230 sense to combine them.
1231 Function "lib/command.c:guestfs_int_cmd_clear_capture_errors"
1233 void
1235 guestfs_int_cmd_clear_capture_errors (struct command *cmd)
1236 Clear the "capture_errors" flag. This means that any errors will go to
1238 stderr, instead of being captured in the event log, and that is usually
1239 undesirable.
1240 Function "lib/command.c:guestfs_int_cmd_clear_close_files"
1242 void
1244 guestfs_int_cmd_clear_close_files (struct command *cmd)
1245 Don't close file descriptors after the fork.
1247 XXX Should allow single fds to be sent to child process.
1249 Function "lib/command.c:guestfs_int_cmd_set_child_callback"
1251 void
1253 guestfs_int_cmd_set_child_callback (struct command *cmd,
1254 cmd_child_callback child_callback,
1255 void *data)
1256 Set a function to be executed in the child, right before the execution.
1258 Can be used to setup the child, for example changing its current
1259 directory.
1260 Function "lib/command.c:guestfs_int_cmd_set_child_rlimit"
1262 void
1264 guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)
1265 Set up child rlimits, in case the process we are running could consume
1267 lots of space or time.
1268 Function "lib/command.c:finish_command"
1270 static void
1272 finish_command (struct command *cmd)
1273 Finish off the command by either "NULL"-terminating the argv array or
1275 adding a terminating "\0" to the string, or die with an internal error
1276 if no command has been added.
1277 Function "lib/command.c:loop"
1279 static int
1281 loop (struct command *cmd)
1282 The loop which reads errors and output and directs it either to the log
1284 or to the stdout callback as appropriate.
1285 Function "lib/command.c:guestfs_int_cmd_run"
1287 int
1289 guestfs_int_cmd_run (struct command *cmd)
1290 Fork, run the command, loop over the output, and waitpid.
1292 Returns the exit status. Test it using "WIF*" macros.
1294 On error: Calls "error" and returns "-1".
1296 Function "lib/command.c:guestfs_int_cmd_pipe_run"
1298 int
1300 guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)
1301 Fork and run the command, but don't wait. Roughly equivalent to
1303 "popen (..., "r"|"w")".
1304 Returns the file descriptor of the pipe, connected to stdout ("r") or
1306 stdin ("w") of the child process.
1307 After reading/writing to this pipe, call "guestfs_int_cmd_pipe_wait" to
1309 wait for the status of the child.
1310 Errors from the subcommand cannot be captured to the error log using
1312 this interface. Instead the caller should call
1313 "guestfs_int_cmd_get_pipe_errors" (after "guestfs_int_cmd_pipe_wait"
1314 returns an error).
1315 Function "lib/command.c:guestfs_int_cmd_pipe_wait"
1317 int
1319 guestfs_int_cmd_pipe_wait (struct command *cmd)
1320 Wait for a subprocess created by "guestfs_int_cmd_pipe_run" to finish.
1322 On error (eg. failed syscall) this returns "-1" and sets the error. If
1323 the subcommand fails, then use "WIF*" macros to check this, and call
1324 "guestfs_int_cmd_get_pipe_errors" to read the error messages printed by
1325 the child.
1326 Function "lib/command.c:guestfs_int_cmd_get_pipe_errors"
1328 char *
1330 guestfs_int_cmd_get_pipe_errors (struct command *cmd)
1331 Read the error messages printed by the child. The caller must free the
1333 returned buffer after use.
1334 Function "lib/command.c:guestfs_int_cmd_close"
1336 void
1338 guestfs_int_cmd_close (struct command *cmd)
1339 Close the "cmd" object and free all resources.
1341 Function "lib/command.c:process_line_buffer"
1343 static void
1345 process_line_buffer (struct command *cmd, int closed)
1346 Deal with buffering stdout for the callback.
1348 File lib/conn-socket.c
1350 This file handles connections to the child process where this is done
1352 over regular POSIX sockets.
1353 Function "lib/conn-socket.c:handle_log_message"
1355 static int
1357 handle_log_message (guestfs_h *g,
1358 struct connection_socket *conn)
1359 This is called if "conn->console_sock" becomes ready to read while we
1361 are doing one of the connection operations above. It reads and deals
1362 with the log message.
1363 Returns:
1365 1 log message(s) were handled successfully
1367 0 connection to appliance closed
1369 "-1"
1371 error
1372 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_listening"
1374 struct connection *
1376 guestfs_int_new_conn_socket_listening (guestfs_h *g,
1377 int daemon_accept_sock,
1378 int console_sock)
1379 Create a new socket connection, listening.
1381 Note that it's OK for "console_sock" to be passed as "-1", meaning
1383 there's no console available for this appliance.
1384 After calling this, "daemon_accept_sock" is owned by the connection,
1386 and will be closed properly either in "accept_connection" or
1387 "free_connection".
1388 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_connected"
1390 struct connection *
1392 guestfs_int_new_conn_socket_connected (guestfs_h *g,
1393 int daemon_sock,
1394 int console_sock)
1395 Create a new socket connection, connected.
1397 As above, but the caller passes us a connected "daemon_sock" and
1399 promises not to call "accept_connection".
1400 File lib/create.c
1402 APIs for creating empty disks.
1404 Mostly this consists of wrappers around the qemu-img(1) program.
1406 Definition "lib/create.c:VALID_FORMAT"
1408 #define VALID_FORMAT
1410 Check for valid backing format. Allow any "^[[:alnum]]+$" (in C
1412 locale), but limit the length to something reasonable.
1413 File lib/drives.c
1415 Drives added are stored in an array in the handle. Code here manages
1417 that array and the individual "struct drive" data.
1418 Function "lib/drives.c:create_overlay"
1420 static int
1422 create_overlay (guestfs_h *g, struct drive *drv)
1423 For readonly drives, create an overlay to protect the original drive
1425 content. Note we never need to clean up these overlays since they are
1426 created in the temporary directory and deleted when the handle is
1427 closed.
1428 Function "lib/drives.c:create_drive_file"
1430 static struct drive *
1432 create_drive_file (guestfs_h *g,
1433 const struct drive_create_data *data)
1434 Create and free the "struct drive".
1436 Function "lib/drives.c:create_drive_dev_null"
1438 static struct drive *
1440 create_drive_dev_null (guestfs_h *g,
1441 struct drive_create_data *data)
1442 Create the special /dev/null drive.
1444 Traditionally you have been able to use /dev/null as a filename, as
1446 many times as you like. Ancient KVM (RHEL 5) cannot handle adding
1447 /dev/null readonly. qemu 1.2 + virtio-scsi segfaults when you use any
1448 zero-sized file including /dev/null.
1449 Because of these problems, we replace /dev/null with a non-zero sized
1451 temporary file. This shouldn't make any difference since users are not
1452 supposed to try and access a null drive.
1453 Function "lib/drives.c:drive_to_string"
1455 static char *
1457 drive_to_string (guestfs_h *g, const struct drive *drv)
1458 Convert a "struct drive" to a string for debugging. The caller must
1460 free this string.
1461 Function "lib/drives.c:add_drive_to_handle_at"
1463 static void
1465 add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)
1466 Add "struct drive" to the "g->drives" vector at the given index
1468 "drv_index". If the array isn't large enough it is reallocated. The
1469 index must not contain a drive already.
1470 Function "lib/drives.c:add_drive_to_handle"
1472 static void
1474 add_drive_to_handle (guestfs_h *g, struct drive *d)
1475 Add struct drive to the end of the "g->drives" vector in the handle.
1477 Function "lib/drives.c:guestfs_int_add_dummy_appliance_drive"
1479 void
1481 guestfs_int_add_dummy_appliance_drive (guestfs_h *g)
1482 Called during launch to add a dummy slot to "g->drives".
1484 Function "lib/drives.c:guestfs_int_free_drives"
1486 void
1488 guestfs_int_free_drives (guestfs_h *g)
1489 Free up all the drives in the handle.
1491 Definition "lib/drives.c:VALID_FORMAT_IFACE"
1493 #define VALID_FORMAT_IFACE
1495 Check string parameter matches regular expression "^[-_[:alnum:]]+$"
1497 (in C locale).
1498 Definition "lib/drives.c:VALID_DISK_LABEL"
1500 #define VALID_DISK_LABEL
1502 Check the disk label is reasonable. It can't contain certain
1504 characters, eg. '/', ','. However be stricter here and ensure it's
1505 just alphabetic and ≤ 20 characters in length.
1506 Definition "lib/drives.c:VALID_HOSTNAME"
1508 #define VALID_HOSTNAME
1510 Check the server hostname is reasonable.
1512 Function "lib/drives.c:valid_port"
1514 static int
1516 valid_port (int port)
1517 Check the port number is reasonable.
1519 Function "lib/drives.c:valid_blocksize"
1521 static int
1523 valid_blocksize (int blocksize)
1524 Check the block size is reasonable. It can't be other then 512 or
1526 4096.
1527 Function "lib/drives.c:guestfs_impl_remove_drive"
1529 int
1531 guestfs_impl_remove_drive (guestfs_h *g, const char *label)
1532 This function implements "guestfs_remove_drive" in guestfs(3).
1534 Depending on whether we are hotplugging or not, this function does
1536 slightly different things: If not hotplugging, then the drive just
1537 disappears as if it had never been added. The later drives "move up"
1538 to fill the space. When hotplugging we have to do some complex stuff,
1539 and we usually end up leaving an empty ("NULL") slot in the "g->drives"
1540 vector.
1541 Function "lib/drives.c:guestfs_int_checkpoint_drives"
1543 size_t
1545 guestfs_int_checkpoint_drives (guestfs_h *g)
1546 Checkpoint and roll back drives, so that groups of drives can be added
1548 atomically. Only used by "guestfs_add_domain" in guestfs(3).
1549 Function "lib/drives.c:guestfs_impl_debug_drives"
1551 char **
1553 guestfs_impl_debug_drives (guestfs_h *g)
1554 Internal function to return the list of drives.
1556 File lib/errors.c
1558 This file handles errors, and also debug, trace and warning messages.
1560 Errors in libguestfs API calls are handled by setting an error message
1562 and optional errno in the handle. The caller has the choice of testing
1563 API calls to find out if they failed and then querying the last error
1564 from the handle, and/or getting a callback.
1565 From the point of view of the library source, generally you should use
1567 the "error" or "perrorf" macros along error paths, eg:
1568 if (something_bad) {
1570 error (g, "something bad happened");
1571 return -1;
1572 }
1573 Make sure to call the "error" or "perrorf" macro exactly once along
1575 each error path, since the handle can only store a single error and the
1576 previous error will be overwritten.
1577 Function "lib/errors.c:guestfs_int_warning"
1579 void
1581 guestfs_int_warning (guestfs_h *g, const char *fs, ...)
1582 Print a warning.
1584 Code should not call this function directly. Use the
1586 "warning (g, fs, ...)" macro.
1587 Warnings are printed unconditionally. We try to make these rare:
1589 Generally speaking, a warning should either be an error, or if it's not
1590 important for end users then it should be a debug message.
1591 Function "lib/errors.c:guestfs_int_debug"
1593 void
1595 guestfs_int_debug (guestfs_h *g, const char *fs, ...)
1596 Print a debug message.
1598 Code should not call this function directly. To add debug messages in
1600 the library, use the "debug (g, fs, ...)" macro. The macro checks if
1601 "g->verbose" is false and avoids the function call, meaning the macro
1602 is more efficient.
1603 Function "lib/errors.c:guestfs_int_trace"
1605 void
1607 guestfs_int_trace (guestfs_h *g, const char *fs, ...)
1608 Print a trace message.
1610 Do not call this function. All calls are generated automatically.
1612 Function "lib/errors.c:guestfs_int_error_errno"
1614 void
1616 guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)
1617 Set the last error and errno in the handle, and optionally raise the
1619 error callback if one is defined.
1620 If you don't need to set errno, use the "error (g, fs, ...)" macro
1622 instead of calling this directly. If you need to set errno then there
1623 is no macro wrapper, so calling this function directly is fine.
1624 Function "lib/errors.c:guestfs_int_perrorf"
1626 void
1628 guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)
1629 Similar to perror(3), but it sets the last error in the handle, raises
1631 the error callback if one is defined, and supports format strings.
1632 You should probably use the "perrorf (g, fs, ...)" macro instead of
1634 calling this directly.
1635 Function "lib/errors.c:guestfs_int_launch_failed_error"
1637 void
1639 guestfs_int_launch_failed_error (guestfs_h *g)
1640 Raise a launch failed error in a standard format.
1642 Since this is the most common error seen by people who have
1644 installation problems, buggy qemu, etc, and since no one reads the FAQ,
1645 describe in this error message what resources are available to debug
1646 launch problems.
1647 Function "lib/errors.c:guestfs_int_unexpected_close_error"
1649 void
1651 guestfs_int_unexpected_close_error (guestfs_h *g)
1652 Raise an error if the appliance unexpectedly crashes after launch.
1654 Function "lib/errors.c:guestfs_int_launch_timeout"
1656 void
1658 guestfs_int_launch_timeout (guestfs_h *g)
1659 Raise an error if the appliance hangs during launch.
1661 Function "lib/errors.c:guestfs_int_external_command_failed"
1663 void
1665 guestfs_int_external_command_failed (guestfs_h *g, int status,
1666 const char *cmd_name, const char *extra)
1667 Raise an error if an external command fails.
1669 "status" is the status code of the command (eg. returned from
1671 waitpid(2) or system(3)). This function turns the status code into an
1672 explanatory string.
1673 File lib/events.c
1675 Function "lib/events.c:replace_old_style_event_callback"
1677 static void
1679 replace_old_style_event_callback (guestfs_h *g,
1680 guestfs_event_callback cb,
1681 uint64_t event_bitmask,
1682 void *opaque,
1683 void *opaque2)
1684 Emulate old-style callback API.
1686 There were no event handles, so multiple callbacks per event were not
1688 supported. Calling the same "guestfs_set_*_callback" function would
1689 replace the existing event. Calling it with "cb == NULL" meant that
1690 the caller wanted to remove the callback.
1691 File lib/guestfs-internal-all.h
1693 This header contains definitions which are shared by all parts of
1695 libguestfs, ie. the daemon, the library, language bindings and virt
1696 tools (ie. all C code).
1697 If you need a definition used by only the library, put it in
1699 lib/guestfs-internal.h instead.
1700 If a definition is used by only a single tool, it should not be in any
1702 shared header file at all.
1703 File lib/guestfs-internal.h
1705 This header file is included in the libguestfs library (lib/) only.
1707 See also lib/guestfs-internal-all.h.
1709 Structure "lib/guestfs-internal.h:event"
1711 struct event {
1713 uint64_t event_bitmask;
1714 guestfs_event_callback cb;
1715 void *opaque;
1716 /* opaque2 is not exposed through the API, but is used internally to
1718 * emulate the old-style callback API.
1719 */
1720 void *opaque2;
1721 };
1722 This struct is used to maintain a list of events registered against the
1724 handle. See "g->events" in the handle.
1725 Structure "lib/guestfs-internal.h:drive"
1727 struct drive {
1729 /* Original source of the drive, eg. file:..., http:... */
1730 struct drive_source src;
1731 /* If the drive is readonly, then an overlay [a local file] is
1733 * created before launch to protect the original drive content, and
1734 * the filename is stored here. Backends should open this file if
1735 * it is non-NULL, else consult the original source above.
1736 *
1737 * Note that the overlay is in a backend-specific format, probably
1738 * different from the source format. eg. qcow2, UML COW.
1739 */
1740 char *overlay;
1741 /* Various per-drive flags. */
1743 bool readonly;
1744 char *iface;
1745 char *name;
1746 char *disk_label;
1747 char *cachemode;
1748 enum discard discard;
1749 bool copyonread;
1750 int blocksize;
1751 };
1752 There is one "struct drive" per drive, including hot-plugged drives.
1754 Structure "lib/guestfs-internal.h:backend_ops"
1756 struct backend_ops {
1758 /* Size (in bytes) of the per-handle data structure needed by this
1759 * backend. The data pointer is allocated and freed by libguestfs
1760 * and passed to the functions in the 'void *data' parameter.
1761 * Inside the data structure is opaque to libguestfs. Any strings
1762 * etc pointed to by it must be freed by the backend during
1763 * shutdown.
1764 */
1765 size_t data_size;
1766 /* Create a COW overlay on top of a drive. This must be a local
1768 * file, created in the temporary directory. This is called when
1769 * the drive is added to the handle.
1770 */
1771 char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);
1772 /* Launch and shut down. */
1774 int (*launch) (guestfs_h *g, void *data, const char *arg);
1775 int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);
1776 /* Miscellaneous. */
1778 int (*get_pid) (guestfs_h *g, void *data);
1779 int (*max_disks) (guestfs_h *g, void *data);
1780 /* Hotplugging drives. */
1782 int (*hot_add_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1783 int (*hot_remove_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1784 };
1785 Backend operations.
1787 Each backend (eg. libvirt, direct) defines some functions which get run
1789 at various places in the handle lifecycle (eg. at launch, shutdown).
1790 The backend defines this struct pointing to those functions.
1791 Structure "lib/guestfs-internal.h:connection"
1793 struct connection {
1795 const struct connection_ops *ops;
1796 /* In the real struct, private data used by each connection module
1798 * follows here.
1799 */
1800 };
1801 Connection module.
1803 A "connection" represents the appliance console connection plus the
1805 daemon connection. It hides the underlying representation (POSIX
1806 sockets, "virStreamPtr").
1807 Structure "lib/guestfs-internal.h:cached_feature"
1809 struct cached_feature {
1811 char *group;
1812 int result;
1813 };
1814 Cache of queried features.
1816 Used to cache the appliance features (see lib/available.c).
1818 Structure "lib/guestfs-internal.h:guestfs_h"
1820 struct guestfs_h {
1822 struct guestfs_h *next; /* Linked list of open handles. */
1823 enum state state; /* See the state machine diagram in guestfs(3)*/
1824 /* Lock acquired when entering any public guestfs_* function to
1826 * protect the handle.
1827 */
1828 gl_recursive_lock_define (, lock);
1829 /**** Configuration of the handle. ****/
1831 bool verbose; /* Debugging. */
1832 bool trace; /* Trace calls. */
1833 bool autosync; /* Autosync. */
1834 bool direct_mode; /* Direct mode. */
1835 bool recovery_proc; /* Create a recovery process. */
1836 bool enable_network; /* Enable the network. */
1837 bool selinux; /* selinux enabled? */
1838 bool pgroup; /* Create process group for children? */
1839 bool close_on_exit; /* Is this handle on the atexit list? */
1840 int smp; /* If > 1, -smp flag passed to hv. */
1842 int memsize; /* Size of RAM (megabytes). */
1843 char *path; /* Path to the appliance. */
1845 char *hv; /* Hypervisor (HV) binary. */
1846 char *append; /* Append to kernel command line. */
1847 struct hv_param *hv_params; /* Extra hv parameters. */
1849 char *program; /* Program name. */
1851 char *identifier; /* Handle identifier. */
1852 /* Array of drives added by add-drive* APIs.
1854 *
1855 * Before launch this list can be empty or contain some drives.
1856 *
1857 * During launch, a dummy slot may be added which represents the
1858 * slot taken up by the appliance drive.
1859 *
1860 * When hotplugging is supported by the backend, drives can be
1861 * added to the end of this list after launch. Also hot-removing a
1862 * drive causes a NULL slot to appear in the list.
1863 *
1864 * During shutdown, this list is deleted, so that each launch gets a
1865 * fresh set of drives (however callers: don't do this, create a new
1866 * handle each time).
1867 *
1868 * Always use ITER_DRIVES macro to iterate over this list!
1869 */
1870 struct drive **drives;
1871 size_t nr_drives;
1872 #define ITER_DRIVES(g,i,drv) \
1874 for (i = 0; i < (g)->nr_drives; ++i) \
1875 if (((drv) = (g)->drives[i]) != NULL)
1876 /* Backend. NB: Use guestfs_int_set_backend to change the backend. */
1878 char *backend; /* The full string, always non-NULL. */
1879 char *backend_arg; /* Pointer to the argument part. */
1880 const struct backend_ops *backend_ops;
1881 void *backend_data; /* Per-handle data. */
1882 char **backend_settings; /* Backend settings (can be NULL). */
1883 /**** Runtime information. ****/
1885 /* Temporary and cache directories. */
1886 /* The actual temporary directory - this is not created with the
1887 * handle, you have to call guestfs_int_lazy_make_tmpdir.
1888 */
1889 char *tmpdir;
1890 char *sockdir;
1891 /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
1892 char *env_tmpdir; /* $TMPDIR (NULL if not set) */
1893 char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/
1894 char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
1895 char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */
1896 /* Error handler, plus stack of old error handlers. */
1898 gl_tls_key_t error_data;
1899 /* Linked list of error_data structures allocated for this handle,
1901 * plus a mutex to protect the linked list.
1902 */
1903 gl_lock_define (, error_data_list_lock);
1904 struct error_data *error_data_list;
1905 /* Out of memory error handler. */
1907 guestfs_abort_cb abort_cb;
1908 /* Events. */
1910 struct event *events;
1911 size_t nr_events;
1912 /* Private data area. */
1914 struct hash_table *pda;
1915 struct pda_entry *pda_next;
1916 /* User cancelled transfer. Not signal-atomic, but it doesn't
1918 * matter for this case because we only care if it is != 0.
1919 */
1920 int user_cancel;
1921 struct timeval launch_t; /* The time that we called guestfs_launch. */
1923 /* Used by bindtests. */
1925 FILE *test_fp;
1926 /* Used to generate unique numbers, eg for temp files. To use this,
1928 * '++g->unique'. Note these are only unique per-handle, not
1929 * globally unique.
1930 */
1931 int unique;
1932 /*** Protocol. ***/
1934 struct connection *conn; /* Connection to appliance. */
1935 int msg_next_serial;
1936 #if HAVE_FUSE
1938 /**** Used by the mount-local APIs. ****/
1939 char *localmountpoint;
1940 struct fuse *fuse; /* FUSE handle. */
1941 int ml_dir_cache_timeout; /* Directory cache timeout. */
1942 Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
1943 int ml_read_only; /* If mounted read-only. */
1944 int ml_debug_calls; /* Extra debug info on each FUSE call. */
1945 #endif
1946 #ifdef HAVE_LIBVIRT_BACKEND
1948 /* Used by lib/libvirt-auth.c. */
1949 #define NR_CREDENTIAL_TYPES 9
1950 unsigned int nr_supported_credentials;
1951 int supported_credentials[NR_CREDENTIAL_TYPES];
1952 const char *saved_libvirt_uri; /* Doesn't need to be freed. */
1953 bool wrapper_warning_done;
1954 unsigned int nr_requested_credentials;
1955 virConnectCredentialPtr requested_credentials;
1956 #endif
1957 /* Cached features. */
1959 struct cached_feature *features;
1960 size_t nr_features;
1961 /* Used by lib/info.c. -1 = not tested or error; else 0 or 1. */
1963 int qemu_img_supports_U_option;
1964 };
1965 The libguestfs handle.
1967 Structure "lib/guestfs-internal.h:version"
1969 struct version {
1971 int v_major;
1972 int v_minor;
1973 int v_micro;
1974 };
1975 Used for storing major.minor.micro version numbers. See lib/version.c
1977 for more information.
1978 File lib/guid.c
1980 Function "lib/guid.c:guestfs_int_validate_guid"
1982 int
1984 guestfs_int_validate_guid (const char *str)
1985 Check whether a string supposed to contain a GUID actually contains it.
1987 It can recognize strings either as
1988 "{21EC2020-3AEA-1069-A2DD-08002B30309D}" or
1989 "21EC2020-3AEA-1069-A2DD-08002B30309D".
1990 File lib/handle.c
1992 This file deals with the "guestfs_h" handle, creating it, closing it,
1994 and initializing/setting/getting fields.
1995 Function "lib/handle.c:init_libguestfs"
1997 static void
1999 init_libguestfs (void)
2000 No initialization is required by libguestfs, but libvirt and libxml2
2002 require initialization if they might be called from multiple threads.
2003 Hence this constructor function which is called when libguestfs is
2004 first loaded.
2005 Function "lib/handle.c:shutdown_backend"
2007 static int
2009 shutdown_backend (guestfs_h *g, int check_for_errors)
2010 This function is the common path for shutting down the backend qemu
2012 process.
2013 "guestfs_shutdown" calls "shutdown_backend" with "check_for_errors=1".
2015 "guestfs_close" calls "shutdown_backend" with "check_for_errors=0".
2016 "check_for_errors" is a hint to the backend about whether we care about
2018 errors or not. In the libvirt case it can be used to optimize the
2019 shutdown for speed when we don't care.
2020 Function "lib/handle.c:close_handles"
2022 static void
2024 close_handles (void)
2025 Close all open handles (called from atexit(3)).
2027 Function "lib/handle.c:guestfs_int_get_backend_setting_bool"
2029 int
2031 guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)
2032 This is a convenience function, but we might consider exporting it as
2034 an API in future.
2035 File lib/info.c
2037 Function "lib/info.c:qemu_img_supports_U_option"
2039 static int
2041 qemu_img_supports_U_option (guestfs_h *g)
2042 Test if the qemu-img info command supports the "-U" option to disable
2044 locking. The result is memoized in the handle.
2045 Note this option was added in qemu 2.11. We can remove this test when
2047 we can assume everyone is using qemu >= 2.11.
2048 File lib/inspect-icon.c
2050 Function "lib/inspect-icon.c:guestfs_int_download_to_tmp"
2052 char *
2054 guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
2055 const char *extension,
2056 uint64_t max_size)
2057 Download a guest file to a local temporary file.
2059 The name of the temporary (downloaded) file is returned. The caller
2061 must free the pointer, but does not need to delete the temporary file.
2062 It will be deleted when the handle is closed.
2063 The name of the temporary file is randomly generated, but an extension
2065 can be specified using "extension" (or pass "NULL" for none).
2066 Refuse to download the guest file if it is larger than "max_size". On
2068 this and other errors, "NULL" is returned.
2069 File lib/launch-direct.c
2071 Implementation of the "direct" backend.
2073 For more details see "BACKENDS" in guestfs(3).
2075 Function "lib/launch-direct.c:add_drive_standard_params"
2077 static int
2079 add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
2080 struct qemuopts *qopts,
2081 size_t i, struct drive *drv)
2082 Add the standard elements of the "-drive" parameter.
2084 Function "lib/launch-direct.c:add_device_blocksize_params"
2086 static int
2088 add_device_blocksize_params (guestfs_h *g, struct qemuopts *qopts,
2089 struct drive *drv)
2090 Add the physical_block_size and logical_block_size elements of the
2092 "-device" parameter.
2093 File lib/launch-libvirt.c
2095 Function "lib/launch-libvirt.c:get_source_format_or_autodetect"
2097 static char *
2099 get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)
2100 Return "drv->src.format", but if it is "NULL", autodetect the format.
2102 libvirt has disabled the feature of detecting the disk format, unless
2104 the administrator sets "allow_disk_format_probing=1" in
2105 /etc/libvirt/qemu.conf. There is no way to detect if this option is
2106 set, so we have to do format detection here using "qemu-img" and pass
2107 that to libvirt.
2108 This can still be a security issue, so in most cases it is recommended
2110 the users pass the format to libguestfs which will faithfully pass that
2111 straight through to libvirt without doing autodetection.
2112 Caller must free the returned string. On error this function sets the
2114 error in the handle and returns "NULL".
2115 Function "lib/launch-libvirt.c:make_qcow2_overlay"
2117 static char *
2119 make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
2120 const char *format)
2121 Create a qcow2 format overlay, with the given "backing_drive" (file).
2123 The "format" parameter is the backing file format. The "format"
2124 parameter can be NULL, in this case the backing format will be
2125 determined automatically. This is used to create the appliance
2126 overlay, and also for read-only drives.
2127 File lib/launch.c
2129 This file implements "guestfs_launch" in guestfs(3).
2131 Most of the work is done by the backends (see "BACKEND" in guestfs(3)),
2133 which are implemented in lib/launch-direct.c, lib/launch-libvirt.c etc,
2134 so this file mostly passes calls through to the current backend.
2135 Function "lib/launch.c:guestfs_int_launch_send_progress"
2137 void
2139 guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)
2140 This function sends a launch progress message.
2142 Launching the appliance generates approximate progress messages.
2144 Currently these are defined as follows:
2145 0 / 12: launch clock starts
2147 3 / 12: appliance created
2148 6 / 12: detected that guest kernel started
2149 9 / 12: detected that /init script is running
2150 12 / 12: launch completed successfully
2151 Notes:
2153 1. This is not a documented ABI and the behaviour may be changed or
2155 removed in future.
2156 2. Messages are only sent if more than 5 seconds has elapsed since the
2158 launch clock started.
2159 3. There is a hack in lib/proto.c to make this work.
2161 Function "lib/launch.c:guestfs_int_timeval_diff"
2163 int64_t
2165 guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)
2166 Compute "y - x" and return the result in milliseconds.
2168 Approximately the same as this code:
2170 http://www.mpp.mpg.de/~huber/util/timevaldiff.c
2171 Function "lib/launch.c:guestfs_int_unblock_sigterm"
2173 void
2175 guestfs_int_unblock_sigterm (void)
2176 Unblock the "SIGTERM" signal. Call this after fork(2) so that the
2178 parent process can send "SIGTERM" to the child process in case
2179 "SIGTERM" is blocked. See https://bugzilla.redhat.com/1460338.
2180 Function "lib/launch.c:guestfs_impl_max_disks"
2182 int
2184 guestfs_impl_max_disks (guestfs_h *g)
2185 Returns the maximum number of disks allowed to be added to the backend
2187 (backend dependent).
2188 Function "lib/launch.c:guestfs_impl_wait_ready"
2190 int
2192 guestfs_impl_wait_ready (guestfs_h *g)
2193 Implementation of "guestfs_wait_ready" in guestfs(3). You had to call
2195 this function after launch in versions ≤ 1.0.70, but it is now an
2196 (almost) no-op.
2197 Function "lib/launch.c:guestfs_int_create_socketname"
2199 int
2201 guestfs_int_create_socketname (guestfs_h *g, const char *filename,
2202 char (*sockpath)[UNIX_PATH_MAX])
2203 Create the path for a socket with the selected filename in the tmpdir.
2205 Function "lib/launch.c:guestfs_int_register_backend"
2207 void
2209 guestfs_int_register_backend (const char *name, const struct backend_ops *ops)
2210 When the library is loaded, each backend calls this function to
2212 register itself in a global list.
2213 Function "lib/launch.c:guestfs_int_set_backend"
2215 int
2217 guestfs_int_set_backend (guestfs_h *g, const char *method)
2218 Implementation of "guestfs_set_backend" in guestfs(3).
2220 · Callers must ensure this is only called in the config state.
2222 · This shouldn't call "error" since it may be called early in handle
2224 initialization. It can return an error code however.
2225 File lib/private-data.c
2227 Implement a private data area where libguestfs C API users can attach
2229 arbitrary pieces of data to a "guestfs_h" handle.
2230 For more information see "PRIVATE DATA AREA" in guestfs(3).
2232 Language bindings do not generally expose this, largely because in non-
2234 C languages it is easy to associate data with handles in other ways
2235 (using hash tables or maps).
2236 Structure "lib/private-data.c:pda_entry"
2238 struct pda_entry {
2240 char *key; /* key */
2241 void *data; /* opaque user data pointer */
2242 };
2243 The private data area is internally stored as a gnulib hash table
2245 containing "pda_entry" structures.
2246 Note the private data area is allocated lazily, since the vast majority
2248 of callers will never use it. This means "g->pda" is likely to be
2249 "NULL".
2250 File lib/proto.c
2252 This is the code used to send and receive RPC messages and (for certain
2254 types of message) to perform file transfers. This code is driven from
2255 the generated actions (lib/actions-*.c). There are five different
2256 cases to consider:
2257 1. A non-daemon function (eg. "guestfs_set_verbose" in guestfs(3)).
2259 There is no RPC involved at all, it's all handled inside the
2260 library.
2261 2. A simple RPC (eg. "guestfs_mount" in guestfs(3)). We write the
2263 request, then read the reply. The sequence of calls is:
2264 guestfs_int_send
2266 guestfs_int_recv
2267 3. An RPC with "FileIn" parameters (eg. "guestfs_upload" in
2269 guestfs(3)). We write the request, then write the file(s), then
2270 read the reply. The sequence of calls is:
2271 guestfs_int_send
2273 guestfs_int_send_file (possibly multiple times)
2274 guestfs_int_recv
2275 4. An RPC with "FileOut" parameters (eg. "guestfs_download" in
2277 guestfs(3)). We write the request, then read the reply, then read
2278 the file(s). The sequence of calls is:
2279 guestfs_int_send
2281 guestfs_int_recv
2282 guestfs_int_recv_file (possibly multiple times)
2283 5. Both "FileIn" and "FileOut" parameters. There are no calls like
2285 this in the current API, but they would be implemented as a
2286 combination of cases 3 and 4.
2287 All read/write/etc operations are performed using the current
2289 connection module ("g->conn"). During operations the connection module
2290 transparently handles log messages that appear on the console.
2291 Function "lib/proto.c:child_cleanup"
2293 static void
2295 child_cleanup (guestfs_h *g)
2296 This is called if we detect EOF, ie. qemu died.
2298 Function "lib/proto.c:guestfs_int_progress_message_callback"
2300 void
2302 guestfs_int_progress_message_callback (guestfs_h *g,
2303 const guestfs_progress *message)
2304 Convenient wrapper to generate a progress message callback.
2306 Function "lib/proto.c:guestfs_int_log_message_callback"
2308 void
2310 guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)
2311 Connection modules call us back here when they get a log message.
2313 Function "lib/proto.c:check_daemon_socket"
2315 static ssize_t
2317 check_daemon_socket (guestfs_h *g)
2318 Before writing to the daemon socket, check the read side of the daemon
2320 socket for any of these conditions:
2321 error
2323 return -1
2324 daemon cancellation message
2326 return -2
2327 progress message
2329 handle it here
2330 end of input or appliance exited unexpectedly
2332 return 0
2333 anything else
2335 return 1
2336 Function "lib/proto.c:guestfs_int_send_file"
2338 int
2340 guestfs_int_send_file (guestfs_h *g, const char *filename)
2341 Send a file.
2343 Returns 0 on success, "-1" for error, "-2" if the daemon cancelled (we
2345 must read the error message).
2346 Function "lib/proto.c:send_file_data"
2348 static int
2350 send_file_data (guestfs_h *g, const char *buf, size_t len)
2351 Send a chunk of file data.
2353 Function "lib/proto.c:send_file_cancellation"
2355 static int
2357 send_file_cancellation (guestfs_h *g)
2358 Send a cancellation message.
2360 Function "lib/proto.c:send_file_complete"
2362 static int
2364 send_file_complete (guestfs_h *g)
2365 Send a file complete chunk.
2367 Function "lib/proto.c:recv_from_daemon"
2369 static int
2371 recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)
2372 This function reads a single message, file chunk, launch flag or
2374 cancellation flag from the daemon. If something was read, it returns
2375 0, otherwise "-1".
2376 Both "size_rtn" and "buf_rtn" must be passed by the caller as non-NULL.
2378 *size_rtn returns the size of the returned message or it may be
2380 "GUESTFS_LAUNCH_FLAG" or "GUESTFS_CANCEL_FLAG".
2381 *buf_rtn is returned containing the message (if any) or will be set to
2383 "NULL". *buf_rtn must be freed by the caller.
2384 This checks for EOF (appliance died) and passes that up through the
2386 child_cleanup function above.
2387 Log message, progress messages are handled transparently here.
2389 Function "lib/proto.c:guestfs_int_recv"
2391 int
2393 guestfs_int_recv (guestfs_h *g, const char *fn,
2394 guestfs_message_header *hdr,
2395 guestfs_message_error *err,
2396 xdrproc_t xdrp, char *ret)
2397 Receive a reply.
2399 Function "lib/proto.c:guestfs_int_recv_discard"
2401 int
2403 guestfs_int_recv_discard (guestfs_h *g, const char *fn)
2404 Same as "guestfs_int_recv", but it discards the reply message.
2406 Notes (XXX):
2408 · This returns an int, but all current callers ignore it.
2410 · The error string may end up being set twice on error paths.
2412 Function "lib/proto.c:guestfs_int_recv_file"
2414 int
2416 guestfs_int_recv_file (guestfs_h *g, const char *filename)
2417 Returns "-1" = error, 0 = EOF, ">0" = more data
2419 Function "lib/proto.c:receive_file_data"
2421 static ssize_t
2423 receive_file_data (guestfs_h *g, void **buf_r)
2424 Receive a chunk of file data.
2426 Returns "-1" = error, 0 = EOF, ">0" = more data
2428 File lib/qemu.c
2430 Functions to handle qemu versions and features.
2432 Function "lib/qemu.c:guestfs_int_test_qemu"
2434 struct qemu_data *
2436 guestfs_int_test_qemu (guestfs_h *g)
2437 Test that the qemu binary (or wrapper) runs, and do "qemu -help" and
2439 other commands so we can find out the version of qemu and what options
2440 this qemu supports.
2441 This caches the results in the cachedir so that as long as the qemu
2443 binary does not change, calling this is effectively free.
2444 Function "lib/qemu.c:cache_filename"
2446 static char *
2448 cache_filename (guestfs_h *g, const char *cachedir,
2449 const struct stat *statbuf, const char *suffix)
2450 Generate the filenames, for the stat file and the other cache files.
2452 By including the size and mtime in the filename we also ensure that the
2454 same user can use multiple versions of qemu without conflicts.
2455 Function "lib/qemu.c:parse_qemu_version"
2457 static void
2459 parse_qemu_version (guestfs_h *g, const char *qemu_help,
2460 struct version *qemu_version)
2461 Parse the first line of "qemu_help" into the major and minor version of
2463 qemu, but don't fail if parsing is not possible.
2464 Function "lib/qemu.c:parse_json"
2466 static void
2468 parse_json (guestfs_h *g, const char *json, json_t **treep)
2469 Parse the json output from QMP. But don't fail if parsing is not
2471 possible.
2472 Function "lib/qemu.c:parse_has_kvm"
2474 static void
2476 parse_has_kvm (guestfs_h *g, const char *json, bool *ret)
2477 Parse the json output from QMP query-kvm to find out if KVM is enabled
2479 on this machine. Don't fail if parsing is not possible, assume KVM is
2480 available.
2481 The JSON output looks like: {"return": {"enabled": true, "present":
2483 true}}
2484 Function "lib/qemu.c:generic_read_cache"
2486 static int
2488 generic_read_cache (guestfs_h *g, const char *filename, char **strp)
2489 Generic functions for reading and writing the cache files, used where
2491 we are just reading and writing plain text strings.
2492 Function "lib/qemu.c:generic_qmp_test"
2494 static int
2496 generic_qmp_test (guestfs_h *g, struct qemu_data *data,
2497 const char *qmp_command,
2498 char **outp)
2499 Run a generic QMP test on the QEMU binary.
2501 Function "lib/qemu.c:guestfs_int_qemu_version"
2503 struct version
2505 guestfs_int_qemu_version (guestfs_h *g, struct qemu_data *data)
2506 Return the parsed version of qemu.
2508 Function "lib/qemu.c:guestfs_int_qemu_supports"
2510 int
2512 guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data,
2513 const char *option)
2514 Test if option is supported by qemu command line (just by grepping the
2516 help text).
2517 Function "lib/qemu.c:guestfs_int_qemu_supports_device"
2519 int
2521 guestfs_int_qemu_supports_device (guestfs_h *g,
2522 const struct qemu_data *data,
2523 const char *device_name)
2524 Test if device is supported by qemu (currently just greps the "qemu
2526 -device ?" output).
2527 Function "lib/qemu.c:guestfs_int_qemu_mandatory_locking"
2529 int
2531 guestfs_int_qemu_mandatory_locking (guestfs_h *g,
2532 const struct qemu_data *data)
2533 Test if the qemu binary uses mandatory file locking, added in QEMU >=
2535 2.10 (but sometimes disabled).
2536 Function "lib/qemu.c:guestfs_int_qemu_escape_param"
2538 char *
2540 guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)
2541 Escape a qemu parameter.
2543 Every "," becomes ",,". The caller must free the returned string.
2545 XXX This functionality is now only used when constructing a qemu-img
2547 command in lib/create.c. We should extend the qemuopts library to
2548 cover this use case.
2549 Function "lib/qemu.c:guestfs_int_drive_source_qemu_param"
2551 char *
2553 guestfs_int_drive_source_qemu_param (guestfs_h *g,
2554 const struct drive_source *src)
2555 Useful function to format a drive + protocol for qemu.
2557 Note that the qemu parameter is the bit after "file=". It is not
2559 escaped here, but would usually be escaped if passed to qemu as part of
2560 a full -drive parameter (but not for qemu-img(1)).
2561 Function "lib/qemu.c:guestfs_int_discard_possible"
2563 bool
2565 guestfs_int_discard_possible (guestfs_h *g, struct drive *drv,
2566 const struct version *qemu_version)
2567 Test if discard is both supported by qemu AND possible with the
2569 underlying file or device. This returns 1 if discard is possible. It
2570 returns 0 if not possible and sets the error to the reason why.
2571 This function is called when the user set "discard == "enable"".
2573 Function "lib/qemu.c:guestfs_int_free_qemu_data"
2575 void
2577 guestfs_int_free_qemu_data (struct qemu_data *data)
2578 Free the "struct qemu_data".
2580 File lib/rescue.c
2582 Support for virt-rescue(1).
2584 File lib/stringsbuf.c
2586 An expandable NULL-terminated vector of strings (like "argv").
2588 Use the "DECLARE_STRINGSBUF" macro to declare the stringsbuf.
2590 Note: Don't confuse this with stringsbuf in the daemon which is a
2592 different type with different methods.
2593 Function "lib/stringsbuf.c:guestfs_int_add_string_nodup"
2595 void
2597 guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)
2598 Add a string to the end of the list.
2600 This doesn't call strdup(3) on the string, so the string itself is
2602 stored inside the vector.
2603 Function "lib/stringsbuf.c:guestfs_int_add_string"
2605 void
2607 guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)
2608 Add a string to the end of the list.
2610 This makes a copy of the string.
2612 Function "lib/stringsbuf.c:guestfs_int_add_sprintf"
2614 void
2616 guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
2617 const char *fs, ...)
2618 Add a string to the end of the list.
2620 Uses an sprintf-like format string when creating the string.
2622 Function "lib/stringsbuf.c:guestfs_int_end_stringsbuf"
2624 void
2626 guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)
2627 Finish the string buffer.
2629 This adds the terminating NULL to the end of the vector.
2631 Function "lib/stringsbuf.c:guestfs_int_free_stringsbuf"
2633 void
2635 guestfs_int_free_stringsbuf (struct stringsbuf *sb)
2636 Free the string buffer and the strings.
2638 File lib/tmpdirs.c
2640 Handle temporary directories.
2642 Function "lib/tmpdirs.c:set_abs_path"
2644 static int
2646 set_abs_path (guestfs_h *g, const char *ctxstr,
2647 const char *tmpdir, char **tmpdir_ret)
2648 We need to make all tmpdir paths absolute because lots of places in the
2650 code assume this. Do it at the time we set the path or read the
2651 environment variable (https://bugzilla.redhat.com/882417).
2652 The "ctxstr" parameter is a string displayed in error messages giving
2654 the context of the operation (eg. name of environment variable being
2655 used, or API function being called).
2656 Function "lib/tmpdirs.c:guestfs_impl_get_tmpdir"
2658 char *
2660 guestfs_impl_get_tmpdir (guestfs_h *g)
2661 Implements the "guestfs_get_tmpdir" API.
2663 Note this actually calculates the tmpdir, so it never returns "NULL".
2665 Function "lib/tmpdirs.c:guestfs_impl_get_cachedir"
2667 char *
2669 guestfs_impl_get_cachedir (guestfs_h *g)
2670 Implements the "guestfs_get_cachedir" API.
2672 Note this actually calculates the cachedir, so it never returns "NULL".
2674 Function "lib/tmpdirs.c:guestfs_impl_get_sockdir"
2676 char *
2678 guestfs_impl_get_sockdir (guestfs_h *g)
2679 Implements the "guestfs_get_sockdir" API.
2681 Note this actually calculates the sockdir, so it never returns "NULL".
2683 Function "lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir"
2685 int
2687 guestfs_int_lazy_make_tmpdir (guestfs_h *g)
2688 The "g->tmpdir" (per-handle temporary directory) is not created when
2690 the handle is created. Instead we create it lazily before the first
2691 time it is used, or during launch.
2692 Function "lib/tmpdirs.c:guestfs_int_make_temp_path"
2694 char *
2696 guestfs_int_make_temp_path (guestfs_h *g,
2697 const char *name, const char *extension)
2698 Generate unique temporary paths for temporary files.
2700 Returns a unique path or NULL on error.
2702 Function "lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir"
2704 char *
2706 guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)
2707 Create the supermin appliance directory under cachedir, if it does not
2709 exist.
2710 Sanity-check that the permissions on the cachedir are safe, in case it
2712 has been pre-created maliciously or tampered with.
2713 Returns the directory name which the caller must free.
2715 Function "lib/tmpdirs.c:guestfs_int_recursive_remove_dir"
2717 void
2719 guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)
2720 Recursively remove a temporary directory. If removal fails, just
2722 return (it's a temporary directory so it'll eventually be cleaned up by
2723 a temp cleaner).
2724 This is implemented using "rm -rf" because that's simpler and safer.
2726 File lib/umask.c
2728 Return current umask in a thread-safe way.
2730 glibc documents, but does not actually implement, a "getumask(3)" call.
2732 We use "Umask" from /proc/self/status for Linux ≥ 4.7. For older Linux
2734 and other Unix, this file implements an expensive but thread-safe way
2735 to get the current process's umask.
2736 Thanks to: Josh Stone, Jiri Jaburek, Eric Blake.
2738 Function "lib/umask.c:guestfs_int_getumask"
2740 int
2742 guestfs_int_getumask (guestfs_h *g)
2743 Returns the current process's umask. On failure, returns "-1" and sets
2745 the error in the guestfs handle.
2746 Function "lib/umask.c:get_umask_from_proc"
2748 static int
2750 get_umask_from_proc (guestfs_h *g)
2751 For Linux ≥ 4.7 get the umask from /proc/self/status.
2753 On failure this returns "-1". However if we could not open the /proc
2755 file or find the "Umask" entry in it, return "-2" which causes the
2756 fallback path to run.
2757 Function "lib/umask.c:get_umask_from_fork"
2759 static int
2761 get_umask_from_fork (guestfs_h *g)
2762 Fallback method of getting the umask using fork.
2764 File lib/unit-tests.c
2766 Unit tests of internal functions.
2768 These tests may use a libguestfs handle, but must not launch the
2770 handle. Also, avoid long-running tests.
2771 Function "lib/unit-tests.c:test_split"
2773 static void
2775 test_split (void)
2776 Test "guestfs_int_split_string".
2778 Function "lib/unit-tests.c:test_concat"
2780 static void
2782 test_concat (void)
2783 Test "guestfs_int_concat_strings".
2785 Function "lib/unit-tests.c:test_join"
2787 static void
2789 test_join (void)
2790 Test "guestfs_int_join_strings".
2792 Function "lib/unit-tests.c:test_validate_guid"
2794 static void
2796 test_validate_guid (void)
2797 Test "guestfs_int_validate_guid".
2799 Function "lib/unit-tests.c:test_drive_name"
2801 static void
2803 test_drive_name (void)
2804 Test "guestfs_int_drive_name".
2806 Function "lib/unit-tests.c:test_drive_index"
2808 static void
2810 test_drive_index (void)
2811 Test "guestfs_int_drive_index".
2813 Function "lib/unit-tests.c:test_getumask"
2815 static void
2817 test_getumask (void)
2818 Test "guestfs_int_getumask".
2820 Function "lib/unit-tests.c:test_command"
2822 static void
2824 test_command (void)
2825 Test "guestfs_int_new_command" etc.
2827 XXX These tests could be made much more thorough. So far we simply
2829 test that it's not obviously broken.
2830 Function "lib/unit-tests.c:test_qemu_escape_param"
2832 static void
2834 test_qemu_escape_param (void)
2835 Test "guestfs_int_qemu_escape_param"
2837 XXX I wanted to make this test run qemu, passing some parameters which
2839 need to be escaped, but I cannot think of a way to do that without
2840 launching a VM.
2841 Function "lib/unit-tests.c:test_timeval_diff"
2843 static void
2845 test_timeval_diff (void)
2846 Test "guestfs_int_timeval_diff".
2848 File lib/version.c
2850 This file provides simple version number management.
2852 Function "lib/version.c:guestfs_int_version_from_x_y"
2854 int
2856 guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)
2857 Parses a version from a string, looking for a "X.Y" pattern.
2859 Returns "-1" on failure (like failed integer parsing), 0 on missing
2861 match, and 1 on match and successful parsing. "v" is changed only on
2862 successful match.
2863 Function "lib/version.c:guestfs_int_version_from_x_y_re"
2865 int
2867 guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
2868 const char *str, const pcre *re)
2869 Parses a version from a string, using the specified "re" as regular
2871 expression which must provide (at least) two matches.
2872 Returns "-1" on failure (like failed integer parsing), 0 on missing
2874 match, and 1 on match and successful parsing. "v" is changed only on
2875 successful match.
2876 Function "lib/version.c:guestfs_int_version_from_x_y_or_x"
2878 int
2880 guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
2881 const char *str)
2882 Parses a version from a string, either looking for a "X.Y" pattern or
2884 considering it as whole integer.
2885 Returns "-1" on failure (like failed integer parsing), 0 on missing
2887 match, and 1 on match and successful parsing. "v" is changed only on
2888 successful match.
2889 Function "lib/version.c:guestfs_int_parse_unsigned_int"
2891 int
2893 guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)
2894 Parse small, unsigned ints, as used in version numbers.
2896 This will fail with an error if trailing characters are found after the
2898 integer.
2899 Returns ≥ 0 on success, or "-1" on failure.
2901 File lib/wait.c
2903 Function "lib/wait.c:guestfs_int_waitpid"
2905 int
2907 guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)
2908 A safe version of waitpid(3) which retries if "EINTR" is returned.
2910 Note: this only needs to be used in the library, or in programs that
2912 install a non-restartable "SIGCHLD" handler (which is not the case for
2913 any current libguestfs virt tools).
2914 If the main program installs a SIGCHLD handler and sets it to be non-
2916 restartable, then what can happen is the library is waiting in a wait
2917 syscall, the child exits, "SIGCHLD" is sent to the process, and the
2918 wait syscall returns "EINTR". Since the library cannot control the
2919 signal handler, we have to instead restart the wait syscall, which is
2920 the purpose of this wrapper.
2921 Function "lib/wait.c:guestfs_int_waitpid_noerror"
2923 void
2925 guestfs_int_waitpid_noerror (pid_t pid)
2926 Like "guestfs_int_waitpid", but ignore errors.
2928 Function "lib/wait.c:guestfs_int_wait4"
2930 int
2932 guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
2933 struct rusage *rusage, const char *errmsg)
2934 A safe version of wait4(2) which retries if "EINTR" is returned.
2936 File lib/whole-file.c
2938 Function "lib/whole-file.c:guestfs_int_read_whole_file"
2940 int
2942 guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
2943 char **data_r, size_t *size_r)
2944 Read the whole file "filename" into a memory buffer.
2946 The memory buffer is initialized and returned in "data_r". The size of
2948 the file in bytes is returned in "size_r". The return buffer must be
2949 freed by the caller.
2950 On error this sets the error in the handle and returns "-1".
2952 For the convenience of callers, the returned buffer is NUL-terminated
2954 (the NUL is not included in the size).
2955 The file must be a regular, local, trusted file. In particular, do not
2957 use this function to read files that might be under control of an
2958 untrusted user since that will lead to a denial-of-service attack.
2959 Subdirectory builder
2961 File builder/index-parser-c.c
2962 This file handles the interface between the C/lex/yacc index file
2964 parser, and the OCaml world. See builder/index_parser.ml for the OCaml
2965 type definition.
2966 Subdirectory common/edit
2968 File common/edit/file-edit.c
2969 This file implements common file editing in a range of utilities
2971 including guestfish(1), virt-edit(1), virt-customize(1) and
2972 virt-builder(1).
2973 It contains the code for both interactive-(editor-)based editing and
2975 non-interactive editing using Perl snippets.
2976 Function "common/edit/file-edit.c:edit_file_editor"
2978 int
2980 edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
2981 const char *backup_extension, int verbose)
2982 Edit "filename" using the specified "editor" application.
2984 If "backup_extension" is not null, then a copy of "filename" is saved
2986 with "backup_extension" appended to its file name.
2987 If "editor" is null, then the $EDITOR environment variable will be
2989 queried for the editor application, leaving "vi" as fallback if not
2990 set.
2991 Returns "-1" for failure, 0 on success, 1 if the editor did not change
2993 the file (e.g. the user closed the editor without saving).
2994 Function "common/edit/file-edit.c:edit_file_perl"
2996 int
2998 edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
2999 const char *backup_extension, int verbose)
3000 Edit "filename" running the specified "perl_expr" using Perl.
3002 If "backup_extension" is not null, then a copy of "filename" is saved
3004 with "backup_extension" appended to its file name.
3005 Returns "-1" for failure, 0 on success.
3007 Subdirectory common/mlxml
3009 File common/mlxml/xml-c.c
3010 Mini interface to libxml2.
3012 Subdirectory common/options
3014 File common/options/config.c
3015 This file parses the guestfish configuration file, usually
3017 ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.
3018 Note that "parse_config" is called very early, before command line
3020 parsing, before the "verbose" flag has been set, even before the global
3021 handle "g" is opened.
3022 File common/options/decrypt.c
3024 This file implements the decryption of disk images, usually done before
3026 mounting their partitions.
3027 Function "common/options/decrypt.c:make_mapname"
3029 static void
3031 make_mapname (const char *device, char *mapname, size_t len)
3032 Make a LUKS map name from the partition name, eg. "/dev/vda2" =>
3034 "cryptvda2"
3035 Function "common/options/decrypt.c:inspect_do_decrypt"
3037 void
3039 inspect_do_decrypt (guestfs_h *g, struct key_store *ks)
3040 Simple implementation of decryption: look for any encrypted partitions
3042 and decrypt them, then rescan for VGs.
3043 File common/options/display-options.c
3045 This file contains common code used to implement --short-options and
3047 --long-options in C virt tools. (The equivalent for OCaml virt tools
3048 is implemented by common/mltools/getopt.ml).
3049 These "hidden" options are used to implement bash tab completion.
3051 Function "common/options/display-options.c:display_short_options"
3053 void
3055 display_short_options (const char *format)
3056 Implements the internal "tool --short-options" flag, which just lists
3058 out the short options available. Used by bash completion.
3059 Function "common/options/display-options.c:display_long_options"
3061 void
3063 display_long_options (const struct option *long_options)
3064 Implements the internal "tool --long-options" flag, which just lists
3066 out the long options available. Used by bash completion.
3067 File common/options/domain.c
3069 Implements the guestfish (and other tools) -d option.
3071 Function "common/options/domain.c:add_libvirt_drives"
3073 int
3075 add_libvirt_drives (guestfs_h *g, const char *guest)
3076 This function is called when a user invokes "guestfish -d guest".
3078 Returns the number of drives added ("> 0"), or "-1" for failure.
3080 File common/options/inspect.c
3082 This file implements inspecting the guest and mounting the filesystems
3084 found in the right places. It is used by the guestfish(1) -i option
3085 and some utilities such as virt-cat(1).
3086 Function "common/options/inspect.c:inspect_mount_handle"
3088 void
3090 inspect_mount_handle (guestfs_h *g, struct key_store *ks)
3091 This function implements the -i option.
3093 Function "common/options/inspect.c:print_inspect_prompt"
3095 void
3097 print_inspect_prompt (void)
3098 This function is called only if "inspect_mount_root" was called, and
3100 only after we've printed the prompt in interactive mode.
3101 File common/options/keys.c
3103 Function "common/options/keys.c:read_key"
3105 char *
3107 read_key (const char *param)
3108 Read a passphrase ('Key') from /dev/tty with echo off.
3110 The caller (fish/cmds.c) will call free on the string afterwards.
3112 Based on the code in cryptsetup file lib/utils.c.
3113 File common/options/options.c
3115 This file contains common options parsing code used by guestfish and
3117 many other tools which share a common options syntax.
3118 For example, guestfish, virt-cat, virt-ls etc all support the -a
3120 option, and that is handled in all of those tools using a macro
3121 "OPTION_a" defined in fish/options.h.
3122 There are a lot of common global variables used, "drvs" accumulates the
3124 list of drives, "verbose" for the -v flag, and many more.
3125 Function "common/options/options.c:option_a"
3127 void
3129 option_a (const char *arg, const char *format, int blocksize,
3130 struct drv **drvsp)
3131 Handle the guestfish -a option on the command line.
3133 Function "common/options/options.c:option_d"
3135 void
3137 option_d (const char *arg, struct drv **drvsp)
3138 Handle the -d option when passed on the command line.
3140 Function "common/options/options.c:display_mountpoints_on_failure"
3142 static void
3144 display_mountpoints_on_failure (const char *mp_device,
3145 const char *user_supplied_options)
3146 If the -m option fails on any command, display a useful error message
3148 listing the mountpoints.
3149 File common/options/uri.c
3151 This file implements URI parsing for the -a option, in many utilities
3153 including guestfish(1), virt-cat(1), virt-builder(1),
3154 virt-customize(1), etc.
3155 Subdirectory common/parallel
3157 File common/parallel/domains.c
3158 This file is used by "virt-df" and some of the other tools when they
3160 are implicitly asked to operate over all libvirt domains (VMs), for
3161 example when "virt-df" is called without specifying any particular disk
3162 image.
3163 It hides the complexity of querying the list of domains from libvirt.
3165 Function "common/parallel/domains.c:free_domains"
3167 void
3169 free_domains (void)
3170 Frees up everything allocated by "get_all_libvirt_domains".
3172 Function "common/parallel/domains.c:get_all_libvirt_domains"
3174 void
3176 get_all_libvirt_domains (const char *libvirt_uri)
3177 Read all libguest guests into the global variables "domains" and
3179 "nr_domains". The guests are ordered by name. This exits on any
3180 error.
3181 File common/parallel/estimate-max-threads.c
3183 Function "common/parallel/estimate-max-threads.c:estimate_max_threads"
3185 size_t
3187 estimate_max_threads (void)
3188 This function uses the output of "free -m" to estimate how many
3190 libguestfs appliances could be safely started in parallel. Note that
3191 it always returns ≥ 1.
3192 Function "common/parallel/estimate-max-threads.c:read_line_from"
3194 static char *
3196 read_line_from (const char *cmd)
3197 Run external command and read the first line of output.
3199 File common/parallel/parallel.c
3201 This file is used by "virt-df" and some of the other tools when they
3203 need to run multiple parallel libguestfs instances to operate on a
3204 large number of libvirt domains efficiently.
3205 It implements a multithreaded work queue. In addition it reorders the
3207 output so the output still appears in the same order as the input (ie.
3208 still ordered alphabetically).
3209 Function "common/parallel/parallel.c:start_threads"
3211 int
3213 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
3214 Run the threads and work through the global list of libvirt domains.
3216 "option_P" is whatever the user passed in the -P option, or 0 if the
3218 user didn't use the -P option (in which case the number of threads is
3219 chosen heuristically).
3220 "options_handle" (which may be "NULL") is the global guestfs handle
3222 created by the options mini-library.
3223 The work function ("work") should do the work (inspecting the domain,
3225 etc.) on domain index "i". However it must not print out any result
3226 directly. Instead it prints anything it needs to the supplied "FILE
3227 *". The work function should return 0 on success or "-1" on error.
3228 The "start_threads" function returns 0 if all work items completed
3230 successfully, or "-1" if there was an error.
3231 Subdirectory common/progress
3233 File common/progress/progress.c
3234 This file implements the progress bar in guestfish(1), virt-resize(1)
3236 and virt-sparsify(1).
3237 Function "common/progress/progress.c:progress_bar_init"
3239 struct progress_bar *
3241 progress_bar_init (unsigned flags)
3242 Initialize a progress bar struct.
3244 It is intended that you can reuse the same struct for multiple commands
3246 (but only in a single thread). Call "progress_bar_reset" before each
3247 new command.
3248 Function "common/progress/progress.c:progress_bar_free"
3250 void
3252 progress_bar_free (struct progress_bar *bar)
3253 Free a progress bar struct.
3255 Function "common/progress/progress.c:progress_bar_reset"
3257 void
3259 progress_bar_reset (struct progress_bar *bar)
3260 This function should be called just before you issue any command.
3262 Function "common/progress/progress.c:estimate_remaining_time"
3264 static double
3266 estimate_remaining_time (struct progress_bar *bar, double ratio)
3267 Return remaining time estimate (in seconds) for current call.
3269 This returns the running mean estimate of remaining time, but if the
3271 latest estimate of total time is greater than two s.d.'s from the
3272 running mean then we don't print anything because we're not confident
3273 that the estimate is meaningful. (Returned value is <0.0 when nothing
3274 should be printed).
3275 Function "common/progress/progress.c:progress_bar_set"
3277 void
3279 progress_bar_set (struct progress_bar *bar,
3280 uint64_t position, uint64_t total)
3281 Set the position of the progress bar.
3283 This should be called from a "GUESTFS_EVENT_PROGRESS" event callback.
3285 Subdirectory common/qemuopts
3287 File common/qemuopts/qemuopts-tests.c
3288 Unit tests of internal functions.
3290 These tests may use a libguestfs handle, but must not launch the
3292 handle. Also, avoid long-running tests.
3293 File common/qemuopts/qemuopts.c
3295 Mini-library for writing qemu command lines and qemu config files.
3297 There are some shortcomings with the model used for qemu options which
3299 aren't clear until you try to convert options into a configuration
3300 file. However if we attempted to model the options in more detail then
3301 this library would be both very difficult to use and incompatible with
3302 older versions of qemu. Hopefully the current model is a decent
3303 compromise.
3304 For reference here are the problems:
3306 · There's inconsistency in qemu between options and config file, eg.
3308 "-smp 4" becomes:
3309 [smp-opts]
3311 cpus = "4"
3312 · Similar to the previous point, you can write either "-smp 4" or
3314 "-smp cpus=4" (although this won't work in very old qemu). When
3315 generating a config file you need to know the implicit key name.
3316 · In "-opt key=value,..." the "key" is really a tree/array specifier.
3318 The way this works is complicated but hinted at here:
3319 http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
3320 · Some options are syntactic sugar. eg. "-kernel foo" is sugar for
3322 "-machine kernel=foo".
3323 Function "common/qemuopts/qemuopts.c:qemuopts_create"
3325 struct qemuopts *
3327 qemuopts_create (void)
3328 Create an empty list of qemu options.
3330 The caller must eventually free the list by calling "qemuopts_free".
3332 Returns "NULL" on error, setting "errno".
3334 Function "common/qemuopts/qemuopts.c:qemuopts_free"
3336 void
3338 qemuopts_free (struct qemuopts *qopts)
3339 Free the list of qemu options.
3341 Function "common/qemuopts/qemuopts.c:qemuopts_add_flag"
3343 int
3345 qemuopts_add_flag (struct qemuopts *qopts, const char *flag)
3346 Add a command line flag which has no argument. eg:
3348 qemuopts_add_flag (qopts, "-no-user-config");
3350 Returns 0 on success. Returns "-1" on error, setting "errno".
3352 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg"
3354 int
3356 qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)
3357 Add a command line flag which has a single argument. eg:
3359 qemuopts_add_arg (qopts, "-m", "1024");
3361 Don't use this if the argument is a comma-separated list, since quoting
3363 will not be done properly. See "qemuopts_add_arg_list".
3364 Returns 0 on success. Returns "-1" on error, setting "errno".
3366 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_format"
3368 int
3370 qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
3371 const char *fs, ...)
3372 Add a command line flag which has a single formatted argument. eg:
3374 qemuopts_add_arg_format (qopts, "-m", "%d", 1024);
3376 Don't use this if the argument is a comma-separated list, since quoting
3378 will not be done properly. See "qemuopts_add_arg_list".
3379 Returns 0 on success. Returns "-1" on error, setting "errno".
3381 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote"
3383 int
3385 qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
3386 const char *value)
3387 This is like "qemuopts_add_arg" except that no quoting is done on the
3389 value.
3390 For "qemuopts_to_script" and "qemuopts_to_channel", this means that
3392 neither shell quoting nor qemu comma quoting is done on the value.
3393 For "qemuopts_to_argv" this means that qemu comma quoting is not done.
3395 "qemuopts_to_config*" will fail.
3397 You should use this with great care.
3399 Function "common/qemuopts/qemuopts.c:qemuopts_start_arg_list"
3401 int
3403 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
3404 Start an argument that takes a comma-separated list of fields.
3406 Typical usage is like this (with error handling omitted):
3408 qemuopts_start_arg_list (qopts, "-drive");
3410 qemuopts_append_arg_list (qopts, "file=foo");
3411 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
3412 qemuopts_end_arg_list (qopts);
3413 which would construct "-drive file=foo,if=ide"
3415 See also "qemuopts_add_arg_list" for a way to do simple cases in one
3417 call.
3418 Returns 0 on success. Returns "-1" on error, setting "errno".
3420 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_list"
3422 int
3424 qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
3425 const char *elem0, ...)
3426 Add a command line flag which has a list of arguments. eg:
3428 qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);
3430 This is turned into a comma-separated list, like: "-drive
3432 file=foo,if=ide". Note that this handles qemu quoting properly, so
3433 individual elements may contain commas and this will do the right
3434 thing.
3435 Returns 0 on success. Returns "-1" on error, setting "errno".
3437 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary"
3439 int
3441 qemuopts_set_binary (struct qemuopts *qopts, const char *binary)
3442 Set the qemu binary name.
3444 Returns 0 on success. Returns "-1" on error, setting "errno".
3446 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch"
3448 int
3450 qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)
3451 Set the qemu binary name to "qemu-system-[arch]".
3453 As a special case if "arch" is "NULL", the binary is set to the KVM
3455 binary for the current host architecture:
3456 qemuopts_set_binary_by_arch (qopts, NULL);
3458 Returns 0 on success. Returns "-1" on error, setting "errno".
3460 Function "common/qemuopts/qemuopts.c:qemuopts_to_script"
3462 int
3464 qemuopts_to_script (struct qemuopts *qopts, const char *filename)
3465 Write the qemu options to a script.
3467 "qemuopts_set_binary*" must be called first.
3469 The script file will start with "#!/bin/sh" and will be chmod to mode
3471 0755.
3472 Returns 0 on success. Returns "-1" on error, setting "errno".
3474 Function "common/qemuopts/qemuopts.c:shell_quote"
3476 static void
3478 shell_quote (const char *str, FILE *fp)
3479 Print "str" to "fp", shell-quoting it if necessary.
3481 Function "common/qemuopts/qemuopts.c:shell_and_comma_quote"
3483 static void
3485 shell_and_comma_quote (const char *str, FILE *fp)
3486 Print "str" to "fp" doing both shell and qemu comma quoting.
3488 Function "common/qemuopts/qemuopts.c:qemuopts_to_channel"
3490 int
3492 qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)
3493 Write the qemu options to a "FILE *fp".
3495 "qemuopts_set_binary*" must be called first.
3497 Only the qemu command line is written. The caller may need to add
3499 "#!/bin/sh" and may need to chmod the resulting file to 0755.
3500 Returns 0 on success. Returns "-1" on error, setting "errno".
3502 Function "common/qemuopts/qemuopts.c:qemuopts_to_argv"
3504 char **
3506 qemuopts_to_argv (struct qemuopts *qopts)
3507 Return a NULL-terminated argument list, of the kind that can be passed
3509 directly to execv(3).
3510 "qemuopts_set_binary*" must be called first. It will be returned as
3512 "argv[0]" in the returned list.
3513 The list of strings and the strings themselves must be freed by the
3515 caller.
3516 Returns "NULL" on error, setting "errno".
3518 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_file"
3520 int
3522 qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)
3523 Write the qemu options to a qemu config file, suitable for reading in
3525 using "qemu -readconfig filename".
3526 Note that qemu config files have limitations on content and quoting, so
3528 not all qemuopts structs can be written (this function returns an error
3529 in these cases). For more information see
3530 https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html
3531 https://bugs.launchpad.net/qemu/+bug/1686364
3532 Also, command line argument names and config file sections sometimes
3534 have different names. For example the equivalent of "-m 1024" is:
3535 [memory]
3537 size = "1024"
3538 This code does not attempt to convert between the two forms. You just
3540 need to know how to do that yourself.
3541 Returns 0 on success. Returns "-1" on error, setting "errno".
3543 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_channel"
3545 int
3547 qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)
3548 Same as "qemuopts_to_config_file", but this writes to a "FILE *fp".
3550 Subdirectory common/utils
3552 File common/utils/cleanups.c
3553 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3555 They are implemented using the "__attribute__((cleanup))" feature of
3556 gcc and clang. Typical usage is:
3557 fn ()
3559 {
3560 CLEANUP_FREE char *str = NULL;
3561 str = safe_asprintf (g, "foo");
3562 // str is freed automatically when the function returns
3563 }
3564 There are a few catches to be aware of with the cleanup mechanism:
3566 · If a cleanup variable is not initialized, then you can end up
3568 calling free(3) with an undefined value, resulting in the program
3569 crashing. For this reason, you should usually initialize every
3570 cleanup variable with something, eg. "NULL"
3571 · Don't mark variables holding return values as cleanup variables.
3573 · The "main()" function shouldn't use cleanup variables since it is
3575 normally exited by calling exit(3), and that doesn't call the
3576 cleanup handlers.
3577 The functions in this file are used internally by the "CLEANUP_*"
3579 macros. Don't call them directly.
3580 File common/utils/gnulib-cleanups.c
3582 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3584 They are implemented using the "__attribute__((cleanup))" feature of
3585 gcc and clang. Typical usage is:
3586 fn ()
3588 {
3589 CLEANUP_FREE char *str = NULL;
3590 str = safe_asprintf (g, "foo");
3591 // str is freed automatically when the function returns
3592 }
3593 There are a few catches to be aware of with the cleanup mechanism:
3595 · If a cleanup variable is not initialized, then you can end up
3597 calling free(3) with an undefined value, resulting in the program
3598 crashing. For this reason, you should usually initialize every
3599 cleanup variable with something, eg. "NULL"
3600 · Don't mark variables holding return values as cleanup variables.
3602 · The "main()" function shouldn't use cleanup variables since it is
3604 normally exited by calling exit(3), and that doesn't call the
3605 cleanup handlers.
3606 The functions in this file are used internally by the "CLEANUP_*"
3608 macros. Don't call them directly.
3609 File common/utils/guestfs-utils.h
3611 This header file is included in all "frontend" parts of libguestfs,
3613 namely the library, non-C language bindings, virt tools and tests.
3614 The daemon does not use this header. If you need a place to put
3616 something shared with absolutely everything including the daemon, put
3617 it in lib/guestfs-internal-all.h
3618 If a definition is only needed by a single component of libguestfs (eg.
3620 just the library, or just a single virt tool) then it should not be
3621 here!
3622 File common/utils/libxml2-writer-macros.h
3624 These macros make it easier to write XML. To use them correctly you
3626 must be aware of these assumptions:
3627 · The "xmlTextWriterPtr" is called "xo". It is used implicitly by
3629 all the macros.
3630 · On failure, a function called "xml_error" is called which you must
3632 define (usually as a macro). You must use "CLEANUP_*" macros in
3633 your functions if you want correct cleanup of local variables along
3634 the error path.
3635 · All the "bad" casting is hidden inside the macros.
3637 Definition "common/utils/libxml2-writer-macros.h:start_element"
3639 #define start_element
3641 To define an XML element use:
3643 start_element ("name") {
3645 ...
3646 } end_element ();
3647 which produces "<name>...</name>"
3649 Definition "common/utils/libxml2-writer-macros.h:empty_element"
3651 #define empty_element
3653 To define an empty element:
3655 empty_element ("name");
3657 which produces "<name/>"
3659 Definition "common/utils/libxml2-writer-macros.h:single_element"
3661 #define single_element
3663 To define a single element with no attributes containing some text:
3665 single_element ("name", text);
3667 which produces "<name>text</name>"
3669 Definition "common/utils/libxml2-writer-macros.h:single_element_format"
3671 #define single_element_format
3673 To define a single element with no attributes containing some text
3675 using a format string:
3676 single_element_format ("cores", "%d", nr_cores);
3678 which produces "<cores>4</cores>"
3680 Definition "common/utils/libxml2-writer-macros.h:attribute"
3682 #define attribute
3684 To define an XML element with attributes, use:
3686 start_element ("name") {
3688 attribute ("foo", "bar");
3689 attribute_format ("count", "%d", count);
3690 ...
3691 } end_element ();
3692 which produces "<name foo="bar" count="123">...</name>"
3694 Definition "common/utils/libxml2-writer-macros.h:attribute_ns"
3696 #define attribute_ns
3698 "attribute_ns (prefix, key, namespace_uri, value)" defines a namespaced
3700 attribute.
3701 Definition "common/utils/libxml2-writer-macros.h:string"
3703 #define string
3705 To define a verbatim string, use:
3707 string ("hello");
3709 Definition "common/utils/libxml2-writer-macros.h:string_format"
3711 #define string_format
3713 To define a verbatim string using a format string, use:
3715 string ("%s, world", greeting);
3717 Definition "common/utils/libxml2-writer-macros.h:base64"
3719 #define base64
3721 To write a string encoded as base64:
3723 base64 (data, size);
3725 Definition "common/utils/libxml2-writer-macros.h:comment"
3727 #define comment
3729 To define a comment in the XML, use:
3731 comment ("number of items = %d", nr_items);
3733 File common/utils/stringlists-utils.c
3735 Utility functions used by the library, tools and language bindings.
3737 These functions must not call internal library functions such as
3739 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3740 Function "common/utils/stringlists-utils.c:guestfs_int_split_string"
3742 char **
3744 guestfs_int_split_string (char sep, const char *str)
3745 Split string at separator character "sep", returning the list of
3747 strings. Returns "NULL" on memory allocation failure.
3748 Note (assuming "sep" is ":"):
3750 "str == NULL"
3752 aborts
3753 "str == """
3755 returns "[]"
3756 "str == "abc""
3758 returns "["abc"]"
3759 "str == ":""
3761 returns "["", ""]"
3762 File common/utils/utils.c
3764 Utility functions used by the library, tools and language bindings.
3766 These functions must not call internal library functions such as
3768 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3769 Function "common/utils/utils.c:guestfs_int_replace_string"
3771 char *
3773 guestfs_int_replace_string (const char *str, const char *s1, const char *s2)
3774 Replace every instance of "s1" appearing in "str" with "s2". A newly
3776 allocated string is returned which must be freed by the caller. If
3777 allocation fails this can return "NULL".
3778 For example:
3780 replace_string ("abcabb", "ab", "a");
3782 would return "acab".
3784 Function "common/utils/utils.c:guestfs_int_exit_status_to_string"
3786 char *
3788 guestfs_int_exit_status_to_string (int status, const char *cmd_name,
3789 char *buffer, size_t buflen)
3790 Translate a wait/system exit status into a printable string.
3792 Function "common/utils/utils.c:guestfs_int_random_string"
3794 int
3796 guestfs_int_random_string (char *ret, size_t len)
3797 Return a random string of characters.
3799 Notes:
3801 · The "ret" buffer must have length "len+1" in order to store the
3803 final "\0" character.
3804 · There is about 5 bits of randomness per output character (so about
3806 "5*len" bits of randomness in the resulting string).
3807 Function "common/utils/utils.c:guestfs_int_drive_name"
3809 char *
3811 guestfs_int_drive_name (size_t index, char *ret)
3812 This turns a drive index (eg. 27) into a drive name (eg. "ab").
3814 Drive indexes count from 0. The return buffer has to be large enough
3816 for the resulting string, and the returned pointer points to the *end*
3817 of the string.
3818 https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
3820 Function "common/utils/utils.c:guestfs_int_drive_index"
3822 ssize_t
3824 guestfs_int_drive_index (const char *name)
3825 The opposite of "guestfs_int_drive_name". Take a string like "ab" and
3827 return the index (eg 27).
3828 Note that you must remove any prefix such as "hd", "sd" etc, or any
3830 partition number before calling the function.
3831 Function "common/utils/utils.c:guestfs_int_is_true"
3833 int
3835 guestfs_int_is_true (const char *str)
3836 Similar to "Tcl_GetBoolean".
3838 Function "common/utils/utils.c:guestfs_int_string_is_valid"
3840 bool
3842 guestfs_int_string_is_valid (const char *str,
3843 size_t min_length, size_t max_length,
3844 int flags, const char *extra)
3845 Check a string for validity, that it contains only certain characters,
3847 and minimum and maximum length. This function is usually wrapped in a
3848 VALID_* macro, see lib/drives.c for an example.
3849 "str" is the string to check.
3851 "min_length" and "max_length" are the minimum and maximum length
3853 checks. 0 means no check.
3854 The flags control:
3856 "VALID_FLAG_ALPHA"
3858 7-bit ASCII-only alphabetic characters are permitted.
3859 "VALID_FLAG_DIGIT"
3861 7-bit ASCII-only digits are permitted.
3862 "extra" is a set of extra characters permitted, in addition to
3864 alphabetic and/or digits. ("extra = NULL" for no extra).
3865 Returns boolean "true" if the string is valid (passes all the tests),
3867 or "false" if not.
3868 Function "common/utils/utils.c:guestfs_int_fadvise_normal"
3870 void
3872 guestfs_int_fadvise_normal (int fd)
3873 Hint that we will read or write the file descriptor normally.
3875 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3877 and sets the per-file number of readahead pages to equal the block
3878 device readahead setting.
3879 It's OK to call this on a non-file since we ignore failure as it is
3881 only a hint.
3882 Function "common/utils/utils.c:guestfs_int_fadvise_sequential"
3884 void
3886 guestfs_int_fadvise_sequential (int fd)
3887 Hint that we will read or write the file descriptor sequentially.
3889 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3891 and sets the per-file number of readahead pages to twice the block
3892 device readahead setting.
3893 It's OK to call this on a non-file since we ignore failure as it is
3895 only a hint.
3896 Function "common/utils/utils.c:guestfs_int_fadvise_random"
3898 void
3900 guestfs_int_fadvise_random (int fd)
3901 Hint that we will read or write the file descriptor randomly.
3903 On Linux, this sets the "FMODE_RANDOM" flag on the file. The effect of
3905 this flag is to:
3906 · Disable normal sequential file readahead.
3908 · If any read of the file is done which misses in the page cache, 2MB
3910 are read into the page cache. [I think - I'm not sure I totally
3911 understand what this is doing]
3912 It's OK to call this on a non-file since we ignore failure as it is
3914 only a hint.
3915 Function "common/utils/utils.c:guestfs_int_fadvise_noreuse"
3917 void
3919 guestfs_int_fadvise_noreuse (int fd)
3920 Hint that we will access the data only once.
3922 On Linux, this does nothing.
3924 It's OK to call this on a non-file since we ignore failure as it is
3926 only a hint.
3927 Function "common/utils/utils.c:guestfs_int_fadvise_dontneed"
3929 void
3931 guestfs_int_fadvise_dontneed (int fd)
3932 Hint that we will not access the data in the near future.
3934 On Linux, this immediately writes out any dirty pages in the page cache
3936 and then invalidates (drops) all pages associated with this file from
3937 the page cache. Apparently it does this even if the file is opened or
3938 being used by other processes. This setting is not persistent; if you
3939 subsequently read the file it will be cached in the page cache as
3940 normal.
3941 It's OK to call this on a non-file since we ignore failure as it is
3943 only a hint.
3944 Function "common/utils/utils.c:guestfs_int_fadvise_willneed"
3946 void
3948 guestfs_int_fadvise_willneed (int fd)
3949 Hint that we will access the data in the near future.
3951 On Linux, this immediately reads the whole file into the page cache.
3953 This setting is not persistent; subsequently pages may be dropped from
3954 the page cache as normal.
3955 It's OK to call this on a non-file since we ignore failure as it is
3957 only a hint.
3958 Function "common/utils/utils.c:guestfs_int_shell_unquote"
3960 char *
3962 guestfs_int_shell_unquote (const char *str)
3963 Unquote a shell-quoted string.
3965 Augeas passes strings to us which may be quoted, eg. if they come from
3967 files in /etc/sysconfig. This function can do simple unquoting of
3968 these strings.
3969 Note this function does not do variable substitution, since that is
3971 impossible without knowing the file context and indeed the environment
3972 under which the shell script is run. Configuration files should not
3973 use complex quoting.
3974 "str" is the input string from Augeas, a string that may be single- or
3976 double-quoted or may not be quoted. The returned string is unquoted,
3977 and must be freed by the caller. "NULL" is returned on error and
3978 "errno" is set accordingly.
3979 For information on double-quoting in bash, see
3981 https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html
3982 Function "common/utils/utils.c:guestfs_int_is_reg"
3984 int
3986 guestfs_int_is_reg (int64_t mode)
3987 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3989 field represents a regular file.
3990 Function "common/utils/utils.c:guestfs_int_is_dir"
3992 int
3994 guestfs_int_is_dir (int64_t mode)
3995 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3997 field represents a directory.
3998 Function "common/utils/utils.c:guestfs_int_is_chr"
4000 int
4002 guestfs_int_is_chr (int64_t mode)
4003 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4005 field represents a char device.
4006 Function "common/utils/utils.c:guestfs_int_is_blk"
4008 int
4010 guestfs_int_is_blk (int64_t mode)
4011 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4013 field represents a block device.
4014 Function "common/utils/utils.c:guestfs_int_is_fifo"
4016 int
4018 guestfs_int_is_fifo (int64_t mode)
4019 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4021 field represents a named pipe (FIFO).
4022 Function "common/utils/utils.c:guestfs_int_is_lnk"
4024 int
4026 guestfs_int_is_lnk (int64_t mode)
4027 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4029 field represents a symbolic link.
4030 Function "common/utils/utils.c:guestfs_int_is_sock"
4032 int
4034 guestfs_int_is_sock (int64_t mode)
4035 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4037 field represents a Unix domain socket.
4038 Function "common/utils/utils.c:guestfs_int_full_path"
4040 char *
4042 guestfs_int_full_path (const char *dir, const char *name)
4043 Concatenate "dir" and "name" to create a path. This correctly handles
4045 the case of concatenating "/" + "filename" as well as "/dir" +
4046 "filename". "name" may be "NULL".
4047 The caller must free the returned path.
4049 This function sets "errno" and returns "NULL" on error.
4051 Function "common/utils/utils.c:guestfs_int_hexdump"
4053 void
4055 guestfs_int_hexdump (const void *data, size_t len, FILE *fp)
4056 Hexdump a block of memory to "FILE *", used for debugging.
4058 Subdirectory common/visit
4060 File common/visit/visit.c
4061 This file contains a recursive function for visiting all files and
4063 directories in a guestfs filesystem.
4064 Adapted from
4066 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/
4067 Function "common/visit/visit.c:visit"
4069 int
4071 visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)
4072 Visit every file and directory in a guestfs filesystem, starting at
4074 "dir".
4075 "dir" may be "/" to visit the entire filesystem, or may be some
4077 subdirectory. Symbolic links are not followed.
4078 The visitor function "f" is called once for every directory and every
4080 file. The parameters passed to "f" include the current directory name,
4081 the current file name (or "NULL" when we're visiting a directory), the
4082 "guestfs_statns" (file permissions etc), and the list of extended
4083 attributes of the file. The visitor function may return "-1" which
4084 causes the whole recursion to stop with an error.
4085 Also passed to this function is an "opaque" pointer which is passed
4087 through to the visitor function.
4088 Returns 0 if everything went OK, or "-1" if there was an error. Error
4090 handling is not particularly well defined. It will either set an error
4091 in the libguestfs handle or print an error on stderr, but there is no
4092 way for the caller to tell the difference.
4093 Subdirectory common/windows
4095 File common/windows/windows.c
4096 This file implements "win:" Windows file path support in guestfish(1).
4098 Function "common/windows/windows.c:is_windows"
4100 int
4102 is_windows (guestfs_h *g, const char *root)
4103 Checks whether "root" is a Windows installation.
4105 This relies on an already being done introspection.
4107 Function "common/windows/windows.c:windows_path"
4109 char *
4111 windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
4112 Resolves "path" as possible Windows path according to "root", giving a
4114 new path that can be used in libguestfs API calls.
4115 Notes:
4117 · "root" must be a Windows installation
4119 · relies on an already being done introspection
4121 · will unmount all the existing mount points and mount the Windows
4123 root (according to "readonly")
4124 · calls exit(3) on memory allocation failures
4126 Subdirectory daemon
4128 File daemon/command.c
4129 This file contains a number of useful functions for running external
4131 commands and capturing their output.
4132 Function "daemon/command.c:commandf"
4134 int
4136 commandf (char **stdoutput, char **stderror, unsigned flags,
4137 const char *name, ...)
4138 Run a command. Optionally capture stdout and stderr as strings.
4140 Returns 0 if the command ran successfully, or "-1" if there was any
4142 error.
4143 For a description of the "flags" see "commandrvf".
4145 There is also a macro "command(out,err,name,...)" which calls
4147 "commandf" with "flags=0".
4148 Function "daemon/command.c:commandrf"
4150 int
4152 commandrf (char **stdoutput, char **stderror, unsigned flags,
4153 const char *name, ...)
4154 Same as "command", but we allow the status code from the subcommand to
4156 be non-zero, and return that status code.
4157 We still return "-1" if there was some other error.
4159 There is also a macro "commandr(out,err,name,...)" which calls
4161 "commandrf" with "flags=0".
4162 Function "daemon/command.c:commandvf"
4164 int
4166 commandvf (char **stdoutput, char **stderror, unsigned flags,
4167 char const *const *argv)
4168 Same as "command", but passing in an argv array.
4170 There is also a macro "commandv(out,err,argv)" which calls "commandvf"
4172 with "flags=0".
4173 Function "daemon/command.c:commandrvf"
4175 int
4177 commandrvf (char **stdoutput, char **stderror, unsigned flags,
4178 char const* const *argv)
4179 This is a more sane version of system(3) for running external commands.
4181 It uses fork/execvp, so we don't need to worry about quoting of
4182 parameters, and it allows us to capture any error messages in a buffer.
4183 If "stdoutput" is not "NULL", then *stdoutput will return the stdout of
4185 the command as a string.
4186 If "stderror" is not "NULL", then *stderror will return the stderr of
4188 the command. If there is a final \n character, it is removed so you
4189 can use the error string directly in a call to "reply_with_error".
4190 Flags are:
4192 "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR"
4194 For broken external commands that send error messages to stdout
4195 (hello, parted) but that don't have any useful stdout information,
4196 use this flag to capture the error messages in the *stderror
4197 buffer. If using this flag, you should pass "stdoutput=NULL"
4198 because nothing could ever be captured in that buffer.
4199 "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN"
4201 For running external commands on chrooted files correctly (see
4202 https://bugzilla.redhat.com/579608) specifying this flag causes
4203 another process to be forked which chroots into sysroot and just
4204 copies the input file to stdin of the specified command. The file
4205 descriptor is ORed with the flags, and that file descriptor is
4206 always closed by this function. See daemon/hexdump.c for an
4207 example of usage.
4208 There is also a macro "commandrv(out,err,argv)" which calls
4210 "commandrvf" with "flags=0".
4211 File daemon/device-name-translation.c
4213 Function
4215 "daemon/device-name-translation.c:device_name_translation_init"
4216 void
4218 device_name_translation_init (void)
4219 Cache daemon disk mapping.
4221 When the daemon starts up, populate a cache with the contents of
4223 /dev/disk/by-path. It's easiest to use "ls -lv" here since the names
4224 are sorted awkwardly.
4225 Function "daemon/device-name-translation.c:device_name_translation"
4227 char *
4229 device_name_translation (const char *device)
4230 Perform device name translation.
4232 Libguestfs defines a few standard formats for device names. (see also
4234 "BLOCK DEVICE NAMING" in guestfs(3) and "guestfs_canonical_device_name"
4235 in guestfs(3)). They are:
4236 /dev/sdX[N]
4238 /dev/hdX[N]
4239 /dev/vdX[N]
4240 These mean the Nth partition on the Xth device. Because Linux no
4241 longer enumerates devices in the order they are passed to qemu, we
4242 must translate these by looking up the actual device using
4243 /dev/disk/by-path/
4244 /dev/mdX
4246 /dev/VG/LV
4247 /dev/mapper/...
4248 /dev/dm-N
4249 These are not translated here.
4250 It returns a newly allocated string which the caller must free.
4252 It returns "NULL" on error. Note it does not call "reply_with_*".
4254 We have to open the device and test for "ENXIO", because the device
4256 nodes may exist in the appliance.
4257 File daemon/guestfsd.c
4259 This is the guestfs daemon which runs inside the guestfs appliance.
4261 This file handles start up and connecting back to the library.
4262 Function "daemon/guestfsd.c:print_shell_quote"
4264 static int
4266 print_shell_quote (FILE *stream,
4267 const struct printf_info *info ATTRIBUTE_UNUSED,
4268 const void *const *args)
4269 printf helper function so we can use %Q ("quoted") and %R to print
4271 shell-quoted strings. See guestfs-hacking(1) for more details.
4272 File daemon/internal.c
4274 Internal functions that are not part of the public API.
4276 File daemon/utils-c.c
4278 Bindings for utility functions.
4280 Note that functions called from OCaml code must never call any of the
4282 "reply*" functions.
4283 File daemon/utils.c
4285 Miscellaneous utility functions used by the daemon.
4287 Function "daemon/utils.c:is_root_device_stat"
4289 static int
4291 is_root_device_stat (struct stat *statbuf)
4292 Return true iff device is the root device (and therefore should be
4294 ignored from the point of view of user calls).
4295 Function "daemon/utils.c:is_device_parameter"
4297 int
4299 is_device_parameter (const char *device)
4300 Parameters marked as "Device", "Dev_or_Path", etc can be passed a block
4302 device name. This function tests if the parameter is a block device
4303 name.
4304 It can also be used in daemon code to test if the string passed as a
4306 "Dev_or_Path" parameter is a device or path.
4307 Function "daemon/utils.c:sysroot_path"
4309 char *
4311 sysroot_path (const char *path)
4312 Turn "/path" into "/sysroot/path".
4314 Returns "NULL" on failure. The caller must check for this and call
4316 "reply_with_perror ("malloc")". The caller must also free the returned
4317 string.
4318 See also the custom %R printf formatter which does shell quoting too.
4320 Function "daemon/utils.c:sysroot_realpath"
4322 char *
4324 sysroot_realpath (const char *path)
4325 Resolve path within sysroot, calling "sysroot_path" on the resolved
4327 path.
4328 Returns "NULL" on failure. The caller must check for this and call
4330 "reply_with_perror ("malloc")". The caller must also free the returned
4331 string.
4332 See also the custom %R printf formatter which does shell quoting too.
4334 Function "daemon/utils.c:is_power_of_2"
4336 int
4338 is_power_of_2 (unsigned long v)
4339 Returns true if "v" is a power of 2.
4341 Uses the algorithm described at
4343 http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2
4344 Function "daemon/utils.c:split_lines_sb"
4346 struct stringsbuf
4348 split_lines_sb (char *str)
4349 Split an output string into a NULL-terminated list of lines, wrapped
4351 into a stringsbuf.
4352 Typically this is used where we have run an external command which has
4354 printed out a list of things, and we want to return an actual list.
4355 The corner cases here are quite tricky. Note in particular:
4357 "" returns "[]"
4359 "\n"
4361 returns "[""]"
4362 "a\nb"
4364 returns "["a"; "b"]"
4365 "a\nb\n"
4367 returns "["a"; "b"]"
4368 "a\nb\n\n"
4370 returns "["a"; "b"; ""]"
4371 The original string is written over and destroyed by this function
4373 (which is usually OK because it's the 'out' string from "command*()").
4374 You can free the original string, because "add_string()" strdups the
4375 strings.
4376 "argv" in the "struct stringsbuf" will be "NULL" in case of errors.
4378 Function "daemon/utils.c:filter_list"
4380 char **
4382 filter_list (bool (*p) (const char *str), char **strs)
4383 Filter a list of strings. Returns a newly allocated list of only the
4385 strings where "p (str) == true".
4386 Note it does not copy the strings, be careful not to double-free them.
4388 Function "daemon/utils.c:trim"
4390 void
4392 trim (char *str)
4393 Skip leading and trailing whitespace, updating the original string in-
4395 place.
4396 Function "daemon/utils.c:parse_btrfsvol"
4398 int
4400 parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
4401 Parse the mountable descriptor for a btrfs subvolume. Don't call this
4403 directly; it is only used from the stubs.
4404 A btrfs subvolume is given as:
4406 btrfsvol:/dev/sda3/root
4408 where /dev/sda3 is a block device containing a btrfs filesystem, and
4410 root is the name of a subvolume on it. This function is passed the
4411 string following "btrfsvol:".
4412 On success, "mountable->device" and "mountable->volume" must be freed
4414 by the caller.
4415 Function "daemon/utils.c:mountable_to_string"
4417 char *
4419 mountable_to_string (const mountable_t *mountable)
4420 Convert a "mountable_t" back to its string representation
4422 This function can be used in an error path, so must not call
4424 "reply_with_error".
4425 Function "daemon/utils.c:prog_exists"
4427 int
4429 prog_exists (const char *prog)
4430 Check program exists and is executable on $PATH.
4432 Function "daemon/utils.c:random_name"
4434 int
4436 random_name (char *template)
4437 Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
4439 template to contain a randomly named file. Any 'X' characters after
4440 the final '/' in the template are replaced with random characters.
4441 Notes: You should probably use an 8.3 path, so it's compatible with all
4443 filesystems including basic FAT. Also this only substitutes lowercase
4444 ASCII letters and numbers, again for compatibility with lowest common
4445 denominator filesystems.
4446 This doesn't create a file or check whether or not the file exists (it
4448 would be extremely unlikely to exist as long as the RNG is working).
4449 If there is an error, "-1" is returned.
4451 Function "daemon/utils.c:udev_settle_file"
4453 void
4455 udev_settle_file (const char *file)
4456 LVM and other commands aren't synchronous, especially when udev is
4458 involved. eg. You can create or remove some device, but the "/dev"
4459 device node won't appear until some time later. This means that you
4460 get an error if you run one command followed by another.
4461 Use "udevadm settle" after certain commands, but don't be too fussed if
4463 it fails.
4464 Function "daemon/utils.c:make_exclude_from_file"
4466 char *
4468 make_exclude_from_file (const char *function, char *const *excludes)
4469 Turn list "excludes" into a temporary file, and return a string
4471 containing the temporary file name. Caller must unlink the file and
4472 free the string.
4473 "function" is the function that invoked this helper, and it is used
4475 mainly for errors/debugging.
4476 Function "daemon/utils.c:read_whole_file"
4478 char *
4480 read_whole_file (const char *filename, size_t *size_r)
4481 Read whole file into dynamically allocated array. If there is an
4483 error, DON'T call reply_with_perror, just return NULL. Returns a
4484 "\0"-terminated string. "size_r" can be specified to get the size of
4485 the returned data.
4486 File daemon/xattr.c
4488 Function "daemon/xattr.c:split_attr_names"
4490 static char **
4492 split_attr_names (char *buf, size_t len)
4493 listxattr(2) returns the string "foo\0bar\0baz" of length "len". (The
4495 last string in the list is \0-terminated but the \0 is not included in
4496 "len").
4497 This function splits it into a regular list of strings.
4499 Note that the returned list contains pointers to the original strings
4501 in "buf" so be careful that you do not double-free them.
4502 Subdirectory fish
4504 File fish/alloc.c
4505 This file implements the guestfish "alloc" and "sparse" commands.
4507 Function "fish/alloc.c:alloc_disk"
4509 int
4511 alloc_disk (const char *filename, const char *size_str, int add, int sparse)
4512 This is the underlying allocation function. It's called from a few
4514 other places in guestfish.
4515 File fish/copy.c
4517 This file implements the guestfish commands "copy-in" and "copy-out".
4519 File fish/destpaths.c
4521 The file handles tab-completion of filesystem paths in guestfish.
4523 File fish/display.c
4525 The file implements the guestfish "display" command, for displaying
4527 graphical files (icons, images) in disk images.
4528 File fish/echo.c
4530 The file implements the guestfish "echo" command.
4532 File fish/edit.c
4534 guestfish "edit" command, suggested by Ján Ondrej.
4536 File fish/events.c
4538 This file implements the guestfish event-related commands, "event",
4540 "delete-event" and "list-events".
4541 File fish/fish.c
4543 guestfish, the guest filesystem shell. This file contains the main
4545 loop and utilities.
4546 Function "fish/fish.c:parse_command_line"
4548 static struct parsed_command
4550 parse_command_line (char *buf, int *exit_on_error_rtn)
4551 Parse a command string, splitting at whitespace, handling '!', '#' etc.
4553 This destructively updates "buf".
4554 "exit_on_error_rtn" is used to pass in the global "exit_on_error"
4556 setting and to return the local setting (eg. if the command begins with
4557 '-').
4558 Returns in "parsed_command.status":
4560 1 got a guestfish command (returned in
4562 "cmd_rtn"/"argv_rtn"/"pipe_rtn")
4563 0 no guestfish command, but otherwise OK
4565 "-1"
4567 an error
4568 Function "fish/fish.c:parse_quoted_string"
4570 static ssize_t
4572 parse_quoted_string (char *p)
4573 Parse double-quoted strings, replacing backslash escape sequences with
4575 the true character. Since the string is returned in place, the escapes
4576 must make the string shorter.
4577 Function "fish/fish.c:execute_and_inline"
4579 static int
4581 execute_and_inline (const char *cmd, int global_exit_on_error)
4582 Used to handle "<!" (execute command and inline result).
4584 Function "fish/fish.c:issue_command"
4586 int
4588 issue_command (const char *cmd, char *argv[], const char *pipecmd,
4589 int rc_exit_on_error_flag)
4590 Run a command.
4592 "rc_exit_on_error_flag" is the "exit_on_error" flag that we pass to the
4594 remote server (when issuing --remote commands). It does not cause
4595 "issue_command" itself to exit on error.
4596 Function "fish/fish.c:extended_help_message"
4598 void
4600 extended_help_message (void)
4601 Print an extended help message when the user types in an unknown
4603 command for the first command issued. A common case is the user doing:
4604 guestfish disk.img
4606 expecting guestfish to open disk.img (in fact, this tried to run a non-
4608 existent command "disk.img").
4609 Function "fish/fish.c:error_cb"
4611 static void
4613 error_cb (guestfs_h *g, void *data, const char *msg)
4614 Error callback. This replaces the standard libguestfs error handler.
4616 Function "fish/fish.c:free_n_strings"
4618 static void
4620 free_n_strings (char **str, size_t len)
4621 Free strings from a non-NULL terminated "char**".
4623 Function "fish/fish.c:decode_ps1"
4625 static char *
4627 decode_ps1 (const char *str)
4628 Decode "str" into the final printable prompt string.
4630 Function "fish/fish.c:win_prefix"
4632 char *
4634 win_prefix (const char *path)
4635 Resolve the special "win:..." form for Windows-specific paths. The
4637 generated code calls this for all device or path arguments.
4638 The function returns a newly allocated string, and the caller must free
4640 this string; else display an error and return "NULL".
4641 Function "fish/fish.c:file_in"
4643 char *
4645 file_in (const char *arg)
4646 Resolve the special "FileIn" paths ("-" or "-<<END" or filename).
4648 The caller (fish/cmds.c) will call "free_file_in" after the command has
4650 run which should clean up resources.
4651 Function "fish/fish.c:file_out"
4653 char *
4655 file_out (const char *arg)
4656 Resolve the special "FileOut" paths ("-" or filename).
4658 The caller (fish/cmds.c) will call "free (str)" after the command has
4660 run.
4661 Function "fish/fish.c:progress_callback"
4663 void
4665 progress_callback (guestfs_h *g, void *data,
4666 uint64_t event, int event_handle, int flags,
4667 const char *buf, size_t buf_len,
4668 const uint64_t *array, size_t array_len)
4669 Callback which displays a progress bar.
4671 File fish/glob.c
4673 This file implements the guestfish "glob" command.
4675 Function "fish/glob.c:expand_devicename"
4677 static char **
4679 expand_devicename (guestfs_h *g, const char *device)
4680 Glob-expand device patterns, such as "/dev/sd*"
4682 (https://bugzilla.redhat.com/635971).
4683 There is no "guestfs_glob_expand_device" function because the
4685 equivalent can be implemented using functions like
4686 "guestfs_list_devices".
4687 It's not immediately clear what it means to expand a pattern like
4689 "/dev/sd*". Should that include device name translation? Should the
4690 result include partitions as well as devices?
4691 Should "/dev/" + "*" return every possible device and filesystem? How
4693 about VGs? LVs?
4694 To solve this what we do is build up a list of every device, partition,
4696 etc., then glob against that list.
4697 Notes for future work (XXX):
4699 · This doesn't handle device name translation. It wouldn't be too
4701 hard to add.
4702 · Could have an API function for returning all device-like things.
4704 Function "fish/glob.c:add_strings_matching"
4706 static int
4708 add_strings_matching (char **pp, const char *glob,
4709 char ***ret, size_t *size_r)
4710 Using POSIX fnmatch(3), find strings in the list "pp" which match
4712 pattern "glob". Add strings which match to the "ret" array. *size_r
4713 is the current size of the "ret" array, which is updated with the new
4714 size.
4715 Function "fish/glob.c:single_element_list"
4717 static char **
4719 single_element_list (const char *element)
4720 Return a single element list containing "element".
4722 File fish/help.c
4724 The file implements the guestfish "help" command.
4726 Function "fish/help.c:display_help"
4728 int
4730 display_help (const char *cmd, size_t argc, char *argv[])
4731 The "help" command.
4733 This used to just list all commands, but that's not very useful.
4735 Instead display some useful context-sensitive help. This could be
4736 improved if we knew how many drives had been added already, and whether
4737 anything was mounted.
4738 File fish/hexedit.c
4740 This file implements the guestfish "hexedit" command.
4742 File fish/lcd.c
4744 Function "fish/lcd.c:run_lcd"
4746 int
4748 run_lcd (const char *cmd, size_t argc, char *argv[])
4749 guestfish "lcd" command (similar to the "lcd" command in BSD ftp).
4751 File fish/man.c
4753 Function "fish/man.c:run_man"
4755 int
4757 run_man (const char *cmd, size_t argc, char *argv[])
4758 guestfish "man" command
4760 File fish/more.c
4762 This file implements the guestfish "more" command.
4764 File fish/prep.c
4766 This file implements the guestfish -N option for creating pre-prepared
4768 disk layouts.
4769 File fish/rc.c
4771 This file implements guestfish remote (command) support.
4773 Function "fish/rc.c:rc_listen"
4775 void
4777 rc_listen (void)
4778 The remote control server (ie. "guestfish --listen").
4780 Function "fish/rc.c:rc_remote"
4782 int
4784 rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
4785 int exit_on_error)
4786 The remote control client (ie. "guestfish --remote").
4788 File fish/reopen.c
4790 This file implements the guestfish "reopen" command.
4792 File fish/setenv.c
4794 This file implements the guestfish "setenv" and "unsetenv" commands.
4796 File fish/supported.c
4798 This file implements the guestfish "supported" command.
4800 File fish/tilde.c
4802 This file implements tilde ("~") expansion of home directories in
4804 guestfish(1).
4805 Function "fish/tilde.c:try_tilde_expansion"
4807 char *
4809 try_tilde_expansion (char *str)
4810 This is called from the script loop if we find a candidate for
4812 "~username" (tilde-expansion).
4813 Function "fish/tilde.c:expand_home"
4815 static char *
4817 expand_home (char *orig, const char *append)
4818 Return $HOME + append string.
4820 Function "fish/tilde.c:find_home_for_username"
4822 static const char *
4824 find_home_for_username (const char *username, size_t ulen)
4825 Lookup "username" (of length "ulen"), return home directory if found,
4827 or "NULL" if not found.
4828 File fish/time.c
4830 This file implements the guestfish "time" command.
4832 Subdirectory python
4834 File python/handle.c
4835 This file contains a small number of functions that are written by
4837 hand. The majority of the bindings are generated (see
4838 python/actions-*.c).
4839
4841 guestfs(3), guestfs-building(1), guestfs-examples(3),
4842 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
4843 guestfs-testing(1), libguestfs-test-tool(1),
4844 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
4845
4847 Richard W.M. Jones ("rjones at redhat dot com")
4848
4850 Copyright (C) 2009-2020 Red Hat Inc.
4851
4853 This library is free software; you can redistribute it and/or modify it
4854 under the terms of the GNU Lesser General Public License as published
4855 by the Free Software Foundation; either version 2 of the License, or
4856 (at your option) any later version.
4857 This library is distributed in the hope that it will be useful, but
4859 WITHOUT ANY WARRANTY; without even the implied warranty of
4860 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4861 Lesser General Public License for more details.
4862 You should have received a copy of the GNU Lesser General Public
4864 License along with this library; if not, write to the Free Software
4865 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
4866 02110-1301 USA
4867
4869 To get a list of bugs against libguestfs, use this link:
4870 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
4871 To report a new bug against libguestfs, use this link:
4873 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
4874 When reporting a bug, please supply:
4876 · The version of libguestfs.
4878 · Where you got libguestfs (eg. which Linux distro, compiled from
4880 source, etc)
4881 · Describe the bug accurately and give a way to reproduce it.
4883 · Run libguestfs-test-tool(1) and paste the complete, unedited output
4885 into the bug report.
4886libguestfs-1.44.0 2021-01-05 guestfs-hacking(1)