X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=src%2Fgenerator.ml;h=fcac9f839803044cc8f02a60c98724df766abc03;hb=0f24424f357e854a9da382de11e4fe81305c8743;hp=b7878506685d3bdc9f97d334aba857b6c1a98cab;hpb=549bba81e739ab10d8013c9ca88ce70b0ddda8e4;p=libguestfs.git diff --git a/src/generator.ml b/src/generator.ml index b787850..fcac9f8 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -1,6 +1,6 @@ #!/usr/bin/env ocaml (* libguestfs - * Copyright (C) 2009 Red Hat Inc. + * Copyright (C) 2009-2010 Red Hat Inc. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -21,21 +21,31 @@ * all the daemon actions. * * To add a new action there are only two files you need to change, - * this one to describe the interface (see the big table below), and - * daemon/.c to write the implementation. + * this one to describe the interface (see the big table of + * 'daemon_functions' below), and daemon/.c to write the + * implementation. * - * After editing this file, run it (./src/generator.ml) to regenerate all the - * output files. Note that if you are using a separate build directory you - * must run generator.ml from the _source_ directory. + * After editing this file, run it (./src/generator.ml) to regenerate + * all the output files. 'make' will rerun this automatically when + * necessary. Note that if you are using a separate build directory + * you must run generator.ml from the _source_ directory. * * IMPORTANT: This script should NOT print any warnings. If it prints * warnings, you should treat them as errors. - * [Need to add -warn-error to ocaml command line] + * + * OCaml tips: + * (1) In emacs, install tuareg-mode to display and format OCaml code + * correctly. 'vim' comes with a good OCaml editing mode by default. + * (2) Read the resources at http://ocaml-tutorial.org/ *) #load "unix.cma";; #load "str.cma";; +#directory "+xml-light";; +#directory "+../pkg-lib/xml-light";; (* for GODI users *) +#load "xml-light.cma";; +open Unix open Printf type style = ret * args @@ -91,7 +101,7 @@ and ret = (* "RStruct" is a function which returns a single named structure * or an error indication (in C, a struct, and in other languages * with varying representations, but usually very efficient). See - * after the function list below for the structures. + * after the function list below for the structures. *) | RStruct of string * string (* name of retval, name of struct *) @@ -135,10 +145,15 @@ and args = argt list (* Function parameters, guestfs handle is implicit. *) *) and argt = | String of string (* const char *name, cannot be NULL *) + | Device of string (* /dev device name, cannot be NULL *) + | Pathname of string (* file name, cannot be NULL *) + | Dev_or_Path of string (* /dev device name or Pathname, cannot be NULL *) | OptString of string (* const char *name, may be NULL *) | StringList of string(* list of strings (each string cannot be NULL) *) + | DeviceList of string(* list of Device names (each cannot be NULL) *) | Bool of string (* boolean *) | Int of string (* int (smallish ints, signed, <= 31 bits) *) + | Int64 of string (* any 64 bit int *) (* 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. @@ -149,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. @@ -160,28 +174,41 @@ and argt = * To return an arbitrary buffer, use RBufferOut. *) | BufferIn of string -*) + (* Key material / passphrase. Eventually we should treat this + * as sensitive and mlock it into physical RAM. However this + * is highly complex because of all the places that XDR-encoded + * strings can end up. So currently the only difference from + * 'String' is the way that guestfish requests these parameters + * from the user. + *) + | Key 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 *) | DeprecatedBy of string (* function is deprecated, use .. instead *) + | Optional of string (* function is part of an optional group *) + | Progress (* function can generate progress messages *) + +and fish_output_t = + | FishOutputOctal (* for int return, print in octal *) + | FishOutputHexadecimal (* for int return, print in hex *) (* 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), and - * a fourth squashfs block device with some known files on it (/dev/sdd). + * a fourth ISO block device with some known files on it (/dev/sdd). * * Note for partitioning purposes, the 500MB device has 1015 cylinders. * Number of cylinders was 63 for IDE emulated disks with precisely * the same size. How exactly this is calculated is a mystery. * - * The squashfs block device (/dev/sdd) comes from images/test.sqsh. + * The ISO block device (/dev/sdd) comes from images/test.iso. * * To be able to run the tests in a reasonable amount of time, * the virtual machine and block devices are reused between tests. @@ -207,45 +234,60 @@ type tests = (test_init * test_prereq * test) list and test = (* Run the command sequence and just expect nothing to fail. *) | TestRun of seq + (* Run the command sequence and expect the output of the final * command to be the string. *) | TestOutput of seq * string + (* Run the command sequence and expect the output of the final * command to be the list of strings. *) | TestOutputList of seq * string list + (* Run the command sequence and expect the output of the final * command to be the list of block devices (could be either * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th * character of each string). *) | TestOutputListOfDevices of seq * string list + (* Run the command sequence and expect the output of the final * command to be the integer. *) | TestOutputInt of seq * int + (* Run the command sequence and expect the output of the final * command to be , eg. ">=", "1". *) | TestOutputIntOp of seq * string * int + (* Run the command sequence and expect the output of the final * command to be a true value (!= 0 or != NULL). *) | TestOutputTrue of seq + (* Run the command sequence and expect the output of the final * command to be a false value (== 0 or == NULL, but not an error). *) | TestOutputFalse of seq + (* Run the command sequence and expect the output of the final * command to be a list of the given length (but don't care about * content). *) | 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 + (* Run the command sequence and expect the final command (only) * to fail. *) @@ -262,17 +304,23 @@ and test_field_compare = 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 + (* Run the test only if 'string' is available in the daemon. *) + | IfAvailable of string + (* Some initial scenarios for testing. *) and test_init = (* Do nothing, block devices could contain random stuff including @@ -284,6 +332,12 @@ and test_init = (* Block devices are empty and no filesystems are mounted. *) | InitEmpty + (* /dev/sda contains a single partition /dev/sda1, with random + * content. /dev/sdb and /dev/sdc may have random content. + * No LVM. + *) + | InitPartition + (* /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. @@ -299,10 +353,10 @@ and test_init = *) | InitBasicFSonLVM - (* /dev/sdd (the squashfs, see images/ directory in source) + (* /dev/sdd (the ISO, see images/ directory in source) * is mounted on / *) - | InitSquashFS + | InitISOFS (* Sequence of commands for testing. *) and seq = cmd list @@ -316,6 +370,19 @@ and cmd = string list * Apart from that, long descriptions are just perldoc paragraphs. *) +(* Generate a random UUID (used in tests). *) +let uuidgen () = + let chan = open_process_in "uuidgen" in + let uuid = input_line chan in + (match close_process_in chan with + | WEXITED 0 -> () + | WEXITED _ -> + failwith "uuidgen: process exited with non-zero status" + | WSIGNALED _ | WSTOPPED _ -> + failwith "uuidgen: process signalled or stopped by signal" + ); + uuid + (* These test functions are used in the language binding tests. *) let test_all_args = [ @@ -324,8 +391,10 @@ let test_all_args = [ StringList "strlist"; Bool "b"; Int "integer"; + Int64 "integer64"; FileIn "filein"; FileOut "fileout"; + BufferIn "bufferin"; ] let test_all_rets = [ @@ -358,9 +427,9 @@ You probably don't want to call this function."); List.map ( fun (name, ret) -> [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs], - [], - "internal test function - do not use", - "\ + [], + "internal test function - do not use", + "\ This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly. @@ -369,9 +438,9 @@ It converts string C to the return type. You probably don't want to call this function."); (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs], - [], - "internal test function - do not use", - "\ + [], + "internal test function - do not use", + "\ This is an internal test function which is used to test whether the automatically generated bindings can handle every possible return type correctly. @@ -388,7 +457,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", "\ @@ -400,13 +469,18 @@ You should call this after configuring the handle ("wait_ready", (RErr, []), -1, [NotInFish], [], - "wait until the qemu subprocess launches", + "wait until the qemu subprocess launches (no op)", "\ -Internally libguestfs is implemented by running a virtual machine -using L. +This function is a no op. + +In versions of the API E 1.0.71 you had to call this function +just after calling C to wait for the launch +to complete. However this is no longer necessary because +C now does the waiting. -You should call this after C to wait for the launch -to complete."); +If you see any calls to this function in code then you can just +remove them, unless you want to retain compatibility with older +versions of the API."); ("kill_subprocess", (RErr, []), -1, [], [], @@ -432,6 +506,14 @@ image). This is equivalent to the qemu parameter C<-drive file=filename,cache=off,if=...>. +C is omitted in cases where it is not supported by +the underlying filesystem. + +C is set at compile time by the configuration option +C<./configure --with-drive-if=...>. In the rare case where you +might need to change this at run time, use C +or C. + Note that this call checks for the existence of C. This stops you from specifying other types of drive which are supported by qemu such as C and C URLs. To specify those, use @@ -445,10 +527,24 @@ This function adds a virtual CD-ROM disk image to the guest. This is equivalent to the qemu parameter C<-cdrom filename>. -Note that this call checks for the existence of C. This +Notes: + +=over 4 + +=item * + +This call checks for the existence of C. This stops you from specifying other types of drive which are supported by qemu such as C and C URLs. To specify those, use -the general C call instead."); +the general C call instead. + +=item * + +If you just want to add an ISO file (often you use this as an +efficient way to transfer large files into the guest), then you +should probably use C instead. + +=back"); ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"], [], @@ -466,6 +562,11 @@ changes to be committed, although qemu can support this. This is equivalent to the qemu parameter C<-drive file=filename,snapshot=on,if=...>. +C is set at compile time by the configuration option +C<./configure --with-drive-if=...>. In the rare case where you +might need to change this at run time, use C +or C. + Note that this call checks for the existence of C. This stops you from specifying other types of drive which are supported by qemu such as C and C URLs. To specify those, use @@ -484,7 +585,7 @@ The first character of C string must be a C<-> (dash). C can be NULL."); - ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"], + ("set_qemu", (RErr, [OptString "qemu"]), -1, [FishAlias "qemu"], [], "set the qemu binary", "\ @@ -496,7 +597,15 @@ configure script. You can also override this by setting the C environment variable. -Setting C to C restores the default qemu binary."); +Setting C to C restores the default qemu binary. + +Note that you should call this function as early as possible +after creating the handle. This is because some pre-launch +operations depend on testing qemu features (by running C). +If the qemu binary changes, we don't retest features, and +so you might see inconsistent results. Using the environment +variable C is safest of all since that picks +the qemu binary at the same time as the handle is created."); ("get_qemu", (RConstString "qemu", []), -1, [], [InitNone, Always, TestRun ( @@ -508,7 +617,7 @@ Return the current qemu binary. This is always non-NULL. If it wasn't set already, then this will return the default qemu binary name."); - ("set_path", (RErr, [String "path"]), -1, [FishAlias "path"], + ("set_path", (RErr, [OptString "searchpath"]), -1, [FishAlias "path"], [], "set the search path", "\ @@ -638,34 +747,6 @@ only useful for printing debug and internal error messages. For more information on states, see L."); - ("set_busy", (RErr, []), -1, [NotInFish], - [], - "set state to busy", - "\ -This sets the state to C. This is only used when implementing -actions using the low-level API. - -For more information on states, see L."); - - ("set_ready", (RErr, []), -1, [NotInFish], - [], - "set state to ready", - "\ -This sets the state to C. This is only used when implementing -actions using the low-level API. - -For more information on states, see L."); - - ("end_busy", (RErr, []), -1, [NotInFish], - [], - "leave the busy state", - "\ -This sets the state to C, or if in C then it leaves the -state as is. This is only used when implementing -actions using the low-level API. - -For more information on states, see L."); - ("set_memsize", (RErr, [Int "memsize"]), -1, [FishAlias "memsize"], [InitNone, Always, TestOutputInt ( [["set_memsize"; "500"]; @@ -723,8 +804,9 @@ against a completely different C library. This call was added in version C<1.0.58>. In previous versions of libguestfs there was no way to get the version -number. From C code you can use ELF weak linking tricks to find out if -this symbol exists (if it doesn't, then it's an earlier version). +number. From C code you can use dynamic linker functions +to find out if this symbol exists (if it doesn't, then +it's an earlier version). The call returns a structure with four elements. The first three (C, C and C) are numbers and @@ -735,536 +817,647 @@ used for distro-specific information. To construct the original version string: C<$major.$minor.$release$extra> -I Don't use this call to test for availability -of features. Distro backports makes this unreliable."); - -] +See also: L. -(* daemon_functions are any functions which cause some action - * to take place in the daemon. - *) +I Don't use this call to test for availability +of features. In enterprise distributions we backport +features from later versions into earlier versions, +making this an unreliable way to test for features. +Use C instead."); -let daemon_functions = [ - ("mount", (RErr, [String "device"; String "mountpoint"]), 1, [], - [InitEmpty, Always, TestOutput ( - [["sfdiskM"; "/dev/sda"; ","]; - ["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", + ("set_selinux", (RErr, [Bool "selinux"]), -1, [FishAlias "selinux"], + [InitNone, Always, TestOutputTrue ( + [["set_selinux"; "true"]; + ["get_selinux"]])], + "set SELinux enabled or disabled at appliance boot", "\ -Mount a guest disk at a position in the filesystem. Block devices -are named C, C 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 rules are the same as for L: A filesystem must -first be mounted on C before others can be mounted. Other -filesystems can only be mounted on directories which already -exist. +This sets the selinux flag that is passed to the appliance +at boot time. The default is C (disabled). -The mounted filesystem is writable, if we have sufficient permissions -on the underlying device. +Note that if SELinux is enabled, it is always in +Permissive mode (C). -The filesystem options C and C are set with this -call, in order to improve reliability."); +For more information on the architecture of libguestfs, +see L."); - ("sync", (RErr, []), 2, [], - [ InitEmpty, Always, TestRun [["sync"]]], - "sync disks, writes are flushed through to the disk image", + ("get_selinux", (RBool "selinux", []), -1, [], + [], + "get SELinux enabled flag", "\ -This syncs the disk, so that any writes are flushed through to the -underlying disk image. +This returns the current setting of the selinux flag which +is passed to the appliance at boot time. See C. -You should always call this if you have modified a disk image, before -closing the handle."); +For more information on the architecture of libguestfs, +see L."); - ("touch", (RErr, [String "path"]), 3, [], - [InitBasicFS, Always, TestOutputTrue ( - [["touch"; "/new"]; - ["exists"; "/new"]])], - "update file timestamps or create a new file", + ("set_trace", (RErr, [Bool "trace"]), -1, [FishAlias "trace"], + [InitNone, Always, TestOutputFalse ( + [["set_trace"; "false"]; + ["get_trace"]])], + "enable or disable command traces", "\ -Touch acts like the L 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."); +If the command trace flag is set to 1, then commands are +printed on stderr before they are executed in a format +which is very similar to the one used by guestfish. In +other words, you can run a program with this enabled, and +you will get out a script which you can feed to guestfish +to perform the same set of actions. - ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning], - [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. +If you want to trace C API calls into libguestfs (and +other libraries) then possibly a better way is to use +the external ltrace(1) command. -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 -or C functions which have a more complex interface."); +Command traces are disabled unless the environment variable +C is defined and set to C<1>."); - ("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)", + ("get_trace", (RBool "trace", []), -1, [], + [], + "get command trace enabled flag", "\ -List the files in C (relative to the root directory, -there is no cwd) in the format of 'ls -la'. - -This command is mostly useful for interactive sessions. It -is I intended that you try to parse the output string."); +Return the command trace flag."); - ("ls", (RStringList "listing", [String "directory"]), 6, [], - [InitBasicFS, Always, TestOutputList ( - [["touch"; "/new"]; - ["touch"; "/newer"]; - ["touch"; "/newest"]; - ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])], - "list the files in a directory", + ("set_direct", (RErr, [Bool "direct"]), -1, [FishAlias "direct"], + [InitNone, Always, TestOutputFalse ( + [["set_direct"; "false"]; + ["get_direct"]])], + "enable or disable direct appliance mode", "\ -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. +If the direct appliance mode flag is enabled, then stdin and +stdout are passed directly through to the appliance once it +is launched. -This command is mostly useful for interactive sessions. Programs -should probably use C instead."); +One consequence of this is that log messages aren't caught +by the library and handled by C, +but go straight to stdout. - ("list_devices", (RStringList "devices", []), 7, [], - [InitEmpty, Always, TestOutputListOfDevices ( - [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])], - "list the block devices", - "\ -List all the block devices. +You probably don't want to use this unless you know what you +are doing. -The full block device names are returned, eg. C"); +The default is disabled."); - ("list_partitions", (RStringList "partitions", []), 8, [], - [InitBasicFS, Always, TestOutputListOfDevices ( - [["list_partitions"]], ["/dev/sda1"]); - InitEmpty, Always, TestOutputListOfDevices ( - [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; - ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])], - "list the partitions", + ("get_direct", (RBool "direct", []), -1, [], + [], + "get direct appliance mode flag", "\ -List all the partitions detected on all block devices. - -The full partition device names are returned, eg. C - -This does not return logical volumes. For that you will need to -call C."); +Return the direct appliance mode flag."); - ("pvs", (RStringList "physvols", []), 9, [], - [InitBasicFSonLVM, Always, TestOutputListOfDevices ( - [["pvs"]], ["/dev/sda1"]); - InitEmpty, Always, TestOutputListOfDevices ( - [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; - ["pvcreate"; "/dev/sda1"]; - ["pvcreate"; "/dev/sda2"]; - ["pvcreate"; "/dev/sda3"]; - ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])], - "list the LVM physical volumes (PVs)", + ("set_recovery_proc", (RErr, [Bool "recoveryproc"]), -1, [FishAlias "recovery-proc"], + [InitNone, Always, TestOutputTrue ( + [["set_recovery_proc"; "true"]; + ["get_recovery_proc"]])], + "enable or disable the recovery process", "\ -List all the physical volumes detected. This is the equivalent -of the L command. +If this is called with the parameter C then +C does not create a recovery process. The +purpose of the recovery process is to stop runaway qemu +processes in the case where the main program aborts abruptly. -This returns a list of just the device names that contain -PVs (eg. C). +This only has any effect if called before C, +and the default is true. -See also C."); +About the only time when you would want to disable this is +if the main process will fork itself into the background +(\"daemonize\" itself). In this case the recovery process +thinks that the main program has disappeared and so kills +qemu, which is not very helpful."); - ("vgs", (RStringList "volgroups", []), 10, [], - [InitBasicFSonLVM, Always, TestOutputList ( - [["vgs"]], ["VG"]); - InitEmpty, Always, TestOutputList ( - [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; - ["pvcreate"; "/dev/sda1"]; - ["pvcreate"; "/dev/sda2"]; - ["pvcreate"; "/dev/sda3"]; - ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"]; - ["vgcreate"; "VG2"; "/dev/sda3"]; - ["vgs"]], ["VG1"; "VG2"])], - "list the LVM volume groups (VGs)", + ("get_recovery_proc", (RBool "recoveryproc", []), -1, [], + [], + "get recovery process enabled flag", "\ -List all the volumes groups detected. This is the equivalent -of the L command. +Return the recovery process enabled flag."); -This returns a list of just the volume group names that were -detected (eg. C). + ("add_drive_with_if", (RErr, [String "filename"; String "iface"]), -1, [], + [], + "add a drive specifying the QEMU block emulation to use", + "\ +This is the same as C but it allows you +to specify the QEMU interface emulation to use at run time."); -See also C."); + ("add_drive_ro_with_if", (RErr, [String "filename"; String "iface"]), -1, [], + [], + "add a drive read-only specifying the QEMU block emulation to use", + "\ +This is the same as C but it allows you +to specify the QEMU interface emulation to use at run time."); + + ("file_architecture", (RString "arch", [Pathname "filename"]), -1, [], + [InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-i586-dynamic"]], "i386"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-sparc-dynamic"]], "sparc"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-win32.exe"]], "i386"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-win64.exe"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/bin-x86_64-dynamic"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-i586.so"]], "i386"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-sparc.so"]], "sparc"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-win32.dll"]], "i386"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-win64.dll"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/lib-x86_64.so"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/initrd-x86_64.img"]], "x86_64"); + InitISOFS, Always, TestOutput ( + [["file_architecture"; "/initrd-x86_64.img.gz"]], "x86_64");], + "detect the architecture of a binary file", + "\ +This detects the architecture of the binary C, +and returns it if known. + +Currently defined architectures are: - ("lvs", (RStringList "logvols", []), 11, [], - [InitBasicFSonLVM, Always, TestOutputList ( - [["lvs"]], ["/dev/VG/LV"]); - InitEmpty, Always, TestOutputList ( - [["sfdiskM"; "/dev/sda"; ",100 ,200 ,"]; - ["pvcreate"; "/dev/sda1"]; - ["pvcreate"; "/dev/sda2"]; - ["pvcreate"; "/dev/sda3"]; - ["vgcreate"; "VG1"; "/dev/sda1 /dev/sda2"]; - ["vgcreate"; "VG2"; "/dev/sda3"]; - ["lvcreate"; "LV1"; "VG1"; "50"]; - ["lvcreate"; "LV2"; "VG1"; "50"]; - ["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. +=over 4 -This returns a list of the logical volume device names -(eg. C). +=item \"i386\" -See also C."); +This string is returned for all 32 bit i386, i486, i586, i686 binaries +irrespective of the precise processor requirements of the binary. - ("pvs_full", (RStructList ("physvols", "lvm_pv"), []), 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."); +=item \"x86_64\" - ("vgs_full", (RStructList ("volgroups", "lvm_vg"), []), 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."); +64 bit x86-64. - ("lvs_full", (RStructList ("logvols", "lvm_lv"), []), 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."); +=item \"sparc\" - ("read_lines", (RStringList "lines", [String "path"]), 15, [], - [InitBasicFS, Always, TestOutputList ( - [["write_file"; "/new"; "line1\r\nline2\nline3"; "0"]; - ["read_lines"; "/new"]], ["line1"; "line2"; "line3"]); - InitBasicFS, Always, TestOutputList ( - [["write_file"; "/new"; ""; "0"]; - ["read_lines"; "/new"]], [])], - "read file as lines", - "\ -Return the contents of the file named C. +32 bit SPARC. -The file contents are returned as a list of lines. Trailing -C and C character sequences are I returned. +=item \"sparc64\" -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."); +64 bit SPARC V9 and above. - ("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. -If there was any previous Augeas handle associated with this -guestfs session, then it is closed. +=item \"ia64\" -You must call this before using any other C -commands. +Intel Itanium. -C is the filesystem root. C must not be NULL, -use C instead. +=item \"ppc\" -The flags are the same as the flags defined in -Eaugeas.hE, the logical I of the following -integers: +32 bit Power PC. -=over 4 +=item \"ppc64\" -=item C = 1 +64 bit Power PC. -Keep the original file with a C<.augsave> extension. +=back -=item C = 2 +Libguestfs may return other architecture strings in future. -Save changes into a file with extension C<.augnew>, and -do not overwrite original. Overrides C. +The function works on at least the following types of files: -=item C = 4 +=over 4 -Typecheck lenses (can be expensive). +=item * -=item C = 8 +many types of Un*x and Linux binary -Do not use standard load path for modules. +=item * -=item C = 16 +many types of Un*x and Linux shared library -Make save a no-op, just record what would have been changed. +=item * -=item C = 32 +Windows Win32 and Win64 binaries -Do not load the tree in C. +=item * + +Windows Win32 and Win64 DLLs + +Win32 binaries and DLLs return C. + +Win64 binaries and DLLs return C. + +=item * + +Linux kernel modules + +=item * + +Linux new-style initrd images + +=item * + +some non-x86 Linux vmlinuz kernels =back -To close the handle, you can call C. +What it can't do currently: -To find out more about Augeas, see L."); +=over 4 - ("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."); +=item * - ("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. +static libraries (libfoo.a) -On success this returns the number of nodes in C, or -C<0> if C evaluates to something which is not a nodeset."); +=item * - ("aug_defnode", (RStruct ("nrnodescreated", "int_bool"), [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. +Linux old-style initrd as compressed ext2 filesystem (RHEL 3) -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. +=item * -On success this returns a pair containing the -number of nodes in the nodeset, and a boolean flag -if a node was created."); +x86 Linux vmlinuz kernels - ("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."); +x86 vmlinuz images (bzImage format) consist of a mix of 16-, 32- and +compressed code, and are horribly hard to unpack. If you want to find +the architecture of a kernel, use the architecture of the associated +initrd or kernel module(s) instead. - ("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."); +=back"); - ("aug_insert", (RErr, [String "path"; String "label"; Bool "before"]), 21, [], - [], (* XXX Augeas code needs tests. *) - "insert a sibling Augeas node", + ("inspect_os", (RStringList "roots", []), -1, [], + [], + "inspect disk and return list of operating systems found", "\ -Create a new sibling C