Date: Thu, 13 Aug 2015 14:46:47 +1000 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Marcelo Araujo <araujo@freebsd.org> Cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r286715 - head/lib/libc/string Message-ID: <20150813134548.U1375@besplex.bde.org> In-Reply-To: <201508130231.t7D2VOhc069855@repo.freebsd.org> References: <201508130231.t7D2VOhc069855@repo.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 13 Aug 2015, Marcelo Araujo wrote: > Author: araujo > Date: Thu Aug 13 02:31:23 2015 > New Revision: 286715 > URL: https://svnweb.freebsd.org/changeset/base/286715 > > Log: > Remove the mention of memcpy(3) that is build on top of bcopy(3). > Fix some phrases to make it more clear. > > Differential Revision: D3378 > Reported by: bde@ > Reviewed by: wblock > Approved by: bapt, rodrigc (mentor) > Sponsored by: gandi.net I don't like this version either :-). > Modified: head/lib/libc/string/bcopy.3 > ============================================================================== > --- head/lib/libc/string/bcopy.3 Thu Aug 13 01:04:26 2015 (r286714) > +++ head/lib/libc/string/bcopy.3 Thu Aug 13 02:31:23 2015 (r286715) > @@ -31,7 +31,7 @@ > .\" @(#)bcopy.3 8.1 (Berkeley) 6/4/93 > .\" $FreeBSD$ > .\" > -.Dd August 11, 2015 > +.Dd August 13, 2015 > .Dt BCOPY 3 > .Os > .Sh NAME > @@ -58,16 +58,14 @@ If > .Fa len > is zero, no bytes are copied. > .Pp > -This function is deprecated (marked as LEGACY in > -POSIX.1-2001): use > -.Xr memcpy 3 > -or > +This function is obsolete (marked as LEGACY in > +POSIX.1-2001): please use This function is not obsolete, but is fully supported in FreeBSD. Its obsoletely doesn't follow at all from the clause in parentheses. LEGACY doesn't even mean obsolencent. In computerspeak it means "old stuff that we don't like". I think you got the "obsolete" wording from NetBSD. But I think NetBSD started deprecating it in 1995. It might really be obsolete for them after 20 years of deprecation. Please don't use pleasant nonsenses like "please" in man pages or comments. > .Xr memmove 3 > in new programs. Still not quite right. New programs should use the best function and that is usually memcpy(). Only old programs that are being roto-tilled should convert bcopy() to memmove() (so as to avoid having to understand them well enough to know if they do overlapped copies). > -Note that the first two arguments are > -interchanged for > -.Xr memcpy 3 > -and > +Note that > +.Fn bcopy > +takes its src and dst arguments in the opposite > +order from > .Xr memmove 3 . OK, except Xr should be Fn. ".Xr memmove 3" is a man page, not a function. Man pages don't take src and dst arguments :-). This normally shows up in the rendering -- in text mode, Fn gives highlighting but Xr doesn't. Now I notice more markup problems: the src and dst arguments are not marked up. In text mode, Fa gives highlighting for args. > POSIX.1-2008 removes the specification of > .Fn bcopy . Better put this before the LEGACY statement and maybe merge the LEGACY statement into the HISTORY section. Since I don't want to deprecate bcopy(), I would put this in the history section too. Technically, this function is not deprecated since it is still a standard BSD function in <strings.h>. The ifdef for this is already quite complicated and broken, thoough it only attempts to keep up with some of the POSIX churn: from strings.h: #if __BSD_VISIBLE || __POSIX_VISIBLE <= 200112 int bcmp(const void *, const void *, size_t) __pure; /* LEGACY */ void bcopy(const void *, void *, size_t); /* LEGACY */ void bzero(void *, size_t); /* LEGACY */ #endif It is POSIX LEGACY, but standard BSD. The POSIX ifdef is quite broken: - before 1996, POSIX didn't have this function, but it also didn't have strings.h so there is no problem (the ifdef is vacuously correct) - between 1996 and 2001, there was an XSI version there may have been a POSIX version that had this function and <strings.h> too. The ifdef is wrong for any such version since it doesn't mention XSI. Such versions are just unsupported. - between 2001 and 2008, POSIX apparently required bcopy() (and the other functions) but didn't declare them anywhere, except in the XSI case it requires them to be declared in <strings.h>. The above supports the non-XSI case of this. The XSI case is broken as in any 1996-2001 versions. - the ifdef is not up to date with changing LEGACY to OBSOLETE, but since LEGACY already resulted in omission of the prototypes in the non-XSI case, nothing needed to be changed in this case, and since the XSI case is unsupported nothing need to be changed to turn off the prototypes for XSI either. Correct code here wouldn't have the POSIX ifdef or LEGACY comments, but might having a comment saying that XSI is intentionally unsupported. XSI messes elswhere are supported, and I am suprised that not supporting it here doesn't cause problems. Ifdefs for historical mistakes would cause much larger messes if they were complete. Just near here, there is the mess of the <string.h> and <strings.h>. 1980's source code had messy ifdefs in applications for this. C90 didn't exactly help by standardizing the SYSVish <string.h>. POSIX.1-2001 actively harmed by restoring the BSDish <strings.h>. FreeBSD handles this problem by including <strings.h> in <string.h> if __BSD_VISIBLE and not documenting the details in man pages. <strings.h> contains mostly BSD functions, and man pages including bcopy(3) say to include <strings.h>, but most applications only include <string.h>, which was where bcopy() was in 4.4.BSD-Lite, and where it still is by the #include hack, but not where it is according to the man page. The ifdefs here seem to be just messy enough to detect the error of using the wrong include in the !__BSD_VISIBLE case. Bruce
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20150813134548.U1375>