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