cstr.h File Reference

Utilities and polyfills for C-style nil-terminated strings. More...

#include <stddef.h>

Go to the source code of this file.

Functions
void *	memccpy (void *restrict dest, const void *restrict src, int ch, size_t len)
	Copies up to len characters from src into dest, stopping early if the character ch is encountered.
char *	strdup (const char *src)
	Duplicates a nil-terminated string.
char *	strndup (const char *src, size_t size)
	Duplicates a nil-terminated string, up to a maximum length.
char *	strzcpy (char dest[restrict static 1], const char src[restrict static 1], size_t len)
	Similar to strncpy(), except result is always nil-terminated.

Detailed Description

Utilities and polyfills for C-style nil-terminated strings.

Function Documentation

memccpy()

void * memccpy	(	void *restrict	dest,
		const void *restrict	src,
		int	ch,
		size_t	len )

Copies up to len characters from src into dest, stopping early if the character ch is encountered.

Parameters

[out]	dest	The memory location to copy characters into.
[in]	src	The memory location to copy characters from.
[in]	ch	The character which when encountered ends the copying.
[in]	len	The maximum number of characters to copy.

Returns

If the character ch was encountered, returns a pointer to the character following it; otherwise, returns a nil pointer..

See also

WG14 N3220 7.26.2.2 “The memccpy function”

WG14 N2349 “Toward more efficient string copying and concatenation”

POSIX memccpy()

Note

dest and src are interpreted as unsigned char*, and ch is interpreted as unsigned char.

strdup()

char * strdup

(

const char *

src

)

Duplicates a nil-terminated string.

The returned string can be passed into free() to destroy it.

Parameters

src	The nil-terminated string to duplicate.

Returns

A pointer to the newly allocated string, or a nil pointer. if an error occurred.

See also

WG14 N3220 7.26.2.6 “The strdup function”

WG14 N2353 “Add strdup and strndup to C2X”

POSIX strdup()

strndup()

char * strndup	(	const char *	src,
		size_t	size )

Duplicates a nil-terminated string, up to a maximum length.

If a nil terminator is not encountered in the first size bytes, it is appended to the duplicated string.

The returned string can be passed into free() to destroy it.

Parameters

src	The nil-terminated string to duplicate.
size	The maximum number of bytes to copy from src.

Returns

A pointer to the newly allocated string, or a nil pointer. if an error occurred.

See also

WG14 N3220 7.26.2.7 “The strndup function”

WG14 N2353 “Add strdup and strndup to C2X”

POSIX strndup()

strzcpy()

char * strzcpy	(	char	dest[restrict static 1],
		const char	src[restrict static 1],
		size_t	len )

Similar to strncpy(), except result is always nil-terminated.

More accurately, this is a more ergonomic form of memccpy that is specifically tailored to be used on nil-terminated C-strings.

Behavior is undefined if len is greater than the size of either dest or src, if dest and src overlap, or if either dest or src are nil pointers.

Replacing use of strncpy()

A common pitfall with strncpy() is that if the string is truncated, the resulting buffer won't be nil-terminated:

char buf[16] = {0};
strncpy(buf, "Hello World! :3 (this is too long)", sizeof buf);
puts(buf); // Undefined behavior, buf is not nil-terminated!

strzcpy() guarantees the result will be nil-terminated:

char buf[16] = {0};
strzcpy(buf, "Hello World! :3 (this is too long)", sizeof buf);
puts(buf); // “Hello World! :3”

Efficient string concatenation

When concatenating several strings, the return value of the previous call to strzcpy() can be used to avoid recalculating the length of the string in the destination buffer:

char buf[16] = {0};
char *buf_end = buf + sizeof buf;
char *last = buf;
if (last) last = strzcpy(last, "Hello ", buf_end - last);
if (last) last = strzcpy(last, "World!", buf_end - last);
if (last) last = strzcpy(last, " :3 ", buf_end - last);
if (last) last = strzcpy(last, "(this is too long)", buf_end - last);
assert(str_eq(buf, "Hello World! :3"));

Parameters

[out]	dest	Pointer to the character buffer to copy into
[in]	src	Pointer to the character buffer to copy from
[in]	len	The maximum number of characters to copy

Returns

If a nil terminator was copied, returns a pointer to that nil terminator in dest; otherwise, the string was truncated, and a nil pointer. is returned. A nil pointer. will also be returned if len is 0.

See also

WG14 N2349 “Toward more efficient string copying and concatenation”

NRK — I'm not a fan of strlcpy(3)

Howard Chu — The Sad State of C Strings

Keith Thompson — No, strncpy() is not a "safer" strcpy()

Bruce Dawson — Stop using strncpy already!

Linus Torvalds — strlcpy() notes