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
25 (* "RErr" as a return value means an int used as a simple error
26 * indication, ie. 0 or -1.
30 (* "RInt" as a return value means an int which is -1 for error
31 * or any value >= 0 on success. Only use this for smallish
32 * positive ints (0 <= i < 2^30).
36 (* "RInt64" is the same as RInt, but is guaranteed to be able
37 * to return a full 64 bit value, _except_ that -1 means error
38 * (so -1 cannot be a valid, non-error return value).
42 (* "RBool" is a bool return value which can be true/false or
47 (* "RConstString" is a string that refers to a constant value.
48 * The return value must NOT be NULL (since NULL indicates
51 * Try to avoid using this. In particular you cannot use this
52 * for values returned from the daemon, because there is no
53 * thread-safe way to return them in the C API.
55 | RConstString of string
57 (* "RConstOptString" is an even more broken version of
58 * "RConstString". The returned string may be NULL and there
59 * is no way to return an error indication. Avoid using this!
61 | RConstOptString of string
63 (* "RString" is a returned string. It must NOT be NULL, since
64 * a NULL return indicates an error. The caller frees this.
68 (* "RStringList" is a list of strings. No string in the list
69 * can be NULL. The caller frees the strings and the array.
71 | RStringList of string
73 (* "RStruct" is a function which returns a single named structure
74 * or an error indication (in C, a struct, and in other languages
75 * with varying representations, but usually very efficient). See
76 * after the function list below for the structures.
78 | RStruct of string * string (* name of retval, name of struct *)
80 (* "RStructList" is a function which returns either a list/array
81 * of structures (could be zero-length), or an error indication.
83 | RStructList of string * string (* name of retval, name of struct *)
85 (* Key-value pairs of untyped strings. Turns into a hashtable or
86 * dictionary in languages which support it. DON'T use this as a
87 * general "bucket" for results. Prefer a stronger typed return
88 * value if one is available, or write a custom struct. Don't use
89 * this if the list could potentially be very long, since it is
90 * inefficient. Keys should be unique. NULLs are not permitted.
92 | RHashtable of string
94 (* "RBufferOut" is handled almost exactly like RString, but
95 * it allows the string to contain arbitrary 8 bit data including
96 * ASCII NUL. In the C API this causes an implicit extra parameter
97 * to be added of type <size_t *size_r>. The extra parameter
98 * returns the actual size of the return buffer in bytes.
100 * Other programming languages support strings with arbitrary 8 bit
103 * At the RPC layer we have to use the opaque<> type instead of
104 * string<>. Returned data is still limited to the max message
107 | RBufferOut of string
109 and args = argt list (* Function parameters, guestfs handle is implicit. *)
111 (* Note in future we should allow a "variable args" parameter as
112 * the final parameter, to allow commands like
113 * chmod mode file [file(s)...]
114 * This is not implemented yet, but many commands (such as chmod)
115 * are currently defined with the argument order keeping this future
116 * possibility in mind.
119 | String of string (* const char *name, cannot be NULL *)
120 | Device of string (* /dev device name, cannot be NULL *)
121 | Pathname of string (* file name, cannot be NULL *)
122 | Dev_or_Path of string (* /dev device name or Pathname, cannot be NULL *)
123 | OptString of string (* const char *name, may be NULL *)
124 | StringList of string(* list of strings (each string cannot be NULL) *)
125 | DeviceList of string(* list of Device names (each cannot be NULL) *)
126 | Bool of string (* boolean *)
127 | Int of string (* int (smallish ints, signed, <= 31 bits) *)
128 | Int64 of string (* any 64 bit int *)
129 (* These are treated as filenames (simple string parameters) in
130 * the C API and bindings. But in the RPC protocol, we transfer
131 * the actual file content up to or down from the daemon.
132 * FileIn: local machine -> daemon (in request)
133 * FileOut: daemon -> local machine (in reply)
134 * In guestfish (only), the special name "-" means read from
135 * stdin or write to stdout.
139 (* Opaque buffer which can contain arbitrary 8 bit data.
140 * In the C API, this is expressed as <const char *, size_t> pair.
141 * Most other languages have a string type which can contain
142 * ASCII NUL. We use whatever type is appropriate for each
144 * Buffers are limited by the total message size. To transfer
145 * large blocks of data, use FileIn/FileOut parameters instead.
146 * To return an arbitrary buffer, use RBufferOut.
149 (* Key material / passphrase. Eventually we should treat this
150 * as sensitive and mlock it into physical RAM. However this
151 * is highly complex because of all the places that XDR-encoded
152 * strings can end up. So currently the only difference from
153 * 'String' is the way that guestfish requests these parameters
159 | ProtocolLimitWarning (* display warning about protocol size limits *)
160 | DangerWillRobinson (* flags particularly dangerous commands *)
161 | FishAlias of string (* provide an alias for this cmd in guestfish *)
162 | FishOutput of fish_output_t (* how to display output in guestfish *)
163 | NotInFish (* do not export via guestfish *)
164 | NotInDocs (* do not add this function to documentation *)
165 | DeprecatedBy of string (* function is deprecated, use .. instead *)
166 | Optional of string (* function is part of an optional group *)
167 | Progress (* function can generate progress messages *)
170 | FishOutputOctal (* for int return, print in octal *)
171 | FishOutputHexadecimal (* for int return, print in hex *)
173 (* You can supply zero or as many tests as you want per API call.
175 * Note that the test environment has 3 block devices, of size 500MB,
176 * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
177 * a fourth ISO block device with some known files on it (/dev/sdd).
179 * Note for partitioning purposes, the 500MB device has 1015 cylinders.
180 * Number of cylinders was 63 for IDE emulated disks with precisely
181 * the same size. How exactly this is calculated is a mystery.
183 * The ISO block device (/dev/sdd) comes from images/test.iso.
185 * To be able to run the tests in a reasonable amount of time,
186 * the virtual machine and block devices are reused between tests.
187 * So don't try testing kill_subprocess :-x
189 * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
191 * Don't assume anything about the previous contents of the block
192 * devices. Use 'Init*' to create some initial scenarios.
194 * You can add a prerequisite clause to any individual test. This
195 * is a run-time check, which, if it fails, causes the test to be
196 * skipped. Useful if testing a command which might not work on
197 * all variations of libguestfs builds. A test that has prerequisite
198 * of 'Always' is run unconditionally.
200 * In addition, packagers can skip individual tests by setting the
201 * environment variables: eg:
202 * SKIP_TEST_<CMD>_<NUM>=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command)
203 * SKIP_TEST_<CMD>=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests)
205 type tests = (test_init * test_prereq * test) list
207 (* Run the command sequence and just expect nothing to fail. *)
210 (* Run the command sequence and expect the output of the final
211 * command to be the string.
213 | TestOutput of seq * string
215 (* Run the command sequence and expect the output of the final
216 * command to be the list of strings.
218 | TestOutputList of seq * string list
220 (* Run the command sequence and expect the output of the final
221 * command to be the list of block devices (could be either
222 * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
223 * character of each string).
225 | TestOutputListOfDevices of seq * string list
227 (* Run the command sequence and expect the output of the final
228 * command to be the integer.
230 | TestOutputInt of seq * int
232 (* Run the command sequence and expect the output of the final
233 * command to be <op> <int>, eg. ">=", "1".
235 | TestOutputIntOp of seq * string * int
237 (* Run the command sequence and expect the output of the final
238 * command to be a true value (!= 0 or != NULL).
240 | TestOutputTrue of seq
242 (* Run the command sequence and expect the output of the final
243 * command to be a false value (== 0 or == NULL, but not an error).
245 | TestOutputFalse of seq
247 (* Run the command sequence and expect the output of the final
248 * command to be a list of the given length (but don't care about
251 | TestOutputLength of seq * int
253 (* Run the command sequence and expect the output of the final
254 * command to be a buffer (RBufferOut), ie. string + size.
256 | TestOutputBuffer of seq * string
258 (* Run the command sequence and expect the output of the final
259 * command to be a structure.
261 | TestOutputStruct of seq * test_field_compare list
263 (* Run the command sequence and expect the output of the final
264 * command to be a string which is the hex MD5 of the content of
267 | TestOutputFileMD5 of seq * string
269 (* Run the command sequence and expect the output of the final
270 * command to be a string which is a block device name (we don't
271 * check the 5th character of the string, so "/dev/sda" == "/dev/vda").
273 | TestOutputDevice of seq * string
275 (* Run the command sequence and expect the final command (only)
278 | TestLastFail of seq
280 and test_field_compare =
281 | CompareWithInt of string * int
282 | CompareWithIntOp of string * string * int
283 | CompareWithString of string * string
284 | CompareFieldsIntEq of string * string
285 | CompareFieldsStrEq of string * string
287 (* Test prerequisites. *)
289 (* Test always runs. *)
292 (* Test is currently disabled - eg. it fails, or it tests some
293 * unimplemented feature.
297 (* 'string' is some C code (a function body) that should return
298 * true or false. The test will run if the code returns true.
302 (* As for 'If' but the test runs _unless_ the code returns true. *)
305 (* Run the test only if 'string' is available in the daemon. *)
306 | IfAvailable of string
308 (* Some initial scenarios for testing. *)
310 (* Do nothing, block devices could contain random stuff including
311 * LVM PVs, and some filesystems might be mounted. This is usually
316 (* Block devices are empty and no filesystems are mounted. *)
319 (* /dev/sda contains a single partition /dev/sda1, with random
320 * content. /dev/sdb and /dev/sdc may have random content.
325 (* /dev/sda contains a single partition /dev/sda1, which is formatted
326 * as ext2, empty [except for lost+found] and mounted on /.
327 * /dev/sdb and /dev/sdc may have random content.
333 * /dev/sda1 (is a PV):
334 * /dev/VG/LV (size 8MB):
335 * formatted as ext2, empty [except for lost+found], mounted on /
336 * /dev/sdb and /dev/sdc may have random content.
340 (* /dev/sdd (the ISO, see images/ directory in source)
345 (* Sequence of commands for testing. *)
347 and cmd = string list
349 (* Type of an action as declared in Generator_actions module. *)
350 type action = string * style * int * flags list * tests * string * string
352 (* Field types for structures. *)
354 | FChar (* C 'char' (really, a 7 bit byte). *)
355 | FString (* nul-terminated ASCII string, NOT NULL. *)
356 | FBuffer (* opaque buffer of bytes, (char *, int) pair *)
361 | FBytes (* Any int measure that counts bytes. *)
362 | FUUID (* 32 bytes long, NOT nul-terminated. *)
363 | FOptPercent (* [0..100], or -1 meaning "not present". *)
365 (* Used for testing language bindings. *)
367 | CallString of string
368 | CallOptString of string option
369 | CallStringList of string list
373 | CallBuffer of string