libexplain/ac/string.h File Reference

Insulate <string.h> differences. More...

#include <libexplain/config.h>
#include <strings.h>

Go to the source code of this file.

Defines
#define	strendcpy   you_mean_explain_strendcpy!^%
#define	strcat   strcat_is_unsafe__use_strendcpy_instead@
#define	strcpy   strcpy_is_unsafe__use_strendcpy_instead@
Functions
int	strcasecmp (const char *, const char *)
int	strncasecmp (const char *, const char *, size_t)
const char *	strsignal (int)
const char *	explain_strsignal (int)
int	strverscmp (const char *, const char *)
char *	explain_strendcpy (char *dst, const char *src, const char *end)
char *	strnstr (const char *haystack, const char *needle, size_t haystack_size)

---

Detailed Description

Insulate <string.h> differences.

Definition in file string.h.

---

Define Documentation

#define strcat   strcat_is_unsafe__use_strendcpy_instead@

Definition at line 134 of file string.h.

#define strcpy   strcpy_is_unsafe__use_strendcpy_instead@

Definition at line 136 of file string.h.

#define strendcpy   you_mean_explain_strendcpy!^%

Definition at line 131 of file string.h.

---

Function Documentation

char* explain_strendcpy	(	char *	dst,
		const char *	src,
		const char *	end
	)

The explain_strendcpy function is a buffer-overrun-safe replacement for strcpy, strcat, and a more efficient replacement for strlcpy and strlcat.

Unless there is no space left in the buffer (dst >= end), the result will always be NUL terminated.

Parameters:

dst	The position within the destination string buffer to be copied into.
src	The string to be copied into the buffer.
end	The end of the string buffer being copied into. In most cases this is of the form "buffer + sizeof(buffer)", a constant which may be calculated at compile time.

Returns:

A pointer into the buffer where at the NUL terminator of the string in the buffer. EXCEPT when an overrun would occur, in which case the end parameter is returned.

Note:

The return value is where the next string would be written into the buffer. For example, un-safe code such as

strcat(strcpy(buffer, "Hello, "), "World\n");

can be safely replaced by

strendcpy(strendcpy(buffer, "Hello, ", buffer + sizeof(buffer)), "World\n", buffer + sizeof(buffer));

and overruns will be handled safely. Similarly, more complex string manipulations can be written

char buffer[100]; char *bp = buffer; bp = strendcpy(bp, "Hello, ", buffer + sizeof(buffer)); bp = strendcpy(bp, "World!\n", buffer + sizeof(buffer));

all that is required to test for an overrun is

if (bp == buffer + sizeof(buffer)) fprintf(stderr, "Overrun!\n");

On the plus side, there is only one functionto remember, not two, replacing both strcpy and strcat.

There have been some quite viable replacements for strcpy and strcat in the BSD strlcpy and strlcat functions. These functions are indeed buffer-ovrrun-safe but they suffer from doing too much work (and touching too much memory) in the case of overruns.

Code such as

strlcpy(buffer, "Hello, ", sizeof(buffer)); strlcat(buffer, "World!\n", sizeof(buffer));

suffers from O(n**2) problem, constantly re-tracing the initial portions of the buffer. In addition, in the case of overruns, the BSD versions of these functions return how big the buffer should have been. This functionality is rarely used, but still requires the src to be traversed all the way to the NUL (and it could be megabytes away) before they can return. The strendcpy function does not suffer from either of these performance problems.

Definition at line 231 of file string.c.

const char* explain_strsignal

(

int

)

Definition at line 219 of file string.c.

int strcasecmp	(	const char *	,
		const char *
	)

Definition at line 75 of file string.c.

int strncasecmp	(	const char *	,
		const char *	,
		size_t
	)

char* strnstr	(	const char *	haystack,
		const char *	needle,
		size_t	haystack_size
	)

Definition at line 254 of file string.c.

const char* strsignal

(

int

)

Definition at line 113 of file string.c.

int strverscmp	(	const char *	,
		const char *
	)