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_parent
108            $node = $h->node_parent ($node)
109
110           Return the parent of "node".
111
112           The parent pointer of the root node in registry files that we have
113           examined seems to be invalid, and so this function will return an
114           error if called on the root node.
115
116           This returns a node handle.
117
118       node_values
119            @values = $h->node_values ($node)
120
121           Return the array of (key, value) pairs attached to this node.
122
123           This returns a list of value handles.
124
125       node_get_value
126            $value = $h->node_get_value ($node, $key)
127
128           Return the value attached to this node which has the name "key", if
129           it exists.
130
131           The key name is matched case insensitively.
132
133           Note that to get the default key, you should pass the empty string
134           "" here.  The default key is often written "@", but inside hives
135           that has no meaning and won't give you the default key.
136
137           This returns a value handle.
138
139       value_key_len
140            $size = $h->value_key_len ($val)
141
142           Return the length of the key (name) of a (key, value) pair as
143           produced by "value_key". The length can legitimately be 0, so errno
144           is the necessary mechanism to check for errors.
145
146           In the context of Windows Registries, a zero-length name means that
147           this value is the default key for this node in the tree.  This is
148           usually written as "@".
149
150           The key is recoded to UTF-8 and may contain embedded NUL
151           characters.
152
153           This returns a size.
154
155       value_key
156            $string = $h->value_key ($val)
157
158           Return the key (name) of a (key, value) pair.  The name is
159           reencoded as UTF-8 and returned as a string.
160
161           The string should be freed by the caller when it is no longer
162           needed.
163
164           Note that this function can return a zero-length string.  In the
165           context of Windows Registries, this means that this value is the
166           default key for this node in the tree.  This is usually written as
167           "@".
168
169       value_type
170            ($type, $len) = $h->value_type ($val)
171
172           Return the data length and data type of the value in this (key,
173           value) pair.  See also "value_value" which returns all this
174           information, and the value itself.  Also, "value_*" functions below
175           which can be used to return the value in a more useful form when
176           you know the type in advance.
177
178       node_struct_length
179            $size = $h->node_struct_length ($node)
180
181           Return the length of the node data structure.
182
183           This returns a size.
184
185       value_struct_length
186            $size = $h->value_struct_length ($val)
187
188           Return the length of the value data structure.
189
190           This returns a size.
191
192       value_data_cell_offset
193            ($len, $value) = $h->value_data_cell_offset ($val)
194
195           Return the offset and length of the value's data cell.
196
197           The data cell is a registry structure that contains the length (a 4
198           byte, little endian integer) followed by the data.
199
200           If the length of the value is less than or equal to 4 bytes then
201           the offset and length returned by this function is zero as the data
202           is inlined in the value.
203
204           Returns 0 and sets errno on error.
205
206       value_value
207            ($type, $data) = $h->value_value ($val)
208
209           Return the value of this (key, value) pair.  The value should be
210           interpreted according to its type (see "hive_type").
211
212       value_string
213            $string = $h->value_string ($val)
214
215           If this value is a string, return the string reencoded as UTF-8 (as
216           a C string).  This only works for values which have type
217           "hive_t_string", "hive_t_expand_string" or "hive_t_link".
218
219       value_multiple_strings
220            @strings = $h->value_multiple_strings ($val)
221
222           If this value is a multiple-string, return the strings reencoded as
223           UTF-8 (in C, as a NULL-terminated array of C strings, in other
224           language bindings, as a list of strings).  This only works for
225           values which have type "hive_t_multiple_strings".
226
227       value_dword
228            $int32 = $h->value_dword ($val)
229
230           If this value is a DWORD (Windows int32), return it.  This only
231           works for values which have type "hive_t_dword" or
232           "hive_t_dword_be".
233
234       value_qword
235            $int64 = $h->value_qword ($val)
236
237           If this value is a QWORD (Windows int64), return it.  This only
238           works for values which have type "hive_t_qword".
239
240       commit
241            $h->commit ([$filename|undef])
242
243           Commit (write) any changes which have been made.
244
245           "filename" is the new file to write.  If "filename" is
246           null/undefined then we overwrite the original file (ie. the file
247           name that was passed to "open").
248
249           Note this does not close the hive handle.  You can perform further
250           operations on the hive after committing, including making more
251           modifications.  If you no longer wish to use the hive, then you
252           should close the handle after committing.
253
254       node_add_child
255            $node = $h->node_add_child ($parent, $name)
256
257           Add a new child node named "name" to the existing node "parent".
258           The new child initially has no subnodes and contains no keys or
259           values.  The sk-record (security descriptor) is inherited from the
260           parent.
261
262           The parent must not have an existing child called "name", so if you
263           want to overwrite an existing child, call "node_delete_child"
264           first.
265
266           This returns a node handle.
267
268       node_delete_child
269            $h->node_delete_child ($node)
270
271           Delete the node "node".  All values at the node and all subnodes
272           are deleted (recursively).  The "node" handle and the handles of
273           all subnodes become invalid.  You cannot delete the root node.
274
275       node_set_values
276            $h->node_set_values ($node, \@values)
277
278           This call can be used to set all the (key, value) pairs stored in
279           "node".
280
281           "node" is the node to modify.
282
283           @values is an array of (keys, value) pairs.  Each element should be
284           a hashref containing "key", "t" (type) and "data".
285
286           Any existing values stored at the node are discarded, and their
287           "value" handles become invalid.  Thus you can remove all values
288           stored at "node" by passing "@values = []".
289
290       node_set_value
291            $h->node_set_value ($node, $val)
292
293           This call can be used to replace a single "(key, value)" pair
294           stored in "node".  If the key does not already exist, then a new
295           key is added.  Key matching is case insensitive.
296
297           "node" is the node to modify.
298

COPYRIGHT

300       Copyright (C) 2009-2017 Red Hat Inc.
301

LICENSE

303       Please see the file COPYING.LIB for the full license.
304