X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fgenerator.ml;h=547acb7df96207fd5e7dfb1c21787bedc47d6cba;hp=2b777f19c3a8e6d90577b253f687bdc279d1334b;hb=bf2b08560f649c22152e4138531ad0b46b4ad1b3;hpb=6a0d9a9937162eee090f8dc331921724aef5784d diff --git a/src/generator.ml b/src/generator.ml index 2b777f1..547acb7 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -169,15 +169,7 @@ type flags = | 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 -of somewhere between 2MB and 4MB. To transfer large files you should use -FTP." - -let danger_will_robinson = - "B." + | DeprecatedBy of string (* function is deprecated, use .. instead *) (* You can supply zero or as many tests as you want per API call. * @@ -251,6 +243,10 @@ and test = *) | TestOutputLength of seq * int (* Run the command sequence and expect the output of the final + * command to be a buffer (RBufferOut), ie. string + size. + *) + | TestOutputBuffer of seq * string + (* Run the command sequence and expect the output of the final * command to be a structure. *) | TestOutputStruct of seq * test_field_compare list @@ -288,14 +284,17 @@ and test_init = * a bad idea. *) | InitNone + (* Block devices are empty and no filesystems are mounted. *) | InitEmpty + (* /dev/sda contains a single partition /dev/sda1, which is formatted * as ext2, empty [except for lost+found] and mounted on /. * /dev/sdb and /dev/sdc may have random content. * No LVM. *) | InitBasicFS + (* /dev/sda: * /dev/sda1 (is a PV): * /dev/VG/LV (size 8MB): @@ -304,6 +303,11 @@ and test_init = *) | InitBasicFSonLVM + (* /dev/sdd (the squashfs, see images/ directory in source) + * is mounted on / + *) + | InitSquashFS + (* Sequence of commands for testing. *) and seq = cmd list and cmd = string list @@ -1449,7 +1453,10 @@ This call uses the standard L command to determine the type or contents of the file. This also works on devices, for example to find out whether a partition contains a filesystem. -The exact command which runs is C. Note in +This call will also transparently look inside various types +of compressed file. + +The exact command which runs is C. Note in particular that the filename is not prepended to the output (the C<-b> option)."); @@ -1799,12 +1806,8 @@ See also C, C."); InitBasicFS, Always, TestOutput ( [["write_file"; "/new"; "test\n"; "0"]; ["checksum"; "sha512"; "/new"]], "0e3e75234abc68f4378a86b3f4b32a198ba301845b0cd6e50106e874345700cc6663a86c1ea125dc5e92be17c98f9a0f85ca9d5f595db2012f7cc3571945c123"); - InitBasicFS, Always, TestOutput ( - (* RHEL 5 thinks this is an HFS+ filesystem unless we give - * the type explicitly. - *) - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c")], + InitSquashFS, Always, TestOutput ( + [["checksum"; "md5"; "/known-3"]], "46d6ca27ee07cdc6fa99c2e138cc522c")], "compute MD5, SHAx or CRC checksum of file", "\ This call computes the MD5, SHAx or CRC checksum of the @@ -2279,9 +2282,8 @@ The returned strings are transcoded to UTF-8."); (* Test for RHBZ#501888c2 regression which caused large hexdump * commands to segfault. *) - InitBasicFS, Always, TestRun ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["hexdump"; "/100krandom"]])], + InitSquashFS, Always, TestRun ( + [["hexdump"; "/100krandom"]])], "dump a file in hexadecimal", "\ This runs C on the given C. The result is @@ -2618,51 +2620,44 @@ directory and its contents after use. See also: L"); ("wc_l", (RInt "lines", [String "path"]), 118, [], - [InitBasicFS, Always, TestOutputInt ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["wc_l"; "/10klines"]], 10000)], + [InitSquashFS, Always, TestOutputInt ( + [["wc_l"; "/10klines"]], 10000)], "count lines in a file", "\ This command counts the lines in a file, using the C external command."); ("wc_w", (RInt "words", [String "path"]), 119, [], - [InitBasicFS, Always, TestOutputInt ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["wc_w"; "/10klines"]], 10000)], + [InitSquashFS, Always, TestOutputInt ( + [["wc_w"; "/10klines"]], 10000)], "count words in a file", "\ This command counts the words in a file, using the C external command."); ("wc_c", (RInt "chars", [String "path"]), 120, [], - [InitBasicFS, Always, TestOutputInt ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["wc_c"; "/100kallspaces"]], 102400)], + [InitSquashFS, Always, TestOutputInt ( + [["wc_c"; "/100kallspaces"]], 102400)], "count characters in a file", "\ This command counts the characters in a file, using the C external command."); ("head", (RStringList "lines", [String "path"]), 121, [ProtocolLimitWarning], - [InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["head"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz";"3abcdefghijklmnopqrstuvwxyz";"4abcdefghijklmnopqrstuvwxyz";"5abcdefghijklmnopqrstuvwxyz";"6abcdefghijklmnopqrstuvwxyz";"7abcdefghijklmnopqrstuvwxyz";"8abcdefghijklmnopqrstuvwxyz";"9abcdefghijklmnopqrstuvwxyz"])], + [InitSquashFS, Always, TestOutputList ( + [["head"; "/10klines"]], ["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 a list of strings."); ("head_n", (RStringList "lines", [Int "nrlines"; String "path"]), 122, [ProtocolLimitWarning], - [InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]); - InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]); - InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["head_n"; "0"; "/10klines"]], [])], + [InitSquashFS, Always, TestOutputList ( + [["head_n"; "3"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]); + InitSquashFS, Always, TestOutputList ( + [["head_n"; "-9997"; "/10klines"]], ["0abcdefghijklmnopqrstuvwxyz";"1abcdefghijklmnopqrstuvwxyz";"2abcdefghijklmnopqrstuvwxyz"]); + InitSquashFS, Always, TestOutputList ( + [["head_n"; "0"; "/10klines"]], [])], "return first N lines of a file", "\ If the parameter C is a positive number, this returns the first @@ -2674,24 +2669,20 @@ from the file C, excluding the last C lines. If the parameter C is zero, this returns an empty list."); ("tail", (RStringList "lines", [String "path"]), 123, [ProtocolLimitWarning], - [InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])], + [InitSquashFS, Always, TestOutputList ( + [["tail"; "/10klines"]], ["9990abcdefghijklmnopqrstuvwxyz";"9991abcdefghijklmnopqrstuvwxyz";"9992abcdefghijklmnopqrstuvwxyz";"9993abcdefghijklmnopqrstuvwxyz";"9994abcdefghijklmnopqrstuvwxyz";"9995abcdefghijklmnopqrstuvwxyz";"9996abcdefghijklmnopqrstuvwxyz";"9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"])], "return last 10 lines of a file", "\ This command returns up to the last 10 lines of a file as a list of strings."); ("tail_n", (RStringList "lines", [Int "nrlines"; String "path"]), 124, [ProtocolLimitWarning], - [InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]); - InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]); - InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["tail_n"; "0"; "/10klines"]], [])], + [InitSquashFS, Always, TestOutputList ( + [["tail_n"; "3"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]); + InitSquashFS, Always, TestOutputList ( + [["tail_n"; "-9998"; "/10klines"]], ["9997abcdefghijklmnopqrstuvwxyz";"9998abcdefghijklmnopqrstuvwxyz";"9999abcdefghijklmnopqrstuvwxyz"]); + InitSquashFS, Always, TestOutputList ( + [["tail_n"; "0"; "/10klines"]], [])], "return last N lines of a file", "\ If the parameter C is a positive number, this returns the last @@ -2744,9 +2735,8 @@ The result is the estimated size in I (ie. units of 1024 bytes)."); ("initrd_list", (RStringList "filenames", [String "path"]), 128, [], - [InitBasicFS, Always, TestOutputList ( - [["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]; - ["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3"])], + [InitSquashFS, Always, TestOutputList ( + [["initrd_list"; "/initrd"]], ["empty";"known-1";"known-2";"known-3"])], "list files in an initrd", "\ This command lists out files contained in an initrd. @@ -2931,7 +2921,7 @@ were rarely if ever used anyway. See also C and the L manpage."); - ("zfile", (RString "description", [String "method"; String "path"]), 140, [], + ("zfile", (RString "description", [String "method"; String "path"]), 140, [DeprecatedBy "file"], [], "determine file type inside a compressed file", "\ @@ -2940,7 +2930,8 @@ using C. C must be one of C, C or C. -See also: C"); +Since 1.0.63, use C instead which can now +process compressed files."); ("getxattrs", (RStructList ("xattrs", "xattr"), [String "path"]), 141, [], [], @@ -3046,9 +3037,8 @@ with C. See C for full details."); ("read_file", (RBufferOut "content", [String "path"]), 150, [ProtocolLimitWarning], - [InitBasicFS, Always, TestOutput ( - [["write_file"; "/new"; "new file contents"; "0"]; - ["read_file"; "/new"]], "new file contents")], + [InitSquashFS, Always, TestOutputBuffer ( + [["read_file"; "/known-4"]], "abc\ndef\nghi")], "read a file", "\ This calls returns the contents of the file C as a @@ -3059,6 +3049,104 @@ handle files that contain embedded ASCII NUL characters. However unlike C, this function is limited in the total size of file that can be handled."); + ("grep", (RStringList "lines", [String "regex"; String "path"]), 151, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["grep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"]); + InitSquashFS, Always, TestOutputList ( + [["grep"; "nomatch"; "/test-grep.txt"]], [])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("egrep", (RStringList "lines", [String "regex"; String "path"]), 152, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["egrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("fgrep", (RStringList "lines", [String "pattern"; String "path"]), 153, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["fgrep"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("grepi", (RStringList "lines", [String "regex"; String "path"]), 154, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["grepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("egrepi", (RStringList "lines", [String "regex"; String "path"]), 155, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["egrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("fgrepi", (RStringList "lines", [String "pattern"; String "path"]), 156, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["fgrepi"; "abc"; "/test-grep.txt"]], ["abc"; "abc123"; "ABC"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("zgrep", (RStringList "lines", [String "regex"; String "path"]), 157, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["zgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("zegrep", (RStringList "lines", [String "regex"; String "path"]), 158, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["zegrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("zfgrep", (RStringList "lines", [String "pattern"; String "path"]), 159, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["zfgrep"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("zgrepi", (RStringList "lines", [String "regex"; String "path"]), 160, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["zgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("zegrepi", (RStringList "lines", [String "regex"; String "path"]), 161, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["zegrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + + ("zfgrepi", (RStringList "lines", [String "pattern"; String "path"]), 162, [ProtocolLimitWarning], + [InitSquashFS, Always, TestOutputList ( + [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], ["abc"; "abc123"; "ABC"])], + "return lines matching a pattern", + "\ +This calls the external C program and returns the +matching lines."); + ] let all_functions = non_daemon_functions @ daemon_functions @@ -3386,9 +3474,35 @@ let seq_of_test = function | TestOutputListOfDevices (s, _) | TestOutputInt (s, _) | TestOutputIntOp (s, _, _) | TestOutputTrue s | TestOutputFalse s - | TestOutputLength (s, _) | TestOutputStruct (s, _) + | TestOutputLength (s, _) | TestOutputBuffer (s, _) + | TestOutputStruct (s, _) | TestLastFail s -> s +(* Handling for function flags. *) +let protocol_limit_warning = + "Because of the message protocol, there is a transfer limit +of somewhere between 2MB and 4MB. To transfer large files you should use +FTP." + +let danger_will_robinson = + "B." + +let deprecation_notice flags = + try + let alt = + find_map (function DeprecatedBy str -> Some str | _ -> None) flags in + let txt = + sprintf "This function is deprecated. +In new code, use the C<%s> call instead. + +Deprecated functions will not be removed from the API, but the +fact that they are deprecated indicates that there are problems +with correct use of these functions." alt in + Some txt + with + Not_found -> None + (* Check function names etc. for consistency. *) let check_functions () = let contains_uppercase str = @@ -3637,7 +3751,10 @@ I.\n\n" if List.mem ProtocolLimitWarning flags then pr "%s\n\n" protocol_limit_warning; if List.mem DangerWillRobinson flags then - pr "%s\n\n" danger_will_robinson + pr "%s\n\n" danger_will_robinson; + match deprecation_notice flags with + | None -> () + | Some txt -> pr "%s\n\n" txt ) ) all_functions_sorted @@ -4944,6 +5061,13 @@ and generate_one_test_body name i test_name init test = ["lvcreate"; "LV"; "VG"; "8"]; ["mkfs"; "ext2"; "/dev/VG/LV"]; ["mount"; "/dev/VG/LV"; "/"]] + | InitSquashFS -> + pr " /* InitSquashFS for %s */\n" test_name; + List.iter (generate_test_command_call test_name) + [["blockdev_setrw"; "/dev/sda"]; + ["umount_all"]; + ["lvm_remove_all"]; + ["mount_vfs"; "ro"; "squashfs"; "/dev/sdd"; "/"]] ); let get_seq_last = function @@ -5099,6 +5223,23 @@ and generate_one_test_body name i test_name init test = in List.iter (generate_test_command_call test_name) seq; generate_test_command_call ~test test_name last + | TestOutputBuffer (seq, expected) -> + pr " /* TestOutputBuffer for %s (%d) */\n" name i; + pr " const char *expected = \"%s\";\n" (c_quote expected); + let seq, last = get_seq_last seq in + let len = String.length expected in + let test () = + pr " if (size != %d) {\n" len; + pr " fprintf (stderr, \"%s: returned size of buffer wrong, expected %d but got %%zu\\n\", size);\n" test_name len; + pr " return -1;\n"; + pr " }\n"; + pr " if (strncmp (r, expected, size) != 0) {\n"; + pr " fprintf (stderr, \"%s: expected \\\"%%s\\\" but got \\\"%%s\\\"\\n\", expected, r);\n" test_name; + pr " return -1;\n"; + pr " }\n" + in + List.iter (generate_test_command_call test_name) seq; + generate_test_command_call ~test test_name last | TestOutputStruct (seq, checks) -> pr " /* TestOutputStruct for %s (%d) */\n" name i; let seq, last = get_seq_last seq in @@ -5351,6 +5492,12 @@ and generate_fish_cmds () = ("\n\n" ^ danger_will_robinson) else "" in + let warnings = + warnings ^ + match deprecation_notice flags with + | None -> "" + | Some txt -> "\n\n" ^ txt in + let describe_alias = if name <> alias then sprintf "\n\nYou can use '%s' as an alias for this command." alias @@ -5722,7 +5869,11 @@ and generate_fish_actions_pod () = pr "%s\n\n" protocol_limit_warning; if List.mem DangerWillRobinson flags then - pr "%s\n\n" danger_will_robinson + pr "%s\n\n" danger_will_robinson; + + match deprecation_notice flags with + | None -> () + | Some txt -> pr "%s\n\n" txt ) all_functions_sorted (* Generate a C function prototype. *) @@ -6639,7 +6790,10 @@ sub new { if List.mem ProtocolLimitWarning flags then pr "%s\n\n" protocol_limit_warning; if List.mem DangerWillRobinson flags then - pr "%s\n\n" danger_will_robinson + pr "%s\n\n" danger_will_robinson; + match deprecation_notice flags with + | None -> () + | Some txt -> pr "%s\n\n" txt ) ) all_functions_sorted; @@ -7163,6 +7317,10 @@ class GuestFS: if List.mem DangerWillRobinson flags then doc ^ "\n\n" ^ danger_will_robinson else doc in + let doc = + match deprecation_notice flags with + | None -> doc + | Some txt -> doc ^ "\n\n" ^ txt in let doc = pod2text ~width:60 name doc in let doc = List.map (fun line -> replace_str line "\\" "\\\\") doc in let doc = String.concat "\n " doc in @@ -7571,6 +7729,10 @@ public class GuestFS { if List.mem DangerWillRobinson flags then doc ^ "\n\n" ^ danger_will_robinson else doc in + let doc = + match deprecation_notice flags with + | None -> doc + | Some txt -> doc ^ "\n\n" ^ txt in let doc = pod2text ~width:60 name doc in let doc = List.map ( (* RHBZ#501883 *) function