torsten
77c67c12ca
Entire-Metadata: .entire/metadata/fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Session: fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Strategy: manual-commit
2585 lines
98 KiB
C
2585 lines
98 KiB
C
/*
|
|
* (c) Copyright, Real-Time Innovations, 2003-2024.
|
|
* All rights reserved.
|
|
*
|
|
* No duplications, whole or partial, manual or electronic, may be made
|
|
* without express written permission. Any such copies, or
|
|
* revisions thereof, must display this notice unaltered.
|
|
* This code contains trade secrets of Real-Time Innovations, Inc.
|
|
*/
|
|
|
|
#ifndef osapi_utility_h
|
|
#define osapi_utility_h
|
|
|
|
#include <errno.h>
|
|
|
|
#if defined(RTI_WIN32) || defined(RTI_WINCE)
|
|
#ifndef WIN32_LEAN_AND_MEAN
|
|
#define WIN32_LEAN_AND_MEAN
|
|
#endif
|
|
#include <windows.h>
|
|
#include <errhandlingapi.h>
|
|
#endif
|
|
|
|
#include <float.h>
|
|
#include "osapi/osapi_type.h"
|
|
#include "osapi/osapi_dll.h"
|
|
#include "osapi/osapi_vxVersions.h"
|
|
#include "osapi/osapi_rtpsTime.h"
|
|
#include "osapi/osapi_file.h"
|
|
|
|
#include <stdio.h>
|
|
#include <stdarg.h>
|
|
#include <ctype.h>
|
|
|
|
#if defined(RTI_INTY)
|
|
#include <util/error_string.h>
|
|
#endif
|
|
|
|
#if (defined(RTI_VXWORKS) || defined(RTI_QNX) || defined(RTI_INTY))
|
|
#define RTI_DOUBLE_SIGNIFICANT_DIGITS 15
|
|
#else
|
|
#define RTI_DOUBLE_SIGNIFICANT_DIGITS 17
|
|
#endif
|
|
#define RTI_FLOAT_SIGNIFICANT_DIGITS 9
|
|
#define RTI_FLOAT_SIGNIFICANT_DIGIT_SCALE 1000000000
|
|
|
|
#ifdef RTI_WIN32
|
|
#define RTI_OSAPI_FILE_PATH_SEPARATOR ("\\")
|
|
#define RTI_OSAPI_PATH_ENVVAR_SEPARATOR (";")
|
|
#else
|
|
#define RTI_OSAPI_FILE_PATH_SEPARATOR ("/")
|
|
#define RTI_OSAPI_PATH_ENVVAR_SEPARATOR (":")
|
|
#endif
|
|
|
|
#define RTI_OSAPI_PATH_MAX_SIZE 512
|
|
|
|
#if !(defined(RTI_VXWORKS) && VXWORKS_MAJOR_VERSION < 6) \
|
|
&& !(defined(RTI_LYNX) && RTI_LYNX < 500)
|
|
#define RTI_OSAPI_VSNPRINTF_SUPPORTED
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
typedef enum {
|
|
RTI_OSAPI_STRING_REMOVE_PREFIX,
|
|
RTI_OSAPI_STRING_REMOVE_SUFFIX,
|
|
RTI_OSAPI_STRING_REMOVE_SUBSTRING
|
|
} RTIOsapiStringRemoveType;
|
|
|
|
/** @internal \file
|
|
* @brief Simple, static utility functions that is a pest to write
|
|
* over and over again in different modules
|
|
*/
|
|
|
|
/** @internal \defgroup RTIOsapiUtilityClass RTIOsapiUtility
|
|
* \ingroup RTIOsapiModule
|
|
* \brief Namespace for utility functions
|
|
*/
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief static function to return the greater of the two
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_max(int l, int r);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Test if a number is between [lower, upper]
|
|
* @return 1 if within, else 0.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_isWithinBound(
|
|
int me,
|
|
int lower,
|
|
int upper);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Test if a number is between [lower, upper]
|
|
* @return 1 if within and not NaN, else 0.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_isFloatWithinBound(
|
|
float me,
|
|
float lower,
|
|
float upper);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Test if a number is between [lower, upper]
|
|
* @return 1 if within and not NaN, else 0.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_isDoubleWithinBound(
|
|
double me,
|
|
double lower,
|
|
double upper);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief static function to return the lesser of the two
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_min(int l, int r);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief static function to return the absolute value of a number
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_abs(int l);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief static function to do byte swapping in higher layer, so they
|
|
* won't have to use ntohs directly and have to pull in all kinds of system
|
|
* header file
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT16 RTIOsapiUtility_ntohs(RTI_UINT16 s);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief static function to do byte swapping in higher layer, so they
|
|
* won't have to use ntohl directly and have to pull in all kinds of system
|
|
* header file
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT32 RTIOsapiUtility_ntohl(RTI_UINT32 l);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief static function to do byte swapping in higher layer, so they
|
|
* won't have to use htons directly and have to pull in all kinds of system
|
|
* header file
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT16 RTIOsapiUtility_htons(RTI_UINT16 s);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief static function to do byte swapping in higher layer, so they
|
|
* won't have to use htonl directly and have to pull in all kinds of system
|
|
* header file
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT32 RTIOsapiUtility_htonl(RTI_UINT32 l);
|
|
|
|
extern RTIOsapiDllExport void RTIOsapiUtility_hostToNetworkByteOrder(
|
|
void *dst,
|
|
const void *src,
|
|
RTI_UINT32 size);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief static function to tell if a character is in [0, 9] range
|
|
* @return 0 if not.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_isDigit(int c);
|
|
|
|
#define OSAPI_UTILITY_MAX_TEMP_DIRECTORY_NAME_LENGTH 256
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Creates a temporary directory
|
|
*
|
|
* @param outPath On success, it contains the full path to the directory that
|
|
* the function has created. Its size must be at least:
|
|
* OSAPI_UTILITY_MAX_TEMP_DIRECTORY_NAME_LENGTH.
|
|
*
|
|
* @return Success or not.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_createTempDirectory(char *outPath);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Deletes a directory and all its contents
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_deleteDirectory(const char *path);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Look for an environment variable or a file and read the result
|
|
* into the string provided. File takes precedence over environment.
|
|
*
|
|
* Can get a total length RTI_OSAPI_STRING_SEQ_STRING_MAX_SIZE characters into
|
|
* \c buffer from either an environment variable \c envVariableName, or from a
|
|
* file \c fileName. If both \fileName and \c envVariableName are not NULL, the
|
|
* file takes precedence over the environment variable.
|
|
*
|
|
* When a file is read, it is assumed to contain items separated by whitespace
|
|
* and comments, which are ignored. The items are concatenated using \c
|
|
* separator in the output string.
|
|
*
|
|
* @param buffer \st_out The output buffer. Must be non-NULL.
|
|
*
|
|
* @param bufferSize \st_in The size of the \c buffer. Since the method reads
|
|
* at most RTI_OSAPI_STRING_SEQ_STRING_MAX_SIZE characters, \c
|
|
* bufferSize should be size <= RTI_OSAPI_STRING_SEQ_STRING_MAX_SIZE to minimize
|
|
* wasted space.
|
|
*
|
|
* @param envVariableName \st_in The name of the environment variable to get.
|
|
*
|
|
* @param fileName \st_in The name of the file to read.
|
|
*
|
|
* @param separator \st_in When a file is read, items are concatenated
|
|
* by \c separator on the output \c buffer.
|
|
*
|
|
* @param commentchar \st_in When a file is read, characters including and after
|
|
* the \c commentchar till the end of a line are ignored. In addition the
|
|
* whitespace is ignored.
|
|
*
|
|
* @return \c buffer if valid output is produced; NULL otherwise.
|
|
*
|
|
* @see RTI_OSAPI_STRING_SEQ_STRING_MAX_SIZE
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapi_envVarOrFileGet(
|
|
char *buffer,
|
|
size_t bufferSize,
|
|
const char *envVariableName,
|
|
const char *fileName,
|
|
char separator,
|
|
char commentchar);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Gets the value of an environment variable.
|
|
*
|
|
* This function returns a string with the value of the environment
|
|
* variable. The string is dynamically allocated and must be freed by the
|
|
* caller.
|
|
*
|
|
* This function and RTIOsapi_envVarOrFileGet do the same thing (when fileName
|
|
* is NULL), the only difference is that this function returns a dynamically
|
|
* allocated string that must be freed by the caller, while
|
|
* RTIOsapi_envVarOrFileGet expects a pre-allocated buffer to store the result.
|
|
*
|
|
* See https://en.cppreference.com/w/c/program/getenv. This function mitigates
|
|
* CON33-C as prescribed by ENV34-C by copying the value retrieved from regular
|
|
* `getenv` into a newly allocated string which MUST be freed after use.
|
|
*
|
|
* @param envVariableName \b In. The name of the environment variable to get.
|
|
* @return The value of the environment variable, or NULL if it does not exist.
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapi_envVarGet(const char *envVariableName);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the username currently in use.
|
|
*
|
|
* @param username \b Out. The destination buffer to store the resulting user
|
|
* name.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getUsername(char *username, size_t bufferSize);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the full path of an executable
|
|
*
|
|
* Gets the full path of an executable. With argv[0] from the main function
|
|
* only the relative path is available. And if the executable was in the PATH
|
|
* that path is not even relative to the current directory. This function takes
|
|
* that into account and retrieves the full path of the executable argv[0].
|
|
*
|
|
* @param path \b Out. The destination buffer to store the resulting path.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
* @param executable \st_in The value of argv[0] from the main function
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_getExecutablePath(
|
|
char *path,
|
|
int bufferSize,
|
|
const char *executable);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiUtilityClass
|
|
* @brief Maximum length of a path.
|
|
*/
|
|
#define RTI_OSAPI_UTILITY_MAX_PATH_LENGTH (1024)
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiUtilityClass
|
|
* @brief Get the executable name of the running process.
|
|
*
|
|
* @param executableName \b Out. The destination buffer to store the resulting
|
|
* executable name. It must be pre-allocated.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
* @param removeExtension \b In. If RTI_TRUE, the extension of the executable
|
|
* will be removed. Otherwise, it will be kept.
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_getExecutableName(
|
|
char *executableName,
|
|
size_t bufferSize,
|
|
RTIBool removeExtension);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiUtilityClass
|
|
* @brief Returns RTI_TRUE if RTIOsapiUtility_getFilePath is supported.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_isGetFilePathSupported(void);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the full path of the file provided as input and stores it
|
|
* in path.
|
|
*
|
|
* @param[out] path. The full path will be stored in this array.
|
|
* @param[out] pathMaxSize. The size of the path array.
|
|
*
|
|
* The function return RTI_FALSE if:
|
|
* - The file does not exist.
|
|
* - The operation is not supported.
|
|
* - The full path cannot be stored in path.
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getFilePath(char *path, size_t pathMaxSize, const char *file);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the full path of the current executable
|
|
* @param path \b Out. The destination buffer to store the resulting
|
|
* path.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getSelfFullpath(char *path, size_t bufferSize);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the full path of the directory that contains the
|
|
* current executable.
|
|
*
|
|
* If the directory path cannot be determined, it will return the
|
|
* the current working directory "."
|
|
*
|
|
* @param path \b Out. The destination buffer to store the resulting path.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
*
|
|
* @return True on success.
|
|
*
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getSelfDirectoryPath(char *path, size_t bufferSize);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the current working directory, without a trailing slash.
|
|
*
|
|
* @param path \b Out. The destination buffer to store the resulting path.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
*
|
|
* @return the path argument on success, NULL on failure
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_getCurrentDirectory(
|
|
char *path,
|
|
size_t bufferSize);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the target for which this library was built for
|
|
*
|
|
* @param target \b Out. The destination buffer to store the resulting target.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getTarget(char *target, size_t bufferSize);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the time of creation of the file
|
|
*
|
|
* @param buf \b Out. The destination buffer to store the resulting timestamp.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getCreationTimestamp(char *buf, size_t bufferSize);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets the time of execution of the file
|
|
*
|
|
* @param buf \b Out. The destination buffer to store the resulting timestamp.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getExecutionTimestamp(char *buf, size_t bufferSize);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Gets a compacted path
|
|
* A path like build/../../rti/.//lib/arch becomes ../rti/lib/arch
|
|
* In Windows it also replaces / directory separators with \
|
|
* @param path \b Out. The destination buffer to store the resulting path.
|
|
* @param bufferSize \b In. The size of the destination buffer.
|
|
* @param originalPath \b In. The input path
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_normalizePath(
|
|
char *path,
|
|
size_t bufferSize,
|
|
const char *originalPath);
|
|
|
|
#if defined(RTI_IOS_xxx) || defined(RTI_LINUX) || defined(RTI_DARWIN) \
|
|
|| defined(RTI_VXWORKS) || defined(RTI_AIX) || defined(RTI_INTY) \
|
|
|| defined(RTI_QNX)
|
|
#define RTI_OSAPI_GETENV_SETENV_SUPPORTED
|
|
#endif
|
|
|
|
#if defined(RTI_LINUX) || defined(RTI_DARWIN) || defined(RTI_WIN32) \
|
|
|| defined(RTI_INTY) || defined(RTI_QNX)
|
|
#define RTI_OSAPI_GETENV_PUTENV_SUPPORTED
|
|
#endif
|
|
|
|
#if defined(RTI_OSAPI_GETENV_SETENV_SUPPORTED) \
|
|
|| defined(RTI_OSAPI_GETENV_PUTENV_SUPPORTED)
|
|
#define RTI_OSAPI_ENVIRONMENT_GET_SET_SUPPORTED
|
|
#endif
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @return True if setting the environment is supported.
|
|
*
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapi_isEnvVarSetSupported(void);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* The RTIOsapi_envVarSet function sets the value of an environment variable.
|
|
*
|
|
* @param envVariable \st_in The argument envVariable is of the form name=value.
|
|
* if name does not already exist in the environment, then envVariable is added
|
|
* to the environment. If name does exist, then the value of name in the
|
|
* environment is changed to value. The string pointed by envVariable becomes
|
|
* part of the environment, so altering the string changes the environment.
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapi_envVarSet(const char *envVariable);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* The RTIOsapi_envVarUnset function clears the specified variable form the
|
|
* environment.
|
|
*
|
|
* @param varName \st_in The name of the variable to unset.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapi_envVarUnset(const char *varName);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Generates formatted text, under the control of format and any
|
|
* additional arguments.
|
|
*
|
|
* The function stores each generated character in successive locations of the
|
|
* array data object whose first element has the address str. The function
|
|
* concludes by storing a null character.
|
|
*
|
|
* The function does not write more than size bytes (including the null
|
|
* character).
|
|
*
|
|
* @return Number of characters written (not including the null character) if
|
|
* the number of characters to write is less than size and there is no error.
|
|
* Otherwise, -1. If NULL is passed as str, then the number length of the string
|
|
* is returned. If the operation is unsupported the function returns -2;
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_snprintf(
|
|
char *str,
|
|
size_t size,
|
|
const char *format,
|
|
...);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
\brief Generates formatted text, under the control of format and any
|
|
additional arguments.
|
|
|
|
The function stores each generated character in successive locations of the
|
|
array data object whose first element has the address str. The function
|
|
concludes by storing a null character.
|
|
|
|
The function does not write more than size bytes (including the null
|
|
character).
|
|
|
|
@return Number of characters written (not including the null character) if the
|
|
number of characters to write is less than size and there is no error.
|
|
Otherwise, -1. If NULL is passed as str, then the number length of the string
|
|
is returned. If the operation is unsupported the function returns -2;
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_snprintfAdv(
|
|
char *str,
|
|
size_t size,
|
|
RTIBool showErrors,
|
|
const char *format,
|
|
...);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Generates formatted text, under the control of format and any
|
|
* additional arguments.
|
|
*
|
|
* The function stores each generated character in succesive locations of the
|
|
* array data object whose first element has the address str. The function
|
|
* concludes by storing a null character.
|
|
*
|
|
* The function does not write more than size bytes (including the null
|
|
* character).
|
|
*
|
|
* @return Number of characters written (not including the null character) if
|
|
* the number of characters to write is less than size and there is no error.
|
|
* Otherwise, -1. If str is NULL, then we output the formatted text, but the
|
|
* function still returns its equivalent string length. If the operation is
|
|
* unsupported the function returns -2.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_vsnprintf(
|
|
char *str,
|
|
size_t size,
|
|
const char *format,
|
|
va_list args);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Generates formatted text, under the control of format and any
|
|
* additional arguments.
|
|
*
|
|
* The function stores each generated character in successive locations of the
|
|
* array data object whose first element has the address str. The function
|
|
* concludes by storing a null character.
|
|
*
|
|
* The function does not write more than size bytes (including the null
|
|
* character).
|
|
*
|
|
* @return Number of characters written (not including the null character) if
|
|
* the number of characters to write is less than size and there is no error.
|
|
* Otherwise, -1. If str is NULL, then we output the formatted text, but the
|
|
* function still returns its equivalent string length. If the operation is
|
|
* unsupported the function returns -2.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_vsnprintfAdv(
|
|
char *str,
|
|
size_t size,
|
|
RTIBool showErrors,
|
|
const char *format,
|
|
va_list args);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Reads from formatted text, under the control of format and any
|
|
* additional arguments. Translates to sscanf_s instead of sscanf on Windows to
|
|
* avoid "this function or variable may be unsafe" warnings, so if characters
|
|
* and strings are in the format, the arguments must include the buffer lengths.
|
|
* So for portability, don't use RTIOsapiUtility_sscanf for characters or
|
|
* strings.
|
|
*
|
|
* @return Number of fields successfully assigned
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_sscanf(
|
|
const char *s,
|
|
const char *format,
|
|
...);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* \brief This function returns the length of the string in the parameter
|
|
* using strlen(). Accepts NULL as a parameter
|
|
*
|
|
* @return the length of the string.
|
|
*/
|
|
extern RTIOsapiDllExport size_t RTIOsapiUtility_strlen(const char *str);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Returns the length of a string.
|
|
*
|
|
* @param In. The string.
|
|
* @param In. The maximum length allowed.
|
|
*
|
|
* @return This function returns the length of the string in characters, if
|
|
* that is less than maxLength, or maxLength if there is no null terminating
|
|
* among the first maxLength characters pointed to by str.
|
|
*/
|
|
extern RTIOsapiDllExport size_t
|
|
RTIOsapiUtility_strnlen(const char *str, size_t maxLength);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* \brief Function version of RTIOsapiUtility_strlen (which is a macro)
|
|
*/
|
|
extern RTIOsapiDllExport size_t RTIOsapiUtility_strlenFnc(char *str);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* \brief This function copies the string pointed to by src, including
|
|
* the terminating null byte ('\0'), to the buffer pointed to by dest. The
|
|
* strings should not overlap.
|
|
*
|
|
* Unlike strcpy() an additional parameter destStringLengthMax is required to
|
|
* ensure there is no possible buffer overflow. A null char at the end of the
|
|
* string is always added. If src is too long for the dest buffer, dest ends up
|
|
* with a partial, null-terminated copy of src. In this case the function
|
|
* returns null for error checking.
|
|
*
|
|
* @return a pointer to the destination string dest or null if src is too long
|
|
* for dest buffer.
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strcpy(
|
|
char *dest,
|
|
size_t destStringLengthMax,
|
|
const char *src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief This function copies the first n characters of the string pointed
|
|
* to by src, including the terminating null byte ('\0'), to the buffer pointed
|
|
* to by dest. The strings should not overlap.
|
|
*
|
|
* Unlike strncpy() an additional parameter destStringLengthMax is required to
|
|
* ensure there is no possible buffer overflow. A null char at the end of the
|
|
* string is always added. If src is too long for the dest buffer, dest ends up
|
|
* with a partial, null-terminated copy of src. In this case the function
|
|
* returns null for error checking.
|
|
*
|
|
* Unlike strncpy() that writes additional null bytes to dest to ensure that a
|
|
* total of n bytes are written, RTIOsapiUtility_strncpy adds a single null char
|
|
* at the end of the string.
|
|
*
|
|
* TRUST-2037: The value of the src parameter can be NULL only if the value of n
|
|
* = 0. If n > 0 in such a condition .. it will lead to a crash in release mode!
|
|
*
|
|
* @return a pointer to the destination string dest or null if src is too long
|
|
* for dest buffer.
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strncpy(
|
|
char *dest,
|
|
size_t destStringLengthMax,
|
|
const char *src,
|
|
size_t n);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Concatenates the src string after the dest string. The function
|
|
* copies the string pointed to by src, including the terminating null byte
|
|
* ('\0'), at the end of the string (without the final null byte) contained in
|
|
* the buffer pointed to by dest. The strings should not overlap.
|
|
*
|
|
* Unlike strcat, an additional parameter destStringLengthMax is required to
|
|
* ensure there is no possible buffer overflow. A null char at the end of the
|
|
* string is always added. If the resulting concatenation is too long for the
|
|
* dest buffer, dest ends up with a partial null-terminated copy of src. In this
|
|
* case the function returns null for error checking.
|
|
*
|
|
* @return a pointer to the destination string dest or null if src is too long
|
|
* for dest buffer.
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strcat(
|
|
char *dest,
|
|
size_t destStringLengthMax,
|
|
const char *src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Concatenates the first n chars of src string after the dest string.
|
|
* The function copies the first n chars of the string pointed to by src,
|
|
* including the terminating null byte ('\0'), at the end of the string (without
|
|
* the final null byte) contained in the buffer pointed to by dest. The strings
|
|
* should not overlap.
|
|
*
|
|
* Unlike strncat, an additional parameter destStringLengthMax is required to
|
|
* ensure there is no possible buffer overflow. A null char at the end of the
|
|
* string is always added. If the resulting concatenation is too long for the
|
|
* dest buffer, dest ends up with a partial null-terminated copy of src. In this
|
|
* case the function returns null for error checking.
|
|
*
|
|
* @return a pointer to the destination string dest or null if src is too long
|
|
* for dest buffer.
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strncat(
|
|
char *dest,
|
|
size_t destStringLengthMax,
|
|
const char *src,
|
|
size_t n);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Looks for the first occurrence of the pattern string in the src
|
|
* string. It accepts NULL as src or pattern string.
|
|
*
|
|
* @return a pointer to the occurrence if found, NULL otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport const char *RTIOsapiUtility_strstr(
|
|
const char *src,
|
|
const char *pattern);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Looks for the last occurrence of the pattern string in the src string.
|
|
* It accepts NULL as src or pattern string.
|
|
*
|
|
* @return a pointer to the occurrence if found, NULL otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
const char *RTIOsapiUtility_strrstr(const char *src, const char *pattern);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Compare two strings, up to the specified number of bytes.
|
|
*
|
|
* @param str1 \b In. First string. A NULL pointer is treated as the empty
|
|
* string.
|
|
* @param str2 \b In. Second string. A NULL pointer is treated as the empty
|
|
* string.
|
|
* @param size \b In. Number of bytes to compare.
|
|
*
|
|
* @return An integer representing if str1 is less than (< 0), equal (0), or
|
|
* greater (> 0) than str2. Only the first size bytes are compared.
|
|
*/
|
|
extern RTIOsapiDllExport RTI_INT32
|
|
RTIOsapiUtility_strncmp(const char *str1, const char *str2, size_t size);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Compare two strings, until a null terminator is found in one of them.
|
|
*
|
|
* @param[in] str1 First string. A NULL pointer is treated as the empty string.
|
|
* @param[in] str2 Second string. A NULL pointer is treated as the empty string.
|
|
*
|
|
* @return An integer representing if str1 is less than (< 0), equal (0), or
|
|
* greater (> 0) than str2.
|
|
*/
|
|
extern RTIOsapiDllExport RTI_INT32
|
|
RTIOsapiUtility_strcmp(const char *str1, const char *str2);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief compares the two strings s1 and s2, ignoring the case of the
|
|
* characters. It returns an integer less than, equal to, or greater than zero
|
|
* if s1 is found, respectively, to be less than, to match, or be greater than
|
|
* s2.
|
|
*
|
|
* @return a pointer to the occurrence if found, NULL otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_strcasecmp(
|
|
const char *src,
|
|
const char *pattern);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Gets the maximum precision for a double supported by the platform.
|
|
*/
|
|
extern RTIOsapiDllExport unsigned int RTIOsapiUtility_get_double_precision(
|
|
void);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts the initial part of the string to a long integer of the
|
|
* specified base.
|
|
*
|
|
* @param str \b In. The string to convert.
|
|
* @param endPtr \b Out. If not NULL, a pointer to the character after
|
|
* the last character used in the conversion is stored here.
|
|
* @param value \b Out. The resulting integer.
|
|
* @param base \b In. The base for the conversion. Must be between 2 and 36,
|
|
* or be the special value 0. If base is 0, the base is determined by the
|
|
* format of the initial characters of str: if the string begins with "0x" or
|
|
* "0X", base 16 is used; if the string begins with "0", base 8 is used;
|
|
* otherwise, base 10 is used.
|
|
* @param logException \b In. If RTI_TRUE, log an exception when conversion
|
|
* fails.
|
|
*
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_strtolWithBase(
|
|
const char *str,
|
|
const char **endPtr,
|
|
RTI_INT32 *value,
|
|
RTI_INT32 base,
|
|
RTIBool logException);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts the initial part of the string to a long integer.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_strtol(const char *str, RTI_INT32 *value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts the initial part of the string to a unsigned long integer
|
|
* of the specified base.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_strtoulWithBase(
|
|
const char *str,
|
|
const char **endPtr,
|
|
RTI_UINT32 *value,
|
|
RTI_INT32 base);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts the initial part of the string to a long long integer.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_strtoul(const char *str, RTI_UINT32 *value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts the initial part of the string to a unsigned long integer.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_strtoll(const char *str, RTI_INT64 *value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Convert the initial part of the string to a long long integer. Check
|
|
* that the character after the integer is the expectedEndSeparator. If
|
|
* expectedEndSeparator is '\0', then no characters are expected to follow the
|
|
* integer.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_strtollWithEndSeparator(
|
|
const char *str,
|
|
RTI_INT64 *value,
|
|
const char expectedEndSeparator);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Convert the initial part of the string to a long long integer.
|
|
* Populate endPtr with the string following the initial part of the string.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_strtollWithEndPtr(
|
|
const char *str,
|
|
const char **endPtr,
|
|
RTI_INT64 *value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts the initial part of the string to an unsigned long long
|
|
* integer.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_strtoull(const char *str, RTI_UINT64 *value, int base);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts the initial part of the string to a double.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_strtod(const char *str, RTI_DOUBLE64 *value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts the initial part of the string to a float.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_strtof(const char *str, RTI_FLOAT32 *value);
|
|
|
|
#define RTI_OSAPI_UTILITY_MAX_INT8_STR_SIZE 5
|
|
#define RTI_OSAPI_UTILITY_MAX_UINT8_STR_SIZE 4
|
|
#define RTI_OSAPI_UTILITY_MAX_INT16_STR_SIZE 7
|
|
#define RTI_OSAPI_UTILITY_MAX_UINT16_STR_SIZE 6
|
|
#define RTI_OSAPI_UTILITY_MAX_INT32_STR_SIZE 12
|
|
#define RTI_OSAPI_UTILITY_MAX_UINT32_STR_SIZE 11
|
|
#define RTI_OSAPI_UTILITY_MAX_INT64_STR_SIZE 21
|
|
#define RTI_OSAPI_UTILITY_MAX_UINT64_STR_SIZE 21
|
|
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Convert a signed 8-bit signed integer to a string.
|
|
*
|
|
* Note: for maximum performance, this method uses a lookup table.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
const char *RTIOsapiUtility_int8ToStr(RTI_INT8 value);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Convert a signed 8-bit unsigned integer to a string.
|
|
*
|
|
* Note: for maximum performance, this method uses a lookup table.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
const char *RTIOsapiUtility_uint8ToStr(RTI_UINT8 value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Convert a signed 16-bit signed integer to a string.
|
|
*
|
|
* @param str A buffer to hold the resulting string. Must be at least
|
|
* RTI_OSAPI_UTILITY_MAX_INT16_STR_SIZE bytes long.
|
|
* @param size The size of the buffer.
|
|
* @param value The integer value to convert.
|
|
*
|
|
* @return A pointer to the resulting string, or NULL if the
|
|
* buffer is too small. The resulting pointer is always null-terminated. The
|
|
* returned pointer will always point to a position within the provided buffer
|
|
* but it may not be the first position.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
char *RTIOsapiUtility_int16ToStr(char *str, size_t size, RTI_INT16 value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Convert a signed 16-bit unsigned integer to a string.
|
|
*
|
|
* @param str A buffer to hold the resulting string. Must be at least
|
|
* RTI_OSAPI_UTILITY_MAX_UINT16_STR_SIZE bytes long.
|
|
* @param size The size of the buffer.
|
|
* @param value The integer value to convert.
|
|
*
|
|
* @return A pointer to the resulting string, or NULL if the
|
|
* buffer is too small. The resulting pointer is always null-terminated. The
|
|
* returned pointer will always point to a position within the provided buffer
|
|
* but it may not be the first position.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
char *RTIOsapiUtility_uint16ToStr(char *str, size_t size, RTI_UINT16 value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Convert a signed 32-bit signed integer to a string.
|
|
*
|
|
* @param str A buffer to hold the resulting string. Must be at least
|
|
* RTI_OSAPI_UTILITY_MAX_INT32_STR_SIZE bytes long.
|
|
* @param size The size of the buffer.
|
|
* @param value The integer value to convert.
|
|
*
|
|
* @return A pointer to the resulting string, or NULL if the
|
|
* buffer is too small. The resulting pointer is always null-terminated. The
|
|
* returned pointer will always point to a position within the provided buffer
|
|
* but it may not be the first position.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
char *RTIOsapiUtility_int32ToStr(char *str, size_t size, RTI_INT32 value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Convert a signed 32-bit unsigned integer to a string.
|
|
*
|
|
* @param str A buffer to hold the resulting string. Must be at least
|
|
* RTI_OSAPI_UTILITY_MAX_UINT32_STR_SIZE bytes long.
|
|
* @param size The size of the buffer.
|
|
* @param value The integer value to convert.
|
|
*
|
|
* @return A pointer to the resulting string, or NULL if the
|
|
* buffer is too small. The resulting pointer is always null-terminated. The
|
|
* returned pointer will always point to a position within the provided buffer
|
|
* but it may not be the first position.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
char *RTIOsapiUtility_uint32ToStr(char *str, size_t size, RTI_UINT32 value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Convert a signed 64-bit signed integer to a string.
|
|
*
|
|
* @param str A buffer to hold the resulting string. Must be at least
|
|
* RTI_OSAPI_UTILITY_MAX_INT64_STR_SIZE bytes long.
|
|
* @param size The size of the buffer.
|
|
* @param value The integer value to convert.
|
|
*
|
|
* @return A pointer to the resulting string, or NULL if the
|
|
* buffer is too small. The resulting pointer is always null-terminated. The
|
|
* returned pointer will always point to a position within the provided buffer
|
|
* but it may not be the first position.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
char *RTIOsapiUtility_int64ToStr(char *str, size_t size, RTI_INT64 value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Convert a signed 64-bit unsigned integer to a string.
|
|
*
|
|
* @param str A buffer to hold the resulting string. Must be at least
|
|
* RTI_OSAPI_UTILITY_MAX_UINT64_STR_SIZE bytes long.
|
|
* @param size The size of the buffer.
|
|
* @param value The integer value to convert.
|
|
*
|
|
* @return A pointer to the resulting string, or NULL if the
|
|
* buffer is too small. The resulting pointer is always null-terminated. The
|
|
* returned pointer will always point to a position within the provided buffer
|
|
* but it may not be the first position.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
char *RTIOsapiUtility_uint64ToStr(char *str, size_t size, RTI_UINT64 value);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Convert a 32-bit floating point value to a string.
|
|
*
|
|
* Note: this implementation uses a fast implementation for values for which we
|
|
* can use scaling to 64-bit integer. For precision of 9 digits, this means for
|
|
* values lower or equal to 922337203.0f (max int64 value divided by 1e9). For
|
|
* the rest of the cases uses the slow snprintf() way.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_floatToStr(char *str, size_t maxSize, RTI_FLOAT32 value);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Convert a 64-bit double precision floating point value to a string.
|
|
*
|
|
* This implementation uses 17 digits of precision, as define in
|
|
* ``RTI_DOUBLE_SIGNIFICANT_DIGITS``.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_doubleToStr(char *str, size_t maxSize, RTI_DOUBLE64 value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Parses a string containing a binary buffer encoded as hex.
|
|
*
|
|
* Given a buffer containing hex numbers, parses it and fills up a buffer.
|
|
*
|
|
* For example, if the input string is "01020a0b0c", it will fill up
|
|
* the bufOut buffer with the values [0x01, 0x02, 0x0a, 0a0b, 0x0c] and
|
|
* return the value 5 in bufSizeOut.
|
|
*
|
|
* The function will return false if invalid characters (not hex) are found.
|
|
*
|
|
* The parsing will stop either at the end of the input string or
|
|
* when the output buffer is full (as specified in maxSize)
|
|
*
|
|
* @param strIn the input string to parse. Must be NULL-terminated
|
|
* @param bufOut the buffer where to store the data
|
|
* @param maxSize the allocated size of the buffer
|
|
* @param bufSizeOut the number of bytes successfully (written in buffer)
|
|
*
|
|
* @return RTI_TRUE if the function succeeded, RTI_FALSE if strIn is NULL or
|
|
* contains invalid characters.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_parseHexString(
|
|
const char *strIn,
|
|
unsigned char *bufOut,
|
|
size_t maxSize,
|
|
size_t *bufSizeOut);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Converts an string representation of a pointer into a pointer.
|
|
* @return RTI_TRUE if success. Otherwise, RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_strtoptr(const char *str, void **value);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Total length of the environment variable
|
|
*
|
|
* @see RTIOsapi_environmentGet
|
|
*/
|
|
#define RTI_OSAPI_STRING_SEQ_STRING_MAX_SIZE (4096)
|
|
|
|
#if defined(RTI_VXWORKS) && VXWORKS_VERSION_6_3_OR_BETTER \
|
|
|| defined(RTI_VX653) \
|
|
|| (ENABLE_FACE_COMPLIANCE != FACE_COMPLIANCE_LEVEL_NONE)
|
|
#define RTI_REALTIME_CLOCK_ID CLOCK_REALTIME
|
|
#endif
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Reads the system's high resolution timer
|
|
*
|
|
* This function is a generalization of the function 'gethrtime' available only
|
|
* on Solaris.
|
|
* It relies on some hardware clock mechanism that may not available on all the
|
|
* architectures.
|
|
* If not supported, it will generate an error at compile time when invoked.
|
|
*
|
|
* The gethrtime() function returns the current high-resolution
|
|
* real time. Time is expressed as nanoseconds since some arbitrary
|
|
* time in the past; it is not correlated in any way to
|
|
* the time of day, and thus is not subject to resetting or
|
|
* drifting by way of adjtime or settimeofday. The hi-res
|
|
* timer is ideally suited to performance measurement
|
|
* tasks, where cheap, accurate interval timing is required.
|
|
*
|
|
* <b>IMPORTANT</b><br />
|
|
* The method to read the hard real-time clock on some architecture rely on
|
|
* calling the assembler-instruction "rdtsc". This has several drawbacks when
|
|
* used in a multi-core machine with scalable frequency or power management
|
|
* that may put one core to sleep (or slow down the clock).
|
|
* DO *NOT* use this function in a generic way and assume that will work on all
|
|
* the supported platforms. Use it knowing what you are doing.
|
|
* For further information, see the following article:
|
|
* http://msdn2.microsoft.com/en-us/library/bb173458.aspx
|
|
*
|
|
* @return a 64-bit (long long) signed integer representing the number of
|
|
* milliseconds since some arbitrary time in the past.
|
|
*/
|
|
extern RTIOsapiDllExport RTI_INT64 RTIOsapiUtility_gethrtime(void);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Gets real time clock time
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getTimeAdv(struct RTINtpTime *now, RTIBool logException);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Gets real time clock time
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getTime(struct RTINtpTime *now);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* The size of the buffer needed for representing UTC time
|
|
*
|
|
* @see RTIOsapiUtility_getUtcTime
|
|
*/
|
|
#define RTI_OSAPI_UTC_TIME_BUFFER_SIZE 29
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Translates RTI_TIME_T value to struct tm. This is a wrapper
|
|
* around a group of standard gmtime_* functions. See C spec for details.
|
|
*
|
|
* @param timer pointer to a time_t object to convert.
|
|
* @param buf pointer to a struct tm object to store the result.
|
|
*
|
|
* @return value is the pointer to buf upon success, or NULL upon failure.
|
|
*/
|
|
extern RTIOsapiDllExport struct tm *RTIOsapiUtility_gmtime(
|
|
const RTI_TIME_T *timer,
|
|
struct tm *buf);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Populates the buffer with the UTC format of the provided time.
|
|
*
|
|
* If includeSeparators is true, then the format of the time will be
|
|
* YYYY-MM-DD HH:MM:SS.<microseconds>,
|
|
* e.g - 2017-09-11 19:23:43.953248.
|
|
* If includeSeparators is false, then the format of the time will be
|
|
* YYYYMMDDHHMMSS.<microseconds>,
|
|
* e.g - 20170911192343.953248.
|
|
*
|
|
* If the size of the buffer is less than \ref RTI_OSAPI_UTC_TIME_BUFFER_SIZE,
|
|
* then the contents of the buffer are undefined and the functions returns
|
|
* false.
|
|
*
|
|
* @param buffer \b In. The output buffer with time.
|
|
* @param size \b In. The size of the buffer. The minimum size is
|
|
* RTI_OSAPI_UTC_TIME_BUFFER_SIZE.
|
|
* @param time \b In. The time to convert to string.
|
|
* @param includeDate \b In. If true add "YYYY-MM-DD ". If false skip it.
|
|
* @param includeMicroSec \b In. If true add ".<microseconds>". If false skip
|
|
* it.
|
|
* @param includeSeparators \b In. If true, use the " ", "-", and ":"
|
|
* separators. If false, don't use the separators.
|
|
*
|
|
* @return RTI_TRUE if the buffer is filled with the time properly.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_getUtcTime(
|
|
char *buffer,
|
|
unsigned int size,
|
|
const struct RTINtpTime *time,
|
|
RTIBool includeDate,
|
|
RTIBool includeMicroSec,
|
|
RTIBool includeSeparators);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Populates the buffer with the UTC format of the provided time by
|
|
* calling RTIOsapiUtility_getUtcTime with includeDate, includeMicroSec, and
|
|
* includeSeparators set to true.
|
|
*
|
|
* @param buffer \b InOut. The output buffer with time.
|
|
* @param size \b In. The size of the buffer. The minimum size is
|
|
* RTI_OSAPI_UTC_TIME_BUFFER_SIZE.
|
|
* @param time \b In. The time to convert to string.
|
|
*/
|
|
extern RTIOsapiDllExport void RTIOsapiUtility_getUtcTimeForLogging(
|
|
char *buffer,
|
|
unsigned int size,
|
|
const struct RTINtpTime *time);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Safe wrapper for localtime
|
|
*
|
|
* @param timer \b In. Pointer to an object that contains the time.
|
|
* @param buf \b InOut. Pointer to a struct tm object to store the result.
|
|
*
|
|
* @return pointer to a tm structure that contains the time that corresponds to
|
|
* the value pointed by timer.
|
|
*/
|
|
extern RTIOsapiDllExport struct tm *RTIOsapiUtility_localtime(
|
|
const time_t *timer,
|
|
struct tm *buf);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* A version of strtok that doesn't have any internal state. To use it:
|
|
*
|
|
* \verbatim
|
|
* char * token;
|
|
* char * strTokenSave;
|
|
*
|
|
* token = RTIOsapiUtility_strToken(expression, DELIM, &strTokenSave);
|
|
* token = RTIOsapiUtility_strToken(NULL, DELIM, &strTokenSave);
|
|
* \endverbatim
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strToken(
|
|
char *s1,
|
|
const char *delim,
|
|
char **save);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* \brief Extract tokens from strings, excluding those between escape
|
|
* characters.
|
|
*
|
|
* Same as RTIOsapiUtility_strToken, except that tokens in between escape
|
|
* characters will be ignored.
|
|
*
|
|
* @param s1 \b in. String to divide into tokens. It can't be NULL the first
|
|
* time that RTIOsapiUtility_strTokenEx is called. Afterwards, s1 must be NULL.
|
|
*
|
|
* @param delim \b in. Tokens (delimiters) extracted from s1.
|
|
*
|
|
* @param escapeAround \b in. Tokens between two occurrences of escapeAround
|
|
* characters will not break the string. escapeAround characters must appear in
|
|
* pairs.
|
|
* E.g. delim=[,], escapeAround=["], s1=[ABC,DEF,"GHI,JKL"] will become
|
|
* [ABC] [DEF] ["GHI,JKL"]
|
|
*
|
|
* Important: escapeAround characters can only be used for escaping.
|
|
* You should not pass the same character both as an escape and delimiter
|
|
* character.
|
|
* escapeAround characters must always have a matching corresponding character,
|
|
* otherwise this API will return a token ending at the end of the string
|
|
* E.g. delim=[,], escape=["], s1=[ABC,"DE,F"GH,I"JKL,MN] will become
|
|
* [ABC] ["DE,F"GH] [I"JKL,MN]
|
|
*
|
|
* @param escapeBefore \b in. Token preceded by one of these escapeBefore
|
|
* characters will not break the string.
|
|
* E.g. delim=[,], escapeBefore=[\], s1=[ABC,DEF,GHI\,JKL] will become
|
|
* [ABC] [DEF] [GHI,JKL]
|
|
*
|
|
* @params save \b in/out. After the first call to RTIOsapiUtility_strTokenEx
|
|
* save will point to the next unparsed character in s1. It will become the
|
|
* input for the next call.
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strTokenEx(
|
|
char *s1,
|
|
const char *delim,
|
|
const char *escapeAround,
|
|
const char *escapeBefore,
|
|
char **save);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Returns 2 raised to the power of y
|
|
*/
|
|
extern RTIOsapiDllExport unsigned int RTIOsapiUtility_pow2(int y);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiUtilityClass
|
|
* Returns the base-2 logarithm of x
|
|
*
|
|
* @param x Unsigned integer for which we want to calculate the base-2
|
|
* logarithm. It must be greater than 0.
|
|
*
|
|
* @param floor Indicates how to convert non-integer results to integers.
|
|
* When this parameter is 1, the function returns the largest integer not
|
|
* greater than the base-2 logarithm.
|
|
* When this parameter is 0, the function returns the smallest integer not less
|
|
* than the base-2 logarithm.
|
|
*/
|
|
extern RTIOsapiDllExport unsigned int RTIOsapiUtility_log2(
|
|
unsigned int x,
|
|
char floor);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* It removes blank at the head of a string. Accepts a NULL string.
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strTrimStart(char *str);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* It returns a pointer to the first character of a string that is not one of
|
|
* the charactersToSkip. If str or charactersToSkip are NULL, str is returned.
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strTrimStartEx(
|
|
char *str,
|
|
const char *charactersToSkip);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief This function trims leading and trailing whitespace characters from a
|
|
* given string. It modifies the input string in-place and returns a pointer to
|
|
* the first non-whitespace character.
|
|
*
|
|
* @param str \b InOut. A pointer to the string to be trimmed. This string
|
|
* must be modifiable and null-terminated. This parameter may be null.
|
|
*
|
|
* @return Returns a pointer to the first non-whitespace character in the input
|
|
* string. If the string is entirely made up of whitespace or is empty, it
|
|
* returns a pointer to the null terminator of the string.
|
|
*
|
|
* @note The function modifies the input string in-place. Therefore, the
|
|
* returned pointer and the input pointer will point to different locations in
|
|
* memory if the string has leading whitespace. Users should use the return
|
|
* value of the function to access the trimmed string. If users only use the
|
|
* input parameter, they will only see changes to the end of the string
|
|
* (trailing spaces removed), not any spaces that are skipped at the beginning.
|
|
* As the address returned from the function may be different from the address
|
|
* passed in, a temporary variable may be needed to receive the return value.
|
|
* This allows the original pointer to be used later to free the string if
|
|
* necessary. The function does not allocate or free any memory. It's the
|
|
* caller's responsibility to manage the memory of the input string.
|
|
*
|
|
* example:
|
|
* char *myString = malloc(100);
|
|
* strcpy(myString, " Hello, World! ");
|
|
* char *trimmedString = RTIOsapiUtility_strTrim(myString);
|
|
* printf("%s\n", trimmedString); // Outputs: "Hello, World!"
|
|
* free(myString); // Always free the original pointer, not the trimmed one
|
|
*
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strTrim(char *str);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief This function replaces a given string buffer with a new string.
|
|
*
|
|
* @param outputBuffer \b InOut. A pointer to the buffer to be replaced.
|
|
* @param str \b In. The new string to replace the buffer with. The string
|
|
* must be null-terminated.
|
|
*
|
|
* @return RTI_TRUE if the replacement was successful, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_strReplace(
|
|
char **outputBuffer,
|
|
const char *str);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief This function replaces a given string buffer with a given number of
|
|
* elements from a new string.
|
|
*
|
|
* @param outputBuffer \b InOut. A pointer to the buffer to be replaced.
|
|
* @param str \b In. The new string to replace the buffer with. The string
|
|
* must be null-terminated.
|
|
* @param strSize \b In. The number of elements to copy from the new string.
|
|
*
|
|
* @return RTI_TRUE if the replacement was successful, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_strReplaceSized(
|
|
char **outputBuffer,
|
|
const char *str,
|
|
size_t strSize);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
* This function replaces all occurrences of `strToReplace` within `str` with
|
|
* `strReplacement` and stores the result in `outputBuffer`. Accepts a NULL
|
|
* strReplacement (which will result in string trimming). The output buffer must
|
|
* be large enough to hold the resulting string, which can be larger than the
|
|
* original string. The returned string is NULL terminated.
|
|
*
|
|
* The `outputBuffer` parameter can be passed in as NULL and `outputBufferSize`
|
|
* is a pointer that will be set to the size needed in case `outputBuffer` is
|
|
* NULL or it is not NULL but the passed in size is not large enough. The caller
|
|
* of this function can then use the `outputBufferSize` if the function fails,
|
|
* to allocate a buffer of the right size and then call the function again.
|
|
*
|
|
* If `str` and `outputBuffer` are different, the function uses
|
|
* `RTIOsapiMemory_copy` to copy the replacement substring. If `str` and
|
|
* `outputBuffer` are the same, the function uses `RTIOsapiMemory_move` to
|
|
* handle overlapping memory regions safely.
|
|
*
|
|
* @param outputBuffer The buffer to store the resulting string.
|
|
* @param outputBufferSize The size of the output buffer.
|
|
* @param str The input string to be processed.
|
|
* @param strToReplace The substring to be replaced.
|
|
* @param strReplacement The substring to replace strToReplace with.
|
|
*
|
|
* @return RTI_TRUE if the replacement was successful, RTI_FALSE otherwise. If
|
|
* no instances of strToReplace are found, RTI_FALSE is returned.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_strReplaceString(
|
|
char *outputBuffer,
|
|
size_t *outputBufferSize,
|
|
const char *str,
|
|
const char *strToReplace,
|
|
const char *strReplacement);
|
|
|
|
/**
|
|
* @brief Removes a specified substring from a given string based on the removal
|
|
* type.
|
|
*
|
|
* This function removes a specified substring from the input string `str` based
|
|
* on the removal type specified by `type`. The removal type can be one of the
|
|
* following:
|
|
* - `OSAPI_STRING_REMOVE_PREFIX`: Removes the substring if it is a prefix of
|
|
* the input string.
|
|
* - `OSAPI_STRING_REMOVE_SUFFIX`: Removes the substring if it is a suffix of
|
|
* the input string.
|
|
* - `OSAPI_STRING_REMOVE_SUBSTRING`: Removes the first occurrence of the
|
|
* substring from the input string.
|
|
*
|
|
* @param str The input string from which the substring will be removed. This
|
|
* string is modified in place.
|
|
* @param match Set to TRUE if the string was found and removed. Can be NULL.
|
|
* @param sub The substring to be removed from the input string.
|
|
* @param type The type of removal operation to be performed. It should be one
|
|
* of the values defined in `RTIOsapiStringRemoveType`.
|
|
* @return A pointer to the modified input string. If the substring is not
|
|
* found, the original string is returned. If the removal type is invalid, the
|
|
* function returns NULL.
|
|
*
|
|
* @note The input string `str` must be null-terminated. The function modifies
|
|
* the input string in place.
|
|
* @note If `sub` is an empty string, the function returns the original string
|
|
* without any modifications.
|
|
* @note If substring is larger than the original string, the function return
|
|
* the original string.
|
|
*/
|
|
char *RTIOsapiUtility_strRemove(
|
|
char *str,
|
|
RTIBool *match,
|
|
const char *sub,
|
|
RTIOsapiStringRemoveType type);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* This function allocates and returns a string that contains a
|
|
* copy of the contents in str.
|
|
*
|
|
* Returns NULL if the new string couldn't be
|
|
* allocated. Otherwise, returns the new string.
|
|
*
|
|
* The returned string must be freed with
|
|
* RTIOsapiHeap_freeString
|
|
*/
|
|
extern RTIOsapiDllExport char *RTIOsapiUtility_strDuplicate(const char *str);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Initialize the seed for the random number generator.
|
|
* Windows only: this function must be invoked per thread.
|
|
* In Windows the seed is thread-based. If the seed is not specified in a thread
|
|
* it will use the constant 1.
|
|
*/
|
|
extern RTIOsapiDllExport void RTIOsapiUtility_srandWithSeed(unsigned int seed);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Initialize the seed from the time for the random number generator
|
|
*/
|
|
extern RTIOsapiDllExport void RTIOsapiUtility_srand(void);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Generates a random number between 0 and RAND_MAX inclusive.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_rand(void);
|
|
|
|
|
|
#define RTI_OSAPI_UTILITY_RETCODE_OK 0
|
|
#define RTI_OSAPI_UTILITY_RETCODE_ERROR -1
|
|
#define RTI_OSAPI_UTILITY_RETCODE_NOT_SUPPORTED -2
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiUtilityClass
|
|
* @brief Generates a cryptographically secure random number between 0 and
|
|
* UINT_MAX inclusive.
|
|
*
|
|
* Calls to RTIOsapiUtility_srandWithSeed or RTIOsapiUtility_srand do not have
|
|
* any influence over the result of this function.
|
|
*
|
|
* If security is not a concern, you should call RTIOsapiUtility_rand instead,
|
|
* which is faster.
|
|
*
|
|
* @param buffer Pointer to the buffer where the number will be stored. The
|
|
* buffer contents do not need to be initialized.
|
|
*
|
|
* @pre buffer must not be NULL
|
|
*
|
|
* @return RTI_OSAPI_UTILITY_RETCODE_OK if the number could be correctly
|
|
* generated. RTI_OSAPI_UTILITY_RETCODE_ERROR if buffer is NULL or if the
|
|
* number could not be correctly generated.
|
|
* RTI_OSAPI_UTILITY_RETCODE_NOT_SUPPORTED if we currently do not support
|
|
* generating cryptographically secure random numbers for this architecture.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_randSecure(unsigned int *buffer);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Generates a random number between rangeMin and rangeMax inclusive
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_randRange(
|
|
int rangeMin,
|
|
int rangeMax);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Returns RTI_TRUE if the number x is NaN, otherwise RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_isnanf(float x);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* RTI_TRUE if the number x is NaN, otherwise RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_isnan(double x);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Returns RTI_TRUE if the number x is Infinity, otherwise RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_isinff(float x);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Returns RTI_TRUE if the number x is Infinity, otherwise RTI_FALSE
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_isinf(double x);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Returns RTI_TRUE if casting x to float is safe, otherwise RTI_FALSE
|
|
* See: FLP34-C, https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152068
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_isDoubleToFloatSafe(double x);
|
|
|
|
/** @internal @ingroup RTIOsapiUtilityClass
|
|
* @brief Compute the Popcount of a integer value. (get number of enabled bits).
|
|
* @return the number of bits enabled on a 32 bits value.
|
|
*/
|
|
#define RTIOsapiUtility_getEnabledBitCount RTILog_getEnabledBitCount
|
|
|
|
/** @internal @ingroup RTIOsapiUtilityClass
|
|
* @brief get a value that only countain the least significant bit of the input
|
|
* value.
|
|
* @return The value with only the least significant bit enabled.
|
|
*/
|
|
extern RTIOsapiDllExport unsigned int
|
|
RTIOsapiUtility_getLeastSignificantEnabledBit(unsigned int i);
|
|
|
|
/** @internal @ingroup RTIOsapiUtilityClass
|
|
* @brief Normalize a value from a range [rMin, rMax] linearly into a given
|
|
* target range [targetMin, targetMax].
|
|
* @return The value inside of the target range.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_linearNormalization(
|
|
int x,
|
|
int rMin,
|
|
int rMax,
|
|
int targetMin,
|
|
int targetMax);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Maximum length of an error string
|
|
*/
|
|
#define RTI_OSAPI_ERROR_STRING_MAX_SIZE (128)
|
|
|
|
#define RTI_OSAPI_UNKNOWN_ERROR_STRING "Unknown error"
|
|
|
|
|
|
#if defined(RTI_WIN32) || defined(RTI_WINCE)
|
|
#define RTIOsapiUtility_getError GetLastError
|
|
#define RTIOsapiUtility_setError SetLastError
|
|
#else
|
|
#ifdef RTI_VXWORKS
|
|
#ifndef errno
|
|
#define errno errnoGet()
|
|
#endif
|
|
#endif
|
|
#define RTIOsapiUtility_getError() errno
|
|
#define RTIOsapiUtility_setError(x) errno = (x)
|
|
#endif
|
|
|
|
#define RTIOsapiUtility_reportFileErrno( \
|
|
instrumentBit__, \
|
|
logTemplate__, \
|
|
fileName__) \
|
|
RTIOsapiUtility_reportFileErrnoI( \
|
|
RTI_FUNCTION_NAME, \
|
|
instrumentBit__, \
|
|
logTemplate__, \
|
|
fileName__)
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Generates the error string corresponding to an OS error
|
|
*/
|
|
extern RTIOsapiDllExport const char *RTIOsapiUtility_getErrorString(
|
|
char *buffer,
|
|
size_t bufferSize,
|
|
int errnum);
|
|
|
|
/** @internal
|
|
* \ingroup RTIOsapiUtilityClass
|
|
* Log an errno and corresponding string of a file error.
|
|
*/
|
|
extern RTIOsapiDllExport void RTIOsapiUtility_reportFileErrnoI(
|
|
const char *functionName,
|
|
RTILogBitmap instrumentBit,
|
|
const struct RTILogMessageTemplate logTemplate,
|
|
const char *fileName);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Casts the specified integer value as a pointer
|
|
*/
|
|
extern RTIOsapiDllExport void *RTIOsapiUtility_intToPointer(
|
|
const RTI_INT32 intValue);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Casts the specified pointer value as an integer
|
|
*/
|
|
extern RTIOsapiDllExport RTI_INT32
|
|
RTIOsapiUtility_pointerToInt(const void *pointer);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Casts the specified pointer value as a 64-bit unsigned integer
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT64
|
|
RTIOsapiUtility_pointerToUInt64(const void *pointer);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Calculates the crc32 for the input data.
|
|
* @param data Input data for calculating the crc.
|
|
* @param length Length of the input data.
|
|
* @param previousCrc32 If different to zero, the new crc will be calculated
|
|
* using this as the base. That allows to calculate the crc in multiple
|
|
* stages (for example, if we don't have all the data at the beginning).
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT32 RTIOsapiUtility_crc32(
|
|
const void *data,
|
|
RTI_UINT32 length,
|
|
RTI_UINT32 previousCrc32);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Returns true if the machine is little endian, false otherwise
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_isNativeLittleEndian(void);
|
|
|
|
/** @internal \ingroup RTINetioAliasListType
|
|
* @brief Converts the specified string array into a string containing each
|
|
* element in the array separated by the specified delimiter.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_stringArrayToDelimitedString(
|
|
char *dst,
|
|
size_t dst_max,
|
|
char delim,
|
|
const char **stringArray,
|
|
int stringArrayLength);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Validates a single UTF-8 character starting at the beginning of the
|
|
* input string.
|
|
* @param data Input string containing the UTF-8 character.
|
|
* @return If the character is valid, the return value is 1, 2, 3, or 4
|
|
* depending on the size of the character. Else if the character is invalid the
|
|
* function returns -1.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_stringUtf8ValidateChar(
|
|
const char *inputString);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Validates an input string contains valid UTF-8 characters.
|
|
* @param data Input string to validate.
|
|
* @return Boolean value indicating whether the string contains only UTF-8
|
|
* characters or not.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_stringUtf8ValidateString(const char *inputString);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Extracts the first UTF-8 character of a given input string. The value of
|
|
* the character is stored in a unsigned 32-bit integer.
|
|
* @param codepoint Output parameter in which the value of the UTF-8 character
|
|
* is copied.
|
|
* @param inputString Input string containing the UTF-8 character.
|
|
* @return Integer value indicating the size of the UTF-8 character (i.e.,
|
|
* whether it takes 1, 2, 3, or 4 bytes. If the input string does not contain
|
|
* a valid UTF-8 character the function returns -1.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_stringUtf8ToCodepoint(
|
|
RTI_UINT32 *codepoint,
|
|
const char *inputString);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Writes a UTF-8 character in a given input string. The value of
|
|
* the character is provided in a unsigned 32-bit integer that contains the
|
|
* Unicode point.
|
|
* If the outputString is NULL, the function returns the number of bytes that
|
|
* would have been written without operating on the NULL parameter.
|
|
* @param outputString Input string containing the UTF-8 character.
|
|
* @param outputStringLength Number of bytes that can be written in the string.
|
|
* @param codepoint Value of the UTF-8 character.
|
|
* @return Integer value indicating the size of the UTF-8 character (i.e.,
|
|
* whether it takes 1, 2, 3, or 4 bytes. If the outputString has insufficient
|
|
* to allocate the code point, then the function returns the number of bytes
|
|
* that would have been necessary in native form (e.g., -1 if one byte were
|
|
* necessary). If the code point is out of the valid range (i.e.,
|
|
* codepoint > 0x10FFFF || (codepoint >= 0xD800 && codepoint <= 0xDFFF), the
|
|
* function returns -5.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_stringUtf8FromCodepoint(
|
|
char *outputString,
|
|
const RTI_UINT32 outputStringLength,
|
|
const RTI_UINT32 codepoint);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Constructs a UTF-16 surrogate pair given a Unicode code point.
|
|
* The Unicode point must be between U+10000 and U+10FFFF.
|
|
* @param highSurrogate Output parameter with first 16-bit code unit.
|
|
* @param lowSurrogate Output parameter with second 16-bit code unit.
|
|
* @param codepoint Unicode point from which to extract the surrogate pair.
|
|
* @return Boolean value indicating whether the operation succeeded or not.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_stringUtf16ToSurrogatePair(
|
|
RTI_UINT16 *highSurrogate,
|
|
RTI_UINT16 *lowSurrogate,
|
|
const RTI_UINT32 codepoint);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Constructs a Unicode code point given a UTF-16 surrogate pair.
|
|
* The hight surrogate must be between 0xD800 and 0xDBFF and the low
|
|
* surrogate must be between 0xDC00 and 0xDFFF.
|
|
* @param unicode Unicode point from which to extract the surrogate pair.
|
|
* @param highSurrogate First 16-bit code unit.
|
|
* @oaram lowSurrogate Second 16-bit code unit.
|
|
* @return Boolean value indicating whether the operation succeeded or not.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_stringUtf16FromSurrogatePair(
|
|
RTI_UINT32 *codepoint,
|
|
const RTI_UINT16 highSurrogate,
|
|
const RTI_UINT16 lowSurrogate);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* This method converts a string encoded in UTF-8 into a wide string
|
|
* (composed of 16-bit unsigned integer characters) encoded in UTF-16
|
|
* format. This method adds a null terminating character at the end of the
|
|
* output string and assumes that the input string is terminated with a null
|
|
* terminating character. If the inputString is NULL, then the method
|
|
* only calculates the number of bytes that would have been written
|
|
* (excluding the null terminating character).
|
|
* @param outputString Output parameter with the wide string encoded in
|
|
* UTF-16 format.
|
|
* @param outputStringLength Size of the wide string array.
|
|
* @param inputString Input string encoded in UTF-8.
|
|
* @return Integer value indicating the number of wide characters that have
|
|
* been written (excluding the terminating null character).
|
|
* In case of an error, the function returns -1 if the output string has
|
|
* insufficient space to allocate the UTF-16 string, -2 if the input string is
|
|
* invalid UTF-8, and -3 if the input string has code points that are not part
|
|
* of the Basic Multilingual Plane.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_stringUtf8ToUtf16(
|
|
RTI_UINT16 *outputString,
|
|
RTI_UINT32 outputStringLength,
|
|
const char *inputString);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* Converts a wide string encoded in UTF-16 into a string encoded in UTF-8
|
|
* format. The function adds a null terminating character at the end of the
|
|
* output string.
|
|
* If the inputString is NULL, then the method only calculates the number of
|
|
* bytes that would have been written (excluding the null terminating
|
|
* character).
|
|
* @param outputString Output parameter with the string encoded in
|
|
* UTF-8 format.
|
|
* @param outputStringLength Size of the string array.
|
|
* @param inputString Input wide string encoded in UTF-16.
|
|
* @return Integer value indicating the number of bytes that have been written
|
|
* (excluding the null terminating character).
|
|
* In case of an error, the function returns -1 has insufficient space to
|
|
* allocate the UTF-8 string, and -2 if the input string is an invalid UTF-16
|
|
* string (e.g., it includes characters out of the Basic Multilingual Plane.
|
|
*/
|
|
extern RTIOsapiDllExport int RTIOsapiUtility_stringUtf16ToUtf8(
|
|
char *outputString,
|
|
RTI_UINT32 outputStringLength,
|
|
const RTI_UINT16 *inputString,
|
|
RTI_UINT32 inputStringLength);
|
|
|
|
extern RTIOsapiDllExport const char *RTIOsapiUtility_strGetToken(
|
|
size_t *tokenLength,
|
|
const char *s,
|
|
char c);
|
|
|
|
extern RTIOsapiDllExport size_t
|
|
RTIOsapiUtility_strGetTokenCount(const char *string, char separator);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Safe copy of src into dst.
|
|
*
|
|
* This is a macro only function where the output parameter dst does not need
|
|
* to be a pointer.
|
|
*
|
|
* @return RTI_FALSE if src is out of range.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_sizeToInt32(RTI_INT32 dst, size_t src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Safe copy of src into dst.
|
|
*
|
|
* This is a macro only function where the output parameter dst does not need
|
|
* to be a pointer.
|
|
*
|
|
* @return RTI_FALSE if src is out of range.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_sizeToUInt32(RTI_UINT32 dst, size_t src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Safe copy of src into dst.
|
|
*
|
|
* This is a macro only function where the output parameter dst does not need
|
|
* to be a pointer.
|
|
*
|
|
* @return RTI_FALSE if src is out of range.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_sizeToInt64(RTI_UINT64 dst, size_t src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Safe copy of src into dst.
|
|
*
|
|
* This is a macro only function where the output parameter dst does not need
|
|
* to be a pointer.
|
|
*
|
|
* @return RTI_FALSE if src is out of range.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_int32ToSize(size_t dst, RTI_INT32 src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Safe copy of src into dst.
|
|
*
|
|
* This is a macro only function where the output parameter dst does not need
|
|
* to be a pointer.
|
|
*
|
|
* @return RTI_FALSE if src is out of range.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_int64ToSize(size_t dst, RTI_INT64 src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Safe copy of src into dst.
|
|
*
|
|
* This is a macro only function where the output parameter dst does not need
|
|
* to be a pointer.
|
|
*
|
|
* @return RTI_FALSE if src is out of range.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_uint64ToSize(size_t dst, RTI_UINT64 src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Compares equality of two float number.
|
|
*
|
|
* Note: This is a macro only function.
|
|
*
|
|
* When comparing values of float type for equality or non-equality, the results
|
|
* may vary depending on the processor being used and compiler settings.
|
|
*
|
|
* It is recommended to use this function instead of the operators '==' and
|
|
*'!=' to compare equality of float numbers.
|
|
*
|
|
* @param[in] first. First float number.
|
|
* @param[in] second. Second float number.
|
|
*
|
|
* @return RTI_TRUE if the two numbers are nearly equal.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_floatNearlyEqual(float first, float second);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Compares equality of two double number.
|
|
*
|
|
* Note: This is a macro only function.
|
|
*
|
|
* When comparing values of double type for equality or non-equality, the
|
|
*results may vary depending on the processor being used and compiler settings.
|
|
*
|
|
* It is recommended to use this function instead of the operators '==' and
|
|
*'!=' to compare equality of double numbers.
|
|
*
|
|
* @param[in] first. First double number.
|
|
* @param[in] second. Second double number.
|
|
*
|
|
* @return RTI_TRUE if the two numbers are nearly equal.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_doubleNearlyEqual(double first, double second);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Safe copy of src into dst.
|
|
*
|
|
* @return RTI_FALSE if src is out of range.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_int64ToDouble(RTI_DOUBLE64 *dst, RTI_INT64 src);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get uint32__ + n__ without overflowing. If uint32__ is
|
|
* already maximized, then return uint32__. Useful for
|
|
* avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addUInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_UINT32 RTIOsapiUtility_uInt32PlusN(RTI_UINT32 uint32__, RTI_UINT32 n__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get uint32__ - n__ without overflowing. If uint32__ is
|
|
* already minimized, then return uint32__. Useful for
|
|
* avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subUInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_UINT32 RTIOsapiUtility_uInt32MinusN(RTI_UINT32 uint32__, RTI_UINT32 n__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get uint32__ + 1 without overflowing. If uint32__ is
|
|
* already maximized, then return uint32__. Useful for
|
|
* avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addUInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_UINT32 RTIOsapiUtility_uInt32Plus1(RTI_UINT32 uint32__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Increment uint32__ by one without overflowing. If uint32__
|
|
* is already maximized, then don't change it.
|
|
* Useful for avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addUInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
void RTIOsapiUtility_uInt32Plusplus(RTI_UINT32 uint32__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get uint32__ - 1 without underflowing. If uint32__ is
|
|
* already minimized, then return uint32__. Useful for
|
|
* avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subUInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT32
|
|
RTIOsapiUtility_uInt32Minus1(RTI_UINT32 uint32__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Decrement uint32__ by one without underflowing. If uint32__
|
|
* is already minimized, then don't change it.
|
|
* Useful for avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subUInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport void RTIOsapiUtility_uInt32Minusminus(
|
|
RTI_UINT32 uint32__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Increment uint32__ by n__ without overflowing. If uint32__
|
|
* is already maximized, then don't change it.
|
|
* Useful for avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addUInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
void RTIOsapiUtility_uInt32Increment(RTI_UINT32 uint32__, RTI_UINT32 n__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get int32__ + n__ without overflowing. If int32__ is
|
|
* already maximized or minimized, then return int32__. Useful for
|
|
* avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_INT32 RTIOsapiUtility_int32PlusN(RTI_INT32 int32__, RTI_INT32 n__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get int32__ - n__ without overflowing. If int32__ is
|
|
* already maximized or minimized, then return int32__. Useful for
|
|
* avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_INT32 RTIOsapiUtility_int32MinusN(RTI_INT32 int32__, RTI_INT32 n__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get int32__ + 1 without overflowing. If int32__ is already
|
|
* maximized, then return int32__. Useful for avoiding
|
|
* CERT_INT32-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_INT32 RTIOsapiUtility_int32Plus1(RTI_INT32 int32__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Increment int32__ by one without overflowing. If int32__
|
|
* is already maximized, then don't change it.
|
|
* Useful for avoiding CERT_INT32-C Coverity issues.
|
|
* @details Note that this macro is equivalent to preincrement (++value). If you
|
|
* need a postincrement (value++), you need to cache the value.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
void RTIOsapiUtility_int32Plusplus(RTI_INT32 int32__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get int32__ - 1 without underflowing. If int32__ is already
|
|
* minimized, then return int32__. Useful for avoiding
|
|
* CERT_INT32-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport RTI_INT32 RTIOsapiUtility_int32Minus1(RTI_INT32 int32__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Decrement int32__ by one without underflowing. If int32__
|
|
* is already minimized, then don't change it.
|
|
* Useful for avoiding CERT_INT32-C Coverity issues.
|
|
* @details Note that this macro is equivalent to predecrement (--value). If you
|
|
* need a postdecrement (value--), you need to cache the value.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport void RTIOsapiUtility_int32Minusminus(RTI_INT32 int32__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Increment int32__ by n__ without overflowing. If int32__ is
|
|
* already maximized or minimized, then don't change it. Useful for
|
|
* avoiding CERT_INT32-C Coverity issues.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
void RTIOsapiUtility_int32Increment(RTI_INT32 int32__, RTI_INT32 n__);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Decrement int32__ by n__ without underflowing. If int32__ is
|
|
* already maximized or minimized, then don't change it. Useful for
|
|
* avoiding CERT_INT32-C Coverity issues.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subInt32 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
void RTIOsapiUtility_int32Decrement(RTI_INT32 int32__, RTI_INT32 n__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get int64__ + n__ without overflowing. If int64__ is
|
|
* already maximized or minimized, then return int64__. Useful for
|
|
* avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addInt64 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_INT64 RTIOsapiUtility_int64PlusN(RTI_INT64 int64__, RTI_INT64 n__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get int64__ - n__ without overflowing. If int64__ is
|
|
* already maximized or minimized, then return int64__. Useful for
|
|
* avoiding CERT_INT30-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subInt64 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_INT64 RTIOsapiUtility_int64MinusN(RTI_INT64 int64__, RTI_INT64 n__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get int64__ + 1 without overflowing. If int64__ is already
|
|
* maximized, then return int64__. Useful for avoiding
|
|
* CERT_INT64-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addInt64 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
RTI_INT64 RTIOsapiUtility_int64Plus1(RTI_INT64 int64__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Increment int64__ by one without overflowing. If int64__
|
|
* is already maximized, then don't change it. Useful for
|
|
* avoiding CERT_INT64-C Coverity issues.
|
|
* @details Note that this macro is equivalent to preincrement (++value). If you
|
|
* need a postincrement (value++), you need to cache the value.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addInt64 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
void RTIOsapiUtility_int64Plusplus(RTI_INT64 int64__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Get int64__ - 1 without underflowing. If int64__ is already
|
|
* minimized, then return int64__. Useful for avoiding
|
|
* CERT_INT64-C Coverity issues.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subInt64 instead.
|
|
*/
|
|
extern RTIOsapiDllExport RTI_INT64 RTIOsapiUtility_int64Minus1(RTI_INT64 int64__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Decrement int64__ by one without underflowing. If int64__
|
|
* is already minimized, then don't change it. Useful for
|
|
* avoiding CERT_INT64-C Coverity issues.
|
|
* @details Note that this macro is equivalent to predecrement (--value). If you
|
|
* need a postdecrement (value--), you need to cache the value.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_subInt64 instead.
|
|
*/
|
|
extern RTIOsapiDllExport void RTIOsapiUtility_int64Minusminus(RTI_INT64 int64__);
|
|
|
|
/** @internal \ingroup RTIOsapiUtilityClass
|
|
* @brief Increment int64__ by n__ without overflowing. If int64__ is
|
|
* already maximized or minimized, then don't change it. Useful for
|
|
* avoiding CERT_INT64-C Coverity issues.
|
|
*
|
|
* This is a macro-only function where the in/out parameter does
|
|
* not need to be a pointer.
|
|
*
|
|
* @deprecated This API is deprecated due to performance reasons and should
|
|
* no longer be used. Use RTIOsapiUtility_addInt64 instead.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
void RTIOsapiUtility_int64Increment(RTI_INT64 int64__, RTI_INT64 n__);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @brief Adds an int32 value to another int32 value, checking for overflow
|
|
* first.
|
|
*
|
|
* @param[out] out The result of the addition if it does not overflow.
|
|
* @param[in] a The value to which b will be added.
|
|
* @param[in] b The value to add to a.
|
|
*
|
|
* @return RTI_TRUE if the addition does not overflow, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_addInt32(RTI_INT32 *out, RTI_INT32 a, RTI_INT32 b);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @brief Subtracts an int32 value from another int32 value, checking
|
|
* for underflow first.
|
|
*
|
|
* @param[out] out The result of the subtraction if it does not underflow.
|
|
* @param[in] a The value from which b will be subtracted.
|
|
* @param[in] b The value to subtract from a.
|
|
*
|
|
* @return RTI_TRUE if the subtraction does not underflow, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_subInt32(RTI_INT32 *out, RTI_INT32 a, RTI_INT32 b);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @brief Adds an int64 value to another int64 value, checking for overflow
|
|
* first.
|
|
*
|
|
* @param[out] out The result of the addition if it does not overflow.
|
|
* @param[in] a The value to which b will be added.
|
|
* @param[in] b The value to add to a.
|
|
*
|
|
* @return RTI_TRUE if the addition does not overflow, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_addInt64(RTI_INT64 *out, RTI_INT64 a, RTI_INT64 b);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @brief Subtracts an int64 value from another int64 value, checking
|
|
* for underflow first.
|
|
*
|
|
* @param[out] out The result of the subtraction if it does not underflow.
|
|
* @param[in] a The value from which b will be subtracted.
|
|
* @param[in] b The value to subtract from a.
|
|
*
|
|
* @return RTI_TRUE if the subtraction does not underflow, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_subInt64(RTI_INT64 *out, RTI_INT64 a, RTI_INT64 b);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @brief Adds a uint32 value to another uint32 value, checking for
|
|
* overflow first.
|
|
*
|
|
* @param[out] out The result of the addition if it does not overflow.
|
|
* @param[in] a The value to which b will be added.
|
|
* @param[in] b The value to add to a.
|
|
*
|
|
* @return RTI_TRUE if the addition does not overflow, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_addUInt32(RTI_UINT32 *out, RTI_UINT32 a, RTI_UINT32 b);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @brief Subtracts a uint32 value from another uint32 value, checking for
|
|
* underflow first.
|
|
*
|
|
* @param[out] out The result of the subtraction if it does not underflow.
|
|
* @param[in] a The value from which b will be subtracted.
|
|
* @param[in] b The value to subtract from a.
|
|
*
|
|
* @return RTI_TRUE if the subtraction does not underflow, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_subUInt32(RTI_UINT32 *out, RTI_UINT32 a, RTI_UINT32 b);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @brief Adds a uint64 value to another uint64 value, checking for
|
|
* overflow first.
|
|
*
|
|
* @param[out] out The result of the addition if it does not overflow.
|
|
* @param[in] a The value to which b will be added.
|
|
* @param[in] b The value to add to a.
|
|
*
|
|
* @return RTI_TRUE if the addition does not overflow, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_addUInt64(RTI_UINT64 *out, RTI_UINT64 a, RTI_UINT64 b);
|
|
|
|
/**
|
|
* @internal \ingroup RTIOsapiUtilityClass
|
|
*
|
|
* @brief Subtracts a uint64 value from another uint64 value, checking for
|
|
* underflow first.
|
|
*
|
|
* @param[out] out The result of the subtraction if it does not underflow.
|
|
* @param[in] a The value from which b will be subtracted.
|
|
* @param[in] b The value to subtract from a.
|
|
*
|
|
* @return RTI_TRUE if the subtraction does not underflow, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_subUInt64(RTI_UINT64 *out, RTI_UINT64 a, RTI_UINT64 b);
|
|
|
|
/** @internal
|
|
* @brief Enables developers to instrument the execution time of a code block.
|
|
*/
|
|
#define RTIOsapiUtility_timeInstrumentationStart() \
|
|
{ \
|
|
struct RTINtpTime startTime__ = RTI_NTP_TIME_ZERO; \
|
|
struct RTINtpTime endTime__ = RTI_NTP_TIME_ZERO; \
|
|
struct RTINtpTime elapsedTime__ = RTI_NTP_TIME_ZERO; \
|
|
unsigned int totalTimeMicroSec__ = 0; \
|
|
int sec__ = 0; \
|
|
unsigned int microsec__ = 0; \
|
|
\
|
|
if (!RTIOsapiUtility_getTime(&startTime__)) { \
|
|
RTILogMessage_print( \
|
|
RTI_LOG_PRINT_FORMAT_MASK_ALL, \
|
|
RTI_LOG_BIT_EXCEPTION, \
|
|
MODULE_OSAPI, \
|
|
&RTI_LOG_GET_FAILURE_s, \
|
|
"current time"); \
|
|
}
|
|
|
|
#define RTIOsapiUtility_timeInstrumentationEnd(instrumented_block_name__) \
|
|
if (!RTIOsapiUtility_getTime(&endTime__)) { \
|
|
RTILogMessage_print( \
|
|
RTI_LOG_PRINT_FORMAT_MASK_ALL, \
|
|
RTI_LOG_BIT_EXCEPTION, \
|
|
MODULE_OSAPI, \
|
|
&RTI_LOG_GET_FAILURE_s, \
|
|
"current time"); \
|
|
} \
|
|
\
|
|
RTINtpTime_subtract(elapsedTime__, endTime__, startTime__); \
|
|
\
|
|
RTINtpTime_unpackToMicrosec(sec__, microsec__, elapsedTime__); \
|
|
totalTimeMicroSec__ = sec__ * 1000000 + microsec__; \
|
|
RTILogParamString_printPlain( \
|
|
"%s took %d us\n", \
|
|
(instrumented_block_name__), \
|
|
totalTimeMicroSec__); \
|
|
}
|
|
|
|
/** @internal
|
|
* TRUST-756: Helper macro to prevent a pointer value from being speculated.
|
|
* It addresses the Spectre Variant 1 vulnerability in a platform independent
|
|
* way. The technique that we employ here is called Speculative Load Hardening.
|
|
*
|
|
* The events contributing to speculative execution in coverity typically start
|
|
* with an if/else/for/while block.
|
|
* Use this macro inside the block if the true branch is taken otherwise
|
|
* use it just outside the block by passing the condition by prepending it with
|
|
* !.
|
|
*
|
|
* For reference coverity will report something like this as the first
|
|
* contributing event for the issue:
|
|
* compare_value: Comparing <condition>
|
|
* Condition <condition>, taking true/false branch
|
|
* If the true branch is taken you would pass <condition> to this macro while
|
|
* using it inside the block.
|
|
* If the false branch is taken you would pass !<condition> to this macro while
|
|
* using it outside the block.
|
|
*
|
|
* @brief
|
|
* The basic idea to avoid speculative execution of an if/else/for/while block
|
|
* is to force the entry condition execution using a ternary operator. A ternary
|
|
* operator (or a conditional update) based assignment is guaranteed to be
|
|
* implemented in a branchless way on most modern architectures:
|
|
* https://llvm.org/docs/SpeculativeLoadHardening.html#high-level-mitigation-approach
|
|
*
|
|
* @details
|
|
* The AUDIT.SPECULATIVE_EXECUTION_DATA_LEAK checker from Coverity detects
|
|
* Spectre Variant 1 vulnerabilities. This is detailed in this blog post:
|
|
* https://www.synopsys.com/blogs/software-security/detecting-spectre-vulnerability-exploits-with-static-analysis.html
|
|
*
|
|
* This macro adopts the mitigation approach detailed in this post for Variant
|
|
* 1:
|
|
* https://llvm.org/docs/SpeculativeLoadHardening.html#high-level-mitigation-approach
|
|
*
|
|
* For more information about Spectre and Speculative Execution you can also
|
|
* read the paper: https://spectreattack.com/spectre.pdf
|
|
*
|
|
*
|
|
* @param pointer__
|
|
* The pointer to harden against speculative execution.
|
|
* This is typically reported by coverity under the second event contributing to
|
|
* the issue. It should be shown as 'compared_memory_access'.
|
|
*
|
|
* @param pointerType__
|
|
* The type used to cast the result from the ternary operator (conditional
|
|
* update).
|
|
*
|
|
* @param speculatedCondition__
|
|
* The condition that may be bypassed by speculation. For an if/else
|
|
* if/for/while block copy the same condition as is. For the else block copy the
|
|
* if condition by prefixing it with a !. This is typically reported by coverity
|
|
* as the first event contributing to the issue. It should be shown as
|
|
* 'compare_value'.
|
|
*
|
|
*/
|
|
#define RTIOsapiUtility_preventPointerSpeculation( \
|
|
pointer__, \
|
|
pointerType__, \
|
|
speculatedCondition__) \
|
|
{ \
|
|
const size_t RTI_OSAPI_UTILITY_ALL_BITS_ZERO = 0; \
|
|
const size_t RTI_OSAPI_UTILITY_ALL_BITS_ONE = \
|
|
~(RTI_OSAPI_UTILITY_ALL_BITS_ZERO); \
|
|
size_t pointerMask = RTI_OSAPI_UTILITY_ALL_BITS_ONE; \
|
|
\
|
|
pointerMask = (!(speculatedCondition__)) ? RTI_OSAPI_UTILITY_ALL_BITS_ZERO \
|
|
: pointerMask; \
|
|
(pointer__) = (pointerType__) ((size_t) (pointer__) &pointerMask); \
|
|
}
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Swap the endianess of a 32-bit unsigned integer, from big-endian to
|
|
* little-endian or vice versa.
|
|
* This macro is safe regarding overflow and underflow.
|
|
*/
|
|
extern RTIOsapiDllExport RTI_UINT32
|
|
RTIOsapiUtility_swapEndianessUInt32(RTI_UINT32 value);
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Calculates the length of a base64 string derived from an input of
|
|
* the inputLen length. The input and output length are given in bytes. Note
|
|
* the result does not account for null termination.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
size_t RTIOsapiUtility_getEncodedBase64Length(size_t inputLen);
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Calculates the maximum length of a byte array derived from a base64
|
|
* string of base64Len length. The actual byte count can be a few bytes short.
|
|
*/
|
|
extern RTIOsapiDllExport
|
|
size_t RTIOsapiUtility_getDecodedBase64MaxLength(size_t base64Len);
|
|
|
|
/**
|
|
* @internal
|
|
* Encodes a raw byte array (input) into a base64 string (output) in accordance
|
|
* with RFC 4648. The string is not null terminated.
|
|
*
|
|
* @param[out] base64 the resulting base64 representation of the input. Must be
|
|
* allocated to a suitable size (see RTIOsapiUtility_getEncodedBase64Size).
|
|
* The output is not null terminated.
|
|
* @param inpuBytes The byte array to be converted to base64.
|
|
* @param inputLength the number of bytes in the input array to be converted to
|
|
* base64.
|
|
*
|
|
* @return Bool informing if the operation was successful.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_base64Encode(
|
|
char *base64,
|
|
const RTI_UINT8 *bytesInput,
|
|
size_t inputLength);
|
|
|
|
/**
|
|
* @internal
|
|
* Encodes a raw byte array (input) into a base64url string (output) in
|
|
* accordance with RFC 4648. The string is not null terminated.
|
|
*
|
|
* @param[out] base64 the resulting base64url representation of the input. Must
|
|
* be allocated to a suitable size (see
|
|
* RTIOsapiUtility_getEncodedBase64Size).
|
|
* @param inputBytes The byte array to be converted to base64url.
|
|
* @param inputLength the number of bytes in the input array to be converted to
|
|
* base64url.
|
|
*
|
|
* @return Bool informing if the operation was successful.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_base64UrlEncode(
|
|
char *base64,
|
|
const RTI_UINT8 *bytesInput,
|
|
size_t inputLength);
|
|
|
|
/**
|
|
* @internal
|
|
* Decodes a base64 or base64url string (input). All illegal characters will be
|
|
* ignored and can handle both arrays with and without line separators.
|
|
*
|
|
* @param[out] bytesOutput the resulting byte array resulting from the base64
|
|
* input. Must be allocated to a suitable size (see
|
|
* RTIOsapiUtility_getDecodedBase64MaxSize).
|
|
* @param base64 The base64(base64url)-encoded string
|
|
* @param inputLength The length of the input.
|
|
*
|
|
* @return The number of bytes written to the output array.
|
|
*/
|
|
extern RTIOsapiDllExport size_t RTIOsapiUtility_base64Decode(
|
|
RTI_UINT8 *bytesOutput,
|
|
const char *base64,
|
|
size_t inputLength);
|
|
|
|
/**
|
|
* @internal
|
|
* Encodes a raw byte array (input) into a hexadecimal string (output).
|
|
*
|
|
* @param[out] hexBuffer the resulting hexadecimal representation of the input.
|
|
* Must be allocated to a suitable size (2 * inputLength + 1 for null
|
|
* termination).
|
|
* @param hexBufferSize The size of the hex buffer.
|
|
* @param bytesInput The byte array to be converted to hexadecimal.
|
|
* @param inputLength the number of bytes in the input array to be converted to
|
|
* hexadecimal.
|
|
*
|
|
* @return RTI_TRUE if the operation was successful, RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool RTIOsapiUtility_hexEncode(
|
|
char *hex,
|
|
size_t hexBufferSize,
|
|
const RTI_UINT8 *bytesInput,
|
|
size_t inputLength);
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Get the HOME directory for the current user.
|
|
* Only supported on UNIX-like systems.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getHome(char *buffer, size_t bufferSize);
|
|
|
|
/** @internal
|
|
* @brief If set it will overwrite the default directory where the user data
|
|
* is stored.
|
|
*/
|
|
#define RTI_CONNEXT_USER_HOME "RTI_CONNEXT_USER_HOME"
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Get the directory where an application can store data in the system.
|
|
*
|
|
* On Unix, the default directory is $HOME/.rti
|
|
* On Windows, the default directory is %LOCALAPPDATA%\Rti
|
|
*
|
|
* If RTI_CONNEXT_USER_HOME is set, it will be used as the base directory
|
|
* instead of $HOME or %LOCALAPPDATA%.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getApplicationDataDirectory(char *buffer, size_t bufferSize);
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Retrieves the command line used to invoke the current process.
|
|
*
|
|
* This function fills the provided buffer with the executable name and the
|
|
* command line arguments of the current process as a single string. The format
|
|
* of the string is as follows, with each argument separated by a space and
|
|
* null-terminated: "./executable_name arg1 arg2 ... argN".
|
|
*
|
|
* The implementation is platform-specific.
|
|
* - On Linux it reads from /proc/self/cmdline.
|
|
* - On Windows, it uses GetCommandLineA() to obtain the command line.
|
|
* - On macOS (Darwin), it uses _NSGetArgc() and _NSGetArgv().
|
|
* - On unsupported platforms, the function logs an error and returns RTI_FALSE.
|
|
*
|
|
* @attention On Linux and macOS, if the argv array is modified at runtime (like
|
|
* our test framework does for parsing the -range argument), those changes will
|
|
* be reflected in the returned string.
|
|
*
|
|
* @param[out] buffer Pointer to the buffer where the command line string
|
|
* will be stored.
|
|
* @param[in] bufferSize Size of the buffer in bytes.
|
|
*
|
|
* @return RTI_TRUE if the command line was successfully retrieved and stored in
|
|
* the buffer, RTI_FALSE otherwise (e.g., insufficient buffer size, platform not
|
|
* supported, or other errors).
|
|
*
|
|
* @pre buffer must not be NULL and must be initialized.
|
|
* @pre bufferSize must be greater than 0.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getCmdLine(char *buffer, size_t bufferSize);
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Maximum length of the command line buffer.
|
|
*
|
|
* This length is not enforced by RTIOsapiUtility_getCmdLine, but it is
|
|
* recommended to use this value to ensure that the buffer is large enough to
|
|
* hold the command line string.
|
|
*/
|
|
#define RTI_OSAPI_UTILITY_CMD_LINE_MAX_LENGTH 4096
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Generates a Random UUID (v4) according to RFC-4122:
|
|
* https://datatracker.ietf.org/doc/html/rfc4122.
|
|
*
|
|
* The format is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
|
|
*
|
|
* @param[inout] buffer Pointer to a buffer where the generated UUID will be
|
|
* stored. Must be at least RTI_OSAPI_UTILITY_UUID_STRING_LENGTH + 1 bytes
|
|
* long to accommodate the UUID string and a null terminator.
|
|
* @param[in] bufferSize Size of the buffer pointed by buffer.
|
|
*
|
|
* @attention This function should not be used for any security-related
|
|
* purposes, as the generated UUID is not cryptographically secure.
|
|
*
|
|
* @return RTI_TRUE if the UUID was successfully generated and stored in
|
|
* buffer, or RTI_FALSE otherwise.
|
|
*/
|
|
extern RTIOsapiDllExport RTIBool
|
|
RTIOsapiUtility_getRandomUUID(char *buffer, size_t bufferSize);
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Length of the UUID string representation.
|
|
*
|
|
* The UUID string representation is 36 characters long, including the hyphens.
|
|
* It is formatted as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
|
|
*/
|
|
#define RTI_OSAPI_UTILITY_UUID_STRING_LENGTH 36
|
|
|
|
/**
|
|
* @internal
|
|
* @brief Checks if a character is a hexadecimal digit.
|
|
*/
|
|
#define RTIOsapiUtility_isHexDigit(ch__) isxdigit(ch__)
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|
|
|
|
#include "osapi/osapi_utility_impl.h"
|
|
|
|
#endif /* osapi_utility_h */
|