usr/src/man/man3c/wcpcpy.3c

   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.
  52 If
  53 .Fa ws2
  54 contains fewer than
  55 .Fa n
  56 wide-characters, then the
  57 .Fn wcpncpy
  58 function pads wide-characters to the end of the destination
  59 .Fa ws1
  60 until exactly
  61 .Fa n
  62 wide-characters have been written.
  63 .Lp
  64 In the case of
  65 .Fn wcpncpy
  66 a terminating null wide-character will
  67 .Em not
  68 be written if the length of
  69 .Fa ws2
  70 exceeds
  71 .Fa n .
  72 .Lp
  73 If
  74 .Fa ws1
  75 and
  76 .Fa ws2
  77 overlap, the result is undefined.
  78 .Lp
  79 The
  80 .Fn wcpcpy
  81 and
  82 .Fn wcpncpy
  83 functions are the wide-character equivalents of
  84 .Fn stpcpy
  85 and
  86 .Fn stpncpy ,
  87 respectively.
  88 .Sh RETURN VALUES
  89 The
  90 .Fn wcpcpy
  91 and
  92 .Fn wcpncpy
  93 functions return a pointer to the last wide-character written.
  94 In the case of
  95 .Fn wcpncpy
  96 this will always be equal to
  97 .Po Fa ws1 Li + Fa n Li \(mi 1 Pc .
  98 .Sh ERRORS
  99 None.
 100 .Sh INTERFACE STABILITY
 101 .Sy Standard .
 102 .Sh MT-LEVEL
 103 .Sy MT-Safe .
 104 .Sh SEE ALSO
 105 .Xr stpcpy 3C ,
 106 .Xr stpncpy 3C ,
 107 .Xr wcscpy 3C ,
 108 .Xr wcsncpy 3C ,
 109 .Xr wchar.h 3HEAD ,
 110 .Xr standards 5
 111 .Sh STANDARDS
 112 The
 113 .Fn wcpcpy
 114 and
 115 .Fn wcpncpy
 116 functions were introduced in
 117 .St -p1003.1-2008 .