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

COPYRIGHT

272       Copyright (C) 2009-2011 Red Hat Inc.
273

LICENSE

275       Please see the file COPYING.LIB for the full license.
276