[src/trunk]: src/lib/libc/stdio document vsnprintf_ss

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/2bf28ad74b2b
branches:  trunk
changeset: 759978:2bf28ad74b2b
user:      christos <christos%NetBSD.org@localhost>
date:      Wed Dec 22 16:59:10 2010 +0000

description:
document vsnprintf_ss

diffstat:

 lib/libc/stdio/Makefile.inc |   4 ++--
 lib/libc/stdio/printf.3     |  27 ++++++++++++++++++++-------
 2 files changed, 22 insertions(+), 9 deletions(-)

diffs (112 lines):

diff -r 053b2578c362 -r 2bf28ad74b2b lib/libc/stdio/Makefile.inc
--- a/lib/libc/stdio/Makefile.inc       Wed Dec 22 14:05:50 2010 +0000
+++ b/lib/libc/stdio/Makefile.inc       Wed Dec 22 16:59:10 2010 +0000
@@ -1,5 +1,5 @@
 #      from: @(#)Makefile.inc  5.7 (Berkeley) 6/27/91
-#      $NetBSD: Makefile.inc,v 1.39 2010/09/24 21:50:56 christos Exp $
+#      $NetBSD: Makefile.inc,v 1.40 2010/12/22 16:59:10 christos Exp $
 
 # stdio sources
 .PATH: ${.CURDIR}/stdio
@@ -52,7 +52,7 @@
 MLINKS+=printf.3 asprintf.3 printf.3 fprintf.3 printf.3 snprintf.3 \
        printf.3 sprintf.3 printf.3 vasprintf.3 printf.3 vfprintf.3 \
        printf.3 vprintf.3 printf.3 vsnprintf.3 printf.3 vsprintf.3 \
-       printf.3 dprintf.3 printf.3 vdprintf.3
+       printf.3 dprintf.3 printf.3 vdprintf.3 printf.3 vsnprintf_ss.3
 MLINKS+=putc.3 fputc.3 putc.3 putc_unlocked.3 putc.3 putchar.3 \
        putc.3 putchar_unlocked.3 putc.3 putw.3
 MLINKS+=scanf.3 fscanf.3 scanf.3 sscanf.3 scanf.3 vfscanf.3 scanf.3 vscanf.3 \
diff -r 053b2578c362 -r 2bf28ad74b2b lib/libc/stdio/printf.3
--- a/lib/libc/stdio/printf.3   Wed Dec 22 14:05:50 2010 +0000
+++ b/lib/libc/stdio/printf.3   Wed Dec 22 16:59:10 2010 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: printf.3,v 1.55 2010/12/16 17:42:27 wiz Exp $
+.\"    $NetBSD: printf.3,v 1.56 2010/12/22 16:59:10 christos Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -33,7 +33,7 @@
 .\"
 .\"     @(#)printf.3   8.1 (Berkeley) 6/4/93
 .\"
-.Dd August 28, 2010
+.Dd December 22, 2010
 .Dt PRINTF 3
 .Os
 .Sh NAME
@@ -48,6 +48,7 @@
 .Nm vsprintf ,
 .Nm vdprintf ,
 .Nm vsnprintf ,
+.Nm vsnprintf_ss ,
 .Nm vasprintf
 .Nd formatted output conversion
 .Sh LIBRARY
@@ -78,6 +79,8 @@
 .Ft int
 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
 .Ft int
+.Fn vsnprintf_ss "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
+.Ft int
 .Fn vasprintf "char ** restrict ret" "const char * restrict format" "va_list ap"
 .Sh DESCRIPTION
 The
@@ -106,8 +109,9 @@
 .Fn sprintf ,
 .Fn snprintf ,
 .Fn vsprintf ,
+.Fn vsnprintf ,
 and
-.Fn vsnprintf
+.Fn vsnprintf_ss
 write to the character string
 .Fa str ;
 and
@@ -124,6 +128,9 @@
 .Xr stdarg 3 )
 are converted for output.
 .Pp
+.Fn vsnprintf_ss
+is a signal-safe standalone version that does handle floating point formats.
+.Pp
 .Fn asprintf
 and
 .Fn vasprintf
@@ -148,9 +155,10 @@
 on error.
 It is more portable to check for a return value of \-1 instead.
 .Pp
-.Fn snprintf
+.Fn snprintf ,
+.Fn vsnprintf
 and
-.Fn vsnprintf
+.Fn vsnprintf_ss
 will write at most
 .Fa size Ns \-1
 of the characters printed into the output string
@@ -725,9 +733,10 @@
 These functions return
 the number of characters printed, or that would be printed if there
 was adequate space in case of
-.Fn snprintf
+.Fn snprintf ,
+.Fn vsnprintf ,
 and
-.Fn vsnprintf ,
+.Fn vsnprintf_ss
 (not including the trailing
 .Ql \e0
 used to end output to strings).
@@ -825,6 +834,10 @@
 and
 .Fn vasprintf
 are modeled on the ones that first appeared in the GNU C library.
+The function
+.Fn vsnprintf_ss
+is non standard and appeared in
+.Nx 4.0 .
 The functions
 .Fn dprintf
 and