/* ********************************************************** * Copyright 2004 - 2009 VMware, Inc. All rights reserved. * **********************************************************/ /* * @VMKAPIMOD_LICENSE@ */ /* *********************************************************************** * LibC */ /** * \addtogroup Lib * @{ * \defgroup LibC C-Library-Style Interfaces * * @{ *********************************************************************** */ #ifndef _VMKAPI_LIBC_H_ #define _VMKAPI_LIBC_H_ /** \cond never */ #ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H #error This vmkapi file should never be included directly but only via vmkapi.h #endif /** \endcond never */ #include /* *********************************************************************** * vmk_Strnlen -- */ /** * * \brief Determine the length of a string up to a maximum number * of bytes. * * \note This function will not block. * * \param[in] src String whose length is to be determined. * \param[in] maxLen Maximum number of bytes to check. * * \return Length of the string in bytes. * *********************************************************************** */ vmk_ByteCount vmk_Strnlen ( const char *src, vmk_ByteCount maxLen); /* *********************************************************************** * vmk_Strcpy -- */ /** * * \brief Copy a string. * * \note This function will not block. * * \deprecated Use vmk_StringCopy() instead. * * \param[out] dst String to copy to. * \param[in] src String to copy from. * * \return Pointer to src. * *********************************************************************** */ char *vmk_Strcpy( char *dst, const char *src); /* *********************************************************************** * vmk_Strncpy -- */ /** * * \brief Copy a string up to a maximum number of bytes. * * \note This function will not block. * * \deprecated Use vmk_StringCopy() instead. * * \param[out] dst String to copy to. * \param[in] src String to copy from. * \param[in] maxLen Maximum number of bytes to copy into dst. * * \warning A copied string is not automatically nul-terminated. * Users should take care to ensure that the destination * is large enough to hold the string and the nul-terminator. * * \return Pointer src. * *********************************************************************** */ char *vmk_Strncpy( char *dst, const char *src, vmk_ByteCount maxLen); /* *********************************************************************** * vmk_Strlcpy -- */ /** * * \brief Copy a string and ensure nul termination. * * \note This function will not block. * * \deprecated Use vmk_StringLCopy() instead. * * \param[out] dst String to copy to. * \param[in] src String to copy from. * \param[in] size Maximum number of bytes to store a string in dst. * * \note At most size-1 bytes will be copied. All copies will * be terminated with a nul unless size is set to zero. * * \return The length of src. If the return value is greater than * or equal to size, then truncation has occured during * the copy. * *********************************************************************** */ vmk_ByteCount vmk_Strlcpy( char *dst, const char *src, vmk_ByteCount size); /* *********************************************************************** * vmk_Strcmp -- */ /** * * \brief Compare two strings. * * \note This function will not block. * * \param[in] src1 First string to compare. * \param[in] src2 Second string to compare. * * \return A value greater than, less than or equal to 0 depending on * the lexicographical difference between the strings. * *********************************************************************** */ int vmk_Strcmp( const char *src1, const char *src2); /* *********************************************************************** * vmk_Strncmp -- */ /** * * \brief Compare two strings up to a maximum number of bytes. * * \note This function will not block. * * \param[in] src1 First string to compare. * \param[in] src2 Second string to compare. * \param[in] maxLen Maximum number of bytes to compare. * * \return A value greater than, less than or equal to 0 depending on * the lexicographical difference between the strings. * *********************************************************************** */ int vmk_Strncmp( const char *src1, const char *src2, vmk_ByteCount maxLen); /* *********************************************************************** * vmk_Strncasecmp -- */ /** * * \brief Compare two strings while disregarding case. * * \note This function will not block. * * \param[in] src1 First string to compare. * \param[in] src2 Second string to compare. * \param[in] maxLen Maximum number of bytes to compare. * * \return A value greater than, less than or equal to 0 depending on * the lexicographical difference between the strings as if * all characters in the string are lower-case. * *********************************************************************** */ int vmk_Strncasecmp( const char *src1, const char *src2, vmk_ByteCount maxLen); /* *********************************************************************** * vmk_Strchr -- */ /** * * \brief Forward search through a string for a character. * * \note This function will not block. * * \param[in] src String to search forward. * \param[in] c Character to search for. * * \return Pointer to the offset in src where c was found or NULL * if c was not found in src. * *********************************************************************** */ char *vmk_Strchr( const void *src, int c); /* *********************************************************************** * vmk_Strrchr -- */ /** * * \brief Reverse search through a string for a character. * * \note This function will not block. * * \param[in] src String to search backward. * \param[in] c Character to search for. * * \return Pointer to the offset in src where c was found or NULL * if c was not found in src. * *********************************************************************** */ char *vmk_Strrchr( const void *src, int c); /* *********************************************************************** * vmk_Strstr -- */ /** * * \brief Search for a substring in a string. * * \note This function will not block. * * \param[in] s1 String to search. * \param[in] s2 String to search for. * * \return Pointer to the offset in s1 where s2 was found or NULL * if s2 was not found in s1. * *********************************************************************** */ char *vmk_Strstr( const void *s1, const void *s2); /* *********************************************************************** * vmk_Strtol -- */ /** * * \brief Convert a string to a signed long integer. * * \note This function will not block. * * \param[in] str String to convert * \param[out] end If non-NULL, the address of the first invalid * character or the value of str if there are no * digits in the string. * \param[in] base Base of the number being converted which may be * between 2 and 36, or 0 may be supplied such * that strtol will attempt to detect the base * of the number in the string. * * \return Numeric value of the string. * *********************************************************************** */ long vmk_Strtol( const char *str, char **end, int base); /* *********************************************************************** * vmk_Strtoul -- */ /** * * \brief Convert a string to an unsigned long integer. * * \note This function will not block. * * \param[in] str String to convert * \param[out] end If non-NULL, the address of the first invalid * character or the value of str if there are no * digits in the string. * \param[in] base Base of the number being converted which may be * between 2 and 36, or 0 may be supplied such * that strtoul will attempt to detect the base * of the number in the string. * * \return Numeric value of the string. * *********************************************************************** */ unsigned long vmk_Strtoul( const char *str, char **end, int base); /* *********************************************************************** * vmk_Sprintf -- */ /** * * \brief Formatted print to a string. * * \note This function will not block. * * \deprecated Use vmk_StringFormat() instead. * * \printformatstringdoc * * \param[in] str Buffer in which to place output. * \param[in] format Printf-style format string. * * \return Number of bytes in the output string, not including the * terminating nul character. * *********************************************************************** */ int vmk_Sprintf( char *str, const char *format, ...) VMK_ATTRIBUTE_PRINTF(2,3); /* *********************************************************************** * vmk_Snprintf -- */ /** * * \brief Formatted print to a string with a maximum bound. * * \note This function will not block. * * \deprecated Use vmk_StringFormat() instead. * * \printformatstringdoc * * \param[in] str Buffer in which to place output. * \param[in] size Maximum number of bytes to output. * \param[in] format Printf-style format string. * * \return Number of bytes required to format the output string, not * including the terminating nul character. * * \note If the return value is less than the specified size, the * string has been formatted completely. If the return value is * equal to or greater than the specified size, the output has * been truncated. The output will always be nul terminated * unless the specified size is zero. * *********************************************************************** */ int vmk_Snprintf( char *str, vmk_ByteCount size, const char *format, ...) VMK_ATTRIBUTE_PRINTF(3,4); /* *********************************************************************** * vmk_Vsprintf -- */ /** * * \brief Formatted print to a string using varargs. * * \note This function will not block. * * \deprecated Use vmk_StringVFormat() instead. * * \printformatstringdoc * * \param[in] str Buffer in which to place output. * \param[in] format Printf-style format string. * \param[in] ap Varargs for format. * * \return Number of bytes in the output string, not including the * terminating nul character. * *********************************************************************** */ int vmk_Vsprintf( char *str, const char *format, va_list ap); /* ************************************************************************ * vmk_Vsnprintf -- */ /** * * \brief Formatted print to a string with a maximum bound using varargs. * * \note This function will not block. * * \deprecated Use vmk_StringVFormat() instead. * * \printformatstringdoc * * \param[in] str Buffer in which to place output. * \param[in] size Maximum number of bytes to output. * \param[in] format Printf-style format string. * \param[in] ap Varargs for format. * * \return Number of bytes required to format the output string, not * including the terminating nul character. * * \note If the return value is less than the specified size, the * string has been formatted completely. If the return value is * equal to or greater than the specified size, the output has * been truncated. The output will always be nul terminated * unless the specified size is zero. * *********************************************************************** */ int vmk_Vsnprintf( char *str, vmk_ByteCount size, const char *format, va_list ap); /* *********************************************************************** * vmk_Vsscanf -- */ /** * * \brief Formatted scan of a string using varargs. * * \note This function will not block. * * \scanformatstringdoc * * \param[in] inp Buffer to scan. * \param[in] fmt0 Scanf-style format string. * \param[in] ap Varargs that hold input values for format. * * \return Number of input values assigned. * *********************************************************************** */ int vmk_Vsscanf( const char *inp, char const *fmt0, va_list ap); /* *********************************************************************** * vmk_Sscanf -- */ /** * * \brief Formatted scan of a string. * * \note This function will not block. * * \scanformatstringdoc * * \param[in] ibuf Buffer to scan. * \param[in] fmt Scanf-style format string. * * \return Number of input values assigned. * *********************************************************************** */ int vmk_Sscanf( const char *ibuf, const char *fmt, ...) VMK_ATTRIBUTE_SCANF(2, 3); /* *********************************************************************** * vmk_Memset -- */ /** * * \brief Set bytes in a buffer to a particular value. * * \note This function will not block. * * \param[in] dst Destination buffer to set. * \param[in] byte Value to set each byte to. * \param[in] len Number of bytes to set. * * \return Original value of dst. * *********************************************************************** */ void *vmk_Memset( void *dst, int byte, vmk_ByteCount len); /* *********************************************************************** * vmk_Memcpy -- */ /** * * \brief Copy bytes from one buffer to another. * * \note This function will not block. * * \param[in] dst Destination buffer to copy to. * \param[in] src Source buffer to copy from. * \param[in] len Number of bytes to copy. * * \return Original value of dst. * *********************************************************************** */ void *vmk_Memcpy( void *dst, const void *src, vmk_ByteCount len); /* *********************************************************************** * vmk_Memcmp -- */ /** * * \brief Compare bytes between two buffers. * * \note This function will not block. * * \param[in] src1 Buffer to compare. * \param[in] src2 Other buffer to compare. * \param[in] len Number of bytes to compare. * * \return Difference between the first two differing bytes or * zero if the buffers are identical over the specified length. * *********************************************************************** */ int vmk_Memcmp( const void *src1, const void *src2, vmk_ByteCount len); /* *********************************************************************** * vmk_Rand -- */ /** * * \brief Generate the next number in a pseudorandom sequence. * * \note This function will not block. * * \warning This function's pseudorandom numbers do not have high * enough quality for cryptographic purposes. * * \note The values returned are in the range 0 < n <= 0x7fffffff, * and the seed supplied must also be in this range. * * \param[in] seed The previous number in the sequence, if any. To * start a new sequence at a random point, call * vmk_GetRandSeed to get the initial seed. To * start a new sequence at a deterministic point, * choose any fixed value in range for the initial * seed. * * \return A pseudorandom number. * *********************************************************************** */ vmk_uint32 vmk_Rand( vmk_uint32 seed); /* *********************************************************************** * vmk_GetRandSeed -- */ /** * * \brief Generate a random initial seed for vmk_Rand() * * \note This function will not block. * * \warning This function should be called only occasionally, to start * a sequence of pseudorandom numbers generated by * vmk_Rand(). Attempting to use this function frequently to * generate individual random numbers will result in values * with very poor randomness. Even when this function is * called only occasionally, its random numbers do not have * high enough quality for cryptographic purposes. * * \return A random seed value suitable to start a new pseudorandom * sequence. * *********************************************************************** */ vmk_uint32 vmk_GetRandSeed( void); /* *********************************************************************** * vmk_IsPrint -- */ /** * * \brief Determine if a character is printable. * * \note This function will not block. * * \param[in] c Character to check. * * \retval VMK_TRUE Supplied character is printable. * \retval VMK_FALSE Supplied character is not printable. * *********************************************************************** */ vmk_Bool vmk_IsPrint( int c); #endif /* _VMKAPI_LIBC_H_ */ /** @} */ /** @} */