目录

类

class DataProvider

public open class DataProvider {
    public let data: Array<UInt8>
    public var remainingBytes: Int64
    public var offset: Int64
}

功能：DataProvider 是一个工具类，目的是将变异数据的字节流转化为标准的仓颉基本数据。

当前支持的数据结构如下：

目标类型 API 说明
Bool consumeBool() 获取 1 个 Bool，变异数据长度不足时，抛出 ExhaustedException。
Array<Bool> consumeBools(count: Int64) 获取 N 个 Bool，变异数据长度不足时，抛出 ExhaustedException。
Byte consumeByte() 获取 1 个 Byte，变异数据长度不足时，抛出 ExhaustedException。
Array<Byte> consumeBytes(count: Int64) 获取 N 个 Byte，变异数据长度不足时，抛出 ExhaustedException。
UInt8 consumeUInt8() 获取 1 个 UInt8，变异数据长度不足时，抛出 ExhaustedException。
UInt16 consumeUInt16() 获取 1 个 UInt16，变异数据长度不足时，抛出 ExhaustedException。
UInt32 consumeUInt32() 获取 1 个 UInt32，变异数据长度不足时，抛出 ExhaustedException。
UInt64 consumeUInt64() 获取 1 个 UInt64，变异数据长度不足时，抛出 ExhaustedException。
Int8 consumeInt8() 获取 1 个 Int8，变异数据长度不足时，抛出 ExhaustedException。
Int16 consumeInt16() 获取 1 个 Int16，变异数据长度不足时，抛出 ExhaustedException。
Int32 consumeInt32() 获取 1 个 Int32，变异数据长度不足时，抛出 ExhaustedException。
Int32 consumeInt32() 获取 1 个 Int32，变异数据长度不足时，抛出 ExhaustedException。
Array<UInt8> consumeUInt8s(count: Int64) 获取 N 个 UInt8，变异数据长度不足时，抛出 ExhaustedException。
Array<UInt16> consumeUInt16s(count: Int64) 获取 N 个 UInt16，变异数据长度不足时，抛出 ExhaustedException。
Array<UInt32> consumeUInt32s(count: Int64) 获取 N 个 UInt32，变异数据长度不足时，抛出 ExhaustedException。
Array<UInt64> consumeUInt64s(count: Int64) 获取 N 个 UInt64，变异数据长度不足时，抛出 ExhaustedException。
Array<Int8> consumeInt8s(count: Int64) 获取 N 个 Int8，变异数据长度不足时，抛出 ExhaustedException。
Array<Int16> consumeInt16s(count: Int64) 获取 N 个 Int16，变异数据长度不足时，抛出 ExhaustedException。
Array<Int32> consumeInt32s(count: Int64) 获取 N 个 Int32，变异数据长度不足时，抛出 ExhaustedException。
Array<Int32> consumeInt32s(count: Int64) 获取 N 个 Int32，变异数据长度不足时，抛出 ExhaustedException。
Rune consumeRune() 获取 1 个 Rune，变异数据长度不足时，抛出 ExhaustedException。
String consumeAsciiString(maxLength: Int64) 获取 1 个纯 ASCII 的 String，长度为 0 到 maxLength，可以为 0。
String consumeString(maxLength: Int64) 获取 1 个 UTF8 String，长度为 0 到 maxLength，可以为 0。
Array<UInt8> consumeAll() 将 DataProvider 中的剩余内容全部转化为字节数组。
String consumeAllAsAscii() 将 DataProvider 中的剩余内容全部转化为纯 ASCII 的 String。
String consumeAllAsString() 将 DataProvider 中的剩余内容全部转化为 UTF8 String，末尾多余的字符不会被消耗。

不支持Float32和Float64

在数据长度不足时，调用上述大部分虽然会抛出 ExhaustedException，但编写 fuzz 函数时通常并不需要对它进行处理，ExhaustedException 默认会被 fuzz 框架捕获，告诉 libfuzzer 该次运行无效，请继续下一轮变异。随着执行时间的变长，变异数据也会逐渐变长，直到满足 DataProvider 的需求。

如果达到了 max_len 仍无法满足 DataProvider 的需求，则进程退出，请修改 fuzz 测试用例（推荐） 或 增大 max_len（不推荐）。

[h2]let data

public let data: Array<UInt8>

功能：变异数据。

类型：Array<UInt8>

[h2]var offset

public var offset: Int64

功能：已转化的字节数。

类型：Int64

[h2]var remainingBytes

public var remainingBytes: Int64

功能：剩余字节数。

类型：Int64

[h2]func consumeAll()

public open func consumeAll(): Array<UInt8>

功能：将所有数据转换成 UInt8 类型数组。

返回值：

[h2]func consumeAllAsAscii()

public open func consumeAllAsAscii(): String

功能：将所有数据转换成 Ascii String 类型。

返回值：

[h2]func consumeAllAsString()

public open func consumeAllAsString(): String

功能：将所有数据转换成 utf8 String 类型。

返回值：

[h2]func consumeAsciiString(Int64)

public open func consumeAsciiString(maxLength: Int64): String

功能：将数据转换成 Ascii String 类型实例。

参数：

返回值：

[h2]func consumeBool()

public open func consumeBool(): Bool

功能：将数据转换成 Bool 类型实例。

返回值：

[h2]func consumeBools(Int64)

public open func consumeBools(count: Int64): Array<Bool>

功能：将指定数量的数据转换成 Bool 类型数组。

参数：

返回值：

[h2]func consumeByte()

public open func consumeByte(): Byte

功能：将数据转换成 Byte 类型实例。

返回值：

[h2]func consumeBytes(Int64)

public open func consumeBytes(count: Int64): Array<Byte>

功能：将指定数量的数据转换成 Byte 类型数组。

参数：

返回值：

[h2]func consumeFloat32()

public open func consumeFloat32(): Float32

功能：将数据转换成 Float32 类型实例（保留接口，功能暂未实现，当前为抛出异常UnsupportException）。

返回值：

[h2]func consumeFloat64()

public open func consumeFloat64(): Float64

功能：将数据转换成 Float64 类型实例（保留接口，功能暂未实现，当前为抛出异常UnsupportException）。

返回值：

[h2]func consumeInt16()

public open func consumeInt16(): Int16

功能：将数据转换成 Int16 类型实例。

返回值：

[h2]func consumeInt16s(Int64)

public open func consumeInt16s(count: Int64): Array<Int16>

功能：将指定数量的数据转换成 Int16 类型数组。

参数：

返回值：

[h2]func consumeInt32()

public open func consumeInt32(): Int32

功能：将数据转换成 Int32 类型实例。

返回值：

[h2]func consumeInt32s(Int64)

public open func consumeInt32s(count: Int64): Array<Int32>

功能：将指定数量的数据转换成 Int32 类型数组。

参数：

返回值：

[h2]func consumeInt64()

public open func consumeInt64(): Int64

功能：将数据转换成 Int64 类型实例。

返回值：

[h2]func consumeInt64s(Int64)

public open func consumeInt64s(count: Int64): Array<Int64>

功能：将指定数量的数据转换成 Int64 类型数组。

参数：

返回值：

[h2]func consumeInt8()

public open func consumeInt8(): Int8

功能：将数据转换成 Int8 类型实例。

返回值：

[h2]func consumeInt8s(Int64)

public open func consumeInt8s(count: Int64): Array<Int8>

功能：将指定数量的数据转换成 Int8 类型数组。

参数：

返回值：

[h2]func consumeRune()

public open func consumeRune(): Rune

功能：将数据转换成 Rune 类型实例。

返回值：

[h2]func consumeString(Int64)

public open func consumeString(maxLength: Int64): String

功能：将数据转换成 utf8 String 类型实例。

参数：

返回值：

[h2]func consumeUInt16()

public open func consumeUInt16(): UInt16

功能：将数据转换成 UInt16 类型实例。

返回值：

[h2]func consumeUInt16s(Int64)

public open func consumeUInt16s(count: Int64): Array<UInt16>

功能：将指定数量的数据转换成 UInt16 类型数组。

参数：

返回值：

[h2]func consumeUInt32()

public open func consumeUInt32(): UInt32

功能：将数据转换成 UInt32 类型实例。

返回值：

[h2]func consumeUInt32s(Int64)

public open func consumeUInt32s(count: Int64): Array<UInt32>

功能：将指定数量的数据转换成 UInt32 类型数组。

参数：

返回值：

[h2]func consumeUInt64()

public open func consumeUInt64(): UInt64

功能：将数据转换成 UInt64 类型实例。

返回值：

[h2]func consumeUInt64s(Int64)

public open func consumeUInt64s(count: Int64): Array<UInt64>

功能：将指定数量的数据转换成 UInt64 类型数组。

参数：

返回值：

[h2]func consumeUInt8()

public open func consumeUInt8(): UInt8

功能：将数据转换成 UInt8 类型实例。

返回值：

[h2]func consumeUInt8s(Int64)

public open func consumeUInt8s(count: Int64): Array<UInt8>

功能：将指定数量的数据转换成 UInt8 类型数组。

参数：

返回值：

class DebugDataProvider

public class DebugDataProvider <: DataProvider

功能：此类继承了 DataProvider 类型，额外增加了调试信息。

[h2]data

public let data: Array<UInt8>

功能：变异数据。

[h2]offset

public var offset: Int64

功能：已转化的字节数。

[h2]remainingBytes

public var remainingBytes: Int64

功能：剩余字节数。

[h2]func consumeAll()

public override func consumeAll(): Array<UInt8>

功能：将所有数据转换成 UInt8 类型数组。

返回值：

[h2]func consumeAllAsAscii()

public override func consumeAllAsAscii(): String

功能：将所有数据转换成 Ascii String 类型。

返回值：

[h2]func consumeAllAsString()

public override func consumeAllAsString(): String

功能：将所有数据转换成 utf8 String 类型。

返回值：

[h2]func consumeAsciiString(Int64)

public override func consumeAsciiString(maxLength: Int64): String

功能：将数据转换成 Ascii String 类型实例。

参数：

返回值：

[h2]func consumeBool()

public override func consumeBool(): Bool

功能：将数据转换成 Bool 类型实例。

返回值：

[h2]func consumeBools(Int64)

public override func consumeBools(count: Int64): Array<Bool>

功能：将指定数量的数据转换成 Bool 类型数组。

参数：

返回值：

[h2]func consumeByte()

public override func consumeByte(): Byte

功能：将数据转换成 Byte 类型实例。

返回值：

[h2]func consumeBytes(Int64)

public override func consumeBytes(count: Int64): Array<Byte>

功能：将指定数量的数据转换成 Byte 类型数组。

参数：

返回值：

[h2]func consumeFloat32()

public override func consumeFloat32(): Float32

功能：将数据转换成 Float32 类型实例（保留接口，功能暂未实现，当前为抛出异常UnsupportException）。

返回值：

[h2]func consumeFloat64()

public override func consumeFloat64(): Float64

功能：将数据转换成 Float64 类型实例（保留接口，功能暂未实现，当前为抛出异常UnsupportException）。

返回值：

[h2]func consumeInt16()

public override func consumeInt16(): Int16

功能：将数据转换成 Int16 类型实例。

返回值：

[h2]func consumeInt16s(Int64)

public override func consumeInt16s(count: Int64): Array<Int16>

功能：将指定数量的数据转换成 Int16 类型数组。

参数：

返回值：

[h2]func consumeInt32()

public override func consumeInt32(): Int32

功能：将数据转换成 Int32 类型实例。

返回值：

[h2]func consumeInt32s(Int64)

public override func consumeInt32s(count: Int64): Array<Int32>

功能：将指定数量的数据转换成 Int32 类型数组。

参数：

返回值：

[h2]func consumeInt64()

public override func consumeInt64(): Int64

功能：将数据转换成 Int64 类型实例。

返回值：

[h2]func consumeInt64s(Int64)

public override func consumeInt64s(count: Int64): Array<Int64>

功能：将指定数量的数据转换成 Int64 类型数组。

参数：

返回值：

[h2]func consumeInt8()

public override func consumeInt8(): Int8

功能：将数据转换成 Int8 类型实例。

返回值：

[h2]func consumeInt8s(Int64)

public override func consumeInt8s(count: Int64): Array<Int8>

功能：将指定数量的数据转换成 Int8 类型数组。

参数：

返回值：

[h2]func consumeRune()

public override func consumeRune(): Rune

功能：将数据转换成 Rune 类型实例。

返回值：

[h2]func consumeString(Int64)

public override func consumeString(maxLength: Int64): String

功能：将数据转换成 utf8 String 类型实例。

参数：

返回值：

[h2]func consumeUInt16()

public override func consumeUInt16(): UInt16

功能：将数据转换成 UInt16 类型实例。

返回值：

[h2]func consumeUInt16s(Int64)

public override func consumeUInt16s(count: Int64): Array<UInt16>

功能：将指定数量的数据转换成 UInt16 类型数组。

参数：

返回值：

[h2]func consumeUInt32()

public override func consumeUInt32(): UInt32

功能：将数据转换成 UInt32 类型实例。

返回值：

[h2]func consumeUInt32s(Int64)

public override func consumeUInt32s(count: Int64): Array<UInt32>

功能：将指定数量的数据转换成 UInt32 类型数组。

参数：

返回值：

[h2]func consumeUInt64()

public override func consumeUInt64(): UInt64

功能：将数据转换成 UInt64 类型实例。

返回值：

[h2]func consumeUInt64s(Int64)

public override func consumeUInt64s(count: Int64): Array<UInt64>

功能：将指定数量的数据转换成 UInt64 类型数组。

参数：

返回值：

[h2]func consumeUInt8()

public override func consumeUInt8(): UInt8

功能：将数据转换成 UInt8 类型实例。

返回值：

[h2]func consumeUInt8s(Int64)

public override func consumeUInt8s(count: Int64): Array<UInt8>

功能：将指定数量的数据转换成 UInt8 类型数组。

参数：

返回值：

[h2]func wrap(DataProvider)

public static func wrap(dp: DataProvider): DebugDataProvider

功能：根据 DataProvider 实例创建 DebugDataProvider 实例。

参数：

返回值：

class Fuzzer

public class Fuzzer {
    public init(targetFunction: (Array<UInt8>) -> Int32)
    public init(targetFunction: (Array<UInt8>) -> Int32, args: Array<String>)
    public init(targetFunction: (DataProvider) -> Int32)
    public init(targetFunction: (DataProvider) -> Int32, args: Array<String>)
}

功能：Fuzzer 类提供了 fuzz 工具的创建。用户提供需要进行 fuzz 测试的函数 targetFunction，以及设置特定的 fuzz 运行参数 args 比如 fuzz 执行次数、初始种子、生成数据最大长度等，可创建相应类型的 Fuzzer。

[h2]init((Array<UInt8>) -> Int32)

public init(targetFunction: (Array<UInt8>) -> Int32)

功能：根据以 UInt8 数组为参数，以 Int32 为返回值的目标函数，创建 Fuzzer 实例。

参数：

[h2]init((Array<UInt8>) -> Int32, Array<String>)

public init(targetFunction: (Array<UInt8>) -> Int32, args: Array<String>)

功能：根据以 UInt8 数组为参数，以 Int32 为返回值的目标函数，以及 Fuzz 运行参数，创建 Fuzzer 实例。

参数：

[h2]init((DataProvider) -> Int32)

public init(targetFunction: (DataProvider) -> Int32)

功能：根据以 DataProvider 为参数，以 Int32 为返回值的目标函数，创建 Fuzzer 实例。

参数：

[h2]init((DataProvider) -> Int32, Array<String>)

public init(targetFunction: (DataProvider) -> Int32, args: Array<String>)

功能：根据以 DataProvider 为参数，以 Int32 为返回值的目标函数，以及 Fuzz 运行参数，创建 Fuzzer 实例。

参数：

[h2]func disableDebugDataProvider()

public func disableDebugDataProvider(): Unit

功能：关闭调试信息打印功能，当 DataProvider.consumeXXX 被调用时，返回值将不被打印到 stdout。

[h2]func disableFakeCoverage()

public func disableFakeCoverage(): Unit

功能：关闭调用 enableFakeCoverage 对 Fuzz 的影响。

[h2]func enableDebugDataProvider()

public func enableDebugDataProvider(): Unit

功能：启用调试信息打印功能，当 DataProvider.consumeXXX 被调用时，返回值将被打印到 stdout。该功能默认为关闭。

[h2]func enableFakeCoverage()

public func enableFakeCoverage(): Unit

功能：创建一块虚假的覆盖率反馈区域，保持 Fuzz 持续进行。在 DataProvider 模式下，前几轮运行时可能由于数据不足而导致没有覆盖率，libfuzzer 会退出。该功能默认为关闭。

[h2]func getArgs()

public func getArgs(): Array<String>

功能：获取 Fuzz 运行参数。

返回值：

[h2]func setArgs(Array<String>)

public func setArgs(args: Array<String>): Unit

功能：设置 Fuzz 运行参数。

参数：

[h2]func setTargetFunction((Array<UInt8>) -> Int32)

public func setTargetFunction(targetFunction: (Array<UInt8>) -> Int32): Unit

功能：设置 Fuzz 目标函数。

参数：

[h2]func setTargetFunction((DataProvider) -> Int32)

public func setTargetFunction(targetFunction: (DataProvider) -> Int32): Unit

功能：设置 Fuzz 目标函数。

参数：

[h2]func startFuzz()

public func startFuzz(): Unit

功能：执行 Fuzz。

class FuzzerBuilder

public class FuzzerBuilder {
    public init(targetFunction: (Array<UInt8>) -> Int32)
    public init(targetFunction: (DataProvider) -> Int32)
}

功能：此类用于 Fuzzer 类的构建。

[h2]init((Array<UInt8>) -> Int32)

public init(targetFunction: (Array<UInt8>) -> Int32)

功能：根据以 UInt8 数组为参数，以 Int32 为返回值的目标函数，创建 FuzzerBuilder 实例。

参数：

[h2]init((DataProvider) -> Int32)

public init(targetFunction: (DataProvider) -> Int32)

功能：根据以 DataProvider 为参数，以 Int32 为返回值的目标函数，创建 FuzzerBuilder 实例。

参数：

[h2]func build()

public func build(): Fuzzer

功能：生成一个 Fuzzer 实例。

返回值：

[h2]func setArgs(Array)

public func setArgs(args: Array<String>): FuzzerBuilder

功能：设置 Fuzz 运行参数。

参数：

返回值：

[h2]func setTargetFunction((Array<UInt8>) -> Int32)

public func setTargetFunction(targetFunction: (Array<UInt8>) -> Int32): FuzzerBuilder

功能：设置 Fuzz 目标函数。

参数：

返回值：

[h2]func setTargetFunction((DataProvider) -> Int32)

public func setTargetFunction(targetFunction: (DataProvider) -> Int32): FuzzerBuilder

功能：设置 Fuzz 目标函数。

参数：

返回值：