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       node_name
50            $string = $h->node_name ($node)
51
52           Return the name of the node.
53
54           Note that the name of the root node is a dummy, such as
55           "$$$PROTO.HIV" (other names are possible: it seems to depend on the
56           tool or program that created the hive in the first place).  You can
57           only know the "real" name of the root node by knowing which
58           registry file this hive originally comes from, which is knowledge
59           that is outside the scope of this library.
60
61       node_children
62            @nodes = $h->node_children ($node)
63
64           Return an array of nodes which are the subkeys (children) of
65           "node".
66
67           This returns a list of node handles.
68
69       node_get_child
70            $node = $h->node_get_child ($node, $name)
71
72           Return the child of node with the name "name", if it exists.
73
74           The name is matched case insensitively.
75
76           This returns a node handle, or "undef" if the node was not found.
77
78       node_parent
79            $node = $h->node_parent ($node)
80
81           Return the parent of "node".
82
83           The parent pointer of the root node in registry files that we have
84           examined seems to be invalid, and so this function will return an
85           error if called on the root node.
86
87           This returns a node handle.
88
89       node_values
90            @values = $h->node_values ($node)
91
92           Return the array of (key, value) pairs attached to this node.
93
94           This returns a list of value handles.
95
96       node_get_value
97            $value = $h->node_get_value ($node, $key)
98
99           Return the value attached to this node which has the name "key", if
100           it exists.
101
102           The key name is matched case insensitively.
103
104           Note that to get the default key, you should pass the empty string
105           "" here.  The default key is often written "@", but inside hives
106           that has no meaning and won't give you the default key.
107
108           This returns a value handle.
109
110       value_key
111            $string = $h->value_key ($val)
112
113           Return the key (name) of a (key, value) pair.  The name is
114           reencoded as UTF-8 and returned as a string.
115
116           The string should be freed by the caller when it is no longer
117           needed.
118
119           Note that this function can return a zero-length string.  In the
120           context of Windows Registries, this means that this value is the
121           default key for this node in the tree.  This is usually written as
122           "@".
123
124       value_type
125            ($type, $len) = $h->value_type ($val)
126
127           Return the data length and data type of the value in this (key,
128           value) pair.  See also "value_value" which returns all this
129           information, and the value itself.  Also, "value_*" functions below
130           which can be used to return the value in a more useful form when
131           you know the type in advance.
132
133       value_value
134            ($type, $data) = $h->value_value ($val)
135
136           Return the value of this (key, value) pair.  The value should be
137           interpreted according to its type (see "hive_type").
138
139       value_string
140            $string = $h->value_string ($val)
141
142           If this value is a string, return the string reencoded as UTF-8 (as
143           a C string).  This only works for values which have type
144           "hive_t_string", "hive_t_expand_string" or "hive_t_link".
145
146       value_multiple_strings
147            @strings = $h->value_multiple_strings ($val)
148
149           If this value is a multiple-string, return the strings reencoded as
150           UTF-8 (in C, as a NULL-terminated array of C strings, in other
151           language bindings, as a list of strings).  This only works for
152           values which have type "hive_t_multiple_strings".
153
154       value_dword
155            $int32 = $h->value_dword ($val)
156
157           If this value is a DWORD (Windows int32), return it.  This only
158           works for values which have type "hive_t_dword" or
159           "hive_t_dword_be".
160
161       value_qword
162            $int64 = $h->value_qword ($val)
163
164           If this value is a QWORD (Windows int64), return it.  This only
165           works for values which have type "hive_t_qword".
166
167       commit
168            $h->commit ([$filename|undef])
169
170           Commit (write) any changes which have been made.
171
172           "filename" is the new file to write.  If "filename" is
173           null/undefined then we overwrite the original file (ie. the file
174           name that was passed to "open").
175
176           Note this does not close the hive handle.  You can perform further
177           operations on the hive after committing, including making more
178           modifications.  If you no longer wish to use the hive, then you
179           should close the handle after committing.
180
181       node_add_child
182            $node = $h->node_add_child ($parent, $name)
183
184           Add a new child node named "name" to the existing node "parent".
185           The new child initially has no subnodes and contains no keys or
186           values.  The sk-record (security descriptor) is inherited from the
187           parent.
188
189           The parent must not have an existing child called "name", so if you
190           want to overwrite an existing child, call "node_delete_child"
191           first.
192
193           This returns a node handle.
194
195       node_delete_child
196            $h->node_delete_child ($node)
197
198           Delete the node "node".  All values at the node and all subnodes
199           are deleted (recursively).  The "node" handle and the handles of
200           all subnodes become invalid.  You cannot delete the root node.
201
202       node_set_values
203            $h->node_set_values ($node, \@values)
204
205           This call can be used to set all the (key, value) pairs stored in
206           "node".
207
208           "node" is the node to modify.
209
210           @values is an array of (keys, value) pairs.  Each element should be
211           a hashref containing "key", "t" (type) and "data".
212
213           Any existing values stored at the node are discarded, and their
214           "value" handles become invalid.  Thus you can remove all values
215           stored at "node" by passing "@values = []".
216
217       node_set_value
218            $h->node_set_value ($node, $val)
219
220           This call can be used to replace a single "(key, value)" pair
221           stored in "node".  If the key does not already exist, then a new
222           key is added.  Key matching is case insensitive.
223
224           "node" is the node to modify.
225

COPYRIGHT

227       Copyright (C) 2009-2010 Red Hat Inc.
228

LICENSE

230       Please see the file COPYING.LIB for the full license.
231