[thirdparty/man-pages.git] / man3 / wcpncpy.3

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