X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fgenerator.ml;h=6f77e4ba77e564dd0bc83bd04f5eb6e348a02c74;hp=a2b40b86133c7de789903013f38d46be4b4286c8;hb=dc0c80b3884c5fa2735b55b205e7406599bd77b0;hpb=924df6051655ad145eca78e50dff84166b7124f3 diff --git a/src/generator.ml b/src/generator.ml index a2b40b8..6f77e4b 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -24,12 +24,12 @@ * 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";; @@ -43,39 +43,62 @@ 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. 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 + (* "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. + * 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 @@ -84,16 +107,21 @@ and ret = * inefficient. Keys should be unique. NULLs are not permitted. *) | RHashtable of string -(* Not implemented: + (* "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 . Other programming languages - * support strings with arbitrary 8 bit data. At the RPC layer - * we have to use the opaque<> type instead of string<>. + * 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. *) @@ -106,8 +134,12 @@ 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 *) + | Pathname of string (* file name, cannot be NULL *) + | Dev_or_Path of string (* /dev device name or Pathname, cannot be NULL *) | OptString of string (* const char *name, may be NULL *) | StringList of string(* list of strings (each string cannot be NULL) *) + | DeviceList of string(* list of Device names (each 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 @@ -140,27 +172,19 @@ type flags = | FishAction of string (* call this function in guestfish *) | NotInFish (* do not export via guestfish *) | NotInDocs (* do not add this function to documentation *) - -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." + | 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), and - * a fourth squashfs block device with some known files on it (/dev/sdd). + * a fourth ISO 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. + * The ISO block device (/dev/sdd) comes from images/test.iso. * * To be able to run the tests in a reasonable amount of time, * the virtual machine and block devices are reused between tests. @@ -186,41 +210,60 @@ 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. *) @@ -228,6 +271,7 @@ and test = 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 @@ -236,14 +280,17 @@ and test_field_compare = 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 @@ -254,14 +301,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): @@ -270,6 +326,11 @@ and test_init = *) | InitBasicFSonLVM + (* /dev/sdd (the ISO, see images/ directory in source) + * is mounted on / + *) + | InitISOFS + (* Sequence of commands for testing. *) and seq = cmd list and cmd = string list @@ -282,6 +343,19 @@ and cmd = string list * Apart from that, long descriptions are just perldoc paragraphs. *) +(* Generate a random UUID (used in tests). *) +let uuidgen () = + let chan = Unix.open_process_in "uuidgen" in + let uuid = input_line chan in + (match Unix.close_process_in chan with + | Unix.WEXITED 0 -> () + | Unix.WEXITED _ -> + failwith "uuidgen: process exited with non-zero status" + | Unix.WSIGNALED _ | Unix.WSTOPPED _ -> + failwith "uuidgen: process signalled or stopped by signal" + ); + uuid + (* These test functions are used in the language binding tests. *) let test_all_args = [ @@ -300,6 +374,7 @@ let test_all_rets = [ "test0rint64", RInt64 "valout"; "test0rbool", RBool "valout"; "test0rconststring", RConstString "valout"; + "test0rconstoptstring", RConstOptString "valout"; "test0rstring", RString "valout"; "test0rstringlist", RStringList "valout"; "test0rstruct", RStruct ("valout", "lvm_pv"); @@ -323,9 +398,9 @@ You probably don't want to call this function."); List.map ( fun (name, ret) -> [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs], - [], - "internal test function - do not use", - "\ + [], + "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. @@ -334,9 +409,9 @@ 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", - "\ + [], + "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. @@ -365,13 +440,18 @@ You should call this after configuring the handle ("wait_ready", (RErr, []), -1, [NotInFish], [], - "wait until the qemu subprocess launches", + "wait until the qemu subprocess launches (no op)", "\ -Internally libguestfs is implemented by running a virtual machine -using L. +This function is a no op. + +In versions of the API E 1.0.71 you had to call this function +just after calling C to wait for the launch +to complete. However this is no longer necessary because +C now does the waiting. -You should call this after C to wait for the launch -to complete."); +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."); ("kill_subprocess", (RErr, []), -1, [], [], @@ -396,6 +476,8 @@ image). 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 @@ -464,7 +546,8 @@ 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. @@ -472,7 +555,7 @@ 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_path", (RErr, [String "searchpath"]), -1, [FishAlias "path"], [], "set the search path", "\ @@ -484,7 +567,8 @@ C environment variable. 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. @@ -492,7 +576,7 @@ 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, [String "append"]), -1, [FishAlias "append"], + ("set_append", (RErr, [OptString "append"]), -1, [FishAlias "append"], [], "add options to kernel command line", "\ @@ -505,7 +589,11 @@ C environment variable. Setting C to C means I additional options are passed (libguestfs always adds a few of its own)."); - ("get_append", (RConstString "append", []), -1, [], + ("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", "\ @@ -527,7 +615,8 @@ 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."); @@ -548,7 +637,8 @@ C is defined and set to C<1>."); 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 @@ -557,7 +647,8 @@ This returns true iff this handle is ready to accept commands 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 @@ -566,7 +657,8 @@ This returns true iff this handle is being configured 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 @@ -575,7 +667,8 @@ This returns true iff this handle is launching the subprocess 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 @@ -592,36 +685,10 @@ 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 @@ -636,7 +703,8 @@ 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 @@ -650,7 +718,8 @@ 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 @@ -659,7 +728,7 @@ qemu subprocess, then this will return an error. This is an internal call used for debugging and testing."); ("version", (RStruct ("version", "version"), []), -1, [], - [InitBasicFS, Always, TestOutputStruct ( + [InitNone, Always, TestOutputStruct ( [["version"]], [CompareWithInt ("major", 1)])], "get the library version number", "\ @@ -688,6 +757,82 @@ 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."); + + ("set_trace", (RErr, [Bool "trace"]), -1, [FishAlias "trace"], + [InitNone, Always, TestOutputFalse ( + [["set_trace"; "false"]; + ["get_trace"]])], + "enable or disable command traces", + "\ +If the command trace flag is set to 1, then commands are +printed on stdout before they are executed in a format +which is very similar to the one used by guestfish. In +other words, you can run a program with this enabled, and +you will get out a script which you can feed to guestfish +to perform the same set of actions. + +If you want to trace C API calls into libguestfs (and +other libraries) then possibly a better way is to use +the external ltrace(1) command. + +Command traces are disabled unless the environment variable +C is defined and set to C<1>."); + + ("get_trace", (RBool "trace", []), -1, [], + [], + "get command trace enabled flag", + "\ +Return the command trace flag."); + + ("set_direct", (RErr, [Bool "direct"]), -1, [FishAlias "direct"], + [InitNone, Always, TestOutputFalse ( + [["set_direct"; "false"]; + ["get_direct"]])], + "enable or disable direct appliance mode", + "\ +If the direct appliance mode flag is enabled, then stdin and +stdout are passed directly through to the appliance once it +is launched. + +One consequence of this is that log messages aren't caught +by the library and handled by C, +but go straight to stdout. + +You probably don't want to use this unless you know what you +are doing. + +The default is disabled."); + + ("get_direct", (RBool "direct", []), -1, [], + [], + "get direct appliance mode flag", + "\ +Return the direct appliance mode flag."); + ] (* daemon_functions are any functions which cause some action @@ -695,7 +840,7 @@ of features. Distro backports makes this unreliable."); *) let daemon_functions = [ - ("mount", (RErr, [String "device"; String "mountpoint"]), 1, [], + ("mount", (RErr, [Device "device"; String "mountpoint"]), 1, [], [InitEmpty, Always, TestOutput ( [["sfdiskM"; "/dev/sda"; ","]; ["mkfs"; "ext2"; "/dev/sda1"]; @@ -731,7 +876,7 @@ underlying disk image. You should always call this if you have modified a disk image, before closing the handle."); - ("touch", (RErr, [String "path"]), 3, [], + ("touch", (RErr, [Pathname "path"]), 3, [], [InitBasicFS, Always, TestOutputTrue ( [["touch"; "/new"]; ["exists"; "/new"]])], @@ -741,23 +886,22 @@ Touch acts like the L command. It can be used to update the timestamps on a file, or, if the file does not exist, to create a new zero-length file."); - ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning], - [InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; "new file contents"; "0"]; - ["cat"; "/new"]], "new file contents")], + ("cat", (RString "content", [Pathname "path"]), 4, [ProtocolLimitWarning], + [InitISOFS, Always, TestOutput ( + [["cat"; "/known-2"]], "abcdef\n")], "list the contents of a file", "\ 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."); +as end of string). For those you need to use the C +or C functions which have a more complex interface."); - ("ll", (RString "listing", [String "directory"]), 5, [], + ("ll", (RString "listing", [Pathname "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, @@ -766,7 +910,7 @@ there is no cwd) in the format of 'ls -la'. This command is mostly useful for interactive sessions. It is I intended that you try to parse the output string."); - ("ls", (RStringList "listing", [String "directory"]), 6, [], + ("ls", (RStringList "listing", [Pathname "directory"]), 6, [], [InitBasicFS, Always, TestOutputList ( [["touch"; "/new"]; ["touch"; "/newer"]; @@ -890,13 +1034,11 @@ of the L command. The \"full\" version includes all fields."); 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, Always, TestOutputList ( - [["write_file"; "/new"; "line1\r\nline2\nline3"; "0"]; - ["read_lines"; "/new"]], ["line1"; "line2"; "line3"]); - InitBasicFS, Always, TestOutputList ( - [["write_file"; "/new"; ""; "0"]; - ["read_lines"; "/new"]], [])], + ("read_lines", (RStringList "lines", [Pathname "path"]), 15, [], + [InitISOFS, Always, TestOutputList ( + [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]); + InitISOFS, Always, TestOutputList ( + [["read_lines"; "/empty"]], [])], "read file as lines", "\ Return the contents of the file named C. @@ -909,7 +1051,7 @@ Note that this function cannot correctly handle binary files as end of line). For those you need to use the C function which has a more complex interface."); - ("aug_init", (RErr, [String "root"; Int "flags"]), 16, [], + ("aug_init", (RErr, [Pathname "root"; Int "flags"]), 16, [], [], (* XXX Augeas code needs tests. *) "create a new Augeas handle", "\ @@ -995,20 +1137,20 @@ On success this returns a pair containing the number of nodes in the nodeset, and a boolean flag if a node was created."); - ("aug_get", (RString "val", [String "path"]), 19, [], + ("aug_get", (RString "val", [String "augpath"]), 19, [], [], (* XXX Augeas code needs tests. *) "look up the value of an Augeas path", "\ Look up the value associated with C. If C matches exactly one node, the C is returned."); - ("aug_set", (RErr, [String "path"; String "val"]), 20, [], + ("aug_set", (RErr, [String "augpath"; String "val"]), 20, [], [], (* XXX Augeas code needs tests. *) "set Augeas path to value", "\ Set the value associated with C to C."); - ("aug_insert", (RErr, [String "path"; String "label"; Bool "before"]), 21, [], + ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"]), 21, [], [], (* XXX Augeas code needs tests. *) "insert a sibling Augeas node", "\ @@ -1020,7 +1162,7 @@ C must match exactly one existing node in the tree, and C