man3/wcpncpy.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" References consulted:
  11 .\"   GNU glibc-2 source code and manual
  12 .\"   Dinkumware C library reference http://www.dinkumware.com/
  13 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  14 .\"
  15 .TH WCPNCPY 3 2021-03-22 "GNU" "Linux Programmer's Manual"
  16 .SH NAME
  17 wcpncpy \- copy a fixed-size string of wide characters,
  18 returning a pointer to its end
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <wchar.h>
  22 .PP
  23 .BI "wchar_t *wcpncpy(wchar_t *restrict " dest \
  24 ", const wchar_t *restrict " src ,
  25 .BI "                 size_t " n );
  26 .fi
  27 .PP
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 .BR wcpncpy ():
  34 .nf
  35     Since glibc 2.10:
  36         _POSIX_C_SOURCE >= 200809L
  37     Before glibc 2.10:
  38         _GNU_SOURCE
  39 .fi
  40 .SH DESCRIPTION
  41 The
  42 .BR wcpncpy ()
  43 function is the wide-character equivalent
  44 of the
  45 .BR stpncpy (3)
  46 function.
  47 It copies at most
  48 .I n
  49 wide characters from the wide-character
  50 string pointed to by
  51 .IR src ,
  52 including the terminating null wide (L\(aq\e0\(aq),
  53 to the array pointed to by
  54 .IR dest .
  55 Exactly
  56 .I n
  57 wide characters are
  58 written at
  59 .IR dest .
  60 If the length
  61 .IR wcslen(src)
  62 is smaller than
  63 .IR n ,
  64 the remaining wide characters in the array pointed to
  65 by
  66 .I dest
  67 are filled with L\(aq\e0\(aq characters.
  68 If the length
  69 .IR wcslen(src)
  70 is greater than or equal
  71 to
  72 .IR n ,
  73 the string pointed to by
  74 .I dest
  75 will
  76 not be L\(aq\e0\(aq terminated.
  77 .PP
  78 The strings may not overlap.
  79 .PP
  80 The programmer must ensure that there is room for at least
  81 .I n
  82 wide
  83 characters at
  84 .IR dest .
  85 .SH RETURN VALUE
  86 .BR wcpncpy ()
  87 returns a pointer to the last wide character written, that is,
  88 .IR dest + n \-1.
  89 .SH ATTRIBUTES
  90 For an explanation of the terms used in this section, see
  91 .BR attributes (7).
  92 .ad l
  93 .nh
  94 .TS
  95 allbox;
  96 lbx lb lb
  97 l l l.
  98 Interface       Attribute       Value
  99 T{
 100 .BR wcpncpy ()
 101 T}      Thread safety   MT-Safe
 102 .TE
 103 .hy
 104 .ad
 105 .sp 1
 106 .SH CONFORMING TO
 107 POSIX.1-2008.
 108 .SH SEE ALSO
 109 .BR stpncpy (3),
 110 .BR wcsncpy (3)