vmkdrivers/BLD/build/HEADERS/vmkapi-current-all-public/vmkernel64/release/lib/vmkapi_string.h
2015-10-23 15:48:45 -04:00

208 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_ */
/** @} */
/** @} */