1guestfs-hacking(1) Virtualization Support guestfs-hacking(1)
2
3
4
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
15 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
21 Libguestfs uses an autotools-based build system, with the main files
22 being configure.ac and Makefile.am. See "THE BUILD SYSTEM".
23
24 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
31 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
39 To build from source, first read the guestfs-building(1).
40
41 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
52 align
53 virt-alignment-scan(1) command and documentation.
54
55 appliance
56 The libguestfs appliance, build scripts and so on.
57
58 bash
59 Bash tab-completion scripts.
60
61 build-aux
62 Various build scripts used by autotools.
63
64 builder
65 virt-builder(1) command and documentation.
66
67 cat The virt-cat(1), virt-filesystems(1), virt-log(1), virt-ls(1) and
68 virt-tail(1) commands and documentation.
69
70 common
71 Various libraries of internal code can be found in the common
72 subdirectory:
73
74 common/edit
75 Common code for interactively and non-interactively editing
76 files within a libguestfs filesystem.
77
78 common/errnostring
79 The communication protocol used between the library and the
80 daemon running inside the appliance has to encode errnos as
81 strings, which is handled by this library.
82
83 common/mlcustomize
84 Library code associated with "virt-customize" but also used in
85 other tools.
86
87 common/mlgettext
88 Small, generated wrapper which allows libguestfs to be compiled
89 with or without ocaml-gettext. This is generated by
90 ./configure.
91
92 common/mlpcre
93 Lightweight OCaml bindings for Perl Compatible Regular
94 Expressions (PCRE). Note this is not related in any way to
95 Markus Mottl's ocaml-pcre library.
96
97 common/mlprogress
98 OCaml bindings for the progress bar functions (see
99 common/progress).
100
101 common/mlstdutils
102 A library of pure OCaml utility functions used in many places.
103
104 common/mltools
105 OCaml utility functions only used by the OCaml virt tools (like
106 "virt-sysprep", "virt-customize" etc.)
107
108 common/mlutils
109 OCaml bindings for C functions in "common/utils", and some
110 POSIX bindings which are missing from the OCaml stdlib.
111
112 common/mlvisit
113 OCaml bindings for the visit functions (see common/visit).
114
115 common/mlxml
116 OCaml bindings for the libxml2 library.
117
118 common/options
119 Common options parsing for guestfish, guestmount and some virt
120 tools.
121
122 common/parallel
123 A framework used for processing multiple libvirt domains in
124 parallel.
125
126 common/progress
127 Common code for printing progress bars.
128
129 common/protocol
130 The XDR-based communication protocol used between the library
131 and the daemon running inside the appliance is defined here.
132
133 common/qemuopts
134 Mini-library for writing qemu command lines and qemu config
135 files.
136
137 common/structs
138 Common code for printing and freeing libguestfs structs, used
139 by the library and some tools.
140
141 common/utils
142 Various utility functions used throughout the library and
143 tools.
144
145 common/visit
146 Recursively visit a guestfs filesystem hierarchy.
147
148 common/windows
149 Utility functions for handling Windows drive letters.
150
151 contrib
152 Outside contributions, experimental parts.
153
154 customize
155 virt-customize(1) command and documentation.
156
157 daemon
158 The daemon that runs inside the libguestfs appliance and carries
159 out actions.
160
161 df virt-df(1) command and documentation.
162
163 dib virt-dib(1) command and documentation.
164
165 diff
166 virt-diff(1) command and documentation.
167
168 docs
169 Miscellaneous manual pages.
170
171 edit
172 virt-edit(1) command and documentation.
173
174 examples
175 C API example code.
176
177 fish
178 guestfish(1), the command-line shell, and various shell scripts
179 built on top such as virt-copy-in(1), virt-copy-out(1),
180 virt-tar-in(1), virt-tar-out(1).
181
182 format
183 virt-format(1) command and documentation.
184
185 fuse
186 guestmount(1), FUSE (userspace filesystem) built on top of
187 libguestfs.
188
189 generator
190 The crucially important generator, used to automatically generate
191 large amounts of boilerplate C code for things like RPC and
192 bindings.
193
194 get-kernel
195 virt-get-kernel(1) command and documentation.
196
197 inspector
198 virt-inspector(1), the virtual machine image inspector.
199
200 lib Source code to the C library.
201
202 logo
203 Logo used on the website. The fish is called Arthur by the way.
204
205 m4 M4 macros used by autoconf. See "THE BUILD SYSTEM".
206
207 make-fs
208 virt-make-fs(1) command and documentation.
209
210 po Translations of simple gettext strings.
211
212 po-docs
213 The build infrastructure and PO files for translations of manpages
214 and POD files. Eventually this will be combined with the po
215 directory, but that is rather complicated.
216
217 rescue
218 virt-rescue(1) command and documentation.
219
220 resize
221 virt-resize(1) command and documentation.
222
223 sparsify
224 virt-sparsify(1) command and documentation.
225
226 sysprep
227 virt-sysprep(1) command and documentation.
228
229 tests
230 Tests.
231
232 test-data
233 Files and other test data used by the tests.
234
235 test-tool
236 Test tool for end users to test if their qemu/kernel combination
237 will work with libguestfs.
238
239 tmp Used for temporary files when running the tests (instead of /tmp
240 etc). The reason is so that you can run multiple parallel tests of
241 libguestfs without having one set of tests overwriting the
242 appliance created by another.
243
244 tools
245 Command line tools written in Perl (virt-win-reg(1) and many
246 others).
247
248 utils
249 Miscellaneous utilities, such as "boot-benchmark".
250
251 v2v Up to libguestfs > 1.42 this contained the virt-v2v(1) tool, but
252 this has now moved into a separate repository:
253 https://github.com/libguestfs/virt-v2v
254
255 website
256 The http://libguestfs.org website files.
257
258 csharp
259 erlang
260 gobject
261 golang
262 haskell
263 java
264 lua
265 ocaml
266 php
267 perl
268 python
269 ruby
270 Language bindings.
271
272 THE BUILD SYSTEM
273 Libguestfs uses the GNU autotools build system (autoconf, automake,
274 libtool).
275
276 The ./configure script is generated from configure.ac and
277 m4/guestfs-*.m4. Most of the configure script is split over many m4
278 macro files by topic, for example m4/guestfs-daemon.m4 deals with the
279 dependencies of the daemon.
280
281 The job of the top level Makefile.am is mainly to list the
282 subdirectories ("SUBDIRS") in the order they should be compiled.
283
284 common-rules.mk is included in every Makefile.am (top level and
285 subdirectories). subdir-rules.mk is included only in subdirectory
286 Makefile.am files.
287
288 There are many make targets. Use this command to list them all:
289
290 make help
291
293 ADDING A NEW API
294 Because large amounts of boilerplate code in libguestfs are generated,
295 this makes it easy to extend the libguestfs API.
296
297 To add a new API action there are two changes:
298
299 1. You need to add a description of the call (name, parameters, return
300 type, tests, documentation) to generator/actions_*.ml and possibly
301 generator/proc_nr.ml.
302
303 There are two sorts of API action, depending on whether the call
304 goes through to the daemon in the appliance, or is serviced
305 entirely by the library (see "ARCHITECTURE" in
306 guestfs-internals(1)). "guestfs_sync" in guestfs(3) is an example
307 of the former, since the sync is done in the appliance.
308 "guestfs_set_trace" in guestfs(3) is an example of the latter,
309 since a trace flag is maintained in the handle and all tracing is
310 done on the library side.
311
312 Most new actions are of the first type, and get added to the
313 "daemon_functions" list. Each function has a unique procedure
314 number used in the RPC protocol which is assigned to that action
315 when we publish libguestfs and cannot be reused. Take the latest
316 procedure number and increment it.
317
318 For library-only actions of the second type, add to the
319 "non_daemon_functions" list. Since these functions are serviced by
320 the library and do not travel over the RPC mechanism to the daemon,
321 these functions do not need a procedure number, and so the
322 procedure number is set to -1.
323
324 2. Implement the action (in C):
325
326 For daemon actions, implement the function "do_<name>" in the
327 "daemon/" directory.
328
329 For library actions, implement the function "guestfs_impl_<name>"
330 in the "lib/" directory.
331
332 In either case, use another function as an example of what to do.
333
334 3. As an alternative to step 2: Since libguestfs 1.38, daemon actions
335 can be implemented in OCaml. You have to set the "impl = OCaml
336 ..." flag in the generator. Take a look at daemon/file.ml for an
337 example.
338
339 After making these changes, use "make" to compile.
340
341 Note that you don’t need to implement the RPC, language bindings,
342 manual pages or anything else. It’s all automatically generated from
343 the OCaml description.
344
345 Adding tests for an API
346
347 You can supply zero or as many tests as you want per API call. The
348 tests can either be added as part of the API description
349 (generator/actions_*.ml), or in some rarer cases you may want to drop a
350 script into "tests/*/". Note that adding a script to "tests/*/" is
351 slower, so if possible use the first method.
352
353 The following describes the test environment used when you add an API
354 test in actions_*.ml.
355
356 The test environment has 4 block devices:
357
358 /dev/sda 2 GB
359 General block device for testing.
360
361 /dev/sdb 2 GB
362 /dev/sdb1 is an ext2 filesystem used for testing filesystem write
363 operations.
364
365 /dev/sdc 10 MB
366 Used in a few tests where two block devices are needed.
367
368 /dev/sdd
369 ISO with fixed content (see images/test.iso).
370
371 To be able to run the tests in a reasonable amount of time, the
372 libguestfs appliance and block devices are reused between tests. So
373 don't try testing "guestfs_kill_subprocess" in guestfs(3) :-x
374
375 Each test starts with an initial scenario, selected using one of the
376 "Init*" expressions, described in generator/types.ml. These initialize
377 the disks mentioned above in a particular way as documented in
378 types.ml. You should not assume anything about the previous contents
379 of other disks that are not initialized.
380
381 You can add a prerequisite clause to any individual test. This is a
382 run-time check, which, if it fails, causes the test to be skipped.
383 Useful if testing a command which might not work on all variations of
384 libguestfs builds. A test that has prerequisite of "Always" means to
385 run unconditionally.
386
387 In addition, packagers can skip individual tests by setting environment
388 variables before running "make check".
389
390 SKIP_TEST_<CMD>_<NUM>=1
391
392 eg: "SKIP_TEST_COMMAND_3=1" skips test #3 of "guestfs_command" in
393 guestfs(3).
394
395 or:
396
397 SKIP_TEST_<CMD>=1
398
399 eg: "SKIP_TEST_ZEROFREE=1" skips all "guestfs_zerofree" in guestfs(3)
400 tests.
401
402 Packagers can run only certain tests by setting for example:
403
404 TEST_ONLY="vfs_type zerofree"
405
406 See tests/c-api/tests.c for more details of how these environment
407 variables work.
408
409 Debugging new APIs
410
411 Test new actions work before submitting them.
412
413 You can use guestfish to try out new commands.
414
415 Debugging the daemon is a problem because it runs inside a minimal
416 environment. However you can fprintf messages in the daemon to stderr,
417 and they will show up if you use "guestfish -v".
418
419 ADDING A NEW LANGUAGE BINDING
420 All language bindings must be generated by the generator (see the
421 generator subdirectory).
422
423 There is no documentation for this yet. We suggest you look at an
424 existing binding, eg. generator/ocaml.ml or generator/perl.ml.
425
426 Adding tests for language bindings
427
428 Language bindings should come with tests. Previously testing of
429 language bindings was rather ad-hoc, but we have been trying to
430 formalize the set of tests that every language binding should use.
431
432 Currently only the OCaml and Perl bindings actually implement the full
433 set of tests, and the OCaml bindings are canonical, so you should
434 emulate what the OCaml tests do.
435
436 This is the numbering scheme used by the tests:
437
438 - 000+ basic tests:
439
440 010 load the library
441 020 create
442 030 create-flags
443 040 create multiple handles
444 050 test setting and getting config properties
445 060 explicit close
446 065 implicit close (in GC'd languages)
447 070 optargs
448 080 version
449 090 retvalues
450
451 - 100 launch, create partitions and LVs and filesystems
452
453 - 400+ events:
454
455 410 close event
456 420 log messages
457 430 progress messages
458
459 - 800+ regression tests (specific to the language)
460
461 - 900+ any other custom tests for the language
462
463 To save time when running the tests, only 100, 430, 800+, 900+ should
464 launch the handle.
465
466 FORMATTING CODE
467 Our C source code generally adheres to some basic code-formatting
468 conventions. The existing code base is not totally consistent on this
469 front, but we do prefer that contributed code be formatted similarly.
470 In short, use spaces-not-TABs for indentation, use 2 spaces for each
471 indentation level, and other than that, follow the K&R style.
472
473 If you use Emacs, add the following to one of your start-up files
474 (e.g., ~/.emacs), to help ensure that you get indentation right:
475
476 ;;; In libguestfs, indent with spaces everywhere (not TABs).
477 ;;; Exceptions: Makefile and ChangeLog modes.
478 (add-hook 'find-file-hook
479 '(lambda () (if (and buffer-file-name
480 (string-match "/libguestfs\\>"
481 (buffer-file-name))
482 (not (string-equal mode-name "Change Log"))
483 (not (string-equal mode-name "Makefile")))
484 (setq indent-tabs-mode nil))))
485
486 ;;; When editing C sources in libguestfs, use this style.
487 (defun libguestfs-c-mode ()
488 "C mode with adjusted defaults for use with libguestfs."
489 (interactive)
490 (c-set-style "K&R")
491 (setq c-indent-level 2)
492 (setq c-basic-offset 2))
493 (add-hook 'c-mode-hook
494 '(lambda () (if (string-match "/libguestfs\\>"
495 (buffer-file-name))
496 (libguestfs-c-mode))))
497
498 TESTING YOUR CHANGES
499 Turn warnings into errors when developing to make warnings hard to
500 ignore:
501
502 ./configure --enable-werror
503
504 Useful targets are:
505
506 "make check"
507 Runs the regular test suite.
508
509 This is implemented using the regular automake "TESTS" target. See
510 the automake documentation for details.
511
512 "make check-valgrind"
513 Runs a subset of the test suite under valgrind.
514
515 See "VALGRIND" below.
516
517 "make check-valgrind-local-guests"
518 Runs a subset of the test suite under valgrind using locally
519 installed libvirt guests (read-only).
520
521 "make check-direct"
522 Runs all tests using default appliance back-end. This only has any
523 effect if a non-default backend was selected using "./configure
524 --with-default-backend=..."
525
526 "make check-valgrind-direct"
527 Run a subset of the test suite under valgrind using the default
528 appliance back-end.
529
530 "make check-with-upstream-qemu"
531 Runs all tests using a local qemu binary. It looks for the qemu
532 binary in QEMUDIR (defaults to $HOME/d/qemu), but you can set this
533 to another directory on the command line, eg:
534
535 make check-with-upstream-qemu QEMUDIR=/usr/src/qemu
536
537 "make check-with-upstream-libvirt"
538 Runs all tests using a local libvirt. This only has any effect if
539 the libvirt backend was selected using "./configure
540 --with-default-backend=libvirt"
541
542 It looks for libvirt in LIBVIRTDIR (defaults to $HOME/d/libvirt),
543 but you can set this to another directory on the command line, eg:
544
545 make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt
546
547 "make check-slow"
548 Runs some slow/long-running tests which are not run by default.
549
550 To mark a test as slow/long-running:
551
552 • Add it to the list of "TESTS" in the Makefile.am, just like a
553 normal test.
554
555 • Modify the test so it checks if the "SLOW=1" environment
556 variable is set, and if not set it skips (ie. returns with exit
557 code 77). If using $TEST_FUNCTIONS, you can call the function
558 "slow_test" for this.
559
560 • Add a variable "SLOW_TESTS" to the Makefile.am listing the slow
561 tests.
562
563 • Add a rule to the Makefile.am:
564
565 check-slow:
566 $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1
567
568 "sudo make check-root"
569 Runs some tests which require root privileges. These are supposed
570 to be safe, but take care. You have to run this as root (eg. using
571 sudo(8) explicitly).
572
573 To mark a test as requiring root:
574
575 • Add it to the list of "TESTS" in the Makefile.am, just like a
576 normal test.
577
578 • Modify the test so it checks if euid == 0, and if not set it
579 skips (ie. returns with exit code 77). If using
580 $TEST_FUNCTIONS, you can call the function "root_test" for
581 this.
582
583 • Add a variable "ROOT_TESTS" to the Makefile.am listing the root
584 tests.
585
586 • Add a rule to the Makefile.am:
587
588 check-root:
589 $(MAKE) check TESTS="$(ROOT_TESTS)"
590
591 "make check-all"
592 Equivalent to running all "make check*" rules except "check-root".
593
594 "make check-release"
595 Runs a subset of "make check*" rules that are required to pass
596 before a tarball can be released. Currently this is:
597
598 • check
599
600 • check-valgrind
601
602 • check-direct
603
604 • check-valgrind-direct
605
606 • check-slow
607
608 "make installcheck"
609 Run "make check" on the installed copy of libguestfs.
610
611 The version of installed libguestfs being tested, and the version
612 of the libguestfs source tree must be the same.
613
614 Do:
615
616 ./configure
617 make clean ||:
618 make
619 make installcheck
620
621 VALGRIND
622 When you do "make check-valgrind", it searches for any Makefile.am in
623 the tree that has a "check-valgrind:" target and runs it.
624
625 Writing the Makefile.am and tests correctly to use valgrind and working
626 with automake parallel tests is subtle.
627
628 If your tests are run via a shell script wrapper, then in the wrapper
629 use:
630
631 $VG virt-foo
632
633 and in the Makefile.am use:
634
635 check-valgrind:
636 make VG="@VG@" check
637
638 However, if your binaries run directly from the "TESTS" rule, you have
639 to modify the Makefile.am like this:
640
641 LOG_COMPILER = $(VG)
642
643 check-valgrind:
644 make VG="@VG@" check
645
646 In either case, check that the right program is being tested by
647 examining the tmp/valgrind* log files carefully.
648
649 SUBMITTING PATCHES
650 Submit patches to the mailing list:
651 http://www.redhat.com/mailman/listinfo/libguestfs and CC to
652 rjones@redhat.com.
653
654 You do not need to subscribe to the mailing list if you don’t want to.
655 There may be a short delay while your message is moderated.
656
657 INTERNATIONALIZATION (I18N) SUPPORT
658 We support i18n (gettext anyhow) in the library.
659
660 However many messages come from the daemon, and we don’t translate
661 those at the moment. One reason is that the appliance generally has
662 all locale files removed from it, because they take up a lot of space.
663 So we'd have to readd some of those, as well as copying our PO files
664 into the appliance.
665
666 Debugging messages are never translated, since they are intended for
667 the programmers.
668
670 HOW OCAML PROGRAMS ARE COMPILED AND LINKED
671 Mostly this section is "how we make automake & ocamlopt work together"
672 since OCaml programs themselves are easy to compile.
673
674 Automake has no native support for OCaml programs, ocamlc nor ocamlopt.
675 What we do instead is to treat OCaml programs as C programs which
676 happen to contain these "other objects" ("DEPENDENCIES" in automake-
677 speak) that happen to be the OCaml objects. This works because OCaml
678 programs usually have C files for native bindings etc.
679
680 So a typical program is described as just its C sources:
681
682 virt_customize_SOURCES = ... crypt-c.c perl_edit-c.c
683
684 For programs that have no explicit C sources, we create an empty
685 dummy.c file, and list that instead:
686
687 virt_resize_SOURCES = dummy.c
688
689 The OCaml objects which contain most of the code are listed as automake
690 dependencies (other dependencies may also be listed):
691
692 virt_customize_DEPENDENCIES = ... customize_main.cmx
693
694 The only other special thing we need to do is to provide a custom link
695 command. This is needed because automake won't assemble the ocamlopt
696 command, the list of objects and the "-cclib" libraries in the correct
697 order otherwise.
698
699 virt_customize_LINK = \
700 $(top_builddir)/ocaml-link.sh -cclib '-lutils' -- ...
701
702 The actual rules, which you can examine in customize/Makefile.am, are a
703 little bit more complicated than this because they have to handle:
704
705 • Compiling for byte code or native code.
706
707 • The pattern rules needed to compile the OCaml sources to objects.
708
709 These are now kept in subdir-rules.mk at the top level, which is
710 included in every subdirectory Makefile.am.
711
712 • Adding OCaml sources files to "EXTRA_DIST".
713
714 Automake isn't aware of the complete list of sources for a binary,
715 so it will not add them all automatically.
716
718 MAINTAINER MAKEFILE TARGETS
719 These "make" targets probably won’t work and aren't useful unless you
720 are a libguestfs maintainer.
721
722 make maintainer-commit
723
724 This commits everything in the working directory with the commit
725 message "Version $(VERSION).". You must update configure.ac, clean and
726 rebuild first.
727
728 make maintainer-tag
729
730 This tags the current HEAD commit with the tag "v$(VERSION)" and one of
731 the messages:
732
733 Version $(VERSION) stable
734
735 Version $(VERSION) development
736
737 (See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for the difference
738 between a stable and development release.)
739
740 make maintainer-check-authors
741
742 Check that all authors (found in git commit messages) are included in
743 the generator/authors.ml file.
744
745 make maintainer-check-extra-dist
746
747 This rule must be run after "make dist" (so there is a tarball in the
748 working directory). It compares the contents of the tarball with the
749 contents of git to ensure that no files have been missed from
750 Makefile.am "EXTRA_DIST" rules.
751
752 make maintainer-upload-website
753
754 This is used by the software used to automate libguestfs releases to
755 copy the libguestfs website to another git repository before it is
756 uploaded to the web server.
757
758 MAKING A STABLE RELEASE
759 When we make a stable release, there are several steps documented here.
760 See "LIBGUESTFS VERSION NUMBERS" in guestfs(3) for general information
761 about the stable branch policy.
762
763 • Check "make && make check" works on at least:
764
765 Fedora (x86-64)
766 Debian (x86-64)
767 Ubuntu (x86-64)
768 Fedora (aarch64)
769 Fedora (ppc64)
770 Fedora (ppc64le)
771 • Check "./configure --without-libvirt" works.
772
773 • Finalize guestfs-release-notes.pod
774
775 • Create new stable and development directories under
776 http://libguestfs.org/download.
777
778 • Edit website/index.html.in.
779
780 • Set the version (in configure.ac) to the new stable version, ie.
781 1.XX.0, and commit it:
782
783 ./localconfigure
784 make distclean -k
785 ./localconfigure
786 make && make dist
787 make maintainer-commit
788 make maintainer-tag
789
790 • Create the stable branch in git:
791
792 git branch stable-1.XX
793 git push origin stable-1.XX
794
795 • Do a full release of the stable branch.
796
797 • Set the version to the next development version and commit that.
798 Optionally do a full release of the development branch.
799
801 This section documents internal functions inside libguestfs and various
802 utilities. It is intended for libguestfs developers only.
803
804 This section is autogenerated from "/**" comments in source files,
805 which are marked up in POD format.
806
807 These functions are not publicly exported, and may change or be removed
808 at any time.
809
810 Subdirectory lib
811 File lib/actions-support.c
812
813 Helper functions for the actions code in lib/actions-*.c.
814
815 File lib/appliance-cpu.c
816
817 The appliance choice of CPU model.
818
819 Function "lib/appliance-cpu.c:guestfs_int_get_cpu_model"
820
821 const char *
822 guestfs_int_get_cpu_model (int kvm)
823
824 Return the right CPU model to use as the qemu "-cpu" parameter or its
825 equivalent in libvirt. This returns:
826
827 "host"
828 The literal string "host" means use "-cpu host".
829
830 "max"
831 The literal string "max" means use "-cpu max" (the best possible).
832 This requires awkward translation for libvirt.
833
834 some string
835 Some string such as "cortex-a57" means use "-cpu cortex-a57".
836
837 "NULL"
838 "NULL" means no "-cpu" option at all. Note returning "NULL" does
839 not indicate an error.
840
841 This is made unnecessarily hard and fragile because of two stupid
842 choices in QEMU:
843
844 • The default for "qemu-system-aarch64 -M virt" is to emulate a
845 "cortex-a15" (WTF?).
846
847 • We don't know for sure if KVM will work, but "-cpu host" is broken
848 with TCG, so we almost always pass a broken "-cpu" flag if KVM is
849 semi-broken in any way.
850
851 File lib/appliance-kcmdline.c
852
853 The appliance kernel command line.
854
855 Definition "lib/appliance-kcmdline.c:VALID_TERM"
856
857 #define VALID_TERM
858
859 Check that the $TERM environment variable is reasonable before we pass
860 it through to the appliance.
861
862 Function "lib/appliance-kcmdline.c:get_root_uuid_with_file"
863
864 static char *
865 get_root_uuid_with_file (guestfs_h *g, const char *appliance)
866
867 Given a disk image containing an extX filesystem, return the UUID.
868
869 Function "lib/appliance-kcmdline.c:run_qemu_img_dd"
870
871 static int
872 run_qemu_img_dd (guestfs_h *g, const char *in_file, char *out_file)
873
874 Read the first 256k bytes of the in_file with qemu-img(1) command and
875 write them into the out_file. That may be useful to get UUID of the
876 QCOW2 disk image with "get_root_uuid_with_file".
877
878 The function returns zero if successful, otherwise -1.
879
880 Function "lib/appliance-kcmdline.c:get_root_uuid"
881
882 static char *
883 get_root_uuid (guestfs_h *g, const char *appliance)
884
885 Get the UUID from the appliance disk image.
886
887 Function "lib/appliance-kcmdline.c:guestfs_int_appliance_command_line"
888
889 char *
890 guestfs_int_appliance_command_line (guestfs_h *g,
891 const char *appliance,
892 int flags)
893
894 Construct the Linux command line passed to the appliance. This is used
895 by the "direct" and "libvirt" backends, and is simply located in this
896 file because it's a convenient place for this common code.
897
898 The "appliance" parameter is the filename of the appliance (could be
899 NULL) from which we obtain the root UUID.
900
901 The "flags" parameter can contain the following flags logically or'd
902 together (or 0):
903
904 "APPLIANCE_COMMAND_LINE_IS_TCG"
905 If we are launching a qemu TCG guest (ie. KVM is known to be
906 disabled or unavailable). If you don't know, don't pass this flag.
907
908 Note that this function returns a newly allocated buffer which must be
909 freed by the caller.
910
911 File lib/appliance-uefi.c
912
913 Find the UEFI firmware needed to boot the appliance.
914
915 See also lib/uefi.c (autogenerated file) containing the firmware file
916 locations.
917
918 Function "lib/appliance-uefi.c:guestfs_int_get_uefi"
919
920 int
921 guestfs_int_get_uefi (guestfs_h *g, char *const *firmwares,
922 const char **firmware, char **code, char **vars,
923 int *flags)
924
925 Return the location of firmware needed to boot the appliance. This is
926 aarch64 only currently, since that's the only architecture where UEFI
927 is mandatory (and that only for RHEL).
928
929 "firmwares" is an optional list of allowed values for the firmware
930 autoselection of libvirt. It is "NULL" to indicate it is not supported.
931 *firmware is set to one of the strings in "firmwares" in case one can
932 be used.
933
934 *code is initialized with the path to the read-only UEFI code file.
935 *vars is initialized with the path to a copy of the UEFI vars file
936 (which is cleaned up automatically on exit).
937
938 In case a UEFI firmware is available, either *firmware is set to a
939 non-"NULL" value, or *code and *vars are.
940
941 *code and *vars should be freed by the caller, and *firmware must not.
942
943 If the function returns -1 then there was a real error which should
944 cause appliance building to fail (no UEFI firmware is not an error).
945
946 See also virt-v2v.git/v2v/utils.ml:find_uefi_firmware
947
948 File lib/appliance.c
949
950 This file deals with building the libguestfs appliance.
951
952 Function "lib/appliance.c:guestfs_int_build_appliance"
953
954 int
955 guestfs_int_build_appliance (guestfs_h *g,
956 char **kernel_rtn,
957 char **initrd_rtn,
958 char **appliance_rtn)
959
960 Locate or build the appliance.
961
962 This function locates or builds the appliance as necessary, handling
963 the supermin appliance, caching of supermin-built appliances, or using
964 either a fixed or old-style appliance.
965
966 The return value is 0 = good, -1 = error. Returned in
967 "appliance.kernel" will be the name of the kernel to use,
968 "appliance.initrd" the name of the initrd, "appliance.image" the name
969 of the ext2 root filesystem. "appliance.image" can be "NULL", meaning
970 that we are using an old-style (non-ext2) appliance. All three strings
971 must be freed by the caller. However the referenced files themselves
972 must not be deleted.
973
974 The process is as follows:
975
976 1. Look in "path" which contains a supermin appliance skeleton. If no
977 element has this, skip straight to step 3.
978
979 2. Call "supermin --build" to build the full appliance (if it needs to
980 be rebuilt). If this is successful, return the full appliance.
981
982 3. Check "path", looking for a fixed appliance. If one is found,
983 return it.
984
985 4. Check "path", looking for an old-style appliance. If one is found,
986 return it.
987
988 The supermin appliance cache directory lives in $TMPDIR/.guestfs-$UID/
989 and consists of up to four files:
990
991 $TMPDIR/.guestfs-$UID/lock - the supermin lock file
992 $TMPDIR/.guestfs-$UID/appliance.d/kernel - the kernel
993 $TMPDIR/.guestfs-$UID/appliance.d/initrd - the supermin initrd
994 $TMPDIR/.guestfs-$UID/appliance.d/root - the appliance
995
996 Multiple instances of libguestfs with the same UID may be racing to
997 create an appliance. However (since supermin ≥ 5) supermin provides a
998 --lock flag and atomic update of the appliance.d subdirectory.
999
1000 Function "lib/appliance.c:locate_or_build_appliance"
1001
1002 static int
1003 locate_or_build_appliance (guestfs_h *g,
1004 struct appliance_files *appliance,
1005 const char *path)
1006
1007 Check "path", looking for one of appliances: supermin appliance, fixed
1008 appliance or old-style appliance. If one of the fixed appliances is
1009 found, return it. If the supermin appliance skeleton is found, build
1010 and return appliance.
1011
1012 Return values:
1013
1014 1 = appliance is found, returns C<appliance>,
1015 0 = appliance not found,
1016 -1 = error which aborts the launch process.
1017
1018 Function "lib/appliance.c:search_appliance"
1019
1020 static int
1021 search_appliance (guestfs_h *g, struct appliance_files *appliance)
1022
1023 Search elements of "g->path", returning the first "appliance" element
1024 which matches the predicate function "locate_or_build_appliance".
1025
1026 Return values:
1027
1028 1 = a path element matched, returns C<appliance>,
1029 0 = no path element matched,
1030 -1 = error which aborts the launch process.
1031
1032 Function "lib/appliance.c:build_supermin_appliance"
1033
1034 static int
1035 build_supermin_appliance (guestfs_h *g,
1036 const char *supermin_path,
1037 struct appliance_files *appliance)
1038
1039 Build supermin appliance from "supermin_path" to $TMPDIR/.guestfs-$UID.
1040
1041 Returns: 0 = built or -1 = error (aborts launch).
1042
1043 Function "lib/appliance.c:run_supermin_build"
1044
1045 static int
1046 run_supermin_build (guestfs_h *g,
1047 const char *lockfile,
1048 const char *appliancedir,
1049 const char *supermin_path)
1050
1051 Run "supermin --build" and tell it to generate the appliance.
1052
1053 Function "lib/appliance.c:dir_contains_file"
1054
1055 static int
1056 dir_contains_file (guestfs_h *g, const char *dir, const char *file)
1057
1058 Returns true iff "file" is contained in "dir".
1059
1060 Function "lib/appliance.c:dir_contains_files"
1061
1062 static int
1063 dir_contains_files (guestfs_h *g, const char *dir, ...)
1064
1065 Returns true iff every listed file is contained in "dir".
1066
1067 File lib/command.c
1068
1069 A wrapper for running external commands, loosely based on libvirt's
1070 "virCommand" interface.
1071
1072 In outline to use this interface you must:
1073
1074 1. Create a new command handle:
1075
1076 struct command *cmd;
1077 cmd = guestfs_int_new_command (g);
1078
1079 2. Either add arguments:
1080
1081 guestfs_int_cmd_add_arg (cmd, "qemu-img");
1082 guestfs_int_cmd_add_arg (cmd, "info");
1083 guestfs_int_cmd_add_arg (cmd, filename);
1084
1085 (NB: You don't need to add a "NULL" argument at the end.)
1086
1087 3. Or construct a command using a mix of quoted and unquoted strings.
1088 (This is useful for system(3)/popen("r")-style shell commands, with
1089 the added safety of allowing args to be quoted properly).
1090
1091 guestfs_int_cmd_add_string_unquoted (cmd, "qemu-img info ");
1092 guestfs_int_cmd_add_string_quoted (cmd, filename);
1093
1094 4. Set various flags, such as whether you want to capture errors in
1095 the regular libguestfs error log.
1096
1097 5. Run the command. This is what does the fork(2) call, optionally
1098 loops over the output, and then does a waitpid(3) and returns the
1099 exit status of the command.
1100
1101 r = guestfs_int_cmd_run (cmd);
1102 if (r == -1)
1103 // error
1104 // else test r using the WIF* functions
1105
1106 6. Close the handle:
1107
1108 guestfs_int_cmd_close (cmd);
1109
1110 (or use "CLEANUP_CMD_CLOSE").
1111
1112 Function "lib/command.c:guestfs_int_new_command"
1113
1114 struct command *
1115 guestfs_int_new_command (guestfs_h *g)
1116
1117 Create a new command handle.
1118
1119 Function "lib/command.c:guestfs_int_cmd_add_arg"
1120
1121 void
1122 guestfs_int_cmd_add_arg (struct command *cmd, const char *arg)
1123
1124 Add single arg (for "execv"-style command execution).
1125
1126 Function "lib/command.c:guestfs_int_cmd_add_arg_format"
1127
1128 void
1129 guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...)
1130
1131 Add single arg (for "execv"-style command execution) using a
1132 printf(3)-style format string.
1133
1134 Function "lib/command.c:guestfs_int_cmd_add_string_unquoted"
1135
1136 void
1137 guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str)
1138
1139 Add a string (for system(3)-style command execution).
1140
1141 This variant adds the strings without quoting them, which is dangerous
1142 if the string contains untrusted content.
1143
1144 Function "lib/command.c:guestfs_int_cmd_add_string_quoted"
1145
1146 void
1147 guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str)
1148
1149 Add a string (for system(3)-style command execution).
1150
1151 The string is enclosed in double quotes, with any special characters
1152 within the string which need escaping done. This is used to add a
1153 single argument to a system(3)-style command string.
1154
1155 Function "lib/command.c:guestfs_int_cmd_set_stdout_callback"
1156
1157 void
1158 guestfs_int_cmd_set_stdout_callback (struct command *cmd,
1159 cmd_stdout_callback stdout_callback,
1160 void *stdout_data, unsigned flags)
1161
1162 Set a callback which will capture stdout.
1163
1164 If flags contains "CMD_STDOUT_FLAG_LINE_BUFFER" (the default), then the
1165 callback is called line by line on the output. If there is a trailing
1166 "\n" then it is automatically removed before the callback is called.
1167 The line buffer is "\0"-terminated.
1168
1169 If flags contains "CMD_STDOUT_FLAG_UNBUFFERED", then buffers are passed
1170 to the callback as it is received from the command. Note in this case
1171 the buffer is not "\0"-terminated, so you need to may attention to the
1172 length field in the callback.
1173
1174 If flags contains "CMD_STDOUT_FLAG_WHOLE_BUFFER", then the callback is
1175 called exactly once, with the entire buffer. Note in this case the
1176 buffer is not "\0"-terminated, so you need to may attention to the
1177 length field in the callback.
1178
1179 Function "lib/command.c:guestfs_int_cmd_set_stderr_to_stdout"
1180
1181 void
1182 guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd)
1183
1184 Equivalent to adding "2>&1" to the end of the command. This is
1185 incompatible with the "capture_errors" flag, because it doesn't make
1186 sense to combine them.
1187
1188 Function "lib/command.c:guestfs_int_cmd_clear_capture_errors"
1189
1190 void
1191 guestfs_int_cmd_clear_capture_errors (struct command *cmd)
1192
1193 Clear the "capture_errors" flag. This means that any errors will go to
1194 stderr, instead of being captured in the event log, and that is usually
1195 undesirable.
1196
1197 Function "lib/command.c:guestfs_int_cmd_clear_close_files"
1198
1199 void
1200 guestfs_int_cmd_clear_close_files (struct command *cmd)
1201
1202 Don't close file descriptors after the fork.
1203
1204 XXX Should allow single fds to be sent to child process.
1205
1206 Function "lib/command.c:guestfs_int_cmd_set_child_callback"
1207
1208 void
1209 guestfs_int_cmd_set_child_callback (struct command *cmd,
1210 cmd_child_callback child_callback,
1211 void *data)
1212
1213 Set a function to be executed in the child, right before the execution.
1214 Can be used to setup the child, for example changing its current
1215 directory.
1216
1217 Function "lib/command.c:guestfs_int_cmd_set_child_rlimit"
1218
1219 void
1220 guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit)
1221
1222 Set up child rlimits, in case the process we are running could consume
1223 lots of space or time.
1224
1225 Function "lib/command.c:finish_command"
1226
1227 static void
1228 finish_command (struct command *cmd)
1229
1230 Finish off the command by either "NULL"-terminating the argv array or
1231 adding a terminating "\0" to the string, or die with an internal error
1232 if no command has been added.
1233
1234 Function "lib/command.c:loop"
1235
1236 static int
1237 loop (struct command *cmd)
1238
1239 The loop which reads errors and output and directs it either to the log
1240 or to the stdout callback as appropriate.
1241
1242 Function "lib/command.c:guestfs_int_cmd_run"
1243
1244 int
1245 guestfs_int_cmd_run (struct command *cmd)
1246
1247 Fork, run the command, loop over the output, and waitpid.
1248
1249 Returns the exit status. Test it using "WIF*" macros.
1250
1251 On error: Calls "error" and returns -1.
1252
1253 Function "lib/command.c:guestfs_int_cmd_pipe_run"
1254
1255 int
1256 guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode)
1257
1258 Fork and run the command, but don't wait. Roughly equivalent to
1259 "popen (..., "r"|"w")".
1260
1261 Returns the file descriptor of the pipe, connected to stdout ("r") or
1262 stdin ("w") of the child process.
1263
1264 After reading/writing to this pipe, call "guestfs_int_cmd_pipe_wait" to
1265 wait for the status of the child.
1266
1267 Errors from the subcommand cannot be captured to the error log using
1268 this interface. Instead the caller should call
1269 "guestfs_int_cmd_get_pipe_errors" (after "guestfs_int_cmd_pipe_wait"
1270 returns an error).
1271
1272 Function "lib/command.c:guestfs_int_cmd_pipe_wait"
1273
1274 int
1275 guestfs_int_cmd_pipe_wait (struct command *cmd)
1276
1277 Wait for a subprocess created by "guestfs_int_cmd_pipe_run" to finish.
1278 On error (eg. failed syscall) this returns -1 and sets the error. If
1279 the subcommand fails, then use "WIF*" macros to check this, and call
1280 "guestfs_int_cmd_get_pipe_errors" to read the error messages printed by
1281 the child.
1282
1283 Function "lib/command.c:guestfs_int_cmd_get_pipe_errors"
1284
1285 char *
1286 guestfs_int_cmd_get_pipe_errors (struct command *cmd)
1287
1288 Read the error messages printed by the child. The caller must free the
1289 returned buffer after use.
1290
1291 Function "lib/command.c:guestfs_int_cmd_close"
1292
1293 void
1294 guestfs_int_cmd_close (struct command *cmd)
1295
1296 Close the "cmd" object and free all resources.
1297
1298 Function "lib/command.c:process_line_buffer"
1299
1300 static void
1301 process_line_buffer (struct command *cmd, int closed)
1302
1303 Deal with buffering stdout for the callback.
1304
1305 File lib/conn-socket.c
1306
1307 This file handles connections to the child process where this is done
1308 over regular POSIX sockets.
1309
1310 Function "lib/conn-socket.c:handle_log_message"
1311
1312 static int
1313 handle_log_message (guestfs_h *g,
1314 struct connection_socket *conn)
1315
1316 This is called if "conn->console_sock" becomes ready to read while we
1317 are doing one of the connection operations above. It reads and deals
1318 with the log message.
1319
1320 Returns:
1321
1322 1 log message(s) were handled successfully
1323
1324 0 connection to appliance closed
1325
1326 -1 error
1327
1328 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_listening"
1329
1330 struct connection *
1331 guestfs_int_new_conn_socket_listening (guestfs_h *g,
1332 int daemon_accept_sock,
1333 int console_sock)
1334
1335 Create a new socket connection, listening.
1336
1337 Note that it's OK for "console_sock" to be passed as -1, meaning
1338 there's no console available for this appliance.
1339
1340 After calling this, "daemon_accept_sock" is owned by the connection,
1341 and will be closed properly either in "accept_connection" or
1342 "free_connection".
1343
1344 Function "lib/conn-socket.c:guestfs_int_new_conn_socket_connected"
1345
1346 struct connection *
1347 guestfs_int_new_conn_socket_connected (guestfs_h *g,
1348 int daemon_sock,
1349 int console_sock)
1350
1351 Create a new socket connection, connected.
1352
1353 As above, but the caller passes us a connected "daemon_sock" and
1354 promises not to call "accept_connection".
1355
1356 File lib/create.c
1357
1358 APIs for creating empty disks.
1359
1360 Mostly this consists of wrappers around the qemu-img(1) program.
1361
1362 Definition "lib/create.c:VALID_FORMAT"
1363
1364 #define VALID_FORMAT
1365
1366 Check for valid backing format. Allow any "^[[:alnum]]+$" (in C
1367 locale), but limit the length to something reasonable.
1368
1369 File lib/drives.c
1370
1371 Drives added are stored in an array in the handle. Code here manages
1372 that array and the individual "struct drive" data.
1373
1374 Function "lib/drives.c:create_overlay"
1375
1376 static int
1377 create_overlay (guestfs_h *g, struct drive *drv)
1378
1379 For readonly drives, create an overlay to protect the original drive
1380 content. Note we never need to clean up these overlays since they are
1381 created in the temporary directory and deleted when the handle is
1382 closed.
1383
1384 Function "lib/drives.c:create_drive_file"
1385
1386 static struct drive *
1387 create_drive_file (guestfs_h *g,
1388 const struct drive_create_data *data)
1389
1390 Create and free the "struct drive".
1391
1392 Function "lib/drives.c:create_drive_dev_null"
1393
1394 static struct drive *
1395 create_drive_dev_null (guestfs_h *g,
1396 struct drive_create_data *data)
1397
1398 Create the special /dev/null drive.
1399
1400 Traditionally you have been able to use /dev/null as a filename, as
1401 many times as you like. Ancient KVM (RHEL 5) cannot handle adding
1402 /dev/null readonly. qemu 1.2 + virtio-scsi segfaults when you use any
1403 zero-sized file including /dev/null.
1404
1405 Because of these problems, we replace /dev/null with a non-zero sized
1406 temporary file. This shouldn't make any difference since users are not
1407 supposed to try and access a null drive.
1408
1409 Function "lib/drives.c:drive_to_string"
1410
1411 static char *
1412 drive_to_string (guestfs_h *g, const struct drive *drv)
1413
1414 Convert a "struct drive" to a string for debugging. The caller must
1415 free this string.
1416
1417 Function "lib/drives.c:add_drive_to_handle_at"
1418
1419 static void
1420 add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index)
1421
1422 Add "struct drive" to the "g->drives" vector at the given index
1423 "drv_index". If the array isn't large enough it is reallocated. The
1424 index must not contain a drive already.
1425
1426 Function "lib/drives.c:add_drive_to_handle"
1427
1428 static void
1429 add_drive_to_handle (guestfs_h *g, struct drive *d)
1430
1431 Add struct drive to the end of the "g->drives" vector in the handle.
1432
1433 Function "lib/drives.c:guestfs_int_add_dummy_appliance_drive"
1434
1435 void
1436 guestfs_int_add_dummy_appliance_drive (guestfs_h *g)
1437
1438 Called during launch to add a dummy slot to "g->drives".
1439
1440 Function "lib/drives.c:guestfs_int_free_drives"
1441
1442 void
1443 guestfs_int_free_drives (guestfs_h *g)
1444
1445 Free up all the drives in the handle.
1446
1447 Definition "lib/drives.c:VALID_FORMAT"
1448
1449 #define VALID_FORMAT
1450
1451 Check string parameter matches regular expression "^[-_[:alnum:]]+$"
1452 (in C locale).
1453
1454 Definition "lib/drives.c:VALID_DISK_LABEL"
1455
1456 #define VALID_DISK_LABEL
1457
1458 Check the disk label is reasonable. It can't contain certain
1459 characters, eg. '/', ','. However be stricter here and ensure it's
1460 just alphabetic and ≤ 20 characters in length.
1461
1462 Definition "lib/drives.c:VALID_HOSTNAME"
1463
1464 #define VALID_HOSTNAME
1465
1466 Check the server hostname is reasonable.
1467
1468 Function "lib/drives.c:valid_port"
1469
1470 static int
1471 valid_port (int port)
1472
1473 Check the port number is reasonable.
1474
1475 Function "lib/drives.c:valid_blocksize"
1476
1477 static int
1478 valid_blocksize (int blocksize)
1479
1480 Check the block size is reasonable. It can't be other then 512 or
1481 4096.
1482
1483 Function "lib/drives.c:guestfs_int_checkpoint_drives"
1484
1485 size_t
1486 guestfs_int_checkpoint_drives (guestfs_h *g)
1487
1488 Checkpoint and roll back drives, so that groups of drives can be added
1489 atomically. Only used by "guestfs_add_domain" in guestfs(3).
1490
1491 Function "lib/drives.c:guestfs_impl_debug_drives"
1492
1493 char **
1494 guestfs_impl_debug_drives (guestfs_h *g)
1495
1496 Internal function to return the list of drives.
1497
1498 File lib/errors.c
1499
1500 This file handles errors, and also debug, trace and warning messages.
1501
1502 Errors in libguestfs API calls are handled by setting an error message
1503 and optional errno in the handle. The caller has the choice of testing
1504 API calls to find out if they failed and then querying the last error
1505 from the handle, and/or getting a callback.
1506
1507 From the point of view of the library source, generally you should use
1508 the "error" or "perrorf" macros along error paths, eg:
1509
1510 if (something_bad) {
1511 error (g, "something bad happened");
1512 return -1;
1513 }
1514
1515 Make sure to call the "error" or "perrorf" macro exactly once along
1516 each error path, since the handle can only store a single error and the
1517 previous error will be overwritten.
1518
1519 Function "lib/errors.c:guestfs_int_warning"
1520
1521 void
1522 guestfs_int_warning (guestfs_h *g, const char *fs, ...)
1523
1524 Print a warning.
1525
1526 Code should not call this function directly. Use the
1527 "warning (g, fs, ...)" macro.
1528
1529 Warnings are printed unconditionally. We try to make these rare:
1530 Generally speaking, a warning should either be an error, or if it's not
1531 important for end users then it should be a debug message.
1532
1533 Function "lib/errors.c:guestfs_int_debug"
1534
1535 void
1536 guestfs_int_debug (guestfs_h *g, const char *fs, ...)
1537
1538 Print a debug message.
1539
1540 Code should not call this function directly. To add debug messages in
1541 the library, use the "debug (g, fs, ...)" macro. The macro checks if
1542 "g->verbose" is false and avoids the function call, meaning the macro
1543 is more efficient.
1544
1545 Function "lib/errors.c:guestfs_int_trace"
1546
1547 void
1548 guestfs_int_trace (guestfs_h *g, const char *fs, ...)
1549
1550 Print a trace message.
1551
1552 Do not call this function. All calls are generated automatically.
1553
1554 Function "lib/errors.c:guestfs_int_error_errno"
1555
1556 void
1557 guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...)
1558
1559 Set the last error and errno in the handle, and optionally raise the
1560 error callback if one is defined.
1561
1562 If you don't need to set errno, use the "error (g, fs, ...)" macro
1563 instead of calling this directly. If you need to set errno then there
1564 is no macro wrapper, so calling this function directly is fine.
1565
1566 Function "lib/errors.c:guestfs_int_perrorf"
1567
1568 void
1569 guestfs_int_perrorf (guestfs_h *g, const char *fs, ...)
1570
1571 Similar to perror(3), but it sets the last error in the handle, raises
1572 the error callback if one is defined, and supports format strings.
1573
1574 You should probably use the "perrorf (g, fs, ...)" macro instead of
1575 calling this directly.
1576
1577 Function "lib/errors.c:guestfs_int_launch_failed_error"
1578
1579 void
1580 guestfs_int_launch_failed_error (guestfs_h *g)
1581
1582 Raise a launch failed error in a standard format.
1583
1584 Since this is the most common error seen by people who have
1585 installation problems, buggy qemu, etc, and since no one reads the FAQ,
1586 describe in this error message what resources are available to debug
1587 launch problems.
1588
1589 Function "lib/errors.c:guestfs_int_unexpected_close_error"
1590
1591 void
1592 guestfs_int_unexpected_close_error (guestfs_h *g)
1593
1594 Raise an error if the appliance unexpectedly crashes after launch.
1595
1596 Function "lib/errors.c:guestfs_int_launch_timeout"
1597
1598 void
1599 guestfs_int_launch_timeout (guestfs_h *g)
1600
1601 Raise an error if the appliance hangs during launch.
1602
1603 Function "lib/errors.c:guestfs_int_external_command_failed"
1604
1605 void
1606 guestfs_int_external_command_failed (guestfs_h *g, int status,
1607 const char *cmd_name, const char *extra)
1608
1609 Raise an error if an external command fails.
1610
1611 "status" is the status code of the command (eg. returned from
1612 waitpid(2) or system(3)). This function turns the status code into an
1613 explanatory string.
1614
1615 File lib/events.c
1616
1617 Function "lib/events.c:replace_old_style_event_callback"
1618
1619 static void
1620 replace_old_style_event_callback (guestfs_h *g,
1621 guestfs_event_callback cb,
1622 uint64_t event_bitmask,
1623 void *opaque,
1624 void *opaque2)
1625
1626 Emulate old-style callback API.
1627
1628 There were no event handles, so multiple callbacks per event were not
1629 supported. Calling the same "guestfs_set_*_callback" function would
1630 replace the existing event. Calling it with "cb == NULL" meant that
1631 the caller wanted to remove the callback.
1632
1633 File lib/guestfs-internal-all.h
1634
1635 This header contains definitions which are shared by all parts of
1636 libguestfs, ie. the daemon, the library, language bindings and virt
1637 tools (ie. all C code).
1638
1639 If you need a definition used by only the library, put it in
1640 lib/guestfs-internal.h instead.
1641
1642 If a definition is used by only a single tool, it should not be in any
1643 shared header file at all.
1644
1645 File lib/guestfs-internal.h
1646
1647 This header file is included in the libguestfs library (lib/) only.
1648
1649 See also lib/guestfs-internal-all.h.
1650
1651 Structure "lib/guestfs-internal.h:event"
1652
1653 struct event {
1654 uint64_t event_bitmask;
1655 guestfs_event_callback cb;
1656 void *opaque;
1657
1658 /* opaque2 is not exposed through the API, but is used internally to
1659 * emulate the old-style callback API.
1660 */
1661 void *opaque2;
1662 };
1663
1664 This struct is used to maintain a list of events registered against the
1665 handle. See "g->events" in the handle.
1666
1667 Structure "lib/guestfs-internal.h:drive"
1668
1669 struct drive {
1670 /* Original source of the drive, eg. file:..., http:... */
1671 struct drive_source src;
1672
1673 /* If the drive is readonly, then an overlay [a local file] is
1674 * created before launch to protect the original drive content, and
1675 * the filename is stored here. Backends should open this file if
1676 * it is non-NULL, else consult the original source above.
1677 *
1678 * Note that the overlay is in a backend-specific format, probably
1679 * different from the source format. eg. qcow2
1680 */
1681 char *overlay;
1682
1683 /* Various per-drive flags. */
1684 bool readonly;
1685 char *name;
1686 char *disk_label;
1687 char *cachemode;
1688 enum discard discard;
1689 bool copyonread;
1690 int blocksize;
1691 };
1692
1693 There is one "struct drive" per drive.
1694
1695 Structure "lib/guestfs-internal.h:backend_ops"
1696
1697 struct backend_ops {
1698 /* Size (in bytes) of the per-handle data structure needed by this
1699 * backend. The data pointer is allocated and freed by libguestfs
1700 * and passed to the functions in the 'void *data' parameter.
1701 * Inside the data structure is opaque to libguestfs. Any strings
1702 * etc pointed to by it must be freed by the backend during
1703 * shutdown.
1704 */
1705 size_t data_size;
1706
1707 /* Create a COW overlay on top of a drive. This must be a local
1708 * file, created in the temporary directory. This is called when
1709 * the drive is added to the handle.
1710 */
1711 char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv);
1712
1713 /* Launch and shut down. */
1714 int (*launch) (guestfs_h *g, void *data, const char *arg);
1715 int (*shutdown) (guestfs_h *g, void *data, int check_for_errors);
1716
1717 /* Miscellaneous. */
1718 int (*get_pid) (guestfs_h *g, void *data);
1719 int (*max_disks) (guestfs_h *g, void *data);
1720 };
1721
1722 Backend operations.
1723
1724 Each backend (eg. libvirt, direct) defines some functions which get run
1725 at various places in the handle lifecycle (eg. at launch, shutdown).
1726 The backend defines this struct pointing to those functions.
1727
1728 Structure "lib/guestfs-internal.h:connection"
1729
1730 struct connection {
1731 const struct connection_ops *ops;
1732
1733 /* In the real struct, private data used by each connection module
1734 * follows here.
1735 */
1736 };
1737
1738 Connection module.
1739
1740 A "connection" represents the appliance console connection plus the
1741 daemon connection. It hides the underlying representation (POSIX
1742 sockets, "virStreamPtr").
1743
1744 Structure "lib/guestfs-internal.h:cached_feature"
1745
1746 struct cached_feature {
1747 char *group;
1748 int result;
1749 };
1750
1751 Cache of queried features.
1752
1753 Used to cache the appliance features (see lib/available.c).
1754
1755 Structure "lib/guestfs-internal.h:guestfs_h"
1756
1757 struct guestfs_h {
1758 struct guestfs_h *next; /* Linked list of open handles. */
1759 enum state state; /* See the state machine diagram in guestfs(3)*/
1760
1761 /* Lock acquired when entering any public guestfs_* function to
1762 * protect the handle.
1763 */
1764 pthread_mutex_t lock;
1765
1766 /**** Configuration of the handle. ****/
1767 bool verbose; /* Debugging. */
1768 bool trace; /* Trace calls. */
1769 bool autosync; /* Autosync. */
1770 bool direct_mode; /* Direct mode. */
1771 bool recovery_proc; /* Create a recovery process. */
1772 bool enable_network; /* Enable the network. */
1773 bool selinux; /* selinux enabled? */
1774 bool pgroup; /* Create process group for children? */
1775 bool close_on_exit; /* Is this handle on the atexit list? */
1776
1777 int smp; /* If > 1, -smp flag passed to hv. */
1778 int memsize; /* Size of RAM (megabytes). */
1779
1780 char *path; /* Path to the appliance. */
1781 char *hv; /* Hypervisor (HV) binary. */
1782 char *append; /* Append to kernel command line. */
1783
1784 struct hv_param *hv_params; /* Extra hv parameters. */
1785
1786 char *program; /* Program name. */
1787 char *identifier; /* Handle identifier. */
1788
1789 /* Array of drives added by add-drive* APIs.
1790 *
1791 * Before launch this list can be empty or contain some drives.
1792 *
1793 * During launch, a dummy slot may be added which represents the
1794 * slot taken up by the appliance drive.
1795 *
1796 * During shutdown, this list is deleted, so that each launch gets a
1797 * fresh set of drives (however callers: don't do this, create a new
1798 * handle each time).
1799 *
1800 * Always use ITER_DRIVES macro to iterate over this list!
1801 */
1802 struct drive **drives;
1803 size_t nr_drives;
1804
1805 #define ITER_DRIVES(g,i,drv) \
1806 for (i = 0; i < (g)->nr_drives; ++i) \
1807 if (((drv) = (g)->drives[i]) != NULL)
1808
1809 /* Backend. NB: Use guestfs_int_set_backend to change the backend. */
1810 char *backend; /* The full string, always non-NULL. */
1811 char *backend_arg; /* Pointer to the argument part. */
1812 const struct backend_ops *backend_ops;
1813 void *backend_data; /* Per-handle data. */
1814 char **backend_settings; /* Backend settings (can be NULL). */
1815
1816 /**** Runtime information. ****/
1817 /* Temporary and cache directories. */
1818 /* The actual temporary directory - this is not created with the
1819 * handle, you have to call guestfs_int_lazy_make_tmpdir.
1820 */
1821 char *tmpdir;
1822 char *sockdir;
1823 /* Environment variables that affect tmpdir/cachedir/sockdir locations. */
1824 char *env_tmpdir; /* $TMPDIR (NULL if not set) */
1825 char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/
1826 char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */
1827 char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */
1828
1829 /* Error handler, plus stack of old error handlers. */
1830 pthread_key_t error_data;
1831
1832 /* Linked list of error_data structures allocated for this handle,
1833 * plus a mutex to protect the linked list.
1834 */
1835 pthread_mutex_t error_data_list_lock;
1836 struct error_data *error_data_list;
1837
1838 /* Out of memory error handler. */
1839 guestfs_abort_cb abort_cb;
1840
1841 /* Events. */
1842 struct event *events;
1843 size_t nr_events;
1844
1845 /* Private data area. */
1846 struct hash_table *pda;
1847 struct pda_entry *pda_next;
1848
1849 /* User cancelled transfer. Not signal-atomic, but it doesn't
1850 * matter for this case because we only care if it is != 0.
1851 */
1852 int user_cancel;
1853
1854 struct timeval launch_t; /* The time that we called guestfs_launch. */
1855
1856 /* Used by bindtests. */
1857 FILE *test_fp;
1858
1859 /* Used to generate unique numbers, eg for temp files. To use this,
1860 * '++g->unique'. Note these are only unique per-handle, not
1861 * globally unique.
1862 */
1863 int unique;
1864
1865 /*** Protocol. ***/
1866 struct connection *conn; /* Connection to appliance. */
1867 int msg_next_serial;
1868
1869 #if HAVE_FUSE
1870 /**** Used by the mount-local APIs. ****/
1871 char *localmountpoint;
1872 struct fuse *fuse; /* FUSE handle. */
1873 int ml_dir_cache_timeout; /* Directory cache timeout. */
1874 Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */
1875 int ml_read_only; /* If mounted read-only. */
1876 int ml_debug_calls; /* Extra debug info on each FUSE call. */
1877 #endif
1878
1879 #ifdef HAVE_LIBVIRT
1880 /* Used by lib/libvirt-auth.c. */
1881 #define NR_CREDENTIAL_TYPES 9
1882 unsigned int nr_supported_credentials;
1883 int supported_credentials[NR_CREDENTIAL_TYPES];
1884 const char *saved_libvirt_uri; /* Doesn't need to be freed. */
1885 bool wrapper_warning_done;
1886 unsigned int nr_requested_credentials;
1887 virConnectCredentialPtr requested_credentials;
1888 #endif
1889
1890 /* Cached features. */
1891 struct cached_feature *features;
1892 size_t nr_features;
1893
1894 /* Used by lib/info.c. -1 = not tested or error; else 0 or 1. */
1895 int qemu_img_supports_U_option;
1896 };
1897
1898 The libguestfs handle.
1899
1900 Structure "lib/guestfs-internal.h:version"
1901
1902 struct version {
1903 int v_major;
1904 int v_minor;
1905 int v_micro;
1906 };
1907
1908 Used for storing major.minor.micro version numbers. See lib/version.c
1909 for more information.
1910
1911 File lib/guid.c
1912
1913 Function "lib/guid.c:guestfs_int_validate_guid"
1914
1915 int
1916 guestfs_int_validate_guid (const char *str)
1917
1918 Check whether a string supposed to contain a GUID actually contains it.
1919 It can recognize strings either as
1920 "{21EC2020-3AEA-1069-A2DD-08002B30309D}" or
1921 "21EC2020-3AEA-1069-A2DD-08002B30309D".
1922
1923 File lib/handle.c
1924
1925 This file deals with the "guestfs_h" handle, creating it, closing it,
1926 and initializing/setting/getting fields.
1927
1928 Function "lib/handle.c:init_libguestfs"
1929
1930 static void
1931 init_libguestfs (void)
1932
1933 No initialization is required by libguestfs, but libvirt and libxml2
1934 require initialization if they might be called from multiple threads.
1935 Hence this constructor function which is called when libguestfs is
1936 first loaded.
1937
1938 Function "lib/handle.c:shutdown_backend"
1939
1940 static int
1941 shutdown_backend (guestfs_h *g, int check_for_errors)
1942
1943 This function is the common path for shutting down the backend qemu
1944 process.
1945
1946 "guestfs_shutdown" calls "shutdown_backend" with "check_for_errors=1".
1947 "guestfs_close" calls "shutdown_backend" with "check_for_errors=0".
1948
1949 "check_for_errors" is a hint to the backend about whether we care about
1950 errors or not. In the libvirt case it can be used to optimize the
1951 shutdown for speed when we don't care.
1952
1953 Function "lib/handle.c:close_handles"
1954
1955 static void
1956 close_handles (void)
1957
1958 Close all open handles (called from atexit(3)).
1959
1960 Function "lib/handle.c:guestfs_int_get_backend_setting_bool"
1961
1962 int
1963 guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name)
1964
1965 This is a convenience function, but we might consider exporting it as
1966 an API in future.
1967
1968 File lib/info.c
1969
1970 Function "lib/info.c:qemu_img_supports_U_option"
1971
1972 static int
1973 qemu_img_supports_U_option (guestfs_h *g)
1974
1975 Test if the qemu-img info command supports the "-U" option to disable
1976 locking. The result is memoized in the handle.
1977
1978 Note this option was added in qemu 2.11. We can remove this test when
1979 we can assume everyone is using qemu >= 2.11.
1980
1981 File lib/inspect-icon.c
1982
1983 Function "lib/inspect-icon.c:guestfs_int_download_to_tmp"
1984
1985 char *
1986 guestfs_int_download_to_tmp (guestfs_h *g, const char *filename,
1987 const char *extension,
1988 uint64_t max_size)
1989
1990 Download a guest file to a local temporary file.
1991
1992 The name of the temporary (downloaded) file is returned. The caller
1993 must free the pointer, but does not need to delete the temporary file.
1994 It will be deleted when the handle is closed.
1995
1996 The name of the temporary file is randomly generated, but an extension
1997 can be specified using "extension" (or pass "NULL" for none).
1998
1999 Refuse to download the guest file if it is larger than "max_size". On
2000 this and other errors, "NULL" is returned.
2001
2002 File lib/launch-direct.c
2003
2004 Implementation of the "direct" backend.
2005
2006 For more details see "BACKENDS" in guestfs(3).
2007
2008 Function "lib/launch-direct.c:add_drive_standard_params"
2009
2010 static int
2011 add_drive_standard_params (guestfs_h *g, struct backend_direct_data *data,
2012 struct qemuopts *qopts,
2013 size_t i, struct drive *drv)
2014
2015 Add the standard elements of the "-drive" parameter.
2016
2017 Function "lib/launch-direct.c:add_device_blocksize_params"
2018
2019 static int
2020 add_device_blocksize_params (guestfs_h *g, struct qemuopts *qopts,
2021 struct drive *drv)
2022
2023 Add the physical_block_size and logical_block_size elements of the
2024 "-device" parameter.
2025
2026 File lib/launch-libvirt.c
2027
2028 Function "lib/launch-libvirt.c:get_source_format_or_autodetect"
2029
2030 static char *
2031 get_source_format_or_autodetect (guestfs_h *g, struct drive *drv)
2032
2033 Return "drv->src.format", but if it is "NULL", autodetect the format.
2034
2035 libvirt has disabled the feature of detecting the disk format, unless
2036 the administrator sets "allow_disk_format_probing=1" in
2037 /etc/libvirt/qemu.conf. There is no way to detect if this option is
2038 set, so we have to do format detection here using "qemu-img" and pass
2039 that to libvirt.
2040
2041 This can still be a security issue, so in most cases it is recommended
2042 the users pass the format to libguestfs which will faithfully pass that
2043 straight through to libvirt without doing autodetection.
2044
2045 Caller must free the returned string. On error this function sets the
2046 error in the handle and returns "NULL".
2047
2048 Function "lib/launch-libvirt.c:make_qcow2_overlay"
2049
2050 static char *
2051 make_qcow2_overlay (guestfs_h *g, const char *backing_drive,
2052 const char *format)
2053
2054 Create a qcow2 format overlay, with the given "backing_drive" (file).
2055 The "format" parameter is the backing file format. The "format"
2056 parameter can be NULL, in this case the backing format will be
2057 determined automatically. This is used to create the appliance
2058 overlay, and also for read-only drives.
2059
2060 File lib/launch.c
2061
2062 This file implements "guestfs_launch" in guestfs(3).
2063
2064 Most of the work is done by the backends (see "BACKEND" in guestfs(3)),
2065 which are implemented in lib/launch-direct.c, lib/launch-libvirt.c etc,
2066 so this file mostly passes calls through to the current backend.
2067
2068 Function "lib/launch.c:guestfs_int_launch_send_progress"
2069
2070 void
2071 guestfs_int_launch_send_progress (guestfs_h *g, int perdozen)
2072
2073 This function sends a launch progress message.
2074
2075 Launching the appliance generates approximate progress messages.
2076 Currently these are defined as follows:
2077
2078 0 / 12: launch clock starts
2079 3 / 12: appliance created
2080 6 / 12: detected that guest kernel started
2081 9 / 12: detected that /init script is running
2082 12 / 12: launch completed successfully
2083
2084 Notes:
2085
2086 1. This is not a documented ABI and the behaviour may be changed or
2087 removed in future.
2088
2089 2. Messages are only sent if more than 5 seconds has elapsed since the
2090 launch clock started.
2091
2092 3. There is a hack in lib/proto.c to make this work.
2093
2094 Function "lib/launch.c:guestfs_int_timeval_diff"
2095
2096 int64_t
2097 guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y)
2098
2099 Compute "y - x" and return the result in milliseconds.
2100
2101 Approximately the same as this code:
2102 http://www.mpp.mpg.de/~huber/util/timevaldiff.c
2103
2104 Function "lib/launch.c:guestfs_int_unblock_sigterm"
2105
2106 void
2107 guestfs_int_unblock_sigterm (void)
2108
2109 Unblock the "SIGTERM" signal. Call this after fork(2) so that the
2110 parent process can send "SIGTERM" to the child process in case
2111 "SIGTERM" is blocked. See https://bugzilla.redhat.com/1460338.
2112
2113 Function "lib/launch.c:guestfs_impl_max_disks"
2114
2115 int
2116 guestfs_impl_max_disks (guestfs_h *g)
2117
2118 Returns the maximum number of disks allowed to be added to the backend
2119 (backend dependent).
2120
2121 Function "lib/launch.c:guestfs_impl_wait_ready"
2122
2123 int
2124 guestfs_impl_wait_ready (guestfs_h *g)
2125
2126 Implementation of "guestfs_wait_ready" in guestfs(3). You had to call
2127 this function after launch in versions ≤ 1.0.70, but it is now an
2128 (almost) no-op.
2129
2130 Function "lib/launch.c:guestfs_int_create_socketname"
2131
2132 int
2133 guestfs_int_create_socketname (guestfs_h *g, const char *filename,
2134 char (*sockpath)[UNIX_PATH_MAX])
2135
2136 Create the path for a socket with the selected filename in the tmpdir.
2137
2138 Function "lib/launch.c:guestfs_int_register_backend"
2139
2140 void
2141 guestfs_int_register_backend (const char *name, const struct backend_ops *ops)
2142
2143 When the library is loaded, each backend calls this function to
2144 register itself in a global list.
2145
2146 Function "lib/launch.c:guestfs_int_set_backend"
2147
2148 int
2149 guestfs_int_set_backend (guestfs_h *g, const char *method)
2150
2151 Implementation of "guestfs_set_backend" in guestfs(3).
2152
2153 • Callers must ensure this is only called in the config state.
2154
2155 • This shouldn't call "error" since it may be called early in handle
2156 initialization. It can return an error code however.
2157
2158 File lib/private-data.c
2159
2160 Implement a private data area where libguestfs C API users can attach
2161 arbitrary pieces of data to a "guestfs_h" handle.
2162
2163 For more information see "PRIVATE DATA AREA" in guestfs(3).
2164
2165 Language bindings do not generally expose this, largely because in non-
2166 C languages it is easy to associate data with handles in other ways
2167 (using hash tables or maps).
2168
2169 Structure "lib/private-data.c:pda_entry"
2170
2171 struct pda_entry {
2172 char *key; /* key */
2173 void *data; /* opaque user data pointer */
2174 };
2175
2176 The private data area is internally stored as a gnulib hash table
2177 containing "pda_entry" structures.
2178
2179 Note the private data area is allocated lazily, since the vast majority
2180 of callers will never use it. This means "g->pda" is likely to be
2181 "NULL".
2182
2183 File lib/proto.c
2184
2185 This is the code used to send and receive RPC messages and (for certain
2186 types of message) to perform file transfers. This code is driven from
2187 the generated actions (lib/actions-*.c). There are five different
2188 cases to consider:
2189
2190 1. A non-daemon function (eg. "guestfs_set_verbose" in guestfs(3)).
2191 There is no RPC involved at all, it's all handled inside the
2192 library.
2193
2194 2. A simple RPC (eg. "guestfs_mount" in guestfs(3)). We write the
2195 request, then read the reply. The sequence of calls is:
2196
2197 guestfs_int_send
2198 guestfs_int_recv
2199
2200 3. An RPC with "FileIn" parameters (eg. "guestfs_upload" in
2201 guestfs(3)). We write the request, then write the file(s), then
2202 read the reply. The sequence of calls is:
2203
2204 guestfs_int_send
2205 guestfs_int_send_file (possibly multiple times)
2206 guestfs_int_recv
2207
2208 4. An RPC with "FileOut" parameters (eg. "guestfs_download" in
2209 guestfs(3)). We write the request, then read the reply, then read
2210 the file(s). The sequence of calls is:
2211
2212 guestfs_int_send
2213 guestfs_int_recv
2214 guestfs_int_recv_file (possibly multiple times)
2215
2216 5. Both "FileIn" and "FileOut" parameters. There are no calls like
2217 this in the current API, but they would be implemented as a
2218 combination of cases 3 and 4.
2219
2220 All read/write/etc operations are performed using the current
2221 connection module ("g->conn"). During operations the connection module
2222 transparently handles log messages that appear on the console.
2223
2224 Function "lib/proto.c:child_cleanup"
2225
2226 static void
2227 child_cleanup (guestfs_h *g)
2228
2229 This is called if we detect EOF, ie. qemu died.
2230
2231 Function "lib/proto.c:guestfs_int_progress_message_callback"
2232
2233 void
2234 guestfs_int_progress_message_callback (guestfs_h *g,
2235 const guestfs_progress *message)
2236
2237 Convenient wrapper to generate a progress message callback.
2238
2239 Function "lib/proto.c:guestfs_int_log_message_callback"
2240
2241 void
2242 guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len)
2243
2244 Connection modules call us back here when they get a log message.
2245
2246 Function "lib/proto.c:check_daemon_socket"
2247
2248 static ssize_t
2249 check_daemon_socket (guestfs_h *g)
2250
2251 Before writing to the daemon socket, check the read side of the daemon
2252 socket for any of these conditions:
2253
2254 error
2255 return -1
2256
2257 daemon cancellation message
2258 return -2
2259
2260 progress message
2261 handle it here
2262
2263 end of input or appliance exited unexpectedly
2264 return 0
2265
2266 anything else
2267 return 1
2268
2269 Function "lib/proto.c:guestfs_int_send_file"
2270
2271 int
2272 guestfs_int_send_file (guestfs_h *g, const char *filename)
2273
2274 Send a file.
2275
2276 Returns 0 on success, -1 for error, -2 if the daemon cancelled (we must
2277 read the error message).
2278
2279 Function "lib/proto.c:send_file_data"
2280
2281 static int
2282 send_file_data (guestfs_h *g, const char *buf, size_t len)
2283
2284 Send a chunk of file data.
2285
2286 Function "lib/proto.c:send_file_cancellation"
2287
2288 static int
2289 send_file_cancellation (guestfs_h *g)
2290
2291 Send a cancellation message.
2292
2293 Function "lib/proto.c:send_file_complete"
2294
2295 static int
2296 send_file_complete (guestfs_h *g)
2297
2298 Send a file complete chunk.
2299
2300 Function "lib/proto.c:recv_from_daemon"
2301
2302 static int
2303 recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn)
2304
2305 This function reads a single message, file chunk, launch flag or
2306 cancellation flag from the daemon. If something was read, it returns
2307 0, otherwise -1.
2308
2309 Both "size_rtn" and "buf_rtn" must be passed by the caller as non-NULL.
2310
2311 *size_rtn returns the size of the returned message or it may be
2312 "GUESTFS_LAUNCH_FLAG" or "GUESTFS_CANCEL_FLAG".
2313
2314 *buf_rtn is returned containing the message (if any) or will be set to
2315 "NULL". *buf_rtn must be freed by the caller.
2316
2317 This checks for EOF (appliance died) and passes that up through the
2318 child_cleanup function above.
2319
2320 Log message, progress messages are handled transparently here.
2321
2322 Function "lib/proto.c:guestfs_int_recv"
2323
2324 int
2325 guestfs_int_recv (guestfs_h *g, const char *fn,
2326 guestfs_message_header *hdr,
2327 guestfs_message_error *err,
2328 xdrproc_t xdrp, char *ret)
2329
2330 Receive a reply.
2331
2332 Function "lib/proto.c:guestfs_int_recv_discard"
2333
2334 int
2335 guestfs_int_recv_discard (guestfs_h *g, const char *fn)
2336
2337 Same as "guestfs_int_recv", but it discards the reply message.
2338
2339 Notes (XXX):
2340
2341 • This returns an int, but all current callers ignore it.
2342
2343 • The error string may end up being set twice on error paths.
2344
2345 Function "lib/proto.c:guestfs_int_recv_file"
2346
2347 int
2348 guestfs_int_recv_file (guestfs_h *g, const char *filename)
2349
2350 Returns -1 = error, 0 = EOF, ">0" = more data
2351
2352 Function "lib/proto.c:receive_file_data"
2353
2354 static ssize_t
2355 receive_file_data (guestfs_h *g, void **buf_r)
2356
2357 Receive a chunk of file data.
2358
2359 Returns -1 = error, 0 = EOF, ">0" = more data
2360
2361 File lib/qemu.c
2362
2363 Functions to handle qemu versions and features.
2364
2365 Function "lib/qemu.c:guestfs_int_test_qemu"
2366
2367 struct qemu_data *
2368 guestfs_int_test_qemu (guestfs_h *g)
2369
2370 Test that the qemu binary (or wrapper) runs, and do "qemu -help" and
2371 other commands so we can find out the version of qemu and what options
2372 this qemu supports.
2373
2374 This caches the results in the cachedir so that as long as the qemu
2375 binary does not change, calling this is effectively free.
2376
2377 Function "lib/qemu.c:cache_filename"
2378
2379 static char *
2380 cache_filename (guestfs_h *g, const char *cachedir,
2381 const struct stat *statbuf, const char *suffix)
2382
2383 Generate the filenames, for the stat file and the other cache files.
2384
2385 By including the size and mtime in the filename we also ensure that the
2386 same user can use multiple versions of qemu without conflicts.
2387
2388 Function "lib/qemu.c:parse_qemu_version"
2389
2390 static void
2391 parse_qemu_version (guestfs_h *g, const char *qemu_help,
2392 struct version *qemu_version)
2393
2394 Parse the first line of "qemu_help" into the major and minor version of
2395 qemu, but don't fail if parsing is not possible.
2396
2397 Function "lib/qemu.c:parse_json"
2398
2399 static void
2400 parse_json (guestfs_h *g, const char *json, json_t **treep)
2401
2402 Parse the json output from QMP. But don't fail if parsing is not
2403 possible.
2404
2405 Function "lib/qemu.c:parse_has_kvm"
2406
2407 static void
2408 parse_has_kvm (guestfs_h *g, const char *json, bool *ret)
2409
2410 Parse the json output from QMP query-kvm to find out if KVM is enabled
2411 on this machine. Don't fail if parsing is not possible, assume KVM is
2412 available.
2413
2414 The JSON output looks like: {"return": {"enabled": true, "present":
2415 true}}
2416
2417 Function "lib/qemu.c:generic_read_cache"
2418
2419 static int
2420 generic_read_cache (guestfs_h *g, const char *filename, char **strp)
2421
2422 Generic functions for reading and writing the cache files, used where
2423 we are just reading and writing plain text strings.
2424
2425 Function "lib/qemu.c:generic_qmp_test"
2426
2427 static int
2428 generic_qmp_test (guestfs_h *g, struct qemu_data *data,
2429 const char *qmp_command,
2430 char **outp)
2431
2432 Run a generic QMP test on the QEMU binary.
2433
2434 Function "lib/qemu.c:guestfs_int_qemu_version"
2435
2436 struct version
2437 guestfs_int_qemu_version (guestfs_h *g, struct qemu_data *data)
2438
2439 Return the parsed version of qemu.
2440
2441 Function "lib/qemu.c:guestfs_int_qemu_supports"
2442
2443 int
2444 guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data,
2445 const char *option)
2446
2447 Test if option is supported by qemu command line (just by grepping the
2448 help text).
2449
2450 Function "lib/qemu.c:guestfs_int_qemu_supports_device"
2451
2452 int
2453 guestfs_int_qemu_supports_device (guestfs_h *g,
2454 const struct qemu_data *data,
2455 const char *device_name)
2456
2457 Test if device is supported by qemu (currently just greps the "qemu
2458 -device ?" output).
2459
2460 Function "lib/qemu.c:guestfs_int_qemu_mandatory_locking"
2461
2462 int
2463 guestfs_int_qemu_mandatory_locking (guestfs_h *g,
2464 const struct qemu_data *data)
2465
2466 Test if the qemu binary uses mandatory file locking, added in QEMU >=
2467 2.10 (but sometimes disabled).
2468
2469 Function "lib/qemu.c:guestfs_int_qemu_escape_param"
2470
2471 char *
2472 guestfs_int_qemu_escape_param (guestfs_h *g, const char *param)
2473
2474 Escape a qemu parameter.
2475
2476 Every "," becomes ",,". The caller must free the returned string.
2477
2478 XXX This functionality is now only used when constructing a qemu-img
2479 command in lib/create.c. We should extend the qemuopts library to
2480 cover this use case.
2481
2482 Function "lib/qemu.c:guestfs_int_drive_source_qemu_param"
2483
2484 char *
2485 guestfs_int_drive_source_qemu_param (guestfs_h *g,
2486 const struct drive_source *src)
2487
2488 Useful function to format a drive + protocol for qemu.
2489
2490 Note that the qemu parameter is the bit after "file=". It is not
2491 escaped here, but would usually be escaped if passed to qemu as part of
2492 a full -drive parameter (but not for qemu-img(1)).
2493
2494 Function "lib/qemu.c:guestfs_int_discard_possible"
2495
2496 bool
2497 guestfs_int_discard_possible (guestfs_h *g, struct drive *drv,
2498 const struct version *qemu_version)
2499
2500 Test if discard is both supported by qemu AND possible with the
2501 underlying file or device. This returns 1 if discard is possible. It
2502 returns 0 if not possible and sets the error to the reason why.
2503
2504 This function is called when the user set "discard == "enable"".
2505
2506 Function "lib/qemu.c:guestfs_int_free_qemu_data"
2507
2508 void
2509 guestfs_int_free_qemu_data (struct qemu_data *data)
2510
2511 Free the "struct qemu_data".
2512
2513 File lib/rescue.c
2514
2515 Support for virt-rescue(1).
2516
2517 File lib/stringsbuf.c
2518
2519 An expandable NULL-terminated vector of strings (like "argv").
2520
2521 Use the "DECLARE_STRINGSBUF" macro to declare the stringsbuf.
2522
2523 Note: Don't confuse this with stringsbuf in the daemon which is a
2524 different type with different methods.
2525
2526 Function "lib/stringsbuf.c:guestfs_int_add_string_nodup"
2527
2528 void
2529 guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str)
2530
2531 Add a string to the end of the list.
2532
2533 This doesn't call strdup(3) on the string, so the string itself is
2534 stored inside the vector.
2535
2536 Function "lib/stringsbuf.c:guestfs_int_add_string"
2537
2538 void
2539 guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str)
2540
2541 Add a string to the end of the list.
2542
2543 This makes a copy of the string.
2544
2545 Function "lib/stringsbuf.c:guestfs_int_add_sprintf"
2546
2547 void
2548 guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb,
2549 const char *fs, ...)
2550
2551 Add a string to the end of the list.
2552
2553 Uses an sprintf-like format string when creating the string.
2554
2555 Function "lib/stringsbuf.c:guestfs_int_end_stringsbuf"
2556
2557 void
2558 guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb)
2559
2560 Finish the string buffer.
2561
2562 This adds the terminating NULL to the end of the vector.
2563
2564 Function "lib/stringsbuf.c:guestfs_int_free_stringsbuf"
2565
2566 void
2567 guestfs_int_free_stringsbuf (struct stringsbuf *sb)
2568
2569 Free the string buffer and the strings.
2570
2571 File lib/tmpdirs.c
2572
2573 Handle temporary directories.
2574
2575 Function "lib/tmpdirs.c:set_abs_path"
2576
2577 static int
2578 set_abs_path (guestfs_h *g, const char *ctxstr,
2579 const char *tmpdir, char **tmpdir_ret)
2580
2581 We need to make all tmpdir paths absolute because lots of places in the
2582 code assume this. Do it at the time we set the path or read the
2583 environment variable (https://bugzilla.redhat.com/882417).
2584
2585 The "ctxstr" parameter is a string displayed in error messages giving
2586 the context of the operation (eg. name of environment variable being
2587 used, or API function being called).
2588
2589 Function "lib/tmpdirs.c:guestfs_impl_get_tmpdir"
2590
2591 char *
2592 guestfs_impl_get_tmpdir (guestfs_h *g)
2593
2594 Implements the "guestfs_get_tmpdir" API.
2595
2596 Note this actually calculates the tmpdir, so it never returns "NULL".
2597
2598 Function "lib/tmpdirs.c:guestfs_impl_get_cachedir"
2599
2600 char *
2601 guestfs_impl_get_cachedir (guestfs_h *g)
2602
2603 Implements the "guestfs_get_cachedir" API.
2604
2605 Note this actually calculates the cachedir, so it never returns "NULL".
2606
2607 Function "lib/tmpdirs.c:guestfs_impl_get_sockdir"
2608
2609 char *
2610 guestfs_impl_get_sockdir (guestfs_h *g)
2611
2612 Implements the "guestfs_get_sockdir" API.
2613
2614 Note this actually calculates the sockdir, so it never returns "NULL".
2615
2616 Function "lib/tmpdirs.c:guestfs_int_lazy_make_tmpdir"
2617
2618 int
2619 guestfs_int_lazy_make_tmpdir (guestfs_h *g)
2620
2621 The "g->tmpdir" (per-handle temporary directory) is not created when
2622 the handle is created. Instead we create it lazily before the first
2623 time it is used, or during launch.
2624
2625 Function "lib/tmpdirs.c:guestfs_int_make_temp_path"
2626
2627 char *
2628 guestfs_int_make_temp_path (guestfs_h *g,
2629 const char *name, const char *extension)
2630
2631 Generate unique temporary paths for temporary files.
2632
2633 Returns a unique path or NULL on error.
2634
2635 Function "lib/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir"
2636
2637 char *
2638 guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g)
2639
2640 Create the supermin appliance directory under cachedir, if it does not
2641 exist.
2642
2643 Sanity-check that the permissions on the cachedir are safe, in case it
2644 has been pre-created maliciously or tampered with.
2645
2646 Returns the directory name which the caller must free.
2647
2648 Function "lib/tmpdirs.c:guestfs_int_recursive_remove_dir"
2649
2650 void
2651 guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir)
2652
2653 Recursively remove a temporary directory. If removal fails, just
2654 return (it's a temporary directory so it'll eventually be cleaned up by
2655 a temp cleaner).
2656
2657 This is implemented using "rm -rf" because that's simpler and safer.
2658
2659 File lib/umask.c
2660
2661 Return current umask in a thread-safe way.
2662
2663 glibc documents, but does not actually implement, a "getumask(3)" call.
2664
2665 We use "Umask" from /proc/self/status for Linux ≥ 4.7. For older Linux
2666 and other Unix, this file implements an expensive but thread-safe way
2667 to get the current process's umask.
2668
2669 Thanks to: Josh Stone, Jiri Jaburek, Eric Blake.
2670
2671 Function "lib/umask.c:guestfs_int_getumask"
2672
2673 int
2674 guestfs_int_getumask (guestfs_h *g)
2675
2676 Returns the current process's umask. On failure, returns -1 and sets
2677 the error in the guestfs handle.
2678
2679 Function "lib/umask.c:get_umask_from_proc"
2680
2681 static int
2682 get_umask_from_proc (guestfs_h *g)
2683
2684 For Linux ≥ 4.7 get the umask from /proc/self/status.
2685
2686 On failure this returns -1. However if we could not open the /proc
2687 file or find the "Umask" entry in it, return -2 which causes the
2688 fallback path to run.
2689
2690 Function "lib/umask.c:get_umask_from_fork"
2691
2692 static int
2693 get_umask_from_fork (guestfs_h *g)
2694
2695 Fallback method of getting the umask using fork.
2696
2697 File lib/unit-tests.c
2698
2699 Unit tests of internal functions.
2700
2701 These tests may use a libguestfs handle, but must not launch the
2702 handle. Also, avoid long-running tests.
2703
2704 Function "lib/unit-tests.c:test_split"
2705
2706 static void
2707 test_split (void)
2708
2709 Test "guestfs_int_split_string".
2710
2711 Function "lib/unit-tests.c:test_concat"
2712
2713 static void
2714 test_concat (void)
2715
2716 Test "guestfs_int_concat_strings".
2717
2718 Function "lib/unit-tests.c:test_join"
2719
2720 static void
2721 test_join (void)
2722
2723 Test "guestfs_int_join_strings".
2724
2725 Function "lib/unit-tests.c:test_validate_guid"
2726
2727 static void
2728 test_validate_guid (void)
2729
2730 Test "guestfs_int_validate_guid".
2731
2732 Function "lib/unit-tests.c:test_drive_name"
2733
2734 static void
2735 test_drive_name (void)
2736
2737 Test "guestfs_int_drive_name".
2738
2739 Function "lib/unit-tests.c:test_drive_index"
2740
2741 static void
2742 test_drive_index (void)
2743
2744 Test "guestfs_int_drive_index".
2745
2746 Function "lib/unit-tests.c:test_getumask"
2747
2748 static void
2749 test_getumask (void)
2750
2751 Test "guestfs_int_getumask".
2752
2753 Function "lib/unit-tests.c:test_command"
2754
2755 static void
2756 test_command (void)
2757
2758 Test "guestfs_int_new_command" etc.
2759
2760 XXX These tests could be made much more thorough. So far we simply
2761 test that it's not obviously broken.
2762
2763 Function "lib/unit-tests.c:test_qemu_escape_param"
2764
2765 static void
2766 test_qemu_escape_param (void)
2767
2768 Test "guestfs_int_qemu_escape_param"
2769
2770 XXX I wanted to make this test run qemu, passing some parameters which
2771 need to be escaped, but I cannot think of a way to do that without
2772 launching a VM.
2773
2774 Function "lib/unit-tests.c:test_timeval_diff"
2775
2776 static void
2777 test_timeval_diff (void)
2778
2779 Test "guestfs_int_timeval_diff".
2780
2781 File lib/version.c
2782
2783 This file provides simple version number management.
2784
2785 Function "lib/version.c:guestfs_int_version_from_x_y"
2786
2787 int
2788 guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str)
2789
2790 Parses a version from a string, looking for a "X.Y" pattern.
2791
2792 Returns -1 on failure (like failed integer parsing), 0 on missing
2793 match, and 1 on match and successful parsing. "v" is changed only on
2794 successful match.
2795
2796 Function "lib/version.c:guestfs_int_version_from_x_y_re"
2797
2798 int
2799 guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v,
2800 const char *str, const pcre2_code *re)
2801
2802 Parses a version from a string, using the specified "re" as regular
2803 expression which must provide (at least) two matches.
2804
2805 Returns -1 on failure (like failed integer parsing), 0 on missing
2806 match, and 1 on match and successful parsing. "v" is changed only on
2807 successful match.
2808
2809 Function "lib/version.c:guestfs_int_version_from_x_y_or_x"
2810
2811 int
2812 guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v,
2813 const char *str)
2814
2815 Parses a version from a string, either looking for a "X.Y" pattern or
2816 considering it as whole integer.
2817
2818 Returns -1 on failure (like failed integer parsing), 0 on missing
2819 match, and 1 on match and successful parsing. "v" is changed only on
2820 successful match.
2821
2822 Function "lib/version.c:guestfs_int_parse_unsigned_int"
2823
2824 int
2825 guestfs_int_parse_unsigned_int (guestfs_h *g, const char *str)
2826
2827 Parse small, unsigned ints, as used in version numbers.
2828
2829 This will fail with an error if trailing characters are found after the
2830 integer.
2831
2832 Returns ≥ 0 on success, or -1 on failure.
2833
2834 File lib/wait.c
2835
2836 Function "lib/wait.c:guestfs_int_waitpid"
2837
2838 int
2839 guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg)
2840
2841 A safe version of waitpid(3) which retries if "EINTR" is returned.
2842
2843 Note: this only needs to be used in the library, or in programs that
2844 install a non-restartable "SIGCHLD" handler (which is not the case for
2845 any current libguestfs virt tools).
2846
2847 If the main program installs a SIGCHLD handler and sets it to be non-
2848 restartable, then what can happen is the library is waiting in a wait
2849 syscall, the child exits, "SIGCHLD" is sent to the process, and the
2850 wait syscall returns "EINTR". Since the library cannot control the
2851 signal handler, we have to instead restart the wait syscall, which is
2852 the purpose of this wrapper.
2853
2854 Function "lib/wait.c:guestfs_int_waitpid_noerror"
2855
2856 void
2857 guestfs_int_waitpid_noerror (pid_t pid)
2858
2859 Like "guestfs_int_waitpid", but ignore errors.
2860
2861 Function "lib/wait.c:guestfs_int_wait4"
2862
2863 int
2864 guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status,
2865 struct rusage *rusage, const char *errmsg)
2866
2867 A safe version of wait4(2) which retries if "EINTR" is returned.
2868
2869 File lib/whole-file.c
2870
2871 Function "lib/whole-file.c:guestfs_int_read_whole_file"
2872
2873 int
2874 guestfs_int_read_whole_file (guestfs_h *g, const char *filename,
2875 char **data_r, size_t *size_r)
2876
2877 Read the whole file "filename" into a memory buffer.
2878
2879 The memory buffer is initialized and returned in "data_r". The size of
2880 the file in bytes is returned in "size_r". The return buffer must be
2881 freed by the caller.
2882
2883 On error this sets the error in the handle and returns -1.
2884
2885 For the convenience of callers, the returned buffer is NUL-terminated
2886 (the NUL is not included in the size).
2887
2888 The file must be a regular, local, trusted file. In particular, do not
2889 use this function to read files that might be under control of an
2890 untrusted user since that will lead to a denial-of-service attack.
2891
2892 Subdirectory common/edit
2893 File common/edit/file-edit.c
2894
2895 This file implements common file editing in a range of utilities
2896 including guestfish(1), virt-edit(1), virt-customize(1) and
2897 virt-builder(1).
2898
2899 It contains the code for both interactive-(editor-)based editing and
2900 non-interactive editing using Perl snippets.
2901
2902 Function "common/edit/file-edit.c:edit_file_editor"
2903
2904 int
2905 edit_file_editor (guestfs_h *g, const char *filename, const char *editor,
2906 const char *backup_extension, int verbose)
2907
2908 Edit "filename" using the specified "editor" application.
2909
2910 If "backup_extension" is not null, then a copy of "filename" is saved
2911 with "backup_extension" appended to its file name.
2912
2913 If "editor" is null, then the $EDITOR environment variable will be
2914 queried for the editor application, leaving "vi" as fallback if not
2915 set.
2916
2917 Returns -1 for failure, 0 on success, 1 if the editor did not change
2918 the file (e.g. the user closed the editor without saving).
2919
2920 Function "common/edit/file-edit.c:edit_file_perl"
2921
2922 int
2923 edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr,
2924 const char *backup_extension, int verbose)
2925
2926 Edit "filename" running the specified "perl_expr" using Perl.
2927
2928 If "backup_extension" is not null, then a copy of "filename" is saved
2929 with "backup_extension" appended to its file name.
2930
2931 Returns -1 for failure, 0 on success.
2932
2933 Subdirectory common/options
2934 File common/options/config.c
2935
2936 This file parses the guestfish configuration file, usually
2937 ~/.libguestfs-tools.rc or /etc/libguestfs-tools.conf.
2938
2939 Note that "parse_config" is called very early, before command line
2940 parsing, before the "verbose" flag has been set, even before the global
2941 handle "g" is opened.
2942
2943 File common/options/decrypt.c
2944
2945 This file implements the decryption of disk images, usually done before
2946 mounting their partitions.
2947
2948 Function "common/options/decrypt.c:make_mapname"
2949
2950 static char *
2951 make_mapname (const char *device)
2952
2953 Make a LUKS map name from the partition or logical volume name, eg.
2954 "/dev/vda2" => "cryptvda2", or "/dev/vg-ssd/lv-root7" =>
2955 "cryptvgssdlvroot7". Note that, in logical volume device names,
2956 c_isalnum() eliminates the "/" separator from between the VG and the
2957 LV, so this mapping is not unique; but for our purposes, it will do.
2958
2959 Function "common/options/decrypt.c:inspect_do_decrypt"
2960
2961 void
2962 inspect_do_decrypt (guestfs_h *g, struct key_store *ks)
2963
2964 Simple implementation of decryption: look for any encrypted partitions
2965 and decrypt them, then rescan for VGs.
2966
2967 File common/options/display-options.c
2968
2969 This file contains common code used to implement --short-options and
2970 --long-options in C virt tools. (The equivalent for OCaml virt tools
2971 is implemented by common/mltools/getopt.ml).
2972
2973 These "hidden" options are used to implement bash tab completion.
2974
2975 Function "common/options/display-options.c:display_short_options"
2976
2977 void
2978 display_short_options (const char *format)
2979
2980 Implements the internal "tool --short-options" flag, which just lists
2981 out the short options available. Used by bash completion.
2982
2983 Function "common/options/display-options.c:display_long_options"
2984
2985 void
2986 display_long_options (const struct option *long_options)
2987
2988 Implements the internal "tool --long-options" flag, which just lists
2989 out the long options available. Used by bash completion.
2990
2991 File common/options/domain.c
2992
2993 Implements the guestfish (and other tools) -d option.
2994
2995 Function "common/options/domain.c:add_libvirt_drives"
2996
2997 int
2998 add_libvirt_drives (guestfs_h *g, const char *guest)
2999
3000 This function is called when a user invokes "guestfish -d guest".
3001
3002 Returns the number of drives added ("> 0"), or -1 for failure.
3003
3004 File common/options/inspect.c
3005
3006 This file implements inspecting the guest and mounting the filesystems
3007 found in the right places. It is used by the guestfish(1) -i option
3008 and some utilities such as virt-cat(1).
3009
3010 Function "common/options/inspect.c:inspect_mount_handle"
3011
3012 void
3013 inspect_mount_handle (guestfs_h *g, struct key_store *ks)
3014
3015 This function implements the -i option.
3016
3017 Function "common/options/inspect.c:print_inspect_prompt"
3018
3019 void
3020 print_inspect_prompt (void)
3021
3022 This function is called only if "inspect_mount_root" was called, and
3023 only after we've printed the prompt in interactive mode.
3024
3025 File common/options/keys.c
3026
3027 Function "common/options/keys.c:read_key"
3028
3029 char *
3030 read_key (const char *param)
3031
3032 Read a passphrase ('Key') from /dev/tty with echo off.
3033
3034 The caller (fish/cmds.c) will call free on the string afterwards.
3035 Based on the code in cryptsetup file lib/utils.c.
3036
3037 File common/options/options.c
3038
3039 This file contains common options parsing code used by guestfish and
3040 many other tools which share a common options syntax.
3041
3042 For example, guestfish, virt-cat, virt-ls etc all support the -a
3043 option, and that is handled in all of those tools using a macro
3044 "OPTION_a" defined in fish/options.h.
3045
3046 There are a lot of common global variables used, "drvs" accumulates the
3047 list of drives, "verbose" for the -v flag, and many more.
3048
3049 Function "common/options/options.c:option_a"
3050
3051 void
3052 option_a (const char *arg, const char *format, int blocksize,
3053 struct drv **drvsp)
3054
3055 Handle the guestfish -a option on the command line.
3056
3057 Function "common/options/options.c:option_d"
3058
3059 void
3060 option_d (const char *arg, struct drv **drvsp)
3061
3062 Handle the -d option when passed on the command line.
3063
3064 Function "common/options/options.c:display_mountpoints_on_failure"
3065
3066 static void
3067 display_mountpoints_on_failure (const char *mp_device,
3068 const char *user_supplied_options)
3069
3070 If the -m option fails on any command, display a useful error message
3071 listing the mountpoints.
3072
3073 File common/options/uri.c
3074
3075 This file implements URI parsing for the -a option, in many utilities
3076 including guestfish(1), virt-cat(1), virt-builder(1),
3077 virt-customize(1), etc.
3078
3079 Subdirectory common/parallel
3080 File common/parallel/domains.c
3081
3082 This file is used by "virt-df" and some of the other tools when they
3083 are implicitly asked to operate over all libvirt domains (VMs), for
3084 example when "virt-df" is called without specifying any particular disk
3085 image.
3086
3087 It hides the complexity of querying the list of domains from libvirt.
3088
3089 Function "common/parallel/domains.c:free_domains"
3090
3091 void
3092 free_domains (void)
3093
3094 Frees up everything allocated by "get_all_libvirt_domains".
3095
3096 Function "common/parallel/domains.c:get_all_libvirt_domains"
3097
3098 void
3099 get_all_libvirt_domains (const char *libvirt_uri)
3100
3101 Read all libguest guests into the global variables "domains" and
3102 "nr_domains". The guests are ordered by name. This exits on any
3103 error.
3104
3105 File common/parallel/estimate-max-threads.c
3106
3107 Function "common/parallel/estimate-max-threads.c:estimate_max_threads"
3108
3109 size_t
3110 estimate_max_threads (void)
3111
3112 This function uses the output of "free -m" to estimate how many
3113 libguestfs appliances could be safely started in parallel. Note that
3114 it always returns ≥ 1.
3115
3116 Function "common/parallel/estimate-max-threads.c:read_line_from"
3117
3118 static char *
3119 read_line_from (const char *cmd)
3120
3121 Run external command and read the first line of output.
3122
3123 File common/parallel/parallel.c
3124
3125 This file is used by "virt-df" and some of the other tools when they
3126 need to run multiple parallel libguestfs instances to operate on a
3127 large number of libvirt domains efficiently.
3128
3129 It implements a multithreaded work queue. In addition it reorders the
3130 output so the output still appears in the same order as the input (ie.
3131 still ordered alphabetically).
3132
3133 Function "common/parallel/parallel.c:start_threads"
3134
3135 int
3136 start_threads (size_t option_P, guestfs_h *options_handle, work_fn work)
3137
3138 Run the threads and work through the global list of libvirt domains.
3139
3140 "option_P" is whatever the user passed in the -P option, or 0 if the
3141 user didn't use the -P option (in which case the number of threads is
3142 chosen heuristically).
3143
3144 "options_handle" (which may be "NULL") is the global guestfs handle
3145 created by the options mini-library.
3146
3147 The work function ("work") should do the work (inspecting the domain,
3148 etc.) on domain index "i". However it must not print out any result
3149 directly. Instead it prints anything it needs to the supplied "FILE
3150 *". The work function should return 0 on success or -1 on error.
3151
3152 The "start_threads" function returns 0 if all work items completed
3153 successfully, or -1 if there was an error.
3154
3155 Subdirectory common/progress
3156 File common/progress/progress.c
3157
3158 This file implements the progress bar in guestfish(1), virt-resize(1)
3159 and virt-sparsify(1).
3160
3161 Function "common/progress/progress.c:progress_bar_init"
3162
3163 struct progress_bar *
3164 progress_bar_init (unsigned flags)
3165
3166 Initialize a progress bar struct.
3167
3168 It is intended that you can reuse the same struct for multiple commands
3169 (but only in a single thread). Call "progress_bar_reset" before each
3170 new command.
3171
3172 Function "common/progress/progress.c:progress_bar_free"
3173
3174 void
3175 progress_bar_free (struct progress_bar *bar)
3176
3177 Free a progress bar struct.
3178
3179 Function "common/progress/progress.c:progress_bar_reset"
3180
3181 void
3182 progress_bar_reset (struct progress_bar *bar)
3183
3184 This function should be called just before you issue any command.
3185
3186 Function "common/progress/progress.c:estimate_remaining_time"
3187
3188 static double
3189 estimate_remaining_time (struct progress_bar *bar, double ratio)
3190
3191 Return remaining time estimate (in seconds) for current call.
3192
3193 This returns the running mean estimate of remaining time, but if the
3194 latest estimate of total time is greater than two s.d.'s from the
3195 running mean then we don't print anything because we're not confident
3196 that the estimate is meaningful. (Returned value is <0.0 when nothing
3197 should be printed).
3198
3199 Function "common/progress/progress.c:progress_bar_set"
3200
3201 void
3202 progress_bar_set (struct progress_bar *bar,
3203 uint64_t position, uint64_t total)
3204
3205 Set the position of the progress bar.
3206
3207 This should be called from a "GUESTFS_EVENT_PROGRESS" event callback.
3208
3209 Subdirectory common/qemuopts
3210 File common/qemuopts/qemuopts-tests.c
3211
3212 Unit tests of internal functions.
3213
3214 These tests may use a libguestfs handle, but must not launch the
3215 handle. Also, avoid long-running tests.
3216
3217 File common/qemuopts/qemuopts.c
3218
3219 Mini-library for writing qemu command lines and qemu config files.
3220
3221 There are some shortcomings with the model used for qemu options which
3222 aren't clear until you try to convert options into a configuration
3223 file. However if we attempted to model the options in more detail then
3224 this library would be both very difficult to use and incompatible with
3225 older versions of qemu. Hopefully the current model is a decent
3226 compromise.
3227
3228 For reference here are the problems:
3229
3230 • There's inconsistency in qemu between options and config file, eg.
3231 "-smp 4" becomes:
3232
3233 [smp-opts]
3234 cpus = "4"
3235
3236 • Similar to the previous point, you can write either "-smp 4" or
3237 "-smp cpus=4" (although this won't work in very old qemu). When
3238 generating a config file you need to know the implicit key name.
3239
3240 • In "-opt key=value,..." the "key" is really a tree/array specifier.
3241 The way this works is complicated but hinted at here:
3242 http://git.qemu.org/?p=qemu.git;a=blob;f=util/keyval.c;h=93d5db6b590427e412dfb172f1c406d6dd8958c1;hb=HEAD
3243
3244 • Some options are syntactic sugar. eg. "-kernel foo" is sugar for
3245 "-machine kernel=foo".
3246
3247 Function "common/qemuopts/qemuopts.c:qemuopts_create"
3248
3249 struct qemuopts *
3250 qemuopts_create (void)
3251
3252 Create an empty list of qemu options.
3253
3254 The caller must eventually free the list by calling "qemuopts_free".
3255
3256 Returns "NULL" on error, setting "errno".
3257
3258 Function "common/qemuopts/qemuopts.c:qemuopts_free"
3259
3260 void
3261 qemuopts_free (struct qemuopts *qopts)
3262
3263 Free the list of qemu options.
3264
3265 Function "common/qemuopts/qemuopts.c:qemuopts_add_flag"
3266
3267 int
3268 qemuopts_add_flag (struct qemuopts *qopts, const char *flag)
3269
3270 Add a command line flag which has no argument. eg:
3271
3272 qemuopts_add_flag (qopts, "-no-user-config");
3273
3274 Returns 0 on success. Returns -1 on error, setting "errno".
3275
3276 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg"
3277
3278 int
3279 qemuopts_add_arg (struct qemuopts *qopts, const char *flag, const char *value)
3280
3281 Add a command line flag which has a single argument. eg:
3282
3283 qemuopts_add_arg (qopts, "-m", "1024");
3284
3285 Don't use this if the argument is a comma-separated list, since quoting
3286 will not be done properly. See "qemuopts_add_arg_list".
3287
3288 Returns 0 on success. Returns -1 on error, setting "errno".
3289
3290 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_format"
3291
3292 int
3293 qemuopts_add_arg_format (struct qemuopts *qopts, const char *flag,
3294 const char *fs, ...)
3295
3296 Add a command line flag which has a single formatted argument. eg:
3297
3298 qemuopts_add_arg_format (qopts, "-m", "%d", 1024);
3299
3300 Don't use this if the argument is a comma-separated list, since quoting
3301 will not be done properly. See "qemuopts_add_arg_list".
3302
3303 Returns 0 on success. Returns -1 on error, setting "errno".
3304
3305 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_noquote"
3306
3307 int
3308 qemuopts_add_arg_noquote (struct qemuopts *qopts, const char *flag,
3309 const char *value)
3310
3311 This is like "qemuopts_add_arg" except that no quoting is done on the
3312 value.
3313
3314 For "qemuopts_to_script" and "qemuopts_to_channel", this means that
3315 neither shell quoting nor qemu comma quoting is done on the value.
3316
3317 For "qemuopts_to_argv" this means that qemu comma quoting is not done.
3318
3319 "qemuopts_to_config*" will fail.
3320
3321 You should use this with great care.
3322
3323 Function "common/qemuopts/qemuopts.c:qemuopts_start_arg_list"
3324
3325 int
3326 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
3327
3328 Start an argument that takes a comma-separated list of fields.
3329
3330 Typical usage is like this (with error handling omitted):
3331
3332 qemuopts_start_arg_list (qopts, "-drive");
3333 qemuopts_append_arg_list (qopts, "file=foo");
3334 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
3335 qemuopts_end_arg_list (qopts);
3336
3337 which would construct "-drive file=foo,if=ide"
3338
3339 See also "qemuopts_add_arg_list" for a way to do simple cases in one
3340 call.
3341
3342 Returns 0 on success. Returns -1 on error, setting "errno".
3343
3344 Function "common/qemuopts/qemuopts.c:qemuopts_add_arg_list"
3345
3346 int
3347 qemuopts_add_arg_list (struct qemuopts *qopts, const char *flag,
3348 const char *elem0, ...)
3349
3350 Add a command line flag which has a list of arguments. eg:
3351
3352 qemuopts_add_arg_list (qopts, "-drive", "file=foo", "if=ide", NULL);
3353
3354 This is turned into a comma-separated list, like: "-drive
3355 file=foo,if=ide". Note that this handles qemu quoting properly, so
3356 individual elements may contain commas and this will do the right
3357 thing.
3358
3359 Returns 0 on success. Returns -1 on error, setting "errno".
3360
3361 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary"
3362
3363 int
3364 qemuopts_set_binary (struct qemuopts *qopts, const char *binary)
3365
3366 Set the qemu binary name.
3367
3368 Returns 0 on success. Returns -1 on error, setting "errno".
3369
3370 Function "common/qemuopts/qemuopts.c:qemuopts_set_binary_by_arch"
3371
3372 int
3373 qemuopts_set_binary_by_arch (struct qemuopts *qopts, const char *arch)
3374
3375 Set the qemu binary name to "qemu-system-[arch]".
3376
3377 As a special case if "arch" is "NULL", the binary is set to the KVM
3378 binary for the current host architecture:
3379
3380 qemuopts_set_binary_by_arch (qopts, NULL);
3381
3382 Returns 0 on success. Returns -1 on error, setting "errno".
3383
3384 Function "common/qemuopts/qemuopts.c:qemuopts_to_script"
3385
3386 int
3387 qemuopts_to_script (struct qemuopts *qopts, const char *filename)
3388
3389 Write the qemu options to a script.
3390
3391 "qemuopts_set_binary*" must be called first.
3392
3393 The script file will start with "#!/bin/sh" and will be chmod to mode
3394 0755.
3395
3396 Returns 0 on success. Returns -1 on error, setting "errno".
3397
3398 Function "common/qemuopts/qemuopts.c:shell_quote"
3399
3400 static void
3401 shell_quote (const char *str, FILE *fp)
3402
3403 Print "str" to "fp", shell-quoting it if necessary.
3404
3405 Function "common/qemuopts/qemuopts.c:shell_and_comma_quote"
3406
3407 static void
3408 shell_and_comma_quote (const char *str, FILE *fp)
3409
3410 Print "str" to "fp" doing both shell and qemu comma quoting.
3411
3412 Function "common/qemuopts/qemuopts.c:qemuopts_to_channel"
3413
3414 int
3415 qemuopts_to_channel (struct qemuopts *qopts, FILE *fp)
3416
3417 Write the qemu options to a "FILE *fp".
3418
3419 "qemuopts_set_binary*" must be called first.
3420
3421 Only the qemu command line is written. The caller may need to add
3422 "#!/bin/sh" and may need to chmod the resulting file to 0755.
3423
3424 Returns 0 on success. Returns -1 on error, setting "errno".
3425
3426 Function "common/qemuopts/qemuopts.c:qemuopts_to_argv"
3427
3428 char **
3429 qemuopts_to_argv (struct qemuopts *qopts)
3430
3431 Return a NULL-terminated argument list, of the kind that can be passed
3432 directly to execv(3).
3433
3434 "qemuopts_set_binary*" must be called first. It will be returned as
3435 "argv[0]" in the returned list.
3436
3437 The list of strings and the strings themselves must be freed by the
3438 caller.
3439
3440 Returns "NULL" on error, setting "errno".
3441
3442 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_file"
3443
3444 int
3445 qemuopts_to_config_file (struct qemuopts *qopts, const char *filename)
3446
3447 Write the qemu options to a qemu config file, suitable for reading in
3448 using "qemu -readconfig filename".
3449
3450 Note that qemu config files have limitations on content and quoting, so
3451 not all qemuopts structs can be written (this function returns an error
3452 in these cases). For more information see
3453 https://habkost.net/posts/2016/12/qemu-apis-qemuopts.html
3454 https://bugs.launchpad.net/qemu/+bug/1686364
3455
3456 Also, command line argument names and config file sections sometimes
3457 have different names. For example the equivalent of "-m 1024" is:
3458
3459 [memory]
3460 size = "1024"
3461
3462 This code does not attempt to convert between the two forms. You just
3463 need to know how to do that yourself.
3464
3465 Returns 0 on success. Returns -1 on error, setting "errno".
3466
3467 Function "common/qemuopts/qemuopts.c:qemuopts_to_config_channel"
3468
3469 int
3470 qemuopts_to_config_channel (struct qemuopts *qopts, FILE *fp)
3471
3472 Same as "qemuopts_to_config_file", but this writes to a "FILE *fp".
3473
3474 Subdirectory common/utils
3475 File common/utils/cleanups.c
3476
3477 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3478 They are implemented using the "__attribute__((cleanup))" feature of
3479 gcc and clang. Typical usage is:
3480
3481 fn ()
3482 {
3483 CLEANUP_FREE char *str = NULL;
3484 str = safe_asprintf (g, "foo");
3485 // str is freed automatically when the function returns
3486 }
3487
3488 There are a few catches to be aware of with the cleanup mechanism:
3489
3490 • If a cleanup variable is not initialized, then you can end up
3491 calling free(3) with an undefined value, resulting in the program
3492 crashing. For this reason, you should usually initialize every
3493 cleanup variable with something, eg. "NULL"
3494
3495 • Don't mark variables holding return values as cleanup variables.
3496
3497 • The main() function shouldn't use cleanup variables since it is
3498 normally exited by calling exit(3), and that doesn't call the
3499 cleanup handlers.
3500
3501 The functions in this file are used internally by the "CLEANUP_*"
3502 macros. Don't call them directly.
3503
3504 File common/utils/gnulib-cleanups.c
3505
3506 Libguestfs uses "CLEANUP_*" macros to simplify temporary allocations.
3507 They are implemented using the "__attribute__((cleanup))" feature of
3508 gcc and clang. Typical usage is:
3509
3510 fn ()
3511 {
3512 CLEANUP_FREE char *str = NULL;
3513 str = safe_asprintf (g, "foo");
3514 // str is freed automatically when the function returns
3515 }
3516
3517 There are a few catches to be aware of with the cleanup mechanism:
3518
3519 • If a cleanup variable is not initialized, then you can end up
3520 calling free(3) with an undefined value, resulting in the program
3521 crashing. For this reason, you should usually initialize every
3522 cleanup variable with something, eg. "NULL"
3523
3524 • Don't mark variables holding return values as cleanup variables.
3525
3526 • The main() function shouldn't use cleanup variables since it is
3527 normally exited by calling exit(3), and that doesn't call the
3528 cleanup handlers.
3529
3530 The functions in this file are used internally by the "CLEANUP_*"
3531 macros. Don't call them directly.
3532
3533 File common/utils/guestfs-utils.h
3534
3535 This header file is included in all "frontend" parts of libguestfs,
3536 namely the library, non-C language bindings, virt tools and tests.
3537
3538 The daemon does not use this header. If you need a place to put
3539 something shared with absolutely everything including the daemon, put
3540 it in lib/guestfs-internal-all.h
3541
3542 If a definition is only needed by a single component of libguestfs (eg.
3543 just the library, or just a single virt tool) then it should not be
3544 here!
3545
3546 File common/utils/libxml2-writer-macros.h
3547
3548 These macros make it easier to write XML. To use them correctly you
3549 must be aware of these assumptions:
3550
3551 • The "xmlTextWriterPtr" is called "xo". It is used implicitly by
3552 all the macros.
3553
3554 • On failure, a function called "xml_error" is called which you must
3555 define (usually as a macro). You must use "CLEANUP_*" macros in
3556 your functions if you want correct cleanup of local variables along
3557 the error path.
3558
3559 • All the "bad" casting is hidden inside the macros.
3560
3561 Definition "common/utils/libxml2-writer-macros.h:start_element"
3562
3563 #define start_element
3564
3565 To define an XML element use:
3566
3567 start_element ("name") {
3568 ...
3569 } end_element ();
3570
3571 which produces "<name>...</name>"
3572
3573 Definition "common/utils/libxml2-writer-macros.h:empty_element"
3574
3575 #define empty_element
3576
3577 To define an empty element:
3578
3579 empty_element ("name");
3580
3581 which produces "<name/>"
3582
3583 Definition "common/utils/libxml2-writer-macros.h:single_element"
3584
3585 #define single_element
3586
3587 To define a single element with no attributes containing some text:
3588
3589 single_element ("name", text);
3590
3591 which produces "<name>text</name>"
3592
3593 Definition "common/utils/libxml2-writer-macros.h:single_element_format"
3594
3595 #define single_element_format
3596
3597 To define a single element with no attributes containing some text
3598 using a format string:
3599
3600 single_element_format ("cores", "%d", nr_cores);
3601
3602 which produces "<cores>4</cores>"
3603
3604 Definition "common/utils/libxml2-writer-macros.h:attribute"
3605
3606 #define attribute
3607
3608 To define an XML element with attributes, use:
3609
3610 start_element ("name") {
3611 attribute ("foo", "bar");
3612 attribute_format ("count", "%d", count);
3613 ...
3614 } end_element ();
3615
3616 which produces "<name foo="bar" count="123">...</name>"
3617
3618 Definition "common/utils/libxml2-writer-macros.h:attribute_ns"
3619
3620 #define attribute_ns
3621
3622 "attribute_ns (prefix, key, namespace_uri, value)" defines a namespaced
3623 attribute.
3624
3625 Definition "common/utils/libxml2-writer-macros.h:string"
3626
3627 #define string
3628
3629 To define a verbatim string, use:
3630
3631 string ("hello");
3632
3633 Definition "common/utils/libxml2-writer-macros.h:string_format"
3634
3635 #define string_format
3636
3637 To define a verbatim string using a format string, use:
3638
3639 string ("%s, world", greeting);
3640
3641 Definition "common/utils/libxml2-writer-macros.h:base64"
3642
3643 #define base64
3644
3645 To write a string encoded as base64:
3646
3647 base64 (data, size);
3648
3649 Definition "common/utils/libxml2-writer-macros.h:comment"
3650
3651 #define comment
3652
3653 To define a comment in the XML, use:
3654
3655 comment ("number of items = %d", nr_items);
3656
3657 File common/utils/stringlists-utils.c
3658
3659 Utility functions used by the library, tools and language bindings.
3660
3661 These functions must not call internal library functions such as
3662 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3663
3664 Function "common/utils/stringlists-utils.c:guestfs_int_split_string"
3665
3666 char **
3667 guestfs_int_split_string (char sep, const char *str)
3668
3669 Split string at separator character "sep", returning the list of
3670 strings. Returns "NULL" on memory allocation failure.
3671
3672 Note (assuming "sep" is ":"):
3673
3674 "str == NULL"
3675 aborts
3676
3677 "str == """
3678 returns "[]"
3679
3680 "str == "abc""
3681 returns "["abc"]"
3682
3683 "str == ":""
3684 returns "["", ""]"
3685
3686 File common/utils/utils.c
3687
3688 Utility functions used by the library, tools and language bindings.
3689
3690 These functions must not call internal library functions such as
3691 "safe_*", "error" or "perrorf", or any "guestfs_int_*".
3692
3693 Function "common/utils/utils.c:guestfs_int_replace_string"
3694
3695 char *
3696 guestfs_int_replace_string (const char *str, const char *s1, const char *s2)
3697
3698 Replace every instance of "s1" appearing in "str" with "s2". A newly
3699 allocated string is returned which must be freed by the caller. If
3700 allocation fails this can return "NULL".
3701
3702 For example:
3703
3704 replace_string ("abcabb", "ab", "a");
3705
3706 would return "acab".
3707
3708 Function "common/utils/utils.c:guestfs_int_exit_status_to_string"
3709
3710 char *
3711 guestfs_int_exit_status_to_string (int status, const char *cmd_name,
3712 char *buffer, size_t buflen)
3713
3714 Translate a wait/system exit status into a printable string.
3715
3716 Function "common/utils/utils.c:guestfs_int_random_string"
3717
3718 int
3719 guestfs_int_random_string (char *ret, size_t len)
3720
3721 Return a random string of characters.
3722
3723 Notes:
3724
3725 • The "ret" buffer must have length "len+1" in order to store the
3726 final "\0" character.
3727
3728 • There is about 5 bits of randomness per output character (so about
3729 "5*len" bits of randomness in the resulting string).
3730
3731 Function "common/utils/utils.c:guestfs_int_drive_name"
3732
3733 char *
3734 guestfs_int_drive_name (size_t index, char *ret)
3735
3736 This turns a drive index (eg. 27) into a drive name (eg. "ab").
3737
3738 Drive indexes count from 0. The return buffer has to be large enough
3739 for the resulting string, and the returned pointer points to the *end*
3740 of the string.
3741
3742 https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
3743
3744 Function "common/utils/utils.c:guestfs_int_drive_index"
3745
3746 ssize_t
3747 guestfs_int_drive_index (const char *name)
3748
3749 The opposite of "guestfs_int_drive_name". Take a string like "ab" and
3750 return the index (eg 27).
3751
3752 Note that you must remove any prefix such as "hd", "sd" etc, or any
3753 partition number before calling the function.
3754
3755 Function "common/utils/utils.c:guestfs_int_is_true"
3756
3757 int
3758 guestfs_int_is_true (const char *str)
3759
3760 Similar to "Tcl_GetBoolean".
3761
3762 Function "common/utils/utils.c:guestfs_int_string_is_valid"
3763
3764 bool
3765 guestfs_int_string_is_valid (const char *str,
3766 size_t min_length, size_t max_length,
3767 int flags, const char *extra)
3768
3769 Check a string for validity, that it contains only certain characters,
3770 and minimum and maximum length. This function is usually wrapped in a
3771 VALID_* macro, see lib/drives.c for an example.
3772
3773 "str" is the string to check.
3774
3775 "min_length" and "max_length" are the minimum and maximum length
3776 checks. 0 means no check.
3777
3778 The flags control:
3779
3780 "VALID_FLAG_ALPHA"
3781 7-bit ASCII-only alphabetic characters are permitted.
3782
3783 "VALID_FLAG_DIGIT"
3784 7-bit ASCII-only digits are permitted.
3785
3786 "extra" is a set of extra characters permitted, in addition to
3787 alphabetic and/or digits. ("extra = NULL" for no extra).
3788
3789 Returns boolean "true" if the string is valid (passes all the tests),
3790 or "false" if not.
3791
3792 Function "common/utils/utils.c:guestfs_int_fadvise_normal"
3793
3794 void
3795 guestfs_int_fadvise_normal (int fd)
3796
3797 Hint that we will read or write the file descriptor normally.
3798
3799 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3800 and sets the per-file number of readahead pages to equal the block
3801 device readahead setting.
3802
3803 It's OK to call this on a non-file since we ignore failure as it is
3804 only a hint.
3805
3806 Function "common/utils/utils.c:guestfs_int_fadvise_sequential"
3807
3808 void
3809 guestfs_int_fadvise_sequential (int fd)
3810
3811 Hint that we will read or write the file descriptor sequentially.
3812
3813 On Linux, this clears the "FMODE_RANDOM" flag on the file [see below]
3814 and sets the per-file number of readahead pages to twice the block
3815 device readahead setting.
3816
3817 It's OK to call this on a non-file since we ignore failure as it is
3818 only a hint.
3819
3820 Function "common/utils/utils.c:guestfs_int_fadvise_random"
3821
3822 void
3823 guestfs_int_fadvise_random (int fd)
3824
3825 Hint that we will read or write the file descriptor randomly.
3826
3827 On Linux, this sets the "FMODE_RANDOM" flag on the file. The effect of
3828 this flag is to:
3829
3830 • Disable normal sequential file readahead.
3831
3832 • If any read of the file is done which misses in the page cache, 2MB
3833 are read into the page cache. [I think - I'm not sure I totally
3834 understand what this is doing]
3835
3836 It's OK to call this on a non-file since we ignore failure as it is
3837 only a hint.
3838
3839 Function "common/utils/utils.c:guestfs_int_fadvise_noreuse"
3840
3841 void
3842 guestfs_int_fadvise_noreuse (int fd)
3843
3844 Hint that we will access the data only once.
3845
3846 On Linux, this does nothing.
3847
3848 It's OK to call this on a non-file since we ignore failure as it is
3849 only a hint.
3850
3851 Function "common/utils/utils.c:guestfs_int_fadvise_dontneed"
3852
3853 void
3854 guestfs_int_fadvise_dontneed (int fd)
3855
3856 Hint that we will not access the data in the near future.
3857
3858 On Linux, this immediately writes out any dirty pages in the page cache
3859 and then invalidates (drops) all pages associated with this file from
3860 the page cache. Apparently it does this even if the file is opened or
3861 being used by other processes. This setting is not persistent; if you
3862 subsequently read the file it will be cached in the page cache as
3863 normal.
3864
3865 It's OK to call this on a non-file since we ignore failure as it is
3866 only a hint.
3867
3868 Function "common/utils/utils.c:guestfs_int_fadvise_willneed"
3869
3870 void
3871 guestfs_int_fadvise_willneed (int fd)
3872
3873 Hint that we will access the data in the near future.
3874
3875 On Linux, this immediately reads the whole file into the page cache.
3876 This setting is not persistent; subsequently pages may be dropped from
3877 the page cache as normal.
3878
3879 It's OK to call this on a non-file since we ignore failure as it is
3880 only a hint.
3881
3882 Function "common/utils/utils.c:guestfs_int_shell_unquote"
3883
3884 char *
3885 guestfs_int_shell_unquote (const char *str)
3886
3887 Unquote a shell-quoted string.
3888
3889 Augeas passes strings to us which may be quoted, eg. if they come from
3890 files in /etc/sysconfig. This function can do simple unquoting of
3891 these strings.
3892
3893 Note this function does not do variable substitution, since that is
3894 impossible without knowing the file context and indeed the environment
3895 under which the shell script is run. Configuration files should not
3896 use complex quoting.
3897
3898 "str" is the input string from Augeas, a string that may be single- or
3899 double-quoted or may not be quoted. The returned string is unquoted,
3900 and must be freed by the caller. "NULL" is returned on error and
3901 "errno" is set accordingly.
3902
3903 For information on double-quoting in bash, see
3904 https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html
3905
3906 Function "common/utils/utils.c:guestfs_int_is_reg"
3907
3908 int
3909 guestfs_int_is_reg (int64_t mode)
3910
3911 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3912 field represents a regular file.
3913
3914 Function "common/utils/utils.c:guestfs_int_is_dir"
3915
3916 int
3917 guestfs_int_is_dir (int64_t mode)
3918
3919 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3920 field represents a directory.
3921
3922 Function "common/utils/utils.c:guestfs_int_is_chr"
3923
3924 int
3925 guestfs_int_is_chr (int64_t mode)
3926
3927 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3928 field represents a char device.
3929
3930 Function "common/utils/utils.c:guestfs_int_is_blk"
3931
3932 int
3933 guestfs_int_is_blk (int64_t mode)
3934
3935 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3936 field represents a block device.
3937
3938 Function "common/utils/utils.c:guestfs_int_is_fifo"
3939
3940 int
3941 guestfs_int_is_fifo (int64_t mode)
3942
3943 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3944 field represents a named pipe (FIFO).
3945
3946 Function "common/utils/utils.c:guestfs_int_is_lnk"
3947
3948 int
3949 guestfs_int_is_lnk (int64_t mode)
3950
3951 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3952 field represents a symbolic link.
3953
3954 Function "common/utils/utils.c:guestfs_int_is_sock"
3955
3956 int
3957 guestfs_int_is_sock (int64_t mode)
3958
3959 Return true if the "guestfs_statns" or "guestfs_lstatns" "st_mode"
3960 field represents a Unix domain socket.
3961
3962 Function "common/utils/utils.c:guestfs_int_full_path"
3963
3964 char *
3965 guestfs_int_full_path (const char *dir, const char *name)
3966
3967 Concatenate "dir" and "name" to create a path. This correctly handles
3968 the case of concatenating "/" + "filename" as well as "/dir" +
3969 "filename". "name" may be "NULL".
3970
3971 The caller must free the returned path.
3972
3973 This function sets "errno" and returns "NULL" on error.
3974
3975 Function "common/utils/utils.c:guestfs_int_hexdump"
3976
3977 void
3978 guestfs_int_hexdump (const void *data, size_t len, FILE *fp)
3979
3980 Hexdump a block of memory to "FILE *", used for debugging.
3981
3982 Function "common/utils/utils.c:guestfs_int_strerror"
3983
3984 const char *
3985 guestfs_int_strerror (int errnum, char *buf, size_t buflen)
3986
3987 Thread-safe strerror_r.
3988
3989 This is a wrapper around the two variants of strerror_r(3) in glibc
3990 since it is hard to use correctly (RHBZ#2030396).
3991
3992 The buffer passed in should be large enough to store the error message
3993 (256 chars at least) and should be non-static. Note that the buffer
3994 might not be used, use the return value.
3995
3996 Subdirectory common/visit
3997 File common/visit/visit.c
3998
3999 This file contains a recursive function for visiting all files and
4000 directories in a guestfs filesystem.
4001
4002 Adapted from
4003 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/
4004
4005 Function "common/visit/visit.c:visit"
4006
4007 int
4008 visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque)
4009
4010 Visit every file and directory in a guestfs filesystem, starting at
4011 "dir".
4012
4013 "dir" may be "/" to visit the entire filesystem, or may be some
4014 subdirectory. Symbolic links are not followed.
4015
4016 The visitor function "f" is called once for every directory and every
4017 file. The parameters passed to "f" include the current directory name,
4018 the current file name (or "NULL" when we're visiting a directory), the
4019 "guestfs_statns" (file permissions etc), and the list of extended
4020 attributes of the file. The visitor function may return -1 which
4021 causes the whole recursion to stop with an error.
4022
4023 Also passed to this function is an "opaque" pointer which is passed
4024 through to the visitor function.
4025
4026 Returns 0 if everything went OK, or -1 if there was an error. Error
4027 handling is not particularly well defined. It will either set an error
4028 in the libguestfs handle or print an error on stderr, but there is no
4029 way for the caller to tell the difference.
4030
4031 Subdirectory common/windows
4032 File common/windows/windows.c
4033
4034 This file implements "win:" Windows file path support in guestfish(1).
4035
4036 Function "common/windows/windows.c:is_windows"
4037
4038 int
4039 is_windows (guestfs_h *g, const char *root)
4040
4041 Checks whether "root" is a Windows installation.
4042
4043 This relies on an already being done introspection.
4044
4045 Function "common/windows/windows.c:windows_path"
4046
4047 char *
4048 windows_path (guestfs_h *g, const char *root, const char *path, int readonly)
4049
4050 Resolves "path" as possible Windows path according to "root", giving a
4051 new path that can be used in libguestfs API calls.
4052
4053 Notes:
4054
4055 • "root" must be a Windows installation
4056
4057 • relies on an already being done introspection
4058
4059 • will unmount all the existing mount points and mount the Windows
4060 root (according to "readonly")
4061
4062 • calls exit(3) on memory allocation failures
4063
4064 Subdirectory daemon
4065 File daemon/command.c
4066
4067 This file contains a number of useful functions for running external
4068 commands and capturing their output.
4069
4070 Function "daemon/command.c:commandf"
4071
4072 int
4073 commandf (char **stdoutput, char **stderror, unsigned flags,
4074 const char *name, ...)
4075
4076 Run a command. Optionally capture stdout and stderr as strings.
4077
4078 Returns 0 if the command ran successfully, or -1 if there was any
4079 error.
4080
4081 For a description of the "flags" see "commandrvf".
4082
4083 There is also a macro "command(out,err,name,...)" which calls
4084 "commandf" with "flags=0".
4085
4086 Function "daemon/command.c:commandrf"
4087
4088 int
4089 commandrf (char **stdoutput, char **stderror, unsigned flags,
4090 const char *name, ...)
4091
4092 Same as "command", but we allow the status code from the subcommand to
4093 be non-zero, and return that status code.
4094
4095 We still return -1 if there was some other error.
4096
4097 There is also a macro "commandr(out,err,name,...)" which calls
4098 "commandrf" with "flags=0".
4099
4100 Function "daemon/command.c:commandvf"
4101
4102 int
4103 commandvf (char **stdoutput, char **stderror, unsigned flags,
4104 char const *const *argv)
4105
4106 Same as "command", but passing in an argv array.
4107
4108 There is also a macro "commandv(out,err,argv)" which calls "commandvf"
4109 with "flags=0".
4110
4111 Function "daemon/command.c:commandrvf"
4112
4113 int
4114 commandrvf (char **stdoutput, char **stderror, unsigned flags,
4115 char const* const *argv)
4116
4117 This is a more sane version of system(3) for running external commands.
4118 It uses fork/execvp, so we don't need to worry about quoting of
4119 parameters, and it allows us to capture any error messages in a buffer.
4120
4121 If "stdoutput" is not "NULL", then *stdoutput will return the stdout of
4122 the command as a string.
4123
4124 If "stderror" is not "NULL", then *stderror will return the stderr of
4125 the command. If there is a final \n character, it is removed so you
4126 can use the error string directly in a call to "reply_with_error".
4127
4128 Flags are:
4129
4130 "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR"
4131 For broken external commands that send error messages to stdout
4132 (hello, parted) but that don't have any useful stdout information,
4133 use this flag to capture the error messages in the *stderror
4134 buffer. If using this flag, you should pass "stdoutput=NULL"
4135 because nothing could ever be captured in that buffer.
4136
4137 "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN"
4138 For running external commands on chrooted files correctly (see
4139 https://bugzilla.redhat.com/579608) specifying this flag causes
4140 another process to be forked which chroots into sysroot and just
4141 copies the input file to stdin of the specified command. The file
4142 descriptor is ORed with the flags, and that file descriptor is
4143 always closed by this function. See daemon/hexdump.c for an
4144 example of usage.
4145
4146 There is also a macro "commandrv(out,err,argv)" which calls
4147 "commandrvf" with "flags=0".
4148
4149 File daemon/device-name-translation.c
4150
4151 Function
4152 "daemon/device-name-translation.c:device_name_translation_init"
4153
4154 void
4155 device_name_translation_init (void)
4156
4157 Cache daemon disk mapping.
4158
4159 When the daemon starts up, populate a cache with the contents of
4160 /dev/disk/by-path. It's easiest to use "ls -lv" here since the names
4161 are sorted awkwardly.
4162
4163 Function "daemon/device-name-translation.c:device_name_translation"
4164
4165 char *
4166 device_name_translation (const char *device)
4167
4168 Perform device name translation.
4169
4170 Libguestfs defines a few standard formats for device names. (see also
4171 "BLOCK DEVICE NAMING" in guestfs(3) and "guestfs_canonical_device_name"
4172 in guestfs(3)). They are:
4173
4174 /dev/sdX[N]
4175 /dev/hdX[N]
4176 /dev/vdX[N]
4177 These mean the Nth partition on the Xth device. Because Linux no
4178 longer enumerates devices in the order they are passed to qemu, we
4179 must translate these by looking up the actual device using
4180 /dev/disk/by-path/
4181
4182 /dev/mdX
4183 /dev/VG/LV
4184 /dev/mapper/...
4185 /dev/dm-N
4186 These are not translated here.
4187
4188 It returns a newly allocated string which the caller must free.
4189
4190 It returns "NULL" on error. Note it does not call "reply_with_*".
4191
4192 We have to open the device and test for "ENXIO", because the device
4193 nodes may exist in the appliance.
4194
4195 File daemon/guestfsd.c
4196
4197 This is the guestfs daemon which runs inside the guestfs appliance.
4198 This file handles start up and connecting back to the library.
4199
4200 Function "daemon/guestfsd.c:shell_quote"
4201
4202 void
4203 shell_quote (const char *str, FILE *fp)
4204
4205 Write "str" to the file "fp", ensuring it is shell quoted.
4206
4207 Function "daemon/guestfsd.c:sysroot_shell_quote"
4208
4209 void
4210 sysroot_shell_quote (const char *path, FILE *fp)
4211
4212 Write "sysroot" + "path" to the file "fp", ensuring it is shell quoted.
4213 The path must be an absolute path.
4214
4215 File daemon/internal.c
4216
4217 Internal functions that are not part of the public API.
4218
4219 File daemon/utils-c.c
4220
4221 Bindings for utility functions.
4222
4223 Note that functions called from OCaml code must never call any of the
4224 "reply*" functions.
4225
4226 File daemon/utils.c
4227
4228 Miscellaneous utility functions used by the daemon.
4229
4230 Function "daemon/utils.c:is_root_device_stat"
4231
4232 static int
4233 is_root_device_stat (struct stat *statbuf)
4234
4235 Return true iff device is the root device (and therefore should be
4236 ignored from the point of view of user calls).
4237
4238 Function "daemon/utils.c:is_device_parameter"
4239
4240 int
4241 is_device_parameter (const char *device)
4242
4243 Parameters marked as "Device", "Dev_or_Path", etc can be passed a block
4244 device name. This function tests if the parameter is a block device
4245 name.
4246
4247 It can also be used in daemon code to test if the string passed as a
4248 "Dev_or_Path" parameter is a device or path.
4249
4250 Function "daemon/utils.c:sysroot_path"
4251
4252 char *
4253 sysroot_path (const char *path)
4254
4255 Turn "/path" into "/sysroot/path".
4256
4257 Returns "NULL" on failure. The caller must check for this and call
4258 "reply_with_perror ("malloc")". The caller must also free the returned
4259 string.
4260
4261 See also the custom %R printf formatter which does shell quoting too.
4262
4263 Function "daemon/utils.c:sysroot_realpath"
4264
4265 char *
4266 sysroot_realpath (const char *path)
4267
4268 Resolve path within sysroot, calling "sysroot_path" on the resolved
4269 path.
4270
4271 Returns "NULL" on failure. The caller must check for this and call
4272 "reply_with_perror ("malloc")". The caller must also free the returned
4273 string.
4274
4275 See also the custom %R printf formatter which does shell quoting too.
4276
4277 Function "daemon/utils.c:is_power_of_2"
4278
4279 int
4280 is_power_of_2 (unsigned long v)
4281
4282 Returns true if "v" is a power of 2.
4283
4284 Uses the algorithm described at
4285 http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2
4286
4287 Function "daemon/utils.c:split_lines_sb"
4288
4289 struct stringsbuf
4290 split_lines_sb (char *str)
4291
4292 Split an output string into a NULL-terminated list of lines, wrapped
4293 into a stringsbuf.
4294
4295 Typically this is used where we have run an external command which has
4296 printed out a list of things, and we want to return an actual list.
4297
4298 The corner cases here are quite tricky. Note in particular:
4299
4300 "" returns "[]"
4301
4302 "\n"
4303 returns "[""]"
4304
4305 "a\nb"
4306 returns "["a"; "b"]"
4307
4308 "a\nb\n"
4309 returns "["a"; "b"]"
4310
4311 "a\nb\n\n"
4312 returns "["a"; "b"; ""]"
4313
4314 The original string is written over and destroyed by this function
4315 (which is usually OK because it's the 'out' string from "command*()").
4316 You can free the original string, because add_string() strdups the
4317 strings.
4318
4319 "argv" in the "struct stringsbuf" will be "NULL" in case of errors.
4320
4321 Function "daemon/utils.c:filter_list"
4322
4323 char **
4324 filter_list (bool (*p) (const char *str), char **strs)
4325
4326 Filter a list of strings. Returns a newly allocated list of only the
4327 strings where "p (str) == true".
4328
4329 Note it does not copy the strings, be careful not to double-free them.
4330
4331 Function "daemon/utils.c:trim"
4332
4333 void
4334 trim (char *str)
4335
4336 Skip leading and trailing whitespace, updating the original string in-
4337 place.
4338
4339 Function "daemon/utils.c:parse_btrfsvol"
4340
4341 int
4342 parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
4343
4344 Parse the mountable descriptor for a btrfs subvolume. Don't call this
4345 directly; it is only used from the stubs.
4346
4347 A btrfs subvolume is given as:
4348
4349 btrfsvol:/dev/sda3/root
4350
4351 where /dev/sda3 is a block device containing a btrfs filesystem, and
4352 root is the name of a subvolume on it. This function is passed the
4353 string following "btrfsvol:".
4354
4355 On success, "mountable->device" and "mountable->volume" must be freed
4356 by the caller.
4357
4358 Function "daemon/utils.c:mountable_to_string"
4359
4360 char *
4361 mountable_to_string (const mountable_t *mountable)
4362
4363 Convert a "mountable_t" back to its string representation
4364
4365 This function can be used in an error path, so must not call
4366 "reply_with_error".
4367
4368 Function "daemon/utils.c:prog_exists"
4369
4370 int
4371 prog_exists (const char *prog)
4372
4373 Check program exists and is executable on $PATH.
4374
4375 Function "daemon/utils.c:random_name"
4376
4377 int
4378 random_name (char *template)
4379
4380 Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
4381 template to contain a randomly named file. Any 'X' characters after
4382 the final '/' in the template are replaced with random characters.
4383
4384 Notes: You should probably use an 8.3 path, so it's compatible with all
4385 filesystems including basic FAT. Also this only substitutes lowercase
4386 ASCII letters and numbers, again for compatibility with lowest common
4387 denominator filesystems.
4388
4389 This doesn't create a file or check whether or not the file exists (it
4390 would be extremely unlikely to exist as long as the RNG is working).
4391
4392 If there is an error, -1 is returned.
4393
4394 Function "daemon/utils.c:udev_settle_file"
4395
4396 void
4397 udev_settle_file (const char *file)
4398
4399 LVM and other commands aren't synchronous, especially when udev is
4400 involved. eg. You can create or remove some device, but the "/dev"
4401 device node won't appear until some time later. This means that you
4402 get an error if you run one command followed by another.
4403
4404 Use "udevadm settle" after certain commands, but don't be too fussed if
4405 it fails.
4406
4407 Function "daemon/utils.c:make_exclude_from_file"
4408
4409 char *
4410 make_exclude_from_file (const char *function, char *const *excludes)
4411
4412 Turn list "excludes" into a temporary file, and return a string
4413 containing the temporary file name. Caller must unlink the file and
4414 free the string.
4415
4416 "function" is the function that invoked this helper, and it is used
4417 mainly for errors/debugging.
4418
4419 Function "daemon/utils.c:read_whole_file"
4420
4421 char *
4422 read_whole_file (const char *filename, size_t *size_r)
4423
4424 Read whole file into dynamically allocated array. If there is an
4425 error, DON'T call reply_with_perror, just return NULL. Returns a
4426 "\0"-terminated string. "size_r" can be specified to get the size of
4427 the returned data.
4428
4429 File daemon/xattr.c
4430
4431 Function "daemon/xattr.c:split_attr_names"
4432
4433 static char **
4434 split_attr_names (char *buf, size_t len)
4435
4436 listxattr(2) returns the string "foo\0bar\0baz" of length "len". (The
4437 last string in the list is \0-terminated but the \0 is not included in
4438 "len").
4439
4440 This function splits it into a regular list of strings.
4441
4442 Note that the returned list contains pointers to the original strings
4443 in "buf" so be careful that you do not double-free them.
4444
4445 Subdirectory fish
4446 File fish/alloc.c
4447
4448 This file implements the guestfish "alloc" and "sparse" commands.
4449
4450 Function "fish/alloc.c:alloc_disk"
4451
4452 int
4453 alloc_disk (const char *filename, const char *size_str, int add, int sparse)
4454
4455 This is the underlying allocation function. It's called from a few
4456 other places in guestfish.
4457
4458 File fish/copy.c
4459
4460 This file implements the guestfish commands "copy-in" and "copy-out".
4461
4462 File fish/destpaths.c
4463
4464 The file handles tab-completion of filesystem paths in guestfish.
4465
4466 File fish/display.c
4467
4468 The file implements the guestfish "display" command, for displaying
4469 graphical files (icons, images) in disk images.
4470
4471 File fish/echo.c
4472
4473 The file implements the guestfish "echo" command.
4474
4475 File fish/edit.c
4476
4477 guestfish "edit" command, suggested by Ján Ondrej.
4478
4479 File fish/events.c
4480
4481 This file implements the guestfish event-related commands, "event",
4482 "delete-event" and "list-events".
4483
4484 File fish/fish.c
4485
4486 guestfish, the guest filesystem shell. This file contains the main
4487 loop and utilities.
4488
4489 Function "fish/fish.c:parse_command_line"
4490
4491 static struct parsed_command
4492 parse_command_line (char *buf, int *exit_on_error_rtn)
4493
4494 Parse a command string, splitting at whitespace, handling '!', '#' etc.
4495 This destructively updates "buf".
4496
4497 "exit_on_error_rtn" is used to pass in the global "exit_on_error"
4498 setting and to return the local setting (eg. if the command begins with
4499 '-').
4500
4501 Returns in "parsed_command.status":
4502
4503 1 got a guestfish command (returned in
4504 "cmd_rtn"/"argv_rtn"/"pipe_rtn")
4505
4506 0 no guestfish command, but otherwise OK
4507
4508 -1 an error
4509
4510 Function "fish/fish.c:parse_quoted_string"
4511
4512 static ssize_t
4513 parse_quoted_string (char *p)
4514
4515 Parse double-quoted strings, replacing backslash escape sequences with
4516 the true character. Since the string is returned in place, the escapes
4517 must make the string shorter.
4518
4519 Function "fish/fish.c:execute_and_inline"
4520
4521 static int
4522 execute_and_inline (const char *cmd, int global_exit_on_error)
4523
4524 Used to handle "<!" (execute command and inline result).
4525
4526 Function "fish/fish.c:issue_command"
4527
4528 int
4529 issue_command (const char *cmd, char *argv[], const char *pipecmd,
4530 int rc_exit_on_error_flag)
4531
4532 Run a command.
4533
4534 "rc_exit_on_error_flag" is the "exit_on_error" flag that we pass to the
4535 remote server (when issuing --remote commands). It does not cause
4536 "issue_command" itself to exit on error.
4537
4538 Function "fish/fish.c:extended_help_message"
4539
4540 void
4541 extended_help_message (void)
4542
4543 Print an extended help message when the user types in an unknown
4544 command for the first command issued. A common case is the user doing:
4545
4546 guestfish disk.img
4547
4548 expecting guestfish to open disk.img (in fact, this tried to run a non-
4549 existent command "disk.img").
4550
4551 Function "fish/fish.c:error_cb"
4552
4553 static void
4554 error_cb (guestfs_h *g, void *data, const char *msg)
4555
4556 Error callback. This replaces the standard libguestfs error handler.
4557
4558 Function "fish/fish.c:free_n_strings"
4559
4560 static void
4561 free_n_strings (char **str, size_t len)
4562
4563 Free strings from a non-NULL terminated "char**".
4564
4565 Function "fish/fish.c:decode_ps1"
4566
4567 static char *
4568 decode_ps1 (const char *str)
4569
4570 Decode "str" into the final printable prompt string.
4571
4572 Function "fish/fish.c:win_prefix"
4573
4574 char *
4575 win_prefix (const char *path)
4576
4577 Resolve the special "win:..." form for Windows-specific paths. The
4578 generated code calls this for all device or path arguments.
4579
4580 The function returns a newly allocated string, and the caller must free
4581 this string; else display an error and return "NULL".
4582
4583 Function "fish/fish.c:file_in"
4584
4585 char *
4586 file_in (const char *arg)
4587
4588 Resolve the special "FileIn" paths ("-" or "-<<END" or filename).
4589
4590 The caller (fish/cmds.c) will call "free_file_in" after the command has
4591 run which should clean up resources.
4592
4593 Function "fish/fish.c:file_out"
4594
4595 char *
4596 file_out (const char *arg)
4597
4598 Resolve the special "FileOut" paths ("-" or filename).
4599
4600 The caller (fish/cmds.c) will call "free (str)" after the command has
4601 run.
4602
4603 Function "fish/fish.c:progress_callback"
4604
4605 void
4606 progress_callback (guestfs_h *g, void *data,
4607 uint64_t event, int event_handle, int flags,
4608 const char *buf, size_t buf_len,
4609 const uint64_t *array, size_t array_len)
4610
4611 Callback which displays a progress bar.
4612
4613 File fish/glob.c
4614
4615 This file implements the guestfish "glob" command.
4616
4617 Function "fish/glob.c:expand_devicename"
4618
4619 static char **
4620 expand_devicename (guestfs_h *g, const char *device)
4621
4622 Glob-expand device patterns, such as "/dev/sd*"
4623 (https://bugzilla.redhat.com/635971).
4624
4625 There is no "guestfs_glob_expand_device" function because the
4626 equivalent can be implemented using functions like
4627 "guestfs_list_devices".
4628
4629 It's not immediately clear what it means to expand a pattern like
4630 "/dev/sd*". Should that include device name translation? Should the
4631 result include partitions as well as devices?
4632
4633 Should "/dev/" + "*" return every possible device and filesystem? How
4634 about VGs? LVs?
4635
4636 To solve this what we do is build up a list of every device, partition,
4637 etc., then glob against that list.
4638
4639 Notes for future work (XXX):
4640
4641 • This doesn't handle device name translation. It wouldn't be too
4642 hard to add.
4643
4644 • Could have an API function for returning all device-like things.
4645
4646 Function "fish/glob.c:add_strings_matching"
4647
4648 static int
4649 add_strings_matching (char **pp, const char *glob,
4650 char ***ret, size_t *size_r)
4651
4652 Using POSIX fnmatch(3), find strings in the list "pp" which match
4653 pattern "glob". Add strings which match to the "ret" array. *size_r
4654 is the current size of the "ret" array, which is updated with the new
4655 size.
4656
4657 Function "fish/glob.c:single_element_list"
4658
4659 static char **
4660 single_element_list (const char *element)
4661
4662 Return a single element list containing "element".
4663
4664 File fish/help.c
4665
4666 The file implements the guestfish "help" command.
4667
4668 Function "fish/help.c:display_help"
4669
4670 int
4671 display_help (const char *cmd, size_t argc, char *argv[])
4672
4673 The "help" command.
4674
4675 This used to just list all commands, but that's not very useful.
4676 Instead display some useful context-sensitive help. This could be
4677 improved if we knew how many drives had been added already, and whether
4678 anything was mounted.
4679
4680 File fish/hexedit.c
4681
4682 This file implements the guestfish "hexedit" command.
4683
4684 File fish/lcd.c
4685
4686 Function "fish/lcd.c:run_lcd"
4687
4688 int
4689 run_lcd (const char *cmd, size_t argc, char *argv[])
4690
4691 guestfish "lcd" command (similar to the "lcd" command in BSD ftp).
4692
4693 File fish/man.c
4694
4695 Function "fish/man.c:run_man"
4696
4697 int
4698 run_man (const char *cmd, size_t argc, char *argv[])
4699
4700 guestfish "man" command
4701
4702 File fish/more.c
4703
4704 This file implements the guestfish "more" command.
4705
4706 File fish/prep.c
4707
4708 This file implements the guestfish -N option for creating pre-prepared
4709 disk layouts.
4710
4711 File fish/rc.c
4712
4713 This file implements guestfish remote (command) support.
4714
4715 Function "fish/rc.c:rc_listen"
4716
4717 void
4718 rc_listen (void)
4719
4720 The remote control server (ie. "guestfish --listen").
4721
4722 Function "fish/rc.c:rc_remote"
4723
4724 int
4725 rc_remote (int pid, const char *cmd, size_t argc, char *argv[],
4726 int exit_on_error)
4727
4728 The remote control client (ie. "guestfish --remote").
4729
4730 File fish/reopen.c
4731
4732 This file implements the guestfish "reopen" command.
4733
4734 File fish/setenv.c
4735
4736 This file implements the guestfish "setenv" and "unsetenv" commands.
4737
4738 File fish/supported.c
4739
4740 This file implements the guestfish "supported" command.
4741
4742 File fish/tilde.c
4743
4744 This file implements tilde ("~") expansion of home directories in
4745 guestfish(1).
4746
4747 Function "fish/tilde.c:try_tilde_expansion"
4748
4749 char *
4750 try_tilde_expansion (char *str)
4751
4752 This is called from the script loop if we find a candidate for
4753 "~username" (tilde-expansion).
4754
4755 Function "fish/tilde.c:expand_home"
4756
4757 static char *
4758 expand_home (char *orig, const char *append)
4759
4760 Return $HOME + append string.
4761
4762 Function "fish/tilde.c:find_home_for_username"
4763
4764 static const char *
4765 find_home_for_username (const char *username, size_t ulen)
4766
4767 Lookup "username" (of length "ulen"), return home directory if found,
4768 or "NULL" if not found.
4769
4770 File fish/time.c
4771
4772 This file implements the guestfish "time" command.
4773
4774 Subdirectory python
4775 File python/handle.c
4776
4777 This file contains a small number of functions that are written by
4778 hand. The majority of the bindings are generated (see
4779 python/actions-*.c).
4780
4782 guestfs(3), guestfs-building(1), guestfs-examples(3),
4783 guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
4784 guestfs-testing(1), libguestfs-test-tool(1),
4785 libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
4786
4788 Richard W.M. Jones ("rjones at redhat dot com")
4789
4791 Copyright (C) 2009-2023 Red Hat Inc.
4792
4794 This library is free software; you can redistribute it and/or modify it
4795 under the terms of the GNU Lesser General Public License as published
4796 by the Free Software Foundation; either version 2 of the License, or
4797 (at your option) any later version.
4798
4799 This library is distributed in the hope that it will be useful, but
4800 WITHOUT ANY WARRANTY; without even the implied warranty of
4801 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
4802 Lesser General Public License for more details.
4803
4804 You should have received a copy of the GNU Lesser General Public
4805 License along with this library; if not, write to the Free Software
4806 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
4807 02110-1301 USA
4808
4810 To get a list of bugs against libguestfs, use this link:
4811 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
4812
4813 To report a new bug against libguestfs, use this link:
4814 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
4815
4816 When reporting a bug, please supply:
4817
4818 • The version of libguestfs.
4819
4820 • Where you got libguestfs (eg. which Linux distro, compiled from
4821 source, etc)
4822
4823 • Describe the bug accurately and give a way to reproduce it.
4824
4825 • Run libguestfs-test-tool(1) and paste the complete, unedited output
4826 into the bug report.
4827
4828
4829
4830libguestfs-1.50.1 2023-02-21 guestfs-hacking(1)