errcore.h@ 76659

Last change on this file since 76659 was 76585, checked in by vboxsync, 6 years ago
*: scm --fix-header-guard-endif
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 31.3 KB

Line
1	/** @file
2	* IPRT - Status Codes Core.
3	*/
4
5	/*
6	* Copyright (C) 2006-2019 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_INCLUDED_errcore_h
27	#define IPRT_INCLUDED_errcore_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <iprt/cdefs.h>
33	#include <iprt/types.h>
34	#include <iprt/stdarg.h>
35
36
37	/** @defgroup grp_rt_err_core Status Codes Core
38	* @ingroup grp_rt_err
39	* @{
40	*/
41
42	/** @def RTERR_STRICT_RC
43	* Indicates that RT_SUCCESS_NP, RT_SUCCESS, RT_FAILURE_NP and RT_FAILURE should
44	* make type enforcing at compile time.
45	*
46	* @remarks Only define this for C++ code.
47	*/
48	#if defined(__cplusplus) \
49	&& !defined(RTERR_STRICT_RC) \
50	&& !defined(RTERR_NO_STRICT_RC) \
51	&& ( defined(DOXYGEN_RUNNING) \
52	\|\| defined(DEBUG) \
53	\|\| defined(RT_STRICT) )
54	# define RTERR_STRICT_RC 1
55	#endif
56
57
58	/** @def RT_SUCCESS
59	* Check for success. We expect success in normal cases, that is the code path depending on
60	* this check is normally taken. To prevent any prediction use RT_SUCCESS_NP instead.
61	*
62	* @returns true if rc indicates success.
63	* @returns false if rc indicates failure.
64	*
65	* @param rc The iprt status code to test.
66	*/
67	#define RT_SUCCESS(rc) ( RT_LIKELY(RT_SUCCESS_NP(rc)) )
68
69	/** @def RT_SUCCESS_NP
70	* Check for success. Don't predict the result.
71	*
72	* @returns true if rc indicates success.
73	* @returns false if rc indicates failure.
74	*
75	* @param rc The iprt status code to test.
76	*/
77	#ifdef RTERR_STRICT_RC
78	# define RT_SUCCESS_NP(rc) ( RTErrStrictType(rc).success() )
79	#else
80	# define RT_SUCCESS_NP(rc) ( (int)(rc) >= VINF_SUCCESS )
81	#endif
82
83	/** @def RT_FAILURE
84	* Check for failure, predicting unlikely.
85	*
86	* We don't expect in normal cases, that is the code path depending on this
87	* check is normally NOT taken. To prevent any prediction use RT_FAILURE_NP
88	* instead.
89	*
90	* @returns true if rc indicates failure.
91	* @returns false if rc indicates success.
92	*
93	* @param rc The iprt status code to test.
94	*
95	* @remarks Please structure your code to use the RT_SUCCESS() macro instead of
96	* RT_FAILURE() where possible, as that gives us a better shot at good
97	* code with the windows compilers.
98	*/
99	#define RT_FAILURE(rc) ( RT_UNLIKELY(!RT_SUCCESS_NP(rc)) )
100
101	/** @def RT_FAILURE_NP
102	* Check for failure, no prediction.
103	*
104	* @returns true if rc indicates failure.
105	* @returns false if rc indicates success.
106	*
107	* @param rc The iprt status code to test.
108	*/
109	#define RT_FAILURE_NP(rc) ( !RT_SUCCESS_NP(rc) )
110
111
112	#ifdef __cplusplus
113	/**
114	* Strict type validation class.
115	*
116	* This is only really useful for type checking the arguments to RT_SUCCESS,
117	* RT_SUCCESS_NP, RT_FAILURE and RT_FAILURE_NP. The RTErrStrictType2
118	* constructor is for integration with external status code strictness regimes.
119	*/
120	class RTErrStrictType
121	{
122	protected:
123	int32_t m_rc;
124
125	public:
126	/**
127	* Constructor for interaction with external status code strictness regimes.
128	*
129	* This is a special constructor for helping external return code validator
130	* classes interact cleanly with RT_SUCCESS, RT_SUCCESS_NP, RT_FAILURE and
131	* RT_FAILURE_NP while barring automatic cast to integer.
132	*
133	* @param rcObj IPRT status code object from an automatic cast.
134	*/
135	RTErrStrictType(RTErrStrictType2 const rcObj)
136	: m_rc(rcObj.getValue())
137	{
138	}
139
140	/**
141	* Integer constructor used by RT_SUCCESS_NP.
142	*
143	* @param rc IPRT style status code.
144	*/
145	RTErrStrictType(int32_t rc)
146	: m_rc(rc)
147	{
148	}
149
150	#if 0 /** @todo figure where int32_t is long instead of int. */
151	/**
152	* Integer constructor used by RT_SUCCESS_NP.
153	*
154	* @param rc IPRT style status code.
155	*/
156	RTErrStrictType(signed int rc)
157	: m_rc(rc)
158	{
159	}
160	#endif
161
162	/**
163	* Test for success.
164	*/
165	bool success() const
166	{
167	return m_rc >= 0;
168	}
169
170	private:
171	/** @name Try ban a number of wrong types.
172	* @{ */
173	RTErrStrictType(uint8_t rc) : m_rc(-999) { NOREF(rc); }
174	RTErrStrictType(uint16_t rc) : m_rc(-999) { NOREF(rc); }
175	RTErrStrictType(uint32_t rc) : m_rc(-999) { NOREF(rc); }
176	RTErrStrictType(uint64_t rc) : m_rc(-999) { NOREF(rc); }
177	RTErrStrictType(int8_t rc) : m_rc(-999) { NOREF(rc); }
178	RTErrStrictType(int16_t rc) : m_rc(-999) { NOREF(rc); }
179	RTErrStrictType(int64_t rc) : m_rc(-999) { NOREF(rc); }
180	/** @todo fight long here - clashes with int32_t/int64_t on some platforms. */
181	/** @} */
182	};
183	#endif /* __cplusplus */
184
185
186	RT_C_DECLS_BEGIN
187
188	/**
189	* Converts a Darwin HRESULT error to an iprt status code.
190	*
191	* @returns iprt status code.
192	* @param iNativeCode HRESULT error code.
193	* @remark Darwin ring-3 only.
194	*/
195	RTDECL(int) RTErrConvertFromDarwinCOM(int32_t iNativeCode);
196
197	/**
198	* Converts a Darwin IOReturn error to an iprt status code.
199	*
200	* @returns iprt status code.
201	* @param iNativeCode IOReturn error code.
202	* @remark Darwin only.
203	*/
204	RTDECL(int) RTErrConvertFromDarwinIO(int iNativeCode);
205
206	/**
207	* Converts a Darwin kern_return_t error to an iprt status code.
208	*
209	* @returns iprt status code.
210	* @param iNativeCode kern_return_t error code.
211	* @remark Darwin only.
212	*/
213	RTDECL(int) RTErrConvertFromDarwinKern(int iNativeCode);
214
215	/**
216	* Converts a Darwin error to an iprt status code.
217	*
218	* This will consult RTErrConvertFromDarwinKern, RTErrConvertFromDarwinIO
219	* and RTErrConvertFromDarwinCOM in this order. The latter is ring-3 only as it
220	* doesn't apply elsewhere.
221	*
222	* @returns iprt status code.
223	* @param iNativeCode Darwin error code.
224	* @remarks Darwin only.
225	* @remarks This is recommended over RTErrConvertFromDarwinKern and RTErrConvertFromDarwinIO
226	* since these are really just subsets of the same error space.
227	*/
228	RTDECL(int) RTErrConvertFromDarwin(int iNativeCode);
229
230	/**
231	* Converts errno to iprt status code.
232	*
233	* @returns iprt status code.
234	* @param uNativeCode errno code.
235	*/
236	RTDECL(int) RTErrConvertFromErrno(unsigned uNativeCode);
237
238	/**
239	* Converts a L4 errno to a iprt status code.
240	*
241	* @returns iprt status code.
242	* @param uNativeCode l4 errno.
243	* @remark L4 only.
244	*/
245	RTDECL(int) RTErrConvertFromL4Errno(unsigned uNativeCode);
246
247	/**
248	* Converts NT status code to iprt status code.
249	*
250	* Needless to say, this is only available on NT and winXX targets.
251	*
252	* @returns iprt status code.
253	* @param lNativeCode NT status code.
254	* @remark Windows only.
255	*/
256	RTDECL(int) RTErrConvertFromNtStatus(long lNativeCode);
257
258	/**
259	* Converts OS/2 error code to iprt status code.
260	*
261	* @returns iprt status code.
262	* @param uNativeCode OS/2 error code.
263	* @remark OS/2 only.
264	*/
265	RTDECL(int) RTErrConvertFromOS2(unsigned uNativeCode);
266
267	/**
268	* Converts Win32 error code to iprt status code.
269	*
270	* @returns iprt status code.
271	* @param uNativeCode Win32 error code.
272	* @remark Windows only.
273	*/
274	RTDECL(int) RTErrConvertFromWin32(unsigned uNativeCode);
275
276	/**
277	* Converts an iprt status code to a errno status code.
278	*
279	* @returns errno status code.
280	* @param iErr iprt status code.
281	*/
282	RTDECL(int) RTErrConvertToErrno(int iErr);
283
284	#ifdef IN_RING3
285
286	/**
287	* iprt status code message.
288	*/
289	typedef struct RTSTATUSMSG
290	{
291	/** Pointer to the short message string. */
292	const char *pszMsgShort;
293	/** Pointer to the full message string. */
294	const char *pszMsgFull;
295	/** Pointer to the define string. */
296	const char *pszDefine;
297	/** Status code number. */
298	int iCode;
299	} RTSTATUSMSG;
300	/** Pointer to iprt status code message. */
301	typedef RTSTATUSMSG *PRTSTATUSMSG;
302	/** Pointer to const iprt status code message. */
303	typedef const RTSTATUSMSG *PCRTSTATUSMSG;
304
305	/**
306	* Get the message structure corresponding to a given iprt status code.
307	*
308	* @returns Pointer to read-only message description.
309	* @param rc The status code.
310	*/
311	RTDECL(PCRTSTATUSMSG) RTErrGet(int rc);
312
313	/**
314	* Get the define corresponding to a given iprt status code.
315	*
316	* @returns Pointer to read-only string with the \#define identifier.
317	* @param rc The status code.
318	*/
319	#define RTErrGetDefine(rc) (RTErrGet(rc)->pszDefine)
320
321	/**
322	* Get the short description corresponding to a given iprt status code.
323	*
324	* @returns Pointer to read-only string with the description.
325	* @param rc The status code.
326	*/
327	#define RTErrGetShort(rc) (RTErrGet(rc)->pszMsgShort)
328
329	/**
330	* Get the full description corresponding to a given iprt status code.
331	*
332	* @returns Pointer to read-only string with the description.
333	* @param rc The status code.
334	*/
335	#define RTErrGetFull(rc) (RTErrGet(rc)->pszMsgFull)
336
337	#ifdef RT_OS_WINDOWS
338	/**
339	* Windows error code message.
340	*/
341	typedef struct RTWINERRMSG
342	{
343	/** Pointer to the full message string. */
344	const char *pszMsgFull;
345	/** Pointer to the define string. */
346	const char *pszDefine;
347	/** Error code number. */
348	long iCode;
349	} RTWINERRMSG;
350	/** Pointer to Windows error code message. */
351	typedef RTWINERRMSG *PRTWINERRMSG;
352	/** Pointer to const Windows error code message. */
353	typedef const RTWINERRMSG *PCRTWINERRMSG;
354
355	/**
356	* Get the message structure corresponding to a given Windows error code.
357	*
358	* @returns Pointer to read-only message description.
359	* @param rc The status code.
360	*/
361	RTDECL(PCRTWINERRMSG) RTErrWinGet(long rc);
362
363	/** On windows COM errors are part of the Windows error database. */
364	typedef RTWINERRMSG RTCOMERRMSG;
365
366	#else /* !RT_OS_WINDOWS */
367
368	/**
369	* COM/XPCOM error code message.
370	*/
371	typedef struct RTCOMERRMSG
372	{
373	/** Pointer to the full message string. */
374	const char *pszMsgFull;
375	/** Pointer to the define string. */
376	const char *pszDefine;
377	/** Error code number. */
378	uint32_t iCode;
379	} RTCOMERRMSG;
380	#endif /* !RT_OS_WINDOWS */
381	/** Pointer to a XPCOM/COM error code message. */
382	typedef RTCOMERRMSG *PRTCOMERRMSG;
383	/** Pointer to const a XPCOM/COM error code message. */
384	typedef const RTCOMERRMSG *PCRTCOMERRMSG;
385
386	/**
387	* Get the message structure corresponding to a given COM/XPCOM error code.
388	*
389	* @returns Pointer to read-only message description.
390	* @param rc The status code.
391	*/
392	RTDECL(PCRTCOMERRMSG) RTErrCOMGet(uint32_t rc);
393
394	#endif /* IN_RING3 */
395
396	/** @defgroup RTERRINFO_FLAGS_XXX RTERRINFO::fFlags
397	* @{ */
398	/** Custom structure (the default). */
399	#define RTERRINFO_FLAGS_T_CUSTOM UINT32_C(0)
400	/** Static structure (RTERRINFOSTATIC). */
401	#define RTERRINFO_FLAGS_T_STATIC UINT32_C(1)
402	/** Allocated structure (RTErrInfoAlloc). */
403	#define RTERRINFO_FLAGS_T_ALLOC UINT32_C(2)
404	/** Reserved type. */
405	#define RTERRINFO_FLAGS_T_RESERVED UINT32_C(3)
406	/** Type mask. */
407	#define RTERRINFO_FLAGS_T_MASK UINT32_C(3)
408	/** Error info is set. */
409	#define RTERRINFO_FLAGS_SET RT_BIT_32(2)
410	/** Fixed flags (magic). */
411	#define RTERRINFO_FLAGS_MAGIC UINT32_C(0xbabe0000)
412	/** The bit mask for the magic value. */
413	#define RTERRINFO_FLAGS_MAGIC_MASK UINT32_C(0xffff0000)
414	/** @} */
415
416	/**
417	* Initializes an error info structure.
418	*
419	* @returns @a pErrInfo.
420	* @param pErrInfo The error info structure to init.
421	* @param pszMsg The message buffer. Must be at least one byte.
422	* @param cbMsg The size of the message buffer.
423	*/
424	DECLINLINE(PRTERRINFO) RTErrInfoInit(PRTERRINFO pErrInfo, char *pszMsg, size_t cbMsg)
425	{
426	*pszMsg = '\0';
427
428	pErrInfo->fFlags = RTERRINFO_FLAGS_T_CUSTOM \| RTERRINFO_FLAGS_MAGIC;
429	pErrInfo->rc = /VINF_SUCCESS/ 0;
430	pErrInfo->pszMsg = pszMsg;
431	pErrInfo->cbMsg = cbMsg;
432	pErrInfo->apvReserved[0] = NULL;
433	pErrInfo->apvReserved[1] = NULL;
434
435	return pErrInfo;
436	}
437
438	/**
439	* Initialize a static error info structure.
440	*
441	* @returns Pointer to the core error info structure.
442	* @param pStaticErrInfo The static error info structure to init.
443	*/
444	DECLINLINE(PRTERRINFO) RTErrInfoInitStatic(PRTERRINFOSTATIC pStaticErrInfo)
445	{
446	RTErrInfoInit(&pStaticErrInfo->Core, pStaticErrInfo->szMsg, sizeof(pStaticErrInfo->szMsg));
447	pStaticErrInfo->Core.fFlags = RTERRINFO_FLAGS_T_STATIC \| RTERRINFO_FLAGS_MAGIC;
448	return &pStaticErrInfo->Core;
449	}
450
451	/**
452	* Allocates a error info structure with a buffer at least the given size.
453	*
454	* @returns Pointer to an error info structure on success, NULL on failure.
455	*
456	* @param cbMsg The minimum message buffer size. Use 0 to get
457	* the default buffer size.
458	*/
459	RTDECL(PRTERRINFO) RTErrInfoAlloc(size_t cbMsg);
460
461	/**
462	* Same as RTErrInfoAlloc, except that an IPRT status code is returned.
463	*
464	* @returns IPRT status code.
465	*
466	* @param cbMsg The minimum message buffer size. Use 0 to get
467	* the default buffer size.
468	* @param ppErrInfo Where to store the pointer to the allocated
469	* error info structure on success. This is
470	* always set to NULL.
471	*/
472	RTDECL(int) RTErrInfoAllocEx(size_t cbMsg, PRTERRINFO *ppErrInfo);
473
474	/**
475	* Frees an error info structure allocated by RTErrInfoAlloc or
476	* RTErrInfoAllocEx.
477	*
478	* @param pErrInfo The error info structure.
479	*/
480	RTDECL(void) RTErrInfoFree(PRTERRINFO pErrInfo);
481
482	/**
483	* Fills in the error info details.
484	*
485	* @returns @a rc.
486	*
487	* @param pErrInfo The error info structure to fill in.
488	* @param rc The status code to return.
489	* @param pszMsg The error message string.
490	*/
491	RTDECL(int) RTErrInfoSet(PRTERRINFO pErrInfo, int rc, const char *pszMsg);
492
493	/**
494	* Fills in the error info details, with a sprintf style message.
495	*
496	* @returns @a rc.
497	*
498	* @param pErrInfo The error info structure to fill in.
499	* @param rc The status code to return.
500	* @param pszFormat The format string.
501	* @param ... The format arguments.
502	*/
503	RTDECL(int) RTErrInfoSetF(PRTERRINFO pErrInfo, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
504
505	/**
506	* Fills in the error info details, with a vsprintf style message.
507	*
508	* @returns @a rc.
509	*
510	* @param pErrInfo The error info structure to fill in.
511	* @param rc The status code to return.
512	* @param pszFormat The format string.
513	* @param va The format arguments.
514	*/
515	RTDECL(int) RTErrInfoSetV(PRTERRINFO pErrInfo, int rc, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
516
517	/**
518	* Adds more error info details.
519	*
520	* @returns @a rc.
521	*
522	* @param pErrInfo The error info structure to fill in.
523	* @param rc The status code to return.
524	* @param pszMsg The error message string to add.
525	*/
526	RTDECL(int) RTErrInfoAdd(PRTERRINFO pErrInfo, int rc, const char *pszMsg);
527
528	/**
529	* Adds more error info details, with a sprintf style message.
530	*
531	* @returns @a rc.
532	*
533	* @param pErrInfo The error info structure to fill in.
534	* @param rc The status code to return.
535	* @param pszFormat The format string to add.
536	* @param ... The format arguments.
537	*/
538	RTDECL(int) RTErrInfoAddF(PRTERRINFO pErrInfo, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
539
540	/**
541	* Adds more error info details, with a vsprintf style message.
542	*
543	* @returns @a rc.
544	*
545	* @param pErrInfo The error info structure to fill in.
546	* @param rc The status code to return.
547	* @param pszFormat The format string to add.
548	* @param va The format arguments.
549	*/
550	RTDECL(int) RTErrInfoAddV(PRTERRINFO pErrInfo, int rc, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
551
552	/** @name RTERRINFO_LOG_F_XXX
553	* @{ */
554	/** Both debug and release log. */
555	#define RTERRINFO_LOG_F_RELEASE RT_BIT_32(0)
556	/** @} */
557
558	/**
559	* Fills in the error info details.
560	*
561	* @returns @a rc.
562	*
563	* @param pErrInfo The error info structure to fill in.
564	* @param rc The status code to return.
565	* @param iLogGroup The logging group.
566	* @param fFlags RTERRINFO_LOG_F_XXX.
567	* @param pszMsg The error message string.
568	*/
569	RTDECL(int) RTErrInfoLogAndSet(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszMsg);
570
571	/**
572	* Fills in the error info details, with a sprintf style message.
573	*
574	* @returns @a rc.
575	*
576	* @param pErrInfo The error info structure to fill in.
577	* @param rc The status code to return.
578	* @param iLogGroup The logging group.
579	* @param fFlags RTERRINFO_LOG_F_XXX.
580	* @param pszFormat The format string.
581	* @param ... The format arguments.
582	*/
583	RTDECL(int) RTErrInfoLogAndSetF(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
584
585	/**
586	* Fills in the error info details, with a vsprintf style message.
587	*
588	* @returns @a rc.
589	*
590	* @param pErrInfo The error info structure to fill in.
591	* @param rc The status code to return.
592	* @param iLogGroup The logging group.
593	* @param fFlags RTERRINFO_LOG_F_XXX.
594	* @param pszFormat The format string.
595	* @param va The format arguments.
596	*/
597	RTDECL(int) RTErrInfoLogAndSetV(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(5, 0);
598
599	/**
600	* Adds more error info details.
601	*
602	* @returns @a rc.
603	*
604	* @param pErrInfo The error info structure to fill in.
605	* @param rc The status code to return.
606	* @param iLogGroup The logging group.
607	* @param fFlags RTERRINFO_LOG_F_XXX.
608	* @param pszMsg The error message string to add.
609	*/
610	RTDECL(int) RTErrInfoLogAndAdd(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszMsg);
611
612	/**
613	* Adds more error info details, with a sprintf style message.
614	*
615	* @returns @a rc.
616	*
617	* @param pErrInfo The error info structure to fill in.
618	* @param rc The status code to return.
619	* @param iLogGroup The logging group.
620	* @param fFlags RTERRINFO_LOG_F_XXX.
621	* @param pszFormat The format string to add.
622	* @param ... The format arguments.
623	*/
624	RTDECL(int) RTErrInfoLogAndAddF(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
625
626	/**
627	* Adds more error info details, with a vsprintf style message.
628	*
629	* @returns @a rc.
630	*
631	* @param pErrInfo The error info structure to fill in.
632	* @param rc The status code to return.
633	* @param iLogGroup The logging group.
634	* @param fFlags RTERRINFO_LOG_F_XXX.
635	* @param pszFormat The format string to add.
636	* @param va The format arguments.
637	*/
638	RTDECL(int) RTErrInfoLogAndAddV(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(5, 0);
639
640	/** @name Macros wrapping the RTErrInfoLog* functions.
641	* @{ */
642	#ifndef LOG_DISABLED
643	# define RTERRINFO_LOG_SET( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoLogAndSet( a_pErrInfo, a_rc, LOG_GROUP, 0, a_pszMsg)
644	# define RTERRINFO_LOG_SET_V(a_pErrInfo, a_rc, a_pszMsg, a_va) RTErrInfoLogAndSetV(a_pErrInfo, a_rc, LOG_GROUP, 0, a_pszMsg, a_va)
645	# define RTERRINFO_LOG_ADD( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoLogAndAdd( a_pErrInfo, a_rc, LOG_GROUP, 0, a_pszMsg)
646	# define RTERRINFO_LOG_ADD_V(a_pErrInfo, a_rc, a_pszMsg, a_va) RTErrInfoLogAndAddV(a_pErrInfo, a_rc, LOG_GROUP, 0, a_pszMsg, a_va)
647	# ifdef RT_COMPILER_SUPPORTS_VA_ARGS
648	# define RTERRINFO_LOG_ADD_F(a_pErrInfo, a_rc, ...) RTErrInfoLogAndAddF(a_pErrInfo, a_rc, LOG_GROUP, 0, __VA_ARGS__)
649	# define RTERRINFO_LOG_SET_F(a_pErrInfo, a_rc, ...) RTErrInfoLogAndSetF(a_pErrInfo, a_rc, LOG_GROUP, 0, __VA_ARGS__)
650	# else
651	# define RTERRINFO_LOG_ADD_F RTErrInfoSetF
652	# define RTERRINFO_LOG_SET_F RTErrInfoAddF
653	# endif
654	#else
655	# define RTERRINFO_LOG_SET( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoSet( a_pErrInfo, a_rc, a_pszMsg)
656	# define RTERRINFO_LOG_SET_V(a_pErrInfo, a_rc, a_pszMsg, a_va) RTErrInfoSetV(a_pErrInfo, a_rc, a_pszMsg, a_va)
657	# define RTERRINFO_LOG_ADD( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoAdd( a_pErrInfo, a_rc, a_pszMsg)
658	# define RTERRINFO_LOG_ADD_V(a_pErrInfo, a_rc, a_pszMsg, a_va) RTErrInfoAddV(a_pErrInfo, a_rc, a_pszMsg, a_va)
659	# define RTERRINFO_LOG_ADD_F RTErrInfoSetF
660	# define RTERRINFO_LOG_SET_F RTErrInfoAddF
661	#endif
662
663	#define RTERRINFO_LOG_REL_SET( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoLogAndSet( a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, a_pszMsg)
664	#define RTERRINFO_LOG_REL_SET_V(a_pErrInfo, a_rc, a_pszMsg, a_va) RTErrInfoLogAndSetV(a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, a_pszMsg, a_va)
665	#define RTERRINFO_LOG_REL_ADD( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoLogAndAdd( a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, a_pszMsg)
666	#define RTERRINFO_LOG_REL_ADD_V(a_pErrInfo, a_rc, a_pszMsg, a_va) RTErrInfoLogAndAddV(a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, a_pszMsg, a_va)
667	#ifdef RT_COMPILER_SUPPORTS_VA_ARGS
668	# define RTERRINFO_LOG_REL_ADD_F(a_pErrInfo, a_rc, ...) RTErrInfoLogAndAddF(a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, __VA_ARGS__)
669	# define RTERRINFO_LOG_REL_SET_F(a_pErrInfo, a_rc, ...) RTErrInfoLogAndSetF(a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, __VA_ARGS__)
670	#else
671	# define RTERRINFO_LOG_REL_ADD_F RTErrInfoSetF
672	# define RTERRINFO_LOG_REL_SET_F RTErrInfoAddF
673	#endif
674	/** @} */
675
676
677	/**
678	* Checks if the error info is set.
679	*
680	* @returns true if set, false if not.
681	* @param pErrInfo The error info structure. NULL is OK.
682	*/
683	DECLINLINE(bool) RTErrInfoIsSet(PCRTERRINFO pErrInfo)
684	{
685	if (!pErrInfo)
686	return false;
687	return (pErrInfo->fFlags & (RTERRINFO_FLAGS_MAGIC_MASK \| RTERRINFO_FLAGS_SET))
688	== (RTERRINFO_FLAGS_MAGIC \| RTERRINFO_FLAGS_SET);
689	}
690
691	/**
692	* Clears the error info structure.
693	*
694	* @param pErrInfo The error info structure. NULL is OK.
695	*/
696	DECLINLINE(void) RTErrInfoClear(PRTERRINFO pErrInfo)
697	{
698	if (pErrInfo)
699	{
700	pErrInfo->fFlags &= ~RTERRINFO_FLAGS_SET;
701	pErrInfo->rc = /VINF_SUCCESS/0;
702	*pErrInfo->pszMsg = '\0';
703	}
704	}
705
706	/**
707	* Storage for error variables.
708	*
709	* @remarks Do NOT touch the members! They are platform specific and what's
710	* where may change at any time!
711	*/
712	typedef union RTERRVARS
713	{
714	int8_t ai8Vars[32];
715	int16_t ai16Vars[16];
716	int32_t ai32Vars[8];
717	int64_t ai64Vars[4];
718	} RTERRVARS;
719	/** Pointer to an error variable storage union. */
720	typedef RTERRVARS *PRTERRVARS;
721	/** Pointer to a const error variable storage union. */
722	typedef RTERRVARS const *PCRTERRVARS;
723
724	/**
725	* Saves the error variables.
726	*
727	* @returns @a pVars.
728	* @param pVars The variable storage union.
729	*/
730	RTDECL(PRTERRVARS) RTErrVarsSave(PRTERRVARS pVars);
731
732	/**
733	* Restores the error variables.
734	*
735	* @param pVars The variable storage union.
736	*/
737	RTDECL(void) RTErrVarsRestore(PCRTERRVARS pVars);
738
739	/**
740	* Checks if the first variable set equals the second.
741	*
742	* @returns true if they are equal, false if not.
743	* @param pVars1 The first variable storage union.
744	* @param pVars2 The second variable storage union.
745	*/
746	RTDECL(bool) RTErrVarsAreEqual(PCRTERRVARS pVars1, PCRTERRVARS pVars2);
747
748	/**
749	* Checks if the (live) error variables have changed since we saved them.
750	*
751	* @returns @c true if they have changed, @c false if not.
752	* @param pVars The saved variables to compare the current state
753	* against.
754	*/
755	RTDECL(bool) RTErrVarsHaveChanged(PCRTERRVARS pVars);
756
757	RT_C_DECLS_END
758
759
760	/* We duplicate a handful of very commonly used status codes from err.h here.
761	Needless to say, these needs to match the err.h definition exactly: */
762
763	/** Success.
764	* @ingroup grp_rt_err */
765	#define VINF_SUCCESS 0
766
767	/** General failure - DON'T USE THIS!!!
768	* @ingroup grp_rt_err */
769	#define VERR_GENERAL_FAILURE (-1)
770	/** Invalid parameter.
771	* @ingroup grp_rt_err */
772	#define VERR_INVALID_PARAMETER (-2)
773	/** Invalid parameter.
774	* @ingroup grp_rt_err */
775	#define VWRN_INVALID_PARAMETER 2
776	/** Invalid magic or cookie.
777	* @ingroup grp_rt_err */
778	#define VERR_INVALID_MAGIC (-3)
779	/** Invalid magic or cookie.
780	* @ingroup grp_rt_err */
781	#define VWRN_INVALID_MAGIC 3
782	/** Invalid loader handle.
783	* @ingroup grp_rt_err */
784	#define VERR_INVALID_HANDLE (-4)
785	/** Invalid loader handle.
786	* @ingroup grp_rt_err */
787	#define VWRN_INVALID_HANDLE 4
788	/** Invalid memory pointer. */
789	#define VERR_INVALID_POINTER (-6)
790	/** Memory allocation failed.
791	* @ingroup grp_rt_err */
792	#define VERR_NO_MEMORY (-8)
793	/** Permission denied.
794	* @ingroup grp_rt_err */
795	#define VERR_PERMISSION_DENIED (-10)
796	/** Permission denied.
797	* @ingroup grp_rt_err */
798	#define VINF_PERMISSION_DENIED 10
799	/** Version mismatch.
800	* @ingroup grp_rt_err */
801	#define VERR_VERSION_MISMATCH (-11)
802	/** The request function is not implemented.
803	* @ingroup grp_rt_err */
804	#define VERR_NOT_IMPLEMENTED (-12)
805	/** Invalid flags was given.
806	* @ingroup grp_rt_err */
807	#define VERR_INVALID_FLAGS (-13)
808	/** Incorrect call order.
809	* @ingroup grp_rt_err */
810	#define VERR_WRONG_ORDER (-22)
811	/** Invalid function.
812	* @ingroup grp_rt_err */
813	#define VERR_INVALID_FUNCTION (-36)
814	/** Not supported.
815	* @ingroup grp_rt_err */
816	#define VERR_NOT_SUPPORTED (-37)
817	/** Not supported.
818	* @ingroup grp_rt_err */
819	#define VINF_NOT_SUPPORTED 37
820	/** Access denied.
821	* @ingroup grp_rt_err */
822	#define VERR_ACCESS_DENIED (-38)
823	/** Call interrupted.
824	* @ingroup grp_rt_err */
825	#define VERR_INTERRUPTED (-39)
826	/** Call interrupted.
827	* @ingroup grp_rt_err */
828	#define VINF_INTERRUPTED 39
829	/** Timeout.
830	* @ingroup grp_rt_err */
831	#define VERR_TIMEOUT (-40)
832	/** Timeout.
833	* @ingroup grp_rt_err */
834	#define VINF_TIMEOUT 40
835	/** Buffer too small to save result.
836	* @ingroup grp_rt_err */
837	#define VERR_BUFFER_OVERFLOW (-41)
838	/** Buffer too small to save result.
839	* @ingroup grp_rt_err */
840	#define VINF_BUFFER_OVERFLOW 41
841	/** Data size overflow.
842	* @ingroup grp_rt_err */
843	#define VERR_TOO_MUCH_DATA (-42)
844	/** Retry the operation.
845	* @ingroup grp_rt_err */
846	#define VERR_TRY_AGAIN (-52)
847	/** Retry the operation.
848	* @ingroup grp_rt_err */
849	#define VINF_TRY_AGAIN 52
850	/** Generic parse error.
851	* @ingroup grp_rt_err */
852	#define VERR_PARSE_ERROR (-53)
853	/** Value out of range.
854	* @ingroup grp_rt_err */
855	#define VERR_OUT_OF_RANGE (-54)
856	/** A numeric conversion encountered a value which was too big for the target.
857	* @ingroup grp_rt_err */
858	#define VERR_NUMBER_TOO_BIG (-55)
859	/** A numeric conversion encountered a value which was too big for the target.
860	* @ingroup grp_rt_err */
861	#define VWRN_NUMBER_TOO_BIG 55
862	/** The operation was cancelled by the user (copy) or another thread (local ipc).
863	* @ingroup grp_rt_err */
864	#define VERR_CANCELLED (-70)
865	/** Trailing characters.
866	* @ingroup grp_rt_err */
867	#define VERR_TRAILING_CHARS (-76)
868	/** Trailing characters.
869	* @ingroup grp_rt_err */
870	#define VWRN_TRAILING_CHARS 76
871	/** Trailing spaces.
872	* @ingroup grp_rt_err */
873	#define VERR_TRAILING_SPACES (-77)
874	/** Trailing spaces.
875	* @ingroup grp_rt_err */
876	#define VWRN_TRAILING_SPACES 77
877	/** Generic not found error.
878	* @ingroup grp_rt_err */
879	#define VERR_NOT_FOUND (-78)
880	/** Generic not found warning.
881	* @ingroup grp_rt_err */
882	#define VWRN_NOT_FOUND 78
883	/** Generic invalid state error.
884	* @ingroup grp_rt_err */
885	#define VERR_INVALID_STATE (-79)
886	/** Generic invalid state warning.
887	* @ingroup grp_rt_err */
888	#define VWRN_INVALID_STATE 79
889	/** Generic out of resources error.
890	* @ingroup grp_rt_err */
891	#define VERR_OUT_OF_RESOURCES (-80)
892	/** Generic out of resources warning.
893	* @ingroup grp_rt_err */
894	#define VWRN_OUT_OF_RESOURCES 80
895	/** End of string.
896	* @ingroup grp_rt_err */
897	#define VERR_END_OF_STRING (-83)
898	/** Return instigated by a callback or similar.
899	* @ingroup grp_rt_err */
900	#define VERR_CALLBACK_RETURN (-88)
901	/** Return instigated by a callback or similar.
902	* @ingroup grp_rt_err */
903	#define VINF_CALLBACK_RETURN 88
904	/** Duplicate something.
905	* @ingroup grp_rt_err */
906	#define VERR_DUPLICATE (-98)
907	/** Something is missing.
908	* @ingroup grp_rt_err */
909	#define VERR_MISSING (-99)
910	/** Buffer underflow.
911	* @ingroup grp_rt_err */
912	#define VERR_BUFFER_UNDERFLOW (-22401)
913	/** Buffer underflow.
914	* @ingroup grp_rt_err */
915	#define VINF_BUFFER_UNDERFLOW 22401
916	/** Something is not available or not working properly.
917	* @ingroup grp_rt_err */
918	#define VERR_NOT_AVAILABLE (-22403)
919	/** Mismatch.
920	* @ingroup grp_rt_err */
921	#define VERR_MISMATCH (-22408)
922	/** Wrong type.
923	* @ingroup grp_rt_err */
924	#define VERR_WRONG_TYPE (-22409)
925	/** Wrong type.
926	* @ingroup grp_rt_err */
927	#define VWRN_WRONG_TYPE (22409)
928	/** Wrong parameter count.
929	* @ingroup grp_rt_err */
930	#define VERR_WRONG_PARAMETER_COUNT (-22415)
931	/** Wrong parameter type.
932	* @ingroup grp_rt_err */
933	#define VERR_WRONG_PARAMETER_TYPE (-22416)
934	/** Invalid client ID.
935	* @ingroup grp_rt_err */
936	#define VERR_INVALID_CLIENT_ID (-22417)
937	/** Invalid session ID.
938	* @ingroup grp_rt_err */
939	#define VERR_INVALID_SESSION_ID (-22418)
940	/** Incompatible configuration requested.
941	* @ingroup grp_rt_err */
942	#define VERR_INCOMPATIBLE_CONFIG (-22420)
943	/** Internal error - this should never happen.
944	* @ingroup grp_rt_err */
945	#define VERR_INTERNAL_ERROR (-225)
946	/** RTGetOpt: Not an option.
947	* @ingroup grp_rt_err */
948	#define VINF_GETOPT_NOT_OPTION 828
949	/** RTGetOpt: Command line option not recognized.
950	* @ingroup grp_rt_err */
951	#define VERR_GETOPT_UNKNOWN_OPTION (-825)
952
953	/** @} */
954
955	#endif /* !IPRT_INCLUDED_errcore_h */
956

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/errcore.h@ 76659

Download in other formats: