NAME

stpncpy, strncpy — copy fixed-width buffers with NUL padding

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <string.h>

char *
stpncpy(char * restrict dst, const char * restrict src, size_t len);

char *
strncpy(char * restrict dst, const char * restrict src, size_t len);

DESCRIPTION

The stpncpy() and strncpy() functions fill a len-byte buffer at dst by copying up to len non-NUL bytes from src followed by enough NUL bytes — possibly zero of them — to pad the remainder.

The buffers src and dst may not overlap.

The buffer src is not required to hold a NUL-terminated string on input; it is only required either to have at least len bytes allocated and initialized, or to have a NUL byte if it is shorter than len bytes.

The buffer dst is not guaranteed to hold a NUL-terminated string on output; stpncpy() and strncpy() write exactly len bytes to it, which includes nonempty NUL padding only if a NUL byte appears in the first len bytes at src.

RETURN VALUES

The strncpy() function returns dst.

The stpncpy() function returns a pointer to the byte after the last non-NUL byte of dst. This does not necessarily point to a NUL byte; stpncpy() may return &dst[len], if all len bytes starting at src are non- NUL.

EXAMPLES

The following logic fills a fixed-width field in a record that might appear on disk with the content of a caller-provided string str, padded to the end of the field with NUL bytes:

struct record {
	uint16_t	id;
	char		name[6];
	uint8_t		tag;
	...
};

struct record *rec = ...;
strncpy(rec->name, str, sizeof(rec->name));

The following values for str result in the following corresponding contents of rec->name:

Note that when str has at least six non-NUL bytes, rec->name is not NUL-terminated — it is only padded with (possibly zero) NUL bytes to fill the fixed-width buffer. When str has more than six non-NUL bytes, the additional ones are truncated. If str has space for fewer than six bytes, and the last one is not NUL, using strncpy() is undefined.

Because strncpy() does not guarantee to NUL-terminate the result, if NUL-termination is required it must be done explicitly:

char buf[1024];

strncpy(buf, input, sizeof(buf) - 1);
buf[sizeof(buf) - 1] = '\0';

If input is guaranteed to be NUL-terminated, and if buf need only be NUL-terminated, not fully initialized with NUL padding, this could be achieved using strlcpy(3) as follows:

strlcpy(buf, input, sizeof(buf));

It is not enough for input to have sizeof(buf) bytes allocated; it MUST be NUL-terminated for strlcpy(3) to be used.

Note that because strlcpy(3) is not defined in any standards, it should only be used when portability is not a concern.

WARNING: Because strlcpy(3) does not fully initialize dst, but does read all the way to a NUL terminator in src even past len bytes, strlcpy(3) is not a safe NUL-terminating replacement for strncpy(). Naively replacing strncpy() by strlcpy(3) can lead to crashes, undefined behaviour, and disclosure of secrets from uninitialized memory.

SEE ALSO

bcopy(3), memccpy(3), memcpy(3), memmove(3), strcpy(3), strlcpy(3), wcscpy(3)

STANDARDS

The strncpy() function conforms to ISO/IEC 9899:1999 (“ISO C99”).

The stpncpy() function conforms to IEEE Std 1003.1-2008 (“POSIX.1”).

HISTORY

The stpncpy() function first appeared in NetBSD 6.0.

SECURITY CONSIDERATIONS

The stpncpy() and strncpy() functions are not guaranteed to NUL-terminate the result.