Logo Search packages:      
Sourcecode: virtualbox-ose version File versions

RTDECL ( int   ) 

Converts a Darwin HRESULT error to an iprt status code.

Returns:
iprt status code.
Parameters:
iNativeCode HRESULT error code.
Remarks:
Darwin ring-3 only.
Converts a Darwin IOReturn error to an iprt status code.

Returns:
iprt status code.
Parameters:
iNativeCode IOReturn error code.
Remarks:
Darwin only.
Converts a Darwin kern_return_t error to an iprt status code.

Returns:
iprt status code.
Parameters:
iNativeCode kern_return_t error code.
Remarks:
Darwin only.
Converts a Darwin error to an iprt status code.

This will consult RTErrConvertFromDarwinKern, RTErrConvertFromDarwinIO and RTErrConvertFromDarwinCOM in this order. The latter is ring-3 only as it doesn't apply elsewhere.

Returns:
iprt status code.
Parameters:
iNativeCode Darwin error code.
Remarks:
Darwin only.

This is recommended over RTErrConvertFromDarwinKern and RTErrConvertFromDarwinIO since these are really just subsets of the same error space.

Converts errno to iprt status code.

Returns:
iprt status code.
Parameters:
uNativeCode errno code.
Converts a L4 errno to a iprt status code.

Returns:
iprt status code.
Parameters:
uNativeCode l4 errno.
Remarks:
L4 only.
Converts NT status code to iprt status code.

Needless to say, this is only available on NT and winXX targets.

Returns:
iprt status code.
Parameters:
lNativeCode NT status code.
Remarks:
Windows only.
Converts OS/2 error code to iprt status code.

Returns:
iprt status code.
Parameters:
uNativeCode OS/2 error code.
Remarks:
OS/2 only.
Converts Win32 error code to iprt status code.

Returns:
iprt status code.
Parameters:
uNativeCode Win32 error code.
Remarks:
Windows only.
Converts an iprt status code to a errno status code.

Returns:
errno status code.
Parameters:
iErr iprt status code.
Encodes the specifed data into a Base64 string, the caller supplies the output buffer.

This will make the same assumptions about line breaks and EOL size as RTBase64EncodedLength() does. A RTBase64EncodeEx function can be added if more strict control over the output formatting is found necessary.

Returns:
IRPT status code.
Return values:
VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer may contain an invalid Base64 string.
Parameters:
pvData The data to encode.
cbData The number of bytes to encode.
pszBuf Where to put the Base64 string.
cbBuf The size of the output buffer, including the terminator.
pcchActual The actual number of characters returned.
Destroy a cache freeing allocated memory.

Returns:
iprt status code.
Parameters:
pCache Pointer to the cache.
Request an object from the cache.

Returns:
iprt status VERR_CACHE_EMPTY if cache is not unlimited and there is no object left in cache.
Parameters:
pCache Pointer to the cache to get an object from.
ppObj Where to store the pointer to the object.
Insert an object into the cache.

Returns:
iprt status code. VERR_CACHE_FULL if cache is not unlimited and there is no free entry left in cache.
Parameters:
pCache Pointer to the cache.
pObj Pointer to the object to insert.
Variant of RTDbgAsCreate that takes a name format string.

Returns:
IPRT status code.
Parameters:
phDbgAs Where to store the address space handle on success.
FirstAddr The first address in the address space.
LastAddr The last address in the address space.
pszNameFmt The name format of the address space.
va Format arguments.
Variant of RTDbgAsCreate that takes a name format string.

Returns:
IPRT status code.
Parameters:
phDbgAs Where to store the address space handle on success.
FirstAddr The first address in the address space.
LastAddr The last address in the address space.
pszNameFmt The name format of the address space.
... Format arguments.
Links a module into the address space at the give address.

The size of the mapping is determined using RTDbgModImageSize().

Returns:
IPRT status code.
Return values:
VERR_OUT_OF_RANGE if the specified address will put the module outside the address space.
VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
Parameters:
hDbgAs The address space handle.
hDbgMod The module handle of the module to be linked in.
ImageAddr The address to link the module at.
fFlags See RTDBGASLINK_FLAGS_*.
Links a segment into the address space at the give address.

The size of the mapping is determined using RTDbgModSegmentSize().

Returns:
IPRT status code.
Return values:
VERR_OUT_OF_RANGE if the specified address will put the module outside the address space.
VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
Parameters:
hDbgAs The address space handle.
hDbgMod The module handle.
iSeg The segment number (0-based) of the segment to be linked in.
SegAddr The address to link the segment at.
fFlags See RTDBGASLINK_FLAGS_*.
Unlinks all the mappings of a module from the address space.

Returns:
IPRT status code.
Return values:
VERR_NOT_FOUND if the module wasn't found.
Parameters:
hDbgAs The address space handle.
hDbgMod The module handle of the module to be unlinked.
Unlinks the mapping at the specified address.

Returns:
IPRT status code.
Return values:
VERR_NOT_FOUND if no module or segment is mapped at that address.
Parameters:
hDbgAs The address space handle.
Addr The address within the mapping to be unlinked.
Queries mapping module information by handle.

Returns:
IPRT status code.
Return values:
VERR_NOT_FOUND if no mapping was found at the specified address.
Parameters:
hDbgAs The address space handle.
Addr Address within the mapping of the module or segment.
phMod Where to the return the retained module handle. Optional.
pAddr Where to return the base address of the mapping. Optional.
piSeg Where to return the segment index. This is set to NIL if the entire module is mapped as a single mapping. Optional.
Queries mapping module information by name.

Returns:
IPRT status code.
Return values:
VERR_NOT_FOUND if no mapping was found at the specified address.
VERR_OUT_OF_RANGE if the name index was out of range.
Parameters:
hDbgAs The address space handle.
pszName The module name.
iName There can be more than one module by the same name in an address space. This argument indicates which is ment. (0 based)
phMod Where to the return the retained module handle.
Adds a symbol to a module in the address space.

Returns:
IPRT status code. See RTDbgModSymbolAdd for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if no module was found at the specified address.
VERR_NOT_SUPPORTED if the module interpret doesn't support adding custom symbols.
Parameters:
hDbgAs The address space handle.
pszSymbol The symbol name.
Addr The address of the symbol.
cb The size of the symbol.
fFlags Symbol flags.
piOrdinal Where to return the symbol ordinal on success. If the interpreter doesn't do ordinals, this will be set to UINT32_MAX. Optional
Query a symbol by address.

Returns:
IPRT status code. See RTDbgModSymbolAddr for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if the address couldn't be mapped to a module.
Parameters:
hDbgAs The address space handle.
Addr The address which closest symbol is requested.
poffDisp Where to return the distance between the symbol and address. Optional.
pSymInfo Where to return the symbol info.
Query a symbol by address.

Returns:
IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if the address couldn't be mapped to a module.
Parameters:
hDbgAs The address space handle.
Addr The address which closest symbol is requested.
poffDisp Where to return the distance between the symbol and address. Optional.
ppSymInfo Where to return the pointer to the allocated symbol info. Always set. Free with RTDbgSymbolFree.
Query a symbol by name.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if not found.
Parameters:
hDbgAs The address space handle.
pszSymbol The symbol name.
pSymInfo Where to return the symbol info.
Query a symbol by name.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if not found.
Parameters:
hDbgAs The address space handle.
pszSymbol The symbol name.
ppSymInfo Where to return the pointer to the allocated symbol info. Always set. Free with RTDbgSymbolFree.
Query a line number by address.

Returns:
IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if the address couldn't be mapped to a module.
Parameters:
hDbgAs The address space handle.
Addr The address which closest symbol is requested.
poffDisp Where to return the distance between the line number and address.
pLine Where to return the line number information.
Adds a line number to a module in the address space.

Returns:
IPRT status code. See RTDbgModSymbolAdd for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if no module was found at the specified address.
VERR_NOT_SUPPORTED if the module interpret doesn't support adding custom symbols.
Parameters:
hDbgAs The address space handle.
pszFile The file name.
uLineNo The line number.
Addr The address of the symbol.
piOrdinal Where to return the line number ordinal on success. If the interpreter doesn't do ordinals, this will be set to UINT32_MAX. Optional.
Query a line number by address.

Returns:
IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if the address couldn't be mapped to a module.
Parameters:
hDbgAs The address space handle.
Addr The address which closest symbol is requested.
poffDisp Where to return the distance between the line number and address.
ppLine Where to return the pointer to the allocated line number info. Always set. Free with RTDbgLineFree.
Creates a module based on the default debug info container.

This can be used to manually load a module and its symbol. The primary user group is the debug info interpreters, which use this API to create an efficient debug info container behind the scenes and forward all queries to it once the info has been loaded.

Returns:
IPRT status code.
Parameters:
phDbgMod Where to return the module handle.
pszName The name of the module (mandatory).
cbSeg The size of initial segment. If zero, segments will have to be added manually using RTDbgModSegmentAdd.
fFlags Flags reserved for future extensions, MBZ for now.
Adds a segment to the module. Optional feature.

This method is intended used for manually constructing debug info for a module. The main usage is from other debug info interpreters that want to avoid writing a debug info database and instead uses the standard container behind the scenes.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if this feature isn't support by the debug info interpreter. This is a common return code.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
VERR_INVALID_PARAMETER if fFlags contains undefined flags.
VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
Parameters:
hDbgMod The module handle.
uRva The image relative address of the segment.
cb The size of the segment.
pszName The segment name. Does not normally need to be unique, although this is somewhat up to the debug interpreter to decide.
fFlags Segment flags. Reserved for future used, MBZ.
piSeg The segment index or NIL_RTDBGSEGIDX on input. The assigned segment index on successful return. Optional.
Query information about a segment.

This can be used together with RTDbgModSegmentCount to enumerate segments. The index starts a 0 and stops one below RTDbgModSegmentCount.

Returns:
IPRT status code.
Return values:
VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
VERR_INVALID_HANDLE if hDbgMod is invalid.
Parameters:
hDbgMod The module handle.
iSeg The segment index. No special segments.
pSegInfo Where to return the segment info. The RTDBGSEGMENT::Address member will be set to RTUINTPTR_MAX or the load address used at link time.
Adds a line number to the module.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if the module interpret doesn't support adding custom symbols. This is a common place occurance.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or short.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
Parameters:
hDbgMod The module handle.
pszSymbol The symbol name.
iSeg The segment index.
off The segment offset.
cb The size of the symbol. Can be zero, although this may depend somewhat on the debug interpreter.
fFlags Symbol flags. Reserved for the future, MBZ.
piOrdinal Where to return the symbol ordinal on success. If the interpreter doesn't do ordinals, this will be set to UINT32_MAX. Optional.
Queries symbol information by ordinal number.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
Parameters:
hDbgMod The module handle.
iOrdinal The symbol ordinal number. 0-based. The highest number is RTDbgModSymbolCount() - 1.
pSymInfo Where to store the symbol information.
Queries symbol information by ordinal number.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
Parameters:
hDbgMod The module handle.
iOrdinal The symbol ordinal number. 0-based. The highest number is RTDbgModSymbolCount() - 1.
ppSymInfo Where to store the pointer to the returned symbol information. Always set. Free with RTDbgSymbolFree.
Queries symbol information by address.

The returned symbol is what the debug info interpreter consideres the symbol most applicable to the specified address. This usually means a symbol with an address equal or lower than the requested.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
Parameters:
hDbgMod The module handle.
iSeg The segment number.
off The offset into the segment.
poffDisp Where to store the distance between the specified address and the returned symbol. Optional.
pSymInfo Where to store the symbol information.
Queries symbol information by address.

The returned symbol is what the debug info interpreter consideres the symbol most applicable to the specified address. This usually means a symbol with an address equal or lower than the requested.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
Parameters:
hDbgMod The module handle.
iSeg The segment index.
off The offset into the segment.
poffDisp Where to store the distance between the specified address and the returned symbol. Optional.
ppSymInfo Where to store the pointer to the returned symbol information. Always set. Free with RTDbgSymbolFree.
Queries symbol information by symbol name.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or short.
Parameters:
hDbgMod The module handle.
pszSymbol The symbol name.
pSymInfo Where to store the symbol information.
Queries symbol information by symbol name.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or short.
VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
Parameters:
hDbgMod The module handle.
pszSymbol The symbol name.
ppSymInfo Where to store the pointer to the returned symbol information. Always set. Free with RTDbgSymbolFree.
Adds a line number to the module.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if the module interpret doesn't support adding custom symbols. This should be consider a normal response.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or empty.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
Parameters:
hDbgMod The module handle.
pszFile The file name.
uLineNo The line number.
iSeg The segment index.
off The segment offset.
piOrdinal Where to return the line number ordinal on success. If the interpreter doesn't do ordinals, this will be set to UINT32_MAX. Optional.
Queries line number information by ordinal number.

This can be used to enumerate the line numbers for the module. Use RTDbgModLineCount() to figure the end of the ordinals.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
VERR_DBG_LINE_NOT_FOUND if there is no line number with that ordinal.
VERR_INVALID_HANDLE if hDbgMod is invalid.
Parameters:
hDbgMod The module handle.
iOrdinal The line number ordinal number.
pLineInfo Where to store the information about the line number.
Queries line number information by ordinal number.

This can be used to enumerate the line numbers for the module. Use RTDbgModLineCount() to figure the end of the ordinals.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
VERR_DBG_LINE_NOT_FOUND if there is no line number with that ordinal.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_NO_MEMORY if RTDbgLineAlloc fails.
Parameters:
hDbgMod The module handle.
iOrdinal The line number ordinal number.
ppLineInfo Where to store the pointer to the returned line number information. Always set. Free with RTDbgLineFree.
Queries line number information by address.

The returned line number is what the debug info interpreter consideres the one most applicable to the specified address. This usually means a line number with an address equal or lower than the requested.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
Parameters:
hDbgMod The module handle.
iSeg The segment number.
off The offset into the segment.
poffDisp Where to store the distance between the specified address and the returned symbol. Optional.
pSymInfo Where to store the symbol information.
Queries line number information by address.

The returned line number is what the debug info interpreter consideres the one most applicable to the specified address. This usually means a line number with an address equal or lower than the requested.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
VERR_NO_MEMORY if RTDbgLineAlloc fails.
Parameters:
hDbgMod The module handle.
iSeg The segment number.
off The offset into the segment.
poffDisp Where to store the distance between the specified address and the returned symbol. Optional.
ppLineInfo Where to store the pointer to the returned line number information. Always set. Free with RTDbgLineFree.
Converts a Darwin IOReturn error to an iprt status code.

Returns:
iprt status code.
Parameters:
iNativeCode IOReturn error code.
Remarks:
Darwin only.
Converts a Darwin kern_return_t error to an iprt status code.

Returns:
iprt status code.
Parameters:
iNativeCode kern_return_t error code.
Remarks:
Darwin only.
Converts a Darwin error to an iprt status code.

This will consult RTErrConvertFromDarwinKern, RTErrConvertFromDarwinIO and RTErrConvertFromDarwinCOM in this order. The latter is ring-3 only as it doesn't apply elsewhere.

Returns:
iprt status code.
Parameters:
iNativeCode Darwin error code.
Remarks:
Darwin only.

This is recommended over RTErrConvertFromDarwinKern and RTErrConvertFromDarwinIO since these are really just subsets of the same error space.

Converts errno to iprt status code.

Returns:
iprt status code.
Parameters:
uNativeCode errno code.
Converts a L4 errno to a iprt status code.

Returns:
iprt status code.
Parameters:
uNativeCode l4 errno.
Remarks:
L4 only.
Converts NT status code to iprt status code.

Needless to say, this is only available on NT and winXX targets.

Returns:
iprt status code.
Parameters:
lNativeCode NT status code.
Remarks:
Windows only.
Converts OS/2 error code to iprt status code.

Returns:
iprt status code.
Parameters:
uNativeCode OS/2 error code.
Remarks:
OS/2 only.
Converts Win32 error code to iprt status code.

Returns:
iprt status code.
Parameters:
uNativeCode Win32 error code.
Remarks:
Windows only.
Converts an iprt status code to a errno status code.

Returns:
errno status code.
Parameters:
iErr iprt status code.
Command line argument parser, handling both long and short options and checking argument formats, if desired.

This is to be called in a loop until it returns 0 (meaning that all options were parsed) or a negative value (meaning that an error occured). How non-option arguments are dealt with depends on the flags passed to RTGetOptInit. The default (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to the argument string.

For example, for a program which takes the following options:

--optwithstring (or -s) and a string argument; --optwithint (or -i) and a 32-bit signed integer argument; --verbose (or -v) with no arguments,

code would look something like this:

int main(int argc, char **argv)
{
     RTR3Init();

     static const RTGETOPTDEF s_aOptions[] =
     {
         { "--optwithstring",    's', RTGETOPT_REQ_STRING },
         { "--optwithint",       'i', RTGETOPT_REQ_INT32 },
         { "--verbose",          'v', 0 },
     };

     int ch;
     RTGETOPTUNION ValueUnion;
     RTGETOPTSTATE GetState;
     RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
     while ((ch = RTGetOpt(&GetState, &ValueUnion)))
     {
         // for options that require an argument, ValueUnion has received the value
         switch (ch)
         {
             case 's': // --optwithstring or -s
                 // string argument, copy ValueUnion.psz
                 break;

             case 'i': // --optwithint or -i
                 // integer argument, copy ValueUnion.i32
                 break;

             case 'v': // --verbose or -v
                 g_fOptVerbose = true;
                 break;

             case VINF_GETOPT_NOT_OPTION:
                 // handle non-option argument in ValueUnion.psz.
                 break;

             default:
                 if (ch > 0)
                 {
                     if (RT_C_IS_GRAPH(ch))
                         Error("unhandled option: -%c\n", ch);
                     else
                         Error("unhandled option: %i\n", ch);
                 }
                 else if (ch == VERR_GETOPT_UNKNOWN_OPTION)
                     Error("unknown option: %s\n", ValueUnion.psz);
                 else if (ValueUnion.pDef)
                     Error("%s: %Rrs\n", ValueUnion.pDef->pszLong, ch);
                 else
                     Error("%Rrs\n", ch);
                 return 1;
         }
     }

     return 0;
}

Returns:
0 when done parsing.

the iShort value of the option. pState->pDef points to the option definition which matched.

IPRT error status on parse error.

VINF_GETOPT_NOT_OPTION when encountering a non-option argument and RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the argument string.

VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option. pValueUnion->psz points to the option string.

VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if a required argument (aka value) was missing for an option.

VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if argument (aka value) conversion failed.

Parameters:
pState The state previously initialized with RTGetOptInit.
pValueUnion Union with value; in the event of an error, psz member points to erroneous parameter; otherwise, for options that require an argument, this contains the value of that argument, depending on the type that is required.
A simplified version of the RTHandleTableCreateEx API.

It assumes a max of about 64K handles with 1 being the base. The table access will serialized (RTHANDLETABLE_FLAGS_LOCKED).

Returns:
IPRT status code and *phHandleTable.
Parameters:
pHandleTable Where to store the handle table handle on success.
Destroys a handle table.

If any entries are still in used the pfnDelete callback will be invoked on each of them (if specfied) to allow to you clean things up.

Returns:
IPRT status code
Parameters:
hHandleTable The handle to the handle table.
pfnDelete Function to be called back on each handle still in use. Optional.
pvUser The user argument to pfnDelete.
Allocates a handle from the handle table.

Returns:
IPRT status code, almost any.
Return values:
VINF_SUCCESS on success.
VERR_NO_MEMORY if we failed to extend the handle table.
VERR_NO_MORE_HANDLES if we're out of handles.
Parameters:
hHandleTable The handle to the handle table.
pvObj The object to associate with the new handle. This must be aligned on a 4 byte boundrary.
ph Where to return the handle on success.
Remarks:
Do not call this if RTHANDLETABLE_FLAGS_CONTEXT was used during creation.
Allocates a handle from the handle table.

Returns:
IPRT status code, almost any.
Return values:
VINF_SUCCESS on success.
VERR_NO_MEMORY if we failed to extend the handle table.
VERR_NO_MORE_HANDLES if we're out of handles.
Parameters:
hHandleTable The handle to the handle table.
pvObj The object to associate with the new handle. This must be aligned on a 4 byte boundrary.
pvCtx The context to associate with the new handle.
ph Where to return the handle on success.
Remarks:
Call this if RTHANDLETABLE_FLAGS_CONTEXT was used during creation.
Merge two simple heaps into one.

The requiremet is of course that they next two each other memory wise.

Returns:
IPRT status code on success.
Parameters:
pHeap Where to store the handle to the merged heap on success.
Heap1 Handle to the first heap.
Heap2 Handle to the second heap.
Remarks:
This API isn't implemented yet.
Deregister a termination callback.

Returns:
VINF_SUCCESS if found, VERR_NOT_FOUND if the callback/pvUser pair wasn't found.
Parameters:
pfnCallback The callback function.
pvUser The user argument for the callback.
Loads a dynamic load library (/shared object) image file residing in the RTPathAppPrivateArch() directory.

Suffix is not required.

Returns:
iprt status code.
Parameters:
pszFilename Image filename. No path.
phLdrMod Where to store the handle to the loaded module.
Open a binary image file, extended version.

Returns:
iprt status code.
Parameters:
pszFilename Image filename.
fFlags Reserved, MBZ.
enmArch CPU architecture specifier for the image to be loaded.
phLdrMod Where to store the handle to the loader module.
Opens a binary image file using kLdr.

Returns:
iprt status code.
Parameters:
pszFilename Image filename.
phLdrMod Where to store the handle to the loaded module.
fFlags Reserved, MBZ.
enmArch CPU architecture specifier for the image to be loaded.
Remarks:
Primarily for testing the loader.
Open a binary image from in-memory bits.

Returns:
iprt status code.
Parameters:
pvBits The start of the raw-image.
cbBits The size of the raw-image.
enmBits What to expect from the pvBits.
pszLogName What to call the raw-image when logging. For RTLdrLoad and RTLdrOpen the filename is used for this.
phLdrMod Where to store the handle to the loader module.
Closes a loader module handle.

The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen() and RTLdrOpenBits() functions.

Returns:
iprt status code.
Parameters:
hLdrMod The loader module handle.
Gets the address of a named exported symbol.

Returns:
iprt status code.
Parameters:
hLdrMod The loader module handle.
pszSymbol Symbol name.
ppvValue Where to store the symbol value. Note that this is restricted to the pointer size used on the host!
Gets the address of a named exported symbol.

This function differs from the plain one in that it can deal with both GC and HC address sizes, and that it can calculate the symbol value relative to any given base address.

Returns:
iprt status code.
Parameters:
hLdrMod The loader module handle.
pvBits Optional pointer to the loaded image. Set this to NULL if no RTLdrGetBits() processed image bits are available. Not supported for RTLdrLoad() images.
BaseAddress Image load address. Not supported for RTLdrLoad() images.
pszSymbol Symbol name.
pValue Where to store the symbol value.
Loads the image into a buffer provided by the user and applies fixups for the given base address.

Returns:
iprt status code.
Parameters:
hLdrMod The load module handle.
pvBits Where to put the bits. Must be as large as RTLdrSize() suggests.
BaseAddress The base address.
pfnGetImport Callback function for resolving imports one by one.
pvUser User argument for the callback.
Remarks:
Not supported for RTLdrLoad() images.
Relocates bits after getting them. Useful for code which moves around a bit.

Returns:
iprt status code.
Parameters:
hLdrMod The loader module handle.
pvBits Where the image bits are. Must've been passed to RTLdrGetBits().
NewBaseAddress The new base address.
OldBaseAddress The old base address.
pfnGetImport Callback function for resolving imports one by one.
pvUser User argument for the callback.
Remarks:
Not supported for RTLdrLoad() images.
Enumerates all symbols in a module.

Returns:
iprt status code.
Parameters:
hLdrMod The loader module handle.
fFlags Flags indicating what to return and such.
pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*) Set this to NULL if no RTLdrGetBits() processed image bits are available.
BaseAddress Image load address.
pfnCallback Callback function.
pvUser User argument for the callback.
Remarks:
Not supported for RTLdrLoad() images.
Opens a sysfs file.

Returns:
The file descriptor. -1 and errno on failure.
Parameters:
pszFormat The name format, either absolute or relative to "/sys/".
... The format args.
Destroys a local IPC server.

Returns:
IPRT status code.
Parameters:
hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
Listen for clients.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success and *phClientSession containing the session handle.
VERR_CANCELLED if the listening was interrupted by RTLocalIpcServerCancel().
Parameters:
hServer The server handle.
phClientSession Where to store the client session handle on success.
Cancel the current or subsequent RTLocalIpcServerListen call.

Returns:
IPRT status code.
Parameters:
hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
Connects to a local IPC server.

This is used a client process (or thread).

Returns:
IPRT status code.
Parameters:
VINF_SUCCESS on success and *phSession holding the session handle.
phSession Where to store the sesson handle on success.
pszName The server name (see RTLocalIpcServerCreate for details).
fFlags Flags. Current undefined, pass 0.
Closes the local IPC session.

This can be used with sessions created by both RTLocalIpcSessionConnect and RTLocalIpcServerListen.

Returns:
IPRT status code.
Parameters:
hSession The session handle. The nil value is quietly ignored (VINF_SUCCESS).
Receive data from the other end of an local IPC session.

This will block if there isn't any data.

Returns:
IPRT status code.
Return values:
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
Parameters:
hSession The session handle.
pvBuffer Where to store the data.
cbBuffer If pcbRead is non-NULL this indicates the maximum number of bytes to read. If pcbRead is NULL the this is the exact number of bytes to read.
pcbRead Optional argument for indicating a partial read and returning the number of bytes actually read. This may return 0 on some implementations?
Send data to the other end of an local IPC session.

This may or may not block until the data is received by the other party, this is an implementation detail. If you want to make sure that the data has been received you should allways call RTLocalIpcSessionFlush().

Returns:
IPRT status code.
Return values:
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
Parameters:
hSession The session handle.
pvBuffer The data to write.
cbBuffer The number of bytes to write.
Flush any buffered data and (perhaps) wait for the other party to receive it.

The waiting for the other party to receive the data is implementation dependent.

Returns:
IPRT status code.
Return values:
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
Parameters:
hSession The session handle.
Wait for data to become read for reading or for the session to be disconnected.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS when there is data to read.
VERR_TIMEOUT if no data became available within the specified period (cMillies)
VERR_BROKEN_PIPE if the session was disconnected.
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
Parameters:
hSession The session handle.
cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT to wait forever.
Remarks:
VERR_INTERRUPTED will not be returned. If this is desired at some later point add a RTLocalIpcSessionWaitForDataNoResume() variant like we're using elsewhere.
Cancells a pending or subsequent operation.

Not all methods are cancellable, only those which are specfied returning VERR_CANCELLED. The others are assumed to not be blocking for ever and ever.

Returns:
IPRT status code.
Parameters:
hSession The session handle.
Query the process ID of the other party.

This is an optional feature which may not be implemented, so don't depend on it and check for VERR_NOT_SUPPORTED.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS and *pProcess on success.
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
VERR_NOT_SUPPORTED and *pProcess = NIL_RTPROCESS if not supported.
Parameters:
hSession The session handle.
pProcess Where to store the process ID.
Query the user ID of the other party.

This is an optional feature which may not be implemented, so don't depend on it and check for VERR_NOT_SUPPORTED.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS and *pUid on success.
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
VERR_NOT_SUPPORTED and *pUid = NIL_RTUID if not supported.
Parameters:
hSession The session handle.
pUid Where to store the user ID on success.
Query the group ID of the other party.

This is an optional feature which may not be implemented, so don't depend on it and check for VERR_NOT_SUPPORTED.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS and *pUid on success.
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
VERR_NOT_SUPPORTED and *pGid = NIL_RTUID if not supported.
Parameters:
hSession The session handle.
pGid Where to store the group ID on success.
Create a logger instance.

Returns:
iprt status code.
Parameters:
ppLogger Where to store the logger instance.
fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
pszGroupSettings The initial group settings.
pszEnvVarBase Base name for the environment variables for this instance.
cGroups Number of groups in the array.
papszGroups Pointer to array of groups. This must stick around for the life of the logger instance.
fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
cchErrorMsg The size of the error message buffer.
pszFilenameFmt Log filename format string. Standard RTStrFormat().
... Format arguments.
Create a logger instance.

Returns:
iprt status code.
Parameters:
ppLogger Where to store the logger instance.
fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
pszGroupSettings The initial group settings.
pszEnvVarBase Base name for the environment variables for this instance.
cGroups Number of groups in the array.
papszGroups Pointer to array of groups. This must stick around for the life of the logger instance.
fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
cchErrorMsg The size of the error message buffer.
pszFilenameFmt Log filename format string. Standard RTStrFormat().
args Format arguments.
Create a logger instance for singled threaded ring-0 usage.

Returns:
iprt status code.
Parameters:
pLogger Where to create the logger instance.
cbLogger The amount of memory available for the logger instance.
pfnLogger Pointer to logger wrapper function for the clone.
pfnFlush Pointer to flush function for the clone.
fFlags Logger instance flags for the clone, a combination of the RTLOGFLAGS_* values.
fDestFlags The destination flags.
Destroys a logger instance.

The instance is flushed and all output destinations closed (where applicable).

Returns:
iprt status code.
Parameters:
pLogger The logger instance which close destroyed. NULL is fine.
Create a logger instance clone for RC usage.

Returns:
iprt status code.
Parameters:
pLogger The logger instance to be cloned.
pLoggerRC Where to create the RC logger instance.
cbLoggerRC Amount of memory allocated to for the RC logger instance clone.
pfnLoggerRCPtr Pointer to logger wrapper function for this instance (RC Ptr).
pfnFlushRCPtr Pointer to flush function (RC Ptr).
fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
Sets the custom prefix callback.

Returns:
IPRT status code.
Parameters:
pLogger The logger instance.
pfnCallback The callback.
pvUser The user argument for the callback.
Copies the group settings and flags from logger instance to another.

Returns:
IPRT status code.
Parameters:
pDstLogger The destination logger instance.
pSrcLogger The source logger instance. If NULL the default one is used.
fFlagsOr OR mask for the flags.
fFlagsAnd AND mask for the flags.
Updates the group settings for the logger instance using the specified specification string.

Returns:
iprt status code. Failures can safely be ignored.
Parameters:
pLogger Logger instance (NULL for default logger).
pszVar Value to parse.
Updates the flags for the logger instance using the specified specification string.

Returns:
iprt status code. Failures can safely be ignored.
Parameters:
pLogger Logger instance (NULL for default logger).
pszVar Value to parse.
Destroys the specified pool, freeing all the memory it contains.

Returns:
IPRT status code.
Parameters:
hMemPool The handle to the pool. The nil handle and RTMEMPOOL_DEFAULT are quitely ignored (retval VINF_SUCCESS).
Converts a CPU identifier to a CPU set index.

This may or may not validate the presence of the CPU.

Returns:
The CPU set index on success, -1 on failure.
Parameters:
idCpu The identifier of the CPU.
Gets the current working directory of the process.

Returns:
IPRT status code.
Parameters:
pszPath Where to store the path.
cchPath The size of the buffer pszPath points to.
Get the real path (no symlinks, no . or .. components), must exist.

Returns:
iprt status code.
Parameters:
pszPath The path to resolve.
pszRealPath Where to store the real path.
cchRealPath Size of the buffer.
Get the absolute path (starts from root, no . or .. components), doesn't have to exist. Note that this method is designed to never perform actual file system access, therefore symlinks are not resolved.

Returns:
iprt status code.
Parameters:
pszPath The path to resolve.
pszAbsPath Where to store the absolute path.
cchAbsPath Size of the buffer.
Get the absolute path (no symlinks, no . or .. components), assuming the given base path as the current directory. The resulting path doesn't have to exist.

Returns:
iprt status code.
Parameters:
pszBase The base path to act like a current directory. When NULL, the actual cwd is used (i.e. the call is equivalent to RTPathAbs(pszPath, ...).
pszPath The path to resolve.
pszAbsPath Where to store the absolute path.
cchAbsPath Size of the buffer.
Compares two paths.

The comparison takes platform-dependent details into account, such as:

  • On DOS-like platforms, both separator chars (|\| and |/|) are considered to be equal.
  • On platforms with case-insensitive file systems, mismatching characters are uppercased and compared again.

Returns:
< 0 if the first path less than the second path.

0 if the first path identical to the second path.

> 0 if the first path greater than the second path.

Parameters:
pszPath1 Path to compare (must be an absolute path).
pszPath2 Path to compare (must be an absolute path).
Remarks:
File system details are currently ignored. This means that you won't get case-insentive compares on unix systems when a path goes into a case-insensitive filesystem like FAT, HPFS, HFS, NTFS, JFS, or similar. For NT, OS/2 and similar you'll won't get case-sensitve compares on a case-sensitive file system.
Appends one partial path to another.

The main purpose of this function is to deal correctly with the slashes when concatenating the two partial paths.

Return values:
VINF_SUCCESS on success.
VERR_BUFFER_OVERFLOW if the result is too big to fit within cbPathDst bytes. No changes has been made.
VERR_INVALID_PARAMETER if the string pointed to by pszPath is longer than cbPathDst-1 bytes (failed to find terminator). Asserted.
Parameters:
pszPath The path to append pszAppend to. This serves as both input and output. This can be empty, in which case pszAppend is just copied over.
cbPathDst The size of the buffer pszPath points to, terminator included. This should NOT be strlen(pszPath).
pszAppend The partial path to append to pszPath. This can be NULL, in which case nothing is done.
Remarks:
On OS/2, Window and similar systems, concatenating a drive letter specifier with a slash prefixed path will result in an absolute path. Meaning, RTPathAppend(strcpy(szBuf, "C:"), sizeof(szBuf), "/bar") will result in "C:/bar". (This follows directly from the behavior when pszPath is empty.)
On the other hand, when joining a drive letter specifier with a partial path that does not start with a slash, the result is not an absolute path. Meaning, RTPathAppend(strcpy(szBuf, "C:"), sizeof(szBuf), "bar") will result in "C:bar".

Create an instance of the default pseudo random number generator.

Returns:
IPRT status code.
Parameters:
phRand Where to store the handle to the generator.
Create an instance of the Park-Miller pseudo random number generator.

Returns:
IPRT status code.
Parameters:
phRand Where to store the handle to the generator.
Create an instance of the faster random number generator for the OS.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED on platforms which doesn't have this feature.
VERR_FILE_NOT_FOUND on system where the random generator hasn't been installed or configured correctly.
VERR_PATH_NOT_FOUND for the same reasons as VERR_FILE_NOT_FOUND.
Parameters:
phRand Where to store the handle to the generator.
Remarks:
Think /dev/urandom.
Create an instance of the truer random number generator for the OS.

Don't use this unless you seriously need good random numbers because most systems will have will have problems producing sufficient entropy for this and you'll end up blocking while it accumulates.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED on platforms which doesn't have this feature.
VERR_FILE_NOT_FOUND on system where the random generator hasn't been installed or configured correctly.
VERR_PATH_NOT_FOUND for the same reasons as VERR_FILE_NOT_FOUND.
Parameters:
phRand Where to store the handle to the generator.
Remarks:
Think /dev/random.
Destroys a random number generator.

Returns:
IPRT status code.
Parameters:
hRand Handle to the random number generator.
Generic method for seeding of a random number generator.

The different generators may have specialized methods for seeding, use one of those if you desire better control over ther result.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if it isn't a pseudo generator.
Parameters:
hRand Handle to the random number generator.
u64Seed Seed.
Save the current state of a pseudo generator.

This can be use to save the state so it can later be resumed at the same position.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success. *pcbState contains the length of the returned string and pszState contains the state string.
VERR_BUFFER_OVERFLOW if the supplied buffer is too small. *pcbState will contain the necessary buffer size.
VERR_NOT_SUPPORTED by non-psuedo generators.
Parameters:
hRand Handle to the random number generator.
pszState Where to store the state. The returned string will be null terminated and printable.
pcbState The size of the buffer pszState points to on input, the size required / used on return (including the terminator, thus the 'cb' instead of 'cch').
Restores the state of a pseudo generator.

The state must've been obtained using RTRandAdvGetState.

Returns:
IPRT status code.
Return values:
VERR_PARSE_ERROR if the state string is malformed.
VERR_NOT_SUPPORTED by non-psuedo generators.
Parameters:
hRand Handle to the random number generator.
pszState The state to load.
Destroy an event semaphore.

Returns:
iprt status code.
Parameters:
EventSem Handle of the
Signal an event semaphore.

The event semaphore will be signaled and automatically reset after exactly one thread have successfully returned from RTSemEventWait() after waiting/polling on that semaphore.

Returns:
iprt status code.
Parameters:
EventSem The event semaphore to signal.
Wait for the event semaphore to be signaled, resume on interruption.

This function will resume if the wait is interrupted by an async system event (like a unix signal) or similar.

Returns:
iprt status code. Will not return VERR_INTERRUPTED.
Parameters:
EventSem The event semaphore to wait on.
cMillies Number of milliseconds to wait.
Wait for the event semaphore to be signaled, return on interruption.

This function will not resume the wait if interrupted.

Returns:
iprt status code.
Parameters:
EventSem The event semaphore to wait on.
cMillies Number of milliseconds to wait.
Create a event multi semaphore.

Returns:
iprt status code.
Parameters:
pEventMultiSem Where to store the event multi semaphore handle.
Destroy an event multi semaphore.

Returns:
iprt status code.
Parameters:
EventMultiSem The event multi sempahore to destroy.
Signal an event multi semaphore.

Returns:
iprt status code.
Parameters:
EventMultiSem The event multi semaphore to signal.
Resets an event multi semaphore to non-signaled state.

Returns:
iprt status code.
Parameters:
EventMultiSem The event multi semaphore to reset.
Wait for the event multi semaphore to be signaled, resume on interruption.

This function will resume if the wait is interrupted by an async system event (like a unix signal) or similar.

Returns:
iprt status code. Will not return VERR_INTERRUPTED.
Parameters:
EventMultiSem The event multi semaphore to wait on.
cMillies Number of milliseconds to wait.
Wait for the event multi semaphore to be signaled, return on interruption.

This function will not resume the wait if interrupted.

Returns:
iprt status code.
Parameters:
EventMultiSem The event multi semaphore to wait on.
cMillies Number of milliseconds to wait.
Create a mutex semaphore.

Returns:
iprt status code.
Parameters:
pMutexSem Where to store the mutex semaphore handle.
Destroy a mutex semaphore.

Returns:
iprt status code.
Parameters:
MutexSem The mutex semaphore to destroy.
Request ownership of a mutex semaphore, resume on interruption.

This function will resume if the wait is interrupted by an async system event (like a unix signal) or similar.

The same thread may request a mutex semaphore multiple times, a nested counter is kept to make sure it's released on the right RTSemMutexRelease() call.

Returns:
iprt status code. Will not return VERR_INTERRUPTED.
Parameters:
MutexSem The mutex semaphore to request ownership over.
cMillies The number of milliseconds to wait.
Request ownership of a mutex semaphore, return on interruption.

This function will not resume the wait if interrupted.

The same thread may request a mutex semaphore multiple times, a nested counter is kept to make sure it's released on the right RTSemMutexRelease() call.

Returns:
iprt status code.
Parameters:
MutexSem The mutex semaphore to request ownership over.
cMillies The number of milliseconds to wait.
Release the ownership of a mutex semaphore.

Returns:
iprt status code.
Parameters:
MutexSem The mutex to release the ownership of. It goes without saying the the calling thread must own it.
Create a fast mutex semaphore.

Returns:
iprt status code.
Parameters:
pMutexSem Where to store the mutex semaphore handle.
Remarks:
Fast mutex semaphores are not recursive.
Destroy a fast mutex semaphore.

Returns:
iprt status code.
Parameters:
MutexSem The mutex semaphore to destroy.
Request ownership of a fast mutex semaphore.

The same thread may request a mutex semaphore multiple times, a nested counter is kept to make sure it's released on the right RTSemMutexRelease() call.

Returns:
iprt status code.
Parameters:
MutexSem The mutex semaphore to request ownership over.
Release the ownership of a fast mutex semaphore.

Returns:
iprt status code.
Parameters:
MutexSem The mutex to release the ownership of. It goes without saying the the calling thread must own it.
Creates a read/write semaphore.

Returns:
iprt status code.
Parameters:
pRWSem Where to store the handle to the created RW semaphore.
Destroys a read/write semaphore.

Returns:
iprt status code.
Parameters:
RWSem The Read/Write semaphore to destroy.
Request read access to a read/write semaphore, resume on interruption

Returns:
iprt status code.
Return values:
VINF_SUCCESS on success.
VERR_INTERRUPT if the wait was interrupted.
VERR_INVALID_HANDLE if RWSem is invalid.
Parameters:
RWSem The Read/Write semaphore to request read access to.
cMillies The number of milliseconds to wait.
Request read access to a read/write semaphore, return on interruption

Returns:
iprt status code.
Return values:
VINF_SUCCESS on success.
VERR_INTERRUPT if the wait was interrupted.
VERR_INVALID_HANDLE if RWSem is invalid.
Parameters:
RWSem The Read/Write semaphore to request read access to.
cMillies The number of milliseconds to wait.
Release read access to a read/write semaphore.

Returns:
iprt status code.
Parameters:
RWSem The Read/Write sempahore to release read access to. Goes without saying that caller must have read access to the sem.
Request write access to a read/write semaphore, resume on interruption.

Returns:
iprt status code.
Return values:
VINF_SUCCESS on success.
VERR_DEADLOCK if the caller owned the read lock.
VERR_INVALID_HANDLE if RWSem is invalid.
Parameters:
RWSem The Read/Write semaphore to request write access to.
cMillies The number of milliseconds to wait.
Request write access to a read/write semaphore, return on interruption.

Returns:
iprt status code.
Return values:
VINF_SUCCESS on success.
VERR_INTERRUPT if the wait was interrupted.
VERR_DEADLOCK if the caller owned the read lock.
VERR_INVALID_HANDLE if RWSem is invalid.
Parameters:
RWSem The Read/Write semaphore to request write access to.
cMillies The number of milliseconds to wait.
Release write access to a read/write semaphore.

Returns:
iprt status code.
Parameters:
RWSem The Read/Write sempahore to release read access to. Goes without saying that caller must have write access to the sem.
Init a Ping-Pong construct.

Returns:
iprt status code.
Parameters:
pPP Pointer to the ping-pong structure which needs initialization.
Deletes a Ping-Pong construct.

Returns:
iprt status code.
Parameters:
pPP Pointer to the ping-pong structure which is to be destroyed. (I.e. put into uninitialized state.)
Signals the pong thread in a ping-pong construct. (I.e. sends ping.) This is called by the ping thread.

Returns:
iprt status code.
Parameters:
pPP Pointer to the ping-pong structure to ping.
Signals the ping thread in a ping-pong construct. (I.e. sends pong.) This is called by the pong thread.

Returns:
iprt status code.
Parameters:
pPP Pointer to the ping-pong structure to pong.
Wait function for the ping thread.

Returns:
iprt status code. Will not return VERR_INTERRUPTED.
Parameters:
pPP Pointer to the ping-pong structure to wait on.
cMillies Number of milliseconds to wait.
Wait function for the pong thread.

Returns:
iprt status code. Will not return VERR_INTERRUPTED.
Parameters:
pPP Pointer to the ping-pong structure to wait on.
cMillies Number of milliseconds to wait.
Destroys a spinlock created by RTSpinlockCreate().

Returns:
iprt status code.
Parameters:
Spinlock Spinlock returned by RTSpinlockCreate().
Destroys a string cache.

This will cause all strings in the cache to be released and thus become invalid.

Returns:
IPRT status.
Parameters:
hStrCache Handle to the string cache. The nil and default handles are ignored quietly (VINF_SUCCESS).
Validates the UTF-8 encoding of the string.

Returns:
iprt status code.
Parameters:
psz The string.
Validates the UTF-8 encoding of the string.

Returns:
iprt status code.
Parameters:
psz The string.
cch The max string length. Use RTSTR_MAX to process the entire string.
fFlags Reserved for future. Pass 0.
Gets the number of code points the string is made up of, excluding the terminator.

This function will validate the string, and incorrectly encoded UTF-8 strings will be rejected.

Returns:
iprt status code.
Parameters:
psz The string.
cch The max string length. Use RTSTR_MAX to process the entire string.
pcuc Where to store the code point count. This is undefined on failure.
Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.

Returns:
iprt status code.
Parameters:
pszString UTF-8 string to convert.
ppUniString Receives pointer to the allocated unicode string. The returned string must be freed using RTUniFree().
Translates pszString from UTF-8 to an array of code points, allocating the result array if requested.

Returns:
iprt status code.
Parameters:
pszString UTF-8 string to convert.
cchString The maximum size in chars (the type) to convert. The conversion stop when it reaches cchString or the string terminator ('\0'). Use RTSTR_MAX to translate the entire string.
ppaCps If cCps is non-zero, this must either be pointing to pointer to a buffer of the specified size, or pointer to a NULL pointer. If *ppusz is NULL or cCps is zero a buffer of at least cCps items will be allocated to hold the translated string. If a buffer was requested it must be freed using RTUtf16Free().
cCps The number of code points in the unicode string. This includes the terminator.
pcCps Where to store the length of the translated string. (Optional) This field will be updated even on failure, however the value is only specified for the following two error codes. On VERR_BUFFER_OVERFLOW and VERR_NO_STR_MEMORY it contains the required buffer space.
Calculates the length of the string in RTUTF16 items.

This function will validate the string, and incorrectly encoded UTF-8 strings will be rejected.

Returns:
iprt status code.
Parameters:
psz The string.
cch The max string length. Use RTSTR_MAX to process the entire string.
pcwc Where to store the string length. Optional. This is undefined on failure.
Translate a UTF-8 string into a UTF-16 allocating the result buffer.

Returns:
iprt status code.
Parameters:
pszString UTF-8 string to convert.
ppwszString Receives pointer to the allocated UTF-16 string. The returned string must be freed using RTUtf16Free().
Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.

Returns:
iprt status code.
Parameters:
pszString UTF-8 string to convert.
cchString The maximum size in chars (the type) to convert. The conversion stop when it reaches cchString or the string terminator ('\0'). Use RTSTR_MAX to translate the entire string.
ppwsz If cwc is non-zero, this must either be pointing to pointer to a buffer of the specified size, or pointer to a NULL pointer. If *ppwsz is NULL or cwc is zero a buffer of at least cwc items will be allocated to hold the translated string. If a buffer was requested it must be freed using RTUtf16Free().
cwc The buffer size in RTUTF16s. This includes the terminator.
pcwc Where to store the length of the translated string. (Optional) This field will be updated even on failure, however the value is only specified for the following two error codes. On VERR_BUFFER_OVERFLOW and VERR_NO_STR_MEMORY it contains the required buffer space.
Get the unicode code point at the given string position.

Returns:
iprt status code

VERR_INVALID_UTF8_ENCODING if the encoding is invalid.

Parameters:
ppsz The string.
pCp Where to store the unicode code point. Stores RTUNICP_INVALID if the encoding is invalid.
Get the unicode code point at the given string position for a string of a given length.

Returns:
iprt status code
Return values:
VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
Parameters:
ppsz The string.
pcch Pointer to the length of the string. This will be decremented by the size of the code point.
pCp Where to store the unicode code point. Stores RTUNICP_INVALID if the encoding is invalid.
Formats an integer number according to the parameters.

Returns:
Length of the formatted number.
Parameters:
psz Pointer to output string buffer of sufficient size.
u64Value Value to format.
uiBase Number representation base.
cchWidth Width.
cchPrecision Precision.
fFlags Flags (NTFS_*).
Register a format handler for a type.

The format handler is used to handle 'R[type]' format types, where the argument in the vector is a pointer value (a bit restrictive, but keeps it simple).

The caller must ensure that no other thread will be making use of any of the dynamic formatting type facilities simultaneously with this call.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success.
VERR_ALREADY_EXISTS if the type has already been registered.
VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
Parameters:
pszType The type name.
pfnHandler The handler address. See FNRTSTRFORMATTYPE for details.
pvUser The user argument to pass to the handler. See RTStrFormatTypeSetUser for how to update this later.
Deregisters a format type.

The caller must ensure that no other thread will be making use of any of the dynamic formatting type facilities simultaneously with this call.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success.
VERR_FILE_NOT_FOUND if not found.
Parameters:
pszType The type to deregister.
Sets the user argument for a type.

This can be used if a user argument needs relocating in GC.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success.
VERR_FILE_NOT_FOUND if not found.
Parameters:
pszType The type to update.
pvUser The new user argument value.
Allocating string printf.

Returns:
The length of the string in the returned *ppszBuffer.

-1 on failure.

Parameters:
ppszBuffer Where to store the pointer to the allocated output buffer. The buffer should be freed using RTStrFree(). On failure *ppszBuffer will be set to NULL.
pszFormat The format string.
args The format argument.
Allocating string printf.

Returns:
The length of the string in the returned *ppszBuffer.

-1 on failure.

Parameters:
ppszBuffer Where to store the pointer to the allocated output buffer. The buffer should be freed using RTStrFree(). On failure *ppszBuffer will be set to NULL.
pszFormat The format string.
... The format argument.
Performs a case sensitive string compare between two UTF-8 strings.

Encoding errors are ignored by the current implementation. So, the only difference between this and the CRT strcmp function is the handling of NULL arguments.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
psz1 First UTF-8 string. Null is allowed.
psz2 Second UTF-8 string. Null is allowed.
Performs a case sensitive string compare between two UTF-8 strings, given a maximum string length.

Encoding errors are ignored by the current implementation. So, the only difference between this and the CRT strncmp function is the handling of NULL arguments.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
psz1 First UTF-8 string. Null is allowed.
psz2 Second UTF-8 string. Null is allowed.
cchMax The maximum string length
Performs a case insensitive string compare between two UTF-8 strings.

This is a simplified compare, as only the simplified lower/upper case folding specified by the unicode specs are used. It does not consider character pairs as they are used in some languages, just simple upper & lower case compares.

The result is the difference between the mismatching codepoints after they both have been lower cased.

If the string encoding is invalid the function will assert (strict builds) and use RTStrCmp for the remainder of the string.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
psz1 First UTF-8 string. Null is allowed.
psz2 Second UTF-8 string. Null is allowed.
Performs a case insensitive string compare between two UTF-8 strings, given a maximum string length.

This is a simplified compare, as only the simplified lower/upper case folding specified by the unicode specs are used. It does not consider character pairs as they are used in some languages, just simple upper & lower case compares.

The result is the difference between the mismatching codepoints after they both have been lower cased.

If the string encoding is invalid the function will assert (strict builds) and use RTStrCmp for the remainder of the string.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
psz1 First UTF-8 string. Null is allowed.
psz2 Second UTF-8 string. Null is allowed.
cchMax Maximum string length
Find the length of a zero-terminated byte string, given a max string length.

See also RTStrNLen.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS if the string has a length less than cchMax.
VERR_BUFFER_OVERFLOW if the end of the string wasn't found before cchMax was reached.
Parameters:
pszString The string.
cchMax The max string length.
pcch Where to store the string length excluding the terminator. This is set to cchMax if the terminator isn't found.
Converts a string representation of a number to a 64-bit unsigned number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu64 Where to store the converted number. (optional)
Converts a string representation of a number to a 64-bit unsigned number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VINF_SUCCESS 
VERR_NO_DIGITS 
VERR_TRAILING_SPACES 
VERR_TRAILING_CHARS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu64 Where to store the converted number. (optional)
Converts a string representation of a number to a 32-bit unsigned number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu32 Where to store the converted number. (optional)
Converts a string representation of a number to a 32-bit unsigned number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VINF_SUCCESS 
VERR_NO_DIGITS 
VERR_TRAILING_SPACES 
VERR_TRAILING_CHARS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu32 Where to store the converted number. (optional)
Converts a string representation of a number to a 16-bit unsigned number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu16 Where to store the converted number. (optional)
Converts a string representation of a number to a 16-bit unsigned number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VINF_SUCCESS 
VERR_NO_DIGITS 
VERR_TRAILING_SPACES 
VERR_TRAILING_CHARS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu16 Where to store the converted number. (optional)
Converts a string representation of a number to a 8-bit unsigned number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu8 Where to store the converted number. (optional)
Converts a string representation of a number to a 8-bit unsigned number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VINF_SUCCESS 
VERR_NO_DIGITS 
VERR_TRAILING_SPACES 
VERR_TRAILING_CHARS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu8 Where to store the converted number. (optional)
Converts a string representation of a number to a 64-bit signed number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi64 Where to store the converted number. (optional)
Converts a string representation of a number to a 64-bit signed number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VINF_SUCCESS 
VERR_TRAILING_CHARS 
VERR_TRAILING_SPACES 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi64 Where to store the converted number. (optional)
Converts a string representation of a number to a 32-bit signed number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi32 Where to store the converted number. (optional)
Converts a string representation of a number to a 32-bit signed number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VINF_SUCCESS 
VERR_TRAILING_CHARS 
VERR_TRAILING_SPACES 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi32 Where to store the converted number. (optional)
Converts a string representation of a number to a 16-bit signed number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi16 Where to store the converted number. (optional)
Converts a string representation of a number to a 16-bit signed number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VINF_SUCCESS 
VERR_TRAILING_CHARS 
VERR_TRAILING_SPACES 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi16 Where to store the converted number. (optional)
Converts a string representation of a number to a 8-bit signed number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi8 Where to store the converted number. (optional)
Converts a string representation of a number to a 8-bit signed number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VINF_SUCCESS 
VERR_TRAILING_CHARS 
VERR_TRAILING_SPACES 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi8 Where to store the converted number. (optional)
Destroys the string space. The caller supplies a callback which will be called for each of the string nodes in for freeing their memory and other resources.

Returns:
0 or what ever non-zero return value pfnCallback returned when aborting the destruction.
Parameters:
pStrSpace The space to insert it into.
pfnCallback The callback.
pvUser The user argument.
Enumerates the string space. The caller supplies a callback which will be called for each of the string nodes.

Returns:
0 or what ever non-zero return value pfnCallback returned when aborting the destruction.
Parameters:
pStrSpace The space to insert it into.
pfnCallback The callback.
pvUser The user argument.
Allocates a new copy of the specified UTF-16 string.

Returns:
iprt status code.
Parameters:
ppwszString Receives pointer of the allocated UTF-16 string. The returned pointer must be freed using RTUtf16Free().
pwszString UTF-16 string to duplicate.
cwcExtra Number of extra RTUTF16 items to allocate.
Remarks:
This function will not make any attempt to validate the encoding.
Performs a case sensitive string compare between two UTF-16 strings.

Returns:
< 0 if the first string less than the second string.s

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
pwsz1 First UTF-16 string. Null is allowed.
pwsz2 Second UTF-16 string. Null is allowed.
Remarks:
This function will not make any attempt to validate the encoding.
Performs a case insensitive string compare between two UTF-16 strings.

This is a simplified compare, as only the simplified lower/upper case folding specified by the unicode specs are used. It does not consider character pairs as they are used in some languages, just simple upper & lower case compares.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
pwsz1 First UTF-16 string. Null is allowed.
pwsz2 Second UTF-16 string. Null is allowed.
Performs a case insensitive string compare between two UTF-16 strings using the current locale of the process (if applicable).

This differs from RTUtf16ICmp() in that it will try, if a locale with the required data is available, to do a correct case-insensitive compare. It follows that it is more complex and thereby likely to be more expensive.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
pwsz1 First UTF-16 string. Null is allowed.
pwsz2 Second UTF-16 string. Null is allowed.
Translate a UTF-16 string into a UTF-8 allocating the result buffer.

Returns:
iprt status code.
Parameters:
pwszString UTF-16 string to convert.
ppszString Receives pointer of allocated UTF-8 string on success, and is always set to NULL on failure. The returned pointer must be freed using RTStrFree().
Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly sized buffer allocated by the function.

Returns:
iprt status code.
Parameters:
pwszString The UTF-16 string to convert.
cwcString The number of RTUTF16 items to translate from pwszString. The translation will stop when reaching cwcString or the terminator ('\0'). Use RTSTR_MAX to translate the entire string.
ppsz If cch is non-zero, this must either be pointing to a pointer to a buffer of the specified size, or pointer to a NULL pointer. If *ppsz is NULL or cch is zero a buffer of at least cch chars will be allocated to hold the translated string. If a buffer was requested it must be freed using RTUtf16Free().
cch The buffer size in chars (the type). This includes the terminator.
pcch Where to store the length of the translated string. (Optional) This field will be updated even on failure, however the value is only specified for the following two error codes. On VERR_BUFFER_OVERFLOW and VERR_NO_STR_MEMORY it contains the required buffer space.
Calculates the length of the UTF-16 string in UTF-8 chars (bytes).

This function will validate the string, and incorrectly encoded UTF-16 strings will be rejected.

Returns:
iprt status code.
Parameters:
pwsz The string.
cwc The max string length. Use RTSTR_MAX to process the entire string.
pcch Where to store the string length (in bytes). Optional. This is undefined on failure.
Get the unicode code point at the given string position.

Returns:
iprt status code.
Parameters:
ppwsz Pointer to the string pointer. This will be updated to point to the char following the current code point.
pCp Where to store the code point. RTUNICP_INVALID is stored here on failure.
Remarks:
This is an internal worker for RTUtf16GetCpEx().
Queries the total amount of RAM accessible to the system.

This figure should not include memory that is installed but not used, nor memory that will be slow to bring online. The definition of 'slow' here is slower than swapping out a MB of pages to disk.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS and *pcb on sucess.
VERR_ACCESS_DENIED if the information isn't accessible to the caller.
Parameters:
pcb Where to store the result (in bytes).
Queries the amount of RAM that is currently locked down or in some other way made impossible to virtualize within reasonably short time.

The purposes of this API is, when combined with RTSystemQueryTotalRam, to be able to determin an absolute max limit for how much fixed memory it is (theoretically) possible to allocate (or lock down).

The kind memory covered by this function includes:

  • locked (wired) memory - like for instance RTR0MemObjLockUser and RTR0MemObjLockKernel makes,
  • kernel pools and heaps - like for instance the ring-0 variant of RTMemAlloc taps into,
  • fixed (not pagable) kernel allocations - like for instance all the RTR0MemObjAlloc* functions makes,
  • any similar memory that isn't easily swapped out, discarded, or flushed to disk.

This works against the value returned by RTSystemQueryTotalRam, and the value reported by this function can never be larger than what a call to RTSystemQueryTotalRam returns.

The short time term here is relative to swapping to disk like in RTSystemQueryTotalRam. This could mean that (part of) the dirty buffers in the dynamic I/O cache could be included in the total. If the dynamic I/O cache isn't likely to either flush buffers when the load increases and put them back into normal circulation, they should be included in the memory accounted for here.

Return values:
VINF_SUCCESS and *pcb on sucess.
VERR_NOT_SUPPORTED if the information isn't available on the system in general. The caller must handle this scenario.
VERR_ACCESS_DENIED if the information isn't accessible to the caller.
Parameters:
pcb Where to store the result (in bytes).
Remarks:
This function could've been inverted and called RTSystemQueryAvailableRam, but that might give impression that it would be possible to allocate the amount of memory it indicates for a single purpose, something which would be very improbable on most systems.

We might have to add another output parameter to this function that indicates if some of the memory kinds listed above cannot be accounted for on the system and therefore is not include in the returned amount.

Create a new thread.

Returns:
iprt status code.
Parameters:
pThread Where to store the thread handle to the new thread. (optional)
pfnThread The thread function.
pvUser User argument.
cbStack The size of the stack for the new thread. Use 0 for the default stack size.
enmType The thread type. Used for deciding scheduling attributes of the thread.
fFlags Flags of the RTTHREADFLAGS type (ORed together).
pszName Thread name.
Remarks:
When called in Ring-0, this API will create a new kernel thread and not a thread in the context of the calling process.
Create a new thread.

Same as RTThreadCreate except the name is given in the RTStrPrintfV form.

Returns:
iprt status code.
Parameters:
pThread See RTThreadCreate.
pfnThread See RTThreadCreate.
pvUser See RTThreadCreate.
cbStack See RTThreadCreate.
enmType See RTThreadCreate.
fFlags See RTThreadCreate.
pszName Thread name format.
va Format arguments.
Create a new thread.

Same as RTThreadCreate except the name is given in the RTStrPrintf form.

Returns:
iprt status code.
Parameters:
pThread See RTThreadCreate.
pfnThread See RTThreadCreate.
pvUser See RTThreadCreate.
cbStack See RTThreadCreate.
enmType See RTThreadCreate.
fFlags See RTThreadCreate.
pszName Thread name format.
... Format arguments.
Changes the type of the specified thread.

Returns:
iprt status code.
Parameters:
Thread The thread which type should be changed.
enmType The new thread type.
Remarks:
In Ring-0 it only works if Thread == RTThreadSelf().
Wait for the thread to terminate, resume on interruption.

Returns:
iprt status code. Will not return VERR_INTERRUPTED.
Parameters:
Thread The thread to wait for.
cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for an indefinite wait.
prc Where to store the return code of the thread. Optional.
Wait for the thread to terminate, return on interruption.

Returns:
iprt status code.
Parameters:
Thread The thread to wait for.
cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for an indefinite wait.
prc Where to store the return code of the thread. Optional.
Sets the name of a thread.

Returns:
iprt status code.
Parameters:
Thread Thread handle of the thread to query the name of.
pszName The thread name.
Signal the user event.

Returns:
iprt status code.
Wait for the user event.

Returns:
iprt status code.
Parameters:
Thread The thread to wait for.
cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for an indefinite wait.
Wait for the user event, return on interruption.

Returns:
iprt status code.
Parameters:
Thread The thread to wait for.
cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for an indefinite wait.
Reset the user event.

Returns:
iprt status code.
Parameters:
Thread The thread to reset.
Pokes the thread.

This will signal the thread, attempting to interrupt whatever it's currently doing. This is *NOT* implemented on all platforms and may cause unresolved symbols during linking or VERR_NOT_IMPLEMENTED at runtime.

Returns:
IPRT status code.
Parameters:
hThread The thread to poke. This must not be the calling thread.
Create a suspended timer.

Returns:
iprt status code.
Return values:
VERR_NOT_SUPPORTED if an unsupported flag was specfied.
Parameters:
ppTimer Where to store the timer handle.
u64NanoInterval The interval between timer ticks specified in nanoseconds if it's a recurring timer. This is rounded to the fit the system timer granularity. For one shot timers, pass 0.
fFlags Timer flags.
pfnTimer Callback function which shall be scheduled for execution on every timer tick.
pvUser User argument for the callback.
See also:
RTTimerStart, RTTimerStop, RTTimerDestroy, RTTimerGetSystemGranularity
Stops and destroys a running timer.

Returns:
iprt status code.
Parameters:
pTimer Timer to stop and destroy. NULL is ok.
Stops an active timer.

Returns:
IPRT status code.
Return values:
VERR_INVALID_HANDLE if pTimer isn't valid.
VERR_TIMER_ACTIVE if the timer isn't suspended.
Parameters:
pTimer The timer to activate.
u64First The RTTimeSystemNanoTS() for when the timer should start firing (relative). If 0 is specified, the timer will fire ASAP.
See also:
RTTimerStop
Stops an active timer.

Returns:
IPRT status code.
Return values:
VERR_INVALID_HANDLE if pTimer isn't valid.
VERR_TIMER_SUSPENDED if the timer isn't active.
VERR_NOT_SUPPORTED if the IPRT implementation doesn't support stopping a timer.
Parameters:
pTimer The timer to suspend.
See also:
RTTimerStart
Requests a specific system timer granularity.

Successfull calls to this API must be coupled with the exact same number of calls to RTTimerReleaseSystemGranularity() in order to undo any changes made.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if the requested value isn't supported by the host platform or if the host platform doesn't support modifying the system timer granularity.
VERR_PERMISSION_DENIED if the caller doesn't have the necessary privilege to modify the system timer granularity.
Parameters:
u32Request The requested system timer granularity in nanoseconds.
pu32Granted Where to store the granted system granularity. This is the value that should be passed to RTTimerReleaseSystemGranularity(). It is what RTTimerGetSystemGranularity() would return immediately after the change was made.
The value differ from the request in two ways; rounding and scale. Meaning if your request is for 10.000.000 you might be granted 10.000.055 or 1.000.000.
See also:
RTTimerReleaseSystemGranularity, RTTimerGetSystemGranularity
Releases a system timer granularity grant acquired by RTTimerRequestSystemGranularity().

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if the host platform doesn't have any way of modifying the system timer granularity.
VERR_WRONG_ORDER if nobody call RTTimerRequestSystemGranularity() with the given grant value.
Parameters:
u32Granted The granted system granularity.
See also:
RTTimerRequestSystemGranularity
Create a recurring low resolution timer.

Returns:
iprt status code.
Parameters:
phTimerLR Where to store the timer handle.
uMilliesInterval Milliseconds between the timer ticks, at least 100 ms. If higher resolution is required use the other API.
pfnTimer Callback function which shall be scheduled for execution on every timer tick.
pvUser User argument for the callback.
See also:
RTTimerLRCreateEx, RTTimerLRDestroy, RTTimerLRStop
Create a suspended low resolution timer.

Returns:
iprt status code.
Return values:
VERR_NOT_SUPPORTED if an unsupported flag was specfied.
Parameters:
phTimerLR Where to store the timer handle.
u64NanoInterval The interval between timer ticks specified in nanoseconds if it's a recurring timer, the minimum for is 100000000 ns. For one shot timers, pass 0.
fFlags Timer flags. Same as RTTimerCreateEx.
pfnTimer Callback function which shall be scheduled for execution on every timer tick.
pvUser User argument for the callback.
See also:
RTTimerLRStart, RTTimerLRStop, RTTimerLRDestroy
Stops and destroys a running low resolution timer.

Returns:
iprt status code.
Parameters:
hTimerLR The low resolution timer to stop and destroy. NIL_RTTIMERLR is accepted.
Stops an active low resolution timer.

Returns:
IPRT status code.
Return values:
VERR_INVALID_HANDLE if pTimer isn't valid.
VERR_TIMER_ACTIVE if the timer isn't suspended.
Parameters:
hTimerLR The low resolution timer to activate.
u64First The RTTimeSystemNanoTS() for when the timer should start firing (relative), the minimum is 100000000 ns. If 0 is specified, the timer will fire ASAP.
See also:
RTTimerLRStop
Stops an active low resolution timer.

Returns:
IPRT status code.
Return values:
VERR_INVALID_HANDLE if pTimer isn't valid.
VERR_TIMER_SUSPENDED if the timer isn't active.
VERR_NOT_SUPPORTED if the IPRT implementation doesn't support stopping a timer.
Parameters:
hTimerLR The low resolution timer to suspend.
See also:
RTTimerLRStart
Makes null UUID value.

Returns:
iprt status code.
Parameters:
pUuid Where to store generated null uuid.
Compares two UUID values.

Returns:
0 if eq, < 0 or > 0.
Parameters:
pUuid1 First value to compare. NULL is treated like if RTUuidIsNull() return true.
pUuid2 Second value to compare. NULL is treated like if RTUuidIsNull() return true.
Compares a UUID value with a UUID string.

Note:
IPRT uses little endian byte ordering in the UUID integer fields. If you want to pass IPRT UUIDs in binary representation to other UUID libraries and expect to get exactly the same string representation as in IPRT, you need to convert the first three integer fields (one 32 bit value, two 16 bit values) separately to big endian (also called network byte order). Correspondingly, if you want to get the right result with UUIDs which are in big endian format, you need to convert them before using this function.
See also:
RTUUID::Gen
Returns:
0 if eq, < 0 or > 0.
Parameters:
pUuid1 First value to compare. NULL is not allowed.
pszString2 The 2nd UUID in string form. NULL of malformed string is not permitted.
Converts binary UUID to its string representation.

Note:
IPRT uses little endian byte ordering in the UUID integer fields. If you want to pass IPRT UUIDs in binary representation to other UUID libraries and expect to get exactly the same string representation as in IPRT, you need to convert the first three integer fields (one 32 bit value, two 16 bit values) separately to big endian (also called network byte order). Correspondingly, if you want to get the right result with UUIDs which are in big endian format, you need to convert them before using this function.
See also:
RTUUID::Gen
Returns:
iprt status code.
Parameters:
pUuid Uuid to convert.
pszString Where to store result string.
cchString pszString buffer length, must be >= RTUUID_STR_LENGTH.
Converts UUID from its string representation to binary format.

Note:
IPRT uses little endian byte ordering in the UUID integer fields. If you want to pass IPRT UUIDs in binary representation to other UUID libraries and expect to get exactly the same string representation as in IPRT, you need to convert the first three integer fields (one 32 bit value, two 16 bit values) separately to big endian (also called network byte order). Correspondingly, if you want to get the right result with UUIDs which are in big endian format, you need to convert them before using this function.
See also:
RTUUID::Gen
Returns:
iprt status code.
Parameters:
pUuid Where to store result Uuid.
pszString String with UUID text data.
Converts binary UUID to its UTF-16 string representation.

Note:
See note in RTUuidToStr.
See also:
RTUUID::Gen
Returns:
iprt status code.
Parameters:
pUuid Uuid to convert.
pwszString Where to store result string.
cwcString pszString buffer length, must be >= RTUUID_STR_LENGTH.
Converts UUID from its UTF-16 string representation to binary format.

Note:
See note in RTUuidFromStr.
See also:
RTUUID::Gen
Returns:
iprt status code.
Parameters:
pUuid Where to store result Uuid.
pwszString String with UUID text data.
Compresses a chunk of memory.

Returns:
iprt status code.
Parameters:
pZip The compressor instance.
pvBuf Pointer to buffer containing the bits to compress.
cbBuf Number of bytes to compress.
Finishes the compression. This will flush all data and terminate the compression data stream.

Returns:
iprt status code.
Parameters:
pZip The compressor instance.
Destroys the compressor instance.

Returns:
iprt status code.
Parameters:
pZip The compressor instance.
Create a decompressor instance.

Returns:
iprt status code.
Parameters:
ppZip Where to store the instance handle.
pvUser User argument which will be passed on to pfnOut and pfnIn.
pfnIn Callback for producing input for decompression.
Decompresses a chunk of memory.

Returns:
iprt status code.
Parameters:
pZip The decompressor instance.
pvBuf Where to store the decompressed data.
cbBuf Number of bytes to produce. If pcbWritten is set any number of bytes up to cbBuf might be returned.
pcbWritten Number of bytes actually written to the buffer. If NULL cbBuf number of bytes must be written.
Destroys the decompressor instance.

Returns:
iprt status code.
Parameters:
pZip The decompressor instance.
Destroy a request packet queueu

Returns:
iprt status code.
Parameters:
pQueue The request queue.
Process one or more request packets

Returns:
iprt status code.

VERR_TIMEOUT if cMillies was reached without the packet being added.

Parameters:
pQueue The request queue.
cMillies Number of milliseconds to wait for a pending request. Use RT_INDEFINITE_WAIT to only wait till one is added.
Initialize a critical section.

Returns:
iprt status code.
Parameters:
pCritSect Pointer to the critical section structure.
fFlags Flags, any combination of the RTCRITSECT_FLAGS #defines.
Create a cache for objects.

Returns:
iprt status code.
Parameters:
ppObjCache Where to store the pointer to the created cache.
cElements Number of elements the cache can hold. 0 if unlimited size.
cbElement Size of one element in bytes
fProt Protection flags for protecting cache against concurrent access from different threads. RTOBJCACHE_PROTECT_REQUEST to protect the request function. RTOBJCACHE_PROTECT_INSERT to protect the insert function.
Destroy a cache freeing allocated memory.

Returns:
iprt status code.
Parameters:
pCache Pointer to the cache.
Request an object from the cache.

Returns:
iprt status VERR_CACHE_EMPTY if cache is not unlimited and there is no object left in cache.
Parameters:
pCache Pointer to the cache to get an object from.
ppObj Where to store the pointer to the object.
Insert an object into the cache.

Returns:
iprt status code. VERR_CACHE_FULL if cache is not unlimited and there is no free entry left in cache.
Parameters:
pCache Pointer to the cache.
pObj Pointer to the object to insert.
Creates an empty address space.

Returns:
IPRT status code.
Parameters:
phDbgAs Where to store the address space handle on success.
FirstAddr The first address in the address space.
LastAddr The last address in the address space.
pszName The name of the address space.
Variant of RTDbgAsCreate that takes a name format string.

Returns:
IPRT status code.
Parameters:
phDbgAs Where to store the address space handle on success.
FirstAddr The first address in the address space.
LastAddr The last address in the address space.
pszNameFmt The name format of the address space.
va Format arguments.
Variant of RTDbgAsCreate that takes a name format string.

Returns:
IPRT status code.
Parameters:
phDbgAs Where to store the address space handle on success.
FirstAddr The first address in the address space.
LastAddr The last address in the address space.
pszNameFmt The name format of the address space.
... Format arguments.
Links a module into the address space at the give address.

The size of the mapping is determined using RTDbgModImageSize().

Returns:
IPRT status code.
Return values:
VERR_OUT_OF_RANGE if the specified address will put the module outside the address space.
VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
Parameters:
hDbgAs The address space handle.
hDbgMod The module handle of the module to be linked in.
ImageAddr The address to link the module at.
fFlags See RTDBGASLINK_FLAGS_*.
Links a segment into the address space at the give address.

The size of the mapping is determined using RTDbgModSegmentSize().

Returns:
IPRT status code.
Return values:
VERR_OUT_OF_RANGE if the specified address will put the module outside the address space.
VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
Parameters:
hDbgAs The address space handle.
hDbgMod The module handle.
iSeg The segment number (0-based) of the segment to be linked in.
SegAddr The address to link the segment at.
fFlags See RTDBGASLINK_FLAGS_*.
Unlinks all the mappings of a module from the address space.

Returns:
IPRT status code.
Return values:
VERR_NOT_FOUND if the module wasn't found.
Parameters:
hDbgAs The address space handle.
hDbgMod The module handle of the module to be unlinked.
Unlinks the mapping at the specified address.

Returns:
IPRT status code.
Return values:
VERR_NOT_FOUND if no module or segment is mapped at that address.
Parameters:
hDbgAs The address space handle.
Addr The address within the mapping to be unlinked.
Queries mapping module information by handle.

Returns:
IPRT status code.
Return values:
VERR_NOT_FOUND if no mapping was found at the specified address.
Parameters:
hDbgAs The address space handle.
Addr Address within the mapping of the module or segment.
phMod Where to the return the retained module handle. Optional.
pAddr Where to return the base address of the mapping. Optional.
piSeg Where to return the segment index. This is set to NIL if the entire module is mapped as a single mapping. Optional.
Queries mapping module information by name.

Returns:
IPRT status code.
Return values:
VERR_NOT_FOUND if no mapping was found at the specified address.
VERR_OUT_OF_RANGE if the name index was out of range.
Parameters:
hDbgAs The address space handle.
pszName The module name.
iName There can be more than one module by the same name in an address space. This argument indicates which is ment. (0 based)
phMod Where to the return the retained module handle.
Adds a symbol to a module in the address space.

Returns:
IPRT status code. See RTDbgModSymbolAdd for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if no module was found at the specified address.
VERR_NOT_SUPPORTED if the module interpret doesn't support adding custom symbols.
Parameters:
hDbgAs The address space handle.
pszSymbol The symbol name.
Addr The address of the symbol.
cb The size of the symbol.
fFlags Symbol flags.
piOrdinal Where to return the symbol ordinal on success. If the interpreter doesn't do ordinals, this will be set to UINT32_MAX. Optional
Query a symbol by address.

Returns:
IPRT status code. See RTDbgModSymbolAddr for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if the address couldn't be mapped to a module.
Parameters:
hDbgAs The address space handle.
Addr The address which closest symbol is requested.
poffDisp Where to return the distance between the symbol and address. Optional.
pSymInfo Where to return the symbol info.
Query a symbol by address.

Returns:
IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if the address couldn't be mapped to a module.
Parameters:
hDbgAs The address space handle.
Addr The address which closest symbol is requested.
poffDisp Where to return the distance between the symbol and address. Optional.
ppSymInfo Where to return the pointer to the allocated symbol info. Always set. Free with RTDbgSymbolFree.
Query a symbol by name.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if not found.
Parameters:
hDbgAs The address space handle.
pszSymbol The symbol name.
pSymInfo Where to return the symbol info.
Query a symbol by name.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if not found.
Parameters:
hDbgAs The address space handle.
pszSymbol The symbol name.
ppSymInfo Where to return the pointer to the allocated symbol info. Always set. Free with RTDbgSymbolFree.
Query a line number by address.

Returns:
IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if the address couldn't be mapped to a module.
Parameters:
hDbgAs The address space handle.
Addr The address which closest symbol is requested.
poffDisp Where to return the distance between the line number and address.
pLine Where to return the line number information.
Adds a line number to a module in the address space.

Returns:
IPRT status code. See RTDbgModSymbolAdd for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if no module was found at the specified address.
VERR_NOT_SUPPORTED if the module interpret doesn't support adding custom symbols.
Parameters:
hDbgAs The address space handle.
pszFile The file name.
uLineNo The line number.
Addr The address of the symbol.
piOrdinal Where to return the line number ordinal on success. If the interpreter doesn't do ordinals, this will be set to UINT32_MAX. Optional.
Query a line number by address.

Returns:
IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
Return values:
VERR_INVALID_HANDLE if hDbgAs is invalid.
VERR_NOT_FOUND if the address couldn't be mapped to a module.
Parameters:
hDbgAs The address space handle.
Addr The address which closest symbol is requested.
poffDisp Where to return the distance between the line number and address.
ppLine Where to return the pointer to the allocated line number info. Always set. Free with RTDbgLineFree.
Creates a module based on the default debug info container.

This can be used to manually load a module and its symbol. The primary user group is the debug info interpreters, which use this API to create an efficient debug info container behind the scenes and forward all queries to it once the info has been loaded.

Returns:
IPRT status code.
Parameters:
phDbgMod Where to return the module handle.
pszName The name of the module (mandatory).
cbSeg The size of initial segment. If zero, segments will have to be added manually using RTDbgModSegmentAdd.
fFlags Flags reserved for future extensions, MBZ for now.
Adds a segment to the module. Optional feature.

This method is intended used for manually constructing debug info for a module. The main usage is from other debug info interpreters that want to avoid writing a debug info database and instead uses the standard container behind the scenes.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if this feature isn't support by the debug info interpreter. This is a common return code.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
VERR_INVALID_PARAMETER if fFlags contains undefined flags.
VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
Parameters:
hDbgMod The module handle.
uRva The image relative address of the segment.
cb The size of the segment.
pszName The segment name. Does not normally need to be unique, although this is somewhat up to the debug interpreter to decide.
fFlags Segment flags. Reserved for future used, MBZ.
piSeg The segment index or NIL_RTDBGSEGIDX on input. The assigned segment index on successful return. Optional.
Query information about a segment.

This can be used together with RTDbgModSegmentCount to enumerate segments. The index starts a 0 and stops one below RTDbgModSegmentCount.

Returns:
IPRT status code.
Return values:
VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
VERR_INVALID_HANDLE if hDbgMod is invalid.
Parameters:
hDbgMod The module handle.
iSeg The segment index. No special segments.
pSegInfo Where to return the segment info. The RTDBGSEGMENT::Address member will be set to RTUINTPTR_MAX or the load address used at link time.
Adds a line number to the module.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if the module interpret doesn't support adding custom symbols. This is a common place occurance.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or short.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
Parameters:
hDbgMod The module handle.
pszSymbol The symbol name.
iSeg The segment index.
off The segment offset.
cb The size of the symbol. Can be zero, although this may depend somewhat on the debug interpreter.
fFlags Symbol flags. Reserved for the future, MBZ.
piOrdinal Where to return the symbol ordinal on success. If the interpreter doesn't do ordinals, this will be set to UINT32_MAX. Optional.
Queries symbol information by ordinal number.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
Parameters:
hDbgMod The module handle.
iOrdinal The symbol ordinal number. 0-based. The highest number is RTDbgModSymbolCount() - 1.
pSymInfo Where to store the symbol information.
Queries symbol information by ordinal number.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
Parameters:
hDbgMod The module handle.
iOrdinal The symbol ordinal number. 0-based. The highest number is RTDbgModSymbolCount() - 1.
ppSymInfo Where to store the pointer to the returned symbol information. Always set. Free with RTDbgSymbolFree.
Queries symbol information by address.

The returned symbol is what the debug info interpreter consideres the symbol most applicable to the specified address. This usually means a symbol with an address equal or lower than the requested.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
Parameters:
hDbgMod The module handle.
iSeg The segment number.
off The offset into the segment.
poffDisp Where to store the distance between the specified address and the returned symbol. Optional.
pSymInfo Where to store the symbol information.
Queries symbol information by address.

The returned symbol is what the debug info interpreter consideres the symbol most applicable to the specified address. This usually means a symbol with an address equal or lower than the requested.

Returns:
IPRT status code.
Return values:
VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
Parameters:
hDbgMod The module handle.
iSeg The segment index.
off The offset into the segment.
poffDisp Where to store the distance between the specified address and the returned symbol. Optional.
ppSymInfo Where to store the pointer to the returned symbol information. Always set. Free with RTDbgSymbolFree.
Queries symbol information by symbol name.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or short.
Parameters:
hDbgMod The module handle.
pszSymbol The symbol name.
pSymInfo Where to store the symbol information.
Queries symbol information by symbol name.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_SYMBOLS if there aren't any symbols.
VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or short.
VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
Parameters:
hDbgMod The module handle.
pszSymbol The symbol name.
ppSymInfo Where to store the pointer to the returned symbol information. Always set. Free with RTDbgSymbolFree.
Adds a line number to the module.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if the module interpret doesn't support adding custom symbols. This should be consider a normal response.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or empty.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
Parameters:
hDbgMod The module handle.
pszFile The file name.
uLineNo The line number.
iSeg The segment index.
off The segment offset.
piOrdinal Where to return the line number ordinal on success. If the interpreter doesn't do ordinals, this will be set to UINT32_MAX. Optional.
Queries line number information by ordinal number.

This can be used to enumerate the line numbers for the module. Use RTDbgModLineCount() to figure the end of the ordinals.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
VERR_DBG_LINE_NOT_FOUND if there is no line number with that ordinal.
VERR_INVALID_HANDLE if hDbgMod is invalid.
Parameters:
hDbgMod The module handle.
iOrdinal The line number ordinal number.
pLineInfo Where to store the information about the line number.
Queries line number information by ordinal number.

This can be used to enumerate the line numbers for the module. Use RTDbgModLineCount() to figure the end of the ordinals.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
VERR_DBG_LINE_NOT_FOUND if there is no line number with that ordinal.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_NO_MEMORY if RTDbgLineAlloc fails.
Parameters:
hDbgMod The module handle.
iOrdinal The line number ordinal number.
ppLineInfo Where to store the pointer to the returned line number information. Always set. Free with RTDbgLineFree.
Queries line number information by address.

The returned line number is what the debug info interpreter consideres the one most applicable to the specified address. This usually means a line number with an address equal or lower than the requested.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
Parameters:
hDbgMod The module handle.
iSeg The segment number.
off The offset into the segment.
poffDisp Where to store the distance between the specified address and the returned symbol. Optional.
pSymInfo Where to store the symbol information.
Queries line number information by address.

The returned line number is what the debug info interpreter consideres the one most applicable to the specified address. This usually means a line number with an address equal or lower than the requested.

Returns:
IPRT status code.
Return values:
VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
VERR_INVALID_HANDLE if hDbgMod is invalid.
VERR_DBG_INVALID_RVA if an image relative address is specified and it's not inside any of the segments defined by the module.
VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the end of the segment.
VERR_NO_MEMORY if RTDbgLineAlloc fails.
Parameters:
hDbgMod The module handle.
iSeg The segment number.
off The offset into the segment.
poffDisp Where to store the distance between the specified address and the returned symbol. Optional.
ppLineInfo Where to store the pointer to the returned line number information. Always set. Free with RTDbgLineFree.
Initialize the RTGetOpt state.

The passed in argument vector may be sorted if fFlags indicates that this is desired (to be implemented).

Returns:
VINF_SUCCESS, VERR_INVALID_PARAMETER or VERR_INVALID_POINTER.
Parameters:
pState The state.
argc Argument count, to be copied from what comes in with main().
argv Argument array, to be copied from what comes in with main(). This may end up being modified by the option/argument sorting.
paOptions Array of RTGETOPTDEF structures, which must specify what options are understood by the program.
cOptions Number of array items passed in with paOptions.
iFirst The argument to start with (in argv).
fFlags The flags. MBZ for now.
Command line argument parser, handling both long and short options and checking argument formats, if desired.

This is to be called in a loop until it returns 0 (meaning that all options were parsed) or a negative value (meaning that an error occured). How non-option arguments are dealt with depends on the flags passed to RTGetOptInit. The default (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to the argument string.

For example, for a program which takes the following options:

--optwithstring (or -s) and a string argument; --optwithint (or -i) and a 32-bit signed integer argument; --verbose (or -v) with no arguments,

code would look something like this:

int main(int argc, char **argv)
{
     RTR3Init();

     static const RTGETOPTDEF s_aOptions[] =
     {
         { "--optwithstring",    's', RTGETOPT_REQ_STRING },
         { "--optwithint",       'i', RTGETOPT_REQ_INT32 },
         { "--verbose",          'v', 0 },
     };

     int ch;
     RTGETOPTUNION ValueUnion;
     RTGETOPTSTATE GetState;
     RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
     while ((ch = RTGetOpt(&GetState, &ValueUnion)))
     {
         // for options that require an argument, ValueUnion has received the value
         switch (ch)
         {
             case 's': // --optwithstring or -s
                 // string argument, copy ValueUnion.psz
                 break;

             case 'i': // --optwithint or -i
                 // integer argument, copy ValueUnion.i32
                 break;

             case 'v': // --verbose or -v
                 g_fOptVerbose = true;
                 break;

             case VINF_GETOPT_NOT_OPTION:
                 // handle non-option argument in ValueUnion.psz.
                 break;

             default:
                 if (ch > 0)
                 {
                     if (RT_C_IS_GRAPH(ch))
                         Error("unhandled option: -%c\n", ch);
                     else
                         Error("unhandled option: %i\n", ch);
                 }
                 else if (ch == VERR_GETOPT_UNKNOWN_OPTION)
                     Error("unknown option: %s\n", ValueUnion.psz);
                 else if (ValueUnion.pDef)
                     Error("%s: %Rrs\n", ValueUnion.pDef->pszLong, ch);
                 else
                     Error("%Rrs\n", ch);
                 return 1;
         }
     }

     return 0;
}

Returns:
0 when done parsing.

the iShort value of the option. pState->pDef points to the option definition which matched.

IPRT error status on parse error.

VINF_GETOPT_NOT_OPTION when encountering a non-option argument and RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the argument string.

VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option. pValueUnion->psz points to the option string.

VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if a required argument (aka value) was missing for an option.

VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if argument (aka value) conversion failed.

Parameters:
pState The state previously initialized with RTGetOptInit.
pValueUnion Union with value; in the event of an error, psz member points to erroneous parameter; otherwise, for options that require an argument, this contains the value of that argument, depending on the type that is required.
Creates a handle table.

The handle table translates a 32-bit handle into an object pointer, optionally calling you back so you can retain the object without racing RTHandleTableFree.

Returns:
IPRT status code and on success a handle table handle will be stored at the location phHandleTable points at.
Parameters:
pHandleTable Where to store the handle table handle on success.
fFlags Flags, see RTHANDLETABLE_FLAGS_*.
uBase The handle base value. This is the value of the first handle to be returned.
cMax The max number of handles. When exceeded the RTHandleTableAlloc or RTHandleTableAllocWithCtx calls will fail. Note that this number will be rounded up to a multiple of the sub-table size, or if it's too close to UINT32_MAX it will be rounded down.
pfnRetain Optional retain callback that will be called from behind the lock (if any) during lookup.
pvUser The user argument to the retain callback.
A simplified version of the RTHandleTableCreateEx API.

It assumes a max of about 64K handles with 1 being the base. The table access will serialized (RTHANDLETABLE_FLAGS_LOCKED).

Returns:
IPRT status code and *phHandleTable.
Parameters:
pHandleTable Where to store the handle table handle on success.
Destroys a handle table.

If any entries are still in used the pfnDelete callback will be invoked on each of them (if specfied) to allow to you clean things up.

Returns:
IPRT status code
Parameters:
hHandleTable The handle to the handle table.
pfnDelete Function to be called back on each handle still in use. Optional.
pvUser The user argument to pfnDelete.
Allocates a handle from the handle table.

Returns:
IPRT status code, almost any.
Return values:
VINF_SUCCESS on success.
VERR_NO_MEMORY if we failed to extend the handle table.
VERR_NO_MORE_HANDLES if we're out of handles.
Parameters:
hHandleTable The handle to the handle table.
pvObj The object to associate with the new handle. This must be aligned on a 4 byte boundrary.
ph Where to return the handle on success.
Remarks:
Do not call this if RTHANDLETABLE_FLAGS_CONTEXT was used during creation.
Allocates a handle from the handle table.

Returns:
IPRT status code, almost any.
Return values:
VINF_SUCCESS on success.
VERR_NO_MEMORY if we failed to extend the handle table.
VERR_NO_MORE_HANDLES if we're out of handles.
Parameters:
hHandleTable The handle to the handle table.
pvObj The object to associate with the new handle. This must be aligned on a 4 byte boundrary.
pvCtx The context to associate with the new handle.
ph Where to return the handle on success.
Remarks:
Call this if RTHANDLETABLE_FLAGS_CONTEXT was used during creation.
Initializes the heap.

Returns:
IPRT status code on success.
Parameters:
pHeap Where to store the heap anchor block on success.
pvMemory Pointer to the heap memory.
cbMemory The size of the heap memory.
Merge two simple heaps into one.

The requiremet is of course that they next two each other memory wise.

Returns:
IPRT status code on success.
Parameters:
pHeap Where to store the handle to the merged heap on success.
Heap1 Handle to the first heap.
Heap2 Handle to the second heap.
Remarks:
This API isn't implemented yet.
Registers a termination callback.

This is intended for performing clean up during IPRT termination. Frequently paired with lazy initialization thru RTOnce.

The callbacks are called in LIFO order.

Returns:
IPRT status code.
Parameters:
pfnCallback The callback function.
pvUser The user argument for the callback.
Remarks:
May need to acquire a fast mutex or critical section, so use with some care in ring-0 context.

Be very careful using this from code that may be unloaded before IPRT terminates. Unlike some atexit and on_exit implementations, IPRT will not automatically unregister callbacks when a module gets unloaded.

Deregister a termination callback.

Returns:
VINF_SUCCESS if found, VERR_NOT_FOUND if the callback/pvUser pair wasn't found.
Parameters:
pfnCallback The callback function.
pvUser The user argument for the callback.
Create a local IPC server.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success and *phServer containg the instance handle.
Parameters:
phServer Where to put the server instance handle.
pszName The servier name. This must be unique and not include any special chars or slashes. It will be morphed into a unique platform specific identifier.
fFlags Flags, see RTLOCALIPC_FLAGS_*.
Destroys a local IPC server.

Returns:
IPRT status code.
Parameters:
hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
Listen for clients.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success and *phClientSession containing the session handle.
VERR_CANCELLED if the listening was interrupted by RTLocalIpcServerCancel().
Parameters:
hServer The server handle.
phClientSession Where to store the client session handle on success.
Cancel the current or subsequent RTLocalIpcServerListen call.

Returns:
IPRT status code.
Parameters:
hServer The server handle. The nil value is quietly ignored (VINF_SUCCESS).
Connects to a local IPC server.

This is used a client process (or thread).

Returns:
IPRT status code.
Parameters:
VINF_SUCCESS on success and *phSession holding the session handle.
phSession Where to store the sesson handle on success.
pszName The server name (see RTLocalIpcServerCreate for details).
fFlags Flags. Current undefined, pass 0.
Closes the local IPC session.

This can be used with sessions created by both RTLocalIpcSessionConnect and RTLocalIpcServerListen.

Returns:
IPRT status code.
Parameters:
hSession The session handle. The nil value is quietly ignored (VINF_SUCCESS).
Receive data from the other end of an local IPC session.

This will block if there isn't any data.

Returns:
IPRT status code.
Return values:
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
Parameters:
hSession The session handle.
pvBuffer Where to store the data.
cbBuffer If pcbRead is non-NULL this indicates the maximum number of bytes to read. If pcbRead is NULL the this is the exact number of bytes to read.
pcbRead Optional argument for indicating a partial read and returning the number of bytes actually read. This may return 0 on some implementations?
Send data to the other end of an local IPC session.

This may or may not block until the data is received by the other party, this is an implementation detail. If you want to make sure that the data has been received you should allways call RTLocalIpcSessionFlush().

Returns:
IPRT status code.
Return values:
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
Parameters:
hSession The session handle.
pvBuffer The data to write.
cbBuffer The number of bytes to write.
Flush any buffered data and (perhaps) wait for the other party to receive it.

The waiting for the other party to receive the data is implementation dependent.

Returns:
IPRT status code.
Return values:
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
Parameters:
hSession The session handle.
Wait for data to become read for reading or for the session to be disconnected.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS when there is data to read.
VERR_TIMEOUT if no data became available within the specified period (cMillies)
VERR_BROKEN_PIPE if the session was disconnected.
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
Parameters:
hSession The session handle.
cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT to wait forever.
Remarks:
VERR_INTERRUPTED will not be returned. If this is desired at some later point add a RTLocalIpcSessionWaitForDataNoResume() variant like we're using elsewhere.
Cancells a pending or subsequent operation.

Not all methods are cancellable, only those which are specfied returning VERR_CANCELLED. The others are assumed to not be blocking for ever and ever.

Returns:
IPRT status code.
Parameters:
hSession The session handle.
Query the process ID of the other party.

This is an optional feature which may not be implemented, so don't depend on it and check for VERR_NOT_SUPPORTED.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS and *pProcess on success.
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
VERR_NOT_SUPPORTED and *pProcess = NIL_RTPROCESS if not supported.
Parameters:
hSession The session handle.
pProcess Where to store the process ID.
Query the user ID of the other party.

This is an optional feature which may not be implemented, so don't depend on it and check for VERR_NOT_SUPPORTED.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS and *pUid on success.
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
VERR_NOT_SUPPORTED and *pUid = NIL_RTUID if not supported.
Parameters:
hSession The session handle.
pUid Where to store the user ID on success.
Query the group ID of the other party.

This is an optional feature which may not be implemented, so don't depend on it and check for VERR_NOT_SUPPORTED.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS and *pUid on success.
VERR_CANCELLED if the operation was cancelled by RTLocalIpcSessionCancel.
VERR_NOT_SUPPORTED and *pGid = NIL_RTUID if not supported.
Parameters:
hSession The session handle.
pGid Where to store the group ID on success.
Create a logger instance.

Returns:
iprt status code.
Parameters:
ppLogger Where to store the logger instance.
fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
pszGroupSettings The initial group settings.
pszEnvVarBase Base name for the environment variables for this instance.
cGroups Number of groups in the array.
papszGroups Pointer to array of groups. This must stick around for the life of the logger instance.
fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
pszFilenameFmt Log filename format string. Standard RTStrFormat().
... Format arguments.
Create a logger instance.

Returns:
iprt status code.
Parameters:
ppLogger Where to store the logger instance.
fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
pszGroupSettings The initial group settings.
pszEnvVarBase Base name for the environment variables for this instance.
cGroups Number of groups in the array.
papszGroups Pointer to array of groups. This must stick around for the life of the logger instance.
fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
cchErrorMsg The size of the error message buffer.
pszFilenameFmt Log filename format string. Standard RTStrFormat().
... Format arguments.
Create a logger instance.

Returns:
iprt status code.
Parameters:
ppLogger Where to store the logger instance.
fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
pszGroupSettings The initial group settings.
pszEnvVarBase Base name for the environment variables for this instance.
cGroups Number of groups in the array.
papszGroups Pointer to array of groups. This must stick around for the life of the logger instance.
fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
cchErrorMsg The size of the error message buffer.
pszFilenameFmt Log filename format string. Standard RTStrFormat().
args Format arguments.
Create a logger instance for singled threaded ring-0 usage.

Returns:
iprt status code.
Parameters:
pLogger Where to create the logger instance.
cbLogger The amount of memory available for the logger instance.
pfnLogger Pointer to logger wrapper function for the clone.
pfnFlush Pointer to flush function for the clone.
fFlags Logger instance flags for the clone, a combination of the RTLOGFLAGS_* values.
fDestFlags The destination flags.
Destroys a logger instance.

The instance is flushed and all output destinations closed (where applicable).

Returns:
iprt status code.
Parameters:
pLogger The logger instance which close destroyed. NULL is fine.
Create a logger instance clone for RC usage.

Returns:
iprt status code.
Parameters:
pLogger The logger instance to be cloned.
pLoggerRC Where to create the RC logger instance.
cbLoggerRC Amount of memory allocated to for the RC logger instance clone.
pfnLoggerRCPtr Pointer to logger wrapper function for this instance (RC Ptr).
pfnFlushRCPtr Pointer to flush function (RC Ptr).
fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
Sets the custom prefix callback.

Returns:
IPRT status code.
Parameters:
pLogger The logger instance.
pfnCallback The callback.
pvUser The user argument for the callback.
Copies the group settings and flags from logger instance to another.

Returns:
IPRT status code.
Parameters:
pDstLogger The destination logger instance.
pSrcLogger The source logger instance. If NULL the default one is used.
fFlagsOr OR mask for the flags.
fFlagsAnd AND mask for the flags.
Updates the group settings for the logger instance using the specified specification string.

Returns:
iprt status code. Failures can safely be ignored.
Parameters:
pLogger Logger instance (NULL for default logger).
pszVar Value to parse.
Updates the flags for the logger instance using the specified specification string.

Returns:
iprt status code. Failures can safely be ignored.
Parameters:
pLogger Logger instance (NULL for default logger).
pszVar Value to parse.
Change the page level protection of a memory region.

Returns:
iprt status code.
Parameters:
pv Start of the region. Will be rounded down to nearest page boundary.
cb Size of the region. Will be rounded up to the nearest page boundary.
fProtect The new protection, a combination of the RTMEM_PROT_* defines.
Creates a new memory pool.

Returns:
IPRT status code.
Parameters:
phMemPool Where to return the handle to the new memory pool.
pszName The name of the pool (for debug purposes).
Destroys the specified pool, freeing all the memory it contains.

Returns:
IPRT status code.
Parameters:
hMemPool The handle to the pool. The nil handle and RTMEMPOOL_DEFAULT are quitely ignored (retval VINF_SUCCESS).
Serializes execution of the pfnOnce function, making sure it's executed exactly once and that nobody returns from RTOnce before it has executed successfully.

Returns:
IPRT like status code returned by pfnOnce.
Parameters:
pOnce Pointer to the execute once variable.
pfnOnce The function to executed once.
pvUser1 The first user parameter for pfnOnce.
pvUser2 The second user parameter for pfnOnce.
Create a new string cache.

Returns:
IPRT status code
Parameters:
phStrCache Where to return the string cache handle.
pszName The name of the cache (for debug purposes).
Destroys a string cache.

This will cause all strings in the cache to be released and thus become invalid.

Returns:
IPRT status.
Parameters:
hStrCache Handle to the string cache. The nil and default handles are ignored quietly (VINF_SUCCESS).
Allocates a new copy of the given UTF-8 string.

Returns:
iprt status code.
Parameters:
ppszString Receives pointer of the allocated UTF-8 string. The returned pointer must be freed using RTStrFree().
pszString UTF-8 string to duplicate.
Validates the UTF-8 encoding of the string.

Returns:
iprt status code.
Parameters:
psz The string.
Validates the UTF-8 encoding of the string.

Returns:
iprt status code.
Parameters:
psz The string.
cch The max string length. Use RTSTR_MAX to process the entire string.
fFlags Reserved for future. Pass 0.
Gets the number of code points the string is made up of, excluding the terminator.

This function will validate the string, and incorrectly encoded UTF-8 strings will be rejected.

Returns:
iprt status code.
Parameters:
psz The string.
cch The max string length. Use RTSTR_MAX to process the entire string.
pcuc Where to store the code point count. This is undefined on failure.
Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.

Returns:
iprt status code.
Parameters:
pszString UTF-8 string to convert.
ppUniString Receives pointer to the allocated unicode string. The returned string must be freed using RTUniFree().
Translates pszString from UTF-8 to an array of code points, allocating the result array if requested.

Returns:
iprt status code.
Parameters:
pszString UTF-8 string to convert.
cchString The maximum size in chars (the type) to convert. The conversion stop when it reaches cchString or the string terminator ('\0'). Use RTSTR_MAX to translate the entire string.
ppaCps If cCps is non-zero, this must either be pointing to pointer to a buffer of the specified size, or pointer to a NULL pointer. If *ppusz is NULL or cCps is zero a buffer of at least cCps items will be allocated to hold the translated string. If a buffer was requested it must be freed using RTUtf16Free().
cCps The number of code points in the unicode string. This includes the terminator.
pcCps Where to store the length of the translated string. (Optional) This field will be updated even on failure, however the value is only specified for the following two error codes. On VERR_BUFFER_OVERFLOW and VERR_NO_STR_MEMORY it contains the required buffer space.
Calculates the length of the string in RTUTF16 items.

This function will validate the string, and incorrectly encoded UTF-8 strings will be rejected.

Returns:
iprt status code.
Parameters:
psz The string.
cch The max string length. Use RTSTR_MAX to process the entire string.
pcwc Where to store the string length. Optional. This is undefined on failure.
Translate a UTF-8 string into a UTF-16 allocating the result buffer.

Returns:
iprt status code.
Parameters:
pszString UTF-8 string to convert.
ppwszString Receives pointer to the allocated UTF-16 string. The returned string must be freed using RTUtf16Free().
Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.

Returns:
iprt status code.
Parameters:
pszString UTF-8 string to convert.
cchString The maximum size in chars (the type) to convert. The conversion stop when it reaches cchString or the string terminator ('\0'). Use RTSTR_MAX to translate the entire string.
ppwsz If cwc is non-zero, this must either be pointing to pointer to a buffer of the specified size, or pointer to a NULL pointer. If *ppwsz is NULL or cwc is zero a buffer of at least cwc items will be allocated to hold the translated string. If a buffer was requested it must be freed using RTUtf16Free().
cwc The buffer size in RTUTF16s. This includes the terminator.
pcwc Where to store the length of the translated string. (Optional) This field will be updated even on failure, however the value is only specified for the following two error codes. On VERR_BUFFER_OVERFLOW and VERR_NO_STR_MEMORY it contains the required buffer space.
Get the unicode code point at the given string position.

Returns:
iprt status code

VERR_INVALID_UTF8_ENCODING if the encoding is invalid.

Parameters:
ppsz The string.
pCp Where to store the unicode code point. Stores RTUNICP_INVALID if the encoding is invalid.
Get the unicode code point at the given string position for a string of a given length.

Returns:
iprt status code
Return values:
VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
Parameters:
ppsz The string.
pcch Pointer to the length of the string. This will be decremented by the size of the code point.
pCp Where to store the unicode code point. Stores RTUNICP_INVALID if the encoding is invalid.
Formats an integer number according to the parameters.

Returns:
Length of the formatted number.
Parameters:
psz Pointer to output string buffer of sufficient size.
u64Value Value to format.
uiBase Number representation base.
cchWidth Width.
cchPrecision Precision.
fFlags Flags (NTFS_*).
Register a format handler for a type.

The format handler is used to handle 'R[type]' format types, where the argument in the vector is a pointer value (a bit restrictive, but keeps it simple).

The caller must ensure that no other thread will be making use of any of the dynamic formatting type facilities simultaneously with this call.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success.
VERR_ALREADY_EXISTS if the type has already been registered.
VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
Parameters:
pszType The type name.
pfnHandler The handler address. See FNRTSTRFORMATTYPE for details.
pvUser The user argument to pass to the handler. See RTStrFormatTypeSetUser for how to update this later.
Deregisters a format type.

The caller must ensure that no other thread will be making use of any of the dynamic formatting type facilities simultaneously with this call.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success.
VERR_FILE_NOT_FOUND if not found.
Parameters:
pszType The type to deregister.
Sets the user argument for a type.

This can be used if a user argument needs relocating in GC.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success.
VERR_FILE_NOT_FOUND if not found.
Parameters:
pszType The type to update.
pvUser The new user argument value.
Allocating string printf.

Returns:
The length of the string in the returned *ppszBuffer.

-1 on failure.

Parameters:
ppszBuffer Where to store the pointer to the allocated output buffer. The buffer should be freed using RTStrFree(). On failure *ppszBuffer will be set to NULL.
pszFormat The format string.
args The format argument.
Allocating string printf.

Returns:
The length of the string in the returned *ppszBuffer.

-1 on failure.

Parameters:
ppszBuffer Where to store the pointer to the allocated output buffer. The buffer should be freed using RTStrFree(). On failure *ppszBuffer will be set to NULL.
pszFormat The format string.
... The format argument.
Performs a case sensitive string compare between two UTF-8 strings.

Encoding errors are ignored by the current implementation. So, the only difference between this and the CRT strcmp function is the handling of NULL arguments.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
psz1 First UTF-8 string. Null is allowed.
psz2 Second UTF-8 string. Null is allowed.
Performs a case sensitive string compare between two UTF-8 strings, given a maximum string length.

Encoding errors are ignored by the current implementation. So, the only difference between this and the CRT strncmp function is the handling of NULL arguments.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
psz1 First UTF-8 string. Null is allowed.
psz2 Second UTF-8 string. Null is allowed.
cchMax The maximum string length
Performs a case insensitive string compare between two UTF-8 strings.

This is a simplified compare, as only the simplified lower/upper case folding specified by the unicode specs are used. It does not consider character pairs as they are used in some languages, just simple upper & lower case compares.

The result is the difference between the mismatching codepoints after they both have been lower cased.

If the string encoding is invalid the function will assert (strict builds) and use RTStrCmp for the remainder of the string.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
psz1 First UTF-8 string. Null is allowed.
psz2 Second UTF-8 string. Null is allowed.
Performs a case insensitive string compare between two UTF-8 strings, given a maximum string length.

This is a simplified compare, as only the simplified lower/upper case folding specified by the unicode specs are used. It does not consider character pairs as they are used in some languages, just simple upper & lower case compares.

The result is the difference between the mismatching codepoints after they both have been lower cased.

If the string encoding is invalid the function will assert (strict builds) and use RTStrCmp for the remainder of the string.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
psz1 First UTF-8 string. Null is allowed.
psz2 Second UTF-8 string. Null is allowed.
cchMax Maximum string length
Find the length of a zero-terminated byte string, given a max string length.

See also RTStrNLen.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS if the string has a length less than cchMax.
VERR_BUFFER_OVERFLOW if the end of the string wasn't found before cchMax was reached.
Parameters:
pszString The string.
cchMax The max string length.
pcch Where to store the string length excluding the terminator. This is set to cchMax if the terminator isn't found.
Converts a string representation of a number to a 64-bit unsigned number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu64 Where to store the converted number. (optional)
Converts a string representation of a number to a 64-bit unsigned number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VINF_SUCCESS 
VERR_NO_DIGITS 
VERR_TRAILING_SPACES 
VERR_TRAILING_CHARS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu64 Where to store the converted number. (optional)
Converts a string representation of a number to a 32-bit unsigned number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu32 Where to store the converted number. (optional)
Converts a string representation of a number to a 32-bit unsigned number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VINF_SUCCESS 
VERR_NO_DIGITS 
VERR_TRAILING_SPACES 
VERR_TRAILING_CHARS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu32 Where to store the converted number. (optional)
Converts a string representation of a number to a 16-bit unsigned number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu16 Where to store the converted number. (optional)
Converts a string representation of a number to a 16-bit unsigned number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VINF_SUCCESS 
VERR_NO_DIGITS 
VERR_TRAILING_SPACES 
VERR_TRAILING_CHARS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu16 Where to store the converted number. (optional)
Converts a string representation of a number to a 8-bit unsigned number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu8 Where to store the converted number. (optional)
Converts a string representation of a number to a 8-bit unsigned number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_NEGATIVE_UNSIGNED 
VINF_SUCCESS 
VERR_NO_DIGITS 
VERR_TRAILING_SPACES 
VERR_TRAILING_CHARS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pu8 Where to store the converted number. (optional)
Converts a string representation of a number to a 64-bit signed number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi64 Where to store the converted number. (optional)
Converts a string representation of a number to a 64-bit signed number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VINF_SUCCESS 
VERR_TRAILING_CHARS 
VERR_TRAILING_SPACES 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi64 Where to store the converted number. (optional)
Converts a string representation of a number to a 32-bit signed number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi32 Where to store the converted number. (optional)
Converts a string representation of a number to a 32-bit signed number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VINF_SUCCESS 
VERR_TRAILING_CHARS 
VERR_TRAILING_SPACES 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi32 Where to store the converted number. (optional)
Converts a string representation of a number to a 16-bit signed number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi16 Where to store the converted number. (optional)
Converts a string representation of a number to a 16-bit signed number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VINF_SUCCESS 
VERR_TRAILING_CHARS 
VERR_TRAILING_SPACES 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi16 Where to store the converted number. (optional)
Converts a string representation of a number to a 8-bit signed number.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VWRN_TRAILING_CHARS 
VWRN_TRAILING_SPACES 
VINF_SUCCESS 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
ppszNext Where to store the pointer to the first char following the number. (Optional)
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi8 Where to store the converted number. (optional)
Converts a string representation of a number to a 8-bit signed number, making sure the full string is converted.

Returns:
iprt status code. Warnings are used to indicate conversion problems.
Return values:
VWRN_NUMBER_TOO_BIG 
VINF_SUCCESS 
VERR_TRAILING_CHARS 
VERR_TRAILING_SPACES 
VERR_NO_DIGITS 
Parameters:
pszValue Pointer to the string value.
uBase The base of the representation used. If 0 the function will look for known prefixes before defaulting to 10.
pi8 Where to store the converted number. (optional)
Destroys the string space. The caller supplies a callback which will be called for each of the string nodes in for freeing their memory and other resources.

Returns:
0 or what ever non-zero return value pfnCallback returned when aborting the destruction.
Parameters:
pStrSpace The space to insert it into.
pfnCallback The callback.
pvUser The user argument.
Enumerates the string space. The caller supplies a callback which will be called for each of the string nodes.

Returns:
0 or what ever non-zero return value pfnCallback returned when aborting the destruction.
Parameters:
pStrSpace The space to insert it into.
pfnCallback The callback.
pvUser The user argument.
Allocates a new copy of the specified UTF-16 string.

Returns:
iprt status code.
Parameters:
ppwszString Receives pointer of the allocated UTF-16 string. The returned pointer must be freed using RTUtf16Free().
pwszString UTF-16 string to duplicate.
cwcExtra Number of extra RTUTF16 items to allocate.
Remarks:
This function will not make any attempt to validate the encoding.
Performs a case sensitive string compare between two UTF-16 strings.

Returns:
< 0 if the first string less than the second string.s

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
pwsz1 First UTF-16 string. Null is allowed.
pwsz2 Second UTF-16 string. Null is allowed.
Remarks:
This function will not make any attempt to validate the encoding.
Performs a case insensitive string compare between two UTF-16 strings.

This is a simplified compare, as only the simplified lower/upper case folding specified by the unicode specs are used. It does not consider character pairs as they are used in some languages, just simple upper & lower case compares.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
pwsz1 First UTF-16 string. Null is allowed.
pwsz2 Second UTF-16 string. Null is allowed.
Performs a case insensitive string compare between two UTF-16 strings using the current locale of the process (if applicable).

This differs from RTUtf16ICmp() in that it will try, if a locale with the required data is available, to do a correct case-insensitive compare. It follows that it is more complex and thereby likely to be more expensive.

Returns:
< 0 if the first string less than the second string.

0 if the first string identical to the second string.

> 0 if the first string greater than the second string.

Parameters:
pwsz1 First UTF-16 string. Null is allowed.
pwsz2 Second UTF-16 string. Null is allowed.
Translate a UTF-16 string into a UTF-8 allocating the result buffer.

Returns:
iprt status code.
Parameters:
pwszString UTF-16 string to convert.
ppszString Receives pointer of allocated UTF-8 string on success, and is always set to NULL on failure. The returned pointer must be freed using RTStrFree().
Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly sized buffer allocated by the function.

Returns:
iprt status code.
Parameters:
pwszString The UTF-16 string to convert.
cwcString The number of RTUTF16 items to translate from pwszString. The translation will stop when reaching cwcString or the terminator ('\0'). Use RTSTR_MAX to translate the entire string.
ppsz If cch is non-zero, this must either be pointing to a pointer to a buffer of the specified size, or pointer to a NULL pointer. If *ppsz is NULL or cch is zero a buffer of at least cch chars will be allocated to hold the translated string. If a buffer was requested it must be freed using RTUtf16Free().
cch The buffer size in chars (the type). This includes the terminator.
pcch Where to store the length of the translated string. (Optional) This field will be updated even on failure, however the value is only specified for the following two error codes. On VERR_BUFFER_OVERFLOW and VERR_NO_STR_MEMORY it contains the required buffer space.
Calculates the length of the UTF-16 string in UTF-8 chars (bytes).

This function will validate the string, and incorrectly encoded UTF-16 strings will be rejected.

Returns:
iprt status code.
Parameters:
pwsz The string.
cwc The max string length. Use RTSTR_MAX to process the entire string.
pcch Where to store the string length (in bytes). Optional. This is undefined on failure.
Get the unicode code point at the given string position.

Returns:
iprt status code.
Parameters:
ppwsz Pointer to the string pointer. This will be updated to point to the char following the current code point.
pCp Where to store the code point. RTUNICP_INVALID is stored here on failure.
Remarks:
This is an internal worker for RTUtf16GetCpEx().
Queries information about the OS.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS on success.
VERR_INVALID_PARAMETER if enmInfo is invalid.
VERR_INVALID_POINTER if pszInfoStr is invalid.
VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will contain the chopped off result in this case, provided cchInfo isn't 0.
VERR_NOT_SUPPORTED if the info level isn't implemented. The buffer will contain an empty string.
Parameters:
enmInfo The OS info level.
pszInfo Where to store the result.
cchInfo The size of the output buffer.
Queries the total amount of RAM accessible to the system.

This figure should not include memory that is installed but not used, nor memory that will be slow to bring online. The definition of 'slow' here is slower than swapping out a MB of pages to disk.

Returns:
IPRT status code.
Return values:
VINF_SUCCESS and *pcb on sucess.
VERR_ACCESS_DENIED if the information isn't accessible to the caller.
Parameters:
pcb Where to store the result (in bytes).
Queries the amount of RAM that is currently locked down or in some other way made impossible to virtualize within reasonably short time.

The purposes of this API is, when combined with RTSystemQueryTotalRam, to be able to determin an absolute max limit for how much fixed memory it is (theoretically) possible to allocate (or lock down).

The kind memory covered by this function includes:

  • locked (wired) memory - like for instance RTR0MemObjLockUser and RTR0MemObjLockKernel makes,
  • kernel pools and heaps - like for instance the ring-0 variant of RTMemAlloc taps into,
  • fixed (not pagable) kernel allocations - like for instance all the RTR0MemObjAlloc* functions makes,
  • any similar memory that isn't easily swapped out, discarded, or flushed to disk.

This works against the value returned by RTSystemQueryTotalRam, and the value reported by this function can never be larger than what a call to RTSystemQueryTotalRam returns.

The short time term here is relative to swapping to disk like in RTSystemQueryTotalRam. This could mean that (part of) the dirty buffers in the dynamic I/O cache could be included in the total. If the dynamic I/O cache isn't likely to either flush buffers when the load increases and put them back into normal circulation, they should be included in the memory accounted for here.

Return values:
VINF_SUCCESS and *pcb on sucess.
VERR_NOT_SUPPORTED if the information isn't available on the system in general. The caller must handle this scenario.
VERR_ACCESS_DENIED if the information isn't accessible to the caller.
Parameters:
pcb Where to store the result (in bytes).
Remarks:
This function could've been inverted and called RTSystemQueryAvailableRam, but that might give impression that it would be possible to allocate the amount of memory it indicates for a single purpose, something which would be very improbable on most systems.

We might have to add another output parameter to this function that indicates if some of the memory kinds listed above cannot be accounted for on the system and therefore is not include in the returned amount.

Create a recurring timer.

Returns:
iprt status code.
Parameters:
ppTimer Where to store the timer handle.
uMilliesInterval Milliseconds between the timer ticks. This is rounded up to the system granularity.
pfnTimer Callback function which shall be scheduled for execution on every timer tick.
pvUser User argument for the callback.
See also:
RTTimerDestroy, RTTimerStop
Create a suspended timer.

Returns:
iprt status code.
Return values:
VERR_NOT_SUPPORTED if an unsupported flag was specfied.
Parameters:
ppTimer Where to store the timer handle.
u64NanoInterval The interval between timer ticks specified in nanoseconds if it's a recurring timer. This is rounded to the fit the system timer granularity. For one shot timers, pass 0.
fFlags Timer flags.
pfnTimer Callback function which shall be scheduled for execution on every timer tick.
pvUser User argument for the callback.
See also:
RTTimerStart, RTTimerStop, RTTimerDestroy, RTTimerGetSystemGranularity
Stops and destroys a running timer.

Returns:
iprt status code.
Parameters:
pTimer Timer to stop and destroy. NULL is ok.
Stops an active timer.

Returns:
IPRT status code.
Return values:
VERR_INVALID_HANDLE if pTimer isn't valid.
VERR_TIMER_ACTIVE if the timer isn't suspended.
Parameters:
pTimer The timer to activate.
u64First The RTTimeSystemNanoTS() for when the timer should start firing (relative). If 0 is specified, the timer will fire ASAP.
See also:
RTTimerStop
Stops an active timer.

Returns:
IPRT status code.
Return values:
VERR_INVALID_HANDLE if pTimer isn't valid.
VERR_TIMER_SUSPENDED if the timer isn't active.
VERR_NOT_SUPPORTED if the IPRT implementation doesn't support stopping a timer.
Parameters:
pTimer The timer to suspend.
See also:
RTTimerStart
Requests a specific system timer granularity.

Successfull calls to this API must be coupled with the exact same number of calls to RTTimerReleaseSystemGranularity() in order to undo any changes made.

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if the requested value isn't supported by the host platform or if the host platform doesn't support modifying the system timer granularity.
VERR_PERMISSION_DENIED if the caller doesn't have the necessary privilege to modify the system timer granularity.
Parameters:
u32Request The requested system timer granularity in nanoseconds.
pu32Granted Where to store the granted system granularity. This is the value that should be passed to RTTimerReleaseSystemGranularity(). It is what RTTimerGetSystemGranularity() would return immediately after the change was made.
The value differ from the request in two ways; rounding and scale. Meaning if your request is for 10.000.000 you might be granted 10.000.055 or 1.000.000.
See also:
RTTimerReleaseSystemGranularity, RTTimerGetSystemGranularity
Releases a system timer granularity grant acquired by RTTimerRequestSystemGranularity().

Returns:
IPRT status code.
Return values:
VERR_NOT_SUPPORTED if the host platform doesn't have any way of modifying the system timer granularity.
VERR_WRONG_ORDER if nobody call RTTimerRequestSystemGranularity() with the given grant value.
Parameters:
u32Granted The granted system granularity.
See also:
RTTimerRequestSystemGranularity
Create a recurring low resolution timer.

Returns:
iprt status code.
Parameters:
phTimerLR Where to store the timer handle.
uMilliesInterval Milliseconds between the timer ticks, at least 100 ms. If higher resolution is required use the other API.
pfnTimer Callback function which shall be scheduled for execution on every timer tick.
pvUser User argument for the callback.
See also:
RTTimerLRCreateEx, RTTimerLRDestroy, RTTimerLRStop
Create a suspended low resolution timer.

Returns:
iprt status code.
Return values:
VERR_NOT_SUPPORTED if an unsupported flag was specfied.
Parameters:
phTimerLR Where to store the timer handle.
u64NanoInterval The interval between timer ticks specified in nanoseconds if it's a recurring timer, the minimum for is 100000000 ns. For one shot timers, pass 0.
fFlags Timer flags. Same as RTTimerCreateEx.
pfnTimer Callback function which shall be scheduled for execution on every timer tick.
pvUser User argument for the callback.
See also:
RTTimerLRStart, RTTimerLRStop, RTTimerLRDestroy
Stops and destroys a running low resolution timer.

Returns:
iprt status code.
Parameters:
hTimerLR The low resolution timer to stop and destroy. NIL_RTTIMERLR is accepted.
Stops an active low resolution timer.

Returns:
IPRT status code.
Return values:
VERR_INVALID_HANDLE if pTimer isn't valid.
VERR_TIMER_ACTIVE if the timer isn't suspended.
Parameters:
hTimerLR The low resolution timer to activate.
u64First The RTTimeSystemNanoTS() for when the timer should start firing (relative), the minimum is 100000000 ns. If 0 is specified, the timer will fire ASAP.
See also:
RTTimerLRStop
Stops an active low resolution timer.

Returns:
IPRT status code.
Return values:
VERR_INVALID_HANDLE if pTimer isn't valid.
VERR_TIMER_SUSPENDED if the timer isn't active.
VERR_NOT_SUPPORTED if the IPRT implementation doesn't support stopping a timer.
Parameters:
hTimerLR The low resolution timer to suspend.
See also:
RTTimerLRStart
Create a compressor instance.

Returns:
iprt status code.
Parameters:
ppZip Where to store the instance handle.
pvUser User argument which will be passed on to pfnOut and pfnIn.
pfnOut Callback for consuming output of compression.
enmType Type of compressor to create.
enmLevel Compression level.
Compresses a chunk of memory.

Returns:
iprt status code.
Parameters:
pZip The compressor instance.
pvBuf Pointer to buffer containing the bits to compress.
cbBuf Number of bytes to compress.
Finishes the compression. This will flush all data and terminate the compression data stream.

Returns:
iprt status code.
Parameters:
pZip The compressor instance.
Destroys the compressor instance.

Returns:
iprt status code.
Parameters:
pZip The compressor instance.
Create a decompressor instance.

Returns:
iprt status code.
Parameters:
ppZip Where to store the instance handle.
pvUser User argument which will be passed on to pfnOut and pfnIn.
pfnIn Callback for producing input for decompression.
Decompresses a chunk of memory.

Returns:
iprt status code.
Parameters:
pZip The decompressor instance.
pvBuf Where to store the decompressed data.
cbBuf Number of bytes to produce. If pcbWritten is set any number of bytes up to cbBuf might be returned.
pcbWritten Number of bytes actually written to the buffer. If NULL cbBuf number of bytes must be written.
Destroys the decompressor instance.

Returns:
iprt status code.
Parameters:
pZip The decompressor instance.
Initialize seeds.

Remarks:
You should choose ANY 4 random 64-bit seeds x,y,z,w < 2^64-1 and a random seed c in 0<= c < a = 2^62+2^47+2. There are P=(2^62+2^46+2)*(2^64-1)^4 > 2^318 possible choices for seeds, the period of the RNG.
Initializes the heap.

Returns:
IPRT status code on success.
Parameters:
pHeap Where to store the heap anchor block on success.
pvMemory Pointer to the heap memory.
cbMemory The size of the heap memory.
Creates an empty address space.

Returns:
IPRT status code.
Parameters:
phDbgAs Where to store the address space handle on success.
FirstAddr The first address in the address space.
LastAddr The last address in the address space.
pszName The name of the address space.
Gets the address of a named exported symbol.

Returns:
iprt status code.
Parameters:
hLdrMod The loader module handle.
pszSymbol Symbol name.
ppvValue Where to store the symbol value. Note that this is restricted to the pointer size used on the host!
Loads the image into a buffer provided by the user and applies fixups for the given base address.

Returns:
iprt status code.
Parameters:
hLdrMod The load module handle.
pvBits Where to put the bits. Must be as large as RTLdrSize() suggests.
BaseAddress The base address.
pfnGetImport Callback function for resolving imports one by one.
pvUser User argument for the callback.
Remarks:
Not supported for RTLdrLoad() images.
Create a logger instance, comprehensive version.

Returns:
iprt status code.
Parameters:
ppLogger Where to store the logger instance.
fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
pszGroupSettings The initial group settings.
pszEnvVarBase Base name for the environment variables for this instance.
cGroups Number of groups in the array.
papszGroups Pointer to array of groups. This must stick around for the life of the logger instance.
fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
cchErrorMsg The size of the error message buffer.
pszFilenameFmt Log filename format string. Standard RTStrFormat().
... Format arguments.
Create a cache for objects.

Returns:
iprt status code.
Parameters:
ppObjCache Where to store the pointer to the created cache.
cElements Number of elements the cache can hold. 0 if unlimited size.
cbElement Size of one element in bytes
fProt Protection flags for protecting cache against concurrent access from different threads. RTOBJCACHE_PROTECT_REQUESTER to protect the request function. RTOBJCACHE_PROTECT_INSERT to protect the insert function.
Create a request packet queueu

Returns:
iprt status code.
Parameters:
ppQueue Where to store the request queue pointer.
Destroy a request packet queueu

Returns:
iprt status code.
Parameters:
pQueue The request queue.
Process one or more request packets

Returns:
iprt status code.

VERR_TIMEOUT if cMillies was reached without the packet being added.

Parameters:
pQueue The request queue.
cMillies Number of milliseconds to wait for a pending request. Use RT_INDEFINITE_WAIT to only wait till one is added.
Adopts a non-IPRT thread.

Returns:
IPRT status code.
Parameters:
enmType The thread type.
fFlags The thread flags. RTTHREADFLAGS_WAITABLE is not currently allowed.
pszName The thread name. Optional.
pThread Where to store the thread handle. Optional.
Formats an integer number according to the parameters.

Returns:
Length of the formatted number.
Parameters:
psz Pointer to output string buffer of sufficient size.
u64Value Value to format.
uiBase Number representation base.
cchWidth Width.
cchPrecision Precision.
fFlags Flags (NTFS_*).
Allocates a new copy of the given UTF-8 string.

Returns:
iprt status code.
Parameters:
ppszString Receives pointer of the allocated UTF-8 string. The returned pointer must be freed using RTStrFree().
pszString UTF-8 string to duplicate.
Destroys the specified tree, starting with the root node and working our way down.

Returns:
0 on success.

Return value from callback on failure. On failure, the tree will be in an unbalanced condition and only further calls to the Destroy should be made on it. Note that the node we fail on will be considered dead and no action is taken to link it back into the tree.

Parameters:
ppTree Pointer to the AVL-tree root node pointer.
pfnCallBack Pointer to callback function.
pvUser User parameter passed on to the callback function.
Iterates thru all nodes in the given tree.
Returns:
0 on success. Return from callback on failure.
Parameters:
ppTree Pointer to the AVL-tree root node pointer.
fFromLeft TRUE: Left to right. FALSE: Right to left.
pfnCallBack Pointer to callback function.
pvParam Userparameter passed on to the callback function.
Initialize a critical section.

Initialize a critical section.

Returns:
iprt status code.
Parameters:
pCritSect Pointer to the critical section structure.
fFlags Flags, any combination of the RTCRITSECT_FLAGS #defines.
Todo:
figure out which headers to include to get this one typedef...
Todo:
RTmpCpuId().
Todo:
RTmpCpuId().
Todo:
RTMpCpuId()
Todo:
RTmpCpuId().

Todo:
map this differently on solaris.

Todo:
map this differently on solaris.

Definition at line 80 of file req.cpp.

{
    /*
     * Check input.
     */
    if (!pQueue)
    {
        AssertFailed();
        return VERR_INVALID_PARAMETER;
    }
    RTSemEventDestroy(pQueue->EventSem);
    RTMemFree(pQueue);
    return VINF_SUCCESS;
}


Generated by  Doxygen 1.6.0   Back to index