VirtualBox

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

Last change on this file since 27345 was 26226, checked in by vboxsync, 15 years ago

s/RTGCDECL/RTGCDECL/g

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.7 KB
Line 
1/** @file
2 * IPRT - Runtime Init/Term.
3 */
4
5/*
6 * Copyright (C) 2006-2009 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_initterm_h
31#define ___iprt_initterm_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35
36RT_C_DECLS_BEGIN
37
38/** @defgroup grp_rt IPRT APIs
39 * @{
40 */
41
42/** @defgroup grp_rt_initterm Init / Term
43 * @{
44 */
45
46#ifdef IN_RING3
47/**
48 * Initializes the runtime library.
49 *
50 * @returns iprt status code.
51 */
52RTR3DECL(int) RTR3Init(void);
53
54
55/**
56 * Initializes the runtime library and try initialize SUPLib too.
57 *
58 * @returns IPRT status code.
59 *
60 * @remarks Failure to initialize SUPLib is ignored.
61 */
62RTR3DECL(int) RTR3InitAndSUPLib(void);
63
64/**
65 * Initializes the runtime library passing it the program path.
66 *
67 * @returns IPRT status code.
68 * @param pszProgramPath The path to the program file.
69 */
70RTR3DECL(int) RTR3InitWithProgramPath(const char *pszProgramPath);
71
72/**
73 * Initializes the runtime library passing it the program path,
74 * and try initialize SUPLib too (failures ignored).
75 *
76 * @returns IPRT status code.
77 * @param pszProgramPath The path to the program file.
78 *
79 * @remarks Failure to initialize SUPLib is ignored.
80 */
81RTR3DECL(int) RTR3InitAndSUPLibWithProgramPath(const char *pszProgramPath);
82
83/**
84 * Initializes the runtime library and possibly also SUPLib too.
85 *
86 * Avoid this interface, it's not considered stable.
87 *
88 * @returns IPRT status code.
89 * @param iVersion The interface version. Must be 0 atm.
90 * @param pszProgramPath The program path. Pass NULL if we're to figure it out ourselves.
91 * @param fInitSUPLib Whether to initialize the support library or not.
92 */
93RTR3DECL(int) RTR3InitEx(uint32_t iVersion, const char *pszProgramPath, bool fInitSUPLib);
94
95/**
96 * Terminates the runtime library.
97 */
98RTR3DECL(void) RTR3Term(void);
99
100#endif /* IN_RING3 */
101
102
103#ifdef IN_RING0
104/**
105 * Initalizes the ring-0 driver runtime library.
106 *
107 * @returns iprt status code.
108 * @param fReserved Flags reserved for the future.
109 */
110RTR0DECL(int) RTR0Init(unsigned fReserved);
111
112/**
113 * Terminates the ring-0 driver runtime library.
114 */
115RTR0DECL(void) RTR0Term(void);
116
117/**
118 * Forcibily terminates the ring-0 driver runtime library.
119 *
120 * This should be used when statically linking the IPRT. Module using dynamic
121 * linking shall use RTR0Term. If you're not sure, use RTR0Term!
122 */
123RTR0DECL(void) RTR0TermForced(void);
124#endif
125
126#ifdef IN_RC
127/**
128 * Initializes the raw-mode context runtime library.
129 *
130 * @returns iprt status code.
131 *
132 * @param u64ProgramStartNanoTS The startup timestamp.
133 */
134RTRCDECL(int) RTRCInit(uint64_t u64ProgramStartNanoTS);
135
136/**
137 * Terminates the raw-mode context runtime library.
138 */
139RTRCDECL(void) RTRCTerm(void);
140#endif
141
142
143/**
144 * Termination reason.
145 */
146typedef enum RTTERMREASON
147{
148 /** Normal exit. iStatus contains the exit code. */
149 RTTERMREASON_EXIT = 1,
150 /** Any abnormal exit. iStatus is 0 and has no meaning. */
151 RTTERMREASON_ABEND,
152 /** Killed by a signal. The iStatus contains the signal number. */
153 RTTERMREASON_SIGNAL,
154 /** The IPRT module is being unloaded. iStatus is 0 and has no meaning. */
155 RTTERMREASON_UNLOAD
156} RTTERMREASON;
157
158/** Whether lazy clean up is Okay or not.
159 * When the process is exiting, it is a waste of time to for instance free heap
160 * memory or close open files. OTOH, when the runtime is unloaded from the
161 * process, it is important to release absolutely all resources to prevent
162 * resource leaks. */
163#define RTTERMREASON_IS_LAZY_CLEANUP_OK(enmReason) ((enmReason) != RTTERMREASON_UNLOAD)
164
165
166/**
167 * IPRT termination callback function.
168 *
169 * @param enmReason The cause of the termination.
170 * @param iStatus The meaning of this depends on enmReason.
171 * @param pvUser User argument passed to RTTermRegisterCallback.
172 */
173typedef DECLCALLBACK(void) FNRTTERMCALLBACK(RTTERMREASON enmReason, int32_t iStatus, void *pvUser);
174/** Pointer to an IPRT termination callback function. */
175typedef FNRTTERMCALLBACK *PFNRTTERMCALLBACK;
176
177
178/**
179 * Registers a termination callback.
180 *
181 * This is intended for performing clean up during IPRT termination. Frequently
182 * paired with lazy initialization thru RTOnce.
183 *
184 * The callbacks are called in LIFO order.
185 *
186 * @returns IPRT status code.
187 *
188 * @param pfnCallback The callback function.
189 * @param pvUser The user argument for the callback.
190 *
191 * @remarks May need to acquire a fast mutex or critical section, so use with
192 * some care in ring-0 context.
193 *
194 * @remarks Be very careful using this from code that may be unloaded before
195 * IPRT terminates. Unlike some atexit and on_exit implementations,
196 * IPRT will not automatically unregister callbacks when a module gets
197 * unloaded.
198 */
199RTDECL(int) RTTermRegisterCallback(PFNRTTERMCALLBACK pfnCallback, void *pvUser);
200
201/**
202 * Deregister a termination callback.
203 *
204 * @returns VINF_SUCCESS if found, VERR_NOT_FOUND if the callback/pvUser pair
205 * wasn't found.
206 *
207 * @param pfnCallback The callback function.
208 * @param pvUser The user argument for the callback.
209 */
210RTDECL(int) RTTermDeregisterCallback(PFNRTTERMCALLBACK pfnCallback, void *pvUser);
211
212/**
213 * Runs the termination callback queue.
214 *
215 * Normally called by an internal IPRT termination function, but may also be
216 * called by external code immediately prior to terminating IPRT if it is in a
217 * better position to state the termination reason and/or status.
218 *
219 * @param enmReason The reason why it's called.
220 * @param iStatus The associated exit status or signal number.
221 */
222RTDECL(void) RTTermRunCallbacks(RTTERMREASON enmReason, int32_t iStatus);
223
224/** @} */
225
226/** @} */
227
228RT_C_DECLS_END
229
230
231#endif
232
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