VirtualBox

source: vbox/trunk/include/iprt/initterm.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.8 KB
Line 
1/** @file
2 * IPRT - Runtime Init/Term.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
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 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
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
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.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_initterm_h
37#define IPRT_INCLUDED_initterm_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44
45RT_C_DECLS_BEGIN
46
47/** @defgroup grp_rt IPRT C/C++ APIs
48 * @{
49 */
50
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 *
58 * @{
59 */
60
61#ifdef IN_RING3
62
63/** @name RTR3INIT_FLAGS_XXX - RTR3Init* flags.
64 * @see RTR3InitExeNoArguments, RTR3InitExe, RTR3InitDll, RTR3InitEx
65 * @{ */
66/** Initializing IPRT from a DLL. */
67# define RTR3INIT_FLAGS_DLL RT_BIT(0)
68/** The caller ensures that the argument vector is UTF-8. */
69# define RTR3INIT_FLAGS_UTF8_ARGV RT_BIT(1)
70/** Indicates that this is a standalone application without any additional
71 * shared libraries in the application directory. Mainly windows loader mess. */
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)
87/** @} */
88
89/** @name RTR3InitEx version
90 * @{ */
91/** Version 1. */
92# define RTR3INIT_VER_1 UINT32_C(1)
93/** Version 2 - new flags, rearranged a bit. */
94# define RTR3INIT_VER_2 UINT32_C(2)
95/** The current version. */
96# define RTR3INIT_VER_CUR RTR3INIT_VER_2
97/** @} */
98
99/**
100 * Initializes the runtime library.
101 *
102 * @returns iprt status code.
103 * @param fFlags Flags, see RTR3INIT_FLAGS_XXX.
104 */
105RTR3DECL(int) RTR3InitExeNoArguments(uint32_t fFlags);
106
107/**
108 * Initializes the runtime library.
109 *
110 * @returns iprt status code.
111 * @param cArgs Pointer to the argument count.
112 * @param ppapszArgs Pointer to the argument vector pointer.
113 * @param fFlags Flags, see RTR3INIT_FLAGS_XXX.
114 */
115RTR3DECL(int) RTR3InitExe(int cArgs, char ***ppapszArgs, uint32_t fFlags);
116
117/**
118 * Initializes the runtime library.
119 *
120 * @returns iprt status code.
121 * @param fFlags Flags, see RTR3INIT_FLAGS_XXX.
122 */
123RTR3DECL(int) RTR3InitDll(uint32_t fFlags);
124
125/**
126 * Initializes the runtime library and possibly also SUPLib too.
127 *
128 * Avoid this interface, it's not considered stable.
129 *
130 * @returns IPRT status code.
131 * @param iVersion The interface version. Must be 0 atm.
132 * @param fFlags Flags, see RTR3INIT_FLAGS_XXX.
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.
138 */
139RTR3DECL(int) RTR3InitEx(uint32_t iVersion, uint32_t fFlags, int cArgs, char ***ppapszArgs, const char *pszProgramPath);
140
141/**
142 * Terminates the runtime library.
143 */
144RTR3DECL(void) RTR3Term(void);
145
146/**
147 * Is IPRT succesfully initialized?
148 *
149 * @returns true/false.
150 */
151RTR3DECL(bool) RTR3InitIsInitialized(void);
152
153/**
154 * Are we running in unobtrusive mode?
155 * @returns true/false.
156 */
157RTR3DECL(bool) RTR3InitIsUnobtrusive(void);
158
159#endif /* IN_RING3 */
160
161
162#ifdef IN_RING0
163/**
164 * Initializes the ring-0 driver runtime library.
165 *
166 * @returns iprt status code.
167 * @param fReserved Flags reserved for the future.
168 */
169RTR0DECL(int) RTR0Init(unsigned fReserved);
170
171/**
172 * Terminates the ring-0 driver runtime library.
173 */
174RTR0DECL(void) RTR0Term(void);
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 */
182RTR0DECL(void) RTR0TermForced(void);
183#endif
184
185#ifdef IN_RC
186/**
187 * Initializes the raw-mode context runtime library.
188 *
189 * @returns iprt status code.
190 *
191 * @param u64ProgramStartNanoTS The startup timestamp.
192 */
193RTRCDECL(int) RTRCInit(uint64_t u64ProgramStartNanoTS);
194
195/**
196 * Terminates the raw-mode context runtime library.
197 */
198RTRCDECL(void) RTRCTerm(void);
199#endif
200
201
202/**
203 * Termination reason.
204 */
205typedef 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 */
232typedef DECLCALLBACKTYPE(void, FNRTTERMCALLBACK,(RTTERMREASON enmReason, int32_t iStatus, void *pvUser));
233/** Pointer to an IPRT termination callback function. */
234typedef 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 */
258RTDECL(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 */
269RTDECL(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 */
281RTDECL(void) RTTermRunCallbacks(RTTERMREASON enmReason, int32_t iStatus);
282
283/** @} */
284
285/** @} */
286
287RT_C_DECLS_END
288
289
290#endif /* !IPRT_INCLUDED_initterm_h */
291
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette