X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fgenerator.ml;h=b3f27cd709362bd29f356a6264c64dd72665b943;hp=1017ad1c134fab0e44150fa11720da627da888ed;hb=0c07f0d23698798475e0d09491812aca52440328;hpb=5365ebd501850ea10d9a5b28fc6480ea34dbe16d diff --git a/src/generator.ml b/src/generator.ml index 1017ad1..e3453a3 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -24,15 +24,16 @@ * this one to describe the interface (see the big table below), and * daemon/.c to write the implementation. * - * After editing this file, run it (./src/generator.ml) to regenerate - * all the output files. + * After editing this file, run it (./src/generator.ml) to regenerate all the + * output files. Note that if you are using a separate build directory you + * must run generator.ml from the _source_ directory. * * IMPORTANT: This script should NOT print any warnings. If it prints * warnings, you should treat them as errors. - * [Need to add -warn-error to ocaml command line] *) #load "unix.cma";; +#load "str.cma";; open Printf @@ -42,29 +43,86 @@ and ret = * indication, ie. 0 or -1. *) | RErr + (* "RInt" as a return value means an int which is -1 for error - * or any value >= 0 on success. + * or any value >= 0 on success. Only use this for smallish + * positive ints (0 <= i < 2^30). *) | RInt of string + + (* "RInt64" is the same as RInt, but is guaranteed to be able + * to return a full 64 bit value, _except_ that -1 means error + * (so -1 cannot be a valid, non-error return value). + *) + | RInt64 of string + (* "RBool" is a bool return value which can be true/false or * -1 for error. *) | RBool of string + (* "RConstString" is a string that refers to a constant value. + * The return value must NOT be NULL (since NULL indicates + * an error). + * * Try to avoid using this. In particular you cannot use this * for values returned from the daemon, because there is no * thread-safe way to return them in the C API. *) | RConstString of string - (* "RString" and "RStringList" are caller-frees. *) + + (* "RConstOptString" is an even more broken version of + * "RConstString". The returned string may be NULL and there + * is no way to return an error indication. Avoid using this! + *) + | RConstOptString of string + + (* "RString" is a returned string. It must NOT be NULL, since + * a NULL return indicates an error. The caller frees this. + *) | RString of string + + (* "RStringList" is a list of strings. No string in the list + * can be NULL. The caller frees the strings and the array. + *) | RStringList of string - (* Some limited tuples are possible: *) - | RIntBool of string * string - (* LVM PVs, VGs and LVs. *) - | RPVList of string - | RVGList of string - | RLVList of string + + (* "RStruct" is a function which returns a single named structure + * or an error indication (in C, a struct, and in other languages + * with varying representations, but usually very efficient). See + * after the function list below for the structures. + *) + | RStruct of string * string (* name of retval, name of struct *) + + (* "RStructList" is a function which returns either a list/array + * of structures (could be zero-length), or an error indication. + *) + | RStructList of string * string (* name of retval, name of struct *) + + (* Key-value pairs of untyped strings. Turns into a hashtable or + * dictionary in languages which support it. DON'T use this as a + * general "bucket" for results. Prefer a stronger typed return + * value if one is available, or write a custom struct. Don't use + * this if the list could potentially be very long, since it is + * inefficient. Keys should be unique. NULLs are not permitted. + *) + | RHashtable of string + + (* "RBufferOut" is handled almost exactly like RString, but + * it allows the string to contain arbitrary 8 bit data including + * ASCII NUL. In the C API this causes an implicit extra parameter + * to be added of type . The extra parameter + * returns the actual size of the return buffer in bytes. + * + * Other programming languages support strings with arbitrary 8 bit + * data. + * + * At the RPC layer we have to use the opaque<> type instead of + * string<>. Returned data is still limited to the max message + * size (ie. ~ 2 MB). + *) + | RBufferOut of string + and args = argt list (* Function parameters, guestfs handle is implicit. *) (* Note in future we should allow a "variable args" parameter as @@ -76,10 +134,33 @@ and args = argt list (* Function parameters, guestfs handle is implicit. *) *) and argt = | String of string (* const char *name, cannot be NULL *) + | Device of string (* /dev device name, cannot be NULL *) | OptString of string (* const char *name, may be NULL *) | StringList of string(* list of strings (each string cannot be NULL) *) | Bool of string (* boolean *) | Int of string (* int (smallish ints, signed, <= 31 bits) *) + (* These are treated as filenames (simple string parameters) in + * the C API and bindings. But in the RPC protocol, we transfer + * the actual file content up to or down from the daemon. + * FileIn: local machine -> daemon (in request) + * FileOut: daemon -> local machine (in reply) + * In guestfish (only), the special name "-" means read from + * stdin or write to stdout. + *) + | FileIn of string + | FileOut of string +(* Not implemented: + (* Opaque buffer which can contain arbitrary 8 bit data. + * In the C API, this is expressed as pair. + * Most other languages have a string type which can contain + * ASCII NUL. We use whatever type is appropriate for each + * language. + * Buffers are limited by the total message size. To transfer + * large blocks of data, use FileIn/FileOut parameters instead. + * To return an arbitrary buffer, use RBufferOut. + *) + | BufferIn of string +*) type flags = | ProtocolLimitWarning (* display warning about protocol size limits *) @@ -87,65 +168,129 @@ type flags = | FishAlias of string (* provide an alias for this cmd in guestfish *) | FishAction of string (* call this function in guestfish *) | NotInFish (* do not export via guestfish *) - -let protocol_limit_warning = - "Because of the message protocol, there is a transfer limit -of somewhere between 2MB and 4MB. To transfer large files you should use -FTP." - -let danger_will_robinson = - "B." + | NotInDocs (* do not add this function to documentation *) + | DeprecatedBy of string (* function is deprecated, use .. instead *) (* You can supply zero or as many tests as you want per API call. * * Note that the test environment has 3 block devices, of size 500MB, - * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc). - * Note for partitioning purposes, the 500MB device has 63 cylinders. + * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and + * a fourth squashfs block device with some known files on it (/dev/sdd). + * + * Note for partitioning purposes, the 500MB device has 1015 cylinders. + * Number of cylinders was 63 for IDE emulated disks with precisely + * the same size. How exactly this is calculated is a mystery. + * + * The squashfs block device (/dev/sdd) comes from images/test.sqsh. * * To be able to run the tests in a reasonable amount of time, * the virtual machine and block devices are reused between tests. * So don't try testing kill_subprocess :-x * - * Between each test we umount-all and lvm-remove-all. + * Between each test we blockdev-setrw, umount-all, lvm-remove-all. * * Don't assume anything about the previous contents of the block * devices. Use 'Init*' to create some initial scenarios. + * + * You can add a prerequisite clause to any individual test. This + * is a run-time check, which, if it fails, causes the test to be + * skipped. Useful if testing a command which might not work on + * all variations of libguestfs builds. A test that has prerequisite + * of 'Always' is run unconditionally. + * + * In addition, packagers can skip individual tests by setting the + * environment variables: eg: + * SKIP_TEST__=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command) + * SKIP_TEST_=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests) *) -type tests = (test_init * test) list +type tests = (test_init * test_prereq * test) list and test = (* Run the command sequence and just expect nothing to fail. *) | TestRun of seq + (* Run the command sequence and expect the output of the final * command to be the string. *) | TestOutput of seq * string + (* Run the command sequence and expect the output of the final * command to be the list of strings. *) | TestOutputList of seq * string list + + (* Run the command sequence and expect the output of the final + * command to be the list of block devices (could be either + * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th + * character of each string). + *) + | TestOutputListOfDevices of seq * string list + (* Run the command sequence and expect the output of the final * command to be the integer. *) | TestOutputInt of seq * int + + (* Run the command sequence and expect the output of the final + * command to be , eg. ">=", "1". + *) + | TestOutputIntOp of seq * string * int + (* Run the command sequence and expect the output of the final * command to be a true value (!= 0 or != NULL). *) | TestOutputTrue of seq + (* Run the command sequence and expect the output of the final * command to be a false value (== 0 or == NULL, but not an error). *) | TestOutputFalse of seq + (* Run the command sequence and expect the output of the final * command to be a list of the given length (but don't care about * content). *) | TestOutputLength of seq * int + + (* Run the command sequence and expect the output of the final + * command to be a buffer (RBufferOut), ie. string + size. + *) + | TestOutputBuffer of seq * string + + (* Run the command sequence and expect the output of the final + * command to be a structure. + *) + | TestOutputStruct of seq * test_field_compare list + (* Run the command sequence and expect the final command (only) * to fail. *) | TestLastFail of seq +and test_field_compare = + | CompareWithInt of string * int + | CompareWithIntOp of string * string * int + | CompareWithString of string * string + | CompareFieldsIntEq of string * string + | CompareFieldsStrEq of string * string + +(* Test prerequisites. *) +and test_prereq = + (* Test always runs. *) + | Always + + (* Test is currently disabled - eg. it fails, or it tests some + * unimplemented feature. + *) + | Disabled + + (* 'string' is some C code (a function body) that should return + * true or false. The test will run if the code returns true. + *) + | If of string + + (* As for 'If' but the test runs _unless_ the code returns true. *) + | Unless of string + (* Some initial scenarios for testing. *) and test_init = (* Do nothing, block devices could contain random stuff including @@ -153,14 +298,23 @@ and test_init = * a bad idea. *) | InitNone + (* Block devices are empty and no filesystems are mounted. *) | InitEmpty + + (* /dev/sda contains a single partition /dev/sda1, with random + * content. /dev/sdb and /dev/sdc may have random content. + * No LVM. + *) + | InitPartition + (* /dev/sda contains a single partition /dev/sda1, which is formatted * as ext2, empty [except for lost+found] and mounted on /. * /dev/sdb and /dev/sdc may have random content. * No LVM. *) | InitBasicFS + (* /dev/sda: * /dev/sda1 (is a PV): * /dev/VG/LV (size 8MB): @@ -169,6 +323,11 @@ and test_init = *) | InitBasicFSonLVM + (* /dev/sdd (the squashfs, see images/ directory in source) + * is mounted on / + *) + | InitSquashFS + (* Sequence of commands for testing. *) and seq = cmd list and cmd = string list @@ -181,7 +340,78 @@ and cmd = string list * Apart from that, long descriptions are just perldoc paragraphs. *) -let non_daemon_functions = [ +(* These test functions are used in the language binding tests. *) + +let test_all_args = [ + String "str"; + OptString "optstr"; + StringList "strlist"; + Bool "b"; + Int "integer"; + FileIn "filein"; + FileOut "fileout"; +] + +let test_all_rets = [ + (* except for RErr, which is tested thoroughly elsewhere *) + "test0rint", RInt "valout"; + "test0rint64", RInt64 "valout"; + "test0rbool", RBool "valout"; + "test0rconststring", RConstString "valout"; + "test0rconstoptstring", RConstOptString "valout"; + "test0rstring", RString "valout"; + "test0rstringlist", RStringList "valout"; + "test0rstruct", RStruct ("valout", "lvm_pv"); + "test0rstructlist", RStructList ("valout", "lvm_pv"); + "test0rhashtable", RHashtable "valout"; +] + +let test_functions = [ + ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs], + [], + "internal test function - do not use", + "\ +This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +parameter type correctly. + +It echos the contents of each parameter to stdout. + +You probably don't want to call this function."); +] @ List.flatten ( + List.map ( + fun (name, ret) -> + [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs], + [], + "internal test function - do not use", + "\ +This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +return type correctly. + +It converts string C to the return type. + +You probably don't want to call this function."); + (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs], + [], + "internal test function - do not use", + "\ +This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +return type correctly. + +This function always returns an error. + +You probably don't want to call this function.")] + ) test_all_rets +) + +(* non_daemon_functions are any functions which don't get processed + * in the daemon, eg. functions for setting and getting local + * configuration values. + *) + +let non_daemon_functions = test_functions @ [ ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"], [], "launch the qemu subprocess", @@ -223,7 +453,15 @@ 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 is equivalent to the qemu parameter C<-drive file=filename>."); +This is equivalent to the qemu parameter +C<-drive file=filename,cache=off,if=...>. +C is omitted in cases where it is not supported by +the underlying filesystem. + +Note that this call checks for the existence of C. This +stops you from specifying other types of drive which are supported +by qemu such as C and C URLs. To specify those, use +the general C call instead."); ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"], [], @@ -231,7 +469,33 @@ This is equivalent to the qemu parameter C<-drive file=filename>."); "\ This function adds a virtual CD-ROM disk image to the guest. -This is equivalent to the qemu parameter C<-cdrom filename>."); +This is equivalent to the qemu parameter C<-cdrom filename>. + +Note that this call checks for the existence of C. This +stops you from specifying other types of drive which are supported +by qemu such as C and C URLs. To specify those, use +the general C call instead."); + + ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"], + [], + "add a drive in snapshot mode (read-only)", + "\ +This adds a drive in snapshot mode, making it effectively +read-only. + +Note that writes to the device are allowed, and will be seen for +the duration of the guestfs handle, but they are written +to a temporary file which is discarded as soon as the guestfs +handle is closed. We don't currently have any method to enable +changes to be committed, although qemu can support this. + +This is equivalent to the qemu parameter +C<-drive file=filename,snapshot=on,if=...>. + +Note that this call checks for the existence of C. This +stops you from specifying other types of drive which are supported +by qemu such as C and C URLs. To specify those, use +the general C call instead."); ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [], [], @@ -246,6 +510,30 @@ The first character of C string must be a C<-> (dash). C can be NULL."); + ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"], + [], + "set the qemu binary", + "\ +Set the qemu binary that we will use. + +The default is chosen when the library was compiled by the +configure script. + +You can also override this by setting the C +environment variable. + +Setting C to C restores the default qemu binary."); + + ("get_qemu", (RConstString "qemu", []), -1, [], + [InitNone, Always, TestRun ( + [["get_qemu"]])], + "get the qemu binary", + "\ +Return the current qemu binary. + +This is always non-NULL. If it wasn't set already, then this will +return the default qemu binary name."); + ("set_path", (RErr, [String "path"]), -1, [FishAlias "path"], [], "set the search path", @@ -255,13 +543,11 @@ Set the path that libguestfs searches for kernel and initrd.img. The default is C<$libdir/guestfs> unless overridden by setting C environment variable. -The string C is stashed in the libguestfs handle, so the caller -must make sure it remains valid for the lifetime of the handle. - Setting C to C restores the default path."); ("get_path", (RConstString "path", []), -1, [], - [], + [InitNone, Always, TestRun ( + [["get_path"]])], "get the search path", "\ Return the current search path. @@ -269,16 +555,47 @@ Return the current search path. This is always non-NULL. If it wasn't set already, then this will return the default path."); + ("set_append", (RErr, [OptString "append"]), -1, [FishAlias "append"], + [], + "add options to kernel command line", + "\ +This function is used to add additional options to the +guest kernel command line. + +The default is C unless overridden by setting +C environment variable. + +Setting C to C means I additional options +are passed (libguestfs always adds a few of its own)."); + + ("get_append", (RConstOptString "append", []), -1, [], + (* This cannot be tested with the current framework. The + * function can return NULL in normal operations, which the + * test framework interprets as an error. + *) + [], + "get the additional kernel options", + "\ +Return the additional kernel options which are added to the +guest kernel command line. + +If C then no options are added."); + ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"], [], "set autosync mode", "\ If C is true, this enables autosync. Libguestfs will make a -best effort attempt to run C when the handle is closed -(also if the program exits without closing handles)."); +best effort attempt to run C followed by +C when the handle is closed +(also if the program exits without closing handles). + +This is disabled by default (except in guestfish where it is +enabled by default)."); ("get_autosync", (RBool "autosync", []), -1, [], - [], + [InitNone, Always, TestRun ( + [["get_autosync"]])], "get autosync mode", "\ Get the autosync flag."); @@ -296,13 +613,192 @@ C is defined and set to C<1>."); [], "get verbose mode", "\ -This returns the verbose messages flag.") +This returns the verbose messages flag."); + + ("is_ready", (RBool "ready", []), -1, [], + [InitNone, Always, TestOutputTrue ( + [["is_ready"]])], + "is ready to accept commands", + "\ +This returns true iff this handle is ready to accept commands +(in the C state). + +For more information on states, see L."); + + ("is_config", (RBool "config", []), -1, [], + [InitNone, Always, TestOutputFalse ( + [["is_config"]])], + "is in configuration state", + "\ +This returns true iff this handle is being configured +(in the C state). + +For more information on states, see L."); + + ("is_launching", (RBool "launching", []), -1, [], + [InitNone, Always, TestOutputFalse ( + [["is_launching"]])], + "is launching subprocess", + "\ +This returns true iff this handle is launching the subprocess +(in the C state). + +For more information on states, see L."); + + ("is_busy", (RBool "busy", []), -1, [], + [InitNone, Always, TestOutputFalse ( + [["is_busy"]])], + "is busy processing a command", + "\ +This returns true iff this handle is busy processing a command +(in the C state). + +For more information on states, see L."); + + ("get_state", (RInt "state", []), -1, [], + [], + "get the current state", + "\ +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."); + + ("set_busy", (RErr, []), -1, [NotInFish], + [], + "set state to busy", + "\ +This sets the state to C. This is only used when implementing +actions using the low-level API. + +For more information on states, see L."); + + ("set_ready", (RErr, []), -1, [NotInFish], + [], + "set state to ready", + "\ +This sets the state to C. This is only used when implementing +actions using the low-level API. + +For more information on states, see L."); + + ("end_busy", (RErr, []), -1, [NotInFish], + [], + "leave the busy state", + "\ +This sets the state to C, or if in C then it leaves the +state as is. This is only used when implementing +actions using the low-level API. + +For more information on states, see L."); + + ("set_memsize", (RErr, [Int "memsize"]), -1, [FishAlias "memsize"], + [InitNone, Always, TestOutputInt ( + [["set_memsize"; "500"]; + ["get_memsize"]], 500)], + "set memory allocated to the qemu subprocess", + "\ +This sets the memory size in megabytes allocated to the +qemu subprocess. This only has any effect if called before +C. + +You can also change this by setting the environment +variable C before the handle is +created. + +For more information on the architecture of libguestfs, +see L."); + + ("get_memsize", (RInt "memsize", []), -1, [], + [InitNone, Always, TestOutputIntOp ( + [["get_memsize"]], ">=", 256)], + "get memory allocated to the qemu subprocess", + "\ +This gets the memory size in megabytes allocated to the +qemu subprocess. + +If C was not called +on this handle, and if C was not set, +then this returns the compiled-in default value for memsize. + +For more information on the architecture of libguestfs, +see L."); + + ("get_pid", (RInt "pid", []), -1, [FishAlias "pid"], + [InitNone, Always, TestOutputIntOp ( + [["get_pid"]], ">=", 1)], + "get PID of qemu subprocess", + "\ +Return the process ID of the qemu subprocess. If there is no +qemu subprocess, then this will return an error. + +This is an internal call used for debugging and testing."); + + ("version", (RStruct ("version", "version"), []), -1, [], + [InitNone, Always, TestOutputStruct ( + [["version"]], [CompareWithInt ("major", 1)])], + "get the library version number", + "\ +Return the libguestfs version number that the program is linked +against. + +Note that because of dynamic linking this is not necessarily +the version of libguestfs that you compiled against. You can +compile the program, and then at runtime dynamically link +against a completely different C library. + +This call was added in version C<1.0.58>. In previous +versions of libguestfs there was no way to get the version +number. From C code you can use ELF weak linking tricks to find out if +this symbol exists (if it doesn't, then it's an earlier version). + +The call returns a structure with four elements. The first +three (C, C and C) are numbers and +correspond to the usual version triplet. The fourth element +(C) is a string and is normally empty, but may be +used for distro-specific information. + +To construct the original version string: +C<$major.$minor.$release$extra> + +I Don't use this call to test for availability +of features. Distro backports makes this unreliable."); + + ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"], + [InitNone, Always, TestOutputTrue ( + [["set_selinux"; "true"]; + ["get_selinux"]])], + "set SELinux enabled or disabled at appliance boot", + "\ +This sets the selinux flag that is passed to the appliance +at boot time. The default is C (disabled). + +Note that if SELinux is enabled, it is always in +Permissive mode (C). + +For more information on the architecture of libguestfs, +see L."); + + ("get_selinux", (RBool "selinux", []), -1, [], + [], + "get SELinux enabled flag", + "\ +This returns the current setting of the selinux flag which +is passed to the appliance at boot time. See C. + +For more information on the architecture of libguestfs, +see L."); + ] +(* daemon_functions are any functions which cause some action + * to take place in the daemon. + *) + let daemon_functions = [ - ("mount", (RErr, [String "device"; String "mountpoint"]), 1, [], - [InitEmpty, TestOutput ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","]; + ("mount", (RErr, [Device "device"; String "mountpoint"]), 1, [], + [InitEmpty, Always, TestOutput ( + [["sfdiskM"; "/dev/sda"; ","]; ["mkfs"; "ext2"; "/dev/sda1"]; ["mount"; "/dev/sda1"; "/"]; ["write_file"; "/new"; "new file contents"; "0"]; @@ -327,7 +823,7 @@ The filesystem options C and C are set with this call, in order to improve reliability."); ("sync", (RErr, []), 2, [], - [ InitEmpty, TestRun [["sync"]]], + [ InitEmpty, Always, TestRun [["sync"]]], "sync disks, writes are flushed through to the disk image", "\ This syncs the disk, so that any writes are flushed through to the @@ -337,7 +833,7 @@ You should always call this if you have modified a disk image, before closing the handle."); ("touch", (RErr, [String "path"]), 3, [], - [InitBasicFS, TestOutputTrue ( + [InitBasicFS, Always, TestOutputTrue ( [["touch"; "/new"]; ["exists"; "/new"]])], "update file timestamps or create a new file", @@ -347,9 +843,8 @@ update the timestamps on a file, or, if the file does not exist, to create a new zero-length file."); ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning], - [InitBasicFS, TestOutput ( - [["write_file"; "/new"; "new file contents"; "0"]; - ["cat"; "/new"]], "new file contents")], + [InitSquashFS, Always, TestOutput ( + [["cat"; "/known-2"]], "abcdef\n")], "list the contents of a file", "\ Return the contents of the file named C. @@ -357,12 +852,12 @@ Return the contents of the file named C. Note that this function cannot correctly handle binary files (specifically, files containing C<\\0> character which is treated as end of string). For those you need to use the C -function which has a more complex interface."); +or C functions which have a more complex interface."); ("ll", (RString "listing", [String "directory"]), 5, [], [], (* XXX Tricky to test because it depends on the exact format - * of the 'ls -l' command, which changes between F10 and F11. - *) + * of the 'ls -l' command, which changes between F10 and F11. + *) "list the files in a directory (long format)", "\ List the files in C (relative to the root directory, @@ -372,7 +867,7 @@ This command is mostly useful for interactive sessions. It is I intended that you try to parse the output string."); ("ls", (RStringList "listing", [String "directory"]), 6, [], - [InitBasicFS, TestOutputList ( + [InitBasicFS, Always, TestOutputList ( [["touch"; "/new"]; ["touch"; "/newer"]; ["touch"; "/newest"]; @@ -387,8 +882,8 @@ This command is mostly useful for interactive sessions. Programs should probably use C instead."); ("list_devices", (RStringList "devices", []), 7, [], - [InitEmpty, TestOutputList ( - [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"])], + [InitEmpty, Always, TestOutputListOfDevices ( + [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])], "list the block devices", "\ List all the block devices. @@ -396,10 +891,10 @@ List all the block devices. The full block device names are returned, eg. C"); ("list_partitions", (RStringList "partitions", []), 8, [], - [InitBasicFS, TestOutputList ( + [InitBasicFS, Always, TestOutputListOfDevices ( [["list_partitions"]], ["/dev/sda1"]); - InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; + InitEmpty, Always, TestOutputListOfDevices ( + [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])], "list the partitions", "\ @@ -411,10 +906,10 @@ This does not return logical volumes. For that you will need to call C."); ("pvs", (RStringList "physvols", []), 9, [], - [InitBasicFSonLVM, TestOutputList ( + [InitBasicFSonLVM, Always, TestOutputListOfDevices ( [["pvs"]], ["/dev/sda1"]); - InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; + InitEmpty, Always, TestOutputListOfDevices ( + [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; ["pvcreate"; "/dev/sda3"]; @@ -430,10 +925,10 @@ PVs (eg. C). See also C."); ("vgs", (RStringList "volgroups", []), 10, [], - [InitBasicFSonLVM, TestOutputList ( + [InitBasicFSonLVM, Always, TestOutputList ( [["vgs"]], ["VG"]); - InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; + InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; ["pvcreate"; "/dev/sda3"]; @@ -451,10 +946,10 @@ detected (eg. C). See also C."); ("lvs", (RStringList "logvols", []), 11, [], - [InitBasicFSonLVM, TestOutputList ( + [InitBasicFSonLVM, Always, TestOutputList ( [["lvs"]], ["/dev/VG/LV"]); - InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; + InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; ["pvcreate"; "/dev/sda3"]; @@ -474,37 +969,32 @@ This returns a list of the logical volume device names See also C."); - ("pvs_full", (RPVList "physvols", []), 12, [], - [InitBasicFSonLVM, TestOutputLength ( - [["pvs"]], 1)], + ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [], + [], (* XXX how to test? *) "list the LVM physical volumes (PVs)", "\ List all the physical volumes detected. This is the equivalent of the L command. The \"full\" version includes all fields."); - ("vgs_full", (RVGList "volgroups", []), 13, [], - [InitBasicFSonLVM, TestOutputLength ( - [["pvs"]], 1)], + ("vgs_full", (RStructList ("volgroups", "lvm_vg"), []), 13, [], + [], (* XXX how to test? *) "list the LVM volume groups (VGs)", "\ List all the volumes groups detected. This is the equivalent of the L command. The \"full\" version includes all fields."); - ("lvs_full", (RLVList "logvols", []), 14, [], - [InitBasicFSonLVM, TestOutputLength ( - [["pvs"]], 1)], + ("lvs_full", (RStructList ("logvols", "lvm_lv"), []), 14, [], + [], (* XXX how to test? *) "list the LVM logical volumes (LVs)", "\ List all the logical volumes detected. This is the equivalent of the L command. The \"full\" version includes all fields."); ("read_lines", (RStringList "lines", [String "path"]), 15, [], - [InitBasicFS, TestOutputList ( - [["write_file"; "/new"; "line1\r\nline2\nline3"; "0"]; - ["read_lines"; "/new"]], ["line1"; "line2"; "line3"]); - InitBasicFS, TestOutputList ( - [["write_file"; "/new"; ""; "0"]; - ["read_lines"; "/new"]], [])], + [InitSquashFS, Always, TestOutputList ( + [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]); + InitSquashFS, Always, TestOutputList ( + [["read_lines"; "/empty"]], [])], "read file as lines", "\ Return the contents of the file named C. @@ -588,7 +1078,7 @@ undefined. On success this returns the number of nodes in C, or C<0> if C evaluates to something which is not a nodeset."); - ("aug_defnode", (RIntBool ("nrnodes", "created"), [String "name"; String "expr"; String "val"]), 18, [], + ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"]), 18, [], [], (* XXX Augeas code needs tests. *) "define an Augeas node", "\ @@ -677,12 +1167,12 @@ This is just a shortcut for listing C C and sorting the resulting nodes into alphabetical order."); ("rm", (RErr, [String "path"]), 29, [], - [InitBasicFS, TestRun + [InitBasicFS, Always, TestRun [["touch"; "/new"]; ["rm"; "/new"]]; - InitBasicFS, TestLastFail + InitBasicFS, Always, TestLastFail [["rm"; "/new"]]; - InitBasicFS, TestLastFail + InitBasicFS, Always, TestLastFail [["mkdir"; "/new"]; ["rm"; "/new"]]], "remove a file", @@ -690,12 +1180,12 @@ C and sorting the resulting nodes into alphabetical order."); Remove the single file C."); ("rmdir", (RErr, [String "path"]), 30, [], - [InitBasicFS, TestRun + [InitBasicFS, Always, TestRun [["mkdir"; "/new"]; ["rmdir"; "/new"]]; - InitBasicFS, TestLastFail + InitBasicFS, Always, TestLastFail [["rmdir"; "/new"]]; - InitBasicFS, TestLastFail + InitBasicFS, Always, TestLastFail [["touch"; "/new"]; ["rmdir"; "/new"]]], "remove a directory", @@ -703,7 +1193,7 @@ Remove the single file C."); Remove the single directory C."); ("rm_rf", (RErr, [String "path"]), 31, [], - [InitBasicFS, TestOutputFalse + [InitBasicFS, Always, TestOutputFalse [["mkdir"; "/new"]; ["mkdir"; "/new/foo"]; ["touch"; "/new/foo/bar"]; @@ -716,25 +1206,32 @@ contents if its a directory. This is like the C shell command."); ("mkdir", (RErr, [String "path"]), 32, [], - [InitBasicFS, TestOutputTrue + [InitBasicFS, Always, TestOutputTrue [["mkdir"; "/new"]; ["is_dir"; "/new"]]; - InitBasicFS, TestLastFail + InitBasicFS, Always, TestLastFail [["mkdir"; "/new/foo/bar"]]], "create a directory", "\ Create a directory named C."); ("mkdir_p", (RErr, [String "path"]), 33, [], - [InitBasicFS, TestOutputTrue + [InitBasicFS, Always, TestOutputTrue [["mkdir_p"; "/new/foo/bar"]; ["is_dir"; "/new/foo/bar"]]; - InitBasicFS, TestOutputTrue + InitBasicFS, Always, TestOutputTrue [["mkdir_p"; "/new/foo/bar"]; ["is_dir"; "/new/foo"]]; - InitBasicFS, TestOutputTrue + InitBasicFS, Always, TestOutputTrue [["mkdir_p"; "/new/foo/bar"]; - ["is_dir"; "/new"]]], + ["is_dir"; "/new"]]; + (* Regression tests for RHBZ#503133: *) + InitBasicFS, Always, TestRun + [["mkdir"; "/new"]; + ["mkdir_p"; "/new"]]; + InitBasicFS, Always, TestLastFail + [["touch"; "/new"]; + ["mkdir_p"; "/new"]]], "create a directory and parents", "\ Create a directory named C, creating any parent directories @@ -758,12 +1255,10 @@ names, you will need to locate and parse the password file yourself (Augeas support makes this relatively easy)."); ("exists", (RBool "existsflag", [String "path"]), 36, [], - [InitBasicFS, TestOutputTrue ( - [["touch"; "/new"]; - ["exists"; "/new"]]); - InitBasicFS, TestOutputTrue ( - [["mkdir"; "/new"]; - ["exists"; "/new"]])], + [InitSquashFS, Always, TestOutputTrue ( + [["exists"; "/empty"]]); + InitSquashFS, Always, TestOutputTrue ( + [["exists"; "/directory"]])], "test if file or directory exists", "\ This returns C if and only if there is a file, directory @@ -772,12 +1267,10 @@ This returns C if and only if there is a file, directory See also C, C, C."); ("is_file", (RBool "fileflag", [String "path"]), 37, [], - [InitBasicFS, TestOutputTrue ( - [["touch"; "/new"]; - ["is_file"; "/new"]]); - InitBasicFS, TestOutputFalse ( - [["mkdir"; "/new"]; - ["is_file"; "/new"]])], + [InitSquashFS, Always, TestOutputTrue ( + [["is_file"; "/known-1"]]); + InitSquashFS, Always, TestOutputFalse ( + [["is_file"; "/directory"]])], "test if file exists", "\ This returns C if and only if there is a file @@ -787,12 +1280,10 @@ other objects like directories. See also C."); ("is_dir", (RBool "dirflag", [String "path"]), 38, [], - [InitBasicFS, TestOutputFalse ( - [["touch"; "/new"]; - ["is_dir"; "/new"]]); - InitBasicFS, TestOutputTrue ( - [["mkdir"; "/new"]; - ["is_dir"; "/new"]])], + [InitSquashFS, Always, TestOutputFalse ( + [["is_dir"; "/known-3"]]); + InitSquashFS, Always, TestOutputTrue ( + [["is_dir"; "/directory"]])], "test if file exists", "\ This returns C if and only if there is a directory @@ -801,9 +1292,9 @@ other objects like files. See also C."); - ("pvcreate", (RErr, [String "device"]), 39, [], - [InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; + ("pvcreate", (RErr, [Device "device"]), 39, [], + [InitEmpty, Always, TestOutputListOfDevices ( + [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; ["pvcreate"; "/dev/sda3"]; @@ -815,8 +1306,8 @@ where C should usually be a partition name such as C."); ("vgcreate", (RErr, [String "volgroup"; StringList "physvols"]), 40, [], - [InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; + [InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; ["pvcreate"; "/dev/sda3"]; @@ -829,8 +1320,8 @@ This creates an LVM volume group called C from the non-empty list of physical volumes C."); ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"]), 41, [], - [InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; + [InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; ["pvcreate"; "/dev/sda3"]; @@ -849,9 +1340,9 @@ from the non-empty list of physical volumes C."); This creates an LVM volume group called C on the volume group C, with C megabytes."); - ("mkfs", (RErr, [String "fstype"; String "device"]), 42, [], - [InitEmpty, TestOutput ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","]; + ("mkfs", (RErr, [String "fstype"; Device "device"]), 42, [], + [InitEmpty, Always, TestOutput ( + [["sfdiskM"; "/dev/sda"; ","]; ["mkfs"; "ext2"; "/dev/sda1"]; ["mount"; "/dev/sda1"; "/"]; ["write_file"; "/new"; "new file contents"; "0"]; @@ -859,12 +1350,12 @@ on the volume group C, with C megabytes."); "make a filesystem", "\ This creates a filesystem on C (usually a partition -of LVM logical volume). The filesystem type is C, for +or LVM logical volume). The filesystem type is C, for example C."); - ("sfdisk", (RErr, [String "device"; - Int "cyls"; Int "heads"; Int "sectors"; - StringList "lines"]), 43, [DangerWillRobinson], + ("sfdisk", (RErr, [Device "device"; + Int "cyls"; Int "heads"; Int "sectors"; + StringList "lines"]), 43, [DangerWillRobinson], [], "create partitions on a block device", "\ @@ -886,15 +1377,29 @@ information refer to the L manpage. To create a single partition occupying the whole disk, you would pass C as a single element list, when the single element being -the string C<,> (comma)."); +the string C<,> (comma). + +See also: C, C"); ("write_file", (RErr, [String "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning], - [InitEmpty, TestOutput ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","]; - ["mkfs"; "ext2"; "/dev/sda1"]; - ["mount"; "/dev/sda1"; "/"]; - ["write_file"; "/new"; "new file contents"; "0"]; - ["cat"; "/new"]], "new file contents")], + [InitBasicFS, Always, TestOutput ( + [["write_file"; "/new"; "new file contents"; "0"]; + ["cat"; "/new"]], "new file contents"); + InitBasicFS, Always, TestOutput ( + [["write_file"; "/new"; "\nnew file contents\n"; "0"]; + ["cat"; "/new"]], "\nnew file contents\n"); + InitBasicFS, Always, TestOutput ( + [["write_file"; "/new"; "\n\n"; "0"]; + ["cat"; "/new"]], "\n\n"); + InitBasicFS, Always, TestOutput ( + [["write_file"; "/new"; ""; "0"]; + ["cat"; "/new"]], ""); + InitBasicFS, Always, TestOutput ( + [["write_file"; "/new"; "\n\n\n"; "0"]; + ["cat"; "/new"]], "\n\n\n"); + InitBasicFS, Always, TestOutput ( + [["write_file"; "/new"; "\n"; "0"]; + ["cat"; "/new"]], "\n")], "create a file", "\ This call creates a file called C. The contents of the @@ -903,16 +1408,21 @@ with length C. As a special case, if C is C<0> then the length is calculated using C (so in this case -the content cannot contain embedded ASCII NULs)."); +the content cannot contain embedded ASCII NULs). + +I Owing to a bug, writing content containing ASCII NUL +characters does I work, even if the length is specified. +We hope to resolve this bug in a future version. In the meantime +use C."); ("umount", (RErr, [String "pathordevice"]), 45, [FishAlias "unmount"], - [InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","]; + [InitEmpty, Always, TestOutputListOfDevices ( + [["sfdiskM"; "/dev/sda"; ","]; ["mkfs"; "ext2"; "/dev/sda1"]; ["mount"; "/dev/sda1"; "/"]; ["mounts"]], ["/dev/sda1"]); - InitEmpty, TestOutputList ( - [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","]; + InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ","]; ["mkfs"; "ext2"; "/dev/sda1"]; ["mount"; "/dev/sda1"; "/"]; ["umount"; "/"]; @@ -924,18 +1434,34 @@ specified either by its mountpoint (path) or the device which contains the filesystem."); ("mounts", (RStringList "devices", []), 46, [], - [InitBasicFS, TestOutputList ( + [InitBasicFS, Always, TestOutputListOfDevices ( [["mounts"]], ["/dev/sda1"])], "show mounted filesystems", "\ This returns the list of currently mounted filesystems. It returns the list of devices (eg. C, C). -Some internal mounts are not shown."); +Some internal mounts are not shown. + +See also: C"); ("umount_all", (RErr, []), 47, [FishAlias "unmount-all"], - [InitBasicFS, TestOutputList ( + [InitBasicFS, Always, TestOutputList ( [["umount_all"]; + ["mounts"]], []); + (* check that umount_all can unmount nested mounts correctly: *) + InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; + ["mkfs"; "ext2"; "/dev/sda1"]; + ["mkfs"; "ext2"; "/dev/sda2"]; + ["mkfs"; "ext2"; "/dev/sda3"]; + ["mount"; "/dev/sda1"; "/"]; + ["mkdir"; "/mp1"]; + ["mount"; "/dev/sda2"; "/mp1"]; + ["mkdir"; "/mp1/mp2"]; + ["mount"; "/dev/sda3"; "/mp1/mp2"]; + ["mkdir"; "/mp1/mp2/mp3"]; + ["umount_all"]; ["mounts"]], [])], "unmount all filesystems", "\ @@ -951,29 +1477,77 @@ This command removes all LVM logical volumes, volume groups and physical volumes."); ("file", (RString "description", [String "path"]), 49, [], - [InitBasicFS, TestOutput ( - [["touch"; "/new"]; - ["file"; "/new"]], "empty"); - InitBasicFS, TestOutput ( - [["write_file"; "/new"; "some content\n"; "0"]; - ["file"; "/new"]], "ASCII text"); - InitBasicFS, TestLastFail ( - [["file"; "/nofile"]])], + [InitSquashFS, Always, TestOutput ( + [["file"; "/empty"]], "empty"); + InitSquashFS, Always, TestOutput ( + [["file"; "/known-1"]], "ASCII text"); + InitSquashFS, Always, TestLastFail ( + [["file"; "/notexists"]])], "determine file type", "\ This call uses the standard L command to determine the type or contents of the file. This also works on devices, for example to find out whether a partition contains a filesystem. -The exact command which runs is C. Note in +This call will also transparently look inside various types +of compressed file. + +The exact command which runs is C. Note in particular that the filename is not prepended to the output (the C<-b> option)."); - ("command", (RString "output", [StringList "arguments"]), 50, [], - [], (* XXX how to test? *) + ("command", (RString "output", [StringList "arguments"]), 50, [ProtocolLimitWarning], + [InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 1"]], "Result1"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 2"]], "Result2\n"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 3"]], "\nResult3"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 4"]], "\nResult4\n"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 5"]], "\nResult5\n\n"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 6"]], "\n\nResult6\n\n"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 7"]], ""); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 8"]], "\n"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 9"]], "\n\n"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n"); + InitBasicFS, Always, TestOutput ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command 11"]], "Result11-1\nResult11-2"); + InitBasicFS, Always, TestLastFail ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command"; "/test-command"]])], "run a command from the guest filesystem", "\ -This calls runs a command from the guest filesystem. The +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). @@ -981,7 +1555,16 @@ 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). +non-empty (ie. must contain a program name). Note that +the command runs directly, and is I invoked via +the shell (see C). + +The return value is anything printed to I 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 from the command. The C<$PATH> environment variable will contain at least C and C. If you require a program from @@ -994,2562 +1577,6030 @@ correct places. It is the caller's responsibility to ensure all filesystems that are needed are mounted at the right locations."); - ("command_lines", (RStringList "lines", [StringList "arguments"]), 51, [], - [], (* XXX how to test? *) + ("command_lines", (RStringList "lines", [StringList "arguments"]), 51, [ProtocolLimitWarning], + [InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 1"]], ["Result1"]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 2"]], ["Result2"]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 3"]], ["";"Result3"]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 4"]], ["";"Result4"]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 5"]], ["";"Result5";""]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 7"]], []); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 8"]], [""]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 9"]], ["";""]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]); + InitBasicFS, Always, TestOutputList ( + [["upload"; "test-command"; "/test-command"]; + ["chmod"; "0o755"; "/test-command"]; + ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])], "run a command, returning lines", "\ This is the same as C, but splits the -result into a list of lines."); +result into a list of lines. -] +See also: C"); -let all_functions = non_daemon_functions @ daemon_functions + ("stat", (RStruct ("statbuf", "stat"), [String "path"]), 52, [], + [InitSquashFS, Always, TestOutputStruct ( + [["stat"; "/empty"]], [CompareWithInt ("size", 0)])], + "get file information", + "\ +Returns file information for the given C. -(* In some places we want the functions to be displayed sorted - * alphabetically, so this is useful: - *) -let all_functions_sorted = - List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) -> - compare n1 n2) all_functions - -(* Column names and types from LVM PVs/VGs/LVs. *) -let pv_cols = [ - "pv_name", `String; - "pv_uuid", `UUID; - "pv_fmt", `String; - "pv_size", `Bytes; - "dev_size", `Bytes; - "pv_free", `Bytes; - "pv_used", `Bytes; - "pv_attr", `String (* XXX *); - "pv_pe_count", `Int; - "pv_pe_alloc_count", `Int; - "pv_tags", `String; - "pe_start", `Bytes; - "pv_mda_count", `Int; - "pv_mda_free", `Bytes; -(* Not in Fedora 10: - "pv_mda_size", `Bytes; -*) -] -let vg_cols = [ - "vg_name", `String; - "vg_uuid", `UUID; - "vg_fmt", `String; - "vg_attr", `String (* XXX *); - "vg_size", `Bytes; - "vg_free", `Bytes; - "vg_sysid", `String; - "vg_extent_size", `Bytes; - "vg_extent_count", `Int; - "vg_free_count", `Int; - "max_lv", `Int; - "max_pv", `Int; - "pv_count", `Int; - "lv_count", `Int; - "snap_count", `Int; - "vg_seqno", `Int; - "vg_tags", `String; - "vg_mda_count", `Int; - "vg_mda_free", `Bytes; -(* Not in Fedora 10: - "vg_mda_size", `Bytes; -*) -] -let lv_cols = [ - "lv_name", `String; - "lv_uuid", `UUID; - "lv_attr", `String (* XXX *); - "lv_major", `Int; - "lv_minor", `Int; - "lv_kernel_major", `Int; - "lv_kernel_minor", `Int; - "lv_size", `Bytes; - "seg_count", `Int; - "origin", `String; - "snap_percent", `OptPercent; - "copy_percent", `OptPercent; - "move_pv", `String; - "lv_tags", `String; - "mirror_log", `String; - "modules", `String; -] +This is the same as the C system call."); -(* Useful functions. - * Note we don't want to use any external OCaml libraries which - * makes this a bit harder than it should be. - *) -let failwithf fs = ksprintf failwith fs + ("lstat", (RStruct ("statbuf", "stat"), [String "path"]), 53, [], + [InitSquashFS, Always, TestOutputStruct ( + [["lstat"; "/empty"]], [CompareWithInt ("size", 0)])], + "get file information for a symbolic link", + "\ +Returns file information for the given C. -let replace_char s c1 c2 = - let s2 = String.copy s in - let r = ref false in - for i = 0 to String.length s2 - 1 do - if String.unsafe_get s2 i = c1 then ( - String.unsafe_set s2 i c2; - r := true - ) - done; - if not !r then s else s2 +This is the same as C except that if C +is a symbolic link, then the link is stat-ed, not the file it +refers to. -let rec find s sub = - let len = String.length s in - let sublen = String.length sub in - let rec loop i = - if i <= len-sublen then ( - let rec loop2 j = - if j < sublen then ( - if s.[i+j] = sub.[j] then loop2 (j+1) - else -1 - ) else - i (* found *) - in - let r = loop2 0 in - if r = -1 then loop (i+1) else r - ) else - -1 (* not found *) - in - loop 0 +This is the same as the C system call."); -let rec replace_str s s1 s2 = - let len = String.length s in - let sublen = String.length s1 in - let i = find s s1 in - if i = -1 then s - else ( - let s' = String.sub s 0 i in - let s'' = String.sub s (i+sublen) (len-i-sublen) in - s' ^ s2 ^ replace_str s'' s1 s2 - ) + ("statvfs", (RStruct ("statbuf", "statvfs"), [String "path"]), 54, [], + [InitSquashFS, Always, TestOutputStruct ( + [["statvfs"; "/"]], [CompareWithInt ("namemax", 256)])], + "get file system statistics", + "\ +Returns file system statistics for any mounted file system. +C 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). -let rec string_split sep str = - let len = String.length str in - let seplen = String.length sep in - let i = find str sep in - if i = -1 then [str] - else ( - let s' = String.sub str 0 i in - let s'' = String.sub str (i+seplen) (len-i-seplen) in - s' :: string_split sep s'' - ) +This is the same as the C system call."); -let rec find_map f = function - | [] -> raise Not_found - | x :: xs -> - match f x with - | Some y -> y - | None -> find_map f xs + ("tune2fs_l", (RHashtable "superblock", [Device "device"]), 55, [], + [], (* XXX test *) + "get ext2/ext3/ext4 superblock details", + "\ +This returns the contents of the ext2, ext3 or ext4 filesystem +superblock on C. + +It is the same as running C. See L +manpage for more details. The list of fields returned isn't +clearly defined, and depends on both the version of C +that libguestfs was built against, and the filesystem itself."); + + ("blockdev_setro", (RErr, [Device "device"]), 56, [], + [InitEmpty, Always, TestOutputTrue ( + [["blockdev_setro"; "/dev/sda"]; + ["blockdev_getro"; "/dev/sda"]])], + "set block device to read-only", + "\ +Sets the block device named C to read-only. -let iteri f xs = - let rec loop i = function - | [] -> () - | x :: xs -> f i x; loop (i+1) xs - in - loop 0 xs +This uses the L command."); -let mapi f xs = - let rec loop i = function - | [] -> [] - | x :: xs -> let r = f i x in r :: loop (i+1) xs - in - loop 0 xs + ("blockdev_setrw", (RErr, [Device "device"]), 57, [], + [InitEmpty, Always, TestOutputFalse ( + [["blockdev_setrw"; "/dev/sda"]; + ["blockdev_getro"; "/dev/sda"]])], + "set block device to read-write", + "\ +Sets the block device named C to read-write. -let name_of_argt = function - | String n | OptString n | StringList n | Bool n | Int n -> n +This uses the L command."); -(* Check function names etc. for consistency. *) -let check_functions () = - let contains_uppercase str = - let len = String.length str in - let rec loop i = - if i >= len then false - else ( - let c = str.[i] in - if c >= 'A' && c <= 'Z' then true - else loop (i+1) - ) - in - loop 0 - in + ("blockdev_getro", (RBool "ro", [Device "device"]), 58, [], + [InitEmpty, Always, TestOutputTrue ( + [["blockdev_setro"; "/dev/sda"]; + ["blockdev_getro"; "/dev/sda"]])], + "is block device set to read-only", + "\ +Returns a boolean indicating if the block device is read-only +(true if read-only, false if not). - (* Check function names. *) - List.iter ( - fun (name, _, _, _, _, _, _) -> - if String.length name >= 7 && String.sub name 0 7 = "guestfs" then - failwithf "function name %s does not need 'guestfs' prefix" name; - if contains_uppercase name then - failwithf "function name %s should not contain uppercase chars" name; - if String.contains name '-' then - failwithf "function name %s should not contain '-', use '_' instead." - name - ) all_functions; +This uses the L command."); - (* Check function parameter/return names. *) - List.iter ( - fun (name, style, _, _, _, _, _) -> - let check_arg_ret_name n = - if contains_uppercase n then - failwithf "%s param/ret %s should not contain uppercase chars" - name n; - if String.contains n '-' || String.contains n '_' then - failwithf "%s param/ret %s should not contain '-' or '_'" - name n; - if n = "value" then - failwithf "%s has a param/ret called 'value', which causes conflicts in the OCaml bindings, use something like 'val' or a more descriptive name" n; - if n = "argv" || n = "args" then - failwithf "%s has a param/ret called 'argv' or 'args', which will cause some conflicts in the generated code" n - in + ("blockdev_getss", (RInt "sectorsize", [Device "device"]), 59, [], + [InitEmpty, Always, TestOutputInt ( + [["blockdev_getss"; "/dev/sda"]], 512)], + "get sectorsize of block device", + "\ +This returns the size of sectors on a block device. +Usually 512, but can be larger for modern devices. - (match fst style with - | RErr -> () - | RInt n | RBool n | RConstString n | RString n - | RStringList n | RPVList n | RVGList n | RLVList n -> - check_arg_ret_name n - | RIntBool (n,m) -> - check_arg_ret_name n; - check_arg_ret_name m - ); - List.iter (fun arg -> check_arg_ret_name (name_of_argt arg)) (snd style) - ) all_functions; +(Note, this is not the size in sectors, use C +for that). - (* Check short descriptions. *) - List.iter ( - fun (name, _, _, _, _, shortdesc, _) -> - if shortdesc.[0] <> Char.lowercase shortdesc.[0] then - failwithf "short description of %s should begin with lowercase." name; - let c = shortdesc.[String.length shortdesc-1] in - if c = '\n' || c = '.' then - failwithf "short description of %s should not end with . or \\n." name - ) all_functions; +This uses the L command."); - (* Check long dscriptions. *) - List.iter ( - fun (name, _, _, _, _, _, longdesc) -> - if longdesc.[String.length longdesc-1] = '\n' then - failwithf "long description of %s should not end with \\n." name - ) all_functions; + ("blockdev_getbsz", (RInt "blocksize", [Device "device"]), 60, [], + [InitEmpty, Always, TestOutputInt ( + [["blockdev_getbsz"; "/dev/sda"]], 4096)], + "get blocksize of block device", + "\ +This returns the block size of a device. - (* Check proc_nrs. *) - List.iter ( - fun (name, _, proc_nr, _, _, _, _) -> - if proc_nr <= 0 then - failwithf "daemon function %s should have proc_nr > 0" name - ) daemon_functions; +(Note this is different from both I and +I). - List.iter ( - fun (name, _, proc_nr, _, _, _, _) -> - if proc_nr <> -1 then - failwithf "non-daemon function %s should have proc_nr -1" name - ) non_daemon_functions; +This uses the L command."); - let proc_nrs = - List.map (fun (name, _, proc_nr, _, _, _, _) -> name, proc_nr) - daemon_functions in - let proc_nrs = - List.sort (fun (_,nr1) (_,nr2) -> compare nr1 nr2) proc_nrs in - let rec loop = function - | [] -> () - | [_] -> () - | (name1,nr1) :: ((name2,nr2) :: _ as rest) when nr1 < nr2 -> - loop rest - | (name1,nr1) :: (name2,nr2) :: _ -> - failwithf "%s and %s have conflicting procedure numbers (%d, %d)" - name1 name2 nr1 nr2 - in - loop proc_nrs + ("blockdev_setbsz", (RErr, [Device "device"; Int "blocksize"]), 61, [], + [], (* XXX test *) + "set blocksize of block device", + "\ +This sets the block size of a device. -(* 'pr' prints to the current output file. *) -let chan = ref stdout -let pr fs = ksprintf (output_string !chan) fs +(Note this is different from both I and +I). -(* Generate a header block in a number of standard styles. *) -type comment_style = CStyle | HashStyle | OCamlStyle -type license = GPLv2 | LGPLv2 +This uses the L command."); -let generate_header comment license = - let c = match comment with - | CStyle -> pr "/* "; " *" - | HashStyle -> pr "# "; "#" - | OCamlStyle -> pr "(* "; " *" in - pr "libguestfs generated file\n"; - pr "%s WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.\n" c; - pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c; - pr "%s\n" c; - pr "%s Copyright (C) 2009 Red Hat Inc.\n" c; - pr "%s\n" c; - (match license with - | GPLv2 -> - pr "%s This program is free software; you can redistribute it and/or modify\n" c; - pr "%s it under the terms of the GNU General Public License as published by\n" c; - pr "%s the Free Software Foundation; either version 2 of the License, or\n" c; - pr "%s (at your option) any later version.\n" c; - pr "%s\n" c; - pr "%s This program is distributed in the hope that it will be useful,\n" c; - pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c; - pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n" c; - pr "%s GNU General Public License for more details.\n" c; - pr "%s\n" c; - pr "%s You should have received a copy of the GNU General Public License along\n" c; - pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c; - pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c; + ("blockdev_getsz", (RInt64 "sizeinsectors", [Device "device"]), 62, [], + [InitEmpty, Always, TestOutputInt ( + [["blockdev_getsz"; "/dev/sda"]], 1024000)], + "get total size of device in 512-byte sectors", + "\ +This returns the size of the device in units of 512-byte sectors +(even if the sectorsize isn't 512 bytes ... weird). - | LGPLv2 -> - pr "%s This library is free software; you can redistribute it and/or\n" c; - pr "%s modify it under the terms of the GNU Lesser General Public\n" c; - pr "%s License as published by the Free Software Foundation; either\n" c; - pr "%s version 2 of the License, or (at your option) any later version.\n" c; - pr "%s\n" c; - pr "%s This library is distributed in the hope that it will be useful,\n" c; - pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c; - pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\n" c; - pr "%s Lesser General Public License for more details.\n" c; - pr "%s\n" c; - pr "%s You should have received a copy of the GNU Lesser General Public\n" c; - pr "%s License along with this library; if not, write to the Free Software\n" c; - pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c; - ); - (match comment with - | CStyle -> pr " */\n" - | HashStyle -> () - | OCamlStyle -> pr " *)\n" - ); - pr "\n" +See also C for the real sector size of +the device, and C for the more +useful I. -(* Start of main code generation functions below this line. *) +This uses the L command."); -(* Generate the pod documentation for the C API. *) -let rec generate_actions_pod () = - List.iter ( - fun (shortname, style, _, flags, _, _, longdesc) -> - let name = "guestfs_" ^ shortname in - pr "=head2 %s\n\n" name; - pr " "; - generate_prototype ~extern:false ~handle:"handle" name style; - pr "\n\n"; - pr "%s\n\n" longdesc; - (match fst style with - | RErr -> - pr "This function returns 0 on success or -1 on error.\n\n" - | RInt _ -> - pr "On error this function returns -1.\n\n" - | RBool _ -> - pr "This function returns a C truth value on success or -1 on error.\n\n" - | RConstString _ -> - pr "This function returns a string or NULL on error. -The string is owned by the guest handle and must I be freed.\n\n" - | RString _ -> - pr "This function returns a string or NULL on error. -I.\n\n" - | RStringList _ -> - pr "This function returns a NULL-terminated array of strings -(like L), or NULL if there was an error. -I.\n\n" - | RIntBool _ -> - pr "This function returns a C. -I after use>.\n\n" - | RPVList _ -> - pr "This function returns a C. -I after use>.\n\n" - | RVGList _ -> - pr "This function returns a C. -I after use>.\n\n" - | RLVList _ -> - pr "This function returns a C. -I after use>.\n\n" - ); - if List.mem ProtocolLimitWarning flags then - pr "%s\n\n" protocol_limit_warning; - if List.mem DangerWillRobinson flags then - pr "%s\n\n" danger_will_robinson; - ) all_functions_sorted + ("blockdev_getsize64", (RInt64 "sizeinbytes", [Device "device"]), 63, [], + [InitEmpty, Always, TestOutputInt ( + [["blockdev_getsize64"; "/dev/sda"]], 524288000)], + "get total size of device in bytes", + "\ +This returns the size of the device in bytes. -and generate_structs_pod () = - (* LVM structs documentation. *) - List.iter ( - fun (typ, cols) -> - pr "=head2 guestfs_lvm_%s\n" typ; - pr "\n"; - pr " struct guestfs_lvm_%s {\n" typ; - List.iter ( - function - | name, `String -> pr " char *%s;\n" name - | name, `UUID -> - pr " /* The next field is NOT nul-terminated, be careful when printing it: */\n"; - pr " char %s[32];\n" name - | name, `Bytes -> pr " uint64_t %s;\n" name - | name, `Int -> pr " int64_t %s;\n" name - | name, `OptPercent -> - pr " /* The next field is [0..100] or -1 meaning 'not present': */\n"; - pr " float %s;\n" name - ) cols; - pr " \n"; - pr " struct guestfs_lvm_%s_list {\n" typ; - pr " uint32_t len; /* Number of elements in list. */\n"; - pr " struct guestfs_lvm_%s *val; /* Elements. */\n" typ; - pr " };\n"; - pr " \n"; - pr " void guestfs_free_lvm_%s_list (struct guestfs_free_lvm_%s_list *);\n" - typ typ; - pr "\n" - ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols] +See also C. -(* Generate the protocol (XDR) file, 'guestfs_protocol.x' and - * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'. - * - * We have to use an underscore instead of a dash because otherwise - * rpcgen generates incorrect code. - * - * This header is NOT exported to clients, but see also generate_structs_h. - *) -and generate_xdr () = - generate_header CStyle LGPLv2; +This uses the L command."); - (* This has to be defined to get around a limitation in Sun's rpcgen. *) - pr "typedef string str<>;\n"; - pr "\n"; + ("blockdev_flushbufs", (RErr, [Device "device"]), 64, [], + [InitEmpty, Always, TestRun + [["blockdev_flushbufs"; "/dev/sda"]]], + "flush device buffers", + "\ +This tells the kernel to flush internal buffers associated +with C. - (* LVM internal structures. *) - List.iter ( - function - | typ, cols -> - pr "struct guestfs_lvm_int_%s {\n" typ; - List.iter (function - | name, `String -> pr " string %s<>;\n" name - | name, `UUID -> pr " opaque %s[32];\n" name - | name, `Bytes -> pr " hyper %s;\n" name - | name, `Int -> pr " hyper %s;\n" name - | name, `OptPercent -> pr " float %s;\n" name - ) cols; - pr "};\n"; - pr "\n"; - pr "typedef struct guestfs_lvm_int_%s guestfs_lvm_int_%s_list<>;\n" typ typ; - pr "\n"; - ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols]; +This uses the L command."); - List.iter ( - fun (shortname, style, _, _, _, _, _) -> - let name = "guestfs_" ^ shortname in + ("blockdev_rereadpt", (RErr, [Device "device"]), 65, [], + [InitEmpty, Always, TestRun + [["blockdev_rereadpt"; "/dev/sda"]]], + "reread partition table", + "\ +Reread the partition table on C. - (match snd style with - | [] -> () - | args -> - pr "struct %s_args {\n" name; - List.iter ( - function - | String n -> pr " string %s<>;\n" n - | OptString n -> pr " str *%s;\n" n - | StringList n -> pr " str %s<>;\n" n - | Bool n -> pr " bool %s;\n" n - | Int n -> pr " int %s;\n" n - ) args; - pr "};\n\n" - ); - (match fst style with - | RErr -> () - | RInt n -> - pr "struct %s_ret {\n" name; - pr " int %s;\n" n; - pr "};\n\n" - | RBool n -> - pr "struct %s_ret {\n" name; - pr " bool %s;\n" n; - pr "};\n\n" - | RConstString _ -> - failwithf "RConstString cannot be returned from a daemon function" - | RString n -> - pr "struct %s_ret {\n" name; - pr " string %s<>;\n" n; - pr "};\n\n" - | RStringList n -> - pr "struct %s_ret {\n" name; - pr " str %s<>;\n" n; - pr "};\n\n" - | RIntBool (n,m) -> - pr "struct %s_ret {\n" name; - pr " int %s;\n" n; - pr " bool %s;\n" m; - pr "};\n\n" - | RPVList n -> - pr "struct %s_ret {\n" name; - pr " guestfs_lvm_int_pv_list %s;\n" n; - pr "};\n\n" - | RVGList n -> - pr "struct %s_ret {\n" name; - pr " guestfs_lvm_int_vg_list %s;\n" n; - pr "};\n\n" - | RLVList n -> - pr "struct %s_ret {\n" name; - pr " guestfs_lvm_int_lv_list %s;\n" n; - pr "};\n\n" - ); - ) daemon_functions; +This uses the L command."); - (* Table of procedure numbers. *) - pr "enum guestfs_procedure {\n"; - List.iter ( - fun (shortname, _, proc_nr, _, _, _, _) -> - pr " GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr - ) daemon_functions; - pr " GUESTFS_PROC_dummy\n"; (* so we don't have a "hanging comma" *) - pr "};\n"; - pr "\n"; + ("upload", (RErr, [FileIn "filename"; String "remotefilename"]), 66, [], + [InitBasicFS, Always, TestOutput ( + (* Pick a file from cwd which isn't likely to change. *) + [["upload"; "../COPYING.LIB"; "/COPYING.LIB"]; + ["checksum"; "md5"; "/COPYING.LIB"]], + Digest.to_hex (Digest.file "COPYING.LIB"))], + "upload a file from the local machine", + "\ +Upload local file C to C on the +filesystem. + +C can also be a named pipe. + +See also C."); + + ("download", (RErr, [String "remotefilename"; FileOut "filename"]), 67, [], + [InitBasicFS, Always, TestOutput ( + (* Pick a file from cwd which isn't likely to change. *) + [["upload"; "../COPYING.LIB"; "/COPYING.LIB"]; + ["download"; "/COPYING.LIB"; "testdownload.tmp"]; + ["upload"; "testdownload.tmp"; "/upload"]; + ["checksum"; "md5"; "/upload"]], + Digest.to_hex (Digest.file "COPYING.LIB"))], + "download a file to the local machine", + "\ +Download file C and save it as C +on the local machine. + +C can also be a named pipe. + +See also C, C."); + + ("checksum", (RString "checksum", [String "csumtype"; String "path"]), 68, [], + [InitSquashFS, Always, TestOutput ( + [["checksum"; "crc"; "/known-3"]], "2891671662"); + InitSquashFS, Always, TestLastFail ( + [["checksum"; "crc"; "/notexists"]]); + InitSquashFS, Always, TestOutput ( + [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c"); + InitSquashFS, Always, TestOutput ( + [["checksum"; "sha1"; "/known-3"]], "b7ebccc3ee418311091c3eda0a45b83c0a770f15"); + InitSquashFS, Always, TestOutput ( + [["checksum"; "sha224"; "/known-3"]], "d2cd1774b28f3659c14116be0a6dc2bb5c4b350ce9cd5defac707741"); + InitSquashFS, Always, TestOutput ( + [["checksum"; "sha256"; "/known-3"]], "75bb71b90cd20cb13f86d2bea8dad63ac7194e7517c3b52b8d06ff52d3487d30"); + InitSquashFS, Always, TestOutput ( + [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640"); + InitSquashFS, Always, TestOutput ( + [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6")], + "compute MD5, SHAx or CRC checksum of file", + "\ +This call computes the MD5, SHAx or CRC checksum of the +file named C. - (* Having to choose a maximum message size is annoying for several - * reasons (it limits what we can do in the API), but it (a) makes - * the protocol a lot simpler, and (b) provides a bound on the size - * of the daemon which operates in limited memory space. For large - * file transfers you should use FTP. - *) - pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024); - pr "\n"; +The type of checksum to compute is given by the C +parameter which must have one of the following values: - (* Message header, etc. *) - pr "\ -const GUESTFS_PROGRAM = 0x2000F5F5; -const GUESTFS_PROTOCOL_VERSION = 1; +=over 4 -enum guestfs_message_direction { - GUESTFS_DIRECTION_CALL = 0, /* client -> daemon */ - GUESTFS_DIRECTION_REPLY = 1 /* daemon -> client */ -}; +=item C -enum guestfs_message_status { - GUESTFS_STATUS_OK = 0, - GUESTFS_STATUS_ERROR = 1 -}; +Compute the cyclic redundancy check (CRC) specified by POSIX +for the C command. -const GUESTFS_ERROR_LEN = 256; +=item C -struct guestfs_message_error { - string error; /* error message */ -}; +Compute the MD5 hash (using the C program). -struct guestfs_message_header { - unsigned prog; /* GUESTFS_PROGRAM */ - unsigned vers; /* GUESTFS_PROTOCOL_VERSION */ - guestfs_procedure proc; /* GUESTFS_PROC_x */ - guestfs_message_direction direction; - unsigned serial; /* message serial number */ - guestfs_message_status status; -}; -" +=item C -(* Generate the guestfs-structs.h file. *) -and generate_structs_h () = - generate_header CStyle LGPLv2; +Compute the SHA1 hash (using the C program). - (* This is a public exported header file containing various - * structures. The structures are carefully written to have - * exactly the same in-memory format as the XDR structures that - * we use on the wire to the daemon. The reason for creating - * copies of these structures here is just so we don't have to - * export the whole of guestfs_protocol.h (which includes much - * unrelated and XDR-dependent stuff that we don't want to be - * public, or required by clients). - * - * To reiterate, we will pass these structures to and from the - * client with a simple assignment or memcpy, so the format - * must be identical to what rpcgen / the RFC defines. - *) +=item C - (* guestfs_int_bool structure. *) - pr "struct guestfs_int_bool {\n"; - pr " int32_t i;\n"; - pr " int32_t b;\n"; - pr "};\n"; - pr "\n"; +Compute the SHA224 hash (using the C program). - (* LVM public structures. *) - List.iter ( - function - | typ, cols -> - pr "struct guestfs_lvm_%s {\n" typ; - List.iter ( - function - | name, `String -> pr " char *%s;\n" name - | name, `UUID -> pr " char %s[32]; /* this is NOT nul-terminated, be careful when printing */\n" name - | name, `Bytes -> pr " uint64_t %s;\n" name - | name, `Int -> pr " int64_t %s;\n" name - | name, `OptPercent -> pr " float %s; /* [0..100] or -1 */\n" name - ) cols; - pr "};\n"; - pr "\n"; - pr "struct guestfs_lvm_%s_list {\n" typ; - pr " uint32_t len;\n"; - pr " struct guestfs_lvm_%s *val;\n" typ; - pr "};\n"; - pr "\n" - ) ["pv", pv_cols; "vg", vg_cols; "lv", lv_cols] +=item C -(* Generate the guestfs-actions.h file. *) -and generate_actions_h () = - generate_header CStyle LGPLv2; - List.iter ( - fun (shortname, style, _, _, _, _, _) -> - let name = "guestfs_" ^ shortname in - generate_prototype ~single_line:true ~newline:true ~handle:"handle" - name style - ) all_functions +Compute the SHA256 hash (using the C program). -(* Generate the client-side dispatch stubs. *) -and generate_client_actions () = - generate_header CStyle LGPLv2; +=item C - (* Client-side stubs for each function. *) - List.iter ( - fun (shortname, style, _, _, _, _, _) -> - let name = "guestfs_" ^ shortname in +Compute the SHA384 hash (using the C program). - (* Generate the return value struct. *) - pr "struct %s_rv {\n" shortname; - pr " int cb_done; /* flag to indicate callback was called */\n"; - pr " struct guestfs_message_header hdr;\n"; - pr " struct guestfs_message_error err;\n"; - (match fst style with - | RErr -> () - | RConstString _ -> - failwithf "RConstString cannot be returned from a daemon function" - | RInt _ - | RBool _ | RString _ | RStringList _ - | RIntBool _ - | RPVList _ | RVGList _ | RLVList _ -> - pr " struct %s_ret ret;\n" name - ); - pr "};\n\n"; +=item C - (* Generate the callback function. *) - pr "static void %s_cb (guestfs_h *g, void *data, XDR *xdr)\n" shortname; - pr "{\n"; - pr " struct %s_rv *rv = (struct %s_rv *) data;\n" shortname shortname; - pr "\n"; - pr " if (!xdr_guestfs_message_header (xdr, &rv->hdr)) {\n"; - pr " error (g, \"%s: failed to parse reply header\");\n" name; - pr " return;\n"; - pr " }\n"; - pr " if (rv->hdr.status == GUESTFS_STATUS_ERROR) {\n"; - pr " if (!xdr_guestfs_message_error (xdr, &rv->err)) {\n"; - pr " error (g, \"%s: failed to parse reply error\");\n" name; - pr " return;\n"; - pr " }\n"; - pr " goto done;\n"; - pr " }\n"; +Compute the SHA512 hash (using the C program). - (match fst style with - | RErr -> () - | RConstString _ -> - failwithf "RConstString cannot be returned from a daemon function" - | RInt _ - | RBool _ | RString _ | RStringList _ - | RIntBool _ - | RPVList _ | RVGList _ | RLVList _ -> - pr " if (!xdr_%s_ret (xdr, &rv->ret)) {\n" name; - pr " error (g, \"%s: failed to parse reply\");\n" name; - pr " return;\n"; - pr " }\n"; - ); +=back - pr " done:\n"; - pr " rv->cb_done = 1;\n"; - pr " main_loop.main_loop_quit (g);\n"; - pr "}\n\n"; +The checksum is returned as a printable string."); - (* Generate the action stub. *) - generate_prototype ~extern:false ~semicolon:false ~newline:true - ~handle:"g" name style; + ("tar_in", (RErr, [FileIn "tarfile"; String "directory"]), 69, [], + [InitBasicFS, Always, TestOutput ( + [["tar_in"; "../images/helloworld.tar"; "/"]; + ["cat"; "/hello"]], "hello\n")], + "unpack tarfile to directory", + "\ +This command uploads and unpacks local file C (an +I tar file) into C. - let error_code = - match fst style with - | RErr | RInt _ | RBool _ -> "-1" - | RConstString _ -> - failwithf "RConstString cannot be returned from a daemon function" - | RString _ | RStringList _ | RIntBool _ - | RPVList _ | RVGList _ | RLVList _ -> - "NULL" in +To upload a compressed tarball, use C."); - pr "{\n"; + ("tar_out", (RErr, [String "directory"; FileOut "tarfile"]), 70, [], + [], + "pack directory into tarfile", + "\ +This command packs the contents of C and downloads +it to local file C. - (match snd style with - | [] -> () - | _ -> pr " struct %s_args args;\n" name - ); +To download a compressed tarball, use C."); - pr " struct %s_rv rv;\n" shortname; - pr " int serial;\n"; - pr "\n"; - pr " if (g->state != READY) {\n"; - pr " error (g, \"%s called from the wrong state, %%d != READY\",\n" - name; - pr " g->state);\n"; - pr " return %s;\n" error_code; - pr " }\n"; - pr "\n"; - pr " memset (&rv, 0, sizeof rv);\n"; - pr "\n"; + ("tgz_in", (RErr, [FileIn "tarball"; String "directory"]), 71, [], + [InitBasicFS, Always, TestOutput ( + [["tgz_in"; "../images/helloworld.tar.gz"; "/"]; + ["cat"; "/hello"]], "hello\n")], + "unpack compressed tarball to directory", + "\ +This command uploads and unpacks local file C (a +I tar file) into C. - (match snd style with - | [] -> - pr " serial = dispatch (g, GUESTFS_PROC_%s, NULL, NULL);\n" - (String.uppercase shortname) - | args -> - List.iter ( - function - | String n -> - pr " args.%s = (char *) %s;\n" n n - | OptString n -> - pr " args.%s = %s ? (char **) &%s : NULL;\n" n n n - | StringList n -> - pr " args.%s.%s_val = (char **) %s;\n" n n n; - pr " for (args.%s.%s_len = 0; %s[args.%s.%s_len]; args.%s.%s_len++) ;\n" n n n n n n n; - | Bool n -> - pr " args.%s = %s;\n" n n - | Int n -> - pr " args.%s = %s;\n" n n - ) args; - pr " serial = dispatch (g, GUESTFS_PROC_%s,\n" - (String.uppercase shortname); - pr " (xdrproc_t) xdr_%s_args, (char *) &args);\n" - name; - ); - pr " if (serial == -1)\n"; - pr " return %s;\n" error_code; - pr "\n"; +To upload an uncompressed tarball, use C."); - pr " rv.cb_done = 0;\n"; - pr " g->reply_cb_internal = %s_cb;\n" shortname; - pr " g->reply_cb_internal_data = &rv;\n"; - pr " main_loop.main_loop_run (g);\n"; - pr " g->reply_cb_internal = NULL;\n"; - pr " g->reply_cb_internal_data = NULL;\n"; - pr " if (!rv.cb_done) {\n"; - pr " error (g, \"%s failed, see earlier error messages\");\n" name; - pr " return %s;\n" error_code; - pr " }\n"; - pr "\n"; + ("tgz_out", (RErr, [String "directory"; FileOut "tarball"]), 72, [], + [], + "pack directory into compressed tarball", + "\ +This command packs the contents of C and downloads +it to local file C. + +To download an uncompressed tarball, use C."); + + ("mount_ro", (RErr, [Device "device"; String "mountpoint"]), 73, [], + [InitBasicFS, Always, TestLastFail ( + [["umount"; "/"]; + ["mount_ro"; "/dev/sda1"; "/"]; + ["touch"; "/new"]]); + InitBasicFS, Always, TestOutput ( + [["write_file"; "/new"; "data"; "0"]; + ["umount"; "/"]; + ["mount_ro"; "/dev/sda1"; "/"]; + ["cat"; "/new"]], "data")], + "mount a guest disk, read-only", + "\ +This is the same as the C command, but it +mounts the filesystem with the read-only (I<-o ro>) flag."); - pr " if (check_reply_header (g, &rv.hdr, GUESTFS_PROC_%s, serial) == -1)\n" - (String.uppercase shortname); - pr " return %s;\n" error_code; - pr "\n"; + ("mount_options", (RErr, [String "options"; Device "device"; String "mountpoint"]), 74, [], + [], + "mount a guest disk with mount options", + "\ +This is the same as the C command, but it +allows you to set the mount options as for the +L I<-o> flag."); - pr " if (rv.hdr.status == GUESTFS_STATUS_ERROR) {\n"; - pr " error (g, \"%%s\", rv.err.error);\n"; - pr " return %s;\n" error_code; - pr " }\n"; - pr "\n"; + ("mount_vfs", (RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"]), 75, [], + [], + "mount a guest disk with mount options and vfstype", + "\ +This is the same as the C command, but it +allows you to set both the mount options and the vfstype +as for the L I<-o> and I<-t> flags."); - (match fst style with - | RErr -> pr " return 0;\n" - | RInt n - | RBool n -> pr " return rv.ret.%s;\n" n - | RConstString _ -> - failwithf "RConstString cannot be returned from a daemon function" - | RString n -> - pr " return rv.ret.%s; /* caller will free */\n" n - | RStringList n -> - pr " /* caller will free this, but we need to add a NULL entry */\n"; - pr " rv.ret.%s.%s_val =" n n; - pr " safe_realloc (g, rv.ret.%s.%s_val,\n" n n; - pr " sizeof (char *) * (rv.ret.%s.%s_len + 1));\n" - n n; - pr " rv.ret.%s.%s_val[rv.ret.%s.%s_len] = NULL;\n" n n n n; - pr " return rv.ret.%s.%s_val;\n" n n - | RIntBool _ -> - pr " /* caller with free this */\n"; - pr " return safe_memdup (g, &rv.ret, sizeof (rv.ret));\n" - | RPVList n -> - pr " /* caller will free this */\n"; - pr " return safe_memdup (g, &rv.ret.%s, sizeof (rv.ret.%s));\n" n n - | RVGList n -> - pr " /* caller will free this */\n"; - pr " return safe_memdup (g, &rv.ret.%s, sizeof (rv.ret.%s));\n" n n - | RLVList n -> - pr " /* caller will free this */\n"; - pr " return safe_memdup (g, &rv.ret.%s, sizeof (rv.ret.%s));\n" n n - ); + ("debug", (RString "result", [String "subcmd"; StringList "extraargs"]), 76, [], + [], + "debugging and internals", + "\ +The C command exposes some internals of +C (the guestfs daemon) that runs inside the +qemu subprocess. - pr "}\n\n" - ) daemon_functions +There is no comprehensive help for this command. You have +to look at the file C in the libguestfs source +to find out what you can do."); -(* Generate daemon/actions.h. *) -and generate_daemon_actions_h () = - generate_header CStyle GPLv2; + ("lvremove", (RErr, [Device "device"]), 77, [], + [InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ","]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["lvremove"; "/dev/VG/LV1"]; + ["lvs"]], ["/dev/VG/LV2"]); + InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ","]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["lvremove"; "/dev/VG"]; + ["lvs"]], []); + InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ","]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["lvremove"; "/dev/VG"]; + ["vgs"]], ["VG"])], + "remove an LVM logical volume", + "\ +Remove an LVM logical volume C, where C is +the path to the LV, such as C. - pr "#include \"../src/guestfs_protocol.h\"\n"; - pr "\n"; +You can also remove all LVs in a volume group by specifying +the VG name, C."); - List.iter ( - fun (name, style, _, _, _, _, _) -> - generate_prototype - ~single_line:true ~newline:true ~in_daemon:true ~prefix:"do_" - name style; - ) daemon_functions + ("vgremove", (RErr, [String "vgname"]), 78, [], + [InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ","]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["lvs"]], []); + InitEmpty, Always, TestOutputList ( + [["sfdiskM"; "/dev/sda"; ","]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["vgs"]], [])], + "remove an LVM volume group", + "\ +Remove an LVM volume group C, (for example C). -(* Generate the server-side stubs. *) -and generate_daemon_actions () = - generate_header CStyle GPLv2; +This also forcibly removes all logical volumes in the volume +group (if any)."); - pr "#define _GNU_SOURCE // for strchrnul\n"; - pr "\n"; - pr "#include \n"; - pr "#include \n"; - pr "#include \n"; - pr "#include \n"; - pr "#include \n"; - pr "#include \n"; - pr "#include \n"; - pr "\n"; - pr "#include \"daemon.h\"\n"; - pr "#include \"../src/guestfs_protocol.h\"\n"; - pr "#include \"actions.h\"\n"; - pr "\n"; + ("pvremove", (RErr, [Device "device"]), 79, [], + [InitEmpty, Always, TestOutputListOfDevices ( + [["sfdiskM"; "/dev/sda"; ","]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["pvremove"; "/dev/sda1"]; + ["lvs"]], []); + InitEmpty, Always, TestOutputListOfDevices ( + [["sfdiskM"; "/dev/sda"; ","]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["pvremove"; "/dev/sda1"]; + ["vgs"]], []); + InitEmpty, Always, TestOutputListOfDevices ( + [["sfdiskM"; "/dev/sda"; ","]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV1"; "VG"; "50"]; + ["lvcreate"; "LV2"; "VG"; "50"]; + ["vgremove"; "VG"]; + ["pvremove"; "/dev/sda1"]; + ["pvs"]], [])], + "remove an LVM physical volume", + "\ +This wipes a physical volume C so that LVM will no longer +recognise it. + +The implementation uses the C command which refuses to +wipe physical volumes that contain any volume groups, so you have +to remove those first."); + + ("set_e2label", (RErr, [Device "device"; String "label"]), 80, [], + [InitBasicFS, Always, TestOutput ( + [["set_e2label"; "/dev/sda1"; "testlabel"]; + ["get_e2label"; "/dev/sda1"]], "testlabel")], + "set the ext2/3/4 filesystem label", + "\ +This sets the ext2/3/4 filesystem label of the filesystem on +C to C