string.h File Reference

String utility functions. More...

Macros
#define	_SPDK_STRINGIFY(x)   #x
#define	SPDK_STRINGIFY(x)   _SPDK_STRINGIFY(x)

Functions
char *	spdk_sprintf_alloc (const char *format,...)
	sprintf with automatic buffer allocation. More...
char *	spdk_vsprintf_alloc (const char *format, va_list args)
	vsprintf with automatic buffer allocation. More...
char *	spdk_sprintf_append_realloc (char *buffer, const char *format,...)
	Append string using vsprintf with automatic buffer re-allocation. More...
char *	spdk_vsprintf_append_realloc (char *buffer, const char *format, va_list args)
	Append string using vsprintf with automatic buffer re-allocation. More...
char *	spdk_strlwr (char *s)
	Convert string to lowercase in place. More...
char *	spdk_strsepq (char **stringp, const char *delim)
	Parse a delimited string with quote handling. More...
char *	spdk_str_trim (char *s)
	Trim whitespace from a string in place. More...
void	spdk_strerror_r (int errnum, char *buf, size_t buflen)
	Copy the string version of an error into the user supplied buffer. More...
const char *	spdk_strerror (int errnum)
	Return the string version of an error from a static, thread-local buffer. More...
size_t	spdk_str_chomp (char *s)
	Remove trailing newlines from the end of a string in place. More...
void	spdk_strcpy_pad (void *dst, const char *src, size_t size, int pad)
	Copy a string into a fixed-size buffer, padding extra bytes with a specific character. More...
size_t	spdk_strlen_pad (const void *str, size_t size, int pad)
	Find the length of a string that has been padded with a specific byte. More...
int	spdk_parse_ip_addr (char *ip, char **host, char **port)
	Parse an IP address into its hostname and port components. More...
int	spdk_parse_capacity (const char *cap_str, uint64_t *cap, bool *has_prefix)
	Parse a string representing a number possibly followed by a binary prefix. More...
bool	spdk_mem_all_zero (const void *data, size_t size)
	Check if a buffer is all zero (0x00) bytes or not. More...
long int	spdk_strtol (const char *nptr, int base)
	Convert the string in nptr to a long integer value according to the given base. More...
long long int	spdk_strtoll (const char *nptr, int base)
	Convert the string in nptr to a long long integer value according to the given base. More...
char **	spdk_strarray_from_string (const char *str, const char *delim)
	Build a NULL-terminated array of strings from the given string separated by the given chars in delim, as if split by strpbrk(). More...
char **	spdk_strarray_dup (const char **strarray)
	Duplicate a NULL-terminated array of strings. More...
void	spdk_strarray_free (char **strarray)
	Free a NULL-terminated array of strings. More...
int	spdk_strcpy_replace (char *dst, size_t size, const char *src, const char *search, const char *replace)
	Copy a string into a fixed-size buffer with all occurrences of the search string replaced with the given replace substring. More...

Detailed Description

String utility functions.

Function Documentation

spdk_mem_all_zero()

bool spdk_mem_all_zero	(	const void *	data,
		size_t	size
	)

Check if a buffer is all zero (0x00) bytes or not.

Parameters

data	Buffer to check.
size	Size of data in bytes.

Returns

true if data consists entirely of zeroes, or false if any byte in data is not zero.

spdk_parse_capacity()

int spdk_parse_capacity	(	const char *	cap_str,
		uint64_t *	cap,
		bool *	has_prefix
	)

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.

Parameters

cap_str	Null terminated string.
cap	Pointer where the parsed capacity (in bytes) will be put.
has_prefix	Pointer to a flag that will be set to describe whether given string contains a binary prefix (optional).

Returns

0 on success, or negative errno on failure.

spdk_parse_ip_addr()

int spdk_parse_ip_addr	(	char *	ip,
		char **	host,
		char **	port
	)

Parse an IP address into its hostname and port components.

This modifies the IP address in place.

Parameters

ip	A null terminated IP address, including port. Both IPv4 and IPv6 are supported.
host	Will point to the start of the hostname within ip. The string will be null terminated.
port	Will point to the start of the port within ip. The string will be null terminated.

Returns

0 on success. -EINVAL on failure.

spdk_sprintf_alloc()

char* spdk_sprintf_alloc	(	const char *	format,
			...
	)

sprintf with automatic buffer allocation.

The return value is the formatted string, which should be passed to free() when no longer needed.

Parameters

format

Format for the string to print.

Returns

the formatted string on success, or NULL on failure.

spdk_sprintf_append_realloc()

char* spdk_sprintf_append_realloc	(	char *	buffer,
		const char *	format,
			...
	)

Append string using vsprintf with automatic buffer re-allocation.

The return value is the formatted string, in which the original string in buffer is unchanged and the specified formatted string is appended.

The returned string should be passed to free() when no longer needed.

If buffer is NULL, the call is equivalent to spdk_sprintf_alloc(). If the call fails, the original buffer is left untouched.

Parameters

buffer	Buffer which has a formatted string.
format	Format for the string to print.

Returns

the formatted string on success, or NULL on failure.

spdk_str_chomp()

size_t spdk_str_chomp

(

char *

s

)

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.

Parameters

s	String to remove newline from.

Returns

the number of characters removed.

spdk_str_trim()

char* spdk_str_trim

(

char *

s

)

Trim whitespace from a string in place.

Parameters

s	String to trim.

Returns

the trimmed string.

spdk_strarray_dup()

char** spdk_strarray_dup

(

const char **

strarray

)

Duplicate a NULL-terminated array of strings.

Returns NULL on failure. The array, and the strings, are allocated with the standard allocator (e.g. calloc()).

Parameters

strarray

input array of strings.

spdk_strarray_free()

void spdk_strarray_free

(

char **

strarray

)

Free a NULL-terminated array of strings.

The array and its strings must have been allocated with the standard allocator (calloc() etc.).

Parameters

strarray

array of strings.

spdk_strarray_from_string()

char** spdk_strarray_from_string	(	const char *	str,
		const char *	delim
	)

Build a NULL-terminated array of strings from the given string separated by the given chars in delim, as if split by strpbrk().

Empty items are pointers to an empty string.

Parameters

str	Input string
delim	Separating delimiter set.

Returns

the string array, or NULL on failure.

spdk_strcpy_pad()

void spdk_strcpy_pad	(	void *	dst,
		const char *	src,
		size_t	size,
		int	pad
	)

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.

Parameters

dst	Pointer to destination fixed-size buffer to fill.
src	Pointer to source null-terminated string to copy into dst.
size	Number of bytes to fill in dst.
pad	Character to pad extra space in dst beyond the size of src.

spdk_strcpy_replace()

int spdk_strcpy_replace	(	char *	dst,
		size_t	size,
		const char *	src,
		const char *	search,
		const char *	replace
	)

Copy a string into a fixed-size buffer with all occurrences of the search string replaced with the given replace substring.

The fixed-size buffer must not be less than the string with the replaced values including the terminating null byte.

Parameters

dst	Pointer to destination fixed-size buffer to fill.
size	Size of the destination fixed-size buffer in bytes.
src	Pointer to source null-terminated string to copy into dst.
search	The string being searched for.
replace	the replacement substring the replaces the found search substring.

Returns

0 on success, or negated errno on failure.

spdk_strerror()

const char* spdk_strerror

(

int

errnum

)

Return the string version of an error from a static, thread-local buffer.

This function is thread safe.

Parameters

errnum

Error code.

Returns

a pointer to buffer upon success.

spdk_strerror_r()

void spdk_strerror_r	(	int	errnum,
		char *	buf,
		size_t	buflen
	)

Copy the string version of an error into the user supplied buffer.

Parameters

errnum	Error code.
buf	Pointer to a buffer in which to place the error message.
buflen	The size of the buffer in bytes.

spdk_strlen_pad()

size_t spdk_strlen_pad	(	const void *	str,
		size_t	size,
		int	pad
	)

Find the length of a string that has been padded with a specific byte.

Parameters

str	Right-padded string to find the length of.
size	Size of the full string pointed to by str, including padding.
pad	Character that was used to pad str up to size.

Returns

the length of the non-padded portion of str.

spdk_strlwr()

char* spdk_strlwr

(

char *

s

)

Convert string to lowercase in place.

Parameters

s	String to convert to lowercase.

Returns

the converted string.

spdk_strsepq()

char* spdk_strsepq	(	char **	stringp,
		const char *	delim
	)

Parse a delimited string with quote handling.

Note that the string will be modified in place to add the string terminator to each field.

Parameters

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.
delim	Null-terminated string containing the list of accepted delimiters.

Returns

a pointer to beginning of the current field.

spdk_strtol()

long int spdk_strtol	(	const char *	nptr,
		int	base
	)

Convert the string in nptr to a long integer value according to the given base.

spdk_strtol() does the additional error checking and allows only strings that contains only numbers and is positive number or zero. The caller only has to check if the return value is not negative.

Parameters

nptr	String containing numbers.
base	Base which must be between 2 and 32 inclusive, or be the special value 0.

Returns

positive number or zero on success, or negative errno on failure.

spdk_strtoll()

long long int spdk_strtoll	(	const char *	nptr,
		int	base
	)

Convert the string in nptr to a long long integer value according to the given base.

spdk_strtoll() does the additional error checking and allows only strings that contains only numbers and is positive number or zero. The caller only has to check if the return value is not negative.

Parameters

nptr	String containing numbers.
base	Base which must be between 2 and 32 inclusive, or be the special value 0.

Returns

positive number or zero on success, or negative errno on failure.

spdk_vsprintf_alloc()

char* spdk_vsprintf_alloc	(	const char *	format,
		va_list	args
	)

vsprintf with automatic buffer allocation.

The return value is the formatted string, which should be passed to free() when no longer needed.

Parameters

format	Format for the string to print.
args	A value that identifies a variable arguments list.

Returns

the formatted string on success, or NULL on failure.

spdk_vsprintf_append_realloc()

char* spdk_vsprintf_append_realloc	(	char *	buffer,
		const char *	format,
		va_list	args
	)

Append string using vsprintf with automatic buffer re-allocation.

The return value is the formatted string, in which the original string in buffer is unchanged and the specified formatted string is appended.

The returned string should be passed to free() when no longer needed.

If buffer is NULL, the call is equivalent to spdk_sprintf_alloc(). If the call fails, the original buffer is left untouched.

Parameters

buffer	Buffer which has a formatted string.
format	Format for the string to print.
args	A value that identifies a variable arguments list.

Returns

the formatted string on success, or NULL on failure.