/* **********************************************************
* 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 <stdarg.h>
/*
***********************************************************************
* 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_ */
/** @} */
/** @} */