errcore.h@ 95897

Last change on this file since 95897 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 31.7 KB

Line
1	/** @file
2	* IPRT - Status Codes Core.
3	*/
4
5	/*
6	* Copyright (C) 2006-2022 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) RT_NO_THROW_DEF
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) RT_NO_THROW_DEF
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 RT_NO_THROW_DEF
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) RT_NO_THROW_DEF : m_rc(-999) { NOREF(rc); }
174	RTErrStrictType(uint16_t rc) RT_NO_THROW_DEF : m_rc(-999) { NOREF(rc); }
175	RTErrStrictType(uint32_t rc) RT_NO_THROW_DEF : m_rc(-999) { NOREF(rc); }
176	RTErrStrictType(uint64_t rc) RT_NO_THROW_DEF : m_rc(-999) { NOREF(rc); }
177	RTErrStrictType(int8_t rc) RT_NO_THROW_DEF : m_rc(-999) { NOREF(rc); }
178	RTErrStrictType(int16_t rc) RT_NO_THROW_DEF : m_rc(-999) { NOREF(rc); }
179	RTErrStrictType(int64_t rc) RT_NO_THROW_DEF : 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
285	#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/string.h & iprt/log.h */
286	#define DECLARED_FNRTSTROUTPUT
287	/**
288	* Output callback.
289	*
290	* @returns number of bytes written.
291	* @param pvArg User argument.
292	* @param pachChars Pointer to an array of utf-8 characters.
293	* @param cbChars Number of bytes in the character array pointed to by pachChars.
294	*/
295	typedef DECLCALLBACKTYPE(size_t, FNRTSTROUTPUT,(void pvArg, const char pachChars, size_t cbChars));
296	/** Pointer to callback function. */
297	typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
298	#endif
299
300	#ifdef IN_RING3
301
302	RTDECL(bool) RTErrIsKnown(int rc);
303	RTDECL(ssize_t) RTErrQueryDefine(int rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
304	RTDECL(ssize_t) RTErrQueryMsgShort(int rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
305	RTDECL(ssize_t) RTErrQueryMsgFull(int rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
306
307	/** @name Error formatters used internally by RTStrFormat.
308	* @internal
309	* @{ */
310	RTDECL(size_t) RTErrFormatDefine( int rc, PFNRTSTROUTPUT pfnOutput, void pvArgOutput, char pszTmp, size_t cbTmp);
311	RTDECL(size_t) RTErrFormatMsgShort(int rc, PFNRTSTROUTPUT pfnOutput, void pvArgOutput, char pszTmp, size_t cbTmp);
312	RTDECL(size_t) RTErrFormatMsgFull( int rc, PFNRTSTROUTPUT pfnOutput, void pvArgOutput, char pszTmp, size_t cbTmp);
313	RTDECL(size_t) RTErrFormatMsgAll( int rc, PFNRTSTROUTPUT pfnOutput, void pvArgOutput, char pszTmp, size_t cbTmp);
314	/** @} */
315
316
317	# ifdef RT_OS_WINDOWS
318	/**
319	* Windows error code message.
320	*/
321	typedef struct RTWINERRMSG
322	{
323	/** Pointer to the full message string. */
324	const char *pszMsgFull;
325	/** Pointer to the define string. */
326	const char *pszDefine;
327	/** Error code number. */
328	long iCode;
329	} RTWINERRMSG;
330	/** Pointer to Windows error code message. */
331	typedef RTWINERRMSG *PRTWINERRMSG;
332	/** Pointer to const Windows error code message. */
333	typedef const RTWINERRMSG *PCRTWINERRMSG;
334
335	RTDECL(bool) RTErrWinIsKnown(long rc);
336	RTDECL(ssize_t) RTErrWinQueryDefine(long rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
337
338	/** @name Error formatters used internally by RTStrFormat.
339	* @internal
340	* @{ */
341	RTDECL(size_t) RTErrWinFormatDefine(long rc, PFNRTSTROUTPUT pfnOutput, void pvArgOutput, char pszTmp, size_t cbTmp);
342	RTDECL(size_t) RTErrWinFormatMsg( long rc, PFNRTSTROUTPUT pfnOutput, void pvArgOutput, char pszTmp, size_t cbTmp);
343	RTDECL(size_t) RTErrWinFormatMsgAll(long rc, PFNRTSTROUTPUT pfnOutput, void pvArgOutput, char pszTmp, size_t cbTmp);
344	/** @} */
345
346	# else /* !RT_OS_WINDOWS */
347
348	/**
349	* COM/XPCOM error code message.
350	*/
351	typedef struct RTCOMERRMSG
352	{
353	/** Pointer to the full message string. */
354	const char *pszMsgFull;
355	/** Pointer to the define string. */
356	const char *pszDefine;
357	/** Error code number. */
358	uint32_t iCode;
359	} RTCOMERRMSG;
360	/** Pointer to a XPCOM/COM error code message. */
361	typedef RTCOMERRMSG *PRTCOMERRMSG;
362	/** Pointer to const a XPCOM/COM error code message. */
363	typedef const RTCOMERRMSG *PCRTCOMERRMSG;
364
365	/**
366	* Get the message structure corresponding to a given COM/XPCOM error code.
367	*
368	* @returns Pointer to read-only message description.
369	* @param rc The status code.
370	*/
371	RTDECL(PCRTCOMERRMSG) RTErrCOMGet(uint32_t rc);
372
373	# endif /* !RT_OS_WINDOWS */
374
375	#endif /* IN_RING3 */
376
377	/** @defgroup RTERRINFO_FLAGS_XXX RTERRINFO::fFlags
378	* @{ */
379	/** Custom structure (the default). */
380	#define RTERRINFO_FLAGS_T_CUSTOM UINT32_C(0)
381	/** Static structure (RTERRINFOSTATIC). */
382	#define RTERRINFO_FLAGS_T_STATIC UINT32_C(1)
383	/** Allocated structure (RTErrInfoAlloc). */
384	#define RTERRINFO_FLAGS_T_ALLOC UINT32_C(2)
385	/** Reserved type. */
386	#define RTERRINFO_FLAGS_T_RESERVED UINT32_C(3)
387	/** Type mask. */
388	#define RTERRINFO_FLAGS_T_MASK UINT32_C(3)
389	/** Error info is set. */
390	#define RTERRINFO_FLAGS_SET RT_BIT_32(2)
391	/** Fixed flags (magic). */
392	#define RTERRINFO_FLAGS_MAGIC UINT32_C(0xbabe0000)
393	/** The bit mask for the magic value. */
394	#define RTERRINFO_FLAGS_MAGIC_MASK UINT32_C(0xffff0000)
395	/** @} */
396
397	/**
398	* Initializes an error info structure.
399	*
400	* @returns @a pErrInfo.
401	* @param pErrInfo The error info structure to init.
402	* @param pszMsg The message buffer. Must be at least one byte.
403	* @param cbMsg The size of the message buffer.
404	*/
405	DECLINLINE(PRTERRINFO) RTErrInfoInit(PRTERRINFO pErrInfo, char *pszMsg, size_t cbMsg)
406	{
407	*pszMsg = '\0';
408
409	pErrInfo->fFlags = RTERRINFO_FLAGS_T_CUSTOM \| RTERRINFO_FLAGS_MAGIC;
410	pErrInfo->rc = /VINF_SUCCESS/ 0;
411	pErrInfo->pszMsg = pszMsg;
412	pErrInfo->cbMsg = cbMsg;
413	pErrInfo->apvReserved[0] = NULL;
414	pErrInfo->apvReserved[1] = NULL;
415
416	return pErrInfo;
417	}
418
419	/**
420	* Initialize a static error info structure.
421	*
422	* @returns Pointer to the core error info structure.
423	* @param pStaticErrInfo The static error info structure to init.
424	*/
425	DECLINLINE(PRTERRINFO) RTErrInfoInitStatic(PRTERRINFOSTATIC pStaticErrInfo)
426	{
427	RTErrInfoInit(&pStaticErrInfo->Core, pStaticErrInfo->szMsg, sizeof(pStaticErrInfo->szMsg));
428	pStaticErrInfo->Core.fFlags = RTERRINFO_FLAGS_T_STATIC \| RTERRINFO_FLAGS_MAGIC;
429	return &pStaticErrInfo->Core;
430	}
431
432	/**
433	* Allocates a error info structure with a buffer at least the given size.
434	*
435	* @returns Pointer to an error info structure on success, NULL on failure.
436	*
437	* @param cbMsg The minimum message buffer size. Use 0 to get
438	* the default buffer size.
439	*/
440	RTDECL(PRTERRINFO) RTErrInfoAlloc(size_t cbMsg);
441
442	/**
443	* Same as RTErrInfoAlloc, except that an IPRT status code is returned.
444	*
445	* @returns IPRT status code.
446	*
447	* @param cbMsg The minimum message buffer size. Use 0 to get
448	* the default buffer size.
449	* @param ppErrInfo Where to store the pointer to the allocated
450	* error info structure on success. This is
451	* always set to NULL.
452	*/
453	RTDECL(int) RTErrInfoAllocEx(size_t cbMsg, PRTERRINFO *ppErrInfo);
454
455	/**
456	* Frees an error info structure allocated by RTErrInfoAlloc or
457	* RTErrInfoAllocEx.
458	*
459	* @param pErrInfo The error info structure.
460	*/
461	RTDECL(void) RTErrInfoFree(PRTERRINFO pErrInfo);
462
463	/**
464	* Fills in the error info details.
465	*
466	* @returns @a rc.
467	*
468	* @param pErrInfo The error info structure to fill in.
469	* @param rc The status code to return.
470	* @param pszMsg The error message string.
471	*/
472	RTDECL(int) RTErrInfoSet(PRTERRINFO pErrInfo, int rc, const char *pszMsg);
473
474	/**
475	* Fills in the error info details, with a sprintf style message.
476	*
477	* @returns @a rc.
478	*
479	* @param pErrInfo The error info structure to fill in.
480	* @param rc The status code to return.
481	* @param pszFormat The format string.
482	* @param ... The format arguments.
483	*/
484	RTDECL(int) RTErrInfoSetF(PRTERRINFO pErrInfo, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
485
486	/**
487	* Fills in the error info details, with a vsprintf style message.
488	*
489	* @returns @a rc.
490	*
491	* @param pErrInfo The error info structure to fill in.
492	* @param rc The status code to return.
493	* @param pszFormat The format string.
494	* @param va The format arguments.
495	*/
496	RTDECL(int) RTErrInfoSetV(PRTERRINFO pErrInfo, int rc, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
497
498	/**
499	* Adds more error info details.
500	*
501	* @returns @a rc.
502	*
503	* @param pErrInfo The error info structure to fill in.
504	* @param rc The status code to return.
505	* @param pszMsg The error message string to add.
506	*/
507	RTDECL(int) RTErrInfoAdd(PRTERRINFO pErrInfo, int rc, const char *pszMsg);
508
509	/**
510	* Adds more error info details, with a sprintf style message.
511	*
512	* @returns @a rc.
513	*
514	* @param pErrInfo The error info structure to fill in.
515	* @param rc The status code to return.
516	* @param pszFormat The format string to add.
517	* @param ... The format arguments.
518	*/
519	RTDECL(int) RTErrInfoAddF(PRTERRINFO pErrInfo, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
520
521	/**
522	* Adds more error info details, with a vsprintf style message.
523	*
524	* @returns @a rc.
525	*
526	* @param pErrInfo The error info structure to fill in.
527	* @param rc The status code to return.
528	* @param pszFormat The format string to add.
529	* @param va The format arguments.
530	*/
531	RTDECL(int) RTErrInfoAddV(PRTERRINFO pErrInfo, int rc, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
532
533	/** @name RTERRINFO_LOG_F_XXX
534	* @{ */
535	/** Both debug and release log. */
536	#define RTERRINFO_LOG_F_RELEASE RT_BIT_32(0)
537	/** @} */
538
539	/**
540	* Fills in the error info details.
541	*
542	* @returns @a rc.
543	*
544	* @param pErrInfo The error info structure to fill in.
545	* @param rc The status code to return.
546	* @param iLogGroup The logging group.
547	* @param fFlags RTERRINFO_LOG_F_XXX.
548	* @param pszMsg The error message string.
549	*/
550	RTDECL(int) RTErrInfoLogAndSet(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszMsg);
551
552	/**
553	* Fills in the error info details, with a sprintf style message.
554	*
555	* @returns @a rc.
556	*
557	* @param pErrInfo The error info structure to fill in.
558	* @param rc The status code to return.
559	* @param iLogGroup The logging group.
560	* @param fFlags RTERRINFO_LOG_F_XXX.
561	* @param pszFormat The format string.
562	* @param ... The format arguments.
563	*/
564	RTDECL(int) RTErrInfoLogAndSetF(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
565
566	/**
567	* Fills in the error info details, with a vsprintf style message.
568	*
569	* @returns @a rc.
570	*
571	* @param pErrInfo The error info structure to fill in.
572	* @param rc The status code to return.
573	* @param iLogGroup The logging group.
574	* @param fFlags RTERRINFO_LOG_F_XXX.
575	* @param pszFormat The format string.
576	* @param va The format arguments.
577	*/
578	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);
579
580	/**
581	* Adds more error info details.
582	*
583	* @returns @a rc.
584	*
585	* @param pErrInfo The error info structure to fill in.
586	* @param rc The status code to return.
587	* @param iLogGroup The logging group.
588	* @param fFlags RTERRINFO_LOG_F_XXX.
589	* @param pszMsg The error message string to add.
590	*/
591	RTDECL(int) RTErrInfoLogAndAdd(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszMsg);
592
593	/**
594	* Adds more error info details, with a sprintf style message.
595	*
596	* @returns @a rc.
597	*
598	* @param pErrInfo The error info structure to fill in.
599	* @param rc The status code to return.
600	* @param iLogGroup The logging group.
601	* @param fFlags RTERRINFO_LOG_F_XXX.
602	* @param pszFormat The format string to add.
603	* @param ... The format arguments.
604	*/
605	RTDECL(int) RTErrInfoLogAndAddF(PRTERRINFO pErrInfo, int rc, uint32_t iLogGroup, uint32_t fFlags, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
606
607	/**
608	* Adds more error info details, with a vsprintf style message.
609	*
610	* @returns @a rc.
611	*
612	* @param pErrInfo The error info structure to fill in.
613	* @param rc The status code to return.
614	* @param iLogGroup The logging group.
615	* @param fFlags RTERRINFO_LOG_F_XXX.
616	* @param pszFormat The format string to add.
617	* @param va The format arguments.
618	*/
619	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);
620
621	/** @name Macros wrapping the RTErrInfoLog* functions.
622	* @{ */
623	#ifndef LOG_DISABLED
624	# define RTERRINFO_LOG_SET( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoLogAndSet( a_pErrInfo, a_rc, LOG_GROUP, 0, a_pszMsg)
625	# 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)
626	# define RTERRINFO_LOG_ADD( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoLogAndAdd( a_pErrInfo, a_rc, LOG_GROUP, 0, a_pszMsg)
627	# 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)
628	# ifdef RT_COMPILER_SUPPORTS_VA_ARGS
629	# define RTERRINFO_LOG_ADD_F(a_pErrInfo, a_rc, ...) RTErrInfoLogAndAddF(a_pErrInfo, a_rc, LOG_GROUP, 0, __VA_ARGS__)
630	# define RTERRINFO_LOG_SET_F(a_pErrInfo, a_rc, ...) RTErrInfoLogAndSetF(a_pErrInfo, a_rc, LOG_GROUP, 0, __VA_ARGS__)
631	# else
632	# define RTERRINFO_LOG_ADD_F RTErrInfoAddF
633	# define RTERRINFO_LOG_SET_F RTErrInfoSetF
634	# endif
635	#else
636	# define RTERRINFO_LOG_SET( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoSet( a_pErrInfo, a_rc, a_pszMsg)
637	# define RTERRINFO_LOG_SET_V(a_pErrInfo, a_rc, a_pszMsg, a_va) RTErrInfoSetV(a_pErrInfo, a_rc, a_pszMsg, a_va)
638	# define RTERRINFO_LOG_ADD( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoAdd( a_pErrInfo, a_rc, a_pszMsg)
639	# define RTERRINFO_LOG_ADD_V(a_pErrInfo, a_rc, a_pszMsg, a_va) RTErrInfoAddV(a_pErrInfo, a_rc, a_pszMsg, a_va)
640	# define RTERRINFO_LOG_ADD_F RTErrInfoAddF
641	# define RTERRINFO_LOG_SET_F RTErrInfoSetF
642	#endif
643
644	#define RTERRINFO_LOG_REL_SET( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoLogAndSet( a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, a_pszMsg)
645	#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)
646	#define RTERRINFO_LOG_REL_ADD( a_pErrInfo, a_rc, a_pszMsg) RTErrInfoLogAndAdd( a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, a_pszMsg)
647	#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)
648	#ifdef RT_COMPILER_SUPPORTS_VA_ARGS
649	# define RTERRINFO_LOG_REL_ADD_F(a_pErrInfo, a_rc, ...) RTErrInfoLogAndAddF(a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, __VA_ARGS__)
650	# define RTERRINFO_LOG_REL_SET_F(a_pErrInfo, a_rc, ...) RTErrInfoLogAndSetF(a_pErrInfo, a_rc, LOG_GROUP, RTERRINFO_LOG_F_RELEASE, __VA_ARGS__)
651	#else
652	# define RTERRINFO_LOG_REL_ADD_F RTErrInfoAddF
653	# define RTERRINFO_LOG_REL_SET_F RTErrInfoSetF
654	#endif
655	/** @} */
656
657
658	/**
659	* Checks if the error info is set.
660	*
661	* @returns true if set, false if not.
662	* @param pErrInfo The error info structure. NULL is OK.
663	*/
664	DECLINLINE(bool) RTErrInfoIsSet(PCRTERRINFO pErrInfo)
665	{
666	if (!pErrInfo)
667	return false;
668	return (pErrInfo->fFlags & (RTERRINFO_FLAGS_MAGIC_MASK \| RTERRINFO_FLAGS_SET))
669	== (RTERRINFO_FLAGS_MAGIC \| RTERRINFO_FLAGS_SET);
670	}
671
672	/**
673	* Clears the error info structure.
674	*
675	* @param pErrInfo The error info structure. NULL is OK.
676	*/
677	DECLINLINE(void) RTErrInfoClear(PRTERRINFO pErrInfo)
678	{
679	if (pErrInfo)
680	{
681	pErrInfo->fFlags &= ~RTERRINFO_FLAGS_SET;
682	pErrInfo->rc = /VINF_SUCCESS/0;
683	*pErrInfo->pszMsg = '\0';
684	}
685	}
686
687	/**
688	* Storage for error variables.
689	*
690	* @remarks Do NOT touch the members! They are platform specific and what's
691	* where may change at any time!
692	*/
693	typedef union RTERRVARS
694	{
695	int8_t ai8Vars[32];
696	int16_t ai16Vars[16];
697	int32_t ai32Vars[8];
698	int64_t ai64Vars[4];
699	} RTERRVARS;
700	/** Pointer to an error variable storage union. */
701	typedef RTERRVARS *PRTERRVARS;
702	/** Pointer to a const error variable storage union. */
703	typedef RTERRVARS const *PCRTERRVARS;
704
705	/**
706	* Saves the error variables.
707	*
708	* @returns @a pVars.
709	* @param pVars The variable storage union.
710	*/
711	RTDECL(PRTERRVARS) RTErrVarsSave(PRTERRVARS pVars);
712
713	/**
714	* Restores the error variables.
715	*
716	* @param pVars The variable storage union.
717	*/
718	RTDECL(void) RTErrVarsRestore(PCRTERRVARS pVars);
719
720	/**
721	* Checks if the first variable set equals the second.
722	*
723	* @returns true if they are equal, false if not.
724	* @param pVars1 The first variable storage union.
725	* @param pVars2 The second variable storage union.
726	*/
727	RTDECL(bool) RTErrVarsAreEqual(PCRTERRVARS pVars1, PCRTERRVARS pVars2);
728
729	/**
730	* Checks if the (live) error variables have changed since we saved them.
731	*
732	* @returns @c true if they have changed, @c false if not.
733	* @param pVars The saved variables to compare the current state
734	* against.
735	*/
736	RTDECL(bool) RTErrVarsHaveChanged(PCRTERRVARS pVars);
737
738	RT_C_DECLS_END
739
740
741	/* We duplicate a handful of very commonly used status codes from err.h here.
742	Needless to say, these needs to match the err.h definition exactly: */
743
744	/** Success.
745	* @ingroup grp_rt_err */
746	#define VINF_SUCCESS 0
747
748	/** General failure - DON'T USE THIS!!!
749	* @ingroup grp_rt_err */
750	#define VERR_GENERAL_FAILURE (-1)
751	/** Invalid parameter.
752	* @ingroup grp_rt_err */
753	#define VERR_INVALID_PARAMETER (-2)
754	/** Invalid parameter.
755	* @ingroup grp_rt_err */
756	#define VWRN_INVALID_PARAMETER 2
757	/** Invalid magic or cookie.
758	* @ingroup grp_rt_err */
759	#define VERR_INVALID_MAGIC (-3)
760	/** Invalid magic or cookie.
761	* @ingroup grp_rt_err */
762	#define VWRN_INVALID_MAGIC 3
763	/** Invalid loader handle.
764	* @ingroup grp_rt_err */
765	#define VERR_INVALID_HANDLE (-4)
766	/** Invalid loader handle.
767	* @ingroup grp_rt_err */
768	#define VWRN_INVALID_HANDLE 4
769	/** Invalid memory pointer. */
770	#define VERR_INVALID_POINTER (-6)
771	/** Memory allocation failed.
772	* @ingroup grp_rt_err */
773	#define VERR_NO_MEMORY (-8)
774	/** Permission denied.
775	* @ingroup grp_rt_err */
776	#define VERR_PERMISSION_DENIED (-10)
777	/** Permission denied.
778	* @ingroup grp_rt_err */
779	#define VINF_PERMISSION_DENIED 10
780	/** Version mismatch.
781	* @ingroup grp_rt_err */
782	#define VERR_VERSION_MISMATCH (-11)
783	/** The request function is not implemented.
784	* @ingroup grp_rt_err */
785	#define VERR_NOT_IMPLEMENTED (-12)
786	/** Invalid flags was given.
787	* @ingroup grp_rt_err */
788	#define VERR_INVALID_FLAGS (-13)
789	/** Incorrect call order.
790	* @ingroup grp_rt_err */
791	#define VERR_WRONG_ORDER (-22)
792	/** Invalid function.
793	* @ingroup grp_rt_err */
794	#define VERR_INVALID_FUNCTION (-36)
795	/** Not supported.
796	* @ingroup grp_rt_err */
797	#define VERR_NOT_SUPPORTED (-37)
798	/** Not supported.
799	* @ingroup grp_rt_err */
800	#define VINF_NOT_SUPPORTED 37
801	/** Access denied.
802	* @ingroup grp_rt_err */
803	#define VERR_ACCESS_DENIED (-38)
804	/** Call interrupted.
805	* @ingroup grp_rt_err */
806	#define VERR_INTERRUPTED (-39)
807	/** Call interrupted.
808	* @ingroup grp_rt_err */
809	#define VINF_INTERRUPTED 39
810	/** Timeout.
811	* @ingroup grp_rt_err */
812	#define VERR_TIMEOUT (-40)
813	/** Timeout.
814	* @ingroup grp_rt_err */
815	#define VINF_TIMEOUT 40
816	/** Buffer too small to save result.
817	* @ingroup grp_rt_err */
818	#define VERR_BUFFER_OVERFLOW (-41)
819	/** Buffer too small to save result.
820	* @ingroup grp_rt_err */
821	#define VINF_BUFFER_OVERFLOW 41
822	/** Data size overflow.
823	* @ingroup grp_rt_err */
824	#define VERR_TOO_MUCH_DATA (-42)
825	/** Retry the operation.
826	* @ingroup grp_rt_err */
827	#define VERR_TRY_AGAIN (-52)
828	/** Retry the operation.
829	* @ingroup grp_rt_err */
830	#define VINF_TRY_AGAIN 52
831	/** Generic parse error.
832	* @ingroup grp_rt_err */
833	#define VERR_PARSE_ERROR (-53)
834	/** Value out of range.
835	* @ingroup grp_rt_err */
836	#define VERR_OUT_OF_RANGE (-54)
837	/** A numeric conversion encountered a value which was too big for the target.
838	* @ingroup grp_rt_err */
839	#define VERR_NUMBER_TOO_BIG (-55)
840	/** A numeric conversion encountered a value which was too big for the target.
841	* @ingroup grp_rt_err */
842	#define VWRN_NUMBER_TOO_BIG 55
843	/** The operation was cancelled by the user (copy) or another thread (local ipc).
844	* @ingroup grp_rt_err */
845	#define VERR_CANCELLED (-70)
846	/** Trailing characters.
847	* @ingroup grp_rt_err */
848	#define VERR_TRAILING_CHARS (-76)
849	/** Trailing characters.
850	* @ingroup grp_rt_err */
851	#define VWRN_TRAILING_CHARS 76
852	/** Trailing spaces.
853	* @ingroup grp_rt_err */
854	#define VERR_TRAILING_SPACES (-77)
855	/** Trailing spaces.
856	* @ingroup grp_rt_err */
857	#define VWRN_TRAILING_SPACES 77
858	/** Generic not found error.
859	* @ingroup grp_rt_err */
860	#define VERR_NOT_FOUND (-78)
861	/** Generic not found warning.
862	* @ingroup grp_rt_err */
863	#define VWRN_NOT_FOUND 78
864	/** Generic invalid state error.
865	* @ingroup grp_rt_err */
866	#define VERR_INVALID_STATE (-79)
867	/** Generic invalid state warning.
868	* @ingroup grp_rt_err */
869	#define VWRN_INVALID_STATE 79
870	/** Generic out of resources error.
871	* @ingroup grp_rt_err */
872	#define VERR_OUT_OF_RESOURCES (-80)
873	/** Generic out of resources warning.
874	* @ingroup grp_rt_err */
875	#define VWRN_OUT_OF_RESOURCES 80
876	/** End of string.
877	* @ingroup grp_rt_err */
878	#define VERR_END_OF_STRING (-83)
879	/** Return instigated by a callback or similar.
880	* @ingroup grp_rt_err */
881	#define VERR_CALLBACK_RETURN (-88)
882	/** Return instigated by a callback or similar.
883	* @ingroup grp_rt_err */
884	#define VINF_CALLBACK_RETURN 88
885	/** Duplicate something.
886	* @ingroup grp_rt_err */
887	#define VERR_DUPLICATE (-98)
888	/** Something is missing.
889	* @ingroup grp_rt_err */
890	#define VERR_MISSING (-99)
891	/** Buffer underflow.
892	* @ingroup grp_rt_err */
893	#define VERR_BUFFER_UNDERFLOW (-22401)
894	/** Buffer underflow.
895	* @ingroup grp_rt_err */
896	#define VINF_BUFFER_UNDERFLOW 22401
897	/** Something is not available or not working properly.
898	* @ingroup grp_rt_err */
899	#define VERR_NOT_AVAILABLE (-22403)
900	/** Mismatch.
901	* @ingroup grp_rt_err */
902	#define VERR_MISMATCH (-22408)
903	/** Wrong type.
904	* @ingroup grp_rt_err */
905	#define VERR_WRONG_TYPE (-22409)
906	/** Wrong type.
907	* @ingroup grp_rt_err */
908	#define VWRN_WRONG_TYPE (22409)
909	/** Wrong parameter count.
910	* @ingroup grp_rt_err */
911	#define VERR_WRONG_PARAMETER_COUNT (-22415)
912	/** Wrong parameter type.
913	* @ingroup grp_rt_err */
914	#define VERR_WRONG_PARAMETER_TYPE (-22416)
915	/** Invalid client ID.
916	* @ingroup grp_rt_err */
917	#define VERR_INVALID_CLIENT_ID (-22417)
918	/** Invalid session ID.
919	* @ingroup grp_rt_err */
920	#define VERR_INVALID_SESSION_ID (-22418)
921	/** Incompatible configuration requested.
922	* @ingroup grp_rt_err */
923	#define VERR_INCOMPATIBLE_CONFIG (-22420)
924	/** Internal error - this should never happen.
925	* @ingroup grp_rt_err */
926	#define VERR_INTERNAL_ERROR (-225)
927	/** RTGetOpt: Not an option.
928	* @ingroup grp_rt_err */
929	#define VINF_GETOPT_NOT_OPTION 828
930	/** RTGetOpt: Command line option not recognized.
931	* @ingroup grp_rt_err */
932	#define VERR_GETOPT_UNKNOWN_OPTION (-825)
933
934	/** @} */
935
936	#endif /* !IPRT_INCLUDED_errcore_h */
937

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

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

Download in other formats: