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  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:	Mon, 16 Jun 2014 06:12:03 +0200
From:	"Michael Kerrisk (man-pages)" <>
To:	John Stultz <>
CC:, David Herrmann <>,
	lkml <>,
	Ryan Lortie <>,
	Linus Torvalds <>,
	Andrew Morton <>,
	"" <>,
	"" <>,
	Linux API <>,
	Greg Kroah-Hartman <>,
	Lennart Poettering <>,
	Daniel Mack <>, Kay Sievers <>,
	Hugh Dickins <>,
	Tony Battersby <>,
	Andy Lutomirski <>
Subject: Re: [PATCH v3 3/7] shm: add memfd_create() syscall

On 06/13/2014 06:20 PM, John Stultz wrote:
> On Fri, Jun 13, 2014 at 7:20 AM, Michael Kerrisk (man-pages)
> <> wrote:
>> The general notion these days is that a (comprehensive) manual page
>> _should_ come *with* the system call, rather than after the fact. And
>> there's a lot of value in that. I've found no end of bugs and design
>> errors while writing (comprehensive) man pages after the fact (by
>> which time it's too late to fix the design errors), and also found
>> quite a few of those issues when I've managed to work with folk at the
>> same time as they write the syscall. Bottom line: you really should
>> write formal documentation now, as part of the process of code
>> submission. It improves the chance of finding implementation and
>> design bugs, and may well widen your circle of reviewers.
> I very much agree here. One practical issue I've noticed is that
> having separate targets for both the code changes and the manpages can
> be an extra barrier for folks getting changes correctly documented as
> the change is being submitted. Reviewers may say "be sure to send
> updates to the man pages" but its not always easy to remember to
> follow up and make sure the submitter got the changes (which match the
> merged patches) to you as well.
> I've been thinking it might be nice to have the kernel syscall man
> pages included in the kernel source tree, then have them
> copied/imported over to the man-pages project (similar to how glibc
> imports uapi kernel headers).  They could even be kept in the
> include/uapi directory, and checkpatch could ensure that changes that
> touch include/uapi also have modifications to something in the
> manpages directory. This way folks would be able to include the man
> page change with the code change, making it easier for developers to
> do the right thing, making it easier for reviewers to ensure its
> correct, and making it easier for maintainers to ensure man page
> documentation is properly in sync.
> Or is this something that has been hashed over already? I do admit
> this would disrupt your process a bit.

It's more a less a FAQ from my point of view, so I wrote this:

In short, I agree that the current process is not optimal, but lacking
(a lot) more time, it'd be hard to make any change to the current 
process. In any case, I think there's room for a lot of improvement
even without changing the current process. (For example, while I 
agree that having man pages in a separate location from the kernel 
source does create some barriers, I don't think it's the reason
most developers don't update the man pages. One just has to
look at the patchy state Documentation/filesystems/proc.txt as one 
example to support that view point.)



Michael Kerrisk
Linux man-pages maintainer;
Linux/UNIX System Programming Training:
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to
More majordomo info at
Please read the FAQ at

Powered by blists - more mailing lists