1  .\"	$OpenBSD: strlcpy.3,v 1.26 2013/09/30 12:02:35 millert Exp $
  2  .\"
  3  .\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com>
  4  .\"
  5  .\" Permission to use, copy, modify, and distribute this software for any
  6  .\" purpose with or without fee is hereby granted, provided that the above
  7  .\" copyright notice and this permission notice appear in all copies.
  8  .\"
  9  .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 10  .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 11  .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 12  .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 13  .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 14  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 15  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 16  .\"
 17  .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
 18  .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 19  .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
 20  .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 21  .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 22  .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 23  .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 24  .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 25  .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 26  .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 27  .\"
 28  .\" $FreeBSD$
 29  .\"
 30  .Dd February 26, 2016
 31  .Dt STRLCPY 3
 32  .Os
 33  .Sh NAME
 34  .Nm strlcpy ,
 35  .Nm strlcat
 36  .Nd size-bounded string copying and concatenation
 37  .Sh LIBRARY
 38  .Lb libc
 39  .Sh SYNOPSIS
 40  .In string.h
 41  .Ft size_t
 42  .Fn strlcpy "char * restrict dst" "const char * restrict src" "size_t dstsize"
 43  .Ft size_t
 44  .Fn strlcat "char * restrict dst" "const char * restrict src" "size_t dstsize"
 45  .Sh DESCRIPTION
 46  The
 47  .Fn strlcpy
 48  and
 49  .Fn strlcat
 50  functions copy and concatenate strings with the
 51  same input parameters and output result as
 52  .Xr snprintf 3 .
 53  They are designed to be safer, more consistent, and less error
 54  prone replacements for the easily misused functions
 55  .Xr strncpy 3
 56  and
 57  .Xr strncat 3 .
 58  .Pp
 59  .Fn strlcpy
 60  and
 61  .Fn strlcat
 62  take the full size of the destination buffer and guarantee
 63  NUL-termination if there is room.
 64  Note that room for the NUL should be included in
 65  .Fa dstsize .
 66  .Pp
 67  .Fn strlcpy
 68  copies up to
 69  .Fa dstsize
 70  \- 1 characters from the string
 71  .Fa src
 72  to
 73  .Fa dst ,
 74  NUL-terminating the result if
 75  .Fa dstsize
 76  is not 0.
 77  .Pp
 78  .Fn strlcat
 79  appends string
 80  .Fa src
 81  to the end of
 82  .Fa dst .
 83  It will append at most
 84  .Fa dstsize
 85  \- strlen(dst) \- 1 characters.
 86  It will then NUL-terminate, unless
 87  .Fa dstsize
 88  is 0 or the original
 89  .Fa dst
 90  string was longer than
 91  .Fa dstsize
 92  (in practice this should not happen
 93  as it means that either
 94  .Fa dstsize
 95  is incorrect or that
 96  .Fa dst
 97  is not a proper string).
 98  .Pp
 99  If the
100  .Fa src
101  and
102  .Fa dst
103  strings overlap, the behavior is undefined.
104  .Sh RETURN VALUES
105  Besides quibbles over the return type
106  .Pf ( Va size_t
107  versus
108  .Va int )
109  and signal handler safety
110  .Pf ( Xr snprintf 3
111  is not entirely safe on some systems), the
112  following two are equivalent:
113  .Bd -literal -offset indent
114  n = strlcpy(dst, src, len);
115  n = snprintf(dst, len, "%s", src);
116  .Ed
117  .Pp
118  Like
119  .Xr snprintf 3 ,
120  the
121  .Fn strlcpy
122  and
123  .Fn strlcat
124  functions return the total length of the string they tried to create.
125  For
126  .Fn strlcpy
127  that means the length of
128  .Fa src .
129  For
130  .Fn strlcat
131  that means the initial length of
132  .Fa dst
133  plus
134  the length of
135  .Fa src .
136  .Pp
137  If the return value is
138  .Cm >=
139  .Va dstsize ,
140  the output string has been truncated.
141  It is the caller's responsibility to handle this.
142  .Sh EXAMPLES
143  The following code fragment illustrates the simple case:
144  .Bd -literal -offset indent
145  char *s, *p, buf[BUFSIZ];
146  
147  \&...
148  
149  (void)strlcpy(buf, s, sizeof(buf));
150  (void)strlcat(buf, p, sizeof(buf));
151  .Ed
152  .Pp
153  To detect truncation, perhaps while building a pathname, something
154  like the following might be used:
155  .Bd -literal -offset indent
156  char *dir, *file, pname[MAXPATHLEN];
157  
158  \&...
159  
160  if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
161  	goto toolong;
162  if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
163  	goto toolong;
164  .Ed
165  .Pp
166  Since it is known how many characters were copied the first time, things
167  can be sped up a bit by using a copy instead of an append:
168  .Bd -literal -offset indent
169  char *dir, *file, pname[MAXPATHLEN];
170  size_t n;
171  
172  \&...
173  
174  n = strlcpy(pname, dir, sizeof(pname));
175  if (n >= sizeof(pname))
176  	goto toolong;
177  if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
178  	goto toolong;
179  .Ed
180  .Pp
181  However, one may question the validity of such optimizations, as they
182  defeat the whole purpose of
183  .Fn strlcpy
184  and
185  .Fn strlcat .
186  As a matter of fact, the first version of this manual page got it wrong.
187  .Sh SEE ALSO
188  .Xr snprintf 3 ,
189  .Xr strncat 3 ,
190  .Xr strncpy 3 ,
191  .Xr wcslcpy 3
192  .Sh HISTORY
193  The
194  .Fn strlcpy
195  and
196  .Fn strlcat
197  functions first appeared in
198  .Ox 2.4 ,
199  and
200  .Fx 3.3 .