Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Alex,

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?

I think the proposed patch is okay. Do you want to send me
a final version?

> 
> Also I don't know if we should encourage one of them.  STAILQ seems to
> be more complete.  What would you do about it?

Not knowing, I would say: let's say nothing for now.

Thanks,

Michael


> [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),
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/