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