1.\" $OpenBSD: wcslcpy.3,v 1.3 2011/07/25 07:51:30 jmc 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.Dd $Mdocdate: July 25 2011 $ 18.Dt WCSLCPY 3 19.Os 20.Sh NAME 21.Nm wcslcpy , 22.Nm wcslcat 23.Nd size-bounded wide string copying and concatenation 24.Sh SYNOPSIS 25.Fd #include <wchar.h> 26.Ft size_t 27.Fn wcslcpy "wchar_t *dst" "const wchar_t *src" "size_t size" 28.Ft size_t 29.Fn wcslcat "wchar_t *dst" "const wchar_t *src" "size_t size" 30.Sh DESCRIPTION 31The 32.Fn wcslcpy 33and 34.Fn wcslcat 35functions copy and concatenate wide strings respectively. 36They are designed to be safer, more consistent, and less error prone 37replacements for 38.Xr wcsncpy 3 39and 40.Xr wcsncat 3 . 41Unlike those functions, 42.Fn wcslcpy 43and 44.Fn wcslcat 45take the full size of the buffer (not just the length) and guarantee to 46terminate the result with a null wide character (as long as 47.Fa size 48is larger than 0 or, in the case of 49.Fn wcslcat , 50as long as there is at least one wide character free in 51.Fa dst ) . 52Note that a wide character for the null wide character should be included in 53.Fa size . 54Also note that 55.Fn wcslcpy 56and 57.Fn wcslcat 58only operate on wide strings that are terminated with a null wide character 59(L'\e0'). 60This means that for 61.Fn wcslcpy 62.Fa src 63must be terminated with a null wide character and for 64.Fn wcslcat 65both 66.Fa src 67and 68.Fa dst 69must be terminated with a null wide character. 70.Pp 71The 72.Fn wcslcpy 73function copies up to 74.Fa size 75\(mi 1 wide characters from the wide string 76.Fa src 77to 78.Fa dst , 79terminating the result with a null wide character. 80.Pp 81The 82.Fn wcslcat 83function appends the wide string 84.Fa src 85to the end of 86.Fa dst . 87It will append at most 88.Fa size 89\(mi wcslen(dst) \(mi 1 wide characters, terminating the result with a null 90wide character. 91.Sh RETURN VALUES 92The 93.Fn wcslcpy 94and 95.Fn wcslcat 96functions return the total length of the wide string they tried to create. 97For 98.Fn wcslcpy 99that means the length of 100.Fa src . 101For 102.Fn wcslcat 103that means the initial length of 104.Fa dst 105plus 106the length of 107.Fa src . 108While this may seem somewhat confusing, it was done to make 109truncation detection simple. 110.Pp 111Note, however, that if 112.Fn wcslcat 113traverses 114.Fa size 115wide characters without finding a null wide character, the length of the 116string is considered to be 117.Fa size 118and the destination wide string will not be terminated with a null wide 119character (since there was no space for it). 120This keeps 121.Fn wcslcat 122from running off the end of a wide string. 123In practice this should not happen (as it means that either 124.Fa size 125is incorrect or that 126.Fa dst 127is not terminated with a null wide character). 128The check exists to prevent potential security problems in incorrect code. 129.Sh SEE ALSO 130.Xr strlcpy 3 , 131.Xr swprintf 3 , 132.Xr wcsncat 3 , 133.Xr wcsncpy 3 134.Sh HISTORY 135The 136.Fn wcslcpy 137and 138.Fn wcslcat 139functions first appeared in 140.Ox 3.8 . 141.Sh AUTHORS 142The 143.Fn wcslcpy 144and 145.Fn wcslcat 146functions are based on code by 147.An Todd C. Miller Aq Todd.Miller@courtesan.com . 148