.\" Automatically generated by Podwrapper::Man 1.34.6 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "guestfs-hacking 1" .TH guestfs-hacking 1 "2017-03-08" "libguestfs-1.34.6" "Virtualization Support" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" guestfs\-hacking \- extending and contributing to libguestfs .SH "DESCRIPTION" .IX Header "DESCRIPTION" This manual page is for hackers who want to extend libguestfs itself. .SH "OVERVIEW OF THE SOURCE CODE" .IX Header "OVERVIEW OF THE SOURCE CODE" Libguestfs source is located in the github repository https://github.com/libguestfs/libguestfs .PP Large amounts of boilerplate code in libguestfs (\s-1RPC,\s0 bindings, documentation) are generated. This means that many source files will appear to be missing from a straightforward git checkout. You have to run the generator (\f(CW\*(C`./autogen.sh && make \-C generator\*(C'\fR) in order to create those files. .PP Libguestfs uses an autotools-based build system, with the main files being \fIconfigure.ac\fR and \fIMakefile.am\fR. See \*(L"\s-1THE BUILD SYSTEM\*(R"\s0. .PP The \fIgenerator\fR subdirectory contains the generator, plus files describing the \s-1API. \s0 The \fIsrc\fR subdirectory contains source for the library. The \fIappliance\fR and \fIdaemon\fR subdirectories contain the source for the code that builds the appliance, and the code that runs in the appliance respectively. Other directories are covered in the section \*(L"\s-1SOURCE CODE SUBDIRECTORIES\*(R"\s0 below. .PP Apart from the fact that all \s-1API\s0 entry points go via some generated code, the library is straightforward. (In fact, even the generated code is designed to be readable, and should be read as ordinary code). Some actions run entirely in the library, and are written as C functions in files under \fIsrc\fR. Others are forwarded to the daemon where (after some generated \s-1RPC\s0 marshalling) they appear as C functions in files under \fIdaemon\fR. .PP To build from source, first read the \fIguestfs\-building\fR\|(1). .SH "SOURCE CODE SUBDIRECTORIES" .IX Header "SOURCE CODE SUBDIRECTORIES" There are a lot of subdirectories in the source tree! Which ones should you concentrate on first? \fIsrc\fR and \fIdaemon\fR which contain the source code of the core library. \fIgenerator\fR is the code generator described above, so that is important. The \fIMakefile.am\fR in the root directory will tell you in which order the subdirectories get built. And then if you are looking at a particular tool (eg. \fIv2v\fR) or language binding (eg. \fIpython\fR), go straight to that subdirectory, but remember that if you didn't run the generator yet, then you may find files which appear to be missing. .IP "\fIalign\fR" 4 .IX Item "align" \&\fIvirt\-alignment\-scan\fR\|(1) command and documentation. .IP "\fIappliance\fR" 4 .IX Item "appliance" The libguestfs appliance, build scripts and so on. .IP "\fIbash\fR" 4 .IX Item "bash" Bash tab-completion scripts. .IP "\fIbuild-aux\fR" 4 .IX Item "build-aux" Various build scripts used by autotools. .IP "\fIbuilder\fR" 4 .IX Item "builder" \&\fIvirt\-builder\fR\|(1) command and documentation. .IP "\fIcat\fR" 4 .IX Item "cat" The \fIvirt\-cat\fR\|(1), \fIvirt\-filesystems\fR\|(1), \fIvirt\-log\fR\|(1) and \fIvirt\-ls\fR\|(1) commands and documentation. .IP "\fIcontrib\fR" 4 .IX Item "contrib" Outside contributions, experimental parts. .IP "\fIcustomize\fR" 4 .IX Item "customize" \&\fIvirt\-customize\fR\|(1) command and documentation. .IP "\fIdaemon\fR" 4 .IX Item "daemon" The daemon that runs inside the libguestfs appliance and carries out actions. .IP "\fIdf\fR" 4 .IX Item "df" \&\fIvirt\-df\fR\|(1) command and documentation. .IP "\fIdib\fR" 4 .IX Item "dib" \&\fIvirt\-dib\fR\|(1) command and documentation. .IP "\fIdiff\fR" 4 .IX Item "diff" \&\fIvirt\-diff\fR\|(1) command and documentation. .IP "\fIdocs\fR" 4 .IX Item "docs" Miscellaneous manual pages. .IP "\fIedit\fR" 4 .IX Item "edit" \&\fIvirt\-edit\fR\|(1) command and documentation. .IP "\fIexamples\fR" 4 .IX Item "examples" C \s-1API\s0 example code. .IP "\fIfish\fR" 4 .IX Item "fish" \&\fIguestfish\fR\|(1), the command-line shell, and various shell scripts built on top such as \fIvirt\-copy\-in\fR\|(1), \fIvirt\-copy\-out\fR\|(1), \&\fIvirt\-tar\-in\fR\|(1), \fIvirt\-tar\-out\fR\|(1). .IP "\fIformat\fR" 4 .IX Item "format" \&\fIvirt\-format\fR\|(1) command and documentation. .IP "\fIfuse\fR" 4 .IX Item "fuse" \&\fIguestmount\fR\|(1), \s-1FUSE \s0(userspace filesystem) built on top of libguestfs. .IP "\fIgenerator\fR" 4 .IX Item "generator" The crucially important generator, used to automatically generate large amounts of boilerplate C code for things like \s-1RPC\s0 and bindings. .IP "\fIget-kernel\fR" 4 .IX Item "get-kernel" \&\fIvirt\-get\-kernel\fR\|(1) command and documentation. .IP "\fIgnulib\fR" 4 .IX Item "gnulib" Gnulib is used as a portability library. A copy of gnulib is included under here. .IP "\fIinspector\fR" 4 .IX Item "inspector" \&\fIvirt\-inspector\fR\|(1), the virtual machine image inspector. .IP "\fIlogo\fR" 4 .IX Item "logo" Logo used on the website. The fish is called Arthur by the way. .IP "\fIm4\fR" 4 .IX Item "m4" M4 macros used by autoconf. See \*(L"\s-1THE BUILD SYSTEM\*(R"\s0. .IP "\fImake-fs\fR" 4 .IX Item "make-fs" \&\fIvirt\-make\-fs\fR\|(1) command and documentation. .IP "\fImllib\fR" 4 .IX Item "mllib" Various libraries and common code used by \fIvirt\-resize\fR\|(1) and the other tools which are written in OCaml. .IP "\fIp2v\fR" 4 .IX Item "p2v" \&\fIvirt\-p2v\fR\|(1) command, documentation and scripts for building the virt\-p2v \s-1ISO\s0 or disk image. .IP "\fIpo\fR" 4 .IX Item "po" Translations of simple gettext strings. .IP "\fIpo-docs\fR" 4 .IX Item "po-docs" The build infrastructure and \s-1PO\s0 files for translations of manpages and \&\s-1POD\s0 files. Eventually this will be combined with the \fIpo\fR directory, but that is rather complicated. .IP "\fIrescue\fR" 4 .IX Item "rescue" \&\fIvirt\-rescue\fR\|(1) command and documentation. .IP "\fIresize\fR" 4 .IX Item "resize" \&\fIvirt\-resize\fR\|(1) command and documentation. .IP "\fIsparsify\fR" 4 .IX Item "sparsify" \&\fIvirt\-sparsify\fR\|(1) command and documentation. .IP "\fIsrc\fR" 4 .IX Item "src" Source code to the C library. .IP "\fIsysprep\fR" 4 .IX Item "sysprep" \&\fIvirt\-sysprep\fR\|(1) command and documentation. .IP "\fItests\fR" 4 .IX Item "tests" Tests. .IP "\fItest-data\fR" 4 .IX Item "test-data" Files and other test data used by the tests. .IP "\fItest-tool\fR" 4 .IX Item "test-tool" Test tool for end users to test if their qemu/kernel combination will work with libguestfs. .IP "\fItmp\fR" 4 .IX Item "tmp" Used for temporary files when running the tests (instead of \fI/tmp\fR etc). The reason is so that you can run multiple parallel tests of libguestfs without having one set of tests overwriting the appliance created by another. .IP "\fItools\fR" 4 .IX Item "tools" Command line tools written in Perl (\fIvirt\-win\-reg\fR\|(1) and many others). .IP "\fIutils\fR" 4 .IX Item "utils" Miscellaneous utilities, such as \f(CW\*(C`boot\-benchmark\*(C'\fR. .IP "\fIv2v\fR" 4 .IX Item "v2v" \&\fIvirt\-v2v\fR\|(1) command and documentation. .IP "\fIwebsite\fR" 4 .IX Item "website" The http://libguestfs.org website files. .IP "\fIcsharp\fR" 4 .IX Item "csharp" .PD 0 .IP "\fIerlang\fR" 4 .IX Item "erlang" .IP "\fIgobject\fR" 4 .IX Item "gobject" .IP "\fIgolang\fR" 4 .IX Item "golang" .IP "\fIhaskell\fR" 4 .IX Item "haskell" .IP "\fIjava\fR" 4 .IX Item "java" .IP "\fIlua\fR" 4 .IX Item "lua" .IP "\fIocaml\fR" 4 .IX Item "ocaml" .IP "\fIphp\fR" 4 .IX Item "php" .IP "\fIperl\fR" 4 .IX Item "perl" .IP "\fIpython\fR" 4 .IX Item "python" .IP "\fIruby\fR" 4 .IX Item "ruby" .PD Language bindings. .SH "THE BUILD SYSTEM" .IX Header "THE BUILD SYSTEM" Libguestfs uses the \s-1GNU\s0 autotools build system (autoconf, automake, libtool). .PP The \fI./configure\fR script is generated from \fIconfigure.ac\fR and \&\fIm4/guestfs_*.m4\fR. Most of the configure script is split over many m4 macro files by topic, for example \fIm4/guestfs_daemon.m4\fR deals with the dependencies of the daemon. .PP The job of the top level \fIMakefile.am\fR is mainly to list the subdirectories (\f(CW\*(C`SUBDIRS\*(C'\fR) in the order they should be compiled. .PP \&\fIcommon\-rules.mk\fR is included in every \fIMakefile.am\fR (top level and subdirectories). \fIsubdir\-rules.mk\fR is included only in subdirectory \&\fIMakefile.am\fR files. .PP There are many make targets. Use this command to list them all: .PP .Vb 1 \& make help .Ve .SH "ADDING A NEW API" .IX Header "ADDING A NEW API" Because large amounts of boilerplate code in libguestfs are generated, this makes it easy to extend the libguestfs \s-1API.\s0 .PP To add a new \s-1API\s0 action there are two changes: .IP "1." 4 You need to add a description of the call (name, parameters, return type, tests, documentation) to \fIgenerator/actions.ml\fR. .Sp There are two sorts of \s-1API\s0 action, depending on whether the call goes through to the daemon in the appliance, or is serviced entirely by the library (see \*(L"\s-1ARCHITECTURE\*(R"\s0 in \fIguestfs\-internals\fR\|(1)). \*(L"guestfs_sync\*(R" in \fIguestfs\fR\|(3) is an example of the former, since the sync is done in the appliance. \&\*(L"guestfs_set_trace\*(R" in \fIguestfs\fR\|(3) is an example of the latter, since a trace flag is maintained in the handle and all tracing is done on the library side. .Sp Most new actions are of the first type, and get added to the \&\f(CW\*(C`daemon_functions\*(C'\fR list. Each function has a unique procedure number used in the \s-1RPC\s0 protocol which is assigned to that action when we publish libguestfs and cannot be reused. Take the latest procedure number and increment it. .Sp For library-only actions of the second type, add to the \&\f(CW\*(C`non_daemon_functions\*(C'\fR list. Since these functions are serviced by the library and do not travel over the \s-1RPC\s0 mechanism to the daemon, these functions do not need a procedure number, and so the procedure number is set to \f(CW\*(C`\-1\*(C'\fR. .IP "2." 4 Implement the action (in C): .Sp For daemon actions, implement the function \f(CW\*(C`do_\*(C'\fR in the \&\f(CW\*(C`daemon/\*(C'\fR directory. .Sp For library actions, implement the function \f(CW\*(C`guestfs_impl_\*(C'\fR in the \f(CW\*(C`src/\*(C'\fR directory. .Sp In either case, use another function as an example of what to do. .PP After making these changes, use \f(CW\*(C`make\*(C'\fR to compile. .PP Note that you don't need to implement the \s-1RPC,\s0 language bindings, manual pages or anything else. It's all automatically generated from the OCaml description. .SS "Adding tests for an \s-1API\s0" .IX Subsection "Adding tests for an API" You can supply zero or as many tests as you want per \s-1API\s0 call. The tests can either be added as part of the \s-1API\s0 description (\fIgenerator/actions.ml\fR), or in some rarer cases you may want to drop a script into \f(CW\*(C`tests/*/\*(C'\fR. Note that adding a script to \f(CW\*(C`tests/*/\*(C'\fR is slower, so if possible use the first method. .PP The following describes the test environment used when you add an \s-1API\s0 test in \fIactions.ml\fR. .PP The test environment has 4 block devices: .IP "\fI/dev/sda\fR 2 \s-1GB\s0" 4 .IX Item "/dev/sda 2 GB" General block device for testing. .IP "\fI/dev/sdb\fR 2 \s-1GB\s0" 4 .IX Item "/dev/sdb 2 GB" \&\fI/dev/sdb1\fR is an ext2 filesystem used for testing filesystem write operations. .IP "\fI/dev/sdc\fR 10 \s-1MB\s0" 4 .IX Item "/dev/sdc 10 MB" Used in a few tests where two block devices are needed. .IP "\fI/dev/sdd\fR" 4 .IX Item "/dev/sdd" \&\s-1ISO\s0 with fixed content (see \fIimages/test.iso\fR). .PP To be able to run the tests in a reasonable amount of time, the libguestfs appliance and block devices are reused between tests. So don't try testing \*(L"guestfs_kill_subprocess\*(R" in \fIguestfs\fR\|(3) :\-x .PP Each test starts with an initial scenario, selected using one of the \&\f(CW\*(C`Init*\*(C'\fR expressions, described in \fIgenerator/types.ml\fR. These initialize the disks mentioned above in a particular way as documented in \fItypes.ml\fR. You should not assume anything about the previous contents of other disks that are not initialized. .PP You can add a prerequisite clause to any individual test. This is a run-time check, which, if it fails, causes the test to be skipped. Useful if testing a command which might not work on all variations of libguestfs builds. A test that has prerequisite of \f(CW\*(C`Always\*(C'\fR means to run unconditionally. .PP In addition, packagers can skip individual tests by setting environment variables before running \f(CW\*(C`make check\*(C'\fR. .PP .Vb 1 \& SKIP_TEST__=1 .Ve .PP eg: \f(CW\*(C`SKIP_TEST_COMMAND_3=1\*(C'\fR skips test #3 of \*(L"guestfs_command\*(R" in \fIguestfs\fR\|(3). .PP or: .PP .Vb 1 \& SKIP_TEST_=1 .Ve .PP eg: \f(CW\*(C`SKIP_TEST_ZEROFREE=1\*(C'\fR skips all \*(L"guestfs_zerofree\*(R" in \fIguestfs\fR\|(3) tests. .PP Packagers can run only certain tests by setting for example: .PP .Vb 1 \& TEST_ONLY="vfs_type zerofree" .Ve .PP See \fItests/c\-api/tests.c\fR for more details of how these environment variables work. .SS "Debugging new APIs" .IX Subsection "Debugging new APIs" Test new actions work before submitting them. .PP You can use guestfish to try out new commands. .PP Debugging the daemon is a problem because it runs inside a minimal environment. However you can fprintf messages in the daemon to stderr, and they will show up if you use \f(CW\*(C`guestfish \-v\*(C'\fR. .SH "ADDING A NEW LANGUAGE BINDING" .IX Header "ADDING A NEW LANGUAGE BINDING" All language bindings must be generated by the generator (see the \fIgenerator\fR subdirectory). .PP There is no documentation for this yet. We suggest you look at an existing binding, eg. \fIgenerator/ocaml.ml\fR or \&\fIgenerator/perl.ml\fR. .SS "Adding tests for language bindings" .IX Subsection "Adding tests for language bindings" Language bindings should come with tests. Previously testing of language bindings was rather ad-hoc, but we have been trying to formalize the set of tests that every language binding should use. .PP Currently only the OCaml and Perl bindings actually implement the full set of tests, and the OCaml bindings are canonical, so you should emulate what the OCaml tests do. .PP This is the numbering scheme used by the tests: .PP .Vb 1 \& \- 000+ basic tests: \& \& 010 load the library \& 020 create \& 030 create\-flags \& 040 create multiple handles \& 050 test setting and getting config properties \& 060 explicit close \& 065 implicit close (in GC\*(Aqd languages) \& 070 optargs \& 080 version \& 090 retvalues \& \& \- 100 launch, create partitions and LVs and filesystems \& \& \- 400+ events: \& \& 410 close event \& 420 log messages \& 430 progress messages \& \& \- 800+ regression tests (specific to the language) \& \& \- 900+ any other custom tests for the language .Ve .PP To save time when running the tests, only 100, 430, 800+, 900+ should launch the handle. .SH "FORMATTING CODE" .IX Header "FORMATTING CODE" Our C source code generally adheres to some basic code-formatting conventions. The existing code base is not totally consistent on this front, but we do prefer that contributed code be formatted similarly. In short, use spaces-not-TABs for indentation, use 2 spaces for each indentation level, and other than that, follow the K&R style. .PP If you use Emacs, add the following to one of one of your start-up files (e.g., ~/.emacs), to help ensure that you get indentation right: .PP .Vb 9 \& ;;; In libguestfs, indent with spaces everywhere (not TABs). \& ;;; Exceptions: Makefile and ChangeLog modes. \& (add\-hook \*(Aqfind\-file\-hook \& \*(Aq(lambda () (if (and buffer\-file\-name \& (string\-match "/libguestfs\e\e>" \& (buffer\-file\-name)) \& (not (string\-equal mode\-name "Change Log")) \& (not (string\-equal mode\-name "Makefile"))) \& (setq indent\-tabs\-mode nil)))) \& \& ;;; When editing C sources in libguestfs, use this style. \& (defun libguestfs\-c\-mode () \& "C mode with adjusted defaults for use with libguestfs." \& (interactive) \& (c\-set\-style "K&R") \& (setq c\-indent\-level 2) \& (setq c\-basic\-offset 2)) \& (add\-hook \*(Aqc\-mode\-hook \& \*(Aq(lambda () (if (string\-match "/libguestfs\e\e>" \& (buffer\-file\-name)) \& (libguestfs\-c\-mode)))) .Ve .SH "TESTING YOUR CHANGES" .IX Header "TESTING YOUR CHANGES" Turn warnings into errors when developing to make warnings hard to ignore: .PP .Vb 1 \& ./configure \-\-enable\-werror .Ve .PP Useful targets are: .ie n .IP """make check""" 4 .el .IP "\f(CWmake check\fR" 4 .IX Item "make check" Runs the regular test suite. .Sp This is implemented using the regular automake \f(CW\*(C`TESTS\*(C'\fR target. See the automake documentation for details. .ie n .IP """make check\-valgrind""" 4 .el .IP "\f(CWmake check\-valgrind\fR" 4 .IX Item "make check-valgrind" Runs a subset of the test suite under valgrind. .Sp See \*(L"\s-1VALGRIND\*(R"\s0 below. .ie n .IP """make check\-valgrind\-local\-guests""" 4 .el .IP "\f(CWmake check\-valgrind\-local\-guests\fR" 4 .IX Item "make check-valgrind-local-guests" Runs a subset of the test suite under valgrind using locally installed libvirt guests (read-only). .ie n .IP """make check\-direct""" 4 .el .IP "\f(CWmake check\-direct\fR" 4 .IX Item "make check-direct" Runs all tests using default appliance back-end. This only has any effect if a non-default backend was selected using \f(CW\*(C`./configure \-\-with\-default\-backend=...\*(C'\fR .ie n .IP """make check\-valgrind\-direct""" 4 .el .IP "\f(CWmake check\-valgrind\-direct\fR" 4 .IX Item "make check-valgrind-direct" Run a subset of the test suite under valgrind using the default appliance back-end. .ie n .IP """make check\-uml""" 4 .el .IP "\f(CWmake check\-uml\fR" 4 .IX Item "make check-uml" Runs all tests using the User-Mode Linux backend. .Sp As there is no standard location for the User-Mode Linux kernel, you \&\fIhave\fR to set \f(CW\*(C`LIBGUESTFS_HV\*(C'\fR to point to the kernel image, eg: .Sp .Vb 1 \& make check\-uml LIBGUESTFS_HV=~/d/linux\-um/vmlinux .Ve .ie n .IP """make check\-valgrind\-uml""" 4 .el .IP "\f(CWmake check\-valgrind\-uml\fR" 4 .IX Item "make check-valgrind-uml" Runs all tests using the User-Mode Linux backend, under valgrind. .Sp As above, you have to set \f(CW\*(C`LIBGUESTFS_HV\*(C'\fR to point to the kernel. .ie n .IP """make check\-with\-upstream\-qemu""" 4 .el .IP "\f(CWmake check\-with\-upstream\-qemu\fR" 4 .IX Item "make check-with-upstream-qemu" Runs all tests using a local qemu binary. It looks for the qemu binary in \s-1QEMUDIR \s0(defaults to \fI\f(CI$HOME\fI/d/qemu\fR), but you can set this to another directory on the command line, eg: .Sp .Vb 1 \& make check\-with\-upstream\-qemu QEMUDIR=/usr/src/qemu .Ve .ie n .IP """make check\-with\-upstream\-libvirt""" 4 .el .IP "\f(CWmake check\-with\-upstream\-libvirt\fR" 4 .IX Item "make check-with-upstream-libvirt" Runs all tests using a local libvirt. This only has any effect if the libvirt backend was selected using \&\f(CW\*(C`./configure \-\-with\-default\-backend=libvirt\*(C'\fR .Sp It looks for libvirt in \s-1LIBVIRTDIR \s0(defaults to \fI\f(CI$HOME\fI/d/libvirt\fR), but you can set this to another directory on the command line, eg: .Sp .Vb 1 \& make check\-with\-upstream\-libvirt LIBVIRTDIR=/usr/src/libvirt .Ve .ie n .IP """make check\-slow""" 4 .el .IP "\f(CWmake check\-slow\fR" 4 .IX Item "make check-slow" Runs some slow/long\-running tests which are not run by default. .Sp To mark a test as slow/long\-running: .RS 4 .IP "\(bu" 4 Add it to the list of \f(CW\*(C`TESTS\*(C'\fR in the \fIMakefile.am\fR, just like a normal test. .IP "\(bu" 4 Modify the test so it checks if the \f(CW\*(C`SLOW=1\*(C'\fR environment variable is set, and if \fInot\fR set it skips (ie. returns with exit code 77). .IP "\(bu" 4 Add a variable \f(CW\*(C`SLOW_TESTS\*(C'\fR to the \fIMakefile.am\fR listing the slow tests. .IP "\(bu" 4 Add a rule to the \fIMakefile.am\fR: .Sp .Vb 2 \& check\-slow: \& $(MAKE) check TESTS="$(SLOW_TESTS)" SLOW=1 .Ve .RE .RS 4 .RE .ie n .IP """make check\-all""" 4 .el .IP "\f(CWmake check\-all\fR" 4 .IX Item "make check-all" Equivalent to running all \f(CW\*(C`make check*\*(C'\fR rules. .ie n .IP """make check\-release""" 4 .el .IP "\f(CWmake check\-release\fR" 4 .IX Item "make check-release" Runs a subset of \f(CW\*(C`make check*\*(C'\fR rules that are required to pass before a tarball can be released. Currently this is: .RS 4 .IP "\(bu" 4 check .IP "\(bu" 4 check-valgrind .IP "\(bu" 4 check-direct .IP "\(bu" 4 check-valgrind-direct .IP "\(bu" 4 check-slow .RE .RS 4 .RE .ie n .IP """make installcheck""" 4 .el .IP "\f(CWmake installcheck\fR" 4 .IX Item "make installcheck" Run \f(CW\*(C`make check\*(C'\fR on the installed copy of libguestfs. .Sp The version of installed libguestfs being tested, and the version of the libguestfs source tree must be the same. .Sp Do: .Sp .Vb 4 \& ./autogen.sh \& make clean ||: \& make \& make installcheck .Ve .SS "\s-1VALGRIND\s0" .IX Subsection "VALGRIND" When you do \f(CW\*(C`make check\-valgrind\*(C'\fR, it searches for any \fIMakefile.am\fR in the tree that has a \f(CW\*(C`check\-valgrind:\*(C'\fR target and runs it. .PP Writing the \fIMakefile.am\fR and tests correctly to use valgrind and working with automake parallel tests is subtle. .PP If your tests are run via a shell script wrapper, then in the wrapper use: .PP .Vb 1 \& $VG virt\-foo .Ve .PP and in the \fIMakefile.am\fR use: .PP .Vb 2 \& check\-valgrind: \& make VG="@VG@" check .Ve .PP However, if your binaries run directly from the \f(CW\*(C`TESTS\*(C'\fR rule, you have to modify the \fIMakefile.am\fR like this: .PP .Vb 1 \& LOG_COMPILER = $(VG) \& \& check\-valgrind: \& make VG="@VG@" check .Ve .PP In either case, check that the right program is being tested by examining the \fItmp/valgrind*\fR log files carefully. .SH "SUBMITTING PATCHES" .IX Header "SUBMITTING PATCHES" Submit patches to the mailing list: http://www.redhat.com/mailman/listinfo/libguestfs and \s-1CC\s0 to rjones@redhat.com. .PP You do not need to subscribe to the mailing list if you don't want to. There may be a short delay while your message is moderated. .SH "DAEMON CUSTOM PRINTF FORMATTERS" .IX Header "DAEMON CUSTOM PRINTF FORMATTERS" In the daemon code we have created custom printf formatters \f(CW%Q\fR and \&\f(CW%R\fR, which are used to do shell quoting. .ie n .IP "%Q" 4 .el .IP "\f(CW%Q\fR" 4 .IX Item "%Q" Simple shell quoted string. Any spaces or other shell characters are escaped for you. .ie n .IP "%R" 4 .el .IP "\f(CW%R\fR" 4 .IX Item "%R" Same as \f(CW%Q\fR except the string is treated as a path which is prefixed by the sysroot. .PP For example: .PP .Vb 1 \& asprintf (&cmd, "cat %R", path); .Ve .PP would produce \f(CW\*(C`cat /sysroot/some\e path\e with\e spaces\*(C'\fR .PP \&\fINote:\fR Do \fInot\fR use these when you are passing parameters to the \&\f(CW\*(C`command{,r,v,rv}()\*(C'\fR functions. These parameters do \s-1NOT\s0 need to be quoted because they are not passed via the shell (instead, straight to exec). You probably want to use the \f(CW\*(C`sysroot_path()\*(C'\fR function however. .SH "INTERNATIONALIZATION (I18N) SUPPORT" .IX Header "INTERNATIONALIZATION (I18N) SUPPORT" We support i18n (gettext anyhow) in the library. .PP However many messages come from the daemon, and we don't translate those at the moment. One reason is that the appliance generally has all locale files removed from it, because they take up a lot of space. So we'd have to readd some of those, as well as copying our \s-1PO\s0 files into the appliance. .PP Debugging messages are never translated, since they are intended for the programmers. .SH "HOW OCAML PROGRAMS ARE COMPILED AND LINKED" .IX Header "HOW OCAML PROGRAMS ARE COMPILED AND LINKED" Mostly this section is \*(L"how we make automake & ocamlopt work together\*(R" since OCaml programs themselves are easy to compile. .PP Automake has no native support for OCaml programs, ocamlc nor ocamlopt. What we do instead is to treat OCaml programs as C programs which happen to contain these \*(L"other objects\*(R" (\f(CW"DEPENDENCIES"\fR in automake-speak) that happen to be the OCaml objects. This works because OCaml programs usually have C files for native bindings etc. .PP So a typical program is described as just its C sources: .PP .Vb 1 \& virt_v2v_SOURCES = ... utils\-c.c xml\-c.c .Ve .PP For programs that have no explicit C sources, we create an empty \&\fIdummy.c\fR file, and list that instead: .PP .Vb 1 \& virt_resize_SOURCES = dummy.c .Ve .PP The OCaml objects which contain most of the code are listed as automake dependencies (other dependencies may also be listed): .PP .Vb 1 \& virt_v2v_DEPENDENCIES = ... cmdline.cmx v2v.cmx .Ve .PP The only other special thing we need to do is to provide a custom link command. This is needed because automake won't assemble the ocamlopt command, the list of objects and the \f(CW\*(C`\-cclib\*(C'\fR libraries in the correct order otherwise. .PP .Vb 2 \& virt_v2v_LINK = \e \& $(top_srcdir)/ocaml\-link.sh \-cclib \*(Aq\-lutils \-lgnu\*(Aq \-\- ... .Ve .PP The actual rules, which you can examine in \fIv2v/Makefile.am\fR, are a little bit more complicated than this because they have to handle: .IP "\(bu" 4 Compiling for byte code or native code. .IP "\(bu" 4 The pattern rules needed to compile the OCaml sources to objects. .Sp These are now kept in \fIsubdir\-rules.mk\fR at the top level, which is included in every subdirectory \fIMakefile.am\fR. .IP "\(bu" 4 Adding OCaml sources files to \f(CW\*(C`EXTRA_DIST\*(C'\fR. .Sp Automake isn't aware of the complete list of sources for a binary, so it will not add them all automatically. .SH "VIRT\-V2V" .IX Header "VIRT-V2V" First a little history. Virt\-v2v has been through at least two complete rewrites, so this is probably about the third version (but we don't intend to rewrite it again). The previous version was written in Perl and can be found here: https://git.fedorahosted.org/git/virt\-v2v.git .PP The current version started out as almost a line-for-line rewrite of the Perl code in OCaml + C, and it still has a fairly similar structure. Therefore if there are details of this code that you don't understand (especially in the details of guest conversion), checking the Perl code may help. .PP The files to start with when reading this code are: .IP "\(bu" 4 \&\fItypes.mli\fR .IP "\(bu" 4 \&\fIv2v.ml\fR .PP \&\fItypes.mli\fR defines all the structures used and passed around when communicating between different bits of the program. \fIv2v.ml\fR controls how the program runs in stages. .PP After studying those files, you may want to branch out into the input modules (\fIinput_*\fR), the output modules (\fIoutput_*\fR) or the conversion modules (\fIconvert_*\fR). The input and output modules define \fI\-i\fR and \fI\-o\fR options (see the manual). The conversion modules define what guest types we can handle and the detailed steps involved in converting them. .PP Every other file in this directory is a support module / library of some sort. Some code is written in C, especially where we want to use an external C library such as libxml2. .SH "VIRT\-P2V" .IX Header "VIRT-P2V" Virt\-p2v is a front end on virt\-v2v. ie. All it does is act as a \s-1GUI\s0 front end, and it calls out to virt\-v2v to perform the actual conversion. Therefore most of the C code in the \fIp2v/\fR subdirectory is Gtk (\s-1GUI\s0) code, or supporting code for talking to the remote conversion server. There is no special support for physical machines in virt\-v2v. They are converted in the same way as foreign VMs. .SS "Running virt\-p2v" .IX Subsection "Running virt-p2v" You can run the \fIp2v/virt\-p2v\fR binary directly, but it will try to convert your machine's real \fI/dev/sda\fR which is unlikely to work well. However virt\-p2v also has a test mode in which you can supply a test disk: .PP .Vb 1 \& make \-C p2v run\-virt\-p2v\-directly .Ve .PP This is a wrapper around the \fIvirt\-p2v\fR\|(1) \fI\-\-test\-disk\fR option. You can control the \*(L"physical machine\*(R" disk by setting \&\f(CW\*(C`PHYSICAL_MACHINE\*(C'\fR to point to a disk image. .PP A more realistic test is to run virt\-p2v inside a \s-1VM\s0 on the local machine. To do that, do: .PP .Vb 1 \& make \-C p2v run\-virt\-p2v\-in\-a\-vm .Ve .PP This also runs qemu with the \*(L"physical machine\*(R" disk (which you can set by setting \f(CW\*(C`PHYSICAL_MACHINE\*(C'\fR), a virtual \s-1CD,\s0 and a variety of network cards for testing. .PP A third way to run virt\-p2v simulates fairly accurately the program being downloaded over \s-1PXE\s0 and then doing an automatic conversion of the source physical machine (the non-GUI path \*(-- see next section below): .PP .Vb 1 \& make \-C p2v run\-virt\-p2v\-non\-gui\-conversion .Ve .SS "Understanding the virt\-p2v code" .IX Subsection "Understanding the virt-p2v code" \&\fISee also:\fR \*(L"\s-1HOW VIRT\-P2V WORKS\*(R"\s0 in \fIvirt\-p2v\fR\|(1) .PP There are two paths through the code, \s-1GUI\s0 or non-GUI (parsing the kernel command line): .PP .Vb 4 \& main.c ──────┬─────▶ gui.c ──────┬─────▶ conversion.c \& │ │ \& │ │ \& └────▶ kernel.c ────┘ .Ve .PP but both paths call back to the \fIconversion.c\fR function \&\f(CW\*(C`start_conversion\*(C'\fR to run the remote virt\-v2v. .PP The main task of \fIgui.c\fR/\fIkernel.c\fR is to populate the virt\-v2v configuration (\fIconfig.c\fR). .PP During conversion, we need to establish ssh connections, and that is done using two libraries: .PP .Vb 1 \& conversion.c ──────▶ ssh.c ──────▶ miniexpect.c .Ve .PP where \fIssh.c\fR is responsible for managing ssh connections overall, and \fIminiexpect.c\fR implements \*(L"expect-like\*(R" functionality for talking interactively to the remote virt\-v2v conversion server. .PP (Note that miniexpect is a separate library with its own upstream, so if you patch miniexpect.c, then please make sure the changes get reflected in miniexpect's upstream too: \&\fIhttp://git.annexia.org/?p=miniexpect.git;a=summary\fR) .SH "MAKING A STABLE RELEASE" .IX Header "MAKING A STABLE RELEASE" When we make a stable release, there are several steps documented here. See \*(L"\s-1LIBGUESTFS VERSION NUMBERS\*(R"\s0 in \fIguestfs\fR\|(3) for general information about the stable branch policy. .IP "\(bu" 4 Check \f(CW\*(C`make && make check\*(C'\fR works on at least Fedora, Debian and Ubuntu. .IP "\(bu" 4 Check \f(CW\*(C`./configure \-\-without\-libvirt\*(C'\fR works. .IP "\(bu" 4 Finalize \fIguestfs\-release\-notes.pod\fR .IP "\(bu" 4 Push and pull from Zanata. .Sp Run: .Sp .Vb 1 \& zanata push .Ve .Sp to push the latest \s-1POT\s0 files to Zanata. Then run: .Sp .Vb 1 \& ./zanata\-pull.sh .Ve .Sp which is a wrapper to pull the latest translated \fI*.po\fR files. .IP "\(bu" 4 Consider updating gnulib to latest upstream version. .IP "\(bu" 4 Create new stable and development directories under http://libguestfs.org/download. .IP "\(bu" 4 Edit \fIwebsite/index.html.in\fR. .IP "\(bu" 4 Set the version (in \fIconfigure.ac\fR) to the new \fIstable\fR version, ie. 1.XX.0, and commit it: .Sp .Vb 6 \& ./localconfigure \& make distclean \-k \& ./localconfigure \& make && make dist \& make maintainer\-commit \& make maintainer\-tag .Ve .IP "\(bu" 4 Create the stable branch in git: .Sp .Vb 2 \& git branch stable\-1.XX \& git push origin stable\-1.XX .Ve .IP "\(bu" 4 Do a full release of the stable branch. .IP "\(bu" 4 Set the version to the next development version and commit that. Optionally do a full release of the development branch. .SH "INTERNAL DOCUMENTATION" .IX Header "INTERNAL DOCUMENTATION" This section documents internal functions inside libguestfs and various utilities. It is intended for libguestfs developers only. .PP This section is autogenerated from \f(CW\*(C`/**\*(C'\fR comments in source files, which are marked up in \s-1POD\s0 format. .PP \&\fBThese functions are not publicly exported, and may change or be removed at any time.\fR .SS "Subdirectory \fIsrc\fP" .IX Subsection "Subdirectory src" \fIFile \fIsrc/actions\-support.c\fI\fR .IX Subsection "File src/actions-support.c" .PP Helper functions for the actions code in \fIsrc/actions\-*.c\fR. .PP \fIFile \fIsrc/appliance.c\fI\fR .IX Subsection "File src/appliance.c" .PP This file deals with building the libguestfs appliance. .PP Function \f(CW\*(C`src/appliance.c:guestfs_int_build_appliance\*(C'\fR .IX Subsection "Function src/appliance.c:guestfs_int_build_appliance" .PP .Vb 5 \& int \& guestfs_int_build_appliance (guestfs_h *g, \& char **kernel_rtn, \& char **initrd_rtn, \& char **appliance_rtn) .Ve .PP Locate or build the appliance. .PP This function locates or builds the appliance as necessary, handling the supermin appliance, caching of supermin-built appliances, or using either a fixed or old-style appliance. .PP The return value is \f(CW0\fR = good, \f(CW\*(C`\-1\*(C'\fR = error. Returned in \&\f(CW*kernel\fR will be the name of the kernel to use, \f(CW*initrd\fR the name of the initrd, \f(CW*appliance\fR the name of the ext2 root filesystem. \f(CW*appliance\fR can be \f(CW\*(C`NULL\*(C'\fR, meaning that we are using an old-style (non\-ext2) appliance. All three strings must be freed by the caller. However the referenced files themselves must \&\fInot\fR be deleted. .PP The process is as follows: .IP "1." 4 Look for the first element of \f(CW\*(C`g\->path\*(C'\fR which contains a supermin appliance skeleton. If no element has this, skip straight to step 3. .IP "2." 4 Call \f(CW\*(C`supermin \-\-build\*(C'\fR to build the full appliance (if it needs to be rebuilt). If this is successful, return the full appliance. .IP "3." 4 Check each element of \f(CW\*(C`g\->path\*(C'\fR, looking for a fixed appliance. If one is found, return it. .IP "4." 4 Check each element of \f(CW\*(C`g\->path\*(C'\fR, looking for an old-style appliance. If one is found, return it. .PP The supermin appliance cache directory lives in \&\fI\f(CI$TMPDIR\fI/.guestfs\-$UID/\fR and consists of up to four files: .PP .Vb 4 \& $TMPDIR/.guestfs\-$UID/lock \- the supermin lock file \& $TMPDIR/.guestfs\-$UID/appliance.d/kernel \- the kernel \& $TMPDIR/.guestfs\-$UID/appliance.d/initrd \- the supermin initrd \& $TMPDIR/.guestfs\-$UID/appliance.d/root \- the appliance .Ve .PP Multiple instances of libguestfs with the same \s-1UID\s0 may be racing to create an appliance. However (since supermin ≥ 5) supermin provides a \fI\-\-lock\fR flag and atomic update of the \fIappliance.d\fR subdirectory. .PP Function \f(CW\*(C`src/appliance.c:build_supermin_appliance\*(C'\fR .IX Subsection "Function src/appliance.c:build_supermin_appliance" .PP .Vb 5 \& static int \& build_supermin_appliance (guestfs_h *g, \& const char *supermin_path, \& char **kernel, char **initrd, \& char **appliance) .Ve .PP Build supermin appliance from \f(CW\*(C`supermin_path\*(C'\fR to \&\fI\f(CI$TMPDIR\fI/.guestfs\-$UID\fR. .PP Returns: \f(CW0\fR = built or \f(CW\*(C`\-1\*(C'\fR = error (aborts launch). .PP Function \f(CW\*(C`src/appliance.c:run_supermin_build\*(C'\fR .IX Subsection "Function src/appliance.c:run_supermin_build" .PP .Vb 5 \& static int \& run_supermin_build (guestfs_h *g, \& const char *lockfile, \& const char *appliancedir, \& const char *supermin_path) .Ve .PP Run \f(CW\*(C`supermin \-\-build\*(C'\fR and tell it to generate the appliance. .PP Function \f(CW\*(C`src/appliance.c:find_path\*(C'\fR .IX Subsection "Function src/appliance.c:find_path" .PP .Vb 5 \& static int \& find_path (guestfs_h *g, \& int (*pred) (guestfs_h *g, const char *pelem, void *data), \& void *data, \& char **pelem_ret) .Ve .PP Search elements of \f(CW\*(C`g\->path\*(C'\fR, returning the first path element which matches the predicate function \f(CW\*(C`pred\*(C'\fR. .PP Function \f(CW\*(C`pred\*(C'\fR must return a true or false value. If it returns \&\f(CW\*(C`\-1\*(C'\fR then the entire search is aborted. .PP Return values: .PP .Vb 4 \& 1 = a path element matched, it is returned in *pelem_ret and must be \& freed by the caller, \& 0 = no path element matched, *pelem_ret is set to NULL, or \& \-1 = error which aborts the launch process .Ve .PP Function \f(CW\*(C`src/appliance.c:dir_contains_file\*(C'\fR .IX Subsection "Function src/appliance.c:dir_contains_file" .PP .Vb 2 \& static int \& dir_contains_file (guestfs_h *g, const char *dir, const char *file) .Ve .PP Returns true iff \f(CW\*(C`file\*(C'\fR is contained in \f(CW\*(C`dir\*(C'\fR. .PP Function \f(CW\*(C`src/appliance.c:dir_contains_files\*(C'\fR .IX Subsection "Function src/appliance.c:dir_contains_files" .PP .Vb 2 \& static int \& dir_contains_files (guestfs_h *g, const char *dir, ...) .Ve .PP Returns true iff every listed file is contained in \f(CW\*(C`dir\*(C'\fR. .PP Function \f(CW\*(C`src/appliance.c:guestfs_int_get_uefi\*(C'\fR .IX Subsection "Function src/appliance.c:guestfs_int_get_uefi" .PP .Vb 2 \& int \& guestfs_int_get_uefi (guestfs_h *g, char **code, char **vars, int *flags) .Ve .PP Return the location of firmware needed to boot the appliance. This is aarch64 only currently, since that's the only architecture where \&\s-1UEFI\s0 is mandatory (and that only for \s-1RHEL\s0). .PP \&\f(CW*code\fR is initialized with the path to the read-only \s-1UEFI\s0 code file. \f(CW*vars\fR is initialized with the path to a copy of the \s-1UEFI\s0 vars file (which is cleaned up automatically on exit). .PP If \f(CW*code\fR == \f(CW*vars\fR == \f(CW\*(C`NULL\*(C'\fR then no \s-1UEFI\s0 firmware is available. .PP \&\f(CW*code\fR and \f(CW*vars\fR should be freed by the caller. .PP If the function returns \f(CW\*(C`\-1\*(C'\fR then there was a real error which should cause appliance building to fail (no \s-1UEFI\s0 firmware is not an error). .PP See also \fIv2v/utils.ml\fR:find_uefi_firmware .PP \fIFile \fIsrc/cleanup.c\fI\fR .IX Subsection "File src/cleanup.c" .PP Libguestfs uses \f(CW\*(C`CLEANUP_*\*(C'\fR macros to simplify temporary allocations. They are implemented using the \&\f(CW\*(C`_\|_attribute_\|_((cleanup))\*(C'\fR feature of gcc and clang. Typical usage is: .PP .Vb 6 \& fn () \& { \& CLEANUP_FREE char *str = NULL; \& str = safe_asprintf (g, "foo"); \& // str is freed automatically when the function returns \& } .Ve .PP There are a few catches to be aware of with the cleanup mechanism: .IP "\(bu" 4 If a cleanup variable is not initialized, then you can end up calling \fIfree\fR\|(3) with an undefined value, resulting in the program crashing. For this reason, you should usually initialize every cleanup variable with something, eg. \f(CW\*(C`NULL\*(C'\fR .IP "\(bu" 4 Don't mark variables holding return values as cleanup variables. .IP "\(bu" 4 The \f(CW\*(C`main()\*(C'\fR function shouldn't use cleanup variables since it is normally exited by calling \fIexit\fR\|(3), and that doesn't call the cleanup handlers. .PP The functions in this file are used internally by the \f(CW\*(C`CLEANUP_*\*(C'\fR macros. Don't call them directly. .PP \fIFile \fIsrc/command.c\fI\fR .IX Subsection "File src/command.c" .PP A wrapper for running external commands, loosely based on libvirt's \&\f(CW\*(C`virCommand\*(C'\fR interface. .PP In outline to use this interface you must: .IP "1." 4 Create a new command handle: .Sp .Vb 2 \& struct command *cmd; \& cmd = guestfs_int_new_command (g); .Ve .IP "2." 4 \&\fIEither\fR add arguments: .Sp .Vb 3 \& guestfs_int_cmd_add_arg (cmd, "qemu\-img"); \& guestfs_int_cmd_add_arg (cmd, "info"); \& guestfs_int_cmd_add_arg (cmd, filename); .Ve .Sp (\fB\s-1NB:\s0\fR You don't need to add a \f(CW\*(C`NULL\*(C'\fR argument at the end.) .IP "3." 4 \&\fIOr\fR construct a command using a mix of quoted and unquoted strings. (This is useful for \fIsystem\fR\|(3)/\f(CW\*(C`popen("r")\*(C'\fR\-style shell commands, with the added safety of allowing args to be quoted properly). .Sp .Vb 2 \& guestfs_int_cmd_add_string_unquoted (cmd, "qemu\-img info "); \& guestfs_int_cmd_add_string_quoted (cmd, filename); .Ve .IP "4." 4 Set various flags, such as whether you want to capture errors in the regular libguestfs error log. .IP "5." 4 Run the command. This is what does the \fIfork\fR\|(2) call, optionally loops over the output, and then does a \fIwaitpid\fR\|(3) and returns the exit status of the command. .Sp .Vb 4 \& r = guestfs_int_cmd_run (cmd); \& if (r == \-1) \& // error \& // else test r using the WIF* functions .Ve .IP "6." 4 Close the handle: .Sp .Vb 1 \& guestfs_int_cmd_close (cmd); .Ve .Sp (or use \f(CW\*(C`CLEANUP_CMD_CLOSE\*(C'\fR). .PP Function \f(CW\*(C`src/command.c:guestfs_int_new_command\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_new_command" .PP .Vb 2 \& struct command * \& guestfs_int_new_command (guestfs_h *g) .Ve .PP Create a new command handle. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_add_arg\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_add_arg" .PP .Vb 2 \& void \& guestfs_int_cmd_add_arg (struct command *cmd, const char *arg) .Ve .PP Add single arg (for \f(CW\*(C`execv\*(C'\fR\-style command execution). .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_add_arg_format\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_add_arg_format" .PP .Vb 2 \& void \& guestfs_int_cmd_add_arg_format (struct command *cmd, const char *fs, ...) .Ve .PP Add single arg (for \f(CW\*(C`execv\*(C'\fR\-style command execution) using a \fIprintf\fR\|(3)\-style format string. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_add_string_unquoted\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_add_string_unquoted" .PP .Vb 2 \& void \& guestfs_int_cmd_add_string_unquoted (struct command *cmd, const char *str) .Ve .PP Add a string (for \fIsystem\fR\|(3)\-style command execution). .PP This variant adds the strings without quoting them, which is dangerous if the string contains untrusted content. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_add_string_quoted\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_add_string_quoted" .PP .Vb 2 \& void \& guestfs_int_cmd_add_string_quoted (struct command *cmd, const char *str) .Ve .PP Add a string (for \fIsystem\fR\|(3)\-style command execution). .PP The string is enclosed in double quotes, with any special characters within the string which need escaping done. This is used to add a single argument to a \fIsystem\fR\|(3)\-style command string. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_set_stdout_callback\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_set_stdout_callback" .PP .Vb 4 \& void \& guestfs_int_cmd_set_stdout_callback (struct command *cmd, \& cmd_stdout_callback stdout_callback, \& void *stdout_data, unsigned flags) .Ve .PP Set a callback which will capture stdout. .PP If flags contains \f(CW\*(C`CMD_STDOUT_FLAG_LINE_BUFFER\*(C'\fR (the default), then the callback is called line by line on the output. If there is a trailing \f(CW\*(C`\en\*(C'\fR then it is automatically removed before the callback is called. The line buffer is \f(CW\*(C`\e0\*(C'\fR\-terminated. .PP If flags contains \f(CW\*(C`CMD_STDOUT_FLAG_UNBUFFERED\*(C'\fR, then buffers are passed to the callback as it is received from the command. Note in this case the buffer is \fInot\fR \f(CW\*(C`\e0\*(C'\fR\-terminated, so you need to may attention to the length field in the callback. .PP If flags contains \f(CW\*(C`CMD_STDOUT_FLAG_WHOLE_BUFFER\*(C'\fR, then the callback is called exactly once, with the entire buffer. Note in this case the buffer is \fInot\fR \f(CW\*(C`\e0\*(C'\fR\-terminated, so you need to may attention to the length field in the callback. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_set_stderr_to_stdout\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_set_stderr_to_stdout" .PP .Vb 2 \& void \& guestfs_int_cmd_set_stderr_to_stdout (struct command *cmd) .Ve .PP Equivalent to adding \f(CW\*(C`2>&1\*(C'\fR to the end of the command. This is incompatible with the \f(CW\*(C`capture_errors\*(C'\fR flag, because it doesn't make sense to combine them. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_clear_capture_errors\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_clear_capture_errors" .PP .Vb 2 \& void \& guestfs_int_cmd_clear_capture_errors (struct command *cmd) .Ve .PP Clear the \f(CW\*(C`capture_errors\*(C'\fR flag. This means that any errors will go to stderr, instead of being captured in the event log, and that is usually undesirable. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_clear_close_files\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_clear_close_files" .PP .Vb 2 \& void \& guestfs_int_cmd_clear_close_files (struct command *cmd) .Ve .PP Don't close file descriptors after the fork. .PP \&\s-1XXX\s0 Should allow single fds to be sent to child process. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_set_child_callback\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_set_child_callback" .PP .Vb 4 \& void \& guestfs_int_cmd_set_child_callback (struct command *cmd, \& cmd_child_callback child_callback, \& void *data) .Ve .PP Set a function to be executed in the child, right before the execution. Can be used to setup the child, for example changing its current directory. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_set_child_rlimit\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_set_child_rlimit" .PP .Vb 2 \& void \& guestfs_int_cmd_set_child_rlimit (struct command *cmd, int resource, long limit) .Ve .PP Set up child rlimits, in case the process we are running could consume lots of space or time. .PP Function \f(CW\*(C`src/command.c:finish_command\*(C'\fR .IX Subsection "Function src/command.c:finish_command" .PP .Vb 2 \& static void \& finish_command (struct command *cmd) .Ve .PP Finish off the command by either \f(CW\*(C`NULL\*(C'\fR\-terminating the argv array or adding a terminating \f(CW\*(C`\e0\*(C'\fR to the string, or die with an internal error if no command has been added. .PP Function \f(CW\*(C`src/command.c:loop\*(C'\fR .IX Subsection "Function src/command.c:loop" .PP .Vb 2 \& static int \& loop (struct command *cmd) .Ve .PP The loop which reads errors and output and directs it either to the log or to the stdout callback as appropriate. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_run\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_run" .PP .Vb 2 \& int \& guestfs_int_cmd_run (struct command *cmd) .Ve .PP Fork, run the command, loop over the output, and waitpid. .PP Returns the exit status. Test it using \f(CW\*(C`WIF*\*(C'\fR macros. .PP On error: Calls \f(CW\*(C`error\*(C'\fR and returns \f(CW\*(C`\-1\*(C'\fR. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_pipe_run\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_pipe_run" .PP .Vb 2 \& int \& guestfs_int_cmd_pipe_run (struct command *cmd, const char *mode) .Ve .PP Fork and run the command, but don't wait. Roughly equivalent to \&\f(CW\*(C`popen (..., "r"|"w")\*(C'\fR. .PP Returns the file descriptor of the pipe, connected to stdout (\f(CW"r"\fR) or stdin (\f(CW"w"\fR) of the child process. .PP After reading/writing to this pipe, call \&\f(CW\*(C`guestfs_int_cmd_pipe_wait\*(C'\fR to wait for the status of the child. .PP Errors from the subcommand cannot be captured to the error log using this interface. Instead the caller should call \&\f(CW\*(C`guestfs_int_cmd_get_pipe_errors\*(C'\fR (after \&\f(CW\*(C`guestfs_int_cmd_pipe_wait\*(C'\fR returns an error). .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_pipe_wait\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_pipe_wait" .PP .Vb 2 \& int \& guestfs_int_cmd_pipe_wait (struct command *cmd) .Ve .PP Wait for a subprocess created by \f(CW\*(C`guestfs_int_cmd_pipe_run\*(C'\fR to finish. On error (eg. failed syscall) this returns \f(CW\*(C`\-1\*(C'\fR and sets the error. If the subcommand fails, then use \f(CW\*(C`WIF*\*(C'\fR macros to check this, and call \f(CW\*(C`guestfs_int_cmd_get_pipe_errors\*(C'\fR to read the error messages printed by the child. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_get_pipe_errors\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_get_pipe_errors" .PP .Vb 2 \& char * \& guestfs_int_cmd_get_pipe_errors (struct command *cmd) .Ve .PP Read the error messages printed by the child. The caller must free the returned buffer after use. .PP Function \f(CW\*(C`src/command.c:guestfs_int_cmd_close\*(C'\fR .IX Subsection "Function src/command.c:guestfs_int_cmd_close" .PP .Vb 2 \& void \& guestfs_int_cmd_close (struct command *cmd) .Ve .PP Close the \f(CW\*(C`cmd\*(C'\fR object and free all resources. .PP Function \f(CW\*(C`src/command.c:process_line_buffer\*(C'\fR .IX Subsection "Function src/command.c:process_line_buffer" .PP .Vb 2 \& static void \& process_line_buffer (struct command *cmd, int closed) .Ve .PP Deal with buffering stdout for the callback. .PP \fIFile \fIsrc/conn\-socket.c\fI\fR .IX Subsection "File src/conn-socket.c" .PP This file handles connections to the child process where this is done over regular \s-1POSIX\s0 sockets. .PP Function \f(CW\*(C`src/conn\-socket.c:handle_log_message\*(C'\fR .IX Subsection "Function src/conn-socket.c:handle_log_message" .PP .Vb 3 \& static int \& handle_log_message (guestfs_h *g, \& struct connection_socket *conn) .Ve .PP This is called if \f(CW\*(C`conn\->console_sock\*(C'\fR becomes ready to read while we are doing one of the connection operations above. It reads and deals with the log message. .PP Returns: .ie n .IP "1" 4 .el .IP "\f(CW1\fR" 4 .IX Item "1" log message(s) were handled successfully .ie n .IP "0" 4 .el .IP "\f(CW0\fR" 4 .IX Item "0" connection to appliance closed .ie n .IP """\-1""" 4 .el .IP "\f(CW\-1\fR" 4 .IX Item "-1" error .PP Function \f(CW\*(C`src/conn\-socket.c:guestfs_int_new_conn_socket_listening\*(C'\fR .IX Subsection "Function src/conn-socket.c:guestfs_int_new_conn_socket_listening" .PP .Vb 4 \& struct connection * \& guestfs_int_new_conn_socket_listening (guestfs_h *g, \& int daemon_accept_sock, \& int console_sock) .Ve .PP Create a new socket connection, listening. .PP Note that it's \s-1OK\s0 for \f(CW\*(C`console_sock\*(C'\fR to be passed as \f(CW\*(C`\-1\*(C'\fR, meaning there's no console available for this appliance. .PP After calling this, \f(CW\*(C`daemon_accept_sock\*(C'\fR is owned by the connection, and will be closed properly either in \&\f(CW\*(C`accept_connection\*(C'\fR or \f(CW\*(C`free_connection\*(C'\fR. .PP Function \f(CW\*(C`src/conn\-socket.c:guestfs_int_new_conn_socket_connected\*(C'\fR .IX Subsection "Function src/conn-socket.c:guestfs_int_new_conn_socket_connected" .PP .Vb 4 \& struct connection * \& guestfs_int_new_conn_socket_connected (guestfs_h *g, \& int daemon_sock, \& int console_sock) .Ve .PP Create a new socket connection, connected. .PP As above, but the caller passes us a connected \f(CW\*(C`daemon_sock\*(C'\fR and promises not to call \f(CW\*(C`accept_connection\*(C'\fR. .PP \fIFile \fIsrc/create.c\fI\fR .IX Subsection "File src/create.c" .PP APIs for creating empty disks. .PP Mostly this consists of wrappers around the \fIqemu\-img\fR\|(1) program. .PP \fIFile \fIsrc/drives.c\fI\fR .IX Subsection "File src/drives.c" .PP Drives added are stored in an array in the handle. Code here manages that array and the individual \f(CW\*(C`struct drive\*(C'\fR data. .PP Function \f(CW\*(C`src/drives.c:create_overlay\*(C'\fR .IX Subsection "Function src/drives.c:create_overlay" .PP .Vb 2 \& static int \& create_overlay (guestfs_h *g, struct drive *drv) .Ve .PP For readonly drives, create an overlay to protect the original drive content. Note we never need to clean up these overlays since they are created in the temporary directory and deleted when the handle is closed. .PP Function \f(CW\*(C`src/drives.c:create_drive_file\*(C'\fR .IX Subsection "Function src/drives.c:create_drive_file" .PP .Vb 3 \& static struct drive * \& create_drive_file (guestfs_h *g, \& const struct drive_create_data *data) .Ve .PP Create and free the \f(CW\*(C`struct drive\*(C'\fR. .PP Function \f(CW\*(C`src/drives.c:create_drive_dev_null\*(C'\fR .IX Subsection "Function src/drives.c:create_drive_dev_null" .PP .Vb 3 \& static struct drive * \& create_drive_dev_null (guestfs_h *g, \& struct drive_create_data *data) .Ve .PP Create the special \fI/dev/null\fR drive. .PP Traditionally you have been able to use \fI/dev/null\fR as a filename, as many times as you like. Ancient \s-1KVM \s0(\s-1RHEL 5\s0) cannot handle adding \fI/dev/null\fR readonly. qemu 1.2 + virtio-scsi segfaults when you use any zero-sized file including \fI/dev/null\fR. .PP Because of these problems, we replace \fI/dev/null\fR with a non-zero sized temporary file. This shouldn't make any difference since users are not supposed to try and access a null drive. .PP Function \f(CW\*(C`src/drives.c:drive_to_string\*(C'\fR .IX Subsection "Function src/drives.c:drive_to_string" .PP .Vb 2 \& static char * \& drive_to_string (guestfs_h *g, const struct drive *drv) .Ve .PP Convert a \f(CW\*(C`struct drive\*(C'\fR to a string for debugging. The caller must free this string. .PP Function \f(CW\*(C`src/drives.c:add_drive_to_handle_at\*(C'\fR .IX Subsection "Function src/drives.c:add_drive_to_handle_at" .PP .Vb 2 \& static void \& add_drive_to_handle_at (guestfs_h *g, struct drive *d, size_t drv_index) .Ve .PP Add \f(CW\*(C`struct drive\*(C'\fR to the \f(CW\*(C`g\->drives\*(C'\fR vector at the given index \f(CW\*(C`drv_index\*(C'\fR. If the array isn't large enough it is reallocated. The index must not contain a drive already. .PP Function \f(CW\*(C`src/drives.c:add_drive_to_handle\*(C'\fR .IX Subsection "Function src/drives.c:add_drive_to_handle" .PP .Vb 2 \& static void \& add_drive_to_handle (guestfs_h *g, struct drive *d) .Ve .PP Add struct drive to the end of the \f(CW\*(C`g\->drives\*(C'\fR vector in the handle. .PP Function \f(CW\*(C`src/drives.c:guestfs_int_add_dummy_appliance_drive\*(C'\fR .IX Subsection "Function src/drives.c:guestfs_int_add_dummy_appliance_drive" .PP .Vb 2 \& void \& guestfs_int_add_dummy_appliance_drive (guestfs_h *g) .Ve .PP Called during launch to add a dummy slot to \f(CW\*(C`g\->drives\*(C'\fR. .PP Function \f(CW\*(C`src/drives.c:guestfs_int_free_drives\*(C'\fR .IX Subsection "Function src/drives.c:guestfs_int_free_drives" .PP .Vb 2 \& void \& guestfs_int_free_drives (guestfs_h *g) .Ve .PP Free up all the drives in the handle. .PP Function \f(CW\*(C`src/drives.c:valid_format_iface\*(C'\fR .IX Subsection "Function src/drives.c:valid_format_iface" .PP .Vb 2 \& static int \& valid_format_iface (const char *str) .Ve .PP Check string parameter matches regular expression \&\f(CW\*(C`^[\-_[:alnum:]]+$\*(C'\fR (in C locale). .PP Function \f(CW\*(C`src/drives.c:valid_disk_label\*(C'\fR .IX Subsection "Function src/drives.c:valid_disk_label" .PP .Vb 2 \& static int \& valid_disk_label (const char *str) .Ve .PP Check the disk label is reasonable. It can't contain certain characters, eg. \f(CW\*(Aq/\*(Aq\fR, \f(CW\*(Aq,\*(Aq\fR. However be stricter here and ensure it's just alphabetic and ≤ 20 characters in length. .PP Function \f(CW\*(C`src/drives.c:valid_hostname\*(C'\fR .IX Subsection "Function src/drives.c:valid_hostname" .PP .Vb 2 \& static int \& valid_hostname (const char *str) .Ve .PP Check the server hostname is reasonable. .PP Function \f(CW\*(C`src/drives.c:valid_port\*(C'\fR .IX Subsection "Function src/drives.c:valid_port" .PP .Vb 2 \& static int \& valid_port (int port) .Ve .PP Check the port number is reasonable. .PP Function \f(CW\*(C`src/drives.c:guestfs_impl_remove_drive\*(C'\fR .IX Subsection "Function src/drives.c:guestfs_impl_remove_drive" .PP .Vb 2 \& int \& guestfs_impl_remove_drive (guestfs_h *g, const char *label) .Ve .PP This function implements \*(L"guestfs_remove_drive\*(R" in \fIguestfs\fR\|(3). .PP Depending on whether we are hotplugging or not, this function does slightly different things: If not hotplugging, then the drive just disappears as if it had never been added. The later drives \*(L"move up\*(R" to fill the space. When hotplugging we have to do some complex stuff, and we usually end up leaving an empty (\f(CW\*(C`NULL\*(C'\fR) slot in the \&\f(CW\*(C`g\->drives\*(C'\fR vector. .PP Function \f(CW\*(C`src/drives.c:guestfs_int_checkpoint_drives\*(C'\fR .IX Subsection "Function src/drives.c:guestfs_int_checkpoint_drives" .PP .Vb 2 \& size_t \& guestfs_int_checkpoint_drives (guestfs_h *g) .Ve .PP Checkpoint and roll back drives, so that groups of drives can be added atomicly. Only used by \*(L"guestfs_add_domain\*(R" in \fIguestfs\fR\|(3). .PP Function \f(CW\*(C`src/drives.c:guestfs_impl_debug_drives\*(C'\fR .IX Subsection "Function src/drives.c:guestfs_impl_debug_drives" .PP .Vb 2 \& char ** \& guestfs_impl_debug_drives (guestfs_h *g) .Ve .PP Internal function to return the list of drives. .PP \fIFile \fIsrc/errors.c\fI\fR .IX Subsection "File src/errors.c" .PP This file handles errors, and also debug, trace and warning messages. .PP Errors in libguestfs \s-1API\s0 calls are handled by setting an error message and optional errno in the handle. The caller has the choice of testing \s-1API\s0 calls to find out if they failed and then querying the last error from the handle, and/or getting a callback. .PP From the point of view of the library source, generally you should use the \f(CW\*(C`error\*(C'\fR or \f(CW\*(C`perrorf\*(C'\fR macros along error paths, eg: .PP .Vb 4 \& if (something_bad) { \& error (g, "something bad happened"); \& return \-1; \& } .Ve .PP Make sure to call the \f(CW\*(C`error\*(C'\fR or \f(CW\*(C`perrorf\*(C'\fR macro exactly once along each error path, since the handle can only store a single error and the previous error will be overwritten. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_warning\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_warning" .PP .Vb 2 \& void \& guestfs_int_warning (guestfs_h *g, const char *fs, ...) .Ve .PP Print a warning. .PP Code should \fInot\fR call this function directly. Use the \&\f(CW\*(C`warning (g, fs, ...)\*(C'\fR macro. .PP Warnings are printed unconditionally. We try to make these rare: Generally speaking, a warning should either be an error, or if it's not important for end users then it should be a debug message. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_debug\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_debug" .PP .Vb 2 \& void \& guestfs_int_debug (guestfs_h *g, const char *fs, ...) .Ve .PP Print a debug message. .PP Code should \fInot\fR call this function directly. To add debug messages in the library, use the \f(CW\*(C`debug (g, fs, ...)\*(C'\fR macro. The macro checks if \f(CW\*(C`g\->verbose\*(C'\fR is false and avoids the function call, meaning the macro is more efficient. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_trace\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_trace" .PP .Vb 2 \& void \& guestfs_int_trace (guestfs_h *g, const char *fs, ...) .Ve .PP Print a trace message. .PP Do not call this function. All calls are generated automatically. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_error_errno\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_error_errno" .PP .Vb 2 \& void \& guestfs_int_error_errno (guestfs_h *g, int errnum, const char *fs, ...) .Ve .PP Set the last error and errno in the handle, and optionally raise the error callback if one is defined. .PP If you don't need to set errno, use the \f(CW\*(C`error (g, fs, ...)\*(C'\fR macro instead of calling this directly. If you need to set errno then there is no macro wrapper, so calling this function directly is fine. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_perrorf\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_perrorf" .PP .Vb 2 \& void \& guestfs_int_perrorf (guestfs_h *g, const char *fs, ...) .Ve .PP Similar to \fIperror\fR\|(3), but it sets the last error in the handle, raises the error callback if one is defined, and supports format strings. .PP You should probably use the \f(CW\*(C`perrorf (g, fs, ...)\*(C'\fR macro instead of calling this directly. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_launch_failed_error\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_launch_failed_error" .PP .Vb 2 \& void \& guestfs_int_launch_failed_error (guestfs_h *g) .Ve .PP Raise a launch failed error in a standard format. .PP Since this is the most common error seen by people who have installation problems, buggy qemu, etc, and since no one reads the \&\s-1FAQ,\s0 describe in this error message what resources are available to debug launch problems. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_unexpected_close_error\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_unexpected_close_error" .PP .Vb 2 \& void \& guestfs_int_unexpected_close_error (guestfs_h *g) .Ve .PP Raise an error if the appliance unexpectedly crashes after launch. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_launch_timeout\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_launch_timeout" .PP .Vb 2 \& void \& guestfs_int_launch_timeout (guestfs_h *g) .Ve .PP Raise an error if the appliance hangs during launch. .PP Function \f(CW\*(C`src/errors.c:guestfs_int_external_command_failed\*(C'\fR .IX Subsection "Function src/errors.c:guestfs_int_external_command_failed" .PP .Vb 3 \& void \& guestfs_int_external_command_failed (guestfs_h *g, int status, \& const char *cmd_name, const char *extra) .Ve .PP Raise an error if an external command fails. .PP \&\f(CW\*(C`status\*(C'\fR is the status code of the command (eg. returned from \&\fIwaitpid\fR\|(2) or \fIsystem\fR\|(3)). This function turns the status code into an explanatory string. .PP \fIFile \fIsrc/events.c\fI\fR .IX Subsection "File src/events.c" .PP Function \f(CW\*(C`src/events.c:replace_old_style_event_callback\*(C'\fR .IX Subsection "Function src/events.c:replace_old_style_event_callback" .PP .Vb 6 \& static void \& replace_old_style_event_callback (guestfs_h *g, \& guestfs_event_callback cb, \& uint64_t event_bitmask, \& void *opaque, \& void *opaque2) .Ve .PP Emulate old-style callback \s-1API.\s0 .PP There were no event handles, so multiple callbacks per event were not supported. Calling the same \f(CW\*(C`guestfs_set_*_callback\*(C'\fR function would replace the existing event. Calling it with \f(CW\*(C`cb == NULL\*(C'\fR meant that the caller wanted to remove the callback. .PP \fIFile \fIsrc/guestfs\-internal\-all.h\fI\fR .IX Subsection "File src/guestfs-internal-all.h" .PP This header contains definitions which are shared by all parts of libguestfs, ie. the daemon, the library, language bindings and virt tools (ie. \fIall\fR C code). .PP If you need a definition used by only the library, put it in \&\fIsrc/guestfs\-internal.h\fR instead. If you need a definition used by only the frontend (non-daemon) parts of libguestfs, try \&\fIsrc/guestfs\-internal\-frontend.h\fR. If a definition is used by only a single tool, it should not be in any shared header file at all. .PP \fIFile \fIsrc/guestfs\-internal\-frontend.h\fI\fR .IX Subsection "File src/guestfs-internal-frontend.h" .PP This header file is included in all \*(L"frontend\*(R" parts of libguestfs, namely the library, non-C language bindings, virt tools and tests. .PP The daemon does \fBnot\fR use this header. If you need a place to put something shared with absolutely everything including the daemon, put it in \fIsrc/guestfs\-internal\-all.h\fR .PP If a definition is only needed by a single component of libguestfs (eg. just the library, or just a single virt tool) then it should \&\fBnot\fR be here! .PP \fIFile \fIsrc/guestfs\-internal.h\fI\fR .IX Subsection "File src/guestfs-internal.h" .PP This header file is included in the libguestfs library (\fIsrc/\fR) only. .PP See also \fIsrc/guestfs\-internal\-frontend.h\fR and \&\fIsrc/guestfs\-internal\-all.h\fR .PP Structure \f(CW\*(C`src/guestfs\-internal.h:event\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:event" .PP .Vb 4 \& struct event { \& uint64_t event_bitmask; \& guestfs_event_callback cb; \& void *opaque; \& \& /* opaque2 is not exposed through the API, but is used internally to \& * emulate the old\-style callback API. \& */ \& void *opaque2; \& }; .Ve .PP This struct is used to maintain a list of events registered against the handle. See \f(CW\*(C`g\->events\*(C'\fR in the handle. .PP Structure \f(CW\*(C`src/guestfs\-internal.h:drive\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:drive" .PP .Vb 3 \& struct drive { \& /* Original source of the drive, eg. file:..., http:... */ \& struct drive_source src; \& \& /* If the drive is readonly, then an overlay [a local file] is \& * created before launch to protect the original drive content, and \& * the filename is stored here. Backends should open this file if \& * it is non\-NULL, else consult the original source above. \& * \& * Note that the overlay is in a backend\-specific format, probably \& * different from the source format. eg. qcow2, UML COW. \& */ \& char *overlay; \& \& /* Various per\-drive flags. */ \& bool readonly; \& char *iface; \& char *name; \& char *disk_label; \& char *cachemode; \& enum discard discard; \& bool copyonread; \& }; .Ve .PP There is one \f(CW\*(C`struct drive\*(C'\fR per drive, including hot-plugged drives. .PP Structure \f(CW\*(C`src/guestfs\-internal.h:backend_ops\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:backend_ops" .PP .Vb 9 \& struct backend_ops { \& /* Size (in bytes) of the per\-handle data structure needed by this \& * backend. The data pointer is allocated and freed by libguestfs \& * and passed to the functions in the \*(Aqvoid *data\*(Aq parameter. \& * Inside the data structure is opaque to libguestfs. Any strings \& * etc pointed to by it must be freed by the backend during \& * shutdown. \& */ \& size_t data_size; \& \& /* Create a COW overlay on top of a drive. This must be a local \& * file, created in the temporary directory. This is called when \& * the drive is added to the handle. \& */ \& char *(*create_cow_overlay) (guestfs_h *g, void *data, struct drive *drv); \& \& /* Launch and shut down. */ \& int (*launch) (guestfs_h *g, void *data, const char *arg); \& int (*shutdown) (guestfs_h *g, void *data, int check_for_errors); \& \& /* Miscellaneous. */ \& int (*get_pid) (guestfs_h *g, void *data); \& int (*max_disks) (guestfs_h *g, void *data); \& \& /* Hotplugging drives. */ \& int (*hot_add_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index); \& int (*hot_remove_drive) (guestfs_h *g, void *data, struct drive *drv, size_t drv_index); \& }; .Ve .PP Backend operations. .PP Each backend (eg. libvirt, direct) defines some functions which get run at various places in the handle lifecycle (eg. at launch, shutdown). The backend defines this struct pointing to those functions. .PP Structure \f(CW\*(C`src/guestfs\-internal.h:connection\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:connection" .PP .Vb 2 \& struct connection { \& const struct connection_ops *ops; \& \& /* In the real struct, private data used by each connection module \& * follows here. \& */ \& }; .Ve .PP Connection module. .PP A \f(CW\*(C`connection\*(C'\fR represents the appliance console connection plus the daemon connection. It hides the underlying representation (\s-1POSIX\s0 sockets, \f(CW\*(C`virStreamPtr\*(C'\fR). .PP Structure \f(CW\*(C`src/guestfs\-internal.h:error_cb_stack\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:error_cb_stack" .PP .Vb 5 \& struct error_cb_stack { \& struct error_cb_stack *next; \& guestfs_error_handler_cb error_cb; \& void * error_cb_data; \& }; .Ve .PP Stack of old error handlers. .PP Structure \f(CW\*(C`src/guestfs\-internal.h:cached_feature\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:cached_feature" .PP .Vb 4 \& struct cached_feature { \& char *group; \& int result; \& }; .Ve .PP Cache of queried features. .PP Used to cache the appliance features (see \fIsrc/available.c\fR). .PP Structure \f(CW\*(C`src/guestfs\-internal.h:guestfs_h\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:guestfs_h" .PP .Vb 3 \& struct guestfs_h { \& struct guestfs_h *next; /* Linked list of open handles. */ \& enum state state; /* See the state machine diagram in guestfs(3)*/ \& \& /**** Configuration of the handle. ****/ \& bool verbose; /* Debugging. */ \& bool trace; /* Trace calls. */ \& bool autosync; /* Autosync. */ \& bool direct_mode; /* Direct mode. */ \& bool recovery_proc; /* Create a recovery process. */ \& bool enable_network; /* Enable the network. */ \& bool selinux; /* selinux enabled? */ \& bool pgroup; /* Create process group for children? */ \& bool close_on_exit; /* Is this handle on the atexit list? */ \& \& int smp; /* If > 1, \-smp flag passed to hv. */ \& int memsize; /* Size of RAM (megabytes). */ \& \& char *path; /* Path to the appliance. */ \& char *hv; /* Hypervisor (HV) binary. */ \& char *append; /* Append to kernel command line. */ \& \& struct hv_param *hv_params; /* Extra hv parameters. */ \& \& char *program; /* Program name. */ \& char *identifier; /* Handle identifier. */ \& \& /* Array of drives added by add\-drive* APIs. \& * \& * Before launch this list can be empty or contain some drives. \& * \& * During launch, a dummy slot may be added which represents the \& * slot taken up by the appliance drive. \& * \& * When hotplugging is supported by the backend, drives can be \& * added to the end of this list after launch. Also hot\-removing a \& * drive causes a NULL slot to appear in the list. \& * \& * During shutdown, this list is deleted, so that each launch gets a \& * fresh set of drives (however callers: don\*(Aqt do this, create a new \& * handle each time). \& * \& * Always use ITER_DRIVES macro to iterate over this list! \& */ \& struct drive **drives; \& size_t nr_drives; \& \& #define ITER_DRIVES(g,i,drv) \e \& for (i = 0; i < (g)\->nr_drives; ++i) \e \& if (((drv) = (g)\->drives[i]) != NULL) \& \& /* Backend. NB: Use guestfs_int_set_backend to change the backend. */ \& char *backend; /* The full string, always non\-NULL. */ \& char *backend_arg; /* Pointer to the argument part. */ \& const struct backend_ops *backend_ops; \& void *backend_data; /* Per\-handle data. */ \& char **backend_settings; /* Backend settings (can be NULL). */ \& \& /**** Runtime information. ****/ \& char *last_error; /* Last error on handle. */ \& int last_errnum; /* errno, or 0 if there was no errno */ \& \& /* Temporary and cache directories. */ \& /* The actual temporary directory \- this is not created with the \& * handle, you have to call guestfs_int_lazy_make_tmpdir. \& */ \& char *tmpdir; \& char *sockdir; \& /* Environment variables that affect tmpdir/cachedir/sockdir locations. */ \& char *env_tmpdir; /* $TMPDIR (NULL if not set) */ \& char *env_runtimedir; /* $XDG_RUNTIME_DIR (NULL if not set)*/ \& char *int_tmpdir; /* $LIBGUESTFS_TMPDIR or guestfs_set_tmpdir or NULL */ \& char *int_cachedir; /* $LIBGUESTFS_CACHEDIR or guestfs_set_cachedir or NULL */ \& \& /* Error handler, plus stack of old error handlers. */ \& guestfs_error_handler_cb error_cb; \& void * error_cb_data; \& struct error_cb_stack *error_cb_stack; \& \& /* Out of memory error handler. */ \& guestfs_abort_cb abort_cb; \& \& /* Events. */ \& struct event *events; \& size_t nr_events; \& \& /* Information gathered by inspect_os. Must be freed by calling \& * guestfs_int_free_inspect_info. \& */ \& struct inspect_fs *fses; \& size_t nr_fses; \& \& /* Private data area. */ \& struct hash_table *pda; \& struct pda_entry *pda_next; \& \& /* User cancelled transfer. Not signal\-atomic, but it doesn\*(Aqt \& * matter for this case because we only care if it is != 0. \& */ \& int user_cancel; \& \& struct timeval launch_t; /* The time that we called guestfs_launch. */ \& \& /* Used by bindtests. */ \& FILE *test_fp; \& \& /* Used to generate unique numbers, eg for temp files. To use this, \& * \*(Aq++g\->unique\*(Aq. Note these are only unique per\-handle, not \& * globally unique. \& */ \& int unique; \& \& /*** Protocol. ***/ \& struct connection *conn; /* Connection to appliance. */ \& int msg_next_serial; \& \& #if HAVE_FUSE \& /**** Used by the mount\-local APIs. ****/ \& const char *localmountpoint; \& struct fuse *fuse; /* FUSE handle. */ \& int ml_dir_cache_timeout; /* Directory cache timeout. */ \& Hash_table *lsc_ht, *xac_ht, *rlc_ht; /* Directory cache. */ \& int ml_read_only; /* If mounted read\-only. */ \& int ml_debug_calls; /* Extra debug info on each FUSE call. */ \& #endif \& \& #ifdef HAVE_LIBVIRT_BACKEND \& /* Used by src/libvirt\-auth.c. */ \& #define NR_CREDENTIAL_TYPES 9 \& unsigned int nr_supported_credentials; \& int supported_credentials[NR_CREDENTIAL_TYPES]; \& const char *saved_libvirt_uri; /* Doesn\*(Aqt need to be freed. */ \& bool wrapper_warning_done; \& unsigned int nr_requested_credentials; \& virConnectCredentialPtr requested_credentials; \& #endif \& \& /* Cached features. */ \& struct cached_feature *features; \& size_t nr_features; \& }; .Ve .PP The libguestfs handle. .PP Structure \f(CW\*(C`src/guestfs\-internal.h:version\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:version" .PP .Vb 5 \& struct version { \& int v_major; \& int v_minor; \& int v_micro; \& }; .Ve .PP Used for storing major.minor.micro version numbers. See \fIsrc/version.c\fR for more information. .PP Structure \f(CW\*(C`src/guestfs\-internal.h:inspect_fs\*(C'\fR .IX Subsection "Structure src/guestfs-internal.h:inspect_fs" .PP .Vb 10 \& struct inspect_fs { \& int is_root; \& char *mountable; \& enum inspect_os_type type; \& enum inspect_os_distro distro; \& enum inspect_os_package_format package_format; \& enum inspect_os_package_management package_management; \& char *product_name; \& char *product_variant; \& struct version version; \& char *arch; \& char *hostname; \& char *windows_systemroot; \& char *windows_current_control_set; \& char **drive_mappings; \& enum inspect_os_format format; \& int is_live_disk; \& int is_netinst_disk; \& int is_multipart_disk; \& struct inspect_fstab_entry *fstab; \& size_t nr_fstab; \& }; .Ve .PP The inspection code maintains one of these structures per mountable filesystem found in the disk image. The struct (or structs) which have the \f(CW\*(C`is_root\*(C'\fR flag set are inspection roots, each corresponding to a single guest. Note that a filesystem can be shared between multiple guests. .PP \fIFile \fIsrc/guid.c\fI\fR .IX Subsection "File src/guid.c" .PP Function \f(CW\*(C`src/guid.c:guestfs_int_validate_guid\*(C'\fR .IX Subsection "Function src/guid.c:guestfs_int_validate_guid" .PP .Vb 2 \& int \& guestfs_int_validate_guid (const char *str) .Ve .PP Check whether a string supposed to contain a \s-1GUID\s0 actually contains it. It can recognize strings either as \&\f(CW\*(C`{21EC2020\-3AEA\-1069\-A2DD\-08002B30309D}\*(C'\fR or \&\f(CW\*(C`21EC2020\-3AEA\-1069\-A2DD\-08002B30309D\*(C'\fR. .PP \fIFile \fIsrc/handle.c\fI\fR .IX Subsection "File src/handle.c" .PP This file deals with the \f(CW\*(C`guestfs_h\*(C'\fR handle, creating it, closing it, and initializing/setting/getting fields. .PP Function \f(CW\*(C`src/handle.c:init_libguestfs\*(C'\fR .IX Subsection "Function src/handle.c:init_libguestfs" .PP .Vb 2 \& static void \& init_libguestfs (void) .Ve .PP No initialization is required by libguestfs, but libvirt and libxml2 require initialization if they might be called from multiple threads. Hence this constructor function which is called when libguestfs is first loaded. .PP Function \f(CW\*(C`src/handle.c:shutdown_backend\*(C'\fR .IX Subsection "Function src/handle.c:shutdown_backend" .PP .Vb 2 \& static int \& shutdown_backend (guestfs_h *g, int check_for_errors) .Ve .PP This function is the common path for shutting down the backend qemu process. .PP \&\f(CW\*(C`guestfs_shutdown\*(C'\fR calls \f(CW\*(C`shutdown_backend\*(C'\fR with \&\f(CW\*(C`check_for_errors=1\*(C'\fR. \f(CW\*(C`guestfs_close\*(C'\fR calls \f(CW\*(C`shutdown_backend\*(C'\fR with \f(CW\*(C`check_for_errors=0\*(C'\fR. .PP \&\f(CW\*(C`check_for_errors\*(C'\fR is a hint to the backend about whether we care about errors or not. In the libvirt case it can be used to optimize the shutdown for speed when we don't care. .PP Function \f(CW\*(C`src/handle.c:close_handles\*(C'\fR .IX Subsection "Function src/handle.c:close_handles" .PP .Vb 2 \& static void \& close_handles (void) .Ve .PP Close all open handles (called from \fIatexit\fR\|(3)). .PP Function \f(CW\*(C`src/handle.c:guestfs_int_get_backend_setting_bool\*(C'\fR .IX Subsection "Function src/handle.c:guestfs_int_get_backend_setting_bool" .PP .Vb 2 \& int \& guestfs_int_get_backend_setting_bool (guestfs_h *g, const char *name) .Ve .PP This is a convenience function, but we might consider exporting it as an \s-1API\s0 in future. .PP \fIFile \fIsrc/inspect.c\fI\fR .IX Subsection "File src/inspect.c" .PP This file, and the other \f(CW\*(C`src/inspect*.c\*(C'\fR files, handle inspection. See \*(L"\s-1INSPECTION\*(R"\s0 in \fIguestfs\fR\|(3). .PP Function \f(CW\*(C`src/inspect.c:guestfs_impl_inspect_os\*(C'\fR .IX Subsection "Function src/inspect.c:guestfs_impl_inspect_os" .PP .Vb 2 \& char ** \& guestfs_impl_inspect_os (guestfs_h *g) .Ve .PP The main inspection \s-1API.\s0 .PP Function \f(CW\*(C`src/inspect.c:collect_coreos_inspection_info\*(C'\fR .IX Subsection "Function src/inspect.c:collect_coreos_inspection_info" .PP .Vb 2 \& static void \& collect_coreos_inspection_info (guestfs_h *g) .Ve .PP Traverse through the filesystem list and find out if it contains the \f(CW\*(C`/\*(C'\fR and \f(CW\*(C`/usr\*(C'\fR filesystems of a CoreOS image. If this is the case, sum up all the collected information on the root fs. .PP Function \f(CW\*(C`src/inspect.c:check_for_duplicated_bsd_root\*(C'\fR .IX Subsection "Function src/inspect.c:check_for_duplicated_bsd_root" .PP .Vb 2 \& static void \& check_for_duplicated_bsd_root (guestfs_h *g) .Ve .PP On *BSD systems, sometimes \fI/dev/sda[1234]\fR is a shadow of the real root filesystem that is probably \fI/dev/sda5\fR (see: http://www.freebsd.org/doc/handbook/disk\-organization.html) .PP Function \f(CW\*(C`src/inspect.c:guestfs_int_download_to_tmp\*(C'\fR .IX Subsection "Function src/inspect.c:guestfs_int_download_to_tmp" .PP .Vb 4 \& char * \& guestfs_int_download_to_tmp (guestfs_h *g, struct inspect_fs *fs, \& const char *filename, \& const char *basename, uint64_t max_size) .Ve .PP Download a guest file to a local temporary file. The file is cached in the temporary directory, and is not downloaded again. .PP The name of the temporary (downloaded) file is returned. The caller must free the pointer, but does \fInot\fR need to delete the temporary file. It will be deleted when the handle is closed. .PP Refuse to download the guest file if it is larger than \f(CW\*(C`max_size\*(C'\fR. On this and other errors, \f(CW\*(C`NULL\*(C'\fR is returned. .PP There is actually one cache per \f(CW\*(C`struct inspect_fs *\*(C'\fR in order to handle the case of multiple roots. .PP \fIFile \fIsrc/launch\-direct.c\fI\fR .IX Subsection "File src/launch-direct.c" .PP Implementation of the \f(CW\*(C`direct\*(C'\fR backend. .PP For more details see \*(L"\s-1BACKENDS\*(R"\s0 in \fIguestfs\fR\|(3). .PP \fIFile \fIsrc/launch\-libvirt.c\fI\fR .IX Subsection "File src/launch-libvirt.c" .PP Function \f(CW\*(C`src/launch\-libvirt.c:get_source_format_or_autodetect\*(C'\fR .IX Subsection "Function src/launch-libvirt.c:get_source_format_or_autodetect" .PP .Vb 2 \& static char * \& get_source_format_or_autodetect (guestfs_h *g, struct drive *drv) .Ve .PP Return \f(CW\*(C`drv\->src.format\*(C'\fR, but if it is \f(CW\*(C`NULL\*(C'\fR, autodetect the format. .PP libvirt has disabled the feature of detecting the disk format, unless the administrator sets \f(CW\*(C`allow_disk_format_probing=1\*(C'\fR in \&\fI/etc/libvirt/qemu.conf\fR. There is no way to detect if this option is set, so we have to do format detection here using \&\f(CW\*(C`qemu\-img\*(C'\fR and pass that to libvirt. .PP This can still be a security issue, so in most cases it is recommended the users pass the format to libguestfs which will faithfully pass that straight through to libvirt without doing autodetection. .PP Caller must free the returned string. On error this function sets the error in the handle and returns \f(CW\*(C`NULL\*(C'\fR. .PP Function \f(CW\*(C`src/launch\-libvirt.c:make_qcow2_overlay\*(C'\fR .IX Subsection "Function src/launch-libvirt.c:make_qcow2_overlay" .PP .Vb 3 \& static char * \& make_qcow2_overlay (guestfs_h *g, const char *backing_drive, \& const char *format) .Ve .PP Create a qcow2 format overlay, with the given \f(CW\*(C`backing_drive\*(C'\fR (file). The \f(CW\*(C`format\*(C'\fR parameter, which must be non-NULL, is the backing file format. This is used to create the appliance overlay, and also for read-only drives. .PP \fIFile \fIsrc/launch.c\fI\fR .IX Subsection "File src/launch.c" .PP This file implements \*(L"guestfs_launch\*(R" in \fIguestfs\fR\|(3). .PP Most of the work is done by the backends (see \&\*(L"\s-1BACKEND\*(R"\s0 in \fIguestfs\fR\|(3)), which are implemented in \&\fIsrc/launch\-direct.c\fR, \fIsrc/launch\-libvirt.c\fR etc, so this file mostly passes calls through to the current backend. .PP Function \f(CW\*(C`src/launch.c:guestfs_int_launch_send_progress\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_int_launch_send_progress" .PP .Vb 2 \& void \& guestfs_int_launch_send_progress (guestfs_h *g, int perdozen) .Ve .PP This function sends a launch progress message. .PP Launching the appliance generates approximate progress messages. Currently these are defined as follows: .PP .Vb 5 \& 0 / 12: launch clock starts \& 3 / 12: appliance created \& 6 / 12: detected that guest kernel started \& 9 / 12: detected that /init script is running \& 12 / 12: launch completed successfully .Ve .PP Notes: .IP "1." 4 This is not a documented \s-1ABI\s0 and the behaviour may be changed or removed in future. .IP "2." 4 Messages are only sent if more than 5 seconds has elapsed since the launch clock started. .IP "3." 4 There is a hack in \fIsrc/proto.c\fR to make this work. .PP Function \f(CW\*(C`src/launch.c:guestfs_int_timeval_diff\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_int_timeval_diff" .PP .Vb 2 \& int64_t \& guestfs_int_timeval_diff (const struct timeval *x, const struct timeval *y) .Ve .PP Compute \f(CW\*(C`y \- x\*(C'\fR and return the result in milliseconds. .PP Approximately the same as this code: http://www.mpp.mpg.de/~huber/util/timevaldiff.c .PP Function \f(CW\*(C`src/launch.c:guestfs_impl_max_disks\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_impl_max_disks" .PP .Vb 2 \& int \& guestfs_impl_max_disks (guestfs_h *g) .Ve .PP Returns the maximum number of disks allowed to be added to the backend (backend dependent). .PP Function \f(CW\*(C`src/launch.c:guestfs_impl_wait_ready\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_impl_wait_ready" .PP .Vb 2 \& int \& guestfs_impl_wait_ready (guestfs_h *g) .Ve .PP Implementation of \*(L"guestfs_wait_ready\*(R" in \fIguestfs\fR\|(3). You had to call this function after launch in versions ≤ 1.0.70, but it is now an (almost) no-op. .PP Function \f(CW\*(C`src/launch.c:valid_term\*(C'\fR .IX Subsection "Function src/launch.c:valid_term" .PP .Vb 2 \& static bool \& valid_term (const char *term) .Ve .PP Check that the \f(CW$TERM\fR environment variable is reasonable before we pass it through to the appliance. .PP Function \f(CW\*(C`src/launch.c:guestfs_int_appliance_command_line\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_int_appliance_command_line" .PP .Vb 3 \& char * \& guestfs_int_appliance_command_line (guestfs_h *g, const char *appliance_dev, \& int flags) .Ve .PP Construct the Linux command line passed to the appliance. This is used by the \f(CW\*(C`direct\*(C'\fR and \f(CW\*(C`libvirt\*(C'\fR backends, and is simply located in this file because it's a convenient place for this common code. .PP The \f(CW\*(C`appliance_dev\*(C'\fR parameter must be the full device name of the appliance disk and must have already been adjusted to take into account virtio-blk or virtio-scsi; eg \f(CW\*(C`/dev/sdb\*(C'\fR. .PP The \f(CW\*(C`flags\*(C'\fR parameter can contain the following flags logically or'd together (or 0): .ie n .IP """APPLIANCE_COMMAND_LINE_IS_TCG""" 4 .el .IP "\f(CWAPPLIANCE_COMMAND_LINE_IS_TCG\fR" 4 .IX Item "APPLIANCE_COMMAND_LINE_IS_TCG" If we are launching a qemu \s-1TCG\s0 guest (ie. \s-1KVM\s0 is known to be disabled or unavailable). If you don't know, don't pass this flag. .PP Note that this function returns a newly allocated buffer which must be freed by the caller. .PP Function \f(CW\*(C`src/launch.c:guestfs_int_get_cpu_model\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_int_get_cpu_model" .PP .Vb 2 \& const char * \& guestfs_int_get_cpu_model (int kvm) .Ve .PP Return the right \s-1CPU\s0 model to use as the qemu \f(CW\*(C`\-cpu\*(C'\fR parameter or its equivalent in libvirt. This returns: .ie n .IP """host""" 4 .el .IP "\f(CW``host''\fR" 4 .IX Item """host""" The literal string \f(CW"host"\fR means use \f(CW\*(C`\-cpu host\*(C'\fR. .IP "some string" 4 .IX Item "some string" Some string such as \f(CW"cortex\-a57"\fR means use \f(CW\*(C`\-cpu cortex\-a57\*(C'\fR. .ie n .IP """NULL""" 4 .el .IP "\f(CWNULL\fR" 4 .IX Item "NULL" \&\f(CW\*(C`NULL\*(C'\fR means no \f(CW\*(C`\-cpu\*(C'\fR option at all. Note returning \f(CW\*(C`NULL\*(C'\fR does not indicate an error. .PP This is made unnecessarily hard and fragile because of two stupid choices in \s-1QEMU:\s0 .IP "\(bu" 4 The default for \f(CW\*(C`qemu\-system\-aarch64 \-M virt\*(C'\fR is to emulate a \&\f(CW\*(C`cortex\-a15\*(C'\fR (\s-1WTF\s0?). .IP "\(bu" 4 We don't know for sure if \s-1KVM\s0 will work, but \f(CW\*(C`\-cpu host\*(C'\fR is broken with \s-1TCG,\s0 so we almost always pass a broken \f(CW\*(C`\-cpu\*(C'\fR flag if \s-1KVM\s0 is semi-broken in any way. .PP Function \f(CW\*(C`src/launch.c:guestfs_int_create_socketname\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_int_create_socketname" .PP .Vb 3 \& int \& guestfs_int_create_socketname (guestfs_h *g, const char *filename, \& char (*sockpath)[UNIX_PATH_MAX]) .Ve .PP Create the path for a socket with the selected filename in the tmpdir. .PP Function \f(CW\*(C`src/launch.c:guestfs_int_register_backend\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_int_register_backend" .PP .Vb 2 \& void \& guestfs_int_register_backend (const char *name, const struct backend_ops *ops) .Ve .PP When the library is loaded, each backend calls this function to register itself in a global list. .PP Function \f(CW\*(C`src/launch.c:guestfs_int_set_backend\*(C'\fR .IX Subsection "Function src/launch.c:guestfs_int_set_backend" .PP .Vb 2 \& int \& guestfs_int_set_backend (guestfs_h *g, const char *method) .Ve .PP Implementation of \*(L"guestfs_set_backend\*(R" in \fIguestfs\fR\|(3). .IP "\(bu" 4 Callers must ensure this is only called in the config state. .IP "\(bu" 4 This shouldn't call \f(CW\*(C`error\*(C'\fR since it may be called early in handle initialization. It can return an error code however. .PP \fIFile \fIsrc/private\-data.c\fI\fR .IX Subsection "File src/private-data.c" .PP Implement a private data area where libguestfs C \s-1API\s0 users can attach arbitrary pieces of data to a \f(CW\*(C`guestfs_h\*(C'\fR handle. .PP For more information see \*(L"\s-1PRIVATE DATA AREA\*(R"\s0 in \fIguestfs\fR\|(3). .PP Language bindings do not generally expose this, largely because in non-C languages it is easy to associate data with handles in other ways (using hash tables or maps). .PP Structure \f(CW\*(C`src/private\-data.c:pda_entry\*(C'\fR .IX Subsection "Structure src/private-data.c:pda_entry" .PP .Vb 4 \& struct pda_entry { \& char *key; /* key */ \& void *data; /* opaque user data pointer */ \& }; .Ve .PP The private data area is internally stored as a gnulib hash table containing \f(CW\*(C`pda_entry\*(C'\fR structures. .PP Note the private data area is allocated lazily, since the vast majority of callers will never use it. This means \f(CW\*(C`g\->pda\*(C'\fR is likely to be \f(CW\*(C`NULL\*(C'\fR. .PP \fIFile \fIsrc/proto.c\fI\fR .IX Subsection "File src/proto.c" .PP This is the code used to send and receive \s-1RPC\s0 messages and (for certain types of message) to perform file transfers. This code is driven from the generated actions (\fIsrc/actions\-*.c\fR). There are five different cases to consider: .IP "1." 4 A non-daemon function (eg. \*(L"guestfs_set_verbose\*(R" in \fIguestfs\fR\|(3)). There is no \s-1RPC\s0 involved at all, it's all handled inside the library. .IP "2." 4 A simple \s-1RPC \s0(eg. \*(L"guestfs_mount\*(R" in \fIguestfs\fR\|(3)). We write the request, then read the reply. The sequence of calls is: .Sp .Vb 2 \& guestfs_int_send \& guestfs_int_recv .Ve .IP "3." 4 An \s-1RPC\s0 with \f(CW\*(C`FileIn\*(C'\fR parameters (eg. \*(L"guestfs_upload\*(R" in \fIguestfs\fR\|(3)). We write the request, then write the file(s), then read the reply. The sequence of calls is: .Sp .Vb 3 \& guestfs_int_send \& guestfs_int_send_file (possibly multiple times) \& guestfs_int_recv .Ve .IP "4." 4 An \s-1RPC\s0 with \f(CW\*(C`FileOut\*(C'\fR parameters (eg. \*(L"guestfs_download\*(R" in \fIguestfs\fR\|(3)). We write the request, then read the reply, then read the file(s). The sequence of calls is: .Sp .Vb 3 \& guestfs_int_send \& guestfs_int_recv \& guestfs_int_recv_file (possibly multiple times) .Ve .IP "5." 4 Both \f(CW\*(C`FileIn\*(C'\fR and \f(CW\*(C`FileOut\*(C'\fR parameters. There are no calls like this in the current \s-1API,\s0 but they would be implemented as a combination of cases 3 and 4. .PP All read/write/etc operations are performed using the current connection module (\f(CW\*(C`g\->conn\*(C'\fR). During operations the connection module transparently handles log messages that appear on the console. .PP Function \f(CW\*(C`src/proto.c:child_cleanup\*(C'\fR .IX Subsection "Function src/proto.c:child_cleanup" .PP .Vb 2 \& static void \& child_cleanup (guestfs_h *g) .Ve .PP This is called if we detect \s-1EOF,\s0 ie. qemu died. .PP Function \f(CW\*(C`src/proto.c:guestfs_int_progress_message_callback\*(C'\fR .IX Subsection "Function src/proto.c:guestfs_int_progress_message_callback" .PP .Vb 3 \& void \& guestfs_int_progress_message_callback (guestfs_h *g, \& const guestfs_progress *message) .Ve .PP Convenient wrapper to generate a progress message callback. .PP Function \f(CW\*(C`src/proto.c:guestfs_int_log_message_callback\*(C'\fR .IX Subsection "Function src/proto.c:guestfs_int_log_message_callback" .PP .Vb 2 \& void \& guestfs_int_log_message_callback (guestfs_h *g, const char *buf, size_t len) .Ve .PP Connection modules call us back here when they get a log message. .PP Function \f(CW\*(C`src/proto.c:check_daemon_socket\*(C'\fR .IX Subsection "Function src/proto.c:check_daemon_socket" .PP .Vb 2 \& static ssize_t \& check_daemon_socket (guestfs_h *g) .Ve .PP Before writing to the daemon socket, check the read side of the daemon socket for any of these conditions: .IP "error" 4 .IX Item "error" return \-1 .IP "daemon cancellation message" 4 .IX Item "daemon cancellation message" return \-2 .IP "progress message" 4 .IX Item "progress message" handle it here .IP "end of input or appliance exited unexpectedly" 4 .IX Item "end of input or appliance exited unexpectedly" return 0 .IP "anything else" 4 .IX Item "anything else" return 1 .PP Function \f(CW\*(C`src/proto.c:guestfs_int_send_file\*(C'\fR .IX Subsection "Function src/proto.c:guestfs_int_send_file" .PP .Vb 2 \& int \& guestfs_int_send_file (guestfs_h *g, const char *filename) .Ve .PP Send a file. .PP Returns \f(CW0\fR on success, \f(CW\*(C`\-1\*(C'\fR for error, \f(CW\*(C`\-2\*(C'\fR if the daemon cancelled (we must read the error message). .PP Function \f(CW\*(C`src/proto.c:send_file_data\*(C'\fR .IX Subsection "Function src/proto.c:send_file_data" .PP .Vb 2 \& static int \& send_file_data (guestfs_h *g, const char *buf, size_t len) .Ve .PP Send a chunk of file data. .PP Function \f(CW\*(C`src/proto.c:send_file_cancellation\*(C'\fR .IX Subsection "Function src/proto.c:send_file_cancellation" .PP .Vb 2 \& static int \& send_file_cancellation (guestfs_h *g) .Ve .PP Send a cancellation message. .PP Function \f(CW\*(C`src/proto.c:send_file_complete\*(C'\fR .IX Subsection "Function src/proto.c:send_file_complete" .PP .Vb 2 \& static int \& send_file_complete (guestfs_h *g) .Ve .PP Send a file complete chunk. .PP Function \f(CW\*(C`src/proto.c:recv_from_daemon\*(C'\fR .IX Subsection "Function src/proto.c:recv_from_daemon" .PP .Vb 2 \& static int \& recv_from_daemon (guestfs_h *g, uint32_t *size_rtn, void **buf_rtn) .Ve .PP This function reads a single message, file chunk, launch flag or cancellation flag from the daemon. If something was read, it returns \f(CW0\fR, otherwise \f(CW\*(C`\-1\*(C'\fR. .PP Both \f(CW\*(C`size_rtn\*(C'\fR and \f(CW\*(C`buf_rtn\*(C'\fR must be passed by the caller as non-NULL. .PP \&\f(CW*size_rtn\fR returns the size of the returned message or it may be \&\f(CW\*(C`GUESTFS_LAUNCH_FLAG\*(C'\fR or \f(CW\*(C`GUESTFS_CANCEL_FLAG\*(C'\fR. .PP \&\f(CW*buf_rtn\fR is returned containing the message (if any) or will be set to \f(CW\*(C`NULL\*(C'\fR. \f(CW*buf_rtn\fR must be freed by the caller. .PP This checks for \s-1EOF \s0(appliance died) and passes that up through the child_cleanup function above. .PP Log message, progress messages are handled transparently here. .PP Function \f(CW\*(C`src/proto.c:guestfs_int_recv\*(C'\fR .IX Subsection "Function src/proto.c:guestfs_int_recv" .PP .Vb 5 \& int \& guestfs_int_recv (guestfs_h *g, const char *fn, \& guestfs_message_header *hdr, \& guestfs_message_error *err, \& xdrproc_t xdrp, char *ret) .Ve .PP Receive a reply. .PP Function \f(CW\*(C`src/proto.c:guestfs_int_recv_discard\*(C'\fR .IX Subsection "Function src/proto.c:guestfs_int_recv_discard" .PP .Vb 2 \& int \& guestfs_int_recv_discard (guestfs_h *g, const char *fn) .Ve .PP Same as \f(CW\*(C`guestfs_int_recv\*(C'\fR, but it discards the reply message. .PP Notes (\s-1XXX\s0): .IP "\(bu" 4 This returns an int, but all current callers ignore it. .IP "\(bu" 4 The error string may end up being set twice on error paths. .PP Function \f(CW\*(C`src/proto.c:guestfs_int_recv_file\*(C'\fR .IX Subsection "Function src/proto.c:guestfs_int_recv_file" .PP .Vb 2 \& int \& guestfs_int_recv_file (guestfs_h *g, const char *filename) .Ve .PP Returns \f(CW\*(C`\-1\*(C'\fR = error, \f(CW0\fR = \s-1EOF, \s0\f(CW\*(C`>0\*(C'\fR = more data .PP Function \f(CW\*(C`src/proto.c:receive_file_data\*(C'\fR .IX Subsection "Function src/proto.c:receive_file_data" .PP .Vb 2 \& static ssize_t \& receive_file_data (guestfs_h *g, void **buf_r) .Ve .PP Receive a chunk of file data. .PP Returns \f(CW\*(C`\-1\*(C'\fR = error, \f(CW0\fR = \s-1EOF, \s0\f(CW\*(C`>0\*(C'\fR = more data .PP \fIFile \fIsrc/qemu.c\fI\fR .IX Subsection "File src/qemu.c" .PP Functions to handle qemu versions and features. .PP Function \f(CW\*(C`src/qemu.c:guestfs_int_test_qemu\*(C'\fR .IX Subsection "Function src/qemu.c:guestfs_int_test_qemu" .PP .Vb 2 \& struct qemu_data * \& guestfs_int_test_qemu (guestfs_h *g, struct version *qemu_version) .Ve .PP Test qemu binary (or wrapper) runs, and do \f(CW\*(C`qemu \-help\*(C'\fR so we know the version of qemu what options this qemu supports, and \&\f(CW\*(C`qemu \-device ?\*(C'\fR so we know what devices are available. .PP The version number of qemu (from the \f(CW\*(C`\-help\*(C'\fR output) is saved in \&\f(CW&qemu_version\fR. .PP This caches the results in the cachedir so that as long as the qemu binary does not change, calling this is effectively free. .PP Function \f(CW\*(C`src/qemu.c:parse_qemu_version\*(C'\fR .IX Subsection "Function src/qemu.c:parse_qemu_version" .PP .Vb 3 \& static void \& parse_qemu_version (guestfs_h *g, const char *qemu_help, \& struct version *qemu_version) .Ve .PP Parse the first line of \f(CW\*(C`qemu_help\*(C'\fR into the major and minor version of qemu, but don't fail if parsing is not possible. .PP Function \f(CW\*(C`src/qemu.c:guestfs_int_qemu_supports\*(C'\fR .IX Subsection "Function src/qemu.c:guestfs_int_qemu_supports" .PP .Vb 3 \& int \& guestfs_int_qemu_supports (guestfs_h *g, const struct qemu_data *data, \& const char *option) .Ve .PP Test if option is supported by qemu command line (just by grepping the help text). .PP Function \f(CW\*(C`src/qemu.c:guestfs_int_qemu_supports_device\*(C'\fR .IX Subsection "Function src/qemu.c:guestfs_int_qemu_supports_device" .PP .Vb 4 \& int \& guestfs_int_qemu_supports_device (guestfs_h *g, \& const struct qemu_data *data, \& const char *device_name) .Ve .PP Test if device is supported by qemu (currently just greps the \&\f(CW\*(C`qemu \-device ?\*(C'\fR output). .PP Function \f(CW\*(C`src/qemu.c:guestfs_int_qemu_supports_virtio_scsi\*(C'\fR .IX Subsection "Function src/qemu.c:guestfs_int_qemu_supports_virtio_scsi" .PP .Vb 3 \& int \& guestfs_int_qemu_supports_virtio_scsi (guestfs_h *g, struct qemu_data *data, \& const struct version *qemu_version) .Ve .PP Test if qemu supports virtio-scsi. .PP Returns \f(CW1\fR = use virtio-scsi, or \f(CW0\fR = use virtio-blk. .PP Function \f(CW\*(C`src/qemu.c:guestfs_int_qemu_escape_param\*(C'\fR .IX Subsection "Function src/qemu.c:guestfs_int_qemu_escape_param" .PP .Vb 2 \& char * \& guestfs_int_qemu_escape_param (guestfs_h *g, const char *param) .Ve .PP Escape a qemu parameter. .PP Every \f(CW\*(C`,\*(C'\fR becomes \f(CW\*(C`,,\*(C'\fR. The caller must free the returned string. .PP Function \f(CW\*(C`src/qemu.c:guestfs_int_drive_source_qemu_param\*(C'\fR .IX Subsection "Function src/qemu.c:guestfs_int_drive_source_qemu_param" .PP .Vb 3 \& char * \& guestfs_int_drive_source_qemu_param (guestfs_h *g, \& const struct drive_source *src) .Ve .PP Useful function to format a drive + protocol for qemu. .PP Note that the qemu parameter is the bit after \f(CW"file="\fR. It is not escaped here, but would usually be escaped if passed to qemu as part of a full \-drive parameter (but not for \fIqemu\-img\fR\|(1)). .PP Function \f(CW\*(C`src/qemu.c:guestfs_int_discard_possible\*(C'\fR .IX Subsection "Function src/qemu.c:guestfs_int_discard_possible" .PP .Vb 3 \& bool \& guestfs_int_discard_possible (guestfs_h *g, struct drive *drv, \& const struct version *qemu_version) .Ve .PP Test if discard is both supported by qemu \s-1AND\s0 possible with the underlying file or device. This returns \f(CW1\fR if discard is possible. It returns \f(CW0\fR if not possible and sets the error to the reason why. .PP This function is called when the user set \f(CW\*(C`discard == "enable"\*(C'\fR. .PP Function \f(CW\*(C`src/qemu.c:guestfs_int_free_qemu_data\*(C'\fR .IX Subsection "Function src/qemu.c:guestfs_int_free_qemu_data" .PP .Vb 2 \& void \& guestfs_int_free_qemu_data (struct qemu_data *data) .Ve .PP Free the \f(CW\*(C`struct qemu_data\*(C'\fR. .PP \fIFile \fIsrc/stringsbuf.c\fI\fR .IX Subsection "File src/stringsbuf.c" .PP An expandable NULL-terminated vector of strings (like \f(CW\*(C`argv\*(C'\fR). .PP Use the \f(CW\*(C`DECLARE_STRINGSBUF\*(C'\fR macro to declare the stringsbuf. .PP Note: Don't confuse this with stringsbuf in the daemon which is a different type with different methods. .PP Function \f(CW\*(C`src/stringsbuf.c:guestfs_int_add_string_nodup\*(C'\fR .IX Subsection "Function src/stringsbuf.c:guestfs_int_add_string_nodup" .PP .Vb 2 \& void \& guestfs_int_add_string_nodup (guestfs_h *g, struct stringsbuf *sb, char *str) .Ve .PP Add a string to the end of the list. .PP This doesn't call \fIstrdup\fR\|(3) on the string, so the string itself is stored inside the vector. .PP Function \f(CW\*(C`src/stringsbuf.c:guestfs_int_add_string\*(C'\fR .IX Subsection "Function src/stringsbuf.c:guestfs_int_add_string" .PP .Vb 2 \& void \& guestfs_int_add_string (guestfs_h *g, struct stringsbuf *sb, const char *str) .Ve .PP Add a string to the end of the list. .PP This makes a copy of the string. .PP Function \f(CW\*(C`src/stringsbuf.c:guestfs_int_add_sprintf\*(C'\fR .IX Subsection "Function src/stringsbuf.c:guestfs_int_add_sprintf" .PP .Vb 3 \& void \& guestfs_int_add_sprintf (guestfs_h *g, struct stringsbuf *sb, \& const char *fs, ...) .Ve .PP Add a string to the end of the list. .PP Uses an sprintf-like format string when creating the string. .PP Function \f(CW\*(C`src/stringsbuf.c:guestfs_int_end_stringsbuf\*(C'\fR .IX Subsection "Function src/stringsbuf.c:guestfs_int_end_stringsbuf" .PP .Vb 2 \& void \& guestfs_int_end_stringsbuf (guestfs_h *g, struct stringsbuf *sb) .Ve .PP Finish the string buffer. .PP This adds the terminating \s-1NULL\s0 to the end of the vector. .PP Function \f(CW\*(C`src/stringsbuf.c:guestfs_int_free_stringsbuf\*(C'\fR .IX Subsection "Function src/stringsbuf.c:guestfs_int_free_stringsbuf" .PP .Vb 2 \& void \& guestfs_int_free_stringsbuf (struct stringsbuf *sb) .Ve .PP Free the string buffer and the strings. .PP \fIFile \fIsrc/tmpdirs.c\fI\fR .IX Subsection "File src/tmpdirs.c" .PP Handle temporary directories. .PP Function \f(CW\*(C`src/tmpdirs.c:set_abs_path\*(C'\fR .IX Subsection "Function src/tmpdirs.c:set_abs_path" .PP .Vb 3 \& static int \& set_abs_path (guestfs_h *g, const char *ctxstr, \& const char *tmpdir, char **tmpdir_ret) .Ve .PP We need to make all tmpdir paths absolute because lots of places in the code assume this. Do it at the time we set the path or read the environment variable (https://bugzilla.redhat.com/882417). .PP The \f(CW\*(C`ctxstr\*(C'\fR parameter is a string displayed in error messages giving the context of the operation (eg. name of environment variable being used, or \s-1API\s0 function being called). .PP Function \f(CW\*(C`src/tmpdirs.c:guestfs_impl_get_tmpdir\*(C'\fR .IX Subsection "Function src/tmpdirs.c:guestfs_impl_get_tmpdir" .PP .Vb 2 \& char * \& guestfs_impl_get_tmpdir (guestfs_h *g) .Ve .PP Implements the \f(CW\*(C`guestfs_get_tmpdir\*(C'\fR \s-1API.\s0 .PP Note this actually calculates the tmpdir, so it never returns \&\f(CW\*(C`NULL\*(C'\fR. .PP Function \f(CW\*(C`src/tmpdirs.c:guestfs_impl_get_cachedir\*(C'\fR .IX Subsection "Function src/tmpdirs.c:guestfs_impl_get_cachedir" .PP .Vb 2 \& char * \& guestfs_impl_get_cachedir (guestfs_h *g) .Ve .PP Implements the \f(CW\*(C`guestfs_get_cachedir\*(C'\fR \s-1API.\s0 .PP Note this actually calculates the cachedir, so it never returns \f(CW\*(C`NULL\*(C'\fR. .PP Function \f(CW\*(C`src/tmpdirs.c:guestfs_impl_get_sockdir\*(C'\fR .IX Subsection "Function src/tmpdirs.c:guestfs_impl_get_sockdir" .PP .Vb 2 \& char * \& guestfs_impl_get_sockdir (guestfs_h *g) .Ve .PP Implements the \f(CW\*(C`guestfs_get_sockdir\*(C'\fR \s-1API.\s0 .PP Note this actually calculates the sockdir, so it never returns \&\f(CW\*(C`NULL\*(C'\fR. .PP Function \f(CW\*(C`src/tmpdirs.c:guestfs_int_lazy_make_tmpdir\*(C'\fR .IX Subsection "Function src/tmpdirs.c:guestfs_int_lazy_make_tmpdir" .PP .Vb 2 \& int \& guestfs_int_lazy_make_tmpdir (guestfs_h *g) .Ve .PP The \f(CW\*(C`g\->tmpdir\*(C'\fR (per-handle temporary directory) is not created when the handle is created. Instead we create it lazily before the first time it is used, or during launch. .PP Function \f(CW\*(C`src/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir\*(C'\fR .IX Subsection "Function src/tmpdirs.c:guestfs_int_lazy_make_supermin_appliance_dir" .PP .Vb 2 \& char * \& guestfs_int_lazy_make_supermin_appliance_dir (guestfs_h *g) .Ve .PP Create the supermin appliance directory under cachedir, if it does not exist. .PP Sanity-check that the permissions on the cachedir are safe, in case it has been pre-created maliciously or tampered with. .PP Returns the directory name which the caller must free. .PP Function \f(CW\*(C`src/tmpdirs.c:guestfs_int_recursive_remove_dir\*(C'\fR .IX Subsection "Function src/tmpdirs.c:guestfs_int_recursive_remove_dir" .PP .Vb 2 \& void \& guestfs_int_recursive_remove_dir (guestfs_h *g, const char *dir) .Ve .PP Recursively remove a temporary directory. If removal fails, just return (it's a temporary directory so it'll eventually be cleaned up by a temp cleaner). .PP This is implemented using \f(CW\*(C`rm \-rf\*(C'\fR because that's simpler and safer. .PP \fIFile \fIsrc/umask.c\fI\fR .IX Subsection "File src/umask.c" .PP Return current umask in a thread-safe way. .PP glibc documents, but does not actually implement, a \*(L"\fIgetumask\fR\|(3)\*(R" call. .PP We use \f(CW\*(C`Umask\*(C'\fR from \fI/proc/self/status\fR for Linux ≥ 4.7. For older Linux and other Unix, this file implements an expensive but thread-safe way to get the current process's umask. .PP Thanks to: Josh Stone, Jiri Jaburek, Eric Blake. .PP Function \f(CW\*(C`src/umask.c:guestfs_int_getumask\*(C'\fR .IX Subsection "Function src/umask.c:guestfs_int_getumask" .PP .Vb 2 \& int \& guestfs_int_getumask (guestfs_h *g) .Ve .PP Returns the current process's umask. On failure, returns \f(CW\*(C`\-1\*(C'\fR and sets the error in the guestfs handle. .PP Function \f(CW\*(C`src/umask.c:get_umask_from_proc\*(C'\fR .IX Subsection "Function src/umask.c:get_umask_from_proc" .PP .Vb 2 \& static int \& get_umask_from_proc (guestfs_h *g) .Ve .PP For Linux ≥ 4.7 get the umask from \fI/proc/self/status\fR. .PP On failure this returns \f(CW\*(C`\-1\*(C'\fR. However if we could not open the \&\fI/proc\fR file or find the \f(CW\*(C`Umask\*(C'\fR entry in it, return \f(CW\*(C`\-2\*(C'\fR which causes the fallback path to run. .PP Function \f(CW\*(C`src/umask.c:get_umask_from_fork\*(C'\fR .IX Subsection "Function src/umask.c:get_umask_from_fork" .PP .Vb 2 \& static int \& get_umask_from_fork (guestfs_h *g) .Ve .PP Fallback method of getting the umask using fork. .PP \fIFile \fIsrc/unit\-tests.c\fI\fR .IX Subsection "File src/unit-tests.c" .PP Unit tests of internal functions. .PP These tests may use a libguestfs handle, but must not launch the handle. Also, avoid long-running tests. .PP Function \f(CW\*(C`src/unit\-tests.c:test_split\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_split" .PP .Vb 2 \& static void \& test_split (void) .Ve .PP Test \f(CW\*(C`guestfs_int_split_string\*(C'\fR. .PP Function \f(CW\*(C`src/unit\-tests.c:test_concat\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_concat" .PP .Vb 2 \& static void \& test_concat (void) .Ve .PP Test \f(CW\*(C`guestfs_int_concat_strings\*(C'\fR. .PP Function \f(CW\*(C`src/unit\-tests.c:test_join\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_join" .PP .Vb 2 \& static void \& test_join (void) .Ve .PP Test \f(CW\*(C`guestfs_int_join_strings\*(C'\fR. .PP Function \f(CW\*(C`src/unit\-tests.c:test_validate_guid\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_validate_guid" .PP .Vb 2 \& static void \& test_validate_guid (void) .Ve .PP Test \f(CW\*(C`guestfs_int_validate_guid\*(C'\fR. .PP Function \f(CW\*(C`src/unit\-tests.c:test_drive_name\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_drive_name" .PP .Vb 2 \& static void \& test_drive_name (void) .Ve .PP Test \f(CW\*(C`guestfs_int_drive_name\*(C'\fR. .PP Function \f(CW\*(C`src/unit\-tests.c:test_drive_index\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_drive_index" .PP .Vb 2 \& static void \& test_drive_index (void) .Ve .PP Test \f(CW\*(C`guestfs_int_drive_index\*(C'\fR. .PP Function \f(CW\*(C`src/unit\-tests.c:test_getumask\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_getumask" .PP .Vb 2 \& static void \& test_getumask (void) .Ve .PP Test \f(CW\*(C`guestfs_int_getumask\*(C'\fR. .PP Function \f(CW\*(C`src/unit\-tests.c:test_command\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_command" .PP .Vb 2 \& static void \& test_command (void) .Ve .PP Test \f(CW\*(C`guestfs_int_new_command\*(C'\fR etc. .PP \&\s-1XXX\s0 These tests could be made much more thorough. So far we simply test that it's not obviously broken. .PP Function \f(CW\*(C`src/unit\-tests.c:test_qemu_escape_param\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_qemu_escape_param" .PP .Vb 2 \& static void \& test_qemu_escape_param (void) .Ve .PP Test \f(CW\*(C`guestfs_int_qemu_escape_param\*(C'\fR .PP \&\s-1XXX I\s0 wanted to make this test run qemu, passing some parameters which need to be escaped, but I cannot think of a way to do that without launching a \s-1VM.\s0 .PP Function \f(CW\*(C`src/unit\-tests.c:test_timeval_diff\*(C'\fR .IX Subsection "Function src/unit-tests.c:test_timeval_diff" .PP .Vb 2 \& static void \& test_timeval_diff (void) .Ve .PP Test \f(CW\*(C`guestfs_int_timeval_diff\*(C'\fR. .PP \fIFile \fIsrc/utils.c\fI\fR .IX Subsection "File src/utils.c" .PP Utility functions used by the library, tools and language bindings. .PP These functions these \fImust not\fR call internal library functions such as \f(CW\*(C`safe_*\*(C'\fR, \f(CW\*(C`error\*(C'\fR or \f(CW\*(C`perrorf\*(C'\fR, or any \f(CW\*(C`guestfs_int_*\*(C'\fR. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_split_string\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_split_string" .PP .Vb 2 \& char ** \& guestfs_int_split_string (char sep, const char *str) .Ve .PP Split string at separator character \f(CW\*(C`sep\*(C'\fR, returning the list of strings. Returns \f(CW\*(C`NULL\*(C'\fR on memory allocation failure. .PP Note (assuming \f(CW\*(C`sep\*(C'\fR is \f(CW\*(C`:\*(C'\fR): .ie n .IP """str == NULL""" 4 .el .IP "\f(CWstr == NULL\fR" 4 .IX Item "str == NULL" aborts .ie n .IP """str == """"""" 4 .el .IP "\f(CWstr == ``''\fR" 4 .IX Item "str == """"" returns \f(CW\*(C`[]\*(C'\fR .ie n .IP """str == ""abc""""" 4 .el .IP "\f(CWstr == ``abc''\fR" 4 .IX Item "str == ""abc""" returns \f(CW\*(C`["abc"]\*(C'\fR .ie n .IP """str == "":""""" 4 .el .IP "\f(CWstr == ``:''\fR" 4 .IX Item "str == "":""" returns \f(CW\*(C`["", ""]\*(C'\fR .PP Function \f(CW\*(C`src/utils.c:guestfs_int_exit_status_to_string\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_exit_status_to_string" .PP .Vb 3 \& char * \& guestfs_int_exit_status_to_string (int status, const char *cmd_name, \& char *buffer, size_t buflen) .Ve .PP Translate a wait/system exit status into a printable string. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_random_string\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_random_string" .PP .Vb 2 \& int \& guestfs_int_random_string (char *ret, size_t len) .Ve .PP Return a random string of characters. .PP Notes: .IP "\(bu" 4 The \f(CW\*(C`ret\*(C'\fR buffer must have length \f(CW\*(C`len+1\*(C'\fR in order to store the final \f(CW\*(C`\e0\*(C'\fR character. .IP "\(bu" 4 There is about 5 bits of randomness per output character (so about \&\f(CW\*(C`5*len\*(C'\fR bits of randomness in the resulting string). .PP Function \f(CW\*(C`src/utils.c:guestfs_int_drive_name\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_drive_name" .PP .Vb 2 \& char * \& guestfs_int_drive_name (size_t index, char *ret) .Ve .PP This turns a drive index (eg. \f(CW27\fR) into a drive name (eg. \f(CW"ab"\fR). .PP Drive indexes count from \f(CW0\fR. The return buffer has to be large enough for the resulting string, and the returned pointer points to the *end* of the string. .PP https://rwmj.wordpress.com/2011/01/09/how\-are\-linux\-drives\-named\-beyond\-drive\-26\-devsdz/ .PP Function \f(CW\*(C`src/utils.c:guestfs_int_drive_index\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_drive_index" .PP .Vb 2 \& ssize_t \& guestfs_int_drive_index (const char *name) .Ve .PP The opposite of \f(CW\*(C`guestfs_int_drive_name\*(C'\fR. Take a string like \&\f(CW"ab"\fR and return the index (eg \f(CW27\fR). .PP Note that you must remove any prefix such as \f(CW"hd"\fR, \f(CW"sd"\fR etc, or any partition number before calling the function. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_is_true\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_is_true" .PP .Vb 2 \& int \& guestfs_int_is_true (const char *str) .Ve .PP Similar to \f(CW\*(C`Tcl_GetBoolean\*(C'\fR. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_fadvise_normal\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_fadvise_normal" .PP .Vb 2 \& void \& guestfs_int_fadvise_normal (int fd) .Ve .PP Hint that we will read or write the file descriptor normally. .PP On Linux, this clears the \f(CW\*(C`FMODE_RANDOM\*(C'\fR flag on the file [see below] and sets the per-file number of readahead pages to equal the block device readahead setting. .PP It's \s-1OK\s0 to call this on a non-file since we ignore failure as it is only a hint. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_fadvise_sequential\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_fadvise_sequential" .PP .Vb 2 \& void \& guestfs_int_fadvise_sequential (int fd) .Ve .PP Hint that we will read or write the file descriptor sequentially. .PP On Linux, this clears the \f(CW\*(C`FMODE_RANDOM\*(C'\fR flag on the file [see below] and sets the per-file number of readahead pages to twice the block device readahead setting. .PP It's \s-1OK\s0 to call this on a non-file since we ignore failure as it is only a hint. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_fadvise_random\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_fadvise_random" .PP .Vb 2 \& void \& guestfs_int_fadvise_random (int fd) .Ve .PP Hint that we will read or write the file descriptor randomly. .PP On Linux, this sets the \f(CW\*(C`FMODE_RANDOM\*(C'\fR flag on the file. The effect of this flag is to: .IP "\(bu" 4 Disable normal sequential file readahead. .IP "\(bu" 4 If any read of the file is done which misses in the page cache, 2MB are read into the page cache. [I think \- I'm not sure I totally understand what this is doing] .PP It's \s-1OK\s0 to call this on a non-file since we ignore failure as it is only a hint. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_fadvise_noreuse\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_fadvise_noreuse" .PP .Vb 2 \& void \& guestfs_int_fadvise_noreuse (int fd) .Ve .PP Hint that we will access the data only once. .PP On Linux, this does nothing. .PP It's \s-1OK\s0 to call this on a non-file since we ignore failure as it is only a hint. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_fadvise_dontneed\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_fadvise_dontneed" .PP .Vb 2 \& void \& guestfs_int_fadvise_dontneed (int fd) .Ve .PP Hint that we will not access the data in the near future. .PP On Linux, this immediately writes out any dirty pages in the page cache and then invalidates (drops) all pages associated with this file from the page cache. Apparently it does this even if the file is opened or being used by other processes. This setting is not persistent; if you subsequently read the file it will be cached in the page cache as normal. .PP It's \s-1OK\s0 to call this on a non-file since we ignore failure as it is only a hint. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_fadvise_willneed\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_fadvise_willneed" .PP .Vb 2 \& void \& guestfs_int_fadvise_willneed (int fd) .Ve .PP Hint that we will access the data in the near future. .PP On Linux, this immediately reads the whole file into the page cache. This setting is not persistent; subsequently pages may be dropped from the page cache as normal. .PP It's \s-1OK\s0 to call this on a non-file since we ignore failure as it is only a hint. .PP Function \f(CW\*(C`src/utils.c:guestfs_int_shell_unquote\*(C'\fR .IX Subsection "Function src/utils.c:guestfs_int_shell_unquote" .PP .Vb 2 \& char * \& guestfs_int_shell_unquote (const char *str) .Ve .PP Unquote a shell-quoted string. .PP Augeas passes strings to us which may be quoted, eg. if they come from files in \fI/etc/sysconfig\fR. This function can do simple unquoting of these strings. .PP Note this function does not do variable substitution, since that is impossible without knowing the file context and indeed the environment under which the shell script is run. Configuration files should not use complex quoting. .PP \&\f(CW\*(C`str\*(C'\fR is the input string from Augeas, a string that may be single\- or double-quoted or may not be quoted. The returned string is unquoted, and must be freed by the caller. \f(CW\*(C`NULL\*(C'\fR is returned on error and \f(CW\*(C`errno\*(C'\fR is set accordingly. .PP For information on double-quoting in bash, see https://www.gnu.org/software/bash/manual/html_node/Double\-Quotes.html .PP \fIFile \fIsrc/version.c\fI\fR .IX Subsection "File src/version.c" .PP This file provides simple version number management. .PP Function \f(CW\*(C`src/version.c:guestfs_int_version_from_x_y\*(C'\fR .IX Subsection "Function src/version.c:guestfs_int_version_from_x_y" .PP .Vb 2 \& int \& guestfs_int_version_from_x_y (guestfs_h *g, struct version *v, const char *str) .Ve .PP Parses a version from a string, looking for a \f(CW\*(C`X.Y\*(C'\fR pattern. .PP Returns \f(CW\*(C`\-1\*(C'\fR on failure (like failed integer parsing), \f(CW0\fR on missing match, and \f(CW1\fR on match and successful parsing. \f(CW\*(C`v\*(C'\fR is changed only on successful match. .PP Function \f(CW\*(C`src/version.c:guestfs_int_version_from_x_y_re\*(C'\fR .IX Subsection "Function src/version.c:guestfs_int_version_from_x_y_re" .PP .Vb 3 \& int \& guestfs_int_version_from_x_y_re (guestfs_h *g, struct version *v, \& const char *str, const pcre *re) .Ve .PP Parses a version from a string, using the specified \f(CW\*(C`re\*(C'\fR as regular expression which \fImust\fR provide (at least) two matches. .PP Returns \f(CW\*(C`\-1\*(C'\fR on failure (like failed integer parsing), \f(CW0\fR on missing match, and \f(CW1\fR on match and successful parsing. \f(CW\*(C`v\*(C'\fR is changed only on successful match. .PP Function \f(CW\*(C`src/version.c:guestfs_int_version_from_x_y_or_x\*(C'\fR .IX Subsection "Function src/version.c:guestfs_int_version_from_x_y_or_x" .PP .Vb 3 \& int \& guestfs_int_version_from_x_y_or_x (guestfs_h *g, struct version *v, \& const char *str) .Ve .PP Parses a version from a string, either looking for a \f(CW\*(C`X.Y\*(C'\fR pattern or considering it as whole integer. .PP Returns \f(CW\*(C`\-1\*(C'\fR on failure (like failed integer parsing), \f(CW0\fR on missing match, and \f(CW1\fR on match and successful parsing. \f(CW\*(C`v\*(C'\fR is changed only on successful match. .PP \fIFile \fIsrc/wait.c\fI\fR .IX Subsection "File src/wait.c" .PP Function \f(CW\*(C`src/wait.c:guestfs_int_waitpid\*(C'\fR .IX Subsection "Function src/wait.c:guestfs_int_waitpid" .PP .Vb 2 \& int \& guestfs_int_waitpid (guestfs_h *g, pid_t pid, int *status, const char *errmsg) .Ve .PP A safe version of \fIwaitpid\fR\|(3) which retries if \f(CW\*(C`EINTR\*(C'\fR is returned. .PP \&\fINote:\fR this only needs to be used in the library, or in programs that install a non-restartable \f(CW\*(C`SIGCHLD\*(C'\fR handler (which is not the case for any current libguestfs virt tools). .PP If the main program installs a \s-1SIGCHLD\s0 handler and sets it to be non-restartable, then what can happen is the library is waiting in a wait syscall, the child exits, \f(CW\*(C`SIGCHLD\*(C'\fR is sent to the process, and the wait syscall returns \f(CW\*(C`EINTR\*(C'\fR. Since the library cannot control the signal handler, we have to instead restart the wait syscall, which is the purpose of this wrapper. .PP Function \f(CW\*(C`src/wait.c:guestfs_int_waitpid_noerror\*(C'\fR .IX Subsection "Function src/wait.c:guestfs_int_waitpid_noerror" .PP .Vb 2 \& void \& guestfs_int_waitpid_noerror (pid_t pid) .Ve .PP Like \f(CW\*(C`guestfs_int_waitpid\*(C'\fR, but ignore errors. .PP Function \f(CW\*(C`src/wait.c:guestfs_int_wait4\*(C'\fR .IX Subsection "Function src/wait.c:guestfs_int_wait4" .PP .Vb 3 \& int \& guestfs_int_wait4 (guestfs_h *g, pid_t pid, int *status, \& struct rusage *rusage, const char *errmsg) .Ve .PP A safe version of \fIwait4\fR\|(2) which retries if \f(CW\*(C`EINTR\*(C'\fR is returned. .PP \fIFile \fIsrc/whole\-file.c\fI\fR .IX Subsection "File src/whole-file.c" .PP Function \f(CW\*(C`src/whole\-file.c:guestfs_int_read_whole_file\*(C'\fR .IX Subsection "Function src/whole-file.c:guestfs_int_read_whole_file" .PP .Vb 3 \& int \& guestfs_int_read_whole_file (guestfs_h *g, const char *filename, \& char **data_r, size_t *size_r) .Ve .PP Read the whole file \f(CW\*(C`filename\*(C'\fR into a memory buffer. .PP The memory buffer is initialized and returned in \f(CW\*(C`data_r\*(C'\fR. The size of the file in bytes is returned in \f(CW\*(C`size_r\*(C'\fR. The return buffer must be freed by the caller. .PP On error this sets the error in the handle and returns \f(CW\*(C`\-1\*(C'\fR. .PP For the convenience of callers, the returned buffer is NUL-terminated (the \s-1NUL\s0 is not included in the size). .PP The file must be a \fBregular\fR, \fBlocal\fR, \fBtrusted\fR file. In particular, do not use this function to read files that might be under control of an untrusted user since that will lead to a denial-of-service attack. .SS "Subdirectory \fIbuilder\fP" .IX Subsection "Subdirectory builder" \fIFile \fIbuilder/index\-parser\-c.c\fI\fR .IX Subsection "File builder/index-parser-c.c" .PP This file handles the interface between the C/lex/yacc index file parser, and the OCaml world. See \fIbuilder/index_parser.ml\fR for the OCaml type definition. .SS "Subdirectory \fIcat\fP" .IX Subsection "Subdirectory cat" \fIFile \fIcat/visit.c\fI\fR .IX Subsection "File cat/visit.c" .PP This file contains a recursive function for visiting all files and directories in a guestfs filesystem. .PP Adapted from https://rwmj.wordpress.com/2010/12/15/tip\-audit\-virtual\-machine\-for\-setuid\-files/ .PP Function \f(CW\*(C`cat/visit.c:visit\*(C'\fR .IX Subsection "Function cat/visit.c:visit" .PP .Vb 2 \& int \& visit (guestfs_h *g, const char *dir, visitor_function f, void *opaque) .Ve .PP Visit every file and directory in a guestfs filesystem, starting at \f(CW\*(C`dir\*(C'\fR. .PP \&\f(CW\*(C`dir\*(C'\fR may be \f(CW"/"\fR to visit the entire filesystem, or may be some subdirectory. Symbolic links are not followed. .PP The visitor function \f(CW\*(C`f\*(C'\fR is called once for every directory and every file. The parameters passed to \f(CW\*(C`f\*(C'\fR include the current directory name, the current file name (or \f(CW\*(C`NULL\*(C'\fR when we're visiting a directory), the \f(CW\*(C`guestfs_statns\*(C'\fR (file permissions etc), and the list of extended attributes of the file. The visitor function may return \f(CW\*(C`\-1\*(C'\fR which causes the whole recursion to stop with an error. .PP Also passed to this function is an \f(CW\*(C`opaque\*(C'\fR pointer which is passed through to the visitor function. .PP Returns \f(CW0\fR if everything went \s-1OK,\s0 or \f(CW\*(C`\-1\*(C'\fR if there was an error. Error handling is not particularly well defined. It will either set an error in the libguestfs handle or print an error on stderr, but there is no way for the caller to tell the difference. .SS "Subdirectory \fIdaemon\fP" .IX Subsection "Subdirectory daemon" \fIFile \fIdaemon/command.c\fI\fR .IX Subsection "File daemon/command.c" .PP This file contains a number of useful functions for running external commands and capturing their output. .PP Function \f(CW\*(C`daemon/command.c:commandf\*(C'\fR .IX Subsection "Function daemon/command.c:commandf" .PP .Vb 3 \& int \& commandf (char **stdoutput, char **stderror, unsigned flags, \& const char *name, ...) .Ve .PP Run a command. Optionally capture stdout and stderr as strings. .PP Returns \f(CW0\fR if the command ran successfully, or \f(CW\*(C`\-1\*(C'\fR if there was any error. .PP For a description of the \f(CW\*(C`flags\*(C'\fR see \f(CW\*(C`commandrvf\*(C'\fR. .PP There is also a macro \f(CW\*(C`command(out,err,name,...)\*(C'\fR which calls \&\f(CW\*(C`commandf\*(C'\fR with \f(CW\*(C`flags=0\*(C'\fR. .PP Function \f(CW\*(C`daemon/command.c:commandrf\*(C'\fR .IX Subsection "Function daemon/command.c:commandrf" .PP .Vb 3 \& int \& commandrf (char **stdoutput, char **stderror, unsigned flags, \& const char *name, ...) .Ve .PP Same as \f(CW\*(C`command\*(C'\fR, but we allow the status code from the subcommand to be non-zero, and return that status code. .PP We still return \f(CW\*(C`\-1\*(C'\fR if there was some other error. .PP There is also a macro \f(CW\*(C`commandr(out,err,name,...)\*(C'\fR which calls \&\f(CW\*(C`commandrf\*(C'\fR with \f(CW\*(C`flags=0\*(C'\fR. .PP Function \f(CW\*(C`daemon/command.c:commandvf\*(C'\fR .IX Subsection "Function daemon/command.c:commandvf" .PP .Vb 3 \& int \& commandvf (char **stdoutput, char **stderror, unsigned flags, \& char const *const *argv) .Ve .PP Same as \f(CW\*(C`command\*(C'\fR, but passing in an argv array. .PP There is also a macro \f(CW\*(C`commandv(out,err,argv)\*(C'\fR which calls \&\f(CW\*(C`commandvf\*(C'\fR with \f(CW\*(C`flags=0\*(C'\fR. .PP Function \f(CW\*(C`daemon/command.c:commandrvf\*(C'\fR .IX Subsection "Function daemon/command.c:commandrvf" .PP .Vb 3 \& int \& commandrvf (char **stdoutput, char **stderror, unsigned flags, \& char const* const *argv) .Ve .PP This is a more sane version of \fIsystem\fR\|(3) for running external commands. It uses fork/execvp, so we don't need to worry about quoting of parameters, and it allows us to capture any error messages in a buffer. .PP If \f(CW\*(C`stdoutput\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR, then \f(CW*stdoutput\fR will return the stdout of the command as a string. .PP If \f(CW\*(C`stderror\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR, then \f(CW*stderror\fR will return the stderr of the command. If there is a final \en character, it is removed so you can use the error string directly in a call to \&\f(CW\*(C`reply_with_error\*(C'\fR. .PP Flags are: .ie n .IP """COMMAND_FLAG_FOLD_STDOUT_ON_STDERR""" 4 .el .IP "\f(CWCOMMAND_FLAG_FOLD_STDOUT_ON_STDERR\fR" 4 .IX Item "COMMAND_FLAG_FOLD_STDOUT_ON_STDERR" For broken external commands that send error messages to stdout (hello, parted) but that don't have any useful stdout information, use this flag to capture the error messages in the \f(CW*stderror\fR buffer. If using this flag, you should pass \f(CW\*(C`stdoutput=NULL\*(C'\fR because nothing could ever be captured in that buffer. .ie n .IP """COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN""" 4 .el .IP "\f(CWCOMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN\fR" 4 .IX Item "COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN" For running external commands on chrooted files correctly (see https://bugzilla.redhat.com/579608) specifying this flag causes another process to be forked which chroots into sysroot and just copies the input file to stdin of the specified command. The file descriptor is ORed with the flags, and that file descriptor is always closed by this function. See \fIdaemon/hexdump.c\fR for an example of usage. .PP There is also a macro \f(CW\*(C`commandrv(out,err,argv)\*(C'\fR which calls \&\f(CW\*(C`commandrvf\*(C'\fR with \f(CW\*(C`flags=0\*(C'\fR. .PP \fIFile \fIdaemon/guestfsd.c\fI\fR .IX Subsection "File daemon/guestfsd.c" .PP This is the guestfs daemon which runs inside the guestfs appliance. This file handles start up, connecting back to the library, and has several utility functions. .PP Function \f(CW\*(C`daemon/guestfsd.c:is_root_device_stat\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:is_root_device_stat" .PP .Vb 2 \& static int \& is_root_device_stat (struct stat *statbuf) .Ve .PP Return true iff device is the root device (and therefore should be ignored from the point of view of user calls). .PP Function \f(CW\*(C`daemon/guestfsd.c:sysroot_path\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:sysroot_path" .PP .Vb 2 \& char * \& sysroot_path (const char *path) .Ve .PP Turn \f(CW"/path"\fR into \f(CW"/sysroot/path"\fR. .PP Returns \f(CW\*(C`NULL\*(C'\fR on failure. The caller \fImust\fR check for this and call \f(CW\*(C`reply_with_perror ("malloc")\*(C'\fR. The caller must also free the returned string. .PP See also the custom \f(CW%R\fR printf formatter which does shell quoting too. .PP Function \f(CW\*(C`daemon/guestfsd.c:sysroot_realpath\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:sysroot_realpath" .PP .Vb 2 \& char * \& sysroot_realpath (const char *path) .Ve .PP Resolve path within sysroot, calling \f(CW\*(C`sysroot_path\*(C'\fR on the resolved path. .PP Returns \f(CW\*(C`NULL\*(C'\fR on failure. The caller \fImust\fR check for this and call \f(CW\*(C`reply_with_perror ("malloc")\*(C'\fR. The caller must also free the returned string. .PP See also the custom \f(CW%R\fR printf formatter which does shell quoting too. .PP Function \f(CW\*(C`daemon/guestfsd.c:is_power_of_2\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:is_power_of_2" .PP .Vb 2 \& int \& is_power_of_2 (unsigned long v) .Ve .PP Returns true if \f(CW\*(C`v\*(C'\fR is a power of 2. .PP Uses the algorithm described at http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2 .PP Function \f(CW\*(C`daemon/guestfsd.c:compare_device_names\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:compare_device_names" .PP .Vb 2 \& int \& compare_device_names (const char *a, const char *b) .Ve .PP Compare device names (including partition numbers if present). .PP https://rwmj.wordpress.com/2011/01/09/how\-are\-linux\-drives\-named\-beyond\-drive\-26\-devsdz/ .PP Function \f(CW\*(C`daemon/guestfsd.c:split_lines_sb\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:split_lines_sb" .PP .Vb 2 \& struct stringsbuf \& split_lines_sb (char *str) .Ve .PP Split an output string into a NULL-terminated list of lines, wrapped into a stringsbuf. .PP Typically this is used where we have run an external command which has printed out a list of things, and we want to return an actual list. .PP The corner cases here are quite tricky. Note in particular: .ie n .IP """""" 4 .el .IP "\f(CW``''\fR" 4 .IX Item """""" returns \f(CW\*(C`[]\*(C'\fR .ie n .IP """\en""" 4 .el .IP "\f(CW``\en''\fR" 4 .IX Item """n""" returns \f(CW\*(C`[""]\*(C'\fR .ie n .IP """a\enb""" 4 .el .IP "\f(CW``a\enb''\fR" 4 .IX Item """anb""" returns \f(CW\*(C`["a"; "b"]\*(C'\fR .ie n .IP """a\enb\en""" 4 .el .IP "\f(CW``a\enb\en''\fR" 4 .IX Item """anbn""" returns \f(CW\*(C`["a"; "b"]\*(C'\fR .ie n .IP """a\enb\en\en""" 4 .el .IP "\f(CW``a\enb\en\en''\fR" 4 .IX Item """anbnn""" returns \f(CW\*(C`["a"; "b"; ""]\*(C'\fR .PP The original string is written over and destroyed by this function (which is usually \s-1OK\s0 because it's the 'out' string from \&\f(CW\*(C`command*()\*(C'\fR). You can free the original string, because \&\f(CW\*(C`add_string()\*(C'\fR strdups the strings. .PP \&\f(CW\*(C`argv\*(C'\fR in the \f(CW\*(C`struct stringsbuf\*(C'\fR will be \f(CW\*(C`NULL\*(C'\fR in case of errors. .PP Function \f(CW\*(C`daemon/guestfsd.c:trim\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:trim" .PP .Vb 2 \& void \& trim (char *str) .Ve .PP Skip leading and trailing whitespace, updating the original string in-place. .PP Function \f(CW\*(C`daemon/guestfsd.c:print_shell_quote\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:print_shell_quote" .PP .Vb 4 \& static int \& print_shell_quote (FILE *stream, \& const struct printf_info *info ATTRIBUTE_UNUSED, \& const void *const *args) .Ve .PP printf helper function so we can use \f(CW%Q\fR (\*(L"quoted\*(R") and \f(CW%R\fR to print shell-quoted strings. See \fIguestfs\-hacking\fR\|(1) for more details. .PP Function \f(CW\*(C`daemon/guestfsd.c:device_name_translation\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:device_name_translation" .PP .Vb 2 \& char * \& device_name_translation (const char *device) .Ve .PP Perform device name translation. See \fIguestfs\fR\|(3) for the algorithm. Usually you should not call this directly. .PP It returns a newly allocated string which the caller must free. .PP It returns \f(CW\*(C`NULL\*(C'\fR on error. \fBNote\fR it does \fInot\fR call \&\f(CW\*(C`reply_with_*\*(C'\fR. .PP We have to open the device and test for \f(CW\*(C`ENXIO\*(C'\fR, because the device nodes may exist in the appliance. .PP Function \f(CW\*(C`daemon/guestfsd.c:parse_btrfsvol\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:parse_btrfsvol" .PP .Vb 2 \& int \& parse_btrfsvol (const char *desc_orig, mountable_t *mountable) .Ve .PP Parse the mountable descriptor for a btrfs subvolume. Don't call this directly; it is only used from the stubs. .PP A btrfs subvolume is given as: .PP .Vb 1 \& btrfsvol:/dev/sda3/root .Ve .PP where \fI/dev/sda3\fR is a block device containing a btrfs filesystem, and root is the name of a subvolume on it. This function is passed the string following \f(CW"btrfsvol:"\fR. .PP On success, \f(CW\*(C`mountable\->device\*(C'\fR and \f(CW\*(C`mountable\->volume\*(C'\fR must be freed by the caller. .PP Function \f(CW\*(C`daemon/guestfsd.c:mountable_to_string\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:mountable_to_string" .PP .Vb 2 \& char * \& mountable_to_string (const mountable_t *mountable) .Ve .PP Convert a \f(CW\*(C`mountable_t\*(C'\fR back to its string representation .PP This function can be used in an error path, so must not call \&\f(CW\*(C`reply_with_error\*(C'\fR. .PP Function \f(CW\*(C`daemon/guestfsd.c:prog_exists\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:prog_exists" .PP .Vb 2 \& int \& prog_exists (const char *prog) .Ve .PP Check program exists and is executable on \f(CW$PATH\fR. .PP Function \f(CW\*(C`daemon/guestfsd.c:random_name\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:random_name" .PP .Vb 2 \& int \& random_name (char *template) .Ve .PP Pass a template such as \f(CW"/sysroot/XXXXXXXX.XXX"\fR. This updates the template to contain a randomly named file. Any \f(CW\*(AqX\*(Aq\fR characters after the final \f(CW\*(Aq/\*(Aq\fR in the template are replaced with random characters. .PP Notes: You should probably use an 8.3 path, so it's compatible with all filesystems including basic \s-1FAT. \s0 Also this only substitutes lowercase \s-1ASCII\s0 letters and numbers, again for compatibility with lowest common denominator filesystems. .PP This doesn't create a file or check whether or not the file exists (it would be extremely unlikely to exist as long as the \s-1RNG\s0 is working). .PP If there is an error, \f(CW\*(C`\-1\*(C'\fR is returned. .PP Function \f(CW\*(C`daemon/guestfsd.c:udev_settle\*(C'\fR .IX Subsection "Function daemon/guestfsd.c:udev_settle" .PP .Vb 2 \& void \& udev_settle (void) .Ve .PP \&\s-1LVM\s0 and other commands aren't synchronous, especially when udev is involved. eg. You can create or remove some device, but the \&\f(CW\*(C`/dev\*(C'\fR device node won't appear until some time later. This means that you get an error if you run one command followed by another. .PP Use \f(CW\*(C`udevadm settle\*(C'\fR after certain commands, but don't be too fussed if it fails. .PP \fIFile \fIdaemon/internal.c\fI\fR .IX Subsection "File daemon/internal.c" .PP Internal functions that are not part of the public \s-1API.\s0 .SS "Subdirectory \fIdf\fP" .IX Subsection "Subdirectory df" \fIFile \fIdf/domains.c\fI\fR .IX Subsection "File df/domains.c" .PP This file is used by \f(CW\*(C`virt\-df\*(C'\fR and some of the other tools when they are implicitly asked to operate over all libvirt domains (VMs), for example when \f(CW\*(C`virt\-df\*(C'\fR is called without specifying any particular disk image. .PP It hides the complexity of querying the list of domains from libvirt. .PP Function \f(CW\*(C`df/domains.c:free_domains\*(C'\fR .IX Subsection "Function df/domains.c:free_domains" .PP .Vb 2 \& void \& free_domains (void) .Ve .PP Frees up everything allocated by \f(CW\*(C`get_all_libvirt_domains\*(C'\fR. .PP Function \f(CW\*(C`df/domains.c:get_all_libvirt_domains\*(C'\fR .IX Subsection "Function df/domains.c:get_all_libvirt_domains" .PP .Vb 2 \& void \& get_all_libvirt_domains (const char *libvirt_uri) .Ve .PP Read all libguest guests into the global variables \f(CW\*(C`domains\*(C'\fR and \&\f(CW\*(C`nr_domains\*(C'\fR. The guests are ordered by name. This exits on any error. .PP \fIFile \fIdf/estimate\-max\-threads.c\fI\fR .IX Subsection "File df/estimate-max-threads.c" .PP Function \f(CW\*(C`df/estimate\-max\-threads.c:estimate_max_threads\*(C'\fR .IX Subsection "Function df/estimate-max-threads.c:estimate_max_threads" .PP .Vb 2 \& size_t \& estimate_max_threads (void) .Ve .PP This function uses the output of \f(CW\*(C`free \-m\*(C'\fR to estimate how many libguestfs appliances could be safely started in parallel. Note that it always returns ≥ 1. .PP Function \f(CW\*(C`df/estimate\-max\-threads.c:read_line_from\*(C'\fR .IX Subsection "Function df/estimate-max-threads.c:read_line_from" .PP .Vb 2 \& static char * \& read_line_from (const char *cmd) .Ve .PP Run external command and read the first line of output. .PP \fIFile \fIdf/parallel.c\fI\fR .IX Subsection "File df/parallel.c" .PP This file is used by \f(CW\*(C`virt\-df\*(C'\fR and some of the other tools when they need to run multiple parallel libguestfs instances to operate on a large number of libvirt domains efficiently. .PP It implements a multithreaded work queue. In addition it reorders the output so the output still appears in the same order as the input (ie. still ordered alphabetically). .PP Function \f(CW\*(C`df/parallel.c:start_threads\*(C'\fR .IX Subsection "Function df/parallel.c:start_threads" .PP .Vb 2 \& int \& start_threads (size_t option_P, guestfs_h *options_handle, work_fn work) .Ve .PP Run the threads and work through the global list of libvirt domains. .PP \&\f(CW\*(C`option_P\*(C'\fR is whatever the user passed in the \fI\-P\fR option, or \&\f(CW0\fR if the user didn't use the \fI\-P\fR option (in which case the number of threads is chosen heuristically). .PP \&\f(CW\*(C`options_handle\*(C'\fR (which may be \f(CW\*(C`NULL\*(C'\fR) is the global guestfs handle created by the options mini-library. .PP The work function (\f(CW\*(C`work\*(C'\fR) should do the work (inspecting the domain, etc.) on domain index \f(CW\*(C`i\*(C'\fR. However it \fImust not\fR print out any result directly. Instead it prints anything it needs to the supplied \f(CW\*(C`FILE *\*(C'\fR. The work function should return \f(CW0\fR on success or \f(CW\*(C`\-1\*(C'\fR on error. .PP The \f(CW\*(C`start_threads\*(C'\fR function returns \f(CW0\fR if all work items completed successfully, or \f(CW\*(C`\-1\*(C'\fR if there was an error. .SS "Subdirectory \fIfish\fP" .IX Subsection "Subdirectory fish" \fIFile \fIfish/alloc.c\fI\fR .IX Subsection "File fish/alloc.c" .PP This file implements the guestfish \f(CW\*(C`alloc\*(C'\fR and \f(CW\*(C`sparse\*(C'\fR commands. .PP Function \f(CW\*(C`fish/alloc.c:alloc_disk\*(C'\fR .IX Subsection "Function fish/alloc.c:alloc_disk" .PP .Vb 2 \& int \& alloc_disk (const char *filename, const char *size_str, int add, int sparse) .Ve .PP This is the underlying allocation function. It's called from a few other places in guestfish. .PP \fIFile \fIfish/config.c\fI\fR .IX Subsection "File fish/config.c" .PP This file parses the guestfish configuration file, usually \&\fI~/.libguestfs\-tools.rc\fR or \fI/etc/libguestfs\-tools.conf\fR. .PP Note that \f(CW\*(C`parse_config\*(C'\fR is called very early, before command line parsing, before the \f(CW\*(C`verbose\*(C'\fR flag has been set, even before the global handle \f(CW\*(C`g\*(C'\fR is opened. .PP \fIFile \fIfish/copy.c\fI\fR .IX Subsection "File fish/copy.c" .PP This file implements the guestfish commands \f(CW\*(C`copy\-in\*(C'\fR and \&\f(CW\*(C`copy\-out\*(C'\fR. .PP \fIFile \fIfish/decrypt.c\fI\fR .IX Subsection "File fish/decrypt.c" .PP This file implements the decryption of disk images, usually done before mounting their partitions. .PP Function \f(CW\*(C`fish/decrypt.c:make_mapname\*(C'\fR .IX Subsection "Function fish/decrypt.c:make_mapname" .PP .Vb 2 \& static void \& make_mapname (const char *device, char *mapname, size_t len) .Ve .PP Make a \s-1LUKS\s0 map name from the partition name, eg. \f(CW"/dev/vda2" => "luksvda2"\fR .PP Function \f(CW\*(C`fish/decrypt.c:inspect_do_decrypt\*(C'\fR .IX Subsection "Function fish/decrypt.c:inspect_do_decrypt" .PP .Vb 2 \& void \& inspect_do_decrypt (guestfs_h *g) .Ve .PP Simple implementation of decryption: look for any \f(CW\*(C`crypto_LUKS\*(C'\fR partitions and decrypt them, then rescan for VGs. This only works for Fedora whole-disk encryption. \s-1WIP\s0 to make this work for other encryption schemes. .PP \fIFile \fIfish/destpaths.c\fI\fR .IX Subsection "File fish/destpaths.c" .PP The file handles tab-completion of filesystem paths in guestfish. .PP \fIFile \fIfish/display\-options.c\fI\fR .IX Subsection "File fish/display-options.c" .PP This file contains common code used to implement \fI\-\-short\-options\fR and \fI\-\-long\-options\fR in C virt tools. (The equivalent for OCaml virt tools is implemented by \fImllib/getopt.ml\fR). .PP These \*(L"hidden\*(R" options are used to implement bash tab completion. .PP Function \f(CW\*(C`fish/display\-options.c:display_short_options\*(C'\fR .IX Subsection "Function fish/display-options.c:display_short_options" .PP .Vb 2 \& void \& display_short_options (const char *format) .Ve .PP Implements the internal \f(CW\*(C`tool \f(CI\-\-short\-options\f(CW\*(C'\fR flag, which just lists out the short options available. Used by bash completion. .PP Function \f(CW\*(C`fish/display\-options.c:display_long_options\*(C'\fR .IX Subsection "Function fish/display-options.c:display_long_options" .PP .Vb 2 \& void \& display_long_options (const struct option *long_options) .Ve .PP Implements the internal \f(CW\*(C`tool \f(CI\-\-long\-options\f(CW\*(C'\fR flag, which just lists out the long options available. Used by bash completion. .PP \fIFile \fIfish/display.c\fI\fR .IX Subsection "File fish/display.c" .PP The file implements the guestfish \f(CW\*(C`display\*(C'\fR command, for displaying graphical files (icons, images) in disk images. .PP \fIFile \fIfish/domain.c\fI\fR .IX Subsection "File fish/domain.c" .PP Implements the guestfish (and other tools) \fI\-d\fR option. .PP Function \f(CW\*(C`fish/domain.c:add_libvirt_drives\*(C'\fR .IX Subsection "Function fish/domain.c:add_libvirt_drives" .PP .Vb 2 \& int \& add_libvirt_drives (guestfs_h *g, const char *guest) .Ve .PP This function is called when a user invokes \f(CW\*(C`guestfish \-d guest\*(C'\fR. .PP Returns the number of drives added (\f(CW\*(C`> 0\*(C'\fR), or \f(CW\*(C`\-1\*(C'\fR for failure. .PP \fIFile \fIfish/echo.c\fI\fR .IX Subsection "File fish/echo.c" .PP The file implements the guestfish \f(CW\*(C`echo\*(C'\fR command. .PP \fIFile \fIfish/edit.c\fI\fR .IX Subsection "File fish/edit.c" .PP guestfish \f(CW\*(C`edit\*(C'\fR command, suggested by Ján Ondrej. .PP \fIFile \fIfish/events.c\fI\fR .IX Subsection "File fish/events.c" .PP This file implements the guestfish event-related commands, \&\f(CW\*(C`event\*(C'\fR, \f(CW\*(C`delete\-event\*(C'\fR and \f(CW\*(C`list\-events\*(C'\fR. .PP \fIFile \fIfish/file\-edit.c\fI\fR .IX Subsection "File fish/file-edit.c" .PP This file implements common file editing in a range of utilities including \fIguestfish\fR\|(1), \fIvirt\-edit\fR\|(1), \fIvirt\-customize\fR\|(1) and \fIvirt\-builder\fR\|(1). .PP It contains the code for both interactive\-(editor\-)based editing and non-interactive editing using Perl snippets. .PP Function \f(CW\*(C`fish/file\-edit.c:edit_file_editor\*(C'\fR .IX Subsection "Function fish/file-edit.c:edit_file_editor" .PP .Vb 3 \& int \& edit_file_editor (guestfs_h *g, const char *filename, const char *editor, \& const char *backup_extension, int verbose) .Ve .PP Edit \f(CW\*(C`filename\*(C'\fR using the specified \f(CW\*(C`editor\*(C'\fR application. .PP If \f(CW\*(C`backup_extension\*(C'\fR is not null, then a copy of \f(CW\*(C`filename\*(C'\fR is saved with \f(CW\*(C`backup_extension\*(C'\fR appended to its file name. .PP If \f(CW\*(C`editor\*(C'\fR is null, then the \f(CW$EDITOR\fR environment variable will be queried for the editor application, leaving \f(CW\*(C`vi\*(C'\fR as fallback if not set. .PP Returns \f(CW\*(C`\-1\*(C'\fR for failure, \f(CW0\fR on success, \f(CW1\fR if the editor did not change the file (e.g. the user closed the editor without saving). .PP Function \f(CW\*(C`fish/file\-edit.c:edit_file_perl\*(C'\fR .IX Subsection "Function fish/file-edit.c:edit_file_perl" .PP .Vb 3 \& int \& edit_file_perl (guestfs_h *g, const char *filename, const char *perl_expr, \& const char *backup_extension, int verbose) .Ve .PP Edit \f(CW\*(C`filename\*(C'\fR running the specified \f(CW\*(C`perl_expr\*(C'\fR using Perl. .PP If \f(CW\*(C`backup_extension\*(C'\fR is not null, then a copy of \f(CW\*(C`filename\*(C'\fR is saved with \f(CW\*(C`backup_extension\*(C'\fR appended to its file name. .PP Returns \f(CW\*(C`\-1\*(C'\fR for failure, \f(CW0\fR on success. .PP \fIFile \fIfish/fish.c\fI\fR .IX Subsection "File fish/fish.c" .PP guestfish, the guest filesystem shell. This file contains the main loop and utilities. .PP Function \f(CW\*(C`fish/fish.c:parse_command_line\*(C'\fR .IX Subsection "Function fish/fish.c:parse_command_line" .PP .Vb 2 \& static struct parsed_command \& parse_command_line (char *buf, int *exit_on_error_rtn) .Ve .PP Parse a command string, splitting at whitespace, handling \f(CW\*(Aq!\*(Aq\fR, \&\f(CW\*(Aq#\*(Aq\fR etc. This destructively updates \f(CW\*(C`buf\*(C'\fR. .PP \&\f(CW\*(C`exit_on_error_rtn\*(C'\fR is used to pass in the global \f(CW\*(C`exit_on_error\*(C'\fR setting and to return the local setting (eg. if the command begins with \f(CW\*(Aq\-\*(Aq\fR). .PP Returns in \f(CW\*(C`parsed_command.status\*(C'\fR: .ie n .IP "1" 4 .el .IP "\f(CW1\fR" 4 .IX Item "1" got a guestfish command (returned in \f(CW\*(C`cmd_rtn\*(C'\fR/\f(CW\*(C`argv_rtn\*(C'\fR/\f(CW\*(C`pipe_rtn\*(C'\fR) .ie n .IP "0" 4 .el .IP "\f(CW0\fR" 4 .IX Item "0" no guestfish command, but otherwise \s-1OK\s0 .ie n .IP """\-1""" 4 .el .IP "\f(CW\-1\fR" 4 .IX Item "-1" an error .PP Function \f(CW\*(C`fish/fish.c:parse_quoted_string\*(C'\fR .IX Subsection "Function fish/fish.c:parse_quoted_string" .PP .Vb 2 \& static ssize_t \& parse_quoted_string (char *p) .Ve .PP Parse double-quoted strings, replacing backslash escape sequences with the true character. Since the string is returned in place, the escapes must make the string shorter. .PP Function \f(CW\*(C`fish/fish.c:execute_and_inline\*(C'\fR .IX Subsection "Function fish/fish.c:execute_and_inline" .PP .Vb 2 \& static int \& execute_and_inline (const char *cmd, int global_exit_on_error) .Ve .PP Used to handle \f(CW\*(C` 0) or \f(CW0\fR if there is an error. .PP Function \f(CW\*(C`p2v/conversion.c:connect_with_source_port\*(C'\fR .IX Subsection "Function p2v/conversion.c:connect_with_source_port" .PP .Vb 2 \& static int \& connect_with_source_port (const char *hostname, int dest_port, int source_port) .Ve .PP Connect to \f(CW\*(C`hostname:dest_port\*(C'\fR, resolving the address using \&\fIgetaddrinfo\fR\|(3). .PP This also sets the source port of the connection to the first free port number ≥ \f(CW\*(C`source_port\*(C'\fR. .PP This may involve multiple connections \- to IPv4 and IPv6 for instance. .PP Function \f(CW\*(C`p2v/conversion.c:generate_libvirt_xml\*(C'\fR .IX Subsection "Function p2v/conversion.c:generate_libvirt_xml" .PP .Vb 3 \& static void \& generate_libvirt_xml (struct config *config, struct data_conn *data_conns, \& const char *filename) .Ve .PP Write the libvirt \s-1XML\s0 for this physical machine. .PP Note this is not actually input for libvirt. It's input for virt\-v2v on the conversion server. Virt\-v2v will (if necessary) generate the final libvirt \s-1XML.\s0 .PP Function \f(CW\*(C`p2v/conversion.c:map_interface_to_network\*(C'\fR .IX Subsection "Function p2v/conversion.c:map_interface_to_network" .PP .Vb 2 \& static const char * \& map_interface_to_network (struct config *config, const char *interface) .Ve .PP Using \f(CW\*(C`config\->network_map\*(C'\fR, map the interface to a target network name. If no map is found, return \f(CW\*(C`default\*(C'\fR. See \&\fIvirt\-p2v\fR\|(1) documentation of \f(CW"p2v.network"\fR for how the network map works. .PP Note this returns a static string which is only valid as long as \&\f(CW\*(C`config\->network_map\*(C'\fR is not freed. .PP Function \f(CW\*(C`p2v/conversion.c:generate_name\*(C'\fR .IX Subsection "Function p2v/conversion.c:generate_name" .PP .Vb 2 \& static void \& generate_name (struct config *config, const char *filename) .Ve .PP Write the guest name into \f(CW\*(C`filename\*(C'\fR. .PP Function \f(CW\*(C`p2v/conversion.c:generate_wrapper_script\*(C'\fR .IX Subsection "Function p2v/conversion.c:generate_wrapper_script" .PP .Vb 3 \& static void \& generate_wrapper_script (struct config *config, const char *remote_dir, \& const char *filename) .Ve .PP Construct the virt\-v2v wrapper script. .PP This will be sent to the remote server, and is easier than trying to \*(L"type\*(R" a long and complex single command line into the ssh connection when we start the conversion. .PP Function \f(CW\*(C`p2v/conversion.c:print_quoted\*(C'\fR .IX Subsection "Function p2v/conversion.c:print_quoted" .PP .Vb 2 \& static void \& print_quoted (FILE *fp, const char *s) .Ve .PP Print a shell-quoted string on \f(CW\*(C`fp\*(C'\fR. .PP Function \f(CW\*(C`p2v/conversion.c:generate_dmesg_file\*(C'\fR .IX Subsection "Function p2v/conversion.c:generate_dmesg_file" .PP .Vb 2 \& static void \& generate_dmesg_file (const char *filename) .Ve .PP Put the output of the \f(CW\*(C`dmesg\*(C'\fR command into \f(CW\*(C`filename\*(C'\fR. .PP If the command fails, this is non-fatal. .PP \fIFile \fIp2v/gui.c\fI\fR .IX Subsection "File p2v/gui.c" .PP This file implements almost all of the virt\-p2v graphical user interface (\s-1GUI\s0). .PP The \s-1GUI\s0 has three main dialogs: .IP "Connection dialog" 4 .IX Item "Connection dialog" The connection dialog is the one shown initially. It asks the user to type in the login details for the remote conversion server and invites the user to test the ssh connection. .IP "Conversion dialog" 4 .IX Item "Conversion dialog" The conversion dialog asks for information about the target \s-1VM \&\s0(eg. the number of vCPUs required), and about what to convert (eg. which network interfaces should be copied and which should be ignored). .IP "Running dialog" 4 .IX Item "Running dialog" The running dialog is displayed when the P2V process is underway. It mainly displays the virt\-v2v debug messages. .PP Note that the other major dialog (\f(CW"Configure network ..."\fR) is handled entirely by NetworkManager's \fInm\-connection\-editor\fR\|(1) program and has nothing to do with this code. .PP Function \f(CW\*(C`p2v/gui.c:gui_conversion\*(C'\fR .IX Subsection "Function p2v/gui.c:gui_conversion" .PP .Vb 2 \& void \& gui_conversion (struct config *config) .Ve .PP The entry point from the main program. .PP Note that \f(CW\*(C`gtk_init\*(C'\fR etc have already been called in \f(CW\*(C`main\*(C'\fR. .PP Function \f(CW\*(C`p2v/gui.c:create_connection_dialog\*(C'\fR .IX Subsection "Function p2v/gui.c:create_connection_dialog" .PP .Vb 2 \& static void \& create_connection_dialog (struct config *config) .Ve .PP Create the connection dialog. .PP This creates the dialog, but it is not displayed. See \&\f(CW\*(C`show_connection_dialog\*(C'\fR. .PP Function \f(CW\*(C`p2v/gui.c:username_changed_callback\*(C'\fR .IX Subsection "Function p2v/gui.c:username_changed_callback" .PP .Vb 2 \& static void \& username_changed_callback (GtkWidget *w, gpointer data) .Ve .PP If the username is \*(L"root\*(R", disable the sudo button. .PP Function \f(CW\*(C`p2v/gui.c:password_or_identity_changed_callback\*(C'\fR .IX Subsection "Function p2v/gui.c:password_or_identity_changed_callback" .PP .Vb 2 \& static void \& password_or_identity_changed_callback (GtkWidget *w, gpointer data) .Ve .PP The password or \s-1SSH\s0 identity \s-1URL\s0 entries are mutually exclusive, so if one contains text then disable the other. This function is called when the \*(L"changed\*(R" signal is received on either. .PP Function \f(CW\*(C`p2v/gui.c:show_connection_dialog\*(C'\fR .IX Subsection "Function p2v/gui.c:show_connection_dialog" .PP .Vb 2 \& static void \& show_connection_dialog (void) .Ve .PP Hide all other dialogs and show the connection dialog. .PP Function \f(CW\*(C`p2v/gui.c:test_connection_clicked\*(C'\fR .IX Subsection "Function p2v/gui.c:test_connection_clicked" .PP .Vb 2 \& static void \& test_connection_clicked (GtkWidget *w, gpointer data) .Ve .PP Callback from the \f(CW\*(C`Test connection\*(C'\fR button. .PP This initiates a background thread which actually does the ssh to the conversion server and the rest of the testing (see \&\f(CW\*(C`test_connection_thread\*(C'\fR). .PP Function \f(CW\*(C`p2v/gui.c:test_connection_thread\*(C'\fR .IX Subsection "Function p2v/gui.c:test_connection_thread" .PP .Vb 2 \& static void * \& test_connection_thread (void *data) .Ve .PP Run \f(CW\*(C`test_connection\*(C'\fR (in a detached background thread). Once it finishes stop the spinner and set the spinner message appropriately. If the test is successful then we enable the \&\f(CW\*(C`Next\*(C'\fR button. If unsuccessful, an error is shown in the connection dialog. .PP Function \f(CW\*(C`p2v/gui.c:start_spinner\*(C'\fR .IX Subsection "Function p2v/gui.c:start_spinner" .PP .Vb 2 \& static gboolean \& start_spinner (gpointer user_data) .Ve .PP Idle task called from \f(CW\*(C`test_connection_thread\*(C'\fR (but run on the main thread) to start the spinner in the connection dialog. .PP Function \f(CW\*(C`p2v/gui.c:stop_spinner\*(C'\fR .IX Subsection "Function p2v/gui.c:stop_spinner" .PP .Vb 2 \& static gboolean \& stop_spinner (gpointer user_data) .Ve .PP Idle task called from \f(CW\*(C`test_connection_thread\*(C'\fR (but run on the main thread) to stop the spinner in the connection dialog. .PP Function \f(CW\*(C`p2v/gui.c:test_connection_error\*(C'\fR .IX Subsection "Function p2v/gui.c:test_connection_error" .PP .Vb 2 \& static gboolean \& test_connection_error (gpointer user_data) .Ve .PP Idle task called from \f(CW\*(C`test_connection_thread\*(C'\fR (but run on the main thread) when there is an error. Display the error message and disable the \f(CW\*(C`Next\*(C'\fR button so the user is forced to correct it. .PP Function \f(CW\*(C`p2v/gui.c:test_connection_ok\*(C'\fR .IX Subsection "Function p2v/gui.c:test_connection_ok" .PP .Vb 2 \& static gboolean \& test_connection_ok (gpointer user_data) .Ve .PP Idle task called from \f(CW\*(C`test_connection_thread\*(C'\fR (but run on the main thread) when the connection test was successful. .PP Function \f(CW\*(C`p2v/gui.c:configure_network_button_clicked\*(C'\fR .IX Subsection "Function p2v/gui.c:configure_network_button_clicked" .PP .Vb 2 \& static void \& configure_network_button_clicked (GtkWidget *w, gpointer data) .Ve .PP Callback from the \f(CW\*(C`Configure network ...\*(C'\fR button. This dialog is handled entirely by an external program which is part of NetworkManager. .PP Function \f(CW\*(C`p2v/gui.c:xterm_button_clicked\*(C'\fR .IX Subsection "Function p2v/gui.c:xterm_button_clicked" .PP .Vb 2 \& static void \& xterm_button_clicked (GtkWidget *w, gpointer data) .Ve .PP Callback from the \f(CW\*(C`XTerm ...\*(C'\fR button. .PP Function \f(CW\*(C`p2v/gui.c:about_button_clicked\*(C'\fR .IX Subsection "Function p2v/gui.c:about_button_clicked" .PP .Vb 2 \& static void \& about_button_clicked (GtkWidget *w, gpointer data) .Ve .PP Callback from the \f(CW\*(C`About virt\-p2v ...\*(C'\fR button. .PP See also \fIp2v/about\-authors.c\fR and \fIp2v/about\-license.c\fR. .PP Function \f(CW\*(C`p2v/gui.c:connection_next_clicked\*(C'\fR .IX Subsection "Function p2v/gui.c:connection_next_clicked" .PP .Vb 2 \& static void \& connection_next_clicked (GtkWidget *w, gpointer data) .Ve .PP Callback when the connection dialog \f(CW\*(C`Next\*(C'\fR button has been clicked. .PP Function \f(CW\*(C`p2v/gui.c:create_conversion_dialog\*(C'\fR .IX Subsection "Function p2v/gui.c:create_conversion_dialog" .PP .Vb 2 \& static void \& create_conversion_dialog (struct config *config) .Ve .PP Create the conversion dialog. .PP This creates the dialog, but it is not displayed. See \&\f(CW\*(C`show_conversion_dialog\*(C'\fR. .PP Function \f(CW\*(C`p2v/gui.c:show_conversion_dialog\*(C'\fR .IX Subsection "Function p2v/gui.c:show_conversion_dialog" .PP .Vb 2 \& static void \& show_conversion_dialog (void) .Ve .PP Hide all other dialogs and show the conversion dialog. .PP Function \f(CW\*(C`p2v/gui.c:set_info_label\*(C'\fR .IX Subsection "Function p2v/gui.c:set_info_label" .PP .Vb 2 \& static void \& set_info_label (void) .Ve .PP Update the \f(CW\*(C`Information\*(C'\fR section in the conversion dialog. .PP Note that \f(CW\*(C`v2v_version\*(C'\fR (the remote virt\-v2v version) is read from the remote virt\-v2v in the \f(CW\*(C`test_connection\*(C'\fR function. .PP Function \f(CW\*(C`p2v/gui.c:repopulate_output_combo\*(C'\fR .IX Subsection "Function p2v/gui.c:repopulate_output_combo" .PP .Vb 2 \& static void \& repopulate_output_combo (struct config *config) .Ve .PP Repopulate the list of output drivers in the \f(CW\*(C`Output to (\-o)\*(C'\fR combo. The list of drivers is read from the remote virt\-v2v instance in \f(CW\*(C`test_connection\*(C'\fR. .PP Function \f(CW\*(C`p2v/gui.c:populate_disks\*(C'\fR .IX Subsection "Function p2v/gui.c:populate_disks" .PP .Vb 2 \& static void \& populate_disks (GtkTreeView *disks_list) .Ve .PP Populate the \f(CW\*(C`Fixed hard disks\*(C'\fR treeview. .PP Function \f(CW\*(C`p2v/gui.c:populate_removable\*(C'\fR .IX Subsection "Function p2v/gui.c:populate_removable" .PP .Vb 2 \& static void \& populate_removable (GtkTreeView *removable_list) .Ve .PP Populate the \f(CW\*(C`Removable media\*(C'\fR treeview. .PP Function \f(CW\*(C`p2v/gui.c:populate_interfaces\*(C'\fR .IX Subsection "Function p2v/gui.c:populate_interfaces" .PP .Vb 2 \& static void \& populate_interfaces (GtkTreeView *interfaces_list) .Ve .PP Populate the \f(CW\*(C`Network interfaces\*(C'\fR treeview. .PP Function \f(CW\*(C`p2v/gui.c:maybe_identify_click\*(C'\fR .IX Subsection "Function p2v/gui.c:maybe_identify_click" .PP .Vb 3 \& static gboolean \& maybe_identify_click (GtkWidget *interfaces_list, GdkEventButton *event, \& gpointer data) .Ve .PP When the user clicks on the interface name on the list of interfaces, we want to run \f(CW\*(C`ethtool \-\-identify\*(C'\fR, which usually makes some lights flash on the physical interface. .PP We cannot catch clicks on the cell itself, so we have to go via a more obscure route. See http://stackoverflow.com/a/27207433 and https://en.wikibooks.org/wiki/GTK%2B_By_Example/Tree_View/Events .PP Function \f(CW\*(C`p2v/gui.c:conversion_back_clicked\*(C'\fR .IX Subsection "Function p2v/gui.c:conversion_back_clicked" .PP .Vb 2 \& static void \& conversion_back_clicked (GtkWidget *w, gpointer data) .Ve .PP The conversion dialog \f(CW\*(C`Back\*(C'\fR button has been clicked. .PP Function \f(CW\*(C`p2v/gui.c:vcpus_or_memory_check_callback\*(C'\fR .IX Subsection "Function p2v/gui.c:vcpus_or_memory_check_callback" .PP .Vb 2 \& static void \& vcpus_or_memory_check_callback (GtkWidget *w, gpointer data) .Ve .PP Display a warning if the vCPUs or memory is outside the supported range (https://bugzilla.redhat.com/823758). .PP Function \f(CW\*(C`p2v/gui.c:create_running_dialog\*(C'\fR .IX Subsection "Function p2v/gui.c:create_running_dialog" .PP .Vb 2 \& static void \& create_running_dialog (void) .Ve .PP Create the running dialog. .PP This creates the dialog, but it is not displayed. See \&\f(CW\*(C`show_running_dialog\*(C'\fR. .PP Function \f(CW\*(C`p2v/gui.c:show_running_dialog\*(C'\fR .IX Subsection "Function p2v/gui.c:show_running_dialog" .PP .Vb 2 \& static void \& show_running_dialog (void) .Ve .PP Hide all other dialogs and show the running dialog. .PP Function \f(CW\*(C`p2v/gui.c:set_log_dir\*(C'\fR .IX Subsection "Function p2v/gui.c:set_log_dir" .PP .Vb 2 \& static gboolean \& set_log_dir (gpointer user_data) .Ve .PP Display the remote log directory in the running dialog. .PP If this isn't called from the main thread, then you must only call it via an idle task (\f(CW\*(C`g_idle_add\*(C'\fR). .PP \&\fB\s-1NB:\s0\fR This frees the remote_dir (\f(CW\*(C`user_data\*(C'\fR pointer) which was strdup'd in \f(CW\*(C`notify_ui_callback\*(C'\fR. .PP Function \f(CW\*(C`p2v/gui.c:set_status\*(C'\fR .IX Subsection "Function p2v/gui.c:set_status" .PP .Vb 2 \& static gboolean \& set_status (gpointer user_data) .Ve .PP Display the conversion status in the running dialog. .PP If this isn't called from the main thread, then you must only call it via an idle task (\f(CW\*(C`g_idle_add\*(C'\fR). .PP \&\fB\s-1NB:\s0\fR This frees the message (\f(CW\*(C`user_data\*(C'\fR pointer) which was strdup'd in \f(CW\*(C`notify_ui_callback\*(C'\fR. .PP Function \f(CW\*(C`p2v/gui.c:add_v2v_output\*(C'\fR .IX Subsection "Function p2v/gui.c:add_v2v_output" .PP .Vb 2 \& static gboolean \& add_v2v_output (gpointer user_data) .Ve .PP Append output from the virt\-v2v process to the buffer, and scroll to ensure it is visible. .PP This function is able to parse \s-1ANSI\s0 colour sequences and more. .PP If this isn't called from the main thread, then you must only call it via an idle task (\f(CW\*(C`g_idle_add\*(C'\fR). .PP \&\fB\s-1NB:\s0\fR This frees the message (\f(CW\*(C`user_data\*(C'\fR pointer) which was strdup'd in \f(CW\*(C`notify_ui_callback\*(C'\fR. .PP Function \f(CW\*(C`p2v/gui.c:start_conversion_clicked\*(C'\fR .IX Subsection "Function p2v/gui.c:start_conversion_clicked" .PP .Vb 2 \& static void \& start_conversion_clicked (GtkWidget *w, gpointer data) .Ve .PP Callback when the \f(CW\*(C`Start conversion\*(C'\fR button is clicked. .PP Function \f(CW\*(C`p2v/gui.c:start_conversion_thread\*(C'\fR .IX Subsection "Function p2v/gui.c:start_conversion_thread" .PP .Vb 2 \& static void * \& start_conversion_thread (void *data) .Ve .PP This is the background thread which performs the conversion. .PP Function \f(CW\*(C`p2v/gui.c:conversion_error\*(C'\fR .IX Subsection "Function p2v/gui.c:conversion_error" .PP .Vb 2 \& static gboolean \& conversion_error (gpointer user_data) .Ve .PP Idle task called from \f(CW\*(C`start_conversion_thread\*(C'\fR (but run on the main thread) when there was an error during the conversion. .PP Function \f(CW\*(C`p2v/gui.c:conversion_finished\*(C'\fR .IX Subsection "Function p2v/gui.c:conversion_finished" .PP .Vb 2 \& static gboolean \& conversion_finished (gpointer user_data) .Ve .PP Idle task called from \f(CW\*(C`start_conversion_thread\*(C'\fR (but run on the main thread) when the conversion completed without errors. .PP Function \f(CW\*(C`p2v/gui.c:notify_ui_callback\*(C'\fR .IX Subsection "Function p2v/gui.c:notify_ui_callback" .PP .Vb 2 \& static void \& notify_ui_callback (int type, const char *data) .Ve .PP This is called from \fIconversion.c\fR:\f(CW\*(C`start_conversion\*(C'\fR when there is a status change or a log message. .PP Function \f(CW\*(C`p2v/gui.c:cancel_conversion_dialog\*(C'\fR .IX Subsection "Function p2v/gui.c:cancel_conversion_dialog" .PP .Vb 2 \& static void \& cancel_conversion_dialog (GtkWidget *w, gpointer data) .Ve .PP This is called when the user clicks on the \*(L"Cancel conversion\*(R" button. Since conversions can run for a long time, and cancelling the conversion is non-recoverable, this function displays a confirmation dialog before cancelling the conversion. .PP \fIFile \fIp2v/inhibit.c\fI\fR .IX Subsection "File p2v/inhibit.c" .PP This file is used to inhibit power saving, sleep, suspend etc during the conversion. .PP The method it uses is to send a D\-Bus message to logind, as described here: .PP https://www.freedesktop.org/wiki/Software/systemd/inhibit/ .PP If virt\-p2v is compiled without D\-Bus support then this does nothing. .PP Function \f(CW\*(C`p2v/inhibit.c:inhibit_power_saving\*(C'\fR .IX Subsection "Function p2v/inhibit.c:inhibit_power_saving" .PP .Vb 2 \& int \& inhibit_power_saving (void) .Ve .PP Inhibit all forms of power saving. A file descriptor is returned, and when the file descriptor is closed the inhibit is stopped. .PP If the function returns \f(CW\*(C`\-1\*(C'\fR then \f(CW\*(C`Inhibit\*(C'\fR operation could not be performed (eg. if we are compiled without D\-Bus support, or there is some error contacting logind). This is not usually fatal from the point of view of the caller, conversion can continue. .PP \fIFile \fIp2v/kernel\-cmdline.c\fI\fR .IX Subsection "File p2v/kernel-cmdline.c" .PP Mini library to read and parse \f(CW\*(C`/proc/cmdline\*(C'\fR. .PP Function \f(CW\*(C`p2v/kernel\-cmdline.c:parse_cmdline_string\*(C'\fR .IX Subsection "Function p2v/kernel-cmdline.c:parse_cmdline_string" .PP .Vb 2 \& char ** \& parse_cmdline_string (const char *cmdline) .Ve .PP Read and parse \f(CW\*(C`/proc/cmdline\*(C'\fR. .PP We only support double quoting, consistent with the Linux documentation. https://www.kernel.org/doc/Documentation/kernel\-parameters.txt .PP systemd supports single and double quoting and single character escaping, but we don't support all that. .PP Returns a list of key, value pairs, terminated by \f(CW\*(C`NULL\*(C'\fR. .PP \fIFile \fIp2v/kernel.c\fI\fR .IX Subsection "File p2v/kernel.c" .PP Kernel-driven, non-interactive configuration of virt\-p2v. .PP \fIFile \fIp2v/main.c\fI\fR .IX Subsection "File p2v/main.c" .PP Function \f(CW\*(C`p2v/main.c:partition_parent\*(C'\fR .IX Subsection "Function p2v/main.c:partition_parent" .PP .Vb 2 \& static dev_t \& partition_parent (dev_t part_dev) .Ve .PP Get parent device of a partition. .PP Returns \f(CW0\fR if no parent device could be found. .PP Function \f(CW\*(C`p2v/main.c:device_contains\*(C'\fR .IX Subsection "Function p2v/main.c:device_contains" .PP .Vb 2 \& static int \& device_contains (const char *dev, dev_t root_device) .Ve .PP Return true if the named device (eg. \f(CW\*(C`dev == "sda"\*(C'\fR) contains the root filesystem. \f(CW\*(C`root_device\*(C'\fR is the major:minor of the root filesystem (eg. \f(CW\*(C`8:1\*(C'\fR if the root filesystem was \fI/dev/sda1\fR). .PP This doesn't work for LVs and so on. However we only really care if this test works on the P2V \s-1ISO\s0 where the root device is a regular partition. .PP Function \f(CW\*(C`p2v/main.c:find_all_disks\*(C'\fR .IX Subsection "Function p2v/main.c:find_all_disks" .PP .Vb 2 \& static void \& find_all_disks (void) .Ve .PP Enumerate all disks in \fI/sys/block\fR and add them to the global \&\f(CW\*(C`all_disks\*(C'\fR and \f(CW\*(C`all_removable\*(C'\fR arrays. .PP Function \f(CW\*(C`p2v/main.c:find_all_interfaces\*(C'\fR .IX Subsection "Function p2v/main.c:find_all_interfaces" .PP .Vb 2 \& static void \& find_all_interfaces (void) .Ve .PP Enumerate all network interfaces in \fI/sys/class/net\fR and add them to the global \f(CW\*(C`all_interfaces\*(C'\fR array. .PP Function \f(CW\*(C`p2v/main.c:cpuinfo_flags\*(C'\fR .IX Subsection "Function p2v/main.c:cpuinfo_flags" .PP .Vb 2 \& static int \& cpuinfo_flags (void) .Ve .PP Read the list of flags from \fI/proc/cpuinfo\fR. .PP \fIFile \fIp2v/ssh.c\fI\fR .IX Subsection "File p2v/ssh.c" .PP This file handles the ssh connections to the conversion server. .PP virt\-p2v will open several connections over the lifetime of the conversion process. .PP In \f(CW\*(C`test_connection\*(C'\fR, it will first open a connection (to check it is possible) and query virt\-v2v on the server to ensure it exists, it is the right version, and so on. This connection is then closed, because in the \s-1GUI\s0 case we don't want to deal with keeping it alive in case the administrator has set up an autologout. .PP Once we start conversion, we will open a control connection to send the libvirt configuration data and to start up virt\-v2v, and we will open up one data connection per local hard disk. The data connection(s) have a reverse port forward to the local \&\fIqemu\-nbd\fR\|(8) server which is serving the content of that hard disk. The remote port for each data connection is assigned by ssh. See \f(CW\*(C`open_data_connection\*(C'\fR and \f(CW\*(C`start_remote_conversion\*(C'\fR. .PP Function \f(CW\*(C`p2v/ssh.c:curl_download\*(C'\fR .IX Subsection "Function p2v/ssh.c:curl_download" .PP .Vb 2 \& static int \& curl_download (const char *url, const char *local_file) .Ve .PP Download \s-1URL\s0 to local file using the external 'curl' command. .PP Function \f(CW\*(C`p2v/ssh.c:cache_ssh_identity\*(C'\fR .IX Subsection "Function p2v/ssh.c:cache_ssh_identity" .PP .Vb 2 \& static int \& cache_ssh_identity (struct config *config) .Ve .PP Re-cache the \f(CW\*(C`config\->identity_url\*(C'\fR if needed. .PP Function \f(CW\*(C`p2v/ssh.c:start_ssh\*(C'\fR .IX Subsection "Function p2v/ssh.c:start_ssh" .PP .Vb 3 \& static mexp_h * \& start_ssh (unsigned spawn_flags, struct config *config, \& char **extra_args, int wait_prompt) .Ve .PP Start ssh subprocess with the standard arguments and possibly some optional arguments. Also handles authentication. .PP Function \f(CW\*(C`p2v/ssh.c:scp_file\*(C'\fR .IX Subsection "Function p2v/ssh.c:scp_file" .PP .Vb 2 \& int \& scp_file (struct config *config, const char *localfile, const char *remotefile) .Ve .PP Upload a file to remote using \fIscp\fR\|(1). .PP This is a simplified version of \*(L"start_ssh\*(R" above. .PP \fIFile \fIp2v/utils.c\fI\fR .IX Subsection "File p2v/utils.c" .PP Function \f(CW\*(C`p2v/utils.c:get_blockdev_size\*(C'\fR .IX Subsection "Function p2v/utils.c:get_blockdev_size" .PP .Vb 2 \& uint64_t \& get_blockdev_size (const char *dev) .Ve .PP Return size of a block device, from \fI/sys/block/\fIdev\fI/size\fR. .PP This function always succeeds, or else exits (since we expect \&\f(CW\*(C`dev\*(C'\fR to always be valid and the \f(CW\*(C`size\*(C'\fR file to always exist). .PP Function \f(CW\*(C`p2v/utils.c:get_blockdev_model\*(C'\fR .IX Subsection "Function p2v/utils.c:get_blockdev_model" .PP .Vb 2 \& char * \& get_blockdev_model (const char *dev) .Ve .PP Return model of a block device, from \fI/sys/block/\fIdev\fI/device/model\fR. .PP Returns \f(CW\*(C`NULL\*(C'\fR if the file was not found. The caller must free the returned string. .PP Function \f(CW\*(C`p2v/utils.c:get_blockdev_serial\*(C'\fR .IX Subsection "Function p2v/utils.c:get_blockdev_serial" .PP .Vb 2 \& char * \& get_blockdev_serial (const char *dev) .Ve .PP Return the serial number of a block device. .PP This is found using the lsblk command. .PP Returns \f(CW\*(C`NULL\*(C'\fR if we could not get the serial number. The caller must free the returned string. .PP Function \f(CW\*(C`p2v/utils.c:get_if_addr\*(C'\fR .IX Subsection "Function p2v/utils.c:get_if_addr" .PP .Vb 2 \& char * \& get_if_addr (const char *if_name) .Ve .PP Return contents of \fI/sys/class/net/\fIif_name\fI/address\fR (if found). .PP Function \f(CW\*(C`p2v/utils.c:get_if_vendor\*(C'\fR .IX Subsection "Function p2v/utils.c:get_if_vendor" .PP .Vb 2 \& char * \& get_if_vendor (const char *if_name, int truncate) .Ve .PP Return contents of \fI/sys/class/net/\fIif_name\fI/device/vendor\fR (if found), mapped to the \s-1PCI\s0 vendor. See: http://pjwelsh.blogspot.co.uk/2011/11/howto\-get\-network\-card\-vendor\-device\-or.html .PP Function \f(CW\*(C`p2v/utils.c:wait_network_online\*(C'\fR .IX Subsection "Function p2v/utils.c:wait_network_online" .PP .Vb 2 \& void \& wait_network_online (const struct config *config) .Ve .PP Wait for the network to come online, but don't error out if that fails. The caller will call \f(CW\*(C`test_connection\*(C'\fR immediately after this which will fail if the network didn't come online. .PP \fIFile \fIp2v/whole\-file.c\fI\fR .IX Subsection "File p2v/whole-file.c" .PP Function \f(CW\*(C`p2v/whole\-file.c:read_whole_file\*(C'\fR .IX Subsection "Function p2v/whole-file.c:read_whole_file" .PP .Vb 2 \& int \& read_whole_file (const char *filename, char **data_r, size_t *size_r) .Ve .PP Read the whole file into a memory buffer and return it. The file should be a regular, local, trusted file. .SS "Subdirectory \fIpython\fP" .IX Subsection "Subdirectory python" \fIFile \fIpython/handle.c\fI\fR .IX Subsection "File python/handle.c" .PP This file contains a small number of functions that are written by hand. The majority of the bindings are generated (see \&\fIpython/actions\-*.c\fR). .SS "Subdirectory \fIv2v\fP" .IX Subsection "Subdirectory v2v" \fIFile \fIv2v/domainxml\-c.c\fI\fR .IX Subsection "File v2v/domainxml-c.c" .PP This module implements various \f(CW\*(C`virsh\*(C'\fR\-like commands, but with non-broken authentication handling. .PP \fIFile \fIv2v/xml\-c.c\fI\fR .IX Subsection "File v2v/xml-c.c" .PP Mini interface to libxml2. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIguestfs\fR\|(3), \&\fIguestfs\-building\fR\|(1), \&\fIguestfs\-examples\fR\|(3), \&\fIguestfs\-internals\fR\|(1), \&\fIguestfs\-performance\fR\|(1), \&\fIguestfs\-release\-notes\fR\|(1), \&\fIguestfs\-testing\fR\|(1), \&\fIlibguestfs\-test\-tool\fR\|(1), \&\fIlibguestfs\-make\-fixed\-appliance\fR\|(1), http://libguestfs.org/. .SH "AUTHORS" .IX Header "AUTHORS" Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR) .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2009\-2016 Red Hat Inc. .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. .PP This library is distributed in the hope that it will be useful, but \&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the \s-1GNU\s0 Lesser General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA 02110\-1301 USA\s0 .SH "BUGS" .IX Header "BUGS" To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools .PP To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools .PP When reporting a bug, please supply: .IP "\(bu" 4 The version of libguestfs. .IP "\(bu" 4 Where you got libguestfs (eg. which Linux distro, compiled from source, etc) .IP "\(bu" 4 Describe the bug accurately and give a way to reproduce it. .IP "\(bu" 4 Run \fIlibguestfs\-test\-tool\fR\|(1) and paste the \fBcomplete, unedited\fR output into the bug report.