xref: /netbsd-src/lib/libc/string/strncpy.3 (revision 865c57e0098351fba0d2d2a97b33e7e0270e62c6) 
1.\" Copyright (c) 1990, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Chris Torek and the American National Standards Committee X3,
6.\" on Information Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     from: @(#)strcpy.3	8.1 (Berkeley) 6/4/93
33.\"     from: NetBSD: strcpy.3,v 1.23 2015/04/01 20:18:17 riastradh Exp
34.\"	$NetBSD: strncpy.3,v 1.8 2023/08/11 16:04:25 riastradh Exp $
35.\"
36.Dd August 11, 2023
37.Dt STRNCPY 3
38.Os
39.Sh NAME
40.Nm stpncpy ,
41.Nm strncpy
42.Nd copy fixed-width string buffers
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In string.h
47.Ft char *
48.Fn stpncpy "char * restrict dst" "const char * restrict src" "size_t len"
49.Ft char *
50.Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len"
51.Sh DESCRIPTION
52The
53.Fn stpncpy
54and
55.Fn strncpy
56functions copy at most
57.Fa len
58.No non- Ns Tn NUL
59characters from
60.Fa src
61into
62.Fa dst .
63If
64.Fa src
65is less than
66.Fa len
67characters long before the first
68.Tn NUL
69character, the remainder of
70.Fa dst
71is filled with
72.Tn NUL
73characters.
74Otherwise,
75.Fa dst
76is
77.Em not
78terminated with a
79.Tn NUL
80character.
81.Pp
82The strings
83.Fa src
84and
85.Fa dst
86may not overlap.
87.Sh RETURN VALUES
88The
89.Fn strncpy
90function returns
91.Fa dst .
92.Pp
93The
94.Fn stpncpy
95function returns a pointer to the terminating
96.Tn NUL
97character of
98.Fa dst .
99If
100.Fn stpncpy
101does not terminate
102.Fa dst
103with a
104.Tn NUL
105character, it instead returns a pointer to
106.Sm off
107.Fa dst Li "[" Fa len Li "]" ,
108.Sm on
109which may be one past the last element of an array.
110.Sh EXAMPLES
111The following logic fills a fixed-width field in a record that might
112appear on disk with the content of a caller-provided string
113.Dv str ,
114padded to the end of the field with
115.Tn NUL
116characters:
117.Bd -literal -offset indent
118struct record {
119	uint16_t	id;
120	char		name[6];
121	uint8_t		tag;
122	...
123};
124
125struct record *rec = ...;
126strncpy(rec->name, str, sizeof(rec->name));
127.Ed
128.Pp
129The following values for
130.Dv str
131result in the following corresponding contents of
132.Dv rec Ns Li "->name" :
133.Bl -column -offset indent ".Li \*qabcdefghi\*q" ".Li \*qabc\e0\e0\e0\*q"
134.It Dv str Ta Dv rec Ns Li "->name"
135.It Li \*qabc\e0\*q Ta Li \*qabc\e0\e0\e0\*q
136.It Li \*qabc\e0\e0\e0\*q Ta Li \*qabc\e0\e0\e0\*q
137.It Li \*qabcde\e0\*q Ta Li \*qabcde\e0\*q
138.It Li \*qabcdef\e0\*q Ta Li \*qabcdef\*q
139.It Li \*qabcdef\*q Ta Li \*qabcdef\*q
140.It Li \*qabcdefghi\e0\*q Ta Li \*qabcdef\*q
141.It Li \*qabcdefghi\*q Ta Li \*qabcdef\*q
142.El
143.Pp
144Note that when
145.Dv str
146has at least six
147.No non- Ns Tn NUL
148characters,
149.Dv rec Ns Li "->name"
150is
151.Em not
152.Tn NUL Ns -terminated
153\(em it is only
154.Em padded
155with (possibly zero)
156.Tn NUL
157bytes to fill the fixed-width buffer.
158When
159.Dv str
160has
161.Em more
162than six
163.No non- Ns Tn NUL
164characters, the additional ones are truncated.
165If
166.Dv str
167has space for
168.Em fewer
169than six characters, and the last one is not
170.Tn NUL ,
171using
172.Fn strncpy
173is undefined.
174.Pp
175Because
176.Fn strncpy
177does
178.Em not
179guarantee to
180.Tn NUL Ns -terminate
181the result, if
182.Tn NUL Ns -termination
183is required it must be done explicitly:
184.Bd -literal -offset indent
185char buf[1024];
186
187(void)strncpy(buf, input, sizeof(buf) - 1);
188buf[sizeof(buf) - 1] = '\e0';
189.Ed
190.Pp
191If
192.Va buf
193need only be
194.Tn NUL Ns -terminated ,
195not fully initialized with
196.Tn NUL
197padding,
198this could be achieved using
199.Xr strlcpy 3
200as follows:
201.Bd -literal -offset indent
202(void)strlcpy(buf, input, sizeof(buf));
203.Ed
204.Pp
205Note that because
206.Xr strlcpy 3
207is not defined in any standards, it should
208only be used when portability is not a concern.
209.Pp
210.Sy WARNING :
211Because
212.Xr strlcpy 3
213does not fully initialize
214.Fa dst ,
215it is
216.Em not
217a safe
218.Tn NUL Ns -terminating
219replacement for
220.Fn strncpy
221if the buffer is not separately zero-initialized.
222Naively replacing
223.Fn strncpy
224by
225.Xr strlcpy 3
226can lead to disclosure of secrets from uninitialized memory.
227.Sh SEE ALSO
228.Xr bcopy 3 ,
229.Xr memccpy 3 ,
230.Xr memcpy 3 ,
231.Xr memmove 3 ,
232.Xr strcpy 3 ,
233.Xr strlcpy 3 ,
234.Xr wcscpy 3
235.Sh STANDARDS
236The
237.Fn strncpy
238function conforms to
239.St -isoC-99 .
240.Pp
241The
242.Fn stpncpy
243function conforms to
244.St -p1003.1-2008 .
245.Sh HISTORY
246The
247.Fn stpncpy
248function first appeared in
249.Nx 6.0 .
250.Sh SECURITY CONSIDERATIONS
251The
252.Fn stpncpy
253and
254.Fn strncpy
255functions are not guaranteed to
256.Tn NUL Ns -terminate
257the result.
258