Add tests to many non-daemon functions.
[libguestfs.git] / src / generator.ml
1 #!/usr/bin/env ocaml
2 (* libguestfs
3  * Copyright (C) 2009 Red Hat Inc.
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 2 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18  *)
19
20 (* This script generates a large amount of code and documentation for
21  * all the daemon actions.
22  *
23  * To add a new action there are only two files you need to change,
24  * this one to describe the interface (see the big table below), and
25  * daemon/<somefile>.c to write the implementation.
26  *
27  * After editing this file, run it (./src/generator.ml) to regenerate
28  * all the output files.
29  *
30  * IMPORTANT: This script should NOT print any warnings.  If it prints
31  * warnings, you should treat them as errors.
32  * [Need to add -warn-error to ocaml command line]
33  *)
34
35 #load "unix.cma";;
36 #load "str.cma";;
37
38 open Printf
39
40 type style = ret * args
41 and ret =
42     (* "RErr" as a return value means an int used as a simple error
43      * indication, ie. 0 or -1.
44      *)
45   | RErr
46     (* "RInt" as a return value means an int which is -1 for error
47      * or any value >= 0 on success.  Only use this for smallish
48      * positive ints (0 <= i < 2^30).
49      *)
50   | RInt of string
51     (* "RInt64" is the same as RInt, but is guaranteed to be able
52      * to return a full 64 bit value, _except_ that -1 means error
53      * (so -1 cannot be a valid, non-error return value).
54      *)
55   | RInt64 of string
56     (* "RBool" is a bool return value which can be true/false or
57      * -1 for error.
58      *)
59   | RBool of string
60     (* "RConstString" is a string that refers to a constant value.
61      * Try to avoid using this.  In particular you cannot use this
62      * for values returned from the daemon, because there is no
63      * thread-safe way to return them in the C API.
64      *)
65   | RConstString of string
66     (* "RString" and "RStringList" are caller-frees. *)
67   | RString of string
68   | RStringList of string
69     (* "RStruct" is a function which returns a single named structure
70      * or an error indication (in C, a struct, and in other languages
71      * with varying representations, but usually very efficient).  See
72      * after the function list below for the structures. 
73      *)
74   | RStruct of string * string          (* name of retval, name of struct *)
75     (* "RStructList" is a function which returns either a list/array
76      * of structures (could be zero-length), or an error indication.
77      *)
78   | RStructList of string * string      (* name of retval, name of struct *)
79     (* Key-value pairs of untyped strings.  Turns into a hashtable or
80      * dictionary in languages which support it.  DON'T use this as a
81      * general "bucket" for results.  Prefer a stronger typed return
82      * value if one is available, or write a custom struct.  Don't use
83      * this if the list could potentially be very long, since it is
84      * inefficient.  Keys should be unique.  NULLs are not permitted.
85      *)
86   | RHashtable of string
87 (* Not implemented:
88     (* "RBufferOut" is handled almost exactly like RString, but
89      * it allows the string to contain arbitrary 8 bit data including
90      * ASCII NUL.  In the C API this causes an implicit extra parameter
91      * to be added of type <size_t *size_r>.  Other programming languages
92      * support strings with arbitrary 8 bit data.  At the RPC layer
93      * we have to use the opaque<> type instead of string<>.
94      *)
95   | RBufferOut of string
96 *)
97
98 and args = argt list    (* Function parameters, guestfs handle is implicit. *)
99
100     (* Note in future we should allow a "variable args" parameter as
101      * the final parameter, to allow commands like
102      *   chmod mode file [file(s)...]
103      * This is not implemented yet, but many commands (such as chmod)
104      * are currently defined with the argument order keeping this future
105      * possibility in mind.
106      *)
107 and argt =
108   | String of string    (* const char *name, cannot be NULL *)
109   | OptString of string (* const char *name, may be NULL *)
110   | StringList of string(* list of strings (each string cannot be NULL) *)
111   | Bool of string      (* boolean *)
112   | Int of string       (* int (smallish ints, signed, <= 31 bits) *)
113     (* These are treated as filenames (simple string parameters) in
114      * the C API and bindings.  But in the RPC protocol, we transfer
115      * the actual file content up to or down from the daemon.
116      * FileIn: local machine -> daemon (in request)
117      * FileOut: daemon -> local machine (in reply)
118      * In guestfish (only), the special name "-" means read from
119      * stdin or write to stdout.
120      *)
121   | FileIn of string
122   | FileOut of string
123 (* Not implemented:
124     (* Opaque buffer which can contain arbitrary 8 bit data.
125      * In the C API, this is expressed as <char *, int> pair.
126      * Most other languages have a string type which can contain
127      * ASCII NUL.  We use whatever type is appropriate for each
128      * language.
129      * Buffers are limited by the total message size.  To transfer
130      * large blocks of data, use FileIn/FileOut parameters instead.
131      * To return an arbitrary buffer, use RBufferOut.
132      *)
133   | BufferIn of string
134 *)
135
136 type flags =
137   | ProtocolLimitWarning  (* display warning about protocol size limits *)
138   | DangerWillRobinson    (* flags particularly dangerous commands *)
139   | FishAlias of string   (* provide an alias for this cmd in guestfish *)
140   | FishAction of string  (* call this function in guestfish *)
141   | NotInFish             (* do not export via guestfish *)
142   | NotInDocs             (* do not add this function to documentation *)
143
144 let protocol_limit_warning =
145   "Because of the message protocol, there is a transfer limit
146 of somewhere between 2MB and 4MB.  To transfer large files you should use
147 FTP."
148
149 let danger_will_robinson =
150   "B<This command is dangerous.  Without careful use you
151 can easily destroy all your data>."
152
153 (* You can supply zero or as many tests as you want per API call.
154  *
155  * Note that the test environment has 3 block devices, of size 500MB,
156  * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and
157  * a fourth squashfs block device with some known files on it (/dev/sdd).
158  *
159  * Note for partitioning purposes, the 500MB device has 1015 cylinders.
160  * Number of cylinders was 63 for IDE emulated disks with precisely
161  * the same size.  How exactly this is calculated is a mystery.
162  *
163  * The squashfs block device (/dev/sdd) comes from images/test.sqsh.
164  *
165  * To be able to run the tests in a reasonable amount of time,
166  * the virtual machine and block devices are reused between tests.
167  * So don't try testing kill_subprocess :-x
168  *
169  * Between each test we blockdev-setrw, umount-all, lvm-remove-all.
170  *
171  * Don't assume anything about the previous contents of the block
172  * devices.  Use 'Init*' to create some initial scenarios.
173  *
174  * You can add a prerequisite clause to any individual test.  This
175  * is a run-time check, which, if it fails, causes the test to be
176  * skipped.  Useful if testing a command which might not work on
177  * all variations of libguestfs builds.  A test that has prerequisite
178  * of 'Always' is run unconditionally.
179  *
180  * In addition, packagers can skip individual tests by setting the
181  * environment variables:     eg:
182  *   SKIP_TEST_<CMD>_<NUM>=1  SKIP_TEST_COMMAND_3=1  (skips test #3 of command)
183  *   SKIP_TEST_<CMD>=1        SKIP_TEST_ZEROFREE=1   (skips all zerofree tests)
184  *)
185 type tests = (test_init * test_prereq * test) list
186 and test =
187     (* Run the command sequence and just expect nothing to fail. *)
188   | TestRun of seq
189     (* Run the command sequence and expect the output of the final
190      * command to be the string.
191      *)
192   | TestOutput of seq * string
193     (* Run the command sequence and expect the output of the final
194      * command to be the list of strings.
195      *)
196   | TestOutputList of seq * string list
197     (* Run the command sequence and expect the output of the final
198      * command to be the list of block devices (could be either
199      * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
200      * character of each string).
201      *)
202   | TestOutputListOfDevices of seq * string list
203     (* Run the command sequence and expect the output of the final
204      * command to be the integer.
205      *)
206   | TestOutputInt of seq * int
207     (* Run the command sequence and expect the output of the final
208      * command to be <op> <int>, eg. ">=", "1".
209      *)
210   | TestOutputIntOp of seq * string * int
211     (* Run the command sequence and expect the output of the final
212      * command to be a true value (!= 0 or != NULL).
213      *)
214   | TestOutputTrue of seq
215     (* Run the command sequence and expect the output of the final
216      * command to be a false value (== 0 or == NULL, but not an error).
217      *)
218   | TestOutputFalse of seq
219     (* Run the command sequence and expect the output of the final
220      * command to be a list of the given length (but don't care about
221      * content).
222      *)
223   | TestOutputLength of seq * int
224     (* Run the command sequence and expect the output of the final
225      * command to be a structure.
226      *)
227   | TestOutputStruct of seq * test_field_compare list
228     (* Run the command sequence and expect the final command (only)
229      * to fail.
230      *)
231   | TestLastFail of seq
232
233 and test_field_compare =
234   | CompareWithInt of string * int
235   | CompareWithIntOp of string * string * int
236   | CompareWithString of string * string
237   | CompareFieldsIntEq of string * string
238   | CompareFieldsStrEq of string * string
239
240 (* Test prerequisites. *)
241 and test_prereq =
242     (* Test always runs. *)
243   | Always
244     (* Test is currently disabled - eg. it fails, or it tests some
245      * unimplemented feature.
246      *)
247   | Disabled
248     (* 'string' is some C code (a function body) that should return
249      * true or false.  The test will run if the code returns true.
250      *)
251   | If of string
252     (* As for 'If' but the test runs _unless_ the code returns true. *)
253   | Unless of string
254
255 (* Some initial scenarios for testing. *)
256 and test_init =
257     (* Do nothing, block devices could contain random stuff including
258      * LVM PVs, and some filesystems might be mounted.  This is usually
259      * a bad idea.
260      *)
261   | InitNone
262     (* Block devices are empty and no filesystems are mounted. *)
263   | InitEmpty
264     (* /dev/sda contains a single partition /dev/sda1, which is formatted
265      * as ext2, empty [except for lost+found] and mounted on /.
266      * /dev/sdb and /dev/sdc may have random content.
267      * No LVM.
268      *)
269   | InitBasicFS
270     (* /dev/sda:
271      *   /dev/sda1 (is a PV):
272      *     /dev/VG/LV (size 8MB):
273      *       formatted as ext2, empty [except for lost+found], mounted on /
274      * /dev/sdb and /dev/sdc may have random content.
275      *)
276   | InitBasicFSonLVM
277
278 (* Sequence of commands for testing. *)
279 and seq = cmd list
280 and cmd = string list
281
282 (* Note about long descriptions: When referring to another
283  * action, use the format C<guestfs_other> (ie. the full name of
284  * the C function).  This will be replaced as appropriate in other
285  * language bindings.
286  *
287  * Apart from that, long descriptions are just perldoc paragraphs.
288  *)
289
290 (* These test functions are used in the language binding tests. *)
291
292 let test_all_args = [
293   String "str";
294   OptString "optstr";
295   StringList "strlist";
296   Bool "b";
297   Int "integer";
298   FileIn "filein";
299   FileOut "fileout";
300 ]
301
302 let test_all_rets = [
303   (* except for RErr, which is tested thoroughly elsewhere *)
304   "test0rint",         RInt "valout";
305   "test0rint64",       RInt64 "valout";
306   "test0rbool",        RBool "valout";
307   "test0rconststring", RConstString "valout";
308   "test0rstring",      RString "valout";
309   "test0rstringlist",  RStringList "valout";
310   "test0rstruct",      RStruct ("valout", "lvm_pv");
311   "test0rstructlist",  RStructList ("valout", "lvm_pv");
312   "test0rhashtable",   RHashtable "valout";
313 ]
314
315 let test_functions = [
316   ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs],
317    [],
318    "internal test function - do not use",
319    "\
320 This is an internal test function which is used to test whether
321 the automatically generated bindings can handle every possible
322 parameter type correctly.
323
324 It echos the contents of each parameter to stdout.
325
326 You probably don't want to call this function.");
327 ] @ List.flatten (
328   List.map (
329     fun (name, ret) ->
330       [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs],
331         [],
332         "internal test function - do not use",
333         "\
334 This is an internal test function which is used to test whether
335 the automatically generated bindings can handle every possible
336 return type correctly.
337
338 It converts string C<val> to the return type.
339
340 You probably don't want to call this function.");
341        (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs],
342         [],
343         "internal test function - do not use",
344         "\
345 This is an internal test function which is used to test whether
346 the automatically generated bindings can handle every possible
347 return type correctly.
348
349 This function always returns an error.
350
351 You probably don't want to call this function.")]
352   ) test_all_rets
353 )
354
355 (* non_daemon_functions are any functions which don't get processed
356  * in the daemon, eg. functions for setting and getting local
357  * configuration values.
358  *)
359
360 let non_daemon_functions = test_functions @ [
361   ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"],
362    [],
363    "launch the qemu subprocess",
364    "\
365 Internally libguestfs is implemented by running a virtual machine
366 using L<qemu(1)>.
367
368 You should call this after configuring the handle
369 (eg. adding drives) but before performing any actions.");
370
371   ("wait_ready", (RErr, []), -1, [NotInFish],
372    [],
373    "wait until the qemu subprocess launches",
374    "\
375 Internally libguestfs is implemented by running a virtual machine
376 using L<qemu(1)>.
377
378 You should call this after C<guestfs_launch> to wait for the launch
379 to complete.");
380
381   ("kill_subprocess", (RErr, []), -1, [],
382    [],
383    "kill the qemu subprocess",
384    "\
385 This kills the qemu subprocess.  You should never need to call this.");
386
387   ("add_drive", (RErr, [String "filename"]), -1, [FishAlias "add"],
388    [],
389    "add an image to examine or modify",
390    "\
391 This function adds a virtual machine disk image C<filename> to the
392 guest.  The first time you call this function, the disk appears as IDE
393 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
394 so on.
395
396 You don't necessarily need to be root when using libguestfs.  However
397 you obviously do need sufficient permissions to access the filename
398 for whatever operations you want to perform (ie. read access if you
399 just want to read the image or write access if you want to modify the
400 image).
401
402 This is equivalent to the qemu parameter
403 C<-drive file=filename,cache=off,if=...>.
404
405 Note that this call checks for the existence of C<filename>.  This
406 stops you from specifying other types of drive which are supported
407 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
408 the general C<guestfs_config> call instead.");
409
410   ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"],
411    [],
412    "add a CD-ROM disk image to examine",
413    "\
414 This function adds a virtual CD-ROM disk image to the guest.
415
416 This is equivalent to the qemu parameter C<-cdrom filename>.
417
418 Note that this call checks for the existence of C<filename>.  This
419 stops you from specifying other types of drive which are supported
420 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
421 the general C<guestfs_config> call instead.");
422
423   ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"],
424    [],
425    "add a drive in snapshot mode (read-only)",
426    "\
427 This adds a drive in snapshot mode, making it effectively
428 read-only.
429
430 Note that writes to the device are allowed, and will be seen for
431 the duration of the guestfs handle, but they are written
432 to a temporary file which is discarded as soon as the guestfs
433 handle is closed.  We don't currently have any method to enable
434 changes to be committed, although qemu can support this.
435
436 This is equivalent to the qemu parameter
437 C<-drive file=filename,snapshot=on,if=...>.
438
439 Note that this call checks for the existence of C<filename>.  This
440 stops you from specifying other types of drive which are supported
441 by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
442 the general C<guestfs_config> call instead.");
443
444   ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [],
445    [],
446    "add qemu parameters",
447    "\
448 This can be used to add arbitrary qemu command line parameters
449 of the form C<-param value>.  Actually it's not quite arbitrary - we
450 prevent you from setting some parameters which would interfere with
451 parameters that we use.
452
453 The first character of C<param> string must be a C<-> (dash).
454
455 C<value> can be NULL.");
456
457   ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"],
458    [],
459    "set the qemu binary",
460    "\
461 Set the qemu binary that we will use.
462
463 The default is chosen when the library was compiled by the
464 configure script.
465
466 You can also override this by setting the C<LIBGUESTFS_QEMU>
467 environment variable.
468
469 Setting C<qemu> to C<NULL> restores the default qemu binary.");
470
471   ("get_qemu", (RConstString "qemu", []), -1, [],
472    [InitNone, Always, TestRun (
473       [["get_qemu"]])],
474    "get the qemu binary",
475    "\
476 Return the current qemu binary.
477
478 This is always non-NULL.  If it wasn't set already, then this will
479 return the default qemu binary name.");
480
481   ("set_path", (RErr, [String "path"]), -1, [FishAlias "path"],
482    [],
483    "set the search path",
484    "\
485 Set the path that libguestfs searches for kernel and initrd.img.
486
487 The default is C<$libdir/guestfs> unless overridden by setting
488 C<LIBGUESTFS_PATH> environment variable.
489
490 Setting C<path> to C<NULL> restores the default path.");
491
492   ("get_path", (RConstString "path", []), -1, [],
493    [InitNone, Always, TestRun (
494       [["get_path"]])],
495    "get the search path",
496    "\
497 Return the current search path.
498
499 This is always non-NULL.  If it wasn't set already, then this will
500 return the default path.");
501
502   ("set_append", (RErr, [String "append"]), -1, [FishAlias "append"],
503    [],
504    "add options to kernel command line",
505    "\
506 This function is used to add additional options to the
507 guest kernel command line.
508
509 The default is C<NULL> unless overridden by setting
510 C<LIBGUESTFS_APPEND> environment variable.
511
512 Setting C<append> to C<NULL> means I<no> additional options
513 are passed (libguestfs always adds a few of its own).");
514
515   ("get_append", (RConstString "append", []), -1, [],
516    (* This cannot be tested with the current framework.  The
517     * function can return NULL in normal operations, which the
518     * test framework interprets as an error.
519     *)
520    [],
521    "get the additional kernel options",
522    "\
523 Return the additional kernel options which are added to the
524 guest kernel command line.
525
526 If C<NULL> then no options are added.");
527
528   ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"],
529    [],
530    "set autosync mode",
531    "\
532 If C<autosync> is true, this enables autosync.  Libguestfs will make a
533 best effort attempt to run C<guestfs_umount_all> followed by
534 C<guestfs_sync> when the handle is closed
535 (also if the program exits without closing handles).
536
537 This is disabled by default (except in guestfish where it is
538 enabled by default).");
539
540   ("get_autosync", (RBool "autosync", []), -1, [],
541    [InitNone, Always, TestRun (
542       [["get_autosync"]])],
543    "get autosync mode",
544    "\
545 Get the autosync flag.");
546
547   ("set_verbose", (RErr, [Bool "verbose"]), -1, [FishAlias "verbose"],
548    [],
549    "set verbose mode",
550    "\
551 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
552
553 Verbose messages are disabled unless the environment variable
554 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.");
555
556   ("get_verbose", (RBool "verbose", []), -1, [],
557    [],
558    "get verbose mode",
559    "\
560 This returns the verbose messages flag.");
561
562   ("is_ready", (RBool "ready", []), -1, [],
563    [InitNone, Always, TestOutputTrue (
564       [["is_ready"]])],
565    "is ready to accept commands",
566    "\
567 This returns true iff this handle is ready to accept commands
568 (in the C<READY> state).
569
570 For more information on states, see L<guestfs(3)>.");
571
572   ("is_config", (RBool "config", []), -1, [],
573    [InitNone, Always, TestOutputFalse (
574       [["is_config"]])],
575    "is in configuration state",
576    "\
577 This returns true iff this handle is being configured
578 (in the C<CONFIG> state).
579
580 For more information on states, see L<guestfs(3)>.");
581
582   ("is_launching", (RBool "launching", []), -1, [],
583    [InitNone, Always, TestOutputFalse (
584       [["is_launching"]])],
585    "is launching subprocess",
586    "\
587 This returns true iff this handle is launching the subprocess
588 (in the C<LAUNCHING> state).
589
590 For more information on states, see L<guestfs(3)>.");
591
592   ("is_busy", (RBool "busy", []), -1, [],
593    [InitNone, Always, TestOutputFalse (
594       [["is_busy"]])],
595    "is busy processing a command",
596    "\
597 This returns true iff this handle is busy processing a command
598 (in the C<BUSY> state).
599
600 For more information on states, see L<guestfs(3)>.");
601
602   ("get_state", (RInt "state", []), -1, [],
603    [],
604    "get the current state",
605    "\
606 This returns the current state as an opaque integer.  This is
607 only useful for printing debug and internal error messages.
608
609 For more information on states, see L<guestfs(3)>.");
610
611   ("set_busy", (RErr, []), -1, [NotInFish],
612    [],
613    "set state to busy",
614    "\
615 This sets the state to C<BUSY>.  This is only used when implementing
616 actions using the low-level API.
617
618 For more information on states, see L<guestfs(3)>.");
619
620   ("set_ready", (RErr, []), -1, [NotInFish],
621    [],
622    "set state to ready",
623    "\
624 This sets the state to C<READY>.  This is only used when implementing
625 actions using the low-level API.
626
627 For more information on states, see L<guestfs(3)>.");
628
629   ("end_busy", (RErr, []), -1, [NotInFish],
630    [],
631    "leave the busy state",
632    "\
633 This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
634 state as is.  This is only used when implementing
635 actions using the low-level API.
636
637 For more information on states, see L<guestfs(3)>.");
638
639   ("set_memsize", (RErr, [Int "memsize"]), -1, [FishAlias "memsize"],
640    [InitNone, Always, TestOutputInt (
641       [["set_memsize"; "500"];
642        ["get_memsize"]], 500)],
643    "set memory allocated to the qemu subprocess",
644    "\
645 This sets the memory size in megabytes allocated to the
646 qemu subprocess.  This only has any effect if called before
647 C<guestfs_launch>.
648
649 You can also change this by setting the environment
650 variable C<LIBGUESTFS_MEMSIZE> before the handle is
651 created.
652
653 For more information on the architecture of libguestfs,
654 see L<guestfs(3)>.");
655
656   ("get_memsize", (RInt "memsize", []), -1, [],
657    [InitNone, Always, TestOutputIntOp (
658       [["get_memsize"]], ">=", 256)],
659    "get memory allocated to the qemu subprocess",
660    "\
661 This gets the memory size in megabytes allocated to the
662 qemu subprocess.
663
664 If C<guestfs_set_memsize> was not called
665 on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
666 then this returns the compiled-in default value for memsize.
667
668 For more information on the architecture of libguestfs,
669 see L<guestfs(3)>.");
670
671   ("get_pid", (RInt "pid", []), -1, [FishAlias "pid"],
672    [InitNone, Always, TestOutputIntOp (
673       [["get_pid"]], ">=", 1)],
674    "get PID of qemu subprocess",
675    "\
676 Return the process ID of the qemu subprocess.  If there is no
677 qemu subprocess, then this will return an error.
678
679 This is an internal call used for debugging and testing.");
680
681   ("version", (RStruct ("version", "version"), []), -1, [],
682    [InitNone, Always, TestOutputStruct (
683       [["version"]], [CompareWithInt ("major", 1)])],
684    "get the library version number",
685    "\
686 Return the libguestfs version number that the program is linked
687 against.
688
689 Note that because of dynamic linking this is not necessarily
690 the version of libguestfs that you compiled against.  You can
691 compile the program, and then at runtime dynamically link
692 against a completely different C<libguestfs.so> library.
693
694 This call was added in version C<1.0.58>.  In previous
695 versions of libguestfs there was no way to get the version
696 number.  From C code you can use ELF weak linking tricks to find out if
697 this symbol exists (if it doesn't, then it's an earlier version).
698
699 The call returns a structure with four elements.  The first
700 three (C<major>, C<minor> and C<release>) are numbers and
701 correspond to the usual version triplet.  The fourth element
702 (C<extra>) is a string and is normally empty, but may be
703 used for distro-specific information.
704
705 To construct the original version string:
706 C<$major.$minor.$release$extra>
707
708 I<Note:> Don't use this call to test for availability
709 of features.  Distro backports makes this unreliable.");
710
711 ]
712
713 (* daemon_functions are any functions which cause some action
714  * to take place in the daemon.
715  *)
716
717 let daemon_functions = [
718   ("mount", (RErr, [String "device"; String "mountpoint"]), 1, [],
719    [InitEmpty, Always, TestOutput (
720       [["sfdiskM"; "/dev/sda"; ","];
721        ["mkfs"; "ext2"; "/dev/sda1"];
722        ["mount"; "/dev/sda1"; "/"];
723        ["write_file"; "/new"; "new file contents"; "0"];
724        ["cat"; "/new"]], "new file contents")],
725    "mount a guest disk at a position in the filesystem",
726    "\
727 Mount a guest disk at a position in the filesystem.  Block devices
728 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
729 the guest.  If those block devices contain partitions, they will have
730 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
731 names can be used.
732
733 The rules are the same as for L<mount(2)>:  A filesystem must
734 first be mounted on C</> before others can be mounted.  Other
735 filesystems can only be mounted on directories which already
736 exist.
737
738 The mounted filesystem is writable, if we have sufficient permissions
739 on the underlying device.
740
741 The filesystem options C<sync> and C<noatime> are set with this
742 call, in order to improve reliability.");
743
744   ("sync", (RErr, []), 2, [],
745    [ InitEmpty, Always, TestRun [["sync"]]],
746    "sync disks, writes are flushed through to the disk image",
747    "\
748 This syncs the disk, so that any writes are flushed through to the
749 underlying disk image.
750
751 You should always call this if you have modified a disk image, before
752 closing the handle.");
753
754   ("touch", (RErr, [String "path"]), 3, [],
755    [InitBasicFS, Always, TestOutputTrue (
756       [["touch"; "/new"];
757        ["exists"; "/new"]])],
758    "update file timestamps or create a new file",
759    "\
760 Touch acts like the L<touch(1)> command.  It can be used to
761 update the timestamps on a file, or, if the file does not exist,
762 to create a new zero-length file.");
763
764   ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning],
765    [InitBasicFS, Always, TestOutput (
766       [["write_file"; "/new"; "new file contents"; "0"];
767        ["cat"; "/new"]], "new file contents")],
768    "list the contents of a file",
769    "\
770 Return the contents of the file named C<path>.
771
772 Note that this function cannot correctly handle binary files
773 (specifically, files containing C<\\0> character which is treated
774 as end of string).  For those you need to use the C<guestfs_download>
775 function which has a more complex interface.");
776
777   ("ll", (RString "listing", [String "directory"]), 5, [],
778    [], (* XXX Tricky to test because it depends on the exact format
779         * of the 'ls -l' command, which changes between F10 and F11.
780         *)
781    "list the files in a directory (long format)",
782    "\
783 List the files in C<directory> (relative to the root directory,
784 there is no cwd) in the format of 'ls -la'.
785
786 This command is mostly useful for interactive sessions.  It
787 is I<not> intended that you try to parse the output string.");
788
789   ("ls", (RStringList "listing", [String "directory"]), 6, [],
790    [InitBasicFS, Always, TestOutputList (
791       [["touch"; "/new"];
792        ["touch"; "/newer"];
793        ["touch"; "/newest"];
794        ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])],
795    "list the files in a directory",
796    "\
797 List the files in C<directory> (relative to the root directory,
798 there is no cwd).  The '.' and '..' entries are not returned, but
799 hidden files are shown.
800
801 This command is mostly useful for interactive sessions.  Programs
802 should probably use C<guestfs_readdir> instead.");
803
804   ("list_devices", (RStringList "devices", []), 7, [],
805    [InitEmpty, Always, TestOutputListOfDevices (
806       [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])],
807    "list the block devices",
808    "\
809 List all the block devices.
810
811 The full block device names are returned, eg. C</dev/sda>");
812
813   ("list_partitions", (RStringList "partitions", []), 8, [],
814    [InitBasicFS, Always, TestOutputListOfDevices (
815       [["list_partitions"]], ["/dev/sda1"]);
816     InitEmpty, Always, TestOutputListOfDevices (
817       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
818        ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
819    "list the partitions",
820    "\
821 List all the partitions detected on all block devices.
822
823 The full partition device names are returned, eg. C</dev/sda1>
824
825 This does not return logical volumes.  For that you will need to
826 call C<guestfs_lvs>.");
827
828   ("pvs", (RStringList "physvols", []), 9, [],
829    [InitBasicFSonLVM, Always, TestOutputListOfDevices (
830       [["pvs"]], ["/dev/sda1"]);
831     InitEmpty, Always, TestOutputListOfDevices (
832       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
833        ["pvcreate"; "/dev/sda1"];
834        ["pvcreate"; "/dev/sda2"];
835        ["pvcreate"; "/dev/sda3"];
836        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
837    "list the LVM physical volumes (PVs)",
838    "\
839 List all the physical volumes detected.  This is the equivalent
840 of the L<pvs(8)> command.
841
842 This returns a list of just the device names that contain
843 PVs (eg. C</dev/sda2>).
844
845 See also C<guestfs_pvs_full>.");
846
847   ("vgs", (RStringList "volgroups", []), 10, [],
848    [InitBasicFSonLVM, Always, TestOutputList (
849       [["vgs"]], ["VG"]);
850     InitEmpty, Always, TestOutputList (
851       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
852        ["pvcreate"; "/dev/sda1"];
853        ["pvcreate"; "/dev/sda2"];
854        ["pvcreate"; "/dev/sda3"];
855        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
856        ["vgcreate"; "VG2"; "/dev/sda3"];
857        ["vgs"]], ["VG1"; "VG2"])],
858    "list the LVM volume groups (VGs)",
859    "\
860 List all the volumes groups detected.  This is the equivalent
861 of the L<vgs(8)> command.
862
863 This returns a list of just the volume group names that were
864 detected (eg. C<VolGroup00>).
865
866 See also C<guestfs_vgs_full>.");
867
868   ("lvs", (RStringList "logvols", []), 11, [],
869    [InitBasicFSonLVM, Always, TestOutputList (
870       [["lvs"]], ["/dev/VG/LV"]);
871     InitEmpty, Always, TestOutputList (
872       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
873        ["pvcreate"; "/dev/sda1"];
874        ["pvcreate"; "/dev/sda2"];
875        ["pvcreate"; "/dev/sda3"];
876        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
877        ["vgcreate"; "VG2"; "/dev/sda3"];
878        ["lvcreate"; "LV1"; "VG1"; "50"];
879        ["lvcreate"; "LV2"; "VG1"; "50"];
880        ["lvcreate"; "LV3"; "VG2"; "50"];
881        ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])],
882    "list the LVM logical volumes (LVs)",
883    "\
884 List all the logical volumes detected.  This is the equivalent
885 of the L<lvs(8)> command.
886
887 This returns a list of the logical volume device names
888 (eg. C</dev/VolGroup00/LogVol00>).
889
890 See also C<guestfs_lvs_full>.");
891
892   ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 12, [],
893    [], (* XXX how to test? *)
894    "list the LVM physical volumes (PVs)",
895    "\
896 List all the physical volumes detected.  This is the equivalent
897 of the L<pvs(8)> command.  The \"full\" version includes all fields.");
898
899   ("vgs_full", (RStructList ("volgroups", "lvm_vg"), []), 13, [],
900    [], (* XXX how to test? *)
901    "list the LVM volume groups (VGs)",
902    "\
903 List all the volumes groups detected.  This is the equivalent
904 of the L<vgs(8)> command.  The \"full\" version includes all fields.");
905
906   ("lvs_full", (RStructList ("logvols", "lvm_lv"), []), 14, [],
907    [], (* XXX how to test? *)
908    "list the LVM logical volumes (LVs)",
909    "\
910 List all the logical volumes detected.  This is the equivalent
911 of the L<lvs(8)> command.  The \"full\" version includes all fields.");
912
913   ("read_lines", (RStringList "lines", [String "path"]), 15, [],
914    [InitBasicFS, Always, TestOutputList (
915       [["write_file"; "/new"; "line1\r\nline2\nline3"; "0"];
916        ["read_lines"; "/new"]], ["line1"; "line2"; "line3"]);
917     InitBasicFS, Always, TestOutputList (
918       [["write_file"; "/new"; ""; "0"];
919        ["read_lines"; "/new"]], [])],
920    "read file as lines",
921    "\
922 Return the contents of the file named C<path>.
923
924 The file contents are returned as a list of lines.  Trailing
925 C<LF> and C<CRLF> character sequences are I<not> returned.
926
927 Note that this function cannot correctly handle binary files
928 (specifically, files containing C<\\0> character which is treated
929 as end of line).  For those you need to use the C<guestfs_read_file>
930 function which has a more complex interface.");
931
932   ("aug_init", (RErr, [String "root"; Int "flags"]), 16, [],
933    [], (* XXX Augeas code needs tests. *)
934    "create a new Augeas handle",
935    "\
936 Create a new Augeas handle for editing configuration files.
937 If there was any previous Augeas handle associated with this
938 guestfs session, then it is closed.
939
940 You must call this before using any other C<guestfs_aug_*>
941 commands.
942
943 C<root> is the filesystem root.  C<root> must not be NULL,
944 use C</> instead.
945
946 The flags are the same as the flags defined in
947 E<lt>augeas.hE<gt>, the logical I<or> of the following
948 integers:
949
950 =over 4
951
952 =item C<AUG_SAVE_BACKUP> = 1
953
954 Keep the original file with a C<.augsave> extension.
955
956 =item C<AUG_SAVE_NEWFILE> = 2
957
958 Save changes into a file with extension C<.augnew>, and
959 do not overwrite original.  Overrides C<AUG_SAVE_BACKUP>.
960
961 =item C<AUG_TYPE_CHECK> = 4
962
963 Typecheck lenses (can be expensive).
964
965 =item C<AUG_NO_STDINC> = 8
966
967 Do not use standard load path for modules.
968
969 =item C<AUG_SAVE_NOOP> = 16
970
971 Make save a no-op, just record what would have been changed.
972
973 =item C<AUG_NO_LOAD> = 32
974
975 Do not load the tree in C<guestfs_aug_init>.
976
977 =back
978
979 To close the handle, you can call C<guestfs_aug_close>.
980
981 To find out more about Augeas, see L<http://augeas.net/>.");
982
983   ("aug_close", (RErr, []), 26, [],
984    [], (* XXX Augeas code needs tests. *)
985    "close the current Augeas handle",
986    "\
987 Close the current Augeas handle and free up any resources
988 used by it.  After calling this, you have to call
989 C<guestfs_aug_init> again before you can use any other
990 Augeas functions.");
991
992   ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [],
993    [], (* XXX Augeas code needs tests. *)
994    "define an Augeas variable",
995    "\
996 Defines an Augeas variable C<name> whose value is the result
997 of evaluating C<expr>.  If C<expr> is NULL, then C<name> is
998 undefined.
999
1000 On success this returns the number of nodes in C<expr>, or
1001 C<0> if C<expr> evaluates to something which is not a nodeset.");
1002
1003   ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [String "name"; String "expr"; String "val"]), 18, [],
1004    [], (* XXX Augeas code needs tests. *)
1005    "define an Augeas node",
1006    "\
1007 Defines a variable C<name> whose value is the result of
1008 evaluating C<expr>.
1009
1010 If C<expr> evaluates to an empty nodeset, a node is created,
1011 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
1012 C<name> will be the nodeset containing that single node.
1013
1014 On success this returns a pair containing the
1015 number of nodes in the nodeset, and a boolean flag
1016 if a node was created.");
1017
1018   ("aug_get", (RString "val", [String "path"]), 19, [],
1019    [], (* XXX Augeas code needs tests. *)
1020    "look up the value of an Augeas path",
1021    "\
1022 Look up the value associated with C<path>.  If C<path>
1023 matches exactly one node, the C<value> is returned.");
1024
1025   ("aug_set", (RErr, [String "path"; String "val"]), 20, [],
1026    [], (* XXX Augeas code needs tests. *)
1027    "set Augeas path to value",
1028    "\
1029 Set the value associated with C<path> to C<value>.");
1030
1031   ("aug_insert", (RErr, [String "path"; String "label"; Bool "before"]), 21, [],
1032    [], (* XXX Augeas code needs tests. *)
1033    "insert a sibling Augeas node",
1034    "\
1035 Create a new sibling C<label> for C<path>, inserting it into
1036 the tree before or after C<path> (depending on the boolean
1037 flag C<before>).
1038
1039 C<path> must match exactly one existing node in the tree, and
1040 C<label> must be a label, ie. not contain C</>, C<*> or end
1041 with a bracketed index C<[N]>.");
1042
1043   ("aug_rm", (RInt "nrnodes", [String "path"]), 22, [],
1044    [], (* XXX Augeas code needs tests. *)
1045    "remove an Augeas path",
1046    "\
1047 Remove C<path> and all of its children.
1048
1049 On success this returns the number of entries which were removed.");
1050
1051   ("aug_mv", (RErr, [String "src"; String "dest"]), 23, [],
1052    [], (* XXX Augeas code needs tests. *)
1053    "move Augeas node",
1054    "\
1055 Move the node C<src> to C<dest>.  C<src> must match exactly
1056 one node.  C<dest> is overwritten if it exists.");
1057
1058   ("aug_match", (RStringList "matches", [String "path"]), 24, [],
1059    [], (* XXX Augeas code needs tests. *)
1060    "return Augeas nodes which match path",
1061    "\
1062 Returns a list of paths which match the path expression C<path>.
1063 The returned paths are sufficiently qualified so that they match
1064 exactly one node in the current tree.");
1065
1066   ("aug_save", (RErr, []), 25, [],
1067    [], (* XXX Augeas code needs tests. *)
1068    "write all pending Augeas changes to disk",
1069    "\
1070 This writes all pending changes to disk.
1071
1072 The flags which were passed to C<guestfs_aug_init> affect exactly
1073 how files are saved.");
1074
1075   ("aug_load", (RErr, []), 27, [],
1076    [], (* XXX Augeas code needs tests. *)
1077    "load files into the tree",
1078    "\
1079 Load files into the tree.
1080
1081 See C<aug_load> in the Augeas documentation for the full gory
1082 details.");
1083
1084   ("aug_ls", (RStringList "matches", [String "path"]), 28, [],
1085    [], (* XXX Augeas code needs tests. *)
1086    "list Augeas nodes under a path",
1087    "\
1088 This is just a shortcut for listing C<guestfs_aug_match>
1089 C<path/*> and sorting the resulting nodes into alphabetical order.");
1090
1091   ("rm", (RErr, [String "path"]), 29, [],
1092    [InitBasicFS, Always, TestRun
1093       [["touch"; "/new"];
1094        ["rm"; "/new"]];
1095     InitBasicFS, Always, TestLastFail
1096       [["rm"; "/new"]];
1097     InitBasicFS, Always, TestLastFail
1098       [["mkdir"; "/new"];
1099        ["rm"; "/new"]]],
1100    "remove a file",
1101    "\
1102 Remove the single file C<path>.");
1103
1104   ("rmdir", (RErr, [String "path"]), 30, [],
1105    [InitBasicFS, Always, TestRun
1106       [["mkdir"; "/new"];
1107        ["rmdir"; "/new"]];
1108     InitBasicFS, Always, TestLastFail
1109       [["rmdir"; "/new"]];
1110     InitBasicFS, Always, TestLastFail
1111       [["touch"; "/new"];
1112        ["rmdir"; "/new"]]],
1113    "remove a directory",
1114    "\
1115 Remove the single directory C<path>.");
1116
1117   ("rm_rf", (RErr, [String "path"]), 31, [],
1118    [InitBasicFS, Always, TestOutputFalse
1119       [["mkdir"; "/new"];
1120        ["mkdir"; "/new/foo"];
1121        ["touch"; "/new/foo/bar"];
1122        ["rm_rf"; "/new"];
1123        ["exists"; "/new"]]],
1124    "remove a file or directory recursively",
1125    "\
1126 Remove the file or directory C<path>, recursively removing the
1127 contents if its a directory.  This is like the C<rm -rf> shell
1128 command.");
1129
1130   ("mkdir", (RErr, [String "path"]), 32, [],
1131    [InitBasicFS, Always, TestOutputTrue
1132       [["mkdir"; "/new"];
1133        ["is_dir"; "/new"]];
1134     InitBasicFS, Always, TestLastFail
1135       [["mkdir"; "/new/foo/bar"]]],
1136    "create a directory",
1137    "\
1138 Create a directory named C<path>.");
1139
1140   ("mkdir_p", (RErr, [String "path"]), 33, [],
1141    [InitBasicFS, Always, TestOutputTrue
1142       [["mkdir_p"; "/new/foo/bar"];
1143        ["is_dir"; "/new/foo/bar"]];
1144     InitBasicFS, Always, TestOutputTrue
1145       [["mkdir_p"; "/new/foo/bar"];
1146        ["is_dir"; "/new/foo"]];
1147     InitBasicFS, Always, TestOutputTrue
1148       [["mkdir_p"; "/new/foo/bar"];
1149        ["is_dir"; "/new"]];
1150     (* Regression tests for RHBZ#503133: *)
1151     InitBasicFS, Always, TestRun
1152       [["mkdir"; "/new"];
1153        ["mkdir_p"; "/new"]];
1154     InitBasicFS, Always, TestLastFail
1155       [["touch"; "/new"];
1156        ["mkdir_p"; "/new"]]],
1157    "create a directory and parents",
1158    "\
1159 Create a directory named C<path>, creating any parent directories
1160 as necessary.  This is like the C<mkdir -p> shell command.");
1161
1162   ("chmod", (RErr, [Int "mode"; String "path"]), 34, [],
1163    [], (* XXX Need stat command to test *)
1164    "change file mode",
1165    "\
1166 Change the mode (permissions) of C<path> to C<mode>.  Only
1167 numeric modes are supported.");
1168
1169   ("chown", (RErr, [Int "owner"; Int "group"; String "path"]), 35, [],
1170    [], (* XXX Need stat command to test *)
1171    "change file owner and group",
1172    "\
1173 Change the file owner to C<owner> and group to C<group>.
1174
1175 Only numeric uid and gid are supported.  If you want to use
1176 names, you will need to locate and parse the password file
1177 yourself (Augeas support makes this relatively easy).");
1178
1179   ("exists", (RBool "existsflag", [String "path"]), 36, [],
1180    [InitBasicFS, Always, TestOutputTrue (
1181       [["touch"; "/new"];
1182        ["exists"; "/new"]]);
1183     InitBasicFS, Always, TestOutputTrue (
1184       [["mkdir"; "/new"];
1185        ["exists"; "/new"]])],
1186    "test if file or directory exists",
1187    "\
1188 This returns C<true> if and only if there is a file, directory
1189 (or anything) with the given C<path> name.
1190
1191 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.");
1192
1193   ("is_file", (RBool "fileflag", [String "path"]), 37, [],
1194    [InitBasicFS, Always, TestOutputTrue (
1195       [["touch"; "/new"];
1196        ["is_file"; "/new"]]);
1197     InitBasicFS, Always, TestOutputFalse (
1198       [["mkdir"; "/new"];
1199        ["is_file"; "/new"]])],
1200    "test if file exists",
1201    "\
1202 This returns C<true> if and only if there is a file
1203 with the given C<path> name.  Note that it returns false for
1204 other objects like directories.
1205
1206 See also C<guestfs_stat>.");
1207
1208   ("is_dir", (RBool "dirflag", [String "path"]), 38, [],
1209    [InitBasicFS, Always, TestOutputFalse (
1210       [["touch"; "/new"];
1211        ["is_dir"; "/new"]]);
1212     InitBasicFS, Always, TestOutputTrue (
1213       [["mkdir"; "/new"];
1214        ["is_dir"; "/new"]])],
1215    "test if file exists",
1216    "\
1217 This returns C<true> if and only if there is a directory
1218 with the given C<path> name.  Note that it returns false for
1219 other objects like files.
1220
1221 See also C<guestfs_stat>.");
1222
1223   ("pvcreate", (RErr, [String "device"]), 39, [],
1224    [InitEmpty, Always, TestOutputListOfDevices (
1225       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1226        ["pvcreate"; "/dev/sda1"];
1227        ["pvcreate"; "/dev/sda2"];
1228        ["pvcreate"; "/dev/sda3"];
1229        ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])],
1230    "create an LVM physical volume",
1231    "\
1232 This creates an LVM physical volume on the named C<device>,
1233 where C<device> should usually be a partition name such
1234 as C</dev/sda1>.");
1235
1236   ("vgcreate", (RErr, [String "volgroup"; StringList "physvols"]), 40, [],
1237    [InitEmpty, Always, TestOutputList (
1238       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1239        ["pvcreate"; "/dev/sda1"];
1240        ["pvcreate"; "/dev/sda2"];
1241        ["pvcreate"; "/dev/sda3"];
1242        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1243        ["vgcreate"; "VG2"; "/dev/sda3"];
1244        ["vgs"]], ["VG1"; "VG2"])],
1245    "create an LVM volume group",
1246    "\
1247 This creates an LVM volume group called C<volgroup>
1248 from the non-empty list of physical volumes C<physvols>.");
1249
1250   ("lvcreate", (RErr, [String "logvol"; String "volgroup"; Int "mbytes"]), 41, [],
1251    [InitEmpty, Always, TestOutputList (
1252       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1253        ["pvcreate"; "/dev/sda1"];
1254        ["pvcreate"; "/dev/sda2"];
1255        ["pvcreate"; "/dev/sda3"];
1256        ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"];
1257        ["vgcreate"; "VG2"; "/dev/sda3"];
1258        ["lvcreate"; "LV1"; "VG1"; "50"];
1259        ["lvcreate"; "LV2"; "VG1"; "50"];
1260        ["lvcreate"; "LV3"; "VG2"; "50"];
1261        ["lvcreate"; "LV4"; "VG2"; "50"];
1262        ["lvcreate"; "LV5"; "VG2"; "50"];
1263        ["lvs"]],
1264       ["/dev/VG1/LV1"; "/dev/VG1/LV2";
1265        "/dev/VG2/LV3"; "/dev/VG2/LV4"; "/dev/VG2/LV5"])],
1266    "create an LVM volume group",
1267    "\
1268 This creates an LVM volume group called C<logvol>
1269 on the volume group C<volgroup>, with C<size> megabytes.");
1270
1271   ("mkfs", (RErr, [String "fstype"; String "device"]), 42, [],
1272    [InitEmpty, Always, TestOutput (
1273       [["sfdiskM"; "/dev/sda"; ","];
1274        ["mkfs"; "ext2"; "/dev/sda1"];
1275        ["mount"; "/dev/sda1"; "/"];
1276        ["write_file"; "/new"; "new file contents"; "0"];
1277        ["cat"; "/new"]], "new file contents")],
1278    "make a filesystem",
1279    "\
1280 This creates a filesystem on C<device> (usually a partition
1281 or LVM logical volume).  The filesystem type is C<fstype>, for
1282 example C<ext3>.");
1283
1284   ("sfdisk", (RErr, [String "device";
1285                      Int "cyls"; Int "heads"; Int "sectors";
1286                      StringList "lines"]), 43, [DangerWillRobinson],
1287    [],
1288    "create partitions on a block device",
1289    "\
1290 This is a direct interface to the L<sfdisk(8)> program for creating
1291 partitions on block devices.
1292
1293 C<device> should be a block device, for example C</dev/sda>.
1294
1295 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1296 and sectors on the device, which are passed directly to sfdisk as
1297 the I<-C>, I<-H> and I<-S> parameters.  If you pass C<0> for any
1298 of these, then the corresponding parameter is omitted.  Usually for
1299 'large' disks, you can just pass C<0> for these, but for small
1300 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1301 out the right geometry and you will need to tell it.
1302
1303 C<lines> is a list of lines that we feed to C<sfdisk>.  For more
1304 information refer to the L<sfdisk(8)> manpage.
1305
1306 To create a single partition occupying the whole disk, you would
1307 pass C<lines> as a single element list, when the single element being
1308 the string C<,> (comma).
1309
1310 See also: C<guestfs_sfdisk_l>, C<guestfs_sfdisk_N>");
1311
1312   ("write_file", (RErr, [String "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning],
1313    [InitBasicFS, Always, TestOutput (
1314       [["write_file"; "/new"; "new file contents"; "0"];
1315        ["cat"; "/new"]], "new file contents");
1316     InitBasicFS, Always, TestOutput (
1317       [["write_file"; "/new"; "\nnew file contents\n"; "0"];
1318        ["cat"; "/new"]], "\nnew file contents\n");
1319     InitBasicFS, Always, TestOutput (
1320       [["write_file"; "/new"; "\n\n"; "0"];
1321        ["cat"; "/new"]], "\n\n");
1322     InitBasicFS, Always, TestOutput (
1323       [["write_file"; "/new"; ""; "0"];
1324        ["cat"; "/new"]], "");
1325     InitBasicFS, Always, TestOutput (
1326       [["write_file"; "/new"; "\n\n\n"; "0"];
1327        ["cat"; "/new"]], "\n\n\n");
1328     InitBasicFS, Always, TestOutput (
1329       [["write_file"; "/new"; "\n"; "0"];
1330        ["cat"; "/new"]], "\n")],
1331    "create a file",
1332    "\
1333 This call creates a file called C<path>.  The contents of the
1334 file is the string C<content> (which can contain any 8 bit data),
1335 with length C<size>.
1336
1337 As a special case, if C<size> is C<0>
1338 then the length is calculated using C<strlen> (so in this case
1339 the content cannot contain embedded ASCII NULs).
1340
1341 I<NB.> Owing to a bug, writing content containing ASCII NUL
1342 characters does I<not> work, even if the length is specified.
1343 We hope to resolve this bug in a future version.  In the meantime
1344 use C<guestfs_upload>.");
1345
1346   ("umount", (RErr, [String "pathordevice"]), 45, [FishAlias "unmount"],
1347    [InitEmpty, Always, TestOutputListOfDevices (
1348       [["sfdiskM"; "/dev/sda"; ","];
1349        ["mkfs"; "ext2"; "/dev/sda1"];
1350        ["mount"; "/dev/sda1"; "/"];
1351        ["mounts"]], ["/dev/sda1"]);
1352     InitEmpty, Always, TestOutputList (
1353       [["sfdiskM"; "/dev/sda"; ","];
1354        ["mkfs"; "ext2"; "/dev/sda1"];
1355        ["mount"; "/dev/sda1"; "/"];
1356        ["umount"; "/"];
1357        ["mounts"]], [])],
1358    "unmount a filesystem",
1359    "\
1360 This unmounts the given filesystem.  The filesystem may be
1361 specified either by its mountpoint (path) or the device which
1362 contains the filesystem.");
1363
1364   ("mounts", (RStringList "devices", []), 46, [],
1365    [InitBasicFS, Always, TestOutputListOfDevices (
1366       [["mounts"]], ["/dev/sda1"])],
1367    "show mounted filesystems",
1368    "\
1369 This returns the list of currently mounted filesystems.  It returns
1370 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1371
1372 Some internal mounts are not shown.");
1373
1374   ("umount_all", (RErr, []), 47, [FishAlias "unmount-all"],
1375    [InitBasicFS, Always, TestOutputList (
1376       [["umount_all"];
1377        ["mounts"]], []);
1378     (* check that umount_all can unmount nested mounts correctly: *)
1379     InitEmpty, Always, TestOutputList (
1380       [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"];
1381        ["mkfs"; "ext2"; "/dev/sda1"];
1382        ["mkfs"; "ext2"; "/dev/sda2"];
1383        ["mkfs"; "ext2"; "/dev/sda3"];
1384        ["mount"; "/dev/sda1"; "/"];
1385        ["mkdir"; "/mp1"];
1386        ["mount"; "/dev/sda2"; "/mp1"];
1387        ["mkdir"; "/mp1/mp2"];
1388        ["mount"; "/dev/sda3"; "/mp1/mp2"];
1389        ["mkdir"; "/mp1/mp2/mp3"];
1390        ["umount_all"];
1391        ["mounts"]], [])],
1392    "unmount all filesystems",
1393    "\
1394 This unmounts all mounted filesystems.
1395
1396 Some internal mounts are not unmounted by this call.");
1397
1398   ("lvm_remove_all", (RErr, []), 48, [DangerWillRobinson],
1399    [],
1400    "remove all LVM LVs, VGs and PVs",
1401    "\
1402 This command removes all LVM logical volumes, volume groups
1403 and physical volumes.");
1404
1405   ("file", (RString "description", [String "path"]), 49, [],
1406    [InitBasicFS, Always, TestOutput (
1407       [["touch"; "/new"];
1408        ["file"; "/new"]], "empty");
1409     InitBasicFS, Always, TestOutput (
1410       [["write_file"; "/new"; "some content\n"; "0"];
1411        ["file"; "/new"]], "ASCII text");
1412     InitBasicFS, Always, TestLastFail (
1413       [["file"; "/nofile"]])],
1414    "determine file type",
1415    "\
1416 This call uses the standard L<file(1)> command to determine
1417 the type or contents of the file.  This also works on devices,
1418 for example to find out whether a partition contains a filesystem.
1419
1420 The exact command which runs is C<file -bsL path>.  Note in
1421 particular that the filename is not prepended to the output
1422 (the C<-b> option).");
1423
1424   ("command", (RString "output", [StringList "arguments"]), 50, [ProtocolLimitWarning],
1425    [InitBasicFS, Always, TestOutput (
1426       [["upload"; "test-command"; "/test-command"];
1427        ["chmod"; "0o755"; "/test-command"];
1428        ["command"; "/test-command 1"]], "Result1");
1429     InitBasicFS, Always, TestOutput (
1430       [["upload"; "test-command"; "/test-command"];
1431        ["chmod"; "0o755"; "/test-command"];
1432        ["command"; "/test-command 2"]], "Result2\n");
1433     InitBasicFS, Always, TestOutput (
1434       [["upload"; "test-command"; "/test-command"];
1435        ["chmod"; "0o755"; "/test-command"];
1436        ["command"; "/test-command 3"]], "\nResult3");
1437     InitBasicFS, Always, TestOutput (
1438       [["upload"; "test-command"; "/test-command"];
1439        ["chmod"; "0o755"; "/test-command"];
1440        ["command"; "/test-command 4"]], "\nResult4\n");
1441     InitBasicFS, Always, TestOutput (
1442       [["upload"; "test-command"; "/test-command"];
1443        ["chmod"; "0o755"; "/test-command"];
1444        ["command"; "/test-command 5"]], "\nResult5\n\n");
1445     InitBasicFS, Always, TestOutput (
1446       [["upload"; "test-command"; "/test-command"];
1447        ["chmod"; "0o755"; "/test-command"];
1448        ["command"; "/test-command 6"]], "\n\nResult6\n\n");
1449     InitBasicFS, Always, TestOutput (
1450       [["upload"; "test-command"; "/test-command"];
1451        ["chmod"; "0o755"; "/test-command"];
1452        ["command"; "/test-command 7"]], "");
1453     InitBasicFS, Always, TestOutput (
1454       [["upload"; "test-command"; "/test-command"];
1455        ["chmod"; "0o755"; "/test-command"];
1456        ["command"; "/test-command 8"]], "\n");
1457     InitBasicFS, Always, TestOutput (
1458       [["upload"; "test-command"; "/test-command"];
1459        ["chmod"; "0o755"; "/test-command"];
1460        ["command"; "/test-command 9"]], "\n\n");
1461     InitBasicFS, Always, TestOutput (
1462       [["upload"; "test-command"; "/test-command"];
1463        ["chmod"; "0o755"; "/test-command"];
1464        ["command"; "/test-command 10"]], "Result10-1\nResult10-2\n");
1465     InitBasicFS, Always, TestOutput (
1466       [["upload"; "test-command"; "/test-command"];
1467        ["chmod"; "0o755"; "/test-command"];
1468        ["command"; "/test-command 11"]], "Result11-1\nResult11-2");
1469     InitBasicFS, Always, TestLastFail (
1470       [["upload"; "test-command"; "/test-command"];
1471        ["chmod"; "0o755"; "/test-command"];
1472        ["command"; "/test-command"]])],
1473    "run a command from the guest filesystem",
1474    "\
1475 This call runs a command from the guest filesystem.  The
1476 filesystem must be mounted, and must contain a compatible
1477 operating system (ie. something Linux, with the same
1478 or compatible processor architecture).
1479
1480 The single parameter is an argv-style list of arguments.
1481 The first element is the name of the program to run.
1482 Subsequent elements are parameters.  The list must be
1483 non-empty (ie. must contain a program name).  Note that
1484 the command runs directly, and is I<not> invoked via
1485 the shell (see C<guestfs_sh>).
1486
1487 The return value is anything printed to I<stdout> by
1488 the command.
1489
1490 If the command returns a non-zero exit status, then
1491 this function returns an error message.  The error message
1492 string is the content of I<stderr> from the command.
1493
1494 The C<$PATH> environment variable will contain at least
1495 C</usr/bin> and C</bin>.  If you require a program from
1496 another location, you should provide the full path in the
1497 first parameter.
1498
1499 Shared libraries and data files required by the program
1500 must be available on filesystems which are mounted in the
1501 correct places.  It is the caller's responsibility to ensure
1502 all filesystems that are needed are mounted at the right
1503 locations.");
1504
1505   ("command_lines", (RStringList "lines", [StringList "arguments"]), 51, [ProtocolLimitWarning],
1506    [InitBasicFS, Always, TestOutputList (
1507       [["upload"; "test-command"; "/test-command"];
1508        ["chmod"; "0o755"; "/test-command"];
1509        ["command_lines"; "/test-command 1"]], ["Result1"]);
1510     InitBasicFS, Always, TestOutputList (
1511       [["upload"; "test-command"; "/test-command"];
1512        ["chmod"; "0o755"; "/test-command"];
1513        ["command_lines"; "/test-command 2"]], ["Result2"]);
1514     InitBasicFS, Always, TestOutputList (
1515       [["upload"; "test-command"; "/test-command"];
1516        ["chmod"; "0o755"; "/test-command"];
1517        ["command_lines"; "/test-command 3"]], ["";"Result3"]);
1518     InitBasicFS, Always, TestOutputList (
1519       [["upload"; "test-command"; "/test-command"];
1520        ["chmod"; "0o755"; "/test-command"];
1521        ["command_lines"; "/test-command 4"]], ["";"Result4"]);
1522     InitBasicFS, Always, TestOutputList (
1523       [["upload"; "test-command"; "/test-command"];
1524        ["chmod"; "0o755"; "/test-command"];
1525        ["command_lines"; "/test-command 5"]], ["";"Result5";""]);
1526     InitBasicFS, Always, TestOutputList (
1527       [["upload"; "test-command"; "/test-command"];
1528        ["chmod"; "0o755"; "/test-command"];
1529        ["command_lines"; "/test-command 6"]], ["";"";"Result6";""]);
1530     InitBasicFS, Always, TestOutputList (
1531       [["upload"; "test-command"; "/test-command"];
1532        ["chmod"; "0o755"; "/test-command"];
1533        ["command_lines"; "/test-command 7"]], []);
1534     InitBasicFS, Always, TestOutputList (
1535       [["upload"; "test-command"; "/test-command"];
1536        ["chmod"; "0o755"; "/test-command"];
1537        ["command_lines"; "/test-command 8"]], [""]);
1538     InitBasicFS, Always, TestOutputList (
1539       [["upload"; "test-command"; "/test-command"];
1540        ["chmod"; "0o755"; "/test-command"];
1541        ["command_lines"; "/test-command 9"]], ["";""]);
1542     InitBasicFS, Always, TestOutputList (
1543       [["upload"; "test-command"; "/test-command"];
1544        ["chmod"; "0o755"; "/test-command"];
1545        ["command_lines"; "/test-command 10"]], ["Result10-1";"Result10-2"]);
1546     InitBasicFS, Always, TestOutputList (
1547       [["upload"; "test-command"; "/test-command"];
1548        ["chmod"; "0o755"; "/test-command"];
1549        ["command_lines"; "/test-command 11"]], ["Result11-1";"Result11-2"])],
1550    "run a command, returning lines",
1551    "\
1552 This is the same as C<guestfs_command>, but splits the
1553 result into a list of lines.
1554
1555 See also: C<guestfs_sh_lines>");
1556
1557   ("stat", (RStruct ("statbuf", "stat"), [String "path"]), 52, [],
1558    [InitBasicFS, Always, TestOutputStruct (
1559       [["touch"; "/new"];
1560        ["stat"; "/new"]], [CompareWithInt ("size", 0)])],
1561    "get file information",
1562    "\
1563 Returns file information for the given C<path>.
1564
1565 This is the same as the C<stat(2)> system call.");
1566
1567   ("lstat", (RStruct ("statbuf", "stat"), [String "path"]), 53, [],
1568    [InitBasicFS, Always, TestOutputStruct (
1569       [["touch"; "/new"];
1570        ["lstat"; "/new"]], [CompareWithInt ("size", 0)])],
1571    "get file information for a symbolic link",
1572    "\
1573 Returns file information for the given C<path>.
1574
1575 This is the same as C<guestfs_stat> except that if C<path>
1576 is a symbolic link, then the link is stat-ed, not the file it
1577 refers to.
1578
1579 This is the same as the C<lstat(2)> system call.");
1580
1581   ("statvfs", (RStruct ("statbuf", "statvfs"), [String "path"]), 54, [],
1582    [InitBasicFS, Always, TestOutputStruct (
1583       [["statvfs"; "/"]], [CompareWithInt ("namemax", 255);
1584                            CompareWithInt ("bsize", 1024)])],
1585    "get file system statistics",
1586    "\
1587 Returns file system statistics for any mounted file system.
1588 C<path> should be a file or directory in the mounted file system
1589 (typically it is the mount point itself, but it doesn't need to be).
1590
1591 This is the same as the C<statvfs(2)> system call.");
1592
1593   ("tune2fs_l", (RHashtable "superblock", [String "device"]), 55, [],
1594    [], (* XXX test *)
1595    "get ext2/ext3/ext4 superblock details",
1596    "\
1597 This returns the contents of the ext2, ext3 or ext4 filesystem
1598 superblock on C<device>.
1599
1600 It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
1601 manpage for more details.  The list of fields returned isn't
1602 clearly defined, and depends on both the version of C<tune2fs>
1603 that libguestfs was built against, and the filesystem itself.");
1604
1605   ("blockdev_setro", (RErr, [String "device"]), 56, [],
1606    [InitEmpty, Always, TestOutputTrue (
1607       [["blockdev_setro"; "/dev/sda"];
1608        ["blockdev_getro"; "/dev/sda"]])],
1609    "set block device to read-only",
1610    "\
1611 Sets the block device named C<device> to read-only.
1612
1613 This uses the L<blockdev(8)> command.");
1614
1615   ("blockdev_setrw", (RErr, [String "device"]), 57, [],
1616    [InitEmpty, Always, TestOutputFalse (
1617       [["blockdev_setrw"; "/dev/sda"];
1618        ["blockdev_getro"; "/dev/sda"]])],
1619    "set block device to read-write",
1620    "\
1621 Sets the block device named C<device> to read-write.
1622
1623 This uses the L<blockdev(8)> command.");
1624
1625   ("blockdev_getro", (RBool "ro", [String "device"]), 58, [],
1626    [InitEmpty, Always, TestOutputTrue (
1627       [["blockdev_setro"; "/dev/sda"];
1628        ["blockdev_getro"; "/dev/sda"]])],
1629    "is block device set to read-only",
1630    "\
1631 Returns a boolean indicating if the block device is read-only
1632 (true if read-only, false if not).
1633
1634 This uses the L<blockdev(8)> command.");
1635
1636   ("blockdev_getss", (RInt "sectorsize", [String "device"]), 59, [],
1637    [InitEmpty, Always, TestOutputInt (
1638       [["blockdev_getss"; "/dev/sda"]], 512)],
1639    "get sectorsize of block device",
1640    "\
1641 This returns the size of sectors on a block device.
1642 Usually 512, but can be larger for modern devices.
1643
1644 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
1645 for that).
1646
1647 This uses the L<blockdev(8)> command.");
1648
1649   ("blockdev_getbsz", (RInt "blocksize", [String "device"]), 60, [],
1650    [InitEmpty, Always, TestOutputInt (
1651       [["blockdev_getbsz"; "/dev/sda"]], 4096)],
1652    "get blocksize of block device",
1653    "\
1654 This returns the block size of a device.
1655
1656 (Note this is different from both I<size in blocks> and
1657 I<filesystem block size>).
1658
1659 This uses the L<blockdev(8)> command.");
1660
1661   ("blockdev_setbsz", (RErr, [String "device"; Int "blocksize"]), 61, [],
1662    [], (* XXX test *)
1663    "set blocksize of block device",
1664    "\
1665 This sets the block size of a device.
1666
1667 (Note this is different from both I<size in blocks> and
1668 I<filesystem block size>).
1669
1670 This uses the L<blockdev(8)> command.");
1671
1672   ("blockdev_getsz", (RInt64 "sizeinsectors", [String "device"]), 62, [],
1673    [InitEmpty, Always, TestOutputInt (
1674       [["blockdev_getsz"; "/dev/sda"]], 1024000)],
1675    "get total size of device in 512-byte sectors",
1676    "\
1677 This returns the size of the device in units of 512-byte sectors
1678 (even if the sectorsize isn't 512 bytes ... weird).
1679
1680 See also C<guestfs_blockdev_getss> for the real sector size of
1681 the device, and C<guestfs_blockdev_getsize64> for the more
1682 useful I<size in bytes>.
1683
1684 This uses the L<blockdev(8)> command.");
1685
1686   ("blockdev_getsize64", (RInt64 "sizeinbytes", [String "device"]), 63, [],
1687    [InitEmpty, Always, TestOutputInt (
1688       [["blockdev_getsize64"; "/dev/sda"]], 524288000)],
1689    "get total size of device in bytes",
1690    "\
1691 This returns the size of the device in bytes.
1692
1693 See also C<guestfs_blockdev_getsz>.
1694
1695 This uses the L<blockdev(8)> command.");
1696
1697   ("blockdev_flushbufs", (RErr, [String "device"]), 64, [],
1698    [InitEmpty, Always, TestRun
1699       [["blockdev_flushbufs"; "/dev/sda"]]],
1700    "flush device buffers",
1701    "\
1702 This tells the kernel to flush internal buffers associated
1703 with C<device>.
1704
1705 This uses the L<blockdev(8)> command.");
1706
1707   ("blockdev_rereadpt", (RErr, [String "device"]), 65, [],
1708    [InitEmpty, Always, TestRun
1709       [["blockdev_rereadpt"; "/dev/sda"]]],
1710    "reread partition table",
1711    "\
1712 Reread the partition table on C<device>.
1713
1714 This uses the L<blockdev(8)> command.");
1715
1716   ("upload", (RErr, [FileIn "filename"; String "remotefilename"]), 66, [],
1717    [InitBasicFS, Always, TestOutput (
1718       (* Pick a file from cwd which isn't likely to change. *)
1719     [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1720      ["checksum"; "md5"; "/COPYING.LIB"]], "e3eda01d9815f8d24aae2dbd89b68b06")],
1721    "upload a file from the local machine",
1722    "\
1723 Upload local file C<filename> to C<remotefilename> on the
1724 filesystem.
1725
1726 C<filename> can also be a named pipe.
1727
1728 See also C<guestfs_download>.");
1729
1730   ("download", (RErr, [String "remotefilename"; FileOut "filename"]), 67, [],
1731    [InitBasicFS, Always, TestOutput (
1732       (* Pick a file from cwd which isn't likely to change. *)
1733     [["upload"; "../COPYING.LIB"; "/COPYING.LIB"];
1734      ["download"; "/COPYING.LIB"; "testdownload.tmp"];
1735      ["upload"; "testdownload.tmp"; "/upload"];
1736      ["checksum"; "md5"; "/upload"]], "e3eda01d9815f8d24aae2dbd89b68b06")],
1737    "download a file to the local machine",
1738    "\
1739 Download file C<remotefilename> and save it as C<filename>
1740 on the local machine.
1741
1742 C<filename> can also be a named pipe.
1743
1744 See also C<guestfs_upload>, C<guestfs_cat>.");
1745
1746   ("checksum", (RString "checksum", [String "csumtype"; String "path"]), 68, [],
1747    [InitBasicFS, Always, TestOutput (
1748       [["write_file"; "/new"; "test\n"; "0"];
1749        ["checksum"; "crc"; "/new"]], "935282863");
1750     InitBasicFS, Always, TestLastFail (
1751       [["checksum"; "crc"; "/new"]]);
1752     InitBasicFS, Always, TestOutput (
1753       [["write_file"; "/new"; "test\n"; "0"];
1754        ["checksum"; "md5"; "/new"]], "d8e8fca2dc0f896fd7cb4cb0031ba249");
1755     InitBasicFS, Always, TestOutput (
1756       [["write_file"; "/new"; "test\n"; "0"];
1757        ["checksum"; "sha1"; "/new"]], "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83");
1758     InitBasicFS, Always, TestOutput (
1759       [["write_file"; "/new"; "test\n"; "0"];
1760        ["checksum"; "sha224"; "/new"]], "52f1bf093f4b7588726035c176c0cdb4376cfea53819f1395ac9e6ec");
1761     InitBasicFS, Always, TestOutput (
1762       [["write_file"; "/new"; "test\n"; "0"];
1763        ["checksum"; "sha256"; "/new"]], "f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2");
1764     InitBasicFS, Always, TestOutput (
1765       [["write_file"; "/new"; "test\n"; "0"];
1766        ["checksum"; "sha384"; "/new"]], "109bb6b5b6d5547c1ce03c7a8bd7d8f80c1cb0957f50c4f7fda04692079917e4f9cad52b878f3d8234e1a170b154b72d");
1767     InitBasicFS, Always, TestOutput (
1768       [["write_file"; "/new"; "test\n"; "0"];
1769        ["checksum"; "sha512"; "/new"]], "0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123");
1770     InitBasicFS, Always, TestOutput (
1771       (* RHEL 5 thinks this is an HFS+ filesystem unless we give
1772        * the type explicitly.
1773        *)
1774       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
1775        ["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c")],
1776    "compute MD5, SHAx or CRC checksum of file",
1777    "\
1778 This call computes the MD5, SHAx or CRC checksum of the
1779 file named C<path>.
1780
1781 The type of checksum to compute is given by the C<csumtype>
1782 parameter which must have one of the following values:
1783
1784 =over 4
1785
1786 =item C<crc>
1787
1788 Compute the cyclic redundancy check (CRC) specified by POSIX
1789 for the C<cksum> command.
1790
1791 =item C<md5>
1792
1793 Compute the MD5 hash (using the C<md5sum> program).
1794
1795 =item C<sha1>
1796
1797 Compute the SHA1 hash (using the C<sha1sum> program).
1798
1799 =item C<sha224>
1800
1801 Compute the SHA224 hash (using the C<sha224sum> program).
1802
1803 =item C<sha256>
1804
1805 Compute the SHA256 hash (using the C<sha256sum> program).
1806
1807 =item C<sha384>
1808
1809 Compute the SHA384 hash (using the C<sha384sum> program).
1810
1811 =item C<sha512>
1812
1813 Compute the SHA512 hash (using the C<sha512sum> program).
1814
1815 =back
1816
1817 The checksum is returned as a printable string.");
1818
1819   ("tar_in", (RErr, [FileIn "tarfile"; String "directory"]), 69, [],
1820    [InitBasicFS, Always, TestOutput (
1821       [["tar_in"; "../images/helloworld.tar"; "/"];
1822        ["cat"; "/hello"]], "hello\n")],
1823    "unpack tarfile to directory",
1824    "\
1825 This command uploads and unpacks local file C<tarfile> (an
1826 I<uncompressed> tar file) into C<directory>.
1827
1828 To upload a compressed tarball, use C<guestfs_tgz_in>.");
1829
1830   ("tar_out", (RErr, [String "directory"; FileOut "tarfile"]), 70, [],
1831    [],
1832    "pack directory into tarfile",
1833    "\
1834 This command packs the contents of C<directory> and downloads
1835 it to local file C<tarfile>.
1836
1837 To download a compressed tarball, use C<guestfs_tgz_out>.");
1838
1839   ("tgz_in", (RErr, [FileIn "tarball"; String "directory"]), 71, [],
1840    [InitBasicFS, Always, TestOutput (
1841       [["tgz_in"; "../images/helloworld.tar.gz"; "/"];
1842        ["cat"; "/hello"]], "hello\n")],
1843    "unpack compressed tarball to directory",
1844    "\
1845 This command uploads and unpacks local file C<tarball> (a
1846 I<gzip compressed> tar file) into C<directory>.
1847
1848 To upload an uncompressed tarball, use C<guestfs_tar_in>.");
1849
1850   ("tgz_out", (RErr, [String "directory"; FileOut "tarball"]), 72, [],
1851    [],
1852    "pack directory into compressed tarball",
1853    "\
1854 This command packs the contents of C<directory> and downloads
1855 it to local file C<tarball>.
1856
1857 To download an uncompressed tarball, use C<guestfs_tar_out>.");
1858
1859   ("mount_ro", (RErr, [String "device"; String "mountpoint"]), 73, [],
1860    [InitBasicFS, Always, TestLastFail (
1861       [["umount"; "/"];
1862        ["mount_ro"; "/dev/sda1"; "/"];
1863        ["touch"; "/new"]]);
1864     InitBasicFS, Always, TestOutput (
1865       [["write_file"; "/new"; "data"; "0"];
1866        ["umount"; "/"];
1867        ["mount_ro"; "/dev/sda1"; "/"];
1868        ["cat"; "/new"]], "data")],
1869    "mount a guest disk, read-only",
1870    "\
1871 This is the same as the C<guestfs_mount> command, but it
1872 mounts the filesystem with the read-only (I<-o ro>) flag.");
1873
1874   ("mount_options", (RErr, [String "options"; String "device"; String "mountpoint"]), 74, [],
1875    [],
1876    "mount a guest disk with mount options",
1877    "\
1878 This is the same as the C<guestfs_mount> command, but it
1879 allows you to set the mount options as for the
1880 L<mount(8)> I<-o> flag.");
1881
1882   ("mount_vfs", (RErr, [String "options"; String "vfstype"; String "device"; String "mountpoint"]), 75, [],
1883    [],
1884    "mount a guest disk with mount options and vfstype",
1885    "\
1886 This is the same as the C<guestfs_mount> command, but it
1887 allows you to set both the mount options and the vfstype
1888 as for the L<mount(8)> I<-o> and I<-t> flags.");
1889
1890   ("debug", (RString "result", [String "subcmd"; StringList "extraargs"]), 76, [],
1891    [],
1892    "debugging and internals",
1893    "\
1894 The C<guestfs_debug> command exposes some internals of
1895 C<guestfsd> (the guestfs daemon) that runs inside the
1896 qemu subprocess.
1897
1898 There is no comprehensive help for this command.  You have
1899 to look at the file C<daemon/debug.c> in the libguestfs source
1900 to find out what you can do.");
1901
1902   ("lvremove", (RErr, [String "device"]), 77, [],
1903    [InitEmpty, Always, TestOutputList (
1904       [["sfdiskM"; "/dev/sda"; ","];
1905        ["pvcreate"; "/dev/sda1"];
1906        ["vgcreate"; "VG"; "/dev/sda1"];
1907        ["lvcreate"; "LV1"; "VG"; "50"];
1908        ["lvcreate"; "LV2"; "VG"; "50"];
1909        ["lvremove"; "/dev/VG/LV1"];
1910        ["lvs"]], ["/dev/VG/LV2"]);
1911     InitEmpty, Always, TestOutputList (
1912       [["sfdiskM"; "/dev/sda"; ","];
1913        ["pvcreate"; "/dev/sda1"];
1914        ["vgcreate"; "VG"; "/dev/sda1"];
1915        ["lvcreate"; "LV1"; "VG"; "50"];
1916        ["lvcreate"; "LV2"; "VG"; "50"];
1917        ["lvremove"; "/dev/VG"];
1918        ["lvs"]], []);
1919     InitEmpty, Always, TestOutputList (
1920       [["sfdiskM"; "/dev/sda"; ","];
1921        ["pvcreate"; "/dev/sda1"];
1922        ["vgcreate"; "VG"; "/dev/sda1"];
1923        ["lvcreate"; "LV1"; "VG"; "50"];
1924        ["lvcreate"; "LV2"; "VG"; "50"];
1925        ["lvremove"; "/dev/VG"];
1926        ["vgs"]], ["VG"])],
1927    "remove an LVM logical volume",
1928    "\
1929 Remove an LVM logical volume C<device>, where C<device> is
1930 the path to the LV, such as C</dev/VG/LV>.
1931
1932 You can also remove all LVs in a volume group by specifying
1933 the VG name, C</dev/VG>.");
1934
1935   ("vgremove", (RErr, [String "vgname"]), 78, [],
1936    [InitEmpty, Always, TestOutputList (
1937       [["sfdiskM"; "/dev/sda"; ","];
1938        ["pvcreate"; "/dev/sda1"];
1939        ["vgcreate"; "VG"; "/dev/sda1"];
1940        ["lvcreate"; "LV1"; "VG"; "50"];
1941        ["lvcreate"; "LV2"; "VG"; "50"];
1942        ["vgremove"; "VG"];
1943        ["lvs"]], []);
1944     InitEmpty, Always, TestOutputList (
1945       [["sfdiskM"; "/dev/sda"; ","];
1946        ["pvcreate"; "/dev/sda1"];
1947        ["vgcreate"; "VG"; "/dev/sda1"];
1948        ["lvcreate"; "LV1"; "VG"; "50"];
1949        ["lvcreate"; "LV2"; "VG"; "50"];
1950        ["vgremove"; "VG"];
1951        ["vgs"]], [])],
1952    "remove an LVM volume group",
1953    "\
1954 Remove an LVM volume group C<vgname>, (for example C<VG>).
1955
1956 This also forcibly removes all logical volumes in the volume
1957 group (if any).");
1958
1959   ("pvremove", (RErr, [String "device"]), 79, [],
1960    [InitEmpty, Always, TestOutputListOfDevices (
1961       [["sfdiskM"; "/dev/sda"; ","];
1962        ["pvcreate"; "/dev/sda1"];
1963        ["vgcreate"; "VG"; "/dev/sda1"];
1964        ["lvcreate"; "LV1"; "VG"; "50"];
1965        ["lvcreate"; "LV2"; "VG"; "50"];
1966        ["vgremove"; "VG"];
1967        ["pvremove"; "/dev/sda1"];
1968        ["lvs"]], []);
1969     InitEmpty, Always, TestOutputListOfDevices (
1970       [["sfdiskM"; "/dev/sda"; ","];
1971        ["pvcreate"; "/dev/sda1"];
1972        ["vgcreate"; "VG"; "/dev/sda1"];
1973        ["lvcreate"; "LV1"; "VG"; "50"];
1974        ["lvcreate"; "LV2"; "VG"; "50"];
1975        ["vgremove"; "VG"];
1976        ["pvremove"; "/dev/sda1"];
1977        ["vgs"]], []);
1978     InitEmpty, Always, TestOutputListOfDevices (
1979       [["sfdiskM"; "/dev/sda"; ","];
1980        ["pvcreate"; "/dev/sda1"];
1981        ["vgcreate"; "VG"; "/dev/sda1"];
1982        ["lvcreate"; "LV1"; "VG"; "50"];
1983        ["lvcreate"; "LV2"; "VG"; "50"];
1984        ["vgremove"; "VG"];
1985        ["pvremove"; "/dev/sda1"];
1986        ["pvs"]], [])],
1987    "remove an LVM physical volume",
1988    "\
1989 This wipes a physical volume C<device> so that LVM will no longer
1990 recognise it.
1991
1992 The implementation uses the C<pvremove> command which refuses to
1993 wipe physical volumes that contain any volume groups, so you have
1994 to remove those first.");
1995
1996   ("set_e2label", (RErr, [String "device"; String "label"]), 80, [],
1997    [InitBasicFS, Always, TestOutput (
1998       [["set_e2label"; "/dev/sda1"; "testlabel"];
1999        ["get_e2label"; "/dev/sda1"]], "testlabel")],
2000    "set the ext2/3/4 filesystem label",
2001    "\
2002 This sets the ext2/3/4 filesystem label of the filesystem on
2003 C<device> to C<label>.  Filesystem labels are limited to
2004 16 characters.
2005
2006 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
2007 to return the existing label on a filesystem.");
2008
2009   ("get_e2label", (RString "label", [String "device"]), 81, [],
2010    [],
2011    "get the ext2/3/4 filesystem label",
2012    "\
2013 This returns the ext2/3/4 filesystem label of the filesystem on
2014 C<device>.");
2015
2016   ("set_e2uuid", (RErr, [String "device"; String "uuid"]), 82, [],
2017    [InitBasicFS, Always, TestOutput (
2018       [["set_e2uuid"; "/dev/sda1"; "a3a61220-882b-4f61-89f4-cf24dcc7297d"];
2019        ["get_e2uuid"; "/dev/sda1"]], "a3a61220-882b-4f61-89f4-cf24dcc7297d");
2020     InitBasicFS, Always, TestOutput (
2021       [["set_e2uuid"; "/dev/sda1"; "clear"];
2022        ["get_e2uuid"; "/dev/sda1"]], "");
2023     (* We can't predict what UUIDs will be, so just check the commands run. *)
2024     InitBasicFS, Always, TestRun (
2025       [["set_e2uuid"; "/dev/sda1"; "random"]]);
2026     InitBasicFS, Always, TestRun (
2027       [["set_e2uuid"; "/dev/sda1"; "time"]])],
2028    "set the ext2/3/4 filesystem UUID",
2029    "\
2030 This sets the ext2/3/4 filesystem UUID of the filesystem on
2031 C<device> to C<uuid>.  The format of the UUID and alternatives
2032 such as C<clear>, C<random> and C<time> are described in the
2033 L<tune2fs(8)> manpage.
2034
2035 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
2036 to return the existing UUID of a filesystem.");
2037
2038   ("get_e2uuid", (RString "uuid", [String "device"]), 83, [],
2039    [],
2040    "get the ext2/3/4 filesystem UUID",
2041    "\
2042 This returns the ext2/3/4 filesystem UUID of the filesystem on
2043 C<device>.");
2044
2045   ("fsck", (RInt "status", [String "fstype"; String "device"]), 84, [],
2046    [InitBasicFS, Always, TestOutputInt (
2047       [["umount"; "/dev/sda1"];
2048        ["fsck"; "ext2"; "/dev/sda1"]], 0);
2049     InitBasicFS, Always, TestOutputInt (
2050       [["umount"; "/dev/sda1"];
2051        ["zero"; "/dev/sda1"];
2052        ["fsck"; "ext2"; "/dev/sda1"]], 8)],
2053    "run the filesystem checker",
2054    "\
2055 This runs the filesystem checker (fsck) on C<device> which
2056 should have filesystem type C<fstype>.
2057
2058 The returned integer is the status.  See L<fsck(8)> for the
2059 list of status codes from C<fsck>.
2060
2061 Notes:
2062
2063 =over 4
2064
2065 =item *
2066
2067 Multiple status codes can be summed together.
2068
2069 =item *
2070
2071 A non-zero return code can mean \"success\", for example if
2072 errors have been corrected on the filesystem.
2073
2074 =item *
2075
2076 Checking or repairing NTFS volumes is not supported
2077 (by linux-ntfs).
2078
2079 =back
2080
2081 This command is entirely equivalent to running C<fsck -a -t fstype device>.");
2082
2083   ("zero", (RErr, [String "device"]), 85, [],
2084    [InitBasicFS, Always, TestOutput (
2085       [["umount"; "/dev/sda1"];
2086        ["zero"; "/dev/sda1"];
2087        ["file"; "/dev/sda1"]], "data")],
2088    "write zeroes to the device",
2089    "\
2090 This command writes zeroes over the first few blocks of C<device>.
2091
2092 How many blocks are zeroed isn't specified (but it's I<not> enough
2093 to securely wipe the device).  It should be sufficient to remove
2094 any partition tables, filesystem superblocks and so on.
2095
2096 See also: C<guestfs_scrub_device>.");
2097
2098   ("grub_install", (RErr, [String "root"; String "device"]), 86, [],
2099    (* Test disabled because grub-install incompatible with virtio-blk driver.
2100     * See also: https://bugzilla.redhat.com/show_bug.cgi?id=479760
2101     *)
2102    [InitBasicFS, Disabled, TestOutputTrue (
2103       [["grub_install"; "/"; "/dev/sda1"];
2104        ["is_dir"; "/boot"]])],
2105    "install GRUB",
2106    "\
2107 This command installs GRUB (the Grand Unified Bootloader) on
2108 C<device>, with the root directory being C<root>.");
2109
2110   ("cp", (RErr, [String "src"; String "dest"]), 87, [],
2111    [InitBasicFS, Always, TestOutput (
2112       [["write_file"; "/old"; "file content"; "0"];
2113        ["cp"; "/old"; "/new"];
2114        ["cat"; "/new"]], "file content");
2115     InitBasicFS, Always, TestOutputTrue (
2116       [["write_file"; "/old"; "file content"; "0"];
2117        ["cp"; "/old"; "/new"];
2118        ["is_file"; "/old"]]);
2119     InitBasicFS, Always, TestOutput (
2120       [["write_file"; "/old"; "file content"; "0"];
2121        ["mkdir"; "/dir"];
2122        ["cp"; "/old"; "/dir/new"];
2123        ["cat"; "/dir/new"]], "file content")],
2124    "copy a file",
2125    "\
2126 This copies a file from C<src> to C<dest> where C<dest> is
2127 either a destination filename or destination directory.");
2128
2129   ("cp_a", (RErr, [String "src"; String "dest"]), 88, [],
2130    [InitBasicFS, Always, TestOutput (
2131       [["mkdir"; "/olddir"];
2132        ["mkdir"; "/newdir"];
2133        ["write_file"; "/olddir/file"; "file content"; "0"];
2134        ["cp_a"; "/olddir"; "/newdir"];
2135        ["cat"; "/newdir/olddir/file"]], "file content")],
2136    "copy a file or directory recursively",
2137    "\
2138 This copies a file or directory from C<src> to C<dest>
2139 recursively using the C<cp -a> command.");
2140
2141   ("mv", (RErr, [String "src"; String "dest"]), 89, [],
2142    [InitBasicFS, Always, TestOutput (
2143       [["write_file"; "/old"; "file content"; "0"];
2144        ["mv"; "/old"; "/new"];
2145        ["cat"; "/new"]], "file content");
2146     InitBasicFS, Always, TestOutputFalse (
2147       [["write_file"; "/old"; "file content"; "0"];
2148        ["mv"; "/old"; "/new"];
2149        ["is_file"; "/old"]])],
2150    "move a file",
2151    "\
2152 This moves a file from C<src> to C<dest> where C<dest> is
2153 either a destination filename or destination directory.");
2154
2155   ("drop_caches", (RErr, [Int "whattodrop"]), 90, [],
2156    [InitEmpty, Always, TestRun (
2157       [["drop_caches"; "3"]])],
2158    "drop kernel page cache, dentries and inodes",
2159    "\
2160 This instructs the guest kernel to drop its page cache,
2161 and/or dentries and inode caches.  The parameter C<whattodrop>
2162 tells the kernel what precisely to drop, see
2163 L<http://linux-mm.org/Drop_Caches>
2164
2165 Setting C<whattodrop> to 3 should drop everything.
2166
2167 This automatically calls L<sync(2)> before the operation,
2168 so that the maximum guest memory is freed.");
2169
2170   ("dmesg", (RString "kmsgs", []), 91, [],
2171    [InitEmpty, Always, TestRun (
2172       [["dmesg"]])],
2173    "return kernel messages",
2174    "\
2175 This returns the kernel messages (C<dmesg> output) from
2176 the guest kernel.  This is sometimes useful for extended
2177 debugging of problems.
2178
2179 Another way to get the same information is to enable
2180 verbose messages with C<guestfs_set_verbose> or by setting
2181 the environment variable C<LIBGUESTFS_DEBUG=1> before
2182 running the program.");
2183
2184   ("ping_daemon", (RErr, []), 92, [],
2185    [InitEmpty, Always, TestRun (
2186       [["ping_daemon"]])],
2187    "ping the guest daemon",
2188    "\
2189 This is a test probe into the guestfs daemon running inside
2190 the qemu subprocess.  Calling this function checks that the
2191 daemon responds to the ping message, without affecting the daemon
2192 or attached block device(s) in any other way.");
2193
2194   ("equal", (RBool "equality", [String "file1"; String "file2"]), 93, [],
2195    [InitBasicFS, Always, TestOutputTrue (
2196       [["write_file"; "/file1"; "contents of a file"; "0"];
2197        ["cp"; "/file1"; "/file2"];
2198        ["equal"; "/file1"; "/file2"]]);
2199     InitBasicFS, Always, TestOutputFalse (
2200       [["write_file"; "/file1"; "contents of a file"; "0"];
2201        ["write_file"; "/file2"; "contents of another file"; "0"];
2202        ["equal"; "/file1"; "/file2"]]);
2203     InitBasicFS, Always, TestLastFail (
2204       [["equal"; "/file1"; "/file2"]])],
2205    "test if two files have equal contents",
2206    "\
2207 This compares the two files C<file1> and C<file2> and returns
2208 true if their content is exactly equal, or false otherwise.
2209
2210 The external L<cmp(1)> program is used for the comparison.");
2211
2212   ("strings", (RStringList "stringsout", [String "path"]), 94, [ProtocolLimitWarning],
2213    [InitBasicFS, Always, TestOutputList (
2214       [["write_file"; "/new"; "hello\nworld\n"; "0"];
2215        ["strings"; "/new"]], ["hello"; "world"]);
2216     InitBasicFS, Always, TestOutputList (
2217       [["touch"; "/new"];
2218        ["strings"; "/new"]], [])],
2219    "print the printable strings in a file",
2220    "\
2221 This runs the L<strings(1)> command on a file and returns
2222 the list of printable strings found.");
2223
2224   ("strings_e", (RStringList "stringsout", [String "encoding"; String "path"]), 95, [ProtocolLimitWarning],
2225    [InitBasicFS, Always, TestOutputList (
2226       [["write_file"; "/new"; "hello\nworld\n"; "0"];
2227        ["strings_e"; "b"; "/new"]], []);
2228     InitBasicFS, Disabled, TestOutputList (
2229       [["write_file"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"; "24"];
2230        ["strings_e"; "b"; "/new"]], ["hello"; "world"])],
2231    "print the printable strings in a file",
2232    "\
2233 This is like the C<guestfs_strings> command, but allows you to
2234 specify the encoding.
2235
2236 See the L<strings(1)> manpage for the full list of encodings.
2237
2238 Commonly useful encodings are C<l> (lower case L) which will
2239 show strings inside Windows/x86 files.
2240
2241 The returned strings are transcoded to UTF-8.");
2242
2243   ("hexdump", (RString "dump", [String "path"]), 96, [ProtocolLimitWarning],
2244    [InitBasicFS, Always, TestOutput (
2245       [["write_file"; "/new"; "hello\nworld\n"; "12"];
2246        ["hexdump"; "/new"]], "00000000  68 65 6c 6c 6f 0a 77 6f  72 6c 64 0a              |hello.world.|\n0000000c\n");
2247     (* Test for RHBZ#501888c2 regression which caused large hexdump
2248      * commands to segfault.
2249      *)
2250     InitBasicFS, Always, TestRun (
2251       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2252        ["hexdump"; "/100krandom"]])],
2253    "dump a file in hexadecimal",
2254    "\
2255 This runs C<hexdump -C> on the given C<path>.  The result is
2256 the human-readable, canonical hex dump of the file.");
2257
2258   ("zerofree", (RErr, [String "device"]), 97, [],
2259    [InitNone, Always, TestOutput (
2260       [["sfdiskM"; "/dev/sda"; ","];
2261        ["mkfs"; "ext3"; "/dev/sda1"];
2262        ["mount"; "/dev/sda1"; "/"];
2263        ["write_file"; "/new"; "test file"; "0"];
2264        ["umount"; "/dev/sda1"];
2265        ["zerofree"; "/dev/sda1"];
2266        ["mount"; "/dev/sda1"; "/"];
2267        ["cat"; "/new"]], "test file")],
2268    "zero unused inodes and disk blocks on ext2/3 filesystem",
2269    "\
2270 This runs the I<zerofree> program on C<device>.  This program
2271 claims to zero unused inodes and disk blocks on an ext2/3
2272 filesystem, thus making it possible to compress the filesystem
2273 more effectively.
2274
2275 You should B<not> run this program if the filesystem is
2276 mounted.
2277
2278 It is possible that using this program can damage the filesystem
2279 or data on the filesystem.");
2280
2281   ("pvresize", (RErr, [String "device"]), 98, [],
2282    [],
2283    "resize an LVM physical volume",
2284    "\
2285 This resizes (expands or shrinks) an existing LVM physical
2286 volume to match the new size of the underlying device.");
2287
2288   ("sfdisk_N", (RErr, [String "device"; Int "partnum";
2289                        Int "cyls"; Int "heads"; Int "sectors";
2290                        String "line"]), 99, [DangerWillRobinson],
2291    [],
2292    "modify a single partition on a block device",
2293    "\
2294 This runs L<sfdisk(8)> option to modify just the single
2295 partition C<n> (note: C<n> counts from 1).
2296
2297 For other parameters, see C<guestfs_sfdisk>.  You should usually
2298 pass C<0> for the cyls/heads/sectors parameters.");
2299
2300   ("sfdisk_l", (RString "partitions", [String "device"]), 100, [],
2301    [],
2302    "display the partition table",
2303    "\
2304 This displays the partition table on C<device>, in the
2305 human-readable output of the L<sfdisk(8)> command.  It is
2306 not intended to be parsed.");
2307
2308   ("sfdisk_kernel_geometry", (RString "partitions", [String "device"]), 101, [],
2309    [],
2310    "display the kernel geometry",
2311    "\
2312 This displays the kernel's idea of the geometry of C<device>.
2313
2314 The result is in human-readable format, and not designed to
2315 be parsed.");
2316
2317   ("sfdisk_disk_geometry", (RString "partitions", [String "device"]), 102, [],
2318    [],
2319    "display the disk geometry from the partition table",
2320    "\
2321 This displays the disk geometry of C<device> read from the
2322 partition table.  Especially in the case where the underlying
2323 block device has been resized, this can be different from the
2324 kernel's idea of the geometry (see C<guestfs_sfdisk_kernel_geometry>).
2325
2326 The result is in human-readable format, and not designed to
2327 be parsed.");
2328
2329   ("vg_activate_all", (RErr, [Bool "activate"]), 103, [],
2330    [],
2331    "activate or deactivate all volume groups",
2332    "\
2333 This command activates or (if C<activate> is false) deactivates
2334 all logical volumes in all volume groups.
2335 If activated, then they are made known to the
2336 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2337 then those devices disappear.
2338
2339 This command is the same as running C<vgchange -a y|n>");
2340
2341   ("vg_activate", (RErr, [Bool "activate"; StringList "volgroups"]), 104, [],
2342    [],
2343    "activate or deactivate some volume groups",
2344    "\
2345 This command activates or (if C<activate> is false) deactivates
2346 all logical volumes in the listed volume groups C<volgroups>.
2347 If activated, then they are made known to the
2348 kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
2349 then those devices disappear.
2350
2351 This command is the same as running C<vgchange -a y|n volgroups...>
2352
2353 Note that if C<volgroups> is an empty list then B<all> volume groups
2354 are activated or deactivated.");
2355
2356   ("lvresize", (RErr, [String "device"; Int "mbytes"]), 105, [],
2357    [InitNone, Always, TestOutput (
2358     [["sfdiskM"; "/dev/sda"; ","];
2359      ["pvcreate"; "/dev/sda1"];
2360      ["vgcreate"; "VG"; "/dev/sda1"];
2361      ["lvcreate"; "LV"; "VG"; "10"];
2362      ["mkfs"; "ext2"; "/dev/VG/LV"];
2363      ["mount"; "/dev/VG/LV"; "/"];
2364      ["write_file"; "/new"; "test content"; "0"];
2365      ["umount"; "/"];
2366      ["lvresize"; "/dev/VG/LV"; "20"];
2367      ["e2fsck_f"; "/dev/VG/LV"];
2368      ["resize2fs"; "/dev/VG/LV"];
2369      ["mount"; "/dev/VG/LV"; "/"];
2370      ["cat"; "/new"]], "test content")],
2371    "resize an LVM logical volume",
2372    "\
2373 This resizes (expands or shrinks) an existing LVM logical
2374 volume to C<mbytes>.  When reducing, data in the reduced part
2375 is lost.");
2376
2377   ("resize2fs", (RErr, [String "device"]), 106, [],
2378    [], (* lvresize tests this *)
2379    "resize an ext2/ext3 filesystem",
2380    "\
2381 This resizes an ext2 or ext3 filesystem to match the size of
2382 the underlying device.
2383
2384 I<Note:> It is sometimes required that you run C<guestfs_e2fsck_f>
2385 on the C<device> before calling this command.  For unknown reasons
2386 C<resize2fs> sometimes gives an error about this and sometimes not.
2387 In any case, it is always safe to call C<guestfs_e2fsck_f> before
2388 calling this function.");
2389
2390   ("find", (RStringList "names", [String "directory"]), 107, [],
2391    [InitBasicFS, Always, TestOutputList (
2392       [["find"; "/"]], ["lost+found"]);
2393     InitBasicFS, Always, TestOutputList (
2394       [["touch"; "/a"];
2395        ["mkdir"; "/b"];
2396        ["touch"; "/b/c"];
2397        ["find"; "/"]], ["a"; "b"; "b/c"; "lost+found"]);
2398     InitBasicFS, Always, TestOutputList (
2399       [["mkdir_p"; "/a/b/c"];
2400        ["touch"; "/a/b/c/d"];
2401        ["find"; "/a/b/"]], ["c"; "c/d"])],
2402    "find all files and directories",
2403    "\
2404 This command lists out all files and directories, recursively,
2405 starting at C<directory>.  It is essentially equivalent to
2406 running the shell command C<find directory -print> but some
2407 post-processing happens on the output, described below.
2408
2409 This returns a list of strings I<without any prefix>.  Thus
2410 if the directory structure was:
2411
2412  /tmp/a
2413  /tmp/b
2414  /tmp/c/d
2415
2416 then the returned list from C<guestfs_find> C</tmp> would be
2417 4 elements:
2418
2419  a
2420  b
2421  c
2422  c/d
2423
2424 If C<directory> is not a directory, then this command returns
2425 an error.
2426
2427 The returned list is sorted.");
2428
2429   ("e2fsck_f", (RErr, [String "device"]), 108, [],
2430    [], (* lvresize tests this *)
2431    "check an ext2/ext3 filesystem",
2432    "\
2433 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
2434 filesystem checker on C<device>, noninteractively (C<-p>),
2435 even if the filesystem appears to be clean (C<-f>).
2436
2437 This command is only needed because of C<guestfs_resize2fs>
2438 (q.v.).  Normally you should use C<guestfs_fsck>.");
2439
2440   ("sleep", (RErr, [Int "secs"]), 109, [],
2441    [InitNone, Always, TestRun (
2442     [["sleep"; "1"]])],
2443    "sleep for some seconds",
2444    "\
2445 Sleep for C<secs> seconds.");
2446
2447   ("ntfs_3g_probe", (RInt "status", [Bool "rw"; String "device"]), 110, [],
2448    [InitNone, Always, TestOutputInt (
2449       [["sfdiskM"; "/dev/sda"; ","];
2450        ["mkfs"; "ntfs"; "/dev/sda1"];
2451        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 0);
2452     InitNone, Always, TestOutputInt (
2453       [["sfdiskM"; "/dev/sda"; ","];
2454        ["mkfs"; "ext2"; "/dev/sda1"];
2455        ["ntfs_3g_probe"; "true"; "/dev/sda1"]], 12)],
2456    "probe NTFS volume",
2457    "\
2458 This command runs the L<ntfs-3g.probe(8)> command which probes
2459 an NTFS C<device> for mountability.  (Not all NTFS volumes can
2460 be mounted read-write, and some cannot be mounted at all).
2461
2462 C<rw> is a boolean flag.  Set it to true if you want to test
2463 if the volume can be mounted read-write.  Set it to false if
2464 you want to test if the volume can be mounted read-only.
2465
2466 The return value is an integer which C<0> if the operation
2467 would succeed, or some non-zero value documented in the
2468 L<ntfs-3g.probe(8)> manual page.");
2469
2470   ("sh", (RString "output", [String "command"]), 111, [],
2471    [], (* XXX needs tests *)
2472    "run a command via the shell",
2473    "\
2474 This call runs a command from the guest filesystem via the
2475 guest's C</bin/sh>.
2476
2477 This is like C<guestfs_command>, but passes the command to:
2478
2479  /bin/sh -c \"command\"
2480
2481 Depending on the guest's shell, this usually results in
2482 wildcards being expanded, shell expressions being interpolated
2483 and so on.
2484
2485 All the provisos about C<guestfs_command> apply to this call.");
2486
2487   ("sh_lines", (RStringList "lines", [String "command"]), 112, [],
2488    [], (* XXX needs tests *)
2489    "run a command via the shell returning lines",
2490    "\
2491 This is the same as C<guestfs_sh>, but splits the result
2492 into a list of lines.
2493
2494 See also: C<guestfs_command_lines>");
2495
2496   ("glob_expand", (RStringList "paths", [String "pattern"]), 113, [],
2497    [InitBasicFS, Always, TestOutputList (
2498       [["mkdir_p"; "/a/b/c"];
2499        ["touch"; "/a/b/c/d"];
2500        ["touch"; "/a/b/c/e"];
2501        ["glob_expand"; "/a/b/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2502     InitBasicFS, Always, TestOutputList (
2503       [["mkdir_p"; "/a/b/c"];
2504        ["touch"; "/a/b/c/d"];
2505        ["touch"; "/a/b/c/e"];
2506        ["glob_expand"; "/a/*/c/*"]], ["/a/b/c/d"; "/a/b/c/e"]);
2507     InitBasicFS, Always, TestOutputList (
2508       [["mkdir_p"; "/a/b/c"];
2509        ["touch"; "/a/b/c/d"];
2510        ["touch"; "/a/b/c/e"];
2511        ["glob_expand"; "/a/*/x/*"]], [])],
2512    "expand a wildcard path",
2513    "\
2514 This command searches for all the pathnames matching
2515 C<pattern> according to the wildcard expansion rules
2516 used by the shell.
2517
2518 If no paths match, then this returns an empty list
2519 (note: not an error).
2520
2521 It is just a wrapper around the C L<glob(3)> function
2522 with flags C<GLOB_MARK|GLOB_BRACE>.
2523 See that manual page for more details.");
2524
2525   ("scrub_device", (RErr, [String "device"]), 114, [DangerWillRobinson],
2526    [InitNone, Always, TestRun ( (* use /dev/sdc because it's smaller *)
2527       [["scrub_device"; "/dev/sdc"]])],
2528    "scrub (securely wipe) a device",
2529    "\
2530 This command writes patterns over C<device> to make data retrieval
2531 more difficult.
2532
2533 It is an interface to the L<scrub(1)> program.  See that
2534 manual page for more details.");
2535
2536   ("scrub_file", (RErr, [String "file"]), 115, [],
2537    [InitBasicFS, Always, TestRun (
2538       [["write_file"; "/file"; "content"; "0"];
2539        ["scrub_file"; "/file"]])],
2540    "scrub (securely wipe) a file",
2541    "\
2542 This command writes patterns over a file to make data retrieval
2543 more difficult.
2544
2545 The file is I<removed> after scrubbing.
2546
2547 It is an interface to the L<scrub(1)> program.  See that
2548 manual page for more details.");
2549
2550   ("scrub_freespace", (RErr, [String "dir"]), 116, [],
2551    [], (* XXX needs testing *)
2552    "scrub (securely wipe) free space",
2553    "\
2554 This command creates the directory C<dir> and then fills it
2555 with files until the filesystem is full, and scrubs the files
2556 as for C<guestfs_scrub_file>, and deletes them.
2557 The intention is to scrub any free space on the partition
2558 containing C<dir>.
2559
2560 It is an interface to the L<scrub(1)> program.  See that
2561 manual page for more details.");
2562
2563   ("mkdtemp", (RString "dir", [String "template"]), 117, [],
2564    [InitBasicFS, Always, TestRun (
2565       [["mkdir"; "/tmp"];
2566        ["mkdtemp"; "/tmp/tmpXXXXXX"]])],
2567    "create a temporary directory",
2568    "\
2569 This command creates a temporary directory.  The
2570 C<template> parameter should be a full pathname for the
2571 temporary directory name with the final six characters being
2572 \"XXXXXX\".
2573
2574 For example: \"/tmp/myprogXXXXXX\" or \"/Temp/myprogXXXXXX\",
2575 the second one being suitable for Windows filesystems.
2576
2577 The name of the temporary directory that was created
2578 is returned.
2579
2580 The temporary directory is created with mode 0700
2581 and is owned by root.
2582
2583 The caller is responsible for deleting the temporary
2584 directory and its contents after use.
2585
2586 See also: L<mkdtemp(3)>");
2587
2588   ("wc_l", (RInt "lines", [String "path"]), 118, [],
2589    [InitBasicFS, Always, TestOutputInt (
2590       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2591        ["wc_l"; "/10klines"]], 10000)],
2592    "count lines in a file",
2593    "\
2594 This command counts the lines in a file, using the
2595 C<wc -l> external command.");
2596
2597   ("wc_w", (RInt "words", [String "path"]), 119, [],
2598    [InitBasicFS, Always, TestOutputInt (
2599       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2600        ["wc_w"; "/10klines"]], 10000)],
2601    "count words in a file",
2602    "\
2603 This command counts the words in a file, using the
2604 C<wc -w> external command.");
2605
2606   ("wc_c", (RInt "chars", [String "path"]), 120, [],
2607    [InitBasicFS, Always, TestOutputInt (
2608       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2609        ["wc_c"; "/100kallspaces"]], 102400)],
2610    "count characters in a file",
2611    "\
2612 This command counts the characters in a file, using the
2613 C<wc -c> external command.");
2614
2615   ("head", (RStringList "lines", [String "path"]), 121, [ProtocolLimitWarning],
2616    [InitBasicFS, Always, TestOutputList (
2617       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2618        ["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])],
2619    "return first 10 lines of a file",
2620    "\
2621 This command returns up to the first 10 lines of a file as
2622 a list of strings.");
2623
2624   ("head_n", (RStringList "lines", [Int "nrlines"; String "path"]), 122, [ProtocolLimitWarning],
2625    [InitBasicFS, Always, TestOutputList (
2626       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2627        ["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
2628     InitBasicFS, Always, TestOutputList (
2629       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2630        ["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]);
2631     InitBasicFS, Always, TestOutputList (
2632       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2633        ["head_n"; "0"; "/10klines"]], [])],
2634    "return first N lines of a file",
2635    "\
2636 If the parameter C<nrlines> is a positive number, this returns the first
2637 C<nrlines> lines of the file C<path>.
2638
2639 If the parameter C<nrlines> is a negative number, this returns lines
2640 from the file C<path>, excluding the last C<nrlines> lines.
2641
2642 If the parameter C<nrlines> is zero, this returns an empty list.");
2643
2644   ("tail", (RStringList "lines", [String "path"]), 123, [ProtocolLimitWarning],
2645    [InitBasicFS, Always, TestOutputList (
2646       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2647        ["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])],
2648    "return last 10 lines of a file",
2649    "\
2650 This command returns up to the last 10 lines of a file as
2651 a list of strings.");
2652
2653   ("tail_n", (RStringList "lines", [Int "nrlines"; String "path"]), 124, [ProtocolLimitWarning],
2654    [InitBasicFS, Always, TestOutputList (
2655       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2656        ["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
2657     InitBasicFS, Always, TestOutputList (
2658       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2659        ["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]);
2660     InitBasicFS, Always, TestOutputList (
2661       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2662        ["tail_n"; "0"; "/10klines"]], [])],
2663    "return last N lines of a file",
2664    "\
2665 If the parameter C<nrlines> is a positive number, this returns the last
2666 C<nrlines> lines of the file C<path>.
2667
2668 If the parameter C<nrlines> is a negative number, this returns lines
2669 from the file C<path>, starting with the C<-nrlines>th line.
2670
2671 If the parameter C<nrlines> is zero, this returns an empty list.");
2672
2673   ("df", (RString "output", []), 125, [],
2674    [], (* XXX Tricky to test because it depends on the exact format
2675         * of the 'df' command and other imponderables.
2676         *)
2677    "report file system disk space usage",
2678    "\
2679 This command runs the C<df> command to report disk space used.
2680
2681 This command is mostly useful for interactive sessions.  It
2682 is I<not> intended that you try to parse the output string.
2683 Use C<statvfs> from programs.");
2684
2685   ("df_h", (RString "output", []), 126, [],
2686    [], (* XXX Tricky to test because it depends on the exact format
2687         * of the 'df' command and other imponderables.
2688         *)
2689    "report file system disk space usage (human readable)",
2690    "\
2691 This command runs the C<df -h> command to report disk space used
2692 in human-readable format.
2693
2694 This command is mostly useful for interactive sessions.  It
2695 is I<not> intended that you try to parse the output string.
2696 Use C<statvfs> from programs.");
2697
2698   ("du", (RInt64 "sizekb", [String "path"]), 127, [],
2699    [InitBasicFS, Always, TestOutputInt (
2700       [["mkdir"; "/p"];
2701        ["du"; "/p"]], 1 (* ie. 1 block, so depends on ext3 blocksize *))],
2702    "estimate file space usage",
2703    "\
2704 This command runs the C<du -s> command to estimate file space
2705 usage for C<path>.
2706
2707 C<path> can be a file or a directory.  If C<path> is a directory
2708 then the estimate includes the contents of the directory and all
2709 subdirectories (recursively).
2710
2711 The result is the estimated size in I<kilobytes>
2712 (ie. units of 1024 bytes).");
2713
2714   ("initrd_list", (RStringList "filenames", [String "path"]), 128, [],
2715    [InitBasicFS, Always, TestOutputList (
2716       [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"];
2717        ["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3"])],
2718    "list files in an initrd",
2719    "\
2720 This command lists out files contained in an initrd.
2721
2722 The files are listed without any initial C</> character.  The
2723 files are listed in the order they appear (not necessarily
2724 alphabetical).  Directory names are listed as separate items.
2725
2726 Old Linux kernels (2.4 and earlier) used a compressed ext2
2727 filesystem as initrd.  We I<only> support the newer initramfs
2728 format (compressed cpio files).");
2729
2730   ("mount_loop", (RErr, [String "file"; String "mountpoint"]), 129, [],
2731    [],
2732    "mount a file using the loop device",
2733    "\
2734 This command lets you mount C<file> (a filesystem image
2735 in a file) on a mount point.  It is entirely equivalent to
2736 the command C<mount -o loop file mountpoint>.");
2737
2738   ("mkswap", (RErr, [String "device"]), 130, [],
2739    [InitEmpty, Always, TestRun (
2740       [["sfdiskM"; "/dev/sda"; ","];
2741        ["mkswap"; "/dev/sda1"]])],
2742    "create a swap partition",
2743    "\
2744 Create a swap partition on C<device>.");
2745
2746   ("mkswap_L", (RErr, [String "label"; String "device"]), 131, [],
2747    [InitEmpty, Always, TestRun (
2748       [["sfdiskM"; "/dev/sda"; ","];
2749        ["mkswap_L"; "hello"; "/dev/sda1"]])],
2750    "create a swap partition with a label",
2751    "\
2752 Create a swap partition on C<device> with label C<label>.");
2753
2754   ("mkswap_U", (RErr, [String "uuid"; String "device"]), 132, [],
2755    [InitEmpty, Always, TestRun (
2756       [["sfdiskM"; "/dev/sda"; ","];
2757        ["mkswap_U"; "a3a61220-882b-4f61-89f4-cf24dcc7297d"; "/dev/sda1"]])],
2758    "create a swap partition with an explicit UUID",
2759    "\
2760 Create a swap partition on C<device> with UUID C<uuid>.");
2761
2762   ("mknod", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; String "path"]), 133, [],
2763    [InitBasicFS, Always, TestOutputStruct (
2764       [["mknod"; "0o10777"; "0"; "0"; "/node"];
2765        (* NB: default umask 022 means 0777 -> 0755 in these tests *)
2766        ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)]);
2767     InitBasicFS, Always, TestOutputStruct (
2768       [["mknod"; "0o60777"; "66"; "99"; "/node"];
2769        ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
2770    "make block, character or FIFO devices",
2771    "\
2772 This call creates block or character special devices, or
2773 named pipes (FIFOs).
2774
2775 The C<mode> parameter should be the mode, using the standard
2776 constants.  C<devmajor> and C<devminor> are the
2777 device major and minor numbers, only used when creating block
2778 and character special devices.");
2779
2780   ("mkfifo", (RErr, [Int "mode"; String "path"]), 134, [],
2781    [InitBasicFS, Always, TestOutputStruct (
2782       [["mkfifo"; "0o777"; "/node"];
2783        ["stat"; "/node"]], [CompareWithInt ("mode", 0o10755)])],
2784    "make FIFO (named pipe)",
2785    "\
2786 This call creates a FIFO (named pipe) called C<path> with
2787 mode C<mode>.  It is just a convenient wrapper around
2788 C<guestfs_mknod>.");
2789
2790   ("mknod_b", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; String "path"]), 135, [],
2791    [InitBasicFS, Always, TestOutputStruct (
2792       [["mknod_b"; "0o777"; "99"; "66"; "/node"];
2793        ["stat"; "/node"]], [CompareWithInt ("mode", 0o60755)])],
2794    "make block device node",
2795    "\
2796 This call creates a block device node called C<path> with
2797 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
2798 It is just a convenient wrapper around C<guestfs_mknod>.");
2799
2800   ("mknod_c", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; String "path"]), 136, [],
2801    [InitBasicFS, Always, TestOutputStruct (
2802       [["mknod_c"; "0o777"; "99"; "66"; "/node"];
2803        ["stat"; "/node"]], [CompareWithInt ("mode", 0o20755)])],
2804    "make char device node",
2805    "\
2806 This call creates a char device node called C<path> with
2807 mode C<mode> and device major/minor C<devmajor> and C<devminor>.
2808 It is just a convenient wrapper around C<guestfs_mknod>.");
2809
2810   ("umask", (RInt "oldmask", [Int "mask"]), 137, [],
2811    [], (* XXX umask is one of those stateful things that we should
2812         * reset between each test.
2813         *)
2814    "set file mode creation mask (umask)",
2815    "\
2816 This function sets the mask used for creating new files and
2817 device nodes to C<mask & 0777>.
2818
2819 Typical umask values would be C<022> which creates new files
2820 with permissions like \"-rw-r--r--\" or \"-rwxr-xr-x\", and
2821 C<002> which creates new files with permissions like
2822 \"-rw-rw-r--\" or \"-rwxrwxr-x\".
2823
2824 The default umask is C<022>.  This is important because it
2825 means that directories and device nodes will be created with
2826 C<0644> or C<0755> mode even if you specify C<0777>.
2827
2828 See also L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
2829
2830 This call returns the previous umask.");
2831
2832   ("readdir", (RStructList ("entries", "dirent"), [String "dir"]), 138, [],
2833    [],
2834    "read directories entries",
2835    "\
2836 This returns the list of directory entries in directory C<dir>.
2837
2838 All entries in the directory are returned, including C<.> and
2839 C<..>.  The entries are I<not> sorted, but returned in the same
2840 order as the underlying filesystem.
2841
2842 This function is primarily intended for use by programs.  To
2843 get a simple list of names, use C<guestfs_ls>.  To get a printable
2844 directory for human consumption, use C<guestfs_ll>.");
2845
2846   ("sfdiskM", (RErr, [String "device"; StringList "lines"]), 139, [DangerWillRobinson],
2847    [],
2848    "create partitions on a block device",
2849    "\
2850 This is a simplified interface to the C<guestfs_sfdisk>
2851 command, where partition sizes are specified in megabytes
2852 only (rounded to the nearest cylinder) and you don't need
2853 to specify the cyls, heads and sectors parameters which
2854 were rarely if ever used anyway.
2855
2856 See also C<guestfs_sfdisk> and the L<sfdisk(8)> manpage.");
2857
2858 ]
2859
2860 let all_functions = non_daemon_functions @ daemon_functions
2861
2862 (* In some places we want the functions to be displayed sorted
2863  * alphabetically, so this is useful:
2864  *)
2865 let all_functions_sorted =
2866   List.sort (fun (n1,_,_,_,_,_,_) (n2,_,_,_,_,_,_) ->
2867                compare n1 n2) all_functions
2868
2869 (* Field types for structures. *)
2870 type field =
2871   | FChar                       (* C 'char' (really, a 7 bit byte). *)
2872   | FString                     (* nul-terminated ASCII string. *)
2873   | FUInt32
2874   | FInt32
2875   | FUInt64
2876   | FInt64
2877   | FBytes                      (* Any int measure that counts bytes. *)
2878   | FUUID                       (* 32 bytes long, NOT nul-terminated. *)
2879   | FOptPercent                 (* [0..100], or -1 meaning "not present". *)
2880
2881 (* Because we generate extra parsing code for LVM command line tools,
2882  * we have to pull out the LVM columns separately here.
2883  *)
2884 let lvm_pv_cols = [
2885   "pv_name", FString;
2886   "pv_uuid", FUUID;
2887   "pv_fmt", FString;
2888   "pv_size", FBytes;
2889   "dev_size", FBytes;
2890   "pv_free", FBytes;
2891   "pv_used", FBytes;
2892   "pv_attr", FString (* XXX *);
2893   "pv_pe_count", FInt64;
2894   "pv_pe_alloc_count", FInt64;
2895   "pv_tags", FString;
2896   "pe_start", FBytes;
2897   "pv_mda_count", FInt64;
2898   "pv_mda_free", FBytes;
2899   (* Not in Fedora 10:
2900      "pv_mda_size", FBytes;
2901   *)
2902 ]
2903 let lvm_vg_cols = [
2904   "vg_name", FString;
2905   "vg_uuid", FUUID;
2906   "vg_fmt", FString;
2907   "vg_attr", FString (* XXX *);
2908   "vg_size", FBytes;
2909   "vg_free", FBytes;
2910   "vg_sysid", FString;
2911   "vg_extent_size", FBytes;
2912   "vg_extent_count", FInt64;
2913   "vg_free_count", FInt64;
2914   "max_lv", FInt64;
2915   "max_pv", FInt64;
2916   "pv_count", FInt64;
2917   "lv_count", FInt64;
2918   "snap_count", FInt64;
2919   "vg_seqno", FInt64;
2920   "vg_tags", FString;
2921   "vg_mda_count", FInt64;
2922   "vg_mda_free", FBytes;
2923   (* Not in Fedora 10:
2924      "vg_mda_size", FBytes;
2925   *)
2926 ]
2927 let lvm_lv_cols = [
2928   "lv_name", FString;
2929   "lv_uuid", FUUID;
2930   "lv_attr", FString (* XXX *);
2931   "lv_major", FInt64;
2932   "lv_minor", FInt64;
2933   "lv_kernel_major", FInt64;
2934   "lv_kernel_minor", FInt64;
2935   "lv_size", FBytes;
2936   "seg_count", FInt64;
2937   "origin", FString;
2938   "snap_percent", FOptPercent;
2939   "copy_percent", FOptPercent;
2940   "move_pv", FString;
2941   "lv_tags", FString;
2942   "mirror_log", FString;
2943   "modules", FString;
2944 ]
2945
2946 (* Names and fields in all structures (in RStruct and RStructList)
2947  * that we support.
2948  *)
2949 let structs = [
2950   (* The old RIntBool return type, only ever used for aug_defnode.  Do
2951    * not use this struct in any new code.
2952    *)
2953   "int_bool", [
2954     "i", FInt32;                (* for historical compatibility *)
2955     "b", FInt32;                (* for historical compatibility *)
2956   ];
2957
2958   (* LVM PVs, VGs, LVs. *)
2959   "lvm_pv", lvm_pv_cols;
2960   "lvm_vg", lvm_vg_cols;
2961   "lvm_lv", lvm_lv_cols;
2962
2963   (* Column names and types from stat structures.
2964    * NB. Can't use things like 'st_atime' because glibc header files
2965    * define some of these as macros.  Ugh.
2966    *)
2967   "stat", [
2968     "dev", FInt64;
2969     "ino", FInt64;
2970     "mode", FInt64;
2971     "nlink", FInt64;
2972     "uid", FInt64;
2973     "gid", FInt64;
2974     "rdev", FInt64;
2975     "size", FInt64;
2976     "blksize", FInt64;
2977     "blocks", FInt64;
2978     "atime", FInt64;
2979     "mtime", FInt64;
2980     "ctime", FInt64;
2981   ];
2982   "statvfs", [
2983     "bsize", FInt64;
2984     "frsize", FInt64;
2985     "blocks", FInt64;
2986     "bfree", FInt64;
2987     "bavail", FInt64;
2988     "files", FInt64;
2989     "ffree", FInt64;
2990     "favail", FInt64;
2991     "fsid", FInt64;
2992     "flag", FInt64;
2993     "namemax", FInt64;
2994   ];
2995
2996   (* Column names in dirent structure. *)
2997   "dirent", [
2998     "ino", FInt64;
2999     (* 'b' 'c' 'd' 'f' (FIFO) 'l' 'r' (regular file) 's' 'u' '?' *)
3000     "ftyp", FChar;
3001     "name", FString;
3002   ];
3003
3004   (* Version numbers. *)
3005   "version", [
3006     "major", FInt64;
3007     "minor", FInt64;
3008     "release", FInt64;
3009     "extra", FString;
3010   ];
3011 ] (* end of structs *)
3012
3013 (* Ugh, Java has to be different ..
3014  * These names are also used by the Haskell bindings.
3015  *)
3016 let java_structs = [
3017   "int_bool", "IntBool";
3018   "lvm_pv", "PV";
3019   "lvm_vg", "VG";
3020   "lvm_lv", "LV";
3021   "stat", "Stat";
3022   "statvfs", "StatVFS";
3023   "dirent", "Dirent";
3024   "version", "Version";
3025 ]
3026
3027 (* Used for testing language bindings. *)
3028 type callt =
3029   | CallString of string
3030   | CallOptString of string option
3031   | CallStringList of string list
3032   | CallInt of int
3033   | CallBool of bool
3034
3035 (* Used to memoize the result of pod2text. *)
3036 let pod2text_memo_filename = "src/.pod2text.data"
3037 let pod2text_memo : ((int * string * string), string list) Hashtbl.t =
3038   try
3039     let chan = open_in pod2text_memo_filename in
3040     let v = input_value chan in
3041     close_in chan;
3042     v
3043   with
3044     _ -> Hashtbl.create 13
3045
3046 (* Useful functions.
3047  * Note we don't want to use any external OCaml libraries which
3048  * makes this a bit harder than it should be.
3049  *)
3050 let failwithf fs = ksprintf failwith fs
3051
3052 let replace_char s c1 c2 =
3053   let s2 = String.copy s in
3054   let r = ref false in
3055   for i = 0 to String.length s2 - 1 do
3056     if String.unsafe_get s2 i = c1 then (
3057       String.unsafe_set s2 i c2;
3058       r := true
3059     )
3060   done;
3061   if not !r then s else s2
3062
3063 let isspace c =
3064   c = ' '
3065   (* || c = '\f' *) || c = '\n' || c = '\r' || c = '\t' (* || c = '\v' *)
3066
3067 let triml ?(test = isspace) str =
3068   let i = ref 0 in
3069   let n = ref (String.length str) in
3070   while !n > 0 && test str.[!i]; do
3071     decr n;
3072     incr i
3073   done;
3074   if !i = 0 then str
3075   else String.sub str !i !n
3076
3077 let trimr ?(test = isspace) str =
3078   let n = ref (String.length str) in
3079   while !n > 0 && test str.[!n-1]; do
3080     decr n
3081   done;
3082   if !n = String.length str then str
3083   else String.sub str 0 !n
3084
3085 let trim ?(test = isspace) str =
3086   trimr ~test (triml ~test str)
3087
3088 let rec find s sub =
3089   let len = String.length s in
3090   let sublen = String.length sub in
3091   let rec loop i =
3092     if i <= len-sublen then (
3093       let rec loop2 j =
3094         if j < sublen then (
3095           if s.[i+j] = sub.[j] then loop2 (j+1)
3096           else -1
3097         ) else
3098           i (* found *)
3099       in
3100       let r = loop2 0 in
3101       if r = -1 then loop (i+1) else r
3102     ) else
3103       -1 (* not found *)
3104   in
3105   loop 0
3106
3107 let rec replace_str s s1 s2 =
3108   let len = String.length s in
3109   let sublen = String.length s1 in
3110   let i = find s s1 in
3111   if i = -1 then s
3112   else (
3113     let s' = String.sub s 0 i in
3114     let s'' = String.sub s (i+sublen) (len-i-sublen) in
3115     s' ^ s2 ^ replace_str s'' s1 s2
3116   )
3117
3118 let rec string_split sep str =
3119   let len = String.length str in
3120   let seplen = String.length sep in
3121   let i = find str sep in
3122   if i = -1 then [str]
3123   else (
3124     let s' = String.sub str 0 i in
3125     let s'' = String.sub str (i+seplen) (len-i-seplen) in
3126     s' :: string_split sep s''
3127   )
3128
3129 let files_equal n1 n2 =
3130   let cmd = sprintf "cmp -s %s %s" (Filename.quote n1) (Filename.quote n2) in
3131   match Sys.command cmd with
3132   | 0 -> true
3133   | 1 -> false
3134   | i -> failwithf "%s: failed with error code %d" cmd i
3135
3136 let rec find_map f = function
3137   | [] -> raise Not_found
3138   | x :: xs ->
3139       match f x with
3140       | Some y -> y
3141       | None -> find_map f xs
3142
3143 let iteri f xs =
3144   let rec loop i = function
3145     | [] -> ()
3146     | x :: xs -> f i x; loop (i+1) xs
3147   in
3148   loop 0 xs
3149
3150 let mapi f xs =
3151   let rec loop i = function
3152     | [] -> []
3153     | x :: xs -> let r = f i x in r :: loop (i+1) xs
3154   in
3155   loop 0 xs
3156
3157 let name_of_argt = function
3158   | String n | OptString n | StringList n | Bool n | Int n
3159   | FileIn n | FileOut n -> n
3160
3161 let java_name_of_struct typ =
3162   try List.assoc typ java_structs
3163   with Not_found ->
3164     failwithf
3165       "java_name_of_struct: no java_structs entry corresponding to %s" typ
3166
3167 let cols_of_struct typ =
3168   try List.assoc typ structs
3169   with Not_found ->
3170     failwithf "cols_of_struct: unknown struct %s" typ
3171
3172 let seq_of_test = function
3173   | TestRun s | TestOutput (s, _) | TestOutputList (s, _)
3174   | TestOutputListOfDevices (s, _)
3175   | TestOutputInt (s, _) | TestOutputIntOp (s, _, _)
3176   | TestOutputTrue s | TestOutputFalse s
3177   | TestOutputLength (s, _) | TestOutputStruct (s, _)
3178   | TestLastFail s -> s
3179
3180 (* Check function names etc. for consistency. *)
3181 let check_functions () =
3182   let contains_uppercase str =
3183     let len = String.length str in
3184     let rec loop i =
3185       if i >= len then false
3186       else (
3187         let c = str.[i] in
3188         if c >= 'A' && c <= 'Z' then true
3189         else loop (i+1)
3190       )
3191     in
3192     loop 0
3193   in
3194
3195   (* Check function names. *)
3196   List.iter (
3197     fun (name, _, _, _, _, _, _) ->
3198       if String.length name >= 7 && String.sub name 0 7 = "guestfs" then
3199         failwithf "function name %s does not need 'guestfs' prefix" name;
3200       if name = "" then
3201         failwithf "function name is empty";
3202       if name.[0] < 'a' || name.[0] > 'z' then
3203         failwithf "function name %s must start with lowercase a-z" name;
3204       if String.contains name '-' then
3205         failwithf "function name %s should not contain '-', use '_' instead."
3206           name
3207   ) all_functions;
3208
3209   (* Check function parameter/return names. *)
3210   List.iter (
3211     fun (name, style, _, _, _, _, _) ->
3212       let check_arg_ret_name n =
3213         if contains_uppercase n then
3214           failwithf "%s param/ret %s should not contain uppercase chars"
3215             name n;
3216         if String.contains n '-' || String.contains n '_' then
3217           failwithf "%s param/ret %s should not contain '-' or '_'"
3218             name n;
3219         if n = "value" then
3220           failwithf "%s has a param/ret called 'value', which causes conflicts in the OCaml bindings, use something like 'val' or a more descriptive name" name;
3221         if n = "int" || n = "char" || n = "short" || n = "long" then
3222           failwithf "%s has a param/ret which conflicts with a C type (eg. 'int', 'char' etc.)" name;
3223         if n = "i" || n = "n" then
3224           failwithf "%s has a param/ret called 'i' or 'n', which will cause some conflicts in the generated code" name;
3225         if n = "argv" || n = "args" then
3226           failwithf "%s has a param/ret called 'argv' or 'args', which will cause some conflicts in the generated code" name
3227       in
3228
3229       (match fst style with
3230        | RErr -> ()
3231        | RInt n | RInt64 n | RBool n | RConstString n | RString n
3232        | RStringList n | RStruct (n, _) | RStructList (n, _)
3233        | RHashtable n ->
3234            check_arg_ret_name n
3235       );
3236       List.iter (fun arg -> check_arg_ret_name (name_of_argt arg)) (snd style)
3237   ) all_functions;
3238
3239   (* Check short descriptions. *)
3240   List.iter (
3241     fun (name, _, _, _, _, shortdesc, _) ->
3242       if shortdesc.[0] <> Char.lowercase shortdesc.[0] then
3243         failwithf "short description of %s should begin with lowercase." name;
3244       let c = shortdesc.[String.length shortdesc-1] in
3245       if c = '\n' || c = '.' then
3246         failwithf "short description of %s should not end with . or \\n." name
3247   ) all_functions;
3248
3249   (* Check long dscriptions. *)
3250   List.iter (
3251     fun (name, _, _, _, _, _, longdesc) ->
3252       if longdesc.[String.length longdesc-1] = '\n' then
3253         failwithf "long description of %s should not end with \\n." name
3254   ) all_functions;
3255
3256   (* Check proc_nrs. *)
3257   List.iter (
3258     fun (name, _, proc_nr, _, _, _, _) ->
3259       if proc_nr <= 0 then
3260         failwithf "daemon function %s should have proc_nr > 0" name
3261   ) daemon_functions;
3262
3263   List.iter (
3264     fun (name, _, proc_nr, _, _, _, _) ->
3265       if proc_nr <> -1 then
3266         failwithf "non-daemon function %s should have proc_nr -1" name
3267   ) non_daemon_functions;
3268
3269   let proc_nrs =
3270     List.map (fun (name, _, proc_nr, _, _, _, _) -> name, proc_nr)
3271       daemon_functions in
3272   let proc_nrs =
3273     List.sort (fun (_,nr1) (_,nr2) -> compare nr1 nr2) proc_nrs in
3274   let rec loop = function
3275     | [] -> ()
3276     | [_] -> ()
3277     | (name1,nr1) :: ((name2,nr2) :: _ as rest) when nr1 < nr2 ->
3278         loop rest
3279     | (name1,nr1) :: (name2,nr2) :: _ ->
3280         failwithf "%s and %s have conflicting procedure numbers (%d, %d)"
3281           name1 name2 nr1 nr2
3282   in
3283   loop proc_nrs;
3284
3285   (* Check tests. *)
3286   List.iter (
3287     function
3288       (* Ignore functions that have no tests.  We generate a
3289        * warning when the user does 'make check' instead.
3290        *)
3291     | name, _, _, _, [], _, _ -> ()
3292     | name, _, _, _, tests, _, _ ->
3293         let funcs =
3294           List.map (
3295             fun (_, _, test) ->
3296               match seq_of_test test with
3297               | [] ->
3298                   failwithf "%s has a test containing an empty sequence" name
3299               | cmds -> List.map List.hd cmds
3300           ) tests in
3301         let funcs = List.flatten funcs in
3302
3303         let tested = List.mem name funcs in
3304
3305         if not tested then
3306           failwithf "function %s has tests but does not test itself" name
3307   ) all_functions
3308
3309 (* 'pr' prints to the current output file. *)
3310 let chan = ref stdout
3311 let pr fs = ksprintf (output_string !chan) fs
3312
3313 (* Generate a header block in a number of standard styles. *)
3314 type comment_style = CStyle | HashStyle | OCamlStyle | HaskellStyle
3315 type license = GPLv2 | LGPLv2
3316
3317 let generate_header comment license =
3318   let c = match comment with
3319     | CStyle ->     pr "/* "; " *"
3320     | HashStyle ->  pr "# ";  "#"
3321     | OCamlStyle -> pr "(* "; " *"
3322     | HaskellStyle -> pr "{- "; "  " in
3323   pr "libguestfs generated file\n";
3324   pr "%s WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.\n" c;
3325   pr "%s ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.\n" c;
3326   pr "%s\n" c;
3327   pr "%s Copyright (C) 2009 Red Hat Inc.\n" c;
3328   pr "%s\n" c;
3329   (match license with
3330    | GPLv2 ->
3331        pr "%s This program is free software; you can redistribute it and/or modify\n" c;
3332        pr "%s it under the terms of the GNU General Public License as published by\n" c;
3333        pr "%s the Free Software Foundation; either version 2 of the License, or\n" c;
3334        pr "%s (at your option) any later version.\n" c;
3335        pr "%s\n" c;
3336        pr "%s This program is distributed in the hope that it will be useful,\n" c;
3337        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
3338        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n" c;
3339        pr "%s GNU General Public License for more details.\n" c;
3340        pr "%s\n" c;
3341        pr "%s You should have received a copy of the GNU General Public License along\n" c;
3342        pr "%s with this program; if not, write to the Free Software Foundation, Inc.,\n" c;
3343        pr "%s 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n" c;
3344
3345    | LGPLv2 ->
3346        pr "%s This library is free software; you can redistribute it and/or\n" c;
3347        pr "%s modify it under the terms of the GNU Lesser General Public\n" c;
3348        pr "%s License as published by the Free Software Foundation; either\n" c;
3349        pr "%s version 2 of the License, or (at your option) any later version.\n" c;
3350        pr "%s\n" c;
3351        pr "%s This library is distributed in the hope that it will be useful,\n" c;
3352        pr "%s but WITHOUT ANY WARRANTY; without even the implied warranty of\n" c;
3353        pr "%s MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\n" c;
3354        pr "%s Lesser General Public License for more details.\n" c;
3355        pr "%s\n" c;
3356        pr "%s You should have received a copy of the GNU Lesser General Public\n" c;
3357        pr "%s License along with this library; if not, write to the Free Software\n" c;
3358        pr "%s Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA\n" c;
3359   );
3360   (match comment with
3361    | CStyle -> pr " */\n"
3362    | HashStyle -> ()
3363    | OCamlStyle -> pr " *)\n"
3364    | HaskellStyle -> pr "-}\n"
3365   );
3366   pr "\n"
3367
3368 (* Start of main code generation functions below this line. *)
3369
3370 (* Generate the pod documentation for the C API. *)
3371 let rec generate_actions_pod () =
3372   List.iter (
3373     fun (shortname, style, _, flags, _, _, longdesc) ->
3374       if not (List.mem NotInDocs flags) then (
3375         let name = "guestfs_" ^ shortname in
3376         pr "=head2 %s\n\n" name;
3377         pr " ";
3378         generate_prototype ~extern:false ~handle:"handle" name style;
3379         pr "\n\n";
3380         pr "%s\n\n" longdesc;
3381         (match fst style with
3382          | RErr ->
3383              pr "This function returns 0 on success or -1 on error.\n\n"
3384          | RInt _ ->
3385              pr "On error this function returns -1.\n\n"
3386          | RInt64 _ ->
3387              pr "On error this function returns -1.\n\n"
3388          | RBool _ ->
3389              pr "This function returns a C truth value on success or -1 on error.\n\n"
3390          | RConstString _ ->
3391              pr "This function returns a string, or NULL on error.
3392 The string is owned by the guest handle and must I<not> be freed.\n\n"
3393          | RString _ ->
3394              pr "This function returns a string, or NULL on error.
3395 I<The caller must free the returned string after use>.\n\n"
3396          | RStringList _ ->
3397              pr "This function returns a NULL-terminated array of strings
3398 (like L<environ(3)>), or NULL if there was an error.
3399 I<The caller must free the strings and the array after use>.\n\n"
3400          | RStruct (_, typ) ->
3401              pr "This function returns a C<struct guestfs_%s *>,
3402 or NULL if there was an error.
3403 I<The caller must call C<guestfs_free_%s> after use>.\n\n" typ typ
3404          | RStructList (_, typ) ->
3405              pr "This function returns a C<struct guestfs_%s_list *>
3406 (see E<lt>guestfs-structs.hE<gt>),
3407 or NULL if there was an error.
3408 I<The caller must call C<guestfs_free_%s_list> after use>.\n\n" typ typ
3409          | RHashtable _ ->
3410              pr "This function returns a NULL-terminated array of
3411 strings, or NULL if there was an error.
3412 The array of strings will always have length C<2n+1>, where
3413 C<n> keys and values alternate, followed by the trailing NULL entry.
3414 I<The caller must free the strings and the array after use>.\n\n"
3415         );
3416         if List.mem ProtocolLimitWarning flags then
3417           pr "%s\n\n" protocol_limit_warning;
3418         if List.mem DangerWillRobinson flags then
3419           pr "%s\n\n" danger_will_robinson
3420       )
3421   ) all_functions_sorted
3422
3423 and generate_structs_pod () =
3424   (* Structs documentation. *)
3425   List.iter (
3426     fun (typ, cols) ->
3427       pr "=head2 guestfs_%s\n" typ;
3428       pr "\n";
3429       pr " struct guestfs_%s {\n" typ;
3430       List.iter (
3431         function
3432         | name, FChar -> pr "   char %s;\n" name
3433         | name, FUInt32 -> pr "   uint32_t %s;\n" name
3434         | name, FInt32 -> pr "   int32_t %s;\n" name
3435         | name, (FUInt64|FBytes) -> pr "   uint64_t %s;\n" name
3436         | name, FInt64 -> pr "   int64_t %s;\n" name
3437         | name, FString -> pr "   char *%s;\n" name
3438         | name, FUUID ->
3439             pr "   /* The next field is NOT nul-terminated, be careful when printing it: */\n";
3440             pr "   char %s[32];\n" name
3441         | name, FOptPercent ->
3442             pr "   /* The next field is [0..100] or -1 meaning 'not present': */\n";
3443             pr "   float %s;\n" name
3444       ) cols;
3445       pr " };\n";
3446       pr " \n";
3447       pr " struct guestfs_%s_list {\n" typ;
3448       pr "   uint32_t len; /* Number of elements in list. */\n";
3449       pr "   struct guestfs_%s *val; /* Elements. */\n" typ;
3450       pr " };\n";
3451       pr " \n";
3452       pr " void guestfs_free_%s (struct guestfs_free_%s *);\n" typ typ;
3453       pr " void guestfs_free_%s_list (struct guestfs_free_%s_list *);\n"
3454         typ typ;
3455       pr "\n"
3456   ) structs
3457
3458 (* Generate the protocol (XDR) file, 'guestfs_protocol.x' and
3459  * indirectly 'guestfs_protocol.h' and 'guestfs_protocol.c'.
3460  *
3461  * We have to use an underscore instead of a dash because otherwise
3462  * rpcgen generates incorrect code.
3463  *
3464  * This header is NOT exported to clients, but see also generate_structs_h.
3465  *)
3466 and generate_xdr () =
3467   generate_header CStyle LGPLv2;
3468
3469   (* This has to be defined to get around a limitation in Sun's rpcgen. *)
3470   pr "typedef string str<>;\n";
3471   pr "\n";
3472
3473   (* Internal structures. *)
3474   List.iter (
3475     function
3476     | typ, cols ->
3477         pr "struct guestfs_int_%s {\n" typ;
3478         List.iter (function
3479                    | name, FChar -> pr "  char %s;\n" name
3480                    | name, FString -> pr "  string %s<>;\n" name
3481                    | name, FUUID -> pr "  opaque %s[32];\n" name
3482                    | name, (FInt32|FUInt32) -> pr "  int %s;\n" name
3483                    | name, (FInt64|FUInt64|FBytes) -> pr "  hyper %s;\n" name
3484                    | name, FOptPercent -> pr "  float %s;\n" name
3485                   ) cols;
3486         pr "};\n";
3487         pr "\n";
3488         pr "typedef struct guestfs_int_%s guestfs_int_%s_list<>;\n" typ typ;
3489         pr "\n";
3490   ) structs;
3491
3492   List.iter (
3493     fun (shortname, style, _, _, _, _, _) ->
3494       let name = "guestfs_" ^ shortname in
3495
3496       (match snd style with
3497        | [] -> ()
3498        | args ->
3499            pr "struct %s_args {\n" name;
3500            List.iter (
3501              function
3502              | String n -> pr "  string %s<>;\n" n
3503              | OptString n -> pr "  str *%s;\n" n
3504              | StringList n -> pr "  str %s<>;\n" n
3505              | Bool n -> pr "  bool %s;\n" n
3506              | Int n -> pr "  int %s;\n" n
3507              | FileIn _ | FileOut _ -> ()
3508            ) args;
3509            pr "};\n\n"
3510       );
3511       (match fst style with
3512        | RErr -> ()
3513        | RInt n ->
3514            pr "struct %s_ret {\n" name;
3515            pr "  int %s;\n" n;
3516            pr "};\n\n"
3517        | RInt64 n ->
3518            pr "struct %s_ret {\n" name;
3519            pr "  hyper %s;\n" n;
3520            pr "};\n\n"
3521        | RBool n ->
3522            pr "struct %s_ret {\n" name;
3523            pr "  bool %s;\n" n;
3524            pr "};\n\n"
3525        | RConstString _ ->
3526            failwithf "RConstString cannot be returned from a daemon function"
3527        | RString n ->
3528            pr "struct %s_ret {\n" name;
3529            pr "  string %s<>;\n" n;
3530            pr "};\n\n"
3531        | RStringList n ->
3532            pr "struct %s_ret {\n" name;
3533            pr "  str %s<>;\n" n;
3534            pr "};\n\n"
3535        | RStruct (n, typ) ->
3536            pr "struct %s_ret {\n" name;
3537            pr "  guestfs_int_%s %s;\n" typ n;
3538            pr "};\n\n"
3539        | RStructList (n, typ) ->
3540            pr "struct %s_ret {\n" name;
3541            pr "  guestfs_int_%s_list %s;\n" typ n;
3542            pr "};\n\n"
3543        | RHashtable n ->
3544            pr "struct %s_ret {\n" name;
3545            pr "  str %s<>;\n" n;
3546            pr "};\n\n"
3547       );
3548   ) daemon_functions;
3549
3550   (* Table of procedure numbers. *)
3551   pr "enum guestfs_procedure {\n";
3552   List.iter (
3553     fun (shortname, _, proc_nr, _, _, _, _) ->
3554       pr "  GUESTFS_PROC_%s = %d,\n" (String.uppercase shortname) proc_nr
3555   ) daemon_functions;
3556   pr "  GUESTFS_PROC_NR_PROCS\n";
3557   pr "};\n";
3558   pr "\n";
3559
3560   (* Having to choose a maximum message size is annoying for several
3561    * reasons (it limits what we can do in the API), but it (a) makes
3562    * the protocol a lot simpler, and (b) provides a bound on the size
3563    * of the daemon which operates in limited memory space.  For large
3564    * file transfers you should use FTP.
3565    *)
3566   pr "const GUESTFS_MESSAGE_MAX = %d;\n" (4 * 1024 * 1024);
3567   pr "\n";
3568
3569   (* Message header, etc. *)
3570   pr "\
3571 /* The communication protocol is now documented in the guestfs(3)
3572  * manpage.
3573  */
3574
3575 const GUESTFS_PROGRAM = 0x2000F5F5;
3576 const GUESTFS_PROTOCOL_VERSION = 1;
3577
3578 /* These constants must be larger than any possible message length. */
3579 const GUESTFS_LAUNCH_FLAG = 0xf5f55ff5;
3580 const GUESTFS_CANCEL_FLAG = 0xffffeeee;
3581
3582 enum guestfs_message_direction {
3583   GUESTFS_DIRECTION_CALL = 0,        /* client -> daemon */
3584   GUESTFS_DIRECTION_REPLY = 1        /* daemon -> client */
3585 };
3586
3587 enum guestfs_message_status {
3588   GUESTFS_STATUS_OK = 0,
3589   GUESTFS_STATUS_ERROR = 1
3590 };
3591
3592 const GUESTFS_ERROR_LEN = 256;
3593
3594 struct guestfs_message_error {
3595   string error_message<GUESTFS_ERROR_LEN>;
3596 };
3597
3598 struct guestfs_message_header {
3599   unsigned prog;                     /* GUESTFS_PROGRAM */
3600   unsigned vers;                     /* GUESTFS_PROTOCOL_VERSION */
3601   guestfs_procedure proc;            /* GUESTFS_PROC_x */
3602   guestfs_message_direction direction;
3603   unsigned serial;                   /* message serial number */
3604   guestfs_message_status status;
3605 };
3606
3607 const GUESTFS_MAX_CHUNK_SIZE = 8192;
3608
3609 struct guestfs_chunk {
3610   int cancel;                        /* if non-zero, transfer is cancelled */
3611   /* data size is 0 bytes if the transfer has finished successfully */
3612   opaque data<GUESTFS_MAX_CHUNK_SIZE>;
3613 };
3614 "
3615
3616 (* Generate the guestfs-structs.h file. *)
3617 and generate_structs_h () =
3618   generate_header CStyle LGPLv2;
3619
3620   (* This is a public exported header file containing various
3621    * structures.  The structures are carefully written to have
3622    * exactly the same in-memory format as the XDR structures that
3623    * we use on the wire to the daemon.  The reason for creating
3624    * copies of these structures here is just so we don't have to
3625    * export the whole of guestfs_protocol.h (which includes much
3626    * unrelated and XDR-dependent stuff that we don't want to be
3627    * public, or required by clients).
3628    *
3629    * To reiterate, we will pass these structures to and from the
3630    * client with a simple assignment or memcpy, so the format
3631    * must be identical to what rpcgen / the RFC defines.
3632    *)
3633
3634   (* Public structures. *)
3635   List.iter (
3636     fun (typ, cols) ->
3637       pr "struct guestfs_%s {\n" typ;
3638       List.iter (
3639         function
3640         | name, FChar -> pr "  char %s;\n" name
3641         | name, FString -> pr "  char *%s;\n" name
3642         | name, FUUID -> pr "  char %s[32]; /* this is NOT nul-terminated, be careful when printing */\n" name
3643         | name, FUInt32 -> pr "  uint32_t %s;\n" name
3644         | name, FInt32 -> pr "  int32_t %s;\n" name
3645         | name, (FUInt64|FBytes) -> pr "  uint64_t %s;\n" name
3646         | name, FInt64 -> pr "  int64_t %s;\n" name
3647         | name, FOptPercent -> pr "  float %s; /* [0..100] or -1 */\n" name
3648       ) cols;
3649       pr "};\n";
3650       pr "\n";
3651       pr "struct guestfs_%s_list {\n" typ;
3652       pr "  uint32_t len;\n";
3653       pr "  struct guestfs_%s *val;\n" typ;
3654       pr "};\n";
3655       pr "\n";
3656       pr "extern void guestfs_free_%s (struct guestfs_%s *);\n" typ typ;
3657       pr "extern void guestfs_free_%s_list (struct guestfs_%s_list *);\n" typ typ;
3658       pr "\n"
3659   ) structs
3660
3661 (* Generate the guestfs-actions.h file. *)
3662 and generate_actions_h () =
3663   generate_header CStyle LGPLv2;
3664   List.iter (
3665     fun (shortname, style, _, _, _, _, _) ->
3666       let name = "guestfs_" ^ shortname in
3667       generate_prototype ~single_line:true ~newline:true ~handle:"handle"
3668         name style
3669   ) all_functions
3670
3671 (* Generate the client-side dispatch stubs. *)
3672 and generate_client_actions () =
3673   generate_header CStyle LGPLv2;
3674
3675   pr "\
3676 #include <stdio.h>
3677 #include <stdlib.h>
3678
3679 #include \"guestfs.h\"
3680 #include \"guestfs_protocol.h\"
3681
3682 #define error guestfs_error
3683 #define perrorf guestfs_perrorf
3684 #define safe_malloc guestfs_safe_malloc
3685 #define safe_realloc guestfs_safe_realloc
3686 #define safe_strdup guestfs_safe_strdup
3687 #define safe_memdup guestfs_safe_memdup
3688
3689 /* Check the return message from a call for validity. */
3690 static int
3691 check_reply_header (guestfs_h *g,
3692                     const struct guestfs_message_header *hdr,
3693                     int proc_nr, int serial)
3694 {
3695   if (hdr->prog != GUESTFS_PROGRAM) {
3696     error (g, \"wrong program (%%d/%%d)\", hdr->prog, GUESTFS_PROGRAM);
3697     return -1;