Module Name: src
Committed By: riastradh
Date: Fri Aug 11 08:15:30 UTC 2023
Modified Files:
src/lib/libc/string: strlcpy.3
Log Message:
strlcpy(3): Rework man page to clarify relation to strncpy(3).
Add caveats explaining when strlcpy(3) and strlcat(3) are dangerously
inadequate or inappropriate.
XXX pullup-10
XXX pullup-9
XXX pullup-8
To generate a diff of this commit:
cvs rdiff -u -r1.14 -r1.15 src/lib/libc/string/strlcpy.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/strlcpy.3
diff -u src/lib/libc/string/strlcpy.3:1.14 src/lib/libc/string/strlcpy.3:1.15
--- src/lib/libc/string/strlcpy.3:1.14 Sun Aug 28 10:48:16 2022
+++ src/lib/libc/string/strlcpy.3 Fri Aug 11 08:15:30 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: strlcpy.3,v 1.14 2022/08/28 10:48:16 hgutch Exp $
+.\" $NetBSD: strlcpy.3,v 1.15 2023/08/11 08:15:30 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]>
@@ -26,7 +26,7 @@
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd March 1, 2001
+.Dd August 11, 2023
.Dt STRLCPY 3
.Os
.Sh NAME
@@ -46,17 +46,36 @@ The
.Fn strlcpy
and
.Fn strlcat
-functions copy and concatenate strings respectively.
-They are designed
-to be safer, more consistent, and less error prone replacements for
+functions copy and concatenate NUL-terminated strings respectively.
+.Pp
+The
+.Fn strlcpy
+function copies up to
+.Fa size
+- 1 characters from the NUL-terminated string
+.Fa src
+to
+.Fa dst ,
+NUL-terminating the result.
+.Pp
+The
+.Fn strlcat
+function appends the NUL-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.
+.Ss Relation to Xr strncpy 3 and Xr strncat 3
+Unlike
.Xr strncpy 3
and
-.Xr strncat 3 .
-Unlike those functions,
+.Xr strncat 3 ,
.Fn strlcpy
and
.Fn strlcat
-take the full size of the buffer (not just the length) and guarantee to
+are guaranteed to
NUL-terminate the result (as long as
.Fa size
is larger than 0 or, in the case of
@@ -65,7 +84,26 @@ as long as there is at least one byte fr
.Fa dst ) .
Note that you should include a byte for the NUL in
.Fa size .
-Also note that
+.Pp
+.Sy WARNING :
+Also unlike
+.Xr strncpy 3
+and
+.Xr strncat 3 ,
+.Fn strlcpy
+and
+.Fn strlcat
+are not guaranteed to initialize all
+.Fa size
+bytes of
+.Fa dst
+\(em bytes past
+.Fa dst Ns Li "[" Fn strlen src Li "+ 1" Ns Li "]"
+are left uninitialized.
+This can lead to security vulnerabilities such as leaking secrets from
+uninitialized stack or heap buffers.
+.Pp
+.Sy WARNING :
.Fn strlcpy
and
.Fn strlcat
@@ -82,26 +120,19 @@ both
and
.Fa dst
must be NUL-terminated.
-.Pp
-The
+Applications handling fixed-width fields with
+.Pq possibly empty
+NUL padding, instead of NUL-terminated C strings, MUST use
+.Xr strncpy 3
+and
+.Xr strncat 3
+instead.
+Attempting to use
.Fn strlcpy
-function copies up to
-.Fa size
-- 1 characters from the NUL-terminated string
-.Fa src
-to
-.Fa dst ,
-NUL-terminating the result.
-.Pp
-The
+or
.Fn strlcat
-function appends the NUL-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.
+for these cases can lead to crashes or security vulnerabilities from
+buffer overruns.
.Sh RETURN VALUES
The
.Fn strlcpy
