[thirdparty/man-pages.git] / man3 / stpncpy.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
.\"
.\" Corrected, aeb, 990824
.TH STPNCPY 3  2015-03-02 "GNU" "Linux Programmer's Manual"
.SH NAME
stpncpy \- copy a fixed-size string, returning a pointer to its end
.SH SYNOPSIS
.nf
.B #include <string.h>
.sp
.BI "char *stpncpy(char *" dest ", const char *" src ", size_t " n );
.fi
.sp
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.sp
.BR stpncpy ():
.PD 0
.ad l
.RS 4
.TP 4
Since glibc 2.10:
_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
.TP
Before glibc 2.10:
_GNU_SOURCE
.RE
.ad
.PD
.SH DESCRIPTION
The
.BR stpncpy ()
function copies at most
.I n
characters from the string
pointed to by
.IR src ,
including the terminating null byte (\(aq\\0\(aq),
to the array pointed to by
.IR dest .
Exactly
.I n
characters are written at
.IR dest .
If the length
.I strlen(src)
is smaller than
.IR n ,
the
remaining characters in the array pointed to by
.I dest
are filled
with null bytes (\(aq\\0\(aq),
If the length
.I strlen(src)
is greater than or equal to
.IR n ,
the string pointed to by
.I dest
will
not be null-terminated.
.PP
The strings may not overlap.
.PP
The programmer must ensure that there is room for at least
.I n
characters
at
.IR dest .
.SH RETURN VALUE
.BR stpncpy ()
returns a pointer to the terminating null byte
in
.IR dest ,
or, if
.I dest
is not null-terminated,
.IR dest + n .
.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 stpncpy ()
T}	Thread safety	MT-Safe
.TE
.SH CONFORMING TO
This function was added to POSIX.1-2008.
Before that, it was a GNU extension.
It first appeared in version 1.07 of the GNU C library in 1993.
.SH SEE ALSO
.BR strncpy (3),
.BR wcpncpy (3)
Commit	Line	Data
fea681da MK	1	.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
fea681da MK	2	.\"
89e3ffe9	3	.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
fea681da MK	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.
fe382ebf	8	.\" %%%LICENSE_END
fea681da MK	9	.\"
	10	.\" References consulted:
	11	.\" GNU glibc-2 source code and manual
	12	.\"
	13	.\" Corrected, aeb, 990824
fe0fefbf	14	.TH STPNCPY 3 2015-03-02 "GNU" "Linux Programmer's Manual"
fea681da MK	15	.SH NAME
	16	stpncpy \- copy a fixed-size string, returning a pointer to its end
	17	.SH SYNOPSIS
	18	.nf
fea681da MK	19	.B #include <string.h>
	20	.sp
	21	.BI "char stpncpy(char " dest ", const char *" src ", size_t " n );
	22	.fi
79247bb1 MK	23	.sp
	24	.in -4n
	25	Feature Test Macro Requirements for glibc (see
	26	.BR feature_test_macros (7)):
	27	.in
	28	.sp
	29	.BR stpncpy ():
ea91c3fd MK	30	.PD 0
	31	.ad l
	32	.RS 4
	33	.TP 4
	34	Since glibc 2.10:
	35	_XOPEN_SOURCE\ >=\ 700 \|\| _POSIX_C_SOURCE\ >=\ 200809L
	36	.TP
79247bb1 MK	37	Before glibc 2.10:
79247bb1 MK	38	_GNU_SOURCE
ea91c3fd MK	39	.RE
	40	.ad
	41	.PD
fea681da	42	.SH DESCRIPTION
60a90ecd MK	43	The
60a90ecd MK	44	.BR stpncpy ()
e4a0d6cb MK	45	function copies at most
	46	.I n
	47	characters from the string
	48	pointed to by
	49	.IR src ,
	50	including the terminating null byte (\(aq\\0\(aq),
	51	to the array pointed to by
	52	.IR dest .
	53	Exactly
	54	.I n
	55	characters are written at
	56	.IR dest .
	57	If the length
	58	.I strlen(src)
	59	is smaller than
	60	.IR n ,
	61	the
	62	remaining characters in the array pointed to by
	63	.I dest
	64	are filled
71d9e7ae	65	with null bytes (\(aq\\0\(aq),
e4a0d6cb MK	66	If the length
e4a0d6cb MK	67	.I strlen(src)
0d2eda1a	68	is greater than or equal to
e4a0d6cb MK	69	.IR n ,
	70	the string pointed to by
	71	.I dest
	72	will
71d9e7ae	73	not be null-terminated.
fea681da MK	74	.PP
	75	The strings may not overlap.
	76	.PP
e4a0d6cb MK	77	The programmer must ensure that there is room for at least
	78	.I n
	79	characters
	80	at
	81	.IR dest .
47297adb	82	.SH RETURN VALUE
60a90ecd	83	.BR stpncpy ()
aa198ef9	84	returns a pointer to the terminating null byte
e4a0d6cb MK	85	in
	86	.IR dest ,
	87	or, if
	88	.I dest
	89	is not null-terminated,
716fe466	90	.IR dest + n .
f27f40b7	91	.SH ATTRIBUTES
ea1e1b75 PH	92	For an explanation of the terms used in this section, see
	93	.BR attributes (7).
	94	.TS
	95	allbox;
	96	lb lb lb
	97	l l l.
	98	Interface Attribute Value
	99	T{
f27f40b7	100	.BR stpncpy ()
ea1e1b75 PH	101	T} Thread safety MT-Safe
ea1e1b75 PH	102	.TE
47297adb	103	.SH CONFORMING TO
e3948c69 MK	104	This function was added to POSIX.1-2008.
e3948c69 MK	105	Before that, it was a GNU extension.
e06ba91b	106	It first appeared in version 1.07 of the GNU C library in 1993.
47297adb	107	.SH SEE ALSO
1709027c	108	.BR strncpy (3),
0a4f8b7b	109	.BR wcpncpy (3)