FreeBSD Developers' Handbook The FreeBSD Documentation Project Copyright © 2000, 2001, 2002, 2003, 2004 The FreeBSD Documentation Project Welcome to the Developers' Handbook. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the FreeBSD documentation project mailing list. The latest version of this document is always available from the FreeBSD World Wide Web server. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met: Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) 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. Important: THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "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 FREEBSD DOCUMENTATION PROJECT 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 DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. FreeBSD is a registered trademark of the FreeBSD Foundation. Apple, FireWire, Mac, Macintosh, Mac OS, Quicktime, and TrueType are trademarks of Apple Computer, Inc., registered in the United States and other countries. IBM, AIX, EtherJet, Netfinity, OS/2, PowerPC, PS/2, S/390, and ThinkPad are trademarks of International Business Machines Corporation in the United States, other countries, or both. IEEE, POSIX, and 802 are registered trademarks of Institute of Electrical and Electronics Engineers, Inc. in the United States. Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium, and Xeon are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Linux is a registered trademark of Linus Torvalds. Microsoft, IntelliMouse, MS-DOS, Outlook, Windows, Windows Media and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Motif, OSF/1, and UNIX are registered trademarks and IT DialTone and The Open Group are trademarks of The Open Group in the United States and other countries. Sun, Sun Microsystems, Java, Java Virtual Machine, JavaServer Pages, JDK, JSP, JVM, Netra, Solaris, StarOffice, Sun Blade, Sun Enterprise, Sun Fire, SunOS, and Ultra are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the ``™'' or the ``®'' symbol. Table of Contents I. Basics 1 Introduction 1.1 Developing on FreeBSD 1.2 The BSD Vision 1.3 Architectural Guidelines 1.4 The Layout of /usr/src 2 Programming Tools 2.1 Synopsis 2.2 Introduction 2.3 Introduction to Programming 2.4 Compiling with cc 2.5 Make 2.6 Debugging 2.7 Using Emacs as a Development Environment 2.8 Further Reading 3 Secure Programming 3.1 Synopsis 3.2 Secure Design Methodology 3.3 Buffer Overflows 3.4 SetUID issues 3.5 Limiting your program's environment 3.6 Trust 3.7 Race Conditions 4 Localization and Internationalization - L10N and I18N 4.1 Programming I18N Compliant Applications 5 Source Tree Guidelines and Policies 5.1 MAINTAINER on Makefiles 5.2 Contributed Software 5.3 Encumbered Files 5.4 Shared Libraries 6 Regression and Performance Testing 6.1. Micro Benchmark Checklist II. Interprocess Communication 7 * Signals 8 Sockets 8.1 Synopsis 8.2 Networking and Diversity 8.3 Protocols 8.4 The Sockets Model 8.5 Essential Socket Functions 8.6 Helper Functions 8.7 Concurrent Servers 9 IPv6 Internals 9.1 IPv6/IPsec Implementation III. Kernel 10 DMA 10.1 DMA: What it is and How it Works 11 Kernel Debugging 11.1 Obtaining a Kernel Crash Dump 11.2 Debugging a Kernel Crash Dump with kgdb 11.3 Debugging a Crash Dump with DDD 11.4 Post-Mortem Analysis of a Dump 11.5 On-Line Kernel Debugging Using DDB 11.6 On-Line Kernel Debugging Using Remote GDB 11.7 Debugging Loadable Modules Using GDB 11.8 Debugging a Console Driver 12 * UFS 13 * AFS 14 * Syscons 15 * Compatibility Layers 15.1 * Linux IV. Architectures 16 x86 Assembly Language Programming 16.1 Synopsis 16.2 The Tools 16.3 System Calls 16.4 Return Values 16.5 Creating Portable Code 16.6 Our First Program 16.7 Writing UNIX® Filters 16.8 Buffered Input and Output 16.9 Command Line Arguments 16.10 UNIX Environment 16.11 Working with Files 16.12 One-Pointed Mind 16.13 Using the FPU 16.14 Caveats 16.15 Acknowledgements 17 * Alpha V. Appendices Bibliography Index List of Examples 2-1. A sample .emacs file