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