errcore.h@ 81372

Last change on this file since 81372 was 77110, checked in by vboxsync, 6 years ago
RTErrConvertFromErrno(): Convert the uNativeCode parameter from unsigned to int. errno is specified to be of type int and while it should only ever contain positive values RTErrConvertFromErrno() is also used inside the various kernel drivers where errno does not exist and the return code might be negative as well. The example here is ERESTART (-1) on FreeBSD causing a compile error with clang and this fix is cleaner IMO instead of casting ERSTART to unsigned.
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 iNativeCode errno code.
235	*/
236	RTDECL(int) RTErrConvertFromErrno(int iNativeCode);
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@ 81372

Download in other formats: