X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=src%2Fgenerator.ml;h=c7d208f1b9725596689b838224fbda7c4134f986;hb=refs%2Fheads%2Flongdesc;hp=f686e660381b19928a9b5b5fe723a88fc71815b6;hpb=706c75629733d05a891a81eebe373d124409cfb8;p=libguestfs.git diff --git a/src/generator.ml b/src/generator.ml index f686e66..c7d208f 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -33,6 +33,7 @@ *) #load "unix.cma";; +#load "str.cma";; open Printf @@ -43,9 +44,15 @@ and ret = *) | RErr (* "RInt" as a return value means an int which is -1 for error - * or any value >= 0 on success. + * or any value >= 0 on success. Only use this for smallish + * positive ints (0 <= i < 2^30). *) | RInt of string + (* "RInt64" is the same as RInt, but is guaranteed to be able + * to return a full 64 bit value, _except_ that -1 means error + * (so -1 cannot be a valid, non-error return value). + *) + | RInt64 of string (* "RBool" is a bool return value which can be true/false or * -1 for error. *) @@ -92,6 +99,16 @@ and argt = | StringList of string(* list of strings (each string cannot be NULL) *) | Bool of string (* boolean *) | Int of string (* int (smallish ints, signed, <= 31 bits) *) + (* These are treated as filenames (simple string parameters) in + * the C API and bindings. But in the RPC protocol, we transfer + * the actual file content up to or down from the daemon. + * FileIn: local machine -> daemon (in request) + * FileOut: daemon -> local machine (in reply) + * In guestfish (only), the special name "-" means read from + * stdin or write to stdout. + *) + | FileIn of string + | FileOut of string type flags = | ProtocolLimitWarning (* display warning about protocol size limits *) @@ -99,6 +116,7 @@ type flags = | FishAlias of string (* provide an alias for this cmd in guestfish *) | FishAction of string (* call this function in guestfish *) | NotInFish (* do not export via guestfish *) + | NotInDocs (* do not add this function to documentation *) let protocol_limit_warning = "Because of the message protocol, there is a transfer limit @@ -112,19 +130,41 @@ can easily destroy all your data>." (* You can supply zero or as many tests as you want per API call. * * Note that the test environment has 3 block devices, of size 500MB, - * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc). + * 50MB and 10MB (respectively /dev/sda, /dev/sdb, /dev/sdc), and + * a fourth squashfs block device with some known files on it (/dev/sdd). + * * Note for partitioning purposes, the 500MB device has 63 cylinders. * + * The squashfs block device (/dev/sdd) comes from images/test.sqsh. + * * To be able to run the tests in a reasonable amount of time, * the virtual machine and block devices are reused between tests. * So don't try testing kill_subprocess :-x * - * Between each test we umount-all and lvm-remove-all (except InitNone). + * Between each test we blockdev-setrw, umount-all, lvm-remove-all. + * + * If the appliance is running an older Linux kernel (eg. RHEL 5) then + * devices are named /dev/hda etc. To cope with this, the test suite + * adds some hairly logic to detect this case, and then automagically + * replaces all strings which match "/dev/sd.*" with "/dev/hd.*". + * When writing test cases you shouldn't have to worry about this + * difference. * * Don't assume anything about the previous contents of the block * devices. Use 'Init*' to create some initial scenarios. + * + * You can add a prerequisite clause to any individual test. This + * is a run-time check, which, if it fails, causes the test to be + * skipped. Useful if testing a command which might not work on + * all variations of libguestfs builds. A test that has prerequisite + * of 'Always' is run unconditionally. + * + * In addition, packagers can skip individual tests by setting the + * environment variables: eg: + * SKIP_TEST__=1 SKIP_TEST_COMMAND_3=1 (skips test #3 of command) + * SKIP_TEST_=1 SKIP_TEST_ZEROFREE=1 (skips all zerofree tests) *) -type tests = (test_init * test) list +type tests = (test_init * test_prereq * test) list and test = (* Run the command sequence and just expect nothing to fail. *) | TestRun of seq @@ -168,6 +208,21 @@ and test_field_compare = | CompareFieldsIntEq of string * string | CompareFieldsStrEq of string * string +(* Test prerequisites. *) +and test_prereq = + (* Test always runs. *) + | Always + (* Test is currently disabled - eg. it fails, or it tests some + * unimplemented feature. + *) + | Disabled + (* 'string' is some C code (a function body) that should return + * true or false. The test will run if the code returns true. + *) + | If of string + (* As for 'If' but the test runs _unless_ the code returns true. *) + | Unless of string + (* Some initial scenarios for testing. *) and test_init = (* Do nothing, block devices could contain random stuff including @@ -195,266 +250,519 @@ and test_init = and seq = cmd list and cmd = string list -(* Note about long descriptions: When referring to another - * action, use the format C (ie. the full name of - * the C function). This will be replaced as appropriate in other - * language bindings. - * - * Apart from that, long descriptions are just perldoc paragraphs. +(* The short description is always a single, short line of plain text. + * Long descriptions use this limited "language" which is converted + * into the required formats on output (eg. perldoc, javadoc, etc.) + * At the top level, long descriptions are a list of paragraphs. + *) +type longdesc = para list +and para = + | P of snippet list (* full paragraph *) + | Q of string (* same as P[T str] *) + | ItemList of (snippet list * para) list (* list of items *) + | BulletList of para list (* bullet point list *) + | Note of snippet list (* full note paragraph *) + | QNote of string (* same as Note[T str] *) + | Pre of string list (* preformatted lines *) + | SeeAlso of string list (* see also other commands *) +and snippet = + | T of string (* text *) + | C of string (* code *) + | A of string (* named parameter *) + | X of string (* cross-reference to other command *) + | XA of string * snippet list (* call command with args *) + | XU of string (* cross-reference to unimplemented *) + | XW of string (* cross-reference to wildcard *) + | Em of string (* emphasized text *) + | Man of string * int (* manpage (name, section) *) + | URL of string (* URL *) + | NULL (* "NULL", "undef" etc. *) + | NONNULL (* "non-NULL", "defined", etc. *) + +(* These test functions are used in the language binding tests. *) + +let test_all_args = [ + String "str"; + OptString "optstr"; + StringList "strlist"; + Bool "b"; + Int "integer"; + FileIn "filein"; + FileOut "fileout"; +] + +let test_all_rets = [ + (* except for RErr, which is tested thoroughly elsewhere *) + "test0rint", RInt "valout"; + "test0rint64", RInt64 "valout"; + "test0rbool", RBool "valout"; + "test0rconststring", RConstString "valout"; + "test0rstring", RString "valout"; + "test0rstringlist", RStringList "valout"; + "test0rintbool", RIntBool ("valout", "valout"); + "test0rpvlist", RPVList "valout"; + "test0rvglist", RVGList "valout"; + "test0rlvlist", RLVList "valout"; + "test0rstat", RStat "valout"; + "test0rstatvfs", RStatVFS "valout"; + "test0rhashtable", RHashtable "valout"; +] + +let test_functions = [ + ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs], + [], + "internal test function - do not use", + [ +Q"This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +parameter type correctly."; + +Q"It echos the contents of each parameter to stdout."; + +Q"You probably don't want to call this function."]); +] @ List.flatten ( + List.map ( + fun (name, ret) -> + [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs], + [], + "internal test function - do not use", + [ +Q"This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +return type correctly."; + +P[T"It converts string ";A"val";T" to the return type."]; + +Q"You probably don't want to call this function."]); + + (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs], + [], + "internal test function - do not use", + [ +Q"This is an internal test function which is used to test whether +the automatically generated bindings can handle every possible +return type correctly."; + +Q"This function always returns an error."; + +Q"You probably don't want to call this function."])] + ) test_all_rets +) + +(* non_daemon_functions are any functions which don't get processed + * in the daemon, eg. functions for setting and getting local + * configuration values. *) -let non_daemon_functions = [ +let non_daemon_functions = test_functions @ [ ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"], [], "launch the qemu subprocess", - "\ -Internally libguestfs is implemented by running a virtual machine -using L. + [ +P[T"Internally libguestfs is implemented by running a virtual machine +using ";Man("qemu",1);T"."]; -You should call this after configuring the handle -(eg. adding drives) but before performing any actions."); +Q"You should call this after configuring the handle +(eg. adding drives) but before performing any actions."]); ("wait_ready", (RErr, []), -1, [NotInFish], [], "wait until the qemu subprocess launches", - "\ -Internally libguestfs is implemented by running a virtual machine -using L. + [ +P[T"Internally libguestfs is implemented by running a virtual machine +using ";Man("qemu",1);T"."]; -You should call this after C to wait for the launch -to complete."); +P[T"You should call this after ";X"launch"; T" to wait for the launch +to complete."]]); ("kill_subprocess", (RErr, []), -1, [], [], "kill the qemu subprocess", - "\ -This kills the qemu subprocess. You should never need to call this."); + [ +Q"This kills the qemu subprocess. You should never need to call this."]); ("add_drive", (RErr, [String "filename"]), -1, [FishAlias "add"], [], "add an image to examine or modify", - "\ -This function adds a virtual machine disk image C to the + [ +P[T"This function adds a virtual machine disk image ";A"filename";T" to the guest. The first time you call this function, the disk appears as IDE -disk 0 (C) in the guest, the second time as C, and -so on. +disk 0 (";C"/dev/sda";T") in the guest, the second time as ";C"/dev/sdb";T", and +so on."]; -You don't necessarily need to be root when using libguestfs. However +Q"You don't necessarily need to be root when using libguestfs. However you obviously do need sufficient permissions to access the filename for whatever operations you want to perform (ie. read access if you just want to read the image or write access if you want to modify the -image). +image)."; + +P[T"This is equivalent to the qemu parameter ";C"-drive file=filename";T"."]; -This is equivalent to the qemu parameter C<-drive file=filename>."); +Note[T"Note that this call checks for the existence of ";A"filename";T". This +stops you from specifying other types of drive which are supported +by qemu such as ";C"nbd:";T" and ";C"http:";T" URLs. To specify those, use +the general ";X"config";T" call instead."]]); ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"], [], "add a CD-ROM disk image to examine", - "\ -This function adds a virtual CD-ROM disk image to the guest. + [ +Q"This function adds a virtual CD-ROM disk image to the guest."; + +P[T"This is equivalent to the qemu parameter ";C"-cdrom filename";T"."]; + +Note[T"Note that this call checks for the existence of ";A"filename";T". This +stops you from specifying other types of drive which are supported +by qemu such as ";C"nbd:";T" and ";C"http:";T" URLs. To specify those, use +the general ";X"config";T" call instead."]]); + + ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"], + [], + "add a drive in snapshot mode (read-only)", + [ +Q"This adds a drive in snapshot mode, making it effectively +read-only."; + +Q"Note that writes to the device are allowed, and will be seen for +the duration of the guestfs handle, but they are written +to a temporary file which is discarded as soon as the guestfs +handle is closed. We don't currently have any method to enable +changes to be committed, although qemu can support this."; + +P[T"This is equivalent to the qemu parameter "; +C"-drive file=filename,snapshot=on";T"."]; -This is equivalent to the qemu parameter C<-cdrom filename>."); +Note[T"This call checks for the existence of ";A"filename";T". This +stops you from specifying other types of drive which are supported +by qemu such as ";C"nbd:";T" and ";C"http:";T" URLs. To specify those, use +the general ";X"config";T" call instead."]]); ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [], [], "add qemu parameters", - "\ -This can be used to add arbitrary qemu command line parameters -of the form C<-param value>. Actually it's not quite arbitrary - we + [ +P[T"This can be used to add arbitrary qemu command line parameters +of the form ";C"-qemuparam qemuvalue";T". +Actually it's not quite arbitrary - we prevent you from setting some parameters which would interfere with -parameters that we use. +parameters that we use."]; -The first character of C string must be a C<-> (dash). +P[T"The first character of ";A"qemuparam"; +T" string must be a ";C"-";T" (dash)."]; + +P[A"qemuvalue";T" can be ";NULL;T"."]]); + + ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"], + [], + "set the qemu binary", + [ +Q"Set the qemu binary that we will use."; + +Q"The default is chosen when the library was compiled by the +configure script."; + +P[T"You can also override this by setting the ";C"LIBGUESTFS_QEMU"; +T" environment variable."]; + +P[T"Setting ";A"qemu";T" to ";NULL;T" restores the default qemu binary."]]); + + ("get_qemu", (RConstString "qemu", []), -1, [], + [], + "get the qemu binary", + [ +Q"Return the current qemu binary."; -C can be NULL."); +P[T"This is always ";NONNULL;T". If it wasn't set already, then this will +return the default qemu binary name."]]); ("set_path", (RErr, [String "path"]), -1, [FishAlias "path"], [], "set the search path", - "\ -Set the path that libguestfs searches for kernel and initrd.img. + [ +Q"Set the path that libguestfs searches for kernel and initrd.img."; -The default is C<$libdir/guestfs> unless overridden by setting -C environment variable. +P[T"The default is ";C"$libdir/guestfs";T" unless overridden by setting "; +C"LIBGUESTFS_PATH";T" environment variable."]; -The string C is stashed in the libguestfs handle, so the caller -must make sure it remains valid for the lifetime of the handle. - -Setting C to C restores the default path."); +P[T"Setting ";A"path";T" to ";NULL;T" restores the default path."]]); ("get_path", (RConstString "path", []), -1, [], [], "get the search path", - "\ -Return the current search path. + [ +Q"Return the current search path."; + +P[T"This is always ";NONNULL;T". If it wasn't set already, then this will +return the default path."]]); + + ("set_append", (RErr, [String "append"]), -1, [FishAlias "append"], + [], + "add options to kernel command line", + [ +Q"This function is used to add additional options to the +guest kernel command line."; + +P[T"The default is ";NULL;T" unless overridden by setting "; +C"LIBGUESTFS_APPEND";T" environment variable."]; + +P[T"Setting ";A"append";T" to ";NULL;T" means ";Em"no"; +T" additional options are passed +(libguestfs always adds a few of its own)."]]); + + ("get_append", (RConstString "append", []), -1, [], + [], + "get the additional kernel options", + [ +Q"Return the additional kernel options which are added to the +guest kernel command line."; -This is always non-NULL. If it wasn't set already, then this will -return the default path."); +P[T"If ";NULL;T" then no options are added."]]); ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"], [], "set autosync mode", - "\ -If C is true, this enables autosync. Libguestfs will make a -best effort attempt to run C when the handle is closed -(also if the program exits without closing handles)."); + [ +P[T"If ";A"autosync";T" is true, this enables autosync. Libguestfs will make a +best effort attempt to run ";X"umount_all";T" followed by "; +X"sync";T" when the handle is closed +(also if the program exits without closing handles)."]; + +Q"This is disabled by default (except in guestfish where it is +enabled by default)."]); ("get_autosync", (RBool "autosync", []), -1, [], [], "get autosync mode", - "\ -Get the autosync flag."); + [ +Q"Get the autosync flag."]); ("set_verbose", (RErr, [Bool "verbose"]), -1, [FishAlias "verbose"], [], "set verbose mode", - "\ -If C is true, this turns on verbose messages (to C). + [ +P[T"If ";A"verbose";T" is true, this turns on verbose messages +(to ";C"stderr";T")."]; -Verbose messages are disabled unless the environment variable -C is defined and set to C<1>."); +P[T"Verbose messages are disabled unless the environment variable "; +C"LIBGUESTFS_DEBUG";T" is defined and set to ";C"1";T"."]]); ("get_verbose", (RBool "verbose", []), -1, [], [], "get verbose mode", - "\ -This returns the verbose messages flag.") + [ +Q"This returns the verbose messages flag."]); + + ("is_ready", (RBool "ready", []), -1, [], + [], + "is ready to accept commands", + [ +P[T"This returns true iff this handle is ready to accept commands +(in the ";C"READY";T" state)."]; + +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); + + ("is_config", (RBool "config", []), -1, [], + [], + "is in configuration state", + [ +P[T"This returns true iff this handle is being configured +(in the ";C"CONFIG";T" state)."]; + +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); + + ("is_launching", (RBool "launching", []), -1, [], + [], + "is launching subprocess", + [ +P[T"This returns true iff this handle is launching the subprocess +(in the ";C"LAUNCHING";T" state)."]; + +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); + + ("is_busy", (RBool "busy", []), -1, [], + [], + "is busy processing a command", + [ +P[T"This returns true iff this handle is busy processing a command +(in the ";C"BUSY";T" state)."]; + +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); + + ("get_state", (RInt "state", []), -1, [], + [], + "get the current state", + [ +Q"This returns the current state as an opaque integer. This is +only useful for printing debug and internal error messages."; + +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); + + ("set_busy", (RErr, []), -1, [NotInFish], + [], + "set state to busy", + [ +P[T"This sets the state to ";C"BUSY";T". This is only used when implementing +actions using the low-level API."]; + +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); + + ("set_ready", (RErr, []), -1, [NotInFish], + [], + "set state to ready", + [ +P[T"This sets the state to ";C"READY";T". This is only used when implementing +actions using the low-level API."]; + +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); + + ("end_busy", (RErr, []), -1, [NotInFish], + [], + "leave the busy state", + [ +P[T"This sets the state to ";C"READY";T", or if in ";C"CONFIG"; +T" then it leaves the +state as is. This is only used when implementing +actions using the low-level API."]; + +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); + ] +(* daemon_functions are any functions which cause some action + * to take place in the daemon. + *) + let daemon_functions = [ ("mount", (RErr, [String "device"; String "mountpoint"]), 1, [], - [InitEmpty, TestOutput ( + [InitEmpty, Always, TestOutput ( [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ","]; ["mkfs"; "ext2"; "/dev/sda1"]; ["mount"; "/dev/sda1"; "/"]; ["write_file"; "/new"; "new file contents"; "0"]; ["cat"; "/new"]], "new file contents")], "mount a guest disk at a position in the filesystem", - "\ -Mount a guest disk at a position in the filesystem. Block devices -are named C, C and so on, as they were added to + [ +P[T"Mount a guest disk at a position in the filesystem. Block devices +are named ";C"/dev/sda";T", ";C"/dev/sdb";T" and so on, as they were added to the guest. If those block devices contain partitions, they will have -the usual names (eg. C). Also LVM C-style -names can be used. +the usual names (eg. ";C"/dev/sda1";T"). Also LVM ";C"/dev/VG/LV";T"-style +names can be used."]; -The rules are the same as for L: A filesystem must -first be mounted on C before others can be mounted. Other +P[T"The rules are the same as for ";Man("mount",8);T": A filesystem must +first be mounted on ";C"/";T" before others can be mounted. Other filesystems can only be mounted on directories which already -exist. +exist."]; -The mounted filesystem is writable, if we have sufficient permissions -on the underlying device. +Q"The mounted filesystem is writable, if we have sufficient permissions +on the underlying device."; -The filesystem options C and C are set with this -call, in order to improve reliability."); +P[T"The filesystem options ";C"sync";T" and ";C"noatime";T" are set with this +call, in order to improve reliability."]]); ("sync", (RErr, []), 2, [], - [ InitEmpty, TestRun [["sync"]]], + [ InitEmpty, Always, TestRun [["sync"]]], "sync disks, writes are flushed through to the disk image", - "\ -This syncs the disk, so that any writes are flushed through to the -underlying disk image. + [ +Q"This syncs the disk, so that any writes are flushed through to the +underlying disk image."; -You should always call this if you have modified a disk image, before -closing the handle."); +Q"You should always call this if you have modified a disk image, before +closing the handle."]); ("touch", (RErr, [String "path"]), 3, [], - [InitBasicFS, TestOutputTrue ( + [InitBasicFS, Always, TestOutputTrue ( [["touch"; "/new"]; ["exists"; "/new"]])], "update file timestamps or create a new file", - "\ -Touch acts like the L command. It can be used to + [ +P[T"Touch acts like the ";Man("touch",1);T" command. It can be used to update the timestamps on a file, or, if the file does not exist, -to create a new zero-length file."); +to create a new zero-length file."]]); ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning], - [InitBasicFS, TestOutput ( + [InitBasicFS, Always, TestOutput ( [["write_file"; "/new"; "new file contents"; "0"]; ["cat"; "/new"]], "new file contents")], "list the contents of a file", - "\ -Return the contents of the file named C. + [ +P[T"Return the contents of the file named ";A"path";T"."]; -Note that this function cannot correctly handle binary files -(specifically, files containing C<\\0> character which is treated -as end of string). For those you need to use the C -function which has a more complex interface."); +P[T"Note that this function cannot correctly handle binary files +(specifically, files containing ";C"\\0";T" character which is treated +as end of string). For those you need to use the ";X"download"; +T" function which has a more complex interface."]]); ("ll", (RString "listing", [String "directory"]), 5, [], [], (* XXX Tricky to test because it depends on the exact format * of the 'ls -l' command, which changes between F10 and F11. *) "list the files in a directory (long format)", - "\ -List the files in C (relative to the root directory, -there is no cwd) in the format of 'ls -la'. + [ +P[T"List the files in ";A"directory";T" (relative to the root directory, +there is no cwd) in the format of ";C"ls -la";T"."]; -This command is mostly useful for interactive sessions. It -is I intended that you try to parse the output string."); +P[T"This command is mostly useful for interactive sessions. It +is ";Em"not";T" intended that you try to parse the output string."]]); ("ls", (RStringList "listing", [String "directory"]), 6, [], - [InitBasicFS, TestOutputList ( + [InitBasicFS, Always, TestOutputList ( [["touch"; "/new"]; ["touch"; "/newer"]; ["touch"; "/newest"]; ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])], "list the files in a directory", - "\ -List the files in C (relative to the root directory, -there is no cwd). The '.' and '..' entries are not returned, but -hidden files are shown. - -This command is mostly useful for interactive sessions. Programs -should probably use C instead."); + [ +P[T"List the files in ";A"directory";T" (relative to the root directory, +there is no cwd). The ";C".";T" and ";C"..";T" entries are not returned, but +hidden files are shown."]]); ("list_devices", (RStringList "devices", []), 7, [], - [InitEmpty, TestOutputList ( - [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"])], + [InitEmpty, Always, TestOutputList ( + [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])], "list the block devices", - "\ -List all the block devices. + [ +Q"List all the block devices."; -The full block device names are returned, eg. C"); +P[T"The full block device names are returned, eg. ";C"/dev/sda";T"."]]); ("list_partitions", (RStringList "partitions", []), 8, [], - [InitBasicFS, TestOutputList ( + [InitBasicFS, Always, TestOutputList ( [["list_partitions"]], ["/dev/sda1"]); - InitEmpty, TestOutputList ( + InitEmpty, Always, TestOutputList ( [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])], "list the partitions", - "\ -List all the partitions detected on all block devices. + [ +Q"List all the partitions detected on all block devices."; -The full partition device names are returned, eg. C +P[T"The full partition device names are returned, eg. ";C"/dev/sda1"]; -This does not return logical volumes. For that you will need to -call C."); +P[T"This does not return logical volumes. For that you will need to +call ";X"lvs";T"."]]); ("pvs", (RStringList "physvols", []), 9, [], - [InitBasicFSonLVM, TestOutputList ( + [InitBasicFSonLVM, Always, TestOutputList ( [["pvs"]], ["/dev/sda1"]); - InitEmpty, TestOutputList ( + InitEmpty, Always, TestOutputList ( [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; ["pvcreate"; "/dev/sda3"]; ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])], "list the LVM physical volumes (PVs)", - "\ -List all the physical volumes detected. This is the equivalent -of the L command. + [ +P[T"List all the physical volumes detected. This is the equivalent +of the ";Man("pvs",8);T" command."]; -This returns a list of just the device names that contain -PVs (eg. C). +P[T"This returns a list of just the device names that contain +PVs (eg. ";C"/dev/sda2";T")."]; -See also C."); +SeeAlso["pvs_full"]]); ("vgs", (RStringList "volgroups", []), 10, [], - [InitBasicFSonLVM, TestOutputList ( + [InitBasicFSonLVM, Always, TestOutputList ( [["vgs"]], ["VG"]); - InitEmpty, TestOutputList ( + InitEmpty, Always, TestOutputList ( [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; @@ -463,19 +771,19 @@ See also C."); ["vgcreate"; "VG2"; "/dev/sda3"]; ["vgs"]], ["VG1"; "VG2"])], "list the LVM volume groups (VGs)", - "\ -List all the volumes groups detected. This is the equivalent -of the L command. + [ +P[T"List all the volumes groups detected. This is the equivalent +of the ";Man("vgs",8);T" command."]; -This returns a list of just the volume group names that were -detected (eg. C). +P[T"This returns a list of just the volume group names that were +detected (eg. ";C"VolGroup00";T")."]; -See also C."); +SeeAlso["vgs_full"]]); ("lvs", (RStringList "logvols", []), 11, [], - [InitBasicFSonLVM, TestOutputList ( + [InitBasicFSonLVM, Always, TestOutputList ( [["lvs"]], ["/dev/VG/LV"]); - InitEmpty, TestOutputList ( + InitEmpty, Always, TestOutputList ( [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; ["pvcreate"; "/dev/sda1"]; ["pvcreate"; "/dev/sda2"]; @@ -487,354 +795,364 @@ See also C."); ["lvcreate"; "LV3"; "VG2"; "50"]; ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])], "list the LVM logical volumes (LVs)", - "\ -List all the logical volumes detected. This is the equivalent -of the L command. + [ +P[T"List all the logical volumes detected. This is the equivalent +of the ";Man("lvs",8);T" command."]; -This returns a list of the logical volume device names -(eg. C). +P[T"This returns a list of the logical volume device names +(eg. ";C"/dev/VolGroup00/LogVol00";T")."]; -See also C."); +SeeAlso["lvs_full"]]); ("pvs_full", (RPVList "physvols", []), 12, [], [], (* XXX how to test? *) "list the LVM physical volumes (PVs)", - "\ -List all the physical volumes detected. This is the equivalent -of the L command. The \"full\" version includes all fields."); + [ +P[T"List all the physical volumes detected. This is the equivalent +of the ";Man("pvs",8);T" command. +The \"full\" version includes all fields."]]); ("vgs_full", (RVGList "volgroups", []), 13, [], [], (* XXX how to test? *) "list the LVM volume groups (VGs)", - "\ -List all the volumes groups detected. This is the equivalent -of the L command. The \"full\" version includes all fields."); + [ +P[T"List all the volumes groups detected. This is the equivalent +of the ";Man("vgs",8);T" command. +The \"full\" version includes all fields."]]); ("lvs_full", (RLVList "logvols", []), 14, [], [], (* XXX how to test? *) "list the LVM logical volumes (LVs)", - "\ -List all the logical volumes detected. This is the equivalent -of the L command. The \"full\" version includes all fields."); + [ +P[T"List all the logical volumes detected. This is the equivalent +of the ";Man("lvs",8);T" command. +The \"full\" version includes all fields."]]); ("read_lines", (RStringList "lines", [String "path"]), 15, [], - [InitBasicFS, TestOutputList ( + [InitBasicFS, Always, TestOutputList ( [["write_file"; "/new"; "line1\r\nline2\nline3"; "0"]; ["read_lines"; "/new"]], ["line1"; "line2"; "line3"]); - InitBasicFS, TestOutputList ( + InitBasicFS, Always, TestOutputList ( [["write_file"; "/new"; ""; "0"]; ["read_lines"; "/new"]], [])], "read file as lines", - "\ -Return the contents of the file named C. + [ +P[T"Return the contents of the file named ";A"path";T"."]; -The file contents are returned as a list of lines. Trailing -C and C character sequences are I returned. +P[T"The file contents are returned as a list of lines. Trailing "; +C"LF";T" and ";C"CRLF";T" character sequences are ";Em"not";T" returned."]; -Note that this function cannot correctly handle binary files -(specifically, files containing C<\\0> character which is treated -as end of line). For those you need to use the C -function which has a more complex interface."); +P[T"Note that this function cannot correctly handle binary files +(specifically, files containing ";C"\\0";T" character which is treated +as end of line). For those you need to use the ";XU"read_file"; +T" function which has a more complex interface."]]); ("aug_init", (RErr, [String "root"; Int "flags"]), 16, [], [], (* XXX Augeas code needs tests. *) "create a new Augeas handle", - "\ -Create a new Augeas handle for editing configuration files. + [ +Q"Create a new Augeas handle for editing configuration files. If there was any previous Augeas handle associated with this -guestfs session, then it is closed. +guestfs session, then it is closed."; -You must call this before using any other C -commands. +P[T"You must call this before using any other ";XW"aug_*"; +T" commands."]; -C is the filesystem root. C must not be NULL, -use C instead. +P[A"root";T" is the filesystem root. ";A"root";T" must be ";NONNULL;T", +use ";C"/";T" instead."]; -The flags are the same as the flags defined in -Eaugeas.hE, the logical I of the following -integers: +P[T"The flags are the same as the flags defined in +, the logical OR of the following +integers:"]; -=over 4 +ItemList [ -=item C = 1 +[C"AUG_SAVE_BACKUP";T" = 1"], -Keep the original file with a C<.augsave> extension. + P[T"Keep the original file with a ";C".augsave";T" extension."]; -=item C = 2 +[C"AUG_SAVE_NEWFILE";T" = 2"], -Save changes into a file with extension C<.augnew>, and -do not overwrite original. Overrides C. + P[T"Save changes into a file with extension ";C".augnew";T", and +do not overwrite original. Overrides ";C"AUG_SAVE_BACKUP";T"."]; -=item C = 4 +[C"AUG_TYPE_CHECK";T" = 4"], -Typecheck lenses (can be expensive). + Q"Typecheck lenses (can be expensive)."; -=item C = 8 +[C"AUG_NO_STDINC";T" = 8"], -Do not use standard load path for modules. + Q"Do not use standard load path for modules."; -=item C = 16 +[C"AUG_SAVE_NOOP";T" = 16"], -Make save a no-op, just record what would have been changed. + Q"Make save a no-op, just record what would have been changed."; -=item C = 32 +[C"AUG_NO_LOAD";T" = 32"], -Do not load the tree in C. + P[T"Do not load the tree in ";X"aug_init";T"."]; -=back +]; -To close the handle, you can call C. +P[T"To close the handle, you can call ";X"aug_close";T"."]; -To find out more about Augeas, see L."); +P[T"To find out more about Augeas, see ";URL"http://augeas.net/";T"."]]); ("aug_close", (RErr, []), 26, [], [], (* XXX Augeas code needs tests. *) "close the current Augeas handle", - "\ -Close the current Augeas handle and free up any resources -used by it. After calling this, you have to call -C again before you can use any other -Augeas functions."); + [ +P[T"Close the current Augeas handle and free up any resources +used by it. After calling this, you have to call "; +X"aug_init";T" again before you can use any other +Augeas functions."]]); ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [], [], (* XXX Augeas code needs tests. *) "define an Augeas variable", - "\ -Defines an Augeas variable C whose value is the result -of evaluating C. If C is NULL, then C is -undefined. + [ +P[T"Defines an Augeas variable ";A"name";T" whose value is the result +of evaluating ";A"expr";T". If ";A"expr";T" is ";NULL;T", then ";A"name";T" is +undefined."]; -On success this returns the number of nodes in C, or -C<0> if C evaluates to something which is not a nodeset."); +P[T"On success this returns the number of nodes in ";A"expr";T", or "; +C"0";T" if ";A"expr";T" evaluates to something which is not a nodeset."]]); ("aug_defnode", (RIntBool ("nrnodes", "created"), [String "name"; String "expr"; String "val"]), 18, [], [], (* XXX Augeas code needs tests. *) "define an Augeas node", - "\ -Defines a variable C whose value is the result of -evaluating C. + [ +P[T"Defines a variable ";A"name";T" whose value is the result of +evaluating ";A"expr";T"."]; -If C evaluates to an empty nodeset, a node is created, -equivalent to calling C C, C. -C will be the nodeset containing that single node. +P[T"If ";A"expr";T" evaluates to an empty nodeset, a node is created, +equivalent to calling ";XA("aug_set",[A"expr";A"value"]);T". "; +A"name";T" will be the nodeset containing that single node."]; -On success this returns a pair containing the +Q"On success this returns a pair containing the number of nodes in the nodeset, and a boolean flag -if a node was created."); +if a node was created."]); ("aug_get", (RString "val", [String "path"]), 19, [], [], (* XXX Augeas code needs tests. *) "look up the value of an Augeas path", - "\ -Look up the value associated with C. If C -matches exactly one node, the C is returned."); + [ +P[T"Look up the value associated with ";A"path";T". If ";A"path"; +T" matches exactly one node, the ";C"value";T" is returned."]]); ("aug_set", (RErr, [String "path"; String "val"]), 20, [], [], (* XXX Augeas code needs tests. *) "set Augeas path to value", - "\ -Set the value associated with C to C."); + [ +P[T"Set the value associated with ";A"path";T" to ";A"val";T"."]]); ("aug_insert", (RErr, [String "path"; String "label"; Bool "before"]), 21, [], [], (* XXX Augeas code needs tests. *) "insert a sibling Augeas node", - "\ -Create a new sibling C