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