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.16 2023/08/13 11:27:22 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 buffers with NUL padding 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 fill a 57.Fa len Ns -byte 58buffer at 59.Fa dst 60by copying up to 61.Fa len 62.No non- Ns Tn NUL 63bytes from 64.Fa src 65followed by enough 66.Tn NUL 67bytes \(em possibly zero of them \(em to pad the remainder. 68.Pp 69The buffers 70.Fa src 71and 72.Fa dst 73may not overlap. 74.Pp 75The buffer 76.Fa src 77is not required to hold a 78.Tn NUL Ns -terminated 79string on input; it is only required 80.Em either 81to have at least 82.Fa len 83bytes allocated and initialized, 84.Em or 85to have a 86.Tn NUL 87byte if it is shorter than 88.Fa len 89bytes. 90.Pp 91The buffer 92.Fa dst 93is not guaranteed to hold a 94.Tn NUL Ns -terminated 95string on output; 96.Fn stpncpy 97and 98.Fn strncpy 99write exactly 100.Fa len 101bytes to it, which includes nonempty 102.Tn NUL 103padding only if a 104.Tn NUL 105byte appears in the first 106.Fa len 107bytes at 108.Fa src . 109.Sh RETURN VALUES 110The 111.Fn strncpy 112function returns 113.Fa dst . 114.Pp 115The 116.Fn stpncpy 117function returns a pointer to the byte after the last 118.No non- Ns Tn NUL 119byte of 120.Fa dst . 121This does not necessarily point to a 122.Tn NUL 123byte; 124.Fn stpncpy 125may return 126.Li \*(Am Ns Fa dst Ns Li "[" Fa len Ns Li "]" Ns , 127if all 128.Fa len 129bytes starting at 130.Fa src 131are 132.No non- Tn NUL . 133.Sh EXAMPLES 134The following logic fills a fixed-width field in a record that might 135appear on disk with the content of a caller-provided string 136.Dv str , 137padded to the end of the field with 138.Tn NUL 139bytes: 140.Bd -literal -offset indent 141struct record { 142 uint16_t id; 143 char name[6]; 144 uint8_t tag; 145 ... 146}; 147 148struct record *rec = ...; 149strncpy(rec->name, str, sizeof(rec->name)); 150.Ed 151.Pp 152The following values for 153.Dv str 154result in the following corresponding contents of 155.Dv rec Ns Li "->name" : 156.Bl -column -offset indent ".Li \*qabcdefghi\e0\*q" ".Li \*qabc\e0\e0\e0\*q" 157.It Dv str Ta Dv rec Ns Li "->name" 158.It Li \*qabc\e0\*q Ta Li \*qabc\e0\e0\e0\*q 159.It Li \*qabc\e0\e0\e0\*q Ta Li \*qabc\e0\e0\e0\*q 160.It Li \*qabcde\e0\*q Ta Li \*qabcde\e0\*q 161.It Li \*qabcdef\e0\*q Ta Li \*qabcdef\*q 162.It Li \*qabcdef\*q Ta Li \*qabcdef\*q 163.It Li \*qabcdefghi\e0\*q Ta Li \*qabcdef\*q 164.It Li \*qabcdefghi\*q Ta Li \*qabcdef\*q 165.El 166.Pp 167Note that when 168.Dv str 169has at least six 170.No non- Ns Tn NUL 171bytes, 172.Dv rec Ns Li "->name" 173is 174.Em not 175.Tn NUL Ns -terminated 176\(em it is only 177.Em padded 178with (possibly zero) 179.Tn NUL 180bytes to fill the fixed-width buffer. 181When 182.Dv str 183has 184.Em more 185than six 186.No non- Ns Tn NUL 187bytes, the additional ones are truncated. 188If 189.Dv str 190has space for 191.Em fewer 192than six bytes, and the last one is not 193.Tn NUL , 194using 195.Fn strncpy 196is undefined. 197.Pp 198Because 199.Fn strncpy 200does 201.Em not 202guarantee to 203.Tn NUL Ns -terminate 204the result, if 205.Tn NUL Ns -termination 206is required it must be done explicitly: 207.Bd -literal -offset indent 208char buf[1024]; 209 210strncpy(buf, input, sizeof(buf) - 1); 211buf[sizeof(buf) - 1] = '\e0'; 212.Ed 213.Pp 214If 215.Va input 216is guaranteed to be 217.Tn NUL Ns -terminated , 218and if 219.Va buf 220need only be 221.Tn NUL Ns -terminated , 222not fully initialized with 223.Tn NUL 224padding, 225this could be achieved using 226.Xr strlcpy 3 227as follows: 228.Bd -literal -offset indent 229strlcpy(buf, input, sizeof(buf)); 230.Ed 231.Pp 232It is not enough for 233.Va input 234to have 235.Li sizeof(buf) 236bytes allocated; it MUST be 237.Tn NUL Ns -terminated 238for 239.Xr strlcpy 3 240to be used. 241.Pp 242Note that because 243.Xr strlcpy 3 244is not defined in any standards, it should 245only be used when portability is not a concern. 246.Pp 247.Sy WARNING : 248Because 249.Xr strlcpy 3 250does not fully initialize 251.Fa dst , 252but does read all the way to a 253.Tn NUL 254terminator in 255.Fa src 256even past 257.Fa len 258bytes, 259.Xr strlcpy 3 260is 261.Em not 262a safe 263.Tn NUL Ns -terminating 264replacement for 265.Fn strncpy . 266Naively replacing 267.Fn strncpy 268by 269.Xr strlcpy 3 270can lead to crashes, undefined behaviour, and disclosure of secrets 271from uninitialized memory. 272.Sh SEE ALSO 273.Xr bcopy 3 , 274.Xr memccpy 3 , 275.Xr memcpy 3 , 276.Xr memmove 3 , 277.Xr strcpy 3 , 278.Xr strlcpy 3 , 279.Xr wcscpy 3 280.Sh STANDARDS 281The 282.Fn strncpy 283function conforms to 284.St -isoC-99 . 285.Pp 286The 287.Fn stpncpy 288function conforms to 289.St -p1003.1-2008 . 290.Sh HISTORY 291The 292.Fn stpncpy 293function first appeared in 294.Nx 6.0 . 295.Sh SECURITY CONSIDERATIONS 296The 297.Fn stpncpy 298and 299.Fn strncpy 300functions are not guaranteed to 301.Tn NUL Ns -terminate 302the result. 303