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
_______________________________________________
svn-src-head@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
