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