From 97773d2bbee8e28830fd689deef9e9f63ce0c18e Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Sat, 18 Feb 2017 10:32:33 +0000 Subject: [PATCH] generator: Group and move APIs from actions.ml into actions_*.ml. Group the APIs logically and move them into new modules: Actions_core: Core APIs and anything that doesn't fit into another group, eg. launch. (With some more effort this could be split further.) Actions_augeas: Augeas APIs, eg. aug-init. Actions_debug: Debug APIs. Actions_hivex: Hivex APIs, eg. hivex-open. Actions_inspection: Inspection APIs, eg. inspect-get-type. Actions_properties: Handle properties, eg. set-hv, get-hv. Actions_tsk: SleuthKit APIs, eg. filesystem-walk. *_deprecated: All of the above modules have deprecated variants, where we place the deprecated actions. --- docs/guestfs-hacking.pod | 6 +- generator/Makefile.am | 30 + generator/README | 4 +- generator/actions.ml | 13150 +----------------- generator/actions_augeas.ml | 278 + generator/actions_augeas.mli | 21 + generator/actions_core.ml | 10067 ++++++++++++++ generator/actions_core.mli | 22 + generator/actions_core_deprecated.ml | 793 ++ generator/actions_core_deprecated.mli | 22 + generator/actions_debug.ml | 69 + generator/actions_debug.mli | 22 + generator/actions_hivex.ml | 254 + generator/actions_hivex.mli | 22 + generator/actions_inspection.ml | 810 ++ generator/actions_inspection.mli | 21 + generator/actions_inspection_deprecated.ml | 124 + generator/actions_inspection_deprecated.mli | 21 + generator/actions_properties.ml | 642 + generator/actions_properties.mli | 21 + generator/actions_properties_deprecated.ml | 131 + generator/actions_properties_deprecated.mli | 21 + generator/actions_tsk.ml | 246 + generator/actions_tsk.mli | 22 + 24 files changed, 13681 insertions(+), 13138 deletions(-) create mode 100644 generator/actions_augeas.ml create mode 100644 generator/actions_augeas.mli create mode 100644 generator/actions_core.ml create mode 100644 generator/actions_core.mli create mode 100644 generator/actions_core_deprecated.ml create mode 100644 generator/actions_core_deprecated.mli create mode 100644 generator/actions_debug.ml create mode 100644 generator/actions_debug.mli create mode 100644 generator/actions_hivex.ml create mode 100644 generator/actions_hivex.mli create mode 100644 generator/actions_inspection.ml create mode 100644 generator/actions_inspection.mli create mode 100644 generator/actions_inspection_deprecated.ml create mode 100644 generator/actions_inspection_deprecated.mli create mode 100644 generator/actions_properties.ml create mode 100644 generator/actions_properties.mli create mode 100644 generator/actions_properties_deprecated.ml create mode 100644 generator/actions_properties_deprecated.mli create mode 100644 generator/actions_tsk.ml create mode 100644 generator/actions_tsk.mli diff --git a/docs/guestfs-hacking.pod b/docs/guestfs-hacking.pod index 8c643ca05..43b69e664 100644 --- a/docs/guestfs-hacking.pod +++ b/docs/guestfs-hacking.pod @@ -349,7 +349,7 @@ To add a new API action there are two changes: =item 1. You need to add a description of the call (name, parameters, return -type, tests, documentation) to F. +type, tests, documentation) to F. There are two sorts of API action, depending on whether the call goes through to the daemon in the appliance, or is serviced entirely by the @@ -395,12 +395,12 @@ the OCaml description. You can supply zero or as many tests as you want per API call. The tests can either be added as part of the API description -(F), or in some rarer cases you may want to drop +(F), or in some rarer cases you may want to drop a script into C. Note that adding a script to C is slower, so if possible use the first method. The following describes the test environment used when you add an API -test in F. +test in F. The test environment has 4 block devices: diff --git a/generator/Makefile.am b/generator/Makefile.am index 03f01c032..c281789a8 100644 --- a/generator/Makefile.am +++ b/generator/Makefile.am @@ -21,8 +21,28 @@ include $(top_srcdir)/subdir-rules.mk sources = \ actions.ml \ actions.mli \ + actions_augeas.ml \ + actions_augeas.mli \ + actions_core.ml \ + actions_core.mli \ + actions_core_deprecated.ml \ + actions_core_deprecated.mli \ + actions_debug.ml \ + actions_debug.mli \ + actions_hivex.ml \ + actions_hivex.mli \ + actions_inspection.ml \ + actions_inspection.mli \ + actions_inspection_deprecated.ml \ + actions_inspection_deprecated.mli \ actions_internal_tests.ml \ actions_internal_tests.mli \ + actions_properties.ml \ + actions_properties.mli \ + actions_properties_deprecated.ml \ + actions_properties_deprecated.mli \ + actions_tsk.ml \ + actions_tsk.mli \ bindtests.ml \ bindtests.mli \ c.ml \ @@ -94,7 +114,17 @@ objects = \ common_utils.cmo \ types.cmo \ utils.cmo \ + actions_augeas.cmo \ + actions_core.cmo \ + actions_core_deprecated.cmo \ + actions_debug.cmo \ + actions_hivex.cmo \ + actions_inspection.cmo \ + actions_inspection_deprecated.cmo \ actions_internal_tests.cmo \ + actions_properties.cmo \ + actions_properties_deprecated.cmo \ + actions_tsk.cmo \ actions.cmo \ structs.cmo \ optgroups.cmo \ diff --git a/generator/README b/generator/README index 6ae29bd55..879a68c87 100644 --- a/generator/README +++ b/generator/README @@ -2,7 +2,7 @@ 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, -'actions.ml' to describe the interface, and daemon/.c to +'actions_*.ml' to describe the interface, and daemon/.c to write the implementation. After editing these files, build it (make -C generator) to regenerate @@ -27,7 +27,7 @@ everything is exported. Some notable files in this directory: - actions.ml The libguestfs API. + actions_*.ml The libguestfs API. structs.ml Structures returned by the API. c.ml Generate C API. .ml Generate bindings for . diff --git a/generator/actions.ml b/generator/actions.ml index 2c4e3d563..1fa3b02de 100644 --- a/generator/actions.ml +++ b/generator/actions.ml @@ -29,13144 +29,28 @@ open Utils let non_daemon_functions = Actions_internal_tests.test_functions @ - Actions_internal_tests.test_support_functions @ [ - { defaults with - name = "launch"; added = (0, 0, 3); - style = RErr, [], []; - fish_alias = ["run"]; progress = true; config_only = true; - shortdesc = "launch the backend"; - longdesc = "\ -You should call this after configuring the handle -(eg. adding drives) but before performing any actions. - -Do not call C twice on the same handle. Although -it will not give an error (for historical reasons), the precise -behaviour when you do this is not well defined. Handles are -very cheap to create, so create a new one for each launch." }; - - { defaults with - name = "wait_ready"; added = (0, 0, 3); - style = RErr, [], []; - visibility = VStateTest; - deprecated_by = Some "launch"; - blocking = false; - shortdesc = "wait until the hypervisor 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"; added = (0, 0, 3); - style = RErr, [], []; - deprecated_by = Some "shutdown"; - shortdesc = "kill the hypervisor"; - longdesc = "\ -This kills the hypervisor. - -Do not call this. See: C instead." }; - - { defaults with - name = "add_cdrom"; added = (0, 0, 3); - style = RErr, [String "filename"], []; - deprecated_by = Some "add_drive_ro"; config_only = true; - blocking = false; - shortdesc = "add a CD-ROM disk image to examine"; - longdesc = "\ -This function adds a virtual CD-ROM disk image to the guest. - -The image is added as read-only drive, so this function is equivalent -of C." }; - - { defaults with - name = "add_drive_ro"; added = (1, 0, 38); - style = RErr, [String "filename"], []; - fish_alias = ["add-ro"]; config_only = true; - blocking = false; - 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"; added = (0, 0, 3); - style = RErr, [String "hvparam"; OptString "hvvalue"], []; - config_only = true; - blocking = false; - shortdesc = "add hypervisor parameters"; - longdesc = "\ -This can be used to add arbitrary hypervisor 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"; added = (1, 0, 6); - style = RErr, [OptString "hv"], []; - fish_alias = ["qemu"]; config_only = true; - blocking = false; - deprecated_by = Some "set_hv"; - shortdesc = "set the hypervisor binary (usually qemu)"; - longdesc = "\ -Set the hypervisor binary (usually qemu) 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"; added = (1, 0, 6); - style = RConstString "hv", [], []; - blocking = false; - deprecated_by = Some "get_hv"; - tests = [ - InitNone, Always, TestRun ( - [["get_qemu"]]), [] - ]; - shortdesc = "get the hypervisor binary (usually qemu)"; - longdesc = "\ -Return the current hypervisor binary (usually qemu). - -This is always non-NULL. If it wasn't set already, then this will -return the default qemu binary name." }; - - { defaults with - name = "set_hv"; added = (1, 23, 17); - style = RErr, [String "hv"], []; - fish_alias = ["hv"]; config_only = true; - blocking = false; - shortdesc = "set the hypervisor binary"; - longdesc = "\ -Set the hypervisor binary that we will use. The hypervisor -depends on the backend, but is usually the location of the -qemu/KVM hypervisor. For the uml backend, it is the location -of the C or C binary. - -The default is chosen when the library was compiled by the -configure script. - -You can also override this by setting the C -environment variable. - -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_hv"; added = (1, 23, 17); - style = RString "hv", [], []; - blocking = false; - tests = [ - InitNone, Always, TestRun ( - [["get_hv"]]), [] - ]; - shortdesc = "get the hypervisor binary"; - longdesc = "\ -Return the current hypervisor 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"; added = (0, 0, 3); - style = RErr, [OptString "searchpath"], []; - fish_alias = ["path"]; config_only = true; - blocking = false; - 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"; added = (0, 0, 3); - style = RConstString "path", [], []; - blocking = false; - 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"; added = (1, 0, 26); - style = RErr, [OptString "append"], []; - fish_alias = ["append"]; config_only = true; - blocking = false; - shortdesc = "add options to kernel command line"; - longdesc = "\ -This function is used to add additional options to the -libguestfs appliance 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"; added = (1, 0, 26); - style = RConstOptString "append", [], []; - blocking = false; - (* This cannot be tested with the current framework. The - * function can return NULL in normal operations, which the - * test framework interprets as an error. - *) - shortdesc = "get the additional kernel options"; - longdesc = "\ -Return the additional kernel options which are added to the -libguestfs appliance kernel command line. - -If C then no options are added." }; - - { defaults with - name = "set_autosync"; added = (0, 0, 3); - style = RErr, [Bool "autosync"], []; - fish_alias = ["autosync"]; - blocking = false; - 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"; added = (0, 0, 3); - style = RBool "autosync", [], []; - blocking = false; - tests = [ - InitNone, Always, TestResultTrue ( - [["get_autosync"]]), [] - ]; - shortdesc = "get autosync mode"; - longdesc = "\ -Get the autosync flag." }; - - { defaults with - name = "set_verbose"; added = (0, 0, 3); - style = RErr, [Bool "verbose"], []; - fish_alias = ["verbose"]; - blocking = false; - 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"; added = (0, 0, 3); - style = RBool "verbose", [], []; - blocking = false; - shortdesc = "get verbose mode"; - longdesc = "\ -This returns the verbose messages flag." }; - - { defaults with - name = "is_ready"; added = (1, 0, 2); - style = RBool "ready", [], []; - visibility = VStateTest; - blocking = false; - tests = [ - InitNone, Always, TestResultTrue ( - [["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"; added = (1, 0, 2); - style = RBool "config", [], []; - blocking = false; - tests = [ - InitNone, Always, TestResultFalse ( - [["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"; added = (1, 0, 2); - style = RBool "launching", [], []; - visibility = VStateTest; - blocking = false; - tests = [ - InitNone, Always, TestResultFalse ( - [["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"; added = (1, 0, 2); - style = RBool "busy", [], []; - visibility = VStateTest; - blocking = false; - tests = [ - InitNone, Always, TestResultFalse ( - [["is_busy"]]), [] - ]; - shortdesc = "is busy processing a command"; - longdesc = "\ -This always returns false. This function is deprecated with no -replacement. Do not use this function. - -For more information on states, see L." }; - - { defaults with - name = "get_state"; added = (1, 0, 2); - style = RInt "state", [], []; - visibility = VStateTest; - blocking = false; - 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"; added = (1, 0, 55); - style = RErr, [Int "memsize"], []; - fish_alias = ["memsize"]; config_only = true; - blocking = false; - shortdesc = "set memory allocated to the hypervisor"; - longdesc = "\ -This sets the memory size in megabytes allocated to the -hypervisor. 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"; added = (1, 0, 55); - style = RInt "memsize", [], []; - blocking = false; - tests = [ - InitNone, Always, TestResult ( - [["get_memsize"]], "ret >= 256"), [] - ]; - shortdesc = "get memory allocated to the hypervisor"; - longdesc = "\ -This gets the memory size in megabytes allocated to the -hypervisor. - -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"; added = (1, 0, 56); - style = RInt "pid", [], []; - fish_alias = ["pid"]; - blocking = false; - shortdesc = "get PID of hypervisor"; - longdesc = "\ -Return the process ID of the hypervisor. If there is no -hypervisor running, then this will return an error. - -This is an internal call used for debugging and testing." }; - - { defaults with - name = "version"; added = (1, 0, 58); - style = RStruct ("version", "version"), [], []; - blocking = false; - tests = [ - InitNone, Always, TestResult ( - [["version"]], "ret->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 F 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 or C instead." }; - - { defaults with - name = "set_selinux"; added = (1, 0, 67); - style = RErr, [Bool "selinux"], []; - fish_alias = ["selinux"]; config_only = true; - blocking = false; - deprecated_by = Some "selinux_relabel"; - 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"; added = (1, 0, 67); - style = RBool "selinux", [], []; - blocking = false; - deprecated_by = Some "selinux_relabel"; - 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"; added = (1, 0, 69); - style = RErr, [Bool "trace"], []; - fish_alias = ["trace"]; - blocking = false; - tests = [ - InitNone, Always, TestResultFalse ( - [["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 L 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"; added = (1, 0, 69); - style = RBool "trace", [], []; - blocking = false; - shortdesc = "get command trace enabled flag"; - longdesc = "\ -Return the command trace flag." }; - - { defaults with - name = "set_direct"; added = (1, 0, 72); - style = RErr, [Bool "direct"], []; - fish_alias = ["direct"]; config_only = true; - blocking = false; - 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"; added = (1, 0, 72); - style = RBool "direct", [], []; - blocking = false; - shortdesc = "get direct appliance mode flag"; - longdesc = "\ -Return the direct appliance mode flag." }; - - { defaults with - name = "set_recovery_proc"; added = (1, 0, 77); - style = RErr, [Bool "recoveryproc"], []; - fish_alias = ["recovery-proc"]; config_only = true; - blocking = false; - 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 hypervisor -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 -the hypervisor, which is not very helpful." }; - - { defaults with - name = "get_recovery_proc"; added = (1, 0, 77); - style = RBool "recoveryproc", [], []; - blocking = false; - shortdesc = "get recovery process enabled flag"; - longdesc = "\ -Return the recovery process enabled flag." }; - - { defaults with - name = "add_drive_with_if"; added = (1, 0, 84); - style = RErr, [String "filename"; String "iface"], []; - deprecated_by = Some "add_drive"; config_only = true; - blocking = false; - 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"; added = (1, 0, 84); - style = RErr, [String "filename"; String "iface"], []; - blocking = false; - 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"; added = (1, 5, 3); - style = RString "arch", [Pathname "filename"], []; - tests = [ - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-aarch64-dynamic"]], "aarch64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-armv7-dynamic"]], "arm"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-i586-dynamic"]], "i386"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-ppc64-dynamic"]], "ppc64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-ppc64le-dynamic"]], "ppc64le"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-riscv64-dynamic"]], "riscv64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-s390x-dynamic"]], "s390x"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-sparc-dynamic"]], "sparc"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-win32.exe"]], "i386"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-win64.exe"]], "x86_64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-x86_64-dynamic"]], "x86_64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-aarch64.so"]], "aarch64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-armv7.so"]], "arm"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-i586.so"]], "i386"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-ppc64.so"]], "ppc64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-ppc64le.so"]], "ppc64le"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-riscv64.so"]], "riscv64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-s390x.so"]], "s390x"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-sparc.so"]], "sparc"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-win32.dll"]], "i386"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-win64.dll"]], "x86_64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-x86_64.so"]], "x86_64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/initrd-x86_64.img"]], "x86_64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/initrd-x86_64.img.gz"]], "x86_64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/bin-x86_64-dynamic.gz"]], "x86_64"), []; - InitISOFS, Always, TestResultString ( - [["file_architecture"; "/lib-i586.so.xz"]], "i386"), []; - ]; - shortdesc = "detect the architecture of a binary file"; - longdesc = "\ -This detects the architecture of the binary F, -and returns it if known. - -Currently defined architectures are: - -=over 4 - -=item \"aarch64\" - -64 bit ARM. - -=item \"arm\" - -32 bit ARM. - -=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 \"ia64\" - -Intel Itanium. - -=item \"ppc\" - -32 bit Power PC. - -=item \"ppc64\" - -64 bit Power PC (big endian). - -=item \"ppc64le\" - -64 bit Power PC (little endian). - -=item \"riscv32\" - -=item \"riscv64\" - -=item \"riscv128\" - -RISC-V 32-, 64- or 128-bit variants. - -=item \"s390\" - -31 bit IBM S/390. - -=item \"s390x\" - -64 bit IBM S/390. - -=item \"sparc\" - -32 bit SPARC. - -=item \"sparc64\" - -64 bit SPARC V9 and above. - -=item \"x86_64\" - -64 bit x86-64. - -=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"; added = (1, 5, 3); - 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"; added = (1, 5, 3); - style = RString "name", [Mountable "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 \"openbsd\" - -OpenBSD. - -=item \"hurd\" - -GNU/Hurd. - -=item \"dos\" - -MS-DOS, FreeDOS and others. - -=item \"minix\" - -MINIX. - -=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"; added = (1, 5, 3); - style = RString "arch", [Mountable "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"; added = (1, 5, 3); - style = RString "distro", [Mountable "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 \"alpinelinux\" - -Alpine Linux. - -=item \"altlinux\" - -ALT Linux. - -=item \"archlinux\" - -Arch Linux. - -=item \"buildroot\" - -Buildroot-derived distro, but not one we specifically recognize. - -=item \"centos\" - -CentOS. - -=item \"cirros\" - -Cirros. - -=item \"coreos\" - -CoreOS. - -=item \"debian\" - -Debian. - -=item \"fedora\" - -Fedora. - -=item \"freebsd\" - -FreeBSD. - -=item \"freedos\" - -FreeDOS. - -=item \"frugalware\" - -Frugalware. - -=item \"gentoo\" - -Gentoo. - -=item \"linuxmint\" - -Linux Mint. - -=item \"mageia\" - -Mageia. - -=item \"mandriva\" - -Mandriva. - -=item \"meego\" - -MeeGo. - -=item \"netbsd\" - -NetBSD. - -=item \"openbsd\" - -OpenBSD. - -=item \"opensuse\" - -OpenSUSE. - -=item \"oraclelinux\" - -Oracle Linux. - -=item \"pardus\" - -Pardus. - -=item \"pldlinux\" - -PLD Linux. - -=item \"redhat-based\" - -Some Red Hat-derived distro. - -=item \"rhel\" - -Red Hat Enterprise Linux. - -=item \"scientificlinux\" - -Scientific Linux. - -=item \"slackware\" - -Slackware. - -=item \"sles\" - -SuSE Linux Enterprise Server or Desktop. - -=item \"suse-based\" - -Some openSuSE-derived distro. - -=item \"ttylinux\" - -ttylinux. - -=item \"ubuntu\" - -Ubuntu. - -=item \"unknown\" - -The distro could not be determined. - -=item \"voidlinux\" - -Void Linux. - -=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"; added = (1, 5, 3); - style = RInt "major", [Mountable "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"; added = (1, 5, 3); - style = RInt "minor", [Mountable "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"; added = (1, 5, 3); - style = RString "product", [Mountable "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"; added = (1, 5, 3); - style = RHashtable "mountpoints", [Mountable "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 F. -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. F) and a value -which is the filesystem that would be mounted there -(eg. F). - -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\" F. 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"; added = (1, 5, 3); - style = RStringList "filesystems", [Mountable "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 = "mountable_device"; added = (1, 33, 15); - style = RString "device", [Mountable "mountable"], []; - shortdesc = "extract the device part of a mountable"; - longdesc = "\ -Returns the device name of a mountable. In quite a lot of -cases, the mountable is the device name. - -However this doesn't apply for btrfs subvolumes, where the -mountable is a combination of both the device name and the -subvolume path (see also C to -extract the subvolume path of the mountable if any)." }; - - { defaults with - name = "mountable_subvolume"; added = (1, 33, 15); - style = RString "subvolume", [Mountable "mountable"], []; - shortdesc = "extract the subvolume part of a mountable"; - longdesc = "\ -Returns the subvolume path of a mountable. Btrfs subvolumes -mountables are a combination of both the device name and the -subvolume path (see also C to extract -the device of the mountable). - -If the mountable does not represent a btrfs subvolume, then -this function fails and the C is set to C." }; - - { defaults with - name = "set_network"; added = (1, 5, 4); - style = RErr, [Bool "network"], []; - fish_alias = ["network"]; config_only = true; - blocking = false; - 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"; added = (1, 5, 4); - style = RBool "network", [], []; - blocking = false; - shortdesc = "get enable network flag"; - longdesc = "\ -This returns the enable network flag." }; - - { defaults with - name = "list_filesystems"; added = (1, 5, 15); - style = RHashtable "fses", [], []; - shortdesc = "list filesystems"; - longdesc = "\ -This inspection command looks for filesystems on partitions, -block devices and logical volumes, returning a list of C -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 key is not necessarily a block device. It may also be an opaque -'mountable' string which can be passed to C. - -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"; added = (0, 0, 3); - style = RErr, [String "filename"], [OBool "readonly"; OString "format"; OString "iface"; OString "name"; OString "label"; OString "protocol"; OStringList "server"; OString "username"; OString "secret"; OString "cachemode"; OString "discard"; OBool "copyonread"]; - once_had_no_optargs = true; - blocking = false; - fish_alias = ["add"]; - shortdesc = "add an image to examine or modify"; - longdesc = "\ -This function adds a disk image called F to the handle. -F may be a regular host file or a host device. - -When this function is called before C (the -usual case) then the first time you call this function, -the disk appears in the API as F, the second time -as F, and so on. - -In libguestfs E 1.20 you can also call this function -after launch (with some restrictions). This is called -\"hotplugging\". When hotplugging, you must specify a -C