X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=generator%2Fgenerator_types.ml;h=50e960405000a16005d3b9cf3b68c1f3494a2cf6;hp=0ed6f7483e8d14917d32fdab48c86d8ed8885a60;hb=7739d7f471f9575828bd32489695d92dde005a9c;hpb=ff38fea645e69e8f4d84f2691dac3116d9bac1c4 diff --git a/generator/generator_types.ml b/generator/generator_types.ml index 0ed6f74..50e9604 100644 --- a/generator/generator_types.ml +++ b/generator/generator_types.ml @@ -1,5 +1,5 @@ (* libguestfs - * Copyright (C) 2009-2010 Red Hat Inc. + * Copyright (C) 2009-2011 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 @@ -20,7 +20,45 @@ (* Types used to describe the API. *) -type style = ret * args +type style = ret * args * args + (* The [style] is a tuple which describes the return value and + * arguments of a function. + * + * [ret] is the return value, one of the [R*] values below. + * + * The second element is the list of required arguments, a list of + * [argt]s from the list below, eg. [Bool], [String] etc. Each has + * a name so that for example [Int "foo"] corresponds in the C + * bindings to an [int foo] parameter. + * + * The third element is the list of optional arguments. These are + * mapped to optional arguments in the language binding, eg. in + * Perl to: + * $g->fn (required1, required2, opt1 => val, opt2 => val); + * As the name suggests these are optional, and the function can + * tell which optional parameters were supplied by the caller. + * + * Only [Bool], [Int], [Int64], [String] may currently appear in + * the optional argument list (we may permit more types in future). + * + * ABI and API considerations + * -------------------------- + * + * The return type and required arguments may not be changed after + * these have been published in a stable version of libguestfs, + * because doing so would break the ABI. + * + * If a published function has one or more optional arguments, + * then the call can be extended without breaking the ABI or API. + * This is in fact the only way to change an existing function. + * There are limitations on this: + * + * (1) you may _only_ add extra elements at the end of the list + * (2) you may _not_ rearrange or rename or remove existing elements + * (3) you may _not_ add optional arguments to a function which did + * not have any before (since this breaks the C ABI). + *) + and ret = (* "RErr" as a return value means an int used as a simple error * indication, ie. 0 or -1. @@ -108,14 +146,10 @@ and ret = and args = argt list (* Function parameters, guestfs handle is implicit. *) - (* Note in future we should allow a "variable args" parameter as - * the final parameter, to allow commands like - * chmod mode file [file(s)...] - * This is not implemented yet, but many commands (such as chmod) - * are currently defined with the argument order keeping this future - * possibility in mind. - *) and argt = + | Bool of string (* boolean *) + | Int of string (* int (smallish ints, signed, <= 31 bits) *) + | Int64 of string (* any 64 bit int *) | 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 *) @@ -123,19 +157,6 @@ and argt = | 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. - * 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 (* 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 @@ -154,6 +175,35 @@ and argt = * from the user. *) | Key of string + (* 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 + (* This specifies an opaque pointer that is passed through + * untouched. Only non-daemon functions are supported. + * + * Pointer ("foo *", "bar") translates to "foo *bar" in the + * C API. The pointer ("bar") cannot be NULL. + * + * This is less well supported in other language bindings: + * if the pointer type is known then we may be able to produce + * a suitable binding, otherwise this is translated into a 64 + * bit int. + * + * Functions with this parameter type are not supported at all + * in guestfish (the function must be declared "NotInFish" else + * you will get an error). Also the function cannot contain + * tests, although we should fix this in future. + *) + | Pointer of (string * string) + +type errcode = [ `CannotReturnError | `ErrorIsMinusOne | `ErrorIsNULL ] type flags = | ProtocolLimitWarning (* display warning about protocol size limits *) @@ -170,38 +220,7 @@ 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 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 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. - * So don't try testing kill_subprocess :-x - * - * 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) - *) +(* See guestfs(3)/EXTENDING LIBGUESTFS. *) type tests = (test_init * test_prereq * test) list and test = (* Run the command sequence and just expect nothing to fail. *) @@ -317,15 +336,16 @@ and test_init = | InitEmpty (* /dev/sda contains a single partition /dev/sda1, with random - * content. /dev/sdb and /dev/sdc may have random content. - * No LVM. + * 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. + * + * Note: for testing filesystem operations, it is quicker to use + * InitScratchFS *) | InitBasicFS @@ -333,7 +353,9 @@ and test_init = * /dev/sda1 (is a PV): * /dev/VG/LV (size 8MB): * formatted as ext2, empty [except for lost+found], mounted on / - * /dev/sdb and /dev/sdc may have random content. + * + * Note: only use this if you really need a freshly created filesystem + * on LVM. Normally you should use InitScratchFS instead. *) | InitBasicFSonLVM @@ -342,6 +364,16 @@ and test_init = *) | InitISOFS + (* /dev/sdb1 (write scratch disk) is mounted on /. The filesystem + * will be empty. + * + * Note that this filesystem is not recreated between tests, and + * could contain random files and directories from previous tests. + * Therefore it is recommended that you create uniquely named files + * and directories for your tests. + *) + | InitScratchFS + (* Sequence of commands for testing. *) and seq = cmd list and cmd = string list