Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

On 2/10/21 4:11 PM, Alejandro Colomar (man-pages) wrote:
> [ CC += glibc ]
> 
> On 2/10/21 4:06 PM, Alejandro Colomar (man-pages) wrote:
>> Hi Michael,
>>
>> When I refactored queue.3, I found out that there was no documentation
>> for SIMPLEQ.  I didn't do anything about it because I've never used it
>> and didn't understand what it was, and more importantly why.
>>
>> Now I found out that it only exists because of historical reasons [1],
>> but it is identical to STAILQ (minus a missing SIMPLEQ equivalent for
>> STAILQ_CONCAT()).  So I'd add links simpleq.3, SIMPLEQ_*.3 -> STAILQ.3,
>> and add a paragraph to queue.7 and another one to stailq.3.
>>
>> What do you think about the following?
>>
>> Also I don't know if we should encourage one of them.  STAILQ seems to
>> be more complete.  What would you do about it?
> 
> BTW, a suggestion for glibc:  glibc could simplify the code with things like
> 
> #define SIMPLEQ_ENTRY(type) STAILQ(type)
s/STAILQ/&_ENTRY/
> 
> It would make it more obvious that they're the same thing.
> 
>>
>> Thanks,
>>
>> Alex
>>
>> [1]: <https://gitlab.freedesktop.org/libbsd/libbsd/-/issues/5>
>>
>> ---
>>
>> $ git diff
>> diff --git a/man7/queue.7 b/man7/queue.7
>> index f92887a36..c3facafd0 100644
>> --- a/man7/queue.7
>> +++ b/man7/queue.7
>> @@ -138,6 +138,15 @@ Not in POSIX.1, POSIX.1-2001, or POSIX.1-2008.
>>  Present on the BSDs.
>>  .I <sys/queue.h>
>>  macros first appeared in 4.4BSD.
>> +.SH NOTES
>> +Some BSDs provide SIMPLEQ instead of STAILQ.
>> +The interfaces are identical, but for historical reasons
>> +they were named differently on different BSDs.
>> +STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD.
>> +For compatibility, glibc provides both sets of macros.
>>  .SH SEE ALSO
>>  .BR circleq (3),
>>  .BR insque (3),
>>
> 
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/