summaryrefslogtreecommitdiffstats
path: root/include/iprt/fuzz.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/iprt/fuzz.h')
-rw-r--r--include/iprt/fuzz.h971
1 files changed, 971 insertions, 0 deletions
diff --git a/include/iprt/fuzz.h b/include/iprt/fuzz.h
new file mode 100644
index 00000000..15f3fe92
--- /dev/null
+++ b/include/iprt/fuzz.h
@@ -0,0 +1,971 @@
+/** @file
+ * IPRT - Fuzzing framework
+ */
+
+/*
+ * Copyright (C) 2018-2023 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef IPRT_INCLUDED_fuzz_h
+#define IPRT_INCLUDED_fuzz_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <iprt/cdefs.h>
+#include <iprt/process.h>
+#include <iprt/types.h>
+
+RT_C_DECLS_BEGIN
+
+/** @defgroup grp_rt_fuzz RTFuzz - Data fuzzing framework
+ * @ingroup grp_rt
+ * @sa grp_rt_test
+ * @{
+ */
+
+/** A fuzzer context handle. */
+typedef struct RTFUZZCTXINT *RTFUZZCTX;
+/** Pointer to a fuzzer context handle. */
+typedef RTFUZZCTX *PRTFUZZCTX;
+/** NIL fuzzer context handle. */
+#define NIL_RTFUZZCTX ((RTFUZZCTX)~(uintptr_t)0)
+/** A fuzzer input handle. */
+typedef struct RTFUZZINPUTINT *RTFUZZINPUT;
+/** Pointer to a fuzzer input handle. */
+typedef RTFUZZINPUT *PRTFUZZINPUT;
+/** NIL fuzzer input handle. */
+#define NIL_RTFUZZINPUT ((RTFUZZINPUT)~(uintptr_t)0)
+
+
+/** A fuzzer config handle. */
+typedef struct RTFUZZCFGINT *RTFUZZCFG;
+/** Pointer to a fuzzer config handle. */
+typedef RTFUZZCFG *PRTFUZZCFG;
+/** NIL fuzzer config handle. */
+#define NIL_RTFUZZCFG ((RTFUZZCFG)~(uintptr_t)0)
+
+
+/** A fuzzer target recorder handler. */
+typedef struct RTFUZZTGTRECINT *RTFUZZTGTREC;
+/** Pointer to a fuzzer target recorder handle. */
+typedef RTFUZZTGTREC *PRTFUZZTGTREC;
+/** NIL fuzzer target recorder handle. */
+#define NIL_RTFUZZTGTREC ((RTFUZZTGTREC)~(uintptr_t)0)
+/** A fuzzed target state handle. */
+typedef struct RTFUZZTGTSTATEINT *RTFUZZTGTSTATE;
+/** Pointer to a fuzzed target state handle. */
+typedef RTFUZZTGTSTATE *PRTFUZZTGTSTATE;
+/** NIL fuzzed target state handle. */
+#define NIL_RTFUZZTGTSTATE ((RTFUZZTGTSTATE)~(uintptr_t)0)
+
+
+/** Fuzzing observer handle. */
+typedef struct RTFUZZOBSINT *RTFUZZOBS;
+/** Pointer to a fuzzing observer handle. */
+typedef RTFUZZOBS *PRTFUZZOBS;
+/** NIL fuzzing observer handle. */
+#define NIL_RTFUZZOBS ((RTFUZZOBS)~(uintptr_t)0)
+
+
+/**
+ * Fuzzing context type.
+ */
+typedef enum RTFUZZCTXTYPE
+{
+ /** Invalid type. */
+ RTFUZZCTXTYPE_INVALID = 0,
+ /** Original input data is a single binary large object (BLOB), from a file or similar. */
+ RTFUZZCTXTYPE_BLOB,
+ /** Original input data is from a data stream like a network connection. */
+ RTFUZZCTXTYPE_STREAM,
+ /** 32bit hack. */
+ RTFUZZCTXTYPE_32BIT_HACK = 0x7fffffff
+} RTFUZZCTXTYPE;
+
+
+/**
+ * Fuzzing context statistics.
+ */
+typedef struct RTFUZZCTXSTATS
+{
+ /** Amount of memory currently allocated. */
+ size_t cbMemory;
+ /** Number of mutations accumulated in the corpus. */
+ uint64_t cMutations;
+} RTFUZZCTXSTATS;
+/** Pointer to fuzzing context statistics. */
+typedef RTFUZZCTXSTATS *PRTFUZZCTXSTATS;
+
+
+/** @name RTFUZZCTX_F_XXX - Flags for RTFuzzCtxCfgSetBehavioralFlags
+ * @{ */
+/** Adds all generated inputs automatically to the input corpus for the owning context. */
+#define RTFUZZCTX_F_BEHAVIORAL_ADD_INPUT_AUTOMATICALLY_TO_CORPUS RT_BIT_32(0)
+/** All valid behavioral modification flags. */
+#define RTFUZZCTX_F_BEHAVIORAL_VALID (RTFUZZCTX_F_BEHAVIORAL_ADD_INPUT_AUTOMATICALLY_TO_CORPUS)
+/** @} */
+
+
+/** @name RTFUZZOBS_SANITIZER_F_XXX - Flags for RTFuzzObsSetTestBinarySanitizers().
+ * @{ */
+/** ASAN is compiled and enabled (observer needs to configure to abort on error to catch memory errors). */
+#define RTFUZZOBS_SANITIZER_F_ASAN UINT32_C(0x00000001)
+/** A converage sanitizer is compiled in which can be used to produce coverage reports aiding in the
+ * fuzzing process. */
+#define RTFUZZOBS_SANITIZER_F_SANCOV UINT32_C(0x00000002)
+/** @} */
+
+
+/** @name RTFUZZTGT_REC_STATE_F_XXX - Flags for RTFuzzTgtRecorderCreate().
+ * @{ */
+/** The output from stdout is used to compare states. */
+#define RTFUZZTGT_REC_STATE_F_STDOUT RT_BIT_32(0)
+/** The output from stderr is used to compare states. */
+#define RTFUZZTGT_REC_STATE_F_STDERR RT_BIT_32(1)
+/** The process status is used to compare states. */
+#define RTFUZZTGT_REC_STATE_F_PROCSTATUS RT_BIT_32(2)
+/** The coverage report is used to compare states. */
+#define RTFUZZTGT_REC_STATE_F_SANCOV RT_BIT_32(3)
+/** Mask of all valid flags. */
+#define RTFUZZTGT_REC_STATE_F_VALID UINT32_C(0x0000000f)
+/** @} */
+
+
+/** @name RTFUZZCFG_IMPORT_F_XXX - Flags for RTFuzzCfgImport().
+ * @{ */
+/** Default flags. */
+#define RTFUZZCFG_IMPORT_F_DEFAULT 0
+/** Adds only the inputs and doesn't set any glboal configuration flags of the fuzzing context. */
+#define RTFUZZCFG_IMPORT_F_ONLY_INPUT RT_BIT_32(0)
+/** Mask of all valid flags. */
+#define RTFUZZCFG_IMPORT_F_VALID UINT32_C(0x00000001)
+/** @} */
+
+
+/**
+ * Fuzzing context state export callback.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx Handle of the fuzzing context.
+ * @param pvBuf The data to write.
+ * @param cbWrite Number of bytes to write.
+ * @param pvUser Opaque user data passed in RTFuzzCtxStateExport().
+ */
+typedef DECLCALLBACKTYPE(int, FNRTFUZZCTXEXPORT,(RTFUZZCTX hFuzzCtx, const void *pvBuf, size_t cbWrite, void *pvUser));
+/** Pointer to a fuzzing context state export callback. */
+typedef FNRTFUZZCTXEXPORT *PFNRTFUZZCTXEXPORT;
+
+/**
+ * Fuzzing context state import callback.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx Handle of the fuzzing context.
+ * @param pvBuf Where to store the read data.
+ * @param cbRead Number of bytes to read.
+ * @param pcbRead Where to store the amount of data written, optional.
+ * @param pvUser Opaque user data passed in RTFuzzCtxCreateFromState().
+ */
+typedef DECLCALLBACKTYPE(int, FNRTFUZZCTXIMPORT,(RTFUZZCTX hFuzzCtx, void *pvBuf, size_t cbRead, size_t *pcbRead, void *pvUser));
+/** Pointer to a fuzzing context state export callback. */
+typedef FNRTFUZZCTXIMPORT *PFNRTFUZZCTXIMPORT;
+
+
+/**
+ * Creates a new fuzzing context.
+ *
+ * @returns IPRT status code.
+ * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
+ * @param enmType Fuzzing context data type.
+ */
+RTDECL(int) RTFuzzCtxCreate(PRTFUZZCTX phFuzzCtx, RTFUZZCTXTYPE enmType);
+
+/**
+ * Creates a new fuzzing context from the given state.
+ *
+ * @returns IPRT status code.
+ * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
+ * @param pfnImport State import callback.
+ * @param pvUser Opaque user data to pass to the callback.
+ */
+RTDECL(int) RTFuzzCtxCreateFromState(PRTFUZZCTX phFuzzCtx, PFNRTFUZZCTXIMPORT pfnImport, void *pvUser);
+
+/**
+ * Creates a new fuzzing context loading the state from the given memory buffer.
+ *
+ * @returns IPRT status code.
+ * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
+ * @param pvState Pointer to the memory containing the state.
+ * @param cbState Size of the state buffer.
+ */
+RTDECL(int) RTFuzzCtxCreateFromStateMem(PRTFUZZCTX phFuzzCtx, const void *pvState, size_t cbState);
+
+/**
+ * Creates a new fuzzing context loading the state from the given file.
+ *
+ * @returns IPRT status code.
+ * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
+ * @param pszFilename File to load the fuzzing context from.
+ */
+RTDECL(int) RTFuzzCtxCreateFromStateFile(PRTFUZZCTX phFuzzCtx, const char *pszFilename);
+
+/**
+ * Retains a reference to the given fuzzing context.
+ *
+ * @returns New reference count on success.
+ * @param hFuzzCtx Handle of the fuzzing context.
+ */
+RTDECL(uint32_t) RTFuzzCtxRetain(RTFUZZCTX hFuzzCtx);
+
+/**
+ * Releases a reference from the given fuzzing context, destroying it when reaching 0.
+ *
+ * @returns New reference count on success, 0 if the fuzzing context got destroyed.
+ * @param hFuzzCtx Handle of the fuzzing context.
+ */
+RTDECL(uint32_t) RTFuzzCtxRelease(RTFUZZCTX hFuzzCtx);
+
+/**
+ * Queries statistics about the given fuzzing context.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx Handle of the fuzzing context.
+ * @param pStats Where to store the stats on success.
+ */
+RTDECL(int) RTFuzzCtxQueryStats(RTFUZZCTX hFuzzCtx, PRTFUZZCTXSTATS pStats);
+
+/**
+ * Exports the given fuzzing context state.
+ *
+ * @returns IPRT statuse code
+ * @param hFuzzCtx The fuzzing context to export.
+ * @param pfnExport Export callback.
+ * @param pvUser Opaque user data to pass to the callback.
+ */
+RTDECL(int) RTFuzzCtxStateExport(RTFUZZCTX hFuzzCtx, PFNRTFUZZCTXEXPORT pfnExport, void *pvUser);
+
+/**
+ * Exports the given fuzzing context state to memory allocating the buffer.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context to export.
+ * @param ppvState Where to store the pointer to the memory containing state on success.
+ * Free with RTMemFree().
+ * @param pcbState Where to store the size of the state in bytes.
+ */
+RTDECL(int) RTFuzzCtxStateExportToMem(RTFUZZCTX hFuzzCtx, void **ppvState, size_t *pcbState);
+
+/**
+ * Exports the given fuzzing context state to the given file.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context to export.
+ * @param pszFilename The file to save the state to.
+ */
+RTDECL(int) RTFuzzCtxStateExportToFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
+
+/**
+ * Adds a new seed to the input corpus of the given fuzzing context.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param pvInput The pointer to the input buffer.
+ * @param cbInput Size of the input buffer.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAdd(RTFUZZCTX hFuzzCtx, const void *pvInput, size_t cbInput);
+
+/**
+ * Adds a new seed to the input corpus of the given fuzzing context - extended version.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param pvInput The pointer to the input buffer.
+ * @param cbInput Size of the input buffer.
+ * @param offMutStart Start offset at which a mutation can happen.
+ * @param cbMutRange Size of the range in bytes where a mutation can happen,
+ * use UINT64_MAX to allow mutations till the end of the input.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAddEx(RTFUZZCTX hFuzzCtx, const void *pvInput, size_t cbInput,
+ uint64_t offMutStart, uint64_t cbMutRange);
+
+/**
+ * Adds a new seed to the input corpus of the given fuzzing context from the given file.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param pszFilename The filename to load the seed from.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAddFromFile(RTFUZZCTX hFuzzCtx, const char *pszFilename);
+
+/**
+ * Adds a new seed to the input corpus of the given fuzzing context from the given file - extended version.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param pszFilename The filename to load the seed from.
+ * @param offMutStart Start offset at which a mutation can happen.
+ * @param cbMutRange Size of the range in bytes where a mutation can happen,
+ * use UINT64_MAX to allow mutations till the end of the input.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAddFromFileEx(RTFUZZCTX hFuzzCtx, const char *pszFilename,
+ uint64_t offMutStart, uint64_t cbMutRange);
+
+/**
+ * Adds a new seed to the input corpus of the given fuzzing context from the given VFS file.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param hVfsFile The VFS file handle to load the seed from.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsFile(RTFUZZCTX hFuzzCtx, RTVFSFILE hVfsFile);
+
+/**
+ * Adds a new seed to the input corpus of the given fuzzing context from the given VFS file - extended version.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param hVfsFile The VFS file handle to load the seed from.
+ * @param offMutStart Start offset at which a mutation can happen.
+ * @param cbMutRange Size of the range in bytes where a mutation can happen,
+ * use UINT64_MAX to allow mutations till the end of the input.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsFileEx(RTFUZZCTX hFuzzCtx, RTVFSFILE hVfsFile,
+ uint64_t offMutStart, uint64_t cbMutRange);
+
+/**
+ * Adds a new seed to the input corpus of the given fuzzing context from the given VFS I/O stream.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param hVfsIos The VFS I/O stream handle to load the seed from.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsIoStrm(RTFUZZCTX hFuzzCtx, RTVFSIOSTREAM hVfsIos);
+
+/**
+ * Adds a new seed to the input corpus of the given fuzzing context from the given VFS I/O stream - extended version.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param hVfsIos The VFS I/O stream handle to load the seed from.
+ * @param offMutStart Start offset at which a mutation can happen.
+ * @param cbMutRange Size of the range in bytes where a mutation can happen,
+ * use UINT64_MAX to allow mutations till the end of the input.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAddFromVfsIoStrmEx(RTFUZZCTX hFuzzCtx, RTVFSIOSTREAM hVfsIos,
+ uint64_t offMutStart, uint64_t cbMutRange);
+
+/**
+ * Adds new seeds to the input corpus of the given fuzzing context from the given directory.
+ *
+ * Will only process regular files, i.e. ignores directories, symbolic links, devices, fifos
+ * and such.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param pszDirPath The directory to load seeds from.
+ */
+RTDECL(int) RTFuzzCtxCorpusInputAddFromDirPath(RTFUZZCTX hFuzzCtx, const char *pszDirPath);
+
+/**
+ * Restricts the maximum input size to generate by the fuzzing context.
+ *
+ * @returns IPRT status code
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param cbMax Maximum input size in bytes.
+ */
+RTDECL(int) RTFuzzCtxCfgSetInputSeedMaximum(RTFUZZCTX hFuzzCtx, size_t cbMax);
+
+/**
+ * Returns the maximum input size of the given fuzzing context.
+ *
+ * @returns Maximum input size generated in bytes.
+ * @param hFuzzCtx The fuzzing context handle.
+ */
+RTDECL(size_t) RTFuzzCtxCfgGetInputSeedMaximum(RTFUZZCTX hFuzzCtx);
+
+/**
+ * Sets flags controlling the behavior of the fuzzing context.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param fFlags Flags controlling the fuzzing context, RTFUZZCTX_F_XXX.
+ */
+RTDECL(int) RTFuzzCtxCfgSetBehavioralFlags(RTFUZZCTX hFuzzCtx, uint32_t fFlags);
+
+/**
+ * Returns the current set behavioral flags for the given fuzzing context.
+ *
+ * @returns Behavioral flags of the given fuzzing context.
+ * @param hFuzzCtx The fuzzing context handle.
+ */
+RTDECL(uint32_t) RTFuzzCfgGetBehavioralFlags(RTFUZZCTX hFuzzCtx);
+
+/**
+ * Sets the temporary directory used by the fuzzing context.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param pszPathTmp The directory for the temporary state.
+ */
+RTDECL(int) RTFuzzCtxCfgSetTmpDirectory(RTFUZZCTX hFuzzCtx, const char *pszPathTmp);
+
+/**
+ * Returns the current temporary directory.
+ *
+ * @returns Current temporary directory.
+ * @param hFuzzCtx The fuzzing context handle.
+ */
+RTDECL(const char *) RTFuzzCtxCfgGetTmpDirectory(RTFUZZCTX hFuzzCtx);
+
+/**
+ * Sets the range in which a particular input can get mutated.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param offStart Start offset at which a mutation can happen.
+ * @param cbRange Size of the range in bytes where a mutation can happen,
+ * use UINT64_MAX to allow mutations till the end of the input.
+ */
+RTDECL(int) RTFuzzCtxCfgSetMutationRange(RTFUZZCTX hFuzzCtx, uint64_t offStart, uint64_t cbRange);
+
+/**
+ * Reseeds the PRNG of the given fuzzing context.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param uSeed The new seed.
+ */
+RTDECL(int) RTFuzzCtxReseed(RTFUZZCTX hFuzzCtx, uint64_t uSeed);
+
+/**
+ * Generates a new input from the given fuzzing context and returns it.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCtx The fuzzing context handle.
+ * @param phFuzzInput Where to store the handle to the fuzzed input on success.
+ */
+RTDECL(int) RTFuzzCtxInputGenerate(RTFUZZCTX hFuzzCtx, PRTFUZZINPUT phFuzzInput);
+
+
+/**
+ * Retains a reference to the given fuzzing input handle.
+ *
+ * @returns New reference count on success.
+ * @param hFuzzInput The fuzzing input handle.
+ */
+RTDECL(uint32_t) RTFuzzInputRetain(RTFUZZINPUT hFuzzInput);
+
+/**
+ * Releases a reference from the given fuzzing input handle, destroying it when reaching 0.
+ *
+ * @returns New reference count on success, 0 if the fuzzing input got destroyed.
+ * @param hFuzzInput The fuzzing input handle.
+ */
+RTDECL(uint32_t) RTFuzzInputRelease(RTFUZZINPUT hFuzzInput);
+
+/**
+ * Queries the data pointer and size of the given fuzzed input blob.
+ *
+ * @returns IPRT status code
+ * @param hFuzzInput The fuzzing input handle.
+ * @param ppv Where to store the pointer to the input data on success.
+ * @param pcb Where to store the size of the input data on success.
+ */
+RTDECL(int) RTFuzzInputQueryBlobData(RTFUZZINPUT hFuzzInput, void **ppv, size_t *pcb);
+
+/**
+ * Processes the given data stream for a streamed fuzzing context.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzInput The fuzzing input handle.
+ * @param pvBuf The data buffer.
+ * @param cbBuf Size of the buffer.
+ */
+RTDECL(int) RTFuzzInputMutateStreamData(RTFUZZINPUT hFuzzInput, void *pvBuf, size_t cbBuf);
+
+/**
+ * Queries the string of the MD5 digest for the given fuzzed input.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the size of the string buffer is not sufficient.
+ * @param hFuzzInput The fuzzing input handle.
+ * @param pszDigest Where to store the digest string and a closing terminator.
+ * @param cchDigest Size of the string buffer in characters (including the zero terminator).
+ */
+RTDECL(int) RTFuzzInputQueryDigestString(RTFUZZINPUT hFuzzInput, char *pszDigest, size_t cchDigest);
+
+/**
+ * Writes the given fuzzing input to the given file.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzInput The fuzzing input handle.
+ * @param pszFilename The filename to store the input to.
+ */
+RTDECL(int) RTFuzzInputWriteToFile(RTFUZZINPUT hFuzzInput, const char *pszFilename);
+
+/**
+ * Adds the given fuzzed input to the input corpus of the owning context.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_ALREADY_EXISTS if the input exists already.
+ * @param hFuzzInput The fuzzing input handle.
+ */
+RTDECL(int) RTFuzzInputAddToCtxCorpus(RTFUZZINPUT hFuzzInput);
+
+/**
+ * Removes the given fuzzed input from the input corpus of the owning context.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_NOT_FOUND if the input is not part of the corpus.
+ * @param hFuzzInput The fuzzing input handle.
+ */
+RTDECL(int) RTFuzzInputRemoveFromCtxCorpus(RTFUZZINPUT hFuzzInput);
+
+
+/**
+ * Creates a fuzzing config from the given VFS file handle.
+ *
+ * @returns IPRT status code.
+ * @param phFuzzCfg Where to store the handle to the fuzzing config on success.
+ * @param hVfsFile The VFS file to use (retained).
+ * @param pErrInfo Where to store extended error info. Optional.
+ */
+RTDECL(int) RTFuzzCfgCreateFromVfsFile(PRTFUZZCFG phFuzzCfg, RTVFSFILE hVfsFile, PRTERRINFO pErrInfo);
+
+/**
+ * Creates a fuzzing config from the given file path.
+ *
+ * @returns IPRT status code.
+ * @param phFuzzCfg Where to store the handle to the fuzzing config on success.
+ * @param pszFilename Filename to load the config from.
+ * @param pErrInfo Where to store extended error info. Optional.
+ */
+RTDECL(int) RTFuzzCfgCreateFromFile(PRTFUZZCFG phFuzzCfg, const char *pszFilename, PRTERRINFO pErrInfo);
+
+/**
+ * Retains a reference to the given fuzzing config.
+ *
+ * @returns New reference count on success.
+ * @param hFuzzCfg Handle of the fuzzing config.
+ */
+RTDECL(uint32_t) RTFuzzCfgRetain(RTFUZZCFG hFuzzCfg);
+
+/**
+ * Releases a reference from the given fuzzing config, destroying it when reaching 0.
+ *
+ * @returns New reference count on success, 0 if the fuzzing config got destroyed.
+ * @param hFuzzCfg Handle of the fuzzing config.
+ */
+RTDECL(uint32_t) RTFuzzCfgRelease(RTFUZZCFG hFuzzCfg);
+
+/**
+ * Imports the given fuzzing config into a previously created fuzzing context.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCfg Handle of the fuzzing config.
+ * @param hFuzzCtx Handle of the fuzzing context.
+ * @param fFlags Flags controlling what to import exactly, combination of RTFUZZCFG_IMPORT_F_XXX.
+ */
+RTDECL(int) RTFuzzCfgImport(RTFUZZCFG hFuzzCfg, RTFUZZCTX hFuzzCtx, uint32_t fFlags);
+
+/**
+ * Queries the custom config for the controller of the fuzzing process.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzCfg Handle of the fuzzing config.
+ * @param phVfsFile Where to store the handle of the VFS file containing the custom config.
+ */
+RTDECL(int) RTFuzzCfgQueryCustomCfg(RTFUZZCFG hFuzzCfg, PRTVFSFILE phVfsFile);
+
+
+/**
+ * Creates a new fuzzed target recorder.
+ *
+ * @returns IPRT status code.
+ * @param phFuzzTgtRec Where to store the handle to the fuzzed target recorder on success.
+ * @param fRecFlags What to take into account when checking for equal states.
+ * Combination of RTFUZZTGT_REC_STATE_F_*
+ */
+RTDECL(int) RTFuzzTgtRecorderCreate(PRTFUZZTGTREC phFuzzTgtRec, uint32_t fRecFlags);
+
+/**
+ * Retains a reference to the given fuzzed target recorder handle.
+ *
+ * @returns New reference count on success.
+ * @param hFuzzTgtRec The fuzzed target recorder handle.
+ */
+RTDECL(uint32_t) RTFuzzTgtRecorderRetain(RTFUZZTGTREC hFuzzTgtRec);
+
+/**
+ * Releases a reference from the given fuzzed target recorder handle, destroying it when reaching 0.
+ *
+ * @returns New reference count on success, 0 if the fuzzed target recorder got destroyed.
+ * @param hFuzzTgtRec The fuzzed target recorder handle.
+ */
+RTDECL(uint32_t) RTFuzzTgtRecorderRelease(RTFUZZTGTREC hFuzzTgtRec);
+
+/**
+ * Creates a new empty fuzzed target state.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtRec The fuzzed target recorder handle.
+ * @param phFuzzTgtState Where to store the handle to the fuzzed target state on success.
+ */
+RTDECL(int) RTFuzzTgtRecorderCreateNewState(RTFUZZTGTREC hFuzzTgtRec, PRTFUZZTGTSTATE phFuzzTgtState);
+
+/**
+ * Retains a reference to the given fuzzed target state handle.
+ *
+ * @returns New reference count on success.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ */
+RTDECL(uint32_t) RTFuzzTgtStateRetain(RTFUZZTGTSTATE hFuzzTgtState);
+
+/**
+ * Releases a reference from the given fuzzed target state handle, destroying it when reaching 0.
+ *
+ * @returns New reference count on success, 0 if the fuzzed target recorder got destroyed.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ */
+RTDECL(uint32_t) RTFuzzTgtStateRelease(RTFUZZTGTSTATE hFuzzTgtState);
+
+/**
+ * Resets the given fuzzed target state to an empty state (keeping allocated memory).
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ *
+ * @note Useful when the state is not added to the recorded set to avoid allocating memory.
+ */
+RTDECL(int) RTFuzzTgtStateReset(RTFUZZTGTSTATE hFuzzTgtState);
+
+/**
+ * Finalizes the given fuzzed target state, making it readonly.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ */
+RTDECL(int) RTFuzzTgtStateFinalize(RTFUZZTGTSTATE hFuzzTgtState);
+
+/**
+ * Adds the given state to the set for the owning target recorder.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_ALREADY_EXISTS if the state is already existing in the recorder set.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ *
+ * @note This also finalizes the target state if not already done.
+ */
+RTDECL(int) RTFuzzTgtStateAddToRecorder(RTFUZZTGTSTATE hFuzzTgtState);
+
+/**
+ * Appends the given stdout output to the given target state.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ * @param pvStdOut Pointer to the stdout data buffer.
+ * @param cbStdOut Size of the stdout data buffer in bytes.
+ */
+RTDECL(int) RTFuzzTgtStateAppendStdoutFromBuf(RTFUZZTGTSTATE hFuzzTgtState, const void *pvStdOut, size_t cbStdOut);
+
+/**
+ * Appends the given stderr output to the given target state.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ * @param pvStdErr Pointer to the stderr data buffer.
+ * @param cbStdErr Size of the stderr data buffer in bytes.
+ */
+RTDECL(int) RTFuzzTgtStateAppendStderrFromBuf(RTFUZZTGTSTATE hFuzzTgtState, const void *pvStdErr, size_t cbStdErr);
+
+/**
+ * Appends the given stdout output to the given target state, reading from the given pipe.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ * @param hPipe The stdout pipe to read the data from.
+ */
+RTDECL(int) RTFuzzTgtStateAppendStdoutFromPipe(RTFUZZTGTSTATE hFuzzTgtState, RTPIPE hPipe);
+
+/**
+ * Appends the given stderr output to the given target state, reading from the given pipe.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ * @param hPipe The stdout pipe to read the data from.
+ */
+RTDECL(int) RTFuzzTgtStateAppendStderrFromPipe(RTFUZZTGTSTATE hFuzzTgtState, RTPIPE hPipe);
+
+/**
+ * Adds the SanCov coverage information from the given file to the given target state.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ * @param pszFilename Filename of the coverage report.
+ */
+RTDECL(int) RTFuzzTgtStateAddSanCovReportFromFile(RTFUZZTGTSTATE hFuzzTgtState, const char *pszFilename);
+
+/**
+ * Adds the given process status to the target state.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ * @param pProcSts The process status to add.
+ */
+RTDECL(int) RTFuzzTgtStateAddProcSts(RTFUZZTGTSTATE hFuzzTgtState, PCRTPROCSTATUS pProcSts);
+
+/**
+ * Dumps the given target state to the given directory.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzTgtState The fuzzed target state handle.
+ * @param pszDirPath The directory to dump to.
+ */
+RTDECL(int) RTFuzzTgtStateDumpToDir(RTFUZZTGTSTATE hFuzzTgtState, const char *pszDirPath);
+
+
+/**
+ * Fuzzed binary input channel.
+ */
+typedef enum RTFUZZOBSINPUTCHAN
+{
+ /** Invalid. */
+ RTFUZZOBSINPUTCHAN_INVALID = 0,
+ /** File input. */
+ RTFUZZOBSINPUTCHAN_FILE,
+ /** Input over stdin. */
+ RTFUZZOBSINPUTCHAN_STDIN,
+ /** The binary is a fuzzing aware client using the
+ * specified protocol over stdin/stdout. */
+ RTFUZZOBSINPUTCHAN_FUZZING_AWARE_CLIENT,
+ /** TCP server. */
+ RTFUZZOBSINPUTCHAN_TCP_SERVER,
+ /** TCP client. */
+ RTFUZZOBSINPUTCHAN_TCP_CLIENT,
+ /** UDP server. */
+ RTFUZZOBSINPUTCHAN_UDP_SERVER,
+ /** UDP client. */
+ RTFUZZOBSINPUTCHAN_UDP_CLIENT,
+ /** 32bit hack. */
+ RTFUZZOBSINPUTCHAN_32BIT_HACK = 0x7fffffff
+} RTFUZZOBSINPUTCHAN;
+
+/**
+ * Fuzzing observer statistics.
+ */
+typedef struct RTFUZZOBSSTATS
+{
+ /** Number of fuzzed inputs per second. */
+ uint32_t cFuzzedInputsPerSec;
+ /** Number of overall fuzzed inputs. */
+ uint32_t cFuzzedInputs;
+ /** Number of observed hangs. */
+ uint32_t cFuzzedInputsHang;
+ /** Number of observed crashes. */
+ uint32_t cFuzzedInputsCrash;
+} RTFUZZOBSSTATS;
+/** Pointer to a fuzzing observer statistics record. */
+typedef RTFUZZOBSSTATS *PRTFUZZOBSSTATS;
+
+/**
+ * Creates a new fuzzing observer.
+ *
+ * @returns IPRT status code.
+ * @param phFuzzObs Where to store the fuzzing observer handle on success.
+ * @param enmType Fuzzing context data type.
+ * @param fTgtRecFlags Flags to pass to the target state recorder, see RTFuzzTgtRecorderCreate().
+ */
+RTDECL(int) RTFuzzObsCreate(PRTFUZZOBS phFuzzObs, RTFUZZCTXTYPE enmType, uint32_t fTgtRecFlags);
+
+/**
+ * Destroys a previously created fuzzing observer.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ */
+RTDECL(int) RTFuzzObsDestroy(RTFUZZOBS hFuzzObs);
+
+/**
+ * Queries the internal fuzzing context of the given observer.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param phFuzzCtx Where to store the handle to the fuzzing context on success.
+ *
+ * @note The fuzzing context handle should be released with RTFuzzCtxRelease() when not used anymore.
+ */
+RTDECL(int) RTFuzzObsQueryCtx(RTFUZZOBS hFuzzObs, PRTFUZZCTX phFuzzCtx);
+
+/**
+ * Queries the current statistics for the given fuzzing observer.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param pStats Where to store the statistics to.
+ */
+RTDECL(int) RTFuzzObsQueryStats(RTFUZZOBS hFuzzObs, PRTFUZZOBSSTATS pStats);
+
+/**
+ * Sets the temp directory for the given fuzzing observer.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param pszTmp The temp directory path.
+ */
+RTDECL(int) RTFuzzObsSetTmpDirectory(RTFUZZOBS hFuzzObs, const char *pszTmp);
+
+/**
+ * Sets the directory to store results to.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param pszResults The path to store the results.
+ */
+RTDECL(int) RTFuzzObsSetResultDirectory(RTFUZZOBS hFuzzObs, const char *pszResults);
+
+/**
+ * Sets the binary to run for each fuzzed input.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param pszBinary The binary path.
+ * @param enmInputChan The input channel to use.
+ */
+RTDECL(int) RTFuzzObsSetTestBinary(RTFUZZOBS hFuzzObs, const char *pszBinary, RTFUZZOBSINPUTCHAN enmInputChan);
+
+/**
+ * Sets additional arguments to run the binary with.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param papszArgs Pointer to the array of arguments.
+ * @param cArgs Number of arguments.
+ */
+RTDECL(int) RTFuzzObsSetTestBinaryArgs(RTFUZZOBS hFuzzObs, const char * const *papszArgs, unsigned cArgs);
+
+/**
+ * Sets an environment block to run the binary in.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param hEnv The environment block to set for the test binary.
+ * Use RTENV_DEFAULT for the default process environment or
+ * NULL for an empty environment.
+ *
+ * @note Upon successful return of this function the observer has taken ownership over the
+ * environment block and can alter it in unexpected ways. It also destroys the environment
+ * block when the observer gets destroyed. So don't touch the environment block after
+ * calling this function.
+ */
+RTDECL(int) RTFuzzObsSetTestBinaryEnv(RTFUZZOBS hFuzzObs, RTENV hEnv);
+
+/**
+ * Makes the observer aware of any configured sanitizers for the test binary.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param fSanitizers Bitmask of compiled and enabled sanitiziers in the
+ * target binary.
+ */
+RTDECL(int) RTFuzzObsSetTestBinarySanitizers(RTFUZZOBS hFuzzObs, uint32_t fSanitizers);
+
+/**
+ * Sets maximum timeout until a process is considered hung and killed.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param msTimeoutMax The maximum number of milliseconds to wait until the process
+ * is considered hung.
+ */
+RTDECL(int) RTFuzzObsSetTestBinaryTimeout(RTFUZZOBS hFuzzObs, RTMSINTERVAL msTimeoutMax);
+
+/**
+ * Starts fuzzing the set binary.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ * @param cProcs Number of processes to run simulteanously,
+ * 0 will create as many processes as there are CPUs available.
+ */
+RTDECL(int) RTFuzzObsExecStart(RTFUZZOBS hFuzzObs, uint32_t cProcs);
+
+/**
+ * Stops the fuzzing process.
+ *
+ * @returns IPRT status code.
+ * @param hFuzzObs The fuzzing observer handle.
+ */
+RTDECL(int) RTFuzzObsExecStop(RTFUZZOBS hFuzzObs);
+
+
+/**
+ * A fuzzing master program.
+ *
+ * @returns Program exit code.
+ *
+ * @param cArgs The number of arguments.
+ * @param papszArgs The argument vector. (Note that this may be
+ * reordered, so the memory must be writable.)
+ */
+RTR3DECL(RTEXITCODE) RTFuzzCmdMaster(unsigned cArgs, char **papszArgs);
+
+
+/**
+ * Client input consumption callback.
+ *
+ * @returns IPRT status code.
+ * @retval VINF_SUCCESS the fuzzed code accepted the input.
+ * @retval VERR_* the client rejected the input while parsing it.
+ * @param pvBuf The buffer containing the input data.
+ * @param cbBuf Size of the buffer in bytes.
+ * @param pvUser Opaque user data.
+ */
+typedef DECLCALLBACKTYPE(int, FNFUZZCLIENTCONSUME,(const void *pvBuf, size_t cbBuf, void *pvUser));
+/** Pointer to a client consumption callback. */
+typedef FNFUZZCLIENTCONSUME *PFNFUZZCLIENTCONSUME;
+
+/**
+ * A fuzzing client program for more efficient fuzzing.
+ *
+ * @returns Program exit code.
+ *
+ * @param cArgs The number of arguments.
+ * @param papszArgs The argument vector. (Note that this may be
+ * reordered, so the memory must be writable.)
+ * @param pfnConsume Input data consumption callback.
+ * @param pvUser Opaque user data to pass to the callback.
+ */
+RTR3DECL(RTEXITCODE) RTFuzzCmdFuzzingClient(unsigned cArgs, char **papszArgs, PFNFUZZCLIENTCONSUME pfnConsume, void *pvUser);
+/** @} */
+
+RT_C_DECLS_END
+
+#endif /* !IPRT_INCLUDED_fuzz_h */
+