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. v2v) or language
48 binding (eg. python), go straight to that subdirectory, but remember
49 that if you didn't run the generator yet, then you may find files which
50 appear to be missing.
51 align
53 virt-alignment-scan(1) command and documentation.
54 appliance
56 The libguestfs appliance, build scripts and so on.
57 bash
59 Bash tab-completion scripts.
60 build-aux
62 Various build scripts used by autotools.
63 builder
65 virt-builder(1) command and documentation.
66 cat The virt-cat(1), virt-filesystems(1), virt-log(1), virt-ls(1) and
68 virt-tail(1) commands and documentation.
69 common
71 Various libraries of internal code can be found in the common
72 subdirectory:
73 common/edit
75 Common code for interactively and non-interactively editing
76 files within a libguestfs filesystem.
77 common/errnostring
79 The communication protocol used between the library and the
80 daemon running inside the appliance has to encode errnos as
81 strings, which is handled by this library.
82 common/miniexpect
84 A copy of the miniexpect library from
85 http://git.annexia.org/?p=miniexpect.git;a=summary. This is
86 used in virt-p2v.
87 common/mlaugeas
89 Bindings for the Augeas library. These come from the ocaml-
90 augeas library http://git.annexia.org/?p=ocaml-augeas.git
91 common/mlgettext
93 Small, generated wrapper which allows libguestfs to be compiled
94 with or without ocaml-gettext. This is generated by
95 ./configure.
96 common/mlpcre
98 Lightweight OCaml bindings for Perl Compatible Regular
99 Expressions (PCRE). Note this is not related in any way to
100 Markus Mottl's ocaml-pcre library.
101 common/mlprogress
103 OCaml bindings for the progress bar functions (see
104 common/progress).
105 common/mlstdutils
107 A library of pure OCaml utility functions used in many places.
108 common/mltools
110 OCaml utility functions only used by the OCaml virt tools (like
111 "virt-sysprep", "virt-v2v" etc.)
112 common/mlutils
114 OCaml bindings for C functions in "common/utils", and some
115 POSIX bindings which are missing from the OCaml stdlib.
116 common/mlvisit
118 OCaml bindings for the visit functions (see common/visit).
119 common/mlxml
121 OCaml bindings for the libxml2 library.
122 common/options
124 Common options parsing for guestfish, guestmount and some virt
125 tools.
126 common/parallel
128 A framework used for processing multiple libvirt domains in
129 parallel.
130 common/progress
132 Common code for printing progress bars.
133 common/protocol
135 The XDR-based communication protocol used between the library
136 and the daemon running inside the appliance is defined here.
137 common/qemuopts
139 Mini-library for writing qemu command lines and qemu config
140 files.
141 common/structs
143 Common code for printing and freeing libguestfs structs, used
144 by the library and some tools.
145 common/utils
147 Various utility functions used throughout the library and
148 tools.
149 common/visit
151 Recursively visit a guestfs filesystem hierarchy.
152 common/windows
154 Utility functions for handling Windows drive letters.
155 contrib
157 Outside contributions, experimental parts.
158 customize
160 virt-customize(1) command and documentation.
161 daemon
163 The daemon that runs inside the libguestfs appliance and carries
164 out actions.
165 df virt-df(1) command and documentation.
167 dib virt-dib(1) command and documentation.
169 diff
171 virt-diff(1) command and documentation.
172 docs
174 Miscellaneous manual pages.
175 edit
177 virt-edit(1) command and documentation.
178 examples
180 C API example code.
181 fish
183 guestfish(1), the command-line shell, and various shell scripts
184 built on top such as virt-copy-in(1), virt-copy-out(1),
185 virt-tar-in(1), virt-tar-out(1).
186 format
188 virt-format(1) command and documentation.
189 fuse
191 guestmount(1), FUSE (userspace filesystem) built on top of
192 libguestfs.
193 generator
195 The crucially important generator, used to automatically generate
196 large amounts of boilerplate C code for things like RPC and
197 bindings.
198 get-kernel
200 virt-get-kernel(1) command and documentation.
201 gnulib
203 Gnulib is used as a portability library. A copy of gnulib is
204 included under here.
205 inspector
207 virt-inspector(1), the virtual machine image inspector.
208 lib Source code to the C library.
210 logo
212 Logo used on the website. The fish is called Arthur by the way.
213 m4 M4 macros used by autoconf. See "THE BUILD SYSTEM".
215 make-fs
217 virt-make-fs(1) command and documentation.
218 p2v virt-p2v(1) command, documentation and scripts for building the
220 virt-p2v ISO or disk image.
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 virt-v2v(1) command and documentation.
264 website
266 The http://libguestfs.org website files.
267 csharp
269 erlang
270 gobject
271 golang
272 haskell
273 java
274 lua
275 ocaml
276 php
277 perl
278 python
279 ruby
280 Language bindings.
281 THE BUILD SYSTEM
283 Libguestfs uses the GNU autotools build system (autoconf, automake,
284 libtool).
285 The ./configure script is generated from configure.ac and
287 m4/guestfs-*.m4. Most of the configure script is split over many m4
288 macro files by topic, for example m4/guestfs-daemon.m4 deals with the
289 dependencies of the daemon.
290 The job of the top level Makefile.am is mainly to list the
292 subdirectories ("SUBDIRS") in the order they should be compiled.
293 common-rules.mk is included in every Makefile.am (top level and
295 subdirectories). subdir-rules.mk is included only in subdirectory
296 Makefile.am files.
297 There are many make targets. Use this command to list them all:
299 make help
301
303 ADDING A NEW API
304 Because large amounts of boilerplate code in libguestfs are generated,
305 this makes it easy to extend the libguestfs API.
306 To add a new API action there are two changes:
308 1. You need to add a description of the call (name, parameters, return
310 type, tests, documentation) to generator/actions_*.ml and possibly
311 generator/proc_nr.ml.
312 There are two sorts of API action, depending on whether the call
314 goes through to the daemon in the appliance, or is serviced
315 entirely by the library (see "ARCHITECTURE" in
316 guestfs-internals(1)). "guestfs_sync" in guestfs(3) is an example
317 of the former, since the sync is done in the appliance.
318 "guestfs_set_trace" in guestfs(3) is an example of the latter,
319 since a trace flag is maintained in the handle and all tracing is
320 done on the library side.
321 Most new actions are of the first type, and get added to the
323 "daemon_functions" list. Each function has a unique procedure
324 number used in the RPC protocol which is assigned to that action
325 when we publish libguestfs and cannot be reused. Take the latest
326 procedure number and increment it.
327 For library-only actions of the second type, add to the
329 "non_daemon_functions" list. Since these functions are serviced by
330 the library and do not travel over the RPC mechanism to the daemon,
331 these functions do not need a procedure number, and so the
332 procedure number is set to "-1".
333 2. Implement the action (in C):
335 For daemon actions, implement the function "do_<name>" in the
337 "daemon/" directory.
338 For library actions, implement the function "guestfs_impl_<name>"
340 in the "lib/" directory.
341 In either case, use another function as an example of what to do.
343 3. As an alternative to step 2: Since libguestfs 1.38, daemon actions
345 can be implemented in OCaml. You have to set the "impl = OCaml
346 ..." flag in the generator. Take a look at daemon/file.ml for an
347 example.
348 After making these changes, use "make" to compile.
350 Note that you don’t need to implement the RPC, language bindings,
352 manual pages or anything else. It’s all automatically generated from
353 the OCaml description.
354 Adding tests for an API
356 You can supply zero or as many tests as you want per API call. The
358 tests can either be added as part of the API description
359 (generator/actions_*.ml), or in some rarer cases you may want to drop a
360 script into "tests/*/". Note that adding a script to "tests/*/" is
361 slower, so if possible use the first method.
362 The following describes the test environment used when you add an API
364 test in actions_*.ml.
365 The test environment has 4 block devices:
367 /dev/sda 2 GB
369 General block device for testing.
370 /dev/sdb 2 GB
372 /dev/sdb1 is an ext2 filesystem used for testing filesystem write
373 operations.
374 /dev/sdc 10 MB
376 Used in a few tests where two block devices are needed.
377 /dev/sdd
379 ISO with fixed content (see images/test.iso).
380 To be able to run the tests in a reasonable amount of time, the
382 libguestfs appliance and block devices are reused between tests. So
383 don't try testing "guestfs_kill_subprocess" in guestfs(3) :-x
384 Each test starts with an initial scenario, selected using one of the
386 "Init*" expressions, described in generator/types.ml. These initialize
387 the disks mentioned above in a particular way as documented in
388 types.ml. You should not assume anything about the previous contents
389 of other disks that are not initialized.
390 You can add a prerequisite clause to any individual test. This is a
392 run-time check, which, if it fails, causes the test to be skipped.
393 Useful if testing a command which might not work on all variations of
394 libguestfs builds. A test that has prerequisite of "Always" means to
395 run unconditionally.
396 In addition, packagers can skip individual tests by setting environment
398 variables before running "make check".
399 SKIP_TEST_<CMD>_<NUM>=1
401 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command" in
403 guestfs(3).
404 or:
406 SKIP_TEST_<CMD>=1
408 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" in guestfs(3)
410 tests.
411 Packagers can run only certain tests by setting for example:
413 TEST_ONLY="vfs_type zerofree"
415 See tests/c-api/tests.c for more details of how these environment
417 variables work.
418 Debugging new APIs
420 Test new actions work before submitting them.
422 You can use guestfish to try out new commands.
424 Debugging the daemon is a problem because it runs inside a minimal
426 environment. However you can fprintf messages in the daemon to stderr,
427 and they will show up if you use "guestfish -v".
428 ADDING A NEW LANGUAGE BINDING
430 All language bindings must be generated by the generator (see the
431 generator subdirectory).
432 There is no documentation for this yet. We suggest you look at an
434 existing binding, eg. generator/ocaml.ml or generator/perl.ml.
435 Adding tests for language bindings
437 Language bindings should come with tests. Previously testing of
439 language bindings was rather ad-hoc, but we have been trying to
440 formalize the set of tests that every language binding should use.
441 Currently only the OCaml and Perl bindings actually implement the full
443 set of tests, and the OCaml bindings are canonical, so you should
444 emulate what the OCaml tests do.
445 This is the numbering scheme used by the tests:
447 - 000+ basic tests:
449 010 load the library
451 020 create
452 030 create-flags
453 040 create multiple handles
454 050 test setting and getting config properties
455 060 explicit close
456 065 implicit close (in GC'd languages)
457 070 optargs
458 080 version
459 090 retvalues
460 - 100 launch, create partitions and LVs and filesystems
462 - 400+ events:
464 410 close event
466 420 log messages
467 430 progress messages
468 - 800+ regression tests (specific to the language)
470 - 900+ any other custom tests for the language
472 To save time when running the tests, only 100, 430, 800+, 900+ should
474 launch the handle.
475 FORMATTING CODE
477 Our C source code generally adheres to some basic code-formatting
478 conventions. The existing code base is not totally consistent on this
479 front, but we do prefer that contributed code be formatted similarly.
480 In short, use spaces-not-TABs for indentation, use 2 spaces for each
481 indentation level, and other than that, follow the K&R style.
482 If you use Emacs, add the following to one of your start-up files
484 (e.g., ~/.emacs), to help ensure that you get indentation right:
485 ;;; In libguestfs, indent with spaces everywhere (not TABs).
487 ;;; Exceptions: Makefile and ChangeLog modes.
488 (add-hook 'find-file-hook
489 '(lambda () (if (and buffer-file-name
490 (string-match "/libguestfs\\>"
491 (buffer-file-name))
492 (not (string-equal mode-name "Change Log"))
493 (not (string-equal mode-name "Makefile")))
494 (setq indent-tabs-mode nil))))
495 ;;; When editing C sources in libguestfs, use this style.
497 (defun libguestfs-c-mode ()
498 "C mode with adjusted defaults for use with libguestfs."
499 (interactive)
500 (c-set-style "K&R")
501 (setq c-indent-level 2)
502 (setq c-basic-offset 2))
503 (add-hook 'c-mode-hook
504 '(lambda () (if (string-match "/libguestfs\\>"
505 (buffer-file-name))
506 (libguestfs-c-mode))))
507 TESTING YOUR CHANGES
509 Turn warnings into errors when developing to make warnings hard to
510 ignore:
511 ./configure --enable-werror
513 Useful targets are:
515 "make check"
517 Runs the regular test suite.
518 This is implemented using the regular automake "TESTS" target. See
520 the automake documentation for details.
521 "make check-valgrind"
523 Runs a subset of the test suite under valgrind.
524 See "VALGRIND" below.
526 "make check-valgrind-local-guests"
528 Runs a subset of the test suite under valgrind using locally
529 installed libvirt guests (read-only).
530 "make check-direct"
532 Runs all tests using default appliance back-end. This only has any
533 effect if a non-default backend was selected using "./configure
534 --with-default-backend=..."
535 "make check-valgrind-direct"
537 Run a subset of the test suite under valgrind using the default
538 appliance back-end.
539 "make check-uml"
541 Runs all tests using the User-Mode Linux backend.
542 As there is no standard location for the User-Mode Linux kernel,
544 you have to set "LIBGUESTFS_HV" to point to the kernel image, eg:
545 make check-uml LIBGUESTFS_HV=~/d/linux-um/vmlinux
547 "make check-valgrind-uml"
549 Runs all tests using the User-Mode Linux backend, under valgrind.
550 As above, you have to set "LIBGUESTFS_HV" to point to the kernel.
552 "make check-with-upstream-qemu"
554 Runs all tests using a local qemu binary. It looks for the qemu
555 binary in QEMUDIR (defaults to $HOME/d/qemu), but you can set this
556 to another directory on the command line, eg:
557 make check-with-upstream-qemu QEMUDIR=/usr/src/qemu
559 "make check-with-upstream-libvirt"
561 Runs all tests using a local libvirt. This only has any effect if
562 the libvirt backend was selected using "./configure
563 --with-default-backend=libvirt"
564 It looks for libvirt in LIBVIRTDIR (defaults to $HOME/d/libvirt),
566 but you can set this to another directory on the command line, eg:
567 make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt
569 "make check-slow"
571 Runs some slow/long-running tests which are not run by default.
572 To mark a test as slow/long-running:
574 · Add it to the list of "TESTS" in the Makefile.am, just like a
576 normal test.
577 · Modify the test so it checks if the "SLOW=1" environment
579 variable is set, and if not set it skips (ie. returns with exit
580 code 77). If using $TEST_FUNCTIONS, you can call the function
581 "slow_test" for this.
582 · Add a variable "SLOW_TESTS" to the Makefile.am listing the slow
584 tests.
585 · Add a rule to the Makefile.am:
587 check-slow:
589 $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
590 "sudo make check-root"
592 Runs some tests which require root privileges. These are supposed
593 to be safe, but take care. You have to run this as root (eg. using
594 sudo(8) explicitly).
595 To mark a test as requiring root:
597 · Add it to the list of "TESTS" in the Makefile.am, just like a
599 normal test.
600 · Modify the test so it checks if euid == 0, and if not set it
602 skips (ie. returns with exit code 77). If using
603 $TEST_FUNCTIONS, you can call the function "root_test" for
604 this.
605 · Add a variable "ROOT_TESTS" to the Makefile.am listing the root
607 tests.
608 · Add a rule to the Makefile.am:
610 check-root:
612 $(MAKE) check TESTS="$(ROOT_TESTS)"
613 "make check-all"
615 Equivalent to running all "make check*" rules except "check-root".
616 "make check-release"
618 Runs a subset of "make check*" rules that are required to pass
619 before a tarball can be released. Currently this is:
620 · check
622 · check-valgrind
624 · check-direct
626 · check-valgrind-direct
628 · check-slow
630 "make installcheck"
632 Run "make check" on the installed copy of libguestfs.
633 The version of installed libguestfs being tested, and the version
635 of the libguestfs source tree must be the same.
636 Do:
638 ./autogen.sh
640 make clean ||:
641 make
642 make installcheck
643 VALGRIND
645 When you do "make check-valgrind", it searches for any Makefile.am in
646 the tree that has a "check-valgrind:" target and runs it.
647 Writing the Makefile.am and tests correctly to use valgrind and working
649 with automake parallel tests is subtle.
650 If your tests are run via a shell script wrapper, then in the wrapper
652 use:
653 $VG virt-foo
655 and in the Makefile.am use:
657 check-valgrind:
659 make VG="@VG@" check
660 However, if your binaries run directly from the "TESTS" rule, you have
662 to modify the Makefile.am like this:
663 LOG_COMPILER = $(VG)
665 check-valgrind:
667 make VG="@VG@" check
668 In either case, check that the right program is being tested by
670 examining the tmp/valgrind* log files carefully.
671 SUBMITTING PATCHES
673 Submit patches to the mailing list:
674 http://www.redhat.com/mailman/listinfo/libguestfs and CC to
675 rjones@redhat.com.
676 You do not need to subscribe to the mailing list if you don’t want to.
678 There may be a short delay while your message is moderated.
679 DAEMON CUSTOM PRINTF FORMATTERS
681 In the daemon code we have created custom printf formatters %Q and %R,
682 which are used to do shell quoting.
683 %Q Simple shell quoted string. Any spaces or other shell characters
685 are escaped for you.
686 %R Same as %Q except the string is treated as a path which is prefixed
688 by the sysroot.
689 For example:
691 asprintf (&cmd, "cat %R", path);
693 would produce "cat /sysroot/some\ path\ with\ spaces"
695 Note: Do not use these when you are passing parameters to the
697 "command{,r,v,rv}()" functions. These parameters do NOT need to be
698 quoted because they are not passed via the shell (instead, straight to
699 exec). You probably want to use the "sysroot_path()" function however.
700 INTERNATIONALIZATION (I18N) SUPPORT
702 We support i18n (gettext anyhow) in the library.
703 However many messages come from the daemon, and we don’t translate
705 those at the moment. One reason is that the appliance generally has
706 all locale files removed from it, because they take up a lot of space.
707 So we'd have to readd some of those, as well as copying our PO files
708 into the appliance.
709 Debugging messages are never translated, since they are intended for
711 the programmers.
712
714 HOW OCAML PROGRAMS ARE COMPILED AND LINKED
715 Mostly this section is "how we make automake & ocamlopt work together"
716 since OCaml programs themselves are easy to compile.
717 Automake has no native support for OCaml programs, ocamlc nor ocamlopt.
719 What we do instead is to treat OCaml programs as C programs which
720 happen to contain these "other objects" ("DEPENDENCIES" in automake-
721 speak) that happen to be the OCaml objects. This works because OCaml
722 programs usually have C files for native bindings etc.
723 So a typical program is described as just its C sources:
725 virt_v2v_SOURCES = ... utils-c.c xml-c.c
727 For programs that have no explicit C sources, we create an empty
729 dummy.c file, and list that instead:
730 virt_resize_SOURCES = dummy.c
732 The OCaml objects which contain most of the code are listed as automake
734 dependencies (other dependencies may also be listed):
735 virt_v2v_DEPENDENCIES = ... cmdline.cmx v2v.cmx
737 The only other special thing we need to do is to provide a custom link
739 command. This is needed because automake won't assemble the ocamlopt
740 command, the list of objects and the "-cclib" libraries in the correct
741 order otherwise.
742 virt_v2v_LINK = \
744 $(top_srcdir)/ocaml-link.sh -cclib '-lutils -lgnu' -- ...
745 The actual rules, which you can examine in v2v/Makefile.am, are a
747 little bit more complicated than this because they have to handle:
748 · Compiling for byte code or native code.
750 · The pattern rules needed to compile the OCaml sources to objects.
752 These are now kept in subdir-rules.mk at the top level, which is
754 included in every subdirectory Makefile.am.
755 · Adding OCaml sources files to "EXTRA_DIST".
757 Automake isn't aware of the complete list of sources for a binary,
759 so it will not add them all automatically.
760 VIRT-V2V
762 First a little history. Virt-v2v has been through at least two
763 complete rewrites, so this is probably about the third version (but we
764 don't intend to rewrite it again). The previous version was written in
765 Perl and can be found here:
766 https://git.fedorahosted.org/git/virt-v2v.git
767 The current version started out as almost a line-for-line rewrite of
769 the Perl code in OCaml + C, and it still has a fairly similar
770 structure. Therefore if there are details of this code that you don't
771 understand (especially in the details of guest conversion), checking
772 the Perl code may help.
773 The files to start with when reading this code are:
775 · types.mli
777 · v2v.ml
779 types.mli defines all the structures used and passed around when
781 communicating between different bits of the program. v2v.ml controls
782 how the program runs in stages.
783 After studying those files, you may want to branch out into the input
785 modules (input_*), the output modules (output_*) or the conversion
786 modules (convert_*). The input and output modules define -i and -o
787 options (see the manual). The conversion modules define what guest
788 types we can handle and the detailed steps involved in converting them.
789 Every other file in this directory is a support module / library of
791 some sort. Some code is written in C, especially where we want to use
792 an external C library such as libxml2.
793 VIRT-P2V
795 Virt-p2v is a front end on virt-v2v. ie. All it does is act as a GUI
796 front end, and it calls out to virt-v2v to perform the actual
797 conversion. Therefore most of the C code in the p2v/ subdirectory is
798 Gtk (GUI) code, or supporting code for talking to the remote conversion
799 server. There is no special support for physical machines in virt-v2v.
800 They are converted in the same way as foreign VMs.
801 Running virt-p2v
803 You can run the p2v/virt-p2v binary directly, but it will try to
805 convert your machine’s real /dev/sda which is unlikely to work well.
806 However virt-p2v also has a test mode in which you can supply a test
807 disk:
808 make -C p2v run-virt-p2v-directly
810 This is a wrapper around the virt-p2v(1) --test-disk option. You can
812 control the "physical machine" disk by setting "PHYSICAL_MACHINE" to
813 point to a disk image.
814 A more realistic test is to run virt-p2v inside a VM on the local
816 machine. To do that, do:
817 make -C p2v run-virt-p2v-in-a-vm
819 This also runs qemu with the "physical machine" disk (which you can set
821 by setting "PHYSICAL_MACHINE"), a virtual CD, and a variety of network
822 cards for testing. You can change the qemu binary and add extra qemu
823 options by setting "QEMU" and/or "QEMU_OPTIONS" on the make
824 commandline.
825 A third way to run virt-p2v simulates fairly accurately the program
827 being downloaded over PXE and then doing an automatic conversion of the
828 source physical machine (the non-GUI path -- see next section below):
829 make -C p2v run-virt-p2v-non-gui-conversion
831 Understanding the virt-p2v code
833 See also: "HOW VIRT-P2V WORKS" in virt-p2v(1)
835 There are two paths through the code, GUI or non-GUI (parsing the
837 kernel command line):
838 main.c ──────┬─────▶ gui.c ──────┬─────▶ conversion.c
840 │ │
841 │ │
842 └────▶ kernel.c ────┘
843 but both paths call back to the conversion.c function
845 "start_conversion" to run the remote virt-v2v.
846 The main task of gui.c/kernel.c is to populate the virt-v2v
848 configuration (config.c).
849 During conversion, we need to establish ssh connections, and that is
851 done using two libraries:
852 conversion.c ──────▶ ssh.c ──────▶ miniexpect.c
854 where ssh.c is responsible for managing ssh connections overall, and
856 miniexpect.c implements "expect-like" functionality for talking
857 interactively to the remote virt-v2v conversion server.
858 (Note that miniexpect is a separate library with its own upstream, so
860 if you patch miniexpect.c, then please make sure the changes get
861 reflected in miniexpect’s upstream too:
862 http://git.annexia.org/?p=miniexpect.git;a=summary)
863
865 MAINTAINER MAKEFILE TARGETS
866 These "make" targets probably won’t work and aren't useful unless you
867 are a libguestfs maintainer.
868 make maintainer-commit
870 This commits everything in the working directory with the commit
872 message "Version $(VERSION).". You must update configure.ac, clean and
873 rebuild first.
874 make maintainer-tag
876 This tags the current HEAD commit with the tag "v$(VERSION)" and one of
878 the messages:
879 Version $(VERSION) stable
881 Version $(VERSION) development
883 (See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for the difference
885 between a stable and development release.)
886 make maintainer-check-authors
888 Check that all authors (found in git commit messages) are included in
890 the generator/authors.ml file.
891 make maintainer-check-extra-dist
893 This rule must be run after "make dist" (so there is a tarball in the
895 working directory). It compares the contents of the tarball with the
896 contents of git to ensure that no files have been missed from
897 Makefile.am "EXTRA_DIST" rules.
898 make maintainer-upload-website
900 This is used by the software used to automate libguestfs releases to
902 copy the libguestfs website to another git repository before it is
903 uploaded to the web server.
904 MAKING A STABLE RELEASE
906 When we make a stable release, there are several steps documented here.
907 See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for general information
908 about the stable branch policy.
909 · Check "make && make check" works on at least:
911 Fedora (x86-64)
913 Debian (x86-64)
914 Ubuntu (x86-64)
915 Fedora (aarch64)
916 Fedora (ppc64)
917 Fedora (ppc64le)
918 · Check "./configure --without-libvirt" works.
919 · Finalize guestfs-release-notes.pod
921 · Push and pull from Zanata.
923 Run:
925 zanata push
927 to push the latest POT files to Zanata. Then run:
929 ./zanata-pull.sh
931 which is a wrapper to pull the latest translated *.po files.
933 · Consider updating gnulib to latest upstream version.
935 · Create new stable and development directories under
937 http://libguestfs.org/download.
938 · Edit website/index.html.in.
940 · Set the version (in configure.ac) to the new stable version, ie.
942 1.XX.0, and commit it:
943 ./localconfigure
945 make distclean -k
946 ./localconfigure
947 make && make dist
948 make maintainer-commit
949 make maintainer-tag
950 · Create the stable branch in git:
952 git branch stable-1.XX
954 git push origin stable-1.XX
955 · Do a full release of the stable branch.
957 · Set the version to the next development version and commit that.
959 Optionally do a full release of the development branch.
960
962 This section documents internal functions inside libguestfs and various
963 utilities. It is intended for libguestfs developers only.
964 This section is autogenerated from "/**" comments in source files,
966 which are marked up in POD format.
967 These functions are not publicly exported, and may change or be removed
969 at any time.
970 Subdirectory lib
972 File lib/actions-support.c
973 Helper functions for the actions code in lib/actions-*.c.
975 File lib/appliance-cpu.c
977 The appliance choice of CPU model.
979 Function "lib/appliance-cpu.c:guestfs_int_get_cpu_model"
981 const char *
983 guestfs_int_get_cpu_model (int kvm)
984 Return the right CPU model to use as the qemu "-cpu" parameter or its
986 equivalent in libvirt. This returns:
987 "host"
989 The literal string "host" means use "-cpu host".
990 some string
992 Some string such as "cortex-a57" means use "-cpu cortex-a57".
993 "NULL"
995 "NULL" means no "-cpu" option at all. Note returning "NULL" does
996 not indicate an error.
997 This is made unnecessarily hard and fragile because of two stupid
999 choices in QEMU:
1000 · The default for "qemu-system-aarch64 -M virt" is to emulate a
1002 "cortex-a15" (WTF?).
1003 · We don't know for sure if KVM will work, but "-cpu host" is broken
1005 with TCG, so we almost always pass a broken "-cpu" flag if KVM is
1006 semi-broken in any way.
1007 File lib/appliance-kcmdline.c
1009 The appliance kernel command line.
1011 Definition "lib/appliance-kcmdline.c:VALID_TERM"
1013 #define VALID_TERM
1015 Check that the $TERM environment variable is reasonable before we pass
1017 it through to the appliance.
1018 Function "lib/appliance-kcmdline.c:guestfs_int_appliance_command_line"
1020 char *
1022 guestfs_int_appliance_command_line (guestfs_h *g, const char *appliance_dev,
1023 int flags)
1024 Construct the Linux command line passed to the appliance. This is used
1026 by the "direct" and "libvirt" backends, and is simply located in this
1027 file because it's a convenient place for this common code.
1028 The "appliance_dev" parameter must be the full device name of the
1030 appliance disk and must have already been adjusted to take into account
1031 virtio-blk or virtio-scsi; eg "/dev/sdb".
1032 The "flags" parameter can contain the following flags logically or'd
1034 together (or 0):
1035 "APPLIANCE_COMMAND_LINE_IS_TCG"
1037 If we are launching a qemu TCG guest (ie. KVM is known to be
1038 disabled or unavailable). If you don't know, don't pass this flag.
1039 Note that this function returns a newly allocated buffer which must be
1041 freed by the caller.
1042 File lib/appliance-uefi.c
1044 Find the UEFI firmware needed to boot the appliance.
1046 See also lib/uefi.c (autogenerated file) containing the firmware file
1048 locations.
1049 Function "lib/appliance-uefi.c:guestfs_int_get_uefi"
1051 int
1053 guestfs_int_get_uefi (guestfs_h *g, char **code, char **vars, int *flags)
1054 Return the location of firmware needed to boot the appliance. This is
1056 aarch64 only currently, since that's the only architecture where UEFI
1057 is mandatory (and that only for RHEL).
1058 *code is initialized with the path to the read-only UEFI code file.
1060 *vars is initialized with the path to a copy of the UEFI vars file
1061 (which is cleaned up automatically on exit).
1062 If *code == *vars == "NULL" then no UEFI firmware is available.
1064 *code and *vars should be freed by the caller.
1066 If the function returns "-1" then there was a real error which should
1068 cause appliance building to fail (no UEFI firmware is not an error).
1069 See also v2v/utils.ml:find_uefi_firmware
1071 File lib/appliance.c
1073 This file deals with building the libguestfs appliance.
1075 Function "lib/appliance.c:guestfs_int_build_appliance"
1077 int
1079 guestfs_int_build_appliance (guestfs_h *g,
1080 char **kernel_rtn,
1081 char **initrd_rtn,
1082 char **appliance_rtn)
1083 Locate or build the appliance.
1085 This function locates or builds the appliance as necessary, handling
1087 the supermin appliance, caching of supermin-built appliances, or using
1088 either a fixed or old-style appliance.
1089 The return value is 0 = good, "-1" = error. Returned in
1091 "appliance.kernel" will be the name of the kernel to use,
1092 "appliance.initrd" the name of the initrd, "appliance.image" the name
1093 of the ext2 root filesystem. "appliance.image" can be "NULL", meaning
1094 that we are using an old-style (non-ext2) appliance. All three strings
1095 must be freed by the caller. However the referenced files themselves
1096 must not be deleted.
1097 The process is as follows:
1099 1. Look in "path" which contains a supermin appliance skeleton. If no
1101 element has this, skip straight to step 3.
1102 2. Call "supermin --build" to build the full appliance (if it needs to
1104 be rebuilt). If this is successful, return the full appliance.
1105 3. Check "path", looking for a fixed appliance. If one is found,
1107 return it.
1108 4. Check "path", looking for an old-style appliance. If one is found,
1110 return it.
1111 The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/
1113 and consists of up to four files:
1114 $TMPDIR/.guestfs-$UID/lock - the supermin lock file
1116 $TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
1117 $TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
1118 $TMPDIR/.guestfs-$UID/appliance.d/root - the appliance
1119 Multiple instances of libguestfs with the same UID may be racing to
1121 create an appliance. However (since supermin ≥ 5) supermin provides a
1122 --lock flag and atomic update of the appliance.d subdirectory.
1123 Function "lib/appliance.c:locate_or_build_appliance"
1125 static int
1127 locate_or_build_appliance (guestfs_h *g,
1128 struct appliance_files *appliance,
1129 const char *path)
1130 Check "path", looking for one of appliances: supermin appliance, fixed
1132 appliance or old-style appliance. If one of the fixed appliances is
1133 found, return it. If the supermin appliance skeleton is found, build
1134 and return appliance.
1135 Return values:
1137 1 = appliance is found, returns C<appliance>,
1139 0 = appliance not found,
1140 -1 = error which aborts the launch process.
1141 Function "lib/appliance.c:search_appliance"
1143 static int
1145 search_appliance (guestfs_h *g, struct appliance_files *appliance)
1146 Search elements of "g->path", returning the first "appliance" element
1148 which matches the predicate function "locate_or_build_appliance".
1149 Return values:
1151 1 = a path element matched, returns C<appliance>,
1153 0 = no path element matched,
1154 -1 = error which aborts the launch process.
1155 Function "lib/appliance.c:build_supermin_appliance"
1157 static int
1159 build_supermin_appliance (guestfs_h *g,
1160 const char *supermin_path,
1161 struct appliance_files *appliance)
1162 Build supermin appliance from "supermin_path" to $TMPDIR/.guestfs-$UID.
1164 Returns: 0 = built or "-1" = error (aborts launch).
1166 Function "lib/appliance.c:run_supermin_build"
1168 static int
1170 run_supermin_build (guestfs_h *g,
1171 const char *lockfile,
1172 const char *appliancedir,
1173 const char *supermin_path)
1174 Run "supermin --build" and tell it to generate the appliance.
1176 Function "lib/appliance.c:dir_contains_file"
1178 static int
1180 dir_contains_file (guestfs_h *g, const char *dir, const char *file)
1181 Returns true iff "file" is contained in "dir".
1183 Function "lib/appliance.c:dir_contains_files"
1185 static int
1187 dir_contains_files (guestfs_h *g, const char *dir, ...)
1188 Returns true iff every listed file is contained in "dir".
1190 File lib/command.c
1192 A wrapper for running external commands, loosely based on libvirt's
1194 "virCommand" interface.
1195 In outline to use this interface you must:
1197 1. Create a new command handle:
1199 struct command *cmd;
1201 cmd = guestfs_int_new_command (g);
1202 2. Either add arguments:
1204 guestfs_int_cmd_add_arg (cmd, "qemu-img");
1206 guestfs_int_cmd_add_arg (cmd, "info");
1207 guestfs_int_cmd_add_arg (cmd, filename);
1208 (NB: You don't need to add a "NULL" argument at the end.)
1210 3. Or construct a command using a mix of quoted and unquoted strings.
1212 (This is useful for system(3)/"popen("r")"-style shell commands,
1213 with the added safety of allowing args to be quoted properly).
1214 guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
1216 guestfs_int_cmd_add_string_quoted (cmd, filename);
1217 4. Set various flags, such as whether you want to capture errors in
1219 the regular libguestfs error log.
1220 5. Run the command. This is what does the fork(2) call, optionally
1222 loops over the output, and then does a waitpid(3) and returns the
1223 exit status of the command.
1224 r = guestfs_int_cmd_run (cmd);
1226 if (r == -1)
1227 // error
1228 // else test r using the WIF* functions
1229 6. Close the handle:
1231 guestfs_int_cmd_close (cmd);
1233 (or use "CLEANUP_CMD_CLOSE").
1235 Function "lib/command.c:guestfs_int_new_command"
1237 struct command *
1239 guestfs_int_new_command (guestfs_h *g)
1240 Create a new command handle.
1242 Function "lib/command.c:guestfs_int_cmd_add_arg"
1244 void
1246 guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)
1247 Add single arg (for "execv"-style command execution).
1249 Function "lib/command.c:guestfs_int_cmd_add_arg_format"
1251 void
1253 guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)
1254 Add single arg (for "execv"-style command execution) using a
1256 printf(3)-style format string.
1257 Function "lib/command.c:guestfs_int_cmd_add_string_unquoted"
1259 void
1261 guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)
1262 Add a string (for system(3)-style command execution).
1264 This variant adds the strings without quoting them, which is dangerous
1266 if the string contains untrusted content.
1267 Function "lib/command.c:guestfs_int_cmd_add_string_quoted"
1269 void
1271 guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)
1272 Add a string (for system(3)-style command execution).
1274 The string is enclosed in double quotes, with any special characters
1276 within the string which need escaping done. This is used to add a
1277 single argument to a system(3)-style command string.
1278 Function "lib/command.c:guestfs_int_cmd_set_stdout_callback"
1280 void
1282 guestfs_int_cmd_set_stdout_callback (struct command *cmd,
1283 cmd_stdout_callback stdout_callback,
1284 void *stdout_data, unsigned flags)
1285 Set a callback which will capture stdout.
1287 If flags contains "CMD_STDOUT_FLAG_LINE_BUFFER" (the default), then the
1289 callback is called line by line on the output. If there is a trailing
1290 "\n" then it is automatically removed before the callback is called.
1291 The line buffer is "\0"-terminated.
1292 If flags contains "CMD_STDOUT_FLAG_UNBUFFERED", then buffers are passed
1294 to the callback as it is received from the command. Note in this case
1295 the buffer is not "\0"-terminated, so you need to may attention to the
1296 length field in the callback.
1297 If flags contains "CMD_STDOUT_FLAG_WHOLE_BUFFER", then the callback is
1299 called exactly once, with the entire buffer. Note in this case the
1300 buffer is not "\0"-terminated, so you need to may attention to the
1301 length field in the callback.
1302 Function "lib/command.c:guestfs_int_cmd_set_stderr_to_stdout"
1304 void
1306 guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)
1307 Equivalent to adding "2>&1" to the end of the command. This is
1309 incompatible with the "capture_errors" flag, because it doesn't make
1310 sense to combine them.
1311 Function "lib/command.c:guestfs_int_cmd_clear_capture_errors"
1313 void
1315 guestfs_int_cmd_clear_capture_errors (struct command *cmd)
1316 Clear the "capture_errors" flag. This means that any errors will go to
1318 stderr, instead of being captured in the event log, and that is usually
1319 undesirable.
1320 Function "lib/command.c:guestfs_int_cmd_clear_close_files"
1322 void
1324 guestfs_int_cmd_clear_close_files (struct command *cmd)
1325 Don't close file descriptors after the fork.
1327 XXX Should allow single fds to be sent to child process.
1329 Function "lib/command.c:guestfs_int_cmd_set_child_callback"
1331 void
1333 guestfs_int_cmd_set_child_callback (struct command *cmd,
1334 cmd_child_callback child_callback,
1335 void *data)
1336 Set a function to be executed in the child, right before the execution.
1338 Can be used to setup the child, for example changing its current
1339 directory.
1340 Function "lib/command.c:guestfs_int_cmd_set_child_rlimit"
1342 void
1344 guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)
1345 Set up child rlimits, in case the process we are running could consume
1347 lots of space or time.
1348 Function "lib/command.c:finish_command"
1350 static void
1352 finish_command (struct command *cmd)
1353 Finish off the command by either "NULL"-terminating the argv array or
1355 adding a terminating "\0" to the string, or die with an internal error
1356 if no command has been added.
1357 Function "lib/command.c:loop"
1359 static int
1361 loop (struct command *cmd)
1362 The loop which reads errors and output and directs it either to the log
1364 or to the stdout callback as appropriate.
1365 Function "lib/command.c:guestfs_int_cmd_run"
1367 int
1369 guestfs_int_cmd_run (struct command *cmd)
1370 Fork, run the command, loop over the output, and waitpid.
1372 Returns the exit status. Test it using "WIF*" macros.
1374 On error: Calls "error" and returns "-1".
1376 Function "lib/command.c:guestfs_int_cmd_pipe_run"
1378 int
1380 guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)
1381 Fork and run the command, but don't wait. Roughly equivalent to
1383 "popen (..., "r"|"w")".
1384 Returns the file descriptor of the pipe, connected to stdout ("r") or
1386 stdin ("w") of the child process.
1387 After reading/writing to this pipe, call "guestfs_int_cmd_pipe_wait" to
1389 wait for the status of the child.
1390 Errors from the subcommand cannot be captured to the error log using
1392 this interface. Instead the caller should call
1393 "guestfs_int_cmd_get_pipe_errors" (after "guestfs_int_cmd_pipe_wait"
1394 returns an error).
1395 Function "lib/command.c:guestfs_int_cmd_pipe_wait"
1397 int
1399 guestfs_int_cmd_pipe_wait (struct command *cmd)
1400 Wait for a subprocess created by "guestfs_int_cmd_pipe_run" to finish.
1402 On error (eg. failed syscall) this returns "-1" and sets the error. If
1403 the subcommand fails, then use "WIF*" macros to check this, and call
1404 "guestfs_int_cmd_get_pipe_errors" to read the error messages printed by
1405 the child.
1406 Function "lib/command.c:guestfs_int_cmd_get_pipe_errors"
1408 char *
1410 guestfs_int_cmd_get_pipe_errors (struct command *cmd)
1411 Read the error messages printed by the child. The caller must free the
1413 returned buffer after use.
1414 Function "lib/command.c:guestfs_int_cmd_close"
1416 void
1418 guestfs_int_cmd_close (struct command *cmd)
1419 Close the "cmd" object and free all resources.
1421 Function "lib/command.c:process_line_buffer"
1423 static void
1425 process_line_buffer (struct command *cmd, int closed)
1426 Deal with buffering stdout for the callback.
1428 File lib/conn-socket.c
1430 This file handles connections to the child process where this is done
1432 over regular POSIX sockets.
1433 Function "lib/conn-socket.c:handle_log_message"
1435 static int
1437 handle_log_message (guestfs_h *g,
1438 struct connection_socket *conn)
1439 This is called if "conn->console_sock" becomes ready to read while we
1441 are doing one of the connection operations above. It reads and deals
1442 with the log message.
1443 Returns:
1445 1 log message(s) were handled successfully
1447 0 connection to appliance closed
1449 "-1"
1451 error
1452 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_listening"
1454 struct connection *
1456 guestfs_int_new_conn_socket_listening (guestfs_h *g,
1457 int daemon_accept_sock,
1458 int console_sock)
1459 Create a new socket connection, listening.
1461 Note that it's OK for "console_sock" to be passed as "-1", meaning
1463 there's no console available for this appliance.
1464 After calling this, "daemon_accept_sock" is owned by the connection,
1466 and will be closed properly either in "accept_connection" or
1467 "free_connection".
1468 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_connected"
1470 struct connection *
1472 guestfs_int_new_conn_socket_connected (guestfs_h *g,
1473 int daemon_sock,
1474 int console_sock)
1475 Create a new socket connection, connected.
1477 As above, but the caller passes us a connected "daemon_sock" and
1479 promises not to call "accept_connection".
1480 File lib/create.c
1482 APIs for creating empty disks.
1484 Mostly this consists of wrappers around the qemu-img(1) program.
1486 Definition "lib/create.c:VALID_FORMAT"
1488 #define VALID_FORMAT
1490 Check for valid backing format. Allow any "^[[:alnum]]+$" (in C
1492 locale), but limit the length to something reasonable.
1493 File lib/drives.c
1495 Drives added are stored in an array in the handle. Code here manages
1497 that array and the individual "struct drive" data.
1498 Function "lib/drives.c:create_overlay"
1500 static int
1502 create_overlay (guestfs_h *g, struct drive *drv)
1503 For readonly drives, create an overlay to protect the original drive
1505 content. Note we never need to clean up these overlays since they are
1506 created in the temporary directory and deleted when the handle is
1507 closed.
1508 Function "lib/drives.c:create_drive_file"
1510 static struct drive *
1512 create_drive_file (guestfs_h *g,
1513 const struct drive_create_data *data)
1514 Create and free the "struct drive".
1516 Function "lib/drives.c:create_drive_dev_null"
1518 static struct drive *
1520 create_drive_dev_null (guestfs_h *g,
1521 struct drive_create_data *data)
1522 Create the special /dev/null drive.
1524 Traditionally you have been able to use /dev/null as a filename, as
1526 many times as you like. Ancient KVM (RHEL 5) cannot handle adding
1527 /dev/null readonly. qemu 1.2 + virtio-scsi segfaults when you use any
1528 zero-sized file including /dev/null.
1529 Because of these problems, we replace /dev/null with a non-zero sized
1531 temporary file. This shouldn't make any difference since users are not
1532 supposed to try and access a null drive.
1533 Function "lib/drives.c:drive_to_string"
1535 static char *
1537 drive_to_string (guestfs_h *g, const struct drive *drv)
1538 Convert a "struct drive" to a string for debugging. The caller must
1540 free this string.
1541 Function "lib/drives.c:add_drive_to_handle_at"
1543 static void
1545 add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)
1546 Add "struct drive" to the "g->drives" vector at the given index
1548 "drv_index". If the array isn't large enough it is reallocated. The
1549 index must not contain a drive already.
1550 Function "lib/drives.c:add_drive_to_handle"
1552 static void
1554 add_drive_to_handle (guestfs_h *g, struct drive *d)
1555 Add struct drive to the end of the "g->drives" vector in the handle.
1557 Function "lib/drives.c:guestfs_int_add_dummy_appliance_drive"
1559 void
1561 guestfs_int_add_dummy_appliance_drive (guestfs_h *g)
1562 Called during launch to add a dummy slot to "g->drives".
1564 Function "lib/drives.c:guestfs_int_free_drives"
1566 void
1568 guestfs_int_free_drives (guestfs_h *g)
1569 Free up all the drives in the handle.
1571 Definition "lib/drives.c:VALID_FORMAT_IFACE"
1573 #define VALID_FORMAT_IFACE
1575 Check string parameter matches regular expression "^[-_[:alnum:]]+$"
1577 (in C locale).
1578 Definition "lib/drives.c:VALID_DISK_LABEL"
1580 #define VALID_DISK_LABEL
1582 Check the disk label is reasonable. It can't contain certain
1584 characters, eg. '/', ','. However be stricter here and ensure it's
1585 just alphabetic and ≤ 20 characters in length.
1586 Definition "lib/drives.c:VALID_HOSTNAME"
1588 #define VALID_HOSTNAME
1590 Check the server hostname is reasonable.
1592 Function "lib/drives.c:valid_port"
1594 static int
1596 valid_port (int port)
1597 Check the port number is reasonable.
1599 Function "lib/drives.c:guestfs_impl_remove_drive"
1601 int
1603 guestfs_impl_remove_drive (guestfs_h *g, const char *label)
1604 This function implements "guestfs_remove_drive" in guestfs(3).
1606 Depending on whether we are hotplugging or not, this function does
1608 slightly different things: If not hotplugging, then the drive just
1609 disappears as if it had never been added. The later drives "move up"
1610 to fill the space. When hotplugging we have to do some complex stuff,
1611 and we usually end up leaving an empty ("NULL") slot in the "g->drives"
1612 vector.
1613 Function "lib/drives.c:guestfs_int_checkpoint_drives"
1615 size_t
1617 guestfs_int_checkpoint_drives (guestfs_h *g)
1618 Checkpoint and roll back drives, so that groups of drives can be added
1620 atomicly. Only used by "guestfs_add_domain" in guestfs(3).
1621 Function "lib/drives.c:guestfs_impl_debug_drives"
1623 char **
1625 guestfs_impl_debug_drives (guestfs_h *g)
1626 Internal function to return the list of drives.
1628 File lib/errors.c
1630 This file handles errors, and also debug, trace and warning messages.
1632 Errors in libguestfs API calls are handled by setting an error message
1634 and optional errno in the handle. The caller has the choice of testing
1635 API calls to find out if they failed and then querying the last error
1636 from the handle, and/or getting a callback.
1637 From the point of view of the library source, generally you should use
1639 the "error" or "perrorf" macros along error paths, eg:
1640 if (something_bad) {
1642 error (g, "something bad happened");
1643 return -1;
1644 }
1645 Make sure to call the "error" or "perrorf" macro exactly once along
1647 each error path, since the handle can only store a single error and the
1648 previous error will be overwritten.
1649 Function "lib/errors.c:guestfs_int_warning"
1651 void
1653 guestfs_int_warning (guestfs_h *g, const char *fs, ...)
1654 Print a warning.
1656 Code should not call this function directly. Use the
1658 "warning (g, fs, ...)" macro.
1659 Warnings are printed unconditionally. We try to make these rare:
1661 Generally speaking, a warning should either be an error, or if it's not
1662 important for end users then it should be a debug message.
1663 Function "lib/errors.c:guestfs_int_debug"
1665 void
1667 guestfs_int_debug (guestfs_h *g, const char *fs, ...)
1668 Print a debug message.
1670 Code should not call this function directly. To add debug messages in
1672 the library, use the "debug (g, fs, ...)" macro. The macro checks if
1673 "g->verbose" is false and avoids the function call, meaning the macro
1674 is more efficient.
1675 Function "lib/errors.c:guestfs_int_trace"
1677 void
1679 guestfs_int_trace (guestfs_h *g, const char *fs, ...)
1680 Print a trace message.
1682 Do not call this function. All calls are generated automatically.
1684 Function "lib/errors.c:guestfs_int_error_errno"
1686 void
1688 guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)
1689 Set the last error and errno in the handle, and optionally raise the
1691 error callback if one is defined.
1692 If you don't need to set errno, use the "error (g, fs, ...)" macro
1694 instead of calling this directly. If you need to set errno then there
1695 is no macro wrapper, so calling this function directly is fine.
1696 Function "lib/errors.c:guestfs_int_perrorf"
1698 void
1700 guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)
1701 Similar to perror(3), but it sets the last error in the handle, raises
1703 the error callback if one is defined, and supports format strings.
1704 You should probably use the "perrorf (g, fs, ...)" macro instead of
1706 calling this directly.
1707 Function "lib/errors.c:guestfs_int_launch_failed_error"
1709 void
1711 guestfs_int_launch_failed_error (guestfs_h *g)
1712 Raise a launch failed error in a standard format.
1714 Since this is the most common error seen by people who have
1716 installation problems, buggy qemu, etc, and since no one reads the FAQ,
1717 describe in this error message what resources are available to debug
1718 launch problems.
1719 Function "lib/errors.c:guestfs_int_unexpected_close_error"
1721 void
1723 guestfs_int_unexpected_close_error (guestfs_h *g)
1724 Raise an error if the appliance unexpectedly crashes after launch.
1726 Function "lib/errors.c:guestfs_int_launch_timeout"
1728 void
1730 guestfs_int_launch_timeout (guestfs_h *g)
1731 Raise an error if the appliance hangs during launch.
1733 Function "lib/errors.c:guestfs_int_external_command_failed"
1735 void
1737 guestfs_int_external_command_failed (guestfs_h *g, int status,
1738 const char *cmd_name, const char *extra)
1739 Raise an error if an external command fails.
1741 "status" is the status code of the command (eg. returned from
1743 waitpid(2) or system(3)). This function turns the status code into an
1744 explanatory string.
1745 File lib/events.c
1747 Function "lib/events.c:replace_old_style_event_callback"
1749 static void
1751 replace_old_style_event_callback (guestfs_h *g,
1752 guestfs_event_callback cb,
1753 uint64_t event_bitmask,
1754 void *opaque,
1755 void *opaque2)
1756 Emulate old-style callback API.
1758 There were no event handles, so multiple callbacks per event were not
1760 supported. Calling the same "guestfs_set_*_callback" function would
1761 replace the existing event. Calling it with "cb == NULL" meant that
1762 the caller wanted to remove the callback.
1763 File lib/guestfs-internal-all.h
1765 This header contains definitions which are shared by all parts of
1767 libguestfs, ie. the daemon, the library, language bindings and virt
1768 tools (ie. all C code).
1769 If you need a definition used by only the library, put it in
1771 lib/guestfs-internal.h instead.
1772 If a definition is used by only a single tool, it should not be in any
1774 shared header file at all.
1775 File lib/guestfs-internal.h
1777 This header file is included in the libguestfs library (lib/) only.
1779 See also lib/guestfs-internal-all.h.
1781 Structure "lib/guestfs-internal.h:event"
1783 struct event {
1785 uint64_t event_bitmask;
1786 guestfs_event_callback cb;
1787 void *opaque;
1788 /* opaque2 is not exposed through the API, but is used internally to
1790 * emulate the old-style callback API.
1791 */
1792 void *opaque2;
1793 };
1794 This struct is used to maintain a list of events registered against the
1796 handle. See "g->events" in the handle.
1797 Structure "lib/guestfs-internal.h:drive"
1799 struct drive {
1801 /* Original source of the drive, eg. file:..., http:... */
1802 struct drive_source src;
1803 /* If the drive is readonly, then an overlay [a local file] is
1805 * created before launch to protect the original drive content, and
1806 * the filename is stored here. Backends should open this file if
1807 * it is non-NULL, else consult the original source above.
1808 *
1809 * Note that the overlay is in a backend-specific format, probably
1810 * different from the source format. eg. qcow2, UML COW.
1811 */
1812 char *overlay;
1813 /* Various per-drive flags. */
1815 bool readonly;
1816 char *iface;
1817 char *name;
1818 char *disk_label;
1819 char *cachemode;
1820 enum discard discard;
1821 bool copyonread;
1822 };
1823 There is one "struct drive" per drive, including hot-plugged drives.
1825 Structure "lib/guestfs-internal.h:backend_ops"
1827 struct backend_ops {
1829 /* Size (in bytes) of the per-handle data structure needed by this
1830 * backend. The data pointer is allocated and freed by libguestfs
1831 * and passed to the functions in the 'void *data' parameter.
1832 * Inside the data structure is opaque to libguestfs. Any strings
1833 * etc pointed to by it must be freed by the backend during
1834 * shutdown.
1835 */
1836 size_t data_size;
1837 /* Create a COW overlay on top of a drive. This must be a local
1839 * file, created in the temporary directory. This is called when
1840 * the drive is added to the handle.
1841 */
1842 char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);
1843 /* Launch and shut down. */
1845 int (*launch) (guestfs_h *g, void *data, const char *arg);
1846 int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);
1847 /* Miscellaneous. */
1849 int (*get_pid) (guestfs_h *g, void *data);
1850 int (*max_disks) (guestfs_h *g, void *data);
1851 /* Hotplugging drives. */
1853 int (*hot_add_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1854 int (*hot_remove_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1855 };
1856 Backend operations.
1858 Each backend (eg. libvirt, direct) defines some functions which get run
1860 at various places in the handle lifecycle (eg. at launch, shutdown).
1861 The backend defines this struct pointing to those functions.
1862 Structure "lib/guestfs-internal.h:connection"
1864 struct connection {
1866 const struct connection_ops *ops;
1867 /* In the real struct, private data used by each connection module
1869 * follows here.
1870 */
1871 };
1872 Connection module.
1874 A "connection" represents the appliance console connection plus the
1876 daemon connection. It hides the underlying representation (POSIX
1877 sockets, "virStreamPtr").
1878 Structure "lib/guestfs-internal.h:cached_feature"
1880 struct cached_feature {
1882 char *group;
1883 int result;
1884 };
1885 Cache of queried features.
1887 Used to cache the appliance features (see lib/available.c).
1889 Structure "lib/guestfs-internal.h:guestfs_h"
1891 struct guestfs_h {
1893 struct guestfs_h *next; /* Linked list of open handles. */
1894 enum state state; /* See the state machine diagram in guestfs(3)*/
1895 /* Lock acquired when entering any public guestfs_* function to
1897 * protect the handle.
1898 */
1899 gl_recursive_lock_define (, lock);
1900 /**** Configuration of the handle. ****/
1902 bool verbose; /* Debugging. */
1903 bool trace; /* Trace calls. */
1904 bool autosync; /* Autosync. */
1905 bool direct_mode; /* Direct mode. */
1906 bool recovery_proc; /* Create a recovery process. */
1907 bool enable_network; /* Enable the network. */
1908 bool selinux; /* selinux enabled? */
1909 bool pgroup; /* Create process group for children? */
1910 bool close_on_exit; /* Is this handle on the atexit list? */
1911 int smp; /* If > 1, -smp flag passed to hv. */
1913 int memsize; /* Size of RAM (megabytes). */
1914 char *path; /* Path to the appliance. */
1916 char *hv; /* Hypervisor (HV) binary. */
1917 char *append; /* Append to kernel command line. */
1918 struct hv_param *hv_params; /* Extra hv parameters. */
1920 char *program; /* Program name. */
1922 char *identifier; /* Handle identifier. */
1923 /* Array of drives added by add-drive* APIs.
1925 *
1926 * Before launch this list can be empty or contain some drives.
1927 *
1928 * During launch, a dummy slot may be added which represents the
1929 * slot taken up by the appliance drive.
1930 *
1931 * When hotplugging is supported by the backend, drives can be
1932 * added to the end of this list after launch. Also hot-removing a
1933 * drive causes a NULL slot to appear in the list.
1934 *
1935 * During shutdown, this list is deleted, so that each launch gets a
1936 * fresh set of drives (however callers: don't do this, create a new
1937 * handle each time).
1938 *
1939 * Always use ITER_DRIVES macro to iterate over this list!
1940 */
1941 struct drive **drives;
1942 size_t nr_drives;
1943 #define ITER_DRIVES(g,i,drv) \
1945 for (i = 0; i < (g)->nr_drives; ++i) \
1946 if (((drv) = (g)->drives[i]) != NULL)
1947 /* Backend. NB: Use guestfs_int_set_backend to change the backend. */
1949 char *backend; /* The full string, always non-NULL. */
1950 char *backend_arg; /* Pointer to the argument part. */
1951 const struct backend_ops *backend_ops;
1952 void *backend_data; /* Per-handle data. */
1953 char **backend_settings; /* Backend settings (can be NULL). */
1954 /**** Runtime information. ****/
1956 /* Temporary and cache directories. */
1957 /* The actual temporary directory - this is not created with the
1958 * handle, you have to call guestfs_int_lazy_make_tmpdir.
1959 */
1960 char *tmpdir;
1961 char *sockdir;
1962 /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
1963 char *env_tmpdir; /* $TMPDIR (NULL if not set) */
1964 char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/
1965 char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
1966 char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */
1967 /* Error handler, plus stack of old error handlers. */
1969 gl_tls_key_t error_data;
1970 /* Linked list of error_data structures allocated for this handle,
1972 * plus a mutex to protect the linked list.
1973 */
1974 gl_lock_define (, error_data_list_lock);
1975 struct error_data *error_data_list;
1976 /* Out of memory error handler. */
1978 guestfs_abort_cb abort_cb;
1979 /* Events. */
1981 struct event *events;
1982 size_t nr_events;
1983 /* Private data area. */
1985 struct hash_table *pda;
1986 struct pda_entry *pda_next;
1987 /* User cancelled transfer. Not signal-atomic, but it doesn't
1989 * matter for this case because we only care if it is != 0.
1990 */
1991 int user_cancel;
1992 struct timeval launch_t; /* The time that we called guestfs_launch. */
1994 /* Used by bindtests. */
1996 FILE *test_fp;
1997 /* Used to generate unique numbers, eg for temp files. To use this,
1999 * '++g->unique'. Note these are only unique per-handle, not
2000 * globally unique.
2001 */
2002 int unique;
2003 /*** Protocol. ***/
2005 struct connection *conn; /* Connection to appliance. */
2006 int msg_next_serial;
2007 #if HAVE_FUSE
2009 /**** Used by the mount-local APIs. ****/
2010 char *localmountpoint;
2011 struct fuse *fuse; /* FUSE handle. */
2012 int ml_dir_cache_timeout; /* Directory cache timeout. */
2013 Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
2014 int ml_read_only; /* If mounted read-only. */
2015 int ml_debug_calls; /* Extra debug info on each FUSE call. */
2016 #endif
2017 #ifdef HAVE_LIBVIRT_BACKEND
2019 /* Used by lib/libvirt-auth.c. */
2020 #define NR_CREDENTIAL_TYPES 9
2021 unsigned int nr_supported_credentials;
2022 int supported_credentials[NR_CREDENTIAL_TYPES];
2023 const char *saved_libvirt_uri; /* Doesn't need to be freed. */
2024 bool wrapper_warning_done;
2025 unsigned int nr_requested_credentials;
2026 virConnectCredentialPtr requested_credentials;
2027 #endif
2028 /* Cached features. */
2030 struct cached_feature *features;
2031 size_t nr_features;
2032 /* Used by lib/info.c. -1 = not tested or error; else 0 or 1. */
2034 int qemu_img_supports_U_option;
2035 };
2036 The libguestfs handle.
2038 Structure "lib/guestfs-internal.h:version"
2040 struct version {
2042 int v_major;
2043 int v_minor;
2044 int v_micro;
2045 };
2046 Used for storing major.minor.micro version numbers. See lib/version.c
2048 for more information.
2049 File lib/guid.c
2051 Function "lib/guid.c:guestfs_int_validate_guid"
2053 int
2055 guestfs_int_validate_guid (const char *str)
2056 Check whether a string supposed to contain a GUID actually contains it.
2058 It can recognize strings either as
2059 "{21EC2020-3AEA-1069-A2DD-08002B30309D}" or
2060 "21EC2020-3AEA-1069-A2DD-08002B30309D".
2061 File lib/handle.c
2063 This file deals with the "guestfs_h" handle, creating it, closing it,
2065 and initializing/setting/getting fields.
2066 Function "lib/handle.c:init_libguestfs"
2068 static void
2070 init_libguestfs (void)
2071 No initialization is required by libguestfs, but libvirt and libxml2
2073 require initialization if they might be called from multiple threads.
2074 Hence this constructor function which is called when libguestfs is
2075 first loaded.
2076 Function "lib/handle.c:shutdown_backend"
2078 static int
2080 shutdown_backend (guestfs_h *g, int check_for_errors)
2081 This function is the common path for shutting down the backend qemu
2083 process.
2084 "guestfs_shutdown" calls "shutdown_backend" with "check_for_errors=1".
2086 "guestfs_close" calls "shutdown_backend" with "check_for_errors=0".
2087 "check_for_errors" is a hint to the backend about whether we care about
2089 errors or not. In the libvirt case it can be used to optimize the
2090 shutdown for speed when we don't care.
2091 Function "lib/handle.c:close_handles"
2093 static void
2095 close_handles (void)
2096 Close all open handles (called from atexit(3)).
2098 Function "lib/handle.c:guestfs_int_get_backend_setting_bool"
2100 int
2102 guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)
2103 This is a convenience function, but we might consider exporting it as
2105 an API in future.
2106 File lib/info.c
2108 Function "lib/info.c:qemu_img_supports_U_option"
2110 static int
2112 qemu_img_supports_U_option (guestfs_h *g)
2113 Test if the qemu-img info command supports the "-U" option to disable
2115 locking. The result is memoized in the handle.
2116 Note this option was added in qemu 2.11. We can remove this test when
2118 we can assume everyone is using qemu >= 2.11.
2119 File lib/inspect-icon.c
2121 Function "lib/inspect-icon.c:guestfs_int_download_to_tmp"
2123 char *
2125 guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
2126 const char *extension,
2127 uint64_t max_size)
2128 Download a guest file to a local temporary file.
2130 The name of the temporary (downloaded) file is returned. The caller
2132 must free the pointer, but does not need to delete the temporary file.
2133 It will be deleted when the handle is closed.
2134 The name of the temporary file is randomly generated, but an extension
2136 can be specified using "extension" (or pass "NULL" for none).
2137 Refuse to download the guest file if it is larger than "max_size". On
2139 this and other errors, "NULL" is returned.
2140 File lib/launch-direct.c
2142 Implementation of the "direct" backend.
2144 For more details see "BACKENDS" in guestfs(3).
2146 Function "lib/launch-direct.c:add_drive_standard_params"
2148 static int
2150 add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
2151 struct qemuopts *qopts,
2152 size_t i, struct drive *drv)
2153 Add the standard elements of the "-drive" parameter.
2155 File lib/launch-libvirt.c
2157 Function "lib/launch-libvirt.c:get_source_format_or_autodetect"
2159 static char *
2161 get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)
2162 Return "drv->src.format", but if it is "NULL", autodetect the format.
2164 libvirt has disabled the feature of detecting the disk format, unless
2166 the administrator sets "allow_disk_format_probing=1" in
2167 /etc/libvirt/qemu.conf. There is no way to detect if this option is
2168 set, so we have to do format detection here using "qemu-img" and pass
2169 that to libvirt.
2170 This can still be a security issue, so in most cases it is recommended
2172 the users pass the format to libguestfs which will faithfully pass that
2173 straight through to libvirt without doing autodetection.
2174 Caller must free the returned string. On error this function sets the
2176 error in the handle and returns "NULL".
2177 Function "lib/launch-libvirt.c:make_qcow2_overlay"
2179 static char *
2181 make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
2182 const char *format)
2183 Create a qcow2 format overlay, with the given "backing_drive" (file).
2185 The "format" parameter is the backing file format. The "format"
2186 parameter can be NULL, in this case the backing format will be
2187 determined automatically. This is used to create the appliance
2188 overlay, and also for read-only drives.
2189 File lib/launch.c
2191 This file implements "guestfs_launch" in guestfs(3).
2193 Most of the work is done by the backends (see "BACKEND" in guestfs(3)),
2195 which are implemented in lib/launch-direct.c, lib/launch-libvirt.c etc,
2196 so this file mostly passes calls through to the current backend.
2197 Function "lib/launch.c:guestfs_int_launch_send_progress"
2199 void
2201 guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)
2202 This function sends a launch progress message.
2204 Launching the appliance generates approximate progress messages.
2206 Currently these are defined as follows:
2207 0 / 12: launch clock starts
2209 3 / 12: appliance created
2210 6 / 12: detected that guest kernel started
2211 9 / 12: detected that /init script is running
2212 12 / 12: launch completed successfully
2213 Notes:
2215 1. This is not a documented ABI and the behaviour may be changed or
2217 removed in future.
2218 2. Messages are only sent if more than 5 seconds has elapsed since the
2220 launch clock started.
2221 3. There is a hack in lib/proto.c to make this work.
2223 Function "lib/launch.c:guestfs_int_timeval_diff"
2225 int64_t
2227 guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)
2228 Compute "y - x" and return the result in milliseconds.
2230 Approximately the same as this code:
2232 http://www.mpp.mpg.de/~huber/util/timevaldiff.c
2233 Function "lib/launch.c:guestfs_int_unblock_sigterm"
2235 void
2237 guestfs_int_unblock_sigterm (void)
2238 Unblock the "SIGTERM" signal. Call this after fork(2) so that the
2240 parent process can send "SIGTERM" to the child process in case
2241 "SIGTERM" is blocked. See https://bugzilla.redhat.com/1460338.
2242 Function "lib/launch.c:guestfs_impl_max_disks"
2244 int
2246 guestfs_impl_max_disks (guestfs_h *g)
2247 Returns the maximum number of disks allowed to be added to the backend
2249 (backend dependent).
2250 Function "lib/launch.c:guestfs_impl_wait_ready"
2252 int
2254 guestfs_impl_wait_ready (guestfs_h *g)
2255 Implementation of "guestfs_wait_ready" in guestfs(3). You had to call
2257 this function after launch in versions ≤ 1.0.70, but it is now an
2258 (almost) no-op.
2259 Function "lib/launch.c:guestfs_int_create_socketname"
2261 int
2263 guestfs_int_create_socketname (guestfs_h *g, const char *filename,
2264 char (*sockpath)[UNIX_PATH_MAX])
2265 Create the path for a socket with the selected filename in the tmpdir.
2267 Function "lib/launch.c:guestfs_int_register_backend"
2269 void
2271 guestfs_int_register_backend (const char *name, const struct backend_ops *ops)
2272 When the library is loaded, each backend calls this function to
2274 register itself in a global list.
2275 Function "lib/launch.c:guestfs_int_set_backend"
2277 int
2279 guestfs_int_set_backend (guestfs_h *g, const char *method)
2280 Implementation of "guestfs_set_backend" in guestfs(3).
2282 · Callers must ensure this is only called in the config state.
2284 · This shouldn't call "error" since it may be called early in handle
2286 initialization. It can return an error code however.
2287 File lib/private-data.c
2289 Implement a private data area where libguestfs C API users can attach
2291 arbitrary pieces of data to a "guestfs_h" handle.
2292 For more information see "PRIVATE DATA AREA" in guestfs(3).
2294 Language bindings do not generally expose this, largely because in non-
2296 C languages it is easy to associate data with handles in other ways
2297 (using hash tables or maps).
2298 Structure "lib/private-data.c:pda_entry"
2300 struct pda_entry {
2302 char *key; /* key */
2303 void *data; /* opaque user data pointer */
2304 };
2305 The private data area is internally stored as a gnulib hash table
2307 containing "pda_entry" structures.
2308 Note the private data area is allocated lazily, since the vast majority
2310 of callers will never use it. This means "g->pda" is likely to be
2311 "NULL".
2312 File lib/proto.c
2314 This is the code used to send and receive RPC messages and (for certain
2316 types of message) to perform file transfers. This code is driven from
2317 the generated actions (lib/actions-*.c). There are five different
2318 cases to consider:
2319 1. A non-daemon function (eg. "guestfs_set_verbose" in guestfs(3)).
2321 There is no RPC involved at all, it's all handled inside the
2322 library.
2323 2. A simple RPC (eg. "guestfs_mount" in guestfs(3)). We write the
2325 request, then read the reply. The sequence of calls is:
2326 guestfs_int_send
2328 guestfs_int_recv
2329 3. An RPC with "FileIn" parameters (eg. "guestfs_upload" in
2331 guestfs(3)). We write the request, then write the file(s), then
2332 read the reply. The sequence of calls is:
2333 guestfs_int_send
2335 guestfs_int_send_file (possibly multiple times)
2336 guestfs_int_recv
2337 4. An RPC with "FileOut" parameters (eg. "guestfs_download" in
2339 guestfs(3)). We write the request, then read the reply, then read
2340 the file(s). The sequence of calls is:
2341 guestfs_int_send
2343 guestfs_int_recv
2344 guestfs_int_recv_file (possibly multiple times)
2345 5. Both "FileIn" and "FileOut" parameters. There are no calls like
2347 this in the current API, but they would be implemented as a
2348 combination of cases 3 and 4.
2349 All read/write/etc operations are performed using the current
2351 connection module ("g->conn"). During operations the connection module
2352 transparently handles log messages that appear on the console.
2353 Function "lib/proto.c:child_cleanup"
2355 static void
2357 child_cleanup (guestfs_h *g)
2358 This is called if we detect EOF, ie. qemu died.
2360 Function "lib/proto.c:guestfs_int_progress_message_callback"
2362 void
2364 guestfs_int_progress_message_callback (guestfs_h *g,
2365 const guestfs_progress *message)
2366 Convenient wrapper to generate a progress message callback.
2368 Function "lib/proto.c:guestfs_int_log_message_callback"
2370 void
2372 guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)
2373 Connection modules call us back here when they get a log message.
2375 Function "lib/proto.c:check_daemon_socket"
2377 static ssize_t
2379 check_daemon_socket (guestfs_h *g)
2380 Before writing to the daemon socket, check the read side of the daemon
2382 socket for any of these conditions:
2383 error
2385 return -1
2386 daemon cancellation message
2388 return -2
2389 progress message
2391 handle it here
2392 end of input or appliance exited unexpectedly
2394 return 0
2395 anything else
2397 return 1
2398 Function "lib/proto.c:guestfs_int_send_file"
2400 int
2402 guestfs_int_send_file (guestfs_h *g, const char *filename)
2403 Send a file.
2405 Returns 0 on success, "-1" for error, "-2" if the daemon cancelled (we
2407 must read the error message).
2408 Function "lib/proto.c:send_file_data"
2410 static int
2412 send_file_data (guestfs_h *g, const char *buf, size_t len)
2413 Send a chunk of file data.
2415 Function "lib/proto.c:send_file_cancellation"
2417 static int
2419 send_file_cancellation (guestfs_h *g)
2420 Send a cancellation message.
2422 Function "lib/proto.c:send_file_complete"
2424 static int
2426 send_file_complete (guestfs_h *g)
2427 Send a file complete chunk.
2429 Function "lib/proto.c:recv_from_daemon"
2431 static int
2433 recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)
2434 This function reads a single message, file chunk, launch flag or
2436 cancellation flag from the daemon. If something was read, it returns
2437 0, otherwise "-1".
2438 Both "size_rtn" and "buf_rtn" must be passed by the caller as non-NULL.
2440 *size_rtn returns the size of the returned message or it may be
2442 "GUESTFS_LAUNCH_FLAG" or "GUESTFS_CANCEL_FLAG".
2443 *buf_rtn is returned containing the message (if any) or will be set to
2445 "NULL". *buf_rtn must be freed by the caller.
2446 This checks for EOF (appliance died) and passes that up through the
2448 child_cleanup function above.
2449 Log message, progress messages are handled transparently here.
2451 Function "lib/proto.c:guestfs_int_recv"
2453 int
2455 guestfs_int_recv (guestfs_h *g, const char *fn,
2456 guestfs_message_header *hdr,
2457 guestfs_message_error *err,
2458 xdrproc_t xdrp, char *ret)
2459 Receive a reply.
2461 Function "lib/proto.c:guestfs_int_recv_discard"
2463 int
2465 guestfs_int_recv_discard (guestfs_h *g, const char *fn)
2466 Same as "guestfs_int_recv", but it discards the reply message.
2468 Notes (XXX):
2470 · This returns an int, but all current callers ignore it.
2472 · The error string may end up being set twice on error paths.
2474 Function "lib/proto.c:guestfs_int_recv_file"
2476 int
2478 guestfs_int_recv_file (guestfs_h *g, const char *filename)
2479 Returns "-1" = error, 0 = EOF, ">0" = more data
2481 Function "lib/proto.c:receive_file_data"
2483 static ssize_t
2485 receive_file_data (guestfs_h *g, void **buf_r)
2486 Receive a chunk of file data.
2488 Returns "-1" = error, 0 = EOF, ">0" = more data
2490 File lib/qemu.c
2492 Functions to handle qemu versions and features.
2494 Function "lib/qemu.c:guestfs_int_test_qemu"
2496 struct qemu_data *
2498 guestfs_int_test_qemu (guestfs_h *g)
2499 Test that the qemu binary (or wrapper) runs, and do "qemu -help" and
2501 other commands so we can find out the version of qemu and what options
2502 this qemu supports.
2503 This caches the results in the cachedir so that as long as the qemu
2505 binary does not change, calling this is effectively free.
2506 Function "lib/qemu.c:cache_filename"
2508 static char *
2510 cache_filename (guestfs_h *g, const char *cachedir,
2511 const struct stat *statbuf, const char *suffix)
2512 Generate the filenames, for the stat file and the other cache files.
2514 By including the size and mtime in the filename we also ensure that the
2516 same user can use multiple versions of qemu without conflicts.
2517 Function "lib/qemu.c:parse_qemu_version"
2519 static void
2521 parse_qemu_version (guestfs_h *g, const char *qemu_help,
2522 struct version *qemu_version)
2523 Parse the first line of "qemu_help" into the major and minor version of
2525 qemu, but don't fail if parsing is not possible.
2526 Function "lib/qemu.c:parse_json"
2528 static void
2530 parse_json (guestfs_h *g, const char *json, json_t **treep)
2531 Parse the json output from QMP. But don't fail if parsing is not
2533 possible.
2534 Function "lib/qemu.c:parse_has_kvm"
2536 static void
2538 parse_has_kvm (guestfs_h *g, const char *json, bool *ret)
2539 Parse the json output from QMP query-kvm to find out if KVM is enabled
2541 on this machine. Don't fail if parsing is not possible, assume KVM is
2542 available.
2543 The JSON output looks like: {"return": {"enabled": true, "present":
2545 true}}
2546 Function "lib/qemu.c:generic_read_cache"
2548 static int
2550 generic_read_cache (guestfs_h *g, const char *filename, char **strp)
2551 Generic functions for reading and writing the cache files, used where
2553 we are just reading and writing plain text strings.
2554 Function "lib/qemu.c:generic_qmp_test"
2556 static int
2558 generic_qmp_test (guestfs_h *g, struct qemu_data *data,
2559 const char *qmp_command,
2560 char **outp)
2561 Run a generic QMP test on the QEMU binary.
2563 Function "lib/qemu.c:guestfs_int_qemu_version"
2565 struct version
2567 guestfs_int_qemu_version (guestfs_h *g, struct qemu_data *data)
2568 Return the parsed version of qemu.
2570 Function "lib/qemu.c:guestfs_int_qemu_supports"
2572 int
2574 guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data,
2575 const char *option)
2576 Test if option is supported by qemu command line (just by grepping the
2578 help text).
2579 Function "lib/qemu.c:guestfs_int_qemu_supports_device"
2581 int
2583 guestfs_int_qemu_supports_device (guestfs_h *g,
2584 const struct qemu_data *data,
2585 const char *device_name)
2586 Test if device is supported by qemu (currently just greps the "qemu
2588 -device ?" output).
2589 Function "lib/qemu.c:guestfs_int_qemu_mandatory_locking"
2591 int
2593 guestfs_int_qemu_mandatory_locking (guestfs_h *g,
2594 const struct qemu_data *data)
2595 Test if the qemu binary uses mandatory file locking, added in QEMU >=
2597 2.10 (but sometimes disabled).
2598 Function "lib/qemu.c:guestfs_int_qemu_escape_param"
2600 char *
2602 guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)
2603 Escape a qemu parameter.
2605 Every "," becomes ",,". The caller must free the returned string.
2607 XXX This functionality is now only used when constructing a qemu-img
2609 command in lib/create.c. We should extend the qemuopts library to
2610 cover this use case.
2611 Function "lib/qemu.c:guestfs_int_drive_source_qemu_param"
2613 char *
2615 guestfs_int_drive_source_qemu_param (guestfs_h *g,
2616 const struct drive_source *src)
2617 Useful function to format a drive + protocol for qemu.
2619 Note that the qemu parameter is the bit after "file=". It is not
2621 escaped here, but would usually be escaped if passed to qemu as part of
2622 a full -drive parameter (but not for qemu-img(1)).
2623 Function "lib/qemu.c:guestfs_int_discard_possible"
2625 bool
2627 guestfs_int_discard_possible (guestfs_h *g, struct drive *drv,
2628 const struct version *qemu_version)
2629 Test if discard is both supported by qemu AND possible with the
2631 underlying file or device. This returns 1 if discard is possible. It
2632 returns 0 if not possible and sets the error to the reason why.
2633 This function is called when the user set "discard == "enable"".
2635 Function "lib/qemu.c:guestfs_int_free_qemu_data"
2637 void
2639 guestfs_int_free_qemu_data (struct qemu_data *data)
2640 Free the "struct qemu_data".
2642 File lib/rescue.c
2644 Support for virt-rescue(1).
2646 File lib/stringsbuf.c
2648 An expandable NULL-terminated vector of strings (like "argv").
2650 Use the "DECLARE_STRINGSBUF" macro to declare the stringsbuf.
2652 Note: Don't confuse this with stringsbuf in the daemon which is a
2654 different type with different methods.
2655 Function "lib/stringsbuf.c:guestfs_int_add_string_nodup"
2657 void
2659 guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)
2660 Add a string to the end of the list.
2662 This doesn't call strdup(3) on the string, so the string itself is
2664 stored inside the vector.
2665 Function "lib/stringsbuf.c:guestfs_int_add_string"
2667 void
2669 guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)
2670 Add a string to the end of the list.
2672 This makes a copy of the string.
2674 Function "lib/stringsbuf.c:guestfs_int_add_sprintf"
2676 void
2678 guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
2679 const char *fs, ...)
2680 Add a string to the end of the list.
2682 Uses an sprintf-like format string when creating the string.
2684 Function "lib/stringsbuf.c:guestfs_int_end_stringsbuf"
2686 void
2688 guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)
2689 Finish the string buffer.
2691 This adds the terminating NULL to the end of the vector.
2693 Function "lib/stringsbuf.c:guestfs_int_free_stringsbuf"
2695 void
2697 guestfs_int_free_stringsbuf (struct stringsbuf *sb)
2698 Free the string buffer and the strings.
2700 File lib/tmpdirs.c
2702 Handle temporary directories.
2704 Function "lib/tmpdirs.c:set_abs_path"
2706 static int
2708 set_abs_path (guestfs_h *g, const char *ctxstr,
2709 const char *tmpdir, char **tmpdir_ret)
2710 We need to make all tmpdir paths absolute because lots of places in the
2712 code assume this. Do it at the time we set the path or read the
2713 environment variable (https://bugzilla.redhat.com/882417).
2714 The "ctxstr" parameter is a string displayed in error messages giving
2716 the context of the operation (eg. name of environment variable being
2717 used, or API function being called).
2718 Function "lib/tmpdirs.c:guestfs_impl_get_tmpdir"
2720 char *
2722 guestfs_impl_get_tmpdir (guestfs_h *g)
2723 Implements the "guestfs_get_tmpdir" API.
2725 Note this actually calculates the tmpdir, so it never returns "NULL".
2727 Function "lib/tmpdirs.c:guestfs_impl_get_cachedir"
2729 char *
2731 guestfs_impl_get_cachedir (guestfs_h *g)
2732 Implements the "guestfs_get_cachedir" API.
2734 Note this actually calculates the cachedir, so it never returns "NULL".
2736 Function "lib/tmpdirs.c:guestfs_impl_get_sockdir"
2738 char *
2740 guestfs_impl_get_sockdir (guestfs_h *g)
2741 Implements the "guestfs_get_sockdir" API.
2743 Note this actually calculates the sockdir, so it never returns "NULL".
2745 Function "lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir"
2747 int
2749 guestfs_int_lazy_make_tmpdir (guestfs_h *g)
2750 The "g->tmpdir" (per-handle temporary directory) is not created when
2752 the handle is created. Instead we create it lazily before the first
2753 time it is used, or during launch.
2754 Function "lib/tmpdirs.c:guestfs_int_make_temp_path"
2756 char *
2758 guestfs_int_make_temp_path (guestfs_h *g,
2759 const char *name, const char *extension)
2760 Generate unique temporary paths for temporary files.
2762 Returns a unique path or NULL on error.
2764 Function "lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir"
2766 char *
2768 guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)
2769 Create the supermin appliance directory under cachedir, if it does not
2771 exist.
2772 Sanity-check that the permissions on the cachedir are safe, in case it
2774 has been pre-created maliciously or tampered with.
2775 Returns the directory name which the caller must free.
2777 Function "lib/tmpdirs.c:guestfs_int_recursive_remove_dir"
2779 void
2781 guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)
2782 Recursively remove a temporary directory. If removal fails, just
2784 return (it's a temporary directory so it'll eventually be cleaned up by
2785 a temp cleaner).
2786 This is implemented using "rm -rf" because that's simpler and safer.
2788 File lib/umask.c
2790 Return current umask in a thread-safe way.
2792 glibc documents, but does not actually implement, a "getumask(3)" call.
2794 We use "Umask" from /proc/self/status for Linux ≥ 4.7. For older Linux
2796 and other Unix, this file implements an expensive but thread-safe way
2797 to get the current process's umask.
2798 Thanks to: Josh Stone, Jiri Jaburek, Eric Blake.
2800 Function "lib/umask.c:guestfs_int_getumask"
2802 int
2804 guestfs_int_getumask (guestfs_h *g)
2805 Returns the current process's umask. On failure, returns "-1" and sets
2807 the error in the guestfs handle.
2808 Function "lib/umask.c:get_umask_from_proc"
2810 static int
2812 get_umask_from_proc (guestfs_h *g)
2813 For Linux ≥ 4.7 get the umask from /proc/self/status.
2815 On failure this returns "-1". However if we could not open the /proc
2817 file or find the "Umask" entry in it, return "-2" which causes the
2818 fallback path to run.
2819 Function "lib/umask.c:get_umask_from_fork"
2821 static int
2823 get_umask_from_fork (guestfs_h *g)
2824 Fallback method of getting the umask using fork.
2826 File lib/unit-tests.c
2828 Unit tests of internal functions.
2830 These tests may use a libguestfs handle, but must not launch the
2832 handle. Also, avoid long-running tests.
2833 Function "lib/unit-tests.c:test_split"
2835 static void
2837 test_split (void)
2838 Test "guestfs_int_split_string".
2840 Function "lib/unit-tests.c:test_concat"
2842 static void
2844 test_concat (void)
2845 Test "guestfs_int_concat_strings".
2847 Function "lib/unit-tests.c:test_join"
2849 static void
2851 test_join (void)
2852 Test "guestfs_int_join_strings".
2854 Function "lib/unit-tests.c:test_validate_guid"
2856 static void
2858 test_validate_guid (void)
2859 Test "guestfs_int_validate_guid".
2861 Function "lib/unit-tests.c:test_drive_name"
2863 static void
2865 test_drive_name (void)
2866 Test "guestfs_int_drive_name".
2868 Function "lib/unit-tests.c:test_drive_index"
2870 static void
2872 test_drive_index (void)
2873 Test "guestfs_int_drive_index".
2875 Function "lib/unit-tests.c:test_getumask"
2877 static void
2879 test_getumask (void)
2880 Test "guestfs_int_getumask".
2882 Function "lib/unit-tests.c:test_command"
2884 static void
2886 test_command (void)
2887 Test "guestfs_int_new_command" etc.
2889 XXX These tests could be made much more thorough. So far we simply
2891 test that it's not obviously broken.
2892 Function "lib/unit-tests.c:test_qemu_escape_param"
2894 static void
2896 test_qemu_escape_param (void)
2897 Test "guestfs_int_qemu_escape_param"
2899 XXX I wanted to make this test run qemu, passing some parameters which
2901 need to be escaped, but I cannot think of a way to do that without
2902 launching a VM.
2903 Function "lib/unit-tests.c:test_timeval_diff"
2905 static void
2907 test_timeval_diff (void)
2908 Test "guestfs_int_timeval_diff".
2910 File lib/version.c
2912 This file provides simple version number management.
2914 Function "lib/version.c:guestfs_int_version_from_x_y"
2916 int
2918 guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)
2919 Parses a version from a string, looking for a "X.Y" pattern.
2921 Returns "-1" on failure (like failed integer parsing), 0 on missing
2923 match, and 1 on match and successful parsing. "v" is changed only on
2924 successful match.
2925 Function "lib/version.c:guestfs_int_version_from_x_y_re"
2927 int
2929 guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
2930 const char *str, const pcre *re)
2931 Parses a version from a string, using the specified "re" as regular
2933 expression which must provide (at least) two matches.
2934 Returns "-1" on failure (like failed integer parsing), 0 on missing
2936 match, and 1 on match and successful parsing. "v" is changed only on
2937 successful match.
2938 Function "lib/version.c:guestfs_int_version_from_x_y_or_x"
2940 int
2942 guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
2943 const char *str)
2944 Parses a version from a string, either looking for a "X.Y" pattern or
2946 considering it as whole integer.
2947 Returns "-1" on failure (like failed integer parsing), 0 on missing
2949 match, and 1 on match and successful parsing. "v" is changed only on
2950 successful match.
2951 Function "lib/version.c:guestfs_int_parse_unsigned_int"
2953 int
2955 guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)
2956 Parse small, unsigned ints, as used in version numbers.
2958 This will fail with an error if trailing characters are found after the
2960 integer.
2961 Returns ≥ 0 on success, or "-1" on failure.
2963 File lib/wait.c
2965 Function "lib/wait.c:guestfs_int_waitpid"
2967 int
2969 guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)
2970 A safe version of waitpid(3) which retries if "EINTR" is returned.
2972 Note: this only needs to be used in the library, or in programs that
2974 install a non-restartable "SIGCHLD" handler (which is not the case for
2975 any current libguestfs virt tools).
2976 If the main program installs a SIGCHLD handler and sets it to be non-
2978 restartable, then what can happen is the library is waiting in a wait
2979 syscall, the child exits, "SIGCHLD" is sent to the process, and the
2980 wait syscall returns "EINTR". Since the library cannot control the
2981 signal handler, we have to instead restart the wait syscall, which is
2982 the purpose of this wrapper.
2983 Function "lib/wait.c:guestfs_int_waitpid_noerror"
2985 void
2987 guestfs_int_waitpid_noerror (pid_t pid)
2988 Like "guestfs_int_waitpid", but ignore errors.
2990 Function "lib/wait.c:guestfs_int_wait4"
2992 int
2994 guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
2995 struct rusage *rusage, const char *errmsg)
2996 A safe version of wait4(2) which retries if "EINTR" is returned.
2998 File lib/whole-file.c
3000 Function "lib/whole-file.c:guestfs_int_read_whole_file"
3002 int
3004 guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
3005 char **data_r, size_t *size_r)
3006 Read the whole file "filename" into a memory buffer.
3008 The memory buffer is initialized and returned in "data_r". The size of
3010 the file in bytes is returned in "size_r". The return buffer must be
3011 freed by the caller.
3012 On error this sets the error in the handle and returns "-1".
3014 For the convenience of callers, the returned buffer is NUL-terminated
3016 (the NUL is not included in the size).
3017 The file must be a regular, local, trusted file. In particular, do not
3019 use this function to read files that might be under control of an
3020 untrusted user since that will lead to a denial-of-service attack.
3021 Subdirectory builder
3023 File builder/index-parser-c.c
3024 This file handles the interface between the C/lex/yacc index file
3026 parser, and the OCaml world. See builder/index_parser.ml for the OCaml
3027 type definition.
3028 Subdirectory common/edit
3030 File common/edit/file-edit.c
3031 This file implements common file editing in a range of utilities
3033 including guestfish(1), virt-edit(1), virt-customize(1) and
3034 virt-builder(1).
3035 It contains the code for both interactive-(editor-)based editing and
3037 non-interactive editing using Perl snippets.
3038 Function "common/edit/file-edit.c:edit_file_editor"
3040 int
3042 edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
3043 const char *backup_extension, int verbose)
3044 Edit "filename" using the specified "editor" application.
3046 If "backup_extension" is not null, then a copy of "filename" is saved
3048 with "backup_extension" appended to its file name.
3049 If "editor" is null, then the $EDITOR environment variable will be
3051 queried for the editor application, leaving "vi" as fallback if not
3052 set.
3053 Returns "-1" for failure, 0 on success, 1 if the editor did not change
3055 the file (e.g. the user closed the editor without saving).
3056 Function "common/edit/file-edit.c:edit_file_perl"
3058 int
3060 edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
3061 const char *backup_extension, int verbose)
3062 Edit "filename" running the specified "perl_expr" using Perl.
3064 If "backup_extension" is not null, then a copy of "filename" is saved
3066 with "backup_extension" appended to its file name.
3067 Returns "-1" for failure, 0 on success.
3069 Subdirectory common/mlxml
3071 File common/mlxml/xml-c.c
3072 Mini interface to libxml2.
3074 Subdirectory common/options
3076 File common/options/config.c
3077 This file parses the guestfish configuration file, usually
3079 ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.
3080 Note that "parse_config" is called very early, before command line
3082 parsing, before the "verbose" flag has been set, even before the global
3083 handle "g" is opened.
3084 File common/options/decrypt.c
3086 This file implements the decryption of disk images, usually done before
3088 mounting their partitions.
3089 Function "common/options/decrypt.c:make_mapname"
3091 static void
3093 make_mapname (const char *device, char *mapname, size_t len)
3094 Make a LUKS map name from the partition name, eg. "/dev/vda2" =>
3096 "luksvda2"
3097 Function "common/options/decrypt.c:inspect_do_decrypt"
3099 void
3101 inspect_do_decrypt (guestfs_h *g, struct key_store *ks)
3102 Simple implementation of decryption: look for any "crypto_LUKS"
3104 partitions and decrypt them, then rescan for VGs. This only works for
3105 Fedora whole-disk encryption. WIP to make this work for other
3106 encryption schemes.
3107 File common/options/display-options.c
3109 This file contains common code used to implement --short-options and
3111 --long-options in C virt tools. (The equivalent for OCaml virt tools
3112 is implemented by common/mltools/getopt.ml).
3113 These "hidden" options are used to implement bash tab completion.
3115 Function "common/options/display-options.c:display_short_options"
3117 void
3119 display_short_options (const char *format)
3120 Implements the internal "tool --short-options" flag, which just lists
3122 out the short options available. Used by bash completion.
3123 Function "common/options/display-options.c:display_long_options"
3125 void
3127 display_long_options (const struct option *long_options)
3128 Implements the internal "tool --long-options" flag, which just lists
3130 out the long options available. Used by bash completion.
3131 File common/options/domain.c
3133 Implements the guestfish (and other tools) -d option.
3135 Function "common/options/domain.c:add_libvirt_drives"
3137 int
3139 add_libvirt_drives (guestfs_h *g, const char *guest)
3140 This function is called when a user invokes "guestfish -d guest".
3142 Returns the number of drives added ("> 0"), or "-1" for failure.
3144 File common/options/inspect.c
3146 This file implements inspecting the guest and mounting the filesystems
3148 found in the right places. It is used by the guestfish(1) -i option
3149 and some utilities such as virt-cat(1).
3150 Function "common/options/inspect.c:inspect_mount_handle"
3152 void
3154 inspect_mount_handle (guestfs_h *g, struct key_store *ks)
3155 This function implements the -i option.
3157 Function "common/options/inspect.c:print_inspect_prompt"
3159 void
3161 print_inspect_prompt (void)
3162 This function is called only if "inspect_mount_root" was called, and
3164 only after we've printed the prompt in interactive mode.
3165 File common/options/keys.c
3167 Function "common/options/keys.c:read_key"
3169 char *
3171 read_key (const char *param)
3172 Read a passphrase ('Key') from /dev/tty with echo off.
3174 The caller (fish/cmds.c) will call free on the string afterwards.
3176 Based on the code in cryptsetup file lib/utils.c.
3177 File common/options/options.c
3179 This file contains common options parsing code used by guestfish and
3181 many other tools which share a common options syntax.
3182 For example, guestfish, virt-cat, virt-ls etc all support the -a
3184 option, and that is handled in all of those tools using a macro
3185 "OPTION_a" defined in fish/options.h.
3186 There are a lot of common global variables used, "drvs" accumulates the
3188 list of drives, "verbose" for the -v flag, and many more.
3189 Function "common/options/options.c:option_a"
3191 void
3193 option_a (const char *arg, const char *format, struct drv **drvsp)
3194 Handle the guestfish -a option on the command line.
3196 Function "common/options/options.c:option_d"
3198 void
3200 option_d (const char *arg, struct drv **drvsp)
3201 Handle the -d option when passed on the command line.
3203 Function "common/options/options.c:display_mountpoints_on_failure"
3205 static void
3207 display_mountpoints_on_failure (const char *mp_device,
3208 const char *user_supplied_options)
3209 If the -m option fails on any command, display a useful error message
3211 listing the mountpoints.
3212 File common/options/uri.c
3214 This file implements URI parsing for the -a option, in many utilities
3216 including guestfish(1), virt-cat(1), virt-builder(1),
3217 virt-customize(1), etc.
3218 Subdirectory common/parallel
3220 File common/parallel/domains.c
3221 This file is used by "virt-df" and some of the other tools when they
3223 are implicitly asked to operate over all libvirt domains (VMs), for
3224 example when "virt-df" is called without specifying any particular disk
3225 image.
3226 It hides the complexity of querying the list of domains from libvirt.
3228 Function "common/parallel/domains.c:free_domains"
3230 void
3232 free_domains (void)
3233 Frees up everything allocated by "get_all_libvirt_domains".
3235 Function "common/parallel/domains.c:get_all_libvirt_domains"
3237 void
3239 get_all_libvirt_domains (const char *libvirt_uri)
3240 Read all libguest guests into the global variables "domains" and
3242 "nr_domains". The guests are ordered by name. This exits on any
3243 error.
3244 File common/parallel/estimate-max-threads.c
3246 Function "common/parallel/estimate-max-threads.c:estimate_max_threads"
3248 size_t
3250 estimate_max_threads (void)
3251 This function uses the output of "free -m" to estimate how many
3253 libguestfs appliances could be safely started in parallel. Note that
3254 it always returns ≥ 1.
3255 Function "common/parallel/estimate-max-threads.c:read_line_from"
3257 static char *
3259 read_line_from (const char *cmd)
3260 Run external command and read the first line of output.
3262 File common/parallel/parallel.c
3264 This file is used by "virt-df" and some of the other tools when they
3266 need to run multiple parallel libguestfs instances to operate on a
3267 large number of libvirt domains efficiently.
3268 It implements a multithreaded work queue. In addition it reorders the
3270 output so the output still appears in the same order as the input (ie.
3271 still ordered alphabetically).
3272 Function "common/parallel/parallel.c:start_threads"
3274 int
3276 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
3277 Run the threads and work through the global list of libvirt domains.
3279 "option_P" is whatever the user passed in the -P option, or 0 if the
3281 user didn't use the -P option (in which case the number of threads is
3282 chosen heuristically).
3283 "options_handle" (which may be "NULL") is the global guestfs handle
3285 created by the options mini-library.
3286 The work function ("work") should do the work (inspecting the domain,
3288 etc.) on domain index "i". However it must not print out any result
3289 directly. Instead it prints anything it needs to the supplied "FILE
3290 *". The work function should return 0 on success or "-1" on error.
3291 The "start_threads" function returns 0 if all work items completed
3293 successfully, or "-1" if there was an error.
3294 Subdirectory common/progress
3296 File common/progress/progress.c
3297 This file implements the progress bar in guestfish(1), virt-resize(1)
3299 and virt-sparsify(1).
3300 Function "common/progress/progress.c:progress_bar_init"
3302 struct progress_bar *
3304 progress_bar_init (unsigned flags)
3305 Initialize a progress bar struct.
3307 It is intended that you can reuse the same struct for multiple commands
3309 (but only in a single thread). Call "progress_bar_reset" before each
3310 new command.
3311 Function "common/progress/progress.c:progress_bar_free"
3313 void
3315 progress_bar_free (struct progress_bar *bar)
3316 Free a progress bar struct.
3318 Function "common/progress/progress.c:progress_bar_reset"
3320 void
3322 progress_bar_reset (struct progress_bar *bar)
3323 This function should be called just before you issue any command.
3325 Function "common/progress/progress.c:estimate_remaining_time"
3327 static double
3329 estimate_remaining_time (struct progress_bar *bar, double ratio)
3330 Return remaining time estimate (in seconds) for current call.
3332 This returns the running mean estimate of remaining time, but if the
3334 latest estimate of total time is greater than two s.d.'s from the
3335 running mean then we don't print anything because we're not confident
3336 that the estimate is meaningful. (Returned value is <0.0 when nothing
3337 should be printed).
3338 Function "common/progress/progress.c:progress_bar_set"
3340 void
3342 progress_bar_set (struct progress_bar *bar,
3343 uint64_t position, uint64_t total)
3344 Set the position of the progress bar.
3346 This should be called from a "GUESTFS_EVENT_PROGRESS" event callback.
3348 Subdirectory common/qemuopts
3350 File common/qemuopts/qemuopts-tests.c
3351 Unit tests of internal functions.
3353 These tests may use a libguestfs handle, but must not launch the
3355 handle. Also, avoid long-running tests.
3356 File common/qemuopts/qemuopts.c
3358 Mini-library for writing qemu command lines and qemu config files.
3360 There are some shortcomings with the model used for qemu options which
3362 aren't clear until you try to convert options into a configuration
3363 file. However if we attempted to model the options in more detail then
3364 this library would be both very difficult to use and incompatible with
3365 older versions of qemu. Hopefully the current model is a decent
3366 compromise.
3367 For reference here are the problems:
3369 · There's inconsistency in qemu between options and config file, eg.
3371 "-smp 4" becomes:
3372 [smp-opts]
3374 cpus = "4"
3375 · Similar to the previous point, you can write either "-smp 4" or
3377 "-smp cpus=4" (although this won't work in very old qemu). When
3378 generating a config file you need to know the implicit key name.
3379 · In "-opt key=value,..." the "key" is really a tree/array specifier.
3381 The way this works is complicated but hinted at here:
3382 http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
3383 · Some options are syntactic sugar. eg. "-kernel foo" is sugar for
3385 "-machine kernel=foo".
3386 Function "common/qemuopts/qemuopts.c:qemuopts_create"
3388 struct qemuopts *
3390 qemuopts_create (void)
3391 Create an empty list of qemu options.
3393 The caller must eventually free the list by calling "qemuopts_free".
3395 Returns "NULL" on error, setting "errno".
3397 Function "common/qemuopts/qemuopts.c:qemuopts_free"
3399 void
3401 qemuopts_free (struct qemuopts *qopts)
3402 Free the list of qemu options.
3404 Function "common/qemuopts/qemuopts.c:qemuopts_add_flag"
3406 int
3408 qemuopts_add_flag (struct qemuopts *qopts, const char *flag)
3409 Add a command line flag which has no argument. eg:
3411 qemuopts_add_flag (qopts, "-no-user-config");
3413 Returns 0 on success. Returns "-1" on error, setting "errno".
3415 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg"
3417 int
3419 qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)
3420 Add a command line flag which has a single argument. eg:
3422 qemuopts_add_arg (qopts, "-m", "1024");
3424 Don't use this if the argument is a comma-separated list, since quoting
3426 will not be done properly. See "qemuopts_add_arg_list".
3427 Returns 0 on success. Returns "-1" on error, setting "errno".
3429 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_format"
3431 int
3433 qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
3434 const char *fs, ...)
3435 Add a command line flag which has a single formatted argument. eg:
3437 qemuopts_add_arg_format (qopts, "-m", "%d", 1024);
3439 Don't use this if the argument is a comma-separated list, since quoting
3441 will not be done properly. See "qemuopts_add_arg_list".
3442 Returns 0 on success. Returns "-1" on error, setting "errno".
3444 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote"
3446 int
3448 qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
3449 const char *value)
3450 This is like "qemuopts_add_arg" except that no quoting is done on the
3452 value.
3453 For "qemuopts_to_script" and "qemuopts_to_channel", this means that
3455 neither shell quoting nor qemu comma quoting is done on the value.
3456 For "qemuopts_to_argv" this means that qemu comma quoting is not done.
3458 "qemuopts_to_config*" will fail.
3460 You should use this with great care.
3462 Function "common/qemuopts/qemuopts.c:qemuopts_start_arg_list"
3464 int
3466 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
3467 Start an argument that takes a comma-separated list of fields.
3469 Typical usage is like this (with error handling omitted):
3471 qemuopts_start_arg_list (qopts, "-drive");
3473 qemuopts_append_arg_list (qopts, "file=foo");
3474 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
3475 qemuopts_end_arg_list (qopts);
3476 which would construct "-drive file=foo,if=ide"
3478 See also "qemuopts_add_arg_list" for a way to do simple cases in one
3480 call.
3481 Returns 0 on success. Returns "-1" on error, setting "errno".
3483 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_list"
3485 int
3487 qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
3488 const char *elem0, ...)
3489 Add a command line flag which has a list of arguments. eg:
3491 qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);
3493 This is turned into a comma-separated list, like: "-drive
3495 file=foo,if=ide". Note that this handles qemu quoting properly, so
3496 individual elements may contain commas and this will do the right
3497 thing.
3498 Returns 0 on success. Returns "-1" on error, setting "errno".
3500 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary"
3502 int
3504 qemuopts_set_binary (struct qemuopts *qopts, const char *binary)
3505 Set the qemu binary name.
3507 Returns 0 on success. Returns "-1" on error, setting "errno".
3509 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch"
3511 int
3513 qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)
3514 Set the qemu binary name to "qemu-system-[arch]".
3516 As a special case if "arch" is "NULL", the binary is set to the KVM
3518 binary for the current host architecture:
3519 qemuopts_set_binary_by_arch (qopts, NULL);
3521 Returns 0 on success. Returns "-1" on error, setting "errno".
3523 Function "common/qemuopts/qemuopts.c:qemuopts_to_script"
3525 int
3527 qemuopts_to_script (struct qemuopts *qopts, const char *filename)
3528 Write the qemu options to a script.
3530 "qemuopts_set_binary*" must be called first.
3532 The script file will start with "#!/bin/sh" and will be chmod to mode
3534 0755.
3535 Returns 0 on success. Returns "-1" on error, setting "errno".
3537 Function "common/qemuopts/qemuopts.c:shell_quote"
3539 static void
3541 shell_quote (const char *str, FILE *fp)
3542 Print "str" to "fp", shell-quoting it if necessary.
3544 Function "common/qemuopts/qemuopts.c:shell_and_comma_quote"
3546 static void
3548 shell_and_comma_quote (const char *str, FILE *fp)
3549 Print "str" to "fp" doing both shell and qemu comma quoting.
3551 Function "common/qemuopts/qemuopts.c:qemuopts_to_channel"
3553 int
3555 qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)
3556 Write the qemu options to a "FILE *fp".
3558 "qemuopts_set_binary*" must be called first.
3560 Only the qemu command line is written. The caller may need to add
3562 "#!/bin/sh" and may need to chmod the resulting file to 0755.
3563 Returns 0 on success. Returns "-1" on error, setting "errno".
3565 Function "common/qemuopts/qemuopts.c:qemuopts_to_argv"
3567 char **
3569 qemuopts_to_argv (struct qemuopts *qopts)
3570 Return a NULL-terminated argument list, of the kind that can be passed
3572 directly to execv(3).
3573 "qemuopts_set_binary*" must be called first. It will be returned as
3575 "argv[0]" in the returned list.
3576 The list of strings and the strings themselves must be freed by the
3578 caller.
3579 Returns "NULL" on error, setting "errno".
3581 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_file"
3583 int
3585 qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)
3586 Write the qemu options to a qemu config file, suitable for reading in
3588 using "qemu -readconfig filename".
3589 Note that qemu config files have limitations on content and quoting, so
3591 not all qemuopts structs can be written (this function returns an error
3592 in these cases). For more information see
3593 https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html
3594 https://bugs.launchpad.net/qemu/+bug/1686364
3595 Also, command line argument names and config file sections sometimes
3597 have different names. For example the equivalent of "-m 1024" is:
3598 [memory]
3600 size = "1024"
3601 This code does not attempt to convert between the two forms. You just
3603 need to know how to do that yourself.
3604 Returns 0 on success. Returns "-1" on error, setting "errno".
3606 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_channel"
3608 int
3610 qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)
3611 Same as "qemuopts_to_config_file", but this writes to a "FILE *fp".
3613 Subdirectory common/utils
3615 File common/utils/cleanups.c
3616 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3618 They are implemented using the "__attribute__((cleanup))" feature of
3619 gcc and clang. Typical usage is:
3620 fn ()
3622 {
3623 CLEANUP_FREE char *str = NULL;
3624 str = safe_asprintf (g, "foo");
3625 // str is freed automatically when the function returns
3626 }
3627 There are a few catches to be aware of with the cleanup mechanism:
3629 · If a cleanup variable is not initialized, then you can end up
3631 calling free(3) with an undefined value, resulting in the program
3632 crashing. For this reason, you should usually initialize every
3633 cleanup variable with something, eg. "NULL"
3634 · Don't mark variables holding return values as cleanup variables.
3636 · The "main()" function shouldn't use cleanup variables since it is
3638 normally exited by calling exit(3), and that doesn't call the
3639 cleanup handlers.
3640 The functions in this file are used internally by the "CLEANUP_*"
3642 macros. Don't call them directly.
3643 File common/utils/gnulib-cleanups.c
3645 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3647 They are implemented using the "__attribute__((cleanup))" feature of
3648 gcc and clang. Typical usage is:
3649 fn ()
3651 {
3652 CLEANUP_FREE char *str = NULL;
3653 str = safe_asprintf (g, "foo");
3654 // str is freed automatically when the function returns
3655 }
3656 There are a few catches to be aware of with the cleanup mechanism:
3658 · If a cleanup variable is not initialized, then you can end up
3660 calling free(3) with an undefined value, resulting in the program
3661 crashing. For this reason, you should usually initialize every
3662 cleanup variable with something, eg. "NULL"
3663 · Don't mark variables holding return values as cleanup variables.
3665 · The "main()" function shouldn't use cleanup variables since it is
3667 normally exited by calling exit(3), and that doesn't call the
3668 cleanup handlers.
3669 The functions in this file are used internally by the "CLEANUP_*"
3671 macros. Don't call them directly.
3672 File common/utils/guestfs-utils.h
3674 This header file is included in all "frontend" parts of libguestfs,
3676 namely the library, non-C language bindings, virt tools and tests.
3677 The daemon does not use this header. If you need a place to put
3679 something shared with absolutely everything including the daemon, put
3680 it in lib/guestfs-internal-all.h
3681 If a definition is only needed by a single component of libguestfs (eg.
3683 just the library, or just a single virt tool) then it should not be
3684 here!
3685 File common/utils/libxml2-writer-macros.h
3687 These macros make it easier to write XML. To use them correctly you
3689 must be aware of these assumptions:
3690 · The "xmlTextWriterPtr" is called "xo". It is used implicitly by
3692 all the macros.
3693 · On failure, a function called "xml_error" is called which you must
3695 define (usually as a macro). You must use "CLEANUP_*" macros in
3696 your functions if you want correct cleanup of local variables along
3697 the error path.
3698 · All the "bad" casting is hidden inside the macros.
3700 Definition "common/utils/libxml2-writer-macros.h:start_element"
3702 #define start_element
3704 To define an XML element use:
3706 start_element ("name") {
3708 ...
3709 } end_element ();
3710 which produces "<name>...</name>"
3712 Definition "common/utils/libxml2-writer-macros.h:empty_element"
3714 #define empty_element
3716 To define an empty element:
3718 empty_element ("name");
3720 which produces "<name/>"
3722 Definition "common/utils/libxml2-writer-macros.h:single_element"
3724 #define single_element
3726 To define a single element with no attributes containing some text:
3728 single_element ("name", text);
3730 which produces "<name>text</name>"
3732 Definition "common/utils/libxml2-writer-macros.h:single_element_format"
3734 #define single_element_format
3736 To define a single element with no attributes containing some text
3738 using a format string:
3739 single_element_format ("cores", "%d", nr_cores);
3741 which produces "<cores>4</cores>"
3743 Definition "common/utils/libxml2-writer-macros.h:attribute"
3745 #define attribute
3747 To define an XML element with attributes, use:
3749 start_element ("name") {
3751 attribute ("foo", "bar");
3752 attribute_format ("count", "%d", count);
3753 ...
3754 } end_element ();
3755 which produces "<name foo="bar" count="123">...</name>"
3757 Definition "common/utils/libxml2-writer-macros.h:attribute_ns"
3759 #define attribute_ns
3761 "attribute_ns (prefix, key, namespace_uri, value)" defines a namespaced
3763 attribute.
3764 Definition "common/utils/libxml2-writer-macros.h:string"
3766 #define string
3768 To define a verbatim string, use:
3770 string ("hello");
3772 Definition "common/utils/libxml2-writer-macros.h:string_format"
3774 #define string_format
3776 To define a verbatim string using a format string, use:
3778 string ("%s, world", greeting);
3780 Definition "common/utils/libxml2-writer-macros.h:base64"
3782 #define base64
3784 To write a string encoded as base64:
3786 base64 (data, size);
3788 Definition "common/utils/libxml2-writer-macros.h:comment"
3790 #define comment
3792 To define a comment in the XML, use:
3794 comment ("number of items = %d", nr_items);
3796 File common/utils/utils.c
3798 Utility functions used by the library, tools and language bindings.
3800 These functions must not call internal library functions such as
3802 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3803 Function "common/utils/utils.c:guestfs_int_split_string"
3805 char **
3807 guestfs_int_split_string (char sep, const char *str)
3808 Split string at separator character "sep", returning the list of
3810 strings. Returns "NULL" on memory allocation failure.
3811 Note (assuming "sep" is ":"):
3813 "str == NULL"
3815 aborts
3816 "str == """
3818 returns "[]"
3819 "str == "abc""
3821 returns "["abc"]"
3822 "str == ":""
3824 returns "["", ""]"
3825 Function "common/utils/utils.c:guestfs_int_exit_status_to_string"
3827 char *
3829 guestfs_int_exit_status_to_string (int status, const char *cmd_name,
3830 char *buffer, size_t buflen)
3831 Translate a wait/system exit status into a printable string.
3833 Function "common/utils/utils.c:guestfs_int_random_string"
3835 int
3837 guestfs_int_random_string (char *ret, size_t len)
3838 Return a random string of characters.
3840 Notes:
3842 · The "ret" buffer must have length "len+1" in order to store the
3844 final "\0" character.
3845 · There is about 5 bits of randomness per output character (so about
3847 "5*len" bits of randomness in the resulting string).
3848 Function "common/utils/utils.c:guestfs_int_drive_name"
3850 char *
3852 guestfs_int_drive_name (size_t index, char *ret)
3853 This turns a drive index (eg. 27) into a drive name (eg. "ab").
3855 Drive indexes count from 0. The return buffer has to be large enough
3857 for the resulting string, and the returned pointer points to the *end*
3858 of the string.
3859 https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
3861 Function "common/utils/utils.c:guestfs_int_drive_index"
3863 ssize_t
3865 guestfs_int_drive_index (const char *name)
3866 The opposite of "guestfs_int_drive_name". Take a string like "ab" and
3868 return the index (eg 27).
3869 Note that you must remove any prefix such as "hd", "sd" etc, or any
3871 partition number before calling the function.
3872 Function "common/utils/utils.c:guestfs_int_is_true"
3874 int
3876 guestfs_int_is_true (const char *str)
3877 Similar to "Tcl_GetBoolean".
3879 Function "common/utils/utils.c:guestfs_int_string_is_valid"
3881 bool
3883 guestfs_int_string_is_valid (const char *str,
3884 size_t min_length, size_t max_length,
3885 int flags, const char *extra)
3886 Check a string for validity, that it contains only certain characters,
3888 and minimum and maximum length. This function is usually wrapped in a
3889 VALID_* macro, see lib/drives.c for an example.
3890 "str" is the string to check.
3892 "min_length" and "max_length" are the minimum and maximum length
3894 checks. 0 means no check.
3895 The flags control:
3897 "VALID_FLAG_ALPHA"
3899 7-bit ASCII-only alphabetic characters are permitted.
3900 "VALID_FLAG_DIGIT"
3902 7-bit ASCII-only digits are permitted.
3903 "extra" is a set of extra characters permitted, in addition to
3905 alphabetic and/or digits. ("extra = NULL" for no extra).
3906 Returns boolean "true" if the string is valid (passes all the tests),
3908 or "false" if not.
3909 Function "common/utils/utils.c:guestfs_int_fadvise_normal"
3911 void
3913 guestfs_int_fadvise_normal (int fd)
3914 Hint that we will read or write the file descriptor normally.
3916 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3918 and sets the per-file number of readahead pages to equal the block
3919 device readahead setting.
3920 It's OK to call this on a non-file since we ignore failure as it is
3922 only a hint.
3923 Function "common/utils/utils.c:guestfs_int_fadvise_sequential"
3925 void
3927 guestfs_int_fadvise_sequential (int fd)
3928 Hint that we will read or write the file descriptor sequentially.
3930 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3932 and sets the per-file number of readahead pages to twice the block
3933 device readahead setting.
3934 It's OK to call this on a non-file since we ignore failure as it is
3936 only a hint.
3937 Function "common/utils/utils.c:guestfs_int_fadvise_random"
3939 void
3941 guestfs_int_fadvise_random (int fd)
3942 Hint that we will read or write the file descriptor randomly.
3944 On Linux, this sets the "FMODE_RANDOM" flag on the file. The effect of
3946 this flag is to:
3947 · Disable normal sequential file readahead.
3949 · If any read of the file is done which misses in the page cache, 2MB
3951 are read into the page cache. [I think - I'm not sure I totally
3952 understand what this is doing]
3953 It's OK to call this on a non-file since we ignore failure as it is
3955 only a hint.
3956 Function "common/utils/utils.c:guestfs_int_fadvise_noreuse"
3958 void
3960 guestfs_int_fadvise_noreuse (int fd)
3961 Hint that we will access the data only once.
3963 On Linux, this does nothing.
3965 It's OK to call this on a non-file since we ignore failure as it is
3967 only a hint.
3968 Function "common/utils/utils.c:guestfs_int_fadvise_dontneed"
3970 void
3972 guestfs_int_fadvise_dontneed (int fd)
3973 Hint that we will not access the data in the near future.
3975 On Linux, this immediately writes out any dirty pages in the page cache
3977 and then invalidates (drops) all pages associated with this file from
3978 the page cache. Apparently it does this even if the file is opened or
3979 being used by other processes. This setting is not persistent; if you
3980 subsequently read the file it will be cached in the page cache as
3981 normal.
3982 It's OK to call this on a non-file since we ignore failure as it is
3984 only a hint.
3985 Function "common/utils/utils.c:guestfs_int_fadvise_willneed"
3987 void
3989 guestfs_int_fadvise_willneed (int fd)
3990 Hint that we will access the data in the near future.
3992 On Linux, this immediately reads the whole file into the page cache.
3994 This setting is not persistent; subsequently pages may be dropped from
3995 the page cache as normal.
3996 It's OK to call this on a non-file since we ignore failure as it is
3998 only a hint.
3999 Function "common/utils/utils.c:guestfs_int_shell_unquote"
4001 char *
4003 guestfs_int_shell_unquote (const char *str)
4004 Unquote a shell-quoted string.
4006 Augeas passes strings to us which may be quoted, eg. if they come from
4008 files in /etc/sysconfig. This function can do simple unquoting of
4009 these strings.
4010 Note this function does not do variable substitution, since that is
4012 impossible without knowing the file context and indeed the environment
4013 under which the shell script is run. Configuration files should not
4014 use complex quoting.
4015 "str" is the input string from Augeas, a string that may be single- or
4017 double-quoted or may not be quoted. The returned string is unquoted,
4018 and must be freed by the caller. "NULL" is returned on error and
4019 "errno" is set accordingly.
4020 For information on double-quoting in bash, see
4022 https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html
4023 Function "common/utils/utils.c:guestfs_int_is_reg"
4025 int
4027 guestfs_int_is_reg (int64_t mode)
4028 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4030 field represents a regular file.
4031 Function "common/utils/utils.c:guestfs_int_is_dir"
4033 int
4035 guestfs_int_is_dir (int64_t mode)
4036 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4038 field represents a directory.
4039 Function "common/utils/utils.c:guestfs_int_is_chr"
4041 int
4043 guestfs_int_is_chr (int64_t mode)
4044 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4046 field represents a char device.
4047 Function "common/utils/utils.c:guestfs_int_is_blk"
4049 int
4051 guestfs_int_is_blk (int64_t mode)
4052 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4054 field represents a block device.
4055 Function "common/utils/utils.c:guestfs_int_is_fifo"
4057 int
4059 guestfs_int_is_fifo (int64_t mode)
4060 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4062 field represents a named pipe (FIFO).
4063 Function "common/utils/utils.c:guestfs_int_is_lnk"
4065 int
4067 guestfs_int_is_lnk (int64_t mode)
4068 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4070 field represents a symbolic link.
4071 Function "common/utils/utils.c:guestfs_int_is_sock"
4073 int
4075 guestfs_int_is_sock (int64_t mode)
4076 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4078 field represents a Unix domain socket.
4079 Function "common/utils/utils.c:guestfs_int_full_path"
4081 char *
4083 guestfs_int_full_path (const char *dir, const char *name)
4084 Concatenate "dir" and "name" to create a path. This correctly handles
4086 the case of concatenating "/" + "filename" as well as "/dir" +
4087 "filename". "name" may be "NULL".
4088 The caller must free the returned path.
4090 This function sets "errno" and returns "NULL" on error.
4092 Function "common/utils/utils.c:guestfs_int_hexdump"
4094 void
4096 guestfs_int_hexdump (const void *data, size_t len, FILE *fp)
4097 Hexdump a block of memory to "FILE *", used for debugging.
4099 Subdirectory common/visit
4101 File common/visit/visit.c
4102 This file contains a recursive function for visiting all files and
4104 directories in a guestfs filesystem.
4105 Adapted from
4107 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/
4108 Function "common/visit/visit.c:visit"
4110 int
4112 visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)
4113 Visit every file and directory in a guestfs filesystem, starting at
4115 "dir".
4116 "dir" may be "/" to visit the entire filesystem, or may be some
4118 subdirectory. Symbolic links are not followed.
4119 The visitor function "f" is called once for every directory and every
4121 file. The parameters passed to "f" include the current directory name,
4122 the current file name (or "NULL" when we're visiting a directory), the
4123 "guestfs_statns" (file permissions etc), and the list of extended
4124 attributes of the file. The visitor function may return "-1" which
4125 causes the whole recursion to stop with an error.
4126 Also passed to this function is an "opaque" pointer which is passed
4128 through to the visitor function.
4129 Returns 0 if everything went OK, or "-1" if there was an error. Error
4131 handling is not particularly well defined. It will either set an error
4132 in the libguestfs handle or print an error on stderr, but there is no
4133 way for the caller to tell the difference.
4134 Subdirectory common/windows
4136 File common/windows/windows.c
4137 This file implements "win:" Windows file path support in guestfish(1).
4139 Function "common/windows/windows.c:is_windows"
4141 int
4143 is_windows (guestfs_h *g, const char *root)
4144 Checks whether "root" is a Windows installation.
4146 This relies on an already being done introspection.
4148 Function "common/windows/windows.c:windows_path"
4150 char *
4152 windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
4153 Resolves "path" as possible Windows path according to "root", giving a
4155 new path that can be used in libguestfs API calls.
4156 Notes:
4158 · "root" must be a Windows installation
4160 · relies on an already being done introspection
4162 · will unmount all the existing mount points and mount the Windows
4164 root (according to "readonly")
4165 · calls exit(3) on memory allocation failures
4167 Subdirectory daemon
4169 File daemon/command.c
4170 This file contains a number of useful functions for running external
4172 commands and capturing their output.
4173 Function "daemon/command.c:commandf"
4175 int
4177 commandf (char **stdoutput, char **stderror, unsigned flags,
4178 const char *name, ...)
4179 Run a command. Optionally capture stdout and stderr as strings.
4181 Returns 0 if the command ran successfully, or "-1" if there was any
4183 error.
4184 For a description of the "flags" see "commandrvf".
4186 There is also a macro "command(out,err,name,...)" which calls
4188 "commandf" with "flags=0".
4189 Function "daemon/command.c:commandrf"
4191 int
4193 commandrf (char **stdoutput, char **stderror, unsigned flags,
4194 const char *name, ...)
4195 Same as "command", but we allow the status code from the subcommand to
4197 be non-zero, and return that status code.
4198 We still return "-1" if there was some other error.
4200 There is also a macro "commandr(out,err,name,...)" which calls
4202 "commandrf" with "flags=0".
4203 Function "daemon/command.c:commandvf"
4205 int
4207 commandvf (char **stdoutput, char **stderror, unsigned flags,
4208 char const *const *argv)
4209 Same as "command", but passing in an argv array.
4211 There is also a macro "commandv(out,err,argv)" which calls "commandvf"
4213 with "flags=0".
4214 Function "daemon/command.c:commandrvf"
4216 int
4218 commandrvf (char **stdoutput, char **stderror, unsigned flags,
4219 char const* const *argv)
4220 This is a more sane version of system(3) for running external commands.
4222 It uses fork/execvp, so we don't need to worry about quoting of
4223 parameters, and it allows us to capture any error messages in a buffer.
4224 If "stdoutput" is not "NULL", then *stdoutput will return the stdout of
4226 the command as a string.
4227 If "stderror" is not "NULL", then *stderror will return the stderr of
4229 the command. If there is a final \n character, it is removed so you
4230 can use the error string directly in a call to "reply_with_error".
4231 Flags are:
4233 "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR"
4235 For broken external commands that send error messages to stdout
4236 (hello, parted) but that don't have any useful stdout information,
4237 use this flag to capture the error messages in the *stderror
4238 buffer. If using this flag, you should pass "stdoutput=NULL"
4239 because nothing could ever be captured in that buffer.
4240 "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN"
4242 For running external commands on chrooted files correctly (see
4243 https://bugzilla.redhat.com/579608) specifying this flag causes
4244 another process to be forked which chroots into sysroot and just
4245 copies the input file to stdin of the specified command. The file
4246 descriptor is ORed with the flags, and that file descriptor is
4247 always closed by this function. See daemon/hexdump.c for an
4248 example of usage.
4249 There is also a macro "commandrv(out,err,argv)" which calls
4251 "commandrvf" with "flags=0".
4252 File daemon/device-name-translation.c
4254 Function "daemon/device-name-translation.c:device_name_translation"
4256 char *
4258 device_name_translation (const char *device)
4259 Perform device name translation.
4261 It returns a newly allocated string which the caller must free.
4263 It returns "NULL" on error. Note it does not call "reply_with_*".
4265 We have to open the device and test for "ENXIO", because the device
4267 nodes may exist in the appliance.
4268 File daemon/guestfsd.c
4270 This is the guestfs daemon which runs inside the guestfs appliance.
4272 This file handles start up and connecting back to the library.
4273 Function "daemon/guestfsd.c:print_shell_quote"
4275 static int
4277 print_shell_quote (FILE *stream,
4278 const struct printf_info *info ATTRIBUTE_UNUSED,
4279 const void *const *args)
4280 printf helper function so we can use %Q ("quoted") and %R to print
4282 shell-quoted strings. See guestfs-hacking(1) for more details.
4283 File daemon/internal.c
4285 Internal functions that are not part of the public API.
4287 File daemon/utils-c.c
4289 Bindings for utility functions.
4291 Note that functions called from OCaml code must never call any of the
4293 "reply*" functions.
4294 File daemon/utils.c
4296 Miscellaneous utility functions used by the daemon.
4298 Function "daemon/utils.c:is_root_device_stat"
4300 static int
4302 is_root_device_stat (struct stat *statbuf)
4303 Return true iff device is the root device (and therefore should be
4305 ignored from the point of view of user calls).
4306 Function "daemon/utils.c:is_device_parameter"
4308 int
4310 is_device_parameter (const char *device)
4311 Parameters marked as "Device", "Dev_or_Path", etc can be passed a block
4313 device name. This function tests if the parameter is a block device
4314 name.
4315 It can also be used in daemon code to test if the string passed as a
4317 "Dev_or_Path" parameter is a device or path.
4318 Function "daemon/utils.c:sysroot_path"
4320 char *
4322 sysroot_path (const char *path)
4323 Turn "/path" into "/sysroot/path".
4325 Returns "NULL" on failure. The caller must check for this and call
4327 "reply_with_perror ("malloc")". The caller must also free the returned
4328 string.
4329 See also the custom %R printf formatter which does shell quoting too.
4331 Function "daemon/utils.c:sysroot_realpath"
4333 char *
4335 sysroot_realpath (const char *path)
4336 Resolve path within sysroot, calling "sysroot_path" on the resolved
4338 path.
4339 Returns "NULL" on failure. The caller must check for this and call
4341 "reply_with_perror ("malloc")". The caller must also free the returned
4342 string.
4343 See also the custom %R printf formatter which does shell quoting too.
4345 Function "daemon/utils.c:is_power_of_2"
4347 int
4349 is_power_of_2 (unsigned long v)
4350 Returns true if "v" is a power of 2.
4352 Uses the algorithm described at
4354 http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2
4355 Function "daemon/utils.c:split_lines_sb"
4357 struct stringsbuf
4359 split_lines_sb (char *str)
4360 Split an output string into a NULL-terminated list of lines, wrapped
4362 into a stringsbuf.
4363 Typically this is used where we have run an external command which has
4365 printed out a list of things, and we want to return an actual list.
4366 The corner cases here are quite tricky. Note in particular:
4368 "" returns "[]"
4370 "\n"
4372 returns "[""]"
4373 "a\nb"
4375 returns "["a"; "b"]"
4376 "a\nb\n"
4378 returns "["a"; "b"]"
4379 "a\nb\n\n"
4381 returns "["a"; "b"; ""]"
4382 The original string is written over and destroyed by this function
4384 (which is usually OK because it's the 'out' string from "command*()").
4385 You can free the original string, because "add_string()" strdups the
4386 strings.
4387 "argv" in the "struct stringsbuf" will be "NULL" in case of errors.
4389 Function "daemon/utils.c:trim"
4391 void
4393 trim (char *str)
4394 Skip leading and trailing whitespace, updating the original string in-
4396 place.
4397 Function "daemon/utils.c:parse_btrfsvol"
4399 int
4401 parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
4402 Parse the mountable descriptor for a btrfs subvolume. Don't call this
4404 directly; it is only used from the stubs.
4405 A btrfs subvolume is given as:
4407 btrfsvol:/dev/sda3/root
4409 where /dev/sda3 is a block device containing a btrfs filesystem, and
4411 root is the name of a subvolume on it. This function is passed the
4412 string following "btrfsvol:".
4413 On success, "mountable->device" and "mountable->volume" must be freed
4415 by the caller.
4416 Function "daemon/utils.c:mountable_to_string"
4418 char *
4420 mountable_to_string (const mountable_t *mountable)
4421 Convert a "mountable_t" back to its string representation
4423 This function can be used in an error path, so must not call
4425 "reply_with_error".
4426 Function "daemon/utils.c:prog_exists"
4428 int
4430 prog_exists (const char *prog)
4431 Check program exists and is executable on $PATH.
4433 Function "daemon/utils.c:random_name"
4435 int
4437 random_name (char *template)
4438 Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
4440 template to contain a randomly named file. Any 'X' characters after
4441 the final '/' in the template are replaced with random characters.
4442 Notes: You should probably use an 8.3 path, so it's compatible with all
4444 filesystems including basic FAT. Also this only substitutes lowercase
4445 ASCII letters and numbers, again for compatibility with lowest common
4446 denominator filesystems.
4447 This doesn't create a file or check whether or not the file exists (it
4449 would be extremely unlikely to exist as long as the RNG is working).
4450 If there is an error, "-1" is returned.
4452 Function "daemon/utils.c:udev_settle_file"
4454 void
4456 udev_settle_file (const char *file)
4457 LVM and other commands aren't synchronous, especially when udev is
4459 involved. eg. You can create or remove some device, but the "/dev"
4460 device node won't appear until some time later. This means that you
4461 get an error if you run one command followed by another.
4462 Use "udevadm settle" after certain commands, but don't be too fussed if
4464 it fails.
4465 Function "daemon/utils.c:make_exclude_from_file"
4467 char *
4469 make_exclude_from_file (const char *function, char *const *excludes)
4470 Turn list "excludes" into a temporary file, and return a string
4472 containing the temporary file name. Caller must unlink the file and
4473 free the string.
4474 "function" is the function that invoked this helper, and it is used
4476 mainly for errors/debugging.
4477 Subdirectory fish
4479 File fish/alloc.c
4480 This file implements the guestfish "alloc" and "sparse" commands.
4482 Function "fish/alloc.c:alloc_disk"
4484 int
4486 alloc_disk (const char *filename, const char *size_str, int add, int sparse)
4487 This is the underlying allocation function. It's called from a few
4489 other places in guestfish.
4490 File fish/copy.c
4492 This file implements the guestfish commands "copy-in" and "copy-out".
4494 File fish/destpaths.c
4496 The file handles tab-completion of filesystem paths in guestfish.
4498 File fish/display.c
4500 The file implements the guestfish "display" command, for displaying
4502 graphical files (icons, images) in disk images.
4503 File fish/echo.c
4505 The file implements the guestfish "echo" command.
4507 File fish/edit.c
4509 guestfish "edit" command, suggested by Ján Ondrej.
4511 File fish/events.c
4513 This file implements the guestfish event-related commands, "event",
4515 "delete-event" and "list-events".
4516 File fish/fish.c
4518 guestfish, the guest filesystem shell. This file contains the main
4520 loop and utilities.
4521 Function "fish/fish.c:parse_command_line"
4523 static struct parsed_command
4525 parse_command_line (char *buf, int *exit_on_error_rtn)
4526 Parse a command string, splitting at whitespace, handling '!', '#' etc.
4528 This destructively updates "buf".
4529 "exit_on_error_rtn" is used to pass in the global "exit_on_error"
4531 setting and to return the local setting (eg. if the command begins with
4532 '-').
4533 Returns in "parsed_command.status":
4535 1 got a guestfish command (returned in
4537 "cmd_rtn"/"argv_rtn"/"pipe_rtn")
4538 0 no guestfish command, but otherwise OK
4540 "-1"
4542 an error
4543 Function "fish/fish.c:parse_quoted_string"
4545 static ssize_t
4547 parse_quoted_string (char *p)
4548 Parse double-quoted strings, replacing backslash escape sequences with
4550 the true character. Since the string is returned in place, the escapes
4551 must make the string shorter.
4552 Function "fish/fish.c:execute_and_inline"
4554 static int
4556 execute_and_inline (const char *cmd, int global_exit_on_error)
4557 Used to handle "<!" (execute command and inline result).
4559 Function "fish/fish.c:issue_command"
4561 int
4563 issue_command (const char *cmd, char *argv[], const char *pipecmd,
4564 int rc_exit_on_error_flag)
4565 Run a command.
4567 "rc_exit_on_error_flag" is the "exit_on_error" flag that we pass to the
4569 remote server (when issuing --remote commands). It does not cause
4570 "issue_command" itself to exit on error.
4571 Function "fish/fish.c:extended_help_message"
4573 void
4575 extended_help_message (void)
4576 Print an extended help message when the user types in an unknown
4578 command for the first command issued. A common case is the user doing:
4579 guestfish disk.img
4581 expecting guestfish to open disk.img (in fact, this tried to run a non-
4583 existent command "disk.img").
4584 Function "fish/fish.c:error_cb"
4586 static void
4588 error_cb (guestfs_h *g, void *data, const char *msg)
4589 Error callback. This replaces the standard libguestfs error handler.
4591 Function "fish/fish.c:free_n_strings"
4593 static void
4595 free_n_strings (char **str, size_t len)
4596 Free strings from a non-NULL terminated "char**".
4598 Function "fish/fish.c:decode_ps1"
4600 static char *
4602 decode_ps1 (const char *str)
4603 Decode "str" into the final printable prompt string.
4605 Function "fish/fish.c:win_prefix"
4607 char *
4609 win_prefix (const char *path)
4610 Resolve the special "win:..." form for Windows-specific paths. The
4612 generated code calls this for all device or path arguments.
4613 The function returns a newly allocated string, and the caller must free
4615 this string; else display an error and return "NULL".
4616 Function "fish/fish.c:file_in"
4618 char *
4620 file_in (const char *arg)
4621 Resolve the special "FileIn" paths ("-" or "-<<END" or filename).
4623 The caller (fish/cmds.c) will call "free_file_in" after the command has
4625 run which should clean up resources.
4626 Function "fish/fish.c:file_out"
4628 char *
4630 file_out (const char *arg)
4631 Resolve the special "FileOut" paths ("-" or filename).
4633 The caller (fish/cmds.c) will call "free (str)" after the command has
4635 run.
4636 Function "fish/fish.c:progress_callback"
4638 void
4640 progress_callback (guestfs_h *g, void *data,
4641 uint64_t event, int event_handle, int flags,
4642 const char *buf, size_t buf_len,
4643 const uint64_t *array, size_t array_len)
4644 Callback which displays a progress bar.
4646 File fish/glob.c
4648 This file implements the guestfish "glob" command.
4650 Function "fish/glob.c:expand_devicename"
4652 static char **
4654 expand_devicename (guestfs_h *g, const char *device)
4655 Glob-expand device patterns, such as "/dev/sd*"
4657 (https://bugzilla.redhat.com/635971).
4658 There is no "guestfs_glob_expand_device" function because the
4660 equivalent can be implemented using functions like
4661 "guestfs_list_devices".
4662 It's not immediately clear what it means to expand a pattern like
4664 "/dev/sd*". Should that include device name translation? Should the
4665 result include partitions as well as devices?
4666 Should "/dev/" + "*" return every possible device and filesystem? How
4668 about VGs? LVs?
4669 To solve this what we do is build up a list of every device, partition,
4671 etc., then glob against that list.
4672 Notes for future work (XXX):
4674 · This doesn't handle device name translation. It wouldn't be too
4676 hard to add.
4677 · Could have an API function for returning all device-like things.
4679 Function "fish/glob.c:add_strings_matching"
4681 static int
4683 add_strings_matching (char **pp, const char *glob,
4684 char ***ret, size_t *size_r)
4685 Using POSIX fnmatch(3), find strings in the list "pp" which match
4687 pattern "glob". Add strings which match to the "ret" array. *size_r
4688 is the current size of the "ret" array, which is updated with the new
4689 size.
4690 Function "fish/glob.c:single_element_list"
4692 static char **
4694 single_element_list (const char *element)
4695 Return a single element list containing "element".
4697 File fish/help.c
4699 The file implements the guestfish "help" command.
4701 Function "fish/help.c:display_help"
4703 int
4705 display_help (const char *cmd, size_t argc, char *argv[])
4706 The "help" command.
4708 This used to just list all commands, but that's not very useful.
4710 Instead display some useful context-sensitive help. This could be
4711 improved if we knew how many drives had been added already, and whether
4712 anything was mounted.
4713 File fish/hexedit.c
4715 This file implements the guestfish "hexedit" command.
4717 File fish/lcd.c
4719 Function "fish/lcd.c:run_lcd"
4721 int
4723 run_lcd (const char *cmd, size_t argc, char *argv[])
4724 guestfish "lcd" command (similar to the "lcd" command in BSD ftp).
4726 File fish/man.c
4728 Function "fish/man.c:run_man"
4730 int
4732 run_man (const char *cmd, size_t argc, char *argv[])
4733 guestfish "man" command
4735 File fish/more.c
4737 This file implements the guestfish "more" command.
4739 File fish/prep.c
4741 This file implements the guestfish -N option for creating pre-prepared
4743 disk layouts.
4744 File fish/rc.c
4746 This file implements guestfish remote (command) support.
4748 Function "fish/rc.c:rc_listen"
4750 void
4752 rc_listen (void)
4753 The remote control server (ie. "guestfish --listen").
4755 Function "fish/rc.c:rc_remote"
4757 int
4759 rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
4760 int exit_on_error)
4761 The remote control client (ie. "guestfish --remote").
4763 File fish/reopen.c
4765 This file implements the guestfish "reopen" command.
4767 File fish/setenv.c
4769 This file implements the guestfish "setenv" and "unsetenv" commands.
4771 File fish/supported.c
4773 This file implements the guestfish "supported" command.
4775 File fish/tilde.c
4777 This file implements tilde ("~") expansion of home directories in
4779 guestfish(1).
4780 Function "fish/tilde.c:try_tilde_expansion"
4782 char *
4784 try_tilde_expansion (char *str)
4785 This is called from the script loop if we find a candidate for
4787 "~username" (tilde-expansion).
4788 Function "fish/tilde.c:expand_home"
4790 static char *
4792 expand_home (char *orig, const char *append)
4793 Return $HOME + append string.
4795 Function "fish/tilde.c:find_home_for_username"
4797 static const char *
4799 find_home_for_username (const char *username, size_t ulen)
4800 Lookup "username" (of length "ulen"), return home directory if found,
4802 or "NULL" if not found.
4803 File fish/time.c
4805 This file implements the guestfish "time" command.
4807 Subdirectory p2v
4809 File p2v/config.c
4810 Function "p2v/config.c:new_config"
4812 struct config *
4814 new_config (void)
4815 Allocate a new config struct.
4817 Function "p2v/config.c:copy_config"
4819 struct config *
4821 copy_config (struct config *old)
4822 Copy a config struct.
4824 Function "p2v/config.c:free_config"
4826 void
4828 free_config (struct config *c)
4829 Free a config struct.
4831 Function "p2v/config.c:print_config"
4833 void
4835 print_config (struct config *c, FILE *fp)
4836 Print the conversion parameters and other important information.
4838 File p2v/conversion.c
4840 This file manages the p2v conversion.
4842 The conversion is actually done by virt-v2v(1) running on the remote
4844 conversion server. This file manages running the remote command and
4845 provides callbacks for displaying the output.
4846 When virt-p2v operates in GUI mode, this code runs in a separate
4848 thread. When virt-p2v operates in kernel mode, this runs synchronously
4849 in the main thread.
4850 Function "p2v/conversion.c:generate_name"
4852 static void
4854 generate_name (struct config *config, const char *filename)
4855 Write the guest name into "filename".
4857 Function "p2v/conversion.c:generate_wrapper_script"
4859 static void
4861 generate_wrapper_script (struct config *config, const char *remote_dir,
4862 const char *filename)
4863 Construct the virt-v2v wrapper script.
4865 This will be sent to the remote server, and is easier than trying to
4867 "type" a long and complex single command line into the ssh connection
4868 when we start the conversion.
4869 Function "p2v/conversion.c:print_quoted"
4871 static void
4873 print_quoted (FILE *fp, const char *s)
4874 Print a shell-quoted string on "fp".
4876 Function "p2v/conversion.c:generate_system_data"
4878 static void
4880 generate_system_data (const char *dmesg_file,
4881 const char *lscpu_file,
4882 const char *lspci_file,
4883 const char *lsscsi_file,
4884 const char *lsusb_file)
4885 Collect data about the system running virt-p2v such as the dmesg output
4887 and lists of PCI devices. This is useful for diagnosis when things go
4888 wrong.
4889 If any command fails, this is non-fatal.
4891 Function "p2v/conversion.c:generate_p2v_version_file"
4893 static void
4895 generate_p2v_version_file (const char *p2v_version_file)
4896 Generate a file containing the version of virt-p2v.
4898 The version of virt-v2v is contained in the conversion log.
4900 File p2v/cpuid.c
4902 Find CPU vendor, topology and some CPU flags.
4904 lscpu (from util-linux) provides CPU vendor, topology and flags.
4906 ACPI can be read by seeing if /sys/firmware/acpi exists.
4908 CPU model is essentially impossible to get without using libvirt, but
4910 we cannot use libvirt for the reasons outlined in this message:
4911 https://www.redhat.com/archives/libvirt-users/2017-March/msg00071.html
4912 Note that #vCPUs and amount of RAM is handled by main.c.
4914 Function "p2v/cpuid.c:get_lscpu"
4916 static char **
4918 get_lscpu (void)
4919 Get the output of lscpu as a list of (key, value) pairs (as a flattened
4921 list of strings).
4922 Function "p2v/cpuid.c:get_field"
4924 static const char *
4926 get_field (char **lscpu, const char *key)
4927 Read a single field from lscpu output.
4929 If the field does not exist, returns "NULL".
4931 Function "p2v/cpuid.c:get_vendor"
4933 static void
4935 get_vendor (char **lscpu, struct cpu_config *cpu)
4936 Read the CPU vendor from lscpu output.
4938 Function "p2v/cpuid.c:get_topology"
4940 static void
4942 get_topology (char **lscpu, struct cpu_config *cpu)
4943 Read the CPU topology from lscpu output.
4945 Function "p2v/cpuid.c:get_flags"
4947 static void
4949 get_flags (char **lscpu, struct cpu_config *cpu)
4950 Read some important flags from lscpu output.
4952 Function "p2v/cpuid.c:get_acpi"
4954 static void
4956 get_acpi (struct cpu_config *cpu)
4957 Find out if the system uses ACPI.
4959 File p2v/gui.c
4961 This file implements almost all of the virt-p2v graphical user
4963 interface (GUI).
4964 The GUI has three main dialogs:
4966 Connection dialog
4968 The connection dialog is the one shown initially. It asks the user
4969 to type in the login details for the remote conversion server and
4970 invites the user to test the ssh connection.
4971 Conversion dialog
4973 The conversion dialog asks for information about the target VM (eg.
4974 the number of vCPUs required), and about what to convert (eg. which
4975 network interfaces should be copied and which should be ignored).
4976 Running dialog
4978 The running dialog is displayed when the P2V process is underway.
4979 It mainly displays the virt-v2v debug messages.
4980 Note that the other major dialog ("Configure network ...") is handled
4982 entirely by NetworkManager's nm-connection-editor(1) program and has
4983 nothing to do with this code.
4984 This file is written in a kind of "pseudo-Gtk" which is backwards
4986 compatible from Gtk 2.10 (RHEL 5) through at least Gtk 3.22. This is
4987 done using a few macros to implement old "gtk_*" functions or map them
4988 to newer functions. Supporting ancient Gtk is important because we
4989 want to provide a virt-p2v binary that can run on very old kernels, to
4990 support 32 bit and proprietary SCSI drivers.
4991 Function "p2v/gui.c:gui_conversion"
4993 void
4995 gui_conversion (struct config *config)
4996 The entry point from the main program.
4998 Note that "gtk_init" etc have already been called in "main".
5000 Function "p2v/gui.c:create_connection_dialog"
5002 static void
5004 create_connection_dialog (struct config *config)
5005 Create the connection dialog.
5007 This creates the dialog, but it is not displayed. See
5009 "show_connection_dialog".
5010 Function "p2v/gui.c:username_changed_callback"
5012 static void
5014 username_changed_callback (GtkWidget *w, gpointer data)
5015 If the username is "root", disable the sudo button.
5017 Function "p2v/gui.c:password_or_identity_changed_callback"
5019 static void
5021 password_or_identity_changed_callback (GtkWidget *w, gpointer data)
5022 The password or SSH identity URL entries are mutually exclusive, so if
5024 one contains text then disable the other. This function is called when
5025 the "changed" signal is received on either.
5026 Function "p2v/gui.c:show_connection_dialog"
5028 static void
5030 show_connection_dialog (void)
5031 Hide all other dialogs and show the connection dialog.
5033 Function "p2v/gui.c:test_connection_clicked"
5035 static void
5037 test_connection_clicked (GtkWidget *w, gpointer data)
5038 Callback from the "Test connection" button.
5040 This initiates a background thread which actually does the ssh to the
5042 conversion server and the rest of the testing (see
5043 "test_connection_thread").
5044 Function "p2v/gui.c:test_connection_thread"
5046 static void *
5048 test_connection_thread (void *data)
5049 Run "test_connection" (in a detached background thread). Once it
5051 finishes stop the spinner and set the spinner message appropriately.
5052 If the test is successful then we enable the "Next" button. If
5053 unsuccessful, an error is shown in the connection dialog.
5054 Function "p2v/gui.c:start_spinner"
5056 static gboolean
5058 start_spinner (gpointer user_data)
5059 Idle task called from "test_connection_thread" (but run on the main
5061 thread) to start the spinner in the connection dialog.
5062 Function "p2v/gui.c:stop_spinner"
5064 static gboolean
5066 stop_spinner (gpointer user_data)
5067 Idle task called from "test_connection_thread" (but run on the main
5069 thread) to stop the spinner in the connection dialog.
5070 Function "p2v/gui.c:test_connection_error"
5072 static gboolean
5074 test_connection_error (gpointer user_data)
5075 Idle task called from "test_connection_thread" (but run on the main
5077 thread) when there is an error. Display the error message and disable
5078 the "Next" button so the user is forced to correct it.
5079 Function "p2v/gui.c:test_connection_ok"
5081 static gboolean
5083 test_connection_ok (gpointer user_data)
5084 Idle task called from "test_connection_thread" (but run on the main
5086 thread) when the connection test was successful.
5087 Function "p2v/gui.c:configure_network_button_clicked"
5089 static void
5091 configure_network_button_clicked (GtkWidget *w, gpointer data)
5092 Callback from the "Configure network ..." button. This dialog is
5094 handled entirely by an external program which is part of
5095 NetworkManager.
5096 Function "p2v/gui.c:xterm_button_clicked"
5098 static void
5100 xterm_button_clicked (GtkWidget *w, gpointer data)
5101 Callback from the "XTerm ..." button.
5103 Function "p2v/gui.c:about_button_clicked"
5105 static void
5107 about_button_clicked (GtkWidget *w, gpointer data)
5108 Callback from the "About virt-p2v ..." button.
5110 See also p2v/about-authors.c and p2v/about-license.c.
5112 Function "p2v/gui.c:connection_next_clicked"
5114 static void
5116 connection_next_clicked (GtkWidget *w, gpointer data)
5117 Callback when the connection dialog "Next" button has been clicked.
5119 Function "p2v/gui.c:create_conversion_dialog"
5121 static void
5123 create_conversion_dialog (struct config *config)
5124 Create the conversion dialog.
5126 This creates the dialog, but it is not displayed. See
5128 "show_conversion_dialog".
5129 Function "p2v/gui.c:show_conversion_dialog"
5131 static void
5133 show_conversion_dialog (void)
5134 Hide all other dialogs and show the conversion dialog.
5136 Function "p2v/gui.c:set_info_label"
5138 static void
5140 set_info_label (void)
5141 Update the "Information" section in the conversion dialog.
5143 Note that "v2v_version" (the remote virt-v2v version) is read from the
5145 remote virt-v2v in the "test_connection" function.
5146 Function "p2v/gui.c:repopulate_output_combo"
5148 static void
5150 repopulate_output_combo (struct config *config)
5151 Repopulate the list of output drivers in the "Output to (-o)" combo.
5153 The list of drivers is read from the remote virt-v2v instance in
5154 "test_connection".
5155 Function "p2v/gui.c:populate_disks"
5157 static void
5159 populate_disks (GtkTreeView *disks_list)
5160 Populate the "Fixed hard disks" treeview.
5162 Function "p2v/gui.c:populate_removable"
5164 static void
5166 populate_removable (GtkTreeView *removable_list)
5167 Populate the "Removable media" treeview.
5169 Function "p2v/gui.c:populate_interfaces"
5171 static void
5173 populate_interfaces (GtkTreeView *interfaces_list)
5174 Populate the "Network interfaces" treeview.
5176 Function "p2v/gui.c:maybe_identify_click"
5178 static gboolean
5180 maybe_identify_click (GtkWidget *interfaces_list, GdkEventButton *event,
5181 gpointer data)
5182 When the user clicks on the interface name on the list of interfaces,
5184 we want to run "ethtool --identify", which usually makes some lights
5185 flash on the physical interface.
5186 We cannot catch clicks on the cell itself, so we have to go via a more
5188 obscure route. See http://stackoverflow.com/a/27207433 and
5189 https://en.wikibooks.org/wiki/GTK%2B_By_Example/Tree_View/Events
5190 Function "p2v/gui.c:conversion_back_clicked"
5192 static void
5194 conversion_back_clicked (GtkWidget *w, gpointer data)
5195 The conversion dialog "Back" button has been clicked.
5197 Function "p2v/gui.c:vcpus_or_memory_check_callback"
5199 static void
5201 vcpus_or_memory_check_callback (GtkWidget *w, gpointer data)
5202 Display a warning if the vCPUs or memory is outside the supported range
5204 (https://bugzilla.redhat.com/823758).
5205 Function "p2v/gui.c:create_running_dialog"
5207 static void
5209 create_running_dialog (void)
5210 Create the running dialog.
5212 This creates the dialog, but it is not displayed. See
5214 "show_running_dialog".
5215 Function "p2v/gui.c:show_running_dialog"
5217 static void
5219 show_running_dialog (void)
5220 Hide all other dialogs and show the running dialog.
5222 Function "p2v/gui.c:set_log_dir"
5224 static gboolean
5226 set_log_dir (gpointer user_data)
5227 Display the remote log directory in the running dialog.
5229 If this isn't called from the main thread, then you must only call it
5231 via an idle task ("g_idle_add").
5232 NB: This frees the remote_dir ("user_data" pointer) which was strdup'd
5234 in "notify_ui_callback".
5235 Function "p2v/gui.c:set_status"
5237 static gboolean
5239 set_status (gpointer user_data)
5240 Display the conversion status in the running dialog.
5242 If this isn't called from the main thread, then you must only call it
5244 via an idle task ("g_idle_add").
5245 NB: This frees the message ("user_data" pointer) which was strdup'd in
5247 "notify_ui_callback".
5248 Function "p2v/gui.c:add_v2v_output"
5250 static gboolean
5252 add_v2v_output (gpointer user_data)
5253 Append output from the virt-v2v process to the buffer, and scroll to
5255 ensure it is visible.
5256 This function is able to parse ANSI colour sequences and more.
5258 If this isn't called from the main thread, then you must only call it
5260 via an idle task ("g_idle_add").
5261 NB: This frees the message ("user_data" pointer) which was strdup'd in
5263 "notify_ui_callback".
5264 Function "p2v/gui.c:start_conversion_clicked"
5266 static void
5268 start_conversion_clicked (GtkWidget *w, gpointer data)
5269 Callback when the "Start conversion" button is clicked.
5271 Function "p2v/gui.c:start_conversion_thread"
5273 static void *
5275 start_conversion_thread (void *data)
5276 This is the background thread which performs the conversion.
5278 Function "p2v/gui.c:conversion_error"
5280 static gboolean
5282 conversion_error (gpointer user_data)
5283 Idle task called from "start_conversion_thread" (but run on the main
5285 thread) when there was an error during the conversion.
5286 Function "p2v/gui.c:conversion_finished"
5288 static gboolean
5290 conversion_finished (gpointer user_data)
5291 Idle task called from "start_conversion_thread" (but run on the main
5293 thread) when the conversion completed without errors.
5294 Function "p2v/gui.c:notify_ui_callback"
5296 static void
5298 notify_ui_callback (int type, const char *data)
5299 This is called from conversion.c:"start_conversion" when there is a
5301 status change or a log message.
5302 Function "p2v/gui.c:cancel_conversion_dialog"
5304 static void
5306 cancel_conversion_dialog (GtkWidget *w, gpointer data)
5307 This is called when the user clicks on the "Cancel conversion" button.
5309 Since conversions can run for a long time, and cancelling the
5310 conversion is non-recoverable, this function displays a confirmation
5311 dialog before cancelling the conversion.
5312 File p2v/inhibit.c
5314 This file is used to inhibit power saving, sleep, suspend etc during
5316 the conversion.
5317 The method it uses is to send a D-Bus message to logind, as described
5319 here:
5320 https://www.freedesktop.org/wiki/Software/systemd/inhibit/
5322 If virt-p2v is compiled without D-Bus support then this does nothing.
5324 Function "p2v/inhibit.c:inhibit_power_saving"
5326 int
5328 inhibit_power_saving (void)
5329 Inhibit all forms of power saving. A file descriptor is returned, and
5331 when the file descriptor is closed the inhibit is stopped.
5332 If the function returns "-1" then "Inhibit" operation could not be
5334 performed (eg. if we are compiled without D-Bus support, or there is
5335 some error contacting logind). This is not usually fatal from the
5336 point of view of the caller, conversion can continue.
5337 File p2v/kernel-cmdline.c
5339 Mini library to read and parse "/proc/cmdline".
5341 Function "p2v/kernel-cmdline.c:parse_cmdline_string"
5343 char **
5345 parse_cmdline_string (const char *cmdline)
5346 Read and parse "/proc/cmdline".
5348 We only support double quoting, consistent with the Linux
5350 documentation.
5351 https://www.kernel.org/doc/Documentation/kernel-parameters.txt
5352 systemd supports single and double quoting and single character
5354 escaping, but we don't support all that.
5355 Returns a list of key, value pairs, terminated by "NULL".
5357 File p2v/kernel-config.c
5359 Function "p2v/kernel-config.c:update_config_from_kernel_cmdline"
5361 void
5363 update_config_from_kernel_cmdline (struct config *c, char **cmdline)
5364 Read the kernel command line and parse out any "p2v.*" fields that we
5366 understand into the config struct.
5367 File p2v/kernel.c
5369 Kernel-driven, non-interactive configuration of virt-p2v.
5371 File p2v/main.c
5373 Function "p2v/main.c:partition_parent"
5375 static dev_t
5377 partition_parent (dev_t part_dev)
5378 Get parent device of a partition.
5380 Returns 0 if no parent device could be found.
5382 Function "p2v/main.c:device_contains"
5384 static int
5386 device_contains (const char *dev, dev_t root_device)
5387 Return true if the named device (eg. "dev == "sda"") contains the root
5389 filesystem. "root_device" is the major:minor of the root filesystem
5390 (eg. "8:1" if the root filesystem was /dev/sda1).
5391 This doesn't work for LVs and so on. However we only really care if
5393 this test works on the P2V ISO where the root device is a regular
5394 partition.
5395 Function "p2v/main.c:find_all_disks"
5397 static void
5399 find_all_disks (void)
5400 Enumerate all disks in /sys/block and add them to the global
5402 "all_disks" and "all_removable" arrays.
5403 Function "p2v/main.c:find_all_interfaces"
5405 static void
5407 find_all_interfaces (void)
5408 Enumerate all network interfaces in /sys/class/net and add them to the
5410 global "all_interfaces" array.
5411 File p2v/nbd.c
5413 This file handles the virt-p2v --nbd command line option and running
5415 either qemu-nbd(8) or nbdkit(1).
5416 Function "p2v/nbd.c:set_nbd_option"
5418 void
5420 set_nbd_option (const char *opt)
5421 The main program calls this to set the --nbd option.
5423 Function "p2v/nbd.c:test_nbd_servers"
5425 void
5427 test_nbd_servers (void)
5428 Test the --nbd option (or built-in default list) to see which servers
5430 are actually installed and appear to be working.
5431 Set the "use_server" global accordingly.
5433 Function "p2v/nbd.c:start_nbd_server"
5435 pid_t
5437 start_nbd_server (const char **ipaddr, int *port, const char *device)
5438 Start the NBD server.
5440 We previously tested all NBD servers (see "test_nbd_servers") and
5442 hopefully found one which will work.
5443 Returns the process ID (> 0) or 0 if there is an error.
5445 Function "p2v/nbd.c:socket_activation"
5447 static inline void
5449 socket_activation (int *fds, size_t nr_fds)
5450 Set up file descriptors and environment variables for socket
5452 activation.
5453 Note this function runs in the child between fork and exec.
5455 Function "p2v/nbd.c:start_qemu_nbd"
5457 static pid_t
5459 start_qemu_nbd (const char *device,
5460 const char *ipaddr, int port, int *fds, size_t nr_fds)
5461 Start a local qemu-nbd(1) process.
5463 If we are using socket activation, "fds" and "nr_fds" will contain the
5465 locally pre-opened file descriptors for this. Otherwise if "fds ==
5466 NULL" we pass the port number.
5467 Returns the process ID (> 0) or 0 if there is an error.
5469 Function "p2v/nbd.c:start_nbdkit"
5471 static pid_t
5473 start_nbdkit (const char *device,
5474 const char *ipaddr, int port, int *fds, size_t nr_fds)
5475 Start a local nbdkit(1) process using the nbdkit-file-plugin(1).
5477 If we are using socket activation, "fds" and "nr_fds" will contain the
5479 locally pre-opened file descriptors for this. Otherwise if "fds ==
5480 NULL" we pass the port number.
5481 Returns the process ID (> 0) or 0 if there is an error.
5483 Function "p2v/nbd.c:get_local_port"
5485 static int
5487 get_local_port (void)
5488 This is used when we are starting an NBD server that does not support
5490 socket activation. We have to pass the '-p' option to the NBD server,
5491 but there's no good way to choose a free port, so we have to just
5492 guess.
5493 Returns the port number on success or "-1" on error.
5495 Function "p2v/nbd.c:open_listening_socket"
5497 static int
5499 open_listening_socket (const char *ipaddr, int **fds, size_t *nr_fds)
5500 This is used when we are starting an NBD server which supports socket
5502 activation. We can open a listening socket on an unused local port and
5503 return it.
5504 Returns the port number on success or "-1" on error.
5506 The file descriptor(s) bound are returned in the array *fds, *nr_fds.
5508 The caller must free the array.
5509 Function "p2v/nbd.c:wait_for_nbd_server_to_start"
5511 int
5513 wait_for_nbd_server_to_start (const char *ipaddr, int port)
5514 Wait for a local NBD server to start and be listening for connections.
5516 Function "p2v/nbd.c:connect_with_source_port"
5518 static int
5520 connect_with_source_port (const char *hostname, int dest_port, int source_port)
5521 Connect to "hostname:dest_port", resolving the address using
5523 getaddrinfo(3).
5524 This also sets the source port of the connection to the first free port
5526 number ≥ "source_port".
5527 This may involve multiple connections - to IPv4 and IPv6 for instance.
5529 File p2v/physical-xml.c
5531 Create the physical.xml file, which is a piece of phony libvirt XML
5533 used to communicate the metadata of the physical machine to virt-v2v.
5534 Function "p2v/physical-xml.c:generate_physical_xml"
5536 void
5538 generate_physical_xml (struct config *config, struct data_conn *data_conns,
5539 const char *filename)
5540 Write the libvirt XML for this physical machine.
5542 Note this is not actually input for libvirt. It's input for virt-v2v
5544 on the conversion server. Virt-v2v will (if necessary) generate the
5545 final libvirt XML.
5546 Function "p2v/physical-xml.c:map_interface_to_network"
5548 static const char *
5550 map_interface_to_network (struct config *config, const char *interface)
5551 Using "config->network_map", map the interface to a target network
5553 name. If no map is found, return "default". See virt-p2v(1)
5554 documentation of "p2v.network" for how the network map works.
5555 Note this returns a static string which is only valid as long as
5557 "config->network_map" is not freed.
5558 File p2v/rtc.c
5560 Try to calculate Real Time Clock (RTC) offset from UTC in seconds. For
5562 example if the RTC is 1 hour ahead of UTC, this will return 3600. This
5563 is stored in "config->rtc_offset".
5564 Function "p2v/rtc.c:get_rtc_config"
5566 void
5568 get_rtc_config (struct rtc_config *rtc)
5569 Return RTC offset from UTC in seconds, positive numbers meaning that
5571 the RTC is running ahead of UTC.
5572 In the error case, "rtc>offset" is updated with 0 and "rtc>basis" is
5574 set to "BASIS_UNKNOWN".
5575 File p2v/ssh.c
5577 This file handles the ssh connections to the conversion server.
5579 virt-p2v will open several connections over the lifetime of the
5581 conversion process.
5582 In "test_connection", it will first open a connection (to check it is
5584 possible) and query virt-v2v on the server to ensure it exists, it is
5585 the right version, and so on. This connection is then closed, because
5586 in the GUI case we don't want to deal with keeping it alive in case the
5587 administrator has set up an autologout.
5588 Once we start conversion, we will open a control connection to send the
5590 libvirt configuration data and to start up virt-v2v, and we will open
5591 up one data connection per local hard disk. The data connection(s)
5592 have a reverse port forward to the local NBD server which is serving
5593 the content of that hard disk. The remote port for each data
5594 connection is assigned by ssh. See "open_data_connection" and
5595 "start_remote_conversion".
5596 Function "p2v/ssh.c:curl_download"
5598 static int
5600 curl_download (const char *url, const char *local_file)
5601 Download URL to local file using the external 'curl' command.
5603 Function "p2v/ssh.c:cache_ssh_identity"
5605 static int
5607 cache_ssh_identity (struct config *config)
5608 Re-cache the "config->identity.url" if needed.
5610 Function "p2v/ssh.c:start_ssh"
5612 static mexp_h *
5614 start_ssh (unsigned spawn_flags, struct config *config,
5615 char **extra_args, int wait_prompt)
5616 Start ssh subprocess with the standard arguments and possibly some
5618 optional arguments. Also handles authentication.
5619 Function "p2v/ssh.c:scp_file"
5621 int
5623 scp_file (struct config *config, const char *target, const char *local, ...)
5624 Upload file(s) to remote using scp(1).
5626 Note that the target (directory or file) comes before the list of local
5628 files, because the list of local files is a varargs list.
5629 This is a simplified version of "start_ssh" above.
5631 File p2v/utils.c
5633 Function "p2v/utils.c:get_blockdev_size"
5635 uint64_t
5637 get_blockdev_size (const char *dev)
5638 Return size of a block device, from /sys/block/dev/size.
5640 This function always succeeds, or else exits (since we expect "dev" to
5642 always be valid and the "size" file to always exist).
5643 Function "p2v/utils.c:get_blockdev_model"
5645 char *
5647 get_blockdev_model (const char *dev)
5648 Return model of a block device, from /sys/block/dev/device/model.
5650 Returns "NULL" if the file was not found. The caller must free the
5652 returned string.
5653 Function "p2v/utils.c:get_blockdev_serial"
5655 char *
5657 get_blockdev_serial (const char *dev)
5658 Return the serial number of a block device.
5660 This is found using the lsblk command.
5662 Returns "NULL" if we could not get the serial number. The caller must
5664 free the returned string.
5665 Function "p2v/utils.c:get_if_addr"
5667 char *
5669 get_if_addr (const char *if_name)
5670 Return contents of /sys/class/net/if_name/address (if found).
5672 Function "p2v/utils.c:get_if_vendor"
5674 char *
5676 get_if_vendor (const char *if_name, int truncate)
5677 Return contents of /sys/class/net/if_name/device/vendor (if found),
5679 mapped to the PCI vendor. See:
5680 http://pjwelsh.blogspot.co.uk/2011/11/howto-get-network-card-vendor-device-or.html
5681 Function "p2v/utils.c:wait_network_online"
5683 void
5685 wait_network_online (const struct config *config)
5686 Wait for the network to come online, but don't error out if that fails.
5688 The caller will call "test_connection" immediately after this which
5689 will fail if the network didn't come online.
5690 File p2v/whole-file.c
5692 Function "p2v/whole-file.c:read_whole_file"
5694 int
5696 read_whole_file (const char *filename, char **data_r, size_t *size_r)
5697 Read the whole file into a memory buffer and return it. The file
5699 should be a regular, local, trusted file.
5700 Subdirectory python
5702 File python/handle.c
5703 This file contains a small number of functions that are written by
5705 hand. The majority of the bindings are generated (see
5706 python/actions-*.c).
5707 Subdirectory v2v
5709 File v2v/libvirt_utils-c.c
5710 This module implements various "virsh"-like commands, but with non-
5712 broken authentication handling.
5713
5715 guestfs(3), guestfs-building(1), guestfs-examples(3),
5716 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
5717 guestfs-testing(1), libguestfs-test-tool(1),
5718 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
5719
5721 Richard W.M. Jones ("rjones at redhat dot com")
5722
5724 Copyright (C) 2009-2019 Red Hat Inc.
5725
5727 This library is free software; you can redistribute it and/or modify it
5728 under the terms of the GNU Lesser General Public License as published
5729 by the Free Software Foundation; either version 2 of the License, or
5730 (at your option) any later version.
5731 This library is distributed in the hope that it will be useful, but
5733 WITHOUT ANY WARRANTY; without even the implied warranty of
5734 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5735 Lesser General Public License for more details.
5736 You should have received a copy of the GNU Lesser General Public
5738 License along with this library; if not, write to the Free Software
5739 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
5740 02110-1301 USA
5741
5743 To get a list of bugs against libguestfs, use this link:
5744 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
5745 To report a new bug against libguestfs, use this link:
5747 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
5748 When reporting a bug, please supply:
5750 · The version of libguestfs.
5752 · Where you got libguestfs (eg. which Linux distro, compiled from
5754 source, etc)
5755 · Describe the bug accurately and give a way to reproduce it.
5757 · Run libguestfs-test-tool(1) and paste the complete, unedited output
5759 into the bug report.
5760libguestfs-1.40.2 2019-02-07 guestfs-hacking(1)