Module Name: src
Committed By: riastradh
Date: Fri Aug 11 15:36:17 UTC 2023
Modified Files:
src/lib/libc/string: strcpy.3 strlcpy.3 strncpy.3
Log Message:
strcpy(3), strlcpy(3), strncpy(3): Use `.Tn NUL' for the zero byte.
Let's be consistent within these man pages. (If someone else really
likes the unpronounceable `.Ql \e0' better, that's fine, you can go
through and systematically change all the man pages to use that after
we're done clarifying strcpy(3), strncpy(3), and strlcpy(3).)
To generate a diff of this commit:
cvs rdiff -u -r1.24 -r1.25 src/lib/libc/string/strcpy.3
cvs rdiff -u -r1.15 -r1.16 src/lib/libc/string/strlcpy.3
cvs rdiff -u -r1.5 -r1.6 src/lib/libc/string/strncpy.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/string/strcpy.3
diff -u src/lib/libc/string/strcpy.3:1.24 src/lib/libc/string/strcpy.3:1.25
--- src/lib/libc/string/strcpy.3:1.24 Fri Aug 11 09:39:39 2023
+++ src/lib/libc/string/strcpy.3 Fri Aug 11 15:36:17 2023
@@ -30,7 +30,7 @@
.\" SUCH DAMAGE.
.\"
.\" from: @(#)strcpy.3 8.1 (Berkeley) 6/4/93
-.\" $NetBSD: strcpy.3,v 1.24 2023/08/11 09:39:39 riastradh Exp $
+.\" $NetBSD: strcpy.3,v 1.25 2023/08/11 15:36:17 riastradh Exp $
.\"
.Dd August 11, 2023
.Dt STRCPY 3
@@ -58,7 +58,7 @@ copy the string
to
.Fa dst ,
including the terminating
-.Ql \e0
+.Tn NUL
character.
.Pp
The strings
@@ -69,7 +69,7 @@ may not overlap.
The string
.Fa src
must be terminated by a
-.Ql \e0
+.Tn NUL
character.
The memory for
.Fa dst
@@ -85,7 +85,7 @@ function returns
The
.Fn stpcpy
function returns a pointer to the terminating
-.Ql \e0
+.Tn NUL
character of
.Fa dst .
.Sh SEE ALSO
@@ -117,11 +117,11 @@ The
and
.Fn stpcpy
functions copy until a
-.Ql \e0
+.Tn NUL
terminator without any bounds checks on the size of the input or output
buffers.
If the input buffer is missing a
-.Ql \e0
+.Tn NUL
terminator, or the input string is longer than the output buffer, this
can lead to crashes or security vulnerabilities from buffer overruns,
including disclosure of secrets in memory and arbitrary code
Index: src/lib/libc/string/strlcpy.3
diff -u src/lib/libc/string/strlcpy.3:1.15 src/lib/libc/string/strlcpy.3:1.16
--- src/lib/libc/string/strlcpy.3:1.15 Fri Aug 11 08:15:30 2023
+++ src/lib/libc/string/strlcpy.3 Fri Aug 11 15:36:17 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: strlcpy.3,v 1.15 2023/08/11 08:15:30 riastradh Exp $
+.\" $NetBSD: strlcpy.3,v 1.16 2023/08/11 15:36:17 riastradh Exp $
.\" from OpenBSD: strlcpy.3,v 1.11 2000/11/16 23:27:41 angelos Exp
.\"
.\" Copyright (c) 1998, 2000 Todd C. Miller <[email protected]>
@@ -46,27 +46,36 @@ The
.Fn strlcpy
and
.Fn strlcat
-functions copy and concatenate NUL-terminated strings respectively.
+functions copy and concatenate
+.Tn NUL Ns -terminated
+strings respectively.
.Pp
The
.Fn strlcpy
function copies up to
.Fa size
-- 1 characters from the NUL-terminated string
+- 1 characters from the
+.Tn NUL Ns -terminated
+string
.Fa src
to
.Fa dst ,
-NUL-terminating the result.
+.Tn NUL Ns -terminating
+the result.
.Pp
The
.Fn strlcat
-function appends the NUL-terminated string
+function appends the
+.Tn NUL Ns -terminated
+string
.Fa src
to the end of
.Fa dst .
It will append at most
.Fa size
-- strlen(dst) - 1 bytes, NUL-terminating the result.
+- strlen(dst) - 1 bytes,
+.Tn NUL -terminating
+the result.
.Ss Relation to Xr strncpy 3 and Xr strncat 3
Unlike
.Xr strncpy 3
@@ -76,13 +85,16 @@ and
and
.Fn strlcat
are guaranteed to
-NUL-terminate the result (as long as
+.Tn NUL Ns -terminate
+the result (as long as
.Fa size
is larger than 0 or, in the case of
.Fn strlcat ,
as long as there is at least one byte free in
.Fa dst ) .
-Note that you should include a byte for the NUL in
+Note that you should include a byte for the
+.Tn NUL
+in
.Fa size .
.Pp
.Sy WARNING :
@@ -113,16 +125,22 @@ strings.
This means that for
.Fn strlcpy
.Fa src
-must be NUL-terminated and for
+must be
+.Tn NUL Ns -terminated
+and for
.Fn strlcat
both
.Fa src
and
.Fa dst
-must be NUL-terminated.
+must be
+.Tn NUL Ns -terminated .
Applications handling fixed-width fields with
.Pq possibly empty
-NUL padding, instead of NUL-terminated C strings, MUST use
+.Tn NUL
+padding, instead of
+.Tn NUL Ns -terminated
+C strings, MUST use
.Xr strncpy 3
and
.Xr strncat 3
@@ -157,11 +175,13 @@ Note however, that if
.Fn strlcat
traverses
.Fa size
-characters without finding a NUL, the length of the string is considered
-to be
+characters without finding a
+.Tn NUL ,
+the length of the string is considered to be
.Fa size
-and the destination string will not be NUL-terminated (since there was
-no space for the NUL).
+and the destination string will not be
+.Tn NUL Ns -terminated
+.Pq since there was no space for the Tn NUL .
This keeps
.Fn strlcat
from running off the end of a string.
Index: src/lib/libc/string/strncpy.3
diff -u src/lib/libc/string/strncpy.3:1.5 src/lib/libc/string/strncpy.3:1.6
--- src/lib/libc/string/strncpy.3:1.5 Fri Aug 11 13:18:24 2023
+++ src/lib/libc/string/strncpy.3 Fri Aug 11 15:36:17 2023
@@ -30,7 +30,7 @@
.\" SUCH DAMAGE.
.\"
.\" from: @(#)strcpy.3 8.1 (Berkeley) 6/4/93
-.\" $NetBSD: strncpy.3,v 1.5 2023/08/11 13:18:24 uwe Exp $
+.\" $NetBSD: strncpy.3,v 1.6 2023/08/11 15:36:17 riastradh Exp $
.\"
.Dd August 11, 2023
.Dt STRNCPY 3
@@ -54,7 +54,7 @@ and
.Fn strncpy
functions copy at most
.Fa len
-.No non- Ns Ql \e0
+.No non- Ns Tn NUL
characters from
.Fa src
into
@@ -64,18 +64,18 @@ If
is less than
.Fa len
characters long before the first
-.Ql \e0
+.Tn NUL
character, the remainder of
.Fa dst
is filled with
-.Ql \e0
+.Tn NUL
characters.
Otherwise,
.Fa dst
is
.Em not
terminated with a
-.Ql \e0
+.Tn NUL
character.
.Pp
The strings
@@ -92,7 +92,7 @@ function returns
The
.Fn stpncpy
function returns a pointer to the terminating
-.Ql \e0
+.Tn NUL
character of
.Fa dst .
If
@@ -100,7 +100,7 @@ If
does not terminate
.Fa dst
with a
-.Ql \e0
+.Tn NUL
character, it instead returns a pointer to
.Sm off
.Fa dst Li "[" Fa len Li "]" ,
