2 * Copyright (C) 2009-2010 Red Hat Inc.
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 (* Please read generator/README first. *)
21 (* Types used to describe the API. *)
23 type style = ret * args * args
24 (* The [style] is a tuple which describes the return value and
25 * arguments of a function.
27 * [ret] is the return value, one of the [R*] values below.
29 * The second element is the list of required arguments, a list of
30 * [argt]s from the list below, eg. [Bool], [String] etc. Each has
31 * a name so that for example [Int "foo"] corresponds in the C
32 * bindings to an [int foo] parameter.
34 * The third element is the list of optional arguments. These are
35 * mapped to optional arguments in the language binding, eg. in
37 * $g->fn (required1, required2, opt1 => val, opt2 => val);
38 * As the name suggests these are optional, and the function can
39 * tell which optional parameters were supplied by the caller.
41 * Only [Bool], [Int], [Int64], [String] may currently appear in
42 * the optional argument list (we may permit more types in future).
44 * ABI and API considerations
45 * --------------------------
47 * The return type and required arguments may not be changed after
48 * these have been published in a stable version of libguestfs,
49 * because doing so would break the ABI.
51 * If a published function has one or more optional arguments,
52 * then the call can be extended without breaking the ABI or API.
53 * This is in fact the only way to change an existing function.
54 * There are limitations on this:
56 * (1) you may _only_ add extra elements at the end of the list
57 * (2) you may _not_ rearrange or rename or remove existing elements
58 * (3) you may _not_ add optional arguments to a function which did
59 * not have any before (since this breaks the C ABI).
63 (* "RErr" as a return value means an int used as a simple error
64 * indication, ie. 0 or -1.
68 (* "RInt" as a return value means an int which is -1 for error
69 * or any value >= 0 on success. Only use this for smallish
70 * positive ints (0 <= i < 2^30).
74 (* "RInt64" is the same as RInt, but is guaranteed to be able
75 * to return a full 64 bit value, _except_ that -1 means error
76 * (so -1 cannot be a valid, non-error return value).
80 (* "RBool" is a bool return value which can be true/false or
85 (* "RConstString" is a string that refers to a constant value.
86 * The return value must NOT be NULL (since NULL indicates
89 * Try to avoid using this. In particular you cannot use this
90 * for values returned from the daemon, because there is no
91 * thread-safe way to return them in the C API.
93 | RConstString of string
95 (* "RConstOptString" is an even more broken version of
96 * "RConstString". The returned string may be NULL and there
97 * is no way to return an error indication. Avoid using this!
99 | RConstOptString of string
101 (* "RString" is a returned string. It must NOT be NULL, since
102 * a NULL return indicates an error. The caller frees this.
106 (* "RStringList" is a list of strings. No string in the list
107 * can be NULL. The caller frees the strings and the array.
109 | RStringList of string
111 (* "RStruct" is a function which returns a single named structure
112 * or an error indication (in C, a struct, and in other languages
113 * with varying representations, but usually very efficient). See
114 * after the function list below for the structures.
116 | RStruct of string * string (* name of retval, name of struct *)
118 (* "RStructList" is a function which returns either a list/array
119 * of structures (could be zero-length), or an error indication.
121 | RStructList of string * string (* name of retval, name of struct *)
123 (* Key-value pairs of untyped strings. Turns into a hashtable or
124 * dictionary in languages which support it. DON'T use this as a
125 * general "bucket" for results. Prefer a stronger typed return
126 * value if one is available, or write a custom struct. Don't use
127 * this if the list could potentially be very long, since it is
128 * inefficient. Keys should be unique. NULLs are not permitted.
130 | RHashtable of string
132 (* "RBufferOut" is handled almost exactly like RString, but
133 * it allows the string to contain arbitrary 8 bit data including
134 * ASCII NUL. In the C API this causes an implicit extra parameter
135 * to be added of type <size_t *size_r>. The extra parameter
136 * returns the actual size of the return buffer in bytes.
138 * Other programming languages support strings with arbitrary 8 bit
141 * At the RPC layer we have to use the opaque<> type instead of
142 * string<>. Returned data is still limited to the max message
145 | RBufferOut of string
147 and args = argt list (* Function parameters, guestfs handle is implicit. *)
150 | Bool of string (* boolean *)
151 | Int of string (* int (smallish ints, signed, <= 31 bits) *)
152 | Int64 of string (* any 64 bit int *)
153 | String of string (* const char *name, cannot be NULL *)
154 | Device of string (* /dev device name, cannot be NULL *)
155 | Pathname of string (* file name, cannot be NULL *)
156 | Dev_or_Path of string (* /dev device name or Pathname, cannot be NULL *)
157 | OptString of string (* const char *name, may be NULL *)
158 | StringList of string(* list of strings (each string cannot be NULL) *)
159 | DeviceList of string(* list of Device names (each cannot be NULL) *)
160 (* Opaque buffer which can contain arbitrary 8 bit data.
161 * In the C API, this is expressed as <const char *, size_t> pair.
162 * Most other languages have a string type which can contain
163 * ASCII NUL. We use whatever type is appropriate for each
165 * Buffers are limited by the total message size. To transfer
166 * large blocks of data, use FileIn/FileOut parameters instead.
167 * To return an arbitrary buffer, use RBufferOut.
170 (* Key material / passphrase. Eventually we should treat this
171 * as sensitive and mlock it into physical RAM. However this
172 * is highly complex because of all the places that XDR-encoded
173 * strings can end up. So currently the only difference from
174 * 'String' is the way that guestfish requests these parameters
178 (* These are treated as filenames (simple string parameters) in
179 * the C API and bindings. But in the RPC protocol, we transfer
180 * the actual file content up to or down from the daemon.
181 * FileIn: local machine -> daemon (in request)
182 * FileOut: daemon -> local machine (in reply)
183 * In guestfish (only), the special name "-" means read from
184 * stdin or write to stdout.
190 | ProtocolLimitWarning (* display warning about protocol size limits *)
191 | DangerWillRobinson (* flags particularly dangerous commands *)
192 | FishAlias of string (* provide an alias for this cmd in guestfish *)
193 | FishOutput of fish_output_t (* how to display output in guestfish *)
194 | NotInFish (* do not export via guestfish *)
195 | NotInDocs (* do not add this function to documentation *)
196 | DeprecatedBy of string (* function is deprecated, use .. instead *)
197 | Optional of string (* function is part of an optional group *)
198 | Progress (* function can generate progress messages *)
201 | FishOutputOctal (* for int return, print in octal *)
202 | FishOutputHexadecimal (* for int return, print in hex *)
204 (* You can supply zero or as many tests as you want per API call.
206 * Note that the test environment has 3 block devices, of size 500MB,
207 * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
208 * a fourth ISO block device with some known files on it (/dev/sdd).
210 * Note for partitioning purposes, the 500MB device has 1015 cylinders.
211 * Number of cylinders was 63 for IDE emulated disks with precisely
212 * the same size. How exactly this is calculated is a mystery.
214 * The ISO block device (/dev/sdd) comes from images/test.iso.
216 * To be able to run the tests in a reasonable amount of time,
217 * the virtual machine and block devices are reused between tests.
218 * So don't try testing kill_subprocess :-x
220 * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
222 * Don't assume anything about the previous contents of the block
223 * devices. Use 'Init*' to create some initial scenarios.
225 * You can add a prerequisite clause to any individual test. This
226 * is a run-time check, which, if it fails, causes the test to be
227 * skipped. Useful if testing a command which might not work on
228 * all variations of libguestfs builds. A test that has prerequisite
229 * of 'Always' is run unconditionally.
231 * In addition, packagers can skip individual tests by setting the
232 * environment variables: eg:
233 * SKIP_TEST_<CMD>_<NUM>=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command)
234 * SKIP_TEST_<CMD>=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests)
236 type tests = (test_init * test_prereq * test) list
238 (* Run the command sequence and just expect nothing to fail. *)
241 (* Run the command sequence and expect the output of the final
242 * command to be the string.
244 | TestOutput of seq * string
246 (* Run the command sequence and expect the output of the final
247 * command to be the list of strings.
249 | TestOutputList of seq * string list
251 (* Run the command sequence and expect the output of the final
252 * command to be the list of block devices (could be either
253 * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
254 * character of each string).
256 | TestOutputListOfDevices of seq * string list
258 (* Run the command sequence and expect the output of the final
259 * command to be the integer.
261 | TestOutputInt of seq * int
263 (* Run the command sequence and expect the output of the final
264 * command to be <op> <int>, eg. ">=", "1".
266 | TestOutputIntOp of seq * string * int
268 (* Run the command sequence and expect the output of the final
269 * command to be a true value (!= 0 or != NULL).
271 | TestOutputTrue of seq
273 (* Run the command sequence and expect the output of the final
274 * command to be a false value (== 0 or == NULL, but not an error).
276 | TestOutputFalse of seq
278 (* Run the command sequence and expect the output of the final
279 * command to be a list of the given length (but don't care about
282 | TestOutputLength of seq * int
284 (* Run the command sequence and expect the output of the final
285 * command to be a buffer (RBufferOut), ie. string + size.
287 | TestOutputBuffer of seq * string
289 (* Run the command sequence and expect the output of the final
290 * command to be a structure.
292 | TestOutputStruct of seq * test_field_compare list
294 (* Run the command sequence and expect the output of the final
295 * command to be a string which is the hex MD5 of the content of
298 | TestOutputFileMD5 of seq * string
300 (* Run the command sequence and expect the output of the final
301 * command to be a string which is a block device name (we don't
302 * check the 5th character of the string, so "/dev/sda" == "/dev/vda").
304 | TestOutputDevice of seq * string
306 (* Run the command sequence and expect the final command (only)
309 | TestLastFail of seq
311 and test_field_compare =
312 | CompareWithInt of string * int
313 | CompareWithIntOp of string * string * int
314 | CompareWithString of string * string
315 | CompareFieldsIntEq of string * string
316 | CompareFieldsStrEq of string * string
318 (* Test prerequisites. *)
320 (* Test always runs. *)
323 (* Test is currently disabled - eg. it fails, or it tests some
324 * unimplemented feature.
328 (* 'string' is some C code (a function body) that should return
329 * true or false. The test will run if the code returns true.
333 (* As for 'If' but the test runs _unless_ the code returns true. *)
336 (* Run the test only if 'string' is available in the daemon. *)
337 | IfAvailable of string
339 (* Some initial scenarios for testing. *)
341 (* Do nothing, block devices could contain random stuff including
342 * LVM PVs, and some filesystems might be mounted. This is usually
347 (* Block devices are empty and no filesystems are mounted. *)
350 (* /dev/sda contains a single partition /dev/sda1, with random
351 * content. /dev/sdb and /dev/sdc may have random content.
356 (* /dev/sda contains a single partition /dev/sda1, which is formatted
357 * as ext2, empty [except for lost+found] and mounted on /.
358 * /dev/sdb and /dev/sdc may have random content.
364 * /dev/sda1 (is a PV):
365 * /dev/VG/LV (size 8MB):
366 * formatted as ext2, empty [except for lost+found], mounted on /
367 * /dev/sdb and /dev/sdc may have random content.
371 (* /dev/sdd (the ISO, see images/ directory in source)
376 (* Sequence of commands for testing. *)
378 and cmd = string list
380 (* Type of an action as declared in Generator_actions module. *)
381 type action = string * style * int * flags list * tests * string * string
383 (* Field types for structures. *)
385 | FChar (* C 'char' (really, a 7 bit byte). *)
386 | FString (* nul-terminated ASCII string, NOT NULL. *)
387 | FBuffer (* opaque buffer of bytes, (char *, int) pair *)
392 | FBytes (* Any int measure that counts bytes. *)
393 | FUUID (* 32 bytes long, NOT nul-terminated. *)
394 | FOptPercent (* [0..100], or -1 meaning "not present". *)
396 (* Used for testing language bindings. *)
398 | CallString of string
399 | CallOptString of string option
400 | CallStringList of string list
404 | CallBuffer of string