Win::Hivex::Regedit(3pm)

1Win::Hivex::Regedit(3)User Contributed Perl DocumentationWin::Hivex::Regedit(3)
2
3
4

NAME

6       Win::Hivex::Regedit - Helper for reading and writing regedit format
7       files
8

SYNOPSIS

10        use Win::Hivex;
11        use Win::Hivex::Regedit qw(reg_import reg_export);
12
13        $h = Win::Hivex->open ('SOFTWARE', write => 1);
14
15        open FILE, "updates.reg";
16        reg_import (\*FILE, $h);
17        $h->commit (undef);
18
19        reg_export ($h, "\\Microsoft\\Windows NT\\CurrentVersion", \*OUTFILE,
20           prefix => "HKEY_LOCAL_MACHINE\\SOFTWARE");
21

DESCRIPTION

23       Win::Hivex::Regedit is a helper library for reading and writing the
24       Windows regedit (or ".REG") file format.  This is the textual format
25       that is commonly used on Windows for distributing groups of Windows
26       Registry changes, and this format is read and written by the
27       proprietary "reg.exe" and "regedit.exe" programs supplied with Windows.
28       It is not the same as the binary "hive" format which the hivex library
29       itself can read and write.  Note that the regedit format is not well-
30       specified, and hence deviations can occur between what the Windows
31       program can read/write and what we can read/write.  (Please file bugs
32       for any deviations found).
33
34       Win::Hivex::Regedit is the low-level Perl library.  There is also a
35       command line tool for combining hive files and reg files
36       (hivexregedit(1)).  If you have a Windows virtual machine that you need
37       to merge regedit-format changes into, use the high-level
38       virt-win-reg(1) tool (part of libguestfs tools).
39
40   FUNCTIONS
41   reg_import
42        reg_import ($fh, ($h|$map), [encoding => "UTF-16LE"]);
43
44       This function imports the registry keys from file handle $fh either
45       into the hive $h or via a map function.
46
47       The hive handle $h must have been opened for writing, ie.  using the
48       "write => 1" flag to "Win::Hivex->open".
49
50       In the binary hive file, the first part of the key name (eg.
51       "HKEY_LOCAL_MACHINE\SOFTWARE") is not stored.  You just have to know
52       (somehow) that this maps to the "SOFTWARE" hive.  Therefore if you are
53       given a file containing a mixture of keys that have to be added to
54       different hives, you have to have a way to map these to the hive
55       handles.  This is outside the scope of the hivex library, but if the
56       second argument is a CODEREF (ie. reference to a function) then this
57       $map function is called on each key name:
58
59        map ($keyname)
60        ==> ($h, $keyname)
61
62       As shown, the function should return a pair, hive handle, and the true
63       key name (with the prefix stripped off).  For example:
64
65        sub map {
66          if ($_[0] =~ /^HKEY_LOCAL_MACHINE\\SOFTWARE(.*)/i) {
67            return ($software_h, $1);
68          } else ...
69        }
70
71       "encoding" is the encoding used by default for strings.  If not
72       specified, this defaults to "UTF-16LE", however we highly advise you to
73       specify it.  See "ENCODING STRINGS" below.
74
75       As with the regedit program, we merge the new registry keys with
76       existing ones, and new node values with old ones.  You can use the "-"
77       (minus) character to delete individual keys and values.  This is
78       explained in detail in the Wikipedia page on the Windows Registry.
79
80       Remember you need to call "$h->commit (undef)" on the hivex handle
81       before any changes are written to the hive file.  See "WRITING TO HIVE
82       FILES" in hivex(3).
83
84   reg_export
85        reg_export ($h, $key, $fh,
86                    [prefix => $prefix],
87                    [unsafe_printable_strings => 1]);
88
89       This function exports the registry keys starting at the root $key and
90       recursively downwards into the file handle $fh.
91
92       $key is a case-insensitive path of the node to start from, relative to
93       the root of the hive.  It is an error if this path does not exist.
94       Path elements should be separated by backslash characters.
95
96       $prefix is prefixed to each key name.  The usual use for this is to
97       make key names appear as they would on Windows.  For example the key
98       "\Foo" in the SOFTWARE Registry, with $prefix
99       "HKEY_LOCAL_MACHINE\SOFTWARE", would be written as:
100
101        [HKEY_LOCAL_MACHINE\SOFTWARE\Foo]
102        "Key 1"=...
103        "Key 2"=...
104
105       If "unsafe_printable_strings" is not given or is false, then the output
106       is written as pure 7 bit ASCII, with line endings which are the default
107       for the local host.  Strings are always encoded as hex bytes.  This is
108       safe because it preserves the original content and encoding of strings.
109       See "ENCODING STRINGS" below.
110
111       If "unsafe_printable_strings" is true, then strings are assumed to be
112       UTF-16LE and are converted to UTF-8 for output.  The final zero
113       codepoint in the string is removed if there is one.  This is unsafe
114       because it does not preserve the fidelity of the strings in the
115       Registry and because the content type of strings is not always
116       UTF-16LE.  However it is useful if you just want to display strings for
117       quick hacking and debugging.
118
119       You may need to convert the file's encoding using iconv(1) and line
120       endings using unix2dos(1) if sending to a Windows user.
121
122       Nodes and keys are sorted alphabetically in the output.
123
124       This function does not print a header.  The real regedit program will
125       print a header like:
126
127        Windows Registry Editor Version 5.00
128
129       followed by a blank line.  (Other headers are possible, see the
130       Wikipedia page on the Windows Registry).  If you want a header, you
131       need to write it out yourself.
132
133   reg_export_node
134        reg_export_node ($h, $node, $fh, ...);
135
136       This is exactly the same as "reg_export" except that instead of
137       specifying the path to a key as a string, you pass a hivex library
138       $node handle.
139

ENCODING STRINGS

141       The situation with encoding strings in the Registry on Windows is very
142       confused.  There are two main encodings that you would find in the
143       binary (hive) file, 7 bit ASCII and UTF-16LE.  (Other encodings are
144       possible, it's also possible to have arbitrary binary data incorrectly
145       marked with a string type).
146
147       The hive file itself doesn't contain any indication of string encoding.
148       Windows probably guesses the encoding.
149
150       We think that regedit probably either guesses which encoding to use
151       based on the file encoding, or else has different defaults for
152       different versions of Windows.  Neither choice is appropriate for a
153       tool used in a real operating system.
154
155       When using "reg_import", you should specify the default encoding for
156       strings using the "encoding" parameter.  If not specified, it defaults
157       to UTF-16LE.
158
159       The file itself that is imported should be in the local encoding for
160       files (usually UTF-8 on modern Linux systems).  This means if you
161       receive a regedit file from a Windows system, you may sometimes have to
162       reencode it:
163
164        iconv -f utf-16le -t utf-8 < input.reg | dos2unix > output.reg
165
166       When writing regedit files ("reg_export") we bypass this madness
167       completely.  All strings (even pure ASCII) are written as hex bytes so
168       there is no doubt about how they should be encoded when they are read
169       back in.
170

COPYRIGHT

172       Copyright (C) 2010-2011 Red Hat Inc.
173

LICENSE

175       Please see the file COPYING.LIB for the full license.
176

NAME

SYNOPSIS

DESCRIPTION

ENCODING STRINGS

COPYRIGHT

LICENSE

SEE ALSO