errcore.h@ 101243

Last change on this file since 101243 was 98573, checked in by vboxsync, 22 months ago
iprt/err.h,errcore.h: Corrected VERR_INVALID_HANDLE description.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 32.0 KB

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

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

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

Download in other formats: