/** @file * IPRT - Runtime Init/Term. */ /* * Copyright (C) 2006-2024 Oracle and/or its affiliates. * * This file is part of VirtualBox base platform packages, as * available from https://www.virtualbox.org. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation, in version 3 of the * License. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, see . * * The contents of this file may alternatively be used under the terms * of the Common Development and Distribution License Version 1.0 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included * in the VirtualBox 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. * * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0 */ #ifndef IPRT_INCLUDED_initterm_h #define IPRT_INCLUDED_initterm_h #ifndef RT_WITHOUT_PRAGMA_ONCE # pragma once #endif #include #include RT_C_DECLS_BEGIN /** @defgroup grp_rt IPRT C/C++ APIs * @{ */ /** @defgroup grp_rt_initterm RTInit/RTTerm - Initialization and Termination * * APIs for initializing and terminating the IPRT, optionally it can also * convert input arguments to UTF-8 (in ring-3). * * @sa RTOnce, RTOnceEx. * * @{ */ #ifdef IN_RING3 /** @name RTR3INIT_FLAGS_XXX - RTR3Init* flags. * @see RTR3InitExeNoArguments, RTR3InitExe, RTR3InitDll, RTR3InitEx * @{ */ /** Initializing IPRT from a DLL. */ # define RTR3INIT_FLAGS_DLL RT_BIT(0) /** The caller ensures that the argument vector is UTF-8. */ # define RTR3INIT_FLAGS_UTF8_ARGV RT_BIT(1) /** Indicates that this is a standalone application without any additional * shared libraries in the application directory. Mainly windows loader mess. */ # define RTR3INIT_FLAGS_STANDALONE_APP RT_BIT(2) /** We are sharing a process space, so we need to behave. */ # define RTR3INIT_FLAGS_UNOBTRUSIVE RT_BIT(3) /** Initialize SUPLib (must not fail). */ # define RTR3INIT_FLAGS_SUPLIB RT_BIT(16) /** Try initialize SUPLib and ignore failures. */ # define RTR3INIT_FLAGS_TRY_SUPLIB RT_BIT(17) /** Shift count for passing thru SUPR3INIT_F_XXX flags. */ # define RTR3INIT_FLAGS_SUPLIB_SHIFT 18 /** The mask covering the passthru SUPR3INIT_F_XXX flags. */ # define RTR3INIT_FLAGS_SUPLIB_MASK UINT32_C(0xfffc0000) /** Valid flag mask. */ # define RTR3INIT_FLAGS_VALID_MASK UINT32_C(0xffff000f) /** @} */ /** @name RTR3InitEx version * @{ */ /** Version 1. */ # define RTR3INIT_VER_1 UINT32_C(1) /** Version 2 - new flags, rearranged a bit. */ # define RTR3INIT_VER_2 UINT32_C(2) /** The current version. */ # define RTR3INIT_VER_CUR RTR3INIT_VER_2 /** @} */ /** * Initializes the runtime library. * * @returns iprt status code. * @param fFlags Flags, see RTR3INIT_FLAGS_XXX. */ RTR3DECL(int) RTR3InitExeNoArguments(uint32_t fFlags); /** * Initializes the runtime library. * * @returns iprt status code. * @param cArgs Pointer to the argument count. * @param ppapszArgs Pointer to the argument vector pointer. * @param fFlags Flags, see RTR3INIT_FLAGS_XXX. */ RTR3DECL(int) RTR3InitExe(int cArgs, char ***ppapszArgs, uint32_t fFlags); /** * Initializes the runtime library. * * @returns iprt status code. * @param fFlags Flags, see RTR3INIT_FLAGS_XXX. */ RTR3DECL(int) RTR3InitDll(uint32_t fFlags); /** * Initializes the runtime library and possibly also SUPLib too. * * Avoid this interface, it's not considered stable. * * @returns IPRT status code. * @param iVersion The interface version. Must be 0 atm. * @param fFlags Flags, see RTR3INIT_FLAGS_XXX. * @param cArgs Pointer to the argument count. * @param ppapszArgs Pointer to the argument vector pointer. NULL * allowed if @a cArgs is 0. * @param pszProgramPath The program path. Pass NULL if we're to figure it * out ourselves. */ RTR3DECL(int) RTR3InitEx(uint32_t iVersion, uint32_t fFlags, int cArgs, char ***ppapszArgs, const char *pszProgramPath); /** * Terminates the runtime library. */ RTR3DECL(void) RTR3Term(void); /** * Is IPRT succesfully initialized? * * @returns true/false. */ RTR3DECL(bool) RTR3InitIsInitialized(void); /** * Are we running in unobtrusive mode? * @returns true/false. */ RTR3DECL(bool) RTR3InitIsUnobtrusive(void); #endif /* IN_RING3 */ #ifdef IN_RING0 /** * Initializes the ring-0 driver runtime library. * * @returns iprt status code. * @param fReserved Flags reserved for the future. */ RTR0DECL(int) RTR0Init(unsigned fReserved); /** * Terminates the ring-0 driver runtime library. */ RTR0DECL(void) RTR0Term(void); /** * Forcibily terminates the ring-0 driver runtime library. * * This should be used when statically linking the IPRT. Module using dynamic * linking shall use RTR0Term. If you're not sure, use RTR0Term! */ RTR0DECL(void) RTR0TermForced(void); #endif #ifdef IN_RC /** * Initializes the raw-mode context runtime library. * * @returns iprt status code. * * @param u64ProgramStartNanoTS The startup timestamp. */ RTRCDECL(int) RTRCInit(uint64_t u64ProgramStartNanoTS); /** * Terminates the raw-mode context runtime library. */ RTRCDECL(void) RTRCTerm(void); #endif /** * Termination reason. */ typedef enum RTTERMREASON { /** Normal exit. iStatus contains the exit code. */ RTTERMREASON_EXIT = 1, /** Any abnormal exit. iStatus is 0 and has no meaning. */ RTTERMREASON_ABEND, /** Killed by a signal. The iStatus contains the signal number. */ RTTERMREASON_SIGNAL, /** The IPRT module is being unloaded. iStatus is 0 and has no meaning. */ RTTERMREASON_UNLOAD } RTTERMREASON; /** Whether lazy clean up is Okay or not. * When the process is exiting, it is a waste of time to for instance free heap * memory or close open files. OTOH, when the runtime is unloaded from the * process, it is important to release absolutely all resources to prevent * resource leaks. */ #define RTTERMREASON_IS_LAZY_CLEANUP_OK(enmReason) ((enmReason) != RTTERMREASON_UNLOAD) /** * IPRT termination callback function. * * @param enmReason The cause of the termination. * @param iStatus The meaning of this depends on enmReason. * @param pvUser User argument passed to RTTermRegisterCallback. */ typedef DECLCALLBACKTYPE(void, FNRTTERMCALLBACK,(RTTERMREASON enmReason, int32_t iStatus, void *pvUser)); /** Pointer to an IPRT termination callback function. */ typedef FNRTTERMCALLBACK *PFNRTTERMCALLBACK; /** * Registers a termination callback. * * This is intended for performing clean up during IPRT termination. Frequently * paired with lazy initialization thru RTOnce. * * The callbacks are called in LIFO order. * * @returns IPRT status code. * * @param pfnCallback The callback function. * @param pvUser The user argument for the callback. * * @remarks May need to acquire a fast mutex or critical section, so use with * some care in ring-0 context. * * @remarks Be very careful using this from code that may be unloaded before * IPRT terminates. Unlike some atexit and on_exit implementations, * IPRT will not automatically unregister callbacks when a module gets * unloaded. */ RTDECL(int) RTTermRegisterCallback(PFNRTTERMCALLBACK pfnCallback, void *pvUser); /** * Deregister a termination callback. * * @returns VINF_SUCCESS if found, VERR_NOT_FOUND if the callback/pvUser pair * wasn't found. * * @param pfnCallback The callback function. * @param pvUser The user argument for the callback. */ RTDECL(int) RTTermDeregisterCallback(PFNRTTERMCALLBACK pfnCallback, void *pvUser); /** * Runs the termination callback queue. * * Normally called by an internal IPRT termination function, but may also be * called by external code immediately prior to terminating IPRT if it is in a * better position to state the termination reason and/or status. * * @param enmReason The reason why it's called. * @param iStatus The associated exit status or signal number. */ RTDECL(void) RTTermRunCallbacks(RTTERMREASON enmReason, int32_t iStatus); /** @} */ /** @} */ RT_C_DECLS_END #endif /* !IPRT_INCLUDED_initterm_h */