1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
|
/** @file
* IPRT - Runtime Init/Term.
*/
/*
* Copyright (C) 2006-2019 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* you can redistribute it and/or modify it under the terms of the GNU
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE 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.
*/
#ifndef IPRT_INCLUDED_initterm_h
#define IPRT_INCLUDED_initterm_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/cdefs.h>
#include <iprt/types.h>
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 (RTR3INIT_XXX).
* @{ */
/** Try initialize SUPLib. */
#define RTR3INIT_FLAGS_SUPLIB RT_BIT(0)
/** Initializing IPRT from a DLL. */
#define RTR3INIT_FLAGS_DLL RT_BIT(1)
/** We are sharing a process space, so we need to behave. */
#define RTR3INIT_FLAGS_UNOBTRUSIVE RT_BIT(2)
/** The caller ensures that the argument bector is UTF-8. */
#define RTR3INIT_FLAGS_UTF8_ARGV RT_BIT(3)
/** 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(4)
/** @} */
/** @name RTR3InitEx version
* @{ */
/** Version 1. */
#define RTR3INIT_VER_1 UINT32_C(1)
/** The current version. */
#define RTR3INIT_VER_CUR RTR3INIT_VER_1
/** @} */
/**
* Initializes the runtime library.
*
* @returns iprt status code.
* @param fFlags Flags, see RTR3INIT_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_XXX.
*/
RTR3DECL(int) RTR3InitExe(int cArgs, char ***ppapszArgs, uint32_t fFlags);
/**
* Initializes the runtime library.
*
* @returns iprt status code.
* @param fFlags Flags, see RTR3INIT_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_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 DECLCALLBACK(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 */
|
