diff --git a/share/man/Makefile b/share/man/Makefile index 8e8c272eae74..7ce9e417896b 100644 --- a/share/man/Makefile +++ b/share/man/Makefile @@ -1,7 +1,7 @@ # @(#)Makefile 8.2 (Berkeley) 4/16/94 # XXX MISSING: man3f -SUBDIR= man1 man3 man4 man5 man7 man8 +SUBDIR= man1 man3 man4 man5 man7 man8 man9 makedb: makewhatis ${DESTDIR}${BINDIR}/man diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile new file mode 100644 index 000000000000..972a9a0606bd --- /dev/null +++ b/share/man/man9/Makefile @@ -0,0 +1,5 @@ +# @(#)Makefile 8.1 (Berkeley) 6/5/93 + +MAN8= intro.9 + +.include diff --git a/share/man/man9/intro.9 b/share/man/man9/intro.9 new file mode 100644 index 000000000000..02e42dc5b5a0 --- /dev/null +++ b/share/man/man9/intro.9 @@ -0,0 +1,116 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)intro.8 8.2 (Berkeley) 12/11/93 +.\" +.Dd December 13, 1995 +.Dt INTRO 9 +.Os FreeBSD 2.2 +.Sh NAME +.Nm intro +.Nd "introduction to system kernel interfaces" +.Sh DESCRIPTION +This section contains information about the interfaces and +subroutines in the kernel. + +.Sh PROTOTYPES ANSI-C AND ALL THAT +Yes please. + +We would like all code to be fully prototyped. + +If your code compiles cleanly with +.Nm cc +.Ar -Wall +we would feel happy about it. +It is important to understand that this isn't a question of just shutting up +.Nm cc , +it is a question about avoiding the things it complains about. +To put it bluntly, don't hide the problem by casting and other +obfuscating practices, solve the problem. + +.Sh INDENTATION AND STYLE +Belive it or not, there actually exists a guide for indentation and style. +It isn't generally applied though. + +We would appreciate if people would pay attention to it, and at least not +violate it blatantly. + +We don't mind it too badly if you have your own style, but please make +sure we can read it too. + +In particular there are some iron-clad requirements: +.Bl -enum -compact +.It +TAB stops is 8. +.It +All funtion names start in col 1. +.El + +.Sh NAMING THINGS +Some general rules exist: +.Bl -enum +.It +If a function is meant as a debugging aid in DDB, it should be enclosed +in +.Bd -literal -offset indent +#ifdef DDB + +#endif /* DDB */ +.Ed + +And the name of the procedure shoule start with the prefix +.Li DDB_ +to clearly identify the procedure as a debugger routine. +.El + + +.Sh SCOPE OF SYMBOLS +It is important to carefully consider the scope of symbols in the kernel. +The default is to make everything static, unless some reason requires +the opposite. + +There are several reasons for this policy, +the main one is that the kernel is one monolithic name-space, +and polution is not a good idea here either. + +For device drivers and other modules that don't add new internal interfaces +to the kernel, the entire source should be in one file it possible. +That way all symbols can be made static. + +If for some reason a module is split over multiple source files, then try +to split the module along some major fault-line and consider using the +number of global symbols as your guide. +The fewer the better. + +.Sh HISTORY +The +.Nm intro +section manual page appeared in FreeBSD 2.2