From owner-svn-src-head@FreeBSD.ORG Sat Apr 21 06:09:10 2012 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id B956F1065670; Sat, 21 Apr 2012 06:09:10 +0000 (UTC) (envelope-from das@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 8C9FF8FC0A; Sat, 21 Apr 2012 06:09:10 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q3L69AcR074458; Sat, 21 Apr 2012 06:09:10 GMT (envelope-from das@svn.freebsd.org) Received: (from das@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q3L69AsN074456; Sat, 21 Apr 2012 06:09:10 GMT (envelope-from das@svn.freebsd.org) Message-Id: <201204210609.q3L69AsN074456@svn.freebsd.org> From: David Schultz Date: Sat, 21 Apr 2012 06:09:10 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r234530 - head/lib/libc/stdio X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 21 Apr 2012 06:09:10 -0000 Author: das Date: Sat Apr 21 06:09:09 2012 New Revision: 234530 URL: http://svn.freebsd.org/changeset/base/234530 Log: - Fix the claim that the output is always null-terminated. This isn't true if the size is zero. - Fix a claim that sprintf() is the same as snprintf() with an infinite size. It's equivalent to snprintf() with a size of INT_MAX + 1. - Document the return values in the return values section. - Document the possible errno value of EOVERFLOW. MFC after: 2 weeks Modified: head/lib/libc/stdio/printf.3 Modified: head/lib/libc/stdio/printf.3 ============================================================================== --- head/lib/libc/stdio/printf.3 Sat Apr 21 06:08:29 2012 (r234529) +++ head/lib/libc/stdio/printf.3 Sat Apr 21 06:09:09 2012 (r234530) @@ -113,20 +113,6 @@ string that specifies how subsequent arg .Xr stdarg 3 ) are converted for output. .Pp -These functions return the number of characters printed -(not including the trailing -.Ql \e0 -used to end output to strings) or a negative value if an output error occurs, -except for -.Fn snprintf -and -.Fn vsnprintf , -which return the number of characters that would have been printed if the -.Fa size -were unlimited -(again, not including the final -.Ql \e0 ) . -.Pp The .Fn asprintf and @@ -164,15 +150,19 @@ if the return value is greater than or e .Fa size argument, the string was too short and some of the printed characters were discarded. -The output is always null-terminated. +The output is always null-terminated, unless +.Fa size +is 0. .Pp The .Fn sprintf and .Fn vsprintf functions -effectively assume an infinite -.Fa size . +effectively assume a +.Fa size +of +.Dv INT_MAX + 1. .Pp The format string is composed of zero or more directives: ordinary @@ -670,6 +660,21 @@ In no case does a non-existent or small a numeric field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. +.Sh RETURN VALUES +These functions return the number of characters printed +(not including the trailing +.Ql \e0 +used to end output to strings), +except for +.Fn snprintf +and +.Fn vsnprintf , +which return the number of characters that would have been printed if the +.Fa size +were unlimited +(again, not including the final +.Ql \e0 ) . +These functions return a negative value if an error occurs. .Sh EXAMPLES To print a date and time in the form .Dq Li "Sunday, July 3, 10:02" , @@ -771,6 +776,13 @@ family of functions may fail if: An invalid wide character code was encountered. .It Bq Er ENOMEM Insufficient storage space is available. +.It Bq Er EOVERFLOW +The +.Fa size +argument exceeds +.Dv INT_MAX + 1 , +or the return value would be too large to be represented by an +.Vt int . .El .Sh SEE ALSO .Xr printf 1 ,