projects / apple / xnu.git / blame
| Commit | Line | Data |
|---|---|---|
| 55e303ae A |
1 | .\" Copyright (c) 1983, 1991, 1993 |
| 2 | .\" The Regents of the University of California. All rights reserved. | |
| 3 | .\" | |
| 4 | .\" Redistribution and use in source and binary forms, with or without | |
| 5 | .\" modification, are permitted provided that the following conditions | |
| 6 | .\" are met: | |
| 7 | .\" 1. Redistributions of source code must retain the above copyright | |
| 8 | .\" notice, this list of conditions and the following disclaimer. | |
| 9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
| 10 | .\" notice, this list of conditions and the following disclaimer in the | |
| 11 | .\" documentation and/or other materials provided with the distribution. | |
| 12 | .\" 3. All advertising materials mentioning features or use of this software | |
| 13 | .\" must display the following acknowledgement: | |
| 14 | .\" This product includes software developed by the University of | |
| 15 | .\" California, Berkeley and its contributors. | |
| 16 | .\" 4. Neither the name of the University nor the names of its contributors | |
| 17 | .\" may be used to endorse or promote products derived from this software | |
| 18 | .\" without specific prior written permission. | |
| 19 | .\" | |
| 20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
| 21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
| 22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
| 23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
| 24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
| 25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
| 26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
| 27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
| 28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
| 29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
| 30 | .\" SUCH DAMAGE. | |
| 31 | .\" | |
| 32 | .\" $FreeBSD: src/share/man/man9/intro.9,v 1.15 2001/07/14 19:41:16 schweikh Exp $ | |
| 33 | .\" | |
| 34 | .Dd December 13, 1995 | |
| 35 | .Dt INTRO 9 | |
| 36 | .Os | |
| 37 | .Sh NAME | |
| 38 | .Nm intro | |
| 39 | .Nd "introduction to system kernel interfaces" | |
| 40 | .Sh DESCRIPTION | |
| 41 | This section contains information about the interfaces and | |
| 42 | subroutines in the kernel. | |
| 43 | .Sh PROTOTYPES ANSI-C AND ALL THAT | |
| 44 | Yes please. | |
| 45 | .Pp | |
| 46 | We would like all code to be fully prototyped. | |
| 47 | .Pp | |
| 48 | If your code compiles cleanly with | |
| 49 | .Nm cc | |
| 50 | .Ar -Wall | |
| 51 | we would feel happy about it. | |
| 52 | It is important to understand that this isn't a question of just shutting up | |
| 53 | .Nm cc , | |
| 54 | it is a question about avoiding the things it complains about. | |
| 55 | To put it bluntly, don't hide the problem by casting and other | |
| 56 | obfuscating practices, solve the problem. | |
| 57 | .Sh INDENTATION AND STYLE | |
| 58 | Believe it or not, there actually exists a guide for indentation and style. | |
| 59 | It isn't generally applied though. | |
| 60 | .Pp | |
| 61 | We would appreciate if people would pay attention to it, and at least not | |
| 62 | violate it blatantly. | |
| 63 | .Pp | |
| 64 | We don't mind it too badly if you have your own style, but please make | |
| 65 | sure we can read it too. | |
| 66 | .Pp | |
| 67 | Please take time to read | |
| 68 | .Xr style 9 | |
| 69 | for more information. | |
| 70 | .Sh NAMING THINGS | |
| 71 | Some general rules exist: | |
| 72 | .Bl -enum | |
| 73 | .It | |
| 74 | If a function is meant as a debugging aid in DDB, it should be enclosed | |
| 75 | in | |
| 76 | .Bd -literal -offset indent | |
| 77 | #ifdef DDB | |
| 78 | ||
| 79 | #endif /* DDB */ | |
| 80 | .Ed | |
| 81 | .Pp | |
| 82 | And the name of the procedure should start with the prefix | |
| 83 | .Li DDB_ | |
| 84 | to clearly identify the procedure as a debugger routine. | |
| 85 | .El | |
| 86 | .Sh SCOPE OF SYMBOLS | |
| 87 | It is important to carefully consider the scope of symbols in the kernel. | |
| 88 | The default is to make everything static, unless some reason requires | |
| 89 | the opposite. | |
| 90 | .Pp | |
| 91 | There are several reasons for this policy, | |
| 92 | the main one is that the kernel is one monolithic name-space, | |
| 93 | and pollution is not a good idea here either. | |
| 94 | .Pp | |
| 95 | For device drivers and other modules that don't add new internal interfaces | |
| 96 | to the kernel, the entire source should be in one file if possible. | |
| 97 | That way all symbols can be made static. | |
| 98 | .Pp | |
| 99 | If for some reason a module is split over multiple source files, then try | |
| 100 | to split the module along some major fault-line and consider using the | |
| 101 | number of global symbols as your guide. | |
| 102 | The fewer the better. | |
| 103 | .Sh SEE ALSO | |
| 104 | .Xr style 9 | |
| 105 | .Sh HISTORY | |
| 106 | The | |
| 107 | .Nm | |
| 108 | section manual page appeared in | |
| 109 | .Fx 2.2 . |