[1] | 1 | /** @file
|
---|
[8245] | 2 | * IPRT - Runtime Init/Term.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[98103] | 6 | * Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
---|
[1] | 7 | *
|
---|
[96407] | 8 | * This file is part of VirtualBox base platform packages, as
|
---|
| 9 | * available from https://www.virtualbox.org.
|
---|
[5999] | 10 | *
|
---|
[96407] | 11 | * This program is free software; you can redistribute it and/or
|
---|
| 12 | * modify it under the terms of the GNU General Public License
|
---|
| 13 | * as published by the Free Software Foundation, in version 3 of the
|
---|
| 14 | * License.
|
---|
| 15 | *
|
---|
| 16 | * This program is distributed in the hope that it will be useful, but
|
---|
| 17 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
| 18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
| 19 | * General Public License for more details.
|
---|
| 20 | *
|
---|
| 21 | * You should have received a copy of the GNU General Public License
|
---|
| 22 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
| 23 | *
|
---|
[5999] | 24 | * The contents of this file may alternatively be used under the terms
|
---|
| 25 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 26 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
| 27 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
[5999] | 28 | * CDDL are applicable instead of those of the GPL.
|
---|
| 29 | *
|
---|
| 30 | * You may elect to license modified versions of this file under the
|
---|
| 31 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[96407] | 32 | *
|
---|
| 33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[1] | 34 | */
|
---|
| 35 |
|
---|
[76557] | 36 | #ifndef IPRT_INCLUDED_initterm_h
|
---|
| 37 | #define IPRT_INCLUDED_initterm_h
|
---|
[76507] | 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 39 | # pragma once
|
---|
| 40 | #endif
|
---|
[1] | 41 |
|
---|
| 42 | #include <iprt/cdefs.h>
|
---|
| 43 | #include <iprt/types.h>
|
---|
| 44 |
|
---|
[20374] | 45 | RT_C_DECLS_BEGIN
|
---|
[1] | 46 |
|
---|
[36508] | 47 | /** @defgroup grp_rt IPRT C/C++ APIs
|
---|
[1] | 48 | * @{
|
---|
| 49 | */
|
---|
| 50 |
|
---|
[57942] | 51 | /** @defgroup grp_rt_initterm RTInit/RTTerm - Initialization and Termination
|
---|
| 52 | *
|
---|
| 53 | * APIs for initializing and terminating the IPRT, optionally it can also
|
---|
| 54 | * convert input arguments to UTF-8 (in ring-3).
|
---|
| 55 | *
|
---|
| 56 | * @sa RTOnce, RTOnceEx.
|
---|
| 57 | *
|
---|
[1] | 58 | * @{
|
---|
| 59 | */
|
---|
| 60 |
|
---|
| 61 | #ifdef IN_RING3
|
---|
[81549] | 62 |
|
---|
[92613] | 63 | /** @name RTR3INIT_FLAGS_XXX - RTR3Init* flags.
|
---|
| 64 | * @see RTR3InitExeNoArguments, RTR3InitExe, RTR3InitDll, RTR3InitEx
|
---|
[38636] | 65 | * @{ */
|
---|
| 66 | /** Initializing IPRT from a DLL. */
|
---|
[92613] | 67 | # define RTR3INIT_FLAGS_DLL RT_BIT(0)
|
---|
[92562] | 68 | /** The caller ensures that the argument vector is UTF-8. */
|
---|
[92613] | 69 | # define RTR3INIT_FLAGS_UTF8_ARGV RT_BIT(1)
|
---|
[59404] | 70 | /** Indicates that this is a standalone application without any additional
|
---|
| 71 | * shared libraries in the application directory. Mainly windows loader mess. */
|
---|
[92613] | 72 | # define RTR3INIT_FLAGS_STANDALONE_APP RT_BIT(2)
|
---|
| 73 | /** We are sharing a process space, so we need to behave. */
|
---|
| 74 | # define RTR3INIT_FLAGS_UNOBTRUSIVE RT_BIT(3)
|
---|
| 75 |
|
---|
| 76 | /** Initialize SUPLib (must not fail). */
|
---|
| 77 | # define RTR3INIT_FLAGS_SUPLIB RT_BIT(16)
|
---|
| 78 | /** Try initialize SUPLib and ignore failures. */
|
---|
| 79 | # define RTR3INIT_FLAGS_TRY_SUPLIB RT_BIT(17)
|
---|
| 80 | /** Shift count for passing thru SUPR3INIT_F_XXX flags. */
|
---|
| 81 | # define RTR3INIT_FLAGS_SUPLIB_SHIFT 18
|
---|
| 82 | /** The mask covering the passthru SUPR3INIT_F_XXX flags. */
|
---|
| 83 | # define RTR3INIT_FLAGS_SUPLIB_MASK UINT32_C(0xfffc0000)
|
---|
| 84 |
|
---|
| 85 | /** Valid flag mask. */
|
---|
| 86 | # define RTR3INIT_FLAGS_VALID_MASK UINT32_C(0xffff000f)
|
---|
[38636] | 87 | /** @} */
|
---|
| 88 |
|
---|
| 89 | /** @name RTR3InitEx version
|
---|
| 90 | * @{ */
|
---|
| 91 | /** Version 1. */
|
---|
[92613] | 92 | # define RTR3INIT_VER_1 UINT32_C(1)
|
---|
| 93 | /** Version 2 - new flags, rearranged a bit. */
|
---|
| 94 | # define RTR3INIT_VER_2 UINT32_C(2)
|
---|
[38636] | 95 | /** The current version. */
|
---|
[92613] | 96 | # define RTR3INIT_VER_CUR RTR3INIT_VER_2
|
---|
[38636] | 97 | /** @} */
|
---|
| 98 |
|
---|
[1] | 99 | /**
|
---|
[11822] | 100 | * Initializes the runtime library.
|
---|
[1] | 101 | *
|
---|
| 102 | * @returns iprt status code.
|
---|
[92613] | 103 | * @param fFlags Flags, see RTR3INIT_FLAGS_XXX.
|
---|
[11822] | 104 | */
|
---|
[38636] | 105 | RTR3DECL(int) RTR3InitExeNoArguments(uint32_t fFlags);
|
---|
[11822] | 106 |
|
---|
| 107 | /**
|
---|
[38636] | 108 | * Initializes the runtime library.
|
---|
[1] | 109 | *
|
---|
[38636] | 110 | * @returns iprt status code.
|
---|
| 111 | * @param cArgs Pointer to the argument count.
|
---|
| 112 | * @param ppapszArgs Pointer to the argument vector pointer.
|
---|
[92613] | 113 | * @param fFlags Flags, see RTR3INIT_FLAGS_XXX.
|
---|
[1] | 114 | */
|
---|
[57926] | 115 | RTR3DECL(int) RTR3InitExe(int cArgs, char ***ppapszArgs, uint32_t fFlags);
|
---|
[1] | 116 |
|
---|
| 117 | /**
|
---|
[38636] | 118 | * Initializes the runtime library.
|
---|
[11822] | 119 | *
|
---|
[38636] | 120 | * @returns iprt status code.
|
---|
[92613] | 121 | * @param fFlags Flags, see RTR3INIT_FLAGS_XXX.
|
---|
[11822] | 122 | */
|
---|
[38636] | 123 | RTR3DECL(int) RTR3InitDll(uint32_t fFlags);
|
---|
[11822] | 124 |
|
---|
| 125 | /**
|
---|
[11841] | 126 | * Initializes the runtime library and possibly also SUPLib too.
|
---|
[13813] | 127 | *
|
---|
[11841] | 128 | * Avoid this interface, it's not considered stable.
|
---|
[13813] | 129 | *
|
---|
[11841] | 130 | * @returns IPRT status code.
|
---|
| 131 | * @param iVersion The interface version. Must be 0 atm.
|
---|
[92613] | 132 | * @param fFlags Flags, see RTR3INIT_FLAGS_XXX.
|
---|
[38636] | 133 | * @param cArgs Pointer to the argument count.
|
---|
| 134 | * @param ppapszArgs Pointer to the argument vector pointer. NULL
|
---|
| 135 | * allowed if @a cArgs is 0.
|
---|
| 136 | * @param pszProgramPath The program path. Pass NULL if we're to figure it
|
---|
| 137 | * out ourselves.
|
---|
[11841] | 138 | */
|
---|
[57926] | 139 | RTR3DECL(int) RTR3InitEx(uint32_t iVersion, uint32_t fFlags, int cArgs, char ***ppapszArgs, const char *pszProgramPath);
|
---|
[11841] | 140 |
|
---|
[11822] | 141 | /**
|
---|
[1] | 142 | * Terminates the runtime library.
|
---|
| 143 | */
|
---|
| 144 | RTR3DECL(void) RTR3Term(void);
|
---|
| 145 |
|
---|
[44456] | 146 | /**
|
---|
[53525] | 147 | * Is IPRT succesfully initialized?
|
---|
| 148 | *
|
---|
| 149 | * @returns true/false.
|
---|
| 150 | */
|
---|
| 151 | RTR3DECL(bool) RTR3InitIsInitialized(void);
|
---|
| 152 |
|
---|
| 153 | /**
|
---|
[44456] | 154 | * Are we running in unobtrusive mode?
|
---|
[46583] | 155 | * @returns true/false.
|
---|
[44456] | 156 | */
|
---|
| 157 | RTR3DECL(bool) RTR3InitIsUnobtrusive(void);
|
---|
[81549] | 158 |
|
---|
[11822] | 159 | #endif /* IN_RING3 */
|
---|
[1] | 160 |
|
---|
[11822] | 161 |
|
---|
[1] | 162 | #ifdef IN_RING0
|
---|
| 163 | /**
|
---|
[33540] | 164 | * Initializes the ring-0 driver runtime library.
|
---|
[1] | 165 | *
|
---|
| 166 | * @returns iprt status code.
|
---|
| 167 | * @param fReserved Flags reserved for the future.
|
---|
| 168 | */
|
---|
| 169 | RTR0DECL(int) RTR0Init(unsigned fReserved);
|
---|
| 170 |
|
---|
| 171 | /**
|
---|
| 172 | * Terminates the ring-0 driver runtime library.
|
---|
| 173 | */
|
---|
| 174 | RTR0DECL(void) RTR0Term(void);
|
---|
[24179] | 175 |
|
---|
| 176 | /**
|
---|
| 177 | * Forcibily terminates the ring-0 driver runtime library.
|
---|
| 178 | *
|
---|
| 179 | * This should be used when statically linking the IPRT. Module using dynamic
|
---|
| 180 | * linking shall use RTR0Term. If you're not sure, use RTR0Term!
|
---|
| 181 | */
|
---|
| 182 | RTR0DECL(void) RTR0TermForced(void);
|
---|
[1] | 183 | #endif
|
---|
| 184 |
|
---|
[13832] | 185 | #ifdef IN_RC
|
---|
[3123] | 186 | /**
|
---|
[13813] | 187 | * Initializes the raw-mode context runtime library.
|
---|
[3123] | 188 | *
|
---|
| 189 | * @returns iprt status code.
|
---|
| 190 | *
|
---|
| 191 | * @param u64ProgramStartNanoTS The startup timestamp.
|
---|
| 192 | */
|
---|
[26226] | 193 | RTRCDECL(int) RTRCInit(uint64_t u64ProgramStartNanoTS);
|
---|
[3123] | 194 |
|
---|
| 195 | /**
|
---|
[13813] | 196 | * Terminates the raw-mode context runtime library.
|
---|
[3123] | 197 | */
|
---|
[26226] | 198 | RTRCDECL(void) RTRCTerm(void);
|
---|
[3123] | 199 | #endif
|
---|
| 200 |
|
---|
| 201 |
|
---|
[19897] | 202 | /**
|
---|
| 203 | * Termination reason.
|
---|
| 204 | */
|
---|
| 205 | typedef enum RTTERMREASON
|
---|
| 206 | {
|
---|
| 207 | /** Normal exit. iStatus contains the exit code. */
|
---|
| 208 | RTTERMREASON_EXIT = 1,
|
---|
| 209 | /** Any abnormal exit. iStatus is 0 and has no meaning. */
|
---|
| 210 | RTTERMREASON_ABEND,
|
---|
| 211 | /** Killed by a signal. The iStatus contains the signal number. */
|
---|
| 212 | RTTERMREASON_SIGNAL,
|
---|
| 213 | /** The IPRT module is being unloaded. iStatus is 0 and has no meaning. */
|
---|
| 214 | RTTERMREASON_UNLOAD
|
---|
| 215 | } RTTERMREASON;
|
---|
| 216 |
|
---|
| 217 | /** Whether lazy clean up is Okay or not.
|
---|
| 218 | * When the process is exiting, it is a waste of time to for instance free heap
|
---|
| 219 | * memory or close open files. OTOH, when the runtime is unloaded from the
|
---|
| 220 | * process, it is important to release absolutely all resources to prevent
|
---|
| 221 | * resource leaks. */
|
---|
| 222 | #define RTTERMREASON_IS_LAZY_CLEANUP_OK(enmReason) ((enmReason) != RTTERMREASON_UNLOAD)
|
---|
| 223 |
|
---|
| 224 |
|
---|
| 225 | /**
|
---|
| 226 | * IPRT termination callback function.
|
---|
| 227 | *
|
---|
| 228 | * @param enmReason The cause of the termination.
|
---|
| 229 | * @param iStatus The meaning of this depends on enmReason.
|
---|
| 230 | * @param pvUser User argument passed to RTTermRegisterCallback.
|
---|
| 231 | */
|
---|
[85121] | 232 | typedef DECLCALLBACKTYPE(void, FNRTTERMCALLBACK,(RTTERMREASON enmReason, int32_t iStatus, void *pvUser));
|
---|
[19897] | 233 | /** Pointer to an IPRT termination callback function. */
|
---|
| 234 | typedef FNRTTERMCALLBACK *PFNRTTERMCALLBACK;
|
---|
| 235 |
|
---|
| 236 |
|
---|
| 237 | /**
|
---|
| 238 | * Registers a termination callback.
|
---|
| 239 | *
|
---|
| 240 | * This is intended for performing clean up during IPRT termination. Frequently
|
---|
| 241 | * paired with lazy initialization thru RTOnce.
|
---|
| 242 | *
|
---|
| 243 | * The callbacks are called in LIFO order.
|
---|
| 244 | *
|
---|
| 245 | * @returns IPRT status code.
|
---|
| 246 | *
|
---|
| 247 | * @param pfnCallback The callback function.
|
---|
| 248 | * @param pvUser The user argument for the callback.
|
---|
| 249 | *
|
---|
| 250 | * @remarks May need to acquire a fast mutex or critical section, so use with
|
---|
| 251 | * some care in ring-0 context.
|
---|
| 252 | *
|
---|
| 253 | * @remarks Be very careful using this from code that may be unloaded before
|
---|
| 254 | * IPRT terminates. Unlike some atexit and on_exit implementations,
|
---|
| 255 | * IPRT will not automatically unregister callbacks when a module gets
|
---|
| 256 | * unloaded.
|
---|
| 257 | */
|
---|
| 258 | RTDECL(int) RTTermRegisterCallback(PFNRTTERMCALLBACK pfnCallback, void *pvUser);
|
---|
| 259 |
|
---|
| 260 | /**
|
---|
| 261 | * Deregister a termination callback.
|
---|
| 262 | *
|
---|
| 263 | * @returns VINF_SUCCESS if found, VERR_NOT_FOUND if the callback/pvUser pair
|
---|
| 264 | * wasn't found.
|
---|
| 265 | *
|
---|
| 266 | * @param pfnCallback The callback function.
|
---|
| 267 | * @param pvUser The user argument for the callback.
|
---|
| 268 | */
|
---|
| 269 | RTDECL(int) RTTermDeregisterCallback(PFNRTTERMCALLBACK pfnCallback, void *pvUser);
|
---|
| 270 |
|
---|
| 271 | /**
|
---|
| 272 | * Runs the termination callback queue.
|
---|
| 273 | *
|
---|
| 274 | * Normally called by an internal IPRT termination function, but may also be
|
---|
| 275 | * called by external code immediately prior to terminating IPRT if it is in a
|
---|
| 276 | * better position to state the termination reason and/or status.
|
---|
| 277 | *
|
---|
| 278 | * @param enmReason The reason why it's called.
|
---|
| 279 | * @param iStatus The associated exit status or signal number.
|
---|
| 280 | */
|
---|
| 281 | RTDECL(void) RTTermRunCallbacks(RTTERMREASON enmReason, int32_t iStatus);
|
---|
| 282 |
|
---|
[1] | 283 | /** @} */
|
---|
| 284 |
|
---|
| 285 | /** @} */
|
---|
| 286 |
|
---|
[20374] | 287 | RT_C_DECLS_END
|
---|
[1] | 288 |
|
---|
| 289 |
|
---|
[76585] | 290 | #endif /* !IPRT_INCLUDED_initterm_h */
|
---|
[1] | 291 |
|
---|