From owner-svn-src-all@freebsd.org Wed Jun 6 20:09:22 2018 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id ADD8BFE1740; Wed, 6 Jun 2018 20:09:22 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 5F9A0857DD; Wed, 6 Jun 2018 20:09:22 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 3B6347A36; Wed, 6 Jun 2018 20:09:22 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w56K9MKv011865; Wed, 6 Jun 2018 20:09:22 GMT (envelope-from cem@FreeBSD.org) Received: (from cem@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w56K9MtH011864; Wed, 6 Jun 2018 20:09:22 GMT (envelope-from cem@FreeBSD.org) Message-Id: <201806062009.w56K9MtH011864@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: cem set sender to cem@FreeBSD.org using -f From: Conrad Meyer Date: Wed, 6 Jun 2018 20:09:22 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r334733 - head/lib/libc/string X-SVN-Group: head X-SVN-Commit-Author: cem X-SVN-Commit-Paths: head/lib/libc/string X-SVN-Commit-Revision: 334733 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 06 Jun 2018 20:09:22 -0000 Author: cem Date: Wed Jun 6 20:09:21 2018 New Revision: 334733 URL: https://svnweb.freebsd.org/changeset/base/334733 Log: strcpy.3: Improve legibility and clarity In the DESCRIPTION, put the more commonly used functions first in the corresponding sentence, to help catch the eye. Pull out the note about overlapping buffers to its own paragraph, as it applies to all routines documented by this page. Emphasize the potentially surprising strncpy(3) behavior of zero-filling the remainder of a buffer larger than the source string. Encourage strlcpy use; remove portability note about strlcpy(3). Adapting a strlcpy-using code base to a platform that does not provide strlcpy in libc is so trivial as to not be worth mentioning. (Just copy strlcpy.c out of any BSD libc, or include and link the pre-packaged libbsd library on non-BSD platforms.) Likewise, expand the page's warning about ease of potential misuse to cover all functions documented herein, and explicitly suggest using strlcpy most of the time. The text was mostly cribbed from a similar suggestion in gets(3). Finally, document the remaining valid use of strncpy -- the rare fixed-length record with no expectation of nul-termination. Sponsored by: Dell EMC Isilon Modified: head/lib/libc/string/strcpy.3 Modified: head/lib/libc/string/strcpy.3 ============================================================================== --- head/lib/libc/string/strcpy.3 Wed Jun 6 20:03:35 2018 (r334732) +++ head/lib/libc/string/strcpy.3 Wed Jun 6 20:09:21 2018 (r334733) @@ -32,7 +32,7 @@ .\" @(#)strcpy.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd February 28, 2009 +.Dd June 6, 2018 .Dt STRCPY 3 .Os .Sh NAME @@ -55,9 +55,9 @@ .Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len" .Sh DESCRIPTION The -.Fn stpcpy -and .Fn strcpy +and +.Fn stpcpy functions copy the string .Fa src @@ -66,22 +66,18 @@ to (including the terminating .Ql \e0 character.) -If -.Fa src -and -.Fa dst -overlap, the results are undefined. .Pp The -.Fn stpncpy -and .Fn strncpy +and +.Fn stpncpy functions copy at most .Fa len characters from .Fa src into .Fa dst . +.Bf Sy If .Fa src is less than @@ -92,16 +88,25 @@ the remainder of is filled with .Ql \e0 characters. +.Ef Otherwise, .Fa dst is .Em not terminated. -If +.Pp +For all of +.Fn strcpy , +.Fn strncpy , +.Fn stpcpy , +and +.Fn stpncpy , +the result is undefined +if .Fa src and .Fa dst -overlap, the results are undefined. +overlap. .Sh RETURN VALUES The .Fn strcpy @@ -182,11 +187,6 @@ This could be better achieved using as shown in the following example: .Pp .Dl "(void)strlcpy(buf, input, sizeof(buf));" -.Pp -Note that because -.Xr strlcpy 3 -is not defined in any standards, it should -only be used when portability is not a concern. .Sh SEE ALSO .Xr bcopy 3 , .Xr memccpy 3 , @@ -218,8 +218,16 @@ and was added in .Fx 8.0 . .Sh SECURITY CONSIDERATIONS -The -.Fn strcpy -function is easily misused in a manner which enables malicious users -to arbitrarily change a running program's functionality through a -buffer overflow attack. +All of the functions documented in this manual page are easily misused in a +manner which enables malicious users to arbitrarily change a running program's +functionality through a buffer overflow attack. +.Pp +It is strongly suggested that the +.Fn strlcpy +function be used in almost all cases. +.Pp +For some, but not all, fixed-length records, non-terminated strings may be both +valid and desirable. +In that specific case, the +.Fn strncpy +function may be most sensible.