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