From d331fd70e2c3ba2815460c8cd93a97eb9a81c6a5 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Sun, 2 Sep 2012 18:26:48 +0100 Subject: generator: Rename 'generator_*' as '*'. This is a simple renaming of the files/modules. Note that in OCaml, module names are derived from filenames by capitalizing the first letter. Thus the old module names had the form "Generator_api_versions". The new modules names have the form "Api_versions". --- generator/Makefile.am | 70 +- generator/README | 24 +- generator/actions.ml | 10081 +++++++++++++++++++++++++++++++++ generator/actions.mli | 43 + generator/api_versions.ml | 43 + generator/api_versions.mli | 32 + generator/bindtests.ml | 841 +++ generator/c.ml | 1655 ++++++ generator/checks.ml | 285 + generator/csharp.ml | 289 + generator/daemon.ml | 579 ++ generator/docstrings.ml | 117 + generator/erlang.ml | 486 ++ generator/errnostring.ml | 337 ++ generator/events.ml | 42 + generator/fish.ml | 1087 ++++ generator/generator_actions.ml | 10081 --------------------------------- generator/generator_actions.mli | 43 - generator/generator_api_versions.ml | 43 - generator/generator_api_versions.mli | 32 - generator/generator_bindtests.ml | 841 --- generator/generator_c.ml | 1655 ------ generator/generator_checks.ml | 285 - generator/generator_csharp.ml | 289 - generator/generator_daemon.ml | 579 -- generator/generator_docstrings.ml | 117 - generator/generator_erlang.ml | 486 -- generator/generator_errnostring.ml | 337 -- generator/generator_events.ml | 42 - generator/generator_fish.ml | 1087 ---- generator/generator_gobject.ml | 1305 ----- generator/generator_haskell.ml | 251 - generator/generator_java.ml | 860 --- generator/generator_main.ml | 156 - generator/generator_ocaml.ml | 726 --- generator/generator_optgroups.ml | 39 - generator/generator_perl.ml | 1087 ---- generator/generator_php.ml | 559 -- generator/generator_pr.ml | 70 - generator/generator_pr.mli | 35 - generator/generator_prepopts.ml | 105 - generator/generator_prepopts.mli | 30 - generator/generator_python.ml | 769 --- generator/generator_ruby.ml | 761 --- generator/generator_structs.ml | 313 - generator/generator_structs.mli | 43 - generator/generator_tests_c_api.ml | 979 ---- generator/generator_types.ml | 456 -- generator/generator_utils.ml | 364 -- generator/generator_utils.mli | 133 - generator/generator_xdr.ml | 253 - generator/gobject.ml | 1305 +++++ generator/haskell.ml | 251 + generator/java.ml | 860 +++ generator/main.ml | 156 + generator/ocaml.ml | 726 +++ generator/optgroups.ml | 39 + generator/perl.ml | 1087 ++++ generator/php.ml | 559 ++ generator/pr.ml | 70 + generator/pr.mli | 35 + generator/prepopts.ml | 105 + generator/prepopts.mli | 30 + generator/python.ml | 769 +++ generator/ruby.ml | 761 +++ generator/structs.ml | 313 + generator/structs.mli | 43 + generator/tests_c_api.ml | 979 ++++ generator/types.ml | 456 ++ generator/utils.ml | 362 ++ generator/utils.mli | 133 + generator/xdr.ml | 253 + src/guestfs.pod | 19 +- 73 files changed, 25265 insertions(+), 25268 deletions(-) create mode 100644 generator/actions.ml create mode 100644 generator/actions.mli create mode 100644 generator/api_versions.ml create mode 100644 generator/api_versions.mli create mode 100644 generator/bindtests.ml create mode 100644 generator/c.ml create mode 100644 generator/checks.ml create mode 100644 generator/csharp.ml create mode 100644 generator/daemon.ml create mode 100644 generator/docstrings.ml create mode 100644 generator/erlang.ml create mode 100644 generator/errnostring.ml create mode 100644 generator/events.ml create mode 100644 generator/fish.ml delete mode 100644 generator/generator_actions.ml delete mode 100644 generator/generator_actions.mli delete mode 100644 generator/generator_api_versions.ml delete mode 100644 generator/generator_api_versions.mli delete mode 100644 generator/generator_bindtests.ml delete mode 100644 generator/generator_c.ml delete mode 100644 generator/generator_checks.ml delete mode 100644 generator/generator_csharp.ml delete mode 100644 generator/generator_daemon.ml delete mode 100644 generator/generator_docstrings.ml delete mode 100644 generator/generator_erlang.ml delete mode 100644 generator/generator_errnostring.ml delete mode 100644 generator/generator_events.ml delete mode 100644 generator/generator_fish.ml delete mode 100644 generator/generator_gobject.ml delete mode 100644 generator/generator_haskell.ml delete mode 100644 generator/generator_java.ml delete mode 100644 generator/generator_main.ml delete mode 100644 generator/generator_ocaml.ml delete mode 100644 generator/generator_optgroups.ml delete mode 100644 generator/generator_perl.ml delete mode 100644 generator/generator_php.ml delete mode 100644 generator/generator_pr.ml delete mode 100644 generator/generator_pr.mli delete mode 100644 generator/generator_prepopts.ml delete mode 100644 generator/generator_prepopts.mli delete mode 100644 generator/generator_python.ml delete mode 100644 generator/generator_ruby.ml delete mode 100644 generator/generator_structs.ml delete mode 100644 generator/generator_structs.mli delete mode 100644 generator/generator_tests_c_api.ml delete mode 100644 generator/generator_types.ml delete mode 100644 generator/generator_utils.ml delete mode 100644 generator/generator_utils.mli delete mode 100644 generator/generator_xdr.ml create mode 100644 generator/gobject.ml create mode 100644 generator/haskell.ml create mode 100644 generator/java.ml create mode 100644 generator/main.ml create mode 100644 generator/ocaml.ml create mode 100644 generator/optgroups.ml create mode 100644 generator/perl.ml create mode 100644 generator/php.ml create mode 100644 generator/pr.ml create mode 100644 generator/pr.mli create mode 100644 generator/prepopts.ml create mode 100644 generator/prepopts.mli create mode 100644 generator/python.ml create mode 100644 generator/ruby.ml create mode 100644 generator/structs.ml create mode 100644 generator/structs.mli create mode 100644 generator/tests_c_api.ml create mode 100644 generator/types.ml create mode 100644 generator/utils.ml create mode 100644 generator/utils.mli create mode 100644 generator/xdr.ml diff --git a/generator/Makefile.am b/generator/Makefile.am index eb6b79d6..e218ffac 100644 --- a/generator/Makefile.am +++ b/generator/Makefile.am @@ -16,41 +16,41 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. SOURCES = \ - generator_types.ml \ - generator_utils.mli \ - generator_utils.ml \ - generator_actions.mli \ - generator_actions.ml \ - generator_structs.mli \ - generator_structs.ml \ - generator_api_versions.mli \ - generator_api_versions.ml \ - generator_optgroups.ml \ - generator_prepopts.mli \ - generator_prepopts.ml \ - generator_events.ml \ - generator_pr.mli \ - generator_pr.ml \ - generator_docstrings.ml \ - generator_checks.ml \ - generator_c.ml \ - generator_xdr.ml \ - generator_daemon.ml \ - generator_tests_c_api.ml \ - generator_fish.ml \ - generator_ocaml.ml \ - generator_perl.ml \ - generator_python.ml \ - generator_ruby.ml \ - generator_java.ml \ - generator_haskell.ml \ - generator_csharp.ml \ - generator_php.ml \ - generator_erlang.ml \ - generator_gobject.ml \ - generator_bindtests.ml \ - generator_errnostring.ml \ - generator_main.ml + types.ml \ + utils.mli \ + utils.ml \ + actions.mli \ + actions.ml \ + structs.mli \ + structs.ml \ + api_versions.mli \ + api_versions.ml \ + optgroups.ml \ + prepopts.mli \ + prepopts.ml \ + events.ml \ + pr.mli \ + pr.ml \ + docstrings.ml \ + checks.ml \ + c.ml \ + xdr.ml \ + daemon.ml \ + tests_c_api.ml \ + fish.ml \ + ocaml.ml \ + perl.ml \ + python.ml \ + ruby.ml \ + java.ml \ + haskell.ml \ + csharp.ml \ + php.ml \ + erlang.ml \ + gobject.ml \ + bindtests.ml \ + errnostring.ml \ + main.ml SOURCES_ML = $(filter %.ml,$(SOURCES)) OBJECTS = $(SOURCES_ML:.ml=.cmo) diff --git a/generator/README b/generator/README index afc58ebc..442b0be6 100644 --- a/generator/README +++ b/generator/README @@ -2,8 +2,8 @@ This program generates a large amount of code and documentation for all the daemon actions. To add a new action there are only two files you need to change, -'generator_actions.ml' to describe the interface, and -daemon/.c to write the implementation. +'actions.ml' to describe the interface, and daemon/.c to +write the implementation. After editing these files, build it (make -C generator) to regenerate all the output files. 'make' will rerun this automatically when @@ -19,19 +19,19 @@ correctly. 'vim' comes with a good OCaml editing mode by default. (2) Read the resources at http://ocaml-tutorial.org/ -(3) A module called 'Generator_foo' is defined in one or two files -called 'generator_foo.mli' and 'generator_foo.ml' (NB: lowercase first -letter). The *.mli file, if present, defines the public interface for -the module. The *.ml file is the implementation. If the *.mli file -is missing then everything is exported. +(3) A module called 'Foo' is defined in one or two files called +'foo.mli' and 'foo.ml' (NB: lowercase first letter). The *.mli file, +if present, defines the public interface for the module. The *.ml +file is the implementation. If the *.mli file is missing then +everything is exported. Some notable files in this directory: -generator_actions.ml The libguestfs API. -generator_structs.ml Structures returned by the API. -generator_c.ml Generate C API. -generator_.ml Generate bindings for . -generator_main.ml The main generator program. + actions.ml The libguestfs API. + structs.ml Structures returned by the API. + c.ml Generate C API. + .ml Generate bindings for . + main.ml The main generator program. Note about long descriptions: diff --git a/generator/actions.ml b/generator/actions.ml new file mode 100644 index 00000000..65012adb --- /dev/null +++ b/generator/actions.ml @@ -0,0 +1,10081 @@ +(* libguestfs + * Copyright (C) 2009-2012 Red Hat Inc. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + *) + +(* Please read generator/README first. *) + +open Types +open Utils + +(* Default settings for all action fields. So we copy and override + * this struct by writing '{ defaults with name = &c }' + *) +let defaults = { name = ""; style = RErr, [], []; proc_nr = None; + tests = []; shortdesc = ""; longdesc = ""; + protocol_limit_warning = false; fish_alias = []; + fish_output = None; in_fish = true; in_docs = true; + deprecated_by = None; optional = None; + progress = false; camel_name = ""; + cancellable = false; config_only = false; + once_had_no_optargs = false; + c_name = ""; c_function = ""; c_optarg_prefix = ""; + non_c_aliases = [] } + +(* These test functions are used in the language binding tests. *) + +let test_all_args = [ + String "str"; + OptString "optstr"; + StringList "strlist"; + Bool "b"; + Int "integer"; + Int64 "integer64"; + FileIn "filein"; + FileOut "fileout"; + BufferIn "bufferin"; +] + +let test_all_optargs = [ + OBool "obool"; + OInt "oint"; + OInt64 "oint64"; + OString "ostring"; + OStringList "ostringlist"; +] + +let test_all_rets = [ + (* except for RErr, which is tested thoroughly elsewhere *) + "internal_test_rint", RInt "valout"; + "internal_test_rint64", RInt64 "valout"; + "internal_test_rbool", RBool "valout"; + "internal_test_rconststring", RConstString "valout"; + "internal_test_rconstoptstring", RConstOptString "valout"; + "internal_test_rstring", RString "valout"; + "internal_test_rstringlist", RStringList "valout"; + "internal_test_rstruct", RStruct ("valout", "lvm_pv"); + "internal_test_rstructlist", RStructList ("valout", "lvm_pv"); + "internal_test_rhashtable", RHashtable "valout"; + "internal_test_rbufferout", RBufferOut "valout"; +] + +let test_functions = [ + { defaults with + name = "internal_test"; + style = RErr, test_all_args, test_all_optargs; + in_fish = false; in_docs = false; cancellable = true; + shortdesc = "internal test function - do not use"; + longdesc = "\ +This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +parameter type correctly. + +It echos the contents of each parameter to stdout (by default) +or to a file (if C was called). + +You probably don't want to call this function." } +] @ List.flatten ( + List.map ( + fun (name, ret) -> [ + { defaults with + name = name; + style = ret, [String "val"], []; + in_fish = false; in_docs = false; + shortdesc = "internal test function - do not use"; + longdesc = "\ +This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +return type correctly. + +It converts string C to the return type. + +You probably don't want to call this function." }; + { defaults with + name = name ^ "err"; + style = ret, [], []; + in_fish = false; in_docs = false; + shortdesc = "internal test function - do not use"; + longdesc = "\ +This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +return type correctly. + +This function always returns an error. + +You probably don't want to call this function." } + ] + ) test_all_rets +) + +(* non_daemon_functions are any functions which don't get processed + * in the daemon, eg. functions for setting and getting local + * configuration values. + *) + +let non_daemon_functions = test_functions @ [ + { defaults with + name = "internal_test_set_output"; + style = RErr, [String "filename"], []; + in_fish = false; in_docs = false; + shortdesc = "internal test function - do not use"; + longdesc = "\ +This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +parameter type correctly. + +It sets the output file used by C. + +You probably don't want to call this function." }; + + { defaults with + name = "internal_test_close_output"; + style = RErr, [], []; + in_fish = false; in_docs = false; + shortdesc = "internal test function - do not use"; + longdesc = "\ +This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +parameter type correctly. + +It closes the output file previously opened by +C. + +You probably don't want to call this function." }; + + { defaults with + name = "launch"; + style = RErr, [], []; + fish_alias = ["run"]; progress = true; config_only = true; + shortdesc = "launch the qemu subprocess"; + longdesc = "\ +Internally libguestfs is implemented by running a virtual machine +using L. + +You should call this after configuring the handle +(eg. adding drives) but before performing any actions." }; + + { defaults with + name = "wait_ready"; + style = RErr, [], []; + in_fish = false; deprecated_by = Some "launch"; + shortdesc = "wait until the qemu subprocess launches (no op)"; + longdesc = "\ +This function is a no op. + +In versions of the API E 1.0.71 you had to call this function +just after calling C to wait for the launch +to complete. However this is no longer necessary because +C now does the waiting. + +If you see any calls to this function in code then you can just +remove them, unless you want to retain compatibility with older +versions of the API." }; + + { defaults with + name = "kill_subprocess"; + style = RErr, [], []; + deprecated_by = Some "shutdown"; + shortdesc = "kill the qemu subprocess"; + longdesc = "\ +This kills the qemu subprocess. + +Do not call this. See: C instead." }; + + { defaults with + name = "add_cdrom"; + style = RErr, [String "filename"], []; + deprecated_by = Some "add_drive"; config_only = true; + shortdesc = "add a CD-ROM disk image to examine"; + longdesc = "\ +This function adds a virtual CD-ROM disk image to the guest. + +B ISO files are just ordinary +read-only disk images. Use C instead." }; + + { defaults with + name = "add_drive_ro"; + style = RErr, [String "filename"], []; + fish_alias = ["add-ro"]; config_only = true; + shortdesc = "add a drive in snapshot mode (read-only)"; + longdesc = "\ +This function is the equivalent of calling C +with the optional parameter C set to 1, +so the disk is added read-only, with the format being detected +automatically." }; + + { defaults with + name = "config"; + style = RErr, [String "qemuparam"; OptString "qemuvalue"], []; + config_only = true; + shortdesc = "add qemu parameters"; + longdesc = "\ +This can be used to add arbitrary qemu command line parameters +of the form I<-param value>. Actually it's not quite arbitrary - we +prevent you from setting some parameters which would interfere with +parameters that we use. + +The first character of C string must be a C<-> (dash). + +C can be NULL." }; + + { defaults with + name = "set_qemu"; + style = RErr, [OptString "qemu"], []; + fish_alias = ["qemu"]; config_only = true; + shortdesc = "set the qemu binary"; + longdesc = "\ +Set the qemu binary that we will use. + +The default is chosen when the library was compiled by the +configure script. + +You can also override this by setting the C +environment variable. + +Setting C to C restores the default qemu binary. + +Note that you should call this function as early as possible +after creating the handle. This is because some pre-launch +operations depend on testing qemu features (by running C). +If the qemu binary changes, we don't retest features, and +so you might see inconsistent results. Using the environment +variable C is safest of all since that picks +the qemu binary at the same time as the handle is created." }; + + { defaults with + name = "get_qemu"; + style = RConstString "qemu", [], []; + tests = [ + InitNone, Always, TestRun ( + [["get_qemu"]]) + ]; + shortdesc = "get the qemu binary"; + longdesc = "\ +Return the current qemu binary. + +This is always non-NULL. If it wasn't set already, then this will +return the default qemu binary name." }; + + { defaults with + name = "set_path"; + style = RErr, [OptString "searchpath"], []; + fish_alias = ["path"]; config_only = true; + shortdesc = "set the search path"; + longdesc = "\ +Set the path that libguestfs searches for kernel and initrd.img. + +The default is C<$libdir/guestfs> unless overridden by setting +C environment variable. + +Setting C to C restores the default path." }; + + { defaults with + name = "get_path"; + style = RConstString "path", [], []; + tests = [ + InitNone, Always, TestRun ( + [["get_path"]]) + ]; + shortdesc = "get the search path"; + longdesc = "\ +Return the current search path. + +This is always non-NULL. If it wasn't set already, then this will +return the default path." }; + + { defaults with + name = "set_append"; + style = RErr, [OptString "append"], []; + fish_alias = ["append"]; config_only = true; + shortdesc = "add options to kernel command line"; + longdesc = "\ +This function is used to add additional options to the +guest kernel command line. + +The default is C unless overridden by setting +C environment variable. + +Setting C to C means I additional options +are passed (libguestfs always adds a few of its own)." }; + + { defaults with + name = "get_append"; + style = RConstOptString "append", [], []; + (* This cannot be tested with the current framework. The + * function can return NULL in normal operations, which the + * test framework interprets as an error. + *) + tests = []; + shortdesc = "get the additional kernel options"; + longdesc = "\ +Return the additional kernel options which are added to the +guest kernel command line. + +If C then no options are added." }; + + { defaults with + name = "set_autosync"; + style = RErr, [Bool "autosync"], []; + fish_alias = ["autosync"]; + shortdesc = "set autosync mode"; + longdesc = "\ +If C is true, this enables autosync. Libguestfs will make a +best effort attempt to make filesystems consistent and synchronized +when the handle is closed +(also if the program exits without closing handles). + +This is enabled by default (since libguestfs 1.5.24, previously it was +disabled by default)." }; + + { defaults with + name = "get_autosync"; + style = RBool "autosync", [], []; + tests = [ + InitNone, Always, TestOutputTrue ( + [["get_autosync"]]) + ]; + shortdesc = "get autosync mode"; + longdesc = "\ +Get the autosync flag." }; + + { defaults with + name = "set_verbose"; + style = RErr, [Bool "verbose"], []; + fish_alias = ["verbose"]; + shortdesc = "set verbose mode"; + longdesc = "\ +If C is true, this turns on verbose messages. + +Verbose messages are disabled unless the environment variable +C is defined and set to C<1>. + +Verbose messages are normally sent to C, unless you +register a callback to send them somewhere else (see +C)." }; + + { defaults with + name = "get_verbose"; + style = RBool "verbose", [], []; + shortdesc = "get verbose mode"; + longdesc = "\ +This returns the verbose messages flag." }; + + { defaults with + name = "is_ready"; + style = RBool "ready", [], []; + tests = [ + InitNone, Always, TestOutputTrue ( + [["is_ready"]]) + ]; + shortdesc = "is ready to accept commands"; + longdesc = "\ +This returns true iff this handle is ready to accept commands +(in the C state). + +For more information on states, see L." }; + + { defaults with + name = "is_config"; + style = RBool "config", [], []; + tests = [ + InitNone, Always, TestOutputFalse ( + [["is_config"]]) + ]; + shortdesc = "is in configuration state"; + longdesc = "\ +This returns true iff this handle is being configured +(in the C state). + +For more information on states, see L." }; + + { defaults with + name = "is_launching"; + style = RBool "launching", [], []; + tests = [ + InitNone, Always, TestOutputFalse ( + [["is_launching"]]) + ]; + shortdesc = "is launching subprocess"; + longdesc = "\ +This returns true iff this handle is launching the subprocess +(in the C state). + +For more information on states, see L." }; + + { defaults with + name = "is_busy"; + style = RBool "busy", [], []; + in_docs = false; + tests = [ + InitNone, Always, TestOutputFalse ( + [["is_busy"]]) + ]; + shortdesc = "is busy processing a command"; + longdesc = "\ +This always returns false. Do not use this function. + +For more information on states, see L." }; + + { defaults with + name = "get_state"; + style = RInt "state", [], []; + shortdesc = "get the current state"; + longdesc = "\ +This returns the current state as an opaque integer. This is +only useful for printing debug and internal error messages. + +For more information on states, see L." }; + + { defaults with + name = "set_memsize"; + style = RErr, [Int "memsize"], []; + fish_alias = ["memsize"]; config_only = true; + shortdesc = "set memory allocated to the qemu subprocess"; + longdesc = "\ +This sets the memory size in megabytes allocated to the +qemu subprocess. This only has any effect if called before +C. + +You can also change this by setting the environment +variable C before the handle is +created. + +For more information on the architecture of libguestfs, +see L." }; + + { defaults with + name = "get_memsize"; + style = RInt "memsize", [], []; + tests = [ + InitNone, Always, TestOutputIntOp ( + [["get_memsize"]], ">=", 256) + ]; + shortdesc = "get memory allocated to the qemu subprocess"; + longdesc = "\ +This gets the memory size in megabytes allocated to the +qemu subprocess. + +If C was not called +on this handle, and if C was not set, +then this returns the compiled-in default value for memsize. + +For more information on the architecture of libguestfs, +see L." }; + + { defaults with + name = "get_pid"; + style = RInt "pid", [], []; + fish_alias = ["pid"]; + tests = []; + shortdesc = "get PID of qemu subprocess"; + longdesc = "\ +Return the process ID of the qemu subprocess. If there is no +qemu subprocess, then this will return an error. + +This is an internal call used for debugging and testing." }; + + { defaults with + name = "version"; + style = RStruct ("version", "version"), [], []; + tests = [ + InitNone, Always, TestOutputStruct ( + [["version"]], [CompareWithInt ("major", 1)]) + ]; + shortdesc = "get the library version number"; + longdesc = "\ +Return the libguestfs version number that the program is linked +against. + +Note that because of dynamic linking this is not necessarily +the version of libguestfs that you compiled against. You can +compile the program, and then at runtime dynamically link +against a completely different C library. + +This call was added in version C<1.0.58>. In previous +versions of libguestfs there was no way to get the version +number. From C code you can use dynamic linker functions +to find out if this symbol exists (if it doesn't, then +it's an earlier version). + +The call returns a structure with four elements. The first +three (C, C and C) are numbers and +correspond to the usual version triplet. The fourth element +(C) is a string and is normally empty, but may be +used for distro-specific information. + +To construct the original version string: +C<$major.$minor.$release$extra> + +See also: L. + +I Don't use this call to test for availability +of features. In enterprise distributions we backport +features from later versions into earlier versions, +making this an unreliable way to test for features. +Use C instead." }; + + { defaults with + name = "set_selinux"; + style = RErr, [Bool "selinux"], []; + fish_alias = ["selinux"]; config_only = true; + shortdesc = "set SELinux enabled or disabled at appliance boot"; + longdesc = "\ +This sets the selinux flag that is passed to the appliance +at boot time. The default is C (disabled). + +Note that if SELinux is enabled, it is always in +Permissive mode (C). + +For more information on the architecture of libguestfs, +see L." }; + + { defaults with + name = "get_selinux"; + style = RBool "selinux", [], []; + shortdesc = "get SELinux enabled flag"; + longdesc = "\ +This returns the current setting of the selinux flag which +is passed to the appliance at boot time. See C. + +For more information on the architecture of libguestfs, +see L." }; + + { defaults with + name = "set_trace"; + style = RErr, [Bool "trace"], []; + fish_alias = ["trace"]; + tests = [ + InitNone, Always, TestOutputFalse ( + [["set_trace"; "false"]; + ["get_trace"]]) + ]; + shortdesc = "enable or disable command traces"; + longdesc = "\ +If the command trace flag is set to 1, then libguestfs +calls, parameters and return values are traced. + +If you want to trace C API calls into libguestfs (and +other libraries) then possibly a better way is to use +the external ltrace(1) command. + +Command traces are disabled unless the environment variable +C is defined and set to C<1>. + +Trace messages are normally sent to C, unless you +register a callback to send them somewhere else (see +C)." }; + + { defaults with + name = "get_trace"; + style = RBool "trace", [], []; + shortdesc = "get command trace enabled flag"; + longdesc = "\ +Return the command trace flag." }; + + { defaults with + name = "set_direct"; + style = RErr, [Bool "direct"], []; + fish_alias = ["direct"]; config_only = true; + shortdesc = "enable or disable direct appliance mode"; + longdesc = "\ +If the direct appliance mode flag is enabled, then stdin and +stdout are passed directly through to the appliance once it +is launched. + +One consequence of this is that log messages aren't caught +by the library and handled by C, +but go straight to stdout. + +You probably don't want to use this unless you know what you +are doing. + +The default is disabled." }; + + { defaults with + name = "get_direct"; + style = RBool "direct", [], []; + shortdesc = "get direct appliance mode flag"; + longdesc = "\ +Return the direct appliance mode flag." }; + + { defaults with + name = "set_recovery_proc"; + style = RErr, [Bool "recoveryproc"], []; + fish_alias = ["recovery-proc"]; config_only = true; + shortdesc = "enable or disable the recovery process"; + longdesc = "\ +If this is called with the parameter C then +C does not create a recovery process. The +purpose of the recovery process is to stop runaway qemu +processes in the case where the main program aborts abruptly. + +This only has any effect if called before C, +and the default is true. + +About the only time when you would want to disable this is +if the main process will fork itself into the background +(\"daemonize\" itself). In this case the recovery process +thinks that the main program has disappeared and so kills +qemu, which is not very helpful." }; + + { defaults with + name = "get_recovery_proc"; + style = RBool "recoveryproc", [], []; + shortdesc = "get recovery process enabled flag"; + longdesc = "\ +Return the recovery process enabled flag." }; + + { defaults with + name = "add_drive_with_if"; + style = RErr, [String "filename"; String "iface"], []; + deprecated_by = Some "add_drive"; config_only = true; + shortdesc = "add a drive specifying the QEMU block emulation to use"; + longdesc = "\ +This is the same as C but it allows you +to specify the QEMU interface emulation to use at run time." }; + + { defaults with + name = "add_drive_ro_with_if"; + style = RErr, [String "filename"; String "iface"], []; + deprecated_by = Some "add_drive"; config_only = true; + shortdesc = "add a drive read-only specifying the QEMU block emulation to use"; + longdesc = "\ +This is the same as C but it allows you +to specify the QEMU interface emulation to use at run time." }; + + { defaults with + name = "file_architecture"; + style = RString "arch", [Pathname "filename"], []; + tests = [ + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-i586-dynamic"]], "i386"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-sparc-dynamic"]], "sparc"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-win32.exe"]], "i386"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-win64.exe"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-x86_64-dynamic"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-i586.so"]], "i386"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-sparc.so"]], "sparc"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-win32.dll"]], "i386"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-win64.dll"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-x86_64.so"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/initrd-x86_64.img"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/initrd-x86_64.img.gz"]], "x86_64"); + ]; + shortdesc = "detect the architecture of a binary file"; + longdesc = "\ +This detects the architecture of the binary C, +and returns it if known. + +Currently defined architectures are: + +=over 4 + +=item \"i386\" + +This string is returned for all 32 bit i386, i486, i586, i686 binaries +irrespective of the precise processor requirements of the binary. + +=item \"x86_64\" + +64 bit x86-64. + +=item \"sparc\" + +32 bit SPARC. + +=item \"sparc64\" + +64 bit SPARC V9 and above. + +=item \"ia64\" + +Intel Itanium. + +=item \"ppc\" + +32 bit Power PC. + +=item \"ppc64\" + +64 bit Power PC. + +=back + +Libguestfs may return other architecture strings in future. + +The function works on at least the following types of files: + +=over 4 + +=item * + +many types of Un*x and Linux binary + +=item * + +many types of Un*x and Linux shared library + +=item * + +Windows Win32 and Win64 binaries + +=item * + +Windows Win32 and Win64 DLLs + +Win32 binaries and DLLs return C. + +Win64 binaries and DLLs return C. + +=item * + +Linux kernel modules + +=item * + +Linux new-style initrd images + +=item * + +some non-x86 Linux vmlinuz kernels + +=back + +What it can't do currently: + +=over 4 + +=item * + +static libraries (libfoo.a) + +=item * + +Linux old-style initrd as compressed ext2 filesystem (RHEL 3) + +=item * + +x86 Linux vmlinuz kernels + +x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and +compressed code, and are horribly hard to unpack. If you want to find +the architecture of a kernel, use the architecture of the associated +initrd or kernel module(s) instead. + +=back" }; + + { defaults with + name = "inspect_os"; + style = RStringList "roots", [], []; + shortdesc = "inspect disk and return list of operating systems found"; + longdesc = "\ +This function uses other libguestfs functions and certain +heuristics to inspect the disk(s) (usually disks belonging to +a virtual machine), looking for operating systems. + +The list returned is empty if no operating systems were found. + +If one operating system was found, then this returns a list with +a single element, which is the name of the root filesystem of +this operating system. It is also possible for this function +to return a list containing more than one element, indicating +a dual-boot or multi-boot virtual machine, with each element being +the root filesystem of one of the operating systems. + +You can pass the root string(s) returned to other +C functions in order to query further +information about each operating system, such as the name +and version. + +This function uses other libguestfs features such as +C and C in order to mount +and unmount filesystems and look at the contents. This should +be called with no disks currently mounted. The function may also +use Augeas, so any existing Augeas handle will be closed. + +This function cannot decrypt encrypted disks. The caller +must do that first (supplying the necessary keys) if the +disk is encrypted. + +Please read L for more details. + +See also C." }; + + { defaults with + name = "inspect_get_type"; + style = RString "name", [Device "root"], []; + shortdesc = "get type of inspected operating system"; + longdesc = "\ +This returns the type of the inspected operating system. +Currently defined types are: + +=over 4 + +=item \"linux\" + +Any Linux-based operating system. + +=item \"windows\" + +Any Microsoft Windows operating system. + +=item \"freebsd\" + +FreeBSD. + +=item \"netbsd\" + +NetBSD. + +=item \"hurd\" + +GNU/Hurd. + +=item \"dos\" + +MS-DOS, FreeDOS and others. + +=item \"unknown\" + +The operating system type could not be determined. + +=back + +Future versions of libguestfs may return other strings here. +The caller should be prepared to handle any string. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_arch"; + style = RString "arch", [Device "root"], []; + shortdesc = "get architecture of inspected operating system"; + longdesc = "\ +This returns the architecture of the inspected operating system. +The possible return values are listed under +C. + +If the architecture could not be determined, then the +string C is returned. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_distro"; + style = RString "distro", [Device "root"], []; + shortdesc = "get distro of inspected operating system"; + longdesc = "\ +This returns the distro (distribution) of the inspected operating +system. + +Currently defined distros are: + +=over 4 + +=item \"archlinux\" + +Arch Linux. + +=item \"buildroot\" + +Buildroot-derived distro, but not one we specifically recognize. + +=item \"centos\" + +CentOS. + +=item \"cirros\" + +Cirros. + +=item \"debian\" + +Debian. + +=item \"fedora\" + +Fedora. + +=item \"freedos\" + +FreeDOS. + +=item \"gentoo\" + +Gentoo. + +=item \"linuxmint\" + +Linux Mint. + +=item \"mageia\" + +Mageia. + +=item \"mandriva\" + +Mandriva. + +=item \"meego\" + +MeeGo. + +=item \"opensuse\" + +OpenSUSE. + +=item \"pardus\" + +Pardus. + +=item \"redhat-based\" + +Some Red Hat-derived distro. + +=item \"rhel\" + +Red Hat Enterprise Linux. + +=item \"scientificlinux\" + +Scientific Linux. + +=item \"slackware\" + +Slackware. + +=item \"ttylinux\" + +ttylinux. + +=item \"ubuntu\" + +Ubuntu. + +=item \"unknown\" + +The distro could not be determined. + +=item \"windows\" + +Windows does not have distributions. This string is +returned if the OS type is Windows. + +=back + +Future versions of libguestfs may return other strings here. +The caller should be prepared to handle any string. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_major_version"; + style = RInt "major", [Device "root"], []; + shortdesc = "get major version of inspected operating system"; + longdesc = "\ +This returns the major version number of the inspected operating +system. + +Windows uses a consistent versioning scheme which is I +reflected in the popular public names used by the operating system. +Notably the operating system known as \"Windows 7\" is really +version 6.1 (ie. major = 6, minor = 1). You can find out the +real versions corresponding to releases of Windows by consulting +Wikipedia or MSDN. + +If the version could not be determined, then C<0> is returned. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_minor_version"; + style = RInt "minor", [Device "root"], []; + shortdesc = "get minor version of inspected operating system"; + longdesc = "\ +This returns the minor version number of the inspected operating +system. + +If the version could not be determined, then C<0> is returned. + +Please read L for more details. +See also C." }; + + { defaults with + name = "inspect_get_product_name"; + style = RString "product", [Device "root"], []; + shortdesc = "get product name of inspected operating system"; + longdesc = "\ +This returns the product name of the inspected operating +system. The product name is generally some freeform string +which can be displayed to the user, but should not be +parsed by programs. + +If the product name could not be determined, then the +string C is returned. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_mountpoints"; + style = RHashtable "mountpoints", [Device "root"], []; + shortdesc = "get mountpoints of inspected operating system"; + longdesc = "\ +This returns a hash of where we think the filesystems +associated with this operating system should be mounted. +Callers should note that this is at best an educated guess +made by reading configuration files such as C. +I that this may return filesystems +which are non-existent or not mountable and callers should +be prepared to handle or ignore failures if they try to +mount them. + +Each element in the returned hashtable has a key which +is the path of the mountpoint (eg. C) and a value +which is the filesystem that would be mounted there +(eg. C). + +Non-mounted devices such as swap devices are I +returned in this list. + +For operating systems like Windows which still use drive +letters, this call will only return an entry for the first +drive \"mounted on\" C. For information about the +mapping of drive letters to partitions, see +C. + +Please read L for more details. +See also C." }; + + { defaults with + name = "inspect_get_filesystems"; + style = RStringList "filesystems", [Device "root"], []; + shortdesc = "get filesystems associated with inspected operating system"; + longdesc = "\ +This returns a list of all the filesystems that we think +are associated with this operating system. This includes +the root filesystem, other ordinary filesystems, and +non-mounted devices like swap partitions. + +In the case of a multi-boot virtual machine, it is possible +for a filesystem to be shared between operating systems. + +Please read L for more details. +See also C." }; + + { defaults with + name = "set_network"; + style = RErr, [Bool "network"], []; + fish_alias = ["network"]; config_only = true; + shortdesc = "set enable network flag"; + longdesc = "\ +If C is true, then the network is enabled in the +libguestfs appliance. The default is false. + +This affects whether commands are able to access the network +(see L). + +You must call this before calling C, otherwise +it has no effect." }; + + { defaults with + name = "get_network"; + style = RBool "network", [], []; + shortdesc = "get enable network flag"; + longdesc = "\ +This returns the enable network flag." }; + + { defaults with + name = "list_filesystems"; + style = RHashtable "fses", [], []; + shortdesc = "list filesystems"; + longdesc = "\ +This inspection command looks for filesystems on partitions, +block devices and logical volumes, returning a list of devices +containing filesystems and their type. + +The return value is a hash, where the keys are the devices +containing filesystems, and the values are the filesystem types. +For example: + + \"/dev/sda1\" => \"ntfs\" + \"/dev/sda2\" => \"ext2\" + \"/dev/vg_guest/lv_root\" => \"ext4\" + \"/dev/vg_guest/lv_swap\" => \"swap\" + +The value can have the special value \"unknown\", meaning the +content of the device is undetermined or empty. +\"swap\" means a Linux swap partition. + +This command runs other libguestfs commands, which might include +C and C, and therefore you should +use this soon after launch and only when nothing is mounted. + +Not all of the filesystems returned will be mountable. In +particular, swap partitions are returned in the list. Also +this command does not check that each filesystem +found is valid and mountable, and some filesystems might +be mountable but require special options. Filesystems may +not all belong to a single logical operating system +(use C to look for OSes)." }; + + { defaults with + name = "add_drive"; + style = RErr, [String "filename"], [OBool "readonly"; OString "format"; OString "iface"; OString "name"]; + once_had_no_optargs = true; + fish_alias = ["add"]; config_only = true; + shortdesc = "add an image to examine or modify"; + longdesc = "\ +This function adds a virtual machine disk image C to +libguestfs. The first time you call this function, the disk +appears as C, the second time as C, and +so on. + +You don't necessarily need to be root when using libguestfs. However +you obviously do need sufficient permissions to access the filename +for whatever operations you want to perform (ie. read access if you +just want to read the image or write access if you want to modify the +image). + +This call checks that C exists. + +C may be the special string C<\"/dev/null\">. +See L. + +The optional arguments are: + +=over 4 + +=item C + +If true then the image is treated as read-only. Writes are still +allowed, but they are stored in a temporary snapshot overlay which +is discarded at the end. The disk that you add is not modified. + +=item C + +This forces the image format. If you omit this (or use C +or C) then the format is automatically detected. +Possible formats include C and C. + +Automatic detection of the format opens you up to a potential +security hole when dealing with untrusted raw-format images. +See CVE-2010-3851 and RHBZ#642934. Specifying the format closes +this security hole. + +=item C + +This rarely-used option lets you emulate the behaviour of the +deprecated C call (q.v.) + +=item C + +The name the drive had in the original guest, e.g. /dev/sdb. This is used as a +hint to the guest inspection process if it is available. + +=back + +C can have the special value C, which means +to add a null (zero length) raw format device. You can add C +multiple times." }; + + { defaults with + name = "inspect_get_windows_systemroot"; + style = RString "systemroot", [Device "root"], []; + shortdesc = "get Windows systemroot of inspected operating system"; + longdesc = "\ +This returns the Windows systemroot of the inspected guest. +The systemroot is a directory path such as C. + +This call assumes that the guest is Windows and that the +systemroot could be determined by inspection. If this is not +the case then an error is returned. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_roots"; + style = RStringList "roots", [], []; + shortdesc = "return list of operating systems found by last inspection"; + longdesc = "\ +This function is a convenient way to get the list of root +devices, as returned from a previous call to C, +but without redoing the whole inspection process. + +This returns an empty list if either no root devices were +found or the caller has not called C. + +Please read L for more details." }; + + { defaults with + name = "debug_drives"; + style = RStringList "cmdline", [], []; + in_docs = false; + shortdesc = "debug the drives (internal use only)"; + longdesc = "\ +This returns the internal list of drives. 'debug' commands are +not part of the formal API and can be removed or changed at any time." }; + + { defaults with + name = "add_domain"; + style = RInt "nrdisks", [String "dom"], [OString "libvirturi"; OBool "readonly"; OString "iface"; OBool "live"; OBool "allowuuid"; OString "readonlydisk"]; + fish_alias = ["domain"]; config_only = true; + shortdesc = "add the disk(s) from a named libvirt domain"; + longdesc = "\ +This function adds the disk(s) attached to the named libvirt +domain C. It works by connecting to libvirt, requesting +the domain and domain XML from libvirt, parsing it for disks, +and calling C on each one. + +The number of disks added is returned. This operation is atomic: +if an error is returned, then no disks are added. + +This function does some minimal checks to make sure the libvirt +domain is not running (unless C is true). In a future +version we will try to acquire the libvirt lock on each disk. + +Disks must be accessible locally. This often means that adding disks +from a remote libvirt connection (see L) +will fail unless those disks are accessible via the same device path +locally too. + +The optional C parameter sets the libvirt URI +(see L). If this is not set then +we connect to the default libvirt URI (or one set through an +environment variable, see the libvirt documentation for full +details). + +The optional C flag controls whether this call will try +to connect to a running virtual machine C process if +it sees a suitable EchannelE element in the libvirt +XML definition. The default (if the flag is omitted) is never +to try. See L for more +information. + +If the C flag is true (default is false) then a UUID +I be passed instead of the domain name. The C string is +treated as a UUID first and looked up, and if that lookup fails +then we treat C as a name as usual. + +The optional C parameter controls what we do for +disks which are marked Ereadonly/E in the libvirt XML. +Possible values are: + +=over 4 + +=item readonlydisk = \"error\" + +If C is false: + +The whole call is aborted with an error if any disk with +the Ereadonly/E flag is found. + +If C is true: + +Disks with the Ereadonly/E flag are added read-only. + +=item readonlydisk = \"read\" + +If C is false: + +Disks with the Ereadonly/E flag are added read-only. +Other disks are added read/write. + +If C is true: + +Disks with the Ereadonly/E flag are added read-only. + +=item readonlydisk = \"write\" (default) + +If C is false: + +Disks with the Ereadonly/E flag are added read/write. + +If C is true: + +Disks with the Ereadonly/E flag are added read-only. + +=item readonlydisk = \"ignore\" + +If C is true or false: + +Disks with the Ereadonly/E flag are skipped. + +=back + +The other optional parameters are passed directly through to +C." }; + +(* +This interface is not quite baked yet. -- RWMJ 2010-11-11 + { defaults with + name = "add_libvirt_dom"; + style = RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [Bool "readonly"; String "iface"; Bool "live"; String "readonlydisk"]; + in_fish = false; + shortdesc = "add the disk(s) from a libvirt domain"; + longdesc = "\ +This function adds the disk(s) attached to the libvirt domain C. +It works by requesting the domain XML from libvirt, parsing it for +disks, and calling C on each one. + +In the C API we declare C, but really it has type +C. This is so we don't need Elibvirt.hE. + +The number of disks added is returned. This operation is atomic: +if an error is returned, then no disks are added. + +This function does some minimal checks to make sure the libvirt +domain is not running (unless C is true). In a future +version we will try to acquire the libvirt lock on each disk. + +Disks must be accessible locally. This often means that adding disks +from a remote libvirt connection (see L) +will fail unless those disks are accessible via the same device path +locally too. + +The optional C flag controls whether this call will try +to connect to a running virtual machine C process if +it sees a suitable EchannelE element in the libvirt +XML definition. The default (if the flag is omitted) is never +to try. See L for more +information. + +The optional C parameter controls what we do for +disks which are marked Ereadonly/E in the libvirt XML. +See C for possible values. + +The other optional parameters are passed directly through to +C." }; +*) + + { defaults with + name = "inspect_get_package_format"; + style = RString "packageformat", [Device "root"], []; + shortdesc = "get package format used by the operating system"; + longdesc = "\ +This function and C return +the package format and package management tool used by the +inspected operating system. For example for Fedora these +functions would return C (package format) and +C (package management). + +This returns the string C if we could not determine the +package format I if the operating system does not have +a real packaging system (eg. Windows). + +Possible strings include: +C, C, C, C, C, C. +Future versions of libguestfs may return other strings. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_package_management"; + style = RString "packagemanagement", [Device "root"], []; + shortdesc = "get package management tool used by the operating system"; + longdesc = "\ +C and this function return +the package format and package management tool used by the +inspected operating system. For example for Fedora these +functions would return C (package format) and +C (package management). + +This returns the string C if we could not determine the +package management tool I if the operating system does not have +a real packaging system (eg. Windows). + +Possible strings include: C, C, +C (for all Debian derivatives), +C, C, C, C, C. +Future versions of libguestfs may return other strings. + +Please read L for more details." }; + + { defaults with + name = "inspect_list_applications"; + style = RStructList ("applications", "application"), [Device "root"], []; + shortdesc = "get list of applications installed in the operating system"; + longdesc = "\ +Return the list of applications installed in the operating system. + +I This call works differently from other parts of the +inspection API. You have to call C, then +C, then mount up the disks, +before calling this. Listing applications is a significantly +more difficult operation which requires access to the full +filesystem. Also note that unlike the other +C calls which are just returning +data cached in the libguestfs handle, this call actually reads +parts of the mounted filesystems during the call. + +This returns an empty list if the inspection code was not able +to determine the list of applications. + +The application structure contains the following fields: + +=over 4 + +=item C + +The name of the application. For Red Hat-derived and Debian-derived +Linux guests, this is the package name. + +=item C + +The display name of the application, sometimes localized to the +install language of the guest operating system. + +If unavailable this is returned as an empty string C<\"\">. +Callers needing to display something can use C instead. + +=item C + +For package managers which use epochs, this contains the epoch of +the package (an integer). If unavailable, this is returned as C<0>. + +=item C + +The version string of the application or package. If unavailable +this is returned as an empty string C<\"\">. + +=item C + +The release string of the application or package, for package +managers that use this. If unavailable this is returned as an +empty string C<\"\">. + +=item C + +The installation path of the application (on operating systems +such as Windows which use installation paths). This path is +in the format used by the guest operating system, it is not +a libguestfs path. + +If unavailable this is returned as an empty string C<\"\">. + +=item C + +The install path translated into a libguestfs path. +If unavailable this is returned as an empty string C<\"\">. + +=item C + +The name of the publisher of the application, for package +managers that use this. If unavailable this is returned +as an empty string C<\"\">. + +=item C + +The URL (eg. upstream URL) of the application. +If unavailable this is returned as an empty string C<\"\">. + +=item C + +For packaging systems which support this, the name of the source +package. If unavailable this is returned as an empty string C<\"\">. + +=item C + +A short (usually one line) description of the application or package. +If unavailable this is returned as an empty string C<\"\">. + +=item C + +A longer description of the application or package. +If unavailable this is returned as an empty string C<\"\">. + +=back + +Please read L for more details." }; + + { defaults with + name = "inspect_get_hostname"; + style = RString "hostname", [Device "root"], []; + shortdesc = "get hostname of the operating system"; + longdesc = "\ +This function returns the hostname of the operating system +as found by inspection of the guest's configuration files. + +If the hostname could not be determined, then the +string C is returned. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_format"; + style = RString "format", [Device "root"], []; + shortdesc = "get format of inspected operating system"; + longdesc = "\ +This returns the format of the inspected operating system. You +can use it to detect install images, live CDs and similar. + +Currently defined formats are: + +=over 4 + +=item \"installed\" + +This is an installed operating system. + +=item \"installer\" + +The disk image being inspected is not an installed operating system, +but a I install disk, live CD, or similar. + +=item \"unknown\" + +The format of this disk image is not known. + +=back + +Future versions of libguestfs may return other strings here. +The caller should be prepared to handle any string. + +Please read L for more details." }; + + { defaults with + name = "inspect_is_live"; + style = RBool "live", [Device "root"], []; + shortdesc = "get live flag for install disk"; + longdesc = "\ +If C returns C (this +is an install disk), then this returns true if a live image +was detected on the disk. + +Please read L for more details." }; + + { defaults with + name = "inspect_is_netinst"; + style = RBool "netinst", [Device "root"], []; + shortdesc = "get netinst (network installer) flag for install disk"; + longdesc = "\ +If C returns C (this +is an install disk), then this returns true if the disk is +a network installer, ie. not a self-contained install CD but +one which is likely to require network access to complete +the install. + +Please read L for more details." }; + + { defaults with + name = "inspect_is_multipart"; + style = RBool "multipart", [Device "root"], []; + shortdesc = "get multipart flag for install disk"; + longdesc = "\ +If C returns C (this +is an install disk), then this returns true if the disk is +part of a set. + +Please read L for more details." }; + + { defaults with + name = "set_attach_method"; + style = RErr, [String "attachmethod"], []; + fish_alias = ["attach-method"]; config_only = true; + shortdesc = "set the attach method"; + longdesc = "\ +Set the method that libguestfs uses to connect to the back end +guestfsd daemon. + +Possible attach methods are: + +=over 4 + +=item C + +Launch an appliance and connect to it. + +This is the ordinary method and normally the default, but see the +note below. + +=item C + +=item C> + +Use libvirt to launch the appliance. The optional I is the +libvirt connection URI to use (see L). + +=item C> + +Connect to the Unix domain socket I. + +This method lets you connect to an existing daemon or (using +virtio-serial) to a live guest. For more information, see +L. + +=back + +C is usually the default attach method. However since +libguestfs E 1.19.24 it has been possible to change the default +in two ways: + +=over 4 + +=item Setting LIBGUESTFS_ATTACH_METHOD + +Users can set this environment variable to change the default. + +=item Configuring the default attach method when building libguestfs + +Distributors can override the default when libguestfs is built +(using C<./configure --with-default-attach-method=...>). + +To find out if libguestfs was compiled with a different default +attach method, do: + + guestfish get-attach-method + +=back" }; + + { defaults with + name = "get_attach_method"; + style = RString "attachmethod", [], []; + tests = [ + InitNone, Always, TestRun ( + [["get_attach_method"]]) + ]; + shortdesc = "get the attach method"; + longdesc = "\ +Return the current attach method. See C." }; + + { defaults with + name = "inspect_get_product_variant"; + style = RString "variant", [Device "root"], []; + shortdesc = "get product variant of inspected operating system"; + longdesc = "\ +This returns the product variant of the inspected operating +system. + +For Windows guests, this returns the contents of the Registry key +C +C which is usually a string such as +C or C (other values are possible). This +can be used to distinguish consumer and enterprise versions +of Windows that have the same version number (for example, +Windows 7 and Windows 2008 Server are both version 6.1, +but the former is C and the latter is C). + +For enterprise Linux guests, in future we intend this to return +the product variant such as C, C and so on. But +this is not implemented at present. + +If the product variant could not be determined, then the +string C is returned. + +Please read L for more details. +See also C, +C." }; + + { defaults with + name = "inspect_get_windows_current_control_set"; + style = RString "controlset", [Device "root"], []; + shortdesc = "get Windows CurrentControlSet of inspected operating system"; + longdesc = "\ +This returns the Windows CurrentControlSet of the inspected guest. +The CurrentControlSet is a registry key name such as C. + +This call assumes that the guest is Windows and that the +Registry could be examined by inspection. If this is not +the case then an error is returned. + +Please read L for more details." }; + + { defaults with + name = "inspect_get_drive_mappings"; + style = RHashtable "drives", [Device "root"], []; + shortdesc = "get drive letter mappings"; + longdesc = "\ +This call is useful for Windows which uses a primitive system +of assigning drive letters (like \"C:\") to partitions. +This inspection API examines the Windows Registry to find out +how disks/partitions are mapped to drive letters, and returns +a hash table as in the example below: + + C => /dev/vda2 + E => /dev/vdb1 + F => /dev/vdc1 + +Note that keys are drive letters. For Windows, the key is +case insensitive and just contains the drive letter, without +the customary colon separator character. + +In future we may support other operating systems that also used drive +letters, but the keys for those might not be case insensitive +and might be longer than 1 character. For example in OS-9, +hard drives were named C, C

etc. + +For Windows guests, currently only hard drive mappings are +returned. Removable disks (eg. DVD-ROMs) are ignored. + +For guests that do not use drive mappings, or if the drive mappings +could not be determined, this returns an empty hash table. + +Please read L for more details. +See also C, +C." }; + + { defaults with + name = "inspect_get_icon"; + style = RBufferOut "icon", [Device "root"], [OBool "favicon"; OBool "highquality"]; + shortdesc = "get the icon corresponding to this operating system"; + longdesc = "\ +This function returns an icon corresponding to the inspected +operating system. The icon is returned as a buffer containing a +PNG image (re-encoded to PNG if necessary). + +If it was not possible to get an icon this function returns a +zero-length (non-NULL) buffer. I. + +Libguestfs will start by looking for a file called +C or C +and if it has the correct format, the contents of this file will +be returned. You can disable favicons by passing the +optional C boolean as false (default is true). + +If finding the favicon fails, then we look in other places in the +guest for a suitable icon. + +If the optional C boolean is true then +only high quality icons are returned, which means only icons of +high resolution with an alpha channel. The default (false) is +to return any icon we can, even if it is of substandard quality. + +Notes: + +=over 4 + +=item * + +Unlike most other inspection API calls, the guest's disks must be +mounted up before you call this, since it needs to read information +from the guest filesystem during the call. + +=item * + +B The icon data comes from the untrusted guest, +and should be treated with caution. PNG files have been +known to contain exploits. Ensure that libpng (or other relevant +libraries) are fully up to date before trying to process or +display the icon. + +=item * + +The PNG image returned can be any size. It might not be square. +Libguestfs tries to return the largest, highest quality +icon available. The application must scale the icon to the +required size. + +=item * + +Extracting icons from Windows guests requires the external +C program from the C package, and +several programs (C, C, C) +from the C package. These must be installed separately. + +=item * + +Operating system icons are usually trademarks. Seek legal +advice before using trademarks in applications. + +=back" }; + + { defaults with + name = "set_pgroup"; + style = RErr, [Bool "pgroup"], []; + fish_alias = ["pgroup"]; config_only = true; + shortdesc = "set process group flag"; + longdesc = "\ +If C is true, child processes are placed into +their own process group. + +The practical upshot of this is that signals like C (from +users pressing C<^C>) won't be received by the child process. + +The default for this flag is false, because usually you want +C<^C> to kill the subprocess. Guestfish sets this flag to +true when used interactively, so that C<^C> can cancel +long-running commands gracefully (see C)." }; + + { defaults with + name = "get_pgroup"; + style = RBool "pgroup", [], []; + shortdesc = "get process group flag"; + longdesc = "\ +This returns the process group flag." }; + + { defaults with + name = "set_smp"; + style = RErr, [Int "smp"], []; + fish_alias = ["smp"]; config_only = true; + shortdesc = "set number of virtual CPUs in appliance"; + longdesc = "\ +Change the number of virtual CPUs assigned to the appliance. The +default is C<1>. Increasing this may improve performance, though +often it has no effect. + +This function must be called before C." }; + + { defaults with + name = "get_smp"; + style = RInt "smp", [], []; + shortdesc = "get number of virtual CPUs in appliance"; + longdesc = "\ +This returns the number of virtual CPUs assigned to the appliance." }; + + { defaults with + name = "mount_local"; + style = RErr, [String "localmountpoint"], [OBool "readonly"; OString "options"; OInt "cachetimeout"; OBool "debugcalls"]; + shortdesc = "mount on the local filesystem"; + longdesc = "\ +This call exports the libguestfs-accessible filesystem to +a local mountpoint (directory) called C. +Ordinary reads and writes to files and directories under +C are redirected through libguestfs. + +If the optional C flag is set to true, then +writes to the filesystem return error C. + +C is a comma-separated list of mount options. +See L for some useful options. + +C sets the timeout (in seconds) for cached directory +entries. The default is 60 seconds. See L +for further information. + +If C is set to true, then additional debugging +information is generated for every FUSE call. + +When C returns, the filesystem is ready, +but is not processing requests (access to it will block). You +have to call C to run the main loop. + +See L for full documentation." }; + + { defaults with + name = "mount_local_run"; + style = RErr, [], []; + cancellable = true (* in a future version *); + shortdesc = "run main loop of mount on the local filesystem"; + longdesc = "\ +Run the main loop which translates kernel calls to libguestfs +calls. + +This should only be called after C +returns successfully. The call will not return until the +filesystem is unmounted. + +B you must I make concurrent libguestfs calls +on the same handle from another thread, +with the exception of C. + +You may call this from a different thread than the one which +called C, subject to the usual rules +for threads and libguestfs (see +L). + +See L for full documentation." }; + + { defaults with + name = "umount_local"; + style = RErr, [], [OBool "retry"]; + tests = [] (* tests in fuse subdirectory *); + shortdesc = "unmount a locally mounted filesystem"; + longdesc = "\ +If libguestfs is exporting the filesystem on a local +mountpoint, then this unmounts it. + +See L for full documentation." }; + + { defaults with + name = "max_disks"; + style = RInt "disks", [], []; + shortdesc = "maximum number of disks that may be added"; + longdesc = "\ +Return the maximum number of disks that may be added to a +handle (eg. by C and similar calls). + +This function was added in libguestfs 1.19.7. In previous +versions of libguestfs the limit was 25. + +See L for additional +information on this topic." }; + + { defaults with + name = "canonical_device_name"; + style = RString "canonical", [String "device"], []; + shortdesc = "return canonical device name"; + longdesc = "\ +This utility function is useful when displaying device names to +the user. It takes a number of irregular device names and +returns them in a consistent format: + +=over 4 + +=item C + +=item C + +These are returned as C. Note this works for device +names and partition names. This is approximately the reverse of +the algorithm described in L. + +=item C + +=item C + +Converted to C form using C. + +=back + +Other strings are returned unmodified." }; + + { defaults with + name = "shutdown"; + style = RErr, [], []; + shortdesc = "shutdown the qemu subprocess"; + longdesc = "\ +This is the opposite of C. It performs an orderly +shutdown of the backend process(es). If the autosync flag is set +(which is the default) then the disk image is synchronized. + +If the subprocess exits with an error then this function will return +an error, which should I be ignored (it may indicate that the +disk image could not be written out properly). + +It is safe to call this multiple times. Extra calls are ignored. + +This call does I close or free up the handle. You still +need to call C afterwards. + +C will call this if you don't do it explicitly, +but note that any errors are ignored in that case." }; + + { defaults with + name = "cat"; + style = RString "content", [Pathname "path"], []; + tests = [ + InitISOFS, Always, TestOutput ( + [["cat"; "/known-2"]], "abcdef\n") + ]; + shortdesc = "list the contents of a file"; + longdesc = "\ +Return the contents of the file named C. + +Because, in C, this function returns a C, there is no +way to differentiate between a C<\\0> character in a file and +end of string. To handle binary files, use the C +or C functions." }; + + { defaults with + name = "find"; + style = RStringList "names", [Pathname "directory"], []; + tests = [ + InitBasicFS, Always, TestOutputList ( + [["find"; "/"]], ["lost+found"]); + InitBasicFS, Always, TestOutputList ( + [["touch"; "/a"]; + ["mkdir"; "/b"]; + ["touch"; "/b/c"]; + ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]); + InitScratchFS, Always, TestOutputList ( + [["mkdir_p"; "/find/b/c"]; + ["touch"; "/find/b/c/d"]; + ["find"; "/find/b/"]], ["c"; "c/d"]) + ]; + shortdesc = "find all files and directories"; + longdesc = "\ +This command lists out all files and directories, recursively, +starting at C. It is essentially equivalent to +running the shell command C but some +post-processing happens on the output, described below. + +This returns a list of strings I. Thus +if the directory structure was: + + /tmp/a + /tmp/b + /tmp/c/d + +then the returned list from C C would be +4 elements: + + a + b + c + c/d + +If C is not a directory, then this command returns +an error. + +The returned list is sorted." }; + + { defaults with + name = "read_file"; + style = RBufferOut "content", [Pathname "path"], []; + tests = [ + InitISOFS, Always, TestOutputBuffer ( + [["read_file"; "/known-4"]], "abc\ndef\nghi") + ]; + shortdesc = "read a file"; + longdesc = "\ +This calls returns the contents of the file C as a +buffer. + +Unlike C, this function can correctly +handle files that contain embedded ASCII NUL characters." }; + + { defaults with + name = "read_lines"; + style = RStringList "lines", [Pathname "path"], []; + tests = [ + InitISOFS, Always, TestOutputList ( + [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]); + InitISOFS, Always, TestOutputList ( + [["read_lines"; "/empty"]], []); + InitScratchFS, Always, TestOutputList ( + [["write"; "/read_lines1"; "\n"]; + ["read_lines"; "/read_lines1"]], [""]); + InitScratchFS, Always, TestOutputList ( + [["write"; "/read_lines2"; "\r\n"]; + ["read_lines"; "/read_lines2"]], [""]); + InitScratchFS, Always, TestOutputList ( + [["write"; "/read_lines3"; "\n\r\n"]; + ["read_lines"; "/read_lines3"]], [""; ""]); + InitScratchFS, Always, TestOutputList ( + [["write"; "/read_lines4"; "a"]; + ["read_lines"; "/read_lines4"]], ["a"]); + InitScratchFS, Always, TestOutputList ( + [["write"; "/read_lines5"; "a\nb"]; + ["read_lines"; "/read_lines5"]], ["a"; "b"]); + InitScratchFS, Always, TestOutputList ( + [["write"; "/read_lines6"; "a\nb\n"]; + ["read_lines"; "/read_lines6"]], ["a"; "b"]); + InitScratchFS, Always, TestOutputList ( + [["write"; "/read_lines7"; "a\nb\r\n"]; + ["read_lines"; "/read_lines7"]], ["a"; "b"]); + InitScratchFS, Always, TestOutputList ( + [["write"; "/read_lines8"; "a\nb\r\n\n"]; + ["read_lines"; "/read_lines8"]], ["a"; "b"; ""]); + ]; + shortdesc = "read file as lines"; + longdesc = "\ +Return the contents of the file named C. + +The file contents are returned as a list of lines. Trailing +C and C character sequences are I returned. + +Note that this function cannot correctly handle binary files +(specifically, files containing C<\\0> character which is treated +as end of string). For those you need to use the C +function and split the buffer into lines yourself." }; + + { defaults with + name = "write"; + style = RErr, [Pathname "path"; BufferIn "content"], []; + tests = [ + InitScratchFS, Always, TestOutput ( + [["write"; "/write"; "new file contents"]; + ["cat"; "/write"]], "new file contents"); + InitScratchFS, Always, TestOutput ( + [["write"; "/write2"; "\nnew file contents\n"]; + ["cat"; "/write2"]], "\nnew file contents\n"); + InitScratchFS, Always, TestOutput ( + [["write"; "/write3"; "\n\n"]; + ["cat"; "/write3"]], "\n\n"); + InitScratchFS, Always, TestOutput ( + [["write"; "/write4"; ""]; + ["cat"; "/write4"]], ""); + InitScratchFS, Always, TestOutput ( + [["write"; "/write5"; "\n\n\n"]; + ["cat"; "/write5"]], "\n\n\n"); + InitScratchFS, Always, TestOutput ( + [["write"; "/write6"; "\n"]; + ["cat"; "/write6"]], "\n") + ]; + shortdesc = "create a new file"; + longdesc = "\ +This call creates a file called C. The content of the +file is the string C (which can contain any 8 bit data). + +See also C." }; + + { defaults with + name = "write_append"; + style = RErr, [Pathname "path"; BufferIn "content"], []; + tests = [ + InitScratchFS, Always, TestOutput ( + [["write"; "/write_append"; "line1\n"]; + ["write_append"; "/write_append"; "line2\n"]; + ["write_append"; "/write_append"; "line3a"]; + ["write_append"; "/write_append"; "line3b\n"]; + ["cat"; "/write_append"]], "line1\nline2\nline3aline3b\n") + ]; + shortdesc = "append content to end of file"; + longdesc = "\ +This call appends C to the end of file C. If +C does not exist, then a new file is created. + +See also C." }; + + { defaults with + name = "lstatlist"; + style = RStructList ("statbufs", "stat"), [Pathname "path"; StringList "names"], []; + shortdesc = "lstat on multiple files"; + longdesc = "\ +This call allows you to perform the C operation +on multiple files, where all files are in the directory C. +C is the list of files from this directory. + +On return you get a list of stat structs, with a one-to-one +correspondence to the C list. If any name did not exist +or could not be lstat'd, then the C field of that structure +is set to C<-1>. + +This call is intended for programs that want to efficiently +list a directory contents without making many round-trips. +See also C for a similarly efficient call +for getting extended attributes." }; + + { defaults with + name = "lxattrlist"; + style = RStructList ("xattrs", "xattr"), [Pathname "path"; StringList "names"], []; + optional = Some "linuxxattrs"; + shortdesc = "lgetxattr on multiple files"; + longdesc = "\ +This call allows you to get the extended attributes +of multiple files, where all files are in the directory C. +C is the list of files from this directory. + +On return you get a flat list of xattr structs which must be +interpreted sequentially. The first xattr struct always has a zero-length +C. C in this struct is zero-length +to indicate there was an error doing C for this +file, I is a C string which is a decimal number +(the number of following attributes for this file, which could +be C<\"0\">). Then after the first xattr struct are the +zero or more attributes for the first named file. +This repeats for the second and subsequent files. + +This call is intended for programs that want to efficiently +list a directory contents without making many round-trips. +See also C for a similarly efficient call +for getting standard stats." }; + + { defaults with + name = "readlinklist"; + style = RStringList "links", [Pathname "path"; StringList "names"], []; + shortdesc = "readlink on multiple files"; + longdesc = "\ +This call allows you to do a C operation +on multiple files, where all files are in the directory C. +C is the list of files from this directory. + +On return you get a list of strings, with a one-to-one +correspondence to the C list. Each string is the +value of the symbolic link. + +If the C operation fails on any name, then +the corresponding result string is the empty string C<\"\">. +However the whole operation is completed even if there +were C errors, and so you can call this +function with names where you don't know if they are +symbolic links already (albeit slightly less efficient). + +This call is intended for programs that want to efficiently +list a directory contents without making many round-trips." }; + + { defaults with + name = "ls"; + style = RStringList "listing", [Pathname "directory"], []; + tests = [ + InitScratchFS, Always, TestOutputList ( + [["mkdir"; "/ls"]; + ["touch"; "/ls/new"]; + ["touch"; "/ls/newer"]; + ["touch"; "/ls/newest"]; + ["ls"; "/ls"]], ["new"; "newer"; "newest"]) + ]; + shortdesc = "list the files in a directory"; + longdesc = "\ +List the files in C (relative to the root directory, +there is no cwd). The '.' and '..' entries are not returned, but +hidden files are shown." }; + + { defaults with + name = "hivex_value_utf8"; + style = RString "databuf", [Int64 "valueh"], []; + optional = Some "hivex"; + shortdesc = "return the data field from the (key, datatype, data) tuple"; + longdesc = "\ +This calls C (which returns the +data field from a hivex value tuple). It then assumes that +the field is a UTF-16LE string and converts the result to +UTF-8 (or if this is not possible, it returns an error). + +This is useful for reading strings out of the Windows registry. +However it is not foolproof because the registry is not +strongly-typed and fields can contain arbitrary or unexpected +data." }; + +] + +(* daemon_functions are any functions which cause some action + * to take place in the daemon. + *) + +let daemon_functions = [ + { defaults with + name = "mount"; + style = RErr, [Device "device"; String "mountpoint"], []; + proc_nr = Some 1; + tests = [ + InitEmpty, Always, TestOutput ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents") + ]; + shortdesc = "mount a guest disk at a position in the filesystem"; + longdesc = "\ +Mount a guest disk at a position in the filesystem. Block devices +are named C, C and so on, as they were added to +the guest. If those block devices contain partitions, they will have +the usual names (eg. C). Also LVM C-style +names can be used. + +The rules are the same as for L: A filesystem must +first be mounted on C before others can be mounted. Other +filesystems can only be mounted on directories which already +exist. + +The mounted filesystem is writable, if we have sufficient permissions +on the underlying device. + +Before libguestfs 1.13.16, this call implicitly added the options +C and C. The C option greatly slowed +writes and caused many problems for users. If your program +might need to work with older versions of libguestfs, use +C instead (using an empty string for the +first parameter if you don't want any options)." }; + + { defaults with + name = "sync"; + style = RErr, [], []; + proc_nr = Some 2; + tests = [ + InitEmpty, Always, TestRun [["sync"]] + ]; + shortdesc = "sync disks, writes are flushed through to the disk image"; + longdesc = "\ +This syncs the disk, so that any writes are flushed through to the +underlying disk image. + +You should always call this if you have modified a disk image, before +closing the handle." }; + + { defaults with + name = "touch"; + style = RErr, [Pathname "path"], []; + proc_nr = Some 3; + tests = [ + InitScratchFS, Always, TestOutputTrue ( + [["touch"; "/touch"]; + ["exists"; "/touch"]]) + ]; + shortdesc = "update file timestamps or create a new file"; + longdesc = "\ +Touch acts like the L command. It can be used to +update the timestamps on a file, or, if the file does not exist, +to create a new zero-length file. + +This command only works on regular files, and will fail on other +file types such as directories, symbolic links, block special etc." }; + + { defaults with + name = "ll"; + style = RString "listing", [Pathname "directory"], []; + proc_nr = Some 5; + tests = []; (* XXX Tricky to test because it depends on the exact format + * of the 'ls -l' command, which changes between F10 and F11. + *) + shortdesc = "list the files in a directory (long format)"; + longdesc = "\ +List the files in C (relative to the root directory, +there is no cwd) in the format of 'ls -la'. + +This command is mostly useful for interactive sessions. It +is I intended that you try to parse the output string." }; + + { defaults with + name = "list_devices"; + style = RStringList "devices", [], []; + proc_nr = Some 7; + tests = [ + InitEmpty, Always, TestOutputListOfDevices ( + [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"]) + ]; + shortdesc = "list the block devices"; + longdesc = "\ +List all the block devices. + +The full block device names are returned, eg. C. + +See also C." }; + + { defaults with + name = "list_partitions"; + style = RStringList "partitions", [], []; + proc_nr = Some 8; + tests = [ + InitBasicFS, Always, TestOutputListOfDevices ( + [["list_partitions"]], ["/dev/sda1"; "/dev/sdb1"]); + InitEmpty, Always, TestOutputListOfDevices ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "409599"]; + ["part_add"; "/dev/sda"; "p"; "409600"; "-64"]; + ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"; "/dev/sdb1"]) + ]; + shortdesc = "list the partitions"; + longdesc = "\ +List all the partitions detected on all block devices. + +The full partition device names are returned, eg. C + +This does not return logical volumes. For that you will need to +call C. + +See also C." }; + + { defaults with + name = "pvs"; + style = RStringList "physvols", [], []; + proc_nr = Some 9; + optional = Some "lvm2"; + tests = [ + InitBasicFSonLVM, Always, TestOutputListOfDevices ( + [["pvs"]], ["/dev/sda1"]); + InitEmpty, Always, TestOutputListOfDevices ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "409599"]; + ["part_add"; "/dev/sda"; "p"; "409600"; "-64"]; + ["pvcreate"; "/dev/sda1"]; + ["pvcreate"; "/dev/sda2"]; + ["pvcreate"; "/dev/sda3"]; + ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"]) + ]; + shortdesc = "list the LVM physical volumes (PVs)"; + longdesc = "\ +List all the physical volumes detected. This is the equivalent +of the L command. + +This returns a list of just the device names that contain +PVs (eg. C). + +See also C." }; + + { defaults with + name = "vgs"; + style = RStringList "volgroups", [], []; + proc_nr = Some 10; + optional = Some "lvm2"; + tests = [ + InitBasicFSonLVM, Always, TestOutputList ( + [["vgs"]], ["VG"]); + InitEmpty, Always, TestOutputList ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "409599"]; + ["part_add"; "/dev/sda"; "p"; "409600"; "-64"]; + ["pvcreate"; "/dev/sda1"]; + ["pvcreate"; "/dev/sda2"]; + ["pvcreate"; "/dev/sda3"]; + ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"]; + ["vgcreate"; "VG2"; "/dev/sda3"]; + ["vgs"]], ["VG1"; "VG2"]) + ]; + shortdesc = "list the LVM volume groups (VGs)"; + longdesc = "\ +List all the volumes groups detected. This is the equivalent +of the L command. + +This returns a list of just the volume group names that were +detected (eg. C). + +See also C." }; + + { defaults with + name = "lvs"; + style = RStringList "logvols", [], []; + proc_nr = Some 11; + optional = Some "lvm2"; + tests = [ + InitBasicFSonLVM, Always, TestOutputList ( + [["lvs"]], ["/dev/VG/LV"]); + InitEmpty, Always, TestOutputList ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "409599"]; + ["part_add"; "/dev/sda"; "p"; "409600"; "-64"]; + ["pvcreate"; "/dev/sda1"]; + ["pvcreate"; "/dev/sda2"]; + ["pvcreate"; "/dev/sda3"]; + ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"]; + ["vgcreate"; "VG2"; "/dev/sda3"]; + ["lvcreate"; "LV1"; "VG1"; "50"]; + ["lvcreate"; "LV2"; "VG1"; "50"]; + ["lvcreate"; "LV3"; "VG2"; "50"]; + ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"]) + ]; + shortdesc = "list the LVM logical volumes (LVs)"; + longdesc = "\ +List all the logical volumes detected. This is the equivalent +of the L command. + +This returns a list of the logical volume device names +(eg. C). + +See also C, C." }; + + { defaults with + name = "pvs_full"; + style = RStructList ("physvols", "lvm_pv"), [], []; + proc_nr = Some 12; + optional = Some "lvm2"; + shortdesc = "list the LVM physical volumes (PVs)"; + longdesc = "\ +List all the physical volumes detected. This is the equivalent +of the L command. The \"full\" version includes all fields." }; + + { defaults with + name = "vgs_full"; + style = RStructList ("volgroups", "lvm_vg"), [], []; + proc_nr = Some 13; + optional = Some "lvm2"; + shortdesc = "list the LVM volume groups (VGs)"; + longdesc = "\ +List all the volumes groups detected. This is the equivalent +of the L command. The \"full\" version includes all fields." }; + + { defaults with + name = "lvs_full"; + style = RStructList ("logvols", "lvm_lv"), [], []; + proc_nr = Some 14; + optional = Some "lvm2"; + shortdesc = "list the LVM logical volumes (LVs)"; + longdesc = "\ +List all the logical volumes detected. This is the equivalent +of the L command. The \"full\" version includes all fields." }; + + { defaults with + name = "aug_init"; + style = RErr, [Pathname "root"; Int "flags"], []; + proc_nr = Some 16; + optional = Some "augeas"; + shortdesc = "create a new Augeas handle"; + longdesc = "\ +Create a new Augeas handle for editing configuration files. +If there was any previous Augeas handle associated with this +guestfs session, then it is closed. + +You must call this before using any other C +commands. + +C is the filesystem root. C must not be NULL, +use C instead. + +The flags are the same as the flags defined in +Eaugeas.hE, the logical I of the following +integers: + +=over 4 + +=item C = 1 + +Keep the original file with a C<.augsave> extension. + +=item C = 2 + +Save changes into a file with extension C<.augnew>, and +do not overwrite original. Overrides C. + +=item C = 4 + +Typecheck lenses. + +This option is only useful when debugging Augeas lenses. Use +of this option may require additional memory for the libguestfs +appliance. You may need to set the C +environment variable or call C. + +=item C = 8 + +Do not use standard load path for modules. + +=item C = 16 + +Make save a no-op, just record what would have been changed. + +=item C = 32 + +Do not load the tree in C. + +=back + +To close the handle, you can call C. + +To find out more about Augeas, see L." }; + + { defaults with + name = "aug_close"; + style = RErr, [], []; + proc_nr = Some 26; + optional = Some "augeas"; + shortdesc = "close the current Augeas handle"; + longdesc = "\ +Close the current Augeas handle and free up any resources +used by it. After calling this, you have to call +C again before you can use any other +Augeas functions." }; + + { defaults with + name = "aug_defvar"; + style = RInt "nrnodes", [String "name"; OptString "expr"], []; + proc_nr = Some 17; + optional = Some "augeas"; + shortdesc = "define an Augeas variable"; + longdesc = "\ +Defines an Augeas variable C whose value is the result +of evaluating C. If C is NULL, then C is +undefined. + +On success this returns the number of nodes in C, or +C<0> if C evaluates to something which is not a nodeset." }; + + { defaults with + name = "aug_defnode"; + style = RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"], []; + proc_nr = Some 18; + optional = Some "augeas"; + shortdesc = "define an Augeas node"; + longdesc = "\ +Defines a variable C whose value is the result of +evaluating C. + +If C evaluates to an empty nodeset, a node is created, +equivalent to calling C C, C. +C will be the nodeset containing that single node. + +On success this returns a pair containing the +number of nodes in the nodeset, and a boolean flag +if a node was created." }; + + { defaults with + name = "aug_get"; + style = RString "val", [String "augpath"], []; + proc_nr = Some 19; + optional = Some "augeas"; + shortdesc = "look up the value of an Augeas path"; + longdesc = "\ +Look up the value associated with C. If C +matches exactly one node, the C is returned." }; + + { defaults with + name = "aug_set"; + style = RErr, [String "augpath"; String "val"], []; + proc_nr = Some 20; + optional = Some "augeas"; + shortdesc = "set Augeas path to value"; + longdesc = "\ +Set the value associated with C to C. + +In the Augeas API, it is possible to clear a node by setting +the value to NULL. Due to an oversight in the libguestfs API +you cannot do that with this call. Instead you must use the +C call." }; + + { defaults with + name = "aug_insert"; + style = RErr, [String "augpath"; String "label"; Bool "before"], []; + proc_nr = Some 21; + optional = Some "augeas"; + shortdesc = "insert a sibling Augeas node"; + longdesc = "\ +Create a new sibling C