libhivex is a library for extracting the contents of Windows Registry
"hive" files. It is designed to be secure against buggy or malicious
-registry files, and to have limited functionality (writing or
-modifying these files is not in the scope of this library).
+registry files.
Unlike many other tools in this area, it doesn't use the textual .REG
format for output, because parsing that is as much trouble as parsing
Opens the hive named C<filename> for reading.
Flags is an ORed list of the open flags (or C<0> if you don't
-want to pass any flags). Currently the only
-flags defined are:
+want to pass any flags). These flags are defined:
=over 4
This is also selected if the C<HIVEX_DEBUG> environment variable
is set to 1.
+=item HIVEX_OPEN_WRITE
+
+Open the hive for writing. If omitted, the hive is read-only.
+
+See L</WRITING TO HIVE FILES>.
+
=back
C<hivex_open> returns a hive handle. On error this returns NULL and
Close a hive handle and free all associated resources.
+Note that any uncommitted writes are I<not> committed by this call,
+but instead are lost. See L</WRITING TO HIVE FILES>.
+
Returns 0 on success. On error this returns -1 and sets errno.
=back
=over 4
+=item hive_node_h
+
+This is a node handle, an integer but opaque outside the library.
+Valid node handles cannot be 0. The library returns 0 in some
+situations to indicate an error.
+
=item hive_node_h hivex_root (hive_h *h);
Return root node of the hive. All valid registries must contain
=over 4
+=item hive_value_h
+
+This is a value handle, an integer but opaque outside the library.
+Valid value handles cannot be 0. The library returns 0 in some
+situations to indicate an error.
+
=item hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
Return the 0-terminated array of (key, value) pairs attached to
=item char *hivex_value_value (hive_h *h, hive_value_h value, hive_type *t, size_t *len);
Return the value of this (key, value) pair. The value should
-be interpreted according to its type (see C<hive_type>).
+be interpreted according to its type (see C<enum hive_type>).
The value is returned in an array of bytes of length C<len>.
hive_type t, size_t len, const char *key, const char *value);
int (*value_other) (hive_h *, void *opaque, hive_node_h, hive_value_h,
hive_type t, size_t len, const char *key, const char *value);
+ /* If value_any callback is not NULL, then the other value_*
+ * callbacks are not used, and value_any is called on all values.
+ */
+ int (*value_any) (hive_h *, void *opaque, hive_node_h, hive_value_h,
+ hive_type t, size_t len, const char *key, const char *value);
};
=over 4
empty string for the default key). The value is a typed object
(eg. string, int32, binary, etc.).
+=head2 RELATIONSHIP TO .REG FILES
+
+Although this library does not care about or deal with Windows reg
+files, it's useful to look at the relationship between the registry
+itself and reg files because they are so common.
+
+A reg file is a text representation of the registry, or part of the
+registry. The actual registry hives that Windows uses are binary
+files. There are a number of Windows and Linux tools that let you
+generate reg files, or merge reg files back into the registry hives.
+Notable amongst them is Microsoft's REGEDIT program (formerly known as
+REGEDT32).
+
+A typical reg file will contain many sections looking like this:
+
+ [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
+ "@"="Generic Stack"
+ "TileInfo"="prop:System.FileCount"
+ "TilePath"=str(2):"%systemroot%\\system32"
+ "ThumbnailCutoff"=dword:00000000
+ "FriendlyTypeName"=hex(2):40,00,25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,00,\
+ 6f,00,74,00,25,00,5c,00,53,00,79,00,73,00,74,00,65,00,6d,00,\
+ 33,00,32,00,5c,00,73,00,65,00,61,00,72,00,63,00,68,00,66,00,\
+ 6f,00,6c,00,64,00,65,00,72,00,2e,00,64,00,6c,00,6c,00,2c,00,\
+ 2d,00,39,00,30,00,32,00,38,00,00,00,d8
+
+Taking this one piece at a time:
+
+ [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Stack]
+
+This is the path to this node in the registry tree. The first part,
+C<HKEY_LOCAL_MACHINE\SOFTWARE> means that this comes from a hive
+(file) called C<SOFTWARE>. C<\Classes\Stack> is the real path part,
+starting at the root node of the C<SOFTWARE> hive.
+
+Below the node name is a list of zero or more key-value pairs. Any
+interior or leaf node in the registry may have key-value pairs
+attached.
+
+ "@"="Generic Stack"
+
+This is the "default key". In reality (ie. inside the binary hive)
+the key string is the empty string. In reg files this is written as
+C<@> but this has no meaning either in the hives themselves or in this
+library. The value is a string (type 1 - see C<enum hive_type>
+above).
+
+ "TileInfo"="prop:System.FileCount"
+
+This is a regular (key, value) pair, with the value being a type 1
+string. Note that inside the binary file the string is likely to be
+UTF-16 encoded. This library converts to and from UTF-8 strings
+transparently.
+
+ "TilePath"=str(2):"%systemroot%\\system32"
+
+The value in this case has type 2 (expanded string) meaning that some
+%...% variables get expanded by Windows. (This library doesn't know
+or care about variable expansion).
+
+ "ThumbnailCutoff"=dword:00000000
+
+The value in this case is a dword (type 4).
+
+ "FriendlyTypeName"=hex(2):40,00,....
+
+This value is an expanded string (type 2) represented in the reg file
+as a series of hex bytes. In this case the string appears to be a
+UTF-16 string.
+
=head1 NOTE ON THE USE OF ERRNO
-Many functions in this library set errno to indicate errors.
-These are the values of errno you may encounter:
+Many functions in this library set errno to indicate errors. These
+are the values of errno you may encounter (this list is not
+exhaustive):
=over 4
=back
+=head1 ENVIRONMENT VARIABLES
+
+=over 4
+
+=item HIVEX_DEBUG
+
+Setting HIVEX_DEBUG=1 will enable very verbose messages. This is
+useful for debugging problems with the library itself.
+
+=back
+
=head1 SEE ALSO
L<hivexml(1)>,
L<guestfs(3)>,
L<http://libguestfs.org/>,
L<virt-cat(1)>,
-L<virt-edit(1)>.
+L<virt-edit(1)>,
+L<http://en.wikipedia.org/wiki/Windows_Registry>.
=head1 AUTHORS
=head1 COPYRIGHT
-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009-2010 Red Hat Inc.
Derived from code by Petter Nordahl-Hagen under a compatible license:
-Copyright (c) 1997-2007 Petter Nordahl-Hagen.
+Copyright (C) 1997-2007 Petter Nordahl-Hagen.
Derived from code by Markus Stephany under a compatible license:
-Copyright (c)2000-2004, Markus Stephany.
+Copyright (C) 2000-2004 Markus Stephany.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
git.annexia.org / libguestfs.git / blobdiff