X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fgenerator.ml;h=ebfd45daaa4c8e389437365f4fefa8f9a131d464;hp=ef7d3d5ffae7efbc3025357f58fe78d7b4982c25;hb=4d5c22800214008b229e937dada2299de8353d9e;hpb=a61bccecfba1c9501910d28de24bac945e95001f diff --git a/src/generator.ml b/src/generator.ml index ef7d3d5..ec6123a 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -1,6 +1,6 @@ #!/usr/bin/env ocaml (* libguestfs - * Copyright (C) 2009 Red Hat Inc. + * Copyright (C) 2009-2010 Red Hat Inc. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -21,20 +21,31 @@ * all the daemon actions. * * To add a new action there are only two files you need to change, - * this one to describe the interface (see the big table below), and - * daemon/.c to write the implementation. + * this one to describe the interface (see the big table of + * 'daemon_functions' below), and daemon/.c to write the + * implementation. * - * 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. + * After editing this file, run it (./src/generator.ml) to regenerate + * all the output files. 'make' will rerun this automatically when + * necessary. 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. + * + * OCaml tips: + * (1) In emacs, install tuareg-mode to display and format OCaml code + * correctly. 'vim' comes with a good OCaml editing mode by default. + * (2) Read the resources at http://ocaml-tutorial.org/ *) #load "unix.cma";; #load "str.cma";; +#directory "+xml-light";; +#directory "+../pkg-lib/xml-light";; (* for GODI users *) +#load "xml-light.cma";; +open Unix open Printf type style = ret * args @@ -139,8 +150,10 @@ and argt = | 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) *) + | Int64 of string (* any 64 bit int *) (* 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. @@ -151,9 +164,8 @@ and argt = *) | 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. + * 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. @@ -162,28 +174,32 @@ and argt = * To return an arbitrary buffer, use RBufferOut. *) | BufferIn of string -*) type flags = | ProtocolLimitWarning (* display warning about protocol size limits *) | DangerWillRobinson (* flags particularly dangerous commands *) | FishAlias of string (* provide an alias for this cmd in guestfish *) - | FishAction of string (* call this function in guestfish *) + | FishOutput of fish_output_t (* how to display output in guestfish *) | NotInFish (* do not export via guestfish *) | NotInDocs (* do not add this function to documentation *) | DeprecatedBy of string (* function is deprecated, use .. instead *) + | Optional of string (* function is part of an optional group *) + +and fish_output_t = + | FishOutputOctal (* for int return, print in octal *) + | FishOutputHexadecimal (* for int return, print in hex *) (* 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. @@ -293,6 +309,9 @@ and test_prereq = (* As for 'If' but the test runs _unless_ the code returns true. *) | Unless of string + (* Run the test only if 'string' is available in the daemon. *) + | IfAvailable of string + (* Some initial scenarios for testing. *) and test_init = (* Do nothing, block devices could contain random stuff including @@ -325,10 +344,10 @@ and test_init = *) | InitBasicFSonLVM - (* /dev/sdd (the squashfs, see images/ directory in source) + (* /dev/sdd (the ISO, see images/ directory in source) * is mounted on / *) - | InitSquashFS + | InitISOFS (* Sequence of commands for testing. *) and seq = cmd list @@ -344,13 +363,13 @@ and cmd = string list (* Generate a random UUID (used in tests). *) let uuidgen () = - let chan = Unix.open_process_in "uuidgen" in + let chan = open_process_in "uuidgen" in let uuid = input_line chan in - (match Unix.close_process_in chan with - | Unix.WEXITED 0 -> () - | Unix.WEXITED _ -> + (match close_process_in chan with + | WEXITED 0 -> () + | WEXITED _ -> failwith "uuidgen: process exited with non-zero status" - | Unix.WSIGNALED _ | Unix.WSTOPPED _ -> + | WSIGNALED _ | WSTOPPED _ -> failwith "uuidgen: process signalled or stopped by signal" ); uuid @@ -363,8 +382,10 @@ let test_all_args = [ StringList "strlist"; Bool "b"; Int "integer"; + Int64 "integer64"; FileIn "filein"; FileOut "fileout"; + BufferIn "bufferin"; ] let test_all_rets = [ @@ -427,7 +448,7 @@ You probably don't want to call this function.")] *) let non_daemon_functions = test_functions @ [ - ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"], + ("launch", (RErr, []), -1, [FishAlias "run"], [], "launch the qemu subprocess", "\ @@ -439,13 +460,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. -You should call this after C to wait for the launch -to complete."); +In versions of the API E 1.0.71 you had to call this function +just after calling C to wait for the launch +to complete. However this is no longer necessary because +C now does the waiting. + +If you see any calls to this function in code then you can just +remove them, unless you want to retain compatibility with older +versions of the API."); ("kill_subprocess", (RErr, []), -1, [], [], @@ -470,9 +496,15 @@ 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. +C is set at compile time by the configuration option +C<./configure --with-drive-if=...>. In the rare case where you +might need to change this at run time, use C +or C. + 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 @@ -486,10 +518,24 @@ This function adds a virtual CD-ROM disk image to the guest. This is equivalent to the qemu parameter C<-cdrom filename>. -Note that this call checks for the existence of C. This +Notes: + +=over 4 + +=item * + +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."); +the general C call instead. + +=item * + +If you just want to add an ISO file (often you use this as an +efficient way to transfer large files into the guest), then you +should probably use C instead. + +=back"); ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"], [], @@ -505,7 +551,14 @@ 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=...>. +C<-drive file=filename,snapshot=on,readonly=on,if=...>. + +C is set at compile time by the configuration option +C<./configure --with-drive-if=...>. In the rare case where you +might need to change this at run time, use C +or C. + +C is only added where qemu supports this option. Note that this call checks for the existence of C. This stops you from specifying other types of drive which are supported @@ -525,7 +578,7 @@ The first character of C string must be a C<-> (dash). C can be NULL."); - ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"], + ("set_qemu", (RErr, [OptString "qemu"]), -1, [FishAlias "qemu"], [], "set the qemu binary", "\ @@ -537,7 +590,15 @@ configure script. You can also override this by setting the C environment variable. -Setting C to C restores the default qemu binary."); +Setting C to C restores the default qemu binary. + +Note that you should call this function as early as possible +after creating the handle. This is because some pre-launch +operations depend on testing qemu features (by running C). +If the qemu binary changes, we don't retest features, and +so you might see inconsistent results. Using the environment +variable C is safest of all since that picks +the qemu binary at the same time as the handle is created."); ("get_qemu", (RConstString "qemu", []), -1, [], [InitNone, Always, TestRun ( @@ -549,7 +610,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 "searchpath"]), -1, [FishAlias "path"], + ("set_path", (RErr, [OptString "searchpath"]), -1, [FishAlias "path"], [], "set the search path", "\ @@ -679,34 +740,6 @@ 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"]; @@ -764,8 +797,9 @@ 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). +number. From C code you can use dynamic linker functions +to find out if this symbol exists (if it doesn't, then +it's an earlier version). The call returns a structure with four elements. The first three (C, C and C) are numbers and @@ -776,8 +810,13 @@ used for distro-specific information. To construct the original version string: C<$major.$minor.$release$extra> +See also: L. + I Don't use this call to test for availability -of features. Distro backports makes this unreliable."); +of features. In enterprise distributions we backport +features from later versions into earlier versions, +making this an unreliable way to test for features. +Use C instead."); ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"], [InitNone, Always, TestOutputTrue ( @@ -804,6 +843,97 @@ 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."); + + ("set_recovery_proc", (RErr, [Bool "recoveryproc"]), -1, [FishAlias "recovery-proc"], + [InitNone, Always, TestOutputTrue ( + [["set_recovery_proc"; "true"]; + ["get_recovery_proc"]])], + "enable or disable the recovery process", + "\ +If this is called with the parameter C then +C does not create a recovery process. The +purpose of the recovery process is to stop runaway qemu +processes in the case where the main program aborts abruptly. + +This only has any effect if called before C, +and the default is true. + +About the only time when you would want to disable this is +if the main process will fork itself into the background +(\"daemonize\" itself). In this case the recovery process +thinks that the main program has disappeared and so kills +qemu, which is not very helpful."); + + ("get_recovery_proc", (RBool "recoveryproc", []), -1, [], + [], + "get recovery process enabled flag", + "\ +Return the recovery process enabled flag."); + + ("add_drive_with_if", (RErr, [String "filename"; String "iface"]), -1, [], + [], + "add a drive specifying the QEMU block emulation to use", + "\ +This is the same as C but it allows you +to specify the QEMU interface emulation to use at run time."); + + ("add_drive_ro_with_if", (RErr, [String "filename"; String "iface"]), -1, [], + [], + "add a drive read-only specifying the QEMU block emulation to use", + "\ +This is the same as C but it allows you +to specify the QEMU interface emulation to use at run time."); + ] (* daemon_functions are any functions which cause some action @@ -813,10 +943,10 @@ see L."); let daemon_functions = [ ("mount", (RErr, [Device "device"; String "mountpoint"]), 1, [], [InitEmpty, Always, TestOutput ( - [["sfdiskM"; "/dev/sda"; ","]; + [["part_disk"; "/dev/sda"; "mbr"]; ["mkfs"; "ext2"; "/dev/sda1"]; ["mount"; "/dev/sda1"; "/"]; - ["write_file"; "/new"; "new file contents"; "0"]; + ["write"; "/new"; "new file contents"]; ["cat"; "/new"]], "new file contents")], "mount a guest disk at a position in the filesystem", "\ @@ -834,8 +964,15 @@ exist. The mounted filesystem is writable, if we have sufficient permissions on the underlying device. -The filesystem options C and C are set with this -call, in order to improve reliability."); +B +When you use this call, the filesystem options C and C +are set implicitly. This was originally done because we thought it +would improve reliability, but it turns out that I<-o sync> has a +very large negative performance impact and negligible effect on +reliability. Therefore we recommend that you avoid using +C in any code that needs performance, and instead +use C (use an empty string for the first +parameter if you don't want any options)."); ("sync", (RErr, []), 2, [], [ InitEmpty, Always, TestRun [["sync"]]], @@ -858,7 +995,7 @@ update the timestamps on a file, or, if the file does not exist, to create a new zero-length file."); ("cat", (RString "content", [Pathname "path"]), 4, [ProtocolLimitWarning], - [InitSquashFS, Always, TestOutput ( + [InitISOFS, Always, TestOutput ( [["cat"; "/known-2"]], "abcdef\n")], "list the contents of a file", "\ @@ -920,7 +1057,7 @@ The full partition device names are returned, eg. C This does not return logical volumes. For that you will need to call C."); - ("pvs", (RStringList "physvols", []), 9, [], + ("pvs", (RStringList "physvols", []), 9, [Optional "lvm2"], [InitBasicFSonLVM, Always, TestOutputListOfDevices ( [["pvs"]], ["/dev/sda1"]); InitEmpty, Always, TestOutputListOfDevices ( @@ -939,7 +1076,7 @@ PVs (eg. C). See also C."); - ("vgs", (RStringList "volgroups", []), 10, [], + ("vgs", (RStringList "volgroups", []), 10, [Optional "lvm2"], [InitBasicFSonLVM, Always, TestOutputList ( [["vgs"]], ["VG"]); InitEmpty, Always, TestOutputList ( @@ -960,7 +1097,7 @@ detected (eg. C). See also C."); - ("lvs", (RStringList "logvols", []), 11, [], + ("lvs", (RStringList "logvols", []), 11, [Optional "lvm2"], [InitBasicFSonLVM, Always, TestOutputList ( [["lvs"]], ["/dev/VG/LV"]); InitEmpty, Always, TestOutputList ( @@ -984,21 +1121,21 @@ This returns a list of the logical volume device names See also C."); - ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [], + ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [Optional "lvm2"], [], (* 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", (RStructList ("volgroups", "lvm_vg"), []), 13, [], + ("vgs_full", (RStructList ("volgroups", "lvm_vg"), []), 13, [Optional "lvm2"], [], (* 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", (RStructList ("logvols", "lvm_lv"), []), 14, [], + ("lvs_full", (RStructList ("logvols", "lvm_lv"), []), 14, [Optional "lvm2"], [], (* XXX how to test? *) "list the LVM logical volumes (LVs)", "\ @@ -1006,9 +1143,9 @@ List all the logical volumes detected. This is the equivalent of the L command. The \"full\" version includes all fields."); ("read_lines", (RStringList "lines", [Pathname "path"]), 15, [], - [InitSquashFS, Always, TestOutputList ( + [InitISOFS, Always, TestOutputList ( [["read_lines"; "/known-4"]], ["abc"; "def"; "ghi"]); - InitSquashFS, Always, TestOutputList ( + InitISOFS, Always, TestOutputList ( [["read_lines"; "/empty"]], [])], "read file as lines", "\ @@ -1022,7 +1159,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, [Pathname "root"; Int "flags"]), 16, [], + ("aug_init", (RErr, [Pathname "root"; Int "flags"]), 16, [Optional "augeas"], [], (* XXX Augeas code needs tests. *) "create a new Augeas handle", "\ @@ -1073,7 +1210,7 @@ To close the handle, you can call C. To find out more about Augeas, see L."); - ("aug_close", (RErr, []), 26, [], + ("aug_close", (RErr, []), 26, [Optional "augeas"], [], (* XXX Augeas code needs tests. *) "close the current Augeas handle", "\ @@ -1082,7 +1219,7 @@ used by it. After calling this, you have to call C again before you can use any other Augeas functions."); - ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [], + ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [Optional "augeas"], [], (* XXX Augeas code needs tests. *) "define an Augeas variable", "\ @@ -1093,7 +1230,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", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"]), 18, [], + ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"]), 18, [Optional "augeas"], [], (* XXX Augeas code needs tests. *) "define an Augeas node", "\ @@ -1108,20 +1245,25 @@ 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 "augpath"]), 19, [], + ("aug_get", (RString "val", [String "augpath"]), 19, [Optional "augeas"], [], (* 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 "augpath"; String "val"]), 20, [], + ("aug_set", (RErr, [String "augpath"; String "val"]), 20, [Optional "augeas"], [], (* XXX Augeas code needs tests. *) "set Augeas path to value", "\ -Set the value associated with C to C."); +Set the value associated with C to C. + +In the Augeas API, it is possible to clear a node by setting +the value to NULL. Due to an oversight in the libguestfs API +you cannot do that with this call. Instead you must use the +C call."); - ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"]), 21, [], + ("aug_insert", (RErr, [String "augpath"; String "label"; Bool "before"]), 21, [Optional "augeas"], [], (* XXX Augeas code needs tests. *) "insert a sibling Augeas node", "\ @@ -1133,7 +1275,7 @@ C must match exactly one existing node in the tree, and C