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