git.annexia.org / libguestfs.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
hivex: Add HIVEX_OPEN_WRITE flag to allow hive to be opened for writing.
[libguestfs.git] / hivex / hivex.pod
diff --git a/hivex/hivex.pod b/hivex/hivex.pod
index 1078bf1..5a58144 100644 (file)
--- a/hivex/hivex.pod
+++ b/hivex/hivex.pod
@@ -13,8 +13,7 @@ hivex - Windows Registry "hive" extraction library
 
 libhivex is a library for extracting the contents of Windows Registry
 "hive" files.  It is designed to be secure against buggy or malicious
 
 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
 
 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
@@ -32,8 +31,7 @@ L<hivexget(1)>).
 Opens the hive named C<filename> for reading.
 
 Flags is an ORed list of the open flags (or C<0> if you don't
 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
 
 
 =over 4
 
@@ -49,6 +47,12 @@ itself.
 This is also selected if the C<HIVEX_DEBUG> environment variable
 is set to 1.
 
 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
 =back
 
 C<hivex_open> returns a hive handle.  On error this returns NULL and
@@ -58,6 +62,9 @@ sets C<errno> to indicate the error.
 
 Close a hive handle and free all associated resources.
 
 
 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
 Returns 0 on success.  On error this returns -1 and sets errno.
 
 =back
@@ -66,6 +73,12 @@ Returns 0 on success.  On error this returns -1 and sets errno.
 
 =over 4
 
 
 =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
 =item hive_node_h hivex_root (hive_h *h);
 
 Return root node of the hive.  All valid registries must contain
@@ -143,6 +156,12 @@ stored at each node.
 
 =over 4
 
 
 =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 hive_value_h *hivex_node_values (hive_h *h, hive_node_h node);
 
 Return the 0-terminated array of (key, value) pairs attached to
@@ -195,7 +214,7 @@ Returns 0 on success.  On error this returns -1 and sets errno.
 =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
 =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>.
 
 
 The value is returned in an array of bytes of length C<len>.
 
@@ -269,6 +288,11 @@ all, set the function pointer to NULL.
          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);
          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
  };
 
 =over 4
@@ -325,10 +349,81 @@ stored in the registry.  The key is always a string (possibly the
 empty string for the default key).  The value is a typed object
 (eg. string, int32, binary, etc.).
 
 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
 
 =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
 
 
 =over 4
 
@@ -359,6 +454,17 @@ Field in the registry out of range.
 
 =back
 
 
 =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)>,
 =head1 SEE ALSO
 
 L<hivexml(1)>,
@@ -367,7 +473,8 @@ L<virt-win-reg(1)>,
 L<guestfs(3)>,
 L<http://libguestfs.org/>,
 L<virt-cat(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 AUTHORS
 
@@ -375,13 +482,13 @@ Richard W.M. Jones (C<rjones at redhat dot com>)
 
 =head1 COPYRIGHT
 
 
 =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:
 
 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:
 
 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
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
[MOVED TO GITHUB] library for accessing and modifying guest disk images