1guestfs-hacking(1) Virtualization Support guestfs-hacking(1)
2
6 guestfs-hacking - extending and contributing to libguestfs
7
9 This manual page is for hackers who want to extend libguestfs itself.
10
12 Libguestfs source is located in the github repository
13 https://github.com/libguestfs/libguestfs
14 Large amounts of boilerplate code in libguestfs (RPC, bindings,
16 documentation) are generated. This means that many source files will
17 appear to be missing from a straightforward git checkout. You have to
18 run the generator ("./configure && make -C generator") in order to
19 create those files.
20 Libguestfs uses an autotools-based build system, with the main files
22 being configure.ac and Makefile.am. See "THE BUILD SYSTEM".
23 The generator subdirectory contains the generator, plus files
25 describing the API. The lib subdirectory contains source for the
26 library. The appliance and daemon subdirectories contain the source
27 for the code that builds the appliance, and the code that runs in the
28 appliance respectively. Other directories are covered in the section
29 "SOURCE CODE SUBDIRECTORIES" below.
30 Apart from the fact that all API entry points go via some generated
32 code, the library is straightforward. (In fact, even the generated
33 code is designed to be readable, and should be read as ordinary code).
34 Some actions run entirely in the library, and are written as C
35 functions in files under lib. Others are forwarded to the daemon where
36 (after some generated RPC marshalling) they appear as C functions in
37 files under daemon.
38 To build from source, first read the guestfs-building(1).
40 SOURCE CODE SUBDIRECTORIES
42 There are a lot of subdirectories in the source tree! Which ones
43 should you concentrate on first? lib and daemon which contain the
44 source code of the core library. generator is the code generator
45 described above, so that is important. The Makefile.am in the root
46 directory will tell you in which order the subdirectories get built.
47 And then if you are looking at a particular tool (eg. customize) or
48 language binding (eg. python), go straight to that subdirectory, but
49 remember that if you didn't run the generator yet, then you may find
50 files which appear to be missing.
51 align
53 virt-alignment-scan(1) command and documentation.
54 appliance
56 The libguestfs appliance, build scripts and so on.
57 bash
59 Bash tab-completion scripts.
60 build-aux
62 Various build scripts used by autotools.
63 builder
65 virt-builder(1) command and documentation.
66 bundled
68 Embedded copies of other libraries, mostly for convenience (and the
69 embedded library is not widespread enough).
70 bundled/ocaml-augeas
72 Bindings for the Augeas library. These come from the ocaml-
73 augeas library http://git.annexia.org/?p=ocaml-augeas.git
74 cat The virt-cat(1), virt-filesystems(1), virt-log(1), virt-ls(1) and
76 virt-tail(1) commands and documentation.
77 common
79 Various libraries of internal code can be found in the common
80 subdirectory:
81 common/edit
83 Common code for interactively and non-interactively editing
84 files within a libguestfs filesystem.
85 common/errnostring
87 The communication protocol used between the library and the
88 daemon running inside the appliance has to encode errnos as
89 strings, which is handled by this library.
90 common/mlcustomize
92 Library code associated with "virt-customize" but also used in
93 other tools.
94 common/mlgettext
96 Small, generated wrapper which allows libguestfs to be compiled
97 with or without ocaml-gettext. This is generated by
98 ./configure.
99 common/mlpcre
101 Lightweight OCaml bindings for Perl Compatible Regular
102 Expressions (PCRE). Note this is not related in any way to
103 Markus Mottl's ocaml-pcre library.
104 common/mlprogress
106 OCaml bindings for the progress bar functions (see
107 common/progress).
108 common/mlstdutils
110 A library of pure OCaml utility functions used in many places.
111 common/mltools
113 OCaml utility functions only used by the OCaml virt tools (like
114 "virt-sysprep", "virt-customize" etc.)
115 common/mlutils
117 OCaml bindings for C functions in "common/utils", and some
118 POSIX bindings which are missing from the OCaml stdlib.
119 common/mlvisit
121 OCaml bindings for the visit functions (see common/visit).
122 common/mlxml
124 OCaml bindings for the libxml2 library.
125 common/options
127 Common options parsing for guestfish, guestmount and some virt
128 tools.
129 common/parallel
131 A framework used for processing multiple libvirt domains in
132 parallel.
133 common/progress
135 Common code for printing progress bars.
136 common/protocol
138 The XDR-based communication protocol used between the library
139 and the daemon running inside the appliance is defined here.
140 common/qemuopts
142 Mini-library for writing qemu command lines and qemu config
143 files.
144 common/structs
146 Common code for printing and freeing libguestfs structs, used
147 by the library and some tools.
148 common/utils
150 Various utility functions used throughout the library and
151 tools.
152 common/visit
154 Recursively visit a guestfs filesystem hierarchy.
155 common/windows
157 Utility functions for handling Windows drive letters.
158 contrib
160 Outside contributions, experimental parts.
161 customize
163 virt-customize(1) command and documentation.
164 daemon
166 The daemon that runs inside the libguestfs appliance and carries
167 out actions.
168 df virt-df(1) command and documentation.
170 dib virt-dib(1) command and documentation.
172 diff
174 virt-diff(1) command and documentation.
175 docs
177 Miscellaneous manual pages.
178 edit
180 virt-edit(1) command and documentation.
181 examples
183 C API example code.
184 fish
186 guestfish(1), the command-line shell, and various shell scripts
187 built on top such as virt-copy-in(1), virt-copy-out(1),
188 virt-tar-in(1), virt-tar-out(1).
189 format
191 virt-format(1) command and documentation.
192 fuse
194 guestmount(1), FUSE (userspace filesystem) built on top of
195 libguestfs.
196 generator
198 The crucially important generator, used to automatically generate
199 large amounts of boilerplate C code for things like RPC and
200 bindings.
201 get-kernel
203 virt-get-kernel(1) command and documentation.
204 inspector
206 virt-inspector(1), the virtual machine image inspector.
207 lib Source code to the C library.
209 logo
211 Logo used on the website. The fish is called Arthur by the way.
212 m4 M4 macros used by autoconf. See "THE BUILD SYSTEM".
214 make-fs
216 virt-make-fs(1) command and documentation.
217 po Translations of simple gettext strings.
219 po-docs
221 The build infrastructure and PO files for translations of manpages
222 and POD files. Eventually this will be combined with the po
223 directory, but that is rather complicated.
224 rescue
226 virt-rescue(1) command and documentation.
227 resize
229 virt-resize(1) command and documentation.
230 sparsify
232 virt-sparsify(1) command and documentation.
233 sysprep
235 virt-sysprep(1) command and documentation.
236 tests
238 Tests.
239 test-data
241 Files and other test data used by the tests.
242 test-tool
244 Test tool for end users to test if their qemu/kernel combination
245 will work with libguestfs.
246 tmp Used for temporary files when running the tests (instead of /tmp
248 etc). The reason is so that you can run multiple parallel tests of
249 libguestfs without having one set of tests overwriting the
250 appliance created by another.
251 tools
253 Command line tools written in Perl (virt-win-reg(1) and many
254 others).
255 utils
257 Miscellaneous utilities, such as "boot-benchmark".
258 v2v Up to libguestfs > 1.42 this contained the virt-v2v(1) tool, but
260 this has now moved into a separate repository:
261 https://github.com/libguestfs/virt-v2v
262 website
264 The http://libguestfs.org website files.
265 csharp
267 erlang
268 gobject
269 golang
270 haskell
271 java
272 lua
273 ocaml
274 php
275 perl
276 python
277 ruby
278 Language bindings.
279 THE BUILD SYSTEM
281 Libguestfs uses the GNU autotools build system (autoconf, automake,
282 libtool).
283 The ./configure script is generated from configure.ac and
285 m4/guestfs-*.m4. Most of the configure script is split over many m4
286 macro files by topic, for example m4/guestfs-daemon.m4 deals with the
287 dependencies of the daemon.
288 The job of the top level Makefile.am is mainly to list the
290 subdirectories ("SUBDIRS") in the order they should be compiled.
291 common-rules.mk is included in every Makefile.am (top level and
293 subdirectories). subdir-rules.mk is included only in subdirectory
294 Makefile.am files.
295 There are many make targets. Use this command to list them all:
297 make help
299
301 ADDING A NEW API
302 Because large amounts of boilerplate code in libguestfs are generated,
303 this makes it easy to extend the libguestfs API.
304 To add a new API action there are two changes:
306 1. You need to add a description of the call (name, parameters, return
308 type, tests, documentation) to generator/actions_*.ml and possibly
309 generator/proc_nr.ml.
310 There are two sorts of API action, depending on whether the call
312 goes through to the daemon in the appliance, or is serviced
313 entirely by the library (see "ARCHITECTURE" in
314 guestfs-internals(1)). "guestfs_sync" in guestfs(3) is an example
315 of the former, since the sync is done in the appliance.
316 "guestfs_set_trace" in guestfs(3) is an example of the latter,
317 since a trace flag is maintained in the handle and all tracing is
318 done on the library side.
319 Most new actions are of the first type, and get added to the
321 "daemon_functions" list. Each function has a unique procedure
322 number used in the RPC protocol which is assigned to that action
323 when we publish libguestfs and cannot be reused. Take the latest
324 procedure number and increment it.
325 For library-only actions of the second type, add to the
327 "non_daemon_functions" list. Since these functions are serviced by
328 the library and do not travel over the RPC mechanism to the daemon,
329 these functions do not need a procedure number, and so the
330 procedure number is set to "-1".
331 2. Implement the action (in C):
333 For daemon actions, implement the function "do_<name>" in the
335 "daemon/" directory.
336 For library actions, implement the function "guestfs_impl_<name>"
338 in the "lib/" directory.
339 In either case, use another function as an example of what to do.
341 3. As an alternative to step 2: Since libguestfs 1.38, daemon actions
343 can be implemented in OCaml. You have to set the "impl = OCaml
344 ..." flag in the generator. Take a look at daemon/file.ml for an
345 example.
346 After making these changes, use "make" to compile.
348 Note that you don’t need to implement the RPC, language bindings,
350 manual pages or anything else. It’s all automatically generated from
351 the OCaml description.
352 Adding tests for an API
354 You can supply zero or as many tests as you want per API call. The
356 tests can either be added as part of the API description
357 (generator/actions_*.ml), or in some rarer cases you may want to drop a
358 script into "tests/*/". Note that adding a script to "tests/*/" is
359 slower, so if possible use the first method.
360 The following describes the test environment used when you add an API
362 test in actions_*.ml.
363 The test environment has 4 block devices:
365 /dev/sda 2 GB
367 General block device for testing.
368 /dev/sdb 2 GB
370 /dev/sdb1 is an ext2 filesystem used for testing filesystem write
371 operations.
372 /dev/sdc 10 MB
374 Used in a few tests where two block devices are needed.
375 /dev/sdd
377 ISO with fixed content (see images/test.iso).
378 To be able to run the tests in a reasonable amount of time, the
380 libguestfs appliance and block devices are reused between tests. So
381 don't try testing "guestfs_kill_subprocess" in guestfs(3) :-x
382 Each test starts with an initial scenario, selected using one of the
384 "Init*" expressions, described in generator/types.ml. These initialize
385 the disks mentioned above in a particular way as documented in
386 types.ml. You should not assume anything about the previous contents
387 of other disks that are not initialized.
388 You can add a prerequisite clause to any individual test. This is a
390 run-time check, which, if it fails, causes the test to be skipped.
391 Useful if testing a command which might not work on all variations of
392 libguestfs builds. A test that has prerequisite of "Always" means to
393 run unconditionally.
394 In addition, packagers can skip individual tests by setting environment
396 variables before running "make check".
397 SKIP_TEST_<CMD>_<NUM>=1
399 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command" in
401 guestfs(3).
402 or:
404 SKIP_TEST_<CMD>=1
406 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" in guestfs(3)
408 tests.
409 Packagers can run only certain tests by setting for example:
411 TEST_ONLY="vfs_type zerofree"
413 See tests/c-api/tests.c for more details of how these environment
415 variables work.
416 Debugging new APIs
418 Test new actions work before submitting them.
420 You can use guestfish to try out new commands.
422 Debugging the daemon is a problem because it runs inside a minimal
424 environment. However you can fprintf messages in the daemon to stderr,
425 and they will show up if you use "guestfish -v".
426 ADDING A NEW LANGUAGE BINDING
428 All language bindings must be generated by the generator (see the
429 generator subdirectory).
430 There is no documentation for this yet. We suggest you look at an
432 existing binding, eg. generator/ocaml.ml or generator/perl.ml.
433 Adding tests for language bindings
435 Language bindings should come with tests. Previously testing of
437 language bindings was rather ad-hoc, but we have been trying to
438 formalize the set of tests that every language binding should use.
439 Currently only the OCaml and Perl bindings actually implement the full
441 set of tests, and the OCaml bindings are canonical, so you should
442 emulate what the OCaml tests do.
443 This is the numbering scheme used by the tests:
445 - 000+ basic tests:
447 010 load the library
449 020 create
450 030 create-flags
451 040 create multiple handles
452 050 test setting and getting config properties
453 060 explicit close
454 065 implicit close (in GC'd languages)
455 070 optargs
456 080 version
457 090 retvalues
458 - 100 launch, create partitions and LVs and filesystems
460 - 400+ events:
462 410 close event
464 420 log messages
465 430 progress messages
466 - 800+ regression tests (specific to the language)
468 - 900+ any other custom tests for the language
470 To save time when running the tests, only 100, 430, 800+, 900+ should
472 launch the handle.
473 FORMATTING CODE
475 Our C source code generally adheres to some basic code-formatting
476 conventions. The existing code base is not totally consistent on this
477 front, but we do prefer that contributed code be formatted similarly.
478 In short, use spaces-not-TABs for indentation, use 2 spaces for each
479 indentation level, and other than that, follow the K&R style.
480 If you use Emacs, add the following to one of your start-up files
482 (e.g., ~/.emacs), to help ensure that you get indentation right:
483 ;;; In libguestfs, indent with spaces everywhere (not TABs).
485 ;;; Exceptions: Makefile and ChangeLog modes.
486 (add-hook 'find-file-hook
487 '(lambda () (if (and buffer-file-name
488 (string-match "/libguestfs\\>"
489 (buffer-file-name))
490 (not (string-equal mode-name "Change Log"))
491 (not (string-equal mode-name "Makefile")))
492 (setq indent-tabs-mode nil))))
493 ;;; When editing C sources in libguestfs, use this style.
495 (defun libguestfs-c-mode ()
496 "C mode with adjusted defaults for use with libguestfs."
497 (interactive)
498 (c-set-style "K&R")
499 (setq c-indent-level 2)
500 (setq c-basic-offset 2))
501 (add-hook 'c-mode-hook
502 '(lambda () (if (string-match "/libguestfs\\>"
503 (buffer-file-name))
504 (libguestfs-c-mode))))
505 TESTING YOUR CHANGES
507 Turn warnings into errors when developing to make warnings hard to
508 ignore:
509 ./configure --enable-werror
511 Useful targets are:
513 "make check"
515 Runs the regular test suite.
516 This is implemented using the regular automake "TESTS" target. See
518 the automake documentation for details.
519 "make check-valgrind"
521 Runs a subset of the test suite under valgrind.
522 See "VALGRIND" below.
524 "make check-valgrind-local-guests"
526 Runs a subset of the test suite under valgrind using locally
527 installed libvirt guests (read-only).
528 "make check-direct"
530 Runs all tests using default appliance back-end. This only has any
531 effect if a non-default backend was selected using "./configure
532 --with-default-backend=..."
533 "make check-valgrind-direct"
535 Run a subset of the test suite under valgrind using the default
536 appliance back-end.
537 "make check-uml"
539 Runs all tests using the User-Mode Linux backend.
540 As there is no standard location for the User-Mode Linux kernel,
542 you have to set "LIBGUESTFS_HV" to point to the kernel image, eg:
543 make check-uml LIBGUESTFS_HV=~/d/linux-um/vmlinux
545 "make check-valgrind-uml"
547 Runs all tests using the User-Mode Linux backend, under valgrind.
548 As above, you have to set "LIBGUESTFS_HV" to point to the kernel.
550 "make check-with-upstream-qemu"
552 Runs all tests using a local qemu binary. It looks for the qemu
553 binary in QEMUDIR (defaults to $HOME/d/qemu), but you can set this
554 to another directory on the command line, eg:
555 make check-with-upstream-qemu QEMUDIR=/usr/src/qemu
557 "make check-with-upstream-libvirt"
559 Runs all tests using a local libvirt. This only has any effect if
560 the libvirt backend was selected using "./configure
561 --with-default-backend=libvirt"
562 It looks for libvirt in LIBVIRTDIR (defaults to $HOME/d/libvirt),
564 but you can set this to another directory on the command line, eg:
565 make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt
567 "make check-slow"
569 Runs some slow/long-running tests which are not run by default.
570 To mark a test as slow/long-running:
572 • Add it to the list of "TESTS" in the Makefile.am, just like a
574 normal test.
575 • Modify the test so it checks if the "SLOW=1" environment
577 variable is set, and if not set it skips (ie. returns with exit
578 code 77). If using $TEST_FUNCTIONS, you can call the function
579 "slow_test" for this.
580 • Add a variable "SLOW_TESTS" to the Makefile.am listing the slow
582 tests.
583 • Add a rule to the Makefile.am:
585 check-slow:
587 $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
588 "sudo make check-root"
590 Runs some tests which require root privileges. These are supposed
591 to be safe, but take care. You have to run this as root (eg. using
592 sudo(8) explicitly).
593 To mark a test as requiring root:
595 • Add it to the list of "TESTS" in the Makefile.am, just like a
597 normal test.
598 • Modify the test so it checks if euid == 0, and if not set it
600 skips (ie. returns with exit code 77). If using
601 $TEST_FUNCTIONS, you can call the function "root_test" for
602 this.
603 • Add a variable "ROOT_TESTS" to the Makefile.am listing the root
605 tests.
606 • Add a rule to the Makefile.am:
608 check-root:
610 $(MAKE) check TESTS="$(ROOT_TESTS)"
611 "make check-all"
613 Equivalent to running all "make check*" rules except "check-root".
614 "make check-release"
616 Runs a subset of "make check*" rules that are required to pass
617 before a tarball can be released. Currently this is:
618 • check
620 • check-valgrind
622 • check-direct
624 • check-valgrind-direct
626 • check-slow
628 "make installcheck"
630 Run "make check" on the installed copy of libguestfs.
631 The version of installed libguestfs being tested, and the version
633 of the libguestfs source tree must be the same.
634 Do:
636 ./configure
638 make clean ||:
639 make
640 make installcheck
641 VALGRIND
643 When you do "make check-valgrind", it searches for any Makefile.am in
644 the tree that has a "check-valgrind:" target and runs it.
645 Writing the Makefile.am and tests correctly to use valgrind and working
647 with automake parallel tests is subtle.
648 If your tests are run via a shell script wrapper, then in the wrapper
650 use:
651 $VG virt-foo
653 and in the Makefile.am use:
655 check-valgrind:
657 make VG="@VG@" check
658 However, if your binaries run directly from the "TESTS" rule, you have
660 to modify the Makefile.am like this:
661 LOG_COMPILER = $(VG)
663 check-valgrind:
665 make VG="@VG@" check
666 In either case, check that the right program is being tested by
668 examining the tmp/valgrind* log files carefully.
669 SUBMITTING PATCHES
671 Submit patches to the mailing list:
672 http://www.redhat.com/mailman/listinfo/libguestfs and CC to
673 rjones@redhat.com.
674 You do not need to subscribe to the mailing list if you don’t want to.
676 There may be a short delay while your message is moderated.
677 DAEMON CUSTOM PRINTF FORMATTERS
679 In the daemon code we have created custom printf formatters %Q and %R,
680 which are used to do shell quoting.
681 %Q Simple shell quoted string. Any spaces or other shell characters
683 are escaped for you.
684 %R Same as %Q except the string is treated as a path which is prefixed
686 by the sysroot.
687 For example:
689 asprintf (&cmd, "cat %R", path);
691 would produce "cat /sysroot/some\ path\ with\ spaces"
693 Note: Do not use these when you are passing parameters to the
695 "command{,r,v,rv}()" functions. These parameters do NOT need to be
696 quoted because they are not passed via the shell (instead, straight to
697 exec). You probably want to use the "sysroot_path()" function however.
698 INTERNATIONALIZATION (I18N) SUPPORT
700 We support i18n (gettext anyhow) in the library.
701 However many messages come from the daemon, and we don’t translate
703 those at the moment. One reason is that the appliance generally has
704 all locale files removed from it, because they take up a lot of space.
705 So we'd have to readd some of those, as well as copying our PO files
706 into the appliance.
707 Debugging messages are never translated, since they are intended for
709 the programmers.
710
712 HOW OCAML PROGRAMS ARE COMPILED AND LINKED
713 Mostly this section is "how we make automake & ocamlopt work together"
714 since OCaml programs themselves are easy to compile.
715 Automake has no native support for OCaml programs, ocamlc nor ocamlopt.
717 What we do instead is to treat OCaml programs as C programs which
718 happen to contain these "other objects" ("DEPENDENCIES" in automake-
719 speak) that happen to be the OCaml objects. This works because OCaml
720 programs usually have C files for native bindings etc.
721 So a typical program is described as just its C sources:
723 virt_customize_SOURCES = ... crypt-c.c perl_edit-c.c
725 For programs that have no explicit C sources, we create an empty
727 dummy.c file, and list that instead:
728 virt_resize_SOURCES = dummy.c
730 The OCaml objects which contain most of the code are listed as automake
732 dependencies (other dependencies may also be listed):
733 virt_customize_DEPENDENCIES = ... customize_main.cmx
735 The only other special thing we need to do is to provide a custom link
737 command. This is needed because automake won't assemble the ocamlopt
738 command, the list of objects and the "-cclib" libraries in the correct
739 order otherwise.
740 virt_customize_LINK = \
742 $(top_builddir)/ocaml-link.sh -cclib '-lutils' -- ...
743 The actual rules, which you can examine in customize/Makefile.am, are a
745 little bit more complicated than this because they have to handle:
746 • Compiling for byte code or native code.
748 • The pattern rules needed to compile the OCaml sources to objects.
750 These are now kept in subdir-rules.mk at the top level, which is
752 included in every subdirectory Makefile.am.
753 • Adding OCaml sources files to "EXTRA_DIST".
755 Automake isn't aware of the complete list of sources for a binary,
757 so it will not add them all automatically.
758
760 MAINTAINER MAKEFILE TARGETS
761 These "make" targets probably won’t work and aren't useful unless you
762 are a libguestfs maintainer.
763 make maintainer-commit
765 This commits everything in the working directory with the commit
767 message "Version $(VERSION).". You must update configure.ac, clean and
768 rebuild first.
769 make maintainer-tag
771 This tags the current HEAD commit with the tag "v$(VERSION)" and one of
773 the messages:
774 Version $(VERSION) stable
776 Version $(VERSION) development
778 (See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for the difference
780 between a stable and development release.)
781 make maintainer-check-authors
783 Check that all authors (found in git commit messages) are included in
785 the generator/authors.ml file.
786 make maintainer-check-extra-dist
788 This rule must be run after "make dist" (so there is a tarball in the
790 working directory). It compares the contents of the tarball with the
791 contents of git to ensure that no files have been missed from
792 Makefile.am "EXTRA_DIST" rules.
793 make maintainer-upload-website
795 This is used by the software used to automate libguestfs releases to
797 copy the libguestfs website to another git repository before it is
798 uploaded to the web server.
799 MAKING A STABLE RELEASE
801 When we make a stable release, there are several steps documented here.
802 See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for general information
803 about the stable branch policy.
804 • Check "make && make check" works on at least:
806 Fedora (x86-64)
808 Debian (x86-64)
809 Ubuntu (x86-64)
810 Fedora (aarch64)
811 Fedora (ppc64)
812 Fedora (ppc64le)
813 • Check "./configure --without-libvirt" works.
814 • Finalize guestfs-release-notes.pod
816 • Create new stable and development directories under
818 http://libguestfs.org/download.
819 • Edit website/index.html.in.
821 • Set the version (in configure.ac) to the new stable version, ie.
823 1.XX.0, and commit it:
824 ./localconfigure
826 make distclean -k
827 ./localconfigure
828 make && make dist
829 make maintainer-commit
830 make maintainer-tag
831 • Create the stable branch in git:
833 git branch stable-1.XX
835 git push origin stable-1.XX
836 • Do a full release of the stable branch.
838 • Set the version to the next development version and commit that.
840 Optionally do a full release of the development branch.
841
843 This section documents internal functions inside libguestfs and various
844 utilities. It is intended for libguestfs developers only.
845 This section is autogenerated from "/**" comments in source files,
847 which are marked up in POD format.
848 These functions are not publicly exported, and may change or be removed
850 at any time.
851 Subdirectory lib
853 File lib/actions-support.c
854 Helper functions for the actions code in lib/actions-*.c.
856 File lib/appliance-cpu.c
858 The appliance choice of CPU model.
860 Function "lib/appliance-cpu.c:guestfs_int_get_cpu_model"
862 const char *
864 guestfs_int_get_cpu_model (int kvm)
865 Return the right CPU model to use as the qemu "-cpu" parameter or its
867 equivalent in libvirt. This returns:
868 "host"
870 The literal string "host" means use "-cpu host".
871 "max"
873 The literal string "max" means use "-cpu max" (the best possible).
874 This requires awkward translation for libvirt.
875 some string
877 Some string such as "cortex-a57" means use "-cpu cortex-a57".
878 "NULL"
880 "NULL" means no "-cpu" option at all. Note returning "NULL" does
881 not indicate an error.
882 This is made unnecessarily hard and fragile because of two stupid
884 choices in QEMU:
885 • The default for "qemu-system-aarch64 -M virt" is to emulate a
887 "cortex-a15" (WTF?).
888 • We don't know for sure if KVM will work, but "-cpu host" is broken
890 with TCG, so we almost always pass a broken "-cpu" flag if KVM is
891 semi-broken in any way.
892 File lib/appliance-kcmdline.c
894 The appliance kernel command line.
896 Definition "lib/appliance-kcmdline.c:VALID_TERM"
898 #define VALID_TERM
900 Check that the $TERM environment variable is reasonable before we pass
902 it through to the appliance.
903 Function "lib/appliance-kcmdline.c:get_root_uuid_with_file"
905 static char *
907 get_root_uuid_with_file (guestfs_h *g, const char *appliance)
908 Given a disk image containing an extX filesystem, return the UUID.
910 Function "lib/appliance-kcmdline.c:run_qemu_img_dd"
912 static int
914 run_qemu_img_dd (guestfs_h *g, const char *in_file, char *out_file)
915 Read the first 256k bytes of the in_file with qemu-img(1) command and
917 write them into the out_file. That may be useful to get UUID of the
918 QCOW2 disk image with "get_root_uuid_with_file".
919 The function returns zero if successful, otherwise -1.
921 Function "lib/appliance-kcmdline.c:get_root_uuid"
923 static char *
925 get_root_uuid (guestfs_h *g, const char *appliance)
926 Get the UUID from the appliance disk image.
928 Function "lib/appliance-kcmdline.c:guestfs_int_appliance_command_line"
930 char *
932 guestfs_int_appliance_command_line (guestfs_h *g,
933 const char *appliance,
934 int flags)
935 Construct the Linux command line passed to the appliance. This is used
937 by the "direct" and "libvirt" backends, and is simply located in this
938 file because it's a convenient place for this common code.
939 The "appliance" parameter is the filename of the appliance (could be
941 NULL) from which we obtain the root UUID.
942 The "flags" parameter can contain the following flags logically or'd
944 together (or 0):
945 "APPLIANCE_COMMAND_LINE_IS_TCG"
947 If we are launching a qemu TCG guest (ie. KVM is known to be
948 disabled or unavailable). If you don't know, don't pass this flag.
949 Note that this function returns a newly allocated buffer which must be
951 freed by the caller.
952 File lib/appliance-uefi.c
954 Find the UEFI firmware needed to boot the appliance.
956 See also lib/uefi.c (autogenerated file) containing the firmware file
958 locations.
959 Function "lib/appliance-uefi.c:guestfs_int_get_uefi"
961 int
963 guestfs_int_get_uefi (guestfs_h *g, char *const *firmwares,
964 const char **firmware, char **code, char **vars,
965 int *flags)
966 Return the location of firmware needed to boot the appliance. This is
968 aarch64 only currently, since that's the only architecture where UEFI
969 is mandatory (and that only for RHEL).
970 "firmwares" is an optional list of allowed values for the firmware
972 autoselection of libvirt. It is "NULL" to indicate it is not supported.
973 *firmware is set to one of the strings in "firmwares" in case one can
974 be used.
975 *code is initialized with the path to the read-only UEFI code file.
977 *vars is initialized with the path to a copy of the UEFI vars file
978 (which is cleaned up automatically on exit).
979 In case a UEFI firmware is available, either *firmware is set to a
981 non-"NULL" value, or *code and *vars are.
982 *code and *vars should be freed by the caller, and *firmware must not.
984 If the function returns "-1" then there was a real error which should
986 cause appliance building to fail (no UEFI firmware is not an error).
987 See also virt-v2v.git/v2v/utils.ml:find_uefi_firmware
989 File lib/appliance.c
991 This file deals with building the libguestfs appliance.
993 Function "lib/appliance.c:guestfs_int_build_appliance"
995 int
997 guestfs_int_build_appliance (guestfs_h *g,
998 char **kernel_rtn,
999 char **initrd_rtn,
1000 char **appliance_rtn)
1001 Locate or build the appliance.
1003 This function locates or builds the appliance as necessary, handling
1005 the supermin appliance, caching of supermin-built appliances, or using
1006 either a fixed or old-style appliance.
1007 The return value is 0 = good, "-1" = error. Returned in
1009 "appliance.kernel" will be the name of the kernel to use,
1010 "appliance.initrd" the name of the initrd, "appliance.image" the name
1011 of the ext2 root filesystem. "appliance.image" can be "NULL", meaning
1012 that we are using an old-style (non-ext2) appliance. All three strings
1013 must be freed by the caller. However the referenced files themselves
1014 must not be deleted.
1015 The process is as follows:
1017 1. Look in "path" which contains a supermin appliance skeleton. If no
1019 element has this, skip straight to step 3.
1020 2. Call "supermin --build" to build the full appliance (if it needs to
1022 be rebuilt). If this is successful, return the full appliance.
1023 3. Check "path", looking for a fixed appliance. If one is found,
1025 return it.
1026 4. Check "path", looking for an old-style appliance. If one is found,
1028 return it.
1029 The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/
1031 and consists of up to four files:
1032 $TMPDIR/.guestfs-$UID/lock - the supermin lock file
1034 $TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
1035 $TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
1036 $TMPDIR/.guestfs-$UID/appliance.d/root - the appliance
1037 Multiple instances of libguestfs with the same UID may be racing to
1039 create an appliance. However (since supermin ≥ 5) supermin provides a
1040 --lock flag and atomic update of the appliance.d subdirectory.
1041 Function "lib/appliance.c:locate_or_build_appliance"
1043 static int
1045 locate_or_build_appliance (guestfs_h *g,
1046 struct appliance_files *appliance,
1047 const char *path)
1048 Check "path", looking for one of appliances: supermin appliance, fixed
1050 appliance or old-style appliance. If one of the fixed appliances is
1051 found, return it. If the supermin appliance skeleton is found, build
1052 and return appliance.
1053 Return values:
1055 1 = appliance is found, returns C<appliance>,
1057 0 = appliance not found,
1058 -1 = error which aborts the launch process.
1059 Function "lib/appliance.c:search_appliance"
1061 static int
1063 search_appliance (guestfs_h *g, struct appliance_files *appliance)
1064 Search elements of "g->path", returning the first "appliance" element
1066 which matches the predicate function "locate_or_build_appliance".
1067 Return values:
1069 1 = a path element matched, returns C<appliance>,
1071 0 = no path element matched,
1072 -1 = error which aborts the launch process.
1073 Function "lib/appliance.c:build_supermin_appliance"
1075 static int
1077 build_supermin_appliance (guestfs_h *g,
1078 const char *supermin_path,
1079 struct appliance_files *appliance)
1080 Build supermin appliance from "supermin_path" to $TMPDIR/.guestfs-$UID.
1082 Returns: 0 = built or "-1" = error (aborts launch).
1084 Function "lib/appliance.c:run_supermin_build"
1086 static int
1088 run_supermin_build (guestfs_h *g,
1089 const char *lockfile,
1090 const char *appliancedir,
1091 const char *supermin_path)
1092 Run "supermin --build" and tell it to generate the appliance.
1094 Function "lib/appliance.c:dir_contains_file"
1096 static int
1098 dir_contains_file (guestfs_h *g, const char *dir, const char *file)
1099 Returns true iff "file" is contained in "dir".
1101 Function "lib/appliance.c:dir_contains_files"
1103 static int
1105 dir_contains_files (guestfs_h *g, const char *dir, ...)
1106 Returns true iff every listed file is contained in "dir".
1108 File lib/command.c
1110 A wrapper for running external commands, loosely based on libvirt's
1112 "virCommand" interface.
1113 In outline to use this interface you must:
1115 1. Create a new command handle:
1117 struct command *cmd;
1119 cmd = guestfs_int_new_command (g);
1120 2. Either add arguments:
1122 guestfs_int_cmd_add_arg (cmd, "qemu-img");
1124 guestfs_int_cmd_add_arg (cmd, "info");
1125 guestfs_int_cmd_add_arg (cmd, filename);
1126 (NB: You don't need to add a "NULL" argument at the end.)
1128 3. Or construct a command using a mix of quoted and unquoted strings.
1130 (This is useful for system(3)/"popen("r")"-style shell commands,
1131 with the added safety of allowing args to be quoted properly).
1132 guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
1134 guestfs_int_cmd_add_string_quoted (cmd, filename);
1135 4. Set various flags, such as whether you want to capture errors in
1137 the regular libguestfs error log.
1138 5. Run the command. This is what does the fork(2) call, optionally
1140 loops over the output, and then does a waitpid(3) and returns the
1141 exit status of the command.
1142 r = guestfs_int_cmd_run (cmd);
1144 if (r == -1)
1145 // error
1146 // else test r using the WIF* functions
1147 6. Close the handle:
1149 guestfs_int_cmd_close (cmd);
1151 (or use "CLEANUP_CMD_CLOSE").
1153 Function "lib/command.c:guestfs_int_new_command"
1155 struct command *
1157 guestfs_int_new_command (guestfs_h *g)
1158 Create a new command handle.
1160 Function "lib/command.c:guestfs_int_cmd_add_arg"
1162 void
1164 guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)
1165 Add single arg (for "execv"-style command execution).
1167 Function "lib/command.c:guestfs_int_cmd_add_arg_format"
1169 void
1171 guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)
1172 Add single arg (for "execv"-style command execution) using a
1174 printf(3)-style format string.
1175 Function "lib/command.c:guestfs_int_cmd_add_string_unquoted"
1177 void
1179 guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)
1180 Add a string (for system(3)-style command execution).
1182 This variant adds the strings without quoting them, which is dangerous
1184 if the string contains untrusted content.
1185 Function "lib/command.c:guestfs_int_cmd_add_string_quoted"
1187 void
1189 guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)
1190 Add a string (for system(3)-style command execution).
1192 The string is enclosed in double quotes, with any special characters
1194 within the string which need escaping done. This is used to add a
1195 single argument to a system(3)-style command string.
1196 Function "lib/command.c:guestfs_int_cmd_set_stdout_callback"
1198 void
1200 guestfs_int_cmd_set_stdout_callback (struct command *cmd,
1201 cmd_stdout_callback stdout_callback,
1202 void *stdout_data, unsigned flags)
1203 Set a callback which will capture stdout.
1205 If flags contains "CMD_STDOUT_FLAG_LINE_BUFFER" (the default), then the
1207 callback is called line by line on the output. If there is a trailing
1208 "\n" then it is automatically removed before the callback is called.
1209 The line buffer is "\0"-terminated.
1210 If flags contains "CMD_STDOUT_FLAG_UNBUFFERED", then buffers are passed
1212 to the callback as it is received from the command. Note in this case
1213 the buffer is not "\0"-terminated, so you need to may attention to the
1214 length field in the callback.
1215 If flags contains "CMD_STDOUT_FLAG_WHOLE_BUFFER", then the callback is
1217 called exactly once, with the entire buffer. Note in this case the
1218 buffer is not "\0"-terminated, so you need to may attention to the
1219 length field in the callback.
1220 Function "lib/command.c:guestfs_int_cmd_set_stderr_to_stdout"
1222 void
1224 guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)
1225 Equivalent to adding "2>&1" to the end of the command. This is
1227 incompatible with the "capture_errors" flag, because it doesn't make
1228 sense to combine them.
1229 Function "lib/command.c:guestfs_int_cmd_clear_capture_errors"
1231 void
1233 guestfs_int_cmd_clear_capture_errors (struct command *cmd)
1234 Clear the "capture_errors" flag. This means that any errors will go to
1236 stderr, instead of being captured in the event log, and that is usually
1237 undesirable.
1238 Function "lib/command.c:guestfs_int_cmd_clear_close_files"
1240 void
1242 guestfs_int_cmd_clear_close_files (struct command *cmd)
1243 Don't close file descriptors after the fork.
1245 XXX Should allow single fds to be sent to child process.
1247 Function "lib/command.c:guestfs_int_cmd_set_child_callback"
1249 void
1251 guestfs_int_cmd_set_child_callback (struct command *cmd,
1252 cmd_child_callback child_callback,
1253 void *data)
1254 Set a function to be executed in the child, right before the execution.
1256 Can be used to setup the child, for example changing its current
1257 directory.
1258 Function "lib/command.c:guestfs_int_cmd_set_child_rlimit"
1260 void
1262 guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)
1263 Set up child rlimits, in case the process we are running could consume
1265 lots of space or time.
1266 Function "lib/command.c:finish_command"
1268 static void
1270 finish_command (struct command *cmd)
1271 Finish off the command by either "NULL"-terminating the argv array or
1273 adding a terminating "\0" to the string, or die with an internal error
1274 if no command has been added.
1275 Function "lib/command.c:loop"
1277 static int
1279 loop (struct command *cmd)
1280 The loop which reads errors and output and directs it either to the log
1282 or to the stdout callback as appropriate.
1283 Function "lib/command.c:guestfs_int_cmd_run"
1285 int
1287 guestfs_int_cmd_run (struct command *cmd)
1288 Fork, run the command, loop over the output, and waitpid.
1290 Returns the exit status. Test it using "WIF*" macros.
1292 On error: Calls "error" and returns "-1".
1294 Function "lib/command.c:guestfs_int_cmd_pipe_run"
1296 int
1298 guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)
1299 Fork and run the command, but don't wait. Roughly equivalent to
1301 "popen (..., "r"|"w")".
1302 Returns the file descriptor of the pipe, connected to stdout ("r") or
1304 stdin ("w") of the child process.
1305 After reading/writing to this pipe, call "guestfs_int_cmd_pipe_wait" to
1307 wait for the status of the child.
1308 Errors from the subcommand cannot be captured to the error log using
1310 this interface. Instead the caller should call
1311 "guestfs_int_cmd_get_pipe_errors" (after "guestfs_int_cmd_pipe_wait"
1312 returns an error).
1313 Function "lib/command.c:guestfs_int_cmd_pipe_wait"
1315 int
1317 guestfs_int_cmd_pipe_wait (struct command *cmd)
1318 Wait for a subprocess created by "guestfs_int_cmd_pipe_run" to finish.
1320 On error (eg. failed syscall) this returns "-1" and sets the error. If
1321 the subcommand fails, then use "WIF*" macros to check this, and call
1322 "guestfs_int_cmd_get_pipe_errors" to read the error messages printed by
1323 the child.
1324 Function "lib/command.c:guestfs_int_cmd_get_pipe_errors"
1326 char *
1328 guestfs_int_cmd_get_pipe_errors (struct command *cmd)
1329 Read the error messages printed by the child. The caller must free the
1331 returned buffer after use.
1332 Function "lib/command.c:guestfs_int_cmd_close"
1334 void
1336 guestfs_int_cmd_close (struct command *cmd)
1337 Close the "cmd" object and free all resources.
1339 Function "lib/command.c:process_line_buffer"
1341 static void
1343 process_line_buffer (struct command *cmd, int closed)
1344 Deal with buffering stdout for the callback.
1346 File lib/conn-socket.c
1348 This file handles connections to the child process where this is done
1350 over regular POSIX sockets.
1351 Function "lib/conn-socket.c:handle_log_message"
1353 static int
1355 handle_log_message (guestfs_h *g,
1356 struct connection_socket *conn)
1357 This is called if "conn->console_sock" becomes ready to read while we
1359 are doing one of the connection operations above. It reads and deals
1360 with the log message.
1361 Returns:
1363 1 log message(s) were handled successfully
1365 0 connection to appliance closed
1367 "-1"
1369 error
1370 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_listening"
1372 struct connection *
1374 guestfs_int_new_conn_socket_listening (guestfs_h *g,
1375 int daemon_accept_sock,
1376 int console_sock)
1377 Create a new socket connection, listening.
1379 Note that it's OK for "console_sock" to be passed as "-1", meaning
1381 there's no console available for this appliance.
1382 After calling this, "daemon_accept_sock" is owned by the connection,
1384 and will be closed properly either in "accept_connection" or
1385 "free_connection".
1386 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_connected"
1388 struct connection *
1390 guestfs_int_new_conn_socket_connected (guestfs_h *g,
1391 int daemon_sock,
1392 int console_sock)
1393 Create a new socket connection, connected.
1395 As above, but the caller passes us a connected "daemon_sock" and
1397 promises not to call "accept_connection".
1398 File lib/create.c
1400 APIs for creating empty disks.
1402 Mostly this consists of wrappers around the qemu-img(1) program.
1404 Definition "lib/create.c:VALID_FORMAT"
1406 #define VALID_FORMAT
1408 Check for valid backing format. Allow any "^[[:alnum]]+$" (in C
1410 locale), but limit the length to something reasonable.
1411 File lib/drives.c
1413 Drives added are stored in an array in the handle. Code here manages
1415 that array and the individual "struct drive" data.
1416 Function "lib/drives.c:create_overlay"
1418 static int
1420 create_overlay (guestfs_h *g, struct drive *drv)
1421 For readonly drives, create an overlay to protect the original drive
1423 content. Note we never need to clean up these overlays since they are
1424 created in the temporary directory and deleted when the handle is
1425 closed.
1426 Function "lib/drives.c:create_drive_file"
1428 static struct drive *
1430 create_drive_file (guestfs_h *g,
1431 const struct drive_create_data *data)
1432 Create and free the "struct drive".
1434 Function "lib/drives.c:create_drive_dev_null"
1436 static struct drive *
1438 create_drive_dev_null (guestfs_h *g,
1439 struct drive_create_data *data)
1440 Create the special /dev/null drive.
1442 Traditionally you have been able to use /dev/null as a filename, as
1444 many times as you like. Ancient KVM (RHEL 5) cannot handle adding
1445 /dev/null readonly. qemu 1.2 + virtio-scsi segfaults when you use any
1446 zero-sized file including /dev/null.
1447 Because of these problems, we replace /dev/null with a non-zero sized
1449 temporary file. This shouldn't make any difference since users are not
1450 supposed to try and access a null drive.
1451 Function "lib/drives.c:drive_to_string"
1453 static char *
1455 drive_to_string (guestfs_h *g, const struct drive *drv)
1456 Convert a "struct drive" to a string for debugging. The caller must
1458 free this string.
1459 Function "lib/drives.c:add_drive_to_handle_at"
1461 static void
1463 add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)
1464 Add "struct drive" to the "g->drives" vector at the given index
1466 "drv_index". If the array isn't large enough it is reallocated. The
1467 index must not contain a drive already.
1468 Function "lib/drives.c:add_drive_to_handle"
1470 static void
1472 add_drive_to_handle (guestfs_h *g, struct drive *d)
1473 Add struct drive to the end of the "g->drives" vector in the handle.
1475 Function "lib/drives.c:guestfs_int_add_dummy_appliance_drive"
1477 void
1479 guestfs_int_add_dummy_appliance_drive (guestfs_h *g)
1480 Called during launch to add a dummy slot to "g->drives".
1482 Function "lib/drives.c:guestfs_int_free_drives"
1484 void
1486 guestfs_int_free_drives (guestfs_h *g)
1487 Free up all the drives in the handle.
1489 Definition "lib/drives.c:VALID_FORMAT_IFACE"
1491 #define VALID_FORMAT_IFACE
1493 Check string parameter matches regular expression "^[-_[:alnum:]]+$"
1495 (in C locale).
1496 Definition "lib/drives.c:VALID_DISK_LABEL"
1498 #define VALID_DISK_LABEL
1500 Check the disk label is reasonable. It can't contain certain
1502 characters, eg. '/', ','. However be stricter here and ensure it's
1503 just alphabetic and ≤ 20 characters in length.
1504 Definition "lib/drives.c:VALID_HOSTNAME"
1506 #define VALID_HOSTNAME
1508 Check the server hostname is reasonable.
1510 Function "lib/drives.c:valid_port"
1512 static int
1514 valid_port (int port)
1515 Check the port number is reasonable.
1517 Function "lib/drives.c:valid_blocksize"
1519 static int
1521 valid_blocksize (int blocksize)
1522 Check the block size is reasonable. It can't be other then 512 or
1524 4096.
1525 Function "lib/drives.c:guestfs_impl_remove_drive"
1527 int
1529 guestfs_impl_remove_drive (guestfs_h *g, const char *label)
1530 This function implements "guestfs_remove_drive" in guestfs(3).
1532 Depending on whether we are hotplugging or not, this function does
1534 slightly different things: If not hotplugging, then the drive just
1535 disappears as if it had never been added. The later drives "move up"
1536 to fill the space. When hotplugging we have to do some complex stuff,
1537 and we usually end up leaving an empty ("NULL") slot in the "g->drives"
1538 vector.
1539 Function "lib/drives.c:guestfs_int_checkpoint_drives"
1541 size_t
1543 guestfs_int_checkpoint_drives (guestfs_h *g)
1544 Checkpoint and roll back drives, so that groups of drives can be added
1546 atomically. Only used by "guestfs_add_domain" in guestfs(3).
1547 Function "lib/drives.c:guestfs_impl_debug_drives"
1549 char **
1551 guestfs_impl_debug_drives (guestfs_h *g)
1552 Internal function to return the list of drives.
1554 File lib/errors.c
1556 This file handles errors, and also debug, trace and warning messages.
1558 Errors in libguestfs API calls are handled by setting an error message
1560 and optional errno in the handle. The caller has the choice of testing
1561 API calls to find out if they failed and then querying the last error
1562 from the handle, and/or getting a callback.
1563 From the point of view of the library source, generally you should use
1565 the "error" or "perrorf" macros along error paths, eg:
1566 if (something_bad) {
1568 error (g, "something bad happened");
1569 return -1;
1570 }
1571 Make sure to call the "error" or "perrorf" macro exactly once along
1573 each error path, since the handle can only store a single error and the
1574 previous error will be overwritten.
1575 Function "lib/errors.c:guestfs_int_warning"
1577 void
1579 guestfs_int_warning (guestfs_h *g, const char *fs, ...)
1580 Print a warning.
1582 Code should not call this function directly. Use the
1584 "warning (g, fs, ...)" macro.
1585 Warnings are printed unconditionally. We try to make these rare:
1587 Generally speaking, a warning should either be an error, or if it's not
1588 important for end users then it should be a debug message.
1589 Function "lib/errors.c:guestfs_int_debug"
1591 void
1593 guestfs_int_debug (guestfs_h *g, const char *fs, ...)
1594 Print a debug message.
1596 Code should not call this function directly. To add debug messages in
1598 the library, use the "debug (g, fs, ...)" macro. The macro checks if
1599 "g->verbose" is false and avoids the function call, meaning the macro
1600 is more efficient.
1601 Function "lib/errors.c:guestfs_int_trace"
1603 void
1605 guestfs_int_trace (guestfs_h *g, const char *fs, ...)
1606 Print a trace message.
1608 Do not call this function. All calls are generated automatically.
1610 Function "lib/errors.c:guestfs_int_error_errno"
1612 void
1614 guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)
1615 Set the last error and errno in the handle, and optionally raise the
1617 error callback if one is defined.
1618 If you don't need to set errno, use the "error (g, fs, ...)" macro
1620 instead of calling this directly. If you need to set errno then there
1621 is no macro wrapper, so calling this function directly is fine.
1622 Function "lib/errors.c:guestfs_int_perrorf"
1624 void
1626 guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)
1627 Similar to perror(3), but it sets the last error in the handle, raises
1629 the error callback if one is defined, and supports format strings.
1630 You should probably use the "perrorf (g, fs, ...)" macro instead of
1632 calling this directly.
1633 Function "lib/errors.c:guestfs_int_launch_failed_error"
1635 void
1637 guestfs_int_launch_failed_error (guestfs_h *g)
1638 Raise a launch failed error in a standard format.
1640 Since this is the most common error seen by people who have
1642 installation problems, buggy qemu, etc, and since no one reads the FAQ,
1643 describe in this error message what resources are available to debug
1644 launch problems.
1645 Function "lib/errors.c:guestfs_int_unexpected_close_error"
1647 void
1649 guestfs_int_unexpected_close_error (guestfs_h *g)
1650 Raise an error if the appliance unexpectedly crashes after launch.
1652 Function "lib/errors.c:guestfs_int_launch_timeout"
1654 void
1656 guestfs_int_launch_timeout (guestfs_h *g)
1657 Raise an error if the appliance hangs during launch.
1659 Function "lib/errors.c:guestfs_int_external_command_failed"
1661 void
1663 guestfs_int_external_command_failed (guestfs_h *g, int status,
1664 const char *cmd_name, const char *extra)
1665 Raise an error if an external command fails.
1667 "status" is the status code of the command (eg. returned from
1669 waitpid(2) or system(3)). This function turns the status code into an
1670 explanatory string.
1671 File lib/events.c
1673 Function "lib/events.c:replace_old_style_event_callback"
1675 static void
1677 replace_old_style_event_callback (guestfs_h *g,
1678 guestfs_event_callback cb,
1679 uint64_t event_bitmask,
1680 void *opaque,
1681 void *opaque2)
1682 Emulate old-style callback API.
1684 There were no event handles, so multiple callbacks per event were not
1686 supported. Calling the same "guestfs_set_*_callback" function would
1687 replace the existing event. Calling it with "cb == NULL" meant that
1688 the caller wanted to remove the callback.
1689 File lib/guestfs-internal-all.h
1691 This header contains definitions which are shared by all parts of
1693 libguestfs, ie. the daemon, the library, language bindings and virt
1694 tools (ie. all C code).
1695 If you need a definition used by only the library, put it in
1697 lib/guestfs-internal.h instead.
1698 If a definition is used by only a single tool, it should not be in any
1700 shared header file at all.
1701 File lib/guestfs-internal.h
1703 This header file is included in the libguestfs library (lib/) only.
1705 See also lib/guestfs-internal-all.h.
1707 Structure "lib/guestfs-internal.h:event"
1709 struct event {
1711 uint64_t event_bitmask;
1712 guestfs_event_callback cb;
1713 void *opaque;
1714 /* opaque2 is not exposed through the API, but is used internally to
1716 * emulate the old-style callback API.
1717 */
1718 void *opaque2;
1719 };
1720 This struct is used to maintain a list of events registered against the
1722 handle. See "g->events" in the handle.
1723 Structure "lib/guestfs-internal.h:drive"
1725 struct drive {
1727 /* Original source of the drive, eg. file:..., http:... */
1728 struct drive_source src;
1729 /* If the drive is readonly, then an overlay [a local file] is
1731 * created before launch to protect the original drive content, and
1732 * the filename is stored here. Backends should open this file if
1733 * it is non-NULL, else consult the original source above.
1734 *
1735 * Note that the overlay is in a backend-specific format, probably
1736 * different from the source format. eg. qcow2, UML COW.
1737 */
1738 char *overlay;
1739 /* Various per-drive flags. */
1741 bool readonly;
1742 char *iface;
1743 char *name;
1744 char *disk_label;
1745 char *cachemode;
1746 enum discard discard;
1747 bool copyonread;
1748 int blocksize;
1749 };
1750 There is one "struct drive" per drive, including hot-plugged drives.
1752 Structure "lib/guestfs-internal.h:backend_ops"
1754 struct backend_ops {
1756 /* Size (in bytes) of the per-handle data structure needed by this
1757 * backend. The data pointer is allocated and freed by libguestfs
1758 * and passed to the functions in the 'void *data' parameter.
1759 * Inside the data structure is opaque to libguestfs. Any strings
1760 * etc pointed to by it must be freed by the backend during
1761 * shutdown.
1762 */
1763 size_t data_size;
1764 /* Create a COW overlay on top of a drive. This must be a local
1766 * file, created in the temporary directory. This is called when
1767 * the drive is added to the handle.
1768 */
1769 char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);
1770 /* Launch and shut down. */
1772 int (*launch) (guestfs_h *g, void *data, const char *arg);
1773 int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);
1774 /* Miscellaneous. */
1776 int (*get_pid) (guestfs_h *g, void *data);
1777 int (*max_disks) (guestfs_h *g, void *data);
1778 /* Hotplugging drives. */
1780 int (*hot_add_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1781 int (*hot_remove_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index);
1782 };
1783 Backend operations.
1785 Each backend (eg. libvirt, direct) defines some functions which get run
1787 at various places in the handle lifecycle (eg. at launch, shutdown).
1788 The backend defines this struct pointing to those functions.
1789 Structure "lib/guestfs-internal.h:connection"
1791 struct connection {
1793 const struct connection_ops *ops;
1794 /* In the real struct, private data used by each connection module
1796 * follows here.
1797 */
1798 };
1799 Connection module.
1801 A "connection" represents the appliance console connection plus the
1803 daemon connection. It hides the underlying representation (POSIX
1804 sockets, "virStreamPtr").
1805 Structure "lib/guestfs-internal.h:cached_feature"
1807 struct cached_feature {
1809 char *group;
1810 int result;
1811 };
1812 Cache of queried features.
1814 Used to cache the appliance features (see lib/available.c).
1816 Structure "lib/guestfs-internal.h:guestfs_h"
1818 struct guestfs_h {
1820 struct guestfs_h *next; /* Linked list of open handles. */
1821 enum state state; /* See the state machine diagram in guestfs(3)*/
1822 /* Lock acquired when entering any public guestfs_* function to
1824 * protect the handle.
1825 */
1826 pthread_mutex_t lock;
1827 /**** Configuration of the handle. ****/
1829 bool verbose; /* Debugging. */
1830 bool trace; /* Trace calls. */
1831 bool autosync; /* Autosync. */
1832 bool direct_mode; /* Direct mode. */
1833 bool recovery_proc; /* Create a recovery process. */
1834 bool enable_network; /* Enable the network. */
1835 bool selinux; /* selinux enabled? */
1836 bool pgroup; /* Create process group for children? */
1837 bool close_on_exit; /* Is this handle on the atexit list? */
1838 int smp; /* If > 1, -smp flag passed to hv. */
1840 int memsize; /* Size of RAM (megabytes). */
1841 char *path; /* Path to the appliance. */
1843 char *hv; /* Hypervisor (HV) binary. */
1844 char *append; /* Append to kernel command line. */
1845 struct hv_param *hv_params; /* Extra hv parameters. */
1847 char *program; /* Program name. */
1849 char *identifier; /* Handle identifier. */
1850 /* Array of drives added by add-drive* APIs.
1852 *
1853 * Before launch this list can be empty or contain some drives.
1854 *
1855 * During launch, a dummy slot may be added which represents the
1856 * slot taken up by the appliance drive.
1857 *
1858 * When hotplugging is supported by the backend, drives can be
1859 * added to the end of this list after launch. Also hot-removing a
1860 * drive causes a NULL slot to appear in the list.
1861 *
1862 * During shutdown, this list is deleted, so that each launch gets a
1863 * fresh set of drives (however callers: don't do this, create a new
1864 * handle each time).
1865 *
1866 * Always use ITER_DRIVES macro to iterate over this list!
1867 */
1868 struct drive **drives;
1869 size_t nr_drives;
1870 #define ITER_DRIVES(g,i,drv) \
1872 for (i = 0; i < (g)->nr_drives; ++i) \
1873 if (((drv) = (g)->drives[i]) != NULL)
1874 /* Backend. NB: Use guestfs_int_set_backend to change the backend. */
1876 char *backend; /* The full string, always non-NULL. */
1877 char *backend_arg; /* Pointer to the argument part. */
1878 const struct backend_ops *backend_ops;
1879 void *backend_data; /* Per-handle data. */
1880 char **backend_settings; /* Backend settings (can be NULL). */
1881 /**** Runtime information. ****/
1883 /* Temporary and cache directories. */
1884 /* The actual temporary directory - this is not created with the
1885 * handle, you have to call guestfs_int_lazy_make_tmpdir.
1886 */
1887 char *tmpdir;
1888 char *sockdir;
1889 /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
1890 char *env_tmpdir; /* $TMPDIR (NULL if not set) */
1891 char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/
1892 char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
1893 char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */
1894 /* Error handler, plus stack of old error handlers. */
1896 pthread_key_t error_data;
1897 /* Linked list of error_data structures allocated for this handle,
1899 * plus a mutex to protect the linked list.
1900 */
1901 pthread_mutex_t error_data_list_lock;
1902 struct error_data *error_data_list;
1903 /* Out of memory error handler. */
1905 guestfs_abort_cb abort_cb;
1906 /* Events. */
1908 struct event *events;
1909 size_t nr_events;
1910 /* Private data area. */
1912 struct hash_table *pda;
1913 struct pda_entry *pda_next;
1914 /* User cancelled transfer. Not signal-atomic, but it doesn't
1916 * matter for this case because we only care if it is != 0.
1917 */
1918 int user_cancel;
1919 struct timeval launch_t; /* The time that we called guestfs_launch. */
1921 /* Used by bindtests. */
1923 FILE *test_fp;
1924 /* Used to generate unique numbers, eg for temp files. To use this,
1926 * '++g->unique'. Note these are only unique per-handle, not
1927 * globally unique.
1928 */
1929 int unique;
1930 /*** Protocol. ***/
1932 struct connection *conn; /* Connection to appliance. */
1933 int msg_next_serial;
1934 #if HAVE_FUSE
1936 /**** Used by the mount-local APIs. ****/
1937 char *localmountpoint;
1938 struct fuse *fuse; /* FUSE handle. */
1939 int ml_dir_cache_timeout; /* Directory cache timeout. */
1940 Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
1941 int ml_read_only; /* If mounted read-only. */
1942 int ml_debug_calls; /* Extra debug info on each FUSE call. */
1943 #endif
1944 #ifdef HAVE_LIBVIRT_BACKEND
1946 /* Used by lib/libvirt-auth.c. */
1947 #define NR_CREDENTIAL_TYPES 9
1948 unsigned int nr_supported_credentials;
1949 int supported_credentials[NR_CREDENTIAL_TYPES];
1950 const char *saved_libvirt_uri; /* Doesn't need to be freed. */
1951 bool wrapper_warning_done;
1952 unsigned int nr_requested_credentials;
1953 virConnectCredentialPtr requested_credentials;
1954 #endif
1955 /* Cached features. */
1957 struct cached_feature *features;
1958 size_t nr_features;
1959 /* Used by lib/info.c. -1 = not tested or error; else 0 or 1. */
1961 int qemu_img_supports_U_option;
1962 };
1963 The libguestfs handle.
1965 Structure "lib/guestfs-internal.h:version"
1967 struct version {
1969 int v_major;
1970 int v_minor;
1971 int v_micro;
1972 };
1973 Used for storing major.minor.micro version numbers. See lib/version.c
1975 for more information.
1976 File lib/guid.c
1978 Function "lib/guid.c:guestfs_int_validate_guid"
1980 int
1982 guestfs_int_validate_guid (const char *str)
1983 Check whether a string supposed to contain a GUID actually contains it.
1985 It can recognize strings either as
1986 "{21EC2020-3AEA-1069-A2DD-08002B30309D}" or
1987 "21EC2020-3AEA-1069-A2DD-08002B30309D".
1988 File lib/handle.c
1990 This file deals with the "guestfs_h" handle, creating it, closing it,
1992 and initializing/setting/getting fields.
1993 Function "lib/handle.c:init_libguestfs"
1995 static void
1997 init_libguestfs (void)
1998 No initialization is required by libguestfs, but libvirt and libxml2
2000 require initialization if they might be called from multiple threads.
2001 Hence this constructor function which is called when libguestfs is
2002 first loaded.
2003 Function "lib/handle.c:shutdown_backend"
2005 static int
2007 shutdown_backend (guestfs_h *g, int check_for_errors)
2008 This function is the common path for shutting down the backend qemu
2010 process.
2011 "guestfs_shutdown" calls "shutdown_backend" with "check_for_errors=1".
2013 "guestfs_close" calls "shutdown_backend" with "check_for_errors=0".
2014 "check_for_errors" is a hint to the backend about whether we care about
2016 errors or not. In the libvirt case it can be used to optimize the
2017 shutdown for speed when we don't care.
2018 Function "lib/handle.c:close_handles"
2020 static void
2022 close_handles (void)
2023 Close all open handles (called from atexit(3)).
2025 Function "lib/handle.c:guestfs_int_get_backend_setting_bool"
2027 int
2029 guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)
2030 This is a convenience function, but we might consider exporting it as
2032 an API in future.
2033 File lib/info.c
2035 Function "lib/info.c:qemu_img_supports_U_option"
2037 static int
2039 qemu_img_supports_U_option (guestfs_h *g)
2040 Test if the qemu-img info command supports the "-U" option to disable
2042 locking. The result is memoized in the handle.
2043 Note this option was added in qemu 2.11. We can remove this test when
2045 we can assume everyone is using qemu >= 2.11.
2046 File lib/inspect-icon.c
2048 Function "lib/inspect-icon.c:guestfs_int_download_to_tmp"
2050 char *
2052 guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
2053 const char *extension,
2054 uint64_t max_size)
2055 Download a guest file to a local temporary file.
2057 The name of the temporary (downloaded) file is returned. The caller
2059 must free the pointer, but does not need to delete the temporary file.
2060 It will be deleted when the handle is closed.
2061 The name of the temporary file is randomly generated, but an extension
2063 can be specified using "extension" (or pass "NULL" for none).
2064 Refuse to download the guest file if it is larger than "max_size". On
2066 this and other errors, "NULL" is returned.
2067 File lib/launch-direct.c
2069 Implementation of the "direct" backend.
2071 For more details see "BACKENDS" in guestfs(3).
2073 Function "lib/launch-direct.c:add_drive_standard_params"
2075 static int
2077 add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
2078 struct qemuopts *qopts,
2079 size_t i, struct drive *drv)
2080 Add the standard elements of the "-drive" parameter.
2082 Function "lib/launch-direct.c:add_device_blocksize_params"
2084 static int
2086 add_device_blocksize_params (guestfs_h *g, struct qemuopts *qopts,
2087 struct drive *drv)
2088 Add the physical_block_size and logical_block_size elements of the
2090 "-device" parameter.
2091 File lib/launch-libvirt.c
2093 Function "lib/launch-libvirt.c:get_source_format_or_autodetect"
2095 static char *
2097 get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)
2098 Return "drv->src.format", but if it is "NULL", autodetect the format.
2100 libvirt has disabled the feature of detecting the disk format, unless
2102 the administrator sets "allow_disk_format_probing=1" in
2103 /etc/libvirt/qemu.conf. There is no way to detect if this option is
2104 set, so we have to do format detection here using "qemu-img" and pass
2105 that to libvirt.
2106 This can still be a security issue, so in most cases it is recommended
2108 the users pass the format to libguestfs which will faithfully pass that
2109 straight through to libvirt without doing autodetection.
2110 Caller must free the returned string. On error this function sets the
2112 error in the handle and returns "NULL".
2113 Function "lib/launch-libvirt.c:make_qcow2_overlay"
2115 static char *
2117 make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
2118 const char *format)
2119 Create a qcow2 format overlay, with the given "backing_drive" (file).
2121 The "format" parameter is the backing file format. The "format"
2122 parameter can be NULL, in this case the backing format will be
2123 determined automatically. This is used to create the appliance
2124 overlay, and also for read-only drives.
2125 File lib/launch.c
2127 This file implements "guestfs_launch" in guestfs(3).
2129 Most of the work is done by the backends (see "BACKEND" in guestfs(3)),
2131 which are implemented in lib/launch-direct.c, lib/launch-libvirt.c etc,
2132 so this file mostly passes calls through to the current backend.
2133 Function "lib/launch.c:guestfs_int_launch_send_progress"
2135 void
2137 guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)
2138 This function sends a launch progress message.
2140 Launching the appliance generates approximate progress messages.
2142 Currently these are defined as follows:
2143 0 / 12: launch clock starts
2145 3 / 12: appliance created
2146 6 / 12: detected that guest kernel started
2147 9 / 12: detected that /init script is running
2148 12 / 12: launch completed successfully
2149 Notes:
2151 1. This is not a documented ABI and the behaviour may be changed or
2153 removed in future.
2154 2. Messages are only sent if more than 5 seconds has elapsed since the
2156 launch clock started.
2157 3. There is a hack in lib/proto.c to make this work.
2159 Function "lib/launch.c:guestfs_int_timeval_diff"
2161 int64_t
2163 guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)
2164 Compute "y - x" and return the result in milliseconds.
2166 Approximately the same as this code:
2168 http://www.mpp.mpg.de/~huber/util/timevaldiff.c
2169 Function "lib/launch.c:guestfs_int_unblock_sigterm"
2171 void
2173 guestfs_int_unblock_sigterm (void)
2174 Unblock the "SIGTERM" signal. Call this after fork(2) so that the
2176 parent process can send "SIGTERM" to the child process in case
2177 "SIGTERM" is blocked. See https://bugzilla.redhat.com/1460338.
2178 Function "lib/launch.c:guestfs_impl_max_disks"
2180 int
2182 guestfs_impl_max_disks (guestfs_h *g)
2183 Returns the maximum number of disks allowed to be added to the backend
2185 (backend dependent).
2186 Function "lib/launch.c:guestfs_impl_wait_ready"
2188 int
2190 guestfs_impl_wait_ready (guestfs_h *g)
2191 Implementation of "guestfs_wait_ready" in guestfs(3). You had to call
2193 this function after launch in versions ≤ 1.0.70, but it is now an
2194 (almost) no-op.
2195 Function "lib/launch.c:guestfs_int_create_socketname"
2197 int
2199 guestfs_int_create_socketname (guestfs_h *g, const char *filename,
2200 char (*sockpath)[UNIX_PATH_MAX])
2201 Create the path for a socket with the selected filename in the tmpdir.
2203 Function "lib/launch.c:guestfs_int_register_backend"
2205 void
2207 guestfs_int_register_backend (const char *name, const struct backend_ops *ops)
2208 When the library is loaded, each backend calls this function to
2210 register itself in a global list.
2211 Function "lib/launch.c:guestfs_int_set_backend"
2213 int
2215 guestfs_int_set_backend (guestfs_h *g, const char *method)
2216 Implementation of "guestfs_set_backend" in guestfs(3).
2218 • Callers must ensure this is only called in the config state.
2220 • This shouldn't call "error" since it may be called early in handle
2222 initialization. It can return an error code however.
2223 File lib/private-data.c
2225 Implement a private data area where libguestfs C API users can attach
2227 arbitrary pieces of data to a "guestfs_h" handle.
2228 For more information see "PRIVATE DATA AREA" in guestfs(3).
2230 Language bindings do not generally expose this, largely because in non-
2232 C languages it is easy to associate data with handles in other ways
2233 (using hash tables or maps).
2234 Structure "lib/private-data.c:pda_entry"
2236 struct pda_entry {
2238 char *key; /* key */
2239 void *data; /* opaque user data pointer */
2240 };
2241 The private data area is internally stored as a gnulib hash table
2243 containing "pda_entry" structures.
2244 Note the private data area is allocated lazily, since the vast majority
2246 of callers will never use it. This means "g->pda" is likely to be
2247 "NULL".
2248 File lib/proto.c
2250 This is the code used to send and receive RPC messages and (for certain
2252 types of message) to perform file transfers. This code is driven from
2253 the generated actions (lib/actions-*.c). There are five different
2254 cases to consider:
2255 1. A non-daemon function (eg. "guestfs_set_verbose" in guestfs(3)).
2257 There is no RPC involved at all, it's all handled inside the
2258 library.
2259 2. A simple RPC (eg. "guestfs_mount" in guestfs(3)). We write the
2261 request, then read the reply. The sequence of calls is:
2262 guestfs_int_send
2264 guestfs_int_recv
2265 3. An RPC with "FileIn" parameters (eg. "guestfs_upload" in
2267 guestfs(3)). We write the request, then write the file(s), then
2268 read the reply. The sequence of calls is:
2269 guestfs_int_send
2271 guestfs_int_send_file (possibly multiple times)
2272 guestfs_int_recv
2273 4. An RPC with "FileOut" parameters (eg. "guestfs_download" in
2275 guestfs(3)). We write the request, then read the reply, then read
2276 the file(s). The sequence of calls is:
2277 guestfs_int_send
2279 guestfs_int_recv
2280 guestfs_int_recv_file (possibly multiple times)
2281 5. Both "FileIn" and "FileOut" parameters. There are no calls like
2283 this in the current API, but they would be implemented as a
2284 combination of cases 3 and 4.
2285 All read/write/etc operations are performed using the current
2287 connection module ("g->conn"). During operations the connection module
2288 transparently handles log messages that appear on the console.
2289 Function "lib/proto.c:child_cleanup"
2291 static void
2293 child_cleanup (guestfs_h *g)
2294 This is called if we detect EOF, ie. qemu died.
2296 Function "lib/proto.c:guestfs_int_progress_message_callback"
2298 void
2300 guestfs_int_progress_message_callback (guestfs_h *g,
2301 const guestfs_progress *message)
2302 Convenient wrapper to generate a progress message callback.
2304 Function "lib/proto.c:guestfs_int_log_message_callback"
2306 void
2308 guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)
2309 Connection modules call us back here when they get a log message.
2311 Function "lib/proto.c:check_daemon_socket"
2313 static ssize_t
2315 check_daemon_socket (guestfs_h *g)
2316 Before writing to the daemon socket, check the read side of the daemon
2318 socket for any of these conditions:
2319 error
2321 return -1
2322 daemon cancellation message
2324 return -2
2325 progress message
2327 handle it here
2328 end of input or appliance exited unexpectedly
2330 return 0
2331 anything else
2333 return 1
2334 Function "lib/proto.c:guestfs_int_send_file"
2336 int
2338 guestfs_int_send_file (guestfs_h *g, const char *filename)
2339 Send a file.
2341 Returns 0 on success, "-1" for error, "-2" if the daemon cancelled (we
2343 must read the error message).
2344 Function "lib/proto.c:send_file_data"
2346 static int
2348 send_file_data (guestfs_h *g, const char *buf, size_t len)
2349 Send a chunk of file data.
2351 Function "lib/proto.c:send_file_cancellation"
2353 static int
2355 send_file_cancellation (guestfs_h *g)
2356 Send a cancellation message.
2358 Function "lib/proto.c:send_file_complete"
2360 static int
2362 send_file_complete (guestfs_h *g)
2363 Send a file complete chunk.
2365 Function "lib/proto.c:recv_from_daemon"
2367 static int
2369 recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)
2370 This function reads a single message, file chunk, launch flag or
2372 cancellation flag from the daemon. If something was read, it returns
2373 0, otherwise "-1".
2374 Both "size_rtn" and "buf_rtn" must be passed by the caller as non-NULL.
2376 *size_rtn returns the size of the returned message or it may be
2378 "GUESTFS_LAUNCH_FLAG" or "GUESTFS_CANCEL_FLAG".
2379 *buf_rtn is returned containing the message (if any) or will be set to
2381 "NULL". *buf_rtn must be freed by the caller.
2382 This checks for EOF (appliance died) and passes that up through the
2384 child_cleanup function above.
2385 Log message, progress messages are handled transparently here.
2387 Function "lib/proto.c:guestfs_int_recv"
2389 int
2391 guestfs_int_recv (guestfs_h *g, const char *fn,
2392 guestfs_message_header *hdr,
2393 guestfs_message_error *err,
2394 xdrproc_t xdrp, char *ret)
2395 Receive a reply.
2397 Function "lib/proto.c:guestfs_int_recv_discard"
2399 int
2401 guestfs_int_recv_discard (guestfs_h *g, const char *fn)
2402 Same as "guestfs_int_recv", but it discards the reply message.
2404 Notes (XXX):
2406 • This returns an int, but all current callers ignore it.
2408 • The error string may end up being set twice on error paths.
2410 Function "lib/proto.c:guestfs_int_recv_file"
2412 int
2414 guestfs_int_recv_file (guestfs_h *g, const char *filename)
2415 Returns "-1" = error, 0 = EOF, ">0" = more data
2417 Function "lib/proto.c:receive_file_data"
2419 static ssize_t
2421 receive_file_data (guestfs_h *g, void **buf_r)
2422 Receive a chunk of file data.
2424 Returns "-1" = error, 0 = EOF, ">0" = more data
2426 File lib/qemu.c
2428 Functions to handle qemu versions and features.
2430 Function "lib/qemu.c:guestfs_int_test_qemu"
2432 struct qemu_data *
2434 guestfs_int_test_qemu (guestfs_h *g)
2435 Test that the qemu binary (or wrapper) runs, and do "qemu -help" and
2437 other commands so we can find out the version of qemu and what options
2438 this qemu supports.
2439 This caches the results in the cachedir so that as long as the qemu
2441 binary does not change, calling this is effectively free.
2442 Function "lib/qemu.c:cache_filename"
2444 static char *
2446 cache_filename (guestfs_h *g, const char *cachedir,
2447 const struct stat *statbuf, const char *suffix)
2448 Generate the filenames, for the stat file and the other cache files.
2450 By including the size and mtime in the filename we also ensure that the
2452 same user can use multiple versions of qemu without conflicts.
2453 Function "lib/qemu.c:parse_qemu_version"
2455 static void
2457 parse_qemu_version (guestfs_h *g, const char *qemu_help,
2458 struct version *qemu_version)
2459 Parse the first line of "qemu_help" into the major and minor version of
2461 qemu, but don't fail if parsing is not possible.
2462 Function "lib/qemu.c:parse_json"
2464 static void
2466 parse_json (guestfs_h *g, const char *json, json_t **treep)
2467 Parse the json output from QMP. But don't fail if parsing is not
2469 possible.
2470 Function "lib/qemu.c:parse_has_kvm"
2472 static void
2474 parse_has_kvm (guestfs_h *g, const char *json, bool *ret)
2475 Parse the json output from QMP query-kvm to find out if KVM is enabled
2477 on this machine. Don't fail if parsing is not possible, assume KVM is
2478 available.
2479 The JSON output looks like: {"return": {"enabled": true, "present":
2481 true}}
2482 Function "lib/qemu.c:generic_read_cache"
2484 static int
2486 generic_read_cache (guestfs_h *g, const char *filename, char **strp)
2487 Generic functions for reading and writing the cache files, used where
2489 we are just reading and writing plain text strings.
2490 Function "lib/qemu.c:generic_qmp_test"
2492 static int
2494 generic_qmp_test (guestfs_h *g, struct qemu_data *data,
2495 const char *qmp_command,
2496 char **outp)
2497 Run a generic QMP test on the QEMU binary.
2499 Function "lib/qemu.c:guestfs_int_qemu_version"
2501 struct version
2503 guestfs_int_qemu_version (guestfs_h *g, struct qemu_data *data)
2504 Return the parsed version of qemu.
2506 Function "lib/qemu.c:guestfs_int_qemu_supports"
2508 int
2510 guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data,
2511 const char *option)
2512 Test if option is supported by qemu command line (just by grepping the
2514 help text).
2515 Function "lib/qemu.c:guestfs_int_qemu_supports_device"
2517 int
2519 guestfs_int_qemu_supports_device (guestfs_h *g,
2520 const struct qemu_data *data,
2521 const char *device_name)
2522 Test if device is supported by qemu (currently just greps the "qemu
2524 -device ?" output).
2525 Function "lib/qemu.c:guestfs_int_qemu_mandatory_locking"
2527 int
2529 guestfs_int_qemu_mandatory_locking (guestfs_h *g,
2530 const struct qemu_data *data)
2531 Test if the qemu binary uses mandatory file locking, added in QEMU >=
2533 2.10 (but sometimes disabled).
2534 Function "lib/qemu.c:guestfs_int_qemu_escape_param"
2536 char *
2538 guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)
2539 Escape a qemu parameter.
2541 Every "," becomes ",,". The caller must free the returned string.
2543 XXX This functionality is now only used when constructing a qemu-img
2545 command in lib/create.c. We should extend the qemuopts library to
2546 cover this use case.
2547 Function "lib/qemu.c:guestfs_int_drive_source_qemu_param"
2549 char *
2551 guestfs_int_drive_source_qemu_param (guestfs_h *g,
2552 const struct drive_source *src)
2553 Useful function to format a drive + protocol for qemu.
2555 Note that the qemu parameter is the bit after "file=". It is not
2557 escaped here, but would usually be escaped if passed to qemu as part of
2558 a full -drive parameter (but not for qemu-img(1)).
2559 Function "lib/qemu.c:guestfs_int_discard_possible"
2561 bool
2563 guestfs_int_discard_possible (guestfs_h *g, struct drive *drv,
2564 const struct version *qemu_version)
2565 Test if discard is both supported by qemu AND possible with the
2567 underlying file or device. This returns 1 if discard is possible. It
2568 returns 0 if not possible and sets the error to the reason why.
2569 This function is called when the user set "discard == "enable"".
2571 Function "lib/qemu.c:guestfs_int_free_qemu_data"
2573 void
2575 guestfs_int_free_qemu_data (struct qemu_data *data)
2576 Free the "struct qemu_data".
2578 File lib/rescue.c
2580 Support for virt-rescue(1).
2582 File lib/stringsbuf.c
2584 An expandable NULL-terminated vector of strings (like "argv").
2586 Use the "DECLARE_STRINGSBUF" macro to declare the stringsbuf.
2588 Note: Don't confuse this with stringsbuf in the daemon which is a
2590 different type with different methods.
2591 Function "lib/stringsbuf.c:guestfs_int_add_string_nodup"
2593 void
2595 guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)
2596 Add a string to the end of the list.
2598 This doesn't call strdup(3) on the string, so the string itself is
2600 stored inside the vector.
2601 Function "lib/stringsbuf.c:guestfs_int_add_string"
2603 void
2605 guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)
2606 Add a string to the end of the list.
2608 This makes a copy of the string.
2610 Function "lib/stringsbuf.c:guestfs_int_add_sprintf"
2612 void
2614 guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
2615 const char *fs, ...)
2616 Add a string to the end of the list.
2618 Uses an sprintf-like format string when creating the string.
2620 Function "lib/stringsbuf.c:guestfs_int_end_stringsbuf"
2622 void
2624 guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)
2625 Finish the string buffer.
2627 This adds the terminating NULL to the end of the vector.
2629 Function "lib/stringsbuf.c:guestfs_int_free_stringsbuf"
2631 void
2633 guestfs_int_free_stringsbuf (struct stringsbuf *sb)
2634 Free the string buffer and the strings.
2636 File lib/tmpdirs.c
2638 Handle temporary directories.
2640 Function "lib/tmpdirs.c:set_abs_path"
2642 static int
2644 set_abs_path (guestfs_h *g, const char *ctxstr,
2645 const char *tmpdir, char **tmpdir_ret)
2646 We need to make all tmpdir paths absolute because lots of places in the
2648 code assume this. Do it at the time we set the path or read the
2649 environment variable (https://bugzilla.redhat.com/882417).
2650 The "ctxstr" parameter is a string displayed in error messages giving
2652 the context of the operation (eg. name of environment variable being
2653 used, or API function being called).
2654 Function "lib/tmpdirs.c:guestfs_impl_get_tmpdir"
2656 char *
2658 guestfs_impl_get_tmpdir (guestfs_h *g)
2659 Implements the "guestfs_get_tmpdir" API.
2661 Note this actually calculates the tmpdir, so it never returns "NULL".
2663 Function "lib/tmpdirs.c:guestfs_impl_get_cachedir"
2665 char *
2667 guestfs_impl_get_cachedir (guestfs_h *g)
2668 Implements the "guestfs_get_cachedir" API.
2670 Note this actually calculates the cachedir, so it never returns "NULL".
2672 Function "lib/tmpdirs.c:guestfs_impl_get_sockdir"
2674 char *
2676 guestfs_impl_get_sockdir (guestfs_h *g)
2677 Implements the "guestfs_get_sockdir" API.
2679 Note this actually calculates the sockdir, so it never returns "NULL".
2681 Function "lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir"
2683 int
2685 guestfs_int_lazy_make_tmpdir (guestfs_h *g)
2686 The "g->tmpdir" (per-handle temporary directory) is not created when
2688 the handle is created. Instead we create it lazily before the first
2689 time it is used, or during launch.
2690 Function "lib/tmpdirs.c:guestfs_int_make_temp_path"
2692 char *
2694 guestfs_int_make_temp_path (guestfs_h *g,
2695 const char *name, const char *extension)
2696 Generate unique temporary paths for temporary files.
2698 Returns a unique path or NULL on error.
2700 Function "lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir"
2702 char *
2704 guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)
2705 Create the supermin appliance directory under cachedir, if it does not
2707 exist.
2708 Sanity-check that the permissions on the cachedir are safe, in case it
2710 has been pre-created maliciously or tampered with.
2711 Returns the directory name which the caller must free.
2713 Function "lib/tmpdirs.c:guestfs_int_recursive_remove_dir"
2715 void
2717 guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)
2718 Recursively remove a temporary directory. If removal fails, just
2720 return (it's a temporary directory so it'll eventually be cleaned up by
2721 a temp cleaner).
2722 This is implemented using "rm -rf" because that's simpler and safer.
2724 File lib/umask.c
2726 Return current umask in a thread-safe way.
2728 glibc documents, but does not actually implement, a "getumask(3)" call.
2730 We use "Umask" from /proc/self/status for Linux ≥ 4.7. For older Linux
2732 and other Unix, this file implements an expensive but thread-safe way
2733 to get the current process's umask.
2734 Thanks to: Josh Stone, Jiri Jaburek, Eric Blake.
2736 Function "lib/umask.c:guestfs_int_getumask"
2738 int
2740 guestfs_int_getumask (guestfs_h *g)
2741 Returns the current process's umask. On failure, returns "-1" and sets
2743 the error in the guestfs handle.
2744 Function "lib/umask.c:get_umask_from_proc"
2746 static int
2748 get_umask_from_proc (guestfs_h *g)
2749 For Linux ≥ 4.7 get the umask from /proc/self/status.
2751 On failure this returns "-1". However if we could not open the /proc
2753 file or find the "Umask" entry in it, return "-2" which causes the
2754 fallback path to run.
2755 Function "lib/umask.c:get_umask_from_fork"
2757 static int
2759 get_umask_from_fork (guestfs_h *g)
2760 Fallback method of getting the umask using fork.
2762 File lib/unit-tests.c
2764 Unit tests of internal functions.
2766 These tests may use a libguestfs handle, but must not launch the
2768 handle. Also, avoid long-running tests.
2769 Function "lib/unit-tests.c:test_split"
2771 static void
2773 test_split (void)
2774 Test "guestfs_int_split_string".
2776 Function "lib/unit-tests.c:test_concat"
2778 static void
2780 test_concat (void)
2781 Test "guestfs_int_concat_strings".
2783 Function "lib/unit-tests.c:test_join"
2785 static void
2787 test_join (void)
2788 Test "guestfs_int_join_strings".
2790 Function "lib/unit-tests.c:test_validate_guid"
2792 static void
2794 test_validate_guid (void)
2795 Test "guestfs_int_validate_guid".
2797 Function "lib/unit-tests.c:test_drive_name"
2799 static void
2801 test_drive_name (void)
2802 Test "guestfs_int_drive_name".
2804 Function "lib/unit-tests.c:test_drive_index"
2806 static void
2808 test_drive_index (void)
2809 Test "guestfs_int_drive_index".
2811 Function "lib/unit-tests.c:test_getumask"
2813 static void
2815 test_getumask (void)
2816 Test "guestfs_int_getumask".
2818 Function "lib/unit-tests.c:test_command"
2820 static void
2822 test_command (void)
2823 Test "guestfs_int_new_command" etc.
2825 XXX These tests could be made much more thorough. So far we simply
2827 test that it's not obviously broken.
2828 Function "lib/unit-tests.c:test_qemu_escape_param"
2830 static void
2832 test_qemu_escape_param (void)
2833 Test "guestfs_int_qemu_escape_param"
2835 XXX I wanted to make this test run qemu, passing some parameters which
2837 need to be escaped, but I cannot think of a way to do that without
2838 launching a VM.
2839 Function "lib/unit-tests.c:test_timeval_diff"
2841 static void
2843 test_timeval_diff (void)
2844 Test "guestfs_int_timeval_diff".
2846 File lib/version.c
2848 This file provides simple version number management.
2850 Function "lib/version.c:guestfs_int_version_from_x_y"
2852 int
2854 guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)
2855 Parses a version from a string, looking for a "X.Y" pattern.
2857 Returns "-1" on failure (like failed integer parsing), 0 on missing
2859 match, and 1 on match and successful parsing. "v" is changed only on
2860 successful match.
2861 Function "lib/version.c:guestfs_int_version_from_x_y_re"
2863 int
2865 guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
2866 const char *str, const pcre2_code *re)
2867 Parses a version from a string, using the specified "re" as regular
2869 expression which must provide (at least) two matches.
2870 Returns "-1" on failure (like failed integer parsing), 0 on missing
2872 match, and 1 on match and successful parsing. "v" is changed only on
2873 successful match.
2874 Function "lib/version.c:guestfs_int_version_from_x_y_or_x"
2876 int
2878 guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
2879 const char *str)
2880 Parses a version from a string, either looking for a "X.Y" pattern or
2882 considering it as whole integer.
2883 Returns "-1" on failure (like failed integer parsing), 0 on missing
2885 match, and 1 on match and successful parsing. "v" is changed only on
2886 successful match.
2887 Function "lib/version.c:guestfs_int_parse_unsigned_int"
2889 int
2891 guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)
2892 Parse small, unsigned ints, as used in version numbers.
2894 This will fail with an error if trailing characters are found after the
2896 integer.
2897 Returns ≥ 0 on success, or "-1" on failure.
2899 File lib/wait.c
2901 Function "lib/wait.c:guestfs_int_waitpid"
2903 int
2905 guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)
2906 A safe version of waitpid(3) which retries if "EINTR" is returned.
2908 Note: this only needs to be used in the library, or in programs that
2910 install a non-restartable "SIGCHLD" handler (which is not the case for
2911 any current libguestfs virt tools).
2912 If the main program installs a SIGCHLD handler and sets it to be non-
2914 restartable, then what can happen is the library is waiting in a wait
2915 syscall, the child exits, "SIGCHLD" is sent to the process, and the
2916 wait syscall returns "EINTR". Since the library cannot control the
2917 signal handler, we have to instead restart the wait syscall, which is
2918 the purpose of this wrapper.
2919 Function "lib/wait.c:guestfs_int_waitpid_noerror"
2921 void
2923 guestfs_int_waitpid_noerror (pid_t pid)
2924 Like "guestfs_int_waitpid", but ignore errors.
2926 Function "lib/wait.c:guestfs_int_wait4"
2928 int
2930 guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
2931 struct rusage *rusage, const char *errmsg)
2932 A safe version of wait4(2) which retries if "EINTR" is returned.
2934 File lib/whole-file.c
2936 Function "lib/whole-file.c:guestfs_int_read_whole_file"
2938 int
2940 guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
2941 char **data_r, size_t *size_r)
2942 Read the whole file "filename" into a memory buffer.
2944 The memory buffer is initialized and returned in "data_r". The size of
2946 the file in bytes is returned in "size_r". The return buffer must be
2947 freed by the caller.
2948 On error this sets the error in the handle and returns "-1".
2950 For the convenience of callers, the returned buffer is NUL-terminated
2952 (the NUL is not included in the size).
2953 The file must be a regular, local, trusted file. In particular, do not
2955 use this function to read files that might be under control of an
2956 untrusted user since that will lead to a denial-of-service attack.
2957 Subdirectory common/edit
2959 File common/edit/file-edit.c
2960 This file implements common file editing in a range of utilities
2962 including guestfish(1), virt-edit(1), virt-customize(1) and
2963 virt-builder(1).
2964 It contains the code for both interactive-(editor-)based editing and
2966 non-interactive editing using Perl snippets.
2967 Function "common/edit/file-edit.c:edit_file_editor"
2969 int
2971 edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
2972 const char *backup_extension, int verbose)
2973 Edit "filename" using the specified "editor" application.
2975 If "backup_extension" is not null, then a copy of "filename" is saved
2977 with "backup_extension" appended to its file name.
2978 If "editor" is null, then the $EDITOR environment variable will be
2980 queried for the editor application, leaving "vi" as fallback if not
2981 set.
2982 Returns "-1" for failure, 0 on success, 1 if the editor did not change
2984 the file (e.g. the user closed the editor without saving).
2985 Function "common/edit/file-edit.c:edit_file_perl"
2987 int
2989 edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
2990 const char *backup_extension, int verbose)
2991 Edit "filename" running the specified "perl_expr" using Perl.
2993 If "backup_extension" is not null, then a copy of "filename" is saved
2995 with "backup_extension" appended to its file name.
2996 Returns "-1" for failure, 0 on success.
2998 Subdirectory common/options
3000 File common/options/config.c
3001 This file parses the guestfish configuration file, usually
3003 ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.
3004 Note that "parse_config" is called very early, before command line
3006 parsing, before the "verbose" flag has been set, even before the global
3007 handle "g" is opened.
3008 File common/options/decrypt.c
3010 This file implements the decryption of disk images, usually done before
3012 mounting their partitions.
3013 Function "common/options/decrypt.c:make_mapname"
3015 static void
3017 make_mapname (const char *device, char *mapname, size_t len)
3018 Make a LUKS map name from the partition name, eg. "/dev/vda2" =>
3020 "cryptvda2"
3021 Function "common/options/decrypt.c:inspect_do_decrypt"
3023 void
3025 inspect_do_decrypt (guestfs_h *g, struct key_store *ks)
3026 Simple implementation of decryption: look for any encrypted partitions
3028 and decrypt them, then rescan for VGs.
3029 File common/options/display-options.c
3031 This file contains common code used to implement --short-options and
3033 --long-options in C virt tools. (The equivalent for OCaml virt tools
3034 is implemented by common/mltools/getopt.ml).
3035 These "hidden" options are used to implement bash tab completion.
3037 Function "common/options/display-options.c:display_short_options"
3039 void
3041 display_short_options (const char *format)
3042 Implements the internal "tool --short-options" flag, which just lists
3044 out the short options available. Used by bash completion.
3045 Function "common/options/display-options.c:display_long_options"
3047 void
3049 display_long_options (const struct option *long_options)
3050 Implements the internal "tool --long-options" flag, which just lists
3052 out the long options available. Used by bash completion.
3053 File common/options/domain.c
3055 Implements the guestfish (and other tools) -d option.
3057 Function "common/options/domain.c:add_libvirt_drives"
3059 int
3061 add_libvirt_drives (guestfs_h *g, const char *guest)
3062 This function is called when a user invokes "guestfish -d guest".
3064 Returns the number of drives added ("> 0"), or "-1" for failure.
3066 File common/options/inspect.c
3068 This file implements inspecting the guest and mounting the filesystems
3070 found in the right places. It is used by the guestfish(1) -i option
3071 and some utilities such as virt-cat(1).
3072 Function "common/options/inspect.c:inspect_mount_handle"
3074 void
3076 inspect_mount_handle (guestfs_h *g, struct key_store *ks)
3077 This function implements the -i option.
3079 Function "common/options/inspect.c:print_inspect_prompt"
3081 void
3083 print_inspect_prompt (void)
3084 This function is called only if "inspect_mount_root" was called, and
3086 only after we've printed the prompt in interactive mode.
3087 File common/options/keys.c
3089 Function "common/options/keys.c:read_key"
3091 char *
3093 read_key (const char *param)
3094 Read a passphrase ('Key') from /dev/tty with echo off.
3096 The caller (fish/cmds.c) will call free on the string afterwards.
3098 Based on the code in cryptsetup file lib/utils.c.
3099 File common/options/options.c
3101 This file contains common options parsing code used by guestfish and
3103 many other tools which share a common options syntax.
3104 For example, guestfish, virt-cat, virt-ls etc all support the -a
3106 option, and that is handled in all of those tools using a macro
3107 "OPTION_a" defined in fish/options.h.
3108 There are a lot of common global variables used, "drvs" accumulates the
3110 list of drives, "verbose" for the -v flag, and many more.
3111 Function "common/options/options.c:option_a"
3113 void
3115 option_a (const char *arg, const char *format, int blocksize,
3116 struct drv **drvsp)
3117 Handle the guestfish -a option on the command line.
3119 Function "common/options/options.c:option_d"
3121 void
3123 option_d (const char *arg, struct drv **drvsp)
3124 Handle the -d option when passed on the command line.
3126 Function "common/options/options.c:display_mountpoints_on_failure"
3128 static void
3130 display_mountpoints_on_failure (const char *mp_device,
3131 const char *user_supplied_options)
3132 If the -m option fails on any command, display a useful error message
3134 listing the mountpoints.
3135 File common/options/uri.c
3137 This file implements URI parsing for the -a option, in many utilities
3139 including guestfish(1), virt-cat(1), virt-builder(1),
3140 virt-customize(1), etc.
3141 Subdirectory common/parallel
3143 File common/parallel/domains.c
3144 This file is used by "virt-df" and some of the other tools when they
3146 are implicitly asked to operate over all libvirt domains (VMs), for
3147 example when "virt-df" is called without specifying any particular disk
3148 image.
3149 It hides the complexity of querying the list of domains from libvirt.
3151 Function "common/parallel/domains.c:free_domains"
3153 void
3155 free_domains (void)
3156 Frees up everything allocated by "get_all_libvirt_domains".
3158 Function "common/parallel/domains.c:get_all_libvirt_domains"
3160 void
3162 get_all_libvirt_domains (const char *libvirt_uri)
3163 Read all libguest guests into the global variables "domains" and
3165 "nr_domains". The guests are ordered by name. This exits on any
3166 error.
3167 File common/parallel/estimate-max-threads.c
3169 Function "common/parallel/estimate-max-threads.c:estimate_max_threads"
3171 size_t
3173 estimate_max_threads (void)
3174 This function uses the output of "free -m" to estimate how many
3176 libguestfs appliances could be safely started in parallel. Note that
3177 it always returns ≥ 1.
3178 Function "common/parallel/estimate-max-threads.c:read_line_from"
3180 static char *
3182 read_line_from (const char *cmd)
3183 Run external command and read the first line of output.
3185 File common/parallel/parallel.c
3187 This file is used by "virt-df" and some of the other tools when they
3189 need to run multiple parallel libguestfs instances to operate on a
3190 large number of libvirt domains efficiently.
3191 It implements a multithreaded work queue. In addition it reorders the
3193 output so the output still appears in the same order as the input (ie.
3194 still ordered alphabetically).
3195 Function "common/parallel/parallel.c:start_threads"
3197 int
3199 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
3200 Run the threads and work through the global list of libvirt domains.
3202 "option_P" is whatever the user passed in the -P option, or 0 if the
3204 user didn't use the -P option (in which case the number of threads is
3205 chosen heuristically).
3206 "options_handle" (which may be "NULL") is the global guestfs handle
3208 created by the options mini-library.
3209 The work function ("work") should do the work (inspecting the domain,
3211 etc.) on domain index "i". However it must not print out any result
3212 directly. Instead it prints anything it needs to the supplied "FILE
3213 *". The work function should return 0 on success or "-1" on error.
3214 The "start_threads" function returns 0 if all work items completed
3216 successfully, or "-1" if there was an error.
3217 Subdirectory common/progress
3219 File common/progress/progress.c
3220 This file implements the progress bar in guestfish(1), virt-resize(1)
3222 and virt-sparsify(1).
3223 Function "common/progress/progress.c:progress_bar_init"
3225 struct progress_bar *
3227 progress_bar_init (unsigned flags)
3228 Initialize a progress bar struct.
3230 It is intended that you can reuse the same struct for multiple commands
3232 (but only in a single thread). Call "progress_bar_reset" before each
3233 new command.
3234 Function "common/progress/progress.c:progress_bar_free"
3236 void
3238 progress_bar_free (struct progress_bar *bar)
3239 Free a progress bar struct.
3241 Function "common/progress/progress.c:progress_bar_reset"
3243 void
3245 progress_bar_reset (struct progress_bar *bar)
3246 This function should be called just before you issue any command.
3248 Function "common/progress/progress.c:estimate_remaining_time"
3250 static double
3252 estimate_remaining_time (struct progress_bar *bar, double ratio)
3253 Return remaining time estimate (in seconds) for current call.
3255 This returns the running mean estimate of remaining time, but if the
3257 latest estimate of total time is greater than two s.d.'s from the
3258 running mean then we don't print anything because we're not confident
3259 that the estimate is meaningful. (Returned value is <0.0 when nothing
3260 should be printed).
3261 Function "common/progress/progress.c:progress_bar_set"
3263 void
3265 progress_bar_set (struct progress_bar *bar,
3266 uint64_t position, uint64_t total)
3267 Set the position of the progress bar.
3269 This should be called from a "GUESTFS_EVENT_PROGRESS" event callback.
3271 Subdirectory common/qemuopts
3273 File common/qemuopts/qemuopts-tests.c
3274 Unit tests of internal functions.
3276 These tests may use a libguestfs handle, but must not launch the
3278 handle. Also, avoid long-running tests.
3279 File common/qemuopts/qemuopts.c
3281 Mini-library for writing qemu command lines and qemu config files.
3283 There are some shortcomings with the model used for qemu options which
3285 aren't clear until you try to convert options into a configuration
3286 file. However if we attempted to model the options in more detail then
3287 this library would be both very difficult to use and incompatible with
3288 older versions of qemu. Hopefully the current model is a decent
3289 compromise.
3290 For reference here are the problems:
3292 • There's inconsistency in qemu between options and config file, eg.
3294 "-smp 4" becomes:
3295 [smp-opts]
3297 cpus = "4"
3298 • Similar to the previous point, you can write either "-smp 4" or
3300 "-smp cpus=4" (although this won't work in very old qemu). When
3301 generating a config file you need to know the implicit key name.
3302 • In "-opt key=value,..." the "key" is really a tree/array specifier.
3304 The way this works is complicated but hinted at here:
3305 http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
3306 • Some options are syntactic sugar. eg. "-kernel foo" is sugar for
3308 "-machine kernel=foo".
3309 Function "common/qemuopts/qemuopts.c:qemuopts_create"
3311 struct qemuopts *
3313 qemuopts_create (void)
3314 Create an empty list of qemu options.
3316 The caller must eventually free the list by calling "qemuopts_free".
3318 Returns "NULL" on error, setting "errno".
3320 Function "common/qemuopts/qemuopts.c:qemuopts_free"
3322 void
3324 qemuopts_free (struct qemuopts *qopts)
3325 Free the list of qemu options.
3327 Function "common/qemuopts/qemuopts.c:qemuopts_add_flag"
3329 int
3331 qemuopts_add_flag (struct qemuopts *qopts, const char *flag)
3332 Add a command line flag which has no argument. eg:
3334 qemuopts_add_flag (qopts, "-no-user-config");
3336 Returns 0 on success. Returns "-1" on error, setting "errno".
3338 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg"
3340 int
3342 qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)
3343 Add a command line flag which has a single argument. eg:
3345 qemuopts_add_arg (qopts, "-m", "1024");
3347 Don't use this if the argument is a comma-separated list, since quoting
3349 will not be done properly. See "qemuopts_add_arg_list".
3350 Returns 0 on success. Returns "-1" on error, setting "errno".
3352 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_format"
3354 int
3356 qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
3357 const char *fs, ...)
3358 Add a command line flag which has a single formatted argument. eg:
3360 qemuopts_add_arg_format (qopts, "-m", "%d", 1024);
3362 Don't use this if the argument is a comma-separated list, since quoting
3364 will not be done properly. See "qemuopts_add_arg_list".
3365 Returns 0 on success. Returns "-1" on error, setting "errno".
3367 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote"
3369 int
3371 qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
3372 const char *value)
3373 This is like "qemuopts_add_arg" except that no quoting is done on the
3375 value.
3376 For "qemuopts_to_script" and "qemuopts_to_channel", this means that
3378 neither shell quoting nor qemu comma quoting is done on the value.
3379 For "qemuopts_to_argv" this means that qemu comma quoting is not done.
3381 "qemuopts_to_config*" will fail.
3383 You should use this with great care.
3385 Function "common/qemuopts/qemuopts.c:qemuopts_start_arg_list"
3387 int
3389 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
3390 Start an argument that takes a comma-separated list of fields.
3392 Typical usage is like this (with error handling omitted):
3394 qemuopts_start_arg_list (qopts, "-drive");
3396 qemuopts_append_arg_list (qopts, "file=foo");
3397 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
3398 qemuopts_end_arg_list (qopts);
3399 which would construct "-drive file=foo,if=ide"
3401 See also "qemuopts_add_arg_list" for a way to do simple cases in one
3403 call.
3404 Returns 0 on success. Returns "-1" on error, setting "errno".
3406 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_list"
3408 int
3410 qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
3411 const char *elem0, ...)
3412 Add a command line flag which has a list of arguments. eg:
3414 qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);
3416 This is turned into a comma-separated list, like: "-drive
3418 file=foo,if=ide". Note that this handles qemu quoting properly, so
3419 individual elements may contain commas and this will do the right
3420 thing.
3421 Returns 0 on success. Returns "-1" on error, setting "errno".
3423 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary"
3425 int
3427 qemuopts_set_binary (struct qemuopts *qopts, const char *binary)
3428 Set the qemu binary name.
3430 Returns 0 on success. Returns "-1" on error, setting "errno".
3432 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch"
3434 int
3436 qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)
3437 Set the qemu binary name to "qemu-system-[arch]".
3439 As a special case if "arch" is "NULL", the binary is set to the KVM
3441 binary for the current host architecture:
3442 qemuopts_set_binary_by_arch (qopts, NULL);
3444 Returns 0 on success. Returns "-1" on error, setting "errno".
3446 Function "common/qemuopts/qemuopts.c:qemuopts_to_script"
3448 int
3450 qemuopts_to_script (struct qemuopts *qopts, const char *filename)
3451 Write the qemu options to a script.
3453 "qemuopts_set_binary*" must be called first.
3455 The script file will start with "#!/bin/sh" and will be chmod to mode
3457 0755.
3458 Returns 0 on success. Returns "-1" on error, setting "errno".
3460 Function "common/qemuopts/qemuopts.c:shell_quote"
3462 static void
3464 shell_quote (const char *str, FILE *fp)
3465 Print "str" to "fp", shell-quoting it if necessary.
3467 Function "common/qemuopts/qemuopts.c:shell_and_comma_quote"
3469 static void
3471 shell_and_comma_quote (const char *str, FILE *fp)
3472 Print "str" to "fp" doing both shell and qemu comma quoting.
3474 Function "common/qemuopts/qemuopts.c:qemuopts_to_channel"
3476 int
3478 qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)
3479 Write the qemu options to a "FILE *fp".
3481 "qemuopts_set_binary*" must be called first.
3483 Only the qemu command line is written. The caller may need to add
3485 "#!/bin/sh" and may need to chmod the resulting file to 0755.
3486 Returns 0 on success. Returns "-1" on error, setting "errno".
3488 Function "common/qemuopts/qemuopts.c:qemuopts_to_argv"
3490 char **
3492 qemuopts_to_argv (struct qemuopts *qopts)
3493 Return a NULL-terminated argument list, of the kind that can be passed
3495 directly to execv(3).
3496 "qemuopts_set_binary*" must be called first. It will be returned as
3498 "argv[0]" in the returned list.
3499 The list of strings and the strings themselves must be freed by the
3501 caller.
3502 Returns "NULL" on error, setting "errno".
3504 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_file"
3506 int
3508 qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)
3509 Write the qemu options to a qemu config file, suitable for reading in
3511 using "qemu -readconfig filename".
3512 Note that qemu config files have limitations on content and quoting, so
3514 not all qemuopts structs can be written (this function returns an error
3515 in these cases). For more information see
3516 https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html
3517 https://bugs.launchpad.net/qemu/+bug/1686364
3518 Also, command line argument names and config file sections sometimes
3520 have different names. For example the equivalent of "-m 1024" is:
3521 [memory]
3523 size = "1024"
3524 This code does not attempt to convert between the two forms. You just
3526 need to know how to do that yourself.
3527 Returns 0 on success. Returns "-1" on error, setting "errno".
3529 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_channel"
3531 int
3533 qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)
3534 Same as "qemuopts_to_config_file", but this writes to a "FILE *fp".
3536 Subdirectory common/utils
3538 File common/utils/cleanups.c
3539 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3541 They are implemented using the "__attribute__((cleanup))" feature of
3542 gcc and clang. Typical usage is:
3543 fn ()
3545 {
3546 CLEANUP_FREE char *str = NULL;
3547 str = safe_asprintf (g, "foo");
3548 // str is freed automatically when the function returns
3549 }
3550 There are a few catches to be aware of with the cleanup mechanism:
3552 • If a cleanup variable is not initialized, then you can end up
3554 calling free(3) with an undefined value, resulting in the program
3555 crashing. For this reason, you should usually initialize every
3556 cleanup variable with something, eg. "NULL"
3557 • Don't mark variables holding return values as cleanup variables.
3559 • The "main()" function shouldn't use cleanup variables since it is
3561 normally exited by calling exit(3), and that doesn't call the
3562 cleanup handlers.
3563 The functions in this file are used internally by the "CLEANUP_*"
3565 macros. Don't call them directly.
3566 File common/utils/gnulib-cleanups.c
3568 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3570 They are implemented using the "__attribute__((cleanup))" feature of
3571 gcc and clang. Typical usage is:
3572 fn ()
3574 {
3575 CLEANUP_FREE char *str = NULL;
3576 str = safe_asprintf (g, "foo");
3577 // str is freed automatically when the function returns
3578 }
3579 There are a few catches to be aware of with the cleanup mechanism:
3581 • If a cleanup variable is not initialized, then you can end up
3583 calling free(3) with an undefined value, resulting in the program
3584 crashing. For this reason, you should usually initialize every
3585 cleanup variable with something, eg. "NULL"
3586 • Don't mark variables holding return values as cleanup variables.
3588 • The "main()" function shouldn't use cleanup variables since it is
3590 normally exited by calling exit(3), and that doesn't call the
3591 cleanup handlers.
3592 The functions in this file are used internally by the "CLEANUP_*"
3594 macros. Don't call them directly.
3595 File common/utils/guestfs-utils.h
3597 This header file is included in all "frontend" parts of libguestfs,
3599 namely the library, non-C language bindings, virt tools and tests.
3600 The daemon does not use this header. If you need a place to put
3602 something shared with absolutely everything including the daemon, put
3603 it in lib/guestfs-internal-all.h
3604 If a definition is only needed by a single component of libguestfs (eg.
3606 just the library, or just a single virt tool) then it should not be
3607 here!
3608 File common/utils/libxml2-writer-macros.h
3610 These macros make it easier to write XML. To use them correctly you
3612 must be aware of these assumptions:
3613 • The "xmlTextWriterPtr" is called "xo". It is used implicitly by
3615 all the macros.
3616 • On failure, a function called "xml_error" is called which you must
3618 define (usually as a macro). You must use "CLEANUP_*" macros in
3619 your functions if you want correct cleanup of local variables along
3620 the error path.
3621 • All the "bad" casting is hidden inside the macros.
3623 Definition "common/utils/libxml2-writer-macros.h:start_element"
3625 #define start_element
3627 To define an XML element use:
3629 start_element ("name") {
3631 ...
3632 } end_element ();
3633 which produces "<name>...</name>"
3635 Definition "common/utils/libxml2-writer-macros.h:empty_element"
3637 #define empty_element
3639 To define an empty element:
3641 empty_element ("name");
3643 which produces "<name/>"
3645 Definition "common/utils/libxml2-writer-macros.h:single_element"
3647 #define single_element
3649 To define a single element with no attributes containing some text:
3651 single_element ("name", text);
3653 which produces "<name>text</name>"
3655 Definition "common/utils/libxml2-writer-macros.h:single_element_format"
3657 #define single_element_format
3659 To define a single element with no attributes containing some text
3661 using a format string:
3662 single_element_format ("cores", "%d", nr_cores);
3664 which produces "<cores>4</cores>"
3666 Definition "common/utils/libxml2-writer-macros.h:attribute"
3668 #define attribute
3670 To define an XML element with attributes, use:
3672 start_element ("name") {
3674 attribute ("foo", "bar");
3675 attribute_format ("count", "%d", count);
3676 ...
3677 } end_element ();
3678 which produces "<name foo="bar" count="123">...</name>"
3680 Definition "common/utils/libxml2-writer-macros.h:attribute_ns"
3682 #define attribute_ns
3684 "attribute_ns (prefix, key, namespace_uri, value)" defines a namespaced
3686 attribute.
3687 Definition "common/utils/libxml2-writer-macros.h:string"
3689 #define string
3691 To define a verbatim string, use:
3693 string ("hello");
3695 Definition "common/utils/libxml2-writer-macros.h:string_format"
3697 #define string_format
3699 To define a verbatim string using a format string, use:
3701 string ("%s, world", greeting);
3703 Definition "common/utils/libxml2-writer-macros.h:base64"
3705 #define base64
3707 To write a string encoded as base64:
3709 base64 (data, size);
3711 Definition "common/utils/libxml2-writer-macros.h:comment"
3713 #define comment
3715 To define a comment in the XML, use:
3717 comment ("number of items = %d", nr_items);
3719 File common/utils/stringlists-utils.c
3721 Utility functions used by the library, tools and language bindings.
3723 These functions must not call internal library functions such as
3725 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3726 Function "common/utils/stringlists-utils.c:guestfs_int_split_string"
3728 char **
3730 guestfs_int_split_string (char sep, const char *str)
3731 Split string at separator character "sep", returning the list of
3733 strings. Returns "NULL" on memory allocation failure.
3734 Note (assuming "sep" is ":"):
3736 "str == NULL"
3738 aborts
3739 "str == """
3741 returns "[]"
3742 "str == "abc""
3744 returns "["abc"]"
3745 "str == ":""
3747 returns "["", ""]"
3748 File common/utils/utils.c
3750 Utility functions used by the library, tools and language bindings.
3752 These functions must not call internal library functions such as
3754 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3755 Function "common/utils/utils.c:guestfs_int_replace_string"
3757 char *
3759 guestfs_int_replace_string (const char *str, const char *s1, const char *s2)
3760 Replace every instance of "s1" appearing in "str" with "s2". A newly
3762 allocated string is returned which must be freed by the caller. If
3763 allocation fails this can return "NULL".
3764 For example:
3766 replace_string ("abcabb", "ab", "a");
3768 would return "acab".
3770 Function "common/utils/utils.c:guestfs_int_exit_status_to_string"
3772 char *
3774 guestfs_int_exit_status_to_string (int status, const char *cmd_name,
3775 char *buffer, size_t buflen)
3776 Translate a wait/system exit status into a printable string.
3778 Function "common/utils/utils.c:guestfs_int_random_string"
3780 int
3782 guestfs_int_random_string (char *ret, size_t len)
3783 Return a random string of characters.
3785 Notes:
3787 • The "ret" buffer must have length "len+1" in order to store the
3789 final "\0" character.
3790 • There is about 5 bits of randomness per output character (so about
3792 "5*len" bits of randomness in the resulting string).
3793 Function "common/utils/utils.c:guestfs_int_drive_name"
3795 char *
3797 guestfs_int_drive_name (size_t index, char *ret)
3798 This turns a drive index (eg. 27) into a drive name (eg. "ab").
3800 Drive indexes count from 0. The return buffer has to be large enough
3802 for the resulting string, and the returned pointer points to the *end*
3803 of the string.
3804 https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
3806 Function "common/utils/utils.c:guestfs_int_drive_index"
3808 ssize_t
3810 guestfs_int_drive_index (const char *name)
3811 The opposite of "guestfs_int_drive_name". Take a string like "ab" and
3813 return the index (eg 27).
3814 Note that you must remove any prefix such as "hd", "sd" etc, or any
3816 partition number before calling the function.
3817 Function "common/utils/utils.c:guestfs_int_is_true"
3819 int
3821 guestfs_int_is_true (const char *str)
3822 Similar to "Tcl_GetBoolean".
3824 Function "common/utils/utils.c:guestfs_int_string_is_valid"
3826 bool
3828 guestfs_int_string_is_valid (const char *str,
3829 size_t min_length, size_t max_length,
3830 int flags, const char *extra)
3831 Check a string for validity, that it contains only certain characters,
3833 and minimum and maximum length. This function is usually wrapped in a
3834 VALID_* macro, see lib/drives.c for an example.
3835 "str" is the string to check.
3837 "min_length" and "max_length" are the minimum and maximum length
3839 checks. 0 means no check.
3840 The flags control:
3842 "VALID_FLAG_ALPHA"
3844 7-bit ASCII-only alphabetic characters are permitted.
3845 "VALID_FLAG_DIGIT"
3847 7-bit ASCII-only digits are permitted.
3848 "extra" is a set of extra characters permitted, in addition to
3850 alphabetic and/or digits. ("extra = NULL" for no extra).
3851 Returns boolean "true" if the string is valid (passes all the tests),
3853 or "false" if not.
3854 Function "common/utils/utils.c:guestfs_int_fadvise_normal"
3856 void
3858 guestfs_int_fadvise_normal (int fd)
3859 Hint that we will read or write the file descriptor normally.
3861 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3863 and sets the per-file number of readahead pages to equal the block
3864 device readahead setting.
3865 It's OK to call this on a non-file since we ignore failure as it is
3867 only a hint.
3868 Function "common/utils/utils.c:guestfs_int_fadvise_sequential"
3870 void
3872 guestfs_int_fadvise_sequential (int fd)
3873 Hint that we will read or write the file descriptor sequentially.
3875 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3877 and sets the per-file number of readahead pages to twice the block
3878 device readahead setting.
3879 It's OK to call this on a non-file since we ignore failure as it is
3881 only a hint.
3882 Function "common/utils/utils.c:guestfs_int_fadvise_random"
3884 void
3886 guestfs_int_fadvise_random (int fd)
3887 Hint that we will read or write the file descriptor randomly.
3889 On Linux, this sets the "FMODE_RANDOM" flag on the file. The effect of
3891 this flag is to:
3892 • Disable normal sequential file readahead.
3894 • If any read of the file is done which misses in the page cache, 2MB
3896 are read into the page cache. [I think - I'm not sure I totally
3897 understand what this is doing]
3898 It's OK to call this on a non-file since we ignore failure as it is
3900 only a hint.
3901 Function "common/utils/utils.c:guestfs_int_fadvise_noreuse"
3903 void
3905 guestfs_int_fadvise_noreuse (int fd)
3906 Hint that we will access the data only once.
3908 On Linux, this does nothing.
3910 It's OK to call this on a non-file since we ignore failure as it is
3912 only a hint.
3913 Function "common/utils/utils.c:guestfs_int_fadvise_dontneed"
3915 void
3917 guestfs_int_fadvise_dontneed (int fd)
3918 Hint that we will not access the data in the near future.
3920 On Linux, this immediately writes out any dirty pages in the page cache
3922 and then invalidates (drops) all pages associated with this file from
3923 the page cache. Apparently it does this even if the file is opened or
3924 being used by other processes. This setting is not persistent; if you
3925 subsequently read the file it will be cached in the page cache as
3926 normal.
3927 It's OK to call this on a non-file since we ignore failure as it is
3929 only a hint.
3930 Function "common/utils/utils.c:guestfs_int_fadvise_willneed"
3932 void
3934 guestfs_int_fadvise_willneed (int fd)
3935 Hint that we will access the data in the near future.
3937 On Linux, this immediately reads the whole file into the page cache.
3939 This setting is not persistent; subsequently pages may be dropped from
3940 the page cache as normal.
3941 It's OK to call this on a non-file since we ignore failure as it is
3943 only a hint.
3944 Function "common/utils/utils.c:guestfs_int_shell_unquote"
3946 char *
3948 guestfs_int_shell_unquote (const char *str)
3949 Unquote a shell-quoted string.
3951 Augeas passes strings to us which may be quoted, eg. if they come from
3953 files in /etc/sysconfig. This function can do simple unquoting of
3954 these strings.
3955 Note this function does not do variable substitution, since that is
3957 impossible without knowing the file context and indeed the environment
3958 under which the shell script is run. Configuration files should not
3959 use complex quoting.
3960 "str" is the input string from Augeas, a string that may be single- or
3962 double-quoted or may not be quoted. The returned string is unquoted,
3963 and must be freed by the caller. "NULL" is returned on error and
3964 "errno" is set accordingly.
3965 For information on double-quoting in bash, see
3967 https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html
3968 Function "common/utils/utils.c:guestfs_int_is_reg"
3970 int
3972 guestfs_int_is_reg (int64_t mode)
3973 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3975 field represents a regular file.
3976 Function "common/utils/utils.c:guestfs_int_is_dir"
3978 int
3980 guestfs_int_is_dir (int64_t mode)
3981 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3983 field represents a directory.
3984 Function "common/utils/utils.c:guestfs_int_is_chr"
3986 int
3988 guestfs_int_is_chr (int64_t mode)
3989 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3991 field represents a char device.
3992 Function "common/utils/utils.c:guestfs_int_is_blk"
3994 int
3996 guestfs_int_is_blk (int64_t mode)
3997 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3999 field represents a block device.
4000 Function "common/utils/utils.c:guestfs_int_is_fifo"
4002 int
4004 guestfs_int_is_fifo (int64_t mode)
4005 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4007 field represents a named pipe (FIFO).
4008 Function "common/utils/utils.c:guestfs_int_is_lnk"
4010 int
4012 guestfs_int_is_lnk (int64_t mode)
4013 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4015 field represents a symbolic link.
4016 Function "common/utils/utils.c:guestfs_int_is_sock"
4018 int
4020 guestfs_int_is_sock (int64_t mode)
4021 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
4023 field represents a Unix domain socket.
4024 Function "common/utils/utils.c:guestfs_int_full_path"
4026 char *
4028 guestfs_int_full_path (const char *dir, const char *name)
4029 Concatenate "dir" and "name" to create a path. This correctly handles
4031 the case of concatenating "/" + "filename" as well as "/dir" +
4032 "filename". "name" may be "NULL".
4033 The caller must free the returned path.
4035 This function sets "errno" and returns "NULL" on error.
4037 Function "common/utils/utils.c:guestfs_int_hexdump"
4039 void
4041 guestfs_int_hexdump (const void *data, size_t len, FILE *fp)
4042 Hexdump a block of memory to "FILE *", used for debugging.
4044 Subdirectory common/visit
4046 File common/visit/visit.c
4047 This file contains a recursive function for visiting all files and
4049 directories in a guestfs filesystem.
4050 Adapted from
4052 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/
4053 Function "common/visit/visit.c:visit"
4055 int
4057 visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)
4058 Visit every file and directory in a guestfs filesystem, starting at
4060 "dir".
4061 "dir" may be "/" to visit the entire filesystem, or may be some
4063 subdirectory. Symbolic links are not followed.
4064 The visitor function "f" is called once for every directory and every
4066 file. The parameters passed to "f" include the current directory name,
4067 the current file name (or "NULL" when we're visiting a directory), the
4068 "guestfs_statns" (file permissions etc), and the list of extended
4069 attributes of the file. The visitor function may return "-1" which
4070 causes the whole recursion to stop with an error.
4071 Also passed to this function is an "opaque" pointer which is passed
4073 through to the visitor function.
4074 Returns 0 if everything went OK, or "-1" if there was an error. Error
4076 handling is not particularly well defined. It will either set an error
4077 in the libguestfs handle or print an error on stderr, but there is no
4078 way for the caller to tell the difference.
4079 Subdirectory common/windows
4081 File common/windows/windows.c
4082 This file implements "win:" Windows file path support in guestfish(1).
4084 Function "common/windows/windows.c:is_windows"
4086 int
4088 is_windows (guestfs_h *g, const char *root)
4089 Checks whether "root" is a Windows installation.
4091 This relies on an already being done introspection.
4093 Function "common/windows/windows.c:windows_path"
4095 char *
4097 windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
4098 Resolves "path" as possible Windows path according to "root", giving a
4100 new path that can be used in libguestfs API calls.
4101 Notes:
4103 • "root" must be a Windows installation
4105 • relies on an already being done introspection
4107 • will unmount all the existing mount points and mount the Windows
4109 root (according to "readonly")
4110 • calls exit(3) on memory allocation failures
4112 Subdirectory daemon
4114 File daemon/command.c
4115 This file contains a number of useful functions for running external
4117 commands and capturing their output.
4118 Function "daemon/command.c:commandf"
4120 int
4122 commandf (char **stdoutput, char **stderror, unsigned flags,
4123 const char *name, ...)
4124 Run a command. Optionally capture stdout and stderr as strings.
4126 Returns 0 if the command ran successfully, or "-1" if there was any
4128 error.
4129 For a description of the "flags" see "commandrvf".
4131 There is also a macro "command(out,err,name,...)" which calls
4133 "commandf" with "flags=0".
4134 Function "daemon/command.c:commandrf"
4136 int
4138 commandrf (char **stdoutput, char **stderror, unsigned flags,
4139 const char *name, ...)
4140 Same as "command", but we allow the status code from the subcommand to
4142 be non-zero, and return that status code.
4143 We still return "-1" if there was some other error.
4145 There is also a macro "commandr(out,err,name,...)" which calls
4147 "commandrf" with "flags=0".
4148 Function "daemon/command.c:commandvf"
4150 int
4152 commandvf (char **stdoutput, char **stderror, unsigned flags,
4153 char const *const *argv)
4154 Same as "command", but passing in an argv array.
4156 There is also a macro "commandv(out,err,argv)" which calls "commandvf"
4158 with "flags=0".
4159 Function "daemon/command.c:commandrvf"
4161 int
4163 commandrvf (char **stdoutput, char **stderror, unsigned flags,
4164 char const* const *argv)
4165 This is a more sane version of system(3) for running external commands.
4167 It uses fork/execvp, so we don't need to worry about quoting of
4168 parameters, and it allows us to capture any error messages in a buffer.
4169 If "stdoutput" is not "NULL", then *stdoutput will return the stdout of
4171 the command as a string.
4172 If "stderror" is not "NULL", then *stderror will return the stderr of
4174 the command. If there is a final \n character, it is removed so you
4175 can use the error string directly in a call to "reply_with_error".
4176 Flags are:
4178 "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR"
4180 For broken external commands that send error messages to stdout
4181 (hello, parted) but that don't have any useful stdout information,
4182 use this flag to capture the error messages in the *stderror
4183 buffer. If using this flag, you should pass "stdoutput=NULL"
4184 because nothing could ever be captured in that buffer.
4185 "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN"
4187 For running external commands on chrooted files correctly (see
4188 https://bugzilla.redhat.com/579608) specifying this flag causes
4189 another process to be forked which chroots into sysroot and just
4190 copies the input file to stdin of the specified command. The file
4191 descriptor is ORed with the flags, and that file descriptor is
4192 always closed by this function. See daemon/hexdump.c for an
4193 example of usage.
4194 There is also a macro "commandrv(out,err,argv)" which calls
4196 "commandrvf" with "flags=0".
4197 File daemon/device-name-translation.c
4199 Function
4201 "daemon/device-name-translation.c:device_name_translation_init"
4202 void
4204 device_name_translation_init (void)
4205 Cache daemon disk mapping.
4207 When the daemon starts up, populate a cache with the contents of
4209 /dev/disk/by-path. It's easiest to use "ls -lv" here since the names
4210 are sorted awkwardly.
4211 Function "daemon/device-name-translation.c:device_name_translation"
4213 char *
4215 device_name_translation (const char *device)
4216 Perform device name translation.
4218 Libguestfs defines a few standard formats for device names. (see also
4220 "BLOCK DEVICE NAMING" in guestfs(3) and "guestfs_canonical_device_name"
4221 in guestfs(3)). They are:
4222 /dev/sdX[N]
4224 /dev/hdX[N]
4225 /dev/vdX[N]
4226 These mean the Nth partition on the Xth device. Because Linux no
4227 longer enumerates devices in the order they are passed to qemu, we
4228 must translate these by looking up the actual device using
4229 /dev/disk/by-path/
4230 /dev/mdX
4232 /dev/VG/LV
4233 /dev/mapper/...
4234 /dev/dm-N
4235 These are not translated here.
4236 It returns a newly allocated string which the caller must free.
4238 It returns "NULL" on error. Note it does not call "reply_with_*".
4240 We have to open the device and test for "ENXIO", because the device
4242 nodes may exist in the appliance.
4243 File daemon/guestfsd.c
4245 This is the guestfs daemon which runs inside the guestfs appliance.
4247 This file handles start up and connecting back to the library.
4248 Function "daemon/guestfsd.c:print_shell_quote"
4250 static int
4252 print_shell_quote (FILE *stream,
4253 const struct printf_info *info ATTRIBUTE_UNUSED,
4254 const void *const *args)
4255 printf helper function so we can use %Q ("quoted") and %R to print
4257 shell-quoted strings. See guestfs-hacking(1) for more details.
4258 File daemon/internal.c
4260 Internal functions that are not part of the public API.
4262 File daemon/utils-c.c
4264 Bindings for utility functions.
4266 Note that functions called from OCaml code must never call any of the
4268 "reply*" functions.
4269 File daemon/utils.c
4271 Miscellaneous utility functions used by the daemon.
4273 Function "daemon/utils.c:is_root_device_stat"
4275 static int
4277 is_root_device_stat (struct stat *statbuf)
4278 Return true iff device is the root device (and therefore should be
4280 ignored from the point of view of user calls).
4281 Function "daemon/utils.c:is_device_parameter"
4283 int
4285 is_device_parameter (const char *device)
4286 Parameters marked as "Device", "Dev_or_Path", etc can be passed a block
4288 device name. This function tests if the parameter is a block device
4289 name.
4290 It can also be used in daemon code to test if the string passed as a
4292 "Dev_or_Path" parameter is a device or path.
4293 Function "daemon/utils.c:sysroot_path"
4295 char *
4297 sysroot_path (const char *path)
4298 Turn "/path" into "/sysroot/path".
4300 Returns "NULL" on failure. The caller must check for this and call
4302 "reply_with_perror ("malloc")". The caller must also free the returned
4303 string.
4304 See also the custom %R printf formatter which does shell quoting too.
4306 Function "daemon/utils.c:sysroot_realpath"
4308 char *
4310 sysroot_realpath (const char *path)
4311 Resolve path within sysroot, calling "sysroot_path" on the resolved
4313 path.
4314 Returns "NULL" on failure. The caller must check for this and call
4316 "reply_with_perror ("malloc")". The caller must also free the returned
4317 string.
4318 See also the custom %R printf formatter which does shell quoting too.
4320 Function "daemon/utils.c:is_power_of_2"
4322 int
4324 is_power_of_2 (unsigned long v)
4325 Returns true if "v" is a power of 2.
4327 Uses the algorithm described at
4329 http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2
4330 Function "daemon/utils.c:split_lines_sb"
4332 struct stringsbuf
4334 split_lines_sb (char *str)
4335 Split an output string into a NULL-terminated list of lines, wrapped
4337 into a stringsbuf.
4338 Typically this is used where we have run an external command which has
4340 printed out a list of things, and we want to return an actual list.
4341 The corner cases here are quite tricky. Note in particular:
4343 "" returns "[]"
4345 "\n"
4347 returns "[""]"
4348 "a\nb"
4350 returns "["a"; "b"]"
4351 "a\nb\n"
4353 returns "["a"; "b"]"
4354 "a\nb\n\n"
4356 returns "["a"; "b"; ""]"
4357 The original string is written over and destroyed by this function
4359 (which is usually OK because it's the 'out' string from "command*()").
4360 You can free the original string, because "add_string()" strdups the
4361 strings.
4362 "argv" in the "struct stringsbuf" will be "NULL" in case of errors.
4364 Function "daemon/utils.c:filter_list"
4366 char **
4368 filter_list (bool (*p) (const char *str), char **strs)
4369 Filter a list of strings. Returns a newly allocated list of only the
4371 strings where "p (str) == true".
4372 Note it does not copy the strings, be careful not to double-free them.
4374 Function "daemon/utils.c:trim"
4376 void
4378 trim (char *str)
4379 Skip leading and trailing whitespace, updating the original string in-
4381 place.
4382 Function "daemon/utils.c:parse_btrfsvol"
4384 int
4386 parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
4387 Parse the mountable descriptor for a btrfs subvolume. Don't call this
4389 directly; it is only used from the stubs.
4390 A btrfs subvolume is given as:
4392 btrfsvol:/dev/sda3/root
4394 where /dev/sda3 is a block device containing a btrfs filesystem, and
4396 root is the name of a subvolume on it. This function is passed the
4397 string following "btrfsvol:".
4398 On success, "mountable->device" and "mountable->volume" must be freed
4400 by the caller.
4401 Function "daemon/utils.c:mountable_to_string"
4403 char *
4405 mountable_to_string (const mountable_t *mountable)
4406 Convert a "mountable_t" back to its string representation
4408 This function can be used in an error path, so must not call
4410 "reply_with_error".
4411 Function "daemon/utils.c:prog_exists"
4413 int
4415 prog_exists (const char *prog)
4416 Check program exists and is executable on $PATH.
4418 Function "daemon/utils.c:random_name"
4420 int
4422 random_name (char *template)
4423 Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
4425 template to contain a randomly named file. Any 'X' characters after
4426 the final '/' in the template are replaced with random characters.
4427 Notes: You should probably use an 8.3 path, so it's compatible with all
4429 filesystems including basic FAT. Also this only substitutes lowercase
4430 ASCII letters and numbers, again for compatibility with lowest common
4431 denominator filesystems.
4432 This doesn't create a file or check whether or not the file exists (it
4434 would be extremely unlikely to exist as long as the RNG is working).
4435 If there is an error, "-1" is returned.
4437 Function "daemon/utils.c:udev_settle_file"
4439 void
4441 udev_settle_file (const char *file)
4442 LVM and other commands aren't synchronous, especially when udev is
4444 involved. eg. You can create or remove some device, but the "/dev"
4445 device node won't appear until some time later. This means that you
4446 get an error if you run one command followed by another.
4447 Use "udevadm settle" after certain commands, but don't be too fussed if
4449 it fails.
4450 Function "daemon/utils.c:make_exclude_from_file"
4452 char *
4454 make_exclude_from_file (const char *function, char *const *excludes)
4455 Turn list "excludes" into a temporary file, and return a string
4457 containing the temporary file name. Caller must unlink the file and
4458 free the string.
4459 "function" is the function that invoked this helper, and it is used
4461 mainly for errors/debugging.
4462 Function "daemon/utils.c:read_whole_file"
4464 char *
4466 read_whole_file (const char *filename, size_t *size_r)
4467 Read whole file into dynamically allocated array. If there is an
4469 error, DON'T call reply_with_perror, just return NULL. Returns a
4470 "\0"-terminated string. "size_r" can be specified to get the size of
4471 the returned data.
4472 File daemon/xattr.c
4474 Function "daemon/xattr.c:split_attr_names"
4476 static char **
4478 split_attr_names (char *buf, size_t len)
4479 listxattr(2) returns the string "foo\0bar\0baz" of length "len". (The
4481 last string in the list is \0-terminated but the \0 is not included in
4482 "len").
4483 This function splits it into a regular list of strings.
4485 Note that the returned list contains pointers to the original strings
4487 in "buf" so be careful that you do not double-free them.
4488 Subdirectory fish
4490 File fish/alloc.c
4491 This file implements the guestfish "alloc" and "sparse" commands.
4493 Function "fish/alloc.c:alloc_disk"
4495 int
4497 alloc_disk (const char *filename, const char *size_str, int add, int sparse)
4498 This is the underlying allocation function. It's called from a few
4500 other places in guestfish.
4501 File fish/copy.c
4503 This file implements the guestfish commands "copy-in" and "copy-out".
4505 File fish/destpaths.c
4507 The file handles tab-completion of filesystem paths in guestfish.
4509 File fish/display.c
4511 The file implements the guestfish "display" command, for displaying
4513 graphical files (icons, images) in disk images.
4514 File fish/echo.c
4516 The file implements the guestfish "echo" command.
4518 File fish/edit.c
4520 guestfish "edit" command, suggested by Ján Ondrej.
4522 File fish/events.c
4524 This file implements the guestfish event-related commands, "event",
4526 "delete-event" and "list-events".
4527 File fish/fish.c
4529 guestfish, the guest filesystem shell. This file contains the main
4531 loop and utilities.
4532 Function "fish/fish.c:parse_command_line"
4534 static struct parsed_command
4536 parse_command_line (char *buf, int *exit_on_error_rtn)
4537 Parse a command string, splitting at whitespace, handling '!', '#' etc.
4539 This destructively updates "buf".
4540 "exit_on_error_rtn" is used to pass in the global "exit_on_error"
4542 setting and to return the local setting (eg. if the command begins with
4543 '-').
4544 Returns in "parsed_command.status":
4546 1 got a guestfish command (returned in
4548 "cmd_rtn"/"argv_rtn"/"pipe_rtn")
4549 0 no guestfish command, but otherwise OK
4551 "-1"
4553 an error
4554 Function "fish/fish.c:parse_quoted_string"
4556 static ssize_t
4558 parse_quoted_string (char *p)
4559 Parse double-quoted strings, replacing backslash escape sequences with
4561 the true character. Since the string is returned in place, the escapes
4562 must make the string shorter.
4563 Function "fish/fish.c:execute_and_inline"
4565 static int
4567 execute_and_inline (const char *cmd, int global_exit_on_error)
4568 Used to handle "<!" (execute command and inline result).
4570 Function "fish/fish.c:issue_command"
4572 int
4574 issue_command (const char *cmd, char *argv[], const char *pipecmd,
4575 int rc_exit_on_error_flag)
4576 Run a command.
4578 "rc_exit_on_error_flag" is the "exit_on_error" flag that we pass to the
4580 remote server (when issuing --remote commands). It does not cause
4581 "issue_command" itself to exit on error.
4582 Function "fish/fish.c:extended_help_message"
4584 void
4586 extended_help_message (void)
4587 Print an extended help message when the user types in an unknown
4589 command for the first command issued. A common case is the user doing:
4590 guestfish disk.img
4592 expecting guestfish to open disk.img (in fact, this tried to run a non-
4594 existent command "disk.img").
4595 Function "fish/fish.c:error_cb"
4597 static void
4599 error_cb (guestfs_h *g, void *data, const char *msg)
4600 Error callback. This replaces the standard libguestfs error handler.
4602 Function "fish/fish.c:free_n_strings"
4604 static void
4606 free_n_strings (char **str, size_t len)
4607 Free strings from a non-NULL terminated "char**".
4609 Function "fish/fish.c:decode_ps1"
4611 static char *
4613 decode_ps1 (const char *str)
4614 Decode "str" into the final printable prompt string.
4616 Function "fish/fish.c:win_prefix"
4618 char *
4620 win_prefix (const char *path)
4621 Resolve the special "win:..." form for Windows-specific paths. The
4623 generated code calls this for all device or path arguments.
4624 The function returns a newly allocated string, and the caller must free
4626 this string; else display an error and return "NULL".
4627 Function "fish/fish.c:file_in"
4629 char *
4631 file_in (const char *arg)
4632 Resolve the special "FileIn" paths ("-" or "-<<END" or filename).
4634 The caller (fish/cmds.c) will call "free_file_in" after the command has
4636 run which should clean up resources.
4637 Function "fish/fish.c:file_out"
4639 char *
4641 file_out (const char *arg)
4642 Resolve the special "FileOut" paths ("-" or filename).
4644 The caller (fish/cmds.c) will call "free (str)" after the command has
4646 run.
4647 Function "fish/fish.c:progress_callback"
4649 void
4651 progress_callback (guestfs_h *g, void *data,
4652 uint64_t event, int event_handle, int flags,
4653 const char *buf, size_t buf_len,
4654 const uint64_t *array, size_t array_len)
4655 Callback which displays a progress bar.
4657 File fish/glob.c
4659 This file implements the guestfish "glob" command.
4661 Function "fish/glob.c:expand_devicename"
4663 static char **
4665 expand_devicename (guestfs_h *g, const char *device)
4666 Glob-expand device patterns, such as "/dev/sd*"
4668 (https://bugzilla.redhat.com/635971).
4669 There is no "guestfs_glob_expand_device" function because the
4671 equivalent can be implemented using functions like
4672 "guestfs_list_devices".
4673 It's not immediately clear what it means to expand a pattern like
4675 "/dev/sd*". Should that include device name translation? Should the
4676 result include partitions as well as devices?
4677 Should "/dev/" + "*" return every possible device and filesystem? How
4679 about VGs? LVs?
4680 To solve this what we do is build up a list of every device, partition,
4682 etc., then glob against that list.
4683 Notes for future work (XXX):
4685 • This doesn't handle device name translation. It wouldn't be too
4687 hard to add.
4688 • Could have an API function for returning all device-like things.
4690 Function "fish/glob.c:add_strings_matching"
4692 static int
4694 add_strings_matching (char **pp, const char *glob,
4695 char ***ret, size_t *size_r)
4696 Using POSIX fnmatch(3), find strings in the list "pp" which match
4698 pattern "glob". Add strings which match to the "ret" array. *size_r
4699 is the current size of the "ret" array, which is updated with the new
4700 size.
4701 Function "fish/glob.c:single_element_list"
4703 static char **
4705 single_element_list (const char *element)
4706 Return a single element list containing "element".
4708 File fish/help.c
4710 The file implements the guestfish "help" command.
4712 Function "fish/help.c:display_help"
4714 int
4716 display_help (const char *cmd, size_t argc, char *argv[])
4717 The "help" command.
4719 This used to just list all commands, but that's not very useful.
4721 Instead display some useful context-sensitive help. This could be
4722 improved if we knew how many drives had been added already, and whether
4723 anything was mounted.
4724 File fish/hexedit.c
4726 This file implements the guestfish "hexedit" command.
4728 File fish/lcd.c
4730 Function "fish/lcd.c:run_lcd"
4732 int
4734 run_lcd (const char *cmd, size_t argc, char *argv[])
4735 guestfish "lcd" command (similar to the "lcd" command in BSD ftp).
4737 File fish/man.c
4739 Function "fish/man.c:run_man"
4741 int
4743 run_man (const char *cmd, size_t argc, char *argv[])
4744 guestfish "man" command
4746 File fish/more.c
4748 This file implements the guestfish "more" command.
4750 File fish/prep.c
4752 This file implements the guestfish -N option for creating pre-prepared
4754 disk layouts.
4755 File fish/rc.c
4757 This file implements guestfish remote (command) support.
4759 Function "fish/rc.c:rc_listen"
4761 void
4763 rc_listen (void)
4764 The remote control server (ie. "guestfish --listen").
4766 Function "fish/rc.c:rc_remote"
4768 int
4770 rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
4771 int exit_on_error)
4772 The remote control client (ie. "guestfish --remote").
4774 File fish/reopen.c
4776 This file implements the guestfish "reopen" command.
4778 File fish/setenv.c
4780 This file implements the guestfish "setenv" and "unsetenv" commands.
4782 File fish/supported.c
4784 This file implements the guestfish "supported" command.
4786 File fish/tilde.c
4788 This file implements tilde ("~") expansion of home directories in
4790 guestfish(1).
4791 Function "fish/tilde.c:try_tilde_expansion"
4793 char *
4795 try_tilde_expansion (char *str)
4796 This is called from the script loop if we find a candidate for
4798 "~username" (tilde-expansion).
4799 Function "fish/tilde.c:expand_home"
4801 static char *
4803 expand_home (char *orig, const char *append)
4804 Return $HOME + append string.
4806 Function "fish/tilde.c:find_home_for_username"
4808 static const char *
4810 find_home_for_username (const char *username, size_t ulen)
4811 Lookup "username" (of length "ulen"), return home directory if found,
4813 or "NULL" if not found.
4814 File fish/time.c
4816 This file implements the guestfish "time" command.
4818 Subdirectory python
4820 File python/handle.c
4821 This file contains a small number of functions that are written by
4823 hand. The majority of the bindings are generated (see
4824 python/actions-*.c).
4825
4827 guestfs(3), guestfs-building(1), guestfs-examples(3),
4828 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
4829 guestfs-testing(1), libguestfs-test-tool(1),
4830 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
4831
4833 Richard W.M. Jones ("rjones at redhat dot com")
4834
4836 Copyright (C) 2009-2020 Red Hat Inc.
4837
4839 This library is free software; you can redistribute it and/or modify it
4840 under the terms of the GNU Lesser General Public License as published
4841 by the Free Software Foundation; either version 2 of the License, or
4842 (at your option) any later version.
4843 This library is distributed in the hope that it will be useful, but
4845 WITHOUT ANY WARRANTY; without even the implied warranty of
4846 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4847 Lesser General Public License for more details.
4848 You should have received a copy of the GNU Lesser General Public
4850 License along with this library; if not, write to the Free Software
4851 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
4852 02110-1301 USA
4853
4855 To get a list of bugs against libguestfs, use this link:
4856 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
4857 To report a new bug against libguestfs, use this link:
4859 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
4860 When reporting a bug, please supply:
4862 • The version of libguestfs.
4864 • Where you got libguestfs (eg. which Linux distro, compiled from
4866 source, etc)
4867 • Describe the bug accurately and give a way to reproduce it.
4869 • Run libguestfs-test-tool(1) and paste the complete, unedited output
4871 into the bug report.
4872libguestfs-1.46.0 2021-09-23 guestfs-hacking(1)