Win::Hivex(3pm)

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

NAME

6       Win::Hivex - Perl bindings for reading and writing Windows Registry
7       hive files
8

SYNOPSIS

10        use Win::Hivex;
11
12        $h = Win::Hivex->open ('SOFTWARE');
13        $root_node = $h->root ();
14        print $h->node_name ($root_node);
15

DESCRIPTION

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

ERRORS

21       All errors turn into calls to "croak" (see Carp(3)).
22

METHODS

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

COPYRIGHT

315       Copyright (C) 2009-2022 Red Hat Inc.
316

LICENSE

318       Please see the file COPYING.LIB for the full license.
319