X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fgenerator.ml;h=32a814003a3247d16be83e4bd69b085df57feec1;hp=87855e7d1e919e0b0274fb0b50c061a292ab1263;hb=1214b321621e7750c67423ecf4d9528809e1eeac;hpb=4f376dbafb78ee9b5ad1652360472a14de64753d diff --git a/src/generator.ml b/src/generator.ml index 87855e7..32a8140 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -164,9 +164,8 @@ and argt = *) | FileIn of string | FileOut of string -(* Not implemented: (* Opaque buffer which can contain arbitrary 8 bit data. - * In the C API, this is expressed as pair. + * In the C API, this is expressed as pair. * Most other languages have a string type which can contain * ASCII NUL. We use whatever type is appropriate for each * language. @@ -175,13 +174,11 @@ and argt = * To return an arbitrary buffer, use RBufferOut. *) | BufferIn of string -*) type flags = | ProtocolLimitWarning (* display warning about protocol size limits *) | DangerWillRobinson (* flags particularly dangerous commands *) | FishAlias of string (* provide an alias for this cmd in guestfish *) - | FishAction of string (* call this function in guestfish *) | FishOutput of fish_output_t (* how to display output in guestfish *) | NotInFish (* do not export via guestfish *) | NotInDocs (* do not add this function to documentation *) @@ -385,6 +382,7 @@ let test_all_args = [ Int64 "integer64"; FileIn "filein"; FileOut "fileout"; + BufferIn "bufferin"; ] let test_all_rets = [ @@ -447,7 +445,7 @@ You probably don't want to call this function.")] *) let non_daemon_functions = test_functions @ [ - ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"], + ("launch", (RErr, []), -1, [FishAlias "run"], [], "launch the qemu subprocess", "\ @@ -940,7 +938,7 @@ let daemon_functions = [ [["part_disk"; "/dev/sda"; "mbr"]; ["mkfs"; "ext2"; "/dev/sda1"]; ["mount"; "/dev/sda1"; "/"]; - ["write_file"; "/new"; "new file contents"; "0"]; + ["write"; "/new"; "new file contents"]; ["cat"; "/new"]], "new file contents")], "mount a guest disk at a position in the filesystem", "\ @@ -958,8 +956,15 @@ exist. 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."); +B +When you use this call, the filesystem options C and C +are set implicitly. This was originally done because we thought it +would improve reliability, but it turns out that I<-o sync> has a +very large negative performance impact and negligible effect on +reliability. Therefore we recommend that you avoid using +C in any code that needs performance, and instead +use C (use an empty string for the first +parameter if you don't want any options)."); ("sync", (RErr, []), 2, [], [ InitEmpty, Always, TestRun [["sync"]]], @@ -1390,7 +1395,9 @@ numeric modes are supported. I: When using this command from guestfish, C by default would be decimal, unless you prefix it with -C<0> to get octal, ie. use C<0700> not C<700>."); +C<0> to get octal, ie. use C<0700> not C<700>. + +The mode actually set is affected by the umask."); ("chown", (RErr, [Int "owner"; Int "group"; Pathname "path"]), 35, [], [], (* XXX Need stat command to test *) @@ -1493,7 +1500,7 @@ on the volume group C, with C megabytes."); [["part_disk"; "/dev/sda"; "mbr"]; ["mkfs"; "ext2"; "/dev/sda1"]; ["mount_options"; ""; "/dev/sda1"; "/"]; - ["write_file"; "/new"; "new file contents"; "0"]; + ["write"; "/new"; "new file contents"]; ["cat"; "/new"]], "new file contents")], "make a filesystem", "\ @@ -1530,25 +1537,8 @@ the string C<,> (comma). See also: C, C, C"); - ("write_file", (RErr, [Pathname "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning], - [InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; "new file contents"; "0"]; - ["cat"; "/new"]], "new file contents"); - InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; "\nnew file contents\n"; "0"]; - ["cat"; "/new"]], "\nnew file contents\n"); - InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; "\n\n"; "0"]; - ["cat"; "/new"]], "\n\n"); - InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; ""; "0"]; - ["cat"; "/new"]], ""); - InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; "\n\n\n"; "0"]; - ["cat"; "/new"]], "\n\n\n"); - InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; "\n"; "0"]; - ["cat"; "/new"]], "\n")], + ("write_file", (RErr, [Pathname "path"; String "content"; Int "size"]), 44, [ProtocolLimitWarning; DeprecatedBy "write"], + [], "create a file", "\ This call creates a file called C. The contents of the @@ -1560,9 +1550,7 @@ then the length is calculated using C (so in this case the content cannot contain embedded ASCII NULs). I Owing to a bug, writing content containing ASCII NUL -characters does I work, even if the length is specified. -We hope to resolve this bug in a future version. In the meantime -use C."); +characters does I work, even if the length is specified."); ("umount", (RErr, [String "pathordevice"]), 45, [FishAlias "unmount"], [InitEmpty, Always, TestOutputListOfDevices ( @@ -1982,7 +1970,10 @@ See also C, C."); InitISOFS, Always, TestOutput ( [["checksum"; "sha384"; "/known-3"]], "5fa7883430f357b5d7b7271d3a1d2872b51d73cba72731de6863d3dea55f30646af2799bef44d5ea776a5ec7941ac640"); InitISOFS, Always, TestOutput ( - [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6")], + [["checksum"; "sha512"; "/known-3"]], "2794062c328c6b216dca90443b7f7134c5f40e56bd0ed7853123275a09982a6f992e6ca682f9d2fba34a4c5e870d8fe077694ff831e3032a004ee077e00603f6"); + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestOutput ( + [["checksum"; "sha512"; "/abssymlink"]], "5f57d0639bc95081c53afc63a449403883818edc64da48930ad6b1a4fb49be90404686877743fbcd7c99811f3def7df7bc22635c885c6a8cf79c806b43451c1a")], "compute MD5, SHAx or CRC checksum of file", "\ This call computes the MD5, SHAx or CRC checksum of the @@ -2024,9 +2015,13 @@ Compute the SHA512 hash (using the C program). =back -The checksum is returned as a printable string."); +The checksum is returned as a printable string. - ("tar_in", (RErr, [FileIn "tarfile"; String "directory"]), 69, [], +To get the checksum for a device, use C. + +To get the checksums for many files, use C."); + + ("tar_in", (RErr, [FileIn "tarfile"; Pathname "directory"]), 69, [], [InitBasicFS, Always, TestOutput ( [["tar_in"; "../images/helloworld.tar"; "/"]; ["cat"; "/hello"]], "hello\n")], @@ -2048,7 +2043,7 @@ it to local file C. To download a compressed tarball, use C or C."); - ("tgz_in", (RErr, [FileIn "tarball"; String "directory"]), 71, [], + ("tgz_in", (RErr, [FileIn "tarball"; Pathname "directory"]), 71, [], [InitBasicFS, Always, TestOutput ( [["tgz_in"; "../images/helloworld.tar.gz"; "/"]; ["cat"; "/hello"]], "hello\n")], @@ -2074,7 +2069,7 @@ To download an uncompressed tarball, use C."); ["mount_ro"; "/dev/sda1"; "/"]; ["touch"; "/new"]]); InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; "data"; "0"]; + [["write"; "/new"; "data"]; ["umount"; "/"]; ["mount_ro"; "/dev/sda1"; "/"]; ["cat"; "/new"]], "data")], @@ -2089,7 +2084,11 @@ mounts the filesystem with the read-only (I<-o ro>) flag."); "\ This is the same as the C command, but it allows you to set the mount options as for the -L I<-o> flag."); +L I<-o> flag. + +If the C parameter is an empty string, then +no options are passed (all options default to whatever +the filesystem uses)."); ("mount_vfs", (RErr, [String "options"; String "vfstype"; Device "device"; String "mountpoint"]), 75, [], [], @@ -2322,15 +2321,15 @@ C, with the root directory being C."); ("cp", (RErr, [Pathname "src"; Pathname "dest"]), 87, [], [InitBasicFS, Always, TestOutput ( - [["write_file"; "/old"; "file content"; "0"]; + [["write"; "/old"; "file content"]; ["cp"; "/old"; "/new"]; ["cat"; "/new"]], "file content"); InitBasicFS, Always, TestOutputTrue ( - [["write_file"; "/old"; "file content"; "0"]; + [["write"; "/old"; "file content"]; ["cp"; "/old"; "/new"]; ["is_file"; "/old"]]); InitBasicFS, Always, TestOutput ( - [["write_file"; "/old"; "file content"; "0"]; + [["write"; "/old"; "file content"]; ["mkdir"; "/dir"]; ["cp"; "/old"; "/dir/new"]; ["cat"; "/dir/new"]], "file content")], @@ -2343,7 +2342,7 @@ either a destination filename or destination directory."); [InitBasicFS, Always, TestOutput ( [["mkdir"; "/olddir"]; ["mkdir"; "/newdir"]; - ["write_file"; "/olddir/file"; "file content"; "0"]; + ["write"; "/olddir/file"; "file content"]; ["cp_a"; "/olddir"; "/newdir"]; ["cat"; "/newdir/olddir/file"]], "file content")], "copy a file or directory recursively", @@ -2353,11 +2352,11 @@ recursively using the C command."); ("mv", (RErr, [Pathname "src"; Pathname "dest"]), 89, [], [InitBasicFS, Always, TestOutput ( - [["write_file"; "/old"; "file content"; "0"]; + [["write"; "/old"; "file content"]; ["mv"; "/old"; "/new"]; ["cat"; "/new"]], "file content"); InitBasicFS, Always, TestOutputFalse ( - [["write_file"; "/old"; "file content"; "0"]; + [["write"; "/old"; "file content"]; ["mv"; "/old"; "/new"]; ["is_file"; "/old"]])], "move a file", @@ -2406,12 +2405,12 @@ or attached block device(s) in any other way."); ("equal", (RBool "equality", [Pathname "file1"; Pathname "file2"]), 93, [], [InitBasicFS, Always, TestOutputTrue ( - [["write_file"; "/file1"; "contents of a file"; "0"]; + [["write"; "/file1"; "contents of a file"]; ["cp"; "/file1"; "/file2"]; ["equal"; "/file1"; "/file2"]]); InitBasicFS, Always, TestOutputFalse ( - [["write_file"; "/file1"; "contents of a file"; "0"]; - ["write_file"; "/file2"; "contents of another file"; "0"]; + [["write"; "/file1"; "contents of a file"]; + ["write"; "/file2"; "contents of another file"]; ["equal"; "/file1"; "/file2"]]); InitBasicFS, Always, TestLastFail ( [["equal"; "/file1"; "/file2"]])], @@ -2426,7 +2425,10 @@ The external L program is used for the comparison."); [InitISOFS, Always, TestOutputList ( [["strings"; "/known-5"]], ["abcdefghi"; "jklmnopqr"]); InitISOFS, Always, TestOutputList ( - [["strings"; "/empty"]], [])], + [["strings"; "/empty"]], []); + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestRun ( + [["strings"; "/abssymlink"]])], "print the printable strings in a file", "\ This runs the L command on a file and returns @@ -2435,18 +2437,47 @@ the list of printable strings found."); ("strings_e", (RStringList "stringsout", [String "encoding"; Pathname "path"]), 95, [ProtocolLimitWarning], [InitISOFS, Always, TestOutputList ( [["strings_e"; "b"; "/known-5"]], []); - InitBasicFS, Disabled, TestOutputList ( - [["write_file"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"; "24"]; + InitBasicFS, Always, TestOutputList ( + [["write"; "/new"; "\000h\000e\000l\000l\000o\000\n\000w\000o\000r\000l\000d\000\n"]; ["strings_e"; "b"; "/new"]], ["hello"; "world"])], "print the printable strings in a file", "\ This is like the C command, but allows you to -specify the encoding. +specify the encoding of strings that are looked for in +the source file C. -See the L manpage for the full list of encodings. +Allowed encodings are: -Commonly useful encodings are C (lower case L) which will -show strings inside Windows/x86 files. +=over 4 + +=item s + +Single 7-bit-byte characters like ASCII and the ASCII-compatible +parts of ISO-8859-X (this is what C uses). + +=item S + +Single 8-bit-byte characters. + +=item b + +16-bit big endian strings such as those encoded in +UTF-16BE or UCS-2BE. + +=item l (lower case letter L) + +16-bit little endian such as UTF-16LE and UCS-2LE. +This is useful for examining binaries in Windows guests. + +=item B + +32-bit big endian such as UCS-4BE. + +=item L + +32-bit little endian such as UCS-4LE. + +=back The returned strings are transcoded to UTF-8."); @@ -2457,7 +2488,10 @@ The returned strings are transcoded to UTF-8."); * commands to segfault. *) InitISOFS, Always, TestRun ( - [["hexdump"; "/100krandom"]])], + [["hexdump"; "/100krandom"]]); + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestRun ( + [["hexdump"; "/abssymlink"]])], "dump a file in hexadecimal", "\ This runs C on the given C. The result is @@ -2468,7 +2502,7 @@ the human-readable, canonical hex dump of the file."); [["part_disk"; "/dev/sda"; "mbr"]; ["mkfs"; "ext3"; "/dev/sda1"]; ["mount_options"; ""; "/dev/sda1"; "/"]; - ["write_file"; "/new"; "test file"; "0"]; + ["write"; "/new"; "test file"]; ["umount"; "/dev/sda1"]; ["zerofree"; "/dev/sda1"]; ["mount_options"; ""; "/dev/sda1"; "/"]; @@ -2573,13 +2607,20 @@ are activated or deactivated."); ["lvcreate"; "LV"; "VG"; "10"]; ["mkfs"; "ext2"; "/dev/VG/LV"]; ["mount_options"; ""; "/dev/VG/LV"; "/"]; - ["write_file"; "/new"; "test content"; "0"]; + ["write"; "/new"; "test content"]; ["umount"; "/"]; ["lvresize"; "/dev/VG/LV"; "20"]; ["e2fsck_f"; "/dev/VG/LV"]; ["resize2fs"; "/dev/VG/LV"]; ["mount_options"; ""; "/dev/VG/LV"; "/"]; - ["cat"; "/new"]], "test content")], + ["cat"; "/new"]], "test content"); + InitNone, Always, TestRun ( + (* Make an LV smaller to test RHBZ#587484. *) + [["part_disk"; "/dev/sda"; "mbr"]; + ["pvcreate"; "/dev/sda1"]; + ["vgcreate"; "VG"; "/dev/sda1"]; + ["lvcreate"; "LV"; "VG"; "20"]; + ["lvresize"; "/dev/VG/LV"; "10"]])], "resize an LVM logical volume", "\ This resizes (expands or shrinks) an existing LVM logical @@ -2753,7 +2794,7 @@ manual page for more details."); ("scrub_file", (RErr, [Pathname "file"]), 115, [Optional "scrub"], [InitBasicFS, Always, TestRun ( - [["write_file"; "/file"; "content"; "0"]; + [["write"; "/file"; "content"]; ["scrub_file"; "/file"]])], "scrub (securely wipe) a file", "\ @@ -2805,7 +2846,10 @@ See also: L"); ("wc_l", (RInt "lines", [Pathname "path"]), 118, [], [InitISOFS, Always, TestOutputInt ( - [["wc_l"; "/10klines"]], 10000)], + [["wc_l"; "/10klines"]], 10000); + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestOutputInt ( + [["wc_l"; "/abssymlink"]], 10000)], "count lines in a file", "\ This command counts the lines in a file, using the @@ -2829,7 +2873,10 @@ C external command."); ("head", (RStringList "lines", [Pathname "path"]), 121, [ProtocolLimitWarning], [InitISOFS, Always, TestOutputList ( - [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])], + [["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"]); + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestOutputList ( + [["head"; "/abssymlink"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])], "return first 10 lines of a file", "\ This command returns up to the first 10 lines of a file as @@ -2985,7 +3032,17 @@ named pipes (FIFOs). The C parameter should be the mode, using the standard constants. C and C are the device major and minor numbers, only used when creating block -and character special devices."); +and character special devices. + +Note that, just like L, the mode must be bitwise +OR'd with S_IFBLK, S_IFCHR, S_IFIFO or S_IFSOCK (otherwise this call +just creates a regular file). These constants are +available in the standard Linux header files, or you can use +C, C or C +which are wrappers around this command which bitwise OR +in the appropriate constant for you. + +The mode actually set is affected by the umask."); ("mkfifo", (RErr, [Int "mode"; Pathname "path"]), 134, [Optional "mknod"], [InitBasicFS, Always, TestOutputStruct ( @@ -2995,7 +3052,9 @@ and character special devices."); "\ This call creates a FIFO (named pipe) called C with mode C. It is just a convenient wrapper around -C."); +C. + +The mode actually set is affected by the umask."); ("mknod_b", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"]), 135, [Optional "mknod"], [InitBasicFS, Always, TestOutputStruct ( @@ -3005,7 +3064,9 @@ C."); "\ This call creates a block device node called C with mode C and device major/minor C and C. -It is just a convenient wrapper around C."); +It is just a convenient wrapper around C. + +The mode actually set is affected by the umask."); ("mknod_c", (RErr, [Int "mode"; Int "devmajor"; Int "devminor"; Pathname "path"]), 136, [Optional "mknod"], [InitBasicFS, Always, TestOutputStruct ( @@ -3015,12 +3076,13 @@ It is just a convenient wrapper around C."); "\ This call creates a char device node called C with mode C and device major/minor C and C. -It is just a convenient wrapper around C."); +It is just a convenient wrapper around C. + +The mode actually set is affected by the umask."); ("umask", (RInt "oldmask", [Int "mask"]), 137, [FishOutput FishOutputOctal], - [], (* XXX umask is one of those stateful things that we should - * reset between each test. - *) + [InitEmpty, Always, TestOutputInt ( + [["umask"; "0o22"]], 0o22)], "set file mode creation mask (umask)", "\ This function sets the mask used for creating new files and @@ -3035,7 +3097,8 @@ The default umask is C<022>. This is important because it means that directories and device nodes will be created with C<0644> or C<0755> mode even if you specify C<0777>. -See also L, C, C. +See also C, +L, C, C. This call returns the previous umask."); @@ -3232,7 +3295,20 @@ for full details."); ("read_file", (RBufferOut "content", [Pathname "path"]), 150, [ProtocolLimitWarning], [InitISOFS, Always, TestOutputBuffer ( - [["read_file"; "/known-4"]], "abc\ndef\nghi")], + [["read_file"; "/known-4"]], "abc\ndef\nghi"); + (* Test various near large, large and too large files (RHBZ#589039). *) + InitBasicFS, Always, TestLastFail ( + [["touch"; "/a"]; + ["truncate_size"; "/a"; "4194303"]; (* GUESTFS_MESSAGE_MAX - 1 *) + ["read_file"; "/a"]]); + InitBasicFS, Always, TestLastFail ( + [["touch"; "/a"]; + ["truncate_size"; "/a"; "4194304"]; (* GUESTFS_MESSAGE_MAX *) + ["read_file"; "/a"]]); + InitBasicFS, Always, TestLastFail ( + [["touch"; "/a"]; + ["truncate_size"; "/a"; "41943040"]; (* GUESTFS_MESSAGE_MAX * 10 *) + ["read_file"; "/a"]])], "read a file", "\ This calls returns the contents of the file C as a @@ -3247,7 +3323,10 @@ in the total size of file that can be handled."); [InitISOFS, Always, TestOutputList ( [["grep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"]); InitISOFS, Always, TestOutputList ( - [["grep"; "nomatch"; "/test-grep.txt"]], [])], + [["grep"; "nomatch"; "/test-grep.txt"]], []); + (* Test for RHBZ#579608, absolute symbolic links. *) + InitISOFS, Always, TestOutputList ( + [["grep"; "nomatch"; "/abssymlink"]], [])], "return lines matching a pattern", "\ This calls the external C program and returns the @@ -3623,7 +3702,7 @@ and C"); [["part_disk"; "/dev/sda"; "mbr"]; ["mkfs_b"; "ext2"; "4096"; "/dev/sda1"]; ["mount_options"; ""; "/dev/sda1"; "/"]; - ["write_file"; "/new"; "new file contents"; "0"]; + ["write"; "/new"; "new file contents"]; ["cat"; "/new"]], "new file contents")], "make a filesystem with block size", "\ @@ -3638,7 +3717,7 @@ are C<1024>, C<2048> or C<4096> only."); ["mke2journal"; "4096"; "/dev/sda1"]; ["mke2fs_J"; "ext2"; "4096"; "/dev/sda2"; "/dev/sda1"]; ["mount_options"; ""; "/dev/sda2"; "/"]; - ["write_file"; "/new"; "new file contents"; "0"]; + ["write"; "/new"; "new file contents"]; ["cat"; "/new"]], "new file contents")], "make ext2/3/4 external journal", "\ @@ -3653,7 +3732,7 @@ to the command: ["mke2journal_L"; "4096"; "JOURNAL"; "/dev/sda1"]; ["mke2fs_JL"; "ext2"; "4096"; "/dev/sda2"; "JOURNAL"]; ["mount_options"; ""; "/dev/sda2"; "/"]; - ["write_file"; "/new"; "new file contents"; "0"]; + ["write"; "/new"; "new file contents"]; ["cat"; "/new"]], "new file contents")], "make ext2/3/4 external journal with label", "\ @@ -3666,7 +3745,7 @@ This creates an ext2 external journal on C with label C