[Libguestfs] [PATCH 5/6] 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 | 10082 ++++++++++++++++++++ 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 | 231 + 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 8c643ca..43b69e6 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<generator/actions.ml>. +type, tests, documentation) to F<generator/actions_*.ml>. 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<generator/actions.ml>), or in some rarer cases you may want to drop +(F<generator/actions_*.ml>), or in some rarer cases you may want to drop a script into C<tests/*/>. Note that adding a script to C<tests/*/> is slower, so if possible use the first method. The following describes the test environment used when you add an API -test in F<actions.ml>. +test in F<actions_*.ml>. The test environment has 4 block devices: diff --git a/generator/Makefile.am b/generator/Makefile.am index 03f01c0..c281789 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 6ae29bd..879a68c 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/<somefile>.c to +'actions_*.ml' to describe the interface, and daemon/<somefile>.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. <lang>.ml Generate bindings for <lang>. diff --git a/generator/actions.ml b/generator/actions.ml index 2c4e3d5..1fa3b02 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<guestfs_launch> 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<lt> 1.0.71 you had to call this function -just after calling C<guestfs_launch> to wait for the launch -to complete. However this is no longer necessary because -C<guestfs_launch> 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<guestfs_shutdown> 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<guestfs_add_drive_ro>." }; - - { 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<guestfs_add_drive_opts> -with the optional parameter C<GUESTFS_ADD_DRIVE_OPTS_READONLY> 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<hvparam> string must be a C<-> (dash). - -C<hvvalue> 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<LIBGUESTFS_HV> -environment variable. - -Setting C<hv> to C<NULL> 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<qemu -help>). -If the qemu binary changes, we don't retest features, and -so you might see inconsistent results. Using the environment -variable C<LIBGUESTFS_HV> 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<linux> or C<vmlinux> binary. - -The default is chosen when the library was compiled by the -configure script. - -You can also override this by setting the C<LIBGUESTFS_HV> -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<qemu -help>). -If the qemu binary changes, we don't retest features, and -so you might see inconsistent results. Using the environment -variable C<LIBGUESTFS_HV> 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<LIBGUESTFS_PATH> environment variable. - -Setting C<path> to C<NULL> 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<NULL> unless overridden by setting -C<LIBGUESTFS_APPEND> environment variable. - -Setting C<append> to C<NULL> means I<no> 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<NULL> 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<autosync> 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<verbose> is true, this turns on verbose messages. - -Verbose messages are disabled unless the environment variable -C<LIBGUESTFS_DEBUG> is defined and set to C<1>. - -Verbose messages are normally sent to C<stderr>, unless you -register a callback to send them somewhere else (see -C<guestfs_set_event_callback>)." }; - - { 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<READY> state). - -For more information on states, see L<guestfs(3)>." }; - - { 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<CONFIG> state). - -For more information on states, see L<guestfs(3)>." }; - - { 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<LAUNCHING> state). - -For more information on states, see L<guestfs(3)>." }; - - { 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<guestfs(3)>." }; - - { 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<guestfs(3)>." }; - - { 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<guestfs_launch>. - -You can also change this by setting the environment -variable C<LIBGUESTFS_MEMSIZE> before the handle is -created. - -For more information on the architecture of libguestfs, -see L<guestfs(3)>." }; - - { 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<guestfs_set_memsize> was not called -on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set, -then this returns the compiled-in default value for memsize. - -For more information on the architecture of libguestfs, -see L<guestfs(3)>." }; - - { 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<libguestfs.so> 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<major>, C<minor> and C<release>) are numbers and -correspond to the usual version triplet. The fourth element -(C<extra>) 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<guestfs(3)/LIBGUESTFS VERSION NUMBERS>. - -I<Note:> 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<guestfs_available> or C<guestfs_feature_available> 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<selinux=0> (disabled). - -Note that if SELinux is enabled, it is always in -Permissive mode (C<enforcing=0>). - -For more information on the architecture of libguestfs, -see L<guestfs(3)>." }; - - { 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<guestfs_set_selinux>. - -For more information on the architecture of libguestfs, -see L<guestfs(3)>." }; - - { 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<ltrace(1)> command. - -Command traces are disabled unless the environment variable -C<LIBGUESTFS_TRACE> is defined and set to C<1>. - -Trace messages are normally sent to C<stderr>, unless you -register a callback to send them somewhere else (see -C<guestfs_set_event_callback>)." }; - - { 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<guestfs_set_log_message_callback>, -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<false> then -C<guestfs_launch> 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<guestfs_launch>, -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<guestfs_add_drive> 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<guestfs_add_drive_ro> 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<filename>, -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<i386>. - -Win64 binaries and DLLs return C<x86_64>. - -=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<guestfs_inspect_get_*> 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<guestfs_mount_ro> and C<guestfs_umount_all> 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<guestfs(3)/INSPECTION> for more details. - -See also C<guestfs_list_filesystems>." }; - - { 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<guestfs(3)/INSPECTION> 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<guestfs_file_architecture>. - -If the architecture could not be determined, then the -string C<unknown> is returned. - -Please read L<guestfs(3)/INSPECTION> 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<guestfs(3)/INSPECTION> 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<not> -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<guestfs(3)/INSPECTION> 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<guestfs(3)/INSPECTION> for more details. -See also C<guestfs_inspect_get_major_version>." }; - - { 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<unknown> is returned. - -Please read L<guestfs(3)/INSPECTION> 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</etc/fstab>. -I<In particular note> 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</boot>) and a value -which is the filesystem that would be mounted there -(eg. F</dev/sda1>). - -Non-mounted devices such as swap devices are I<not> -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<guestfs_inspect_get_drive_mappings>. - -Please read L<guestfs(3)/INSPECTION> for more details. -See also C<guestfs_inspect_get_filesystems>." }; - - { 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<guestfs(3)/INSPECTION> for more details. -See also C<guestfs_inspect_get_mountpoints>." }; - - { 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<guestfs_mountable_subvolume> 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<guestfs_mountable_device> to extract -the device of the mountable). - -If the mountable does not represent a btrfs subvolume, then -this function fails and the C<errno> is set to C<EINVAL>." }; - - { 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<network> 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<guestfs(3)/RUNNING COMMANDS>). - -You must call this before calling C<guestfs_launch>, 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<mountables> -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<guestfs_mount>. - -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<guestfs_mount> and C<guestfs_umount>, 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<guestfs_inspect_os> 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<filename> to the handle. -F<filename> may be a regular host file or a host device. - -When this function is called before C<guestfs_launch> (the -usual case) then the first time you call this function, -the disk appears in the API as F</dev/sda>, the second time -as F</dev/sdb>, and so on. - -In libguestfs E<ge> 1.20 you can also call this function -after launch (with some restrictions). This is called -\"hotplugging\". When hotplugging, you must specify a -C<label> so that the new disk gets a predictable name. -For more information see L<guestfs(3)/HOTPLUGGING>. - -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 F<filename> exists. - -F<filename> may be the special string C<\"/dev/null\">. -See L<guestfs(3)/NULL DISKS>. - -The optional arguments are: - -=over 4 - -=item C<readonly> - -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<format> - -This forces the image format. If you omit this (or use C<guestfs_add_drive> -or C<guestfs_add_drive_ro>) then the format is automatically detected. -Possible formats include C<raw> and C<qcow2>. - -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<iface> - -This rarely-used option lets you emulate the behaviour of the -deprecated C<guestfs_add_drive_with_if> call (q.v.) - -=item C<name> - -The name the drive had in the original guest, e.g. F</dev/sdb>. -This is used as a hint to the guest inspection process if -it is available. - -=item C<label> - -Give the disk a label. The label should be a unique, short -string using I<only> ASCII characters C<[a-zA-Z]>. -As well as its usual name in the API (such as F</dev/sda>), -the drive will also be named F</dev/disk/guestfs/I<label>>. - -See L<guestfs(3)/DISK LABELS>. - -=item C<protocol> - -The optional protocol argument can be used to select an alternate -source protocol. - -See also: L<guestfs(3)/REMOTE STORAGE>. - -=over 4 - -=item C<protocol = \"file\"> - -F<filename> is interpreted as a local file or device. -This is the default if the optional protocol parameter -is omitted. - -=item C<protocol = \"ftp\"|\"ftps\"|\"http\"|\"https\"|\"tftp\"> - -Connect to a remote FTP, HTTP or TFTP server. -The C<server> parameter must also be supplied - see below. - -See also: L<guestfs(3)/FTP, HTTP AND TFTP> - -=item C<protocol = \"gluster\"> - -Connect to the GlusterFS server. -The C<server> parameter must also be supplied - see below. - -See also: L<guestfs(3)/GLUSTER> - -=item C<protocol = \"iscsi\"> - -Connect to the iSCSI server. -The C<server> parameter must also be supplied - see below. -The C<username> parameter may be supplied. See below. -The C<secret> parameter may be supplied. See below. - -See also: L<guestfs(3)/ISCSI>. - -=item C<protocol = \"nbd\"> - -Connect to the Network Block Device server. -The C<server> parameter must also be supplied - see below. - -See also: L<guestfs(3)/NETWORK BLOCK DEVICE>. - -=item C<protocol = \"rbd\"> - -Connect to the Ceph (librbd/RBD) server. -The C<server> parameter must also be supplied - see below. -The C<username> parameter may be supplied. See below. -The C<secret> parameter may be supplied. See below. - -See also: L<guestfs(3)/CEPH>. - -=item C<protocol = \"sheepdog\"> - -Connect to the Sheepdog server. -The C<server> parameter may also be supplied - see below. - -See also: L<guestfs(3)/SHEEPDOG>. - -=item C<protocol = \"ssh\"> - -Connect to the Secure Shell (ssh) server. - -The C<server> parameter must be supplied. -The C<username> parameter may be supplied. See below. - -See also: L<guestfs(3)/SSH>. - -=back - -=item C<server> - -For protocols which require access to a remote server, this -is a list of server(s). - - Protocol Number of servers required - -------- -------------------------- - file List must be empty or param not used at all - ftp|ftps|http|https|tftp Exactly one - gluster Exactly one - iscsi Exactly one - nbd Exactly one - rbd Zero or more - sheepdog Zero or more - ssh Exactly one - -Each list element is a string specifying a server. The string must be -in one of the following formats: - - hostname - hostname:port - tcp:hostname - tcp:hostname:port - unix:/path/to/socket - -If the port number is omitted, then the standard port number -for the protocol is used (see F</etc/services>). - -=item C<username> - -For the C<ftp>, C<ftps>, C<http>, C<https>, C<iscsi>, C<rbd>, C<ssh> -and C<tftp> protocols, this specifies the remote username. - -If not given, then the local username is used for C<ssh>, and no authentication -is attempted for ceph. But note this sometimes may give unexpected results, for -example if using the libvirt backend and if the libvirt backend is configured to -start the qemu appliance as a special user such as C<qemu.qemu>. If in doubt, -specify the remote username you want. - -=item C<secret> - -For the C<rbd> protocol only, this specifies the 'secret' to use when -connecting to the remote device. It must be base64 encoded. - -If not given, then a secret matching the given username will be looked up in the -default keychain locations, or if no username is given, then no authentication -will be used. - -=item C<cachemode> - -Choose whether or not libguestfs will obey sync operations (safe but slow) -or not (unsafe but fast). The possible values for this string are: - -=over 4 - -=item C<cachemode = \"writeback\"> - -This is the default. - -Write operations in the API do not return until a L<write(2)> -call has completed in the host [but note this does not imply -that anything gets written to disk]. - -Sync operations in the API, including implicit syncs caused by -filesystem journalling, will not return until an L<fdatasync(2)> -call has completed in the host, indicating that data has been -committed to disk. - -=item C<cachemode = \"unsafe\"> - -In this mode, there are no guarantees. Libguestfs may cache -anything and ignore sync requests. This is suitable only -for scratch or temporary disks. - -=back - -=item C<discard> - -Enable or disable discard (a.k.a. trim or unmap) support on this -drive. If enabled, operations such as C<guestfs_fstrim> will be able -to discard / make thin / punch holes in the underlying host file -or device. - -Possible discard settings are: - -=over 4 - -=item C<discard = \"disable\"> - -Disable discard support. This is the default. - -=item C<discard = \"enable\"> - -Enable discard support. Fail if discard is not possible. - -=item C<discard = \"besteffort\"> - -Enable discard support if possible, but don't fail if it is not -supported. - -Since not all backends and not all underlying systems support -discard, this is a good choice if you want to use discard if -possible, but don't mind if it doesn't work. - -=back - -=item C<copyonread> - -The boolean parameter C<copyonread> enables copy-on-read support. -This only affects disk formats which have backing files, and causes -reads to be stored in the overlay layer, speeding up multiple reads -of the same area of disk. - -The default is false. - -=back" }; - - { defaults with - name = "inspect_get_windows_systemroot"; added = (1, 5, 25); - style = RString "systemroot", [Mountable "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 F</WINDOWS>. - -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<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_get_roots"; added = (1, 7, 3); - 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<guestfs_inspect_os>, -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<guestfs_inspect_os>. - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "debug_drives"; added = (1, 13, 22); - style = RStringList "cmdline", [], []; - visibility = VDebug; - blocking = 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"; added = (1, 7, 4); - style = RInt "nrdisks", [String "dom"], [OString "libvirturi"; OBool "readonly"; OString "iface"; OBool "live"; OBool "allowuuid"; OString "readonlydisk"; OString "cachemode"; OString "discard"; OBool "copyonread"]; - 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<dom>. It works by connecting to libvirt, requesting -the domain and domain XML from libvirt, parsing it for disks, -and calling C<guestfs_add_drive_opts> 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<readonly> 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<http://libvirt.org/remote.html>) -will fail unless those disks are accessible via the same device path -locally too. - -The optional C<libvirturi> parameter sets the libvirt URI -(see L<http://libvirt.org/uri.html>). 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<live> flag controls whether this call will try -to connect to a running virtual machine C<guestfsd> process if -it sees a suitable E<lt>channelE<gt> element in the libvirt -XML definition. The default (if the flag is omitted) is never -to try. See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more -information. - -If the C<allowuuid> flag is true (default is false) then a UUID -I<may> be passed instead of the domain name. The C<dom> string is -treated as a UUID first and looked up, and if that lookup fails -then we treat C<dom> as a name as usual. - -The optional C<readonlydisk> parameter controls what we do for -disks which are marked E<lt>readonly/E<gt> in the libvirt XML. -Possible values are: - -=over 4 - -=item readonlydisk = \"error\" - -If C<readonly> is false: - -The whole call is aborted with an error if any disk with -the E<lt>readonly/E<gt> flag is found. - -If C<readonly> is true: - -Disks with the E<lt>readonly/E<gt> flag are added read-only. - -=item readonlydisk = \"read\" - -If C<readonly> is false: - -Disks with the E<lt>readonly/E<gt> flag are added read-only. -Other disks are added read/write. - -If C<readonly> is true: - -Disks with the E<lt>readonly/E<gt> flag are added read-only. - -=item readonlydisk = \"write\" (default) - -If C<readonly> is false: - -Disks with the E<lt>readonly/E<gt> flag are added read/write. - -If C<readonly> is true: - -Disks with the E<lt>readonly/E<gt> flag are added read-only. - -=item readonlydisk = \"ignore\" - -If C<readonly> is true or false: - -Disks with the E<lt>readonly/E<gt> flag are skipped. - -=back - -The other optional parameters are passed directly through to -C<guestfs_add_drive_opts>." }; - - { defaults with - name = "add_libvirt_dom"; added = (1, 29, 14); - style = RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [OBool "readonly"; OString "iface"; OBool "live"; OString "readonlydisk"; OString "cachemode"; OString "discard"; OBool "copyonread"]; - config_only = true; - shortdesc = "add the disk(s) from a libvirt domain"; - longdesc = "\ -This function adds the disk(s) attached to the libvirt domain C<dom>. -It works by requesting the domain XML from libvirt, parsing it for -disks, and calling C<guestfs_add_drive_opts> on each one. - -In the C API we declare C<void *dom>, but really it has type -C<virDomainPtr dom>. This is so we don't need E<lt>libvirt.hE<gt>. - -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<readonly> 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<http://libvirt.org/remote.html>) -will fail unless those disks are accessible via the same device path -locally too. - -The optional C<live> flag controls whether this call will try -to connect to a running virtual machine C<guestfsd> process if -it sees a suitable E<lt>channelE<gt> element in the libvirt -XML definition. The default (if the flag is omitted) is never -to try. See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more -information. - -The optional C<readonlydisk> parameter controls what we do for -disks which are marked E<lt>readonly/E<gt> in the libvirt XML. -See C<guestfs_add_domain> for possible values. - -The other optional parameters are passed directly through to -C<guestfs_add_drive_opts>." }; - - { defaults with - name = "inspect_get_package_format"; added = (1, 7, 5); - style = RString "packageformat", [Mountable "root"], []; - shortdesc = "get package format used by the operating system"; - longdesc = "\ -This function and C<guestfs_inspect_get_package_management> return -the package format and package management tool used by the -inspected operating system. For example for Fedora these -functions would return C<rpm> (package format), and -C<yum> or C<dnf> (package management). - -This returns the string C<unknown> if we could not determine the -package format I<or> if the operating system does not have -a real packaging system (eg. Windows). - -Possible strings include: -C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>, C<pkgsrc>, C<apk>, -C<xbps>. -Future versions of libguestfs may return other strings. - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_get_package_management"; added = (1, 7, 5); - style = RString "packagemanagement", [Mountable "root"], []; - shortdesc = "get package management tool used by the operating system"; - longdesc = "\ -C<guestfs_inspect_get_package_format> 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<rpm> (package format), and -C<yum> or C<dnf> (package management). - -This returns the string C<unknown> if we could not determine the -package management tool I<or> if the operating system does not have -a real packaging system (eg. Windows). - -Possible strings include: C<yum>, C<dnf>, C<up2date>, -C<apt> (for all Debian derivatives), -C<portage>, C<pisi>, C<pacman>, C<urpmi>, C<zypper>, C<apk>, C<xbps>. -Future versions of libguestfs may return other strings. - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_list_applications"; added = (1, 7, 8); - style = RStructList ("applications", "application"), [Mountable "root"], []; - deprecated_by = Some "inspect_list_applications2"; - shortdesc = "get list of applications installed in the operating system"; - longdesc = "\ -Return the list of applications installed in the operating system. - -I<Note:> This call works differently from other parts of the -inspection API. You have to call C<guestfs_inspect_os>, then -C<guestfs_inspect_get_mountpoints>, 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<guestfs_inspect_get_*> 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<app_name> - -The name of the application. For Red Hat-derived and Debian-derived -Linux guests, this is the package name. - -=item C<app_display_name> - -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<app_name> instead. - -=item C<app_epoch> - -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<app_version> - -The version string of the application or package. If unavailable -this is returned as an empty string C<\"\">. - -=item C<app_release> - -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<app_install_path> - -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<app_trans_path> - -The install path translated into a libguestfs path. -If unavailable this is returned as an empty string C<\"\">. - -=item C<app_publisher> - -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<app_url> - -The URL (eg. upstream URL) of the application. -If unavailable this is returned as an empty string C<\"\">. - -=item C<app_source_package> - -For packaging systems which support this, the name of the source -package. If unavailable this is returned as an empty string C<\"\">. - -=item C<app_summary> - -A short (usually one line) description of the application or package. -If unavailable this is returned as an empty string C<\"\">. - -=item C<app_description> - -A longer description of the application or package. -If unavailable this is returned as an empty string C<\"\">. - -=back - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_list_applications2"; added = (1, 19, 56); - style = RStructList ("applications2", "application2"), [Mountable "root"], []; - shortdesc = "get list of applications installed in the operating system"; - longdesc = "\ -Return the list of applications installed in the operating system. - -I<Note:> This call works differently from other parts of the -inspection API. You have to call C<guestfs_inspect_os>, then -C<guestfs_inspect_get_mountpoints>, 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<guestfs_inspect_get_*> 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<app2_name> - -The name of the application. For Red Hat-derived and Debian-derived -Linux guests, this is the package name. - -=item C<app2_display_name> - -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<app2_name> instead. - -=item C<app2_epoch> - -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<app2_version> - -The version string of the application or package. If unavailable -this is returned as an empty string C<\"\">. - -=item C<app2_release> - -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<app2_arch> - -The architecture string of the application or package, for package -managers that use this. If unavailable this is returned as an empty -string C<\"\">. - -=item C<app2_install_path> - -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<app2_trans_path> - -The install path translated into a libguestfs path. -If unavailable this is returned as an empty string C<\"\">. - -=item C<app2_publisher> - -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<app2_url> - -The URL (eg. upstream URL) of the application. -If unavailable this is returned as an empty string C<\"\">. - -=item C<app2_source_package> - -For packaging systems which support this, the name of the source -package. If unavailable this is returned as an empty string C<\"\">. - -=item C<app2_summary> - -A short (usually one line) description of the application or package. -If unavailable this is returned as an empty string C<\"\">. - -=item C<app2_description> - -A longer description of the application or package. -If unavailable this is returned as an empty string C<\"\">. - -=back - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_get_hostname"; added = (1, 7, 9); - style = RString "hostname", [Mountable "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<unknown> is returned. - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_get_format"; added = (1, 9, 4); - style = RString "format", [Mountable "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<bootable> 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<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_is_live"; added = (1, 9, 4); - style = RBool "live", [Mountable "root"], []; - shortdesc = "get live flag for install disk"; - longdesc = "\ -If C<guestfs_inspect_get_format> returns C<installer> (this -is an install disk), then this returns true if a live image -was detected on the disk. - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_is_netinst"; added = (1, 9, 4); - style = RBool "netinst", [Mountable "root"], []; - shortdesc = "get netinst (network installer) flag for install disk"; - longdesc = "\ -If C<guestfs_inspect_get_format> returns C<installer> (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<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_is_multipart"; added = (1, 9, 4); - style = RBool "multipart", [Mountable "root"], []; - shortdesc = "get multipart flag for install disk"; - longdesc = "\ -If C<guestfs_inspect_get_format> returns C<installer> (this -is an install disk), then this returns true if the disk is -part of a set. - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "set_attach_method"; added = (1, 9, 8); - style = RErr, [String "backend"], []; - fish_alias = ["attach-method"]; config_only = true; - blocking = false; - deprecated_by = Some "set_backend"; - shortdesc = "set the backend"; - longdesc = "\ -Set the method that libguestfs uses to connect to the backend -guestfsd daemon. - -See L<guestfs(3)/BACKEND>." }; - - { defaults with - name = "get_attach_method"; added = (1, 9, 8); - style = RString "backend", [], []; - blocking = false; - deprecated_by = Some "get_backend"; - tests = [ - InitNone, Always, TestRun ( - [["get_attach_method"]]), [] - ]; - shortdesc = "get the backend"; - longdesc = "\ -Return the current backend. - -See C<guestfs_set_backend> and L<guestfs(3)/BACKEND>." }; - - { defaults with - name = "set_backend"; added = (1, 21, 26); - style = RErr, [String "backend"], []; - fish_alias = ["backend"]; config_only = true; - blocking = false; - shortdesc = "set the backend"; - longdesc = "\ -Set the method that libguestfs uses to connect to the backend -guestfsd daemon. - -This handle property was previously called the \"attach method\". - -See L<guestfs(3)/BACKEND>." }; - - { defaults with - name = "get_backend"; added = (1, 21, 26); - style = RString "backend", [], []; - blocking = false; - tests = [ - InitNone, Always, TestRun ( - [["get_backend"]]), [] - ]; - shortdesc = "get the backend"; - longdesc = "\ -Return the current backend. - -This handle property was previously called the \"attach method\". - -See C<guestfs_set_backend> and L<guestfs(3)/BACKEND>." }; - - { defaults with - name = "inspect_get_product_variant"; added = (1, 9, 13); - style = RString "variant", [Mountable "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<HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion> -C<InstallationType> which is usually a string such as -C<Client> or C<Server> (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<Client> and the latter is C<Server>). - -For enterprise Linux guests, in future we intend this to return -the product variant such as C<Desktop>, C<Server> and so on. But -this is not implemented at present. - -If the product variant could not be determined, then the -string C<unknown> is returned. - -Please read L<guestfs(3)/INSPECTION> for more details. -See also C<guestfs_inspect_get_product_name>, -C<guestfs_inspect_get_major_version>." }; - - { defaults with - name = "inspect_get_windows_current_control_set"; added = (1, 9, 17); - style = RString "controlset", [Mountable "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<ControlSet001>. - -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<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_get_drive_mappings"; added = (1, 9, 17); - style = RHashtable "drives", [Mountable "root"], []; - shortdesc = "get drive letter mappings"; - longdesc = "\ -This call is useful for Windows which uses a primitive system -of assigning drive letters (like F<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<h0>, C<h1> 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<guestfs(3)/INSPECTION> for more details. -See also C<guestfs_inspect_get_mountpoints>, -C<guestfs_inspect_get_filesystems>." }; - - { defaults with - name = "inspect_get_icon"; added = (1, 11, 12); - style = RBufferOut "icon", [Mountable "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<Callers must check for this case>. - -Libguestfs will start by looking for a file called -F</etc/favicon.png> or F<C:\\etc\\favicon.png> -and if it has the correct format, the contents of this file will -be returned. You can disable favicons by passing the -optional C<favicon> 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<highquality> 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<Security:> 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<wrestool> program from the C<icoutils> package, and -several programs (C<bmptopnm>, C<pnmtopng>, C<pamcut>) -from the C<netpbm> 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"; added = (1, 11, 18); - style = RErr, [Bool "pgroup"], []; - fish_alias = ["pgroup"]; config_only = true; - blocking = false; - shortdesc = "set process group flag"; - longdesc = "\ -If C<pgroup> is true, child processes are placed into -their own process group. - -The practical upshot of this is that signals like C<SIGINT> (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<guestfs_user_cancel>)." }; - - { defaults with - name = "get_pgroup"; added = (1, 11, 18); - style = RBool "pgroup", [], []; - blocking = false; - shortdesc = "get process group flag"; - longdesc = "\ -This returns the process group flag." }; - - { defaults with - name = "set_smp"; added = (1, 13, 15); - style = RErr, [Int "smp"], []; - fish_alias = ["smp"]; config_only = true; - blocking = false; - 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<guestfs_launch>." }; - - { defaults with - name = "get_smp"; added = (1, 13, 15); - style = RInt "smp", [], []; - blocking = false; - 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"; added = (1, 17, 22); - 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<localmountpoint>. -Ordinary reads and writes to files and directories under -C<localmountpoint> are redirected through libguestfs. - -If the optional C<readonly> flag is set to true, then -writes to the filesystem return error C<EROFS>. - -C<options> is a comma-separated list of mount options. -See L<guestmount(1)> for some useful options. - -C<cachetimeout> sets the timeout (in seconds) for cached directory -entries. The default is 60 seconds. See L<guestmount(1)> -for further information. - -If C<debugcalls> is set to true, then additional debugging -information is generated for every FUSE call. - -When C<guestfs_mount_local> returns, the filesystem is ready, -but is not processing requests (access to it will block). You -have to call C<guestfs_mount_local_run> to run the main loop. - -See L<guestfs(3)/MOUNT LOCAL> for full documentation." }; - - { defaults with - name = "mount_local_run"; added = (1, 17, 22); - 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<guestfs_mount_local> -returns successfully. The call will not return until the -filesystem is unmounted. - -B<Note> you must I<not> make concurrent libguestfs calls -on the same handle from another thread. - -You may call this from a different thread than the one which -called C<guestfs_mount_local>, subject to the usual rules -for threads and libguestfs (see -L<guestfs(3)/MULTIPLE HANDLES AND MULTIPLE THREADS>). - -See L<guestfs(3)/MOUNT LOCAL> for full documentation." }; - - { defaults with - name = "umount_local"; added = (1, 17, 22); - style = RErr, [], [OBool "retry"]; - test_excuse = "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<guestfs(3)/MOUNT LOCAL> for full documentation." }; - - { defaults with - name = "max_disks"; added = (1, 19, 7); - style = RInt "disks", [], []; - blocking = false; - 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<guestfs_add_drive_opts> and similar calls). - -This function was added in libguestfs 1.19.7. In previous -versions of libguestfs the limit was 25. - -See L<guestfs(3)/MAXIMUM NUMBER OF DISKS> for additional -information on this topic." }; - - { defaults with - name = "canonical_device_name"; added = (1, 19, 7); - style = RString "canonical", [String "device"], []; - tests = [ - InitNone, Always, TestResultString ( - [["canonical_device_name"; "/dev/hda"]], "/dev/sda"), []; - InitNone, Always, TestResultString ( - [["canonical_device_name"; "/dev/vdaaa"]], "/dev/sdaaa"), []; - InitNone, Always, TestResultString ( - [["canonical_device_name"; "/dev/sdb"]], "/dev/sdb"), []; - InitBasicFSonLVM, IfAvailable "lvm2", TestResultString ( - [["canonical_device_name"; "/dev/mapper/VG-LV"]], "/dev/VG/LV"), []; - InitNone, Always, TestResultString ( - [["canonical_device_name"; "/dev/md0"]], "/dev/md0"), []; - InitNone, Always, TestResultString ( - [["canonical_device_name"; "/dev/md127"]], "/dev/md127"), []; - ]; - 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 F</dev/hdX> - -=item F</dev/vdX> - -These are returned as F</dev/sdX>. Note this works for device -names and partition names. This is approximately the reverse of -the algorithm described in L<guestfs(3)/BLOCK DEVICE NAMING>. - -=item F</dev/mapper/VG-LV> - -=item F</dev/dm-N> - -Converted to F</dev/VG/LV> form using C<guestfs_lvm_canonical_lv_name>. - -=back - -Other strings are returned unmodified." }; - - { defaults with - name = "shutdown"; added = (1, 19, 16); - style = RErr, [], []; - shortdesc = "shutdown the hypervisor"; - longdesc = "\ -This is the opposite of C<guestfs_launch>. 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<not> 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<not> close or free up the handle. You still -need to call C<guestfs_close> afterwards. - -C<guestfs_close> will call this if you don't do it explicitly, -but note that any errors are ignored in that case." }; - - { defaults with - name = "cat"; added = (0, 0, 4); - style = RString "content", [Pathname "path"], []; - tests = [ - InitISOFS, Always, TestResultString ( - [["cat"; "/known-2"]], "abcdef\n"), [] - ]; - shortdesc = "list the contents of a file"; - longdesc = "\ -Return the contents of the file named C<path>. - -Because, in C, this function returns a C<char *>, 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<guestfs_read_file> -or C<guestfs_download> functions." }; - - { defaults with - name = "find"; added = (1, 0, 27); - style = RStringList "names", [Pathname "directory"], []; - tests = [ - InitBasicFS, Always, TestResult ( - [["find"; "/"]], - "is_string_list (ret, 1, \"lost+found\")"), []; - InitBasicFS, Always, TestResult ( - [["touch"; "/a"]; - ["mkdir"; "/b"]; - ["touch"; "/b/c"]; - ["find"; "/"]], - "is_string_list (ret, 4, \"a\", \"b\", \"b/c\", \"lost+found\")"), []; - InitScratchFS, Always, TestResult ( - [["mkdir_p"; "/find/b/c"]; - ["touch"; "/find/b/c/d"]; - ["find"; "/find/b/"]], - "is_string_list (ret, 2, \"c\", \"c/d\")"), [] - ]; - shortdesc = "find all files and directories"; - longdesc = "\ -This command lists out all files and directories, recursively, -starting at F<directory>. It is essentially equivalent to -running the shell command C<find directory -print> but some -post-processing happens on the output, described below. - -This returns a list of strings I<without any prefix>. Thus -if the directory structure was: - - /tmp/a - /tmp/b - /tmp/c/d - -then the returned list from C<guestfs_find> F</tmp> would be -4 elements: - - a - b - c - c/d - -If F<directory> is not a directory, then this command returns -an error. - -The returned list is sorted." }; - - { defaults with - name = "read_file"; added = (1, 0, 63); - style = RBufferOut "content", [Pathname "path"], []; - tests = [ - InitISOFS, Always, TestResult ( - [["read_file"; "/known-4"]], - "compare_buffers (ret, size, \"abc\\ndef\\nghi\", 11) == 0"), [] - ]; - shortdesc = "read a file"; - longdesc = "\ -This calls returns the contents of the file C<path> as a -buffer. - -Unlike C<guestfs_cat>, this function can correctly -handle files that contain embedded ASCII NUL characters." }; - - { defaults with - name = "read_lines"; added = (0, 0, 7); - style = RStringList "lines", [Pathname "path"], []; - tests = [ - InitISOFS, Always, TestResult ( - [["read_lines"; "/known-4"]], - "is_string_list (ret, 3, \"abc\", \"def\", \"ghi\")"), []; - InitISOFS, Always, TestResult ( - [["read_lines"; "/empty"]], - "is_string_list (ret, 0)"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/read_lines1"; "\n"]; - ["read_lines"; "/read_lines1"]], - "is_string_list (ret, 1, \"\")"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/read_lines2"; "\r\n"]; - ["read_lines"; "/read_lines2"]], - "is_string_list (ret, 1, \"\")"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/read_lines3"; "\n\r\n"]; - ["read_lines"; "/read_lines3"]], - "is_string_list (ret, 2, \"\", \"\")"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/read_lines4"; "a"]; - ["read_lines"; "/read_lines4"]], - "is_string_list (ret, 1, \"a\")"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/read_lines5"; "a\nb"]; - ["read_lines"; "/read_lines5"]], - "is_string_list (ret, 2, \"a\", \"b\")"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/read_lines6"; "a\nb\n"]; - ["read_lines"; "/read_lines6"]], - "is_string_list (ret, 2, \"a\", \"b\")"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/read_lines7"; "a\nb\r\n"]; - ["read_lines"; "/read_lines7"]], - "is_string_list (ret, 2, \"a\", \"b\")"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/read_lines8"; "a\nb\r\n\n"]; - ["read_lines"; "/read_lines8"]], - "is_string_list (ret, 3, \"a\", \"b\", \"\")"), []; - ]; - shortdesc = "read file as lines"; - longdesc = "\ -Return the contents of the file named C<path>. - -The file contents are returned as a list of lines. Trailing -C<LF> and C<CRLF> character sequences are I<not> 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<guestfs_read_file> -function and split the buffer into lines yourself." }; - - { defaults with - name = "write"; added = (1, 3, 14); - style = RErr, [Pathname "path"; BufferIn "content"], []; - tests = [ - InitScratchFS, Always, TestResultString ( - [["write"; "/write"; "new file contents"]; - ["cat"; "/write"]], "new file contents"), []; - InitScratchFS, Always, TestResultString ( - [["write"; "/write2"; "\nnew file contents\n"]; - ["cat"; "/write2"]], "\nnew file contents\n"), []; - InitScratchFS, Always, TestResultString ( - [["write"; "/write3"; "\n\n"]; - ["cat"; "/write3"]], "\n\n"), []; - InitScratchFS, Always, TestResultString ( - [["write"; "/write4"; ""]; - ["cat"; "/write4"]], ""), []; - InitScratchFS, Always, TestResultString ( - [["write"; "/write5"; "\n\n\n"]; - ["cat"; "/write5"]], "\n\n\n"), []; - InitScratchFS, Always, TestResultString ( - [["write"; "/write6"; "\n"]; - ["cat"; "/write6"]], "\n"), [] - ]; - shortdesc = "create a new file"; - longdesc = "\ -This call creates a file called C<path>. The content of the -file is the string C<content> (which can contain any 8 bit data). - -See also C<guestfs_write_append>." }; - - { defaults with - name = "write_append"; added = (1, 11, 18); - style = RErr, [Pathname "path"; BufferIn "content"], []; - tests = [ - InitScratchFS, Always, TestResultString ( - [["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<content> to the end of file C<path>. If -C<path> does not exist, then a new file is created. - -See also C<guestfs_write>." }; - - { defaults with - name = "lstatlist"; added = (1, 0, 77); - style = RStructList ("statbufs", "stat"), [Pathname "path"; FilenameList "names"], []; - deprecated_by = Some "lstatnslist"; - shortdesc = "lstat on multiple files"; - longdesc = "\ -This call allows you to perform the C<guestfs_lstat> operation -on multiple files, where all files are in the directory C<path>. -C<names> 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<names> list. If any name did not exist -or could not be lstat'd, then the C<st_ino> 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<guestfs_lxattrlist> for a similarly efficient call -for getting extended attributes." }; - - { defaults with - name = "lstatnslist"; added = (1, 27, 53); - style = RStructList ("statbufs", "statns"), [Pathname "path"; FilenameList "names"], []; - shortdesc = "lstat on multiple files"; - longdesc = "\ -This call allows you to perform the C<guestfs_lstatns> operation -on multiple files, where all files are in the directory C<path>. -C<names> 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<names> list. If any name did not exist -or could not be lstat'd, then the C<st_ino> 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<guestfs_lxattrlist> for a similarly efficient call -for getting extended attributes." }; - - { defaults with - name = "lxattrlist"; added = (1, 0, 77); - style = RStructList ("xattrs", "xattr"), [Pathname "path"; FilenameList "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<path>. -C<names> 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<attrname>. C<attrval> in this struct is zero-length -to indicate there was an error doing C<lgetxattr> for this -file, I<or> 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<guestfs_lstatlist> for a similarly efficient call -for getting standard stats." }; - - { defaults with - name = "readlinklist"; added = (1, 0, 77); - style = RStringList "links", [Pathname "path"; FilenameList "names"], []; - shortdesc = "readlink on multiple files"; - longdesc = "\ -This call allows you to do a C<readlink> operation -on multiple files, where all files are in the directory C<path>. -C<names> 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<names> list. Each string is the -value of the symbolic link. - -If the L<readlink(2)> 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 L<readlink(2)> 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"; added = (0, 0, 4); - style = RStringList "listing", [Pathname "directory"], []; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir"; "/ls"]; - ["touch"; "/ls/new"]; - ["touch"; "/ls/newer"]; - ["touch"; "/ls/newest"]; - ["ls"; "/ls"]], - "is_string_list (ret, 3, \"new\", \"newer\", \"newest\")"), [] - ]; - shortdesc = "list the files in a directory"; - longdesc = "\ -List the files in F<directory> (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"; added = (1, 19, 35); - style = RString "databuf", [Int64 "valueh"], []; - optional = Some "hivex"; - shortdesc = "return the data field from the (key, datatype, data) tuple"; - longdesc = "\ -This calls C<guestfs_hivex_value_value> (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." }; - - { defaults with - name = "disk_format"; added = (1, 19, 38); - style = RString "format", [String "filename"], []; - tests = [ - InitEmpty, Always, TestResultString ( - [["disk_format"; "../../test-data/blank-disks/blank-disk-1s.raw"]], "raw"), []; - InitEmpty, Always, TestResultString ( - [["disk_format"; "../../test-data/blank-disks/blank-disk-1s.qcow2"]], "qcow2"), []; - InitEmpty, Always, TestResultString ( - [["disk_format"; "../../test-data/blank-disks/blank-disk-1K.raw"]], "raw"), []; - InitEmpty, Always, TestResultString ( - [["disk_format"; "../../test-data/blank-disks/blank-disk-1K.qcow2"]], "qcow2"), []; - InitEmpty, Always, TestResultString ( - [["disk_format"; "../../test-data/blank-disks/blank-disk-1M.raw"]], "raw"), []; - InitEmpty, Always, TestResultString ( - [["disk_format"; "../../test-data/blank-disks/blank-disk-1M.qcow2"]], "qcow2"), []; - InitEmpty, Always, TestResultString ( - [["disk_format"; "../../test-data/blank-disks/blank-disk-with-backing.qcow2"]], "qcow2"), []; - ]; - shortdesc = "detect the disk format of a disk image"; - longdesc = "\ -Detect and return the format of the disk image called F<filename>. -F<filename> can also be a host device, etc. If the format of the -image could not be detected, then C<\"unknown\"> is returned. - -Note that detecting the disk format can be insecure under some -circumstances. See L<guestfs(3)/CVE-2010-3851>. - -See also: L<guestfs(3)/DISK IMAGE FORMATS>" }; - - { defaults with - name = "disk_virtual_size"; added = (1, 19, 39); - style = RInt64 "size", [String "filename"], []; - tests = [ - InitEmpty, Always, TestResult ( - [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1s.raw"]], "ret == 512"), []; - InitEmpty, Always, TestResult ( - [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1s.qcow2"]], "ret == 512"), []; - InitEmpty, Always, TestResult ( - [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1K.raw"]], "ret == 1024"), []; - InitEmpty, Always, TestResult ( - [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1K.qcow2"]], "ret == 1024"), []; - InitEmpty, Always, TestResult ( - [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1M.raw"]], "ret == 1024*1024"), []; - InitEmpty, Always, TestResult ( - [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1M.qcow2"]], "ret == 1024*1024"), []; - InitEmpty, Always, TestResult ( - [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-with-backing.qcow2"]], "ret == 1024*1024"), []; - ]; - shortdesc = "return virtual size of a disk"; - longdesc = "\ -Detect and return the virtual size in bytes of the disk image -called F<filename>. - -Note that detecting disk features can be insecure under some -circumstances. See L<guestfs(3)/CVE-2010-3851>." }; - - { defaults with - name = "disk_has_backing_file"; added = (1, 19, 39); - style = RBool "backingfile", [String "filename"], []; - tests = [ - InitEmpty, Always, TestResultFalse ( - [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1s.raw"]]), []; - InitEmpty, Always, TestResultFalse ( - [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1s.qcow2"]]), []; - InitEmpty, Always, TestResultFalse ( - [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1K.raw"]]), []; - InitEmpty, Always, TestResultFalse ( - [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1K.qcow2"]]), []; - InitEmpty, Always, TestResultFalse ( - [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1M.raw"]]), []; - InitEmpty, Always, TestResultFalse ( - [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1M.qcow2"]]), []; - InitEmpty, Always, TestResultTrue ( - [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-with-backing.qcow2"]]), []; - ]; - shortdesc = "return whether disk has a backing file"; - longdesc = "\ -Detect and return whether the disk image F<filename> has a -backing file. - -Note that detecting disk features can be insecure under some -circumstances. See L<guestfs(3)/CVE-2010-3851>." }; - - { defaults with - name = "remove_drive"; added = (1, 19, 49); - style = RErr, [String "label"], []; - blocking = false; - shortdesc = "remove a disk image"; - longdesc = "\ -This function is conceptually the opposite of C<guestfs_add_drive_opts>. -It removes the drive that was previously added with label C<label>. - -Note that in order to remove drives, you have to add them with -labels (see the optional C<label> argument to C<guestfs_add_drive_opts>). -If you didn't use a label, then they cannot be removed. - -You can call this function before or after launching the handle. -If called after launch, if the backend supports it, we try to hot -unplug the drive: see L<guestfs(3)/HOTPLUGGING>. The disk B<must not> -be in use (eg. mounted) when you do this. We try to detect if the -disk is in use and stop you from doing this." }; - - { defaults with - name = "set_libvirt_supported_credentials"; added = (1, 19, 52); - style = RErr, [StringList "creds"], []; - blocking = false; - shortdesc = "set libvirt credentials supported by calling program"; - longdesc = "\ -Call this function before setting an event handler for -C<GUESTFS_EVENT_LIBVIRT_AUTH>, to supply the list of credential types -that the program knows how to process. - -The C<creds> list must be a non-empty list of strings. -Possible strings are: - -=over 4 - -=item C<username> - -=item C<authname> - -=item C<language> - -=item C<cnonce> - -=item C<passphrase> - -=item C<echoprompt> - -=item C<noechoprompt> - -=item C<realm> - -=item C<external> - -=back - -See libvirt documentation for the meaning of these credential types. - -See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; - - { defaults with - name = "get_libvirt_requested_credentials"; added = (1, 19, 52); - style = RStringList "creds", [], []; - blocking = false; - shortdesc = "get list of credentials requested by libvirt"; - longdesc = "\ -This should only be called during the event callback -for events of type C<GUESTFS_EVENT_LIBVIRT_AUTH>. - -Return the list of credentials requested by libvirt. Possible -values are a subset of the strings provided when you called -C<guestfs_set_libvirt_supported_credentials>. - -See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; - - { defaults with - name = "get_libvirt_requested_credential_prompt"; added = (1, 19, 52); - style = RString "prompt", [Int "index"], []; - blocking = false; - shortdesc = "prompt of i'th requested credential"; - longdesc = "\ -Get the prompt (provided by libvirt) for the C<index>'th -requested credential. If libvirt did not provide a prompt, -this returns the empty string C<\"\">. - -See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; - - { defaults with - name = "get_libvirt_requested_credential_challenge"; added = (1, 19, 52); - style = RString "challenge", [Int "index"], []; - blocking = false; - shortdesc = "challenge of i'th requested credential"; - longdesc = "\ -Get the challenge (provided by libvirt) for the C<index>'th -requested credential. If libvirt did not provide a challenge, -this returns the empty string C<\"\">. - -See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; - - { defaults with - name = "get_libvirt_requested_credential_defresult"; added = (1, 19, 52); - style = RString "defresult", [Int "index"], []; - blocking = false; - shortdesc = "default result of i'th requested credential"; - longdesc = "\ -Get the default result (provided by libvirt) for the C<index>'th -requested credential. If libvirt did not provide a default result, -this returns the empty string C<\"\">. - -See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; - - { defaults with - name = "set_libvirt_requested_credential"; added = (1, 19, 52); - style = RErr, [Int "index"; BufferIn "cred"], []; - blocking = false; - shortdesc = "pass requested credential back to libvirt"; - longdesc = "\ -After requesting the C<index>'th credential from the user, -call this function to pass the answer back to libvirt. - -See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; - - { defaults with - name = "parse_environment"; added = (1, 19, 53); - style = RErr, [], []; - blocking = false; - shortdesc = "parse the environment and set handle flags accordingly"; - longdesc = "\ -Parse the program's environment and set flags in the handle -accordingly. For example if C<LIBGUESTFS_DEBUG=1> then the -'verbose' flag is set in the handle. - -I<Most programs do not need to call this>. It is done implicitly -when you call C<guestfs_create>. - -See L<guestfs(3)/ENVIRONMENT VARIABLES> for a list of environment -variables that can affect libguestfs handles. See also -L<guestfs(3)/guestfs_create_flags>, and -C<guestfs_parse_environment_list>." }; - - { defaults with - name = "parse_environment_list"; added = (1, 19, 53); - style = RErr, [StringList "environment"], []; - blocking = false; - shortdesc = "parse the environment and set handle flags accordingly"; - longdesc = "\ -Parse the list of strings in the argument C<environment> -and set flags in the handle accordingly. -For example if C<LIBGUESTFS_DEBUG=1> is a string in the list, -then the 'verbose' flag is set in the handle. - -This is the same as C<guestfs_parse_environment> except that -it parses an explicit list of strings instead of the program's -environment." }; - - { defaults with - name = "set_tmpdir"; added = (1, 19, 58); - style = RErr, [OptString "tmpdir"], []; - fish_alias = ["tmpdir"]; config_only = true; - blocking = false; - shortdesc = "set the temporary directory"; - longdesc = "\ -Set the directory used by the handle to store temporary files. - -The environment variables C<LIBGUESTFS_TMPDIR> and C<TMPDIR> -control the default value: If C<LIBGUESTFS_TMPDIR> is set, then -that is the default. Else if C<TMPDIR> is set, then that is -the default. Else F</tmp> is the default." }; - - { defaults with - name = "get_tmpdir"; added = (1, 19, 58); - style = RString "tmpdir", [], []; - blocking = false; - shortdesc = "get the temporary directory"; - longdesc = "\ -Get the directory used by the handle to store temporary files." }; - - { defaults with - name = "set_cachedir"; added = (1, 19, 58); - style = RErr, [OptString "cachedir"], []; - fish_alias = ["cachedir"]; config_only = true; - blocking = false; - shortdesc = "set the appliance cache directory"; - longdesc = "\ -Set the directory used by the handle to store the appliance -cache, when using a supermin appliance. The appliance is -cached and shared between all handles which have the same -effective user ID. - -The environment variables C<LIBGUESTFS_CACHEDIR> and C<TMPDIR> -control the default value: If C<LIBGUESTFS_CACHEDIR> is set, then -that is the default. Else if C<TMPDIR> is set, then that is -the default. Else F</var/tmp> is the default." }; - - { defaults with - name = "get_cachedir"; added = (1, 19, 58); - style = RString "cachedir", [], []; - blocking = false; - shortdesc = "get the appliance cache directory"; - longdesc = "\ -Get the directory used by the handle to store the appliance cache." }; - - { defaults with - name = "user_cancel"; added = (1, 11, 18); - style = RErr, [], []; - blocking = false; wrapper = false; - shortdesc = "cancel the current upload or download operation"; - longdesc = "\ -This function cancels the current upload or download operation. - -Unlike most other libguestfs calls, this function is signal safe and -thread safe. You can call it from a signal handler or from another -thread, without needing to do any locking. - -The transfer that was in progress (if there is one) will stop shortly -afterwards, and will return an error. The errno (see -L</guestfs_last_errno>) is set to C<EINTR>, so you can test for this -to find out if the operation was cancelled or failed because of -another error. - -No cleanup is performed: for example, if a file was being uploaded -then after cancellation there may be a partially uploaded file. It is -the caller's responsibility to clean up if necessary. - -There are two common places that you might call C<guestfs_user_cancel>: - -In an interactive text-based program, you might call it from a -C<SIGINT> signal handler so that pressing C<^C> cancels the current -operation. (You also need to call L</guestfs_set_pgroup> so that -child processes don't receive the C<^C> signal). - -In a graphical program, when the main thread is displaying a progress -bar with a cancel button, wire up the cancel button to call this -function." }; - - { defaults with - name = "set_program"; added = (1, 21, 29); - style = RErr, [String "program"], []; - fish_alias = ["program"]; - blocking = false; - shortdesc = "set the program name"; - longdesc = "\ -Set the program name. This is an informative string which the -main program may optionally set in the handle. - -When the handle is created, the program name in the handle is -set to the basename from C<argv[0]>. The program name can never -be C<NULL>." }; - - { defaults with - name = "get_program"; added = (1, 21, 29); - style = RConstString "program", [], []; - blocking = false; - tests = [ - InitNone, Always, TestRun ( - [["get_program"]]), [] - ]; - shortdesc = "get the program name"; - longdesc = "\ -Get the program name. See C<guestfs_set_program>." }; - - { defaults with - name = "add_drive_scratch"; added = (1, 23, 10); - style = RErr, [Int64 "size"], [OString "name"; OString "label"]; - blocking = false; - fish_alias = ["scratch"]; - shortdesc = "add a temporary scratch drive"; - longdesc = "\ -This command adds a temporary scratch drive to the handle. The -C<size> parameter is the virtual size (in bytes). The scratch -drive is blank initially (all reads return zeroes until you start -writing to it). The drive is deleted when the handle is closed. - -The optional arguments C<name> and C<label> are passed through to -C<guestfs_add_drive>." }; - - { defaults with - name = "journal_get"; added = (1, 23, 11); - style = RStructList ("fields", "xattr"), [], []; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "read the current journal entry"; - longdesc = "\ -Read the current journal entry. This returns all the fields -in the journal as a set of C<(attrname, attrval)> pairs. The -C<attrname> is the field name (a string). - -The C<attrval> is the field value (a binary blob, often but -not always a string). Please note that C<attrval> is a byte -array, I<not> a \\0-terminated C string. - -The length of data may be truncated to the data threshold -(see: C<guestfs_journal_set_data_threshold>, -C<guestfs_journal_get_data_threshold>). - -If you set the data threshold to unlimited (C<0>) then this call -can read a journal entry of any size, ie. it is not limited by -the libguestfs protocol." }; - - { defaults with - name = "disk_create"; added = (1, 25, 31); - style = RErr, [String "filename"; String "format"; Int64 "size"], [OString "backingfile"; OString "backingformat"; OString "preallocation"; OString "compat"; OInt "clustersize"]; - test_excuse = "tests in tests/create subdirectory"; - shortdesc = "create a blank disk image"; - longdesc = "\ -Create a blank disk image called F<filename> (a host file) -with format C<format> (usually C<raw> or C<qcow2>). -The size is C<size> bytes. - -If used with the optional C<backingfile> parameter, then a snapshot -is created on top of the backing file. In this case, C<size> must -be passed as C<-1>. The size of the snapshot is the same as the -size of the backing file, which is discovered automatically. You -are encouraged to also pass C<backingformat> to describe the format -of C<backingfile>. - -If F<filename> refers to a block device, then the device is -formatted. The C<size> is ignored since block devices have an -intrinsic size. - -The other optional parameters are: - -=over 4 - -=item C<preallocation> - -If format is C<raw>, then this can be either C<off> (or C<sparse>) -or C<full> to create a sparse or fully allocated file respectively. -The default is C<off>. - -If format is C<qcow2>, then this can be C<off> (or C<sparse>), -C<metadata> or C<full>. Preallocating metadata can be faster -when doing lots of writes, but uses more space. -The default is C<off>. - -=item C<compat> - -C<qcow2> only: -Pass the string C<1.1> to use the advanced qcow2 format supported -by qemu E<ge> 1.1. - -=item C<clustersize> - -C<qcow2> only: -Change the qcow2 cluster size. The default is 65536 (bytes) and -this setting may be any power of two between 512 and 2097152. - -=back - -Note that this call does not add the new disk to the handle. You -may need to call C<guestfs_add_drive_opts> separately." }; - - { defaults with - name = "get_backend_settings"; added = (1, 25, 24); - style = RStringList "settings", [], []; - blocking = false; - tests = [ - InitNone, Always, TestRun ( - [["get_backend_settings"]]), [] - ]; - shortdesc = "get per-backend settings"; - longdesc = "\ -Return the current backend settings. - -This call returns all backend settings strings. If you want to -find a single backend setting, see C<guestfs_get_backend_setting>. - -See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; - - { defaults with - name = "set_backend_settings"; added = (1, 25, 24); - style = RErr, [StringList "settings"], []; - config_only = true; - blocking = false; - shortdesc = "replace per-backend settings strings"; - longdesc = "\ -Set a list of zero or more settings which are passed through to -the current backend. Each setting is a string which is interpreted -in a backend-specific way, or ignored if not understood by the -backend. - -The default value is an empty list, unless the environment -variable C<LIBGUESTFS_BACKEND_SETTINGS> was set when the handle -was created. This environment variable contains a colon-separated -list of settings. - -This call replaces all backend settings. If you want to replace -a single backend setting, see C<guestfs_set_backend_setting>. -If you want to clear a single backend setting, see -C<guestfs_clear_backend_setting>. - -See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; - - { defaults with - name = "get_backend_setting"; added = (1, 27, 2); - style = RString "val", [String "name"], []; - blocking = false; - shortdesc = "get a single per-backend settings string"; - longdesc = "\ -Find a backend setting string which is either C<\"name\"> or -begins with C<\"name=\">. If C<\"name\">, this returns the -string C<\"1\">. If C<\"name=\">, this returns the part -after the equals sign (which may be an empty string). - -If no such setting is found, this function throws an error. -The errno (see C<guestfs_last_errno>) will be C<ESRCH> in this -case. - -See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; - - { defaults with - name = "set_backend_setting"; added = (1, 27, 2); - style = RErr, [String "name"; String "val"], []; - config_only = true; - blocking = false; - shortdesc = "set a single per-backend settings string"; - longdesc = "\ -Append C<\"name=value\"> to the backend settings string list. -However if a string already exists matching C<\"name\"> -or beginning with C<\"name=\">, then that setting is replaced. - -See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; - - { defaults with - name = "clear_backend_setting"; added = (1, 27, 2); - style = RInt "count", [String "name"], []; - config_only = true; - blocking = false; - shortdesc = "remove a single per-backend settings string"; - longdesc = "\ -If there is a backend setting string matching C<\"name\"> or -beginning with C<\"name=\">, then that string is removed -from the backend settings. - -This call returns the number of strings which were removed -(which may be 0, 1 or greater than 1). - -See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; - - { defaults with - name = "stat"; added = (1, 9, 2); - style = RStruct ("statbuf", "stat"), [Pathname "path"], []; - deprecated_by = Some "statns"; - tests = [ - InitISOFS, Always, TestResult ( - [["stat"; "/empty"]], "ret->size == 0"), [] - ]; - shortdesc = "get file information"; - longdesc = "\ -Returns file information for the given C<path>. - -This is the same as the L<stat(2)> system call." }; - - { defaults with - name = "lstat"; added = (1, 9, 2); - style = RStruct ("statbuf", "stat"), [Pathname "path"], []; - deprecated_by = Some "lstatns"; - tests = [ - InitISOFS, Always, TestResult ( - [["lstat"; "/empty"]], "ret->size == 0"), [] - ]; - shortdesc = "get file information for a symbolic link"; - longdesc = "\ -Returns file information for the given C<path>. - -This is the same as C<guestfs_stat> except that if C<path> -is a symbolic link, then the link is stat-ed, not the file it -refers to. - -This is the same as the L<lstat(2)> system call." }; - - { defaults with - name = "c_pointer"; added = (1, 29, 17); - style = RInt64 "ptr", [], []; - fish_output = Some FishOutputHexadecimal; - tests = [ - InitNone, Always, TestRun ( - [["c_pointer"]]), [] - ]; - shortdesc = "return the C pointer to the guestfs_h handle"; - longdesc = "\ -In non-C language bindings, this allows you to retrieve the underlying -C pointer to the handle (ie. C<guestfs_h *>). The purpose of this is -to allow other libraries to interwork with libguestfs." }; - - { defaults with - name = "copy_in"; added = (1, 29, 24); - style = RErr, [String "localpath"; Pathname "remotedir"], []; - visibility = VPublicNoFish; - shortdesc = "copy local files or directories into an image"; - longdesc = "\ -C<guestfs_copy_in> copies local files or directories recursively into -the disk image, placing them in the directory called C<remotedir> -(which must exist). - -Wildcards cannot be used." }; - - { defaults with - name = "copy_out"; added = (1, 29, 24); - style = RErr, [Pathname "remotepath"; String "localdir"], []; - visibility = VPublicNoFish; - shortdesc = "copy remote files or directories out of an image"; - longdesc = "\ -C<guestfs_copy_out> copies remote files or directories recursively -out of the disk image, placing them on the host disk in a local -directory called C<localdir> (which must exist). - -To download to the current directory, use C<.> as in: - - C<guestfs_copy_out> /home . - -Wildcards cannot be used." }; - - { defaults with - name = "set_identifier"; added = (1, 31, 14); - style = RErr, [String "identifier"], []; - fish_alias = ["identifier"]; - blocking = false; - shortdesc = "set the handle identifier"; - longdesc = "\ -This is an informative string which the caller may optionally -set in the handle. It is printed in various places, allowing -the current handle to be identified in debugging output. - -One important place is when tracing is enabled. If the -identifier string is not an empty string, then trace messages -change from this: - - libguestfs: trace: get_tmpdir - libguestfs: trace: get_tmpdir = \"/tmp\" - -to this: - - libguestfs: trace: ID: get_tmpdir - libguestfs: trace: ID: get_tmpdir = \"/tmp\" - -where C<ID> is the identifier string set by this call. - -The identifier must only contain alphanumeric ASCII characters, -underscore and minus sign. The default is the empty string. - -See also C<guestfs_set_program>, C<guestfs_set_trace>, -C<guestfs_get_identifier>." }; - - { defaults with - name = "get_identifier"; added = (1, 31, 14); - style = RConstString "identifier", [], []; - blocking = false; - tests = [ - InitNone, Always, TestRun ( - [["get_identifier"]]), [] - ]; - shortdesc = "get the handle identifier"; - longdesc = "\ -Get the handle identifier. See C<guestfs_set_identifier>." }; - - { defaults with - name = "available"; added = (1, 0, 80); - style = RErr, [StringList "groups"], []; - tests = [ - InitNone, Always, TestRun [["available"; ""]], [] - ]; - shortdesc = "test availability of some parts of the API"; - longdesc = "\ -This command is used to check the availability of some -groups of functionality in the appliance, which not all builds of -the libguestfs appliance will be able to provide. - -The libguestfs groups, and the functions that those -groups correspond to, are listed in L<guestfs(3)/AVAILABILITY>. -You can also fetch this list at runtime by calling -C<guestfs_available_all_groups>. - -The argument C<groups> is a list of group names, eg: -C<[\"inotify\", \"augeas\"]> would check for the availability of -the Linux inotify functions and Augeas (configuration file -editing) functions. - -The command returns no error if I<all> requested groups are available. - -It fails with an error if one or more of the requested -groups is unavailable in the appliance. - -If an unknown group name is included in the -list of groups then an error is always returned. - -I<Notes:> - -=over 4 - -=item * - -C<guestfs_feature_available> is the same as this call, but -with a slightly simpler to use API: that call returns a boolean -true/false instead of throwing an error. - -=item * - -You must call C<guestfs_launch> before calling this function. - -The reason is because we don't know what groups are -supported by the appliance/daemon until it is running and can -be queried. - -=item * - -If a group of functions is available, this does not necessarily -mean that they will work. You still have to check for errors -when calling individual API functions even if they are -available. - -=item * - -It is usually the job of distro packagers to build -complete functionality into the libguestfs appliance. -Upstream libguestfs, if built from source with all -requirements satisfied, will support everything. - -=item * - -This call was added in version C<1.0.80>. In previous -versions of libguestfs all you could do would be to speculatively -execute a command to find out if the daemon implemented it. -See also C<guestfs_version>. - -=back - -See also C<guestfs_filesystem_available>." }; - - { defaults with - name = "feature_available"; added = (1, 21, 26); - style = RBool "isavailable", [StringList "groups"], []; - tests = [ - InitNone, Always, TestResultTrue [["feature_available"; ""]], [] - ]; - shortdesc = "test availability of some parts of the API"; - longdesc = "\ -This is the same as C<guestfs_available>, but unlike that -call it returns a simple true/false boolean result, instead -of throwing an exception if a feature is not found. For -other documentation see C<guestfs_available>." }; - - { defaults with - name = "get_sockdir"; added = (1, 33, 8); - style = RString "sockdir", [], []; - blocking = false; - shortdesc = "get the temporary directory for sockets"; - longdesc = "\ -Get the directory used by the handle to store temporary socket files. - -This is different from C<guestfs_tmpdir>, as we need shorter paths for -sockets (due to the limited buffers of filenames for UNIX sockets), -and C<guestfs_tmpdir> may be too long for them. - -The environment variable C<XDG_RUNTIME_DIR> controls the default -value: If C<XDG_RUNTIME_DIR> is set, then that is the default. -Else F</tmp> is the default." }; - - { defaults with - name = "filesystem_walk"; added = (1, 33, 39); - style = RStructList ("dirents", "tsk_dirent"), [Mountable "device";], []; - optional = Some "libtsk"; - progress = true; cancellable = true; - shortdesc = "walk through the filesystem content"; - longdesc = "\ -Walk through the internal structures of a disk partition -(eg. F</dev/sda1>) in order to return a list of all the files -and directories stored within. - -It is not necessary to mount the disk partition to run this command. - -All entries in the filesystem are returned. This function can list deleted -or unaccessible files. The entries are I<not> sorted. - -The C<tsk_dirent> structure contains the following fields. - -=over 4 - -=item 'tsk_inode' - -Filesystem reference number of the node. It migh be C<0> -if the node has been deleted. - -=item 'tsk_type' - -Basic file type information. -See below for a detailed list of values. - -=item 'tsk_size' - -File size in bytes. It migh be C<-1> -if the node has been deleted. - -=item 'tsk_name' - -The file path relative to its directory. - -=item 'tsk_flags' - -Bitfield containing extra information regarding the entry. -It contains the logical OR of the following values: - -=over 4 - -=item 0x0001 - -If set to C<1>, the file is allocated and visible within the filesystem. -Otherwise, the file has been deleted. -Under certain circumstances, the function C<download_inode> -can be used to recover deleted files. - -=item 0x0002 - -Filesystem such as NTFS and Ext2 or greater, separate the file name -from the metadata structure. -The bit is set to C<1> when the file name is in an unallocated state -and the metadata structure is in an allocated one. -This generally implies the metadata has been reallocated to a new file. -Therefore, information such as file type, file size, timestamps, -number of links and symlink target might not correspond -with the ones of the original deleted entry. - -=item 0x0004 - -The bit is set to C<1> when the file is compressed using filesystem -native compression support (NTFS). The API is not able to detect -application level compression. - -=back - -=item 'tsk_atime_sec' - -=item 'tsk_atime_nsec' - -=item 'tsk_mtime_sec' - -=item 'tsk_mtime_nsec' - -=item 'tsk_ctime_sec' - -=item 'tsk_ctime_nsec' - -=item 'tsk_crtime_sec' - -=item 'tsk_crtime_nsec' - -Respectively, access, modification, last status change and creation -time in Unix format in seconds and nanoseconds. - -=item 'tsk_nlink' - -Number of file names pointing to this entry. - -=item 'tsk_link' - -If the entry is a symbolic link, this field will contain the path -to the target file. - -=back - -The C<tsk_type> field will contain one of the following characters: - -=over 4 - -=item 'b' - -Block special - -=item 'c' - -Char special - -=item 'd' - -Directory - -=item 'f' - -FIFO (named pipe) - -=item 'l' - -Symbolic link - -=item 'r' - -Regular file - -=item 's' - -Socket - -=item 'h' - -Shadow inode (Solaris) - -=item 'w' - -Whiteout inode (BSD) - -=item 'u' - -Unknown file type - -=back" }; - - { defaults with - name = "find_inode"; added = (1, 35, 6); - style = RStructList ("dirents", "tsk_dirent"), [Mountable "device"; Int64 "inode";], []; - optional = Some "libtsk"; - progress = true; cancellable = true; - shortdesc = "search the entries associated to the given inode"; - longdesc = "\ -Searches all the entries associated with the given inode. - -For each entry, a C<tsk_dirent> structure is returned. -See C<filesystem_walk> for more information about C<tsk_dirent> structures." }; - - { defaults with - name = "inspect_get_windows_software_hive"; added = (1, 35, 26); - style = RString "path", [Mountable "root"], []; - shortdesc = "get the path of the Windows software hive"; - longdesc = "\ -This returns the path to the hive (binary Windows Registry file) -corresponding to HKLM\\SOFTWARE. - -This call assumes that the guest is Windows and that the guest -has a software hive file with the right name. If this is not the -case then an error is returned. This call does not check that the -hive is a valid Windows Registry hive. - -You can use C<guestfs_hivex_open> to read or write to the hive. - -Please read L<guestfs(3)/INSPECTION> for more details." }; - - { defaults with - name = "inspect_get_windows_system_hive"; added = (1, 35, 26); - style = RString "path", [Mountable "root"], []; - shortdesc = "get the path of the Windows system hive"; - longdesc = "\ -This returns the path to the hive (binary Windows Registry file) -corresponding to HKLM\\SYSTEM. - -This call assumes that the guest is Windows and that the guest -has a system hive file with the right name. If this is not the -case then an error is returned. This call does not check that the -hive is a valid Windows Registry hive. - -You can use C<guestfs_hivex_open> to read or write to the hive. - -Please read L<guestfs(3)/INSPECTION> for more details." }; - -] + Actions_internal_tests.test_support_functions @ + Actions_core.non_daemon_functions @ + Actions_core_deprecated.non_daemon_functions @ + Actions_debug.non_daemon_functions @ + Actions_hivex.non_daemon_functions @ + Actions_inspection.non_daemon_functions @ + Actions_inspection_deprecated.non_daemon_functions @ + Actions_properties.non_daemon_functions @ + Actions_properties_deprecated.non_daemon_functions @ + Actions_tsk.non_daemon_functions (* daemon_functions are any functions which cause some action * to take place in the daemon. *) -let daemon_functions = [ - { defaults with - name = "mount"; added = (0, 0, 3); - style = RErr, [Mountable "mountable"; String "mountpoint"], []; - proc_nr = Some 1; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "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 F</dev/sda>, F</dev/sdb> and so on, as they were added to -the guest. If those block devices contain partitions, they will have -the usual names (eg. F</dev/sda1>). Also LVM F</dev/VG/LV>-style -names can be used, or 'mountable' strings returned by -C<guestfs_list_filesystems> or C<guestfs_inspect_get_mountpoints>. - -The rules are the same as for L<mount(2)>: A filesystem must -first be mounted on F</> 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<sync> and C<noatime>. The C<sync> option greatly slowed -writes and caused many problems for users. If your program -might need to work with older versions of libguestfs, use -C<guestfs_mount_options> instead (using an empty string for the -first parameter if you don't want any options)." }; - - { defaults with - name = "sync"; added = (0, 0, 3); - 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"; added = (0, 0, 3); - style = RErr, [Pathname "path"], []; - proc_nr = Some 3; - tests = [ - InitScratchFS, Always, TestResultTrue ( - [["touch"; "/touch"]; - ["exists"; "/touch"]]), [] - ]; - shortdesc = "update file timestamps or create a new file"; - longdesc = "\ -Touch acts like the L<touch(1)> 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"; added = (0, 0, 4); - style = RString "listing", [Pathname "directory"], []; - proc_nr = Some 5; - test_excuse = "tricky to test because it depends on the exact format of the 'ls -l' command, which changed between Fedora 10 and Fedora 11"; - shortdesc = "list the files in a directory (long format)"; - longdesc = "\ -List the files in F<directory> (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<not> intended that you try to parse the output string." }; - - { defaults with - name = "list_devices"; added = (0, 0, 4); - style = RStringList "devices", [], []; - proc_nr = Some 7; - tests = [ - InitEmpty, Always, TestResult ( - [["list_devices"]], - "is_device_list (ret, 4, \"/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. F</dev/sda>. - -See also C<guestfs_list_filesystems>." }; - - { defaults with - name = "list_partitions"; added = (0, 0, 4); - style = RStringList "partitions", [], []; - proc_nr = Some 8; - tests = [ - InitBasicFS, Always, TestResult ( - [["list_partitions"]], - "is_device_list (ret, 2, \"/dev/sda1\", \"/dev/sdb1\")"), []; - InitEmpty, Always, TestResult ( - [["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"]], - "is_device_list (ret, 4, \"/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. F</dev/sda1> - -This does not return logical volumes. For that you will need to -call C<guestfs_lvs>. - -See also C<guestfs_list_filesystems>." }; - - { defaults with - name = "pvs"; added = (0, 0, 4); - style = RStringList "physvols", [], []; - proc_nr = Some 9; - optional = Some "lvm2"; - tests = [ - InitBasicFSonLVM, Always, TestResult ( - [["pvs"]], "is_device_list (ret, 1, \"/dev/sda1\")"), []; - InitEmpty, Always, TestResult ( - [["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"]], - "is_device_list (ret, 3, \"/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<pvs(8)> command. - -This returns a list of just the device names that contain -PVs (eg. F</dev/sda2>). - -See also C<guestfs_pvs_full>." }; - - { defaults with - name = "vgs"; added = (0, 0, 4); - style = RStringList "volgroups", [], []; - proc_nr = Some 10; - optional = Some "lvm2"; - tests = [ - InitBasicFSonLVM, Always, TestResult ( - [["vgs"]], "is_string_list (ret, 1, \"VG\")"), []; - InitEmpty, Always, TestResult ( - [["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"]], - "is_string_list (ret, 2, \"VG1\", \"VG2\")"), [] - ]; - shortdesc = "list the LVM volume groups (VGs)"; - longdesc = "\ -List all the volumes groups detected. This is the equivalent -of the L<vgs(8)> command. - -This returns a list of just the volume group names that were -detected (eg. C<VolGroup00>). - -See also C<guestfs_vgs_full>." }; - - { defaults with - name = "lvs"; added = (0, 0, 4); - style = RStringList "logvols", [], []; - proc_nr = Some 11; - optional = Some "lvm2"; - tests = [ - InitBasicFSonLVM, Always, TestResult ( - [["lvs"]], - "is_string_list (ret, 1, \"/dev/VG/LV\")"), []; - InitEmpty, Always, TestResult ( - [["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"]], - "is_string_list (ret, 3, \"/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<lvs(8)> command. - -This returns a list of the logical volume device names -(eg. F</dev/VolGroup00/LogVol00>). - -See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>." }; - - { defaults with - name = "pvs_full"; added = (0, 0, 4); - 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<pvs(8)> command. The \"full\" version includes all fields." }; - - { defaults with - name = "vgs_full"; added = (0, 0, 4); - 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<vgs(8)> command. The \"full\" version includes all fields." }; - - { defaults with - name = "lvs_full"; added = (0, 0, 4); - 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<lvs(8)> command. The \"full\" version includes all fields." }; - - { defaults with - name = "aug_init"; added = (0, 0, 7); - style = RErr, [Pathname "root"; Int "flags"], []; - proc_nr = Some 16; - tests = [ - InitBasicFS, Always, TestResultString ( - [["mkdir"; "/etc"]; - ["write"; "/etc/hostname"; "test.example.org"]; - ["aug_init"; "/"; "0"]; - ["aug_get"; "/files/etc/hostname/hostname"]], "test.example.org"), [["aug_close"]] - ]; - 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<guestfs_aug_*> -commands. - -C<root> is the filesystem root. C<root> must not be NULL, -use F</> instead. - -The flags are the same as the flags defined in -E<lt>augeas.hE<gt>, the logical I<or> of the following -integers: - -=over 4 - -=item C<AUG_SAVE_BACKUP> = 1 - -Keep the original file with a C<.augsave> extension. - -=item C<AUG_SAVE_NEWFILE> = 2 - -Save changes into a file with extension C<.augnew>, and -do not overwrite original. Overrides C<AUG_SAVE_BACKUP>. - -=item C<AUG_TYPE_CHECK> = 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<LIBGUESTFS_MEMSIZE> -environment variable or call C<guestfs_set_memsize>. - -=item C<AUG_NO_STDINC> = 8 - -Do not use standard load path for modules. - -=item C<AUG_SAVE_NOOP> = 16 - -Make save a no-op, just record what would have been changed. - -=item C<AUG_NO_LOAD> = 32 - -Do not load the tree in C<guestfs_aug_init>. - -=back - -To close the handle, you can call C<guestfs_aug_close>. - -To find out more about Augeas, see L<http://augeas.net/>." }; - - { defaults with - name = "aug_close"; added = (0, 0, 7); - style = RErr, [], []; - proc_nr = Some 26; - 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<guestfs_aug_init> again before you can use any other -Augeas functions." }; - - { defaults with - name = "aug_defvar"; added = (0, 0, 7); - style = RInt "nrnodes", [String "name"; OptString "expr"], []; - proc_nr = Some 17; - shortdesc = "define an Augeas variable"; - longdesc = "\ -Defines an Augeas variable C<name> whose value is the result -of evaluating C<expr>. If C<expr> is NULL, then C<name> is -undefined. - -On success this returns the number of nodes in C<expr>, or -C<0> if C<expr> evaluates to something which is not a nodeset." }; - - { defaults with - name = "aug_defnode"; added = (0, 0, 7); - style = RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"], []; - proc_nr = Some 18; - shortdesc = "define an Augeas node"; - longdesc = "\ -Defines a variable C<name> whose value is the result of -evaluating C<expr>. - -If C<expr> evaluates to an empty nodeset, a node is created, -equivalent to calling C<guestfs_aug_set> C<expr>, C<value>. -C<name> 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"; added = (0, 0, 7); - style = RString "val", [String "augpath"], []; - proc_nr = Some 19; - shortdesc = "look up the value of an Augeas path"; - longdesc = "\ -Look up the value associated with C<path>. If C<path> -matches exactly one node, the C<value> is returned." }; - - { defaults with - name = "aug_set"; added = (0, 0, 7); - style = RErr, [String "augpath"; String "val"], []; - proc_nr = Some 20; - tests = [ - InitBasicFS, Always, TestResultString ( - [["mkdir"; "/etc"]; - ["write"; "/etc/hostname"; "test.example.org"]; - ["aug_init"; "/"; "0"]; - ["aug_set"; "/files/etc/hostname/hostname"; "replace.example.com"]; - ["aug_get"; "/files/etc/hostname/hostname"]], "replace.example.com"), [["aug_close"]] - ]; - shortdesc = "set Augeas path to value"; - longdesc = "\ -Set the value associated with C<path> to C<val>. - -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<guestfs_aug_clear> call." }; - - { defaults with - name = "aug_insert"; added = (0, 0, 7); - style = RErr, [String "augpath"; String "label"; Bool "before"], []; - proc_nr = Some 21; - tests = [ - InitBasicFS, Always, TestResultString ( - [["mkdir"; "/etc"]; - ["write"; "/etc/hosts"; ""]; - ["aug_init"; "/"; "0"]; - ["aug_insert"; "/files/etc/hosts"; "1"; "false"]; - ["aug_set"; "/files/etc/hosts/1/ipaddr"; "127.0.0.1"]; - ["aug_set"; "/files/etc/hosts/1/canonical"; "foobar"]; - ["aug_clear"; "/files/etc/hosts/1/canonical"]; - ["aug_set"; "/files/etc/hosts/1/canonical"; "localhost"]; - ["aug_save"]; - ["cat"; "/etc/hosts"]], "\n127.0.0.1\tlocalhost\n"), [["aug_close"]] - ]; - shortdesc = "insert a sibling Augeas node"; - longdesc = "\ -Create a new sibling C<label> for C<path>, inserting it into -the tree before or after C<path> (depending on the boolean -flag C<before>). - -C<path> must match exactly one existing node in the tree, and -C<label> must be a label, ie. not contain F</>, C<*> or end -with a bracketed index C<[N]>." }; - - { defaults with - name = "aug_rm"; added = (0, 0, 7); - style = RInt "nrnodes", [String "augpath"], []; - proc_nr = Some 22; - shortdesc = "remove an Augeas path"; - longdesc = "\ -Remove C<path> and all of its children. - -On success this returns the number of entries which were removed." }; - - { defaults with - name = "aug_mv"; added = (0, 0, 7); - style = RErr, [String "src"; String "dest"], []; - proc_nr = Some 23; - shortdesc = "move Augeas node"; - longdesc = "\ -Move the node C<src> to C<dest>. C<src> must match exactly -one node. C<dest> is overwritten if it exists." }; - - { defaults with - name = "aug_match"; added = (0, 0, 7); - style = RStringList "matches", [String "augpath"], []; - proc_nr = Some 24; - shortdesc = "return Augeas nodes which match augpath"; - longdesc = "\ -Returns a list of paths which match the path expression C<path>. -The returned paths are sufficiently qualified so that they match -exactly one node in the current tree." }; - - { defaults with - name = "aug_save"; added = (0, 0, 7); - style = RErr, [], []; - proc_nr = Some 25; - shortdesc = "write all pending Augeas changes to disk"; - longdesc = "\ -This writes all pending changes to disk. - -The flags which were passed to C<guestfs_aug_init> affect exactly -how files are saved." }; - - { defaults with - name = "aug_load"; added = (0, 0, 7); - style = RErr, [], []; - proc_nr = Some 27; - shortdesc = "load files into the tree"; - longdesc = "\ -Load files into the tree. - -See C<aug_load> in the Augeas documentation for the full gory -details." }; - - { defaults with - name = "aug_ls"; added = (0, 0, 8); - style = RStringList "matches", [String "augpath"], []; - proc_nr = Some 28; - tests = [ - InitBasicFS, Always, TestResult ( - [["mkdir"; "/etc"]; - ["write"; "/etc/hosts"; "127.0.0.1 localhost"]; - ["aug_init"; "/"; "0"]; - ["aug_ls"; "/files/etc/hosts/1"]], - "is_string_list (ret, 2, \"/files/etc/hosts/1/canonical\", \"/files/etc/hosts/1/ipaddr\")"), [["aug_close"]] - ]; - shortdesc = "list Augeas nodes under augpath"; - longdesc = "\ -This is just a shortcut for listing C<guestfs_aug_match> -C<path/*> and sorting the resulting nodes into alphabetical order." }; - - { defaults with - name = "rm"; added = (0, 0, 8); - style = RErr, [Pathname "path"], []; - proc_nr = Some 29; - tests = [ - InitScratchFS, Always, TestRun - [["mkdir"; "/rm"]; - ["touch"; "/rm/new"]; - ["rm"; "/rm/new"]], []; - InitScratchFS, Always, TestLastFail - [["rm"; "/nosuchfile"]], []; - InitScratchFS, Always, TestLastFail - [["mkdir"; "/rm2"]; - ["rm"; "/rm2"]], [] - ]; - shortdesc = "remove a file"; - longdesc = "\ -Remove the single file C<path>." }; - - { defaults with - name = "rmdir"; added = (0, 0, 8); - style = RErr, [Pathname "path"], []; - proc_nr = Some 30; - tests = [ - InitScratchFS, Always, TestRun - [["mkdir"; "/rmdir"]; - ["rmdir"; "/rmdir"]], []; - InitScratchFS, Always, TestLastFail - [["rmdir"; "/rmdir2"]], []; - InitScratchFS, Always, TestLastFail - [["mkdir"; "/rmdir3"]; - ["touch"; "/rmdir3/new"]; - ["rmdir"; "/rmdir3/new"]], [] - ]; - shortdesc = "remove a directory"; - longdesc = "\ -Remove the single directory C<path>." }; - - { defaults with - name = "rm_rf"; added = (0, 0, 8); - style = RErr, [Pathname "path"], []; - proc_nr = Some 31; - tests = [ - InitScratchFS, Always, TestResultFalse - [["mkdir"; "/rm_rf"]; - ["mkdir"; "/rm_rf/foo"]; - ["touch"; "/rm_rf/foo/bar"]; - ["rm_rf"; "/rm_rf"]; - ["exists"; "/rm_rf"]], [] - ]; - shortdesc = "remove a file or directory recursively"; - longdesc = "\ -Remove the file or directory C<path>, recursively removing the -contents if its a directory. This is like the C<rm -rf> shell -command." }; - - { defaults with - name = "mkdir"; added = (0, 0, 8); - style = RErr, [Pathname "path"], []; - proc_nr = Some 32; - tests = [ - InitScratchFS, Always, TestResultTrue - [["mkdir"; "/mkdir"]; - ["is_dir"; "/mkdir"; ""]], []; - InitScratchFS, Always, TestLastFail - [["mkdir"; "/mkdir2/foo/bar"]], [] - ]; - shortdesc = "create a directory"; - longdesc = "\ -Create a directory named C<path>." }; - - { defaults with - name = "mkdir_p"; added = (0, 0, 8); - style = RErr, [Pathname "path"], []; - proc_nr = Some 33; - tests = [ - InitScratchFS, Always, TestResultTrue - [["mkdir_p"; "/mkdir_p/foo/bar"]; - ["is_dir"; "/mkdir_p/foo/bar"; ""]], []; - InitScratchFS, Always, TestResultTrue - [["mkdir_p"; "/mkdir_p2/foo/bar"]; - ["is_dir"; "/mkdir_p2/foo"; ""]], []; - InitScratchFS, Always, TestResultTrue - [["mkdir_p"; "/mkdir_p3/foo/bar"]; - ["is_dir"; "/mkdir_p3"; ""]], []; - (* Regression tests for RHBZ#503133: *) - InitScratchFS, Always, TestRun - [["mkdir"; "/mkdir_p4"]; - ["mkdir_p"; "/mkdir_p4"]], []; - InitScratchFS, Always, TestLastFail - [["touch"; "/mkdir_p5"]; - ["mkdir_p"; "/mkdir_p5"]], [] - ]; - shortdesc = "create a directory and parents"; - longdesc = "\ -Create a directory named C<path>, creating any parent directories -as necessary. This is like the C<mkdir -p> shell command." }; - - { defaults with - name = "chmod"; added = (0, 0, 8); - style = RErr, [Int "mode"; Pathname "path"], []; - proc_nr = Some 34; - shortdesc = "change file mode"; - longdesc = "\ -Change the mode (permissions) of C<path> to C<mode>. Only -numeric modes are supported. - -I<Note>: When using this command from guestfish, C<mode> -by default would be decimal, unless you prefix it with -C<0> to get octal, ie. use C<0700> not C<700>. - -The mode actually set is affected by the umask." }; - - { defaults with - name = "chown"; added = (0, 0, 8); - style = RErr, [Int "owner"; Int "group"; Pathname "path"], []; - proc_nr = Some 35; - shortdesc = "change file owner and group"; - longdesc = "\ -Change the file owner to C<owner> and group to C<group>. - -Only numeric uid and gid are supported. If you want to use -names, you will need to locate and parse the password file -yourself (Augeas support makes this relatively easy)." }; - - { defaults with - name = "exists"; added = (0, 0, 8); - style = RBool "existsflag", [Pathname "path"], []; - proc_nr = Some 36; - tests = [ - InitISOFS, Always, TestResultTrue ( - [["exists"; "/empty"]]), []; - InitISOFS, Always, TestResultTrue ( - [["exists"; "/directory"]]), [] - ]; - shortdesc = "test if file or directory exists"; - longdesc = "\ -This returns C<true> if and only if there is a file, directory -(or anything) with the given C<path> name. - -See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>." }; - - { defaults with - name = "is_file"; added = (0, 0, 8); - style = RBool "fileflag", [Pathname "path"], [OBool "followsymlinks"]; - proc_nr = Some 37; - once_had_no_optargs = true; - tests = [ - InitISOFS, Always, TestResultTrue ( - [["is_file"; "/known-1"; ""]]), []; - InitISOFS, Always, TestResultFalse ( - [["is_file"; "/directory"; ""]]), []; - InitISOFS, Always, TestResultTrue ( - [["is_file"; "/abssymlink"; "true"]]), [] - ]; - shortdesc = "test if a regular file"; - longdesc = "\ -This returns C<true> if and only if there is a regular file -with the given C<path> name. Note that it returns false for -other objects like directories. - -If the optional flag C<followsymlinks> is true, then a symlink -(or chain of symlinks) that ends with a file also causes the -function to return true. - -See also C<guestfs_stat>." }; - - { defaults with - name = "is_dir"; added = (0, 0, 8); - style = RBool "dirflag", [Pathname "path"], [OBool "followsymlinks"]; - proc_nr = Some 38; - once_had_no_optargs = true; - tests = [ - InitISOFS, Always, TestResultFalse ( - [["is_dir"; "/known-3"; ""]]), []; - InitISOFS, Always, TestResultTrue ( - [["is_dir"; "/directory"; ""]]), [] - ]; - shortdesc = "test if a directory"; - longdesc = "\ -This returns C<true> if and only if there is a directory -with the given C<path> name. Note that it returns false for -other objects like files. - -If the optional flag C<followsymlinks> is true, then a symlink -(or chain of symlinks) that ends with a directory also causes the -function to return true. - -See also C<guestfs_stat>." }; - - { defaults with - name = "pvcreate"; added = (0, 0, 8); - style = RErr, [Device "device"], []; - proc_nr = Some 39; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestResult ( - [["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"]], - "is_device_list (ret, 3, \"/dev/sda1\", \"/dev/sda2\", \"/dev/sda3\")"), [] - ]; - shortdesc = "create an LVM physical volume"; - longdesc = "\ -This creates an LVM physical volume on the named C<device>, -where C<device> should usually be a partition name such -as F</dev/sda1>." }; - - { defaults with - name = "vgcreate"; added = (0, 0, 8); - style = RErr, [String "volgroup"; DeviceList "physvols"], []; - proc_nr = Some 40; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestResult ( - [["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"]], - "is_string_list (ret, 2, \"VG1\", \"VG2\")"), []; - InitEmpty, Always, TestLastFail ( - [["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"; "/foo/bar /dev/sda2"]]), []; - ]; - shortdesc = "create an LVM volume group"; - longdesc = "\ -This creates an LVM volume group called C<volgroup> -from the non-empty list of physical volumes C<physvols>." }; - - { defaults with - name = "lvcreate"; added = (0, 0, 8); - style = RErr, [String "logvol"; String "volgroup"; Int "mbytes"], []; - proc_nr = Some 41; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestResult ( - [["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"]; - ["lvcreate"; "LV4"; "VG2"; "50"]; - ["lvcreate"; "LV5"; "VG2"; "50"]; - ["lvs"]], - "is_string_list (ret, 5, \"/dev/VG1/LV1\", \"/dev/VG1/LV2\", \"/dev/VG2/LV3\", \"/dev/VG2/LV4\", \"/dev/VG2/LV5\")"), [] - ]; - shortdesc = "create an LVM logical volume"; - longdesc = "\ -This creates an LVM logical volume called C<logvol> -on the volume group C<volgroup>, with C<size> megabytes." }; - - { defaults with - name = "sfdisk"; added = (0, 0, 8); - style = RErr, [Device "device"; - Int "cyls"; Int "heads"; Int "sectors"; - StringList "lines"], []; - proc_nr = Some 43; - deprecated_by = Some "part_add"; - shortdesc = "create partitions on a block device"; - longdesc = "\ -This is a direct interface to the L<sfdisk(8)> program for creating -partitions on block devices. - -C<device> should be a block device, for example F</dev/sda>. - -C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads -and sectors on the device, which are passed directly to sfdisk as -the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any -of these, then the corresponding parameter is omitted. Usually for -'large' disks, you can just pass C<0> for these, but for small -(floppy-sized) disks, sfdisk (or rather, the kernel) cannot work -out the right geometry and you will need to tell it. - -C<lines> is a list of lines that we feed to C<sfdisk>. For more -information refer to the L<sfdisk(8)> manpage. - -To create a single partition occupying the whole disk, you would -pass C<lines> as a single element list, when the single element being -the string C<,> (comma). - -See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>, -C<guestfs_part_init>" }; - - { defaults with - name = "write_file"; added = (0, 0, 8); - style = RErr, [Pathname "path"; String "content"; Int "size"], []; - proc_nr = Some 44; - protocol_limit_warning = true; deprecated_by = Some "write"; - (* Regression test for RHBZ#597135. *) - tests = [ - InitScratchFS, Always, TestLastFail - [["write_file"; "/write_file"; "abc"; "10000"]], [] - ]; - shortdesc = "create a file"; - longdesc = "\ -This call creates a file called C<path>. The contents of the -file is the string C<content> (which can contain any 8 bit data), -with length C<size>. - -As a special case, if C<size> is C<0> -then the length is calculated using C<strlen> (so in this case -the content cannot contain embedded ASCII NULs). - -I<NB.> Owing to a bug, writing content containing ASCII NUL -characters does I<not> work, even if the length is specified." }; - - { defaults with - name = "umount"; added = (0, 0, 8); - style = RErr, [Dev_or_Path "pathordevice"], [OBool "force"; OBool "lazyunmount"]; - proc_nr = Some 45; - fish_alias = ["unmount"]; - once_had_no_optargs = true; - tests = [ - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["mounts"]], "is_device_list (ret, 1, \"/dev/sda1\")"), []; - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["umount"; "/"; "false"; "false"]; - ["mounts"]], "is_string_list (ret, 0)"), [] - ]; - shortdesc = "unmount a filesystem"; - longdesc = "\ -This unmounts the given filesystem. The filesystem may be -specified either by its mountpoint (path) or the device which -contains the filesystem." }; - - { defaults with - name = "mounts"; added = (0, 0, 8); - style = RStringList "devices", [], []; - proc_nr = Some 46; - tests = [ - InitScratchFS, Always, TestResult ( - [["mounts"]], "is_device_list (ret, 1, \"/dev/sdb1\")"), [] - ]; - shortdesc = "show mounted filesystems"; - longdesc = "\ -This returns the list of currently mounted filesystems. It returns -the list of devices (eg. F</dev/sda1>, F</dev/VG/LV>). - -Some internal mounts are not shown. - -See also: C<guestfs_mountpoints>" }; - - { defaults with - name = "umount_all"; added = (0, 0, 8); - style = RErr, [], []; - proc_nr = Some 47; - fish_alias = ["unmount-all"]; - tests = [ - InitScratchFS, Always, TestResult ( - [["umount_all"]; - ["mounts"]], "is_string_list (ret, 0)"), []; - (* check that umount_all can unmount nested mounts correctly: *) - InitEmpty, Always, TestResult ( - [["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"]; - ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mkfs"; "ext2"; "/dev/sda2"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mkfs"; "ext2"; "/dev/sda3"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["mkdir"; "/mp1"]; - ["mount"; "/dev/sda2"; "/mp1"]; - ["mkdir"; "/mp1/mp2"]; - ["mount"; "/dev/sda3"; "/mp1/mp2"]; - ["mkdir"; "/mp1/mp2/mp3"]; - ["umount_all"]; - ["mounts"]], "is_string_list (ret, 0)"), [] - ]; - shortdesc = "unmount all filesystems"; - longdesc = "\ -This unmounts all mounted filesystems. - -Some internal mounts are not unmounted by this call." }; - - { defaults with - name = "lvm_remove_all"; added = (0, 0, 8); - style = RErr, [], []; - proc_nr = Some 48; - optional = Some "lvm2"; - shortdesc = "remove all LVM LVs, VGs and PVs"; - longdesc = "\ -This command removes all LVM logical volumes, volume groups -and physical volumes." }; - - { defaults with - name = "file"; added = (1, 9, 1); - style = RString "description", [Dev_or_Path "path"], []; - proc_nr = Some 49; - tests = [ - InitISOFS, Always, TestResultString ( - [["file"; "/empty"]], "empty"), []; - InitISOFS, Always, TestResultString ( - [["file"; "/known-1"]], "ASCII text"), []; - InitISOFS, Always, TestLastFail ( - [["file"; "/notexists"]]), []; - InitISOFS, Always, TestResultString ( - [["file"; "/abssymlink"]], "symbolic link"), []; - InitISOFS, Always, TestResultString ( - [["file"; "/directory"]], "directory"), [] - ]; - shortdesc = "determine file type"; - longdesc = "\ -This call uses the standard L<file(1)> command to determine -the type or contents of the file. - -This call will also transparently look inside various types -of compressed file. - -The exact command which runs is C<file -zb path>. Note in -particular that the filename is not prepended to the output -(the I<-b> option). - -The output depends on the output of the underlying L<file(1)> -command and it can change in future in ways beyond our control. -In other words, the output is not guaranteed by the ABI. - -See also: L<file(1)>, C<guestfs_vfs_type>, C<guestfs_lstat>, -C<guestfs_is_file>, C<guestfs_is_blockdev> (etc), C<guestfs_is_zero>." }; - - { defaults with - name = "command"; added = (1, 9, 1); - style = RString "output", [StringList "arguments"], []; - proc_nr = Some 50; - protocol_limit_warning = true; - tests = [ - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command"]; - ["upload"; "test-command"; "/command/test-command"]; - ["chmod"; "0o755"; "/command/test-command"]; - ["command"; "/command/test-command 1"]], "Result1"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command2"]; - ["upload"; "test-command"; "/command2/test-command"]; - ["chmod"; "0o755"; "/command2/test-command"]; - ["command"; "/command2/test-command 2"]], "Result2\n"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command3"]; - ["upload"; "test-command"; "/command3/test-command"]; - ["chmod"; "0o755"; "/command3/test-command"]; - ["command"; "/command3/test-command 3"]], "\nResult3"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command4"]; - ["upload"; "test-command"; "/command4/test-command"]; - ["chmod"; "0o755"; "/command4/test-command"]; - ["command"; "/command4/test-command 4"]], "\nResult4\n"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command5"]; - ["upload"; "test-command"; "/command5/test-command"]; - ["chmod"; "0o755"; "/command5/test-command"]; - ["command"; "/command5/test-command 5"]], "\nResult5\n\n"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command6"]; - ["upload"; "test-command"; "/command6/test-command"]; - ["chmod"; "0o755"; "/command6/test-command"]; - ["command"; "/command6/test-command 6"]], "\n\nResult6\n\n"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command7"]; - ["upload"; "test-command"; "/command7/test-command"]; - ["chmod"; "0o755"; "/command7/test-command"]; - ["command"; "/command7/test-command 7"]], ""), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command8"]; - ["upload"; "test-command"; "/command8/test-command"]; - ["chmod"; "0o755"; "/command8/test-command"]; - ["command"; "/command8/test-command 8"]], "\n"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command9"]; - ["upload"; "test-command"; "/command9/test-command"]; - ["chmod"; "0o755"; "/command9/test-command"]; - ["command"; "/command9/test-command 9"]], "\n\n"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command10"]; - ["upload"; "test-command"; "/command10/test-command"]; - ["chmod"; "0o755"; "/command10/test-command"]; - ["command"; "/command10/test-command 10"]], "Result10-1\nResult10-2\n"), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/command11"]; - ["upload"; "test-command"; "/command11/test-command"]; - ["chmod"; "0o755"; "/command11/test-command"]; - ["command"; "/command11/test-command 11"]], "Result11-1\nResult11-2"), []; - InitScratchFS, IfNotCrossAppliance, TestLastFail ( - [["mkdir"; "/command12"]; - ["upload"; "test-command"; "/command12/test-command"]; - ["chmod"; "0o755"; "/command12/test-command"]; - ["command"; "/command12/test-command"]]), []; - InitScratchFS, IfNotCrossAppliance, TestResultString ( - [["mkdir"; "/pwd"]; - ["upload"; "test-pwd"; "/pwd/test-pwd"]; - ["chmod"; "0o755"; "/pwd/test-pwd"]; - ["command"; "/pwd/test-pwd"]], "/"), []; - ]; - shortdesc = "run a command from the guest filesystem"; - longdesc = "\ -This call runs a command from the guest filesystem. The -filesystem must be mounted, and must contain a compatible -operating system (ie. something Linux, with the same -or compatible processor architecture). - -The single parameter is an argv-style list of arguments. -The first element is the name of the program to run. -Subsequent elements are parameters. The list must be -non-empty (ie. must contain a program name). Note that -the command runs directly, and is I<not> invoked via -the shell (see C<guestfs_sh>). - -The return value is anything printed to I<stdout> by -the command. - -If the command returns a non-zero exit status, then -this function returns an error message. The error message -string is the content of I<stderr> from the command. - -The C<$PATH> environment variable will contain at least -F</usr/bin> and F</bin>. If you require a program from -another location, you should provide the full path in the -first parameter. - -Shared libraries and data files required by the program -must be available on filesystems which are mounted in the -correct places. It is the caller's responsibility to ensure -all filesystems that are needed are mounted at the right -locations." }; - - { defaults with - name = "command_lines"; added = (1, 9, 1); - style = RStringList "lines", [StringList "arguments"], []; - proc_nr = Some 51; - protocol_limit_warning = true; - tests = [ - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines"]; - ["upload"; "test-command"; "/command_lines/test-command"]; - ["chmod"; "0o755"; "/command_lines/test-command"]; - ["command_lines"; "/command_lines/test-command 1"]], - "is_string_list (ret, 1, \"Result1\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines2"]; - ["upload"; "test-command"; "/command_lines2/test-command"]; - ["chmod"; "0o755"; "/command_lines2/test-command"]; - ["command_lines"; "/command_lines2/test-command 2"]], - "is_string_list (ret, 1, \"Result2\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines3"]; - ["upload"; "test-command"; "/command_lines3/test-command"]; - ["chmod"; "0o755"; "/command_lines3/test-command"]; - ["command_lines"; "/command_lines3/test-command 3"]], - "is_string_list (ret, 2, \"\", \"Result3\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines4"]; - ["upload"; "test-command"; "/command_lines4/test-command"]; - ["chmod"; "0o755"; "/command_lines4/test-command"]; - ["command_lines"; "/command_lines4/test-command 4"]], - "is_string_list (ret, 2, \"\", \"Result4\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines5"]; - ["upload"; "test-command"; "/command_lines5/test-command"]; - ["chmod"; "0o755"; "/command_lines5/test-command"]; - ["command_lines"; "/command_lines5/test-command 5"]], - "is_string_list (ret, 3, \"\", \"Result5\", \"\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines6"]; - ["upload"; "test-command"; "/command_lines6/test-command"]; - ["chmod"; "0o755"; "/command_lines6/test-command"]; - ["command_lines"; "/command_lines6/test-command 6"]], - "is_string_list (ret, 4, \"\", \"\", \"Result6\", \"\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines7"]; - ["upload"; "test-command"; "/command_lines7/test-command"]; - ["chmod"; "0o755"; "/command_lines7/test-command"]; - ["command_lines"; "/command_lines7/test-command 7"]], - "is_string_list (ret, 0)"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines8"]; - ["upload"; "test-command"; "/command_lines8/test-command"]; - ["chmod"; "0o755"; "/command_lines8/test-command"]; - ["command_lines"; "/command_lines8/test-command 8"]], - "is_string_list (ret, 1, \"\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines9"]; - ["upload"; "test-command"; "/command_lines9/test-command"]; - ["chmod"; "0o755"; "/command_lines9/test-command"]; - ["command_lines"; "/command_lines9/test-command 9"]], - "is_string_list (ret, 2, \"\", \"\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines10"]; - ["upload"; "test-command"; "/command_lines10/test-command"]; - ["chmod"; "0o755"; "/command_lines10/test-command"]; - ["command_lines"; "/command_lines10/test-command 10"]], - "is_string_list (ret, 2, \"Result10-1\", \"Result10-2\")"), []; - InitScratchFS, IfNotCrossAppliance, TestResult ( - [["mkdir"; "/command_lines11"]; - ["upload"; "test-command"; "/command_lines11/test-command"]; - ["chmod"; "0o755"; "/command_lines11/test-command"]; - ["command_lines"; "/command_lines11/test-command 11"]], - "is_string_list (ret, 2, \"Result11-1\", \"Result11-2\")"), [] - ]; - shortdesc = "run a command, returning lines"; - longdesc = "\ -This is the same as C<guestfs_command>, but splits the -result into a list of lines. - -See also: C<guestfs_sh_lines>" }; - - { defaults with - name = "statvfs"; added = (1, 9, 2); - style = RStruct ("statbuf", "statvfs"), [Pathname "path"], []; - proc_nr = Some 54; - tests = [ - InitISOFS, Always, TestResult ( - [["statvfs"; "/"]], "ret->namemax == 255"), [] - ]; - shortdesc = "get file system statistics"; - longdesc = "\ -Returns file system statistics for any mounted file system. -C<path> should be a file or directory in the mounted file system -(typically it is the mount point itself, but it doesn't need to be). - -This is the same as the L<statvfs(2)> system call." }; - - { defaults with - name = "tune2fs_l"; added = (1, 9, 2); - style = RHashtable "superblock", [Device "device"], []; - proc_nr = Some 55; - tests = [ - InitScratchFS, Always, TestResult ( - [["tune2fs_l"; "/dev/sdb1"]], - "check_hash (ret, \"Filesystem magic number\", \"0xEF53\") == 0 && "^ - "check_hash (ret, \"Filesystem OS type\", \"Linux\") == 0"), []; - ]; - shortdesc = "get ext2/ext3/ext4 superblock details"; - longdesc = "\ -This returns the contents of the ext2, ext3 or ext4 filesystem -superblock on C<device>. - -It is the same as running C<tune2fs -l device>. See L<tune2fs(8)> -manpage for more details. The list of fields returned isn't -clearly defined, and depends on both the version of C<tune2fs> -that libguestfs was built against, and the filesystem itself." }; - - { defaults with - name = "blockdev_setro"; added = (1, 9, 3); - style = RErr, [Device "device"], []; - proc_nr = Some 56; - tests = [ - InitEmpty, Always, TestResultTrue ( - [["blockdev_setro"; "/dev/sda"]; - ["blockdev_getro"; "/dev/sda"]]), [] - ]; - shortdesc = "set block device to read-only"; - longdesc = "\ -Sets the block device named C<device> to read-only. - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "blockdev_setrw"; added = (1, 9, 3); - style = RErr, [Device "device"], []; - proc_nr = Some 57; - tests = [ - InitEmpty, Always, TestResultFalse ( - [["blockdev_setrw"; "/dev/sda"]; - ["blockdev_getro"; "/dev/sda"]]), [] - ]; - shortdesc = "set block device to read-write"; - longdesc = "\ -Sets the block device named C<device> to read-write. - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "blockdev_getro"; added = (1, 9, 3); - style = RBool "ro", [Device "device"], []; - proc_nr = Some 58; - tests = [ - InitEmpty, Always, TestResultTrue ( - [["blockdev_setro"; "/dev/sda"]; - ["blockdev_getro"; "/dev/sda"]]), [] - ]; - shortdesc = "is block device set to read-only"; - longdesc = "\ -Returns a boolean indicating if the block device is read-only -(true if read-only, false if not). - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "blockdev_getss"; added = (1, 9, 3); - style = RInt "sectorsize", [Device "device"], []; - proc_nr = Some 59; - tests = [ - InitEmpty, Always, TestResult ( - [["blockdev_getss"; "/dev/sda"]], "ret == 512"), [] - ]; - shortdesc = "get sectorsize of block device"; - longdesc = "\ -This returns the size of sectors on a block device. -Usually 512, but can be larger for modern devices. - -(Note, this is not the size in sectors, use C<guestfs_blockdev_getsz> -for that). - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "blockdev_getbsz"; added = (1, 9, 3); - style = RInt "blocksize", [Device "device"], []; - proc_nr = Some 60; - test_excuse = "cannot be tested because output differs depending on page size"; - shortdesc = "get blocksize of block device"; - longdesc = "\ -This returns the block size of a device. - -Note: this is different from both I<size in blocks> and -I<filesystem block size>. Also this setting is not really -used by anything. You should probably not use it for -anything. Filesystems have their own idea about what -block size to choose. - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "blockdev_setbsz"; added = (1, 9, 3); - style = RErr, [Device "device"; Int "blocksize"], []; - proc_nr = Some 61; - deprecated_by = Some "mkfs"; - shortdesc = "set blocksize of block device"; - longdesc = "\ -This call does nothing and has never done anything -because of a bug in blockdev. B<Do not use it.> - -If you need to set the filesystem block size, use the -C<blocksize> option of C<guestfs_mkfs>." }; - - { defaults with - name = "blockdev_getsz"; added = (1, 9, 3); - style = RInt64 "sizeinsectors", [Device "device"], []; - proc_nr = Some 62; - tests = [ - InitEmpty, Always, TestResult ( - [["blockdev_getsz"; "/dev/sda"]], - "ret == INT64_C(2)*1024*1024*1024/512"), [] - ]; - shortdesc = "get total size of device in 512-byte sectors"; - longdesc = "\ -This returns the size of the device in units of 512-byte sectors -(even if the sectorsize isn't 512 bytes ... weird). - -See also C<guestfs_blockdev_getss> for the real sector size of -the device, and C<guestfs_blockdev_getsize64> for the more -useful I<size in bytes>. - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "blockdev_getsize64"; added = (1, 9, 3); - style = RInt64 "sizeinbytes", [Device "device"], []; - proc_nr = Some 63; - tests = [ - InitEmpty, Always, TestResult ( - [["blockdev_getsize64"; "/dev/sda"]], - "ret == INT64_C(2)*1024*1024*1024"), [] - ]; - shortdesc = "get total size of device in bytes"; - longdesc = "\ -This returns the size of the device in bytes. - -See also C<guestfs_blockdev_getsz>. - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "blockdev_flushbufs"; added = (1, 9, 3); - style = RErr, [Device "device"], []; - proc_nr = Some 64; - tests = [ - InitEmpty, Always, TestRun - [["blockdev_flushbufs"; "/dev/sda"]], [] - ]; - shortdesc = "flush device buffers"; - longdesc = "\ -This tells the kernel to flush internal buffers associated -with C<device>. - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "blockdev_rereadpt"; added = (1, 9, 3); - style = RErr, [Device "device"], []; - proc_nr = Some 65; - tests = [ - InitEmpty, Always, TestRun - [["blockdev_rereadpt"; "/dev/sda"]], [] - ]; - shortdesc = "reread partition table"; - longdesc = "\ -Reread the partition table on C<device>. - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "upload"; added = (1, 0, 2); - style = RErr, [FileIn "filename"; Dev_or_Path "remotefilename"], []; - proc_nr = Some 66; - progress = true; cancellable = true; - tests = [ - InitScratchFS, Always, TestResultString ( - (* Pick a file from cwd which isn't likely to change. *) - [["mkdir"; "/upload"]; - ["upload"; "$srcdir/../../COPYING.LIB"; "/upload/COPYING.LIB"]; - ["checksum"; "md5"; "/upload/COPYING.LIB"]], - Digest.to_hex (Digest.file "COPYING.LIB")), [] - ]; - shortdesc = "upload a file from the local machine"; - longdesc = "\ -Upload local file F<filename> to F<remotefilename> on the -filesystem. - -F<filename> can also be a named pipe. - -See also C<guestfs_download>." }; - - { defaults with - name = "download"; added = (1, 0, 2); - style = RErr, [Dev_or_Path "remotefilename"; FileOut "filename"], []; - proc_nr = Some 67; - progress = true; cancellable = true; - tests = [ - InitScratchFS, Always, TestResultString ( - (* Pick a file from cwd which isn't likely to change. *) - [["mkdir"; "/download"]; - ["upload"; "$srcdir/../../COPYING.LIB"; "/download/COPYING.LIB"]; - ["download"; "/download/COPYING.LIB"; "testdownload.tmp"]; - ["upload"; "testdownload.tmp"; "/download/upload"]; - ["checksum"; "md5"; "/download/upload"]], - Digest.to_hex (Digest.file "COPYING.LIB")), [] - ]; - shortdesc = "download a file to the local machine"; - longdesc = "\ -Download file F<remotefilename> and save it as F<filename> -on the local machine. - -F<filename> can also be a named pipe. - -See also C<guestfs_upload>, C<guestfs_cat>." }; - - { defaults with - name = "checksum"; added = (1, 0, 2); - style = RString "checksum", [String "csumtype"; Pathname "path"], []; - proc_nr = Some 68; - tests = [ - InitISOFS, Always, TestResultString ( - [["checksum"; "crc"; "/known-3"]], "2891671662"), []; - InitISOFS, Always, TestLastFail ( - [["checksum"; "crc"; "/notexists"]]), []; - InitISOFS, Always, TestResultString ( - [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c"), []; - InitISOFS, Always, TestResultString ( - [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15"), []; - InitISOFS, Always, TestResultString ( - [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741"), []; - InitISOFS, Always, TestResultString ( - [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30"), []; - InitISOFS, Always, TestResultString ( - [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640"), []; - InitISOFS, Always, TestResultString ( - [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6"), []; - (* Test for RHBZ#579608, absolute symbolic links. *) - InitISOFS, Always, TestResultString ( - [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a"), [] - ]; - shortdesc = "compute MD5, SHAx or CRC checksum of file"; - longdesc = "\ -This call computes the MD5, SHAx or CRC checksum of the -file named C<path>. - -The type of checksum to compute is given by the C<csumtype> -parameter which must have one of the following values: - -=over 4 - -=item C<crc> - -Compute the cyclic redundancy check (CRC) specified by POSIX -for the C<cksum> command. - -=item C<md5> - -Compute the MD5 hash (using the C<md5sum> program). - -=item C<sha1> - -Compute the SHA1 hash (using the C<sha1sum> program). - -=item C<sha224> - -Compute the SHA224 hash (using the C<sha224sum> program). - -=item C<sha256> - -Compute the SHA256 hash (using the C<sha256sum> program). - -=item C<sha384> - -Compute the SHA384 hash (using the C<sha384sum> program). - -=item C<sha512> - -Compute the SHA512 hash (using the C<sha512sum> program). - -=back - -The checksum is returned as a printable string. - -To get the checksum for a device, use C<guestfs_checksum_device>. - -To get the checksums for many files, use C<guestfs_checksums_out>." }; - - { defaults with - name = "tar_in"; added = (1, 0, 3); - style = RErr, [FileIn "tarfile"; Pathname "directory"], [OString "compress"; OBool "xattrs"; OBool "selinux"; OBool "acls"]; - proc_nr = Some 69; - once_had_no_optargs = true; - cancellable = true; - tests = [ - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/tar_in"]; - ["tar_in"; "$srcdir/../../test-data/files/helloworld.tar"; "/tar_in"; "NOARG"; ""; ""; ""]; - ["cat"; "/tar_in/hello"]], "hello\n"), []; - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/tar_in_gz"]; - ["tar_in"; "$srcdir/../../test-data/files/helloworld.tar.gz"; "/tar_in_gz"; "gzip"; ""; ""; ""]; - ["cat"; "/tar_in_gz/hello"]], "hello\n"), []; - InitScratchFS, IfAvailable "xz", TestResultString ( - [["mkdir"; "/tar_in_xz"]; - ["tar_in"; "$srcdir/../../test-data/files/helloworld.tar.xz"; "/tar_in_xz"; "xz"; ""; ""; ""]; - ["cat"; "/tar_in_xz/hello"]], "hello\n"), [] - ]; - shortdesc = "unpack tarfile to directory"; - longdesc = "\ -This command uploads and unpacks local file C<tarfile> into F<directory>. - -The optional C<compress> flag controls compression. If not given, -then the input should be an uncompressed tar file. Otherwise one -of the following strings may be given to select the compression -type of the input file: C<compress>, C<gzip>, C<bzip2>, C<xz>, C<lzop>. -(Note that not all builds of libguestfs will support all of these -compression types). - -The other optional arguments are: - -=over 4 - -=item C<xattrs> - -If set to true, extended attributes are restored from the tar file. - -=item C<selinux> - -If set to true, SELinux contexts are restored from the tar file. - -=item C<acls> - -If set to true, POSIX ACLs are restored from the tar file. - -=back" }; - - { defaults with - name = "tar_out"; added = (1, 0, 3); - style = RErr, [String "directory"; FileOut "tarfile"], [OString "compress"; OBool "numericowner"; OStringList "excludes"; OBool "xattrs"; OBool "selinux"; OBool "acls"]; - proc_nr = Some 70; - once_had_no_optargs = true; - cancellable = true; - shortdesc = "pack directory into tarfile"; - longdesc = "\ -This command packs the contents of F<directory> and downloads -it to local file C<tarfile>. - -The optional C<compress> flag controls compression. If not given, -then the output will be an uncompressed tar file. Otherwise one -of the following strings may be given to select the compression -type of the output file: C<compress>, C<gzip>, C<bzip2>, C<xz>, C<lzop>. -(Note that not all builds of libguestfs will support all of these -compression types). - -The other optional arguments are: - -=over 4 - -=item C<excludes> - -A list of wildcards. Files are excluded if they match any of the -wildcards. - -=item C<numericowner> - -If set to true, the output tar file will contain UID/GID numbers -instead of user/group names. - -=item C<xattrs> - -If set to true, extended attributes are saved in the output tar. - -=item C<selinux> - -If set to true, SELinux contexts are saved in the output tar. - -=item C<acls> - -If set to true, POSIX ACLs are saved in the output tar. - -=back" }; - - { defaults with - name = "tgz_in"; added = (1, 0, 3); - style = RErr, [FileIn "tarball"; Pathname "directory"], []; - proc_nr = Some 71; - deprecated_by = Some "tar_in"; - cancellable = true; - tests = [ - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/tgz_in"]; - ["tgz_in"; "$srcdir/../../test-data/files/helloworld.tar.gz"; "/tgz_in"]; - ["cat"; "/tgz_in/hello"]], "hello\n"), [] - ]; - shortdesc = "unpack compressed tarball to directory"; - longdesc = "\ -This command uploads and unpacks local file C<tarball> (a -I<gzip compressed> tar file) into F<directory>." }; - - { defaults with - name = "tgz_out"; added = (1, 0, 3); - style = RErr, [Pathname "directory"; FileOut "tarball"], []; - proc_nr = Some 72; - deprecated_by = Some "tar_out"; - cancellable = true; - shortdesc = "pack directory into compressed tarball"; - longdesc = "\ -This command packs the contents of F<directory> and downloads -it to local file C<tarball>." }; - - { defaults with - name = "mount_ro"; added = (1, 0, 10); - style = RErr, [Mountable "mountable"; String "mountpoint"], []; - proc_nr = Some 73; - tests = [ - InitBasicFS, Always, TestLastFail ( - [["umount"; "/"; "false"; "false"]; - ["mount_ro"; "/dev/sda1"; "/"]; - ["touch"; "/new"]]), []; - InitBasicFS, Always, TestResultString ( - [["write"; "/new"; "data"]; - ["umount"; "/"; "false"; "false"]; - ["mount_ro"; "/dev/sda1"; "/"]; - ["cat"; "/new"]], "data"), [] - ]; - shortdesc = "mount a guest disk, read-only"; - longdesc = "\ -This is the same as the C<guestfs_mount> command, but it -mounts the filesystem with the read-only (I<-o ro>) flag." }; - - { defaults with - name = "mount_options"; added = (1, 0, 10); - style = RErr, [String "options"; Mountable "mountable"; String "mountpoint"], []; - proc_nr = Some 74; - shortdesc = "mount a guest disk with mount options"; - longdesc = "\ -This is the same as the C<guestfs_mount> command, but it -allows you to set the mount options as for the -L<mount(8)> I<-o> flag. - -If the C<options> parameter is an empty string, then -no options are passed (all options default to whatever -the filesystem uses)." }; - - { defaults with - name = "mount_vfs"; added = (1, 0, 10); - style = RErr, [String "options"; String "vfstype"; Mountable "mountable"; String "mountpoint"], []; - proc_nr = Some 75; - shortdesc = "mount a guest disk with mount options and vfstype"; - longdesc = "\ -This is the same as the C<guestfs_mount> command, but it -allows you to set both the mount options and the vfstype -as for the L<mount(8)> I<-o> and I<-t> flags." }; - - { defaults with - name = "debug"; added = (1, 0, 11); - style = RString "result", [String "subcmd"; StringList "extraargs"], []; - proc_nr = Some 76; - visibility = VDebug; - shortdesc = "debugging and internals"; - longdesc = "\ -The C<guestfs_debug> command exposes some internals of -C<guestfsd> (the guestfs daemon) that runs inside the -hypervisor. - -There is no comprehensive help for this command. You have -to look at the file F<daemon/debug.c> in the libguestfs source -to find out what you can do." }; - - { defaults with - name = "lvremove"; added = (1, 0, 13); - style = RErr, [Device "device"], []; - proc_nr = Some 77; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV1"; "VG"; "50"]; - ["lvcreate"; "LV2"; "VG"; "50"]; - ["lvremove"; "/dev/VG/LV1"]; - ["lvs"]], - "is_string_list (ret, 1, \"/dev/VG/LV2\")"), []; - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV1"; "VG"; "50"]; - ["lvcreate"; "LV2"; "VG"; "50"]; - ["lvremove"; "/dev/VG"]; - ["lvs"]], - "is_string_list (ret, 0)"), []; - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV1"; "VG"; "50"]; - ["lvcreate"; "LV2"; "VG"; "50"]; - ["lvremove"; "/dev/VG"]; - ["vgs"]], - "is_string_list (ret, 1, \"VG\")"), [] - ]; - shortdesc = "remove an LVM logical volume"; - longdesc = "\ -Remove an LVM logical volume C<device>, where C<device> is -the path to the LV, such as F</dev/VG/LV>. - -You can also remove all LVs in a volume group by specifying -the VG name, F</dev/VG>." }; - - { defaults with - name = "vgremove"; added = (1, 0, 13); - style = RErr, [String "vgname"], []; - proc_nr = Some 78; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV1"; "VG"; "50"]; - ["lvcreate"; "LV2"; "VG"; "50"]; - ["vgremove"; "VG"]; - ["lvs"]], - "is_string_list (ret, 0)"), []; - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV1"; "VG"; "50"]; - ["lvcreate"; "LV2"; "VG"; "50"]; - ["vgremove"; "VG"]; - ["vgs"]], - "is_string_list (ret, 0)"), [] - ]; - shortdesc = "remove an LVM volume group"; - longdesc = "\ -Remove an LVM volume group C<vgname>, (for example C<VG>). - -This also forcibly removes all logical volumes in the volume -group (if any)." }; - - { defaults with - name = "pvremove"; added = (1, 0, 13); - style = RErr, [Device "device"], []; - proc_nr = Some 79; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV1"; "VG"; "50"]; - ["lvcreate"; "LV2"; "VG"; "50"]; - ["vgremove"; "VG"]; - ["pvremove"; "/dev/sda1"]; - ["lvs"]], - "is_string_list (ret, 0)"), []; - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV1"; "VG"; "50"]; - ["lvcreate"; "LV2"; "VG"; "50"]; - ["vgremove"; "VG"]; - ["pvremove"; "/dev/sda1"]; - ["vgs"]], - "is_string_list (ret, 0)"), []; - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV1"; "VG"; "50"]; - ["lvcreate"; "LV2"; "VG"; "50"]; - ["vgremove"; "VG"]; - ["pvremove"; "/dev/sda1"]; - ["pvs"]], - "is_string_list (ret, 0)"), [] - ]; - shortdesc = "remove an LVM physical volume"; - longdesc = "\ -This wipes a physical volume C<device> so that LVM will no longer -recognise it. - -The implementation uses the C<pvremove> command which refuses to -wipe physical volumes that contain any volume groups, so you have -to remove those first." }; - - { defaults with - name = "set_e2label"; added = (1, 0, 15); - style = RErr, [Device "device"; String "label"], []; - proc_nr = Some 80; - deprecated_by = Some "set_label"; - tests = [ - InitBasicFS, Always, TestResultString ( - [["set_e2label"; "/dev/sda1"; "testlabel"]; - ["get_e2label"; "/dev/sda1"]], "testlabel"), [] - ]; - shortdesc = "set the ext2/3/4 filesystem label"; - longdesc = "\ -This sets the ext2/3/4 filesystem label of the filesystem on -C<device> to C<label>. Filesystem labels are limited to -16 characters. - -You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label> -to return the existing label on a filesystem." }; - - { defaults with - name = "get_e2label"; added = (1, 0, 15); - style = RString "label", [Device "device"], []; - proc_nr = Some 81; - deprecated_by = Some "vfs_label"; - shortdesc = "get the ext2/3/4 filesystem label"; - longdesc = "\ -This returns the ext2/3/4 filesystem label of the filesystem on -C<device>." }; - - { defaults with - name = "set_e2uuid"; added = (1, 0, 15); - style = RErr, [Device "device"; String "uuid"], []; - proc_nr = Some 82; - deprecated_by = Some "set_uuid"; - tests = [ - InitBasicFS, Always, TestResultString ( - [["set_e2uuid"; "/dev/sda1"; stable_uuid]; - ["get_e2uuid"; "/dev/sda1"]], stable_uuid), []; - InitBasicFS, Always, TestResultString ( - [["set_e2uuid"; "/dev/sda1"; "clear"]; - ["get_e2uuid"; "/dev/sda1"]], ""), []; - (* We can't predict what UUIDs will be, so just check - the commands run. *) - InitBasicFS, Always, TestRun ( - [["set_e2uuid"; "/dev/sda1"; "random"]]), []; - InitBasicFS, Always, TestRun ( - [["set_e2uuid"; "/dev/sda1"; "time"]]), [] - ]; - shortdesc = "set the ext2/3/4 filesystem UUID"; - longdesc = "\ -This sets the ext2/3/4 filesystem UUID of the filesystem on -C<device> to C<uuid>. The format of the UUID and alternatives -such as C<clear>, C<random> and C<time> are described in the -L<tune2fs(8)> manpage. - -You can use C<guestfs_vfs_uuid> to return the existing UUID -of a filesystem." }; - - { defaults with - name = "get_e2uuid"; added = (1, 0, 15); - style = RString "uuid", [Device "device"], []; - proc_nr = Some 83; - deprecated_by = Some "vfs_uuid"; - tests = [ - (* We can't predict what UUID will be, so just check - the command run; regression test for RHBZ#597112. *) - InitNone, Always, TestRun ( - [["mke2journal"; "1024"; "/dev/sdc"]; - ["get_e2uuid"; "/dev/sdc"]]), [] - ]; - shortdesc = "get the ext2/3/4 filesystem UUID"; - longdesc = "\ -This returns the ext2/3/4 filesystem UUID of the filesystem on -C<device>." }; - - { defaults with - name = "fsck"; added = (1, 0, 16); - style = RInt "status", [String "fstype"; Device "device"], []; - proc_nr = Some 84; - fish_output = Some FishOutputHexadecimal; - tests = [ - InitBasicFS, Always, TestResult ( - [["umount"; "/dev/sda1"; "false"; "false"]; - ["fsck"; "ext2"; "/dev/sda1"]], "ret == 0"), []; - InitBasicFS, Always, TestResult ( - [["umount"; "/dev/sda1"; "false"; "false"]; - ["zero"; "/dev/sda1"]; - ["fsck"; "ext2"; "/dev/sda1"]], "ret == 8"), [] - ]; - shortdesc = "run the filesystem checker"; - longdesc = "\ -This runs the filesystem checker (fsck) on C<device> which -should have filesystem type C<fstype>. - -The returned integer is the status. See L<fsck(8)> for the -list of status codes from C<fsck>. - -Notes: - -=over 4 - -=item * - -Multiple status codes can be summed together. - -=item * - -A non-zero return code can mean \"success\", for example if -errors have been corrected on the filesystem. - -=item * - -Checking or repairing NTFS volumes is not supported -(by linux-ntfs). - -=back - -This command is entirely equivalent to running C<fsck -a -t fstype device>." }; - - { defaults with - name = "zero"; added = (1, 0, 16); - style = RErr, [Device "device"], []; - proc_nr = Some 85; - progress = true; - tests = [ - InitBasicFS, Always, TestRun ( - [["umount"; "/dev/sda1"; "false"; "false"]; - ["zero"; "/dev/sda1"]]), [] - ]; - shortdesc = "write zeroes to the device"; - longdesc = "\ -This command writes zeroes over the first few blocks of C<device>. - -How many blocks are zeroed isn't specified (but it's I<not> enough -to securely wipe the device). It should be sufficient to remove -any partition tables, filesystem superblocks and so on. - -If blocks are already zero, then this command avoids writing -zeroes. This prevents the underlying device from becoming non-sparse -or growing unnecessarily. - -See also: C<guestfs_zero_device>, C<guestfs_scrub_device>, -C<guestfs_is_zero_device>" }; - - { defaults with - name = "grub_install"; added = (1, 0, 17); - style = RErr, [Pathname "root"; Device "device"], []; - proc_nr = Some 86; - optional = Some "grub"; - (* See: - * https://bugzilla.redhat.com/show_bug.cgi?id=484986 - * https://bugzilla.redhat.com/show_bug.cgi?id=479760 - *) - tests = [ - InitBasicFS, Always, TestResultTrue ( - [["mkdir_p"; "/boot/grub"]; - ["write"; "/boot/grub/device.map"; "(hd0) /dev/sda"]; - ["grub_install"; "/"; "/dev/sda"]; - ["is_dir"; "/boot"; ""]]), [] - ]; - shortdesc = "install GRUB 1"; - longdesc = "\ -This command installs GRUB 1 (the Grand Unified Bootloader) on -C<device>, with the root directory being C<root>. - -Notes: - -=over 4 - -=item * - -There is currently no way in the API to install grub2, which -is used by most modern Linux guests. It is possible to run -the grub2 command from the guest, although see the -caveats in L<guestfs(3)/RUNNING COMMANDS>. - -=item * - -This uses C<grub-install> from the host. Unfortunately grub is -not always compatible with itself, so this only works in rather -narrow circumstances. Careful testing with each guest version -is advisable. - -=item * - -If grub-install reports the error -\"No suitable drive was found in the generated device map.\" -it may be that you need to create a F</boot/grub/device.map> -file first that contains the mapping between grub device names -and Linux device names. It is usually sufficient to create -a file containing: - - (hd0) /dev/vda - -replacing F</dev/vda> with the name of the installation device. - -=back" }; - - { defaults with - name = "cp"; added = (1, 0, 18); - style = RErr, [Pathname "src"; Pathname "dest"], []; - proc_nr = Some 87; - tests = [ - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/cp"]; - ["write"; "/cp/old"; "file content"]; - ["cp"; "/cp/old"; "/cp/new"]; - ["cat"; "/cp/new"]], "file content"), []; - InitScratchFS, Always, TestResultTrue ( - [["mkdir"; "/cp2"]; - ["write"; "/cp2/old"; "file content"]; - ["cp"; "/cp2/old"; "/cp2/new"]; - ["is_file"; "/cp2/old"; ""]]), []; - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/cp3"]; - ["write"; "/cp3/old"; "file content"]; - ["mkdir"; "/cp3/dir"]; - ["cp"; "/cp3/old"; "/cp3/dir/new"]; - ["cat"; "/cp3/dir/new"]], "file content"), [] - ]; - shortdesc = "copy a file"; - longdesc = "\ -This copies a file from C<src> to C<dest> where C<dest> is -either a destination filename or destination directory." }; - - { defaults with - name = "cp_a"; added = (1, 0, 18); - style = RErr, [Pathname "src"; Pathname "dest"], []; - proc_nr = Some 88; - tests = [ - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/cp_a1"]; - ["mkdir"; "/cp_a2"]; - ["write"; "/cp_a1/file"; "file content"]; - ["cp_a"; "/cp_a1"; "/cp_a2"]; - ["cat"; "/cp_a2/cp_a1/file"]], "file content"), [] - ]; - shortdesc = "copy a file or directory recursively"; - longdesc = "\ -This copies a file or directory from C<src> to C<dest> -recursively using the C<cp -a> command." }; - - { defaults with - name = "mv"; added = (1, 0, 18); - style = RErr, [Pathname "src"; Pathname "dest"], []; - proc_nr = Some 89; - tests = [ - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/mv"]; - ["write"; "/mv/old"; "file content"]; - ["mv"; "/mv/old"; "/mv/new"]; - ["cat"; "/mv/new"]], "file content"), []; - InitScratchFS, Always, TestResultFalse ( - [["mkdir"; "/mv2"]; - ["write"; "/mv2/old"; "file content"]; - ["mv"; "/mv2/old"; "/mv2/new"]; - ["is_file"; "/mv2/old"; ""]]), [] - ]; - shortdesc = "move a file"; - longdesc = "\ -This moves a file from C<src> to C<dest> where C<dest> is -either a destination filename or destination directory. - -See also: C<guestfs_rename>." }; - - { defaults with - name = "drop_caches"; added = (1, 0, 18); - style = RErr, [Int "whattodrop"], []; - proc_nr = Some 90; - tests = [ - InitEmpty, Always, TestRun ( - [["drop_caches"; "3"]]), [] - ]; - shortdesc = "drop kernel page cache, dentries and inodes"; - longdesc = "\ -This instructs the guest kernel to drop its page cache, -and/or dentries and inode caches. The parameter C<whattodrop> -tells the kernel what precisely to drop, see -L<http://linux-mm.org/Drop_Caches> - -Setting C<whattodrop> to 3 should drop everything. - -This automatically calls L<sync(2)> before the operation, -so that the maximum guest memory is freed." }; - - { defaults with - name = "dmesg"; added = (1, 0, 18); - style = RString "kmsgs", [], []; - proc_nr = Some 91; - tests = [ - InitEmpty, Always, TestRun ( - [["dmesg"]]), [] - ]; - shortdesc = "return kernel messages"; - longdesc = "\ -This returns the kernel messages (C<dmesg> output) from -the guest kernel. This is sometimes useful for extended -debugging of problems. - -Another way to get the same information is to enable -verbose messages with C<guestfs_set_verbose> or by setting -the environment variable C<LIBGUESTFS_DEBUG=1> before -running the program." }; - - { defaults with - name = "ping_daemon"; added = (1, 0, 18); - style = RErr, [], []; - proc_nr = Some 92; - tests = [ - InitEmpty, Always, TestRun ( - [["ping_daemon"]]), [] - ]; - shortdesc = "ping the guest daemon"; - longdesc = "\ -This is a test probe into the guestfs daemon running inside -the libguestfs appliance. Calling this function checks that the -daemon responds to the ping message, without affecting the daemon -or attached block device(s) in any other way." }; - - { defaults with - name = "equal"; added = (1, 0, 18); - style = RBool "equality", [Pathname "file1"; Pathname "file2"], []; - proc_nr = Some 93; - tests = [ - InitScratchFS, Always, TestResultTrue ( - [["mkdir"; "/equal"]; - ["write"; "/equal/file1"; "contents of a file"]; - ["cp"; "/equal/file1"; "/equal/file2"]; - ["equal"; "/equal/file1"; "/equal/file2"]]), []; - InitScratchFS, Always, TestResultFalse ( - [["mkdir"; "/equal2"]; - ["write"; "/equal2/file1"; "contents of a file"]; - ["write"; "/equal2/file2"; "contents of another file"]; - ["equal"; "/equal2/file1"; "/equal2/file2"]]), []; - InitScratchFS, Always, TestLastFail ( - [["mkdir"; "/equal3"]; - ["equal"; "/equal3/file1"; "/equal3/file2"]]), [] - ]; - shortdesc = "test if two files have equal contents"; - longdesc = "\ -This compares the two files F<file1> and F<file2> and returns -true if their content is exactly equal, or false otherwise. - -The external L<cmp(1)> program is used for the comparison." }; - - { defaults with - name = "strings"; added = (1, 0, 22); - style = RStringList "stringsout", [Pathname "path"], []; - proc_nr = Some 94; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResult ( - [["strings"; "/known-5"]], - "is_string_list (ret, 2, \"abcdefghi\", \"jklmnopqr\")"), []; - InitISOFS, Always, TestResult ( - [["strings"; "/empty"]], - "is_string_list (ret, 0)"), []; - (* Test for RHBZ#579608, absolute symbolic links. *) - InitISOFS, Always, TestRun ( - [["strings"; "/abssymlink"]]), [] - ]; - shortdesc = "print the printable strings in a file"; - longdesc = "\ -This runs the L<strings(1)> command on a file and returns -the list of printable strings found. - -The C<strings> command has, in the past, had problems with -parsing untrusted files. These are mitigated in the current -version of libguestfs, but see L<guestfs(3)/CVE-2014-8484>." }; - - { defaults with - name = "strings_e"; added = (1, 0, 22); - style = RStringList "stringsout", [String "encoding"; Pathname "path"], []; - proc_nr = Some 95; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResult ( - [["strings_e"; "b"; "/known-5"]], - "is_string_list (ret, 0)"), []; - InitScratchFS, Always, TestResult ( - [["write"; "/strings_e"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"]; - ["strings_e"; "b"; "/strings_e"]], - "is_string_list (ret, 2, \"hello\", \"world\")"), [] - ]; - shortdesc = "print the printable strings in a file"; - longdesc = "\ -This is like the C<guestfs_strings> command, but allows you to -specify the encoding of strings that are looked for in -the source file C<path>. - -Allowed encodings are: - -=over 4 - -=item s - -Single 7-bit-byte characters like ASCII and the ASCII-compatible -parts of ISO-8859-X (this is what C<guestfs_strings> uses). - -=item S - -Single 8-bit-byte characters. - -=item b - -16-bit big endian strings such as those encoded in -UTF-16BE or UCS-2BE. - -=item l (lower case letter L) - -16-bit little endian such as UTF-16LE and UCS-2LE. -This is useful for examining binaries in Windows guests. - -=item B - -32-bit big endian such as UCS-4BE. - -=item L - -32-bit little endian such as UCS-4LE. - -=back - -The returned strings are transcoded to UTF-8. - -The C<strings> command has, in the past, had problems with -parsing untrusted files. These are mitigated in the current -version of libguestfs, but see L<guestfs(3)/CVE-2014-8484>." }; - - { defaults with - name = "hexdump"; added = (1, 0, 22); - style = RString "dump", [Pathname "path"], []; - proc_nr = Some 96; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResultString ( - [["hexdump"; "/known-4"]], "00000000 61 62 63 0a 64 65 66 0a 67 68 69 |abc.def.ghi|\n0000000b\n"), []; - (* Test for RHBZ#501888c2 regression which caused large hexdump - * commands to segfault. - *) - InitISOFS, Always, TestRun ( - [["hexdump"; "/100krandom"]]), []; - (* Test for RHBZ#579608, absolute symbolic links. *) - InitISOFS, Always, TestRun ( - [["hexdump"; "/abssymlink"]]), [] - ]; - shortdesc = "dump a file in hexadecimal"; - longdesc = "\ -This runs C<hexdump -C> on the given C<path>. The result is -the human-readable, canonical hex dump of the file." }; - - { defaults with - name = "zerofree"; added = (1, 0, 26); - style = RErr, [Device "device"], []; - proc_nr = Some 97; - optional = Some "zerofree"; - tests = [ - InitNone, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "ext3"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["write"; "/new"; "test file"]; - ["umount"; "/dev/sda1"; "false"; "false"]; - ["zerofree"; "/dev/sda1"]; - ["mount"; "/dev/sda1"; "/"]; - ["cat"; "/new"]], "test file"), [] - ]; - shortdesc = "zero unused inodes and disk blocks on ext2/3 filesystem"; - longdesc = "\ -This runs the I<zerofree> program on C<device>. This program -claims to zero unused inodes and disk blocks on an ext2/3 -filesystem, thus making it possible to compress the filesystem -more effectively. - -You should B<not> run this program if the filesystem is -mounted. - -It is possible that using this program can damage the filesystem -or data on the filesystem." }; - - { defaults with - name = "pvresize"; added = (1, 0, 26); - style = RErr, [Device "device"], []; - proc_nr = Some 98; - optional = Some "lvm2"; - shortdesc = "resize an LVM physical volume"; - longdesc = "\ -This resizes (expands or shrinks) an existing LVM physical -volume to match the new size of the underlying device." }; - - { defaults with - name = "sfdisk_N"; added = (1, 0, 26); - style = RErr, [Device "device"; Int "partnum"; - Int "cyls"; Int "heads"; Int "sectors"; - String "line"], []; - proc_nr = Some 99; - deprecated_by = Some "part_add"; - shortdesc = "modify a single partition on a block device"; - longdesc = "\ -This runs L<sfdisk(8)> option to modify just the single -partition C<n> (note: C<n> counts from 1). - -For other parameters, see C<guestfs_sfdisk>. You should usually -pass C<0> for the cyls/heads/sectors parameters. - -See also: C<guestfs_part_add>" }; - - { defaults with - name = "sfdisk_l"; added = (1, 0, 26); - style = RString "partitions", [Device "device"], []; - proc_nr = Some 100; - deprecated_by = Some "part_list"; - shortdesc = "display the partition table"; - longdesc = "\ -This displays the partition table on C<device>, in the -human-readable output of the L<sfdisk(8)> command. It is -not intended to be parsed. - -See also: C<guestfs_part_list>" }; - - { defaults with - name = "sfdisk_kernel_geometry"; added = (1, 0, 26); - style = RString "partitions", [Device "device"], []; - proc_nr = Some 101; - shortdesc = "display the kernel geometry"; - longdesc = "\ -This displays the kernel's idea of the geometry of C<device>. - -The result is in human-readable format, and not designed to -be parsed." }; - - { defaults with - name = "sfdisk_disk_geometry"; added = (1, 0, 26); - style = RString "partitions", [Device "device"], []; - proc_nr = Some 102; - shortdesc = "display the disk geometry from the partition table"; - longdesc = "\ -This displays the disk geometry of C<device> read from the -partition table. Especially in the case where the underlying -block device has been resized, this can be different from the -kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>). - -The result is in human-readable format, and not designed to -be parsed." }; - - { defaults with - name = "vg_activate_all"; added = (1, 0, 26); - style = RErr, [Bool "activate"], []; - proc_nr = Some 103; - optional = Some "lvm2"; - shortdesc = "activate or deactivate all volume groups"; - longdesc = "\ -This command activates or (if C<activate> is false) deactivates -all logical volumes in all volume groups. - -This command is the same as running C<vgchange -a y|n>" }; - - { defaults with - name = "vg_activate"; added = (1, 0, 26); - style = RErr, [Bool "activate"; StringList "volgroups"], []; - proc_nr = Some 104; - optional = Some "lvm2"; - shortdesc = "activate or deactivate some volume groups"; - longdesc = "\ -This command activates or (if C<activate> is false) deactivates -all logical volumes in the listed volume groups C<volgroups>. - -This command is the same as running C<vgchange -a y|n volgroups...> - -Note that if C<volgroups> is an empty list then B<all> volume groups -are activated or deactivated." }; - - { defaults with - name = "lvresize"; added = (1, 0, 27); - style = RErr, [Device "device"; Int "mbytes"], []; - proc_nr = Some 105; - optional = Some "lvm2"; - tests = [ - InitNone, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV"; "VG"; "10"]; - ["mkfs"; "ext2"; "/dev/VG/LV"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/VG/LV"; "/"]; - ["write"; "/new"; "test content"]; - ["umount"; "/"; "false"; "false"]; - ["lvresize"; "/dev/VG/LV"; "20"]; - ["e2fsck_f"; "/dev/VG/LV"]; - ["e2fsck"; "/dev/VG/LV"; "true"; "false"]; - ["e2fsck"; "/dev/VG/LV"; "false"; "true"]; - ["resize2fs"; "/dev/VG/LV"]; - ["mount"; "/dev/VG/LV"; "/"]; - ["cat"; "/new"]], "test content"), []; - InitNone, Always, TestRun ( - (* Make an LV smaller to test RHBZ#587484. *) - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV"; "VG"; "20"]; - ["lvresize"; "/dev/VG/LV"; "10"]]), [] - ]; - shortdesc = "resize an LVM logical volume"; - longdesc = "\ -This resizes (expands or shrinks) an existing LVM logical -volume to C<mbytes>. When reducing, data in the reduced part -is lost." }; - - { defaults with - name = "resize2fs"; added = (1, 0, 27); - style = RErr, [Device "device"], []; - proc_nr = Some 106; - shortdesc = "resize an ext2, ext3 or ext4 filesystem"; - longdesc = "\ -This resizes an ext2, ext3 or ext4 filesystem to match the size of -the underlying device. - -See also L<guestfs(3)/RESIZE2FS ERRORS>." }; - - { defaults with - name = "e2fsck_f"; added = (1, 0, 29); - style = RErr, [Device "device"], []; - proc_nr = Some 108; - deprecated_by = Some "e2fsck"; - shortdesc = "check an ext2/ext3 filesystem"; - longdesc = "\ -This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3 -filesystem checker on C<device>, noninteractively (I<-p>), -even if the filesystem appears to be clean (I<-f>)." }; - - { defaults with - name = "sleep"; added = (1, 0, 41); - style = RErr, [Int "secs"], []; - proc_nr = Some 109; - tests = [ - InitNone, Always, TestRun ( - [["sleep"; "1"]]), [] - ]; - shortdesc = "sleep for some seconds"; - longdesc = "\ -Sleep for C<secs> seconds." }; - - { defaults with - name = "ntfs_3g_probe"; added = (1, 0, 43); - style = RInt "status", [Bool "rw"; Device "device"], []; - proc_nr = Some 110; - optional = Some "ntfs3g"; - tests = [ - InitNone, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["ntfs_3g_probe"; "true"; "/dev/sda1"]], "ret == 0"), []; - InitNone, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["ntfs_3g_probe"; "true"; "/dev/sda1"]], "ret == 12"), [] - ]; - shortdesc = "probe NTFS volume"; - longdesc = "\ -This command runs the L<ntfs-3g.probe(8)> command which probes -an NTFS C<device> for mountability. (Not all NTFS volumes can -be mounted read-write, and some cannot be mounted at all). - -C<rw> is a boolean flag. Set it to true if you want to test -if the volume can be mounted read-write. Set it to false if -you want to test if the volume can be mounted read-only. - -The return value is an integer which C<0> if the operation -would succeed, or some non-zero value documented in the -L<ntfs-3g.probe(8)> manual page." }; - - { defaults with - name = "sh"; added = (1, 0, 50); - style = RString "output", [String "command"], []; - proc_nr = Some 111; - shortdesc = "run a command via the shell"; - longdesc = "\ -This call runs a command from the guest filesystem via the -guest's F</bin/sh>. - -This is like C<guestfs_command>, but passes the command to: - - /bin/sh -c \"command\" - -Depending on the guest's shell, this usually results in -wildcards being expanded, shell expressions being interpolated -and so on. - -All the provisos about C<guestfs_command> apply to this call." }; - - { defaults with - name = "sh_lines"; added = (1, 0, 50); - style = RStringList "lines", [String "command"], []; - proc_nr = Some 112; - shortdesc = "run a command via the shell returning lines"; - longdesc = "\ -This is the same as C<guestfs_sh>, but splits the result -into a list of lines. - -See also: C<guestfs_command_lines>" }; - - { defaults with - name = "glob_expand"; added = (1, 0, 50); - (* Use Pathname here, and hence ABS_PATH (pattern,...) in - * generated code in stubs.c, since all valid glob patterns must - * start with "/". There is no concept of "cwd" in libguestfs, - * hence no "."-relative names. - *) - style = RStringList "paths", [Pathname "pattern"], [OBool "directoryslash"]; - proc_nr = Some 113; - once_had_no_optargs = true; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir_p"; "/glob_expand/b/c"]; - ["touch"; "/glob_expand/b/c/d"]; - ["touch"; "/glob_expand/b/c/e"]; - ["glob_expand"; "/glob_expand/b/c/*"; ""]], - "is_string_list (ret, 2, \"/glob_expand/b/c/d\", \"/glob_expand/b/c/e\")"), []; - InitScratchFS, Always, TestResult ( - [["mkdir_p"; "/glob_expand2/b/c"]; - ["touch"; "/glob_expand2/b/c/d"]; - ["touch"; "/glob_expand2/b/c/e"]; - ["glob_expand"; "/glob_expand2/*/c/*"; ""]], - "is_string_list (ret, 2, \"/glob_expand2/b/c/d\", \"/glob_expand2/b/c/e\")"), []; - InitScratchFS, Always, TestResult ( - [["mkdir_p"; "/glob_expand3/b/c"]; - ["touch"; "/glob_expand3/b/c/d"]; - ["touch"; "/glob_expand3/b/c/e"]; - ["glob_expand"; "/glob_expand3/*/x/*"; ""]], - "is_string_list (ret, 0)"), []; - InitScratchFS, Always, TestResult ( - [["mkdir_p"; "/glob_expand4/b/c"]; - ["touch"; "/glob_expand4/b1"]; - ["touch"; "/glob_expand4/c1"]; - ["glob_expand"; "/glob_expand4/b*"; "false"]], - "is_string_list (ret, 2, \"/glob_expand4/b\", \"/glob_expand4/b1\")"), []; - ]; - shortdesc = "expand a wildcard path"; - longdesc = "\ -This command searches for all the pathnames matching -C<pattern> according to the wildcard expansion rules -used by the shell. - -If no paths match, then this returns an empty list -(note: not an error). - -It is just a wrapper around the C L<glob(3)> function -with flags C<GLOB_MARK|GLOB_BRACE>. -See that manual page for more details. - -C<directoryslash> controls whether use the C<GLOB_MARK> flag for -L<glob(3)>, and it defaults to true. It can be explicitly set as -off to return no trailing slashes in filenames of directories. - -Notice that there is no equivalent command for expanding a device -name (eg. F</dev/sd*>). Use C<guestfs_list_devices>, -C<guestfs_list_partitions> etc functions instead." }; - - { defaults with - name = "scrub_device"; added = (1, 0, 52); - style = RErr, [Device "device"], []; - proc_nr = Some 114; - optional = Some "scrub"; - tests = [ - InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *) - [["scrub_device"; "/dev/sdc"]]), [] - ]; - shortdesc = "scrub (securely wipe) a device"; - longdesc = "\ -This command writes patterns over C<device> to make data retrieval -more difficult. - -It is an interface to the L<scrub(1)> program. See that -manual page for more details." }; - - { defaults with - name = "scrub_file"; added = (1, 0, 52); - style = RErr, [Pathname "file"], []; - proc_nr = Some 115; - optional = Some "scrub"; - tests = [ - InitScratchFS, Always, TestRun ( - [["write"; "/scrub_file"; "content"]; - ["scrub_file"; "/scrub_file"]]), []; - InitScratchFS, Always, TestRun ( - [["write"; "/scrub_file_2"; "content"]; - ["ln_s"; "/scrub_file_2"; "/scrub_file_2_link"]; - ["scrub_file"; "/scrub_file_2_link"]]), []; - InitScratchFS, Always, TestLastFail ( - [["ln_s"; "/scrub_file_3_notexisting"; "/scrub_file_3_link"]; - ["scrub_file"; "/scrub_file_3_link"]]), []; - InitScratchFS, Always, TestLastFail ( - [["write"; "/scrub_file_4"; "content"]; - ["ln_s"; "../sysroot/scrub_file_4"; "/scrub_file_4_link"]; - ["scrub_file"; "/scrub_file_4_link"]]), []; - ]; - shortdesc = "scrub (securely wipe) a file"; - longdesc = "\ -This command writes patterns over a file to make data retrieval -more difficult. - -The file is I<removed> after scrubbing. - -It is an interface to the L<scrub(1)> program. See that -manual page for more details." }; - - { defaults with - name = "scrub_freespace"; added = (1, 0, 52); - style = RErr, [Pathname "dir"], []; - proc_nr = Some 116; - optional = Some "scrub"; - tests = [] (* XXX needs testing *); - shortdesc = "scrub (securely wipe) free space"; - longdesc = "\ -This command creates the directory C<dir> and then fills it -with files until the filesystem is full, and scrubs the files -as for C<guestfs_scrub_file>, and deletes them. -The intention is to scrub any free space on the partition -containing C<dir>. - -It is an interface to the L<scrub(1)> program. See that -manual page for more details." }; - - { defaults with - name = "mkdtemp"; added = (1, 0, 54); - style = RString "dir", [Pathname "tmpl"], []; - proc_nr = Some 117; - tests = [ - InitScratchFS, Always, TestRun ( - [["mkdir"; "/mkdtemp"]; - ["mkdtemp"; "/mkdtemp/tmpXXXXXX"]]), [] - ]; - shortdesc = "create a temporary directory"; - longdesc = "\ -This command creates a temporary directory. The -C<tmpl> parameter should be a full pathname for the -temporary directory name with the final six characters being -\"XXXXXX\". - -For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\", -the second one being suitable for Windows filesystems. - -The name of the temporary directory that was created -is returned. - -The temporary directory is created with mode 0700 -and is owned by root. - -The caller is responsible for deleting the temporary -directory and its contents after use. - -See also: L<mkdtemp(3)>" }; - - { defaults with - name = "wc_l"; added = (1, 0, 54); - style = RInt "lines", [Pathname "path"], []; - proc_nr = Some 118; - tests = [ - InitISOFS, Always, TestResult ( - [["wc_l"; "/10klines"]], "ret == 10000"), []; - (* Test for RHBZ#579608, absolute symbolic links. *) - InitISOFS, Always, TestResult ( - [["wc_l"; "/abssymlink"]], "ret == 10000"), [] - ]; - shortdesc = "count lines in a file"; - longdesc = "\ -This command counts the lines in a file, using the -C<wc -l> external command." }; - - { defaults with - name = "wc_w"; added = (1, 0, 54); - style = RInt "words", [Pathname "path"], []; - proc_nr = Some 119; - tests = [ - InitISOFS, Always, TestResult ( - [["wc_w"; "/10klines"]], "ret == 10000"), [] - ]; - shortdesc = "count words in a file"; - longdesc = "\ -This command counts the words in a file, using the -C<wc -w> external command." }; - - { defaults with - name = "wc_c"; added = (1, 0, 54); - style = RInt "chars", [Pathname "path"], []; - proc_nr = Some 120; - tests = [ - InitISOFS, Always, TestResult ( - [["wc_c"; "/100kallspaces"]], "ret == 102400"), [] - ]; - shortdesc = "count characters in a file"; - longdesc = "\ -This command counts the characters in a file, using the -C<wc -c> external command." }; - - { defaults with - name = "head"; added = (1, 0, 54); - style = RStringList "lines", [Pathname "path"], []; - proc_nr = Some 121; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResult ( - [["head"; "/10klines"]], - "is_string_list (ret, 10, \"0abcdefghijklmnopqrstuvwxyz\", \"1abcdefghijklmnopqrstuvwxyz\", \"2abcdefghijklmnopqrstuvwxyz\", \"3abcdefghijklmnopqrstuvwxyz\", \"4abcdefghijklmnopqrstuvwxyz\", \"5abcdefghijklmnopqrstuvwxyz\", \"6abcdefghijklmnopqrstuvwxyz\", \"7abcdefghijklmnopqrstuvwxyz\", \"8abcdefghijklmnopqrstuvwxyz\", \"9abcdefghijklmnopqrstuvwxyz\")"), []; - (* Test for RHBZ#579608, absolute symbolic links. *) - InitISOFS, Always, TestResult ( - [["head"; "/abssymlink"]], - "is_string_list (ret, 10, \"0abcdefghijklmnopqrstuvwxyz\", \"1abcdefghijklmnopqrstuvwxyz\", \"2abcdefghijklmnopqrstuvwxyz\", \"3abcdefghijklmnopqrstuvwxyz\", \"4abcdefghijklmnopqrstuvwxyz\", \"5abcdefghijklmnopqrstuvwxyz\", \"6abcdefghijklmnopqrstuvwxyz\", \"7abcdefghijklmnopqrstuvwxyz\", \"8abcdefghijklmnopqrstuvwxyz\", \"9abcdefghijklmnopqrstuvwxyz\")"), [] - ]; - shortdesc = "return first 10 lines of a file"; - longdesc = "\ -This command returns up to the first 10 lines of a file as -a list of strings." }; - - { defaults with - name = "head_n"; added = (1, 0, 54); - style = RStringList "lines", [Int "nrlines"; Pathname "path"], []; - proc_nr = Some 122; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResult ( - [["head_n"; "3"; "/10klines"]], - "is_string_list (ret, 3, \"0abcdefghijklmnopqrstuvwxyz\", \"1abcdefghijklmnopqrstuvwxyz\", \"2abcdefghijklmnopqrstuvwxyz\")"), []; - InitISOFS, Always, TestResult ( - [["head_n"; "-9997"; "/10klines"]], - "is_string_list (ret, 3, \"0abcdefghijklmnopqrstuvwxyz\", \"1abcdefghijklmnopqrstuvwxyz\", \"2abcdefghijklmnopqrstuvwxyz\")"), []; - InitISOFS, Always, TestResult ( - [["head_n"; "0"; "/10klines"]], - "is_string_list (ret, 0)"), [] - ]; - shortdesc = "return first N lines of a file"; - longdesc = "\ -If the parameter C<nrlines> is a positive number, this returns the first -C<nrlines> lines of the file C<path>. - -If the parameter C<nrlines> is a negative number, this returns lines -from the file C<path>, excluding the last C<nrlines> lines. - -If the parameter C<nrlines> is zero, this returns an empty list." }; - - { defaults with - name = "tail"; added = (1, 0, 54); - style = RStringList "lines", [Pathname "path"], []; - proc_nr = Some 123; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResult ( - [["tail"; "/10klines"]], - "is_string_list (ret, 10, \"9990abcdefghijklmnopqrstuvwxyz\", \"9991abcdefghijklmnopqrstuvwxyz\", \"9992abcdefghijklmnopqrstuvwxyz\", \"9993abcdefghijklmnopqrstuvwxyz\", \"9994abcdefghijklmnopqrstuvwxyz\", \"9995abcdefghijklmnopqrstuvwxyz\", \"9996abcdefghijklmnopqrstuvwxyz\", \"9997abcdefghijklmnopqrstuvwxyz\", \"9998abcdefghijklmnopqrstuvwxyz\", \"9999abcdefghijklmnopqrstuvwxyz\")"), [] - ]; - shortdesc = "return last 10 lines of a file"; - longdesc = "\ -This command returns up to the last 10 lines of a file as -a list of strings." }; - - { defaults with - name = "tail_n"; added = (1, 0, 54); - style = RStringList "lines", [Int "nrlines"; Pathname "path"], []; - proc_nr = Some 124; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResult ( - [["tail_n"; "3"; "/10klines"]], - "is_string_list (ret, 3, \"9997abcdefghijklmnopqrstuvwxyz\", \"9998abcdefghijklmnopqrstuvwxyz\", \"9999abcdefghijklmnopqrstuvwxyz\")"), []; - InitISOFS, Always, TestResult ( - [["tail_n"; "-9998"; "/10klines"]], - "is_string_list (ret, 3, \"9997abcdefghijklmnopqrstuvwxyz\", \"9998abcdefghijklmnopqrstuvwxyz\", \"9999abcdefghijklmnopqrstuvwxyz\")"), []; - InitISOFS, Always, TestResult ( - [["tail_n"; "0"; "/10klines"]], - "is_string_list (ret, 0)"), [] - ]; - shortdesc = "return last N lines of a file"; - longdesc = "\ -If the parameter C<nrlines> is a positive number, this returns the last -C<nrlines> lines of the file C<path>. - -If the parameter C<nrlines> is a negative number, this returns lines -from the file C<path>, starting with the C<-nrlines>th line. - -If the parameter C<nrlines> is zero, this returns an empty list." }; - - { defaults with - name = "df"; added = (1, 0, 54); - style = RString "output", [], []; - proc_nr = Some 125; - test_excuse = "tricky to test because it depends on the exact format of the 'df' command and other imponderables"; - shortdesc = "report file system disk space usage"; - longdesc = "\ -This command runs the C<df> command to report disk space used. - -This command is mostly useful for interactive sessions. It -is I<not> intended that you try to parse the output string. -Use C<guestfs_statvfs> from programs." }; - - { defaults with - name = "df_h"; added = (1, 0, 54); - style = RString "output", [], []; - proc_nr = Some 126; - test_excuse = "tricky to test because it depends on the exact format of the 'df' command and other imponderables"; - shortdesc = "report file system disk space usage (human readable)"; - longdesc = "\ -This command runs the C<df -h> command to report disk space used -in human-readable format. - -This command is mostly useful for interactive sessions. It -is I<not> intended that you try to parse the output string. -Use C<guestfs_statvfs> from programs." }; - - { defaults with - name = "du"; added = (1, 0, 54); - style = RInt64 "sizekb", [Pathname "path"], []; - proc_nr = Some 127; - progress = true; - tests = [ - InitISOFS, Always, TestResult ( - [["du"; "/directory"]], "ret == 2" (* ISO fs blocksize is 2K *)), [] - ]; - shortdesc = "estimate file space usage"; - longdesc = "\ -This command runs the C<du -s> command to estimate file space -usage for C<path>. - -C<path> can be a file or a directory. If C<path> is a directory -then the estimate includes the contents of the directory and all -subdirectories (recursively). - -The result is the estimated size in I<kilobytes> -(ie. units of 1024 bytes)." }; - - { defaults with - name = "initrd_list"; added = (1, 0, 54); - style = RStringList "filenames", [Pathname "path"], []; - proc_nr = Some 128; - tests = [ - InitISOFS, Always, TestResult ( - [["initrd_list"; "/initrd"]], - "is_string_list (ret, 6, \"empty\", \"known-1\", \"known-2\", \"known-3\", \"known-4\", \"known-5\")"), [] - ]; - shortdesc = "list files in an initrd"; - longdesc = "\ -This command lists out files contained in an initrd. - -The files are listed without any initial F</> character. The -files are listed in the order they appear (not necessarily -alphabetical). Directory names are listed as separate items. - -Old Linux kernels (2.4 and earlier) used a compressed ext2 -filesystem as initrd. We I<only> support the newer initramfs -format (compressed cpio files)." }; - - { defaults with - name = "mount_loop"; added = (1, 0, 54); - style = RErr, [Pathname "file"; Pathname "mountpoint"], []; - proc_nr = Some 129; - shortdesc = "mount a file using the loop device"; - longdesc = "\ -This command lets you mount F<file> (a filesystem image -in a file) on a mount point. It is entirely equivalent to -the command C<mount -o loop file mountpoint>." }; - - { defaults with - name = "mkswap"; added = (1, 0, 55); - style = RErr, [Device "device"], [OString "label"; OString "uuid"]; - proc_nr = Some 130; - once_had_no_optargs = true; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkswap"; "/dev/sda1"; "NOARG"; "NOARG"]]), []; - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkswap"; "/dev/sda1"; "hello"; "NOARG"]]), []; - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkswap"; "/dev/sda1"; "NOARG"; stable_uuid]; - ["vfs_uuid"; "/dev/sda1"]], stable_uuid), []; - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkswap"; "/dev/sda1"; "hello"; stable_uuid]; - ["vfs_label"; "/dev/sda1"]], "hello"), [] - ]; - shortdesc = "create a swap partition"; - longdesc = "\ -Create a Linux swap partition on C<device>. - -The option arguments C<label> and C<uuid> allow you to set the -label and/or UUID of the new swap partition." }; - - { defaults with - name = "mkswap_L"; added = (1, 0, 55); - style = RErr, [String "label"; Device "device"], []; - proc_nr = Some 131; - deprecated_by = Some "mkswap"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkswap_L"; "hello"; "/dev/sda1"]]), [] - ]; - shortdesc = "create a swap partition with a label"; - longdesc = "\ -Create a swap partition on C<device> with label C<label>. - -Note that you cannot attach a swap label to a block device -(eg. F</dev/sda>), just to a partition. This appears to be -a limitation of the kernel or swap tools." }; - - { defaults with - name = "mkswap_U"; added = (1, 0, 55); - style = RErr, [String "uuid"; Device "device"], []; - proc_nr = Some 132; - deprecated_by = Some "mkswap"; - optional = Some "linuxfsuuid"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkswap_U"; stable_uuid; "/dev/sda1"]]), [] - ]; - shortdesc = "create a swap partition with an explicit UUID"; - longdesc = "\ -Create a swap partition on C<device> with UUID C<uuid>." }; - - { defaults with - name = "mknod"; added = (1, 0, 55); - style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []; - proc_nr = Some 133; - optional = Some "mknod"; - tests = [ - InitScratchFS, Always, TestResult ( - [["mknod"; "0o10777"; "0"; "0"; "/mknod"]; - (* NB: default umask 022 means 0777 -> 0755 in these tests *) - ["stat"; "/mknod"]], - "S_ISFIFO (ret->mode) && (ret->mode & 0777) == 0755"), []; - InitScratchFS, Always, TestResult ( - [["mknod"; "0o60777"; "66"; "99"; "/mknod2"]; - ["stat"; "/mknod2"]], - "S_ISBLK (ret->mode) && (ret->mode & 0777) == 0755"), [] - ]; - shortdesc = "make block, character or FIFO devices"; - longdesc = "\ -This call creates block or character special devices, or -named pipes (FIFOs). - -The C<mode> parameter should be the mode, using the standard -constants. C<devmajor> and C<devminor> are the -device major and minor numbers, only used when creating block -and character special devices. - -Note that, just like L<mknod(2)>, the mode must be bitwise -OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call -just creates a regular file). These constants are -available in the standard Linux header files, or you can use -C<guestfs_mknod_b>, C<guestfs_mknod_c> or C<guestfs_mkfifo> -which are wrappers around this command which bitwise OR -in the appropriate constant for you. - -The mode actually set is affected by the umask." }; - - { defaults with - name = "mkfifo"; added = (1, 0, 55); - style = RErr, [Int "mode"; Pathname "path"], []; - proc_nr = Some 134; - optional = Some "mknod"; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkfifo"; "0o777"; "/mkfifo"]; - ["stat"; "/mkfifo"]], - "S_ISFIFO (ret->mode) && (ret->mode & 0777) == 0755"), []; - InitScratchFS, Always, TestLastFail ( - [["mkfifo"; "0o20777"; "/mkfifo-2"]]), []; - ]; - shortdesc = "make FIFO (named pipe)"; - longdesc = "\ -This call creates a FIFO (named pipe) called C<path> with -mode C<mode>. It is just a convenient wrapper around -C<guestfs_mknod>. - -Unlike with C<guestfs_mknod>, C<mode> B<must> contain only permissions -bits. - -The mode actually set is affected by the umask." }; - - { defaults with - name = "mknod_b"; added = (1, 0, 55); - style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []; - proc_nr = Some 135; - optional = Some "mknod"; - tests = [ - InitScratchFS, Always, TestResult ( - [["mknod_b"; "0o777"; "99"; "66"; "/mknod_b"]; - ["stat"; "/mknod_b"]], - "S_ISBLK (ret->mode) && (ret->mode & 0777) == 0755"), []; - InitScratchFS, Always, TestLastFail ( - [["mknod_b"; "0o10777"; "99"; "66"; "/mknod_b-2"]]), []; - ]; - shortdesc = "make block device node"; - longdesc = "\ -This call creates a block device node called C<path> with -mode C<mode> and device major/minor C<devmajor> and C<devminor>. -It is just a convenient wrapper around C<guestfs_mknod>. - -Unlike with C<guestfs_mknod>, C<mode> B<must> contain only permissions -bits. - -The mode actually set is affected by the umask." }; - - { defaults with - name = "mknod_c"; added = (1, 0, 55); - style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []; - proc_nr = Some 136; - optional = Some "mknod"; - tests = [ - InitScratchFS, Always, TestResult ( - [["mknod_c"; "0o777"; "99"; "66"; "/mknod_c"]; - ["stat"; "/mknod_c"]], - "S_ISCHR (ret->mode) && (ret->mode & 0777) == 0755"), []; - InitScratchFS, Always, TestLastFail ( - [["mknod_c"; "0o20777"; "99"; "66"; "/mknod_c-2"]]), []; - ]; - shortdesc = "make char device node"; - longdesc = "\ -This call creates a char device node called C<path> with -mode C<mode> and device major/minor C<devmajor> and C<devminor>. -It is just a convenient wrapper around C<guestfs_mknod>. - -Unlike with C<guestfs_mknod>, C<mode> B<must> contain only permissions -bits. - -The mode actually set is affected by the umask." }; - - { defaults with - name = "umask"; added = (1, 0, 55); - style = RInt "oldmask", [Int "mask"], []; - proc_nr = Some 137; - fish_output = Some FishOutputOctal; - tests = [ - InitEmpty, Always, TestResult ( - [["umask"; "0o22"]], "ret == 022"), [] - ]; - shortdesc = "set file mode creation mask (umask)"; - longdesc = "\ -This function sets the mask used for creating new files and -device nodes to C<mask & 0777>. - -Typical umask values would be C<022> which creates new files -with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and -C<002> which creates new files with permissions like -\"-rw-rw-r--\" or \"-rwxrwxr-x\". - -The default umask is C<022>. This is important because it -means that directories and device nodes will be created with -C<0644> or C<0755> mode even if you specify C<0777>. - -See also C<guestfs_get_umask>, -L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>. - -This call returns the previous umask." }; - - { defaults with - name = "readdir"; added = (1, 0, 55); - style = RStructList ("entries", "dirent"), [Pathname "dir"], []; - proc_nr = Some 138; - protocol_limit_warning = true; - shortdesc = "read directories entries"; - longdesc = "\ -This returns the list of directory entries in directory C<dir>. - -All entries in the directory are returned, including C<.> and -C<..>. The entries are I<not> sorted, but returned in the same -order as the underlying filesystem. - -Also this call returns basic file type information about each -file. The C<ftyp> field will contain one of the following characters: - -=over 4 - -=item 'b' - -Block special - -=item 'c' - -Char special - -=item 'd' - -Directory - -=item 'f' - -FIFO (named pipe) - -=item 'l' - -Symbolic link - -=item 'r' - -Regular file - -=item 's' - -Socket - -=item 'u' - -Unknown file type - -=item '?' - -The L<readdir(3)> call returned a C<d_type> field with an -unexpected value - -=back - -This function is primarily intended for use by programs. To -get a simple list of names, use C<guestfs_ls>. To get a printable -directory for human consumption, use C<guestfs_ll>." }; - - { defaults with - name = "sfdiskM"; added = (1, 0, 55); - style = RErr, [Device "device"; StringList "lines"], []; - proc_nr = Some 139; - deprecated_by = Some "part_add"; - shortdesc = "create partitions on a block device"; - longdesc = "\ -This is a simplified interface to the C<guestfs_sfdisk> -command, where partition sizes are specified in megabytes -only (rounded to the nearest cylinder) and you don't need -to specify the cyls, heads and sectors parameters which -were rarely if ever used anyway. - -See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage -and C<guestfs_part_disk>" }; - - { defaults with - name = "zfile"; added = (1, 0, 59); - style = RString "description", [String "meth"; Pathname "path"], []; - proc_nr = Some 140; - deprecated_by = Some "file"; - shortdesc = "determine file type inside a compressed file"; - longdesc = "\ -This command runs F<file> after first decompressing C<path> -using C<method>. - -C<method> must be one of C<gzip>, C<compress> or C<bzip2>. - -Since 1.0.63, use C<guestfs_file> instead which can now -process compressed files." }; - - { defaults with - name = "getxattrs"; added = (1, 0, 59); - style = RStructList ("xattrs", "xattr"), [Pathname "path"], []; - proc_nr = Some 141; - optional = Some "linuxxattrs"; - shortdesc = "list extended attributes of a file or directory"; - longdesc = "\ -This call lists the extended attributes of the file or directory -C<path>. - -At the system call level, this is a combination of the -L<listxattr(2)> and L<getxattr(2)> calls. - -See also: C<guestfs_lgetxattrs>, L<attr(5)>." }; - - { defaults with - name = "lgetxattrs"; added = (1, 0, 59); - style = RStructList ("xattrs", "xattr"), [Pathname "path"], []; - proc_nr = Some 142; - optional = Some "linuxxattrs"; - shortdesc = "list extended attributes of a file or directory"; - longdesc = "\ -This is the same as C<guestfs_getxattrs>, but if C<path> -is a symbolic link, then it returns the extended attributes -of the link itself." }; - - { defaults with - name = "setxattr"; added = (1, 0, 59); - style = RErr, [String "xattr"; - String "val"; Int "vallen"; (* will be BufferIn *) - Pathname "path"], []; - proc_nr = Some 143; - optional = Some "linuxxattrs"; - shortdesc = "set extended attribute of a file or directory"; - longdesc = "\ -This call sets the extended attribute named C<xattr> -of the file C<path> to the value C<val> (of length C<vallen>). -The value is arbitrary 8 bit data. - -See also: C<guestfs_lsetxattr>, L<attr(5)>." }; - - { defaults with - name = "lsetxattr"; added = (1, 0, 59); - style = RErr, [String "xattr"; - String "val"; Int "vallen"; (* will be BufferIn *) - Pathname "path"], []; - proc_nr = Some 144; - optional = Some "linuxxattrs"; - shortdesc = "set extended attribute of a file or directory"; - longdesc = "\ -This is the same as C<guestfs_setxattr>, but if C<path> -is a symbolic link, then it sets an extended attribute -of the link itself." }; - - { defaults with - name = "removexattr"; added = (1, 0, 59); - style = RErr, [String "xattr"; Pathname "path"], []; - proc_nr = Some 145; - optional = Some "linuxxattrs"; - shortdesc = "remove extended attribute of a file or directory"; - longdesc = "\ -This call removes the extended attribute named C<xattr> -of the file C<path>. - -See also: C<guestfs_lremovexattr>, L<attr(5)>." }; - - { defaults with - name = "lremovexattr"; added = (1, 0, 59); - style = RErr, [String "xattr"; Pathname "path"], []; - proc_nr = Some 146; - optional = Some "linuxxattrs"; - shortdesc = "remove extended attribute of a file or directory"; - longdesc = "\ -This is the same as C<guestfs_removexattr>, but if C<path> -is a symbolic link, then it removes an extended attribute -of the link itself." }; - - { defaults with - name = "mountpoints"; added = (1, 0, 62); - style = RHashtable "mps", [], []; - proc_nr = Some 147; - shortdesc = "show mountpoints"; - longdesc = "\ -This call is similar to C<guestfs_mounts>. That call returns -a list of devices. This one returns a hash table (map) of -device name to directory where the device is mounted." }; - - { defaults with - name = "mkmountpoint"; added = (1, 0, 62); - (* This is a special case: while you would expect a parameter - * of type "Pathname", that doesn't work, because it implies - * NEED_ROOT in the generated calling code in stubs.c, and - * this function cannot use NEED_ROOT. - *) - style = RErr, [String "exemptpath"], []; - proc_nr = Some 148; - shortdesc = "create a mountpoint"; - longdesc = "\ -C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are -specialized calls that can be used to create extra mountpoints -before mounting the first filesystem. - -These calls are I<only> necessary in some very limited circumstances, -mainly the case where you want to mount a mix of unrelated and/or -read-only filesystems together. - -For example, live CDs often contain a \"Russian doll\" nest of -filesystems, an ISO outer layer, with a squashfs image inside, with -an ext2/3 image inside that. You can unpack this as follows -in guestfish: - - add-ro Fedora-11-i686-Live.iso - run - mkmountpoint /cd - mkmountpoint /sqsh - mkmountpoint /ext3fs - mount /dev/sda /cd - mount-loop /cd/LiveOS/squashfs.img /sqsh - mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs - -The inner filesystem is now unpacked under the /ext3fs mountpoint. - -C<guestfs_mkmountpoint> is not compatible with C<guestfs_umount_all>. -You may get unexpected errors if you try to mix these calls. It is -safest to manually unmount filesystems and remove mountpoints after use. - -C<guestfs_umount_all> unmounts filesystems by sorting the paths -longest first, so for this to work for manual mountpoints, you -must ensure that the innermost mountpoints have the longest -pathnames, as in the example code above. - -For more details see L<https://bugzilla.redhat.com/show_bug.cgi?id=599503> - -Autosync [see C<guestfs_set_autosync>, this is set by default on -handles] can cause C<guestfs_umount_all> to be called when the handle -is closed which can also trigger these issues." }; - - { defaults with - name = "rmmountpoint"; added = (1, 0, 62); - style = RErr, [String "exemptpath"], []; - proc_nr = Some 149; - shortdesc = "remove a mountpoint"; - longdesc = "\ -This calls removes a mountpoint that was previously created -with C<guestfs_mkmountpoint>. See C<guestfs_mkmountpoint> -for full details." }; - - { defaults with - name = "grep"; added = (1, 0, 66); - style = RStringList "lines", [String "regex"; Pathname "path"], [OBool "extended"; OBool "fixed"; OBool "insensitive"; OBool "compressed"]; - proc_nr = Some 151; - protocol_limit_warning = true; once_had_no_optargs = true; - tests = [ - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt"; ""; ""; ""; ""]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "nomatch"; "/test-grep.txt"; ""; ""; ""; ""]], - "is_string_list (ret, 0)"), []; - (* Test for RHBZ#579608, absolute symbolic links. *) - InitISOFS, Always, TestResult ( - [["grep"; "nomatch"; "/abssymlink"; ""; ""; ""; ""]], - "is_string_list (ret, 0)"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt"; "true"; ""; ""; ""]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt"; ""; "true"; ""; ""]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt"; ""; ""; "true"; ""]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt"; "true"; ""; "true"; ""]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt"; ""; "true"; "true"; ""]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt.gz"; ""; ""; ""; "true"]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt.gz"; "true"; ""; ""; "true"]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt.gz"; ""; "true"; ""; "true"]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt.gz"; ""; ""; "true"; "true"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt.gz"; "true"; ""; "true"; "true"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; - InitISOFS, Always, TestResult ( - [["grep"; "abc"; "/test-grep.txt.gz"; ""; "true"; "true"; "true"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<grep> program and returns the -matching lines. - -The optional flags are: - -=over 4 - -=item C<extended> - -Use extended regular expressions. -This is the same as using the I<-E> flag. - -=item C<fixed> - -Match fixed (don't use regular expressions). -This is the same as using the I<-F> flag. - -=item C<insensitive> - -Match case-insensitive. This is the same as using the I<-i> flag. - -=item C<compressed> - -Use C<zgrep> instead of C<grep>. This allows the input to be -compress- or gzip-compressed. - -=back" }; - - { defaults with - name = "egrep"; added = (1, 0, 66); - style = RStringList "lines", [String "regex"; Pathname "path"], []; - proc_nr = Some 152; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["egrep"; "abc"; "/test-grep.txt"]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<egrep> program and returns the -matching lines." }; - - { defaults with - name = "fgrep"; added = (1, 0, 66); - style = RStringList "lines", [String "pattern"; Pathname "path"], []; - proc_nr = Some 153; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["fgrep"; "abc"; "/test-grep.txt"]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<fgrep> program and returns the -matching lines." }; - - { defaults with - name = "grepi"; added = (1, 0, 66); - style = RStringList "lines", [String "regex"; Pathname "path"], []; - proc_nr = Some 154; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["grepi"; "abc"; "/test-grep.txt"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<grep -i> program and returns the -matching lines." }; - - { defaults with - name = "egrepi"; added = (1, 0, 66); - style = RStringList "lines", [String "regex"; Pathname "path"], []; - proc_nr = Some 155; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["egrepi"; "abc"; "/test-grep.txt"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<egrep -i> program and returns the -matching lines." }; - - { defaults with - name = "fgrepi"; added = (1, 0, 66); - style = RStringList "lines", [String "pattern"; Pathname "path"], []; - proc_nr = Some 156; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["fgrepi"; "abc"; "/test-grep.txt"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<fgrep -i> program and returns the -matching lines." }; - - { defaults with - name = "zgrep"; added = (1, 0, 66); - style = RStringList "lines", [String "regex"; Pathname "path"], []; - proc_nr = Some 157; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["zgrep"; "abc"; "/test-grep.txt.gz"]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<zgrep> program and returns the -matching lines." }; - - { defaults with - name = "zegrep"; added = (1, 0, 66); - style = RStringList "lines", [String "regex"; Pathname "path"], []; - proc_nr = Some 158; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["zegrep"; "abc"; "/test-grep.txt.gz"]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<zegrep> program and returns the -matching lines." }; - - { defaults with - name = "zfgrep"; added = (1, 0, 66); - style = RStringList "lines", [String "pattern"; Pathname "path"], []; - proc_nr = Some 159; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["zfgrep"; "abc"; "/test-grep.txt.gz"]], - "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<zfgrep> program and returns the -matching lines." }; - - { defaults with - name = "zgrepi"; added = (1, 0, 66); - style = RStringList "lines", [String "regex"; Pathname "path"], []; - proc_nr = Some 160; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["zgrepi"; "abc"; "/test-grep.txt.gz"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<zgrep -i> program and returns the -matching lines." }; - - { defaults with - name = "zegrepi"; added = (1, 0, 66); - style = RStringList "lines", [String "regex"; Pathname "path"], []; - proc_nr = Some 161; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["zegrepi"; "abc"; "/test-grep.txt.gz"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<zegrep -i> program and returns the -matching lines." }; - - { defaults with - name = "zfgrepi"; added = (1, 0, 66); - style = RStringList "lines", [String "pattern"; Pathname "path"], []; - proc_nr = Some 162; - protocol_limit_warning = true; - deprecated_by = Some "grep"; - tests = [ - InitISOFS, Always, TestResult ( - [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], - "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] - ]; - shortdesc = "return lines matching a pattern"; - longdesc = "\ -This calls the external C<zfgrep -i> program and returns the -matching lines." }; - - { defaults with - name = "realpath"; added = (1, 0, 66); - style = RString "rpath", [Pathname "path"], []; - proc_nr = Some 163; - tests = [ - InitISOFS, Always, TestResultString ( - [["realpath"; "/../directory"]], "/directory"), [] - ]; - shortdesc = "canonicalized absolute pathname"; - longdesc = "\ -Return the canonicalized absolute pathname of C<path>. The -returned path has no C<.>, C<..> or symbolic link path elements." }; - - { defaults with - name = "ln"; added = (1, 0, 66); - style = RErr, [String "target"; Pathname "linkname"], []; - proc_nr = Some 164; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir"; "/ln"]; - ["touch"; "/ln/a"]; - ["ln"; "/ln/a"; "/ln/b"]; - ["stat"; "/ln/b"]], "ret->nlink == 2"), [] - ]; - shortdesc = "create a hard link"; - longdesc = "\ -This command creates a hard link using the C<ln> command." }; - - { defaults with - name = "ln_f"; added = (1, 0, 66); - style = RErr, [String "target"; Pathname "linkname"], []; - proc_nr = Some 165; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir"; "/ln_f"]; - ["touch"; "/ln_f/a"]; - ["touch"; "/ln_f/b"]; - ["ln_f"; "/ln_f/a"; "/ln_f/b"]; - ["stat"; "/ln_f/b"]], "ret->nlink == 2"), [] - ]; - shortdesc = "create a hard link"; - longdesc = "\ -This command creates a hard link using the C<ln -f> command. -The I<-f> option removes the link (C<linkname>) if it exists already." }; - - { defaults with - name = "ln_s"; added = (1, 0, 66); - style = RErr, [String "target"; Pathname "linkname"], []; - proc_nr = Some 166; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir"; "/ln_s"]; - ["touch"; "/ln_s/a"]; - ["ln_s"; "a"; "/ln_s/b"]; - ["lstat"; "/ln_s/b"]], - "S_ISLNK (ret->mode) && (ret->mode & 0777) == 0777"), [] - ]; - shortdesc = "create a symbolic link"; - longdesc = "\ -This command creates a symbolic link using the C<ln -s> command." }; - - { defaults with - name = "ln_sf"; added = (1, 0, 66); - style = RErr, [String "target"; Pathname "linkname"], []; - proc_nr = Some 167; - tests = [ - InitScratchFS, Always, TestResultString ( - [["mkdir_p"; "/ln_sf/b"]; - ["touch"; "/ln_sf/b/c"]; - ["ln_sf"; "../d"; "/ln_sf/b/c"]; - ["readlink"; "/ln_sf/b/c"]], "../d"), [] - ]; - shortdesc = "create a symbolic link"; - longdesc = "\ -This command creates a symbolic link using the C<ln -sf> command, -The I<-f> option removes the link (C<linkname>) if it exists already." }; - - { defaults with - name = "readlink"; added = (1, 0, 66); - style = RString "link", [Pathname "path"], []; - proc_nr = Some 168; - shortdesc = "read the target of a symbolic link"; - longdesc = "\ -This command reads the target of a symbolic link." }; - - { defaults with - name = "fallocate"; added = (1, 0, 66); - style = RErr, [Pathname "path"; Int "len"], []; - proc_nr = Some 169; - deprecated_by = Some "fallocate64"; - tests = [ - InitScratchFS, Always, TestResult ( - [["fallocate"; "/fallocate"; "1000000"]; - ["stat"; "/fallocate"]], "ret->size == 1000000"), [] - ]; - shortdesc = "preallocate a file in the guest filesystem"; - longdesc = "\ -This command preallocates a file (containing zero bytes) named -C<path> of size C<len> bytes. If the file exists already, it -is overwritten. - -Do not confuse this with the guestfish-specific -C<alloc> command which allocates a file in the host and -attaches it as a device." }; - - { defaults with - name = "swapon_device"; added = (1, 0, 66); - style = RErr, [Device "device"], []; - proc_nr = Some 170; - tests = [ - InitPartition, Always, TestRun ( - [["mkswap"; "/dev/sda1"; "NOARG"; "NOARG"]; - ["swapon_device"; "/dev/sda1"]; - ["swapoff_device"; "/dev/sda1"]]), [] - ]; - shortdesc = "enable swap on device"; - longdesc = "\ -This command enables the libguestfs appliance to use the -swap device or partition named C<device>. The increased -memory is made available for all commands, for example -those run using C<guestfs_command> or C<guestfs_sh>. - -Note that you should not swap to existing guest swap -partitions unless you know what you are doing. They may -contain hibernation information, or other information that -the guest doesn't want you to trash. You also risk leaking -information about the host to the guest this way. Instead, -attach a new host device to the guest and swap on that." }; - - { defaults with - name = "swapoff_device"; added = (1, 0, 66); - style = RErr, [Device "device"], []; - proc_nr = Some 171; - shortdesc = "disable swap on device"; - longdesc = "\ -This command disables the libguestfs appliance swap -device or partition named C<device>. -See C<guestfs_swapon_device>." }; - - { defaults with - name = "swapon_file"; added = (1, 0, 66); - style = RErr, [Pathname "file"], []; - proc_nr = Some 172; - tests = [ - InitScratchFS, Always, TestRun ( - [["fallocate"; "/swapon_file"; "8388608"]; - ["mkswap_file"; "/swapon_file"]; - ["swapon_file"; "/swapon_file"]; - ["swapoff_file"; "/swapon_file"]; - ["rm"; "/swapon_file"]]), [] - ]; - shortdesc = "enable swap on file"; - longdesc = "\ -This command enables swap to a file. -See C<guestfs_swapon_device> for other notes." }; - - { defaults with - name = "swapoff_file"; added = (1, 0, 66); - style = RErr, [Pathname "file"], []; - proc_nr = Some 173; - shortdesc = "disable swap on file"; - longdesc = "\ -This command disables the libguestfs appliance swap on file." }; - - { defaults with - name = "swapon_label"; added = (1, 0, 66); - style = RErr, [String "label"], []; - proc_nr = Some 174; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkswap"; "/dev/sda1"; "swapit"; "NOARG"]; - ["swapon_label"; "swapit"]; - ["swapoff_label"; "swapit"]; - ["zero"; "/dev/sda"]; - ["blockdev_rereadpt"; "/dev/sda"]]), [] - ]; - shortdesc = "enable swap on labeled swap partition"; - longdesc = "\ -This command enables swap to a labeled swap partition. -See C<guestfs_swapon_device> for other notes." }; - - { defaults with - name = "swapoff_label"; added = (1, 0, 66); - style = RErr, [String "label"], []; - proc_nr = Some 175; - shortdesc = "disable swap on labeled swap partition"; - longdesc = "\ -This command disables the libguestfs appliance swap on -labeled swap partition." }; - - { defaults with - name = "swapon_uuid"; added = (1, 0, 66); - style = RErr, [String "uuid"], []; - proc_nr = Some 176; - optional = Some "linuxfsuuid"; - tests = [ - InitEmpty, Always, TestRun ( - [["mkswap"; "/dev/sdc"; "NOARG"; stable_uuid]; - ["swapon_uuid"; stable_uuid]; - ["swapoff_uuid"; stable_uuid]]), [] - ]; - shortdesc = "enable swap on swap partition by UUID"; - longdesc = "\ -This command enables swap to a swap partition with the given UUID. -See C<guestfs_swapon_device> for other notes." }; - - { defaults with - name = "swapoff_uuid"; added = (1, 0, 66); - style = RErr, [String "uuid"], []; - proc_nr = Some 177; - optional = Some "linuxfsuuid"; - shortdesc = "disable swap on swap partition by UUID"; - longdesc = "\ -This command disables the libguestfs appliance swap partition -with the given UUID." }; - - { defaults with - name = "mkswap_file"; added = (1, 0, 66); - style = RErr, [Pathname "path"], []; - proc_nr = Some 178; - tests = [ - InitScratchFS, Always, TestRun ( - [["fallocate"; "/mkswap_file"; "8388608"]; - ["mkswap_file"; "/mkswap_file"]; - ["rm"; "/mkswap_file"]]), [] - ]; - shortdesc = "create a swap file"; - longdesc = "\ -Create a swap file. - -This command just writes a swap file signature to an existing -file. To create the file itself, use something like C<guestfs_fallocate>." }; - - { defaults with - name = "inotify_init"; added = (1, 0, 66); - style = RErr, [Int "maxevents"], []; - proc_nr = Some 179; - optional = Some "inotify"; - tests = [ - InitISOFS, Always, TestRun ( - [["inotify_init"; "0"]]), [] - ]; - shortdesc = "create an inotify handle"; - longdesc = "\ -This command creates a new inotify handle. -The inotify subsystem can be used to notify events which happen to -objects in the guest filesystem. - -C<maxevents> is the maximum number of events which will be -queued up between calls to C<guestfs_inotify_read> or -C<guestfs_inotify_files>. -If this is passed as C<0>, then the kernel (or previously set) -default is used. For Linux 2.6.29 the default was 16384 events. -Beyond this limit, the kernel throws away events, but records -the fact that it threw them away by setting a flag -C<IN_Q_OVERFLOW> in the returned structure list (see -C<guestfs_inotify_read>). - -Before any events are generated, you have to add some -watches to the internal watch list. See: C<guestfs_inotify_add_watch> and -C<guestfs_inotify_rm_watch>. - -Queued up events should be read periodically by calling -C<guestfs_inotify_read> -(or C<guestfs_inotify_files> which is just a helpful -wrapper around C<guestfs_inotify_read>). If you don't -read the events out often enough then you risk the internal -queue overflowing. - -The handle should be closed after use by calling -C<guestfs_inotify_close>. This also removes any -watches automatically. - -See also L<inotify(7)> for an overview of the inotify interface -as exposed by the Linux kernel, which is roughly what we expose -via libguestfs. Note that there is one global inotify handle -per libguestfs instance." }; - - { defaults with - name = "inotify_add_watch"; added = (1, 0, 66); - style = RInt64 "wd", [Pathname "path"; Int "mask"], []; - proc_nr = Some 180; - optional = Some "inotify"; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir"; "/inotify_add_watch"]; - ["inotify_init"; "0"]; - ["inotify_add_watch"; "/inotify_add_watch"; "4095"]; - ["touch"; "/inotify_add_watch/a"]; - ["touch"; "/inotify_add_watch/b"]; - ["inotify_files"]], - "is_string_list (ret, 2, \"a\", \"b\")"), [] - ]; - shortdesc = "add an inotify watch"; - longdesc = "\ -Watch C<path> for the events listed in C<mask>. - -Note that if C<path> is a directory then events within that -directory are watched, but this does I<not> happen recursively -(in subdirectories). - -Note for non-C or non-Linux callers: the inotify events are -defined by the Linux kernel ABI and are listed in -F</usr/include/sys/inotify.h>." }; - - { defaults with - name = "inotify_rm_watch"; added = (1, 0, 66); - style = RErr, [Int(*XXX64*) "wd"], []; - proc_nr = Some 181; - optional = Some "inotify"; - shortdesc = "remove an inotify watch"; - longdesc = "\ -Remove a previously defined inotify watch. -See C<guestfs_inotify_add_watch>." }; - - { defaults with - name = "inotify_read"; added = (1, 0, 66); - style = RStructList ("events", "inotify_event"), [], []; - proc_nr = Some 182; - optional = Some "inotify"; - shortdesc = "return list of inotify events"; - longdesc = "\ -Return the complete queue of events that have happened -since the previous read call. - -If no events have happened, this returns an empty list. - -I<Note>: In order to make sure that all events have been -read, you must call this function repeatedly until it -returns an empty list. The reason is that the call will -read events up to the maximum appliance-to-host message -size and leave remaining events in the queue." }; - - { defaults with - name = "inotify_files"; added = (1, 0, 66); - style = RStringList "paths", [], []; - proc_nr = Some 183; - optional = Some "inotify"; - shortdesc = "return list of watched files that had events"; - longdesc = "\ -This function is a helpful wrapper around C<guestfs_inotify_read> -which just returns a list of pathnames of objects that were -touched. The returned pathnames are sorted and deduplicated." }; - - { defaults with - name = "inotify_close"; added = (1, 0, 66); - style = RErr, [], []; - proc_nr = Some 184; - optional = Some "inotify"; - shortdesc = "close the inotify handle"; - longdesc = "\ -This closes the inotify handle which was previously -opened by inotify_init. It removes all watches, throws -away any pending events, and deallocates all resources." }; - - { defaults with - name = "setcon"; added = (1, 0, 67); - style = RErr, [String "context"], []; - proc_nr = Some 185; - optional = Some "selinux"; - deprecated_by = Some "selinux_relabel"; - shortdesc = "set SELinux security context"; - longdesc = "\ -This sets the SELinux security context of the daemon -to the string C<context>. - -See the documentation about SELINUX in L<guestfs(3)>." }; - - { defaults with - name = "getcon"; added = (1, 0, 67); - style = RString "context", [], []; - proc_nr = Some 186; - optional = Some "selinux"; - deprecated_by = Some "selinux_relabel"; - shortdesc = "get SELinux security context"; - longdesc = "\ -This gets the SELinux security context of the daemon. - -See the documentation about SELINUX in L<guestfs(3)>, -and C<guestfs_setcon>" }; - - { defaults with - name = "mkfs_b"; added = (1, 0, 68); - style = RErr, [String "fstype"; Int "blocksize"; Device "device"], []; - proc_nr = Some 187; - deprecated_by = Some "mkfs"; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs_b"; "ext2"; "4096"; "/dev/sda1"]; - ["mount"; "/dev/sda1"; "/"]; - ["write"; "/new"; "new file contents"]; - ["cat"; "/new"]], "new file contents"), []; - InitEmpty, Always, TestRun ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["mkfs_b"; "vfat"; "32768"; "/dev/sda1"]]), []; - InitEmpty, Always, TestLastFail ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["mkfs_b"; "vfat"; "32769"; "/dev/sda1"]]), []; - InitEmpty, Always, TestLastFail ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["mkfs_b"; "vfat"; "33280"; "/dev/sda1"]]), []; - InitEmpty, IfAvailable "ntfsprogs", TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs_b"; "ntfs"; "32768"; "/dev/sda1"]]), [] - ]; - shortdesc = "make a filesystem with block size"; - longdesc = "\ -This call is similar to C<guestfs_mkfs>, but it allows you to -control the block size of the resulting filesystem. Supported -block sizes depend on the filesystem type, but typically they -are C<1024>, C<2048> or C<4096> only. - -For VFAT and NTFS the C<blocksize> parameter is treated as -the requested cluster size." }; - - { defaults with - name = "mke2journal"; added = (1, 0, 68); - style = RErr, [Int "blocksize"; Device "device"], []; - proc_nr = Some 188; - deprecated_by = Some "mke2fs"; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; - ["mke2journal"; "4096"; "/dev/sda1"]; - ["mke2fs_J"; "ext2"; "4096"; "/dev/sda2"; "/dev/sda1"]; - ["mount"; "/dev/sda2"; "/"]; - ["write"; "/new"; "new file contents"]; - ["cat"; "/new"]], "new file contents"), [] - ]; - shortdesc = "make ext2/3/4 external journal"; - longdesc = "\ -This creates an ext2 external journal on C<device>. It is equivalent -to the command: - - mke2fs -O journal_dev -b blocksize device" }; - - { defaults with - name = "mke2journal_L"; added = (1, 0, 68); - style = RErr, [Int "blocksize"; String "label"; Device "device"], []; - proc_nr = Some 189; - deprecated_by = Some "mke2fs"; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; - ["mke2journal_L"; "4096"; "JOURNAL"; "/dev/sda1"]; - ["mke2fs_JL"; "ext2"; "4096"; "/dev/sda2"; "JOURNAL"]; - ["mount"; "/dev/sda2"; "/"]; - ["write"; "/new"; "new file contents"]; - ["cat"; "/new"]], "new file contents"), [] - ]; - shortdesc = "make ext2/3/4 external journal with label"; - longdesc = "\ -This creates an ext2 external journal on C<device> with label C<label>." }; - - { defaults with - name = "mke2journal_U"; added = (1, 0, 68); - style = RErr, [Int "blocksize"; String "uuid"; Device "device"], []; - proc_nr = Some 190; - deprecated_by = Some "mke2fs"; - optional = Some "linuxfsuuid"; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; - ["mke2journal_U"; "4096"; stable_uuid; "/dev/sda1"]; - ["mke2fs_JU"; "ext2"; "4096"; "/dev/sda2"; stable_uuid]; - ["mount"; "/dev/sda2"; "/"]; - ["write"; "/new"; "new file contents"]; - ["cat"; "/new"]], "new file contents"), [] - ]; - shortdesc = "make ext2/3/4 external journal with UUID"; - longdesc = "\ -This creates an ext2 external journal on C<device> with UUID C<uuid>." }; - - { defaults with - name = "mke2fs_J"; added = (1, 0, 68); - style = RErr, [String "fstype"; Int "blocksize"; Device "device"; Device "journal"], []; - proc_nr = Some 191; - deprecated_by = Some "mke2fs"; - shortdesc = "make ext2/3/4 filesystem with external journal"; - longdesc = "\ -This creates an ext2/3/4 filesystem on C<device> with -an external journal on C<journal>. It is equivalent -to the command: - - mke2fs -t fstype -b blocksize -J device=<journal> <device> - -See also C<guestfs_mke2journal>." }; - - { defaults with - name = "mke2fs_JL"; added = (1, 0, 68); - style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "label"], []; - proc_nr = Some 192; - deprecated_by = Some "mke2fs"; - shortdesc = "make ext2/3/4 filesystem with external journal"; - longdesc = "\ -This creates an ext2/3/4 filesystem on C<device> with -an external journal on the journal labeled C<label>. - -See also C<guestfs_mke2journal_L>." }; - - { defaults with - name = "mke2fs_JU"; added = (1, 0, 68); - style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "uuid"], []; - proc_nr = Some 193; - deprecated_by = Some "mke2fs"; - optional = Some "linuxfsuuid"; - shortdesc = "make ext2/3/4 filesystem with external journal"; - longdesc = "\ -This creates an ext2/3/4 filesystem on C<device> with -an external journal on the journal with UUID C<uuid>. - -See also C<guestfs_mke2journal_U>." }; - - { defaults with - name = "modprobe"; added = (1, 0, 68); - style = RErr, [String "modulename"], []; - proc_nr = Some 194; - optional = Some "linuxmodules"; - tests = [ - InitNone, Always, TestRun [["modprobe"; "fat"]], [] - ]; - shortdesc = "load a kernel module"; - longdesc = "\ -This loads a kernel module in the appliance." }; - - { defaults with - name = "echo_daemon"; added = (1, 0, 69); - style = RString "output", [StringList "words"], []; - proc_nr = Some 195; - tests = [ - InitNone, Always, TestResultString ( - [["echo_daemon"; "This is a test"]], "This is a test"), []; - InitNone, Always, TestResultString ( - [["echo_daemon"; ""]], ""), []; - ]; - shortdesc = "echo arguments back to the client"; - longdesc = "\ -This command concatenates the list of C<words> passed with single spaces -between them and returns the resulting string. - -You can use this command to test the connection through to the daemon. - -See also C<guestfs_ping_daemon>." }; - - { defaults with - name = "find0"; added = (1, 0, 74); - style = RErr, [Pathname "directory"; FileOut "files"], []; - proc_nr = Some 196; - cancellable = true; - test_excuse = "there is a regression test for this"; - shortdesc = "find all files and directories, returning NUL-separated list"; - longdesc = "\ -This command lists out all files and directories, recursively, -starting at F<directory>, placing the resulting list in the -external file called F<files>. - -This command works the same way as C<guestfs_find> with the -following exceptions: - -=over 4 - -=item * - -The resulting list is written to an external file. - -=item * - -Items (filenames) in the result are separated -by C<\\0> characters. See L<find(1)> option I<-print0>. - -=item * - -The result list is not sorted. - -=back" }; - - { defaults with - name = "case_sensitive_path"; added = (1, 0, 75); - style = RString "rpath", [Pathname "path"], []; - proc_nr = Some 197; - tests = [ - InitISOFS, Always, TestResultString ( - [["case_sensitive_path"; "/DIRECTORY"]], "/directory"), []; - InitISOFS, Always, TestResultString ( - [["case_sensitive_path"; "/DIRECTORY/"]], "/directory"), []; - InitISOFS, Always, TestResultString ( - [["case_sensitive_path"; "/Known-1"]], "/known-1"), []; - InitISOFS, Always, TestLastFail ( - [["case_sensitive_path"; "/Known-1/"]]), []; - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/case_sensitive_path"]; - ["mkdir"; "/case_sensitive_path/bbb"]; - ["touch"; "/case_sensitive_path/bbb/c"]; - ["case_sensitive_path"; "/CASE_SENSITIVE_path/bbB/C"]], "/case_sensitive_path/bbb/c"), []; - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/case_sensitive_path2"]; - ["mkdir"; "/case_sensitive_path2/bbb"]; - ["touch"; "/case_sensitive_path2/bbb/c"]; - ["case_sensitive_path"; "/case_sensitive_PATH2////bbB/C"]], "/case_sensitive_path2/bbb/c"), []; - InitScratchFS, Always, TestLastFail ( - [["mkdir"; "/case_sensitive_path3"]; - ["mkdir"; "/case_sensitive_path3/bbb"]; - ["touch"; "/case_sensitive_path3/bbb/c"]; - ["case_sensitive_path"; "/case_SENSITIVE_path3/bbb/../bbb/C"]]), []; - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/case_sensitive_path4"]; - ["case_sensitive_path"; "/case_SENSITIVE_path4/new_file"]], "/case_sensitive_path4/new_file"), [] - ]; - shortdesc = "return true path on case-insensitive filesystem"; - longdesc = "\ -This can be used to resolve case insensitive paths on -a filesystem which is case sensitive. The use case is -to resolve paths which you have read from Windows configuration -files or the Windows Registry, to the true path. - -The command handles a peculiarity of the Linux ntfs-3g -filesystem driver (and probably others), which is that although -the underlying filesystem is case-insensitive, the driver -exports the filesystem to Linux as case-sensitive. - -One consequence of this is that special directories such -as F<C:\\windows> may appear as F</WINDOWS> or F</windows> -(or other things) depending on the precise details of how -they were created. In Windows itself this would not be -a problem. - -Bug or feature? You decide: -L<http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1> - -C<guestfs_case_sensitive_path> attempts to resolve the true case of -each element in the path. It will return a resolved path if either the -full path or its parent directory exists. If the parent directory -exists but the full path does not, the case of the parent directory -will be correctly resolved, and the remainder appended unmodified. For -example, if the file C<\"/Windows/System32/netkvm.sys\"> exists: - -=over 4 - -=item C<guestfs_case_sensitive_path> (\"/windows/system32/netkvm.sys\") - -\"Windows/System32/netkvm.sys\" - -=item C<guestfs_case_sensitive_path> (\"/windows/system32/NoSuchFile\") - -\"Windows/System32/NoSuchFile\" - -=item C<guestfs_case_sensitive_path> (\"/windows/system33/netkvm.sys\") - -I<ERROR> - -=back - -I<Note>: -Because of the above behaviour, C<guestfs_case_sensitive_path> cannot -be used to check for the existence of a file. - -I<Note>: -This function does not handle drive names, backslashes etc. - -See also C<guestfs_realpath>." }; - - { defaults with - name = "vfs_type"; added = (1, 0, 75); - style = RString "fstype", [Mountable "mountable"], []; - proc_nr = Some 198; - tests = [ - InitScratchFS, Always, TestResultString ( - [["vfs_type"; "/dev/sdb1"]], "ext2"), [] - ]; - shortdesc = "get the Linux VFS type corresponding to a mounted device"; - longdesc = "\ -This command gets the filesystem type corresponding to -the filesystem on C<mountable>. - -For most filesystems, the result is the name of the Linux -VFS module which would be used to mount this filesystem -if you mounted it without specifying the filesystem type. -For example a string such as C<ext3> or C<ntfs>." }; - - { defaults with - name = "truncate"; added = (1, 0, 77); - style = RErr, [Pathname "path"], []; - proc_nr = Some 199; - tests = [ - InitScratchFS, Always, TestResult ( - [["write"; "/truncate"; "some stuff so size is not zero"]; - ["truncate"; "/truncate"]; - ["stat"; "/truncate"]], "ret->size == 0"), [] - ]; - shortdesc = "truncate a file to zero size"; - longdesc = "\ -This command truncates C<path> to a zero-length file. The -file must exist already." }; - - { defaults with - name = "truncate_size"; added = (1, 0, 77); - style = RErr, [Pathname "path"; Int64 "size"], []; - proc_nr = Some 200; - tests = [ - InitScratchFS, Always, TestResult ( - [["touch"; "/truncate_size"]; - ["truncate_size"; "/truncate_size"; "1000"]; - ["stat"; "/truncate_size"]], "ret->size == 1000"), [] - ]; - shortdesc = "truncate a file to a particular size"; - longdesc = "\ -This command truncates C<path> to size C<size> bytes. The file -must exist already. - -If the current file size is less than C<size> then -the file is extended to the required size with zero bytes. -This creates a sparse file (ie. disk blocks are not allocated -for the file until you write to it). To create a non-sparse -file of zeroes, use C<guestfs_fallocate64> instead." }; - - { defaults with - name = "utimens"; added = (1, 0, 77); - style = RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"], []; - proc_nr = Some 201; - (* Test directories, named pipes etc (RHBZ#761451, RHBZ#761460) *) - tests = [ - InitScratchFS, Always, TestResult ( - [["touch"; "/utimens-file"]; - ["utimens"; "/utimens-file"; "12345"; "67890"; "9876"; "5432"]; - ["stat"; "/utimens-file"]], "ret->mtime == 9876"), []; - InitScratchFS, Always, TestResult ( - [["mkdir"; "/utimens-dir"]; - ["utimens"; "/utimens-dir"; "12345"; "67890"; "9876"; "5432"]; - ["stat"; "/utimens-dir"]], "ret->mtime == 9876"), []; - InitScratchFS, Always, TestResult ( - [["mkfifo"; "0o644"; "/utimens-fifo"]; - ["utimens"; "/utimens-fifo"; "12345"; "67890"; "9876"; "5432"]; - ["stat"; "/utimens-fifo"]], "ret->mtime == 9876"), []; - InitScratchFS, Always, TestResult ( - [["ln_sf"; "/utimens-file"; "/utimens-link"]; - ["utimens"; "/utimens-link"; "12345"; "67890"; "9876"; "5432"]; - ["stat"; "/utimens-link"]], "ret->mtime == 9876"), []; - InitScratchFS, Always, TestResult ( - [["mknod_b"; "0o644"; "8"; "0"; "/utimens-block"]; - ["utimens"; "/utimens-block"; "12345"; "67890"; "9876"; "5432"]; - ["stat"; "/utimens-block"]], "ret->mtime == 9876"), []; - InitScratchFS, Always, TestResult ( - [["mknod_c"; "0o644"; "1"; "3"; "/utimens-char"]; - ["utimens"; "/utimens-char"; "12345"; "67890"; "9876"; "5432"]; - ["stat"; "/utimens-char"]], "ret->mtime == 9876"), [] - ]; - shortdesc = "set timestamp of a file with nanosecond precision"; - longdesc = "\ -This command sets the timestamps of a file with nanosecond -precision. - -C<atsecs, atnsecs> are the last access time (atime) in secs and -nanoseconds from the epoch. - -C<mtsecs, mtnsecs> are the last modification time (mtime) in -secs and nanoseconds from the epoch. - -If the C<*nsecs> field contains the special value C<-1> then -the corresponding timestamp is set to the current time. (The -C<*secs> field is ignored in this case). - -If the C<*nsecs> field contains the special value C<-2> then -the corresponding timestamp is left unchanged. (The -C<*secs> field is ignored in this case)." }; - - { defaults with - name = "mkdir_mode"; added = (1, 0, 77); - style = RErr, [Pathname "path"; Int "mode"], []; - proc_nr = Some 202; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir_mode"; "/mkdir_mode"; "0o111"]; - ["stat"; "/mkdir_mode"]], - "S_ISDIR (ret->mode) && (ret->mode & 0777) == 0111"), [] - ]; - shortdesc = "create a directory with a particular mode"; - longdesc = "\ -This command creates a directory, setting the initial permissions -of the directory to C<mode>. - -For common Linux filesystems, the actual mode which is set will -be C<mode & ~umask & 01777>. Non-native-Linux filesystems may -interpret the mode in other ways. - -See also C<guestfs_mkdir>, C<guestfs_umask>" }; - - { defaults with - name = "lchown"; added = (1, 0, 77); - style = RErr, [Int "owner"; Int "group"; Pathname "path"], []; - proc_nr = Some 203; - shortdesc = "change file owner and group"; - longdesc = "\ -Change the file owner to C<owner> and group to C<group>. -This is like C<guestfs_chown> but if C<path> is a symlink then -the link itself is changed, not the target. - -Only numeric uid and gid are supported. If you want to use -names, you will need to locate and parse the password file -yourself (Augeas support makes this relatively easy)." }; - - { defaults with - name = "internal_lxattrlist"; added = (1, 19, 32); - style = RStructList ("xattrs", "xattr"), [Pathname "path"; FilenameList "names"], []; - proc_nr = Some 205; - visibility = VInternal; - 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<path>. -C<names> 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<attrname>. C<attrval> in this struct is zero-length -to indicate there was an error doing C<lgetxattr> for this -file, I<or> 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<guestfs_lstatlist> for a similarly efficient call -for getting standard stats. Very long directory listings -might cause the protocol message size to be exceeded, causing -this call to fail. The caller must split up such requests -into smaller groups of names." }; - - { defaults with - name = "internal_readlinklist"; added = (1, 19, 32); - style = RStringList "links", [Pathname "path"; FilenameList "names"], []; - proc_nr = Some 206; - visibility = VInternal; - shortdesc = "readlink on multiple files"; - longdesc = "\ -This call allows you to do a C<readlink> operation -on multiple files, where all files are in the directory C<path>. -C<names> 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<names> list. Each string is the -value of the symbolic link. - -If the L<readlink(2)> 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 L<readlink(2)> 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. -Very long directory listings might cause the protocol -message size to be exceeded, causing -this call to fail. The caller must split up such requests -into smaller groups of names." }; - - { defaults with - name = "pread"; added = (1, 0, 77); - style = RBufferOut "content", [Pathname "path"; Int "count"; Int64 "offset"], []; - proc_nr = Some 207; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResult ( - [["pread"; "/known-4"; "1"; "3"]], - "compare_buffers (ret, size, \"\\n\", 1) == 0"), []; - InitISOFS, Always, TestResult ( - [["pread"; "/empty"; "0"; "100"]], - "compare_buffers (ret, size, NULL, 0) == 0"), [] - ]; - shortdesc = "read part of a file"; - longdesc = "\ -This command lets you read part of a file. It reads C<count> -bytes of the file, starting at C<offset>, from file C<path>. - -This may read fewer bytes than requested. For further details -see the L<pread(2)> system call. - -See also C<guestfs_pwrite>, C<guestfs_pread_device>." }; - - { defaults with - name = "part_init"; added = (1, 0, 78); - style = RErr, [Device "device"; String "parttype"], []; - proc_nr = Some 208; - tests = [ - InitEmpty, Always, TestRun ( - [["part_init"; "/dev/sda"; "gpt"]]), [] - ]; - shortdesc = "create an empty partition table"; - longdesc = "\ -This creates an empty partition table on C<device> of one of the -partition types listed below. Usually C<parttype> should be -either C<msdos> or C<gpt> (for large disks). - -Initially there are no partitions. Following this, you should -call C<guestfs_part_add> for each partition required. - -Possible values for C<parttype> are: - -=over 4 - -=item B<efi> - -=item B<gpt> - -Intel EFI / GPT partition table. - -This is recommended for >= 2 TB partitions that will be accessed -from Linux and Intel-based Mac OS X. It also has limited backwards -compatibility with the C<mbr> format. - -=item B<mbr> - -=item B<msdos> - -The standard PC \"Master Boot Record\" (MBR) format used -by MS-DOS and Windows. This partition type will B<only> work -for device sizes up to 2 TB. For large disks we recommend -using C<gpt>. - -=back - -Other partition table types that may work but are not -supported include: - -=over 4 - -=item B<aix> - -AIX disk labels. - -=item B<amiga> - -=item B<rdb> - -Amiga \"Rigid Disk Block\" format. - -=item B<bsd> - -BSD disk labels. - -=item B<dasd> - -DASD, used on IBM mainframes. - -=item B<dvh> - -MIPS/SGI volumes. - -=item B<mac> - -Old Mac partition format. Modern Macs use C<gpt>. - -=item B<pc98> - -NEC PC-98 format, common in Japan apparently. - -=item B<sun> - -Sun disk labels. - -=back" }; - - { defaults with - name = "part_add"; added = (1, 0, 78); - style = RErr, [Device "device"; String "prlogex"; Int64 "startsect"; Int64 "endsect"], []; - proc_nr = Some 209; - tests = [ - InitEmpty, Always, TestRun ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]]), []; - InitEmpty, Always, TestRun ( - [["part_init"; "/dev/sda"; "gpt"]; - ["part_add"; "/dev/sda"; "primary"; "34"; "127"]; - ["part_add"; "/dev/sda"; "primary"; "128"; "-34"]]), []; - InitEmpty, Always, TestRun ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "primary"; "32"; "127"]; - ["part_add"; "/dev/sda"; "primary"; "128"; "255"]; - ["part_add"; "/dev/sda"; "primary"; "256"; "511"]; - ["part_add"; "/dev/sda"; "primary"; "512"; "-1"]]), [] - ]; - shortdesc = "add a partition to the device"; - longdesc = "\ -This command adds a partition to C<device>. If there is no partition -table on the device, call C<guestfs_part_init> first. - -The C<prlogex> parameter is the type of partition. Normally you -should pass C<p> or C<primary> here, but MBR partition tables also -support C<l> (or C<logical>) and C<e> (or C<extended>) partition -types. - -C<startsect> and C<endsect> are the start and end of the partition -in I<sectors>. C<endsect> may be negative, which means it counts -backwards from the end of the disk (C<-1> is the last sector). - -Creating a partition which covers the whole disk is not so easy. -Use C<guestfs_part_disk> to do that." }; - - { defaults with - name = "part_disk"; added = (1, 0, 78); - style = RErr, [Device "device"; String "parttype"], []; - proc_nr = Some 210; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]]), []; - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "gpt"]]), [] - ]; - shortdesc = "partition whole disk with a single primary partition"; - longdesc = "\ -This command is simply a combination of C<guestfs_part_init> -followed by C<guestfs_part_add> to create a single primary partition -covering the whole disk. - -C<parttype> is the partition table type, usually C<mbr> or C<gpt>, -but other possible values are described in C<guestfs_part_init>." }; - - { defaults with - name = "part_set_bootable"; added = (1, 0, 78); - style = RErr, [Device "device"; Int "partnum"; Bool "bootable"], []; - proc_nr = Some 211; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["part_set_bootable"; "/dev/sda"; "1"; "true"]]), [] - ]; - shortdesc = "make a partition bootable"; - longdesc = "\ -This sets the bootable flag on partition numbered C<partnum> on -device C<device>. Note that partitions are numbered from 1. - -The bootable flag is used by some operating systems (notably -Windows) to determine which partition to boot from. It is by -no means universally recognized." }; - - { defaults with - name = "part_set_name"; added = (1, 0, 78); - style = RErr, [Device "device"; Int "partnum"; String "name"], []; - proc_nr = Some 212; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "gpt"]; - ["part_set_name"; "/dev/sda"; "1"; "thepartname"]]), [] - ]; - shortdesc = "set partition name"; - longdesc = "\ -This sets the partition name on partition numbered C<partnum> on -device C<device>. Note that partitions are numbered from 1. - -The partition name can only be set on certain types of partition -table. This works on C<gpt> but not on C<mbr> partitions." }; - - { defaults with - name = "part_list"; added = (1, 0, 78); - style = RStructList ("partitions", "partition"), [Device "device"], []; - proc_nr = Some 213; - tests = [] (* XXX Add a regression test for this. *); - shortdesc = "list partitions on a device"; - longdesc = "\ -This command parses the partition table on C<device> and -returns the list of partitions found. - -The fields in the returned structure are: - -=over 4 - -=item B<part_num> - -Partition number, counting from 1. - -=item B<part_start> - -Start of the partition I<in bytes>. To get sectors you have to -divide by the device's sector size, see C<guestfs_blockdev_getss>. - -=item B<part_end> - -End of the partition in bytes. - -=item B<part_size> - -Size of the partition in bytes. - -=back" }; - - { defaults with - name = "part_get_parttype"; added = (1, 0, 78); - style = RString "parttype", [Device "device"], []; - proc_nr = Some 214; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "gpt"]; - ["part_get_parttype"; "/dev/sda"]], "gpt"), [] - ]; - shortdesc = "get the partition table type"; - longdesc = "\ -This command examines the partition table on C<device> and -returns the partition table type (format) being used. - -Common return values include: C<msdos> (a DOS/Windows style MBR -partition table), C<gpt> (a GPT/EFI-style partition table). Other -values are possible, although unusual. See C<guestfs_part_init> -for a full list." }; - - { defaults with - name = "fill"; added = (1, 0, 79); - style = RErr, [Int "c"; Int "len"; Pathname "path"], []; - proc_nr = Some 215; - progress = true; - tests = [ - InitScratchFS, Always, TestResult ( - [["fill"; "0x63"; "10"; "/fill"]; - ["read_file"; "/fill"]], - "compare_buffers (ret, size, \"cccccccccc\", 10) == 0"), [] - ]; - shortdesc = "fill a file with octets"; - longdesc = "\ -This command creates a new file called C<path>. The initial -content of the file is C<len> octets of C<c>, where C<c> -must be a number in the range C<[0..255]>. - -To fill a file with zero bytes (sparsely), it is -much more efficient to use C<guestfs_truncate_size>. -To create a file with a pattern of repeating bytes -use C<guestfs_fill_pattern>." }; - - { defaults with - name = "dd"; added = (1, 0, 80); - style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"], []; - proc_nr = Some 217; - deprecated_by = Some "copy_device_to_device"; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir"; "/dd"]; - ["write"; "/dd/src"; "hello, world"]; - ["dd"; "/dd/src"; "/dd/dest"]; - ["read_file"; "/dd/dest"]], - "compare_buffers (ret, size, \"hello, world\", 12) == 0"), [] - ]; - shortdesc = "copy from source to destination using dd"; - longdesc = "\ -This command copies from one source device or file C<src> -to another destination device or file C<dest>. Normally you -would use this to copy to or from a device or partition, for -example to duplicate a filesystem. - -If the destination is a device, it must be as large or larger -than the source file or device, otherwise the copy will fail. -This command cannot do partial copies -(see C<guestfs_copy_device_to_device>)." }; - - { defaults with - name = "filesize"; added = (1, 0, 82); - style = RInt64 "size", [Pathname "file"], []; - proc_nr = Some 218; - tests = [ - InitScratchFS, Always, TestResult ( - [["write"; "/filesize"; "hello, world"]; - ["filesize"; "/filesize"]], "ret == 12"), [] - ]; - shortdesc = "return the size of the file in bytes"; - longdesc = "\ -This command returns the size of F<file> in bytes. - -To get other stats about a file, use C<guestfs_stat>, C<guestfs_lstat>, -C<guestfs_is_dir>, C<guestfs_is_file> etc. -To get the size of block devices, use C<guestfs_blockdev_getsize64>." }; - - { defaults with - name = "lvrename"; added = (1, 0, 83); - style = RErr, [String "logvol"; String "newlogvol"], []; - proc_nr = Some 219; - tests = [ - InitBasicFSonLVM, Always, TestResult ( - [["lvrename"; "/dev/VG/LV"; "/dev/VG/LV2"]; - ["lvs"]], - "is_string_list (ret, 1, \"/dev/VG/LV2\")"), [] - ]; - shortdesc = "rename an LVM logical volume"; - longdesc = "\ -Rename a logical volume C<logvol> with the new name C<newlogvol>." }; - - { defaults with - name = "vgrename"; added = (1, 0, 83); - style = RErr, [String "volgroup"; String "newvolgroup"], []; - proc_nr = Some 220; - tests = [ - InitBasicFSonLVM, Always, TestResult ( - [["umount"; "/"; "false"; "false"]; - ["vg_activate"; "false"; "VG"]; - ["vgrename"; "VG"; "VG2"]; - ["vg_activate"; "true"; "VG2"]; - ["mount"; "/dev/VG2/LV"; "/"]; - ["vgs"]], - "is_string_list (ret, 1, \"VG2\")"), [] - ]; - shortdesc = "rename an LVM volume group"; - longdesc = "\ -Rename a volume group C<volgroup> with the new name C<newvolgroup>." }; - - { defaults with - name = "initrd_cat"; added = (1, 0, 84); - style = RBufferOut "content", [Pathname "initrdpath"; String "filename"], []; - proc_nr = Some 221; - protocol_limit_warning = true; - tests = [ - InitISOFS, Always, TestResult ( - [["initrd_cat"; "/initrd"; "known-4"]], - "compare_buffers (ret, size, \"abc\\ndef\\nghi\", 11) == 0"), [] - ]; - shortdesc = "list the contents of a single file in an initrd"; - longdesc = "\ -This command unpacks the file F<filename> from the initrd file -called F<initrdpath>. The filename must be given I<without> the -initial F</> character. - -For example, in guestfish you could use the following command -to examine the boot script (usually called F</init>) -contained in a Linux initrd or initramfs image: - - initrd-cat /boot/initrd-<version>.img init - -See also C<guestfs_initrd_list>." }; - - { defaults with - name = "pvuuid"; added = (1, 0, 87); - style = RString "uuid", [Device "device"], []; - proc_nr = Some 222; - shortdesc = "get the UUID of a physical volume"; - longdesc = "\ -This command returns the UUID of the LVM PV C<device>." }; - - { defaults with - name = "vguuid"; added = (1, 0, 87); - style = RString "uuid", [String "vgname"], []; - proc_nr = Some 223; - shortdesc = "get the UUID of a volume group"; - longdesc = "\ -This command returns the UUID of the LVM VG named C<vgname>." }; - - { defaults with - name = "lvuuid"; added = (1, 0, 87); - style = RString "uuid", [Device "device"], []; - proc_nr = Some 224; - shortdesc = "get the UUID of a logical volume"; - longdesc = "\ -This command returns the UUID of the LVM LV C<device>." }; - - { defaults with - name = "vgpvuuids"; added = (1, 0, 87); - style = RStringList "uuids", [String "vgname"], []; - proc_nr = Some 225; - shortdesc = "get the PV UUIDs containing the volume group"; - longdesc = "\ -Given a VG called C<vgname>, this returns the UUIDs of all -the physical volumes that this volume group resides on. - -You can use this along with C<guestfs_pvs> and C<guestfs_pvuuid> -calls to associate physical volumes and volume groups. - -See also C<guestfs_vglvuuids>." }; - - { defaults with - name = "vglvuuids"; added = (1, 0, 87); - style = RStringList "uuids", [String "vgname"], []; - proc_nr = Some 226; - shortdesc = "get the LV UUIDs of all LVs in the volume group"; - longdesc = "\ -Given a VG called C<vgname>, this returns the UUIDs of all -the logical volumes created in this volume group. - -You can use this along with C<guestfs_lvs> and C<guestfs_lvuuid> -calls to associate logical volumes and volume groups. - -See also C<guestfs_vgpvuuids>." }; - - { defaults with - name = "copy_size"; added = (1, 0, 87); - style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"], []; - proc_nr = Some 227; - progress = true; deprecated_by = Some "copy_device_to_device"; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir"; "/copy_size"]; - ["write"; "/copy_size/src"; "hello, world"]; - ["copy_size"; "/copy_size/src"; "/copy_size/dest"; "5"]; - ["read_file"; "/copy_size/dest"]], - "compare_buffers (ret, size, \"hello\", 5) == 0"), [] - ]; - shortdesc = "copy size bytes from source to destination using dd"; - longdesc = "\ -This command copies exactly C<size> bytes from one source device -or file C<src> to another destination device or file C<dest>. - -Note this will fail if the source is too short or if the destination -is not large enough." }; - - { defaults with - name = "zero_device"; added = (1, 3, 1); - style = RErr, [Device "device"], []; - proc_nr = Some 228; - progress = true; - tests = [ - InitBasicFSonLVM, Always, TestRun ( - [["zero_device"; "/dev/VG/LV"]]), [] - ]; - shortdesc = "write zeroes to an entire device"; - longdesc = "\ -This command writes zeroes over the entire C<device>. Compare -with C<guestfs_zero> which just zeroes the first few blocks of -a device. - -If blocks are already zero, then this command avoids writing -zeroes. This prevents the underlying device from becoming non-sparse -or growing unnecessarily." }; - - { defaults with - name = "txz_in"; added = (1, 3, 2); - style = RErr, [FileIn "tarball"; Pathname "directory"], []; - proc_nr = Some 229; - deprecated_by = Some "tar_in"; - optional = Some "xz"; cancellable = true; - tests = [ - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/txz_in"]; - ["txz_in"; "$srcdir/../../test-data/files/helloworld.tar.xz"; "/txz_in"]; - ["cat"; "/txz_in/hello"]], "hello\n"), [] - ]; - shortdesc = "unpack compressed tarball to directory"; - longdesc = "\ -This command uploads and unpacks local file C<tarball> (an -I<xz compressed> tar file) into F<directory>." }; - - { defaults with - name = "txz_out"; added = (1, 3, 2); - style = RErr, [Pathname "directory"; FileOut "tarball"], []; - proc_nr = Some 230; - deprecated_by = Some "tar_out"; - optional = Some "xz"; cancellable = true; - shortdesc = "pack directory into compressed tarball"; - longdesc = "\ -This command packs the contents of F<directory> and downloads -it to local file C<tarball> (as an xz compressed tar archive)." }; - - { defaults with - name = "vgscan"; added = (1, 3, 2); - style = RErr, [], []; - proc_nr = Some 232; - tests = [ - InitEmpty, Always, TestRun ( - [["vgscan"]]), [] - ]; - shortdesc = "rescan for LVM physical volumes, volume groups and logical volumes"; - longdesc = "\ -This rescans all block devices and rebuilds the list of LVM -physical volumes, volume groups and logical volumes." }; - - { defaults with - name = "part_del"; added = (1, 3, 2); - style = RErr, [Device "device"; Int "partnum"], []; - proc_nr = Some 233; - tests = [ - InitEmpty, Always, TestRun ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]; - ["part_del"; "/dev/sda"; "1"]]), [] - ]; - shortdesc = "delete a partition"; - longdesc = "\ -This command deletes the partition numbered C<partnum> on C<device>. - -Note that in the case of MBR partitioning, deleting an -extended partition also deletes any logical partitions -it contains." }; - - { defaults with - name = "part_get_bootable"; added = (1, 3, 2); - style = RBool "bootable", [Device "device"; Int "partnum"], []; - proc_nr = Some 234; - tests = [ - InitEmpty, Always, TestResultTrue ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]; - ["part_set_bootable"; "/dev/sda"; "1"; "true"]; - ["part_get_bootable"; "/dev/sda"; "1"]]), [] - ]; - shortdesc = "return true if a partition is bootable"; - longdesc = "\ -This command returns true if the partition C<partnum> on -C<device> has the bootable flag set. - -See also C<guestfs_part_set_bootable>." }; - - { defaults with - name = "part_get_mbr_id"; added = (1, 3, 2); - style = RInt "idbyte", [Device "device"; Int "partnum"], []; - proc_nr = Some 235; - fish_output = Some FishOutputHexadecimal; - tests = [ - InitEmpty, Always, TestResult ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]; - ["part_set_mbr_id"; "/dev/sda"; "1"; "0x7f"]; - ["part_get_mbr_id"; "/dev/sda"; "1"]], "ret == 0x7f"), [] - ]; - shortdesc = "get the MBR type byte (ID byte) from a partition"; - longdesc = "\ -Returns the MBR type byte (also known as the ID byte) from -the numbered partition C<partnum>. - -Note that only MBR (old DOS-style) partitions have type bytes. -You will get undefined results for other partition table -types (see C<guestfs_part_get_parttype>)." }; - - { defaults with - name = "part_set_mbr_id"; added = (1, 3, 2); - style = RErr, [Device "device"; Int "partnum"; Int "idbyte"], []; - proc_nr = Some 236; - shortdesc = "set the MBR type byte (ID byte) of a partition"; - longdesc = "\ -Sets the MBR type byte (also known as the ID byte) of -the numbered partition C<partnum> to C<idbyte>. Note -that the type bytes quoted in most documentation are -in fact hexadecimal numbers, but usually documented -without any leading \"0x\" which might be confusing. - -Note that only MBR (old DOS-style) partitions have type bytes. -You will get undefined results for other partition table -types (see C<guestfs_part_get_parttype>)." }; - - { defaults with - name = "checksum_device"; added = (1, 3, 2); - style = RString "checksum", [String "csumtype"; Device "device"], []; - proc_nr = Some 237; - tests = [ - InitISOFS, Always, TestResult ( - [["checksum_device"; "md5"; "/dev/sdd"]], - "check_file_md5 (ret, \"../../test-data/test.iso\") == 0"), [] - ]; - shortdesc = "compute MD5, SHAx or CRC checksum of the contents of a device"; - longdesc = "\ -This call computes the MD5, SHAx or CRC checksum of the -contents of the device named C<device>. For the types of -checksums supported see the C<guestfs_checksum> command." }; - - { defaults with - name = "lvresize_free"; added = (1, 3, 3); - style = RErr, [Device "lv"; Int "percent"], []; - proc_nr = Some 238; - optional = Some "lvm2"; - tests = [ - InitNone, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV"; "VG"; "10"]; - ["lvresize_free"; "/dev/VG/LV"; "100"]]), [] - ]; - shortdesc = "expand an LV to fill free space"; - longdesc = "\ -This expands an existing logical volume C<lv> so that it fills -C<pc>% of the remaining free space in the volume group. Commonly -you would call this with pc = 100 which expands the logical volume -as much as possible, using all remaining free space in the volume -group." }; - - { defaults with - name = "aug_clear"; added = (1, 3, 4); - style = RErr, [String "augpath"], []; - proc_nr = Some 239; - shortdesc = "clear Augeas path"; - longdesc = "\ -Set the value associated with C<path> to C<NULL>. This -is the same as the L<augtool(1)> C<clear> command." }; - - { defaults with - name = "get_umask"; added = (1, 3, 4); - style = RInt "mask", [], []; - proc_nr = Some 240; - fish_output = Some FishOutputOctal; - tests = [ - InitEmpty, Always, TestResult ( - [["get_umask"]], "ret == 022"), [] - ]; - shortdesc = "get the current umask"; - longdesc = "\ -Return the current umask. By default the umask is C<022> -unless it has been set by calling C<guestfs_umask>." }; - - { defaults with - name = "debug_upload"; added = (1, 3, 5); - style = RErr, [FileIn "filename"; String "tmpname"; Int "mode"], []; - proc_nr = Some 241; - visibility = VDebug; - cancellable = true; - shortdesc = "upload a file to the appliance (internal use only)"; - longdesc = "\ -The C<guestfs_debug_upload> command uploads a file to -the libguestfs appliance. - -There is no comprehensive help for this command. You have -to look at the file F<daemon/debug.c> in the libguestfs source -to find out what it is for." }; - - { defaults with - name = "base64_in"; added = (1, 3, 5); - style = RErr, [FileIn "base64file"; Pathname "filename"], []; - proc_nr = Some 242; - cancellable = true; - tests = [ - InitScratchFS, Always, TestResultString ( - [["base64_in"; "../../test-data/files/hello.b64"; "/base64_in"]; - ["cat"; "/base64_in"]], "hello\n"), [] - ]; - shortdesc = "upload base64-encoded data to file"; - longdesc = "\ -This command uploads base64-encoded data from C<base64file> -to F<filename>." }; - - { defaults with - name = "base64_out"; added = (1, 3, 5); - style = RErr, [Pathname "filename"; FileOut "base64file"], []; - proc_nr = Some 243; - cancellable = true; - shortdesc = "download file and encode as base64"; - longdesc = "\ -This command downloads the contents of F<filename>, writing -it out to local file C<base64file> encoded as base64." }; - - { defaults with - name = "checksums_out"; added = (1, 3, 7); - style = RErr, [String "csumtype"; Pathname "directory"; FileOut "sumsfile"], []; - proc_nr = Some 244; - cancellable = true; - shortdesc = "compute MD5, SHAx or CRC checksum of files in a directory"; - longdesc = "\ -This command computes the checksums of all regular files in -F<directory> and then emits a list of those checksums to -the local output file C<sumsfile>. - -This can be used for verifying the integrity of a virtual -machine. However to be properly secure you should pay -attention to the output of the checksum command (it uses -the ones from GNU coreutils). In particular when the -filename is not printable, coreutils uses a special -backslash syntax. For more information, see the GNU -coreutils info file." }; - - { defaults with - name = "fill_pattern"; added = (1, 3, 12); - style = RErr, [String "pattern"; Int "len"; Pathname "path"], []; - proc_nr = Some 245; - progress = true; - tests = [ - InitScratchFS, Always, TestResult ( - [["fill_pattern"; "abcdefghijklmnopqrstuvwxyz"; "28"; "/fill_pattern"]; - ["read_file"; "/fill_pattern"]], - "compare_buffers (ret, size, \"abcdefghijklmnopqrstuvwxyzab\", 28) == 0"), [] - ]; - shortdesc = "fill a file with a repeating pattern of bytes"; - longdesc = "\ -This function is like C<guestfs_fill> except that it creates -a new file of length C<len> containing the repeating pattern -of bytes in C<pattern>. The pattern is truncated if necessary -to ensure the length of the file is exactly C<len> bytes." }; - - { defaults with - name = "internal_write"; added = (1, 19, 32); - style = RErr, [Pathname "path"; BufferIn "content"], []; - proc_nr = Some 246; - visibility = VInternal; - protocol_limit_warning = true; - tests = [ - InitScratchFS, Always, TestResultString ( - [["internal_write"; "/internal_write"; "new file contents"]; - ["cat"; "/internal_write"]], "new file contents"), []; - InitScratchFS, Always, TestResultString ( - [["internal_write"; "/internal_write2"; "\nnew file contents\n"]; - ["cat"; "/internal_write2"]], "\nnew file contents\n"), []; - InitScratchFS, Always, TestResultString ( - [["internal_write"; "/internal_write3"; "\n\n"]; - ["cat"; "/internal_write3"]], "\n\n"), []; - InitScratchFS, Always, TestResultString ( - [["internal_write"; "/internal_write4"; ""]; - ["cat"; "/internal_write4"]], ""), []; - InitScratchFS, Always, TestResultString ( - [["internal_write"; "/internal_write5"; "\n\n\n"]; - ["cat"; "/internal_write5"]], "\n\n\n"), []; - InitScratchFS, Always, TestResultString ( - [["internal_write"; "/internal_write6"; "\n"]; - ["cat"; "/internal_write6"]], "\n"), [] - ]; - shortdesc = "create a new file"; - longdesc = "\ -This call creates a file called C<path>. The content of the -file is the string C<content> (which can contain any 8 bit data). - -See also C<guestfs_write_append>." }; - - { defaults with - name = "pwrite"; added = (1, 3, 14); - style = RInt "nbytes", [Pathname "path"; BufferIn "content"; Int64 "offset"], []; - proc_nr = Some 247; - protocol_limit_warning = true; - tests = [ - InitScratchFS, Always, TestResultString ( - [["write"; "/pwrite"; "new file contents"]; - ["pwrite"; "/pwrite"; "data"; "4"]; - ["cat"; "/pwrite"]], "new data contents"), []; - InitScratchFS, Always, TestResultString ( - [["write"; "/pwrite2"; "new file contents"]; - ["pwrite"; "/pwrite2"; "is extended"; "9"]; - ["cat"; "/pwrite2"]], "new file is extended"), []; - InitScratchFS, Always, TestResultString ( - [["write"; "/pwrite3"; "new file contents"]; - ["pwrite"; "/pwrite3"; ""; "4"]; - ["cat"; "/pwrite3"]], "new file contents"), [] - ]; - shortdesc = "write to part of a file"; - longdesc = "\ -This command writes to part of a file. It writes the data -buffer C<content> to the file C<path> starting at offset C<offset>. - -This command implements the L<pwrite(2)> system call, and like -that system call it may not write the full data requested. The -return value is the number of bytes that were actually written -to the file. This could even be 0, although short writes are -unlikely for regular files in ordinary circumstances. - -See also C<guestfs_pread>, C<guestfs_pwrite_device>." }; - - { defaults with - name = "resize2fs_size"; added = (1, 3, 14); - style = RErr, [Device "device"; Int64 "size"], []; - proc_nr = Some 248; - shortdesc = "resize an ext2, ext3 or ext4 filesystem (with size)"; - longdesc = "\ -This command is the same as C<guestfs_resize2fs> except that it -allows you to specify the new size (in bytes) explicitly. - -See also L<guestfs(3)/RESIZE2FS ERRORS>." }; - - { defaults with - name = "pvresize_size"; added = (1, 3, 14); - style = RErr, [Device "device"; Int64 "size"], []; - proc_nr = Some 249; - optional = Some "lvm2"; - shortdesc = "resize an LVM physical volume (with size)"; - longdesc = "\ -This command is the same as C<guestfs_pvresize> except that it -allows you to specify the new size (in bytes) explicitly." }; - - { defaults with - name = "ntfsresize_size"; added = (1, 3, 14); - style = RErr, [Device "device"; Int64 "size"], []; - proc_nr = Some 250; - optional = Some "ntfsprogs"; deprecated_by = Some "ntfsresize"; - shortdesc = "resize an NTFS filesystem (with size)"; - longdesc = "\ -This command is the same as C<guestfs_ntfsresize> except that it -allows you to specify the new size (in bytes) explicitly." }; - - { defaults with - name = "available_all_groups"; added = (1, 3, 15); - style = RStringList "groups", [], []; - proc_nr = Some 251; - tests = [ - InitNone, Always, TestRun [["available_all_groups"]], [] - ]; - shortdesc = "return a list of all optional groups"; - longdesc = "\ -This command returns a list of all optional groups that this -daemon knows about. Note this returns both supported and unsupported -groups. To find out which ones the daemon can actually support -you have to call C<guestfs_available> / C<guestfs_feature_available> -on each member of the returned list. - -See also C<guestfs_available>, C<guestfs_feature_available> -and L<guestfs(3)/AVAILABILITY>." }; - - { defaults with - name = "fallocate64"; added = (1, 3, 17); - style = RErr, [Pathname "path"; Int64 "len"], []; - proc_nr = Some 252; - tests = [ - InitScratchFS, Always, TestResult ( - [["fallocate64"; "/fallocate64"; "1000000"]; - ["stat"; "/fallocate64"]], "ret->size == 1000000"), [] - ]; - shortdesc = "preallocate a file in the guest filesystem"; - longdesc = "\ -This command preallocates a file (containing zero bytes) named -C<path> of size C<len> bytes. If the file exists already, it -is overwritten. - -Note that this call allocates disk blocks for the file. -To create a sparse file use C<guestfs_truncate_size> instead. - -The deprecated call C<guestfs_fallocate> does the same, -but owing to an oversight it only allowed 30 bit lengths -to be specified, effectively limiting the maximum size -of files created through that call to 1GB. - -Do not confuse this with the guestfish-specific -C<alloc> and C<sparse> commands which create -a file in the host and attach it as a device." }; - - { defaults with - name = "vfs_label"; added = (1, 3, 18); - style = RString "label", [Mountable "mountable"], []; - proc_nr = Some 253; - tests = [ - InitBasicFS, Always, TestResultString ( - [["set_label"; "/dev/sda1"; "LTEST"]; - ["vfs_label"; "/dev/sda1"]], "LTEST"), []; - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "test-label"]; - ["vfs_label"; "/dev/sda1"]], "test-label"), []; - InitEmpty, IfAvailable "btrfs", TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "btrfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; ""]; - ["set_label"; "/dev/sda1"; "test-label-btrfs"]; - ["vfs_label"; "/dev/sda1"]], "test-label-btrfs"), []; - ]; - shortdesc = "get the filesystem label"; - longdesc = "\ -This returns the label of the filesystem on C<mountable>. - -If the filesystem is unlabeled, this returns the empty string. - -To find a filesystem from the label, use C<guestfs_findfs_label>." }; - - { defaults with - name = "vfs_uuid"; added = (1, 3, 18); - style = RString "uuid", [Mountable "mountable"], []; - fish_alias = ["get-uuid"]; - proc_nr = Some 254; - tests = [ - InitBasicFS, Always, TestResultString ( - [["set_e2uuid"; "/dev/sda1"; stable_uuid]; - ["vfs_uuid"; "/dev/sda1"]], stable_uuid), [] - ]; - shortdesc = "get the filesystem UUID"; - longdesc = "\ -This returns the filesystem UUID of the filesystem on C<mountable>. - -If the filesystem does not have a UUID, this returns the empty string. - -To find a filesystem from the UUID, use C<guestfs_findfs_uuid>." }; - - { defaults with - name = "lvm_set_filter"; added = (1, 5, 1); - style = RErr, [DeviceList "devices"], []; - proc_nr = Some 255; - optional = Some "lvm2"; - test_excuse = "cannot be tested with the current framework because the VG is being used by the mounted filesystem, so the 'vgchange -an' command we do first will fail"; - shortdesc = "set LVM device filter"; - longdesc = "\ -This sets the LVM device filter so that LVM will only be -able to \"see\" the block devices in the list C<devices>, -and will ignore all other attached block devices. - -Where disk image(s) contain duplicate PVs or VGs, this -command is useful to get LVM to ignore the duplicates, otherwise -LVM can get confused. Note also there are two types -of duplication possible: either cloned PVs/VGs which have -identical UUIDs; or VGs that are not cloned but just happen -to have the same name. In normal operation you cannot -create this situation, but you can do it outside LVM, eg. -by cloning disk images or by bit twiddling inside the LVM -metadata. - -This command also clears the LVM cache and performs a volume -group scan. - -You can filter whole block devices or individual partitions. - -You cannot use this if any VG is currently in use (eg. -contains a mounted filesystem), even if you are not -filtering out that VG." }; - - { defaults with - name = "lvm_clear_filter"; added = (1, 5, 1); - style = RErr, [], []; - proc_nr = Some 256; - test_excuse = "cannot be tested with the current framework because the VG is being used by the mounted filesystem, so the 'vgchange -an' command we do first will fail"; - shortdesc = "clear LVM device filter"; - longdesc = "\ -This undoes the effect of C<guestfs_lvm_set_filter>. LVM -will be able to see every block device. - -This command also clears the LVM cache and performs a volume -group scan." }; - - { defaults with - name = "luks_open"; added = (1, 5, 1); - style = RErr, [Device "device"; Key "key"; String "mapname"], []; - proc_nr = Some 257; - optional = Some "luks"; - shortdesc = "open a LUKS-encrypted block device"; - longdesc = "\ -This command opens a block device which has been encrypted -according to the Linux Unified Key Setup (LUKS) standard. - -C<device> is the encrypted block device or partition. - -The caller must supply one of the keys associated with the -LUKS block device, in the C<key> parameter. - -This creates a new block device called F</dev/mapper/mapname>. -Reads and writes to this block device are decrypted from and -encrypted to the underlying C<device> respectively. - -If this block device contains LVM volume groups, then -calling C<guestfs_vgscan> followed by C<guestfs_vg_activate_all> -will make them visible. - -Use C<guestfs_list_dm_devices> to list all device mapper -devices." }; - - { defaults with - name = "luks_open_ro"; added = (1, 5, 1); - style = RErr, [Device "device"; Key "key"; String "mapname"], []; - proc_nr = Some 258; - optional = Some "luks"; - shortdesc = "open a LUKS-encrypted block device read-only"; - longdesc = "\ -This is the same as C<guestfs_luks_open> except that a read-only -mapping is created." }; - - { defaults with - name = "luks_close"; added = (1, 5, 1); - style = RErr, [Device "device"], []; - proc_nr = Some 259; - optional = Some "luks"; - shortdesc = "close a LUKS device"; - longdesc = "\ -This closes a LUKS device that was created earlier by -C<guestfs_luks_open> or C<guestfs_luks_open_ro>. The -C<device> parameter must be the name of the LUKS mapping -device (ie. F</dev/mapper/mapname>) and I<not> the name -of the underlying block device." }; - - { defaults with - name = "luks_format"; added = (1, 5, 2); - style = RErr, [Device "device"; Key "key"; Int "keyslot"], []; - proc_nr = Some 260; - optional = Some "luks"; - shortdesc = "format a block device as a LUKS encrypted device"; - longdesc = "\ -This command erases existing data on C<device> and formats -the device as a LUKS encrypted device. C<key> is the -initial key, which is added to key slot C<slot>. (LUKS -supports 8 key slots, numbered 0-7)." }; - - { defaults with - name = "luks_format_cipher"; added = (1, 5, 2); - style = RErr, [Device "device"; Key "key"; Int "keyslot"; String "cipher"], []; - proc_nr = Some 261; - optional = Some "luks"; - shortdesc = "format a block device as a LUKS encrypted device"; - longdesc = "\ -This command is the same as C<guestfs_luks_format> but -it also allows you to set the C<cipher> used." }; - - { defaults with - name = "luks_add_key"; added = (1, 5, 2); - style = RErr, [Device "device"; Key "key"; Key "newkey"; Int "keyslot"], []; - proc_nr = Some 262; - optional = Some "luks"; - shortdesc = "add a key on a LUKS encrypted device"; - longdesc = "\ -This command adds a new key on LUKS device C<device>. -C<key> is any existing key, and is used to access the device. -C<newkey> is the new key to add. C<keyslot> is the key slot -that will be replaced. - -Note that if C<keyslot> already contains a key, then this -command will fail. You have to use C<guestfs_luks_kill_slot> -first to remove that key." }; - - { defaults with - name = "luks_kill_slot"; added = (1, 5, 2); - style = RErr, [Device "device"; Key "key"; Int "keyslot"], []; - proc_nr = Some 263; - optional = Some "luks"; - shortdesc = "remove a key from a LUKS encrypted device"; - longdesc = "\ -This command deletes the key in key slot C<keyslot> from the -encrypted LUKS device C<device>. C<key> must be one of the -I<other> keys." }; - - { defaults with - name = "is_lv"; added = (1, 5, 3); - style = RBool "lvflag", [Mountable "mountable"], []; - proc_nr = Some 264; - tests = [ - InitBasicFSonLVM, Always, TestResultTrue ( - [["is_lv"; "/dev/VG/LV"]]), []; - InitBasicFSonLVM, Always, TestResultFalse ( - [["is_lv"; "/dev/sda1"]]), [] - ]; - shortdesc = "test if mountable is a logical volume"; - longdesc = "\ -This command tests whether C<mountable> is a logical volume, and -returns true iff this is the case." }; - - { defaults with - name = "findfs_uuid"; added = (1, 5, 3); - style = RString "device", [String "uuid"], []; - proc_nr = Some 265; - shortdesc = "find a filesystem by UUID"; - longdesc = "\ -This command searches the filesystems and returns the one -which has the given UUID. An error is returned if no such -filesystem can be found. - -To find the UUID of a filesystem, use C<guestfs_vfs_uuid>." }; - - { defaults with - name = "findfs_label"; added = (1, 5, 3); - style = RString "device", [String "label"], []; - proc_nr = Some 266; - shortdesc = "find a filesystem by label"; - longdesc = "\ -This command searches the filesystems and returns the one -which has the given label. An error is returned if no such -filesystem can be found. - -To find the label of a filesystem, use C<guestfs_vfs_label>." }; - - { defaults with - name = "is_chardev"; added = (1, 5, 10); - style = RBool "flag", [Pathname "path"], [OBool "followsymlinks"]; - proc_nr = Some 267; - once_had_no_optargs = true; - tests = [ - InitISOFS, Always, TestResultFalse ( - [["is_chardev"; "/directory"; ""]]), []; - InitScratchFS, Always, TestResultTrue ( - [["mknod_c"; "0o777"; "99"; "66"; "/is_chardev"]; - ["is_chardev"; "/is_chardev"; ""]]), [] - ]; - shortdesc = "test if character device"; - longdesc = "\ -This returns C<true> if and only if there is a character device -with the given C<path> name. - -If the optional flag C<followsymlinks> is true, then a symlink -(or chain of symlinks) that ends with a chardev also causes the -function to return true. - -See also C<guestfs_stat>." }; - - { defaults with - name = "is_blockdev"; added = (1, 5, 10); - style = RBool "flag", [Pathname "path"], [OBool "followsymlinks"]; - proc_nr = Some 268; - once_had_no_optargs = true; - tests = [ - InitISOFS, Always, TestResultFalse ( - [["is_blockdev"; "/directory"; ""]]), []; - InitScratchFS, Always, TestResultTrue ( - [["mknod_b"; "0o777"; "99"; "66"; "/is_blockdev"]; - ["is_blockdev"; "/is_blockdev"; ""]]), [] - ]; - shortdesc = "test if block device"; - longdesc = "\ -This returns C<true> if and only if there is a block device -with the given C<path> name. - -If the optional flag C<followsymlinks> is true, then a symlink -(or chain of symlinks) that ends with a block device also causes the -function to return true. - -This call only looks at files within the guest filesystem. Libguestfs -partitions and block devices (eg. F</dev/sda>) cannot be used as the -C<path> parameter of this call. - -See also C<guestfs_stat>." }; - - { defaults with - name = "is_fifo"; added = (1, 5, 10); - style = RBool "flag", [Pathname "path"], [OBool "followsymlinks"]; - proc_nr = Some 269; - once_had_no_optargs = true; - tests = [ - InitISOFS, Always, TestResultFalse ( - [["is_fifo"; "/directory"; ""]]), []; - InitScratchFS, Always, TestResultTrue ( - [["mkfifo"; "0o777"; "/is_fifo"]; - ["is_fifo"; "/is_fifo"; ""]]), [] - ]; - shortdesc = "test if FIFO (named pipe)"; - longdesc = "\ -This returns C<true> if and only if there is a FIFO (named pipe) -with the given C<path> name. - -If the optional flag C<followsymlinks> is true, then a symlink -(or chain of symlinks) that ends with a FIFO also causes the -function to return true. - -See also C<guestfs_stat>." }; - - { defaults with - name = "is_symlink"; added = (1, 5, 10); - style = RBool "flag", [Pathname "path"], []; - proc_nr = Some 270; - tests = [ - InitISOFS, Always, TestResultFalse ( - [["is_symlink"; "/directory"]]), []; - InitISOFS, Always, TestResultTrue ( - [["is_symlink"; "/abssymlink"]]), [] - ]; - shortdesc = "test if symbolic link"; - longdesc = "\ -This returns C<true> if and only if there is a symbolic link -with the given C<path> name. - -See also C<guestfs_stat>." }; - - { defaults with - name = "is_socket"; added = (1, 5, 10); - style = RBool "flag", [Pathname "path"], [OBool "followsymlinks"]; - proc_nr = Some 271; - once_had_no_optargs = true; - (* XXX Need a positive test for sockets. *) - tests = [ - InitISOFS, Always, TestResultFalse ( - [["is_socket"; "/directory"; ""]]), [] - ]; - shortdesc = "test if socket"; - longdesc = "\ -This returns C<true> if and only if there is a Unix domain socket -with the given C<path> name. - -If the optional flag C<followsymlinks> is true, then a symlink -(or chain of symlinks) that ends with a socket also causes the -function to return true. - -See also C<guestfs_stat>." }; - - { defaults with - name = "part_to_dev"; added = (1, 5, 15); - style = RString "device", [Device "partition"], []; - proc_nr = Some 272; - tests = [ - InitPartition, Always, TestResultDevice ( - [["part_to_dev"; "/dev/sda1"]], "/dev/sda"), []; - InitEmpty, Always, TestLastFail ( - [["part_to_dev"; "/dev/sda"]]), [] - ]; - shortdesc = "convert partition name to device name"; - longdesc = "\ -This function takes a partition name (eg. \"/dev/sdb1\") and -removes the partition number, returning the device name -(eg. \"/dev/sdb\"). - -The named partition must exist, for example as a string returned -from C<guestfs_list_partitions>. - -See also C<guestfs_part_to_partnum>, C<guestfs_device_index>." }; - - { defaults with - name = "upload_offset"; added = (1, 5, 17); - style = RErr, [FileIn "filename"; Dev_or_Path "remotefilename"; Int64 "offset"], []; - proc_nr = Some 273; - progress = true; cancellable = true; - tests = - (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in [ - InitScratchFS, Always, TestResultString ( - [["upload_offset"; "$srcdir/../../COPYING.LIB"; "/upload_offset"; "0"]; - ["checksum"; "md5"; "/upload_offset"]], md5), [] - ]); - shortdesc = "upload a file from the local machine with offset"; - longdesc = "\ -Upload local file F<filename> to F<remotefilename> on the -filesystem. - -F<remotefilename> is overwritten starting at the byte C<offset> -specified. The intention is to overwrite parts of existing -files or devices, although if a non-existent file is specified -then it is created with a \"hole\" before C<offset>. The -size of the data written is implicit in the size of the -source F<filename>. - -Note that there is no limit on the amount of data that -can be uploaded with this call, unlike with C<guestfs_pwrite>, -and this call always writes the full amount unless an -error occurs. - -See also C<guestfs_upload>, C<guestfs_pwrite>." }; - - { defaults with - name = "download_offset"; added = (1, 5, 17); - style = RErr, [Dev_or_Path "remotefilename"; FileOut "filename"; Int64 "offset"; Int64 "size"], []; - proc_nr = Some 274; - progress = true; cancellable = true; - tests = - (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in - let offset = string_of_int 100 in - let size = string_of_int ((Unix.stat "COPYING.LIB").Unix.st_size - 100) in - [ - InitScratchFS, Always, TestResultString ( - (* Pick a file from cwd which isn't likely to change. *) - [["mkdir"; "/download_offset"]; - ["upload"; "$srcdir/../../COPYING.LIB"; "/download_offset/COPYING.LIB"]; - ["download_offset"; "/download_offset/COPYING.LIB"; "testdownload.tmp"; offset; size]; - ["upload_offset"; "testdownload.tmp"; "/download_offset/COPYING.LIB"; offset]; - ["checksum"; "md5"; "/download_offset/COPYING.LIB"]], md5), [] - ]); - shortdesc = "download a file to the local machine with offset and size"; - longdesc = "\ -Download file F<remotefilename> and save it as F<filename> -on the local machine. - -F<remotefilename> is read for C<size> bytes starting at C<offset> -(this region must be within the file or device). - -Note that there is no limit on the amount of data that -can be downloaded with this call, unlike with C<guestfs_pread>, -and this call always reads the full amount unless an -error occurs. - -See also C<guestfs_download>, C<guestfs_pread>." }; - - { defaults with - name = "pwrite_device"; added = (1, 5, 20); - style = RInt "nbytes", [Device "device"; BufferIn "content"; Int64 "offset"], []; - proc_nr = Some 275; - protocol_limit_warning = true; - tests = [ - InitPartition, Always, TestResult ( - [["pwrite_device"; "/dev/sda"; "\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000"; "446"]; - ["blockdev_rereadpt"; "/dev/sda"]; - ["list_partitions"]], - "is_device_list (ret, 1, \"/dev/sdb1\")"), [] - ]; - shortdesc = "write to part of a device"; - longdesc = "\ -This command writes to part of a device. It writes the data -buffer C<content> to C<device> starting at offset C<offset>. - -This command implements the L<pwrite(2)> system call, and like -that system call it may not write the full data requested -(although short writes to disk devices and partitions are -probably impossible with standard Linux kernels). - -See also C<guestfs_pwrite>." }; - - { defaults with - name = "pread_device"; added = (1, 5, 21); - style = RBufferOut "content", [Device "device"; Int "count"; Int64 "offset"], []; - proc_nr = Some 276; - protocol_limit_warning = true; - tests = [ - InitEmpty, Always, TestResult ( - [["pread_device"; "/dev/sdd"; "8"; "32768"]], - "compare_buffers (ret, size, \"\\1CD001\\1\\0\", 8) == 0"), [] - ]; - shortdesc = "read part of a device"; - longdesc = "\ -This command lets you read part of a block device. It reads C<count> -bytes of C<device>, starting at C<offset>. - -This may read fewer bytes than requested. For further details -see the L<pread(2)> system call. - -See also C<guestfs_pread>." }; - - { defaults with - name = "lvm_canonical_lv_name"; added = (1, 5, 24); - style = RString "lv", [Device "lvname"], []; - proc_nr = Some 277; - tests = [ - InitBasicFSonLVM, IfAvailable "lvm2", TestResultString ( - [["lvm_canonical_lv_name"; "/dev/mapper/VG-LV"]], "/dev/VG/LV"), []; - InitBasicFSonLVM, IfAvailable "lvm2", TestResultString ( - [["lvm_canonical_lv_name"; "/dev/VG/LV"]], "/dev/VG/LV"), [] - ]; - shortdesc = "get canonical name of an LV"; - longdesc = "\ -This converts alternative naming schemes for LVs that you -might find to the canonical name. For example, F</dev/mapper/VG-LV> -is converted to F</dev/VG/LV>. - -This command returns an error if the C<lvname> parameter does -not refer to a logical volume. - -See also C<guestfs_is_lv>, C<guestfs_canonical_device_name>." }; - - { defaults with - name = "mkfs"; added = (0, 0, 8); - style = RErr, [String "fstype"; Device "device"], [OInt "blocksize"; OString "features"; OInt "inode"; OInt "sectorsize"; OString "label"]; - proc_nr = Some 278; - once_had_no_optargs = true; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["write"; "/new"; "new file contents"]; - ["cat"; "/new"]], "new file contents"), [] - ]; - shortdesc = "make a filesystem"; - longdesc = "\ -This function creates a filesystem on C<device>. The filesystem -type is C<fstype>, for example C<ext3>. - -The optional arguments are: - -=over 4 - -=item C<blocksize> - -The filesystem block size. Supported block sizes depend on the -filesystem type, but typically they are C<1024>, C<2048> or C<4096> -for Linux ext2/3 filesystems. - -For VFAT and NTFS the C<blocksize> parameter is treated as -the requested cluster size. - -For UFS block sizes, please see L<mkfs.ufs(8)>. - -=item C<features> - -This passes the I<-O> parameter to the external mkfs program. - -For certain filesystem types, this allows extra filesystem -features to be selected. See L<mke2fs(8)> and L<mkfs.ufs(8)> -for more details. - -You cannot use this optional parameter with the C<gfs> or -C<gfs2> filesystem type. - -=item C<inode> - -This passes the I<-I> parameter to the external L<mke2fs(8)> program -which sets the inode size (only for ext2/3/4 filesystems at present). - -=item C<sectorsize> - -This passes the I<-S> parameter to external L<mkfs.ufs(8)> program, -which sets sector size for ufs filesystem. - -=back" }; - - { defaults with - name = "getxattr"; added = (1, 7, 24); - style = RBufferOut "xattr", [Pathname "path"; String "name"], []; - proc_nr = Some 279; - optional = Some "linuxxattrs"; - shortdesc = "get a single extended attribute"; - longdesc = "\ -Get a single extended attribute from file C<path> named C<name>. -This call follows symlinks. If you want to lookup an extended -attribute for the symlink itself, use C<guestfs_lgetxattr>. - -Normally it is better to get all extended attributes from a file -in one go by calling C<guestfs_getxattrs>. However some Linux -filesystem implementations are buggy and do not provide a way to -list out attributes. For these filesystems (notably ntfs-3g) -you have to know the names of the extended attributes you want -in advance and call this function. - -Extended attribute values are blobs of binary data. If there -is no extended attribute named C<name>, this returns an error. - -See also: C<guestfs_getxattrs>, C<guestfs_lgetxattr>, L<attr(5)>." }; - - { defaults with - name = "lgetxattr"; added = (1, 7, 24); - style = RBufferOut "xattr", [Pathname "path"; String "name"], []; - proc_nr = Some 280; - optional = Some "linuxxattrs"; - shortdesc = "get a single extended attribute"; - longdesc = "\ -Get a single extended attribute from file C<path> named C<name>. -If C<path> is a symlink, then this call returns an extended -attribute from the symlink. - -Normally it is better to get all extended attributes from a file -in one go by calling C<guestfs_getxattrs>. However some Linux -filesystem implementations are buggy and do not provide a way to -list out attributes. For these filesystems (notably ntfs-3g) -you have to know the names of the extended attributes you want -in advance and call this function. - -Extended attribute values are blobs of binary data. If there -is no extended attribute named C<name>, this returns an error. - -See also: C<guestfs_lgetxattrs>, C<guestfs_getxattr>, L<attr(5)>." }; - - { defaults with - name = "resize2fs_M"; added = (1, 9, 4); - style = RErr, [Device "device"], []; - proc_nr = Some 281; - shortdesc = "resize an ext2, ext3 or ext4 filesystem to the minimum size"; - longdesc = "\ -This command is the same as C<guestfs_resize2fs>, but the filesystem -is resized to its minimum size. This works like the I<-M> option -to the C<resize2fs> command. - -To get the resulting size of the filesystem you should call -C<guestfs_tune2fs_l> and read the C<Block size> and C<Block count> -values. These two numbers, multiplied together, give the -resulting size of the minimal filesystem in bytes. - -See also L<guestfs(3)/RESIZE2FS ERRORS>." }; - - { defaults with - name = "internal_autosync"; added = (1, 9, 7); - style = RErr, [], []; - proc_nr = Some 282; - visibility = VInternal; - shortdesc = "internal autosync operation"; - longdesc = "\ -This command performs the autosync operation just before the -handle is closed. You should not call this command directly. -Instead, use the autosync flag (C<guestfs_set_autosync>) to -control whether or not this operation is performed when the -handle is closed." }; - - { defaults with - name = "is_zero"; added = (1, 11, 8); - style = RBool "zeroflag", [Pathname "path"], []; - proc_nr = Some 283; - tests = [ - InitISOFS, Always, TestResultTrue ( - [["is_zero"; "/100kallzeroes"]]), []; - InitISOFS, Always, TestResultFalse ( - [["is_zero"; "/100kallspaces"]]), [] - ]; - shortdesc = "test if a file contains all zero bytes"; - longdesc = "\ -This returns true iff the file exists and the file is empty or -it contains all zero bytes." }; - - { defaults with - name = "is_zero_device"; added = (1, 11, 8); - style = RBool "zeroflag", [Device "device"], []; - proc_nr = Some 284; - tests = [ - InitBasicFS, Always, TestResultTrue ( - [["umount"; "/dev/sda1"; "false"; "false"]; - ["zero_device"; "/dev/sda1"]; - ["is_zero_device"; "/dev/sda1"]]), []; - InitBasicFS, Always, TestResultFalse ( - [["is_zero_device"; "/dev/sda1"]]), [] - ]; - shortdesc = "test if a device contains all zero bytes"; - longdesc = "\ -This returns true iff the device exists and contains all zero bytes. - -Note that for large devices this can take a long time to run." }; - - { defaults with - name = "list_9p"; added = (1, 11, 12); - style = RStringList "mounttags", [], []; - proc_nr = Some 285; - shortdesc = "list 9p filesystems"; - longdesc = "\ -List all 9p filesystems attached to the guest. A list of -mount tags is returned." }; - - { defaults with - name = "mount_9p"; added = (1, 11, 12); - style = RErr, [String "mounttag"; String "mountpoint"], [OString "options"]; - proc_nr = Some 286; - camel_name = "Mount9P"; - shortdesc = "mount 9p filesystem"; - longdesc = "\ -Mount the virtio-9p filesystem with the tag C<mounttag> on the -directory C<mountpoint>. - -If required, C<trans=virtio> will be automatically added to the options. -Any other options required can be passed in the optional C<options> -parameter." }; - - { defaults with - name = "list_dm_devices"; added = (1, 11, 15); - style = RStringList "devices", [], []; - proc_nr = Some 287; - shortdesc = "list device mapper devices"; - longdesc = "\ -List all device mapper devices. - -The returned list contains F</dev/mapper/*> devices, eg. ones created -by a previous call to C<guestfs_luks_open>. - -Device mapper devices which correspond to logical volumes are I<not> -returned in this list. Call C<guestfs_lvs> if you want to list logical -volumes." }; - - { defaults with - name = "ntfsresize"; added = (1, 3, 2); - style = RErr, [Device "device"], [OInt64 "size"; OBool "force"]; - once_had_no_optargs = true; - proc_nr = Some 288; - optional = Some "ntfsprogs"; camel_name = "NTFSResizeOpts"; - shortdesc = "resize an NTFS filesystem"; - longdesc = "\ -This command resizes an NTFS filesystem, expanding or -shrinking it to the size of the underlying device. - -The optional parameters are: - -=over 4 - -=item C<size> - -The new size (in bytes) of the filesystem. If omitted, the filesystem -is resized to fit the container (eg. partition). - -=item C<force> - -If this option is true, then force the resize of the filesystem -even if the filesystem is marked as requiring a consistency check. - -After the resize operation, the filesystem is always marked -as requiring a consistency check (for safety). You have to boot -into Windows to perform this check and clear this condition. -If you I<don't> set the C<force> option then it is not -possible to call C<guestfs_ntfsresize> multiple times on a -single filesystem without booting into Windows between each resize. - -=back - -See also L<ntfsresize(8)>." }; - - { defaults with - name = "btrfs_filesystem_resize"; added = (1, 11, 17); - style = RErr, [Pathname "mountpoint"], [OInt64 "size"]; - proc_nr = Some 289; - optional = Some "btrfs"; camel_name = "BTRFSFilesystemResize"; - shortdesc = "resize a btrfs filesystem"; - longdesc = "\ -This command resizes a btrfs filesystem. - -Note that unlike other resize calls, the filesystem has to be -mounted and the parameter is the mountpoint not the device -(this is a requirement of btrfs itself). - -The optional parameters are: - -=over 4 - -=item C<size> - -The new size (in bytes) of the filesystem. If omitted, the filesystem -is resized to the maximum size. - -=back - -See also L<btrfs(8)>." }; - - { defaults with - name = "internal_write_append"; added = (1, 19, 32); - style = RErr, [Pathname "path"; BufferIn "content"], []; - proc_nr = Some 290; - visibility = VInternal; - protocol_limit_warning = true; - tests = [ - InitScratchFS, Always, TestResultString ( - [["write"; "/internal_write_append"; "line1\n"]; - ["internal_write_append"; "/internal_write_append"; "line2\n"]; - ["internal_write_append"; "/internal_write_append"; "line3a"]; - ["internal_write_append"; "/internal_write_append"; "line3b\n"]; - ["cat"; "/internal_write_append"]], "line1\nline2\nline3aline3b\n"), [] - ]; - shortdesc = "append content to end of file"; - longdesc = "\ -This call appends C<content> to the end of file C<path>. If -C<path> does not exist, then a new file is created. - -See also C<guestfs_write>." }; - - { defaults with - name = "compress_out"; added = (1, 13, 15); - style = RErr, [String "ctype"; Pathname "file"; FileOut "zfile"], [OInt "level"]; - proc_nr = Some 291; - cancellable = true; - shortdesc = "output compressed file"; - longdesc = "\ -This command compresses F<file> and writes it out to the local -file F<zfile>. - -The compression program used is controlled by the C<ctype> parameter. -Currently this includes: C<compress>, C<gzip>, C<bzip2>, C<xz> or C<lzop>. -Some compression types may not be supported by particular builds of -libguestfs, in which case you will get an error containing the -substring \"not supported\". - -The optional C<level> parameter controls compression level. The -meaning and default for this parameter depends on the compression -program being used." }; - - { defaults with - name = "compress_device_out"; added = (1, 13, 15); - style = RErr, [String "ctype"; Device "device"; FileOut "zdevice"], [OInt "level"]; - proc_nr = Some 292; - cancellable = true; - shortdesc = "output compressed device"; - longdesc = "\ -This command compresses C<device> and writes it out to the local -file C<zdevice>. - -The C<ctype> and optional C<level> parameters have the same meaning -as in C<guestfs_compress_out>." }; - - { defaults with - name = "part_to_partnum"; added = (1, 13, 25); - style = RInt "partnum", [Device "partition"], []; - proc_nr = Some 293; - tests = [ - InitPartition, Always, TestResult ( - [["part_to_partnum"; "/dev/sda1"]], "ret == 1"), []; - InitEmpty, Always, TestLastFail ( - [["part_to_partnum"; "/dev/sda"]]), [] - ]; - shortdesc = "convert partition name to partition number"; - longdesc = "\ -This function takes a partition name (eg. \"/dev/sdb1\") and -returns the partition number (eg. C<1>). - -The named partition must exist, for example as a string returned -from C<guestfs_list_partitions>. - -See also C<guestfs_part_to_dev>." }; - - { defaults with - name = "copy_device_to_device"; added = (1, 13, 25); - style = RErr, [Device "src"; Device "dest"], [OInt64 "srcoffset"; OInt64 "destoffset"; OInt64 "size"; OBool "sparse"; OBool "append"]; - proc_nr = Some 294; - progress = true; - shortdesc = "copy from source device to destination device"; - longdesc = "\ -The four calls C<guestfs_copy_device_to_device>, -C<guestfs_copy_device_to_file>, -C<guestfs_copy_file_to_device>, and -C<guestfs_copy_file_to_file> -let you copy from a source (device|file) to a destination -(device|file). - -Partial copies can be made since you can specify optionally -the source offset, destination offset and size to copy. These -values are all specified in bytes. If not given, the offsets -both default to zero, and the size defaults to copying as much -as possible until we hit the end of the source. - -The source and destination may be the same object. However -overlapping regions may not be copied correctly. - -If the destination is a file, it is created if required. If -the destination file is not large enough, it is extended. - -If the destination is a file and the C<append> flag is not set, -then the destination file is truncated. If the C<append> flag is -set, then the copy appends to the destination file. The C<append> -flag currently cannot be set for devices. - -If the C<sparse> flag is true then the call avoids writing -blocks that contain only zeroes, which can help in some situations -where the backing disk is thin-provisioned. Note that unless -the target is already zeroed, using this option will result -in incorrect copying." }; - - { defaults with - name = "copy_device_to_file"; added = (1, 13, 25); - style = RErr, [Device "src"; Pathname "dest"], [OInt64 "srcoffset"; OInt64 "destoffset"; OInt64 "size"; OBool "sparse"; OBool "append"]; - proc_nr = Some 295; - progress = true; - shortdesc = "copy from source device to destination file"; - longdesc = "\ -See C<guestfs_copy_device_to_device> for a general overview -of this call." }; - - { defaults with - name = "copy_file_to_device"; added = (1, 13, 25); - style = RErr, [Pathname "src"; Device "dest"], [OInt64 "srcoffset"; OInt64 "destoffset"; OInt64 "size"; OBool "sparse"; OBool "append"]; - proc_nr = Some 296; - progress = true; - shortdesc = "copy from source file to destination device"; - longdesc = "\ -See C<guestfs_copy_device_to_device> for a general overview -of this call." }; - - { defaults with - name = "copy_file_to_file"; added = (1, 13, 25); - style = RErr, [Pathname "src"; Pathname "dest"], [OInt64 "srcoffset"; OInt64 "destoffset"; OInt64 "size"; OBool "sparse"; OBool "append"]; - proc_nr = Some 297; - progress = true; - tests = [ - InitScratchFS, Always, TestResult ( - [["mkdir"; "/copyff"]; - ["write"; "/copyff/src"; "hello, world"]; - ["copy_file_to_file"; "/copyff/src"; "/copyff/dest"; ""; ""; ""; ""; "false"]; - ["read_file"; "/copyff/dest"]], - "compare_buffers (ret, size, \"hello, world\", 12) == 0"), []; - InitScratchFS, Always, TestResultTrue ( - let size = 1024 * 1024 in - [["mkdir"; "/copyff2"]; - ["fill"; "0"; string_of_int size; "/copyff2/src"]; - ["touch"; "/copyff2/dest"]; - ["truncate_size"; "/copyff2/dest"; string_of_int size]; - ["copy_file_to_file"; "/copyff2/src"; "/copyff2/dest"; ""; ""; ""; "true"; "false"]; - ["is_zero"; "/copyff2/dest"]]), []; - InitScratchFS, Always, TestResult ( - [["mkdir"; "/copyff3"]; - ["write"; "/copyff3/src"; "hello, world"]; - ["copy_file_to_file"; "/copyff3/src"; "/copyff3/dest"; ""; ""; ""; ""; "true"]; - ["copy_file_to_file"; "/copyff3/src"; "/copyff3/dest"; ""; ""; ""; ""; "true"]; - ["copy_file_to_file"; "/copyff3/src"; "/copyff3/dest"; ""; ""; ""; ""; "true"]; - ["read_file"; "/copyff3/dest"]], - "compare_buffers (ret, size, \"hello, worldhello, worldhello, world\", 12*3) == 0"), []; - ]; - shortdesc = "copy from source file to destination file"; - longdesc = "\ -See C<guestfs_copy_device_to_device> for a general overview -of this call. - -This is B<not> the function you want for copying files. This -is for copying blocks within existing files. See C<guestfs_cp>, -C<guestfs_cp_a> and C<guestfs_mv> for general file copying and -moving functions." }; - - { defaults with - name = "tune2fs"; added = (1, 15, 4); - style = RErr, [Device "device"], [OBool "force"; OInt "maxmountcount"; OInt "mountcount"; OString "errorbehavior"; OInt64 "group"; OInt "intervalbetweenchecks"; OInt "reservedblockspercentage"; OString "lastmounteddirectory"; OInt64 "reservedblockscount"; OInt64 "user"]; - proc_nr = Some 298; - camel_name = "Tune2FS"; - tests = [ - InitScratchFS, Always, TestResult ( - [["tune2fs"; "/dev/sdb1"; "false"; "0"; ""; "NOARG"; ""; "0"; ""; "NOARG"; ""; ""]; - ["tune2fs_l"; "/dev/sdb1"]], - "check_hash (ret, \"Check interval\", \"0 (<none>)\") == 0 && "^ - "check_hash (ret, \"Maximum mount count\", \"-1\") == 0"), []; - InitScratchFS, Always, TestResult ( - [["tune2fs"; "/dev/sdb1"; "false"; "0"; ""; "NOARG"; ""; "86400"; ""; "NOARG"; ""; ""]; - ["tune2fs_l"; "/dev/sdb1"]], - "check_hash (ret, \"Check interval\", \"86400 (1 day)\") == 0 && "^ - "check_hash (ret, \"Maximum mount count\", \"-1\") == 0"), []; - InitScratchFS, Always, TestResult ( - [["tune2fs"; "/dev/sdb1"; "false"; ""; ""; "NOARG"; "1"; ""; ""; "NOARG"; ""; "1"]; - ["tune2fs_l"; "/dev/sdb1"]], - "match_re (get_key (ret, \"Reserved blocks uid\"), \"\\\\d+ \\\\(user \\\\S+\\\\)\") && "^ - "match_re (get_key (ret, \"Reserved blocks gid\"), \"\\\\d+ \\\\(group \\\\S+\\\\)\")"), []; - InitScratchFS, Always, TestResult ( - [["tune2fs"; "/dev/sdb1"; "false"; ""; ""; "NOARG"; "0"; ""; ""; "NOARG"; ""; "0"]; - ["tune2fs_l"; "/dev/sdb1"]], - "match_re (get_key (ret, \"Reserved blocks uid\"), \"\\\\d+ \\\\(user \\\\S+\\\\)\") && "^ - "match_re (get_key (ret, \"Reserved blocks gid\"), \"\\\\d+ \\\\(group \\\\S+\\\\)\")"), []; - ]; - shortdesc = "adjust ext2/ext3/ext4 filesystem parameters"; - longdesc = "\ -This call allows you to adjust various filesystem parameters of -an ext2/ext3/ext4 filesystem called C<device>. - -The optional parameters are: - -=over 4 - -=item C<force> - -Force tune2fs to complete the operation even in the face of errors. -This is the same as the tune2fs C<-f> option. - -=item C<maxmountcount> - -Set the number of mounts after which the filesystem is checked -by L<e2fsck(8)>. If this is C<0> then the number of mounts is -disregarded. This is the same as the tune2fs C<-c> option. - -=item C<mountcount> - -Set the number of times the filesystem has been mounted. -This is the same as the tune2fs C<-C> option. - -=item C<errorbehavior> - -Change the behavior of the kernel code when errors are detected. -Possible values currently are: C<continue>, C<remount-ro>, C<panic>. -In practice these options don't really make any difference, -particularly for write errors. - -This is the same as the tune2fs C<-e> option. - -=item C<group> - -Set the group which can use reserved filesystem blocks. -This is the same as the tune2fs C<-g> option except that it -can only be specified as a number. - -=item C<intervalbetweenchecks> - -Adjust the maximal time between two filesystem checks -(in seconds). If the option is passed as C<0> then -time-dependent checking is disabled. - -This is the same as the tune2fs C<-i> option. - -=item C<reservedblockspercentage> - -Set the percentage of the filesystem which may only be allocated -by privileged processes. -This is the same as the tune2fs C<-m> option. - -=item C<lastmounteddirectory> - -Set the last mounted directory. -This is the same as the tune2fs C<-M> option. - -=item C<reservedblockscount> -Set the number of reserved filesystem blocks. -This is the same as the tune2fs C<-r> option. - -=item C<user> - -Set the user who can use the reserved filesystem blocks. -This is the same as the tune2fs C<-u> option except that it -can only be specified as a number. - -=back - -To get the current values of filesystem parameters, see -C<guestfs_tune2fs_l>. For precise details of how tune2fs -works, see the L<tune2fs(8)> man page." }; - - { defaults with - name = "md_create"; added = (1, 15, 6); - style = RErr, [String "name"; DeviceList "devices"], [OInt64 "missingbitmap"; OInt "nrdevices"; OInt "spare"; OInt64 "chunk"; OString "level"]; - proc_nr = Some 299; - optional = Some "mdadm"; camel_name = "MDCreate"; - shortdesc = "create a Linux md (RAID) device"; - longdesc = "\ -Create a Linux md (RAID) device named C<name> on the devices -in the list C<devices>. - -The optional parameters are: - -=over 4 - -=item C<missingbitmap> - -A bitmap of missing devices. If a bit is set it means that a -missing device is added to the array. The least significant bit -corresponds to the first device in the array. - -As examples: - -If C<devices = [\"/dev/sda\"]> and C<missingbitmap = 0x1> then -the resulting array would be C<[E<lt>missingE<gt>, \"/dev/sda\"]>. - -If C<devices = [\"/dev/sda\"]> and C<missingbitmap = 0x2> then -the resulting array would be C<[\"/dev/sda\", E<lt>missingE<gt>]>. - -This defaults to C<0> (no missing devices). - -The length of C<devices> + the number of bits set in -C<missingbitmap> must equal C<nrdevices> + C<spare>. - -=item C<nrdevices> - -The number of active RAID devices. - -If not set, this defaults to the length of C<devices> plus -the number of bits set in C<missingbitmap>. - -=item C<spare> - -The number of spare devices. - -If not set, this defaults to C<0>. - -=item C<chunk> - -The chunk size in bytes. - -=item C<level> - -The RAID level, which can be one of: -I<linear>, I<raid0>, I<0>, I<stripe>, I<raid1>, I<1>, I<mirror>, -I<raid4>, I<4>, I<raid5>, I<5>, I<raid6>, I<6>, I<raid10>, I<10>. -Some of these are synonymous, and more levels may be added in future. - -If not set, this defaults to C<raid1>. - -=back" }; - - { defaults with - name = "list_md_devices"; added = (1, 15, 4); - style = RStringList "devices", [], []; - proc_nr = Some 300; - shortdesc = "list Linux md (RAID) devices"; - longdesc = "\ -List all Linux md devices." }; - - { defaults with - name = "md_detail"; added = (1, 15, 6); - style = RHashtable "info", [Device "md"], []; - proc_nr = Some 301; - optional = Some "mdadm"; - shortdesc = "obtain metadata for an MD device"; - longdesc = "\ -This command exposes the output of 'mdadm -DY E<lt>mdE<gt>'. -The following fields are usually present in the returned hash. -Other fields may also be present. - -=over - -=item C<level> - -The raid level of the MD device. - -=item C<devices> - -The number of underlying devices in the MD device. - -=item C<metadata> - -The metadata version used. - -=item C<uuid> - -The UUID of the MD device. - -=item C<name> - -The name of the MD device. - -=back" }; - - { defaults with - name = "md_stop"; added = (1, 15, 6); - style = RErr, [Device "md"], []; - proc_nr = Some 302; - optional = Some "mdadm"; - shortdesc = "stop a Linux md (RAID) device"; - longdesc = "\ -This command deactivates the MD array named C<md>. The -device is stopped, but it is not destroyed or zeroed." }; - - { defaults with - name = "blkid"; added = (1, 15, 9); - style = RHashtable "info", [Device "device"], []; - proc_nr = Some 303; - tests = [ - InitScratchFS, Always, TestResult ( - [["blkid"; "/dev/sdb1"]], - "check_hash (ret, \"TYPE\", \"ext2\") == 0 && "^ - "check_hash (ret, \"USAGE\", \"filesystem\") == 0 && "^ - "check_hash (ret, \"PART_ENTRY_NUMBER\", \"1\") == 0 && "^ - "check_hash (ret, \"PART_ENTRY_TYPE\", \"0x83\") == 0 && "^ - "check_hash (ret, \"PART_ENTRY_OFFSET\", \"128\") == 0 && "^ - "check_hash (ret, \"PART_ENTRY_SIZE\", \"4194049\") == 0"), []; - ]; - shortdesc = "print block device attributes"; - longdesc = "\ -This command returns block device attributes for C<device>. The following fields are -usually present in the returned hash. Other fields may also be present. - -=over - -=item C<UUID> - -The uuid of this device. - -=item C<LABEL> - -The label of this device. - -=item C<VERSION> - -The version of blkid command. - -=item C<TYPE> - -The filesystem type or RAID of this device. - -=item C<USAGE> - -The usage of this device, for example C<filesystem> or C<raid>. - -=back" }; - - { defaults with - name = "e2fsck"; added = (1, 15, 17); - style = RErr, [Device "device"], [OBool "correct"; OBool "forceall"]; - proc_nr = Some 304; - shortdesc = "check an ext2/ext3 filesystem"; - longdesc = "\ -This runs the ext2/ext3 filesystem checker on C<device>. -It can take the following optional arguments: - -=over 4 - -=item C<correct> - -Automatically repair the file system. This option will cause e2fsck -to automatically fix any filesystem problems that can be safely -fixed without human intervention. - -This option may not be specified at the same time as the C<forceall> option. - -=item C<forceall> - -Assume an answer of 'yes' to all questions; allows e2fsck to be used -non-interactively. - -This option may not be specified at the same time as the C<correct> option. - -=back" }; - - { defaults with - name = "llz"; added = (1, 17, 6); - style = RString "listing", [Pathname "directory"], []; - proc_nr = Some 305; - deprecated_by = Some "lgetxattrs"; - shortdesc = "list the files in a directory (long format with SELinux contexts)"; - longdesc = "\ -List the files in F<directory> in the format of 'ls -laZ'. - -This command is mostly useful for interactive sessions. It -is I<not> intended that you try to parse the output string." }; - - { defaults with - name = "wipefs"; added = (1, 17, 6); - style = RErr, [Device "device"], []; - proc_nr = Some 306; - optional = Some "wipefs"; - tests = [ - InitBasicFSonLVM, Always, TestRun ( - [["umount"; "/dev/VG/LV"; ""; ""]; - ["wipefs"; "/dev/VG/LV"]]), [] - ]; - shortdesc = "wipe a filesystem signature from a device"; - longdesc = "\ -This command erases filesystem or RAID signatures from -the specified C<device> to make the filesystem invisible to libblkid. - -This does not erase the filesystem itself nor any other data from the -C<device>. - -Compare with C<guestfs_zero> which zeroes the first few blocks of a -device." }; - - { defaults with - name = "ntfsfix"; added = (1, 17, 9); - style = RErr, [Device "device"], [OBool "clearbadsectors"]; - proc_nr = Some 307; - optional = Some "ntfs3g"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["ntfsfix"; "/dev/sda1"; "false"]]), [] - ]; - shortdesc = "fix common errors and force Windows to check NTFS"; - longdesc = "\ -This command repairs some fundamental NTFS inconsistencies, -resets the NTFS journal file, and schedules an NTFS consistency -check for the first boot into Windows. - -This is I<not> an equivalent of Windows C<chkdsk>. It does I<not> -scan the filesystem for inconsistencies. - -The optional C<clearbadsectors> flag clears the list of bad sectors. -This is useful after cloning a disk with bad sectors to a new disk." }; - - { defaults with - name = "ntfsclone_out"; added = (1, 17, 9); - style = RErr, [Device "device"; FileOut "backupfile"], [OBool "metadataonly"; OBool "rescue"; OBool "ignorefscheck"; OBool "preservetimestamps"; OBool "force"]; - proc_nr = Some 308; - optional = Some "ntfs3g"; cancellable = true; - test_excuse = "tested in tests/ntfsclone"; - shortdesc = "save NTFS to backup file"; - longdesc = "\ -Stream the NTFS filesystem C<device> to the local file -C<backupfile>. The format used for the backup file is a -special format used by the L<ntfsclone(8)> tool. - -If the optional C<metadataonly> flag is true, then I<only> the -metadata is saved, losing all the user data (this is useful -for diagnosing some filesystem problems). - -The optional C<rescue>, C<ignorefscheck>, C<preservetimestamps> -and C<force> flags have precise meanings detailed in the -L<ntfsclone(8)> man page. - -Use C<guestfs_ntfsclone_in> to restore the file back to a -libguestfs device." }; - - { defaults with - name = "ntfsclone_in"; added = (1, 17, 9); - style = RErr, [FileIn "backupfile"; Device "device"], []; - proc_nr = Some 309; - optional = Some "ntfs3g"; cancellable = true; - test_excuse = "tested in tests/ntfsclone"; - shortdesc = "restore NTFS from backup file"; - longdesc = "\ -Restore the C<backupfile> (from a previous call to -C<guestfs_ntfsclone_out>) to C<device>, overwriting -any existing contents of this device." }; - - { defaults with - name = "set_label"; added = (1, 17, 9); - style = RErr, [Mountable "mountable"; String "label"], []; - proc_nr = Some 310; - tests = [ - InitBasicFS, Always, TestResultString ( - [["set_label"; "/dev/sda1"; "testlabel"]; - ["vfs_label"; "/dev/sda1"]], "testlabel"), []; - InitPartition, IfAvailable "ntfs3g", TestResultString ( - [["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["set_label"; "/dev/sda1"; "testlabel2"]; - ["vfs_label"; "/dev/sda1"]], "testlabel2"), []; - InitPartition, Always, TestLastFail ( - [["zero"; "/dev/sda1"]; - ["set_label"; "/dev/sda1"; "testlabel2"]]), [] - ]; - shortdesc = "set filesystem label"; - longdesc = "\ -Set the filesystem label on C<mountable> to C<label>. - -Only some filesystem types support labels, and libguestfs supports -setting labels on only a subset of these. - -=over 4 - -=item ext2, ext3, ext4 - -Labels are limited to 16 bytes. - -=item NTFS - -Labels are limited to 128 unicode characters. - -=item XFS - -The label is limited to 12 bytes. The filesystem must not -be mounted when trying to set the label. - -=item btrfs - -The label is limited to 255 bytes and some characters are -not allowed. Setting the label on a btrfs subvolume will set the -label on its parent filesystem. The filesystem must not be mounted -when trying to set the label. - -=item fat - -The label is limited to 11 bytes. - -=item swap - -The label is limited to 16 bytes. - -=back - -If there is no support for changing the label -for the type of the specified filesystem, -set_label will fail and set errno as ENOTSUP. - -To read the label on a filesystem, call C<guestfs_vfs_label>." }; - - { defaults with - name = "zero_free_space"; added = (1, 17, 18); - style = RErr, [Pathname "directory"], []; - proc_nr = Some 311; - progress = true; - tests = [ - InitScratchFS, Always, TestRun ( - [["zero_free_space"; "/"]]), [] - ]; - shortdesc = "zero free space in a filesystem"; - longdesc = "\ -Zero the free space in the filesystem mounted on F<directory>. -The filesystem must be mounted read-write. - -The filesystem contents are not affected, but any free space -in the filesystem is freed. - -Free space is not \"trimmed\". You may want to call -C<guestfs_fstrim> either as an alternative to this, -or after calling this, depending on your requirements." }; - - { defaults with - name = "lvcreate_free"; added = (1, 17, 18); - style = RErr, [String "logvol"; String "volgroup"; Int "percent"], []; - proc_nr = Some 312; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate_free"; "LV1"; "VG"; "50"]; - ["lvcreate_free"; "LV2"; "VG"; "50"]; - ["lvcreate_free"; "LV3"; "VG"; "50"]; - ["lvcreate_free"; "LV4"; "VG"; "100"]; - ["lvs"]], - "is_string_list (ret, 4, \"/dev/VG/LV1\", \"/dev/VG/LV2\", \"/dev/VG/LV3\", \"/dev/VG/LV4\")"), [] - ]; - shortdesc = "create an LVM logical volume in % remaining free space"; - longdesc = "\ -Create an LVM logical volume called F</dev/volgroup/logvol>, -using approximately C<percent> % of the free space remaining -in the volume group. Most usefully, when C<percent> is C<100> -this will create the largest possible LV." }; - - { defaults with - name = "isoinfo_device"; added = (1, 17, 19); - style = RStruct ("isodata", "isoinfo"), [Device "device"], []; - proc_nr = Some 313; - tests = [ - InitNone, Always, TestResult ( - [["isoinfo_device"; "/dev/sdd"]], - "STREQ (ret->iso_system_id, GUESTFS_ISO_SYSTEM_ID) && "^ - "STREQ (ret->iso_volume_id, \"CDROM\") && "^ - "STREQ (ret->iso_volume_set_id, \"\") && "^ - "ret->iso_volume_set_size == 1 && "^ - "ret->iso_volume_sequence_number == 1 && "^ - "ret->iso_logical_block_size == 2048"), [] - ]; - shortdesc = "get ISO information from primary volume descriptor of device"; - longdesc = "\ -C<device> is an ISO device. This returns a struct of information -read from the primary volume descriptor (the ISO equivalent of the -superblock) of the device. - -Usually it is more efficient to use the L<isoinfo(1)> command -with the I<-d> option on the host to analyze ISO files, -instead of going through libguestfs. - -For information on the primary volume descriptor fields, see -L<http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>" }; - - { defaults with - name = "isoinfo"; added = (1, 17, 19); - style = RStruct ("isodata", "isoinfo"), [Pathname "isofile"], []; - proc_nr = Some 314; - shortdesc = "get ISO information from primary volume descriptor of ISO file"; - longdesc = "\ -This is the same as C<guestfs_isoinfo_device> except that it -works for an ISO file located inside some other mounted filesystem. -Note that in the common case where you have added an ISO file -as a libguestfs device, you would I<not> call this. Instead -you would call C<guestfs_isoinfo_device>." }; - - { defaults with - name = "vgmeta"; added = (1, 17, 20); - style = RBufferOut "metadata", [String "vgname"], []; - proc_nr = Some 315; - optional = Some "lvm2"; - shortdesc = "get volume group metadata"; - longdesc = "\ -C<vgname> is an LVM volume group. This command examines the -volume group and returns its metadata. - -Note that the metadata is an internal structure used by LVM, -subject to change at any time, and is provided for information only." }; - - { defaults with - name = "md_stat"; added = (1, 17, 21); - style = RStructList ("devices", "mdstat"), [Device "md"], []; - proc_nr = Some 316; - optional = Some "mdadm"; - shortdesc = "get underlying devices from an MD device"; - longdesc = "\ -This call returns a list of the underlying devices which make -up the single software RAID array device C<md>. - -To get a list of software RAID devices, call C<guestfs_list_md_devices>. - -Each structure returned corresponds to one device along with -additional status information: - -=over 4 - -=item C<mdstat_device> - -The name of the underlying device. - -=item C<mdstat_index> - -The index of this device within the array. - -=item C<mdstat_flags> - -Flags associated with this device. This is a string containing -(in no specific order) zero or more of the following flags: - -=over 4 - -=item C<W> - -write-mostly - -=item C<F> - -device is faulty - -=item C<S> - -device is a RAID spare - -=item C<R> - -replacement - -=back - -=back" }; - - { defaults with - name = "mkfs_btrfs"; added = (1, 17, 25); - style = RErr, [DeviceList "devices"], [OInt64 "allocstart"; OInt64 "bytecount"; OString "datatype"; OInt "leafsize"; OString "label"; OString "metadata"; OInt "nodesize"; OInt "sectorsize"]; - proc_nr = Some 317; - optional = Some "btrfs"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs_btrfs"; "/dev/sda1"; "0"; "268435456"; "single"; ""; "test"; "single"; "65536"; "512"]]), [] - ]; - shortdesc = "create a btrfs filesystem"; - longdesc = "\ -Create a btrfs filesystem, allowing all configurables to be set. -For more information on the optional arguments, see L<mkfs.btrfs(8)>. - -Since btrfs filesystems can span multiple devices, this takes a -non-empty list of devices. - -To create general filesystems, use C<guestfs_mkfs>." }; - - { defaults with - name = "get_e2attrs"; added = (1, 17, 31); - style = RString "attrs", [Pathname "file"], []; - proc_nr = Some 318; - tests = [ - InitScratchFS, Always, TestResultString ( - [["touch"; "/e2attrs1"]; - ["get_e2attrs"; "/e2attrs1"]], ""), []; - InitScratchFS, Always, TestResultString ( - [["touch"; "/e2attrs2"]; - ["set_e2attrs"; "/e2attrs2"; "is"; "false"]; - ["get_e2attrs"; "/e2attrs2"]], "is"), []; - InitScratchFS, Always, TestResultString ( - [["touch"; "/e2attrs3"]; - ["set_e2attrs"; "/e2attrs3"; "is"; "false"]; - ["set_e2attrs"; "/e2attrs3"; "i"; "true"]; - ["get_e2attrs"; "/e2attrs3"]], "s"), []; - InitScratchFS, Always, TestResultString ( - [["touch"; "/e2attrs4"]; - ["set_e2attrs"; "/e2attrs4"; "adst"; "false"]; - ["set_e2attrs"; "/e2attrs4"; "iS"; "false"]; - ["set_e2attrs"; "/e2attrs4"; "i"; "true"]; - ["set_e2attrs"; "/e2attrs4"; "ad"; "true"]; - ["set_e2attrs"; "/e2attrs4"; ""; "false"]; - ["set_e2attrs"; "/e2attrs4"; ""; "true"]; - ["get_e2attrs"; "/e2attrs4"]], "Sst"), []; - InitScratchFS, Always, TestLastFail ( - [["touch"; "/e2attrs5"]; - ["set_e2attrs"; "/e2attrs5"; "R"; "false"]]), []; - InitScratchFS, Always, TestLastFail ( - [["touch"; "/e2attrs6"]; - ["set_e2attrs"; "/e2attrs6"; "v"; "false"]]), []; - InitScratchFS, Always, TestLastFail ( - [["touch"; "/e2attrs7"]; - ["set_e2attrs"; "/e2attrs7"; "aa"; "false"]]), []; - InitScratchFS, Always, TestLastFail ( - [["touch"; "/e2attrs8"]; - ["set_e2attrs"; "/e2attrs8"; "BabcdB"; "false"]]), [] - ]; - shortdesc = "get ext2 file attributes of a file"; - longdesc = "\ -This returns the file attributes associated with F<file>. - -The attributes are a set of bits associated with each -inode which affect the behaviour of the file. The attributes -are returned as a string of letters (described below). The -string may be empty, indicating that no file attributes are -set for this file. - -These attributes are only present when the file is located on -an ext2/3/4 filesystem. Using this call on other filesystem -types will result in an error. - -The characters (file attributes) in the returned string are -currently: - -=over 4 - -=item 'A' - -When the file is accessed, its atime is not modified. - -=item 'a' - -The file is append-only. - -=item 'c' - -The file is compressed on-disk. - -=item 'D' - -(Directories only.) Changes to this directory are written -synchronously to disk. - -=item 'd' - -The file is not a candidate for backup (see L<dump(8)>). - -=item 'E' - -The file has compression errors. - -=item 'e' - -The file is using extents. - -=item 'h' - -The file is storing its blocks in units of the filesystem blocksize -instead of sectors. - -=item 'I' - -(Directories only.) The directory is using hashed trees. - -=item 'i' - -The file is immutable. It cannot be modified, deleted or renamed. -No link can be created to this file. - -=item 'j' - -The file is data-journaled. - -=item 's' - -When the file is deleted, all its blocks will be zeroed. - -=item 'S' - -Changes to this file are written synchronously to disk. - -=item 'T' - -(Directories only.) This is a hint to the block allocator -that subdirectories contained in this directory should be -spread across blocks. If not present, the block allocator -will try to group subdirectories together. - -=item 't' - -For a file, this disables tail-merging. -(Not used by upstream implementations of ext2.) - -=item 'u' - -When the file is deleted, its blocks will be saved, allowing -the file to be undeleted. - -=item 'X' - -The raw contents of the compressed file may be accessed. - -=item 'Z' - -The compressed file is dirty. - -=back - -More file attributes may be added to this list later. Not all -file attributes may be set for all kinds of files. For -detailed information, consult the L<chattr(1)> man page. - -See also C<guestfs_set_e2attrs>. - -Don't confuse these attributes with extended attributes -(see C<guestfs_getxattr>)." }; - - { defaults with - name = "set_e2attrs"; added = (1, 17, 31); - style = RErr, [Pathname "file"; String "attrs"], [OBool "clear"]; - proc_nr = Some 319; - shortdesc = "set ext2 file attributes of a file"; - longdesc = "\ -This sets or clears the file attributes C<attrs> -associated with the inode F<file>. - -C<attrs> is a string of characters representing -file attributes. See C<guestfs_get_e2attrs> for a list of -possible attributes. Not all attributes can be changed. - -If optional boolean C<clear> is not present or false, then -the C<attrs> listed are set in the inode. - -If C<clear> is true, then the C<attrs> listed are cleared -in the inode. - -In both cases, other attributes not present in the C<attrs> -string are left unchanged. - -These attributes are only present when the file is located on -an ext2/3/4 filesystem. Using this call on other filesystem -types will result in an error." }; - - { defaults with - name = "get_e2generation"; added = (1, 17, 31); - style = RInt64 "generation", [Pathname "file"], []; - proc_nr = Some 320; - tests = [ - InitScratchFS, Always, TestResult ( - [["touch"; "/e2generation"]; - ["set_e2generation"; "/e2generation"; "123456"]; - ["get_e2generation"; "/e2generation"]], "ret == 123456"), [] - ]; - shortdesc = "get ext2 file generation of a file"; - longdesc = "\ -This returns the ext2 file generation of a file. The generation -(which used to be called the \"version\") is a number associated -with an inode. This is most commonly used by NFS servers. - -The generation is only present when the file is located on -an ext2/3/4 filesystem. Using this call on other filesystem -types will result in an error. - -See C<guestfs_set_e2generation>." }; - - { defaults with - name = "set_e2generation"; added = (1, 17, 31); - style = RErr, [Pathname "file"; Int64 "generation"], []; - proc_nr = Some 321; - shortdesc = "set ext2 file generation of a file"; - longdesc = "\ -This sets the ext2 file generation of a file. - -See C<guestfs_get_e2generation>." }; - - { defaults with - name = "btrfs_subvolume_snapshot"; added = (1, 17, 35); - style = RErr, [Pathname "source"; Pathname "dest"], [OBool "ro"; OString "qgroupid"]; - proc_nr = Some 322; - once_had_no_optargs = true; - optional = Some "btrfs"; camel_name = "BTRFSSubvolumeSnapshot"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["mkdir"; "/dir"]; - ["btrfs_subvolume_create"; "/test1"; "NOARG"]; - ["btrfs_subvolume_create"; "/test2"; "NOARG"]; - ["btrfs_subvolume_create"; "/dir/test3"; "NOARG"]; - ["btrfs_subvolume_snapshot"; "/dir/test3"; "/dir/test5"; "true"; "NOARG"]; - ["btrfs_subvolume_snapshot"; "/dir/test3"; "/dir/test6"; ""; "0/1000"]]), [] - ]; - shortdesc = "create a btrfs snapshot"; - longdesc = "\ -Create a snapshot of the btrfs subvolume C<source>. -The C<dest> argument is the destination directory and the name -of the snapshot, in the form F</path/to/dest/name>. By default -the newly created snapshot is writable, if the value of optional -parameter C<ro> is true, then a readonly snapshot is created. The -optional parameter C<qgroupid> represents the qgroup which the -newly created snapshot will be added to." }; - - { defaults with - name = "btrfs_subvolume_delete"; added = (1, 17, 35); - style = RErr, [Pathname "subvolume"], []; - proc_nr = Some 323; - optional = Some "btrfs"; camel_name = "BTRFSSubvolumeDelete"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_subvolume_create"; "/test1"; "NOARG"]; - ["btrfs_subvolume_delete"; "/test1"]]), [] - ]; - shortdesc = "delete a btrfs subvolume or snapshot"; - longdesc = "\ -Delete the named btrfs subvolume or snapshot." }; - - { defaults with - name = "btrfs_subvolume_create"; added = (1, 17, 35); - style = RErr, [Pathname "dest"], [OString "qgroupid"]; - proc_nr = Some 324; - once_had_no_optargs = true; - optional = Some "btrfs"; camel_name = "BTRFSSubvolumeCreate"; - shortdesc = "create a btrfs subvolume"; - longdesc = "\ -Create a btrfs subvolume. The C<dest> argument is the destination -directory and the name of the subvolume, in the form F</path/to/dest/name>. -The optional parameter C<qgroupid> represents the qgroup which the newly -created subvolume will be added to." }; - - { defaults with - name = "btrfs_subvolume_list"; added = (1, 17, 35); - style = RStructList ("subvolumes", "btrfssubvolume"), [Mountable_or_Path "fs"], []; - proc_nr = Some 325; - optional = Some "btrfs"; camel_name = "BTRFSSubvolumeList"; - test_excuse = "tested in tests/btrfs"; - shortdesc = "list btrfs snapshots and subvolumes"; - longdesc = "\ -List the btrfs snapshots and subvolumes of the btrfs filesystem -which is mounted at C<fs>." }; - - { defaults with - name = "btrfs_subvolume_set_default"; added = (1, 17, 35); - style = RErr, [Int64 "id"; Pathname "fs"], []; - proc_nr = Some 326; - optional = Some "btrfs"; camel_name = "BTRFSSubvolumeSetDefault"; - test_excuse = "tested in tests/btrfs"; - shortdesc = "set default btrfs subvolume"; - longdesc = "\ -Set the subvolume of the btrfs filesystem C<fs> which will -be mounted by default. See C<guestfs_btrfs_subvolume_list> to -get a list of subvolumes." }; - - { defaults with - name = "btrfs_filesystem_sync"; added = (1, 17, 35); - style = RErr, [Pathname "fs"], []; - proc_nr = Some 327; - optional = Some "btrfs"; camel_name = "BTRFSFilesystemSync"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_subvolume_create"; "/test1"; "NOARG"]; - ["btrfs_filesystem_sync"; "/test1"]; - ["btrfs_filesystem_balance"; "/test1"]]), [] - ]; - shortdesc = "sync a btrfs filesystem"; - longdesc = "\ -Force sync on the btrfs filesystem mounted at C<fs>." }; - - { defaults with - name = "btrfs_filesystem_balance"; added = (1, 17, 35); - style = RErr, [Pathname "fs"], []; - fish_alias = ["btrfs-balance"]; - proc_nr = Some 328; - optional = Some "btrfs"; camel_name = "BTRFSFilesystemBalance"; - shortdesc = "balance a btrfs filesystem"; - longdesc = "\ -Balance the chunks in the btrfs filesystem mounted at C<fs> -across the underlying devices." }; - - { defaults with - name = "btrfs_device_add"; added = (1, 17, 35); - style = RErr, [DeviceList "devices"; Pathname "fs"], []; - proc_nr = Some 329; - optional = Some "btrfs"; camel_name = "BTRFSDeviceAdd"; - test_excuse = "test disk isn't large enough to test this thoroughly, so there is an external test in 'tests/btrfs' directory"; - shortdesc = "add devices to a btrfs filesystem"; - longdesc = "\ -Add the list of device(s) in C<devices> to the btrfs filesystem -mounted at C<fs>. If C<devices> is an empty list, this does nothing." }; - - { defaults with - name = "btrfs_device_delete"; added = (1, 17, 35); - style = RErr, [DeviceList "devices"; Pathname "fs"], []; - proc_nr = Some 330; - optional = Some "btrfs"; camel_name = "BTRFSDeviceDelete"; - test_excuse = "test disk isn't large enough to test this thoroughly, so there is an external test in 'tests/btrfs' directory."; - shortdesc = "remove devices from a btrfs filesystem"; - longdesc = "\ -Remove the C<devices> from the btrfs filesystem mounted at C<fs>. -If C<devices> is an empty list, this does nothing." }; - - { defaults with - name = "btrfs_set_seeding"; added = (1, 17, 43); - style = RErr, [Device "device"; Bool "seeding"], []; - proc_nr = Some 331; - optional = Some "btrfs"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_set_seeding"; "/dev/sda1"; "true"]; - ["btrfs_set_seeding"; "/dev/sda1"; "false"]]), [] - ]; - shortdesc = "enable or disable the seeding feature of device"; - longdesc = "\ -Enable or disable the seeding feature of a device that contains -a btrfs filesystem." }; - - { defaults with - name = "btrfs_fsck"; added = (1, 17, 43); - style = RErr, [Device "device"], [OInt64 "superblock"; OBool "repair"]; - proc_nr = Some 332; - optional = Some "btrfs"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_fsck"; "/dev/sda1"; ""; ""]]), [] - ]; - shortdesc = "check a btrfs filesystem"; - longdesc = "\ -Used to check a btrfs filesystem, C<device> is the device file where the -filesystem is stored." }; - - { defaults with - name = "filesystem_available"; added = (1, 19, 5); - style = RBool "fsavail", [String "filesystem"], []; - proc_nr = Some 333; - shortdesc = "check if filesystem is available"; - longdesc = "\ -Check whether libguestfs supports the named filesystem. -The argument C<filesystem> is a filesystem name, such as -C<ext3>. - -You must call C<guestfs_launch> before using this command. - -This is mainly useful as a negative test. If this returns true, -it doesn't mean that a particular filesystem can be created -or mounted, since filesystems can fail for other reasons -such as it being a later version of the filesystem, -or having incompatible features, or lacking the right -mkfs.E<lt>I<fs>E<gt> tool. - -See also C<guestfs_available>, C<guestfs_feature_available>, -L<guestfs(3)/AVAILABILITY>." }; - - { defaults with - name = "fstrim"; added = (1, 19, 6); - style = RErr, [Pathname "mountpoint"], [OInt64 "offset"; OInt64 "length"; OInt64 "minimumfreeextent"]; - proc_nr = Some 334; - optional = Some "fstrim"; - shortdesc = "trim free space in a filesystem"; - longdesc = "\ -Trim the free space in the filesystem mounted on C<mountpoint>. -The filesystem must be mounted read-write. - -The filesystem contents are not affected, but any free space -in the filesystem is \"trimmed\", that is, given back to the host -device, thus making disk images more sparse, allowing unused space -in qcow2 files to be reused, etc. - -This operation requires support in libguestfs, the mounted -filesystem, the host filesystem, qemu and the host kernel. -If this support isn't present it may give an error or even -appear to run but do nothing. - -In the case where the kernel vfs driver does not support -trimming, this call will fail with errno set to C<ENOTSUP>. -Currently this happens when trying to trim FAT filesystems. - -See also C<guestfs_zero_free_space>. That is a slightly -different operation that turns free space in the filesystem -into zeroes. It is valid to call C<guestfs_fstrim> either -instead of, or after calling C<guestfs_zero_free_space>." }; - - { defaults with - name = "device_index"; added = (1, 19, 7); - style = RInt "index", [Device "device"], []; - proc_nr = Some 335; - tests = [ - InitEmpty, Always, TestResult ( - [["device_index"; "/dev/sda"]], "ret == 0"), [] - ]; - shortdesc = "convert device to index"; - longdesc = "\ -This function takes a device name (eg. \"/dev/sdb\") and -returns the index of the device in the list of devices. - -Index numbers start from 0. The named device must exist, -for example as a string returned from C<guestfs_list_devices>. - -See also C<guestfs_list_devices>, C<guestfs_part_to_dev>." }; - - { defaults with - name = "nr_devices"; added = (1, 19, 15); - style = RInt "nrdisks", [], []; - proc_nr = Some 336; - tests = [ - InitEmpty, Always, TestResult ( - [["nr_devices"]], "ret == 4"), [] - ]; - shortdesc = "return number of whole block devices (disks) added"; - longdesc = "\ -This returns the number of whole block devices that were -added. This is the same as the number of devices that would -be returned if you called C<guestfs_list_devices>. - -To find out the maximum number of devices that could be added, -call C<guestfs_max_disks>." }; - - { defaults with - name = "xfs_info"; added = (1, 19, 21); - style = RStruct ("info", "xfsinfo"), [Dev_or_Path "pathordevice"], []; - proc_nr = Some 337; - optional = Some "xfs"; - tests = [ - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["xfs_info"; "/"]], "ret->xfs_blocksize == 4096"), [] - ]; - shortdesc = "get geometry of XFS filesystem"; - longdesc = "\ -C<pathordevice> is a mounted XFS filesystem or a device containing -an XFS filesystem. This command returns the geometry of the filesystem. - -The returned struct contains geometry information. Missing -fields are returned as C<-1> (for numeric fields) or empty -string." }; - - { defaults with - name = "pvchange_uuid"; added = (1, 19, 26); - style = RErr, [Device "device"], []; - proc_nr = Some 338; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["pvchange_uuid"; "/dev/sda1"]]), [] - ]; - shortdesc = "generate a new random UUID for a physical volume"; - longdesc = "\ -Generate a new random UUID for the physical volume C<device>." }; - - { defaults with - name = "pvchange_uuid_all"; added = (1, 19, 26); - style = RErr, [], []; - proc_nr = Some 339; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["pvchange_uuid_all"]]), [] - ]; - shortdesc = "generate new random UUIDs for all physical volumes"; - longdesc = "\ -Generate new random UUIDs for all physical volumes." }; - - { defaults with - name = "vgchange_uuid"; added = (1, 19, 26); - style = RErr, [String "vg"], []; - proc_nr = Some 340; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["vgchange_uuid"; "/dev/VG"]]), [] - ]; - shortdesc = "generate a new random UUID for a volume group"; - longdesc = "\ -Generate a new random UUID for the volume group C<vg>." }; - - { defaults with - name = "vgchange_uuid_all"; added = (1, 19, 26); - style = RErr, [], []; - proc_nr = Some 341; - optional = Some "lvm2"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["vgchange_uuid_all"]]), [] - ]; - shortdesc = "generate new random UUIDs for all volume groups"; - longdesc = "\ -Generate new random UUIDs for all volume groups." }; - - { defaults with - name = "utsname"; added = (1, 19, 27); - style = RStruct ("uts", "utsname"), [], []; - proc_nr = Some 342; - tests = [ - InitEmpty, Always, TestRun ( - [["utsname"]]), [] - ]; - shortdesc = "appliance kernel version"; - longdesc = "\ -This returns the kernel version of the appliance, where this is -available. This information is only useful for debugging. Nothing -in the returned structure is defined by the API." }; - - { defaults with - name = "xfs_growfs"; added = (1, 19, 28); - style = RErr, [Pathname "path"], [OBool "datasec"; OBool "logsec"; OBool "rtsec"; OInt64 "datasize"; OInt64 "logsize"; OInt64 "rtsize"; OInt64 "rtextsize"; OInt "maxpct"]; - proc_nr = Some 343; - optional = Some "xfs"; - tests = [ - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["pvcreate"; "/dev/sda1"]; - ["vgcreate"; "VG"; "/dev/sda1"]; - ["lvcreate"; "LV"; "VG"; "40"]; - ["mkfs"; "xfs"; "/dev/VG/LV"; ""; "NOARG"; ""; ""; "NOARG"]; - ["lvresize"; "/dev/VG/LV"; "80"]; - ["mount"; "/dev/VG/LV"; "/"]; - ["xfs_growfs"; "/"; "true"; "false"; "false"; ""; ""; ""; ""; ""]; - ["xfs_info"; "/"]], "ret->xfs_blocksize == 4096"), []; - ]; - shortdesc = "expand an existing XFS filesystem"; - longdesc = "\ -Grow the XFS filesystem mounted at C<path>. - -The returned struct contains geometry information. Missing -fields are returned as C<-1> (for numeric fields) or empty -string." }; - - { defaults with - name = "rsync"; added = (1, 19, 29); - style = RErr, [Pathname "src"; Pathname "dest"], [OBool "archive"; OBool "deletedest"]; - proc_nr = Some 344; - optional = Some "rsync"; - test_excuse = "tests are in tests/rsync"; - shortdesc = "synchronize the contents of two directories"; - longdesc = "\ -This call may be used to copy or synchronize two directories -under the same libguestfs handle. This uses the L<rsync(1)> -program which uses a fast algorithm that avoids copying files -unnecessarily. - -C<src> and C<dest> are the source and destination directories. -Files are copied from C<src> to C<dest>. - -The optional arguments are: - -=over 4 - -=item C<archive> - -Turns on archive mode. This is the same as passing the -I<--archive> flag to C<rsync>. - -=item C<deletedest> - -Delete files at the destination that do not exist at the source. - -=back" }; - - { defaults with - name = "rsync_in"; added = (1, 19, 29); - style = RErr, [String "remote"; Pathname "dest"], [OBool "archive"; OBool "deletedest"]; - proc_nr = Some 345; - optional = Some "rsync"; - test_excuse = "tests are in tests/rsync"; - shortdesc = "synchronize host or remote filesystem with filesystem"; - longdesc = "\ -This call may be used to copy or synchronize the filesystem -on the host or on a remote computer with the filesystem -within libguestfs. This uses the L<rsync(1)> program -which uses a fast algorithm that avoids copying files unnecessarily. - -This call only works if the network is enabled. See -C<guestfs_set_network> or the I<--network> option to -various tools like L<guestfish(1)>. - -Files are copied from the remote server and directory -specified by C<remote> to the destination directory C<dest>. - -The format of the remote server string is defined by L<rsync(1)>. -Note that there is no way to supply a password or passphrase -so the target must be set up not to require one. - -The optional arguments are the same as those of C<guestfs_rsync>." }; - - { defaults with - name = "rsync_out"; added = (1, 19, 29); - style = RErr, [Pathname "src"; String "remote"], [OBool "archive"; OBool "deletedest"]; - proc_nr = Some 346; - optional = Some "rsync"; - test_excuse = "tests are in tests/rsync"; - shortdesc = "synchronize filesystem with host or remote filesystem"; - longdesc = "\ -This call may be used to copy or synchronize the filesystem within -libguestfs with a filesystem on the host or on a remote computer. -This uses the L<rsync(1)> program which uses a fast algorithm that -avoids copying files unnecessarily. - -This call only works if the network is enabled. See -C<guestfs_set_network> or the I<--network> option to -various tools like L<guestfish(1)>. - -Files are copied from the source directory C<src> to the -remote server and directory specified by C<remote>. - -The format of the remote server string is defined by L<rsync(1)>. -Note that there is no way to supply a password or passphrase -so the target must be set up not to require one. - -The optional arguments are the same as those of C<guestfs_rsync>. - -Globbing does not happen on the C<src> parameter. In programs -which use the API directly you have to expand wildcards yourself -(see C<guestfs_glob_expand>). In guestfish you can use the C<glob> -command (see L<guestfish(1)/glob>), for example: - - ><fs> glob rsync-out /* rsync://remote/" }; - - { defaults with - name = "ls0"; added = (1, 19, 32); - style = RErr, [Pathname "dir"; FileOut "filenames"], []; - proc_nr = Some 347; - shortdesc = "get list of files in a directory"; - longdesc = "\ -This specialized command is used to get a listing of -the filenames in the directory C<dir>. The list of filenames -is written to the local file F<filenames> (on the host). - -In the output file, the filenames are separated by C<\\0> characters. - -C<.> and C<..> are not returned. The filenames are not sorted." }; - - { defaults with - name = "fill_dir"; added = (1, 19, 32); - style = RErr, [Pathname "dir"; Int "nr"], []; - proc_nr = Some 348; - shortdesc = "fill a directory with empty files"; - longdesc = "\ -This function, useful for testing filesystems, creates C<nr> -empty files in the directory C<dir> with names C<00000000> -through C<nr-1> (ie. each file name is 8 digits long padded -with zeroes)." }; - - { defaults with - name = "xfs_admin"; added = (1, 19, 33); - style = RErr, [Device "device"], [OBool "extunwritten"; OBool "imgfile"; OBool "v2log"; OBool "projid32bit"; OBool "lazycounter"; OString "label"; OString "uuid"]; - proc_nr = Some 349; - optional = Some "xfs"; - tests = [ - InitEmpty, Always, TestResult ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["xfs_admin"; "/dev/sda1"; ""; ""; ""; ""; "false"; "NOARG"; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["xfs_info"; "/"]], "ret->xfs_lazycount == 0"), []; - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["xfs_admin"; "/dev/sda1"; ""; ""; ""; ""; ""; "NOARG"; stable_uuid]; - ["vfs_uuid"; "/dev/sda1"]], stable_uuid), []; - InitEmpty, Always, TestResultString ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["xfs_admin"; "/dev/sda1"; ""; ""; ""; ""; ""; "LBL-TEST"; "NOARG"]; - ["vfs_label"; "/dev/sda1"]], "LBL-TEST"), []; - ]; - shortdesc = "change parameters of an XFS filesystem"; - longdesc = "\ -Change the parameters of the XFS filesystem on C<device>. - -Devices that are mounted cannot be modified. -Administrators must unmount filesystems before this call -can modify parameters. - -Some of the parameters of a mounted filesystem can be examined -and modified using the C<guestfs_xfs_info> and -C<guestfs_xfs_growfs> calls." }; - - { defaults with - name = "hivex_open"; added = (1, 19, 35); - style = RErr, [Pathname "filename"], [OBool "verbose"; OBool "debug"; OBool "write"; OBool "unsafe"]; - proc_nr = Some 350; - optional = Some "hivex"; - tests = [ - InitScratchFS, Always, TestRun ( - [["upload"; "$srcdir/../../test-data/files/minimal"; "/hivex_open"]; - ["hivex_open"; "/hivex_open"; ""; ""; "false"; ""]; - ["hivex_root"]; (* in this hive, it returns 0x1020 *) - ["hivex_node_name"; "0x1020"]; - ["hivex_node_children"; "0x1020"]; - ["hivex_node_values"; "0x1020"]]), [["hivex_close"]] - ]; - shortdesc = "open a Windows Registry hive file"; - longdesc = "\ -Open the Windows Registry hive file named F<filename>. -If there was any previous hivex handle associated with this -guestfs session, then it is closed. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_close"; added = (1, 19, 35); - style = RErr, [], []; - proc_nr = Some 351; - optional = Some "hivex"; - shortdesc = "close the current hivex handle"; - longdesc = "\ -Close the current hivex handle. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_root"; added = (1, 19, 35); - style = RInt64 "nodeh", [], []; - proc_nr = Some 352; - optional = Some "hivex"; - shortdesc = "return the root node of the hive"; - longdesc = "\ -Return the root node of the hive. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_name"; added = (1, 19, 35); - style = RString "name", [Int64 "nodeh"], []; - proc_nr = Some 353; - optional = Some "hivex"; - shortdesc = "return the name of the node"; - longdesc = "\ -Return the name of C<nodeh>. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_children"; added = (1, 19, 35); - style = RStructList ("nodehs", "hivex_node"), [Int64 "nodeh"], []; - proc_nr = Some 354; - optional = Some "hivex"; - shortdesc = "return list of nodes which are subkeys of node"; - longdesc = "\ -Return the list of nodes which are subkeys of C<nodeh>. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_get_child"; added = (1, 19, 35); - style = RInt64 "child", [Int64 "nodeh"; String "name"], []; - proc_nr = Some 355; - optional = Some "hivex"; - shortdesc = "return the named child of node"; - longdesc = "\ -Return the child of C<nodeh> with the name C<name>, if it exists. -This can return C<0> meaning the name was not found. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_parent"; added = (1, 19, 35); - style = RInt64 "parent", [Int64 "nodeh"], []; - proc_nr = Some 356; - optional = Some "hivex"; - shortdesc = "return the parent of node"; - longdesc = "\ -Return the parent node of C<nodeh>. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_values"; added = (1, 19, 35); - style = RStructList ("valuehs", "hivex_value"), [Int64 "nodeh"], []; - proc_nr = Some 357; - optional = Some "hivex"; - shortdesc = "return list of values attached to node"; - longdesc = "\ -Return the array of (key, datatype, data) tuples attached to C<nodeh>. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_get_value"; added = (1, 19, 35); - style = RInt64 "valueh", [Int64 "nodeh"; String "key"], []; - proc_nr = Some 358; - optional = Some "hivex"; - shortdesc = "return the named value"; - longdesc = "\ -Return the value attached to C<nodeh> which has the -name C<key>, if it exists. This can return C<0> meaning -the key was not found. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_value_key"; added = (1, 19, 35); - style = RString "key", [Int64 "valueh"], []; - proc_nr = Some 359; - optional = Some "hivex"; - shortdesc = "return the key field from the (key, datatype, data) tuple"; - longdesc = "\ -Return the key (name) field of a (key, datatype, data) tuple. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_value_type"; added = (1, 19, 35); - style = RInt64 "datatype", [Int64 "valueh"], []; - proc_nr = Some 360; - optional = Some "hivex"; - shortdesc = "return the data type from the (key, datatype, data) tuple"; - longdesc = "\ -Return the data type field from a (key, datatype, data) tuple. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_value_value"; added = (1, 19, 35); - style = RBufferOut "databuf", [Int64 "valueh"], []; - proc_nr = Some 361; - optional = Some "hivex"; - shortdesc = "return the data field from the (key, datatype, data) tuple"; - longdesc = "\ -Return the data field of a (key, datatype, data) tuple. - -This is a wrapper around the L<hivex(3)> call of the same name. - -See also: C<guestfs_hivex_value_utf8>." }; - - { defaults with - name = "hivex_commit"; added = (1, 19, 35); - style = RErr, [OptString "filename"], []; - proc_nr = Some 362; - optional = Some "hivex"; - tests = [ - InitScratchFS, Always, TestRun ( - [["upload"; "$srcdir/../../test-data/files/minimal"; "/hivex_commit1"]; - ["hivex_open"; "/hivex_commit1"; ""; ""; "true"; ""]; - ["hivex_commit"; "NULL"]]), [["hivex_close"]]; - InitScratchFS, Always, TestResultTrue ( - [["upload"; "$srcdir/../../test-data/files/minimal"; "/hivex_commit2"]; - ["hivex_open"; "/hivex_commit2"; ""; ""; "true"; ""]; - ["hivex_commit"; "/hivex_commit2_copy"]; - ["is_file"; "/hivex_commit2_copy"; "false"]]), [["hivex_close"]] - ]; - shortdesc = "commit (write) changes back to the hive"; - longdesc = "\ -Commit (write) changes to the hive. - -If the optional F<filename> parameter is null, then the changes -are written back to the same hive that was opened. If this is -not null then they are written to the alternate filename given -and the original hive is left untouched. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_add_child"; added = (1, 19, 35); - style = RInt64 "nodeh", [Int64 "parent"; String "name"], []; - proc_nr = Some 363; - optional = Some "hivex"; - shortdesc = "add a child node"; - longdesc = "\ -Add a child node to C<parent> named C<name>. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_delete_child"; added = (1, 19, 35); - style = RErr, [Int64 "nodeh"], []; - proc_nr = Some 364; - optional = Some "hivex"; - shortdesc = "delete a node (recursively)"; - longdesc = "\ -Delete C<nodeh>, recursively if necessary. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "hivex_node_set_value"; added = (1, 19, 35); - style = RErr, [Int64 "nodeh"; String "key"; Int64 "t"; BufferIn "val"], []; - proc_nr = Some 365; - optional = Some "hivex"; - shortdesc = "set or replace a single value in a node"; - longdesc = "\ -Set or replace a single value under the node C<nodeh>. The -C<key> is the name, C<t> is the type, and C<val> is the data. - -This is a wrapper around the L<hivex(3)> call of the same name." }; - - { defaults with - name = "xfs_repair"; added = (1, 19, 36); - style = RInt "status", [Dev_or_Path "device"], [OBool "forcelogzero"; OBool "nomodify"; OBool "noprefetch"; OBool "forcegeometry"; OInt64 "maxmem"; OInt64 "ihashsize"; OInt64 "bhashsize"; OInt64 "agstride"; OString "logdev"; OString "rtdev"]; - proc_nr = Some 366; - optional = Some "xfs"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_disk"; "/dev/sda"; "mbr"]; - ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["xfs_repair"; "/dev/sda1"; ""; "true"; ""; ""; ""; ""; ""; ""; "NOARG"; "NOARG"] - ]), [] - ]; - shortdesc = "repair an XFS filesystem"; - longdesc = "\ -Repair corrupt or damaged XFS filesystem on C<device>. - -The filesystem is specified using the C<device> argument which should be -the device name of the disk partition or volume containing the filesystem. -If given the name of a block device, C<xfs_repair> will attempt to find -the raw device associated with the specified block device and will use -the raw device instead. - -Regardless, the filesystem to be repaired must be unmounted, otherwise, -the resulting filesystem may be inconsistent or corrupt. - -The returned status indicates whether filesystem corruption was -detected (returns C<1>) or was not detected (returns C<0>)." }; - - { defaults with - name = "rm_f"; added = (1, 19, 42); - style = RErr, [Pathname "path"], []; - proc_nr = Some 367; - tests = [ - InitScratchFS, Always, TestResultFalse - [["mkdir"; "/rm_f"]; - ["touch"; "/rm_f/foo"]; - ["rm_f"; "/rm_f/foo"]; - ["rm_f"; "/rm_f/not_exists"]; - ["exists"; "/rm_f/foo"]], []; - InitScratchFS, Always, TestLastFail - [["mkdir"; "/rm_f2"]; - ["mkdir"; "/rm_f2/foo"]; - ["rm_f"; "/rm_f2/foo"]], [] - ]; - shortdesc = "remove a file ignoring errors"; - longdesc = "\ -Remove the file C<path>. - -If the file doesn't exist, that error is ignored. (Other errors, -eg. I/O errors or bad paths, are not ignored) - -This call cannot remove directories. -Use C<guestfs_rmdir> to remove an empty directory, -or C<guestfs_rm_rf> to remove directories recursively." }; - - { defaults with - name = "mke2fs"; added = (1, 19, 44); - style = RErr, [Device "device"], [OInt64 "blockscount"; OInt64 "blocksize"; OInt64 "fragsize"; OInt64 "blockspergroup"; OInt64 "numberofgroups"; OInt64 "bytesperinode"; OInt64 "inodesize"; OInt64 "journalsize"; OInt64 "numberofinodes"; OInt64 "stridesize"; OInt64 "stripewidth"; OInt64 "maxonlineresize"; OInt "reservedblockspercentage"; OInt "mmpupdateinterval"; OString "journaldevice"; OString "label"; OString "lastmounteddir"; OString "creatoros"; OString "fstype"; OString "usagetype"; OString "uuid"; OBool "forcecreate"; OBool "writesbandgrouponly"; OBool "lazyitableinit"; OBool "lazyjournalinit"; OBool "testfs"; OBool "discard"; OBool "quotatype"; OBool "extent"; OBool "filetype"; OBool "flexbg"; OBool "hasjournal"; OBool "journaldev"; OBool "largefile"; OBool "quota"; OBool "resizeinode"; OBool "sparsesuper"; OBool "uninitbg"]; - proc_nr = Some 368; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; - ["mke2fs"; "/dev/sda1"; ""; "4096"; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; "NOARG"; - "NOARG"; "NOARG"; "NOARG"; "NOARG"; "NOARG"; - "NOARG"; ""; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; "true"; ""; ""; - ""; ""; ""]; - ["mke2fs"; "/dev/sda2"; ""; "4096"; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; "/dev/sda1"; - "NOARG"; "NOARG"; "NOARG"; "ext2"; "NOARG"; - "NOARG"; ""; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""]; - ["mount"; "/dev/sda2"; "/"]; - ["write"; "/new"; "new file contents"]; - ["cat"; "/new"]], "new file contents"), []; - InitEmpty, Always, TestResultString ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; - ["mke2fs"; "/dev/sda1"; ""; "4096"; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; "/dev/sda1"; - "JOURNAL"; "NOARG"; "NOARG"; "ext2"; "NOARG"; - "NOARG"; ""; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; "true"; ""; ""; - ""; ""; ""]; - ["mke2fs"; "/dev/sda2"; ""; "4096"; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; "LABEL=JOURNAL"; - "JOURNAL"; "NOARG"; "NOARG"; "ext2"; "NOARG"; - "NOARG"; ""; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""]; - ["mount"; "/dev/sda2"; "/"]; - ["write"; "/new"; "new file contents"]; - ["cat"; "/new"]], "new file contents"), []; - InitEmpty, Always, TestResultString ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; - ["mke2fs"; "/dev/sda1"; ""; "4096"; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; "NOARG"; - "NOARG"; "NOARG"; "NOARG"; "NOARG"; "NOARG"; - stable_uuid; ""; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; "true"; ""; ""; - ""; ""; ""]; - ["mke2fs"; "/dev/sda2"; ""; "4096"; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; "UUID=" ^ stable_uuid; - "JOURNAL"; "NOARG"; "NOARG"; "ext2"; "NOARG"; - "NOARG"; "true"; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""; ""; ""; - ""; ""; ""]; - ["mount"; "/dev/sda2"; "/"]; - ["write"; "/new"; "new file contents"]; - ["cat"; "/new"]], "new file contents"), [] - ]; - shortdesc = "create an ext2/ext3/ext4 filesystem on device"; - (* XXX document optional args properly *) - longdesc = "\ -C<mke2fs> is used to create an ext2, ext3, or ext4 filesystem -on C<device>. - -The optional C<blockscount> is the size of the filesystem in blocks. -If omitted it defaults to the size of C<device>. Note if the -filesystem is too small to contain a journal, C<mke2fs> will -silently create an ext2 filesystem instead." }; - - { defaults with - name = "list_disk_labels"; added = (1, 19, 49); - style = RHashtable "labels", [], []; - proc_nr = Some 369; - tests = [ - (* The test disks have no labels, so we can be sure there are - * no labels. See in tests/disk-labels/ for tests checking - * for actual disk labels. - * - * Also, we make use of the assumption that RHashtable is a - * char*[] in C, so an empty hash has just a NULL element. - *) - InitScratchFS, Always, TestResult ( - [["list_disk_labels"]], - "is_string_list (ret, 0)"), []; - ]; - shortdesc = "mapping of disk labels to devices"; - longdesc = "\ -If you add drives using the optional C<label> parameter -of C<guestfs_add_drive_opts>, you can use this call to -map between disk labels, and raw block device and partition -names (like F</dev/sda> and F</dev/sda1>). - -This returns a hashtable, where keys are the disk labels -(I<without> the F</dev/disk/guestfs> prefix), and the values -are the full raw block device and partition names -(eg. F</dev/sda> and F</dev/sda1>)." }; - - { defaults with - name = "internal_hot_add_drive"; added = (1, 19, 49); - style = RErr, [String "label"], []; - proc_nr = Some 370; - visibility = VInternal; - shortdesc = "internal hotplugging operation"; - longdesc = "\ -This function is used internally when hotplugging drives." }; - - { defaults with - name = "internal_hot_remove_drive_precheck"; added = (1, 19, 49); - style = RErr, [String "label"], []; - proc_nr = Some 371; - visibility = VInternal; - shortdesc = "internal hotplugging operation"; - longdesc = "\ -This function is used internally when hotplugging drives." }; - - { defaults with - name = "internal_hot_remove_drive"; added = (1, 19, 49); - style = RErr, [String "label"], []; - proc_nr = Some 372; - visibility = VInternal; - shortdesc = "internal hotplugging operation"; - longdesc = "\ -This function is used internally when hotplugging drives." }; - - { defaults with - name = "mktemp"; added = (1, 19, 53); - style = RString "path", [Pathname "tmpl"], [OString "suffix"]; - proc_nr = Some 373; - tests = [ - InitScratchFS, Always, TestRun ( - [["mkdir"; "/mktemp"]; - ["mktemp"; "/mktemp/tmpXXXXXX"; "NOARG"]; - ["mktemp"; "/mktemp/tmpXXXXXX"; "suff"]]), [] - ]; - shortdesc = "create a temporary file"; - longdesc = "\ -This command creates a temporary file. The -C<tmpl> parameter should be a full pathname for the -temporary directory name with the final six characters being -\"XXXXXX\". - -For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\", -the second one being suitable for Windows filesystems. - -The name of the temporary file that was created -is returned. - -The temporary file is created with mode 0600 -and is owned by root. - -The caller is responsible for deleting the temporary -file after use. - -If the optional C<suffix> parameter is given, then the suffix -(eg. C<.txt>) is appended to the temporary name. - -See also: C<guestfs_mkdtemp>." }; - - { defaults with - name = "mklost_and_found"; added = (1, 19, 56); - style = RErr, [Pathname "mountpoint"], []; - proc_nr = Some 374; - tests = [ - InitBasicFS, Always, TestRun ( - [["rm_rf"; "/lost+found"]; - ["mklost_and_found"; "/"]]), [] - ]; - shortdesc = "make lost+found directory on an ext2/3/4 filesystem"; - longdesc = "\ -Make the C<lost+found> directory, normally in the root directory -of an ext2/3/4 filesystem. C<mountpoint> is the directory under -which we try to create the C<lost+found> directory." }; - - { defaults with - name = "acl_get_file"; added = (1, 19, 63); - style = RString "acl", [Pathname "path"; String "acltype"], []; - proc_nr = Some 375; - optional = Some "acl"; - shortdesc = "get the POSIX ACL attached to a file"; - longdesc = "\ -This function returns the POSIX Access Control List (ACL) attached -to C<path>. The ACL is returned in \"long text form\" (see L<acl(5)>). - -The C<acltype> parameter may be: - -=over 4 - -=item C<access> - -Return the ordinary (access) ACL for any file, directory or -other filesystem object. - -=item C<default> - -Return the default ACL. Normally this only makes sense if -C<path> is a directory. - -=back" }; - - { defaults with - name = "acl_set_file"; added = (1, 19, 63); - style = RErr, [Pathname "path"; String "acltype"; String "acl"], []; - proc_nr = Some 376; - optional = Some "acl"; - tests = [ - InitScratchFS, Always, TestRun ( - [["touch"; "/acl_set_file_0"]; - ["acl_set_file"; "/acl_set_file_0"; "access"; "u::r-x,g::r-x,o::r-x"]; - ["acl_get_file"; "/acl_set_file_0"; "access"]]), []; - InitScratchFS, Always, TestRun ( - [["touch"; "/acl_set_file_1"]; - ["acl_set_file"; "/acl_set_file_1"; "access"; "u::r-x,g::r-x,o::r-x,m::rwx,u:500:rw,g:600:x"]]), []; - InitScratchFS, Always, TestLastFail ( - [["touch"; "/acl_set_file_2"]; - (* m (mask) entry is required when setting user or group ACLs *) - ["acl_set_file"; "/acl_set_file_2"; "access"; "u::r-x,g::r-x,o::r-x,u:500:rw,g:600:x"]]), []; - InitScratchFS, Always, TestLastFail ( - [["touch"; "/acl_set_file_3"]; - (* user does not exist *) - ["acl_set_file"; "/acl_set_file_3"; "access"; "u::r-x,g::r-x,o::r-x,m::rwx,u:notauser:rw"]]), []; - InitScratchFS, Always, TestLastFail ( - [["touch"; "/acl_set_file_4"]; - (* cannot set default on a non-directory *) - ["acl_set_file"; "/acl_set_file_4"; "default"; "u::r-x,g::r-x,o::r-x"]]), []; - InitScratchFS, Always, TestRun ( - [["mkdir"; "/acl_set_file_5"]; - ["acl_set_file"; "/acl_set_file_5"; "default"; "u::r-x,g::r-x,o::r-x"]]), []; - ]; - shortdesc = "set the POSIX ACL attached to a file"; - longdesc = "\ -This function sets the POSIX Access Control List (ACL) attached -to C<path>. - -The C<acltype> parameter may be: - -=over 4 - -=item C<access> - -Set the ordinary (access) ACL for any file, directory or -other filesystem object. - -=item C<default> - -Set the default ACL. Normally this only makes sense if -C<path> is a directory. - -=back - -The C<acl> parameter is the new ACL in either \"long text form\" -or \"short text form\" (see L<acl(5)>). The new ACL completely -replaces any previous ACL on the file. The ACL must contain the -full Unix permissions (eg. C<u::rwx,g::rx,o::rx>). - -If you are specifying individual users or groups, then the -mask field is also required (eg. C<m::rwx>), followed by the -C<u:I<ID>:...> and/or C<g:I<ID>:...> field(s). A full ACL -string might therefore look like this: - - u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx - \\ Unix permissions / \\mask/ \\ ACL / - -You should use numeric UIDs and GIDs. To map usernames and -groupnames to the correct numeric ID in the context of the -guest, use the Augeas functions (see C<guestfs_aug_init>)." }; - - { defaults with - name = "acl_delete_def_file"; added = (1, 19, 63); - style = RErr, [Pathname "dir"], []; - proc_nr = Some 377; - optional = Some "acl"; - tests = [ - (* Documentation for libacl says this should fail, but it doesn't. - * Therefore disable this test. - *) - InitScratchFS, Disabled, TestLastFail ( - [["touch"; "/acl_delete_def_file_0"]; - ["acl_delete_def_file"; "/acl_delete_def_file_0"]]), []; - InitScratchFS, Always, TestRun ( - [["mkdir"; "/acl_delete_def_file_1"]; - ["acl_set_file"; "/acl_delete_def_file_1"; "default"; "user::r-x,group::r-x,other::r-x"]; - ["acl_delete_def_file"; "/acl_delete_def_file_1"]]), []; - ]; - shortdesc = "delete the default POSIX ACL of a directory"; - longdesc = "\ -This function deletes the default POSIX Access Control List (ACL) -attached to directory C<dir>." }; - - { defaults with - name = "cap_get_file"; added = (1, 19, 63); - style = RString "cap", [Pathname "path"], []; - proc_nr = Some 378; - optional = Some "linuxcaps"; - shortdesc = "get the Linux capabilities attached to a file"; - longdesc = "\ -This function returns the Linux capabilities attached to C<path>. -The capabilities set is returned in text form (see L<cap_to_text(3)>). - -If no capabilities are attached to a file, an empty string is returned." }; - - { defaults with - name = "cap_set_file"; added = (1, 19, 63); - style = RErr, [Pathname "path"; String "cap"], []; - proc_nr = Some 379; - optional = Some "linuxcaps"; - tests = [ - InitScratchFS, Always, TestResultString ( - [["touch"; "/cap_set_file_0"]; - ["cap_set_file"; "/cap_set_file_0"; "cap_chown=p cap_chown+e"]; - ["cap_get_file"; "/cap_set_file_0"]], "= cap_chown+ep"), []; - ]; - shortdesc = "set the Linux capabilities attached to a file"; - longdesc = "\ -This function sets the Linux capabilities attached to C<path>. -The capabilities set C<cap> should be passed in text form -(see L<cap_from_text(3)>)." }; - - { defaults with - name = "list_ldm_volumes"; added = (1, 20, 0); - style = RStringList "devices", [], []; - proc_nr = Some 380; - optional = Some "ldm"; - shortdesc = "list all Windows dynamic disk volumes"; - longdesc = "\ -This function returns all Windows dynamic disk volumes -that were found at launch time. It returns a list of -device names." }; - - { defaults with - name = "list_ldm_partitions"; added = (1, 20, 0); - style = RStringList "devices", [], []; - proc_nr = Some 381; - optional = Some "ldm"; - shortdesc = "list all Windows dynamic disk partitions"; - longdesc = "\ -This function returns all Windows dynamic disk partitions -that were found at launch time. It returns a list of -device names." }; - - { defaults with - name = "ldmtool_create_all"; added = (1, 20, 0); - style = RErr, [], []; - proc_nr = Some 382; - optional = Some "ldm"; - shortdesc = "scan and create Windows dynamic disk volumes"; - longdesc = "\ -This function scans all block devices looking for Windows -dynamic disk volumes and partitions, and creates devices -for any that were found. - -Call C<guestfs_list_ldm_volumes> and C<guestfs_list_ldm_partitions> -to return all devices. - -Note that you B<don't> normally need to call this explicitly, -since it is done automatically at C<guestfs_launch> time. -However you might want to call this function if you have -hotplugged disks or have just created a Windows dynamic disk." }; - - { defaults with - name = "ldmtool_remove_all"; added = (1, 20, 0); - style = RErr, [], []; - proc_nr = Some 383; - optional = Some "ldm"; - shortdesc = "remove all Windows dynamic disk volumes"; - longdesc = "\ -This is essentially the opposite of C<guestfs_ldmtool_create_all>. -It removes the device mapper mappings for all Windows dynamic disk -volumes" }; - - { defaults with - name = "ldmtool_scan"; added = (1, 20, 0); - style = RStringList "guids", [], []; - proc_nr = Some 384; - optional = Some "ldm"; - shortdesc = "scan for Windows dynamic disks"; - longdesc = "\ -This function scans for Windows dynamic disks. It returns a list -of identifiers (GUIDs) for all disk groups that were found. These -identifiers can be passed to other C<guestfs_ldmtool_*> functions. - -This function scans all block devices. To scan a subset of -block devices, call C<guestfs_ldmtool_scan_devices> instead." }; - - { defaults with - name = "ldmtool_scan_devices"; added = (1, 20, 0); - style = RStringList "guids", [DeviceList "devices"], []; - proc_nr = Some 385; - optional = Some "ldm"; - shortdesc = "scan for Windows dynamic disks"; - longdesc = "\ -This function scans for Windows dynamic disks. It returns a list -of identifiers (GUIDs) for all disk groups that were found. These -identifiers can be passed to other C<guestfs_ldmtool_*> functions. - -The parameter C<devices> is a list of block devices which are -scanned. If this list is empty, all block devices are scanned." }; - - { defaults with - name = "ldmtool_diskgroup_name"; added = (1, 20, 0); - style = RString "name", [String "diskgroup"], []; - proc_nr = Some 386; - optional = Some "ldm"; - shortdesc = "return the name of a Windows dynamic disk group"; - longdesc = "\ -Return the name of a Windows dynamic disk group. The C<diskgroup> -parameter should be the GUID of a disk group, one element from -the list returned by C<guestfs_ldmtool_scan>." }; - - { defaults with - name = "ldmtool_diskgroup_volumes"; added = (1, 20, 0); - style = RStringList "volumes", [String "diskgroup"], []; - proc_nr = Some 387; - optional = Some "ldm"; - shortdesc = "return the volumes in a Windows dynamic disk group"; - longdesc = "\ -Return the volumes in a Windows dynamic disk group. The C<diskgroup> -parameter should be the GUID of a disk group, one element from -the list returned by C<guestfs_ldmtool_scan>." }; - - { defaults with - name = "ldmtool_diskgroup_disks"; added = (1, 20, 0); - style = RStringList "disks", [String "diskgroup"], []; - proc_nr = Some 388; - optional = Some "ldm"; - shortdesc = "return the disks in a Windows dynamic disk group"; - longdesc = "\ -Return the disks in a Windows dynamic disk group. The C<diskgroup> -parameter should be the GUID of a disk group, one element from -the list returned by C<guestfs_ldmtool_scan>." }; - - { defaults with - name = "ldmtool_volume_type"; added = (1, 20, 0); - style = RString "voltype", [String "diskgroup"; String "volume"], []; - proc_nr = Some 389; - optional = Some "ldm"; - shortdesc = "return the type of a Windows dynamic disk volume"; - longdesc = "\ -Return the type of the volume named C<volume> in the disk -group with GUID C<diskgroup>. - -Possible volume types that can be returned here include: -C<simple>, C<spanned>, C<striped>, C<mirrored>, C<raid5>. -Other types may also be returned." }; - - { defaults with - name = "ldmtool_volume_hint"; added = (1, 20, 0); - style = RString "hint", [String "diskgroup"; String "volume"], []; - proc_nr = Some 390; - optional = Some "ldm"; - shortdesc = "return the hint field of a Windows dynamic disk volume"; - longdesc = "\ -Return the hint field of the volume named C<volume> in the disk -group with GUID C<diskgroup>. This may not be defined, in which -case the empty string is returned. The hint field is often, though -not always, the name of a Windows drive, eg. C<E:>." }; - - { defaults with - name = "ldmtool_volume_partitions"; added = (1, 20, 0); - style = RStringList "partitions", [String "diskgroup"; String "volume"], []; - proc_nr = Some 391; - optional = Some "ldm"; - shortdesc = "return the partitions in a Windows dynamic disk volume"; - longdesc = "\ -Return the list of partitions in the volume named C<volume> in the disk -group with GUID C<diskgroup>." }; - - { defaults with - name = "part_set_gpt_type"; added = (1, 21, 1); - style = RErr, [Device "device"; Int "partnum"; GUID "guid"], []; - proc_nr = Some 392; - optional = Some "gdisk"; - tests = [ - InitGPT, Always, TestLastFail ( - [["part_set_gpt_type"; "/dev/sda"; "1"; "f"]]), []; - InitGPT, Always, TestResultString ( - [["part_set_gpt_type"; "/dev/sda"; "1"; - "01234567-89AB-CDEF-0123-456789ABCDEF"]; - ["part_get_gpt_type"; "/dev/sda"; "1"]], - "01234567-89AB-CDEF-0123-456789ABCDEF"), []; - ]; - shortdesc = "set the type GUID of a GPT partition"; - longdesc = "\ -Set the type GUID of numbered GPT partition C<partnum> to C<guid>. Return an -error if the partition table of C<device> isn't GPT, or if C<guid> is not a -valid GUID. - -See L<http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUI... -for a useful list of type GUIDs." }; - - { defaults with - name = "part_get_gpt_type"; added = (1, 21, 1); - style = RString "guid", [Device "device"; Int "partnum"], []; - proc_nr = Some 393; - optional = Some "gdisk"; - tests = [ - InitGPT, Always, TestResultString ( - [["part_set_gpt_type"; "/dev/sda"; "1"; - "01234567-89AB-CDEF-0123-456789ABCDEF"]; - ["part_get_gpt_type"; "/dev/sda"; "1"]], - "01234567-89AB-CDEF-0123-456789ABCDEF"), []; - ]; - shortdesc = "get the type GUID of a GPT partition"; - longdesc = "\ -Return the type GUID of numbered GPT partition C<partnum>. For MBR partitions, -return an appropriate GUID corresponding to the MBR type. Behaviour is undefined -for other partition types." }; - - { defaults with - name = "rename"; added = (1, 21, 5); - style = RErr, [Pathname "oldpath"; Pathname "newpath"], []; - proc_nr = Some 394; - tests = [ - InitScratchFS, Always, TestResultFalse ( - [["mkdir"; "/rename"]; - ["write"; "/rename/old"; "file content"]; - ["rename"; "/rename/old"; "/rename/new"]; - ["is_file"; "/rename/old"; ""]]), [] - ]; - shortdesc = "rename a file on the same filesystem"; - longdesc = "\ -Rename a file to a new place on the same filesystem. This is -the same as the Linux L<rename(2)> system call. In most cases -you are better to use C<guestfs_mv> instead." }; - - { defaults with - name = "is_whole_device"; added = (1, 21, 9); - style = RBool "flag", [Device "device"], []; - proc_nr = Some 395; - tests = [ - InitEmpty, Always, TestResultTrue ( - [["is_whole_device"; "/dev/sda"]]), []; - InitPartition, Always, TestResultFalse ( - [["is_whole_device"; "/dev/sda1"]]), []; - InitBasicFSonLVM, Always, TestResultFalse ( - [["is_whole_device"; "/dev/VG/LV"]]), []; - ]; - shortdesc = "test if a device is a whole device"; - longdesc = "\ -This returns C<true> if and only if C<device> refers to a whole block -device. That is, not a partition or a logical device." }; - - { defaults with - name = "internal_parse_mountable"; added = (1, 21, 11); - style = RStruct ("mountable", "internal_mountable"), [Mountable "mountable"], []; - visibility = VInternal; - proc_nr = Some 396; - shortdesc = "parse a mountable string"; - longdesc = "\ -Parse a mountable string." }; - - { defaults with - name = "internal_rhbz914931"; added = (1, 21, 14); - style = RErr, [FileIn "filename"; Int "count"], []; - proc_nr = Some 397; - visibility = VInternal; - cancellable = true; - shortdesc = "used only to test rhbz914931 (internal use only)"; - longdesc = "\ -This is only used to debug RHBZ#914931. Note that this -deliberately crashes guestfsd." }; - - { defaults with - name = "syslinux"; added = (1, 21, 27); - style = RErr, [Device "device"], [OString "directory"]; - proc_nr = Some 399; - optional = Some "syslinux"; - shortdesc = "install the SYSLINUX bootloader"; - longdesc = "\ -Install the SYSLINUX bootloader on C<device>. - -The device parameter must be either a whole disk formatted -as a FAT filesystem, or a partition formatted as a FAT filesystem. -In the latter case, the partition should be marked as \"active\" -(C<guestfs_part_set_bootable>) and a Master Boot Record must be -installed (eg. using C<guestfs_pwrite_device>) on the first -sector of the whole disk. -The SYSLINUX package comes with some suitable Master Boot Records. -See the L<syslinux(1)> man page for further information. - -The optional arguments are: - -=over 4 - -=item F<directory> - -Install SYSLINUX in the named subdirectory, instead of in the -root directory of the FAT filesystem. - -=back - -Additional configuration can be supplied to SYSLINUX by -placing a file called F<syslinux.cfg> on the FAT filesystem, -either in the root directory, or under F<directory> if that -optional argument is being used. For further information -about the contents of this file, see L<syslinux(1)>. - -See also C<guestfs_extlinux>." }; - - { defaults with - name = "extlinux"; added = (1, 21, 27); - style = RErr, [Pathname "directory"], []; - proc_nr = Some 400; - optional = Some "extlinux"; - shortdesc = "install the SYSLINUX bootloader on an ext2/3/4 or btrfs filesystem"; - longdesc = "\ -Install the SYSLINUX bootloader on the device mounted at F<directory>. -Unlike C<guestfs_syslinux> which requires a FAT filesystem, this can -be used on an ext2/3/4 or btrfs filesystem. - -The F<directory> parameter can be either a mountpoint, or a -directory within the mountpoint. - -You also have to mark the partition as \"active\" -(C<guestfs_part_set_bootable>) and a Master Boot Record must -be installed (eg. using C<guestfs_pwrite_device>) on the first -sector of the whole disk. -The SYSLINUX package comes with some suitable Master Boot Records. -See the L<extlinux(1)> man page for further information. - -Additional configuration can be supplied to SYSLINUX by -placing a file called F<extlinux.conf> on the filesystem -under F<directory>. For further information -about the contents of this file, see L<extlinux(1)>. - -See also C<guestfs_syslinux>." }; - - { defaults with - name = "cp_r"; added = (1, 21, 38); - style = RErr, [Pathname "src"; Pathname "dest"], []; - proc_nr = Some 401; - tests = [ - InitScratchFS, Always, TestResultString ( - [["mkdir"; "/cp_r1"]; - ["mkdir"; "/cp_r2"]; - ["write"; "/cp_r1/file"; "file content"]; - ["cp_r"; "/cp_r1"; "/cp_r2"]; - ["cat"; "/cp_r2/cp_r1/file"]], "file content"), [] - ]; - shortdesc = "copy a file or directory recursively"; - longdesc = "\ -This copies a file or directory from C<src> to C<dest> -recursively using the C<cp -rP> command. - -Most users should use C<guestfs_cp_a> instead. This command -is useful when you don't want to preserve permissions, because -the target filesystem does not support it (primarily when -writing to DOS FAT filesystems)." }; - - { defaults with - name = "remount"; added = (1, 23, 2); - style = RErr, [Pathname "mountpoint"], [OBool "rw"]; - proc_nr = Some 402; - tests = [ - InitScratchFS, Always, TestLastFail ( - [["remount"; "/"; "false"]; - ["write"; "/remount1"; "data"]]), []; - InitScratchFS, Always, TestRun ( - [["remount"; "/"; "false"]; - ["remount"; "/"; "true"]; - ["write"; "/remount2"; "data"]]), [] - ]; - shortdesc = "remount a filesystem with different options"; - longdesc = "\ -This call allows you to change the C<rw> (readonly/read-write) -flag on an already mounted filesystem at C<mountpoint>, -converting a readonly filesystem to be read-write, or vice-versa. - -Note that at the moment you must supply the \"optional\" C<rw> -parameter. In future we may allow other flags to be adjusted." }; - - { defaults with - name = "set_uuid"; added = (1, 23, 10); - style = RErr, [Device "device"; String "uuid"], []; - proc_nr = Some 403; - tests = [ - InitBasicFS, Always, TestResultString ( - [["set_uuid"; "/dev/sda1"; stable_uuid]; - ["vfs_uuid"; "/dev/sda1"]], stable_uuid), []; - ]; - shortdesc = "set the filesystem UUID"; - longdesc = "\ -Set the filesystem UUID on C<device> to C<uuid>. -If this fails and the errno is ENOTSUP, -means that there is no support for changing the UUID -for the type of the specified filesystem. - -Only some filesystem types support setting UUIDs. - -To read the UUID on a filesystem, call C<guestfs_vfs_uuid>." }; - - { defaults with - name = "journal_open"; added = (1, 23, 11); - style = RErr, [Pathname "directory"], []; - proc_nr = Some 404; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "open the systemd journal"; - longdesc = "\ -Open the systemd journal located in F<directory>. Any previously -opened journal handle is closed. - -The contents of the journal can be read using C<guestfs_journal_next> -and C<guestfs_journal_get>. - -After you have finished using the journal, you should close the -handle by calling C<guestfs_journal_close>." }; - - { defaults with - name = "journal_close"; added = (1, 23, 11); - style = RErr, [], []; - proc_nr = Some 405; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "close the systemd journal"; - longdesc = "\ -Close the journal handle." }; - - { defaults with - name = "journal_next"; added = (1, 23, 11); - style = RBool "more", [], []; - proc_nr = Some 406; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "move to the next journal entry"; - longdesc = "\ -Move to the next journal entry. You have to call this -at least once after opening the handle before you are able -to read data. - -The returned boolean tells you if there are any more journal -records to read. C<true> means you can read the next record -(eg. using C<guestfs_journal_get>), and C<false> means you -have reached the end of the journal." }; - - { defaults with - name = "journal_skip"; added = (1, 23, 11); - style = RInt64 "rskip", [Int64 "skip"], []; - proc_nr = Some 407; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "skip forwards or backwards in the journal"; - longdesc = "\ -Skip forwards (C<skip E<ge> 0>) or backwards (C<skip E<lt> 0>) in the -journal. - -The number of entries actually skipped is returned (note S<C<rskip E<ge> 0>>). -If this is not the same as the absolute value of the skip parameter -(C<|skip|>) you passed in then it means you have reached the end or -the start of the journal." }; - - { defaults with - name = "internal_journal_get"; added = (1, 23, 11); - style = RErr, [FileOut "filename"], []; - proc_nr = Some 408; - visibility = VInternal; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "internal journal reading operation"; - longdesc = "\ -This function is used internally when reading the journal." }; - - { defaults with - name = "journal_get_data_threshold"; added = (1, 23, 11); - style = RInt64 "threshold", [], []; - proc_nr = Some 409; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "get the data threshold for reading journal entries"; - longdesc = "\ -Get the current data threshold for reading journal entries. -This is a hint to the journal that it may truncate data fields to -this size when reading them (note also that it may not truncate them). -If this returns C<0>, then the threshold is unlimited. - -See also C<guestfs_journal_set_data_threshold>." }; - - { defaults with - name = "journal_set_data_threshold"; added = (1, 23, 11); - style = RErr, [Int64 "threshold"], []; - proc_nr = Some 410; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "set the data threshold for reading journal entries"; - longdesc = "\ -Set the data threshold for reading journal entries. -This is a hint to the journal that it may truncate data fields to -this size when reading them (note also that it may not truncate them). -If you set this to C<0>, then the threshold is unlimited. - -See also C<guestfs_journal_get_data_threshold>." }; - - { defaults with - name = "aug_setm"; added = (1, 23, 14); - style = RInt "nodes", [String "base"; OptString "sub"; String "val"], []; - proc_nr = Some 411; - tests = [ - InitBasicFS, Always, TestResultString ( - [["mkdir"; "/etc"]; - ["write"; "/etc/passwd"; "root:x:0:0:root:/root:/bin/bash\nbin:x:1:1:bin:/bin:/sbin/nologin\ndaemon:x:2:2:daemon:/sbin:/bin/csh\n"]; - ["aug_init"; "/"; "0"]; - ["aug_setm"; "/files/etc/passwd/*"; "shell"; "/sbin/nologin"]; - ["aug_save"]; - ["cat"; "/etc/passwd"]], "root:x:0:0:root:/root:/sbin/nologin\nbin:x:1:1:bin:/bin:/sbin/nologin\ndaemon:x:2:2:daemon:/sbin:/sbin/nologin\n"), [["aug_close"]] - ]; - shortdesc = "set multiple Augeas nodes"; - longdesc = "\ -Change multiple Augeas nodes in a single operation. C<base> is -an expression matching multiple nodes. C<sub> is a path expression -relative to C<base>. All nodes matching C<base> are found, and then -for each node, C<sub> is changed to C<val>. C<sub> may also be C<NULL> -in which case the C<base> nodes are modified. - -This returns the number of nodes modified." }; - - { defaults with - name = "aug_label"; added = (1, 23, 14); - style = RString "label", [String "augpath"], []; - proc_nr = Some 412; - tests = [ - InitBasicFS, Always, TestResultString ( - [["mkdir"; "/etc"]; - ["write"; "/etc/passwd"; "root:x:0:0:root:/root:/bin/bash\nbin:x:1:1:bin:/bin:/sbin/nologin\ndaemon:x:2:2:daemon:/sbin:/bin/csh\n"]; - ["aug_init"; "/"; "0"]; - ["aug_label"; "/files/etc/passwd/*[last()]"]], "daemon"), [["aug_close"]] - ]; - shortdesc = "return the label from an Augeas path expression"; - longdesc = "\ -The label (name of the last element) of the Augeas path expression -C<augpath> is returned. C<augpath> must match exactly one node, else -this function returns an error." }; - - { defaults with - name = "internal_upload"; added = (1, 23, 30); - style = RErr, [FileIn "filename"; String "tmpname"; Int "mode"], []; - proc_nr = Some 413; - visibility = VInternal; - cancellable = true; - shortdesc = "upload a file to the appliance (internal use only)"; - longdesc = "\ -This function is used internally when setting up the appliance." }; - - { defaults with - name = "internal_exit"; added = (1, 23, 30); - style = RErr, [], []; - proc_nr = Some 414; - (* Really VInternal, but we need to use it from the Perl bindings. XXX *) - visibility = VDebug; - cancellable = true; - shortdesc = "cause the daemon to exit (internal use only)"; - longdesc = "\ -This function is used internally when testing the appliance." }; - - { defaults with - name = "copy_attributes"; added = (1, 25, 21); - style = RErr, [Pathname "src"; Pathname "dest"], [OBool "all"; OBool "mode"; OBool "xattributes"; OBool "ownership"]; - proc_nr = Some 415; - shortdesc = "copy the attributes of a path (file/directory) to another"; - longdesc = "\ -Copy the attributes of a path (which can be a file or a directory) -to another path. - -By default C<no> attribute is copied, so make sure to specify any -(or C<all> to copy everything). - -The optional arguments specify which attributes can be copied: - -=over 4 - -=item C<mode> - -Copy part of the file mode from C<source> to C<destination>. Only the -UNIX permissions and the sticky/setuid/setgid bits can be copied. - -=item C<xattributes> - -Copy the Linux extended attributes (xattrs) from C<source> to C<destination>. -This flag does nothing if the I<linuxxattrs> feature is not available -(see C<guestfs_feature_available>). - -=item C<ownership> - -Copy the owner uid and the group gid of C<source> to C<destination>. - -=item C<all> - -Copy B<all> the attributes from C<source> to C<destination>. Enabling it -enables all the other flags, if they are not specified already. - -=back" }; - - { defaults with - name = "part_get_name"; added = (1, 25, 33); - style = RString "name", [Device "device"; Int "partnum"], []; - proc_nr = Some 416; - shortdesc = "get partition name"; - longdesc = "\ -This gets the partition name on partition numbered C<partnum> on -device C<device>. Note that partitions are numbered from 1. - -The partition name can only be read on certain types of partition -table. This works on C<gpt> but not on C<mbr> partitions." }; - - { defaults with - name = "blkdiscard"; added = (1, 25, 44); - style = RErr, [Device "device"], []; - proc_nr = Some 417; - optional = Some "blkdiscard"; - shortdesc = "discard all blocks on a device"; - longdesc = "\ -This discards all blocks on the block device C<device>, giving -the free space back to the host. - -This operation requires support in libguestfs, the host filesystem, -qemu and the host kernel. If this support isn't present it may give -an error or even appear to run but do nothing. You must also -set the C<discard> attribute on the underlying drive (see -C<guestfs_add_drive_opts>)." }; - - { defaults with - name = "blkdiscardzeroes"; added = (1, 25, 44); - style = RBool "zeroes", [Device "device"], []; - proc_nr = Some 418; - optional = Some "blkdiscardzeroes"; - shortdesc = "return true if discarded blocks are read as zeroes"; - longdesc = "\ -This call returns true if blocks on C<device> that have been -discarded by a call to C<guestfs_blkdiscard> are returned as -blocks of zero bytes when read the next time. - -If it returns false, then it may be that discarded blocks are -read as stale or random data." }; - - { defaults with - name = "cpio_out"; added = (1, 27, 9); - style = RErr, [String "directory"; FileOut "cpiofile"], [OString "format"]; - proc_nr = Some 419; - cancellable = true; - shortdesc = "pack directory into cpio file"; - longdesc = "\ -This command packs the contents of F<directory> and downloads -it to local file C<cpiofile>. - -The optional C<format> parameter can be used to select the format. -Only the following formats are currently permitted: - -=over 4 - -=item C<newc> - -New (SVR4) portable format. This format happens to be compatible -with the cpio-like format used by the Linux kernel for initramfs. - -This is the default format. - -=item C<crc> - -New (SVR4) portable format with a checksum. - -=back" }; - - { defaults with - name = "journal_get_realtime_usec"; added = (1, 27, 18); - style = RInt64 "usec", [], []; - proc_nr = Some 420; - optional = Some "journal"; - test_excuse = "tests in tests/journal subdirectory"; - shortdesc = "get the timestamp of the current journal entry"; - longdesc = "\ -Get the realtime (wallclock) timestamp of the current journal entry." }; - - { defaults with - name = "statns"; added = (1, 27, 53); - style = RStruct ("statbuf", "statns"), [Pathname "path"], []; - proc_nr = Some 421; - tests = [ - InitISOFS, Always, TestResult ( - [["statns"; "/empty"]], "ret->st_size == 0"), [] - ]; - shortdesc = "get file information"; - longdesc = "\ -Returns file information for the given C<path>. - -This is the same as the L<stat(2)> system call." }; - - { defaults with - name = "lstatns"; added = (1, 27, 53); - style = RStruct ("statbuf", "statns"), [Pathname "path"], []; - proc_nr = Some 422; - tests = [ - InitISOFS, Always, TestResult ( - [["lstatns"; "/empty"]], "ret->st_size == 0"), [] - ]; - shortdesc = "get file information for a symbolic link"; - longdesc = "\ -Returns file information for the given C<path>. - -This is the same as C<guestfs_statns> except that if C<path> -is a symbolic link, then the link is stat-ed, not the file it -refers to. - -This is the same as the L<lstat(2)> system call." }; - - { defaults with - name = "internal_lstatnslist"; added = (1, 27, 53); - style = RStructList ("statbufs", "statns"), [Pathname "path"; FilenameList "names"], []; - proc_nr = Some 423; - visibility = VInternal; - shortdesc = "lstat on multiple files"; - longdesc = "\ -This is the internal call which implements C<guestfs_lstatnslist>." }; - - { defaults with - name = "blockdev_setra"; added = (1, 29, 10); - style = RErr, [Device "device"; Int "sectors"], []; - proc_nr = Some 424; - tests = [ - InitEmpty, Always, TestRun ( - [["blockdev_setra"; "/dev/sda"; "1024" ]]), [] - ]; - shortdesc = "set readahead"; - longdesc = "\ -Set readahead (in 512-byte sectors) for the device. - -This uses the L<blockdev(8)> command." }; - - { defaults with - name = "btrfs_subvolume_get_default"; added = (1, 29, 17); - style = RInt64 "id", [Mountable_or_Path "fs"], []; - proc_nr = Some 425; - optional = Some "btrfs"; camel_name = "BTRFSSubvolumeGetDefault"; - tests = [ - InitPartition, Always, TestResult ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_subvolume_get_default"; "/dev/sda1"]], "ret > 0"), []; - InitPartition, Always, TestResult ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_subvolume_get_default"; "/"]], "ret > 0"), [] - ]; - shortdesc = "get the default subvolume or snapshot of a filesystem"; - longdesc = "\ -Get the default subvolume or snapshot of a filesystem mounted at C<mountpoint>." }; - - { defaults with - name = "btrfs_subvolume_show"; added = (1, 29, 17); - style = RHashtable "btrfssubvolumeinfo", [Pathname "subvolume"], []; - proc_nr = Some 426; - optional = Some "btrfs"; camel_name = "BTRFSSubvolumeShow"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_subvolume_create"; "/sub1"; "NOARG"]; - ["btrfs_subvolume_show"; "/sub1"]]), []; - InitPartition, Always, TestLastFail ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["mkdir"; "/dir1"]; - ["btrfs_subvolume_show"; "/dir1"]]), []; - ]; - shortdesc = "return detailed information of the subvolume"; - longdesc = "\ -Return detailed information of the subvolume." }; - - { defaults with - name = "btrfs_quota_enable"; added = (1, 29, 17); - style = RErr, [Mountable_or_Path "fs"; Bool "enable"], []; - proc_nr = Some 427; - optional = Some "btrfs"; camel_name = "BTRFSQuotaEnable"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_quota_enable"; "/dev/sda1"; "true"]]), []; - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "true"]]), []; - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_quota_enable"; "/dev/sda1"; "false"]]), []; - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "false"]]), []; - ]; - shortdesc = "enable or disable subvolume quota support"; - longdesc = "\ -Enable or disable subvolume quota support for filesystem which contains C<path>." }; - - { defaults with - name = "btrfs_quota_rescan"; added = (1, 29, 17); - style = RErr, [Mountable_or_Path "fs"], []; - proc_nr = Some 428; - optional = Some "btrfs"; camel_name = "BTRFSQuotaRescan"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_quota_enable"; "/dev/sda1"; "true"]; - ["btrfs_quota_rescan"; "/dev/sda1"]]), []; - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "true"]; - ["btrfs_quota_rescan"; "/"]]), []; - ]; - - shortdesc = "trash all qgroup numbers and scan the metadata again with the current config"; - longdesc = "\ -Trash all qgroup numbers and scan the metadata again with the current config." }; - - { defaults with - name = "btrfs_qgroup_limit"; added = (1, 29, 17); - style = RErr, [Pathname "subvolume"; Int64 "size"], []; - proc_nr = Some 429; - optional = Some "btrfs"; camel_name = "BTRFSQgroupLimit"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "true"]; - ["btrfs_qgroup_limit"; "/"; "10737418240"]]), []; - InitPartition, Always, TestLastFail ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "false"]; - ["btrfs_qgroup_limit"; "/"; "10737418240"]]), []; - ]; - shortdesc = "limit the size of a subvolume"; - longdesc = "\ -Limit the size of a subvolume which's path is C<subvolume>. C<size> -can have suffix of G, M, or K. " }; - - { defaults with - name = "btrfs_qgroup_create"; added = (1, 29, 17); - style = RErr, [String "qgroupid"; Pathname "subvolume"], []; - proc_nr = Some 430; - optional = Some "btrfs"; camel_name = "BTRFSQgroupCreate"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "true"]; - ["btrfs_subvolume_create"; "/sub1"; "NOARG"]; - ["btrfs_qgroup_create"; "0/1000"; "/sub1"]]), []; - ]; - shortdesc = "create a subvolume quota group"; - longdesc = "\ -Create a quota group (qgroup) for subvolume at C<subvolume>." }; - - { defaults with - name = "btrfs_qgroup_destroy"; added = (1, 29, 17); - style = RErr, [String "qgroupid"; Pathname "subvolume"], []; - proc_nr = Some 431; - optional = Some "btrfs"; camel_name = "BTRFSQgroupDestroy"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "true"]; - ["btrfs_subvolume_create"; "/sub1"; "NOARG"]; - ["btrfs_qgroup_create"; "0/1000"; "/sub1"]; - ["btrfs_qgroup_destroy"; "0/1000"; "/sub1"]]), []; - ]; - shortdesc = "destroy a subvolume quota group"; - longdesc = "\ -Destroy a quota group." }; - - { defaults with - name = "btrfs_qgroup_show"; added = (1, 29, 17); - style = RStructList ("qgroups", "btrfsqgroup"), [Pathname "path"], []; - proc_nr = Some 432; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "true"]; - ["btrfs_subvolume_create"; "/sub1"; "NOARG"]; - ["btrfs_qgroup_create"; "0/1000"; "/sub1"]; - ["btrfs_qgroup_show"; "/"]]), []; - ]; - optional = Some "btrfs"; camel_name = "BTRFSQgroupShow"; - shortdesc = "show subvolume quota groups"; - longdesc = "\ -Show all subvolume quota groups in a btrfs filesystem, including their -usages." }; - - { defaults with - name = "btrfs_qgroup_assign"; added = (1, 29, 17); - style = RErr, [String "src"; String "dst"; Pathname "path"], []; - proc_nr = Some 433; - optional = Some "btrfs"; camel_name = "BTRFSQgroupAssign"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "true"]; - ["btrfs_qgroup_create"; "0/1000"; "/"]; - ["btrfs_qgroup_create"; "1/1000"; "/"]; - ["btrfs_qgroup_assign"; "0/1000"; "1/1000"; "/"]]), []; - ]; - shortdesc = "add a qgroup to a parent qgroup"; - longdesc = "\ -Add qgroup C<src> to parent qgroup C<dst>. This command can group -several qgroups into a parent qgroup to share common limit." }; - - { defaults with - name = "btrfs_qgroup_remove"; added = (1, 29, 17); - style = RErr, [String "src"; String "dst"; Pathname "path"], []; - proc_nr = Some 434; - optional = Some "btrfs"; camel_name = "BTRFSQgroupRemove"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_quota_enable"; "/"; "true"]; - ["btrfs_qgroup_create"; "0/1000"; "/"]; - ["btrfs_qgroup_create"; "1/1000"; "/"]; - ["btrfs_qgroup_assign"; "0/1000"; "1/1000"; "/"]; - ["btrfs_qgroup_remove"; "0/1000"; "1/1000"; "/"]]), []; - ]; - shortdesc = "remove a qgroup from its parent qgroup"; - longdesc = "\ -Remove qgroup C<src> from the parent qgroup C<dst>." }; - - { defaults with - name = "btrfs_scrub_start"; added = (1, 29, 22); - style = RErr, [Pathname "path"], []; - proc_nr = Some 435; - optional = Some "btrfs"; camel_name = "BTRFSScrubStart"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_scrub_start"; "/"]]), []; - ]; - shortdesc = "read all data from all disks and verify checksums"; - longdesc = "\ -Reads all the data and metadata on the filesystem, and uses checksums -and the duplicate copies from RAID storage to identify and repair any -corrupt data." }; - - { defaults with - name = "btrfs_scrub_cancel"; added = (1, 29, 22); - style = RErr, [Pathname "path"], []; - proc_nr = Some 436; - optional = Some "btrfs"; camel_name = "BTRFSScrubCancel"; - test_excuse = "test disk isn't large enough that btrfs_scrub_start completes before we can cancel it"; - shortdesc = "cancel a running scrub"; - longdesc = "\ -Cancel a running scrub on a btrfs filesystem." }; - - { defaults with - name = "btrfs_scrub_resume"; added = (1, 29, 22); - style = RErr, [Pathname "path"], []; - proc_nr = Some 437; - optional = Some "btrfs"; camel_name = "BTRFSScrubResume"; - test_excuse = "test disk isn't large enough that btrfs_scrub_start completes before we can cancel and resume it"; - shortdesc = "resume a previously canceled or interrupted scrub"; - longdesc = "\ -Resume a previously canceled or interrupted scrub on a btrfs filesystem." }; - -{ defaults with - name = "btrfs_balance_pause"; added = (1, 29, 22); - style = RErr, [Pathname "path"], []; - proc_nr = Some 438; - optional = Some "btrfs"; camel_name = "BTRFSBalancePause"; - test_excuse = "test disk isn't large enough to test this thoroughly"; - shortdesc = "pause a running balance"; - longdesc = "\ -Pause a running balance on a btrfs filesystem." }; - -{ defaults with - name = "btrfs_balance_cancel"; added = (1, 29, 22); - style = RErr, [Pathname "path"], []; - proc_nr = Some 439; - optional = Some "btrfs"; camel_name = "BTRFSBalanceCancel"; - test_excuse = "test disk isn't large enough that btrfs_balance completes before we can cancel it"; - shortdesc = "cancel a running or paused balance"; - longdesc = "\ -Cancel a running balance on a btrfs filesystem." }; - -{ defaults with - name = "btrfs_balance_resume"; added = (1, 29, 22); - style = RErr, [Pathname "path"], []; - proc_nr = Some 440; - optional = Some "btrfs"; camel_name = "BTRFSBalanceResume"; - test_excuse = "test disk isn't large enough that btrfs_balance completes before we can pause and resume it"; - shortdesc = "resume a paused balance"; - longdesc = "\ -Resume a paused balance on a btrfs filesystem." }; - - { defaults with - name = "btrfs_filesystem_defragment"; added = (1, 29, 22); - style = RErr, [Pathname "path"], [OBool "flush"; OString "compress"]; - proc_nr = Some 443; - optional = Some "btrfs"; camel_name = "BTRFSFilesystemDefragment"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_filesystem_defragment"; "/"; "true"; "lzo"]]), []; - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["touch"; "/hello"]; - ["btrfs_filesystem_defragment"; "/hello"; ""; "zlib"]]), []; - ]; - shortdesc = "defragment a file or directory"; - longdesc = "\ -Defragment a file or directory on a btrfs filesystem. compress is one of zlib or lzo." }; - - { defaults with - name = "btrfs_rescue_chunk_recover"; added = (1, 29, 22); - style = RErr, [Device "device"], []; - proc_nr = Some 444; - optional = Some "btrfs"; camel_name = "BTRFSRescueChunkRecover"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_rescue_chunk_recover"; "/dev/sda1"]]), []; - ]; - shortdesc = "recover the chunk tree of btrfs filesystem"; - longdesc = "\ -Recover the chunk tree of btrfs filesystem by scanning the devices one by one." }; - - { defaults with - name = "btrfs_rescue_super_recover"; added = (1, 29, 22); - style = RErr, [Device "device"], []; - proc_nr = Some 445; - optional = Some "btrfs"; camel_name = "BTRFSRescueSuperRecover"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_rescue_super_recover"; "/dev/sda1"]]), []; - ]; - shortdesc = "recover bad superblocks from good copies"; - longdesc = "\ -Recover bad superblocks from good copies." }; - - { defaults with - name = "part_set_gpt_guid"; added = (1, 29, 25); - style = RErr, [Device "device"; Int "partnum"; GUID "guid"], []; - proc_nr = Some 446; - optional = Some "gdisk"; - tests = [ - InitGPT, Always, TestLastFail ( - [["part_set_gpt_guid"; "/dev/sda"; "1"; "f"]]), []; - InitGPT, Always, TestResultString ( - [["part_set_gpt_guid"; "/dev/sda"; "1"; - "01234567-89AB-CDEF-0123-456789ABCDEF"]; - ["part_get_gpt_guid"; "/dev/sda"; "1"]], - "01234567-89AB-CDEF-0123-456789ABCDEF"), []; - ]; - shortdesc = "set the GUID of a GPT partition"; - longdesc = "\ -Set the GUID of numbered GPT partition C<partnum> to C<guid>. Return an -error if the partition table of C<device> isn't GPT, or if C<guid> is not a -valid GUID." }; - - { defaults with - name = "part_get_gpt_guid"; added = (1, 29, 25); - style = RString "guid", [Device "device"; Int "partnum"], []; - proc_nr = Some 447; - optional = Some "gdisk"; - tests = [ - InitGPT, Always, TestResultString ( - [["part_set_gpt_guid"; "/dev/sda"; "1"; - "01234567-89AB-CDEF-0123-456789ABCDEF"]; - ["part_get_gpt_guid"; "/dev/sda"; "1"]], - "01234567-89AB-CDEF-0123-456789ABCDEF"), []; - ]; - shortdesc = "get the GUID of a GPT partition"; - longdesc = "\ -Return the GUID of numbered GPT partition C<partnum>." }; - -{ defaults with - name = "btrfs_balance_status"; added = (1, 29, 26); - style = RStruct ("status", "btrfsbalance"), [Pathname "path"], []; - proc_nr = Some 448; - optional = Some "btrfs"; camel_name = "BTRFSBalanceStatus"; - test_excuse = "test disk isn't large enough that btrfs_balance completes before we can get its status"; - shortdesc = "show the status of a running or paused balance"; - longdesc = "\ -Show the status of a running or paused balance on a btrfs filesystem." }; - - { defaults with - name = "btrfs_scrub_status"; added = (1, 29, 26); - style = RStruct ("status", "btrfsscrub"), [Pathname "path"], []; - proc_nr = Some 449; - optional = Some "btrfs"; camel_name = "BTRFSScrubStatus"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_scrub_start"; "/"]; - ["btrfs_scrub_status"; "/"]]), []; - ]; - shortdesc = "show status of running or finished scrub"; - longdesc = "\ -Show status of running or finished scrub on a btrfs filesystem." }; - - { defaults with - name = "btrfstune_seeding"; added = (1, 29, 29); - style = RErr, [Device "device"; Bool "seeding"], []; - proc_nr = Some 450; - optional = Some "btrfs"; camel_name = "BTRFSTuneSeeding"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfstune_seeding"; "/dev/sda1"; "true"]; - ["btrfstune_seeding"; "/dev/sda1"; "false"]]), [] - ]; - - shortdesc = "enable or disable seeding of a btrfs device"; - longdesc = "\ -Enable seeding of a btrfs device, this will force a fs readonly -so that you can use it to build other filesystems." }; - - { defaults with - name = "btrfstune_enable_extended_inode_refs"; added = (1, 29, 29); - style = RErr, [Device "device"], []; - proc_nr = Some 451; - optional = Some "btrfs"; camel_name = "BTRFSTuneEnableExtendedInodeRefs"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfstune_enable_extended_inode_refs"; "/dev/sda1"]]), [] - ]; - - shortdesc = "enable extended inode refs"; - longdesc = "\ -This will Enable extended inode refs." }; - - { defaults with - name = "btrfstune_enable_skinny_metadata_extent_refs"; added = (1, 29, 29); - style = RErr, [Device "device"], []; - proc_nr = Some 452; - optional = Some "btrfs"; camel_name = "BTRFSTuneEnableSkinnyMetadataExtentRefs"; - tests = [ - InitPartition, Always, TestRun ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfstune_enable_skinny_metadata_extent_refs"; "/dev/sda1"]]), [] - ]; - - shortdesc = "enable skinny metadata extent refs"; - longdesc = "\ -This enable skinny metadata extent refs." }; - - { defaults with - name = "btrfs_image"; added = (1, 29, 32); - style = RErr, [DeviceList "source"; Pathname "image"], [OInt "compresslevel"]; - proc_nr = Some 453; - optional = Some "btrfs"; camel_name = "BTRFSImage"; - tests = [ - InitEmpty, Always, TestRun ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "2047999"]; - ["part_add"; "/dev/sda"; "p"; "2048000"; "4095999"]; - ["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mkfs_btrfs"; "/dev/sda2"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["mount"; "/dev/sda1"; "/"]; - ["btrfs_image"; "/dev/sda2"; "/1.img"; ""]; - ["btrfs_image"; "/dev/sda2"; "/2.img"; "2"]]), [] - ]; - - shortdesc = "create an image of a btrfs filesystem"; - longdesc = "\ -This is used to create an image of a btrfs filesystem. -All data will be zeroed, but metadata and the like is preserved." }; - - { defaults with - name = "part_get_mbr_part_type"; added = (1, 29, 32); - style = RString "partitiontype", [Device "device"; Int "partnum"], []; - proc_nr = Some 454; - tests = [ - InitEmpty, Always, TestResultString ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["part_add"; "/dev/sda"; "e"; "204800"; "614400"]; - ["part_add"; "/dev/sda"; "l"; "204864"; "205988"]; - ["part_get_mbr_part_type"; "/dev/sda"; "5"]], "logical"), []; - InitEmpty, Always, TestResultString ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; - ["part_add"; "/dev/sda"; "e"; "204800"; "614400"]; - ["part_add"; "/dev/sda"; "l"; "204864"; "205988"]; - ["part_get_mbr_part_type"; "/dev/sda"; "2"]], "extended"), [] - ]; - - shortdesc = "get the MBR partition type"; - longdesc = "\ -This returns the partition type of an MBR partition -numbered C<partnum> on device C<device>. - -It returns C<primary>, C<logical>, or C<extended>." }; - - { defaults with - name = "btrfs_replace"; added = (1, 29, 48); - style = RErr, [Device "srcdev"; Device "targetdev"; Pathname "mntpoint"], []; - proc_nr = Some 455; - optional = Some "btrfs"; camel_name = "BTRFSReplace"; - test_excuse = "put the test in 'tests/btrfs' directory"; - shortdesc = "replace a btrfs managed device with another device"; - longdesc = "\ -Replace device of a btrfs filesystem. On a live filesystem, duplicate the data -to the target device which is currently stored on the source device. -After completion of the operation, the source device is wiped out and -removed from the filesystem. - -The C<targetdev> needs to be same size or larger than the C<srcdev>. Devices -which are currently mounted are never allowed to be used as the C<targetdev>." }; - - { defaults with - name = "set_uuid_random"; added = (1, 29, 50); - style = RErr, [Device "device"], []; - proc_nr = Some 456; - tests = [ - InitBasicFS, Always, TestRun ( - [["set_uuid_random"; "/dev/sda1"]]), []; - ]; - shortdesc = "set a random UUID for the filesystem"; - longdesc = "\ -Set the filesystem UUID on C<device> to a random UUID. -If this fails and the errno is ENOTSUP, -means that there is no support for changing the UUID -for the type of the specified filesystem. - -Only some filesystem types support setting UUIDs. - -To read the UUID on a filesystem, call C<guestfs_vfs_uuid>." }; - - { defaults with - name = "vfs_minimum_size"; added = (1, 31, 18); - style = RInt64 "sizeinbytes", [Mountable "mountable"], []; - proc_nr = Some 457; - tests = [ - InitBasicFS, Always, TestRun ( - [["vfs_minimum_size"; "/dev/sda1"]]), []; - InitPartition, IfAvailable "ntfsprogs", TestRun( - [["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["vfs_minimum_size"; "/dev/sda1"]]), []; - InitPartition, IfAvailable "btrfs", TestRunOrUnsupported ( - [["mkfs"; "btrfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["vfs_minimum_size"; "/dev/sda1"]]), []; - InitPartition, IfAvailable "xfs", TestRun ( - [["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; - ["mount"; "/dev/sda1"; "/"]; - ["vfs_minimum_size"; "/dev/sda1"]]), []; - ]; - shortdesc = "get minimum filesystem size"; - longdesc = "\ -Get the minimum size of filesystem in bytes. -This is the minimum possible size for filesystem shrinking. - -If getting minimum size of specified filesystem is not supported, -this will fail and set errno as ENOTSUP. - -See also L<ntfsresize(8)>, L<resize2fs(8)>, L<btrfs(8)>, L<xfs_info(8)>." }; - - { defaults with - name = "internal_feature_available"; added = (1, 31, 25); - style = RInt "result", [String "group"], []; - proc_nr = Some 458; - visibility = VInternal; - shortdesc = "test availability of some parts of the API"; - longdesc = "\ -This is the internal call which implements C<guestfs_feature_available>." }; - - { defaults with - name = "part_set_disk_guid"; added = (1, 33, 2); - style = RErr, [Device "device"; GUID "guid"], []; - proc_nr = Some 459; - optional = Some "gdisk"; - tests = [ - InitGPT, Always, TestLastFail ( - [["part_set_disk_guid"; "/dev/sda"; "f"]]), []; - InitGPT, Always, TestResultString ( - [["part_set_disk_guid"; "/dev/sda"; - "01234567-89AB-CDEF-0123-456789ABCDEF"]; - ["part_get_disk_guid"; "/dev/sda"]], - "01234567-89AB-CDEF-0123-456789ABCDEF"), []; - ]; - shortdesc = "set the GUID of a GPT-partitioned disk"; - longdesc = "\ -Set the disk identifier (GUID) of a GPT-partitioned C<device> to C<guid>. -Return an error if the partition table of C<device> isn't GPT, -or if C<guid> is not a valid GUID." }; - - { defaults with - name = "part_get_disk_guid"; added = (1, 33, 2); - style = RString "guid", [Device "device"], []; - proc_nr = Some 460; - optional = Some "gdisk"; - tests = [ - InitGPT, Always, TestResultString ( - [["part_set_disk_guid"; "/dev/sda"; - "01234567-89AB-CDEF-0123-456789ABCDEF"]; - ["part_get_disk_guid"; "/dev/sda"]], - "01234567-89AB-CDEF-0123-456789ABCDEF"), []; - ]; - shortdesc = "get the GUID of a GPT-partitioned disk"; - longdesc = "\ -Return the disk identifier (GUID) of a GPT-partitioned C<device>. -Behaviour is undefined for other partition types." }; - - { defaults with - name = "part_set_disk_guid_random"; added = (1, 33, 2); - style = RErr, [Device "device"], []; - proc_nr = Some 461; - optional = Some "gdisk"; - tests = [ - InitGPT, Always, TestRun ( - [["part_set_disk_guid_random"; "/dev/sda"]]), []; - ]; - shortdesc = "set the GUID of a GPT-partitioned disk to random value"; - longdesc = "\ -Set the disk identifier (GUID) of a GPT-partitioned C<device> to -a randomly generated value. -Return an error if the partition table of C<device> isn't GPT." }; - - { defaults with - name = "part_expand_gpt"; added = (1, 33, 2); - style = RErr, [Device "device"], []; - proc_nr = Some 462; - optional = Some "gdisk"; - shortdesc = "move backup GPT header to the end of the disk"; - longdesc = "\ -Move backup GPT data structures to the end of the disk. -This is useful in case of in-place image expand -since disk space after backup GPT header is not usable. -This is equivalent to C<sgdisk -e>. - -See also L<sgdisk(8)>." }; - - { defaults with - name = "ntfscat_i"; added = (1, 33, 14); - style = RErr, [Mountable "device"; Int64 "inode"; FileOut "filename"], []; - proc_nr = Some 463; - progress = true; cancellable = true; - shortdesc = "download a file to the local machine given its inode"; - longdesc = "\ -Download a file given its inode from a NTFS filesystem and save it as -F<filename> on the local machine. - -This allows to download some otherwise inaccessible files such as the ones -within the C<$Extend> folder. - -The filesystem from which to extract the file must be unmounted, -otherwise the call will fail." }; - - { defaults with - name = "download_inode"; added = (1, 33, 14); - style = RErr, [Mountable "device"; Int64 "inode"; FileOut "filename"], []; - proc_nr = Some 464; - optional = Some "sleuthkit"; - progress = true; cancellable = true; - shortdesc = "download a file to the local machine given its inode"; - longdesc = "\ -Download a file given its inode from the disk partition -(eg. F</dev/sda1>) and save it as F<filename> on the local machine. - -It is not required to mount the disk to run this command. - -The command is capable of downloading deleted or inaccessible files." }; - - { defaults with - name = "btrfs_filesystem_show"; added = (1, 33, 29); - style = RStringList "devices", [Device "device"], []; - proc_nr = Some 465; - optional = Some "btrfs"; camel_name = "BTRFSFilesystemsShow"; - tests = [ - InitScratchFS, Always, TestLastFail ( - [["btrfs_filesystem_show"; "/dev/sdb"]]), []; - InitPartition, Always, TestResult ( - [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_filesystem_show"; "/dev/sda1"]], - "is_string_list (ret, 1, \"/dev/sda1\")"), []; - InitEmpty, Always, TestResult ( - [["part_init"; "/dev/sda"; "mbr"]; - ["part_add"; "/dev/sda"; "p"; "64"; "2047999"]; - ["part_add"; "/dev/sda"; "p"; "2048000"; "4095999"]; - ["mkfs_btrfs"; "/dev/sda1 /dev/sda2"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; - ["btrfs_filesystem_show"; "/dev/sda1"]], - "is_string_list (ret, 2, \"/dev/sda1\", \"/dev/sda2\")"), []; - ]; - shortdesc = "list devices for btrfs filesystem"; - longdesc = "\ -Show all the devices where the filesystems in C<device> is spanned over. - -If not all the devices for the filesystems are present, then this function -fails and the C<errno> is set to C<ENODEV>." }; - - { defaults with - name = "internal_filesystem_walk"; added = (1, 33, 39); - style = RErr, [Mountable "device"; FileOut "filename"], []; - proc_nr = Some 466; - visibility = VInternal; - optional = Some "libtsk"; - shortdesc = "walk through the filesystem content"; - longdesc = "Internal function for filesystem_walk." }; - - { defaults with - name = "selinux_relabel"; added = (1, 33, 43); - style = RErr, [String "specfile"; Pathname "path"], [OBool "force"]; - proc_nr = Some 467; - optional = Some "selinuxrelabel"; - test_excuse = "tests are in the tests/relabel directory"; - shortdesc = "relabel parts of the filesystem"; - longdesc = "\ -SELinux relabel parts of the filesystem. - -The C<specfile> parameter controls the policy spec file used. -You have to parse C</etc/selinux/config> to find the correct -SELinux policy and then pass the spec file, usually: -C</etc/selinux/> + I<selinuxtype> + C</contexts/files/file_contexts>. - -The required C<path> parameter is the top level directory where -relabelling starts. Normally you should pass C<path> as C</> -to relabel the whole guest filesystem. - -The optional C<force> boolean controls whether the context -is reset for customizable files, and also whether the -user, role and range parts of the file context is changed." }; - - { defaults with - name = "download_blocks"; added = (1, 33, 45); - style = RErr, [Mountable "device"; Int64 "start"; Int64 "stop"; FileOut "filename"], [OBool "unallocated"]; - proc_nr = Some 468; - optional = Some "sleuthkit"; - progress = true; cancellable = true; - shortdesc = "download the given data units from the disk"; - longdesc = "\ -Download the data units from F<start> address -to F<stop> from the disk partition (eg. F</dev/sda1>) -and save them as F<filename> on the local machine. - -The use of this API on sparse disk image formats such as QCOW, -may result in large zero-filled files downloaded on the host. - -The size of a data unit varies across filesystem implementations. -On NTFS filesystems data units are referred as clusters -while on ExtX ones they are referred as fragments. - -If the optional C<unallocated> flag is true (default is false), -only the unallocated blocks will be extracted. -This is useful to detect hidden data or to retrieve deleted files -which data units have not been overwritten yet." }; - - { defaults with - name = "aug_transform"; added = (1, 35, 2); - style = RErr, [String "lens"; String "file"], [ OBool "remove"]; - proc_nr = Some 469; - shortdesc = "add/remove an Augeas lens transformation"; - longdesc = "\ -Add an Augeas transformation for the specified C<lens> so it can -handle C<file>. - -If C<remove> is true (C<false> by default), then the transformation -is removed." }; - - { defaults with - name = "internal_find_inode"; added = (1, 35, 6); - style = RErr, [Mountable "device"; Int64 "inode"; FileOut "filename";], []; - proc_nr = Some 470; - visibility = VInternal; - optional = Some "libtsk"; - shortdesc = "search the entries associated to the given inode"; - longdesc = "Internal function for find_inode." }; - - { defaults with - name = "mksquashfs"; added = (1, 35, 25); - style = RErr, [Pathname "path"; FileOut "filename"], [OString "compress"; OStringList "excludes"]; - proc_nr = Some 471; - optional = Some "squashfs"; - cancellable = true; - shortdesc = "create a squashfs filesystem"; - longdesc = "\ -Create a squashfs filesystem for the specified C<path>. - -The optional C<compress> flag controls compression. If not given, -then the output compressed using C<gzip>. Otherwise one -of the following strings may be given to select the compression -type of the squashfs: C<gzip>, C<lzma>, C<lzo>, C<lz4>, C<xz>. - -The other optional arguments are: - -=over 4 - -=item C<excludes> - -A list of wildcards. Files are excluded if they match any of the -wildcards. - -=back - -Please note that this API may fail when used to compress directories -with large files, such as the resulting squashfs will be over 3GB big." }; - -] +let daemon_functions = + Actions_augeas.daemon_functions @ + Actions_core.daemon_functions @ + Actions_core_deprecated.daemon_functions @ + Actions_debug.daemon_functions @ + Actions_hivex.daemon_functions @ + Actions_tsk.daemon_functions (* Non-API meta-commands available only in guestfish. * diff --git a/generator/actions_augeas.ml b/generator/actions_augeas.ml new file mode 100644 index 0000000..cc77c7f --- /dev/null +++ b/generator/actions_augeas.ml @@ -0,0 +1,278 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 + +(* Augeas APIs. *) + +let daemon_functions = [ + { defaults with + name = "aug_init"; added = (0, 0, 7); + style = RErr, [Pathname "root"; Int "flags"], []; + proc_nr = Some 16; + tests = [ + InitBasicFS, Always, TestResultString ( + [["mkdir"; "/etc"]; + ["write"; "/etc/hostname"; "test.example.org"]; + ["aug_init"; "/"; "0"]; + ["aug_get"; "/files/etc/hostname/hostname"]], "test.example.org"), [["aug_close"]] + ]; + 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<guestfs_aug_*> +commands. + +C<root> is the filesystem root. C<root> must not be NULL, +use F</> instead. + +The flags are the same as the flags defined in +E<lt>augeas.hE<gt>, the logical I<or> of the following +integers: + +=over 4 + +=item C<AUG_SAVE_BACKUP> = 1 + +Keep the original file with a C<.augsave> extension. + +=item C<AUG_SAVE_NEWFILE> = 2 + +Save changes into a file with extension C<.augnew>, and +do not overwrite original. Overrides C<AUG_SAVE_BACKUP>. + +=item C<AUG_TYPE_CHECK> = 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<LIBGUESTFS_MEMSIZE> +environment variable or call C<guestfs_set_memsize>. + +=item C<AUG_NO_STDINC> = 8 + +Do not use standard load path for modules. + +=item C<AUG_SAVE_NOOP> = 16 + +Make save a no-op, just record what would have been changed. + +=item C<AUG_NO_LOAD> = 32 + +Do not load the tree in C<guestfs_aug_init>. + +=back + +To close the handle, you can call C<guestfs_aug_close>. + +To find out more about Augeas, see L<http://augeas.net/>." }; + + { defaults with + name = "aug_close"; added = (0, 0, 7); + style = RErr, [], []; + proc_nr = Some 26; + 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<guestfs_aug_init> again before you can use any other +Augeas functions." }; + + { defaults with + name = "aug_defvar"; added = (0, 0, 7); + style = RInt "nrnodes", [String "name"; OptString "expr"], []; + proc_nr = Some 17; + shortdesc = "define an Augeas variable"; + longdesc = "\ +Defines an Augeas variable C<name> whose value is the result +of evaluating C<expr>. If C<expr> is NULL, then C<name> is +undefined. + +On success this returns the number of nodes in C<expr>, or +C<0> if C<expr> evaluates to something which is not a nodeset." }; + + { defaults with + name = "aug_defnode"; added = (0, 0, 7); + style = RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"], []; + proc_nr = Some 18; + shortdesc = "define an Augeas node"; + longdesc = "\ +Defines a variable C<name> whose value is the result of +evaluating C<expr>. + +If C<expr> evaluates to an empty nodeset, a node is created, +equivalent to calling C<guestfs_aug_set> C<expr>, C<value>. +C<name> 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"; added = (0, 0, 7); + style = RString "val", [String "augpath"], []; + proc_nr = Some 19; + shortdesc = "look up the value of an Augeas path"; + longdesc = "\ +Look up the value associated with C<path>. If C<path> +matches exactly one node, the C<value> is returned." }; + + { defaults with + name = "aug_set"; added = (0, 0, 7); + style = RErr, [String "augpath"; String "val"], []; + proc_nr = Some 20; + tests = [ + InitBasicFS, Always, TestResultString ( + [["mkdir"; "/etc"]; + ["write"; "/etc/hostname"; "test.example.org"]; + ["aug_init"; "/"; "0"]; + ["aug_set"; "/files/etc/hostname/hostname"; "replace.example.com"]; + ["aug_get"; "/files/etc/hostname/hostname"]], "replace.example.com"), [["aug_close"]] + ]; + shortdesc = "set Augeas path to value"; + longdesc = "\ +Set the value associated with C<path> to C<val>. + +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<guestfs_aug_clear> call." }; + + { defaults with + name = "aug_insert"; added = (0, 0, 7); + style = RErr, [String "augpath"; String "label"; Bool "before"], []; + proc_nr = Some 21; + tests = [ + InitBasicFS, Always, TestResultString ( + [["mkdir"; "/etc"]; + ["write"; "/etc/hosts"; ""]; + ["aug_init"; "/"; "0"]; + ["aug_insert"; "/files/etc/hosts"; "1"; "false"]; + ["aug_set"; "/files/etc/hosts/1/ipaddr"; "127.0.0.1"]; + ["aug_set"; "/files/etc/hosts/1/canonical"; "foobar"]; + ["aug_clear"; "/files/etc/hosts/1/canonical"]; + ["aug_set"; "/files/etc/hosts/1/canonical"; "localhost"]; + ["aug_save"]; + ["cat"; "/etc/hosts"]], "\n127.0.0.1\tlocalhost\n"), [["aug_close"]] + ]; + shortdesc = "insert a sibling Augeas node"; + longdesc = "\ +Create a new sibling C<label> for C<path>, inserting it into +the tree before or after C<path> (depending on the boolean +flag C<before>). + +C<path> must match exactly one existing node in the tree, and +C<label> must be a label, ie. not contain F</>, C<*> or end +with a bracketed index C<[N]>." }; + + { defaults with + name = "aug_rm"; added = (0, 0, 7); + style = RInt "nrnodes", [String "augpath"], []; + proc_nr = Some 22; + shortdesc = "remove an Augeas path"; + longdesc = "\ +Remove C<path> and all of its children. + +On success this returns the number of entries which were removed." }; + + { defaults with + name = "aug_mv"; added = (0, 0, 7); + style = RErr, [String "src"; String "dest"], []; + proc_nr = Some 23; + shortdesc = "move Augeas node"; + longdesc = "\ +Move the node C<src> to C<dest>. C<src> must match exactly +one node. C<dest> is overwritten if it exists." }; + + { defaults with + name = "aug_match"; added = (0, 0, 7); + style = RStringList "matches", [String "augpath"], []; + proc_nr = Some 24; + shortdesc = "return Augeas nodes which match augpath"; + longdesc = "\ +Returns a list of paths which match the path expression C<path>. +The returned paths are sufficiently qualified so that they match +exactly one node in the current tree." }; + + { defaults with + name = "aug_save"; added = (0, 0, 7); + style = RErr, [], []; + proc_nr = Some 25; + shortdesc = "write all pending Augeas changes to disk"; + longdesc = "\ +This writes all pending changes to disk. + +The flags which were passed to C<guestfs_aug_init> affect exactly +how files are saved." }; + + { defaults with + name = "aug_load"; added = (0, 0, 7); + style = RErr, [], []; + proc_nr = Some 27; + shortdesc = "load files into the tree"; + longdesc = "\ +Load files into the tree. + +See C<aug_load> in the Augeas documentation for the full gory +details." }; + + { defaults with + name = "aug_ls"; added = (0, 0, 8); + style = RStringList "matches", [String "augpath"], []; + proc_nr = Some 28; + tests = [ + InitBasicFS, Always, TestResult ( + [["mkdir"; "/etc"]; + ["write"; "/etc/hosts"; "127.0.0.1 localhost"]; + ["aug_init"; "/"; "0"]; + ["aug_ls"; "/files/etc/hosts/1"]], + "is_string_list (ret, 2, \"/files/etc/hosts/1/canonical\", \"/files/etc/hosts/1/ipaddr\")"), [["aug_close"]] + ]; + shortdesc = "list Augeas nodes under augpath"; + longdesc = "\ +This is just a shortcut for listing C<guestfs_aug_match> +C<path/*> and sorting the resulting nodes into alphabetical order." }; + + { defaults with + name = "aug_clear"; added = (1, 3, 4); + style = RErr, [String "augpath"], []; + proc_nr = Some 239; + shortdesc = "clear Augeas path"; + longdesc = "\ +Set the value associated with C<path> to C<NULL>. This +is the same as the L<augtool(1)> C<clear> command." }; + + { defaults with + name = "aug_transform"; added = (1, 35, 2); + style = RErr, [String "lens"; String "file"], [ OBool "remove"]; + proc_nr = Some 469; + shortdesc = "add/remove an Augeas lens transformation"; + longdesc = "\ +Add an Augeas transformation for the specified C<lens> so it can +handle C<file>. + +If C<remove> is true (C<false> by default), then the transformation +is removed." }; + +] diff --git a/generator/actions_augeas.mli b/generator/actions_augeas.mli new file mode 100644 index 0000000..23eefe0 --- /dev/null +++ b/generator/actions_augeas.mli @@ -0,0 +1,21 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val daemon_functions : Types.action list diff --git a/generator/actions_core.ml b/generator/actions_core.ml new file mode 100644 index 0000000..124a337 --- /dev/null +++ b/generator/actions_core.ml @@ -0,0 +1,10082 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 Utils +open Types + +(* "Core" APIs. *) + +let non_daemon_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<guestfs_launch> 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 = "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<guestfs_add_drive_opts> +with the optional parameter C<GUESTFS_ADD_DRIVE_OPTS_READONLY> 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<hvparam> string must be a C<-> (dash). + +C<hvvalue> can be NULL." }; + + { 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<READY> state). + +For more information on states, see L<guestfs(3)>." }; + + { 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<CONFIG> state). + +For more information on states, see L<guestfs(3)>." }; + + { 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<LAUNCHING> state). + +For more information on states, see L<guestfs(3)>." }; + + { 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<guestfs(3)>." }; + + { 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<guestfs(3)>." }; + + { 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<libguestfs.so> 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<major>, C<minor> and C<release>) are numbers and +correspond to the usual version triplet. The fourth element +(C<extra>) 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<guestfs(3)/LIBGUESTFS VERSION NUMBERS>. + +I<Note:> 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<guestfs_available> or C<guestfs_feature_available> instead." }; + + { 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<filename>, +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<i386>. + +Win64 binaries and DLLs return C<x86_64>. + +=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 = "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<guestfs_mountable_subvolume> 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<guestfs_mountable_device> to extract +the device of the mountable). + +If the mountable does not represent a btrfs subvolume, then +this function fails and the C<errno> is set to C<EINVAL>." }; + + { 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<mountables> +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<guestfs_mount>. + +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<guestfs_mount> and C<guestfs_umount>, 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<guestfs_inspect_os> 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<filename> to the handle. +F<filename> may be a regular host file or a host device. + +When this function is called before C<guestfs_launch> (the +usual case) then the first time you call this function, +the disk appears in the API as F</dev/sda>, the second time +as F</dev/sdb>, and so on. + +In libguestfs E<ge> 1.20 you can also call this function +after launch (with some restrictions). This is called +\"hotplugging\". When hotplugging, you must specify a +C<label> so that the new disk gets a predictable name. +For more information see L<guestfs(3)/HOTPLUGGING>. + +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 F<filename> exists. + +F<filename> may be the special string C<\"/dev/null\">. +See L<guestfs(3)/NULL DISKS>. + +The optional arguments are: + +=over 4 + +=item C<readonly> + +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<format> + +This forces the image format. If you omit this (or use C<guestfs_add_drive> +or C<guestfs_add_drive_ro>) then the format is automatically detected. +Possible formats include C<raw> and C<qcow2>. + +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<iface> + +This rarely-used option lets you emulate the behaviour of the +deprecated C<guestfs_add_drive_with_if> call (q.v.) + +=item C<name> + +The name the drive had in the original guest, e.g. F</dev/sdb>. +This is used as a hint to the guest inspection process if +it is available. + +=item C<label> + +Give the disk a label. The label should be a unique, short +string using I<only> ASCII characters C<[a-zA-Z]>. +As well as its usual name in the API (such as F</dev/sda>), +the drive will also be named F</dev/disk/guestfs/I<label>>. + +See L<guestfs(3)/DISK LABELS>. + +=item C<protocol> + +The optional protocol argument can be used to select an alternate +source protocol. + +See also: L<guestfs(3)/REMOTE STORAGE>. + +=over 4 + +=item C<protocol = \"file\"> + +F<filename> is interpreted as a local file or device. +This is the default if the optional protocol parameter +is omitted. + +=item C<protocol = \"ftp\"|\"ftps\"|\"http\"|\"https\"|\"tftp\"> + +Connect to a remote FTP, HTTP or TFTP server. +The C<server> parameter must also be supplied - see below. + +See also: L<guestfs(3)/FTP, HTTP AND TFTP> + +=item C<protocol = \"gluster\"> + +Connect to the GlusterFS server. +The C<server> parameter must also be supplied - see below. + +See also: L<guestfs(3)/GLUSTER> + +=item C<protocol = \"iscsi\"> + +Connect to the iSCSI server. +The C<server> parameter must also be supplied - see below. +The C<username> parameter may be supplied. See below. +The C<secret> parameter may be supplied. See below. + +See also: L<guestfs(3)/ISCSI>. + +=item C<protocol = \"nbd\"> + +Connect to the Network Block Device server. +The C<server> parameter must also be supplied - see below. + +See also: L<guestfs(3)/NETWORK BLOCK DEVICE>. + +=item C<protocol = \"rbd\"> + +Connect to the Ceph (librbd/RBD) server. +The C<server> parameter must also be supplied - see below. +The C<username> parameter may be supplied. See below. +The C<secret> parameter may be supplied. See below. + +See also: L<guestfs(3)/CEPH>. + +=item C<protocol = \"sheepdog\"> + +Connect to the Sheepdog server. +The C<server> parameter may also be supplied - see below. + +See also: L<guestfs(3)/SHEEPDOG>. + +=item C<protocol = \"ssh\"> + +Connect to the Secure Shell (ssh) server. + +The C<server> parameter must be supplied. +The C<username> parameter may be supplied. See below. + +See also: L<guestfs(3)/SSH>. + +=back + +=item C<server> + +For protocols which require access to a remote server, this +is a list of server(s). + + Protocol Number of servers required + -------- -------------------------- + file List must be empty or param not used at all + ftp|ftps|http|https|tftp Exactly one + gluster Exactly one + iscsi Exactly one + nbd Exactly one + rbd Zero or more + sheepdog Zero or more + ssh Exactly one + +Each list element is a string specifying a server. The string must be +in one of the following formats: + + hostname + hostname:port + tcp:hostname + tcp:hostname:port + unix:/path/to/socket + +If the port number is omitted, then the standard port number +for the protocol is used (see F</etc/services>). + +=item C<username> + +For the C<ftp>, C<ftps>, C<http>, C<https>, C<iscsi>, C<rbd>, C<ssh> +and C<tftp> protocols, this specifies the remote username. + +If not given, then the local username is used for C<ssh>, and no authentication +is attempted for ceph. But note this sometimes may give unexpected results, for +example if using the libvirt backend and if the libvirt backend is configured to +start the qemu appliance as a special user such as C<qemu.qemu>. If in doubt, +specify the remote username you want. + +=item C<secret> + +For the C<rbd> protocol only, this specifies the 'secret' to use when +connecting to the remote device. It must be base64 encoded. + +If not given, then a secret matching the given username will be looked up in the +default keychain locations, or if no username is given, then no authentication +will be used. + +=item C<cachemode> + +Choose whether or not libguestfs will obey sync operations (safe but slow) +or not (unsafe but fast). The possible values for this string are: + +=over 4 + +=item C<cachemode = \"writeback\"> + +This is the default. + +Write operations in the API do not return until a L<write(2)> +call has completed in the host [but note this does not imply +that anything gets written to disk]. + +Sync operations in the API, including implicit syncs caused by +filesystem journalling, will not return until an L<fdatasync(2)> +call has completed in the host, indicating that data has been +committed to disk. + +=item C<cachemode = \"unsafe\"> + +In this mode, there are no guarantees. Libguestfs may cache +anything and ignore sync requests. This is suitable only +for scratch or temporary disks. + +=back + +=item C<discard> + +Enable or disable discard (a.k.a. trim or unmap) support on this +drive. If enabled, operations such as C<guestfs_fstrim> will be able +to discard / make thin / punch holes in the underlying host file +or device. + +Possible discard settings are: + +=over 4 + +=item C<discard = \"disable\"> + +Disable discard support. This is the default. + +=item C<discard = \"enable\"> + +Enable discard support. Fail if discard is not possible. + +=item C<discard = \"besteffort\"> + +Enable discard support if possible, but don't fail if it is not +supported. + +Since not all backends and not all underlying systems support +discard, this is a good choice if you want to use discard if +possible, but don't mind if it doesn't work. + +=back + +=item C<copyonread> + +The boolean parameter C<copyonread> enables copy-on-read support. +This only affects disk formats which have backing files, and causes +reads to be stored in the overlay layer, speeding up multiple reads +of the same area of disk. + +The default is false. + +=back" }; + + { defaults with + name = "add_domain"; added = (1, 7, 4); + style = RInt "nrdisks", [String "dom"], [OString "libvirturi"; OBool "readonly"; OString "iface"; OBool "live"; OBool "allowuuid"; OString "readonlydisk"; OString "cachemode"; OString "discard"; OBool "copyonread"]; + 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<dom>. It works by connecting to libvirt, requesting +the domain and domain XML from libvirt, parsing it for disks, +and calling C<guestfs_add_drive_opts> 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<readonly> 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<http://libvirt.org/remote.html>) +will fail unless those disks are accessible via the same device path +locally too. + +The optional C<libvirturi> parameter sets the libvirt URI +(see L<http://libvirt.org/uri.html>). 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<live> flag controls whether this call will try +to connect to a running virtual machine C<guestfsd> process if +it sees a suitable E<lt>channelE<gt> element in the libvirt +XML definition. The default (if the flag is omitted) is never +to try. See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more +information. + +If the C<allowuuid> flag is true (default is false) then a UUID +I<may> be passed instead of the domain name. The C<dom> string is +treated as a UUID first and looked up, and if that lookup fails +then we treat C<dom> as a name as usual. + +The optional C<readonlydisk> parameter controls what we do for +disks which are marked E<lt>readonly/E<gt> in the libvirt XML. +Possible values are: + +=over 4 + +=item readonlydisk = \"error\" + +If C<readonly> is false: + +The whole call is aborted with an error if any disk with +the E<lt>readonly/E<gt> flag is found. + +If C<readonly> is true: + +Disks with the E<lt>readonly/E<gt> flag are added read-only. + +=item readonlydisk = \"read\" + +If C<readonly> is false: + +Disks with the E<lt>readonly/E<gt> flag are added read-only. +Other disks are added read/write. + +If C<readonly> is true: + +Disks with the E<lt>readonly/E<gt> flag are added read-only. + +=item readonlydisk = \"write\" (default) + +If C<readonly> is false: + +Disks with the E<lt>readonly/E<gt> flag are added read/write. + +If C<readonly> is true: + +Disks with the E<lt>readonly/E<gt> flag are added read-only. + +=item readonlydisk = \"ignore\" + +If C<readonly> is true or false: + +Disks with the E<lt>readonly/E<gt> flag are skipped. + +=back + +The other optional parameters are passed directly through to +C<guestfs_add_drive_opts>." }; + + { defaults with + name = "add_libvirt_dom"; added = (1, 29, 14); + style = RInt "nrdisks", [Pointer ("virDomainPtr", "dom")], [OBool "readonly"; OString "iface"; OBool "live"; OString "readonlydisk"; OString "cachemode"; OString "discard"; OBool "copyonread"]; + config_only = true; + shortdesc = "add the disk(s) from a libvirt domain"; + longdesc = "\ +This function adds the disk(s) attached to the libvirt domain C<dom>. +It works by requesting the domain XML from libvirt, parsing it for +disks, and calling C<guestfs_add_drive_opts> on each one. + +In the C API we declare C<void *dom>, but really it has type +C<virDomainPtr dom>. This is so we don't need E<lt>libvirt.hE<gt>. + +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<readonly> 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<http://libvirt.org/remote.html>) +will fail unless those disks are accessible via the same device path +locally too. + +The optional C<live> flag controls whether this call will try +to connect to a running virtual machine C<guestfsd> process if +it sees a suitable E<lt>channelE<gt> element in the libvirt +XML definition. The default (if the flag is omitted) is never +to try. See L<guestfs(3)/ATTACHING TO RUNNING DAEMONS> for more +information. + +The optional C<readonlydisk> parameter controls what we do for +disks which are marked E<lt>readonly/E<gt> in the libvirt XML. +See C<guestfs_add_domain> for possible values. + +The other optional parameters are passed directly through to +C<guestfs_add_drive_opts>." }; + + { defaults with + name = "mount_local"; added = (1, 17, 22); + 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<localmountpoint>. +Ordinary reads and writes to files and directories under +C<localmountpoint> are redirected through libguestfs. + +If the optional C<readonly> flag is set to true, then +writes to the filesystem return error C<EROFS>. + +C<options> is a comma-separated list of mount options. +See L<guestmount(1)> for some useful options. + +C<cachetimeout> sets the timeout (in seconds) for cached directory +entries. The default is 60 seconds. See L<guestmount(1)> +for further information. + +If C<debugcalls> is set to true, then additional debugging +information is generated for every FUSE call. + +When C<guestfs_mount_local> returns, the filesystem is ready, +but is not processing requests (access to it will block). You +have to call C<guestfs_mount_local_run> to run the main loop. + +See L<guestfs(3)/MOUNT LOCAL> for full documentation." }; + + { defaults with + name = "mount_local_run"; added = (1, 17, 22); + 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<guestfs_mount_local> +returns successfully. The call will not return until the +filesystem is unmounted. + +B<Note> you must I<not> make concurrent libguestfs calls +on the same handle from another thread. + +You may call this from a different thread than the one which +called C<guestfs_mount_local>, subject to the usual rules +for threads and libguestfs (see +L<guestfs(3)/MULTIPLE HANDLES AND MULTIPLE THREADS>). + +See L<guestfs(3)/MOUNT LOCAL> for full documentation." }; + + { defaults with + name = "umount_local"; added = (1, 17, 22); + style = RErr, [], [OBool "retry"]; + test_excuse = "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<guestfs(3)/MOUNT LOCAL> for full documentation." }; + + { defaults with + name = "max_disks"; added = (1, 19, 7); + style = RInt "disks", [], []; + blocking = false; + 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<guestfs_add_drive_opts> and similar calls). + +This function was added in libguestfs 1.19.7. In previous +versions of libguestfs the limit was 25. + +See L<guestfs(3)/MAXIMUM NUMBER OF DISKS> for additional +information on this topic." }; + + { defaults with + name = "canonical_device_name"; added = (1, 19, 7); + style = RString "canonical", [String "device"], []; + tests = [ + InitNone, Always, TestResultString ( + [["canonical_device_name"; "/dev/hda"]], "/dev/sda"), []; + InitNone, Always, TestResultString ( + [["canonical_device_name"; "/dev/vdaaa"]], "/dev/sdaaa"), []; + InitNone, Always, TestResultString ( + [["canonical_device_name"; "/dev/sdb"]], "/dev/sdb"), []; + InitBasicFSonLVM, IfAvailable "lvm2", TestResultString ( + [["canonical_device_name"; "/dev/mapper/VG-LV"]], "/dev/VG/LV"), []; + InitNone, Always, TestResultString ( + [["canonical_device_name"; "/dev/md0"]], "/dev/md0"), []; + InitNone, Always, TestResultString ( + [["canonical_device_name"; "/dev/md127"]], "/dev/md127"), []; + ]; + 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 F</dev/hdX> + +=item F</dev/vdX> + +These are returned as F</dev/sdX>. Note this works for device +names and partition names. This is approximately the reverse of +the algorithm described in L<guestfs(3)/BLOCK DEVICE NAMING>. + +=item F</dev/mapper/VG-LV> + +=item F</dev/dm-N> + +Converted to F</dev/VG/LV> form using C<guestfs_lvm_canonical_lv_name>. + +=back + +Other strings are returned unmodified." }; + + { defaults with + name = "shutdown"; added = (1, 19, 16); + style = RErr, [], []; + shortdesc = "shutdown the hypervisor"; + longdesc = "\ +This is the opposite of C<guestfs_launch>. 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<not> 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<not> close or free up the handle. You still +need to call C<guestfs_close> afterwards. + +C<guestfs_close> will call this if you don't do it explicitly, +but note that any errors are ignored in that case." }; + + { defaults with + name = "cat"; added = (0, 0, 4); + style = RString "content", [Pathname "path"], []; + tests = [ + InitISOFS, Always, TestResultString ( + [["cat"; "/known-2"]], "abcdef\n"), [] + ]; + shortdesc = "list the contents of a file"; + longdesc = "\ +Return the contents of the file named C<path>. + +Because, in C, this function returns a C<char *>, 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<guestfs_read_file> +or C<guestfs_download> functions." }; + + { defaults with + name = "find"; added = (1, 0, 27); + style = RStringList "names", [Pathname "directory"], []; + tests = [ + InitBasicFS, Always, TestResult ( + [["find"; "/"]], + "is_string_list (ret, 1, \"lost+found\")"), []; + InitBasicFS, Always, TestResult ( + [["touch"; "/a"]; + ["mkdir"; "/b"]; + ["touch"; "/b/c"]; + ["find"; "/"]], + "is_string_list (ret, 4, \"a\", \"b\", \"b/c\", \"lost+found\")"), []; + InitScratchFS, Always, TestResult ( + [["mkdir_p"; "/find/b/c"]; + ["touch"; "/find/b/c/d"]; + ["find"; "/find/b/"]], + "is_string_list (ret, 2, \"c\", \"c/d\")"), [] + ]; + shortdesc = "find all files and directories"; + longdesc = "\ +This command lists out all files and directories, recursively, +starting at F<directory>. It is essentially equivalent to +running the shell command C<find directory -print> but some +post-processing happens on the output, described below. + +This returns a list of strings I<without any prefix>. Thus +if the directory structure was: + + /tmp/a + /tmp/b + /tmp/c/d + +then the returned list from C<guestfs_find> F</tmp> would be +4 elements: + + a + b + c + c/d + +If F<directory> is not a directory, then this command returns +an error. + +The returned list is sorted." }; + + { defaults with + name = "read_file"; added = (1, 0, 63); + style = RBufferOut "content", [Pathname "path"], []; + tests = [ + InitISOFS, Always, TestResult ( + [["read_file"; "/known-4"]], + "compare_buffers (ret, size, \"abc\\ndef\\nghi\", 11) == 0"), [] + ]; + shortdesc = "read a file"; + longdesc = "\ +This calls returns the contents of the file C<path> as a +buffer. + +Unlike C<guestfs_cat>, this function can correctly +handle files that contain embedded ASCII NUL characters." }; + + { defaults with + name = "read_lines"; added = (0, 0, 7); + style = RStringList "lines", [Pathname "path"], []; + tests = [ + InitISOFS, Always, TestResult ( + [["read_lines"; "/known-4"]], + "is_string_list (ret, 3, \"abc\", \"def\", \"ghi\")"), []; + InitISOFS, Always, TestResult ( + [["read_lines"; "/empty"]], + "is_string_list (ret, 0)"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/read_lines1"; "\n"]; + ["read_lines"; "/read_lines1"]], + "is_string_list (ret, 1, \"\")"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/read_lines2"; "\r\n"]; + ["read_lines"; "/read_lines2"]], + "is_string_list (ret, 1, \"\")"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/read_lines3"; "\n\r\n"]; + ["read_lines"; "/read_lines3"]], + "is_string_list (ret, 2, \"\", \"\")"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/read_lines4"; "a"]; + ["read_lines"; "/read_lines4"]], + "is_string_list (ret, 1, \"a\")"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/read_lines5"; "a\nb"]; + ["read_lines"; "/read_lines5"]], + "is_string_list (ret, 2, \"a\", \"b\")"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/read_lines6"; "a\nb\n"]; + ["read_lines"; "/read_lines6"]], + "is_string_list (ret, 2, \"a\", \"b\")"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/read_lines7"; "a\nb\r\n"]; + ["read_lines"; "/read_lines7"]], + "is_string_list (ret, 2, \"a\", \"b\")"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/read_lines8"; "a\nb\r\n\n"]; + ["read_lines"; "/read_lines8"]], + "is_string_list (ret, 3, \"a\", \"b\", \"\")"), []; + ]; + shortdesc = "read file as lines"; + longdesc = "\ +Return the contents of the file named C<path>. + +The file contents are returned as a list of lines. Trailing +C<LF> and C<CRLF> character sequences are I<not> 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<guestfs_read_file> +function and split the buffer into lines yourself." }; + + { defaults with + name = "write"; added = (1, 3, 14); + style = RErr, [Pathname "path"; BufferIn "content"], []; + tests = [ + InitScratchFS, Always, TestResultString ( + [["write"; "/write"; "new file contents"]; + ["cat"; "/write"]], "new file contents"), []; + InitScratchFS, Always, TestResultString ( + [["write"; "/write2"; "\nnew file contents\n"]; + ["cat"; "/write2"]], "\nnew file contents\n"), []; + InitScratchFS, Always, TestResultString ( + [["write"; "/write3"; "\n\n"]; + ["cat"; "/write3"]], "\n\n"), []; + InitScratchFS, Always, TestResultString ( + [["write"; "/write4"; ""]; + ["cat"; "/write4"]], ""), []; + InitScratchFS, Always, TestResultString ( + [["write"; "/write5"; "\n\n\n"]; + ["cat"; "/write5"]], "\n\n\n"), []; + InitScratchFS, Always, TestResultString ( + [["write"; "/write6"; "\n"]; + ["cat"; "/write6"]], "\n"), [] + ]; + shortdesc = "create a new file"; + longdesc = "\ +This call creates a file called C<path>. The content of the +file is the string C<content> (which can contain any 8 bit data). + +See also C<guestfs_write_append>." }; + + { defaults with + name = "write_append"; added = (1, 11, 18); + style = RErr, [Pathname "path"; BufferIn "content"], []; + tests = [ + InitScratchFS, Always, TestResultString ( + [["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<content> to the end of file C<path>. If +C<path> does not exist, then a new file is created. + +See also C<guestfs_write>." }; + + { defaults with + name = "lstatnslist"; added = (1, 27, 53); + style = RStructList ("statbufs", "statns"), [Pathname "path"; FilenameList "names"], []; + shortdesc = "lstat on multiple files"; + longdesc = "\ +This call allows you to perform the C<guestfs_lstatns> operation +on multiple files, where all files are in the directory C<path>. +C<names> 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<names> list. If any name did not exist +or could not be lstat'd, then the C<st_ino> 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<guestfs_lxattrlist> for a similarly efficient call +for getting extended attributes." }; + + { defaults with + name = "lxattrlist"; added = (1, 0, 77); + style = RStructList ("xattrs", "xattr"), [Pathname "path"; FilenameList "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<path>. +C<names> 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<attrname>. C<attrval> in this struct is zero-length +to indicate there was an error doing C<lgetxattr> for this +file, I<or> 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<guestfs_lstatlist> for a similarly efficient call +for getting standard stats." }; + + { defaults with + name = "readlinklist"; added = (1, 0, 77); + style = RStringList "links", [Pathname "path"; FilenameList "names"], []; + shortdesc = "readlink on multiple files"; + longdesc = "\ +This call allows you to do a C<readlink> operation +on multiple files, where all files are in the directory C<path>. +C<names> 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<names> list. Each string is the +value of the symbolic link. + +If the L<readlink(2)> 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 L<readlink(2)> 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"; added = (0, 0, 4); + style = RStringList "listing", [Pathname "directory"], []; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir"; "/ls"]; + ["touch"; "/ls/new"]; + ["touch"; "/ls/newer"]; + ["touch"; "/ls/newest"]; + ["ls"; "/ls"]], + "is_string_list (ret, 3, \"new\", \"newer\", \"newest\")"), [] + ]; + shortdesc = "list the files in a directory"; + longdesc = "\ +List the files in F<directory> (relative to the root directory, +there is no cwd). The '.' and '..' entries are not returned, but +hidden files are shown." }; + + { defaults with + name = "disk_format"; added = (1, 19, 38); + style = RString "format", [String "filename"], []; + tests = [ + InitEmpty, Always, TestResultString ( + [["disk_format"; "../../test-data/blank-disks/blank-disk-1s.raw"]], "raw"), []; + InitEmpty, Always, TestResultString ( + [["disk_format"; "../../test-data/blank-disks/blank-disk-1s.qcow2"]], "qcow2"), []; + InitEmpty, Always, TestResultString ( + [["disk_format"; "../../test-data/blank-disks/blank-disk-1K.raw"]], "raw"), []; + InitEmpty, Always, TestResultString ( + [["disk_format"; "../../test-data/blank-disks/blank-disk-1K.qcow2"]], "qcow2"), []; + InitEmpty, Always, TestResultString ( + [["disk_format"; "../../test-data/blank-disks/blank-disk-1M.raw"]], "raw"), []; + InitEmpty, Always, TestResultString ( + [["disk_format"; "../../test-data/blank-disks/blank-disk-1M.qcow2"]], "qcow2"), []; + InitEmpty, Always, TestResultString ( + [["disk_format"; "../../test-data/blank-disks/blank-disk-with-backing.qcow2"]], "qcow2"), []; + ]; + shortdesc = "detect the disk format of a disk image"; + longdesc = "\ +Detect and return the format of the disk image called F<filename>. +F<filename> can also be a host device, etc. If the format of the +image could not be detected, then C<\"unknown\"> is returned. + +Note that detecting the disk format can be insecure under some +circumstances. See L<guestfs(3)/CVE-2010-3851>. + +See also: L<guestfs(3)/DISK IMAGE FORMATS>" }; + + { defaults with + name = "disk_virtual_size"; added = (1, 19, 39); + style = RInt64 "size", [String "filename"], []; + tests = [ + InitEmpty, Always, TestResult ( + [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1s.raw"]], "ret == 512"), []; + InitEmpty, Always, TestResult ( + [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1s.qcow2"]], "ret == 512"), []; + InitEmpty, Always, TestResult ( + [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1K.raw"]], "ret == 1024"), []; + InitEmpty, Always, TestResult ( + [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1K.qcow2"]], "ret == 1024"), []; + InitEmpty, Always, TestResult ( + [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1M.raw"]], "ret == 1024*1024"), []; + InitEmpty, Always, TestResult ( + [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-1M.qcow2"]], "ret == 1024*1024"), []; + InitEmpty, Always, TestResult ( + [["disk_virtual_size"; "../../test-data/blank-disks/blank-disk-with-backing.qcow2"]], "ret == 1024*1024"), []; + ]; + shortdesc = "return virtual size of a disk"; + longdesc = "\ +Detect and return the virtual size in bytes of the disk image +called F<filename>. + +Note that detecting disk features can be insecure under some +circumstances. See L<guestfs(3)/CVE-2010-3851>." }; + + { defaults with + name = "disk_has_backing_file"; added = (1, 19, 39); + style = RBool "backingfile", [String "filename"], []; + tests = [ + InitEmpty, Always, TestResultFalse ( + [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1s.raw"]]), []; + InitEmpty, Always, TestResultFalse ( + [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1s.qcow2"]]), []; + InitEmpty, Always, TestResultFalse ( + [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1K.raw"]]), []; + InitEmpty, Always, TestResultFalse ( + [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1K.qcow2"]]), []; + InitEmpty, Always, TestResultFalse ( + [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1M.raw"]]), []; + InitEmpty, Always, TestResultFalse ( + [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-1M.qcow2"]]), []; + InitEmpty, Always, TestResultTrue ( + [["disk_has_backing_file"; "../../test-data/blank-disks/blank-disk-with-backing.qcow2"]]), []; + ]; + shortdesc = "return whether disk has a backing file"; + longdesc = "\ +Detect and return whether the disk image F<filename> has a +backing file. + +Note that detecting disk features can be insecure under some +circumstances. See L<guestfs(3)/CVE-2010-3851>." }; + + { defaults with + name = "remove_drive"; added = (1, 19, 49); + style = RErr, [String "label"], []; + blocking = false; + shortdesc = "remove a disk image"; + longdesc = "\ +This function is conceptually the opposite of C<guestfs_add_drive_opts>. +It removes the drive that was previously added with label C<label>. + +Note that in order to remove drives, you have to add them with +labels (see the optional C<label> argument to C<guestfs_add_drive_opts>). +If you didn't use a label, then they cannot be removed. + +You can call this function before or after launching the handle. +If called after launch, if the backend supports it, we try to hot +unplug the drive: see L<guestfs(3)/HOTPLUGGING>. The disk B<must not> +be in use (eg. mounted) when you do this. We try to detect if the +disk is in use and stop you from doing this." }; + + { defaults with + name = "set_libvirt_supported_credentials"; added = (1, 19, 52); + style = RErr, [StringList "creds"], []; + blocking = false; + shortdesc = "set libvirt credentials supported by calling program"; + longdesc = "\ +Call this function before setting an event handler for +C<GUESTFS_EVENT_LIBVIRT_AUTH>, to supply the list of credential types +that the program knows how to process. + +The C<creds> list must be a non-empty list of strings. +Possible strings are: + +=over 4 + +=item C<username> + +=item C<authname> + +=item C<language> + +=item C<cnonce> + +=item C<passphrase> + +=item C<echoprompt> + +=item C<noechoprompt> + +=item C<realm> + +=item C<external> + +=back + +See libvirt documentation for the meaning of these credential types. + +See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; + + { defaults with + name = "get_libvirt_requested_credentials"; added = (1, 19, 52); + style = RStringList "creds", [], []; + blocking = false; + shortdesc = "get list of credentials requested by libvirt"; + longdesc = "\ +This should only be called during the event callback +for events of type C<GUESTFS_EVENT_LIBVIRT_AUTH>. + +Return the list of credentials requested by libvirt. Possible +values are a subset of the strings provided when you called +C<guestfs_set_libvirt_supported_credentials>. + +See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; + + { defaults with + name = "get_libvirt_requested_credential_prompt"; added = (1, 19, 52); + style = RString "prompt", [Int "index"], []; + blocking = false; + shortdesc = "prompt of i'th requested credential"; + longdesc = "\ +Get the prompt (provided by libvirt) for the C<index>'th +requested credential. If libvirt did not provide a prompt, +this returns the empty string C<\"\">. + +See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; + + { defaults with + name = "get_libvirt_requested_credential_challenge"; added = (1, 19, 52); + style = RString "challenge", [Int "index"], []; + blocking = false; + shortdesc = "challenge of i'th requested credential"; + longdesc = "\ +Get the challenge (provided by libvirt) for the C<index>'th +requested credential. If libvirt did not provide a challenge, +this returns the empty string C<\"\">. + +See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; + + { defaults with + name = "get_libvirt_requested_credential_defresult"; added = (1, 19, 52); + style = RString "defresult", [Int "index"], []; + blocking = false; + shortdesc = "default result of i'th requested credential"; + longdesc = "\ +Get the default result (provided by libvirt) for the C<index>'th +requested credential. If libvirt did not provide a default result, +this returns the empty string C<\"\">. + +See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; + + { defaults with + name = "set_libvirt_requested_credential"; added = (1, 19, 52); + style = RErr, [Int "index"; BufferIn "cred"], []; + blocking = false; + shortdesc = "pass requested credential back to libvirt"; + longdesc = "\ +After requesting the C<index>'th credential from the user, +call this function to pass the answer back to libvirt. + +See L<guestfs(3)/LIBVIRT AUTHENTICATION> for documentation and example code." }; + + { defaults with + name = "parse_environment"; added = (1, 19, 53); + style = RErr, [], []; + blocking = false; + shortdesc = "parse the environment and set handle flags accordingly"; + longdesc = "\ +Parse the program's environment and set flags in the handle +accordingly. For example if C<LIBGUESTFS_DEBUG=1> then the +'verbose' flag is set in the handle. + +I<Most programs do not need to call this>. It is done implicitly +when you call C<guestfs_create>. + +See L<guestfs(3)/ENVIRONMENT VARIABLES> for a list of environment +variables that can affect libguestfs handles. See also +L<guestfs(3)/guestfs_create_flags>, and +C<guestfs_parse_environment_list>." }; + + { defaults with + name = "parse_environment_list"; added = (1, 19, 53); + style = RErr, [StringList "environment"], []; + blocking = false; + shortdesc = "parse the environment and set handle flags accordingly"; + longdesc = "\ +Parse the list of strings in the argument C<environment> +and set flags in the handle accordingly. +For example if C<LIBGUESTFS_DEBUG=1> is a string in the list, +then the 'verbose' flag is set in the handle. + +This is the same as C<guestfs_parse_environment> except that +it parses an explicit list of strings instead of the program's +environment." }; + + { defaults with + name = "user_cancel"; added = (1, 11, 18); + style = RErr, [], []; + blocking = false; wrapper = false; + shortdesc = "cancel the current upload or download operation"; + longdesc = "\ +This function cancels the current upload or download operation. + +Unlike most other libguestfs calls, this function is signal safe and +thread safe. You can call it from a signal handler or from another +thread, without needing to do any locking. + +The transfer that was in progress (if there is one) will stop shortly +afterwards, and will return an error. The errno (see +L</guestfs_last_errno>) is set to C<EINTR>, so you can test for this +to find out if the operation was cancelled or failed because of +another error. + +No cleanup is performed: for example, if a file was being uploaded +then after cancellation there may be a partially uploaded file. It is +the caller's responsibility to clean up if necessary. + +There are two common places that you might call C<guestfs_user_cancel>: + +In an interactive text-based program, you might call it from a +C<SIGINT> signal handler so that pressing C<^C> cancels the current +operation. (You also need to call L</guestfs_set_pgroup> so that +child processes don't receive the C<^C> signal). + +In a graphical program, when the main thread is displaying a progress +bar with a cancel button, wire up the cancel button to call this +function." }; + + { defaults with + name = "add_drive_scratch"; added = (1, 23, 10); + style = RErr, [Int64 "size"], [OString "name"; OString "label"]; + blocking = false; + fish_alias = ["scratch"]; + shortdesc = "add a temporary scratch drive"; + longdesc = "\ +This command adds a temporary scratch drive to the handle. The +C<size> parameter is the virtual size (in bytes). The scratch +drive is blank initially (all reads return zeroes until you start +writing to it). The drive is deleted when the handle is closed. + +The optional arguments C<name> and C<label> are passed through to +C<guestfs_add_drive>." }; + + { defaults with + name = "journal_get"; added = (1, 23, 11); + style = RStructList ("fields", "xattr"), [], []; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "read the current journal entry"; + longdesc = "\ +Read the current journal entry. This returns all the fields +in the journal as a set of C<(attrname, attrval)> pairs. The +C<attrname> is the field name (a string). + +The C<attrval> is the field value (a binary blob, often but +not always a string). Please note that C<attrval> is a byte +array, I<not> a \\0-terminated C string. + +The length of data may be truncated to the data threshold +(see: C<guestfs_journal_set_data_threshold>, +C<guestfs_journal_get_data_threshold>). + +If you set the data threshold to unlimited (C<0>) then this call +can read a journal entry of any size, ie. it is not limited by +the libguestfs protocol." }; + + { defaults with + name = "disk_create"; added = (1, 25, 31); + style = RErr, [String "filename"; String "format"; Int64 "size"], [OString "backingfile"; OString "backingformat"; OString "preallocation"; OString "compat"; OInt "clustersize"]; + test_excuse = "tests in tests/create subdirectory"; + shortdesc = "create a blank disk image"; + longdesc = "\ +Create a blank disk image called F<filename> (a host file) +with format C<format> (usually C<raw> or C<qcow2>). +The size is C<size> bytes. + +If used with the optional C<backingfile> parameter, then a snapshot +is created on top of the backing file. In this case, C<size> must +be passed as C<-1>. The size of the snapshot is the same as the +size of the backing file, which is discovered automatically. You +are encouraged to also pass C<backingformat> to describe the format +of C<backingfile>. + +If F<filename> refers to a block device, then the device is +formatted. The C<size> is ignored since block devices have an +intrinsic size. + +The other optional parameters are: + +=over 4 + +=item C<preallocation> + +If format is C<raw>, then this can be either C<off> (or C<sparse>) +or C<full> to create a sparse or fully allocated file respectively. +The default is C<off>. + +If format is C<qcow2>, then this can be C<off> (or C<sparse>), +C<metadata> or C<full>. Preallocating metadata can be faster +when doing lots of writes, but uses more space. +The default is C<off>. + +=item C<compat> + +C<qcow2> only: +Pass the string C<1.1> to use the advanced qcow2 format supported +by qemu E<ge> 1.1. + +=item C<clustersize> + +C<qcow2> only: +Change the qcow2 cluster size. The default is 65536 (bytes) and +this setting may be any power of two between 512 and 2097152. + +=back + +Note that this call does not add the new disk to the handle. You +may need to call C<guestfs_add_drive_opts> separately." }; + + { defaults with + name = "stat"; added = (1, 9, 2); + style = RStruct ("statbuf", "stat"), [Pathname "path"], []; + deprecated_by = Some "statns"; + tests = [ + InitISOFS, Always, TestResult ( + [["stat"; "/empty"]], "ret->size == 0"), [] + ]; + shortdesc = "get file information"; + longdesc = "\ +Returns file information for the given C<path>. + +This is the same as the L<stat(2)> system call." }; + + { defaults with + name = "lstat"; added = (1, 9, 2); + style = RStruct ("statbuf", "stat"), [Pathname "path"], []; + deprecated_by = Some "lstatns"; + tests = [ + InitISOFS, Always, TestResult ( + [["lstat"; "/empty"]], "ret->size == 0"), [] + ]; + shortdesc = "get file information for a symbolic link"; + longdesc = "\ +Returns file information for the given C<path>. + +This is the same as C<guestfs_stat> except that if C<path> +is a symbolic link, then the link is stat-ed, not the file it +refers to. + +This is the same as the L<lstat(2)> system call." }; + + { defaults with + name = "c_pointer"; added = (1, 29, 17); + style = RInt64 "ptr", [], []; + fish_output = Some FishOutputHexadecimal; + tests = [ + InitNone, Always, TestRun ( + [["c_pointer"]]), [] + ]; + shortdesc = "return the C pointer to the guestfs_h handle"; + longdesc = "\ +In non-C language bindings, this allows you to retrieve the underlying +C pointer to the handle (ie. C<guestfs_h *>). The purpose of this is +to allow other libraries to interwork with libguestfs." }; + + { defaults with + name = "copy_in"; added = (1, 29, 24); + style = RErr, [String "localpath"; Pathname "remotedir"], []; + visibility = VPublicNoFish; + shortdesc = "copy local files or directories into an image"; + longdesc = "\ +C<guestfs_copy_in> copies local files or directories recursively into +the disk image, placing them in the directory called C<remotedir> +(which must exist). + +Wildcards cannot be used." }; + + { defaults with + name = "copy_out"; added = (1, 29, 24); + style = RErr, [Pathname "remotepath"; String "localdir"], []; + visibility = VPublicNoFish; + shortdesc = "copy remote files or directories out of an image"; + longdesc = "\ +C<guestfs_copy_out> copies remote files or directories recursively +out of the disk image, placing them on the host disk in a local +directory called C<localdir> (which must exist). + +To download to the current directory, use C<.> as in: + + C<guestfs_copy_out> /home . + +Wildcards cannot be used." }; + + { defaults with + name = "available"; added = (1, 0, 80); + style = RErr, [StringList "groups"], []; + tests = [ + InitNone, Always, TestRun [["available"; ""]], [] + ]; + shortdesc = "test availability of some parts of the API"; + longdesc = "\ +This command is used to check the availability of some +groups of functionality in the appliance, which not all builds of +the libguestfs appliance will be able to provide. + +The libguestfs groups, and the functions that those +groups correspond to, are listed in L<guestfs(3)/AVAILABILITY>. +You can also fetch this list at runtime by calling +C<guestfs_available_all_groups>. + +The argument C<groups> is a list of group names, eg: +C<[\"inotify\", \"augeas\"]> would check for the availability of +the Linux inotify functions and Augeas (configuration file +editing) functions. + +The command returns no error if I<all> requested groups are available. + +It fails with an error if one or more of the requested +groups is unavailable in the appliance. + +If an unknown group name is included in the +list of groups then an error is always returned. + +I<Notes:> + +=over 4 + +=item * + +C<guestfs_feature_available> is the same as this call, but +with a slightly simpler to use API: that call returns a boolean +true/false instead of throwing an error. + +=item * + +You must call C<guestfs_launch> before calling this function. + +The reason is because we don't know what groups are +supported by the appliance/daemon until it is running and can +be queried. + +=item * + +If a group of functions is available, this does not necessarily +mean that they will work. You still have to check for errors +when calling individual API functions even if they are +available. + +=item * + +It is usually the job of distro packagers to build +complete functionality into the libguestfs appliance. +Upstream libguestfs, if built from source with all +requirements satisfied, will support everything. + +=item * + +This call was added in version C<1.0.80>. In previous +versions of libguestfs all you could do would be to speculatively +execute a command to find out if the daemon implemented it. +See also C<guestfs_version>. + +=back + +See also C<guestfs_filesystem_available>." }; + + { defaults with + name = "feature_available"; added = (1, 21, 26); + style = RBool "isavailable", [StringList "groups"], []; + tests = [ + InitNone, Always, TestResultTrue [["feature_available"; ""]], [] + ]; + shortdesc = "test availability of some parts of the API"; + longdesc = "\ +This is the same as C<guestfs_available>, but unlike that +call it returns a simple true/false boolean result, instead +of throwing an exception if a feature is not found. For +other documentation see C<guestfs_available>." }; + +] + +let daemon_functions = [ + { defaults with + name = "mount"; added = (0, 0, 3); + style = RErr, [Mountable "mountable"; String "mountpoint"], []; + proc_nr = Some 1; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "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 F</dev/sda>, F</dev/sdb> and so on, as they were added to +the guest. If those block devices contain partitions, they will have +the usual names (eg. F</dev/sda1>). Also LVM F</dev/VG/LV>-style +names can be used, or 'mountable' strings returned by +C<guestfs_list_filesystems> or C<guestfs_inspect_get_mountpoints>. + +The rules are the same as for L<mount(2)>: A filesystem must +first be mounted on F</> 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<sync> and C<noatime>. The C<sync> option greatly slowed +writes and caused many problems for users. If your program +might need to work with older versions of libguestfs, use +C<guestfs_mount_options> instead (using an empty string for the +first parameter if you don't want any options)." }; + + { defaults with + name = "sync"; added = (0, 0, 3); + 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"; added = (0, 0, 3); + style = RErr, [Pathname "path"], []; + proc_nr = Some 3; + tests = [ + InitScratchFS, Always, TestResultTrue ( + [["touch"; "/touch"]; + ["exists"; "/touch"]]), [] + ]; + shortdesc = "update file timestamps or create a new file"; + longdesc = "\ +Touch acts like the L<touch(1)> 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"; added = (0, 0, 4); + style = RString "listing", [Pathname "directory"], []; + proc_nr = Some 5; + test_excuse = "tricky to test because it depends on the exact format of the 'ls -l' command, which changed between Fedora 10 and Fedora 11"; + shortdesc = "list the files in a directory (long format)"; + longdesc = "\ +List the files in F<directory> (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<not> intended that you try to parse the output string." }; + + { defaults with + name = "list_devices"; added = (0, 0, 4); + style = RStringList "devices", [], []; + proc_nr = Some 7; + tests = [ + InitEmpty, Always, TestResult ( + [["list_devices"]], + "is_device_list (ret, 4, \"/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. F</dev/sda>. + +See also C<guestfs_list_filesystems>." }; + + { defaults with + name = "list_partitions"; added = (0, 0, 4); + style = RStringList "partitions", [], []; + proc_nr = Some 8; + tests = [ + InitBasicFS, Always, TestResult ( + [["list_partitions"]], + "is_device_list (ret, 2, \"/dev/sda1\", \"/dev/sdb1\")"), []; + InitEmpty, Always, TestResult ( + [["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"]], + "is_device_list (ret, 4, \"/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. F</dev/sda1> + +This does not return logical volumes. For that you will need to +call C<guestfs_lvs>. + +See also C<guestfs_list_filesystems>." }; + + { defaults with + name = "pvs"; added = (0, 0, 4); + style = RStringList "physvols", [], []; + proc_nr = Some 9; + optional = Some "lvm2"; + tests = [ + InitBasicFSonLVM, Always, TestResult ( + [["pvs"]], "is_device_list (ret, 1, \"/dev/sda1\")"), []; + InitEmpty, Always, TestResult ( + [["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"]], + "is_device_list (ret, 3, \"/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<pvs(8)> command. + +This returns a list of just the device names that contain +PVs (eg. F</dev/sda2>). + +See also C<guestfs_pvs_full>." }; + + { defaults with + name = "vgs"; added = (0, 0, 4); + style = RStringList "volgroups", [], []; + proc_nr = Some 10; + optional = Some "lvm2"; + tests = [ + InitBasicFSonLVM, Always, TestResult ( + [["vgs"]], "is_string_list (ret, 1, \"VG\")"), []; + InitEmpty, Always, TestResult ( + [["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"]], + "is_string_list (ret, 2, \"VG1\", \"VG2\")"), [] + ]; + shortdesc = "list the LVM volume groups (VGs)"; + longdesc = "\ +List all the volumes groups detected. This is the equivalent +of the L<vgs(8)> command. + +This returns a list of just the volume group names that were +detected (eg. C<VolGroup00>). + +See also C<guestfs_vgs_full>." }; + + { defaults with + name = "lvs"; added = (0, 0, 4); + style = RStringList "logvols", [], []; + proc_nr = Some 11; + optional = Some "lvm2"; + tests = [ + InitBasicFSonLVM, Always, TestResult ( + [["lvs"]], + "is_string_list (ret, 1, \"/dev/VG/LV\")"), []; + InitEmpty, Always, TestResult ( + [["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"]], + "is_string_list (ret, 3, \"/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<lvs(8)> command. + +This returns a list of the logical volume device names +(eg. F</dev/VolGroup00/LogVol00>). + +See also C<guestfs_lvs_full>, C<guestfs_list_filesystems>." }; + + { defaults with + name = "pvs_full"; added = (0, 0, 4); + 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<pvs(8)> command. The \"full\" version includes all fields." }; + + { defaults with + name = "vgs_full"; added = (0, 0, 4); + 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<vgs(8)> command. The \"full\" version includes all fields." }; + + { defaults with + name = "lvs_full"; added = (0, 0, 4); + 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<lvs(8)> command. The \"full\" version includes all fields." }; + + { defaults with + name = "rm"; added = (0, 0, 8); + style = RErr, [Pathname "path"], []; + proc_nr = Some 29; + tests = [ + InitScratchFS, Always, TestRun + [["mkdir"; "/rm"]; + ["touch"; "/rm/new"]; + ["rm"; "/rm/new"]], []; + InitScratchFS, Always, TestLastFail + [["rm"; "/nosuchfile"]], []; + InitScratchFS, Always, TestLastFail + [["mkdir"; "/rm2"]; + ["rm"; "/rm2"]], [] + ]; + shortdesc = "remove a file"; + longdesc = "\ +Remove the single file C<path>." }; + + { defaults with + name = "rmdir"; added = (0, 0, 8); + style = RErr, [Pathname "path"], []; + proc_nr = Some 30; + tests = [ + InitScratchFS, Always, TestRun + [["mkdir"; "/rmdir"]; + ["rmdir"; "/rmdir"]], []; + InitScratchFS, Always, TestLastFail + [["rmdir"; "/rmdir2"]], []; + InitScratchFS, Always, TestLastFail + [["mkdir"; "/rmdir3"]; + ["touch"; "/rmdir3/new"]; + ["rmdir"; "/rmdir3/new"]], [] + ]; + shortdesc = "remove a directory"; + longdesc = "\ +Remove the single directory C<path>." }; + + { defaults with + name = "rm_rf"; added = (0, 0, 8); + style = RErr, [Pathname "path"], []; + proc_nr = Some 31; + tests = [ + InitScratchFS, Always, TestResultFalse + [["mkdir"; "/rm_rf"]; + ["mkdir"; "/rm_rf/foo"]; + ["touch"; "/rm_rf/foo/bar"]; + ["rm_rf"; "/rm_rf"]; + ["exists"; "/rm_rf"]], [] + ]; + shortdesc = "remove a file or directory recursively"; + longdesc = "\ +Remove the file or directory C<path>, recursively removing the +contents if its a directory. This is like the C<rm -rf> shell +command." }; + + { defaults with + name = "mkdir"; added = (0, 0, 8); + style = RErr, [Pathname "path"], []; + proc_nr = Some 32; + tests = [ + InitScratchFS, Always, TestResultTrue + [["mkdir"; "/mkdir"]; + ["is_dir"; "/mkdir"; ""]], []; + InitScratchFS, Always, TestLastFail + [["mkdir"; "/mkdir2/foo/bar"]], [] + ]; + shortdesc = "create a directory"; + longdesc = "\ +Create a directory named C<path>." }; + + { defaults with + name = "mkdir_p"; added = (0, 0, 8); + style = RErr, [Pathname "path"], []; + proc_nr = Some 33; + tests = [ + InitScratchFS, Always, TestResultTrue + [["mkdir_p"; "/mkdir_p/foo/bar"]; + ["is_dir"; "/mkdir_p/foo/bar"; ""]], []; + InitScratchFS, Always, TestResultTrue + [["mkdir_p"; "/mkdir_p2/foo/bar"]; + ["is_dir"; "/mkdir_p2/foo"; ""]], []; + InitScratchFS, Always, TestResultTrue + [["mkdir_p"; "/mkdir_p3/foo/bar"]; + ["is_dir"; "/mkdir_p3"; ""]], []; + (* Regression tests for RHBZ#503133: *) + InitScratchFS, Always, TestRun + [["mkdir"; "/mkdir_p4"]; + ["mkdir_p"; "/mkdir_p4"]], []; + InitScratchFS, Always, TestLastFail + [["touch"; "/mkdir_p5"]; + ["mkdir_p"; "/mkdir_p5"]], [] + ]; + shortdesc = "create a directory and parents"; + longdesc = "\ +Create a directory named C<path>, creating any parent directories +as necessary. This is like the C<mkdir -p> shell command." }; + + { defaults with + name = "chmod"; added = (0, 0, 8); + style = RErr, [Int "mode"; Pathname "path"], []; + proc_nr = Some 34; + shortdesc = "change file mode"; + longdesc = "\ +Change the mode (permissions) of C<path> to C<mode>. Only +numeric modes are supported. + +I<Note>: When using this command from guestfish, C<mode> +by default would be decimal, unless you prefix it with +C<0> to get octal, ie. use C<0700> not C<700>. + +The mode actually set is affected by the umask." }; + + { defaults with + name = "chown"; added = (0, 0, 8); + style = RErr, [Int "owner"; Int "group"; Pathname "path"], []; + proc_nr = Some 35; + shortdesc = "change file owner and group"; + longdesc = "\ +Change the file owner to C<owner> and group to C<group>. + +Only numeric uid and gid are supported. If you want to use +names, you will need to locate and parse the password file +yourself (Augeas support makes this relatively easy)." }; + + { defaults with + name = "exists"; added = (0, 0, 8); + style = RBool "existsflag", [Pathname "path"], []; + proc_nr = Some 36; + tests = [ + InitISOFS, Always, TestResultTrue ( + [["exists"; "/empty"]]), []; + InitISOFS, Always, TestResultTrue ( + [["exists"; "/directory"]]), [] + ]; + shortdesc = "test if file or directory exists"; + longdesc = "\ +This returns C<true> if and only if there is a file, directory +(or anything) with the given C<path> name. + +See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>." }; + + { defaults with + name = "is_file"; added = (0, 0, 8); + style = RBool "fileflag", [Pathname "path"], [OBool "followsymlinks"]; + proc_nr = Some 37; + once_had_no_optargs = true; + tests = [ + InitISOFS, Always, TestResultTrue ( + [["is_file"; "/known-1"; ""]]), []; + InitISOFS, Always, TestResultFalse ( + [["is_file"; "/directory"; ""]]), []; + InitISOFS, Always, TestResultTrue ( + [["is_file"; "/abssymlink"; "true"]]), [] + ]; + shortdesc = "test if a regular file"; + longdesc = "\ +This returns C<true> if and only if there is a regular file +with the given C<path> name. Note that it returns false for +other objects like directories. + +If the optional flag C<followsymlinks> is true, then a symlink +(or chain of symlinks) that ends with a file also causes the +function to return true. + +See also C<guestfs_stat>." }; + + { defaults with + name = "is_dir"; added = (0, 0, 8); + style = RBool "dirflag", [Pathname "path"], [OBool "followsymlinks"]; + proc_nr = Some 38; + once_had_no_optargs = true; + tests = [ + InitISOFS, Always, TestResultFalse ( + [["is_dir"; "/known-3"; ""]]), []; + InitISOFS, Always, TestResultTrue ( + [["is_dir"; "/directory"; ""]]), [] + ]; + shortdesc = "test if a directory"; + longdesc = "\ +This returns C<true> if and only if there is a directory +with the given C<path> name. Note that it returns false for +other objects like files. + +If the optional flag C<followsymlinks> is true, then a symlink +(or chain of symlinks) that ends with a directory also causes the +function to return true. + +See also C<guestfs_stat>." }; + + { defaults with + name = "pvcreate"; added = (0, 0, 8); + style = RErr, [Device "device"], []; + proc_nr = Some 39; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestResult ( + [["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"]], + "is_device_list (ret, 3, \"/dev/sda1\", \"/dev/sda2\", \"/dev/sda3\")"), [] + ]; + shortdesc = "create an LVM physical volume"; + longdesc = "\ +This creates an LVM physical volume on the named C<device>, +where C<device> should usually be a partition name such +as F</dev/sda1>." }; + + { defaults with + name = "vgcreate"; added = (0, 0, 8); + style = RErr, [String "volgroup"; DeviceList "physvols"], []; + proc_nr = Some 40; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestResult ( + [["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"]], + "is_string_list (ret, 2, \"VG1\", \"VG2\")"), []; + InitEmpty, Always, TestLastFail ( + [["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"; "/foo/bar /dev/sda2"]]), []; + ]; + shortdesc = "create an LVM volume group"; + longdesc = "\ +This creates an LVM volume group called C<volgroup> +from the non-empty list of physical volumes C<physvols>." }; + + { defaults with + name = "lvcreate"; added = (0, 0, 8); + style = RErr, [String "logvol"; String "volgroup"; Int "mbytes"], []; + proc_nr = Some 41; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestResult ( + [["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"]; + ["lvcreate"; "LV4"; "VG2"; "50"]; + ["lvcreate"; "LV5"; "VG2"; "50"]; + ["lvs"]], + "is_string_list (ret, 5, \"/dev/VG1/LV1\", \"/dev/VG1/LV2\", \"/dev/VG2/LV3\", \"/dev/VG2/LV4\", \"/dev/VG2/LV5\")"), [] + ]; + shortdesc = "create an LVM logical volume"; + longdesc = "\ +This creates an LVM logical volume called C<logvol> +on the volume group C<volgroup>, with C<size> megabytes." }; + + { defaults with + name = "write_file"; added = (0, 0, 8); + style = RErr, [Pathname "path"; String "content"; Int "size"], []; + proc_nr = Some 44; + protocol_limit_warning = true; deprecated_by = Some "write"; + (* Regression test for RHBZ#597135. *) + tests = [ + InitScratchFS, Always, TestLastFail + [["write_file"; "/write_file"; "abc"; "10000"]], [] + ]; + shortdesc = "create a file"; + longdesc = "\ +This call creates a file called C<path>. The contents of the +file is the string C<content> (which can contain any 8 bit data), +with length C<size>. + +As a special case, if C<size> is C<0> +then the length is calculated using C<strlen> (so in this case +the content cannot contain embedded ASCII NULs). + +I<NB.> Owing to a bug, writing content containing ASCII NUL +characters does I<not> work, even if the length is specified." }; + + { defaults with + name = "umount"; added = (0, 0, 8); + style = RErr, [Dev_or_Path "pathordevice"], [OBool "force"; OBool "lazyunmount"]; + proc_nr = Some 45; + fish_alias = ["unmount"]; + once_had_no_optargs = true; + tests = [ + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["mounts"]], "is_device_list (ret, 1, \"/dev/sda1\")"), []; + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["umount"; "/"; "false"; "false"]; + ["mounts"]], "is_string_list (ret, 0)"), [] + ]; + shortdesc = "unmount a filesystem"; + longdesc = "\ +This unmounts the given filesystem. The filesystem may be +specified either by its mountpoint (path) or the device which +contains the filesystem." }; + + { defaults with + name = "mounts"; added = (0, 0, 8); + style = RStringList "devices", [], []; + proc_nr = Some 46; + tests = [ + InitScratchFS, Always, TestResult ( + [["mounts"]], "is_device_list (ret, 1, \"/dev/sdb1\")"), [] + ]; + shortdesc = "show mounted filesystems"; + longdesc = "\ +This returns the list of currently mounted filesystems. It returns +the list of devices (eg. F</dev/sda1>, F</dev/VG/LV>). + +Some internal mounts are not shown. + +See also: C<guestfs_mountpoints>" }; + + { defaults with + name = "umount_all"; added = (0, 0, 8); + style = RErr, [], []; + proc_nr = Some 47; + fish_alias = ["unmount-all"]; + tests = [ + InitScratchFS, Always, TestResult ( + [["umount_all"]; + ["mounts"]], "is_string_list (ret, 0)"), []; + (* check that umount_all can unmount nested mounts correctly: *) + InitEmpty, Always, TestResult ( + [["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"]; + ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mkfs"; "ext2"; "/dev/sda2"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mkfs"; "ext2"; "/dev/sda3"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["mkdir"; "/mp1"]; + ["mount"; "/dev/sda2"; "/mp1"]; + ["mkdir"; "/mp1/mp2"]; + ["mount"; "/dev/sda3"; "/mp1/mp2"]; + ["mkdir"; "/mp1/mp2/mp3"]; + ["umount_all"]; + ["mounts"]], "is_string_list (ret, 0)"), [] + ]; + shortdesc = "unmount all filesystems"; + longdesc = "\ +This unmounts all mounted filesystems. + +Some internal mounts are not unmounted by this call." }; + + { defaults with + name = "lvm_remove_all"; added = (0, 0, 8); + style = RErr, [], []; + proc_nr = Some 48; + optional = Some "lvm2"; + shortdesc = "remove all LVM LVs, VGs and PVs"; + longdesc = "\ +This command removes all LVM logical volumes, volume groups +and physical volumes." }; + + { defaults with + name = "file"; added = (1, 9, 1); + style = RString "description", [Dev_or_Path "path"], []; + proc_nr = Some 49; + tests = [ + InitISOFS, Always, TestResultString ( + [["file"; "/empty"]], "empty"), []; + InitISOFS, Always, TestResultString ( + [["file"; "/known-1"]], "ASCII text"), []; + InitISOFS, Always, TestLastFail ( + [["file"; "/notexists"]]), []; + InitISOFS, Always, TestResultString ( + [["file"; "/abssymlink"]], "symbolic link"), []; + InitISOFS, Always, TestResultString ( + [["file"; "/directory"]], "directory"), [] + ]; + shortdesc = "determine file type"; + longdesc = "\ +This call uses the standard L<file(1)> command to determine +the type or contents of the file. + +This call will also transparently look inside various types +of compressed file. + +The exact command which runs is C<file -zb path>. Note in +particular that the filename is not prepended to the output +(the I<-b> option). + +The output depends on the output of the underlying L<file(1)> +command and it can change in future in ways beyond our control. +In other words, the output is not guaranteed by the ABI. + +See also: L<file(1)>, C<guestfs_vfs_type>, C<guestfs_lstat>, +C<guestfs_is_file>, C<guestfs_is_blockdev> (etc), C<guestfs_is_zero>." }; + + { defaults with + name = "command"; added = (1, 9, 1); + style = RString "output", [StringList "arguments"], []; + proc_nr = Some 50; + protocol_limit_warning = true; + tests = [ + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command"]; + ["upload"; "test-command"; "/command/test-command"]; + ["chmod"; "0o755"; "/command/test-command"]; + ["command"; "/command/test-command 1"]], "Result1"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command2"]; + ["upload"; "test-command"; "/command2/test-command"]; + ["chmod"; "0o755"; "/command2/test-command"]; + ["command"; "/command2/test-command 2"]], "Result2\n"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command3"]; + ["upload"; "test-command"; "/command3/test-command"]; + ["chmod"; "0o755"; "/command3/test-command"]; + ["command"; "/command3/test-command 3"]], "\nResult3"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command4"]; + ["upload"; "test-command"; "/command4/test-command"]; + ["chmod"; "0o755"; "/command4/test-command"]; + ["command"; "/command4/test-command 4"]], "\nResult4\n"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command5"]; + ["upload"; "test-command"; "/command5/test-command"]; + ["chmod"; "0o755"; "/command5/test-command"]; + ["command"; "/command5/test-command 5"]], "\nResult5\n\n"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command6"]; + ["upload"; "test-command"; "/command6/test-command"]; + ["chmod"; "0o755"; "/command6/test-command"]; + ["command"; "/command6/test-command 6"]], "\n\nResult6\n\n"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command7"]; + ["upload"; "test-command"; "/command7/test-command"]; + ["chmod"; "0o755"; "/command7/test-command"]; + ["command"; "/command7/test-command 7"]], ""), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command8"]; + ["upload"; "test-command"; "/command8/test-command"]; + ["chmod"; "0o755"; "/command8/test-command"]; + ["command"; "/command8/test-command 8"]], "\n"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command9"]; + ["upload"; "test-command"; "/command9/test-command"]; + ["chmod"; "0o755"; "/command9/test-command"]; + ["command"; "/command9/test-command 9"]], "\n\n"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command10"]; + ["upload"; "test-command"; "/command10/test-command"]; + ["chmod"; "0o755"; "/command10/test-command"]; + ["command"; "/command10/test-command 10"]], "Result10-1\nResult10-2\n"), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/command11"]; + ["upload"; "test-command"; "/command11/test-command"]; + ["chmod"; "0o755"; "/command11/test-command"]; + ["command"; "/command11/test-command 11"]], "Result11-1\nResult11-2"), []; + InitScratchFS, IfNotCrossAppliance, TestLastFail ( + [["mkdir"; "/command12"]; + ["upload"; "test-command"; "/command12/test-command"]; + ["chmod"; "0o755"; "/command12/test-command"]; + ["command"; "/command12/test-command"]]), []; + InitScratchFS, IfNotCrossAppliance, TestResultString ( + [["mkdir"; "/pwd"]; + ["upload"; "test-pwd"; "/pwd/test-pwd"]; + ["chmod"; "0o755"; "/pwd/test-pwd"]; + ["command"; "/pwd/test-pwd"]], "/"), []; + ]; + shortdesc = "run a command from the guest filesystem"; + longdesc = "\ +This call runs a command from the guest filesystem. The +filesystem must be mounted, and must contain a compatible +operating system (ie. something Linux, with the same +or compatible processor architecture). + +The single parameter is an argv-style list of arguments. +The first element is the name of the program to run. +Subsequent elements are parameters. The list must be +non-empty (ie. must contain a program name). Note that +the command runs directly, and is I<not> invoked via +the shell (see C<guestfs_sh>). + +The return value is anything printed to I<stdout> by +the command. + +If the command returns a non-zero exit status, then +this function returns an error message. The error message +string is the content of I<stderr> from the command. + +The C<$PATH> environment variable will contain at least +F</usr/bin> and F</bin>. If you require a program from +another location, you should provide the full path in the +first parameter. + +Shared libraries and data files required by the program +must be available on filesystems which are mounted in the +correct places. It is the caller's responsibility to ensure +all filesystems that are needed are mounted at the right +locations." }; + + { defaults with + name = "command_lines"; added = (1, 9, 1); + style = RStringList "lines", [StringList "arguments"], []; + proc_nr = Some 51; + protocol_limit_warning = true; + tests = [ + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines"]; + ["upload"; "test-command"; "/command_lines/test-command"]; + ["chmod"; "0o755"; "/command_lines/test-command"]; + ["command_lines"; "/command_lines/test-command 1"]], + "is_string_list (ret, 1, \"Result1\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines2"]; + ["upload"; "test-command"; "/command_lines2/test-command"]; + ["chmod"; "0o755"; "/command_lines2/test-command"]; + ["command_lines"; "/command_lines2/test-command 2"]], + "is_string_list (ret, 1, \"Result2\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines3"]; + ["upload"; "test-command"; "/command_lines3/test-command"]; + ["chmod"; "0o755"; "/command_lines3/test-command"]; + ["command_lines"; "/command_lines3/test-command 3"]], + "is_string_list (ret, 2, \"\", \"Result3\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines4"]; + ["upload"; "test-command"; "/command_lines4/test-command"]; + ["chmod"; "0o755"; "/command_lines4/test-command"]; + ["command_lines"; "/command_lines4/test-command 4"]], + "is_string_list (ret, 2, \"\", \"Result4\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines5"]; + ["upload"; "test-command"; "/command_lines5/test-command"]; + ["chmod"; "0o755"; "/command_lines5/test-command"]; + ["command_lines"; "/command_lines5/test-command 5"]], + "is_string_list (ret, 3, \"\", \"Result5\", \"\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines6"]; + ["upload"; "test-command"; "/command_lines6/test-command"]; + ["chmod"; "0o755"; "/command_lines6/test-command"]; + ["command_lines"; "/command_lines6/test-command 6"]], + "is_string_list (ret, 4, \"\", \"\", \"Result6\", \"\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines7"]; + ["upload"; "test-command"; "/command_lines7/test-command"]; + ["chmod"; "0o755"; "/command_lines7/test-command"]; + ["command_lines"; "/command_lines7/test-command 7"]], + "is_string_list (ret, 0)"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines8"]; + ["upload"; "test-command"; "/command_lines8/test-command"]; + ["chmod"; "0o755"; "/command_lines8/test-command"]; + ["command_lines"; "/command_lines8/test-command 8"]], + "is_string_list (ret, 1, \"\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines9"]; + ["upload"; "test-command"; "/command_lines9/test-command"]; + ["chmod"; "0o755"; "/command_lines9/test-command"]; + ["command_lines"; "/command_lines9/test-command 9"]], + "is_string_list (ret, 2, \"\", \"\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines10"]; + ["upload"; "test-command"; "/command_lines10/test-command"]; + ["chmod"; "0o755"; "/command_lines10/test-command"]; + ["command_lines"; "/command_lines10/test-command 10"]], + "is_string_list (ret, 2, \"Result10-1\", \"Result10-2\")"), []; + InitScratchFS, IfNotCrossAppliance, TestResult ( + [["mkdir"; "/command_lines11"]; + ["upload"; "test-command"; "/command_lines11/test-command"]; + ["chmod"; "0o755"; "/command_lines11/test-command"]; + ["command_lines"; "/command_lines11/test-command 11"]], + "is_string_list (ret, 2, \"Result11-1\", \"Result11-2\")"), [] + ]; + shortdesc = "run a command, returning lines"; + longdesc = "\ +This is the same as C<guestfs_command>, but splits the +result into a list of lines. + +See also: C<guestfs_sh_lines>" }; + + { defaults with + name = "statvfs"; added = (1, 9, 2); + style = RStruct ("statbuf", "statvfs"), [Pathname "path"], []; + proc_nr = Some 54; + tests = [ + InitISOFS, Always, TestResult ( + [["statvfs"; "/"]], "ret->namemax == 255"), [] + ]; + shortdesc = "get file system statistics"; + longdesc = "\ +Returns file system statistics for any mounted file system. +C<path> should be a file or directory in the mounted file system +(typically it is the mount point itself, but it doesn't need to be). + +This is the same as the L<statvfs(2)> system call." }; + + { defaults with + name = "tune2fs_l"; added = (1, 9, 2); + style = RHashtable "superblock", [Device "device"], []; + proc_nr = Some 55; + tests = [ + InitScratchFS, Always, TestResult ( + [["tune2fs_l"; "/dev/sdb1"]], + "check_hash (ret, \"Filesystem magic number\", \"0xEF53\") == 0 && "^ + "check_hash (ret, \"Filesystem OS type\", \"Linux\") == 0"), []; + ]; + shortdesc = "get ext2/ext3/ext4 superblock details"; + longdesc = "\ +This returns the contents of the ext2, ext3 or ext4 filesystem +superblock on C<device>. + +It is the same as running C<tune2fs -l device>. See L<tune2fs(8)> +manpage for more details. The list of fields returned isn't +clearly defined, and depends on both the version of C<tune2fs> +that libguestfs was built against, and the filesystem itself." }; + + { defaults with + name = "blockdev_setro"; added = (1, 9, 3); + style = RErr, [Device "device"], []; + proc_nr = Some 56; + tests = [ + InitEmpty, Always, TestResultTrue ( + [["blockdev_setro"; "/dev/sda"]; + ["blockdev_getro"; "/dev/sda"]]), [] + ]; + shortdesc = "set block device to read-only"; + longdesc = "\ +Sets the block device named C<device> to read-only. + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "blockdev_setrw"; added = (1, 9, 3); + style = RErr, [Device "device"], []; + proc_nr = Some 57; + tests = [ + InitEmpty, Always, TestResultFalse ( + [["blockdev_setrw"; "/dev/sda"]; + ["blockdev_getro"; "/dev/sda"]]), [] + ]; + shortdesc = "set block device to read-write"; + longdesc = "\ +Sets the block device named C<device> to read-write. + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "blockdev_getro"; added = (1, 9, 3); + style = RBool "ro", [Device "device"], []; + proc_nr = Some 58; + tests = [ + InitEmpty, Always, TestResultTrue ( + [["blockdev_setro"; "/dev/sda"]; + ["blockdev_getro"; "/dev/sda"]]), [] + ]; + shortdesc = "is block device set to read-only"; + longdesc = "\ +Returns a boolean indicating if the block device is read-only +(true if read-only, false if not). + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "blockdev_getss"; added = (1, 9, 3); + style = RInt "sectorsize", [Device "device"], []; + proc_nr = Some 59; + tests = [ + InitEmpty, Always, TestResult ( + [["blockdev_getss"; "/dev/sda"]], "ret == 512"), [] + ]; + shortdesc = "get sectorsize of block device"; + longdesc = "\ +This returns the size of sectors on a block device. +Usually 512, but can be larger for modern devices. + +(Note, this is not the size in sectors, use C<guestfs_blockdev_getsz> +for that). + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "blockdev_getbsz"; added = (1, 9, 3); + style = RInt "blocksize", [Device "device"], []; + proc_nr = Some 60; + test_excuse = "cannot be tested because output differs depending on page size"; + shortdesc = "get blocksize of block device"; + longdesc = "\ +This returns the block size of a device. + +Note: this is different from both I<size in blocks> and +I<filesystem block size>. Also this setting is not really +used by anything. You should probably not use it for +anything. Filesystems have their own idea about what +block size to choose. + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "blockdev_getsz"; added = (1, 9, 3); + style = RInt64 "sizeinsectors", [Device "device"], []; + proc_nr = Some 62; + tests = [ + InitEmpty, Always, TestResult ( + [["blockdev_getsz"; "/dev/sda"]], + "ret == INT64_C(2)*1024*1024*1024/512"), [] + ]; + shortdesc = "get total size of device in 512-byte sectors"; + longdesc = "\ +This returns the size of the device in units of 512-byte sectors +(even if the sectorsize isn't 512 bytes ... weird). + +See also C<guestfs_blockdev_getss> for the real sector size of +the device, and C<guestfs_blockdev_getsize64> for the more +useful I<size in bytes>. + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "blockdev_getsize64"; added = (1, 9, 3); + style = RInt64 "sizeinbytes", [Device "device"], []; + proc_nr = Some 63; + tests = [ + InitEmpty, Always, TestResult ( + [["blockdev_getsize64"; "/dev/sda"]], + "ret == INT64_C(2)*1024*1024*1024"), [] + ]; + shortdesc = "get total size of device in bytes"; + longdesc = "\ +This returns the size of the device in bytes. + +See also C<guestfs_blockdev_getsz>. + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "blockdev_flushbufs"; added = (1, 9, 3); + style = RErr, [Device "device"], []; + proc_nr = Some 64; + tests = [ + InitEmpty, Always, TestRun + [["blockdev_flushbufs"; "/dev/sda"]], [] + ]; + shortdesc = "flush device buffers"; + longdesc = "\ +This tells the kernel to flush internal buffers associated +with C<device>. + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "blockdev_rereadpt"; added = (1, 9, 3); + style = RErr, [Device "device"], []; + proc_nr = Some 65; + tests = [ + InitEmpty, Always, TestRun + [["blockdev_rereadpt"; "/dev/sda"]], [] + ]; + shortdesc = "reread partition table"; + longdesc = "\ +Reread the partition table on C<device>. + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "upload"; added = (1, 0, 2); + style = RErr, [FileIn "filename"; Dev_or_Path "remotefilename"], []; + proc_nr = Some 66; + progress = true; cancellable = true; + tests = [ + InitScratchFS, Always, TestResultString ( + (* Pick a file from cwd which isn't likely to change. *) + [["mkdir"; "/upload"]; + ["upload"; "$srcdir/../../COPYING.LIB"; "/upload/COPYING.LIB"]; + ["checksum"; "md5"; "/upload/COPYING.LIB"]], + Digest.to_hex (Digest.file "COPYING.LIB")), [] + ]; + shortdesc = "upload a file from the local machine"; + longdesc = "\ +Upload local file F<filename> to F<remotefilename> on the +filesystem. + +F<filename> can also be a named pipe. + +See also C<guestfs_download>." }; + + { defaults with + name = "download"; added = (1, 0, 2); + style = RErr, [Dev_or_Path "remotefilename"; FileOut "filename"], []; + proc_nr = Some 67; + progress = true; cancellable = true; + tests = [ + InitScratchFS, Always, TestResultString ( + (* Pick a file from cwd which isn't likely to change. *) + [["mkdir"; "/download"]; + ["upload"; "$srcdir/../../COPYING.LIB"; "/download/COPYING.LIB"]; + ["download"; "/download/COPYING.LIB"; "testdownload.tmp"]; + ["upload"; "testdownload.tmp"; "/download/upload"]; + ["checksum"; "md5"; "/download/upload"]], + Digest.to_hex (Digest.file "COPYING.LIB")), [] + ]; + shortdesc = "download a file to the local machine"; + longdesc = "\ +Download file F<remotefilename> and save it as F<filename> +on the local machine. + +F<filename> can also be a named pipe. + +See also C<guestfs_upload>, C<guestfs_cat>." }; + + { defaults with + name = "checksum"; added = (1, 0, 2); + style = RString "checksum", [String "csumtype"; Pathname "path"], []; + proc_nr = Some 68; + tests = [ + InitISOFS, Always, TestResultString ( + [["checksum"; "crc"; "/known-3"]], "2891671662"), []; + InitISOFS, Always, TestLastFail ( + [["checksum"; "crc"; "/notexists"]]), []; + InitISOFS, Always, TestResultString ( + [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c"), []; + InitISOFS, Always, TestResultString ( + [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15"), []; + InitISOFS, Always, TestResultString ( + [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741"), []; + InitISOFS, Always, TestResultString ( + [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30"), []; + InitISOFS, Always, TestResultString ( + [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640"), []; + InitISOFS, Always, TestResultString ( + [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6"), []; + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestResultString ( + [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a"), [] + ]; + shortdesc = "compute MD5, SHAx or CRC checksum of file"; + longdesc = "\ +This call computes the MD5, SHAx or CRC checksum of the +file named C<path>. + +The type of checksum to compute is given by the C<csumtype> +parameter which must have one of the following values: + +=over 4 + +=item C<crc> + +Compute the cyclic redundancy check (CRC) specified by POSIX +for the C<cksum> command. + +=item C<md5> + +Compute the MD5 hash (using the C<md5sum> program). + +=item C<sha1> + +Compute the SHA1 hash (using the C<sha1sum> program). + +=item C<sha224> + +Compute the SHA224 hash (using the C<sha224sum> program). + +=item C<sha256> + +Compute the SHA256 hash (using the C<sha256sum> program). + +=item C<sha384> + +Compute the SHA384 hash (using the C<sha384sum> program). + +=item C<sha512> + +Compute the SHA512 hash (using the C<sha512sum> program). + +=back + +The checksum is returned as a printable string. + +To get the checksum for a device, use C<guestfs_checksum_device>. + +To get the checksums for many files, use C<guestfs_checksums_out>." }; + + { defaults with + name = "tar_in"; added = (1, 0, 3); + style = RErr, [FileIn "tarfile"; Pathname "directory"], [OString "compress"; OBool "xattrs"; OBool "selinux"; OBool "acls"]; + proc_nr = Some 69; + once_had_no_optargs = true; + cancellable = true; + tests = [ + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/tar_in"]; + ["tar_in"; "$srcdir/../../test-data/files/helloworld.tar"; "/tar_in"; "NOARG"; ""; ""; ""]; + ["cat"; "/tar_in/hello"]], "hello\n"), []; + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/tar_in_gz"]; + ["tar_in"; "$srcdir/../../test-data/files/helloworld.tar.gz"; "/tar_in_gz"; "gzip"; ""; ""; ""]; + ["cat"; "/tar_in_gz/hello"]], "hello\n"), []; + InitScratchFS, IfAvailable "xz", TestResultString ( + [["mkdir"; "/tar_in_xz"]; + ["tar_in"; "$srcdir/../../test-data/files/helloworld.tar.xz"; "/tar_in_xz"; "xz"; ""; ""; ""]; + ["cat"; "/tar_in_xz/hello"]], "hello\n"), [] + ]; + shortdesc = "unpack tarfile to directory"; + longdesc = "\ +This command uploads and unpacks local file C<tarfile> into F<directory>. + +The optional C<compress> flag controls compression. If not given, +then the input should be an uncompressed tar file. Otherwise one +of the following strings may be given to select the compression +type of the input file: C<compress>, C<gzip>, C<bzip2>, C<xz>, C<lzop>. +(Note that not all builds of libguestfs will support all of these +compression types). + +The other optional arguments are: + +=over 4 + +=item C<xattrs> + +If set to true, extended attributes are restored from the tar file. + +=item C<selinux> + +If set to true, SELinux contexts are restored from the tar file. + +=item C<acls> + +If set to true, POSIX ACLs are restored from the tar file. + +=back" }; + + { defaults with + name = "tar_out"; added = (1, 0, 3); + style = RErr, [String "directory"; FileOut "tarfile"], [OString "compress"; OBool "numericowner"; OStringList "excludes"; OBool "xattrs"; OBool "selinux"; OBool "acls"]; + proc_nr = Some 70; + once_had_no_optargs = true; + cancellable = true; + shortdesc = "pack directory into tarfile"; + longdesc = "\ +This command packs the contents of F<directory> and downloads +it to local file C<tarfile>. + +The optional C<compress> flag controls compression. If not given, +then the output will be an uncompressed tar file. Otherwise one +of the following strings may be given to select the compression +type of the output file: C<compress>, C<gzip>, C<bzip2>, C<xz>, C<lzop>. +(Note that not all builds of libguestfs will support all of these +compression types). + +The other optional arguments are: + +=over 4 + +=item C<excludes> + +A list of wildcards. Files are excluded if they match any of the +wildcards. + +=item C<numericowner> + +If set to true, the output tar file will contain UID/GID numbers +instead of user/group names. + +=item C<xattrs> + +If set to true, extended attributes are saved in the output tar. + +=item C<selinux> + +If set to true, SELinux contexts are saved in the output tar. + +=item C<acls> + +If set to true, POSIX ACLs are saved in the output tar. + +=back" }; + + { defaults with + name = "mount_ro"; added = (1, 0, 10); + style = RErr, [Mountable "mountable"; String "mountpoint"], []; + proc_nr = Some 73; + tests = [ + InitBasicFS, Always, TestLastFail ( + [["umount"; "/"; "false"; "false"]; + ["mount_ro"; "/dev/sda1"; "/"]; + ["touch"; "/new"]]), []; + InitBasicFS, Always, TestResultString ( + [["write"; "/new"; "data"]; + ["umount"; "/"; "false"; "false"]; + ["mount_ro"; "/dev/sda1"; "/"]; + ["cat"; "/new"]], "data"), [] + ]; + shortdesc = "mount a guest disk, read-only"; + longdesc = "\ +This is the same as the C<guestfs_mount> command, but it +mounts the filesystem with the read-only (I<-o ro>) flag." }; + + { defaults with + name = "mount_options"; added = (1, 0, 10); + style = RErr, [String "options"; Mountable "mountable"; String "mountpoint"], []; + proc_nr = Some 74; + shortdesc = "mount a guest disk with mount options"; + longdesc = "\ +This is the same as the C<guestfs_mount> command, but it +allows you to set the mount options as for the +L<mount(8)> I<-o> flag. + +If the C<options> parameter is an empty string, then +no options are passed (all options default to whatever +the filesystem uses)." }; + + { defaults with + name = "mount_vfs"; added = (1, 0, 10); + style = RErr, [String "options"; String "vfstype"; Mountable "mountable"; String "mountpoint"], []; + proc_nr = Some 75; + shortdesc = "mount a guest disk with mount options and vfstype"; + longdesc = "\ +This is the same as the C<guestfs_mount> command, but it +allows you to set both the mount options and the vfstype +as for the L<mount(8)> I<-o> and I<-t> flags." }; + + { defaults with + name = "lvremove"; added = (1, 0, 13); + style = RErr, [Device "device"], []; + proc_nr = Some 77; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["lvremove"; "/dev/VG/LV1"]; + ["lvs"]], + "is_string_list (ret, 1, \"/dev/VG/LV2\")"), []; + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["lvremove"; "/dev/VG"]; + ["lvs"]], + "is_string_list (ret, 0)"), []; + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["lvremove"; "/dev/VG"]; + ["vgs"]], + "is_string_list (ret, 1, \"VG\")"), [] + ]; + shortdesc = "remove an LVM logical volume"; + longdesc = "\ +Remove an LVM logical volume C<device>, where C<device> is +the path to the LV, such as F</dev/VG/LV>. + +You can also remove all LVs in a volume group by specifying +the VG name, F</dev/VG>." }; + + { defaults with + name = "vgremove"; added = (1, 0, 13); + style = RErr, [String "vgname"], []; + proc_nr = Some 78; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["lvs"]], + "is_string_list (ret, 0)"), []; + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["vgs"]], + "is_string_list (ret, 0)"), [] + ]; + shortdesc = "remove an LVM volume group"; + longdesc = "\ +Remove an LVM volume group C<vgname>, (for example C<VG>). + +This also forcibly removes all logical volumes in the volume +group (if any)." }; + + { defaults with + name = "pvremove"; added = (1, 0, 13); + style = RErr, [Device "device"], []; + proc_nr = Some 79; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["pvremove"; "/dev/sda1"]; + ["lvs"]], + "is_string_list (ret, 0)"), []; + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["pvremove"; "/dev/sda1"]; + ["vgs"]], + "is_string_list (ret, 0)"), []; + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["pvremove"; "/dev/sda1"]; + ["pvs"]], + "is_string_list (ret, 0)"), [] + ]; + shortdesc = "remove an LVM physical volume"; + longdesc = "\ +This wipes a physical volume C<device> so that LVM will no longer +recognise it. + +The implementation uses the C<pvremove> command which refuses to +wipe physical volumes that contain any volume groups, so you have +to remove those first." }; + + { defaults with + name = "fsck"; added = (1, 0, 16); + style = RInt "status", [String "fstype"; Device "device"], []; + proc_nr = Some 84; + fish_output = Some FishOutputHexadecimal; + tests = [ + InitBasicFS, Always, TestResult ( + [["umount"; "/dev/sda1"; "false"; "false"]; + ["fsck"; "ext2"; "/dev/sda1"]], "ret == 0"), []; + InitBasicFS, Always, TestResult ( + [["umount"; "/dev/sda1"; "false"; "false"]; + ["zero"; "/dev/sda1"]; + ["fsck"; "ext2"; "/dev/sda1"]], "ret == 8"), [] + ]; + shortdesc = "run the filesystem checker"; + longdesc = "\ +This runs the filesystem checker (fsck) on C<device> which +should have filesystem type C<fstype>. + +The returned integer is the status. See L<fsck(8)> for the +list of status codes from C<fsck>. + +Notes: + +=over 4 + +=item * + +Multiple status codes can be summed together. + +=item * + +A non-zero return code can mean \"success\", for example if +errors have been corrected on the filesystem. + +=item * + +Checking or repairing NTFS volumes is not supported +(by linux-ntfs). + +=back + +This command is entirely equivalent to running C<fsck -a -t fstype device>." }; + + { defaults with + name = "zero"; added = (1, 0, 16); + style = RErr, [Device "device"], []; + proc_nr = Some 85; + progress = true; + tests = [ + InitBasicFS, Always, TestRun ( + [["umount"; "/dev/sda1"; "false"; "false"]; + ["zero"; "/dev/sda1"]]), [] + ]; + shortdesc = "write zeroes to the device"; + longdesc = "\ +This command writes zeroes over the first few blocks of C<device>. + +How many blocks are zeroed isn't specified (but it's I<not> enough +to securely wipe the device). It should be sufficient to remove +any partition tables, filesystem superblocks and so on. + +If blocks are already zero, then this command avoids writing +zeroes. This prevents the underlying device from becoming non-sparse +or growing unnecessarily. + +See also: C<guestfs_zero_device>, C<guestfs_scrub_device>, +C<guestfs_is_zero_device>" }; + + { defaults with + name = "grub_install"; added = (1, 0, 17); + style = RErr, [Pathname "root"; Device "device"], []; + proc_nr = Some 86; + optional = Some "grub"; + (* See: + * https://bugzilla.redhat.com/show_bug.cgi?id=484986 + * https://bugzilla.redhat.com/show_bug.cgi?id=479760 + *) + tests = [ + InitBasicFS, Always, TestResultTrue ( + [["mkdir_p"; "/boot/grub"]; + ["write"; "/boot/grub/device.map"; "(hd0) /dev/sda"]; + ["grub_install"; "/"; "/dev/sda"]; + ["is_dir"; "/boot"; ""]]), [] + ]; + shortdesc = "install GRUB 1"; + longdesc = "\ +This command installs GRUB 1 (the Grand Unified Bootloader) on +C<device>, with the root directory being C<root>. + +Notes: + +=over 4 + +=item * + +There is currently no way in the API to install grub2, which +is used by most modern Linux guests. It is possible to run +the grub2 command from the guest, although see the +caveats in L<guestfs(3)/RUNNING COMMANDS>. + +=item * + +This uses C<grub-install> from the host. Unfortunately grub is +not always compatible with itself, so this only works in rather +narrow circumstances. Careful testing with each guest version +is advisable. + +=item * + +If grub-install reports the error +\"No suitable drive was found in the generated device map.\" +it may be that you need to create a F</boot/grub/device.map> +file first that contains the mapping between grub device names +and Linux device names. It is usually sufficient to create +a file containing: + + (hd0) /dev/vda + +replacing F</dev/vda> with the name of the installation device. + +=back" }; + + { defaults with + name = "cp"; added = (1, 0, 18); + style = RErr, [Pathname "src"; Pathname "dest"], []; + proc_nr = Some 87; + tests = [ + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/cp"]; + ["write"; "/cp/old"; "file content"]; + ["cp"; "/cp/old"; "/cp/new"]; + ["cat"; "/cp/new"]], "file content"), []; + InitScratchFS, Always, TestResultTrue ( + [["mkdir"; "/cp2"]; + ["write"; "/cp2/old"; "file content"]; + ["cp"; "/cp2/old"; "/cp2/new"]; + ["is_file"; "/cp2/old"; ""]]), []; + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/cp3"]; + ["write"; "/cp3/old"; "file content"]; + ["mkdir"; "/cp3/dir"]; + ["cp"; "/cp3/old"; "/cp3/dir/new"]; + ["cat"; "/cp3/dir/new"]], "file content"), [] + ]; + shortdesc = "copy a file"; + longdesc = "\ +This copies a file from C<src> to C<dest> where C<dest> is +either a destination filename or destination directory." }; + + { defaults with + name = "cp_a"; added = (1, 0, 18); + style = RErr, [Pathname "src"; Pathname "dest"], []; + proc_nr = Some 88; + tests = [ + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/cp_a1"]; + ["mkdir"; "/cp_a2"]; + ["write"; "/cp_a1/file"; "file content"]; + ["cp_a"; "/cp_a1"; "/cp_a2"]; + ["cat"; "/cp_a2/cp_a1/file"]], "file content"), [] + ]; + shortdesc = "copy a file or directory recursively"; + longdesc = "\ +This copies a file or directory from C<src> to C<dest> +recursively using the C<cp -a> command." }; + + { defaults with + name = "mv"; added = (1, 0, 18); + style = RErr, [Pathname "src"; Pathname "dest"], []; + proc_nr = Some 89; + tests = [ + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/mv"]; + ["write"; "/mv/old"; "file content"]; + ["mv"; "/mv/old"; "/mv/new"]; + ["cat"; "/mv/new"]], "file content"), []; + InitScratchFS, Always, TestResultFalse ( + [["mkdir"; "/mv2"]; + ["write"; "/mv2/old"; "file content"]; + ["mv"; "/mv2/old"; "/mv2/new"]; + ["is_file"; "/mv2/old"; ""]]), [] + ]; + shortdesc = "move a file"; + longdesc = "\ +This moves a file from C<src> to C<dest> where C<dest> is +either a destination filename or destination directory. + +See also: C<guestfs_rename>." }; + + { defaults with + name = "drop_caches"; added = (1, 0, 18); + style = RErr, [Int "whattodrop"], []; + proc_nr = Some 90; + tests = [ + InitEmpty, Always, TestRun ( + [["drop_caches"; "3"]]), [] + ]; + shortdesc = "drop kernel page cache, dentries and inodes"; + longdesc = "\ +This instructs the guest kernel to drop its page cache, +and/or dentries and inode caches. The parameter C<whattodrop> +tells the kernel what precisely to drop, see +L<http://linux-mm.org/Drop_Caches> + +Setting C<whattodrop> to 3 should drop everything. + +This automatically calls L<sync(2)> before the operation, +so that the maximum guest memory is freed." }; + + { defaults with + name = "dmesg"; added = (1, 0, 18); + style = RString "kmsgs", [], []; + proc_nr = Some 91; + tests = [ + InitEmpty, Always, TestRun ( + [["dmesg"]]), [] + ]; + shortdesc = "return kernel messages"; + longdesc = "\ +This returns the kernel messages (C<dmesg> output) from +the guest kernel. This is sometimes useful for extended +debugging of problems. + +Another way to get the same information is to enable +verbose messages with C<guestfs_set_verbose> or by setting +the environment variable C<LIBGUESTFS_DEBUG=1> before +running the program." }; + + { defaults with + name = "ping_daemon"; added = (1, 0, 18); + style = RErr, [], []; + proc_nr = Some 92; + tests = [ + InitEmpty, Always, TestRun ( + [["ping_daemon"]]), [] + ]; + shortdesc = "ping the guest daemon"; + longdesc = "\ +This is a test probe into the guestfs daemon running inside +the libguestfs appliance. Calling this function checks that the +daemon responds to the ping message, without affecting the daemon +or attached block device(s) in any other way." }; + + { defaults with + name = "equal"; added = (1, 0, 18); + style = RBool "equality", [Pathname "file1"; Pathname "file2"], []; + proc_nr = Some 93; + tests = [ + InitScratchFS, Always, TestResultTrue ( + [["mkdir"; "/equal"]; + ["write"; "/equal/file1"; "contents of a file"]; + ["cp"; "/equal/file1"; "/equal/file2"]; + ["equal"; "/equal/file1"; "/equal/file2"]]), []; + InitScratchFS, Always, TestResultFalse ( + [["mkdir"; "/equal2"]; + ["write"; "/equal2/file1"; "contents of a file"]; + ["write"; "/equal2/file2"; "contents of another file"]; + ["equal"; "/equal2/file1"; "/equal2/file2"]]), []; + InitScratchFS, Always, TestLastFail ( + [["mkdir"; "/equal3"]; + ["equal"; "/equal3/file1"; "/equal3/file2"]]), [] + ]; + shortdesc = "test if two files have equal contents"; + longdesc = "\ +This compares the two files F<file1> and F<file2> and returns +true if their content is exactly equal, or false otherwise. + +The external L<cmp(1)> program is used for the comparison." }; + + { defaults with + name = "strings"; added = (1, 0, 22); + style = RStringList "stringsout", [Pathname "path"], []; + proc_nr = Some 94; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResult ( + [["strings"; "/known-5"]], + "is_string_list (ret, 2, \"abcdefghi\", \"jklmnopqr\")"), []; + InitISOFS, Always, TestResult ( + [["strings"; "/empty"]], + "is_string_list (ret, 0)"), []; + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestRun ( + [["strings"; "/abssymlink"]]), [] + ]; + shortdesc = "print the printable strings in a file"; + longdesc = "\ +This runs the L<strings(1)> command on a file and returns +the list of printable strings found. + +The C<strings> command has, in the past, had problems with +parsing untrusted files. These are mitigated in the current +version of libguestfs, but see L<guestfs(3)/CVE-2014-8484>." }; + + { defaults with + name = "strings_e"; added = (1, 0, 22); + style = RStringList "stringsout", [String "encoding"; Pathname "path"], []; + proc_nr = Some 95; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResult ( + [["strings_e"; "b"; "/known-5"]], + "is_string_list (ret, 0)"), []; + InitScratchFS, Always, TestResult ( + [["write"; "/strings_e"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"]; + ["strings_e"; "b"; "/strings_e"]], + "is_string_list (ret, 2, \"hello\", \"world\")"), [] + ]; + shortdesc = "print the printable strings in a file"; + longdesc = "\ +This is like the C<guestfs_strings> command, but allows you to +specify the encoding of strings that are looked for in +the source file C<path>. + +Allowed encodings are: + +=over 4 + +=item s + +Single 7-bit-byte characters like ASCII and the ASCII-compatible +parts of ISO-8859-X (this is what C<guestfs_strings> uses). + +=item S + +Single 8-bit-byte characters. + +=item b + +16-bit big endian strings such as those encoded in +UTF-16BE or UCS-2BE. + +=item l (lower case letter L) + +16-bit little endian such as UTF-16LE and UCS-2LE. +This is useful for examining binaries in Windows guests. + +=item B + +32-bit big endian such as UCS-4BE. + +=item L + +32-bit little endian such as UCS-4LE. + +=back + +The returned strings are transcoded to UTF-8. + +The C<strings> command has, in the past, had problems with +parsing untrusted files. These are mitigated in the current +version of libguestfs, but see L<guestfs(3)/CVE-2014-8484>." }; + + { defaults with + name = "hexdump"; added = (1, 0, 22); + style = RString "dump", [Pathname "path"], []; + proc_nr = Some 96; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResultString ( + [["hexdump"; "/known-4"]], "00000000 61 62 63 0a 64 65 66 0a 67 68 69 |abc.def.ghi|\n0000000b\n"), []; + (* Test for RHBZ#501888c2 regression which caused large hexdump + * commands to segfault. + *) + InitISOFS, Always, TestRun ( + [["hexdump"; "/100krandom"]]), []; + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestRun ( + [["hexdump"; "/abssymlink"]]), [] + ]; + shortdesc = "dump a file in hexadecimal"; + longdesc = "\ +This runs C<hexdump -C> on the given C<path>. The result is +the human-readable, canonical hex dump of the file." }; + + { defaults with + name = "zerofree"; added = (1, 0, 26); + style = RErr, [Device "device"], []; + proc_nr = Some 97; + optional = Some "zerofree"; + tests = [ + InitNone, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ext3"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["write"; "/new"; "test file"]; + ["umount"; "/dev/sda1"; "false"; "false"]; + ["zerofree"; "/dev/sda1"]; + ["mount"; "/dev/sda1"; "/"]; + ["cat"; "/new"]], "test file"), [] + ]; + shortdesc = "zero unused inodes and disk blocks on ext2/3 filesystem"; + longdesc = "\ +This runs the I<zerofree> program on C<device>. This program +claims to zero unused inodes and disk blocks on an ext2/3 +filesystem, thus making it possible to compress the filesystem +more effectively. + +You should B<not> run this program if the filesystem is +mounted. + +It is possible that using this program can damage the filesystem +or data on the filesystem." }; + + { defaults with + name = "pvresize"; added = (1, 0, 26); + style = RErr, [Device "device"], []; + proc_nr = Some 98; + optional = Some "lvm2"; + shortdesc = "resize an LVM physical volume"; + longdesc = "\ +This resizes (expands or shrinks) an existing LVM physical +volume to match the new size of the underlying device." }; + + { defaults with + name = "sfdisk_kernel_geometry"; added = (1, 0, 26); + style = RString "partitions", [Device "device"], []; + proc_nr = Some 101; + shortdesc = "display the kernel geometry"; + longdesc = "\ +This displays the kernel's idea of the geometry of C<device>. + +The result is in human-readable format, and not designed to +be parsed." }; + + { defaults with + name = "sfdisk_disk_geometry"; added = (1, 0, 26); + style = RString "partitions", [Device "device"], []; + proc_nr = Some 102; + shortdesc = "display the disk geometry from the partition table"; + longdesc = "\ +This displays the disk geometry of C<device> read from the +partition table. Especially in the case where the underlying +block device has been resized, this can be different from the +kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>). + +The result is in human-readable format, and not designed to +be parsed." }; + + { defaults with + name = "vg_activate_all"; added = (1, 0, 26); + style = RErr, [Bool "activate"], []; + proc_nr = Some 103; + optional = Some "lvm2"; + shortdesc = "activate or deactivate all volume groups"; + longdesc = "\ +This command activates or (if C<activate> is false) deactivates +all logical volumes in all volume groups. + +This command is the same as running C<vgchange -a y|n>" }; + + { defaults with + name = "vg_activate"; added = (1, 0, 26); + style = RErr, [Bool "activate"; StringList "volgroups"], []; + proc_nr = Some 104; + optional = Some "lvm2"; + shortdesc = "activate or deactivate some volume groups"; + longdesc = "\ +This command activates or (if C<activate> is false) deactivates +all logical volumes in the listed volume groups C<volgroups>. + +This command is the same as running C<vgchange -a y|n volgroups...> + +Note that if C<volgroups> is an empty list then B<all> volume groups +are activated or deactivated." }; + + { defaults with + name = "lvresize"; added = (1, 0, 27); + style = RErr, [Device "device"; Int "mbytes"], []; + proc_nr = Some 105; + optional = Some "lvm2"; + tests = [ + InitNone, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV"; "VG"; "10"]; + ["mkfs"; "ext2"; "/dev/VG/LV"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/VG/LV"; "/"]; + ["write"; "/new"; "test content"]; + ["umount"; "/"; "false"; "false"]; + ["lvresize"; "/dev/VG/LV"; "20"]; + ["e2fsck_f"; "/dev/VG/LV"]; + ["e2fsck"; "/dev/VG/LV"; "true"; "false"]; + ["e2fsck"; "/dev/VG/LV"; "false"; "true"]; + ["resize2fs"; "/dev/VG/LV"]; + ["mount"; "/dev/VG/LV"; "/"]; + ["cat"; "/new"]], "test content"), []; + InitNone, Always, TestRun ( + (* Make an LV smaller to test RHBZ#587484. *) + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV"; "VG"; "20"]; + ["lvresize"; "/dev/VG/LV"; "10"]]), [] + ]; + shortdesc = "resize an LVM logical volume"; + longdesc = "\ +This resizes (expands or shrinks) an existing LVM logical +volume to C<mbytes>. When reducing, data in the reduced part +is lost." }; + + { defaults with + name = "resize2fs"; added = (1, 0, 27); + style = RErr, [Device "device"], []; + proc_nr = Some 106; + shortdesc = "resize an ext2, ext3 or ext4 filesystem"; + longdesc = "\ +This resizes an ext2, ext3 or ext4 filesystem to match the size of +the underlying device. + +See also L<guestfs(3)/RESIZE2FS ERRORS>." }; + + { defaults with + name = "sleep"; added = (1, 0, 41); + style = RErr, [Int "secs"], []; + proc_nr = Some 109; + tests = [ + InitNone, Always, TestRun ( + [["sleep"; "1"]]), [] + ]; + shortdesc = "sleep for some seconds"; + longdesc = "\ +Sleep for C<secs> seconds." }; + + { defaults with + name = "ntfs_3g_probe"; added = (1, 0, 43); + style = RInt "status", [Bool "rw"; Device "device"], []; + proc_nr = Some 110; + optional = Some "ntfs3g"; + tests = [ + InitNone, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["ntfs_3g_probe"; "true"; "/dev/sda1"]], "ret == 0"), []; + InitNone, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["ntfs_3g_probe"; "true"; "/dev/sda1"]], "ret == 12"), [] + ]; + shortdesc = "probe NTFS volume"; + longdesc = "\ +This command runs the L<ntfs-3g.probe(8)> command which probes +an NTFS C<device> for mountability. (Not all NTFS volumes can +be mounted read-write, and some cannot be mounted at all). + +C<rw> is a boolean flag. Set it to true if you want to test +if the volume can be mounted read-write. Set it to false if +you want to test if the volume can be mounted read-only. + +The return value is an integer which C<0> if the operation +would succeed, or some non-zero value documented in the +L<ntfs-3g.probe(8)> manual page." }; + + { defaults with + name = "sh"; added = (1, 0, 50); + style = RString "output", [String "command"], []; + proc_nr = Some 111; + shortdesc = "run a command via the shell"; + longdesc = "\ +This call runs a command from the guest filesystem via the +guest's F</bin/sh>. + +This is like C<guestfs_command>, but passes the command to: + + /bin/sh -c \"command\" + +Depending on the guest's shell, this usually results in +wildcards being expanded, shell expressions being interpolated +and so on. + +All the provisos about C<guestfs_command> apply to this call." }; + + { defaults with + name = "sh_lines"; added = (1, 0, 50); + style = RStringList "lines", [String "command"], []; + proc_nr = Some 112; + shortdesc = "run a command via the shell returning lines"; + longdesc = "\ +This is the same as C<guestfs_sh>, but splits the result +into a list of lines. + +See also: C<guestfs_command_lines>" }; + + { defaults with + name = "glob_expand"; added = (1, 0, 50); + (* Use Pathname here, and hence ABS_PATH (pattern,...) in + * generated code in stubs.c, since all valid glob patterns must + * start with "/". There is no concept of "cwd" in libguestfs, + * hence no "."-relative names. + *) + style = RStringList "paths", [Pathname "pattern"], [OBool "directoryslash"]; + proc_nr = Some 113; + once_had_no_optargs = true; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir_p"; "/glob_expand/b/c"]; + ["touch"; "/glob_expand/b/c/d"]; + ["touch"; "/glob_expand/b/c/e"]; + ["glob_expand"; "/glob_expand/b/c/*"; ""]], + "is_string_list (ret, 2, \"/glob_expand/b/c/d\", \"/glob_expand/b/c/e\")"), []; + InitScratchFS, Always, TestResult ( + [["mkdir_p"; "/glob_expand2/b/c"]; + ["touch"; "/glob_expand2/b/c/d"]; + ["touch"; "/glob_expand2/b/c/e"]; + ["glob_expand"; "/glob_expand2/*/c/*"; ""]], + "is_string_list (ret, 2, \"/glob_expand2/b/c/d\", \"/glob_expand2/b/c/e\")"), []; + InitScratchFS, Always, TestResult ( + [["mkdir_p"; "/glob_expand3/b/c"]; + ["touch"; "/glob_expand3/b/c/d"]; + ["touch"; "/glob_expand3/b/c/e"]; + ["glob_expand"; "/glob_expand3/*/x/*"; ""]], + "is_string_list (ret, 0)"), []; + InitScratchFS, Always, TestResult ( + [["mkdir_p"; "/glob_expand4/b/c"]; + ["touch"; "/glob_expand4/b1"]; + ["touch"; "/glob_expand4/c1"]; + ["glob_expand"; "/glob_expand4/b*"; "false"]], + "is_string_list (ret, 2, \"/glob_expand4/b\", \"/glob_expand4/b1\")"), []; + ]; + shortdesc = "expand a wildcard path"; + longdesc = "\ +This command searches for all the pathnames matching +C<pattern> according to the wildcard expansion rules +used by the shell. + +If no paths match, then this returns an empty list +(note: not an error). + +It is just a wrapper around the C L<glob(3)> function +with flags C<GLOB_MARK|GLOB_BRACE>. +See that manual page for more details. + +C<directoryslash> controls whether use the C<GLOB_MARK> flag for +L<glob(3)>, and it defaults to true. It can be explicitly set as +off to return no trailing slashes in filenames of directories. + +Notice that there is no equivalent command for expanding a device +name (eg. F</dev/sd*>). Use C<guestfs_list_devices>, +C<guestfs_list_partitions> etc functions instead." }; + + { defaults with + name = "scrub_device"; added = (1, 0, 52); + style = RErr, [Device "device"], []; + proc_nr = Some 114; + optional = Some "scrub"; + tests = [ + InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *) + [["scrub_device"; "/dev/sdc"]]), [] + ]; + shortdesc = "scrub (securely wipe) a device"; + longdesc = "\ +This command writes patterns over C<device> to make data retrieval +more difficult. + +It is an interface to the L<scrub(1)> program. See that +manual page for more details." }; + + { defaults with + name = "scrub_file"; added = (1, 0, 52); + style = RErr, [Pathname "file"], []; + proc_nr = Some 115; + optional = Some "scrub"; + tests = [ + InitScratchFS, Always, TestRun ( + [["write"; "/scrub_file"; "content"]; + ["scrub_file"; "/scrub_file"]]), []; + InitScratchFS, Always, TestRun ( + [["write"; "/scrub_file_2"; "content"]; + ["ln_s"; "/scrub_file_2"; "/scrub_file_2_link"]; + ["scrub_file"; "/scrub_file_2_link"]]), []; + InitScratchFS, Always, TestLastFail ( + [["ln_s"; "/scrub_file_3_notexisting"; "/scrub_file_3_link"]; + ["scrub_file"; "/scrub_file_3_link"]]), []; + InitScratchFS, Always, TestLastFail ( + [["write"; "/scrub_file_4"; "content"]; + ["ln_s"; "../sysroot/scrub_file_4"; "/scrub_file_4_link"]; + ["scrub_file"; "/scrub_file_4_link"]]), []; + ]; + shortdesc = "scrub (securely wipe) a file"; + longdesc = "\ +This command writes patterns over a file to make data retrieval +more difficult. + +The file is I<removed> after scrubbing. + +It is an interface to the L<scrub(1)> program. See that +manual page for more details." }; + + { defaults with + name = "scrub_freespace"; added = (1, 0, 52); + style = RErr, [Pathname "dir"], []; + proc_nr = Some 116; + optional = Some "scrub"; + tests = [] (* XXX needs testing *); + shortdesc = "scrub (securely wipe) free space"; + longdesc = "\ +This command creates the directory C<dir> and then fills it +with files until the filesystem is full, and scrubs the files +as for C<guestfs_scrub_file>, and deletes them. +The intention is to scrub any free space on the partition +containing C<dir>. + +It is an interface to the L<scrub(1)> program. See that +manual page for more details." }; + + { defaults with + name = "mkdtemp"; added = (1, 0, 54); + style = RString "dir", [Pathname "tmpl"], []; + proc_nr = Some 117; + tests = [ + InitScratchFS, Always, TestRun ( + [["mkdir"; "/mkdtemp"]; + ["mkdtemp"; "/mkdtemp/tmpXXXXXX"]]), [] + ]; + shortdesc = "create a temporary directory"; + longdesc = "\ +This command creates a temporary directory. The +C<tmpl> parameter should be a full pathname for the +temporary directory name with the final six characters being +\"XXXXXX\". + +For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\", +the second one being suitable for Windows filesystems. + +The name of the temporary directory that was created +is returned. + +The temporary directory is created with mode 0700 +and is owned by root. + +The caller is responsible for deleting the temporary +directory and its contents after use. + +See also: L<mkdtemp(3)>" }; + + { defaults with + name = "wc_l"; added = (1, 0, 54); + style = RInt "lines", [Pathname "path"], []; + proc_nr = Some 118; + tests = [ + InitISOFS, Always, TestResult ( + [["wc_l"; "/10klines"]], "ret == 10000"), []; + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestResult ( + [["wc_l"; "/abssymlink"]], "ret == 10000"), [] + ]; + shortdesc = "count lines in a file"; + longdesc = "\ +This command counts the lines in a file, using the +C<wc -l> external command." }; + + { defaults with + name = "wc_w"; added = (1, 0, 54); + style = RInt "words", [Pathname "path"], []; + proc_nr = Some 119; + tests = [ + InitISOFS, Always, TestResult ( + [["wc_w"; "/10klines"]], "ret == 10000"), [] + ]; + shortdesc = "count words in a file"; + longdesc = "\ +This command counts the words in a file, using the +C<wc -w> external command." }; + + { defaults with + name = "wc_c"; added = (1, 0, 54); + style = RInt "chars", [Pathname "path"], []; + proc_nr = Some 120; + tests = [ + InitISOFS, Always, TestResult ( + [["wc_c"; "/100kallspaces"]], "ret == 102400"), [] + ]; + shortdesc = "count characters in a file"; + longdesc = "\ +This command counts the characters in a file, using the +C<wc -c> external command." }; + + { defaults with + name = "head"; added = (1, 0, 54); + style = RStringList "lines", [Pathname "path"], []; + proc_nr = Some 121; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResult ( + [["head"; "/10klines"]], + "is_string_list (ret, 10, \"0abcdefghijklmnopqrstuvwxyz\", \"1abcdefghijklmnopqrstuvwxyz\", \"2abcdefghijklmnopqrstuvwxyz\", \"3abcdefghijklmnopqrstuvwxyz\", \"4abcdefghijklmnopqrstuvwxyz\", \"5abcdefghijklmnopqrstuvwxyz\", \"6abcdefghijklmnopqrstuvwxyz\", \"7abcdefghijklmnopqrstuvwxyz\", \"8abcdefghijklmnopqrstuvwxyz\", \"9abcdefghijklmnopqrstuvwxyz\")"), []; + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestResult ( + [["head"; "/abssymlink"]], + "is_string_list (ret, 10, \"0abcdefghijklmnopqrstuvwxyz\", \"1abcdefghijklmnopqrstuvwxyz\", \"2abcdefghijklmnopqrstuvwxyz\", \"3abcdefghijklmnopqrstuvwxyz\", \"4abcdefghijklmnopqrstuvwxyz\", \"5abcdefghijklmnopqrstuvwxyz\", \"6abcdefghijklmnopqrstuvwxyz\", \"7abcdefghijklmnopqrstuvwxyz\", \"8abcdefghijklmnopqrstuvwxyz\", \"9abcdefghijklmnopqrstuvwxyz\")"), [] + ]; + shortdesc = "return first 10 lines of a file"; + longdesc = "\ +This command returns up to the first 10 lines of a file as +a list of strings." }; + + { defaults with + name = "head_n"; added = (1, 0, 54); + style = RStringList "lines", [Int "nrlines"; Pathname "path"], []; + proc_nr = Some 122; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResult ( + [["head_n"; "3"; "/10klines"]], + "is_string_list (ret, 3, \"0abcdefghijklmnopqrstuvwxyz\", \"1abcdefghijklmnopqrstuvwxyz\", \"2abcdefghijklmnopqrstuvwxyz\")"), []; + InitISOFS, Always, TestResult ( + [["head_n"; "-9997"; "/10klines"]], + "is_string_list (ret, 3, \"0abcdefghijklmnopqrstuvwxyz\", \"1abcdefghijklmnopqrstuvwxyz\", \"2abcdefghijklmnopqrstuvwxyz\")"), []; + InitISOFS, Always, TestResult ( + [["head_n"; "0"; "/10klines"]], + "is_string_list (ret, 0)"), [] + ]; + shortdesc = "return first N lines of a file"; + longdesc = "\ +If the parameter C<nrlines> is a positive number, this returns the first +C<nrlines> lines of the file C<path>. + +If the parameter C<nrlines> is a negative number, this returns lines +from the file C<path>, excluding the last C<nrlines> lines. + +If the parameter C<nrlines> is zero, this returns an empty list." }; + + { defaults with + name = "tail"; added = (1, 0, 54); + style = RStringList "lines", [Pathname "path"], []; + proc_nr = Some 123; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResult ( + [["tail"; "/10klines"]], + "is_string_list (ret, 10, \"9990abcdefghijklmnopqrstuvwxyz\", \"9991abcdefghijklmnopqrstuvwxyz\", \"9992abcdefghijklmnopqrstuvwxyz\", \"9993abcdefghijklmnopqrstuvwxyz\", \"9994abcdefghijklmnopqrstuvwxyz\", \"9995abcdefghijklmnopqrstuvwxyz\", \"9996abcdefghijklmnopqrstuvwxyz\", \"9997abcdefghijklmnopqrstuvwxyz\", \"9998abcdefghijklmnopqrstuvwxyz\", \"9999abcdefghijklmnopqrstuvwxyz\")"), [] + ]; + shortdesc = "return last 10 lines of a file"; + longdesc = "\ +This command returns up to the last 10 lines of a file as +a list of strings." }; + + { defaults with + name = "tail_n"; added = (1, 0, 54); + style = RStringList "lines", [Int "nrlines"; Pathname "path"], []; + proc_nr = Some 124; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResult ( + [["tail_n"; "3"; "/10klines"]], + "is_string_list (ret, 3, \"9997abcdefghijklmnopqrstuvwxyz\", \"9998abcdefghijklmnopqrstuvwxyz\", \"9999abcdefghijklmnopqrstuvwxyz\")"), []; + InitISOFS, Always, TestResult ( + [["tail_n"; "-9998"; "/10klines"]], + "is_string_list (ret, 3, \"9997abcdefghijklmnopqrstuvwxyz\", \"9998abcdefghijklmnopqrstuvwxyz\", \"9999abcdefghijklmnopqrstuvwxyz\")"), []; + InitISOFS, Always, TestResult ( + [["tail_n"; "0"; "/10klines"]], + "is_string_list (ret, 0)"), [] + ]; + shortdesc = "return last N lines of a file"; + longdesc = "\ +If the parameter C<nrlines> is a positive number, this returns the last +C<nrlines> lines of the file C<path>. + +If the parameter C<nrlines> is a negative number, this returns lines +from the file C<path>, starting with the C<-nrlines>th line. + +If the parameter C<nrlines> is zero, this returns an empty list." }; + + { defaults with + name = "df"; added = (1, 0, 54); + style = RString "output", [], []; + proc_nr = Some 125; + test_excuse = "tricky to test because it depends on the exact format of the 'df' command and other imponderables"; + shortdesc = "report file system disk space usage"; + longdesc = "\ +This command runs the C<df> command to report disk space used. + +This command is mostly useful for interactive sessions. It +is I<not> intended that you try to parse the output string. +Use C<guestfs_statvfs> from programs." }; + + { defaults with + name = "df_h"; added = (1, 0, 54); + style = RString "output", [], []; + proc_nr = Some 126; + test_excuse = "tricky to test because it depends on the exact format of the 'df' command and other imponderables"; + shortdesc = "report file system disk space usage (human readable)"; + longdesc = "\ +This command runs the C<df -h> command to report disk space used +in human-readable format. + +This command is mostly useful for interactive sessions. It +is I<not> intended that you try to parse the output string. +Use C<guestfs_statvfs> from programs." }; + + { defaults with + name = "du"; added = (1, 0, 54); + style = RInt64 "sizekb", [Pathname "path"], []; + proc_nr = Some 127; + progress = true; + tests = [ + InitISOFS, Always, TestResult ( + [["du"; "/directory"]], "ret == 2" (* ISO fs blocksize is 2K *)), [] + ]; + shortdesc = "estimate file space usage"; + longdesc = "\ +This command runs the C<du -s> command to estimate file space +usage for C<path>. + +C<path> can be a file or a directory. If C<path> is a directory +then the estimate includes the contents of the directory and all +subdirectories (recursively). + +The result is the estimated size in I<kilobytes> +(ie. units of 1024 bytes)." }; + + { defaults with + name = "initrd_list"; added = (1, 0, 54); + style = RStringList "filenames", [Pathname "path"], []; + proc_nr = Some 128; + tests = [ + InitISOFS, Always, TestResult ( + [["initrd_list"; "/initrd"]], + "is_string_list (ret, 6, \"empty\", \"known-1\", \"known-2\", \"known-3\", \"known-4\", \"known-5\")"), [] + ]; + shortdesc = "list files in an initrd"; + longdesc = "\ +This command lists out files contained in an initrd. + +The files are listed without any initial F</> character. The +files are listed in the order they appear (not necessarily +alphabetical). Directory names are listed as separate items. + +Old Linux kernels (2.4 and earlier) used a compressed ext2 +filesystem as initrd. We I<only> support the newer initramfs +format (compressed cpio files)." }; + + { defaults with + name = "mount_loop"; added = (1, 0, 54); + style = RErr, [Pathname "file"; Pathname "mountpoint"], []; + proc_nr = Some 129; + shortdesc = "mount a file using the loop device"; + longdesc = "\ +This command lets you mount F<file> (a filesystem image +in a file) on a mount point. It is entirely equivalent to +the command C<mount -o loop file mountpoint>." }; + + { defaults with + name = "mkswap"; added = (1, 0, 55); + style = RErr, [Device "device"], [OString "label"; OString "uuid"]; + proc_nr = Some 130; + once_had_no_optargs = true; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkswap"; "/dev/sda1"; "NOARG"; "NOARG"]]), []; + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkswap"; "/dev/sda1"; "hello"; "NOARG"]]), []; + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkswap"; "/dev/sda1"; "NOARG"; stable_uuid]; + ["vfs_uuid"; "/dev/sda1"]], stable_uuid), []; + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkswap"; "/dev/sda1"; "hello"; stable_uuid]; + ["vfs_label"; "/dev/sda1"]], "hello"), [] + ]; + shortdesc = "create a swap partition"; + longdesc = "\ +Create a Linux swap partition on C<device>. + +The option arguments C<label> and C<uuid> allow you to set the +label and/or UUID of the new swap partition." }; + + { defaults with + name = "mknod"; added = (1, 0, 55); + style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []; + proc_nr = Some 133; + optional = Some "mknod"; + tests = [ + InitScratchFS, Always, TestResult ( + [["mknod"; "0o10777"; "0"; "0"; "/mknod"]; + (* NB: default umask 022 means 0777 -> 0755 in these tests *) + ["stat"; "/mknod"]], + "S_ISFIFO (ret->mode) && (ret->mode & 0777) == 0755"), []; + InitScratchFS, Always, TestResult ( + [["mknod"; "0o60777"; "66"; "99"; "/mknod2"]; + ["stat"; "/mknod2"]], + "S_ISBLK (ret->mode) && (ret->mode & 0777) == 0755"), [] + ]; + shortdesc = "make block, character or FIFO devices"; + longdesc = "\ +This call creates block or character special devices, or +named pipes (FIFOs). + +The C<mode> parameter should be the mode, using the standard +constants. C<devmajor> and C<devminor> are the +device major and minor numbers, only used when creating block +and character special devices. + +Note that, just like L<mknod(2)>, the mode must be bitwise +OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call +just creates a regular file). These constants are +available in the standard Linux header files, or you can use +C<guestfs_mknod_b>, C<guestfs_mknod_c> or C<guestfs_mkfifo> +which are wrappers around this command which bitwise OR +in the appropriate constant for you. + +The mode actually set is affected by the umask." }; + + { defaults with + name = "mkfifo"; added = (1, 0, 55); + style = RErr, [Int "mode"; Pathname "path"], []; + proc_nr = Some 134; + optional = Some "mknod"; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkfifo"; "0o777"; "/mkfifo"]; + ["stat"; "/mkfifo"]], + "S_ISFIFO (ret->mode) && (ret->mode & 0777) == 0755"), []; + InitScratchFS, Always, TestLastFail ( + [["mkfifo"; "0o20777"; "/mkfifo-2"]]), []; + ]; + shortdesc = "make FIFO (named pipe)"; + longdesc = "\ +This call creates a FIFO (named pipe) called C<path> with +mode C<mode>. It is just a convenient wrapper around +C<guestfs_mknod>. + +Unlike with C<guestfs_mknod>, C<mode> B<must> contain only permissions +bits. + +The mode actually set is affected by the umask." }; + + { defaults with + name = "mknod_b"; added = (1, 0, 55); + style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []; + proc_nr = Some 135; + optional = Some "mknod"; + tests = [ + InitScratchFS, Always, TestResult ( + [["mknod_b"; "0o777"; "99"; "66"; "/mknod_b"]; + ["stat"; "/mknod_b"]], + "S_ISBLK (ret->mode) && (ret->mode & 0777) == 0755"), []; + InitScratchFS, Always, TestLastFail ( + [["mknod_b"; "0o10777"; "99"; "66"; "/mknod_b-2"]]), []; + ]; + shortdesc = "make block device node"; + longdesc = "\ +This call creates a block device node called C<path> with +mode C<mode> and device major/minor C<devmajor> and C<devminor>. +It is just a convenient wrapper around C<guestfs_mknod>. + +Unlike with C<guestfs_mknod>, C<mode> B<must> contain only permissions +bits. + +The mode actually set is affected by the umask." }; + + { defaults with + name = "mknod_c"; added = (1, 0, 55); + style = RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"], []; + proc_nr = Some 136; + optional = Some "mknod"; + tests = [ + InitScratchFS, Always, TestResult ( + [["mknod_c"; "0o777"; "99"; "66"; "/mknod_c"]; + ["stat"; "/mknod_c"]], + "S_ISCHR (ret->mode) && (ret->mode & 0777) == 0755"), []; + InitScratchFS, Always, TestLastFail ( + [["mknod_c"; "0o20777"; "99"; "66"; "/mknod_c-2"]]), []; + ]; + shortdesc = "make char device node"; + longdesc = "\ +This call creates a char device node called C<path> with +mode C<mode> and device major/minor C<devmajor> and C<devminor>. +It is just a convenient wrapper around C<guestfs_mknod>. + +Unlike with C<guestfs_mknod>, C<mode> B<must> contain only permissions +bits. + +The mode actually set is affected by the umask." }; + + { defaults with + name = "umask"; added = (1, 0, 55); + style = RInt "oldmask", [Int "mask"], []; + proc_nr = Some 137; + fish_output = Some FishOutputOctal; + tests = [ + InitEmpty, Always, TestResult ( + [["umask"; "0o22"]], "ret == 022"), [] + ]; + shortdesc = "set file mode creation mask (umask)"; + longdesc = "\ +This function sets the mask used for creating new files and +device nodes to C<mask & 0777>. + +Typical umask values would be C<022> which creates new files +with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and +C<002> which creates new files with permissions like +\"-rw-rw-r--\" or \"-rwxrwxr-x\". + +The default umask is C<022>. This is important because it +means that directories and device nodes will be created with +C<0644> or C<0755> mode even if you specify C<0777>. + +See also C<guestfs_get_umask>, +L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>. + +This call returns the previous umask." }; + + { defaults with + name = "readdir"; added = (1, 0, 55); + style = RStructList ("entries", "dirent"), [Pathname "dir"], []; + proc_nr = Some 138; + protocol_limit_warning = true; + shortdesc = "read directories entries"; + longdesc = "\ +This returns the list of directory entries in directory C<dir>. + +All entries in the directory are returned, including C<.> and +C<..>. The entries are I<not> sorted, but returned in the same +order as the underlying filesystem. + +Also this call returns basic file type information about each +file. The C<ftyp> field will contain one of the following characters: + +=over 4 + +=item 'b' + +Block special + +=item 'c' + +Char special + +=item 'd' + +Directory + +=item 'f' + +FIFO (named pipe) + +=item 'l' + +Symbolic link + +=item 'r' + +Regular file + +=item 's' + +Socket + +=item 'u' + +Unknown file type + +=item '?' + +The L<readdir(3)> call returned a C<d_type> field with an +unexpected value + +=back + +This function is primarily intended for use by programs. To +get a simple list of names, use C<guestfs_ls>. To get a printable +directory for human consumption, use C<guestfs_ll>." }; + + { defaults with + name = "getxattrs"; added = (1, 0, 59); + style = RStructList ("xattrs", "xattr"), [Pathname "path"], []; + proc_nr = Some 141; + optional = Some "linuxxattrs"; + shortdesc = "list extended attributes of a file or directory"; + longdesc = "\ +This call lists the extended attributes of the file or directory +C<path>. + +At the system call level, this is a combination of the +L<listxattr(2)> and L<getxattr(2)> calls. + +See also: C<guestfs_lgetxattrs>, L<attr(5)>." }; + + { defaults with + name = "lgetxattrs"; added = (1, 0, 59); + style = RStructList ("xattrs", "xattr"), [Pathname "path"], []; + proc_nr = Some 142; + optional = Some "linuxxattrs"; + shortdesc = "list extended attributes of a file or directory"; + longdesc = "\ +This is the same as C<guestfs_getxattrs>, but if C<path> +is a symbolic link, then it returns the extended attributes +of the link itself." }; + + { defaults with + name = "setxattr"; added = (1, 0, 59); + style = RErr, [String "xattr"; + String "val"; Int "vallen"; (* will be BufferIn *) + Pathname "path"], []; + proc_nr = Some 143; + optional = Some "linuxxattrs"; + shortdesc = "set extended attribute of a file or directory"; + longdesc = "\ +This call sets the extended attribute named C<xattr> +of the file C<path> to the value C<val> (of length C<vallen>). +The value is arbitrary 8 bit data. + +See also: C<guestfs_lsetxattr>, L<attr(5)>." }; + + { defaults with + name = "lsetxattr"; added = (1, 0, 59); + style = RErr, [String "xattr"; + String "val"; Int "vallen"; (* will be BufferIn *) + Pathname "path"], []; + proc_nr = Some 144; + optional = Some "linuxxattrs"; + shortdesc = "set extended attribute of a file or directory"; + longdesc = "\ +This is the same as C<guestfs_setxattr>, but if C<path> +is a symbolic link, then it sets an extended attribute +of the link itself." }; + + { defaults with + name = "removexattr"; added = (1, 0, 59); + style = RErr, [String "xattr"; Pathname "path"], []; + proc_nr = Some 145; + optional = Some "linuxxattrs"; + shortdesc = "remove extended attribute of a file or directory"; + longdesc = "\ +This call removes the extended attribute named C<xattr> +of the file C<path>. + +See also: C<guestfs_lremovexattr>, L<attr(5)>." }; + + { defaults with + name = "lremovexattr"; added = (1, 0, 59); + style = RErr, [String "xattr"; Pathname "path"], []; + proc_nr = Some 146; + optional = Some "linuxxattrs"; + shortdesc = "remove extended attribute of a file or directory"; + longdesc = "\ +This is the same as C<guestfs_removexattr>, but if C<path> +is a symbolic link, then it removes an extended attribute +of the link itself." }; + + { defaults with + name = "mountpoints"; added = (1, 0, 62); + style = RHashtable "mps", [], []; + proc_nr = Some 147; + shortdesc = "show mountpoints"; + longdesc = "\ +This call is similar to C<guestfs_mounts>. That call returns +a list of devices. This one returns a hash table (map) of +device name to directory where the device is mounted." }; + + { defaults with + name = "mkmountpoint"; added = (1, 0, 62); + (* This is a special case: while you would expect a parameter + * of type "Pathname", that doesn't work, because it implies + * NEED_ROOT in the generated calling code in stubs.c, and + * this function cannot use NEED_ROOT. + *) + style = RErr, [String "exemptpath"], []; + proc_nr = Some 148; + shortdesc = "create a mountpoint"; + longdesc = "\ +C<guestfs_mkmountpoint> and C<guestfs_rmmountpoint> are +specialized calls that can be used to create extra mountpoints +before mounting the first filesystem. + +These calls are I<only> necessary in some very limited circumstances, +mainly the case where you want to mount a mix of unrelated and/or +read-only filesystems together. + +For example, live CDs often contain a \"Russian doll\" nest of +filesystems, an ISO outer layer, with a squashfs image inside, with +an ext2/3 image inside that. You can unpack this as follows +in guestfish: + + add-ro Fedora-11-i686-Live.iso + run + mkmountpoint /cd + mkmountpoint /sqsh + mkmountpoint /ext3fs + mount /dev/sda /cd + mount-loop /cd/LiveOS/squashfs.img /sqsh + mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs + +The inner filesystem is now unpacked under the /ext3fs mountpoint. + +C<guestfs_mkmountpoint> is not compatible with C<guestfs_umount_all>. +You may get unexpected errors if you try to mix these calls. It is +safest to manually unmount filesystems and remove mountpoints after use. + +C<guestfs_umount_all> unmounts filesystems by sorting the paths +longest first, so for this to work for manual mountpoints, you +must ensure that the innermost mountpoints have the longest +pathnames, as in the example code above. + +For more details see L<https://bugzilla.redhat.com/show_bug.cgi?id=599503> + +Autosync [see C<guestfs_set_autosync>, this is set by default on +handles] can cause C<guestfs_umount_all> to be called when the handle +is closed which can also trigger these issues." }; + + { defaults with + name = "rmmountpoint"; added = (1, 0, 62); + style = RErr, [String "exemptpath"], []; + proc_nr = Some 149; + shortdesc = "remove a mountpoint"; + longdesc = "\ +This calls removes a mountpoint that was previously created +with C<guestfs_mkmountpoint>. See C<guestfs_mkmountpoint> +for full details." }; + + { defaults with + name = "grep"; added = (1, 0, 66); + style = RStringList "lines", [String "regex"; Pathname "path"], [OBool "extended"; OBool "fixed"; OBool "insensitive"; OBool "compressed"]; + proc_nr = Some 151; + protocol_limit_warning = true; once_had_no_optargs = true; + tests = [ + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt"; ""; ""; ""; ""]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "nomatch"; "/test-grep.txt"; ""; ""; ""; ""]], + "is_string_list (ret, 0)"), []; + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestResult ( + [["grep"; "nomatch"; "/abssymlink"; ""; ""; ""; ""]], + "is_string_list (ret, 0)"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt"; "true"; ""; ""; ""]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt"; ""; "true"; ""; ""]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt"; ""; ""; "true"; ""]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt"; "true"; ""; "true"; ""]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt"; ""; "true"; "true"; ""]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt.gz"; ""; ""; ""; "true"]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt.gz"; "true"; ""; ""; "true"]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt.gz"; ""; "true"; ""; "true"]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt.gz"; ""; ""; "true"; "true"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt.gz"; "true"; ""; "true"; "true"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), []; + InitISOFS, Always, TestResult ( + [["grep"; "abc"; "/test-grep.txt.gz"; ""; "true"; "true"; "true"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<grep> program and returns the +matching lines. + +The optional flags are: + +=over 4 + +=item C<extended> + +Use extended regular expressions. +This is the same as using the I<-E> flag. + +=item C<fixed> + +Match fixed (don't use regular expressions). +This is the same as using the I<-F> flag. + +=item C<insensitive> + +Match case-insensitive. This is the same as using the I<-i> flag. + +=item C<compressed> + +Use C<zgrep> instead of C<grep>. This allows the input to be +compress- or gzip-compressed. + +=back" }; + + { defaults with + name = "realpath"; added = (1, 0, 66); + style = RString "rpath", [Pathname "path"], []; + proc_nr = Some 163; + tests = [ + InitISOFS, Always, TestResultString ( + [["realpath"; "/../directory"]], "/directory"), [] + ]; + shortdesc = "canonicalized absolute pathname"; + longdesc = "\ +Return the canonicalized absolute pathname of C<path>. The +returned path has no C<.>, C<..> or symbolic link path elements." }; + + { defaults with + name = "ln"; added = (1, 0, 66); + style = RErr, [String "target"; Pathname "linkname"], []; + proc_nr = Some 164; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir"; "/ln"]; + ["touch"; "/ln/a"]; + ["ln"; "/ln/a"; "/ln/b"]; + ["stat"; "/ln/b"]], "ret->nlink == 2"), [] + ]; + shortdesc = "create a hard link"; + longdesc = "\ +This command creates a hard link using the C<ln> command." }; + + { defaults with + name = "ln_f"; added = (1, 0, 66); + style = RErr, [String "target"; Pathname "linkname"], []; + proc_nr = Some 165; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir"; "/ln_f"]; + ["touch"; "/ln_f/a"]; + ["touch"; "/ln_f/b"]; + ["ln_f"; "/ln_f/a"; "/ln_f/b"]; + ["stat"; "/ln_f/b"]], "ret->nlink == 2"), [] + ]; + shortdesc = "create a hard link"; + longdesc = "\ +This command creates a hard link using the C<ln -f> command. +The I<-f> option removes the link (C<linkname>) if it exists already." }; + + { defaults with + name = "ln_s"; added = (1, 0, 66); + style = RErr, [String "target"; Pathname "linkname"], []; + proc_nr = Some 166; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir"; "/ln_s"]; + ["touch"; "/ln_s/a"]; + ["ln_s"; "a"; "/ln_s/b"]; + ["lstat"; "/ln_s/b"]], + "S_ISLNK (ret->mode) && (ret->mode & 0777) == 0777"), [] + ]; + shortdesc = "create a symbolic link"; + longdesc = "\ +This command creates a symbolic link using the C<ln -s> command." }; + + { defaults with + name = "ln_sf"; added = (1, 0, 66); + style = RErr, [String "target"; Pathname "linkname"], []; + proc_nr = Some 167; + tests = [ + InitScratchFS, Always, TestResultString ( + [["mkdir_p"; "/ln_sf/b"]; + ["touch"; "/ln_sf/b/c"]; + ["ln_sf"; "../d"; "/ln_sf/b/c"]; + ["readlink"; "/ln_sf/b/c"]], "../d"), [] + ]; + shortdesc = "create a symbolic link"; + longdesc = "\ +This command creates a symbolic link using the C<ln -sf> command, +The I<-f> option removes the link (C<linkname>) if it exists already." }; + + { defaults with + name = "readlink"; added = (1, 0, 66); + style = RString "link", [Pathname "path"], []; + proc_nr = Some 168; + shortdesc = "read the target of a symbolic link"; + longdesc = "\ +This command reads the target of a symbolic link." }; + + { defaults with + name = "swapon_device"; added = (1, 0, 66); + style = RErr, [Device "device"], []; + proc_nr = Some 170; + tests = [ + InitPartition, Always, TestRun ( + [["mkswap"; "/dev/sda1"; "NOARG"; "NOARG"]; + ["swapon_device"; "/dev/sda1"]; + ["swapoff_device"; "/dev/sda1"]]), [] + ]; + shortdesc = "enable swap on device"; + longdesc = "\ +This command enables the libguestfs appliance to use the +swap device or partition named C<device>. The increased +memory is made available for all commands, for example +those run using C<guestfs_command> or C<guestfs_sh>. + +Note that you should not swap to existing guest swap +partitions unless you know what you are doing. They may +contain hibernation information, or other information that +the guest doesn't want you to trash. You also risk leaking +information about the host to the guest this way. Instead, +attach a new host device to the guest and swap on that." }; + + { defaults with + name = "swapoff_device"; added = (1, 0, 66); + style = RErr, [Device "device"], []; + proc_nr = Some 171; + shortdesc = "disable swap on device"; + longdesc = "\ +This command disables the libguestfs appliance swap +device or partition named C<device>. +See C<guestfs_swapon_device>." }; + + { defaults with + name = "swapon_file"; added = (1, 0, 66); + style = RErr, [Pathname "file"], []; + proc_nr = Some 172; + tests = [ + InitScratchFS, Always, TestRun ( + [["fallocate"; "/swapon_file"; "8388608"]; + ["mkswap_file"; "/swapon_file"]; + ["swapon_file"; "/swapon_file"]; + ["swapoff_file"; "/swapon_file"]; + ["rm"; "/swapon_file"]]), [] + ]; + shortdesc = "enable swap on file"; + longdesc = "\ +This command enables swap to a file. +See C<guestfs_swapon_device> for other notes." }; + + { defaults with + name = "swapoff_file"; added = (1, 0, 66); + style = RErr, [Pathname "file"], []; + proc_nr = Some 173; + shortdesc = "disable swap on file"; + longdesc = "\ +This command disables the libguestfs appliance swap on file." }; + + { defaults with + name = "swapon_label"; added = (1, 0, 66); + style = RErr, [String "label"], []; + proc_nr = Some 174; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkswap"; "/dev/sda1"; "swapit"; "NOARG"]; + ["swapon_label"; "swapit"]; + ["swapoff_label"; "swapit"]; + ["zero"; "/dev/sda"]; + ["blockdev_rereadpt"; "/dev/sda"]]), [] + ]; + shortdesc = "enable swap on labeled swap partition"; + longdesc = "\ +This command enables swap to a labeled swap partition. +See C<guestfs_swapon_device> for other notes." }; + + { defaults with + name = "swapoff_label"; added = (1, 0, 66); + style = RErr, [String "label"], []; + proc_nr = Some 175; + shortdesc = "disable swap on labeled swap partition"; + longdesc = "\ +This command disables the libguestfs appliance swap on +labeled swap partition." }; + + { defaults with + name = "swapon_uuid"; added = (1, 0, 66); + style = RErr, [String "uuid"], []; + proc_nr = Some 176; + optional = Some "linuxfsuuid"; + tests = [ + InitEmpty, Always, TestRun ( + [["mkswap"; "/dev/sdc"; "NOARG"; stable_uuid]; + ["swapon_uuid"; stable_uuid]; + ["swapoff_uuid"; stable_uuid]]), [] + ]; + shortdesc = "enable swap on swap partition by UUID"; + longdesc = "\ +This command enables swap to a swap partition with the given UUID. +See C<guestfs_swapon_device> for other notes." }; + + { defaults with + name = "swapoff_uuid"; added = (1, 0, 66); + style = RErr, [String "uuid"], []; + proc_nr = Some 177; + optional = Some "linuxfsuuid"; + shortdesc = "disable swap on swap partition by UUID"; + longdesc = "\ +This command disables the libguestfs appliance swap partition +with the given UUID." }; + + { defaults with + name = "mkswap_file"; added = (1, 0, 66); + style = RErr, [Pathname "path"], []; + proc_nr = Some 178; + tests = [ + InitScratchFS, Always, TestRun ( + [["fallocate"; "/mkswap_file"; "8388608"]; + ["mkswap_file"; "/mkswap_file"]; + ["rm"; "/mkswap_file"]]), [] + ]; + shortdesc = "create a swap file"; + longdesc = "\ +Create a swap file. + +This command just writes a swap file signature to an existing +file. To create the file itself, use something like C<guestfs_fallocate>." }; + + { defaults with + name = "inotify_init"; added = (1, 0, 66); + style = RErr, [Int "maxevents"], []; + proc_nr = Some 179; + optional = Some "inotify"; + tests = [ + InitISOFS, Always, TestRun ( + [["inotify_init"; "0"]]), [] + ]; + shortdesc = "create an inotify handle"; + longdesc = "\ +This command creates a new inotify handle. +The inotify subsystem can be used to notify events which happen to +objects in the guest filesystem. + +C<maxevents> is the maximum number of events which will be +queued up between calls to C<guestfs_inotify_read> or +C<guestfs_inotify_files>. +If this is passed as C<0>, then the kernel (or previously set) +default is used. For Linux 2.6.29 the default was 16384 events. +Beyond this limit, the kernel throws away events, but records +the fact that it threw them away by setting a flag +C<IN_Q_OVERFLOW> in the returned structure list (see +C<guestfs_inotify_read>). + +Before any events are generated, you have to add some +watches to the internal watch list. See: C<guestfs_inotify_add_watch> and +C<guestfs_inotify_rm_watch>. + +Queued up events should be read periodically by calling +C<guestfs_inotify_read> +(or C<guestfs_inotify_files> which is just a helpful +wrapper around C<guestfs_inotify_read>). If you don't +read the events out often enough then you risk the internal +queue overflowing. + +The handle should be closed after use by calling +C<guestfs_inotify_close>. This also removes any +watches automatically. + +See also L<inotify(7)> for an overview of the inotify interface +as exposed by the Linux kernel, which is roughly what we expose +via libguestfs. Note that there is one global inotify handle +per libguestfs instance." }; + + { defaults with + name = "inotify_add_watch"; added = (1, 0, 66); + style = RInt64 "wd", [Pathname "path"; Int "mask"], []; + proc_nr = Some 180; + optional = Some "inotify"; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir"; "/inotify_add_watch"]; + ["inotify_init"; "0"]; + ["inotify_add_watch"; "/inotify_add_watch"; "4095"]; + ["touch"; "/inotify_add_watch/a"]; + ["touch"; "/inotify_add_watch/b"]; + ["inotify_files"]], + "is_string_list (ret, 2, \"a\", \"b\")"), [] + ]; + shortdesc = "add an inotify watch"; + longdesc = "\ +Watch C<path> for the events listed in C<mask>. + +Note that if C<path> is a directory then events within that +directory are watched, but this does I<not> happen recursively +(in subdirectories). + +Note for non-C or non-Linux callers: the inotify events are +defined by the Linux kernel ABI and are listed in +F</usr/include/sys/inotify.h>." }; + + { defaults with + name = "inotify_rm_watch"; added = (1, 0, 66); + style = RErr, [Int(*XXX64*) "wd"], []; + proc_nr = Some 181; + optional = Some "inotify"; + shortdesc = "remove an inotify watch"; + longdesc = "\ +Remove a previously defined inotify watch. +See C<guestfs_inotify_add_watch>." }; + + { defaults with + name = "inotify_read"; added = (1, 0, 66); + style = RStructList ("events", "inotify_event"), [], []; + proc_nr = Some 182; + optional = Some "inotify"; + shortdesc = "return list of inotify events"; + longdesc = "\ +Return the complete queue of events that have happened +since the previous read call. + +If no events have happened, this returns an empty list. + +I<Note>: In order to make sure that all events have been +read, you must call this function repeatedly until it +returns an empty list. The reason is that the call will +read events up to the maximum appliance-to-host message +size and leave remaining events in the queue." }; + + { defaults with + name = "inotify_files"; added = (1, 0, 66); + style = RStringList "paths", [], []; + proc_nr = Some 183; + optional = Some "inotify"; + shortdesc = "return list of watched files that had events"; + longdesc = "\ +This function is a helpful wrapper around C<guestfs_inotify_read> +which just returns a list of pathnames of objects that were +touched. The returned pathnames are sorted and deduplicated." }; + + { defaults with + name = "inotify_close"; added = (1, 0, 66); + style = RErr, [], []; + proc_nr = Some 184; + optional = Some "inotify"; + shortdesc = "close the inotify handle"; + longdesc = "\ +This closes the inotify handle which was previously +opened by inotify_init. It removes all watches, throws +away any pending events, and deallocates all resources." }; + + { defaults with + name = "modprobe"; added = (1, 0, 68); + style = RErr, [String "modulename"], []; + proc_nr = Some 194; + optional = Some "linuxmodules"; + tests = [ + InitNone, Always, TestRun [["modprobe"; "fat"]], [] + ]; + shortdesc = "load a kernel module"; + longdesc = "\ +This loads a kernel module in the appliance." }; + + { defaults with + name = "echo_daemon"; added = (1, 0, 69); + style = RString "output", [StringList "words"], []; + proc_nr = Some 195; + tests = [ + InitNone, Always, TestResultString ( + [["echo_daemon"; "This is a test"]], "This is a test"), []; + InitNone, Always, TestResultString ( + [["echo_daemon"; ""]], ""), []; + ]; + shortdesc = "echo arguments back to the client"; + longdesc = "\ +This command concatenates the list of C<words> passed with single spaces +between them and returns the resulting string. + +You can use this command to test the connection through to the daemon. + +See also C<guestfs_ping_daemon>." }; + + { defaults with + name = "find0"; added = (1, 0, 74); + style = RErr, [Pathname "directory"; FileOut "files"], []; + proc_nr = Some 196; + cancellable = true; + test_excuse = "there is a regression test for this"; + shortdesc = "find all files and directories, returning NUL-separated list"; + longdesc = "\ +This command lists out all files and directories, recursively, +starting at F<directory>, placing the resulting list in the +external file called F<files>. + +This command works the same way as C<guestfs_find> with the +following exceptions: + +=over 4 + +=item * + +The resulting list is written to an external file. + +=item * + +Items (filenames) in the result are separated +by C<\\0> characters. See L<find(1)> option I<-print0>. + +=item * + +The result list is not sorted. + +=back" }; + + { defaults with + name = "case_sensitive_path"; added = (1, 0, 75); + style = RString "rpath", [Pathname "path"], []; + proc_nr = Some 197; + tests = [ + InitISOFS, Always, TestResultString ( + [["case_sensitive_path"; "/DIRECTORY"]], "/directory"), []; + InitISOFS, Always, TestResultString ( + [["case_sensitive_path"; "/DIRECTORY/"]], "/directory"), []; + InitISOFS, Always, TestResultString ( + [["case_sensitive_path"; "/Known-1"]], "/known-1"), []; + InitISOFS, Always, TestLastFail ( + [["case_sensitive_path"; "/Known-1/"]]), []; + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/case_sensitive_path"]; + ["mkdir"; "/case_sensitive_path/bbb"]; + ["touch"; "/case_sensitive_path/bbb/c"]; + ["case_sensitive_path"; "/CASE_SENSITIVE_path/bbB/C"]], "/case_sensitive_path/bbb/c"), []; + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/case_sensitive_path2"]; + ["mkdir"; "/case_sensitive_path2/bbb"]; + ["touch"; "/case_sensitive_path2/bbb/c"]; + ["case_sensitive_path"; "/case_sensitive_PATH2////bbB/C"]], "/case_sensitive_path2/bbb/c"), []; + InitScratchFS, Always, TestLastFail ( + [["mkdir"; "/case_sensitive_path3"]; + ["mkdir"; "/case_sensitive_path3/bbb"]; + ["touch"; "/case_sensitive_path3/bbb/c"]; + ["case_sensitive_path"; "/case_SENSITIVE_path3/bbb/../bbb/C"]]), []; + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/case_sensitive_path4"]; + ["case_sensitive_path"; "/case_SENSITIVE_path4/new_file"]], "/case_sensitive_path4/new_file"), [] + ]; + shortdesc = "return true path on case-insensitive filesystem"; + longdesc = "\ +This can be used to resolve case insensitive paths on +a filesystem which is case sensitive. The use case is +to resolve paths which you have read from Windows configuration +files or the Windows Registry, to the true path. + +The command handles a peculiarity of the Linux ntfs-3g +filesystem driver (and probably others), which is that although +the underlying filesystem is case-insensitive, the driver +exports the filesystem to Linux as case-sensitive. + +One consequence of this is that special directories such +as F<C:\\windows> may appear as F</WINDOWS> or F</windows> +(or other things) depending on the precise details of how +they were created. In Windows itself this would not be +a problem. + +Bug or feature? You decide: +L<http://www.tuxera.com/community/ntfs-3g-faq/#posixfilenames1> + +C<guestfs_case_sensitive_path> attempts to resolve the true case of +each element in the path. It will return a resolved path if either the +full path or its parent directory exists. If the parent directory +exists but the full path does not, the case of the parent directory +will be correctly resolved, and the remainder appended unmodified. For +example, if the file C<\"/Windows/System32/netkvm.sys\"> exists: + +=over 4 + +=item C<guestfs_case_sensitive_path> (\"/windows/system32/netkvm.sys\") + +\"Windows/System32/netkvm.sys\" + +=item C<guestfs_case_sensitive_path> (\"/windows/system32/NoSuchFile\") + +\"Windows/System32/NoSuchFile\" + +=item C<guestfs_case_sensitive_path> (\"/windows/system33/netkvm.sys\") + +I<ERROR> + +=back + +I<Note>: +Because of the above behaviour, C<guestfs_case_sensitive_path> cannot +be used to check for the existence of a file. + +I<Note>: +This function does not handle drive names, backslashes etc. + +See also C<guestfs_realpath>." }; + + { defaults with + name = "vfs_type"; added = (1, 0, 75); + style = RString "fstype", [Mountable "mountable"], []; + proc_nr = Some 198; + tests = [ + InitScratchFS, Always, TestResultString ( + [["vfs_type"; "/dev/sdb1"]], "ext2"), [] + ]; + shortdesc = "get the Linux VFS type corresponding to a mounted device"; + longdesc = "\ +This command gets the filesystem type corresponding to +the filesystem on C<mountable>. + +For most filesystems, the result is the name of the Linux +VFS module which would be used to mount this filesystem +if you mounted it without specifying the filesystem type. +For example a string such as C<ext3> or C<ntfs>." }; + + { defaults with + name = "truncate"; added = (1, 0, 77); + style = RErr, [Pathname "path"], []; + proc_nr = Some 199; + tests = [ + InitScratchFS, Always, TestResult ( + [["write"; "/truncate"; "some stuff so size is not zero"]; + ["truncate"; "/truncate"]; + ["stat"; "/truncate"]], "ret->size == 0"), [] + ]; + shortdesc = "truncate a file to zero size"; + longdesc = "\ +This command truncates C<path> to a zero-length file. The +file must exist already." }; + + { defaults with + name = "truncate_size"; added = (1, 0, 77); + style = RErr, [Pathname "path"; Int64 "size"], []; + proc_nr = Some 200; + tests = [ + InitScratchFS, Always, TestResult ( + [["touch"; "/truncate_size"]; + ["truncate_size"; "/truncate_size"; "1000"]; + ["stat"; "/truncate_size"]], "ret->size == 1000"), [] + ]; + shortdesc = "truncate a file to a particular size"; + longdesc = "\ +This command truncates C<path> to size C<size> bytes. The file +must exist already. + +If the current file size is less than C<size> then +the file is extended to the required size with zero bytes. +This creates a sparse file (ie. disk blocks are not allocated +for the file until you write to it). To create a non-sparse +file of zeroes, use C<guestfs_fallocate64> instead." }; + + { defaults with + name = "utimens"; added = (1, 0, 77); + style = RErr, [Pathname "path"; Int64 "atsecs"; Int64 "atnsecs"; Int64 "mtsecs"; Int64 "mtnsecs"], []; + proc_nr = Some 201; + (* Test directories, named pipes etc (RHBZ#761451, RHBZ#761460) *) + tests = [ + InitScratchFS, Always, TestResult ( + [["touch"; "/utimens-file"]; + ["utimens"; "/utimens-file"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-file"]], "ret->mtime == 9876"), []; + InitScratchFS, Always, TestResult ( + [["mkdir"; "/utimens-dir"]; + ["utimens"; "/utimens-dir"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-dir"]], "ret->mtime == 9876"), []; + InitScratchFS, Always, TestResult ( + [["mkfifo"; "0o644"; "/utimens-fifo"]; + ["utimens"; "/utimens-fifo"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-fifo"]], "ret->mtime == 9876"), []; + InitScratchFS, Always, TestResult ( + [["ln_sf"; "/utimens-file"; "/utimens-link"]; + ["utimens"; "/utimens-link"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-link"]], "ret->mtime == 9876"), []; + InitScratchFS, Always, TestResult ( + [["mknod_b"; "0o644"; "8"; "0"; "/utimens-block"]; + ["utimens"; "/utimens-block"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-block"]], "ret->mtime == 9876"), []; + InitScratchFS, Always, TestResult ( + [["mknod_c"; "0o644"; "1"; "3"; "/utimens-char"]; + ["utimens"; "/utimens-char"; "12345"; "67890"; "9876"; "5432"]; + ["stat"; "/utimens-char"]], "ret->mtime == 9876"), [] + ]; + shortdesc = "set timestamp of a file with nanosecond precision"; + longdesc = "\ +This command sets the timestamps of a file with nanosecond +precision. + +C<atsecs, atnsecs> are the last access time (atime) in secs and +nanoseconds from the epoch. + +C<mtsecs, mtnsecs> are the last modification time (mtime) in +secs and nanoseconds from the epoch. + +If the C<*nsecs> field contains the special value C<-1> then +the corresponding timestamp is set to the current time. (The +C<*secs> field is ignored in this case). + +If the C<*nsecs> field contains the special value C<-2> then +the corresponding timestamp is left unchanged. (The +C<*secs> field is ignored in this case)." }; + + { defaults with + name = "mkdir_mode"; added = (1, 0, 77); + style = RErr, [Pathname "path"; Int "mode"], []; + proc_nr = Some 202; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir_mode"; "/mkdir_mode"; "0o111"]; + ["stat"; "/mkdir_mode"]], + "S_ISDIR (ret->mode) && (ret->mode & 0777) == 0111"), [] + ]; + shortdesc = "create a directory with a particular mode"; + longdesc = "\ +This command creates a directory, setting the initial permissions +of the directory to C<mode>. + +For common Linux filesystems, the actual mode which is set will +be C<mode & ~umask & 01777>. Non-native-Linux filesystems may +interpret the mode in other ways. + +See also C<guestfs_mkdir>, C<guestfs_umask>" }; + + { defaults with + name = "lchown"; added = (1, 0, 77); + style = RErr, [Int "owner"; Int "group"; Pathname "path"], []; + proc_nr = Some 203; + shortdesc = "change file owner and group"; + longdesc = "\ +Change the file owner to C<owner> and group to C<group>. +This is like C<guestfs_chown> but if C<path> is a symlink then +the link itself is changed, not the target. + +Only numeric uid and gid are supported. If you want to use +names, you will need to locate and parse the password file +yourself (Augeas support makes this relatively easy)." }; + + { defaults with + name = "internal_lxattrlist"; added = (1, 19, 32); + style = RStructList ("xattrs", "xattr"), [Pathname "path"; FilenameList "names"], []; + proc_nr = Some 205; + visibility = VInternal; + 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<path>. +C<names> 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<attrname>. C<attrval> in this struct is zero-length +to indicate there was an error doing C<lgetxattr> for this +file, I<or> 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<guestfs_lstatlist> for a similarly efficient call +for getting standard stats. Very long directory listings +might cause the protocol message size to be exceeded, causing +this call to fail. The caller must split up such requests +into smaller groups of names." }; + + { defaults with + name = "internal_readlinklist"; added = (1, 19, 32); + style = RStringList "links", [Pathname "path"; FilenameList "names"], []; + proc_nr = Some 206; + visibility = VInternal; + shortdesc = "readlink on multiple files"; + longdesc = "\ +This call allows you to do a C<readlink> operation +on multiple files, where all files are in the directory C<path>. +C<names> 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<names> list. Each string is the +value of the symbolic link. + +If the L<readlink(2)> 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 L<readlink(2)> 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. +Very long directory listings might cause the protocol +message size to be exceeded, causing +this call to fail. The caller must split up such requests +into smaller groups of names." }; + + { defaults with + name = "pread"; added = (1, 0, 77); + style = RBufferOut "content", [Pathname "path"; Int "count"; Int64 "offset"], []; + proc_nr = Some 207; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResult ( + [["pread"; "/known-4"; "1"; "3"]], + "compare_buffers (ret, size, \"\\n\", 1) == 0"), []; + InitISOFS, Always, TestResult ( + [["pread"; "/empty"; "0"; "100"]], + "compare_buffers (ret, size, NULL, 0) == 0"), [] + ]; + shortdesc = "read part of a file"; + longdesc = "\ +This command lets you read part of a file. It reads C<count> +bytes of the file, starting at C<offset>, from file C<path>. + +This may read fewer bytes than requested. For further details +see the L<pread(2)> system call. + +See also C<guestfs_pwrite>, C<guestfs_pread_device>." }; + + { defaults with + name = "part_init"; added = (1, 0, 78); + style = RErr, [Device "device"; String "parttype"], []; + proc_nr = Some 208; + tests = [ + InitEmpty, Always, TestRun ( + [["part_init"; "/dev/sda"; "gpt"]]), [] + ]; + shortdesc = "create an empty partition table"; + longdesc = "\ +This creates an empty partition table on C<device> of one of the +partition types listed below. Usually C<parttype> should be +either C<msdos> or C<gpt> (for large disks). + +Initially there are no partitions. Following this, you should +call C<guestfs_part_add> for each partition required. + +Possible values for C<parttype> are: + +=over 4 + +=item B<efi> + +=item B<gpt> + +Intel EFI / GPT partition table. + +This is recommended for >= 2 TB partitions that will be accessed +from Linux and Intel-based Mac OS X. It also has limited backwards +compatibility with the C<mbr> format. + +=item B<mbr> + +=item B<msdos> + +The standard PC \"Master Boot Record\" (MBR) format used +by MS-DOS and Windows. This partition type will B<only> work +for device sizes up to 2 TB. For large disks we recommend +using C<gpt>. + +=back + +Other partition table types that may work but are not +supported include: + +=over 4 + +=item B<aix> + +AIX disk labels. + +=item B<amiga> + +=item B<rdb> + +Amiga \"Rigid Disk Block\" format. + +=item B<bsd> + +BSD disk labels. + +=item B<dasd> + +DASD, used on IBM mainframes. + +=item B<dvh> + +MIPS/SGI volumes. + +=item B<mac> + +Old Mac partition format. Modern Macs use C<gpt>. + +=item B<pc98> + +NEC PC-98 format, common in Japan apparently. + +=item B<sun> + +Sun disk labels. + +=back" }; + + { defaults with + name = "part_add"; added = (1, 0, 78); + style = RErr, [Device "device"; String "prlogex"; Int64 "startsect"; Int64 "endsect"], []; + proc_nr = Some 209; + tests = [ + InitEmpty, Always, TestRun ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]]), []; + InitEmpty, Always, TestRun ( + [["part_init"; "/dev/sda"; "gpt"]; + ["part_add"; "/dev/sda"; "primary"; "34"; "127"]; + ["part_add"; "/dev/sda"; "primary"; "128"; "-34"]]), []; + InitEmpty, Always, TestRun ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "primary"; "32"; "127"]; + ["part_add"; "/dev/sda"; "primary"; "128"; "255"]; + ["part_add"; "/dev/sda"; "primary"; "256"; "511"]; + ["part_add"; "/dev/sda"; "primary"; "512"; "-1"]]), [] + ]; + shortdesc = "add a partition to the device"; + longdesc = "\ +This command adds a partition to C<device>. If there is no partition +table on the device, call C<guestfs_part_init> first. + +The C<prlogex> parameter is the type of partition. Normally you +should pass C<p> or C<primary> here, but MBR partition tables also +support C<l> (or C<logical>) and C<e> (or C<extended>) partition +types. + +C<startsect> and C<endsect> are the start and end of the partition +in I<sectors>. C<endsect> may be negative, which means it counts +backwards from the end of the disk (C<-1> is the last sector). + +Creating a partition which covers the whole disk is not so easy. +Use C<guestfs_part_disk> to do that." }; + + { defaults with + name = "part_disk"; added = (1, 0, 78); + style = RErr, [Device "device"; String "parttype"], []; + proc_nr = Some 210; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]]), []; + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "gpt"]]), [] + ]; + shortdesc = "partition whole disk with a single primary partition"; + longdesc = "\ +This command is simply a combination of C<guestfs_part_init> +followed by C<guestfs_part_add> to create a single primary partition +covering the whole disk. + +C<parttype> is the partition table type, usually C<mbr> or C<gpt>, +but other possible values are described in C<guestfs_part_init>." }; + + { defaults with + name = "part_set_bootable"; added = (1, 0, 78); + style = RErr, [Device "device"; Int "partnum"; Bool "bootable"], []; + proc_nr = Some 211; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["part_set_bootable"; "/dev/sda"; "1"; "true"]]), [] + ]; + shortdesc = "make a partition bootable"; + longdesc = "\ +This sets the bootable flag on partition numbered C<partnum> on +device C<device>. Note that partitions are numbered from 1. + +The bootable flag is used by some operating systems (notably +Windows) to determine which partition to boot from. It is by +no means universally recognized." }; + + { defaults with + name = "part_set_name"; added = (1, 0, 78); + style = RErr, [Device "device"; Int "partnum"; String "name"], []; + proc_nr = Some 212; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "gpt"]; + ["part_set_name"; "/dev/sda"; "1"; "thepartname"]]), [] + ]; + shortdesc = "set partition name"; + longdesc = "\ +This sets the partition name on partition numbered C<partnum> on +device C<device>. Note that partitions are numbered from 1. + +The partition name can only be set on certain types of partition +table. This works on C<gpt> but not on C<mbr> partitions." }; + + { defaults with + name = "part_list"; added = (1, 0, 78); + style = RStructList ("partitions", "partition"), [Device "device"], []; + proc_nr = Some 213; + tests = [] (* XXX Add a regression test for this. *); + shortdesc = "list partitions on a device"; + longdesc = "\ +This command parses the partition table on C<device> and +returns the list of partitions found. + +The fields in the returned structure are: + +=over 4 + +=item B<part_num> + +Partition number, counting from 1. + +=item B<part_start> + +Start of the partition I<in bytes>. To get sectors you have to +divide by the device's sector size, see C<guestfs_blockdev_getss>. + +=item B<part_end> + +End of the partition in bytes. + +=item B<part_size> + +Size of the partition in bytes. + +=back" }; + + { defaults with + name = "part_get_parttype"; added = (1, 0, 78); + style = RString "parttype", [Device "device"], []; + proc_nr = Some 214; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "gpt"]; + ["part_get_parttype"; "/dev/sda"]], "gpt"), [] + ]; + shortdesc = "get the partition table type"; + longdesc = "\ +This command examines the partition table on C<device> and +returns the partition table type (format) being used. + +Common return values include: C<msdos> (a DOS/Windows style MBR +partition table), C<gpt> (a GPT/EFI-style partition table). Other +values are possible, although unusual. See C<guestfs_part_init> +for a full list." }; + + { defaults with + name = "fill"; added = (1, 0, 79); + style = RErr, [Int "c"; Int "len"; Pathname "path"], []; + proc_nr = Some 215; + progress = true; + tests = [ + InitScratchFS, Always, TestResult ( + [["fill"; "0x63"; "10"; "/fill"]; + ["read_file"; "/fill"]], + "compare_buffers (ret, size, \"cccccccccc\", 10) == 0"), [] + ]; + shortdesc = "fill a file with octets"; + longdesc = "\ +This command creates a new file called C<path>. The initial +content of the file is C<len> octets of C<c>, where C<c> +must be a number in the range C<[0..255]>. + +To fill a file with zero bytes (sparsely), it is +much more efficient to use C<guestfs_truncate_size>. +To create a file with a pattern of repeating bytes +use C<guestfs_fill_pattern>." }; + + { defaults with + name = "filesize"; added = (1, 0, 82); + style = RInt64 "size", [Pathname "file"], []; + proc_nr = Some 218; + tests = [ + InitScratchFS, Always, TestResult ( + [["write"; "/filesize"; "hello, world"]; + ["filesize"; "/filesize"]], "ret == 12"), [] + ]; + shortdesc = "return the size of the file in bytes"; + longdesc = "\ +This command returns the size of F<file> in bytes. + +To get other stats about a file, use C<guestfs_stat>, C<guestfs_lstat>, +C<guestfs_is_dir>, C<guestfs_is_file> etc. +To get the size of block devices, use C<guestfs_blockdev_getsize64>." }; + + { defaults with + name = "lvrename"; added = (1, 0, 83); + style = RErr, [String "logvol"; String "newlogvol"], []; + proc_nr = Some 219; + tests = [ + InitBasicFSonLVM, Always, TestResult ( + [["lvrename"; "/dev/VG/LV"; "/dev/VG/LV2"]; + ["lvs"]], + "is_string_list (ret, 1, \"/dev/VG/LV2\")"), [] + ]; + shortdesc = "rename an LVM logical volume"; + longdesc = "\ +Rename a logical volume C<logvol> with the new name C<newlogvol>." }; + + { defaults with + name = "vgrename"; added = (1, 0, 83); + style = RErr, [String "volgroup"; String "newvolgroup"], []; + proc_nr = Some 220; + tests = [ + InitBasicFSonLVM, Always, TestResult ( + [["umount"; "/"; "false"; "false"]; + ["vg_activate"; "false"; "VG"]; + ["vgrename"; "VG"; "VG2"]; + ["vg_activate"; "true"; "VG2"]; + ["mount"; "/dev/VG2/LV"; "/"]; + ["vgs"]], + "is_string_list (ret, 1, \"VG2\")"), [] + ]; + shortdesc = "rename an LVM volume group"; + longdesc = "\ +Rename a volume group C<volgroup> with the new name C<newvolgroup>." }; + + { defaults with + name = "initrd_cat"; added = (1, 0, 84); + style = RBufferOut "content", [Pathname "initrdpath"; String "filename"], []; + proc_nr = Some 221; + protocol_limit_warning = true; + tests = [ + InitISOFS, Always, TestResult ( + [["initrd_cat"; "/initrd"; "known-4"]], + "compare_buffers (ret, size, \"abc\\ndef\\nghi\", 11) == 0"), [] + ]; + shortdesc = "list the contents of a single file in an initrd"; + longdesc = "\ +This command unpacks the file F<filename> from the initrd file +called F<initrdpath>. The filename must be given I<without> the +initial F</> character. + +For example, in guestfish you could use the following command +to examine the boot script (usually called F</init>) +contained in a Linux initrd or initramfs image: + + initrd-cat /boot/initrd-<version>.img init + +See also C<guestfs_initrd_list>." }; + + { defaults with + name = "pvuuid"; added = (1, 0, 87); + style = RString "uuid", [Device "device"], []; + proc_nr = Some 222; + shortdesc = "get the UUID of a physical volume"; + longdesc = "\ +This command returns the UUID of the LVM PV C<device>." }; + + { defaults with + name = "vguuid"; added = (1, 0, 87); + style = RString "uuid", [String "vgname"], []; + proc_nr = Some 223; + shortdesc = "get the UUID of a volume group"; + longdesc = "\ +This command returns the UUID of the LVM VG named C<vgname>." }; + + { defaults with + name = "lvuuid"; added = (1, 0, 87); + style = RString "uuid", [Device "device"], []; + proc_nr = Some 224; + shortdesc = "get the UUID of a logical volume"; + longdesc = "\ +This command returns the UUID of the LVM LV C<device>." }; + + { defaults with + name = "vgpvuuids"; added = (1, 0, 87); + style = RStringList "uuids", [String "vgname"], []; + proc_nr = Some 225; + shortdesc = "get the PV UUIDs containing the volume group"; + longdesc = "\ +Given a VG called C<vgname>, this returns the UUIDs of all +the physical volumes that this volume group resides on. + +You can use this along with C<guestfs_pvs> and C<guestfs_pvuuid> +calls to associate physical volumes and volume groups. + +See also C<guestfs_vglvuuids>." }; + + { defaults with + name = "vglvuuids"; added = (1, 0, 87); + style = RStringList "uuids", [String "vgname"], []; + proc_nr = Some 226; + shortdesc = "get the LV UUIDs of all LVs in the volume group"; + longdesc = "\ +Given a VG called C<vgname>, this returns the UUIDs of all +the logical volumes created in this volume group. + +You can use this along with C<guestfs_lvs> and C<guestfs_lvuuid> +calls to associate logical volumes and volume groups. + +See also C<guestfs_vgpvuuids>." }; + + { defaults with + name = "copy_size"; added = (1, 0, 87); + style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"], []; + proc_nr = Some 227; + progress = true; deprecated_by = Some "copy_device_to_device"; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir"; "/copy_size"]; + ["write"; "/copy_size/src"; "hello, world"]; + ["copy_size"; "/copy_size/src"; "/copy_size/dest"; "5"]; + ["read_file"; "/copy_size/dest"]], + "compare_buffers (ret, size, \"hello\", 5) == 0"), [] + ]; + shortdesc = "copy size bytes from source to destination using dd"; + longdesc = "\ +This command copies exactly C<size> bytes from one source device +or file C<src> to another destination device or file C<dest>. + +Note this will fail if the source is too short or if the destination +is not large enough." }; + + { defaults with + name = "zero_device"; added = (1, 3, 1); + style = RErr, [Device "device"], []; + proc_nr = Some 228; + progress = true; + tests = [ + InitBasicFSonLVM, Always, TestRun ( + [["zero_device"; "/dev/VG/LV"]]), [] + ]; + shortdesc = "write zeroes to an entire device"; + longdesc = "\ +This command writes zeroes over the entire C<device>. Compare +with C<guestfs_zero> which just zeroes the first few blocks of +a device. + +If blocks are already zero, then this command avoids writing +zeroes. This prevents the underlying device from becoming non-sparse +or growing unnecessarily." }; + + { defaults with + name = "vgscan"; added = (1, 3, 2); + style = RErr, [], []; + proc_nr = Some 232; + tests = [ + InitEmpty, Always, TestRun ( + [["vgscan"]]), [] + ]; + shortdesc = "rescan for LVM physical volumes, volume groups and logical volumes"; + longdesc = "\ +This rescans all block devices and rebuilds the list of LVM +physical volumes, volume groups and logical volumes." }; + + { defaults with + name = "part_del"; added = (1, 3, 2); + style = RErr, [Device "device"; Int "partnum"], []; + proc_nr = Some 233; + tests = [ + InitEmpty, Always, TestRun ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]; + ["part_del"; "/dev/sda"; "1"]]), [] + ]; + shortdesc = "delete a partition"; + longdesc = "\ +This command deletes the partition numbered C<partnum> on C<device>. + +Note that in the case of MBR partitioning, deleting an +extended partition also deletes any logical partitions +it contains." }; + + { defaults with + name = "part_get_bootable"; added = (1, 3, 2); + style = RBool "bootable", [Device "device"; Int "partnum"], []; + proc_nr = Some 234; + tests = [ + InitEmpty, Always, TestResultTrue ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]; + ["part_set_bootable"; "/dev/sda"; "1"; "true"]; + ["part_get_bootable"; "/dev/sda"; "1"]]), [] + ]; + shortdesc = "return true if a partition is bootable"; + longdesc = "\ +This command returns true if the partition C<partnum> on +C<device> has the bootable flag set. + +See also C<guestfs_part_set_bootable>." }; + + { defaults with + name = "part_get_mbr_id"; added = (1, 3, 2); + style = RInt "idbyte", [Device "device"; Int "partnum"], []; + proc_nr = Some 235; + fish_output = Some FishOutputHexadecimal; + tests = [ + InitEmpty, Always, TestResult ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "primary"; "1"; "-1"]; + ["part_set_mbr_id"; "/dev/sda"; "1"; "0x7f"]; + ["part_get_mbr_id"; "/dev/sda"; "1"]], "ret == 0x7f"), [] + ]; + shortdesc = "get the MBR type byte (ID byte) from a partition"; + longdesc = "\ +Returns the MBR type byte (also known as the ID byte) from +the numbered partition C<partnum>. + +Note that only MBR (old DOS-style) partitions have type bytes. +You will get undefined results for other partition table +types (see C<guestfs_part_get_parttype>)." }; + + { defaults with + name = "part_set_mbr_id"; added = (1, 3, 2); + style = RErr, [Device "device"; Int "partnum"; Int "idbyte"], []; + proc_nr = Some 236; + shortdesc = "set the MBR type byte (ID byte) of a partition"; + longdesc = "\ +Sets the MBR type byte (also known as the ID byte) of +the numbered partition C<partnum> to C<idbyte>. Note +that the type bytes quoted in most documentation are +in fact hexadecimal numbers, but usually documented +without any leading \"0x\" which might be confusing. + +Note that only MBR (old DOS-style) partitions have type bytes. +You will get undefined results for other partition table +types (see C<guestfs_part_get_parttype>)." }; + + { defaults with + name = "checksum_device"; added = (1, 3, 2); + style = RString "checksum", [String "csumtype"; Device "device"], []; + proc_nr = Some 237; + tests = [ + InitISOFS, Always, TestResult ( + [["checksum_device"; "md5"; "/dev/sdd"]], + "check_file_md5 (ret, \"../../test-data/test.iso\") == 0"), [] + ]; + shortdesc = "compute MD5, SHAx or CRC checksum of the contents of a device"; + longdesc = "\ +This call computes the MD5, SHAx or CRC checksum of the +contents of the device named C<device>. For the types of +checksums supported see the C<guestfs_checksum> command." }; + + { defaults with + name = "lvresize_free"; added = (1, 3, 3); + style = RErr, [Device "lv"; Int "percent"], []; + proc_nr = Some 238; + optional = Some "lvm2"; + tests = [ + InitNone, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV"; "VG"; "10"]; + ["lvresize_free"; "/dev/VG/LV"; "100"]]), [] + ]; + shortdesc = "expand an LV to fill free space"; + longdesc = "\ +This expands an existing logical volume C<lv> so that it fills +C<pc>% of the remaining free space in the volume group. Commonly +you would call this with pc = 100 which expands the logical volume +as much as possible, using all remaining free space in the volume +group." }; + + { defaults with + name = "get_umask"; added = (1, 3, 4); + style = RInt "mask", [], []; + proc_nr = Some 240; + fish_output = Some FishOutputOctal; + tests = [ + InitEmpty, Always, TestResult ( + [["get_umask"]], "ret == 022"), [] + ]; + shortdesc = "get the current umask"; + longdesc = "\ +Return the current umask. By default the umask is C<022> +unless it has been set by calling C<guestfs_umask>." }; + + { defaults with + name = "base64_in"; added = (1, 3, 5); + style = RErr, [FileIn "base64file"; Pathname "filename"], []; + proc_nr = Some 242; + cancellable = true; + tests = [ + InitScratchFS, Always, TestResultString ( + [["base64_in"; "../../test-data/files/hello.b64"; "/base64_in"]; + ["cat"; "/base64_in"]], "hello\n"), [] + ]; + shortdesc = "upload base64-encoded data to file"; + longdesc = "\ +This command uploads base64-encoded data from C<base64file> +to F<filename>." }; + + { defaults with + name = "base64_out"; added = (1, 3, 5); + style = RErr, [Pathname "filename"; FileOut "base64file"], []; + proc_nr = Some 243; + cancellable = true; + shortdesc = "download file and encode as base64"; + longdesc = "\ +This command downloads the contents of F<filename>, writing +it out to local file C<base64file> encoded as base64." }; + + { defaults with + name = "checksums_out"; added = (1, 3, 7); + style = RErr, [String "csumtype"; Pathname "directory"; FileOut "sumsfile"], []; + proc_nr = Some 244; + cancellable = true; + shortdesc = "compute MD5, SHAx or CRC checksum of files in a directory"; + longdesc = "\ +This command computes the checksums of all regular files in +F<directory> and then emits a list of those checksums to +the local output file C<sumsfile>. + +This can be used for verifying the integrity of a virtual +machine. However to be properly secure you should pay +attention to the output of the checksum command (it uses +the ones from GNU coreutils). In particular when the +filename is not printable, coreutils uses a special +backslash syntax. For more information, see the GNU +coreutils info file." }; + + { defaults with + name = "fill_pattern"; added = (1, 3, 12); + style = RErr, [String "pattern"; Int "len"; Pathname "path"], []; + proc_nr = Some 245; + progress = true; + tests = [ + InitScratchFS, Always, TestResult ( + [["fill_pattern"; "abcdefghijklmnopqrstuvwxyz"; "28"; "/fill_pattern"]; + ["read_file"; "/fill_pattern"]], + "compare_buffers (ret, size, \"abcdefghijklmnopqrstuvwxyzab\", 28) == 0"), [] + ]; + shortdesc = "fill a file with a repeating pattern of bytes"; + longdesc = "\ +This function is like C<guestfs_fill> except that it creates +a new file of length C<len> containing the repeating pattern +of bytes in C<pattern>. The pattern is truncated if necessary +to ensure the length of the file is exactly C<len> bytes." }; + + { defaults with + name = "internal_write"; added = (1, 19, 32); + style = RErr, [Pathname "path"; BufferIn "content"], []; + proc_nr = Some 246; + visibility = VInternal; + protocol_limit_warning = true; + tests = [ + InitScratchFS, Always, TestResultString ( + [["internal_write"; "/internal_write"; "new file contents"]; + ["cat"; "/internal_write"]], "new file contents"), []; + InitScratchFS, Always, TestResultString ( + [["internal_write"; "/internal_write2"; "\nnew file contents\n"]; + ["cat"; "/internal_write2"]], "\nnew file contents\n"), []; + InitScratchFS, Always, TestResultString ( + [["internal_write"; "/internal_write3"; "\n\n"]; + ["cat"; "/internal_write3"]], "\n\n"), []; + InitScratchFS, Always, TestResultString ( + [["internal_write"; "/internal_write4"; ""]; + ["cat"; "/internal_write4"]], ""), []; + InitScratchFS, Always, TestResultString ( + [["internal_write"; "/internal_write5"; "\n\n\n"]; + ["cat"; "/internal_write5"]], "\n\n\n"), []; + InitScratchFS, Always, TestResultString ( + [["internal_write"; "/internal_write6"; "\n"]; + ["cat"; "/internal_write6"]], "\n"), [] + ]; + shortdesc = "create a new file"; + longdesc = "\ +This call creates a file called C<path>. The content of the +file is the string C<content> (which can contain any 8 bit data). + +See also C<guestfs_write_append>." }; + + { defaults with + name = "pwrite"; added = (1, 3, 14); + style = RInt "nbytes", [Pathname "path"; BufferIn "content"; Int64 "offset"], []; + proc_nr = Some 247; + protocol_limit_warning = true; + tests = [ + InitScratchFS, Always, TestResultString ( + [["write"; "/pwrite"; "new file contents"]; + ["pwrite"; "/pwrite"; "data"; "4"]; + ["cat"; "/pwrite"]], "new data contents"), []; + InitScratchFS, Always, TestResultString ( + [["write"; "/pwrite2"; "new file contents"]; + ["pwrite"; "/pwrite2"; "is extended"; "9"]; + ["cat"; "/pwrite2"]], "new file is extended"), []; + InitScratchFS, Always, TestResultString ( + [["write"; "/pwrite3"; "new file contents"]; + ["pwrite"; "/pwrite3"; ""; "4"]; + ["cat"; "/pwrite3"]], "new file contents"), [] + ]; + shortdesc = "write to part of a file"; + longdesc = "\ +This command writes to part of a file. It writes the data +buffer C<content> to the file C<path> starting at offset C<offset>. + +This command implements the L<pwrite(2)> system call, and like +that system call it may not write the full data requested. The +return value is the number of bytes that were actually written +to the file. This could even be 0, although short writes are +unlikely for regular files in ordinary circumstances. + +See also C<guestfs_pread>, C<guestfs_pwrite_device>." }; + + { defaults with + name = "resize2fs_size"; added = (1, 3, 14); + style = RErr, [Device "device"; Int64 "size"], []; + proc_nr = Some 248; + shortdesc = "resize an ext2, ext3 or ext4 filesystem (with size)"; + longdesc = "\ +This command is the same as C<guestfs_resize2fs> except that it +allows you to specify the new size (in bytes) explicitly. + +See also L<guestfs(3)/RESIZE2FS ERRORS>." }; + + { defaults with + name = "pvresize_size"; added = (1, 3, 14); + style = RErr, [Device "device"; Int64 "size"], []; + proc_nr = Some 249; + optional = Some "lvm2"; + shortdesc = "resize an LVM physical volume (with size)"; + longdesc = "\ +This command is the same as C<guestfs_pvresize> except that it +allows you to specify the new size (in bytes) explicitly." }; + + { defaults with + name = "ntfsresize_size"; added = (1, 3, 14); + style = RErr, [Device "device"; Int64 "size"], []; + proc_nr = Some 250; + optional = Some "ntfsprogs"; deprecated_by = Some "ntfsresize"; + shortdesc = "resize an NTFS filesystem (with size)"; + longdesc = "\ +This command is the same as C<guestfs_ntfsresize> except that it +allows you to specify the new size (in bytes) explicitly." }; + + { defaults with + name = "available_all_groups"; added = (1, 3, 15); + style = RStringList "groups", [], []; + proc_nr = Some 251; + tests = [ + InitNone, Always, TestRun [["available_all_groups"]], [] + ]; + shortdesc = "return a list of all optional groups"; + longdesc = "\ +This command returns a list of all optional groups that this +daemon knows about. Note this returns both supported and unsupported +groups. To find out which ones the daemon can actually support +you have to call C<guestfs_available> / C<guestfs_feature_available> +on each member of the returned list. + +See also C<guestfs_available>, C<guestfs_feature_available> +and L<guestfs(3)/AVAILABILITY>." }; + + { defaults with + name = "fallocate64"; added = (1, 3, 17); + style = RErr, [Pathname "path"; Int64 "len"], []; + proc_nr = Some 252; + tests = [ + InitScratchFS, Always, TestResult ( + [["fallocate64"; "/fallocate64"; "1000000"]; + ["stat"; "/fallocate64"]], "ret->size == 1000000"), [] + ]; + shortdesc = "preallocate a file in the guest filesystem"; + longdesc = "\ +This command preallocates a file (containing zero bytes) named +C<path> of size C<len> bytes. If the file exists already, it +is overwritten. + +Note that this call allocates disk blocks for the file. +To create a sparse file use C<guestfs_truncate_size> instead. + +The deprecated call C<guestfs_fallocate> does the same, +but owing to an oversight it only allowed 30 bit lengths +to be specified, effectively limiting the maximum size +of files created through that call to 1GB. + +Do not confuse this with the guestfish-specific +C<alloc> and C<sparse> commands which create +a file in the host and attach it as a device." }; + + { defaults with + name = "vfs_label"; added = (1, 3, 18); + style = RString "label", [Mountable "mountable"], []; + proc_nr = Some 253; + tests = [ + InitBasicFS, Always, TestResultString ( + [["set_label"; "/dev/sda1"; "LTEST"]; + ["vfs_label"; "/dev/sda1"]], "LTEST"), []; + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "test-label"]; + ["vfs_label"; "/dev/sda1"]], "test-label"), []; + InitEmpty, IfAvailable "btrfs", TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "btrfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; ""]; + ["set_label"; "/dev/sda1"; "test-label-btrfs"]; + ["vfs_label"; "/dev/sda1"]], "test-label-btrfs"), []; + ]; + shortdesc = "get the filesystem label"; + longdesc = "\ +This returns the label of the filesystem on C<mountable>. + +If the filesystem is unlabeled, this returns the empty string. + +To find a filesystem from the label, use C<guestfs_findfs_label>." }; + + { defaults with + name = "vfs_uuid"; added = (1, 3, 18); + style = RString "uuid", [Mountable "mountable"], []; + fish_alias = ["get-uuid"]; + proc_nr = Some 254; + tests = [ + InitBasicFS, Always, TestResultString ( + [["set_e2uuid"; "/dev/sda1"; stable_uuid]; + ["vfs_uuid"; "/dev/sda1"]], stable_uuid), [] + ]; + shortdesc = "get the filesystem UUID"; + longdesc = "\ +This returns the filesystem UUID of the filesystem on C<mountable>. + +If the filesystem does not have a UUID, this returns the empty string. + +To find a filesystem from the UUID, use C<guestfs_findfs_uuid>." }; + + { defaults with + name = "lvm_set_filter"; added = (1, 5, 1); + style = RErr, [DeviceList "devices"], []; + proc_nr = Some 255; + optional = Some "lvm2"; + test_excuse = "cannot be tested with the current framework because the VG is being used by the mounted filesystem, so the 'vgchange -an' command we do first will fail"; + shortdesc = "set LVM device filter"; + longdesc = "\ +This sets the LVM device filter so that LVM will only be +able to \"see\" the block devices in the list C<devices>, +and will ignore all other attached block devices. + +Where disk image(s) contain duplicate PVs or VGs, this +command is useful to get LVM to ignore the duplicates, otherwise +LVM can get confused. Note also there are two types +of duplication possible: either cloned PVs/VGs which have +identical UUIDs; or VGs that are not cloned but just happen +to have the same name. In normal operation you cannot +create this situation, but you can do it outside LVM, eg. +by cloning disk images or by bit twiddling inside the LVM +metadata. + +This command also clears the LVM cache and performs a volume +group scan. + +You can filter whole block devices or individual partitions. + +You cannot use this if any VG is currently in use (eg. +contains a mounted filesystem), even if you are not +filtering out that VG." }; + + { defaults with + name = "lvm_clear_filter"; added = (1, 5, 1); + style = RErr, [], []; + proc_nr = Some 256; + test_excuse = "cannot be tested with the current framework because the VG is being used by the mounted filesystem, so the 'vgchange -an' command we do first will fail"; + shortdesc = "clear LVM device filter"; + longdesc = "\ +This undoes the effect of C<guestfs_lvm_set_filter>. LVM +will be able to see every block device. + +This command also clears the LVM cache and performs a volume +group scan." }; + + { defaults with + name = "luks_open"; added = (1, 5, 1); + style = RErr, [Device "device"; Key "key"; String "mapname"], []; + proc_nr = Some 257; + optional = Some "luks"; + shortdesc = "open a LUKS-encrypted block device"; + longdesc = "\ +This command opens a block device which has been encrypted +according to the Linux Unified Key Setup (LUKS) standard. + +C<device> is the encrypted block device or partition. + +The caller must supply one of the keys associated with the +LUKS block device, in the C<key> parameter. + +This creates a new block device called F</dev/mapper/mapname>. +Reads and writes to this block device are decrypted from and +encrypted to the underlying C<device> respectively. + +If this block device contains LVM volume groups, then +calling C<guestfs_vgscan> followed by C<guestfs_vg_activate_all> +will make them visible. + +Use C<guestfs_list_dm_devices> to list all device mapper +devices." }; + + { defaults with + name = "luks_open_ro"; added = (1, 5, 1); + style = RErr, [Device "device"; Key "key"; String "mapname"], []; + proc_nr = Some 258; + optional = Some "luks"; + shortdesc = "open a LUKS-encrypted block device read-only"; + longdesc = "\ +This is the same as C<guestfs_luks_open> except that a read-only +mapping is created." }; + + { defaults with + name = "luks_close"; added = (1, 5, 1); + style = RErr, [Device "device"], []; + proc_nr = Some 259; + optional = Some "luks"; + shortdesc = "close a LUKS device"; + longdesc = "\ +This closes a LUKS device that was created earlier by +C<guestfs_luks_open> or C<guestfs_luks_open_ro>. The +C<device> parameter must be the name of the LUKS mapping +device (ie. F</dev/mapper/mapname>) and I<not> the name +of the underlying block device." }; + + { defaults with + name = "luks_format"; added = (1, 5, 2); + style = RErr, [Device "device"; Key "key"; Int "keyslot"], []; + proc_nr = Some 260; + optional = Some "luks"; + shortdesc = "format a block device as a LUKS encrypted device"; + longdesc = "\ +This command erases existing data on C<device> and formats +the device as a LUKS encrypted device. C<key> is the +initial key, which is added to key slot C<slot>. (LUKS +supports 8 key slots, numbered 0-7)." }; + + { defaults with + name = "luks_format_cipher"; added = (1, 5, 2); + style = RErr, [Device "device"; Key "key"; Int "keyslot"; String "cipher"], []; + proc_nr = Some 261; + optional = Some "luks"; + shortdesc = "format a block device as a LUKS encrypted device"; + longdesc = "\ +This command is the same as C<guestfs_luks_format> but +it also allows you to set the C<cipher> used." }; + + { defaults with + name = "luks_add_key"; added = (1, 5, 2); + style = RErr, [Device "device"; Key "key"; Key "newkey"; Int "keyslot"], []; + proc_nr = Some 262; + optional = Some "luks"; + shortdesc = "add a key on a LUKS encrypted device"; + longdesc = "\ +This command adds a new key on LUKS device C<device>. +C<key> is any existing key, and is used to access the device. +C<newkey> is the new key to add. C<keyslot> is the key slot +that will be replaced. + +Note that if C<keyslot> already contains a key, then this +command will fail. You have to use C<guestfs_luks_kill_slot> +first to remove that key." }; + + { defaults with + name = "luks_kill_slot"; added = (1, 5, 2); + style = RErr, [Device "device"; Key "key"; Int "keyslot"], []; + proc_nr = Some 263; + optional = Some "luks"; + shortdesc = "remove a key from a LUKS encrypted device"; + longdesc = "\ +This command deletes the key in key slot C<keyslot> from the +encrypted LUKS device C<device>. C<key> must be one of the +I<other> keys." }; + + { defaults with + name = "is_lv"; added = (1, 5, 3); + style = RBool "lvflag", [Mountable "mountable"], []; + proc_nr = Some 264; + tests = [ + InitBasicFSonLVM, Always, TestResultTrue ( + [["is_lv"; "/dev/VG/LV"]]), []; + InitBasicFSonLVM, Always, TestResultFalse ( + [["is_lv"; "/dev/sda1"]]), [] + ]; + shortdesc = "test if mountable is a logical volume"; + longdesc = "\ +This command tests whether C<mountable> is a logical volume, and +returns true iff this is the case." }; + + { defaults with + name = "findfs_uuid"; added = (1, 5, 3); + style = RString "device", [String "uuid"], []; + proc_nr = Some 265; + shortdesc = "find a filesystem by UUID"; + longdesc = "\ +This command searches the filesystems and returns the one +which has the given UUID. An error is returned if no such +filesystem can be found. + +To find the UUID of a filesystem, use C<guestfs_vfs_uuid>." }; + + { defaults with + name = "findfs_label"; added = (1, 5, 3); + style = RString "device", [String "label"], []; + proc_nr = Some 266; + shortdesc = "find a filesystem by label"; + longdesc = "\ +This command searches the filesystems and returns the one +which has the given label. An error is returned if no such +filesystem can be found. + +To find the label of a filesystem, use C<guestfs_vfs_label>." }; + + { defaults with + name = "is_chardev"; added = (1, 5, 10); + style = RBool "flag", [Pathname "path"], [OBool "followsymlinks"]; + proc_nr = Some 267; + once_had_no_optargs = true; + tests = [ + InitISOFS, Always, TestResultFalse ( + [["is_chardev"; "/directory"; ""]]), []; + InitScratchFS, Always, TestResultTrue ( + [["mknod_c"; "0o777"; "99"; "66"; "/is_chardev"]; + ["is_chardev"; "/is_chardev"; ""]]), [] + ]; + shortdesc = "test if character device"; + longdesc = "\ +This returns C<true> if and only if there is a character device +with the given C<path> name. + +If the optional flag C<followsymlinks> is true, then a symlink +(or chain of symlinks) that ends with a chardev also causes the +function to return true. + +See also C<guestfs_stat>." }; + + { defaults with + name = "is_blockdev"; added = (1, 5, 10); + style = RBool "flag", [Pathname "path"], [OBool "followsymlinks"]; + proc_nr = Some 268; + once_had_no_optargs = true; + tests = [ + InitISOFS, Always, TestResultFalse ( + [["is_blockdev"; "/directory"; ""]]), []; + InitScratchFS, Always, TestResultTrue ( + [["mknod_b"; "0o777"; "99"; "66"; "/is_blockdev"]; + ["is_blockdev"; "/is_blockdev"; ""]]), [] + ]; + shortdesc = "test if block device"; + longdesc = "\ +This returns C<true> if and only if there is a block device +with the given C<path> name. + +If the optional flag C<followsymlinks> is true, then a symlink +(or chain of symlinks) that ends with a block device also causes the +function to return true. + +This call only looks at files within the guest filesystem. Libguestfs +partitions and block devices (eg. F</dev/sda>) cannot be used as the +C<path> parameter of this call. + +See also C<guestfs_stat>." }; + + { defaults with + name = "is_fifo"; added = (1, 5, 10); + style = RBool "flag", [Pathname "path"], [OBool "followsymlinks"]; + proc_nr = Some 269; + once_had_no_optargs = true; + tests = [ + InitISOFS, Always, TestResultFalse ( + [["is_fifo"; "/directory"; ""]]), []; + InitScratchFS, Always, TestResultTrue ( + [["mkfifo"; "0o777"; "/is_fifo"]; + ["is_fifo"; "/is_fifo"; ""]]), [] + ]; + shortdesc = "test if FIFO (named pipe)"; + longdesc = "\ +This returns C<true> if and only if there is a FIFO (named pipe) +with the given C<path> name. + +If the optional flag C<followsymlinks> is true, then a symlink +(or chain of symlinks) that ends with a FIFO also causes the +function to return true. + +See also C<guestfs_stat>." }; + + { defaults with + name = "is_symlink"; added = (1, 5, 10); + style = RBool "flag", [Pathname "path"], []; + proc_nr = Some 270; + tests = [ + InitISOFS, Always, TestResultFalse ( + [["is_symlink"; "/directory"]]), []; + InitISOFS, Always, TestResultTrue ( + [["is_symlink"; "/abssymlink"]]), [] + ]; + shortdesc = "test if symbolic link"; + longdesc = "\ +This returns C<true> if and only if there is a symbolic link +with the given C<path> name. + +See also C<guestfs_stat>." }; + + { defaults with + name = "is_socket"; added = (1, 5, 10); + style = RBool "flag", [Pathname "path"], [OBool "followsymlinks"]; + proc_nr = Some 271; + once_had_no_optargs = true; + (* XXX Need a positive test for sockets. *) + tests = [ + InitISOFS, Always, TestResultFalse ( + [["is_socket"; "/directory"; ""]]), [] + ]; + shortdesc = "test if socket"; + longdesc = "\ +This returns C<true> if and only if there is a Unix domain socket +with the given C<path> name. + +If the optional flag C<followsymlinks> is true, then a symlink +(or chain of symlinks) that ends with a socket also causes the +function to return true. + +See also C<guestfs_stat>." }; + + { defaults with + name = "part_to_dev"; added = (1, 5, 15); + style = RString "device", [Device "partition"], []; + proc_nr = Some 272; + tests = [ + InitPartition, Always, TestResultDevice ( + [["part_to_dev"; "/dev/sda1"]], "/dev/sda"), []; + InitEmpty, Always, TestLastFail ( + [["part_to_dev"; "/dev/sda"]]), [] + ]; + shortdesc = "convert partition name to device name"; + longdesc = "\ +This function takes a partition name (eg. \"/dev/sdb1\") and +removes the partition number, returning the device name +(eg. \"/dev/sdb\"). + +The named partition must exist, for example as a string returned +from C<guestfs_list_partitions>. + +See also C<guestfs_part_to_partnum>, C<guestfs_device_index>." }; + + { defaults with + name = "upload_offset"; added = (1, 5, 17); + style = RErr, [FileIn "filename"; Dev_or_Path "remotefilename"; Int64 "offset"], []; + proc_nr = Some 273; + progress = true; cancellable = true; + tests = + (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in [ + InitScratchFS, Always, TestResultString ( + [["upload_offset"; "$srcdir/../../COPYING.LIB"; "/upload_offset"; "0"]; + ["checksum"; "md5"; "/upload_offset"]], md5), [] + ]); + shortdesc = "upload a file from the local machine with offset"; + longdesc = "\ +Upload local file F<filename> to F<remotefilename> on the +filesystem. + +F<remotefilename> is overwritten starting at the byte C<offset> +specified. The intention is to overwrite parts of existing +files or devices, although if a non-existent file is specified +then it is created with a \"hole\" before C<offset>. The +size of the data written is implicit in the size of the +source F<filename>. + +Note that there is no limit on the amount of data that +can be uploaded with this call, unlike with C<guestfs_pwrite>, +and this call always writes the full amount unless an +error occurs. + +See also C<guestfs_upload>, C<guestfs_pwrite>." }; + + { defaults with + name = "download_offset"; added = (1, 5, 17); + style = RErr, [Dev_or_Path "remotefilename"; FileOut "filename"; Int64 "offset"; Int64 "size"], []; + proc_nr = Some 274; + progress = true; cancellable = true; + tests = + (let md5 = Digest.to_hex (Digest.file "COPYING.LIB") in + let offset = string_of_int 100 in + let size = string_of_int ((Unix.stat "COPYING.LIB").Unix.st_size - 100) in + [ + InitScratchFS, Always, TestResultString ( + (* Pick a file from cwd which isn't likely to change. *) + [["mkdir"; "/download_offset"]; + ["upload"; "$srcdir/../../COPYING.LIB"; "/download_offset/COPYING.LIB"]; + ["download_offset"; "/download_offset/COPYING.LIB"; "testdownload.tmp"; offset; size]; + ["upload_offset"; "testdownload.tmp"; "/download_offset/COPYING.LIB"; offset]; + ["checksum"; "md5"; "/download_offset/COPYING.LIB"]], md5), [] + ]); + shortdesc = "download a file to the local machine with offset and size"; + longdesc = "\ +Download file F<remotefilename> and save it as F<filename> +on the local machine. + +F<remotefilename> is read for C<size> bytes starting at C<offset> +(this region must be within the file or device). + +Note that there is no limit on the amount of data that +can be downloaded with this call, unlike with C<guestfs_pread>, +and this call always reads the full amount unless an +error occurs. + +See also C<guestfs_download>, C<guestfs_pread>." }; + + { defaults with + name = "pwrite_device"; added = (1, 5, 20); + style = RInt "nbytes", [Device "device"; BufferIn "content"; Int64 "offset"], []; + proc_nr = Some 275; + protocol_limit_warning = true; + tests = [ + InitPartition, Always, TestResult ( + [["pwrite_device"; "/dev/sda"; "\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000"; "446"]; + ["blockdev_rereadpt"; "/dev/sda"]; + ["list_partitions"]], + "is_device_list (ret, 1, \"/dev/sdb1\")"), [] + ]; + shortdesc = "write to part of a device"; + longdesc = "\ +This command writes to part of a device. It writes the data +buffer C<content> to C<device> starting at offset C<offset>. + +This command implements the L<pwrite(2)> system call, and like +that system call it may not write the full data requested +(although short writes to disk devices and partitions are +probably impossible with standard Linux kernels). + +See also C<guestfs_pwrite>." }; + + { defaults with + name = "pread_device"; added = (1, 5, 21); + style = RBufferOut "content", [Device "device"; Int "count"; Int64 "offset"], []; + proc_nr = Some 276; + protocol_limit_warning = true; + tests = [ + InitEmpty, Always, TestResult ( + [["pread_device"; "/dev/sdd"; "8"; "32768"]], + "compare_buffers (ret, size, \"\\1CD001\\1\\0\", 8) == 0"), [] + ]; + shortdesc = "read part of a device"; + longdesc = "\ +This command lets you read part of a block device. It reads C<count> +bytes of C<device>, starting at C<offset>. + +This may read fewer bytes than requested. For further details +see the L<pread(2)> system call. + +See also C<guestfs_pread>." }; + + { defaults with + name = "lvm_canonical_lv_name"; added = (1, 5, 24); + style = RString "lv", [Device "lvname"], []; + proc_nr = Some 277; + tests = [ + InitBasicFSonLVM, IfAvailable "lvm2", TestResultString ( + [["lvm_canonical_lv_name"; "/dev/mapper/VG-LV"]], "/dev/VG/LV"), []; + InitBasicFSonLVM, IfAvailable "lvm2", TestResultString ( + [["lvm_canonical_lv_name"; "/dev/VG/LV"]], "/dev/VG/LV"), [] + ]; + shortdesc = "get canonical name of an LV"; + longdesc = "\ +This converts alternative naming schemes for LVs that you +might find to the canonical name. For example, F</dev/mapper/VG-LV> +is converted to F</dev/VG/LV>. + +This command returns an error if the C<lvname> parameter does +not refer to a logical volume. + +See also C<guestfs_is_lv>, C<guestfs_canonical_device_name>." }; + + { defaults with + name = "mkfs"; added = (0, 0, 8); + style = RErr, [String "fstype"; Device "device"], [OInt "blocksize"; OString "features"; OInt "inode"; OInt "sectorsize"; OString "label"]; + proc_nr = Some 278; + once_had_no_optargs = true; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "ext2"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents"), [] + ]; + shortdesc = "make a filesystem"; + longdesc = "\ +This function creates a filesystem on C<device>. The filesystem +type is C<fstype>, for example C<ext3>. + +The optional arguments are: + +=over 4 + +=item C<blocksize> + +The filesystem block size. Supported block sizes depend on the +filesystem type, but typically they are C<1024>, C<2048> or C<4096> +for Linux ext2/3 filesystems. + +For VFAT and NTFS the C<blocksize> parameter is treated as +the requested cluster size. + +For UFS block sizes, please see L<mkfs.ufs(8)>. + +=item C<features> + +This passes the I<-O> parameter to the external mkfs program. + +For certain filesystem types, this allows extra filesystem +features to be selected. See L<mke2fs(8)> and L<mkfs.ufs(8)> +for more details. + +You cannot use this optional parameter with the C<gfs> or +C<gfs2> filesystem type. + +=item C<inode> + +This passes the I<-I> parameter to the external L<mke2fs(8)> program +which sets the inode size (only for ext2/3/4 filesystems at present). + +=item C<sectorsize> + +This passes the I<-S> parameter to external L<mkfs.ufs(8)> program, +which sets sector size for ufs filesystem. + +=back" }; + + { defaults with + name = "getxattr"; added = (1, 7, 24); + style = RBufferOut "xattr", [Pathname "path"; String "name"], []; + proc_nr = Some 279; + optional = Some "linuxxattrs"; + shortdesc = "get a single extended attribute"; + longdesc = "\ +Get a single extended attribute from file C<path> named C<name>. +This call follows symlinks. If you want to lookup an extended +attribute for the symlink itself, use C<guestfs_lgetxattr>. + +Normally it is better to get all extended attributes from a file +in one go by calling C<guestfs_getxattrs>. However some Linux +filesystem implementations are buggy and do not provide a way to +list out attributes. For these filesystems (notably ntfs-3g) +you have to know the names of the extended attributes you want +in advance and call this function. + +Extended attribute values are blobs of binary data. If there +is no extended attribute named C<name>, this returns an error. + +See also: C<guestfs_getxattrs>, C<guestfs_lgetxattr>, L<attr(5)>." }; + + { defaults with + name = "lgetxattr"; added = (1, 7, 24); + style = RBufferOut "xattr", [Pathname "path"; String "name"], []; + proc_nr = Some 280; + optional = Some "linuxxattrs"; + shortdesc = "get a single extended attribute"; + longdesc = "\ +Get a single extended attribute from file C<path> named C<name>. +If C<path> is a symlink, then this call returns an extended +attribute from the symlink. + +Normally it is better to get all extended attributes from a file +in one go by calling C<guestfs_getxattrs>. However some Linux +filesystem implementations are buggy and do not provide a way to +list out attributes. For these filesystems (notably ntfs-3g) +you have to know the names of the extended attributes you want +in advance and call this function. + +Extended attribute values are blobs of binary data. If there +is no extended attribute named C<name>, this returns an error. + +See also: C<guestfs_lgetxattrs>, C<guestfs_getxattr>, L<attr(5)>." }; + + { defaults with + name = "resize2fs_M"; added = (1, 9, 4); + style = RErr, [Device "device"], []; + proc_nr = Some 281; + shortdesc = "resize an ext2, ext3 or ext4 filesystem to the minimum size"; + longdesc = "\ +This command is the same as C<guestfs_resize2fs>, but the filesystem +is resized to its minimum size. This works like the I<-M> option +to the C<resize2fs> command. + +To get the resulting size of the filesystem you should call +C<guestfs_tune2fs_l> and read the C<Block size> and C<Block count> +values. These two numbers, multiplied together, give the +resulting size of the minimal filesystem in bytes. + +See also L<guestfs(3)/RESIZE2FS ERRORS>." }; + + { defaults with + name = "internal_autosync"; added = (1, 9, 7); + style = RErr, [], []; + proc_nr = Some 282; + visibility = VInternal; + shortdesc = "internal autosync operation"; + longdesc = "\ +This command performs the autosync operation just before the +handle is closed. You should not call this command directly. +Instead, use the autosync flag (C<guestfs_set_autosync>) to +control whether or not this operation is performed when the +handle is closed." }; + + { defaults with + name = "is_zero"; added = (1, 11, 8); + style = RBool "zeroflag", [Pathname "path"], []; + proc_nr = Some 283; + tests = [ + InitISOFS, Always, TestResultTrue ( + [["is_zero"; "/100kallzeroes"]]), []; + InitISOFS, Always, TestResultFalse ( + [["is_zero"; "/100kallspaces"]]), [] + ]; + shortdesc = "test if a file contains all zero bytes"; + longdesc = "\ +This returns true iff the file exists and the file is empty or +it contains all zero bytes." }; + + { defaults with + name = "is_zero_device"; added = (1, 11, 8); + style = RBool "zeroflag", [Device "device"], []; + proc_nr = Some 284; + tests = [ + InitBasicFS, Always, TestResultTrue ( + [["umount"; "/dev/sda1"; "false"; "false"]; + ["zero_device"; "/dev/sda1"]; + ["is_zero_device"; "/dev/sda1"]]), []; + InitBasicFS, Always, TestResultFalse ( + [["is_zero_device"; "/dev/sda1"]]), [] + ]; + shortdesc = "test if a device contains all zero bytes"; + longdesc = "\ +This returns true iff the device exists and contains all zero bytes. + +Note that for large devices this can take a long time to run." }; + + { defaults with + name = "list_9p"; added = (1, 11, 12); + style = RStringList "mounttags", [], []; + proc_nr = Some 285; + shortdesc = "list 9p filesystems"; + longdesc = "\ +List all 9p filesystems attached to the guest. A list of +mount tags is returned." }; + + { defaults with + name = "mount_9p"; added = (1, 11, 12); + style = RErr, [String "mounttag"; String "mountpoint"], [OString "options"]; + proc_nr = Some 286; + camel_name = "Mount9P"; + shortdesc = "mount 9p filesystem"; + longdesc = "\ +Mount the virtio-9p filesystem with the tag C<mounttag> on the +directory C<mountpoint>. + +If required, C<trans=virtio> will be automatically added to the options. +Any other options required can be passed in the optional C<options> +parameter." }; + + { defaults with + name = "list_dm_devices"; added = (1, 11, 15); + style = RStringList "devices", [], []; + proc_nr = Some 287; + shortdesc = "list device mapper devices"; + longdesc = "\ +List all device mapper devices. + +The returned list contains F</dev/mapper/*> devices, eg. ones created +by a previous call to C<guestfs_luks_open>. + +Device mapper devices which correspond to logical volumes are I<not> +returned in this list. Call C<guestfs_lvs> if you want to list logical +volumes." }; + + { defaults with + name = "ntfsresize"; added = (1, 3, 2); + style = RErr, [Device "device"], [OInt64 "size"; OBool "force"]; + once_had_no_optargs = true; + proc_nr = Some 288; + optional = Some "ntfsprogs"; camel_name = "NTFSResizeOpts"; + shortdesc = "resize an NTFS filesystem"; + longdesc = "\ +This command resizes an NTFS filesystem, expanding or +shrinking it to the size of the underlying device. + +The optional parameters are: + +=over 4 + +=item C<size> + +The new size (in bytes) of the filesystem. If omitted, the filesystem +is resized to fit the container (eg. partition). + +=item C<force> + +If this option is true, then force the resize of the filesystem +even if the filesystem is marked as requiring a consistency check. + +After the resize operation, the filesystem is always marked +as requiring a consistency check (for safety). You have to boot +into Windows to perform this check and clear this condition. +If you I<don't> set the C<force> option then it is not +possible to call C<guestfs_ntfsresize> multiple times on a +single filesystem without booting into Windows between each resize. + +=back + +See also L<ntfsresize(8)>." }; + + { defaults with + name = "btrfs_filesystem_resize"; added = (1, 11, 17); + style = RErr, [Pathname "mountpoint"], [OInt64 "size"]; + proc_nr = Some 289; + optional = Some "btrfs"; camel_name = "BTRFSFilesystemResize"; + shortdesc = "resize a btrfs filesystem"; + longdesc = "\ +This command resizes a btrfs filesystem. + +Note that unlike other resize calls, the filesystem has to be +mounted and the parameter is the mountpoint not the device +(this is a requirement of btrfs itself). + +The optional parameters are: + +=over 4 + +=item C<size> + +The new size (in bytes) of the filesystem. If omitted, the filesystem +is resized to the maximum size. + +=back + +See also L<btrfs(8)>." }; + + { defaults with + name = "internal_write_append"; added = (1, 19, 32); + style = RErr, [Pathname "path"; BufferIn "content"], []; + proc_nr = Some 290; + visibility = VInternal; + protocol_limit_warning = true; + tests = [ + InitScratchFS, Always, TestResultString ( + [["write"; "/internal_write_append"; "line1\n"]; + ["internal_write_append"; "/internal_write_append"; "line2\n"]; + ["internal_write_append"; "/internal_write_append"; "line3a"]; + ["internal_write_append"; "/internal_write_append"; "line3b\n"]; + ["cat"; "/internal_write_append"]], "line1\nline2\nline3aline3b\n"), [] + ]; + shortdesc = "append content to end of file"; + longdesc = "\ +This call appends C<content> to the end of file C<path>. If +C<path> does not exist, then a new file is created. + +See also C<guestfs_write>." }; + + { defaults with + name = "compress_out"; added = (1, 13, 15); + style = RErr, [String "ctype"; Pathname "file"; FileOut "zfile"], [OInt "level"]; + proc_nr = Some 291; + cancellable = true; + shortdesc = "output compressed file"; + longdesc = "\ +This command compresses F<file> and writes it out to the local +file F<zfile>. + +The compression program used is controlled by the C<ctype> parameter. +Currently this includes: C<compress>, C<gzip>, C<bzip2>, C<xz> or C<lzop>. +Some compression types may not be supported by particular builds of +libguestfs, in which case you will get an error containing the +substring \"not supported\". + +The optional C<level> parameter controls compression level. The +meaning and default for this parameter depends on the compression +program being used." }; + + { defaults with + name = "compress_device_out"; added = (1, 13, 15); + style = RErr, [String "ctype"; Device "device"; FileOut "zdevice"], [OInt "level"]; + proc_nr = Some 292; + cancellable = true; + shortdesc = "output compressed device"; + longdesc = "\ +This command compresses C<device> and writes it out to the local +file C<zdevice>. + +The C<ctype> and optional C<level> parameters have the same meaning +as in C<guestfs_compress_out>." }; + + { defaults with + name = "part_to_partnum"; added = (1, 13, 25); + style = RInt "partnum", [Device "partition"], []; + proc_nr = Some 293; + tests = [ + InitPartition, Always, TestResult ( + [["part_to_partnum"; "/dev/sda1"]], "ret == 1"), []; + InitEmpty, Always, TestLastFail ( + [["part_to_partnum"; "/dev/sda"]]), [] + ]; + shortdesc = "convert partition name to partition number"; + longdesc = "\ +This function takes a partition name (eg. \"/dev/sdb1\") and +returns the partition number (eg. C<1>). + +The named partition must exist, for example as a string returned +from C<guestfs_list_partitions>. + +See also C<guestfs_part_to_dev>." }; + + { defaults with + name = "copy_device_to_device"; added = (1, 13, 25); + style = RErr, [Device "src"; Device "dest"], [OInt64 "srcoffset"; OInt64 "destoffset"; OInt64 "size"; OBool "sparse"; OBool "append"]; + proc_nr = Some 294; + progress = true; + shortdesc = "copy from source device to destination device"; + longdesc = "\ +The four calls C<guestfs_copy_device_to_device>, +C<guestfs_copy_device_to_file>, +C<guestfs_copy_file_to_device>, and +C<guestfs_copy_file_to_file> +let you copy from a source (device|file) to a destination +(device|file). + +Partial copies can be made since you can specify optionally +the source offset, destination offset and size to copy. These +values are all specified in bytes. If not given, the offsets +both default to zero, and the size defaults to copying as much +as possible until we hit the end of the source. + +The source and destination may be the same object. However +overlapping regions may not be copied correctly. + +If the destination is a file, it is created if required. If +the destination file is not large enough, it is extended. + +If the destination is a file and the C<append> flag is not set, +then the destination file is truncated. If the C<append> flag is +set, then the copy appends to the destination file. The C<append> +flag currently cannot be set for devices. + +If the C<sparse> flag is true then the call avoids writing +blocks that contain only zeroes, which can help in some situations +where the backing disk is thin-provisioned. Note that unless +the target is already zeroed, using this option will result +in incorrect copying." }; + + { defaults with + name = "copy_device_to_file"; added = (1, 13, 25); + style = RErr, [Device "src"; Pathname "dest"], [OInt64 "srcoffset"; OInt64 "destoffset"; OInt64 "size"; OBool "sparse"; OBool "append"]; + proc_nr = Some 295; + progress = true; + shortdesc = "copy from source device to destination file"; + longdesc = "\ +See C<guestfs_copy_device_to_device> for a general overview +of this call." }; + + { defaults with + name = "copy_file_to_device"; added = (1, 13, 25); + style = RErr, [Pathname "src"; Device "dest"], [OInt64 "srcoffset"; OInt64 "destoffset"; OInt64 "size"; OBool "sparse"; OBool "append"]; + proc_nr = Some 296; + progress = true; + shortdesc = "copy from source file to destination device"; + longdesc = "\ +See C<guestfs_copy_device_to_device> for a general overview +of this call." }; + + { defaults with + name = "copy_file_to_file"; added = (1, 13, 25); + style = RErr, [Pathname "src"; Pathname "dest"], [OInt64 "srcoffset"; OInt64 "destoffset"; OInt64 "size"; OBool "sparse"; OBool "append"]; + proc_nr = Some 297; + progress = true; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir"; "/copyff"]; + ["write"; "/copyff/src"; "hello, world"]; + ["copy_file_to_file"; "/copyff/src"; "/copyff/dest"; ""; ""; ""; ""; "false"]; + ["read_file"; "/copyff/dest"]], + "compare_buffers (ret, size, \"hello, world\", 12) == 0"), []; + InitScratchFS, Always, TestResultTrue ( + let size = 1024 * 1024 in + [["mkdir"; "/copyff2"]; + ["fill"; "0"; string_of_int size; "/copyff2/src"]; + ["touch"; "/copyff2/dest"]; + ["truncate_size"; "/copyff2/dest"; string_of_int size]; + ["copy_file_to_file"; "/copyff2/src"; "/copyff2/dest"; ""; ""; ""; "true"; "false"]; + ["is_zero"; "/copyff2/dest"]]), []; + InitScratchFS, Always, TestResult ( + [["mkdir"; "/copyff3"]; + ["write"; "/copyff3/src"; "hello, world"]; + ["copy_file_to_file"; "/copyff3/src"; "/copyff3/dest"; ""; ""; ""; ""; "true"]; + ["copy_file_to_file"; "/copyff3/src"; "/copyff3/dest"; ""; ""; ""; ""; "true"]; + ["copy_file_to_file"; "/copyff3/src"; "/copyff3/dest"; ""; ""; ""; ""; "true"]; + ["read_file"; "/copyff3/dest"]], + "compare_buffers (ret, size, \"hello, worldhello, worldhello, world\", 12*3) == 0"), []; + ]; + shortdesc = "copy from source file to destination file"; + longdesc = "\ +See C<guestfs_copy_device_to_device> for a general overview +of this call. + +This is B<not> the function you want for copying files. This +is for copying blocks within existing files. See C<guestfs_cp>, +C<guestfs_cp_a> and C<guestfs_mv> for general file copying and +moving functions." }; + + { defaults with + name = "tune2fs"; added = (1, 15, 4); + style = RErr, [Device "device"], [OBool "force"; OInt "maxmountcount"; OInt "mountcount"; OString "errorbehavior"; OInt64 "group"; OInt "intervalbetweenchecks"; OInt "reservedblockspercentage"; OString "lastmounteddirectory"; OInt64 "reservedblockscount"; OInt64 "user"]; + proc_nr = Some 298; + camel_name = "Tune2FS"; + tests = [ + InitScratchFS, Always, TestResult ( + [["tune2fs"; "/dev/sdb1"; "false"; "0"; ""; "NOARG"; ""; "0"; ""; "NOARG"; ""; ""]; + ["tune2fs_l"; "/dev/sdb1"]], + "check_hash (ret, \"Check interval\", \"0 (<none>)\") == 0 && "^ + "check_hash (ret, \"Maximum mount count\", \"-1\") == 0"), []; + InitScratchFS, Always, TestResult ( + [["tune2fs"; "/dev/sdb1"; "false"; "0"; ""; "NOARG"; ""; "86400"; ""; "NOARG"; ""; ""]; + ["tune2fs_l"; "/dev/sdb1"]], + "check_hash (ret, \"Check interval\", \"86400 (1 day)\") == 0 && "^ + "check_hash (ret, \"Maximum mount count\", \"-1\") == 0"), []; + InitScratchFS, Always, TestResult ( + [["tune2fs"; "/dev/sdb1"; "false"; ""; ""; "NOARG"; "1"; ""; ""; "NOARG"; ""; "1"]; + ["tune2fs_l"; "/dev/sdb1"]], + "match_re (get_key (ret, \"Reserved blocks uid\"), \"\\\\d+ \\\\(user \\\\S+\\\\)\") && "^ + "match_re (get_key (ret, \"Reserved blocks gid\"), \"\\\\d+ \\\\(group \\\\S+\\\\)\")"), []; + InitScratchFS, Always, TestResult ( + [["tune2fs"; "/dev/sdb1"; "false"; ""; ""; "NOARG"; "0"; ""; ""; "NOARG"; ""; "0"]; + ["tune2fs_l"; "/dev/sdb1"]], + "match_re (get_key (ret, \"Reserved blocks uid\"), \"\\\\d+ \\\\(user \\\\S+\\\\)\") && "^ + "match_re (get_key (ret, \"Reserved blocks gid\"), \"\\\\d+ \\\\(group \\\\S+\\\\)\")"), []; + ]; + shortdesc = "adjust ext2/ext3/ext4 filesystem parameters"; + longdesc = "\ +This call allows you to adjust various filesystem parameters of +an ext2/ext3/ext4 filesystem called C<device>. + +The optional parameters are: + +=over 4 + +=item C<force> + +Force tune2fs to complete the operation even in the face of errors. +This is the same as the tune2fs C<-f> option. + +=item C<maxmountcount> + +Set the number of mounts after which the filesystem is checked +by L<e2fsck(8)>. If this is C<0> then the number of mounts is +disregarded. This is the same as the tune2fs C<-c> option. + +=item C<mountcount> + +Set the number of times the filesystem has been mounted. +This is the same as the tune2fs C<-C> option. + +=item C<errorbehavior> + +Change the behavior of the kernel code when errors are detected. +Possible values currently are: C<continue>, C<remount-ro>, C<panic>. +In practice these options don't really make any difference, +particularly for write errors. + +This is the same as the tune2fs C<-e> option. + +=item C<group> + +Set the group which can use reserved filesystem blocks. +This is the same as the tune2fs C<-g> option except that it +can only be specified as a number. + +=item C<intervalbetweenchecks> + +Adjust the maximal time between two filesystem checks +(in seconds). If the option is passed as C<0> then +time-dependent checking is disabled. + +This is the same as the tune2fs C<-i> option. + +=item C<reservedblockspercentage> + +Set the percentage of the filesystem which may only be allocated +by privileged processes. +This is the same as the tune2fs C<-m> option. + +=item C<lastmounteddirectory> + +Set the last mounted directory. +This is the same as the tune2fs C<-M> option. + +=item C<reservedblockscount> +Set the number of reserved filesystem blocks. +This is the same as the tune2fs C<-r> option. + +=item C<user> + +Set the user who can use the reserved filesystem blocks. +This is the same as the tune2fs C<-u> option except that it +can only be specified as a number. + +=back + +To get the current values of filesystem parameters, see +C<guestfs_tune2fs_l>. For precise details of how tune2fs +works, see the L<tune2fs(8)> man page." }; + + { defaults with + name = "md_create"; added = (1, 15, 6); + style = RErr, [String "name"; DeviceList "devices"], [OInt64 "missingbitmap"; OInt "nrdevices"; OInt "spare"; OInt64 "chunk"; OString "level"]; + proc_nr = Some 299; + optional = Some "mdadm"; camel_name = "MDCreate"; + shortdesc = "create a Linux md (RAID) device"; + longdesc = "\ +Create a Linux md (RAID) device named C<name> on the devices +in the list C<devices>. + +The optional parameters are: + +=over 4 + +=item C<missingbitmap> + +A bitmap of missing devices. If a bit is set it means that a +missing device is added to the array. The least significant bit +corresponds to the first device in the array. + +As examples: + +If C<devices = [\"/dev/sda\"]> and C<missingbitmap = 0x1> then +the resulting array would be C<[E<lt>missingE<gt>, \"/dev/sda\"]>. + +If C<devices = [\"/dev/sda\"]> and C<missingbitmap = 0x2> then +the resulting array would be C<[\"/dev/sda\", E<lt>missingE<gt>]>. + +This defaults to C<0> (no missing devices). + +The length of C<devices> + the number of bits set in +C<missingbitmap> must equal C<nrdevices> + C<spare>. + +=item C<nrdevices> + +The number of active RAID devices. + +If not set, this defaults to the length of C<devices> plus +the number of bits set in C<missingbitmap>. + +=item C<spare> + +The number of spare devices. + +If not set, this defaults to C<0>. + +=item C<chunk> + +The chunk size in bytes. + +=item C<level> + +The RAID level, which can be one of: +I<linear>, I<raid0>, I<0>, I<stripe>, I<raid1>, I<1>, I<mirror>, +I<raid4>, I<4>, I<raid5>, I<5>, I<raid6>, I<6>, I<raid10>, I<10>. +Some of these are synonymous, and more levels may be added in future. + +If not set, this defaults to C<raid1>. + +=back" }; + + { defaults with + name = "list_md_devices"; added = (1, 15, 4); + style = RStringList "devices", [], []; + proc_nr = Some 300; + shortdesc = "list Linux md (RAID) devices"; + longdesc = "\ +List all Linux md devices." }; + + { defaults with + name = "md_detail"; added = (1, 15, 6); + style = RHashtable "info", [Device "md"], []; + proc_nr = Some 301; + optional = Some "mdadm"; + shortdesc = "obtain metadata for an MD device"; + longdesc = "\ +This command exposes the output of 'mdadm -DY E<lt>mdE<gt>'. +The following fields are usually present in the returned hash. +Other fields may also be present. + +=over + +=item C<level> + +The raid level of the MD device. + +=item C<devices> + +The number of underlying devices in the MD device. + +=item C<metadata> + +The metadata version used. + +=item C<uuid> + +The UUID of the MD device. + +=item C<name> + +The name of the MD device. + +=back" }; + + { defaults with + name = "md_stop"; added = (1, 15, 6); + style = RErr, [Device "md"], []; + proc_nr = Some 302; + optional = Some "mdadm"; + shortdesc = "stop a Linux md (RAID) device"; + longdesc = "\ +This command deactivates the MD array named C<md>. The +device is stopped, but it is not destroyed or zeroed." }; + + { defaults with + name = "blkid"; added = (1, 15, 9); + style = RHashtable "info", [Device "device"], []; + proc_nr = Some 303; + tests = [ + InitScratchFS, Always, TestResult ( + [["blkid"; "/dev/sdb1"]], + "check_hash (ret, \"TYPE\", \"ext2\") == 0 && "^ + "check_hash (ret, \"USAGE\", \"filesystem\") == 0 && "^ + "check_hash (ret, \"PART_ENTRY_NUMBER\", \"1\") == 0 && "^ + "check_hash (ret, \"PART_ENTRY_TYPE\", \"0x83\") == 0 && "^ + "check_hash (ret, \"PART_ENTRY_OFFSET\", \"128\") == 0 && "^ + "check_hash (ret, \"PART_ENTRY_SIZE\", \"4194049\") == 0"), []; + ]; + shortdesc = "print block device attributes"; + longdesc = "\ +This command returns block device attributes for C<device>. The following fields are +usually present in the returned hash. Other fields may also be present. + +=over + +=item C<UUID> + +The uuid of this device. + +=item C<LABEL> + +The label of this device. + +=item C<VERSION> + +The version of blkid command. + +=item C<TYPE> + +The filesystem type or RAID of this device. + +=item C<USAGE> + +The usage of this device, for example C<filesystem> or C<raid>. + +=back" }; + + { defaults with + name = "e2fsck"; added = (1, 15, 17); + style = RErr, [Device "device"], [OBool "correct"; OBool "forceall"]; + proc_nr = Some 304; + shortdesc = "check an ext2/ext3 filesystem"; + longdesc = "\ +This runs the ext2/ext3 filesystem checker on C<device>. +It can take the following optional arguments: + +=over 4 + +=item C<correct> + +Automatically repair the file system. This option will cause e2fsck +to automatically fix any filesystem problems that can be safely +fixed without human intervention. + +This option may not be specified at the same time as the C<forceall> option. + +=item C<forceall> + +Assume an answer of 'yes' to all questions; allows e2fsck to be used +non-interactively. + +This option may not be specified at the same time as the C<correct> option. + +=back" }; + + { defaults with + name = "wipefs"; added = (1, 17, 6); + style = RErr, [Device "device"], []; + proc_nr = Some 306; + optional = Some "wipefs"; + tests = [ + InitBasicFSonLVM, Always, TestRun ( + [["umount"; "/dev/VG/LV"; ""; ""]; + ["wipefs"; "/dev/VG/LV"]]), [] + ]; + shortdesc = "wipe a filesystem signature from a device"; + longdesc = "\ +This command erases filesystem or RAID signatures from +the specified C<device> to make the filesystem invisible to libblkid. + +This does not erase the filesystem itself nor any other data from the +C<device>. + +Compare with C<guestfs_zero> which zeroes the first few blocks of a +device." }; + + { defaults with + name = "ntfsfix"; added = (1, 17, 9); + style = RErr, [Device "device"], [OBool "clearbadsectors"]; + proc_nr = Some 307; + optional = Some "ntfs3g"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["ntfsfix"; "/dev/sda1"; "false"]]), [] + ]; + shortdesc = "fix common errors and force Windows to check NTFS"; + longdesc = "\ +This command repairs some fundamental NTFS inconsistencies, +resets the NTFS journal file, and schedules an NTFS consistency +check for the first boot into Windows. + +This is I<not> an equivalent of Windows C<chkdsk>. It does I<not> +scan the filesystem for inconsistencies. + +The optional C<clearbadsectors> flag clears the list of bad sectors. +This is useful after cloning a disk with bad sectors to a new disk." }; + + { defaults with + name = "ntfsclone_out"; added = (1, 17, 9); + style = RErr, [Device "device"; FileOut "backupfile"], [OBool "metadataonly"; OBool "rescue"; OBool "ignorefscheck"; OBool "preservetimestamps"; OBool "force"]; + proc_nr = Some 308; + optional = Some "ntfs3g"; cancellable = true; + test_excuse = "tested in tests/ntfsclone"; + shortdesc = "save NTFS to backup file"; + longdesc = "\ +Stream the NTFS filesystem C<device> to the local file +C<backupfile>. The format used for the backup file is a +special format used by the L<ntfsclone(8)> tool. + +If the optional C<metadataonly> flag is true, then I<only> the +metadata is saved, losing all the user data (this is useful +for diagnosing some filesystem problems). + +The optional C<rescue>, C<ignorefscheck>, C<preservetimestamps> +and C<force> flags have precise meanings detailed in the +L<ntfsclone(8)> man page. + +Use C<guestfs_ntfsclone_in> to restore the file back to a +libguestfs device." }; + + { defaults with + name = "ntfsclone_in"; added = (1, 17, 9); + style = RErr, [FileIn "backupfile"; Device "device"], []; + proc_nr = Some 309; + optional = Some "ntfs3g"; cancellable = true; + test_excuse = "tested in tests/ntfsclone"; + shortdesc = "restore NTFS from backup file"; + longdesc = "\ +Restore the C<backupfile> (from a previous call to +C<guestfs_ntfsclone_out>) to C<device>, overwriting +any existing contents of this device." }; + + { defaults with + name = "set_label"; added = (1, 17, 9); + style = RErr, [Mountable "mountable"; String "label"], []; + proc_nr = Some 310; + tests = [ + InitBasicFS, Always, TestResultString ( + [["set_label"; "/dev/sda1"; "testlabel"]; + ["vfs_label"; "/dev/sda1"]], "testlabel"), []; + InitPartition, IfAvailable "ntfs3g", TestResultString ( + [["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["set_label"; "/dev/sda1"; "testlabel2"]; + ["vfs_label"; "/dev/sda1"]], "testlabel2"), []; + InitPartition, Always, TestLastFail ( + [["zero"; "/dev/sda1"]; + ["set_label"; "/dev/sda1"; "testlabel2"]]), [] + ]; + shortdesc = "set filesystem label"; + longdesc = "\ +Set the filesystem label on C<mountable> to C<label>. + +Only some filesystem types support labels, and libguestfs supports +setting labels on only a subset of these. + +=over 4 + +=item ext2, ext3, ext4 + +Labels are limited to 16 bytes. + +=item NTFS + +Labels are limited to 128 unicode characters. + +=item XFS + +The label is limited to 12 bytes. The filesystem must not +be mounted when trying to set the label. + +=item btrfs + +The label is limited to 255 bytes and some characters are +not allowed. Setting the label on a btrfs subvolume will set the +label on its parent filesystem. The filesystem must not be mounted +when trying to set the label. + +=item fat + +The label is limited to 11 bytes. + +=item swap + +The label is limited to 16 bytes. + +=back + +If there is no support for changing the label +for the type of the specified filesystem, +set_label will fail and set errno as ENOTSUP. + +To read the label on a filesystem, call C<guestfs_vfs_label>." }; + + { defaults with + name = "zero_free_space"; added = (1, 17, 18); + style = RErr, [Pathname "directory"], []; + proc_nr = Some 311; + progress = true; + tests = [ + InitScratchFS, Always, TestRun ( + [["zero_free_space"; "/"]]), [] + ]; + shortdesc = "zero free space in a filesystem"; + longdesc = "\ +Zero the free space in the filesystem mounted on F<directory>. +The filesystem must be mounted read-write. + +The filesystem contents are not affected, but any free space +in the filesystem is freed. + +Free space is not \"trimmed\". You may want to call +C<guestfs_fstrim> either as an alternative to this, +or after calling this, depending on your requirements." }; + + { defaults with + name = "lvcreate_free"; added = (1, 17, 18); + style = RErr, [String "logvol"; String "volgroup"; Int "percent"], []; + proc_nr = Some 312; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate_free"; "LV1"; "VG"; "50"]; + ["lvcreate_free"; "LV2"; "VG"; "50"]; + ["lvcreate_free"; "LV3"; "VG"; "50"]; + ["lvcreate_free"; "LV4"; "VG"; "100"]; + ["lvs"]], + "is_string_list (ret, 4, \"/dev/VG/LV1\", \"/dev/VG/LV2\", \"/dev/VG/LV3\", \"/dev/VG/LV4\")"), [] + ]; + shortdesc = "create an LVM logical volume in % remaining free space"; + longdesc = "\ +Create an LVM logical volume called F</dev/volgroup/logvol>, +using approximately C<percent> % of the free space remaining +in the volume group. Most usefully, when C<percent> is C<100> +this will create the largest possible LV." }; + + { defaults with + name = "isoinfo_device"; added = (1, 17, 19); + style = RStruct ("isodata", "isoinfo"), [Device "device"], []; + proc_nr = Some 313; + tests = [ + InitNone, Always, TestResult ( + [["isoinfo_device"; "/dev/sdd"]], + "STREQ (ret->iso_system_id, GUESTFS_ISO_SYSTEM_ID) && "^ + "STREQ (ret->iso_volume_id, \"CDROM\") && "^ + "STREQ (ret->iso_volume_set_id, \"\") && "^ + "ret->iso_volume_set_size == 1 && "^ + "ret->iso_volume_sequence_number == 1 && "^ + "ret->iso_logical_block_size == 2048"), [] + ]; + shortdesc = "get ISO information from primary volume descriptor of device"; + longdesc = "\ +C<device> is an ISO device. This returns a struct of information +read from the primary volume descriptor (the ISO equivalent of the +superblock) of the device. + +Usually it is more efficient to use the L<isoinfo(1)> command +with the I<-d> option on the host to analyze ISO files, +instead of going through libguestfs. + +For information on the primary volume descriptor fields, see +L<http://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor>" }; + + { defaults with + name = "isoinfo"; added = (1, 17, 19); + style = RStruct ("isodata", "isoinfo"), [Pathname "isofile"], []; + proc_nr = Some 314; + shortdesc = "get ISO information from primary volume descriptor of ISO file"; + longdesc = "\ +This is the same as C<guestfs_isoinfo_device> except that it +works for an ISO file located inside some other mounted filesystem. +Note that in the common case where you have added an ISO file +as a libguestfs device, you would I<not> call this. Instead +you would call C<guestfs_isoinfo_device>." }; + + { defaults with + name = "vgmeta"; added = (1, 17, 20); + style = RBufferOut "metadata", [String "vgname"], []; + proc_nr = Some 315; + optional = Some "lvm2"; + shortdesc = "get volume group metadata"; + longdesc = "\ +C<vgname> is an LVM volume group. This command examines the +volume group and returns its metadata. + +Note that the metadata is an internal structure used by LVM, +subject to change at any time, and is provided for information only." }; + + { defaults with + name = "md_stat"; added = (1, 17, 21); + style = RStructList ("devices", "mdstat"), [Device "md"], []; + proc_nr = Some 316; + optional = Some "mdadm"; + shortdesc = "get underlying devices from an MD device"; + longdesc = "\ +This call returns a list of the underlying devices which make +up the single software RAID array device C<md>. + +To get a list of software RAID devices, call C<guestfs_list_md_devices>. + +Each structure returned corresponds to one device along with +additional status information: + +=over 4 + +=item C<mdstat_device> + +The name of the underlying device. + +=item C<mdstat_index> + +The index of this device within the array. + +=item C<mdstat_flags> + +Flags associated with this device. This is a string containing +(in no specific order) zero or more of the following flags: + +=over 4 + +=item C<W> + +write-mostly + +=item C<F> + +device is faulty + +=item C<S> + +device is a RAID spare + +=item C<R> + +replacement + +=back + +=back" }; + + { defaults with + name = "mkfs_btrfs"; added = (1, 17, 25); + style = RErr, [DeviceList "devices"], [OInt64 "allocstart"; OInt64 "bytecount"; OString "datatype"; OInt "leafsize"; OString "label"; OString "metadata"; OInt "nodesize"; OInt "sectorsize"]; + proc_nr = Some 317; + optional = Some "btrfs"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs_btrfs"; "/dev/sda1"; "0"; "268435456"; "single"; ""; "test"; "single"; "65536"; "512"]]), [] + ]; + shortdesc = "create a btrfs filesystem"; + longdesc = "\ +Create a btrfs filesystem, allowing all configurables to be set. +For more information on the optional arguments, see L<mkfs.btrfs(8)>. + +Since btrfs filesystems can span multiple devices, this takes a +non-empty list of devices. + +To create general filesystems, use C<guestfs_mkfs>." }; + + { defaults with + name = "get_e2attrs"; added = (1, 17, 31); + style = RString "attrs", [Pathname "file"], []; + proc_nr = Some 318; + tests = [ + InitScratchFS, Always, TestResultString ( + [["touch"; "/e2attrs1"]; + ["get_e2attrs"; "/e2attrs1"]], ""), []; + InitScratchFS, Always, TestResultString ( + [["touch"; "/e2attrs2"]; + ["set_e2attrs"; "/e2attrs2"; "is"; "false"]; + ["get_e2attrs"; "/e2attrs2"]], "is"), []; + InitScratchFS, Always, TestResultString ( + [["touch"; "/e2attrs3"]; + ["set_e2attrs"; "/e2attrs3"; "is"; "false"]; + ["set_e2attrs"; "/e2attrs3"; "i"; "true"]; + ["get_e2attrs"; "/e2attrs3"]], "s"), []; + InitScratchFS, Always, TestResultString ( + [["touch"; "/e2attrs4"]; + ["set_e2attrs"; "/e2attrs4"; "adst"; "false"]; + ["set_e2attrs"; "/e2attrs4"; "iS"; "false"]; + ["set_e2attrs"; "/e2attrs4"; "i"; "true"]; + ["set_e2attrs"; "/e2attrs4"; "ad"; "true"]; + ["set_e2attrs"; "/e2attrs4"; ""; "false"]; + ["set_e2attrs"; "/e2attrs4"; ""; "true"]; + ["get_e2attrs"; "/e2attrs4"]], "Sst"), []; + InitScratchFS, Always, TestLastFail ( + [["touch"; "/e2attrs5"]; + ["set_e2attrs"; "/e2attrs5"; "R"; "false"]]), []; + InitScratchFS, Always, TestLastFail ( + [["touch"; "/e2attrs6"]; + ["set_e2attrs"; "/e2attrs6"; "v"; "false"]]), []; + InitScratchFS, Always, TestLastFail ( + [["touch"; "/e2attrs7"]; + ["set_e2attrs"; "/e2attrs7"; "aa"; "false"]]), []; + InitScratchFS, Always, TestLastFail ( + [["touch"; "/e2attrs8"]; + ["set_e2attrs"; "/e2attrs8"; "BabcdB"; "false"]]), [] + ]; + shortdesc = "get ext2 file attributes of a file"; + longdesc = "\ +This returns the file attributes associated with F<file>. + +The attributes are a set of bits associated with each +inode which affect the behaviour of the file. The attributes +are returned as a string of letters (described below). The +string may be empty, indicating that no file attributes are +set for this file. + +These attributes are only present when the file is located on +an ext2/3/4 filesystem. Using this call on other filesystem +types will result in an error. + +The characters (file attributes) in the returned string are +currently: + +=over 4 + +=item 'A' + +When the file is accessed, its atime is not modified. + +=item 'a' + +The file is append-only. + +=item 'c' + +The file is compressed on-disk. + +=item 'D' + +(Directories only.) Changes to this directory are written +synchronously to disk. + +=item 'd' + +The file is not a candidate for backup (see L<dump(8)>). + +=item 'E' + +The file has compression errors. + +=item 'e' + +The file is using extents. + +=item 'h' + +The file is storing its blocks in units of the filesystem blocksize +instead of sectors. + +=item 'I' + +(Directories only.) The directory is using hashed trees. + +=item 'i' + +The file is immutable. It cannot be modified, deleted or renamed. +No link can be created to this file. + +=item 'j' + +The file is data-journaled. + +=item 's' + +When the file is deleted, all its blocks will be zeroed. + +=item 'S' + +Changes to this file are written synchronously to disk. + +=item 'T' + +(Directories only.) This is a hint to the block allocator +that subdirectories contained in this directory should be +spread across blocks. If not present, the block allocator +will try to group subdirectories together. + +=item 't' + +For a file, this disables tail-merging. +(Not used by upstream implementations of ext2.) + +=item 'u' + +When the file is deleted, its blocks will be saved, allowing +the file to be undeleted. + +=item 'X' + +The raw contents of the compressed file may be accessed. + +=item 'Z' + +The compressed file is dirty. + +=back + +More file attributes may be added to this list later. Not all +file attributes may be set for all kinds of files. For +detailed information, consult the L<chattr(1)> man page. + +See also C<guestfs_set_e2attrs>. + +Don't confuse these attributes with extended attributes +(see C<guestfs_getxattr>)." }; + + { defaults with + name = "set_e2attrs"; added = (1, 17, 31); + style = RErr, [Pathname "file"; String "attrs"], [OBool "clear"]; + proc_nr = Some 319; + shortdesc = "set ext2 file attributes of a file"; + longdesc = "\ +This sets or clears the file attributes C<attrs> +associated with the inode F<file>. + +C<attrs> is a string of characters representing +file attributes. See C<guestfs_get_e2attrs> for a list of +possible attributes. Not all attributes can be changed. + +If optional boolean C<clear> is not present or false, then +the C<attrs> listed are set in the inode. + +If C<clear> is true, then the C<attrs> listed are cleared +in the inode. + +In both cases, other attributes not present in the C<attrs> +string are left unchanged. + +These attributes are only present when the file is located on +an ext2/3/4 filesystem. Using this call on other filesystem +types will result in an error." }; + + { defaults with + name = "get_e2generation"; added = (1, 17, 31); + style = RInt64 "generation", [Pathname "file"], []; + proc_nr = Some 320; + tests = [ + InitScratchFS, Always, TestResult ( + [["touch"; "/e2generation"]; + ["set_e2generation"; "/e2generation"; "123456"]; + ["get_e2generation"; "/e2generation"]], "ret == 123456"), [] + ]; + shortdesc = "get ext2 file generation of a file"; + longdesc = "\ +This returns the ext2 file generation of a file. The generation +(which used to be called the \"version\") is a number associated +with an inode. This is most commonly used by NFS servers. + +The generation is only present when the file is located on +an ext2/3/4 filesystem. Using this call on other filesystem +types will result in an error. + +See C<guestfs_set_e2generation>." }; + + { defaults with + name = "set_e2generation"; added = (1, 17, 31); + style = RErr, [Pathname "file"; Int64 "generation"], []; + proc_nr = Some 321; + shortdesc = "set ext2 file generation of a file"; + longdesc = "\ +This sets the ext2 file generation of a file. + +See C<guestfs_get_e2generation>." }; + + { defaults with + name = "btrfs_subvolume_snapshot"; added = (1, 17, 35); + style = RErr, [Pathname "source"; Pathname "dest"], [OBool "ro"; OString "qgroupid"]; + proc_nr = Some 322; + once_had_no_optargs = true; + optional = Some "btrfs"; camel_name = "BTRFSSubvolumeSnapshot"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["mkdir"; "/dir"]; + ["btrfs_subvolume_create"; "/test1"; "NOARG"]; + ["btrfs_subvolume_create"; "/test2"; "NOARG"]; + ["btrfs_subvolume_create"; "/dir/test3"; "NOARG"]; + ["btrfs_subvolume_snapshot"; "/dir/test3"; "/dir/test5"; "true"; "NOARG"]; + ["btrfs_subvolume_snapshot"; "/dir/test3"; "/dir/test6"; ""; "0/1000"]]), [] + ]; + shortdesc = "create a btrfs snapshot"; + longdesc = "\ +Create a snapshot of the btrfs subvolume C<source>. +The C<dest> argument is the destination directory and the name +of the snapshot, in the form F</path/to/dest/name>. By default +the newly created snapshot is writable, if the value of optional +parameter C<ro> is true, then a readonly snapshot is created. The +optional parameter C<qgroupid> represents the qgroup which the +newly created snapshot will be added to." }; + + { defaults with + name = "btrfs_subvolume_delete"; added = (1, 17, 35); + style = RErr, [Pathname "subvolume"], []; + proc_nr = Some 323; + optional = Some "btrfs"; camel_name = "BTRFSSubvolumeDelete"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_subvolume_create"; "/test1"; "NOARG"]; + ["btrfs_subvolume_delete"; "/test1"]]), [] + ]; + shortdesc = "delete a btrfs subvolume or snapshot"; + longdesc = "\ +Delete the named btrfs subvolume or snapshot." }; + + { defaults with + name = "btrfs_subvolume_create"; added = (1, 17, 35); + style = RErr, [Pathname "dest"], [OString "qgroupid"]; + proc_nr = Some 324; + once_had_no_optargs = true; + optional = Some "btrfs"; camel_name = "BTRFSSubvolumeCreate"; + shortdesc = "create a btrfs subvolume"; + longdesc = "\ +Create a btrfs subvolume. The C<dest> argument is the destination +directory and the name of the subvolume, in the form F</path/to/dest/name>. +The optional parameter C<qgroupid> represents the qgroup which the newly +created subvolume will be added to." }; + + { defaults with + name = "btrfs_subvolume_list"; added = (1, 17, 35); + style = RStructList ("subvolumes", "btrfssubvolume"), [Mountable_or_Path "fs"], []; + proc_nr = Some 325; + optional = Some "btrfs"; camel_name = "BTRFSSubvolumeList"; + test_excuse = "tested in tests/btrfs"; + shortdesc = "list btrfs snapshots and subvolumes"; + longdesc = "\ +List the btrfs snapshots and subvolumes of the btrfs filesystem +which is mounted at C<fs>." }; + + { defaults with + name = "btrfs_subvolume_set_default"; added = (1, 17, 35); + style = RErr, [Int64 "id"; Pathname "fs"], []; + proc_nr = Some 326; + optional = Some "btrfs"; camel_name = "BTRFSSubvolumeSetDefault"; + test_excuse = "tested in tests/btrfs"; + shortdesc = "set default btrfs subvolume"; + longdesc = "\ +Set the subvolume of the btrfs filesystem C<fs> which will +be mounted by default. See C<guestfs_btrfs_subvolume_list> to +get a list of subvolumes." }; + + { defaults with + name = "btrfs_filesystem_sync"; added = (1, 17, 35); + style = RErr, [Pathname "fs"], []; + proc_nr = Some 327; + optional = Some "btrfs"; camel_name = "BTRFSFilesystemSync"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_subvolume_create"; "/test1"; "NOARG"]; + ["btrfs_filesystem_sync"; "/test1"]; + ["btrfs_filesystem_balance"; "/test1"]]), [] + ]; + shortdesc = "sync a btrfs filesystem"; + longdesc = "\ +Force sync on the btrfs filesystem mounted at C<fs>." }; + + { defaults with + name = "btrfs_filesystem_balance"; added = (1, 17, 35); + style = RErr, [Pathname "fs"], []; + fish_alias = ["btrfs-balance"]; + proc_nr = Some 328; + optional = Some "btrfs"; camel_name = "BTRFSFilesystemBalance"; + shortdesc = "balance a btrfs filesystem"; + longdesc = "\ +Balance the chunks in the btrfs filesystem mounted at C<fs> +across the underlying devices." }; + + { defaults with + name = "btrfs_device_add"; added = (1, 17, 35); + style = RErr, [DeviceList "devices"; Pathname "fs"], []; + proc_nr = Some 329; + optional = Some "btrfs"; camel_name = "BTRFSDeviceAdd"; + test_excuse = "test disk isn't large enough to test this thoroughly, so there is an external test in 'tests/btrfs' directory"; + shortdesc = "add devices to a btrfs filesystem"; + longdesc = "\ +Add the list of device(s) in C<devices> to the btrfs filesystem +mounted at C<fs>. If C<devices> is an empty list, this does nothing." }; + + { defaults with + name = "btrfs_device_delete"; added = (1, 17, 35); + style = RErr, [DeviceList "devices"; Pathname "fs"], []; + proc_nr = Some 330; + optional = Some "btrfs"; camel_name = "BTRFSDeviceDelete"; + test_excuse = "test disk isn't large enough to test this thoroughly, so there is an external test in 'tests/btrfs' directory."; + shortdesc = "remove devices from a btrfs filesystem"; + longdesc = "\ +Remove the C<devices> from the btrfs filesystem mounted at C<fs>. +If C<devices> is an empty list, this does nothing." }; + + { defaults with + name = "btrfs_set_seeding"; added = (1, 17, 43); + style = RErr, [Device "device"; Bool "seeding"], []; + proc_nr = Some 331; + optional = Some "btrfs"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_set_seeding"; "/dev/sda1"; "true"]; + ["btrfs_set_seeding"; "/dev/sda1"; "false"]]), [] + ]; + shortdesc = "enable or disable the seeding feature of device"; + longdesc = "\ +Enable or disable the seeding feature of a device that contains +a btrfs filesystem." }; + + { defaults with + name = "btrfs_fsck"; added = (1, 17, 43); + style = RErr, [Device "device"], [OInt64 "superblock"; OBool "repair"]; + proc_nr = Some 332; + optional = Some "btrfs"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_fsck"; "/dev/sda1"; ""; ""]]), [] + ]; + shortdesc = "check a btrfs filesystem"; + longdesc = "\ +Used to check a btrfs filesystem, C<device> is the device file where the +filesystem is stored." }; + + { defaults with + name = "filesystem_available"; added = (1, 19, 5); + style = RBool "fsavail", [String "filesystem"], []; + proc_nr = Some 333; + shortdesc = "check if filesystem is available"; + longdesc = "\ +Check whether libguestfs supports the named filesystem. +The argument C<filesystem> is a filesystem name, such as +C<ext3>. + +You must call C<guestfs_launch> before using this command. + +This is mainly useful as a negative test. If this returns true, +it doesn't mean that a particular filesystem can be created +or mounted, since filesystems can fail for other reasons +such as it being a later version of the filesystem, +or having incompatible features, or lacking the right +mkfs.E<lt>I<fs>E<gt> tool. + +See also C<guestfs_available>, C<guestfs_feature_available>, +L<guestfs(3)/AVAILABILITY>." }; + + { defaults with + name = "fstrim"; added = (1, 19, 6); + style = RErr, [Pathname "mountpoint"], [OInt64 "offset"; OInt64 "length"; OInt64 "minimumfreeextent"]; + proc_nr = Some 334; + optional = Some "fstrim"; + shortdesc = "trim free space in a filesystem"; + longdesc = "\ +Trim the free space in the filesystem mounted on C<mountpoint>. +The filesystem must be mounted read-write. + +The filesystem contents are not affected, but any free space +in the filesystem is \"trimmed\", that is, given back to the host +device, thus making disk images more sparse, allowing unused space +in qcow2 files to be reused, etc. + +This operation requires support in libguestfs, the mounted +filesystem, the host filesystem, qemu and the host kernel. +If this support isn't present it may give an error or even +appear to run but do nothing. + +In the case where the kernel vfs driver does not support +trimming, this call will fail with errno set to C<ENOTSUP>. +Currently this happens when trying to trim FAT filesystems. + +See also C<guestfs_zero_free_space>. That is a slightly +different operation that turns free space in the filesystem +into zeroes. It is valid to call C<guestfs_fstrim> either +instead of, or after calling C<guestfs_zero_free_space>." }; + + { defaults with + name = "device_index"; added = (1, 19, 7); + style = RInt "index", [Device "device"], []; + proc_nr = Some 335; + tests = [ + InitEmpty, Always, TestResult ( + [["device_index"; "/dev/sda"]], "ret == 0"), [] + ]; + shortdesc = "convert device to index"; + longdesc = "\ +This function takes a device name (eg. \"/dev/sdb\") and +returns the index of the device in the list of devices. + +Index numbers start from 0. The named device must exist, +for example as a string returned from C<guestfs_list_devices>. + +See also C<guestfs_list_devices>, C<guestfs_part_to_dev>." }; + + { defaults with + name = "nr_devices"; added = (1, 19, 15); + style = RInt "nrdisks", [], []; + proc_nr = Some 336; + tests = [ + InitEmpty, Always, TestResult ( + [["nr_devices"]], "ret == 4"), [] + ]; + shortdesc = "return number of whole block devices (disks) added"; + longdesc = "\ +This returns the number of whole block devices that were +added. This is the same as the number of devices that would +be returned if you called C<guestfs_list_devices>. + +To find out the maximum number of devices that could be added, +call C<guestfs_max_disks>." }; + + { defaults with + name = "xfs_info"; added = (1, 19, 21); + style = RStruct ("info", "xfsinfo"), [Dev_or_Path "pathordevice"], []; + proc_nr = Some 337; + optional = Some "xfs"; + tests = [ + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["xfs_info"; "/"]], "ret->xfs_blocksize == 4096"), [] + ]; + shortdesc = "get geometry of XFS filesystem"; + longdesc = "\ +C<pathordevice> is a mounted XFS filesystem or a device containing +an XFS filesystem. This command returns the geometry of the filesystem. + +The returned struct contains geometry information. Missing +fields are returned as C<-1> (for numeric fields) or empty +string." }; + + { defaults with + name = "pvchange_uuid"; added = (1, 19, 26); + style = RErr, [Device "device"], []; + proc_nr = Some 338; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["pvchange_uuid"; "/dev/sda1"]]), [] + ]; + shortdesc = "generate a new random UUID for a physical volume"; + longdesc = "\ +Generate a new random UUID for the physical volume C<device>." }; + + { defaults with + name = "pvchange_uuid_all"; added = (1, 19, 26); + style = RErr, [], []; + proc_nr = Some 339; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["pvchange_uuid_all"]]), [] + ]; + shortdesc = "generate new random UUIDs for all physical volumes"; + longdesc = "\ +Generate new random UUIDs for all physical volumes." }; + + { defaults with + name = "vgchange_uuid"; added = (1, 19, 26); + style = RErr, [String "vg"], []; + proc_nr = Some 340; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["vgchange_uuid"; "/dev/VG"]]), [] + ]; + shortdesc = "generate a new random UUID for a volume group"; + longdesc = "\ +Generate a new random UUID for the volume group C<vg>." }; + + { defaults with + name = "vgchange_uuid_all"; added = (1, 19, 26); + style = RErr, [], []; + proc_nr = Some 341; + optional = Some "lvm2"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["vgchange_uuid_all"]]), [] + ]; + shortdesc = "generate new random UUIDs for all volume groups"; + longdesc = "\ +Generate new random UUIDs for all volume groups." }; + + { defaults with + name = "utsname"; added = (1, 19, 27); + style = RStruct ("uts", "utsname"), [], []; + proc_nr = Some 342; + tests = [ + InitEmpty, Always, TestRun ( + [["utsname"]]), [] + ]; + shortdesc = "appliance kernel version"; + longdesc = "\ +This returns the kernel version of the appliance, where this is +available. This information is only useful for debugging. Nothing +in the returned structure is defined by the API." }; + + { defaults with + name = "xfs_growfs"; added = (1, 19, 28); + style = RErr, [Pathname "path"], [OBool "datasec"; OBool "logsec"; OBool "rtsec"; OInt64 "datasize"; OInt64 "logsize"; OInt64 "rtsize"; OInt64 "rtextsize"; OInt "maxpct"]; + proc_nr = Some 343; + optional = Some "xfs"; + tests = [ + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV"; "VG"; "40"]; + ["mkfs"; "xfs"; "/dev/VG/LV"; ""; "NOARG"; ""; ""; "NOARG"]; + ["lvresize"; "/dev/VG/LV"; "80"]; + ["mount"; "/dev/VG/LV"; "/"]; + ["xfs_growfs"; "/"; "true"; "false"; "false"; ""; ""; ""; ""; ""]; + ["xfs_info"; "/"]], "ret->xfs_blocksize == 4096"), []; + ]; + shortdesc = "expand an existing XFS filesystem"; + longdesc = "\ +Grow the XFS filesystem mounted at C<path>. + +The returned struct contains geometry information. Missing +fields are returned as C<-1> (for numeric fields) or empty +string." }; + + { defaults with + name = "rsync"; added = (1, 19, 29); + style = RErr, [Pathname "src"; Pathname "dest"], [OBool "archive"; OBool "deletedest"]; + proc_nr = Some 344; + optional = Some "rsync"; + test_excuse = "tests are in tests/rsync"; + shortdesc = "synchronize the contents of two directories"; + longdesc = "\ +This call may be used to copy or synchronize two directories +under the same libguestfs handle. This uses the L<rsync(1)> +program which uses a fast algorithm that avoids copying files +unnecessarily. + +C<src> and C<dest> are the source and destination directories. +Files are copied from C<src> to C<dest>. + +The optional arguments are: + +=over 4 + +=item C<archive> + +Turns on archive mode. This is the same as passing the +I<--archive> flag to C<rsync>. + +=item C<deletedest> + +Delete files at the destination that do not exist at the source. + +=back" }; + + { defaults with + name = "rsync_in"; added = (1, 19, 29); + style = RErr, [String "remote"; Pathname "dest"], [OBool "archive"; OBool "deletedest"]; + proc_nr = Some 345; + optional = Some "rsync"; + test_excuse = "tests are in tests/rsync"; + shortdesc = "synchronize host or remote filesystem with filesystem"; + longdesc = "\ +This call may be used to copy or synchronize the filesystem +on the host or on a remote computer with the filesystem +within libguestfs. This uses the L<rsync(1)> program +which uses a fast algorithm that avoids copying files unnecessarily. + +This call only works if the network is enabled. See +C<guestfs_set_network> or the I<--network> option to +various tools like L<guestfish(1)>. + +Files are copied from the remote server and directory +specified by C<remote> to the destination directory C<dest>. + +The format of the remote server string is defined by L<rsync(1)>. +Note that there is no way to supply a password or passphrase +so the target must be set up not to require one. + +The optional arguments are the same as those of C<guestfs_rsync>." }; + + { defaults with + name = "rsync_out"; added = (1, 19, 29); + style = RErr, [Pathname "src"; String "remote"], [OBool "archive"; OBool "deletedest"]; + proc_nr = Some 346; + optional = Some "rsync"; + test_excuse = "tests are in tests/rsync"; + shortdesc = "synchronize filesystem with host or remote filesystem"; + longdesc = "\ +This call may be used to copy or synchronize the filesystem within +libguestfs with a filesystem on the host or on a remote computer. +This uses the L<rsync(1)> program which uses a fast algorithm that +avoids copying files unnecessarily. + +This call only works if the network is enabled. See +C<guestfs_set_network> or the I<--network> option to +various tools like L<guestfish(1)>. + +Files are copied from the source directory C<src> to the +remote server and directory specified by C<remote>. + +The format of the remote server string is defined by L<rsync(1)>. +Note that there is no way to supply a password or passphrase +so the target must be set up not to require one. + +The optional arguments are the same as those of C<guestfs_rsync>. + +Globbing does not happen on the C<src> parameter. In programs +which use the API directly you have to expand wildcards yourself +(see C<guestfs_glob_expand>). In guestfish you can use the C<glob> +command (see L<guestfish(1)/glob>), for example: + + ><fs> glob rsync-out /* rsync://remote/" }; + + { defaults with + name = "ls0"; added = (1, 19, 32); + style = RErr, [Pathname "dir"; FileOut "filenames"], []; + proc_nr = Some 347; + shortdesc = "get list of files in a directory"; + longdesc = "\ +This specialized command is used to get a listing of +the filenames in the directory C<dir>. The list of filenames +is written to the local file F<filenames> (on the host). + +In the output file, the filenames are separated by C<\\0> characters. + +C<.> and C<..> are not returned. The filenames are not sorted." }; + + { defaults with + name = "fill_dir"; added = (1, 19, 32); + style = RErr, [Pathname "dir"; Int "nr"], []; + proc_nr = Some 348; + shortdesc = "fill a directory with empty files"; + longdesc = "\ +This function, useful for testing filesystems, creates C<nr> +empty files in the directory C<dir> with names C<00000000> +through C<nr-1> (ie. each file name is 8 digits long padded +with zeroes)." }; + + { defaults with + name = "xfs_admin"; added = (1, 19, 33); + style = RErr, [Device "device"], [OBool "extunwritten"; OBool "imgfile"; OBool "v2log"; OBool "projid32bit"; OBool "lazycounter"; OString "label"; OString "uuid"]; + proc_nr = Some 349; + optional = Some "xfs"; + tests = [ + InitEmpty, Always, TestResult ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["xfs_admin"; "/dev/sda1"; ""; ""; ""; ""; "false"; "NOARG"; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["xfs_info"; "/"]], "ret->xfs_lazycount == 0"), []; + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["xfs_admin"; "/dev/sda1"; ""; ""; ""; ""; ""; "NOARG"; stable_uuid]; + ["vfs_uuid"; "/dev/sda1"]], stable_uuid), []; + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["xfs_admin"; "/dev/sda1"; ""; ""; ""; ""; ""; "LBL-TEST"; "NOARG"]; + ["vfs_label"; "/dev/sda1"]], "LBL-TEST"), []; + ]; + shortdesc = "change parameters of an XFS filesystem"; + longdesc = "\ +Change the parameters of the XFS filesystem on C<device>. + +Devices that are mounted cannot be modified. +Administrators must unmount filesystems before this call +can modify parameters. + +Some of the parameters of a mounted filesystem can be examined +and modified using the C<guestfs_xfs_info> and +C<guestfs_xfs_growfs> calls." }; + + { defaults with + name = "xfs_repair"; added = (1, 19, 36); + style = RInt "status", [Dev_or_Path "device"], [OBool "forcelogzero"; OBool "nomodify"; OBool "noprefetch"; OBool "forcegeometry"; OInt64 "maxmem"; OInt64 "ihashsize"; OInt64 "bhashsize"; OInt64 "agstride"; OString "logdev"; OString "rtdev"]; + proc_nr = Some 366; + optional = Some "xfs"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["xfs_repair"; "/dev/sda1"; ""; "true"; ""; ""; ""; ""; ""; ""; "NOARG"; "NOARG"] + ]), [] + ]; + shortdesc = "repair an XFS filesystem"; + longdesc = "\ +Repair corrupt or damaged XFS filesystem on C<device>. + +The filesystem is specified using the C<device> argument which should be +the device name of the disk partition or volume containing the filesystem. +If given the name of a block device, C<xfs_repair> will attempt to find +the raw device associated with the specified block device and will use +the raw device instead. + +Regardless, the filesystem to be repaired must be unmounted, otherwise, +the resulting filesystem may be inconsistent or corrupt. + +The returned status indicates whether filesystem corruption was +detected (returns C<1>) or was not detected (returns C<0>)." }; + + { defaults with + name = "rm_f"; added = (1, 19, 42); + style = RErr, [Pathname "path"], []; + proc_nr = Some 367; + tests = [ + InitScratchFS, Always, TestResultFalse + [["mkdir"; "/rm_f"]; + ["touch"; "/rm_f/foo"]; + ["rm_f"; "/rm_f/foo"]; + ["rm_f"; "/rm_f/not_exists"]; + ["exists"; "/rm_f/foo"]], []; + InitScratchFS, Always, TestLastFail + [["mkdir"; "/rm_f2"]; + ["mkdir"; "/rm_f2/foo"]; + ["rm_f"; "/rm_f2/foo"]], [] + ]; + shortdesc = "remove a file ignoring errors"; + longdesc = "\ +Remove the file C<path>. + +If the file doesn't exist, that error is ignored. (Other errors, +eg. I/O errors or bad paths, are not ignored) + +This call cannot remove directories. +Use C<guestfs_rmdir> to remove an empty directory, +or C<guestfs_rm_rf> to remove directories recursively." }; + + { defaults with + name = "mke2fs"; added = (1, 19, 44); + style = RErr, [Device "device"], [OInt64 "blockscount"; OInt64 "blocksize"; OInt64 "fragsize"; OInt64 "blockspergroup"; OInt64 "numberofgroups"; OInt64 "bytesperinode"; OInt64 "inodesize"; OInt64 "journalsize"; OInt64 "numberofinodes"; OInt64 "stridesize"; OInt64 "stripewidth"; OInt64 "maxonlineresize"; OInt "reservedblockspercentage"; OInt "mmpupdateinterval"; OString "journaldevice"; OString "label"; OString "lastmounteddir"; OString "creatoros"; OString "fstype"; OString "usagetype"; OString "uuid"; OBool "forcecreate"; OBool "writesbandgrouponly"; OBool "lazyitableinit"; OBool "lazyjournalinit"; OBool "testfs"; OBool "discard"; OBool "quotatype"; OBool "extent"; OBool "filetype"; OBool "flexbg"; OBool "hasjournal"; OBool "journaldev"; OBool "largefile"; OBool "quota"; OBool "resizeinode"; OBool "sparsesuper"; OBool "uninitbg"]; + proc_nr = Some 368; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; + ["mke2fs"; "/dev/sda1"; ""; "4096"; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; "NOARG"; + "NOARG"; "NOARG"; "NOARG"; "NOARG"; "NOARG"; + "NOARG"; ""; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; "true"; ""; ""; + ""; ""; ""]; + ["mke2fs"; "/dev/sda2"; ""; "4096"; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; "/dev/sda1"; + "NOARG"; "NOARG"; "NOARG"; "ext2"; "NOARG"; + "NOARG"; ""; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""]; + ["mount"; "/dev/sda2"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents"), []; + InitEmpty, Always, TestResultString ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; + ["mke2fs"; "/dev/sda1"; ""; "4096"; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; "/dev/sda1"; + "JOURNAL"; "NOARG"; "NOARG"; "ext2"; "NOARG"; + "NOARG"; ""; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; "true"; ""; ""; + ""; ""; ""]; + ["mke2fs"; "/dev/sda2"; ""; "4096"; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; "LABEL=JOURNAL"; + "JOURNAL"; "NOARG"; "NOARG"; "ext2"; "NOARG"; + "NOARG"; ""; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""]; + ["mount"; "/dev/sda2"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents"), []; + InitEmpty, Always, TestResultString ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; + ["mke2fs"; "/dev/sda1"; ""; "4096"; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; "NOARG"; + "NOARG"; "NOARG"; "NOARG"; "NOARG"; "NOARG"; + stable_uuid; ""; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; "true"; ""; ""; + ""; ""; ""]; + ["mke2fs"; "/dev/sda2"; ""; "4096"; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; "UUID=" ^ stable_uuid; + "JOURNAL"; "NOARG"; "NOARG"; "ext2"; "NOARG"; + "NOARG"; "true"; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""; ""; ""; + ""; ""; ""]; + ["mount"; "/dev/sda2"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents"), [] + ]; + shortdesc = "create an ext2/ext3/ext4 filesystem on device"; + (* XXX document optional args properly *) + longdesc = "\ +C<mke2fs> is used to create an ext2, ext3, or ext4 filesystem +on C<device>. + +The optional C<blockscount> is the size of the filesystem in blocks. +If omitted it defaults to the size of C<device>. Note if the +filesystem is too small to contain a journal, C<mke2fs> will +silently create an ext2 filesystem instead." }; + + { defaults with + name = "list_disk_labels"; added = (1, 19, 49); + style = RHashtable "labels", [], []; + proc_nr = Some 369; + tests = [ + (* The test disks have no labels, so we can be sure there are + * no labels. See in tests/disk-labels/ for tests checking + * for actual disk labels. + * + * Also, we make use of the assumption that RHashtable is a + * char*[] in C, so an empty hash has just a NULL element. + *) + InitScratchFS, Always, TestResult ( + [["list_disk_labels"]], + "is_string_list (ret, 0)"), []; + ]; + shortdesc = "mapping of disk labels to devices"; + longdesc = "\ +If you add drives using the optional C<label> parameter +of C<guestfs_add_drive_opts>, you can use this call to +map between disk labels, and raw block device and partition +names (like F</dev/sda> and F</dev/sda1>). + +This returns a hashtable, where keys are the disk labels +(I<without> the F</dev/disk/guestfs> prefix), and the values +are the full raw block device and partition names +(eg. F</dev/sda> and F</dev/sda1>)." }; + + { defaults with + name = "internal_hot_add_drive"; added = (1, 19, 49); + style = RErr, [String "label"], []; + proc_nr = Some 370; + visibility = VInternal; + shortdesc = "internal hotplugging operation"; + longdesc = "\ +This function is used internally when hotplugging drives." }; + + { defaults with + name = "internal_hot_remove_drive_precheck"; added = (1, 19, 49); + style = RErr, [String "label"], []; + proc_nr = Some 371; + visibility = VInternal; + shortdesc = "internal hotplugging operation"; + longdesc = "\ +This function is used internally when hotplugging drives." }; + + { defaults with + name = "internal_hot_remove_drive"; added = (1, 19, 49); + style = RErr, [String "label"], []; + proc_nr = Some 372; + visibility = VInternal; + shortdesc = "internal hotplugging operation"; + longdesc = "\ +This function is used internally when hotplugging drives." }; + + { defaults with + name = "mktemp"; added = (1, 19, 53); + style = RString "path", [Pathname "tmpl"], [OString "suffix"]; + proc_nr = Some 373; + tests = [ + InitScratchFS, Always, TestRun ( + [["mkdir"; "/mktemp"]; + ["mktemp"; "/mktemp/tmpXXXXXX"; "NOARG"]; + ["mktemp"; "/mktemp/tmpXXXXXX"; "suff"]]), [] + ]; + shortdesc = "create a temporary file"; + longdesc = "\ +This command creates a temporary file. The +C<tmpl> parameter should be a full pathname for the +temporary directory name with the final six characters being +\"XXXXXX\". + +For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\", +the second one being suitable for Windows filesystems. + +The name of the temporary file that was created +is returned. + +The temporary file is created with mode 0600 +and is owned by root. + +The caller is responsible for deleting the temporary +file after use. + +If the optional C<suffix> parameter is given, then the suffix +(eg. C<.txt>) is appended to the temporary name. + +See also: C<guestfs_mkdtemp>." }; + + { defaults with + name = "mklost_and_found"; added = (1, 19, 56); + style = RErr, [Pathname "mountpoint"], []; + proc_nr = Some 374; + tests = [ + InitBasicFS, Always, TestRun ( + [["rm_rf"; "/lost+found"]; + ["mklost_and_found"; "/"]]), [] + ]; + shortdesc = "make lost+found directory on an ext2/3/4 filesystem"; + longdesc = "\ +Make the C<lost+found> directory, normally in the root directory +of an ext2/3/4 filesystem. C<mountpoint> is the directory under +which we try to create the C<lost+found> directory." }; + + { defaults with + name = "acl_get_file"; added = (1, 19, 63); + style = RString "acl", [Pathname "path"; String "acltype"], []; + proc_nr = Some 375; + optional = Some "acl"; + shortdesc = "get the POSIX ACL attached to a file"; + longdesc = "\ +This function returns the POSIX Access Control List (ACL) attached +to C<path>. The ACL is returned in \"long text form\" (see L<acl(5)>). + +The C<acltype> parameter may be: + +=over 4 + +=item C<access> + +Return the ordinary (access) ACL for any file, directory or +other filesystem object. + +=item C<default> + +Return the default ACL. Normally this only makes sense if +C<path> is a directory. + +=back" }; + + { defaults with + name = "acl_set_file"; added = (1, 19, 63); + style = RErr, [Pathname "path"; String "acltype"; String "acl"], []; + proc_nr = Some 376; + optional = Some "acl"; + tests = [ + InitScratchFS, Always, TestRun ( + [["touch"; "/acl_set_file_0"]; + ["acl_set_file"; "/acl_set_file_0"; "access"; "u::r-x,g::r-x,o::r-x"]; + ["acl_get_file"; "/acl_set_file_0"; "access"]]), []; + InitScratchFS, Always, TestRun ( + [["touch"; "/acl_set_file_1"]; + ["acl_set_file"; "/acl_set_file_1"; "access"; "u::r-x,g::r-x,o::r-x,m::rwx,u:500:rw,g:600:x"]]), []; + InitScratchFS, Always, TestLastFail ( + [["touch"; "/acl_set_file_2"]; + (* m (mask) entry is required when setting user or group ACLs *) + ["acl_set_file"; "/acl_set_file_2"; "access"; "u::r-x,g::r-x,o::r-x,u:500:rw,g:600:x"]]), []; + InitScratchFS, Always, TestLastFail ( + [["touch"; "/acl_set_file_3"]; + (* user does not exist *) + ["acl_set_file"; "/acl_set_file_3"; "access"; "u::r-x,g::r-x,o::r-x,m::rwx,u:notauser:rw"]]), []; + InitScratchFS, Always, TestLastFail ( + [["touch"; "/acl_set_file_4"]; + (* cannot set default on a non-directory *) + ["acl_set_file"; "/acl_set_file_4"; "default"; "u::r-x,g::r-x,o::r-x"]]), []; + InitScratchFS, Always, TestRun ( + [["mkdir"; "/acl_set_file_5"]; + ["acl_set_file"; "/acl_set_file_5"; "default"; "u::r-x,g::r-x,o::r-x"]]), []; + ]; + shortdesc = "set the POSIX ACL attached to a file"; + longdesc = "\ +This function sets the POSIX Access Control List (ACL) attached +to C<path>. + +The C<acltype> parameter may be: + +=over 4 + +=item C<access> + +Set the ordinary (access) ACL for any file, directory or +other filesystem object. + +=item C<default> + +Set the default ACL. Normally this only makes sense if +C<path> is a directory. + +=back + +The C<acl> parameter is the new ACL in either \"long text form\" +or \"short text form\" (see L<acl(5)>). The new ACL completely +replaces any previous ACL on the file. The ACL must contain the +full Unix permissions (eg. C<u::rwx,g::rx,o::rx>). + +If you are specifying individual users or groups, then the +mask field is also required (eg. C<m::rwx>), followed by the +C<u:I<ID>:...> and/or C<g:I<ID>:...> field(s). A full ACL +string might therefore look like this: + + u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx + \\ Unix permissions / \\mask/ \\ ACL / + +You should use numeric UIDs and GIDs. To map usernames and +groupnames to the correct numeric ID in the context of the +guest, use the Augeas functions (see C<guestfs_aug_init>)." }; + + { defaults with + name = "acl_delete_def_file"; added = (1, 19, 63); + style = RErr, [Pathname "dir"], []; + proc_nr = Some 377; + optional = Some "acl"; + tests = [ + (* Documentation for libacl says this should fail, but it doesn't. + * Therefore disable this test. + *) + InitScratchFS, Disabled, TestLastFail ( + [["touch"; "/acl_delete_def_file_0"]; + ["acl_delete_def_file"; "/acl_delete_def_file_0"]]), []; + InitScratchFS, Always, TestRun ( + [["mkdir"; "/acl_delete_def_file_1"]; + ["acl_set_file"; "/acl_delete_def_file_1"; "default"; "user::r-x,group::r-x,other::r-x"]; + ["acl_delete_def_file"; "/acl_delete_def_file_1"]]), []; + ]; + shortdesc = "delete the default POSIX ACL of a directory"; + longdesc = "\ +This function deletes the default POSIX Access Control List (ACL) +attached to directory C<dir>." }; + + { defaults with + name = "cap_get_file"; added = (1, 19, 63); + style = RString "cap", [Pathname "path"], []; + proc_nr = Some 378; + optional = Some "linuxcaps"; + shortdesc = "get the Linux capabilities attached to a file"; + longdesc = "\ +This function returns the Linux capabilities attached to C<path>. +The capabilities set is returned in text form (see L<cap_to_text(3)>). + +If no capabilities are attached to a file, an empty string is returned." }; + + { defaults with + name = "cap_set_file"; added = (1, 19, 63); + style = RErr, [Pathname "path"; String "cap"], []; + proc_nr = Some 379; + optional = Some "linuxcaps"; + tests = [ + InitScratchFS, Always, TestResultString ( + [["touch"; "/cap_set_file_0"]; + ["cap_set_file"; "/cap_set_file_0"; "cap_chown=p cap_chown+e"]; + ["cap_get_file"; "/cap_set_file_0"]], "= cap_chown+ep"), []; + ]; + shortdesc = "set the Linux capabilities attached to a file"; + longdesc = "\ +This function sets the Linux capabilities attached to C<path>. +The capabilities set C<cap> should be passed in text form +(see L<cap_from_text(3)>)." }; + + { defaults with + name = "list_ldm_volumes"; added = (1, 20, 0); + style = RStringList "devices", [], []; + proc_nr = Some 380; + optional = Some "ldm"; + shortdesc = "list all Windows dynamic disk volumes"; + longdesc = "\ +This function returns all Windows dynamic disk volumes +that were found at launch time. It returns a list of +device names." }; + + { defaults with + name = "list_ldm_partitions"; added = (1, 20, 0); + style = RStringList "devices", [], []; + proc_nr = Some 381; + optional = Some "ldm"; + shortdesc = "list all Windows dynamic disk partitions"; + longdesc = "\ +This function returns all Windows dynamic disk partitions +that were found at launch time. It returns a list of +device names." }; + + { defaults with + name = "ldmtool_create_all"; added = (1, 20, 0); + style = RErr, [], []; + proc_nr = Some 382; + optional = Some "ldm"; + shortdesc = "scan and create Windows dynamic disk volumes"; + longdesc = "\ +This function scans all block devices looking for Windows +dynamic disk volumes and partitions, and creates devices +for any that were found. + +Call C<guestfs_list_ldm_volumes> and C<guestfs_list_ldm_partitions> +to return all devices. + +Note that you B<don't> normally need to call this explicitly, +since it is done automatically at C<guestfs_launch> time. +However you might want to call this function if you have +hotplugged disks or have just created a Windows dynamic disk." }; + + { defaults with + name = "ldmtool_remove_all"; added = (1, 20, 0); + style = RErr, [], []; + proc_nr = Some 383; + optional = Some "ldm"; + shortdesc = "remove all Windows dynamic disk volumes"; + longdesc = "\ +This is essentially the opposite of C<guestfs_ldmtool_create_all>. +It removes the device mapper mappings for all Windows dynamic disk +volumes" }; + + { defaults with + name = "ldmtool_scan"; added = (1, 20, 0); + style = RStringList "guids", [], []; + proc_nr = Some 384; + optional = Some "ldm"; + shortdesc = "scan for Windows dynamic disks"; + longdesc = "\ +This function scans for Windows dynamic disks. It returns a list +of identifiers (GUIDs) for all disk groups that were found. These +identifiers can be passed to other C<guestfs_ldmtool_*> functions. + +This function scans all block devices. To scan a subset of +block devices, call C<guestfs_ldmtool_scan_devices> instead." }; + + { defaults with + name = "ldmtool_scan_devices"; added = (1, 20, 0); + style = RStringList "guids", [DeviceList "devices"], []; + proc_nr = Some 385; + optional = Some "ldm"; + shortdesc = "scan for Windows dynamic disks"; + longdesc = "\ +This function scans for Windows dynamic disks. It returns a list +of identifiers (GUIDs) for all disk groups that were found. These +identifiers can be passed to other C<guestfs_ldmtool_*> functions. + +The parameter C<devices> is a list of block devices which are +scanned. If this list is empty, all block devices are scanned." }; + + { defaults with + name = "ldmtool_diskgroup_name"; added = (1, 20, 0); + style = RString "name", [String "diskgroup"], []; + proc_nr = Some 386; + optional = Some "ldm"; + shortdesc = "return the name of a Windows dynamic disk group"; + longdesc = "\ +Return the name of a Windows dynamic disk group. The C<diskgroup> +parameter should be the GUID of a disk group, one element from +the list returned by C<guestfs_ldmtool_scan>." }; + + { defaults with + name = "ldmtool_diskgroup_volumes"; added = (1, 20, 0); + style = RStringList "volumes", [String "diskgroup"], []; + proc_nr = Some 387; + optional = Some "ldm"; + shortdesc = "return the volumes in a Windows dynamic disk group"; + longdesc = "\ +Return the volumes in a Windows dynamic disk group. The C<diskgroup> +parameter should be the GUID of a disk group, one element from +the list returned by C<guestfs_ldmtool_scan>." }; + + { defaults with + name = "ldmtool_diskgroup_disks"; added = (1, 20, 0); + style = RStringList "disks", [String "diskgroup"], []; + proc_nr = Some 388; + optional = Some "ldm"; + shortdesc = "return the disks in a Windows dynamic disk group"; + longdesc = "\ +Return the disks in a Windows dynamic disk group. The C<diskgroup> +parameter should be the GUID of a disk group, one element from +the list returned by C<guestfs_ldmtool_scan>." }; + + { defaults with + name = "ldmtool_volume_type"; added = (1, 20, 0); + style = RString "voltype", [String "diskgroup"; String "volume"], []; + proc_nr = Some 389; + optional = Some "ldm"; + shortdesc = "return the type of a Windows dynamic disk volume"; + longdesc = "\ +Return the type of the volume named C<volume> in the disk +group with GUID C<diskgroup>. + +Possible volume types that can be returned here include: +C<simple>, C<spanned>, C<striped>, C<mirrored>, C<raid5>. +Other types may also be returned." }; + + { defaults with + name = "ldmtool_volume_hint"; added = (1, 20, 0); + style = RString "hint", [String "diskgroup"; String "volume"], []; + proc_nr = Some 390; + optional = Some "ldm"; + shortdesc = "return the hint field of a Windows dynamic disk volume"; + longdesc = "\ +Return the hint field of the volume named C<volume> in the disk +group with GUID C<diskgroup>. This may not be defined, in which +case the empty string is returned. The hint field is often, though +not always, the name of a Windows drive, eg. C<E:>." }; + + { defaults with + name = "ldmtool_volume_partitions"; added = (1, 20, 0); + style = RStringList "partitions", [String "diskgroup"; String "volume"], []; + proc_nr = Some 391; + optional = Some "ldm"; + shortdesc = "return the partitions in a Windows dynamic disk volume"; + longdesc = "\ +Return the list of partitions in the volume named C<volume> in the disk +group with GUID C<diskgroup>." }; + + { defaults with + name = "part_set_gpt_type"; added = (1, 21, 1); + style = RErr, [Device "device"; Int "partnum"; GUID "guid"], []; + proc_nr = Some 392; + optional = Some "gdisk"; + tests = [ + InitGPT, Always, TestLastFail ( + [["part_set_gpt_type"; "/dev/sda"; "1"; "f"]]), []; + InitGPT, Always, TestResultString ( + [["part_set_gpt_type"; "/dev/sda"; "1"; + "01234567-89AB-CDEF-0123-456789ABCDEF"]; + ["part_get_gpt_type"; "/dev/sda"; "1"]], + "01234567-89AB-CDEF-0123-456789ABCDEF"), []; + ]; + shortdesc = "set the type GUID of a GPT partition"; + longdesc = "\ +Set the type GUID of numbered GPT partition C<partnum> to C<guid>. Return an +error if the partition table of C<device> isn't GPT, or if C<guid> is not a +valid GUID. + +See L<http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUI... +for a useful list of type GUIDs." }; + + { defaults with + name = "part_get_gpt_type"; added = (1, 21, 1); + style = RString "guid", [Device "device"; Int "partnum"], []; + proc_nr = Some 393; + optional = Some "gdisk"; + tests = [ + InitGPT, Always, TestResultString ( + [["part_set_gpt_type"; "/dev/sda"; "1"; + "01234567-89AB-CDEF-0123-456789ABCDEF"]; + ["part_get_gpt_type"; "/dev/sda"; "1"]], + "01234567-89AB-CDEF-0123-456789ABCDEF"), []; + ]; + shortdesc = "get the type GUID of a GPT partition"; + longdesc = "\ +Return the type GUID of numbered GPT partition C<partnum>. For MBR partitions, +return an appropriate GUID corresponding to the MBR type. Behaviour is undefined +for other partition types." }; + + { defaults with + name = "rename"; added = (1, 21, 5); + style = RErr, [Pathname "oldpath"; Pathname "newpath"], []; + proc_nr = Some 394; + tests = [ + InitScratchFS, Always, TestResultFalse ( + [["mkdir"; "/rename"]; + ["write"; "/rename/old"; "file content"]; + ["rename"; "/rename/old"; "/rename/new"]; + ["is_file"; "/rename/old"; ""]]), [] + ]; + shortdesc = "rename a file on the same filesystem"; + longdesc = "\ +Rename a file to a new place on the same filesystem. This is +the same as the Linux L<rename(2)> system call. In most cases +you are better to use C<guestfs_mv> instead." }; + + { defaults with + name = "is_whole_device"; added = (1, 21, 9); + style = RBool "flag", [Device "device"], []; + proc_nr = Some 395; + tests = [ + InitEmpty, Always, TestResultTrue ( + [["is_whole_device"; "/dev/sda"]]), []; + InitPartition, Always, TestResultFalse ( + [["is_whole_device"; "/dev/sda1"]]), []; + InitBasicFSonLVM, Always, TestResultFalse ( + [["is_whole_device"; "/dev/VG/LV"]]), []; + ]; + shortdesc = "test if a device is a whole device"; + longdesc = "\ +This returns C<true> if and only if C<device> refers to a whole block +device. That is, not a partition or a logical device." }; + + { defaults with + name = "internal_parse_mountable"; added = (1, 21, 11); + style = RStruct ("mountable", "internal_mountable"), [Mountable "mountable"], []; + visibility = VInternal; + proc_nr = Some 396; + shortdesc = "parse a mountable string"; + longdesc = "\ +Parse a mountable string." }; + + { defaults with + name = "internal_rhbz914931"; added = (1, 21, 14); + style = RErr, [FileIn "filename"; Int "count"], []; + proc_nr = Some 397; + visibility = VInternal; + cancellable = true; + shortdesc = "used only to test rhbz914931 (internal use only)"; + longdesc = "\ +This is only used to debug RHBZ#914931. Note that this +deliberately crashes guestfsd." }; + + { defaults with + name = "syslinux"; added = (1, 21, 27); + style = RErr, [Device "device"], [OString "directory"]; + proc_nr = Some 399; + optional = Some "syslinux"; + shortdesc = "install the SYSLINUX bootloader"; + longdesc = "\ +Install the SYSLINUX bootloader on C<device>. + +The device parameter must be either a whole disk formatted +as a FAT filesystem, or a partition formatted as a FAT filesystem. +In the latter case, the partition should be marked as \"active\" +(C<guestfs_part_set_bootable>) and a Master Boot Record must be +installed (eg. using C<guestfs_pwrite_device>) on the first +sector of the whole disk. +The SYSLINUX package comes with some suitable Master Boot Records. +See the L<syslinux(1)> man page for further information. + +The optional arguments are: + +=over 4 + +=item F<directory> + +Install SYSLINUX in the named subdirectory, instead of in the +root directory of the FAT filesystem. + +=back + +Additional configuration can be supplied to SYSLINUX by +placing a file called F<syslinux.cfg> on the FAT filesystem, +either in the root directory, or under F<directory> if that +optional argument is being used. For further information +about the contents of this file, see L<syslinux(1)>. + +See also C<guestfs_extlinux>." }; + + { defaults with + name = "extlinux"; added = (1, 21, 27); + style = RErr, [Pathname "directory"], []; + proc_nr = Some 400; + optional = Some "extlinux"; + shortdesc = "install the SYSLINUX bootloader on an ext2/3/4 or btrfs filesystem"; + longdesc = "\ +Install the SYSLINUX bootloader on the device mounted at F<directory>. +Unlike C<guestfs_syslinux> which requires a FAT filesystem, this can +be used on an ext2/3/4 or btrfs filesystem. + +The F<directory> parameter can be either a mountpoint, or a +directory within the mountpoint. + +You also have to mark the partition as \"active\" +(C<guestfs_part_set_bootable>) and a Master Boot Record must +be installed (eg. using C<guestfs_pwrite_device>) on the first +sector of the whole disk. +The SYSLINUX package comes with some suitable Master Boot Records. +See the L<extlinux(1)> man page for further information. + +Additional configuration can be supplied to SYSLINUX by +placing a file called F<extlinux.conf> on the filesystem +under F<directory>. For further information +about the contents of this file, see L<extlinux(1)>. + +See also C<guestfs_syslinux>." }; + + { defaults with + name = "cp_r"; added = (1, 21, 38); + style = RErr, [Pathname "src"; Pathname "dest"], []; + proc_nr = Some 401; + tests = [ + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/cp_r1"]; + ["mkdir"; "/cp_r2"]; + ["write"; "/cp_r1/file"; "file content"]; + ["cp_r"; "/cp_r1"; "/cp_r2"]; + ["cat"; "/cp_r2/cp_r1/file"]], "file content"), [] + ]; + shortdesc = "copy a file or directory recursively"; + longdesc = "\ +This copies a file or directory from C<src> to C<dest> +recursively using the C<cp -rP> command. + +Most users should use C<guestfs_cp_a> instead. This command +is useful when you don't want to preserve permissions, because +the target filesystem does not support it (primarily when +writing to DOS FAT filesystems)." }; + + { defaults with + name = "remount"; added = (1, 23, 2); + style = RErr, [Pathname "mountpoint"], [OBool "rw"]; + proc_nr = Some 402; + tests = [ + InitScratchFS, Always, TestLastFail ( + [["remount"; "/"; "false"]; + ["write"; "/remount1"; "data"]]), []; + InitScratchFS, Always, TestRun ( + [["remount"; "/"; "false"]; + ["remount"; "/"; "true"]; + ["write"; "/remount2"; "data"]]), [] + ]; + shortdesc = "remount a filesystem with different options"; + longdesc = "\ +This call allows you to change the C<rw> (readonly/read-write) +flag on an already mounted filesystem at C<mountpoint>, +converting a readonly filesystem to be read-write, or vice-versa. + +Note that at the moment you must supply the \"optional\" C<rw> +parameter. In future we may allow other flags to be adjusted." }; + + { defaults with + name = "set_uuid"; added = (1, 23, 10); + style = RErr, [Device "device"; String "uuid"], []; + proc_nr = Some 403; + tests = [ + InitBasicFS, Always, TestResultString ( + [["set_uuid"; "/dev/sda1"; stable_uuid]; + ["vfs_uuid"; "/dev/sda1"]], stable_uuid), []; + ]; + shortdesc = "set the filesystem UUID"; + longdesc = "\ +Set the filesystem UUID on C<device> to C<uuid>. +If this fails and the errno is ENOTSUP, +means that there is no support for changing the UUID +for the type of the specified filesystem. + +Only some filesystem types support setting UUIDs. + +To read the UUID on a filesystem, call C<guestfs_vfs_uuid>." }; + + { defaults with + name = "journal_open"; added = (1, 23, 11); + style = RErr, [Pathname "directory"], []; + proc_nr = Some 404; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "open the systemd journal"; + longdesc = "\ +Open the systemd journal located in F<directory>. Any previously +opened journal handle is closed. + +The contents of the journal can be read using C<guestfs_journal_next> +and C<guestfs_journal_get>. + +After you have finished using the journal, you should close the +handle by calling C<guestfs_journal_close>." }; + + { defaults with + name = "journal_close"; added = (1, 23, 11); + style = RErr, [], []; + proc_nr = Some 405; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "close the systemd journal"; + longdesc = "\ +Close the journal handle." }; + + { defaults with + name = "journal_next"; added = (1, 23, 11); + style = RBool "more", [], []; + proc_nr = Some 406; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "move to the next journal entry"; + longdesc = "\ +Move to the next journal entry. You have to call this +at least once after opening the handle before you are able +to read data. + +The returned boolean tells you if there are any more journal +records to read. C<true> means you can read the next record +(eg. using C<guestfs_journal_get>), and C<false> means you +have reached the end of the journal." }; + + { defaults with + name = "journal_skip"; added = (1, 23, 11); + style = RInt64 "rskip", [Int64 "skip"], []; + proc_nr = Some 407; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "skip forwards or backwards in the journal"; + longdesc = "\ +Skip forwards (C<skip E<ge> 0>) or backwards (C<skip E<lt> 0>) in the +journal. + +The number of entries actually skipped is returned (note S<C<rskip E<ge> 0>>). +If this is not the same as the absolute value of the skip parameter +(C<|skip|>) you passed in then it means you have reached the end or +the start of the journal." }; + + { defaults with + name = "internal_journal_get"; added = (1, 23, 11); + style = RErr, [FileOut "filename"], []; + proc_nr = Some 408; + visibility = VInternal; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "internal journal reading operation"; + longdesc = "\ +This function is used internally when reading the journal." }; + + { defaults with + name = "journal_get_data_threshold"; added = (1, 23, 11); + style = RInt64 "threshold", [], []; + proc_nr = Some 409; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "get the data threshold for reading journal entries"; + longdesc = "\ +Get the current data threshold for reading journal entries. +This is a hint to the journal that it may truncate data fields to +this size when reading them (note also that it may not truncate them). +If this returns C<0>, then the threshold is unlimited. + +See also C<guestfs_journal_set_data_threshold>." }; + + { defaults with + name = "journal_set_data_threshold"; added = (1, 23, 11); + style = RErr, [Int64 "threshold"], []; + proc_nr = Some 410; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "set the data threshold for reading journal entries"; + longdesc = "\ +Set the data threshold for reading journal entries. +This is a hint to the journal that it may truncate data fields to +this size when reading them (note also that it may not truncate them). +If you set this to C<0>, then the threshold is unlimited. + +See also C<guestfs_journal_get_data_threshold>." }; + + { defaults with + name = "aug_setm"; added = (1, 23, 14); + style = RInt "nodes", [String "base"; OptString "sub"; String "val"], []; + proc_nr = Some 411; + tests = [ + InitBasicFS, Always, TestResultString ( + [["mkdir"; "/etc"]; + ["write"; "/etc/passwd"; "root:x:0:0:root:/root:/bin/bash\nbin:x:1:1:bin:/bin:/sbin/nologin\ndaemon:x:2:2:daemon:/sbin:/bin/csh\n"]; + ["aug_init"; "/"; "0"]; + ["aug_setm"; "/files/etc/passwd/*"; "shell"; "/sbin/nologin"]; + ["aug_save"]; + ["cat"; "/etc/passwd"]], "root:x:0:0:root:/root:/sbin/nologin\nbin:x:1:1:bin:/bin:/sbin/nologin\ndaemon:x:2:2:daemon:/sbin:/sbin/nologin\n"), [["aug_close"]] + ]; + shortdesc = "set multiple Augeas nodes"; + longdesc = "\ +Change multiple Augeas nodes in a single operation. C<base> is +an expression matching multiple nodes. C<sub> is a path expression +relative to C<base>. All nodes matching C<base> are found, and then +for each node, C<sub> is changed to C<val>. C<sub> may also be C<NULL> +in which case the C<base> nodes are modified. + +This returns the number of nodes modified." }; + + { defaults with + name = "aug_label"; added = (1, 23, 14); + style = RString "label", [String "augpath"], []; + proc_nr = Some 412; + tests = [ + InitBasicFS, Always, TestResultString ( + [["mkdir"; "/etc"]; + ["write"; "/etc/passwd"; "root:x:0:0:root:/root:/bin/bash\nbin:x:1:1:bin:/bin:/sbin/nologin\ndaemon:x:2:2:daemon:/sbin:/bin/csh\n"]; + ["aug_init"; "/"; "0"]; + ["aug_label"; "/files/etc/passwd/*[last()]"]], "daemon"), [["aug_close"]] + ]; + shortdesc = "return the label from an Augeas path expression"; + longdesc = "\ +The label (name of the last element) of the Augeas path expression +C<augpath> is returned. C<augpath> must match exactly one node, else +this function returns an error." }; + + { defaults with + name = "internal_upload"; added = (1, 23, 30); + style = RErr, [FileIn "filename"; String "tmpname"; Int "mode"], []; + proc_nr = Some 413; + visibility = VInternal; + cancellable = true; + shortdesc = "upload a file to the appliance (internal use only)"; + longdesc = "\ +This function is used internally when setting up the appliance." }; + + { defaults with + name = "internal_exit"; added = (1, 23, 30); + style = RErr, [], []; + proc_nr = Some 414; + (* Really VInternal, but we need to use it from the Perl bindings. XXX *) + visibility = VDebug; + cancellable = true; + shortdesc = "cause the daemon to exit (internal use only)"; + longdesc = "\ +This function is used internally when testing the appliance." }; + + { defaults with + name = "copy_attributes"; added = (1, 25, 21); + style = RErr, [Pathname "src"; Pathname "dest"], [OBool "all"; OBool "mode"; OBool "xattributes"; OBool "ownership"]; + proc_nr = Some 415; + shortdesc = "copy the attributes of a path (file/directory) to another"; + longdesc = "\ +Copy the attributes of a path (which can be a file or a directory) +to another path. + +By default C<no> attribute is copied, so make sure to specify any +(or C<all> to copy everything). + +The optional arguments specify which attributes can be copied: + +=over 4 + +=item C<mode> + +Copy part of the file mode from C<source> to C<destination>. Only the +UNIX permissions and the sticky/setuid/setgid bits can be copied. + +=item C<xattributes> + +Copy the Linux extended attributes (xattrs) from C<source> to C<destination>. +This flag does nothing if the I<linuxxattrs> feature is not available +(see C<guestfs_feature_available>). + +=item C<ownership> + +Copy the owner uid and the group gid of C<source> to C<destination>. + +=item C<all> + +Copy B<all> the attributes from C<source> to C<destination>. Enabling it +enables all the other flags, if they are not specified already. + +=back" }; + + { defaults with + name = "part_get_name"; added = (1, 25, 33); + style = RString "name", [Device "device"; Int "partnum"], []; + proc_nr = Some 416; + shortdesc = "get partition name"; + longdesc = "\ +This gets the partition name on partition numbered C<partnum> on +device C<device>. Note that partitions are numbered from 1. + +The partition name can only be read on certain types of partition +table. This works on C<gpt> but not on C<mbr> partitions." }; + + { defaults with + name = "blkdiscard"; added = (1, 25, 44); + style = RErr, [Device "device"], []; + proc_nr = Some 417; + optional = Some "blkdiscard"; + shortdesc = "discard all blocks on a device"; + longdesc = "\ +This discards all blocks on the block device C<device>, giving +the free space back to the host. + +This operation requires support in libguestfs, the host filesystem, +qemu and the host kernel. If this support isn't present it may give +an error or even appear to run but do nothing. You must also +set the C<discard> attribute on the underlying drive (see +C<guestfs_add_drive_opts>)." }; + + { defaults with + name = "blkdiscardzeroes"; added = (1, 25, 44); + style = RBool "zeroes", [Device "device"], []; + proc_nr = Some 418; + optional = Some "blkdiscardzeroes"; + shortdesc = "return true if discarded blocks are read as zeroes"; + longdesc = "\ +This call returns true if blocks on C<device> that have been +discarded by a call to C<guestfs_blkdiscard> are returned as +blocks of zero bytes when read the next time. + +If it returns false, then it may be that discarded blocks are +read as stale or random data." }; + + { defaults with + name = "cpio_out"; added = (1, 27, 9); + style = RErr, [String "directory"; FileOut "cpiofile"], [OString "format"]; + proc_nr = Some 419; + cancellable = true; + shortdesc = "pack directory into cpio file"; + longdesc = "\ +This command packs the contents of F<directory> and downloads +it to local file C<cpiofile>. + +The optional C<format> parameter can be used to select the format. +Only the following formats are currently permitted: + +=over 4 + +=item C<newc> + +New (SVR4) portable format. This format happens to be compatible +with the cpio-like format used by the Linux kernel for initramfs. + +This is the default format. + +=item C<crc> + +New (SVR4) portable format with a checksum. + +=back" }; + + { defaults with + name = "journal_get_realtime_usec"; added = (1, 27, 18); + style = RInt64 "usec", [], []; + proc_nr = Some 420; + optional = Some "journal"; + test_excuse = "tests in tests/journal subdirectory"; + shortdesc = "get the timestamp of the current journal entry"; + longdesc = "\ +Get the realtime (wallclock) timestamp of the current journal entry." }; + + { defaults with + name = "statns"; added = (1, 27, 53); + style = RStruct ("statbuf", "statns"), [Pathname "path"], []; + proc_nr = Some 421; + tests = [ + InitISOFS, Always, TestResult ( + [["statns"; "/empty"]], "ret->st_size == 0"), [] + ]; + shortdesc = "get file information"; + longdesc = "\ +Returns file information for the given C<path>. + +This is the same as the L<stat(2)> system call." }; + + { defaults with + name = "lstatns"; added = (1, 27, 53); + style = RStruct ("statbuf", "statns"), [Pathname "path"], []; + proc_nr = Some 422; + tests = [ + InitISOFS, Always, TestResult ( + [["lstatns"; "/empty"]], "ret->st_size == 0"), [] + ]; + shortdesc = "get file information for a symbolic link"; + longdesc = "\ +Returns file information for the given C<path>. + +This is the same as C<guestfs_statns> except that if C<path> +is a symbolic link, then the link is stat-ed, not the file it +refers to. + +This is the same as the L<lstat(2)> system call." }; + + { defaults with + name = "internal_lstatnslist"; added = (1, 27, 53); + style = RStructList ("statbufs", "statns"), [Pathname "path"; FilenameList "names"], []; + proc_nr = Some 423; + visibility = VInternal; + shortdesc = "lstat on multiple files"; + longdesc = "\ +This is the internal call which implements C<guestfs_lstatnslist>." }; + + { defaults with + name = "blockdev_setra"; added = (1, 29, 10); + style = RErr, [Device "device"; Int "sectors"], []; + proc_nr = Some 424; + tests = [ + InitEmpty, Always, TestRun ( + [["blockdev_setra"; "/dev/sda"; "1024" ]]), [] + ]; + shortdesc = "set readahead"; + longdesc = "\ +Set readahead (in 512-byte sectors) for the device. + +This uses the L<blockdev(8)> command." }; + + { defaults with + name = "btrfs_subvolume_get_default"; added = (1, 29, 17); + style = RInt64 "id", [Mountable_or_Path "fs"], []; + proc_nr = Some 425; + optional = Some "btrfs"; camel_name = "BTRFSSubvolumeGetDefault"; + tests = [ + InitPartition, Always, TestResult ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_subvolume_get_default"; "/dev/sda1"]], "ret > 0"), []; + InitPartition, Always, TestResult ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_subvolume_get_default"; "/"]], "ret > 0"), [] + ]; + shortdesc = "get the default subvolume or snapshot of a filesystem"; + longdesc = "\ +Get the default subvolume or snapshot of a filesystem mounted at C<mountpoint>." }; + + { defaults with + name = "btrfs_subvolume_show"; added = (1, 29, 17); + style = RHashtable "btrfssubvolumeinfo", [Pathname "subvolume"], []; + proc_nr = Some 426; + optional = Some "btrfs"; camel_name = "BTRFSSubvolumeShow"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_subvolume_create"; "/sub1"; "NOARG"]; + ["btrfs_subvolume_show"; "/sub1"]]), []; + InitPartition, Always, TestLastFail ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["mkdir"; "/dir1"]; + ["btrfs_subvolume_show"; "/dir1"]]), []; + ]; + shortdesc = "return detailed information of the subvolume"; + longdesc = "\ +Return detailed information of the subvolume." }; + + { defaults with + name = "btrfs_quota_enable"; added = (1, 29, 17); + style = RErr, [Mountable_or_Path "fs"; Bool "enable"], []; + proc_nr = Some 427; + optional = Some "btrfs"; camel_name = "BTRFSQuotaEnable"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_quota_enable"; "/dev/sda1"; "true"]]), []; + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "true"]]), []; + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_quota_enable"; "/dev/sda1"; "false"]]), []; + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "false"]]), []; + ]; + shortdesc = "enable or disable subvolume quota support"; + longdesc = "\ +Enable or disable subvolume quota support for filesystem which contains C<path>." }; + + { defaults with + name = "btrfs_quota_rescan"; added = (1, 29, 17); + style = RErr, [Mountable_or_Path "fs"], []; + proc_nr = Some 428; + optional = Some "btrfs"; camel_name = "BTRFSQuotaRescan"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_quota_enable"; "/dev/sda1"; "true"]; + ["btrfs_quota_rescan"; "/dev/sda1"]]), []; + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "true"]; + ["btrfs_quota_rescan"; "/"]]), []; + ]; + + shortdesc = "trash all qgroup numbers and scan the metadata again with the current config"; + longdesc = "\ +Trash all qgroup numbers and scan the metadata again with the current config." }; + + { defaults with + name = "btrfs_qgroup_limit"; added = (1, 29, 17); + style = RErr, [Pathname "subvolume"; Int64 "size"], []; + proc_nr = Some 429; + optional = Some "btrfs"; camel_name = "BTRFSQgroupLimit"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "true"]; + ["btrfs_qgroup_limit"; "/"; "10737418240"]]), []; + InitPartition, Always, TestLastFail ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "false"]; + ["btrfs_qgroup_limit"; "/"; "10737418240"]]), []; + ]; + shortdesc = "limit the size of a subvolume"; + longdesc = "\ +Limit the size of a subvolume which's path is C<subvolume>. C<size> +can have suffix of G, M, or K. " }; + + { defaults with + name = "btrfs_qgroup_create"; added = (1, 29, 17); + style = RErr, [String "qgroupid"; Pathname "subvolume"], []; + proc_nr = Some 430; + optional = Some "btrfs"; camel_name = "BTRFSQgroupCreate"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "true"]; + ["btrfs_subvolume_create"; "/sub1"; "NOARG"]; + ["btrfs_qgroup_create"; "0/1000"; "/sub1"]]), []; + ]; + shortdesc = "create a subvolume quota group"; + longdesc = "\ +Create a quota group (qgroup) for subvolume at C<subvolume>." }; + + { defaults with + name = "btrfs_qgroup_destroy"; added = (1, 29, 17); + style = RErr, [String "qgroupid"; Pathname "subvolume"], []; + proc_nr = Some 431; + optional = Some "btrfs"; camel_name = "BTRFSQgroupDestroy"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "true"]; + ["btrfs_subvolume_create"; "/sub1"; "NOARG"]; + ["btrfs_qgroup_create"; "0/1000"; "/sub1"]; + ["btrfs_qgroup_destroy"; "0/1000"; "/sub1"]]), []; + ]; + shortdesc = "destroy a subvolume quota group"; + longdesc = "\ +Destroy a quota group." }; + + { defaults with + name = "btrfs_qgroup_show"; added = (1, 29, 17); + style = RStructList ("qgroups", "btrfsqgroup"), [Pathname "path"], []; + proc_nr = Some 432; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "true"]; + ["btrfs_subvolume_create"; "/sub1"; "NOARG"]; + ["btrfs_qgroup_create"; "0/1000"; "/sub1"]; + ["btrfs_qgroup_show"; "/"]]), []; + ]; + optional = Some "btrfs"; camel_name = "BTRFSQgroupShow"; + shortdesc = "show subvolume quota groups"; + longdesc = "\ +Show all subvolume quota groups in a btrfs filesystem, including their +usages." }; + + { defaults with + name = "btrfs_qgroup_assign"; added = (1, 29, 17); + style = RErr, [String "src"; String "dst"; Pathname "path"], []; + proc_nr = Some 433; + optional = Some "btrfs"; camel_name = "BTRFSQgroupAssign"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "true"]; + ["btrfs_qgroup_create"; "0/1000"; "/"]; + ["btrfs_qgroup_create"; "1/1000"; "/"]; + ["btrfs_qgroup_assign"; "0/1000"; "1/1000"; "/"]]), []; + ]; + shortdesc = "add a qgroup to a parent qgroup"; + longdesc = "\ +Add qgroup C<src> to parent qgroup C<dst>. This command can group +several qgroups into a parent qgroup to share common limit." }; + + { defaults with + name = "btrfs_qgroup_remove"; added = (1, 29, 17); + style = RErr, [String "src"; String "dst"; Pathname "path"], []; + proc_nr = Some 434; + optional = Some "btrfs"; camel_name = "BTRFSQgroupRemove"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_quota_enable"; "/"; "true"]; + ["btrfs_qgroup_create"; "0/1000"; "/"]; + ["btrfs_qgroup_create"; "1/1000"; "/"]; + ["btrfs_qgroup_assign"; "0/1000"; "1/1000"; "/"]; + ["btrfs_qgroup_remove"; "0/1000"; "1/1000"; "/"]]), []; + ]; + shortdesc = "remove a qgroup from its parent qgroup"; + longdesc = "\ +Remove qgroup C<src> from the parent qgroup C<dst>." }; + + { defaults with + name = "btrfs_scrub_start"; added = (1, 29, 22); + style = RErr, [Pathname "path"], []; + proc_nr = Some 435; + optional = Some "btrfs"; camel_name = "BTRFSScrubStart"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_scrub_start"; "/"]]), []; + ]; + shortdesc = "read all data from all disks and verify checksums"; + longdesc = "\ +Reads all the data and metadata on the filesystem, and uses checksums +and the duplicate copies from RAID storage to identify and repair any +corrupt data." }; + + { defaults with + name = "btrfs_scrub_cancel"; added = (1, 29, 22); + style = RErr, [Pathname "path"], []; + proc_nr = Some 436; + optional = Some "btrfs"; camel_name = "BTRFSScrubCancel"; + test_excuse = "test disk isn't large enough that btrfs_scrub_start completes before we can cancel it"; + shortdesc = "cancel a running scrub"; + longdesc = "\ +Cancel a running scrub on a btrfs filesystem." }; + + { defaults with + name = "btrfs_scrub_resume"; added = (1, 29, 22); + style = RErr, [Pathname "path"], []; + proc_nr = Some 437; + optional = Some "btrfs"; camel_name = "BTRFSScrubResume"; + test_excuse = "test disk isn't large enough that btrfs_scrub_start completes before we can cancel and resume it"; + shortdesc = "resume a previously canceled or interrupted scrub"; + longdesc = "\ +Resume a previously canceled or interrupted scrub on a btrfs filesystem." }; + +{ defaults with + name = "btrfs_balance_pause"; added = (1, 29, 22); + style = RErr, [Pathname "path"], []; + proc_nr = Some 438; + optional = Some "btrfs"; camel_name = "BTRFSBalancePause"; + test_excuse = "test disk isn't large enough to test this thoroughly"; + shortdesc = "pause a running balance"; + longdesc = "\ +Pause a running balance on a btrfs filesystem." }; + +{ defaults with + name = "btrfs_balance_cancel"; added = (1, 29, 22); + style = RErr, [Pathname "path"], []; + proc_nr = Some 439; + optional = Some "btrfs"; camel_name = "BTRFSBalanceCancel"; + test_excuse = "test disk isn't large enough that btrfs_balance completes before we can cancel it"; + shortdesc = "cancel a running or paused balance"; + longdesc = "\ +Cancel a running balance on a btrfs filesystem." }; + +{ defaults with + name = "btrfs_balance_resume"; added = (1, 29, 22); + style = RErr, [Pathname "path"], []; + proc_nr = Some 440; + optional = Some "btrfs"; camel_name = "BTRFSBalanceResume"; + test_excuse = "test disk isn't large enough that btrfs_balance completes before we can pause and resume it"; + shortdesc = "resume a paused balance"; + longdesc = "\ +Resume a paused balance on a btrfs filesystem." }; + + { defaults with + name = "btrfs_filesystem_defragment"; added = (1, 29, 22); + style = RErr, [Pathname "path"], [OBool "flush"; OString "compress"]; + proc_nr = Some 443; + optional = Some "btrfs"; camel_name = "BTRFSFilesystemDefragment"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_filesystem_defragment"; "/"; "true"; "lzo"]]), []; + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["touch"; "/hello"]; + ["btrfs_filesystem_defragment"; "/hello"; ""; "zlib"]]), []; + ]; + shortdesc = "defragment a file or directory"; + longdesc = "\ +Defragment a file or directory on a btrfs filesystem. compress is one of zlib or lzo." }; + + { defaults with + name = "btrfs_rescue_chunk_recover"; added = (1, 29, 22); + style = RErr, [Device "device"], []; + proc_nr = Some 444; + optional = Some "btrfs"; camel_name = "BTRFSRescueChunkRecover"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_rescue_chunk_recover"; "/dev/sda1"]]), []; + ]; + shortdesc = "recover the chunk tree of btrfs filesystem"; + longdesc = "\ +Recover the chunk tree of btrfs filesystem by scanning the devices one by one." }; + + { defaults with + name = "btrfs_rescue_super_recover"; added = (1, 29, 22); + style = RErr, [Device "device"], []; + proc_nr = Some 445; + optional = Some "btrfs"; camel_name = "BTRFSRescueSuperRecover"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_rescue_super_recover"; "/dev/sda1"]]), []; + ]; + shortdesc = "recover bad superblocks from good copies"; + longdesc = "\ +Recover bad superblocks from good copies." }; + + { defaults with + name = "part_set_gpt_guid"; added = (1, 29, 25); + style = RErr, [Device "device"; Int "partnum"; GUID "guid"], []; + proc_nr = Some 446; + optional = Some "gdisk"; + tests = [ + InitGPT, Always, TestLastFail ( + [["part_set_gpt_guid"; "/dev/sda"; "1"; "f"]]), []; + InitGPT, Always, TestResultString ( + [["part_set_gpt_guid"; "/dev/sda"; "1"; + "01234567-89AB-CDEF-0123-456789ABCDEF"]; + ["part_get_gpt_guid"; "/dev/sda"; "1"]], + "01234567-89AB-CDEF-0123-456789ABCDEF"), []; + ]; + shortdesc = "set the GUID of a GPT partition"; + longdesc = "\ +Set the GUID of numbered GPT partition C<partnum> to C<guid>. Return an +error if the partition table of C<device> isn't GPT, or if C<guid> is not a +valid GUID." }; + + { defaults with + name = "part_get_gpt_guid"; added = (1, 29, 25); + style = RString "guid", [Device "device"; Int "partnum"], []; + proc_nr = Some 447; + optional = Some "gdisk"; + tests = [ + InitGPT, Always, TestResultString ( + [["part_set_gpt_guid"; "/dev/sda"; "1"; + "01234567-89AB-CDEF-0123-456789ABCDEF"]; + ["part_get_gpt_guid"; "/dev/sda"; "1"]], + "01234567-89AB-CDEF-0123-456789ABCDEF"), []; + ]; + shortdesc = "get the GUID of a GPT partition"; + longdesc = "\ +Return the GUID of numbered GPT partition C<partnum>." }; + +{ defaults with + name = "btrfs_balance_status"; added = (1, 29, 26); + style = RStruct ("status", "btrfsbalance"), [Pathname "path"], []; + proc_nr = Some 448; + optional = Some "btrfs"; camel_name = "BTRFSBalanceStatus"; + test_excuse = "test disk isn't large enough that btrfs_balance completes before we can get its status"; + shortdesc = "show the status of a running or paused balance"; + longdesc = "\ +Show the status of a running or paused balance on a btrfs filesystem." }; + + { defaults with + name = "btrfs_scrub_status"; added = (1, 29, 26); + style = RStruct ("status", "btrfsscrub"), [Pathname "path"], []; + proc_nr = Some 449; + optional = Some "btrfs"; camel_name = "BTRFSScrubStatus"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_scrub_start"; "/"]; + ["btrfs_scrub_status"; "/"]]), []; + ]; + shortdesc = "show status of running or finished scrub"; + longdesc = "\ +Show status of running or finished scrub on a btrfs filesystem." }; + + { defaults with + name = "btrfstune_seeding"; added = (1, 29, 29); + style = RErr, [Device "device"; Bool "seeding"], []; + proc_nr = Some 450; + optional = Some "btrfs"; camel_name = "BTRFSTuneSeeding"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfstune_seeding"; "/dev/sda1"; "true"]; + ["btrfstune_seeding"; "/dev/sda1"; "false"]]), [] + ]; + + shortdesc = "enable or disable seeding of a btrfs device"; + longdesc = "\ +Enable seeding of a btrfs device, this will force a fs readonly +so that you can use it to build other filesystems." }; + + { defaults with + name = "btrfstune_enable_extended_inode_refs"; added = (1, 29, 29); + style = RErr, [Device "device"], []; + proc_nr = Some 451; + optional = Some "btrfs"; camel_name = "BTRFSTuneEnableExtendedInodeRefs"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfstune_enable_extended_inode_refs"; "/dev/sda1"]]), [] + ]; + + shortdesc = "enable extended inode refs"; + longdesc = "\ +This will Enable extended inode refs." }; + + { defaults with + name = "btrfstune_enable_skinny_metadata_extent_refs"; added = (1, 29, 29); + style = RErr, [Device "device"], []; + proc_nr = Some 452; + optional = Some "btrfs"; camel_name = "BTRFSTuneEnableSkinnyMetadataExtentRefs"; + tests = [ + InitPartition, Always, TestRun ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfstune_enable_skinny_metadata_extent_refs"; "/dev/sda1"]]), [] + ]; + + shortdesc = "enable skinny metadata extent refs"; + longdesc = "\ +This enable skinny metadata extent refs." }; + + { defaults with + name = "btrfs_image"; added = (1, 29, 32); + style = RErr, [DeviceList "source"; Pathname "image"], [OInt "compresslevel"]; + proc_nr = Some 453; + optional = Some "btrfs"; camel_name = "BTRFSImage"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "2047999"]; + ["part_add"; "/dev/sda"; "p"; "2048000"; "4095999"]; + ["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mkfs_btrfs"; "/dev/sda2"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["mount"; "/dev/sda1"; "/"]; + ["btrfs_image"; "/dev/sda2"; "/1.img"; ""]; + ["btrfs_image"; "/dev/sda2"; "/2.img"; "2"]]), [] + ]; + + shortdesc = "create an image of a btrfs filesystem"; + longdesc = "\ +This is used to create an image of a btrfs filesystem. +All data will be zeroed, but metadata and the like is preserved." }; + + { defaults with + name = "part_get_mbr_part_type"; added = (1, 29, 32); + style = RString "partitiontype", [Device "device"; Int "partnum"], []; + proc_nr = Some 454; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "e"; "204800"; "614400"]; + ["part_add"; "/dev/sda"; "l"; "204864"; "205988"]; + ["part_get_mbr_part_type"; "/dev/sda"; "5"]], "logical"), []; + InitEmpty, Always, TestResultString ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "e"; "204800"; "614400"]; + ["part_add"; "/dev/sda"; "l"; "204864"; "205988"]; + ["part_get_mbr_part_type"; "/dev/sda"; "2"]], "extended"), [] + ]; + + shortdesc = "get the MBR partition type"; + longdesc = "\ +This returns the partition type of an MBR partition +numbered C<partnum> on device C<device>. + +It returns C<primary>, C<logical>, or C<extended>." }; + + { defaults with + name = "btrfs_replace"; added = (1, 29, 48); + style = RErr, [Device "srcdev"; Device "targetdev"; Pathname "mntpoint"], []; + proc_nr = Some 455; + optional = Some "btrfs"; camel_name = "BTRFSReplace"; + test_excuse = "put the test in 'tests/btrfs' directory"; + shortdesc = "replace a btrfs managed device with another device"; + longdesc = "\ +Replace device of a btrfs filesystem. On a live filesystem, duplicate the data +to the target device which is currently stored on the source device. +After completion of the operation, the source device is wiped out and +removed from the filesystem. + +The C<targetdev> needs to be same size or larger than the C<srcdev>. Devices +which are currently mounted are never allowed to be used as the C<targetdev>." }; + + { defaults with + name = "set_uuid_random"; added = (1, 29, 50); + style = RErr, [Device "device"], []; + proc_nr = Some 456; + tests = [ + InitBasicFS, Always, TestRun ( + [["set_uuid_random"; "/dev/sda1"]]), []; + ]; + shortdesc = "set a random UUID for the filesystem"; + longdesc = "\ +Set the filesystem UUID on C<device> to a random UUID. +If this fails and the errno is ENOTSUP, +means that there is no support for changing the UUID +for the type of the specified filesystem. + +Only some filesystem types support setting UUIDs. + +To read the UUID on a filesystem, call C<guestfs_vfs_uuid>." }; + + { defaults with + name = "vfs_minimum_size"; added = (1, 31, 18); + style = RInt64 "sizeinbytes", [Mountable "mountable"], []; + proc_nr = Some 457; + tests = [ + InitBasicFS, Always, TestRun ( + [["vfs_minimum_size"; "/dev/sda1"]]), []; + InitPartition, IfAvailable "ntfsprogs", TestRun( + [["mkfs"; "ntfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["vfs_minimum_size"; "/dev/sda1"]]), []; + InitPartition, IfAvailable "btrfs", TestRunOrUnsupported ( + [["mkfs"; "btrfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["vfs_minimum_size"; "/dev/sda1"]]), []; + InitPartition, IfAvailable "xfs", TestRun ( + [["mkfs"; "xfs"; "/dev/sda1"; ""; "NOARG"; ""; ""; "NOARG"]; + ["mount"; "/dev/sda1"; "/"]; + ["vfs_minimum_size"; "/dev/sda1"]]), []; + ]; + shortdesc = "get minimum filesystem size"; + longdesc = "\ +Get the minimum size of filesystem in bytes. +This is the minimum possible size for filesystem shrinking. + +If getting minimum size of specified filesystem is not supported, +this will fail and set errno as ENOTSUP. + +See also L<ntfsresize(8)>, L<resize2fs(8)>, L<btrfs(8)>, L<xfs_info(8)>." }; + + { defaults with + name = "internal_feature_available"; added = (1, 31, 25); + style = RInt "result", [String "group"], []; + proc_nr = Some 458; + visibility = VInternal; + shortdesc = "test availability of some parts of the API"; + longdesc = "\ +This is the internal call which implements C<guestfs_feature_available>." }; + + { defaults with + name = "part_set_disk_guid"; added = (1, 33, 2); + style = RErr, [Device "device"; GUID "guid"], []; + proc_nr = Some 459; + optional = Some "gdisk"; + tests = [ + InitGPT, Always, TestLastFail ( + [["part_set_disk_guid"; "/dev/sda"; "f"]]), []; + InitGPT, Always, TestResultString ( + [["part_set_disk_guid"; "/dev/sda"; + "01234567-89AB-CDEF-0123-456789ABCDEF"]; + ["part_get_disk_guid"; "/dev/sda"]], + "01234567-89AB-CDEF-0123-456789ABCDEF"), []; + ]; + shortdesc = "set the GUID of a GPT-partitioned disk"; + longdesc = "\ +Set the disk identifier (GUID) of a GPT-partitioned C<device> to C<guid>. +Return an error if the partition table of C<device> isn't GPT, +or if C<guid> is not a valid GUID." }; + + { defaults with + name = "part_get_disk_guid"; added = (1, 33, 2); + style = RString "guid", [Device "device"], []; + proc_nr = Some 460; + optional = Some "gdisk"; + tests = [ + InitGPT, Always, TestResultString ( + [["part_set_disk_guid"; "/dev/sda"; + "01234567-89AB-CDEF-0123-456789ABCDEF"]; + ["part_get_disk_guid"; "/dev/sda"]], + "01234567-89AB-CDEF-0123-456789ABCDEF"), []; + ]; + shortdesc = "get the GUID of a GPT-partitioned disk"; + longdesc = "\ +Return the disk identifier (GUID) of a GPT-partitioned C<device>. +Behaviour is undefined for other partition types." }; + + { defaults with + name = "part_set_disk_guid_random"; added = (1, 33, 2); + style = RErr, [Device "device"], []; + proc_nr = Some 461; + optional = Some "gdisk"; + tests = [ + InitGPT, Always, TestRun ( + [["part_set_disk_guid_random"; "/dev/sda"]]), []; + ]; + shortdesc = "set the GUID of a GPT-partitioned disk to random value"; + longdesc = "\ +Set the disk identifier (GUID) of a GPT-partitioned C<device> to +a randomly generated value. +Return an error if the partition table of C<device> isn't GPT." }; + + { defaults with + name = "part_expand_gpt"; added = (1, 33, 2); + style = RErr, [Device "device"], []; + proc_nr = Some 462; + optional = Some "gdisk"; + shortdesc = "move backup GPT header to the end of the disk"; + longdesc = "\ +Move backup GPT data structures to the end of the disk. +This is useful in case of in-place image expand +since disk space after backup GPT header is not usable. +This is equivalent to C<sgdisk -e>. + +See also L<sgdisk(8)>." }; + + { defaults with + name = "ntfscat_i"; added = (1, 33, 14); + style = RErr, [Mountable "device"; Int64 "inode"; FileOut "filename"], []; + proc_nr = Some 463; + progress = true; cancellable = true; + shortdesc = "download a file to the local machine given its inode"; + longdesc = "\ +Download a file given its inode from a NTFS filesystem and save it as +F<filename> on the local machine. + +This allows to download some otherwise inaccessible files such as the ones +within the C<$Extend> folder. + +The filesystem from which to extract the file must be unmounted, +otherwise the call will fail." }; + + { defaults with + name = "download_inode"; added = (1, 33, 14); + style = RErr, [Mountable "device"; Int64 "inode"; FileOut "filename"], []; + proc_nr = Some 464; + optional = Some "sleuthkit"; + progress = true; cancellable = true; + shortdesc = "download a file to the local machine given its inode"; + longdesc = "\ +Download a file given its inode from the disk partition +(eg. F</dev/sda1>) and save it as F<filename> on the local machine. + +It is not required to mount the disk to run this command. + +The command is capable of downloading deleted or inaccessible files." }; + + { defaults with + name = "btrfs_filesystem_show"; added = (1, 33, 29); + style = RStringList "devices", [Device "device"], []; + proc_nr = Some 465; + optional = Some "btrfs"; camel_name = "BTRFSFilesystemsShow"; + tests = [ + InitScratchFS, Always, TestLastFail ( + [["btrfs_filesystem_show"; "/dev/sdb"]]), []; + InitPartition, Always, TestResult ( + [["mkfs_btrfs"; "/dev/sda1"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_filesystem_show"; "/dev/sda1"]], + "is_string_list (ret, 1, \"/dev/sda1\")"), []; + InitEmpty, Always, TestResult ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "2047999"]; + ["part_add"; "/dev/sda"; "p"; "2048000"; "4095999"]; + ["mkfs_btrfs"; "/dev/sda1 /dev/sda2"; ""; ""; "NOARG"; ""; "NOARG"; "NOARG"; ""; ""]; + ["btrfs_filesystem_show"; "/dev/sda1"]], + "is_string_list (ret, 2, \"/dev/sda1\", \"/dev/sda2\")"), []; + ]; + shortdesc = "list devices for btrfs filesystem"; + longdesc = "\ +Show all the devices where the filesystems in C<device> is spanned over. + +If not all the devices for the filesystems are present, then this function +fails and the C<errno> is set to C<ENODEV>." }; + + { defaults with + name = "selinux_relabel"; added = (1, 33, 43); + style = RErr, [String "specfile"; Pathname "path"], [OBool "force"]; + proc_nr = Some 467; + optional = Some "selinuxrelabel"; + test_excuse = "tests are in the tests/relabel directory"; + shortdesc = "relabel parts of the filesystem"; + longdesc = "\ +SELinux relabel parts of the filesystem. + +The C<specfile> parameter controls the policy spec file used. +You have to parse C</etc/selinux/config> to find the correct +SELinux policy and then pass the spec file, usually: +C</etc/selinux/> + I<selinuxtype> + C</contexts/files/file_contexts>. + +The required C<path> parameter is the top level directory where +relabelling starts. Normally you should pass C<path> as C</> +to relabel the whole guest filesystem. + +The optional C<force> boolean controls whether the context +is reset for customizable files, and also whether the +user, role and range parts of the file context is changed." }; + + { defaults with + name = "mksquashfs"; added = (1, 35, 25); + style = RErr, [Pathname "path"; FileOut "filename"], [OString "compress"; OStringList "excludes"]; + proc_nr = Some 471; + optional = Some "squashfs"; + cancellable = true; + shortdesc = "create a squashfs filesystem"; + longdesc = "\ +Create a squashfs filesystem for the specified C<path>. + +The optional C<compress> flag controls compression. If not given, +then the output compressed using C<gzip>. Otherwise one +of the following strings may be given to select the compression +type of the squashfs: C<gzip>, C<lzma>, C<lzo>, C<lz4>, C<xz>. + +The other optional arguments are: + +=over 4 + +=item C<excludes> + +A list of wildcards. Files are excluded if they match any of the +wildcards. + +=back + +Please note that this API may fail when used to compress directories +with large files, such as the resulting squashfs will be over 3GB big." }; + +] diff --git a/generator/actions_core.mli b/generator/actions_core.mli new file mode 100644 index 0000000..06b8116 --- /dev/null +++ b/generator/actions_core.mli @@ -0,0 +1,22 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list +val daemon_functions : Types.action list diff --git a/generator/actions_core_deprecated.ml b/generator/actions_core_deprecated.ml new file mode 100644 index 0000000..5c1a275 --- /dev/null +++ b/generator/actions_core_deprecated.ml @@ -0,0 +1,793 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 Utils +open Types + +(* "Core" APIs. All the APIs in this file are deprecated. *) + +let non_daemon_functions = [ + { 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<lt> 1.0.71 you had to call this function +just after calling C<guestfs_launch> to wait for the launch +to complete. However this is no longer necessary because +C<guestfs_launch> 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<guestfs_shutdown> 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<guestfs_add_drive_ro>." }; + + { 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<guestfs_add_drive> 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<guestfs_add_drive_ro> but it allows you +to specify the QEMU interface emulation to use at run time." }; + + { defaults with + name = "lstatlist"; added = (1, 0, 77); + style = RStructList ("statbufs", "stat"), [Pathname "path"; FilenameList "names"], []; + deprecated_by = Some "lstatnslist"; + shortdesc = "lstat on multiple files"; + longdesc = "\ +This call allows you to perform the C<guestfs_lstat> operation +on multiple files, where all files are in the directory C<path>. +C<names> 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<names> list. If any name did not exist +or could not be lstat'd, then the C<st_ino> 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<guestfs_lxattrlist> for a similarly efficient call +for getting extended attributes." }; + +] + +let daemon_functions = [ + { defaults with + name = "sfdisk"; added = (0, 0, 8); + style = RErr, [Device "device"; + Int "cyls"; Int "heads"; Int "sectors"; + StringList "lines"], []; + proc_nr = Some 43; + deprecated_by = Some "part_add"; + shortdesc = "create partitions on a block device"; + longdesc = "\ +This is a direct interface to the L<sfdisk(8)> program for creating +partitions on block devices. + +C<device> should be a block device, for example F</dev/sda>. + +C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads +and sectors on the device, which are passed directly to sfdisk as +the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any +of these, then the corresponding parameter is omitted. Usually for +'large' disks, you can just pass C<0> for these, but for small +(floppy-sized) disks, sfdisk (or rather, the kernel) cannot work +out the right geometry and you will need to tell it. + +C<lines> is a list of lines that we feed to C<sfdisk>. For more +information refer to the L<sfdisk(8)> manpage. + +To create a single partition occupying the whole disk, you would +pass C<lines> as a single element list, when the single element being +the string C<,> (comma). + +See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>, +C<guestfs_part_init>" }; + + { defaults with + name = "blockdev_setbsz"; added = (1, 9, 3); + style = RErr, [Device "device"; Int "blocksize"], []; + proc_nr = Some 61; + deprecated_by = Some "mkfs"; + shortdesc = "set blocksize of block device"; + longdesc = "\ +This call does nothing and has never done anything +because of a bug in blockdev. B<Do not use it.> + +If you need to set the filesystem block size, use the +C<blocksize> option of C<guestfs_mkfs>." }; + + { defaults with + name = "tgz_in"; added = (1, 0, 3); + style = RErr, [FileIn "tarball"; Pathname "directory"], []; + proc_nr = Some 71; + deprecated_by = Some "tar_in"; + cancellable = true; + tests = [ + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/tgz_in"]; + ["tgz_in"; "$srcdir/../../test-data/files/helloworld.tar.gz"; "/tgz_in"]; + ["cat"; "/tgz_in/hello"]], "hello\n"), [] + ]; + shortdesc = "unpack compressed tarball to directory"; + longdesc = "\ +This command uploads and unpacks local file C<tarball> (a +I<gzip compressed> tar file) into F<directory>." }; + + { defaults with + name = "tgz_out"; added = (1, 0, 3); + style = RErr, [Pathname "directory"; FileOut "tarball"], []; + proc_nr = Some 72; + deprecated_by = Some "tar_out"; + cancellable = true; + shortdesc = "pack directory into compressed tarball"; + longdesc = "\ +This command packs the contents of F<directory> and downloads +it to local file C<tarball>." }; + + { defaults with + name = "set_e2label"; added = (1, 0, 15); + style = RErr, [Device "device"; String "label"], []; + proc_nr = Some 80; + deprecated_by = Some "set_label"; + tests = [ + InitBasicFS, Always, TestResultString ( + [["set_e2label"; "/dev/sda1"; "testlabel"]; + ["get_e2label"; "/dev/sda1"]], "testlabel"), [] + ]; + shortdesc = "set the ext2/3/4 filesystem label"; + longdesc = "\ +This sets the ext2/3/4 filesystem label of the filesystem on +C<device> to C<label>. Filesystem labels are limited to +16 characters. + +You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label> +to return the existing label on a filesystem." }; + + { defaults with + name = "get_e2label"; added = (1, 0, 15); + style = RString "label", [Device "device"], []; + proc_nr = Some 81; + deprecated_by = Some "vfs_label"; + shortdesc = "get the ext2/3/4 filesystem label"; + longdesc = "\ +This returns the ext2/3/4 filesystem label of the filesystem on +C<device>." }; + + { defaults with + name = "set_e2uuid"; added = (1, 0, 15); + style = RErr, [Device "device"; String "uuid"], []; + proc_nr = Some 82; + deprecated_by = Some "set_uuid"; + tests = [ + InitBasicFS, Always, TestResultString ( + [["set_e2uuid"; "/dev/sda1"; stable_uuid]; + ["get_e2uuid"; "/dev/sda1"]], stable_uuid), []; + InitBasicFS, Always, TestResultString ( + [["set_e2uuid"; "/dev/sda1"; "clear"]; + ["get_e2uuid"; "/dev/sda1"]], ""), []; + (* We can't predict what UUIDs will be, so just check + the commands run. *) + InitBasicFS, Always, TestRun ( + [["set_e2uuid"; "/dev/sda1"; "random"]]), []; + InitBasicFS, Always, TestRun ( + [["set_e2uuid"; "/dev/sda1"; "time"]]), [] + ]; + shortdesc = "set the ext2/3/4 filesystem UUID"; + longdesc = "\ +This sets the ext2/3/4 filesystem UUID of the filesystem on +C<device> to C<uuid>. The format of the UUID and alternatives +such as C<clear>, C<random> and C<time> are described in the +L<tune2fs(8)> manpage. + +You can use C<guestfs_vfs_uuid> to return the existing UUID +of a filesystem." }; + + { defaults with + name = "get_e2uuid"; added = (1, 0, 15); + style = RString "uuid", [Device "device"], []; + proc_nr = Some 83; + deprecated_by = Some "vfs_uuid"; + tests = [ + (* We can't predict what UUID will be, so just check + the command run; regression test for RHBZ#597112. *) + InitNone, Always, TestRun ( + [["mke2journal"; "1024"; "/dev/sdc"]; + ["get_e2uuid"; "/dev/sdc"]]), [] + ]; + shortdesc = "get the ext2/3/4 filesystem UUID"; + longdesc = "\ +This returns the ext2/3/4 filesystem UUID of the filesystem on +C<device>." }; + + { defaults with + name = "sfdisk_N"; added = (1, 0, 26); + style = RErr, [Device "device"; Int "partnum"; + Int "cyls"; Int "heads"; Int "sectors"; + String "line"], []; + proc_nr = Some 99; + deprecated_by = Some "part_add"; + shortdesc = "modify a single partition on a block device"; + longdesc = "\ +This runs L<sfdisk(8)> option to modify just the single +partition C<n> (note: C<n> counts from 1). + +For other parameters, see C<guestfs_sfdisk>. You should usually +pass C<0> for the cyls/heads/sectors parameters. + +See also: C<guestfs_part_add>" }; + + { defaults with + name = "sfdisk_l"; added = (1, 0, 26); + style = RString "partitions", [Device "device"], []; + proc_nr = Some 100; + deprecated_by = Some "part_list"; + shortdesc = "display the partition table"; + longdesc = "\ +This displays the partition table on C<device>, in the +human-readable output of the L<sfdisk(8)> command. It is +not intended to be parsed. + +See also: C<guestfs_part_list>" }; + + { defaults with + name = "e2fsck_f"; added = (1, 0, 29); + style = RErr, [Device "device"], []; + proc_nr = Some 108; + deprecated_by = Some "e2fsck"; + shortdesc = "check an ext2/ext3 filesystem"; + longdesc = "\ +This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3 +filesystem checker on C<device>, noninteractively (I<-p>), +even if the filesystem appears to be clean (I<-f>)." }; + + { defaults with + name = "mkswap_L"; added = (1, 0, 55); + style = RErr, [String "label"; Device "device"], []; + proc_nr = Some 131; + deprecated_by = Some "mkswap"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkswap_L"; "hello"; "/dev/sda1"]]), [] + ]; + shortdesc = "create a swap partition with a label"; + longdesc = "\ +Create a swap partition on C<device> with label C<label>. + +Note that you cannot attach a swap label to a block device +(eg. F</dev/sda>), just to a partition. This appears to be +a limitation of the kernel or swap tools." }; + + { defaults with + name = "mkswap_U"; added = (1, 0, 55); + style = RErr, [String "uuid"; Device "device"], []; + proc_nr = Some 132; + deprecated_by = Some "mkswap"; + optional = Some "linuxfsuuid"; + tests = [ + InitEmpty, Always, TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkswap_U"; stable_uuid; "/dev/sda1"]]), [] + ]; + shortdesc = "create a swap partition with an explicit UUID"; + longdesc = "\ +Create a swap partition on C<device> with UUID C<uuid>." }; + + { defaults with + name = "sfdiskM"; added = (1, 0, 55); + style = RErr, [Device "device"; StringList "lines"], []; + proc_nr = Some 139; + deprecated_by = Some "part_add"; + shortdesc = "create partitions on a block device"; + longdesc = "\ +This is a simplified interface to the C<guestfs_sfdisk> +command, where partition sizes are specified in megabytes +only (rounded to the nearest cylinder) and you don't need +to specify the cyls, heads and sectors parameters which +were rarely if ever used anyway. + +See also: C<guestfs_sfdisk>, the L<sfdisk(8)> manpage +and C<guestfs_part_disk>" }; + + { defaults with + name = "zfile"; added = (1, 0, 59); + style = RString "description", [String "meth"; Pathname "path"], []; + proc_nr = Some 140; + deprecated_by = Some "file"; + shortdesc = "determine file type inside a compressed file"; + longdesc = "\ +This command runs F<file> after first decompressing C<path> +using C<method>. + +C<method> must be one of C<gzip>, C<compress> or C<bzip2>. + +Since 1.0.63, use C<guestfs_file> instead which can now +process compressed files." }; + + { defaults with + name = "egrep"; added = (1, 0, 66); + style = RStringList "lines", [String "regex"; Pathname "path"], []; + proc_nr = Some 152; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["egrep"; "abc"; "/test-grep.txt"]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<egrep> program and returns the +matching lines." }; + + { defaults with + name = "fgrep"; added = (1, 0, 66); + style = RStringList "lines", [String "pattern"; Pathname "path"], []; + proc_nr = Some 153; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["fgrep"; "abc"; "/test-grep.txt"]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<fgrep> program and returns the +matching lines." }; + + { defaults with + name = "grepi"; added = (1, 0, 66); + style = RStringList "lines", [String "regex"; Pathname "path"], []; + proc_nr = Some 154; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["grepi"; "abc"; "/test-grep.txt"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<grep -i> program and returns the +matching lines." }; + + { defaults with + name = "egrepi"; added = (1, 0, 66); + style = RStringList "lines", [String "regex"; Pathname "path"], []; + proc_nr = Some 155; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["egrepi"; "abc"; "/test-grep.txt"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<egrep -i> program and returns the +matching lines." }; + + { defaults with + name = "fgrepi"; added = (1, 0, 66); + style = RStringList "lines", [String "pattern"; Pathname "path"], []; + proc_nr = Some 156; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["fgrepi"; "abc"; "/test-grep.txt"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<fgrep -i> program and returns the +matching lines." }; + + { defaults with + name = "zgrep"; added = (1, 0, 66); + style = RStringList "lines", [String "regex"; Pathname "path"], []; + proc_nr = Some 157; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["zgrep"; "abc"; "/test-grep.txt.gz"]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<zgrep> program and returns the +matching lines." }; + + { defaults with + name = "zegrep"; added = (1, 0, 66); + style = RStringList "lines", [String "regex"; Pathname "path"], []; + proc_nr = Some 158; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["zegrep"; "abc"; "/test-grep.txt.gz"]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<zegrep> program and returns the +matching lines." }; + + { defaults with + name = "zfgrep"; added = (1, 0, 66); + style = RStringList "lines", [String "pattern"; Pathname "path"], []; + proc_nr = Some 159; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["zfgrep"; "abc"; "/test-grep.txt.gz"]], + "is_string_list (ret, 2, \"abc\", \"abc123\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<zfgrep> program and returns the +matching lines." }; + + { defaults with + name = "zgrepi"; added = (1, 0, 66); + style = RStringList "lines", [String "regex"; Pathname "path"], []; + proc_nr = Some 160; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["zgrepi"; "abc"; "/test-grep.txt.gz"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<zgrep -i> program and returns the +matching lines." }; + + { defaults with + name = "zegrepi"; added = (1, 0, 66); + style = RStringList "lines", [String "regex"; Pathname "path"], []; + proc_nr = Some 161; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["zegrepi"; "abc"; "/test-grep.txt.gz"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<zegrep -i> program and returns the +matching lines." }; + + { defaults with + name = "zfgrepi"; added = (1, 0, 66); + style = RStringList "lines", [String "pattern"; Pathname "path"], []; + proc_nr = Some 162; + protocol_limit_warning = true; + deprecated_by = Some "grep"; + tests = [ + InitISOFS, Always, TestResult ( + [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], + "is_string_list (ret, 3, \"abc\", \"abc123\", \"ABC\")"), [] + ]; + shortdesc = "return lines matching a pattern"; + longdesc = "\ +This calls the external C<zfgrep -i> program and returns the +matching lines." }; + + { defaults with + name = "fallocate"; added = (1, 0, 66); + style = RErr, [Pathname "path"; Int "len"], []; + proc_nr = Some 169; + deprecated_by = Some "fallocate64"; + tests = [ + InitScratchFS, Always, TestResult ( + [["fallocate"; "/fallocate"; "1000000"]; + ["stat"; "/fallocate"]], "ret->size == 1000000"), [] + ]; + shortdesc = "preallocate a file in the guest filesystem"; + longdesc = "\ +This command preallocates a file (containing zero bytes) named +C<path> of size C<len> bytes. If the file exists already, it +is overwritten. + +Do not confuse this with the guestfish-specific +C<alloc> command which allocates a file in the host and +attaches it as a device." }; + + { defaults with + name = "setcon"; added = (1, 0, 67); + style = RErr, [String "context"], []; + proc_nr = Some 185; + optional = Some "selinux"; + deprecated_by = Some "selinux_relabel"; + shortdesc = "set SELinux security context"; + longdesc = "\ +This sets the SELinux security context of the daemon +to the string C<context>. + +See the documentation about SELINUX in L<guestfs(3)>." }; + + { defaults with + name = "getcon"; added = (1, 0, 67); + style = RString "context", [], []; + proc_nr = Some 186; + optional = Some "selinux"; + deprecated_by = Some "selinux_relabel"; + shortdesc = "get SELinux security context"; + longdesc = "\ +This gets the SELinux security context of the daemon. + +See the documentation about SELINUX in L<guestfs(3)>, +and C<guestfs_setcon>" }; + + { defaults with + name = "mkfs_b"; added = (1, 0, 68); + style = RErr, [String "fstype"; Int "blocksize"; Device "device"], []; + proc_nr = Some 187; + deprecated_by = Some "mkfs"; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs_b"; "ext2"; "4096"; "/dev/sda1"]; + ["mount"; "/dev/sda1"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents"), []; + InitEmpty, Always, TestRun ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["mkfs_b"; "vfat"; "32768"; "/dev/sda1"]]), []; + InitEmpty, Always, TestLastFail ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["mkfs_b"; "vfat"; "32769"; "/dev/sda1"]]), []; + InitEmpty, Always, TestLastFail ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["mkfs_b"; "vfat"; "33280"; "/dev/sda1"]]), []; + InitEmpty, IfAvailable "ntfsprogs", TestRun ( + [["part_disk"; "/dev/sda"; "mbr"]; + ["mkfs_b"; "ntfs"; "32768"; "/dev/sda1"]]), [] + ]; + shortdesc = "make a filesystem with block size"; + longdesc = "\ +This call is similar to C<guestfs_mkfs>, but it allows you to +control the block size of the resulting filesystem. Supported +block sizes depend on the filesystem type, but typically they +are C<1024>, C<2048> or C<4096> only. + +For VFAT and NTFS the C<blocksize> parameter is treated as +the requested cluster size." }; + + { defaults with + name = "mke2journal"; added = (1, 0, 68); + style = RErr, [Int "blocksize"; Device "device"], []; + proc_nr = Some 188; + deprecated_by = Some "mke2fs"; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; + ["mke2journal"; "4096"; "/dev/sda1"]; + ["mke2fs_J"; "ext2"; "4096"; "/dev/sda2"; "/dev/sda1"]; + ["mount"; "/dev/sda2"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents"), [] + ]; + shortdesc = "make ext2/3/4 external journal"; + longdesc = "\ +This creates an ext2 external journal on C<device>. It is equivalent +to the command: + + mke2fs -O journal_dev -b blocksize device" }; + + { defaults with + name = "mke2journal_L"; added = (1, 0, 68); + style = RErr, [Int "blocksize"; String "label"; Device "device"], []; + proc_nr = Some 189; + deprecated_by = Some "mke2fs"; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; + ["mke2journal_L"; "4096"; "JOURNAL"; "/dev/sda1"]; + ["mke2fs_JL"; "ext2"; "4096"; "/dev/sda2"; "JOURNAL"]; + ["mount"; "/dev/sda2"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents"), [] + ]; + shortdesc = "make ext2/3/4 external journal with label"; + longdesc = "\ +This creates an ext2 external journal on C<device> with label C<label>." }; + + { defaults with + name = "mke2journal_U"; added = (1, 0, 68); + style = RErr, [Int "blocksize"; String "uuid"; Device "device"], []; + proc_nr = Some 190; + deprecated_by = Some "mke2fs"; + optional = Some "linuxfsuuid"; + tests = [ + InitEmpty, Always, TestResultString ( + [["part_init"; "/dev/sda"; "mbr"]; + ["part_add"; "/dev/sda"; "p"; "64"; "204799"]; + ["part_add"; "/dev/sda"; "p"; "204800"; "-64"]; + ["mke2journal_U"; "4096"; stable_uuid; "/dev/sda1"]; + ["mke2fs_JU"; "ext2"; "4096"; "/dev/sda2"; stable_uuid]; + ["mount"; "/dev/sda2"; "/"]; + ["write"; "/new"; "new file contents"]; + ["cat"; "/new"]], "new file contents"), [] + ]; + shortdesc = "make ext2/3/4 external journal with UUID"; + longdesc = "\ +This creates an ext2 external journal on C<device> with UUID C<uuid>." }; + + { defaults with + name = "mke2fs_J"; added = (1, 0, 68); + style = RErr, [String "fstype"; Int "blocksize"; Device "device"; Device "journal"], []; + proc_nr = Some 191; + deprecated_by = Some "mke2fs"; + shortdesc = "make ext2/3/4 filesystem with external journal"; + longdesc = "\ +This creates an ext2/3/4 filesystem on C<device> with +an external journal on C<journal>. It is equivalent +to the command: + + mke2fs -t fstype -b blocksize -J device=<journal> <device> + +See also C<guestfs_mke2journal>." }; + + { defaults with + name = "mke2fs_JL"; added = (1, 0, 68); + style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "label"], []; + proc_nr = Some 192; + deprecated_by = Some "mke2fs"; + shortdesc = "make ext2/3/4 filesystem with external journal"; + longdesc = "\ +This creates an ext2/3/4 filesystem on C<device> with +an external journal on the journal labeled C<label>. + +See also C<guestfs_mke2journal_L>." }; + + { defaults with + name = "mke2fs_JU"; added = (1, 0, 68); + style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "uuid"], []; + proc_nr = Some 193; + deprecated_by = Some "mke2fs"; + optional = Some "linuxfsuuid"; + shortdesc = "make ext2/3/4 filesystem with external journal"; + longdesc = "\ +This creates an ext2/3/4 filesystem on C<device> with +an external journal on the journal with UUID C<uuid>. + +See also C<guestfs_mke2journal_U>." }; + + { defaults with + name = "dd"; added = (1, 0, 80); + style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"], []; + proc_nr = Some 217; + deprecated_by = Some "copy_device_to_device"; + tests = [ + InitScratchFS, Always, TestResult ( + [["mkdir"; "/dd"]; + ["write"; "/dd/src"; "hello, world"]; + ["dd"; "/dd/src"; "/dd/dest"]; + ["read_file"; "/dd/dest"]], + "compare_buffers (ret, size, \"hello, world\", 12) == 0"), [] + ]; + shortdesc = "copy from source to destination using dd"; + longdesc = "\ +This command copies from one source device or file C<src> +to another destination device or file C<dest>. Normally you +would use this to copy to or from a device or partition, for +example to duplicate a filesystem. + +If the destination is a device, it must be as large or larger +than the source file or device, otherwise the copy will fail. +This command cannot do partial copies +(see C<guestfs_copy_device_to_device>)." }; + + { defaults with + name = "txz_in"; added = (1, 3, 2); + style = RErr, [FileIn "tarball"; Pathname "directory"], []; + proc_nr = Some 229; + deprecated_by = Some "tar_in"; + optional = Some "xz"; cancellable = true; + tests = [ + InitScratchFS, Always, TestResultString ( + [["mkdir"; "/txz_in"]; + ["txz_in"; "$srcdir/../../test-data/files/helloworld.tar.xz"; "/txz_in"]; + ["cat"; "/txz_in/hello"]], "hello\n"), [] + ]; + shortdesc = "unpack compressed tarball to directory"; + longdesc = "\ +This command uploads and unpacks local file C<tarball> (an +I<xz compressed> tar file) into F<directory>." }; + + { defaults with + name = "txz_out"; added = (1, 3, 2); + style = RErr, [Pathname "directory"; FileOut "tarball"], []; + proc_nr = Some 230; + deprecated_by = Some "tar_out"; + optional = Some "xz"; cancellable = true; + shortdesc = "pack directory into compressed tarball"; + longdesc = "\ +This command packs the contents of F<directory> and downloads +it to local file C<tarball> (as an xz compressed tar archive)." }; + + { defaults with + name = "llz"; added = (1, 17, 6); + style = RString "listing", [Pathname "directory"], []; + proc_nr = Some 305; + deprecated_by = Some "lgetxattrs"; + shortdesc = "list the files in a directory (long format with SELinux contexts)"; + longdesc = "\ +List the files in F<directory> in the format of 'ls -laZ'. + +This command is mostly useful for interactive sessions. It +is I<not> intended that you try to parse the output string." }; + +] diff --git a/generator/actions_core_deprecated.mli b/generator/actions_core_deprecated.mli new file mode 100644 index 0000000..06b8116 --- /dev/null +++ b/generator/actions_core_deprecated.mli @@ -0,0 +1,22 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list +val daemon_functions : Types.action list diff --git a/generator/actions_debug.ml b/generator/actions_debug.ml new file mode 100644 index 0000000..6c5970b --- /dev/null +++ b/generator/actions_debug.ml @@ -0,0 +1,69 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 + +(* Debug APIs. *) + +let non_daemon_functions = [ + { defaults with + name = "debug_drives"; added = (1, 13, 22); + style = RStringList "cmdline", [], []; + visibility = VDebug; + blocking = 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." }; + +] + +let daemon_functions = [ + { defaults with + name = "debug"; added = (1, 0, 11); + style = RString "result", [String "subcmd"; StringList "extraargs"], []; + proc_nr = Some 76; + visibility = VDebug; + shortdesc = "debugging and internals"; + longdesc = "\ +The C<guestfs_debug> command exposes some internals of +C<guestfsd> (the guestfs daemon) that runs inside the +hypervisor. + +There is no comprehensive help for this command. You have +to look at the file F<daemon/debug.c> in the libguestfs source +to find out what you can do." }; + + { defaults with + name = "debug_upload"; added = (1, 3, 5); + style = RErr, [FileIn "filename"; String "tmpname"; Int "mode"], []; + proc_nr = Some 241; + visibility = VDebug; + cancellable = true; + shortdesc = "upload a file to the appliance (internal use only)"; + longdesc = "\ +The C<guestfs_debug_upload> command uploads a file to +the libguestfs appliance. + +There is no comprehensive help for this command. You have +to look at the file F<daemon/debug.c> in the libguestfs source +to find out what it is for." }; + +] diff --git a/generator/actions_debug.mli b/generator/actions_debug.mli new file mode 100644 index 0000000..06b8116 --- /dev/null +++ b/generator/actions_debug.mli @@ -0,0 +1,22 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list +val daemon_functions : Types.action list diff --git a/generator/actions_hivex.ml b/generator/actions_hivex.ml new file mode 100644 index 0000000..d6e0f99 --- /dev/null +++ b/generator/actions_hivex.ml @@ -0,0 +1,254 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 + +(* Hivex APIs. *) + +let non_daemon_functions = [ + { defaults with + name = "hivex_value_utf8"; added = (1, 19, 35); + style = RString "databuf", [Int64 "valueh"], []; + optional = Some "hivex"; + shortdesc = "return the data field from the (key, datatype, data) tuple"; + longdesc = "\ +This calls C<guestfs_hivex_value_value> (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." }; + +] + +let daemon_functions = [ + { defaults with + name = "hivex_open"; added = (1, 19, 35); + style = RErr, [Pathname "filename"], [OBool "verbose"; OBool "debug"; OBool "write"; OBool "unsafe"]; + proc_nr = Some 350; + optional = Some "hivex"; + tests = [ + InitScratchFS, Always, TestRun ( + [["upload"; "$srcdir/../../test-data/files/minimal"; "/hivex_open"]; + ["hivex_open"; "/hivex_open"; ""; ""; "false"; ""]; + ["hivex_root"]; (* in this hive, it returns 0x1020 *) + ["hivex_node_name"; "0x1020"]; + ["hivex_node_children"; "0x1020"]; + ["hivex_node_values"; "0x1020"]]), [["hivex_close"]] + ]; + shortdesc = "open a Windows Registry hive file"; + longdesc = "\ +Open the Windows Registry hive file named F<filename>. +If there was any previous hivex handle associated with this +guestfs session, then it is closed. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_close"; added = (1, 19, 35); + style = RErr, [], []; + proc_nr = Some 351; + optional = Some "hivex"; + shortdesc = "close the current hivex handle"; + longdesc = "\ +Close the current hivex handle. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_root"; added = (1, 19, 35); + style = RInt64 "nodeh", [], []; + proc_nr = Some 352; + optional = Some "hivex"; + shortdesc = "return the root node of the hive"; + longdesc = "\ +Return the root node of the hive. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_name"; added = (1, 19, 35); + style = RString "name", [Int64 "nodeh"], []; + proc_nr = Some 353; + optional = Some "hivex"; + shortdesc = "return the name of the node"; + longdesc = "\ +Return the name of C<nodeh>. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_children"; added = (1, 19, 35); + style = RStructList ("nodehs", "hivex_node"), [Int64 "nodeh"], []; + proc_nr = Some 354; + optional = Some "hivex"; + shortdesc = "return list of nodes which are subkeys of node"; + longdesc = "\ +Return the list of nodes which are subkeys of C<nodeh>. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_get_child"; added = (1, 19, 35); + style = RInt64 "child", [Int64 "nodeh"; String "name"], []; + proc_nr = Some 355; + optional = Some "hivex"; + shortdesc = "return the named child of node"; + longdesc = "\ +Return the child of C<nodeh> with the name C<name>, if it exists. +This can return C<0> meaning the name was not found. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_parent"; added = (1, 19, 35); + style = RInt64 "parent", [Int64 "nodeh"], []; + proc_nr = Some 356; + optional = Some "hivex"; + shortdesc = "return the parent of node"; + longdesc = "\ +Return the parent node of C<nodeh>. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_values"; added = (1, 19, 35); + style = RStructList ("valuehs", "hivex_value"), [Int64 "nodeh"], []; + proc_nr = Some 357; + optional = Some "hivex"; + shortdesc = "return list of values attached to node"; + longdesc = "\ +Return the array of (key, datatype, data) tuples attached to C<nodeh>. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_get_value"; added = (1, 19, 35); + style = RInt64 "valueh", [Int64 "nodeh"; String "key"], []; + proc_nr = Some 358; + optional = Some "hivex"; + shortdesc = "return the named value"; + longdesc = "\ +Return the value attached to C<nodeh> which has the +name C<key>, if it exists. This can return C<0> meaning +the key was not found. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_value_key"; added = (1, 19, 35); + style = RString "key", [Int64 "valueh"], []; + proc_nr = Some 359; + optional = Some "hivex"; + shortdesc = "return the key field from the (key, datatype, data) tuple"; + longdesc = "\ +Return the key (name) field of a (key, datatype, data) tuple. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_value_type"; added = (1, 19, 35); + style = RInt64 "datatype", [Int64 "valueh"], []; + proc_nr = Some 360; + optional = Some "hivex"; + shortdesc = "return the data type from the (key, datatype, data) tuple"; + longdesc = "\ +Return the data type field from a (key, datatype, data) tuple. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_value_value"; added = (1, 19, 35); + style = RBufferOut "databuf", [Int64 "valueh"], []; + proc_nr = Some 361; + optional = Some "hivex"; + shortdesc = "return the data field from the (key, datatype, data) tuple"; + longdesc = "\ +Return the data field of a (key, datatype, data) tuple. + +This is a wrapper around the L<hivex(3)> call of the same name. + +See also: C<guestfs_hivex_value_utf8>." }; + + { defaults with + name = "hivex_commit"; added = (1, 19, 35); + style = RErr, [OptString "filename"], []; + proc_nr = Some 362; + optional = Some "hivex"; + tests = [ + InitScratchFS, Always, TestRun ( + [["upload"; "$srcdir/../../test-data/files/minimal"; "/hivex_commit1"]; + ["hivex_open"; "/hivex_commit1"; ""; ""; "true"; ""]; + ["hivex_commit"; "NULL"]]), [["hivex_close"]]; + InitScratchFS, Always, TestResultTrue ( + [["upload"; "$srcdir/../../test-data/files/minimal"; "/hivex_commit2"]; + ["hivex_open"; "/hivex_commit2"; ""; ""; "true"; ""]; + ["hivex_commit"; "/hivex_commit2_copy"]; + ["is_file"; "/hivex_commit2_copy"; "false"]]), [["hivex_close"]] + ]; + shortdesc = "commit (write) changes back to the hive"; + longdesc = "\ +Commit (write) changes to the hive. + +If the optional F<filename> parameter is null, then the changes +are written back to the same hive that was opened. If this is +not null then they are written to the alternate filename given +and the original hive is left untouched. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_add_child"; added = (1, 19, 35); + style = RInt64 "nodeh", [Int64 "parent"; String "name"], []; + proc_nr = Some 363; + optional = Some "hivex"; + shortdesc = "add a child node"; + longdesc = "\ +Add a child node to C<parent> named C<name>. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_delete_child"; added = (1, 19, 35); + style = RErr, [Int64 "nodeh"], []; + proc_nr = Some 364; + optional = Some "hivex"; + shortdesc = "delete a node (recursively)"; + longdesc = "\ +Delete C<nodeh>, recursively if necessary. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + + { defaults with + name = "hivex_node_set_value"; added = (1, 19, 35); + style = RErr, [Int64 "nodeh"; String "key"; Int64 "t"; BufferIn "val"], []; + proc_nr = Some 365; + optional = Some "hivex"; + shortdesc = "set or replace a single value in a node"; + longdesc = "\ +Set or replace a single value under the node C<nodeh>. The +C<key> is the name, C<t> is the type, and C<val> is the data. + +This is a wrapper around the L<hivex(3)> call of the same name." }; + +] diff --git a/generator/actions_hivex.mli b/generator/actions_hivex.mli new file mode 100644 index 0000000..06b8116 --- /dev/null +++ b/generator/actions_hivex.mli @@ -0,0 +1,22 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list +val daemon_functions : Types.action list diff --git a/generator/actions_inspection.ml b/generator/actions_inspection.ml new file mode 100644 index 0000000..72fd4ec --- /dev/null +++ b/generator/actions_inspection.ml @@ -0,0 +1,810 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 + +(* Inspection APIs. *) + +let non_daemon_functions = [ + { 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<guestfs_inspect_get_*> 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<guestfs_mount_ro> and C<guestfs_umount_all> 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<guestfs(3)/INSPECTION> for more details. + +See also C<guestfs_list_filesystems>." }; + + { 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<guestfs(3)/INSPECTION> 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<guestfs_file_architecture>. + +If the architecture could not be determined, then the +string C<unknown> is returned. + +Please read L<guestfs(3)/INSPECTION> 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<guestfs(3)/INSPECTION> 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<not> +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<guestfs(3)/INSPECTION> 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<guestfs(3)/INSPECTION> for more details. +See also C<guestfs_inspect_get_major_version>." }; + + { 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<unknown> is returned. + +Please read L<guestfs(3)/INSPECTION> 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</etc/fstab>. +I<In particular note> 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</boot>) and a value +which is the filesystem that would be mounted there +(eg. F</dev/sda1>). + +Non-mounted devices such as swap devices are I<not> +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<guestfs_inspect_get_drive_mappings>. + +Please read L<guestfs(3)/INSPECTION> for more details. +See also C<guestfs_inspect_get_filesystems>." }; + + { 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<guestfs(3)/INSPECTION> for more details. +See also C<guestfs_inspect_get_mountpoints>." }; + + { defaults with + name = "inspect_get_windows_systemroot"; added = (1, 5, 25); + style = RString "systemroot", [Mountable "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 F</WINDOWS>. + +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<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_get_roots"; added = (1, 7, 3); + 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<guestfs_inspect_os>, +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<guestfs_inspect_os>. + +Please read L<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_get_package_format"; added = (1, 7, 5); + style = RString "packageformat", [Mountable "root"], []; + shortdesc = "get package format used by the operating system"; + longdesc = "\ +This function and C<guestfs_inspect_get_package_management> return +the package format and package management tool used by the +inspected operating system. For example for Fedora these +functions would return C<rpm> (package format), and +C<yum> or C<dnf> (package management). + +This returns the string C<unknown> if we could not determine the +package format I<or> if the operating system does not have +a real packaging system (eg. Windows). + +Possible strings include: +C<rpm>, C<deb>, C<ebuild>, C<pisi>, C<pacman>, C<pkgsrc>, C<apk>, +C<xbps>. +Future versions of libguestfs may return other strings. + +Please read L<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_get_package_management"; added = (1, 7, 5); + style = RString "packagemanagement", [Mountable "root"], []; + shortdesc = "get package management tool used by the operating system"; + longdesc = "\ +C<guestfs_inspect_get_package_format> 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<rpm> (package format), and +C<yum> or C<dnf> (package management). + +This returns the string C<unknown> if we could not determine the +package management tool I<or> if the operating system does not have +a real packaging system (eg. Windows). + +Possible strings include: C<yum>, C<dnf>, C<up2date>, +C<apt> (for all Debian derivatives), +C<portage>, C<pisi>, C<pacman>, C<urpmi>, C<zypper>, C<apk>, C<xbps>. +Future versions of libguestfs may return other strings. + +Please read L<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_list_applications2"; added = (1, 19, 56); + style = RStructList ("applications2", "application2"), [Mountable "root"], []; + shortdesc = "get list of applications installed in the operating system"; + longdesc = "\ +Return the list of applications installed in the operating system. + +I<Note:> This call works differently from other parts of the +inspection API. You have to call C<guestfs_inspect_os>, then +C<guestfs_inspect_get_mountpoints>, 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<guestfs_inspect_get_*> 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<app2_name> + +The name of the application. For Red Hat-derived and Debian-derived +Linux guests, this is the package name. + +=item C<app2_display_name> + +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<app2_name> instead. + +=item C<app2_epoch> + +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<app2_version> + +The version string of the application or package. If unavailable +this is returned as an empty string C<\"\">. + +=item C<app2_release> + +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<app2_arch> + +The architecture string of the application or package, for package +managers that use this. If unavailable this is returned as an empty +string C<\"\">. + +=item C<app2_install_path> + +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<app2_trans_path> + +The install path translated into a libguestfs path. +If unavailable this is returned as an empty string C<\"\">. + +=item C<app2_publisher> + +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<app2_url> + +The URL (eg. upstream URL) of the application. +If unavailable this is returned as an empty string C<\"\">. + +=item C<app2_source_package> + +For packaging systems which support this, the name of the source +package. If unavailable this is returned as an empty string C<\"\">. + +=item C<app2_summary> + +A short (usually one line) description of the application or package. +If unavailable this is returned as an empty string C<\"\">. + +=item C<app2_description> + +A longer description of the application or package. +If unavailable this is returned as an empty string C<\"\">. + +=back + +Please read L<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_get_hostname"; added = (1, 7, 9); + style = RString "hostname", [Mountable "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<unknown> is returned. + +Please read L<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_get_format"; added = (1, 9, 4); + style = RString "format", [Mountable "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<bootable> 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<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_is_live"; added = (1, 9, 4); + style = RBool "live", [Mountable "root"], []; + shortdesc = "get live flag for install disk"; + longdesc = "\ +If C<guestfs_inspect_get_format> returns C<installer> (this +is an install disk), then this returns true if a live image +was detected on the disk. + +Please read L<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_is_netinst"; added = (1, 9, 4); + style = RBool "netinst", [Mountable "root"], []; + shortdesc = "get netinst (network installer) flag for install disk"; + longdesc = "\ +If C<guestfs_inspect_get_format> returns C<installer> (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<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_is_multipart"; added = (1, 9, 4); + style = RBool "multipart", [Mountable "root"], []; + shortdesc = "get multipart flag for install disk"; + longdesc = "\ +If C<guestfs_inspect_get_format> returns C<installer> (this +is an install disk), then this returns true if the disk is +part of a set. + +Please read L<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_get_product_variant"; added = (1, 9, 13); + style = RString "variant", [Mountable "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<HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion> +C<InstallationType> which is usually a string such as +C<Client> or C<Server> (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<Client> and the latter is C<Server>). + +For enterprise Linux guests, in future we intend this to return +the product variant such as C<Desktop>, C<Server> and so on. But +this is not implemented at present. + +If the product variant could not be determined, then the +string C<unknown> is returned. + +Please read L<guestfs(3)/INSPECTION> for more details. +See also C<guestfs_inspect_get_product_name>, +C<guestfs_inspect_get_major_version>." }; + + { defaults with + name = "inspect_get_windows_current_control_set"; added = (1, 9, 17); + style = RString "controlset", [Mountable "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<ControlSet001>. + +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<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_get_drive_mappings"; added = (1, 9, 17); + style = RHashtable "drives", [Mountable "root"], []; + shortdesc = "get drive letter mappings"; + longdesc = "\ +This call is useful for Windows which uses a primitive system +of assigning drive letters (like F<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<h0>, C<h1> 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<guestfs(3)/INSPECTION> for more details. +See also C<guestfs_inspect_get_mountpoints>, +C<guestfs_inspect_get_filesystems>." }; + + { defaults with + name = "inspect_get_icon"; added = (1, 11, 12); + style = RBufferOut "icon", [Mountable "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<Callers must check for this case>. + +Libguestfs will start by looking for a file called +F</etc/favicon.png> or F<C:\\etc\\favicon.png> +and if it has the correct format, the contents of this file will +be returned. You can disable favicons by passing the +optional C<favicon> 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<highquality> 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<Security:> 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<wrestool> program from the C<icoutils> package, and +several programs (C<bmptopnm>, C<pnmtopng>, C<pamcut>) +from the C<netpbm> 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 = "inspect_get_windows_software_hive"; added = (1, 35, 26); + style = RString "path", [Mountable "root"], []; + shortdesc = "get the path of the Windows software hive"; + longdesc = "\ +This returns the path to the hive (binary Windows Registry file) +corresponding to HKLM\\SOFTWARE. + +This call assumes that the guest is Windows and that the guest +has a software hive file with the right name. If this is not the +case then an error is returned. This call does not check that the +hive is a valid Windows Registry hive. + +You can use C<guestfs_hivex_open> to read or write to the hive. + +Please read L<guestfs(3)/INSPECTION> for more details." }; + + { defaults with + name = "inspect_get_windows_system_hive"; added = (1, 35, 26); + style = RString "path", [Mountable "root"], []; + shortdesc = "get the path of the Windows system hive"; + longdesc = "\ +This returns the path to the hive (binary Windows Registry file) +corresponding to HKLM\\SYSTEM. + +This call assumes that the guest is Windows and that the guest +has a system hive file with the right name. If this is not the +case then an error is returned. This call does not check that the +hive is a valid Windows Registry hive. + +You can use C<guestfs_hivex_open> to read or write to the hive. + +Please read L<guestfs(3)/INSPECTION> for more details." }; + +] diff --git a/generator/actions_inspection.mli b/generator/actions_inspection.mli new file mode 100644 index 0000000..327f7aa --- /dev/null +++ b/generator/actions_inspection.mli @@ -0,0 +1,21 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list diff --git a/generator/actions_inspection_deprecated.ml b/generator/actions_inspection_deprecated.ml new file mode 100644 index 0000000..04fb143 --- /dev/null +++ b/generator/actions_inspection_deprecated.ml @@ -0,0 +1,124 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 + +(* Inspection APIs. *) + +let non_daemon_functions = [ + { defaults with + name = "inspect_list_applications"; added = (1, 7, 8); + style = RStructList ("applications", "application"), [Mountable "root"], []; + deprecated_by = Some "inspect_list_applications2"; + shortdesc = "get list of applications installed in the operating system"; + longdesc = "\ +Return the list of applications installed in the operating system. + +I<Note:> This call works differently from other parts of the +inspection API. You have to call C<guestfs_inspect_os>, then +C<guestfs_inspect_get_mountpoints>, 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<guestfs_inspect_get_*> 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<app_name> + +The name of the application. For Red Hat-derived and Debian-derived +Linux guests, this is the package name. + +=item C<app_display_name> + +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<app_name> instead. + +=item C<app_epoch> + +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<app_version> + +The version string of the application or package. If unavailable +this is returned as an empty string C<\"\">. + +=item C<app_release> + +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<app_install_path> + +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<app_trans_path> + +The install path translated into a libguestfs path. +If unavailable this is returned as an empty string C<\"\">. + +=item C<app_publisher> + +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<app_url> + +The URL (eg. upstream URL) of the application. +If unavailable this is returned as an empty string C<\"\">. + +=item C<app_source_package> + +For packaging systems which support this, the name of the source +package. If unavailable this is returned as an empty string C<\"\">. + +=item C<app_summary> + +A short (usually one line) description of the application or package. +If unavailable this is returned as an empty string C<\"\">. + +=item C<app_description> + +A longer description of the application or package. +If unavailable this is returned as an empty string C<\"\">. + +=back + +Please read L<guestfs(3)/INSPECTION> for more details." }; + +] diff --git a/generator/actions_inspection_deprecated.mli b/generator/actions_inspection_deprecated.mli new file mode 100644 index 0000000..327f7aa --- /dev/null +++ b/generator/actions_inspection_deprecated.mli @@ -0,0 +1,21 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list diff --git a/generator/actions_properties.ml b/generator/actions_properties.ml new file mode 100644 index 0000000..8f6455b --- /dev/null +++ b/generator/actions_properties.ml @@ -0,0 +1,642 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 + +(* APIs related to handle properties. *) + +let non_daemon_functions = [ + { 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<linux> or C<vmlinux> binary. + +The default is chosen when the library was compiled by the +configure script. + +You can also override this by setting the C<LIBGUESTFS_HV> +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<qemu -help>). +If the qemu binary changes, we don't retest features, and +so you might see inconsistent results. Using the environment +variable C<LIBGUESTFS_HV> 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<LIBGUESTFS_PATH> environment variable. + +Setting C<path> to C<NULL> 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<NULL> unless overridden by setting +C<LIBGUESTFS_APPEND> environment variable. + +Setting C<append> to C<NULL> means I<no> 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<NULL> 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<autosync> 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<verbose> is true, this turns on verbose messages. + +Verbose messages are disabled unless the environment variable +C<LIBGUESTFS_DEBUG> is defined and set to C<1>. + +Verbose messages are normally sent to C<stderr>, unless you +register a callback to send them somewhere else (see +C<guestfs_set_event_callback>)." }; + + { 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 = "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<guestfs_launch>. + +You can also change this by setting the environment +variable C<LIBGUESTFS_MEMSIZE> before the handle is +created. + +For more information on the architecture of libguestfs, +see L<guestfs(3)>." }; + + { 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<guestfs_set_memsize> was not called +on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set, +then this returns the compiled-in default value for memsize. + +For more information on the architecture of libguestfs, +see L<guestfs(3)>." }; + + { 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 = "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<ltrace(1)> command. + +Command traces are disabled unless the environment variable +C<LIBGUESTFS_TRACE> is defined and set to C<1>. + +Trace messages are normally sent to C<stderr>, unless you +register a callback to send them somewhere else (see +C<guestfs_set_event_callback>)." }; + + { 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<guestfs_set_log_message_callback>, +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<false> then +C<guestfs_launch> 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<guestfs_launch>, +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 = "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<network> 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<guestfs(3)/RUNNING COMMANDS>). + +You must call this before calling C<guestfs_launch>, 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 = "set_backend"; added = (1, 21, 26); + style = RErr, [String "backend"], []; + fish_alias = ["backend"]; config_only = true; + blocking = false; + shortdesc = "set the backend"; + longdesc = "\ +Set the method that libguestfs uses to connect to the backend +guestfsd daemon. + +This handle property was previously called the \"attach method\". + +See L<guestfs(3)/BACKEND>." }; + + { defaults with + name = "get_backend"; added = (1, 21, 26); + style = RString "backend", [], []; + blocking = false; + tests = [ + InitNone, Always, TestRun ( + [["get_backend"]]), [] + ]; + shortdesc = "get the backend"; + longdesc = "\ +Return the current backend. + +This handle property was previously called the \"attach method\". + +See C<guestfs_set_backend> and L<guestfs(3)/BACKEND>." }; + + { defaults with + name = "set_pgroup"; added = (1, 11, 18); + style = RErr, [Bool "pgroup"], []; + fish_alias = ["pgroup"]; config_only = true; + blocking = false; + shortdesc = "set process group flag"; + longdesc = "\ +If C<pgroup> is true, child processes are placed into +their own process group. + +The practical upshot of this is that signals like C<SIGINT> (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<guestfs_user_cancel>)." }; + + { defaults with + name = "get_pgroup"; added = (1, 11, 18); + style = RBool "pgroup", [], []; + blocking = false; + shortdesc = "get process group flag"; + longdesc = "\ +This returns the process group flag." }; + + { defaults with + name = "set_smp"; added = (1, 13, 15); + style = RErr, [Int "smp"], []; + fish_alias = ["smp"]; config_only = true; + blocking = false; + 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<guestfs_launch>." }; + + { defaults with + name = "get_smp"; added = (1, 13, 15); + style = RInt "smp", [], []; + blocking = false; + shortdesc = "get number of virtual CPUs in appliance"; + longdesc = "\ +This returns the number of virtual CPUs assigned to the appliance." }; + + { defaults with + name = "set_tmpdir"; added = (1, 19, 58); + style = RErr, [OptString "tmpdir"], []; + fish_alias = ["tmpdir"]; config_only = true; + blocking = false; + shortdesc = "set the temporary directory"; + longdesc = "\ +Set the directory used by the handle to store temporary files. + +The environment variables C<LIBGUESTFS_TMPDIR> and C<TMPDIR> +control the default value: If C<LIBGUESTFS_TMPDIR> is set, then +that is the default. Else if C<TMPDIR> is set, then that is +the default. Else F</tmp> is the default." }; + + { defaults with + name = "get_tmpdir"; added = (1, 19, 58); + style = RString "tmpdir", [], []; + blocking = false; + shortdesc = "get the temporary directory"; + longdesc = "\ +Get the directory used by the handle to store temporary files." }; + + { defaults with + name = "set_cachedir"; added = (1, 19, 58); + style = RErr, [OptString "cachedir"], []; + fish_alias = ["cachedir"]; config_only = true; + blocking = false; + shortdesc = "set the appliance cache directory"; + longdesc = "\ +Set the directory used by the handle to store the appliance +cache, when using a supermin appliance. The appliance is +cached and shared between all handles which have the same +effective user ID. + +The environment variables C<LIBGUESTFS_CACHEDIR> and C<TMPDIR> +control the default value: If C<LIBGUESTFS_CACHEDIR> is set, then +that is the default. Else if C<TMPDIR> is set, then that is +the default. Else F</var/tmp> is the default." }; + + { defaults with + name = "get_cachedir"; added = (1, 19, 58); + style = RString "cachedir", [], []; + blocking = false; + shortdesc = "get the appliance cache directory"; + longdesc = "\ +Get the directory used by the handle to store the appliance cache." }; + + { defaults with + name = "set_program"; added = (1, 21, 29); + style = RErr, [String "program"], []; + fish_alias = ["program"]; + blocking = false; + shortdesc = "set the program name"; + longdesc = "\ +Set the program name. This is an informative string which the +main program may optionally set in the handle. + +When the handle is created, the program name in the handle is +set to the basename from C<argv[0]>. The program name can never +be C<NULL>." }; + + { defaults with + name = "get_program"; added = (1, 21, 29); + style = RConstString "program", [], []; + blocking = false; + tests = [ + InitNone, Always, TestRun ( + [["get_program"]]), [] + ]; + shortdesc = "get the program name"; + longdesc = "\ +Get the program name. See C<guestfs_set_program>." }; + + { defaults with + name = "get_backend_settings"; added = (1, 25, 24); + style = RStringList "settings", [], []; + blocking = false; + tests = [ + InitNone, Always, TestRun ( + [["get_backend_settings"]]), [] + ]; + shortdesc = "get per-backend settings"; + longdesc = "\ +Return the current backend settings. + +This call returns all backend settings strings. If you want to +find a single backend setting, see C<guestfs_get_backend_setting>. + +See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; + + { defaults with + name = "set_backend_settings"; added = (1, 25, 24); + style = RErr, [StringList "settings"], []; + config_only = true; + blocking = false; + shortdesc = "replace per-backend settings strings"; + longdesc = "\ +Set a list of zero or more settings which are passed through to +the current backend. Each setting is a string which is interpreted +in a backend-specific way, or ignored if not understood by the +backend. + +The default value is an empty list, unless the environment +variable C<LIBGUESTFS_BACKEND_SETTINGS> was set when the handle +was created. This environment variable contains a colon-separated +list of settings. + +This call replaces all backend settings. If you want to replace +a single backend setting, see C<guestfs_set_backend_setting>. +If you want to clear a single backend setting, see +C<guestfs_clear_backend_setting>. + +See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; + + { defaults with + name = "get_backend_setting"; added = (1, 27, 2); + style = RString "val", [String "name"], []; + blocking = false; + shortdesc = "get a single per-backend settings string"; + longdesc = "\ +Find a backend setting string which is either C<\"name\"> or +begins with C<\"name=\">. If C<\"name\">, this returns the +string C<\"1\">. If C<\"name=\">, this returns the part +after the equals sign (which may be an empty string). + +If no such setting is found, this function throws an error. +The errno (see C<guestfs_last_errno>) will be C<ESRCH> in this +case. + +See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; + + { defaults with + name = "set_backend_setting"; added = (1, 27, 2); + style = RErr, [String "name"; String "val"], []; + config_only = true; + blocking = false; + shortdesc = "set a single per-backend settings string"; + longdesc = "\ +Append C<\"name=value\"> to the backend settings string list. +However if a string already exists matching C<\"name\"> +or beginning with C<\"name=\">, then that setting is replaced. + +See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; + + { defaults with + name = "clear_backend_setting"; added = (1, 27, 2); + style = RInt "count", [String "name"], []; + config_only = true; + blocking = false; + shortdesc = "remove a single per-backend settings string"; + longdesc = "\ +If there is a backend setting string matching C<\"name\"> or +beginning with C<\"name=\">, then that string is removed +from the backend settings. + +This call returns the number of strings which were removed +(which may be 0, 1 or greater than 1). + +See L<guestfs(3)/BACKEND>, L<guestfs(3)/BACKEND SETTINGS>." }; + + { defaults with + name = "set_identifier"; added = (1, 31, 14); + style = RErr, [String "identifier"], []; + fish_alias = ["identifier"]; + blocking = false; + shortdesc = "set the handle identifier"; + longdesc = "\ +This is an informative string which the caller may optionally +set in the handle. It is printed in various places, allowing +the current handle to be identified in debugging output. + +One important place is when tracing is enabled. If the +identifier string is not an empty string, then trace messages +change from this: + + libguestfs: trace: get_tmpdir + libguestfs: trace: get_tmpdir = \"/tmp\" + +to this: + + libguestfs: trace: ID: get_tmpdir + libguestfs: trace: ID: get_tmpdir = \"/tmp\" + +where C<ID> is the identifier string set by this call. + +The identifier must only contain alphanumeric ASCII characters, +underscore and minus sign. The default is the empty string. + +See also C<guestfs_set_program>, C<guestfs_set_trace>, +C<guestfs_get_identifier>." }; + + { defaults with + name = "get_identifier"; added = (1, 31, 14); + style = RConstString "identifier", [], []; + blocking = false; + tests = [ + InitNone, Always, TestRun ( + [["get_identifier"]]), [] + ]; + shortdesc = "get the handle identifier"; + longdesc = "\ +Get the handle identifier. See C<guestfs_set_identifier>." }; + + { defaults with + name = "get_sockdir"; added = (1, 33, 8); + style = RString "sockdir", [], []; + blocking = false; + shortdesc = "get the temporary directory for sockets"; + longdesc = "\ +Get the directory used by the handle to store temporary socket files. + +This is different from C<guestfs_tmpdir>, as we need shorter paths for +sockets (due to the limited buffers of filenames for UNIX sockets), +and C<guestfs_tmpdir> may be too long for them. + +The environment variable C<XDG_RUNTIME_DIR> controls the default +value: If C<XDG_RUNTIME_DIR> is set, then that is the default. +Else F</tmp> is the default." }; + +] + +let daemon_functions = [ +] diff --git a/generator/actions_properties.mli b/generator/actions_properties.mli new file mode 100644 index 0000000..327f7aa --- /dev/null +++ b/generator/actions_properties.mli @@ -0,0 +1,21 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list diff --git a/generator/actions_properties_deprecated.ml b/generator/actions_properties_deprecated.ml new file mode 100644 index 0000000..3fe8fef --- /dev/null +++ b/generator/actions_properties_deprecated.ml @@ -0,0 +1,131 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 + +(* APIs related to handle properties. + * All the APIs in this file are deprecated. + *) + +let non_daemon_functions = [ + { 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<LIBGUESTFS_HV> +environment variable. + +Setting C<hv> to C<NULL> 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<qemu -help>). +If the qemu binary changes, we don't retest features, and +so you might see inconsistent results. Using the environment +variable C<LIBGUESTFS_HV> 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_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<selinux=0> (disabled). + +Note that if SELinux is enabled, it is always in +Permissive mode (C<enforcing=0>). + +For more information on the architecture of libguestfs, +see L<guestfs(3)>." }; + + { 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<guestfs_set_selinux>. + +For more information on the architecture of libguestfs, +see L<guestfs(3)>." }; + + { defaults with + name = "set_attach_method"; added = (1, 9, 8); + style = RErr, [String "backend"], []; + fish_alias = ["attach-method"]; config_only = true; + blocking = false; + deprecated_by = Some "set_backend"; + shortdesc = "set the backend"; + longdesc = "\ +Set the method that libguestfs uses to connect to the backend +guestfsd daemon. + +See L<guestfs(3)/BACKEND>." }; + + { defaults with + name = "get_attach_method"; added = (1, 9, 8); + style = RString "backend", [], []; + blocking = false; + deprecated_by = Some "get_backend"; + tests = [ + InitNone, Always, TestRun ( + [["get_attach_method"]]), [] + ]; + shortdesc = "get the backend"; + longdesc = "\ +Return the current backend. + +See C<guestfs_set_backend> and L<guestfs(3)/BACKEND>." }; + +] + +let daemon_functions = [ +] diff --git a/generator/actions_properties_deprecated.mli b/generator/actions_properties_deprecated.mli new file mode 100644 index 0000000..327f7aa --- /dev/null +++ b/generator/actions_properties_deprecated.mli @@ -0,0 +1,21 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list diff --git a/generator/actions_tsk.ml b/generator/actions_tsk.ml new file mode 100644 index 0000000..cde1c58 --- /dev/null +++ b/generator/actions_tsk.ml @@ -0,0 +1,231 @@ +(* libguestfs + * Copyright (C) 2009-2017 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 + +(* SleuthKit APIs. *) + +let non_daemon_functions = [ + { defaults with + name = "filesystem_walk"; added = (1, 33, 39); + style = RStructList ("dirents", "tsk_dirent"), [Mountable "device";], []; + optional = Some "libtsk"; + progress = true; cancellable = true; + shortdesc = "walk through the filesystem content"; + longdesc = "\ +Walk through the internal structures of a disk partition +(eg. F</dev/sda1>) in order to return a list of all the files +and directories stored within. + +It is not necessary to mount the disk partition to run this command. + +All entries in the filesystem are returned. This function can list deleted +or unaccessible files. The entries are I<not> sorted. + +The C<tsk_dirent> structure contains the following fields. + +=over 4 + +=item 'tsk_inode' + +Filesystem reference number of the node. It migh be C<0> +if the node has been deleted. + +=item 'tsk_type' + +Basic file type information. +See below for a detailed list of values. + +=item 'tsk_size' + +File size in bytes. It migh be C<-1> +if the node has been deleted. + +=item 'tsk_name' + +The file path relative to its directory. + +=item 'tsk_flags' + +Bitfield containing extra information regarding the entry. +It contains the logical OR of the following values: + +=over 4 + +=item 0x0001 + +If set to C<1>, the file is allocated and visible within the filesystem. +Otherwise, the file has been deleted. +Under certain circumstances, the function C<download_inode> +can be used to recover deleted files. + +=item 0x0002 + +Filesystem such as NTFS and Ext2 or greater, separate the file name +from the metadata structure. +The bit is set to C<1> when the file name is in an unallocated state +and the metadata structure is in an allocated one. +This generally implies the metadata has been reallocated to a new file. +Therefore, information such as file type, file size, timestamps, +number of links and symlink target might not correspond +with the ones of the original deleted entry. + +=item 0x0004 + +The bit is set to C<1> when the file is compressed using filesystem +native compression support (NTFS). The API is not able to detect +application level compression. + +=back + +=item 'tsk_atime_sec' + +=item 'tsk_atime_nsec' + +=item 'tsk_mtime_sec' + +=item 'tsk_mtime_nsec' + +=item 'tsk_ctime_sec' + +=item 'tsk_ctime_nsec' + +=item 'tsk_crtime_sec' + +=item 'tsk_crtime_nsec' + +Respectively, access, modification, last status change and creation +time in Unix format in seconds and nanoseconds. + +=item 'tsk_nlink' + +Number of file names pointing to this entry. + +=item 'tsk_link' + +If the entry is a symbolic link, this field will contain the path +to the target file. + +=back + +The C<tsk_type> field will contain one of the following characters: + +=over 4 + +=item 'b' + +Block special + +=item 'c' + +Char special + +=item 'd' + +Directory + +=item 'f' + +FIFO (named pipe) + +=item 'l' + +Symbolic link + +=item 'r' + +Regular file + +=item 's' + +Socket + +=item 'h' + +Shadow inode (Solaris) + +=item 'w' + +Whiteout inode (BSD) + +=item 'u' + +Unknown file type + +=back" }; + + { defaults with + name = "find_inode"; added = (1, 35, 6); + style = RStructList ("dirents", "tsk_dirent"), [Mountable "device"; Int64 "inode";], []; + optional = Some "libtsk"; + progress = true; cancellable = true; + shortdesc = "search the entries associated to the given inode"; + longdesc = "\ +Searches all the entries associated with the given inode. + +For each entry, a C<tsk_dirent> structure is returned. +See C<filesystem_walk> for more information about C<tsk_dirent> structures." }; + +] + +let daemon_functions = [ + { defaults with + name = "internal_filesystem_walk"; added = (1, 33, 39); + style = RErr, [Mountable "device"; FileOut "filename"], []; + proc_nr = Some 466; + visibility = VInternal; + optional = Some "libtsk"; + shortdesc = "walk through the filesystem content"; + longdesc = "Internal function for filesystem_walk." }; + + { defaults with + name = "download_blocks"; added = (1, 33, 45); + style = RErr, [Mountable "device"; Int64 "start"; Int64 "stop"; FileOut "filename"], [OBool "unallocated"]; + proc_nr = Some 468; + optional = Some "sleuthkit"; + progress = true; cancellable = true; + shortdesc = "download the given data units from the disk"; + longdesc = "\ +Download the data units from F<start> address +to F<stop> from the disk partition (eg. F</dev/sda1>) +and save them as F<filename> on the local machine. + +The use of this API on sparse disk image formats such as QCOW, +may result in large zero-filled files downloaded on the host. + +The size of a data unit varies across filesystem implementations. +On NTFS filesystems data units are referred as clusters +while on ExtX ones they are referred as fragments. + +If the optional C<unallocated> flag is true (default is false), +only the unallocated blocks will be extracted. +This is useful to detect hidden data or to retrieve deleted files +which data units have not been overwritten yet." }; + + { defaults with + name = "internal_find_inode"; added = (1, 35, 6); + style = RErr, [Mountable "device"; Int64 "inode"; FileOut "filename";], []; + proc_nr = Some 470; + visibility = VInternal; + optional = Some "libtsk"; + shortdesc = "search the entries associated to the given inode"; + longdesc = "Internal function for find_inode." }; + +] diff --git a/generator/actions_tsk.mli b/generator/actions_tsk.mli new file mode 100644 index 0000000..06b8116 --- /dev/null +++ b/generator/actions_tsk.mli @@ -0,0 +1,22 @@ +(* libguestfs + * Copyright (C) 2009-2017 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. *) + +val non_daemon_functions : Types.action list +val daemon_functions : Types.action list -- 2.10.2