Re: misleading note in https://man7.org/linux/man-pages/man3/bstring.3.html

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2748 bytes --]

Hi Sam,

On 1/10/23 09:17, Sam James wrote:
> 
> 
>> On 30 Dec 2022, at 23:05, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>>
>> Hello Aaron Peter,
>>
>> On 12/30/22 23:43, Aaron Peter Bachmann wrote:
>>> Hello!
>>> The note section in https://man7.org/linux/man-pages/man3/bstring.3.html says:
>>> The functions*bcmp*(),*bcopy*(), and*bzero*() are obsolete.  Use
>>>         *memcmp*(),*memcpy*(), and*memset*() instead.
>>> The std-replacement replacement for bcopy() in NOT memcpy() but memmove().
>>> Thus it should say:
>>> The functions*bcmp*(),*bcopy*(), and*bzero*() are obsolete.  Use
>>>         *memcmp*(),*memmove*(), and*memset*() instead.
>>
>> Thanks!  I fixed it.  And while doing it, I also removed the text that said bzero(3) is deprecated.  I encourage its use.
>>
> 
> The man page notes it was in POSIX and then got removed in 2008. Before it was removed from POSIX,
> they said memset was preferred.
> 
> I don't argue that we have to defer to POSIX always, but I'm wondering what your thinking is on such conflicts
> (I'm just wondering about other cases if we hit them).
> 
> What do you think?

I'd say that it's a case-by-case thing.  I wouldn't count it as a precedent, and 
discuss any new case that arises.  I remember I had some other cases of 
functions that have been deprecated by POSIX that I didn't mark as such, because 
the APIs themselves are fine.  For example, utime(2) is such a case.  POSIX 
deprecated it in favor of utimensat(2), but if you only care about seconds, it 
doesn't make much sense to go to the complexity of that call.

Of course, I'll mention in their pages, in STANDARDS, that POSIX or ISO 
deprecates them, but in SYNOPSIS I'll take some freedom as long as the API is 
not marked as [[deprecated]] in the glibc source code.

A kind of rule for using [[deprecated]] in the SYNOPSIS (but it's not a rule):

-  Syscalls are domain of the kernel.  If the kernel deprecates a syscall, it 
gets the attribute in the SYNOPSIS.

-  libc functions get the attribute in the SYNOPSIS in the following cases:

    -  gcc and/or glibc remove the function or deprecate it formally (warn about 
uses).

    -  Even if the function is not deprecated formally, if it has no sane use 
cases (opinionated call; I'll try to get some consensus on this), it might get 
it (fscanf(3) is a good candidate; so far I moved it to a small page separate 
from sscanf(3), and recommended against its use, but didn't deprecate it).

Even if the SYNOPSIS don't mark it as deprecated, it might be deprecated by 
POSIX or ISO, in which case that will be noted in STANDARDS.

Cheers,

Alex

> 
> Best,
> sam

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]