test.h revision 9cabb72c6d6feb65e839ce50765643b98bb9a301
/** @file
* IPRT - Test.
*/
/*
* Copyright (C) 2009 Sun Microsystems, Inc.
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* you can redistribute it and/or modify it under the terms of the GNU
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE 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.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#ifndef ___iprt_test_h
#define ___iprt_test_h
#include <iprt/cdefs.h>
#include <iprt/types.h>
#include <iprt/stdarg.h>
/** A test handle. */
typedef struct RTTESTINT *RTTEST;
/** A pointer to a test handle. */
typedef RTTEST *PRTTEST;
/** A const pointer to a test handle. */
typedef RTTEST const *PCRTTEST;
/** A NIL Test handle. */
#define NIL_RTTEST ((RTTEST)0)
__BEGIN_DECLS
/**
* Creates a test instance.
*
* @returns IPRT status code.
* @param pszTest The test name.
* @param phTest Where to store the test instance handle.
*/
RTR3DECL(int) RTTestCreate(const char *pszTest, PRTTEST phTest);
/**
* Destroys a test instance previously created by RTTestCreate.
*
* @returns IPRT status code.
* @param hTest The test handle. NIL_RTTEST is ignored.
*/
RTR3DECL(int) RTTestDestroy(RTTEST hTest);
/**
* Allocate a block of guarded memory.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param cb The amount of memory to allocate.
* @param cbAlign The alignment of the returned block.
* @param fHead Head or tail optimized guard.
* @param ppvUser Where to return the pointer to the block.
*/
RTR3DECL(int) RTTestGuardedAlloc(RTTEST hTest, size_t cb, uint32_t cbAlign, bool fHead, void **ppvUser);
/**
* Allocates a block of guarded memory where the guarded is immediately after
* the user memory.
*
* @returns Pointer to the allocated memory. NULL on failure.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param cb The amount of memory to allocate.
*/
RTR3DECL(void *) RTTestGuardedAllocTail(RTTEST hTest, size_t cb);
/**
* Allocates a block of guarded memory where the guarded is right in front of
* the user memory.
*
* @returns Pointer to the allocated memory. NULL on failure.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param cb The amount of memory to allocate.
*/
RTR3DECL(void *) RTTestGuardedAllocHead(RTTEST hTest, size_t cb);
/**
* Frees a block of guarded memory.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pv The memory. NULL is ignored.
*/
RTR3DECL(int) RTTestGuardedFree(RTTEST hTest, void *pv);
/**
* Test vprintf making sure the output starts on a new line.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message.
* @param va Arguments.
*/
RTR3DECL(int) RTTestPrintfNlV(RTTEST hTest, const char *pszFormat, va_list va);
/**
* Test printf making sure the output starts on a new line.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message.
* @param ... Arguments.
*/
RTR3DECL(int) RTTestPrintfNl(RTTEST hTest, const char *pszFormat, ...);
/**
* Test vprintf, makes sure lines are prefixed and so forth.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message.
* @param va Arguments.
*/
RTR3DECL(int) RTTestPrintfV(RTTEST hTest, const char *pszFormat, va_list va);
/**
* Test printf, makes sure lines are prefixed and so forth.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message.
* @param ... Arguments.
*/
RTR3DECL(int) RTTestPrintf(RTTEST hTest, const char *pszFormat, ...);
/**
* Prints the test banner.
*
* @returns Number of chars printed.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
RTR3DECL(int) RTTestBanner(RTTEST hTest);
/**
* Summaries the test, destroys the test instance and return an exit code.
*
* @returns Test program exit code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
RTR3DECL(int) RTTestSummaryAndDestroy(RTTEST hTest);
/**
* Increments the error counter.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
*/
RTR3DECL(int) RTTestErrorInc(RTTEST hTest);
/**
* Increments the error counter and prints a failure message.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message. No trailing newline.
* @param va The arguments.
*/
RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va);
/**
* Increments the error counter and prints a failure message.
*
* @returns IPRT status code.
* @param hTest The test handle. If NIL_RTTEST we'll use the one
* associated with the calling thread.
* @param pszFormat The message. No trailing newline.
* @param ... The arguments.
*/
RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...);
__END_DECLS
#endif