1//===- FuzzerInterface.h - Interface header for the Fuzzer ------*- C++ -* ===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8// Define the interface between libFuzzer and the library being tested.
9//===----------------------------------------------------------------------===//
10
11// NOTE: the libFuzzer interface is thin and in the majority of cases
12// you should not include this file into your target. In 95% of cases
13// all you need is to define the following function in your file:
14// extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size);
15
16// WARNING: keep the interface in C.
17
18#ifndef LLVM_FUZZER_INTERFACE_H
19#define LLVM_FUZZER_INTERFACE_H
20
21#include <stddef.h>
22#include <stdint.h>
23
24#ifdef __cplusplus
25extern "C" {
26#endif // __cplusplus
27
28// Define FUZZER_INTERFACE_VISIBILITY to set default visibility in a way that
29// doesn't break MSVC.
30#if defined(_WIN32)
31#define FUZZER_INTERFACE_VISIBILITY __declspec(dllexport)
32#else
33#define FUZZER_INTERFACE_VISIBILITY __attribute__((visibility("default")))
34#endif
35
36// Mandatory user-provided target function.
37// Executes the code under test with [Data, Data+Size) as the input.
38// libFuzzer will invoke this function *many* times with different inputs.
39// Must return 0.
40FUZZER_INTERFACE_VISIBILITY int
41LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size);
42
43// Optional user-provided initialization function.
44// If provided, this function will be called by libFuzzer once at startup.
45// It may read and modify argc/argv.
46// Must return 0.
47FUZZER_INTERFACE_VISIBILITY int LLVMFuzzerInitialize(int *argc, char ***argv);
48
49// Optional user-provided custom mutator.
50// Mutates raw data in [Data, Data+Size) inplace.
51// Returns the new size, which is not greater than MaxSize.
52// Given the same Seed produces the same mutation.
53FUZZER_INTERFACE_VISIBILITY size_t
54LLVMFuzzerCustomMutator(uint8_t *Data, size_t Size, size_t MaxSize,
55 unsigned int Seed);
56
57// Optional user-provided custom cross-over function.
58// Combines pieces of Data1 & Data2 together into Out.
59// Returns the new size, which is not greater than MaxOutSize.
60// Should produce the same mutation given the same Seed.
61FUZZER_INTERFACE_VISIBILITY size_t
62LLVMFuzzerCustomCrossOver(const uint8_t *Data1, size_t Size1,
63 const uint8_t *Data2, size_t Size2, uint8_t *Out,
64 size_t MaxOutSize, unsigned int Seed);
65
66// Experimental, may go away in future.
67// libFuzzer-provided function to be used inside LLVMFuzzerCustomMutator.
68// Mutates raw data in [Data, Data+Size) inplace.
69// Returns the new size, which is not greater than MaxSize.
70FUZZER_INTERFACE_VISIBILITY size_t
71LLVMFuzzerMutate(uint8_t *Data, size_t Size, size_t MaxSize);
72
73#undef FUZZER_INTERFACE_VISIBILITY
74
75#ifdef __cplusplus
76} // extern "C"
77#endif // __cplusplus
78
79#endif // LLVM_FUZZER_INTERFACE_H
80