regfi
Data Structures | Functions
Base Layer: Essential Functions and Data Structures

These functions are either necessary for normal use of the regfi API or just don't fit particularly well in any of the other layers. More...

Data Structures

struct  REGFI_CLASSNAME
 Class name structure (used in storing SysKeys) More...
 
struct  REGFI_DATA
 Data record structure. More...
 
struct  REGFI_VK
 Value structure. More...
 
struct  REGFI_SK
 Security structure. More...
 
struct  REGFI_NK
 Key structure. More...
 
struct  REGFI_FILE
 Registry hive file data structure. More...
 

Functions

const char * regfi_version ()
 Returns the current regfi library version. More...
 
REGFI_FILEregfi_alloc (int fd, REGFI_ENCODING output_encoding)
 Parses file headers of an already open registry hive file and allocates related structures for further parsing. More...
 
REGFI_FILEregfi_alloc_cb (REGFI_RAW_FILE *file_cb, REGFI_ENCODING output_encoding)
 Parses file headers returned by supplied callback functions. More...
 
void regfi_free (REGFI_FILE *file)
 Frees a hive's data structures without closing the underlying file. More...
 
char * regfi_log_get_str ()
 Get errors, warnings, and/or verbose information relating to processing of the given registry file. More...
 
bool regfi_log_set_mask (uint16_t mask)
 Set the verbosity level of messages generated by the library for the current thread. More...
 
const REGFI_NKregfi_get_rootkey (REGFI_FILE *file)
 Fetches a hive's root key. More...
 
void regfi_free_record (REGFI_FILE *file, const void *record)
 Frees a record previously returned by one of the API functions. More...
 
const void * regfi_reference_record (REGFI_FILE *file, const void *record)
 Increments reference count on record. More...
 
uint32_t regfi_fetch_num_subkeys (const REGFI_NK *key)
 Retrieves number of subkeys referenced by this key. More...
 
uint32_t regfi_fetch_num_values (const REGFI_NK *key)
 Retrieves number of values referenced by this key. More...
 
const REGFI_CLASSNAMEregfi_fetch_classname (REGFI_FILE *file, const REGFI_NK *key)
 Retrieves classname for a given key. More...
 
const REGFI_SKregfi_fetch_sk (REGFI_FILE *file, const REGFI_NK *key)
 Returns the SK (security) record referenced by the supplied key. More...
 
const REGFI_SKregfi_next_sk (REGFI_FILE *file, const REGFI_SK *sk)
 Returns the next SK (security) record referenced by the supplied SK record. More...
 
const REGFI_SKregfi_prev_sk (REGFI_FILE *file, const REGFI_SK *sk)
 Returns the previous SK (security) record referenced by the supplied SK record. More...
 
const REGFI_DATAregfi_fetch_data (REGFI_FILE *file, const REGFI_VK *value)
 Retrieves data for a given value. More...
 
bool regfi_find_subkey (REGFI_FILE *file, const REGFI_NK *key, const char *name, uint32_t *index)
 Locates a specific subkey of a given key. More...
 
bool regfi_find_value (REGFI_FILE *file, const REGFI_NK *key, const char *name, uint32_t *index)
 Locates a specific value of a given key. More...
 
const REGFI_NKregfi_get_subkey (REGFI_FILE *file, const REGFI_NK *key, uint32_t index)
 Retrieves a specific subkey of a given key. More...
 
const REGFI_VKregfi_get_value (REGFI_FILE *file, const REGFI_NK *key, uint32_t index)
 Retrieves a specific value of a given key. More...
 
const REGFI_NKregfi_get_parentkey (REGFI_FILE *file, const REGFI_NK *key)
 Uses a key's parent_off reference to retrieve it's parent. More...
 

Detailed Description

These functions are either necessary for normal use of the regfi API or just don't fit particularly well in any of the other layers.

Function Documentation

◆ regfi_version()

const char* regfi_version ( )

Returns the current regfi library version.

Returns
A string indicating the version.

◆ regfi_alloc()

REGFI_FILE* regfi_alloc ( int  fd,
REGFI_ENCODING  output_encoding 
)

Parses file headers of an already open registry hive file and allocates related structures for further parsing.

Parameters
fdA file descriptor of an already open file. Must be seekable.
output_encodingCharacter encoding that strings should be returned in. Only supply the REGFI_ENCODING_* constants, as others will be rejected. The following values are currently accepted: REGFI_ENCODING_DEFAULT (currently REGFI_ENCODING_ASCII) REGFI_ENCODING_ASCII REGFI_ENCODING_UTF8
Returns
A reference to a newly allocated REGFI_FILE structure, if successful; NULL on error. Use regfi_free to free the returned REGFI_FILE.

◆ regfi_alloc_cb()

REGFI_FILE* regfi_alloc_cb ( REGFI_RAW_FILE file_cb,
REGFI_ENCODING  output_encoding 
)

Parses file headers returned by supplied callback functions.

This interface is useful if you have a registry hive in memory or have some other reason to emulate a real file.

Parameters
file_cbA structure defining the callback functions needed to access the file.
output_encodingCharacter encoding that strings should be returned in. Only supply the REGFI_ENCODING_* constants, as others will be rejected. The following values are currently accepted: REGFI_ENCODING_DEFAULT (currently REGFI_ENCODING_ASCII) REGFI_ENCODING_ASCII REGFI_ENCODING_UTF8
Returns
A reference to a newly allocated REGFI_FILE structure, if successful; NULL on error. Use regfi_free to free the returned REGFI_FILE.

◆ regfi_free()

void regfi_free ( REGFI_FILE file)

Frees a hive's data structures without closing the underlying file.

Parameters
fileThe registry structure to free.

◆ regfi_log_get_str()

char* regfi_log_get_str ( )

Get errors, warnings, and/or verbose information relating to processing of the given registry file.

Returns
A newly allocated char* which must be free()d by the caller.

◆ regfi_log_set_mask()

bool regfi_log_set_mask ( uint16_t  mask)

Set the verbosity level of messages generated by the library for the current thread.

Parameters
maskAn integer representing the types of messages desired. Acceptable values are created through bitwise ORs of REGFI_LOG_* values. For instance, if only errors and informational messages were desired (but not warnings), then one would specify: REGFI_LOG_ERROR|REGFI_LOG_INFO By default the message mask is: REGFI_LOG_ERROR|REGFI_LOG_WARN.
Returns
true on success and false on failure. Failure occurs if underlying pthread functions fail. errno is set in this case.

Message masks are set in a thread-specific way. If one were to set a message mask in one thread and then spawn a new thread, then the new thread will have it's message mask reset to the default. This function may be called at any time and will take effect immediately for the current thread.

Note
When a non-zero message mask is set, messages will accumulate in memory without limit if they are not fetched using regfi_log_get_str and subsequently freed by the caller. It is recommended that messsages be fetched after each regfi API call in order to provide the most context.

◆ regfi_get_rootkey()

const REGFI_NK* regfi_get_rootkey ( REGFI_FILE file)

Fetches a hive's root key.

Returns
Returns the root key or NULL on failure. Key must be freed using regfi_free_record.

◆ regfi_free_record()

void regfi_free_record ( REGFI_FILE file,
const void *  record 
)

Frees a record previously returned by one of the API functions.

Parameters
fileThe file from which the record originated.
(This is needed for memory management reasons.)
recordAny of the following record types: REGFI_NK, REGFI_VK, REGFI_SK, REGFI_DATA, and REGFI_CLASSNAME records.
Note
The "const" in the record data type is a bit misleading and is there just for convenience. Since records returned previously must not be modified by users of the API due to internal caching, these are returned as const, so this function is const to make passing those records back easy.

Referenced by regfi_find_subkey(), regfi_find_value(), and regfi_iterator_down().

◆ regfi_reference_record()

const void* regfi_reference_record ( REGFI_FILE file,
const void *  record 
)

Increments reference count on record.

Adds an extra internal reference to specified record, making it necessary to call regfi_free_record on it an additional time before it is freed. This is useful in cases where multiple threads/structures need access to a shared record, without requiring them to be in sync with when it is freed.

Parameters
fileThe file from which the record originated.
(This is needed for memory management reasons.)
recordAny of the following record types: REGFI_NK, REGFI_VK, REGFI_SK, REGFI_DATA, and REGFI_CLASSNAME records.
Returns
Updated record pointer on success, NULL otherwise
Note
Be sure to use the returned record for further access to the structure instead of the previous version of the pointer. E.g.:
myKey = (const REGFI_NK*)regfi_reference_record(myFile, myKey);
const void * regfi_reference_record(REGFI_FILE *file, const void *record)
Increments reference count on record.
Definition: regfi.c:1788
Key structure.
Definition: regfi.h:607

◆ regfi_fetch_num_subkeys()

uint32_t regfi_fetch_num_subkeys ( const REGFI_NK key)

Retrieves number of subkeys referenced by this key.

Number of subkeyss in key structure and subkey list structure could differ, so this provides a standard/sane way of determining the number.

Parameters
keythe key whose number of subkeys is desired
Returns
Returns the number of subkeys referenced by this key.

References REGFI_NK::num_subkeys, and REGFI_NK::subkeys.

Referenced by regfi_find_subkey(), and regfi_get_subkey().

◆ regfi_fetch_num_values()

uint32_t regfi_fetch_num_values ( const REGFI_NK key)

Retrieves number of values referenced by this key.

Number of values in key structure and value list structure could differ, so this provides a standard/sane way of determining the number.

Parameters
keythe key whose number of values is desired
Returns
Returns the number of values referenced by this key.

References REGFI_NK::num_values, and REGFI_NK::values.

Referenced by regfi_find_value(), and regfi_get_value().

◆ regfi_fetch_classname()

const REGFI_CLASSNAME* regfi_fetch_classname ( REGFI_FILE file,
const REGFI_NK key 
)

Retrieves classname for a given key.

Parameters
filethe file from which key is derived
keythe key whose classname is desired
Returns
Returns a newly allocated classname structure, or NULL on failure. Classname structures must be freed with regfi_free_record.

References REGFI_NK::classname_off.

◆ regfi_fetch_sk()

const REGFI_SK* regfi_fetch_sk ( REGFI_FILE file,
const REGFI_NK key 
)

Returns the SK (security) record referenced by the supplied key.

Parameters
filethe file from which key is derived
keythe key whose SK record is desired
Returns
A read-only SK structure, or NULL on failure.

References REGFI_NK::sk_off.

◆ regfi_next_sk()

const REGFI_SK* regfi_next_sk ( REGFI_FILE file,
const REGFI_SK sk 
)

Returns the next SK (security) record referenced by the supplied SK record.

Parameters
filethe file from which sk is derived
skthe SK record whose next sibling SK record is desired
Returns
A read-only SK structure, or NULL on failure.
Note
SK records are included in a circular, doubly-linked list. To iterate over all SK records, be sure to check for the repetition of the SK record you started with to determine when all have been traversed.

References REGFI_SK::next_sk_off.

◆ regfi_prev_sk()

const REGFI_SK* regfi_prev_sk ( REGFI_FILE file,
const REGFI_SK sk 
)

Returns the previous SK (security) record referenced by the supplied SK record.

Parameters
filethe file from which sk is derived
skthe SK record whose previous sibling SK record is desired
Returns
A read-only SK structure, or NULL on failure.
Note
SK records are included in a circular, doubly-linked list. To iterate over all SK records, be sure to check for the repetition of the SK record you started with to determine when all have been traversed.

References REGFI_SK::prev_sk_off.

◆ regfi_fetch_data()

const REGFI_DATA* regfi_fetch_data ( REGFI_FILE file,
const REGFI_VK value 
)

Retrieves data for a given value.

Parameters
filethe file from which value is derived
valuethe value whose data is desired
Returns
Returns a newly allocated data structure, or NULL on failure. Data structures must be freed with regfi_free_record.

References REGFI_VK::data_in_offset, REGFI_VK::data_off, REGFI_VK::data_size, and regfi_load_data().

◆ regfi_find_subkey()

bool regfi_find_subkey ( REGFI_FILE file,
const REGFI_NK key,
const char *  name,
uint32_t *  index 
)

Locates a specific subkey of a given key.

Parameters
filethe file from which key is derived
keythe key whose subkey is desired
namename of the desired subkey (case-insensitive)
indexa return value: the index of the desired subkey. undefined on error
Returns
true if the subkey is found, false if an error occurred or if the specified name could not be found. If an error occurs, messages will be written explaining the issue. (See regfi_log_get_str.)

References REGFI_NK::name, regfi_fetch_num_subkeys(), regfi_free_record(), and regfi_get_subkey().

◆ regfi_find_value()

bool regfi_find_value ( REGFI_FILE file,
const REGFI_NK key,
const char *  name,
uint32_t *  index 
)

Locates a specific value of a given key.

Parameters
filethe file from which key is derived
keythe key whose value is desired
namename of the desired value (case-insensitive)
indexa return value: the index of the desired value.
undefined on error
Returns
true if the value is found, false if an error occurred or if the specified name could not be found. If an error occurs, messages will be written explaining the issue. (See regfi_log_get_str.)

References REGFI_VK::name, regfi_fetch_num_values(), regfi_free_record(), and regfi_get_value().

◆ regfi_get_subkey()

const REGFI_NK* regfi_get_subkey ( REGFI_FILE file,
const REGFI_NK key,
uint32_t  index 
)

Retrieves a specific subkey of a given key.

Parameters
filethe file from which key is derived
keythe key whose subkey is desired
indexthe index of the desired subkey
Returns
the requested subkey or NULL on error.

References regfi_fetch_num_subkeys(), regfi_load_key(), and REGFI_NK::subkeys.

Referenced by regfi_find_subkey().

◆ regfi_get_value()

const REGFI_VK* regfi_get_value ( REGFI_FILE file,
const REGFI_NK key,
uint32_t  index 
)

Retrieves a specific value of a given key.

Parameters
filethe file from which key is derived
keythe key whose value is desired
indexthe index of the desired value
Returns
the requested value or NULL on error.

References regfi_fetch_num_values(), regfi_load_value(), and REGFI_NK::values.

Referenced by regfi_find_value().

◆ regfi_get_parentkey()

const REGFI_NK* regfi_get_parentkey ( REGFI_FILE file,
const REGFI_NK key 
)

Uses a key's parent_off reference to retrieve it's parent.

Parameters
filethe file from which key is derived
keythe key whose parent is desired
Returns
the requested subkey or NULL on error.

References REGFI_NK::parent_off.