svn commit: r286651 - head/lib/libc/string

[Marcelo Araujo]

Hello bde@

Maybe change it as it is in NetBSD would be better:
http://netbsd.gw.com/cgi-bin/man-cgi?bcopy+3+NetBSD-current

They still mention about memcpy(3). However, I need to check their
implementation.

What do you think?

2015-08-12 11:51 GMT+08:00 Bruce Evans <brde at optusnet.com.au>:

> On Wed, 12 Aug 2015, Marcelo Araujo wrote:
>
> Log:
>>  Describe that bcopy(3) is deprecated and marked as LEGACY in
>>  POSIX.1-2001 and removed from the specification in POSIX.1-2008.
>>
>
> Only new and old POSIX software and all Standard C software.  Standard
> C never had bcopy().  POSIX didn't have it until API bloat restored
> many old mistakes.  But BSD has it.  It is memmove(9undoc) that is
> deprecated (but brought back by KPI bloat) in the kernel in FreeBSD,
> but this is about userland.  Only portability requires preferring
> mememove(3).
>
>  New softwares shall use memcpy(3) or memmove(3).
>>
>
> Bad advice.  bcopy() is only similar to memmove().
>
> Modified:
>>  head/lib/libc/string/bcopy.3
>>
>> Modified: head/lib/libc/string/bcopy.3
>>
>> ==============================================================================
>> --- head/lib/libc/string/bcopy.3        Tue Aug 11 22:43:28 2015
>> (r286650)
>> +++ head/lib/libc/string/bcopy.3        Wed Aug 12 00:49:20 2015
>> (r286651)
>> @@ -31,7 +31,7 @@
>> .\"     @(#)bcopy.3     8.1 (Berkeley) 6/4/93
>> .\" $FreeBSD$
>> .\"
>> -.Dd June 4, 1993
>> +.Dd August 11, 2015
>> .Dt BCOPY 3
>> .Os
>> .Sh NAME
>> @@ -57,6 +57,20 @@ The two strings may overlap.
>>
>
> The strings must not overlap for memcpy().
>
> 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
>> +.Xr memmove 3
>> +in new programs.
>>
>
> Bad advice, since these functions are not similar, and it doesn't follow
> from deprecation all the versions of POSIX that have it that it is
> deprecated in FreeBSD.  It follows from the nonexistence of the function
> in POSIX before 2001 and after 2008 that the function is more than
> deprecated.
>
> +Note that the first two arguments are
>> +interchanged for
>> +.Xr memcpy 3
>> +and
>> +.Xr memmove 3 .
>>
>
> The first 2 args are not interchanged for memcpy() and memmove().  They
> are only interchanged for bcopy() and memmove().
>
>
> +POSIX.1-2008 removes the specification of
>> +.Fn bcopy .
>> .Sh SEE ALSO
>> .Xr memccpy 3 ,
>> .Xr memcpy 3 ,
>>
>
> Removing all mention of memcpy() (except the one in the Xr) would fix half
> of the bugs.
>
> POSIX has much better wording for this, as for most things.  From a 2001
> draft:
>
> X 5112 APPLICATION USAGE
> X 5113            memmove( ) is preferred over this function.
>
> When bcopy() was only deprecated, it was un-preferred but not banned.
>
>
> X 5114            The following are approximately equivalent (note the
> order of the arguments):
> X 5115            bcopy(s1,s2,n)  = memmove(s2,s1,n)
> X 5116            For maximum portability, it is recommended to replace
> the function call to bcopy( ) as follows:
> X 5117            #define bcopy(b1,b2,len) (memmove((b2), (b1), (len)),
> (void) 0)
>
> No mention of memcpy(), but an example of how to translate with so much
> attention to details that it is hard to read.  It even translates the
> return type.
>
> X X 5118 RATIONALE
> X 5119            None.
> X X 5120 FUTURE DIRECTIONS
> X 5121            This function may be withdrawn in a future version.
>
> It was apparently withdrawn in 2008.
>
> X X 5122 SEE ALSO
> X 5123            memmove( ), the Base Definitions volume of IEEE Std
> 1003.1-200x, <strings.h>
>
> No mention of memcpy() here either.  I don't like long lists of Xr's to
> vaguely related man pages, with no hint of the exact relation, in FreeBSD
> man pages.  A reader wishing to know any relation at all would have to
> read all the man pages in the long list to see some relation, and
> understand
> all their details to see the exact relation.
>
> X X 5124 CHANGE HISTORY
> X 5125            First released in Issue 4, Version 2.
> X X 5126 Issue 5
> X 5127            Moved from X/OPEN UNIX extension to BASE.
> X X 5128 Issue 6
> X 5129            This function is marked LEGACY.
>
> So bcopy() was apparently XSI in Issue 4, BASE in Issue 5, and
> BASE plus LEGACY in Issue 6.  So why is it still XSI in 2001?
> I don't know the dates of the Issues.  Oops, this is because only
> the <strings.h> include with the prototype for bcopy() is XSI in
> 2001.  It doesn't exist in POSIX.1-1996.
>
> Bruce
>



-- 

-- 
Marcelo Araujo            (__)araujo at FreeBSD.org
\\\'',)http://www.FreeBSD.org <http://www.freebsd.org/>   \/  \ ^
Power To Server.         .\. /_)