ivampiresp/Spdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

include/string.h: add comments for public APIs

Browse Source 
Change-Id: I56488b61ff000070c430851c9627fa23c164fb18
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/406924
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>
This commit is contained in:
Yanbo Zhou 2018-04-09 10:50:30 +08:00 committed by Jim Harris
parent 4e012722ef
commit 19354d966c
1 changed files with 59 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
include/spdk/string.h
View File

@ -47,18 +47,25 @@ extern "C" {
/**
* sprintf with automatic buffer allocation.
*
* The return value is the formatted string,
* which should be passed to free() when no longer needed,
* or NULL on failure.
* The return value is the formatted string, which should be passed to free()
* when no longer needed.
*
* \param format Format for the string to print.
*
* \return the formatted string on success, or NULL on failure.
*/
char *spdk_sprintf_alloc(const char *format, ...) __attribute__((format(printf, 1, 2)));
/**
* vsprintf with automatic buffer allocation.
*
* The return value is the formatted string,
* which should be passed to free() when no longer needed,
* or NULL on failure.
* The return value is the formatted string, which should be passed to free()
* when no longer needed.
*
* \param format Format for the string to print.
* \param args A value that identifies a variable arguments list.
*
* \return the formatted string on success, or NULL on failure.
*/
char *spdk_vsprintf_alloc(const char *format, va_list args);
@ -66,19 +73,23 @@ char *spdk_vsprintf_alloc(const char *format, va_list args);
* Convert string to lowercase in place.
*
* \param s String to convert to lowercase.
*
* \return the converted string.
*/
char *spdk_strlwr(char *s);
/**
* Parse a delimited string with quote handling.
*
* \param stringp Pointer to starting location in string. *stringp will be updated to point to the
* start of the next field, or NULL if the end of the string has been reached.
* Note that the string will be modified in place to add the string terminator
* to each field.
*
* \param stringp Pointer to starting location in string. *stringp will be updated
* to point to the start of the next field, or NULL if the end of the string has
* been reached.
* \param delim Null-terminated string containing the list of accepted delimiters.
*
* \return Pointer to beginning of the current field.
*
* Note that the string will be modified in place to add the string terminator to each field.
* \return a pointer to beginning of the current field.
*/
char *spdk_strsepq(char **stringp, const char *delim);
@ -86,47 +97,52 @@ char *spdk_strsepq(char **stringp, const char *delim);
* Trim whitespace from a string in place.
*
* \param s String to trim.
*
* \return the trimmed string.
*/
char *spdk_str_trim(char *s);
/**
* Copy the string version of an error into the user supplied buffer
*
* \param errnum Error code
* \param buf Pointer to a buffer in which to place the error message
* \param buflen the size of the buffer in bytes
* \param errnum Error code.
* \param buf Pointer to a buffer in which to place the error message.
* \param buflen The size of the buffer in bytes.
*/
void spdk_strerror_r(int errnum, char *buf, size_t buflen);
/**
* Return the string version of an error from a static, thread-local buffer.
* This function is thread safe.
* Return the string version of an error from a static, thread-local buffer. This
* function is thread safe.
*
* \param errnum Error code
* \param errnum Error code.
*
* \return pointer to buffer upon success.
* \return a pointer to buffer upon success.
*/
const char *spdk_strerror(int errnum);
/**
* Remove trailing newlines from the end of a string in place.
*
* Any sequence of trailing \r and \n characters is removed from the end of the string.
* Any sequence of trailing \r and \n characters is removed from the end of the
* string.
*
* \param s String to remove newline from.
* \return Number of characters removed.
*
* \return the number of characters removed.
*/
size_t spdk_str_chomp(char *s);
/**
* Copy a string into a fixed-size buffer, padding extra bytes with a specific character.
* Copy a string into a fixed-size buffer, padding extra bytes with a specific
* character.
*
* If src is longer than size, only size bytes will be copied.
*
* \param dst Pointer to destination fixed-size buffer to fill.
* \param src Pointer to source null-terminated string to copy into dst.
* \param size Number of bytes to fill in dst.
* \param pad Character to pad extra space in dst beyond the size of src.
*
* If src is longer than size, only size bytes will be copied.
*/
void spdk_strcpy_pad(void *dst, const char *src, size_t size, int pad);
@ -137,37 +153,39 @@ void spdk_strcpy_pad(void *dst, const char *src, size_t size, int pad);
* \param size Size of the full string pointed to by str, including padding.
* \param pad Character that was used to pad str up to size.
*
* \return Length of the non-padded portion of str.
* \return the length of the non-padded portion of str.
*/
size_t spdk_strlen_pad(const void *str, size_t size, int pad);
/**
* Parse an IP address into its hostname and port components.
* This modifies the IP address in place.
* Parse an IP address into its hostname and port components. This modifies the
* IP address in place.
*
* \param ip A null terminated IP address, including port.
* Both IPv4 and IPv6 are supported.
* \param host Will point to the start of the hostname within ip.
* The string will be null terminated.
* \param port Will point to the start of the port within ip.
* The string will be null terminated.
* \param ip A null terminated IP address, including port. Both IPv4 and IPv6
* are supported.
* \param host Will point to the start of the hostname within ip. The string will
* be null terminated.
* \param port Will point to the start of the port within ip. The string will be
* null terminated.
*
* \return 0 if successful. -1 on error.
* \return 0 on success. -1 on failure.
*/
int spdk_parse_ip_addr(char *ip, char **host, char **port);
/**
* Parse a string representing a number possibly followed by a binary prefix.
*
* The string can contain a trailing "B" (KB,MB,GB) but it's not necessary.
* "128K" = 128 * 1024; "2G" = 2 * 1024 * 1024; "2GB" = 2 * 1024 * 1024;
* Additionally, lowercase "k", "m", "g" are parsed as well. They are processed
* the same as their uppercase equivalents.
*
* \param cap_str null terminated string
* \param cap pointer where the parsed capacity (in bytes) will be put
* \param has_prefix pointer to a flag that will be set to describe whether given
* string contains a binary prefix
* \returned 0 on success, negative errno otherwise
* \param cap_str Null terminated string.
* \param cap Pointer where the parsed capacity (in bytes) will be put.
* \param has_prefix Pointer to a flag that will be set to describe whether given
* string contains a binary prefix.
*
* \return 0 on success, or negative errno on failure.
*/
int spdk_parse_capacity(const char *cap_str, uint64_t *cap, bool *has_prefix);
@ -176,7 +194,9 @@ int spdk_parse_capacity(const char *cap_str, uint64_t *cap, bool *has_prefix);
*
* \param data Buffer to check.
* \param size Size of data in bytes.
* \return true if data consists entirely of zeroes, or false if any byte in data is not zero.
*
* \return true if data consists entirely of zeroes, or false if any byte in data
* is not zero.
*/
bool spdk_mem_all_zero(const void *data, size_t size);