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 <todd.mil...@courtesan.com> @@ -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