Context Navigation

← Previous Revision
Next Revision →
Normal
Revision Log

errcore.h

Last change on this file was 98573, checked in by vboxsync, 15 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

Rev	Line
[1]	1	/** @file
[76326]	2	* IPRT - Status Codes Core.
[1]	3	*/
	4
	5	/*
[98103]	6	* Copyright (C) 2006-2023 Oracle and/or its affiliates.
[1]	7	*
[96407]	8	* This file is part of VirtualBox base platform packages, as
	9	* available from https://www.virtualbox.org.
[5999]	10	*
[96407]	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	*
[5999]	24	* The contents of this file may alternatively be used under the terms
	25	* of the Common Development and Distribution License Version 1.0
[96407]	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
[5999]	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.
[96407]	32	*
	33	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
[1]	34	*/
	35
[76557]	36	#ifndef IPRT_INCLUDED_errcore_h
	37	#define IPRT_INCLUDED_errcore_h
[76507]	38	#ifndef RT_WITHOUT_PRAGMA_ONCE
	39	# pragma once
	40	#endif
[1]	41
	42	#include <iprt/cdefs.h>
	43	#include <iprt/types.h>
[35182]	44	#include <iprt/stdarg.h>
[1]	45
	46
[76326]	47	/** @defgroup grp_rt_err_core Status Codes Core
	48	* @ingroup grp_rt_err
[1]	49	* @{
	50	*/
[3004]	51
[76348]	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
[22488]	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	*/
[85076]	145	RTErrStrictType(RTErrStrictType2 const rcObj) RT_NO_THROW_DEF
[22488]	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	*/
[85076]	155	RTErrStrictType(int32_t rc) RT_NO_THROW_DEF
[22488]	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	*/
[85076]	175	bool success() const RT_NO_THROW_DEF
[22488]	176	{
	177	return m_rc >= 0;
	178	}
	179
	180	private:
	181	/** @name Try ban a number of wrong types.
	182	* @{ */
[85076]	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); }
[22488]	190	/** @todo fight long here - clashes with int32_t/int64_t on some platforms. */
	191	/** @} */
	192	};
	193	#endif /* __cplusplus */
	194
	195
[33945]	196	RT_C_DECLS_BEGIN
	197
[3004]	198	/**
	199	* Converts a Darwin HRESULT error to an iprt status code.
	200	*
	201	* @returns iprt status code.
[8288]	202	* @param iNativeCode HRESULT error code.
	203	* @remark Darwin ring-3 only.
[3004]	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.
[8288]	211	* @param iNativeCode IOReturn error code.
[3004]	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.
[8288]	220	* @param iNativeCode kern_return_t error code.
[3004]	221	* @remark Darwin only.
	222	*/
	223	RTDECL(int) RTErrConvertFromDarwinKern(int iNativeCode);
	224
	225	/**
[8288]	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	/**
[3004]	241	* Converts errno to iprt status code.
	242	*
	243	* @returns iprt status code.
[77110]	244	* @param iNativeCode errno code.
[3004]	245	*/
[77110]	246	RTDECL(int) RTErrConvertFromErrno(int iNativeCode);
[3004]	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
[4808]	286	/**
[4822]	287	* Converts an iprt status code to a errno status code.
[4808]	288	*
[4822]	289	* @returns errno status code.
[4808]	290	* @param iErr iprt status code.
	291	*/
[4822]	292	RTDECL(int) RTErrConvertToErrno(int iErr);
[3004]	293
	294
[84054]	295	#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/string.h & iprt/log.h */
	296	#define DECLARED_FNRTSTROUTPUT
[3004]	297	/**
[84054]	298	* Output callback.
[3004]	299	*
[84054]	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.
[3004]	304	*/
[85121]	305	typedef DECLCALLBACKTYPE(size_t, FNRTSTROUTPUT,(void pvArg, const char pachChars, size_t cbChars));
[84054]	306	/** Pointer to callback function. */
	307	typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
	308	#endif
[3004]	309
[84054]	310	#ifdef IN_RING3
[3004]	311
[84054]	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);
[3004]	316
[84054]	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	/** @} */
[3004]	325
[84054]	326
[84063]	327	# ifdef RT_OS_WINDOWS
[3004]	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
[84063]	345	RTDECL(bool) RTErrWinIsKnown(long rc);
	346	RTDECL(ssize_t) RTErrWinQueryDefine(long rc, char *pszBuf, size_t cbBuf, bool fFailIfUnknown);
[3004]	347
[84063]	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	/** @} */
[8402]	355
[84063]	356	# else /* !RT_OS_WINDOWS */
[8402]	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
[84063]	383	# endif /* !RT_OS_WINDOWS */
	384
[3004]	385	#endif /* IN_RING3 */
	386
[35182]	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	*
[51770]	432	* @returns Pointer to the core error info structure.
[35182]	433	* @param pStaticErrInfo The static error info structure to init.
	434	*/
[51770]	435	DECLINLINE(PRTERRINFO) RTErrInfoInitStatic(PRTERRINFOSTATIC pStaticErrInfo)
[35182]	436	{
	437	RTErrInfoInit(&pStaticErrInfo->Core, pStaticErrInfo->szMsg, sizeof(pStaticErrInfo->szMsg));
	438	pStaticErrInfo->Core.fFlags = RTERRINFO_FLAGS_T_STATIC \| RTERRINFO_FLAGS_MAGIC;
[51770]	439	return &pStaticErrInfo->Core;
[35182]	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	*/
[57004]	494	RTDECL(int) RTErrInfoSetF(PRTERRINFO pErrInfo, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
[35182]	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	*/
[57004]	506	RTDECL(int) RTErrInfoSetV(PRTERRINFO pErrInfo, int rc, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
[35182]	507
	508	/**
[51770]	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	*/
[57004]	529	RTDECL(int) RTErrInfoAddF(PRTERRINFO pErrInfo, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
[51770]	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	*/
[57004]	541	RTDECL(int) RTErrInfoAddV(PRTERRINFO pErrInfo, int rc, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
[51770]	542
[69011]	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
[51770]	549	/**
[69011]	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	* @{ */
[70315]	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
[88218]	642	# define RTERRINFO_LOG_ADD_F RTErrInfoAddF
	643	# define RTERRINFO_LOG_SET_F RTErrInfoSetF
[70315]	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)
[88218]	650	# define RTERRINFO_LOG_ADD_F RTErrInfoAddF
	651	# define RTERRINFO_LOG_SET_F RTErrInfoSetF
[69011]	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
[88218]	662	# define RTERRINFO_LOG_REL_ADD_F RTErrInfoAddF
	663	# define RTERRINFO_LOG_REL_SET_F RTErrInfoSetF
[69011]	664	#endif
	665	/** @} */
	666
	667
	668	/**
[35182]	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
[37233]	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
[33945]	748	RT_C_DECLS_END
	749
[76421]	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
[98573]	773	/** Invalid handle.
[76421]	774	* @ingroup grp_rt_err */
	775	#define VERR_INVALID_HANDLE (-4)
[98573]	776	/** Invalid handle.
[76421]	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)
[76423]	799	/** Incorrect call order.
	800	* @ingroup grp_rt_err */
	801	#define VERR_WRONG_ORDER (-22)
[76421]	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)
[76423]	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
[76421]	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)
[76423]	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
[76421]	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)
[76423]	937	/** RTGetOpt: Not an option.
	938	* @ingroup grp_rt_err */
	939	#define VINF_GETOPT_NOT_OPTION 828
[76432]	940	/** RTGetOpt: Command line option not recognized.
	941	* @ingroup grp_rt_err */
	942	#define VERR_GETOPT_UNKNOWN_OPTION (-825)
[76421]	943
[3004]	944	/** @} */
	945
[76585]	946	#endif /* !IPRT_INCLUDED_errcore_h */
[1]	947

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

Context Navigation

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

Download in other formats: