1guestfs-hacking(1)          Virtualization Support          guestfs-hacking(1)
2
3
4

NAME

6       guestfs-hacking - extending and contributing to libguestfs
7

DESCRIPTION

9       This manual page is for hackers who want to extend libguestfs itself.
10

THE SOURCE CODE

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

EXTENDING LIBGUESTFS

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

MISCELLANEOUS TOPICS

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_srcdir)/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

MAINTAINER TASKS

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       ·   Push and pull from Zanata.
822
823           Run:
824
825            zanata push
826
827           to push the latest POT files to Zanata.  Then run:
828
829            ./zanata-pull.sh
830
831           which is a wrapper to pull the latest translated *.po files.
832
833       ·   Consider updating gnulib to latest upstream version.
834
835       ·   Create new stable and development directories under
836           http://libguestfs.org/download.
837
838       ·   Edit website/index.html.in.
839
840       ·   Set the version (in configure.ac) to the new stable version, ie.
841           1.XX.0, and commit it:
842
843            ./localconfigure
844            make distclean -k
845            ./localconfigure
846            make && make dist
847            make maintainer-commit
848            make maintainer-tag
849
850       ·   Create the stable branch in git:
851
852            git branch stable-1.XX
853            git push origin stable-1.XX
854
855       ·   Do a full release of the stable branch.
856
857       ·   Set the version to the next development version and commit that.
858           Optionally do a full release of the development branch.
859

INTERNAL DOCUMENTATION

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

SEE ALSO

4812       guestfs(3), guestfs-building(1), guestfs-examples(3),
4813       guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1),
4814       guestfs-testing(1), libguestfs-test-tool(1),
4815       libguestfs-make-fixed-appliance(1), http://libguestfs.org/.
4816

AUTHORS

4818       Richard W.M. Jones ("rjones at redhat dot com")
4819
4821       Copyright (C) 2009-2020 Red Hat Inc.
4822

LICENSE

4824       This library is free software; you can redistribute it and/or modify it
4825       under the terms of the GNU Lesser General Public License as published
4826       by the Free Software Foundation; either version 2 of the License, or
4827       (at your option) any later version.
4828
4829       This library is distributed in the hope that it will be useful, but
4830       WITHOUT ANY WARRANTY; without even the implied warranty of
4831       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
4832       Lesser General Public License for more details.
4833
4834       You should have received a copy of the GNU Lesser General Public
4835       License along with this library; if not, write to the Free Software
4836       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
4837       02110-1301 USA
4838

BUGS

4840       To get a list of bugs against libguestfs, use this link:
4841       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
4842
4843       To report a new bug against libguestfs, use this link:
4844       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
4845
4846       When reporting a bug, please supply:
4847
4848       ·   The version of libguestfs.
4849
4850       ·   Where you got libguestfs (eg. which Linux distro, compiled from
4851           source, etc)
4852
4853       ·   Describe the bug accurately and give a way to reproduce it.
4854
4855       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
4856           into the bug report.
4857
4858
4859
4860libguestfs-1.42.0                 2020-03-09                guestfs-hacking(1)
Impressum