FUNCTIONS

reg_import

 reg_import ($fh, ($h|$map), [encoding => "UTF-16LE"]);

This function imports the registry keys from file handle $fh either into the hive $h or via a map function.

The hive handle $h must have been opened for writing, ie. using the "write => 1" flag to "Win::Hivex->open".

In the binary hive file, the first part of the key name (eg. "HKEY_LOCAL_MACHINE\SOFTWARE") is not stored. You just have to know (somehow) that this maps to the "SOFTWARE" hive. Therefore if you are given a file containing a mixture of keys that have to be added to different hives, you have to have a way to map these to the hive handles. This is outside the scope of the hivex library, but if the second argument is a CODEREF (ie. reference to a function) then this $map function is called on each key name:

 map ($keyname)
 ==> ($h, $keyname)

As shown, the function should return a pair, hive handle, and the true key name (with the prefix stripped off). For example:

 sub map {
   if ($_[0] =~ /^HKEY_LOCAL_MACHINE\\SOFTWARE(.*)/i) {
     return ($software_h, $1);
   } else ...
 }

"encoding" is the encoding used by default for strings. If not specified, this defaults to "UTF-16LE", however we highly advise you to specify it. See "ENCODING STRINGS" below.

As with the regedit program, we merge the new registry keys with existing ones, and new node values with old ones. You can use the "-" (minus) character to delete individual keys and values. This is explained in detail in the Wikipedia page on the Windows Registry.

Remember you need to call "$h->commit (undef)" on the hivex handle before any changes are written to the hive file. See "WRITING TO HIVE FILES" in hivex(3).

reg_export

 reg_export ($h, $key, $fh,
             [prefix => $prefix],
             [unsafe_printable_strings => 1]);

This function exports the registry keys starting at the root $key and recursively downwards into the file handle $fh.

$key is a case-insensitive path of the node to start from, relative to the root of the hive. It is an error if this path does not exist. Path elements should be separated by backslash characters.

$prefix is prefixed to each key name. The usual use for this is to make key names appear as they would on Windows. For example the key "\Foo" in the SOFTWARE Registry, with $prefix "HKEY_LOCAL_MACHINE\SOFTWARE", would be written as:

 [HKEY_LOCAL_MACHINE\SOFTWARE\Foo]
 "Key 1"=...
 "Key 2"=...

If "unsafe_printable_strings" is not given or is false, then the output is written as pure 7 bit ASCII, with line endings which are the default for the local host. Strings are always encoded as hex bytes. This is safe because it preserves the original content and encoding of strings. See "ENCODING STRINGS" below.

If "unsafe_printable_strings" is true, then strings are assumed to be UTF-16LE and are converted to UTF-8 for output. The final zero codepoint in the string is removed if there is one. This is unsafe because it does not preserve the fidelity of the strings in the Registry and because the content type of strings is not always UTF-16LE. However it is useful if you just want to display strings for quick hacking and debugging.

You may need to convert the file's encoding using iconv(1) and line endings using unix2dos(1) if sending to a Windows user.

Nodes and keys are sorted alphabetically in the output.

This function does not print a header. The real regedit program will print a header like:

 Windows Registry Editor Version 5.00

followed by a blank line. (Other headers are possible, see the Wikipedia page on the Windows Registry). If you want a header, you need to write it out yourself.

reg_export_node

 reg_export_node ($h, $node, $fh, ...);

This is exactly the same as "reg_export" except that instead of specifying the path to a key as a string, you pass a hivex library $node handle.