From owner-svn-src-head@FreeBSD.ORG Tue May 19 12:34:16 2015 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id B7D4DEBF; Tue, 19 May 2015 12:34:16 +0000 (UTC) Received: from mail110.syd.optusnet.com.au (mail110.syd.optusnet.com.au [211.29.132.97]) by mx1.freebsd.org (Postfix) with ESMTP id 7E76A1391; Tue, 19 May 2015 12:34:16 +0000 (UTC) Received: from c211-30-166-197.carlnfd1.nsw.optusnet.com.au (c211-30-166-197.carlnfd1.nsw.optusnet.com.au [211.30.166.197]) by mail110.syd.optusnet.com.au (Postfix) with ESMTPS id 010A2781D23; Tue, 19 May 2015 22:34:12 +1000 (AEST) Date: Tue, 19 May 2015 22:34:11 +1000 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Julian Elischer cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r283105 - head/share/man/man9 In-Reply-To: <201505191133.t4JBX54w093912@svn.freebsd.org> Message-ID: <20150519214041.J3472@besplex.bde.org> References: <201505191133.t4JBX54w093912@svn.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.1 cv=L/MkHYj8 c=1 sm=1 tr=0 a=KA6XNC2GZCFrdESI5ZmdjQ==:117 a=PO7r1zJSAAAA:8 a=kj9zAlcOel0A:10 a=JzwRw_2MAAAA:8 a=1azgIOBnuRS1gDRdnzEA:9 a=CjuIK1q_8ugA:10 X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 19 May 2015 12:34:16 -0000 On Tue, 19 May 2015, Julian Elischer wrote: > Author: julian > > Log: > Only several years late, catch the psignal man page up to the > fact that psignal has been renamed to kern_psignal since 9.0. > > MFC after: 1 week It would be better to fix the function to match its documented name. Many other function names are similarly broken. For example, the primary function in getenv(9). There is not a single syscall named foo() misnamed as sys_foo() in any section 9 man page, but I think that is because there never was a single syscall named whose kernel part foo() is documented as foo(9) in any man page, so there was no documentation except the source code to break by renaming. There is even less than null documentation for the kern_foo() layer of syscalls named foo(). Null documentation would be empty. The actual documentation is ".Xr kern_openat 9" in devfs_set_cdevpriv.9. This reference is more broken than usual. As usual, the man page containing the pointer gives no hint on what might be relevant in the pointed-to man page. Here the pointed-to man page also doesn't exist. > Modified: > head/share/man/man9/psignal.9 > > Modified: head/share/man/man9/psignal.9 Now the name of this manpage is broken. It doesn't match the name of any function in it. > ============================================================================== > --- head/share/man/man9/psignal.9 Tue May 19 09:28:52 2015 (r283104) > +++ head/share/man/man9/psignal.9 Tue May 19 11:33:04 2015 (r283105) > @@ -33,6 +33,7 @@ > .Os > .Sh NAME > .Nm psignal , > +.Nm kern_psignal , > .Nm pgsignal , > .Nm gsignal , > .Nm tdsignal psignal() was misnamed because there is a section 3 psignal() and namespaces are handled badly somewhere. The other functions here don't conflict with application names and were not renamed. This gives an inconsistent namespace here. All the other functions have shorter names without an underscore. If the functions (in userland too) had modern uglier names with 'signal' (or better 'sig', but that wouldn't be verbose enough) as a prefix, then renaming would cause larger inconsistencies, but wouldn't be necessary since there would be no conflict because p would be spelled verbosely as 'process' in the kernel and 'print' in userland. More important functions like printf() and malloc() weren't renamed since the churn from than would be too painful. The kernel is compiled with -ffreestanding to handle namespaces correctly in it. This is the correct way of preventing the compiler knowing too much about printf() and turning it into functions that don't exist in the kernel. The kernel malloc() is even more incompatible. printf(9) has the worse name printk() in Minix and Linux. I liked to get away from that. This was technically needed in Minix before C90 standardized things, in particular freestanding environments. Without a standard, the compiler might rewrite any library function like printf(). gcc didn't implement special support for freestanding environments until much later when it started rewriting printf(). BSD ignored this portability problem and just used printf(9). Bruce