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, [prefix => $prefix]);
86
87       This function exports the registry keys starting at the root $key and
88       recursively downwards into the file handle $fh.
89
90       $key is a case-insensitive path of the node to start from, relative to
91       the root of the hive.  It is an error if this path does not exist.
92       Path elements should be separated by backslash characters.
93
94       $prefix is prefixed to each key name.  The usual use for this is to
95       make key names appear as they would on Windows.  For example the key
96       "\Foo" in the SOFTWARE Registry, with $prefix
97       "HKEY_LOCAL_MACHINE\SOFTWARE", would be written as:
98
99        [HKEY_LOCAL_MACHINE\SOFTWARE\Foo]
100        "Key 1"=...
101        "Key 2"=...
102
103       The output is written as pure 7 bit ASCII, with line endings which are
104       the default for the local host.  You may need to convert the file's
105       encoding using iconv(1) and line endings using unix2dos(1) if sending
106       to a Windows user.  Strings are always encoded as hex bytes.  See
107       "ENCODING STRINGS" below.
108
109       Nodes and keys are sorted alphabetically in the output.
110
111       This function does not print a header.  The real regedit program will
112       print a header like:
113
114        Windows Registry Editor Version 5.00
115
116       followed by a blank line.  (Other headers are possible, see the
117       Wikipedia page on the Windows Registry).  If you want a header, you
118       need to write it out yourself.
119
120   reg_export_node
121        reg_export_node ($h, $node, $fh, ...);
122
123       This is exactly the same as "reg_export" except that instead of
124       specifying the path to a key as a string, you pass a hivex library
125       $node handle.
126

ENCODING STRINGS

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

COPYRIGHT

159       Copyright (C) 2010 Red Hat Inc.
160

LICENSE

162       Please see the file COPYING.LIB for the full license.
163

NAME

SYNOPSIS

DESCRIPTION

ENCODING STRINGS

COPYRIGHT

LICENSE

SEE ALSO