209 lines
7.7 KiB
C
209 lines
7.7 KiB
C
|
/* **********************************************************
|
||
|
|
* Copyright 2010 VMware, Inc. All rights reserved.
|
||
|
|
* **********************************************************/
|
||
|
|
|
||
|
|
/*
|
||
|
|
* @VMKAPIMOD_LICENSE@
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* String */ /**
|
||
|
|
* \addtogroup Lib
|
||
|
|
* @{
|
||
|
|
* \defgroup String Interfaces
|
||
|
|
*
|
||
|
|
* @{
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef _VMKAPI_STRING_H_
|
||
|
|
#define _VMKAPI_STRING_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_StringCat -- */ /**
|
||
|
|
*
|
||
|
|
* \brief Appends the source string to the end of the destination string.
|
||
|
|
*
|
||
|
|
* \note This function will not block.
|
||
|
|
*
|
||
|
|
* \param[in] dst String to copy to.
|
||
|
|
* \param[in] src String to append from.
|
||
|
|
* \param[in] dstLen Length of destination buffer.
|
||
|
|
*
|
||
|
|
* \note dst will always be nul terminated so long as dstLen is greater
|
||
|
|
* than zero.
|
||
|
|
*
|
||
|
|
* \retval VMK_OK The string was successfully concatenated.
|
||
|
|
* \retval VMK_LIMIT_EXCEEDED The source string was too long to be
|
||
|
|
* copied fully into the destination. As
|
||
|
|
* much of the source string as possible was
|
||
|
|
* concatenated.
|
||
|
|
* \retval VMK_BAD_PARAM The source string or destination buffer
|
||
|
|
* is not valid.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_StringCat(
|
||
|
|
char *dst,
|
||
|
|
const char *src,
|
||
|
|
vmk_ByteCount dstLen);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_StringCopy -- */ /**
|
||
|
|
*
|
||
|
|
* \brief Copy a string up to a maximum number of bytes.
|
||
|
|
*
|
||
|
|
* \param[out] dst String to copy to.
|
||
|
|
* \param[in] src String to copy from.
|
||
|
|
* \param[in] dstLen Maximum number of bytes to copy into dst.
|
||
|
|
*
|
||
|
|
* \note dst will always be be nul terminated so long as dstLen is
|
||
|
|
* greater than zero.
|
||
|
|
* \note This function will not block.
|
||
|
|
*
|
||
|
|
* \retval VMK_OK The string was successfully copied.
|
||
|
|
* \retval VMK_LIMIT_EXCEEDED The source string was too long to be
|
||
|
|
* copied fully into the destination. As
|
||
|
|
* much of the source string as possible was
|
||
|
|
* copied.
|
||
|
|
* \retval VMK_BAD_PARAM The source string or destination buffer
|
||
|
|
* is not valid.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_StringCopy(
|
||
|
|
char *dst,
|
||
|
|
const char *src,
|
||
|
|
vmk_ByteCount dstLen);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_StringLCopy -- */ /**
|
||
|
|
*
|
||
|
|
* \brief Copy a string and ensure nul termination.
|
||
|
|
*
|
||
|
|
* \param[out] dst String to copy to.
|
||
|
|
* \param[in] src String to copy from.
|
||
|
|
* \param[in] dstLen Maximum number of bytes to store a string in dst.
|
||
|
|
* \param[out] outLen Number of bytes necessary. Optional: may pass
|
||
|
|
* NULL.
|
||
|
|
*
|
||
|
|
* \note dst will always be be nul terminated so long as dstLen is
|
||
|
|
* greater than zero.
|
||
|
|
* \note outLen will always be set to the number of bytes needed to
|
||
|
|
* successfully copy the src string, even if that copy is not
|
||
|
|
* successful, not including the nul terminator.
|
||
|
|
* \note This function will not block.
|
||
|
|
*
|
||
|
|
* \retval VMK_OK The string was successfully copied.
|
||
|
|
* \retval VMK_LIMIT_EXCEEDED The source string was too long to be
|
||
|
|
* copied fully into the destination. As
|
||
|
|
* much of the source string as possible was
|
||
|
|
* copied.
|
||
|
|
* \retval VMK_BAD_PARAM The source string or destination buffer
|
||
|
|
* is not valid.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_StringLCopy(
|
||
|
|
char *dst,
|
||
|
|
const char *src,
|
||
|
|
vmk_ByteCount dstLen,
|
||
|
|
vmk_ByteCount *outLen);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_StringFormat -- */ /**
|
||
|
|
*
|
||
|
|
* \brief Formats the provided format string and arguments into the
|
||
|
|
* destination buffer, up to a maximum bound.
|
||
|
|
*
|
||
|
|
* \param[in] str Buffer in which to place output.
|
||
|
|
* \param[in] strLen Maximum number of bytes to output.
|
||
|
|
* \param[out] outLen Number of bytes necessary to format this string,
|
||
|
|
* not including the terminating nul character.
|
||
|
|
* Optional: may pass NULL.
|
||
|
|
* \param[in] format Printf-style format string.
|
||
|
|
*
|
||
|
|
* \note str will always be be nul terminated so long as strLen is
|
||
|
|
* greater than zero.
|
||
|
|
* \note outLen will always be set to the number of bytes needed to
|
||
|
|
* successfully format the src string, even if that formatting
|
||
|
|
* is not successful, not including the nul terminator.
|
||
|
|
* \printformatstringdoc
|
||
|
|
* \note This function will not block.
|
||
|
|
*
|
||
|
|
* \retval VMK_OK The string was successfully formatted.
|
||
|
|
* \retval VMK_LIMIT_EXCEEDED The source string was too long to be
|
||
|
|
* formatted fully into the destination. As
|
||
|
|
* much of the specified format string as
|
||
|
|
* possible was formatted.
|
||
|
|
* \retval VMK_BAD_PARAM The format string or destination buffer
|
||
|
|
* is not valid.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_StringFormat(
|
||
|
|
char *str,
|
||
|
|
vmk_ByteCount strLen,
|
||
|
|
vmk_ByteCount *outLen,
|
||
|
|
const char *format,
|
||
|
|
...)
|
||
|
|
VMK_ATTRIBUTE_PRINTF(4,5);
|
||
|
|
|
||
|
|
/*
|
||
|
|
***********************************************************************
|
||
|
|
* vmk_StringVFormat -- */ /**
|
||
|
|
*
|
||
|
|
* \brief Formats the provided format string and varargs into the
|
||
|
|
* destination buffer, up to a maximum bound.
|
||
|
|
*
|
||
|
|
* \param[in] str Buffer in which to place output.
|
||
|
|
* \param[in] strLen Maximum number of bytes to output.
|
||
|
|
* \param[out] outLen Number of bytes necessary to format this string,
|
||
|
|
* not including the terminating nul character.
|
||
|
|
* Optional: may pass NULL.
|
||
|
|
* \param[in] format Printf-style format string.
|
||
|
|
* \param[in] ap Varargs for format.
|
||
|
|
*
|
||
|
|
* \note str will always be be nul terminated so long as strLen is
|
||
|
|
* greater than zero.
|
||
|
|
* \note outLen will always be set to the number of bytes needed to
|
||
|
|
* successfully format the src string, even if that formatting
|
||
|
|
* is not successful, not including the nul terminator.
|
||
|
|
* \printformatstringdoc
|
||
|
|
* \note This function will not block.
|
||
|
|
*
|
||
|
|
* \retval VMK_OK The string was successfully formatted.
|
||
|
|
* \retval VMK_LIMIT_EXCEEDED The source string was too long to be
|
||
|
|
* formatted fully into the destination. As
|
||
|
|
* much of the specified format string as
|
||
|
|
* possible was formatted.
|
||
|
|
* \retval VMK_BAD_PARAM The format string or destination buffer
|
||
|
|
* is not valid.
|
||
|
|
*
|
||
|
|
***********************************************************************
|
||
|
|
*/
|
||
|
|
VMK_ReturnStatus vmk_StringVFormat(
|
||
|
|
char *str,
|
||
|
|
vmk_ByteCount strLen,
|
||
|
|
vmk_ByteCount *outLen,
|
||
|
|
const char *format,
|
||
|
|
va_list ap);
|
||
|
|
|
||
|
|
#endif /* _VMKAPI_STRING_H_ */
|
||
|
|
/** @} */
|
||
|
|
/** @} */
|