VirtualBox

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

Last change on this file was 106061, checked in by vboxsync, 3 weeks ago

Copyright year updates by scm.

  • 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-2024 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 */
130class RTErrStrictType
131{
132protected:
133 int32_t m_rc;
134
135public:
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
180private:
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
196RT_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 */
205RTDECL(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 */
214RTDECL(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 */
223RTDECL(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 */
238RTDECL(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 */
246RTDECL(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 */
255RTDECL(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 */
266RTDECL(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 */
275RTDECL(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 */
284RTDECL(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 */
292RTDECL(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 */
305typedef DECLCALLBACKTYPE(size_t, FNRTSTROUTPUT,(void *pvArg, const char *pachChars, size_t cbChars));
306/** Pointer to callback function. */
307typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
308#endif
309
310#ifdef IN_RING3
311
312RTDECL(bool) RTErrIsKnown(int rc);
313RTDECL(ssize_t) RTErrQueryDefine(int rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
314RTDECL(ssize_t) RTErrQueryMsgShort(int rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
315RTDECL(ssize_t) RTErrQueryMsgFull(int rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
316
317/** @name Error formatters used internally by RTStrFormat.
318 * @internal
319 * @{ */
320RTDECL(size_t) RTErrFormatDefine( int rc, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, char *pszTmp, size_t cbTmp);
321RTDECL(size_t) RTErrFormatMsgShort(int rc, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, char *pszTmp, size_t cbTmp);
322RTDECL(size_t) RTErrFormatMsgFull( int rc, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, char *pszTmp, size_t cbTmp);
323RTDECL(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 */
331typedef 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. */
341typedef RTWINERRMSG *PRTWINERRMSG;
342/** Pointer to const Windows error code message. */
343typedef const RTWINERRMSG *PCRTWINERRMSG;
344
345RTDECL(bool) RTErrWinIsKnown(long rc);
346RTDECL(ssize_t) RTErrWinQueryDefine(long rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
347
348/** @name Error formatters used internally by RTStrFormat.
349 * @internal
350 * @{ */
351RTDECL(size_t) RTErrWinFormatDefine(long rc, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, char *pszTmp, size_t cbTmp);
352RTDECL(size_t) RTErrWinFormatMsg( long rc, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, char *pszTmp, size_t cbTmp);
353RTDECL(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 */
361typedef 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. */
371typedef RTCOMERRMSG *PRTCOMERRMSG;
372/** Pointer to const a XPCOM/COM error code message. */
373typedef 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 */
381RTDECL(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 */
415DECLINLINE(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 */
435DECLINLINE(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 */
450RTDECL(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 */
463RTDECL(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 */
471RTDECL(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 */
482RTDECL(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 */
494RTDECL(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 */
506RTDECL(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 */
517RTDECL(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 */
529RTDECL(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 */
541RTDECL(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 */
560RTDECL(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 */
574RTDECL(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 */
588RTDECL(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 */
601RTDECL(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 */
615RTDECL(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 */
629RTDECL(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 */
674DECLINLINE(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 */
687DECLINLINE(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 */
703typedef 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. */
711typedef RTERRVARS *PRTERRVARS;
712/** Pointer to a const error variable storage union. */
713typedef RTERRVARS const *PCRTERRVARS;
714
715/**
716 * Saves the error variables.
717 *
718 * @returns @a pVars.
719 * @param pVars The variable storage union.
720 */
721RTDECL(PRTERRVARS) RTErrVarsSave(PRTERRVARS pVars);
722
723/**
724 * Restores the error variables.
725 *
726 * @param pVars The variable storage union.
727 */
728RTDECL(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 */
737RTDECL(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 */
746RTDECL(bool) RTErrVarsHaveChanged(PCRTERRVARS pVars);
747
748RT_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.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette