diff options
| author |   Bjørn Mork <bjorn@mork.no> | 2015-05-15 10:20:47 +0200 |
|---|---|---|
| committer | Bjørn Mork <bjorn@mork.no> | 2015-05-15 10:20:47 +0200 |
| commit | 73b16af8feec390afbabd9356d6e5e83c0390838 (patch) | |
| tree | 3730020ba2f9caeb9d7815a975af51830b51ce11 /docs | |
busybox: imported from http://www.busybox.net/downloads/busybox-1.13.3.tar.bz2busybox-1.13.3
Signed-off-by: Bjørn Mork <bjorn@mork.no>
Diffstat (limited to 'docs')
58 files changed, 12279 insertions, 0 deletions
diff --git a/docs/Serial-Programming-HOWTO.txt b/docs/Serial-Programming-HOWTO.txt new file mode 100644 index 0000000..0dfc8aa --- /dev/null +++ b/docs/Serial-Programming-HOWTO.txt @@ -0,0 +1,424 @@ +Downloaded from http://www.lafn.org/~dave/linux/Serial-Programming-HOWTO.txt +Seems to be somewhat old, but contains useful bits for getty.c hacking +============================================================================ + + The Linux Serial Programming HOWTO, Part 1 of 2 + By Vernon C. Hoxie + v2.0 10 September 1999 + + This document describes how to program communications with devices + over a serial port on a Linux box. + ______________________________________________________________________ + + Table of Contents + + 1. Copyright + + 2. Introduction + + 3. Opening + + 4. Commands + + 5. Changing Baud Rates + + 6. Additional Control Calls + + 6.1 Sending a "break". + 6.2 Hardware flow control. + 6.3 Flushing I/O buffers. + + 7. Modem control + + 8. Process Groups + + 8.1 Sessions + 8.2 Process Groups + 8.3 Controlling Terminal + 8.3.1 Get the foreground group process id. + 8.3.2 Set the foreground process group id of a terminal. + 8.3.3 Get process group id. + + 9. Lockfiles + + 10. Additional Information + + 11. Feedback + + ______________________________________________________________________ + + 1. Copyright + + The Linux Serial-Programming-HOWTO is copyright (C) 1997 by Vernon + Hoxie. Linux HOWTO documents may be reproduced and distributed in + whole or in part, in any medium physical or electronic, as long as + this copyright notice is retained on all copies. Commercial + redistribution is allowed and encouraged; however, the author would + like to be notified of any such distributions. + + All translations, derivative works, or aggregate works incorporating + this Linux HOWTO document must be covered under this copyright notice. + That is, you may not produce a derivative work from this HOWTO and + impose additional restrictions on its distribution. + + This version is a complete rewrite of the previous Serial-Programming- + HOWTO by Peter H. Baumann, <mailto:Peter.Baumann@dlr.de> + + 2. Introduction + + This HOWTO will attempt to give hints about how to write a program + which needs to access a serial port. Its principal focus will be on + the Linux implementation and what the meaning of the various library + functions available. + + Someone asked about which of several sequences of operations was + right. There is no absolute right way to accomplish an outcome. The + options available are too numerous. If your sequences produces the + desired results, then that is the right way for you. Another + programmer may select another set of options and get the same results. + His method is right for him. + + Neither of these methods may operate properly with some other + implementation of UNIX. It is strange that many of the concepts which + were implemented in the SYSV version have been dumped. Because UNIX + was developed by AT&T and much code has been generated on those + concepts, the AT&T version should be the standard to which others + should emulate. + + Now the standard is POSIX. + + It was once stated that the popularity of UNIX and C was that they + were created by programmers for programmers. Not by scholars who + insist on purity of style in deference to results and simplicity of + use. Not by committees with people who have diverse personal or + proprietary agenda. Now ANSI and POSIX have strayed from those + original clear and simply concepts. + + 3. Opening + + The various serial devices are opened just as any other file. + Although, the fopen(3) command may be used, the plain open(2) is + preferred. This call returns the file descriptor which is required + for the various commands that configure the interface. + + Open(2) has the format: + + #include <fcntl.h> + int open(char *path, int flags, [int mode]); + + In addition to the obvious O_RDWR, O_WRONLY and O_RDONLY, two + additional flags are available. These are O_NONBLOCK and O_NOCTTY. + Other flags listed in the open(2) manual page are not applicable to + serial devices. + + Normally, a serial device opens in "blocking" mode. This means that + the open() will not return until the Carrier Detect line from the port + is active, e.g. modem, is active. When opened with the O_NONBLOCK + flag set, the open() will return immediately regardless of the status + of the DCD line. The "blocking" mode also affects the read() call. + + The fcntl(2) command can be used to change the O_NONBLOCK flag anytime + after the device has been opened. + + The device driver and the data passing through it are controlled + according to settings in the struct termios. This structure is + defined in "/usr/include/termios.h". In the Linux tree, further + reference is made to "/usr/include/asm/termbits.h". + In blocking mode, a read(2) will block until data is available or a + signal is received. It is still subject to state of the ICANON flag. + + When the termios.c_lflag ICANON bit is set, input data is collected + into strings until a NL, EOF or EOL character is received. You can + define these in the termios.c_cc[] array. Also, ERASE and KILL + characters will operate on the incoming data before it is delivered to + the user. + + In non-canonical mode, incoming data is quanitified by use of the + c_cc[VMIN and c_cc[VTIME] values in termios.c_cc[]. + + Some programmers use the select() call to detect the completion of a + read(). This is not the best way of checking for incoming data. + Select() is part of the SOCKETS scheme and too complex for most + applications. + + A full explanation of the fields of the termios structure is contained + in termios(7) of the Users Manual. A version is included in Part 2 of + this HOWTO document. + + 4. Commands + + Changes to the struct termios are made by retrieving the current + settings, making the desired changes and transmitting the modified + structure back to the kernel. + + The historic means of communicating with the kernel was by use of the + ioctl(fd, COMMAND, arg) system call. Then the purists in the + computer industry decided that this was not genetically consistent. + Their argument was that the argument changed its stripes. Sometimes + it was an int, sometimes it was a pointer to int and other times it + was a pointer to struct termios. Then there were those times it was + empty or NULL. These variations are dependent upon the COMMAND. + + As a alternative, the tc* series of functions were concocted. + + These are: + + int tcgetattr(int filedes, struct termios *termios_p); + int tcsetattr(int filedes, int optional_actions, + const struct termios *termios_p); + + instead of: + + int ioctl(int filedes, int command, + struct termios *termios_p); + + where command is TCGETS or one of TCSETS, TCSETSW or TCSETSF. + + The TCSETS command is comparable to the TCSANOW optional_action for + the tc* version. These direct the kernel to adopt the changes + immediately. Other pairs are: + + command optional_action Meaning + TCSETSW TCSADRAIN Change after all output has drained. + TCSETSF TCSAFLUSH Change after all output has drained + then discard any input characters + not read. + + Since the return code from either the ioctl(2) or the tcsetattr(2) + commands only indicate that the command was processed by the kernel. + These do not indicate whether or not the changes were actually + accomplished. Either of these commands should be followed by a call + to: + + ioctl(fd, TCGETS, &new_termios); + + or: + + tcgetattr(fd, &new_termios); + + A user function which makes changes to the termios structure should + define two struct termios variables. One of these variables should + contain the desired configuration. The other should contain a copy of + the kernels version. Then after the desired configuration has been + sent to the kernel, another call should be made to retrieve the + kernels version. Then the two compared. + + Here is an example of how to add RTS/CTS flow control: + + struct termios my_termios; + struct termios new_termios; + + tcgetattr(fd, &my_termios); + my_termios.c_flag |= CRTSCTS; + tcsetattr(fd, TCSANOW, &my_termios); + tcgetattr(fd, &new_termios); + if (memcmp(my_termios, new_termios, + sizeof(my_termios)) != 0) { + /* do some error handling */ + } + + 5. Changing Baud Rates + + With Linux, the baud rate can be changed using a technique similar to + add/delete RTS/CTS. + + struct termios my_termios; + struct termios new_termios; + + tcgetattr(fd, &my_termios); + my_termios.c_flag &= ~CBAUD; + my_termios.c_flag |= B19200; + tcsetattr(fd, TCSANOW, &my_termios); + tcgetattr(fd, &new_termios); + if (memcmp(my_termios, new_termios, + sizeof(my_termios)) != 0) { + /* do some error handling */ + } + + POSIX adds another method. They define: + + speed_t cfgetispeed(const struct termios *termios_p); + speed_t cfgetospeed(const struct termios *termios_p); + + library calls to extract the current input or output speed from the + struct termios pointed to with *termio_p. This is a variable defined + in the calling process. In practice, the data contained in this + termios, should be obtained by the tcgetattr() call or an ioctl() call + using the TCGETS command. + + The companion library calls are: + + int cfsetispeed(struct termios *termios_p, speed_t speed); + int cfsetospeed(struct termios *termios_p, speed_t speed); + + which are used to change the value of the baud rate in the locally + defined *termios_p. Following either of these calls, either a call to + tcsetattr() or ioctl() with one of TCSETS, TCSETSW or TCSETSF as the + command to transmit the change to the kernel. + + The cf* commands are preferred for portability. Some weird Unices use + a considerably different format of termios. + + Most implementations of Linux use only the input speed for both input + and output. These functions are defined in the application program by + reference to <termios.h>. In reality, they are in + /usr/include/asm/termbits.h. + + 6. Additional Control Calls + + 6.1. Sending a "break". + + int ioctl(fd, TCSBRK, int arg); + int tcsendbreak(fd, int arg); + + Send a break: Here the action differs between the conventional + ioctl() call and the POSIX call. For the conventional call, an arg of + '0' sets the break control line of the UART for 0.25 seconds. For the + POSIX command, the break line is set for arg times 0.1 seconds. + + 6.2. Hardware flow control. + + int ioctl(fd, TCXONC, int action); + int tcflow(fd, int action); + + The action flags are: + + o TCOOFF 0 suspend output + + o TCOON 1 restart output + + o TCIOFF 2 transmit STOP character to suspend input + + o TCION 3 transmit START character to restart input + + 6.3. Flushing I/O buffers. + + int ioctl(fd, TCFLSH, queue_selector); + int tcflush(fd, queue_selector); + + The queue_selector flags are: + + o TCIFLUSH 0 flush any data not yet read from the input buffer + + o TCOFLUSH 1 flush any data written to the output buffer but not + yet transmitted + + o TCIOFLUSH 2 flush both buffers + + 7. Modem control + + The hardware modem control lines can be monitored or modified by the + ioctl(2) system call. A set of comparable tc* calls apparently do not + exist. The form of this call is: + + int ioctl(fd, COMMAND, (int *)flags); + + The COMMANDS and their action are: + + o TIOCMBIS turn on control lines depending upon which bits are set + in flags. + + o TIOCMBIC turn off control lines depending upon which bits are + unset in flags. + o TIOCMGET the appropriate bits are set in flags according to the + current status + + o TIOCMSET the state of the UART is changed according to which bits + are set/unset in 'flags' + + The bit pattern of flags refer to the following control lines: + + o TIOCM_LE Line enable + + o TIOCM_DTR Data Terminal Ready + + o TIOCM_RTS Request to send + + o TIOCM_ST Secondary transmit + + o TIOCM_SR Secondary receive + + o TIOCM_CTS Clear to send + + o TIOCM_CAR Carrier detect + + o TIOCM_RNG Ring + + o TIOCM_DSR Data set ready + + It should be noted that some of these bits are controlled by the modem + and the UART cannot change them but their status can be sensed by + TIOCMGET. Also, most Personal Computers do not provide hardware for + secondary transmit and receive. + + There are also a pair of ioctl() to monitor these lines. They are + undocumented as far as I have learned. The commands are TIOCMIWAIT + and TCIOGICOUNT. They also differ between versions of the Linux + kernel. + + See the lines.c file in my "serial_suite" for an example of how these + can be used see <ftp://scicom.alphacd.com/pub/linux/serial_suite> + + 8. Process Groups + + 8.1. Sessions + + 8.2. Process Groups + + Any newly created process inherits the Process Group of its creator. + The Process Group leader has the same PID as PGID. + + 8.3. Controlling Terminal + + There are a series of ioctl(2) and tc*(2) calls which can be used to + monitor or to change the process group to which the device is + attached. + + 8.3.1. Get the foreground group process id. + + If there is no foreground group, a number not representing an existing + process group is returned. On error, a -1 is returned and errno is + set. + + int ioctl(fd, TIOCGPGRP, (pid_t *)pid); + int tcgetpgrp(fd, (pid_t *)pid); + + 8.3.2. Set the foreground process group id of a terminal. + + The fd must be the controlling terminal and be associated with the + session of the calling process. + + int ioctl(fd, TIOCSPGRP, (pid_t *)pid); + int tcsetpgrp(fd, (pid_t *)pid); + + 8.3.3. Get process group id. + + int ioctl(fd, TIOCGPGRP, &(pid_t)pid); + int tcgetpgrp(fd, &(pid_t)pid); + + 9. Lockfiles + + Any process which accesses a serial device should first check for the + existence of lock file for the desired device. If such a lock lock + file exists, this means that the device may be in use by another + process. + + Check my "libdevlocks-x.x.tgz" at + <ftp://scicom.alphacdc.com/pub/linux> for an example of how these lock + files should be utilized. + + 10. Additional Information + + Check out my "serial_suite.tgz" for more information about programming + the serial ports at <mailto:vern@zebra.alphacdc.com>. There some + examples and some blurbs about setting up modems and comments about + some general considerations. + + 11. Feedback + + Please send me any corrections, questions, comments, suggestions, or + additional material. I would like to improve this HOWTO! Tell me + exactly what you don't understand, or what could be clearer. You can + reach me at <mailto:vern@zebra.alphacdc.com> via email. Please + include the version number of the Serial-Programming-HOWTO when + writing. diff --git a/docs/autodocifier.pl b/docs/autodocifier.pl new file mode 100755 index 0000000..576e312 --- /dev/null +++ b/docs/autodocifier.pl @@ -0,0 +1,307 @@ +#!/usr/bin/perl -w +# vi: set sw=4 ts=4: + +use strict; +use Getopt::Long; + +# collect lines continued with a '\' into an array +sub continuation { + my $fh = shift; + my @line; + + while (<$fh>) { + my $s = $_; + $s =~ s/\\\s*$//; + #$s =~ s/#.*$//; + push @line, $s; + last unless (/\\\s*$/); + } + return @line; +} + +# regex && eval away unwanted strings from documentation +sub beautify { + my $text = shift; + for (;;) { + my $text2 = $text; + $text =~ s/SKIP_\w+\(.*?"\s*\)//sxg; + $text =~ s/USE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; + $text =~ s/USAGE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; + last if ( $text2 eq $text ); + } + $text =~ s/"\s*"//sg; + my @line = split("\n", $text); + $text = join('', + map { + s/^\s*"//; + s/"\s*$//; + s/%/%%/g; + s/\$/\\\$/g; + s/\@/\\\@/g; + eval qq[ sprintf(qq{$_}) ] + } @line + ); + return $text; +} + +# generate POD for an applet +sub pod_for_usage { + my $name = shift; + my $usage = shift; + + # Sigh. Fixup the known odd-name applets. +# Perhaps we can use some of APPLET_ODDNAME from include/applets.h ? + $name =~ s/dpkg_deb/dpkg-deb/g; + $name =~ s/fsck_minix/fsck.minix/g; + $name =~ s/mkfs_minix/mkfs.minix/g; + $name =~ s/run_parts/run-parts/g; + $name =~ s/start_stop_daemon/start-stop-daemon/g; + $name =~ s/ether_wake/ether-wake/g; + + # make options bold + my $trivial = $usage->{trivial}; + if (!defined $usage->{trivial}) { + $trivial = ""; + } else { + $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg; + } + my @f0 = + map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ } + split("\n", (defined $usage->{full} ? $usage->{full} : "")); + + # add "\n" prior to certain lines to make indented + # lines look right + my @f1; + my $len = @f0; + for (my $i = 0; $i < $len; $i++) { + push @f1, $f0[$i]; + if (($i+1) != $len && $f0[$i] !~ /^\s/ && $f0[$i+1] =~ /^\s/) { + next if ($f0[$i] =~ /^$/); + push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s); + } + } + my $full = join("\n", @f1); + + # prepare notes if they exist + my $notes = (defined $usage->{notes}) + ? "$usage->{notes}\n\n" + : ""; + + # prepare examples if they exist + my $example = (defined $usage->{example}) + ? + "Example:\n\n" . + join ("\n", + map { "\t$_" } + split("\n", $usage->{example})) . "\n\n" + : ""; + + # Pad the name so that the applet name gets a line + # by itself in BusyBox.txt + my $spaces = 10 - length($name); + if ($spaces > 0) { + $name .= " " x $spaces; + } + + return + "=item B<$name>". + "\n\n$name $trivial\n\n". + "$full\n\n" . + "$notes" . + "$example" . + "\n\n" + ; +} + +# the keys are applet names, and +# the values will contain hashrefs of the form: +# +# { +# trivial => "...", +# full => "...", +# notes => "...", +# example => "...", +# } +my %docs; + + +# get command-line options + +my %opt; + +GetOptions( + \%opt, + "help|h", + "pod|p", + "verbose|v", +); + +if (defined $opt{help}) { + print + "$0 [OPTION]... [FILE]...\n", + "\t--help\n", + "\t--pod\n", + "\t--verbose\n", + ; + exit 1; +} + + +# collect documenation into %docs + +foreach (@ARGV) { + open(USAGE, $_) || die("$0: $_: $!"); + my $fh = *USAGE; + my ($applet, $type, @line); + while (<$fh>) { + if (/^#define (\w+)_(\w+)_usage/) { + $applet = $1; + $type = $2; + @line = continuation($fh); + my $doc = $docs{$applet} ||= { }; + my $text = join("\n", @line); + $doc->{$type} = beautify($text); + } + } +} + + +# generate structured documentation + +my $generator = \&pod_for_usage; + +my @names = sort keys %docs; +my $line = "\t[, [[, "; +for (my $i = 0; $i < $#names; $i++) { + if (length ($line.$names[$i]) >= 65) { + print "$line\n\t"; + $line = ""; + } + $line .= "$names[$i], "; +} +print $line . $names[-1]; + +print "\n\n=head1 COMMAND DESCRIPTIONS\n"; +print "\n=over 4\n\n"; + +foreach my $applet (@names) { + print $generator->($applet, $docs{$applet}); +} + +exit 0; + +__END__ + +=head1 NAME + +autodocifier.pl - generate docs for busybox based on usage.h + +=head1 SYNOPSIS + +autodocifier.pl [OPTION]... [FILE]... + +Example: + + ( cat docs/busybox_header.pod; \ + docs/autodocifier.pl usage.h; \ + cat docs/busybox_footer.pod ) > docs/busybox.pod + +=head1 DESCRIPTION + +The purpose of this script is to automagically generate +documentation for busybox using its usage.h as the original source +for content. It used to be that same content has to be duplicated +in 3 places in slightly different formats -- F<usage.h>, +F<docs/busybox.pod>. This was tedious and error-prone, so it was +decided that F<usage.h> would contain all the text in a +machine-readable form, and scripts could be used to transform this +text into other forms if necessary. + +F<autodocifier.pl> is one such script. It is based on a script by +Erik Andersen <andersen@codepoet.org> which was in turn based on a +script by Mark Whitley <markw@codepoet.org> + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +This displays the help message. + +=item B<--pod> + +Generate POD (this is the default) + +=item B<--verbose> + +Be verbose (not implemented) + +=back + +=head1 FORMAT + +The following is an example of some data this script might parse. + + #define length_trivial_usage \ + "STRING" + #define length_full_usage \ + "Prints out the length of the specified STRING." + #define length_example_usage \ + "$ length Hello\n" \ + "5\n" + +Each entry is a cpp macro that defines a string. The macros are +named systematically in the form: + + $name_$type_usage + +$name is the name of the applet. $type can be "trivial", "full", "notes", +or "example". Every documentation macro must end with "_usage". + +The definition of the types is as follows: + +=over 4 + +=item B<trivial> + +This should be a brief, one-line description of parameters that +the command expects. This will be displayed when B<-h> is issued to +a command. I<REQUIRED> + +=item B<full> + +This should contain descriptions of each option. This will also +be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP +is disabled. I<REQUIRED> + +=item B<notes> + +This is documentation that is intended to go in the POD or SGML, but +not be printed when a B<-h> is given to a command. To see an example +of notes being used, see init_notes_usage in F<usage.h>. I<OPTIONAL> + +=item B<example> + +This should be an example of how the command is actually used. +This will not be printed when a B<-h> is given to a command -- it +will only be included in the POD or SGML documentation. I<OPTIONAL> + +=back + +=head1 FILES + +F<usage.h> + +=head1 COPYRIGHT + +Copyright (c) 2001 John BEPPU. All rights reserved. This program is +free software; you can redistribute it and/or modify it under the same +terms as Perl itself. + +=head1 AUTHOR + +John BEPPU <b@ax9.org> + +=cut + diff --git a/docs/busybox.net/FAQ.html b/docs/busybox.net/FAQ.html new file mode 100644 index 0000000..5ff879d --- /dev/null +++ b/docs/busybox.net/FAQ.html @@ -0,0 +1,1146 @@ +<!--#include file="header.html" --> + +<h3>Frequently Asked Questions</h3> + +This is a collection of some of the more frequently asked questions +about BusyBox. Some of the questions even have answers. If you +have additions to this FAQ document, we would love to add them, + +<h2>General questions</h2> +<ol> +<li><a href="#getting_started">How can I get started using BusyBox?</a></li> +<li><a href="#configure">How do I configure busybox?</a></li> +<li><a href="#build">How do I build BusyBox with a cross-compiler?</a></li> +<li><a href="#build_system">How do I build a BusyBox-based system?</a></li> +<li><a href="#kernel">Which Linux kernel versions are supported?</a></li> +<li><a href="#arch">Which architectures does BusyBox run on?</a></li> +<li><a href="#libc">Which C libraries are supported?</a></li> +<li><a href="#commercial">Can I include BusyBox as part of the software on my device?</a></li> +<li><a href="#external">Where can I find other small utilities since busybox does not include the features I want?</a></li> +<li><a href="#demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></li> +<li><a href="#helpme">I need help with BusyBox! What should I do?</a></li> +<li><a href="#contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></li> +</ol> + +<h2>Troubleshooting</h2> +<ol> +<li><a href="#bugs">I think I found a bug in BusyBox! What should I do?!</a></li> +<li><a href="#backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</a></li> +<li><a href="#init">Busybox init isn't working!</a></li> +<li><a href="#sed">I can't configure busybox on my system.</a></li> +<li><a href="#job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></li> +</ol> + +<h2>Misc. questions</h2> +<ol> + <li><a href="#tz">How do I change the time zone in busybox?</a></li> +</ol> + +<h2>Programming questions</h2> +<ol> + <li><a href="#goals">What are the goals of busybox?</a></li> + <li><a href="#design">What is the design of busybox?</a></li> + <li><a href="#source">How is the source code organized?</a> + <ul> + <li><a href="#source_applets">The applet directories.</a></li> + <li><a href="#source_libbb">The busybox shared library (libbb)</a></li> + </ul> + </li> + <li><a href="#optimize">I want to make busybox even smaller, how do I go about it?</a></li> + <li><a href="#adding">Adding an applet to busybox</a></li> + <li><a href="#standards">What standards does busybox adhere to?</a></li> + <li><a href="#portability">Portability.</a></li> + <li><a href="#tips">Tips and tricks.</a> + <ul> + <li><a href="#tips_encrypted_passwords">Encrypted Passwords</a></li> + <li><a href="#tips_vfork">Fork and vfork</a></li> + <li><a href="#tips_short_read">Short reads and writes</a></li> + <li><a href="#tips_memory">Memory used by relocatable code, PIC, and static linking.</a></li> + <li><a href="#tips_kernel_headers">Including Linux kernel headers.</a></li> + </ul> + </li> + <li><a href="#who">Who are the BusyBox developers?</a></li> +</ol> + + +<hr /> +<h1>General questions</h1> + +<hr /> +<h2><a name="getting_started">How can I get started using BusyBox?</a></h2> + +<p> If you just want to try out busybox without installing it, download the + tarball, extract it, run "make defconfig", and then run "make". +</p> +<p> + This will create a busybox binary with almost all features enabled. To try + out a busybox applet, type "./busybox [appletname] [options]", for + example "./busybox ls -l" or "./busybox cat LICENSE". Type "./busybox" + to see a command list, and "busybox appletname --help" to see a brief + usage message for a given applet. +</p> +<p> + BusyBox uses the name it was invoked under to determine which applet is + being invoked. (Try "mv busybox ls" and then "./ls -l".) Installing + busybox consists of creating symlinks (or hardlinks) to the busybox + binary for each applet in busybox, and making sure these links are in + the shell's command $PATH. The special applet name "busybox" (or with + any optional suffix, such as "busybox-static") uses the first argument + to determine which applet to run, as shown above. +</p> +<p> + BusyBox also has a feature called the + <a name="standalone_shell">"standalone shell"</a>, where the busybox + shell runs any built-in applets before checking the command path. This + feature is also enabled by "make allyesconfig", and to try it out run + the command line "PATH= ./busybox ash". This will blank your command path + and run busybox as your command shell, so the only commands it can find + (without an explicit path such as /bin/ls) are the built-in busybox ones. + This is another good way to see what's built into busybox. + Note that the standalone shell requires CONFIG_BUSYBOX_EXEC_PATH + to be set appropriately, depending on whether or not /proc/self/exe is + available or not. If you do not have /proc, then point that config option + to the location of your busybox binary, usually /bin/busybox. + (So if you set it to /proc/self/exe, and happen to be able to chroot into + your rootfs, you must mount /proc beforehand.) +</p> +<p> + A typical indication that you set CONFIG_BUSYBOX_EXEC_PATH to proc but + forgot to mount proc is: +<pre> +$ /bin/echo $PATH +/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11 +$ echo $PATH +/bin/sh: echo: not found +</pre> + +<hr /> +<h2><a name="configure">How do I configure busybox?</a></h2> + +<p> Busybox is configured similarly to the linux kernel. Create a default + configuration and then run "make menuconfig" to modify it. The end + result is a .config file that tells the busybox build process what features + to include. So instead of "./configure; make; make install" the equivalent + busybox build would be "make defconfig; make; make install". +</p> + +<p> Busybox configured with all features enabled is a little under a megabyte + dynamically linked on x86. To create a smaller busybox, configure it with + fewer features. Individual busybox applets cost anywhere from a few + hundred bytes to tens of kilobytes. Disable unneeded applets to save, + space, using menuconfig. +</p> + +<p>The most important busybox configurators are:</p> + +<ul> +<li><p>make <b>defconfig</b> - Create the maximum "sane" configuration. This +enables almost all features, minus things like debugging options and features +that require changes to the rest of the system to work (such as selinux or +devfs device names). Use this if you want to start from a full-featured +busybox and remove features until it's small enough.</p></li> +<li><p>make <b>allnoconfig</b> - Disable everything. This creates a tiny version +of busybox that doesn't do anything. Start here if you know exactly what +you want and would like to select only those features.</p></li> +<li><p>make <b>menuconfig</b> - Interactively modify a .config file through a +multi-level menu interface. Use this after one of the previous two.</p></li> +</ul> + +<p>Some other configuration options are:</p> +<ul> +<li><p>make <b>oldconfig</b> - Update an old .config file for a newer version +of busybox.</p></li> +<li><p>make <b>allyesconfig</b> - Select absolutely everything. This creates +a statically linked version of busybox full of debug code, with dependencies on +selinux, using devfs names... This makes sure everything compiles. Whether +or not the result would do anything useful is an open question.</p></li> +<li><p>make <b>allbareconfig</b> - Select all applets but disable all sub-features +within each applet. More build coverage testing.</p></li> +<li><p>make <b>randconfig</b> - Create a random configuration for test purposes.</p></li> +</ul> + +<p> Menuconfig modifies your .config file through an interactive menu where you can enable or disable + busybox features, and get help about each feature. + +<p> + To build a smaller busybox binary, run "make menuconfig" and disable the + features you don't need. (Or run "make allnoconfig" and then use + menuconfig to add just the features you need. Don't forget to recompile + with "make" once you've finished configuring.) +</p> + +<hr /> +<h2><a name="build">How do I build BusyBox with a cross-compiler?</a></h2> + +<p> + To build busybox with a cross-compiler, specify CROSS_COMPILE=<prefix>. +</p> +<p> + CROSS_COMPILE specifies the prefix used for all executables used + during compilation. Only gcc and related binutils executables + are prefixed with $(CROSS_COMPILE) in the makefiles. + CROSS_COMPILE can be set on the command line: +</p> +<pre> + make CROSS_COMPILE=arm-linux-uclibcgnueabi- +</pre> +<p> + Alternatively CROSS_COMPILE can be set in the environment. + Default value for CROSS_COMPILE is not to prefix executables. +</p> +<p> + To store the cross-compiler in your .config, set the variable + CONFIG_CROSS_COMPILER_PREFIX accordingly in menuconfig or by + editing the .config file. +</p> + +<hr /> +<h2><a name="build_system">How do I build a BusyBox-based system?</a></h2> + +<p> + BusyBox is a package that replaces a dozen standard packages, but it is + not by itself a complete bootable system. Building an entire Linux + distribution from source is a bit beyond the scope of this FAQ, but it + understandably keeps cropping up on the mailing list, so here are some + pointers. +</p> +<p> + Start by learning how to strip a working system down to the bare essentials + needed to run one or two commands, so you know what it is you actually + need. An excellent practical place to do + this is the <a href="http://www.tldp.org/HOWTO/Bootdisk-HOWTO/">Linux + BootDisk Howto</a>, or for a more theoretical approach try + <a href="http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html">From + PowerUp to Bash Prompt</a>. +</p> +<p> + To learn how to build a working Linux system entirely from source code, + the place to go is the <a href="http://www.linuxfromscratch.org/">Linux + From Scratch</a> project. They have an entire book of step-by-step + instructions you can + <a href="http://www.linuxfromscratch.org/lfs/view/stable/">read online</a> + or + <a href="http://www.linuxfromscratch.org/lfs/downloads/stable/">download</a>. + Be sure to check out the other sections of their main page, including + Beyond Linux From Scratch, Hardened Linux From Scratch, their Hints + directory, and their LiveCD project. (They also have mailing lists which + are better sources of answers to Linux-system building questions than + the busybox list.) +</p> +<p> + If you want an automated yet customizable system builder which produces + a BusyBox and uClibc based system, try + <a href="http://buildroot.uclibc.org/">buildroot</a>, which is + another project by the maintainer of the uClibc (Erik Andersen). + Download the tarball, extract it, unset CC, make. + For more instructions, see the website. +</p> + +<hr /> +<h2><a name="kernel">Which Linux kernel versions are supported?</a></h2> + +<p> + Full functionality requires Linux 2.4.x or better. (Earlier versions may + still work, but are no longer regularly tested.) A large fraction of the + code should run on just about anything. While the current code is fairly + Linux specific, it should be fairly easy to port the majority of the code + to support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you + are into that sort of thing). +</p> + +<hr /> +<h2><a name="arch">Which architectures does BusyBox run on?</a></h2> + +<p> + BusyBox in general will build on any architecture supported by gcc. + Kernel module loading for 2.4 Linux kernels is currently + limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC, + S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels. +</p> +<p> + With 2.6.x kernels, module loading support should work on all architectures. +</p> + +<hr /> +<h2><a name="libc">Which C libraries are supported?</a></h2> + +<p> + On Linux, BusyBox releases are tested against uClibc (0.9.27 or later) and + glibc (2.2 or later). Both should provide full functionality with busybox, + and if you find a bug we want to hear about it. +</p> +<p> + Linux-libc5 is no longer maintained (and has no known advantages over + uClibc), dietlibc is known to have numerous unfixed bugs, and klibc is + missing too many features to build BusyBox. If you require a small C + library for Linux, the busybox developers recommend uClibc. +</p> +<p> + Some BusyBox applets have been built and run under a combination + of newlib and libgloss (see + <a href="http://www.busybox.net/lists/busybox/2005-March/013759.html">this thread</a>). + This is still experimental, but may be supported in a future release. +</p> + +<hr /> +<h2><a name="commercial">Can I include BusyBox as part of the software on my device?</a></h2> + +<p> + Yes. As long as you <a href="http://busybox.net/license.html">fully comply + with the generous terms of the GPL BusyBox license</a> you can ship BusyBox + as part of the software on your device. +</p> + +<hr /> +<h2><a name="external">Where can I find other small utilities since busybox + does not include the features i want?</a></h2> + +<p> + we maintain such a <a href="tinyutils.html">list</a> on this site! +</p> + +<hr /> +<h2><a name="demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></h2> + +<p> + You have not paid us a single cent and yet you still have the product of + many years of our work. We are not your slaves! We work on BusyBox + because we find it useful and interesting. If you go off flaming us, we + will ignore you. + +<hr /> +<h2><a name="helpme">I need help with BusyBox! What should I do?</a></h2> + +<p> + If you find that you need help with BusyBox, you can ask for help on the + BusyBox mailing list at busybox@busybox.net.</p> + +<p> In addition to the mailing list, Erik Andersen (andersee), Manuel Nova + (mjn3), Rob Landley (landley), Mike Frysinger (SpanKY), + Bernhard Reutner-Fischer (blindvt), and other long-time BusyBox developers + are known to hang out on the uClibc IRC channel: #uclibc on + irc.freenode.net. There is a + <a href="http://ibot.Rikers.org/%23uclibc/">web archive of + daily logs of the #uclibc IRC channel</a> going back to 2002. +</p> + +<p> + <b>Please do not send private email to Rob, Erik, Manuel, or the other + BusyBox contributors asking for private help unless you are planning on + paying for consulting services.</b> +</p> + +<p> + When we answer questions on the BusyBox mailing list, it helps everyone + since people with similar problems in the future will be able to get help + by searching the mailing list archives. Private help is reserved as a paid + service. If you need to use private communication, or if you are serious + about getting timely assistance with BusyBox, you should seriously consider + paying for consulting services. +</p> + +<hr /> +<h2><a name="contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></h2> + +<p> + Yes we are. The easy way to sponsor a new feature is to post an offer on + the mailing list to see who's interested. You can also email the project's + maintainer and ask them to recommend someone. +</p> + +<hr /> +<h1>Troubleshooting</h1> + +<hr /> +<h2><a name="bugs">I think I found a bug in BusyBox! What should I do?</a></h2> + +<p> + If you simply need help with using or configuring BusyBox, please submit a + detailed description of your problem to the BusyBox mailing list at <a + href="mailto:busybox@busybox.net">busybox@busybox.net</a>. + Please do not send email to individual developers asking + for private help unless you are planning on paying for consulting services. + When we answer questions on the BusyBox mailing list, it helps everyone, + while private answers help only you... +</p> + +<p> + Bug reports and new feature patches sometimes get lost when posted to the + mailing list, because the developers of BusyBox are busy people and have + only so much they can keep in their brains at a time. You can post a + polite reminder after 2-3 days without offending anybody. If that doesn't + result in a solution, please use the + <a href="http://bugs.busybox.net/">BusyBox Bug + and Patch Tracking System</a> to submit a detailed explanation and we'll + get to it as soon as we can. +</p> + +<p> + Note that bugs entered into the bug system without being mentioned on the + mailing list first may languish there for months before anyone even notices + them. We generally go through the bug system when preparing for new + development releases, to see what fell through the cracks while we were + off writing new features. (It's a fast/unreliable vs slow/reliable thing. + Saves retransits, but the latency sucks.) +</p> + +<hr /> +<h2><a name="backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</a></h2> + +<p>Variants of this one get asked a lot.</p> + +<p>The purpose of the BusyBox mailing list is to develop and improve BusyBox, +and we're happy to respond to our users' needs. But if you're coming to the +list for free tech support we're going to ask you to upgrade to a current +version before we try to diagnose your problem.</p> + +<p>If you're building BusyBox 0.50 with uClibc 0.9.19 and gcc 1.27 there's a +fairly large chance that whatever problem you're seeing has already been fixed. +To get that fix, all you have to do is upgrade to a newer version. If you +don't at least _try_ that, you're wasting our time.</p> + +<p>The volunteers are happy to fix any bugs you point out in the current +versions because doing so helps everybody and makes the project better. We +want to make the current version work for you. But diagnosing, debugging, and +backporting fixes to old versions isn't something we do for free, because it +doesn't help anybody but you. The cost of volunteer tech support is using a +reasonably current version of the project.</p> + +<p>If you don't want to upgrade, you have the complete source code and thus +the ability to fix it yourself, or hire a consultant to do it for you. If you +got your version from a vendor who still supports the older version, they can +help you. But there are limits as to what the volunteers will feel obliged to +do for you.</p> + +<p>As a rule of thumb, volunteers will generally answer polite questions about +a given version for about three years after its release before it's so old +we don't remember the answer off the top of our head. And if you want us to +put any _effort_ into tracking it down, we want you to put in a little effort +of your own by confirming it's still a problem with the current version. It's +also hard for us to fix a problem of yours if we can't reproduce it because +we don't have any systems running an environment that old.</p> + +<p>A consultant will happily set up a special environment just to reproduce +your problem, and you can always ask on the list if any of the developers +have consulting rates.</p> + +<hr /> +<h2><a name="init">Busybox init isn't working!</a></h2> + +<p> + Init is the first program that runs, so it might be that no programs are + working on your new system because of a problem with your cross-compiler, + kernel, console settings, shared libraries, root filesystem... To rule all + that out, first build a statically linked version of the following "hello + world" program with your cross compiler toolchain: +</p> +<pre> +#include <stdio.h> + +int main(int argc, char *argv) +{ + printf("Hello world!\n"); + sleep(999999999); +} +</pre> + +<p> + Now try to boot your device with an "init=" argument pointing to your + hello world program. Did you see the hello world message? Until you + do, don't bother messing with busybox init. +</p> + +<p> + Once you've got it working statically linked, try getting it to work + dynamically linked. Then read the FAQ entry <a href="#build_system">How + do I build a BusyBox-based system?</a>, and the + <a href="/downloads/BusyBox.html#item_init">documentation for BusyBox + init</a>. +</p> + +<hr /> +<h2><a name="sed">I can't configure busybox on my system.</a></h2> + +<p> + Configuring Busybox depends on a recent version of sed. Older + distributions (Red Hat 7.2, Debian 3.0) may not come with a + usable version. Luckily BusyBox can use its own sed to configure itself, + although this leads to a bit of a chicken and egg problem. + You can work around this by hand-configuring busybox to build with just + sed, then putting that sed in your path to configure the rest of busybox + with, like so: +</p> + +<pre> + tar xvjf sources/busybox-x.x.x.tar.bz2 + cd busybox-x.x.x + make allnoconfig + make include/bb_config.h + echo "CONFIG_SED=y" >> .config + echo "#undef ENABLE_SED" >> include/bb_config.h + echo "#define ENABLE_SED 1" >> include/bb_config.h + make + mv busybox sed + export PATH=`pwd`:"$PATH" +</pre> + +<p>Then you can run "make defconfig" or "make menuconfig" normally.</p> + +<hr /> +<h2><a name="job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></h2> + +<p> + Job control will be turned off since your shell can not obtain a controlling + terminal. This typically happens when you run your shell on /dev/console. + The kernel will not provide a controlling terminal on the /dev/console + device. Your should run your shell on a normal tty such as tty1 or ttyS0 + and everything will work perfectly. If you <em>REALLY</em> want your shell + to run on /dev/console, then you can hack your kernel (if you are into that + sortof thing) by changing drivers/char/tty_io.c to change the lines where + it sets "noctty = 1;" to instead set it to "0". I recommend you instead + run your shell on a real console... +</p> + +<hr /> +<h1>Misc. questions</h1> + +<hr /> +<h2><a name="tz">How do I change the time zone in busybox?</a></h2> + +<p>Busybox has nothing to do with the timezone. Please consult your libc +documentation. (<a href="http://google.com/search?q=uclibc+glibc+timezone">http://google.com/search?q=uclibc+glibc+timezone</a>).</p> + +<hr /> +<h1>Development</h1> + +<hr /> +<h2><a name="goals">What are the goals of busybox?</a></h2> + +<p>Busybox aims to be the smallest and simplest correct implementation of the +standard Linux command line tools. First and foremost, this means the +smallest executable size we can manage. We also want to have the simplest +and cleanest implementation we can manage, be <a href="#standards">standards +compliant</a>, minimize run-time memory usage (heap and stack), run fast, and +take over the world.</p> + +<hr /> +<h2><a name="design">What is the design of busybox?</a></h2> + +<p>Busybox is like a swiss army knife: one thing with many functions. +The busybox executable can act like many different programs depending on +the name used to invoke it. Normal practice is to create a bunch of symlinks +pointing to the busybox binary, each of which triggers a different busybox +function. (See <a href="FAQ.html#getting_started">getting started</a> in the +FAQ for more information on usage, and <a href="BusyBox.html">the +busybox documentation</a> for a list of symlink names and what they do.) + +<p>The "one binary to rule them all" approach is primarily for size reasons: a +single multi-purpose executable is smaller then many small files could be. +This way busybox only has one set of ELF headers, it can easily share code +between different apps even when statically linked, it has better packing +efficiency by avoding gaps between files or compression dictionary resets, +and so on.</p> + +<p>Work is underway on new options such as "make standalone" to build separate +binaries for each applet, and a "libbb.so" to make the busybox common code +available as a shared library. Neither is ready yet at the time of this +writing.</p> + +<a name="source"></a> + +<hr /> +<h2><a name="source_applets">The applet directories</a></h2> + +<p>The directory "applets" contains the busybox startup code (applets.c and +busybox.c), and several subdirectories containing the code for the individual +applets.</p> + +<p>Busybox execution starts with the main() function in applets/busybox.c, +which sets the global variable applet_name to argv[0] and calls +run_applet_and_exit() in applets/applets.c. That uses the applets[] array +(defined in include/busybox.h and filled out in include/applets.h) to +transfer control to the appropriate APPLET_main() function (such as +cat_main() or sed_main()). The individual applet takes it from there.</p> + +<p>This is why calling busybox under a different name triggers different +functionality: main() looks up argv[0] in applets[] to get a function pointer +to APPLET_main().</p> + +<p>Busybox applets may also be invoked through the multiplexor applet +"busybox" (see busybox_main() in libbb/appletlib.c), and through the +standalone shell (grep for STANDALONE_SHELL in applets/shell/*.c). +See <a href="FAQ.html#getting_started">getting started</a> in the +FAQ for more information on these alternate usage mechanisms, which are +just different ways to reach the relevant APPLET_main() function.</p> + +<p>The applet subdirectories (archival, console-tools, coreutils, +debianutils, e2fsprogs, editors, findutils, init, loginutils, miscutils, +modutils, networking, procps, shell, sysklogd, and util-linux) correspond +to the configuration sub-menus in menuconfig. Each subdirectory contains the +code to implement the applets in that sub-menu, as well as a Config.in +file defining that configuration sub-menu (with dependencies and help text +for each applet), and the makefile segment (Makefile.in) for that +subdirectory.</p> + +<p>The run-time --help is stored in usage_messages[], which is initialized at +the start of applets/applets.c and gets its help text from usage.h. During the +build this help text is also used to generate the BusyBox documentation (in +html, txt, and man page formats) in the docs directory. See +<a href="#adding">adding an applet to busybox</a> for more +information.</p> + +<hr /> +<h2><a name="source_libbb"><b>libbb</b></a></h2> + +<p>Most non-setup code shared between busybox applets lives in the libbb +directory. It's a mess that evolved over the years without much auditing +or cleanup. For anybody looking for a great project to break into busybox +development with, documenting libbb would be both incredibly useful and good +experience.</p> + +<p>Common themes in libbb include allocation functions that test +for failure and abort the program with an error message so the caller doesn't +have to test the return value (xmalloc(), xstrdup(), etc), wrapped versions +of open(), close(), read(), and write() that test for their own failures +and/or retry automatically, linked list management functions (llist.c), +command line argument parsing (getopt32.c), and a whole lot more.</p> + +<hr /> +<h2><a name="optimize">I want to make busybox even smaller, how do I go about it?</a></h2> + +<p> + To conserve bytes it's good to know where they're being used, and the + size of the final executable isn't always a reliable indicator of + the size of the components (since various structures are rounded up, + so a small change may not even be visible by itself, but many small + savings add up). +</p> + +<p> The busybox Makefile builds two versions of busybox, one of which + (busybox_unstripped) has extra information that various analysis tools + can use. (This has nothing to do with CONFIG_DEBUG, leave that off + when trying to optimize for size.) +</p> + +<p> The <b>"make bloatcheck"</b> option uses Matt Mackall's bloat-o-meter + script to compare two versions of busybox (busybox_unstripped vs + busybox_old), and report which symbols changed size and by how much. + To use it, first build a base version with <b>"make baseline"</b>. + (This creates busybox_old, which should have the original sizes for + comparison purposes.) Then build the new version with your changes + and run "make bloatcheck" to see the size differences from the old + version. +</p> +<p> + The first line of output has totals: how many symbols were added or + removed, how many symbols grew or shrank, the number of bytes added + and number of bytes removed by these changes, and finally the total + number of bytes difference between the two files. The remaining + lines show each individual symbol, the old and new sizes, and the + increase or decrease in size (which results are sorted by). +</p> +<p> + The <b>"make sizes"</b> option produces raw symbol size information for + busybox_unstripped. This is the output from the "nm --size-sort" + command (see "man nm" for more information), and is the information + bloat-o-meter parses to produce the comparison report above. For + defconfig, this is a good way to find the largest symbols in the tree + (which is a good place to start when trying to shrink the code). To + take a closer look at individual applets, configure busybox with just + one applet (run "make allnoconfig" and then switch on a single applet + with menuconfig), and then use "make sizes" to see the size of that + applet's components. +</p> +<p> + The "showasm" command (in the scripts directory) produces an assembly + dump of a function, providing a closer look at what changed. Try + "scripts/showasm busybox_unstripped" to list available symbols, and + "scripts/showasm busybox_unstripped symbolname" to see the assembly + for a sepecific symbol. +</p> + +<hr /> +<h2><a name="adding">Adding an applet to busybox</a></h2> + +<p>To add a new applet to busybox, first pick a name for the applet and +a corresponding CONFIG_NAME. Then do this:</p> + +<ul> +<li>Figure out where in the busybox source tree your applet best fits, +and put your source code there. Be sure to use APPLET_main() instead +of main(), where APPLET is the name of your applet.</li> + +<li>Add your applet to the relevant Config.in file (which file you add +it to determines where it shows up in "make menuconfig"). This uses +the same general format as the linux kernel's configuration system.</li> + +<li>Add your applet to the relevant Makefile.in file (in the same +directory as the Config.in you chose), using the existing entries as a +template and the same CONFIG symbol as you used for Config.in. (Don't +forget "needlibm" or "needcrypt" if your applet needs libm or +libcrypt.)</li> + +<li>Add your applet to "include/applets.h", using one of the existing +entries as a template. (Note: this is in alphabetical order. Applets +are found via binary search, and if you add an applet out of order it +won't work.)</li> + +<li>Add your applet's runtime help text to "include/usage.h". You need +at least appname_trivial_usage (the minimal help text, always included +in the busybox binary when this applet is enabled) and appname_full_usage +(extra help text included in the busybox binary with +CONFIG_FEATURE_VERBOSE_USAGE is enabled), or it won't compile. +The other two help entry types (appname_example_usage and +appname_notes_usage) are optional. They don't take up space in the binary, +but instead show up in the generated documentation (BusyBox.html, +BusyBox.txt, and the man page BusyBox.1).</li> + +<li>Run menuconfig, switch your applet on, compile, test, and fix the +bugs. Be sure to try both "allyesconfig" and "allnoconfig" (and +"allbareconfig" if relevant).</li> + +</ul> + +<hr /> +<h2><a name="standards">What standards does busybox adhere to?</a></h2> + +<p>The standard we're paying attention to is the "Shell and Utilities" +portion of the <a href="http://www.opengroup.org/onlinepubs/009695399/">Open +Group Base Standards</a> (also known as the Single Unix Specification version +3 or SUSv3). Note that paying attention isn't necessarily the same thing as +following it.</p> + +<p>SUSv3 doesn't even mention things like init, mount, tar, or losetup, nor +commonly used options like echo's '-e' and '-n', or sed's '-i'. Busybox is +driven by what real users actually need, not the fact the standard believes +we should implement ed or sccs. For size reasons, we're unlikely to include +much internationalization support beyond UTF-8, and on top of all that, our +configuration menu lets developers chop out features to produce smaller but +very non-standard utilities.</p> + +<p>Also, Busybox is aimed primarily at Linux. Unix standards are interesting +because Linux tries to adhere to them, but portability to dozens of platforms +is only interesting in terms of offering a restricted feature set that works +everywhere, not growing dozens of platform-specific extensions. Busybox +should be portable to all hardware platforms Linux supports, and any other +similar operating systems that are easy to do and won't require much +maintenance.</p> + +<p>In practice, standards compliance tends to be a clean-up step once an +applet is otherwise finished. When polishing and testing a busybox applet, +we ensure we have at least the option of full standards compliance, or else +document where we (intentionally) fall short.</p> + +<hr /> +<h2><a name="portability">Portability.</a></h2> + +<p>Busybox is a Linux project, but that doesn't mean we don't have to worry +about portability. First of all, there are different hardware platforms, +different C library implementations, different versions of the kernel and +build toolchain... The file "include/platform.h" exists to centralize and +encapsulate various platform-specific things in one place, so most busybox +code doesn't have to care where it's running.</p> + +<p>To start with, Linux runs on dozens of hardware platforms. We try to test +each release on x86, x86-64, arm, power pc, and mips. (Since qemu can handle +all of these, this isn't that hard.) This means we have to care about a number +of portability issues like endianness, word size, and alignment, all of which +belong in platform.h. That header handles conditional #includes and gives +us macros we can use in the rest of our code. At some point in the future +we might grow a platform.c, possibly even a platform subdirectory. As long +as the applets themselves don't have to care.</p> + +<p>On a related note, we made the "default signedness of char varies" problem +go away by feeding the compiler -funsigned-char. This gives us consistent +behavior on all platforms, and defaults to 8-bit clean text processing (which +gets us halfway to UTF-8 support). NOMMU support is less easily separated +(see the tips section later in this document), but we're working on it.</p> + +<p>Another type of portability is build environments: we unapologetically use +a number of gcc and glibc extensions (as does the Linux kernel), but these have +been picked up by packages like uClibc, TCC, and Intel's C Compiler. As for +gcc, we take advantage of newer compiler optimizations to get the smallest +possible size, but we also regression test against an older build environment +using the Red Hat 9 image at "http://busybox.net/downloads/qemu". This has a +2.4 kernel, gcc 3.2, make 3.79.1, and glibc 2.3, and is the oldest +build/deployment environment we still put any effort into maintaining. (If +anyone takes an interest in older kernels you're welcome to submit patches, +but the effort would probably be better spent +<a href="http://www.selenic.com/linux-tiny/">trimming +down the 2.6 kernel</a>.) Older gcc versions than that are uninteresting since +we now use c99 features, although +<a href="http://fabrice.bellard.free.fr/tcc/">tcc</a> might be worth a +look.</p> + +<p>We also test busybox against the current release of uClibc. Older versions +of uClibc aren't very interesting (they were buggy, and uClibc wasn't really +usable as a general-purpose C library before version 0.9.26 anyway).</p> + +<p>Other unix implementations are mostly uninteresting, since Linux binaries +have become the new standard for portable Unix programs. Specifically, +the ubiquity of Linux was cited as the main reason the Intel Binary +Compatability Standard 2 died, by the standards group organized to name a +successor to ibcs2: <a href="http://www.telly.org/86open/">the 86open +project</a>. That project disbanded in 1999 with the endorsement of an +existing standard: Linux ELF binaries. Since then, the major players at the +time (such as <a +href="http://www-03.ibm.com/servers/aix/products/aixos/linux/index.html">AIX</a>, <a +href="http://www.sun.com/software/solaris/ds/linux_interop.jsp#3">Solaris</a>, and +<a href="http://www.onlamp.com/pub/a/bsd/2000/03/17/linuxapps.html">FreeBSD</a>) +have all either grown Linux support or folded.</p> + +<p>The major exceptions are newcomer MacOS X, some embedded environments +(such as newlib+libgloss) which provide a posix environment but not a full +Linux environment, and environments like Cygwin that provide only partial Linux +emulation. Also, some embedded Linux systems run a Linux kernel but amputate +things like the /proc directory to save space.</p> + +<p>Supporting these systems is largely a question of providing a clean subset +of BusyBox's functionality -- whichever applets can easily be made to +work in that environment. Annotating the configuration system to +indicate which applets require which prerequisites (such as procfs) is +also welcome. Other efforts to support these systems (swapping #include +files to build in different environments, adding adapter code to platform.h, +adding more extensive special-case supporting infrastructure such as mount's +legacy mtab support) are handled on a case-by-case basis. Support that can be +cleanly hidden in platform.h is reasonably attractive, and failing that +support that can be cleanly separated into a separate conditionally compiled +file is at least worth a look. Special-case code in the body of an applet is +something we're trying to avoid.</p> + +<hr /> +<h2><a name="tips">Programming tips and tricks.</a></h2> + +<p>Various things busybox uses that aren't particularly well documented +elsewhere.</p> + +<hr /> +<h2><a name="tips_encrypted_passwords">Encrypted Passwords</a></h2> + +<p>Password fields in /etc/passwd and /etc/shadow are in a special format. +If the first character isn't '$', then it's an old DES style password. If +the first character is '$' then the password is actually three fields +separated by '$' characters:</p> +<pre> + <b>$type$salt$encrypted_password</b> +</pre> + +<p>The "type" indicates which encryption algorithm to use: 1 for MD5 and 2 for SHA1.</p> + +<p>The "salt" is a bunch of ramdom characters (generally 8) the encryption +algorithm uses to perturb the password in a known and reproducible way (such +as by appending the random data to the unencrypted password, or combining +them with exclusive or). Salt is randomly generated when setting a password, +and then the same salt value is re-used when checking the password. (Salt is +thus stored unencrypted.)</p> + +<p>The advantage of using salt is that the same cleartext password encrypted +with a different salt value produces a different encrypted value. +If each encrypted password uses a different salt value, an attacker is forced +to do the cryptographic math all over again for each password they want to +check. Without salt, they could simply produce a big dictionary of commonly +used passwords ahead of time, and look up each password in a stolen password +file to see if it's a known value. (Even if there are billions of possible +passwords in the dictionary, checking each one is just a binary search against +a file only a few gigabytes long.) With salt they can't even tell if two +different users share the same password without guessing what that password +is and decrypting it. They also can't precompute the attack dictionary for +a specific password until they know what the salt value is.</p> + +<p>The third field is the encrypted password (plus the salt). For md5 this +is 22 bytes.</p> + +<p>The busybox function to handle all this is pw_encrypt(clear, salt) in +"libbb/pw_encrypt.c". The first argument is the clear text password to be +encrypted, and the second is a string in "$type$salt$password" format, from +which the "type" and "salt" fields will be extracted to produce an encrypted +value. (Only the first two fields are needed, the third $ is equivalent to +the end of the string.) The return value is an encrypted password in +/etc/passwd format, with all three $ separated fields. It's stored in +a static buffer, 128 bytes long.</p> + +<p>So when checking an existing password, if pw_encrypt(text, +old_encrypted_password) returns a string that compares identical to +old_encrypted_password, you've got the right password. When setting a new +password, generate a random 8 character salt string, put it in the right +format with sprintf(buffer, "$%c$%s", type, salt), and feed buffer as the +second argument to pw_encrypt(text,buffer).</p> + +<hr /> +<h2><a name="tips_vfork">Fork and vfork</a></h2> + +<p>On systems that haven't got a Memory Management Unit, fork() is unreasonably +expensive to implement (and sometimes even impossible), so a less capable +function called vfork() is used instead. (Using vfork() on a system with an +MMU is like pounding a nail with a wrench. Not the best tool for the job, but +it works.)</p> + +<p>Busybox hides the difference between fork() and vfork() in +libbb/bb_fork_exec.c. If you ever want to fork and exec, use bb_fork_exec() +(which returns a pid and takes the same arguments as execve(), although in +this case envp can be NULL) and don't worry about it. This description is +here in case you want to know why that does what it does.</p> + +<p>Implementing fork() depends on having a Memory Management Unit. With an +MMU then you can simply set up a second set of page tables and share the +physical memory via copy-on-write. So a fork() followed quickly by exec() +only copies a few pages of the parent's memory, just the ones it changes +before freeing them.</p> + +<p>With a very primitive MMU (using a base pointer plus length instead of page +tables, which can provide virtual addresses and protect processes from each +other, but no copy on write) you can still implement fork. But it's +unreasonably expensive, because you have to copy all the parent process' +memory into the new process (which could easily be several megabytes per fork). +And you have to do this even though that memory gets freed again as soon as the +exec happens. (This is not just slow and a waste of space but causes memory +usage spikes that can easily cause the system to run out of memory.)</p> + +<p>Without even a primitive MMU, you have no virtual addresses. Every process +can reach out and touch any other process' memory, because all pointers are to +physical addresses with no protection. Even if you copy a process' memory to +new physical addresses, all of its pointers point to the old objects in the +old process. (Searching through the new copy's memory for pointers and +redirect them to the new locations is not an easy problem.)</p> + +<p>So with a primitive or missing MMU, fork() is just not a good idea.</p> + +<p>In theory, vfork() is just a fork() that writeably shares the heap and stack +rather than copying it (so what one process writes the other one sees). In +practice, vfork() has to suspend the parent process until the child does exec, +at which point the parent wakes up and resumes by returning from the call to +vfork(). All modern kernel/libc combinations implement vfork() to put the +parent to sleep until the child does its exec. There's just no other way to +make it work: the parent has to know the child has done its exec() or exit() +before it's safe to return from the function it's in, so it has to block +until that happens. In fact without suspending the parent there's no way to +even store separate copies of the return value (the pid) from the vfork() call +itself: both assignments write into the same memory location.</p> + +<p>One way to understand (and in fact implement) vfork() is this: imagine +the parent does a setjmp and then continues on (pretending to be the child) +until the exec() comes around, then the _exec_ does the actual fork, and the +parent does a longjmp back to the original vfork call and continues on from +there. (It thus becomes obvious why the child can't return, or modify +local variables it doesn't want the parent to see changed when it resumes.) + +<p>Note a common mistake: the need for vfork doesn't mean you can't have two +processes running at the same time. It means you can't have two processes +sharing the same memory without stomping all over each other. As soon as +the child calls exec(), the parent resumes.</p> + +<p>If the child's attempt to call exec() fails, the child should call _exit() +rather than a normal exit(). This avoids any atexit() code that might confuse +the parent. (The parent should never call _exit(), only a vforked child that +failed to exec.)</p> + +<p>(Now in theory, a nommu system could just copy the _stack_ when it forks +(which presumably is much shorter than the heap), and leave the heap shared. +Even with no MMU at all +In practice, you've just wound up in a multi-threaded situation and you can't +do a malloc() or free() on your heap without freeing the other process' memory +(and if you don't have the proper locking for being threaded, corrupting the +heap if both of you try to do it at the same time and wind up stomping on +each other while traversing the free memory lists). The thing about vfork is +that it's a big red flag warning "there be dragons here" rather than +something subtle and thus even more dangerous.)</p> + +<hr /> +<h2><a name="tips_sort_read">Short reads and writes</a></h2> + +<p>Busybox has special functions, bb_full_read() and bb_full_write(), to +check that all the data we asked for got read or written. Is this a real +world consideration? Try the following:</p> + +<pre>while true; do echo hello; sleep 1; done | tee out.txt</pre> + +<p>If tee is implemented with bb_full_read(), tee doesn't display output +in real time but blocks until its entire input buffer (generally a couple +kilobytes) is read, then displays it all at once. In that case, we _want_ +the short read, for user interface reasons. (Note that read() should never +return 0 unless it has hit the end of input, and an attempt to write 0 +bytes should be ignored by the OS.)</p> + +<p>As for short writes, play around with two processes piping data to each +other on the command line (cat bigfile | gzip > out.gz) and suspend and +resume a few times (ctrl-z to suspend, "fg" to resume). The writer can +experience short writes, which are especially dangerous because if you don't +notice them you'll discard data. They can also happen when a system is under +load and a fast process is piping to a slower one. (Such as an xterm waiting +on x11 when the scheduler decides X is being a CPU hog with all that +text console scrolling...)</p> + +<p>So will data always be read from the far end of a pipe at the +same chunk sizes it was written in? Nope. Don't rely on that. For one +counterexample, see <a href="http://www.faqs.org/rfcs/rfc896.html">rfc 896 +for Nagle's algorithm</a>, which waits a fraction of a second or so before +sending out small amounts of data through a TCP/IP connection in case more +data comes in that can be merged into the same packet. (In case you were +wondering why action games that use TCP/IP set TCP_NODELAY to lower the latency +on their their sockets, now you know.)</p> + +<hr /> +<h2><a name="tips_memory">Memory used by relocatable code, PIC, and static linking.</a></h2> + +<p>The downside of standard dynamic linking is that it results in self-modifying +code. Although each executable's pages are mmaped() into a process' address +space from the executable file and are thus naturally shared between processes +out of the page cache, the library loader (ld-linux.so.2 or ld-uClibc.so.0) +writes to these pages to supply addresses for relocatable symbols. This +dirties the pages, triggering copy-on-write allocation of new memory for each +processes' dirtied pages.</p> + +<p>One solution to this is Position Independent Code (PIC), a way of linking +a file so all the relocations are grouped together. This dirties fewer +pages (often just a single page) for each process' relocations. The down +side is this results in larger executables, which take up more space on disk +(and a correspondingly larger space in memory). But when many copies of the +same program are running, PIC dynamic linking trades a larger disk footprint +for a smaller memory footprint, by sharing more pages.</p> + +<p>A third solution is static linking. A statically linked program has no +relocations, and thus the entire executable is shared between all running +instances. This tends to have a significantly larger disk footprint, but +on a system with only one or two executables, shared libraries aren't much +of a win anyway.</p> + +<p>You can tell the glibc linker to display debugging information about its +relocations with the environment variable "LD_DEBUG". Try +"LD_DEBUG=help /bin/true" for a list of commands. Learning to interpret +"LD_DEBUG=statistics cat /proc/self/statm" could be interesting.</p> + +<p>For more on this topic, here's Rich Felker:</p> +<blockquote> +<p>Dynamic linking (without fixed load addresses) fundamentally requires +at least one dirty page per dso that uses symbols. Making calls (but +never taking the address explicitly) to functions within the same dso +does not require a dirty page by itself, but will with ELF unless you +use -Bsymbolic or hidden symbols when linking.</p> + +<p>ELF uses significant additional stack space for the kernel to pass all +the ELF data structures to the newly created process image. These are +located above the argument list and environment. This normally adds 1 +dirty page to the process size.</p> + +<p>The ELF dynamic linker has its own data segment, adding one or more +dirty pages. I believe it also performs relocations on itself.</p> + +<p>The ELF dynamic linker makes significant dynamic allocations to manage +the global symbol table and the loaded dso's. This data is never +freed. It will be needed again if libdl is used, so unconditionally +freeing it is not possible, but normal programs do not use libdl. Of +course with glibc all programs use libdl (due to nsswitch) so the +issue was never addressed.</p> + +<p>ELF also has the issue that segments are not page-aligned on disk. +This saves up to 4k on disk, but at the expense of using an additional +dirty page in most cases, due to a large portion of the first data +page being filled with a duplicate copy of the last text page.</p> + +<p>The above is just a partial list of the tiny memory penalties of ELF +dynamic linking, which eventually add up to quite a bit. The smallest +I've been able to get a process down to is 8 dirty pages, and the +above factors seem to mostly account for it (but some were difficult +to measure).</p> +</blockquote> + +<hr /> +<h2><a name="tips_kernel_headers"></a>Including kernel headers</h2> + +<p>The "linux" or "asm" directories of /usr/include +contain Linux kernel +headers, so that the C library can talk directly to the Linux kernel. In +a perfect world, applications shouldn't include these headers directly, but +we don't live in a perfect world.</p> + +<p>For example, Busybox's losetup code wants linux/loop.c because nothing else +#defines the structures to call the kernel's loopback device setup ioctls. +Attempts to cut and paste the information into a local busybox header file +proved incredibly painful, because portions of the loop_info structure vary by +architecture, namely the type __kernel_dev_t has different sizes on alpha, +arm, x86, and so on. Meaning we either #include <linux/posix_types.h> or +we hardwire #ifdefs to check what platform we're building on and define this +type appropriately for every single hardware architecture supported by +Linux, which is simply unworkable.</p> + +<p>This is aside from the fact that the relevant type defined in +posix_types.h was renamed to __kernel_old_dev_t during the 2.5 series, so +to cut and paste the structure into our header we have to #include +<linux/version.h> to figure out which name to use. (What we actually +do is +check if we're building on 2.6, and if so just use the new 64 bit structure +instead to avoid the rename entirely.) But we still need the version +check, since 2.4 didn't have the 64 bit structure.</p> + +<p>The BusyBox developers spent <u>two years</u> trying to figure +out a clean way to do all this. There isn't one. The losetup in the +util-linux package from kernel.org isn't doing it cleanly either, they just +hide the ugliness by nesting #include files. Their mount/loop.h +#includes "my_dev_t.h", which #includes <linux/posix_types.h> +and <linux/version.h> just like we do. There simply is no alternative. +</p> + +<p>Just because directly #including kernel headers is sometimes +unavoidable doesn't me we should include them when there's a better +way to do it. However, block copying information out of the kernel headers +is not a better way.</p> + +<hr /> +<h2><a name="who">Who are the BusyBox developers?</a></h2> + +<p>The following login accounts currently exist on busybox.net. (I.E. these +people can commit <a href="http://busybox.net/downloads/patches/">patches</a> +into subversion for the BusyBox, uClibc, and buildroot projects.)</p> + +<pre> +aldot :Bernhard Reutner-Fischer +andersen :Erik Andersen - uClibc and BuildRoot maintainer. +bug1 :Glenn McGrath +davidm :David McCullough +gkajmowi :Garrett Kajmowicz - uClibc++ maintainer +jbglaw :Jan-Benedict Glaw +jocke :Joakim Tjernlund +landley :Rob Landley +lethal :Paul Mundt +mjn3 :Manuel Novoa III +osuadmin :osuadmin +pgf :Paul Fox +pkj :Peter Kjellerstedt +prpplague :David Anders +psm :Peter S. Mazinger +russ :Russ Dill +sandman :Robert Griebl +sjhill :Steven J. Hill +solar :Ned Ludd +timr :Tim Riker +tobiasa :Tobias Anderberg +vapier :Mike Frysinger +vda :Denys Vlasenko - BusyBox maintainer +</pre> + +<p>The following accounts used to exist on busybox.net, but don't anymore so +I can't ask /etc/passwd for their names. Rob Wentworth +<robwen at gmail.com> asked Google and recovered the names:</p> + +<pre> +aaronl :Aaron Lehmann +beppu :John Beppu +dwhedon :David Whedon +erik :Erik Andersen +gfeldman :Gennady Feldman +jimg :Jim Gleason +kraai :Matt Kraai +markw :Mark Whitley +miles :Miles Bader +proski :Pavel Roskin +rjune :Richard June +tausq :Randolph Chung +vodz :Vladimir N. Oleynik +</pre> + + +<br> +<br> +<br> + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/about.html b/docs/busybox.net/about.html new file mode 100644 index 0000000..35809c3 --- /dev/null +++ b/docs/busybox.net/about.html @@ -0,0 +1,24 @@ +<!--#include file="header.html" --> + +<h3>BusyBox: The Swiss Army Knife of Embedded Linux</h3> + +<p>BusyBox combines tiny versions of many common UNIX utilities into a single +small executable. It provides replacements for most of the utilities you +usually find in GNU fileutils, shellutils, etc. The utilities in BusyBox +generally have fewer options than their full-featured GNU cousins; however, +the options that are included provide the expected functionality and behave +very much like their GNU counterparts. BusyBox provides a fairly complete +environment for any small or embedded system.</p> + +<p>BusyBox has been written with size-optimization and limited resources in +mind. It is also extremely modular so you can easily include or exclude +commands (or features) at compile time. This makes it easy to customize +your embedded systems. To create a working system, just add some device +nodes in /dev, a few configuration files in /etc, and a Linux kernel.</p> + +<p>BusyBox is maintained by +<a href="mailto:vda.linux@googlemail.com">Denys Vlasenko</a>, +and licensed under the <a href="license.html">GNU GENERAL PUBLIC LICENSE</a> +version 2.</p> + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/busybox-growth.ps b/docs/busybox.net/busybox-growth.ps new file mode 100644 index 0000000..2379def --- /dev/null +++ b/docs/busybox.net/busybox-growth.ps @@ -0,0 +1,404 @@ +%!PS-Adobe-2.0 +%%Title: busybox-growth.ps +%%Creator: gnuplot 3.5 (pre 3.6) patchlevel beta 347 +%%CreationDate: Tue Apr 10 14:03:36 2001 +%%DocumentFonts: (atend) +%%BoundingBox: 50 40 554 770 +%%Orientation: Landscape +%%Pages: (atend) +%%EndComments +/gnudict 120 dict def +gnudict begin +/Color true def +/Solid true def +/gnulinewidth 5.000 def +/userlinewidth gnulinewidth def +/vshift -46 def +/dl {10 mul} def +/hpt_ 31.5 def +/vpt_ 31.5 def +/hpt hpt_ def +/vpt vpt_ def +/M {moveto} bind def +/L {lineto} bind def +/R {rmoveto} bind def +/V {rlineto} bind def +/vpt2 vpt 2 mul def +/hpt2 hpt 2 mul def +/Lshow { currentpoint stroke M + 0 vshift R show } def +/Rshow { currentpoint stroke M + dup stringwidth pop neg vshift R show } def +/Cshow { currentpoint stroke M + dup stringwidth pop -2 div vshift R show } def +/UP { dup vpt_ mul /vpt exch def hpt_ mul /hpt exch def + /hpt2 hpt 2 mul def /vpt2 vpt 2 mul def } def +/DL { Color {setrgbcolor Solid {pop []} if 0 setdash } + {pop pop pop Solid {pop []} if 0 setdash} ifelse } def +/BL { stroke gnulinewidth 2 mul setlinewidth } def +/AL { stroke gnulinewidth 2 div setlinewidth } def +/UL { gnulinewidth mul /userlinewidth exch def } def +/PL { stroke userlinewidth setlinewidth } def +/LTb { BL [] 0 0 0 DL } def +/LTa { AL [1 dl 2 dl] 0 setdash 0 0 0 setrgbcolor } def +/LT0 { PL [] 1 0 0 DL } def +/LT1 { PL [4 dl 2 dl] 0 1 0 DL } def +/LT2 { PL [2 dl 3 dl] 0 0 1 DL } def +/LT3 { PL [1 dl 1.5 dl] 1 0 1 DL } def +/LT4 { PL [5 dl 2 dl 1 dl 2 dl] 0 1 1 DL } def +/LT5 { PL [4 dl 3 dl 1 dl 3 dl] 1 1 0 DL } def +/LT6 { PL [2 dl 2 dl 2 dl 4 dl] 0 0 0 DL } def +/LT7 { PL [2 dl 2 dl 2 dl 2 dl 2 dl 4 dl] 1 0.3 0 DL } def +/LT8 { PL [2 dl 2 dl 2 dl 2 dl 2 dl 2 dl 2 dl 4 dl] 0.5 0.5 0.5 DL } def +/Pnt { stroke [] 0 setdash + gsave 1 setlinecap M 0 0 V stroke grestore } def +/Dia { stroke [] 0 setdash 2 copy vpt add M + hpt neg vpt neg V hpt vpt neg V + hpt vpt V hpt neg vpt V closepath stroke + Pnt } def +/Pls { stroke [] 0 setdash vpt sub M 0 vpt2 V + currentpoint stroke M + hpt neg vpt neg R hpt2 0 V stroke + } def +/Box { stroke [] 0 setdash 2 copy exch hpt sub exch vpt add M + 0 vpt2 neg V hpt2 0 V 0 vpt2 V + hpt2 neg 0 V closepath stroke + Pnt } def +/Crs { stroke [] 0 setdash exch hpt sub exch vpt add M + hpt2 vpt2 neg V currentpoint stroke M + hpt2 neg 0 R hpt2 vpt2 V stroke } def +/TriU { stroke [] 0 setdash 2 copy vpt 1.12 mul add M + hpt neg vpt -1.62 mul V + hpt 2 mul 0 V + hpt neg vpt 1.62 mul V closepath stroke + Pnt } def +/Star { 2 copy Pls Crs } def +/BoxF { stroke [] 0 setdash exch hpt sub exch vpt add M + 0 vpt2 neg V hpt2 0 V 0 vpt2 V + hpt2 neg 0 V closepath fill } def +/TriUF { stroke [] 0 setdash vpt 1.12 mul add M + hpt neg vpt -1.62 mul V + hpt 2 mul 0 V + hpt neg vpt 1.62 mul V closepath fill } def +/TriD { stroke [] 0 setdash 2 copy vpt 1.12 mul sub M + hpt neg vpt 1.62 mul V + hpt 2 mul 0 V + hpt neg vpt -1.62 mul V closepath stroke + Pnt } def +/TriDF { stroke [] 0 setdash vpt 1.12 mul sub M + hpt neg vpt 1.62 mul V + hpt 2 mul 0 V + hpt neg vpt -1.62 mul V closepath fill} def +/DiaF { stroke [] 0 setdash vpt add M + hpt neg vpt neg V hpt vpt neg V + hpt vpt V hpt neg vpt V closepath fill } def +/Pent { stroke [] 0 setdash 2 copy gsave + translate 0 hpt M 4 {72 rotate 0 hpt L} repeat + closepath stroke grestore Pnt } def +/PentF { stroke [] 0 setdash gsave + translate 0 hpt M 4 {72 rotate 0 hpt L} repeat + closepath fill grestore } def +/Circle { stroke [] 0 setdash 2 copy + hpt 0 360 arc stroke Pnt } def +/CircleF { stroke [] 0 setdash hpt 0 360 arc fill } def +/C0 { BL [] 0 setdash 2 copy moveto vpt 90 450 arc } bind def +/C1 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 0 90 arc closepath fill + vpt 0 360 arc closepath } bind def +/C2 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 90 180 arc closepath fill + vpt 0 360 arc closepath } bind def +/C3 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 0 180 arc closepath fill + vpt 0 360 arc closepath } bind def +/C4 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 180 270 arc closepath fill + vpt 0 360 arc closepath } bind def +/C5 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 0 90 arc + 2 copy moveto + 2 copy vpt 180 270 arc closepath fill + vpt 0 360 arc } bind def +/C6 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 90 270 arc closepath fill + vpt 0 360 arc closepath } bind def +/C7 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 0 270 arc closepath fill + vpt 0 360 arc closepath } bind def +/C8 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 270 360 arc closepath fill + vpt 0 360 arc closepath } bind def +/C9 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 270 450 arc closepath fill + vpt 0 360 arc closepath } bind def +/C10 { BL [] 0 setdash 2 copy 2 copy moveto vpt 270 360 arc closepath fill + 2 copy moveto + 2 copy vpt 90 180 arc closepath fill + vpt 0 360 arc closepath } bind def +/C11 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 0 180 arc closepath fill + 2 copy moveto + 2 copy vpt 270 360 arc closepath fill + vpt 0 360 arc closepath } bind def +/C12 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 180 360 arc closepath fill + vpt 0 360 arc closepath } bind def +/C13 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 0 90 arc closepath fill + 2 copy moveto + 2 copy vpt 180 360 arc closepath fill + vpt 0 360 arc closepath } bind def +/C14 { BL [] 0 setdash 2 copy moveto + 2 copy vpt 90 360 arc closepath fill + vpt 0 360 arc } bind def +/C15 { BL [] 0 setdash 2 copy vpt 0 360 arc closepath fill + vpt 0 360 arc closepath } bind def +/Rec { newpath 4 2 roll moveto 1 index 0 rlineto 0 exch rlineto + neg 0 rlineto closepath } bind def +/Square { dup Rec } bind def +/Bsquare { vpt sub exch vpt sub exch vpt2 Square } bind def +/S0 { BL [] 0 setdash 2 copy moveto 0 vpt rlineto BL Bsquare } bind def +/S1 { BL [] 0 setdash 2 copy vpt Square fill Bsquare } bind def +/S2 { BL [] 0 setdash 2 copy exch vpt sub exch vpt Square fill Bsquare } bind def +/S3 { BL [] 0 setdash 2 copy exch vpt sub exch vpt2 vpt Rec fill Bsquare } bind def +/S4 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt Square fill Bsquare } bind def +/S5 { BL [] 0 setdash 2 copy 2 copy vpt Square fill + exch vpt sub exch vpt sub vpt Square fill Bsquare } bind def +/S6 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt vpt2 Rec fill Bsquare } bind def +/S7 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt vpt2 Rec fill + 2 copy vpt Square fill + Bsquare } bind def +/S8 { BL [] 0 setdash 2 copy vpt sub vpt Square fill Bsquare } bind def +/S9 { BL [] 0 setdash 2 copy vpt sub vpt vpt2 Rec fill Bsquare } bind def +/S10 { BL [] 0 setdash 2 copy vpt sub vpt Square fill 2 copy exch vpt sub exch vpt Square fill + Bsquare } bind def +/S11 { BL [] 0 setdash 2 copy vpt sub vpt Square fill 2 copy exch vpt sub exch vpt2 vpt Rec fill + Bsquare } bind def +/S12 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt2 vpt Rec fill Bsquare } bind def +/S13 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt2 vpt Rec fill + 2 copy vpt Square fill Bsquare } bind def +/S14 { BL [] 0 setdash 2 copy exch vpt sub exch vpt sub vpt2 vpt Rec fill + 2 copy exch vpt sub exch vpt Square fill Bsquare } bind def +/S15 { BL [] 0 setdash 2 copy Bsquare fill Bsquare } bind def +/D0 { gsave translate 45 rotate 0 0 S0 stroke grestore } bind def +/D1 { gsave translate 45 rotate 0 0 S1 stroke grestore } bind def +/D2 { gsave translate 45 rotate 0 0 S2 stroke grestore } bind def +/D3 { gsave translate 45 rotate 0 0 S3 stroke grestore } bind def +/D4 { gsave translate 45 rotate 0 0 S4 stroke grestore } bind def +/D5 { gsave translate 45 rotate 0 0 S5 stroke grestore } bind def +/D6 { gsave translate 45 rotate 0 0 S6 stroke grestore } bind def +/D7 { gsave translate 45 rotate 0 0 S7 stroke grestore } bind def +/D8 { gsave translate 45 rotate 0 0 S8 stroke grestore } bind def +/D9 { gsave translate 45 rotate 0 0 S9 stroke grestore } bind def +/D10 { gsave translate 45 rotate 0 0 S10 stroke grestore } bind def +/D11 { gsave translate 45 rotate 0 0 S11 stroke grestore } bind def +/D12 { gsave translate 45 rotate 0 0 S12 stroke grestore } bind def +/D13 { gsave translate 45 rotate 0 0 S13 stroke grestore } bind def +/D14 { gsave translate 45 rotate 0 0 S14 stroke grestore } bind def +/D15 { gsave translate 45 rotate 0 0 S15 stroke grestore } bind def +/DiaE { stroke [] 0 setdash vpt add M + hpt neg vpt neg V hpt vpt neg V + hpt vpt V hpt neg vpt V closepath stroke } def +/BoxE { stroke [] 0 setdash exch hpt sub exch vpt add M + 0 vpt2 neg V hpt2 0 V 0 vpt2 V + hpt2 neg 0 V closepath stroke } def +/TriUE { stroke [] 0 setdash vpt 1.12 mul add M + hpt neg vpt -1.62 mul V + hpt 2 mul 0 V + hpt neg vpt 1.62 mul V closepath stroke } def +/TriDE { stroke [] 0 setdash vpt 1.12 mul sub M + hpt neg vpt 1.62 mul V + hpt 2 mul 0 V + hpt neg vpt -1.62 mul V closepath stroke } def +/PentE { stroke [] 0 setdash gsave + translate 0 hpt M 4 {72 rotate 0 hpt L} repeat + closepath stroke grestore } def +/CircE { stroke [] 0 setdash + hpt 0 360 arc stroke } def +/Opaque { gsave closepath 1 setgray fill grestore 0 setgray closepath } def +/DiaW { stroke [] 0 setdash vpt add M + hpt neg vpt neg V hpt vpt neg V + hpt vpt V hpt neg vpt V Opaque stroke } def +/BoxW { stroke [] 0 setdash exch hpt sub exch vpt add M + 0 vpt2 neg V hpt2 0 V 0 vpt2 V + hpt2 neg 0 V Opaque stroke } def +/TriUW { stroke [] 0 setdash vpt 1.12 mul add M + hpt neg vpt -1.62 mul V + hpt 2 mul 0 V + hpt neg vpt 1.62 mul V Opaque stroke } def +/TriDW { stroke [] 0 setdash vpt 1.12 mul sub M + hpt neg vpt 1.62 mul V + hpt 2 mul 0 V + hpt neg vpt -1.62 mul V Opaque stroke } def +/PentW { stroke [] 0 setdash gsave + translate 0 hpt M 4 {72 rotate 0 hpt L} repeat + Opaque stroke grestore } def +/CircW { stroke [] 0 setdash + hpt 0 360 arc Opaque stroke } def +/BoxFill { gsave Rec 1 setgray fill grestore } def +end +%%EndProlog +%%Page: 1 1 +gnudict begin +gsave +50 50 translate +0.100 0.100 scale +90 rotate +0 -5040 translate +0 setgray +newpath +(Helvetica) findfont 140 scalefont setfont +1.000 UL +LTb +560 420 M +63 0 V +6409 0 R +-63 0 V +476 420 M +(0) Rshow +560 1056 M +63 0 V +6409 0 R +-63 0 V +-6493 0 R +(100) Rshow +560 1692 M +63 0 V +6409 0 R +-63 0 V +-6493 0 R +(200) Rshow +560 2328 M +63 0 V +6409 0 R +-63 0 V +-6493 0 R +(300) Rshow +560 2964 M +63 0 V +6409 0 R +-63 0 V +-6493 0 R +(400) Rshow +560 3600 M +63 0 V +6409 0 R +-63 0 V +-6493 0 R +(500) Rshow +560 4236 M +63 0 V +6409 0 R +-63 0 V +-6493 0 R +(600) Rshow +560 4872 M +63 0 V +6409 0 R +-63 0 V +-6493 0 R +(700) Rshow +1531 420 M +0 63 V +0 4389 R +0 -63 V +0 -4529 R +(400) Cshow +2825 420 M +0 63 V +0 4389 R +0 -63 V +0 -4529 R +(600) Cshow +4120 420 M +0 63 V +0 4389 R +0 -63 V +0 -4529 R +(800) Cshow +5414 420 M +0 63 V +0 4389 R +0 -63 V +0 -4529 R +(1000) Cshow +6708 420 M +0 63 V +0 4389 R +0 -63 V +0 -4529 R +(1200) Cshow +1.000 UL +LTb +560 420 M +6472 0 V +0 4452 V +-6472 0 V +560 420 L +0 2646 M +currentpoint gsave translate 90 rotate 0 0 M +(tar.gz size \(Kb\)) Cshow +grestore +3796 140 M +(time \(days since Jan 1, 1998\)) Cshow +1.000 UL +LT0 +696 420 M +0 593 V +1255 0 V +0 15 V +214 0 V +0 6 V +958 0 V +0 1 V +-84 0 V +0 37 V +168 0 V +0 262 V +13 0 V +0 56 V +91 0 V +0 33 V +6 0 V +0 1 V +19 0 V +0 11 V +20 0 V +0 13 V +32 0 V +0 104 V +52 0 V +0 27 V +65 0 V +0 15 V +39 0 V +0 126 V +174 0 V +0 103 V +52 0 V +0 49 V +175 0 V +0 56 V +433 0 V +0 661 V +415 0 V +0 857 V +123 0 V +0 -291 V +498 0 V +0 208 V +505 0 V +0 66 V +291 0 V +0 115 V +311 0 V +0 449 V +162 0 V +0 309 V +stroke +grestore +end +showpage +%%Trailer +%%DocumentFonts: Helvetica +%%Pages: 1 diff --git a/docs/busybox.net/copyright.txt b/docs/busybox.net/copyright.txt new file mode 100644 index 0000000..3974756 --- /dev/null +++ b/docs/busybox.net/copyright.txt @@ -0,0 +1,30 @@ + +The code and graphics on this website (and it's mirror sites, if any) are +Copyright (c) 1999-2004 by Erik Andersen. All rights reserved. +Copyright (c) 2005-2006 Rob Landley. + +Documents on this Web site including their graphical elements, design, and +layout are protected by trade dress and other laws and MAY BE COPIED OR +IMITATED IN WHOLE OR IN PART. THIS WEBSITE IS LICENSED FREE OF CHARGE, THERE +IS NO WARRANTY FOR THE WEBSITE TO THE EXTENT PERMITTED BY APPLICABLE LAW. +SHOULD THIS WEBSITE PROVE DEFECTIVE, YOU MAY ASSUME THAT SOMEONE MIGHT GET +AROUND TO SERVICING, REPAIRING OR CORRECTING IT SOMETIME WHEN THEY HAVE NOTHING +BETTER TO DO. REGARDLESS, YOU GET TO KEEP BOTH PIECES. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY +COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THIS +WEBSITE AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR +INABILITY TO USE THIS WEBSITE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR +LOSS OF HAIR, LOSS OF LIFE, LOSS OF MEMORY, LOSS OF YOUR CARKEYS, MISPLACEMENT +OF YOUR PAYCHECK, OR COMMANDER DATA BEING RENDERED UNABLE TO ASSIST THE +STARFLEET OFFICERS ABORD THE STARSHIP ENTERPRISE TO RECALIBRATE THE MAIN +DEFLECTOR ARRAY, LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE +WEBSITE TO OPERATE WITH YOUR WEBBROWSER), EVEN IF SUCH HOLDER OR OTHER PARTY +HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +You have been warned. + +You can contact the webmaster at <rob@landley.net> if you have some sort +of problem with this. + diff --git a/docs/busybox.net/developer.html b/docs/busybox.net/developer.html new file mode 100644 index 0000000..cdb68b7 --- /dev/null +++ b/docs/busybox.net/developer.html @@ -0,0 +1,69 @@ +<!--#include file="header.html" --> + +<h3>Morris Dancing</h3> + +<p>Subversion commit access requires an account on Morris. The server +behind busybox.net and uclibc.org. If you want to be able to commit things to +Subversion, first contribute some stuff to show you are serious, can handle +some responsibility, and that your patches don't generally need a lot of +cleanup. Then, very nicely ask one of us (<a href="mailto:rob@landley.net">Rob +Landley</a> for BusyBox, or <a href="mailto:andersen@codepoet.org">Erik +Andersen</a> for uClibc) for an account.</p> + +<p>If you're approved for an account, you'll need to send an email from your +preferred contact email address with the username you'd like to use when +committing changes to SVN, and attach a public ssh key to access your account +with.</p> + +<p>If you don't currently have an ssh version 2 DSA key at least 1024 bits +long (the default), you can generate a key using the +command <b>ssh-keygen -t dsa</b> and hitting enter at the prompts. This +will create the files <b>~/.ssh/id_dsa</b> and <b>~/.ssh/id_dsa.pub</b> +You must then send the content of 'id_dsa.pub' to me so I can set up your +account. (The content of 'id_dsa' should of course be kept secret, anyone +who has that can access any account that's installed your public key in +its <b>.ssh/authorized_keys</b> file.)</p> + +<p>Note that if you would prefer to keep your communications with us +private, you can encrypt your email using +<a href="http://landley.net/pubkey.gpg">Rob's public key</a> or +<a href="http://www.codepoet.org/andersen/erik/gpg.asc">Erik's public +key</a>.</p> + +<p>Once you are setup with an account, you will need to use your account to +checkout a copy of BusyBox from Subversion:</p> + +<p><b>svn checkout svn+ssh://username@busybox.net/svn/trunk/busybox</b></p> +<p>or</p> +<p><b>svn checkout svn+ssh://username@uclibc.org/svn/trunk/uclibc</b></p> + +<p>You must change <em>username</em> to your own username, or omit +it if it's the same as your local username.</p> + +<p>You can then enter the newly checked out project directory, make changes, +check your changes, diff your changes, revert your changes, and and commit your +changes using commands such as:</p> + +<b><pre> +svn diff +svn status +svn revert +EDITOR=vi svn commit +svn log -v -r PREV:HEAD +svn help +</pre></b> + +<p>For additional detail on how to use Subversion, please visit the +<a href="http://subversion.tigris.org/">the Subversion website</a>. +You might also want to read online or buy a copy of <a +href="http://svnbook.red-bean.com/">the Subversion Book</a>...</p> + +<p>A morris account also gives you a personal web page +(http://busybox.net/~username comes from ~/public_html on morris), and of +course a shell prompt you can ssh into (as a regular user, root access is +reserved for Erik and Rob). But keep in mind an account on Morris is a +priviledge, not a requirement. Most contributors to busybox and uClibc +haven't got one, and accounts are handed out to make the project maintainers' +lives easier, not because "you deserve it".</p> + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/download.html b/docs/busybox.net/download.html new file mode 100644 index 0000000..fa5945e --- /dev/null +++ b/docs/busybox.net/download.html @@ -0,0 +1,60 @@ +<!--#include file="header.html" --> + + + +<h3>Download</h3> + +<p> +Source for the latest release can always be +downloaded from <a href="downloads/">http://www.busybox.net/downloads/</a>. + +<p> +Each 1.x branch has bug fix releases after initial 1.x.0 release. +Also there are patches on top of latest bug fix release. +<p> +Latest releases and patch directories for each branch: +<br> +<a href="http://busybox.net/downloads/busybox-1.10.1.tar.bz2">1.10.1</a>, +<a href="http://busybox.net/downloads/fixes-1.10.1/">patches</a>, +<br> +<a href="http://busybox.net/downloads/busybox-1.9.2.tar.bz2">1.9.2</a>, +<a href="http://busybox.net/downloads/fixes-1.9.2/">patches</a>, +<br> +<a href="http://busybox.net/downloads/busybox-1.8.3.tar.bz2">1.8.3</a>, +<a href="http://busybox.net/downloads/fixes-1.8.3/">patches</a>, +<br> +<a href="http://busybox.net/downloads/busybox-1.7.5.tar.bz2">1.7.5</a>, +<a href="http://busybox.net/downloads/fixes-1.7.5/">patches</a>, +<br> +<a href="http://busybox.net/downloads/busybox-1.6.2.tar.bz2">1.6.2</a>, +<a href="http://busybox.net/downloads/fixes-1.6.2/">patches</a>, +<br> +<a href="http://busybox.net/downloads/busybox-1.5.2.tar.bz2">1.5.2</a>, +<a href="http://busybox.net/downloads/fixes-1.5.2/">patches</a>, +<br> +<a href="http://busybox.net/downloads/busybox-1.4.2.tar.bz2">1.4.2</a>, +<a href="http://busybox.net/downloads/fixes-1.4.2/">patches</a>, +<br> +<a href="http://busybox.net/downloads/busybox-1.3.2.tar.bz2">1.3.2</a>, +<a href="http://busybox.net/downloads/fixes-1.3.2/">patches</a>. + +<p> +You can also obtain <a href="downloads/snapshots/">Daily Snapshots</a> of +the latest development source tree for those wishing to follow BusyBox development, +but cannot or do not wish to use Subversion (svn). + +<ul> + <li> Click here to <a href="/cgi-bin/viewcvs.cgi/trunk/busybox/">browse the source tree</a>. + </li> + + <li>Anonymous <a href="subversion.html">Subversion access</a> is available. + </li> + + <li>For those that are actively contributing obtaining + <a href="developer.html">Subversion read/write access</a> is also possible. + </li> + +</ul> + +<!--#include file="footer.html" --> + diff --git a/docs/busybox.net/fix.html b/docs/busybox.net/fix.html new file mode 100644 index 0000000..7bd7fe0 --- /dev/null +++ b/docs/busybox.net/fix.html @@ -0,0 +1,15 @@ +<!--#include file="header.html" --> + +<h3>How to get your patch added to "hot fixes"</h3> + +<p> If you found a regression or severe bug in busybox, and you have a patch + for it, and you want to see it added to "hot fixes", please rediff your + patch against corresponding unmodified busybox source and send it to + <a href="mailto:busybox@busybox.net">the mailing list</a>. +</p> + +<br> +<br> +<br> + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/footer.html b/docs/busybox.net/footer.html new file mode 100644 index 0000000..0667092 --- /dev/null +++ b/docs/busybox.net/footer.html @@ -0,0 +1,51 @@ +<!-- Footer --> + + + </td> + </tr> + </table> + +<hr /> + + + <table width="100%"> + <tr> + <td width="60%"> + <font face="arial, helvetica, sans-serif" size="-1"> + <!--div style="font-family: arial, helvetica, sans-serif; font-size: 80%;" --> + <a href="/copyright.txt">Copyright © 1999-2008 Erik Andersen</a> + <br> + Mail all comments, insults, suggestions and bribes to + <br> + Denys Vlasenko <a href="mailto:vda.linux@googlemail.com">vda.linux@googlemail.com</a><br> + </font> + <!--/div--> + </td> + + <td> + <a href="http://www.vim.org/"><img border="0" + width="88" height="31" + src="images/written.in.vi.png" + alt="This site created with the vi editor" /></a> + </td> + + <td> + <a href="http://osuosl.org/"><img border="0" + width="114" height="63" + src="images/osuosl.png" + alt="This site is kindly hosted by OSL" /></a> + </td> +<!-- + <td> + <a href="http://validator.w3.org/check?uri=referer"><img + border="0" height="31" width="88" + src="images/valid-html401.png" + alt="Valid HTML" /></a> + </td> +--> + </tr> + </table> + + </body> +</html> + diff --git a/docs/busybox.net/header.html b/docs/busybox.net/header.html new file mode 100644 index 0000000..057b27a --- /dev/null +++ b/docs/busybox.net/header.html @@ -0,0 +1,91 @@ +<!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN'> + +<html> + <head> + <meta http-equiv='Content-Type' content='text/html; charset=iso-8859-1'> + <title>BusyBox</title> + <style type="text/css"> + body { + background-color: #DEE2DE; + color: #000000; + font-family: lucida, helvetica, arial; + font-size: 100%; + } + :link { color: #660000 } + :visited { color: #660000 } + :active { color: #660000 } + td.c2 {font-family: arial, helvetica, sans-serif; font-size: 80%} + td.c1 {font-family: lucida, helvetica; font-size: 248%} + </style> + </head> + + <body> + <!--basefont face="lucida, helvetica, arial" size="3"--> + +<table border="0" cellpadding="0" cellspacing="0"> +<tr> +<td> + <div class="c3"> + <table border="0" cellspacing="1" cellpadding="2"> + <tr> + <td class="c1">BUSYBOX</td> + </tr> + </table> + </div> + + <a href="/"><img src="images/busybox1.png" alt="BusyBox" border="0" /></a><br> +</td> +</tr> + +<tr> + +<td valign="top"> + <b>About</b> + <ul> + <li><a href="about.html">About BusyBox</a></li> + <li><a href="screenshot.html">Screenshot</a></li> + <li><a href="news.html">Announcements</a></li> + </ul> + <b>Documentation</b> + <ul> + <li><a href="FAQ.html">FAQ</a></li> + <li><a href="downloads/BusyBox.html">Command Help</a></li> + <li><a href="downloads/README">README</a></li> + </ul> + <b>Get BusyBox</b> + <ul> + <li><a href="download.html">Download Source</a></li> + <li><a href="license.html">License</a></li> + <li><a href="products.html">Products</a></li> + </ul> + <b>Development</b> + <ul> + <li><a href="/cgi-bin/viewcvs.cgi/trunk/busybox/">Browse Source</a></li> + <li><a href="subversion.html">Source Control</a></li> + <!--li><a href="/downloads/patches/recent.html">Recent Changes</a></li--> + <li><a href="lists.html">Mailing Lists</a></li> + <li><a href="http://bugs.busybox.net/">Bug Tracking</a></li> + </ul> + <p><b>Links</b> + <ul> + <li><a href="links.html">Related Sites</a></li> + <li><a href="tinyutils.html">Tiny Utilities</a></li> + <li><a href="sponsors.html">Sponsors</a></li> + </ul> + <p><b>Developer Pages</b> + <ul> + <li><a href="http://busybox.net/~landley/">Rob</a></li> + <li><a href="http://busybox.net/~aldot/">Bernhard</a></li> + <li><a href="http://busybox.net/~vda/">Denys</a> + <br>- <a href="http://busybox.net/~vda/resume/denys_vlasenko.htm">resume</a> + <br>- <a href="http://busybox.net/~vda/mboot/">mboot</a> + <br>- <a href="http://busybox.net/~vda/linld/">linld</a> + <br>- <a href="http://busybox.net/~vda/init_vs_runsv.html">init must die</a> + <br>- <a href="http://busybox.net/~vda/no_ifup.txt">no ifup</a> + <br>- <a href="http://busybox.net/~vda/unscd/">unscd</a> + </li> + </ul> +</td> + +<td valign="top"> + diff --git a/docs/busybox.net/images/back.png b/docs/busybox.net/images/back.png Binary files differnew file mode 100644 index 0000000..7992386 --- /dev/null +++ b/docs/busybox.net/images/back.png diff --git a/docs/busybox.net/images/busybox.jpeg b/docs/busybox.net/images/busybox.jpeg Binary files differnew file mode 100644 index 0000000..37edc96 --- /dev/null +++ b/docs/busybox.net/images/busybox.jpeg diff --git a/docs/busybox.net/images/busybox.png b/docs/busybox.net/images/busybox.png Binary files differnew file mode 100644 index 0000000..b1eb92f --- /dev/null +++ b/docs/busybox.net/images/busybox.png diff --git a/docs/busybox.net/images/busybox1.png b/docs/busybox.net/images/busybox1.png Binary files differnew file mode 100644 index 0000000..4d3126a --- /dev/null +++ b/docs/busybox.net/images/busybox1.png diff --git a/docs/busybox.net/images/busybox2.jpg b/docs/busybox.net/images/busybox2.jpg Binary files differnew file mode 100644 index 0000000..abf8f06 --- /dev/null +++ b/docs/busybox.net/images/busybox2.jpg diff --git a/docs/busybox.net/images/busybox3.jpg b/docs/busybox.net/images/busybox3.jpg Binary files differnew file mode 100644 index 0000000..0fab84c --- /dev/null +++ b/docs/busybox.net/images/busybox3.jpg diff --git a/docs/busybox.net/images/dir.png b/docs/busybox.net/images/dir.png Binary files differnew file mode 100644 index 0000000..1d633ce --- /dev/null +++ b/docs/busybox.net/images/dir.png diff --git a/docs/busybox.net/images/donate.png b/docs/busybox.net/images/donate.png Binary files differnew file mode 100644 index 0000000..b55621b --- /dev/null +++ b/docs/busybox.net/images/donate.png diff --git a/docs/busybox.net/images/fm.mini.png b/docs/busybox.net/images/fm.mini.png Binary files differnew file mode 100644 index 0000000..c0883cd --- /dev/null +++ b/docs/busybox.net/images/fm.mini.png diff --git a/docs/busybox.net/images/gfx_by_gimp.png b/docs/busybox.net/images/gfx_by_gimp.png Binary files differnew file mode 100644 index 0000000..d583140 --- /dev/null +++ b/docs/busybox.net/images/gfx_by_gimp.png diff --git a/docs/busybox.net/images/ltbutton2.png b/docs/busybox.net/images/ltbutton2.png Binary files differnew file mode 100644 index 0000000..9bad949 --- /dev/null +++ b/docs/busybox.net/images/ltbutton2.png diff --git a/docs/busybox.net/images/osuosl.png b/docs/busybox.net/images/osuosl.png Binary files differnew file mode 100644 index 0000000..b00b500 --- /dev/null +++ b/docs/busybox.net/images/osuosl.png diff --git a/docs/busybox.net/images/sdsmall.png b/docs/busybox.net/images/sdsmall.png Binary files differnew file mode 100644 index 0000000..b102450 --- /dev/null +++ b/docs/busybox.net/images/sdsmall.png diff --git a/docs/busybox.net/images/text.png b/docs/busybox.net/images/text.png Binary files differnew file mode 100644 index 0000000..6034f89 --- /dev/null +++ b/docs/busybox.net/images/text.png diff --git a/docs/busybox.net/images/valid-html401.png b/docs/busybox.net/images/valid-html401.png Binary files differnew file mode 100644 index 0000000..ec9bc0c --- /dev/null +++ b/docs/busybox.net/images/valid-html401.png diff --git a/docs/busybox.net/images/vh40.gif b/docs/busybox.net/images/vh40.gif Binary files differnew file mode 100644 index 0000000..c5e9402 --- /dev/null +++ b/docs/busybox.net/images/vh40.gif diff --git a/docs/busybox.net/images/written.in.vi.png b/docs/busybox.net/images/written.in.vi.png Binary files differnew file mode 100644 index 0000000..84f59bc --- /dev/null +++ b/docs/busybox.net/images/written.in.vi.png diff --git a/docs/busybox.net/index.html b/docs/busybox.net/index.html new file mode 100644 index 0000000..1bab6b0 --- /dev/null +++ b/docs/busybox.net/index.html @@ -0,0 +1 @@ +<!--#include file="news.html" --> diff --git a/docs/busybox.net/license.html b/docs/busybox.net/license.html new file mode 100644 index 0000000..2a4c51d --- /dev/null +++ b/docs/busybox.net/license.html @@ -0,0 +1,99 @@ +<!--#include file="header.html" --> + +<p> +<h3><a name="license">BusyBox is licensed under the GNU General Public License, version 2</a></h3> + +<p>BusyBox is licensed under <a href="http://www.gnu.org/licenses/gpl.html#SEC1">the +GNU General Public License</a> version 2, which is often abbreviated as GPLv2. +(This is the same license the Linux kernel is under, so you may be somewhat +familiar with it by now.)</p> + +<p>A complete copy of the license text is included in the file LICENSE in +the BusyBox source code.</p> + +<p><a href="products.html">Anyone thinking of shipping BusyBox as part of a +product</a> should be familiar with the licensing terms under which they are +allowed to use and distribute BusyBox. Read the full test of the GPL (either +through the above link, or in the file LICENSE in the busybox tarball), and +also read the <a href="http://www.gnu.org/licenses/gpl-faq.html">Frequently +Asked Questions about the GPL</a>.</p> + +<p>Basically, if you distribute GPL software the license requires that you also +distribute the source code to that GPL-licensed software. So if you distribute +BusyBox without making the source code to the version you distribute available, +you violate the license terms, and thus infringe on the copyrights of BusyBox. +(This requirement applies whether or not you modified BusyBox; either way the +license terms still apply to you.) Read the license text for the details.</p> + +<h3><a name="version">A note on GPL versions</a></h3> + +<p>Version 2 of the GPL is the only version of the GPL which current versions +of BusyBox may be distributed under. New code added to the tree is licensed +GPL version 2, and the project's license is GPL version 2.</p> + +<p>Older versions of BusyBox (versions 1.2.2 and earlier, up through about svn +16112) included variants of the recommended +"GPL version 2 or (at your option) later versions" boilerplate +permission grant. Ancient versions of BusyBox +(before svn 49) did not specify any version at all, and section 9 of GPLv2 +(the most recent version at that time) says those old versions may be +redistributed under any version of GPL (including the obsolete V1). This was +conceptually similar to a dual license, except that the different licenses were +different versions of the GPL.</p> + +<p>However, BusyBox has apparently always contained chunks of code that were +licensed under GPL version 2 only. Examples include applets written by Linus +Torvalds (util-linux/mkfs_minix.c and util_linux/mkswap.c) which stated they +"may be redistributed as per the Linux copyright" (which Linus +clarified in the +2.4.0-pre8 release announcement in 2000 was GPLv2 only), and Linux kernel code +copied into libbb/loop.c (after Linus's announcement). There are probably +more, because all we used to check was that the code was GPL, not which +version. (Before the GPLv3 draft proceedings in 2006, it was a purely +theoretical issue that didn't come up much.)</p> + +<p>To summarize: every version of BusyBox may be distributed under the terms of +GPL version 2. New versions (after 1.2.2) may <b>only</b> be distributed under +GPLv2, not under other versions of the GPL. Older versions of BusyBox might +(or might not) be distributable under other versions of the GPL. If you +want to use a GPL version other than 2, you should start with one of the old +versions such as release 1.2.2 or SVN 16112, and do your own homework to +identify and remove any code that can't be licensed under the GPL version you +want to use. New development is all GPLv2.</p> + +<h3><a name="enforce">License enforcement</a></h3> + +<p>BusyBox's copyrights are enforced by the <a +href="http://www.softwarefreedom.org/">Software Freedom Law Center</a> +(you can contact them at gpl@busybox.net), which +"accepts primary responsibility for enforcement of US copyrights on the +software... and coordinates international copyright enforcement efforts for +such works as necessary." If you distribute BusyBox in a way that doesn't +comply with the terms of the license BusyBox is distributed under, expect to +hear from these guys. Their entire reason for existing is to do pro-bono +legal work for free/open source software projects. (We used to list people who +violate the BusyBox license in <a href="shame.html">The Hall of Shame</a>, +but these days we find it much more effective to hand them over to the +lawyers.)</p> + +<p>Our enforcement efforts are aimed at bringing people into compliance with +the BusyBox license. Open source software is under a different license from +proprietary software, but if you violate that license you're still a software +pirate and the law gives the vendor (us) some big sticks to play with. We +don't want monetary awards, injunctions, or to generate bad PR for a company, +unless that's the only way to get somebody that repeatedly ignores us to comply +with the license on our code.</p> + +<h3><a name="good">A Good Example</a></h3> + +<p>These days, <a href="http://www.linksys.com/">Linksys</a> is +doing a good job at complying with the GPL, they get to be an +example of how to do things right. Please take a moment and +check out what they do with +<a href="http://www.linksys.com/servlet/Satellite?c=L_Content_C1&childpagename=US%2FLayout&cid=1115416836002&pagename=Linksys%2FCommon%2FVisitorWrapper"> +distributing the firmware for their WRT54G Router.</a> +Following their example would be a fine way to ensure that you +have also fulfilled your licensing obligations.</p> + +<!--#include file="footer.html" --> + diff --git a/docs/busybox.net/links.html b/docs/busybox.net/links.html new file mode 100644 index 0000000..14ad8d1 --- /dev/null +++ b/docs/busybox.net/links.html @@ -0,0 +1,19 @@ +<!--#include file="header.html" --> + +<h3>Related Sites</h3> + +<br><a href="http://uclibc.org/">uClibc.org</a> +<br><a href="http://cxx.uclibc.org/">uClibc++</a> +<!--br><a href="http://udhcp.busybox.net/">udhcp</a --> +<br><a href="http://buildroot.uclibc.org/">buildroot</a> +<br><a href="http://www.scratchbox.org/">Scratchbox</a> +<br><a href="http://openembedded.org/">OpenEmbedded</a> +<br><a href="http://www.ucdot.org/">uCdot</a> +<br><a href="http://www.linuxdevices.com/">LinuxDevices</a> +<br><a href="http://slashdot.org/">Slashdot</a> +<br><a href="http://freshmeat.net/">Freshmeat</a> +<br><a href="http://linuxtoday.com/">Linux Today</a> +<br><a href="http://lwn.net/">Linux Weekly News</a> +<br><a href="http://www.tldp.org/HOWTO">Linux HOWTOs</a> + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/lists.html b/docs/busybox.net/lists.html new file mode 100644 index 0000000..3a28cc0 --- /dev/null +++ b/docs/busybox.net/lists.html @@ -0,0 +1,46 @@ +<!--#include file="header.html" --> + + +<!-- Begin Introduction section --> + +<h3>Mailing List Information</h3> +BusyBox has a <a href="/lists/busybox/">mailing list</a> for discussion and +development. You can subscribe by visiting +<a href="http://busybox.net/mailman/listinfo/busybox">this page</a>. +Only subscribers to the BusyBox mailing list are allowed to post +to this list. + +<p> +There is also a mailing list for <a href="/lists/busybox-cvs/">active developers</a> +wishing to read the complete diff of each and every change to busybox -- not for the +faint of heart. Active developers can subscribe by visiting +<a href="http://busybox.net/mailman/listinfo/busybox-cvs">this page</a>. +The Subversion server is the only one permtted to post to this list. And yes, +this list name uses the word 'cvs' even though we don't use that anymore... + +<p> + + +<h3>Search the List Archives</h3> +Please search the mailing list archives before asking questions on the mailing +list, since there is a good chance someone else has asked the same question +before. Checking the archives is a great way to avoid annoying everyone on the +list with frequently asked questions... +<p> + +<center> +<form method="GET" action="http://www.google.com/custom"> +<input type="hidden" name="domains" value="busybox.net"> +<input type="hidden" name="sitesearch" value="busybox.net"> +<input type="text" name="q" size="31" maxlength="255" value=""> +<br> +<input type="submit" name="sa" value="search the mailing list archives"> +<br> +<a href="http://www.google.com"><img src="http://www.google.com/logos/Logo_25wht.gif" border="0" alt="Google" height="32" width="75" align="middle"></a> +<br> +</form> +</center> + + + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/news.html b/docs/busybox.net/news.html new file mode 100644 index 0000000..84705db --- /dev/null +++ b/docs/busybox.net/news.html @@ -0,0 +1,216 @@ +<!--#include file="header.html" --> + +<ul> + + <li> + <p>We want to thank the following companies which are providing support for the BusyBox project: + <ul> + <li>AOE media, a <a href="http://www.aoemedia.com/typo3-development.html"> + TYPO3 development agency</a> contributes financially.</li> + <li><a href="http://www.analog.com/en/">Analog Devices, Inc.</a> provided + a <a href="http://docs.blackfin.uclinux.org/doku.php?id=bf537_quick_start"> + Blackfin development board</a> free of charge. + <a href="http://www.analog.com/blackfin">Blackfin</a> + is a NOMMU processor, and its availability for testing is invaluable. + If you are an embedded device developer, + please note that Analog Devices has entire Linux distribution available + for download for this board. Visit + <a href="http://blackfin.uclinux.org/">http://blackfin.uclinux.org/</a> + for more information. + </li> + </ul> + </p> + </li> + + <li><b>28 September 2008 -- BusyBox 1.12.1 (stable), BusyBox 1.11.3 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.12.1.tar.bz2">BusyBox 1.12.1</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_12_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.12.1/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p><a href="http://busybox.net/downloads/busybox-1.11.3.tar.bz2">BusyBox 1.11.3</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_11_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.11.3/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p> + Bugfix-only releases for 1.11.x and 1.12.x branches. + </p> + </li> + + <li><b>21 August 2008 -- BusyBox 1.12.0 (unstable), BusyBox 1.11.2 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.12.0.tar.bz2">BusyBox 1.12.0</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_12_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.12.0/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p><a href="http://busybox.net/downloads/busybox-1.11.2.tar.bz2">BusyBox 1.11.2</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_11_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.11.2/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>Sizes of busybox-1.11.2 and busybox-1.12.0 (with equivalent config, static uclibc build):<pre> + text data bss dec hex filename + 829687 617 7052 837356 cc6ec busybox-1.11.2/busybox + 822961 594 6832 830387 cabb3 busybox-1.12.0/busybox +</pre> + + <p>New applets: rdev (Grant Erickson), setfont, showkey (both by Vladimir) + + <p>Most significant changes since previous release (please report any regression): + <ul> + <li>ash: bash compat: "shift $BIGNUM" is equivalent to "shift 1"</li> + <li>ash: dont allow e.g. exec <&10 to attach to script's fd! </li> + <li>ash: fix a bug where redirection fds were not closed afterwards. optimize close+fcntl(DUPFD) into dup2</li> + <li>ash: fix segfault in "command -v"</li> + <li>ash: fix very weak $RANDOM generator</li> + <li>ash: prevent exec NN>&- from closing fd used for script reading</li> + <li>ash: teach ash about 123>file. It could take only 0..9 before</li> + <li>hush: fix a case where "$@" must expand to no word at all</li> + <li>hush: fix mishandling of a'b'c=fff as assignments. They are not</li> + <li>hush: fix non-detection of builtins and applets in "v=break; ...; $v; ..." case</li> + <li>hush: fix "while false; ..." exitcode; add testsuites</li> + <li>hush: support "case...esac" statements (~350 bytes of code)</li> + <li>hush: support "break [N]" and "continue [N]" statements</li> + <li>hush: support "for if in do done then; do echo $if; done" case</li> + <li>hush: support "for v; do ... done" syntax (implied 'in "$@"')</li> + <li>hush: support $_NUMBERS variable names</li> + <li>libbb: unified config parser (by Vladimir). This change affected many applets</li> + </ul> + + <p>Other changes: + <ul> + <li>libbb: dump: do not use uninitialized memory (closes bug 4364)</li> + <li>libbb: fix bb_strtol[l]'s check for "-" (closes bug 4174)</li> + <li>libbb: fix --help to not affect "test --help"</li> + <li>libbb: fix mishandling of "all argv are opts" in getopt32()</li> + <li>libbb: getopt32() should not ever touch argv[0] (even read)</li> + <li>libbb: introduce and use xrealloc_vector</li> + <li>libbb: [x]fopen_for_{read,write} introduced and used (by Vladimir)</li> + <li>lineedit: fix use-after-free</li> + <li>libunarchive: refactor handling of archived files. "tar f file.tar.lzma" now works too</li> + <li>bb_strtoXXX: close bug 4174 (potential use of buf[-1])</li> + <li>open_transformer: don't leak file descriptor</li> + <li>open_transformer: fix bug of calling exit instead of _exit</li> + <li>arp: without -H type, assume "ether" (closes bug 4564)</li> + <li>ar: reuse existing ar unpacking code</li> + <li>awk: fix a case with multiple -f options. Simplify -f file reading. </li> + <li>build system: introduce and use FAST_FUNC: regparm on i386, otherwise no-op</li> + <li>bunzip2: fix an uncompression error (by Rob Landley rob AT landley.net)</li> + <li>b[un]zip2, g[un]zip: unlink destination if -f is given (closes bug 3854)</li> + <li>comm: almost total rewrite</li> + <li>cpio: fix -m to actually work as expected (by Pascal Bellard)</li> + <li>cpio: internalize archive_xread_all_eof, add a few paranoia checks for corrupted cpio files</li> + <li>cpio: make long opts depend only on ENABLE_GETOPT_LONG</li> + <li>cpio: on unpack, limit filename length to 8k</li> + <li>cpio: support some long options</li> + <li>crond: use execlp instead of execl</li> + <li>cut: fix buffer overflow (closes bug 4544)</li> + <li>envdir: fix "envdir" (no params at all) and "envdir dir" cases</li> + <li>findfs: make it use setuid-ness of busybox binary</li> + <li>fsck: use getmntent_r instead of open-coded parsing (by Vladimir)</li> + <li>fuser: a bit of safety in scanf</li> + <li>grep: option to use GNU regex matching instead of POSIX one. This fixes problems with NULs in files being scanned, but costs +800 bytes</li> + <li>halt: signal init regardless of ENABLE_INIT</li> + <li>httpd: add homedir directive specially for (and by) Walter Harms wharms AT bfs.de</li> + <li>ifupdown: /etc/network/interfaces can have comments with leading blanks</li> + <li>ifupdown: fixes for custom MAC address (by Wade Berrier wberrier AT gmail.com)</li> + <li>ifupdown: fixes for shutdown of DHCP-managed interfaces (by Wade Berrier wberrier AT gmail.com)</li> + <li>inetd: do not trash errno in signal handlers; in CHLD handler, stop looping through services when pid is found</li> + <li>insmod: users report that "|| defined(__powerpc__)" is missing</li> + <li>install: do not chown intermediate directories with install -d (by Natanael Copa)</li> + <li>install: fix long option not taking params (closes bug 4584)</li> + <li>lpd,lpr: send/receive ACKs after filenames, not only after file bodies</li> + <li>ls: fix a bug where we may use uninintialized variable</li> + <li>man: add handling of "man links", by Ivana Varekova varekova AT redhat.com</li> + <li>man: fix a case when a full pathname to manpage is given</li> + <li>man: fix inverted cat/man bool variable</li> + <li>man: fix missed NULL termination of an array</li> + <li>man: mimic "no manual entry for 'bogus'" message and exitcode</li> + <li>man: support cat pages too (by Jason Curl jcurlnews AT arcor.de)</li> + <li>man: teach it to use .lzma if requested by .config</li> + <li>mdev: check for "/block/" substring for block dev detection</li> + <li>mdev: do not complain if mdev.conf does not exist</li> + <li>mdev: if device was moved at creation, at removal correctly remove it from moved location and also remove symlinks to it</li> + <li>mdev: support for serializing hotplug</li> + <li>mdev, init: use shared code for fd sanitization</li> + <li>mkdir: fix "uname 0222; mkdir -p foo/bar" case (by Doug Graham dgraham AT nortel.com)</li> + <li>modprobe: support for /etc/modprobe.d (by Timo Teras)</li> + <li>modprobe: use buffering line reads (fgets()) instead of reads()</li> + <li>modutils: optional modprobe-small (by Vladimir), 15kb smaller than standard one</li> + <li>mount: support for "-o mand" and "[no]relatime"</li> + <li>mount: support nfs mount option "nordiplus" (by Octavian Purdila opurdila AT ixiacom.com)</li> + <li>mount: support "relatime" / "norelatime"</li> + <li>mount: testsuite for "-o mand"</li> + <li>msh: fix "while... continue; ..." (closes bug 3884)</li> + <li>mv: fix a case when we move dangling symlink across mountpoints</li> + <li>netstat: optional -p support (by L. Gabriel Somlo somlo AT cmu.edu)</li> + <li>nmeter: fix read past the end of a buffer (closes bug 4594)</li> + <li>od, hexdump: fix bug where xrealloc may move pointer, leaving other pointers dangling (closes bug 4104)</li> + <li>pidof/killall: allow find_pid_by_name to find running processes started as scripts_with_name_longer_than_15_bytes.sh (closes bug 4054)</li> + <li>printf: do not print garbage on "%Ld" (closes bug 4214)</li> + <li>printf: fix %b, fix several bugs in %*.*, fix compat issues with aborting too early, support %zd; expand testsuite</li> + <li>printf: protect against bogus format specifiers (closes bug 4184)</li> + <li>sendmail: updates from Vladimir:</li> + <li>sendmail: do not discard all headers</li> + <li>sendmail: do not ignore CC; accept to: and cc: case-insensitively. +20 bytes</li> + <li>sendmail: fixed mail recipient address</li> + <li>sendmail: fixed SEGV if sender address is missed</li> + <li>sendmail: use HOSTNAME instead of HOST when no server is explicitly specified</li> + <li>sleep: if FANCY && DESKTOP, support fractional seconds, minutes, hours and so on (coreutils compat)</li> + <li>ssd: CLOSE_EXTRA_FDS in MMU case too</li> + <li>ssd: do not stat -x EXECUTABLE, it is not needed anymore</li> + <li>ssd: fix -a without -x case</li> + <li>ssd: use $PATH</li> + <li>tar: fix handling of tarballs with symlinks with size field != 0</li> + <li>tar: handle autodetection for tiny .tar.gz files too, simplify autodetection</li> + <li>taskset: fix some careless code in both fancy and non-fancy cases. -5 bytes for fancy, +5 for non-fancy</li> + <li>tee: fix infinite looping on open error (echo asd | tee "")</li> + <li>tee: "-" is a name for stdout, handle it that way</li> + <li>telnetd: fix issue file printing</li> + <li>test: fix parser to prefer binop over unop, as coreutils does</li> + <li>testsuite: uniformly use $ECHO with -n -e</li> + <li>time: don't segfault with no arguments</li> + <li>touch: support -r REF_FILE if ENABLE_DESKTOP (needed for blackfin compile)</li> + <li>tr: fix "access past the end of a string" bug 4354</li> + <li>tr: fix "tr [=" case (closes bug 4374)</li> + <li>tr: fix yet another access past the end of a string (closes bug 4374)</li> + <li>unlzma: fix memory leak (by Pascal Bellard)</li> + <li>vi: fix reversed checks for underflow</li> + <li>vi: using array data after it fell out of scope is stupid</li> + <li>xargs: fix -e default to match newer GNU xargs, add SUS mandated -E (closes bug 4414)</li> + <li>other fixes and code size reductions in many applets</li> + </ul> + <p> + The email address gpl@busybox.net is the recommended way to contact + the Software Freedom Law Center to report BusyBox license violations. + </p> + + <li><b>12 July 2008 -- BusyBox 1.11.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.11.1.tar.bz2">BusyBox 1.11.1</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_11_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.11.1/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p> + Bugfix-only release for 1.11.x branch. It contains fixes for awk, + bunzip2, cpio, ifupdown, ip, man, start-stop-daemon, uname and vi. + </p> + </li> + + <li><b>11 July 2008 -- HOWTO is updated</b> + <p> + <a href="http://busybox.net/~vda/HOWTO/i486-linux-uclibc/HOWTO.txt"> + "How to build static busybox for i486-linux-uclibc"</a> is updated + and tested on a fresh Fedora 9 install. Please report if it doesn't + work for you. + </p> + </li> + + + + <li><b>Old News</b><p> + Click here to read <a href="oldnews.html">older news</a> + </p> + </li> + +</ul> + +<!--#include file="footer.html" --> + diff --git a/docs/busybox.net/oldnews.html b/docs/busybox.net/oldnews.html new file mode 100644 index 0000000..5747136 --- /dev/null +++ b/docs/busybox.net/oldnews.html @@ -0,0 +1,2214 @@ +<!--#include file="header.html" --> + +<h3>News archive</h3> + +<ul> + + <li><b>25 June 2008 -- BusyBox 1.11.0 (unstable), BusyBox 1.10.4 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.11.0.tar.bz2">BusyBox 1.11.0</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_11_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.11.0/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p><a href="http://busybox.net/downloads/busybox-1.10.4.tar.bz2">BusyBox 1.10.4</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_10_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.10.4/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p>Sizes of busybox-1.10.4 and busybox-1.11.0 (with equivalent config, static uclibc build):<pre> + text data bss dec hex filename + 800675 636 7080 808391 c55c7 busybox-1.10.4 + 798392 611 6900 805903 c4c0f busybox-1.11.0 +</pre> + + <p>New applets: inotify (Vladimir Dronnikov), man (Ivana Varekova), + fbsplash (Michele Sanges), depmod (Bernhard Reutner-Fischer) + + <p>Changes since previous release: + <ul> + <li>build system: reinstate CONFIG_CROSS_COMPILE_PREFIX</li> + <li>ash: optional bash compatibility features added; other fixes</li> + <li>hush: lots and lots of fixes</li> + <li>msh: fix the case where the file has exec bit but can't be run directly (runs "$SHELL file" instead)</li> + <li>msh: fix exit codes when command is not found or can't be execed</li> + <li>udhcpc: added workaround for buggy kernels</li> + <li>mount: fix mishandling of proto=tcp/udp</li> + <li>diff: make it work on non-seekable streams</li> + <li>openvt: made more compatible with "standard" one</li> + <li>mdev: fix block/char device detection</li> + <li>ping: add -w, -W support (James Simmons)</li> + <li>crond: add handling of "MAILTO=user" lines</li> + <li>start-stop-daemon: make --exec follow symlinks (Joakim Tjernlund)</li> + <li>date: make it accept ISO date format</li> + <li>echo: fix echo -e -n "msg\n\0" (David Pinedo)</li> + <li>httpd: fix several bugs triggered by relative path in -h DIR</li> + <li>printf: fix printf -%s- foo, printf -- -%s- foo</li> + <li>syslogd: do not error out on missing files to rotate</li> + <li>ls: support Unicode in names</li> + <li>ip: support for the LOWER_UP flag (Natanael Copa)</li> + <li>mktemp: make argument optional (coreutil 6.12 compat)</li> + <li>libiproute: fix option parsing, so that "ip -o link" works again</li> + <li>other fixes and code size reductions in many applets</li> + </ul> + <p> + The email address gpl@busybox.net is the recommended way to contact + the Software Freedom Law Center to report BusyBox license violations. + </p> + </li> + + <li><b>12 June 2008 -- Sponsors!</b> + <p>We want to thank the following companies which are providing support + for the BusyBox project: + </p> + <ul> + <li>AOE media, a <a href="http://www.aoemedia.com/typo3-development.html"> + TYPO3 development agency</a> contributes financially.</li> + <li><a href="http://www.analog.com/en/">Analog Devices, Inc.</a> provided + a <a href="http://docs.blackfin.uclinux.org/doku.php?id=bf537_quick_start"> + Blackfin development board</a> free of charge. + <a href="http://www.analog.com/blackfin">Blackfin</a> + is a NOMMU processor, and its availability for testing is invaluable. + If you are an embedded device developer, + please note that Analog Devices has entire Linux distribution available + for download for this board. Visit + <a href="http://blackfin.uclinux.org/">http://blackfin.uclinux.org/</a> + for more information. + </li> + </ul> + </li> + + <li><b>5 June 2008 -- BusyBox 1.10.3 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.10.3.tar.bz2">BusyBox 1.10.3</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_10_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.10.3/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p> + Bugfix-only release for 1.10.x branch. It contains fixes for dnsd, fuser, hush, + ip, mdev and syslogd. + </p> + </li> + + <li><b>8 May 2008 -- BusyBox 1.10.2 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.10.2.tar.bz2">BusyBox 1.10.2</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_10_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.10.2/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p> + Bugfix-only release for 1.10.x branch. It contains fixes for echo, httpd, pidof, + start-stop-daemon, tar, taskset, tab completion in shells, build system. + <p>Please note that mdev was backported from current svn trunk. Please + report if you encounter any problems with it. + </p> + </li> + + <li><b>19 April 2008 -- BusyBox 1.10.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.10.1.tar.bz2">BusyBox 1.10.1</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_10_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.10.1/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p> + Bugfix-only release for 1.10.x branch. It contains fixes for + fuser, init, less, nameif, tail, taskset, tcpudp, top, udhcp. + </li> + + <li><b>21 March 2008 -- BusyBox 1.10.0 (unstable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.10.0.tar.bz2">BusyBox 1.10.0</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_10_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.10.0/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>Sizes of busybox-1.9.2 and busybox-1.10.0 (with almost full config, static uclibc build):<pre> + text data bss dec hex filename + 781405 679 7500 789584 c0c50 busybox-1.9.2 + 773551 640 7372 781563 becfb busybox-1.10.0 +</pre> + <p>Top 10 stack users:<pre> +busybox-1.9.2: busybox-1.10.0: +echo_dg 4116 bb_full_fd_action 4112 +bb_full_fd_action 4112 find_list_entry2 4096 +discard_dg 4108 readlink_main 4096 +discard_dg 4096 ipaddr_list_or_flush 3900 +echo_stream 4096 iproute_list_or_flush 3680 +discard_stream 4096 insmod_main 3152 +find_list_entry2 4096 fallbackSort 2952 +readlink_main 4096 do_iproute 2492 +ipaddr_list_or_flush 3900 cal_main 2464 +iproute_list_or_flush 3680 readhere 2308 +</pre> + + <p>New applets: brctl, chat (by Vladimir Dronnikov <dronnikov AT gmail.com>), + findfs, ifenslave (closes bug 115), lpd (by Vladimir Dronnikov <dronnikov AT gmail.com>), + lpr+lpq (by Walter Harms), script (by Pascal Bellard <pascal.bellard AT ads-lu.com>), + sendmail (Vladimir Dronnikov <dronnikov AT gmail.com>), tac, tftpd. + </p> + <p>Made NOMMU-compatible: crond, crontab, ifupdown, inetd, init, runsv, svlogd, tcpsvd, udpsvd. + </p> + <p>Changes since previous release: + </p> + <ul> + <li>globally: add -Wunused-parameter</li> + <li>globally: add optimization barrier to all "G trick" locations</li> + <li>adduser/addgroup: check username for invalid chars (by Tito <farmatito AT tiscali.it>)</li> + <li>adduser: optional support for long options. Closes bug 2134</li> + <li>ash: handle "A=1 A=2 B=$A; echo $B". Closes bug 947</li> + <li>ash: make ash -c "if set -o barfoo 2>/dev/null; then echo foo; else echo bar; fi" work. Closes bug 1142</li> + <li>build system: don't use "gcc -o /dev/null", old gcc can delete /dev/null in this case</li> + <li>build system: fixes for cross-compiling on an OS X host</li> + <li>build system: make it do without "od -t"</li> + <li>build system: pass CFLAGS to link stage too. Closes bug 1376</li> + <li>build system: add CONFIG_NOMMU</li> + <li>cp: add ENABLE_FEATURE_VERBOSE_CP_MESSAGE. Closes bug 1470</li> + <li>crontab: almost complete rewrite</li> + <li>dnsd: properly set _src_ IP:port on outgoing UDP packets</li> + <li>dpkg: fix bug where existence check was reversed</li> + <li>eject: add -s for SCSI- and USB-devices (Nico Erfurth)</li> + <li>fdisk: fix a case where break was reached only for DOS labels</li> + <li>fsck: don't kill pid -1! (Roy Marples <roy at marples.name>)</li> + <li>fsck_minix: fix bug in map_block2: s/(blknr >= 256 * 256)/(blknr < 256 * 256)/</li> + <li>fuser: substantial rewrite</li> + <li>getopt: add support for "a+" specifier for nonnegative int parameters. By Vladimir Dronnikov <dronnikov at gmail.com></li> + <li>getty: don't try to detect parity on local lines (Joakim Tjernlund <Joakim.Tjernlund at transmode.se>)</li> + <li>halt: write wtmp entry if wtmp support is enabled</li> + <li>httpd: "HEAD" support. Closes bug 1530</li> + <li>httpd: fix bug 2004: wrong argv when interpreter is invoked</li> + <li>httpd: fix bug where we did chdir("") if CGI path had only one "/"</li> + <li>httpd: fix for POST upload</li> + <li>httpd: support for "I:index.xml" syntax (Peter Korsgaard <jacmet AT uclibc.org>)</li> + <li>hush: fix a case where none of pipe members could be started because of fork failure</li> + <li>hush: more correct handling of piping</li> + <li>hush: reinstate `cmd` handling for NOMMU</li> + <li>hush: report [v]fork failures</li> + <li>hush: set CLOEXEC on script file being executed</li> + <li>hush: try to add a bit more of vfork-friendliness</li> + <li>inetd: make "udp nowait" work</li> + <li>inetd: make inetd IPv6-capable</li> + <li>init: add FEATURE_KILL_REMOVED (Eugene Bordenkircher <eugebo AT gmail.com>)</li> + <li>init: allow last line of config file to be not terminated by "\n"</li> + <li>init: do not die if "/dev/null" is missing</li> + <li>init: fix bug 1111: restart actions were not splitting words</li> + <li>init: wait for orphaned children too while waiting for sysinit-like processes (harald-tuxbox AT arcor.de)</li> + <li>ip route: "ip route" was misbehaving (extra argv+1 ate 1st env var)</li> + <li>last: do not go into endless loop on read error</li> + <li>less,klogd,syslogd,nc,tcpudp: exit on signal by killing itself, not exit(1)</li> + <li>less: "examine" command will not bomb out on bad file name now</li> + <li>less: fix bug where backspace wasn't actually deleting chars</li> + <li>less: make it a bit more resistant against status line corruption</li> + <li>less: improve search when data is not supplied fast enough by stdin - now will try reading for 1-2 seconds before declaring that there is no match. This fixes a very common annoyance with long manpages</li> + <li>less: update line input so that it doesn't interfere with screen update. Makes "man bash", [enter], [/], <enter search pattern>, [enter] more usable - manpage now draws even as you enter the pattern!</li> + <li>libbb: filename completion matches dangling symlinks too</li> + <li>libbb: fix getopt state corruption for NOFORK applets</li> + <li>libbb: full_read/write now will report partial data counts prior to error</li> + <li>libbb: intrduce and use safe_gethostname. By Tito <farmatito AT tiscali.it></li> + <li>libbb: introduce and use nonblock_safe_read(). Yay! Our shells are immune from this nasty O_NONBLOCK now!</li> + <li>login,su: avoid clearing environment with some options, as was intended</li> + <li>microcom: read more than 1 byte from device, if possible</li> + <li>microcom: split -d (delay) option away from -t</li> + <li>mktemp: support -p DIR (Timo Teras <timo.teras at iki.fi>)</li> + <li>mount: #ifdef out MOUNT_LABEL code parts if it is not selected</li> + <li>mount: add another mount helper call method</li> + <li>mount: allow and ignore _netdev option</li> + <li>mount: make -f work even without mtab support (Cristian Ionescu-Idbohrn <cristian.ionescu-idbohrn at axis.com>)</li> + <li>mount: optional support for -vv verbosity</li> + <li>mount: plug a hole where FEATURE_MOUNT_HELPERS could allow execution of arbitrary command</li> + <li>mount: recognize "dirsync" (closes bug 835)</li> + <li>mount: sanitize environment if called by non-root</li> + <li>mount: support for mount by label. Closes bug 1143</li> + <li>mount: with -vv -f, say what mount() calls we were going to make</li> + <li>msh: create testsuite (based on hush one)</li> + <li>msh: don't use floating point in "times" builtin</li> + <li>msh: fix Ctrl-C handling with line editing</li> + <li>msh: fix for bug 846 ("break" didn't work second time)</li> + <li>msh: glob0/glob1/glob2/glob3 were just a sorting routine, removed</li> + <li>msh: instead of fixing "ls | cd", "cd | ls" etc disallow builtins in pipes. They make no sense there anyway</li> + <li>msh: stop trying to parse variables in "msh SCRIPT VAR=val param". They are passed as ordinary parameters</li> + <li>netstat: print control chars as "^C" etc</li> + <li>nmeter: fix bug where %[mf] behaves as %[mt]</li> + <li>nohup: compat patch by Christoph Gysin <mailinglist.cache at gmail.com></li> + <li>od: handle /proc files (which have filesize 0) correctly</li> + <li>patch: don't trash permissions of patched file</li> + <li>ps: add conditional support for -o [e]time</li> + <li>ps: fix COMMAND column adjustment; overflow in USER and VSZ columns</li> + <li>reset: call "stty sane". Closes bug 1414</li> + <li>rmdir: optional long options support for Debian users. By Roberto Gordo Saez <roberto.gordo AT gmail.com></li> + <li>run-parts: add --reverse</li> + <li>script: correctly handle buffered "tail" of output</li> + <li>sed: "n" command must reset "we had successful subst" flag. Closes bug 1214</li> + <li>sort: -z outputs NUL terminated lines. Closes bug 1591</li> + <li>stty: fix mishandling of control keywords (Ralf Friedl <Ralf.Friedl AT online.de>)</li> + <li>switch_root: stop at first non-option. Closes bug 1425</li> + <li>syslogd: avoid excessive time() system calls</li> + <li>syslogd: don't die if remote host's IP cannot be resolved. Retry resolutions every two minutes instead</li> + <li>syslogd: fix shmat error check</li> + <li>syslogd: optional support for dropping dups. Closes bug 436</li> + <li>syslogd: send "\n"-terminated messages over the network. Fully closes bug 1574</li> + <li>syslogd: tighten up hostname handling</li> + <li>tail: fix "tail -c 20 /dev/huge_disk" (was taking ages)</li> + <li>tar: compat: handle tarballs with only one zero block at the end</li> + <li>tar: autodetection of gz/bz2 compressed tarballs. Closes bug 992</li> + <li>tar: real support for -p. By Natanael Copa <natanael.copa at gmail.com></li> + <li>tcpudp: narrow down time window where we have no wildcard socket</li> + <li>telnetd: use login always, not "sometimes login, sometimes shell"</li> + <li>test: fix mishandling of "test ! arg1 op arg2 more args"</li> + <li>trylink: instead of build error, disable --gc-sections if GLIBC and STATIC are selected</li> + <li>udhcp: make file paths configurable</li> + <li>udhcp: optional support for non-standard DHCP ports</li> + <li>udhcp: set correct op byte in the packet for DHCPDECLINE</li> + <li>udhcpc: filter unwanted packets in kernel (Cristian Ionescu-Idbohrn <cristian.ionescu-idbohrn AT axis.com>)</li> + <li>udhcpc: fix wrong options in decline and release packets (Jonas Danielsson <jonas.danielsson AT axis.com>)</li> + <li>umount: do not complain several times about the same mountpoint</li> + <li>umount: do not try to free loop device or erase mtab if remounted ro</li> + <li>umount: instead of non-standard -D, use -d with opposite meaning. Closes bug 1604</li> + <li>unlzma: shrink by Pascal Bellard <pascal.bellard AT ads-lu.com></li> + <li>unzip: do not try to read entire compressed stream at once (it can be huge)</li> + <li>unzip: handle short reads correctly</li> + <li>vi: many fixes</li> + <li>zcip: don't chdir to root</li> + <li>zcip: open ARP socket before openlog (else we can trash syslog socket)</li> + </ul> + </li> + + <li><b>21 March 2008 -- BusyBox old stable releases</b> + <p> + Bugfix-only releases for four past branches. Links to locations + for future hot patches are in parentheses. + <p> + <a href="http://busybox.net/downloads/busybox-1.9.2.tar.bz2">1.9.2</a> + (<a href="http://busybox.net/downloads/fixes-1.9.2/">patches</a>), + <a href="http://busybox.net/downloads/busybox-1.8.3.tar.bz2">1.8.3</a> + (<a href="http://busybox.net/downloads/fixes-1.8.3/">patches</a>), + <a href="http://busybox.net/downloads/busybox-1.7.5.tar.bz2">1.7.5</a> + (<a href="http://busybox.net/downloads/fixes-1.7.5/">patches</a>), + <a href="http://busybox.net/downloads/busybox-1.5.2.tar.bz2">1.5.2</a> + (<a href="http://busybox.net/downloads/fixes-1.5.2/">patches</a>). + <p> + <a href="http://busybox.net/fix.html">How to add a patch.</a> + </p> + + + <li><b>12 February 2008 -- BusyBox 1.9.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.9.1.tar.bz2">BusyBox 1.9.1</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_9_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.9.1/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>This is a bugfix-only release, with fixes to fsck, + iproute, mdev, mkswap, msh, nameif, stty, test, zcip.</p> + <p>hush has `command` expansion re-enabled for NOMMU, although it is + inherently unsafe (by virtue of NOMMU's use of vfork instead of fork). + The plan is to make this less likely to bite people in future versions.</p> + </li> + + <li><b>24 December 2007 -- BusyBox 1.9.0 (unstable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.9.0.tar.bz2">BusyBox 1.9.0</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_9_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.9.0/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>Sizes of busybox-1.8.2 and busybox-1.9.0 (with almost full config, static uclibc build):<pre> + text data bss dec hex filename + 792796 978 9724 803498 c42aa busybox-1.8.2 + 783803 683 7508 791994 c15ba busybox-1.9.0 +</pre> + <p>Top 10 stack users:<pre> +busybox-1.8.2: busybox-1.9.0: +input_tab 10428 echo_dg 4116 +umount_main 8252 bb_full_fd_action 4112 +rtnl_talk 8240 discard_dg 4096 +xrtnl_dump_filter 8240 echo_stream 4096 +sendMTFValues 5316 discard_stream 4096 +mainSort 4700 find_list_entry2 4096 +mkfs_minix_main 4288 readlink_main 4096 +grave 4260 ipaddr_list_or_flush 3900 +unix_do_one 4156 iproute_list_or_flush 3680 +parse_prompt 4132 insmod_main 3152 +</pre> + + <p>lash is deleted from this release. hush can be configured down to almost + the same size, but it is significantly less buggy. It even works + on NOMMU machines (interactive mode and backticks are not working on NOMMU, + though). "lash" applet is still available, but it runs hush. + + <p>init has some changes in this release, please report if it causes + problems for you. + + <p>Changes since previous release: + <ul> + <li>Build system improvements + <li>Testsuite additions + <li>Stack size reductions, code size reductions, data/bss reductions + <li>An option to prefer IPv4 address if host has both + <li>New applets: hd, sestatus + <li>Removed applets: lash + <li>hush: fixed a few bugs, wired up echo and test to be builtins + <li>init: simplify forking of children + <li>getty: special handling of '#' and '@' is removed + <li>[su]login: sanitize environment if called by non-root + <li>udhcpc: support "bad" servers which send oversized packets + (Cristian Ionescu-Idbohrn <cristian.ionescu-idbohrn at axis.com>) + <li>udhcpc: -O option allows to specify which options to ask for + (Stefan Hellermann <stefan at the2masters.de>) + <li>udhcpc: optionally check whether given IP is really free (by ARP ping) + (Jonas Danielsson <jonas.danielsson at axis.com>) + <li>vi: now handles files with unlimited line length + <li>vi: speedup for huge line lengths + <li>vi: Del key works + <li>sed: support GNUism '\t' + <li>cp/mv/install: optionally use bigger buffer for bulk copying + <li>line editing: don't eat stack like crazy + <li>passwd: follows symlinked /etc/passwd + <li>renice: accepts priority with +N too + <li>netstat: wide output mode + <li>nameif: extended matching (Nico Erfurth <masta at perlgolf.de>) + <li>test: become NOFORK applet + <li>find: -iname (Alexander Griesser <alexander.griesser at lkh-vil.or.at>) + <li>df: -i option (show inode info) (Pascal Bellard <pascal.bellard at ads-lu.com>) + <li>hexdump: -R option (Pascal Bellard <pascal.bellard at ads-lu.com>) + </ul> + </li> + + <li><b>23 November 2007 -- BusyBox 1.8.2 (stable), BusyBox 1.7.4 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.8.2.tar.bz2">BusyBox 1.8.2</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_8_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.8.2/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + <p><a href="http://busybox.net/downloads/busybox-1.7.4.tar.bz2">BusyBox 1.7.4</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_7_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.7.4/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>These are bugfix-only releases. + 1.8.2 contains fixes for inetd, lash, tar, tr, and build system. + 1.7.4 contains a fix for inetd.</p> + </li> + + <li><b>9 November 2007 -- BusyBox 1.8.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.8.1.tar.bz2">BusyBox 1.8.1</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_8_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.8.1/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>This is a bugfix-only release, with fixes to login (PAM), modprobe, syslogd, telnetd, unzip.</p> + </li> + + <li><b>4 November 2007 -- BusyBox 1.8.0 (unstable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.8.0.tar.bz2">BusyBox 1.8.0</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_8_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.8.0/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>Note: this is probably the very last release with lash. It will be dropped. Please migrate to hush. + + <p>Applets which had many changes since 1.7.x: + <p>httpd: + <ul> + <li>does not clear environment, CGIs will see all environment variables which were set for httpd + <li>fix bug where we were trying to read more POSTDATA than content-length + <li>fix trivial bug (spotted by Alex Landau) + <li>optional support for partial downloads + <li>simplified CGI i/o loop (now it looks good to me) + <li>small auth and IPv6 fixes (Kim B. Heino <Kim.Heino at bluegiga.com>) + <li>support for proxying connection to other http server (by Alex Landau <landau_alex at yahoo.com>) + </ul> + + <p>top: + <ul> + <li>TOPMEM feature - 's(how sizes)' command + <li>don't wait before final bailout (try top -b -n1) + <li>fix for command line wrapping + </ul> + + <p>Build system improvements: libbusybox mode restored (it was lost in transition to new makefiles). + + <p>Code and data size in comparison with 1.7.3:<pre> +Equivalent .config, i386 uclibc static builds: + text data bss dec hex filename + 768123 1055 10768 779946 be6aa busybox-1.7.3/busybox + 759693 974 9420 770087 bc027 busybox-1.8.0/busybox</pre> + + <p>New applets: + <ul> + <li>microcom: new applet by Vladimir Dronnikov <dronnikov at gmail.ru> + <li>kbd_mode: new applet by Loic Grenie <loic.grenie at gmail.com> + <li>bzip2: port bzip2 1.0.4 to busybox, 9 kb of code + <li>pgrep, pkill: new applets by Loic Grenie <loic.grenie at gmail.com> + <li>setsebool: new applet (Yuichi Nakamura <ynakam at hitachisoft.jp>) + </ul> + + <p>Other changes since previous release (abridged): + <ul> + <li>cp: -r and -R imply -d (coreutils compat) + <li>cp: detect and prevent infinite recursion + <li>cp: make it a bit closer to POSIX, but still refuse to open and overwrite symbolic link + <li>hdparm: reduce possibility of numeric overflow in -T + <li>hdparm: simplify timing measurement + <li>wget: -O FILE is allowed to overwrite existing file (compat) + <li>wget: allow dots in header field names + <li>telnetd: add -K option to close sessions as soon as child exits + <li>telnetd: don't SIGKILL child when closing the session, kernel will send SIGHUP for us + <li>ed: large cleanup, add line editing + <li>hush: feeble attempt at making it more NOMMU-friendly + <li>hush: fix glob() + <li>hush: stop doing manual accounting of open fd's, kernel can do it for us + <li>adduser: implement -S and fix uid selection + <li>ash: fix prompt expansion (Natanael Copa <natanael.copa at gmail.com>) + <li>ash: revert "cat | jobs" fix, it causes more problems than good + <li>find: fix -xdev behavior in the presence of two or more nested mount points + <li>grep: fix grep -F -e str1 -e str2 (was matching str2 only) + <li>grep: optimization: stop on first -e match + <li>gunzip: support concatenated gz files + <li>inetd: fix bug 1562 "inetd does not set argv[0] properly" (fix by Ilya Panfilov) + <li>install: 'support' (by ignoring) -v and -b + <li>install: fix bug in "install -c file dir" (tried to copy dir into dir too) + <li>ip: tunnel parameter parsing fix by Jean Wolter <jw5 at os.inf.tu-dresden.de> + <li>isrv: use monotonic_sec + <li>less: make 'f' key page forward + <li>libiproute: add missing break statements + <li>load_policy: update (Yuichi Nakamura <ynakam at hitachisoft.jp>) + <li>logger: fix a problem of losing all argv except first + <li>login: do reject wrong passwords with PAM auth + <li>losetup: support -f (Loic Grenie <loic.grenie at gmail.com>) + <li>fdisk: make fdisk compile on libc without llseek64 + <li>libbb: by popular request allow PATH to be customized at build time + <li>mkswap: selinux support by KaiGai Kohei <kaigai at ak.jp.nec.com> + <li>mount: allow (and ignore) -i + <li>mount: ignore NFS bg option on NOMMU machines + <li>mount: mount helpers support (by Vladimir Dronnikov <dronnikov at gmail.ru>) + <li>passwd: handle Ctrl-C, restore termios on Ctrl-C + <li>passwd: SELinux support by KaiGai Kohei <kaigai at ak.jp.nec.com> + <li>ping: make -I ethN work too (-I addr already worked) + <li>ps: fix RSS parsing (rss field in /proc/PID/stat is in pages, not bytes) + <li>read_line_input: fix it to not do any fancy editing if echoing is disabled + <li>run_parts: make it sort executables by name (required by API) + <li>runsv: do not use clock_gettime if !MONOTONIC_CLOCK + <li>runsvdir: fix "linear wait time" bug + <li>sulogin: remove alarm handling, it is redundant there + <li>svlogd: compat: svlogd -tt should timestamp stderr too + <li>syslogd: bail out if you see null read from Unix socket + <li>syslogd: do not need to poll(), we can just block in read() + <li>tail: work correctly on /proc files (Kazuo TAKADA <kztakada at sm.sony.co.jp>) + <li>tar + gzip/bzip2/etc: support NOMMU machines (by Alex Landau <landau_alex at yahoo.com>) + <li>tar: strip leading '/' BEFORE memorizing hardlink's name + <li>tftp: fix infinite retry bug + <li>umount: support (by ignoring) -i; style fixes + <li>unzip: fix endianness bugs + <li>vi: don't wait 50 ms before reading ESC sequences + <li>watchdog: allow millisecond spec (-t 250ms) + <li>zcip: fix unaligned trap on ARM + </ul> + </li> + + <li><b>4 November 2007 -- BusyBox 1.7.3 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.7.3.tar.bz2">BusyBox 1.7.3</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_7_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.7.3/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>This is a bugfix-only release, with fixes to ash, httpd, inetd, iptun, logger, login, tail.</p> + </li> + + <li><b>30 September 2007 -- BusyBox 1.7.2 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.7.2.tar.bz2">BusyBox 1.7.2</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_7_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.7.2/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>This is a bugfix-only release, with fixes to install, find, login, httpd, runsvdir, chcon, setfiles, fdisk and line editing.</p> + </li> + + <li><b>16 September 2007 -- BusyBox 1.7.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.7.1.tar.bz2">BusyBox 1.7.1</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_7_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.7.1/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>This is a bugfix-only release, with fixes to cp, runsv, tar, busybox --install and build system.</p> + </li> + + <li><b>24 August 2007 -- BusyBox 1.7.0 (unstable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.7.0.tar.bz2">BusyBox 1.7.0</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_7_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.7.0/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>Applets which had many changes since 1.6.x: + <p>httpd: + <ul> + <li>works in standalone mode on NOMMU machines now (partly by Alex Landau <landau_alex at yahoo.com>) + <li>indexer example is rewritten in C + <li>optional support for error pages (by Pierre Metras <genepi at sympatico.ca>) + <li>stop reading headers using 1-byte reads + <li>new option -v[v]: prints client addresses, HTTP codes returned, URLs + <li>extended -p PORT to -p [IP[v6]:]PORT + <li>sendfile support (by Pierre Metras <genepi at sympatico.ca>) + <li>add support for Status: CGI header + <li>fix CGI handling bug (we were closing wrong fd) + <li>CGI I/O loop still doesn't look 100% ok to me... + </ul> + + <p>udhcp[cd]: + <ul> + <li>add -f "foreground" and -S "syslog" options + <li>fixed "ifupdown + udhcpc_without_pidfile_creation" bug + <li>new config option "Rewrite the lease file at every new acknowledge" (Mats Erik Andersson <mats at blue2net.com> (Blue2Net AB)) + <li>consistently treat server_config.start/end IPs as host-order + <li>fix IP parsing for 64bit machines + <li>fix unsafe hton macro usage in read_opt() + <li>do not chdir to / when daemonizing + </ul> + + <p>top, ps, killall, pidof: + <ul> + <li>simpler loadavg processing + <li>truncate usernames to 8 chars + <li>fix non-CONFIG_DESKTOP ps -ww (by rockeychu) + <li>improve /proc/PID/cmdinfo reading code + <li>use cmdline, not comm field (fixes problems with re-execed applets showing as processes with name "exe", and not being found by pidof/killall by applet name) + <li>reduce CPU usage in decimal conversion (optional) (corresponding speedup on kernel side is accepted in mainline Linux kernel, yay!) + <li>make percentile (0.1%) calculations configurable + <li>add config option and code for global CPU% display + <li>reorder columns, so that [P]PIDs are together and VSZ/%MEM are together - makes more sense + </ul> + + <p>Build system improvements: doesn't link against libraries we don't need, + generates verbose link output and map file, allows for custom link + scripts (useful for removing extra padding, among other things). + + <p>Code and data size in comparison with 1.6.1:<pre> +Equivalent .config, i386 glibc dynamic builds: + text data bss dec hex filename + 672671 2768 16808 692247 a9017 busybox-1.6.1/busybox + 662948 2660 13528 679136 a5ce0 busybox-1.7.0/busybox + 662783 2631 13416 678830 a5bae busybox-1.7.0/busybox.customld + +Same .config built against static uclibc: + 765021 1059 11020 777100 bdb8c busybox-1.7.0/busybox_uc</pre> + + <p>Code/data shrink done in applets: crond, hdparm, dd, cal, od, nc, expr, uuencode, + test, slattach, diff, ping, tr, syslogd, hwclock, zcip, find, pidof, ash, uudecode, + runit/*, in libbb. + + <p>New applets: + <ul> + <li>pscan, expand, unexpand (from Tito <farmatito at tiscali.it>) + <li>setfiles, restorecon (by Yuichi Nakamura <ynakam at hitachisoft.jp>) + <li>chpasswd (by Alexander Shishkin <virtuoso at slind.org>) + <li>slattach, ttysize + </ul> + + <p>Unfortunately, not much work is done on shells. This was mostly stalled + by lack of time (read: laziness) on my part to learn how to adapt existing + qemu-runnable image for a NOMMU architechture (available on qemu website) + for local testing of cross-compiled busybox on my machine. + + <p>Other changes since previous release (abridged): + <ul> + <li>addgroup: disallow addgroup -g num user group; make -g 0 work (Tito <farmatito at tiscali.it>) + <li>adduser: close /etc/{passwd,shadow} before calling passwd etc. Spotted by Natanael Copa <natanael.copa at gmail.com> + <li>arping: -i should be -I, fixed + <li>ash: make "jobs | cat" work like in bash (was giving empty output) + <li>ash: recognize -l as --login equivalent; do not recognize +-login + <li>ash: fix buglet in DEBUG code (Nguyen Thai Ngoc Duy <pclouds at gmail.com>) + <li>ash: fix SEGV if type has zero parameters + <li>awk: fix -F 'regex' bug (miscounted fields if last field is empty) + <li>catv: catv without arguments was trying to use environ as argv (Alex Landau <landau_alex at yahoo.com>) + <li>catv: don't die on open error (emit warning) + <li>chown/chgrp: completely match coreutils 6.8 wrt symlink handling + <li>correct_password: do not print "no shadow passwd..." message + <li>crond: don't start sendmail with absolute path, don't report obsolete version (report true bbox version) + <li>dd: fix bug where we assume count=INT_MAX when count is unspecified + <li>devfsd: sanitization by Tito <farmatito at tiscali.it> + <li>echo: fix non-fancy echo + <li>fdisk: make it work with big disks (read: typical today's disks) even if CONFIG_LFS is unset + <li>find: -context support for SELinux (KaiGai Kohei <kaigai at kaigai.gr.jp>) + <li>find: add conditional support for -maxdepth and -regex, make -size match GNU find + <li>find: fix build failure on certain configs (found by Cristian Ionescu-Idbohrn <cristian.ionescu-idbohrn at axis.com>) + <li>fsck_minix: make it print bb version, not it's own (outdated/irrelevant) one + <li>grep: implement -m MAX_MATCHES, fix buglets with context printing + <li>grep: fix selection done by FEATURE_GREP_EGREP_ALIAS (Maxime Bizon <mbizon at freebox.fr> (Freebox)) + <li>hush: add missing dependencies (Maxime Bizon <mbizon at freebox.fr> (Freebox)) + <li>hush: fix read builtin to not read ahead past EOL and to not use insane amounts of stack + <li>ifconfig: make it work with ifaces with interface no. > 255 + <li>ifup/ifdown: make location of ifstate configurable + <li>ifupdown: make netmask parsing smaller and more strict (was accepting 255.0.255.0, 255.1234.0.0 etc...) + <li>install: fix -s (strip) option, fix install a b /a/link/to/dir + <li>libbb: consolidate ARRAY_SIZE macro (Walter Harms <wharms at bfs.de>) + <li>libbb: make /etc/network parsing configurable. -200 bytes when off + <li>libbb: nuke BB_GETOPT_ERROR, always die if there are mutually exclusive options + <li>libbb: xioctl and friends by Tito <farmatito at tiscali.it> + <li>login: optional support for PAM + <li>login: make /etc/nologin support configurable (-240 bytes) + <li>login: ask passwords even for wrong usernames + <li>md5_sha1_sum: fix mishandling when run as /bin/md5sum + <li>mdev: add support for firmware loading + <li>mdev: work even when CONFIG_SYSFS_DEPRECATED in kernel is off + <li>modprobe: add scanning of /lib/modules/`uname -r`/modules.symbols (by Yann E. MORIN <yann.morin.1998 at anciens.enib.fr>) + <li>more: fixes by Tristan Schmelcher <tpkschme at engmail.uwaterloo.ca> + <li>nc: make connecting to IPv4 from IPv6-enabled hosts easier (was requiring -s local_addr) + <li>passwd: fix bug "updating shadow even if user's record is in passwd" + <li>patch: fix -p -1 handling + <li>patch: fix bad line ending handling (Nguyen Thai Ngoc Duy <pclouds at gmail.com>) + <li>ping: display roundtrip times with 1/1000th of ms, not 1/10 ms precision. + <li>ping: fix incorrect handling of -I (Iouri Kharon <bc-info at styx.cabel.net>) + <li>ping: fix non-fancy ping6 + <li>printenv: fix "printenv VAR1 VAR2" bug (spotted by Kalyanatejaswi Balabhadrapatruni <kalyanatejaswi at yahoo.co.in>) + <li>ps: fix -Z (by Yuichi Nakamura <ynakam at hitachisoft.jp>) + <li>rpm: add optional support for bz2 data. +50 bytes of code + <li>rpm: fix bogus "package is not installed" case + <li>sed: fix 'q' command handling (by Nguyen Thai Ngoc Duy <pclouds at gmail.com>) + <li>start_stop_daemon: NOMMU fixes by Alex Landau <landau_alex at yahoo.com> + <li>stat: fix option -Z SEGV + <li>strings: strings a b was processing a twice, fix that + <li>svlogd: fix timestamping, do not warn if config is missing + <li>syslogd, logread: get rid of head pointer, fix logread bug in the process + <li>syslogd: do not convert tabs to ^I, set syslog IPC buffer to mode 0644 + <li>tar: improve OLDGNU compat, make old SUN compat configurable + <li>test: fix testing primary expressions like '"-u" = "-u"' + <li>uudecode: fix to base64 decode by Jorgen Cederlof <jcz at google.com> + <li>vi: multiple fixes by Natanael Copa <natanael.copa at gmail.com> + <li>wget: fix bug in base64 encoding (bug 1404). +10 bytes + <li>wget: lift 256 chars limitation on terminal width + <li>wget, zcip: use monotonic_sec instead of gettimeofday + </ul> + </li> + + <li><b>30 June 2007 -- BusyBox 1.6.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.6.1.tar.bz2">BusyBox 1.6.1</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_6_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.6.1/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>This is a bugfix-only release, with fixes to echo, hush, and wget.</p> + </li> + + <li><b>1 June 2007 -- BusyBox 1.6.0 (unstable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.6.0.tar.bz2">BusyBox 1.6.0</a>. + (<a href="http://busybox.net/cgi-bin/viewcvs.cgi/branches/busybox_1_6_stable/">svn</a>, + <a href="http://busybox.net/downloads/fixes-1.6.0/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>Since this is a x.x.0 release, it probably does not deserve "stable" + label. Please help making 1.6.1 stable by testing 1.6.0.</p> + <p>Note that hush shell had many changes and (hopefully) is much improved now, + but there is a possibility that it regressed in some obscure cases. Please + report any such cases.</p> + <p>lash users please note: lash is going to be deprecated in busybox 1.7.0 + and removed in the more distant future. Please migrate to hush.</p> + <p><a href="http://busybox.net/~vda/mem_usage-1.6.0.txt">Memory usage has decreased, but we can do better still</a></p> + <p>Other changes since previous release: + <ul> +<li>NOFORK: audit small applets and mark some of them as NOFORK. Put big scary warnings in relevant places +<li>NOFORK: factor out NOFORK/NOEXEC code from find. Use NOFORK/NOEXEC in find and xargs +<li>NOFORK: remove potential xmalloc from NOFORK path in bb_full_fd_action +<li>NOMMU: random fixes; compressed --help now works for NOMMU +<li>SELinux: load_policy applet +<li>[u]mount: extend -t option (Roy Marples <uberlord at gentoo.org>) +<li>addgroup: clean up, fix adding users to existing groups and make it optional (Tito) +<li>adduser: don't bomb out if shadow password file doesn't exist (from Tito <farmatito at tiscali.it>) +<li>applet.c: do not even try to read config if run by real root; fix suid config handling +<li>ash: fix infinite loop on exit if tty is not there anymore +<li>ash: fix kill -l (by Mats Erik Andersson <mats.andersson64 at comhem.se>) +<li>ash: implement type -p, costs less than 10 bytes (patch by Mats Erik Andersson <mats.andersson64 at comhem.se>) +<li>awk: don't segfault on printf(%*s). Closes bug 1337 +<li>awk: guard against empty environment +<li>awk: some 'lineno' vars were shorts, made them ints (code got smaller) +<li>cat: stop using stdio.h opens +<li>config system: clarify PREFER_APPLETS/SH_STANDALONE effects in help text +<li>cryptpw: new applet (by Thomas Lundquist <lists at zelow.no>) +<li>cttyhack: new applet +<li>dd: NOEXEC fix; fix skip= parse error (spotted by Dirk Clemens <develop at cle-mens.de>) +<li>deluser: add optional support for removing users from groups (by Tito <farmatito at tiscali.it>) +<li>diff: fix SEGV (NULL deref) in diff -N +<li>diff: fix segfault on empty dirs (Peter Korsgaard <peter.korsgaard at barco.com>) +<li>dnsd: fix several buglets, make smaller; openlog(), so that applet's name is logged +<li>dpkg: run_package_script() returns 0 if all ok and non-zero if failure. The result code was checked incorrectly in two places. (from Kim B. Heino <Kim.Heino at bluegiga.com>) +<li>dpkg: use bitfields which are a bit closer to typical short/char. Code size -800 bytes +<li>dumpleases: getopt32()-ization (from Mats Erik Andersson <mats.andersson64 at comhem.se>) +<li>e2fsprogs: stop using statics in chattr. Minor code shrinkage (-130 bytes) +<li>ether-wake: close bug 1317. Reorder fuctions to avoid forward refs while at it +<li>ether-wake: save a few more bytes of code +<li>find: -group, -depth (Natanael Copa <natanael.copa at gmail.com>) +<li>find: add support for -delete, -path (by Natanael Copa) +<li>find: fix -prune. Add big comment about it +<li>find: improve usage text (Natanael Copa <natanael.copa at gmail.com>) +<li>find: missed 'static' on const data; size and prune were mixed up; use index_in_str_array +<li>find: un-DESKTOPize (Kai Schwenzfeier <niteblade at gmx.net>) +<li>find_root_device: teach to deal with /dev/ subdirs (by Kirill K. Smirnov <lich at math.spbu.ru>) +<li>find_root_device: use lstat - don't follow links +<li>getopt32: fix llist_t options ordering. llist_rev is now unused +<li>getopt: use getopt32 for option parsing - inspired by patch by Mats Erik Andersson <mats.andersson64 at comhem.se> +<li>hdparm: fix multisector mode setting (from Toni Mirabete <amirabete at catix.cat>) +<li>hdparm: make -T -t code smaller (-194 bytes), and output prettier +<li>ifupdown: make it possible to use DHCP clients different from udhcp +<li>ifupdown: reread state file before rewriting it. Fixes "ifup started another ifup" state corruption bug. Patch by Natanael Copa <natanael.copa at gmail.com> +<li>ifupdown: small optimization (avoid doing useless work if we are not going to update state file) +<li>ip: fix compilation if FEATURE_TR_CLASSES is off +<li>ip: mv ip*_main into ip.c; use a dispatcher to save on needless duplication. Saves a minor 12b +<li>ip: rewrite the ip applet to be less bloaty. Convert to index_in_(sub)str_array() +<li>ip: set the scope properly. Thanks to Jean Wolter +<li>iplink: shrink iplink; sanitize libiproute a bit (-916 bytes) +<li>iproute: shrink a bit (-200 bytes) +<li>kill: know much more signals; make code smaller; use common code for kill applet and ash kill builtin +<li>klogd: remove dependency on syslogd +<li>lash: "forking" applets are actually can be treated the same way as "non-forked". Also save a bit of space on trailing NULL array elements. +<li>lash: fix kill buglet (didn't properly recognize ESRCH) +<li>lash: make -c work; crush buffer overrun and free of non-malloced ptr (from Mats Erik Andersson <mats.andersson64 at comhem.se>) +<li>lash: recognize and use NOFORK applets +<li>less: fix case when regex search finds nothing; fix very obscure memory corruption bug; fix less <HUGEFILE + [End] busy loop +<li>libbb: add xsendto, xunlink, xpipe +<li>libbb: fix segfault in reset_ino_dev_hashtable() when *hashtable was NULL +<li>libbb: make pidfile writing configurable +<li>libbb: make xsocket die with address family printed (if VERBOSE_RESOLUTION_ERRORS=y) +<li>libbb: rework NOMMU helper API so that it makes more sense and easier to use +<li>libiproute: audit callgraph, shortcut error paths into die() functions +<li>lineedit: do not try to open NULL history file +<li>lineedit: nuke two unused variables and code which sets them +<li>login: remove setpgrp call (makes it work from shell prompt again); sanitize stdio descriptors (we are suid, need to be careful!) +<li>login: shrink login and set_environment by ~100 bytes +<li>mount: fix incorrect usage of strtok (inadvertently used NULL sometimes) +<li>mount: fix mounting of symlinks (mount from util-linux allows that) +<li>msh: data/bss reduction (more than 9k of it); fix "underscore bug" (a_b=1111 didn't work); fix obscure case with backticks and closed fd 1 +<li>nc: port nc 1.10 to busybox +<li>netstat: fix for bogus state value for raw sockets +<li>netstat: introduce -W: wide, ipv6-friendly output; shrink by ~500 bytes +<li>nmeter: should die if stdout doesn't like him anymore +<li>patch: do not try to delete same file twice +<li>ping: fix wrong sign extension of packet id (bug 1373) +<li>ps: add -o tty and -o rss support; make a bit smaller; work around libc bug: printf("%.*s\n", MAX_INT, buffer) +<li>run_parts: rewrite +<li>run_parts: do not check path portion of a name for "bad chars". Needed for ifupdown. Patch by Gabriel L. Somlo <somlo at cmu.edu> +<li>sed: fix escaped newlines in -f +<li>split: new applet +<li>stat: remove superfluous bss user (flags) and manually unswitch some areas +<li>stty: fix option parsing bug (spotted by Sascha Hauer <s.hauer at pengutronix.de>) +<li>svlogd: fix 'SEGV on uninitialized data' and make it honor TERM +<li>tail: fix SEGV on "tail -N" +<li>ipsvd: tcpsvd,udpsvd are new applets, GPL-ed 'clones' of Dan Bernstein's tcpserver. Author: Gerrit Pape <pape at smarden.org>, http://smarden.sunsite.dk/ipsvd/ +<li>test: close bug 1371; plug a memory leak; code size reduction +<li>tftp: code diet, and I think retransmits were broken +<li>tr: fix bug where we did not reject invalid classes like '[[:alpha'. debloat while at it +<li>udhcp: MAC_BCAST_ADDR and blank_chaddr are in fact constant, move to rodata; use pipe instead of socketpair +<li>udhcp[cd]: stop using atexit magic fir pidfile removal; stop deleting our own pidfile if we daemonize +<li>xargs: shrink code, ~80 bytes; simplify word list management +<li>zcip: make it work on NOMMU (+ improve NOMMU support machinery) + </ul> + </li> + + <li><b>20 May 2007 -- BusyBox 1.5.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.5.1.tar.bz2">BusyBox 1.5.1</a>. + (<a href="http://busybox.net/downloads/fixes-1.5.1/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>This is a bugfix-only release, with fixes to hdparm, hush, ifupdown, ps + and sed.</p> + </li> + + <li><b>23 March 2007 -- BusyBox 1.5.0 (unstable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.5.0.tar.bz2">BusyBox 1.5.0</a>. + (<a href="http://busybox.net/downloads/fixes-1.5.0/">patches</a>, + <a href="http://busybox.net/fix.html">how to add a patch</a>)</p> + + <p>Since this is a x.x.0 release, it probably does not deserve "stable" + label. Please help making 1.5.1 stable by testing 1.5.0.</p> + <p>Notable changes since previous release: + <ul> + <li>find: added support for -user, -not, fixed -mtime, -mmin, -perm + <li>[de]archivers: merge common logic into one module + <li>ping[6]: unified code for both + <li>less: regex search improved + <li>ash: more readable code, testsuite added + <li>sed: several very obscure bugs fixed + <li>chown: -H, -L, -P support (required by POSIX) + <li>tar: handle (broken) checksums a-la Sun; tar restores mode again + <li>grep: implement -w, "implement" -a and -I by ignoring them + <li>cp: more sane behavior when overwriting existing files + <li>init: stop doing silly things with the console (-400 bytes) + <li>httpd: make httpd usable for NOMMU CPUs; fix POSTDATA handling bugs + <li>httpd: run interpreter for configured file extensions in any dir, + not only in /cgi-bin/ + <li>chrt: new applet + <li>SELinux: SELinux-related code and -Z option added to several applets, + new SELinux-specific applets: chcon, runcon. + <li>Build system: produces link map, uses -Wwrite-strings to catch + improper usage of string constants. + <li>Data and bss section usage audited and reduced - should help NOMMU + targets. + <li>Applets with bug fixes: gunzip, vi, syslogd, dpkg, ls, adjtimex, resize, + sv, printf, diff, awk, sort, dpkg, diff, tftp + <li>Applets with usability improvements: swapon, more, ifup/ifdown, hwclock, + udhcpd, start_stop_daemon, cmp + <li>Applets with code cleaned up: telnet, fdisk, fsck_minix, mkfs_minix, + syslogd, swapon, runsv, svlogd, klogd + </ul> + </li> + + <li><b>18 March 2007 -- BusyBox 1.4.2 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.4.2.tar.bz2">BusyBox 1.4.2</a>. + </p> + + <p>This release includes only trivial fixes accumulated since 1.4.1. + </p> + </li> + + <li><b>25 January 2007 -- BusyBox 1.4.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.4.1.tar.bz2">BusyBox 1.4.1</a>. + (<a href="http://busybox.net/downloads/fixes-1.4.1/">patches</a>)</p> + + <p>This release includes only trivial fixes accumulated since 1.4.0. + </p> + </li> + + <li><b>20 January 2007 -- BusyBox 1.4.0 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.4.0.tar.bz2">BusyBox 1.4.0</a>. + (<a href="http://busybox.net/downloads/fixes-1.4.0/">patches</a>)</p> + + <p>Since this is a x.x.0 release, it probably is a bit less "stable" + than usual.</p> + <p>Changes since previous release: + <ul> + <li>e2fsprogs are mostly removed from busybox. Some smaller parts remain, + the rest of it sits disabled in e2fsprogs/old_e2fsprogs/*, because + it's too bloated. Really. I'm afraid it's about the only way we can + ever get e2fsprogs cleaned up. + <li>less: many improvements. Now can display binary files + (although I expect it to have trouble with displays where 8bit chars + don't have 1-to-1 char/glyph relationship). Regexp search is not buggy + anymore. Less does not read entire input up-front. Reads input + as it appears (yay!). Works rather nice as man pager. I recommend it + for general use now. + <li>IPv6: generic support is in place, many networking applets are + upgraded to be IPv6 capable. Probably some work remains, but it is + already much better than what we had previously. + <li>arp: new applet (thanks to Eric Spakman). + <li>fakeidentd: non-forking standalone server part was taking ~90% + of the applet. Factored it out (in fact, rewrote it). + <li>syslogd: mostly rewritten. + <li>decompress_unzip, gzip: sanitized a bit. + <li>sed: better hadling of NULs + <li>httpd: stop adding our own "Content-type:" to CGI output + <li>chown: user.grp works again. + <li>minor bugfixes to: passwd, date, tftp, start_stop_daemon, tar, + ps, ifupdown, time, su, stty, awk, ping[6], sort,... + </ul> + </li> + + <li><b>20 January 2007 -- BusyBox 1.3.2 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.3.2.tar.bz2">BusyBox 1.3.2</a>.</p> + + <p>This release includes only one trivial fix accumulated since 1.3.1 + </p> + </li> + + <li><b>27 December 2006 -- BusyBox 1.3.1 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.3.1.tar.bz2">BusyBox 1.3.1</a>. + (<a href="http://busybox.net/downloads/fixes-1.3.1/">patches</a>)</p> + + <p>Closing 2006 with new release. It includes only trivial fixes accumulated since 1.3.0 + </p> + </li> + + <li><b>14 December 2006 -- BusyBox 1.3.0 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.3.0.tar.bz2">BusyBox 1.3.0</a>. + (<a href="http://busybox.net/downloads/fixes-1.3.0/">patches</a>)</p> + + <p>This release has CONFIG_DESKTOP option which enables features + needed for busybox usage on desktop machine. For example, find, chmod + and chown get several less frequently used options, od is significantly + bigger but matches GNU coreutils, etc. Intended to eventually make + busybox a viable alternative for "standard" utilities for slightly + adventurous desktop users. + <p>Changes since previous release: + <ul> + <li>find: taking many more of standard options + <li>ps: POSIX-compliant -o implemented + <li>cp: added -s, -l + <li>grep: added -r, fixed -h + <li>watch: make it exec child like standard one does (was totally + incompatible) + <li>tar: fix limitations which were preventing bbox tar usage + on big directories: long names and linknames, pax headers + (Linux kernel tarballs have that). Fixed a number of obscure bugs. + Raised max file limit (now 64Gb). Security fixes (/../ attacks). + <li>httpd: added -i (inetd), -f (foreground), support for + directory indexer CGI (example is included), bugfixes. + <li>telnetd: fixed/improved IPv6 support, inetd+standalone support, + other fixes. Useful IPv6 stuff factored out into libbb. + <li>runit/*: new applets adapted from http://smarden.sunsite.dk/runit/ + (these are my personal favorite small-and-beautiful toys) + <li>minor bugfixes to: login, dd, mount, umount, chmod, chown, ln, udhcp, + fdisk, ifconfig, sort, tee, mkswap, wget, insmod. + </ul> + <p>Note that GnuPG key used to sign this release is different. + 1.2.2.1 is also signed post-factum now. Sorry for the mess. + </p> + </li> + + <li><b>29 October 2006 -- BusyBox 1.2.2.1 (fix)</b> + <p><a href="http://busybox.net/downloads/busybox-1.2.2.1.tar.bz2">BusyBox 1.2.2.1</a>.</p> + + <p>Added compile-time warning that static linking against glibc + produces buggy executables. + </li> + + <li><b>24 October 2006 -- BusyBox 1.2.2 (stable)</b> + <p>It's a bit overdue, but + <a href="http://busybox.net/downloads/busybox-1.2.2.tar.bz2">here is + BusyBox 1.2.2</a>.</p> + + <p>This release has dozens of fixes backported from the ongoing development + branch. There are a couple of bugfixes to sed, two fixes to documentation + generation (BusyBox.html shouldn't have USE() macros in it anymore), fix + umount to report the right errno on failure and to umount block devices by + name with newer kernels, fix mount to handle symlinks properly, make mdev + delete device nodes when called for hotplug remove, fix a segfault + in traceroute, a minor portability fix to md5sum option parsing, a build + fix for httpd with old gccs, an options parsing tweak to hdparm, make test + fail gracefully when getgroups() returns -1, fix a race condition in + modprobe when two instances run at once (hotplug does this), make "tar xf + foo.tar dir/dir" extract all subdirectories, make our getty initialize the + terminal more like mingetty, an selinux build fix, an endianness fix in + ping6, fix for zcip defending addresses, clean up some global variables in + gzip to save memory, fix sulogin -tNNN, a help text tweak, several warning + fixes and build fixes, fixup dnsd a bit, and a partridge in a pear tree.</p> + + <p>As <a href="http://lwn.net/Articles/202106/">Linux Weekly News noted</a>, + this is my (Rob's) last release of BusyBox. The new maintainer is Denis + Vlasenko, I'm off to do <a href="http://landley.net/code">other things</a>. + </p> + </li> + + <li><b>29 September 2006 -- New license email address.</b> + <p>The email address gpl@busybox.net is now the recommended way to contact + the Software Freedom Law Center to report BusyBox license violations.</p> + + <li><b>31 July 2006 -- BusyBox 1.2.1 (stable)</b> + <p>Since nobody seems to have objected too loudly over the weekend, I + might as well point you all at + <a href="http://busybox.net/downloads/busybox-1.2.1.tar.bz2">Busybox + 1.2.1</a>, a bugfix-only release with no new features.</p> + + <p>It has three shell fixes (two to lash: going "var=value" without + saying "export" should now work, plus a missing null pointer check, and + one to ash when redirecting output to a file that fills up.) Fix three + embarassing thinkos in the new dmesg command. Two build tweaks + (dependencies for the compressed usage messages and running make in the + libbb subdirectory). One fix to tar so it can extract git-generated + tarballs (rather than barfing on the pax extensions). And a partridge + in a pear... Ahem.</p> + + <p>But wait, there's more! A passwd changing fix so an empty + gecos field doesn't trigger a false objection that the new passwd contains + the gecos field. Make all our setuid() and setgid() calls check the return + value in case somebody's using per-process resource limits that prevent + a user from having too many processes (and thus prevent a process from + switching away from root, in which case the process will now _die_ rather + than continue with root privileges). A fix to adduser to make sure that + /etc/group gets updated. And a fix to modprobe to look for modules.conf + in the right place on 2.6 kernels.</p> + + <li><b>30 June 2006 -- BusyBox 1.2.0</b> + <p>The -devel branch has been stabilized and the result is + <a href="http://busybox.net/downloads/busybox-1.2.0.tar.bz2">Busybox + 1.2.0</a>. Lots of stuff changed, I need to work up a decent changelog + over the weekend.</p> + + <p>I'm still experimenting with how long is best for the development + cycle, and since we've got some largeish projects queued up I'm going to + try a longer one. Expect 1.3.0 in December. (Expect 1.2.1 any time + we fix enough bugs. :)</p> + + <p>Update: Here are <a href="http://busybox.net/downloads/busybox-1.2.0.fixes.patch">the first few bug fixes</a> that will go into 1.2.1.</p> + + <li><b>17 May 2006 -- BusyBox 1.1.3 (stable)</b> + <p><a href="http://busybox.net/downloads/busybox-1.1.3.tar.bz2">BusyBox + 1.1.3</a> is another bugfix release. It makes passwd use salt, fixes a + memory freeing bug in ls, fixes "build all sources at once" mode, makes + mount -a not abort on the first failure, fixes msh so ctrl-c doesn't kill + background processes, makes patch work with patch hunks that don't have a + timestamp, make less's text search a lot more robust (the old one could + segfault), and fixes readlink -f when built against uClibc.</p> + + <p>Expect 1.2.0 sometime next month, which won't be a bugfix release.</p> + + <li><b>10 April 2006 -- BusyBox 1.1.2 (stable)</b> + <p>You can now download <a href="http://busybox.net/downloads/busybox-1.1.2.tar.bz2">BusyBox 1.1.2</a>, a bug fix release consisting of 11 patches + backported from the development branch: Some build fixes, several fixes + for mount and nfsmount, a fix for insmod on big endian systems, a fix for + find -xdev, and a fix for comm. Check the file "changelog" in the tarball + for more info.</p> + + <p>The next new development release (1.2.0) is slated for June. A 1.1.3 + will be released before then if more bug fixes crop up. (The new plan is + to have a 1.x.0 new development release every 3 months, with 1.x.y stable + bugfix only releases based on that as appropriate.)</p> + + <li><b>27 March 2006 -- Software Freedom Law Center representing BusyBox and uClibc</b> + <p>One issue Erik Andersen wanted to resolve when handing off BusyBox + maintainership to Rob Landley was license enforcement. BusyBox and + uClibc's existing license enforcement efforts (pro-bono representation + by Erik's father's law firm, and the + <a href="http://www.busybox.net/shame.html">Hall of Shame</a>), haven't + scaled to match the popularity of the projects. So we put our heads + together and did the obvious thing: ask Pamela Jones of + <a href="http://www.groklaw.net">Groklaw</a> for suggestions. She + referred us to the fine folks at softwarefreedom.org.</p> + + <p>As a result, we're pleased to announce that the + <a href="http://www.softwarefreedom.org">Software Freedom Law Center</a> + has agreed to represent BusyBox and uClibc. We join a number of other + free and open source software projects (such as + <a href="http://lwn.net/Articles/141806/">X.org</a>, + <a href="http://lwn.net/Articles/135413/">Wine</a>, and + <a href="http://plone.org/foundation/newsitems/software-freedom-law-center-support/">Plone</a> + in being represented by a fairly cool bunch of lawyers, which is not a + phrase you get to use every day.</p> + + <li><b>22 March 2006 -- BusyBox 1.1.1</b> + <p>The new maintainer is Rob Landley, and the new release is <a href="http://busybox.net/downloads/busybox-1.1.1.tar.bz2">BusyBox 1.1.1</a>. Expect a "what's new" document in a few days. (Also, Erik and I have have another announcement pending...)</p> + <p>Update: Rather than put out an endless stream of 1.1.1.x releases, + the various small fixes have been collected together into a + <a href="http://busybox.net/downloads/busybox-1.1.1.fixes.patch">patch</a>, + and new fixes will be appended to that as needed. Expect 1.1.2 around + June.</p> + </li> + <li><b>11 January 2006 -- 1.1.0 is out</b> + <p>The new stable release is + <a href="http://www.busybox.net/downloads/busybox-1.1.0.tar.bz2">BusyBox + 1.1.0</a>. It has a number of improvements, including several new applets. + (It also has <a href="http://www.busybox.net/lists/busybox/2006-January/017733.html">a few rough spots</a>, + but we're trying out a "release early, release often" strategy to see how + that works. Expect 1.1.1 sometime in March.)</p> + + <li><b>31 October 2005 -- 1.1.0-pre1</b> + <p>The development branch of busybox is stable enough for wider testing, so + you can now + <a href="http://www.busybox.net/downloads/busybox-1.1.0-pre1.tar.bz2">download</a>, + the first prerelease of 1.1.0. This prerelease includes a lot of + <a href="http://www.busybox.net/downloads/BusyBox.html">new + functionality</a>: new applets, new features, and extensive rewrites of + several existing applets. This prerelease should be noticeably more + <a href="http://www.opengroup.org/onlinepubs/009695399/">standards + compliant</a> than earlier versions of busybox, although we're + still working out the <a href="http://bugs.busybox.net">bugs</a>.</p> + + <li><b>16 August 2005 -- 1.01 is out</b> + + <p>A new stable release (<a href="http://www.busybox.net/downloads/busybox-1.01.tar.bz2">BusyBox + 1.01</a>) is now available for download, containing over a hundred + <a href="http://www.busybox.net/lists/busybox/2005-August/015424.html">small + fixes</a> that have cropped up since the 1.00 release.</p> + + <li><b>13 January 2005 -- Bug and Patch Tracking</b><p> + + Bug reports sometimes get lost when posted to the mailing list. The + developers of BusyBox are busy people, and have only so much they can keep + in their brains at a time. In my case, I'm lucky if I can remember my own + name, much less a bug report posted last week... To prevent your bug report + from getting lost, if you find a bug in BusyBox, please use the + <a href="http://bugs.busybox.net/">shiny new Bug and Patch Tracking System</a> + to post all the gory details. + + <p> + + The same applies to patches... Regardless of whether your patch + is a bug fix or adds spiffy new features, please post your patch + to the Bug and Patch Tracking System to make certain it is + properly considered. + + + <p> + <li><b>13 October 2004 -- BusyBox 1.00 released</b><p> + + When you take a careful look at nearly every embedded Linux device or + software distribution shipping today, you will find a copy of BusyBox. + With countless routers, set top boxes, wireless access points, PDAs, and + who knows what else, the future for Linux and BusyBox on embedded devices + is looking very bright. + + <p> + + It is therefore with great satisfaction that I declare each and every + device already shipping with BusyBox is now officially out of date. + The highly anticipated release of BusyBox 1.00 has arrived! + + <p> + + Over three years in development, BusyBox 1.00 represents a tremendous + improvement over the old 0.60.x stable series. Now featuring a Linux + KernelConf based configuration system (as used by the Linux kernel), + Linux 2.6 kernel support, many many new applets, and the development + work and testing of thousands of people from around the world. + + <p> + + If you are already using BusyBox, you are strongly encouraged to upgrade to + BusyBox 1.00. If you are considering developing an embedded Linux device + or software distribution, you may wish to investigate if using BusyBox is + right for your application. If you need help getting started using + BusyBox, if you wish to donate to help cover expenses, or if you find a bug + and need help reporting it, you are invited to visit the <a + href="FAQ.html">BusyBox FAQ</a>. + + <p> + + As usual you can <a href="downloads">download busybox here</a>. + + <p>Have Fun! + + <p> + <li><b>Old News</b><p> + <a href="/oldnews.html">Click here to read older news</a> + + + <li><b>16 August 2004 -- BusyBox 1.0.0-rc3 released</b><p> + + Here goes release candidate 3... + <p> + The <a href="downloads/Changelog">changelog</a> has all the details. + And as usual you can <a href="downloads">download busybox here</a>. + + <p>Have Fun! + + <p> + <li><b>26 July 2004 -- BusyBox 1.0.0-rc2 released</b><p> + + Here goes release candidate 2... + <p> + The <a href="downloads/Changelog">changelog</a> has all the details. + And as usual you can <a href="downloads">download busybox here</a>. + + <p>Have Fun! + + <p> + <li><b>20 July 2004 -- BusyBox 1.0.0-rc1 released</b><p> + + Here goes release candidate 1... This fixes all (most?) of the problems + that have turned up since -pre10. In particular, loading and unloading of + kernel modules with 2.6.x kernels should be working much better. + <p> + + I <b>really</b> want to get BusyBox 1.0.0 released soon and I see no real + reason why the 1.0.0 release shouldn't happen with things pretty much as + is. BusyBox is in good shape at the moment, and it works nicely for + everything that I'm doing with it. And from the reports I've been getting, + it works nicely for what most everyone else is doing with it as well. + There will eventually be a 1.0.1 anyway, so we might as well get on with + it. No, BusyBox is not perfect. No piece of software ever is. And while + there is still plenty that can be done to improve things, most of that work + is waiting till we can get a solid 1.0.0 release out the door.... + <p> + + Please do not bother to send in patches adding cool new features at this + time. Only bug-fix patches will be accepted. If you have submitted a + bug-fixing patch to the busybox mailing list and no one has emailed you + explaining why your patch was rejected, it is safe to say that your patch + has been lost or forgotten. That happens sometimes. Please re-submit your + bug-fixing patch to the BusyBox mailing list, and be sure to put "[PATCH]" + at the beginning of the email subject line! + + <p> + The <a href="downloads/Changelog">changelog</a> has all the details. + And as usual you can <a href="downloads">download busybox here</a>. + + <p>Have Fun! + + <p> + On a less happy note, My 92 year old grandmother (my dad's mom) passed away + yesterday (June 19th). The funeral will be Thursday in a little town about + 2 hours south of my home. I've checked and there is absolutely no way I + could be back in time for the funeral if I attend <a + href="http://www.linuxsymposium.org/2004/">OLS</a> and give my presentation + as scheduled. + <p> + As such, it is with great reluctance and sadness that I have come + to the conclusion I will have to make my appologies and skip OLS + this year. + <p> + + + <p> + <li><b>13 April 2004 -- BusyBox 1.0.0-pre10 released</b><p> + + Ok, I lied. It turns out that -pre9 will not be the final BusyBox + pre-release. With any luck however -pre10 will be, since I <b>really</b> + want to get BusyBox 1.0.0 released very soon. As usual, please do not + bother to send in patches adding cool new features at this time. Only + bug-fix patches will be accepted. It would also be <b>very</b> helpful if + people could continue to review the BusyBox documentation and submit + improvements. + + <p> + The <a href="downloads/Changelog">changelog</a> has all the details. + And as usual you can <a href="downloads">download busybox here</a>. + + <p>Have Fun! + <p> + + + <p> + <li><b>6 April 2004 -- BusyBox 1.0.0-pre9 released</b><p> + + Here goes the final BusyBox pre-release... This is your last chance for + bug fixes. With luck this will be released as BusyBox 1.0.0 later this + week. Please do not bother to send in patches adding cool new features at + this time. Only bug-fix patches will be accepted. It would also be + <b>very</b> helpful if people could help review the BusyBox documentation + and submit improvements. I've spent a lot of time updating the + documentation to make it better match reality, but I could really use some + assistance in checking that the features supported by the various applets + match the features listed in the documentation. + + <p> + I had hoped to get this released a month ago, but + <a href="http://codepoet.org/gallery/baby_peter/img_1796"> + another release on 1 March 2004</a> has kept me busy... + + <p> + The <a href="downloads/Changelog">changelog</a> has all the details. + And as usual you can <a href="downloads">download busybox here</a>. + + <p>Have Fun! + <p> + + + <p> + <li><b>23 February 2004 -- BusyBox 1.0.0-pre8 released</b><p> + + Here goes yet another BusyBox pre-release... Please do not bother to send + in patches supplying new features at this time. Only bug-fix patches will + be accepted. If you have a cool new feature you would like to see + supported, or if you have an amazing new applet you would like to submit, + please wait and submit such things later. We really want to get a release + out we can all be proud of. We are still aiming to finish off the -pre + series in February and move on to the final 1.0.0 release... So if you + spot any bugs, now would be an excellent time to send in a fix to the + busybox mailing list. It would also be <b>very</b> helpful if people could + help review the BusyBox documentation and submit improvements. It would be + especially helpful if people could check that the features supported by the + various applets match the features listed in the documentation. + + <p> + + The <a href="downloads/Changelog">changelog</a> has all the details. + And as usual you can <a href="downloads">download busybox here</a>. + + <p>Have Fun! + <p> + + + <li><b>4 February 2004 -- BusyBox 1.0.0-pre7 released</b><p> + + There was a bug in -pre6 that broke argument parsing for a + number of applets, since a variable was not being zeroed out + properly. This release is primarily intended to fix that one + problem. In addition, this release fixes several other + problems, including a rewrite by mjn3 of the code for parsing + the busybox.conf file used for suid handling, some shell updates + from vodz, and a scattering of other small fixes. We are still + aiming to finish off the -pre series in February and move on to + the final 1.0.0 release... If you see any problems, of have + suggestions to make, as always, please feel free to email the + busybox mailing list. + + <p> + + The <a href="downloads/Changelog">changelog</a> has all + the details. And as usual you can + <a href="downloads">download busybox here</a>. + + <p>Have Fun! + <p> + + + <p> + <li><b>30 January 2004 -- BusyBox 1.0.0-pre6 released</b><p> + + Here goes the next pre-release for the new BusyBox stable + series. This release adds a number of size optimizations, + updates udhcp, fixes up 2.6 modutils support, updates ash + and the shell command line editing, and the usual pile of + bug fixes both large and small. Things appear to be + settling down now, so with a bit of luck and some testing + perhaps we can finish off the -pre series in February and + move on to the final 1.0.0 release... If you see any + problems, of have suggestions to make, as always, please + feel free to email the busybox mailing list. + + <p> + + People who rely on the <a href="downloads/snapshots/">daily BusyBox snapshots</a> + should be aware that snapshots of the old busybox 0.60.x + series are no longer available. Daily snapshots are now + only available for the BusyBox 1.0.0 series and now use + the naming scheme "busybox-<date>.tar.bz2". Please + adjust any build scripts using the old naming scheme accordingly. + + <p> + + The <a href="downloads/Changelog">changelog</a> has all + the details. And as usual you can + <a href="downloads">download busybox here</a>. + + <p>Have Fun! + <p> + + + <p> + <li><b>23 December 2003 -- BusyBox 1.0.0-pre5 released</b><p> + + Here goes the next pre-release for the new BusyBox stable + series. The most obvious thing in this release is a fix for + a terribly stupid bug in mount that prevented it from working + properly unless you specified the filesystem type. This + release also fixes a few compile problems, updates udhcp, + fixes a silly bug in fdisk, fixes ifup/ifdown to behave like + the Debian version, updates devfsd, updates the 2.6.x + modutils support, add a new 'rx' applet, removes the obsolete + 'loadacm' applet, fixes a few tar bugs, fixes a sed bug, and + a few other odd fixes. + + <p> + + If you see any problems, of have suggestions to make, as + always, please feel free to send an email to the busybox + mailing list. + + <p> + + The <a href="downloads/Changelog">changelog</a> has all + the details. And as usual you can + <a href="downloads">download busybox here</a>. + + <p>Have Fun! + <p> + + + + <li><b>10 December 2003 -- BusyBox 1.0.0-pre4 released</b><p> + + Here goes the fourth pre-release for the new BusyBox stable + series. This release includes major rework to sed, lots of + rework on tar, a new tiny implementation of bunzip2, a new + devfsd applet, support for 2.6.x kernel modules, updates to + the ash shell, sha1sum and md5sum have been merged into a + common applet, the dpkg applets has been cleaned up, and tons + of random bugs have been fixed. Thanks everyone for all the + testing, bug reports, and patches! Once again, a big + thank-you goes to Glenn McGrath (bug1) for stepping in and + helping get patches merged! + + <p> + + And of course, if you are reading this, you might have noticed + the busybox website has been completely reworked. Hopefully + things are now somewhat easier to navigate... If you see any + problems, of have suggestions to make, as always, please feel + free to send an email to the busybox mailing list. + + <p> + + The <a href="downloads/Changelog">changelog</a> has all + the details. And as usual you can + <a href="downloads">download busybox here</a>. + + <p>Have Fun! + + + + <p> + <li><b>12 Sept 2003 -- BusyBox 1.0.0-pre3 released</b><p> + + Here goes the third pre-release for the new BusyBox stable + series. The last prerelease has held up quite well under + testing, but a number of problems have turned up as the number + of people using it has increased. Thanks everyone for all + the testing, bug reports, and patches! + + <p> + + If you have submitted a patch or a bug report to the busybox + mailing list and no one has emailed you explaining why your + patch was rejected, it is safe to say that your patch has + somehow gotten lost or forgotten. That happens sometimes. + Please re-submit your patch or bug report to the BusyBox + mailing list! + + <p> + + The point of the "-preX" versions is to get a larger group of + people and vendors testing, so any problems that turn up can be + fixed prior to the final 1.0.0 release. The main feature + (besides additional testing) that is still still on the TODO + list before the final BusyBox 1.0.0 release is sorting out the + modutils issues. For the new 2.6.x kernels, we already have + patches adding insmod and rmmod support and those need to be + integrated. For 2.4.x kernels, for which busybox only supports + a limited number of architectures, we may want to invest a bit + more work before we cut 1.0.0. Or we may just leave 2.4.x + module loading alone. + + <p> + + I had hoped this release would be out a month ago. And of + course, it wasn't since Erik became busy getting a release of + <a href="http://www.uclibc.org/">uClibc</a> + out the door. Many thanks to Glenn McGrath (bug1) for + stepping in and helping get a bunch of patches merged! I am + not even going to state a date for releasing BusyBox 1.0.0 + -pre4 (or the final 1.0.0). We're aiming for late September... + But if this release proves as to be exceptionally stable (or + exceptionally unstable!), the next release may be very soon + indeed. + + <p> + + The <a href="downloads/Changelog">changelog</a> has all + the details. And as usual you can + <a href="downloads">download busybox here</a>. + + <p>Have Fun! + + + <p> + <li><b>30 July 2003 -- BusyBox 1.0.0-pre2 released</b><p> + + Here goes another pre release for the new BusyBox stable + series. The last prerelease (pre1) was given quite a lot of + testing (thanks everyone!) which has helped turn up a number of + bugs, and these problems have now been fixed. + + <p> + + Highlights of -pre2 include updating the 'ash' shell to sync up + with the Debian 'dash' shell, a new 'hdparm' applet was added, + init again supports pivot_root, The 'reboot' 'halt' and + 'poweroff' applets can now be used without using busybox init. + an ifconfig buffer overflow was fixed, losetup now allows + read-write loop devices, uClinux daemon support was added, the + 'watchdog', 'fdisk', and 'kill' applets were rewritten, there were + tons of doc updates, and there were many other bugs fixed. + <p> + + If you have submitted a patch and it is not included in this + release and Erik has not emailed you explaining why your patch + was rejected, it is safe to say that he has lost your patch. + That happens sometimes. Please re-submit your patch to the + BusyBox mailing list. + <p> + + The point of the "-preX" versions is to get a larger group of + people and vendors testing, so any problems that turn up can be + fixed prior to the final 1.0.0 release. The main feature that + is still still on the TODO list before the final BusyBox 1.0.0 + release is adding module support for the new 2.6.x kernels. If + necessary, a -pre3 BusyBox release will happen on August 6th. + Hopefully (i.e. unless some horrible catastrophic problem + turns up) the final BusyBox 1.0.0 release will be ready by + then... + <p> + + The <a href="downloads/Changelog">changelog</a> has all + the details. As usual you can <a href="downloads">download busybox here</a>. + + <p>Have Fun! + <p> + + <p> + <li><b>15 July 2003 -- BusyBox 1.0.0-pre1 released</b><p> + + The busybox development series has been under construction for + nearly two years now. Which is just entirely too long... So + it is with great pleasure that I announce the imminent release + of a new stable series. Due to the huge number of changes + since the last stable release (and the usual mindless version + number inflation) I am branding this new stable series verison + 1.0.x... + <p> + + The point of "-preX" versions is to get a larger group of + people and vendors testing, so any problems that turn up can be + fixed prior to the magic 1.0.0 release (which should happen + later this month)... I plan to release BusyBox 1.0.0-pre2 next + Monday (July 21st), and, if necessary, -pre3 on July 28th. + Hopefully (i.e. unless some horrible catastrophic problem turns + up) the final BusyBox 1.0.0 release should be ready by the end + of July. + <p> + + If you have submitted patches, and they are not in this release + and I have not emailed you explaining why your patch was + rejected, it is safe to say that I have lost your patch. That + happens sometimes. Please do <b>NOT</b> send all your patches, + support questions, etc, directly to Erik. I get hundreds of + emails every day (which is why I end up losing patches + sometimes in the flood)... The busybox mailing list is the + right place to send your patches, support questions, etc. + <p> + + I would like to especially thank Vladimir Oleynik (vodz), Glenn + McGrath (bug1), Robert Griebl (sandman), and Manuel Novoa III + (mjn3) for their significant efforts and contributions that + have made this release possible. + <p> + + As usual you can <a href="downloads">download busybox here</a>. + You don't really need to bother with the + <a href="downloads/Changelog">changelog</a>, as the changes + vs the stable version are way too extensive to easily enumerate. + But you can take a look if you really want too. + + <p>Have Fun! + <p> + + + + <p> + <li><b>26 October 2002 -- BusyBox 0.60.5 released</b><p> + + I am very pleased to announce that the BusyBox 0.60.5 (stable) + is now available for download. This is a bugfix release for + the stable series to address all the problems that have turned + up since the last release. Unfortunately, the previous release + had a few nasty bugs (i.e. init could deadlock, gunzip -c tried + to delete source files, cp -a wouldn't copy symlinks, and init + was not always providing controlling ttys when it should have). + I know I said that the previous release would be the end of the + 0.60.x series. Well, it turns out I'm a liar. But this time I + mean it (just like last time ;-). This will be the last + release for the 0.60.x series -- all further development work + will be done for the development busybox tree. Expect the development + version to have its first real release very very soon now... + + <p> + The <a href="downloads/Changelog.full">changelog</a> has all + the details. As usual you can <a href="downloads">download busybox here</a>. + <p>Have Fun! + <p> + + <p> + <li><b>18 September 2002 -- BusyBox 0.60.4 released</b><p> + + I am very pleased to announce that the BusyBox 0.60.4 + (stable) is now available for download. This is primarily + a bugfix release for the stable series to address all + the problems that have turned up since the last + release. This will be the last release for the 0.60.x series. + I mean it this time -- all further development work will be done + on the development busybox tree, which is quite solid now and + should soon be getting its first real release. + + <p> + The <a href="downloads/Changelog.full">changelog</a> has all + the details. As usual you can <a href="downloads">download busybox here</a>. + <p>Have Fun! + <p> + + + <p> + <li><b>27 April 2002 -- BusyBox 0.60.3 released</b><p> + + I am very pleased to announce that the BusyBox 0.60.3 (stable) is + now available for download. This is primarily a bugfix release + for the stable series. A number of problems have turned up since + the last release, and this should address most of those problems. + This should be the last release for the 0.60.x series. The + development busybox tree has been progressing nicely, and will + hopefully be ready to become the next stable release. + + <p> + The <a href="downloads/Changelog">changelog</a> has all + the details. As usual you can <a href="downloads">download busybox here</a>. + <p>Have Fun! + <p> + + + <p> + <li><b>6 March 2002 -- busybox.net now has mirrors!</b><p> + + Busybox.net is now much more available, thanks to + the fine folks at <a href="http://i-netinnovations.com/">http://i-netinnovations.com/</a> + who are providing hosting for busybox.net and + uclibc.org. In addition, we now have two mirrors: + <a href="http://busybox.linuxmagic.com/">http://busybox.linuxmagic.com/</a> + in Canada and + <a href="http://busybox.csservers.de/">http://busybox.csservers.de/</a> + in Germany. I hope this makes things much more + accessible for everyone! + + +<li> +<b>3 January 2002 -- Welcome to busybox.net!</b> + +<p>Thanks to the generosity of a number of busybox +users, we have been able to purchase busybox.net +(which is where you are probably reading this). +Right now, busybox.net and uclibc.org are both +living on my home system (at the end of my DSL +line). I apologize for the abrupt move off of +busybox.lineo.com. Unfortunately, I no longer have +the access needed to keep that system updated (for +example, you might notice the daily snapshots there +stopped some time ago).</p> + +<p>Busybox.net is currently hosted on my home +server, at the end of a DSL line. Unfortunately, +the load on them is quite heavy. To address this, +I'm trying to make arrangements to get busybox.net +co-located directly at an ISP. To assist in the +co-location effort, <a href= +"http://www.codepoet.org/~markw">Mark Whitley</a> +(author of busybox sed, cut, and grep) has donated +his <a href= +"http://www.netwinder.org/">NetWinder</a> computer +for hosting busybox.net and uclibc.org. Once this +system is co-located, the current speed problems +should be completely eliminated. Hopefully, too, +some of you will volunteer to set up some mirror +sites, to help to distribute the load a bit.</p> + +<p><!-- + <center> + Click here to help support busybox.net! + <form action="https://www.paypal.com/cgi-bin/webscr" method="post"> + <input type="hidden" name="cmd" value="_xclick"> + <input type="hidden" name="business" value="andersen@codepoet.org"> + <input type="hidden" name="item_name" value="Support Busybox"> + <input type="hidden" name="image_url" value="https://codepoet-consulting.com/images/busybox2.jpg"> + <input type="hidden" name="no_shipping" value="1"> + <input type="image" src="images/donate.png" border="0" name="submit" alt="Make donation using PayPal"> + </form> + </center> + --> + Since some people expressed concern over BusyBox +donations, let me assure you that no one is getting +rich here. All BusyBox and uClibc donations will be +spent paying for bandwidth and needed hardware +upgrades. For example, Mark's NetWinder currently +has just 64Meg of memory. As demonstrated when +google spidered the site the other day, 64 Megs in +not enough, so I'm going to be ordering 256Megs of +ram and a larger hard drive for the box today. So +far, donations received have been sufficient to +cover almost all expenses. In the future, we may +have co-location fees to worry about, but for now +we are ok. A <b>HUGE thank-you</b> goes out to +everyone that has contributed!<br> + -Erik</p> +</li> + +<li> +<b>20 November 2001 -- BusyBox 0.60.2 released</b> + +<p>We am very pleased to announce that the BusyBox +0.60.2 (stable) is now released to the world. This +one is primarily a bugfix release for the stable +series, and it should take care of most everyone's +needs till we can get the nice new stuff we have +been working on in CVS ready to release (with the +wonderful new buildsystem). The biggest change in +this release (beyond bugfixes) is the fact that msh +(the minix shell) has been re-worked by Vladimir N. +Oleynik (vodz) and so it no longer crashes when +told to do complex things with backticks.</p> + +<p>This release has been tested on x86, ARM, and +powerpc using glibc 2.2.4, libc5, and uClibc, so it +should work with just about any Linux system you +throw it at. See the <a href= +"downloads/Changelog">changelog</a> for <small>most +of</small> the details. The last release was +<em>very</em> solid for people, and this one should +be even better.</p> + +<p>As usual BusyBox 0.60.2 can be downloaded from +<a href= +"downloads">http://www.busybox.net/downloads</a>.</p> + +<p>Have Fun.<br> + -Erik</p> +</li> + +<li> <b>18 November 2001 -- Help us buy busybox.net!</b> + +<!-- Begin PayPal Logo --> +<center> +Click here to help buy busybox.net! +<form action="https://www.paypal.com/cgi-bin/webscr" method="post"> +<input type="hidden" name="cmd" value="_xclick"> +<input type="hidden" name="business" value="andersen@codepoet.org"> +<input type="hidden" name="item_name" value="Support Busybox"> +<input type="hidden" name="image_url" value="https://busybox.net/images/busybox2.jpg"> +<input type="hidden" name="no_shipping" value="1"> +<input type="image" src="images/donate.png" name="submit" alt="Make donation using PayPal"> +</form> +</center> +<!-- End PayPal Logo --> + +I've contacted the current owner of busybox.net and he is willing +to sell the domain name -- for $250. He also owns busybox.org but +will not part with it... I will then need to pay the registry fee +for a couple of years and start paying for bandwidth, so this will +initially cost about $300. I would like to host busybox.net on my +home machine (codepoet.org) so I have full control over the system, +but to do that would require that I increase the level of bandwidth +I am paying for. Did you know that so far this month, there +have been over 1.4 Gigabytes of busybox ftp downloads? I don't +even <em>know</em> how much CVS bandwidth it requires. For the +time being, Lineo has continued to graciously provide this +bandwidth, despite the fact that I no longer work for them. If I +start running this all on my home machine, paying for the needed bandwidth +will start costing some money. +<p> + +I was going to pay it all myself, but my wife didn't like that +idea at all (big surprise). It turns out <insert argument +where she wins and I don't> she has better ideas +about what we should spend our money on that don't involve +busybox. She suggested I should ask for contributions on the +mailing list and web page. So... +<p> + +I am hoping that if everyone could contribute a bit, we could pick +up the busybox.net domain name and cover the bandwidth costs. I +know that busybox is being used by a lot of companies as well as +individuals -- hopefully people and companies that are willing to +contribute back a bit. So if everyone could please help out, that +would be wonderful! +<p> + + +<li> <b>23 August 2001 -- BusyBox 0.60.1 released</b> +<br> + + This is a relatively minor bug fixing release that fixes + up the bugs that have shown up in the stable release in + the last few weeks. Fortunately, nothing <em>too</em> + serious has shown up. This release only fixes bugs -- no + new features, no new applets. So without further ado, + here it is. Come and get it. + <p> + The + <a href="downloads/Changelog">changelog</a> has all + the details. As usual BusyBox 0.60.1 can be downloaded from + <a href="downloads">http://busybox.net/downloads</a>. + <p>Have Fun! + <p> + + +<li> <b>2 August 2001 -- BusyBox 0.60.0 released</b> +<br> + I am very pleased to announce the immediate availability of + BusyBox 0.60.0. I have personally tested this release with libc5, glibc, + and <a href="http://uclibc.org/">uClibc</a> on + x86, ARM, and powerpc using linux 2.2 and 2.4, and I know a number + of people using it on everything from ia64 to m68k with great success. + Everything seems to be working very nicely now, so getting a nice + stable bug-free(tm) release out seems to be in order. This releases fixes + a memory leak in syslogd, a number of bugs in the ash and msh shells, and + cleans up a number of things. + + <p> + + Those wanting an easy way to test the 0.60.0 release with uClibc can + use <a href="http://user-mode-linux.sourceforge.net/">User-Mode Linux</a> + to give it a try by downloading and compiling + <a href="ftp://busybox.net/buildroot.tar.gz">buildroot.tar.gz</a>. + You don't have to be root or reboot your machine to run test this way. + Preconfigured User-Mode Linux kernel source is also on busybox.net. + <p> + Another cool thing is the nifty <a href="downloads/tutorial/index.html"> + BusyBox Tutorial</a> contributed by K Computing. This requires + a ShockWave plugin (or standalone viewer), so you may want to grab the + the GPLed shockwave viewer from <a href="http://www.swift-tools.com/Flash/flash-0.4.10.tgz">here</a> + to view the tutorial. + <p> + + Finally, In case you didn't notice anything odd about the + version number of this release, let me point out that this release + is <em>not</em> 0.53, because I bumped the version number up a + bit. This reflects the fact that this release is intended to form + a new stable BusyBox release series. If you need to rely on a + stable version of BusyBox, you should plan on using the stable + 0.60.x series. If bugs show up then I will release 0.60.1, then + 0.60.2, etc... This is also intended to deal with the fact that + the BusyBox build system will be getting a major overhaul for the + next release and I don't want that to break products that people + are shipping. To avoid that, the new build system will be + released as part of a new BusyBox development series that will + have some not-yet-decided-on odd version number. Once things + stabilize and the new build system is working for everyone, then + I will release that as a new stable release series. + + <p> + The + <a href="downloads/Changelog">changelog</a> has all + the details. As usual BusyBox 0.60.0 can be downloaded from + <a href="downloads">http://busybox.net/downloads</a>. + <p>Have Fun! + <p> + + +<li> <b>7 July 2001 -- BusyBox 0.52 released</b> +<br> + + I am very pleased to announce the immediate availability of + BusyBox 0.52 (the "new-and-improved rock-solid release"). This + release is the result of <em>many</em> hours of work and has tons + of bugfixes, optimizations, and cleanups. This release adds + several new applets, including several new shells (such as hush, msh, + and ash). + + <p> + The + <a href="downloads/Changelog">changelog</a> covers + some of the more obvious details, but there are many many things that + are not mentioned, but have been improved in subtle ways. As usual, + BusyBox 0.52 can be downloaded from + <a href="downloads">http://busybox.net/downloads</a>. + <p>Have Fun! + <p> + + +<li> <b>10 April 2001 - Graph of Busybox Growth </b> +<br> +The illustrious Larry Doolittle has made a PostScript chart of the growth +of the Busybox tarball size over time. It is available for downloading / +viewing <a href="busybox-growth.ps"> right here</a>. + +<p> (Note that while the number of applets in Busybox has increased, you +can still configure Busybox to be as small as you want by selectively +turning off whichever applets you don't need.) +<p> + + +<li> <b>10 April 2001 -- BusyBox 0.51 released</b> +<br> + + BusyBox 0.51 (the "rock-solid release") is now out there. This + release adds only 2 new applets: env and vi. The vi applet, + contributed by Sterling Huxley, is very functional, and is only + 22k. This release fixes 3 critical bugs in the 0.50 release. + There were 2 potential segfaults in lash (the busybox shell) in + the 0.50 release which are now fixed. Another critical bug in + 0.50 which is now fixed: syslogd from 0.50 could potentially + deadlock the init process and thereby break your entire system. + <p> + + There are a number of improvements in this release as well. For + one thing, the wget applet is greatly improved. Dmitry Zakharov + added FTP support, and Laurence Anderson make wget fully RFC + compliant for HTTP 1.1. The mechanism for including utility + functions in previous releases was clumsy and error prone. Now + all utility functions are part of a new libbb library, which makes + maintaining utility functions much simpler. And BusyBox now + compiles on itanium systems (thanks to the Debian itanium porters + for letting me use their system!). + <p> + You can read the + <a href="downloads/Changelog">changelog</a> for + complete details. BusyBox 0.51 can be downloaded from + <a href="downloads">http://busybox.net/downloads</a>. + <p>Have Fun! + <p> + +<li> <b>Busybox Boot-Floppy Image</b> + +<p>Because you asked for it, we have made available a <a href= +"downloads/busybox.floppy.img"> Busybox boot floppy +image</a>. Here's how you use it: + +<ol> + + <li> <a href="downloads/busybox.floppy.img"> + Download the image</a> + + <li> dd it onto a floppy like so: <tt> dd if=busybox.floppy.img + of=/dev/fd0 ; sync </tt> + + <li> Pop it in a machine and boot up. + +</ol> + +<p> If you want to look at the contents of the initrd image, do this: + +<pre> + mount ./busybox.floppy.img /mnt -o loop -t msdos + cp /mnt/initrd.gz /tmp + umount /mnt + gunzip /tmp/initrd.gz + mount /tmp/initrd /mnt -o loop -t minix +</pre> + + +<li> <b>15 March 2001 -- BusyBox 0.50 released</b> +<br> + + This release adds several new applets including ifconfig, route, pivot_root, stty, + and tftp, and also fixes tons of bugs. Tab completion in the + shell is now working very well, and the shell's environment variable + expansion was fixed. Tons of other things were fixed or made + smaller. For a fairly complete overview, see the + <a href="downloads/Changelog">changelog</a>. + <p> + lash (the busybox shell) is still with us, fixed up a bit so it + now behaves itself quite nicely. It really is quite usable as + long as you don't expect it to provide Bourne shell grammer. + Standard things like pipes, redirects, command line editing, and + environment variable expansion work great. But we have found that + this shell, while very usable, does not provide an extensible + framework for adding in full Bourne shell behavior. So the first order of + business as we begin working on the next BusyBox release will be to merge in the new shell + currently in progress at + <a href="http://doolittle.faludi.com/~larry/parser.html">Larry Doolittle's website</a>. + <p> + + +<li> <b>27 January 2001 -- BusyBox 0.49 released</b> +<br> + + Several new applets, lots of bug fixes, cleanups, and many smaller + things made nicer. Several cleanups and improvements to the shell. + For a list of the most interesting changes + you might want to look at the <a href="downloads/Changelog">changelog</a>. + <p> + Special thanks go out to Matt Kraai and Larry Doolittle for all their + work on this release, and for keeping on top of things while I've been + out of town. + <p> + <em>Special Note</em><br> + + BusyBox 0.49 was supposed to have replaced lash, the BusyBox + shell, with a new shell that understands full Bourne shell/Posix shell grammer. + Well, that simply didn't happen in time for this release. A new + shell that will eventually replace lash is already under + construction. This new shell is being developed by Larry + Doolittle, and could use all of our help. Please see the work in + progress on <a href="http://doolittle.faludi.com/~larry/parser.html">Larry's website</a> + and help out if you can. This shell will be included in the next + release of BusyBox. + <p> + +<li> <b>13 December 2000 -- BusyBox 0.48 released</b> +<br> + + This release fixes lots and lots of bugs. This has had some very + rigorous testing, and looks very, very clean. The usual tar + update of course: tar no longer breaks hardlinks, tar -xzf is + optionally supported, and the LRP folks will be pleased to know + that 'tar -X' and 'tar --exclude' are both now in. Applets are + now looked up using a binary search making lash (the busybox + shell) much faster. For the new debian-installer (for Debian + woody) a .udeb can now be generated. + <p> + The curious can get a list of some of the more interesting changes by reading + the <a href="downloads/Changelog">changelog</a>. + <p> + Many thanks go out to the many many people that have contributed to + this release, especially Matt Kraai, Larry Doolittle, and Kent Robotti. + <p> +<p> <li> <b>26 September 2000 -- BusyBox 0.47 released</b> +<br> + + This release fixes lots of bugs (including an ugly bug in 0.46 + syslogd that could fork-bomb your system). Added several new + apps: rdate, wget, getopt, dos2unix, unix2dos, reset, unrpm, + renice, xargs, and expr. syslogd now supports network logging. + There are the usual tar updates. Most apps now use getopt for + more correct option parsing. + See the <a href="downloads/Changelog">changelog</a> + for complete details. + + +<p> <li> <b>11 July 2000 -- BusyBox 0.46 released</b> +<br> + + This release fixes several bugs (including a ugly bug in tar, + and fixes for NFSv3 mount support). Added a dumpkmap to allow + people to dump a binary keymaps for use with 'loadkmap', and a + completely reworked 'grep' and 'sed' which should behave better. + BusyBox shell can now also be used as a login shell. + See the <a href="downloads/Changelog">changelog</a> + for complete details. + + +<p> <li> <b>21 June 2000 -- BusyBox 0.45 released</b> +<br> + + This release has been slow in coming, but is very solid at this + point. BusyBox now supports libc5 as well as GNU libc. This + release provides the following new apps: cut, tr, insmod, ar, + mktemp, setkeycodes, md5sum, uuencode, uudecode, which, and + telnet. There are bug fixes for just about every app as well (see + the <a href="downloads/Changelog">changelog</a> for + details). + <p> + Also, some exciting infrastructure news! Busybox now has its own + <a href="lists/busybox/">mailing list</a>, + publically browsable + <a href="/cgi-bin/viewcvs.cgi/trunk/busybox/">CVS tree</a>, + anonymous + <a href="cvs_anon.html">CVS access</a>, and + for those that are actively contributing there is even + <a href="cvs_write.html">CVS write access</a>. + I think this will be a huge help to the ongoing development of BusyBox. + <p> + Also, for the curious, there is no 0.44 release. Somehow 0.44 got announced + a few weeks ago prior to its actually being released. To avoid any confusion + we are just skipping 0.44. + <p> + Many thanks go out to the many people that have contributed to this release + of BusyBox (esp. Pavel Roskin)! + + +<p> <li> <b>19 April 2000 -- syslogd bugfix</b> +<br> +Turns out that there was still a bug in busybox syslogd. +For example, with the following test app: +<pre> +#include <syslog.h> + +int do_log(char* msg, int delay) +{ + openlog("testlog", LOG_PID, LOG_DAEMON); + while(1) { + syslog(LOG_ERR, "%s: testing one, two, three\n", msg); + sleep(delay); + } + closelog(); + return(0); +}; + +int main(void) +{ + if (fork()==0) + do_log("A", 2); + do_log("B", 3); +} +</pre> +it should be logging stuff from both "A" and "B". As released in 0.43 only stuff +from "A" would have been logged. This means that if init tries to log something +while say ppp has the syslog open, init would block (which is bad, bad, bad). +<p> +Karl M. Hegbloom has created a fix for the problem. +Thanks Karl! + + +<p> <li> <b>18 April 2000 -- BusyBox 0.43 released (finally!)</b> +<br> +I have finally gotten everything into a state where I feel pretty +good about things. This is definitely the most stable, solid release +so far. A lot of bugs have been fixed, and the following new apps +have been added: sh, basename, dirname, killall, uptime, +freeramdisk, tr, echo, test, and usleep. Tar has been completely +rewritten from scratch. Bss size has also been greatly reduced. +More details are available in the +<a href="downloads/Changelog">changelog</a>. +Oh, and as a special bonus, I wrote some fairly comprehensive +<em>documentation</em>, complete with examples and full usage information. + +<p> +Many thanks go out to the fine people that have helped by submitting patches +and bug reports; particularly instrumental in helping for this release were +Karl Hegbloom, Pavel Roskin, Friedrich Vedder, Emanuele Caratti, +Bob Tinsley, Nicolas Pitre, Avery Pennarun, Arne Bernin, John Beppu, and Jim Gleason. +There were others so if I somehow forgot to mention you, I'm very sorry. +<p> + +You can grab BusyBox 0.43 tarballs <a href="downloads">here</a>. + +<p> <li> <b>9 April 2000 -- BusyBox 0.43 pre release</b> +<br> +Unfortunately, I have not yet finished all the things I want to +do for BusyBox 0.43, so I am posting this pre-release for people +to poke at. This contains my complete rewrite of tar, which now weighs in at +5k (7k with all options turned on) and works for reading and writing +tarballs (which it does correctly for everything I have been able to throw +at it). Tar also (optionally) supports the "--exclude" option (mainly because +the Linux Router Project folks asked for it). This also has a pre-release +of the micro shell I have been writing. This pre-release should be stable +enough for production use -- it just isn't a release since I have some structural +changes I still want to make. +<p> +The pre-release can be found <a href="downloads">here</a>. +Please let me know ASAP if you find <em>any</em> bugs. + +<p> <li> <b>28 March 2000 -- Andersen Baby Boy release</b> +<br> +I am pleased to announce that on Tuesday March 28th at 5:48pm, weighing in at 7 +lbs. 12 oz, Micah Erik Andersen was born at LDS Hospital here in Salt Lake City. +He was born in the emergency room less then 5 minutes after we arrived -- and +it was such a relief that we even made it to the hospital at all. Despite the +fact that I was driving at an amazingly unlawful speed and honking at everybody +and thinking decidedly unkind thoughts about the people in our way, my wife +(inconsiderate of my feelings and complete lack of medical training) was lying +down in the back seat saying things like "I think I need to start pushing now" +(which she then proceeded to do despite my best encouraging statements to the +contrary). +<p> +Anyway, I'm glad to note that despite the much-faster-than-we-were-expecting +labor, both Shaunalei and our new baby boy are doing wonderfully. +<p> +So now that I am done with my excuse for the slow release cycle... +Progress on the next release of BusyBox has been slow but steady. I expect +to have a release sometime during the first week of April. This release will +include a number of important changes, including the addition of a shell, a +re-write of tar (to accommodate the Linux Router Project), and syslogd can now +accept multiple concurrent connections, fixing lots of unexpected blocking +problems. + + +<p> <li> <b>11 February 2000 -- BusyBox 0.42 released</b> +<br> + + This is the most solid BusyBox release so far. Many, many + bugs have been fixed. See the + <a href="downloads/Changelog">changelog</a> for details. + + Of particular interest, init will now cleanly unmount + filesystems on reboot, cp and mv have been rewritten and + behave much better, and mount and umount no longer leak + loop devices. Many thanks go out to Randolph Chung, + Karl M. Hegbloom, Taketoshi Sano, and Pavel Roskin for + their hard work on this release of BusyBox. Please pound + on it and let me know if you find any bugs. + +<p> <li> <b>19 January 2000 -- BusyBox 0.41 released</b> +<br> + + This release includes bugfixes to cp, mv, logger, true, false, + mkdir, syslogd, and init. New apps include wc, hostid, + logname, tty, whoami, and yes. New features include loop device + support in mount and umount, and better TERM handling by init. + The changelog can be found <a href="downloads/Changelog">here</a>. + +<p> <li> <b>7 January 2000 -- BusyBox 0.40 released</b> +<br> + + This release includes bugfixes to init (now includes inittab support), + syslogd, head, logger, du, grep, cp, mv, sed, dmesg, ls, kill, gunzip, and mknod. + New apps include sort, uniq, lsmod, rmmod, fbset, and loadacm. + In particular, this release fixes an important bug in tar which + in some cases produced serious security problems. + As always, the changelog can be found <a href="downloads/Changelog">here</a>. + +<p> <li> <b>11 December 1999 -- BusyBox Website</b> +<br> + I have received permission from Bruce Perens (the original author of BusyBox) + to set up this site as the new primary website for BusyBox. This website + will always contain pointers to the latest and greatest, and will also + contain the latest documentation on how to use BusyBox, what it can do, + what arguments its apps support, etc. + +<p> <li> <b>10 December 1999 -- BusyBox 0.39 released</b> +<br> + This release includes fixes to init, reboot, halt, kill, and ls, and contains + the new apps ping, hostname, mkfifo, free, tail, du, tee, and head. A full + changelog can be found <a href="downloads/Changelog">here</a>. +<p> <li> <b>5 December 1999 -- BusyBox 0.38 released</b> +<br> + This release includes fixes to tar, cat, ls, dd, rm, umount, find, df, + and make install, and includes new apps syslogd/klogd and logger. + + +</ul> + + +<!--#include file="footer.html" --> + diff --git a/docs/busybox.net/products.html b/docs/busybox.net/products.html new file mode 100644 index 0000000..0460642 --- /dev/null +++ b/docs/busybox.net/products.html @@ -0,0 +1,164 @@ +<!--#include file="header.html" --> + + +<h3>Products/Projects Using BusyBox</h3> + +Do you use BusyBox? I'd love to know about it and +I'd be happy to link to you. + +<p> +I know of the following projects that use BusyBox -- +listed in the order I happen to add them to the web page: + +<ul> + +<li><a href="http://buildroot.uclibc.org/">buildroot</a><br>A configurable +means for building your own busybox/uClibc based system systems, maintained +by the uClibc developers. + +<li><a href="http://openwrt.org">OpenWrt</a> a Linux distribution for embedded +devices, based on buildroot. + +<li><a href="http://www.pengutronix.de/software/ptxdist_en.html">PTXdist</a> + <br>another configurable means for building your own busybox based systems. + +<li><a href= +"http://cvs.debian.org/boot-floppies/"> +Debian installer (boot floppies) project</a> + +<li><a href="http://redhat.com/">Red Hat installer</a> + +<li><a href= +"http://distro.ibiblio.org/pub/Linux/distributions/slackware/slackware-current/source/rootdisks/"> +Slackware Installer</a> + +<li><a href="http://www.gentoo.org/">Gentoo Linux install/boot CDs</a> +<li><a href="http://www.mandriva.com/">The Mandriva installer</a> + +<li><a href="http://Leaf.SourceForge.net">Linux Embedded Appliance Firewall</a> + <br>The sucessor of the Linux Router Project, supporting all sorts + of embedded Linux gateways, routers, wireless routers, and firewalls. + +<li><a href= +"http://www.toms.net/rb/">tomsrtbt</a> + +<li><a href="http://www.stormix.com/">Stormix Installer</a> + +<li><a href="http://www.emacinc.com/linux2_sbc.htm">EMAC Linux 2.0 SBC</a> + +<li><a href="http://www.trinux.org/">Trinux</a> + +<li><a href="http://oddas.sourceforge.net/">ODDAS project</a> + +<li><a href="http://byld.sourceforge.net/">Build Your Linux Disk</a> + +<li><a href= +"http://ibiblio.org/pub/Linux/system/recovery">Zdisk</a> + +<li><a href="http://www.adtran.com">AdTran - +VPN/firewall VPN Linux Distribution</a> + +<li><a href="http://mkcdrec.ota.be/">mkCDrec - make CD-ROM recovery</a> + +<li><a href="http://recycle.lbl.gov/~ldoolitt/bse/">Linux on nanoEngine</a> + +<li><a href="http://www.zelow.no/floppyfw/">Floppyfw</a> + +<li><a href="http://www.ltsp.org/">Linux Terminal Server Project</a> + +<li><a href="http://www.devil-linux.org/">Devil-Linux</a> + +<li><a href="http://dutnux.sourceforge.net/">DutNux</a> + +<li><a href="http://www.microwerks.net/~hugo/mindi/">Mindi</a> + +<li><a href="http://www.minimalinux.org/ttylinux/">ttylinux</a> + +<li><a href="http://www.coyotelinux.com/">Coyote Linux</a> + +<li><a href="http://www.partimage.org/">Partition Image</a> + +<li><a href="http://www.fli4l.de/">fli4l the on(e)-disk-router</a> + +<li><a href="http://tinfoilhat.cultists.net/">Tinfoil Hat Linux</a> + +<li><a href="http://sourceforge.net/projects/gp32linux/">gp32linux</a> +<li><a href="http://familiar.handhelds.org/">Familiar Linux</a><br>A linux distribution for handheld computers +<li><a href="http://rescuecd.sourceforge.net/">Timo's Rescue CD Set</a> +<li><a href="http://sf.net/projects/netstation/">Netstation</a> +<li><a href="http://www.fiwix.org/">GNU/Fiwix Operating System</a> +<li><a href="http://www.softcraft.com/">Generations Linux</a> +<li><a href="http://systemimager.org/relatedprojects/">SystemImager / System Installation Suite</a> +<li><a href="http://www.bablokb.de/gendist/">GENDIST distribution generator</a> +<li><a href="http://diet-pc.sourceforge.net/">DIET-PC embedded Linux thin client distribution</a> +<li><a href="http://byzgl.sourceforge.net/">BYZantine Gnu/Linux</a> +<li><a href="http://dban.sourceforge.net/">Darik's Boot and Nuke</a> +<li><a href="http://www.timesys.com/">TimeSys real-time Linux</a> +<li><a href="http://movix.sf.net/">MoviX</a><br>Boots from CD and automatically plays every video file on the CD +<li><a href="http://katamaran.sourceforge.net">katamaran</a><br>Linux, X11, xfce windowmanager, based on BusyBox +<li><a href="http://www.sourceforge.net/projects/simplygnustep">Prometheus SimplyGNUstep</a> +<li><a href="http://www.renyi.hu/~ekho/lowlife/">lowlife</a><br>A documentation project on how to make your own uClibc-based systems and floppy. +<li><a href="http://metadistros.hispalinux.es/">Metadistros</a><br>a project to allow you easily make Live-CD distributions. +<li><a href="http://salvare.sourceforge.net/">Salvare</a><br>More Linux than tomsrtbt but less than Knoppix, aims to provide a useful workstation as well as a rescue disk. +<li><a href="http://www.stresslinux.org/">stresslinux</a><br>minimal linux distribution running from a bootable cdrom or via PXE. +<li><a href="http://thinstation.sourceforge.net/">thinstation</a><br>convert standard PCs into full-featured diskless thinclients. +<li><a href="http://www.uhulinux.hu/">UHU-Linux Hungary</a> +<li><a href="http://deep-water.berlios.de/">Deep-Water Linux</a> +<li><a href="http://www.freesco.org/">Freesco router</a> +<li><a href="http://Sentry.SourceForge.net/">Sentry Firewall CD</a> + +</ul> + +<p> +And here are products that use BusyBox -- + +<ul> + +<li><a href="http://www.elpa.it/eng/rd129gb.html">RD129 embedded board from ELPA</a> +<li>EMTEC MovieCube R700 uses Busybox 1.1.3. +<li><a href="http://tuxscreen.net">Tuxscreen Linux Phone</a> +<li><a href="http://www.kerbango.com/">The Kerbango Internet Radio</a> +<li><a href="http://www.linuxmagic.com/vpn/">LinuxMagic VPN Firewall</a> +<li><a href="http://www.isilver-inc.com/">I-Silver Linux appliance servers</a> +<li><a href="http://zaurus.sourceforge.net/">Sharp Zaurus PDA</a> +<li><a href="http://www.cyclades.com/">Cyclades-TS and other Cyclades products</a> +<li><a href="http://www.linksys.com/products/product.asp?prid=508">Linksys WRT54G - Wireless-G Broadband Router</a> +<li><a href="http://www.dell.com/us/en/biz/topics/sbtopic_005_truemobile.htm">Dell TrueMobile 1184</a> +<li><a href="http://actiontec.com/products/modems/dual_pcmodem/dpm_overview.html">Actiontec Dual PC Modem</a> +<li><a href="http://www.kiss-technology.com/">Kiss DP Series DVD players</a> +<li><a href="http://www.netgear.com/products/prod_details.asp?prodID=170">NetGear WG602 wireless router</a> + <br>with sources <a href="http://www.netgear.com/support/support_details.asp?dnldID=453">here</a> +<li><a href="http://www.trendware.com/products/TEW-411BRP.htm">TRENDnet TEW-411BRP 802.11g Wireless AP/Router/Switch</a> + <br>Source for busybox and udhcp <a href="http://www.trendware.com/asp/download/fileinfo.asp?file_id=277&B1=Search">here</a> though no kernel source is provided. +<li><a href="http://www.buffalo-technology.com/webcontent/products/wireless/wbr-g54.htm">Buffalo WBR-G54 wireless router</a> + <li><a href="http://www.asus.com/products/communication/wireless/wl-300g/overview.htm">ASUS WL-300g Wireless LAN Access Point</a> + <br>with source<a href="http://www.asus.com.tw/support/download/item.aspx?ModelName=WL-300G">here</a> + <li><a href="http://catalog.belkin.com/IWCatProductPage.process?Merchant_Id=&Section_Id=201522&pcount=&Product_Id=136493">Belkin 54g Wireless DSL/Cable Gateway Router</a> + <br>with source<a href="http://web.belkin.com/support/gpl.asp">here</a> + <li><a href="http://www.acronis.com/products/partitionexpert/">Acronis PartitionExpert 2003</a> + <br>includes a heavily modified BusyBox v0.60.5 with built in + cardmgr, device detection, gpm, lspci, etc. Also includes udhcp, + uClibc 0.9.26, a heavily patched up linux kernel, etc. Source + can only be obtained <a href="http://www.acronis.com/files/gpl/linux.tar.bz2">here</a> + +<li><a href="http://www.usr.com/">U.S. Robotics Sureconnect 4-port ADSL router</a><br> + with source <a href="http://www.usr.com/support/s-gpl-code.asp">here</a> +<li><a href="http://www.actiontec.com/products/broadband/54mbps_wireless_gateway_1p/index.html"> + ActionTec GT701-WG Wireless Gateway/DSL Modem</a> + with source <a href="http://128.121.226.214/gtproducts/index.html">here</a> +<li><a href="http://smartlinux.sourceforge.net/">S.M.A.R.T. Linux</a> +<li><a href="http://www.dlink.com/">DLink - Model GSL-G604T, DSL-300T, and possibly other models</a> + with source <a href="ftp://ftp.dlink.co.uk/dsl_routers_modems/">here,</a> + with source <a href="ftp://ftp.dlink.de/dsl-products/">and here,</a> + and quite possibly other places as well. You may need to dig down a bit + to find the source, but it does seem to be there. +<li><a href="http://www.siemens-mobile.de/cds/frontdoor/0,2241,de_de_0_42931_rArNrNrNrN,00.html">Siemens SE515 DSL router</a> + with source <a href="http://now-portal.c-lab.de/projects/gigaset/">here, I think...</a> + with some details <a href="http://heinz.hippenstiel.org/familie/hp/hobby/gigaset_se515dsl.html">here.</a> +<li><a href="http://freeterm.spb.ru/frwt/">Free Remote Windows Terminal</a> + +<li><a href="http://www.zyxel.com/">ZyXEL Routers</a> + +</ul> + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/screenshot.html b/docs/busybox.net/screenshot.html new file mode 100644 index 0000000..c5ef18b --- /dev/null +++ b/docs/busybox.net/screenshot.html @@ -0,0 +1,75 @@ +<!--#include file="header.html" --> + + +<!-- Begin Screenshot --> + +<h3> Busybox Screenshot! </h3> + + +Everybody loves to look at screenshots, so here is a live action screenshot of BusyBox. + +<pre style="background-color: black; color: lightgreen; padding: 5px; +font-family: monospace; font-size: smaller;" width="100"> + +$ busybox +BusyBox v1.10.1 (2008-04-24 11:30:07 CEST) multi-call binary +Copyright (C) 1998-2007 Erik Andersen, Rob Landley, Denys Vlasenko +and others. Licensed under GPLv2. +See source distribution for full notice. + +Usage: busybox [function] [arguments]... + or: function [arguments]... + + BusyBox is a multi-call binary that combines many common Unix + utilities into a single executable. Most people will create a + link to busybox for each function they wish to use and BusyBox + will act like whatever it was invoked as! + +Currently defined functions: + [, [[, addgroup, adduser, adjtimex, ar, arp, arping, ash, + awk, basename, bbconfig, brctl, bunzip2, bzcat, bzip2, + cal, cat, catv, chat, chattr, chcon, chgrp, chmod, chown, + chpasswd, chpst, chroot, chrt, chvt, cksum, clear, cmp, + comm, cp, cpio, crond, crontab, cryptpw, cttyhack, cut, + date, dc, dd, deallocvt, delgroup, deluser, devfsd, df, + dhcprelay, diff, dirname, dmesg, dnsd, dos2unix, dpkg, + dpkg-deb, du, dumpkmap, dumpleases, echo, ed, egrep, eject, + env, envdir, envuidgid, ether-wake, expand, expr, fakeidentd, + false, fbset, fdflush, fdformat, fdisk, fetchmail, fgrep, + find, findfs, fold, free, freeramdisk, fsck, fsck.minix, + ftpget, ftpput, fuser, getenforce, getopt, getsebool, + getty, grep, gunzip, gzip, halt, hd, hdparm, head, hexdump, + hostid, hostname, httpd, hush, hwclock, id, ifconfig, + ifdown, ifenslave, ifup, inetd, init, insmod, install, + ip, ipaddr, ipcalc, ipcrm, ipcs, iplink, iproute, iprule, + iptunnel, kbd_mode, kill, killall, killall5, klogd, lash, + last, length, less, linux32, linux64, linuxrc, ln, load_policy, + loadfont, loadkmap, logger, login, logname, logread, losetup, + lpd, lpq, lpr, ls, lsattr, lsmod, lzmacat, makedevs, matchpathcon, + md5sum, mdev, mesg, microcom, mkdir, mkfifo, mkfs.minix, + mknod, mkswap, mktemp, modprobe, more, mount, mountpoint, + msh, mt, mv, nameif, nc, netstat, nice, nmeter, nohup, + nslookup, od, openvt, passwd, patch, pgrep, pidof, ping, + ping6, pipe_progress, pivot_root, pkill, poweroff, printenv, + printf, ps, pscan, pwd, raidautorun, rdate, readahead, + readlink, readprofile, realpath, reboot, renice, reset, + resize, restorecon, rm, rmdir, rmmod, route, rpm, rpm2cpio, + rtcwake, run-parts, runcon, runlevel, runsv, runsvdir, + rx, script, sed, selinuxenabled, sendmail, seq, sestatus, + setarch, setconsole, setenforce, setfiles, setkeycodes, + setlogcons, setsebool, setsid, setuidgid, sha1sum, slattach, + sleep, softlimit, sort, split, start-stop-daemon, stat, + strings, stty, su, sulogin, sum, sv, svlogd, swapoff, + swapon, switch_root, sync, sysctl, syslogd, tac, tail, + tar, taskset, tcpsvd, tee, telnet, telnetd, test, tftp, + tftpd, time, top, touch, tr, traceroute, true, tty, ttysize, + udhcpc, udhcpd, udpsvd, umount, uname, uncompress, unexpand, + uniq, unix2dos, unlzma, unzip, uptime, usleep, uudecode, + uuencode, vconfig, vi, vlock, watch, watchdog, wc, wget, + which, who, whoami, xargs, yes, zcat, zcip + +$ <span style="text-decoration:blink;">_</span> + +</pre> + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/shame.html b/docs/busybox.net/shame.html new file mode 100644 index 0000000..d9da44b --- /dev/null +++ b/docs/busybox.net/shame.html @@ -0,0 +1,82 @@ +<!--#include file="header.html" --> + + +<h3>Hall of Shame!!!</h3> + +<p>This page is no longer updated, these days we forward this sort of +thing to the <a href="http://www.softwarefreedom.org">Software Freedom Law +Center</a> instead.</p> + +<p>The following products and/or projects appear to use BusyBox, but do not +appear to release source code as required by the <a +href="/license.html">BusyBox license</a>. This is a violation of the law! +The distributors of these products are invited to contact <a href= +"mailto:andersen@codepoet.org">Erik Andersen</a> if they have any confusion +as to what is needed to bring their products into compliance, or if they have +already brought their product into compliance and wish to be removed from the +Hall of Shame. + +<p> + +Here are the details of <a href="/license.html">exactly how to comply +with the BusyBox license</a>, so there should be no question as to +exactly what is expected. +Complying with the Busybox license is easy and completely free, so the +companies listed below should be ashamed of themselves. Furthermore, each +product listed here is subject to being legally ordered to cease and desist +distribution for violation of copyright law, and the distributor of each +product is subject to being sued for statutory copyright infringement damages +of up to $150,000 per work plus legal fees. Nobody wants to be sued, and <a +href="mailto:andersen@codepoet.org">Erik</a> certainly would prefer to spend +his time doing better things than sue people. But he will sue if forced to +do so to maintain compliance. + +<p> + +Do everyone a favor and don't break the law -- if you use busybox, comply with +the busybox license by releasing the source code with your product. + +<p> + +<ul> + + <li><a href="http://www.trittontechnologies.com/products.html">Tritton Technologies NAS120</a> + <br>see <a href="http://www.ussg.iu.edu/hypermail/linux/kernel/0404.0/1611.html">here for details</a> + <li><a href="http://www.macsense.com/product/homepod/">Macsense HomePod</a> + <br>with details + <a href="http://developer.gloolabs.com/modules.php?op=modload&name=Forums&file=viewtopic&topic=123&forum=7">here</a> + <li><a href="http://www.cpx.com/products.asp?c=Wireless+Products">Compex Wireless Products</a> + <br>appears to be running v0.60.5 with Linux version 2.4.20-uc0 on ColdFire, + but no source code is mentioned or offered. + <li><a href="http://www.inventel.com/en/product/datasheet/10/">Inventel DW 200 wireless/ADSL router</a> + <li><a href="http://www.sweex.com/product.asp">Sweex DSL router</a> + <br>appears to be running BusyBox v1.00-pre2 and udhcpd, but no source + code is mentioned or offered. + <li><a href="http://www.trendware.com/products/TEW-410APB.htm">TRENDnet TEW-410APB</a> + </li><li><a href="http://www.hauppauge.com/Pages/products/data_mediamvp.html">Hauppauge Media MVP</a> + <br>Hauppauge contacted me on 16 Dec 2003, and claims to be working on resolving this problem. + </li><li><a href="http://www.hitex.com/download/adescom/data/">TriCore</a> + </li><li><a href="http://www.allnet.de/">ALLNET 0186 wireless router</a> + </li><li><a href="http://www.dmmtv.com/">Dreambox DM7000S DVB Satellite Receiver</a> + <br> Dream Multimedia contacted me on 22 Dec 2003 and is working on resolving this problem. + <br> Source _may_ be here: http://cvs.tuxbox.org/cgi-bin/viewcvs.cgi/tuxbox/cdk/ + </li><li><a href="http://testing.lkml.org/slashdot.php?mid=331690">Sigma Designs EM8500 based DVD players</a> + <br>Source for the Sigma Designs reference platform is found here<br> + <a href="http://www.uclinux.org/pub/uClinux/ports/arm/EM8500/uClinux-2.4-sigma.tar.gz">uClinux-2.4-sigma.tar.gz</a>, so while Sigma Designs itself appears to be in compliance, as far as I can tell, + no vendors of Sigma Designs EM8500 based devices actually comply with the GPL.... + </li><li><a href="http://testing.lkml.org/slashdot.php?mid=433790">Liteon LVD2001 DVD player using the Sigma Designs EM8500</a> + </li><li><a href="http://www.rimax.net/">Rimax DVD players using the Sigma Designs EM8500</a> + </li><li><a href="http://www.vinc.us/">Bravo DVD players using the Sigma Designs EM8500</a> + </li><li><a href="http://www.hb-direct.com/">H&B DX3110 Divx player based on Sigma Designs EM8500</a> + </li><li><a href="http://www.recospa.it/mdpro1/index.php">United *DVX4066 mpeg4 capable DVD players</a> + </li><li><a href="http://www.a-link.com/RR64AP.html">Avaks alink Roadrunner 64</a> + <br> Partial source available, based on source distributed under NDA from <a href="http://www.lsilogic.com/products/dsl_platform_solutions/hb_linuxr2_2.html"> LSILogic</a>. Why the NDA LSILogic, what are you hiding ? + <br>To verify the Avaks infrigment see my slashdot <a href="http://slashdot.org/~bug1/journal/">journal</a>. + <br>The ZipIt wireless IM device appears to be using Busybox-1.00-pre1 in the ramdisk, however no source has been made available. + </li><li>Undoubtedly there are others... Please report them so we can shame them (or if necessary sue them) into compliance. + +</ul> + + +<!--#include file="footer.html" --> + diff --git a/docs/busybox.net/sponsors.html b/docs/busybox.net/sponsors.html new file mode 100644 index 0000000..e52adfc --- /dev/null +++ b/docs/busybox.net/sponsors.html @@ -0,0 +1,56 @@ +<!--#include file="header.html" --> + +<h3>Sponsors</h3> + +<p>Please visit our sponsors and thank them for their support! They have +provided money for equipment and bandwidth. Next time you need help with a +project, consider these fine companies!</p> + + +<ul> + <li><a href="http://osuosl.org/">OSU OSL</a><br> + OSU OSL kindly provides hosting for BusyBox and uClibc. + </li> + + <li><a href="http://www.codepoet-consulting.com/">Codepoet Consulting</a><br> + Custom Linux, embedded Linux, BusyBox, and uClibc development. + </li> + + <li><a href="http://www.laptopcomputers.org/">Laptop Computers</a> contributes + financially. + </li> + + <li>AOE media, a <a href="http://www.aoemedia.com/typo3-development.html"> + TYPO3 development agency</a> contributes financially. + </li> + + <li><a href="http://www.analog.com/en/">Analog Devices, Inc.</a> provided + a <a href="http://docs.blackfin.uclinux.org/doku.php?id=bf537_quick_start"> + Blackfin development board</a> free of charge. + <a href="http://www.analog.com/blackfin">Blackfin</a> + is a NOMMU processor, and its availability for testing is invaluable. + If you are an embedded device developer, + please note that Analog Devices has entire Linux distribution available + for download for this board. Visit + <a href="http://blackfin.uclinux.org/">http://blackfin.uclinux.org/</a> + for more information. + </li> + + <li><a href="http://www.timesys.com/">TimeSys</a><br> + Embedded Linux development, cross-compilers, real-time, KGDB, tsrpm and cygwin. + </li> + + <li><a href="http://www.penguru.net/">Penguru Consulting</a><br> + Custom development for embedded Linux systems and multimedia platforms. + </li> + + <li><a href="http://opensource.se/">opensource.se</a><br> + Embedded open source consulting in Europe. + </li> + +</ul> + +<p>If you wish to be a sponsor, or if you have already contributed and would +like your name added here, email <a href="mailto:vda.linux@gmail.com">Denys</a>.</p> + +<!--#include file="footer.html" --> diff --git a/docs/busybox.net/subversion.html b/docs/busybox.net/subversion.html new file mode 100644 index 0000000..f051422 --- /dev/null +++ b/docs/busybox.net/subversion.html @@ -0,0 +1,51 @@ +<!--#include file="header.html" --> + +<h3>Accessing Source</h3> + + + +<h3>Patches</h3> + +<p>You can <a href="downloads/">download</a> fixes for particular releases +of busybox, e.g. downloads/fixes-<em>major</em>-<em>minor</em>-<em>patch</em>/ + +<h3>Anonymous Subversion Access</h3> + +We allow anonymous (read-only) Subversion (svn) access to everyone. To +grab a copy of the latest version of BusyBox using anonymous svn access: + +<pre> +svn co svn://busybox.net/trunk/busybox</pre> + +<p> +The current <em>stable branch</em> can be obtained with +<pre> +svn co svn://busybox.net/branches/busybox_1_12_stable +</pre> + +<p> + +If you are not already familiar with using Subversion, I recommend you visit <a +href="http://subversion.tigris.org/">the Subversion website</a>. You might +also want to read online or buy a copy of <a +href="http://svnbook.red-bean.com/">the Subversion Book</a>. If you are +already comfortable with using CVS, you may want to skip ahead to the <a +href="http://svnbook.red-bean.com/en/1.1/apa.html">Subversion for CVS Users</a> +part of the Subversion Book. + +<p> + +Once you've checked out a copy of the source tree, you can update your source +tree at any time so it is in sync with the latest and greatest by entering your +BusyBox directory and running the command: + +<pre> +svn update</pre> + +Because you've only been granted anonymous access to the tree, you won't be +able to commit any changes. Changes can be submitted for inclusion by posting +them to the BusyBox mailing list. For those that are actively contributing +<a href="developer.html">Subversion commit access</a> can be made available. + +<!--#include file="footer.html" --> + diff --git a/docs/busybox.net/tinyutils.html b/docs/busybox.net/tinyutils.html new file mode 100644 index 0000000..1831346 --- /dev/null +++ b/docs/busybox.net/tinyutils.html @@ -0,0 +1,86 @@ +<!--#include file="header.html" --> + + +<h3>External Tiny Utilities</h3> + +This is a list of tiny utilities whose functionality is not provided by +busybox. If you have additional suggestions, please send an e-mail to our +dev mailing list. + +<br><br> + +<table> +<tr> + <th>Feature</th> + <th>Utilities</th> +</tr> + +<tr> + <td>SSH</td> + <td><a href="http://matt.ucc.asn.au/dropbear/">Dropbear</a> has both an ssh server and an ssh client that together come in around 100k. It has no external +dependencies (I.E. it does not depend on OpenSSL, using a built-in copy of +LibTomCrypt instead). It's actively maintained, with a quiet but responsive +mailing list.</td> +</tr> + +<tr> + <td>SMTP</td> + <td><a href="ftp://ftp.debian.org/debian/pool/main/s/ssmtp/">ssmtp</a> is an extremely simple Mail Transfer Agent.</td> +</tr> + +<tr> + <td>ntp</td> + <td><a href="http://doolittle.icarus.com/ntpclient/">ntpclient</a> is a +tiny ntp client. BusyBox has rdate to set the date from a remote server, but +if you want a daemon to repeatedly adjust the clock over time, try that.</td> +</table> + +<p>In a gui environment, you'll probably want a web browser. +<a href="http://www.konqueror.org/embedded/">Konqueror Embedded</a> requires QT +(or QT Embedded), but not KDE. The <a href="http://www.dillo.org/">Dillo</a> +requires GTK+, but not Gnome. Or you can try the <a href="http://links.twibright.com/">graphical +version of links</a>.</p> + +<h3>SCRIPTING LANGUAGES</h3> +<p>Although busybox has built-in support for shell scripts, plenty of other +small scripting languages are available on the net. A few examples:</p> +<table> +<tr> +<th>language</th> +<th>description</th> +</tr> +<tr> +<td> <a href="http://www.foo.be/docs/tpj/issues/vol5_3/tpj0503-0003.html">microperl</a> </td> +<td> A small standalone perl interpreter that can be built from the perl source +s via "make -f Makefile.micro". If you really feel the need for perl on an embe +dded system, this is where to start. +</tr> +<tr> + +<td><a href="http://www.lua.org/pil/">Lua</a></td> +<td>If you just want a small embedded scripting language to write <em>new</em> +code in, this Brazilian import is lightweight, fairly popular, and has +a complete book about it online.</td> +</tr> + +<tr> +<td><a href="http://www.star.le.ac.uk/%7Etjg/rc/">rc</a></td> +<td>The PLAN9 shell. Not compatible with conventional bourne shell syntax, +but fairly lightweight and small.</td> +</tr> + +</tr> +<tr> +<td><a href="http://www.forth.org/">forth</a></td> +<td>A well known language for fast and small programs, decades old but still +in use for everything from OpenBIOS to computer controlled engine timing.</td> +</tr> +</table> + +<p>For more information, you probably want to look at +<a href="http://buildroot.uclibc.org/">buildroot</a> and +<a href="http://gentoo-wiki.com/TinyGentoo">TinyGentoo</a>, which +build and use tiny utilities for all sorts of things.</p> + +<!--#include file="footer.html" --> + diff --git a/docs/busybox_footer.pod b/docs/busybox_footer.pod new file mode 100644 index 0000000..74575bd --- /dev/null +++ b/docs/busybox_footer.pod @@ -0,0 +1,256 @@ +=back + +=head1 LIBC NSS + +GNU Libc (glibc) uses the Name Service Switch (NSS) to configure the behavior +of the C library for the local environment, and to configure how it reads +system data, such as passwords and group information. This is implemented +using an /etc/nsswitch.conf configuration file, and using one or more of the +/lib/libnss_* libraries. BusyBox tries to avoid using any libc calls that make +use of NSS. Some applets however, such as login and su, will use libc functions +that require NSS. + +If you enable CONFIG_USE_BB_PWD_GRP, BusyBox will use internal functions to +directly access the /etc/passwd, /etc/group, and /etc/shadow files without +using NSS. This may allow you to run your system without the need for +installing any of the NSS configuration files and libraries. + +When used with glibc, the BusyBox 'networking' applets will similarly require +that you install at least some of the glibc NSS stuff (in particular, +/etc/nsswitch.conf, /lib/libnss_dns*, /lib/libnss_files*, and /lib/libresolv*). + +Shameless Plug: As an alternative, one could use a C library such as uClibc. In +addition to making your system significantly smaller, uClibc does not require the +use of any NSS support files or libraries. + +=head1 MAINTAINER + +Denis Vlasenko <vda.linux@googlemail.com> + +=head1 AUTHORS + +The following people have contributed code to BusyBox whether they know it or +not. If you have written code included in BusyBox, you should probably be +listed here so you can obtain your bit of eternal glory. If you should be +listed here, or the description of what you have done needs more detail, or is +incorect, please send in an update. + + +=for html <br> + +Emanuele Aina <emanuele.aina@tiscali.it> + run-parts + +=for html <br> + +Erik Andersen <andersen@codepoet.org> + + Tons of new stuff, major rewrite of most of the + core apps, tons of new apps as noted in header files. + Lots of tedious effort writing these boring docs that + nobody is going to actually read. + +=for html <br> + +Laurence Anderson <l.d.anderson@warwick.ac.uk> + + rpm2cpio, unzip, get_header_cpio, read_gz interface, rpm + +=for html <br> + +Jeff Angielski <jeff@theptrgroup.com> + + ftpput, ftpget + +=for html <br> + +Edward Betts <edward@debian.org> + + expr, hostid, logname, whoami + +=for html <br> + +John Beppu <beppu@codepoet.org> + + du, nslookup, sort + +=for html <br> + +Brian Candler <B.Candler@pobox.com> + + tiny-ls(ls) + +=for html <br> + +Randolph Chung <tausq@debian.org> + + fbset, ping, hostname + +=for html <br> + +Dave Cinege <dcinege@psychosis.com> + + more(v2), makedevs, dutmp, modularization, auto links file, + various fixes, Linux Router Project maintenance + +=for html <br> + +Jordan Crouse <jordan@cosmicpenguin.net> + + ipcalc + +=for html <br> + +Magnus Damm <damm@opensource.se> + + tftp client insmod powerpc support + +=for html <br> + +Larry Doolittle <ldoolitt@recycle.lbl.gov> + + pristine source directory compilation, lots of patches and fixes. + +=for html <br> + +Glenn Engel <glenne@engel.org> + + httpd + +=for html <br> + +Gennady Feldman <gfeldman@gena01.com> + + Sysklogd (single threaded syslogd, IPC Circular buffer support, + logread), various fixes. + +=for html <br> + +Karl M. Hegbloom <karlheg@debian.org> + + cp_mv.c, the test suite, various fixes to utility.c, &c. + +=for html <br> + +Daniel Jacobowitz <dan@debian.org> + + mktemp.c + +=for html <br> + +Matt Kraai <kraai@alumni.cmu.edu> + + documentation, bugfixes, test suite + +=for html <br> + +Stephan Linz <linz@li-pro.net> + + ipcalc, Red Hat equivalence + +=for html <br> + +John Lombardo <john@deltanet.com> + + tr + +=for html <br> + +Glenn McGrath <bug1@iinet.net.au> + + Common unarchving code and unarchiving applets, ifupdown, ftpgetput, + nameif, sed, patch, fold, install, uudecode. + Various bugfixes, review and apply numerous patches. + +=for html <br> + +Manuel Novoa III <mjn3@codepoet.org> + + cat, head, mkfifo, mknod, rmdir, sleep, tee, tty, uniq, usleep, wc, yes, + mesg, vconfig, make_directory, parse_mode, dirname, mode_string, + get_last_path_component, simplify_path, and a number trivial libbb routines + + also bug fixes, partial rewrites, and size optimizations in + ash, basename, cal, cmp, cp, df, du, echo, env, ln, logname, md5sum, mkdir, + mv, realpath, rm, sort, tail, touch, uname, watch, arith, human_readable, + interface, dutmp, ifconfig, route + +=for html <br> + +Vladimir Oleynik <dzo@simtreas.ru> + + cmdedit; xargs(current), httpd(current); + ports: ash, crond, fdisk, inetd, stty, traceroute, top; + locale, various fixes + and irreconcilable critic of everything not perfect. + +=for html <br> + +Bruce Perens <bruce@pixar.com> + + Original author of BusyBox in 1995, 1996. Some of his code can + still be found hiding here and there... + +=for html <br> + +Tim Riker <Tim@Rikers.org> + + bug fixes, member of fan club + +=for html <br> + +Kent Robotti <robotti@metconnect.com> + + reset, tons and tons of bug reports and patches. + +=for html <br> + +Chip Rosenthal <chip@unicom.com>, <crosenth@covad.com> + + wget - Contributed by permission of Covad Communications + +=for html <br> + +Pavel Roskin <proski@gnu.org> + + Lots of bugs fixes and patches. + +=for html <br> + +Gyepi Sam <gyepi@praxis-sw.com> + + Remote logging feature for syslogd + +=for html <br> + +Linus Torvalds <torvalds@transmeta.com> + + mkswap, fsck.minix, mkfs.minix + +=for html <br> + +Mark Whitley <markw@codepoet.org> + + grep, sed, cut, xargs(previous), + style-guide, new-applet-HOWTO, bug fixes, etc. + +=for html <br> + +Charles P. Wright <cpwright@villagenet.com> + + gzip, mini-netcat(nc) + +=for html <br> + +Enrique Zanardi <ezanardi@ull.es> + + tarcat (since removed), loadkmap, various fixes, Debian maintenance + +=for html <br> + +Tito Ragusa <farmatito@tiscali.it> + + devfsd and size optimizations in strings, openvt and deallocvt. + +=cut + diff --git a/docs/busybox_header.pod b/docs/busybox_header.pod new file mode 100644 index 0000000..9f2ffc4 --- /dev/null +++ b/docs/busybox_header.pod @@ -0,0 +1,83 @@ +# vi: set sw=4 ts=4: + +=head1 NAME + +BusyBox - The Swiss Army Knife of Embedded Linux + +=head1 SYNTAX + + busybox <applet> [arguments...] # or + + <applet> [arguments...] # if symlinked + +=head1 DESCRIPTION + +BusyBox combines tiny versions of many common UNIX utilities into a single +small executable. It provides minimalist replacements for most of the utilities +you usually find in GNU coreutils, util-linux, etc. The utilities in BusyBox +generally have fewer options than their full-featured GNU cousins; however, the +options that are included provide the expected functionality and behave very +much like their GNU counterparts. + +BusyBox has been written with size-optimization and limited resources in mind. +It is also extremely modular so you can easily include or exclude commands (or +features) at compile time. This makes it easy to customize your embedded +systems. To create a working system, just add /dev, /etc, and a Linux kernel. +BusyBox provides a fairly complete POSIX environment for any small or embedded +system. + +BusyBox is extremely configurable. This allows you to include only the +components you need, thereby reducing binary size. Run 'make config' or 'make +menuconfig' to select the functionality that you wish to enable. Then run +'make' to compile BusyBox using your configuration. + +After the compile has finished, you should use 'make install' to install +BusyBox. This will install the 'bin/busybox' binary, in the target directory +specified by CONFIG_PREFIX. CONFIG_PREFIX can be set when configuring BusyBox, +or you can specify an alternative location at install time (i.e., with a +command line like 'make CONFIG_PREFIX=/tmp/foo install'). If you enabled +any applet installation scheme (either as symlinks or hardlinks), these will +also be installed in the location pointed to by CONFIG_PREFIX. + +=head1 USAGE + +BusyBox is a multi-call binary. A multi-call binary is an executable program +that performs the same job as more than one utility program. That means there +is just a single BusyBox binary, but that single binary acts like a large +number of utilities. This allows BusyBox to be smaller since all the built-in +utility programs (we call them applets) can share code for many common +operations. + +You can also invoke BusyBox by issuing a command as an argument on the +command line. For example, entering + + /bin/busybox ls + +will also cause BusyBox to behave as 'ls'. + +Of course, adding '/bin/busybox' into every command would be painful. So most +people will invoke BusyBox using links to the BusyBox binary. + +For example, entering + + ln -s /bin/busybox ls + ./ls + +will cause BusyBox to behave as 'ls' (if the 'ls' command has been compiled +into BusyBox). Generally speaking, you should never need to make all these +links yourself, as the BusyBox build system will do this for you when you run +the 'make install' command. + +If you invoke BusyBox with no arguments, it will provide you with a list of the +applets that have been compiled into your BusyBox binary. + +=head1 COMMON OPTIONS + +Most BusyBox applets support the B<--help> argument to provide a terse runtime +description of their behavior. If the CONFIG_FEATURE_VERBOSE_USAGE option has +been enabled, more detailed usage information will also be available. + +=head1 COMMANDS + +Currently available applets include: + diff --git a/docs/cgi/cl.html b/docs/cgi/cl.html new file mode 100644 index 0000000..5779d62 --- /dev/null +++ b/docs/cgi/cl.html @@ -0,0 +1,46 @@ +<html><head><title>CGI Command line options</title></head><body><h1><img alt="" src="cl_files/CGIlogo.gif"> CGI Command line options</h1> +<hr> <p> + +</p><h2>Specification</h2> + +The command line is only used in the case of an ISINDEX query. It is +not used in the case of an HTML form or any as yet undefined query +type. The server should search the query information (the <code>QUERY_STRING</code> environment variable) for a non-encoded += character to determine if the command line is to be used, if it +finds one, the command line is not to be used. This trusts the clients +to encode the = sign in ISINDEX queries, a practice which was +considered safe at the time of the design of this specification. <p> + +For example, use the <a href="http://hoohoo.ncsa.uiuc.edu/cgi-bin/finger">finger script</a> and the ISINDEX interface to look up "httpd". You will see that the script will call itself with <code>/cgi-bin/finger?httpd</code> and will actually execute "finger httpd" on the command line and output the results to you. +</p><p> +If the server does find a "=" in the <code>QUERY_STRING</code>, +then the command line will not be used, and no decoding will be +performed. The query then remains intact for processing by an +appropriate FORM submission decoder. +Again, as an example, use <a href="http://hoohoo.ncsa.uiuc.edu/cgi-bin/finger?httpd=name">this hyperlink</a> to submit <code>"httpd=name"</code> to the finger script. Since this <code>QUERY_STRING</code> +contained an unencoded "=", nothing was decoded, the script didn't know +it was being submitted a valid query, and just gave you the default +finger form. +</p><p> +If the server finds that it cannot send the string due to internal +limitations (such as exec() or /bin/sh command line restrictions) the +server should include NO command line information and provide the +non-decoded query information in the environment +variable <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html#query"><code>QUERY_STRING</code></a>. </p><p> +</p><hr> +<h2>Examples</h2> + +Examples of the command line usage are much better <a href="http://hoohoo.ncsa.uiuc.edu/cgi/examples.html">demonstrated</a> than explained. For these +examples, pay close attention to the script output which says what +argc and argv are. <p> + +</p><hr> + +<a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><img alt="[Back]" src="cl_files/back.gif">Return to the +interface specification</a> <p> + +CGI - Common Gateway Interface +</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address> + + +</body></html>
\ No newline at end of file diff --git a/docs/cgi/env.html b/docs/cgi/env.html new file mode 100644 index 0000000..924026b --- /dev/null +++ b/docs/cgi/env.html @@ -0,0 +1,149 @@ +<html><head><title>CGI Environment Variables</title></head><body><h1><img alt="" src="env_files/CGIlogo.gif"> CGI Environment Variables</h1> +<hr> + +<p> + +In order to pass data about the information request from the server to +the script, the server uses command line arguments as well as +environment variables. These environment variables are set when the +server executes the gateway program. </p><p> + +</p><hr> +<h2>Specification</h2> + + <p> +The following environment variables are not request-specific and are +set for all requests: </p><p> + +</p><ul> +<li> <code>SERVER_SOFTWARE</code> <p> + + The name and version of the information server software answering + the request (and running the gateway). Format: name/version </p><p> + +</p></li><li> <code>SERVER_NAME</code> <p> + The server's hostname, DNS alias, or IP address as it would appear + in self-referencing URLs. </p><p> + +</p></li><li> <code>GATEWAY_INTERFACE</code> <p> + The revision of the CGI specification to which this server + complies. Format: CGI/revision</p><p> + +</p></li></ul> + +<hr> + +The following environment variables are specific to the request being +fulfilled by the gateway program: <p> + +</p><ul> +<li> <a name="protocol"><code>SERVER_PROTOCOL</code></a> <p> + The name and revision of the information protcol this request came + in with. Format: protocol/revision </p><p> + +</p></li><li> <code>SERVER_PORT</code> <p> + The port number to which the request was sent. </p><p> + +</p></li><li> <code>REQUEST_METHOD</code> <p> + The method with which the request was made. For HTTP, this is + "GET", "HEAD", "POST", etc. </p><p> + +</p></li><li> <code>PATH_INFO</code> <p> + The extra path information, as given by the client. In other + words, scripts can be accessed by their virtual pathname, followed + by extra information at the end of this path. The extra + information is sent as PATH_INFO. This information should be + decoded by the server if it comes from a URL before it is passed + to the CGI script.</p><p> + +</p></li><li> <code>PATH_TRANSLATED</code> <p> + The server provides a translated version of PATH_INFO, which takes + the path and does any virtual-to-physical mapping to it. </p><p> + +</p></li><li> <code>SCRIPT_NAME</code> <p> + A virtual path to the script being executed, used for + self-referencing URLs. </p><p> + +</p></li><li> <a name="query"><code>QUERY_STRING</code></a> <p> + The information which follows the ? in the <a href="http://www.ncsa.uiuc.edu/demoweb/url-primer.html">URL</a> + which referenced this script. This is the query information. It + should not be decoded in any fashion. This variable should always + be set when there is query information, regardless of <a href="http://hoohoo.ncsa.uiuc.edu/cgi/cl.html">command line decoding</a>. </p><p> + +</p></li><li> <code>REMOTE_HOST</code> <p> + The hostname making the request. If the server does not have this + information, it should set REMOTE_ADDR and leave this unset.</p><p> + +</p></li><li> <code>REMOTE_ADDR</code> <p> + The IP address of the remote host making the request. </p><p> + +</p></li><li> <code>AUTH_TYPE</code> <p> + If the server supports user authentication, and the script is + protects, this is the protocol-specific authentication method used + to validate the user. </p><p> + +</p></li><li> <code>REMOTE_USER</code> <p> + If the server supports user authentication, and the script is + protected, this is the username they have authenticated as. </p><p> +</p></li><li> <code>REMOTE_IDENT</code> <p> + If the HTTP server supports RFC 931 identification, then this + variable will be set to the remote user name retrieved from the + server. Usage of this variable should be limited to logging only. + </p><p> + +</p></li><li> <a name="ct"><code>CONTENT_TYPE</code></a> <p> + For queries which have attached information, such as HTTP POST and + PUT, this is the content type of the data. </p><p> + +</p></li><li> <a name="cl"><code>CONTENT_LENGTH</code></a> <p> + The length of the said content as given by the client. </p><p> + +</p></li></ul> + + +<a name="headers"><hr></a> + +In addition to these, the header lines received from the client, if +any, are placed into the environment with the prefix HTTP_ followed by +the header name. Any - characters in the header name are changed to _ +characters. The server may exclude any headers which it has already +processed, such as Authorization, Content-type, and Content-length. If +necessary, the server may choose to exclude any or all of these +headers if including them would exceed any system environment +limits. <p> + +An example of this is the HTTP_ACCEPT variable which was defined in +CGI/1.0. Another example is the header User-Agent.</p><p> + +</p><ul> +<li> <code>HTTP_ACCEPT</code> <p> + The MIME types which the client will accept, as given by HTTP + headers. Other protocols may need to get this information from + elsewhere. Each item in this list should be separated by commas as + per the HTTP spec. </p><p> + + Format: type/subtype, type/subtype </p><p> + + +</p></li><li> <code>HTTP_USER_AGENT</code><p> + + The browser the client is using to send the request. General +format: <code>software/version library/version</code>.</p><p> + +</p></li></ul> + +<hr> +<h2>Examples</h2> + +Examples of the setting of environment variables are really much better +<a href="http://hoohoo.ncsa.uiuc.edu/cgi/examples.html">demonstrated</a> than explained. <p> + +</p><hr> + +<a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><img alt="[Back]" src="env_files/back.gif">Return to the +interface specification</a> <p> + +CGI - Common Gateway Interface +</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address> + +</body></html>
\ No newline at end of file diff --git a/docs/cgi/in.html b/docs/cgi/in.html new file mode 100644 index 0000000..679306a --- /dev/null +++ b/docs/cgi/in.html @@ -0,0 +1,33 @@ +<html><head><title>CGI Script input</title></head><body><h1><img alt="" src="in_files/CGIlogo.gif"> CGI Script Input</h1> +<hr> + +<h2>Specification</h2> + +For requests which have information attached after the header, such as +HTTP POST or PUT, the information will be sent to the script on stdin. +<p> + +The server will send <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html#cl">CONTENT_LENGTH</a> bytes on +this file descriptor. Remember that it will give the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html#ct">CONTENT_TYPE</a> of the data as well. The server is +in no way obligated to send end-of-file after the script reads +<code>CONTENT_LENGTH</code> bytes. </p><p> +</p><hr> +<h2>Example</h2> + +Let's take a form with METHOD="POST" as an example. Let's say the form +results are 7 bytes encoded, and look like <code>a=b&b=c</code>. +<p> + +In this case, the server will set CONTENT_LENGTH to 7 and CONTENT_TYPE +to application/x-www-form-urlencoded. The first byte on the script's +standard input will be "a", followed by the rest of the encoded string.</p><p> + +</p><hr> + +<a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><img alt="[Back]" src="in_files/back.gif">Return to the +interface specification</a> <p> + +CGI - Common Gateway Interface +</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address> + +</body></html>
\ No newline at end of file diff --git a/docs/cgi/interface.html b/docs/cgi/interface.html new file mode 100644 index 0000000..ea73ce3 --- /dev/null +++ b/docs/cgi/interface.html @@ -0,0 +1,29 @@ +<html><head><title>The Common Gateway Interface Specification +[http://hoohoo.ncsa.uiuc.edu/cgi/interface.html] +</title></head><body><h1><img alt="" src="interface_files/CGIlogo.gif"> The CGI Specification</h1> + +<hr> + +This is the specification for CGI version 1.1, or CGI/1.1. Further +revisions of this protocol are guaranteed to be backward compatible. +<p> + +The server and the CGI script communicate in four major ways. Each of +the following is a hotlink to graphic detail.</p><p> + +</p><ul> +<li> <a href="env.html">Environment variables</a> +</li><li> <a href="cl.html">The command line</a> +</li><li> <a href="in.html">Standard input</a> +</li><li> <a href="out.html">Standard output</a> +</li></ul> +<hr> + + +<a href="http://hoohoo.ncsa.uiuc.edu/cgi/overview.html"><img alt="[Back]" src="interface_files/back.gif">Return to the overview</a> <p> + + + +CGI - Common Gateway Interface +</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address> +</body></html>
\ No newline at end of file diff --git a/docs/cgi/out.html b/docs/cgi/out.html new file mode 100644 index 0000000..2203ee5 --- /dev/null +++ b/docs/cgi/out.html @@ -0,0 +1,126 @@ +<html><head><title>CGI Script output</title></head><body><h1><img alt="" src="out_files/CGIlogo.gif"> CGI Script Output</h1> +<hr> + +<h2>Script output</h2> + +The script sends its output to stdout. This output can either be a +document generated by the script, or instructions to the server for +retrieving the desired output. <p> +</p><hr> + +<h2>Script naming conventions</h2> + +Normally, scripts produce output which is interpreted and sent back to +the client. An advantage of this is that the scripts do not need to +send a full HTTP/1.0 header for every request. <p> +<a name="nph"> +Some scripts may want to avoid the extra overhead of the server +parsing their output, and talk directly to the client. In order to +distinguish these scripts from the other scripts, CGI requires that +the script name begins with nph- if a script does not want the server +to parse its header. In this case, it is the script's responsibility +to return a valid HTTP/1.0 (or HTTP/0.9) response to the client. </a></p><p> + +</p><hr> +<h2><a name="nph">Parsed headers</a></h2> + +<a name="nph">The output of scripts begins with a small header. This header consists +of text lines, in the same format as an </a><a href="http://www.w3.org/hypertext/WWW/Protocols/HTTP/Object_Headers.html"> +HTTP header</a>, terminated by a blank line (a line with only a +linefeed or CR/LF). <p> + +Any headers which are not server directives are sent directly back to +the client. Currently, this specification defines three server +directives:</p><p> + +</p><ul> +<li> <code>Content-type</code> <p> + + This is the MIME type of the document you are returning. </p><p> + +</p></li><li> <code>Location</code> <p> + + This is used to specify to the server that you are returning a + reference to a document rather than an actual document. </p><p> + + If the argument to this is a URL, the server will issue a redirect + to the client. </p><p> + + If the argument to this is a virtual path, the server will + retrieve the document specified as if the client had requested + that document originally. ? directives will work in here, but # + directives must be redirected back to the client.</p><p> + + +</p></li><li> <a name="status"><code>Status</code></a><p> + + This is used to give the server an HTTP/1.0 <a href="http://www.w3.org/hypertext/WWW/Protocols/HTTP/HTRESP.html">status +line</a> to send to the client. The format is <code>nnn xxxxx</code>, +where <code>nnn</code> is the 3-digit status code, and +<code>xxxxx</code> is the reason string, such as "Forbidden".</p><p> + +</p></li></ul> + +<hr> +<h2>Examples</h2> + +Let's say I have a fromgratz to HTML converter. When my converter is +finished with its work, it will output the following on stdout (note +that the lines beginning and ending with --- are just for illustration +and would not be output): <p> + +</p><pre>--- start of output --- +Content-type: text/html + +--- end of output --- +</pre> + +Note the blank line after Content-type. <p> + +Now, let's say I have a script which, in certain instances, wants to +return the document <code>/path/doc.txt</code> from this server just +as if the user had actually requested +<code>http://server:port/path/doc.txt</code> to begin with. In this +case, the script would output: </p><p> +</p><pre>--- start of output --- +Location: /path/doc.txt + +--- end of output --- +</pre> + +The server would then perform the request and send it to the client. +<p> + +Let's say that I have a script which wants to reference our gopher +server. In this case, if the script wanted to refer the user to +<code>gopher://gopher.ncsa.uiuc.edu/</code>, it would output: </p><p> + +</p><pre>--- start of output --- +Location: gopher://gopher.ncsa.uiuc.edu/ + +--- end of output --- +</pre> + +Finally, I have a script which wants to talk to the client directly. +In this case, if the script is referenced with <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html#protocol"><code>SERVER_PROTOCOL</code></a> of HTTP/1.0, +the script would output the following HTTP/1.0 response: <p> + +</p><pre>--- start of output --- +HTTP/1.0 200 OK +Server: NCSA/1.0a6 +Content-type: text/plain + +This is a plaintext document generated on the fly just for you. + +--- end of output --- +</pre> + + +<hr> + +<a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><img alt="[Back]" src="out_files/back.gif">Return to the +interface specification</a> <p> + +CGI - Common Gateway Interface +</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address> +</body></html>
\ No newline at end of file diff --git a/docs/contributing.txt b/docs/contributing.txt new file mode 100644 index 0000000..aad4303 --- /dev/null +++ b/docs/contributing.txt @@ -0,0 +1,449 @@ +Contributing To Busybox +======================= + +This document describes what you need to do to contribute to Busybox, where +you can help, guidelines on testing, and how to submit a well-formed patch +that is more likely to be accepted. + +The Busybox home page is at: http://busybox.net/ + + + +Pre-Contribution Checklist +-------------------------- + +So you want to contribute to Busybox, eh? Great, wonderful, glad you want to +help. However, before you dive in, headlong and hotfoot, there are some things +you need to do: + + +Checkout the Latest Code from CVS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a necessary first step. Please do not try to work with the last +released version, as there is a good chance that somebody has already fixed +the bug you found. Somebody might have even added the feature you had in mind. +Don't make your work obsolete before you start! + +For information on how to check out Busybox from CVS, please look at the +following links: + + http://busybox.net/cvs_anon.html + http://busybox.net/cvs_howto.html + + +Read the Mailing List +~~~~~~~~~~~~~~~~~~~~~ + +No one is required to read the entire archives of the mailing list, but you +should at least read up on what people have been talking about lately. If +you've recently discovered a problem, chances are somebody else has too. If +you're the first to discover a problem, post a message and let the rest of us +know. + +Archives can be found here: + + http://busybox.net/lists/busybox/ + +If you have a serious interest in Busybox, i.e., you are using it day-to-day or +as part of an embedded project, it would be a good idea to join the mailing +list. + +A web-based sign-up form can be found here: + + http://busybox.net/mailman/listinfo/busybox + + +Coordinate with the Applet Maintainer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some (not all) of the applets in Busybox are "owned" by a maintainer who has +put significant effort into it and is probably more familiar with it than +others. To find the maintainer of an applet, look at the top of the .c file +for a name following the word 'Copyright' or 'Written by' or 'Maintainer'. + +Before plunging ahead, it's a good idea to send a message to the mailing list +that says: "Hey, I was thinking about adding the 'transmogrify' feature to the +'foo' applet. Would this be useful? Is anyone else working on it?" You might +want to CC the maintainer (if any) with your question. + + + +Areas Where You Can Help +------------------------ + +Busybox can always use improvement! If you're looking for ways to help, there +are a variety of areas where you could help. + + +What Busybox Doesn't Need +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before listing the areas where you _can_ help, it's worthwhile to mention the +areas where you shouldn't bother. While Busybox strives to be the "Swiss Army +Knife" of embedded Linux, there are some applets that will not be accepted: + + - Any filesystem manipulation tools: Busybox is filesystem independent and + we do not want to start adding mkfs/fsck tools for every (or any) + filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on + borrowed time.) There are far too many of these tools out there. Use + the upstream version. Not everything has to be part of Busybox. + + - Any partitioning tools: Partitioning a device is typically done once and + only once, and tools which do this generally do not need to reside on the + target device (esp a flash device). If you need a partitioning tool, grab + one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but + don't try to merge it into busybox. These are nasty and complex and we + don't want to maintain them. + + - Any disk, device, or media-specific tools: Use the -utils or -tools package + that was designed for your device; don't try to shoehorn them into Busybox. + + - Any architecture specific tools: Busybox is (or should be) architecture + independent. Do not send us tools that cannot be used across multiple + platforms / arches. + + - Any daemons that are not essential to basic system operation. To date, only + syslogd and klogd meet this requirement. We do not need a web server, an + ftp daemon, a dhcp server, a mail transport agent or a dns resolver. If you + need one of those, you are welcome to ask the folks on the mailing list for + recommendations, but please don't bloat up Busybox with any of these. + + +Bug Reporting +~~~~~~~~~~~~~ + +If you find bugs, please submit a detailed bug report to the busybox mailing +list at busybox@busybox.net. A well-written bug report should include a +transcript of a shell session that demonstrates the bad behavior and enables +anyone else to duplicate the bug on their own machine. The following is such +an example: + + To: busybox@busybox.net + From: diligent@testing.linux.org + Subject: /bin/date doesn't work + + Package: busybox + Version: 1.00 + + When I execute Busybox 'date' it produces unexpected results. + With GNU date I get the following output: + + $ date + Wed Mar 21 14:19:41 MST 2001 + + But when I use BusyBox date I get this instead: + + $ date + llegal instruction + + I am using Debian unstable, kernel version 2.4.19-rmk1 on an Netwinder, + and the latest uClibc from CVS. Thanks for the wonderful program! + + -Diligent + +Note the careful description and use of examples showing not only what BusyBox +does, but also a counter example showing what an equivalent GNU app does. Bug +reports lacking such detail may never be fixed... Thanks for understanding. + + + +Write Documentation +~~~~~~~~~~~~~~~~~~~ + +Chances are, documentation in Busybox is either missing or needs improvement. +Either way, help is welcome. + +Work is being done to automatically generate documentation from sources, +especially from the usage.h file. If you want to correct the documentation, +please make changes to the pre-generation parts, rather than the generated +documentation. [More to come on this later...] + +It is preferred that modifications to documentation be submitted in patch +format (more on this below), but we're a little more lenient when it comes to +docs. You could, for example, just say "after the listing of the mount +options, the following example would be helpful..." + + +Consult Existing Sources +~~~~~~~~~~~~~~~~~~~~~~~~ + +For a quick listing of "needs work" spots in the sources, cd into the Busybox +directory and run the following: + + for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; done + +This will show all of the trouble spots or 'questionable' code. Pick a spot, +any spot, these are all invitations for you to contribute. + + +Add a New Applet +~~~~~~~~~~~~~~~~ + +If you want to add a new applet to Busybox, we'd love to see it. However, +before you write any code, please ask beforehand on the mailing list something +like "Do you think applet 'foo' would be useful in Busybox?" or "Would you +guys accept applet 'foo' into Busybox if I were to write it?" If the answer is +"no" by the folks on the mailing list, then you've saved yourself some time. +Conversely, you could get some positive responses from folks who might be +interested in helping you implement it, or can recommend the best approach. +Perhaps most importantly, this is your way of calling "dibs" on something and +avoiding duplication of effort. + +Also, before you write a line of code, please read the 'new-applet-HOWTO.txt' +file in the docs/ directory. + + +Janitorial Work +~~~~~~~~~~~~~~~ + +These are dirty jobs, but somebody's gotta do 'em. + + - Converting applets to use getopt() for option processing. Type 'find -name + '*.c'|grep -L getopt' to get a listing of the applets that currently don't + use getopt. If a .c file processes no options, it should have a line that + reads: /* no options, no getopt */ somewhere in the file. + + - Replace any "naked" calls to malloc, calloc, realloc, str[n]dup, fopen with + the x* equivalents found in libbb/xfuncs.c. + + - Security audits: + http://www.securityfocus.com/popups/forums/secprog/intro.shtml + + - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This + is very Perl-specific, but the advice given in here applies equally well to + C. + + - C library function use audits: Verifying that functions are being used + properly (called with the right args), replacing unsafe library functions + with safer versions, making sure return codes are being checked, etc. + + - Where appropriate, replace preprocessor defined macros and values with + compile-time equivalents. + + - Style guide compliance. See: docs/style-guide.txt + + - Add testcases to tests/testcases. + + - Makefile improvements: + http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html + (I think the recursive problems are pretty much taken care of at this point, non?) + + - "Ten Commandments" compliance: (this is a "maybe", certainly not as + important as any of the previous items.) + http://www.lysator.liu.se/c/ten-commandments.html + +Other useful links: + + - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources + + + +Submitting Patches To Busybox +----------------------------- + +Here are some guidelines on how to submit a patch to Busybox. + + +Making A Patch +~~~~~~~~~~~~~~ + +If you've got anonymous CVS access set up, making a patch is simple. Just make +sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'. +You can send the resulting .patch file to the mailing list with a description +of what it does. (But not before you test it! See the next section for some +guidelines.) It is preferred that patches be sent as attachments, but it is +not required. + +Also, feel free to help test other people's patches and reply to them with +comments. You can apply a patch by saving it into your busybox/ directory and +typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test +if it works as advertised, and post your findings to the mailing list. + +NOTE: Please do not include extraneous or irrelevant changes in your patches. +Please do not try to "bundle" two patches together into one. Make single, +discreet changes on a per-patch basis. Sometimes you need to make a patch that +touches code in many places, but these kind of patches are rare and should be +coordinated with a maintainer. + + +Testing Guidelines +~~~~~~~~~~~~~~~~~~ + +It's considered good form to test your new feature before you submit a patch +to the mailing list, and especially before you commit a change to CVS. Here +are some guidelines on how to test your changes. + + - Always test Busybox applets against GNU counterparts and make sure the + behavior / output is identical between the two. + + - Try several different permutations and combinations of the features you're + adding (i.e., different combinations of command-line switches) and make sure + they all work; make sure one feature does not interfere with another. + + - Make sure you test compiling against the source both with the feature + turned on and turned off in Config.h and make sure Busybox compiles cleanly + both ways. + + - Run the multibuild.pl script in the tests directory and make sure + everything checks out OK. (Do this from within the busybox/ directory by + typing: 'tests/multibuild.pl'.) + + +Making Sure Your Patch Doesn't Get Lost +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you don't want your patch to be lost or forgotten, send it to the busybox +mailing list with a subject line something like this: + + [PATCH] - Adds "transmogrify" feature to "foo" + +In the body, you should have a pseudo-header that looks like the following: + + Package: busybox + Version: v1.01pre (or whatever the current version is) + Severity: wishlist + +The remainder of the body should read along these lines: + + This patch adds the "transmogrify" feature to the "foo" applet. I have + tested this on [arch] system(s) and it works. I have tested it against the + GNU counterparts and the outputs are identical. I have run the scripts in + the 'tests' directory and nothing breaks. + + + +Improving Your Chances of Patch Acceptance +------------------------------------------ + +Even after you send a brilliant patch to the mailing list, sometimes it can go +unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an +unfortunate fact of life, but there are steps you can take to help your patch +get noticed and convince a maintainer that it should be added: + + +Be Succinct +~~~~~~~~~~~ + +A patch that includes small, isolated, obvious changes is more likely to be +accepted than a patch that touches code in lots of different places or makes +sweeping, dubious changes. + + +Back It Up +~~~~~~~~~~ + +Hard facts on why your patch is better than the existing code will go a long +way toward convincing maintainers that your patch should be included. +Specifically, patches are more likely to be accepted if they are provably more +correct, smaller, faster, simpler, or more maintainable than the existing +code. + +Conversely, any patch that is supported with nothing more than "I think this +would be cool" or "this patch is good because I say it is and I've got a Phd +in Computer Science" will likely be ignored. + + +Follow The Style Guide +~~~~~~~~~~~~~~~~~~~~~~ + +It's considered good form to abide by the established coding style used in a +project; Busybox is no exception. We have gone so far as to delineate the +"elements of Busybox style" in the file docs/style-guide.txt. Please follow +them. + + +Work With Someone Else +~~~~~~~~~~~~~~~~~~~~~~ + +Working on a patch in isolation is less effective than working with someone +else for a variety of reasons. If another Busybox user is interested in what +you're doing, then it's two (or more) voices instead of one that can petition +for inclusion of the patch. You'll also have more people that can test your +changes, or even offer suggestions on better approaches you could take. + +Getting other folks interested follows as a natural course if you've received +responses from queries to applet maintainer or positive responses from folks +on the mailing list. + +We've made strident efforts to put a useful "collaboration" infrastructure in +place in the form of mailing lists, the bug tracking system, and CVS. Please +use these resources. + + +Send Patches to the Bug Tracking System +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost" +section, but it is worth mentioning again. A patch sent to the mailing list +might be unnoticed and forgotten. A patch sent to the bug tracking system will +be stored and closely connected to the bug it fixes. + + +Be Polite +~~~~~~~~~ + +The old saying "You'll catch more flies with honey than you will with vinegar" +applies when submitting patches to the mailing list for approval. The way you +present your patch is sometimes just as important as the actual patch itself +(if not more so). Being rude to the maintainers is not an effective way to +convince them that your patch should be included; it will likely have the +opposite effect. + + + +Committing Changes to CVS +------------------------- + +If you submit several patches that demonstrate that you are a skilled and wise +coder, you may be invited to become a committer, thus enabling you to commit +changes directly to CVS. This is nice because you don't have to wait for +someone else to commit your change for you, you can just do it yourself. + +But note that this is a privilege that comes with some responsibilities. You +should test your changes before you commit them. You should also talk to an +applet maintainer before you make any kind of sweeping changes to somebody +else's code. Big changes should still go to the mailing list first. Remember, +being wise, polite, and discreet is more important than being clever. + + +When To Commit +~~~~~~~~~~~~~~ + +Generally, you should feel free to commit a change if: + + - Your changes are small and don't touch many files + - You are fixing a bug + - Somebody has told you that it's okay + - It's obviously the Right Thing + +The more of the above are true, the better it is to just commit a change +directly to CVS. + + +When Not To Commit +~~~~~~~~~~~~~~~~~~ + +Even if you have commit rights, you should probably still post a patch to the +mailing list if: + + - Your changes are broad and touch many different files + - You are adding a feature + - Your changes are speculative or experimental (i.e., trying a new algorithm) + - You are not the maintainer and your changes make the maintainer cringe + +The more of the above are true, the better it is to post a patch to the +mailing list instead of committing. + + + +Final Words +----------- + +If all of this seems complicated, don't panic, it's really not that tough. If +you're having difficulty following some of the steps outlined in this +document don't worry, the folks on the Busybox mailing list are a fairly +good-natured bunch and will work with you to help get your patches into shape +or help you make contributions. + + diff --git a/docs/ctty.htm b/docs/ctty.htm new file mode 100644 index 0000000..8f466cd --- /dev/null +++ b/docs/ctty.htm @@ -0,0 +1,476 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html><head> + <!-- saved from http://www.win.tue.nl/~aeb/linux/lk/lk-10.html --> + <meta name="GENERATOR" content="SGML-Tools 1.0.9"><title>The Linux kernel: Processes</title> +</head> +<body> +<hr> +<h2><a name="s10">10. Processes</a></h2> + +<p>Before looking at the Linux implementation, first a general Unix +description of threads, processes, process groups and sessions. +</p><p>A session contains a number of process groups, and a process group +contains a number of processes, and a process contains a number +of threads. +</p><p>A session can have a controlling tty. +At most one process group in a session can be a foreground process group. +An interrupt character typed on a tty ("Teletype", i.e., terminal) +causes a signal to be sent to all members of the foreground process group +in the session (if any) that has that tty as controlling tty. +</p><p>All these objects have numbers, and we have thread IDs, process IDs, +process group IDs and session IDs. +</p><p> +</p><h2><a name="ss10.1">10.1 Processes</a> +</h2> + +<p> +</p><h3>Creation</h3> + +<p>A new process is traditionally started using the <code>fork()</code> +system call: +</p><blockquote> +<pre>pid_t p; + +p = fork(); +if (p == (pid_t) -1) + /* ERROR */ +else if (p == 0) + /* CHILD */ +else + /* PARENT */ +</pre> +</blockquote> +<p>This creates a child as a duplicate of its parent. +Parent and child are identical in almost all respects. +In the code they are distinguished by the fact that the parent +learns the process ID of its child, while <code>fork()</code> +returns 0 in the child. (It can find the process ID of its +parent using the <code>getppid()</code> system call.) +</p><p> +</p><h3>Termination</h3> + +<p>Normal termination is when the process does +</p><blockquote> +<pre>exit(n); +</pre> +</blockquote> + +or +<blockquote> +<pre>return n; +</pre> +</blockquote> + +from its <code>main()</code> procedure. It returns the single byte <code>n</code> +to its parent. +<p>Abnormal termination is usually caused by a signal. +</p><p> +</p><h3>Collecting the exit code. Zombies</h3> + +<p>The parent does +</p><blockquote> +<pre>pid_t p; +int status; + +p = wait(&status); +</pre> +</blockquote> + +and collects two bytes: +<p> +<figure> +<eps file="absent"> +<img src="ctty_files/exit_status.png"> +</eps> +</figure></p><p>A process that has terminated but has not yet been waited for +is a <i>zombie</i>. It need only store these two bytes: +exit code and reason for termination. +</p><p>On the other hand, if the parent dies first, <code>init</code> (process 1) +inherits the child and becomes its parent. +</p><p> +</p><h3>Signals</h3> + +<p> +</p><h3>Stopping</h3> + +<p>Some signals cause a process to stop: +<code>SIGSTOP</code> (stop!), +<code>SIGTSTP</code> (stop from tty: probably ^Z was typed), +<code>SIGTTIN</code> (tty input asked by background process), +<code>SIGTTOU</code> (tty output sent by background process, and this was +disallowed by <code>stty tostop</code>). +</p><p>Apart from ^Z there also is ^Y. The former stops the process +when it is typed, the latter stops it when it is read. +</p><p>Signals generated by typing the corresponding character on some tty +are sent to all processes that are in the foreground process group +of the session that has that tty as controlling tty. (Details below.) +</p><p>If a process is being traced, every signal will stop it. +</p><p> +</p><h3>Continuing</h3> + +<p><code>SIGCONT</code>: continue a stopped process. +</p><p> +</p><h3>Terminating</h3> + +<p><code>SIGKILL</code> (die! now!), +<code>SIGTERM</code> (please, go away), +<code>SIGHUP</code> (modem hangup), +<code>SIGINT</code> (^C), +<code>SIGQUIT</code> (^\), etc. +Many signals have as default action to kill the target. +(Sometimes with an additional core dump, when such is +allowed by rlimit.) +The signals <code>SIGCHLD</code> and <code>SIGWINCH</code> +are ignored by default. +All except <code>SIGKILL</code> and <code>SIGSTOP</code> can be +caught or ignored or blocked. +For details, see <code>signal(7)</code>. +</p><p> +</p><h2><a name="ss10.2">10.2 Process groups</a> +</h2> + +<p>Every process is member of a unique <i>process group</i>, +identified by its <i>process group ID</i>. +(When the process is created, it becomes a member of the process group +of its parent.) +By convention, the process group ID of a process group +equals the process ID of the first member of the process group, +called the <i>process group leader</i>. +A process finds the ID of its process group using the system call +<code>getpgrp()</code>, or, equivalently, <code>getpgid(0)</code>. +One finds the process group ID of process <code>p</code> using +<code>getpgid(p)</code>. +</p><p>One may use the command <code>ps j</code> to see PPID (parent process ID), +PID (process ID), PGID (process group ID) and SID (session ID) +of processes. With a shell that does not know about job control, +like <code>ash</code>, each of its children will be in the same session +and have the same process group as the shell. With a shell that knows +about job control, like <code>bash</code>, the processes of one pipeline, like +</p><blockquote> +<pre>% cat paper | ideal | pic | tbl | eqn | ditroff > out +</pre> +</blockquote> + +form a single process group. +<p> +</p><h3>Creation</h3> + +<p>A process <code>pid</code> is put into the process group <code>pgid</code> by +</p><blockquote> +<pre>setpgid(pid, pgid); +</pre> +</blockquote> + +If <code>pgid == pid</code> or <code>pgid == 0</code> then this creates +a new process group with process group leader <code>pid</code>. +Otherwise, this puts <code>pid</code> into the already existing +process group <code>pgid</code>. +A zero <code>pid</code> refers to the current process. +The call <code>setpgrp()</code> is equivalent to <code>setpgid(0,0)</code>. +<p> +</p><h3>Restrictions on setpgid()</h3> + +<p>The calling process must be <code>pid</code> itself, or its parent, +and the parent can only do this before <code>pid</code> has done +<code>exec()</code>, and only when both belong to the same session. +It is an error if process <code>pid</code> is a session leader +(and this call would change its <code>pgid</code>). +</p><p> +</p><h3>Typical sequence</h3> + +<p> +</p><blockquote> +<pre>p = fork(); +if (p == (pid_t) -1) { + /* ERROR */ +} else if (p == 0) { /* CHILD */ + setpgid(0, pgid); + ... +} else { /* PARENT */ + setpgid(p, pgid); + ... +} +</pre> +</blockquote> + +This ensures that regardless of whether parent or child is scheduled +first, the process group setting is as expected by both. +<p> +</p><h3>Signalling and waiting</h3> + +<p>One can signal all members of a process group: +</p><blockquote> +<pre>killpg(pgrp, sig); +</pre> +</blockquote> +<p>One can wait for children in ones own process group: +</p><blockquote> +<pre>waitpid(0, &status, ...); +</pre> +</blockquote> + +or in a specified process group: +<blockquote> +<pre>waitpid(-pgrp, &status, ...); +</pre> +</blockquote> +<p> +</p><h3>Foreground process group</h3> + +<p>Among the process groups in a session at most one can be +the <i>foreground process group</i> of that session. +The tty input and tty signals (signals generated by ^C, ^Z, etc.) +go to processes in this foreground process group. +</p><p>A process can determine the foreground process group in its session +using <code>tcgetpgrp(fd)</code>, where <code>fd</code> refers to its +controlling tty. If there is none, this returns a random value +larger than 1 that is not a process group ID. +</p><p>A process can set the foreground process group in its session +using <code>tcsetpgrp(fd,pgrp)</code>, where <code>fd</code> refers to its +controlling tty, and <code>pgrp</code> is a process group in +its session, and this session still is associated to the controlling +tty of the calling process. +</p><p>How does one get <code>fd</code>? By definition, <code>/dev/tty</code> +refers to the controlling tty, entirely independent of redirects +of standard input and output. (There is also the function +<code>ctermid()</code> to get the name of the controlling terminal. +On a POSIX standard system it will return <code>/dev/tty</code>.) +Opening the name of the +controlling tty gives a file descriptor <code>fd</code>. +</p><p> +</p><h3>Background process groups</h3> + +<p>All process groups in a session that are not foreground +process group are <i>background process groups</i>. +Since the user at the keyboard is interacting with foreground +processes, background processes should stay away from it. +When a background process reads from the terminal it gets +a SIGTTIN signal. Normally, that will stop it, the job control shell +notices and tells the user, who can say <code>fg</code> to continue +this background process as a foreground process, and then this +process can read from the terminal. But if the background process +ignores or blocks the SIGTTIN signal, or if its process group +is orphaned (see below), then the read() returns an EIO error, +and no signal is sent. (Indeed, the idea is to tell the process +that reading from the terminal is not allowed right now. +If it wouldn't see the signal, then it will see the error return.) +</p><p>When a background process writes to the terminal, it may get +a SIGTTOU signal. May: namely, when the flag that this must happen +is set (it is off by default). One can set the flag by +</p><blockquote> +<pre>% stty tostop +</pre> +</blockquote> + +and clear it again by +<blockquote> +<pre>% stty -tostop +</pre> +</blockquote> + +and inspect it by +<blockquote> +<pre>% stty -a +</pre> +</blockquote> + +Again, if TOSTOP is set but the background process ignores or blocks +the SIGTTOU signal, or if its process group is orphaned (see below), +then the write() returns an EIO error, and no signal is sent. +<p> +</p><h3>Orphaned process groups</h3> + +<p>The process group leader is the first member of the process group. +It may terminate before the others, and then the process group is +without leader. +</p><p>A process group is called <i>orphaned</i> when <i>the +parent of every member is either in the process group +or outside the session</i>. +In particular, the process group of the session leader +is always orphaned. +</p><p>If termination of a process causes a process group to become +orphaned, and some member is stopped, then all are sent first SIGHUP +and then SIGCONT. +</p><p>The idea is that perhaps the parent of the process group leader +is a job control shell. (In the same session but a different +process group.) As long as this parent is alive, it can +handle the stopping and starting of members in the process group. +When it dies, there may be nobody to continue stopped processes. +Therefore, these stopped processes are sent SIGHUP, so that they +die unless they catch or ignore it, and then SIGCONT to continue them. +</p><p>Note that the process group of the session leader is already +orphaned, so no signals are sent when the session leader dies. +</p><p>Note also that a process group can become orphaned in two ways +by termination of a process: either it was a parent and not itself +in the process group, or it was the last element of the process group +with a parent outside but in the same session. +Furthermore, that a process group can become orphaned +other than by termination of a process, namely when some +member is moved to a different process group. +</p><p> +</p><h2><a name="ss10.3">10.3 Sessions</a> +</h2> + +<p>Every process group is in a unique <i>session</i>. +(When the process is created, it becomes a member of the session +of its parent.) +By convention, the session ID of a session +equals the process ID of the first member of the session, +called the <i>session leader</i>. +A process finds the ID of its session using the system call +<code>getsid()</code>. +</p><p>Every session may have a <i>controlling tty</i>, +that then also is called the controlling tty of each of +its member processes. +A file descriptor for the controlling tty is obtained by +opening <code>/dev/tty</code>. (And when that fails, there was no +controlling tty.) Given a file descriptor for the controlling tty, +one may obtain the SID using <code>tcgetsid(fd)</code>. +</p><p>A session is often set up by a login process. The terminal +on which one is logged in then becomes the controlling tty +of the session. All processes that are descendants of the +login process will in general be members of the session. +</p><p> +</p><h3>Creation</h3> + +<p>A new session is created by +</p><blockquote> +<pre>pid = setsid(); +</pre> +</blockquote> + +This is allowed only when the current process is not a process group leader. +In order to be sure of that we fork first: +<blockquote> +<pre>p = fork(); +if (p) exit(0); +pid = setsid(); +</pre> +</blockquote> + +The result is that the current process (with process ID <code>pid</code>) +becomes session leader of a new session with session ID <code>pid</code>. +Moreover, it becomes process group leader of a new process group. +Both session and process group contain only the single process <code>pid</code>. +Furthermore, this process has no controlling tty. +<p>The restriction that the current process must not be a process group leader +is needed: otherwise its PID serves as PGID of some existing process group +and cannot be used as the PGID of a new process group. +</p><p> +</p><h3>Getting a controlling tty</h3> + +<p>How does one get a controlling terminal? Nobody knows, +this is a great mystery. +</p><p>The System V approach is that the first tty opened by the process +becomes its controlling tty. +</p><p>The BSD approach is that one has to explicitly call +</p><blockquote> +<pre>ioctl(fd, TIOCSCTTY, 0/1); +</pre> +</blockquote> + +to get a controlling tty. +<p>Linux tries to be compatible with both, as always, and this +results in a very obscure complex of conditions. Roughly: +</p><p>The <code>TIOCSCTTY</code> ioctl will give us a controlling tty, +provided that (i) the current process is a session leader, +and (ii) it does not yet have a controlling tty, and +(iii) maybe the tty should not already control some other session; +if it does it is an error if we aren't root, or we steal the tty +if we are all-powerful. +[vda: correction: third parameter controls this: if 1, we steal tty from +any such session, if 0, we don't steal] +</p><p>Opening some terminal will give us a controlling tty, +provided that (i) the current process is a session leader, and +(ii) it does not yet have a controlling tty, and +(iii) the tty does not already control some other session, and +(iv) the open did not have the <code>O_NOCTTY</code> flag, and +(v) the tty is not the foreground VT, and +(vi) the tty is not the console, and +(vii) maybe the tty should not be master or slave pty. +</p><p> +</p><h3>Getting rid of a controlling tty</h3> + +<p>If a process wants to continue as a daemon, it must detach itself +from its controlling tty. Above we saw that <code>setsid()</code> +will remove the controlling tty. Also the ioctl TIOCNOTTY does this. +Moreover, in order not to get a controlling tty again as soon as it +opens a tty, the process has to fork once more, to assure that it +is not a session leader. Typical code fragment: +</p><p> +</p><pre> if ((fork()) != 0) + exit(0); + setsid(); + if ((fork()) != 0) + exit(0); +</pre> +<p>See also <code>daemon(3)</code>. +</p><p> +</p><h3>Disconnect</h3> + +<p>If the terminal goes away by modem hangup, and the line was not local, +then a SIGHUP is sent to the session leader. +Any further reads from the gone terminal return EOF. +(Or possibly -1 with <code>errno</code> set to EIO.) +</p><p>If the terminal is the slave side of a pseudotty, and the master side +is closed (for the last time), then a SIGHUP is sent to the foreground +process group of the slave side. +</p><p>When the session leader dies, a SIGHUP is sent to all processes +in the foreground process group. Moreover, the terminal stops being +the controlling terminal of this session (so that it can become +the controlling terminal of another session). +</p><p>Thus, if the terminal goes away and the session leader is +a job control shell, then it can handle things for its descendants, +e.g. by sending them again a SIGHUP. +If on the other hand the session leader is an innocent process +that does not catch SIGHUP, it will die, and all foreground processes +get a SIGHUP. +</p><p> +</p><h2><a name="ss10.4">10.4 Threads</a> +</h2> + +<p>A process can have several threads. New threads (with the same PID +as the parent thread) are started using the <code>clone</code> system +call using the <code>CLONE_THREAD</code> flag. Threads are distinguished +by a <i>thread ID</i> (TID). An ordinary process has a single thread +with TID equal to PID. The system call <code>gettid()</code> returns the +TID. The system call <code>tkill()</code> sends a signal to a single thread. +</p><p>Example: a process with two threads. Both only print PID and TID and exit. +(Linux 2.4.19 or later.) +</p><pre>% cat << EOF > gettid-demo.c +#include <unistd.h> +#include <sys/types.h> +#define CLONE_SIGHAND 0x00000800 +#define CLONE_THREAD 0x00010000 +#include <linux/unistd.h> +#include <errno.h> +_syscall0(pid_t,gettid) + +int thread(void *p) { + printf("thread: %d %d\n", gettid(), getpid()); +} + +main() { + unsigned char stack[4096]; + int i; + + i = clone(thread, stack+2048, CLONE_THREAD | CLONE_SIGHAND, NULL); + if (i == -1) + perror("clone"); + else + printf("clone returns %d\n", i); + printf("parent: %d %d\n", gettid(), getpid()); +} +EOF +% cc -o gettid-demo gettid-demo.c +% ./gettid-demo +clone returns 21826 +parent: 21825 21825 +thread: 21826 21825 +% +</pre> +<p> +</p><p> +</p><hr> + +</body></html> diff --git a/docs/draft-coar-cgi-v11-03-clean.html b/docs/draft-coar-cgi-v11-03-clean.html new file mode 100644 index 0000000..d52c9b8 --- /dev/null +++ b/docs/draft-coar-cgi-v11-03-clean.html @@ -0,0 +1,2674 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<HTML> + <HEAD> + <TITLE>Common Gateway Interface - 1.1 *Draft 03* [http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html] + </TITLE> +<!--#if expr="$HTTP_USER_AGENT != /Lynx/" --> + <!--#set var="GUI" value="1" --> +<!--#endif --> + <LINK HREF="mailto:Ken.Coar@Golux.Com" rev="revised"> + <LINK REL="STYLESHEET" HREF="cgip-style-rfc.css" TYPE="text/css"> + <META name="latexstyle" content="rfc"> + <META name="author" content="Ken A L Coar"> + <META name="institute" content="IBM Corporation"> + <META name="date" content="25 June 1999"> + <META name="expires" content="Expires 31 December 1999"> + <META name="document" content="INTERNET-DRAFT"> + <META name="file" content="<draft-coar-cgi-v11-03.txt>"> + <META name="group" content="INTERNET-DRAFT"> +<!-- + There are a lot of BNF fragments in this document. To make it work + in all possible browsers (including Lynx, which is used to turn it + into text/plain), we handle these by using PREformatted blocks with + a universal internal margin of 2, inside one-level DL blocks. + --> + </HEAD> + <BODY> + <!-- + HTML doesn't do paper pagination, so we need to fake it out. Basing + our formatting upon RFC2068, there are four (4) lines of header and + four (4) lines of footer for each page. + +<DIV ALIGN="CENTER"> + <PRE> + + + + +Coar, et al. CGI/1.1 Specification May, 1998 +INTERNET-DRAFT Expires 1 December 1998 [Page 2] + + + </PRE> +</DIV> + --> + <!-- + The following weirdness wrt non-breaking spaces is to get Lynx + (which is barely TABLE-aware) to line the left/right justified + text up properly. + --> + <DIV ALIGN="CENTER"> + <TABLE WIDTH="100%" CELLPADDING=0 CELLSPACING=0> + <TR VALIGN="TOP"> + <TD ALIGN="LEFT"> + INTERNET-DRAFT + </TD> + <TD ALIGN="RIGHT"> + Ken A L Coar + </TD> + </TR> + <TR VALIGN="TOP"> + <TD ALIGN="LEFT"> + draft-coar-cgi-v11-03.{html,txt} + </TD> + <TD ALIGN="RIGHT"> + IBM Corporation + </TD> + </TR> + <TR VALIGN="TOP"> + <TD ALIGN="LEFT"> + + </TD> + <TD ALIGN="RIGHT"> + D.R.T. Robinson + </TD> + </TR> + <TR VALIGN="TOP"> + <TD ALIGN="LEFT"> + + </TD> + <TD ALIGN="RIGHT"> + E*TRADE UK Ltd. + </TD> + </TR> + <TR VALIGN="TOP"> + <TD ALIGN="LEFT"> + + </TD> + <TD ALIGN="RIGHT"> + 25 June 1999 + </TD> + </TR> + </TABLE> + </DIV> + + <H1 ALIGN="CENTER"> + The WWW Common Gateway Interface + <BR> + Version 1.1 + </H1> + +<!--#include virtual="I-D-statement" --> + + <H2> + <A NAME="Abstract"> + Abstract + </A> + </H2> + <P> + The Common Gateway Interface (CGI) is a simple interface for running + external programs, software or gateways under an information server + in a platform-independent manner. Currently, the supported information + servers are HTTP servers. + </P> + <P> + The interface has been in use by the World-Wide Web since 1993. This + specification defines the + "current practice" parameters of the + 'CGI/1.1' interface developed and documented at the U.S. National + Centre for Supercomputing Applications [NCSA-CGI]. + This document also defines the use of the CGI/1.1 interface + on the Unix and AmigaDOS(tm) systems. + </P> + <P> + Discussion of this draft occurs on the CGI-WG mailing list; see the + project Web page at + <SAMP><URL:<A HREF="http://CGI-Spec.Golux.Com/" + >http://CGI-Spec.Golux.Com/</A>></SAMP> + for details on the mailing list and the status of the project. + </P> + +<!--#if expr="$GUI" --> + <H2> + Revision History + </H2> + <P> + The revision history of this draft is being maintained using Web-based + GUI notation, such as struck-through characters and colour-coded + sections. The following legend describes how to determine the origin + of a particular revision according to the colour of the text: + </P> + <DL COMPACT> + <DT>Black + </DT> + <DD>Revision 00, released 28 May 1998 + </DD> + <DT>Green + </DT> + <DD>Revision 01, released 28 December 1998 + <BR> + Major structure change: Section 4, "Request Metadata (Meta-Variables)" + was moved entirely under <A HREF="#7.0">Section 7</A>, "Data Input to the + CGI Script." + Due to the size of this change, it is noted here and the text in its + former location does <EM>not</EM> appear as struckthrough. This has + caused major <A HREF="#6.0">sections 5</A> and following to decrement + by one. Other + large text movements are likewise not marked up. References to RFC + 1738 were changed to 2396 (1738's replacement). + </DD> + <DT>Red + </DT> + <DD>Revision 02, released 2 April, 1999 + <BR> + Added text to <A HREF="#8.3">section 8.3</A> defining correct handling + of HTTP/1.1 + requests using "chunked" Transfer-Encoding. Labelled metavariable + names in <A HREF="#8.0">section 8</A> with the appropriate detail section + numbers. + Clarified allowed usage of <SAMP>Status</SAMP> and + <SAMP>Location</SAMP> response header fields. Included new + Internet-Draft language. + </DD> + <DT>Fuchsia + </DT> + <DD>Revision 03, released 25 June 1999 + <BR> + Changed references from "HTTP" to "Protocol-Specific" for the listing of + things like HTTP_ACCEPT. Changed 'entity-body' and 'content-body' to + 'message-body.' Added a note that response headers must comply with + requirements of the protocol level in use. Added a lot of stuff about + security (section 11). Clarified a bunch of productions. Pointed out + that zero-length and omitted values are indistinguishable in this + specification. Clarified production describing order of fields in + script response header. Clarified issues surrounding encoding of + data. Acknowledged additional contributors, and changed one of + the authors' addresses. + </DD> + </DL> +<!--#endif --> + + <H2> + <A NAME="Contents"> + Table of Contents + </A> + </H2> + <DIV ALIGN="CENTER"> + <PRE> + 1 Introduction..............................................<A + HREF="#1.0" + >TBD</A> + 1.1 Purpose................................................<A + HREF="#1.1" + >TBD</A> + 1.2 Requirements...........................................<A + HREF="#1.2" + >TBD</A> + 1.3 Specifications.........................................<A + HREF="#1.3" + >TBD</A> + 1.4 Terminology............................................<A + HREF="#1.4" + >TBD</A> + 2 Notational Conventions and Generic Grammar................<A + HREF="#2.0" + >TBD</A> + 2.1 Augmented BNF..........................................<A + HREF="#2.1" + >TBD</A> + 2.2 Basic Rules............................................<A + HREF="#2.2" + >TBD</A> + 3 Protocol Parameters.......................................<A + HREF="#3.0" + >TBD</A> + 3.1 URL Encoding...........................................<A + HREF="#3.1" + >TBD</A> + 3.2 The Script-URI.........................................<A + HREF="#3.2" + >TBD</A> + 4 Invoking the Script.......................................<A + HREF="#4.0" + >TBD</A> + 5 The CGI Script Command Line...............................<A + HREF="#5.0" + >TBD</A> + 6 Data Input to the CGI Script..............................<A + HREF="#6.0" + >TBD</A> + 6.1 Request Metadata (Metavariables).......................<A + HREF="#6.1" + >TBD</A> + 6.1.1 AUTH_TYPE...........................................<A + HREF="#6.1.1" + >TBD</A> + 6.1.2 CONTENT_LENGTH......................................<A + HREF="#6.1.2" + >TBD</A> + 6.1.3 CONTENT_TYPE........................................<A + HREF="#6.1.3" + >TBD</A> + 6.1.4 GATEWAY_INTERFACE...................................<A + HREF="#6.1.4" + >TBD</A> + 6.1.5 Protocol-Specific Metavariables.....................<A + HREF="#6.1.5" + >TBD</A> + 6.1.6 PATH_INFO...........................................<A + HREF="#6.1.6" + >TBD</A> + 6.1.7 PATH_TRANSLATED.....................................<A + HREF="#6.1.7" + >TBD</A> + 6.1.8 QUERY_STRING........................................<A + HREF="#6.1.8" + >TBD</A> + 6.1.9 REMOTE_ADDR.........................................<A + HREF="#6.1.9" + >TBD</A> + 6.1.10 REMOTE_HOST........................................<A + HREF="#6.1.10" + >TBD</A> + 6.1.11 REMOTE_IDENT.......................................<A + HREF="#6.1.11" + >TBD</A> + 6.1.12 REMOTE_USER........................................<A + HREF="#6.1.12" + >TBD</A> + 6.1.13 REQUEST_METHOD.....................................<A + HREF="#6.1.13" + >TBD</A> + 6.1.14 SCRIPT_NAME........................................<A + HREF="#6.1.14" + >TBD</A> + 6.1.15 SERVER_NAME........................................<A + HREF="#6.1.15" + >TBD</A> + 6.1.16 SERVER_PORT........................................<A + HREF="#6.1.16" + >TBD</A> + 6.1.17 SERVER_PROTOCOL....................................<A + HREF="#6.1.17" + >TBD</A> + 6.1.18 SERVER_SOFTWARE....................................<A + HREF="#6.1.18" + >TBD</A> + 6.2 Request Message-Bodies................................<A + HREF="#6.2" + >TBD</A> + 7 Data Output from the CGI Script...........................<A + HREF="#7.0" + >TBD</A> + 7.1 Non-Parsed Header Output...............................<A + HREF="#7.1" + >TBD</A> + 7.2 Parsed Header Output...................................<A + HREF="#7.2" + >TBD</A> + 7.2.1 CGI header fields...................................<A + HREF="#7.2.1" + >TBD</A> + 7.2.1.1 Content-Type.....................................<A + HREF="#7.2.1.1" + >TBD</A> + 7.2.1.2 Location.........................................<A + HREF="#7.2.1.2" + >TBD</A> + 7.2.1.3 Status...........................................<A + HREF="#7.2.1.3" + >TBD</A> + 7.2.1.4 Extension header fields..........................<A + HREF="#7.2.1.3" + >TBD</A> + 7.2.2 HTTP header fields..................................<A + HREF="#7.2.2" + >TBD</A> + 8 Server Implementation.....................................<A + HREF="#8.0" + >TBD</A> + 8.1 Requirements for Servers...............................<A + HREF="#8.1" + >TBD</A> + 8.1.1 Script-URI..........................................<A + HREF="#8.1" + >TBD</A> + 8.1.2 Request Message-body Handling.......................<A + HREF="#8.1.2" + >TBD</A> + 8.1.3 Required Metavariables..............................<A + HREF="#8.1.3" + >TBD</A> + 8.1.4 Response Compliance.................................<A + HREF="#8.1.4" + >TBD</A> + 8.2 Recommendations for Servers............................<A + HREF="#8.2" + >TBD</A> + 8.3 Summary of Metavariables...............................<A + HREF="#8.3" + >TBD</A> + 9 Script Implementation.....................................<A + HREF="#9.0" + >TBD</A> + 9.1 Requirements for Scripts...............................<A + HREF="#9.1" + >TBD</A> + 9.2 Recommendations for Scripts............................<A + HREF="#9.2" + >TBD</A> + 10 System Specifications....................................<A + HREF="#10.0" + >TBD</A> + 10.1 AmigaDOS..............................................<A + HREF="#10.1" + >TBD</A> + 10.2 Unix..................................................<A + HREF="#10.2" + >TBD</A> + 11 Security Considerations..................................<A + HREF="#11.0" + >TBD</A> + 11.1 Safe Methods..........................................<A + HREF="#11.1" + >TBD</A> + 11.2 HTTP Header Fields Containing Sensitive Information...<A + HREF="#11.2" + >TBD</A> + 11.3 Script Interference with the Server...................<A + HREF="#11.3" + >TBD</A> + 11.4 Data Length and Buffering Considerations..............<A + HREF="#11.4" + >TBD</A> + 11.5 Stateless Processing..................................<A + HREF="#11.5" + >TBD</A> + 12 Acknowledgments..........................................<A + HREF="#12.0" + >TBD</A> + 13 References...............................................<A + HREF="#13.0" + >TBD</A> + 14 Authors' Addresses.......................................<A + HREF="#14.0" + >TBD</A> + </PRE> + </DIV> + + <H2> + <A NAME="1.0"> + 1. Introduction + </A> + </H2> + + <H3> + <A NAME="1.1"> + 1.1. Purpose + </A> + </H3> + <P> + Together the HTTP [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>] server + and the CGI script are responsible + for servicing a client + request by sending back responses. The client + request comprises a Universal Resource Identifier (URI) + [<A HREF="#[1]">1</A>], a + request method, and various ancillary + information about the request + provided by the transport mechanism. + </P> + <P> + The CGI defines the abstract parameters, known as + metavariables, + which describe the client's + request. Together with a + concrete programmer interface this specifies a platform-independent + interface between the script and the HTTP server. + </P> + + <H3> + <A NAME="1.2"> + 1.2. Requirements + </A> + </H3> + <P> + This specification uses the same words as RFC 1123 + [<A HREF="#[5]">5</A>] to define the + significance of each particular requirement. These are: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <DL> + <DT><EM>MUST</EM> + </DT> + <DD> + <P> + This word or the adjective 'required' means that the item is an + absolute requirement of the specification. + </P> + </DD> + <DT><EM>SHOULD</EM> + </DT> + <DD> + <P> + This word or the adjective 'recommended' means that there may + exist valid reasons in particular circumstances to ignore this + item, but the full implications should be understood and the case + carefully weighed before choosing a different course. + </P> + </DD> + <DT><EM>MAY</EM> + </DT> + <DD> + <P> + This word or the adjective 'optional' means that this item is + truly optional. One vendor may choose to include the item because + a particular marketplace requires it or because it enhances the + product, for example; another vendor may omit the same item. + </P> + </DD> + </DL> + <P> + An implementation is not compliant if it fails to satisfy one or more + of the 'must' requirements for the protocols it implements. An + implementation that satisfies all of the 'must' and all of the + 'should' requirements for its features is said to be 'unconditionally + compliant'; one that satisfies all of the 'must' requirements but not + all of the 'should' requirements for its features is said to be + 'conditionally compliant.' + </P> + + <H3> + <A NAME="1.3"> + 1.3. Specifications + </A> + </H3> + <P> + Not all of the functions and features of the CGI are defined in the + main part of this specification. The following phrases are used to + describe the features which are not specified: + </P> + <DL> + <DT><EM>system defined</EM> + </DT> + <DD> + <P> + The feature may differ between systems, but must be the same for + different implementations using the same system. A system will + usually identify a class of operating-systems. Some systems are + defined in + <A HREF="#10.0" + >section 10</A> of this document. + New systems may be defined + by new specifications without revision of this document. + </P> + </DD> + <DT><EM>implementation defined</EM> + </DT> + <DD> + <P> + The behaviour of the feature may vary from implementation to + implementation, but a particular implementation must document its + behaviour. + </P> + </DD> + </DL> + + <H3> + <A NAME="1.4"> + 1.4. Terminology + </A> + </H3> + <P> + This specification uses many terms defined in the HTTP/1.1 + specification [<A HREF="#[8]">8</A>]; however, the following terms are + used here in a + sense which may not accord with their definitions in that document, + or with their common meaning. + </P> + + <DL> + <DT><EM>metavariable</EM> + </DT> + <DD> + <P> + A named parameter that carries information from the server to the + script. It is not necessarily a variable in the operating-system's + environment, although that is the most common implementation. + </P> + </DD> + + <DT><EM>script</EM> + </DT> + <DD> + <P> + The software which is invoked by the server <EM>via</EM> this + interface. It + need not be a standalone program, but could be a + dynamically-loaded or shared library, or even a subroutine in the + server. It <EM>may</EM> be a set of statements + interpreted at run-time, as the term 'script' is frequently + understood, but that is not a requirement and within the context + of this specification the term has the broader definition stated. + </P> + </DD> + <DT><EM>server</EM> + </DT> + <DD> + <P> + The application program which invokes the script in order to service + requests. + </P> + </DD> + </DL> + + <H2> + <A NAME="2.0"> + 2. Notational Conventions and Generic Grammar + </A> + </H2> + + <H3> + <A NAME="2.1"> + 2.1. Augmented BNF + </A> + </H3> + <P> + All of the mechanisms specified in this document are described in + both prose and an augmented Backus-Naur Form (BNF) similar to that + used by RFC 822 [<A HREF="#[6]">6</A>]. This augmented BNF contains + the following constructs: + </P> + <DL> + <DT>name = definition + </DT> + <DD> + <P> + The + definition by the equal character ("="). Whitespace is only + significant in that continuation lines of a definition are + indented. + </P> + </DD> + <DT>"literal" + </DT> + <DD> + <P> + Quotation marks (") surround literal text, except for a literal + quotation mark, which is surrounded by angle-brackets ("<" and ">"). + Unless stated otherwise, the text is case-sensitive. + </P> + </DD> + <DT>rule1 | rule2 + </DT> + <DD> + <P> + Alternative rules are separated by a vertical bar ("|"). + </P> + </DD> + <DT>(rule1 rule2 rule3) + </DT> + <DD> + <P> + Elements enclosed in parentheses are treated as a single element. + </P> + </DD> + <DT>*rule + </DT> + <DD> + <P> + A rule preceded by an asterisk ("*") may have zero or more + occurrences. A rule preceded by an integer followed by an asterisk + must occur at least the specified number of times. + </P> + </DD> + <DT>[rule] + </DT> + <DD> + <P> + An element enclosed in square + brackets ("[" and "]") is optional. + </P> + </DD> + </DL> + + <H3> + <A NAME="2.2"> + 2.2. Basic Rules + </A> + </H3> + <P> + The following rules are used throughout this specification to + describe basic parsing constructs. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + alpha = lowalpha | hialpha + alphanum = alpha | digit + lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" + | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" + | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" + | "y" | "z" + hialpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" + | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" + | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" + | "Y" | "Z" + digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" + | "8" | "9" + hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" + | "b" | "c" | "d" | "e" | "f" + escaped = "%" hex hex + OCTET = <any 8-bit sequence of data> + CHAR = <any US-ASCII character (octets 0 - 127)> + CTL = <any US-ASCII control character + (octets 0 - 31) and DEL (127)> + CR = <US-ASCII CR, carriage return (13)> + LF = <US-ASCII LF, linefeed (10)> + SP = <US-ASCII SP, space (32)> + HT = <US-ASCII HT, horizontal tab (9)> + NL = CR | LF + LWSP = SP | HT | NL + tspecial = "(" | ")" | "@" | "," | ";" | ":" | "\" | <"> + | "/" | "[" | "]" | "?" | "<" | ">" | "{" | "}" + | SP | HT | NL + token = 1*<any CHAR except CTLs or tspecials> + quoted-string = ( <"> *qdtext <"> ) | ( "<" *qatext ">") + qdtext = <any CHAR except <"> and CTLs but including LWSP> + qatext = <any CHAR except "<", ">" and CTLs but + including LWSP> + mark = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")" + unreserved = alphanum | mark + reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | + "$" | "," + uric = reserved | unreserved | escaped + </PRE> + <P> + Note that newline (NL) need not be a single character, but can be a + character sequence. + </P> + + <H2> + <A NAME="3.0"> + 3. Protocol Parameters + </A> + </H2> + + <H3> + <A NAME="3.1"> + 3.1. URL Encoding + </A> + </H3> + <P> + Some variables and constructs used here are described as being + 'URL-encoded'. This encoding is described in section + 2 of RFC + 2396 + [<A HREF="#[4]">4</A>]. + </P> + <P> + An alternate "shortcut" encoding for representing the space + character exists and is in common use. Scripts MUST be prepared to + recognise both '+' and '%20' as an encoded space in a + URL-encoded value. + </P> + <P> + Note that some unsafe characters may have different semantics if + they are encoded. The definition of which characters are unsafe + depends on the context. + For example, the following two URLs do not + necessarily refer to the same resource: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + http://somehost.com/somedir%2Fvalue + http://somehost.com/somedir/value + </PRE> + <P> + See section + 2 of RFC + 2396 [<A HREF="#[4]">4</A>] + for authoritative treatment of this issue. + </P> + + <H3> + <A NAME="3.2"> + 3.2. The Script-URI + </A> + </H3> + <P> + The 'Script-URI' is defined as the URI of the resource identified + by the metavariables. Often, + this URI will be the same as + the URI requested by the client (the 'Client-URI'); however, it need + not be. Instead, it could be a URI invented by the server, and so it + can only be used in the context of the server and its CGI interface. + </P> + <P> + The Script-URI has the syntax of generic-RL as defined in section 2.1 + of RFC 1808 [<A HREF="#[7]">7</A>], with the exception that object + parameters and + fragment identifiers are not permitted: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + <scheme>://<host><port>/<path>?<query> + </PRE> + <P> + The various components of the + Script-URI + are defined by some of the + metavariables (see + <A HREF="#4.0">section 4</A> + below); + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + script-uri = protocol "://" SERVER_NAME ":" SERVER_PORT enc-script + enc-path-info "?" QUERY_STRING + </PRE> + <P> + where 'protocol' is obtained + from SERVER_PROTOCOL, 'enc-script' is a + URL-encoded version of SCRIPT_NAME and 'enc-path-info' is a + URL-encoded version of PATH_INFO. See + <A HREF="#4.6">section 4.6</A> for more information about the PATH_INFO + metavariable. + </P> + <P> + Note that the scheme and the protocol are <EM>not</EM> identical; + for instance, a resource accessed <EM>via</EM> an SSL mechanism + may have a Client-URI with a scheme of "<SAMP>https</SAMP>" + rather than "<SAMP>http</SAMP>". CGI/1.1 provides no means + for the script to reconstruct this, and therefore + the Script-URI includes the base protocol used. + </P> + + <H2> + <A NAME="4.0"> + 4. Invoking the Script + </A> + </H2> + <P> + The + script is invoked in a system defined manner. Unless specified + otherwise, the file containing the script will be invoked as an + executable program. + </P> + + <H2> + <A NAME="5.0"> + 5. The CGI Script Command Line + </A> + </H2> + <P> + Some systems support a method for supplying an array of strings to + the CGI script. This is only used in the case of an 'indexed' query. + This is identified by a "GET" or "HEAD" HTTP request with a URL + query + string not containing any unencoded "=" characters. For such a + request, + servers SHOULD parse the search string + into words, using the following rules: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + search-string = search-word *( "+" search-word ) + search-word = 1*schar + schar = xunreserved | escaped | xreserved + xunreserved = alpha | digit | xsafe | extra + xsafe = "$" | "-" | "_" | "." + xreserved = ";" | "/" | "?" | ":" | "@" | "&" + </PRE> + <P> + After parsing, each word is URL-decoded, optionally encoded in a + system defined manner, + and then the argument list is set to the list + of words. + </P> + <P> + If the server cannot create any part of the argument list, then the + server SHOULD NOT generate any command line information. For example, the + number of arguments may be greater than operating system or server + limitations permit, or one of the words may not be representable as an + argument. + </P> + <P> + Scripts SHOULD check to see if the QUERY_STRING value contains an + unencoded "=" character, and SHOULD NOT use the command line arguments + if it does. + </P> + + <H2> + <A NAME="6.0"> + 6. Data Input to the CGI Script + </A> + </H2> + <P> + Information about a request comes from two different sources: the + request header, and any associated + message-body. + Servers MUST + make portions of this information available to + scripts. + </P> + + <H3> + <A NAME="6.1"> + 6.1. Request Metadata + (Metavariables) + </A> + </H3> + <P> + Each CGI server + implementation MUST define a mechanism + to pass data about the request from + the server to the script. + The metavariables containing these + data + are accessed by the script in a system + defined manner. + The + representation of the characters in the + metavariables is + system defined. + </P> + <P> + This specification does not distinguish between the representation of + null values and missing ones. Whether null or missing values + (such as a query component of "?" or "", respectively) are represented + by undefined metavariables or by metavariables with values of "" is + implementation-defined. + </P> + <P> + Case is not significant in the + metavariable + names, in that there cannot be two + different variables + whose names differ in case only. Here they are + shown using a canonical representation of capitals plus underscore + ("_"). The actual representation of the names is system defined; for + a particular system the representation MAY be defined differently + than this. + </P> + <P> + Metavariable + values MUST be + considered case-sensitive except as noted + otherwise. + </P> + <P> + The canonical + metavariables + defined by this specification are: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + AUTH_TYPE + CONTENT_LENGTH + CONTENT_TYPE + GATEWAY_INTERFACE + PATH_INFO + PATH_TRANSLATED + QUERY_STRING + REMOTE_ADDR + REMOTE_HOST + REMOTE_IDENT + REMOTE_USER + REQUEST_METHOD + SCRIPT_NAME + SERVER_NAME + SERVER_PORT + SERVER_PROTOCOL + SERVER_SOFTWARE + </PRE> + <P> + Metavariables with names beginning with the protocol name (<EM>e.g.</EM>, + "HTTP_ACCEPT") are also canonical in their description of request header + fields. The number and meaning of these fields may change independently + of this specification. (See also <A HREF="#6.1.5">section 6.1.5</A>.) + </P> + + <H4> + <A NAME="6.1.1"> + 6.1.1. AUTH_TYPE + </A> + </H4> + <P> + This variable is specific to requests made + <EM>via</EM> the + "<CODE>http</CODE>" + scheme. + </P> + <P> + If the Script-URI + required access authentication for external + access, then the server + MUST set + the value of + this variable + from the '<SAMP>auth-scheme</SAMP>' token in + the request's "<SAMP>Authorization</SAMP>" header + field. + Otherwise + it is + set to NULL. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + AUTH_TYPE = "" | auth-scheme + auth-scheme = "Basic" | "Digest" | token + </PRE> + <P> + HTTP access authentication schemes are described in section 11 of the + HTTP/1.1 specification [<A HREF="#[8]">8</A>]. The auth-scheme is + not case-sensitive. + </P> + <P> + Servers + MUST + provide this metavariable + to scripts if the request + header included an "<SAMP>Authorization</SAMP>" field + that was authenticated. + </P> + + <H4> + <A NAME="6.1.2"> + 6.1.2. CONTENT_LENGTH + </A> + </H4> + <P> + This + metavariable + is set to the + size of the message-body + entity attached to the request, if any, in decimal + number of octets. If no data are attached, then this + metavariable + is either NULL or not + defined. The syntax is + the same as for + the HTTP "<SAMP>Content-Length</SAMP>" header field (section 14.14, HTTP/1.1 + specification [<A HREF="#[8]">8</A>]). + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + CONTENT_LENGTH = "" | 1*digit + </PRE> + <P> + Servers MUST provide this metavariable + to scripts if the request + was accompanied by a + message-body entity. + </P> + + <H4> + <A NAME="6.1.3"> + 6.1.3. CONTENT_TYPE + </A> + </H4> + <P> + If the request includes a + message-body, + CONTENT_TYPE is set + to + the Internet Media Type + [<A HREF="#[9]">9</A>] of the attached + entity if the type was provided <EM>via</EM> + a "<SAMP>Content-type</SAMP>" field in the + request header, or if the server can determine it in the absence + of a supplied "<SAMP>Content-type</SAMP>" field. The syntax is the + same as for the HTTP + "<SAMP>Content-Type</SAMP>" header field. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + CONTENT_TYPE = "" | media-type + media-type = type "/" subtype *( ";" parameter) + type = token + subtype = token + parameter = attribute "=" value + attribute = token + value = token | quoted-string + </PRE> + <P> + The type, subtype, + and parameter attribute names are not + case-sensitive. Parameter values MAY be case sensitive. + Media types and their use in HTTP are described + in section 3.7 of the + HTTP/1.1 specification [<A HREF="#[8]">8</A>]. + </P> + <P> + Example: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + application/x-www-form-urlencoded + </PRE> + <P> + There is no default value for this variable. If and only if it is + unset, then the script MAY attempt to determine the media type from + the data received. If the type remains unknown, then + the script MAY choose to either assume a + content-type of + <SAMP>application/octet-stream</SAMP> + or reject the request with a 415 ("Unsupported Media Type") + error. See <A HREF="#7.2.1.3">section 7.2.1.3</A> + for more information about returning error status values. + </P> + <P> + Servers MUST provide this metavariable + to scripts if + a "<SAMP>Content-Type</SAMP>" field was present + in the original request header. If the server receives a request + with an attached entity but no "<SAMP>Content-Type</SAMP>" + header field, it MAY attempt to + determine the correct datatype, or it MAY omit this + metavariable when + communicating the request information to the script. + </P> + + <H4> + <A NAME="6.1.4"> + 6.1.4. GATEWAY_INTERFACE + </A> + </H4> + <P> + This + metavariable + is set to + the dialect of CGI being used + by the server to communicate with the script. + Syntax: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + GATEWAY_INTERFACE = "CGI" "/" major "." minor + major = 1*digit + minor = 1*digit + </PRE> + <P> + Note that the major and minor numbers are treated as separate + integers and hence each may be + more than a single + digit. Thus CGI/2.4 is a lower version than CGI/2.13 which in turn + is lower than CGI/12.3. Leading zeros in either + the major or the minor number MUST be ignored by scripts and + SHOULD NOT be generated by servers. + </P> + <P> + This document defines the 1.1 version of the CGI interface + ("CGI/1.1"). + </P> + <P> + Servers MUST provide this metavariable + to scripts. + </P> + + <H4> + <A NAME="6.1.5"> + 6.1.5. Protocol-Specific Metavariables + </A> + </H4> + <P> + These metavariables are specific to + the protocol + <EM>via</EM> which the request is made. + Interpretation of these variables depends on the value of + the + SERVER_PROTOCOL + metavariable + (see + <A HREF="#6.1.17">section 6.1.17</A>). + </P> + <P> + Metavariables + with names beginning with "HTTP_" contain + values from the request header, if the + scheme used was HTTP. + Each + HTTP header field name is converted to upper case, has all occurrences of + "-" replaced with "_", + and has "HTTP_" prepended to form + the metavariable name. + Similar transformations are applied for other + protocols. + The header data MAY be presented as sent + by the client, or MAY be rewritten in ways which do not change its + semantics. If multiple header fields with the same field-name are received + then the server + MUST rewrite them as though they + had been received as a single header field having the same + semantics before being represented in a + metavariable. + Similarly, a header field that is received on more than one line + MUST be merged into a single line. The server MUST, if necessary, + change the representation of the data (for example, the character + set) to be appropriate for a CGI + metavariable. + <!-- ###NOTE: See if 2068 describes this thoroughly, and + point there if so. --> + </P> + <P> + Servers are + not required to create + metavariables for all + the request + header fields that they + receive. In particular, + they MAY + decline to make available any + header fields carrying authentication information, such as + "<SAMP>Authorization</SAMP>", or + which are available to the script + <EM>via</EM> other metavariables, + such as "<SAMP>Content-Length</SAMP>" and "<SAMP>Content-Type</SAMP>". + </P> + + <H4> + <A NAME="6.1.6"> + 6.1.6. PATH_INFO + </A> + </H4> + <P> + The PATH_INFO + metavariable + specifies + a path to be interpreted by the CGI script. It identifies the + resource or sub-resource to be returned + by the CGI + script, and it is derived from the portion + of the URI path following the script name but preceding + any query data. + The syntax + and semantics are similar to a decoded HTTP URL + 'path' token + (defined in + RFC 2396 + [<A HREF="#[4]">4</A>]), with the exception + that a PATH_INFO of "/" + represents a single void path segment. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + PATH_INFO = "" | ( "/" path ) + path = segment *( "/" segment ) + segment = *pchar + pchar = <any CHAR except "/"> + </PRE> + <P> + The PATH_INFO string is the trailing part of the <path> component of + the Script-URI + (see <A HREF="#3.2">section 3.2</A>) + that follows the SCRIPT_NAME + portion of the path. + </P> + <P> + Servers MAY impose their own restrictions and + limitations on what values they will accept for PATH_INFO, and MAY + reject or edit any values they + consider objectionable before passing + them to the script. + </P> + <P> + Servers MUST make this URI component available + to CGI scripts. The PATH_INFO + value is case-sensitive, and the + server MUST preserve the case of the PATH_INFO element of the URI + when making it available to scripts. + </P> + + <H4> + <A NAME="6.1.7"> + 6.1.7. PATH_TRANSLATED + </A> + </H4> + <P> + PATH_TRANSLATED is derived by taking any path-info component of the + request URI (see + <A HREF="#6.1.6">section 6.1.6</A>), decoding it + (see <A HREF="#3.1">section 3.1</A>), parsing it as a URI in its own + right, and performing any virtual-to-physical + translation appropriate to map it onto the + server's document repository structure. + If the request URI includes no path-info + component, the PATH_TRANSLATED metavariable SHOULD NOT be defined. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + PATH_TRANSLATED = *CHAR + </PRE> + <P> + For a request such as the following: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + http://somehost.com/cgi-bin/somescript/this%2eis%2epath%2einfo + </PRE> + <P> + the PATH_INFO component would be decoded, and the result + parsed as though it were a request for the following: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + http://somehost.com/this.is.the.path.info + </PRE> + <P> + This would then be translated to a + location in the server's document repository, + perhaps a filesystem path something + like this: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + /usr/local/www/htdocs/this.is.the.path.info + </PRE> + <P> + The result of the translation is the value of PATH_TRANSLATED. + </P> + <P> + The value of PATH_TRANSLATED may or may not map to a valid + repository + location. + Servers MUST preserve the case of the path-info + segment if and only if the underlying + repository + supports case-sensitive + names. If the + repository + is only case-aware, case-preserving, or case-blind + with regard to + document names, + servers are not required to preserve the + case of the original segment through the translation. + </P> + <P> + The + translation + algorithm the server uses to derive PATH_TRANSLATED is + implementation defined; CGI scripts which use this variable may + suffer limited portability. + </P> + <P> + Servers SHOULD provide this metavariable + to scripts if and only if the request URI includes a + path-info component. + </P> + + <H4> + <A NAME="6.1.8"> + 6.1.8. QUERY_STRING + </A> + </H4> + <P> + A URL-encoded + string; the <query> part of the + Script-URI. + (See + <A HREF="#3.2">section 3.2</A>.) + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + QUERY_STRING = query-string + query-string = *uric + </PRE> + <P> + The URL syntax for a query + string is described in + section 3 of + RFC 2396 + [<A HREF="#[4]">4</A>]. + </P> + <P> + Servers MUST supply this value to scripts. + The QUERY_STRING value is case-sensitive. + If the Script-URI does not include a query component, + the QUERY_STRING metavariable MUST be defined as an empty string (""). + </P> + + <H4> + <A NAME="6.1.9"> + 6.1.9. REMOTE_ADDR + </A> + </H4> + <P> + The IP address of the client + sending the request to the server. This + is not necessarily that of the user + agent + (such as if the request came through a proxy). + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + REMOTE_ADDR = hostnumber + hostnumber = ipv4-address | ipv6-address + </PRE> + <P> + The definitions of <SAMP>ipv4-address</SAMP> and <SAMP>ipv6-address</SAMP> + are provided in Appendix B of RFC 2373 [<A HREF="#[13]">13</A>]. + </P> + <P> + Servers MUST supply this value to scripts. + </P> + + <H4> + <A NAME="6.1.10"> + 6.1.10. REMOTE_HOST + </A> + </H4> + <P> + The fully qualified domain name of the + client sending the request to + the server, if available, otherwise NULL. + (See <A HREF="#6.1.9">section 6.1.9</A>.) + Fully qualified domain names take the form as described in + section 3.5 of RFC 1034 [<A HREF="#[10]">10</A>] and section 2.1 of + RFC 1123 [<A HREF="#[5]">5</A>]. Domain names are not case sensitive. + </P> + <P> + Servers SHOULD provide this information to + scripts. + </P> + + <H4> + <A NAME="6.1.11"> + 6.1.11. REMOTE_IDENT + </A> + </H4> + <P> + The identity information reported about the connection by a + RFC 1413 [<A HREF="#[11]">11</A>] request to the remote agent, if + available. Servers + MAY choose not + to support this feature, or not to request the data + for efficiency reasons. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + REMOTE_IDENT = *CHAR + </PRE> + <P> + The data returned + may be used for authentication purposes, but the level + of trust reposed in them should be minimal. + </P> + <P> + Servers MAY supply this information to scripts if the + RFC1413 [<A HREF="#[11]">11</A>] lookup is performed. + </P> + + <H4> + <A NAME="6.1.12"> + 6.1.12. REMOTE_USER + </A> + </H4> + <P> + If the request required authentication using the "Basic" + mechanism (<EM>i.e.</EM>, the AUTH_TYPE + metavariable is set + to "Basic"), then the value of the REMOTE_USER + metavariable is set to the + user-ID supplied. In all other cases + the value of this metavariable + is undefined. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + REMOTE_USER = *OCTET + </PRE> + <P> + This variable is specific to requests made <EM>via</EM> the + HTTP protocol. + </P> + <P> + Servers SHOULD provide this metavariable + to scripts. + </P> + + <H4> + <A NAME="6.1.13"> + 6.1.13. REQUEST_METHOD + </A> + </H4> + <P> + The REQUEST_METHOD + metavariable + is set to the + method with which the request was made, as described in section + 5.1.1 of the HTTP/1.0 specification [<A HREF="#[3]">3</A>] and + section 5.1.1 of the + HTTP/1.1 specification [<A HREF="#[8]">8</A>]. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + REQUEST_METHOD = http-method + http-method = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" + | "OPTIONS" | "TRACE" | extension-method + extension-method = token + </PRE> + <P> + The method is case sensitive. + CGI/1.1 servers MAY choose to process some methods + directly rather than passing them to scripts. + </P> + <P> + This variable is specific to requests made with HTTP. + </P> + <P> + Servers MUST provide this metavariable + to scripts. + </P> + + <H4> + <A NAME="6.1.14"> + 6.1.14. SCRIPT_NAME + </A> + </H4> + <P> + The SCRIPT_NAME + metavariable + is + set to a URL path that could identify the CGI script (rather than the + script's + output). The syntax and semantics are identical to a + decoded HTTP URL 'path' token + (see RFC 2396 + [<A HREF="#[4]">4</A>]). + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + SCRIPT_NAME = "" | ( "/" [ path ] ) + </PRE> + <P> + The SCRIPT_NAME string is some leading part of the <path> component + of the Script-URI derived in some + implementation defined manner. + No PATH_INFO or QUERY_STRING segments + (see sections <A HREF="#6.1.6">6.1.6</A> and + <A HREF="#6.1.8">6.1.8</A>) are included + in the SCRIPT_NAME value. + </P> + <P> + Servers MUST provide this metavariable + to scripts. + </P> + + <H4> + <A NAME="6.1.15"> + 6.1.15. SERVER_NAME + </A> + </H4> + <P> + The SERVER_NAME + metavariable + is set to the + name of the + server, as + derived from the <host> part of the + Script-URI + (see <A HREF="#3.2">section 3.2</A>). + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + SERVER_NAME = hostname | hostnumber + </PRE> + <P> + Servers MUST provide this metavariable + to scripts. + </P> + + <H4> + <A NAME="6.1.16"> + 6.1.16. SERVER_PORT + </A> + </H4> + <P> + The SERVER_PORT + metavariable + is set to the + port on which the + request was received, as used in the <port> + part of the Script-URI. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + SERVER_PORT = 1*digit + </PRE> + <P> + If the <port> portion of the script-URI is blank, the actual + port number upon which the request was received MUST be supplied. + </P> + <P> + Servers MUST provide this metavariable + to scripts. + </P> + + <H4> + <A NAME="6.1.17"> + 6.1.17. SERVER_PROTOCOL + </A> + </H4> + <P> + The SERVER_PROTOCOL + metavariable + is set to + the + name and revision of the information protocol with which + the + request + arrived. This is not necessarily the same as the protocol version used by + the server in its response to the client. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + SERVER_PROTOCOL = HTTP-Version | extension-version + | extension-token + HTTP-Version = "HTTP" "/" 1*digit "." 1*digit + extension-version = protocol "/" 1*digit "." 1*digit + protocol = 1*( alpha | digit | "+" | "-" | "." ) + extension-token = token + </PRE> + <P> + 'protocol' is a version of the <scheme> part of the + Script-URI, but is + not identical to it. For example, the scheme of a request may be + "<SAMP>https</SAMP>" while the protocol remains "<SAMP>http</SAMP>". + The protocol is not case sensitive, but + by convention, 'protocol' is in + upper case. + </P> + <P> + A well-known extension token value is "INCLUDED", + which signals that the current document is being included as part of + a composite document, rather than being the direct target of the + client request. + </P> + <P> + Servers MUST provide this metavariable + to scripts. + </P> + + <H4> + <A NAME="6.1.18"> + 6.1.18. SERVER_SOFTWARE + </A> + </H4> + <P> + The SERVER_SOFTWARE + metavariable + is set to the + name and version of the information server software answering the + request (and running the gateway). + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + SERVER_SOFTWARE = 1*product + product = token [ "/" product-version ] + product-version = token + </PRE> + <P> + Servers MUST provide this metavariable + to scripts. + </P> + + <H3> + <A NAME="6.2"> + 6.2. Request Message-Bodies + </A> + </H3> + <P> + As there may be a data entity attached to the request, there MUST be + a system defined method for the script to read + these data. Unless + defined otherwise, this will be <EM>via</EM> the 'standard input' file + descriptor. + </P> + <P> + If the CONTENT_LENGTH value (see <A HREF="#6.1.2">section 6.1.2</A>) + is non-NULL, the server MUST supply at least that many bytes to + scripts on the standard input stream. + Scripts are + not obliged to read the data. + Servers MAY signal an EOF condition after CONTENT_LENGTH bytes have been + read, but are + not obligated to do so. Therefore, scripts + MUST NOT + attempt to read more than CONTENT_LENGTH bytes, even if more data + are available. + </P> + <P> + For non-parsed header (NPH) scripts (see + <A HREF="#7.1">section 7.1</A> + below), + servers SHOULD + attempt to ensure that the data + supplied to the script are precisely + as supplied by the client and unaltered by + the server. + </P> + <P> + <A HREF="#8.1.2">Section 8.1.2</A> describes the requirements of + servers with regard to requests that include + message-bodies. + </P> + + <H2> + <A NAME="7.0"> + 7. Data Output from the CGI Script + </A> + </H2> + <P> + There MUST be a system defined method for the script to send data + back to the server or client; a script MUST always return some data. + Unless defined otherwise, this will be <EM>via</EM> the 'standard + output' file descriptor. + </P> + <P> + There are two forms of output that scripts can supply to servers: non-parsed + header (NPH) output, and parsed header output. + Servers MUST support parsed header + output and MAY support NPH output. The method of + distinguishing between the two + types of output (or scripts) is implementation defined. + </P> + <P> + Servers MAY implement a timeout period within which data must be + received from scripts. If a server implementation defines such + a timeout and receives no data from a script within the timeout + period, the server MAY terminate the script process and SHOULD + abort the client request with + either a + '504 Gateway Timed Out' or a + '500 Internal Server Error' response. + </P> + + <H3> + <A NAME="7.1"> + 7.1. Non-Parsed Header Output + </A> + </H3> + <P> + Scripts using the NPH output form + MUST return a complete HTTP response message, as described + in Section 6 of the HTTP specifications + [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>]. + NPH scripts + MUST use the SERVER_PROTOCOL variable to determine the appropriate format + for a response. + </P> + <P> + Servers + SHOULD attempt to ensure that the script output is sent + directly to the client, with minimal + internal and no transport-visible + buffering. + </P> + + <H3> + <A NAME="7.2"> + 7.2. Parsed Header Output + </A> + </H3> + <P> + Scripts using the parsed header output form MUST supply + a CGI response message to the server + as follows: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + CGI-Response = *optional-field CGI-Field *optional-field NL [ Message-Body ] + optional-field = ( CGI-Field | HTTP-Field ) + CGI-Field = Content-type + | Location + | Status + | extension-header + </PRE> + <P><!-- ##### If HTTP defines x-headers, remove ours except x-cgi- --> + The response comprises a header and a body, separated by a blank line. + The body may be NULL. + The header fields are either CGI header fields to be interpreted by + the server, or HTTP header fields + to be included in the response returned + to the client + if the request method is HTTP. At least one + CGI-Field MUST be + supplied, but no CGI field name may be used more than once + in a response. + If a body is supplied, then a "<SAMP>Content-type</SAMP>" + header field MUST be + supplied by the script, + otherwise the script MUST send a "<SAMP>Location</SAMP>" + or "<SAMP>Status</SAMP>" header field. If a + <SAMP>Location</SAMP> CGI-Field + is returned, then the script MUST NOT supply + any HTTP-Fields. + </P> + <P> + Each header field in a CGI-Response MUST be specified on a single line; + CGI/1.1 does not support continuation lines. + </P> + + <H4> + <A NAME="7.2.1"> + 7.2.1. CGI header fields + </A> + </H4> + <P> + The CGI header fields have the generic syntax: + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + generic-field = field-name ":" [ field-value ] NL + field-name = token + field-value = *( field-content | LWSP ) + field-content = *( token | tspecial | quoted-string ) + </PRE> + <P> + The field-name is not case sensitive; a NULL field value is + equivalent to the header field not being sent. + </P> + + <H4> + <A NAME="7.2.1.1"> + 7.2.1.1. Content-Type + </A> + </H4> + <P> + The Internet Media Type [<A HREF="#[9]">9</A>] of the entity + body, which is to be sent unmodified to the client. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + Content-Type = "Content-Type" ":" media-type NL + </PRE> + <P> + This is actually an HTTP-Field + rather than a CGI-Field, but + it is listed here because of its importance in the CGI dialogue as + a member of the "one of these is required" set of header + fields. + </P> + + <H4> + <A NAME="7.2.1.2"> + 7.2.1.2. Location + </A> + </H4> + <P> + This is used to specify to the server that the script is returning a + reference to a document rather than an actual document. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + Location = "Location" ":" + ( fragment-URI | rel-URL-abs-path ) NL + fragment-URI = URI [ # fragmentid ] + URI = scheme ":" *qchar + fragmentid = *qchar + rel-URL-abs-path = "/" [ hpath ] [ "?" query-string ] + hpath = fpsegment *( "/" psegment ) + fpsegment = 1*hchar + psegment = *hchar + hchar = alpha | digit | safe | extra + | ":" | "@" | "& | "=" + </PRE> + <P> + The Location + value is either an absolute URI with optional fragment, + as defined in RFC 1630 [<A HREF="#[1]">1</A>], or an absolute path + within the server's URI space (<EM>i.e.</EM>, + omitting the scheme and network-related fields) and optional + query-string. If an absolute URI is returned by the script, + then the + server MUST generate a + '302 redirect' HTTP response + message unless the script has supplied an + explicit Status response header field. + Scripts returning an absolute URI MAY choose to + provide a message-body. Servers MUST make any appropriate modifications + to the script's output to ensure the response to the user-agent complies + with the response protocol version. + If the Location value is a path, then the server + MUST generate + the response that it would have produced in response to a request + containing the URL + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + scheme "://" SERVER_NAME ":" SERVER_PORT rel-URL-abs-path + </PRE> + <P> + Note: If the request was accompanied by a + message-body + (such as for a POST request), and the script + redirects the request with a Location field, the + message-body + may not be + available to the resource that is the target of the redirect. + </P> + + <H4> + <A NAME="7.2.1.3"> + 7.2.1.3. Status + </A> + </H4> + <P> + The "<SAMP>Status</SAMP>" header field is used to indicate to the server what + status code the server MUST use in the response message. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + Status = "Status" ":" digit digit digit SP reason-phrase NL + reason-phrase = *<CHAR, excluding CTLs, NL> + </PRE> + <P> + The valid status codes are listed in section 6.1.1 of the HTTP/1.0 + specifications [<A HREF="#[3]">3</A>]. If the SERVER_PROTOCOL is + "HTTP/1.1", then the status codes defined in the HTTP/1.1 + specification [<A HREF="#[8]">8</A>] may + be used. If the script does not return a "<SAMP>Status</SAMP>" header + field, then "200 OK" SHOULD be assumed by the server. + </P> + <P> + If a script is being used to handle a particular error or condition + encountered by the server, such as a '404 Not Found' error, the script + SHOULD use the "<SAMP>Status</SAMP>" CGI header field to propagate the error + condition back to the client. <EM>E.g.</EM>, in the example mentioned it + SHOULD include a "Status: 404 Not Found" in the + header data returned to the server. + </P> + + <H4> + <A NAME="7.2.1.4"> + 7.2.1.4. Extension header fields + </A> + </H4> + <P> + Scripts MAY include in their CGI response header additional fields + not defined in this or the HTTP specification. + These are called "extension" fields, + and have the syntax of a <SAMP>generic-field</SAMP> as defined in + <A HREF="#7.2.1">section 7.2.1</A>. The name of an extension field + MUST NOT conflict with a field name defined in this or any other + specification; extension field names SHOULD begin with "X-CGI-" + to ensure uniqueness. + </P> + + <H4> + <A NAME="7.2.2"> + 7.2.2. HTTP header fields + </A> + </H4> + <P> + The script MAY return any other header fields defined by the + specification + for the SERVER_PROTOCOL (HTTP/1.0 [<A HREF="#[3]">3</A>] or HTTP/1.1 + [<A HREF="#[8]">8</A>]). + Servers MUST resolve conflicts beteen CGI header + and HTTP header formats or names (see <A HREF="#8.0">section 8</A>). + </P> + + <H2> + <A NAME="8.0"> + 8. Server Implementation + </A> + </H2> + <P> + This section defines the requirements that must be met by HTTP + servers in order to provide a coherent and correct CGI/1.1 + environment in which scripts may function. It is intended + primarily for server implementors, but it is useful for + script authors to be familiar with the information as well. + </P> + + <H3> + <A NAME="8.1"> + 8.1. Requirements for Servers + </A> + </H3> + <P> + In order to be considered CGI/1.1-compliant, a server must meet + certain basic criteria and provide certain minimal functionality. + The details of these requirements are described in the following sections. + </P> + + <H3> + <A NAME="8.1.1"> + 8.1.1. Script-URI + </A> + </H3> + <P> + Servers MUST support the standard mechanism (described below) which + allows + script authors to determine + what URL to use in documents + which reference the script; + specifically, what URL to use in order to + achieve particular settings of the + metavariables. This + mechanism is as follows: + </P> + <P> + The server + MUST translate the header data from the CGI header field syntax to + the HTTP + header field syntax if these differ. For example, the character + sequence for + newline (such as Unix's ASCII NL) used by CGI scripts may not be the + same as that used by HTTP (ASCII CR followed by LF). The server MUST + also resolve any conflicts between header fields returned by the script + and header fields that it would otherwise send itself. + </P> + + <H3> + <A NAME="8.1.2"> + 8.1.2. Request Message-body Handling + </A> + </H3> + <P> + These are the requirements for server handling of message-bodies directed + to CGI/1.1 resources: + </P> + <OL> + <LI>The message-body the server provides to the CGI script MUST + have any transfer encodings removed. + </LI> + <LI>The server MUST derive and provide a value for the CONTENT_LENGTH + metavariable that reflects the length of the message-body after any + transfer decoding. + </LI> + <LI>The server MUST leave intact any content-encodings of the message-body. + </LI> + </OL> + + <H3> + <A NAME="8.1.3"> + 8.1.3. Required Metavariables + </A> + </H3> + <P> + Servers MUST provide scripts with certain information and + metavariables + as described in <A HREF="#8.3">section 8.3</A>. + </P> + + <H3> + <A NAME="8.1.4"> + 8.1.4. Response Compliance + </A> + </H3> + <P> + Servers MUST ensure that responses sent to the user-agent meet all + requirements of the protocol level in effect. This may involve + modifying, deleting, or augmenting any header + fields and/or message-body supplied by the script. + </P> + + <H3> + <A NAME="8.2"> + 8.2. Recommendations for Servers + </A> + </H3> + <P> + Servers SHOULD provide the "<SAMP>query</SAMP>" component of the script-URI + as command-line arguments to scripts if it does not + contain any unencoded '=' characters and the command-line arguments can + be generated in an unambiguous manner. + (See <A HREF="#5.0">section 5</A>.) + </P> + <P> + Servers SHOULD set the AUTH_TYPE + metavariable to the value of the + '<SAMP>auth-scheme</SAMP>' token of the "<SAMP>Authorization</SAMP>" + field if it was supplied as part of the request header. + (See <A HREF="#6.1.1">section 6.1.1</A>.) + </P> + <P> + Where applicable, servers SHOULD set the current working directory + to the directory in which the script is located before invoking + it. + </P> + <P> + Servers MAY reject with error '404 Not Found' + any requests that would result in + an encoded "/" being decoded into PATH_INFO or SCRIPT_NAME, as this + might represent a loss of information to the script. + </P> + <P> + Although the server and the CGI script need not be consistent in + their handling of URL paths (client URLs and the PATH_INFO data, + respectively), server authors may wish to impose consistency. + So the server implementation SHOULD define its behaviour for the + following cases: + </P> + <OL> + <LI>define any restrictions on allowed characters, in particular + whether ASCII NUL is permitted; + </LI> + <LI>define any restrictions on allowed path segments, in particular + whether non-terminal NULL segments are permitted; + </LI> + <LI>define the behaviour for <SAMP>"."</SAMP> or <SAMP>".."</SAMP> path + segments; <EM>i.e.</EM>, whether they are prohibited, treated as + ordinary path + segments or interpreted in accordance with the relative URL + specification [<A HREF="#[7]">7</A>]; + </LI> + <LI>define any limits of the implementation, including limits on path or + search string lengths, and limits on the volume of header data the server + will parse. + </LI><!-- ##### Move the field resolution/translation para below here --> + </OL> + <P> + Servers MAY generate the + Script-URI in + any way from the client URI, + or from any other data (but the behaviour SHOULD be documented). + </P> + <P> + For non-parsed header (NPH) scripts (see + <A HREF="#7.1">section 7.1</A>), servers SHOULD + attempt to ensure that the script input comes directly from the + client, with minimal buffering. For all scripts the data will be + as supplied by the client. + </P> + + <H3> + <A NAME="8.3"> + 8.3. Summary of + MetaVariables + </A> + </H3> + <P> + Servers MUST provide the following + metavariables to + scripts. See the individual descriptions for exceptions and semantics. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + CONTENT_LENGTH (section <A HREF="#6.1.2">6.1.2</A>) + CONTENT_TYPE (section <A HREF="#6.1.3">6.1.3</A>) + GATEWAY_INTERFACE (section <A HREF="#6.1.4">6.1.4</A>) + PATH_INFO (section <A HREF="#6.1.6">6.1.6</A>) + QUERY_STRING (section <A HREF="#6.1.8">6.1.8</A>) + REMOTE_ADDR (section <A HREF="#6.1.9">6.1.9</A>) + REQUEST_METHOD (section <A HREF="#6.1.13">6.1.13</A>) + SCRIPT_NAME (section <A HREF="#6.1.14">6.1.14</A>) + SERVER_NAME (section <A HREF="#6.1.15">6.1.15</A>) + SERVER_PORT (section <A HREF="#6.1.16">6.1.16</A>) + SERVER_PROTOCOL (section <A HREF="#6.1.17">6.1.17</A>) + SERVER_SOFTWARE (section <A HREF="#6.1.18">6.1.18</A>) + </PRE> + <P> + Servers SHOULD define the following + metavariables for scripts. + See the individual descriptions for exceptions and semantics. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + AUTH_TYPE (section <A HREF="#6.1.1">6.1.1</A>) + REMOTE_HOST (section <A HREF="#6.1.10">6.1.10</A>) + </PRE> + <P> + In addition, servers SHOULD provide + metavariables for all fields present + in the HTTP request header, with the exception of those involved with + access control. Servers MAY at their discretion provide + metavariables + for access control fields. + </P> + <P> + Servers MAY define the following + metavariables. See the individual + descriptions for exceptions and semantics. + </P><!--#if expr="! $GUI" --> + <P></P><!--#endif --> + <PRE> + PATH_TRANSLATED (section <A HREF="#6.1.7">6.1.7</A>) + REMOTE_IDENT (section <A HREF="#6.1.11">6.1.11</A>) + REMOTE_USER (section <A HREF="#6.1.12">6.1.12</A>) + </PRE> + <P> + Servers MAY + at their discretion define additional implementation-specific + extension metavariables + provided their names do not + conflict with defined header field names. Implementation-specific + metavariable names SHOULD + be prefixed with "X_" (<EM>e.g.</EM>, + "X_DBA") to avoid the potential for such conflicts. + </P> + + <H2> + <A NAME="9.0"> + 9. + Script Implementation + </A> + </H2> + <P> + This section defines the requirements and recommendations for scripts + that are intended to function in a CGI/1.1 environment. It is intended + primarily as a reference for script authors, but server implementors + should be familiar with these issues as well. + </P> + + <H3> + <A NAME="9.1"> + 9.1. Requirements for Scripts + </A> + </H3> + <P> + Scripts using the parsed-header method to communicate with servers + MUST supply a response header to the server. + (See <A HREF="#7.0">section 7</A>.) + </P> + <P> + Scripts using the NPH method to communicate with servers MUST + provide complete HTTP responses, and MUST use the value of the + SERVER_PROTOCOL metavariable + to determine the appropriate format. + (See <A HREF="#7.1">section 7.1</A>.) + </P> + <P> + Scripts MUST check the value of the REQUEST_METHOD + metavariable in order + to provide an appropriate response. + (See <A HREF="#6.1.13">section 6.1.13</A>.) + </P> + <P> + Scripts MUST be prepared to handled URL-encoded values in + metavariables. + In addition, they MUST recognise both "+" and "%20" in URL-encoded + quantities as representing the space character. + (See <A HREF="#3.1">section 3.1</A>.) + </P> + <P> + Scripts MUST ignore leading zeros in the major and minor version numbers + in the GATEWAY_INTERFACE + metavariable value. (See + <A HREF="#6.1.4">section 6.1.4</A>.) + </P> + <P> + When processing requests that include a + message-body, scripts + MUST NOT read more than CONTENT_LENGTH bytes from the input stream. + (See sections <A HREF="#6.1.2">6.1.2</A> and <A HREF="#6.2">6.2</A>.) + </P> + + <H3> + <A NAME="9.2"> + 9.2. Recommendations for Scripts + </A> + </H3> + <P> + Servers may interrupt or terminate script execution at any time + and without warning, so scripts SHOULD be prepared to deal with + abnormal termination. + </P> + <P> + Scripts MUST + reject with + error '405 Method Not + Allowed' requests + made using methods that they do not support. If the script does + not intend + processing the PATH_INFO data, then it SHOULD reject the request with + '404 Not + Found' if PATH_INFO is not NULL. + </P> + <P> + If a script is processing the output of a form, it SHOULD + verify that the CONTENT_TYPE + is "<SAMP>application/x-www-form-urlencoded</SAMP>" [<A HREF="#[2]">2</A>] + or whatever other media type is expected. + </P> + <P> + Scripts parsing PATH_INFO, + PATH_TRANSLATED, or SCRIPT_NAME + SHOULD be careful + of void path segments ("<SAMP>//</SAMP>") and special path segments + (<SAMP>"."</SAMP> and + <SAMP>".."</SAMP>). They SHOULD either be removed from the path before + use in OS + system calls, or the request SHOULD be rejected with + '404 Not Found'. + </P> + <P> + As it is impossible for + scripts to determine the client URI that + initiated a + request without knowledge of the specific server in + use, the script SHOULD NOT return "<SAMP>text/html</SAMP>" + documents containing + relative URL links without including a "<SAMP><BASE></SAMP>" + tag in the document. + </P> + <P> + When returning header fields, + scripts SHOULD try to send the CGI + header fields (see section + <A HREF="#7.2">7.2</A>) as soon as possible, and + SHOULD send them + before any HTTP header fields. This may + help reduce the server's memory requirements. + </P> + + <H2> + <A NAME="10.0"> + 10. System Specifications + </A> + </H2> + + <H3> + <A NAME="10.1"> + 10.1. AmigaDOS + </A> + </H3> + <P> + The implementation of the CGI on an AmigaDOS operating system platform + SHOULD use environment variables as the mechanism of providing + request metadata to CGI scripts. + </P> + <DL> + <DT><STRONG>Environment variables</STRONG> + </DT> + <DD> + <P> + These are accessed by the DOS library routine <SAMP>GetVar</SAMP>. The + flags argument SHOULD be 0. Case is ignored, but upper case is + recommended for compatibility with case-sensitive systems. + </P> + </DD> + <DT><STRONG>The current working directory</STRONG> + </DT> + <DD> + <P> + The current working directory for the script is set to the directory + containing the script. + </P> + </DD> + <DT><STRONG>Character set</STRONG> + </DT> + <DD> + <P> + The US-ASCII character set is used for the definition of environment + variable names and header + field names; the newline (NL) sequence is LF; + servers SHOULD also accept CR LF as a newline. + </P> + </DD> + </DL> + + <H3> + <A NAME="10.2"> + 10.2. Unix + </A> + </H3> + <P> + The implementation of the CGI on a UNIX operating system platform + SHOULD use environment variables as the mechanism of providing + request metadata to CGI scripts. + </P> + <P> + For Unix compatible operating systems, the following are defined: + </P> + <DL> + <DT><STRONG>Environment variables</STRONG> + </DT> + <DD> + <P> + These are accessed by the C library routine <SAMP>getenv</SAMP>. + </P> + </DD> + <DT><STRONG>The command line</STRONG> + </DT> + <DD> + <P> + This is accessed using the + <SAMP>argc</SAMP> and <SAMP>argv</SAMP> + arguments to <SAMP>main()</SAMP>. The words have any characters + that + are 'active' in the Bourne shell escaped with a backslash. + If the value of the QUERY_STRING + metavariable + contains an unencoded equals-sign '=', then the command line + SHOULD NOT be used by the script. + </P> + </DD> + <DT><STRONG>The current working directory</STRONG> + </DT> + <DD> + <P> + The current working directory for the script + SHOULD be set to the directory + containing the script. + </P> + </DD> + <DT><STRONG>Character set</STRONG> + </DT> + <DD> + <P> + The US-ASCII character set is used for the definition of environment + variable names and header field names; the newline (NL) sequence is LF; + servers SHOULD also accept CR LF as a newline. + </P> + </DD> + </DL> + + <H2> + <A NAME="11.0"> + 11. Security Considerations + </A> + </H2> + + <H3> + <A NAME="11.1"> + 11.1. Safe Methods + </A> + </H3> + <P> + As discussed in the security considerations of the HTTP + specifications [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>], the + convention has been established that the + GET and HEAD methods should be 'safe'; they should cause no + side-effects and only have the significance of resource retrieval. + </P> + <P> + CGI scripts are responsible for enforcing any HTTP security considerations + [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>] + with respect to the protocol version level of the request and + any side effects generated by the scripts on behalf of + the server. Primary + among these + are the considerations of safe and idempotent methods. Idempotent + requests are those that may be repeated an arbitrary number of times + and produce side effects identical to a single request. + </P> + + <H3> + <A NAME="11.2"> + 11.2. HTTP Header + Fields Containing Sensitive Information + </A> + </H3> + <P> + Some HTTP header fields may carry sensitive information which the server + SHOULD NOT pass on to the script unless explicitly configured to do + so. For example, if the server protects the script using the + "<SAMP>Basic</SAMP>" + authentication scheme, then the client will send an + "<SAMP>Authorization</SAMP>" + header field containing a username and password. If the server, rather + than the script, validates this information then the password SHOULD + NOT be passed on to the script <EM>via</EM> the HTTP_AUTHORIZATION + metavariable + without careful consideration. + This also applies to the + Proxy-Authorization header field and the corresponding + HTTP_PROXY_AUTHORIZATION + metavariable. + </P> + + <H3> + <A NAME="11.3"> + 11.3. Script + Interference with the Server + </A> + </H3> + <P> + The most common implementation of CGI invokes the script as a child + process using the same user and group as the server process. It + SHOULD therefore be ensured that the script cannot interfere with the + server process, its configuration, or documents. + </P> + <P> + If the script is executed by calling a function linked in to the + server software (either at compile-time or run-time) then precautions + SHOULD be taken to protect the core memory of the server, or to + ensure that untrusted code cannot be executed. + </P> + + <H3> + <A NAME="11.4"> + 11.4. Data Length and Buffering Considerations + </A> + </H3> + <P> + This specification places no limits on the length of message-bodies + presented to the script. Scripts should not assume that statically + allocated buffers of any size are sufficient to contain the entire + submission at one time. Use of a fixed length buffer without careful + overflow checking may result in an attacker exploiting 'stack-smashing' + or 'stack-overflow' vulnerabilities of the operating system. + Scripts may spool large submissions to disk or other buffering media, + but a rapid succession of large submissions may result in denial of + service conditions. If the CONTENT_LENGTH of a message-body is larger + than resource considerations allow, scripts should respond with an + error status appropriate for the protocol version; potentially applicable + status codes include '503 Service Unavailable' (HTTP/1.0 and HTTP/1.1), + '413 Request Entity Too Large' (HTTP/1.1), and + '414 Request-URI Too Long' (HTTP/1.1). + </P> + + <H3> + <A NAME="11.5"> + 11.5. Stateless Processing + </A> + </H3> + <P> + The stateless nature of the Web makes each script execution and resource + retrieval independent of all others even when multiple requests constitute a + single conceptual Web transaction. Because of this, a script should not + make any assumptions about the context of the user-agent submitting a + request. In particular, scripts should examine data obtained from the client + and verify that they are valid, both in form and content, before allowing + them to be used for sensitive purposes such as input to other + applications, commands, or operating system services. These uses + include, but are not + limited to: system call arguments, database writes, dynamically evaluated + source code, and input to billing or other secure processes. It is important + that applications be protected from invalid input regardless of whether + the invalidity is the result of user error, logic error, or malicious action. + </P> + <P> + Authors of scripts involved in multi-request transactions should be + particularly cautios about validating the state information; + undesirable effects may result from the substitution of dangerous + values for portions of the submission which might otherwise be + presumed safe. Subversion of this type occurs when alterations + are made to data from a prior stage of the transaction that were + not meant to be controlled by the client (<EM>e.g.</EM>, hidden + HTML form elements, cookies, embedded URLs, <EM>etc.</EM>). + </P> + + <H2> + <A NAME="12.0"> + 12. Acknowledgements + </A> + </H2> + <P> + This work is based on a draft published in 1997 by David R. Robinson, + which in turn was based on the original CGI interface that arose out of + discussions on the <EM>www-talk</EM> mailing list. In particular, + Rob McCool, John Franks, Ari Luotonen, + George Phillips and + Tony Sanders deserve special recognition for their efforts in + defining and implementing the early versions of this interface. + </P> + <P> + This document has also greatly benefited from the comments and + suggestions made by Chris Adie, Dave Kristol, + Mike Meyer, David Morris, Jeremy Madea, + Patrick M<SUP>c</SUP>Manus, Adam Donahue, + Ross Patterson, and Harald Alvestrand. + </P> + + <H2> + <A NAME="13.0"> + 13. References + </A> + </H2> + <DL COMPACT> + <DT><A NAME="[1]">[1]</A> + </DT> + <DD>Berners-Lee, T., 'Universal Resource Identifiers in WWW: A + Unifying Syntax for the Expression of Names and Addresses of + Objects on the Network as used in the World-Wide Web', RFC 1630, + CERN, June 1994. + <P> + </P> + </DD> + <DT><A NAME="[2]">[2]</A> + </DT> + <DD>Berners-Lee, T. and Connolly, D., 'Hypertext Markup Language - + 2.0', RFC 1866, MIT/W3C, November 1995. + <P> + </P> + </DD> + <DT><A NAME="[3]">[3]</A> + </DT> + <DD>Berners-Lee, T., Fielding, R. T. and Frystyk, H., + 'Hypertext Transfer Protocol -- HTTP/1.0', RFC 1945, MIT/LCS, + UC Irvine, May 1996. + <P> + </P> + </DD> + + <DT><A NAME="[4]">[4]</A> + </DT> + <DD>Berners-Lee, T., Fielding, R., and Masinter, L., Editors, + 'Uniform Resource Identifiers (URI): Generic Syntax', RFC 2396, + MIT, U.C. Irvine, Xerox Corporation, August 1996. + <P> + </P> + </DD> + + <DT><A NAME="[5]">[5]</A> + </DT> + <DD>Braden, R., Editor, 'Requirements for Internet Hosts -- + Application and Support', STD 3, RFC 1123, IETF, October 1989. + <P> + </P> + </DD> + <DT><A NAME="[6]">[6]</A> + </DT> + <DD>Crocker, D.H., 'Standard for the Format of ARPA Internet Text + Messages', STD 11, RFC 822, University of Delaware, August 1982. + <P> + </P> + </DD> + <DT><A NAME="[7]">[7]</A> + </DT> + <DD>Fielding, R., 'Relative Uniform Resource Locators', RFC 1808, + UC Irvine, June 1995. + <P> + </P> + </DD> + <DT><A NAME="[8]">[8]</A> + </DT> + <DD>Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and + Berners-Lee, T., 'Hypertext Transfer Protocol -- HTTP/1.1', + RFC 2068, UC Irvine, DEC, + MIT/LCS, January 1997. + <P> + </P> + </DD> + <DT><A NAME="[9]">[9]</A> + </DT> + <DD>Freed, N. and Borenstein N., 'Multipurpose Internet Mail + Extensions (MIME) Part Two: Media Types', RFC 2046, Innosoft, + First Virtual, November 1996. + <P> + </P> + </DD> + <DT><A NAME="[10]">[10]</A> + </DT> + <DD>Mockapetris, P., 'Domain Names - Concepts and Facilities', + STD 13, RFC 1034, ISI, November 1987. + <P> + </P> + </DD> + <DT><A NAME="[11]">[11]</A> + </DT> + <DD>St. Johns, M., 'Identification Protocol', RFC 1431, US + Department of Defense, February 1993. + <P> + </P> + </DD> + <DT><A NAME="[12]">[12]</A> + </DT> + <DD>'Coded Character Set -- 7-bit American Standard Code for + Information Interchange', ANSI X3.4-1986. + <P> + </P> + </DD> + <DT><A NAME="[13]">[13]</A> + </DT> + <DD>Hinden, R. and Deering, S., + 'IP Version 6 Addressing Architecture', RFC 2373, + Nokia, Cisco Systems, + July 1998. + <P> + </P> + </DD> + </DL> + + <H2> + <A NAME="14.0"> + 14. Authors' Addresses + </A> + </H2> + <ADDRESS> + <P> + Ken A L Coar + <BR> + MeepZor Consulting + <BR> + 7824 Mayfaire Crest Lane, Suite 202 + <BR> + Raleigh, NC 27615-4875 + <BR> + U.S.A. + </P> + <P> + Tel: +1 (919) 254.4237 + <BR> + Fax: +1 (919) 254.5250 + <BR> + Email: + <A + HREF="mailto:Ken.Coar@Golux.Com" + ><SAMP>Ken.Coar@Golux.Com</SAMP></A> + </P> + </ADDRESS> + <ADDRESS> + <P> + David Robinson + <BR> + E*TRADE UK Ltd + <BR> + Mount Pleasant House + <BR> + 2 Mount Pleasant + <BR> + Huntingdon Road + <BR> + Cambridge CB3 0RN + <BR> + UK + </P> + <P> + Tel: +44 (1223) 566926 + <BR> + Fax: +44 (1223) 506288 + <BR> + Email: + <A + HREF="mailto:drtr@etrade.co.uk" + ><SAMP>drtr@etrade.co.uk</SAMP></A> + </ADDRESS> + + </BODY> +</HTML> diff --git a/docs/ifupdown_design.txt b/docs/ifupdown_design.txt new file mode 100644 index 0000000..9df5792 --- /dev/null +++ b/docs/ifupdown_design.txt @@ -0,0 +1,44 @@ +This document is meant to convince you to not use ifup/ifdown. + + +The general problem with ifupdown is that it is "copulated in vertical +fashion" by design. It tries to do the job of shell script in C, +and this is invariably doomed to fail. You need ifup/ifdown +to be adaptable by local admins, and C is an extremely poor choice +for that. + +We are doomed to have problems with ifup/ifdown. Just look as this code: + +static const struct dhcp_client_t ext_dhcp_clients[] = { + { "dhcpcd", "<up cmd>", "<down cmd>" }, + { "dhclient", ........ }, + { "pump", ........ }, + { "udhcpc", ........ }, +}; + +static int dhcp_down(struct interface_defn_t *ifd, execfn *exec) +{ +#if ENABLE_FEATURE_IFUPDOWN_EXTERNAL_DHCP + int i ; + for (i = 0; i < ARRAY_SIZE(ext_dhcp_clients); i++) { + if (exists_execable(ext_dhcp_clients[i].name)) + return execute(ext_dhcp_clients[i].stopcmd, ifd, exec); + } + bb_error_msg("no dhcp clients found, using static interface shutdown"); + return static_down(ifd, exec); +#elif ENABLE_APP_UDHCPC + return execute("kill " + "`cat /var/run/udhcpc.%iface%.pid` 2>/dev/null", ifd, exec); +#else + return 0; /* no dhcp support */ +#endif +} + +How the hell it is supposed to work reliably this way? Just imagine that +admin is using pump and ifup/ifdown. It works. Then, for whatever reason, +admin installs dhclient, but does NOT use it. ifdown will STOP WORKING, +just because it will see installed dhclient binary in e.g. /usr/bin/dhclient! +This is stupid. + +I seriously urge people to not use ifup/ifdown. +Use something less brain damaged. diff --git a/docs/keep_data_small.txt b/docs/keep_data_small.txt new file mode 100644 index 0000000..2ddbefa --- /dev/null +++ b/docs/keep_data_small.txt @@ -0,0 +1,216 @@ + Keeping data small + +When many applets are compiled into busybox, all rw data and +bss for each applet are concatenated. Including those from libc, +if static busybox is built. When busybox is started, _all_ this data +is allocated, not just that one part for selected applet. + +What "allocated" exactly means, depends on arch. +On NOMMU it's probably bites the most, actually using real +RAM for rwdata and bss. On i386, bss is lazily allocated +by COWed zero pages. Not sure about rwdata - also COW? + +In order to keep busybox NOMMU and small-mem systems friendly +we should avoid large global data in our applets, and should +minimize usage of libc functions which implicitly use +such structures. + +Small experiment to measure "parasitic" bbox memory consumption: +here we start 1000 "busybox sleep 10" in parallel. +busybox binary is practically allyesconfig static one, +built against uclibc. Run on x86-64 machine with 64-bit kernel: + +bash-3.2# nmeter '%t %c %m %p %[pn]' +23:17:28 .......... 168M 0 147 +23:17:29 .......... 168M 0 147 +23:17:30 U......... 168M 1 147 +23:17:31 SU........ 181M 244 391 +23:17:32 SSSSUUU... 223M 757 1147 +23:17:33 UUU....... 223M 0 1147 +23:17:34 U......... 223M 1 1147 +23:17:35 .......... 223M 0 1147 +23:17:36 .......... 223M 0 1147 +23:17:37 S......... 223M 0 1147 +23:17:38 .......... 223M 1 1147 +23:17:39 .......... 223M 0 1147 +23:17:40 .......... 223M 0 1147 +23:17:41 .......... 210M 0 906 +23:17:42 .......... 168M 1 147 +23:17:43 .......... 168M 0 147 + +This requires 55M of memory. Thus 1 trivial busybox applet +takes 55k of memory on 64-bit x86 kernel. + +On 32-bit kernel we need ~26k per applet. + +Script: + +i=1000; while test $i != 0; do + echo -n . + busybox sleep 30 & + i=$((i - 1)) +done +echo +wait + +(Data from NOMMU arches are sought. Provide 'size busybox' output too) + + + Example 1 + +One example how to reduce global data usage is in +archival/libunarchive/decompress_unzip.c: + +/* This is somewhat complex-looking arrangement, but it allows + * to place decompressor state either in bss or in + * malloc'ed space simply by changing #defines below. + * Sizes on i386: + * text data bss dec hex + * 5256 0 108 5364 14f4 - bss + * 4915 0 0 4915 1333 - malloc + */ +#define STATE_IN_BSS 0 +#define STATE_IN_MALLOC 1 + +(see the rest of the file to get the idea) + +This example completely eliminates globals in that module. +Required memory is allocated in unpack_gz_stream() [its main module] +and then passed down to all subroutines which need to access 'globals' +as a parameter. + + + Example 2 + +In case you don't want to pass this additional parameter everywhere, +take a look at archival/gzip.c. Here all global data is replaced by +single global pointer (ptr_to_globals) to allocated storage. + +In order to not duplicate ptr_to_globals in every applet, you can +reuse single common one. It is defined in libbb/messages.c +as struct globals *const ptr_to_globals, but the struct globals is +NOT defined in libbb.h. You first define your own struct: + +struct globals { int a; char buf[1000]; }; + +and then declare that ptr_to_globals is a pointer to it: + +#define G (*ptr_to_globals) + +ptr_to_globals is declared as constant pointer. +This helps gcc understand that it won't change, resulting in noticeably +smaller code. In order to assign it, use SET_PTR_TO_GLOBALS macro: + + SET_PTR_TO_GLOBALS(xzalloc(sizeof(G))); + +Typically it is done in <applet>_main(). + +Now you can reference "globals" by G.a, G.buf and so on, in any function. + + + bb_common_bufsiz1 + +There is one big common buffer in bss - bb_common_bufsiz1. It is a much +earlier mechanism to reduce bss usage. Each applet can use it for +its needs. Library functions are prohibited from using it. + +'G.' trick can be done using bb_common_bufsiz1 instead of malloced buffer: + +#define G (*(struct globals*)&bb_common_bufsiz1) + +Be careful, though, and use it only if globals fit into bb_common_bufsiz1. +Since bb_common_bufsiz1 is BUFSIZ + 1 bytes long and BUFSIZ can change +from one libc to another, you have to add compile-time check for it: + +if (sizeof(struct globals) > sizeof(bb_common_bufsiz1)) + BUG_<applet>_globals_too_big(); + + + Drawbacks + +You have to initialize it by hand. xzalloc() can be helpful in clearing +allocated storage to 0, but anything more must be done by hand. + +All global variables are prefixed by 'G.' now. If this makes code +less readable, use #defines: + +#define dev_fd (G.dev_fd) +#define sector (G.sector) + + + Word of caution + +If applet doesn't use much of global data, converting it to use +one of above methods is not worth the resulting code obfuscation. +If you have less than ~300 bytes of global data - don't bother. + + + gcc's data alignment problem + +The following attribute added in vi.c: + +static int tabstop; +static struct termios term_orig __attribute__ ((aligned (4))); +static struct termios term_vi __attribute__ ((aligned (4))); + +reduces bss size by 32 bytes, because gcc sometimes aligns structures to +ridiculously large values. asm output diff for above example: + + tabstop: + .zero 4 + .section .bss.term_orig,"aw",@nobits +- .align 32 ++ .align 4 + .type term_orig, @object + .size term_orig, 60 + term_orig: + .zero 60 + .section .bss.term_vi,"aw",@nobits +- .align 32 ++ .align 4 + .type term_vi, @object + .size term_vi, 60 + +gcc doesn't seem to have options for altering this behaviour. + +gcc 3.4.3 and 4.1.1 tested: +char c = 1; +// gcc aligns to 32 bytes if sizeof(struct) >= 32 +struct { + int a,b,c,d; + int i1,i2,i3; +} s28 = { 1 }; // struct will be aligned to 4 bytes +struct { + int a,b,c,d; + int i1,i2,i3,i4; +} s32 = { 1 }; // struct will be aligned to 32 bytes +// same for arrays +char vc31[31] = { 1 }; // unaligned +char vc32[32] = { 1 }; // aligned to 32 bytes + +-fpack-struct=1 reduces alignment of s28 to 1 (but probably +will break layout of many libc structs) but s32 and vc32 +are still aligned to 32 bytes. + +I will try to cook up a patch to add a gcc option for disabling it. +Meanwhile, this is where it can be disabled in gcc source: + +gcc/config/i386/i386.c +int +ix86_data_alignment (tree type, int align) +{ +#if 0 + if (AGGREGATE_TYPE_P (type) + && TYPE_SIZE (type) + && TREE_CODE (TYPE_SIZE (type)) == INTEGER_CST + && (TREE_INT_CST_LOW (TYPE_SIZE (type)) >= 256 + || TREE_INT_CST_HIGH (TYPE_SIZE (type))) && align < 256) + return 256; +#endif + +Result (non-static busybox built against glibc): + +# size /usr/srcdevel/bbox/fix/busybox.t0/busybox busybox + text data bss dec hex filename + 634416 2736 23856 661008 a1610 busybox + 632580 2672 22944 658196 a0b14 busybox_noalign diff --git a/docs/mdev.txt b/docs/mdev.txt new file mode 100644 index 0000000..a8a816c --- /dev/null +++ b/docs/mdev.txt @@ -0,0 +1,127 @@ +------------- + MDEV Primer +------------- + +For those of us who know how to use mdev, a primer might seem lame. For +everyone else, mdev is a weird black box that they hear is awesome, but can't +seem to get their head around how it works. Thus, a primer. + +----------- + Basic Use +----------- + +Mdev has two primary uses: initial population and dynamic updates. Both +require sysfs support in the kernel and have it mounted at /sys. For dynamic +updates, you also need to have hotplugging enabled in your kernel. + +Here's a typical code snippet from the init script: +[0] mount -t proc proc /proc +[1] mount -t sysfs sysfs /sys +[2] echo /bin/mdev > /proc/sys/kernel/hotplug +[3] mdev -s + +Alternatively, without procfs the above becomes: +[1] mount -t sysfs sysfs /sys +[2] sysctl -w kernel.hotplug=/bin/mdev +[3] mdev -s + + +Of course, a more "full" setup would entail executing this before the previous +code snippet: +[4] mount -t tmpfs -o size=64k,mode=0755 tmpfs /dev +[5] mkdir /dev/pts +[6] mount -t devpts devpts /dev/pts + +The simple explanation here is that [1] you need to have /sys mounted before +executing mdev. Then you [2] instruct the kernel to execute /bin/mdev whenever +a device is added or removed so that the device node can be created or +destroyed. Then you [3] seed /dev with all the device nodes that were created +while the system was booting. + +For the "full" setup, you want to [4] make sure /dev is a tmpfs filesystem +(assuming you're running out of flash). Then you want to [5] create the +/dev/pts mount point and finally [6] mount the devpts filesystem on it. + +------------- + MDEV Config (/etc/mdev.conf) +------------- + +Mdev has an optional config file for controlling ownership/permissions of +device nodes if your system needs something more than the default root/root +660 permissions. + +The file has the format: + <device regex> <uid>:<gid> <octal permissions> + or @<maj[,min1[-min2]]> <uid>:<gid> <octal permissions> + +For example: + hd[a-z][0-9]* 0:3 660 + +The config file parsing stops at the first matching line. If no line is +matched, then the default of 0:0 660 is used. To set your own default, simply +create your own total match like so: + .* 1:1 777 + +You can rename/move device nodes by using the next optional field. + <device regex> <uid>:<gid> <octal permissions> [=path] +So if you want to place the device node into a subdirectory, make sure the path +has a trailing /. If you want to rename the device node, just place the name. + hda 0:3 660 =drives/ +This will move "hda" into the drives/ subdirectory. + hdb 0:3 660 =cdrom +This will rename "hdb" to "cdrom". + +Similarly, ">path" renames/moves the device but it also creates +a direct symlink /dev/DEVNAME to the renamed/moved device. + +If you also enable support for executing your own commands, then the file has +the format: + <device regex> <uid>:<gid> <octal permissions> [=path] [@|$|*<command>] + or + <device regex> <uid>:<gid> <octal permissions> [>path] [@|$|*<command>] +The special characters have the meaning: + @ Run after creating the device. + $ Run before removing the device. + * Run both after creating and before removing the device. + +The command is executed via the system() function (which means you're giving a +command to the shell), so make sure you have a shell installed at /bin/sh. You +should also keep in mind that the kernel executes hotplug helpers with stdin, +stdout, and stderr connected to /dev/null. + +For your convenience, the shell env var $MDEV is set to the device name. So if +the device "hdc" was matched, MDEV would be set to "hdc". + +---------- + FIRMWARE +---------- + +Some kernel device drivers need to request firmware at runtime in order to +properly initialize a device. Place all such firmware files into the +/lib/firmware/ directory. At runtime, the kernel will invoke mdev with the +filename of the firmware which mdev will load out of /lib/firmware/ and into +the kernel via the sysfs interface. The exact filename is hardcoded in the +kernel, so look there if you need to know how to name the file in userspace. + +------------ + SEQUENCING +------------ + +Kernel does not serialize hotplug events. It increments SEQNUM environmental +variable for each successive hotplug invocation. Normally, mdev doesn't care. +This may reorder hotplug and hot-unplug events, with typical symptoms of +device nodes sometimes not created as expected. + +However, if /dev/mdev.seq file is found, mdev will compare its +contents with SEQNUM. It will retry up to two seconds, waiting for them +to match. If they match exactly (not even trailing '\n' is allowed), +or if two seconds pass, mdev runs as usual, then it rewrites /dev/mdev.seq +with SEQNUM+1. + +IOW: this will serialize concurrent mdev invocations. + +If you want to activate this feature, execute "echo >/dev/mdev.seq" prior to +setting mdev to be the hotplug handler. This writes single '\n' to the file. +NB: mdev recognizes /dev/mdev.seq consisting of single '\n' characher +as a special case. IOW: this will not make your first hotplug event +to stall for two seconds. diff --git a/docs/new-applet-HOWTO.txt b/docs/new-applet-HOWTO.txt new file mode 100644 index 0000000..6f89cbe --- /dev/null +++ b/docs/new-applet-HOWTO.txt @@ -0,0 +1,182 @@ +How to Add a New Applet to BusyBox +================================== + +This document details the steps you must take to add a new applet to BusyBox. + +Credits: +Matt Kraai - initial writeup +Mark Whitley - the remix +Thomas Lundquist - Trying to keep it updated. + +When doing this you should consider using the latest svn trunk. +This is a good thing if you plan to getting it commited into mainline. + +Initial Write +------------- + +First, write your applet. Be sure to include copyright information at the top, +such as who you stole the code from and so forth. Also include the mini-GPL +boilerplate. Be sure to name the main function <applet>_main instead of main. +And be sure to put it in <applet>.c. Usage does not have to be taken care of by +your applet. +Make sure to #include "libbb.h" as the first include file in your applet so +the bb_config.h and appropriate platform specific files are included properly. + +For a new applet mu, here is the code that would go in mu.c: + +(busybox.h already includes most usual header files. You do not need +#include <stdio.h> etc...) + + +----begin example code------ + +/* vi: set sw=4 ts=4: */ +/* + * Mini mu implementation for busybox + * + * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL> + * + * Licensed under GPLv2 or later, see file LICENSE in this tarball for details. + */ + +#include "libbb.h" +#include "other.h" + +int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE; +int mu_main(int argc, char **argv) +{ + int fd; + ssize_t n; + char mu; + + fd = xopen("/dev/random", O_RDONLY); + + if ((n = safe_read(fd, &mu, 1)) < 1) + bb_perror_msg_and_die("/dev/random"); + + return mu; +} + +----end example code------ + + +Coding Style +------------ + +Before you submit your applet for inclusion in BusyBox, (or better yet, before +you _write_ your applet) please read through the style guide in the docs +directory and make your program compliant. + + +Some Words on libbb +------------------- + +As you are writing your applet, please be aware of the body of pre-existing +useful functions in libbb. Use these instead of reinventing the wheel. + +Additionally, if you have any useful, general-purpose functions in your +applet that could be useful in other applets, consider putting them in libbb. + +And it may be possible that some of the other applets uses functions you +could use. If so, you have to rip the function out of the applet and make +a libbb function out of it. + +Adding a libbb function: +------------------------ + +Make a new file named <function_name>.c + +----start example code------ + +#include "libbb.h" +#include "other.h" + +int function(char *a) +{ + return *a; +} + +----end example code------ + +Add <function_name>.o in the right alphabetically sorted place +in libbb/Kbuild. You should look at the conditional part of +libbb/Kbuild aswell. + +You should also try to find a suitable place in include/libbb.h for +the function declaration. If not, add it somewhere anyway, with or without +ifdefs to include or not. + +You can look at libbb/Config.in and try to find out if the function is +tuneable and add it there if it is. + + +Placement / Directory +--------------------- + +Find the appropriate directory for your new applet. + +Make sure you find the appropriate places in the files, the applets are +sorted alphabetically. + +Add the applet to Kbuild in the chosen directory: + +lib-$(CONFIG_MU) += mu.o + +Add the applet to Config.in in the chosen directory: + +config MU + bool "MU" + default n + help + Returns an indeterminate value. + + +Usage String(s) +--------------- + +Next, add usage information for you applet to include/usage.h. +This should look like the following: + + #define mu_trivial_usage \ + "-[abcde] FILES" + #define mu_full_usage \ + "Returns an indeterminate value.\n\n" \ + "Options:\n" \ + "\t-a\t\tfirst function\n" \ + "\t-b\t\tsecond function\n" \ + ... + +If your program supports flags, the flags should be mentioned on the first +line (-[abcde]) and a detailed description of each flag should go in the +mu_full_usage section, one flag per line. (Numerous examples of this +currently exist in usage.h.) + + +Header Files +------------ + +Next, add an entry to include/applets.h. Be *sure* to keep the list +in alphabetical order, or else it will break the binary-search lookup +algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily: + +Be sure to read the top of applets.h before adding your applet. + + /* all programs above here are alphabetically "less than" 'mu' */ + USE_MU(APPLET(mu, _BB_DIR_USR_BIN, _BB_SUID_NEVER)) + /* all programs below here are alphabetically "greater than" 'mu' */ + + +The Grand Announcement +---------------------- + +Then create a diff by adding the new files with svn (remember your libbb files) + svn add <where you put it>/mu.c +eventually also: + svn add libbb/function.c +then + svn diff +and send it to the mailing list: + busybox@busybox.net + http://busybox.net/mailman/listinfo/busybox + +Sending patches as attachments is preferred, but not required. diff --git a/docs/nofork_noexec.txt b/docs/nofork_noexec.txt new file mode 100644 index 0000000..06c789a --- /dev/null +++ b/docs/nofork_noexec.txt @@ -0,0 +1,79 @@ + NOEXEC and NOFORK applets. + +Unix shells traditionally execute some commands internally in the attempt +to dramatically speed up execution. It will be slow as hell if for every +"echo blah" shell will fork and exec /bin/echo. To this end, shells +have to _reimplement_ these commands internally. + +Busybox is unique in this regard because it already is a collection +of reimplemented Unix commands, and we can do the same trick +for speeding up busybox shells, and more. NOEXEC and NOFORK applets +are exactly those applets which are eligible for these tricks. + +Applet will be subject to NOFORK/NOEXEC tricks if it is marked as such +in applets.h. FEATURE_PREFER_APPLETS is a config option which +globally enables usage of NOFORK/NOEXEC tricks. +If it is enabled, FEATURE_SH_STANDALONE can be enabled too, +and then shells will use NOFORK/NOEXEC tricks for ordinary commands. +NB: shell builtins use these tricks regardless of FEATURE_SH_STANDALONE +or FEATURE_PREFER_APPLETS. + +In C, if you want to call a program and wait for it, use +spawn_and_wait(argv), BB_EXECVP(prog,argv) or BB_EXECLP(prog,argv0,...). +They check whether program name is an applet name and optionally +do NOFORK/NOEXEC thing depending on configuration. + + + NOEXEC + +NOEXEC applet should work correctly if another applet forks and then +executes exit(<applet>_main(argc,argv)) in the child. The rules +roughly are: + +* do not expect shared global variables/buffers to be in their + "initialized" state. Examples: xfunc_error_retval can be != 1, + bb_common_bufsiz1 can be scribbled over, ... +* do not expect that stdio wasn't used before. Calling set[v]buf() + can be disastrous. +* ... + +NOEXEC applets save only one half of fork+exec overhead. +NOEXEC trick is disabled for NOMMU build. + + + NOFORK + +NOFORK applet should work correctly if another applet simply runs +<applet>_main(argc,argv) and then continues with its business (xargs, +find, shells can do it). This poses much more serious limitations +on what applet can/cannot do: + +* all NOEXEC limitations apply. +* do not ever exit() or exec(). + - xfuncs are okay. They are using special trick to return + to the caller applet instead of dying when they detect "x" condition. + - you may "exit" to caller applet by calling xfunc_die(). Return value + is taken from xfunc_error_retval. + - fflush_stdout_and_exit(n) is ok to use. +* do not use shared global data, or save/restore shared global data + prior to returning. (e.g. bb_common_bufsiz1 is off-limits). + - getopt32() is ok to use. You do not need to save/restore option_mask32, + it is already done by core code. +* if you allocate memory, you can use xmalloc() only on the very first + allocation. All other allocations should use malloc[_or_warn](). + After first allocation, you cannot use any xfuncs. + Otherwise, failing xfunc will return to caller applet + without freeing malloced data! +* All allocated data, opened files, signal handlers, termios settings, + O_NONBLOCK flags etc should be freed/closed/restored prior to return. +* ... + +NOFORK applets give the most of speed advantage, but are trickiest +to implement. In order to minimize amount of bugs and maintenance, +prime candidates for NOFORK-ification are those applets which +are small and easy to audit, and those which are more likely to be +frequently executed from shell/find/xargs, particularly in shell +script loops. Applets which mess with signal handlers, termios etc +are probably not worth the effort. + +Any NOFORK applet is also a NOEXEC applet. diff --git a/docs/sigint.htm b/docs/sigint.htm new file mode 100644 index 0000000..e230f4d --- /dev/null +++ b/docs/sigint.htm @@ -0,0 +1,627 @@ +<HTML> +<HEAD> +<link rel="SHORTCUT ICON" href="http://www.cons.org/favicon.ico"> +<TITLE>Proper handling of SIGINT/SIGQUIT [http://www.cons.org/cracauer/sigint.html]</TITLE> +<!-- Created by: GNU m4 using $Revision: 1.20 $ of crawww.m4lib on 11-Feb-2005 --> +<BODY BGCOLOR="#fff8e1"> +<CENTER><H2>Proper handling of SIGINT/SIGQUIT</H2></CENTER> +<img src=linie.png width="100%" alt=" "> +<P> + +<table border=1 cellpadding=4> +<tr><th valign=top align=left>Abstract: </th> +<td valign=top align=left> +In UNIX terminal sessions, you usually have a key like +<code>C-c</code> (Control-C) to immediately end whatever program you +have running in the foreground. This should work even when the program +you called has called other programs in turn. Everything should be +aborted, giving you your command prompt back, no matter how deep the +call stack is. + +<p>Basically, it's trivial. But the existence of interactive +applications that use SIGINT and/or SIGQUIT for other purposes than a +complete immediate abort make matters complicated, and - as was to +expect - left us with several ways to solve the problems. Of course, +existing shells and applications follow different ways. + +<P>This Web pages outlines different ways to solve the problem and +argues that only one of them can do everything right, although it +means that we have to fix some existing software. + + + +</td></tr><tr><th valign=top align=left>Intended audience: </th> +<td valign=top align=left>Programmers who implement programs that catch SIGINT/SIGQUIT. +<BR>Programmers who implements shells or shell-like programs that +execute batches of programs. + +<p>Users who have problems problems getting rid of runaway shell +scripts using <code>Control-C</code>. Or have interactive applications +that don't behave right when sending SIGINT. Examples are emacs'es +that die on Control-g or shellscript statements that sometimes are +executed and sometimes not, apparently not determined by the user's +intention. + + +</td></tr><tr><th valign=top align=left>Required knowledge: </th> +<td valign=top align=left>You have to know what it means to catch SIGINT or SIGQUIT and how +processes are waiting for other processes (childs) they spawned. + + +</td></tr></table> +<img src=linie.png width="100%" alt=" "> + + +<H3>Basic concepts</H3> + +What technically happens when you press Control-C is that all programs +running in the foreground in your current terminal (or virtual +terminal) get the signal SIGINT sent. + +<p>You may change the key that triggers the signal using +<code>stty</code> and running programs may remap the SIGINT-sending +key at any time they like, without your intervention and without +asking you first. + +<p>The usual reaction of a running program to SIGINT is to exit. +However, not all program do an exit on SIGINT, programs are free to +use the signal for other actions or to ignore it at all. + +<p>All programs running in the foreground receive the signal. This may +be a nested "stack" of programs: You started a program that started +another and the outer is waiting for the inner to exit. This nesting +may be arbitrarily deep. + +<p>The innermost program is the one that decides what to do on SIGINT. +It may exit, do something else or do nothing. Still, when the user hit +SIGINT, all the outer programs are awaken, get the signal and may +react on it. + +<H3>What we try to achieve</H3> + +The problem is with shell scripts (or similar programs that call +several subprograms one after another). + +<p>Let us consider the most basic script: +<PRE> +#! /bin/sh +program1 +program2 +</PRE> +and the usual run looks like this: +<PRE> +$ sh myscript +[output of program1] +[output of program2] +$ +</PRE> + +<p>Let us assume that both programs do nothing special on SIGINT, they +just exit. + +<p>Now imagine the user hits C-c while a shellscript is executing its +first program. The following programs receive SIGINT: program1 and +also the shell executing the script. program1 exits. + +<p>But what should the shell do? If we say that it is only the +innermost's programs business to react on SIGINT, the shell will do +nothing special (not exit) and it will continue the execution of the +script and run program2. But this is wrong: The user's intention in +hitting C-c is to abort the whole script, to get his prompt back. If +he hits C-c while the first program is running, he does not want +program2 to be even started. + +<p>here is what would happen if the shell doesn't do anything: +<PRE> +$ sh myscript +[first half of program1's output] +C-c [users presses C-c] +[second half of program1's output will not be displayed] +[output of program2 will appear] +</PRE> + + +<p>Consider a more annoying example: +<pre> +#! /bin/sh +# let's assume there are 300 *.dat files +for file in *.dat ; do + dat2ascii $dat +done +</pre> + +If your shell wouldn't end if the user hits <code>C-c</code>, +<code>C-c</code> would just end <strong>one</strong> dat2ascii run and +the script would continue. Thus, you had to hit <code>C-c</code> up to +300 times to end this script. + +<H3>Alternatives to do so</H3> + +<p>There are several ways to handle abortion of shell scripts when +SIGINT is received while a foreground child runs: + +<menu> + +<li>As just outlined, the shellscript may just continue, ignoring the +fact that the user hit <code>C-c</code>. That way, your shellscript - +including any loops - would continue and you had no chance of aborting +it except using the kill command after finding out the outermost +shell's PID. This "solution" will not be discussed further, as it is +obviously not desirable. + +<p><li>The shell itself exits immediately when it receives SIGINT. Not +only the program called will exit, but the calling (the +script-executing) shell. The first variant is to exit the shell (and +therefore discontinuing execution of the script) immediately, while +the background program may still be executing (remember that although +the shell is just waiting for the called program to exit, it is woken +up and may act). I will call the way of doing things the "IUE" (for +"immediate unconditional exit") for the rest of this document. + +<p><li>As a variant of the former, when the shell receives SIGINT +while it is waiting for a child to exit, the shell does not exit +immediately. but it remembers the fact that a SIGINT happened. After +the called program exits and the shell's wait ends, the shell will +exit itself and hence discontinue the script. I will call the way of +doing things the "WUE" (for "wait and unconditional exit") for the +rest of this document. + +<p><li>There is also a way that the calling shell can tell whether the +called program exited on SIGINT and if it ignored SIGINT (or used it +for other purposes). As in the <sl>WUE</sl> way, the shell waits for +the child to complete. It figures whether the program was ended on +SIGINT and if so, it discontinue the script. If the program did any +other exit, the script will be continued. I will call the way of doing +things the "WCE" (for "wait and cooperative exit") for the rest of +this document. + +</menu> + +<H3>The problem</H3> + +On first sight, all three solutions (IUE, WUE and WCE) all seem to do +what we want: If C-c is hit while the first program of the shell +script runs, the script is discontinued. The user gets his prompt back +immediately. So what are the difference between these way of handling +SIGINT? + +<p>There are programs that use the signal SIGINT for other purposes +than exiting. They use it as a normal keystroke. The user is expected +to use the key that sends SIGINT during a perfectly normal program +run. As a result, the user sends SIGINT in situations where he/she +does not want the program or the script to end. + +<p>The primary example is the emacs editor: C-g does what ESC does in +other applications: It cancels a partially executed or prepared +operation. Technically, emacs remaps the key that sends SIGINT from +C-c to C-g and catches SIGINT. + +<p>Remember that the SIGINT is sent to all programs running in the +foreground. If emacs is executing from a shell script, both emacs and +the shell get SIGINT. emacs is the program that decides what to do: +Exit on SIGINT or not. emacs decides not to exit. The problem arises +when the shell draws its own conclusions from receiving SIGINT without +consulting emacs for its opinion. + +<p>Consider this script: +<PRE> +#! /bin/sh +emacs /tmp/foo +cp /tmp/foo /home/user/mail/sent +</PRE> + +<p>If C-g is used in emacs, both the shell and emacs will received +SIGINT. Emacs will not exit, the user used C-g as a normal editing +keystroke, he/she does not want the script to be aborted on C-g. + +<p>The central problem is that the second command (cp) may +unintentionally be killed when the shell draws its own conclusion +about the user's intention. The innermost program is the only one to +judge. + +<H3>One more example</H3> + +<p>Imagine a mail session using a curses mailer in a tty. You called +your mailer and started to compose a message. Your mailer calls emacs. +<code>C-g</code> is a normal editing key in emacs. Technically it +sends SIGINT (it was <code>C-c</code>, but emacs remapped the key) to +<menu> +<li>emacs +<li>the shell between your mailer and emacs, the one from your mailers + system("emacs /tmp/bla.44") command +<li>the mailer itself +<li>possibly another shell if your mailer was called by a shell script +or from another application using system(3) +<li>your interactive shell (which ignores it since it is interactive +and hence is not relevant to this discussion) +</menu> + +<p>If everyone just exits on SIGINT, you will be left with nothing but +your login shell, without asking. + +<p>But for sure you don't want to be dropped out of your editor and +out of your mailer back to the commandline, having your edited data +and mailer status deleted. + +<p>Understand the difference: While <code>C-g</code> is used an a kind +of abort key in emacs, it isn't the major "abort everything" key. When +you use <code>C-g</code> in emacs, you want to end some internal emacs +command. You don't want your whole emacs and mailer session to end. + +<p>So, if the shell exits immediately if the user sends SIGINT (the +second of the four ways shown above), the parent of emacs would die, +leaving emacs without the controlling tty. The user will lose it's +editing session immediately and unrecoverable. If the "main" shell of +the operating system defaults to this behavior, every editor session +that is spawned from a mailer or such will break (because it is +usually executed by system(3), which calls /bin/sh). This was the case +in FreeBSD before I and Bruce Evans changed it in 1998. + +<p>If the shell recognized that SIGINT was sent and exits after the +current foreground process exited (the third way of the four), the +editor session will not be disturbed, but things will still not work +right. + +<H3>A further look at the alternatives</H3> + +<p>Still considering this script to examine the shell's actions in the +IUE, WUE and ICE way of handling SIGINT: +<PRE> +#! /bin/sh +emacs /tmp/foo +cp /tmp/foo /home/user/mail/sent +</PRE> + +<p>The IUE ("immediate unconditional exit") way does not work at all: +emacs wants to survive the SIGINT (it's a normal editing key for +emacs), but its parent shell unconditionally thinks "We received +SIGINT. Abort everything. Now.". The shell will exit even before emacs +exits. But this will leave emacs in an unusable state, since the death +of its calling shell will leave it without required resources (file +descriptors). This way does not work at all for shellscripts that call +programs that use SIGINT for other purposes than immediate exit. Even +for programs that exit on SIGINT, but want to do some cleanup between +the signal and the exit, may fail before they complete their cleanup. + +<p>It should be noted that this way has one advantage: If a child +blocks SIGINT and does not exit at all, this way will get control back +to the user's terminal. Since such programs should be banned from your +system anyway, I don't think that weighs against the disadvantages. + +<p>WUE ("wait and unconditional exit") is a little more clever: If C-g +was used in emacs, the shell will get SIGINT. It will not immediately +exit, but remember the fact that a SIGINT happened. When emacs ends +(maybe a long time after the SIGINT), it will say "Ok, a SIGINT +happened sometime while the child was executing, the user wants the +script to be discontinued". It will then exit. The cp will not be +executed. But that's bad. The "cp" will be executed when the emacs +session ended without the C-g key ever used, but it will not be +executed when the user used C-g at least one time. That is clearly not +desired. Since C-g is a normal editing key in emacs, the user expects +the rest of the script to behave identically no matter what keys he +used. + +<p>As a result, the "WUE" way is better than the "IUE" way in that it +does not break SIGINT-using programs completely. The emacs session +will end undisturbed. But it still does not support scripts where +other actions should be performed after a program that use SIGINT for +non-exit purposes. Since the behavior is basically undeterminable for +the user, this can lead to nasty surprises. + +<p>The "WCE" way fixes this by "asking" the called program whether it +exited on SIGINT or not. While emacs receives SIGINT, it does not exit +on it and a calling shell waiting for its exit will not be told that +it exited on SIGINT. (Although it receives SIGINT at some point in +time, the system does not enforce that emacs will exit with +"I-exited-on-SIGINT" status. This is under emacs' control, see below). + +<p>this still work for the normal script without SIGINT-using +programs:</p> +<PRE> +#! /bin/sh +program1 +program2 +</PRE> + +Unless program1 and program2 mess around with signal handling, the +system will tell the calling shell whether the programs exited +normally or as a result of SIGINT. + +<p>The "WCE" way then has an easy way to things right: When one called +program exited with "I-exited-on-SIGINT" status, it will discontinue +the script after this program. If the program ends without this +status, the next command in the script is started. + +<p>It is important to understand that a shell in "WCE" modus does not +need to listen to the SIGINT signal at all. Both in the +"emacs-then-cp" script and in the "several-normal-programs" script, it +will be woken up and receive SIGINT when the user hits the +corresponding key. But the shell does not need to react on this event +and it doesn't need to remember the event of any SIGINT, either. +Telling whether the user wants to end a script is done by asking that +program that has to decide, that program that interprets keystrokes +from the user, the innermost program. + +<H3>So everything is well with WCE?</H3> + +Well, almost. + +<p>The problem with the "WCE" modus is that there are broken programs +that do not properly communicate the required information up to the +calling program. + +<p>Unless a program messes with signal handling, the system does this +automatically. + +<p>There are programs that want to exit on SIGINT, but they don't let +the system do the automatic exit, because they want to do some +cleanup. To do so, they catch SIGINT, do the cleanup and then exit by +themselves. + +<p>And here is where the problem arises: Once they catch the signal, +the system will no longer communicate the "I-exited-on-SIGINT" status +to the calling program automatically. Even if the program exit +immediately in the signal handler of SIGINT. Once it catches the +signal, it has to take care of communicating the signal status +itself. + +<p>Some programs don't do this. On SIGINT, they do cleanup and exit +immediatly, but the calling shell isn't told about the non-normal exit +and it will call the next program in the script. + +<p>As a result, the user hits SIGINT and while one program exits, the +shellscript continues. To him/her it looks like the shell fails to +obey to his abortion command. + +<p>Both IUE or WUE shell would not have this problem, since they +discontinue the script on their own. But as I said, they don't support +programs using SIGINT for non-exiting purposes, no matter whether +these programs properly communicate their signal status to the calling +shell or not. + +<p>Since some shell in wide use implement the WUE way (and some even +IUE), there is a considerable number of broken programs out there that +break WCE shells. The programmers just don't recognize it if their +shell isn't WCE. + +<H3>How to be a proper program</H3> + +<p>(Short note in advance: What you need to achieve is that +WIFSIGNALED(status) is true in the calling program and that +WTERMSIG(status) returns SIGINT.) + +<p>If you don't catch SIGINT, the system automatically does the right +thing for you: Your program exits and the calling program gets the +right "I-exited-on-SIGINT" status after waiting for your exit. + +<p>But once you catch SIGINT, you have to act. + +<p>Decide whether the SIGINT is used for exit/abort purposes and hence +a shellscript calling this program should discontinue. This is +hopefully obvious. If you just need to do some cleanup on SIGINT, but +then exit immediately, the answer is "yes". + +<p>If so, you have to tell the calling program about it by exiting +with the "I-exited-on-SIGINT" status. + +<p>There is no other way of doing this than to kill yourself with a +SIGINT signal. Do it by resetting the SIGINT handler to SIG_DFL, then +send yourself the signal. + +<PRE> +void sigint_handler(int sig) +{ + <do some cleanup> + signal(SIGINT, SIG_DFL); + kill(getpid(), SIGINT); +} +</PRE> + +Notes: + +<MENU> + +<LI>You cannot "fake" the proper exit status by an exit(3) with a +special numeric value. People often assume this since the manuals for +shells often list some return value for exactly this. But this is just +a convention for your shell script. It does not work from one UNIX API +program to another. + +<P>All that happens is that the shell sets the "$?" variable to a +special numeric value for the convenience of your script, because your +script does not have access to the lower-lever UNIX status evaluation +functions. This is just an agreement between your script and the +executing shell, it does not have any meaning in other contexts. + +<P><LI>Do not use kill(0, SIGINT) without consulting the manul for +your OS implementation. I.e. on BSD, this would not send the signal to +the current process, but to all processes in the group. + +<P><LI>POSIX 1003.1 allows all these calls to appear in signal +handlers, so it is portable. + +</MENU> + +<p>In a bourne shell script, you can catch signals using the +<code>trap</code> command. Here, the same as for C programs apply. If +the intention of SIGINT is to end your program, you have to exit in a +way that the calling programs "sees" that you have been killed. If +you don't catch SIGINT, this happend automatically, but of you catch +SIGINT, i.e. to do cleanup work, you have to end the program by +killing yourself, not by calling exit. + +<p>Consider this example from FreeBSD's <code>mkdep</code>, which is a +bourne shell script. + +<pre> +TMP=_mkdep$$ +trap 'rm -f $TMP ; trap 2 ; kill -2 $$' 1 2 3 13 15 +</pre> + +Yes, you have to do it the hard way. It's even more annoying in shell +scripts than in C programs since you can't "pre-delete" temporary +files (which isn't really portable in C, though). + +<P>All this applies to programs in all languages, not only C and +bourne shell. Every language implementation that lets you catch SIGINT +should also give you the option to reset the signal and kill yourself. + +<P>It is always desireable to exit the right way, even if you don't +expect your usual callers to depend on it, some unusual one will come +along. This proper exit status will be needed for WCE and will not +hurt when the calling shell uses IUE or WUE. + +<H3>How to be a proper shell</H3> + +All this applies only for the script-executing case. Most shells will +also have interactive modes where things are different. + +<MENU> + +<LI>Do nothing special when SIGINT appears while you wait for a child. +You don't even have to remember that one happened. + +<P><LI>Wait for child to exit, get the exit status. Do not truncate it +to type char. + +<P><LI>Look at WIFSIGNALED(status) and WTERMSIG(status) to tell +whether the child says "I exited on SIGINT: in my opinion the user +wants the shellscript to be discontinued". + +<P><LI>If the latter applies, discontinue the script. + +<P><LI>Exit. But since a shellscript may in turn be called by a +shellscript, you need to make sure that you properly communicate the +discontinue intention to the calling program. As in any other program +(see above), do + +<PRE> + signal(SIGINT, SIG_DFL); + kill(getpid(), SIGINT); +</PRE> + +</MENU> + +<H3>Other remarks</H3> + +Although this web page talks about SIGINT only, almost the same issues +apply to SIGQUIT, including proper exiting by killing yourself after +catching the signal and proper reaction on the WIFSIGNALED(status) +value. One notable difference for SIGQUIT is that you have to make +sure that not the whole call tree dumps core. + +<H3>What to fight</H3> + +Make sure all programs <em>really</em> kill themselves if they react +to SIGINT or SIGQUIT and intend to abort their operation as a result +of this signal. Programs that don't use SIGINT/SIGQUIT as a +termination trigger - but as part of normal operation - don't kill +themselves, but do a normal exit instead. + +<p>Make sure people understand why you can't fake an exit-on-signal by +doing exit(...) using any numerical status. + +<p>Make sure you use a shell that behaves right. Especially if you +develop programs, since it will help seeing problems. + +<H3>Concrete examples how to fix programs:</H3> +<ul> + +<li>The fix for FreeBSD's +<A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/time/time.c.diff?r1=1.10&r2=1.11">time(1)</A>. This fix is the best example, it's quite short and clear and +it fixes a case where someone tried to fake signal exit status by a +numerical value. And the complete program is small. + +<p><li>Fix for FreeBSD's +<A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/truss/main.c.diff?r1=1.9&r2=1.10">truss(1)</A>. + +<p><li>The fix for FreeBSD's +<A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/mkdep/mkdep.gcc.sh.diff?r1=1.8.2.1&r2=1.8.2.2">mkdep(1)</A>, a shell script. + + +<p><li>Fix for FreeBSD's make(1), <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/make/job.c.diff?r1=1.9&r2=1.10">part 1</A>, +<A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/src/usr.bin/make/compat.c.diff?r1=1.10&r2=1.11">part 2</A>. + +</ul> + +<H3>Testsuite for shells</H3> + +I have a collection of shellscripts that test shells for the +behavior. See my <A HREF="download/">download dir</A> to get the newest +"sh-interrupt" files, either as a tarfile or as individual file for +online browsing. This isn't really documented, besides from the +comments the scripts echo. + +<H3>Appendix 1 - table of implementation choices</H3> + +<table border cellpadding=2> + +<tr valign=top> +<th>Method sign</th> +<th>Does what?</th> +<th>Example shells that implement it:</th> +<th>What happens when a shellscript called emacs, the user used +<code>C-g</code> and the script has additional commands in it?</th> +<th>What happens when a shellscript called emacs, the user did not use +<code>C-c</code> and the script has additional commands in it?</th> +<th>What happens if a non-interactive child catches SIGINT?</th> +<th>To behave properly, childs must do what?</th> +</tr> + +<tr valign=top align=left> +<td>IUE</td> +<td>The shell executing a script exits immediately if it receives +SIGINT.</td> +<td>4.4BSD ash (ash), NetBSD, FreeBSD prior to 3.0/22.8</td> +<td>The editor session is lost and subsequent commands are not +executed.</td> +<td>The editor continues as normal and the subsequent commands are +executed. </td> +<td>The scripts ends immediately, returning to the caller even before +the current foreground child of the shell exits. </td> +<td>It doesn't matter what the child does or how it exits, even if the +child continues to operate, the shell returns. </td> +</tr> + +<tr valign=top align=left> +<td>WUE</td> +<td>If the shell executing a script received SIGINT while a foreground +process was running, it will exit after that child's exit.</td> +<td>pdksh (OpenBSD /bin/sh)</td> +<td>The editor continues as normal, but subsequent commands from the +script are not executed.</td> +<td>The editor continues as normal and subsequent commands are +executed. </td> +<td>The scripts returns to its caller after the current foreground +child exits, no matter how the child exited. </td> +<td>It doesn't matter how the child exits (signal status or not), but +if it doesn't return at all, the shell will not return. In no case +will further commands from the script be executed. </td> +</tr> + +<tr valign=top align=left> +<td>WCE</td> +<td>The shell exits if a child signaled that it was killed on a +signal (either it had the default handler for SIGINT or it killed +itself). </td> +<td>bash (Linux /bin/sh), most commercial /bin/sh, FreeBSD /bin/sh +from 3.0/2.2.8.</td> +<td>The editor continues as normal and subsequent commands are +executed. </td> +<td>The editor continues as normal and subsequent commands are +executed. </td> +<td>The scripts returns to its caller after the current foreground +child exits, but only if the child exited with signal status. If +the child did a normal exit (even if it received SIGINT, but catches +it), the script will continue. </td> +<td>The child must be implemented right, or the user will not be able +to break shell scripts reliably.</td> +</tr> + +</table> + +<P><img src=linie.png width="100%" alt=" "> +<BR>©2005 Martin Cracauer <cracauer @ cons.org> +<A HREF="http://www.cons.org/cracauer/">http://www.cons.org/cracauer/</A> +<BR>Last changed: $Date: 2005/02/11 21:44:43 $ +</BODY></HTML> diff --git a/docs/style-guide.txt b/docs/style-guide.txt new file mode 100644 index 0000000..7560d69 --- /dev/null +++ b/docs/style-guide.txt @@ -0,0 +1,714 @@ +Busybox Style Guide +=================== + +This document describes the coding style conventions used in Busybox. If you +add a new file to Busybox or are editing an existing file, please format your +code according to this style. If you are the maintainer of a file that does +not follow these guidelines, please -- at your own convenience -- modify the +file(s) you maintain to bring them into conformance with this style guide. +Please note that this is a low priority task. + +To help you format the whitespace of your programs, an ".indent.pro" file is +included in the main Busybox source directory that contains option flags to +format code as per this style guide. This way you can run GNU indent on your +files by typing 'indent myfile.c myfile.h' and it will magically apply all the +right formatting rules to your file. Please _do_not_ run this on all the files +in the directory, just your own. + + + +Declaration Order +----------------- + +Here is the preferred order in which code should be laid out in a file: + + - commented program name and one-line description + - commented author name and email address(es) + - commented GPL boilerplate + - commented longer description / notes for the program (if needed) + - #includes of .h files with angle brackets (<>) around them + - #includes of .h files with quotes ("") around them + - #defines (if any, note the section below titled "Avoid the Preprocessor") + - const and global variables + - function declarations (if necessary) + - function implementations + + + +Whitespace and Formatting +------------------------- + +This is everybody's favorite flame topic so let's get it out of the way right +up front. + + +Tabs vs. Spaces in Line Indentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The preference in Busybox is to indent lines with tabs. Do not indent lines +with spaces and do not indents lines using a mixture of tabs and spaces. (The +indentation style in the Apache and Postfix source does this sort of thing: +\s\s\s\sif (expr) {\n\tstmt; --ick.) The only exception to this rule is +multi-line comments that use an asterisk at the beginning of each line, i.e.: + + \t/* + \t * This is a block comment. + \t * Note that it has multiple lines + \t * and that the beginning of each line has a tab plus a space + \t * except for the opening '/*' line where the slash + \t * is used instead of a space. + \t */ + +Furthermore, The preference is that tabs be set to display at four spaces +wide, but the beauty of using only tabs (and not spaces) at the beginning of +lines is that you can set your editor to display tabs at *whatever* number of +spaces is desired and the code will still look fine. + + +Operator Spacing +~~~~~~~~~~~~~~~~ + +Put spaces between terms and operators. Example: + + Don't do this: + + for(i=0;i<num_items;i++){ + + Do this instead: + + for (i = 0; i < num_items; i++) { + + While it extends the line a bit longer, the spaced version is more + readable. An allowable exception to this rule is the situation where + excluding the spacing makes it more obvious that we are dealing with a + single term (even if it is a compound term) such as: + + if (str[idx] == '/' && str[idx-1] != '\\') + + or + + if ((argc-1) - (optind+1) > 0) + + +Bracket Spacing +~~~~~~~~~~~~~~~ + +If an opening bracket starts a function, it should be on the +next line with no spacing before it. However, if a bracket follows an opening +control block, it should be on the same line with a single space (not a tab) +between it and the opening control block statement. Examples: + + Don't do this: + + while (!done) + { + + do + { + + Don't do this either: + + while (!done){ + + do{ + + And for heaven's sake, don't do this: + + while (!done) + { + + do + { + + Do this instead: + + while (!done) { + + do { + +If you have long logic statements that need to be wrapped, then uncuddling +the bracket to improve readability is allowed. Generally, this style makes +it easier for reader to notice that 2nd and following lines are still +inside 'if': + + if (some_really_long_checks && some_other_really_long_checks + && some_more_really_long_checks + && even_more_of_long_checks + ) { + do_foo_now; + +Spacing around Parentheses +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Put a space between C keywords and left parens, but not between function names +and the left paren that starts it's parameter list (whether it is being +declared or called). Examples: + + Don't do this: + + while(foo) { + for(i = 0; i < n; i++) { + + Do this instead: + + while (foo) { + for (i = 0; i < n; i++) { + + But do functions like this: + + static int my_func(int foo, char bar) + ... + baz = my_func(1, 2); + +Also, don't put a space between the left paren and the first term, nor between +the last arg and the right paren. + + Don't do this: + + if ( x < 1 ) + strcmp( thisstr, thatstr ) + + Do this instead: + + if (x < 1) + strcmp(thisstr, thatstr) + + +Cuddled Elses +~~~~~~~~~~~~~ + +Also, please "cuddle" your else statements by putting the else keyword on the +same line after the right bracket that closes an 'if' statement. + + Don't do this: + + if (foo) { + stmt; + } + else { + stmt; + } + + Do this instead: + + if (foo) { + stmt; + } else { + stmt; + } + +The exception to this rule is if you want to include a comment before the else +block. Example: + + if (foo) { + stmts... + } + /* otherwise, we're just kidding ourselves, so re-frob the input */ + else { + other_stmts... + } + + +Labels +~~~~~~ + +Labels should start at the beginning of the line, not indented to the block +level (because they do not "belong" to block scope, only to whole function). + + if (foo) { + stmt; + label: + stmt2; + stmt; + } + +(Putting label at position 1 prevents diff -p from confusing label for function +name, but it's not a policy of busybox project to enforce such a minor detail). + + + +Variable and Function Names +--------------------------- + +Use the K&R style with names in all lower-case and underscores occasionally +used to separate words (e.g., "variable_name" and "numchars" are both +acceptable). Using underscores makes variable and function names more readable +because it looks like whitespace; using lower-case is easy on the eyes. + + Frowned upon: + + hitList + TotalChars + szFileName + pf_Nfol_TriState + + Preferred: + + hit_list + total_chars + file_name + sensible_name + +Exceptions: + + - Enums, macros, and constant variables are occasionally written in all + upper-case with words optionally seperatedy by underscores (i.e. FIFO_TYPE, + ISBLKDEV()). + + - Nobody is going to get mad at you for using 'pvar' as the name of a + variable that is a pointer to 'var'. + + +Converting to K&R +~~~~~~~~~~~~~~~~~ + +The Busybox codebase is very much a mixture of code gathered from a variety of +sources. This explains why the current codebase contains such a hodge-podge of +different naming styles (Java, Pascal, K&R, just-plain-weird, etc.). The K&R +guideline explained above should therefore be used on new files that are added +to the repository. Furthermore, the maintainer of an existing file that uses +alternate naming conventions should, at his own convenience, convert those +names over to K&R style. Converting variable names is a very low priority +task. + +If you want to do a search-and-replace of a single variable name in different +files, you can do the following in the busybox directory: + + $ perl -pi -e 's/\bOldVar\b/new_var/g' *.[ch] + +If you want to convert all the non-K&R vars in your file all at once, follow +these steps: + + - In the busybox directory type 'examples/mk2knr.pl files-to-convert'. This + does not do the actual conversion, rather, it generates a script called + 'convertme.pl' that shows what will be converted, giving you a chance to + review the changes beforehand. + + - Review the 'convertme.pl' script that gets generated in the busybox + directory and remove / edit any of the substitutions in there. Please + especially check for false positives (strings that should not be + converted). + + - Type './convertme.pl same-files-as-before' to perform the actual + conversion. + + - Compile and see if everything still works. + +Please be aware of changes that have cascading effects into other files. For +example, if you're changing the name of something in, say utility.c, you +should probably run 'examples/mk2knr.pl utility.c' at first, but when you run +the 'convertme.pl' script you should run it on _all_ files like so: +'./convertme.pl *.[ch]'. + + + +Avoid The Preprocessor +---------------------- + +At best, the preprocessor is a necessary evil, helping us account for platform +and architecture differences. Using the preprocessor unnecessarily is just +plain evil. + + +The Folly of #define +~~~~~~~~~~~~~~~~~~~~ + +Use 'const <type> var' for declaring constants. + + Don't do this: + + #define CONST 80 + + Do this instead, when the variable is in a header file and will be used in + several source files: + + enum { CONST = 80 }; + +Although enum may look ugly to some people, it is better for code size. +With "const int" compiler may fail to optimize it out and will reserve +a real storage in rodata for it! (Hopefully, newer gcc will get better +at it...). With "define", you have slight risk of polluting namespace +(#define doesn't allow you to redefine the name in the inner scopes), +and complex "define" are evaluated each time they uesd, not once +at declarations like enums. Also, the preprocessor does _no_ type checking +whatsoever, making it much more error prone. + + +The Folly of Macros +~~~~~~~~~~~~~~~~~~~ + +Use 'static inline' instead of a macro. + + Don't do this: + + #define mini_func(param1, param2) (param1 << param2) + + Do this instead: + + static inline int mini_func(int param1, param2) + { + return (param1 << param2); + } + +Static inline functions are greatly preferred over macros. They provide type +safety, have no length limitations, no formatting limitations, have an actual +return value, and under gcc they are as cheap as macros. Besides, really long +macros with backslashes at the end of each line are ugly as sin. + + +The Folly of #ifdef +~~~~~~~~~~~~~~~~~~~ + +Code cluttered with ifdefs is difficult to read and maintain. Don't do it. +Instead, put your ifdefs at the top of your .c file (or in a header), and +conditionally define 'static inline' functions, (or *maybe* macros), which are +used in the code. + + Don't do this: + + ret = my_func(bar, baz); + if (!ret) + return -1; + #ifdef CONFIG_FEATURE_FUNKY + maybe_do_funky_stuff(bar, baz); + #endif + + Do this instead: + + (in .h header file) + + #if ENABLE_FEATURE_FUNKY + static inline void maybe_do_funky_stuff(int bar, int baz) + { + /* lotsa code in here */ + } + #else + static inline void maybe_do_funky_stuff(int bar, int baz) {} + #endif + + (in the .c source file) + + ret = my_func(bar, baz); + if (!ret) + return -1; + maybe_do_funky_stuff(bar, baz); + +The great thing about this approach is that the compiler will optimize away +the "no-op" case (the empty function) when the feature is turned off. + +Note also the use of the word 'maybe' in the function name to indicate +conditional execution. + + + +Notes on Strings +---------------- + +Strings in C can get a little thorny. Here's some guidelines for dealing with +strings in Busybox. (There is surely more that could be added to this +section.) + + +String Files +~~~~~~~~~~~~ + +Put all help/usage messages in usage.c. Put other strings in messages.c. +Putting these strings into their own file is a calculated decision designed to +confine spelling errors to a single place and aid internationalization +efforts, if needed. (Side Note: we might want to use a single file - maybe +called 'strings.c' - instead of two, food for thought). + + +Testing String Equivalence +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There's a right way and a wrong way to test for sting equivalence with +strcmp(): + + The wrong way: + + if (!strcmp(string, "foo")) { + ... + + The right way: + + if (strcmp(string, "foo") == 0){ + ... + +The use of the "equals" (==) operator in the latter example makes it much more +obvious that you are testing for equivalence. The former example with the +"not" (!) operator makes it look like you are testing for an error. In a more +perfect world, we would have a streq() function in the string library, but +that ain't the world we're living in. + + +Avoid Dangerous String Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unfortunately, the way C handles strings makes them prone to overruns when +certain library functions are (mis)used. The following table offers a summary +of some of the more notorious troublemakers: + +function overflows preferred +------------------------------------------------- +strcpy dest string safe_strncpy +strncpy may fail to 0-terminate dst safe_strncpy +strcat dest string strncat +gets string it gets fgets +getwd buf string getcwd +[v]sprintf str buffer [v]snprintf +realpath path buffer use with pathconf +[vf]scanf its arguments just avoid it + + +The above is by no means a complete list. Be careful out there. + + + +Avoid Big Static Buffers +------------------------ + +First, some background to put this discussion in context: static buffers look +like this in code: + + /* in a .c file outside any functions */ + static char buffer[BUFSIZ]; /* happily used by any function in this file, + but ick! big! */ + +The problem with these is that any time any busybox app is run, you pay a +memory penalty for this buffer, even if the applet that uses said buffer is +not run. This can be fixed, thusly: + + static char *buffer; + ... + other_func() + { + strcpy(buffer, lotsa_chars); /* happily uses global *buffer */ + ... + foo_main() + { + buffer = xmalloc(sizeof(char)*BUFSIZ); + ... + +However, this approach trades bss segment for text segment. Rather than +mallocing the buffers (and thus growing the text size), buffers can be +declared on the stack in the *_main() function and made available globally by +assigning them to a global pointer thusly: + + static char *pbuffer; + ... + other_func() + { + strcpy(pbuffer, lotsa_chars); /* happily uses global *pbuffer */ + ... + foo_main() + { + char *buffer[BUFSIZ]; /* declared locally, on stack */ + pbuffer = buffer; /* but available globally */ + ... + +This last approach has some advantages (low code size, space not used until +it's needed), but can be a problem in some low resource machines that have +very limited stack space (e.g., uCLinux). + +A macro is declared in busybox.h that implements compile-time selection +between xmalloc() and stack creation, so you can code the line in question as + + RESERVE_CONFIG_BUFFER(buffer, BUFSIZ); + +and the right thing will happen, based on your configuration. + +Another relatively new trick of similar nature is explained +in keep_data_small.txt. + + + +Miscellaneous Coding Guidelines +------------------------------- + +The following are important items that don't fit into any of the above +sections. + + +Model Busybox Applets After GNU Counterparts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When in doubt about the proper behavior of a Busybox program (output, +formatting, options, etc.), model it after the equivalent GNU program. +Doesn't matter how that program behaves on some other flavor of *NIX; doesn't +matter what the POSIX standard says or doesn't say, just model Busybox +programs after their GNU counterparts and it will make life easier on (nearly) +everyone. + +The only time we deviate from emulating the GNU behavior is when: + + - We are deliberately not supporting a feature (such as a command line + switch) + - Emulating the GNU behavior is prohibitively expensive (lots more code + would be required, lots more memory would be used, etc.) + - The difference is minor or cosmetic + +A note on the 'cosmetic' case: output differences might be considered +cosmetic, but if the output is significant enough to break other scripts that +use the output, it should really be fixed. + + +Scope +~~~~~ + +If a const variable is used only in a single source file, put it in the source +file and not in a header file. Likewise, if a const variable is used in only +one function, do not make it global to the file. Instead, declare it inside +the function body. Bottom line: Make a conscious effort to limit declarations +to the smallest scope possible. + +Inside applet files, all functions should be declared static so as to keep the +global name space clean. The only exception to this rule is the "applet_main" +function which must be declared extern. + +If you write a function that performs a task that could be useful outside the +immediate file, turn it into a general-purpose function with no ties to any +applet and put it in the utility.c file instead. + + +Brackets Are Your Friends +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please use brackets on all if and else statements, even if it is only one +line. Example: + + Don't do this: + + if (foo) + stmt1; + stmt2 + stmt3; + + Do this instead: + + if (foo) { + stmt1; + } + stmt2 + stmt3; + +The "bracketless" approach is error prone because someday you might add a line +like this: + + if (foo) + stmt1; + new_line(); + stmt2; + stmt3; + +And the resulting behavior of your program would totally bewilder you. (Don't +laugh, it happens to us all.) Remember folks, this is C, not Python. + + +Function Declarations +~~~~~~~~~~~~~~~~~~~~~ + +Do not use old-style function declarations that declare variable types between +the parameter list and opening bracket. Example: + + Don't do this: + + int foo(parm1, parm2) + char parm1; + float parm2; + { + .... + + Do this instead: + + int foo(char parm1, float parm2) + { + .... + +The only time you would ever need to use the old declaration syntax is to +support ancient, antediluvian compilers. To our good fortune, we have access +to more modern compilers and the old declaration syntax is neither necessary +nor desired. + + +Emphasizing Logical Blocks +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Organization and readability are improved by putting extra newlines around +blocks of code that perform a single task. These are typically blocks that +begin with a C keyword, but not always. + +Furthermore, you should put a single comment (not necessarily one line, just +one comment) before the block, rather than commenting each and every line. +There is an optimal amount of commenting that a program can have; you can +comment too much as well as too little. + +A picture is really worth a thousand words here, the following example +illustrates how to emphasize logical blocks: + + while (line = xmalloc_fgets(fp)) { + + /* eat the newline, if any */ + chomp(line); + + /* ignore blank lines */ + if (strlen(file_to_act_on) == 0) { + continue; + } + + /* if the search string is in this line, print it, + * unless we were told to be quiet */ + if (strstr(line, search) && !be_quiet) { + puts(line); + } + + /* clean up */ + free(line); + } + + +Processing Options with getopt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your applet needs to process command-line switches, please use getopt32() to +do so. Numerous examples can be seen in many of the existing applets, but +basically it boils down to two things: at the top of the .c file, have this +line in the midst of your #includes, if you need to parse long options: + + #include <getopt.h> + +Then have long options defined: + + static const struct option <applet>_long_options[] = { + { "list", 0, NULL, 't' }, + { "extract", 0, NULL, 'x' }, + { NULL, 0, NULL, 0 } + }; + +And a code block similar to the following near the top of your applet_main() +routine: + + char *str_b; + + opt_complementary = "cryptic_string"; + applet_long_options = <applet>_long_options; /* if you have them */ + opt = getopt32(argc, argv, "ab:c", &str_b); + if (opt & 1) { + handle_option_a(); + } + if (opt & 2) { + handle_option_b(str_b); + } + if (opt & 4) { + handle_option_c(); + } + +If your applet takes no options (such as 'init'), there should be a line +somewhere in the file reads: + + /* no options, no getopt */ + +That way, when people go grepping to see which applets need to be converted to +use getopt, they won't get false positives. + +For more info and examples, examine getopt32.c, tar.c, wget.c etc. diff --git a/docs/tar_pax.txt b/docs/tar_pax.txt new file mode 100644 index 0000000..e56c27b --- /dev/null +++ b/docs/tar_pax.txt @@ -0,0 +1,239 @@ +'pax headers' is POSIX 2003 (iirc) addition designed to fix +tar format limitations - older tar format has fixed fields +for everything (filename, uid, filesize etc) which can overflow. + +pax Header Block + +The pax header block shall be identical to the ustar header block +described in ustar Interchange Format, except that two additional +typeflag values are defined: + +x + Represents extended header records for the following file in +the archive (which shall have its own ustar header block). + +g + Represents global extended header records for the following +files in the archive. Each value shall affect all subsequent files +that do not override that value in their own extended header +record and until another global extended header record is reached +that provides another value for the same field. The typeflag g +global headers should not be used with interchange media that +could suffer partial data loss in transporting the archive. + +For both of these types, the size field shall be the size of the +extended header records in octets. The other fields in the header +block are not meaningful to this version of the pax utility. +However, if this archive is read by a pax utility conforming to +the ISO POSIX-2:1993 standard, the header block fields are used to +create a regular file that contains the extended header records as +data. Therefore, header block field values should be selected to +provide reasonable file access to this regular file. + +A further difference from the ustar header block is that data +blocks for files of typeflag 1 (the digit one) (hard link) may be +included, which means that the size field may be greater than +zero. + +pax Extended Header + +An extended header shall consist of one or more records, each +constructed as follows: + +"%d %s=%s\n", <length>, <keyword>, <value> + +The <length> field shall be the decimal length of the extended +header record in octets, including length string itself and the +trailing <newline>. + +[skip] + +atime + The file access time for the following file(s), equivalent to +the value of the st_atime member of the stat structure for a file, +as described by the stat() function. The access time shall be +restored if the process has the appropriate privilege required to +do so. The format of the <value> shall be as described in pax +Extended Header File Times. + +charset + The name of the character set used to encode the data in the +following file(s). + + The encoding is included in an extended header for information +only; when pax is used as described in IEEE Std 1003.1-2001, it +shall not translate the file data into any other encoding. The +BINARY entry indicates unencoded binary data. + + When used in write or copy mode, it is implementation-defined +whether pax includes a charset extended header record for a file. + +comment + A series of characters used as a comment. All characters in +the <value> field shall be ignored by pax. + +gid + The group ID of the group that owns the file, expressed as a +decimal number using digits from the ISO/IEC 646:1991 standard. +This record shall override the gid field in the following header +block(s). When used in write or copy mode, pax shall include a gid +extended header record for each file whose group ID is greater +than 2097151 (octal 7777777). + +gname + The group of the file(s), formatted as a group name in the +group database. This record shall override the gid and gname +fields in the following header block(s), and any gid extended +header record. When used in read, copy, or list mode, pax shall +translate the name from the UTF-8 encoding in the header record to +the character set appropriate for the group database on the +receiving system. If any of the UTF-8 characters cannot be +translated, and if the -o invalid= UTF-8 option is not specified, +the results are implementation-defined. When used in write or copy +mode, pax shall include a gname extended header record for each +file whose group name cannot be represented entirely with the +letters and digits of the portable character set. + +linkpath + The pathname of a link being created to another file, of any +type, previously archived. This record shall override the linkname +field in the following ustar header block(s). The following ustar +header block shall determine the type of link created. If typeflag +of the following header block is 1, it shall be a hard link. If +typeflag is 2, it shall be a symbolic link and the linkpath value +shall be the contents of the symbolic link. The pax utility shall +translate the name of the link (contents of the symbolic link) +from the UTF-8 encoding to the character set appropriate for the +local file system. When used in write or copy mode, pax shall +include a linkpath extended header record for each link whose +pathname cannot be represented entirely with the members of the +portable character set other than NUL. + +mtime + The file modification time of the following file(s), +equivalent to the value of the st_mtime member of the stat +structure for a file, as described in the stat() function. This +record shall override the mtime field in the following header +block(s). The modification time shall be restored if the process +has the appropriate privilege required to do so. The format of the +<value> shall be as described in pax Extended Header File Times. + +path + The pathname of the following file(s). This record shall +override the name and prefix fields in the following header +block(s). The pax utility shall translate the pathname of the file +from the UTF-8 encoding to the character set appropriate for the +local file system. + + When used in write or copy mode, pax shall include a path +extended header record for each file whose pathname cannot be +represented entirely with the members of the portable character +set other than NUL. + +realtime.any + The keywords prefixed by "realtime." are reserved for future +standardization. + +security.any + The keywords prefixed by "security." are reserved for future +standardization. + +size + The size of the file in octets, expressed as a decimal number +using digits from the ISO/IEC 646:1991 standard. This record shall +override the size field in the following header block(s). When +used in write or copy mode, pax shall include a size extended +header record for each file with a size value greater than +8589934591 (octal 77777777777). + +uid + The user ID of the file owner, expressed as a decimal number +using digits from the ISO/IEC 646:1991 standard. This record shall +override the uid field in the following header block(s). When used +in write or copy mode, pax shall include a uid extended header +record for each file whose owner ID is greater than 2097151 (octal +7777777). + +uname + The owner of the following file(s), formatted as a user name +in the user database. This record shall override the uid and uname +fields in the following header block(s), and any uid extended +header record. When used in read, copy, or list mode, pax shall +translate the name from the UTF-8 encoding in the header record to +the character set appropriate for the user database on the +receiving system. If any of the UTF-8 characters cannot be +translated, and if the -o invalid= UTF-8 option is not specified, +the results are implementation-defined. When used in write or copy +mode, pax shall include a uname extended header record for each +file whose user name cannot be represented entirely with the +letters and digits of the portable character set. + +If the <value> field is zero length, it shall delete any header +block field, previously entered extended header value, or global +extended header value of the same name. + +If a keyword in an extended header record (or in a -o +option-argument) overrides or deletes a corresponding field in the +ustar header block, pax shall ignore the contents of that header +block field. + +Unlike the ustar header block fields, NULs shall not delimit +<value>s; all characters within the <value> field shall be +considered data for the field. None of the length limitations of +the ustar header block fields in ustar Header Block shall apply to +the extended header records. + +pax Extended Header File Times + +Time records shall be formatted as a decimal representation of the +time in seconds since the Epoch. If a period ( '.' ) decimal point +character is present, the digits to the right of the point shall +represent the units of a subsecond timing granularity. In read or +copy mode, the pax utility shall truncate the time of a file to +the greatest value that is not greater than the input header +file time. In write or copy mode, the pax utility shall output a +time exactly if it can be represented exactly as a decimal number, +and otherwise shall generate only enough digits so that the same +time shall be recovered if the file is extracted on a system whose +underlying implementation supports the same time granularity. + +Example from Linux kernel archive tarball: + +00000000 70 61 78 5f 67 6c 6f 62 61 6c 5f 68 65 61 64 65 |pax_global_heade| +00000010 72 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |r...............| +00000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000060 00 00 00 00 30 30 30 30 36 36 36 00 30 30 30 30 |....0000666.0000| +00000070 30 30 30 00 30 30 30 30 30 30 30 00 30 30 30 30 |000.0000000.0000| +00000080 30 30 30 30 30 36 34 00 30 30 30 30 30 30 30 30 |0000064.00000000| +00000090 30 30 30 00 30 30 31 34 30 35 33 00 67 00 00 00 |000.0014053.g...| +000000a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000000b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000000c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000000d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000000e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000000f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000100 00 75 73 74 61 72 00 30 30 67 69 74 00 00 00 00 |.ustar.00git....| +00000110 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000120 00 00 00 00 00 00 00 00 00 67 69 74 00 00 00 00 |.........git....| +00000130 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000140 00 00 00 00 00 00 00 00 00 30 30 30 30 30 30 30 |.........0000000| +00000150 00 30 30 30 30 30 30 30 00 00 00 00 00 00 00 00 |.0000000........| +00000160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000180 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000190 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000001a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000001b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000001c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000001d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000001e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +00000200 35 32 20 63 6f 6d 6d 65 6e 74 3d 62 31 30 35 30 |52 comment=b1050| +00000210 32 62 32 32 61 31 32 30 39 64 36 62 34 37 36 33 |2b22a1209d6b4763| +00000220 39 64 38 38 62 38 31 32 62 32 31 66 62 35 39 34 |9d88b812b21fb594| +00000230 39 65 34 0a 00 00 00 00 00 00 00 00 00 00 00 00 |9e4.............| +00000240 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| +... |
