ubuntu/vbox/include/iprt/initterm.h

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