linux-kernel - Re: [PATCH v2] close_range.2: new page documenting close

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 10 Dec 2020 09:21:33 +0100
From:   Stephen Kitt <steve@....org>
To:     "Alejandro Colomar (man-pages)" <alx.manpages@...il.com>
Cc:     linux-man@...r.kernel.org,
        Michael Kerrisk <mtk.manpages@...il.com>,
        Christian Brauner <christian.brauner@...ntu.com>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2] close_range.2: new page documenting close_range(2)

Hi Alejandro,

On Thu, 10 Dec 2020 01:24:28 +0100, "Alejandro Colomar (man-pages)"
<alx.manpages@...il.com> wrote:
> A few more comments below.

Thanks for all the detailed reviews! (Same goes to everyone reviewing this
yesterday, thanks for helping turn my not-so-great attempt into something
really useful.)

> Michael, please have a look at them too.
> 
> Christian, do you have any program that you used to test the syscall
> that could be added as an example program to the page?

I have some example code that I could turn into an example program, but I
imagine Christian has better code than me ;-).

> > +.BI "int close_range(unsigned int " first ", unsigned int " last ",
> > unsigned int " flags );  
> 
> This line overflows an 80-col terminal.  Fix:
> 
> .BI "int close_range(unsigned int " first ", unsigned int " last ,
> .BI "                unsigned int " flags );

Noted, thanks.

> > +.fi  
> 
> Please, add a note here that there is no wrapper for this syscall,
> as in other syscalls without wrapper (see membarrier(2) as an example).
> That way it's easier to grep, if all pages have the same notice.

Ah, right, I used pidfd_open(2) as an example, where it's mentioned later.

> Please use semantic newlines.
> See man-pages(7)::STYLE GUIDE::Use semantic newlines

Noted, thanks.

> > +.SH NOTES
> > +Currently, there is no glibc wrapper for this system call; call it using
> > +.BR syscall (2).  
> 
> I can see that this notice is also present on a few pages,
> but the one in membarrier(2) is more extended.
> 
> Please, copy the notices from membarrier(2).
> There's one in SYNOPSIS, and one in NOTES.

Will do!

> > +.SH USE CASES  
> 
> This section is unconventional.  Please move that text to one of the
> traditional sections.  I think DESCRIPTION would be the best place for this.
> 
> For a list of the traditional sections,
> see man-pages(7)::DESCRIPTION::Sections within a manual page

Indeed; it grew out of pidfd_open's "Use cases" section but making all this
part of the description would be much better.

I'll wait and see if there are other comments, and send a v3 addressing all
the above.

Regards,

Stephen

Content of type "application/pgp-signature" skipped