1Win::Hivex(3) User Contributed Perl Documentation Win::Hivex(3)
2
3
4
6 Win::Hivex - Perl bindings for reading and writing Windows Registry
7 hive files
8
10 use Win::Hivex;
11
12 $h = Win::Hivex->open ('SOFTWARE');
13 $root_node = $h->root ();
14 print $h->node_name ($root_node);
15
17 The "Win::Hivex" module provides a Perl XS binding to the hivex(3) API
18 for reading and writing Windows Registry binary hive files.
19
21 All errors turn into calls to "croak" (see Carp(3)).
22
24 open
25 $h = Win::Hivex->open ($filename,
26 [verbose => 1,]
27 [debug => 1,]
28 [write => 1,]
29 [unsafe => 1,])
30
31 Open a Windows Registry binary hive file.
32
33 The "verbose" and "debug" flags enable different levels of
34 debugging messages.
35
36 The "write" flag is required if you will be modifying the hive file
37 (see "WRITING TO HIVE FILES" in hivex(3)).
38
39 This function returns a hive handle. The hive handle is closed
40 automatically when its reference count drops to 0.
41
42 root
43 $node = $h->root ()
44
45 Return root node of the hive. All valid hives must contain a root
46 node.
47
48 This returns a node handle.
49
50 last_modified
51 $int64 = $h->last_modified ()
52
53 Return the modification time from the header of the hive.
54
55 The returned value is a Windows filetime. To convert this to a
56 Unix "time_t" see:
57 <http://stackoverflow.com/questions/6161776/convert-windows-filetime-to-second-in-unix-linux/6161842#6161842>
58
59 node_name
60 $string = $h->node_name ($node)
61
62 Return the name of the node.
63
64 Note that the name of the root node is a dummy, such as
65 "$$$PROTO.HIV" (other names are possible: it seems to depend on the
66 tool or program that created the hive in the first place). You can
67 only know the "real" name of the root node by knowing which
68 registry file this hive originally comes from, which is knowledge
69 that is outside the scope of this library.
70
71 The name is recoded to UTF-8 and may contain embedded NUL
72 characters.
73
74 node_name_len
75 $size = $h->node_name_len ($node)
76
77 Return the length of the node name as produced by "node_name".
78
79 This returns a size.
80
81 node_timestamp
82 $int64 = $h->node_timestamp ($node)
83
84 Return the modification time of the node.
85
86 The returned value is a Windows filetime. To convert this to a
87 Unix "time_t" see:
88 <http://stackoverflow.com/questions/6161776/convert-windows-filetime-to-second-in-unix-linux/6161842#6161842>
89
90 node_children
91 @nodes = $h->node_children ($node)
92
93 Return an array of nodes which are the subkeys (children) of
94 "node".
95
96 This returns a list of node handles.
97
98 node_get_child
99 $node = $h->node_get_child ($node, $name)
100
101 Return the child of node with the name "name", if it exists.
102
103 The name is matched case insensitively.
104
105 This returns a node handle, or "undef" if the node was not found.
106
107 node_nr_children
108 $size = $h->node_nr_children ($node)
109
110 Return the number of nodes as produced by "node_children".
111
112 This returns a size.
113
114 node_parent
115 $node = $h->node_parent ($node)
116
117 Return the parent of "node".
118
119 The parent pointer of the root node in registry files that we have
120 examined seems to be invalid, and so this function will return an
121 error if called on the root node.
122
123 This returns a node handle.
124
125 node_values
126 @values = $h->node_values ($node)
127
128 Return the array of (key, value) pairs attached to this node.
129
130 This returns a list of value handles.
131
132 node_get_value
133 $value = $h->node_get_value ($node, $key)
134
135 Return the value attached to this node which has the name "key", if
136 it exists.
137
138 The key name is matched case insensitively.
139
140 Note that to get the default key, you should pass the empty string
141 "" here. The default key is often written "@", but inside hives
142 that has no meaning and won't give you the default key.
143
144 This returns a value handle.
145
146 node_nr_values
147 $size = $h->node_nr_values ($node)
148
149 Return the number of (key, value) pairs attached to this node as
150 produced by "node_values".
151
152 This returns a size.
153
154 value_key_len
155 $size = $h->value_key_len ($val)
156
157 Return the length of the key (name) of a (key, value) pair as
158 produced by "value_key". The length can legitimately be 0, so errno
159 is the necessary mechanism to check for errors.
160
161 In the context of Windows Registries, a zero-length name means that
162 this value is the default key for this node in the tree. This is
163 usually written as "@".
164
165 The key is recoded to UTF-8 and may contain embedded NUL
166 characters.
167
168 This returns a size.
169
170 value_key
171 $string = $h->value_key ($val)
172
173 Return the key (name) of a (key, value) pair. The name is
174 reencoded as UTF-8 and returned as a string.
175
176 The string should be freed by the caller when it is no longer
177 needed.
178
179 Note that this function can return a zero-length string. In the
180 context of Windows Registries, this means that this value is the
181 default key for this node in the tree. This is usually written as
182 "@".
183
184 value_type
185 ($type, $len) = $h->value_type ($val)
186
187 Return the data length and data type of the value in this (key,
188 value) pair. See also "value_value" which returns all this
189 information, and the value itself. Also, "value_*" functions below
190 which can be used to return the value in a more useful form when
191 you know the type in advance.
192
193 node_struct_length
194 $size = $h->node_struct_length ($node)
195
196 Return the length of the node data structure.
197
198 This returns a size.
199
200 value_struct_length
201 $size = $h->value_struct_length ($val)
202
203 Return the length of the value data structure.
204
205 This returns a size.
206
207 value_data_cell_offset
208 ($len, $value) = $h->value_data_cell_offset ($val)
209
210 Return the offset and length of the value's data cell.
211
212 The data cell is a registry structure that contains the length (a 4
213 byte, little endian integer) followed by the data.
214
215 If the length of the value is less than or equal to 4 bytes then
216 the offset and length returned by this function is zero as the data
217 is inlined in the value.
218
219 Returns 0 and sets errno on error.
220
221 value_value
222 ($type, $data) = $h->value_value ($val)
223
224 Return the value of this (key, value) pair. The value should be
225 interpreted according to its type (see "hive_type").
226
227 value_string
228 $string = $h->value_string ($val)
229
230 If this value is a string, return the string reencoded as UTF-8 (as
231 a C string). This only works for values which have type
232 "hive_t_string", "hive_t_expand_string" or "hive_t_link".
233
234 value_multiple_strings
235 @strings = $h->value_multiple_strings ($val)
236
237 If this value is a multiple-string, return the strings reencoded as
238 UTF-8 (in C, as a NULL-terminated array of C strings, in other
239 language bindings, as a list of strings). This only works for
240 values which have type "hive_t_multiple_strings".
241
242 value_dword
243 $int32 = $h->value_dword ($val)
244
245 If this value is a DWORD (Windows int32), return it. This only
246 works for values which have type "hive_t_dword" or
247 "hive_t_dword_be".
248
249 value_qword
250 $int64 = $h->value_qword ($val)
251
252 If this value is a QWORD (Windows int64), return it. This only
253 works for values which have type "hive_t_qword".
254
255 commit
256 $h->commit ([$filename|undef])
257
258 Commit (write) any changes which have been made.
259
260 "filename" is the new file to write. If "filename" is
261 null/undefined then we overwrite the original file (ie. the file
262 name that was passed to "open").
263
264 Note this does not close the hive handle. You can perform further
265 operations on the hive after committing, including making more
266 modifications. If you no longer wish to use the hive, then you
267 should close the handle after committing.
268
269 node_add_child
270 $node = $h->node_add_child ($parent, $name)
271
272 Add a new child node named "name" to the existing node "parent".
273 The new child initially has no subnodes and contains no keys or
274 values. The sk-record (security descriptor) is inherited from the
275 parent.
276
277 The parent must not have an existing child called "name", so if you
278 want to overwrite an existing child, call "node_delete_child"
279 first.
280
281 This returns a node handle.
282
283 node_delete_child
284 $h->node_delete_child ($node)
285
286 Delete the node "node". All values at the node and all subnodes
287 are deleted (recursively). The "node" handle and the handles of
288 all subnodes become invalid. You cannot delete the root node.
289
290 node_set_values
291 $h->node_set_values ($node, \@values)
292
293 This call can be used to set all the (key, value) pairs stored in
294 "node".
295
296 "node" is the node to modify.
297
298 @values is an array of (keys, value) pairs. Each element should be
299 a hashref containing "key", "t" (type) and "data".
300
301 Any existing values stored at the node are discarded, and their
302 "value" handles become invalid. Thus you can remove all values
303 stored at "node" by passing "@values = []".
304
305 node_set_value
306 $h->node_set_value ($node, $val)
307
308 This call can be used to replace a single "(key, value)" pair
309 stored in "node". If the key does not already exist, then a new
310 key is added. Key matching is case insensitive.
311
312 "node" is the node to modify.
313
315 Copyright (C) 2009-2021 Red Hat Inc.
316
318 Please see the file COPYING.LIB for the full license.
319
321 hivex(3), hivexsh(1), <http://libguestfs.org>, Sys::Guestfs(3).
322
323
324
325perl v5.34.0 2021-08-02 Win::Hivex(3)