initterm.h revision 7d172bb4ed1217e28e28829193159954f6b40ef7
45e9809aff7304721fddb95654901b32195c9c7avboxsync * IPRT - Runtime Init/Term.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Copyright (C) 2006-2013 Oracle Corporation
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
45e9809aff7304721fddb95654901b32195c9c7avboxsync * available from http://www.virtualbox.org. This file is free software;
45e9809aff7304721fddb95654901b32195c9c7avboxsync * you can redistribute it and/or modify it under the terms of the GNU
45e9809aff7304721fddb95654901b32195c9c7avboxsync * General Public License (GPL) as published by the Free Software
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The contents of this file may alternatively be used under the terms
45e9809aff7304721fddb95654901b32195c9c7avboxsync * of the Common Development and Distribution License Version 1.0
45e9809aff7304721fddb95654901b32195c9c7avboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * VirtualBox OSE distribution, in which case the provisions of the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * CDDL are applicable instead of those of the GPL.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * You may elect to license modified versions of this file under the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * terms and conditions of either the GPL or the CDDL or both.
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** @defgroup grp_rt IPRT C/C++ APIs
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** @defgroup grp_rt_initterm Init / Term
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** @name RTR3Init flags (RTR3INIT_XXX).
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** Try initialize SUPLib. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** Initializing IPRT from a DLL. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** We are sharing a process space, so we need to behave. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** The caller ensures that the argument bector is UTF-8. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** @name RTR3InitEx version
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** Version 1. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** The current version. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Initializes the runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @returns iprt status code.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param fFlags Flags, see RTR3INIT_XXX.
45e9809aff7304721fddb95654901b32195c9c7avboxsyncRTR3DECL(int) RTR3InitExeNoArguments(uint32_t fFlags);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Initializes the runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @returns iprt status code.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param cArgs Pointer to the argument count.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param ppapszArgs Pointer to the argument vector pointer.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param fFlags Flags, see RTR3INIT_XXX.
45e9809aff7304721fddb95654901b32195c9c7avboxsyncRTR3DECL(int) RTR3InitExe(int cArgs, char ***papszArgs, uint32_t fFlags);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Initializes the runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @returns iprt status code.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param fFlags Flags, see RTR3INIT_XXX.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Initializes the runtime library and possibly also SUPLib too.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Avoid this interface, it's not considered stable.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @returns IPRT status code.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param iVersion The interface version. Must be 0 atm.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param fFlags Flags, see RTR3INIT_XXX.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param cArgs Pointer to the argument count.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param ppapszArgs Pointer to the argument vector pointer. NULL
45e9809aff7304721fddb95654901b32195c9c7avboxsync * allowed if @a cArgs is 0.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param pszProgramPath The program path. Pass NULL if we're to figure it
45e9809aff7304721fddb95654901b32195c9c7avboxsync * out ourselves.
45e9809aff7304721fddb95654901b32195c9c7avboxsyncRTR3DECL(int) RTR3InitEx(uint32_t iVersion, uint32_t fFlags, int cArgs, char ***papszArgs, const char *pszProgramPath);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Terminates the runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Are we running in unobtrusive mode?
45e9809aff7304721fddb95654901b32195c9c7avboxsync#endif /* IN_RING3 */
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Initializes the ring-0 driver runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @returns iprt status code.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param fReserved Flags reserved for the future.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Terminates the ring-0 driver runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Forcibily terminates the ring-0 driver runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This should be used when statically linking the IPRT. Module using dynamic
45e9809aff7304721fddb95654901b32195c9c7avboxsync * linking shall use RTR0Term. If you're not sure, use RTR0Term!
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Initializes the raw-mode context runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @returns iprt status code.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param u64ProgramStartNanoTS The startup timestamp.
45e9809aff7304721fddb95654901b32195c9c7avboxsyncRTRCDECL(int) RTRCInit(uint64_t u64ProgramStartNanoTS);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Terminates the raw-mode context runtime library.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Termination reason.
45e9809aff7304721fddb95654901b32195c9c7avboxsync /** Normal exit. iStatus contains the exit code. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync /** Any abnormal exit. iStatus is 0 and has no meaning. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync /** Killed by a signal. The iStatus contains the signal number. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync /** The IPRT module is being unloaded. iStatus is 0 and has no meaning. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** Whether lazy clean up is Okay or not.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * When the process is exiting, it is a waste of time to for instance free heap
45e9809aff7304721fddb95654901b32195c9c7avboxsync * memory or close open files. OTOH, when the runtime is unloaded from the
45e9809aff7304721fddb95654901b32195c9c7avboxsync * process, it is important to release absolutely all resources to prevent
45e9809aff7304721fddb95654901b32195c9c7avboxsync * resource leaks. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync#define RTTERMREASON_IS_LAZY_CLEANUP_OK(enmReason) ((enmReason) != RTTERMREASON_UNLOAD)
45e9809aff7304721fddb95654901b32195c9c7avboxsync * IPRT termination callback function.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param enmReason The cause of the termination.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param iStatus The meaning of this depends on enmReason.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param pvUser User argument passed to RTTermRegisterCallback.
45e9809aff7304721fddb95654901b32195c9c7avboxsynctypedef DECLCALLBACK(void) FNRTTERMCALLBACK(RTTERMREASON enmReason, int32_t iStatus, void *pvUser);
45e9809aff7304721fddb95654901b32195c9c7avboxsync/** Pointer to an IPRT termination callback function. */
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Registers a termination callback.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * This is intended for performing clean up during IPRT termination. Frequently
45e9809aff7304721fddb95654901b32195c9c7avboxsync * paired with lazy initialization thru RTOnce.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * The callbacks are called in LIFO order.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @returns IPRT status code.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param pfnCallback The callback function.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param pvUser The user argument for the callback.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @remarks May need to acquire a fast mutex or critical section, so use with
45e9809aff7304721fddb95654901b32195c9c7avboxsync * some care in ring-0 context.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @remarks Be very careful using this from code that may be unloaded before
45e9809aff7304721fddb95654901b32195c9c7avboxsync * IPRT terminates. Unlike some atexit and on_exit implementations,
45e9809aff7304721fddb95654901b32195c9c7avboxsync * IPRT will not automatically unregister callbacks when a module gets
45e9809aff7304721fddb95654901b32195c9c7avboxsync * unloaded.
45e9809aff7304721fddb95654901b32195c9c7avboxsyncRTDECL(int) RTTermRegisterCallback(PFNRTTERMCALLBACK pfnCallback, void *pvUser);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Deregister a termination callback.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @returns VINF_SUCCESS if found, VERR_NOT_FOUND if the callback/pvUser pair
45e9809aff7304721fddb95654901b32195c9c7avboxsync * wasn't found.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param pfnCallback The callback function.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param pvUser The user argument for the callback.
45e9809aff7304721fddb95654901b32195c9c7avboxsyncRTDECL(int) RTTermDeregisterCallback(PFNRTTERMCALLBACK pfnCallback, void *pvUser);
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Runs the termination callback queue.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * Normally called by an internal IPRT termination function, but may also be
45e9809aff7304721fddb95654901b32195c9c7avboxsync * called by external code immediately prior to terminating IPRT if it is in a
45e9809aff7304721fddb95654901b32195c9c7avboxsync * better position to state the termination reason and/or status.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param enmReason The reason why it's called.
45e9809aff7304721fddb95654901b32195c9c7avboxsync * @param iStatus The associated exit status or signal number.