.TH "ggstrlcpy" 3 "2005-08-26" "libgg-1.0.x" GGI
.SH NAME
\fBggstrlcpy\fR, \fBggstrlcat\fR \- size-bounded string copying and concatenation
.SH SYNOPSIS
.nf
#include <ggi/gg.h>

size_t ggstrlcpy(char *dst, const char *src, size_t siz);

size_t ggstrlcat(char *dst, const char *src, size_t siz);
.fi

.SH DESCRIPTION
The \fBggstrlcpy\fR and \fBggstrlcat\fR functions copy and concatenate strings
respectively.  They are designed to be safer, more consistent, and less
error prone replacements for \f(CWstrncpy(3)\fR and \f(CWstrncat(3)\fR.
Unlike those functions, \fBggstrlcpy\fR and \fBggstrlcat\fR take the full size
of the buffer (not just the length) and guarantee to NUL-terminate the
result (as long as size is larger than 0 or, in the case of \fBggstrlcat\fR,
as long as there is at least one byte free in \fIdst\fR).  Note that you should
include a byte for the NUL in size.  Also note that \fBggstrlcpy\fR and
\fBggstrlcat\fR only operate on true C strings.  This means that for
\fBggstrlcpy\fR \fIsrc\fR must be NUL-terminated and for \fBggstrlcat\fR both \fIsrc\fR
and \fIdst\fR must be NUL-terminated.

The \fBggstrlcpy\fR function copies up to \fIsiz\fR - 1 characters from the
NUL-terminated string \fIsrc\fR to \fIdst\fR, NUL-terminating the result.

The \fBggstrlcat\fR function appends the NUL-terminated string \fIsrc\fR to the
end of \fIdst\fR.  It will append at most \fIsiz\fR - strlen(\fIdst\fR) - 1 bytes,
NUL-terminating the result.
.SH RETURN VALUES
The \fBggstrlcpy\fR and \fBggstrlcat\fR functions return the total length of the
string they tried to create.  For \fBggstrlcpy\fR that means the length of \fIsrc\fR.
For \fBggstrlcat\fR that means the initial length of \fIdst\fR plus the length of
\fIsrc\fR.  While this may seem somewhat confusing it was done to make truncation
detection simple.

Note however, that if \fBggstrlcat\fR traverses size characters without finding
a NUL, the length of the string is considered to be size and the destination
string will not be NUL-terminated (since there was no space for the
NUL).  This keeps \fBggstrlcat\fR from running off the end of a string.  In
practice this should not happen (as it means that either size is incorrect
or that \fIdst\fR is not a proper C string).  The check exists to prevent
potential security problems in incorrect code.
.SH EXAMPLES
The following code fragment illustrates the simple case:

.nf
char *s, *p, buf[BUFSIZ];

\fR...

(void)ggstrlcpy(buf, s, sizeof(buf));
(void)ggstrlcat(buf, p, sizeof(buf));
.fi

To detect truncation, perhaps while building a pathname, something like
the following might be used:

.nf
char *dir, *file, pname[MAXPATHLEN];

\fR...

if (ggstrlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
        goto toolong;
if (ggstrlcat(pname, file, sizeof(pname)) >= sizeof(pname))
        goto toolong;
.fi

Since we know how many characters we copied the first time, we can speed
things up a bit by using a copy instead of an append:

.nf
char *dir, *file, pname[MAXPATHLEN];
size_t n;

\fR...

n = ggstrlcpy(pname, dir, sizeof(pname));
if (n >= sizeof(pname))
        goto toolong;
if (ggstrlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
        goto toolong;
.fi

However, one may question the validity of such optimizations, as they defeat
the whole purpose of \fBggstrlcpy\fR and \fBggstrlcat\fR.
.SH SEE ALSO
\f(CWsnprintf(3)\fR \f(CWstrncat(3)\fR \f(CWstrncpy(3)\fR
.SH HISTORY
\fBstrlcpy\fR and \fBstrlcat\fR first appeared in OpenBSD 2.4, then in
NetBSD 1.4.3 and FreeBSD 3.3.0.
\fBggstrlcpy\fR and \fBggstrlcat\fR has been added to libgg for
portability.