Date: Tue, 19 May 2015 22:34:11 +1000 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Julian Elischer <julian@freebsd.org> Cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r283105 - head/share/man/man9 Message-ID: <20150519214041.J3472@besplex.bde.org> In-Reply-To: <201505191133.t4JBX54w093912@svn.freebsd.org> References: <201505191133.t4JBX54w093912@svn.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20150519214041.J3472>