1ggstrlcpy(3)                          GGI                         ggstrlcpy(3)
2
3
4

NAME

6       ggstrlcpy, ggstrlcat : size-bounded string copying and concatenation
7

SYNOPSIS

9       #include <ggi/gg.h>
10
11       size_t ggstrlcpy(char *dst, const char *src, size_t siz);
12
13       size_t ggstrlcat(char *dst, const char *src, size_t siz);
14
15

DESCRIPTION

17       The  ggstrlcpy  and  ggstrlcat  functions  copy and concatenate strings
18       respectively.  They are designed to be safer, more consistent, and less
19       error  prone  replacements for strncpy(3) and strncat(3).  Unlike those
20       functions, ggstrlcpy and ggstrlcat take the full  size  of  the  buffer
21       (not  just  the  length)  and guarantee to NUL-terminate the result (as
22       long as size is larger than 0 or, in the case of ggstrlcat, as long  as
23       there  is at least one byte free in dst).  Note that you should include
24       a byte for the NUL in size.  Also note  that  ggstrlcpy  and  ggstrlcat
25       only operate on true C strings.  This means that for ggstrlcpy src must
26       be NUL-terminated and for ggstrlcat both src and dst must be NUL-termi‐
27       nated.
28
29       The  ggstrlcpy  function  copies up to siz - 1 characters from the NUL-
30       terminated string src to dst, NUL-terminating the result.
31
32       The ggstrlcat function appends the NUL-terminated string src to the end
33       of dst.  It will append at most siz - strlen(dst) - 1 bytes, NUL-termi‐
34       nating the result.
35

RETURN VALUES

37       The ggstrlcpy and ggstrlcat functions return the total  length  of  the
38       string  they  tried  to create.  For ggstrlcpy that means the length of
39       src.  For ggstrlcat that means the  initial  length  of  dst  plus  the
40       length  of  src.  While this may seem somewhat confusing it was done to
41       make truncation detection simple.
42
43       Note however, that if ggstrlcat traverses size characters without find‐
44       ing  a  NUL,  the length of the string is considered to be size and the
45       destination string will not be NUL-terminated (since there was no space
46       for  the  NUL).   This  keeps  ggstrlcat  from running off the end of a
47       string.  In practice this should not happen (as it  means  that  either
48       size  is  incorrect  or  that dst is not a proper C string).  The check
49       exists to prevent potential security problems in incorrect code.
50

EXAMPLES

52       The following code fragment illustrates the simple case:
53
54       char *s, *p, buf[BUFSIZ];
55
56
57       (void)ggstrlcpy(buf, s, sizeof(buf));
58       (void)ggstrlcat(buf, p, sizeof(buf));
59
60       To detect truncation, perhaps while building a pathname, something like
61       the following might be used:
62
63       char *dir, *file, pname[MAXPATHLEN];
64
65
66       if (ggstrlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
67               goto toolong;
68       if (ggstrlcat(pname, file, sizeof(pname)) >= sizeof(pname))
69               goto toolong;
70
71       Since  we  know  how  many  characters we copied the first time, we can
72       speed things up a bit by using a copy instead of an append:
73
74       char *dir, *file, pname[MAXPATHLEN];
75       size_t n;
76
77
78       n = ggstrlcpy(pname, dir, sizeof(pname));
79       if (n >= sizeof(pname))
80               goto toolong;
81       if (ggstrlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
82               goto toolong;
83
84       However, one may question the validity of such optimizations,  as  they
85       defeat the whole purpose of ggstrlcpy and ggstrlcat.
86

SEE ALSO

88       snprintf(3) strncat(3) strncpy(3)
89

HISTORY

91       strlcpy and strlcat first appeared in OpenBSD 2.4, then in NetBSD 1.4.3
92       and FreeBSD 3.3.0.  ggstrlcpy and ggstrlcat has been added to libgg for
93       portability.
94
95
96
97libgg-1.0.x                       2005-08-26                      ggstrlcpy(3)