SDL_test_fuzzer.h

00001 /*
00002   Simple DirectMedia Layer
00003   Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
00004 
00005   This software is provided 'as-is', without any express or implied
00006   warranty.  In no event will the authors be held liable for any damages
00007   arising from the use of this software.
00008 
00009   Permission is granted to anyone to use this software for any purpose,
00010   including commercial applications, and to alter it and redistribute it
00011   freely, subject to the following restrictions:
00012 
00013   1. The origin of this software must not be misrepresented; you must not
00014      claim that you wrote the original software. If you use this software
00015      in a product, an acknowledgment in the product documentation would be
00016      appreciated but is not required.
00017   2. Altered source versions must be plainly marked as such, and must not be
00018      misrepresented as being the original software.
00019   3. This notice may not be removed or altered from any source distribution.
00020 */
00021 
00022 /**
00023  *  \file SDL_test_fuzzer.h
00024  *
00025  *  Include file for SDL test framework.
00026  *
00027  *  This code is a part of the SDL2_test library, not the main SDL library.
00028  */
00029 
00030 /*
00031 
00032   Data generators for fuzzing test data in a reproducible way.
00033 
00034 */
00035 
00036 #ifndef _SDL_test_fuzzer_h
00037 #define _SDL_test_fuzzer_h
00038 
00039 #include "begin_code.h"
00040 /* Set up for C function definitions, even when using C++ */
00041 #ifdef __cplusplus
00042 extern "C" {
00043 #endif
00044 
00045 
00046 /*
00047   Based on GSOC code by Markus Kauppila <markus.kauppila@gmail.com>
00048 */
00049 
00050 
00051 /**
00052  * \file
00053  * Note: The fuzzer implementation uses a static instance of random context
00054  * internally which makes it thread-UNsafe.
00055  */
00056 
00057 /**
00058  * Initializes the fuzzer for a test
00059  *
00060  * /param execKey Execution "Key" that initializes the random number generator uniquely for the test.
00061  *
00062  */
00063 void SDLTest_FuzzerInit(Uint64 execKey);
00064 
00065 
00066 /**
00067  * Returns a random Uint8
00068  *
00069  * \returns Generated integer
00070  */
00071 Uint8 SDLTest_RandomUint8();
00072 
00073 /**
00074  * Returns a random Sint8
00075  *
00076  * \returns Generated signed integer
00077  */
00078 Sint8 SDLTest_RandomSint8();
00079 
00080 
00081 /**
00082  * Returns a random Uint16
00083  *
00084  * \returns Generated integer
00085  */
00086 Uint16 SDLTest_RandomUint16();
00087 
00088 /**
00089  * Returns a random Sint16
00090  *
00091  * \returns Generated signed integer
00092  */
00093 Sint16 SDLTest_RandomSint16();
00094 
00095 
00096 /**
00097  * Returns a random integer
00098  *
00099  * \returns Generated integer
00100  */
00101 Sint32 SDLTest_RandomSint32();
00102 
00103 
00104 /**
00105  * Returns a random positive integer
00106  *
00107  * \returns Generated integer
00108  */
00109 Uint32 SDLTest_RandomUint32();
00110 
00111 /**
00112  * Returns random Uint64.
00113  *
00114  * \returns Generated integer
00115  */
00116 Uint64 SDLTest_RandomUint64();
00117 
00118 
00119 /**
00120  * Returns random Sint64.
00121  *
00122  * \returns Generated signed integer
00123  */
00124 Sint64 SDLTest_RandomSint64();
00125 
00126 /**
00127  * \returns random float in range [0.0 - 1.0[
00128  */
00129 float SDLTest_RandomUnitFloat ();
00130 
00131 /**
00132  * \returns random double in range [0.0 - 1.0[
00133  */
00134 double SDLTest_RandomUnitDouble ();
00135 
00136 /**
00137  * \returns random float.
00138  *
00139  */
00140 float SDLTest_RandomFloat ();
00141 
00142 /**
00143  * \returns random double.
00144  *
00145  */
00146 double SDLTest_RandomDouble ();
00147 
00148 /**
00149  * Returns a random boundary value for Uint8 within the given boundaries.
00150  * Boundaries are inclusive, see the usage examples below. If validDomain
00151  * is true, the function will only return valid boundaries, otherwise non-valid
00152  * boundaries are also possible.
00153  * If boundary1 > boundary2, the values are swapped
00154  *
00155  * Usage examples:
00156  * RandomUint8BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20
00157  * RandomUint8BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21
00158  * RandomUint8BoundaryValue(0, 99, SDL_FALSE) returns 100
00159  * RandomUint8BoundaryValue(0, 255, SDL_FALSE) returns 0 (error set)
00160  *
00161  * \param boundary1 Lower boundary limit
00162  * \param boundary2 Upper boundary limit
00163  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
00164  *
00165  * \returns Random boundary value for the given range and domain or 0 with error set
00166  */
00167 Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain);
00168 
00169 /**
00170  * Returns a random boundary value for Uint16 within the given boundaries.
00171  * Boundaries are inclusive, see the usage examples below. If validDomain
00172  * is true, the function will only return valid boundaries, otherwise non-valid
00173  * boundaries are also possible.
00174  * If boundary1 > boundary2, the values are swapped
00175  *
00176  * Usage examples:
00177  * RandomUint16BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20
00178  * RandomUint16BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21
00179  * RandomUint16BoundaryValue(0, 99, SDL_FALSE) returns 100
00180  * RandomUint16BoundaryValue(0, 0xFFFF, SDL_FALSE) returns 0 (error set)
00181  *
00182  * \param boundary1 Lower boundary limit
00183  * \param boundary2 Upper boundary limit
00184  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
00185  *
00186  * \returns Random boundary value for the given range and domain or 0 with error set
00187  */
00188 Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain);
00189 
00190 /**
00191  * Returns a random boundary value for Uint32 within the given boundaries.
00192  * Boundaries are inclusive, see the usage examples below. If validDomain
00193  * is true, the function will only return valid boundaries, otherwise non-valid
00194  * boundaries are also possible.
00195  * If boundary1 > boundary2, the values are swapped
00196  *
00197  * Usage examples:
00198  * RandomUint32BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20
00199  * RandomUint32BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21
00200  * RandomUint32BoundaryValue(0, 99, SDL_FALSE) returns 100
00201  * RandomUint32BoundaryValue(0, 0xFFFFFFFF, SDL_FALSE) returns 0 (with error set)
00202  *
00203  * \param boundary1 Lower boundary limit
00204  * \param boundary2 Upper boundary limit
00205  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
00206  *
00207  * \returns Random boundary value for the given range and domain or 0 with error set
00208  */
00209 Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain);
00210 
00211 /**
00212  * Returns a random boundary value for Uint64 within the given boundaries.
00213  * Boundaries are inclusive, see the usage examples below. If validDomain
00214  * is true, the function will only return valid boundaries, otherwise non-valid
00215  * boundaries are also possible.
00216  * If boundary1 > boundary2, the values are swapped
00217  *
00218  * Usage examples:
00219  * RandomUint64BoundaryValue(10, 20, SDL_TRUE) returns 10, 11, 19 or 20
00220  * RandomUint64BoundaryValue(1, 20, SDL_FALSE) returns 0 or 21
00221  * RandomUint64BoundaryValue(0, 99, SDL_FALSE) returns 100
00222  * RandomUint64BoundaryValue(0, 0xFFFFFFFFFFFFFFFF, SDL_FALSE) returns 0 (with error set)
00223  *
00224  * \param boundary1 Lower boundary limit
00225  * \param boundary2 Upper boundary limit
00226  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
00227  *
00228  * \returns Random boundary value for the given range and domain or 0 with error set
00229  */
00230 Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain);
00231 
00232 /**
00233  * Returns a random boundary value for Sint8 within the given boundaries.
00234  * Boundaries are inclusive, see the usage examples below. If validDomain
00235  * is true, the function will only return valid boundaries, otherwise non-valid
00236  * boundaries are also possible.
00237  * If boundary1 > boundary2, the values are swapped
00238  *
00239  * Usage examples:
00240  * RandomSint8BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20
00241  * RandomSint8BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9
00242  * RandomSint8BoundaryValue(SINT8_MIN, 99, SDL_FALSE) returns 100
00243  * RandomSint8BoundaryValue(SINT8_MIN, SINT8_MAX, SDL_FALSE) returns SINT8_MIN (== error value) with error set
00244  *
00245  * \param boundary1 Lower boundary limit
00246  * \param boundary2 Upper boundary limit
00247  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
00248  *
00249  * \returns Random boundary value for the given range and domain or SINT8_MIN with error set
00250  */
00251 Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain);
00252 
00253 
00254 /**
00255  * Returns a random boundary value for Sint16 within the given boundaries.
00256  * Boundaries are inclusive, see the usage examples below. If validDomain
00257  * is true, the function will only return valid boundaries, otherwise non-valid
00258  * boundaries are also possible.
00259  * If boundary1 > boundary2, the values are swapped
00260  *
00261  * Usage examples:
00262  * RandomSint16BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20
00263  * RandomSint16BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9
00264  * RandomSint16BoundaryValue(SINT16_MIN, 99, SDL_FALSE) returns 100
00265  * RandomSint16BoundaryValue(SINT16_MIN, SINT16_MAX, SDL_FALSE) returns SINT16_MIN (== error value) with error set
00266  *
00267  * \param boundary1 Lower boundary limit
00268  * \param boundary2 Upper boundary limit
00269  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
00270  *
00271  * \returns Random boundary value for the given range and domain or SINT16_MIN with error set
00272  */
00273 Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain);
00274 
00275 /**
00276  * Returns a random boundary value for Sint32 within the given boundaries.
00277  * Boundaries are inclusive, see the usage examples below. If validDomain
00278  * is true, the function will only return valid boundaries, otherwise non-valid
00279  * boundaries are also possible.
00280  * If boundary1 > boundary2, the values are swapped
00281  *
00282  * Usage examples:
00283  * RandomSint32BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20
00284  * RandomSint32BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9
00285  * RandomSint32BoundaryValue(SINT32_MIN, 99, SDL_FALSE) returns 100
00286  * RandomSint32BoundaryValue(SINT32_MIN, SINT32_MAX, SDL_FALSE) returns SINT32_MIN (== error value)
00287  *
00288  * \param boundary1 Lower boundary limit
00289  * \param boundary2 Upper boundary limit
00290  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
00291  *
00292  * \returns Random boundary value for the given range and domain or SINT32_MIN with error set
00293  */
00294 Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain);
00295 
00296 /**
00297  * Returns a random boundary value for Sint64 within the given boundaries.
00298  * Boundaries are inclusive, see the usage examples below. If validDomain
00299  * is true, the function will only return valid boundaries, otherwise non-valid
00300  * boundaries are also possible.
00301  * If boundary1 > boundary2, the values are swapped
00302  *
00303  * Usage examples:
00304  * RandomSint64BoundaryValue(-10, 20, SDL_TRUE) returns -11, -10, 19 or 20
00305  * RandomSint64BoundaryValue(-100, -10, SDL_FALSE) returns -101 or -9
00306  * RandomSint64BoundaryValue(SINT64_MIN, 99, SDL_FALSE) returns 100
00307  * RandomSint64BoundaryValue(SINT64_MIN, SINT64_MAX, SDL_FALSE) returns SINT64_MIN (== error value) and error set
00308  *
00309  * \param boundary1 Lower boundary limit
00310  * \param boundary2 Upper boundary limit
00311  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
00312  *
00313  * \returns Random boundary value for the given range and domain or SINT64_MIN with error set
00314  */
00315 Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain);
00316 
00317 
00318 /**
00319  * Returns integer in range [min, max] (inclusive).
00320  * Min and max values can be negative values.
00321  * If Max in smaller tham min, then the values are swapped.
00322  * Min and max are the same value, that value will be returned.
00323  *
00324  * \param min Minimum inclusive value of returned random number
00325  * \param max Maximum inclusive value of returned random number
00326  *
00327  * \returns Generated random integer in range
00328  */
00329 Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
00330 
00331 
00332 /**
00333  * Generates random null-terminated string. The minimum length for
00334  * the string is 1 character, maximum length for the string is 255
00335  * characters and it can contain ASCII characters from 32 to 126.
00336  *
00337  * Note: Returned string needs to be deallocated.
00338  *
00339  * \returns Newly allocated random string; or NULL if length was invalid or string could not be allocated.
00340  */
00341 char * SDLTest_RandomAsciiString();
00342 
00343 
00344 /**
00345  * Generates random null-terminated string. The maximum length for
00346  * the string is defined by the maxLength parameter.
00347  * String can contain ASCII characters from 32 to 126.
00348  *
00349  * Note: Returned string needs to be deallocated.
00350  *
00351  * \param maxLength The maximum length of the generated string.
00352  *
00353  * \returns Newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
00354  */
00355 char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
00356 
00357 
00358 /**
00359  * Generates random null-terminated string. The length for
00360  * the string is defined by the size parameter.
00361  * String can contain ASCII characters from 32 to 126.
00362  *
00363  * Note: Returned string needs to be deallocated.
00364  *
00365  * \param size The length of the generated string
00366  *
00367  * \returns Newly allocated random string; or NULL if size was invalid or string could not be allocated.
00368  */
00369 char * SDLTest_RandomAsciiStringOfSize(int size);
00370 
00371 /**
00372  * Returns the invocation count for the fuzzer since last ...FuzzerInit.
00373  */
00374 int SDLTest_GetFuzzerInvocationCount();
00375 
00376 /* Ends C function definitions when using C++ */
00377 #ifdef __cplusplus
00378 }
00379 #endif
00380 #include "close_code.h"
00381 
00382 #endif /* _SDL_test_fuzzer_h */
00383 
00384 /* vi: set ts=4 sw=4 expandtab: */