From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23251 invoked by alias); 23 May 2009 20:09:19 -0000 Received: (qmail 23234 invoked by uid 22791); 23 May 2009 20:09:19 -0000 X-SWARE-Spam-Status: No, hits=-2.4 required=5.0 tests=AWL,BAYES_00,SPF_PASS X-Spam-Check-By: sourceware.org Received: from ey-out-1920.google.com (HELO ey-out-1920.google.com) (74.125.78.146) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sat, 23 May 2009 20:09:12 +0000 Received: by ey-out-1920.google.com with SMTP id 13so469975eye.24 for ; Sat, 23 May 2009 13:09:08 -0700 (PDT) Received: by 10.210.66.1 with SMTP id o1mr892857eba.56.1243109348817; Sat, 23 May 2009 13:09:08 -0700 (PDT) Received: from ?192.168.2.99? (cpc2-cmbg8-0-0-cust61.cmbg.cable.ntl.com [82.6.108.62]) by mx.google.com with ESMTPS id 24sm7051758eyx.43.2009.05.23.13.09.07 (version=SSLv3 cipher=RC4-MD5); Sat, 23 May 2009 13:09:08 -0700 (PDT) Message-ID: <4A185A9D.8090500@gmail.com> Date: Sat, 23 May 2009 20:09:00 -0000 From: Dave Korn User-Agent: Thunderbird 2.0.0.17 (Windows/20080914) MIME-Version: 1.0 To: Eli Zaretskii CC: Dave Korn , gcc-patches@gcc.gnu.org, gdb-patches@sourceware.org Subject: Re: [RFA] Fix documentation of snprintf and vsnprintf References: <83d4a0szry.fsf@gnu.org> <4A180840.3040004@gmail.com> <837i07u4k7.fsf@gnu.org> In-Reply-To: <837i07u4k7.fsf@gnu.org> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2009-05/txt/msg00521.txt.bz2 Eli Zaretskii wrote: >> Date: Sat, 23 May 2009 15:29:20 +0100 >> From: Dave Korn >> CC: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org >> >> I think it's still a little bit unclear: >> >>> +This function is similar to @code{sprintf}, but it will write at most >>> +var{n} bytes (including the terminating null byte) to @var{buf}. >> It could still be perceived as ambiguous. That sentence says that the >> terminating null byte is included in the count of >> "the-most-bytes-it-will-write", but it doesn't explicitly say that it won't be >> truncated off like the rest of the characters if the output is too long. > > I thought it did say that, as > > "write at most N bytes (including the terminating null byte)" > > means that it will write no more than N bytes, and those N bytes > include the null byte. Yes, the text can be taken to mean this as well, and that is clearly the intended meaning once you know, but it's about how this sentence says the NUL terminating byte should be *counted* the same as all the rest, it might seem to imply that it is *treated* the same as all the rest - and it's not, it's treated differently. > However, I don't mind the text you suggest if people think it says the > same more clearly: > >> How about >> >>> +This function is similar to @code{sprintf}, but it will write at most >>> +var{n} bytes (truncating the output if necessary, so that there is >>> +always guaranteed to be a terminating null byte) to @var{buf}. > > Or maybe we should make it clearer still: > > This function is similar to @code{sprintf}, but it will write to > @var{buf} at most @code{var{n}-1} bytes of text, followed by a > terminating null byte, for the total of @var{n} bytes. > > WDYT? That WFM just fine too :) cheers, DaveK