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