1.\" $OpenBSD: wcslcpy.3,v 1.6 2013/09/25 21:49:31 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.Dd $Mdocdate: September 25 2013 $ 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.In 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.Pp 92If the 93.Fa src 94and 95.Fa dst 96strings overlap, the behavior is undefined. 97.Sh RETURN VALUES 98The 99.Fn wcslcpy 100and 101.Fn wcslcat 102functions return the total length of the wide string they tried to create. 103For 104.Fn wcslcpy 105that means the length of 106.Fa src . 107For 108.Fn wcslcat 109that means the initial length of 110.Fa dst 111plus 112the length of 113.Fa src . 114While this may seem somewhat confusing, it was done to make 115truncation detection simple. 116.Pp 117Note, however, that if 118.Fn wcslcat 119traverses 120.Fa size 121wide characters without finding a null wide character, the length of the 122string is considered to be 123.Fa size 124and the destination wide string will not be terminated with a null wide 125character (since there was no space for it). 126This keeps 127.Fn wcslcat 128from running off the end of a wide string. 129In practice this should not happen (as it means that either 130.Fa size 131is incorrect or that 132.Fa dst 133is not terminated with a null wide character). 134The check exists to prevent potential security problems in incorrect code. 135.Sh SEE ALSO 136.Xr strlcpy 3 , 137.Xr swprintf 3 , 138.Xr wcsncat 3 , 139.Xr wcsncpy 3 140.Sh HISTORY 141The 142.Fn wcslcpy 143and 144.Fn wcslcat 145functions first appeared in 146.Ox 3.8 . 147.Sh AUTHORS 148The 149.Fn wcslcpy 150and 151.Fn wcslcat 152functions are based on code by 153.An Todd C. Miller Aq Mt Todd.Miller@courtesan.com . 154