From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm1-x341.google.com (mail-wm1-x341.google.com [IPv6:2a00:1450:4864:20::341]) by sourceware.org (Postfix) with ESMTPS id 76CEB3857802 for ; Sun, 25 Oct 2020 20:18:41 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 76CEB3857802 Received: by mail-wm1-x341.google.com with SMTP id d3so10560192wma.4 for ; Sun, 25 Oct 2020 13:18:41 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=JMuoar5laTe3QmTiG7e6tNeGHdVA3IsynAfX0MpwZCs=; b=KfkWt6S6m0Qphkn0Eb/N/X2FiagVy74GMaWYa9Y7XGB7Fw0ybREJoc5NBcJfEmMjsM N2H3Xwk1kT6UJUhwFxi8tqtixI2end0qwgwkJcuni9gUeWJqJ3M0KaXJlpXo4gP0gSfs mn39Qxg7vnJ56j3YKllXy1/Vg+xsuJbCplVfDRyavmdbfv/SI2qbSWkjQsOX/YWMC1za 8MjwayRtRpH9HMIKBVbmw/3B7OPPxCb6WHcqlosbzKaka3GFvo+c2C+jWPHsw81xFhFp TvybT0LnXXS3PXh/6cR/dtlQywGk9Xs3vROza+KUExw/L/L1T0MuUqAByQInKlJn4jjH k4ug== X-Gm-Message-State: AOAM532b02pk2JDMrJarH7xt8VzrbAajppXQ6eRLoekXr7zYpgstZy7e dzHcSb+zNSc7VU7Pr8yCUYrjRit/fsg= X-Google-Smtp-Source: ABdhPJyAT3LC0D5chhGxElhkV953Bh8vp116YpUJwjtjoMjatZKmycd8o/VQ+pA5Chg8IecU+6p8Ww== X-Received: by 2002:a7b:c305:: with SMTP id k5mr13263794wmj.102.1603657120240; Sun, 25 Oct 2020 13:18:40 -0700 (PDT) Received: from [192.168.1.143] ([170.253.60.68]) by smtp.gmail.com with ESMTPSA id q8sm18795414wro.32.2020.10.25.13.18.39 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 25 Oct 2020 13:18:39 -0700 (PDT) Subject: Re: [PATCH 2/2] queue.3: Fix & update after forking circleq.3, list.3, slist.3, stailq.3 & tailq.3 To: mtk.manpages@gmail.com Cc: linux-man , "libc-alpha@sourceware.org" References: <20201025102132.41223-1-colomar.6.4.3@gmail.com> <20201025102132.41223-2-colomar.6.4.3@gmail.com> From: Alejandro Colomar Message-ID: <9179f888-7c3d-4625-bb9c-5e17f12433ca@gmail.com> Date: Sun, 25 Oct 2020 21:18:38 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.12.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-11.4 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM, GIT_PATCH_0, KAM_NUMSUBJECT, NICE_REPLY_A, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 25 Oct 2020 20:18:43 -0000 On 2020-10-25 12:41, Michael Kerrisk (man-pages) wrote: > Hi Alex, > > On Sun, 25 Oct 2020 at 11:24, Alejandro Colomar wrote: >> >> - ffix: Use man markup >> - Remove specific notes about code size increase >> and execution time increase, >> as they were (at least) inaccurate. >> Instead, a generic note has been added. >> - Structure the text into subsections. >> - Remove sections that were empty after the forks. >> - Clearly relate macro names (SLIST, TAILQ, ...) >> to a human readable name of which data structure >> they implement. > > Good clean-up! Thanks! :-) Thanks, Alex > > Applied. > > Cheers, > > Michael > >> Reported-by: Michael Kerrisk >> Signed-off-by: Alejandro Colomar >> --- >> man3/queue.3 | 189 ++++++++++++++++++++------------------------------- >> 1 file changed, 75 insertions(+), 114 deletions(-) >> >> diff --git a/man3/queue.3 b/man3/queue.3 >> index 3931f8c96..c1b8a72a8 100644 >> --- a/man3/queue.3 >> +++ b/man3/queue.3 >> @@ -28,160 +28,121 @@ >> .\" SUCH DAMAGE. >> .\" %%%LICENSE_END >> .\" >> -.\" @(#)queue.3 8.2 (Berkeley) 1/24/94 >> -.\" $FreeBSD$ >> .\" >> -.Dd February 7, 2015 >> -.Dt QUEUE 3 >> -.Os >> -.Sh NAME >> -.Nd implementations of singly-linked lists, singly-linked tail queues, >> -lists, tail queues, and circular queues >> -.Sh SYNOPSIS >> -.Sh DESCRIPTION >> -These macros define and operate on five types of data structures: >> -singly-linked lists, singly-linked tail queues, lists, tail queues, and >> -circular queues. >> -All five structures support the following functionality: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.TH QUEUE 3 2015-02-7 "GNU" "Linux Programmer's Manual" >> +.SH NAME >> +queue \- implementations of linked lists and queues >> +.SH DESCRIPTION >> +The >> +.I >> +header file provides a set of macros that >> +define and operate on the following data structures: >> +.IP * 3 >> +singly-linked lists (SLIST) >> +.IP * >> +doubly-linked lists (LIST) >> +.IP * >> +singly-linked tail queues (STAILQ) >> +.IP * >> +doubly-linked tail queues (TAILQ) >> +.IP * >> +doubly-linked circular queues (CIRCLEQ) >> +.PP >> +All structures support the following functionality: >> +.IP * 3 >> Insertion of a new entry at the head of the list. >> -.It >> +.IP * >> Insertion of a new entry after any element in the list. >> -.It >> +.IP * >> O(1) removal of an entry from the head of the list. >> -.It >> +.IP * >> Forward traversal through the list. >> -.\" .It >> +.\".IP * >> .\" Swapping the contents of two lists. >> -.El >> -.Pp >> -Singly-linked lists are the simplest of the four data structures >> +.PP >> +Code size and execution time >> +depend on the complexity of the data structure being used, >> +so programmers should take care of choosing the appropriate one. >> +.SS Singly-linked lists (SLIST) >> +Singly-linked lists are the simplest >> and support only the above functionality. >> -Singly-linked lists are ideal for applications with large datasets >> -and few or no removals, >> +Singly-linked lists are ideal for applications with >> +large datasets and few or no removals, >> or for implementing a LIFO queue. >> Singly-linked lists add the following functionality: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> O(n) removal of any entry in the list. >> -.El >> -.Pp >> +.SS Singly-linked tail queues (STAILQ) >> Singly-linked tail queues add the following functionality: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> Entries can be added at the end of a list. >> -.It >> +.IP * >> O(n) removal of any entry in the list. >> -.It >> +.IP * >> They may be concatenated. >> -.El >> -.Pp >> +.PP >> However: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> All list insertions must specify the head of the list. >> -.It >> +.IP * >> Each head entry requires two pointers rather than one. >> -.It >> -Code size is about 15% greater and operations run about 20% slower >> -than singly-linked lists. >> -.El >> -.Pp >> -Singly-linked tail queues are ideal for applications with large datasets and >> -few or no removals, >> +.PP >> +Singly-linked tail queues are ideal for applications with >> +large datasets and few or no removals, >> or for implementing a FIFO queue. >> -.Pp >> +.SS Doubly-linked data structures >> All doubly linked types of data structures (lists and tail queues) >> additionally allow: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> Insertion of a new entry before any element in the list. >> -.It >> +.IP * >> O(1) removal of any entry in the list. >> -.El >> -.Pp >> +.PP >> However: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> Each element requires two pointers rather than one. >> -.It >> -Code size and execution time of operations (except for removal) is about >> -twice that of the singly-linked data-structures. >> -.El >> -.Pp >> +.SS Doubly-linked lists (LIST) >> Linked lists are the simplest of the doubly linked data structures. >> They add the following functionality over the above: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> They may be traversed backwards. >> -.El >> -.Pp >> +.PP >> However: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> To traverse backwards, an entry to begin the traversal and the list in >> which it is contained must be specified. >> -.El >> -.Pp >> +.SS Doubly-linked tail queues (TAILQ) >> Tail queues add the following functionality: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> Entries can be added at the end of a list. >> -.It >> +.IP * >> They may be traversed backwards, from tail to head. >> -.It >> +.IP * >> They may be concatenated. >> -.El >> -.Pp >> +.PP >> However: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> All list insertions and removals must specify the head of the list. >> -.It >> +.IP * >> Each head entry requires two pointers rather than one. >> -.It >> -Code size is about 15% greater and operations run about 20% slower >> -than singly-linked lists. >> -.El >> -.Pp >> +.SS Doubly-linked circular queues (CIRCLEQ) >> Circular queues add the following functionality over the above: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> The first and last entries are connected. >> -.El >> -.Pp >> +.PP >> However: >> -.Pp >> -.Bl -enum -compact -offset indent >> -.It >> +.IP * 3 >> The termination condition for traversal is more complex. >> -.It >> -Code size is about 40% greater and operations run about 45% slower than lists. >> -.El >> -.Sh EXAMPLES >> -.Sh CONFORMING TO >> +.SH CONFORMING TO >> Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008. >> Present on the BSDs. >> -.Nm queue >> -functions first appeared in >> -.Bx 4.4 . >> -.Sh SEE ALSO >> -.Xr circleq 3 >> -.Xr insque 3 >> -.Xr list 3 >> -.Xr slist 3 >> -.Xr stailq 3 >> -.Xr tailq 3 >> -.\" .Xr tree 3 >> +.I >> +macros first appeared in 4.4BSD. >> +.SH SEE ALSO >> +.BR circleq (3), >> +.BR insque (3), >> +.BR list (3), >> +.BR slist (3), >> +.BR stailq (3), >> +.BR tailq (3) >> +.\" .BR tree (3) >> -- >> 2.28.0 >> > >