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