xref: /illumos-gate/usr/src/man/man3c/wcpcpy.3c (revision 132157d7fb25c120ae1deca2a65fa7c78e8fcfd0)
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source.  A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
13 .\"
14 .Dd "Jul 27, 2014"
15 .Dt WCPCPY 3C
16 .Os
17 .Sh NAME
18 .Nm wcpcpy ,
19 .Nm wcpncpy
20 .Nd copy a wide-character string and return a pointer to its end
21 .Sh SYNOPSIS
22 .In wchar.h
23 .
24 .Ft "wchar_t *"
25 .Fo wcpcpy
26 .Fa "wchar_t *restrict ws1"
27 .Fa "const wchar_t *restrict ws2"
28 .Fc
29 .
30 .Ft "wchar_t *"
31 .Fo wcpncpy
32 .Fa "wchar_t *restrict ws1"
33 .Fa "const wchar_t *restrict ws2"
34 .Fa "size_t n"
35 .Fc
36 .
37 .Sh DESCRIPTION
38 The
39 .Fn wcpcpy
40 and
41 .Fn wcpncpy
42 functions copy the wide-character string pointed to by
43 .Fa ws2
44 into the location pointed to by
45 .Fa ws1 .
46 They stop copying after a null wide-character is copied, or in the case
47 of
48 .Fn wcpncpy ,
49 after
50 .Fa n
51 wide-characters have been copied. If
52 .Fa ws2
53 contains fewer than
54 .Fa n
55 wide-characters, then the
56 .Fn wcpncpy
57 function pads wide-characters to the end of the destination
58 .Fa ws1
59 until exactly
60 .Fa n
61 wide-characters have been written.
62 .Lp
63 In the case of
64 .Fn wcpncpy
65 a terminating null wide-character will
66 .Em not
67 be written if the length of
68 .Fa ws2
69 exceeds
70 .Fa n .
71 .Lp
72 If
73 .Fa ws1
74 and
75 .Fa ws2
76 overlap, the result is undefined.
77 .Lp
78 The
79 .Fn wcpcpy
80 and
81 .Fn wcpncpy
82 functions are the wide-character equivalents of
83 .Fn stpcpy
84 and
85 .Fn stpncpy ,
86 respectively.
87 .Sh RETURN VALUES
88 The
89 .Fn wcpcpy
90 and
91 .Fn wcpncpy
92 functions return a pointer to the last wide-character written.  In the
93 case of
94 .Fn wcpncpy
95 this will always be equal to
96 .Po Fa ws1 Li + Fa n Li \(mi 1 Pc .
97 .Sh ERRORS
98 None.
99 .Sh INTERFACE STABILITY
100 .Sy Standard .
101 .Sh MT-LEVEL
102 .Sy MT-Safe .
103 .Sh SEE ALSO
104 .Xr stpcpy 3C ,
105 .Xr stpncpy 3C ,
106 .Xr wcscpy 3C ,
107 .Xr wcsncpy 3C ,
108 .Xr wchar.h 3HEAD ,
109 .Xr standards 5
110 .Sh STANDARDS
111 The
112 .Fn wcpcpy
113 and
114 .Fn wcpncpy
115 functions were introduced in
116 .St -p1003.1-2008 .
117