diff options
| author | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2021-04-01 18:54:26 +0000 |
|---|---|---|
| committer | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2021-04-01 18:54:26 +0000 |
| commit | 11cd6edd391a42845859da65cb804980dc59221d (patch) | |
| tree | 2bbd657febda2719da6ecc10ca6f84665c5d108e | |
| parent | cd5051bbedb0a91ba0235e325a15904111f8f670 (diff) | |
21 files changed, 593 insertions, 357 deletions
diff --git a/documentation/content/en/books/developers-handbook/_index.adoc b/documentation/content/en/books/developers-handbook/_index.adoc index 08a9490c92..3082156c0f 100644 --- a/documentation/content/en/books/developers-handbook/_index.adoc +++ b/documentation/content/en/books/developers-handbook/_index.adoc @@ -3,28 +3,20 @@ title: FreeBSD Developers' Handbook authors: - author: The FreeBSD Documentation Project copyright: 1995-2020 The FreeBSD Documentation Project -releaseinfo: "$FreeBSD$" -trademarks: ["freebsd", "apple", "ibm", "ieee", "intel", "linux", "microsoft", "opengroup", "sun", "general"] +releaseinfo: "$FreeBSD: head/en_US.ISO8859-1/books/developers-handbook/book.xml 54255 2020-06-15 08:13:08Z bcr $" +trademarks: ["freebsd", "apple", "ibm", "ieee", "intel", "linux", "microsoft", "opengroup", "sun", "general"] +next: books/developers-handbook/parti --- = FreeBSD Developers' Handbook :doctype: book :toc: macro -:toclevels: 2 +:toclevels: 1 :icons: font -:xrefstyle: basic -:relfileprefix: ../ -:outfilesuffix: :sectnums: :sectnumlevels: 6 -:partnums: -:chapter-signifier: Chapter -:part-signifier: Part :source-highlighter: rouge :experimental: -:skip-front-matter: -:book: true -:pdf: false ifeval::["{backend}" == "html5"] include::shared/mirrors.adoc[] @@ -33,8 +25,6 @@ include::shared/releases.adoc[] include::shared/en/mailing-lists.adoc[] include::shared/en/teams.adoc[] include::shared/en/urls.adoc[] -:imagesdir: ../../../../images/books/developers-handbook/ -:chapters-path: content/en/books/developers-handbook/ endif::[] ifeval::["{backend}" == "pdf"] @@ -44,8 +34,6 @@ include::../../../../shared/releases.adoc[] include::../../../../shared/en/mailing-lists.adoc[] include::../../../../shared/en/teams.adoc[] include::../../../../shared/en/urls.adoc[] -:imagesdir: ../../../static/images/books/developers-handbook/ -:chapters-path: endif::[] ifeval::["{backend}" == "epub3"] @@ -55,8 +43,6 @@ include::../../../../shared/releases.adoc[] include::../../../../shared/en/mailing-lists.adoc[] include::../../../../shared/en/teams.adoc[] include::../../../../shared/en/urls.adoc[] -:imagesdir: ../../../static/images/books/developers-handbook/ -:chapters-path: endif::[] [.abstract-title] @@ -69,41 +55,4 @@ The latest version of this document is always available from the link:https://ww ''' -toc::[] - -// Section one -[[basics]] -= Basics - -include::{chapters-path}introduction/chapter.adoc[leveloffset=+1, lines=10..24;35..-1] -include::{chapters-path}tools/chapter.adoc[leveloffset=+1, lines=10..26;37..-1] -include::{chapters-path}secure/chapter.adoc[leveloffset=+1, lines=9..23;34..-1] -include::{chapters-path}l10n/chapter.adoc[leveloffset=+1, lines=8..22;33..-1] -include::{chapters-path}policies/chapter.adoc[leveloffset=+1, lines=10..24;35..-1] -include::{chapters-path}testing/chapter.adoc[leveloffset=+1, lines=8..22;33..-1] - -// Section two -[[ipc]] -= Interprocess Communication - -include::{chapters-path}sockets/chapter.adoc[leveloffset=+1, lines=9..23;35..-1] -include::{chapters-path}ipv6/chapter.adoc[leveloffset=+1, lines=9..23;34..-1] - -// Section three -[[kernel]] -= Kernel - -include::{chapters-path}kernelbuild/chapter.adoc[leveloffset=+1, lines=8..22;33..-1] -include::{chapters-path}kerneldebug/chapter.adoc[leveloffset=+1, lines=11..25;36..-1] - -// Section four -[[architectures]] -= Architectures - -include::{chapters-path}x86/chapter.adoc[leveloffset=+1, lines=8..22;33..-1] - -// Appendices -[[appendices]] -= Appendices - -include::{chapters-path}bibliography/chapter.adoc[leveloffset=+1, lines=6..20;29..-1] +include::content/en/books/developers-handbook/toc.adoc[] diff --git a/documentation/content/en/books/developers-handbook/bibliography/chapter.adoc b/documentation/content/en/books/developers-handbook/bibliography/_index.adoc index fa861831c5..fa861831c5 100644 --- a/documentation/content/en/books/developers-handbook/bibliography/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/bibliography/_index.adoc diff --git a/documentation/content/en/books/developers-handbook/book.adoc b/documentation/content/en/books/developers-handbook/book.adoc new file mode 100644 index 0000000000..c59bda0a3d --- /dev/null +++ b/documentation/content/en/books/developers-handbook/book.adoc @@ -0,0 +1,99 @@ +--- +title: FreeBSD Developers' Handbook +authors: + - author: The FreeBSD Documentation Project +copyright: 1995-2020 The FreeBSD Documentation Project +releaseinfo: "$FreeBSD: head/en_US.ISO8859-1/books/developers-handbook/book.xml 54255 2020-06-15 08:13:08Z bcr $" +trademarks: ["freebsd", "apple", "ibm", "ieee", "intel", "linux", "microsoft", "opengroup", "sun", "general"] +--- + += FreeBSD Developers' Handbook +:doctype: book +:toc: macro +:toclevels: 2 +:icons: font +:xrefstyle: basic +:relfileprefix: ../ +:outfilesuffix: +:sectnums: +:sectnumlevels: 6 +:partnums: +:chapter-signifier: Chapter +:part-signifier: Part +:source-highlighter: rouge +:experimental: +:skip-front-matter: +:book: true +:pdf: false + +ifeval::["{backend}" == "html5"] +include::shared/mirrors.adoc[] +include::shared/authors.adoc[] +include::shared/releases.adoc[] +include::shared/en/mailing-lists.adoc[] +include::shared/en/teams.adoc[] +include::shared/en/urls.adoc[] +:imagesdir: ../../../../images/books/developers-handbook/ +:chapters-path: content/en/books/developers-handbook/ +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/mirrors.adoc[] +include::../../../../shared/authors.adoc[] +include::../../../../shared/releases.adoc[] +include::../../../../shared/en/mailing-lists.adoc[] +include::../../../../shared/en/teams.adoc[] +include::../../../../shared/en/urls.adoc[] +:imagesdir: ../../../static/images/books/developers-handbook/ +:chapters-path: +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/mirrors.adoc[] +include::../../../../shared/authors.adoc[] +include::../../../../shared/releases.adoc[] +include::../../../../shared/en/mailing-lists.adoc[] +include::../../../../shared/en/teams.adoc[] +include::../../../../shared/en/urls.adoc[] +:imagesdir: ../../../static/images/books/developers-handbook/ +:chapters-path: +endif::[] + +[.abstract-title] +[abstract] +Abstract + +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-doc}. + +The latest version of this document is always available from the link:https://www.FreeBSD.org[FreeBSD World Wide Web server]. It may also be downloaded in a variety of formats and compression options from the link:https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:{handbook}#mirrors-ftp/[mirror sites]. + +''' + +toc::[] + +// Section one +include::{chapters-path}parti.adoc[lines=7..8] +include::{chapters-path}introduction/_index.adoc[leveloffset=+1, lines=10..24;35..-1] +include::{chapters-path}tools/_index.adoc[leveloffset=+1, lines=10..26;37..-1] +include::{chapters-path}secure/_index.adoc[leveloffset=+1, lines=9..23;34..-1] +include::{chapters-path}l10n/_index.adoc[leveloffset=+1, lines=8..22;33..-1] +include::{chapters-path}policies/_index.adoc[leveloffset=+1, lines=10..24;35..-1] +include::{chapters-path}testing/_index.adoc[leveloffset=+1, lines=8..22;33..-1] + +// Section two +include::{chapters-path}partii.adoc[lines=7..8] +include::{chapters-path}sockets/_index.adoc[leveloffset=+1, lines=9..23;35..-1] +include::{chapters-path}ipv6/_index.adoc[leveloffset=+1, lines=9..23;34..-1] + +// Section three +include::{chapters-path}partiii.adoc[lines=7..8] +include::{chapters-path}kernelbuild/_index.adoc[leveloffset=+1, lines=8..22;33..-1] +include::{chapters-path}kerneldebug/_index.adoc[leveloffset=+1, lines=11..25;36..-1] + +// Section four +include::{chapters-path}partiv.adoc[lines=7..8] +include::{chapters-path}x86/_index.adoc[leveloffset=+1, lines=8..22;33..-1] + +// Appendices +include::{chapters-path}partv.adoc[lines=7..8] +include::{chapters-path}bibliography/_index.adoc[leveloffset=+1, lines=6..20;29..-1] diff --git a/documentation/content/en/books/developers-handbook/chapters-order.adoc b/documentation/content/en/books/developers-handbook/chapters-order.adoc index 90183764d6..ef978f645c 100644 --- a/documentation/content/en/books/developers-handbook/chapters-order.adoc +++ b/documentation/content/en/books/developers-handbook/chapters-order.adoc @@ -1,12 +1,17 @@ -introduction/chapter.adoc -tools/chapter.adoc -secure/chapter.adoc -l10n/chapter.adoc -policies/chapter.adoc -testing/chapter.adoc -sockets/chapter.adoc -ipv6/chapter.adoc -kernelbuild/chapter.adoc -kerneldebug/chapter.adoc -x86/chapter.adoc -bibliography/chapter.adoc +parti.adoc +introduction/_index.adoc +tools/_index.adoc +secure/_index.adoc +l10n/_index.adoc +policies/_index.adoc +testing/_index.adoc +partii.adoc +sockets/_index.adoc +ipv6/_index.adoc +partiii.adoc +kernelbuild/_index.adoc +kerneldebug/_index.adoc +partiv.adoc +x86/_index.adoc +partv.adoc +bibliography/_index.adoc diff --git a/documentation/content/en/books/developers-handbook/introduction/chapter.adoc b/documentation/content/en/books/developers-handbook/introduction/_index.adoc index 4aff6e3847..019f80f577 100644 --- a/documentation/content/en/books/developers-handbook/introduction/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/introduction/_index.adoc @@ -60,7 +60,7 @@ Our ideology can be described by the following guidelines From Scheifler & Gettys: "X Window System" [[introduction-layout]] -== The Layout of [.filename]#/usr/src# +== The Layout of /usr/src The complete source code to FreeBSD is available from our public repository. The source code is normally installed in [.filename]#/usr/src# which contains the following subdirectories: diff --git a/documentation/content/en/books/developers-handbook/ipv6/chapter.adoc b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc index 50379e6d09..1d86a91fe4 100644 --- a/documentation/content/en/books/developers-handbook/ipv6/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc @@ -164,7 +164,7 @@ Ordinary userland applications should use advanced API (RFC2292) to specify scop In the kernel, an interface index for link-local scoped address is embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address. For example, you may see something like: -[source,shell] +[source,bash] .... fe80:1::200:f8ff:fe01:6317 .... @@ -190,7 +190,7 @@ IPv6 link-local address is generated from IEEE802 address (Ethernet MAC address) Here is an output of netstat command: -[source,shell] +[source,bash] .... Internet6: Destination Gateway Flags Netif Expire @@ -221,7 +221,7 @@ Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers, or mu To summarize the sysctl knob: -[source,shell] +[source,bash] .... accept_rtadv forwarding role of the node --- --- --- @@ -288,7 +288,7 @@ and recompile the new kernel. Then you can test jumbo payloads by the man:ping6[8] command with -b and -s options. The -b option must be specified to enlarge the size of the socket buffer and the -s option specifies the length of the packet, which should be more than 65,535. For example, type as follows: -[source,shell] +[source,bash] .... % ping6 -b 70000 -s 68000 ::1 .... @@ -297,7 +297,7 @@ The IPv6 specification requires that the Jumbo Payload option must not be used i When an IPv6 packet is received, the frame length is checked and compared to the length specified in the payload length field of the IPv6 header or in the value of the Jumbo Payload option, if any. If the former is shorter than the latter, the packet is discarded and statistics are incremented. You can see the statistics as output of man:netstat[8] command with `-s -p ip6' option: -[source,shell] +[source,bash] .... % netstat -s -p ip6 ip6: @@ -345,7 +345,7 @@ To process IP6 header, extension headers and transport headers easily, network d `netstat -s -p ip6` tells you whether or not your driver conforms such requirement. In the following example, "cce0" violates the requirement. (For more information, refer to Section 2.) -[source,shell] +[source,bash] .... Mbuf statistics: 317 one mbuf @@ -374,7 +374,7 @@ You can perform wildcard bind on both of the address families, on the same port. The following table show the behavior of FreeBSD 4.x. -[source,shell] +[source,bash] .... listening side initiating side (AF_INET6 wildcard (connection to ::ffff:10.1.1.1) @@ -627,7 +627,7 @@ Note that the behavior is configurable in per-node manner, not per-SA manner (dr The behavior is summarized as follows (see source code for more detail): -[source,shell] +[source,bash] .... encapsulate decapsulate --- --- diff --git a/documentation/content/en/books/developers-handbook/kernelbuild/chapter.adoc b/documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc index 906ce32357..7322b4cab3 100644 --- a/documentation/content/en/books/developers-handbook/kernelbuild/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/kernelbuild/_index.adoc @@ -47,21 +47,21 @@ Building the kernel this way may be useful when working on the kernel code and i [.procedure] . Run man:config[8] to generate the kernel source code: + -[source,shell] +[source,bash] .... # /usr/sbin/config MYKERNEL .... . Change into the build directory. man:config[8] will print the name of this directory after being run as above. + -[source,shell] +[source,bash] .... # cd ../compile/MYKERNEL .... . Compile the kernel: + -[source,shell] +[source,bash] .... # make depend # make @@ -69,7 +69,7 @@ Building the kernel this way may be useful when working on the kernel code and i . Install the new kernel: + -[source,shell] +[source,bash] .... # make install .... diff --git a/documentation/content/en/books/developers-handbook/kerneldebug/chapter.adoc b/documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc index f0d83de480..930d941c3f 100644 --- a/documentation/content/en/books/developers-handbook/kerneldebug/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc @@ -73,7 +73,7 @@ Check [.filename]#/etc/fstab# or man:swapinfo[8] for a list of swap devices. ==== Make sure the `dumpdir` specified in man:rc.conf[5] exists before a kernel crash! -[source,shell] +[source,bash] .... # mkdir /var/crash # chmod 700 /var/crash @@ -96,7 +96,7 @@ The man:crashinfo[8] utility generates a text file containing a summary of infor If you are testing a new kernel but need to boot a different one in order to get your system up and running again, boot it only into single user mode using the `-s` flag at the boot prompt, and then perform the following steps: -[source,shell] +[source,bash] .... # fsck -p # mount -a -t ufs # make sure /var/crash is writable @@ -111,7 +111,7 @@ This instructs man:savecore[8] to extract a kernel dump from [.filename]#/dev/ad The kernel includes a man:sysctl[8] node that requests a kernel panic. This can be used to verify that your system is properly configured to save kernel crash dumps. You may wish to remount existing file systems as read-only in single user mode before triggering the crash to avoid data loss. -[source,shell] +[source,bash] .... # shutdown now ... @@ -134,21 +134,21 @@ This section covers man:kgdb[1]. The latest version is included in the package:d To enter into the debugger and begin getting information from the dump, start kgdb: -[source,shell] +[source,bash] .... # kgdb -n N .... Where _N_ is the suffix of the [.filename]#vmcore.N# to examine. To open the most recent dump use: -[source,shell] +[source,bash] .... # kgdb -n last .... Normally, man:kgdb[1] should be able to locate the kernel running at the time the dump was generated. If it is not able to locate the correct kernel, pass the pathname of the kernel and dump as two arguments to kgdb: -[source,shell] +[source,bash] .... # kgdb /boot/kernel/kernel /var/crash/vmcore.0 .... @@ -157,7 +157,7 @@ You can debug the crash dump using the kernel sources just like you can for any This dump is from a 5.2-BETA kernel and the crash comes from deep within the kernel. The output below has been modified to include line numbers on the left. This first trace inspects the instruction pointer and obtains a back trace. The address that is used on line 41 for the `list` command is the instruction pointer and can be found on line 17. Most developers will request having at least this information sent to them if you are unable to debug the problem yourself. If, however, you do solve the problem, make sure that your patch winds its way into the source tree via a problem report, mailing lists, or by being able to commit it! -[source,shell] +[source,bash] .... 1:# cd /usr/obj/usr/src/sys/KERNCONF 2:# kgdb kernel.debug /var/crash/vmcore.0 @@ -281,7 +281,7 @@ Once your DDB kernel is running, there are several ways to enter DDB. The first, The second scenario is to drop to the debugger once the system has booted. There are two simple ways to accomplish this. If you would like to break to the debugger from the command prompt, simply type the command: -[source,shell] +[source,bash] .... # sysctl debug.kdb.enter=1 .... @@ -301,7 +301,7 @@ to the kernel configuration file and rebuild/reinstall. The DDB commands roughly resemble some `gdb` commands. The first thing you probably need to do is to set a breakpoint: -[source,shell] +[source,bash] .... break function-name address .... @@ -310,14 +310,14 @@ Numbers are taken hexadecimal by default, but to make them distinct from symbol To exit the debugger and continue execution, type: -[source,shell] +[source,bash] .... continue .... To get a stack trace of the current thread, use: -[source,shell] +[source,bash] .... trace .... @@ -326,7 +326,7 @@ To get a stack trace of an arbitrary thread, specify a process ID or thread ID a If you want to remove a breakpoint, use -[source,shell] +[source,bash] .... del del address-expression @@ -334,28 +334,28 @@ If you want to remove a breakpoint, use The first form will be accepted immediately after a breakpoint hit, and deletes the current breakpoint. The second form can remove any breakpoint, but you need to specify the exact address; this can be obtained from: -[source,shell] +[source,bash] .... show b .... or: -[source,shell] +[source,bash] .... show break .... To single-step the kernel, try: -[source,shell] +[source,bash] .... s .... This will step into functions, but you can make DDB trace them until the matching return statement is reached by: -[source,shell] +[source,bash] .... n .... @@ -367,7 +367,7 @@ This is different from ``gdb``'s `next` statement; it is like ``gdb``'s `finish` To examine data from memory, use (for example): -[source,shell] +[source,bash] .... x/wx 0xf0133fe0,40 x/hd db_symtab_space @@ -377,14 +377,14 @@ To examine data from memory, use (for example): for word/halfword/byte access, and hexadecimal/decimal/character/ string display. The number after the comma is the object count. To display the next 0x10 items, simply use: -[source,shell] +[source,bash] .... x ,10 .... Similarly, use -[source,shell] +[source,bash] .... x/ia foofunc,10 .... @@ -393,7 +393,7 @@ to disassemble the first 0x10 instructions of `foofunc`, and display them along To modify memory, use the write command: -[source,shell] +[source,bash] .... w/b termbuf 0xa 0xb 0 w/w 0xf0010030 0 0 @@ -403,28 +403,28 @@ The command modifier (`b`/`h`/`w`) specifies the size of the data to be written, If you need to know the current registers, use: -[source,shell] +[source,bash] .... show reg .... Alternatively, you can display a single register value by e.g. -[source,shell] +[source,bash] .... p $eax .... and modify it by: -[source,shell] +[source,bash] .... set $eax new-value .... Should you need to call some kernel functions from DDB, simply say: -[source,shell] +[source,bash] .... call func(arg1, arg2, ...) .... @@ -433,28 +433,28 @@ The return value will be printed. For a man:ps[1] style summary of all running processes, use: -[source,shell] +[source,bash] .... ps .... Now you have examined why your kernel failed, and you wish to reboot. Remember that, depending on the severity of previous malfunctioning, not all parts of the kernel might still be working as expected. Perform one of the following actions to shut down and reboot your system: -[source,shell] +[source,bash] .... panic .... This will cause your kernel to dump core and reboot, so you can later analyze the core on a higher level with man:kgdb[1]. -[source,shell] +[source,bash] .... call boot(0) .... Might be a good way to cleanly shut down the running system, `sync()` all disks, and finally, in some cases, reboot. As long as the disk and filesystem interfaces of the kernel are not damaged, this could be a good way for an almost clean shutdown. -[source,shell] +[source,bash] .... reset .... @@ -463,7 +463,7 @@ This is the final way out of disaster and almost the same as hitting the Big Red If you need a short command summary, simply type: -[source,shell] +[source,bash] .... help .... @@ -479,7 +479,7 @@ GDB has already supported _remote debugging_ for a long time. This is done using You should configure the kernel in question with `config -g` if building the "traditional" way. If building the "new" way, make sure that `makeoptions DEBUG=-g` is in the configuration. In both cases, include `DDB` in the configuration, and compile it as usual. This gives a large binary, due to the debugging information. Copy this kernel to the target machine, strip the debugging symbols off with `strip -x`, and boot it using the `-d` boot option. Connect the serial line of the target machine that has "flags 080" set on its uart device to any serial line of the debugging host. See man:uart[4] for information on how to set the flags on an uart device. Now, on the debugging machine, go to the compile directory of the target kernel, and start `gdb`: -[source,shell] +[source,bash] .... % kgdb kernel GDB is free software and you are welcome to distribute copies of it @@ -492,14 +492,14 @@ Copyright 1996 Free Software Foundation, Inc... Initialize the remote debugging session (assuming the first serial port is being used) by: -[source,shell] +[source,bash] .... (kgdb) target remote /dev/cuau0 .... Now, on the target host (the one that entered DDB right before even starting the device probe), type: -[source,shell] +[source,bash] .... Debugger("Boot flags requested debugger") Stopped at Debugger+0x35: movb $0, edata+0x51bc @@ -508,14 +508,14 @@ db> gdb DDB will respond with: -[source,shell] +[source,bash] .... Next trap will enter GDB remote protocol mode .... Every time you type `gdb`, the mode will be toggled between remote GDB and local DDB. In order to force a next trap immediately, simply type `s` (step). Your hosting GDB will now gain control over the target kernel: -[source,shell] +[source,bash] .... Remote debugging using /dev/cuau0 Debugger (msg=0xf01b0383 "Boot flags requested debugger") @@ -579,7 +579,7 @@ To enable FireWire(R) and Dcons support in man:loader[8] on i386 or amd64: Add `LOADER_FIREWIRE_SUPPORT=YES` in [.filename]#/etc/make.conf# and rebuild man:loader[8]: -[source,shell] +[source,bash] .... # cd /sys/boot/i386 && make clean && make && make install .... @@ -588,7 +588,7 @@ To enable man:dcons[4] as an active low-level console, add `boot_multicons="YES" Here are a few configuration examples. A sample kernel configuration file would contain: -[source,shell] +[source,bash] .... device dcons device dcons_crom @@ -600,7 +600,7 @@ options ALT_BREAK_TO_DEBUGGER And a sample [.filename]#/boot/loader.conf# would contain: -[source,shell] +[source,bash] .... dcons_crom_load="YES" dcons_gdb=1 @@ -613,7 +613,7 @@ hw.firewire.dcons_crom.force_console=1 To enable FireWire(R) support in the kernel on the _host machine_: -[source,shell] +[source,bash] .... # kldload firewire .... @@ -622,7 +622,7 @@ Find out the EUI64 (the unique 64 bit identifier) of the FireWire(R) host contro Run man:dconschat[8], with: -[source,shell] +[source,bash] .... # dconschat -e \# -br -G 12345 -t 00-11-22-33-44-55-66-77 .... @@ -648,7 +648,7 @@ The following key combinations can be used once man:dconschat[8] is running: Attach remote GDB by starting man:kgdb[1] with a remote debugging session: -[source,shell] +[source,bash] .... kgdb -r :12345 kernel .... @@ -659,7 +659,7 @@ Here are some general tips: To take full advantage of the speed of FireWire(R), disable other slow console drivers: -[source,shell] +[source,bash] .... # conscontrol delete ttyd0 # serial console # conscontrol delete consolectl # video/keyboard @@ -667,7 +667,7 @@ To take full advantage of the speed of FireWire(R), disable other slow console d There exists a GDB mode for man:emacs[1]; this is what you will need to add to your [.filename]#.emacs#: -[source,shell] +[source,bash] .... (setq gud-gdba-command-name "kgdb -a -a -a -r :12345") (setq gdb-many-windows t) @@ -677,7 +677,7 @@ M-x gdba And for DDD ([.filename]#devel/ddd#): -[source,shell] +[source,bash] .... # remote serial protocol LANG=C ddd --debugger kgdb -r :12345 kernel @@ -695,21 +695,21 @@ To use man:dcons[4] with KVM: Dump a man:dcons[4] buffer of a live system: -[source,shell] +[source,bash] .... # dconschat -1 .... Dump a man:dcons[4] buffer of a crash dump: -[source,shell] +[source,bash] .... # dconschat -1 -M vmcore.XX .... Live core debugging can be done via: -[source,shell] +[source,bash] .... # fwcontrol -m target_eui64 # kgdb kernel /dev/fwmem0.2 diff --git a/documentation/content/en/books/developers-handbook/l10n/chapter.adoc b/documentation/content/en/books/developers-handbook/l10n/_index.adoc index 3903ed3d75..4966af0aa2 100644 --- a/documentation/content/en/books/developers-handbook/l10n/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/l10n/_index.adoc @@ -78,7 +78,7 @@ The language catalog files have to be compiled into a binary form before they ca [[nls-using]] === Using the Catalog Files from the Source Code -Using the catalog files is simple. To use the related functions, [.filename]#nl_types.h# must be included. Before using a catalog, it has to be opened with man:catopen[3]. The function takes two arguments. The first parameter is the name of the installed and compiled catalog. Usually, the name of the program is used, such as grep. This name will be used when looking for the compiled catalog file. The man:catopen[3] call looks for this file in [.filename]#/usr/share/nls/locale/catname# and in [.filename]#/usr/local/shared/nls/locale/catname#, where `locale` is the locale set and `catname` is the catalog name being discussed. The second parameter is a constant, which can have two values: +Using the catalog files is simple. To use the related functions, [.filename]#nl_types.h# must be included. Before using a catalog, it has to be opened with man:catopen[3]. The function takes two arguments. The first parameter is the name of the installed and compiled catalog. Usually, the name of the program is used, such as grep. This name will be used when looking for the compiled catalog file. The man:catopen[3] call looks for this file in [.filename]#/usr/shared/nls/locale/catname# and in [.filename]#/usr/local/shared/nls/locale/catname#, where `locale` is the locale set and `catname` is the catalog name being discussed. The second parameter is a constant, which can have two values: * `NL_CAT_LOCALE`, which means that the used catalog file will be based on `LC_MESSAGES`. * `0`, which means that `LANG` has to be used to open the proper catalog. diff --git a/documentation/content/en/books/developers-handbook/parti.adoc b/documentation/content/en/books/developers-handbook/parti.adoc new file mode 100644 index 0000000000..28dc649a3e --- /dev/null +++ b/documentation/content/en/books/developers-handbook/parti.adoc @@ -0,0 +1,10 @@ +--- +title: Part I. Basics +prev: books/developers-handbook/preface +next: books/developers-handbook/introduction +--- + +[[basics]] += Basics + +include::content/en/books/developers-handbook/toc-1.adoc[] diff --git a/documentation/content/en/books/developers-handbook/partii.adoc b/documentation/content/en/books/developers-handbook/partii.adoc new file mode 100644 index 0000000000..0216af6687 --- /dev/null +++ b/documentation/content/en/books/developers-handbook/partii.adoc @@ -0,0 +1,10 @@ +--- +title: Part II. Interprocess Communication +prev: books/developers-handbook/testing +next: books/developers-handbook/sockets +--- + +[[ipc]] += Interprocess Communication + +include::content/en/books/developers-handbook/toc-2.adoc[] diff --git a/documentation/content/en/books/developers-handbook/partiii.adoc b/documentation/content/en/books/developers-handbook/partiii.adoc new file mode 100644 index 0000000000..7357b79867 --- /dev/null +++ b/documentation/content/en/books/developers-handbook/partiii.adoc @@ -0,0 +1,10 @@ +--- +title: Part III. Kernel +prev: books/developers-handbook/ipv6 +next: books/developers-handbook/kernelbuild +--- + +[[kernel]] += Kernel + +include::content/en/books/developers-handbook/toc-3.adoc[] diff --git a/documentation/content/en/books/developers-handbook/partiv.adoc b/documentation/content/en/books/developers-handbook/partiv.adoc new file mode 100644 index 0000000000..bed213b989 --- /dev/null +++ b/documentation/content/en/books/developers-handbook/partiv.adoc @@ -0,0 +1,11 @@ +--- +title: Part IV. Architectures +prev: books/developers-handbook/kerneldebug +next: books/developers-handbook/x86 +--- + +[[architectures]] += Architectures + +include::content/en/books/developers-handbook/toc-4.adoc[] + diff --git a/documentation/content/en/books/developers-handbook/partv.adoc b/documentation/content/en/books/developers-handbook/partv.adoc new file mode 100644 index 0000000000..305926ca2e --- /dev/null +++ b/documentation/content/en/books/developers-handbook/partv.adoc @@ -0,0 +1,10 @@ +--- +title: Part V. Appendices +prev: books/developers-handbook/x86 +next: books/developers-handbook/bibliography +--- + +[[appendices]] += Appendices + +include::content/en/books/developers-handbook/toc-5.adoc[] diff --git a/documentation/content/en/books/developers-handbook/policies/_index.adoc b/documentation/content/en/books/developers-handbook/policies/_index.adoc new file mode 100644 index 0000000000..0f437fd48c --- /dev/null +++ b/documentation/content/en/books/developers-handbook/policies/_index.adoc @@ -0,0 +1,271 @@ +--- +title: Chapter 5. Source Tree Guidelines and Policies +authors: + - author: Poul-Henning Kamp + - author: Giorgos Keramidas +prev: books/developers-handbook/l10n +next: books/developers-handbook/testing +--- + +[[policies]] += Source Tree Guidelines and Policies +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:source-highlighter: rouge +:experimental: +:skip-front-matter: +:xrefstyle: basic +:relfileprefix: ../ +:outfilesuffix: +:sectnumoffset: 5 + +include::shared/mirrors.adoc[] +include::shared/authors.adoc[] +include::shared/releases.adoc[] +include::shared/en/mailing-lists.adoc[] +include::shared/en/teams.adoc[] +include::shared/en/urls.adoc[] + +toc::[] + +This chapter documents various guidelines and policies in force for the FreeBSD source tree. + +[[policies-style]] +== Style Guidelines + +Consistent coding style is extremely important, particularly with large projects like FreeBSD. Code should follow the FreeBSD coding styles described in man:style[9] and man:style.Makefile[5]. + +[[policies-maintainer]] +== `MAINTAINER` on Makefiles + +If a particular portion of the FreeBSD [.filename]#src/# distribution is being maintained by a person or group of persons, this is communicated through an entry in [.filename]#src/MAINTAINERS#. Maintainers of ports within the Ports Collection express their maintainership to the world by adding a `MAINTAINER` line to the [.filename]#Makefile# of the port in question: + +[.programlisting] +.... +MAINTAINER= email-addresses +.... + +[TIP] +==== + +For other parts of the repository, or for sections not listed as having a maintainer, or when you are unsure who the active maintainer is, try looking at the recent commit history of the relevant parts of the source tree. It is quite often the case that a maintainer is not explicitly named, but the people who are actively working in a part of the source tree for, say, the last couple of years are interested in reviewing changes. Even if this is not specifically mentioned in the documentation or the source itself, asking for a review as a form of courtesy is a very reasonable thing to do. +==== + +The role of the maintainer is as follows: + +* The maintainer owns and is responsible for that code. This means that he or she is responsible for fixing bugs and answering problem reports pertaining to that piece of the code, and in the case of contributed software, for tracking new versions, as appropriate. +* Changes to directories which have a maintainer defined shall be sent to the maintainer for review before being committed. Only if the maintainer does not respond for an unacceptable period of time, to several emails, will it be acceptable to commit changes without review by the maintainer. However, it is suggested that you try to have the changes reviewed by someone else if at all possible. +* It is of course not acceptable to add a person or group as maintainer unless they agree to assume this duty. On the other hand it does not have to be a committer and it can easily be a group of people. + +[[policies-contributed]] +== Contributed Software + +Some parts of the FreeBSD distribution consist of software that is actively being maintained outside the FreeBSD project. For historical reasons, we call this _contributed_ software. Some examples are sendmail, gcc and patch. + +Over the last couple of years, various methods have been used in dealing with this type of software and all have some number of advantages and drawbacks. No clear winner has emerged. + +Since this is the case, after some debate one of these methods has been selected as the "official" method and will be required for future imports of software of this kind. Furthermore, it is strongly suggested that existing contributed software converge on this model over time, as it has significant advantages over the old method, including the ability to easily obtain diffs relative to the "official" versions of the source by everyone (even without direct repository access). This will make it significantly easier to return changes to the primary developers of the contributed software. + +Ultimately, however, it comes down to the people actually doing the work. If using this model is particularly unsuited to the package being dealt with, exceptions to these rules may be granted only with the approval of the core team and with the general consensus of the other developers. The ability to maintain the package in the future will be a key issue in the decisions. + +[NOTE] +==== +Because it makes it harder to import future versions minor, trivial and/or cosmetic changes are _strongly discouraged_ on files that are still tracking the vendor branch. +==== + +[[vendor-import-svn]] +=== Vendor Imports with SVN + +This section describes the vendor import procedure with Subversion in details. + +[.procedure] +. *Preparing the Tree* ++ +If this is your first import after the switch to SVN, you will have to flatten and clean up the vendor tree, and bootstrap merge history in the main tree. If not, you can safely omit this step. ++ +During the conversion from CVS to SVN, vendor branches were imported with the same layout as the main tree. For example, the foo vendor sources ended up in [.filename]#vendor/foo/dist/contrib/foo#, but it is pointless and rather inconvenient. What we really want is to have the vendor source directly in [.filename]#vendor/foo/dist#, like this: ++ +[source,bash] +.... +% cd vendor/foo/dist/contrib/foo +% svn move $(svn list) ../.. +% cd ../.. +% svn remove contrib +% svn propdel -R svn:mergeinfo +% svn commit +.... ++ +Note that, the `propdel` bit is necessary because starting with 1.5, Subversion will automatically add `svn:mergeinfo` to any directory you copy or move. In this case, you will not need this information, since you are not going to merge anything from the tree you deleted. ++ +[NOTE] +==== +You may want to flatten the tags as well. The procedure is exactly the same. If you do this, put off the commit until the end. +==== ++ +Check the [.filename]#dist# tree and perform any cleanup that is deemed to be necessary. You may want to disable keyword expansion, as it makes no sense on unmodified vendor code. In some cases, it can be even be harmful. ++ +[source,bash] +.... +% svn propdel svn:keywords -R . +% svn commit +.... ++ +Bootstrapping of `svn:mergeinfo` on the target directory (in the main tree) to the revision that corresponds to the last change was made to the vendor tree prior to importing new sources is also needed: ++ +[source,bash] +.... +% cd head/contrib/foo +% svn merge --record-only ^/vendor/foo/dist@12345678 . +% svn commit +.... ++ +With some shells, the `^` in the above command may need to be escaped with a backslash. +. *Importing New Sources* ++ +Prepare a full, clean tree of the vendor sources. With SVN, we can keep a full distribution in the vendor tree without bloating the main tree. Import everything but merge only what is needed. ++ +Note that you will need to add any files that were added since the last vendor import, and remove any that were removed. To facilitate this, you should prepare sorted lists of the contents of the vendor tree and of the sources you are about to import: ++ +[source,bash] +.... +% cd vendor/foo/dist +% svn list -R | grep -v '/$' | sort > ../old +% cd ../foo-9.9 +% find . -type f | cut -c 3- | sort > ../new +.... ++ +With these two files, the following command will list removed files (files only in [.filename]#old#): ++ +[source,bash] +.... +% comm -23 ../old ../new +.... ++ +While the command below will list added files (files only in [.filename]#new#): ++ +[source,bash] +.... +% comm -13 ../old ../new +.... ++ +Let us put this together: ++ +[source,bash] +.... +% cd vendor/foo/foo-9.9 +% tar cf - . | tar xf - -C ../dist +% cd ../dist +% comm -23 ../old ../new | xargs svn remove +% comm -13 ../old ../new | xargs svn add +.... ++ +[WARNING] +==== + +If there are new directories in the new distribution, the last command will fail. You will have to add the directories, and run it again. Conversely, if any directories were removed, you will have to remove them manually. +==== ++ +Check properties on any new files: + +** All text files should have `svn:eol-style` set to `native`. +** All binary files should have `svn:mime-type` set to `application/octet-stream`, unless there is a more appropriate media type. +** Executable files should have `svn:executable` set to `*`. +** There should be no other properties on any file in the tree. ++ +[NOTE] +==== +You are ready to commit, but you should first check the output of `svn stat` and `svn diff` to make sure everything is in order. +==== ++ +Once you have committed the new vendor release, you should tag it for future reference. The best and quickest way is to do it directly in the repository: ++ +[source,bash] +.... +% svn copy ^/vendor/foo/dist svn_base/vendor/foo/9.9 +.... ++ +To get the new tag, you can update your working copy of [.filename]#vendor/foo#. ++ +[NOTE] +==== +If you choose to do the copy in the checkout instead, do not forget to remove the generated `svn:mergeinfo` as described above. +==== + +. *Merging to __-HEAD__* ++ +After you have prepared your import, it is time to merge. Option `--accept=postpone` tells SVN not to handle merge conflicts yet, because they will be taken care of manually: ++ +[source,bash] +.... +% cd head/contrib/foo +% svn update +% svn merge --accept=postpone ^/vendor/foo/dist +.... ++ +Resolve any conflicts, and make sure that any files that were added or removed in the vendor tree have been properly added or removed in the main tree. It is always a good idea to check differences against the vendor branch: ++ +[source,bash] +.... +% svn diff --no-diff-deleted --old=^/vendor/foo/dist --new=. +.... ++ +`--no-diff-deleted` tells SVN not to check files that are in the vendor tree but not in the main tree. ++ +[NOTE] +==== +With SVN, there is no concept of on or off the vendor branch. If a file that previously had local modifications no longer does, just remove any left-over cruft, such as FreeBSD version tags, so it no longer shows up in diffs against the vendor tree. +==== ++ +If any changes are required for the world to build with the new sources, make them now - and test until you are satisfied that everything build and runs correctly. +. *Commit* ++ +Now, you are ready to commit. Make sure you get everything in one go. Ideally, you would have done all steps in a clean tree, in which case you can just commit from the top of that tree. That is the best way to avoid surprises. If you do it properly, the tree will move atomically from a consistent state with the old code to a consistent state with the new code. + +[[policies-encumbered]] +== Encumbered Files + +It might occasionally be necessary to include an encumbered file in the FreeBSD source tree. For example, if a device requires a small piece of binary code to be loaded to it before the device will operate, and we do not have the source to that code, then the binary file is said to be encumbered. The following policies apply to including encumbered files in the FreeBSD source tree. + +. Any file which is interpreted or executed by the system CPU(s) and not in source format is encumbered. +. Any file with a license more restrictive than BSD or GNU is encumbered. +. A file which contains downloadable binary data for use by the hardware is not encumbered, unless (1) or (2) apply to it. It must be stored in an architecture neutral ASCII format (file2c or uuencoding is recommended). +. Any encumbered file requires specific approval from the link:https://www.FreeBSD.org/administration/#t-core[Core Team] before it is added to the repository. +. Encumbered files go in [.filename]#src/contrib# or [.filename]#src/sys/contrib#. +. The entire module should be kept together. There is no point in splitting it, unless there is code-sharing with non-encumbered code. +. Object files are named [.filename]#arch/filename.o.uu>#. +. Kernel files: +.. Should always be referenced in [.filename]#conf/files.*# (for build simplicity). +.. Should always be in [.filename]#LINT#, but the link:https://www.FreeBSD.org/administration/#t-core[Core Team] decides per case if it should be commented out or not. The link:https://www.FreeBSD.org/administration/#t-core[Core Team] can, of course, change their minds later on. +.. The _Release Engineer_ decides whether or not it goes into the release. + +. User-land files: +.. The link:https://www.FreeBSD.org/administration/#t-core[Core team] decides if the code should be part of `make world`. +.. The link:https://www.FreeBSD.org/administration/#t-re[Release Engineering] decides if it goes into the release. + +[[policies-shlib]] +== Shared Libraries + +If you are adding shared library support to a port or other piece of software that does not have one, the version numbers should follow these rules. Generally, the resulting numbers will have nothing to do with the release version of the software. + +The three principles of shared library building are: + +* Start from `1.0` +* If there is a change that is backwards compatible, bump minor number (note that ELF systems ignore the minor number) +* If there is an incompatible change, bump major number + +For instance, added functions and bugfixes result in the minor version number being bumped, while deleted functions, changed function call syntax, etc. will force the major version number to change. + +Stick to version numbers of the form major.minor (`_x_._y_`). Our a.out dynamic linker does not handle version numbers of the form `_x_._y_._z_` well. Any version number after the `_y_` (i.e., the third digit) is totally ignored when comparing shared lib version numbers to decide which library to link with. Given two shared libraries that differ only in the "micro" revision, `ld.so` will link with the higher one. That is, if you link with [.filename]#libfoo.so.3.3.3#, the linker only records `3.3` in the headers, and will link with anything starting with `_libfoo.so.3_._(anything >= 3)_._(highest available)_`. + +[NOTE] +==== +`ld.so` will always use the highest "minor" revision. For instance, it will use [.filename]#libc.so.2.2# in preference to [.filename]#libc.so.2.0#, even if the program was initially linked with [.filename]#libc.so.2.0#. +==== + +In addition, our ELF dynamic linker does not handle minor version numbers at all. However, one should still specify a major and minor version number as our [.filename]#Makefile#'s "do the right thing" based on the type of system. + +For non-port libraries, it is also our policy to change the shared library version number only once between releases. In addition, it is our policy to change the major shared library version number only once between major OS releases (i.e., from 6.0 to 7.0). When you make a change to a system library that requires the version number to be bumped, check the [.filename]#Makefile#'s commit logs. It is the responsibility of the committer to ensure that the first such change since the release will result in the shared library version number in the [.filename]#Makefile# to be updated, and any subsequent changes will not. diff --git a/documentation/content/en/books/developers-handbook/policies/chapter.adoc b/documentation/content/en/books/developers-handbook/policies/chapter.adoc deleted file mode 100644 index ea7c98d70c..0000000000 --- a/documentation/content/en/books/developers-handbook/policies/chapter.adoc +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Chapter 5. Source Tree Guidelines and Policies -authors: - - author: Poul-Henning Kamp - - author: Giorgos Keramidas -prev: books/developers-handbook/l10n -next: books/developers-handbook/testing ---- - -[[policies]] -= Source Tree Guidelines and Policies -:doctype: book -:toc: macro -:toclevels: 1 -:icons: font -:sectnums: -:sectnumlevels: 6 -:source-highlighter: rouge -:experimental: -:skip-front-matter: -:xrefstyle: basic -:relfileprefix: ../ -:outfilesuffix: -:sectnumoffset: 5 - -include::shared/mirrors.adoc[] -include::shared/authors.adoc[] -include::shared/releases.adoc[] -include::shared/en/mailing-lists.adoc[] -include::shared/en/teams.adoc[] -include::shared/en/urls.adoc[] - -toc::[] - -This chapter documents various guidelines and policies in force for the FreeBSD source tree. - -[[policies-style]] -== Style Guidelines - -Consistent coding style is extremely important, particularly with large projects like FreeBSD. Code should follow the FreeBSD coding styles described in man:style[9] and man:style.Makefile[5]. - -[[policies-maintainer]] -== `MAINTAINER` on Makefiles - -If a particular portion of the FreeBSD [.filename]#src/# distribution is being maintained by a person or group of persons, this is communicated through an entry in [.filename]#src/MAINTAINERS#. Maintainers of ports within the Ports Collection express their maintainership to the world by adding a `MAINTAINER` line to the [.filename]#Makefile# of the port in question: - -[.programlisting] -.... -MAINTAINER= email-addresses -.... - -[TIP] -==== - -For other parts of the repository, or for sections not listed as having a maintainer, or when you are unsure who the active maintainer is, try looking at the recent commit history of the relevant parts of the source tree. It is quite often the case that a maintainer is not explicitly named, but the people who are actively working in a part of the source tree for, say, the last couple of years are interested in reviewing changes. Even if this is not specifically mentioned in the documentation or the source itself, asking for a review as a form of courtesy is a very reasonable thing to do. -==== - -The role of the maintainer is as follows: - -* The maintainer owns and is responsible for that code. This means that he or she is responsible for fixing bugs and answering problem reports pertaining to that piece of the code, and in the case of contributed software, for tracking new versions, as appropriate. -* Changes to directories which have a maintainer defined shall be sent to the maintainer for review before being committed. Only if the maintainer does not respond for an unacceptable period of time, to several emails, will it be acceptable to commit changes without review by the maintainer. However, it is suggested that you try to have the changes reviewed by someone else if at all possible. -* It is of course not acceptable to add a person or group as maintainer unless they agree to assume this duty. On the other hand it does not have to be a committer and it can easily be a group of people. - -[[policies-contributed]] -== Contributed Software - -Some parts of the FreeBSD distribution consist of software that is actively being maintained outside the FreeBSD project. For historical reasons, we call this _contributed_ software. Some examples are sendmail, gcc and patch. - -Over the last couple of years, various methods have been used in dealing with this type of software and all have some number of advantages and drawbacks. No clear winner has emerged. - -Since this is the case, after some debate one of these methods has been selected as the "official" method and will be required for future imports of software of this kind. Furthermore, it is strongly suggested that existing contributed software converge on this model over time, as it has significant advantages over the old method, including the ability to easily obtain diffs relative to the "official" versions of the source by everyone (even without direct repository access). This will make it significantly easier to return changes to the primary developers of the contributed software. - -Ultimately, however, it comes down to the people actually doing the work. If using this model is particularly unsuited to the package being dealt with, exceptions to these rules may be granted only with the approval of the link:https://www.FreeBSD.org/administration/#t-core[Core Team] and with the general consensus of the other developers. The ability to maintain the package in the future will be a key issue in the decisions. - -[NOTE] -==== -Because it makes it harder to import future versions minor, trivial and/or cosmetic changes are _strongly discouraged_ on files that are still tracking the vendor branch. -==== - -For details on how do do a vendor import please see link:https://docs.freebsd.org/en/articles/committers-guide/#git-primer[the committers guide] - -[[policies-encumbered]] -== Encumbered Files - -It might occasionally be necessary to include an encumbered file in the FreeBSD source tree. For example, if a device requires a small piece of binary code to be loaded to it before the device will operate, and we do not have the source to that code, then the binary file is said to be encumbered. The following policies apply to including encumbered files in the FreeBSD source tree. - -. Any file which is interpreted or executed by the system CPU(s) and not in source format is encumbered. -. Any file with a license more restrictive than BSD or GNU is encumbered. -. A file which contains downloadable binary data for use by the hardware is not encumbered, unless (1) or (2) apply to it. It must be stored in an architecture neutral ASCII format (file2c or uuencoding is recommended). -. Any encumbered file requires specific approval from the link:https://www.FreeBSD.org/administration/#t-core[Core Team] before it is added to the repository. -. Encumbered files go in [.filename]#src/contrib# or [.filename]#src/sys/contrib#. -. The entire module should be kept together. There is no point in splitting it, unless there is code-sharing with non-encumbered code. -. Object files are named [.filename]#arch/filename.o.uu#. -. Firmware files are named [.filename]#filename.fw.uu#. -. Kernel files: -.. Should always be referenced in [.filename]#conf/files.*# (for build simplicity). -.. Should always be in [.filename]#LINT#, but when the consensus isn't clear the link:https://www.FreeBSD.org/administration/#t-core[Core Team] decides if it should be commented out or not. -.. The link:https://www.FreeBSD.org/administration/#t-re[Release Engineering] team decides whether or not it goes into the release. - -. User-land files: -.. The link:https://www.FreeBSD.org/administration/#t-core[Core team] decides if the code should be part of `make world` by default if there is no clear consensus. -.. The link:https://www.FreeBSD.org/administration/#t-re[Release Engineering] team decides if it goes into the release. - -[[policies-shlib]] -== Shared Libraries - -If you are adding shared library support to a port or other piece of software that does not have one, the version numbers should follow these rules. Generally, the resulting numbers will have nothing to do with the release version of the software. - -FreeBSD tries to maintain ABI stability. Most libraries in the system use symbol versioning to remain compatible with old versions of the library. When updating libraries with versioned symbols: - -. Create new symbols in the symbol map for otherwise incompatible changes. -. When deleting old functions, only remove visibility of symbols from newer versions (that is, do not delete functions). -. Avoid gratuitous rearrangement of structures. This will keep compatibility symbols to a minimum. -. If changes require a version bump, re-evaluate whether they are needed at all. - -For project-maintained libraries, please try to follow the following guidelines for major version numbers: - -. New libraries -.. Should start with major version 1, though third-party libraries may start at a different number if warranted -.. All new libraries should either be symvers or private unless there's some compelling reason to deviate. -. For non-symvers libraries, avoid changes that would require a version bump. -.. When making a change that requires one, seriously consider adopting symbol versions at the same time -. For symvers libraries, generally, avoid version bumps -. Changes to structures can be worked around by providing the old structure and old functions to access it (if the layout of the structure is embedded in its clients). -. Changes to function signatures can be implemented by creating compatibility versions of the function (often calling the new version of the function in a specific way). -. If the benefits of a version bump outweight the costs to do it, follow up to ensure compat packages are built, etc -. Carefully consider the impact of a major version bump. When a major version change cannot be avoided, add a version map to avoid future bumps. -. For libraries where the ABI cannot be guaranteed, make them FreeBSD private where possible. Third party libraries that have poor ABI guarantees are generally made private, though there are a few exceptions for historical reasons. -. It is strong policy not to change the ABI of dynamicly linked libararies in an non-backwards compatible way -. Every reasonable effort should be made to make the changes in a binary compatible manner using tools like symbol versioning -. When major version changes cannot be avoided, the policy is to change only between major releases. -.. Minimize the number of major version bumps where possible -.. Multiple bumps are allowed between releases where necessary -.. Where possible, batch multiple changes that each would require a major bump together -.. Ensure that the compatibility ports / packages are updated as appropriate -.. Request an exp-run of ports to understand the full impact of the change to the base system -. Any changes to major libraries must still allow build from source upgrades to succeed - -Changing the ABI is allowed, otherwise FreeBSD cannot evolve. However, the project has generally chosen to pay the added cost of retaining ABI backward-compatibility. diff --git a/documentation/content/en/books/developers-handbook/secure/chapter.adoc b/documentation/content/en/books/developers-handbook/secure/_index.adoc index 0c7c334aab..8ed21a75c2 100644 --- a/documentation/content/en/books/developers-handbook/secure/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/secure/_index.adoc @@ -46,9 +46,9 @@ One of the pitfalls of the UNIX(R) environment is how easy it is to make assumpt [[secure-bufferov]] == Buffer Overflows -Buffer Overflows have been around since the very beginnings of the von Neumann <<cod,1>> architecture. They first gained widespread notoriety in 1988 with the Morris Internet worm. Unfortunately, the same basic attack remains effective today. By far the most common type of buffer overflow attack is based on corrupting the stack. +Buffer Overflows have been around since the very beginnings of the von Neumann crossref:bibliography[cod,1] architecture. They first gained widespread notoriety in 1988 with the Morris Internet worm. Unfortunately, the same basic attack remains effective today. By far the most common type of buffer overflow attack is based on corrupting the stack. -Most modern computer systems use a stack to pass arguments to procedures and to store local variables. A stack is a last in first out (LIFO) buffer in the high memory area of a process image. When a program invokes a function a new "stack frame" is created. This stack frame consists of the arguments passed to the function as well as a dynamic amount of local variable space. The "stack pointer" is a register that holds the current location of the top of the stack. Since this value is constantly changing as new values are pushed onto the top of the stack, many implementations also provide a "frame pointer" that is located near the beginning of a stack frame so that local variables can more easily be addressed relative to this value. <<cod,1>> The return address for function calls is also stored on the stack, and this is the cause of stack-overflow exploits since overflowing a local variable in a function can overwrite the return address of that function, potentially allowing a malicious user to execute any code he or she wants. +Most modern computer systems use a stack to pass arguments to procedures and to store local variables. A stack is a last in first out (LIFO) buffer in the high memory area of a process image. When a program invokes a function a new "stack frame" is created. This stack frame consists of the arguments passed to the function as well as a dynamic amount of local variable space. The "stack pointer" is a register that holds the current location of the top of the stack. Since this value is constantly changing as new values are pushed onto the top of the stack, many implementations also provide a "frame pointer" that is located near the beginning of a stack frame so that local variables can more easily be addressed relative to this value. crossref:bibliography[cod,1] The return address for function calls is also stored on the stack, and this is the cause of stack-overflow exploits since overflowing a local variable in a function can overwrite the return address of that function, potentially allowing a malicious user to execute any code he or she wants. Although stack-based attacks are by far the most common, it would also be possible to overrun the stack with a heap-based (malloc/free) attack. @@ -96,7 +96,7 @@ May overflow the str buffer. === Example Buffer Overflow -The following example code contains a buffer overflow designed to overwrite the return address and skip the instruction immediately following the function call. (Inspired by <<Phrack,4>>) +The following example code contains a buffer overflow designed to overwrite the return address and skip the instruction immediately following the function call. (Inspired by crossref:bibliography[Phrack,4]) [.programlisting] .... diff --git a/documentation/content/en/books/developers-handbook/sockets/chapter.adoc b/documentation/content/en/books/developers-handbook/sockets/_index.adoc index 584e3516a8..bea670b3d2 100644 --- a/documentation/content/en/books/developers-handbook/sockets/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/sockets/_index.adoc @@ -449,7 +449,7 @@ int main() { Go ahead, enter it in your editor, save it as [.filename]#daytime.c#, then compile and run it: -[source,shell] +[source,bash] .... % cc -O3 -o daytime daytime.c % ./daytime @@ -662,7 +662,7 @@ Not all protocols are that simple. Many receive a request from the client, reply Now, go ahead, save the above source code as [.filename]#daytimed.c# (it is customary to end the names of daemons with the letter `d`). After you have compiled it, try running it: -[source,shell] +[source,bash] .... % ./daytimed bind: Permission denied @@ -673,7 +673,7 @@ What happened here? As you will recall, the _daytime_ protocol uses port 13. But Try again, this time as the superuser: -[source,shell] +[source,bash] .... # ./daytimed # @@ -681,7 +681,7 @@ Try again, this time as the superuser: What... Nothing? Let us try again: -[source,shell] +[source,bash] .... # ./daytimed @@ -693,7 +693,7 @@ Every port can only be bound by one program at a time. Our first attempt was ind Fine, we know it is running in the background. But is it working? How do we know it is a proper _daytime_ server? Simple: -[source,shell] +[source,bash] .... % telnet localhost 13 @@ -711,7 +711,7 @@ telnet tried the new IPv6, and failed. It retried with IPv4 and succeeded. The d If you have access to another UNIX(R) system via telnet, you can use it to test accessing the server remotely. My computer does not have a static IP address, so this is what I did: -[source,shell] +[source,bash] .... % who @@ -729,7 +729,7 @@ Connection closed by foreign host. Again, it worked. Will it work using the domain name? -[source,shell] +[source,bash] .... % telnet r47.bfm.org 13 @@ -822,7 +822,7 @@ We now can type a domain name (or an IP address, it works both ways) on the comm Since it takes virtually no time to get the time from your local server, you could run daytime twice in a row: First to get the time from `time.nist.gov`, the second time from your own system. You can then compare the results and see how exact your system clock is: -[source,shell] +[source,bash] .... % daytime ; daytime localhost diff --git a/documentation/content/en/books/developers-handbook/testing/chapter.adoc b/documentation/content/en/books/developers-handbook/testing/_index.adoc index 1b8459bfd3..1b8459bfd3 100644 --- a/documentation/content/en/books/developers-handbook/testing/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/testing/_index.adoc diff --git a/documentation/content/en/books/developers-handbook/tools/chapter.adoc b/documentation/content/en/books/developers-handbook/tools/_index.adoc index a00ea30e31..feeaee40b8 100644 --- a/documentation/content/en/books/developers-handbook/tools/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/tools/_index.adoc @@ -141,14 +141,14 @@ The word _compiling_ is often used to refer to just steps 1 to 4-the others are Fortunately, almost all this detail is hidden from you, as `cc` is a front end that manages calling all these programs with the right arguments for you; simply typing -[source,shell] +[source,bash] .... % cc foobar.c .... will cause [.filename]#foobar.c# to be compiled by all the steps above. If you have more than one file to compile, just do something like -[source,shell] +[source,bash] .... % cc foo.c bar.c .... @@ -160,7 +160,7 @@ There are lots and lots of options for `cc`, which are all in the manual page. H `-o _filename_`:: The output name of the file. If you do not use this option, `cc` will produce an executable called [.filename]#a.out#.footnote:[The reasons for this are buried in the mists of history.] + -[source,shell] +[source,bash] .... % cc foobar.c executable is a.out % cc -o foobar foobar.c executable is foobar @@ -169,7 +169,7 @@ The output name of the file. If you do not use this option, `cc` will produce an `-c`:: Just compile the file, do not link it. Useful for toy programs where you just want to check the syntax, or if you are using a [.filename]#Makefile#. + -[source,shell] +[source,bash] .... % cc -c foobar.c .... @@ -180,7 +180,7 @@ This will produce an _object file_ (not an executable) called [.filename]#foobar Create a debug version of the executable. This makes the compiler put information into the executable about which line of which source file corresponds to which function call. A debugger can use this information to show the source code as you step through the program, which is _very_ useful; the disadvantage is that all this extra information makes the program much bigger. Normally, you compile with `-g` while you are developing a program and then compile a "release version" without `-g` when you are satisfied it works properly. + -[source,shell] +[source,bash] .... % cc -g foobar.c .... @@ -190,7 +190,7 @@ This will produce a debug version of the program. footnote:[Note, we did not use `-O`:: Create an optimized version of the executable. The compiler performs various clever tricks to try to produce an executable that runs faster than normal. You can add a number after the `-O` to specify a higher level of optimization, but this often exposes bugs in the compiler's optimizer. + -[source,shell] +[source,bash] .... % cc -O -o foobar foobar.c .... @@ -212,7 +212,7 @@ Without these flags, `cc` will allow you to use some of its non-standard extensi Generally, you should try to make your code as portable as possible, as otherwise you may have to completely rewrite the program later to get it to work somewhere else-and who knows what you may be using in a few years time? -[source,shell] +[source,bash] .... % cc -Wall -ansi -pedantic -o foobar foobar.c .... @@ -226,7 +226,7 @@ The most common example of this is when compiling a program that uses some of th + The rule is that if the library is called [.filename]#libsomething.a#, you give `cc` the argument `-l__something__`. For example, the math library is [.filename]#libm.a#, so you give `cc` the argument `-lm`. A common "gotcha" with the math library is that it has to be the last library on the command line. + -[source,shell] +[source,bash] .... % cc -o foobar foobar.c -lm .... @@ -235,7 +235,7 @@ This will link the math library functions into [.filename]#foobar#. + If you are compiling C++ code, use {c-plus-plus-command}. {c-plus-plus-command} can also be invoked as {clang-plus-plus-command} on FreeBSD. + -[source,shell] +[source,bash] .... % c++ -o foobar foobar.cc .... @@ -246,14 +246,14 @@ This will both produce an executable [.filename]#foobar# from the C++ source fil ==== I am trying to write a program which uses the sin() function and I get an error like this. What does it mean? -[source,shell] +[source,bash] .... /var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment .... When using mathematical functions like `sin()`, you have to tell `cc` to link in the math library, like so: -[source,shell] +[source,bash] .... % cc -o foobar foobar.c -lm .... @@ -275,14 +275,14 @@ int main() { and I compiled it as: -[source,shell] +[source,bash] .... % cc temp.c -lm .... like you said I should, but I get this when I run it: -[source,shell] +[source,bash] .... % ./a.out 2.1 ^ 6 = 1023.000000 @@ -307,7 +307,7 @@ int main() { After recompiling it as you did before, run it: -[source,shell] +[source,bash] .... % ./a.out 2.1 ^ 6 = 85.766121 @@ -319,7 +319,7 @@ If you are using any of the mathematical functions, _always_ include [.filename] Remember, `cc` will call the executable [.filename]#a.out# unless you tell it differently. Use the `-o _filename_` option: -[source,shell] +[source,bash] .... % cc -o foobar foobar.c .... @@ -332,7 +332,7 @@ Unlike MS-DOS(R), UNIX(R) does not look in the current directory when it is tryi Most UNIX(R) systems have a program called `test` in [.filename]#/usr/bin# and the shell is picking that one up before it gets to checking the current directory. Either type: -[source,shell] +[source,bash] .... % ./test .... @@ -414,14 +414,14 @@ No, fortunately not (unless of course you really do have a hardware problem...). Yes, just go to another console or xterm, do -[source,shell] +[source,bash] .... % ps .... to find out the process ID of your program, and do -[source,shell] +[source,bash] .... % kill -ABRT pid .... @@ -441,7 +441,7 @@ If you want to create a core dump from outside your program, but do not want the When you are working on a simple program with only one or two source files, typing in -[source,shell] +[source,bash] .... % cc file1.c file2.c .... @@ -450,7 +450,7 @@ is not too bad, but it quickly becomes very tedious when there are several files One way to get around this is to use object files and only recompile the source file if the source code has changed. So we could have something like: -[source,shell] +[source,bash] .... % cc file1.o file2.o … file37.c … .... @@ -498,7 +498,7 @@ install: We can tell make which target we want to make by typing: -[source,shell] +[source,bash] .... % make target .... @@ -578,15 +578,15 @@ Now I think you will agree that is rather impressive for a four line script! The secret lies in the last line, which tells `make` to look in the system makefile called [.filename]#bsd.port.mk#. It is easy to overlook this line, but this is where all the clever stuff comes from-someone has written a makefile that tells `make` to do all the things above (plus a couple of other things I did not mention, including handling any errors that may occur) and anyone can get access to that just by putting a single line in their own make file! -If you want to have a look at these system makefiles, they are in [.filename]#/usr/share/mk#, but it is probably best to wait until you have had a bit of practice with makefiles, as they are very complicated (and if you do look at them, make sure you have a flask of strong coffee handy!) +If you want to have a look at these system makefiles, they are in [.filename]#/usr/shared/mk#, but it is probably best to wait until you have had a bit of practice with makefiles, as they are very complicated (and if you do look at them, make sure you have a flask of strong coffee handy!) === More Advanced Uses of `make` `Make` is a very powerful tool, and can do much more than the simple example above shows. Unfortunately, there are several different versions of `make`, and they all differ considerably. The best way to learn what they can do is probably to read the documentation-hopefully this introduction will have given you a base from which you can do this. -The version of make that comes with FreeBSD is the Berkeley make; there is a tutorial for it in [.filename]#/usr/share/doc/psd/12.make#. To view it, do +The version of make that comes with FreeBSD is the Berkeley make; there is a tutorial for it in [.filename]#/usr/shared/doc/psd/12.make#. To view it, do -[source,shell] +[source,bash] .... % zmore paper.ascii.gz .... @@ -611,7 +611,7 @@ to the file. Once you have done this, you can type `info` and then select [.guim Using a debugger allows running the program under more controlled circumstances. Typically, it is possible to step through the program a line at a time, inspect the value of variables, change them, tell the debugger to run up to a certain point and then stop, and so on. It is also possible to attach to a program that is already running, or load a core file to investigate why the program crashed. It is even possible to debug the kernel, though that is a little trickier than the user applications we will be discussing in this section. -This section is intended to be a quick introduction to using debuggers and does not cover specialized topics such as debugging the kernel. For more information about that, refer to <<kerneldebug,Kernel Debugging>>. +This section is intended to be a quick introduction to using debuggers and does not cover specialized topics such as debugging the kernel. For more information about that, refer to crossref:kerneldebug[kerneldebug,Kernel Debugging]. The standard debugger supplied with FreeBSD {rel121-current} is called `lldb` (LLVM debugger). As it is part of the standard installation for that release, there is no need to do anything special to use it. It has good command help, accessible via the `help` command, as well as https://lldb.llvm.org/[a web tutorial and documentation]. @@ -630,7 +630,7 @@ Which one to use is largely a matter of taste. If familiar with one only, use th Start up lldb by typing -[source,shell] +[source,bash] .... % lldb -- progname .... @@ -639,7 +639,7 @@ Start up lldb by typing Compile the program with `-g` to get the most out of using `lldb`. It will work without, but will only display the name of the function currently running, instead of the source code. If it displays a line like: -[source,shell] +[source,bash] .... Breakpoint 1: where = temp`main, address = … .... @@ -682,7 +682,7 @@ This program sets i to be `5` and passes it to a function `bazz()` which prints Compiling and running the program displays -[source,shell] +[source,bash] .... % cc -g -o temp temp.c % ./temp @@ -692,7 +692,7 @@ anint = -5360 That is not what was expected! Time to see what is going on! -[source,shell] +[source,bash] .... % lldb -- temp (lldb) target create "temp" @@ -740,7 +740,7 @@ Process 9992 stopped Hang on a minute! How did anint get to be `-5360`? Was it not set to `5` in `main()`? Let us move up to `main()` and have a look. -[source,shell] +[source,bash] .... (lldb) up Move up call stack frame #1: 0x000000000020130b temp`main at temp.c:9:2 lldb displays stack frame @@ -783,7 +783,7 @@ To examine a core file, specify the name of the core file in addition to the pro The debugger will display something like this: -[source,shell,subs="verbatim,quotes"] +[source,bash,subs="verbatim,quotes"] .... % lldb -c [.filename]#progname.core# -- [.filename]#progname# (lldb) target create "[.filename]#progname#" --core "[.filename]#progname#.core" @@ -793,7 +793,7 @@ Core file '/home/pauamma/tmp/[.filename]#progname.core#' (x86_64) was loaded. In this case, the program was called [.filename]#progname#, so the core file is called [.filename]#progname.core#. The debugger does not display why the program crashed or where. For this, use `thread backtrace all`. This will also show how the function where the program dumped core was called. -[source,shell,subs="verbatim,quotes"] +[source,bash,subs="verbatim,quotes"] .... (lldb) thread backtrace all * thread #1, name = 'progname', stop reason = signal SIGSEGV @@ -811,7 +811,7 @@ One of the neatest features about `lldb` is that it can attach to a program that To do that, start up another `lldb`, use `ps` to find the process ID for the child, and do -[source,shell] +[source,bash] .... (lldb) process attach -p pid .... @@ -848,7 +848,7 @@ Starting with LLDB 12.0.0, remote debugging is supported on FreeBSD. This means To launch a new process to be debugged remotely, run `lldb-server` on the remote server by typing -[source,shell] +[source,bash] .... % lldb-server g host:port -- progname .... @@ -857,14 +857,14 @@ The process will be stopped immediately after launching, and `lldb-server` will Start `lldb` locally and type the following command to connect to the remote server: -[source,shell] +[source,bash] .... (lldb) gdb-remote host:port .... `lldb-server` can also attach to a running process. To do that, type the following on the remote server: -[source,shell] +[source,bash] .... % lldb-server g host:port --attach pid-or-name .... @@ -875,14 +875,14 @@ Start `lldb` locally and type the following command to connect to the remote ser Start up gdb by typing -[source,shell] +[source,bash] .... % gdb progname .... although many people prefer to run it inside Emacs. To do this, type: -[source,shell] +[source,bash] .... M-x gdb RET progname RET .... @@ -893,7 +893,7 @@ Finally, for those finding its text-based command-prompt style off-putting, ther Compile the program with `-g` to get the most out of using `gdb`. It will work without, but will only display the name of the function currently running, instead of the source code. A line like: -[source,shell] +[source,bash] .... ... (no debugging symbols found) ... .... @@ -930,7 +930,7 @@ This program sets i to be `5` and passes it to a function `bazz()` which prints Compiling and running the program displays -[source,shell] +[source,bash] .... % cc -g -o temp temp.c % ./temp @@ -940,7 +940,7 @@ anint = 4231 That was not what we expected! Time to see what is going on! -[source,shell] +[source,bash] .... % gdb temp GDB is free software and you are welcome to distribute copies of it @@ -962,7 +962,7 @@ bazz (anint=4231) at temp.c:17 gdb displays stack frame Hang on a minute! How did anint get to be `4231`? Was it not set to `5` in `main()`? Let us move up to `main()` and have a look. -[source,shell] +[source,bash] .... (gdb) up Move up call stack #1 0x1625 in main () at temp.c:11 gdb displays stack frame @@ -996,7 +996,7 @@ A core file is basically a file which contains the complete state of the process To examine a core file, start up `gdb` in the usual way. Instead of typing `break` or `run`, type -[source,shell] +[source,bash] .... (gdb) core progname.core .... @@ -1005,7 +1005,7 @@ If the core file is not in the current directory, type `dir /path/to/core/file` The debugger should display something like this: -[source,shell,subs="verbatim,quotes"] +[source,bash,subs="verbatim,quotes"] .... % gdb [.filename]#progname# GDB is free software and you are welcome to distribute copies of it @@ -1024,7 +1024,7 @@ In this case, the program was called [.filename]#progname#, so the core file is Sometimes it is useful to be able to see how a function was called, as the problem could have occurred a long way up the call stack in a complex program. `bt` causes `gdb` to print out a back-trace of the call stack: -[source,shell] +[source,bash] .... (gdb) bt #0 0x164a in bazz (anint=0x5) at temp.c:17 @@ -1041,7 +1041,7 @@ One of the neatest features about `gdb` is that it can attach to a program that To do that, start up another `gdb`, use `ps` to find the process ID for the child, and do -[source,shell] +[source,bash] .... (gdb) attach pid .... @@ -1124,7 +1124,7 @@ Unfortunately, there is far too much here to explain it in detail; however there * Emacs already has a pre-defined function called `next-error`. In a compilation output window, this allows you to move from one compilation error to the next by doing `M-n`; we define a complementary function, `previous-error`, that allows you to go to a previous error by doing `M-p`. The nicest feature of all is that `C-c C-c` will open up the source file in which the error occurred and jump to the appropriate line. * We enable Emacs's ability to act as a server, so that if you are doing something outside Emacs and you want to edit a file, you can just type in + -[source,shell] +[source,bash] .... % emacsclient filename .... @@ -1427,7 +1427,7 @@ Now, this is all very well if you only want to program in the languages already The first thing to do is find out if whizbang comes with any files that tell Emacs about the language. These usually end in [.filename]#.el#, short for "Emacs Lisp". For example, if whizbang is a FreeBSD port, we can locate these files by doing -[source,shell] +[source,bash] .... % find /usr/ports/lang/whizbang -name "*.el" -print .... @@ -1436,14 +1436,14 @@ and install them by copying them into the Emacs site Lisp directory. On FreeBSD, So for example, if the output from the find command was -[source,shell] +[source,bash] .... /usr/ports/lang/whizbang/work/misc/whizbang.el .... we would do -[source,shell] +[source,bash] .... # cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/shared/emacs/site-lisp .... diff --git a/documentation/content/en/books/developers-handbook/x86/chapter.adoc b/documentation/content/en/books/developers-handbook/x86/_index.adoc index da89327629..4307e1dd63 100644 --- a/documentation/content/en/books/developers-handbook/x86/chapter.adoc +++ b/documentation/content/en/books/developers-handbook/x86/_index.adoc @@ -135,7 +135,7 @@ This convention has a great disadvantage over the UNIX(R) way, at least as far a If you do choose the Linux convention, you must let the system know about it. After your program is assembled and linked, you need to brand the executable: -[source,shell] +[source,bash] .... % brandelf -t Linux filename .... @@ -501,7 +501,7 @@ Type the code (except the line numbers) in an editor, and save it in a file name If you do not have nasm, type: -[source,shell] +[source,bash] .... % su Password:your root password @@ -522,7 +522,7 @@ If your system is not FreeBSD, you need to get nasm from its https://sourceforge Now you can assemble, link, and run the code: -[source,shell] +[source,bash] .... % nasm -f elf hello.asm % ld -s -o hello hello.o @@ -600,7 +600,7 @@ Once there is no more input left, we ask the system to exit our program, returni Go ahead, and save the code in a file named [.filename]#hex.asm#, then type the following (the `^D` means press the control key and type `D` while holding the control key down): -[source,shell] +[source,bash] .... % nasm -f elf hex.asm % ld -s -o hex hex.o @@ -675,7 +675,7 @@ That means we only need to set `CL` once. We have, therefore, added a new label Once you have changed [.filename]#hex.asm# to reflect these changes, type: -[source,shell] +[source,bash] .... % nasm -f elf hex.asm % ld -s -o hex hex.o @@ -803,7 +803,7 @@ We use `EDI` and `ESI` as pointers to the next byte to be read from or written t Let us see how it works now: -[source,shell] +[source,bash] .... % nasm -f elf hex.asm % ld -s -o hex hex.o @@ -919,7 +919,7 @@ write: Now, let us see how it works: -[source,shell] +[source,bash] .... % nasm -f elf hex.asm % ld -s -o hex hex.o @@ -1457,7 +1457,7 @@ This code produces a 1,396-byte executable. Most of it is data, i.e., the HTML m Assemble and link it as usual: -[source,shell] +[source,bash] .... % nasm -f elf webvars.asm % ld -s -o webvars webvars.o @@ -1478,7 +1478,7 @@ One of the first programs I wrote for UNIX(R) was link:ftp://ftp.int80h.org/unix I have used tuc extensively, but always only to convert from some other OS to UNIX(R), never the other way. I have always wished it would just overwrite the file instead of me having to send the output to a different file. Most of the time, I end up using it like this: -[source,shell] +[source,bash] .... % tuc myfile tempfile % mv tempfile myfile @@ -1486,7 +1486,7 @@ I have used tuc extensively, but always only to convert from some other OS to UN It would be nice to have a ftuc, i.e., _fast tuc_, and use it like this: -[source,shell] +[source,bash] .... % ftuc myfile .... @@ -2034,7 +2034,7 @@ This time I decided to let it do a little more work than a typical tutorial prog Here is its usage message: -[source,shell] +[source,bash] .... Usage: csv [-t<delim>] [-c<comma>] [-p] [-o <outfile>] [-i <infile>] .... @@ -2053,7 +2053,7 @@ I made sure that both `-i filename` and `-ifilename` are accepted. I also made s To get the 11th field of each record, I can now do: -[source,shell] +[source,bash] .... % csv '-t;' data.csv | awk '-F;' '{print $11}' .... @@ -2381,7 +2381,7 @@ Here is what might happen: At this point our filter waits for the image editor to send it more data to process, while the image editor is waiting for our filter to send it the result of the processing of the first row. But the result sits in our output buffer. -The filter and the image editor will continue waiting for each other forever (or, at least, until they are killed). Our software has just entered a <<secure-race-conditions,race condition>>. +The filter and the image editor will continue waiting for each other forever (or, at least, until they are killed). Our software has just entered a crossref:secure[secure-race-conditions,race condition]. This problem does not exist if our filter flushes its output buffer _before_ asking the _kernel_ for more input data. @@ -2555,7 +2555,7 @@ But our pinhole program cannot just work with individual characters, it has to d For example, if we want the program to calculate the pinhole diameter (and other values we will discuss later) at the focal lengths of `100 mm`, `150 mm`, and `210 mm`, we may want to enter something like this: -[source,shell] +[source,bash] .... 100, 150, 210 .... @@ -2570,7 +2570,7 @@ Personally, I like to keep it simple. Something either is a number, so I process Plus, it allows me to break up the monotony of computing and type in a query instead of just a number: -[source,shell] +[source,bash] .... What is the best pinhole diameter for the focal length of 150? @@ -2578,7 +2578,7 @@ What is the best pinhole diameter for the There is no reason for the computer to spit out a number of complaints: -[source,shell] +[source,bash] .... Syntax error: What Syntax error: is @@ -2667,7 +2667,7 @@ So, it makes perfect sense to start each line with the focal length as entered b No, wait! Not as entered by the user. What if the user types in something like this: -[source,shell] +[source,bash] .... 00000000150 .... @@ -2680,7 +2680,7 @@ But... What if the user types something like this: -[source,shell] +[source,bash] .... 17459765723452353453534535353530530534563507309676764423 .... @@ -2697,7 +2697,7 @@ What will we do? We will slap him in the face, in a manner of speaking: -[source,shell] +[source,bash] .... 17459765723452353453534535353530530534563507309676764423 ??? ??? ??? ??? ??? .... @@ -2720,7 +2720,7 @@ That still leaves one possibility uncovered: If all the user enters is a zero (o We can determine this has happened whenever our counter stays at `0`. In that case we need to send `0` to the output, and perform another "slap in the face": -[source,shell] +[source,bash] .... 0 ??? ??? ??? ??? ??? .... @@ -3645,7 +3645,7 @@ Suppose we want to build a pinhole camera to use the 4x5 inch film. The standard Our session might look like this: -[source,shell] +[source,bash] .... % pinhole @@ -3714,7 +3714,7 @@ Because 120 is a medium size film, we may name this file medium. We can set its permissions to execute, and run it as if it were a program: -[source,shell] +[source,bash] .... % chmod 755 medium % ./medium @@ -3722,14 +3722,14 @@ We can set its permissions to execute, and run it as if it were a program: UNIX(R) will interpret that last command as: -[source,shell] +[source,bash] .... % /usr/local/bin/pinhole -b -i ./medium .... It will run that command and display: -[source,shell] +[source,bash] .... 80 358 224 256 1562 11 30 219 137 128 586 9 @@ -3744,21 +3744,21 @@ It will run that command and display: Now, let us enter: -[source,shell] +[source,bash] .... % ./medium -c .... UNIX(R) will treat that as: -[source,shell] +[source,bash] .... % /usr/local/bin/pinhole -b -i ./medium -c .... That gives it two conflicting options: `-b` and `-c` (Use Bender's constant and use Connors' constant). We have programmed it so later options override early ones-our program will calculate everything using Connors' constant: -[source,shell] +[source,bash] .... 80 331 242 256 1826 11 30 203 148 128 685 9 @@ -3773,7 +3773,7 @@ That gives it two conflicting options: `-b` and `-c` (Use Bender's constant and We decide we want to go with Bender's constant after all. We want to save its values as a comma-separated file: -[source,shell] +[source,bash] .... % ./medium -b -e > bender % cat bender @@ -3817,7 +3817,7 @@ There is a major difference in the philosophy of design between MS-DOS(R) and UN This is NEVER guaranteed under UNIX(R). It is quite common for a UNIX(R) user to pipe and redirect program input and output: -[source,shell] +[source,bash] .... % program1 | program2 | program3 > file1 .... |