include/string.h: add comments for public APIs (19354d96) · Commits · Public Repositories / spdk

include/spdk/string.h

+59 −39

Original line number	Diff line number	Diff line
		@@ -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.
		* \param delim Null-terminated string containing the list of accepted delimiters.
		* Note that the string will be modified in place to add the string terminator
		* to each field.
		*
		* \return Pointer to beginning of the current 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.
		*
		* 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);